@synopackageland/ui 0.20.19 → 0.21.0

package/docs/adaptive-layout.md

@@ -146,6 +146,16 @@ 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).
 
+## Phone: one header row, one scroller
+
+On a phone (`AppLayout` 640px or narrower, any height) the layout's bar is
+the page's one header row: the page title (or a sub-page's Back and title,
+`PageHeader` `back`, a pushed settings section) and the page's own actions
+in it. A page with a `SettingsPage` or a `SectionTabs fill` scrolls as one
+under the bar (`data-ui-layout-scroll="page"`), so no settings body becomes
+a short scroller with a hidden scrollbar. Details in docs/mobile-native.md,
+"Phone shell".
+
 ## Short screens
 
 A screen at most 480px tall (a phone in landscape: 753×279, 667×375,

package/docs/button-policy.md

@@ -47,7 +47,9 @@ are in [dsm-native-metrics.md](dsm-native-metrics.md).
 5. Inside a page, use `primary` only for the one step that unblocks the page,
    such as Sign in in a callout; at most one per section.
 6. Keep the default size. `sm` and `lg` exist for dense rows and touch layouts;
-   neighbouring buttons share one size.
+   neighbouring buttons share one size. On a phone every size is drawn one
+   step smaller than the field beside it (md 36, sm 28, lg 44px;
+   `--ui-button-*`), with the same 44px tap box; an IconButton keeps its size.
 7. A disabled button keeps its shape and place. Say why next to it.
 8. An icon-only action is an `IconButton` with a `label`; it shows as its
    tooltip and names the button for screen readers.

package/docs/mobile-native.md

@@ -64,6 +64,7 @@ control and grid sizes; it does not change the 16px field rule.
 | `--ui-font-size-field` (new) | 16 | 16 | 16 | every field on a coarse pointer, to stop iOS focus zoom |
 | `--ui-control-md` | 28 | **44** | **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-button-md` / `-sm` / `-lg` (new) | `--ui-control-*` | `--ui-control-*` | **36 / 28 / 44** | a Button and a SplitButton, one size smaller than the field beside it; the tap box stays 44. An IconButton keeps `--ui-control-*` |
 | `--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) |
@@ -391,7 +392,9 @@ view. `PushTransition` draws one pushed page:
   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.
+  start, the title in the middle and a `header-actions` slot at the end. In
+  a phone `AppLayout` with a `title` it draws no header of its own: the
+  layout's bar shows Back, the title and `header-actions` ("Phone shell").
 - 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
@@ -411,7 +414,7 @@ Where it is used:
 |---|---|---|
 | `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`, four or fewer sections | the scrolling underline strip on a touch phone (0.21.0); a full-width SegmentControl with equal segments in a narrow window used with a mouse, or with `phone="segment"` | 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
@@ -460,12 +463,122 @@ driven by a mouse):
   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.
+- **Actions:** first the page's own actions, then `headerActions`
+  (DropdownMenu entries). The first plain `headerActions` 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.
 
+**One header row.** The bar is the page's only header row on a phone:
+
+- **Page actions join the title.** The `#actions` of the `PageHeader` whose
+  title is in the bar, the `#header-actions` of a pushed page and the
+  `#actions` of an `AppToolbar` in the layout's `toolbar` slot render in the
+  bar (`[data-ui-mobile-page-actions]`), after the title, instead of a row of
+  their own. A Button with an icon is drawn as its icon, 44px, with its label
+  as its accessible name and its tooltip; a Button with text only stays text
+  (the primary colour); a primary or danger Button keeps its fill, one
+  size smaller. Keep one primary per area. An `AppToolbar` whose only content
+  was its actions then takes no row. Actions that do not fit beside the title
+  (the title would be under 80px, or the row would overflow) stay in the
+  page's own header row; `headerActions` "…" is the overflow for more.
+- **A detail page is one row.** `PageHeader` `back` (and `@back`) makes the
+  page a sub-page: on a phone the bar leads with Back, shows this page's
+  title, whatever AppLayout's `title` says, and holds its actions. Back calls
+  `@back`; the App pops its own route. Wider, the header leads its own title
+  with a Back button. Use it instead of a hand-drawn Back row above the page.
+- **A pushed section is one row.** A `PushTransition` with a `title` inside
+  the layout (a settings section pushed from a `SectionTabs` list) takes the
+  bar over the same way while it is shown: Back pops it, and its own 48px
+  back header is not drawn. The list under it keeps the page's title.
+
+**The page scrolls as one.** On a phone, a page holding a `SettingsPage` or
+a `SectionTabs fill` scrolls in the area under the bar, at any height: the
+settings body takes its content's height instead of a scroller of its own,
+and every element between them (an App shell's fill wrappers too) takes its
+content's height. The bar stays, a sticky `PageHeader` and section strip
+stick under it, and Reset / Apply stick at the bottom (a short page keeps
+them at the bottom of the screen). The root carries
+`data-ui-layout-scroll="page"`. A DataGrid or another page that scrolls
+itself keeps its layout.
+
+### Native phone shell (0.21.0)
+
+A *touch phone* is an `AppLayout` 640px or narrower under a coarse pointer
+(the root carries `data-ui-phone`). A narrow DSM window driven by a mouse is
+the phone layout without these additions, and wider layouts are unchanged.
+
+**Bar.** One 48px row: Back on a sub-page, else the menu button, else the
+App's icon (`brand-icon`) on a root page; the title, start-aligned beside
+anything else; at most two trailing icons, the rest in "…". There is no brand
+row. Tabs for the page (`SectionTabs` with four or fewer sections) are the
+scrolling underline strip right under the bar; `phone="segment"` keeps the
+SegmentControl. `AppTabBar` labels are 12px under 24px icons.
+
+**Page actions on a FAB.** By default (`AppLayout` `phone-actions="fab"`)
+the page's actions (PageHeader `#actions`, a pushed page's
+`#header-actions`, AppToolbar `#actions`) render in a floating action button
+at the bottom right, 16px from the edges and above the tab bar. No App
+change: the same slot moves.
+
+- One action: the FAB is that action (56px, its icon only, its label as the
+  accessible name). A tap runs it. It is the area's one primary: a danger
+  action stays red.
+- Two or more: the FAB (`+`, "Page actions") opens a speed dial: the actions
+  as labelled 48px pills over a scrim, staggered in. Focus moves to the first
+  and stays in the dial; Escape, Back, a press on the scrim or the FAB close
+  it and focus returns to the FAB. A pick runs the action and closes the dial;
+  an action that opens a menu closes it once the menu closes. The page behind
+  is inert while it is open. Reduced motion shows and hides it at once.
+- Rare or destructive items belong in `headerActions` ("…" in the bar), not
+  in the page actions.
+- `phone-actions` on `AppLayout`, and on a `PageHeader`, `AppToolbar` or
+  `PushTransition` for one page: `fab` (default), `bar` (icons in the bar, as
+  in 0.20.20) or `inline` (the page's own header row).
+- `PageFab` picks the FAB explicitly: `<PageFab><Button variant="primary">…</Button></PageFab>`
+  inside the page's actions. On a touch phone its content is the FAB and the
+  page's other actions go to the bar; elsewhere it renders in place.
+- A page whose primary action is in a footer bar (a `SettingsPage` footer, a
+  sticky `FormActions`) keeps its actions in the bar: the bottom already has a
+  primary. Content gets `--ui-fab-room` (88px) of bottom padding so the last
+  row is never under the FAB. Toasts are not moved above the FAB.
+
+**Hide on scroll.** On by default (`AppLayout` `hide-on-scroll`). Scrolling
+the page down 16px or more slides the bar, the tab bar, the FAB and a clean
+settings footer out (`data-ui-bars-hidden`, `all` when the page scrolls under
+the bar, `bottom` when the document scrolls); any scroll up of 4px, the top of
+the page and a scroll that stops at its end bring them back. Safe areas are
+kept, and they move in `--ui-motion-bars` (200ms; 0 with reduced motion). They
+never hide while the speed dial, the drawer, a sheet or a dialog is open or a
+text field has focus, and focus moving into a bar shows them. A page shorter
+than the bars' room never hides them.
+
+- Opt out for the App: `<AppLayout :hide-on-scroll="false">`; for one page:
+  `<PageContent :hide-on-scroll="false">`. Both keep the settings footer too.
+- **Settings footer.** A `SettingsPage` footer hides with the bars only while
+  the form is clean: never while it is dirty, invalid or saving, so Apply is
+  in reach after every edit. Set `dirty`, `invalid` and `saving` on the
+  SettingsPage, or let it read them: clean while the footer's primary button
+  (every button, without a primary) is disabled, invalid while a field has
+  `aria-invalid="true"`, saving while a footer button is loading. A clean
+  footer stays at rest: it slides away only with the bars, so Reset / Apply
+  never appear or vanish under the finger while the user edits.
+
+**Footer hints.** In any footer bar (`data-ui-footer-bar`: SettingsPage,
+Dialog, Sheet, BottomSheet, Card, Panel, Wizard, AppActionBar) a hint or
+status beside the buttons ("Enter a Custom ASR API key") takes a full-width
+line of its own above them on a touch phone, wrapping if it must. A hint is an
+element with text and no control in it; wrap bare text in a `<span>`.
+
+**Inside a host shell.** The Package Land mobile shell draws no chrome around
+a registered phone App: the App's bar is the only top bar and its tab bar the
+only bottom bar, edge to edge. A host that draws its own bars sets
+`--ui-host-inset-top/-right/-bottom/-left` on the App's root (or `:root`);
+they replace `env(safe-area-inset-*)` in `--ui-safe-*`, so the bar, the tab
+bar and the FAB clear the host's chrome instead of stacking under it. Android
+Back closes the speed dial first, then pops the App's history.
+
 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

package/docs/release-checks.md

@@ -8,7 +8,7 @@ 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/focus-restore browser checks, Histoire build, exact-tarball registry consumer smoke |
+| `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/short-viewport/phone-layout/focus-restore 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 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synopackageland/ui",
-  "version": "0.20.19",
+  "version": "0.21.0",
   "description": "Shared Vue 3 UI component library with a DSM 7 inspired application theme",
   "license": "MIT",
   "type": "module",
@@ -60,6 +60,62 @@
     "./themes/dsm7-embedded-reset.css": "./dist/themes/dsm7-embedded-reset.css",
     "./themes/dsm7-embedded-theme.css": "./dist/themes/dsm7-embedded-theme.css"
   },
+  "scripts": {
+    "check:docs": "node --test scripts/check-doc-versions.test.mjs && node scripts/check-doc-versions.mjs",
+    "dev": "vite build --watch",
+    "build": "vite build && vite build --mode json && vite build --mode rich-text && vite build --mode grid && vite build --mode cli && vite build --mode preview && vite build --mode embedded && node scripts/postbuild.mjs",
+    "lint": "eslint .",
+    "typecheck": "vue-tsc --noEmit -p tsconfig.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:changed": "echo \"test:changed skips the tests the changes since ${SYNOPKGLAND_GATE_BASE:-origin/master} do not reach (vitest --changed); pnpm check runs them all\" && vitest run --changed ${SYNOPKGLAND_GATE_BASE:-origin/master}",
+    "story": "histoire dev",
+    "story:build": "histoire build",
+    "check:host": "node scripts/dsm-host-shots.mjs",
+    "check:switch": "node scripts/check-switch.mjs",
+    "check:tabs": "node scripts/check-tabs.mjs",
+    "check:mobile": "node scripts/check-mobile-overflow.mjs",
+    "check:ui-patch": "node scripts/check-ui-patch.mjs",
+    "check:narrow": "node scripts/check-narrow-controls.mjs",
+    "check:drawer-form": "node scripts/check-drawer-form.mjs",
+    "check:responsive": "node scripts/check-responsive.mjs",
+    "check:adaptive": "node scripts/check-adaptive.mjs",
+    "check:sidebar-focus": "node scripts/check-sidebar-focus.mjs",
+    "check:json-render": "node scripts/check-json-render.mjs",
+    "check:motion": "node scripts/check-motion.mjs",
+    "check:topology": "node scripts/check-topology.mjs",
+    "check:wizard": "node scripts/check-wizard.mjs",
+    "check:edges": "node scripts/check-edges.mjs",
+    "check:data-grid": "node scripts/check-data-grid.mjs",
+    "check:truncation": "node scripts/check-truncation.mjs",
+    "check:link": "node scripts/check-link.mjs",
+    "check:text-select": "node scripts/check-text-select.mjs",
+    "check:date-picker": "node scripts/check-date-picker.mjs",
+    "check:full-page": "node scripts/check-full-page.mjs",
+    "check:short-viewport": "node scripts/check-short-viewport.mjs",
+    "check:phone-layout": "node scripts/check-phone-layout.mjs",
+    "check:focus-restore": "node scripts/check-focus-restore.mjs",
+    "check:detail-surface": "node scripts/check-detail-surface.mjs",
+    "check:internal": "node --test scripts/check-internal-content.test.mjs scripts/check-npm-metadata.test.mjs && node scripts/check-internal-content.mjs --repo .",
+    "check:npm-metadata": "node scripts/check-npm-metadata.mjs",
+    "check:package": "node scripts/check-package-content.mjs",
+    "check:public-api-consumer": "node scripts/check-public-api-consumer.mjs",
+    "notices:update": "node scripts/third-party-notices.mjs --write",
+    "notices:check": "node scripts/third-party-notices.mjs --check",
+    "check": "bash scripts/docker-check.sh \"npm run gates\"",
+    "check:fast": "bash scripts/docker-check.sh \"npm run gates\"",
+    "check:local-browser": "node scripts/app-local-browser.mjs",
+    "check:infotip": "node scripts/check-infotip.mjs",
+    "release:stage": "node scripts/stage-release.mjs",
+    "check:polish": "bash scripts/docker-check.sh --build --out .polish-shots 'node scripts/check-polish.mjs'",
+    "check:acceptance": "node scripts/check-acceptance.mjs",
+    "check:palette": "node scripts/check-palette.mjs",
+    "gates": "node scripts/gates.mjs",
+    "gates:full": "node scripts/gates.mjs --full",
+    "check:layout": "node scripts/check-layout.mjs",
+    "release:smoke": "node scripts/release-smoke.mjs",
+    "check:browser-install": "playwright install chromium"
+  },
   "peerDependencies": {
     "vue": "^3.5.0"
   },
@@ -79,9 +135,44 @@
     "@tiptap/vue-3": "3.32.1",
     "zod": "^4.6.5"
   },
+  "devDependencies": {
+    "@eslint/js": "10.0.1",
+    "@histoire/plugin-vue": "1.0.0-beta.1",
+    "@tailwindcss/vite": "4.3.3",
+    "@tanstack/vue-virtual": "3.13.39",
+    "@vitejs/plugin-vue": "6.0.9",
+    "@vue/test-utils": "2.5.1",
+    "@vueuse/core": "14.4.0",
+    "eslint": "10.11.0",
+    "eslint-plugin-vue": "10.11.1",
+    "flexsearch": "0.8.212",
+    "globals": "17.12.0",
+    "histoire": "1.0.0-beta.1",
+    "jsdom": "30.1.1",
+    "playwright": "1.58.2",
+    "reka-ui": "2.11.0",
+    "tailwindcss": "4.3.3",
+    "typescript": "5.9.3",
+    "typescript-eslint": "8.71.0",
+    "vite": "7.3.6",
+    "vite-plugin-dts": "5.1.1",
+    "vitest": "5.0.2",
+    "vscode-oniguruma": "2.0.1",
+    "vscode-textmate": "9.3.2",
+    "vue": "3.5.43",
+    "vue-eslint-parser": "10.4.1",
+    "vue-tsc": "3.3.11"
+  },
   "engines": {
     "node": ">=20"
   },
+  "packageManager": "pnpm@10.33.2",
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "esbuild",
+      "vue-demi"
+    ]
+  },
   "config": {
     "bundledRuntime": {
       "@tanstack/vue-virtual": "3.13.39",