@f-ewald/components 1.12.0 → 1.14.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/map-circle.md

@@ -1,13 +1,14 @@
 # `<map-circle>`
 
-A plain circular map marker: a light-to-dark gradient fill with a white
-outer ring, no point/tail (unlike `<map-pin>`) — for markers that don't
-need to visually "point" at their exact coordinate. Purely a visual
-primitive — it has no `mapbox-gl` (or any mapping library) dependency;
-the consumer positions it, e.g. via `new mapboxgl.Marker({ element: el })`.
-It can also replace the former `<map-point>` dense-layer primitive: use
-`size="14" ring-width="3"`, leave the slot empty, and rasterize one marker
-per color for use as a map `icon-image`.
+A plain circular map marker: a radial-gradient fill with a soft highlight
+and a translucent white outer ring, no point/tail (unlike `<map-pin>`) —
+for markers that don't need to visually "point" at their exact
+coordinate. Purely a visual primitive — it has no `mapbox-gl` (or any
+mapping library) dependency; the consumer positions it, e.g. via
+`new mapboxgl.Marker({ element: el })`. It can also replace the former
+`<map-point>` dense-layer primitive: use `size="14" ring-width="3"`, leave
+the slot empty, and rasterize one marker per color for use as a map
+`icon-image`.
 
 ## Install
 
@@ -27,9 +28,10 @@ import "@f-ewald/components/map-circle.js";
 
 | Property | Attribute | Type | Default | Description |
 | --- | --- | --- | --- | --- |
-| `color` | `color` | `string` | `"#4f46e5"` | Fill color; the gradient's light (top) and dark (bottom) stops are derived from this. |
+| `color` | `color` | `string` | `"#4f46e5"` | Fill color; the gradient's light (highlight) and dark (edge) stops are derived from this. |
 | `size` | `size` | `number` | `18` | Diameter, in CSS pixels. |
 | `ringWidth` | `ring-width` | `number` | `4` | White outer ring thickness, in the same viewBox units as `size` (scales with it). |
+| `ringOpacity` | `ring-opacity` | `number` | `0.6` | Outer ring opacity, 0-1 (Apple Maps-style rings are translucent, not solid white). |
 | `highlighted` | `highlighted` | `boolean` | `false` | Scales and glows the circle — a generic emphasis state (e.g. hover, selection). |
 
 ## Events

package/docs/map-pin.md

@@ -1,9 +1,9 @@
 # `<map-pin>`
 
-A circular "Apple Maps"-style map pin: a light-to-dark gradient fill with
-a slight point at the bottom. Purely a visual primitive — it has no
-`mapbox-gl` (or any mapping library) dependency; the consumer positions
-it, e.g. via `new mapboxgl.Marker({ element: pinEl })`.
+A circular "Apple Maps"-style map pin: a radial-gradient fill with a soft
+highlight and a slight point at the bottom. Purely a visual primitive —
+it has no `mapbox-gl` (or any mapping library) dependency; the consumer
+positions it, e.g. via `new mapboxgl.Marker({ element: pinEl })`.
 
 ## Install
 
@@ -22,8 +22,9 @@ import "@f-ewald/components/map-pin.js";
 
 | Property | Attribute | Type | Default | Description |
 | --- | --- | --- | --- | --- |
-| `color` | `color` | `string` | `"#4f46e5"` | Fill color; the gradient's light (top) and dark (bottom) stops are derived from this. |
+| `color` | `color` | `string` | `"#4f46e5"` | Fill color; the gradient's light (highlight) and dark (edge) stops are derived from this. |
 | `size` | `size` | `number` | `32` | Diameter of the circular head, in CSS pixels. |
+| `ringOpacity` | `ring-opacity` | `number` | `0.6` | Outer ring opacity, 0-1 (Apple Maps-style rings are translucent, not solid white). |
 | `highlighted` | `highlighted` | `boolean` | `false` | Scales and glows the pin — a generic emphasis state (e.g. hover, selection). |
 
 ## Events

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/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` |