NE.Standard

Dialogs and notifications

A dialog is declared by the view and rendered closed by the shell, and opened and closed by key — from a command that fills it first, or from a press alone, with no round trip. Notifications are a client effect with nowhere of their own on the tree — they stack up in a corner the view chooses. This page is also where a failed command's report and the error page are configured.

Declaring a dialog

Override CreateDialogs() on the view and return a list of UIDialog:

protected override IReadOnlyList<UIDialog> CreateDialogs()
    => [
        new UIDialog
        {
            Key = ReleasesController.ConfirmKey,
            TitleId = "confirm-delete-title",
            CloseOnBackdrop = false,
            CloseOnEscape = false,
            Content = new StackPanelComponent()
                .SetSpacing(12)
                .AddChild(new TextComponent("confirm-delete-title")
                    .SetTitle("Delete this release?")
                    .SetTitleType(UITextAppearance.Title)
                    .BindDescription(nameof(ReleasesController.Question))
                )
                .AddChild(new StackPanelComponent()
                    .SetOrientation(UIOrientation.Horizontal)
                    .SetSpacing(8)
                    .SetHorizontalAlignment(UIAlignment.End)
                    .AddChild(UIDialogs.CloseButton(ReleasesController.ConfirmKey))
                    .AddChild(new ButtonComponent()
                        .SetTitle("Delete")
                        .SetVariant(UIButtonVariant.Danger)
                        .OnClick(nameof(ReleasesController.DeleteRelease))
                    )
                )
        }.OnClose(nameof(ReleasesController.KeepRelease))
    ];

The content is an ordinary component tree, bound against the view's controller like the rest of the page — here a line the controller writes before it opens the dialog, the standard Cancel, which shuts the dialog on the page and raises its OnClose, and a Delete that runs a command. TitleId names the dialog by the title it shows. UIDialogs.Confirm is the same dialog in one call.

UIDialog:

Member Meaning
Key stable string a command or interaction opens/closes it by
Content the root component of the dialog's body
Surface (UISurfaceStyle) what the panel is made of — Background, Surface (default), Tinted
Placement (UIDialogPlacement) Center (default), or a full-length sheet against Left, Right, Top, Bottom — a shortcut over the members below
Width, MinWidth, MaxWidth, Height, MinHeight, MaxHeight (UIResponsive<UILayoutLength>) the panel's size on the overlay, per tier; unset, a centred panel is sized to its content under a 560 px cap, and on a phone it is the screen less a thin margin
HorizontalAlignment, VerticalAlignment (UIAlignment) where the panel stands on the overlay — Start, Center, End, Stretch; unset, the placement decides
Margin (UIResponsive<UIThickness>) the room kept between the panel and the overlay's edges, per tier
Modal whether it blocks interaction with the view underneath (default true)
CloseOnBackdrop whether clicking the backdrop closes it (default true)
CloseOnEscape whether Escape closes it (default true); a non-modal dialog takes only an Escape pressed inside it
TitleId the id of the component in Content whose words name the dialog for a screen reader (aria-labelledby), so a bound title names it as it changes; it must stand inside the content and in no template, or the view does not compile. The UIDialogs presets set it (UIDialogs.TitleId(key))
AccessibleName the name of a dialog that shows no title of its own, a phrase or an author's text, translated for the page's language; TitleId wins over it
OnClose(command, arguments) a method, not an init member: the command run when the viewer dismisses the dialog by Escape, the backdrop or an × of its own (CloseDialogEffect with RaisesClose); a close the server asks for raises nothing; OnCloseLiteral takes literal values

UIDialog is a record, so a dialog a preset built takes what it does not set itself: UIDialogs.Create(key, title, content) with { Placement = UIDialogPlacement.Right }.

The panel is placed on the overlay the way a component is placed in its host, with the same words: a 640 px editor is Width = UILayoutLength.Absolute(640), a panel pinned to the top-right corner is HorizontalAlignment = End, VerticalAlignment = Start, and a value per tier is UIResponsive<UILayoutLength>.Create(...). A sheet is the same thing spelled short: Placement = Left is a panel at the start edge, stretched top to bottom, 420 px wide unless a Width says otherwise. UILayoutLength.Fill() is the overlay's room less the panel's margins — the authored Margin, else the thin default margin a centred panel keeps (none on a sheet) — so a filled panel keeps its margins rather than running past the overlay's edge.

A destructive confirmation turns both CloseOnBackdrop and CloseOnEscape off, so only its own buttons answer it. A non-modal sheet (Modal = false) at an edge, drawn on Surface = Background, is the shape a filter drawer or a side panel takes — the page keeps working beside it, its Escape included. A dialog opened from another stands on top of it, whatever order CreateDialogs lists them in.

Opening and closing

From a controller, Context.Dialogs (IUIDialogService):

_ = await Context.Dialogs.ShowAsync(Context.Handle, ProgressKey, cancellationToken).ConfigureAwait(false);
// ... work ...
_ = await Context.Dialogs.HideAsync(Context.Handle, ProgressKey, cancellationToken).ConfigureAwait(false);

ShowAsync/HideAsync push straight to the page, as Context.SendEffectsAsync sends an effect, so the dialog stands open for exactly as long as the command takes — the pattern for a wait dialog nothing on its own body dismisses.

A command can instead return the effect, which is the more common shape when opening or closing is the whole of what the command does, or the last thing. The controller behind the confirmation above:

internal sealed partial class ReleasesController : UIControllerBase
{
    public const string ConfirmKey = "confirm-delete";

    private readonly List<int> _releases = [479, 480, 481];

    [RecursiveMember]
    public partial string Question { get; set; } = string.Empty;

    [UICommand]
    public UICommandResult AskBeforeDelete()
    {
        if (_releases.Count == 0)
            return UICommandResult.Ok([new ShowNotificationEffect("Nothing left to delete.", UIColorStyle.Info)]);

        Question = $"Release #{_releases[^1]} goes for good.";

        return UICommandResult.Ok([new OpenDialogEffect(ConfirmKey)]);
    }

    [UICommand]
    public UICommandResult DeleteRelease()
    {
        _releases.RemoveAt(_releases.Count - 1);

        return UICommandResult.Ok([new CloseDialogEffect(ConfirmKey), new ShowNotificationEffect("The release is gone.", UIColorStyle.Success)]);
    }

    /// <summary>The dialog's close: its Cancel has shut it on the page already.</summary>
    [UICommand]
    public static UICommandResult KeepRelease()
        => UICommandResult.Ok([new ShowNotificationEffect("The release stays.", UIColorStyle.Info)]);
}

Changes go first, then effects, so the dialog opens on the question the command has just written.

OpenDialogEffect(dialogKey) and CloseDialogEffect(dialogKey) both take just the key. A dialog that shows what already stands — a sheet of filters, a picker — opens from the press itself, with no round trip and no command:

UIButtons.Icon(UIGlyphs.Search, "Search").InteractOn(EventNames.Click, new OpenDialogEffect(SearchKey))

A close from an interaction is the viewer's own, an × in the dialog: new CloseDialogEffect(key) { RaisesClose = true } closes it on the page and raises its OnClose as Escape does (the UIDialogs headers wire it). The dialog's own Cancel, Close or Done is UIDialogs.CloseButton(key, action), which also puts back the held edits of the form the key names (DiscardFormEffect), so a form opened again shows what the server holds. A close the controller decides — after a save — goes from a command. A key the view does not declare fails the view's compile when an interaction names it; returned from a command, the effect is dropped and logged as an error rather than sent to find nothing.

Notifications

ShowNotificationEffect(string message, UIColorStyle tone = UIColorStyle.Info) raises a toast, and ShowNotificationEffect(UIPhrase message, UIColorStyle tone = UIColorStyle.Info) raises one whose words carry arguments:

return UICommandResult.Ok([new ShowNotificationEffect("app.build.published", UIColorStyle.Success)]);
return UICommandResult.Ok([new ShowNotificationEffect(UIPhrase.Of("app.build.published-number", ("number", 481)), UIColorStyle.Success)]);

A notification's words are translated on the page, as a label's are: a string is read as a plain value on a translatable property is — under KeyPrefixes only a prefixed one is a key, and any other text shows as written — and a UIPhrase is always looked up and filled. An open toast follows a language switch. Message is the UIPhrase either way (UIPhrase.IsText for an author's text), so there is no need to translate in the controller first (localization).

Tone is a UIColorStyle, the scale a badge's colour takes, and six of its members give the toast an accent in their colour: Info, Success, Warning, Danger, Primary and Accent; any other member leaves it with the plain border. A Warning or Danger toast is announced to a screen reader at once (role="alert"), every other one politely. Where a view's notifications stack is UIViewOptions.NotificationPlacement (UINotificationPlacement: Bottom — the default — or Top), set once for the view rather than per notification. Every toast of a view is one width, UIViewOptions.NotificationWidth — 400 pixels by default — and a narrow screen narrows it further.

A toast carries a close button and dismisses itself after five seconds — eight when it carries an action — or after its own Duration. The pointer resting on it, or the keyboard on its buttons, holds it; when they leave, it gets its full time again. One raised while the page is off screen waits until the page is shown, and its time starts there.

A toast with the way back

Action gives a toast one button that runs a command of the controller's — the commonest use is "Deleted — Undo", in place of asking first:

[UICommand]
public UICommandResult Delete(string id)
{
    _deleted[id] = Messages.Take(id);   // a soft delete: kept for the way back

    return UICommandResult.Ok([new ShowNotificationEffect("app.message.deleted")
    {
        Action = new UINotificationAction("app.undo", nameof(Restore), id)
    }]);
}

[UICommand]
public void Restore(string id)
{
    if (_deleted.Remove(id, out Message? message))
        Messages.Put(message);
}

The label is translated as the message is. The argument goes to the command's one parameter; the command needs no button of its own. It is checked as the effect is sent: a command the controller does not declare, or one that takes more than the one argument, is logged, and the toast shows without its button. The page is never told the command or the argument — only an id the runtime issued for this one press — and the press runs the command as a button would, through the command filters, authorization and MaxConcurrent, once. A pressed toast closes.

Duration is the window the button can be pressed in, held open while the reader hovers or focuses the toast. Without one, a toast with an action stands eight seconds rather than five: the reader reads the message before reaching the button. Making the delete final once that window has passed — purging what the soft delete kept — is the controller's; nothing tells it the toast closed.

Off the page: the system's notification

A toast raised in a tab nobody looks at waits there until the tab is shown, so a reader looking elsewhere does not see it. ShowSystemNotificationEffect(title, body) shows the operating system's notification while the page is off screen — another tab chosen, the window minimised — and the page's toast while it is on screen:

[UICommand(ConcurrencyMode = UICommandConcurrencyMode.Background)]
public async Task<UICommandResult> WatchDeployAsync(int release, CancellationToken cancellationToken)
{
    await _deploys.WaitAsync(release, cancellationToken);

    return UICommandResult.Ok([new ShowSystemNotificationEffect(UIPhrase.Of("app.release.live", ("release", release)), "app.release.live.body")
    {
        Tag = $"release:{release}",
        Action = new UINotificationAction("app.open", nameof(OpenRelease), release)
    }]);
}

The page decides as it shows it, from what it is then. When is WhenHidden by default, or Always; Fallback is what shows where the system's does not — off screen with no permission, on screen under WhenHidden, a phone's browser without the framework's worker: the toast by default, its title over its body, held until the page is on screen; or None. A click brings the page forward and runs Action's command, offered for one press as a toast's is; the toast's button runs the same. Tag is the key a later notification replaces this one by — one per chat; without one, each send gets its own. Address, a path of this site, is where a click brings the page — through its own leave, so unsaved work is asked about first — or opens it once the page is gone; a page already there runs Action instead. The fallback toast leads there by an "Open" button (AddressTitle words it), and on a page already there shows Action's button. Icon is the page's icon unless set. Sent to every page of a runtime (SendEffectsToAllAsync, a broadcast), a page off screen is left out while another is on screen, and with none on screen only one of them is sent it, so the reader is told once, where they look; with Always, one page is sent it — the first on screen, else one off screen — so it sounds once.

A reader has many runtimes — one per tab and route by default — so a notification about something that happened to the user, not to one page, goes through IUINotifier, which applies the same rule across all of a browser's pages:

public sealed class ChatNotices(IUINotifier notifier)
{
    public ValueTask<int> MessageAsync(string userId, Message message, CancellationToken cancellationToken)
        => notifier.NotifyUserAsync(userId, new ShowSystemNotificationEffect(message.Author, message.Text)
        {
            Tag = $"chat:{message.ChatId}",
            Address = $"/chat?id={message.ChatId}"
        }, cancellationToken);
}

Each session signed in as the user — each browser — decides on its own: while a page of it is on screen, whatever its route, the pages on screen are sent it and show the fallback; while none is, one page off screen shows the system's. With Always, one page of the browser shows it. It offers no Action — a command belongs to one page's runtime — and refuses one; Address is the way back, and a click without one only brings forward the page that showed it. A page that already shows what it is about — the conversation open on screen, which the controller knows from OnVisibilityChangedAsync — is the application's to know: it does not send. It answers how many pages it reached; none means the user has no page open.

The browser asks the reader first, and only inside their own press: RequestNotificationPermissionEffect raised by an interaction (InteractOn("click", …)), never from a command's answer, after which most browsers refuse without a word. What it answered is Context.NotificationPermission — one browser's, not the reader's — and a change reaches OnNotificationPermissionChangedAsync, queued as posted work is (controllers). Denied is undone only in the browser's settings: say so rather than ask again. A page not on https (localhost aside) shows none and reports Unsupported: a phone opening the PC's address on the network is one.

A desktop browser shows a page's notification itself. A phone's shows only a service worker's, so the application turns the framework's on in its web services, and the page registers it at /_ne/, where it controls no page of the application:

services.AddSystemNotifications();                               // the framework's worker
services.AddSystemNotifications(WebServiceWorkerMode.Imported);  // the application's own worker runs importScripts("/_ne/sw.js")

An iPhone shows a page's notifications only for an application added to the Home Screen, which takes a manifest: WebEndpointOptions.Manifest (WebManifestOptions: Name, ShortName, Icons, Display, colours) is served at /_ne/manifest.webmanifest and linked from every page. A notification to a reader with no page open at all — Web Push — is not in the framework yet.

When a command fails

The client never reads a raw success/failure flag — both the invoke return and the push channel only apply changes and effects. So a failed command whose result carries no effects of its own — one that returned UICommandResult.Fail(error), threw, or was refused by an authorization check — gets one attached automatically: a Danger ShowNotificationEffect whose text comes from UIErrorHandlingOptions, configured through ConfigureErrorHandling:

application.ConfigureErrorHandling(errors =>
{
    errors.NotifyOnCommandFailure = true;
    errors.IncludeExceptionDetail = false;
    errors.CommandRefusedMessage = "You are not allowed to do that.";
    errors.CommandFailedMessage = "Something went wrong. Please try again.";
    errors.ErrorPageMessage = "This page could not be shown.";
    errors.ErrorRoute = "/error";
    errors.NotFoundRoute = "/not-found";
});
Option Meaning
NotifyOnCommandFailure whether a failed command with no effects of its own is reported at all (default true)
IncludeExceptionDetail whether the real exception message reaches the browser, in the toast and on the error page — off by default, since an exception routinely carries a connection string, a table name or a file path
CommandRefusedMessage shown when a command throws an UnauthorizedAccessException — an authorization check's refusal
CommandFailedMessage shown when a command throws anything else, unless IncludeExceptionDetail is on
ErrorPageMessage what the default error page shows, unless IncludeExceptionDetail is on and the failure handed over its text
ErrorRoute where a page goes when resolving its view throws, or rendering it does; a failing command is reported in place, never routed here
NotFoundRoute where a request for an unregistered route goes, with the requested route in its route parameter; the page standing in for that route is answered with a 404

The toast's text has three levels:

  1. What the command wrote. UICommandResult.Fail(error) is shown with its own error as it stands; a failure with no text shows nothing.
  2. A refusal. A command that throws an UnauthorizedAccessException shows CommandRefusedMessage.
  3. Anything else thrown. CommandFailedMessage, or the exception's own message when IncludeExceptionDetail is on.

Returning your own effects from a failing command is how it takes over the reporting — the automatic notification only fires when a command's result carries none. The text at every level is translated on the page by the plain rule a notification's string is — a command's own error included, so under KeyPrefixes only a prefixed one is a key — and follows a language switch while the toast is open; ErrorPageMessage goes through the translator too. An application overrides the framework's wording by localization rather than by re-implementing the mechanism.

A page's own value write or window of rows that fails on the server is reported the same way: the controller's handler's effects, else the failure notification, go to the page that asked. A call to the server that fails in the browser with nothing else saying so — a press, a value, a window of rows or a page turn, a toast's action — shows one toast, Something went wrong. Please try again. (ui.command.failed), once for a burst of them; a dropped connection and an expired press say their own.

When a page fails

A page whose view cannot be resolved goes to ErrorRoute, and so does a page that throws while it is being rendered — a getter that fails as this reader's values are drawn — rather than answering with a bare 500. The error page receives the exception's text when IncludeExceptionDetail is on, as a UIErrorDetail in its message navigation parameter, handed over in-process; an error page of the application's own reads that type, never a string, since a message in the address is anybody's words. Off, there is no parameter and the default page shows ErrorPageMessage. Both routes are used only when they are registered, and the error route never redirects to itself, so a failing error page cannot loop. A refusal while resolving is not an error: it goes to the sign-in or forbidden route instead (see security).