@f-ewald/components 1.2.1 → 1.4.0

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