# @f-ewald/components

A collection of self-contained Lit web components sharing a Tailwind-inspired
design token system. Every component is individually importable and ships
its own TypeScript types and a checked-in custom-elements.json manifest.

Install: `npm install @f-ewald/components`

Import patterns:
- Whole library: `import "@f-ewald/components";` (registers every component)
- Individual component: `import "@f-ewald/components/<tag-name>.js";` (tree-shakes
  everything else, including d3 for non-chart components)

Theming: components use `var(--ui-*, <fallback>)` custom properties, so they
render correctly with zero external CSS. Override any `--ui-*` property on
`:root` (or an ancestor) to retheme, or import the optional
`@f-ewald/components/tokens.css` stylesheet as a starting point.

## <address-autocomplete>

Form-associated text input with a suggestion dropdown. Works as a
drop-in replacement for a plain `<input name="address">`: consumers keep
reading `new FormData(form).get("address")` and calling `form.reset()`
unchanged.

Supports two suggestion sources:
- **API** (default): fetches from `endpoint`, a Mapbox Geocoding v6-shaped
  forward-geocode URL, debounced as the user types.
- **Local array**: set `suggestions` to a fixed `AddressSuggestion[]` and
  the component filters it client-side instead of making any network
  request. Useful for small/fixed address lists, offline use, or tests.
  Takes priority over `endpoint` whenever it's non-null.

Import: `import "@f-ewald/components/address-autocomplete.js";`

Properties: `value` (attribute `value`) : string, default ""; `placeholder` (attribute `placeholder`) : string, default ""; `required` (attribute `required`) : boolean, default false; `disabled` (attribute `disabled`) : boolean, default false; `types` (attribute `types`) : string, default "address"; `endpoint` (attribute `endpoint`) : string, default "https://api.mapbox.com/search/geocode/v6/forward"; `accessToken` (attribute `access-token`) : string, default ""; `bbox` (attribute `bbox`) : string, default ""; `proximity` (attribute `proximity`) : string, default ""; `debounce` (attribute `debounce`) : number, default 300; `minLength` (attribute `min-length`) : number, default 3; `suggestions` (JS property only) : AddressSuggestion[] | null, default null; `selectedSuggestion` (JS property only) : AddressSuggestion | null, default —
Events: `address-select`
CSS custom properties: `--ui-border`, `--ui-focus-ring`, `--ui-font`, `--ui-font-size-sm`, `--ui-line-height-tight`, `--ui-primary`, `--ui-radius-sm`, `--ui-shadow`, `--ui-surface`, `--ui-surface-muted`, `--ui-text`, `--ui-text-muted`

Example:
```html
<address-autocomplete
  placeholder="Start typing an address…"
  access-token="pk.your-mapbox-token"
></address-autocomplete>
```

## <animate-confetti>

Fullscreen confetti animation overlay, rendered on a fixed-position canvas.
Starts automatically on first render and stops after `duration` ms.

Import: `import "@f-ewald/components/animate-confetti.js";`

Properties: `duration` (attribute `duration`) : number, default 6000
Events: none
CSS custom properties: none

Example:
```html
<animate-confetti duration="6000"></animate-confetti>
```

## <autocomplete-input>

Generic form-associated text input with a suggestion dropdown, for any
"type to filter a list of `{key, value}` options" use case. Works as a
drop-in replacement for a plain `<input>` inside a `<form>`: set `name` on
the element itself and consumers keep reading
`new FormData(form).get(name)` and calling `form.reset()` unchanged — the
submitted value is the picked option's `value`, while `key` is available
via the `option-select` event and the `selectedOption` getter for cases
that need the underlying id rather than the display text.

Supports two suggestion sources:
- **API**: set `endpoint` to a URL that, given a `?<query-param>=<text>`
  query string, responds with a JSON array of `{key, value}` objects.
  Requests are debounced as the user types.
- **Local array**: set `options` to a fixed `AutocompleteOption[]` and the
  component filters it client-side instead of making any network
  request. Useful for small/fixed lists, offline use, or tests. Takes
  priority over `endpoint` whenever it's non-null.

Import: `import "@f-ewald/components/autocomplete-input.js";`

Properties: `value` (attribute `value`) : string, default ""; `placeholder` (attribute `placeholder`) : string, default ""; `required` (attribute `required`) : boolean, default false; `disabled` (attribute `disabled`) : boolean, default false; `endpoint` (attribute `endpoint`) : string, default ""; `queryParam` (attribute `query-param`) : string, default "q"; `debounce` (attribute `debounce`) : number, default 300; `minLength` (attribute `min-length`) : number, default 3; `options` (JS property only) : AutocompleteOption[] | null, default null; `selectedOption` (JS property only) : AutocompleteOption | null, default —
Events: `option-select`
CSS custom properties: `--ui-border`, `--ui-focus-ring`, `--ui-font`, `--ui-font-size-sm`, `--ui-line-height-tight`, `--ui-primary`, `--ui-radius-sm`, `--ui-shadow`, `--ui-surface`, `--ui-surface-muted`, `--ui-text`, `--ui-text-muted`

Example:
```html
<form>
  <autocomplete-input name="language" placeholder="Start typing a language…"></autocomplete-input>
</form>
<script type="module">
  // Local mode: filters client-side, no network request.
  document.querySelector("autocomplete-input").options = [
    { key: "ts", value: "TypeScript" },
    { key: "py", value: "Python" },
  ];

  // API mode: omit `options` and set `endpoint` instead — it's queried as
  // `${endpoint}?${queryParam}=<text>` and must respond with [{key, value}].
</script>
```

## <calendar-entry>

Declarative metadata for one calendar event, consumed by a parent
`calendar-month` or `calendar-year`. Read-only/non-interactive; renders
nothing itself.

Import: `import "@f-ewald/components/calendar-entry.js";`

Properties: `start` (attribute `start`) : string, default ""; `end` (attribute `end`) : string, default ""; `label` (attribute `label`) : string, default ""; `color` (attribute `color`) : StatusPillColor, default "neutral"; `href` (attribute `href`) : string | undefined, default —
Events: none
CSS custom properties: none

Example:
```html
<calendar-entry
  start="2026-07-10"
  end="2026-07-18"
  label="Vacation"
  color="success"
>
  <span slot="title">Vacation</span>
  <span slot="detail">Out of office</span>
  <span slot="detail">Road trip along the California coast with several scenic stops</span>
  <span slot="footer">Return July 19 at 6 PM</span>
</calendar-entry>
```

## <calendar-month>

One month rendered as a top-to-bottom list of days — weekends and today
highlighted, with declarative `calendar-entry` children shown as colored
bars spanning the days they cover. An entry's title uses its first visible
day; every remaining visible day becomes one shared body for wrapped
details and an optional ending footer. Overlapping entries stack into
side-by-side lanes rather than being layered/hidden. Read-only.

Lanes are computed independently per instance, from only the entries
overlapping this month — an entry spanning a month boundary may therefore
land in a different lane index in the adjacent month's `calendar-month`.
This is an accepted v1 limitation: cross-month lane continuity would
require a shared parent (`calendar-year`) to assign lanes globally.

Entry attributes and slotted title/detail text are observed, so a
standalone month re-renders when consumers update declarative metadata.

Import: `import "@f-ewald/components/calendar-month.js";`

Properties: `year` (attribute `year`) : number, default —; `month` (attribute `month`) : number, default 1
Events: none
CSS custom properties: `--ui-border`, `--ui-danger`, `--ui-focus-ring`, `--ui-font`, `--ui-font-size-lg`, `--ui-font-size-sm`, `--ui-font-size-xs`, `--ui-font-weight-bold`, `--ui-font-weight-medium`, `--ui-font-weight-regular`, `--ui-font-weight-semibold`, `--ui-hover-overlay`, `--ui-info`, `--ui-line-height-tight`, `--ui-primary`, `--ui-radius-sm`, `--ui-success`, `--ui-surface`, `--ui-surface-muted`, `--ui-text`, `--ui-text-muted`, `--ui-warning`

Example:
```html
<calendar-month year="2026" month="7">
  <calendar-entry start="2026-07-10" end="2026-07-18" label="Vacation" color="success">
    <span slot="title">Vacation</span>
    <span slot="detail">Out of office</span>
    <span slot="detail">Road trip along the California coast with several scenic stops</span>
    <span slot="footer">Return July 19 at 6 PM</span>
  </calendar-entry>
  <calendar-entry start="2026-07-15" end="2026-07-20" label="Conference" color="warning" href="#conf">
    <span slot="detail">Talks and workshops</span>
    <span slot="footer">Closing keynote · July 20</span>
  </calendar-entry>
</calendar-month>
```

## <calendar-year>

A full year of `calendar-month` blocks, generated from declarative
`calendar-entry` children. Each entry is re-projected into the
`calendar-month` blocks it overlaps as a freshly-created `calendar-entry`
element — the original elements stay slotted here and are never moved,
since a DOM node can only have one parent. Read-only.

Import: `import "@f-ewald/components/calendar-year.js";`

Properties: `year` (attribute `year`) : number, default —
Events: none
CSS custom properties: `--ui-font`

Example:
```html
<calendar-year year="2026">
  <calendar-entry start="2026-01-28" end="2026-02-03" label="Offsite" color="primary" href="#offsite">
    <span slot="detail">New York</span>
    <span slot="detail">Team workshops</span>
    <span slot="footer">Closing dinner Friday</span>
  </calendar-entry>
  <calendar-entry start="2026-03-05" end="2026-03-18" label="Product launch" color="success" href="#launch">
    <span slot="detail">Coordinate the release across engineering, design, support, and marketing.</span>
    <span slot="detail">Monitor adoption and production health throughout the rollout.</span>
    <span slot="footer">Public launch · March 18 at 9 AM</span>
  </calendar-entry>
  <calendar-entry start="2026-07-10" end="2026-07-18" label="Vacation" color="success"></calendar-entry>
</calendar-year>
```

## <chat-message>

One conversation entry in a chat-style activity feed. Tool calls and
"thinking" traces are variants of this component rather than separate
ones — they share the same header, collapse behavior, and body card as a
normal message, just dimmed and collapsible with an always-visible summary.

Import: `import "@f-ewald/components/chat-message.js";`

Properties: `role` (attribute `role`) : ChatMessageRole, default "agent"; `variant` (attribute `variant`) : ChatMessageVariant, default "normal"; `author` (attribute `author`) : string, default ""; `timestamp` (attribute `timestamp`) : string | null, default null; `summary` (attribute `summary`) : string, default ""; `collapsible` (attribute `collapsible`) : boolean, default false; `collapsed` (attribute `collapsed`) : boolean, default false
Events: `toggle`
CSS custom properties: `--ui-border`, `--ui-focus-ring`, `--ui-font`, `--ui-font-mono`, `--ui-font-size`, `--ui-font-size-sm`, `--ui-font-weight-semibold`, `--ui-line-height-normal`, `--ui-primary`, `--ui-radius`, `--ui-radius-sm`, `--ui-surface`, `--ui-text`, `--ui-text-muted`

Example:
```html
<chat-message role="user" author="Freddy" timestamp="2026-07-19T12:00:00Z">
  Write notes.md containing a haiku.
</chat-message>
<chat-message role="agent" variant="tool" collapsible collapsed summary='file_write · {"filename": "notes.md"}'>
  directory: .
  filename: notes.md
</chat-message>
```

## <confirm-dialog>

Reusable confirmation dialog: overlay + centered card with a slotted body,
an optional error line, and Cancel/Confirm actions. Instant `display:none`
→ `display:flex` toggle (no transitions). Fires `confirm`/`cancel`
(bubbling, composed) instead of owning any deletion logic itself —
callers stay in charge of the request.

Import: `import "@f-ewald/components/confirm-dialog.js";`

Properties: `open` (attribute `open`) : boolean, default false; `confirmLabel` (attribute `confirm-label`) : string, default "Delete"; `cancelLabel` (attribute `cancel-label`) : string, default "Cancel"; `danger` (attribute `danger`) : boolean, default true; `busy` (attribute `busy`) : boolean, default false; `error` (attribute `error`) : string | null, default null
Events: `confirm`, `cancel`
CSS custom properties: `--ui-border`, `--ui-danger`, `--ui-danger-hover`, `--ui-focus-ring`, `--ui-font`, `--ui-font-size`, `--ui-font-size-sm`, `--ui-font-weight-medium`, `--ui-line-height-normal`, `--ui-line-height-tight`, `--ui-on-accent`, `--ui-overlay`, `--ui-primary`, `--ui-primary-hover`, `--ui-radius`, `--ui-radius-sm`, `--ui-shadow-lg`, `--ui-surface`, `--ui-text`, `--ui-text-muted`

Example:
```html
<confirm-dialog open confirm-label="Delete" cancel-label="Cancel">
  Are you sure you want to delete this item?
</confirm-dialog>
```

## <copy-link-button>

Small icon button that copies `value` to the clipboard and shows a toast
on success/failure (if a `<toast-notification>` element is present), and
always dispatches a `copy-success`/`copy-error` CustomEvent so consumers
without a toast element can react. Defaults to the current page URL if
`value` is unset.

Import: `import "@f-ewald/components/copy-link-button.js";`

Properties: `value` (attribute `value`) : string, default ""; `label` (attribute `label`) : string, default "Copy link"; `disabled` (attribute `disabled`) : boolean, default false
Events: `copy-success`, `copy-error`
CSS custom properties: `--ui-focus-ring`, `--ui-radius-sm`, `--ui-surface-muted`, `--ui-text`, `--ui-text-muted`

Example:
```html
<copy-link-button value="https://example.com/listing/42" label="Copy listing link"></copy-link-button>
```

## <data-table>

A generic, presentational table shell: renders a `<thead>` from `columns`
and one `<tr>` per entry in `rows`, with each cell's content produced by
`renderCell` (default: plain property lookup on the row object). Knows
nothing about what a "row" means — callers own the data shape entirely.

Optional `rowHref` makes whole rows clickable (navigating via `location.hash`),
without hijacking clicks on nested interactive elements (links/buttons) a
cell's rendered content might contain.

Import: `import "@f-ewald/components/data-table.js";`

Properties: `columns` (JS property only) : DataTableColumn[], default []; `rows` (JS property only) : unknown[], default []; `rowKey` (JS property only) : (row: unknown, index: number) => string | number, default —; `renderCell` (JS property only) : (row: unknown, key: string) => unknown, default —; `rowHref` (JS property only) : ((row: unknown) => string | null) | null, default null; `rowLabel` (JS property only) : ((row: unknown) => string) | null, default null
Events: none
CSS custom properties: `--ui-border`, `--ui-focus-ring`, `--ui-font`, `--ui-font-size-sm`, `--ui-font-weight-semibold`, `--ui-surface-muted`, `--ui-text`, `--ui-text-muted`

Example:
```html
<data-table></data-table>
<script type="module">
  const table = document.querySelector("data-table");
  table.columns = [
    { key: "title", label: "Title" },
    { key: "state", label: "State" },
  ];
  table.rows = [
    { id: "tsk_1", title: "Write onboarding docs", state: "Backlog" },
    { id: "tsk_2", title: "Fix the login bug", state: "Done" },
  ];
  table.rowHref = (row) => `#/tasks/${row.id}`;
</script>
```

## <distance-value>

Inline distance display. Renders miles/feet or km/m, switching units at
sensible thresholds (< 0.25 mi → ft; < 0.5 km → m).

Supply exactly one of `miles` or `km`; the other stays null.
km support is present but reserved for future use.

Import: `import "@f-ewald/components/distance-value.js";`

Properties: `miles` (attribute `miles`) : number | null, default null; `km` (attribute `km`) : number | null, default null
Events: none
CSS custom properties: none

Example:
```html
<distance-value miles="5"></distance-value>
```

## <distribution-chart>

Renders a KDE distribution curve for a named metric with one or more value
markers. The SVG viewBox is kept in sync with the element's pixel width via
ResizeObserver so that font sizes and stroke widths are always in real pixels
regardless of container width.

Pass `fontSize` to control all text size (default 10). Pass a single
`{label:'', value}` for a single-value display or multiple
`{label:'A'|'B'|...}` entries to compare several values.

Import: `import "@f-ewald/components/distribution-chart.js";`

Properties: `metric` (attribute `metric`) : string, default ""; `values` (JS property only) : DistributionValue[], default []; `markerColors` (JS property only) : string[], default ["#4f46e5", "#d97706", "#0d9488", "#e11d48"]; `fontSize` (attribute `font-size`) : number, default 10
Events: none
CSS custom properties: `--ui-border`, `--ui-danger`, `--ui-font`, `--ui-font-size-sm`, `--ui-font-size-xs`, `--ui-primary`, `--ui-radius-sm`, `--ui-surface-muted`, `--ui-text-muted`

Example:
```html
<distribution-chart metric="sqft"></distribution-chart>
<script type="module">
  document.querySelector("distribution-chart").values = [{ label: "", value: 1450 }];
</script>
```

## <dropdown-button>

A primary-styled button with a label and chevron that opens an anchored
menu of actions — essentially `form-select` minus "current value"
semantics: a menu, not a select. Use for a set of mutually exclusive
next-step actions (e.g. a failed task's Retry / Close / Backlog).

Import: `import "@f-ewald/components/dropdown-button.js";`

Properties: `label` (attribute `label`) : string, default ""; `options` (JS property only) : DropdownOption[], default []; `disabled` (attribute `disabled`) : boolean, default false
Events: `select`
CSS custom properties: `--ui-border`, `--ui-focus-ring`, `--ui-font`, `--ui-font-size-sm`, `--ui-font-weight-medium`, `--ui-line-height-tight`, `--ui-on-accent`, `--ui-primary`, `--ui-primary-hover`, `--ui-radius-sm`, `--ui-shadow`, `--ui-surface`, `--ui-surface-muted`, `--ui-text`

Example:
```html
<dropdown-button label="Resolve…"></dropdown-button>
<script type="module">
  const dropdown = document.querySelector("dropdown-button");
  dropdown.options = [
    { value: "retry", label: "Retry" },
    { value: "close", label: "Close" },
    { value: "backlog", label: "Backlog" },
  ];
  dropdown.addEventListener("select", (e) => console.log(e.detail.value));
</script>
```

## <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.

Import: `import "@f-ewald/components/editable-text.js";`

Properties: `value` (attribute `value`) : string, default ""; `multiline` (attribute `multiline`) : boolean, default false; `placeholder` (attribute `placeholder`) : string, default ""; `readonly` (attribute `readonly`) : boolean, default false; `label` (attribute `label`) : string, default ""
Events: `change`
CSS custom properties: `--ui-border`, `--ui-focus-ring`, `--ui-primary`, `--ui-radius-sm`, `--ui-surface`, `--ui-surface-muted`, `--ui-text-muted`

Example:
```html
<editable-text value="Write the quarterly report" label="Title"></editable-text>
<editable-text multiline placeholder="Add a description…" label="Description"></editable-text>
```

## <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%; }`.

Set `searchable` to replace the button trigger with an editable combobox
that filters the predefined options by case-insensitive label infix. Typed
text is only a query: `value` changes exclusively when an actual option is
selected, and an uncommitted query is discarded when the list closes.
Each option may also provide a pre-rendered `icon` and square `iconSize`;
iconless options reserve no leading space.

Import: `import "@f-ewald/components/form-select.js";`

Properties: `options` (JS property only) : SelectOption[], default []; `value` (attribute `value`) : string, default ""; `label` (attribute `label`) : string, default ""; `disabled` (attribute `disabled`) : boolean, default false; `searchable` (attribute `searchable`) : boolean, default false
Events: `change`
CSS custom properties: `--ui-border`, `--ui-focus-ring`, `--ui-font`, `--ui-font-size-sm`, `--ui-font-weight-semibold`, `--ui-line-height-tight`, `--ui-primary`, `--ui-radius-sm`, `--ui-shadow`, `--ui-surface`, `--ui-surface-muted`, `--ui-text`, `--ui-text-muted`

Example:
```html
<form-select label="Task state" searchable></form-select>
<script type="module">
  import { iconArrowPath, iconCheckCircle, iconListBullet } from "@f-ewald/components/icons.js";

  const select = document.querySelector("form-select");
  select.options = [
    { value: "backlog", label: "Backlog", icon: iconListBullet(14), iconSize: 14 },
    { value: "open", label: "Open" },
    { value: "in_progress", label: "In progress", icon: iconArrowPath(16), iconSize: 16 },
    { value: "review", label: "Needs review" },
    { value: "done", label: "Done", icon: iconCheckCircle(16), iconSize: 16 },
  ];
  select.value = "open";
  select.addEventListener("change", (e) => console.log(e.detail.value));
</script>
```

## <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).

Import: `import "@f-ewald/components/frame-box.js";`

Properties: `label` (attribute `label`) : string, default ""
Events: none
CSS custom properties: `--ui-border`, `--ui-font`, `--ui-font-size-xs`, `--ui-font-weight-semibold`, `--ui-radius`, `--ui-surface`, `--ui-text-muted`, `--ui-tracking-wide`

Example:
```html
<frame-box label="Debug">
  Framed content goes here.
</frame-box>
```

## <gallery-item>

Declarative image metadata consumed by a parent `photo-gallery`.

Import: `import "@f-ewald/components/gallery-item.js";`

Properties: `src` (attribute `src`) : string, default ""; `alt` (attribute `alt`) : string, default ""; `caption` (attribute `caption`) : string | undefined, default —; `variants` (JS property only) : GalleryItemVariant[], default —
Events: none
CSS custom properties: none

Example:
```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>
```

## <gallery-item-variant>

Responsive image source metadata for a parent `gallery-item`.

Import: `import "@f-ewald/components/gallery-item-variant.js";`

Properties: `media` (attribute `media`) : string | undefined, default —; `srcset` (attribute `srcset`) : string, default ""
Events: none
CSS custom properties: none

Example:
```html
<gallery-item-variant
  media="(max-width: 640px)"
  srcset="/photos/coast-portrait.jpg"
></gallery-item-variant>
```

## <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.

Import: `import "@f-ewald/components/icon-button.js";`

Properties: `icon` (JS property only) : TemplateResult | null, default null; `label` (attribute `label`) : string, default ""; `disabled` (attribute `disabled`) : boolean, default false
Events: `click`
CSS custom properties: `--ui-focus-ring`, `--ui-radius-sm`, `--ui-surface-muted`, `--ui-text`, `--ui-text-muted`

Example:
```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>
```

## <kbd-hint>

Renders a keyboard shortcut as one boxed keycap per `+`-separated token.
Modifier keys are platform-aware: `Mod` becomes Command on macOS and
Control elsewhere. Keycaps derive their presentation from `currentColor`,
so the hint works inside neutral and accent-colored controls.

Import: `import "@f-ewald/components/kbd-hint.js";`

Properties: `keys` (attribute `keys`) : string, default ""; `platform` (attribute `platform`) : KbdPlatform, default "auto"
Events: none
CSS custom properties: `--ui-font-mono`, `--ui-font-size-xs`, `--ui-line-height-glyph`, `--ui-radius-sm`

Example:
```html
<kbd-hint keys="Mod+K"></kbd-hint>
<kbd-hint keys="Mod+Shift+Enter" platform="mac"></kbd-hint>
```

## <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.

Import: `import "@f-ewald/components/live-timer.js";`

Properties: `since` (attribute `since`) : string | null, default null; `format` (attribute `format`) : DurationFormat, default "seconds"; `prefix` (attribute `prefix`) : string, default ""; `suffix` (attribute `suffix`) : string, default ""
Events: none
CSS custom properties: none

Example:
```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>
```

## <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`.

Import: `import "@f-ewald/components/map-circle.js";`

Properties: `color` (attribute `color`) : string, default "#4f46e5"; `size` (attribute `size`) : number, default 18; `ringWidth` (attribute `ring-width`) : number, default 4; `highlighted` (attribute `highlighted`) : boolean, default false
Events: none
CSS custom properties: `--ui-font`, `--ui-font-weight-bold`, `--ui-line-height-glyph`

Example:
```html
<map-circle color="#6b7280"></map-circle>
<map-circle color="#0099D8" size="14" ring-width="3"></map-circle>
<map-circle color="#1a73e8" size="24" ring-width="5" highlighted>1</map-circle>
```

## <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 })`.

Import: `import "@f-ewald/components/map-pin.js";`

Properties: `color` (attribute `color`) : string, default "#4f46e5"; `size` (attribute `size`) : number, default 32; `highlighted` (attribute `highlighted`) : boolean, default false
Events: none
CSS custom properties: `--ui-font`, `--ui-font-weight-bold`, `--ui-line-height-glyph`

Example:
```html
<map-pin color="#1a73e8" size="30">3</map-pin>
<map-pin color="#22c55e" size="26" highlighted>🏠</map-pin>
```

## <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.

Import: `import "@f-ewald/components/percent-bar-chart.js";`

Properties: `groups` (JS property only) : PercentBarGroup[], default []
Events: none
CSS custom properties: `--ui-font`, `--ui-text-muted`

Example:
```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" },
  ];
</script>
```

## <photo-gallery>

Responsive, accessible image carousel composed from declarative
`gallery-item` children.

Import: `import "@f-ewald/components/photo-gallery.js";`

Properties: `currentIndex` (attribute `current-index`) : number, default 0; `delay` (attribute `delay`) : number, default 0; `showControls` (attribute `show-controls`) : boolean, default true; `showCounter` (attribute `show-counter`) : boolean, default false; `showIndicators` (attribute `show-indicators`) : boolean, default false; `showAutoplayControl` (attribute `show-autoplay-control`) : boolean, default true; `paused` (attribute `paused`) : boolean, default false; `aspectRatio` (attribute `aspect-ratio`) : string, default "16 / 9"; `objectFit` (attribute `object-fit`) : PhotoGalleryObjectFit, default "cover"
Events: `slide-change`
CSS custom properties: `--ui-border`, `--ui-focus-ring`, `--ui-font`, `--ui-font-size`, `--ui-font-size-sm`, `--ui-line-height-tight`, `--ui-on-accent`, `--ui-overlay`, `--ui-primary`, `--ui-radius`, `--ui-radius-sm`, `--ui-surface`, `--ui-surface-muted`, `--ui-text`, `--ui-text-muted`

Example:
```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>
```

## <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.

Import: `import "@f-ewald/components/popover-panel.js";`

Properties: `open` (attribute `open`) : boolean, default false; `heading` (attribute `heading`) : string, default ""; `centered` (attribute `centered`) : boolean, default false
Events: `panel-close`
CSS custom properties: `--ui-border`, `--ui-focus-ring`, `--ui-font`, `--ui-font-size-lg`, `--ui-font-weight-semibold`, `--ui-line-height-tight`, `--ui-overlay`, `--ui-radius`, `--ui-radius-sm`, `--ui-shadow-lg`, `--ui-surface`, `--ui-surface-muted`, `--ui-text`, `--ui-text-muted`

Example:
```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>
```

## <price-history-chart>

D3-powered SVG line chart for property price history.

Uses scaleTime (X) + scaleLinear (Y) from d3-scale and line/area path
generators from d3-shape. Adapts to container width via ResizeObserver.

Import: `import "@f-ewald/components/price-history-chart.js";`

Properties: `history` (attribute `history`) : PricePoint[], default []; `yLabels` (attribute `y-labels`) : "auto" | "always" | "never", default "auto"; `maxXLabels` (attribute `max-x-labels`) : number, default 3
Events: none
CSS custom properties: `--ui-border`, `--ui-font`, `--ui-on-accent`, `--ui-primary`, `--ui-text-muted`, `--ui-tooltip`

Example:
```html
<price-history-chart></price-history-chart>
<script type="module">
  document.querySelector("price-history-chart").history = [
    { date: "2023-01-01", price: 620000, eventType: "Listed" },
    { date: "2024-02-01", price: 680000, eventType: "Sold" },
  ];
</script>
```

## <radio-cards>

Single-select group of full-width cards, each with a label and optional
description — for a handful of meaningfully different choices where the
description matters. For many short, same-shaped options (a color swatch,
a basemap style), use `radio-pills` instead. Wraps native radio inputs for
keyboard/a11y and fires `change` rather than relying on form submission.

Import: `import "@f-ewald/components/radio-cards.js";`

Properties: `options` (JS property only) : RadioCardOption[], default []; `value` (attribute `value`) : string, default ""; `disabled` (attribute `disabled`) : boolean, default false
Events: `change`
CSS custom properties: `--ui-border`, `--ui-focus-ring`, `--ui-font`, `--ui-font-size-sm`, `--ui-font-weight-regular`, `--ui-font-weight-semibold`, `--ui-primary`, `--ui-radius-sm`, `--ui-surface-muted`, `--ui-text`, `--ui-text-muted`

Example:
```html
<radio-cards></radio-cards>
<script type="module">
  const el = document.querySelector("radio-cards");
  el.options = [
    { value: "simple", label: "Simple", description: "Quick-ranking view" },
    { value: "detailed", label: "Detailed", description: "Every section and layer" },
  ];
  el.value = "simple";
  el.addEventListener("change", (e) => console.log(e.detail.value));
</script>
```

## <radio-pills>

Single-select group of compact pill-shaped options — for many short,
same-shaped choices (a basemap style, a unit toggle). For a handful of
choices where a description matters, use `radio-cards` instead. Wraps
native radio inputs for keyboard/a11y and fires `change` rather than
relying on form submission.

Import: `import "@f-ewald/components/radio-pills.js";`

Properties: `options` (JS property only) : RadioPillOption[], default []; `value` (attribute `value`) : string, default ""; `disabled` (attribute `disabled`) : boolean, default false
Events: `change`
CSS custom properties: `--ui-border`, `--ui-focus-ring`, `--ui-font`, `--ui-font-size-sm`, `--ui-line-height-tight`, `--ui-primary`, `--ui-surface-muted`, `--ui-text`

Example:
```html
<radio-pills></radio-pills>
<script type="module">
  const el = document.querySelector("radio-pills");
  el.options = [
    { value: "light", label: "Light" },
    { value: "streets", label: "Streets" },
  ];
  el.value = "light";
  el.addEventListener("change", (e) => console.log(e.detail.value));
</script>
```

## <relative-time>

Inline relative-time display (e.g. "3 hours ago"). Accepts either a
standard ISO 8601 string or a SQLite `datetime('now')` string
("YYYY-MM-DD HH:MM:SS", UTC, no zone marker) via `datetime`. Shows the
full date/time in the viewer's local timezone as a hover tooltip, and
re-renders on an interval so the text stays current while visible.

Import: `import "@f-ewald/components/relative-time.js";`

Properties: `datetime` (attribute `datetime`) : string | null, default null
Events: none
CSS custom properties: none

Example:
```html
<relative-time datetime="2026-07-17T07:00:00Z"></relative-time>
```

## <reveal-button>

Button that reveals hidden slotted content when clicked.

Import: `import "@f-ewald/components/reveal-button.js";`

Properties: `label` (attribute `label`) : string, default "Reveal hidden content"; `disabled` (attribute `disabled`) : boolean, default false
Events: none
CSS custom properties: `--ui-focus-ring`, `--ui-font`, `--ui-font-size-sm`, `--ui-font-weight-medium`, `--ui-line-height-tight`, `--ui-on-accent`, `--ui-primary`, `--ui-primary-hover`, `--ui-radius-sm`

Example:
```html
<reveal-button label="Show the secret">
  Surprise! This content was hidden.
</reveal-button>
```

## <roman-numeral>

Converts an integer to a roman numeral inline.

Import: `import "@f-ewald/components/roman-numeral.js";`

Properties: `value` (attribute `value`) : number | undefined, default —
Events: none
CSS custom properties: none

Example:
```html
<roman-numeral value="2004"></roman-numeral>
```

## <slide-panel>

Generic sliding panel shell. Handles positioning, open/close animation,
header chrome, and a close button. Body content is provided via the
default slot; the consumer controls its own padding and overflow.

Desktop: fixed right-side panel that slides from the right.
Mobile (≤48rem): bottom-sheet drawer (60vh) — reserved for future use.

Import: `import "@f-ewald/components/slide-panel.js";`

Properties: `open` (attribute `open`) : boolean, default false; `heading` (attribute `heading`) : string, default ""
Events: `panel-close`
CSS custom properties: `--ui-border`, `--ui-focus-ring`, `--ui-font`, `--ui-font-size-lg`, `--ui-font-weight-semibold`, `--ui-line-height-tight`, `--ui-radius`, `--ui-radius-sm`, `--ui-shadow-lg`, `--ui-surface`, `--ui-surface-muted`, `--ui-text`, `--ui-text-muted`

Example:
```html
<slide-panel open heading="Property details">
  Panel body content goes here.
</slide-panel>
```

## <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%".

Import: `import "@f-ewald/components/stat-meter.js";`

Properties: `label` (attribute `label`) : string, default ""; `percent` (attribute `percent`) : number | null, default null; `color` (attribute `color`) : string, default ""
Events: none
CSS custom properties: `--ui-font`, `--ui-font-size-sm`, `--ui-font-weight-medium`, `--ui-font-weight-semibold`, `--ui-success`, `--ui-surface-muted`, `--ui-text`, `--ui-text-muted`, `--ui-tracking-wide`

Example:
```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>
```

## <status-pill>

Small colored status pill, optionally with a spinning icon — for task/run
states ("Open", "Blocked", "Done") and live-activity indicators ("Running").

Import: `import "@f-ewald/components/status-pill.js";`

Properties: `label` (attribute `label`) : string, default ""; `color` (attribute `color`) : StatusPillColor, default "neutral"; `spinner` (attribute `spinner`) : boolean, default false
Events: none
CSS custom properties: `--ui-danger`, `--ui-font`, `--ui-font-size-sm`, `--ui-font-weight-medium`, `--ui-info`, `--ui-primary`, `--ui-success`, `--ui-text-muted`, `--ui-warning`

Example:
```html
<status-pill label="Running" color="primary" spinner></status-pill>
<status-pill label="Blocked" color="danger"></status-pill>
```

## <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.

Optional `fileIcon` prefixes each tile with a decorative Heroicons
"document" glyph, for grids whose items represent files — the icon never
carries its own accessible name since the rendered tile content (e.g. a
filename) already identifies the item. Off by default, so it consumes no
layout space or markup for grids of non-file items.

Import: `import "@f-ewald/components/tile-grid.js";`

Properties: `items` (JS property only) : unknown[], default []; `itemKey` (JS property only) : (item: unknown, index: number) => string | number, default —; `renderTile` (JS property only) : (item: unknown) => unknown, default —; `itemHref` (JS property only) : ((item: unknown) => string | null) | null, default null; `fileIcon` (attribute `file-icon`) : boolean, default false
Events: none
CSS custom properties: `--ui-border`, `--ui-focus-ring`, `--ui-font`, `--ui-font-size-sm`, `--ui-radius`, `--ui-surface-muted`, `--ui-text`, `--ui-text-muted`

Example:
```html
<tile-grid file-icon></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>
```

## <toast-notification>

Fixed-position stack of dismissible notifications, anchored top-right
(top-full-width on mobile). Not wired to any app state yet — callers add
toasts imperatively via the `show()` method on a live element reference,
e.g. `document.querySelector('toast-notification')?.show('Offline', { variant: 'error' })`,
or via the `notifySuccess`/`notifyError`/`notifyInfo` module-level helpers
exported from this file. Each toast auto-dismisses after `duration` ms and
can also be dismissed via its ✕ button. Appears/disappears instantly — no
slide/fade transitions.

Import: `import "@f-ewald/components/toast-notification.js";`

Properties: none
Events: none
CSS custom properties: `--ui-danger`, `--ui-focus-ring`, `--ui-font`, `--ui-font-size`, `--ui-hover-overlay`, `--ui-info`, `--ui-line-height-glyph`, `--ui-line-height-normal`, `--ui-on-accent`, `--ui-radius`, `--ui-radius-sm`, `--ui-shadow-lg`, `--ui-success`, `--ui-text`

Example:
```html
<toast-notification></toast-notification>
<script type="module">
  import { notifySuccess } from "@f-ewald/components/toast-notification.js";
  notifySuccess("Saved!");
</script>
```

## <ui-button>

Button (or link styled as one) with an optional leading icon, in three
visual weights. Set `href` to render an `<a>` instead of a `<button>` —
same styling either way — for cross-page navigation that should look like
an action button; a disabled/busy link stays a real `<a>` with
`aria-disabled` + `pointer-events: none` rather than losing its href.
Put the icon in the `icon` slot and the label in the default slot.

Form-associated (`type="submit"`/`"reset"`): the actual `<button>` lives in
this element's shadow root, which native HTML form association does not
cross into from an ancestor light-DOM `<form>`. `type="submit"`/`"reset"`
is instead wired through `ElementInternals.form` — the same mechanism
`address-autocomplete` uses to associate with an ancestor form.

Import: `import "@f-ewald/components/ui-button.js";`

Properties: `variant` (attribute `variant`) : ButtonVariant, default "primary"; `href` (attribute `href`) : string | null, default null; `type` (attribute `type`) : "button" | "submit" | "reset", default "button"; `disabled` (attribute `disabled`) : boolean, default false; `busy` (attribute `busy`) : boolean, default false
Events: none
CSS custom properties: `--ui-border`, `--ui-danger`, `--ui-danger-hover`, `--ui-focus-ring`, `--ui-font`, `--ui-font-size-sm`, `--ui-font-weight-medium`, `--ui-line-height-tight`, `--ui-on-accent`, `--ui-primary`, `--ui-primary-hover`, `--ui-radius-sm`, `--ui-text`, `--ui-text-muted`

Example:
```html
<ui-button variant="primary">
  <span slot="icon">...</span>
  New property
</ui-button>
<ui-button variant="danger">Delete</ui-button>
<ui-button variant="secondary" href="/properties?edit=42">Edit</ui-button>
```

## <user-avatar>

Circular avatar. Shows `src` when it loads successfully; falls back to the
first letter of `name` (uppercased) if `src` is unset or fails to load
(e.g. an expired OAuth profile-photo URL); falls back further to a generic
person icon if `name` is also unset. A broken image never leaves a blank
circle.

Import: `import "@f-ewald/components/user-avatar.js";`

Properties: `src` (attribute `src`) : string | null, default null; `name` (attribute `name`) : string | null, default null; `size` (attribute `size`) : string | number, default 32
Events: none
CSS custom properties: `--ui-font`, `--ui-font-weight-semibold`, `--ui-on-accent`, `--ui-primary`

Example:
```html
<user-avatar src="https://example.com/photo.jpg" name="Freddy" size="40"></user-avatar>
```

## <weight-bar-chart>

Sorted horizontal bar chart of labeled weights (normalized fractions
summing to ~1). Bars sort descending — the order IS the priority ranking.
Widths scale relative to the largest weight (which fills its track); the
percent labels carry the absolute values. Rows are keyed by item id
(repeat directive) so a re-render with new weights moves the existing
rows; bar widths animate via CSS, re-sorting is instant.

Import: `import "@f-ewald/components/weight-bar-chart.js";`

Properties: `items` (JS property only) : WeightBarItem[], default []
Events: none
CSS custom properties: `--ui-font`, `--ui-font-size-sm`, `--ui-primary`, `--ui-surface-muted`, `--ui-text`, `--ui-text-muted`

Example:
```html
<weight-bar-chart></weight-bar-chart>
<script type="module">
  document.querySelector("weight-bar-chart").items = [
    { id: "price", label: "Price", value: 0.4 },
    { id: "schools", label: "Schools", value: 0.35 },
    { id: "commute", label: "Commute", value: 0.25 },
  ];
</script>
```