@f-ewald/components 1.2.0 → 1.3.0

package/docs/design-language.md

@@ -134,13 +134,86 @@ literal values are migrated onto them.
 
 - Metadata-only tags may omit standalone playground sections when their full
   behavior is demonstrated through a parent:
-  `calendar-entry`, `gallery-item`, and `gallery-item-variant`.
+  `calendar-entry`, `gallery-item`, `gallery-item-variant`, `kanban-card`,
+  `kanban-column`, and `timeline-entry` (shown through `timeline-container`).
 - Styleless inline formatters may omit empty `static styles`/token imports:
   `distance-value`, `live-timer`, `relative-time`, and `roman-numeral`.
 - Domain visuals may deliberately diverge in geometry and data color, but their
   surrounding typography, focus, motion, and accessibility still follow this
   contract.
 
+## Layout and page templates
+
+The layout components compose into dashboard pages: `app-shell` is the grid
+backbone, and `app-sidebar`, `action-bar`, `page-header`, `pagination-nav`, and
+`form-actions` fill its slots and content.
+
+### Shell grid and metrics
+
+- `app-shell` owns a CSS grid with `sidebar`, `topbar`, `main` (default slot),
+  `detail`, and `footer` areas plus the responsive behavior. It is the only
+  component that coordinates the sidebar rail and the detail overlay.
+- Layout dimensions are documented literal rems, not `--ui-*` tokens (widths and
+  spacing are constants in this system). A few are exposed as overridable
+  `--component-*` custom properties for per-instance tuning, mirroring
+  `--component-layer-z`:
+  - sidebar expanded `--component-sidebar-width` = `16rem`;
+  - sidebar rail `--component-sidebar-rail-width` = `3.5rem`;
+  - top bar `--component-topbar-height` = `3rem`;
+  - detail column reuses the `20rem` / `25rem` panel widths (the `detail-width`
+    `compact` / `comfortable` attribute);
+  - main content is white (`--component-main-background`, default `--ui-surface`)
+    and fluid; constrain reading or form pages with a `max-width` on your own
+    wrapper (roughly `40rem`–`48rem`).
+- The shared `48rem` breakpoint remains the only responsive breakpoint. At or
+  below it the sidebar becomes an off-canvas drawer and the detail an overlay,
+  both raised with `--component-layer-z` and dismissed by a scrim or Escape.
+
+### Sidebar
+
+- Collapsing is a two-mode design: on desktop the sidebar condenses to an icon
+  rail (labels hide, icons stay) via `app-shell`'s `sidebar-collapsed`, which
+  propagates `collapsed` to the slotted `app-sidebar`; below `48rem` it is a
+  drawer with labels shown.
+- The built-in top-bar toggle and the `[` keyboard shortcut (ignored while a
+  text field is focused or a modifier is held) both drive `sidebar-collapsed`.
+  The shortcut is surfaced in the toggle's hover/focus tooltip, not as permanent
+  chrome — reveal shortcuts on interaction rather than displaying them inline.
+- Nav items are the consumer's `<a>`/`<button>` elements with an icon and a
+  label; mark the active one with `aria-current="page"`. Each label reads the
+  inherited `--app-sidebar-label` custom property so rail mode can hide it while
+  its `aria-label` keeps the accessible name.
+- The `header` slot holds the brand: a small logo plus a name. Wrap the name in
+  a `--app-sidebar-label` element so rail mode shows only the logo, centered in
+  line with the nav icons.
+
+### Forms and actions
+
+- The action row above a list uses `action-bar` (`start` = search/filters,
+  `end` = record actions). Pagination below a list uses `pagination-nav`, which
+  is controlled: the consumer owns the data and moves the page on `page-change`.
+- Form button order is fixed: the primary/submit button is rightmost, the
+  secondary/cancel button is immediately to its left, and any tertiary or
+  destructive action is pinned to the far left. Use `form-actions`, which
+  enforces this regardless of source order — never hand-place form buttons in a
+  different order.
+- Page and record actions live in the `page-header` actions slot, not a footer
+  bar: the primary action is the prominent, rightmost button, and destructive or
+  rare actions are de-emphasized (a secondary button or an overflow menu, gated
+  by a `confirm-dialog`). Never duplicate the primary action in both a header and
+  a footer.
+- Reserve `form-actions` for the bottom of an actual editable form. Read (detail)
+  and edit (form) are distinct modes: a read view acts through its header and has
+  no Save/Cancel footer; entering edit shows the form with a `form-actions` bar.
+- Fence clearly distinct sections of a detail or form page with `frame-box`.
+
+### Templates
+
+The recipes under `docs/layouts/` compose these into four pages — list-only,
+list + detail, detail-only, and form — and the MCP `list_layouts` /
+`get_layout` tools serve them. Add a page by adding a `docs/layouts/<name>.md`
+recipe and, ideally, a matching full-page demo under `demo/layouts/`.
+
 ## Playground and documentation
 
 - Visual/interactive nav links and complete sections are alphabetical and have

package/docs/form-actions.md

@@ -0,0 +1,43 @@
+# `<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.
+
+## Install
+
+```js
+import "@f-ewald/components/form-actions.js";
+```
+
+## Usage
+
+```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>
+```
+
+## Attributes / properties
+
+_None._
+
+## Events
+
+_None._
+
+## Slots
+
+_None._
+
+## CSS custom properties
+
+_None._

package/docs/layouts/detail-only.md

@@ -0,0 +1,52 @@
+# Detail-only page
+
+A single record's read view: navigation, a titled header carrying the record
+actions, and the record body grouped into framed sections.
+
+**When to use:** viewing one record on its own route (linked to from a list).
+Read and edit are distinct modes — keep this page read-only and let its primary
+action navigate to the form page for editing.
+
+## Shell slots
+
+- `sidebar` → `app-sidebar`.
+- `topbar` → `page-header` with a linked `breadcrumb` and the record `actions`.
+- default (`main`) → the record body; group distinct sections with `frame-box`.
+
+## Markup
+
+```html
+<app-shell style="height: 100vh">
+  <app-sidebar slot="sidebar"><!-- nav items --></app-sidebar>
+
+  <page-header slot="topbar" heading="Ada Lovelace">
+    <nav slot="breadcrumb" aria-label="Breadcrumb"><a href="/members">Members</a> / Ada Lovelace</nav>
+    <!-- Record actions: primary rightmost, destructive de-emphasized. -->
+    <ui-button slot="actions" variant="secondary">Deactivate</ui-button>
+    <ui-button slot="actions" variant="primary">Edit</ui-button>
+  </page-header>
+
+  <div style="max-width: 48rem;">
+    <frame-box label="Profile"><!-- fields --></frame-box>
+    <frame-box label="Access"><!-- fields --></frame-box>
+  </div>
+</app-shell>
+```
+
+## Notes
+
+- Put record actions in the header, not a footer bar. The primary action (Edit)
+  is the rightmost, prominent button; keep destructive actions (Deactivate,
+  Delete) de-emphasized — a secondary button, or an overflow menu — and gate
+  them with a `confirm-dialog`.
+- Do **not** add a `form-actions` footer here. `form-actions` (Save/Cancel) is
+  for the bottom of an editable form; a read view has nothing to save. Reserve
+  it for the form page — which is where Edit navigates.
+- Back navigation comes from the breadcrumb link, so there is no separate Close
+  button.
+- Constrain the record body with a `max-width` (about `40rem`–`48rem`) and fence
+  distinct field groups with `frame-box`.
+
+**Live demo:** `demo/layouts/detail-only.html`
+
+**Components:** app-shell, app-sidebar, page-header, frame-box, ui-button

package/docs/layouts/form-page.md

@@ -0,0 +1,52 @@
+# Form page
+
+A create/edit form: navigation, a titled header, a single form grouped into
+framed sections, and a `form-actions` bar with the fixed button order.
+
+**When to use:** creating or editing one record. Keep the form in a single
+column so the eye tracks one field to the next.
+
+## Shell slots
+
+- `sidebar` → `app-sidebar`.
+- `topbar` → `page-header` with a `breadcrumb`.
+- default (`main`) → one `<form>`; group fields with `frame-box` and end with
+  `form-actions`.
+
+## Markup
+
+```html
+<app-shell style="height: 100vh">
+  <app-sidebar slot="sidebar"><!-- nav items --></app-sidebar>
+
+  <page-header slot="topbar" heading="Invite member">
+    <nav slot="breadcrumb" aria-label="Breadcrumb">Members / Invite</nav>
+  </page-header>
+
+  <form style="max-width: 40rem;">
+    <frame-box label="Details"><!-- name, email fields --></frame-box>
+    <frame-box label="Role"><!-- role field --></frame-box>
+
+    <form-actions>
+      <ui-button slot="secondary" variant="secondary">Cancel</ui-button>
+      <ui-button slot="primary" type="submit" variant="primary">Send invite</ui-button>
+    </form-actions>
+  </form>
+</app-shell>
+```
+
+## Notes
+
+- Button order is fixed and enforced by `form-actions`: primary/submit rightmost,
+  secondary/cancel to its left, any destructive action pinned far left. Never
+  hand-place form buttons in a different order.
+- Constrain the form with a `max-width` (about `40rem`); a full-width form on a
+  wide dashboard is hard to scan.
+- Group related fields with `frame-box`; keep one field per row in a single
+  column.
+- `ui-button type="submit"` associates with the ancestor `<form>` even from
+  inside `form-actions`.
+
+**Live demo:** `demo/layouts/form-page.html`
+
+**Components:** app-shell, app-sidebar, page-header, frame-box, form-actions, ui-button

package/docs/layouts/list-detail.md

@@ -0,0 +1,52 @@
+# List + detail page
+
+A master-detail dashboard: the list-only page plus a right-hand detail column.
+Selecting a row shows its detail beside the list on desktop and as an overlay on
+narrow screens.
+
+**When to use:** triaging or editing records where keeping the list visible
+while inspecting one item speeds up the workflow (inbox-style screens, admin
+record management).
+
+## Shell slots
+
+- `sidebar` → `app-sidebar`.
+- `topbar` → `page-header`.
+- default (`main`) → `action-bar` + `data-table`.
+- `detail` → the selected record's detail; shown when `detail-open` is set.
+- `footer` → `pagination-nav`.
+
+## Markup
+
+```html
+<app-shell detail-width="comfortable" 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="primary">Create</ui-button>
+    </action-bar>
+    <data-table style="margin-top: 0.5rem; display: block;"></data-table>
+  </div>
+
+  <div slot="detail" style="padding: 1rem;"><!-- selected record --></div>
+
+  <pagination-nav slot="footer" current-page="1" total-pages="6"></pagination-nav>
+</app-shell>
+```
+
+## Notes
+
+- Set `detail-open` on `app-shell` to reveal the detail column; clear it (or
+  listen for the `detail-close` event, fired when the mobile scrim/Escape
+  dismisses the overlay) to hide it.
+- Wire a row selection (e.g. `data-table`'s `rowHref` + a hash listener, or your
+  router) to populate the detail slot and open it.
+- `detail-width` is `compact` (20rem) or `comfortable` (25rem); below 48rem the
+  detail becomes an overlay regardless.
+
+**Live demo:** `demo/layouts/list-detail.html`
+
+**Components:** app-shell, app-sidebar, page-header, action-bar, data-table, pagination-nav

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