@synopackageland/ui 0.20.20 → 0.21.0

package/docs/mobile-native.md

@@ -414,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
@@ -503,6 +503,82 @@ 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synopackageland/ui",
-  "version": "0.20.20",
+  "version": "0.21.0",
   "description": "Shared Vue 3 UI component library with a DSM 7 inspired application theme",
   "license": "MIT",
   "type": "module",