@reliability-design/web 1.4.9 → 1.4.10

package/dist/components/rel-tree/README.md

@@ -0,0 +1,157 @@
+# rel-tree
+
+<!-- @unreleased-component 1.5.0 -->
+
+A hierarchical list whose parents expand and collapse (Figma "Nested Tree"). Each entry in `items` renders as a 24px row: hierarchy guides in the indentation, a caret on parents, a checkbox in `multiple` mode, an optional icon, and a one-line label that truncates with an ellipsis. The tree follows the WAI-ARIA Tree View pattern: it is one Tab stop, and the arrow keys move between rows and expand or collapse them. Use it for file browsers, nested navigation, or any data with more than two levels. Use `rel-accordion` for a few collapsible sections of content, and `rel-menu` for a list of actions.
+
+The tree has no background, padding or radius of its own. Place it inside the surface that hosts it, such as a card, a side panel or a drawer.
+
+## Usage
+
+```html
+<!-- Items are set as a property; `selected` holds the selected value -->
+<rel-tree id="files" field-aria-label="Project files" selected="button"></rel-tree>
+<script>
+  document.getElementById('files').items = [
+    { value: 'src', label: 'src', icon: 'document', expanded: true, children: [
+      { value: 'button', label: 'button.ts', icon: 'document' },
+      { value: 'card', label: 'card.ts', icon: 'document' }
+    ] },
+    { value: 'package', label: 'package.json', icon: 'document' }
+  ];
+  document.getElementById('files').addEventListener('rel-change', (e) => {
+    console.log('selected', e.detail.value);
+  });
+</script>
+
+<!-- Multiple selection: a checkbox on every row; checking a parent checks its subtree -->
+<rel-tree id="scope" selection="multiple" field-aria-label="Folders to sync"></rel-tree>
+<script>
+  const scope = document.getElementById('scope');
+  scope.items = [
+    { value: 'docs', label: 'docs', expanded: true, children: [
+      { value: 'guides', label: 'guides' },
+      { value: 'api', label: 'api' }
+    ] },
+    { value: 'assets', label: 'assets' }
+  ];
+  scope.selectedValues = ['guides'];       // docs shows the indeterminate glyph
+  scope.addEventListener('rel-change', (e) => {
+    console.log('checked', e.detail.value); // e.g. ['docs', 'guides', 'api']
+  });
+</script>
+
+<!-- Lazy children: load a branch the first time it opens -->
+<rel-tree id="remote" field-aria-label="Remote folders"></rel-tree>
+<script>
+  const remote = document.getElementById('remote');
+  remote.items = [{ value: 'home', label: 'home', lazy: true }];
+  remote.addEventListener('rel-load-children', async (e) => {
+    const item = findItem(remote.items, e.detail.value); // your own lookup
+    item.children = await fetchFolder(e.detail.value);    // [] when it has none
+    remote.items = [...remote.items];                     // assign again to re-render
+  });
+</script>
+
+<!-- Navigation only: no selection, Enter and clicks on a parent expand or collapse it -->
+<rel-tree selection="none" field-aria-label="Sections"
+  items='[{"value":"a","label":"Getting started","children":[{"value":"a1","label":"Install"}]}]'>
+</rel-tree>
+
+<!-- Without the hierarchy guides (the indentation stays) -->
+<rel-tree show-guides="false" field-aria-label="Outline"></rel-tree>
+```
+
+In `multiple` mode the check cascades. Checking a parent checks every enabled descendant, and unchecking it clears them; disabled rows keep their state. A parent is checked when all of its children are, unchecked when none are, and indeterminate otherwise. `selected-values` lists every checked value, parents included. When you set it, a parent's value checks its whole subtree, and the array is rewritten in that full form.
+
+A `lazy` item has a caret while its `children` is undefined. Expanding it (by the user, by `expanded: true` or through `expanded-values`) fires `rel-load-children` once and marks the row `aria-busy="true"`. Set the item's `children` and assign `items` again: the row stays open and shows them. An empty array makes the item a leaf. In `multiple` mode, children that load under a checked item arrive checked.
+
+`expanded-values` holds the values of the open parents. It is seeded from the items' `expanded` flags and updated on every expand or collapse; set it to control expansion, or call `expandAll()` / `collapseAll()`.
+
+<!-- readme-gen:start -->
+
+<!-- Generated from rel-tree.ts — do not edit; run readme-generate.mjs -->
+
+## API
+
+### Attributes / Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `items` | `items` | `TreeItem[]` | `[]` | The tree's items, each `{ value, label, icon?, children?, expanded?, disabled?, lazy? }`. Set as a property or as a JSON array attribute. |
+| `selection` | `selection` | `"single" \| "multiple" \| "none"` | `"single"` | Selection mode: `single` (default; the selected row has the Figma Active style and `aria-selected="true"`), `multiple` (a checkbox on every row, see `selected-values`) or `none` (navigation only: Enter, Space and clicks on a parent row expand or collapse it). Reflected. |
+| `selected` | `selected` | `string` | `""` | `value` of the selected item in `single` mode; `""` when nothing is selected. Updated on every user selection. |
+| `selectedValues` | `selected-values` | `string[]` | `[]` | Values of the checked items in `multiple` mode. Checking a parent checks every enabled descendant and unchecking it clears them; a parent is checked when all its children are, and shows the indeterminate glyph (`aria-checked="mixed"`) when only some are. The array lists every checked value, parents included, and is rewritten in that form when you set it: a parent's value checks its whole subtree. |
+| `expandedValues` | `expanded-values` | `string[]` | `[]` | Values of the expanded parents. Seeded from the items' `expanded` flags, updated whenever the user expands or collapses a row; set it to control expansion. |
+| `showGuides` | `show-guides` | `boolean` | `true` | Draws the hierarchy guides (│ ├ └) in the indentation. On by default; `show-guides="false"` hides them and keeps the indentation. Reflected. |
+| `fieldAriaLabel` | `field-aria-label` | `string` | `undefined` | Accessible name of the tree. The tree renders no visible label of its own, so set this (a console warning names trees without one). |
+
+### Methods
+
+| Method | Signature | Description |
+| --- | --- | --- |
+| `expandAll` | `expandAll()` | Expands every parent that has children (lazy items whose children have not been loaded stay closed). |
+| `collapseAll` | `collapseAll()` | Collapses every parent. |
+
+## Events
+
+| Event | Detail | Bubbles / composed | Description |
+| --- | --- | --- | --- |
+| `rel-change` | `{ value: [...this.selectedValues] } / { value: item.value }` | bubbles / composed | The user changed the selection with Enter, Space or a click: picked a row in `single` mode (detail `{ value: string }`) or checked / unchecked one in `multiple` mode (detail `{ value: string[] }`, the new `selected-values`). |
+| `rel-expanded-change` | `{ value: item.value, expanded }` | bubbles / composed | The user expanded or collapsed a parent. Detail: `{ value: string; expanded: boolean }`. |
+| `rel-load-children` | `{ value }` | bubbles / composed | A `lazy` item without `children` was expanded (by the user, `expanded` or `expanded-values`). Load its children, set them on the item and assign `items` again. Fired once per item until its children arrive. Detail: `{ value: string }`. |
+
+## Slots
+
+| Slot | Description |
+| --- | --- |
+| — | This element has no slots. |
+
+## CSS Parts
+
+| Part | Description |
+| --- | --- |
+| `item` | Each `role="treeitem"` element; it contains the item's row and, when expanded, the group of its children. |
+| `row` | The visible row of an item (guides, caret, checkbox, icon, label). Carries the hover, pressed, selected and focus styles. |
+| `guide` | One hierarchy-guide column, one per level of indentation. |
+| `caret` | The expand / collapse caret of a parent row. |
+| `checkbox` | The check glyph of a row in `multiple` mode (Figma .Check Control: unchecked, checked, indeterminate). |
+| `icon` | The optional leading icon. |
+| `label` | The label text. |
+| `group` | The `role="group"` list that holds an expanded item's children. |
+| `tree` | The `role="tree"` list. |
+
+## Tokens / CSS Variables
+
+### Component hooks
+
+Set these on the host (or an ancestor) to customise the element without touching design tokens.
+
+| Custom property | Default | Description |
+| --- | --- | --- |
+| `--rel-tree-guide-color` | `var(--rel-border-subtle)` | Colour of the hierarchy guides (default `var(--rel-border-subtle)`). |
+| `--rel-tree-indent` | `24px` | Width of one level of indentation, one guide column (default 24px). |
+| `--rel-tree-row-height` | `24px` | Row height (default 24px, Figma .Tree Item). |
+
+<!-- readme-gen:end -->
+
+## Accessibility
+
+- The tree needs an accessible name: set `field-aria-label`. The component logs a console warning when it has none.
+- Rows are `role="treeitem"` elements with `aria-level`, `aria-posinset`, `aria-setsize`, `aria-expanded` (parents only), `aria-selected` (single mode), `aria-checked` (`true`, `false` or `mixed`, multiple mode) `aria-disabled` and, while a lazy item loads, `aria-busy`. In multiple mode the tree carries `aria-multiselectable="true"`. Each row is named by its label alone; the caret, checkbox glyph, icon and guides are hidden from assistive technology.
+- The focused row shows an inset 2px focus ring. In forced-colours mode the selected row uses `Highlight` and the guides use `CanvasText`.
+
+### Keyboard
+
+| Key | Action |
+| --- | --- |
+| Tab / Shift+Tab | Moves focus into or out of the tree (one Tab stop, on the selected row, or the first row) |
+| Down / Up | Next / previous visible row |
+| Right | Expands a closed parent; on an open parent, moves to its first child |
+| Left | Collapses an open parent; otherwise moves to the parent |
+| Home / End | First / last visible row |
+| Enter / Space | Selects the row (`selection="single"`), checks or unchecks it (`selection="multiple"`), or expands or collapses a parent (`selection="none"`) |
+| `*` | Expands every sibling of the focused row |
+| Typing a letter | Moves to the next row whose label starts with the typed text |
+
+In a right-to-left context, Right and Left swap and the guides and carets mirror. Disabled rows stay focusable, so the keyboard can reach and read them, but they cannot be selected, checked or expanded.

package/dist/components/rel-upload/README.md

@@ -43,7 +43,7 @@ File upload: `<rel-upload>` renders the dropzone, the format / size hint, the st
     // Any transport works; honour `signal` so Cancel aborts, call `onProgress(loaded, total)` for the bar.
     await putWithProgress('/api/photos', file, { signal, onProgress });
   };
-  photos.addEventListener('rel-complete', (e) => {
+  photos.addEventListener('rel-upload-complete', (e) => {
     console.log('done', e.detail.succeeded.length, 'failed', e.detail.failed.length);
   });
 </script>
@@ -91,11 +91,12 @@ File upload: `<rel-upload>` renders the dropzone, the format / size hint, the st
 | `accept` | `accept` | `string` | `""` | Comma-separated accept list, e.g. ".pdf,.png,.jpg" or "image/*". |
 | `maxSize` | `max-size` | `string` | `""` | Max size per file as a human string ("10MB", "500kb"). Empty → no limit. |
 | `multiple` | `multiple` | `boolean` | `false` | Allow more than one file. |
+| `maxFiles` | `max-files` | `number` | `0` | New in 1.5.0. With `multiple`, the most files the list may hold; `0` (the default) means no limit. Files beyond it become error rows ("only 5 files allowed") and `rel-invalid` rejections with `reason: "count"`. Rows already in the list count first, then new files in selection order; rows rejected by `accept`, `max-size` or the limit hold no place. `retry()` checks the limit again, so removing rows lets a rejected one through. Ignored without `multiple` (one file at a time). |
 | `disabled` | `disabled` | `boolean` | `false` | Disables the whole control. Reflected. |
 | `hint` | `hint` | `string` | `""` | Overrides the derived "PDF, PNG or JPG - up to 10 MB per file" hint. |
 | `dropzoneTitle` | `dropzone-title` | `string` | `"Drag and drop your files here"` | Dropzone headline. |
 | `browseLabel` | `browse-label` | `string` | `"Browse files"` | Browse button label. |
-| `files` | — | `UploadFile[]` | `[]` | The file list. Set it to drive the component in controlled mode; the component also maintains it itself as files are added and removed. Property only. |
+| `files` | — | `UploadFile[]` | `[]` | The file list. Set it to drive the component in controlled mode; the component also maintains it itself as files are added and removed. A row whose `file` is an image (`image/*`) shows a 40px preview in place of the file icon (new in 1.5.0); its object URL is revoked when the row leaves the list and when the element disconnects. Property only. |
 | `uploader` | — | `(file: File, ctx: UploaderContext) => Promise<void>` | `undefined` | Supply an `Uploader` `(file, { file, signal, onProgress }) => Promise<void>` to switch to self-driving mode: the component runs the batch itself with `concurrency`, progress, the delay alert, abort and retry. Unset (default) the component only emits intents. Property only. |
 | `concurrency` | `concurrency` | `number` | `3` | Max files transferred at once in self-driving mode. |
 | `delayThreshold` | `delay-threshold` | `number` | `15000` | ms of continuous uploading before the "taking longer than usual" alert. |
@@ -125,16 +126,18 @@ File upload: `<rel-upload>` renders the dropzone, the format / size hint, the st
 | --- | --- | --- | --- |
 | `rel-cancel` | — | bubbles / composed | Fired when Cancel is pressed (or `cancel()` is called); in-flight transfers are aborted, the list is kept. No detail. |
 | `rel-change` | `{ files: this.files }` | bubbles / composed | Fired whenever the file list changes (files added, a row removed, `reset()`). Detail: `{ files: UploadFile[] }`. |
-| `rel-complete` | `{ succeeded: this.files.filter((f) => f.status === "success"), failed: this.failedFiles, }` | bubbles / composed | Fired when the whole self-driving batch settles without being cancelled. Detail: `{ succeeded: UploadFile[], failed: UploadFile[] }`. |
+| `rel-complete` | `{ succeeded: this.files.filter((f) => f.status === "success"), failed: this.failedFiles, }` | bubbles / composed | Deprecated: use `rel-upload-complete`, which fires once per batch in both modes; removed in 3.0. It still fires as before, and listening for it logs a one-time console warning. Fired when the whole self-driving batch settles without being cancelled. Detail: `{ succeeded: UploadFile[], failed: UploadFile[] }` (every success and error row in the list). Self-driving mode only; `rel-upload-complete` covers both modes. |
 | `rel-file-complete` | `{ id: item.id, file: item.file }` | bubbles / composed | Fired when one file finishes uploading in self-driving mode. Detail: `{ id: string, file: File }`. |
 | `rel-file-error` | `{ id: item.id, file: item.file, error: message }` | bubbles / composed | Fired when one file's `uploader` rejects in self-driving mode. Detail: `{ id: string, file: File, error: string }`. |
+| `rel-file-replaced` | `{ name: previous.name, previous, next }` | bubbles / composed | New in 1.5.0. Fired once per list entry that a newly picked file with the same name replaced (the replace itself is unchanged: names stay unique). The component also announces it and shows an info notice in its alert slot. Detail: `{ name: string, previous: UploadFile, next: UploadFile }`. |
 | `rel-files-added` | `{ added, rejected }` | bubbles / composed | Fired after files are picked or dropped and validated. Detail: `{ added: UploadFile[], rejected: UploadRejection[] }`. |
-| `rel-invalid` | `{ rejected }` | bubbles / composed | Fired just before `rel-files-added` when at least one picked file fails `accept` / `max-size`. Detail: `{ rejected: UploadRejection[] }`. |
+| `rel-invalid` | `{ rejected }` | bubbles / composed | Fired just before `rel-files-added` when at least one picked file fails `accept` / `max-size` / `max-files`. Detail: `{ rejected: UploadRejection[] }`. |
 | `rel-progress` | `{ id: item.id, progress, loaded, total: t }` | bubbles / composed | Fired on every progress tick in self-driving mode. Detail: `{ id: string, progress: number (0–100), loaded: number, total: number }` (bytes). |
 | `rel-remove` | `{ id, file: target?.file }` | bubbles / composed | Fired when a row is removed via its delete button or `removeFile()`. Detail: `{ id: string, file?: File }`. |
 | `rel-retry` | `{ files: requeued }` | bubbles / composed | Fired when Retry re-queues the retryable failed rows. Detail: `{ files: UploadFile[] }`. |
 | `rel-state` | `s / this.state` | bubbles / composed | Fired when the derived `state` snapshot changes (and once after connecting). Detail: `UploadState`. |
 | `rel-upload` | `{ files: targets }` | bubbles / composed | Fired when Upload is pressed (or `upload()` is called) with the rows still `ready`; in controlled mode the app performs the transfer. Detail: `{ files: UploadFile[] }`. |
+| `rel-upload-complete` | `settled` | bubbles / composed | New in 1.5.0. Fired once per batch when nothing is uploading any more, in BOTH modes: in self-driving mode when the `uploader` calls settle, in controlled mode when the app moves the last `uploading` row it set to `success` or `error`. Not fired after `cancel()`. The component announces the result politely ("3 files uploaded", "2 uploaded, 1 failed"), and when nothing failed it shows a success alert in its alert slot ("3 files uploaded"; the delay warning and the failure alert come first). It shows no toast: listen for this event to show your own (for example a success `rel-toast`). Detail: `{ succeeded: UploadFile[], failed: UploadFile[] }`, the rows of this batch only. |
 
 ### Slots
 
@@ -208,7 +211,7 @@ Set these on the host (or an ancestor) to customise the element without touching
 
 ## Notes / Edge Cases
 
-- **Modes.** Without `uploader` the component only emits intents (`rel-upload`, `rel-retry`, `rel-cancel`, `rel-remove`) and your app must write `status` / `progress` / `loaded` / `error` back onto `files` (replace the array — rows are keyed by `id`). With `uploader` the component patches `files` itself, runs up to `concurrency` transfers at once, emits `rel-progress` / `rel-file-complete` / `rel-file-error` per file and `rel-complete` when the batch settles.
+- **Modes.** Without `uploader` the component only emits intents (`rel-upload`, `rel-retry`, `rel-cancel`, `rel-remove`) and your app must write `status` / `progress` / `loaded` / `error` back onto `files` (replace the array — rows are keyed by `id`). With `uploader` the component patches `files` itself, runs up to `concurrency` transfers at once, emits `rel-progress` / `rel-file-complete` / `rel-file-error` per file and `rel-upload-complete` when the batch settles (`rel-complete` still fires too, but is deprecated: listening for it logs a one-time console warning, and it is removed in 3.0).
 - **Validation happens on pick.** Files failing `accept` or `max-size` are kept as `error` rows ("unsupported file type" / "file exceeds the 10MB limit") — that is how the Figma Failure state surfaces them — and are reported in `rel-invalid` and `rel-files-added.rejected`. `retry()` skips rows that would fail validation again (and rows without a `file` object); if every failed row is unretryable the Retry button stays disabled — remove the row instead.
 - **`accept` tokens** are `.ext` (name suffix), `type/*` (MIME prefix) or an exact MIME type; the hint line is derived from them ("PDF, PNG or JPG") plus `max-size` ("- up to 10MB per file"). `max-size` accepts `b` / `kb` / `mb` / `gb` (decimal: 1MB = 1,000,000 bytes); an unparseable string means no limit.
 - **Same-named files replace** the existing entry instead of duplicating it. Without `multiple` only the first picked file is taken and it replaces the whole list.