@f-ewald/components 1.2.1 → 1.3.0

package/docs/layouts/list-only.md

@@ -0,0 +1,50 @@
+# List-only page
+
+A full-width list/table view: a collapsible sidebar, a top bar, an action row,
+the list, and pagination. The default internal-dashboard "index" screen.
+
+**When to use:** browsing or managing a collection of records where a row does
+not need a side-by-side detail pane (rows link to their own detail page). If you
+want an inline detail pane, use the list + detail template instead.
+
+## Shell slots
+
+- `sidebar` → `app-sidebar` with the app's navigation.
+- `topbar` → `page-header` with the collection title (and optional actions).
+- default (`main`) → an `action-bar` above a `data-table`.
+- `footer` → `pagination-nav`.
+
+## Markup
+
+```html
+<app-shell style="height: 100vh">
+  <app-sidebar slot="sidebar"><!-- nav items --></app-sidebar>
+
+  <page-header slot="topbar" heading="Members"></page-header>
+
+  <div>
+    <action-bar>
+      <autocomplete-input slot="start" placeholder="Search…"></autocomplete-input>
+      <ui-button slot="end" variant="secondary">Filter</ui-button>
+      <ui-button slot="end" variant="primary">Create</ui-button>
+    </action-bar>
+    <data-table style="margin-top: 1rem; display: block;"></data-table>
+  </div>
+
+  <pagination-nav slot="footer" current-page="1" total-pages="6"></pagination-nav>
+</app-shell>
+```
+
+## Notes
+
+- Give `app-shell` a height (e.g. `100vh`) so the sidebar and main can size and
+  scroll independently.
+- `pagination-nav` is controlled: set `current-page`/`total-pages` and re-render
+  in response to its `page-change` event, the same way `data-table` leaves the
+  rows to you.
+- Put search and filters in the action bar's `start` slot and record actions
+  (create, delete) in `end`.
+
+**Live demo:** `demo/layouts/list-only.html`
+
+**Components:** app-shell, app-sidebar, page-header, action-bar, data-table, pagination-nav

package/docs/layouts/record-detail.md

@@ -0,0 +1,88 @@
+# Record + metadata rail page
+
+A record's read view with the main content on the left and a persistent
+metadata/detail rail on the right — the Jira/Linear issue layout (description +
+status, assignee, labels, priority).
+
+**When to use:** viewing one rich record whose metadata (status, owner, labels,
+progress) should stay visible alongside the content, and where that metadata is
+mostly a static display of components rather than a transient selection.
+
+## Layout
+
+The rail is a **two-column CSS grid inside the `main` slot**, not the shell's
+`detail` slot:
+
+- `sidebar` → `app-sidebar`.
+- `topbar` → `page-header` with a linked `breadcrumb` and record `actions`
+  (primary Edit rightmost).
+- default (`main`) → a grid: the body (description, activity) on the left, an
+  `<aside>` metadata rail on the right. It collapses to one column at the shared
+  48rem breakpoint so the metadata **stacks below** the content on narrow
+  screens instead of hiding.
+
+The metadata rail is composed from existing components: `frame-box` to group,
+`status-pill` for status/priority/labels, `user-avatar` for people, and
+`stat-meter` for progress. Activity uses `chat-message`.
+
+## Markup
+
+```html
+<app-shell style="height: 100vh">
+  <app-sidebar slot="sidebar"><!-- nav items --></app-sidebar>
+
+  <page-header slot="topbar" heading="Fix flaky login redirect">
+    <nav slot="breadcrumb" aria-label="Breadcrumb"><a href="/board">Board</a> / PROJ-142</nav>
+    <ui-button slot="actions" variant="primary">Edit</ui-button>
+  </page-header>
+
+  <div class="ticket">
+    <div class="ticket-body">
+      <h3>Description</h3>
+      <p>…</p>
+      <frame-box label="Activity">
+        <chat-message role="user" author="Ada Lovelace">…</chat-message>
+      </frame-box>
+    </div>
+
+    <aside class="ticket-meta" aria-label="Issue details">
+      <frame-box label="Details">
+        <dl class="meta">
+          <div class="meta-row"><dt>Status</dt><dd><status-pill label="In Progress" color="info"></status-pill></dd></div>
+          <div class="meta-row"><dt>Assignee</dt><dd><user-avatar name="Ada Lovelace" size="24"></user-avatar> Ada Lovelace</dd></div>
+          <div class="meta-row"><dt>Priority</dt><dd><status-pill label="High" color="warning"></status-pill></dd></div>
+        </dl>
+        <stat-meter label="Progress" percent="60"></stat-meter>
+      </frame-box>
+    </aside>
+  </div>
+</app-shell>
+```
+
+```css
+.ticket {
+  display: grid;
+  grid-template-columns: minmax(0, 1fr) 18rem;
+  gap: 1.5rem;
+  align-items: start;
+}
+@media (max-width: 48rem) {
+  .ticket { grid-template-columns: minmax(0, 1fr); }
+}
+```
+
+## Notes
+
+- Use the two-column grid inside `main` (not the shell `detail` slot) when the
+  metadata is **persistent** and should stack on mobile. The shell's `detail`
+  slot is for a **transient master-detail selection** (list + selected item): on
+  mobile it becomes a dismissible overlay, which hides persistent record
+  metadata. Reach for it in the list + detail template, not here.
+- Editable metadata is a drop-in swap: replace a `status-pill` with a
+  `form-select`, or the label pills with a `multi-select`.
+- Keep the record actions in the header (primary Edit); there is no
+  `form-actions` footer on a read view.
+
+**Live demo:** `demo/layouts/record-detail.html`
+
+**Components:** app-shell, app-sidebar, page-header, frame-box, status-pill, user-avatar, stat-meter, chat-message

package/docs/mcp-evaluation.md

@@ -36,3 +36,24 @@ 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.
+
+## Update (layout system): added `list_layouts` / `get_layout`
+
+The dashboard layout system introduced cross-component knowledge — which
+components compose into which page templates, the slot recipes, and the
+button-placement rule — that no single component's generated doc captures. Two
+thin tools, `list_layouts` and `get_layout(name)`, expose it.
+
+This stays true to the server's founding principle: **no new data source.** The
+tools read the authored `docs/layouts/*.md` recipes (which also ship in the npm
+package and render on the docs site), not a bespoke structure invented for MCP.
+The individual layout components still flow through `list_components` /
+`get_component_docs` automatically.
+
+**Is MCP the right fit here?** It's a reasonable, not slam-dunk, fit. The
+justification is discoverability and targeted retrieval — an agent can list the
+templates and pull just the one it needs, rather than loading everything. If the
+guidance stayed tiny, `llms.txt` alone could carry it; the tools earn their keep
+by making the "preferred layout" explicitly enumerable and by matching the
+per-component tools consumers already call. The cost to watch is keeping the
+recipes, the `demo/layouts/` demos, and the tool output in sync.

package/docs/page-header.md

@@ -0,0 +1,47 @@
+# `<page-header>`
+
+Page title block for the top of a dashboard view: an optional breadcrumb
+trail, the page heading, and a right-aligned cluster of page-level actions.
+It only lays these out — the breadcrumb links and action buttons are entirely
+the consumer's, so it stays framework- and router-agnostic.
+
+## Install
+
+```js
+import "@f-ewald/components/page-header.js";
+```
+
+## Usage
+
+```html
+<page-header heading="Team members">
+  <nav slot="breadcrumb" aria-label="Breadcrumb">Home / Settings / Members</nav>
+  <ui-button slot="actions" variant="primary">Invite</ui-button>
+</page-header>
+```
+
+## Attributes / properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `heading` | `heading` | `string` | `""` | The page heading text. |
+
+## Events
+
+_None._
+
+## Slots
+
+_None._
+
+## CSS custom properties
+
+| Custom property |
+| --- |
+| `--ui-font` |
+| `--ui-font-size-lg` |
+| `--ui-font-size-sm` |
+| `--ui-font-weight-semibold` |
+| `--ui-line-height-tight` |
+| `--ui-text` |
+| `--ui-text-muted` |

package/docs/pagination-nav.md

@@ -0,0 +1,54 @@
+# `<pagination-nav>`
+
+Minimal, controlled pager for list/table views: a previous/next control pair
+around a "Page N of M" status. It owns no data — the consumer sets
+`current-page` / `total-pages` and moves the page in response to the
+`page-change` event (typically alongside its own data fetch), exactly like
+`data-table` leaves the row data to the caller.
+
+Previous is disabled on the first page and next on the last; neither fires an
+event when there is nowhere to go.
+
+## Install
+
+```js
+import "@f-ewald/components/pagination-nav.js";
+```
+
+## Usage
+
+```html
+<pagination-nav current-page="1" total-pages="5"></pagination-nav>
+```
+
+## Attributes / properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `currentPage` | `current-page` | `number` | `1` | The 1-based current page. |
+| `totalPages` | `total-pages` | `number` | `1` | The total number of pages (minimum 1). |
+
+## Events
+
+| Event | Description |
+| --- | --- |
+| `page-change` | The user picked a new page (`detail: { page }`). |
+
+## Slots
+
+_None._
+
+## CSS custom properties
+
+| Custom property |
+| --- |
+| `--ui-border` |
+| `--ui-focus-ring` |
+| `--ui-font` |
+| `--ui-font-size-sm` |
+| `--ui-font-weight-medium` |
+| `--ui-line-height-tight` |
+| `--ui-radius-sm` |
+| `--ui-surface-muted` |
+| `--ui-text` |
+| `--ui-text-muted` |

package/docs/timeline-container.md

@@ -0,0 +1,44 @@
+# `<timeline-container>`
+
+Vertical timeline: a single connecting line runs down the left edge and each
+slotted `timeline-entry` places a dot on it. This is a thin layout and
+semantics wrapper — the entries draw the line segments and dots themselves,
+so the container adds no gap between them (a gap would break the line).
+Exposed to assistive technology as a list of events.
+
+## Install
+
+```js
+import "@f-ewald/components/timeline-container.js";
+```
+
+## Usage
+
+```html
+<timeline-container>
+  <timeline-entry datetime="2026-07-23T09:00:00Z">
+    <span slot="headline">Deployment started</span>
+    Release v1.4.0 is rolling out.
+  </timeline-entry>
+  <timeline-entry datetime="2026-07-23T08:45:00Z">
+    <span slot="headline">Review approved</span>
+    <status-pill label="In Review" color="info"></status-pill>
+  </timeline-entry>
+</timeline-container>
+```
+
+## Attributes / properties
+
+_None._
+
+## Events
+
+_None._
+
+## Slots
+
+_None._
+
+## CSS custom properties
+
+_None._

package/docs/timeline-entry.md

@@ -0,0 +1,52 @@
+# `<timeline-entry>`
+
+One event on a `timeline-container`: a dot on the vertical line, an optional
+headline, a relative timestamp ("3 hours ago"), and freely nested content.
+The connecting line is drawn here — its segment above the dot is hidden on
+the first entry and the segment below is hidden on the last, so the line caps
+exactly at the first and last dots. Only meaningful inside a
+`timeline-container`; demonstrated through it.
+
+## Install
+
+```js
+import "@f-ewald/components/timeline-entry.js";
+```
+
+## Usage
+
+```html
+<timeline-entry datetime="2026-07-23T09:00:00Z">
+  <span slot="headline">Deployment started</span>
+  Release v1.4.0 is rolling out to production.
+</timeline-entry>
+```
+
+## Attributes / properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `datetime` | `datetime` | `string | null` | `null` | ISO 8601 or SQLite datetime string, rendered as a relative time. |
+
+## Events
+
+_None._
+
+## Slots
+
+_None._
+
+## CSS custom properties
+
+| Custom property |
+| --- |
+| `--ui-border` |
+| `--ui-font` |
+| `--ui-font-size` |
+| `--ui-font-size-sm` |
+| `--ui-font-weight-semibold` |
+| `--ui-line-height-normal` |
+| `--ui-line-height-tight` |
+| `--ui-primary` |
+| `--ui-text` |
+| `--ui-text-muted` |

package/llms.txt

@@ -16,6 +16,31 @@ 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.
 
+## <action-bar>
+
+Toolbar that sits directly above a list or table: a left cluster for
+search and filters and a right cluster for record actions (create, delete,
+bulk actions). It's a presentational layout container only — drop any
+controls (`autocomplete-input`, `multi-select`, `ui-button`, …) into the
+`start` and `end` slots; the bar owns none of their behavior and adds no
+search field of its own. The two clusters wrap onto separate rows when the
+bar is too narrow.
+
+Import: `import "@f-ewald/components/action-bar.js";`
+
+Properties: none
+Events: none
+CSS custom properties: none
+
+Example:
+```html
+<action-bar>
+  <autocomplete-input slot="start" placeholder="Search…"></autocomplete-input>
+  <ui-button slot="end" variant="secondary">Delete</ui-button>
+  <ui-button slot="end" variant="primary">Create</ui-button>
+</action-bar>
+```
+
 ## <address-autocomplete>
 
 Form-associated text input with a suggestion dropdown. Works as a
@@ -61,6 +86,89 @@ Example:
 <animate-confetti duration="6000"></animate-confetti>
 ```
 
+## <app-shell>
+
+The dashboard page shell: a slot-based CSS-grid backbone that arranges a
+full-height sidebar, a top bar, the main content, an optional right-hand
+detail column, and an optional footer. It owns the responsive behavior so
+consumers don't re-implement it — above the shared 48rem breakpoint the
+sidebar collapses to an icon rail and the detail region is an inline column;
+at or below it the sidebar becomes an off-canvas drawer and the detail region
+an overlay, both dismissed by a scrim or Escape.
+
+Widths are tunable per instance via `--component-sidebar-width` (16rem),
+`--component-sidebar-rail-width` (3.5rem), and `--component-topbar-height`
+(3rem); the detail column reuses the 20rem/25rem panel widths. The main
+content area is white by default — override it with
+`--component-main-background`. Give the shell a height (e.g. `height: 100vh`)
+so the sidebar and main can size and scroll.
+
+The built-in top-bar button toggles the sidebar, and so does pressing `[`
+anywhere on the page (ignored while typing in a text field or with a
+modifier held). Hovering or keyboard-focusing the toggle reveals a tooltip
+naming the action and its `[` shortcut — the shortcut is not shown as
+permanent chrome.
+
+Import: `import "@f-ewald/components/app-shell.js";`
+
+Properties: `sidebarCollapsed` (attribute `sidebar-collapsed`) : boolean, default false; `detailOpen` (attribute `detail-open`) : boolean, default false; `detailWidth` (attribute `detail-width`) : "compact" | "comfortable", default "compact"
+Events: `sidebar-toggle`, `detail-close`
+CSS custom properties: `--ui-border`, `--ui-focus-ring`, `--ui-font-size-sm`, `--ui-line-height-tight`, `--ui-on-accent`, `--ui-overlay`, `--ui-radius-sm`, `--ui-shadow`, `--ui-shadow-lg`, `--ui-surface`, `--ui-surface-muted`, `--ui-text-muted`, `--ui-tooltip`
+
+Example:
+```html
+<app-shell detail-open style="height: 100vh">
+  <app-sidebar slot="sidebar">
+    <a href="/dashboard" aria-current="page" aria-label="Dashboard">
+      <!-- icon --><span style="display: var(--app-sidebar-label, inline)">Dashboard</span>
+    </a>
+  </app-sidebar>
+  <page-header slot="topbar" heading="Members"></page-header>
+  <action-bar>
+    <autocomplete-input slot="start" placeholder="Search…"></autocomplete-input>
+    <ui-button slot="end" variant="primary">Create</ui-button>
+  </action-bar>
+  <data-table></data-table>
+  <div slot="detail">Selected record…</div>
+  <pagination-nav slot="footer" total-pages="5"></pagination-nav>
+</app-shell>
+```
+
+## <app-sidebar>
+
+Collapsible navigation sidebar for the `app-shell` sidebar slot. It is
+deliberately presentational and router-agnostic: the consumer supplies the
+nav items as plain `<a>`/`<button>` elements (each an icon followed by a
+label), optional `<p>` group headings, and marks the active item with
+`aria-current="page"`. The sidebar styles them, tracks hover/active/focus,
+and — in collapsed "rail" mode — centers the icons and hides the labels.
+
+Rail mode is driven by the `collapsed` attribute (the parent `app-shell`
+toggles it). Labels are hidden by the inherited `--app-sidebar-label` custom
+property, so each label element should read it, e.g.
+`<span style="display: var(--app-sidebar-label, inline)">Reports</span>`;
+keep an `aria-label` on the item so its accessible name survives collapse.
+The sidebar fills the width and height of its container — `app-shell` owns
+the actual rail/expanded width.
+
+Import: `import "@f-ewald/components/app-sidebar.js";`
+
+Properties: `collapsed` (attribute `collapsed`) : boolean, default false
+Events: none
+CSS custom properties: `--ui-border`, `--ui-focus-ring`, `--ui-font`, `--ui-font-size-sm`, `--ui-font-size-xs`, `--ui-font-weight-medium`, `--ui-font-weight-semibold`, `--ui-line-height-tight`, `--ui-primary`, `--ui-radius-sm`, `--ui-surface`, `--ui-surface-muted`, `--ui-text`, `--ui-text-muted`, `--ui-tracking-wide`
+
+Example:
+```html
+<app-sidebar>
+  <a href="/dashboard" aria-current="page" aria-label="Dashboard">
+    <!-- icon --><span style="display: var(--app-sidebar-label, inline)">Dashboard</span>
+  </a>
+  <a href="/members" aria-label="Members">
+    <!-- icon --><span style="display: var(--app-sidebar-label, inline)">Members</span>
+  </a>
+</app-sidebar>
+```
+
 ## <autocomplete-input>
 
 Generic form-associated text input with a suggestion dropdown, for any
@@ -390,6 +498,33 @@ Example:
 <editable-text multiline placeholder="Add a description…" label="Description"></editable-text>
 ```
 
+## <form-actions>
+
+Form footer button bar with a fixed action order for internal apps: the
+primary (submit) button is always rightmost, the secondary (cancel) button
+sits to its immediate left, and an optional tertiary/destructive action is
+pinned to the far left. The order is enforced by the component regardless of
+the source order the buttons are authored in, so every form in a product
+reads the same way.
+
+Purely presentational: it lays out whatever controls (usually `ui-button`)
+are slotted and never intercepts their clicks, `type="submit"`, or events.
+
+Import: `import "@f-ewald/components/form-actions.js";`
+
+Properties: none
+Events: none
+CSS custom properties: none
+
+Example:
+```html
+<form-actions>
+  <ui-button slot="start" variant="danger">Delete</ui-button>
+  <ui-button slot="secondary" variant="secondary">Cancel</ui-button>
+  <ui-button slot="primary" type="submit" variant="primary">Save</ui-button>
+</form-actions>
+```
+
 ## <form-select>
 
 A styled dropdown select: a trigger button showing the current option's
@@ -780,6 +915,49 @@ Example:
 </script>
 ```
 
+## <page-header>
+
+Page title block for the top of a dashboard view: an optional breadcrumb
+trail, the page heading, and a right-aligned cluster of page-level actions.
+It only lays these out — the breadcrumb links and action buttons are entirely
+the consumer's, so it stays framework- and router-agnostic.
+
+Import: `import "@f-ewald/components/page-header.js";`
+
+Properties: `heading` (attribute `heading`) : string, default ""
+Events: none
+CSS custom properties: `--ui-font`, `--ui-font-size-lg`, `--ui-font-size-sm`, `--ui-font-weight-semibold`, `--ui-line-height-tight`, `--ui-text`, `--ui-text-muted`
+
+Example:
+```html
+<page-header heading="Team members">
+  <nav slot="breadcrumb" aria-label="Breadcrumb">Home / Settings / Members</nav>
+  <ui-button slot="actions" variant="primary">Invite</ui-button>
+</page-header>
+```
+
+## <pagination-nav>
+
+Minimal, controlled pager for list/table views: a previous/next control pair
+around a "Page N of M" status. It owns no data — the consumer sets
+`current-page` / `total-pages` and moves the page in response to the
+`page-change` event (typically alongside its own data fetch), exactly like
+`data-table` leaves the row data to the caller.
+
+Previous is disabled on the first page and next on the last; neither fires an
+event when there is nowhere to go.
+
+Import: `import "@f-ewald/components/pagination-nav.js";`
+
+Properties: `currentPage` (attribute `current-page`) : number, default 1; `totalPages` (attribute `total-pages`) : number, default 1
+Events: `page-change`
+CSS custom properties: `--ui-border`, `--ui-focus-ring`, `--ui-font`, `--ui-font-size-sm`, `--ui-font-weight-medium`, `--ui-line-height-tight`, `--ui-radius-sm`, `--ui-surface-muted`, `--ui-text`, `--ui-text-muted`
+
+Example:
+```html
+<pagination-nav current-page="1" total-pages="5"></pagination-nav>
+```
+
 ## <percent-bar-chart>
 
 Horizontal bar chart for labeled percentage rows, using D3's linear scale.
@@ -1095,6 +1273,57 @@ Example:
 </script>
 ```
 
+## <timeline-container>
+
+Vertical timeline: a single connecting line runs down the left edge and each
+slotted `timeline-entry` places a dot on it. This is a thin layout and
+semantics wrapper — the entries draw the line segments and dots themselves,
+so the container adds no gap between them (a gap would break the line).
+Exposed to assistive technology as a list of events.
+
+Import: `import "@f-ewald/components/timeline-container.js";`
+
+Properties: none
+Events: none
+CSS custom properties: none
+
+Example:
+```html
+<timeline-container>
+  <timeline-entry datetime="2026-07-23T09:00:00Z">
+    <span slot="headline">Deployment started</span>
+    Release v1.4.0 is rolling out.
+  </timeline-entry>
+  <timeline-entry datetime="2026-07-23T08:45:00Z">
+    <span slot="headline">Review approved</span>
+    <status-pill label="In Review" color="info"></status-pill>
+  </timeline-entry>
+</timeline-container>
+```
+
+## <timeline-entry>
+
+One event on a `timeline-container`: a dot on the vertical line, an optional
+headline, a relative timestamp ("3 hours ago"), and freely nested content.
+The connecting line is drawn here — its segment above the dot is hidden on
+the first entry and the segment below is hidden on the last, so the line caps
+exactly at the first and last dots. Only meaningful inside a
+`timeline-container`; demonstrated through it.
+
+Import: `import "@f-ewald/components/timeline-entry.js";`
+
+Properties: `datetime` (attribute `datetime`) : string | null, default null
+Events: none
+CSS custom properties: `--ui-border`, `--ui-font`, `--ui-font-size`, `--ui-font-size-sm`, `--ui-font-weight-semibold`, `--ui-line-height-normal`, `--ui-line-height-tight`, `--ui-primary`, `--ui-text`, `--ui-text-muted`
+
+Example:
+```html
+<timeline-entry datetime="2026-07-23T09:00:00Z">
+  <span slot="headline">Deployment started</span>
+  Release v1.4.0 is rolling out to production.
+</timeline-entry>
+```
+
 ## <toast-notification>
 
 Fixed-position stack of dismissible notifications, anchored top-right

package/package.json

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