@f-ewald/components 0.5.0 → 0.7.0

package/docs/form-select.md

@@ -0,0 +1,70 @@
+# `<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).
+
+The trigger fills its host's width (`justify-content: space-between`
+pushes the chevron to the far edge), but the host itself stays
+`display: inline-block` — so usages that never size the host (a filter
+bar, a status picker) keep shrink-to-fit auto-width unchanged. To make an
+instance full-width, size the host itself: `form-select { width: 100%; }`.
+
+## 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/frame-box.md

@@ -0,0 +1,43 @@
+# `<frame-box>`
+
+A titled frame around a slot: a gray border with a small uppercase,
+muted label overlapping the top edge (fieldset/legend-style). Generic —
+the label text is entirely up to the consumer (e.g. "Debug" to visually
+fence off dev-only chrome from the product UI).
+
+## Install
+
+```js
+import "@f-ewald/components/frame-box.js";
+```
+
+## Usage
+
+```html
+<frame-box label="Debug">
+  Framed content goes here.
+</frame-box>
+```
+
+## Attributes / properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `label` | `label` | `string` | `""` | The overlapping title label, e.g. "Debug". |
+
+## Events
+
+_None._
+
+## Slots
+
+_None._
+
+## CSS custom properties
+
+| Custom property |
+| --- |
+| `--ui-border` |
+| `--ui-radius-sm` |
+| `--ui-surface` |
+| `--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/icon-button.md

@@ -0,0 +1,52 @@
+# `<icon-button>`
+
+A borderless button wrapping a passed-in icon, with a rounded
+hover-highlight background. Use for a low-emphasis affordance next to
+content it acts on (e.g. an "Edit" pencil at the end of a table row)
+where a bordered `ui-button` would be too heavy.
+
+## Install
+
+```js
+import "@f-ewald/components/icon-button.js";
+```
+
+## Usage
+
+```html
+<icon-button label="Edit"></icon-button>
+<script type="module">
+  import { iconPencil } from "@f-ewald/components/icons.js";
+  const btn = document.querySelector("icon-button");
+  btn.icon = iconPencil(16);
+  btn.addEventListener("click", () => console.log("edit clicked"));
+</script>
+```
+
+## Attributes / properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `icon` | _(JS property only)_ | `TemplateResult | null` | `null` | Pre-rendered icon template, e.g. `iconPencil(16)` from this package's icon set. |
+| `label` | `label` | `string` | `""` | Required accessible label, applied as `aria-label`/`title`. |
+| `disabled` | `disabled` | `boolean` | `false` | Disables the button and dims it. |
+
+## Events
+
+| Event | Description |
+| --- | --- |
+| `click` | Native click, bubbling as usual — listen on the element itself. |
+
+## Slots
+
+_None._
+
+## CSS custom properties
+
+| Custom property |
+| --- |
+| `--ui-focus-ring` |
+| `--ui-radius-sm` |
+| `--ui-surface-muted` |
+| `--ui-text` |
+| `--ui-text-muted` |

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/mcp-evaluation.md

@@ -1,31 +1,38 @@
 # MCP server evaluation
 
-**Recommendation: do not build an MCP server for this package now.**
+**Update (0.6.0 era, 34 components): built.** The catalog crossed the ~30+
+revisit threshold below, so the upgrade path described here was implemented
+as `src/mcp-server.ts`. See the "MCP server" section in the root `CLAUDE.md`
+for the current tools, build step, and how consuming projects wire it up.
+The original evaluation is kept below for the reasoning that justified
+waiting until this point.
+
+## Original recommendation (superseded): do not build an MCP server yet
 
 ## Rationale
 
-The component catalog is small (14 tags). `llms.txt` ships in the npm
+The component catalog was small (14 tags). `llms.txt` ships in the npm
 package and is fetchable directly from unpkg or GitHub raw, so any LLM or
 agent can load the full API surface — every component's attributes,
 properties, events, slots, tokens, and a usage example — in one small file,
 with no server, process, or additional versioning/packaging burden. An MCP
 server would duplicate that same data behind a stdio process that needs its
 own install, auth-free-but-still-a-process lifecycle, and release cadence
-kept in sync with the package — for zero functional gain at this scale.
+kept in sync with the package — for zero functional gain at that scale.
 
-## When to revisit
+## When to revisit (met)
 
 - The catalog grows past a size where `llms.txt` stops being comfortable to
-  load into a single context window (rule of thumb: ~30+ components).
+  load into a single context window (rule of thumb: ~30+ components). —
+  **met at 34 components.**
 - Consumers want live search, fuzzy matching, or filtered/paginated results
   instead of "load everything."
 - Consumers want examples or docs that go beyond what's derivable from
   `custom-elements.json` (e.g. runnable playground snippets, live preview).
 
-## Upgrade path
+## Upgrade path (implemented)
 
-If/when it's warranted, a thin stdio MCP server exposing two tools —
-`list_components` and `get_component_docs(tag)` — backed by the same
-`custom-elements.json` this package already generates and ships. No new
-data source would be needed; the server would just be a different transport
-over data that already exists.
+A thin stdio MCP server exposing two tools — `list_components` and
+`get_component_docs(tag)` — backed by the same `custom-elements.json` this
+package already generates and ships. No new data source was needed; the
+server is just a different transport over data that already existed.

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,70 @@
+# `<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
+
+| Slot | Description |
+| --- | --- |
+| `(default)` | Popover body content. |
+| `title` | Overrides the plain `heading` text with custom markup. |
+| `actions` | Extra header controls (e.g. an icon+label link) rendered between the title and the close button. |
+
+## 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/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