Lists

A list presents related items as rows that people can scan, select, or open. It suits collections such as messages or search results, including those too long to fit onscreen at once.

list drives the platform’s recycling list (NSTableView / UITableView / RecyclerView / GtkListView / QListView / WinUI ItemsRepeater), so large collections get native virtualization, scroll physics, and platform behaviors. It is the one place Day’s build-once model meets cell reuse, and the resolution is the same model: a row subtree is built once per physical cell and rebound (a single slot-write into its ItemSlot) every time that cell is recycled for a new item.

Contrast with each: each builds every row eagerly under one anchor (fine for a dozen items; ten thousand would all be built up front). list builds only the rows the native widget currently shows.

The UI snippets use generated res::str accessors from an app’s Fluent catalog; see the example messages and catalog setup.

Add to your app

This control is included in day-pieces and re-exported through day::prelude::*. No additional crate or control feature is required.

Authoring

On windows-winui, ItemsRepeater and StackLayout own realization and scroll extents inside a native ScrollViewer. Its element factory reuses ItemContainer rows with Day content; it does not allocate a cell per source index. Selection, keyboard navigation, drag-and-drop, and content-sized rows follow the realized containers. A SwipeControl offers declared leading/trailing actions and guarded deletion, with the same commands in a native row context menu for mouse and keyboard use. Row content can still declare its own context menu. Action callbacks validate the row token and cell generation before use.

list-recycles-distant-rows checks that distant jumps keep a bounded number of rows alive and rebind their actions; list-releases-discarded-rows churns a list by jumps, shrinks, regrowth and reorders and checks the same bound; list-shrink-and-regrow checks emptying and repopulating a scrolled list. Run them with the other list cases using day test --project apps/conformance -t windows-winui 'list-*'.

list(source, row) and each(source, row) take a RowSource (where the rows come from) and one row builder. Two sources ship:

Plain data: an items closure and a key function, wrapped in items(…):

list(
    items(move || messages.get(), |m| m.id),
    move |row: ItemSlot<Message, u64>| {
        column((
            label(move || row.field(|m| m.sender.clone())),
            label(move || row.field(|m| m.preview.clone())),
        ))
        .id_of(move || id!(message_row, row.key()))
    },
)
.row_height(RowHeight::Automatic) // the default: each row as tall as its content
.on_select(move |key| open(key))
.id(id!(inbox))

The row builder receives an ItemSlot<T, K> (Copy handle, tracked get(), memoised field() projections). Because cells are recycled, the builder must read through the slot rather than move the item in, so a surviving cell can be fed a new &T with one write.

A day-model store (feature model; docs/model): passed directly for collection order, or through store.rows(projection) for a display order/filter expressed as a tracked key projection:

list(store.rows(model::ordered_keys), |slot: ModelSlot<Item>| {
    row((
        label(move || slot.name().read()),   // wakes only for THIS row's name
        toggle(slot.done()),                 // two-way; follows the cell across recycles
    ))
})
.on_select(|it: Elem<Item>| open(it.key()))

ModelSlot is itself a day-model Source, so the derive’s field accessors hang off it and resolve the current row on every operation; a control bound once at build keeps working as the cell recycles. The costs stay local: a field edit patches the one control showing it (the row set is unchanged, so the native reload is skipped and nothing is cloned); a change the projection reads re-runs only the projection; and a cell scrolled across the whole collection leaves no observation claims behind (day-pieces/tests/model_rows.rs measures all three).

Builder options: .row_height(RowHeight), .on_select(Fn(Ref)) (the key for a plain source, the row’s Elem for a store source), .multi_select(), .on_selection(Fn(Vec<Ref>)), .selected_rows(Fn() -> Vec<usize>), .selection(binding) (store sources, below), and (reserved, unshipped) .row_kind mapping to native reuse pools.

Asynchronous row images

Android row binding can reenter during a DayFixed measurement while the Day tree is busy. The adapter retains the cell and posts a deferred bind with a row-token/lifetime check; RecyclerView otherwise keeps the empty holder as already bound. This matters for lists first opened in a cover, before any later search or reload has occurred.

Keep the image view mounted and bind its source to the current item’s loaded image or a bundled placeholder. When a cell is rebound, cancel its previous request and associate the result with the requested URL or item key. Check that identity before displaying a result; an older request must not populate a newer row. Clear or replace the previous pixels before waiting for the network, and dispose the task with the row’s scope.

A two-axis .frame(width, height) keeps rows stable while loading. It is a measurement boundary, not a placement barrier: both image-source updates and conditional children inside it are laid out when they change, including in detached native list and tree cells. List cells parked by recycle retain their contents and pending layout dirt, but skip both width-change layout and dirty-cell sweeps. bind_row reactivates and lays them out before redisplay. Resize work therefore follows the active viewport rather than every physical cell accumulated in the native reuse pool.

Imperative scroll-to-end (chat timelines)

A chat timeline wants to stick to the newest message. Two additive builder options drive the native list’s own scroller (not a Day-side scroll view):

let follow = day_reactive::Trigger::new();
list(items(move || messages.get(), |m| m.id), row_builder)
    .scroll_to_end(follow)   // each `follow.notify()` scrolls so the last row is fully visible
    .stick_to_bottom()       // convenience: auto-scroll to end after every data reload
// … after appending a message:
follow.notify();

Sections

.sections(key, header) groups the rows under section headers. key runs with each row index when the rows change and names that row’s section. A header starts every run of rows with the same key, so sort the rows by section first. header builds the header from the slot of the section’s first row, the same slot a row builder gets.

list(items(move || articles.get(), |a: &Article| a.id), article_row)
    .sections(
        move |i| articles.with(|a| a[i].feed_id),
        |slot| label(move || slot.field(|a| a.feed_title.clone())).font(Font::Footnote),
    )

Headers are list rows of their own, drawn in the platform’s group-header style. The header of the section under the top edge stays pinned there while its rows scroll beneath it, and the next header pushes it up.

  • A header is never selected, activated or swiped, and keyboard navigation steps over it.
  • Row indices everywhere count rows only: selection reports, selected_rows, scroll_to_row, swipe offers, first_visible_row and dayscript’s select, swipe_row, reorder and delete_row.
  • A header sizes to its content, even in a Uniform list, and takes the platform’s side insets but not its vertical insets or minimum row height.
  • A row drags only within its own section, the rule UITableView apps follow for grouped tables. A header never lifts, and a drop past either end of the row’s section lands at that end, through the same retarget the reorderable guard uses. The guard sees row indices, and dayscript’s reorder keeps to the same rule. A move between sections is a change to the row’s data: update its section key, and the list regroups.
  • A sectioned list offers no native swipe-to-delete, because deleting a section’s last row takes its header with it. Swipe actions still work, and dayscript’s delete_row still drives the app’s handler.

Cap::ListSections says how a toolkit pins the header:

ToolkitHeader rowsPinned header
AppKitNSTableView group rows (tableView(_:isGroupRow:)), refused by tableView(_:shouldSelectRow:)native: floatsGroupRows
UIKitone table section per header; the header is the section’s UITableViewHeaderFooterViewnative: a plain-style table pins section headers
Androida RecyclerView view type of its own, with no click, ripple or focusemulated: a copy in the list’s overlay
GTK 4model items marked not selectable, activatable or focusableemulated: a copy in a GtkOverlay over the scrolled window
Qtmodel rows without ItemIsEnabled or ItemIsSelectable, painted as a band by the delegateemulated: a copy over the viewport
WinUIcells in a Border of their own, without the ItemContainer rows get, so they take no selection, hover or focusemulated: a copy over the ScrollContentPresenter, under the scroll bars
webcells with role="heading" that take no clicksemulated: a copy in a position: sticky wrapper
ArkUIListItems with no click, drag or swipe actionemulated: a copy stacked over the list

Where the pin is emulated, the host binds the copy through ListSource::bind_pinned. The copy carries no element ids, so a dayscript lookup of an id inside a header finds the header row in the list, never its pinned copy.

Inside day-core the host sees display rows, headers included: ListSource::is_header says which, and len, token_at, bind_row, the selection and scroll patches and the toolkit’s selection events all count headers. day-core translates between display rows and the app’s rows, so a toolkit needs no section logic beyond drawing headers and keeping them out of selection.

First visible row

.first_visible_row(Signal<usize>) receives the first actually visible row, excluding overscan and counting rows only (a header reports its section’s first row). It is opt-in and event-driven: native callbacks enqueue a deduplicated report, and the event pump updates the signal when the tree is available (a report during layout waits for the current borrow to end). AppKit, UIKit, Android, GTK, Qt, WinUI, DOM and ArkUI report scroll changes; mock exposes list_first_visible for tests. The initial index is zero; clamp it when data shrinks. For section headers that float, use .sections instead of an overlay driven by this index.

Row lifetime

A physical cell keeps its row subtree while the toolkit reuses it for different items. Read item values through the ItemSlot in reactive closures and action handlers; a value captured when the row was first built may belong to a previous item. Store persistent per-item state in the model, keyed by the item’s identity.

Leaving the viewport does not necessarily dispose a row. Toolkits may keep spare cells for reuse; a discarded cell or removed list disposes its row scope. Element IDs for recycled rows must follow the slot’s current identity. See element IDs.

A plain items closure refreshes the list when its dependencies change. Sources that supply row deltas, such as persistence queries, can apply insertions, removals, and moves directly.

Toolkit implementations

ToolkitList viewBehavior
AppKitNSTableViewNative scrolling and reusable cells.
UIKitUITableViewNative scrolling and reusable cells.
AndroidRecyclerViewNative scrolling and reusable cells.
GTKGtkListViewNative scrolling; may retain spare cells beyond the visible rows.
QtQListViewNative list interaction with a pool of Day row views.
WinUIItemsRepeaterVirtualized rows within a native scroll viewer.
ArkUIList with NodeAdapterNative scrolling and reusable cells.
WebDOM scrollerBuilds visible rows plus overscan; previously visited rows retain their elements.

Toolkit-specific selection, swipe, and reorder behavior is described with each feature below.

Row metrics

A row reads at the platform’s size without the app padding it. day-core lays each row inside the margins the toolkit’s own list gives a row and keeps it at least that list’s row height, content centered (Toolkit::list_row_metrics, asked of the list when a cell is first used), so a row piece holds only its content: row((icon, label)), not row(..).padding(..).

ToolkitMargins (top, sides)Minimum heightSource
UIKita stock cell’s top margin; the table’s layout margins at the sides (16 or 20pt)the height UIKit fits a stock cell with one line of its default content configurationmeasured from UIKit at runtime
Android8dp, 16dp56dpMaterial one-line list item
AppKit4pt, 8pt28ptmacOS table row
GTK8px, 12px44pxAdwaita rich-list row
Qt4px, 8px28pxitem view row
web10px, 16px44pxa touch-sized web row
ArkUI8vp, 12vp48vpHarmonyOS list item
WinUI0, 12px40pxListViewItem padding and MinHeight

A Uniform row height still wins: the row is that tall and its content sits inside the margins, or, where the row is too short for them, centered in the whole row.

List items

list_item(title) is a row’s standard content drawn as the platform draws its own list rows: a leading icon, the title, an optional subtitle and trailing detail, and a check mark. Every part takes a constant, a signal or a closure, and changes in place, so a recycled row follows its item.

list(scene.items.rows(keys), move |slot| {
    list_item(move || slot.name().read())
        .icon(move || slot.kind().read().icon())     // a resource/vectors glyph, as a template
        .icon_tint(move || slot.tint().read().color())
        .subtitle(move || slot.note().read())
        .detail(move || slot.count().read().to_string())
        .checked(move || slot.done().read())         // the platform's check mark, announced as selected
})

Where Cap::ListItem answers Native the toolkit realizes kinds::LIST_ITEM itself, and the row takes the platform’s fonts, icon size, spacing, secondary colors and check mark:

ToolkitRealized as
UIKitUIListContentView with the cell’s default content configuration; the checkmark accessory’s glyph and a secondary value beside it
Androida Material 3 list item (DayListItem): 24dp leading icon, body-large headline, body-medium supporting text, label-small trailing text, a primary-colored check; 56dp, 72dp with a supporting line
AppKitan image-and-text table cell’s parts: a 16pt template image, the system font, a smaller secondary subtitle, the accent checkmark; at least 28pt
GTKa row box: a 16px icon, the title over a dim caption, a dim value, object-select-symbolic in the accent color; at least 44px
Qt, web, ArkUI, WinUIcomposed from vector, label and image with the same parts

A native list item is the platform’s whole row (Flex::whole_row): the list gives it the side margins from the table above, which line up with the separators, and the item sizes its own height. A composed item, like any custom row, takes the full row metrics.

Row heights

RowHeight::Uniform(h) makes every row h points tall. Each platform has a fixed-pitch fast path for that, and content taller than h is clipped.

RowHeight::Automatic, the default, makes each row as tall as its content at the row’s width, padding included. A row grows when the reader picks a larger text size (Dynamic Type on iOS, font size on Android), when its text wraps onto another line, and when its content changes after it was first shown. Use it for any row with text in it; keep Uniform for rows whose height cannot change, such as a fixed-size thumbnail grid.

day-core measures a row when the toolkit binds it, and ListSource::cell_height answers that height as soon as bind_row returns. When day-core re-lays a bound row at a different height later, it sends ListPatch::RowSizeInvalidated { cell, height }. That patch arrives inside a layout pass, so a toolkit applies it on its next main-loop turn and never asks the source anything synchronously.

ToolkitHow a row takes its height
AppKittableView:heightOfRow: answers the height recorded for the row’s token, or the last measured height for a row not bound yet; a bound row whose drawn height differs gets an unanimated noteHeightOfRowsWithIndexesChanged. A Uniform list does not answer that selector, so it keeps NSTableView’s fixed rowHeight
UIKitself-sizing cells: UITableViewAutomaticDimension, and DayListCell answers systemLayoutSizeFittingSize:… with the row’s height at its content view’s width; a change runs an unanimated beginUpdates/endUpdates
Androidthe holder’s layout height, set after each bind
GTKDayCell measures from cell_height; a change queues a resize of the bound list item
Qtthe model answers each row’s SizeHintRole: the height Day laid it at, or for a row not measured yet the running average of the measured ones; heights are remembered per row token across reloads, and the changes of one turn land as one relayout that keeps the top row where it was
webrows stack by their measured heights; rows not built yet stand at the average
ArkUINODE_HEIGHT on the row’s list item

ArkUI’s automatic row heights are covered by list-rows-size-to-content, verified on the OpenHarmony 7.0 phone emulator.

A text size change while the app runs

day_core::note_text_size_changed() forgets every measurement Day holds and re-lays every bound row, so labels everywhere, and content-sized rows with them, take the new size. UIKit calls it after UIContentSizeCategoryDidChangeNotification, and again when a page that was off screen then (another tab) is shown with the new size in its traits. Android recreates the activity on a fontScale change, as it does for a theme or language change, and the tree is rebuilt at the new scale. The desktop and web toolkits do not report a live change yet; the new size applies from the next launch.

Selection

Rows report selection through two events: Event::SelectionChanged(row) (single) and, in multi-select mode, Event::SelectionSet(rows), the full set of selected indices on every change. .on_selection(Fn(Vec<K>)) receives the selected keys either way (a single-selection report arrives as a one-element set), so an app tracking the whole selection works on every toolkit. .selected_rows(Fn() -> Vec<usize>) reactively syncs app state back into the native selection (ListPatch::Selected; empty clears) without a selection-event echo; drive it from the same signal on_selection writes to get a two-way binding and a “clear selection” action. The binding also applies its initial value after mounting, deferred until row-source updates settle. AppKit preserves the selected tokens across content reloads and reorders; deleting a selected token clears it instead of selecting whichever item inherits its index.

A list of day-model store rows can bind single selection by key instead: .selection(binding) takes any Binding<Option<u64>> holding the selected row’s key. A row the user picks writes its key (clearing writes None) without an echo back to the native list; a key the app writes selects that row through the same ListPatch::Selected sync and scrolls it into view (list_scroll_to_row) once the row is in the snapshot, so an app that inserts a row and selects it in one turn sees it revealed after the reload that brings it. The selection follows its row through inserts, moves and reloads, and the initial key selects without scrolling. The day new starter binds its list this way (.selection(scene.selected)), with the same signal driving ContentList::detail_for (navigation).

Support matrix: AppKit (native NSTableView multi-selection), Qt and Web (the emulated lists: a per-cell press hook, a highlight treatment on the cell’s background, ctrl/cmd toggles, shift extends) honor multi_select and ListPatch::Selected. Android and ArkUI report single selection (a tap replaces, the touch idiom) but do honor ListPatch::Selected: the sync paints the visible cells (the theme accent at 20% alpha as the cell background) and newly bound cells inherit their row’s state, which is what lets the composed tree’s selection follow the canvas (docs/tree). GTK uses native GtkSingleSelection for programmatic sync, reapplying the requested row after model reloads without an event echo. Empty sync clears selection, and out-of-range rows remain unselected. The sync does not take keyboard focus. The remaining toolkits report single selection (SelectionChanged) and ignore the multi flag and the programmatic sync; the one-element on_selection contract still holds there.

AppKit separates selection from keyboard focus. .selected_rows uses native selection but never steals focus from search or other panes. Bind .focused(signal) and set the signal to true for explicit reading commands that should make the table the first responder (and therefore give its selected row the active blue highlight). The native table reports focus loss and gain back to the binding; the surrounding scroll view is not the responder.

Keyboard

A selectable list is a tab stop, and the arrow keys walk it: ↑/↓ move one row, Home and End jump to the first and last, and the row that lands is scrolled into view by the edge it left, so a held arrow scrolls a line at a time rather than recentering on every step. On a multi_select list, shift moves the far end of a range while the near end stays put, so shift+↓ ↓ ↑ grows twice and shrinks once instead of restarting from wherever the last press ended. A press reports exactly what a click on the same row reports, so on_select/on_selection need no keyboard case.

On the desktops this is the native widget’s own behavior: nothing in Day sits ahead of the responder chain, so a focused table, outline or QListView gets its arrow keys the way it always would (docs/menus). On Web there is no native list to inherit it from, so the toolkit builds it: the host carries role="listbox" and the tab stop, cells carry role="option" and aria-selected, and the shim routes the keys into day_dom_list_key. Focus sits on the host rather than a row, because rows are recycled as the list scrolls and focus parked on one would evaporate under it.

UIKit table lists recycle hidden cells in didEndDisplaying and rebind them in willDisplay, so removed rows stop answering element-id lookups and redisplayed rows regain their ids. Reloads are deferred outside the tree borrow: UIKit may retire cells synchronously inside reloadData, and recycling must be able to access Day’s tree at that point.

Programmatic scrolling

.scroll_to_end(Trigger) follows the last row (above); .scroll_to_row(Signal<Option<usize>>) jumps to any row: set the signal to Some(row) and the native list scrolls it into view, realizing it if it was virtualized away (ListPatch::ScrollToRow, clamped to the count). The signal is the row rail’s counterpart to scroll(...).scroll_target(...). Toolkits without a native scroll-to-index (GTK, web) position by uniform row pitch; prefer RowHeight::Uniform when jumping programmatically there.

A Reload whose rows are the same set in a new order (a shuffle, a programmatic sort) animates as native row moves on AppKit (moveRowAtIndex batch, the same animation a drag commit gets); other toolkits apply it instantly. A Splice from a source that reports row events animates its inserts and removals as native row changes on AppKit, UIKit (one delta at a time; a splice of several reloads) and Qt; the other toolkits and every content change reload flat.

Drag-to-reorder

list(source, row)
    .reorderable(
        Reorder::new(|from, to| { /* rotate the backing Vec + persist */ })
            .guard(|from, to| ReorderVerdict::Allow)   // optional: Deny / Retarget(i)
            .enabled(move || !busy.get()),             // optional: withhold the gesture live
    )

A list is reorderable exactly when it carries a Reorder value; the value holds the commit handler, an optional guard and an optional availability, so the feature cannot be half configured. reorderable turns on the platform’s drag mechanism; probe Cap::ListReorder for support. Reorder::new(moved) is the commit: row from landed at row to; apply the identical rotation to the backing data (let it = v.remove(from); v.insert(to, it);) and persist it if the order should survive a relaunch. It runs at the next event drain, never inside the native drop callback.

Reorder::guard vets every proposed drop synchronously, while the drag is live: the native affordance (the macOS gap, the no-drop cursor) reflects the answer before the user releases. ReorderVerdict::Deny refuses the drop (the row springs back); ReorderVerdict::Retarget(i) accepts it at a different index, the “pinned rows” pattern (the Showcase pins its first row this way). Keep the guard pure: it runs inside the platform’s drag callback, so read state and return without mutating UI. Reorder::enabled takes a constant or a reactive bool and is read when the platform asks whether a drag may begin, so an edit mode or a loading state can withhold the gesture without rebuilding the list.

The reorder half of ListSource (ListSource::reorder, present only when the list carries a Reorder) has two calls: can_move(from, proposed) -> accepted-index-or--1 for the live verdict, and move_row(from, to) for the commit, which rotates Day’s row snapshot before returning, so len/token_at/bind_row answer in the new order while the native move animates, and defers the app’s Reorder handler through the event queue. When the app’s own data change echoes back with exactly the committed token order, the piece skips the redundant Reload. When it answers with any other order, the piece reloads: a store’s own row deltas describe the change from its order before the gesture, not from the rows the gesture already moved, so they cannot be replayed. On AppKit, a deferred native reload and retile reconciles the table after the drop callback, preserving its selection and scroll position. This keeps temporary drag geometry from becoming the final document scroll extent. The reconciliation drains the app callback first and safely skips a disposed list.

The dayscript step reorder: { id, from, to } drives the same guard → commit path without a native gesture (a guard denial fails the step, non-retryably); that is how CI asserts reordering on every target.

Per-toolkit affordances:

ToolkitMechanismAffordanceGuard
AppKitNSTableView drag pipeline (pasteboard row, validateDrop/acceptDrop)the .gap placeholder opens where the drop would landlive (validate retargets/denies)
UIKitdrag delegate + moveRow/targetIndexPathForMovelong-press lift + gap, no editing modelive (target-for-move)
AndroidItemTouchHelper on the RecyclerViewlong-press lift, elevation, incremental swapslive per swap; Retarget reads as deny (the helper can’t relocate the gap)
GTK 4DragSource/DropTarget (native DnD framework)row snapshot as drag icon; forbidden cursor on deny (no insertion line yet)live (motion)
QtQDrag over the QListViewgrabbed-cell pixmap, 2px insertion line, no-drop cursorlive (drag-move)
WinUIWinRT drag events on recycled ItemContainer rowssystem drag visuals + live no-drop cursorlive (DragOver); target is the actual row, including variable heights
ArkUISetNodeDraggable + NODE_ON_DROPsystem drag preview; denied drops spring backat drop (SetDragResult)
Webpointer-tracked (emulated — no native list reorder in the browser)lifted cell + animated CSS gap, long-press on touchlive (every hovered slot)
mockMockProbe::list_can_move / list_moveop loglive

Swipe-to-delete

list(source, row)
    .deletable(
        Delete::new(|index| { /* remove from the backing Vec + persist */ })
            .label(res::str::delete())      // optional: the word on the affordance
            .guard(|index| index != 0),     // optional: protect individual rows
    )

A list is deletable exactly when it carries a Delete value: the commit handler, an optional label, an optional per-row guard and an optional .enabled(..) availability. deletable turns on the platform’s delete gesture; probe Cap::ListDelete for support. Delete::new(deleted) is the commit: row index is gone; apply the identical removal to the backing data (v.remove(index)) and persist it if the change should survive a relaunch. It runs at the next event drain, never inside the native swipe callback.

Delete::guard is consulted before the affordance is offered, not after the gesture: a row that answers false shows no delete action at all, rather than one that fails on use. Keep it pure; it runs inside the platform’s swipe callback.

Delete::label carries the app’s own word for the action; it takes the same text sources as a label (res::str::delete() directly, no .format()), resolved in the locale current when the list builds. A toolkit has no access to the app’s Fluent catalog and so cannot translate anything itself; left unset, each toolkit falls back to its platform’s wordless idiom (a trash glyph), which needs no translation.

The delete half of ListSource (ListSource::delete, present only when the list carries a Delete) has two calls: can_delete(index) -> bool for the offer, and delete_row(index) for the commit, which drops the row from Day’s snapshot before returning, so len/token_at/bind_row answer for the shorter list while the native removal animates, and defers the app’s Delete handler through the event queue; the reorder half follows the same rule.

WinUI supports deletion through SwipeControl and the row context menu. Other desktop toolkits answer Unsupported for the delete affordance: GTK and Qt have no swipe idiom at all, and macOS’s row actions (the swipe-actions section below rides them) do not carry the delete affordance yet. A list that must be editable everywhere pairs .deletable(..) with an explicit control (a menu item, a per-row button) and lets the mobile toolkits add the gesture on top.

The dayscript step delete_row: { id, row } drives the same guard → commit path without a native gesture (a guard refusal fails the step, non-retryably), which is how CI asserts deletion on every target, including the desktops, where there is no gesture to simulate.

ToolkitMechanismAffordance
UIKittrailingSwipeActionsConfigurationForRowAtIndexPathrow tracks the finger, destructive action reveals behind it, full swipe commits
AndroidItemTouchHelper swipe (START, so it is the trailing edge in RTL too)row slides to reveal a red field carrying the label; notifyItemRemoved animates the close-up
WinUISwipeControl trailing SwipeItems and MenuFlyoutreveal then press Delete; the guard is checked both when offering and invoking it
AppKit · GTK · Qt · web—Unsupported: the delete affordance does not ride macOS’s row actions yet, and the rest have no swipe idiom; use a menu item or a row button
ArkUINODE_LIST_ITEM_SWIPE_ACTION: a trailing swipe-action item on each deletable rowthe row slides to reveal the labeled action; pressing it runs the guard and commits

Swipe actions

Swipe actions generalize swipe-to-delete: app-declared buttons reveal behind a row as the user drags it aside, on either edge, with the platform’s full-swipe shortcut for the first one (Mail’s triage gestures).

list(source, row)
    .swipe_trailing(move |i| {
        let read = is_read(i);
        vec![
            swipe_action(if read { str::mark_unread() } else { str::mark_read() })
                .symbol(if read { Symbol::CircleFilled } else { Symbol::Circle })
                .tint(palette().accent)
                .action(move || set_read(i, !read)),
        ]
    })
    .swipe_leading(move |i| vec![
        swipe_action(str::delete_word())
            .destructive()
            .action(move || remove(i)),
    ])

The provider runs at gesture time, with the row index, as the row starts to slide, so the offer reflects the row’s current state (the “Mark as Read” / “Mark as Unread” flip above is why it is a closure rather than a fixed list). Keep it pure and fast: it runs inside the platform’s swipe callback. The action handlers run later, at the event drain, never inside the native gesture. When an activation drains, the provider is invoked again and the action looked up by position, so the handler always closes over the row’s current state.

symbol puts a glyph on the button where the platform draws one: above the label on macOS (Mail’s row-action look), in place of it on iOS (the label stays the accessibility name). The platforms without a glyph slot show the label alone.

Edges are semantic, not geometric: Leading follows the reading direction (left in LTR, right in RTL), exactly as every platform’s swipe API already spells it. On Apple platforms a full swipe activates the edge’s first action; WinUI uses reveal-and-press buttons. destructive takes the platform’s destructive styling (red, on the Apple toolkits); tint colors the button where the platform honors one.

Probe Cap::ListSwipeActions: Native on macOS (NSTableView’s tableView:rowActionsForRow:edge:, the two-finger Mail swipe) and iOS (UISwipeActionsConfiguration, sharing one pipeline with swipe-to-delete: on the trailing edge a deletable list offers its delete action first, then the row’s own trailing offer). It is also Native on WinUI (SwipeControl, with labels, symbols and tints), which adds a mouse/keyboard MenuFlyout for the same actions. Everywhere else the answer is Unsupported and no affordance is drawn, so pair each action with an explicit control (a menu item, a toolbar button) for the rest, as the delete section advises.

ListSource::swipe, present only when an edge is declared, carries the swipe half: actions_at(index, edge) -> Vec<ListSwipeAction> pulls the offer (label and styling; the handlers stay in the pieces layer), and perform(index, edge, action) commits an activation, deferring the app’s handler through the event queue.

The dayscript step swipe_row: { id, row, edge?, action?, label?|key? } drives the same offer → commit path without a native gesture (edge defaults to trailing, action to 0, the full-swipe button). label: (literal) or key: (a Fluent key resolved in the run’s locale) pins which button the step may press; pinning matters because offers are state-dependent. The pin is checked before the press: a mismatched offer refuses the activation and fails the step, leaving the row’s state untouched, so a stale pin (say, from an aborted earlier run’s leftover state) fails once instead of flipping state and poisoning every later run. An empty offer or an out-of-range action also fails, non-retryably. This is how a walkthrough exercises the wiring on every target, including the toolkits that show no affordance.

Editing mode

list(source, row)
    .reorderable(Reorder::new(|from, to| { /* … */ }))
    .deletable(Delete::new(|index| { /* … */ }))
    .on_activate(|row| edit(row))
    .editing(move || editing.get())   // or .editing(true) for a page that is always editing

editing puts the list in the platform’s own editing mode, the one an Edit button enters on iOS: each row the Delete offers shows the red delete control at its leading edge, each row the Reorder moves shows a grip at its trailing edge, and a tap still activates the row, so a list of things to configure can open each one from the same screen. The value is reactive; a change animates the controls in or out. The delete control commits through the same Delete::guard → handler path as the swipe, and the grip through the same Reorder::guard → handler path as a long-press drag.

Probe Cap::ListEditing. Only UIKit has a separate editing mode: on the other toolkits a list’s rows already drag, swipe, and open their menus as they are, so editing is ignored there and the list renders as it would without it. A screen that manages a list everywhere uses .editing(true) for iOS and keeps its explicit controls for the toolkits that answer Unsupported for ListDelete.

ToolkitMechanism
UIKitUITableView.setEditing(_:animated:), editingStyleForRowAtIndexPath, commitEditingStyle, allowsSelectionDuringEditing
AppKit · GTK · Qt · web · Android · ArkUI— (Unsupported; ignored)

While editing, UIKit narrows each cell’s content view for the two controls. Rows are DayListCells that report the narrower width through ListSource::layout_cell, so Day lays the row out to fit between them rather than under them.

Separators

list(source, row).separators()      // or .no_separators()

The host draws row separators, at the row boundary; row content does not. A hand-drawn hairline inside a row sits wherever the row’s own layout puts it, which is not where the native selection ends and not where the platform slides its rows: it misaligns with the selection under a uniform pitch, doubles up with iOS’s native line, and stays frozen while a swipe-action reveal slides the row past it. The host’s separator sits at the boundary, so none of those apply.

Left unset, each platform keeps its own default: iOS draws separators, the desktops don’t. .separators() forces them on, .no_separators() off (an iOS list whose rows draw their own separation turns the native line off rather than showing both).

ToolkitMechanism
AppKitgridStyleMask = solidHorizontalGridLineMask, separatorColor
UIKitthe table’s own separatorStyle (default on; false sets .none)
GTKa border-bottom on the ListView’s row CSS nodes
weba border-bottom inside each cell frame (border-box)
Qtthe delegate paints a hairline along each row’s bottom edge (the palette’s Mid, translucent)
Android · ArkUInot lowered yet — a force is ignored; rows separate by their pitch

Reorder + row-height caveat

Rows drag within their own list only; nothing is draggable out of the app. The web, GTK, Qt and ArkUI find the row under the pointer from the rows’ own heights, and AppKit, UIKit and Android use their platform’s own drag.

Selection and activation

Selection identifies the row the user is browsing. Activation performs its main action, such as opening a document or playing a station. Use separate callbacks when selecting a row should update an inspector without starting that action:

list(stations, station_row)
    .on_select(move |station| selected.set(Some(station)))
    .on_activate(move |station| player.play(station));

Desktop lists activate on double-click or Enter; Qt follows the platform’s activation preference. UIKit, Android, and ArkUI activate on a tap. The browser uses double-click or Enter for a mouse and a single tap for touch. Arrow-key selection and programmatic selection do not activate rows. on_activate receives the row’s key or model reference from the current list snapshot, so reordering does not leave it pointing to an old index. An explicit button within a row can offer the same action separately.

At the toolkit boundary, Event::ListActivated(index) carries the current zero-based row index. It is independent of SelectionChanged and SelectionSet; no selection change is required when the user activates an already selected row.

Dayscript keeps the two operations separate:

- select: { id: stations, index: 0 }
- activate: { id: stations, index: 0 }

activate invokes the row without changing selection. An out-of-range index is ignored. Recordings preserve activation even when the row was already selected.

AppKit plain labels inside selected native rows use the system selected text color at paint time, including inactive-window selection. Their normal colors are preserved for reuse and deselection; explicitly attributed text retains its authored run styling.