@f-ewald/components 1.11.0 → 1.13.0

package/docs/form-field.md

@@ -0,0 +1,63 @@
+# `<form-field>`
+
+Per-field wrapper for a form control: label, slotted control, and an
+optional hint or error message, in one consistent unit repeated across a
+form. Purely presentational — composes whatever control is slotted
+(`form-select`, `multi-select`, `autocomplete-input`, `ui-checkbox`, etc.)
+without intercepting its events or value.
+
+The label wraps the default slot for a best-effort visual/click
+association only: every existing value-entry control encapsulates its
+real `<input>` inside its own shadow DOM, so there is no light-DOM `id` a
+`for` attribute could target from outside, and this component cannot set
+`aria-describedby`/`aria-invalid` on an arbitrary slotted control's
+shadow-encapsulated input for the same reason. The error message uses
+`role="alert"` as the practical accessibility mitigation instead of true
+`aria-describedby` association.
+
+## Install
+
+```js
+import "@f-ewald/components/form-field.js";
+```
+
+## Usage
+
+```html
+<form-field label="Task state" hint="Only affects your own view">
+  <form-select></form-select>
+</form-field>
+<form-field label="Terms" required error="You must accept to continue">
+  <ui-checkbox label="I agree to the terms"></ui-checkbox>
+</form-field>
+```
+
+## Attributes / properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `label` | `label` | `string` | `""` | Field label text. |
+| `hint` | `hint` | `string` | `""` | Optional helper text shown below the control when there's no `error`. |
+| `error` | `error` | `string` | `""` | Optional error text; replaces the `hint` display when non-empty. |
+| `required` | `required` | `boolean` | `false` | Shows a required indicator next to the label. |
+
+## Events
+
+_None._
+
+## Slots
+
+_None._
+
+## CSS custom properties
+
+| Custom property |
+| --- |
+| `--ui-danger` |
+| `--ui-font` |
+| `--ui-font-size-sm` |
+| `--ui-font-size-xs` |
+| `--ui-font-weight-medium` |
+| `--ui-line-height-tight` |
+| `--ui-text` |
+| `--ui-text-muted` |

package/docs/layouts/form-page.md

@@ -24,8 +24,11 @@ column so the eye tracks one field to the next.
   </page-header>
 
   <form style="max-width: 40rem;">
-    <frame-box label="Details"><!-- name, email fields --></frame-box>
-    <frame-box label="Role"><!-- role field --></frame-box>
+    <frame-box label="Details">
+      <form-field label="Name"><autocomplete-input name="name"></autocomplete-input></form-field>
+      <form-field label="Email" hint="Work email preferred"><autocomplete-input name="email"></autocomplete-input></form-field>
+    </frame-box>
+    <frame-box label="Role"><!-- role field, also wrapped in form-field --></frame-box>
 
     <form-actions>
       <ui-button slot="secondary" variant="secondary">Cancel</ui-button>
@@ -43,10 +46,11 @@ column so the eye tracks one field to the next.
 - Constrain the form with a `max-width` (about `40rem`); a full-width form on a
   wide dashboard is hard to scan.
 - Group related fields with `frame-box`; keep one field per row in a single
-  column.
+  column. Wrap each individual field in `form-field` for a consistent
+  label/hint/error layout.
 - `ui-button type="submit"` associates with the ancestor `<form>` even from
   inside `form-actions`.
 
 **Live demo:** `demo/layouts/form-page.html`
 
-**Components:** app-shell, app-sidebar, page-header, frame-box, form-actions, ui-button
+**Components:** app-shell, app-sidebar, page-header, frame-box, form-field, form-actions, ui-button

package/docs/load-more.md

@@ -0,0 +1,43 @@
+# `<load-more>`
+
+Click-to-load button for either end of a list. Fully property-driven: the
+consumer sets `loading` while a fetch is in flight and `exhausted` once
+there's nothing left to load; this component never fetches or manages
+state itself.
+
+## Install
+
+```js
+import "@f-ewald/components/load-more.js";
+```
+
+## Usage
+
+```html
+<load-more direction="top" label="Load older"></load-more>
+<load-more></load-more>
+```
+
+## Attributes / properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `direction` | `direction` | `"top" | "bottom"` | `"bottom"` | Which end of a list this instance loads more content for. |
+| `loading` | `loading` | `boolean` | `false` | Consumer-managed busy flag, forwarded to the internal `ui-button`'s `busy`. |
+| `exhausted` | `exhausted` | `boolean` | `false` | Terminal "no more content" state: disables the button and swaps its label. |
+| `label` | `label` | `string` | `"Load more"` | Button text in the normal (loadable) state. |
+| `exhaustedLabel` | `exhausted-label` | `string` | `"No more results"` | Button text shown once `exhausted` is true. |
+
+## Events
+
+| Event | Description |
+| --- | --- |
+| `load-more` | The button was clicked while not `loading`/`exhausted`; detail: `{ direction }`. |
+
+## Slots
+
+_None._
+
+## CSS custom properties
+
+_None._

package/docs/percent-bar-chart.md

@@ -1,7 +1,11 @@
 # `<percent-bar-chart>`
 
-Horizontal bar chart for labeled percentage rows, using D3's linear scale.
-Each group gets its own labeled row; bars are proportional to percentage of 100.
+Bar chart for labeled rows, using D3's linear scale. Horizontal (default)
+renders stacked rows with bars growing rightward; `orientation="vertical"`
+renders side-by-side columns growing upward instead. `mode="percent"`
+(default) scales `value` against a fixed 0-100 domain and labels it with a
+`%` suffix; `mode="value"` scales it against `max` (or the largest `value`
+present) and formats it with `valueFormat`.
 
 ## Install
 
@@ -14,10 +18,16 @@ import "@f-ewald/components/percent-bar-chart.js";
 ```html
 <percent-bar-chart></percent-bar-chart>
 <script type="module">
-  document.querySelector("percent-bar-chart").groups = [
-    { key: "a", label: "White", pct: 45.2, color: "#4f46e5" },
-    { key: "b", label: "Asian", pct: 28.1, color: "#0d9488" },
+  const chart = document.querySelector("percent-bar-chart");
+  chart.groups = [
+    { key: "a", label: "White", value: 45.2, color: "#4f46e5" },
+    { key: "b", label: "Asian", value: 28.1, color: "#0d9488" },
   ];
+
+  // Absolute values instead of percentages, as vertical columns:
+  chart.mode = "value";
+  chart.orientation = "vertical";
+  chart.valueFormat = (value) => `$${value.toLocaleString()}`;
 </script>
 ```
 
@@ -26,6 +36,10 @@ import "@f-ewald/components/percent-bar-chart.js";
 | Property | Attribute | Type | Default | Description |
 | --- | --- | --- | --- | --- |
 | `groups` | _(JS property only)_ | `PercentBarGroup[]` | `[]` | Rows to render, one per group. |
+| `mode` | `mode` | `PercentBarMode` | `"percent"` | Whether `value` is a 0-100 percentage (fixed domain) or an arbitrary number (domain from data/`max`). |
+| `orientation` | `orientation` | `PercentBarOrientation` | `"horizontal"` | Bar direction: stacked rows growing rightward, or columns growing upward. |
+| `max` | `max` | `number | undefined` | `—` | Explicit domain max for `mode="value"`; auto-computed from `groups` when unset. Ignored in `mode="percent"`. |
+| `valueFormat` | _(JS property only)_ | `(value: number) => string` | `—` | Formats a row's value for its label in `mode="value"`. Defaults to locale-formatted number. |
 
 ## Events
 

package/docs/scroll-to-bottom.md

@@ -0,0 +1,68 @@
+# `<scroll-to-bottom>`
+
+Overlay button that appears once the page (or a given `target` container)
+has scrolled more than `threshold` pixels away from the bottom edge, and
+scrolls back to the bottom on click.
+
+With no `target` (default), the button is `position: fixed` to the
+viewport. When `target` is set, the button switches to `position:
+absolute` and expects to be placed as a descendant of a `position:
+relative` (or otherwise positioned) ancestor that establishes the visual
+bounds to float within — typically `target` itself, given `overflow-y:
+auto; position: relative`, so the button stays pinned to that container's
+own visible corner as its content scrolls, rather than floating over the
+whole page.
+
+## Install
+
+```js
+import "@f-ewald/components/scroll-to-bottom.js";
+```
+
+## Usage
+
+```html
+<scroll-to-bottom></scroll-to-bottom>
+
+<!-- Floats inside its own scrollport instead of the whole page: -->
+<div id="log" style="position: relative; overflow-y: auto; height: 10rem">
+  ...
+  <scroll-to-bottom threshold="20"></scroll-to-bottom>
+</div>
+<script type="module">
+  document.querySelector('scroll-to-bottom').target = document.querySelector('#log');
+</script>
+```
+
+## Attributes / properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `target` | _(JS property only)_ | `HTMLElement | null` | `null` | Scrollable container to control; `null` (default) scrolls `window`. |
+| `threshold` | `threshold` | `number` | `200` | Pixels scrolled away from the bottom before the button appears. |
+| `label` | `label` | `string` | `"Scroll to bottom"` | Visible button text, and its accessible name. |
+
+## Events
+
+| Event | Description |
+| --- | --- |
+| `scroll-to-bottom-triggered` | The button was clicked, just before scrolling; detail: `{ target }`. |
+
+## Slots
+
+_None._
+
+## CSS custom properties
+
+| Custom property |
+| --- |
+| `--ui-border` |
+| `--ui-focus-ring` |
+| `--ui-font` |
+| `--ui-font-size-sm` |
+| `--ui-font-weight-medium` |
+| `--ui-line-height-tight` |
+| `--ui-shadow` |
+| `--ui-surface` |
+| `--ui-surface-muted` |
+| `--ui-text` |

package/docs/scroll-to-top.md

@@ -0,0 +1,59 @@
+# `<scroll-to-top>`
+
+Overlay button that appears once the page (or a given `target` container)
+has scrolled more than `threshold` pixels away from the top edge, and
+scrolls back to the top on click.
+
+With no `target` (default), the button is `position: fixed` to the
+viewport. When `target` is set, the button switches to `position:
+absolute` and expects to be placed as a descendant of a `position:
+relative` (or otherwise positioned) ancestor that establishes the visual
+bounds to float within — typically `target` itself, given `overflow-y:
+auto; position: relative`, so the button stays pinned to that container's
+own visible corner as its content scrolls, rather than floating over the
+whole page.
+
+## Install
+
+```js
+import "@f-ewald/components/scroll-to-top.js";
+```
+
+## Usage
+
+```html
+<scroll-to-top></scroll-to-top>
+```
+
+## Attributes / properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `target` | _(JS property only)_ | `HTMLElement | null` | `null` | Scrollable container to control; `null` (default) scrolls `window`. |
+| `threshold` | `threshold` | `number` | `200` | Pixels scrolled away from the top before the button appears. |
+| `label` | `label` | `string` | `"Scroll to top"` | Visible button text, and its accessible name. |
+
+## Events
+
+| Event | Description |
+| --- | --- |
+| `scroll-to-top-triggered` | The button was clicked, just before scrolling; detail: `{ target }`. |
+
+## Slots
+
+_None._
+
+## CSS custom properties
+
+| Custom property |
+| --- |
+| `--ui-border` |
+| `--ui-focus-ring` |
+| `--ui-font` |
+| `--ui-font-size-sm` |
+| `--ui-font-weight-medium` |
+| `--ui-line-height-tight` |
+| `--ui-shadow` |
+| `--ui-surface` |
+| `--ui-surface-muted` |
+| `--ui-text` |

package/docs/tree-view.md

@@ -0,0 +1,69 @@
+# `<tree-view>`
+
+A generic, presentational tree shell: renders `nodes` recursively, one row
+per node, with each row's content produced by `renderNode` (default: plain
+label). Modeled on `data-table`'s headless pattern — knows nothing about
+what a node's `data` means beyond what `renderNode` does with it.
+
+A node with a `children` array (even empty) is a folder: clicking or
+activating its row toggles expand/collapse instead of firing `node-click`.
+A node with no `children` is a leaf: clicking or activating its row fires
+`node-click`. Folders start collapsed; set `default-expanded` to start
+every folder expanded instead. Expansion state is otherwise managed
+internally and untouched by later `nodes` updates, so a user's manual
+toggles survive a data refresh.
+
+## Install
+
+```js
+import "@f-ewald/components/tree-view.js";
+```
+
+## Usage
+
+```html
+<tree-view></tree-view>
+<script type="module">
+  const tree = document.querySelector("tree-view");
+  tree.nodes = [
+    {
+      id: "docs",
+      label: "docs",
+      children: [{ id: "fil_1", label: "notes.txt", data: { id: "fil_1" } }],
+    },
+    { id: "fil_2", label: "readme.md", data: { id: "fil_2" } },
+  ];
+  tree.renderNode = (node) => node.label;
+  tree.addEventListener("node-click", (e) => console.log(e.detail));
+</script>
+```
+
+## Attributes / properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `nodes` | _(JS property only)_ | `TreeNode[]` | `[]` | Tree data; opaque to this component beyond what `renderNode` does with it. |
+| `renderNode` | _(JS property only)_ | `(node: TreeNode) => unknown` | `—` | Produces a row's rendered content for `node`. Default: plain label text. |
+| `defaultExpanded` | `default-expanded` | `boolean` | `false` | Start every folder expanded instead of the default all-collapsed. |
+
+## Events
+
+| Event | Description |
+| --- | --- |
+| `node-click` | A leaf row was activated; detail is `{ id, data }`. |
+
+## Slots
+
+_None._
+
+## CSS custom properties
+
+| Custom property |
+| --- |
+| `--ui-focus-ring` |
+| `--ui-font` |
+| `--ui-font-size-sm` |
+| `--ui-radius-sm` |
+| `--ui-surface-muted` |
+| `--ui-text` |
+| `--ui-text-muted` |

package/docs/ui-checkbox.md

@@ -0,0 +1,58 @@
+# `<ui-checkbox>`
+
+A form-associated boolean checkbox, usable standalone or inside a native
+`<form>`. Submits `name=on` when checked (matching native
+`<input type="checkbox">` semantics) and participates fully in form
+`reset()`, ancestor `<fieldset disabled>`, and `required` validity.
+
+Renders a native `<input type="checkbox">` wrapped in a `<label>`, styled
+via `:has()` on the wrapping label (matching `radio-pills`/`radio-cards`)
+rather than styling the native input directly; the checkbox itself renders
+at `1rem`, matching the existing radio-input convention.
+
+## Install
+
+```js
+import "@f-ewald/components/ui-checkbox.js";
+```
+
+## Usage
+
+```html
+<ui-checkbox label="Subscribe to updates"></ui-checkbox>
+<ui-checkbox name="terms" label="I agree to the terms" required></ui-checkbox>
+```
+
+## Attributes / properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `checked` | `checked` | `boolean` | `false` | Whether the box is checked. |
+| `indeterminate` | `indeterminate` | `boolean` | `false` | Visual "partial selection" state; cleared on the next user interaction. |
+| `disabled` | `disabled` | `boolean` | `false` | Disables interaction; merged with an ancestor `<fieldset disabled>`. |
+| `required` | `required` | `boolean` | `false` | Marks the control invalid via `ElementInternals` while unchecked. |
+| `name` | `name` | `string` | `""` | Form field name; submitted as `name=on` only while checked. |
+| `label` | `label` | `string` | `""` | Visible label text rendered next to the box. |
+
+## Events
+
+| Event | Description |
+| --- | --- |
+| `change` | The checkbox was toggled by the user, in either direction; detail: `{ checked }`. Programmatic `checked` assignments do not fire it. |
+
+## Slots
+
+_None._
+
+## CSS custom properties
+
+| Custom property |
+| --- |
+| `--ui-danger` |
+| `--ui-focus-ring` |
+| `--ui-font` |
+| `--ui-font-size-sm` |
+| `--ui-line-height-tight` |
+| `--ui-primary` |
+| `--ui-radius-sm` |
+| `--ui-text` |