NE.Standard

Items

An items host is any component that renders a keyed collection through a template: ItemsViewComponent, TableComponent and TreeComponent are the general-purpose ones, and MenuComponent, TabsViewComponent, BreadcrumbsComponent, StepsComponent, ButtonGroupComponent and the SelectComponent/MultiSelectComponent/RadioGroupComponent/SearchComponent inputs are all items hosts too — they add a menu, a tab strip, a breadcrumb trail, a wizard step strip, a segmented button strip, or options on top of the same collection machinery.

Static vs bound items

SetItems/AddItem/AddItems hold a plain, author-declared list — data that never changes per session and renders fully on the server, cached alongside the view itself:

new TableComponent()
    .SetItems(DemoDeploymentRow.CreateDeployments())
    .AddTextColumn("Service", nameof(DemoDeploymentRow.Service));

BindItems(path, scope) points the collection at a RecursiveCollection on the controller instead. It is generated for every items host from the Items property, so its scope defaults follow the same rule as any other binding — Root unless you pass Relative.

new ItemsViewComponent()
    .BindItems(nameof(SomeController.Rows))
    .SetTemplate(rowTemplate);

A closed list of options shown by several selects is a static list given to SetOptions (AddOptions, a menu's SetItems): the component keeps its own references and nothing takes the items over, so one static readonly list is shared freely by every select, radio group, menu and page. A list the controller holds is a recursive tree with one owner per node: putting one node in a second place is refused, and the refusal names both places — each path from its root, and the root's type.

Every item is keyed

An item collection — static or bound — must hold IBindableItems, each with a stable string Id; the compiler refuses anything else. Wrap a plain value with UIValueItem<T>, whose Id is derived from the value itself (so the same value cannot appear twice), or UIOptionValue<T>, which also fills Title so Select/MultiSelect/Search/RadioGroup render options with no template of their own. Id is declared [RecursiveMember(false)] — it registers a path segment but generates no setter, because a notifying Id would let an item be re-keyed after insertion and orphan every path built from the old key.

The built-in row shapes: TextItem, OptionItem, MenuItem, TabItem, BadgeItem, ButtonItem, TreeNode, KeyValueActionItem, BreadcrumbItem. Every styling property on them starts null, so an item says only what its author gave it and falls back to the template drawing it; Visibility and Enabled are the exception and default to Visible/true. What an item leaves null, and an empty collection, does not travel at all — at every depth of the item, in the page and over the hub alike — and the page reads a property an item does not carry as null; a false, a zero or any other value set travels as it is.

Item templates

SetTemplate/AddTemplateVariant (declared on ItemsComponentBase<TComponent, TItem, TTemplate>) set the default template and named variants; TemplateKeyProperty (on TemplatedComponentBase, set by path or SetTemplateKeyProperty<TRow>(r => r.Meta.Kind) including dotted paths; FilterBy, SortBy and AddItemReads take typed <TRow> selectors too) names the item property whose value picks a variant by name — MenuItem.Kind choosing between the header, separator, check, select and plain entry templates is the built-in example. FallbackTemplateKey names the variant used when the value names none. Patching the property named by TemplateKeyProperty re-renders that one item through a collection Replace, so any client-side state the row held is gone — that is the mechanism, not a bug.

Inside a template, bindings default to Root like everywhere else — .BindTitle(path, UIBindingScope.Relative) is what reaches the item's own properties, and it is almost always what you want inside a row:

new StackPanelComponent()
    .AddChild(new TextComponent()
        .BindTitle(nameof(DemoRowItem.Title), UIBindingScope.Relative)
    );

There is no "current item index" argument — an item is addressed by key. UIAction.ArgCurrentItemKey(name) and UIAction.ArgCurrentItem(name) pass the row's key or the row itself as a command argument:

.OnItemClickWithItemKey(nameof(Controller.OpenRow))

RowItemsComponentBase<TComponent, TItem, TRow> (the base of TableComponent, TreeComponent and KeyValueActionComponent) wraps the whole row in a TRow — DefaultRowTemplate for all three. A row's events are blocks, one interface each with one extension class (NE.Standard.UI.Components.Foundation.Items, a global using): IItemClickComponent (a press, or Enter or Space on the keyboard's row), IItemOpenComponent (Enter after the click, or a double click), IItemRemoveComponent (Delete on a removable row, a tab's close), IItemMoveComponent (a drag or Alt+arrow), IItemRenameComponent and IItemUnfoldComponent. Each takes five forms — OnItemOpen, OnItemOpenLiteral, OnItemOpenWithItem, OnItemOpenWithItemKey, OnItemOpenWith, and so on — and move's forms that name the row pass its new index too (indexArgumentName = "index"). A host takes only the families its page raises: a list (ItemsViewComponent) and a table click, open, remove and move; a tree all six; a key-value list click, open and remove; a tabs view remove and rename; a menu, breadcrumbs, a steps strip and a button group click. The key-value list is walked as a table is: one Tab stop with the row cursor, Enter clicks then opens the row (or presses its one shown control — on a list that edits in place, the pencil, as F2 does), a double click opens it, Delete raises a wired removal. An item event is kept by its host and written on the template in its slot and on every one set there later, so OnItemClick and SetTemplate (or SetRowTemplate) may come in either order; the same event registered twice, the later wins. It reaches its own slot only: OnItemClick never reaches a variant AddTemplateVariant sets, except a menu's, which names its check entry too. Each click family also takes (key, effect) — one row's press runs a client effect in place of the command (One entry's effect).

What a row carries

The page is sent each row's item kept to what its host reads off it: the properties its templates bind (a nested row's Parent-scoped bindings included), its filter and sort rules, its template key, the key, Group, IsContent and the abilities. A nested list nothing of the row reads is not in it — a list bound inside the row's template gets it as its own rows — and a value that reads the same as an absent one (false under a binding that falls back to false, an ability's true) is left out. A chat list's row whose model holds every message of the conversation is sent its name, its last line and its time.

Code of your own in the browser that reads a row's item past its templates (rows.itemOf in a package's engine) names what it reads, or takes the item whole:

new ItemsViewComponent()
    .BindItems(nameof(Controller.Rows))
    .AddItemReads("Owner.Email", "Score")
    .SetTemplate(new TextComponent().BindTitle(nameof(Row.Title), UIBindingScope.Relative));

new ItemsViewComponent()
    .BindItems(nameof(Controller.Rows))
    .ReadsWholeItems();

In development the page warns, naming the host and the path, where it reads a property a row was not sent. A chart, a layered graph and any host that draws no rows of its own are sent their items whole; the DataGrid sends what its columns, search and templates read, and AddItemReads names the rest.

Grouping, filtering and sorting

GroupedItemsComponentBase adds SetGroupTemplate for a header drawn above each group of items that share IBindableGroup.Group. The header is drawn from the first shown row of its group — its bindings read that row, and a group all of whose rows a filter hides has no header. A command on the header learns which group it heads with UIAction.ArgGroupKey(name), resolved on the server; ArgCurrentItemKey there is the key of the row the header stands in. A windowed host groups too, by neighbours rather than buckets: a row whose group differs from the row before it gets a header, so a chat feed read backwards shows a day's header over the first message of each day. A header stands where its own HorizontalAlignment puts it, as a row does: a day's pill set to Center sits in the middle. ScrollToItemEffect(listId, key) from a command shows a row at the top of the list, its header over it — the first message of a day the command read the window at. FilterBy and SortBy (on ItemsComponentBase) add rules evaluated against an item property:

.FilterBy(filterBoxId, IInputComponent.ValueProperty, nameof(DemoDeploymentRow.Service))
.SortBy(nameof(ITabItemModel.Order))
  • FilterBy(source, itemProperty, operator, activeOperator, activeValue) ties a filter to another component's property (or, with no source, to a constant); the default operator is UIComparisonOperator.LikeIgnoreCase. Under UIComparisonOperator.In (and NotIn), when the item property is a collection (such as IReadOnlyList<string> or a collection of IBindableItem models compared by Id), the filter checks whether any element in the item's collection is in the right-hand set (for example a MultiSelectComponent's chosen keys).
  • SortBy(source, itemProperty, direction, activeOperator, activeValue, priority) — several sorts combine by ascending priority.
  • With no source, both are unconditionally active.

They compile onto UIItemsView (_filters/_sorts) and run client-side on a plain or virtualized host — filtering hides rows via a class rather than removing them, and fails open: an item whose value never reached the client stays visible rather than silently disappearing. A windowed host resolves rules on the server instead (see below), because the client only ever holds one window of a source that may hold thousands.

A row follows its rules as its values change: a controller's change to a property only the rules read sends the row again, and the reader's own edit of a field in the row counts once the server has taken it. The row is re-placed — sorted, filtered or regrouped — a moment after the focus leaves it, never under the caret of someone still typing in it.

Selection

ISelectableItemsComponent (implemented by ItemsViewComponent, TableComponent, TreeComponent) adds:

  • SelectionMode — None (default), One, Many.
  • SelectedKey — two-way, the chosen key under One.
  • SelectedKeys — two-way, the chosen keys in choice order under Many.
  • ISelectionStyleComponent.SelectionStyle — what a chosen row looks like; unset parts fall back to the control's own default.
  • On TableComponent, SelectionMode = UISelectionMode.Many adds a leading checkbox column (TableComponent.SelectionColumnKey = "selection") with a three-state select-all checkbox in the header (TableComponent.SelectAllRegionName) and a row checkbox per row named after the row's header cell.

From the keyboard an items view and a table are one stop of the Tab order, the keyboard's row lit only while the keyboard holds it: a host whose rows are chosen (a listbox, a grid) or a tree keeps the focus and names that row (aria-activedescendant); a list and a read-only table, whose roles take no such name, move the focus onto the row itself (roving tabindex), which is then the stop — in a wrap list the row's tile, the arrows and Enter still the list's. The arrows walk the rows (a horizontal list Left and Right, a wrap by its lines), Home and End go to the ends, Page Up and Page Down a viewport's height. Enter runs the row's click and then its open; Space chooses where the host chooses and otherwise runs the click. A single choice follows the arrows, Shift with an arrow takes a range, Delete raises the remove — of every chosen row shown, where the keyboard's row is among them; one folded away or filtered out stays. A row that is one button is pressed by them, and a control in a part of the row that answers its own press (data-ui-no-row-open: a grid's chevron, its checkbox) is no stop of its own either. A table's header is a group reached by Up from the first row: Left and Right walk its captions as the columns stand, Alt with an arrow moves a column, Shift with an arrow sizes it and Shift+Backspace puts the widths back, and Down goes back. A host whose rows are chosen or pressed is a listbox (rows holding no control of their own) or a grid to a screen reader; a table only read stays a table. A table that is a grid walks its cells, the root naming the cursor's cell: Left and Right go along the row, Home and End to its ends, Ctrl+Home and Ctrl+End to the first and last row, Up and Down keep the column; Enter and Space press a cell's one control, F2 moves the focus into the cell, and Enter on a cell with nothing of its own is the row's. Every cell says where its column stands among the columns shown (aria-colindex), so a moved column is heard at its new place.

A bound SelectedKey under Many (or SelectedKeys under One/None) compiles with a warning (CompiledView.Warnings), logged rather than refused. Nothing prunes SelectedKey/SelectedKeys when the item they name leaves the collection — a controller that removes a chosen item clears the key itself.

Item abilities and whole-control switches

IItemAbilitiesModel — CanSelect, CanDrag, CanRemove, CanRename, CanShowContextMenu, all bool? and unset meaning "may" — lets one item opt out of what its host otherwise allows. The built-in row templates bind each to the matching property of IItemAbilitiesComponent on the row, so a flag flipped on a live item reaches its row like any other bound property.

A row template may set or bind these flags itself — to a controller's flag as readily as to the item — and the row refuses what either its item or its template refuses, in an items view (whose template is drawn inside the row) as in a table or a tree (whose row is the template). That is the switch for a page some sessions may only read: a later Bind takes the place of the template's own binding to the item, and every row follows the controller:

new DefaultRowTemplate()
    .Bind(IItemAbilitiesComponent.CanDragProperty, nameof(Controller.CanEdit), UIBindingScope.Root)

Enabled = false on the host refuses the same gestures, but dims the whole list.

The server holds the row to these flags as well: a move, removal, rename or choice of a row its item or template refuses is refused even from a forged page, as a disabled component's command is. That guards the page, not your data — the command still checks what it is asked to do. Two things are not judged on the server: a drop's keys, which the target's command reads against its own collections, and a windowed source's rows, which the server cannot read by key. A tab's drag and pin tell the server only where the tab goes, and the server writes the orders itself.

The host-wide switches sit beside these per-item flags and gate the mechanism itself:

  • TreeComponent: Draggable, Renamable, RenameOnDoubleClick, Removable, ShowChevron.
  • ItemsViewComponent and TableComponent: Draggable (moving a row among the rows, below), DragHandle and DragHandlePlacement (dragging it by a grip).
  • ItemsViewComponent, TableComponent and TreeComponent: DragKind and DragEffects (offering the rows to another host, below).
  • TabsViewComponent: Draggable (reordering by dragging captions), Renamable (the double click and F2), Removable, ShowOverflow, and TabMenuEntries (the tab menu's built-in entries, below).
  • IRowHoverableComponent.RowHoverable — whether rows highlight under the pointer, on ItemsViewComponent, TableComponent and TreeComponent alike.

Off, the control keeps no chrome for the mechanic at all — Removable = false on a tab strip means no caption shows a close and no room is kept for one, not merely that closing fails.

Moving rows

With Draggable on, a list's or a table's row whose item does not refuse it (CanDrag) is dragged and dropped between two others, or moved one place by Alt+Up and Alt+Down, and by Alt+Left and Alt+Right where the rows run across; in a wrap Alt+Up and Alt+Down move it a line. The row raises move with its key and the index it now takes, and the controller moves it — RecursiveCollection.Move(key, index) finds the row by its key, through the collection's own index, and clamps the index to the list. In a windowed host the index is its place in the source's whole query, which the source places against its window with Move(item, oldSourceIndex, newSourceIndex):

new TableComponent()
    .SetDraggable(true)
    .BindItems(nameof(Controller.Steps))
    .OnItemMoveWithItemKey(nameof(Controller.MoveStep));   // ItemsViewComponent: OnItemMoveWithItemKey

[UICommand]
public void MoveStep(string id, int index)
    => _ = Steps.Move(id, index);

The same index answers TryGet(key, out item) and Remove(key): a command that receives a row's key reaches the row without a loop over the collection.

The row stands in its new place as soon as it is dropped, without waiting for the server; the command's answer says where it stays. The collection's Move of it leaves it there, or puts it where the controller did; a controller that refuses — by doing nothing, or by failing — puts it back, and so does a lost connection. A controller that orders the rows some other way (a remove and an insert, a reload) wins the same way: the page shows what the server sent.

OnItemMove(command, arguments…) takes the arguments by hand; UIAction.ArgEventValue(name) reads the index the event carries. A drag is refused while a sort orders the rows, which would put the row straight back, and it moves the one row dragged — a chosen group moves one row at a time. A row of a list nested in another moves within its own list, and a row of a grouped list or table within its own group: over another group's rows or a group's header no drop line shows and nothing is sent, and Alt+Up/Down at a group's first or last row does nothing. The index sent is still the collection's. The line between two rows has one place, whichever of them the pointer is over: in the middle of the gap a spacing leaves.

A row's words are not selected by default — it is pressed, not read; SetTextSelectable(true) on the list, the table or the row's template lets the reader select and copy them (see text selection). A row that drags by itself never selects, whatever the switch says — a press on it is the drag's. Where a row's words are the reader's to select and copy, or its presses to use, drag it by a grip instead:

new ItemsViewComponent()
    .SetDraggable(true)
    .SetDragHandle(UIDragHandlePlacement.Start)   // SetDragHandle(true): at the row's end
    .OnItemMoveWithItemKey(nameof(Controller.MoveStep));

DragHandle lifts a row only by the grip, at its end or, with DragHandlePlacement = Start, its start; the rest of the row keeps its presses, and its words what TextSelectable gives them. The grip is no tab stop — a press on it gives the list the keyboard on that row, and Alt+Up/Down moves the row as before. A table's grip stands in a narrow track of its own past the last column or before the first, never one of its columns, and a start grip stays pinned with a pinned first column. A wrapped items view draws no grip: its tiles drag whole.

Dragging items to another host

SetDragKind(kind) offers a list's, a table's or a tree's rows to the other components of the view as a kind — lower-case letters, digits and hyphens, "card" — and SetDragEffects says what a drop may do with them: UIDragEffects.Move, Copy, or All, the default; None offers nothing. A row whose item or template refuses it (CanDrag) stays; a sort, which keeps a row from moving among its own host's rows, does not keep it from leaving for another. Any component takes a kind with OnDrop(kind, command, arguments…) (OnDropLiteral for literal arguments): its command receives a UIDrop in its argument named drop, beside the arguments given — Kind, Source (the id the source was given in the view), Keys (the dragged row's, or the chosen rows' where the dragged one is chosen, in the source's order), Index (the place the first takes in a list or a table), Folder (a tree's folder, empty for its top level) and Effect. A drop between two hosts offering the same kind is a move, into anything else a copy; Ctrl (⌥ on a Mac) as it lands asks for a copy, within what the source's DragEffects allow. The keys are the page's word, not a fact: the command checks them against its own collections.

new ItemsViewComponent("todo")
    .BindItems(nameof(BoardController.Todo))
    .SetDragKind("card")
    .SetSelectionMode(UISelectionMode.Many)
    .OnDrop("card", nameof(BoardController.DropCards), UIAction.Arg("list", "todo"));

[UICommand]
public void DropCards(UIDrop drop, string list)
{
    RecursiveCollection<Card> source = CardsOf(drop.Source);
    RecursiveCollection<Card> target = CardsOf(list);
    var at = drop.Index ?? target.Count;

    foreach (var key in drop.Keys)
    {
        Card? card = source.FirstOrDefault(item => item.Id == key);

        if (card is null)
            continue;

        if (drop.Effect == UIDropEffect.Move)
            source.Remove(card);

        target.Insert(at++, drop.Effect == UIDropEffect.Move ? card : card.Copy());
    }
}

DragKind and DragEffects are set as the view is built, never bound — the view checks every OnDrop against the kinds offered when it compiles — so a drag only some sessions may make is gated on the rows' CanDrag (above). A list declared in an item template, one per row of an outer list, is one component: Source names it whichever row's copy the items left. The command finds the target's row by an argument — OnDrop("card", nameof(BoardController.DropCards), UIAction.ArgCurrentItemKey("column")) on the inner list — and the source's by the keys, which therefore stay unique across every copy of the list.

A list or a table marks the place among its rows, a tree the folder under the pointer, anything else its edge, dashed. Between two lists or tables of the kind, neither virtualized nor windowed, a move stands in the target at once and goes back unless the command's answer keeps it there; anything else waits for the server. From the keyboard, Ctrl+X (a move) or Ctrl+C (a copy) on a row — ⌘ on a Mac — takes it, or the chosen rows, and Ctrl+V on a target drops them there, after its keyboard's row in a list. The target decides as a drag's drop does, so a cut pasted into a component of another kind is a copy; Ctrl+V inside a text field is the field's own paste. A kind spelt otherwise, or one no component of the view offers, is refused when the view compiles: a drag never leaves its view.

Hosting modes

IItemsHostComponent.HostMode (ItemsViewComponent, TableComponent) is one of Plain, Virtualized, Windowed — never set directly:

  • Plain (default) — every item is real DOM, rules run over the children.
  • Virtualized() — the client holds every item's value and keeps only the rows in view (plus overscan) in the document — on a Wrap layout the lines in view, as many tiles to a line as fit it; rules run over the values and produce the projected order. The row holding the focus stays drawn while the reader scrolls it out of range, or while its item is refilled, replaced or emptied, until the focus leaves it — a field open in it keeps what is typed. Calling it on a host already bound to a source throws.
  • BindSource(path, scope) — binds to a windowed source (below) and puts the host in Windowed mode; calling it on an already-virtualized host throws, and vice versa.
  • WindowSize sets how many items one window holds (default 50, at most 1000 — past that the view fails its compile, as a pager's page size does); not bindable, read once by the client.
new ItemsViewComponent()
    .BindSource(nameof(Controller.Rows))
    .SetWindowSize(50)
    .FilterBy(filterBoxId, IInputComponent.ValueProperty, nameof(DemoRowItem.Title));

An items view's Padding (responsive, bindable) is room inside its scroll: the rows scroll through it, so a list ending under something laid over its foot — a composer — shows its last row clear of it, and a list held at its end stays there as the padding changes. On the side the bar is drawn the padding is at least the scrollbar's room: with OverlayScrollbars (the default) the overlay thumb's --ui-scrollbar-room (12 px — the thumb 2 to 8 px in, 4 px of air), kept whether the rows overflow or not, so the rows never narrow as they start to scroll. A list padded 12 on both sides stays even, its thumb inside the padding; one padded 4 is widened to 12 there, so no list pads for the thumb. With it off, the classic bar's strip stands past the padding while the rows overflow. A list that only grows with its rows keeps the room too, and SetScroll(UIScrollMode.Disabled) on that axis gives it back. A screen where nothing hovers — a touch screen — draws its thin bar over the edge and keeps no room either way. A tree, a scroll container, a text area and a scrolling region's root keep the room the same way; a popup list keeps it only while it overflows.

ContentMaxWidth (responsive) caps the rows' column inside the view: wider, the column is centred and the view stays as wide as its region, so the bar stands at the region's edge rather than beside the words — a conversation's or a document's column in a wide pane — and the room stands inside the free space either side. SetLayout(UIItemsLayoutType.Accordion) on an ItemsViewComponent whose template is an ExpanderComponent coordinates single-expand across the list's items on the client (expanding one item collapses the others) and joins the borders and outer corners of the currently visible items into a single connected stack as items are added, removed, reordered or filtered.

new ItemsViewComponent()
    .BindSource(nameof(ChatController.Conversation))
    .AnchorToEnd()
    .SetContentMaxWidth(860)
    .SetPadding(UIThickness.All(16, 8, 16, 8));

Where the reader is

An items view's FirstVisibleKey is the key of the row at its top: the first row whose box shows below the scroll's top edge — past the view's Padding, which stands under whatever is laid over that edge, and below a group header the stylesheet holds there. Group headers and a window's stand-ins are no rows. It is the page's to write, bound one way from the page (BindFirstVisibleKey(path)): written once after the first layout, then each time the reader's scroll comes to rest (150 ms without a scroll event, and at least once a second through a scroll that never pauses), and again as the rows or the view's box change — a window read, rows posted, a pane resized. A key that did not change is not sent, a view nobody binds sends nothing, and a value the controller sets scrolls nothing. A windowed view names a row of the window it holds; while only rows still on their way stand in view it says nothing, and a list emptied says null.

LastVisibleKey is the same at the other end: the key of the last row whose box shows above the scroll's bottom edge, past the view's bottom Padding — the room a composer laid over a feed's foot stands in. It is bound and written as the first is (BindLastVisibleKey(path)), and a view bound at both ends measures its rows once for the two. A messenger's pinned bar follows this one: the latest pin on screen or above it, so a pin in the last screenful shows while the reader stands at the end.

Follow it where it lands, in the bound property's setter — the way a chat's pinned bar shows the latest pin at or above the reader:

[RecursiveMember(false)]
public string? TopKey
{
    get;
    set
    {
        if (SetRecursiveProperty(ref field, value, TopKeySegment))
            Pinned = _pins.LastOrDefault(pin => Order(pin) <= Order(value));
    }
}

new ItemsViewComponent()
    .BindSource(nameof(Messages))
    .AnchorToEnd()
    .BindFirstVisibleKey(nameof(TopKey));

Windowed sources

A windowed host's items come from UIItemSourceBase<TItem>, for a collection too large to hold whole — a hundred thousand rows, a conversation read backwards. Subclass it and implement one member, GetWindowAsync, which answers a request for a window with the items in it.

  • UIItemWindowRequest carries Anchor (UIItemAnchor.Start/.End/.At(offset)/.Before(key)/.After(key), told apart by Anchor.Kind), Count, Mode (Replace or Extend, joining the read to the existing window and trimming the far side), and Query.
  • UIItemsQuery (Filters/Sorts, as UIItemFilterTerm/UIItemSortTerm) is what the host's filter/sort rules resolved to, evaluated against the controller value behind each rule's Source — a rule source must be bound on a windowed host, refused at compile time otherwise, because an unbound control lives only in the browser and the server could never see it. An inactive rule contributes no term, so an empty filter box means "everything."
  • UIItemWindow<TItem> is the answer: Items through its constructor, and the init properties Offset (where the window starts, null for a source that counts in cursors), TotalCount (under the query, null when unknown), HasMoreBefore, HasMoreAfter, optionally Aggregates over the whole query, and GroupBefore — the group of the item just before the window, which only the source knows, so a grouped host heads the window's first row only when its group differs (left null, the first grouped row is always headed). It is checked against the request: no more items than asked for, no id twice, and Offset plus the items within TotalCount.
  • UIComparisonEvaluator.Evaluate(left, operator, right) compares one value the way a filter term means it, for a source with nothing better than an in-memory scan — a source over a database translates the terms into its own query instead.

While the next window is read, an items view draws the rows it does not have yet as grey bars in the rows' shape, measured from the rows it shows, and the bars shimmer until the rows land (they stand still for a reader who asked for less motion). A source that cannot count has no room below its last row, so three such rows stand there meanwhile. For rows unlike each other — a conversation's messages, of different heights on both sides — bars would read as messages of their own: SetLoadingLook(UIItemsLoadingLook.Indicator) shows a small ring at the edge the rows come in at instead (the top while older messages load), over the rows in view, moving none of them.

A source over a database reads the count and one page of rows per request. Here OrderStore stands for the application's own data access, with CountAsync, PositionOfAsync (where a key sits under a search) and ReadAsync(search, skip, take):

internal sealed partial class OrderRow(Order order) : RecursiveObservable, IBindableItem
{
    [RecursiveMember(false)]
    public string Id { get; } = order.Id;

    [RecursiveMember]
    public partial string Customer { get; set; } = order.Customer;
}

internal sealed class OrdersSource(OrderStore store) : UIItemSourceBase<OrderRow>
{
    protected override async Task<UIItemWindow<OrderRow>> GetWindowAsync(UIItemWindowRequest request, CancellationToken cancellationToken)
    {
        // The host's one filter rule, resolved on the server; an empty filter box sends no term at all.
        var search = request.Query.Filters.Length > 0 ? request.Query.Filters[0].Value as string : null;

        var total = await store.CountAsync(search, cancellationToken).ConfigureAwait(false);

        var start = request.Anchor.Kind switch
        {
            UIItemAnchorKind.End => total - request.Count,
            UIItemAnchorKind.Offset => request.Anchor.Offset,
            UIItemAnchorKind.Before => await store.PositionOfAsync(search, request.Anchor.Key!, cancellationToken).ConfigureAwait(false) - request.Count,
            UIItemAnchorKind.After => await store.PositionOfAsync(search, request.Anchor.Key!, cancellationToken).ConfigureAwait(false) + 1,
            _ => 0
        };

        start = Math.Clamp(start, 0, Math.Max(0, total - 1));

        IReadOnlyList<Order> orders = await store.ReadAsync(search, start, request.Count, cancellationToken).ConfigureAwait(false);

        return new UIItemWindow<OrderRow>([.. orders.Select(static order => new OrderRow(order))])
        {
            Offset = start,
            TotalCount = total,
            HasMoreBefore = start > 0,
            HasMoreAfter = start + orders.Count < total
        };
    }
}

request.Query.Sorts is the host's SortBy rules in the same way, for the query's ORDER BY.

The UIItemSourceBase<TItem> protected helpers — Append, Prepend, Insert, Replace, Move, Remove, Invalidate — mutate the realized window and its TotalCount/HasMoreBefore/HasMoreAfter bookkeeping under the window's lock; there is no event to raise, changing Items is the change notification, and the subclass never writes Items itself. Append and Prepend are mirrors: each is an item new in the source at the window's end or start, and TotalCount grows by one — Prepend keeps the window's start where it was, now on the new item. An item the window already holds under that key is replaced where it stands, counted already. Insert(item, sourceIndex) is an item new anywhere in the source: inside the window, or at its end where the window ends the source, it joins it; before it, it moves the window's start on; after it, it is only counted. Replace(item) puts a new shape of a held item in its place — an edited, pinned or reacted-to message changes where the reader has it — and is false, changing nothing, for a key the window does not hold. Move(item, oldSourceIndex, newSourceIndex) moves a row inside the window as one move, and otherwise takes it out of its old place and into its new one. Remove(key) takes an item out of the window; Remove(key, sourceIndex) also places one the window does not hold, moving the window's start back for an item gone before it and keeping HasMoreBefore, GroupBefore and HasMoreAfter true. Invalidate drops the window: the page reads it again from its own edge — the end of an end-anchored host — so the reader's place is not kept. A window the source trims back to its limit leaves the page, not the source: the trim is marked as one, and the reader's keyboard cursor waits for its row. A source is itself RecursiveObservable and typically lives as a [RecursiveMember(false)] property on the controller, which reads the first window in OnInitializeAsync so the page paints with rows already in it — the client reads further windows itself as the user scrolls, but nothing paints before the first read completes:

internal sealed partial class OrdersController(OrderStore store) : UIControllerBase
{
    [RecursiveMember(false)]
    public OrdersSource Orders { get; } = new(store);

    protected override Task OnInitializeAsync(CancellationToken cancellationToken)
        => Orders.LoadWindowAsync(new UIItemWindowRequest(UIItemAnchor.Start, 50), cancellationToken);
}

A command jumps the same way — Orders.LoadWindowAsync(new UIItemWindowRequest(UIItemAnchor.At(5_000), 50), ...) replaces the window, and Orders.Offset/Orders.TotalCount say where it landed.

A page at a time

A windowed host that says SetPaging(true) (Paging, bindable) shows its window as a page of WindowSize rows: its scroll asks for nothing, and a PagerComponent aimed at it by id turns the page — through the same window request the scroll makes, by offset. The pager shows the pages by number (UIPagerMode.Full: first, previous, the ends and the pages around the current one with an ellipsis for the rest, next, last) or the rows on show (Compact: "21–40 of 812" between previous and next); on a phone it is compact whatever its mode. SetPageSizes([20, 50, 100]) offers the viewer a size, kept in the browser under the list's id, as a table keeps its columns' widths, so a reload lands on it; a size no longer offered is ignored. Page Up and Page Down in the list turn its page too.

new ItemsViewComponent("results")
    .BindSource(nameof(SearchController.Results))
    .SetWindowSize(20)
    .SetPaging(true)

new PagerComponent()
    .SetTarget("results")
    .SetPageSizes([20, 50, 100])

A pager aimed at nothing, at a component the view does not have, at a host that holds its rows whole or at a window that scrolls is refused when the view compiles. The page lives in the source (Offset); an application that wants it in the address writes it from there — Context.SendEffectsAsync([new ReplaceAddressEffect(...)]) as the source reads a page — and reads it back in OnNavigatedAsync, loading that page's window before the page draws.

The table's columns

TableComponent.AddColumn(caption, template, width, alignment, key, pinned, icon, hidden, content) registers a UITableColumn and a template variant keyed column:{key} (key defaults to a 1-based ordinal; a content caption is shown as written, not looked up as a key). The caption is a phrase: a string is the author's text, UIPhrase.Of(key, args) a key with its arguments, looked up even on a column marked content. AddTextColumn(caption, propertyPath, width, alignment, key, pinned, icon, hidden, content) (and the typed AddTextColumn<TRow>(caption, r => r.Property, ...) overload) is the shorthand for a text cell, binding a DefaultTextTemplate relatively to the row. A pinned column stays fixed while the table scrolls sideways, and pinned columns must lead. An icon (UITableColumn.Icon, and IconColor through SetColumnIcon(key, icon, color)) stands before the caption, in the header and beside a sort mark, while the column's accessible name stays the caption. A hidden column (UITableColumn.Hidden, HideColumn(key)) starts hidden at every width; a viewer's own choice in a column chooser, kept in the browser, wins over it. A plain table draws no chooser, so only a host with one — the data grid — can show such a column again. A row is named by its header cell (role="rowheader"), which a screen reader says as it moves from row to row: the first column with a caption, in a table of more than one column, or the one SetRowHeaderColumn(key) marks (UITableColumn.IsRowHeader). HideColumnBelow(key, tier) hides a column below a viewport tier:

new TableComponent()
    .SetItems(rows)
    .AddTextColumn("Service", nameof(DemoDeploymentRow.Service))
    .AddTextColumn("Replicas", nameof(DemoDeploymentRow.Replicas), UIGridUnit.Absolute(96), UITextAlignment.End)
    .AddColumn("Status", badgeTemplate, UIGridUnit.Absolute(120));

Columns is read-only and render-time only (IsBindable = false) — the columns are how the table is built, not state. ShowHeader, Striped, ShowColumnSeparators, ShowRowSeparators, ResizableColumns (client-side only; widths are never sent back; from the keyboard, Shift with an arrow on a caption, Shift+Backspace to put them back) and ReorderableColumns (a column dragged by its caption; the order stays client-side too, and pinned columns keep their place) round out the table's own switches. Under SetSelectionMode(UISelectionMode.Many), the table prepends its own fixed leading checkbox column (TableComponent.SelectionColumnKey = "selection"), with a three-state select-all checkbox in the header (spanning HeldRows under Virtualized() too), row checkboxes named after each row's header cell, and Shift+Click range selection across checkboxes while row clicks outside the checkbox column leave the checked set untouched. Sorting by header and editing are not built in; a page at a time is the pager's (A page at a time, above).

A column's template may hold a list of its own — an items view bound relatively to a collection on the row — and each row shows its own row's items.

The tree

TreeComponent renders ITreeNodeModel rows — a text item plus ParentId, Kind, HasChildren, IsFolder, Expanded, DropTarget — as a flat, keyed list in walking order, not a nested structure. TreeNode (the built-in model) and TreeNode.Flatten(roots, children, toNode) turn a nested source into that list, stamping ParentId on the way down. A tree is meant for a small set, or for one that loads each folder as it opens (HasChildren with OnItemUnfold, below): it is neither virtualized nor windowed.

  • Kind picks a node template variant added with AddNodeKind(kind, template); ConfigureDefaultNode/ SetNodeTemplate shape the one used when no variant matches.
  • OnItemClick/OnItemClickWithItemKey/OnItemClickWithItem/OnItemClickWith run a command on a press on a node — the row's click, as OnItemClick is a list's — after the selection has followed the press, so a notes tree opens a note on one press (a phone has no double click) and answers with effects like any command. A press on the chevron only folds, and a press inside an open rename field is the field's. From the keyboard, Enter on a node runs its click and then its open (OnItemOpen…), as on an items view's or a table's row, and Space chooses — or, in a tree that chooses nothing, runs the click; Right and Left fold.
  • An empty tree — or one whose every node a filter leaves out — draws its empty template (SetEmptyTemplate, or ConfigureDefaultEmptyTemplate to word the built-in one, which a table has too), and takes it out when a node comes back. SetShowEmptyTemplate(false) (bindable; on the items view, the table, the tabs view, the menu, the radio group and the key-value list too — not a select's or a search's list, whose empty state answers a list the reader opened and is worded only) shows nothing instead — a short list under every row of a feed need not say "nothing" under each; the template is hidden, not left out, and an empty items view, table, tree or key-value list with SetShowEmptyTemplate(false) collapses its own root element so it leaves no gap in a parent stack or grid. Every list host with a built-in empty template words it through ConfigureDefaultEmptyTemplate — the select's list and the radio group, with ConfigureDefaultGroupTemplate for their group headers, and the tabs view; a menu and a key-value list have none until it is asked for, and the same call puts it in. The empty state of an items view, a tree or a table takes the host's whole box: a centring template such as UIPage.Empty stands in the middle of a list given the region's height, as it does in the panes' placeholder; the default line keeps the top.
new TreeComponent("notes-tree")
    .BindItems(nameof(NotesController.Nodes))
    .SetSelectionMode(UISelectionMode.One)
    .BindSelectedKey(nameof(NotesController.SelectedNodeKey))
    .ConfigureDefaultEmptyTemplate(empty => empty.SetTitle("No notes yet."))
    .OnItemClickWithItemKey(nameof(NotesController.OpenNodeAsync))
  • HasChildren lets a node claim children before any are in the list; OnItemUnfold/OnItemUnfoldWithItemKey fire the first time it is unfolded, and the controller answers by adding the children or clearing the flag. A fold and an unfold while that answer is on its way ask nothing more; once it has settled, the next unfold of a node still claiming children and holding none asks again, its chevron faded meanwhile.
  • The reader's fold is kept for the next page load and painted before it shows: per folder, for every folder on the page and at most 200 others, the oldest let go.
  • Renamable/RenameOnDoubleClick plus a node's own CanRename gate F2/double-click renaming; a rename writes the new title back through the node's two-way RenamedTitle binding (bound to ITreeNodeModel.Title by default on the built-in node template, and required on any custom template), and OnItemRename/ OnItemRenameWithItemKey fire afterward for refusing or normalizing it.
  • Draggable plus a node's CanDrag gate dragging a node onto a folder, between two nodes or onto the tree's own ground, or moving it with Alt and an arrow; the move writes DropTarget and raises OnItemMove/OnItemMoveWithItemKey with the index it takes among that folder's nodes, and the controller moves the node or leaves it — nothing moves on the client on its own. A folder is a node with IsFolder = true — even while empty, without asking for its children — or, unmarked, one holding children; IsFolder = false takes no drop whatever it holds. Over a file, the dragged node, a node under it or a disabled folder, the cursor says no drop and a release sends nothing. A tree with a DragKind offers its nodes to another host even without Draggable, a folder going with what it holds.
  • A node that says whether it is a folder (IsFolder true or false) and names no Icon of its own is dressed as a file tree's: a folder, open while unfolded, in a golden yellow, or a page in the title's ink; its own Icon, or an IconColor other than the default, wins.
  • Indent sets how far each level steps in, in pixels; ShowChevron toggles the chevron for a node that can unfold — off, the arrows still fold, and a press folds only a node that cannot be chosen.

Items hosts beyond lists

MenuComponent renders IMenuItemModel entries with Kind selecting header/separator/check/select/plain variants (a check shows Checked as a mark at its end, a select shows Value and opens its Items beside it), an entry's Items as a nested menu up to MenuComponent.MaxSubmenuDepth (4) levels deep (measured automatically from static Items, or set with SetSubmenuDepth(depth) for bound items), and folds to icons alone via ICollapsibleComponent; a press on its switch raises OnExpand or OnCollapse, the forms an expander and a collapsible panel take too (IExpandableComponent), while a section of entries opening raises neither and a bound Expanded the controller pushes folds the menu without them. SetToggleContent puts content beside its switch, seen only while it is open, and SetSearch a search there — the field a text input's own SetSearch makes, Filled and small — that narrows the entries in the browser by the words they show, nested ones included; a search that leaves nothing shows the menu's empty template, "Nothing to show." unless the menu has its own. A menu draws no empty state otherwise — a context menu or an entry's sub-entries holding nothing say nothing — until ConfigureDefaultEmptyTemplate(empty => empty.SetTitle("No chats yet")) puts the built-in one in and words it, a one-line state for a panel's list. A MenuItem is a TextItem, so an entry carries a Description — one muted line under its title, cut with an ellipsis, the icon centred across both — as a contact list's last message; an entry's Icon may be a picture's address, and IconShape = UIShape.Circle draws it round, as a person's avatar is (a glyph keeps its own shape; every item model and text body carries IconShape, and ImageComponent.SetShape(UIShape.Circle) is a standing picture's). A round picture with no picture — no address, an empty one bound later, or one that fails to load — draws a glyph on a neutral circle in its place, the person's (UIGlyphs.Person); a picture of any other shape that fails draws a picture's glyph (UIGlyphs.Image) on the wash in its box; IconFallback (on an item, a text, a badge) or SetIconFallback (an image, a standalone icon) names another for either. The controller binds no visibility for it, a good address given later brings the picture back, and MapUIGlyph redraws the fallback as it does the glyph anywhere. An image tries its FallbackSource first; an application ships no placeholder picture of its own for a failed one. Folded, a menu keeps its entries' badges on their icons' corners and its entries' names: a direct entry's title is its tooltip, on hover and on the keyboard's focus, unless it has a tooltip of its own. SetDisplay(UIMenuDisplay.Rail) draws the menu as a navigation rail instead — a narrow column, each entry its icon over a one-line label, its badge on the icon's corner (an empty BadgeTitle a dot), the current entry marked by a bar on the rail's edge and its icon filled, the ground the menu's Surface; a label cut short shows whole as its tooltip. A rail never folds and draws no toggle, its groups fly out beside it as a folded menu's do, and it takes no search, since a match inside a group would not show; its entries stand edge to edge. SetSize picks its measures, Medium unless set: Large a 72 px column of 24 px glyphs over caption-size labels, Medium 60 px of 20 px glyphs over smaller labels, Small 48 px squares whose labels are only their tooltips (and still the entries' names to a screen reader). Laid out horizontally, it is a bottom navigation bar, its entries sharing its length down to a press's width each — 64, 56 or 48 px by the size — and then scrolling sideways, a caption or a rule between them an upright line. A rail that is the whole of a view's left side is the navigation rail on a wide screen and that bottom bar on a phone: where the sides become drawers (UIViewOptions.SideDrawers, below the medium breakpoint unless the view names another width), a left side holding the rail and nothing else — the rail itself, or containers, stack or wrap panels, surfaces and scroll containers each holding only the next one down to it — is no drawer and gets no button; the rail lies along the page's bottom, the current entry marked on its top edge over the bar's hairline, its groups flying out upward, Left and Right walking it, and the content and footer end above it. A side holding anything more, a list menu, and a right side stay drawers. A view whose page keeps its bottom for itself — a chat's composer — turns the bar off with UIViewOptions.RailBottomBar = false: the side is then a drawer as any other, opened by the header's button, and the rail is drawn in it as a list, each entry its icon beside its title and its groups opening inline; where the sides are columns it is the rail again.

Display takes a value per breakpoint, as Visibility does: SetDisplay(UIMenuDisplay.Rail, xl: UIMenuDisplay.List) is one menu that is the rail below the extra-large width and the list, whole names and all, from it — where a rail's one-line label would cut a long name short. The browser draws the shape of the width it stands at, from the first paint; the toggle, the search and a drawer's pin show only where it is a list, and a list's fold is kept for it while it is a rail. Where the sides are drawers the base tier alone decides, a narrower tier above it never: a rail there is the bottom bar, or with the bar off the drawer's list.

protected override IVisualComponent? CreateLeftSide()
    => new ContainerComponent()
        .SetPadding(UIThickness.All(8, 0, 4, 16))
        .AddChild(new MenuComponent("sidebar")
            .SetDisplay(UIMenuDisplay.Rail)
            .BindItems(nameof(ShellController.Navigation)));

A group's flyout, and a hidden or cut title's tooltip, open toward the content — to the right of a menu on the left, to the left of one on the right, above a bottom bar. A group's own entry, in any menu, only opens and closes its group: it raises no item click, so a command belongs on the entries inside it. TabsViewComponent renders ITabItemModel entries sorted by Pinned descending and then Order, with a two-way SelectedKey for the open page — its pages come from the collection, unlike TabsComponent, whose captions are fixed regions the view authors directly and which is not an items host at all. To a screen reader the strip is a tab list (.ui-tabs-view__tablist, named by the strip's AccessibleName) owning every tab's caption, each caption and its page naming the other, and a tab's × says which tab it closes ("Close Inbox").

A right press on a tabs view's caption — or the context-menu key on a focused one — opens the strip's own tab menu. Its built-in entries are the ones TabMenuEntries chose (UITabMenuEntries, flags, bindable; None by default, so a strip offers none unless asked):

  • Rename — the same field a double click opens, whether or not the strip is Renamable (that switch governs the double click and F2); an item's CanRename = false still refuses it.
  • Pin — shown as Pin or Unpin by the tab's state: the server's built-in tab-pin command flips the tab's two-way Pinned binding, moves the tab to the end of the pinned ones, and writes the two-way Order values that keep it there, as it does for a drop (direct client writes to Pinned or Order are refused).
  • Close or Delete — the two forms of the one remove entry, chosen one or the other (SetTabMenuEntries refuses both): Close is neutral, with the cross; Delete wears the trash glyph in the danger colour. Either does exactly what the cross does, so it shows only where OnItemRemove or OnItemRemoveWithItemKey hangs a command and the tab may go — never on a pinned tab.

An application's own entries go in with AddTabMenuEntries, and OnItemMenuEntry hears them with the entry's key and the tab's. The order is fixed — Rename, Pin or Unpin, a rule, the application's entries and a rule, the remove entry last — and a rule shows only where entries show on both sides of it; a menu with nothing to offer a tab stays shut.

new TabsViewComponent()
    .BindItems(nameof(EditorController.Documents))
    .SetTabMenuEntries(UITabMenuEntries.Rename | UITabMenuEntries.Pin | UITabMenuEntries.Close)
    .AddTabMenuEntries(new MenuItem { Id = "close-others", Title = "Close others" })
    .OnItemMenuEntry(nameof(EditorController.TabAction))      // TabAction(string entry, string id)
    .OnItemRemoveWithItemKey(nameof(EditorController.CloseDocument))

A tab template given a context menu of its own (SetContextMenu) keeps full control: its menu replaces the strip's, and the strip draws none.

StepsComponent renders a numbered wizard step indicator over TextItems (SetItems/BindItems), marking steps before SelectedKey as completed (checkmark), the active step (aria-current="step") as current, and later steps as upcoming, with SetOrientation (Horizontal or Vertical, horizontal strips automatically switching to vertical when their container lacks width for every step) and OnItemClick/OnItemClickWithItemKey to jump between steps.

SelectComponent, SearchComponent and RadioGroupComponent extend OptionsInputComponentBase<TComponent, TItem>, whose value is one option's key, and MultiSelectComponent its sibling over a value of its own, OptionsInputComponentBase<TComponent, TItem, TValue> — an IReadOnlyList<string> of the chosen keys in the order they were chosen, each once. AddOption/AddOptions/SetOptions/BindOptions are the option-flavoured names for AddItem/AddItems/SetItems/BindItems, over IOptionModel items. The select and the multi-select share their field — clear button, chevron, placeholder, where the list opens, appearance, size, caption and affixes — through SelectComponentBase<T, TItem, TValue>; the multi-select draws each chosen option as a chip with its own remove button, checks the chosen ones in a list that stays open while they are toggled, and caps the value with MaxSelected. Its chips are reached from the keyboard: ArrowLeft from the field walks onto them, and Delete or Backspace takes one out.

What a multi-select is drawn as is its Variant, decided at render. UIMultiSelectVariant.Chips is the above and the default. Badges draws each option as its badge — BadgeTitle the words, its style, colour, fill and icon the look, a Description under it — at the start of its row, and each chosen one in the field as that badge with its remove inside it; leave Title unset where the badge is the option's name, or the same words read twice. Checkboxes has no field and no list: every option stands as a checkbox, laid out by Orientation and Spacing as a radio group's radios are, the unchecked boxes off once the field holds MaxSelected. The group is one Tab stop, the arrows walk its boxes and Space checks one; it takes no free text (SetAllowFreeText() with it throws ArgumentException, as does a view setting the pair on the properties). The value is the same list of keys in all four (Button draws the multi-select as a compact button trigger via SetVariant(UIButtonVariant), SetIcon, SetTitle, SetSize, SetColor that opens the checkable option list in a popup and shows the chosen count as a badge on the button instead of chips in a field, taking no free text and usable in TextInputComponent / TextAreaComponent AddLeadingAction, AddTrailingAction and SetTrailingAction). SetVariant also installs the variant's option template, unless the component already holds one of yours:

new MultiSelectComponent()
    .SetVariant(UIMultiSelectVariant.Checkboxes)
    .SetTitle("Email me about")
    .SetOptions(Notifications)
    .SetMaxSelected(3)
    .BindValue(nameof(AccountController.Notifications))

SetAllowFreeText() lets the reader type values of their own — labels, recipients, keywords. An entry stands after the chips: Enter or a comma makes a chip of its text, a pasted "a, b, c" makes three, and Backspace on an empty entry takes the last chip. The options become suggestions, narrowed as the reader types; an arrow picks one, and Enter otherwise takes the text — or, with SetTagEntry(UITagEntry.FirstSuggestion), the first suggestion is marked as the reader types and Enter takes it, the text only where none matches (Escape takes the mark off). A typed tag naming an option is that option's key, any other is its own text, and the value is the same list of strings. A rule every tag must match is RegexEach; a tag it refuses, or one past MaxSelected, stays in the entry and is said on the field's line:

new MultiSelectComponent()
    .SetTitle("Labels")
    .SetAllowFreeText()
    .SetOptions(KnownLabels)
    .SetMaxSelected(5)
    .RegexEach(@"^[^\s,]{2,24}$", "A label is 2 to 24 characters, with no spaces.")
    .BindValue(nameof(TicketController.Labels))

A SearchComponent over its own options narrows them in the browser as the menu's search does — every typed word, in any order, case and accents aside, must appear in an option's name — and a group's header goes with the last of its options. A search with an OnSearch answer narrows nothing itself: its list stands until the answer and then shows exactly what the server sent. Closed, a search is a select's field and shows the chosen option; open, its text field stands pinned at the top of the list. The term stays between openings, selected as the list opens, and a pick closes the list with the keyboard back on the field, which shows the value. With SetAllowFreeText(), a SearchComponent becomes an autocomplete field: pressing Enter in the popup search field commits the trimmed typed text (or a matching enabled option's key) into Value and closes the popup while the list suggests matching options (OnSearch or client narrowing), and picking an option writes its key into Value.

See items-view, table, tree and models for the full property and model reference.