vireuikit 0.7.0 → 0.9.0

package/README.md

@@ -51,10 +51,55 @@ import { MENU_CLOSED, menuPlacement, menuSurfaceFrame, stepMenu } from 'vireuiki
 
 const step = stepMenu(MENU_CLOSED, { type: 'open', focus: 'first' }, items); // items: { label, disabled, focusable? }[]
 // step.focus says where focus goes; a choice always closes the menu.
-const { rect, anchor } = menuPlacement(triggerRect, menuSize, viewport);
+const { rect, anchor } = menuPlacement(triggerRect, menuSize, segment); // the trigger's segment of the window, or the viewport
 const surface = menuSurfaceFrame(triggerBox, { ...rect, radius }, anchor, growthPhase(state));
 ```
 
+## Adaptive model
+
+What every atom and pattern becomes across window classes, input and posture is one pure model, so every target
+decides the same way. The context is the window in dp, the input in three layers (the primary pointer, any coarse
+input, hover, a keyboard), the posture of a folding screen and reduced motion; the functions turn it into forms.
+
+```ts
+import { adaptiveContext, halfOpen, INPUT_MIXED, navigationForm, paneLayout, presentationForm } from 'vireuikit';
+
+const window = { width: 673, height: 841 };
+const ctx = adaptiveContext({ window, input: INPUT_MIXED, posture: halfOpen('book', window) });
+
+navigationForm(ctx, { primary: 4, secondary: 2, search: true }).form; // 'rail'
+paneLayout(ctx, { selected: true, showing: 'detail' }).split; // { kind: 'fold', gap }: the panes split at the fold
+presentationForm('sheet', ctx).form; // 'bottom-sheet'; a side sheet from 840 dp
+```
+
+- `classifyWindow` holds every threshold: widths 600, 840, 1200 and 1600 dp, heights 480 and 900.
+- `navigationForm`: a bar on a compact width and in tabletop, a rail on medium, expanded and a compact height, a
+  sidebar from large; the same primary destinations on every form, at most five bar slots with search, no "More".
+  `bottomAccessory` places a strip above the bar, in its row or along the content.
+- `presentationForm` for a menu, picker, popover, sheet, modal sheet, alert or dialog: a popover is a sheet grown from
+  its source below 600, a supplementary sheet is a bottom sheet below 840 and a side sheet from there, sheets fill
+  the window on a compact height, and every surface lives in one segment, never across the fold.
+- `paneLayout` (list-detail: one pane below 840, a 360 or 412 dp list beside the detail, split at the fold in book
+  posture), `supportingPane` (beside the content from large, over it on expanded, remembered), `postureSplit`.
+- `toolbarLayout` fits a toolbar into its container: neighbours merge, then the lowest priority goes into "…";
+  badged items and the main action stay. `toolbarPlacement` says where the window puts it.
+- `sizeTier` follows the primary pointer and `hitTarget` any coarse input, so a laptop with a touch screen gets the
+  pointer tier with a 44 dp hit area.
+- `formMorph`, `stepFormMorph` and `formMorphFrame` flow one body into its new form on the growth's springs; turned
+  back mid-way it runs back from where it is, and under reduced motion it lands in one frame.
+
+On the web the elements collect their part of the context themselves. A shell that lays itself out from the model
+watches its root:
+
+```ts
+import { setInputOverride, setViewportOverride, watchAdaptiveContext } from 'vireuikit/web';
+
+const stop = watchAdaptiveContext(shell, (ctx) => render(ctx)); // told now and on every change
+```
+
+`setInputOverride` lets a host that knows its input better decide the layers, and `setViewportOverride` makes an
+element the window, with its own segments; the lab's adaptive stage simulates devices with both.
+
 ## Web elements
 
 `vireuikit/web` upgrades native controls with custom elements. The control inside works before the
@@ -78,9 +123,10 @@ setA11yOverride({ reduceTransparency: true });
 - `<vire-icon-button>` lifts into the glass under the finger; the lens response is visible while the
   press is held.
 - Attributes: `glass` (empty or `present`: a lens at rest; `touch`: a lens only under the finger; absent: no
-  glass), `size` (`touch`, `small`, `medium`, `large`, `xlarge`; by default `touch` on a coarse pointer and
-  `medium` otherwise), `disabled`.
-- On a coarse pointer every size keeps a hit area of at least 44 dp without changing layout.
+  glass), `size` (`touch`, `small`, `medium`, `large`, `xlarge`; by default `touch` when the primary pointer is
+  coarse and `medium` otherwise), `disabled`.
+- Wherever a coarse input is present, a touch screen on a laptop too, every size keeps a hit area of at least 44 dp
+  without changing layout. Hover comes from the pointer that entered: a mouse on a tablet hovers, a finger never does.
 - The lens reads the backdrop from declared colours and cannot see an image, a video or a canvas. A host that knows
   what lies under the control sets the element's `sample` (a `BackdropSample` from `vireglass`), at any time; `null`
   hands it back to the probe.
@@ -145,9 +191,78 @@ setA11yOverride({ reduceTransparency: true });
   `<vire-icon-button>`), so there is never glass on glass.
 - Attributes: `glass` (empty, `present` or `touch`: the surface is a lens; absent or anything else: an opaque surface), `size` (as for the buttons; rows are as tall
   as the tier), `corner` (`top-left`, `top-right`, `bottom-left`, `bottom-right`: the trigger corner the menu pins to;
-  by default the one facing the nearest viewport corner). `sample` works as on the buttons; without one, the backdrop
+  by default the one facing the nearest corner of the trigger's segment of the window). On a folding screen the menu
+  stays in its trigger's half, every frame of its growth included, and scrolls if it is taller. `sample` works as on the buttons; without one, the backdrop
   under the menu is read once as it opens and held while it is out.
 
+### Navigation
+
+`<vire-nav>` upgrades a `<nav>` of links into one glass body that is a bar, a rail or a sidebar by the window it covers,
+and changes form through the selected destination.
+
+```html
+<vire-nav glass minimize="scroll" scroller="content">
+  <nav aria-label="Sections">
+    <ul>
+      <li><a href="/" aria-current="page"><svg>…</svg>Home</a></li>
+      <li><a href="/library"><svg>…</svg>Library</a></li>
+    </ul>
+    <ul data-secondary>
+      <li><a href="/feed"><svg>…</svg>Feed</a></li>
+    </ul>
+    <a href="/search" data-search><svg>…</svg>Search</a>
+  </nav>
+  <div data-accessory>…host content, such as a mini player…</div>
+</vire-nav>
+```
+
+- Before the upgrade it is a list of links. After it the element covers its containing block (give that a position): its
+  own box is the window it classifies, so it needs no breakpoints from the host. Only the body, the search, the toggle,
+  the scrim and the accessory take the pointer. Links stay links: no `tablist`, no arrow keys, Tab walks them, and
+  `aria-current` is the host's to set and move; the pill slides to it. Removing the element restores the markup.
+- The form comes from `navigationForm`: a bar on a compact width, a rail on medium and expanded windows, a sidebar from
+  large. Destinations beyond the bar's slots move to the secondary list, which shows only in the sidebar; links not shown
+  in a form are `hidden`. The host carries `data-form` (`bar`, `rail`, `sidebar`), `data-search` (`button`, `item`,
+  `field`) and `data-minimized`.
+- A change of form goes through the selection: it lifts into a lens, the old body contracts into it, the new body grows
+  out of it and the lens settles into the pill. The lens is glass only while it moves. Focus stays on the same link
+  while that link stays shown; a link the new form hides (minimising, a link moving to the secondary list) hands focus to
+  the selected link, or to the toggle. Reduced motion lands the new form in one frame. A press that starts on the bar's inset or between items and ends
+  without a drag settles the lens back on the selected item.
+- On the bar a press lifts the selection into a lens under the finger; a drag moves it, and releasing activates the
+  nearest link once. A tap is a plain click on the link.
+- Attributes: `form` (`bar`, `rail` or `sidebar`: fixes the form), `collapsed` (the sidebar held as a rail; the toggle
+  sets and clears it and the host remembers it), `panes` (panes the content shows; two on a medium window take the bar),
+  `minimize="scroll"` with `scroller` (the id of the scrolling element, resolved in the element's root; or set the
+  `scroller` property to an element), `search-key` (default `/`), `toggle-label` (the toggle's name, default "Sidebar";
+  it never changes, `aria-expanded` says whether the sidebar is shown), `glass` (empty or `present`: glass; otherwise a plain body).
+- Minimising: the bar becomes a circle with the selected icon, and the search a second circle, after 24 dp scrolled
+  down in the scroller, and expands after 24 dp up, at the top, on a tap on it and when focus enters it. Giving the
+  bar another scroller expands it. The element looks the id up again on each change: a node that left the document, or
+  that the id no longer names, is let go and the bar expands. The document itself works as a scroller
+  (`document.documentElement`, `document.body` or `document.scrollingElement`, listened to on the window), and a
+  bounce past either end of the scroll range counts as the end. A step back of less than 4 dp does not break a run.
+- `[data-accessory]` is the bottom accessory. It sits over the bar, in the minimised bar's row, or along the bottom of
+  the content beside a rail or sidebar, and says which in its `data-placement` (`above-bar`, `in-bar`,
+  `content-bottom`): show the transport only when `in-bar`.
+- Insets: the element sets `--vire-nav-inset-bottom` and `--vire-nav-inset-start` (px) on its parent for the content to
+  clear, and fires `vire-nav-layout` with `{ form, minimized, insets, accessoryPlacement }` whenever any changes.
+- Toggle: in the sidebar a button in its head collapses it into a rail (`collapsed`, and `vire-nav-collapse` with
+  `{ collapsed: true }`); an expandable rail beside the content clears it (`{ collapsed: false }`); on an expanded window
+  a rail opens the sidebar over the content behind a scrim (`aria-expanded` is true then too), closed by Escape, a press on the scrim or a link chosen;
+  Escape and the scrim return focus to the toggle if it was inside the navigation. The element stores nothing.
+- Where the model gives a shortcut (a large window, or a keyboard in use), `search-key` pressed outside a field clicks
+  the search link, which carries `aria-keyshortcuts` while it is shown (the shortcut still works for a link the form hides).
+- Every link keeps a 44 dp hit area wherever a coarse input is present, without changing the layout. A `[data-badge]`
+  inside a link is a count (or a dot, when empty) at the icon's corner, and only a picture: the element sets
+  `aria-hidden="true"` on it and restores the attribute on removal. To say it, put a `[data-badge-label]` in the link;
+  it is visually hidden but stays in the link's name:
+  `<a href="/messages"><svg>…</svg>Messages<span data-badge>3</span><span data-badge-label>3 new</span></a>`, read as "Messages 3 new". `sample` and `a11y` work as on the buttons. The bar clears the bottom safe area
+  (`env(safe-area-inset-bottom)`, read once per layout; 0 where unsupported).
+- The element adds nodes inside `<vire-nav>`, so call `defineVireElements()` after a framework has hydrated the markup
+  (in an effect, say), not before. The lens's copy follows the selected link's content, and a link that leaves the markup
+  is left as the author wrote it.
+
 Sizes, behaviour state machines and accessibility modes are exported from `vireuikit` and shared by every
 target. How an atom is accepted:
 [design](https://github.com/pruffit/vireuikit/blob/main/docs/design.md),