@synopackageland/ui 0.20.3 → 0.20.4

package/dist/virtual/cardHeight.d.ts

@@ -0,0 +1,39 @@
+/** Card box metrics in px (layout-spec §2.6). VirtualCardGrid and CardField draw with these. */
+export declare const CARD_METRICS: {
+    readonly border: 1;
+    readonly padBlock: 8;
+    readonly padInline: 12;
+    /** One title line (14/20). */
+    readonly titleLine: 20;
+    /** Space under the title, and between fields. */
+    readonly gap: 8;
+    /** Field name row: 16 px icon, 12 px muted text. */
+    readonly label: 16;
+    /** Between the name row and the value row. */
+    readonly labelGap: 4;
+};
+/** Value-row heights in px for the common field kinds (interaction-spec §5.1). */
+export declare const CARD_VALUE_HEIGHT: {
+    /** One line of 13/20 text, a checkbox or a 20 px select chip. */
+    readonly line: 20;
+    /** Long text, clamped to two lines. */
+    readonly longText: 40;
+    /** A 24 px link chip. */
+    readonly chip: 24;
+    /** A row of 28 px attachment thumbnails. */
+    readonly attachment: 28;
+};
+export type CardHeightInput = {
+    /** Value-row height of each visible field in order, in px; see CARD_VALUE_HEIGHT. */
+    fields: readonly number[];
+    /** Cover box height in px; 0 when the view shows no cover. */
+    cover?: number;
+    /** Whether the card shows its title row. */
+    title?: boolean;
+};
+/**
+ * The height of every card in a view, computed from its configuration so the
+ * grid knows its rows before any record or image arrives. Each field is a name
+ * row, a value row and the gap after it; the last gap is not counted.
+ */
+export declare function cardHeight({ fields, cover, title }: CardHeightInput): number;

package/dist/virtual/galleryColumns.d.ts

@@ -0,0 +1,11 @@
+/** Container width (px) at which the gallery gains its 2nd…6th column (layout-spec §2.6). */
+export declare const GALLERY_BREAKPOINTS: readonly [640, 768, 1024, 1280, 1536];
+/** Gallery columns for a container `width` px wide; 0 while the width is unknown. */
+export declare function galleryColumns(width: number): number;
+/**
+ * Item indices from `startRow` to `endRow` (inclusive) in a grid of `columns`,
+ * clipped to `count`: `[start, end)`.
+ */
+export declare function rowItems(startRow: number, endRow: number, columns: number, count: number): [number, number];
+/** The index a grid arrow, Home/End or Page key moves focus to from `index`; null for other keys. */
+export declare function cardKeyTarget(key: string, index: number, columns: number, count: number, pageRows: number, ctrl?: boolean): number | null;

package/dist/virtual/layoutMotion.d.ts

@@ -0,0 +1,30 @@
+import { Ref } from 'vue';
+/**
+ * Sanctioned layout motion: a side region (AI panel, sidebar rail) is changing
+ * the width of the main area on purpose. Width-dependent layouts inside main,
+ * such as the gallery column count, hold still while it is active and settle
+ * once when it ends (layout-spec §3.3).
+ */
+export type LayoutMotion = {
+    /** True from the first begin until the last motion has ended. */
+    readonly active: Readonly<Ref<boolean>>;
+    /**
+     * Starts a motion and returns its end. Calling the end again does nothing,
+     * so an interrupted motion may end from several paths. Under reduced motion
+     * nothing starts.
+     */
+    begin: (el?: Element | null) => () => void;
+    /**
+     * Begins a motion for the CSS transition `el` is about to run and ends it on
+     * `transitionend`, on a `transitioncancel` that no new transition replaces,
+     * or after the transition's own duration when neither event arrives. Calling
+     * it again for the same element while it moves restarts the wait instead of
+     * adding a second motion. Call it right after changing the property.
+     */
+    track: (el: Element) => void;
+};
+export declare function createLayoutMotion(): LayoutMotion;
+/** Gives the components below a motion of their own, for a layout that only moves its own region. */
+export declare function provideLayoutMotion(motion?: LayoutMotion): LayoutMotion;
+/** The nearest provided motion, else the document-wide one. */
+export declare function useLayoutMotion(): LayoutMotion;

package/docs/adaptive-layout.md

@@ -6,8 +6,8 @@ The same AppRoot + AppLayout supports three presentations:
 | AppLayout container width | Presentation | Layout |
 | --- | --- | --- |
 | 1–640px | `mobile` | Slide-out accessible navigation, tight page gutters, wrapped header actions, narrow-table cards |
-| 641–1199px | `window` | Original dense DSM window interior, same as before |
-| 1200px or wider, with `wide-layout="web"` | `web` | Full page: collapsible and resizable sidebar, heavier dividers, page content flush beside the sidebar at DSM window padding (no page card), lifted cards on flat pages |
+| 641–959px (any width above 640 without `wide-layout="web"`) | `window` | Original dense DSM window interior, same as before |
+| 960px or wider, with `wide-layout="web"` | `web` | Full page: 48px chrome rows, collapsible and resizable sidebar (it starts as the 48px rail at 960–1199), page content flush beside the sidebar at DSM window padding (no page card), lifted cards on flat pages |
 
 A maximized DSM window is still a DSM window: without `wide-layout="web"`,
 AppLayout stays in `window` mode at any width above 640px. Only a full-page
@@ -41,15 +41,21 @@ scales it down, and AppLayout never sees a phone width. When the app owns the
 whole page, call `ensureDeviceViewport()` once and opt into `web`; leave both
 off inside a DSM desktop window:
 
-```ts
-import { ensureDeviceViewport } from '@synopackageland/ui'
-
-// window.js passes whether DSM launched the AppWindow standalone
-// (appWindow.isStandaloneMainWindow?.() or _S('standalone')).
-const restoreViewport = fullPage ? ensureDeviceViewport() : () => {}
-// <AppLayout :wide-layout="fullPage ? 'web' : 'window'" sidebar-storage-key="myapp">
+```vue
+<!-- window.js passes whether DSM launched the AppWindow standalone
+     (appWindow.isStandaloneMainWindow?.() or _S('standalone')). -->
+<AppRoot :full-page="fullPage">
+  <AppLayout :wide-layout="fullPage ? 'web' : 'window'" sidebar-storage-key="myapp">
 ```
 
+`AppRoot full-page` calls `ensureDeviceViewport()` itself and restores the
+page on unmount; a host without an `AppRoot` can call it directly. The
+viewport it writes is
+`width=device-width, initial-scale=1, viewport-fit=cover, interactive-widget=resizes-content`
+(a device-width viewport already on the page keeps its keys and gains only the
+missing two). Zoom is never locked; fields avoid iOS focus zoom by their 16px
+text instead.
+
 A standalone AppWindow should also drop its desktop `minWidth` (for example
 `minWidth: fullPage ? 320 : 700`) so a phone-width page can reach mobile mode.
 
@@ -59,12 +65,66 @@ for a viewport change. `ensureDeviceViewport()` therefore fires one `resize`
 on the next frame after it changes the viewport (and after it restores it), so
 the window narrows to the phone's width.
 
+## Viewport, keyboard and Back on a phone
+
+A full-page `AppRoot` is the page: it is `100dvh` tall, `html` and `body`
+never scroll and have no overscroll (so no pull-to-reload), and only scrollers
+inside the app scroll. There is no document scroll for iOS Safari to push up
+behind the keyboard. Only use `full-page` when nothing else shares the page
+(a Portal that hides DSM's banner, or a standalone launch).
+
+Every `AppRoot`, full page or not, publishes the visual viewport on its root.
+The variables are read-only and updated once per frame:
+
+| Variable | Value |
+|---|---|
+| `--ui-vvh` | the visual viewport height (what is on screen above the keyboard) |
+| `--ui-vv-top` | how far iOS has panned the visual viewport down |
+| `--ui-kb-inset` | the height the keyboard covers at the bottom of the layout: the iOS keyboard; 0 on Android, where `interactive-widget=resizes-content` shrinks the layout itself |
+| `data-ui-keyboard="open"` | a text field has focus and the viewport lost at least 60px to the keyboard (smaller changes are the URL bar) |
+
+Rules for surfaces:
+
+- A bar pinned to the bottom (sticky form actions, a composer, a footer) uses
+  `bottom: var(--ui-kb-inset, 0px)`; one formula works on iOS and Android.
+- A scroller with a sticky footer sets `--ui-scroll-footer: <footer height>`.
+  While the keyboard is open, the scroller holding the focused field gets
+  `data-ui-kb-room`: its `scroll-padding-bottom` becomes keyboard, footer and
+  16px, and on iOS it gets a spacer so the last field can scroll above the
+  keyboard. The field is scrolled into view inside that scroller, never by
+  scrolling the window. A container that aligns its own fields (the reka
+  Drawer keyboard provider) opts out with `data-ui-keyboard-reveal="off"`.
+- Programmatic focus uses `focusWithoutScroll(element)`:
+  `focus({ preventScroll: true })`, then the same in-scroller reveal.
+- `useSoftKeyboard()` is true at once when a text field gains focus on a touch
+  device, and stays true only if the viewport confirms a keyboard within
+  800ms; with a hardware keyboard it turns false again.
+
+`useBackDismiss(open, close, { enabled })` gives an open phone sheet, drawer
+or pushed page one `history.state` entry (the URL does not change; a router's
+state keys are copied through). The Android back button or the iOS edge swipe
+calls `close` for the top surface only; closing by code removes the entry.
+Pass `enabled: false` where the surface is a popover or inside a DSM window.
+
+`node scripts/check-keyboard.mjs [out-dir]` (after `pnpm build`) checks all of
+this in Chromium at 390 and 768 with touch, with Android emulated by a
+viewport resize and iOS by a stand-in visual viewport. A real-device pass on
+iOS Safari and Android Chrome is still needed (spec D6).
+
 ## Web presentation sidebar
 
-In `web`, the sidebar gets a collapse button at its foot and a resize handle
-on its right edge:
+In `web`, the sidebar's 48px head row ends with a collapse button, and a
+resize handle sits on its right edge:
+
+- At 960–1199px the sidebar starts as the rail. Opening it there lasts until
+  the container leaves that band and is not stored, so the wide-screen
+  preference stays as the user left it.
+- Only the sidebar's width moves (`--ui-motion-panel`, ease-in-out); its rows
+  keep the target width inside, so labels never re-wrap while it opens or
+  closes. Nothing moves before the first paint (the stored width and collapse
+  are read during setup) or while the handle is dragged.
 
-- Collapsed, AppSidebar shows icons only; each label becomes a right-side
+- Collapsed (48px rail), the head row keeps only the expand button and AppSidebar shows icons only; each label becomes a right-side
   tooltip and stays the row's accessible name. Badges move to the icon corner.
 - The handle (`role="separator"`) resizes between 200 and 360px (default 248px)
   by dragging, or with Arrow Left/Right (16px), Home and End when focused.
@@ -79,14 +139,14 @@ on its right edge:
 
 A full page has no DSM title bar, so AppLayout shows the app's logo and name:
 at the top of the sidebar of a `wide-layout="web"` page at any width above a
-phone's (logo only when the web sidebar is collapsed), and in the phone bar
+phone's (not in the collapsed rail, whose head row holds the expand button), and in the phone bar
 and at the top of the drawer. A DSM window shows neither, since its title bar
 already does.
 
 - `brand-name` and `brand-icon` (a URL) name the app. Without them AppLayout
   uses the page's `document.title` and `<link rel="icon">`; with none of these
   there is no brand row. The `#brand` slot replaces the default content.
-- The `#sidebar-footer` slot sits beside the collapse button in web and at the
+- The `#sidebar-footer` slot is the sidebar's 48px foot in web and the
   bottom of the phone drawer (not in a DSM window). `AppSidebarUser`
   (`name`, optional `detail`) shows the signed-in account as an initial avatar;
   collapsed, only the avatar remains, with a tooltip.
@@ -100,6 +160,67 @@ already does.
 </AppLayout>
 ```
 
+## Aside: the right side region
+
+The `#aside` slot is a region at the right edge of the shell, full height,
+for a work panel such as an assistant (`AsidePanel` draws the panel; the
+layout only sizes and moves the region). `v-model:aside` is its state:
+
+| State | Region width | Page |
+| --- | --- | --- |
+| `collapsed` (default) | the 48px rail | takes the rest |
+| `open` | `v-model:aside-width` (380, 320–560; the handle on its start edge, Arrow keys, Home and End) | takes the rest |
+| `open` that would leave the page under 480px, or outside `web` | the 48px rail; the panel floats over the page (`overlay`) | unchanged |
+| `expanded` | the whole content area beside the sidebar | `inert`, kept mounted |
+
+On a phone the region has no width; its content places itself (a button and a
+bottom sheet). The slot receives `state`, `overlay`, `width` and
+`presentation`; the region sets `--ui-aside-open-width` so the panel can keep
+its width while the region moves. Dragging writes the width on release.
+
+### AsidePanel
+
+`AsidePanel` is the slot's content. It reads the state from the layout (no
+props to forward) and writes it back through `v-model:aside`:
+
+```vue
+<script setup lang="ts">
+import { AppLayout, AsidePanel, useAsidePreference } from '@synopackageland/ui'
+// Read during setup, so the first paint has the stored state; the app picks the scope.
+const { state, width } = useAsidePreference('studio.aside', 'editor', { state: 'open' })
+</script>
+
+<AppLayout v-model:aside="state" v-model:aside-width="width" wide-layout="web">
+  ...
+  <template #aside>
+    <AsidePanel :title="t('IT assistant')" :icon="Sparkles" shortcut="Ctrl+J">
+      <template #tabs>…a SegmentControl size="sm", only with more than one surface…</template>
+      <template #actions>…a ⋯ menu…</template>
+      …the thread…
+      <template #composer>…the composer…</template>
+    </AsidePanel>
+  </template>
+</AppLayout>
+```
+
+| Mode | When | Panel |
+| --- | --- | --- |
+| docked | `web`, the page keeps 480px | keeps `--ui-aside-open-width` and slides by `translate` while the region's width moves (`--ui-motion-panel`, ease-in-out both ways); the rail button fades in 150ms into a collapse |
+| floating | an open panel the page has no room for, or a 641–959 container | slides over the page from the rail (in `panel` ease-out, out `normal` ease-in); the region keeps its 48px |
+| sheet | a phone (≤640) | a 48px button at the end corner (above the tab bar and the safe area) opens a 90% bottom sheet; `expanded` is full screen; the scrim, Escape and a downward swipe on the header close it; the page is inert |
+
+- The panel is never unmounted: collapsed, it is `inert` and `aria-hidden`, and the thread's scroll and the composer's draft stay. The page is `inert` while the panel is expanded or a sheet is up.
+- Focus moves to the composer's first field on open (not on touch, `initial-focus` changes it) and back to the rail button or the phone button on collapse.
+- Escape: docked and expanded leave it to the content (stop a reply). A floating panel with focus inside, or a sheet, collapses on Escape after any layer opened above it (a menu, a popover) has closed.
+- No transition runs before the first paint has settled. The state needs no `transitionend`: only a floating panel's exit waits for one, with the `normal` token as its deadline, and a new state change or reduced motion ends it at once.
+- Labels: "Open {name}", "Collapse {name}", "Expand {name}" and "Restore {name}" with the title, in the nine locales; `open-label`, `collapse-label`, `expand-label` and `restore-label` replace them. The app binds its shortcut and calls the exposed `toggle()`.
+- `useAsidePreference(key, scope, defaults)` keeps `{"v":1,"<scope>":{"state","width"}}` in localStorage, written on each change (the width only when a drag ends); other fields in a scope's entry are kept. `readAsidePreference` reads it synchronously for a pre-paint script.
+
+Both side regions share one motion signal: `inject(APP_SIDE_MOTION_KEY)` is
+true while the sidebar or the aside changes width (the shell also carries
+`data-ui-side-moving`). Content that measures itself (a canvas grid, a chart,
+a column count) waits for false and then measures once.
+
 ## Usage
 
 ```vue
@@ -124,7 +245,7 @@ import {
 ```
 
 - `AppLayout` defaults to `wide-layout="window"`. Set `wide-layout="web"` on
-  a full-page Portal to enable the full-page layout at 1200px or wider.
+  a full-page Portal to enable the full-page layout at 960px or wider.
 - `AppLayout` defaults to `responsive=true`. Set `:responsive="false"`
   only if the host application intentionally implements its own complete responsive shell.
 - `PageContent surface="auto"` puts the page straight on the content area: flush
@@ -235,7 +356,7 @@ any ancestor. Light defaults and the dark values the workbench uses:
 | `--ui-app-web-surface` | `var(--ui-surface)` | `var(--ui-surface)` (`#1f2832`) |
 | `--ui-app-web-border` | `var(--ui-border)` | `#34404d` |
 | `--ui-app-web-shadow` | `var(--ui-shadow-card)` | `var(--ui-shadow-card)` |
-| `--ui-web-sidebar-collapsed-width` | `64px` | same |
+| `--ui-web-sidebar-collapsed-width` | `48px` | same |
 
 `AppLayout navigation="top"` puts the navigation in a bar above the page in the
 window and web presentations (a phone keeps the drawer); its colours and the

package/docs/callout.md

@@ -6,7 +6,7 @@ has its own component, and none of them is a full-width banner.
 
 | The message | Use | Shape |
 | --- | --- | --- |
-| A passing result: "Settings applied", "The check passed", "Copied" | `useToast()` | A toast that fades after 4.5 s. Do not leave a Callout behind for it. |
+| A passing result: "Settings applied", "The check passed", "Copied" | `useToast()` | A toast at the bottom right: success fades after 3 s, info and warning after 5 s (at least 5 s with an action), an error stays until closed. Do not leave a Callout behind for it. |
 | Something the user has to act on: a missing setting, a failed connection, a sign-in that waits | `<Callout>` | One-line title, at most one line of text, one action. |
 | A risk or a limit of a feature | `<Callout variant="inline">` | One short sentence; longer text in `#details` behind "Learn more", or a link. |
 | A state of the page that fits its toolbar row: "Two devices are offline", "Read only" | `<Callout variant="hint">` | The icon and a few words on one line; the details in a tooltip. |
@@ -160,6 +160,27 @@ and without an action, light and dark, and on a settings page:
   toast.success('Settings applied', 'Added port 6690')
   ```
 
+- Work in progress keeps one toast id from start to result. A pending toast
+  shows only if the work takes longer than 300 ms, has no timer, and turns
+  into its result in place; an error's Retry can turn it back into pending:
+
+  ```ts
+  const id = toast.pending('Deleting')
+  try {
+    await remove()
+    toast.update(id, { title: 'Deleted', tone: 'success', actionLabel: 'Undo', onAction: restore })
+  } catch {
+    toast.update(id, { title: 'Could not delete', tone: 'danger', actionLabel: 'Retry', onAction: retry })
+  }
+  ```
+
+  An action click closes the toast unless its handler updated it. Timers
+  pause while the pointer is over the stack or focus is in it; F8 moves
+  focus to the stack, so its actions are reachable by keyboard.
+- A status that belongs to a place on the page (a form's "Saving" / "Saved",
+  a field's error with Retry) goes in a `StatusSlot`: a fixed box rendered
+  from the start and empty while idle, so the status never pushes content.
+
 - Put a machine error code in `code`, not in the text.
 - Stack at most two Callouts in one section. More means the page should show
   the state in its content (a `Badge`, a `KeyValueRow`) instead.

package/docs/list-detail.md

@@ -0,0 +1,54 @@
+# ListDetail
+
+A list with the selected item's detail beside it, as DSM's own list pages show
+one (a Recycle Bin page with the selected shared folder's oldest items, a
+Packages page with the selected package's advice).
+
+```vue
+<ListDetail :title="selected?.name" storage-key="recycle" @close="selectedKeys = []">
+  <DataGrid v-model:selected-keys="selectedKeys" :columns="columns" :rows="rows" row-key="id" single-select footer />
+  <template v-if="selected" #detail>
+    <p>{{ selected.summary }}</p>
+    <DataGrid :fill="false" :columns="itemColumns" :rows="items" row-key="id" footer />
+  </template>
+</ListDetail>
+```
+
+- The default slot is the list; it takes the room the pane leaves and keeps at
+  least `list-min-width` (360px).
+- The pane shows while the `detail` slot is given (a `v-if` on the slot opens
+  and closes it), or while `open` is true. With `title` it has a header with the
+  title and a Close button that emits `close`; `:closable="false"` drops the
+  button and a `header` slot replaces the title.
+- The pane is white with a 1px border and no shadow. It is not a `Surface`, so
+  an `auto` page stays white when it opens and only the selected row is
+  tinted, even when another App built with an older release shares the DSM
+  document ([adaptive layout](adaptive-layout.md)).
+- The separator between list and pane is dragged with the pointer
+  (`col-resize` cursor) or moved with the keyboard: ArrowLeft widens the pane
+  by 16px and ArrowRight narrows it (64px with Shift), Home makes it as wide
+  as the list allows and End as narrow as `min-width` (280px). A double click
+  goes back to the default. It is a `role="separator"` with
+  `aria-orientation="vertical"`, `aria-controls` naming the pane, and the
+  pane's width in px as `aria-valuenow` between `aria-valuemin` and
+  `aria-valuemax`.
+- `default-width` is the width before the user sets one: a share of the room
+  (default `0.4`, kept between 400px and 640px) or a width in px.
+- The width the user sets is remembered in `localStorage` under
+  `syno-pkg-land-ui:detail-width:<app>:<storage-key>`, where `<app>` is the
+  DSM package (or the page's host and directory) as for
+  [closed callouts](callout.md). Without `storage-key` the App's panes share
+  one width. An unreadable or blocked storage falls back to the default.
+- Narrower than 640px of room the pane goes above the list, full width, and
+  the separator is hidden.
+- In the pane, give tables column widths that fit the default width and dates
+  in a one-line short format; a table wider than the pane scrolls sideways.
+
+Hooks: `data-ui-list-detail` (with `data-open` and `data-dragging`),
+`data-ui-list-detail-list`, `data-ui-list-detail-separator`,
+`data-ui-list-detail-pane`, `data-ui-list-detail-close`; the pane's width is
+`--ui-list-detail-width`.
+
+| Default width (1320px window) | Dragged wider | Wide window (1860px) |
+|---|---|---|
+| ![](screenshots/detail-after.png) | ![](screenshots/detail-dragged.png) | ![](screenshots/detail-wide.png) |

package/docs/mobile-native.md

@@ -0,0 +1,214 @@
+# Mobile-native rules
+
+How the UI SDK behaves on a phone (390×844) and a touch tablet (768×1024).
+
+
+## Signals
+
+| Signal | Where it comes from | What keys on it |
+|---|---|---|
+| Narrow | the app root is 640px wide or narrower: AppRoot sets `data-ui-presentation="mobile"`, AppLayout `data-ui-layout-mode="mobile"` | layout shape: drawer, sheets (as before) |
+| Phone | narrow **and** `(pointer: coarse)` | phone tokens (type, control height, spacing, rows, header) |
+| Touch | `@media (pointer: coarse)` | 16px fields, 44px tap boxes, tap feedback, touch-tablet control sizes |
+| Hover | `@media (hover: hover)` | every hand-written `:hover` rule in the theme |
+
+A touch tablet at 768px gets the touch rules but not the phone tokens. A
+desktop gets neither, so it looks exactly as before. That includes a DSM
+window or browser window narrowed below 640px and used with a mouse: it keeps
+the narrow layout with desktop sizes. The phone tokens need a coarse pointer
+too, because without that gate the 1280 gallery's narrow solo shots changed.
+
+Every touch rule is keyed on `[data-ui-app]`, the root every app has (AppRoot).
+Before this change they were keyed on `[data-ui-theme='dsm7']`. Nothing sets
+that attribute (Studio sets its own theme name), so the rules never applied.
+
+## Tokens and base guards (M-1)
+
+### Type and size tokens
+
+Each size is one token, so changing a size changes one line. Phone values are
+set in `src/theme/adaptive.css` (the phone block), touch values in the
+`@media (pointer: coarse)` blocks of `adaptive.css` and `dsm7.css`, and
+desktop values in `dsm7.css`. An explicit `data-ui-density` keeps the app's
+control and grid sizes; it does not change the 16px field rule.
+
+| Token | Desktop | Touch tablet | Phone | Used for |
+|---|---|---|---|---|
+| `--ui-font-size` | 13 | 13 | **15** | primary text: list and record titles, field values, body copy, menu items |
+| `--ui-font-size-sm` | 12 | 12 | **13** | secondary text: labels, meta, captions, helper text, badges |
+| `--ui-font-size-xs` (new) | 12 | 12 | 12 | the smallest text anywhere |
+| `--ui-line-height` | 20 | 20 | **22** | body line |
+| `--ui-font-size-title` | 16 | 16 | **17** | header and dialog titles |
+| `--ui-grid-font-size` (new) | 13 | 13 | **14** | grid cell text (not yet read by the canvas grid; see below) |
+| `--ui-font-size-field` (new) | 16 | 16 | 16 | every field on a coarse pointer, to stop iOS focus zoom |
+| `--ui-control-md` | 28 | **36** | **44** | fields, selects, form and sheet buttons |
+| `--ui-control-sm` | 24 | **32** | **36** | inline and toolbar buttons (the tap box comes from `--ui-hit-min`) |
+| `--ui-hit-min` (new) | 0 | **44** | **44** | smallest tap box |
+| `--ui-tap-gap` (new) | 0 | **8** | **8** | room between tap targets; `--ui-icon-button-gap` reads it on touch |
+| `--ui-grid-row-height` / `-header-height` | 28 | **36** | **32** | canvas grid rows (docs/ux-grid.md) |
+| `--ui-list-row-height` (new) | 32 | **44** | **48** | list rows |
+| `--ui-menu-row-height` | 32 | **40** | **48** | menu, select and sheet list rows |
+| `--ui-page-padding-x` / `-y` | 16 (narrow layout 12) | 16 | **16** | page gutter |
+| `--ui-section-gap` | 12 | 12 | **20** | space between sections |
+| `--ui-card-padding` | 20 (Card default) | 20 | **16** | card inset |
+| `--ui-chrome-height` | 44 (web 48, narrow layout 44) | – | **48** | the phone header |
+| `--ui-radius-sheet` (new) | 12 | 12 | 12 | top corners of a bottom sheet |
+| `--ui-safe-top/right/bottom/left` (new) | `env(safe-area-inset-*, 0px)` | same | same | notch and home indicator; non-zero only once the viewport meta has `viewport-fit=cover` (M-2) |
+| `--ui-pressed` (new) | 8% of the text colour | same | same | the pressed tint |
+
+Density comes from spacing, not smaller text: phone rows are 44–48px, and
+components add no padding beyond the tokens.
+
+Phone motion tokens (all read 0ms under reduced motion or `data-ui-motion="off"`):
+
+| Token | Value | Use |
+|---|---|---|
+| `--ui-motion-sheet-in` / `-out` | 280 / 200ms | bottom sheet |
+| `--ui-motion-sheet-ease` | `cubic-bezier(0.32, 0.72, 0, 1)` | sheet, push |
+| `--ui-motion-drawer-in` / `-out` | 240 / 180ms | side drawer |
+| `--ui-motion-push` / `-pop` | 280 / 240ms | push navigation |
+| `--ui-motion-spring-back` | 180ms | a sheet released above its close threshold |
+| `--ui-motion-press` | 150ms | pressed tint fading out (it shows at once) |
+
+### Base guards (`preflight.css`)
+
+These rules are in the base layer at zero specificity (`:where()`), so any
+component rule overrides them.
+
+- No blanket `min-width: 0`. The spec asked for one, but the 1280 gallery
+  diff showed it squeezing nowrap rows (Space "wrap off" went one letter per
+  line) and a fixed-size brand icon on the desktop. A component whose flex
+  child must shrink sets `min-w-0` on it instead (M-13 handles the remaining
+  width offenders).
+- `overflow-wrap: break-word` on the app root. A word longer than its line
+  breaks. We use `break-word`, not `anywhere`, because it only breaks text
+  that would overflow and never changes how wide a table column or flex item
+  wants to be. Desktop layouts stay the same.
+- `img`, `video` and `iframe` get `max-width: 100%`, and `img` and `video` also
+  get `height: auto`. `svg` is left alone so icons keep their size.
+- Don't write `100vw` in components. Use `100%` or the viewport variables from
+  M-2. The `check:mobile` script (M-12) enforces this.
+
+### Tap feedback (`touch.css`)
+
+- Buttons, links, labels and every element with a button, tab, option,
+  menuitem, switch, checkbox, radio or treeitem role get
+  `-webkit-tap-highlight-color: transparent` and `touch-action: manipulation`.
+  This removes the grey flash and the 300ms double-tap wait. Pinch zoom still
+  works. A component's own `touch-none` overrides it.
+- Pressed tint on a coarse pointer: an inset `--ui-pressed` shadow appears
+  while the finger is down and fades over `--ui-motion-press`. Button and
+  IconButton draw their own pressed state (`data-variant`), so they're
+  skipped. A component that sets its own shadow or `active:` style also keeps
+  its own.
+- Hover: every hand-written `:hover` rule in the theme sits inside
+  `@media (hover: hover)`, so a tap leaves no stuck hover look. Tailwind's
+  `hover:` utilities already do this.
+
+### Hit area (`hit-area.css`)
+
+On a coarse pointer, a control smaller than `--ui-hit-min` keeps its drawn
+size, and an invisible `::before` grows its tap box evenly on all sides to the
+minimum:
+
+```css
+inset-block: min(0px, calc((100% - var(--ui-hit-min)) / 2));
+inset-inline: min(0px, calc((100% - var(--ui-hit-min)) / 2));
+```
+
+These controls get the hit area:
+
+- **Marked with `data-ui-hit`:** `Button`, `IconButton`
+- **Matched by role or attribute:** `button[role=checkbox]` (Checkbox),
+  `button[role=radio]` (Radio, ToggleButton), `button[role=switch]` (Switch),
+  `[data-tag][role=button]` (a tappable Tag), `[data-tag-remove]`,
+  `[data-ui-password-toggle]`
+
+A new tappable control can opt in by adding `data-ui-hit`. When two tap boxes
+overlap, the later control wins the overlap. Clusters keep `--ui-tap-gap`
+between controls. The rule sits in the base layer, so a component that sets
+its own `position` or draws its own `::before` keeps it, and loses the larger
+tap box.
+
+### Not done in this layer
+
+- **Hardcoded font sizes:** components that write a literal size, such as
+  `text-[13px]` in Checkbox, Switch, Radio, Input and the menu rows, don't
+  pick up the 15px phone text until they read `--ui-font-size`. Their owners
+  (M-5, M-10, M-13) switch them over. Fields are already 16px on touch.
+- **Canvas grid:** the grid draws text at fixed sizes from
+  `src/grid-core/theme.ts`. Reading `--ui-grid-font-size` needs a change in
+  the grid.
+- **Form gap:** `Form` writes its own `--ui-form-gap` inline, from
+  `--ui-field-gap`. The 16px phone form gap belongs to Form (M-10).
+- **Hover rules in `adaptive.css`:** the brand action, sidebar collapse and
+  resize handles still use plain `:hover`. They belong to the shell tasks.
+
+## Floating layer (M-3a)
+
+Every anchored popup is placed by one preset, `src/components/primitives/popover/floating.ts`, on Reka's popper (floating-ui flip, shift, size and hide). A component binds it on its Reka `*Content` and never picks its own collision props.
+
+| Setting | Value |
+|---|---|
+| Boundary | the app window in app scope (`useCollisionBoundary`), else the visual viewport (Reka's root boundary for fixed popups) |
+| Padding | 8px from each edge, plus `--ui-safe-*` (or `env(safe-area-inset-*)`), plus `--ui-kb-inset` at the bottom. Read when the popup opens and again on a visual-viewport resize |
+| Shift | `sticky: 'partial'` |
+| Detached anchor | `hideWhenDetached`: the popup hides once its anchor has left the boundary |
+| Max size | `FLOATING_SIZE_CLASS`: `--reka-popper-available-width` and `-height`. Never `100vw` |
+| Autofocus | none on a coarse pointer (`skipAutoFocusOnTouch` in `overlay.ts`) |
+
+```vue
+<script setup lang="ts">
+import { FLOATING_SIZE_CLASS, useFloating } from '@/components/primitives/popover/floating'
+const floating = useFloating(() => trigger.value?.$el, () => open.value)
+</script>
+<SomeContent v-bind="floating" :class="[ownClasses, FLOATING_SIZE_CLASS]" />
+```
+
+**Portal layer.** `src/theme/floating.css` makes the AppRoot `[data-ui-portals]` layer `position: absolute; inset: 0; overflow: clip; pointer-events: none`. It covers the app root exactly, so app-local dialogs keep the app as their containing block, and nothing in it can add page width or height. Its direct children take presses again; Reka's inline `pointer-events` still wins while a modal surface is open.
+
+**Tooltip on touch.** `openOnTap` defaults to on with a coarse pointer: a tap toggles the tooltip and a tap anywhere else closes it. Pass `:open-on-tap="false"` when the tap must only run the trigger's action.
+
+**Uses it today:** Popover, Tooltip, OverflowTooltip and all anchored popups listed below.
+
+## All anchored popups (M-3b)
+
+Menus (including nested menus and Breadcrumb), Select and the shared ComboboxField,
+DatePicker, ColorPicker, InputSteppers presets, InfoTip, ValidationPopup,
+MentionList and OverflowToolbar now use the floating preset above. SplitButton,
+MultipleSelect and SuperboxSelect inherit it through their shared primitives.
+Menu sublevels inherit the parent's live padding, so an open submenu follows
+safe-area and keyboard changes. Preferred and trigger widths are capped by
+`--reka-popper-available-width`; lists scroll within the available height.
+Opening a searchable Select, calendar or palette on touch does not autofocus
+an input or swatch. Phone bottom sheets and inline validation remain M-5 work.
+
+## Toast, notification and hover-only controls (M-11)
+
+`usePhone()` (`src/composables/phone.ts`) is the phone signal in script: the
+enclosing AppRoot is narrow and the pointer is coarse, the same test as the
+phone tokens. A provider sets `data-ui-phone` from it, and the placement rules
+are in `src/feedback/feedback.css`.
+
+| | Desktop, tablet, narrow window with a mouse | Phone |
+|---|---|---|
+| Toast | bottom right, 360px, swipe right, a stack | bottom, 8px from each side, above the visible tab bar or the keyboard (`--ui-kb-inset`), whichever is higher, plus `--ui-safe-bottom` and 8px; swipe down; only the newest shows, with a `+N` count of the others still open |
+| Notification | the chosen corner, 360px | top, 8px from each side, below `--ui-safe-top` plus 8px; `alignment` is ignored |
+
+- Toasts behind the front one keep their own timers, so a short one can
+  expire unseen. Danger toasts stay until closed and come forward in turn.
+- Toast and notification text reads `--ui-font-size` and
+  `--ui-font-size-sm` (13/12 on a desktop, 15/13 on a phone). A static
+  Notification card no longer has a 320px minimum width.
+- Neither provider writes `100vw` any more.
+
+**Hover-only controls.** VirtualCardGrid card actions, the ScheduleTable edit
+pen and the TypoHeader anchor carry `[@media(hover:none)]:opacity-100`, so a
+touch screen shows them at rest. A component that hides a control until hover
+does the same.
+
+**Card long press.** On touch, holding a VirtualCardGrid card for 250ms opens
+the card's context menu (`menuItems`) through Reka's long press
+(`ContextMenu` `pressOpenDelay`). The click that ends that press doesn't open
+the card. A card without entries opens no menu. The menu is the plain
+context menu for now; it becomes a phone sheet through M-5's rule.

package/docs/release-checks.md

@@ -0,0 +1,23 @@
+# Release checks
+
+`npm run gates` runs basic release checks. `npm run gates:full` adds browser,
+workbench and registry consumer integrations only when explicitly requested.
+`SPL_FULL_GATE=1` aliases `--full`. `npm run gates -- --plan` prints the exact
+selection without running checks. `pnpm check` and `pnpm check:fast` run basic
+checks through the optional build-isolation wrapper.
+
+| Entry point | Default | Explicit full |
+| --- | --- | --- |
+| `npm run gates`, `scripts/gates.mjs` | Internal-content checks, build, lint, typecheck, unit tests, notices, isolated pack and tarball content audit | Adds Chromium installation, responsive/adaptive/date-picker/JSON/host/switch/layout/InfoTip/motion browser checks, Histoire build, exact-tarball registry consumer smoke |
+| `pnpm check`, `check:fast` | Basic, with optional Docker host build isolation | `SPL_FULL_GATE=1` selects the same full plan |
+| `fast-ci.yml`, composite verify action | Basic | No automatic extended checks |
+| Disabled CI/release workflow templates | Basic, version/tag/ancestry checks, stage, pack and actual archive audit | No implicit browser or registry consumer smoke |
+| `scripts/stage-release.mjs`, `release:stage` | Validate existing dist and copy allowlisted publication inputs | No gate invocation |
+| `scripts/ci-release.mjs preflight/audit/dry-run` | Release metadata, archive checks or credential-free npm validation | No browser/workbench/consumer integration |
+| `scripts/ci-release.mjs smoke`, `release:smoke` | Explicit manual consumer integration | Included in full; release:smoke requires full opt-in |
+| `prepack`, `prepublishOnly` | No hooks defined | No hidden gate invocation |
+
+Stage the package only after a successful build/basic check. Preserve version,
+ancestry, immutable-publication, metadata and credential boundaries. Registry
+availability checks needed to publish are distinct from optional consumer tests.
+No full-gate stamp is required for publication.