NE.Standard

Views

A view is a UIViewBase subclass that builds a component tree — the framework compiles it once and renders it to the platform. Every view also implements IUIViewDefinition, whose static ViewKey is the stable name route registration and view lookup use.

internal sealed class CounterView : UIViewBase, IUIViewDefinition
{
    public static string ViewKey => "counter";

    protected override IVisualComponent CreateContent()
        => new ContainerComponent()
            .AddChild(new TextComponent().BindTitle(nameof(CounterController.Count)));
}

Regions

A view builds up to five regions by overriding the corresponding Create* method — all protected virtual except CreateContent, which is abstract and required:

  • CreateHeader()
  • CreateFooter()
  • CreateLeftSide()
  • CreateRightSide()
  • CreateContent() — the only region every view must supply.

Each returns an IVisualComponent? (null for a region the view does not use) except CreateContent, which returns one. Regions are built lazily, once, and cached.

Title and options

Title (defaults to the type name) and Options (UIViewOptions.Default unless overridden) are virtual properties a view overrides directly:

public override string Title => "Dashboard";

public override UIViewOptions Options => new()
{
    StickyHeader = true,
    ScrollContentOnly = true,
    NotificationPlacement = UINotificationPlacement.Top
};

UIViewOptions says what the view wants from its own shell, not from any component in it:

Property Effect
StickyHeader The header region stays at the top of the viewport while the content scrolls under it.
ScrollContentOnly The page keeps the viewport's height; header and sides stand still and only the content region scrolls.
ShellLayout Which regions run the page's full length — FullWidthBands (default: the header and footer across, the sides between them) or FullHeightSides (the sides top to bottom, the header and footer between them).
SideDrawers Below which width the sides leave the page's columns and slide over the content, each opened by a button the header carries (the content, where the page has no header): BelowMd (the default, a phone's), BelowXl (a tablet's either way up), BelowXxl, Always or Never. A left side that is a navigation rail alone is a bar along the page's bottom there instead, with no button (items).
LeftDrawerModal, RightDrawerModal On by default: the side's open drawer dims the page and closes on a press beside it. false leaves the page beside it as it is and working — a setting changed in the drawer, a button pressed beside it — the drawer going by its switch, its button or an Escape from inside it.
RailBottomBar On by default: where the sides are drawers, a left side that is a rail alone is the bottom bar. false keeps it a drawer with its header button, the rail drawn there as a list (icon beside title, groups opening inline) — for a page whose bottom is its own.
NotificationPlacement Which corner this view's toasts stack in — Bottom (default) or Top.
NotificationWidth The width, in pixels, every toast of this view takes — 400 by default; a narrow screen narrows it.
LeftSideLandmark, RightSideLandmark What a side is to a screen reader's list of landmarks — Auto (default: the page's navigation where the side holds a menu and nothing else, else complementary), Navigation or Complementary, for a side that means something else.

The regions are landmarks whatever the options say: the header the page's banner, the content its main region, the footer its content information. They are a screen reader's way past a side: the page draws no "Skip to content" link.

An open drawer is put away by a press beside it, Escape, the screen crossing a breakpoint that ends its side as a drawer, or a link or menu entry taken inside it — a command's as a link's, but not a group's own entry (it only opens the group), a check, or an entry of a popup menu (a context menu, a split button's list), which acts on the drawer's own content.

A page may carry a side's drawer button itself — in a conversation's title row, say, on a phone whose header is collapsed — with ButtonComponent.SetOpensDrawer(UISide.Left) (or Right). The shell then draws no button of its own for that side, so a collapsed header leaves no band behind for it. The page's button opens and puts the drawer away as the shell's does, is marked expanded while it is open, and takes the keyboard back when it goes; it shows only where its side is a drawer — below the width the view names, unpinned, and never for a left side that is the bottom bar — whatever its own Visibility says.

From the extra-large breakpoint up a reader may pin a drawer: it then stands in its column, as on a wide screen, until it is unpinned. A sidebar menu offers the pin at the end of its top row, after its switch and its search, with MenuComponent.SetDrawerPin(true); a side without one — a panel of settings — takes the page's own button, ButtonComponent.SetPinsDrawer(UISide.Left), placed in its own heading. Either shows only where pinning means something and is pressed while the side is pinned: its glyph filled, the hover's light wash kept under it. The page's own button is a toggle whose Pressed is the pin, so an icon of its own for pinned is an interaction on it — .Interact(ButtonComponent.PressedProperty, ITextBaseComponent.IconProperty, UIComparisonOperator.Equal, true, pinned, unpinned) — which hears a pin the page comes back with as well as one pressed. The pin is kept in the browser under the first authored id in the side, so give the side's root an id: without one the key is whatever control comes first inside it, and moves with the layout; a side with no id at all forgets the pin at the next page.

public override UIViewOptions Options { get; } = new() { SideDrawers = UISideDrawers.Always, LeftDrawerModal = false };

protected override IVisualComponent? CreateLeftSide()
    => new StackPanelComponent("generation")
        .SetSpacing(8)
        .AddChild(UILayout.Row(8,
            UIText.Title("Generation"),
            new ButtonComponent().SetIcon(UIGlyphs.PinOutlined).SetTooltip("Pin").SetPinsDrawer(UISide.Left)
        ))
        .AddChild(SettingsFields());

Dialogs

CreateDialogs() declares the view's dialogs, rendered closed by the shell and opened by key from a command. Each UIDialog names a key and its content:

protected override IReadOnlyList<UIDialog> CreateDialogs()
    => [
        new UIDialog
        {
            Key = "confirm-delete",
            Content = new ContainerComponent()
                .AddChild(new TextComponent().SetTitle("Delete this build?"))
        }
    ];

Its size, placement and dismissals, and how a command opens and closes it, are in dialogs and notifications.

Key chords

A chord is written as Ctrl+Shift+P, a letter, a digit, a sign (/) or a key's name (Delete, F2), and matched by the key's place on the keyboard, so it is the same key under any layout; an authored Ctrl is ⌘ on a Mac. Three things carry one, and the page reads them in one registry:

  • A button. SetShortcut("Ctrl+S") on a button and its kin (an action, a split button, a menu entry, a tab caption) presses it from anywhere on the page. Its tooltip says the chord after its words — "Save (Ctrl+S)" — in the reader's platform's form (⇧⌘S on a Mac), and a menu entry shows it at its end the same way.
  • The view. CreateShortcuts() returns the view's own, each running a command or an effect, compiled with the view as its events are; an effect runs on the page with no round trip:
protected override IReadOnlyList<UIShortcut> CreateShortcuts()
    => [
        new UIShortcut("/", new FocusEffect(SearchId)),
        new UIShortcut("Ctrl+Enter", nameof(InboxController.Send))
    ];
  • A context menu's entry (MenuItem.Shortcut) acts on the row the menu belongs to: the row under the list's keyboard cursor, else its chosen row, as if the menu had been opened there and the entry pressed. With no such row — or the keyboard elsewhere on the page — it does nothing.

The rules are one for all three. A chord with Ctrl, Alt or ⌘ fires from inside a field too, unless the field takes it itself (a code field's Ctrl+S), and what was typed is sent first; a key without one, typed into a field, is the field's (/ in the search is a slash), and so is a caret's chord (Ctrl+Left, Ctrl+Backspace…) and the field's own select-all, clipboard, undo and redo (Ctrl+A, C, V, X, Z, Y, Ctrl+Insert). An open modal dialog keeps every chord outside it out of reach. A chord claimed twice fires neither, and the compiler refuses it where it can see both claims and a button or the view's own is among them — two menus' entries of one chord pass, as two graphs' Save does, each answered by its canvas in its own focus; it refuses a chord that names no key, one in a template every row repeats (put it on the row's context menu), and one the browser keeps for itself — a new, closed or restored tab or window, the next or previous tab, quitting (Ctrl+N, Ctrl+T, Ctrl+W, Ctrl+Tab, Ctrl+PageDown, Ctrl+Q, Alt+F4…), which it never hands to a page.

The placement grid

Every visual component has a Placement — its cell(s) in a 24-column grid (UIGridPlacement.GridColumns). SetPlacement is the fluent entry point:

new TextComponent()
    .SetPlacement(1, 1, 24, 1)
public TComponent SetPlacement(int column, int row, int columnSpan = 1, int rowSpan = 1,
    UIGridPlacement? sm = null, UIGridPlacement? md = null, UIGridPlacement? xl = null, UIGridPlacement? xxl = null)

column/row are the starting cell, columnSpan/rowSpan how many cells the component occupies. The four optional arguments after them override the placement per breakpoint — sm, md, xl, xxl, built with UIGridPlacement.At(column, row, columnSpan, rowSpan).

A child of a container with no placement of its own spans all twenty-four columns — one to a row. The two wrapping layouts read the span differently: in a WrapPanel, and in an ItemsView whose layout is Wrap, a child with no placement takes its content's width and the line wraps where the room ends, and a placement makes it that share of the width instead — a template root with .SetPlacement(1, 1, 6, 1) is four items to a line.

The children of a container touch: its grid has no air of its own. SetSpacing gives it some — the same pixels between its columns and between its rows, per breakpoint like any responsive property (SetSpacing(16), SetSpacing(8, xl: 24)), so a side part that moves under the main one on a narrow screen keeps its distance too. The space between columns is capped at a twenty-fourth of the room the container's absolute columns and column floors leave, so a narrow container closes its columns up rather than overflowing. An Auto column's content is not counted: a container with Auto columns and a large spacing wants a responsive one with a small base (SetSpacing(4, md: 24)). The presets in UILayout put their own air between their cells.

Children placed in the same cell overlap, and stand as their order reads: the later over the earlier. A messenger's feed is one cell holding the ItemsView, then a pinned bar aligned to the cell's top and a composer aligned to its foot; the feed's Padding keeps its ends clear of both at rest, and scrolled, its rows pass under them.

This is Placement's own type, UIResponsive<UIGridPlacement>, and the same shape backs every responsive property on a component (Width, Margin, Padding, a border's BorderThickness and BorderRadius — an image's corners too, and so on): a required Base value plus optional per-breakpoint overrides (Sm, Md, Xl, Xxl). An unset breakpoint falls back to the next narrower one that is set, down to Base — mobile-first. UIResponsive<T>.Create(value, sm, md, xl, xxl) builds one explicitly, and a bare T converts to it implicitly (FromValue). A frame that runs edge to edge on a phone says so on the border: new SurfaceComponent().SetBorderThickness(UIThickness.Uniform(0), md: UIThickness.Uniform(1)).SetBorderRadius(UICornerRadius.Uniform(0), md: UICornerRadius.Uniform(12)).

A size is a UILayoutLength. UILayoutLength.Fill() takes the parent's room less the component's own margin on that axis, so a list filling a clipping panel with SetMargin(8) keeps its last row whole rather than losing its last eight pixels under the edge; and a child's width, authored or not, is capped at that same room, so a fixed width does not run off a phone — an authored MaxWidth still rules, and a scroll container's content keeps its size.

Panes the reader arranges

A GridSplitterComponent in a track of its own between two runs of a container's tracks lets the reader re-divide them, by a drag or from the keyboard. The browser keeps the division under the container's id; bind Position — the share before the bar, 0 to 1 — and the controller keeps it instead, so it follows the reader to another device, and a value the controller sets moves the bar. Set but not bound, Position is where the bar starts: a division the reader left stands over it, and a double-click puts the bar back there (resetting the active axis in localStorage, or clearing every axis the bar spans and writing null when Position is bound). A splitter may also switch axes across responsive breakpoints (SetOrientation(UIOrientation.Horizontal, md: UIOrientation.Vertical)) when paired with per-tier SetPlacement and per-tier SetColumn/SetRow definitions. A side let go under 48 px folds away; the bar along that edge shows its line under the pointer, to pull it back out by. A column with a floor (UIGridUnit.Absolute(260, min: 180)) goes under it as the bar is dragged, its content hidden there: let go under 48 px it folds, anywhere else under the floor it springs back to the floor.

A PaneContainerComponent lets the reader move whole panes. Each pane is added with a name at a place — its cells, as a placement — and a grip at the pane's top, shown as the pointer nears it, carries it onto another pane's place: the two trade places, sliding. Layout lists the names in the order of the places; bound, the controller keeps it, else the browser does under the container's id. A splitter among the places sizes the places, whichever pane stands in them:

new PaneContainerComponent("workspace")
    .SetColumn(16, UIGridUnit.Auto())
    .SetRow(1, UIGridUnit.Star())
    .AddRow(UIGridUnit.Auto())
    .AddRow(UIGridUnit.Star())
    .AddPane("chat", UIGridPlacement.At(1, 1, 15, 3), chat)
    .AddPane("tasks", UIGridPlacement.At(17, 1, 8, 1), tasks)
    .AddPane("tree", UIGridPlacement.At(17, 3, 8, 1), tree)
    .AddChild(new GridSplitterComponent()
        .SetPlacement(16, 1, 1, 3)
        .BindPosition(nameof(WorkspaceController.SideShare))
    )
    .AddChild(new GridSplitterComponent()
        .SetOrientation(UIOrientation.Horizontal)
        .SetPlacement(17, 2, 8, 1)
    )
    .BindLayout(nameof(WorkspaceController.Layout))

A layout kept from before a pane was renamed or added still places the panes it names, and the rest take the places left, in the order they were added. From the keyboard: Tab to a grip, Space, an arrow to choose the place, Space again; Escape puts the pane back where it stood.

Component ids

A component's Id is either the string passed to its constructor or a generated u<N> from a process-wide counter. HasAuthoredId says which:

new StackPanelComponent("sidebar")

An authored id is what the client's small per-viewer preferences (a collapsed menu, a split panel's tracks) key off in localStorage; a generated id means nothing between two runs, so a component with no authored id stores nothing. Give one to anything the reader would expect to remember its own state across a reload.

The fluent style

Every component method returns the component itself (TComponent, the generic self-type), so calls chain:

new ContainerComponent()
    .SetPadding(UIThickness.Uniform(8))
    .AddChild(new TextComponent()
        .SetTitle("Hi")
        .SetPlacement(1, 1, 24, 1)
    )
    .SetPlacement(1, 2, 24, 1)

The naming is consistent across every component:

  • Set* assigns an authored value — a plain CLR value the view controls once, at compile time.
  • Bind* (generated per bindable property) or the raw Bind(property, path, scope, mode) ties a property to a controller path instead — see binding.
  • Configure(Action<TComponent>) runs arbitrary code against the component inline, for the rare case a fluent method does not cover.
  • SetDefaults<TDescendant>(Action<TDescendant>) declares property defaults over a component's or a view's subtree — applied at compile time to every descendant assignable to TDescendant (including inside regions, templates, context menus and declared or component-owned dialogs) unless the descendant sets the property itself; the nearest ancestor's rule wins.
  • AddChild(IVisualComponent) / AddChildren(...) append children to a container component (ContainerComponentBase<T> and its descendants).

Written out this way, a real screen gets long. The presets package, NE.Standard.UI.Extensions, is how it stays short: UIPage, UILayout, UIForm, UIButtons, UIText and UIDetails build the common shapes — a header band, a section, a stack, a field with its hint, a button pair — in one call each, and ShownWhen, HiddenWhen and EnabledWhen tie a component to another one's value. They return the same components, so the fluent calls above still apply; see presets.

A clickable surface

OnClick on a SurfaceComponent or a CardComponent makes the whole of it a press target for the command it registers — OnClickWithItemKey(command) on a row's card passes the row's key — and so does an interaction on its click (OnClickShowImage); a file tile (FileTileComponent) the same. Clickable decides it where the author sets or binds it: SetClickable(false) or a bound false lets the click go by, and controls inside are unaffected either way. It takes the keyboard as a button does: a Tab stop, Enter raising its click at once and Space on release, without scrolling the page. To a screen reader it is a button while it holds no control of its own, and a group the reader walks into when it holds one — a link, a button, a field. Disabled or loading, it is no stop at all. A press on a control inside it is that control's, and a press on a clickable surface that is a row's template is the surface's, as a button's is: it does not also choose the row.

SetUrl(address) (or BindUrl) makes a surface, a card, a file tile, a ButtonComponent or an ActionComponent a link instead: its root is an anchor, so the address opens in a new tab, copies as a link and is followed in place with no round trip, behind the same leave guard as any link of the page. A link runs no command on its click and holds no control of its own — a button, a field, another link, or a host whose parts are presses (tabs, a pager, a switcher, an expander, a tree, rows chosen by selection, a strip of buttons, steps, a data grid, a chart with a legend, a zoom or a point's click — a sparkline has none; a package's own component says so by implementing IPressablePartsComponent, answering HasPressableParts where it depends on how it is set up): the view refuses either when it compiles, since the press would race the navigation and an anchor takes no control inside. A link written in a description inside it — [docs](/docs), or an address SetDescriptionAutolinks reads — shows as its words, its styles kept: the press is the card's. A button keeps its look (SetVariant, SetSize) on the anchor; disabled or loading, the link opens from nowhere. A menu's entries and a trail's steps are anchors too, and the one exception to the click rule: their host's OnItemClick stands beside an entry's Url, since one template draws the entries with an address and those with a command. Whatever is pressable as a whole takes an AccessibleName for a name its words do not give it, and so does a host a screen reader names by its role — a tree, a list, a table, a tabs view (on its tab list), a menu, a command bar, steps, a progress, a spinner (SetAccessibleName); a spinner with neither a title nor a name says "Loading" (ui.spinner.loading).

Context menu

SetContextMenu(IVisualComponent contextMenu) sets what opens on a right-click, normally a MenuComponent; ShowContextMenu (bindable, default true) switches the mechanic off without removing the authored menu. On a touch screen a long press opens it — timed by the framework, since iOS Safari raises no contextmenu for one — and is never also a click; a long press in a field inside is the field's own. Below the small breakpoint (640 px) the menu opens as a sheet along the bottom of the screen rather than beside the press, as a split button's list, a strip's "…" and a select's list do.

A menu set on a list's row template is drawn into a row only when it is wanted — opened, pressed by an entry's chord, shown as the row's action bar — rather than into every row as the list is drawn, which kept a feed's rows at a third of their markup; drawn, it stays while its row does. Nothing changes for the application: its entries are the row's own (a bound Items per row, or the template's), a push to them reaches the menu whenever it is drawn, and an entry's chord answers on a row whose menu was never opened.

Action bar

SetActionBar(UIActionBarAlignment) gives a component with a context menu a small row of icons above it — a messenger's pin, edit and delete over the message the reader chose. The bar is a quick view of the menu, not a second list: the menu's entries marked InActionBar stand in it as their icons, each named by its entry's title (for a screen reader: no tooltip, which over the bar would be a popup on a popup), and "…" opens the menu itself where it holds more. A press on an icon is that entry's own press, so one command serves the menu and the bar, and an entry's own effect (OnItemClick(key, effect)) runs from either.

new StackPanelComponent()
    .SetContextMenu(new MenuComponent()
        .SetItems([
            new MenuItem { Id = "pin", Title = "Pin", Icon = UIGlyphs.Pin, InActionBar = true },
            new MenuItem { Id = "edit", Title = "Edit", Icon = UIGlyphs.Edit, InActionBar = true },
            new MenuItem { Id = "copy", Title = "Copy text", Icon = UIGlyphs.Copy }
        ])
        .OnItemClick(nameof(ChatController.MessageAction), UIAction.ArgCurrentItemKey("action"), UIAction.ArgParent("id", nameof(Message.Id)))
        .OnItemClick("copy", CopyToClipboardEffect.ValueOf(MessageTextId))
    )
    .SetActionBar(UIActionBarAlignment.End)
  • It shows over the component the reader chose — a press or a tap on it (which still does what the component does: a row's click opens its item and shows its bar) or the keyboard in it, in a list on the row its cursor lights — never on hover. It stays while that component is chosen and goes on a press elsewhere, Escape, or another chosen. A list with selection and one without behave alike: the bar follows the row last pressed or lit, not the selection.
  • It floats above the component, a small gap over its top edge, as a popup does: the list's scrolling box never clips it, it follows the row as the list scrolls, and hides while the row is scrolled wholly out of sight. A row chosen at the list's top edge is scrolled into view by what the bar lacks, as a messenger brings the message into view; only where the list cannot scroll that far (its first row) does the bar stand under the row. A row the list draws anew — replaced by a push, or a window scrolled past it and back — keeps it. End (the default, a message's side), Start or Center say where along the component it stands; start and end follow the page's direction. It takes no room in the layout, and its icons wrap rather than run past the window.
  • Tab from a list goes into the chosen row's bar; the arrows, Home and End walk the bar, Escape gives the keyboard back to the list, and Escape again takes the bar away. While "…" has its menu open the bar stays, and closing the menu from the keyboard gives the focus back to "…".
  • "…" opens the menu under it, as a menu button opens its list, and by default the whole menu. SetActionBar(alignment, repeatInMore: false) has it open only what the bar does not show — a caption or a rule left with nothing to stand by goes too — while a right-click and a long press still open the whole menu.
  • On a touch screen a tap shows the bar, and a long press opens the menu with the bar's icons in a row atop it instead: the bar standing goes as the menu opens, and nothing is chosen once it closes.
  • Only a plain entry stands in the bar — never a caption, a rule or a group's own entry — and one the menu hides or disables for what it was opened on is hidden or disabled in the bar too.
  • It is set at render time, not bound; a component with an action bar and no context menu is refused when the view compiles.
  • An entry's Shortcut presses it for the row under the list's cursor (see key chords); the bar's icon names it in its tooltip, "Pin (P)".

Visibility

Visibility is UIResponsive<UIVisibility>?, and UIVisibility has three values:

Value Effect
Visible Drawn, and taking part in layout, hit-testing, focus and assistive technology.
Hidden Not drawn, but still holding its place — the layout around it does not move.
Collapsed Gone from the layout as well: everything after it closes the gap.

Theme

Theme (UIThemeMode?) forces a component's subtree into Light or Dark regardless of the session's own theme; null (the default) inherits. This is a per-component override — the session-wide setting is a separate mechanic (SetThemeEffect, see interactions and effects).

Text selection

A page is pressed more than it is read, so the reader may select only reading words: a TextComponent's and a ParagraphComponent's, a field's validation message, a field's value (and CodeInput's Markdown display). Text standing in a row of a list or a table, a clickable surface or a key-value row is that row's caption and does not select; a control's words — a button, a tab, a menu entry, a tree's row, a table's header, a select, a breadcrumb, an expander's header — never do, nor a row that drags by itself, nor, on a touch screen, anything a long press opens a context menu on.

TextSelectable (bool?, bindable, on every component) overrides the place either way, for the component and everything inside it; the nearest component that says wins:

new TableComponent().SetTextSelectable(true)            // its cells' words may be copied
new ParagraphComponent().SetTextSelectable(true)        // a chat message inside a list's row
new TextComponent().SetTitle("Status").SetTextSelectable(false)   // a label, not content

A control and a drag surface are beyond it: a press there is the control's or the drag's.

Inline text markup

A description or a tooltip may carry a small inline markup, parsed by UIInlineMarkup (parity-tested against the client's own parser):

Syntax Produces
**bold** Bold
*italic* Italic
__underline__ Underline
~~strikethrough~~ Strikethrough
`code` Inline code
[label](url) A link — url must pass UIInlineMarkup.IsSafeUrl (relative, #, ?, ., or http/https/mailto/tel)
![glyph] An icon, named by glyph name only — never a URL
[caption]{text} A fold: a caption with collapsible text, which may itself contain markup

A description that sets SetDescriptionAutolinks(true) also links a bare http:// or https:// address, as GitHub's extended autolinks do: one after anything but a letter or digit (a space, a quote, «, (, a marker), with a domain of two or more dotted labels, running to a space (a no-break one too) or <, its trailing .,:;!?*_~, closing quotes ('"»”’) and an unbalanced ) or ] left out. The address is its own label and passes the same IsSafeUrl; inside `code` or a link's label it stays text, and UIInlineMarkup.ToPlainText keeps it as written. A tooltip never links one, and SetDescriptionPlain(true) wins over it. An address in a phrase's argument links too, escaped or not.

A link that leaves the application opens in a new tab with rel="noopener noreferrer": a web, mail or phone address, and one the browser reads as another host — //host, /\host, \\host, whatever control character or tab hides it (WebUrlSafety.IsExternalLink).

A marker is escaped with a backslash (\*) to appear literally; UIInlineMarkup.Escape(text) escapes every marker in a value before it is substituted into a localized string. UIInlineMarkup.ToPlainText(text) strips the markup for a place that takes plain text only, such as an aria-label.

Where to go next