@zeyos/zx 5.0.0 → 5.2.0

package/docs/llms.md

@@ -61,7 +61,10 @@ Themes: `light` | `dark` | `auto` (follows OS).
 (`--zx-space-unit`, 4px: `--zx-space-1…8` = 4/8/12/16/20/24/32/40px), radius steps are fractions of
 one base (`--zx-radius`, 4px: `-sm/-md/-lg/-xl` = 2/3/4/6px; `-full` only for shapes whose roundness
 is the meaning — badges, avatars, toggles), and controls are `--zx-control-height` (30px) tall.
-To tighten or loosen an application, override those tokens on `:root` or on any region:
+To tighten or loosen an application, override those tokens on `:root` or on any region. The
+geometry and material tokens (control size, radius, spacing, blur and glass filters, durations,
+easings, the type scale) are declared on `:root` only, never on a `[data-zx-theme]` block, so an
+override on `:root` reaches nested light and dark regions alike; theme blocks carry colours only:
 
 ```css
 :root { --zx-space-unit: 3.5px; --zx-control-height: 28px; }
@@ -114,7 +117,9 @@ accent), `--zx-color-bg-chrome` (navigation and inspector columns, one tone off
 `--zx-color-on-accent-solid` (the one filled primary button per screen),
 `--zx-color-danger/warning/success/info(+ -bg)`, the categorical tone palette
 `--zx-color-tone-{blue,teal,green,amber,orange,red,pink,violet,slate}-bg/-fg` (tags, chips, icon
-tiles, avatars — neither the accent nor a status), the chart series `--zx-color-chart-1…8`,
+tiles, avatars — neither the accent nor a status) and `-solid` (a solid identity fill, such as a
+module tile, that the white icon glyph reads on at 3:1 in both themes), the chart series
+`--zx-color-chart-1…8`,
 `--zx-focus-ring`, `--zx-control-height/-radius`, `--zx-space-*`, `--zx-radius-*`, `--zx-text-*`
 (`-3xl` for document titles), `--zx-weight-medium/-semibold`, `--zx-tracking-tight/-title`. Never
 use tier-1 palette tokens (`--zx-gray-*`, `--zx-green-*`, `--zx-emerald-*`, `--zx-tone-*`) or raw
@@ -220,12 +225,20 @@ await records.saveView({ name: 'My open invoices', setDefault: true });
   behavior. `load` maps stored timestamps to `Date`; `save` validates and creates/updates, maps back
   to Unix seconds, calls `onSaved`, and shows a success toast. Its toasts (that confirmation and a
   failed request's report) appear in the theme scope of `scope` — default: the form's own element,
-  so a form in a scoped dialog toasts inside that scope; `notify: false` raises none, leaving the
+  so a form in a scoped dialog toasts inside that scope, and the confirmation stays there when
+  `onSaved` closes and destroys the dialog; `notify: false` raises none, leaving the
   promise's result or rejection to the caller.
 - `zeyosTable(client, resource, opts)` returns
-  `{table, load(), setSearch(), setFilters(), loadMore(), count, page, hasMore, destroy()}`. Columns
-  come from schema metadata, sorting uses `sortMode:'server'`, and page zero replaces rows while
-  later pages append them using server `limit`/`offset` and `count`. Table presentation options and
+  `{table, load(), setSearch(), setFilters(), loadMore(), count, page, pageSize, hasMore, destroy()}`.
+  Columns come from schema metadata, sorting uses `sortMode:'server'`, and paging is zero-based with
+  `pageSize: 50` by default: page zero replaces rows while later pages append them using server
+  `limit`/`offset` and `count`; `load({page, pageSize, replace: true})` replaces at any page. A
+  one-based `Pagination` maps onto it as `load({page: detail.page - 1, pageSize: detail.pageSize,
+  replace: true})` (offset `(page - 1) * pageSize`), feeding `result.count` back through
+  `setTotal()`. A response that resolves after `destroy()` is ignored and later loads reject; page
+  must be a non-negative integer and page size a positive integer (`RangeError`), filters an object
+  (`TypeError`), and every argument is checked before any is applied, so a rejected call changes
+  nothing. Table presentation options and
   listeners pass through — `variant`, `zebra`, `stickyHeader`, `responsive`, `growing`, `emptyText`,
   `rowClass`, `rowKind(s)`, `columnVisibility`, `columnReorder`, `hiddenColumns`, `on<event>`;
   `onrowclick` runs beside `onRowClick`. The binding owns `columns`, `data`, and `sortMode`, and
@@ -234,7 +247,8 @@ await records.saveView({ name: 'My open invoices', setDefault: true });
   complete projection, and view options. `zeyosView(client, resource, CardView|TableView|KanbanView,
   opts)` returns `{view, load(), setSearch(), setFilters(), loadMore(), count, page, hasMore,
   savedViews, ready, restoreDefault(), captureView(), saveView(), applyView(), destroy()}` with
-  paging and server sort. Title, preview, group, column, and swim-lane fields stay in the projection
+  paging and server sort. Paging is the same loader as `zeyosTable()` — same `pageSize: 50` default,
+  validation, `replace`/`pageSize` load options, and destroy guard. Title, preview, group, column, and swim-lane fields stay in the projection
   even when hidden. Without `savedViews`, the host may persist `view.getViewState()` directly.
 - `createSavedViewRegistry(transport, {userId,workspaceId,resource})` coordinates private named
   Table/Card/Kanban configurations as one versioned, atomically replaced document. Entries capture
@@ -264,8 +278,10 @@ instance's zone — a day, not an instant: tables show it with no time, and form
 so neither the viewer's zone nor daylight saving moves it. Pass the instance's IANA zone as
 `timeZone` (table, form, view; default: the runtime's own); `unixSecondsToCalendarDay(seconds, tz)`
 and `calendarDayToUnixSeconds(date, tz)` do the same conversion for application code. Use
-`dataFilterStateToFilters(state, defs)` before `tableBinding.setFilters(...)` when wiring a
-`DataFilter`.
+`dataFilterStateToFilters(state, defs, {timeZone})` before `tableBinding.setFilters(...)` when wiring
+a `DataFilter`: with `timeZone`, a `format: 'date'` value (`Date` or `YYYY-MM-DD`) becomes that
+day's midnight in the zone, as forms store it, while `datetime` values stay instants; without it,
+dates convert as exact instants. `FilterPanel` takes the same `timeZone` option.
 
 ### Module icons and colours
 
@@ -303,6 +319,41 @@ registerModules({ tickets: '#f04639', 'my-fork': { label: 'My Fork', icon: 'zeyo
   throw.
 - `registerModules(map)` adds forks and weblets or overrides shipped entries (a bare string sets
   the colour only). Runtime ZeyOS menu data is authoritative: feed its colours in at startup.
+
+### Module bar from the ZeyOS menu
+
+The module bar and the module-layout sidebar read the same shell state the launcher does, plus
+each module's menu and its counts:
+
+```js
+import { buildZeyosAppSidebarConfig, buildZeyosModuleBarConfig } from '/assets/zx-zeyos.esm.js';
+import { AppSidebar, ModuleBar } from '/assets/zx.esm.js';
+
+const state = {
+  modules: ['messages', 'tasks', 'billing', 'contacts', 'calendar', 'tickets'],
+  pinned: ['messages', 'tasks', 'billing', 'tickets'],     // the rest are under "All modules"
+  activeIdentifier: 'tickets',
+  active: 'tickets-mine',                                     // a menu entry, when more precise
+  canUseModule: (module) => permissions.has(module),
+  menus: { tickets: [{ id: 'tickets-mine', label: 'My tickets' }, ['tickets-all', 'All tickets', '#tickets']] },
+  badges: { messages: 7, 'tickets-mine': 3 },
+  resolveApplication: (app) => ({ href: routeFor(app) })
+};
+new AppSidebar(nav, buildZeyosAppSidebarConfig(state, { onselect: route }));
+new ModuleBar(header, buildZeyosModuleBarConfig(state, { orientation: 'horizontal', side: 'top' }));
+```
+
+- `zeyosModuleItems(state, {standardIcons})` → `ModuleItem[]`: every permitted module, fork, and
+  weblet, with its kit icon (or `renderApplicationIcon(app, normalized)`), its colour — the
+  payload's, else the registry's, so `registerModules()` reaches the bar — its menu from
+  `menus[identifier]` (objects or `[id, label, href]` arrays, sections, nesting; unsafe hrefs are
+  disabled), its badge from `badges`, `pinned` from the pinned order, and forks and weblets in
+  their own catalogue group (`labels.forks`, `labels.weblets`). A module with a menu is a panel
+  module; one without is a destination.
+- `buildZeyosModuleBarConfig(state, options)` → ModuleBar options; `buildZeyosAppSidebarConfig()`
+  → AppSidebar options in `layout: 'modules'`. Both draw the classic ZeyOS identity tiles
+  (`appearance: 'solid'`) unless told otherwise. `zeyosModuleBar(target, state, options)` creates
+  the bar directly.
 <!-- /doc -->
 
 ## Custom elements
@@ -384,8 +435,10 @@ a `MenuButton`, where choosing one activates the original control.
   `setActive(name, active?)`, `destroy()`.
 - **Events** — `action {name, item}`, emitted for descriptor-built items in addition to their own
   `onclick`, from the row and from the overflow menu alike.
-- **Keyboard** — Tab reaches the toolbar once; ArrowLeft/ArrowRight move between controls and wrap;
-  Home/End jump to the first and last control.
+- **Keyboard** — Tab reaches the toolbar once; ArrowLeft/ArrowRight move between controls and wrap,
+  in visual order under `dir="rtl"`; Home/End jump to the first and last control. A text field, select,
+  or contenteditable item keeps its own keys: Home/End and the arrows move its caret, and an arrow
+  moves on to the neighbouring control only once the caret is at that edge of the text.
 - **Pressed items** — an item with `active` renders `aria-pressed="true"` and takes the neutral
   `--zx-color-bg-current` fill, never the accent.
 <!-- /doc -->
@@ -524,7 +577,9 @@ Zx owns ranking, focus, request cancellation, and presentation; ZeyOS owns the c
 permissions, recent-history/cache policy, and the route or command ultimately invoked.
 
 - **Constructor** — `new Launcher(null, options)` owns a top-layer dialog in the opener's nearest
-  Zx theme scope;
+  Zx theme scope — never inside another open dialog, which it stacks above in the top layer. Open,
+  it is a modal on the shared overlay stack: Esc and presses inside it reach no popup left open
+  behind it, and toasts move into it while it is open;
   `new Launcher(existingDialog, options)` enhances and later restores an existing `<dialog>`.
 - **Options** — `items`, abortable `sources: [{id, label?, minQuery?, when?, order?, load(query, {signal})}]`,
   `query`, `debounce: 250`, `minQuery: 0`, `maxResults: 100`, `placeholder`, `label`, `emptyText`,
@@ -584,7 +639,9 @@ A fixed-size, product-agnostic application identity. It keeps glyph geometry sta
 sidebars, entity results, and recent-item rows while identity colour and material remain explicit
 options rather than application globals.
 
-- **Options** — `icon` (bundled name, Node, or lazy renderer), `color`, `size: 36`,
+- **Options** — `icon` (bundled name, Node, or lazy renderer), `color` (any CSS colour) or `tone`
+  (one of the nine categorical tones, drawn with its `--zx-color-tone-<tone>-solid` fill; `color`
+  wins when both are given), `size: 36`,
   `iconSize: '52%'`, `label`, `badge`, `selected: false`, `shape: 'tile'|'circle'`,
   `glass: false|'subtle'|'strong'`, and
   additional `class` names.
@@ -697,6 +754,11 @@ Explicit duplicate file IDs are rejected; source order is preserved.
 - **Events** — cancelable `activate {id,index,file,href,event}` and
   `action {id,fileId,index,action,file,event}`, plus `datachange {items}` after a collection
   mutation. Returned items are defensive snapshots.
+- **Updates in place** — mutations are reconciled by file `id`: unchanged rows are left alone and a
+  changed one is updated through `FileItem.set()`, so upload progress can tick through
+  `updateItem(id, {progress})` while focus (say, on that file's Cancel action) and the scroll
+  position stay put. Removing the focused file moves focus to the file that takes its place. Files
+  without an `id` are rebuilt on every mutation.
 <!-- /doc -->
 
 <!-- doc:activity-item -->
@@ -738,6 +800,9 @@ whether a feed is newest- or oldest-first.
   `updateItem(id,values,{silent?})`, `removeItem(id,{silent?})`, `setLoading()`, and `destroy()`.
 - **Events** — `datachange {items}` after mutation. Each child's cancelable `zx-action` bubbles
   naturally through the list for delegated application handling.
+- **Focus** — entries are regrouped on every mutation; focus on an entry's control returns to the
+  same control of the same activity (matched by `id`, else position), so a feed prepending live
+  entries does not drop the reader to `<body>`.
 - **Grouping** — groups keep first-seen group order and item source order. The exported pure
   `groupActivityItems()` and `normalizeActivityItems()` helpers do not mutate caller arrays.
 <!-- /doc -->
@@ -751,7 +816,9 @@ out, or mutates the session.
 
 - **Options** — `account: {name, secondary, src?, initials?, status?, statusLabel?}`, `items`,
   `compact: false`, `label`, and any top/bottom/left/right `placement`.
-- **Methods** — `open()`, `close()`, `toggle()`, `isOpen()`, `setAccount()`, `setItems()`, `focus()`,
+- **Methods** — `open()`, `close()`, `toggle()`, `isOpen()`, `setAccount()`, `setItems()`,
+  `setCompact(compact)` (the avatar alone, or with the name and secondary line — for a navigation
+  column that narrows and widens), `focus()`,
   `getPanel()`, `destroy()`.
 - **Events** — cancelable `select {value, item}`, `open`, and `close`. A canceled selection does
   not run the item's callback and leaves the menu open, so an application can reject or confirm an
@@ -763,6 +830,47 @@ out, or mutates the session.
   would give it, whatever order the stylesheets load in.
 <!-- /doc -->
 
+<!-- doc:workspace-switcher -->
+### WorkspaceSwitcher
+
+Composes `AppIcon` and `MenuButton` into the workspace switcher at the head of a navigation column:
+a trigger with the current workspace's tile, name and secondary line, opening an APG menu of the
+workspaces with the current one checked, then the application's own actions. Zx never decides
+which workspaces a user may see, loads another workspace, or changes the session — switching is a
+cancelable event the application acts on.
+
+- **Options** — `workspaces: [{id, label, secondary?, icon?, tone?, color?, src?, initials?, badge?,
+  disabled?}]` (the tile is the image, else the icon, else the initial, on the tone — derived from
+  the label when neither `tone` nor `color` is given), `active` (defaults to the first enabled
+  workspace, which also replaces an id that is not listed or is disabled), `items` (actions after
+  the workspaces; the separator between them is added for you), `compact: false`, `heading` (null
+  resolves message `workspaceSwitcher.heading`, "Workspaces"; `''` leaves it out), `label` (`%1` is
+  the active workspace's name, filled in again after every switch; null resolves
+  `workspaceSwitcher.label`, "Switch workspace: %1", or `workspaceSwitcher.labelEmpty`, "Switch
+  workspace", while no workspace is active), and any `placement` (default `bottom-start`).
+- **Messages** — `workspaceSwitcher.heading`, `workspaceSwitcher.label` (`%1` the workspace name),
+  `workspaceSwitcher.labelEmpty`; override them per instance through `msg`, or for every instance
+  through `setTranslator()`.
+- **Methods** — `getActive()`, `setActive(id, {silent = true})` (`silent: false` emits `select`
+  first), `setWorkspaces(list)` (keeps the active workspace while it is still listed and enabled,
+  else the first enabled one becomes active), `setItems()`,
+  `setCompact(compact)`, `open()`, `close()`, `toggle()`, `isOpen()`, `focus()`, `getPanel()`,
+  `destroy()`.
+- **Events** — cancelable `select {workspace, id, previous}`: a canceled switch keeps the previous
+  workspace active and the menu open. Cancelable `action {value, item}` for the extra items: a
+  canceled action does not run the item's callback. Both honour `preventDefault()` on the component
+  event and on the bubbling `zx-select` / `zx-action` DOM event alike. `open` and `close`. Choosing the current
+  workspace again only closes the menu.
+- **Semantics** — one native `<button aria-haspopup="menu" aria-expanded>` trigger, named "Switch
+  workspace: <name>" (or the custom `label`) in both states; compact mode shows the tile alone and adds the name as its
+  `title`. Workspaces are `menuitemradio` rows with `aria-checked` under a presentational heading;
+  MenuButton keeps focus return, typeahead and the arrow-key map.
+- **Appearance** — the trigger is a flat full-width row (tile, name, secondary line, chevron) with
+  the hover fill, at least a control and a space-2 tall; its tile is the module bar's tile size, so
+  as an `AppSidebar` `railHeader` it lines up with the module tiles under it. Keep it in step with a
+  modules sidebar by calling `setCompact(presentation !== 'expanded')` on `presentationchange`.
+<!-- /doc -->
+
 <!-- doc:select -->
 ### Select — APG editable combobox
 
@@ -775,8 +883,9 @@ Unifies single-select, local filtering, and async loading.
   `clearable: false`, `filter: false | 'local' | async (query)=>items`, `searchKeys`,
   `minQuery: 0`, `debounce: 200`, `listHeight: 280`, `groupKey`.
 - **Getters** — `.value`, `.selected`.
-- **Methods** — `set(id, {silent})`, `setItems()`, `setFixedItems()`, `setActions()`, `reset()`,
-  `open()`/`close()`, `enable()`/`disable()`, `focus()`.
+- **Methods** — `get()` (the same as `.value`), `set(id, {silent})`, `setItems()`,
+  `setFixedItems()`, `setActions()`, `reset()`, `open()`/`close()`, `enable()`/`disable()`,
+  `focus()`.
 - **Events** — `change {value, item}` (`item` is null on clear), preventable
   `action {id, action, query, select}`, `open`, `close`, `query {query}`, `loaded {items}`.
 - **Fixed choices** — `fixedItems` pins entries to the top of the list, separated by a rule (the
@@ -1072,7 +1181,10 @@ messages rather than the page, and uses the translucent glass surface tokens wit
   when its last toast closes. One whose host was emptied or left the document is replaced on the
   next toast rather than reused, and a scope that is itself detached falls back to the focused
   element's scope. `Message.disposeRegion(scope)` → boolean removes a scope's region at once,
-  toasts and all, for a host torn down while toasts are still showing.
+  toasts and all, for a host torn down while toasts are still showing. While a modal Dialog or
+  Sheet is open the region moves into the topmost one, so toasts and their actions stay visible
+  and clickable above it, and moves back when it closes. A press on a toast dismisses no open menu
+  or drawer.
 - **Per-message options** — `kind: 'info'`, `timeout`, `closable: true`, `maxVisible: 5` (extras
   queue, and hovering pauses dismissal).
 - **Action** — `action: { label, onclick?, kind? }` renders one small button (`.zx-btn`,
@@ -1154,7 +1266,16 @@ When a Dock adopts it, the Sheet becomes an opaque layout surface instead.
   the browser through `showModal()`. Floating `'trap-focus'` and `false` sheets use a manual
   Popover top layer, so they stay viewport-anchored even inside a transformed or clipped theme
   scope while the page keeps scrolling and stays interactive. Escape and outside-click are
-  re-implemented, and `'trap-focus'` adds `focusTrap()` on top. Their top-layer backdrop is
+  re-implemented through the overlay stack, and `'trap-focus'` adds `focusTrap()` on top: Esc
+  closes the sheet when focus is in it (or in a popup it opened) and no popup above it takes the
+  key first, an Esc already handled inside (`defaultPrevented`) is ignored, and a press inside a
+  menu or dropdown anchored in the sheet counts as inside the sheet. Closing the sheet closes the
+  popups it opened. Light dismiss stops at the first layer that contains the press: a press inside
+  the upper of two light-dismiss sheets (or inside any overlay above this one) closes neither the
+  lower sheet nor anything beneath it; a press outside every layer closes each one that
+  light-dismisses. A floating non-modal sheet opened from inside a modal Dialog is hosted by that
+  dialog while open, so it stays usable above it, closes when the dialog closes, and goes back to
+  its theme scope when it closes. Their top-layer backdrop is
   explicitly transparent and non-filtering; `backdrop` is meaningful only when `modal` is `true`.
   A docked Sheet remains a native non-modal dialog in its Dock's flow.
 - **Resizing and detents** — `resizable` makes the inner edge draggable between `min` and `max`.
@@ -1240,7 +1361,25 @@ DOM child of the anchor's nearest Zx theme scope while the browser lifts it into
 - **Hosting** — the host is resolved again on every `open()`. A dropdown created before its anchor
   is in the document keeps its panel detached until the first open instead of parking it on
   `<body>`, so an anchor inserted into a `[data-zx-theme]` region or a `.zx-scope` afterwards still
-  gets its theme. Tooltip, MenuButton, and ContextMenu panels follow the same rule.
+  gets its theme. Tooltip, MenuButton, and ContextMenu panels follow the same rule. While open, a
+  panel whose anchor sits in an open `<dialog>` (a modal Dialog or Sheet, a focus-trapping or
+  non-modal Sheet) is hosted by that dialog instead, so `showModal()` does not make it inert and a
+  focus trap still reaches it; it returns to the theme scope when it closes.
+- **Overlay stack** — an open panel is one entry on the shared overlay stack
+  (`src/core/overlay-stack.js`). Esc closes only the topmost layer that takes it, and an Esc that
+  something inside already handled (`defaultPrevented`) closes nothing. A press outside the panel
+  and every overlay opened from it closes it; a press on the anchor does not. Light dismiss stops
+  at the first layer that contains the press, so a press inside an overlay above the panel (one
+  not opened from it) leaves the panel open; nothing below an open modal reacts at all. A panel
+  opened from inside another overlay closes with that overlay.
+- **Keyboard** — the panel follows its trigger in the Tab order: Tab on the anchor of an open panel
+  moves to the panel's first Tab stop, or onto the panel itself when it has a `tabindex`; Tab past
+  the last stop continues with whatever follows the anchor; Shift+Tab from the first
+  stop returns to the anchor. A Tab stop is what the browser itself stops at: a `tabindex="-1"` part
+  of a composite (a Select's toggle), a roving toolbar's inactive items, disabled, hidden and inert
+  controls, and all but one radio of a group are not. A panel with no Tab stop is skipped. Esc and `close()` with
+  focus inside return focus to the anchor. Opening moves no focus — give the panel `role` and
+  `aria-*` semantics yourself if it is more than a disclosure.
 - **Methods** — `open()`, `close()`, `toggle()`, `isOpen()`, `setContent()`, `getPanel()`.
 - **Events** — `open`, `close`.
 <!-- /doc -->
@@ -1260,8 +1399,16 @@ A button that opens a `role="menu"`.
     default.
   - `role: 'menuitemcheckbox'|'menuitemradio'` with `checked` exposes an APG checked action. The
     application owns state changes and calls `setItems()` with the new model.
-- **Methods** — `setItems()`, `open({returnFocus})`, `close()`, `setLabel()`, `getTrigger()`,
-  `getPanel()`, `focusFirst({returnFocus})`, `focusLast({returnFocus})`.
+  - `{type: 'choice', label, value, options: [{value, label, icon|glyph}], onselect(value, entry,
+    menu)}` draws a setting chosen in place — a theme, a layout: the label, then a small segmented
+    group of `menuitemradio` options named by it. Choosing an option checks it and calls
+    `onselect`; the menu stays open so the change shows, and `select` does not fire. Left and Right
+    move within the row; Up and Down leave it, landing on another row's checked option.
+    `AccountMenu` takes the same entries; `ContextMenu`, which closes on every activation, leaves
+    them out.
+- **Methods** — `setItems()`, `open({returnFocus})`, `close()`, `toggle()` (opens when closed,
+  closes when open, moves no focus), `isOpen()`, `setLabel()`, `getTrigger()`, `getPanel()`,
+  `focusFirst({returnFocus})`, `focusLast({returnFocus})`.
 - **Events** — `select {value, item}`, `open`, `close`.
 - **Focus return** — choosing an item closes the menu and returns focus to the trigger before the
   `select` event and the item's `onselect` run, so a dialog they open returns to the trigger when
@@ -1273,7 +1420,9 @@ A button that opens a `role="menu"`.
   leaves the menu open with focus back on the item, which is the composition seam used by
   `AccountMenu` and rail flyouts.
 - **Keyboard** — ArrowDown/Enter/Space open and focus the first item; ArrowUp opens and focuses the
-  last; arrows cycle; Home/End; typeahead; Enter/Space select; Esc/Tab close.
+  last; arrows cycle; Home/End; typeahead; Enter/Space select; Esc/Tab close. Esc reaches the menu
+  through the overlay stack, so inside a Sheet or Dialog it closes the menu and leaves the sheet
+  open; a menu opened inside a modal Dialog is hosted by it and stays usable.
 - **Appearance** — the highlighted item is a neutral step, a checked item keeps its accent check
   mark, and section headings are sentence-case captions. ContextMenu shares the same rules.
 <!-- /doc -->
@@ -1321,7 +1470,7 @@ A description bubble anchored to another element. The panel is a manual popover
   at all and leaves everything to the methods), `disabled` (false).
 - **Methods** — `show()`, `hide()`, `toggle()`, `isOpen()`, `setContent(content)`, `enable()`, `disable()`, `isDisabled()`, `getAnchor()`, `destroy()`. Convenience factories: `tooltip(anchor, contentOrOptions)` takes either a content value or a full option object, and `describe(anchor, text)` is the one-liner replacement for a `title` attribute. Both return the instance.
 - **Events** — `open`, `close`. Both fire only on a real transition, so a `show()` on an open tooltip is silent.
-- **Keyboard** — Focusing the anchor opens the tooltip at once; moving focus away closes it. `Escape` closes it without moving focus, satisfying WCAG 1.4.13. A `pointerdown` anywhere closes it, and focus that arrives with a click does not re-open it.
+- **Keyboard** — Focusing the anchor opens the tooltip at once; moving focus away closes it. `Escape` closes it without moving focus (WCAG 1.4.13 "dismissible") — and only it, when it is the topmost open overlay, so one press never closes a tooltip and the menu beneath it. A `pointerdown` anywhere closes it, and focus that arrives with a click does not re-open it. A closed tooltip listens to nothing outside its anchor; an open one is an entry on the shared overlay stack.
 <!-- /doc -->
 
 <!-- doc:split-view -->
@@ -1356,9 +1505,9 @@ range select.
   render?: (row,i)=>Node|string, sortValue?, headerTitle? }]`, `data`, `rowId: 'ID'`,
   `sort: { id, dir }`, `sortMode: 'local'|'server'`, `selectable: false|'single'|'multi'`,
   `stickyHeader: true`, `height`, `emptyText`, `rowClass`, `zebra: true`, `variant:
-  'default'|'plain'`, and `hierarchy: false|{parentId, column?, expanded?}`. Locale, currency,
-  unit, and decimals may be row callbacks; values remain numbers in row data while display
-  formatting is locale-aware.
+  'default'|'plain'`, `hierarchy: false|{parentId, column?, expanded?}`, `interactive: false`,
+  and `label`/`labelledBy`. Locale, currency, unit, and decimals may be row callbacks; values
+  remain numbers in row data while display formatting is locale-aware.
 - **Appearance** — the header sits on the table's surface (no band) in the muted text colour at a
   medium weight, sentence case; the sorted column's label takes the text colour beside its arrow.
   Rows are divided by `--zx-color-border-subtle`, the header by the ordinary border, and every cell
@@ -1379,6 +1528,44 @@ range select.
   top bar, sets `aria-busy`, and is cleared by the next `setData`).
 - **Events** — `rowclick {row, id, index, event}`, `rowdblclick`, `sort {id, dir}`,
   `selectionchange {rows, ids}`, `datachange {rows}`, and `rowtoggle {row, id, expanded}`.
+  `rowclick` fires for Enter on a focused row as well as for a click; `event` is then the keydown.
+- **Keyboard** — an *interactive* table implements the WAI-ARIA APG **Grid** pattern
+  (`role="grid"`, with `aria-multiselectable` for `selectable: 'multi'`), or the **Treegrid**
+  pattern with `hierarchy`. A table is interactive when it is `selectable`, has `editMode` or
+  `hierarchy`, sets `interactive: true`, or has a `rowclick`/`rowdblclick` listener attached through
+  `on()` or an `onrowclick`/`onrowdblclick` option (attaching one later turns the grid on). A host
+  that listens only for the bubbling `zx-rowclick` DOM event passes `interactive: true`. TableView
+  always bridges `rowclick` to `recordclick`, so its table is always a grid. Any other table keeps
+  plain `<table>` semantics, no grid role, no name unless `label` is given, and no row Tab stop.
+  In a grid the rows are one Tab stop with a roving `tabindex`; the row checkboxes and disclosure
+  buttons leave the Tab order because the row keys cover them (links and buttons a host renders
+  in cells keep theirs). Focus is on rows by default and on cells when `editMode` is set —
+  reflected as `data-focus="row"|"cell"` on the root. ArrowUp/ArrowDown move a row,
+  ArrowLeft/ArrowRight a cell (cell focus), Home/End go to the first/last row (cell focus:
+  first/last cell of the row) and Ctrl+Home/End to the first/last row's corner cell,
+  PageUp/PageDown move by the rows visible in the scroll region (10 when the table does not scroll
+  itself). Enter activates exactly like a click (`rowclick`; selects in `single`), Enter/F2 on an
+  editable cell opens its editor, Space toggles the row's selection when `selectable` (activates
+  otherwise), Shift+ArrowUp/Down extends a `multi` selection from its anchor, and Ctrl/Cmd+A
+  selects the rows in the DOM — like the header checkbox, not the rows `growing` holds back nor the
+  children of collapsed branches. A sort, new data, or a change in expansion starts the anchor
+  over. Treegrid: ArrowRight expands a collapsed row, then moves into its first child; ArrowLeft
+  collapses an expanded row, then moves to its parent. With cell focus, ArrowLeft from the first
+  cell lands on the row and ArrowRight from the row goes back to its first cell. The focused row
+  (and column) is kept by id across `setData`, sorting, expansion, growing, and `updateRow`; when
+  a collapsed ancestor hides it, the ancestor takes focus, and when it is gone, its neighbour does.
+  Focus is only restored when the body had it, and without scrolling, so a polling refresh never
+  pulls the page back to the table. An emptied table keeps focus on its frame until rows return.
+  Column headers keep their sort buttons in the Tab order rather than joining arrow navigation —
+  the one deliberate departure from the APG grid, which puts the header row inside it. Rows and
+  cells show an inset `--zx-focus-ring` with a transparent outline that forced colours paint.
+- **Naming** — `label` or `labelledBy` (an element id) names the table; a grid without either is
+  named by the `table.label` message (English "Table"), so pass a real name. Row controls are named
+  after the row's first cell with text through `table.selectRow` (`Select %1`), `table.expandRow`,
+  `table.collapseRow`, and `table.moveRow`; `table.row` (`row %1`) stands in for a row without
+  text, and `table.selectAll` names the header checkbox. Sort buttons and selection checkboxes are
+  at least 24×24 px targets; the checkbox is drawn so the glyph stays `--zx-space-4` while a
+  transparent border makes up the target.
 - **Hierarchy** — flat parent references are projected as an ARIA `treegrid`; `getData()` and all
   editing/mutation APIs stay flat and ID-based. Orphans become roots, cycles render once, local
   sort reorders siblings without mixing levels, and growing counts visible rows. Use
@@ -1470,7 +1657,16 @@ range select.
 `{label, target}` object names the chooser's trigger and mounts the disclosure into a host
 element — a list toolbar, say — instead of the view's own. `label` omitted resolves
 `recordView.fields`. This is what lets a translated application use the chooser at all: the
-trigger used to be the literal `Fields`, with no way to change it or move it.
+trigger used to be the literal `Fields`, with no way to change it or move it. `TableView`,
+`CardView`, and `KanbanView` all honour `target`.
+
+**The chooser is public.** `getFieldControls()` returns the view's field chooser — the shared
+disclosure, or for a `TableView` with `fieldControls: true` its Table's column chooser — and
+`mountFieldControls(target)` moves it into a host element (`null` hands it back). The view keeps
+owning it wherever it sits and removes it on `destroy()`; `ListToolbar.bind()` uses exactly this.
+In the shared chooser the move buttons keep focus on the field they moved (or its other button once
+one end disables), a polite live region announces "Name moved to position 2 of 5"
+(`recordView.fieldMoved`), and Escape closes the disclosure and returns focus to its trigger.
 
 `TableView` is the record-oriented entry point above the lower-level `Table`. It extends
 `RecordView` and composes one complete `Table`, so editing, hierarchy, growing, row movement,
@@ -1484,7 +1680,8 @@ responsive stacking, loading, and advanced table events remain available through
   `fieldControls: true`, and `emptyText`. At least one field remains visible.
 - **Shared methods** — `setData()`, `addData()`, `updateRecord()`, `removeRecord()`, `getRecord()`,
   `getData()`, field getters/order/visibility methods, `setSort()`/`getSort()`, selection methods,
-  `setLoading()`, `getViewState()`, and `setViewState()`.
+  `setLoading()`, `getViewState()`, `setViewState()`, `getFieldControls()`, and
+  `mountFieldControls(target)`.
 - **Portable state** — `{version:1,fieldOrder,hiddenFields,sort}` is JSON-safe configuration only.
   Records, selection, DOM nodes, rendered values, and callbacks are never serialized. A state from
   one record view may seed another; unknown fields are ignored and new fields append.
@@ -1503,7 +1700,15 @@ portable state as TableView and KanbanView.
 
 - **Options** — the shared RecordView options plus `titleField`, `subtitleField`, `preview`,
   `previewAlt`, `link`, `actions`, `groupBy`, `groupOrder`, `minCardWidth`, `maxColumns`,
-  `variant: 'outlined'|'raised'|'filled'`, `loadingCount`, `headingLevel`, and `label`.
+  `variant: 'outlined'|'raised'|'filled'`, `loadingCount`, `headingLevel`, and `label` (null
+  resolves message `cardView.label`, "Card view").
+- **Messages** — `cardView.label`, `cardView.sort`, `cardView.sortCards`, `cardView.unsorted`,
+  `cardView.sortAscending`/`cardView.sortDescending` (`%1` the field), `cardView.ungrouped`
+  ("Ungrouped"), `cardView.groupEmpty` ("No records in this group."), `table.empty` for the empty
+  collection ("No records", shared with Table), and the card's own `recordCard.select`,
+  `recordCard.actions` (`%1` the title), `recordCard.untitled`, `recordCard.selected`,
+  `recordCard.notSelected`. English comes from the default catalogue; override per instance
+  through `msg`, or for every instance through `setTranslator()`.
 - **Selection trigger** — `selectionTrigger:'checkbox'` preserves existing selection behavior.
   With `'card'`, selectable backgrounds toggle on click, Enter or Space, Shift+click selects a range,
   and the checkbox is omitted. Links, actions and text selection keep their native behavior. Selection
@@ -1636,7 +1841,18 @@ windowed loader.
   `locale`, `weekStart: 1`, `weekNumbers: true`, `workweek: false`, `agendaDays: 14`,
   `slotDuration: 30`, `slotMinTime: 0`, `slotMaxTime: 1440`, `scrollTime: 480`, `eventLimit: 3`,
   `selectable: false`, `editable: false`, `eventStartEditable`, `eventDurationEditable`,
-  `optimistic: true`, `nowIndicator: true`, `now`, `disabled`, and `renderEvent(event)`.
+  `optimistic: true`, `nowIndicator: true`, `now`, `disabled`, `msg`, and `renderEvent(event)`.
+- **Messages** — every key is namespaced `calendar.*`: `calendar.today`, `calendar.previous`,
+  `calendar.next`, `calendar.new`, `calendar.agenda`/`day`/`week`/`month`/`year` (the view
+  switch), `calendar.viewSwitch`, `calendar.label` (the root's name), `calendar.loading`,
+  `calendar.noEvents`, `calendar.allDay`, `calendar.more` and `calendar.weekNumber` (`%1`),
+  `calendar.dayEvent`/`calendar.dayEvents`, `calendar.resize`, `calendar.moveStarted`,
+  `calendar.resizeStarted`, `calendar.editPreview` (`%1` title, `%2`–`%3` the times),
+  `calendar.editCancelled`, `calendar.editCommitted`. Until 6.0 the bare keys of earlier versions
+  (`today`, `next`, `loading`, …, and `calendar` for `calendar.label`) are still honoured, read
+  right after the namespaced key in the `msg` option and in the host translator; rename them.
+  The built-in English now lives in the default catalogue rather than in `Calendar.defaults.msg`,
+  so a host translator reaches every calendar string.
 - **Event input** — generic records default to `{id,title,start,end,allDay,color,location,editable,
   durationEditable}`. Every field has a string-or-function reader (`eventId`, `eventTitle`,
   `eventStart`, …); numeric dates use `dateUnit: 'milliseconds'|'seconds'`. Inputs are normalized
@@ -1683,6 +1899,8 @@ Declarative client-side filter bar producing a filtered array, commonly wired to
 
 - **Options** — `filters: [{ type: 'select'|'text'|'custom', id, label, field(s)|get, options?,
   predicate?, emptyLabel?, placeholder? }]`, `data`, `autoApply: true`, `clearLabel`.
+- **Messages** — `dataFilter.clear` ("Clear", unless `clearLabel` is given) and `dataFilter.all`
+  ("All", a select filter's empty option unless it sets `emptyLabel`).
 - **Methods** — `setData()`, `apply()` → rows, `clear()`, `getState()`, `setState()`,
   `addFilter()`.
 - **Events** — `filter {rows, state}`.
@@ -1700,7 +1918,7 @@ form renders, with no per-application translation layer in between.
 - **Options** — `fields: Record<string, {type, label?, options?, min?, max?, step?, search?}>`,
   `order` (display order; omitted uses object order), `value` (the applied filters, drafted
   from), `mode: 'draft'|'live'`, `serialize: 'seconds'|'ms'|'iso'|(date, edge) => unknown`,
-  `emptyText`, `msg`.
+  `timeZone` (IANA zone the days are counted in; null = the runtime's own), `emptyText`, `msg`.
 - **Types** — `text`, `select`, `date`, `date:range`, `int`, `float`, `number`, and
   `int:range` / `float:range` / `number:range`. An unrecognised type renders a visible,
   labelled placeholder naming it and is excluded from the value — never dropped silently.
@@ -1725,7 +1943,10 @@ Five behaviours are deliberate rather than incidental:
 
 `serialize` decides how a date leaves the component, because the answer is a wire-format
 decision rather than an application one. A range's upper bound takes the **end** of its day, or
-a one-day range matches nothing.
+a one-day range matches nothing. `timeZone` decides *which* day: with the ZeyOS instance's zone
+(`'Europe/Vienna'`), 15 January serializes from 23:00 UTC on the 14th wherever the browser is, and
+an incoming Unix timestamp shows as the day it falls on there — the rule `zeyosForm()` and
+`zeyosTable()` apply to date-only fields. An unknown zone throws a `RangeError`.
 <!-- /doc -->
 
 <!-- doc:filter -->
@@ -1742,6 +1963,11 @@ adapter to compile into its own backend query language.
   debounce?}`. Built-in types cover text, number/money, date/datetime, boolean, enum/status/
   priority/country/currency/unit/entity, and tags. Compatible operators and their arity come from
   the exported `filterOperators` matrix; applications may explicitly override/add operator IDs.
+- **Relative dates** — `withinLast` and `withinNext` take a span, not two dates: the editor is a
+  whole-number amount and a unit select, and the value is the pair `[amount, unit]` with `unit` one
+  of `RELATIVE_DATE_UNITS` (`'days'|'weeks'|'months'`), e.g. `[7, 'days']`. `validate()` requires a
+  positive whole amount and a known unit; `relativeDateValueError(value)` is the same check for an
+  adapter. A value that is not such a pair (two dates) shows as an empty amount.
 - **Options** — `fields`, `value`, `operators`, `allowGroups: true`, `maxDepth: 3`,
   `maxConditions: 50`, `autoApply: false`, `readonly`, `disabled`, `applyLabel`, `clearLabel`,
   `searchable: false`, `layout: 'standard'|'compact'`, `rootLogic: null|'and'|'or'`,
@@ -1844,24 +2070,45 @@ breadcrumb.
   mounted twice repeats no id and a field `stage` never collides with a `#stage` elsewhere; the
   label, description, and message ids derive from it (`<id>-label`). Radio groups are named after
   the control id. An `id` in the field options that differs from the key is used as given.
-- **Methods** — `addField(id, opts)`, `getField`/`hasField`/`getFields`,
+- **Methods** — `addField(id, opts|Field|element|component)`, `getField`/`hasField`/`getFields`,
   `getValues`/`setValues`/`getValue`/`setValue`, `reset`, `clear`, `focus(id)`,
   `setHighlights`/`clearHighlights`.
+- **Adopting a component** — `addField(id, component)` wraps any component (or element) that is
+  not a registered field type and drives it through its own API. Values: `getValue`/`setValue`,
+  `get`/`set`, `getValues`/`setValues`, `isChecked`/`setChecked`, or a `value` property, tried in
+  that order (a Toggle reads its on-value, as the `toggle` type does); an element is read through
+  `value`, or `checked` for a checkbox or radio. Disabled: `setDisabled(bool)`, then
+  `enable()`/`disable()`, then a `disabled` property; a plain wrapper gets `aria-disabled` and its
+  form controls disabled. Read-only: `setReadonly`/`setReadOnly` or the element's `readOnly`. The
+  component's own `change` becomes the field's `change`, once per edit. Writes keep the caller's
+  `silent`: `setValues(values)` lets the component emit its own `change` to its own listeners and
+  the field emit one `change`; `setValues(values, {silent: true})` and `reset()` stay quiet.
+  Removing the field puts the component back, unsubscribes from it, and undoes the disabled and
+  read-only state the field set.
 
 #### Field
 
 - **Options** — `id` (the control's DOM id; generated when omitted), `name` (the field name and
   native control `name`; defaults to `id` on a standalone field), `type: 'text'`, `label`,
-  `description`, `value`, `placeholder`, `required`, `disabled`, `options`,
-  `layout: 'stack'|'inline'`, `props: {}`.
+  `description`, `value`, `placeholder`, `required`, `disabled`, `readonly` (shown and focusable,
+  not editable; ignored by types whose control has no read-only state, such as `checkbox`,
+  `select`, `zxselect`, `date`, `time`), `options`, `layout: 'stack'|'inline'`, `props: {}`.
 - **Properties** — `controlId` (the control's DOM id), `name`.
 - **Built-in types** — `text`, `password`, `textarea`, `checkbox`, `int`, `float`, `select`,
   `optionlist`, `hidden`, `html` (display content as text: no input frame, a control's height,
   inset like the values around it in a quiet form).
-- **Methods** — `getValue`/`setValue`, `focus`, `reset`, `setDisabled`,
+- **Methods** — `getValue`/`setValue`, `focus`, `reset`, `setDisabled`, `setReadonly`,
   `setHighlight(msg, kind)`, `clearHighlight`, `getInput`, `own(child)`, plus the statics
   `Field.register(type, adapter)` and `Field.has(type)`.
-- **Events** — `change {value}`, `invalid {message}`.
+- **Events** — `change {value}`, once per committed edit whatever the type (a typed value on
+  leaving the input, a slider on release, `code` when the editor loses focus after an edit);
+  `input {value}` for every keystroke or drag step from the types that tell the two apart
+  (`code`, `slider`); `invalid {message}`.
+- **Adapters** — `Field.register(type, (field, options) => ({el, get, set, focus, setDisabled,
+  setReadonly?, destroy?, labelTarget?}))`. An adapter whose widget reports its own commits
+  forwards them with `field.emit('change', {value})` and stops the native `change` its inner
+  control bubbles (`field.listen(widget.el, 'change', (e) => e.stopImmediatePropagation())`), so
+  the Field does not report the same edit twice.
 - **Labels** — small, medium weight, in the muted text colour: quieter than the values they name.
   With `layout: 'inline'` the label lines up with the control's first line.
 
@@ -2350,7 +2597,7 @@ columns, in what shape. The parts have always existed (`Search`, `SortControl`,
 forgetting the same thing.
 
 - **Options** — `search: {placeholder?, value?, debounce?, clearable?}|false`, `count`,
-  `countText`, `views: Array<string|{id, label?, icon?}>` (string presets `auto|cards|table|list`),
+  `countText`, `views: Array<string|{id, label?, icon?}>` (string presets `auto|table|list|cards|gallery|board`),
   `view`, `tools: [{id, label?, icon?, badge?, badgeKind?, pressed?, disabled?, onclick?}]`,
   `label`, `msg`.
 - **Methods** — `setCount()`, `setBadge()`, `setPressed()`, `setToolDisabled()`, `setTools()`,
@@ -2370,18 +2617,90 @@ Three properties are the reason to use this rather than assemble your own:
 The current view and a pressed tool take the neutral `--zx-color-bg-current` fill — a mode the
 list is in, not a pick — never the accent tint.
 
-`bind(view)` is optional sugar for a `TableView` or `CardView`: it feature-detects rather than
-importing them, adopts the view's shape, and mounts a field chooser built with
-`fieldControls: {target}` into the toolbar. The toolbar is fully functional without it.
+`bind(view)` is optional sugar for a `TableView`, `CardView`, or `KanbanView`: it feature-detects
+rather than importing them, adopts the view's shape, and mounts the view's field chooser into the
+tools slot through the view's public `mountFieldControls()` — for a default `TableView` that is its
+Table's column chooser. `unbind()` hands it back to the view, and a view destroyed first takes it
+with it. A chooser already mounted here with `fieldControls: {target: toolbar.getToolsElement()}`
+is left where it is. The toolbar is fully functional without `bind()`.
+<!-- /doc -->
+
+<!-- doc:view-settings -->
+### ViewSettings — the content of a view-settings drawer
+
+Which fields a record view shows and in what order, which hidden field to bring back, what the
+records are grouped by, and which fields a board uses for columns and swim lanes. It is content,
+not a container: put it in a `Sheet`, a `Dropdown`, or a settings page.
+
+- **Options** — `fields: ViewSettingsField[]` (a `ViewField` plus `type`, `groupable`, `locked`),
+  `fieldOrder`, `hiddenFields`, `groupBy`, `grouping: boolean|{fields?}`,
+  `board: {columnBy, swimlaneBy, showEmptyColumns?, fields?}|false` (`fields` restricts the
+  Columns and Swim lanes choices; default: the Group by fields), `sections` (order and presence of
+  `'fields'|'grouping'|'board'`), `types: Record<type, {icon?, label?}>`, `searchThreshold` (8),
+  `headingLevel` (3), `label`, `msg`.
+- **Methods** — `getState()`, `setState(partial, {silent})`, `setFields()`, `getFields()`,
+  `showField()`, `hideField()`, `moveField(id, index)`, `bind(view, {board?})`, `unbind()`,
+  `focus()`, `destroy()`.
+- **Events** — `change {state, reason: 'order'|'visibility'|'group'|'board'}`,
+  `fieldorderchange {order}`, `fieldvisibilitychange {visible, hidden}`, `groupchange {field}`,
+  `boardchange {board}`.
+- **State** — `{fieldOrder, hiddenFields, groupBy, board}`: JSON-safe, ready to persist.
+
+The shown fields are listed in order, each with a drag handle, its type glyph, and a hide button;
+the hidden ones follow with an explicit **Add** button, which puts the field at the end of the
+shown list. Above `searchThreshold` fields a search narrows the hidden list (label, id, and type
+name, ignoring case and accents) and Enter adds the first match. A `locked` field — the record
+title — has neither handle nor hide button and keeps its place while the others move around it.
+`locked` governs only what the panel offers: a bound view has no such notion, so a locked field the
+view hides itself appears under Hidden with Add like any other. The last shown field cannot be
+hidden.
+
+Rows reorder by pointer (mouse, touch, and pen share one path: drag the handle, an insertion line
+shows where it lands, Escape cancels; near the top or bottom edge of the nearest scroll container,
+the container scrolls) and by keyboard on the focused handle: ArrowUp/ArrowDown
+move one step, Home/End to the ends, Space or Enter picks the row up and drops it, Escape returns
+it. Every move is announced in a polite live region ("Owner moved to position 3 of 6"). A redraw
+from outside — `setState()`, `setFields()`, a bound view's change — cancels a pick-up or drag in
+progress (announced) and keeps focus on the same field's control.
+
+The type glyph comes from a built-in map that `types` extends: text, number (int, float,
+percent), money, date, datetime, time, boolean, select (enum), status, priority, entity, tags,
+url, email, image, file, rating. The type name is the glyph's `title` and visually hidden text,
+so it is seen and heard. Grouping and the board offer fields with `groupable !== false` and a
+discrete type (text, select, status, priority, boolean, entity), or `groupable: true`;
+`grouping.fields` restricts the Group by choices.
+
+`bind(view)` connects a `TableView`, `CardView`, or `KanbanView`: it reads the view's fields and
+state, pushes order and visibility through `setFieldOrder()`/`setFieldVisible()`, and follows the
+view's own `statechange`; `unbind()` releases the view. A panel given its own `fields` lists
+those and no others (the title a card draws is not a column to offer); given none, it lists every
+field the view has. The view's labels and types win over the panel's descriptors, which add only
+`locked`, `groupable`, and a type where the view has just the `'text'` default. While bound the view owns the field list: call the view's `setFields()` — the
+panel's own `setFields()` is not pushed and lasts until the view's next change. Grouping and board
+changes are only emitted — the host applies them.
 <!-- /doc -->
 
 <!-- doc:pagination -->
 ### Pagination
 
-The pager for a server-backed list, shaped to drop straight onto `Table` with
-`sortMode: 'server'` or onto the `zeyosTable` binding — `getState()` hands back the `offset` and
-`pageSize` a query needs. `page` is 1-based and always clamped into `[1, pages]`; a `total` of 0 is
-treated as one empty page rather than zero pages.
+The pager for a server-backed list. It owns no data: `getState()` and every `change` hand back
+the `page`, `pageSize`, and zero-based `offset = (page - 1) * pageSize` a query needs. `page` is
+1-based and always clamped into `[1, pages]`; a `total` of 0 is treated as one empty page rather
+than zero pages.
+
+The ZeyOS bindings page differently — zero-based, `pageSize: 50`, appending pages above zero — so
+driving `zeyosTable()` (or `zeyosView()`) takes one mapping in the `change` listener:
+
+```js
+const binding = zeyosTable(client, 'contacts', { pageSize: 25 });
+const pager = new Pagination(host, { pageSize: binding.pageSize });
+pager.on('change', async ({ detail }) => {
+  const result = await binding.load({ page: detail.page - 1, pageSize: detail.pageSize, replace: true });
+  pager.setTotal(result.count ?? 0); // silent, so it cannot loop
+});
+```
+
+In `mode: 'loadmore'` each `change` is one `binding.loadMore()`, which appends.
 
 - **Options** — `page: 1`, `pageSize: 25`, `total: 0`, `pageSizes: [25, 50, 100]`, `siblings: 1`,
   `boundaries: 1`, `showPageSize: true`, `showSummary: true` (renders "26–50 of 312"),
@@ -2396,8 +2715,9 @@ treated as one empty page rather than zero pages.
 - **Semantics** — `<nav aria-label="Pagination">`; the current page carries `aria-current="page"`;
   previous/next are labelled icon buttons that go `disabled` at the ends; the ellipses are
   `aria-hidden` spans, not buttons.
-- **Appearance** — the current page is the neutral `--zx-color-bg-current` fill with a semibold
-  figure: where you are, not a call to action.
+- **Appearance** — the summary and the page-size select sit together at the start of the bar,
+  the pager alone at the end; the current page is the neutral `--zx-color-bg-current` fill with a
+  semibold figure: where you are, not a call to action.
 <!-- /doc -->
 
 <!-- doc:navigation-bar -->
@@ -2431,21 +2751,56 @@ inline; every rail state opens descendants toward the workspace in anchored flyo
 
 - **Options** — `items`, `active`, `expanded`, `collapsed`, `collapsible` (`false` removes the
   minimise and expand buttons), `orientation: 'vertical'|'horizontal'`,
-  `side: 'left'|'right'|'top'|'bottom'`, `label`,
+  `side: 'left'|'right'|'top'|'bottom'`, `layout: 'tree'|'modules'`, `module`, `moduleBar`
+  (`{appearance, labels: 'auto'|'beside'|'below'|'hidden', allModules, label}` for the module
+  strip), `label`,
   `header`, `footer`, `railHeader`, `railFooter`, `openDelay: 80`, `closeDelay: 160`, and
   `renderIcon(item, context)`. Icon values may also be names, nodes, components, or factories.
-- **Methods** — `setItems()`, `getItems()`, `setActive()`, `setExpanded()`, `getExpanded()`,
-  `toggleBranch()`, `expand()`, `collapse()`, `setCollapsed()`, `isCollapsed()`,
+- **Sections** — an item with `section: true` is a quiet heading over its `children`, which stay
+  at its own level: never indented, collapsed, focused, or selected, and it needs no `id`.
+  `actions` (a node) adds trailing controls such as an add button. Sections replace stacking
+  several sidebars: one `<nav>`, one keyboard sequence, one rail. On a rail a section becomes a
+  rule; in a flyout, a caption.
+- **Modules layout** — `layout: 'modules'` reads the top level as modules (`ModuleItem`s: `tone`
+  or `color`, `badge`, `pinned`, `group`) and draws them as a `ModuleBar` strip beside a panel
+  with one module's menu. A module with `children`, `header` (a node above its menu, such as its
+  primary action), or `content` (a node below it, such as a tree or a history) is a panel module:
+  choosing its tile shows its panel and fires a cancelable `modulechange`; any other module is a
+  destination and fires `select`. The panel starts on `module`, else the module holding `active`,
+  and follows `setActive()` into another module. A `section` at the top level heads its modules on
+  the strip.
+- **Presentations** — the modules layout shows `'expanded'` (both menus: the strip names its
+  modules beside their tiles, and the side menu shows), `'compact'` (the module menu collapsed to
+  icons beside the side menu), or `'collapsed'` (the icon strip alone; every module's menu opens as
+  a flyout beside its tile). A small three-way switch at the foot of the strip, above
+  `railFooter`, chooses between them: an APG radio group ("Navigation layout") of one pictogram per
+  presentation, in a row while the modules are named and a column on the icon strip; arrow keys
+  move and choose, Home and End jump. `presentationSwitch: false` leaves it out when the choice
+  lives in a menu instead: `presentationChoice({label})` returns the same choice as a menu
+  `choice` entry (`account.setItems([sidebar.presentationChoice(), …])`; rebuild it after
+  `presentationchange`), and `presentationGlyph(name)` is its pictogram. `presentations` (default all three) decides which it offers;
+  `presentation` sets the first one; `getPresentation()`, `setPresentation()`, and
+  `togglePresentation()` (the next one, wrapping — Mod+B in an application) drive it, and
+  `presentationchange {presentation, previous}` reports it. `moduleBar.labels: 'hidden'` never
+  names the modules. `railHeader`/`railFooter` are the strip's head and foot in every
+  presentation. The arrow toward the panel moves from a tile into its menu, and Left Arrow on a
+  top-level row of the menu returns to the tile.
+- **Methods** — `setItems()`, `getItems()`, `setActive()`, `setBadge(id, badge)`, `setExpanded()`,
+  `getExpanded()`, `toggleBranch()`, `expand()`, `collapse()`, `setCollapsed()`, `isCollapsed()`,
+  `setModule(id, {silent})`, `getModule()`, `setModuleLabels(labels)`, `getPresentation()`,
+  `setPresentation(presentation, {silent})`, `togglePresentation()`, `presentationChoice({label})`,
   `setLayout({orientation, side})`, `openFlyout(id, {focus})`, `closeFlyout()`,
   `closeAllFlyouts()`, `isFlyoutOpen()`, `focus()`, `destroy()`. `getItems()` returns copies of
   the normalized tree; a leaf carries no `children` property.
 - **Events** — cancelable `select {item, id, value, href, event}`,
-  `branchchange {item, id, expanded, ids}`, `collapsechange {collapsed}`, and
-  `flyoutchange {item, id, open}`.
+  `branchchange {item, id, expanded, ids}`, `collapsechange {collapsed}`,
+  `flyoutchange {item, id, open}`, cancelable `modulechange {item, id, previous}`, and
+  `presentationchange {presentation, previous}`.
 - **Presentation state** — horizontal navigation is always effectively minimized and never exposes
   an expand control. Switching layouts does not erase the saved vertical collapsed preference or
-  expanded branch IDs. `AppSidebar` is the single public application-navigation component; use
-  `collapsed: true` or `orientation: 'horizontal'` for its rail presentations.
+  expanded branch IDs. `AppSidebar` is the one component that owns an application's navigation
+  tree; use `collapsed: true` or `orientation: 'horizontal'` for its rail presentations, and
+  `layout: 'modules'` for the module strip it composes from `ModuleBar`.
 - **Current state** — the current page is neutral: the `--zx-color-bg-current` fill, the full
   text colour and a semibold label, in the tree, the rail and every flyout; hover is a lighter
   step of the same overlay. A closed branch (or a rail item) over the active route takes the
@@ -2462,11 +2817,81 @@ inline; every rail state opens descendants toward the workspace in anchored flyo
   link or callback is disabled in every presentation.
 <!-- /doc -->
 
+<!-- doc:module-bar -->
+### ModuleBar — the module level of an application
+
+One colour-coded tile per module, in a vertical strip or a horizontal bar: the level above an
+application's menus. Use it on its own — the classic module bar in an application header, beside
+a tree-layout `AppSidebar` — or through `AppSidebar`'s `layout: 'modules'`, which composes it.
+
+```js
+import { ModuleBar } from '/assets/zx.esm.js';
+
+const bar = new ModuleBar(null, {
+  items: [
+    { id: 'mail', label: 'Mail', icon: 'envelope', tone: 'blue', badge: 7, children: [
+      { id: 'inbox', label: 'Inbox', href: '#inbox' }, { id: 'sent', label: 'Sent', href: '#sent' }
+    ] },
+    { id: 'billing', label: 'Billing', icon: 'file-invoice', color: '#535494', href: '#billing' }
+  ],
+  active: 'inbox',
+  onselect: (event) => { event.preventDefault(); route(event.detail.id); }
+});
+bar.setBadge('mail', 8);
+```
+
+- **Items** (`ModuleItem`) — the `AppNavItem` shape plus `tone` (a categorical tone that follows
+  the theme) or `color` (any CSS colour; it wins), `pinned: true|number` (when any module is
+  pinned, unpinned ones are under "All modules" only), `group` (the catalogue heading), and
+  `description`. Children are the module's menu. A `section` at the top level heads its modules:
+  a caption over them while names are printed beside the tiles, a short rule between groups on an
+  icon strip or bar, and their group in the catalogue.
+- **Options** — `items`, `active` (a module or anything in a module's menu),
+  `orientation: 'vertical'|'horizontal'`, `side`, `appearance: 'tint'|'solid'|'plain'` (the glyph
+  on a tint of the module colour; the solid identity tile; monochrome glyphs),
+  `labels: 'hidden'|'below'|'beside'` (names under the tiles of a vertical strip, or beside them —
+  a navigation column of its own, a row per module with its count at the end),
+  `menus: 'flyout'|'none'`, `expanded`, `controls`, `allModules: 'auto'|'always'|'never'`,
+  `header`, `footer`, `label` (default "Modules"), `openDelay`, `closeDelay`, `renderIcon`.
+- **Menus** — with `menus: 'flyout'` a module's children open beside its tile on hover, focus,
+  click, or the arrow toward the workspace, exactly like a rail. With `menus: 'none'` an adjacent
+  panel the application owns shows them: every module then fires `select`, `setExpanded(id)`
+  names the module the panel shows, and each tile with a menu reports `aria-expanded` and
+  `aria-controls` the `controls` id.
+- **Overflow** — modules that do not fit move behind the "All modules" button; the current module
+  (and the expanded one) always stays. The catalogue lists every module as a labelled tile,
+  grouped by `group`, with a filter field past twelve modules. `partitionModules(items, capacity,
+  keep, reserve)` is the pure function deciding what shows; `reserve` keeps the button's slot for
+  `allModules: 'always'`.
+- **Methods** — `setItems()`, `getItems()`, `setActive()`, `setBadge(id, badge)` (in place, on the
+  tile, in its menu, and in the catalogue), `setExpanded(id)`, `setLabels(labels)` (how a column
+  expands to names and collapses to icons), `setLayout({orientation, side})`,
+  `openFlyout()`, `closeFlyout()`, `closeAllFlyouts()`, `isFlyoutOpen()`, `openAllModules()`,
+  `closeAllModules()`, `isAllModulesOpen()`, `focus()`, `destroy()`.
+- **Events** — cancelable `select {item, id, value, href, event}`, `flyoutchange {item, id, open}`,
+  `overflowchange {visible, overflow}`, and `allmodules {open}`.
+- **Keyboard** — the bar is one Tab stop, on the current module. Arrow keys along the bar move
+  between tiles and wrap; Home and End go to the first and last control; typing jumps to the next
+  module whose name starts with the letters typed; the arrow toward the workspace opens a menu and
+  moves into it; Escape, or the arrow back toward the strip, closes a menu onto its tile; Escape
+  closes the catalogue onto its button, and so does tabbing out of it. In the catalogue, arrows
+  move across the grid, typing goes to the filter field (past twelve modules), and Enter chooses.
+- **Semantics** — a `<nav>` of native links and buttons, never a menu or menubar. The module that
+  is or holds the current page carries `aria-current` (`page` or `true`); an icon-only tile's
+  accessible name is its label, with its count ("Mail (7)"), and it has a tooltip. Current is
+  the neutral `--zx-color-bg-current` fill behind the tile, never the accent or an edge bar.
+- **Geometry** — a target is one control plus a space step, a tile one control less one, so
+  `--zx-control-height` resizes the bar; a coarse pointer keeps a 40px target.
+<!-- /doc -->
+
 <!-- doc:kernel -->
 ### Core helpers
 
 - **Component** — the base class: `on`/`off`/`once`/`emit`, `listen`, `toElement`, `msg`,
-  `destroy`, and the static `Component.from(el)`.
+  `destroy`, and the static `Component.from(el)`. `msg(key, ...args)` always returns text: the
+  instance's `msg` option (a `{[lang]: {…}}` table for the active language, then flat keys), else
+  the host translator, else the class's built-in `msg` defaults, else the default English
+  catalogue, and only then the key itself; `%1`, `%2`, … are filled from `args`.
 - **DOM** — `h(tag, props, ...children)`, `h.raw(html)`, `htmlEscape`, `resolveElement`.
   `__(tag#id.class, properties, content)` is Zx's compact DOM builder and public alias for
   `compactElement()`. It preserves `D*` data, `S*` style, boolean/built-in property, attribute,
@@ -2483,7 +2908,9 @@ inline; every rail state opens descendants toward the workspace in anchored flyo
   `{update, destroy}`. It anchors a manual popover with CSS anchor positioning where the browser
   supports it and a scroll/resize-tracked fallback where it does not. Options are resolved once,
   so changing a placement means `destroy()` and a fresh `position()` call.
-- **i18n** — `setTranslator`, `setLanguage`, `getLanguage`, `translate`, `printf`.
+- **i18n** — `setTranslator`, `setLanguage`, `getLanguage`, `translate`, `printf`, and
+  `defaultMessages`, the frozen English catalogue of every component key (`table.empty` → "No
+  records") that a host copies as the starting point for a locale.
 - **Dates** — `formatDate(d, fmt)`, `parseDate(s, fmt)` (tokens
   `%d %m %Y %y %H %M %S %a %A %b %B %s`), `clampDate`, `isSameDay`, `addDays`, `addMonths`,
   `getWeekStart`.
@@ -2606,12 +3033,20 @@ entry point as the components. See also the Kernel section for `Component`, `h`,
   `copyToClipboard(text)` → `Promise<boolean>` uses the async Clipboard API and falls back to a
   hidden textarea, never rejecting.
 - **Translation** — `setTranslator(fn)`, `setLanguage(lang)`, `getLanguage()`,
-  `translate(key, args)`, `printf(str, args)` (`%s` placeholders). Every component routes its
-  built-in strings through `translate()`, so one translator covers the library, and
-  `setLanguage()` also drives locale-dependent behaviour such as the first day of the week.
+  `translate(key, args)`, `printf(str, args)` (`%1`, `%2`, … placeholders), `defaultMessages`.
+  Every component resolves its built-in strings through `msg()`, so one translator covers the
+  library: per-instance `msg` option → `setTranslator()` function → the component's built-in
+  defaults → the default English catalogue → the key. The translator answers one key at a time;
+  null, undefined, or the key itself means "not translated" and English shows, so an application
+  without a translator never sees a raw key. `defaultMessages` is that catalogue — copy it to
+  start a locale (`setTranslator((key) => de[key])`). `setLanguage()` also selects the language
+  table of a `msg` option and drives locale-dependent behaviour such as the first day of the week.
 - **Keyboard** — `focusTrap(container)` → `{activate, release}` confines Tab to a container;
-  `rovingTabindex(container, itemSelector, {orientation, wrap})` → `{focusFirst, focusLast,
-  destroy}` keeps one tab stop in a group; `typeahead(getItems, onMatch)` →
+  `rovingTabindex(container, itemSelector, {orientation, wrap, rtl: 'auto'})` → `{focusFirst,
+  focusLast, destroy}` keeps one tab stop in a group — horizontal arrows follow `dir="rtl"`, and a
+  text field, select, or contenteditable item keeps Home/End and its arrows (an arrow leaves a text
+  field only from the edge of its text); toggling a `<fieldset disabled>` around items inside the
+  container moves the tab stop off them; `typeahead(getItems, onMatch)` →
   `(event|string) => void` resolves buffered printable keystrokes to an item (500 ms buffer,
   repeated-letter cycling).
 <!-- /doc -->
@@ -2668,8 +3103,13 @@ in component CSS.
   (`--zx-dur-fast` 120ms, `--zx-dur-base` 180ms — both 0ms in a reduced-motion region — and the
   curves `--zx-ease`, `--zx-ease-spring`, `--zx-ease-drawer`).
 - **Tier 2** — the semantic set, the only tokens components may use: `--zx-color-*`,
-  `--zx-control-*`, `--zx-focus-ring`, `--zx-overlay-shadow`, `--zx-drag-shadow` (an item being
-  dragged; its own value in dark, with a faint light rim). The roles that carry the visual
+  `--zx-control-*`, `--zx-focus-ring`, `--zx-surface-shadow` (the contact shadow of a resting
+  surface: a panel, an outlined card in a lane, a slider thumb), `--zx-overlay-shadow`,
+  `--zx-drag-shadow` (an item being dragged; its own value in dark, with a faint light rim). The
+  lint also rejects the accent ramp `--zx-accent-*`, the module palette `--zx-module-*`, and the
+  raw `--zx-shadow-*` steps in component and layout CSS, and any `outline: 0`/`outline: none`:
+  forced-colors mode drops the box-shadow focus ring, so components make the outline transparent
+  and `styles/base.css` repaints it in a system colour there. The roles that carry the visual
   language:
   - **Columns.** `--zx-color-bg-surface` is the working canvas; `--zx-color-bg-chrome` is the
     navigation and inspector tone beside it (one step below the canvas in light, between page and