@synopackageland/ui 0.20.3 → 0.20.5

package/docs/mobile-native.md

@@ -0,0 +1,502 @@
+# Mobile-native rules
+
+How the UI SDK behaves on a phone (390×844) and a touch tablet (768×1024).
+
+## Width containment and the release gate
+
+Typography tables scroll horizontally within their parent, including a flex
+or grid parent. Wizard footer groups wrap within the wizard; stage topology
+nodes shrink with the available width. Topology card tracks shrink rather
+than force their container wider. FormGroup uses a 12px indent level on a
+touch phone and 28px elsewhere; an explicit CSS length keeps its value.
+Settings switch rows retain a 44px touch target, and a Slider's value bubble
+stays inside its track at both ends. Heading permalinks use the shared touch
+hit area. Text fields inside a BottomSheet are at least 44px tall on touch
+tablets as well as phones. Long Select values ellipsize within the trigger.
+Numeric preset rows are at least 44px tall on touch. The rich text toolbar
+counts its 44px touch buttons when deciding which tools fit; the rest move
+into the existing More menu.
+
+`pnpm check:mobile` checks the gallery at both phone and tablet sizes. It is
+a blocking step of `gates:full`; the basic gate selection stays the same.
+Any remaining audit exceptions are bounded in
+`scripts/fixtures/mobile-overflow-allow.json`, with an audit reference and a
+reason. Normal checks never add exceptions.
+
+
+## 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
+
+### 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` |
+| `--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 (a later change 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
+  the viewport layer. The `check:mobile` script 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
+  (later changes) 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.
+- **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
+
+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
+
+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. On a phone, pickers and long menus open as bottom sheets instead
+(see Pickers and menus on a phone); inline validation comes later.
+
+## Toast, notification and hover-only controls
+
+`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 once pickers move to sheets.
+
+## Forms and inputs
+
+The keyboard depends on each field's type, so these are component defaults,
+not tokens.
+
+### Keyboard hints by type
+
+`Input` sets these from its `type`, and `SearchField` from `search`. An
+attribute of the same name on the component overrides each one.
+
+| `type` | Native type | `inputmode` | Other hints |
+|---|---|---|---|
+| `email` | email | email | `autocapitalize=off spellcheck=false` |
+| `tel` | tel | tel | – |
+| `url` | url | url | `autocapitalize=off` |
+| `integer` (new) | text | numeric | – |
+| `decimal` (new) | text | decimal | – |
+| `password` | password | – | `autocapitalize=off spellcheck=false` (still right once revealed) |
+| `search`, `SearchField` | search | – | `enterkeyhint=search` |
+| `text` and others | as given | – | – |
+
+Use `integer` or `decimal` for numbers typed on a phone. They open the number
+keyboard and skip the native number field's spinner and value parsing.
+`type="number"` stays the native field. `Input` and `SearchField` read
+`--ui-font-size` (15px on a phone), and every field is 16px on a coarse
+pointer (see Tokens and base guards). The clear button (`data-ui-hit`) and the password toggle get the
+44px tap box.
+
+### Next and Done
+
+Inside a `Form`, each `Input` that is the primary control of a `FormItem`
+joins the form's field order, which is document order, taken when the field
+mounts. Disabled and read-only fields are skipped. The last field gets
+`enterkeyhint=done` and the others get `next`. On a coarse pointer, Enter on a
+`next` field moves focus to the next field with `focusWithoutScroll`, so the
+page never jumps. It does not submit the form. With a mouse, Enter keeps the
+browser's behaviour. A caller's own `enterkeyhint` turns both off for that
+field. A `SearchField` keeps `search` and is not part of the order. Other
+controls (`InputSteppers`, `Textarea`) are not in the order yet.
+
+`useFormControl({ keyboard: { type, element, active } })` is how a text
+control opts in.
+
+### Phone form layout
+
+- `Form` with `spacing="auto"` puts 16px between items on a phone. Below
+  400px it already stacks labels over fields.
+- `FormActions` is sticky by default on a phone (narrow and coarse,
+  `usePhone()`, exported). Elsewhere it stays off unless you set `sticky`, and
+  `:sticky="false"` turns it off on a phone too. A sticky bar sits at
+  `bottom: var(--ui-kb-inset, 0px)`, so it rides above the iOS keyboard, and
+  it sets `--ui-scroll-footer` on its scroller so a revealed field clears it.
+  On a phone its bottom padding is `max(12px, safe-bottom)`, or 8px while the
+  keyboard is open.
+- On a phone, `FormActions` buttons share the row equally, and a single
+  button is full width. Put the primary button last so it sits on the right.
+
+## BottomSheet
+
+`BottomSheet` is the one bottom sheet, built on Reka's `Drawer` (reka-ui
+2.11.0). It has a 36×4 grabber in a 20px zone, a 48px header with the title
+and a 44px close button, a body that scrolls with `overscroll-behavior:
+contain`, a pinned footer and safe-area padding. The top corners use
+`--ui-radius-sheet`.
+
+- `height`: `auto` (content, up to 92%), `large` (92%; the strip of page left
+  above it closes the sheet when tapped), `full` (the whole screen, below the
+  top safe area), or a CSS height capped at 92%. `snap-points` passes through
+  to the Drawer.
+- A drag follows the finger. Letting go past 30% of the sheet or faster than
+  0.5 px/ms closes it; otherwise it springs back over
+  `--ui-motion-spring-back` (180ms). The two thresholds are hash-checked
+  patch hunks on Reka (`build/reka-patches.json`); Reka's own defaults are
+  40px and 0.3 px/ms. A drag that starts in the body moves the sheet only when
+  the body is scrolled to the top.
+- The Drawer's keyboard provider publishes `--drawer-keyboard-inset` on the
+  viewport. The viewport pads its bottom by it, so the sheet and its footer
+  sit above the keyboard and the heights shrink instead of the sheet moving
+  off the screen.
+- In 280ms on `--ui-motion-sheet-ease`, out 200ms, the scrim
+  (`--ui-drawer-backdrop`) fading with it. Reduced motion uses an 80ms fade.
+- `confirm-close` (set while a form is dirty) asks "Discard changes?" in a
+  nested sheet before a swipe, Back, Escape, an outside press or the close
+  button closes it. Nested sheets stack, and each closes only itself.
+- On a phone, Back closes the top sheet (`useBackDismiss`); `back-dismiss`
+  overrides that.
+
+`Dialog` on a phone (an app 640px or narrower) renders as a `BottomSheet`:
+`auto`, or `full` for `fullscreen` and for a form with more than 3 fields. The
+CSS-only dialog-as-sheet in `adaptive.css` is gone. `Sheet side="bottom"` is
+a `BottomSheet` everywhere; without `size` it fits its content. Left and right
+sheets are unchanged, and their footer keeps clear of the home indicator.
+an input or swatch. On a phone, pickers and long menus open as bottom sheets instead
+(see Pickers and menus on a phone); inline validation comes later.
+
+## Push navigation
+
+On a phone a detail is a page pushed over the page it came from, not a split
+view. `PushTransition` draws one pushed page:
+
+- It slides in from the right over `--ui-motion-push` (280ms) and pops back
+  over `--ui-motion-pop` (240ms), both on `--ui-motion-sheet-ease`. The page
+  under it (`under`) moves 30% left, dims 10% and is `inert` while covered.
+- Its 48px back header (with `title` or the `title` slot) has Back at the
+  start, the title in the middle and a `header-actions` slot at the end.
+- Back, the browser's Back (Android back, the iOS edge swipe, through
+  `useBackDismiss`) and a swipe that starts within 20px of the page's left
+  edge pop it (`pop`). A swipe let go past 35% of the width or faster than
+  0.5px/ms pops; a shorter one springs back over `--ui-motion-spring-back`.
+- Reduced motion or `data-ui-motion="off"`: no slide or parallax, a fade that
+  the zero durations make instant.
+- With `enabled` off (a split view, a desktop) it shows and hides at once and
+  leaves the page under it alone.
+- The covered page leaves the flow (absolute, clipped to the pushed page) and
+  the pushed page stays in flow, so a container with no height takes the
+  pushed page's height. The container is `position: relative` with
+  `overflow-x: clip`, so the page off to the right never widens the document.
+
+Where it is used:
+
+| Component | Phone (640px or less) | Wider |
+|---|---|---|
+| `ListDetail` | the list fills the room; the detail is pushed over it, with Back in place of Close | the split view, unchanged |
+| `SectionTabs`, five or more sections or `fill` (a settings page) | a grouped list (`group` on each item sets the blocks, 48px rows with a chevron) that pushes the tapped section; `v-model:pushed` | the strip |
+| `SectionTabs`, four or fewer sections | a full-width SegmentControl with equal segments | the strip |
+| `SectionTabs` with `phone="strip"` | the scrolling strip, for tabs inside a pushed page or a sheet | the strip |
+
+`phone` (`auto`, `list`, `segment`, `strip`) overrides the choice. A phone
+is the App's presentation (`mobile`), set by AppRoot or AppLayout. The
+`#actions` slot sits above the section list. A `SettingsPage` inside a pushed
+section keeps its sticky footer.
+
+## RecordPanel and AsidePanel on the BottomSheet
+
+Both panels use `BottomSheet` on a phone, so they share its grabber, drag,
+Back, keyboard inset, scrim and motion. Neither has swipe code of its own.
+
+- `RecordPanel` compact (a host 640px or narrower, or too narrow for a 320px
+  panel beside 240px of view) is a `large` sheet (92%). The record's title
+  names it, and the `header` slot sits next to the 44px close button.
+  `has-previous` and `has-next` add a footer with full-width Previous record
+  and Next record buttons (`@previous`, `@next`). The footer stays above the
+  keyboard and the home indicator. `secondary-open` pushes the comments over
+  the body with `PushTransition`, titled by `secondary-label`. Its Back (the
+  button, the edge swipe or the browser's) closes that page before the sheet
+  and emits `update:secondary-open`. Close reasons are `escape`,
+  `button`, `outside` and `swipe` (a drag or Back).
+- `AsidePanel` on a phone is a `large` sheet with `snap-points` `[0.5, 0.92]`.
+  `expanded` makes it `full`. Its expand button is 44px. The phone button
+  hides while it is open and while a record sheet is open.
+- Neither panel remounts the caller's content. The header, body, thread and
+  composer render once and move between the docked panel, the sheet and a
+  hidden holder. A switch between docked and sheet (a rotation or a resize)
+  keeps fields, focus and caret. A collapsed assistant keeps its draft and
+  thread scroll.
+
+
+## Phone shell
+
+On a phone (`AppLayout` 640px or narrower) the layout draws one bar above
+the page, `--ui-chrome-height` tall (48px on a phone, 44px in a narrow window
+driven by a mouse):
+
+- **Leading:** the menu button, or a Back button when `back` is set (it
+  emits `back`; the app pops its own route). While an `AppTabBar` More tab
+  opens the drawer, the menu button steps aside.
+- **Title:** the `title` prop, else the title of the page's `PageHeader`
+  (the last one mounted in the layout's content column), else the brand. 17px
+  semibold, one line, cut with an ellipsis; centred while nothing follows it,
+  start-aligned beside actions. A `PageHeader` whose title moves into the bar
+  keeps its heading for screen readers only, and takes no room when it has
+  nothing else to show (no description, meta or actions). There is no large
+  collapsing title.
+- **Actions:** `headerActions` (DropdownMenu entries). The first plain entry
+  is one 44px button, its icon (the label is its accessible name) or else its
+  label; the rest open from "…". A pick emits `headerAction` with the key.
+
+Every bar button is a 44px target.
+
+The navigation drawer is Reka's `Drawer` with `swipe-direction="left"`,
+portalled like `BottomSheet` (into the AppRoot in app scope). It is 85% of
+the screen, up to 320px, and mounted only while open. A drag left follows the
+finger and closes past 30% or above 0.5 px/ms, otherwise it springs back; it
+moves in 240ms and out 180ms (`--ui-motion-drawer-in/-out`) with the scrim
+fading, and reduced motion uses an 80ms fade. Escape, a press on the scrim, a
+link in it and Back (`useBackDismiss`) close it; focus goes to its close
+button and returns to what opened it. The page keeps its width.
+
+`AppTabBar` hides while the keyboard is open (`useSoftKeyboard`, confirmed by
+the visual viewport), pads by `--ui-safe-bottom`, and shows at most five
+slots: with more tabs, the fifth is More, which opens a menu of the rest (and
+the drawer, inside an AppLayout with a sidebar). More is marked current when
+the current tab is in it.
+
+## Pickers and menus on a phone
+
+In an app 640px wide or narrower (the same signal that turns a Dialog into a
+BottomSheet), a popup that holds a list, a search, a form, more than five
+actions or a submenu opens as a `BottomSheet` instead of a popover. A touch
+tablet and a desktop window keep popovers. One composable makes the choice
+for every picker: `usePhoneSurface(content)` returns `popover` or `sheet`,
+and `menuContent(items)` counts a menu's first-level actions (separators do
+not count) and finds submenus. Each component keeps one open state, and only
+one surface shows it.
+
+| Component | Phone sheet |
+|---|---|
+| Select, Combobox, MultipleSelect, SuperboxSelect | Titled with the field's label; 48px rows; a search pinned above the list (when the field searches or creates) that is not focused on open. From the first search until the sheet closes it keeps 60% of the screen, so the sheet does not jump as results shrink. The field itself is read-only, so a tap opens the sheet instead of the keyboard. A multiple select toggles rows and closes on Done; a free label is added from an `Add "…"` row or Enter |
+| DatePicker | The calendar with 44px days and 16px time selects, and Done in the footer. A date-only pick still closes it |
+| DropdownMenu, ContextMenu | More than five actions, or any submenu: an action sheet with 48px rows, danger rows in red and a Cancel row. A submenu pushes inside the sheet with a back row. Checkbox rows toggle in place; any other pick closes the sheet. Five actions or fewer stay a popover |
+| ColorPicker | The palette with 32px swatches and 44px Reset and Custom buttons |
+
+Escape, a swipe down and Back each close only the top sheet, and an Escape
+that ends an IME composition in the search closes nothing (the BottomSheet's
+guard). `AdaptivePanel` already follows this rule for its own content: a form
+panel, a sheet once its host is 640px or narrower.
+
+## Pagination and the older tables
+
+These key on the narrow signal (an app 640px or narrower, `usePhonePresentation`),
+because they change layout, not size. Sizes still come from the tokens, so a
+narrow window used with a mouse keeps desktop-sized controls.
+
+**Pagination.** The pager becomes `‹ Page 1 of N ›`: previous and next are
+`--ui-control-md` icon buttons (44px on a phone), the total text sits on the
+left, and there are no first, last or page-number buttons. Tapping the label
+opens a `BottomSheet` with a page field (`type="integer"`, `enterkeyhint=go`)
+and, when `items-per-page` is set, the page sizes as 48px rows. A single page
+without sizes shows the label as plain text. An endless pager shows
+`‹ Page 5 ›`, and its sheet only has the sizes. Above 640px the pager is
+unchanged.
+
+**DataGrid and DataTable.** `mobile-view="auto"` (the default) shows a list
+instead of the table. Each row is at least `--ui-list-row-height` (48px on a
+phone): the title column on the first line, up to two columns joined with `·`
+on the second, and trailing columns at the end. Columns place themselves with
+`list`:
+
+| `list` | Place |
+|---|---|
+| unset | the first column is the title, the next two the subtitle; an `actions` column trails |
+| `title` | the first line |
+| `subtitle` | the second line; marked columns replace the unmarked ones |
+| `trailing` | the end of the row, e.g. a status badge |
+| `none` | not in the list |
+
+The same `cell-*` slots render in the list. `mobile-view="table"` keeps the
+table; DataTable's `cards` keeps the fully labeled cards.
+
+DataGrid only:
+
+- **Select mode.** With `selectable`, a 500ms long press on a row selects it
+  (`onLongPress` from VueUse, cancelled by a 10px move or a scroll). Having a
+  selection is select mode: each row gets a checkbox with a 44px tap box, a tap
+  toggles the row, and a bottom bar replaces the footer with select all, the
+  count, the `selection-actions` slot (`keys`, `rows`, `clear`) and Cancel,
+  which clears the selection. Outside select mode a tap is `rowClick`.
+- **View options.** With a sortable column or `column-chooser`, a bar above the
+  list shows the sort and a button that opens a sheet: sort by (a tap on the
+  sorted column flips it, as the header does) and the columns to show, with
+  Reset columns.
+- **Footer.** The phone `Pagination` (one page per step) with the item count
+  and refresh.
+- Groups and expandable rows work in the list. Row drag reorder, column
+  resizing and column reorder are table-only.

package/docs/release-checks.md

@@ -0,0 +1,28 @@
+# 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.
+
+The full plan includes `check:mobile` at 390×844 and 768×1024. A mobile
+failure returns a nonzero status and blocks that plan, like the other checks.
+The mobile allow-list records only bounded audit exceptions with reasons;
+normal runs never add exceptions.

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`; on a phone the `BottomSheet` dialog) | `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` | the phone button | 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: