@synopackageland/ui 0.20.3 → 0.20.5

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
@@ -149,20 +270,22 @@ import {
   remove a child Card's frame or a PageHeader's own vertical padding. The JSON
   `Page` accepts the same value. SDK `AppShell` consumers need that package to
   expose/forward the option to its internal `PageContent`.
-- `DataTable` defaults to `mobile-view="auto"`, switching to accessible labeled
-  cards in the **App's mobile presentation**. A narrow table within an ordinary
+- `DataTable` defaults to `mobile-view="auto"`, switching to a list (a row per
+  item: title, subtitle, trailing column; see docs/mobile-native.md) in the
+  **App's mobile presentation**. A narrow table within an ordinary
   700px/800px DSM Window stays a table, even if its content area is below
   640px. When no AppRoot/AppLayout provides a presentation, DataTable falls
-  back to its own width (640px or less). It preserves *all* columns,
-  custom `cell-*` slots and actions. `mobile-view="table"` retains horizontal
-  scrolling for dense/interactive data; `cards` forces cards at every size.
+  back to its own width (640px or less). `mobile-view="table"` retains horizontal
+  scrolling for dense/interactive data; `cards` shows every column as fully
+  labeled cards at every size.
   Explicit column `width` values (CSS pixels or percentages) use fixed table
   tracks; columns without a width share the remaining space. Long text wraps
   inside those tracks. Tables without widths retain automatic sizing.
-- `DataGrid` retains its desktop semantics (sorting, editing, selection,
-  keyboard navigation, reorder) and horizontally scrolls at narrow widths.
-  Avoid silently removing columns or disabling actions. Use a mobile alternative
-  for very complex tables rather than degrading a grid's editing model.
+- `DataGrid` shows the same phone list in the App's mobile presentation
+  (`mobile-view="auto"`): long press selects, and sorting and columns move into
+  a sheet. `mobile-view="table"` keeps the table, which scrolls horizontally.
+  Use a mobile alternative for very complex tables rather than degrading a
+  grid's editing model.
 - `ResponsiveView` renders a `mobile`, `window`, or `web` slot when available.
   The `default` slot is the fallback for all unprovided modes, so features aren't
   accidentally hidden. Only the active variant is mounted.
@@ -235,7 +358,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/app-local-modal.md

@@ -146,7 +146,7 @@ root and inside the active panel, or use the library's supported popup component
 
 ## Delivery and patch maintenance
 
-Reka 2.10.5 is an exact development dependency, bundled into the UI library's
+Reka 2.11.0 is an exact development dependency, bundled into the UI library's
 ESM dist. It is no longer a consumer runtime dependency. Vue remains an external
 peer, and the bundled code uses that same Vue instance. Consumers receive the
 body-style fix by rebuilding, without a package-manager patch or app code change.

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/layout-rules.md

@@ -72,6 +72,20 @@ The setting is a form value, saved with the page's Apply action. It does not nav
 - A settings page has one Apply. Put Reset then Apply in `SettingsPage`'s `#footer`, at the bottom-right, as Control Panel does. Keep the footer while the page has settings to apply, so nothing moves when a draft changes. Do not put a Save between the fields of a section.
 - A button that belongs to a field (Allowed websites, Trusted Proxies, Advanced Settings) is a grey `Button variant="secondary"` in the flow: in the `FormGroup` it depends on, after the field it acts on (`#after`), or under the section's description.
 
+## Choosing tabs on a phone
+
+Phone layout follows the app container (≤640px) and a coarse pointer, not the browser window alone. A 768px touch tablet keeps its wider layout and still gets 44px tap targets.
+
+| What changes | Use | Phone behaviour |
+|---|---|---|
+| 2–4 short views of the same content | `SegmentControl` | Full width, equal segments, 36px minimum visual height and 44px hit area; translated labels wrap and may grow the row |
+| Many local views or long navigation labels | `Tabs` | Horizontal strip with edge fades; selection scrolls into view without moving the page; labels stay on one line |
+| Up to 5 top-level app destinations | `AppTabBar` | Bottom navigation; additional destinations belong under More |
+| Settings sections or 5+ page sections | `SectionTabs` / `SettingsPage` | Grouped list and push navigation on phone; retain the section structure |
+| A saved form choice | `RadioGroup` | Labelled choices, not navigation tabs |
+
+`SegmentControl variant="sheet"` follows the same phone sizing. More than four existing segments remain horizontally scrollable with fades; use `Tabs` for new many-view navigation. `size="sm"` stays compact on desktop and follows phone sizing on a phone. Icon-only segments require `aria-label`; use visible text when a touch user needs the label to choose. Never place a second bottom tab bar inside a page.
+
 ## Tables
 
 - Use `CellText` for a cell with a main text and secondary information (size, time, path): `text`, `secondary`, optional `icon`, `layout="stacked"` (default) or `"inline"`. It truncates both and shows the full text in a tooltip only when cut. Do not join strings or add margins.

package/docs/list-detail.md

@@ -0,0 +1,60 @@
+# 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.
+- At 640px of room or less (a phone) the list fills the room and the detail
+  is a page pushed over it ([push navigation](mobile-native.md#push-navigation)):
+  it slides in from the right, the list moves 30% left and dims, and a 48px
+  header shows Back and the title in place of Close. Back, the browser's Back
+  and a swipe from the detail's left edge pop it, which emits `close`. The
+  separator is hidden. Give the ListDetail a height to fill so the list and
+  the detail each scroll on their own; without one the detail sets the height.
+- 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`, `data-push` on the
+root while the detail is pushed; 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) |