@synopackageland/ui 0.13.2 → 0.14.1

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synopackageland/ui",
-  "version": "0.13.2",
+  "version": "0.14.1",
   "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": {