@f-ewald/components 0.4.0 → 0.6.0

package/llms.txt

@@ -104,6 +104,30 @@ Example:
 </script>
 ```
 
+## <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-font`, `--ui-font-size`, `--ui-primary`, `--ui-radius`, `--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,
@@ -144,6 +168,40 @@ Example:
 <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
+Events: none
+CSS custom properties: `--ui-border`, `--ui-font`, `--ui-font-size-sm`, `--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
@@ -188,6 +246,114 @@ Example:
 </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).
+
+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
+Events: `change`
+CSS custom properties: `--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`
+
+Example:
+```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>
+```
+
+## <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>
+```
+
+## <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
@@ -247,7 +413,8 @@ CSS custom properties: none
 
 Example:
 ```html
-<map-point></map-point>
+<map-point color="#0099D8"></map-point>
+<map-point color="#fb8072" size="10" ring-width="2"></map-point>
 ```
 
 ## <percent-bar-chart>
@@ -272,6 +439,72 @@ Example:
 </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-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-font`, `--ui-font-size`, `--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.
@@ -425,6 +658,74 @@ Example:
 </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-success`, `--ui-surface-muted`, `--ui-text`, `--ui-text-muted`
+
+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-primary`, `--ui-success`, `--ui-text-muted`
+
+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.
+
+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
+Events: none
+CSS custom properties: `--ui-border`, `--ui-font`, `--ui-font-size-sm`, `--ui-radius`, `--ui-surface-muted`, `--ui-text`
+
+Example:
+```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>
+```
+
 ## <toast-notification>
 
 Fixed-position stack of dismissible notifications, anchored top-right
@@ -492,7 +793,7 @@ 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`) : number, default 32
+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-primary`
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@f-ewald/components",
   "private": false,
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "A collection of universally usable web components for various tasks.",
   "type": "module",
   "main": "dist/index.js",