@synopackageland/ui 0.23.4 → 0.23.5

package/docs/mobile-native.md

@@ -2,6 +2,25 @@
 
 How the UI SDK behaves on a phone (390×844) and a touch tablet (768×1024).
 
+## Phone behaviour contract
+
+What every App gets on a touch phone, from the UI SDK, with no code of its
+own. An App does not override these; a fix to one is made here, for every
+App. Each line links to its details below.
+
+| Behaviour | The rule |
+| --- | --- |
+| FAB and speed dial | The page's one action is a 56px circle (`border-radius: 50%`) with its icon and elevation; two or more open from a 56px circle with `+` as labelled pills. 56px is Material 3's FAB size (56dp; M3's default FAB shape is a rounded square, the UI draws a circle) and clears iOS's 44pt minimum tap target. See [Page actions on a FAB](#native-phone-shell). |
+| One compact top bar | One 44px row: Back, the menu button or the App icon, the title, at most two icons and one "…". No brand row, no second header row. |
+| No tab heading on tab pages | A page of the tab bar draws no title, icon or brand in the bar (`phone-bar-title="none"`) and no heading of its own: the tab bar says where the user is. A sub-page keeps Back and its title. |
+| Title on a tab page is opt-in | Showing a title on a tab page is the App's explicit choice: `phone-bar-title="auto"` on `AppLayout`, and the SDK AppShell's own opt-in (`phoneTitle`). |
+| Hide on scroll | By `transform` only; the scroller keeps its size, position and padding and nothing writes `scrollTop`, so a momentum fling keeps going. Slow scrolls use distance hysteresis, flicks decide at once. See [Hide on scroll](#native-phone-shell) and [Gesture velocity](#gesture-velocity). |
+| No horizontal pan | The page never pans sideways: the phone layout's content area and page scroller clip `overflow-x`, and `check:phone-layout` asserts `scrollWidth == clientWidth` for the document and the page's scrollers at 320, 360, 390 and 430px. An inner horizontal scroller (a table, a tab strip) still scrolls. |
+| Bottom accessory | `#accessory` docks above the tab bar, lifts the FAB and toasts, and slides into the tab bar's place with the bars. |
+| Sticky offsets | `--ui-sticky-top-offset` counts the covered padding, a sticky `PageHeader`, the tabs strip and every `data-ui-sticky` row, so scrolling to an element lands below them. A row in an App's own nested scroller (a side pane) sticks at that scroller's top and counts only there. |
+| No end space under docked bars | The room under the last row is constant (`--ui-page-end-space`, plus `--ui-bars-room` under docked bars); a fill page's list runs under the FAB and bars to the screen's bottom with no blank band. |
+| Gesture velocity | One estimator and one set of thresholds for every gesture decision the UI makes. See [Gesture velocity](#gesture-velocity). |
+
 ## Width containment and the release gate
 
 Typography tables scroll horizontally within their parent, including a flex
@@ -78,7 +97,7 @@ control and grid sizes; it does not change the 16px field rule.
 | `--ui-tab-bar-height` | – | – | **48** | the tab bar's row, above `--ui-safe-bottom` |
 | `--ui-section-tab-height` | 44 | 44 | **40** | the drawn height of a phone's tabs strip (its tap box stays 44) |
 | `--ui-sticky-top-offset` | 0 | 0 | measured | what sticks at the top of a PageContent (see below) |
-| `--ui-page-end-space` | 24 | 24 | 24, the safe area while the bars are hidden on a fill page | room after a page's last row |
+| `--ui-page-end-space` | 24 | 24 | 24 (constant: hiding the bars never changes it) | room after a page's last row |
 | `--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 |
@@ -188,6 +207,18 @@ own) keeps scrolling. An App that puts small controls flush with the edge of
 its own scroller, outside a `PageContent`, clips that content sideways the
 same way.
 
+When an App shell makes the `PageContent` itself its page scroller
+(`overflow-y: auto` on it, like the SDK's `.app-page`), the browser turns its
+sideways clip into `hidden`, which is a scroller again: a page-header ⋯ on its
+right edge made it 13px wider than its view in a landscape phone window. So
+the `PageContent` body clips too. The body reaches over the page's side
+padding (`--ui-page-bleed`, the gutter of a page with a surface, 0 for
+`surface="none"`) with a negative margin and the same padding inside, so its
+content stays where it was, and it clips at the page's own edge: a box keeps
+its 44px over the gutter and loses only what would lie outside the page. The
+body's width and `max-width` allow for the bleed; an App that sizes the body
+itself (`width: 100%`) is overridden by the body's inline width.
+
 A control at the end edge of its own component is the component's job, not
 the page's: a dismissible Callout is often full width in an App's own
 scroller with no `PageContent` around it. Such a control sets
@@ -438,6 +469,46 @@ 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.
 
+## Gesture velocity
+
+Scrolling and dragging stay the browser's own; the UI never animates a
+scroll or replaces momentum. Where the UI itself decides what a gesture
+means, it reads one estimator with one set of thresholds
+(`src/interaction/velocity.ts`, exported from the package):
+
+- `VelocityEstimator`: velocity along one axis (px/s) from a least-squares
+  line through the samples of the last 100ms (`VELOCITY_WINDOW_MS`), at most
+  20 (`VELOCITY_MAX_SAMPLES`). A sample with the same timestamp replaces the
+  last, an out-of-order one is ignored, a reversal of more than 0.5px
+  (`VELOCITY_REVERSAL_PX`) starts a new fit from the turning point, a gap
+  longer than the window starts over, and a fit older than the window reads 0
+  (the finger stopped before lifting).
+- `GESTURE_THRESHOLDS`:
+
+  | Name | Value | Used for |
+  | --- | --- | --- |
+  | `flick` | 1000 px/s | hide or show the phone bars at once; faster bar motion |
+  | `swipe` | 500 px/s | a short swipe commits (pop a pushed page, next image) |
+  | `swipeDistance` | 48px | a slow swipe commits (next image) |
+  | `hideDistance` | 48px | a slow scroll down hides the bars |
+  | `showDistance` | 24px | a slow scroll up shows the bars |
+  | `slop` | 6px | travel before a touch has a direction |
+
+- `velocityDuration(velocity, baseMs)`: a motion set off by a flick takes 60%
+  of its base duration (never under 120ms); anything slower takes the base.
+- `swipeCommits(travel, velocity, distance)`: a released swipe commits past
+  `distance`, or past `slop` at `swipe` speed or faster in its direction.
+
+Reduced motion is the stylesheet's: every transition finishes at once, so a
+decision still happens and nothing animates.
+
+Where it is used: hide on scroll and the FAB (the page's `scrollTop`), the
+pushed page's edge swipe back (`PushTransition`: past 35% of the width, or a
+`swipe`), and the image lightbox's swipe to the next file. The BottomSheet's
+drag and snap, the navigation drawer's swipe and a toast's swipe to dismiss
+are decided by Reka UI, which the UI does not fork; they keep Reka's own
+thresholds. SegmentControl and lists have no swipe gestures.
+
 ## RecordPanel and AsidePanel on the BottomSheet
 
 Both panels use `BottomSheet` on a phone, so they share its grabber, drag,
@@ -586,10 +657,10 @@ the page's actions (PageHeader `#actions`, a pushed page's
 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
+- One action: the FAB is that action (a 56px circle, 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
+- Two or more: the FAB (a 56px circle with `+`, "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;
@@ -627,15 +698,38 @@ change: the same slot moves.
   (fades out) while the speed dial is open; it moves with the bars (`--ui-motion-bars`, at once with reduced motion). A page without a FAB,
   a DSM window and a desktop place toasts as before.
 
-**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.
+**Hide on scroll.** On by default (`AppLayout` `hide-on-scroll`). The page
+scrolls natively; the decision reads the shared velocity estimator (see
+[Gesture velocity](#gesture-velocity)) and the distance travelled one way:
+
+- a slow scroll down of `hideDistance` (48px) slides the bar, the tab bar,
+  the FAB and a clean settings footer out (`data-ui-bars-hidden`); a slow
+  scroll up of `showDistance` (24px) brings them back, so a slow or wobbly
+  drag never flickers them;
+- a flick at `flick` (1000 px/s) or faster hides them, or shows them, at
+  once, and they move in 60% of `--ui-motion-bars` (never under 120ms;
+  `--ui-bars-motion` on the layout), else in `--ui-motion-bars` (200ms; at
+  once with reduced motion);
+- the top of the page and a scroll that stops at its end bring them back.
+
+The bars move by `transform` only. When the page scrolls in an area under
+the bar (a fill layout, or an App shell whose `main` does not let the
+document scroll) the layout marks itself `data-ui-bars-overlay`: the content
+runs under the bar, the tab bar and the accessory from the start, and the
+end of what scrolls has a constant spacer (`--ui-bars-room`: the bar, the
+tab bar or the safe area, and the accessory) so the last row clears them.
+Hiding then translates the bar, the content area and the tab bar
+(`data-ui-bars-hidden="all"`). When the document scrolls, the bar scrolls
+away with it, and only the tab bar, the accessory and the FAB slide
+(`bottom`). Either way the scroller keeps its size, position and padding, no
+`scrollTop` is written, and a momentum fling keeps going on iOS and Android.
+While the content area is translated it is the containing block of a
+`position: fixed` element inside it; the UI's own overlays (sheets, menus,
+toasts) render in the floating layer outside it.
+
+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 that scrolls less 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.
@@ -719,15 +813,32 @@ An App sets no `top` of its own and measures nothing.
   page only.
 - The offset is the page's, not per element: content above a sticky row in
   the middle of a page also stops that much lower (never under it).
+- A row inside a scroll container of the App's own in the body (a wide
+  layout's side pane with `overflow-y: auto`, or any ancestor whose overflow
+  is not `visible` or `clip`, which is where the browser sticks it) sticks in
+  that container, not in the page. It stacks only on that container's earlier
+  rows (`top` 0 for the first), never counts in the page's offset, and the
+  container gets its own `--ui-sticky-top-offset` (its top padding plus its
+  rows), so what scrolls in the pane stops below the pane's rows and not
+  below the page's header. Before 0.23.5 such a row was stuck the page's
+  header height down inside its pane.
+- A nested scroller without rows still inherits the page's offset as its
+  content's scroll margin. Mark it `data-ui-sticky-scope` and what scrolls in
+  it takes no page offset. A fill page's own list scroller
+  (`data-ui-page-scroller`) never takes it: the header is above the list, not
+  over it.
 - The rule has one attribute's specificity, so an App's own class wins for
   `position`, `background` or `z-index`.
 - Before 0.23.4 an App measured its row and added it to the token by hand;
   remove that code when it marks the row instead.
 
 **The end of a page: `--ui-page-end-space`.** The room after a page's last
-row, 24px. While the bars are hidden on a fill page (`data-ui-page-fills`)
-it is only `--ui-safe-bottom`, so the content's scroller runs to the bottom
-of the screen. An App shell that pads its page end reads it:
+row, 24px, constant: hiding the bars never changes it, so the content's
+length never changes mid-scroll. Under docked bars (`data-ui-bars-overlay`)
+the room for the bars is the separate `--ui-bars-room` spacer, and a fill
+page whose own scroller has the FAB's room gets no end space below that
+scroller, so no blank band sits under a list. An App shell that pads its
+page end reads it:
 `padding-bottom: var(--ui-page-end-space, var(--ui-space-6, 24px))`.
 
 **Scroll helpers.** A phone page scrolls in a different element than a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synopackageland/ui",
-  "version": "0.23.4",
+  "version": "0.23.5",
   "description": "Shared Vue 3 UI component library with a DSM 7 inspired application theme",
   "license": "MIT",
   "type": "module",
@@ -60,63 +60,6 @@
     "./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:text-zoom": "node scripts/check-text-zoom.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"
   },
@@ -167,13 +110,6 @@
   "engines": {
     "node": ">=20"
   },
-  "packageManager": "pnpm@10.33.2",
-  "pnpm": {
-    "onlyBuiltDependencies": [
-      "esbuild",
-      "vue-demi"
-    ]
-  },
   "config": {
     "bundledRuntime": {
       "@tanstack/vue-virtual": "3.13.39",
@@ -181,5 +117,62 @@
       "reka-ui": "2.11.0"
     }
   },
-  "homepage": "https://www.varvis.me/docs/"
-}
+  "homepage": "https://www.varvis.me/docs/",
+  "scripts": {
+    "check:docs": "node --test scripts/check-doc-versions.test.mjs && node scripts/check-doc-versions.mjs",
+    "dev": "vite build --watch",
+    "build": "vite build && vite build --mode json && vite build --mode rich-text && vite build --mode grid && vite build --mode cli && vite build --mode preview && vite build --mode embedded && node scripts/postbuild.mjs",
+    "lint": "eslint .",
+    "typecheck": "vue-tsc --noEmit -p tsconfig.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:changed": "echo \"test:changed skips the tests the changes since ${SYNOPKGLAND_GATE_BASE:-origin/master} do not reach (vitest --changed); pnpm check runs them all\" && vitest run --changed ${SYNOPKGLAND_GATE_BASE:-origin/master}",
+    "story": "histoire dev",
+    "story:build": "histoire build",
+    "check:host": "node scripts/dsm-host-shots.mjs",
+    "check:switch": "node scripts/check-switch.mjs",
+    "check:tabs": "node scripts/check-tabs.mjs",
+    "check:mobile": "node scripts/check-mobile-overflow.mjs",
+    "check: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:text-zoom": "node scripts/check-text-zoom.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"
+  }
+}