@f-ewald/components 0.4.0 → 0.6.0

package/docs/editable-text.md

@@ -0,0 +1,51 @@
+# `<editable-text>`
+
+Jira/GitHub-style click-to-edit text: a display span that turns into an
+`<input>` (or auto-growing `<textarea>` when `multiline`) on click. The
+input/textarea inherits the host's font, so a title wrapped in an `<h1>`
+edits at title size.
+
+## Install
+
+```js
+import "@f-ewald/components/editable-text.js";
+```
+
+## Usage
+
+```html
+<editable-text value="Write the quarterly report" label="Title"></editable-text>
+<editable-text multiline placeholder="Add a description…" label="Description"></editable-text>
+```
+
+## Attributes / properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `value` | `value` | `string` | `""` | Current text. |
+| `multiline` | `multiline` | `boolean` | `false` | `false` renders an `<input>`, `true` an auto-growing `<textarea>`. |
+| `placeholder` | `placeholder` | `string` | `""` | Muted placeholder text shown when `value` is empty, and as the input's placeholder. |
+| `readonly` | `readonly` | `boolean` | `false` | Disables entering edit mode. |
+| `label` | `label` | `string` | `""` | `aria-label` applied to the input/textarea. |
+
+## Events
+
+| Event | Description |
+| --- | --- |
+| `change` | Fired with `{ value: string }` when the committed value differs from the previous one. |
+
+## Slots
+
+_None._
+
+## CSS custom properties
+
+| Custom property |
+| --- |
+| `--ui-border` |
+| `--ui-focus-ring` |
+| `--ui-primary` |
+| `--ui-radius-sm` |
+| `--ui-surface` |
+| `--ui-surface-muted` |
+| `--ui-text-muted` |

package/docs/form-select.md

@@ -0,0 +1,64 @@
+# `<form-select>`
+
+A styled dropdown select: a trigger button showing the current option's
+label, opening a listbox popover on click. Drop-in generic replacement for
+a native `<select>` wherever consistent cross-browser styling and a
+`change` event carrying `{ value }` are wanted (e.g. a task's status
+picker).
+
+## Install
+
+```js
+import "@f-ewald/components/form-select.js";
+```
+
+## Usage
+
+```html
+<form-select label="Task state"></form-select>
+<script type="module">
+  const select = document.querySelector("form-select");
+  select.options = [
+    { value: "open", label: "Open" },
+    { value: "in_progress", label: "In progress" },
+    { value: "done", label: "Done" },
+  ];
+  select.value = "open";
+  select.addEventListener("change", (e) => console.log(e.detail.value));
+</script>
+```
+
+## Attributes / properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `options` | _(JS property only)_ | `SelectOption[]` | `[]` | The full list of selectable options. |
+| `value` | `value` | `string` | `""` | Currently selected value; must match one of `options[].value`. |
+| `label` | `label` | `string` | `""` | `aria-label` applied to the trigger button. |
+| `disabled` | `disabled` | `boolean` | `false` | Disables the trigger, preventing the popover from opening. |
+
+## Events
+
+| Event | Description |
+| --- | --- |
+| `change` | Fired with `{ value: string }` when a different option is picked. |
+
+## Slots
+
+_None._
+
+## CSS custom properties
+
+| Custom property |
+| --- |
+| `--ui-border` |
+| `--ui-focus-ring` |
+| `--ui-font` |
+| `--ui-font-size-sm` |
+| `--ui-primary` |
+| `--ui-radius-sm` |
+| `--ui-shadow` |
+| `--ui-surface` |
+| `--ui-surface-muted` |
+| `--ui-text` |
+| `--ui-text-muted` |

package/docs/gallery-item-variant.md

@@ -0,0 +1,37 @@
+# `<gallery-item-variant>`
+
+Responsive image source metadata for a parent `gallery-item`.
+
+## Install
+
+```js
+import "@f-ewald/components/gallery-item-variant.js";
+```
+
+## Usage
+
+```html
+<gallery-item-variant
+  media="(max-width: 640px)"
+  srcset="/photos/coast-portrait.jpg"
+></gallery-item-variant>
+```
+
+## Attributes / properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `media` | `media` | `string | undefined` | `—` | Optional media query that controls when this source is selected. |
+| `srcset` | `srcset` | `string` | `""` | Responsive image candidate string passed to a generated `<source>`. |
+
+## Events
+
+_None._
+
+## Slots
+
+_None._
+
+## CSS custom properties
+
+_None._

package/docs/gallery-item.md

@@ -0,0 +1,47 @@
+# `<gallery-item>`
+
+Declarative image metadata consumed by a parent `photo-gallery`.
+
+## Install
+
+```js
+import "@f-ewald/components/gallery-item.js";
+```
+
+## Usage
+
+```html
+<gallery-item
+  src="/photos/coast.jpg"
+  alt="Rocky California coastline"
+  caption="California coast"
+>
+  <gallery-item-variant
+    media="(max-width: 640px)"
+    srcset="/photos/coast-portrait.jpg"
+  ></gallery-item-variant>
+</gallery-item>
+```
+
+## Attributes / properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `src` | `src` | `string` | `""` | URL of the fallback image. |
+| `alt` | `alt` | `string` | `""` | Required alternative text for the image. |
+| `caption` | `caption` | `string | undefined` | `—` | Optional visible caption rendered below the image. |
+| `variants` | _(JS property only)_ | `GalleryItemVariant[]` | `—` | Responsive source variants declared inside this item. _(read-only)_ |
+
+## Events
+
+_None._
+
+## Slots
+
+| Slot | Description |
+| --- | --- |
+| `(default)` | Optional `gallery-item-variant` responsive image sources. |
+
+## CSS custom properties
+
+_None._

package/docs/live-timer.md

@@ -0,0 +1,39 @@
+# `<live-timer>`
+
+Per-second ticking count-up timer, e.g. a live "running for 12s" or
+"Sleeping for 3 seconds" indicator. Renders nothing while `since` is unset
+or unparseable.
+
+## Install
+
+```js
+import "@f-ewald/components/live-timer.js";
+```
+
+## Usage
+
+```html
+<live-timer since="2026-07-19T12:00:00Z" prefix="Sleeping for "></live-timer>
+<live-timer since="2026-07-19T12:00:00Z" format="compact" prefix="running for "></live-timer>
+```
+
+## Attributes / properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `since` | `since` | `string | null` | `null` | ISO-8601 start instant; elapsed time is measured from here. |
+| `format` | `format` | `DurationFormat` | `"seconds"` | `"seconds"` -> "1 second", "12 seconds"; `"compact"` -> "12s", "3m 12s", "1h 03m 12s". |
+| `prefix` | `prefix` | `string` | `""` | Text rendered before the formatted value. |
+| `suffix` | `suffix` | `string` | `""` | Text rendered after the formatted value. |
+
+## Events
+
+_None._
+
+## Slots
+
+_None._
+
+## CSS custom properties
+
+_None._

package/docs/map-point.md

@@ -19,7 +19,8 @@ import "@f-ewald/components/map-point.js";
 ## Usage
 
 ```html
-<map-point></map-point>
+<map-point color="#0099D8"></map-point>
+<map-point color="#fb8072" size="10" ring-width="2"></map-point>
 ```
 
 ## Attributes / properties

package/docs/photo-gallery.md

@@ -0,0 +1,77 @@
+# `<photo-gallery>`
+
+Responsive, accessible image carousel composed from declarative
+`gallery-item` children.
+
+## Install
+
+```js
+import "@f-ewald/components/photo-gallery.js";
+```
+
+## Usage
+
+```html
+<photo-gallery delay="5000" show-counter show-indicators>
+  <gallery-item
+    src="/photos/coast.jpg"
+    alt="Rocky California coastline"
+    caption="California coast"
+  >
+    <gallery-item-variant
+      media="(max-width: 640px)"
+      srcset="/photos/coast-portrait.jpg"
+    ></gallery-item-variant>
+  </gallery-item>
+  <gallery-item src="/photos/bridge.jpg" alt="Golden Gate Bridge"></gallery-item>
+</photo-gallery>
+<script type="module">
+  document.querySelector("photo-gallery").addEventListener("slide-change", (event) => {
+    console.log(event.detail.currentIndex);
+  });
+</script>
+```
+
+## Attributes / properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `currentIndex` | `current-index` | `number` | `0` | Zero-based active image index. |
+| `delay` | `delay` | `number` | `0` | Autoplay interval in milliseconds. Set to zero to disable autoplay. |
+| `showControls` | `show-controls` | `boolean` | `true` | Whether previous and next buttons are shown. |
+| `showCounter` | `show-counter` | `boolean` | `false` | Whether a current/total counter is shown. |
+| `showIndicators` | `show-indicators` | `boolean` | `false` | Whether clickable slide indicators are shown. |
+| `showAutoplayControl` | `show-autoplay-control` | `boolean` | `true` | Whether autoplay includes a built-in pause/play control. |
+| `paused` | `paused` | `boolean` | `false` | Whether autoplay is explicitly paused. |
+| `aspectRatio` | `aspect-ratio` | `string` | `"16 / 9"` | CSS aspect ratio used by the image viewport. |
+| `objectFit` | `object-fit` | `PhotoGalleryObjectFit` | `"cover"` | How images fit within the stable viewport. |
+
+## Events
+
+| Event | Description |
+| --- | --- |
+| `slide-change` | The active image changed. |
+
+## Slots
+
+| Slot | Description |
+| --- | --- |
+| `(default)` | Declarative `gallery-item` elements rendered as slides. |
+
+## CSS custom properties
+
+| Custom property |
+| --- |
+| `--ui-border` |
+| `--ui-focus-ring` |
+| `--ui-font` |
+| `--ui-font-size` |
+| `--ui-font-size-sm` |
+| `--ui-overlay` |
+| `--ui-primary` |
+| `--ui-radius` |
+| `--ui-radius-sm` |
+| `--ui-surface` |
+| `--ui-surface-muted` |
+| `--ui-text` |
+| `--ui-text-muted` |

package/docs/popover-panel.md

@@ -0,0 +1,66 @@
+# `<popover-panel>`
+
+Generic anchored popover shell: a floating card positioned relative to its
+nearest `position: relative` ancestor (place it next to its trigger button
+inside such a wrapper), as opposed to `slide-panel`'s fixed screen-edge
+drawer. Closes on outside click or Escape. Header chrome and close button
+match `slide-panel`'s API (`heading`, `panel-close`) so either can be
+swapped in for the other with no consumer-side changes beyond the wrapper.
+
+Set `centered` to render as a screen-centered modal with a translucent
+backdrop instead of the default anchored placement.
+
+## Install
+
+```js
+import "@f-ewald/components/popover-panel.js";
+```
+
+## Usage
+
+```html
+<div style="position: relative; display: inline-block;">
+  <button id="new-task-btn">New task</button>
+  <popover-panel heading="New task">
+    Popover body content goes here.
+  </popover-panel>
+</div>
+<script type="module">
+  const popover = document.querySelector("popover-panel");
+  document.querySelector("#new-task-btn").addEventListener("click", () => (popover.open = true));
+  popover.addEventListener("panel-close", () => (popover.open = false));
+</script>
+```
+
+## Attributes / properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `open` | `open` | `boolean` | `false` | Whether the popover is currently visible. |
+| `heading` | `heading` | `string` | `""` | Title text shown in the popover header. |
+| `centered` | `centered` | `boolean` | `false` | Render as a screen-centered modal with a backdrop instead of anchored placement. |
+
+## Events
+
+| Event | Description |
+| --- | --- |
+| `panel-close` | User clicked the close (✕) button, pressed Escape, or clicked outside/the backdrop. |
+
+## Slots
+
+_None._
+
+## CSS custom properties
+
+| Custom property |
+| --- |
+| `--ui-border` |
+| `--ui-font` |
+| `--ui-font-size` |
+| `--ui-radius` |
+| `--ui-radius-sm` |
+| `--ui-shadow-lg` |
+| `--ui-surface` |
+| `--ui-surface-muted` |
+| `--ui-text` |
+| `--ui-text-muted` |

package/docs/stat-meter.md

@@ -0,0 +1,48 @@
+# `<stat-meter>`
+
+A compact labeled meter for a single percentage reading — e.g. CPU or
+memory usage in a dashboard header. `percent` may be `null` when no
+reading is available yet (e.g. the first tick of a polling metric); the
+bar then renders empty and the value shows an em dash instead of "0%".
+
+## Install
+
+```js
+import "@f-ewald/components/stat-meter.js";
+```
+
+## Usage
+
+```html
+<stat-meter label="CPU" percent="42"></stat-meter>
+<stat-meter label="MEM" percent="76"></stat-meter>
+<stat-meter label="I/O"></stat-meter> <!-- percent unset -> null -> renders "—" -->
+<stat-meter label="GPU" percent="88" color="#dc2626"></stat-meter>
+```
+
+## Attributes / properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `label` | `label` | `string` | `""` | Short label shown before the bar, e.g. "CPU" or "MEM". |
+| `percent` | `percent` | `number | null` | `null` | Percentage 0-100. `null` renders an empty bar and a "—" value instead of "0%". |
+| `color` | `color` | `string` | `""` | Fill color override; falls back to the `--ui-success` token. |
+
+## Events
+
+_None._
+
+## Slots
+
+_None._
+
+## CSS custom properties
+
+| Custom property |
+| --- |
+| `--ui-font` |
+| `--ui-font-size-sm` |
+| `--ui-success` |
+| `--ui-surface-muted` |
+| `--ui-text` |
+| `--ui-text-muted` |

package/docs/status-pill.md

@@ -0,0 +1,43 @@
+# `<status-pill>`
+
+Small colored status pill, optionally with a spinning icon — for task/run
+states ("Open", "Blocked", "Done") and live-activity indicators ("Running").
+
+## Install
+
+```js
+import "@f-ewald/components/status-pill.js";
+```
+
+## Usage
+
+```html
+<status-pill label="Running" color="primary" spinner></status-pill>
+<status-pill label="Blocked" color="danger"></status-pill>
+```
+
+## Attributes / properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `label` | `label` | `string` | `""` | Text shown inside the pill. |
+| `color` | `color` | `StatusPillColor` | `"neutral"` | Color variant. |
+| `spinner` | `spinner` | `boolean` | `false` | Renders a small spinning icon before the label. |
+
+## Events
+
+_None._
+
+## Slots
+
+_None._
+
+## CSS custom properties
+
+| Custom property |
+| --- |
+| `--ui-danger` |
+| `--ui-font` |
+| `--ui-primary` |
+| `--ui-success` |
+| `--ui-text-muted` |

package/docs/tile-grid.md

@@ -0,0 +1,58 @@
+# `<tile-grid>`
+
+A generic, presentational grid shell: renders one bordered card per entry
+in `items`, with each tile's content produced by `renderTile` (default:
+stringify). Knows nothing about what an "item" means — callers own the
+data shape entirely. Modeled directly on `data-table`'s headless pattern.
+
+Optional `itemHref` makes whole tiles clickable (navigating via
+`location.hash`), without hijacking clicks on nested interactive elements
+(links/buttons) a tile's rendered content might contain.
+
+## Install
+
+```js
+import "@f-ewald/components/tile-grid.js";
+```
+
+## Usage
+
+```html
+<tile-grid></tile-grid>
+<script type="module">
+  const grid = document.querySelector("tile-grid");
+  grid.items = [
+    { name: "notes.txt" },
+    { name: "photo.jpg" },
+  ];
+  grid.renderTile = (item) => item.name;
+</script>
+```
+
+## Attributes / properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `items` | _(JS property only)_ | `unknown[]` | `[]` | Tile data; opaque to this component beyond what `renderTile` does with it. |
+| `itemKey` | _(JS property only)_ | `(item: unknown, index: number) => string | number` | `—` | Stable identity for `items[i]`, used as the repeat-directive key. Defaults to the item's index. |
+| `renderTile` | _(JS property only)_ | `(item: unknown) => unknown` | `—` | Produces a tile's rendered content for `item`. Default: stringify. |
+| `itemHref` | _(JS property only)_ | `((item: unknown) => string | null) | null` | `null` | When set, clicking a tile (outside any nested link/button) navigates to this hash. |
+
+## Events
+
+_None._
+
+## Slots
+
+_None._
+
+## CSS custom properties
+
+| Custom property |
+| --- |
+| `--ui-border` |
+| `--ui-font` |
+| `--ui-font-size-sm` |
+| `--ui-radius` |
+| `--ui-surface-muted` |
+| `--ui-text` |

package/docs/user-avatar.md

@@ -24,7 +24,7 @@ import "@f-ewald/components/user-avatar.js";
 | --- | --- | --- | --- | --- |
 | `src` | `src` | `string | null` | `null` | Image URL to show. Falls back to initials/icon if unset or it fails to load. |
 | `name` | `name` | `string | null` | `null` | Source string for the fallback initial (e.g. a display name or email) — first character, uppercased. |
-| `size` | `size` | `number` | `32` | Diameter in CSS pixels. |
+| `size` | `size` | `string | number` | `32` | Diameter in CSS pixels, or a preset name (`xs`=18, `sm`=24, `md`=32, `lg`=48). |
 
 ## Events