@synopackageland/ui 0.20.2 → 0.20.4

package/docs/theme-hooks.md

@@ -46,14 +46,26 @@ here stay implementation details and can change in any release.
 | `data-ui-brand-action` | native button around the default brand when `AppLayout` has a `brand` listener | present |
 | `data-ui-sidebar-body` | wrapper of the `sidebar` slot | present |
 | `data-ui-sidebar-footer` | wrapper of the `sidebar-footer` slot | present |
-| `data-ui-sidebar-collapse` | the web rail's collapse button | present |
+| `data-ui-sidebar-collapse` | the web sidebar's collapse button, at the end of its head row | present |
+| `data-ui-layout-aside` | the right side region holding the `aside` slot | present; `data-ui-aside-state` is `open`, `collapsed`, `expanded` |
+| `data-ui-aside` | `AppLayout` root, when it has an `aside` slot | `open`, `collapsed`, `expanded` |
+| `data-ui-aside-overlay` | `AppLayout` root | `true` while the open aside floats over the page |
+| `data-ui-aside-resize` | the aside's resize handle | present |
+| `data-ui-aside-resizing` | `AppLayout` root | `true` while the aside's handle is dragged |
+| `data-ui-side-moving` | `AppLayout` root | `true` while the sidebar or the aside changes width |
+| `data-ui-aside-panel-root` | `AsidePanel` root inside the aside region | `data-ui-aside-mode` is `docked`, `floating`, `sheet`; `data-ui-aside-floating` while the panel floats or slides away from floating |
+| `data-ui-aside-panel` | the panel (`complementary`, or `dialog` as a sheet) | `data-ui-aside-state` is `open`, `collapsed`, `expanded` |
+| `data-ui-aside-rail` / `data-ui-aside-open` | the 48px rail and its button | present |
+| `data-ui-aside-fab` / `data-ui-aside-scrim` | the phone button and the sheet's scrim | present |
+| `data-ui-aside-collapse` / `data-ui-aside-expand` / `data-ui-aside-restore` | header buttons | present |
+| `data-ui-aside-body` / `data-ui-aside-composer` | the thread scroller and the composer | present |
 | `data-ui-mobile-navigation` | the phone bar above the page | present |
 | `data-ui-mobile-menu` | the phone bar's menu (hamburger) button | present |
 | `data-ui-mobile-sidebar-header` | the drawer's header row | present |
 | `data-ui-mobile-backdrop` | the drawer's backdrop | present |
 | `data-ui-app-toolbar` | `AppToolbar` | present |
 | `data-ui-page-header` | `PageHeader` | present |
-| `data-ui-page-header-meta`, `data-ui-page-header-actions` | `PageHeader`'s meta and actions areas | present |
+| `data-ui-page-header-meta`, `data-ui-page-header-actions`, `data-ui-page-header-description` | `PageHeader`'s meta, actions and description | present |
 | `data-page-surface` | `PageContent` | `auto`, `card`, `flat`, `none` |
 | `data-ui-motion` | set by the app on any ancestor (an `AppRoot`, `<html>`) | `off`: the library's motion is instant inside it, as under reduced motion ([Motion](#motion)) |
 
@@ -95,6 +107,7 @@ here stay implementation details and can change in any release.
 | `data-menu-description` | a `DropdownMenu` entry's second line | present |
 | `data-ui-segment-count` | a `SegmentItem`'s count pill | present |
 | `data-ui-segment-control` | `SegmentControl` | `segment`, `sheet` |
+| `data-ui-segment-size` | `SegmentControl` with `size="sm"` | `sm` |
 | `data-ui-segment-moving` | `SegmentControl` while its selection slides (`.ui-segment-thumb` is shown, the new item's own fill waits) | present |
 | `data-ui-swap` | `MotionSwap` and `AppLayout`'s `main` | present |
 | `data-ui-swapped` | the same, after the first change: plays the rise-in | present |
@@ -103,7 +116,7 @@ here stay implementation details and can change in any release.
 | `data-ui-stat-tile` | `StatTile` (`data-tone`; a filter tile also `data-state` `on` / `off`) | present |
 | `data-ui-stat-tile-label`, `-value`, `-unit`, `-note` | `StatTile` parts | present |
 | `data-ui-stat-tile-group` | `StatTileGroup` | present |
-| `data-ui-page-toolbar`, `-start`, `-actions` | `PageToolbar` and its two sides | present |
+| `data-ui-page-toolbar`, `-start`, `-actions` | `PageToolbar` and its two sides | present; the start side carries `data-overflow-start` and `data-overflow-end` while it continues past an edge |
 | `data-ui-summary-card` | `SummaryCard` (`data-state` `loading`, `error`, `ready`; `data-wide`) | present |
 | `data-ui-summary-card-title`, `-state`, `-figures`, `-figure`, `-body`, `-note`, `-error` | `SummaryCard` parts | present |
 | `data-ui-skeleton` | `SectionSkeleton` | `lines`, `figures`, `rows` (parts `data-ui-skeleton-line`, `-figure`, `-row`) |
@@ -188,14 +201,22 @@ does not animate its rows.
 
 | Token | Value | Use |
 | --- | --- | --- |
-| `--ui-motion-fast` | 120ms | colour and state changes, the tab notch and segment fill sliding, menus opening, anything closing |
-| `--ui-motion-normal` | 180ms | dialogs opening, a new row, a tab panel, switched content and pages, the loading mask |
+| `--ui-motion-fast` | 150ms | colour and state changes, the tab notch and segment fill sliding, menus opening, a dialog closing |
+| `--ui-motion-normal` | 200ms | dialogs opening, a new row, a tab panel, switched content and pages, the loading mask, a card's hover shadow |
 | `--ui-motion-slow` | 240ms | height, notifications and toasts arriving, a sheet sliding in |
+| `--ui-motion-panel` | 300ms | a side region: the web sidebar and its rail, an aside, a record panel |
+| `--ui-motion-exit` | 100ms | a popup, menu or tooltip closing |
+| `--ui-motion-stack` | 200ms (`--ui-motion-stack-ease`) | a toast stack closing up |
+| `--ui-motion-flash` | 1600ms | the tint on something changed elsewhere |
+| `--ui-skeleton-pulse` | 1200ms (`--ui-skeleton-pulse-ease`) | one skeleton pulse |
+| `--ui-motion-drag` | 200ms, `cubic-bezier(0.2, 0, 0, 1)` (`--ui-motion-drag-ease`) | siblings making room while dragging |
+| `--ui-motion-drag-settle` | 260ms, `cubic-bezier(0.2, 1, 0.1, 1)` (`--ui-motion-drag-settle-ease`) | a dropped item settling |
+| `--ui-motion-ease` | `cubic-bezier(0.4, 0, 0.2, 1)` | colour and hover fades |
 | `--ui-motion-ease-out` | `cubic-bezier(0.22, 1, 0.36, 1)` | arriving |
 | `--ui-motion-ease-in` | `cubic-bezier(0.4, 0, 1, 1)` | leaving |
-| `--ui-motion-ease-in-out` | `cubic-bezier(0.4, 0, 0.2, 1)` | height between two resting states |
+| `--ui-motion-ease-in-out` | `cubic-bezier(0.4, 0, 0.2, 1)` | height or width between two resting states |
 
-Under `prefers-reduced-motion: reduce` all of it is instant. To turn it off
+Under `prefers-reduced-motion: reduce` all of it is instant, and every duration token reads 0ms, so script that reads them waits for nothing either. To turn it off
 for part of a page, or the whole App, set `data-ui-motion="off"` on any
 ancestor:
 

package/docs/ux-foundation.md

@@ -0,0 +1,133 @@
+# UX foundation: public contract
+
+The building blocks for app views that settle once and do not move again:
+interaction core, drag kit, side regions and panels, virtual cards, feedback
+and motion. Everything here is imported from a package entry; an App never
+imports a source path.
+
+| Entry | What it holds | Load |
+| --- | --- | --- |
+| `@synopackageland/ui` | every name on this page except the grid | normally |
+| `@synopackageland/ui/grid` | `GridHost`, cell renderers, cell theme, save-status store | lazily, when a grid view first opens |
+| `@synopackageland/ui/theme.css` | tokens, chrome and motion | once, at startup |
+
+```ts
+import {
+  AsidePanel, RecordPanel, AdaptivePanel, StatusSlot, VirtualCardGrid, CardCover, CardField,
+  cardHeight, createDragKit, useDragKit, registerOutsideLayer, createEditSession, motionMs,
+} from '@synopackageland/ui'
+
+const GridHost = defineAsyncComponent(() => import('@synopackageland/ui/grid').then(module => module.GridHost))
+```
+
+A consumer fixture that type-checks and imports every name below from the
+packed tarball is in `tests/ux-foundation-consumer/`
+(`node scripts/check-ux-foundation-consumer.mjs`, after `pnpm build`).
+
+## Defaults and opt-in
+
+Nothing here needs a flag. The compact chrome is the only density.
+
+| What | Default | Opt in or change |
+| --- | --- | --- |
+| Web chrome rows (page header, toolbar, sidebar head and footer) | 48px; window and phone keep 44px | none |
+| Chrome controls / header actions / web nav rows / icons | 28px / 32px / 32px / 16px; icon buttons 4px apart | `--ui-nav-row-height`, `--ui-icon-size` ([theme hooks](theme-hooks.md#layout-and-theme-tokens)) |
+| Full-page (`web`) presentation | off; DSM windows stay `window` at any width | `AppLayout wide-layout="web"`: from a 960px container, sidebar starts as the 48px rail below 1200px |
+| Font | system font stack in the `web` presentation | `--ui-font-sans` |
+| Right side region | none | put an `AsidePanel` in `AppLayout`'s `aside` slot; `v-model:aside`, `v-model:aside-width` |
+| Motion | on, with the tokens in [theme hooks](theme-hooks.md#motion) | `data-ui-motion="off"` on any ancestor; reduced motion reads every duration as 0ms |
+| Popup motion inside a grid editor | 150ms in, 100ms out | `provideOverlayMotion('none')` or `motion="none"` |
+| Canvas grid | not loaded | import `@synopackageland/ui/grid` |
+
+## Copy and accessibility
+
+Built-in labels come from the library's nine locales (en, zh-TW, zh-CN, ja,
+ko, de, fr, es, it) and follow `AppRoot locale` (else its `lang`). Names that only the App
+knows are props, already translated: `AsidePanel title`, `RecordPanel label`,
+`AdaptivePanel title`, `VirtualCardGrid label`, `CardField label`,
+`CardCover alt`, `StatusSlot message`. Every built-in label can be replaced
+(`openLabel`, `collapseLabel`, `expandLabel`, `restoreLabel`, `closeLabel`,
+`resizeLabel`, `retryLabel`). No label ends with a period.
+
+## Side regions and panels
+
+| Component | Use | Main props and events |
+| --- | --- | --- |
+| `AppLayout` `aside` slot | the right side region beside the page | `v-model:aside` (`open` / `collapsed` / `expanded`), `v-model:aside-width` (380, 320–560). The slot gets `{ state, overlay, width, presentation }`. An open aside that would leave the page under 480px floats over it; a phone has no region width |
+| `AsidePanel` | the region's content: 48px rail, docked panel, floating panel, phone sheet | `title`, `icon`, `unread`, `fab`, `expandable`, `initialFocus`, `shortcut`; slots `tabs`, `actions`, default. Never unmounted, so scroll and drafts survive a collapse |
+| `useAsidePreference(key, scope)` | the stored state and width, read before first paint | `readAsidePreference`, `writeAsidePreference`, `clampAsideWidth` |
+| `RecordPanel` | a non-modal record panel docked over the view; the view never changes width | `v-model:open`, `v-model:width`, `storageKey`, `secondaryOpen`, `container`, `compactBelow`, `returnFocus`, `initialFocus`, `flush`; `close(reason)`, `resizeEnd`; slots `header`, default, `secondary` |
+| `AdaptivePanel` | a popover in a wide host, a bottom sheet at 640px and narrower; the content is mounted once | `v-model:open`, `title`, `side`, `align`, `width`, `sheetSide`, `sheetSize`, `compactBelow`, `container`, `motion` |
+
+`APP_ASIDE_KEY` and `APP_SIDE_MOTION_KEY` are injection keys for content that
+must react to the region; `WEB_ASIDE_DEFAULT`, `WEB_ASIDE_MIN`,
+`WEB_ASIDE_MAX`, `WEB_RAIL_WIDTH`, `WEB_RAIL_BELOW`, `WEB_LAYOUT_MIN` and
+`MOBILE_LAYOUT_MAX` are the sizes.
+
+## Feedback
+
+| Name | Contract |
+| --- | --- |
+| `SectionSkeleton` `variant="grid" \| "cards" \| "fields"` | the final geometry from the first frame; shapes show after 300ms |
+| `useToast()` | success 3s, info and warning 5s (at least 5s with an action), danger stays; `pending()` shows after 300ms and becomes its result through `update(id)` |
+| `StatusSlot` | a fixed box for `pending` / `saved` / `error` (with Retry); empty while idle, so nothing moves |
+| `useShowAfter(active, { delay })` | true only once `active` has held for the delay (300ms, `PENDING_DELAY_MS`) |
+| `TOAST_DURATION_MS` | the toast durations by tone |
+
+## Virtual cards
+
+`VirtualCardGrid` renders only the rows on screen. Every card has the height
+`cardHeight({ fields, cover, title })` returns, so nothing is measured, and
+the column count (`galleryColumns(width)`, breakpoints `GALLERY_BREAKPOINTS`)
+is known before the first card renders. The grid emits `range(start, end)` for
+the window to load; an unloaded card is a placeholder of the same size. Put
+`CardCover` in the `cover` slot and `CardField` rows in the body, with the same
+value heights you passed to `cardHeight` (`CARD_VALUE_HEIGHT`, `CARD_METRICS`).
+
+While a side region changes width, the column count holds and settles once at
+the end. `AppLayout` drives this for its sidebar and aside. Anything else that
+moves the width of the main area on purpose calls `useLayoutMotion().track(el)`
+right after it changes the width, or `begin()` and the returned end; a layout
+that only moves its own region gives its children `provideLayoutMotion()`.
+
+## Interaction core
+
+| Name | Contract |
+| --- | --- |
+| `registerOutsideLayer` / `useOutsideLayer` | one window-capture listener; layers are walked from the top, everything above the pressed layer gets `onOutside` once; `'veto'` blocks the press and its click; Escape goes to the topmost layer only |
+| `IGNORE_OUTSIDE_ATTR` (`data-ui-ignore-outside`) | put it on every portal root that belongs to an interactive surface |
+| `createCompositionGuard`, `isComposingKey`, `isPrintableKey` | Enter, Escape and Tab belong to an IME while it composes and for 50ms after (`COMPOSITION_END_GRACE_MS`) |
+| `focusSync`, `createFocusOwner`, `isInForeignDialog` | focus synchronously in the input handler, never out of a dialog the surface does not own |
+| `trackPointerGesture` / `usePointerGesture`, `dropIndexAt` | 5px threshold (`DRAG_THRESHOLD_PX`), pointer capture, release on cancel, blur or dispose |
+| `createEditSession` / `useEditSession`, `editSessionOutside` | `start` / `setDraft` / `setComposing` / `commit` / `cancel`; a validation veto keeps the editor; a commit waits for the composition to end |
+
+## Drag kit
+
+`createDragKit` (Vue: `useDragKit`) runs one drag across registered lanes:
+5px mouse threshold, 250ms touch hold (`TOUCH_HOLD_MS`), Space and arrow keys,
+edge auto-scroll, Escape rollback. Register a lane with
+`kit.lane({ id, element, count, layout })`: give a virtual lane a fixed
+`dragListGeometry` or `dragGridGeometry`; a rendered lane can use
+`dragMeasuredGeometry`. Spread `kit.item(lane, index, key)` on each item.
+`onDrop({ key, from, to })` runs in the release frame: change the local data
+there and return the server write's promise; a rejection calls `onRestore` and
+the item slides home. The geometry types are exported as `DragRect`,
+`DragAxis`, `DragArrangement`, `DragLaneGeometry` and `DragLaneLayout`.
+`createAutoScroll` and `edgeSpeed` give the same edge scrolling to other
+surfaces.
+
+## Motion helpers
+
+`motionMs(token, el?)` reads a duration token (`MotionToken`) as it resolves
+on `el`, 0 when motion is off for it (`motionOff`, `MOTION_OFF_SELECTOR`).
+`transitionMs(el)` is the longest transition on an element.
+`useSwapMotion(target, source)` plays the switched-content rise-in when
+`source` changes; `useInsertedKeys(keys, options)` returns the keys of rows
+that were just added, so only those animate in.
+
+## Third-party code
+
+Parts of this foundation are ports of MIT code from Teable and Baserow. The
+notices are kept in each ported file and collected in
+`LICENSES/ux-foundation.md`; the grid entry's notices are
+`LICENSES/ux-grid-teable.md` and `LICENSES/ux-grid-baserow.md`; its contract is [ux-grid](ux-grid.md).

package/docs/ux-grid.md

@@ -0,0 +1,217 @@
+# Grid range, fill and clipboard
+
+`@synopackageland/ui/grid` draws a canvas grid (a Vue port of Teable's MIT
+grid core) and owns geometry, scroll, selection, focus and pointer feedback.
+It never writes data. Every change a user asks for (an edit, a clear, a fill,
+a paste, a reorder, a width) comes out as an event; the caller applies it to
+its row model as one undoable change and saves in the background.
+
+This page covers range selection, the fill handle, edge auto-scroll, column
+and row drag, column width and the clipboard. Editing is in the `GridHost`
+props (`getEditText`, `cell-commit`); cell painters are in `useGridCells`.
+
+## Range selection
+
+| Gesture | Result |
+|---|---|
+| Press a cell and drag | The range follows every head change and paints in the same task (no frame hop) |
+| Drag past an edge | Auto-scroll: 30 px zone at every edge, also past the grid; speed ramps from 0 to 2000 px/s over 1.2 s; the head is re-derived from the last pointer on every tick, so the range keeps growing while the pointer rests |
+| Over a frozen column | No horizontal scroll, so frozen columns stay targets |
+| Shift+click, Shift+arrow | Keep the anchor, move the head; Cmd/Ctrl+Shift+arrow jumps to the edge |
+| Cmd/Ctrl+A | All cells |
+| Column header click / Shift / Cmd | Select columns, extend, toggle |
+| Row checkbox / Shift, corner checkbox | Select rows, a run of rows, all rows |
+| Esc | Keeps the selection; cancels a drag, a resize or a fill in progress |
+
+Hit-testing is arithmetic over cached column offsets and row heights: a
+pointer move reads nothing from the DOM. Past the last column or row, over a
+header or over blank space, a drag head clamps to the nearest data cell.
+
+`selectionBlock(state, { rowCount, columnCount })` gives the rows and columns
+a selection covers (a row selection covers every column, a column selection
+every row); `cellRange` gives the rectangle of a cell selection.
+
+## Fill handle
+
+Set `fillable`. A cell range shows a 7 px handle at its bottom-right corner
+(21 px hit area, crosshair cursor). Dragging it is vertical only; the preview
+tints the target rows and leaves their values visible; auto-scroll works as
+for a range. On release outside the source rows the grid grows the selection
+to source plus target and emits one `fill-request`:
+
+```ts
+interface GridFillRequest {
+  source: GridCellRange  // the selected block
+  target: GridCellRange  // the new rows only, same columns
+  direction: 'down' | 'up'
+}
+```
+
+`fillSeries(values, count, direction)` builds one column's values: with two
+or more different numbers the steps repeat (dates as epoch milliseconds step
+the same way); anything else repeats the source block. The caller decides the
+field rules (a read-only or computed column is skipped), writes the target as
+one undo entry and may show a "filled N cells" toast with its own text.
+
+Read-only grids and `selectable="none"` show no handle.
+
+## Column and row drag
+
+`draggable` turns on column reorder (drag a header) and row reorder (the row
+drag handle, with the `drag` row control). The drag starts after 5 px; a ghost
+and a 2 px drop line follow the pointer directly. Esc cancels and the release
+does nothing. A drop emits `column-reorder` or `row-reorder` with the dragged
+runs and the drop index counted before they are removed.
+
+## Column width
+
+While a resize is dragged, the width follows the pointer and `column-resize`
+fires on every change. On release `column-resize-end` fires once.
+`column-width-save` fires 300 ms after the last finished resize of a column:
+persist the width there. Esc during a resize restores the width and saves
+nothing. A pending save is sent when the grid unmounts.
+
+## Clipboard
+
+The grid's focus owner (a hidden textarea over the active cell) receives the
+browser's native `copy`, `cut` and `paste` events, so Cmd/Ctrl+C, X and V work
+without permissions, including Safari.
+
+**Copy** writes the selected block as tab-separated text (cells with a tab,
+a line break or a quote are quoted, quotes doubled) plus an HTML table for
+more than one cell. Text comes from `getCopyText`, else `getCellText`. If a
+row of the block is not loaded (`isRowLoaded` false), `resolveCopy(block)`
+must return the text; the write then goes through the async clipboard API
+with promise-valued items, so the user gesture still counts. Without
+`resolveCopy` such a copy fails. `clipboard-copy` reports the block, its cell
+count and `ok`; a successful copy outlines the block with a dashed accent line
+until the next edit, paste, fill or Esc.
+
+**Cut** is a copy that, only when it succeeded, also emits `clear-request` for
+the cut block. A failed or refused write clears nothing.
+
+**Paste** parses `text/plain` into rows and emits `paste-request` with a
+proposal. The grid applies nothing:
+
+```ts
+interface GridPasteProposal {
+  start: GridCell              // top-left of the selection
+  values: string[][]           // fitted to the grid's columns
+  target: GridCellRange        // may reach past the last row
+  cellCount: number
+  extraRows: number            // rows past the last row ("Add N rows")
+  droppedColumns: number       // clipboard columns past the last column
+  readonlyColumns: number[]    // target columns to skip
+  repeated: boolean            // one copied cell filled the selected range
+}
+```
+
+The paste policy is the caller's. Studio applies 50 cells or fewer with no
+type errors directly, as one undo entry, and previews larger pastes or pastes
+with errors.
+
+Everything is data: text that starts with `=`, `+`, `-` or `@` is copied and
+pasted as plain text and never evaluated or rewritten.
+
+A paste goes to the grid only when no built-in editor is open and the event
+target is the focus owner or a hidden element; a visible input, textarea or
+contenteditable in a caller's editor keeps its native paste. A read-only grid
+ignores pastes.
+
+For menu commands, `ref.copy(cut?)` copies through the async clipboard API
+(call it inside the click handler) and `ref.paste(text)` builds a proposal
+from text the caller read itself.
+
+## Touch and phone
+
+Interaction-spec §14, adapted to Teable's touch grid. Two switches, kept
+apart:
+
+- **Touch UI**: `(pointer: coarse)`. No fill handle and no column resize
+  handle are drawn or hit (a 5 px edge is no finger target).
+- **Phone**: touch UI and a grid no wider than 640 px (the container, not
+  the window; `PHONE_MAX_WIDTH`).
+
+Each gesture follows its own `pointerType`: a mouse or pen on a touch-capable
+device keeps every mouse gesture above, and a finger on a desktop gets the
+finger path below.
+
+### Finger gestures
+
+| Gesture | Phone (≤640 px) | Touch tablet (>640 px) |
+|---|---|---|
+| Swipe, any direction | Native pan with momentum (`touch-action: pan-x pan-y`). Never selects, never drags | Same |
+| A press that stops a fling (within 100 ms of a scroll frame) | Only stops it | Same |
+| Tap a cell (released within 6 px and before 250 ms) | Selects the cell and emits `row-expand(row, column)`: open the record sheet scrolled to that field. No editor | Selects the cell. No focus, so no keyboard |
+| Tap the selected cell again | `row-expand` again | Edits: `text` and `number` open in place, take focus and bring up the keyboard. `long-text` and `custom` emit `edit-request` with `trigger: 'tap'`. Read-only cells open the read-only view |
+| Return in a finger-opened editor | — | Commits, moves down, and drops focus so the keyboard goes away |
+| Long press 250 ms (cancelled by a 6 px move) | `context-menu` at the press point, selecting the cell unless it is inside the selection. The release is not a tap | Same |
+| Tap a column header | `header-menu` when the column has a menu, else selects the column | Same |
+| Tap the row header | `row-expand(row)` | `row-expand(row)` with the `expand` control, else toggles the row checkbox. The whole header is one target |
+| Second finger | Cancels the tap and the long press (pinch, two-finger pan) | Same |
+| Range drag, fill, column resize, column or row reorder | None | None |
+
+The pointer is cancelled by the browser when it starts panning; selection
+happens on `pointerup` only. The tapped row or header keeps a pressed tint for
+300 ms. A double tap never edits twice: the compatibility `dblclick`, and
+Android's own long-press `contextmenu`, are ignored for 800 ms after a finger.
+
+### Phone layout
+
+- No frozen data column (the row-number gutter still stays).
+- The gutter is 50 px with row numbers only: `rowControls` are not drawn and
+  not hit; a row-header tap opens the record.
+- Wider screens, touch or not, cap frozen columns so the scrolling part keeps
+  at least 240 px (Teable's `getMaxFreezeColumnCount`).
+- Row and header height follow the density tokens: the DSM 7 theme gives
+  36 px on a coarse pointer unless the app sets `data-ui-density`.
+- The grid draws no append row; the host offers its own add button.
+
+### What the host does
+
+- `row-expand(row, column?)`: open the record. On a phone it is a bottom
+  sheet; when `column` is set, scroll the sheet to that field. Do not focus a
+  field on open.
+- `highlightedRow`: pass the row whose record is open so it stays tinted while
+  the sheet or panel is open; `null` when closed.
+- `edit-request` with `trigger: 'tap'`: the editor must fit the screen;
+  otherwise open the record sheet at that field.
+- `context-menu` from a long press: show the row menu as a bottom sheet on a
+  phone (`AdaptivePanel`), a popover elsewhere. Copy, cut and paste go through
+  `ref.copy(cut?)` and `ref.paste(text)` from that menu: a finger never gives
+  the grid focus, so the keyboard clipboard events do not reach it.
+- `header-menu` from a tap: same sheet-or-popover rule.
+
+## Accessibility
+
+The grid is `role="grid"` with `aria-multiselectable="true"`. One element
+takes focus: the focus owner, labelled by its column header, row header and
+cell text. Selection changes do not move focus out of the grid. Toasts for
+copy, fill and paste come from the caller, translated.
+
+## Release checklist (grid entry)
+
+Before a release that changes `@synopackageland/ui/grid`:
+
+1. `pnpm exec vitest run tests/ux-28-grid-range-clipboard.test.ts tests/ux-grid-touch.test.ts tests/grid tests/grid-core`.
+2. `pnpm typecheck` and `pnpm build`.
+3. Browser checks on the built entry: `node tests/grid/browser-check.mjs`,
+   `node tests/grid/edit-browser-check.mjs`,
+   `node tests/grid/cells-browser-check.mjs`, and
+   `node tests/grid/range-browser-check.mjs <out> chromium` and `... webkit`.
+   The range check fails on any DOM read in pointermove, a range that does
+   not paint in the same task, auto-scroll that stops while the pointer
+   rests past the edge, a moved element between +100 ms and +1500 ms, or
+   scroll frames slower than 50 ms at p95; it records the `dist/grid.js` size.
+4. Touch: `node tests/grid/touch-browser-check.mjs <out>` (Chromium touch
+   emulation at 390x844 and 768x1024, real CDP touch input). It fails when a
+   swipe selects or has no momentum, a tap focuses, a phone tap does not open
+   the record, a tablet second tap does not edit, a finger edit keeps focus,
+   or a long press does not open exactly one context menu.
+5. `node scripts/check-package-content.mjs`: `dist/grid.js` imports only
+   `vue` and `./index.js` and keeps the Teable notice.
+6. Notices: `LICENSES/ux-grid-teable.md` and `LICENSES/ux-grid-baserow.md`
+   ship in the package.
+7. Manual, not covered headless: IME first character in Safari, native
+   macOS Cmd+C/X/V into Excel, Numbers and Google Sheets, and on a real
+   iPhone that a second tap brings up the keyboard and Return puts it away.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synopackageland/ui",
-  "version": "0.20.2",
+  "version": "0.20.4",
   "description": "Shared Vue 3 UI component library with a DSM 7 inspired application theme",
   "license": "MIT",
   "type": "module",
@@ -21,8 +21,13 @@
     "docs/component-defaults.md",
     "docs/json-ui.md",
     "docs/layout-rules.md",
+    "docs/list-detail.md",
+    "docs/mobile-native.md",
+    "docs/release-checks.md",
     "docs/size-and-split.md",
     "docs/theme-hooks.md",
+    "docs/ux-foundation.md",
+    "docs/ux-grid.md",
     "docs/wizard.md"
   ],
   "bin": {
@@ -44,6 +49,10 @@
       "types": "./dist/rich-text.d.ts",
       "import": "./dist/rich-text.js"
     },
+    "./grid": {
+      "types": "./dist/grid/index.d.ts",
+      "import": "./dist/grid.js"
+    },
     "./json-catalog.schema.json": "./dist/json-catalog.schema.json",
     "./json-ai-prompt.md": "./dist/json-ai-prompt.md",
     "./theme.css": "./dist/theme.css",
@@ -71,13 +80,95 @@
     "@tiptap/vue-3": "3.32.1",
     "zod": "^4.6.5"
   },
+  "devDependencies": {
+    "@eslint/js": "10.0.1",
+    "@histoire/plugin-vue": "1.0.0-beta.1",
+    "@tailwindcss/vite": "4.3.3",
+    "@tanstack/vue-virtual": "3.13.39",
+    "@vitejs/plugin-vue": "6.0.9",
+    "@vue/test-utils": "2.5.1",
+    "@vueuse/core": "14.4.0",
+    "eslint": "10.11.0",
+    "eslint-plugin-vue": "10.11.1",
+    "flexsearch": "0.8.212",
+    "globals": "17.12.0",
+    "histoire": "1.0.0-beta.1",
+    "jsdom": "30.1.1",
+    "playwright": "1.58.2",
+    "reka-ui": "2.10.5",
+    "tailwindcss": "4.3.3",
+    "typescript": "5.9.3",
+    "typescript-eslint": "8.71.0",
+    "vite": "7.3.6",
+    "vite-plugin-dts": "5.1.1",
+    "vitest": "5.0.2",
+    "vscode-oniguruma": "2.0.1",
+    "vscode-textmate": "9.3.2",
+    "vue": "3.5.43",
+    "vue-eslint-parser": "10.4.1",
+    "vue-tsc": "3.3.11"
+  },
   "engines": {
     "node": ">=20"
   },
   "config": {
     "bundledRuntime": {
+      "@tanstack/vue-virtual": "3.13.39",
+      "@vueuse/core": "14.4.0",
       "reka-ui": "2.10.5"
     }
   },
-  "homepage": "https://www.varvis.me/docs/"
-}
+  "homepage": "https://www.varvis.me/docs/",
+  "scripts": {
+    "check:docs": "node --test scripts/check-doc-versions.test.mjs && node scripts/check-doc-versions.mjs",
+    "dev": "vite build --watch",
+    "build": "vite build && vite build --mode json && vite build --mode rich-text && vite build --mode grid && vite build --mode cli && vite build --mode preview && vite build --mode embedded && node scripts/postbuild.mjs",
+    "lint": "eslint .",
+    "typecheck": "vue-tsc --noEmit -p tsconfig.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:changed": "echo \"test:changed skips the tests the changes since ${SYNOPKGLAND_GATE_BASE:-origin/master} do not reach (vitest --changed); pnpm check runs them all\" && vitest run --changed ${SYNOPKGLAND_GATE_BASE:-origin/master}",
+    "story": "histoire dev",
+    "story:build": "histoire build",
+    "check:host": "node scripts/dsm-host-shots.mjs",
+    "check:switch": "node scripts/check-switch.mjs",
+    "check:tabs": "node scripts/check-tabs.mjs",
+    "check:mobile": "node scripts/check-mobile-overflow.mjs",
+    "check:narrow": "node scripts/check-narrow-controls.mjs",
+    "check:drawer-form": "node scripts/check-drawer-form.mjs",
+    "check:responsive": "node scripts/check-responsive.mjs",
+    "check:adaptive": "node scripts/check-adaptive.mjs",
+    "check:sidebar-focus": "node scripts/check-sidebar-focus.mjs",
+    "check:json-render": "node scripts/check-json-render.mjs",
+    "check:motion": "node scripts/check-motion.mjs",
+    "check:topology": "node scripts/check-topology.mjs",
+    "check:wizard": "node scripts/check-wizard.mjs",
+    "check:edges": "node scripts/check-edges.mjs",
+    "check:data-grid": "node scripts/check-data-grid.mjs",
+    "check:truncation": "node scripts/check-truncation.mjs",
+    "check:link": "node scripts/check-link.mjs",
+    "check:text-select": "node scripts/check-text-select.mjs",
+    "check:date-picker": "node scripts/check-date-picker.mjs",
+    "check:full-page": "node scripts/check-full-page.mjs",
+    "check:detail-surface": "node scripts/check-detail-surface.mjs",
+    "check:internal": "node --test scripts/check-internal-content.test.mjs scripts/check-npm-metadata.test.mjs && node scripts/check-internal-content.mjs --repo .",
+    "check:npm-metadata": "node scripts/check-npm-metadata.mjs",
+    "check:package": "node scripts/check-package-content.mjs",
+    "check:ux-foundation-consumer": "node scripts/check-ux-foundation-consumer.mjs",
+    "notices:update": "node scripts/third-party-notices.mjs --write",
+    "notices:check": "node scripts/third-party-notices.mjs --check",
+    "check": "bash scripts/docker-check.sh \"npm run gates\"",
+    "check:fast": "bash scripts/docker-check.sh \"npm run gates\"",
+    "check:local-browser": "node scripts/app-local-browser.mjs",
+    "check:infotip": "node scripts/check-infotip.mjs",
+    "release:stage": "node scripts/stage-release.mjs",
+    "check:polish": "bash scripts/docker-check.sh --build --out .polish-shots 'node scripts/check-polish.mjs'",
+    "check:acceptance": "node scripts/check-acceptance.mjs",
+    "check:palette": "node scripts/check-palette.mjs",
+    "gates": "node scripts/gates.mjs",
+    "gates:full": "node scripts/gates.mjs --full",
+    "check:layout": "node scripts/check-layout.mjs",
+    "release:smoke": "node scripts/release-smoke.mjs",
+    "check:browser-install": "playwright install chromium"
+  }
+}