@synopackageland/ui 0.13.1 → 0.14.0

package/docs/size-and-split.md

@@ -0,0 +1,96 @@
+# SplitPane, SizeBar and StorageMeter
+
+Three building blocks for storage pages: two panes the user resizes, a size
+bar for a list row, and a "free now → free after" projection. All three are
+styled with classes only and work inside the DSM-embedded theme.
+
+## SplitPane
+
+Two panes side by side (`horizontal`) or one above the other (`vertical`),
+with a separator the user drags, moves with the keyboard, or double-clicks to
+reset.
+
+```vue
+<SplitPane storage-key="myapp.explore.split" :default-size="0.56" :min-start="280" :min-end="480">
+  <template #start><Treemap /></template>
+  <template #end><DataGrid ... /></template>
+</SplitPane>
+```
+
+| Prop | Default | Meaning |
+| --- | --- | --- |
+| `modelValue` | unset | The start pane's share of the room, 0–1. Bind `v-model` to control it; leave it unset and the pane keeps its own state. |
+| `defaultSize` | `0.5` | The share it starts with and returns to on a double click. |
+| `orientation` | `'horizontal'` | `horizontal`: start on the left. `vertical`: start on top. |
+| `minStart` / `minEnd` | `160` | Each pane's minimum in px. The separator stops there; a window too small for both gives the start pane its minimum first. |
+| `gap` | `12` | The separator's thickness in px (the room between the panes). |
+| `storageKey` | unset | Remembers the share in this browser's `localStorage` under `<storageKey>:<orientation>`, so each orientation keeps its own share. Reading and writing are wrapped in `try/catch`; unreadable or invalid storage falls back to `defaultSize`. |
+| `label` | "Resize panes" | The separator's accessible name. |
+
+- **Keyboard.** The separator is a Tab stop (`role="separator"`). Left/Right
+  (horizontal) or Up/Down (vertical) move it by 2%, with Shift by 10%;
+  Home/End go to the minimums. Each change is saved.
+- **ARIA.** `aria-orientation` is perpendicular to the layout, as the ARIA
+  pattern asks; `aria-valuenow`/`aria-valuemin`/`aria-valuemax` are whole
+  percentages of the start pane; `aria-controls` names the start pane.
+- **Reset.** A double click removes the saved share and returns to
+  `defaultSize`. `reset()` is exposed for a menu command.
+- Emits `update:modelValue` on every move. Hooks: `data-ui-split-pane`
+  (`data-orientation`, `data-dragging` while dragged),
+  `data-ui-split-pane-start`, `data-ui-split-pane-separator`,
+  `data-ui-split-pane-end`.
+
+Choose the orientation from the measured content width, not a viewport media
+query: a DSM window can be narrower than the browser.
+
+## SizeBar
+
+A 4px bar for a table cell or list row: `value` against `max` (pass the
+largest row, so that row fills the track), and `part` of it drawn from the
+same start in the full tone, for example the reclaimable part of a size. The
+numbers stay as text beside it.
+
+```vue
+<template #cell-size="{ row }">
+  <CellText :text="formatFileSize(row.size)" />
+  <SizeBar :value="row.size" :max="largest" :part="row.reclaimable" />
+</template>
+```
+
+| Prop | Default | Meaning |
+| --- | --- | --- |
+| `value` | required | The row's size. `null`, `undefined` or `0` draws an empty track. |
+| `max` | required | The size that fills the track. |
+| `part` | `null` | The part of `value` to emphasise. |
+| `tone` | `'primary'` | `primary`, `success`, `warning` or `danger`. |
+| `label` | unset | Accessible name. Without it the bar is decorative (`aria-hidden`); give one only when the bar stands for numbers that are not shown. |
+
+A non-zero value is at least 2px wide. The track colour is
+`--ui-size-bar-track` (default `--ui-gray-a2`). Hooks: `data-ui-size-bar`
+(`data-tone`), `data-ui-size-bar-value`, `data-ui-size-bar-part`.
+
+## StorageMeter
+
+"Free now X → Free after Y" over a bar of the volume: used, the part a cleanup
+frees, and free space.
+
+```vue
+<StorageMeter :total="volume.total" :free="volume.free" :freeing="selection.bytes" :at-least="!selection.exact" :pending="selection.checking" />
+```
+
+| Prop | Default | Meaning |
+| --- | --- | --- |
+| `total` / `free` | required | The volume's bytes. |
+| `freeing` | required | Bytes the action frees; clamped to the used bytes. |
+| `atLeast` | `false` | `freeing` is a lower bound: "Free after" reads "At least Y" and the freed part fades out at its end. |
+| `pending` | `false` | A better number is being worked out: the freed part pulses (not with reduced motion) and the meter is `aria-busy`. |
+| `labels` | built-in | `{ freeNow, freeAfter }`, for an app's own wording. |
+| `format` | `formatFileSize` | Byte formatter (DSM's 1024 base). |
+
+The meter is one `role="img"` whose name is "Free now X, free after Y". Its
+text and bar follow the surrounding text colour (`currentColor`), so it reads
+on a light page and on a dark action bar alike; "Free after" and the freed
+part use `--ui-primary`. Hooks: `data-ui-storage-meter`,
+`data-ui-storage-meter-now`, `data-ui-storage-meter-after`,
+`data-ui-storage-meter-used`, `data-ui-storage-meter-freeing`
+(`data-at-least`).

package/docs/theme-hooks.md

@@ -65,6 +65,11 @@ here stay implementation details and can change in any release.
 | `data-nav-label`, `data-nav-badge` | a row's label and badge | present |
 | `data-nav-contains-current` | a top-bar branch whose child is the current page | present |
 | `aria-current` | the current page's row | `page` |
+| `data-ui-top-nav-item` | measurable top-level row wrapper | present |
+| `data-ui-overflowed` | row moved into More (hidden and inert in the bar) | `true` |
+| `data-ui-top-nav-more` | More menu trigger | present |
+| `data-ui-selected` | More trigger when its subtree contains the current page | `true` |
+| `data-ui-top-nav-overflow-menu` | portalled More dropdown panel | present |
 | `data-ui-sidebar-user` | `AppSidebarUser` | present |
 | `data-ui-user-avatar`, `data-ui-user-name`, `data-ui-user-detail` | its parts | present |
 
@@ -94,6 +99,7 @@ before the token existed. Set them on the app root or any ancestor.
 
 | Token | Affects | Unset |
 | --- | --- | --- |
+| `--ui-nav-row-height` | navigation row height/minimum height; inherited from any ancestor, including outside `AppLayout` | window 42px, web 40px, phone 46px |
 | `--ui-icon-size` | icons in navigation rows (`AppSidebar`, side and top) | 22px in the sidebar, 18px in the top bar |
 | `--ui-heading-weight` | `PageHeader` title, `Card` title, `TypoHeader`, web toolbar titles | 600 (`PageHeader`, `TypoHeader`, toolbar), 700 (`Card`, web `PageHeader`) |
 | `--ui-card-padding` | a regular `Card`'s header, body and footer inset; the body's block padding is 0.8× | 20px (body 16px × 20px). Compact cards are unchanged |
@@ -140,3 +146,23 @@ The colour, radius, spacing and web tokens are listed in the
 ```
 
 The Histoire story *DSM 7 / Top navigation and theme hooks* shows both.
+
+## Navigation sizing and overflow
+
+Set `--ui-nav-row-height: 30px` on the app's theme ancestor to override all
+presentations. Layout modes set only the internal `--ui-nav-row-height-default`
+fallback; they never redefine the public token. Existing density presets and
+explicit values on a row or layout still take precedence through normal CSS
+inheritance. Sidebar rows can grow to fit wrapped labels.
+
+With `navigation="top"`, `AppSidebar` measures the available navigation width,
+row widths (including icons and badges), group spacing and More trigger. The
+trailing items move into More in their original order; nested items and disabled
+states are preserved. More is selected when the current page is anywhere in
+its subtree. Tab reaches the trigger, Enter/Space or ArrowDown opens it,
+arrows navigate, and Escape closes it and returns focus. Resizing or changing
+labels/badges remeasures the row. Hidden bar rows are inert and aria-hidden.
+The phone drawer and default sidebar keep their existing behavior.
+
+The portalled panel has `data-ui-top-nav-overflow-menu`; scope panel styles by
+that attribute rather than relying on it being a descendant of the bar.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synopackageland/ui",
-  "version": "0.13.1",
+  "version": "0.14.0",
   "description": "Shared Vue 3 UI component library with a DSM 7 inspired application theme",
   "license": "MIT",
   "type": "module",
@@ -19,6 +19,7 @@
     "docs/component-defaults-0.5.7.md",
     "docs/json-ui.md",
     "docs/layout-rules.md",
+    "docs/size-and-split.md",
     "docs/theme-hooks.md"
   ],
   "bin": {