@zeyos/zx 4.1.1 → 4.3.0

package/docs/llms.md

@@ -75,11 +75,24 @@ Keep the 600 stop at 4.5:1 or better against white and the 400 stop at 4.5:1 aga
 
 The theme studio treats those stable IDs as complete recipes: selecting a preset also changes its
 density, neutral tint, radius, control height, base text size, font stack, and material strength.
-Its **Material** control is CSS-first (`Flat`, `Glass`, or `Deep glass`); only the deep setting uses
-backdrop blur, and components fall back to solid surfaces under reduced-transparency preferences.
+Its **Material** control is CSS-first (`Flat`, `Glass`, or `Deep glass`). Aurora is the independent
+ambient canvas layer; material controls how surfaces respond to that light. The shared recipe
+applies to AppIcons, ordinary controls, persistent chrome, raised cards, and every transient overlay: Dropdown, ContextMenu,
+MenuButton, AccountMenu, AppRail flyouts, Select, TagPicker, date pickers, tooltips, column menus,
+and toasts use `--zx-color-overlay-surface`; Launcher, Modal, Dialog, and overlay Sheets use the
+calmer `--zx-color-overlay-panel`. Both tiers combine a translucent base, responsive specular and
+Aurora tint layers, backdrop filtering, and dedicated state/divider roles; the modal backdrop is a
+separate material token so it does not erase the light the panel should refract. A docked Sheet is
+layout rather than an overlay and becomes opaque, as do dense data surfaces. Glass and Deep glass
+progressively raise translucency, blur, highlights, and elevation; reduced-transparency,
+increased-contrast, forced-colour, and unsupported-filter environments restore solid surfaces.
+Top-layer components remain DOM children of their nearest Zx theme scope, so a theme or material
+set on an application region continues to inherit through its menus, dialogs, tooltips, and toasts.
 
 Define a product theme by overriding **semantic** tokens under a `[data-zx-theme="name"]` selector:
-`--zx-color-bg-page/surface/raised/control/hover/selected`, `--zx-color-border(-strong/-control)`,
+`--zx-color-bg-page/surface/raised/control/hover/selected`, `--zx-color-glass-chrome/surface`,
+`--zx-color-overlay-surface/panel/backdrop/border/hover/selected/divider/scrim`,
+`--zx-overlay-surface-image/toast-image/panel-image`, `--zx-color-border(-strong/-control)`,
 `--zx-color-text(-muted/-placeholder)`, `--zx-color-accent(-hover)/on-accent`,
 `--zx-color-danger/warning/success/info(+ -bg)`, `--zx-focus-ring`, `--zx-control-height/-radius`,
 `--zx-space-*`, `--zx-radius-*`, `--zx-text-*`. Never use tier-1 palette tokens (`--zx-gray-*`,
@@ -119,8 +132,10 @@ bundles `@zeyos/client`; the application owns client creation, authentication, a
 ```js
 import { createZeyosClient } from '@zeyos/client';
 import {
-  connect, dataFilterStateToFilters, zeyosForm, zeyosSelect, zeyosTable
+  connect, createLegacySavedViewTransport, createSavedViewRegistry,
+  dataFilterStateToFilters, legacySavedViewRequest, zeyosForm, zeyosSelect, zeyosTable, zeyosView
 } from '/assets/zx-zeyos.esm.js';
+import { CardView, TableView } from '/assets/zx.esm.js';
 
 const client = createZeyosClient({ platform, auth });
 const api = connect(client, { locale: 'en-GB' });
@@ -138,6 +153,17 @@ const editor = zeyosForm(client, 'transactions', {
 });
 await editor.load(transactionId);
 await editor.save();
+
+const records = zeyosView(client, 'transactions', TableView, {
+  fields: ['transactionnum', 'account', 'date', 'netamount', 'status'],
+  savedViews: {
+    transport: savedViewTransport,
+    scope: { userId: currentUserId, workspaceId: currentWorkspaceId }
+  }
+});
+await records.ready; // restores a compatible default before the first list request
+await records.load();
+await records.saveView({ name: 'My open invoices', setDefault: true });
 ```
 
 - `connect(client, { onError, locale })` returns `{client, list, get, create, update, reportError}`;
@@ -154,6 +180,21 @@ await editor.save();
   `{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`.
+- `buildZeyosViewConfig(client, resource, opts)` resolves one schema to shared `ViewField[]`, a
+  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
+  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
+  component state plus filters/search and an explicit presentation type, never records, selection,
+  pages, callbacks, or DOM. Duplicate names, defaults, migration, type mismatch, failed writes, and
+  teardown are explicit. `workspaceId:null` addresses ZeyOS's base workspace.
+- `createLegacySavedViewTransport(request)` reuses the authenticated `fields`, `fields_save`, and
+  `fields_remove` endpoints through one reserved, namespaced `userfields` record.
+  `legacySavedViewRequest(PG.load.bind(PG))` is the optional Promise bridge for a legacy host. The
+  scope's `userId` is intentionally not sent to the endpoint; the server session remains authority.
 
 Field mapping is schema-driven: entity/FK → async `zxselect`; enum/list → `optionlist` or native
 `select`; indexed `date` bigint → `date`; other date/time bigints → `datetime`; money/price/numeric
@@ -420,11 +461,13 @@ A native-dialog launcher for applications, recent records, commands, and grouped
 Zx owns ranking, focus, request cancellation, and presentation; ZeyOS owns the catalogue,
 permissions, recent-history/cache policy, and the route or command ultimately invoked.
 
-- **Constructor** — `new Launcher(null, options)` owns a body-level dialog;
+- **Constructor** — `new Launcher(null, options)` owns a top-layer dialog in the opener's nearest
+  Zx theme scope;
   `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`,
-  `loadingText`, `shortcut: 'mod+k'|false`, and visible `hints` labels (or `false`).
+  `loadingText`, `shortcut: 'mod+k'|false`, visible `hints` labels (or `false`), and `scope` to
+  explicitly select an element whose nearest Zx theme scope owns the launcher.
 - **Items** — `{id, label, description?, keywords?, group?, icon?, badge?, value?, href?, target?,
   invoke?, pinned?, disabled?, kind?, current?, when?, groupOrder?, itemOrder?}`. `icon` accepts a
   bundled icon name, Node, or factory. Links stay native so modified and middle clicks work;
@@ -453,27 +496,34 @@ permissions, recent-history/cache policy, and the route or command ultimately in
 <!-- doc:app-icon -->
 ### AppIcon — application identity
 
-A fixed-size, product-agnostic application tile. It keeps glyph geometry stable in launchers,
+A fixed-size, product-agnostic application identity. It keeps glyph geometry stable in launchers,
 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`,
-  `iconSize: '52%'`, `label`, `badge`, `selected: false`, `glass: false|'subtle'|'strong'`, and
+  `iconSize: '52%'`, `label`, `badge`, `selected: false`, `shape: 'tile'|'circle'`,
+  `glass: false|'subtle'|'strong'`, and
   additional `class` names.
 - **Methods** — `set(partialOptions)` updates the existing root; `destroy()` restores an enhanced
   target. `appIcon(options)` is the element-returning convenience factory.
 - **ZeyOS preset** — import `zeyosAppIcon(module, options)` from `@zeyos/zx/zeyos`. Every current
   ZeyOS application/module has a canonical colour and icon mapping in `src/zeyos/modules.js`;
-  entity names and aliases resolve through the same catalogue. `moduleChip()` is the compatible
-  alias. An application may call `useZeyosIcons()` for the existing custom glyph kit or inject an
-  offline `icon` override; Zx never loads a network asset automatically.
-- **Material** — subtle glass is a CSS border/highlight treatment; strong glass progressively adds
-  `backdrop-filter`. `prefers-reduced-transparency` and browsers without support receive a solid
-  tile. Glyphs remain white and geometrically centred in either built-in SVG or Font Awesome form;
-  hover and focus feedback use the same semantic material tokens. The glyph and label semantics do
-  not depend on the visual treatment.
-- **Accessibility** — a non-empty `label` gives the root `role="img"`; otherwise it is decorative.
-  The badge is visual supplementary status, so include its meaning in `label` when it matters.
+  entity names and aliases resolve through the same catalogue. `zeyosAppIcon()` defaults to a
+  circular application vessel; `moduleChip()` deliberately keeps a compact tile for entity and
+  record identity. An application may call `useZeyosIcons()` for the existing custom glyph kit or
+  inject an offline `icon` override; Zx never loads a network asset automatically.
+- **Shape and material** — core `AppIcon` keeps the backward-compatible `tile` default. Application
+  launchers and rails use `circle`; entity rows, recent records, badges, and tables use `tile`.
+  Subtle glass uses a quiet colour bloom, rim, reflection, and shadow without per-icon backdrop
+  blur; strong glass increases those material cues without changing geometry.
+  `prefers-reduced-transparency` receives a solid surface. Glyphs remain crisp white and
+  geometrically centred in either built-in SVG or Font Awesome form. Enabled interactive hosts
+  respond through rim, light, and shadow without translating the icon; decorative and disabled
+  identities do not imply clickability.
+- **Accessibility** — on an owned identity surface, a non-empty `label` gives the root
+  `role="img"`; otherwise it is decorative. When AppIcon enhances a button or link, it preserves
+  that control's native role and uses `label` only as its accessible name. The badge is visual
+  supplementary status, so include its meaning in `label` when it matters.
 <!-- /doc -->
 
 <!-- doc:avatar -->
@@ -744,8 +794,10 @@ The shared floating region is fixed to the upper-right logical corner by default
 messages rather than the page, and uses the translucent glass surface tokens with a solid fallback.
 
 - **Statics** — `Message.info/success/warning/error(msg, opts)`,
-  `Message.show(msg, { kind, timeout=4000, closable })` → `{ close() }`,
-  `Message.progress(text)` → `{ update(pct, text?), done(), fail(text?) }`.
+  `Message.show(msg, { kind, timeout=4000, closable, scope? })` → `{ close() }`,
+  `Message.progress(text, {scope?})` → `{ update(pct, text?), done(), fail(text?) }`. `scope` is
+  an element or selector whose nearest Zx theme scope owns that floating region; without it the
+  focused opener supplies the scope.
 - **Per-message options** — `kind: 'info'`, `timeout`, `closable: true`, `maxVisible: 5` (extras
   queue, and hovering pauses dismissal).
 <!-- /doc -->
@@ -753,11 +805,11 @@ messages rather than the page, and uses the translucent glass surface tokens wit
 <!-- doc:modal -->
 ### Modal
 
-Thin overlay on the native `<dialog>` element. The backdrop uses `--zx-color-bg-backdrop`, and
-focus returns to the opener on close.
+Thin overlay on the native `<dialog>` element. The surface uses the shared, reading-sized overlay
+panel material; the backdrop uses `--zx-color-overlay-backdrop`, and focus returns to the opener on close.
 
 - **Options** — `content`, `width: 'auto'`, `closable: true`, `lightDismiss: false`,
-  `destroyOnClose: false`.
+  `destroyOnClose: false`, `scope: null` (the opener's nearest Zx theme scope by default).
 - **Methods** — `open()`, `close(result?)`, `setContent()`, `isOpen()`.
 - **Events** — `open`, `close {result}`, `cancel` (Esc; preventable with `event.preventDefault()`).
 <!-- /doc -->
@@ -782,13 +834,14 @@ Structured modal: a header with title and close button, a body, and footer butto
 Edge-anchored surface — a `Dialog` attached to one side of the viewport instead of floating in the
 middle. One primitive covers both side sheets and mobile drawers, which differ mainly in the edge they take, so
 `side` replaces what would otherwise be two components. Inherits the whole Dialog anatomy: title,
-footer buttons, switchable views, and focus restoration.
+footer buttons, switchable views, focus restoration, and the reading-sized overlay panel material.
+When a Dock adopts it, the Sheet becomes an opaque layout surface instead.
 
 - **Options** — `side: 'end'` (`'start' | 'end' | 'top' | 'bottom'`, logical), `modal: true`
   (`true | 'trap-focus' | false`), `backdrop: 'dim'` (`'dim' | 'blur' | 'none'`), `size: null`
   (CSS length or px number, applied to whichever axis `side` implies), `closeButton: true`,
   plus everything Dialog takes — `title`, `content`, `buttons`, `closable`, `lightDismiss`
-  (defaults to `true` here, unlike Modal), `destroyOnClose`.
+  (defaults to `true` here, unlike Modal), `destroyOnClose`, `scope`.
 - **Methods** — `open()`, `close(result?)`, `setSide(side)`, `getSide()`, `setSize(size)`,
   `isModal()`, `isDocked()`, `isOpen()`, `getSize()`, `snapTo(target)`, plus Dialog's `setTitle()`, `setContent()`,
   `setButtons()`, `addView()`, `showView()`.
@@ -802,10 +855,12 @@ footer buttons, switchable views, and focus restoration.
   across a handoff: the element moves and reopens in place, so DOM state and listeners survive,
   and no `open`/`close` is emitted for what is only a change of address.
 - **Modality** — `true` delegates focus containment, page inertness, Escape, and the backdrop to
-  the browser through `showModal()`. `'trap-focus'` and `false` open with `show()`, so the page
-  keeps scrolling and stays interactive; Escape and outside-click are re-implemented, and
-  `'trap-focus'` adds `focusTrap()` on top. Only a modal sheet renders a `::backdrop`, so
-  `backdrop` is meaningful only when `modal` is `true`.
+  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
+  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`.
   `snap` gives it detents: a number at or below 1 is a fraction of the viewport along the sheet's
   axis, anything larger is pixels, and a string is any CSS length (`'320px'`, `'90%'`). With
@@ -876,12 +931,14 @@ alone, `new SheetStack({…})`.
 ### Dropdown
 
 Generic anchored popover in the top layer, constructed as `new Dropdown(anchor, options)`. It
-light-dismisses on an outside click or Esc, and mirrors `aria-expanded` onto the anchor.
+light-dismisses on an outside click or Esc, mirrors `aria-expanded` onto the anchor, and stays a
+DOM child of the anchor's nearest Zx theme scope while the browser lifts it into the top layer.
 
 - **Options** — `content`,
   `placement: 'bottom-start'|'bottom-end'|'top-start'|'top-end'|'bottom'|'top'` plus the matching
   `left*` and `right*` placements, `offset: 4`,
-  `matchWidth: false`, `openOn: 'click'|'manual'`, `closeOnSelect: false`.
+  `matchWidth: false`, `openOn: 'click'|'manual'`, `closeOnSelect: false`, `scope: null` (the
+  anchor's nearest Zx theme scope by default).
 - **Methods** — `open()`, `close()`, `toggle()`, `isOpen()`, `setContent()`, `getPanel()`.
 - **Events** — `open`, `close`.
 <!-- /doc -->
@@ -971,7 +1028,7 @@ range select.
   `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.
 - **Methods** — `setData()`, `addData()`, `updateRow(id,row)`, `removeRow(id)`, `getRow(id)`,
-  `getData()`, `empty()`, `setSort(id,dir)`, `getSelection()`, `setSelection(ids)`,
+  `getData()`, `empty()`, `setSort(id,dir)`, `getSort()`, `clearSort()`, `getSelection()`, `setSelection(ids)`,
   `clearSelection()`, `setLoading(bool)` (busy/skeleton state — dims rows, shows an indeterminate
   top bar, sets `aria-busy`, and is cleared by the next `setData`).
 - **Events** — `rowclick {row, id, index, event}`, `rowdblclick`, `sort {id, dir}`,
@@ -1051,6 +1108,82 @@ range select.
 - **Column visibility** — `columnVisibility: true` renders a chooser; `hiddenColumns` seeds it.
   `getVisibleColumns()`, `getHiddenColumns()`, `setColumnVisible()`, and `toggleColumn()` preserve
   caller column order and never allow the final visible column to disappear.
+- **Column order** — `columnReorder: true` adds up/down buttons to the chooser and ArrowUp/
+  ArrowDown support while a column option is focused. `getColumns()`, `setColumns()`,
+  `getColumnOrder()`, `setColumnOrder()`, and `moveColumn()` reconcile stale saved IDs and keep
+  hidden/sorted state attached to stable column IDs. `columnorderchange {order}` fires after a
+  user or non-silent programmatic change.
+<!-- /doc -->
+
+<!-- doc:table-view -->
+### TableView and the shared RecordView contract
+
+`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,
+responsive stacking, loading, and advanced table events remain available through `getTable()`.
+
+- **Shared fields** — every view accepts `fields: [{id,label,get?,render?,sortValue?,sortable?,
+  visible?,duplicate?,type?,view?}]`. Primitive rendered values become text; an explicit Node is
+  adopted. `field.view.table` carries Table-only column keys without changing CardView or KanbanView.
+- **Shared options** — `data`, `recordId: 'ID'`, `sort`, `sortMode: 'local'|'server'`,
+  `selectable: false|'single'|'multi'`, `selection`, `fieldOrder`, `hiddenFields`,
+  `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()`.
+- **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.
+- **TableView composition** — `table: {...}` forwards every advanced Table option, while shared
+  fields/data/id/sort/selection/visibility/order win on overlaps. `getTable()` returns the composed
+  instance. Row events become shared `recordclick`/`recorddblclick` details.
+- **Events** — `recordclick`, `recorddblclick`, `datachange`, `selectionchange`, `sortchange`,
+  `fieldvisibilitychange`, `fieldorderchange`, and `statechange {state,reason}`.
+<!-- /doc -->
+
+<!-- doc:card-view -->
+### CardView
+
+A responsive semantic record collection using the same fields, records, sort, selection, and
+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`.
+- **Cards** — each record is a focusable `<li>` with a native title link, separate secondary
+  actions, optional native multi-select checkbox, labelled metadata, and `aria-selected` state.
+  Title/subtitle fields are not duplicated in metadata unless their field sets `duplicate:true`.
+- **Media and URLs** — `preview` accepts a field ID or callback returning an image URL,
+  `{src,alt,fit}`, Node, or null. Executable/non-image schemes are rejected and image failures show
+  a stable fallback. Title/action links are normalized; `_blank` links receive `noopener`.
+- **Grouping and layout** — `groupBy` is a field ID or callback; `groupOrder` may deliberately show
+  empty groups. Cards reflow through container queries and may cap columns without viewport logic.
+- **Interaction** — Enter activates a focused card; Space toggles selection. Links, actions,
+  selection controls, and selected text do not also activate the card. `recordaction` adds the
+  resolved action to the shared event set.
+<!-- /doc -->
+
+<!-- doc:kanban-view -->
+### KanbanView
+
+A semantic record board with explicit or data-derived columns, optional swim lanes, shared record
+cards, advisory work-in-progress limits, and equivalent pointer/programmatic/keyboard movement.
+
+- **Options** — the shared RecordView options plus `columnBy`, `columns`, `swimlaneBy`,
+  `swimlanes`, card title/subtitle/preview/link/actions, `moveMode: 'local'|'external'`,
+  `columnOrder`, `swimlaneOrder`, collapsed IDs, `showCounts`, `showEmptyColumns`, `variant`, and
+  `label`. Column/lane descriptors use stable `id`, `label`, optional stored `value`, and `accept`;
+  columns may also declare an advisory `limit`.
+- **Methods** — configure/get/move columns and swim lanes, collapse either axis, and
+  `moveRecord(id,{column?,lane?,index?})`. Board-specific order/collapse joins the common view
+  state; record order, movement history, and selection do not.
+- **Movement boundary** — `recordmove {record,id,from,to,column,swimlane,limitExceeded}` is
+  cancelable and fires before a commit/request. `accept` is a hard eligibility gate; WIP is visual
+  advice. Local mode clones the moved record and never mutates host data. External mode emits only,
+  for server validation and optimistic rollback owned by ZeyOS.
+- **Keyboard** — focus the move handle; Enter/Space grabs or drops, Escape cancels, Left/Right
+  chooses a column, Up/Down chooses a bucket-relative position, and Alt+Up/Down chooses a swim
+  lane. A polite live region announces every target and result. Native drag is an enhancement.
 <!-- /doc -->
 
 <!-- doc:grid -->
@@ -1102,6 +1235,53 @@ code, so future adapters do not change the public `Chart` API.
   for assistive technology; `'visible'` makes exact values part of the interface.
 <!-- /doc -->
 
+<!-- doc:calendar -->
+### Calendar
+
+A dependency-free scheduling surface for operational events. One component owns agenda, day,
+week, month, and year views; local-time range math; timed collision columns; multi-day lanes;
+loading and empty states; pointer range selection; and equivalent pointer/keyboard move and resize
+interactions. Visible ranges use an exclusive `end`, so `dateschange` can be passed directly to a
+windowed loader.
+
+- **Options** — `events`, `date`, `view: 'month'`, `views: ['agenda','day','week','month','year']`,
+  `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)`.
+- **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
+  atomically, duplicate IDs and inverted intervals throw, Dates are copied, text is never parsed as
+  HTML, and suspicious CSS colour strings are ignored.
+- **Methods** — `getEvents()`, `setEvents()`, `addEvent()`, `updateEvent()`, `removeEvent()`,
+  `getDate()`, `setDate()`, `getView()`, `setView()`, `prev()`, `next()`, `today()`,
+  `setLoading()`, `focusEvent()`, `destroy()`.
+- **Events** — `dateschange {view,start,end}`, `viewchange {view,oldView}`, `eventclick`,
+  `eventdblclick`, `dateclick {date,allDay,view}`, `select {start,end,allDay,view}`,
+  `new {date,view}`, `moreclick {date,count}`, `eventschange {events}`, and cancelable
+  `eventchange {event,oldEvent,action,delta,jsEvent,revert}`.
+- **Persistence** — `optimistic: true` updates local events before `eventchange`; call the
+  idempotent, version-guarded `detail.revert()` if persistence fails. With `optimistic: false`, the
+  component stays controlled: it emits the proposal without changing data, and the application
+  applies an accepted response through `updateEvent()` or `setEvents()`. Zx does not send requests.
+- **View layout** — agenda days keep every event in one vertically stacked content column. Month
+  uses a continuous seven-day grid with full-height day boundaries and event lanes overlaid below
+  the date labels; today is indicated with accent text instead of a decorative edge highlight.
+- **Pointer editing** — a timed move preserves the point where the event was grabbed and snaps the
+  resulting start to `slotDuration`. The lower grip stretches the event in its original day column,
+  while pointer capture keeps either interaction active if the pointer leaves the event surface.
+- **Keyboard** — time slots and date grids use arrow-key navigation, Home/End, PageUp/PageDown,
+  Enter/Space activation, and roving focus. On an editable event, Space grabs it, arrows propose a
+  slot/day move (or change the focused resize grip), Space drops, and Escape cancels. Live status
+  text announces the edit and its proposed times.
+- **ZeyOS binding** — `zeyosCalendar()` maps current appointment occurrence rows (`ID`, `name`,
+  `location`, `color`, `datefrom`, `dateto`, and association text). `calendarEventToZeyosPatch()`
+  returns the base `ID` with Unix-second dates. The current server already expands recurrence into
+  the requested window; recurrence rules, DAV synchronization, permissions, and routes therefore
+  remain in ZeyOS instead of being reimplemented in core.
+<!-- /doc -->
+
 <!-- doc:data-filter -->
 ### DataFilter
 
@@ -1405,6 +1585,30 @@ so buttons and links in its action, content, and footer regions remain valid sib
   container query when the card itself becomes narrow.
 <!-- /doc -->
 
+<!-- doc:aurora -->
+### Aurora
+
+A decorative, CSS-driven ambient light field for an existing application surface. Aurora enhances
+the target in place: it does not wrap, replace, or relocate the surface's content, and it does not
+own routing, overlays, or interaction. Its gradients sit behind the target's children, so raised
+Cards and other Liquid Glass surfaces can pick up the underlying colour naturally.
+
+- **Options** — `preset: 'source'|'confluence'|'horizon'|'diagonal'|'edge'|'curtain'`,
+  `colors: []` (zero to four concrete CSS colours),
+  `intensity: 'subtle'|'balanced'|'vivid'`.
+- **Methods** — `setPreset(preset)`, `setColors(colors)`, `setIntensity(intensity)`.
+- **Palette** — an empty list uses semantic accent, info, success, and warning colours. One colour
+  fills all four fields; two alternate; three repeat the second colour in the fourth field; four
+  map directly. Network/image-bearing CSS values and palettes longer than four are rejected.
+- **Geometry** — Source starts at the leading chrome; Confluence meets from the corners; Horizon
+  forms a shallow top band; Diagonal crosses the surface; Edge preserves a neutral centre; Curtain
+  descends as four elongated fields. All use ordinary CSS gradients without animation.
+- **Lifecycle** — `destroy()` removes an owned root or restores every original attribute and child
+  of an enhanced target. Content is never rebuilt when a setter changes the effect.
+- **Accessibility** — the light field is pointer-transparent and purely decorative. Forced-colour
+  and reduced-transparency preferences remove it entirely.
+<!-- /doc -->
+
 <!-- doc:panel -->
 ### Panel / MasterPanel
 

package/docs/llms.txt

@@ -21,21 +21,26 @@ exports and as `window.zx.*`.
 - [Contributor contract](https://github.com/zeyos/zx/blob/main/AGENTS.md): conventions for editing component source (token rules, render-time state, listeners, ARIA/APG).
 
 ## Components
-- Inputs and identity: `button()`, `buttonGroup()`, `badge()`/`badgeGroup()`, `CheckButton`,
-  `Toggle`, `Search`, `AppIcon` (+ `zeyosAppIcon()` presets), `Avatar`,
+- Inputs: `button()`, `buttonGroup()`, `badge()`/`badgeGroup()`, `CheckButton`,
+  `Toggle`, `Search`,
   `Select` (APG combobox; `filter: false|'local'|async`; priority, status, permission, and
   `Select.entity()` presets), `Checklist`, `TagPicker` (icon/color identity), `NumberField`, `Rating`, `Slider`,
   `copyButton()`/`CopyInput`, `DatePicker`, `MonthPicker`, `TimePicker`,
   `Datebox`/`DateTimeBox`, `DateRangePicker`/`DateRangeBox`, `Timebox`.
 - Overlays: `Message` (toasts/inline/progress), `Modal`, `Dialog` (+ `alert`/`confirm`/`prompt` Promises), `Sheet` (edge-anchored Dialog; `side`, `modal: true|'trap-focus'|false`, `backdrop`, `snap` detents, swipe-to-dismiss), `SheetStack` (drill-down; `stack`/`cascade`), `Dropdown`, `MenuButton`, `ContextMenu` (right-click; `selector` for per-row menus), `Tooltip`/`tooltip()`/`describe()`.
 - Data: `Table` (sortable, selectable, sticky header, opt-in inline cell/row editing, row reorder,
-  column visibility), `Grid` with single-click editing and `Grid.BillingItems()`, engine-neutral
-  `Chart` with injected `ChartJsAdapter`, backend-neutral nested `Filter`, simple client-side
+  column visibility), shared `RecordView` state through `TableView`, `CardView`, and `KanbanView`,
+  `Grid` with single-click editing and `Grid.BillingItems()`, engine-neutral
+  `Chart` with injected `ChartJsAdapter`, `Calendar` (agenda/day/week/month/year, pointer/keyboard
+  drag and resize, `optimistic: true|false`), backend-neutral nested `Filter`, simple client-side
   `DataFilter`, `Pagination` (+ pure `paginationRange()`), `TreeView` (APG tree),
   `Finder` (Miller columns).
 - Forms: `Form`, `Fieldset`, `Questionnaire` (guided one-question-at-a-time flow with branching), `Field` (type registry), `ValueList`, `MultiValueEditor`, `FieldUpload`.
 - Layout: `stack()`/`grid()`/`aspect()` (spacing, an intrinsically reflowing grid, a fixed-ratio
-  box), `Groupbox`, `Card` (media/title link/actions/footer), `Panel` (header/footer action
+  box), `Groupbox`, `Card` (media/title link/actions/footer), `AppIcon` (generic tile geometry;
+  circular `zeyosAppIcon()` application presets and compact `moduleChip()` identities),
+  `Aurora` (one- to four-colour ambient
+  canvas light; shared material roles govern chrome and overlays), `Avatar`, `Panel` (header/footer action
   buttons), `MasterPanel`, `Tabbox`
   (`variant: 'divided'|'bracket'|'line'|'segmented'`), `NavigationBar`, `AppSidebar` (expanded and
   minimized vertical states plus horizontal rail layouts), `AccountMenu`, `Launcher`,
@@ -47,11 +52,16 @@ exports and as `window.zx.*`.
 - Helpers: `formatNumber`/`formatCurrency`/`formatPercent`/`formatFileSize`/`formatRelativeTime` (locale-aware, cached `Intl`), `debounce`/`throttle`, `groupBy`/`sortBy`/`uniqueBy`, `escapeRegExp`/`highlightMatch`, `storage()` (namespaced JSON, degrades to memory), `toCsv`/`downloadBlob`/`copyToClipboard`, `truncate()`/`isTruncated()` (line clamp with the full value on hover).
 
 ## Theming
-Load `zx.css` once; set `data-zx-theme` (`light`|`dark`|`auto`) and `data-zx-density` (`cozy`|`compact`) on any ancestor. Define a product theme by overriding semantic `--zx-color-*` / `--zx-control-*` tokens under `[data-zx-theme="name"]`. The theme studio controls accent, neutral tint, density, font, type size, radius, control height, and CSS-first glass material. Never use tier-1 palette tokens or raw color literals in application CSS.
+Load `zx.css` once; set `data-zx-theme` (`light`|`dark`|`auto`) and `data-zx-density` (`cozy`|`compact`) on any ancestor. Define a product theme by overriding semantic `--zx-color-*` / `--zx-control-*` tokens under `[data-zx-theme="name"]`. The theme studio controls accent, neutral tint, density, font, type size, radius, control height, and CSS-first glass material. Compact menus, pickers, tooltips, column menus, and toasts share responsive compact glass; Launcher, Modal, Dialog, and floating Sheets share a calmer reading panel. Both preserve scoped theme inheritance and refract Aurora/page content; docked Sheets and dense data surfaces remain opaque. Never use tier-1 palette tokens or raw color literals in application CSS.
 
 ## Talking to ZeyOS
 Use the dedicated ZeyOS client library **`@zeyos/client`** (`npm install @zeyos/client`) for ZeyOS business data: `createZeyosClient({ platform, auth })`, typed `client.api.list/get/create/update<Resource>` over the full OpenAPI surface, and `normalizeListResult`. Zx accepts the client by injection and does not bundle it. See the `website/layouts/zeyos-invoices.layout.js` layout for a Zx-components-on-@zeyos/client reference. Zx also ships a minimal `Http`/`zeyosService` for ad-hoc in-app `remotecall`, but `@zeyos/client` is the recommended default.
 
+The optional `./zeyos` entry maps schemas into all three record views. `SavedViewRegistry` adds
+private named configurations scoped by authenticated user, workspace/fork (including null for the
+base workspace), and resource through an injected atomic transport. The compatibility transport
+reuses ZeyOS `userfields`; records, selection, pages, callbacks, and DOM are never persisted.
+
 ## Installing
 `npm install @zeyos/zx`. Entry points: `.` (components), `./zeyos` (ZeyOS binding), `./zx.css`
 (styles), and `./global` (classic script tag). Docs: https://zx.zeyos.com

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zeyos/zx",
-  "version": "4.1.1",
+  "version": "4.3.0",
   "description": "Dependency-free JavaScript implementation of the Xenon Design System.",
   "type": "module",
   "license": "MIT",

package/src/components/account-menu/account-menu.css

@@ -60,7 +60,7 @@
   min-inline-size: 220px;
   gap: 2px;
   margin: calc(-1 * var(--zx-space-1)) calc(-1 * var(--zx-space-1)) var(--zx-space-1);
-  border-block-end: 1px solid var(--zx-color-border);
+  border-block-end: 1px solid var(--zx-color-overlay-divider);
   padding: var(--zx-space-3);
 }