@synopackageland/ui 0.18.3 → 0.19.1

package/docs/theme-hooks.md

@@ -55,6 +55,7 @@ here stay implementation details and can change in any release.
 | `data-ui-page-header` | `PageHeader` | present |
 | `data-ui-page-header-meta`, `data-ui-page-header-actions` | `PageHeader`'s meta and actions areas | present |
 | `data-page-surface` | `PageContent` | `auto`, `card`, `flat`, `none` |
+| `data-ui-motion` | set by the app on any ancestor (an `AppRoot`, `<html>`) | `off`: the library's motion is instant inside it, as under reduced motion ([Motion](#motion)) |
 
 ### Navigation rows (`AppSidebar`, side or top)
 
@@ -166,6 +167,58 @@ The colour, radius, spacing and web tokens are listed in the
 [README](../README.md#theme-override), [colour system](color-system.md) and
 [adaptive layout](adaptive-layout.md#safe-overrides).
 
+## Motion
+
+The components move a little by default: dialogs and their masks fade in and
+settle from 97 %, menus, popovers and select lists drop 4px from their trigger,
+a notification slides 8px in, expandable bodies (`Card`, `SettingsSection`,
+`ExpandableItem`, `Callout` details, `TimelineRow`, `FacetPanel`, `Accordion`,
+`Fieldset`) open their height, a row the user just added fades in, and a tab
+panel switched to rises 4px. Only opacity, transforms and height through grid
+rows move. Exits are shorter than entrances and let clicks through at once.
+Nothing animates on first render, and a list's first data, a refresh or paging
+does not animate its rows.
+
+| Token | Value | Use |
+| --- | --- | --- |
+| `--ui-motion-fast` | 120ms | colour and state changes, menus opening, anything closing |
+| `--ui-motion-normal` | 180ms | dialogs opening, a new row, a tab panel, the loading mask |
+| `--ui-motion-slow` | 240ms | height, notifications and toasts arriving, a sheet sliding in |
+| `--ui-motion-ease-out` | `cubic-bezier(0.22, 1, 0.36, 1)` | arriving |
+| `--ui-motion-ease-in` | `cubic-bezier(0.4, 0, 1, 1)` | leaving |
+| `--ui-motion-ease-in-out` | `cubic-bezier(0.4, 0, 0.2, 1)` | height between two resting states |
+
+Under `prefers-reduced-motion: reduce` all of it is instant. To turn it off
+for part of a page, or the whole App, set `data-ui-motion="off"` on any
+ancestor:
+
+```vue
+<AppRoot data-ui-motion="off">
+  <App />
+</AppRoot>
+```
+
+## Hover hit areas
+
+Hover never moves or resizes the element under the pointer, and the room
+between two neighbouring rows of a list is never a dead strip. Otherwise a
+pointer resting on the edge is inside, outside, inside again: the hover wash and
+the hand cursor blink.
+
+- Rows of a list carry `data-ui-hit-row` (stacked: `AppSidebar` pages, branches
+  and group toggles) or `data-ui-hit-row="inline"` (side by side: top
+  navigation, `Tabs`, `SegmentControl`). Each row's hit area reaches forward over
+  the next `--ui-hit-row-slop` (default `6px`) through an invisible `::after`, so
+  a margin or gap a theme puts between rows stays visible but clickable. The next
+  row is drawn after it, so the slop never takes a pixel from it. Put the
+  attribute on your own rows of a list to get the same; do not give those rows
+  another `::after`.
+- A theme or App hovers with colour, shadow or outline. To lift or grow
+  something, move an inner layer (`.card:hover .icon { transform: … }`), or add
+  a `:hover::after` strip that covers the spot the element leaves.
+  `tests/hover-geometry.test.ts` fails on a `:hover` rule (or Tailwind
+  `hover:` utility) that moves or resizes the hovered element itself.
+
 ## Example: a dark top bar
 
 ```css

package/package.json

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