@f-ewald/components 1.2.1 → 1.4.0

package/dist/timeline-entry.d.ts

@@ -0,0 +1,31 @@
+import { LitElement } from "lit";
+import "./relative-time.js";
+/**
+ * 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.
+ *
+ * @element timeline-entry
+ * @slot headline - Optional headline/title for the event.
+ * @slot - The event content; nest any elements here.
+ */
+export declare class TimelineEntry extends LitElement {
+    /** ISO 8601 or SQLite datetime string, rendered as a relative time. */
+    datetime: string | null;
+    /** Whether the headline slot currently has assigned content. */
+    private _hasHeadline;
+    static styles: import("lit").CSSResult[];
+    connectedCallback(): void;
+    /** Collapses the headline when nothing is slotted so the time sits alone. */
+    private _onHeadlineSlotChange;
+    render(): import("lit-html").TemplateResult<1>;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        "timeline-entry": TimelineEntry;
+    }
+}
+//# sourceMappingURL=timeline-entry.d.ts.map

package/dist/timeline-entry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timeline-entry.d.ts","sourceRoot":"","sources":["../src/timeline-entry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAsB,MAAM,KAAK,CAAC;AAErD,OAAO,oBAAoB,CAAC;AAG5B;;;;;;;;;;;GAWG;AACH,qBACa,aAAc,SAAQ,UAAU;IAC3C,uEAAuE;IAC3D,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAQ;IAE3C,gEAAgE;IACvD,OAAO,CAAC,YAAY,CAAS;IAEtC,OAAgB,MAAM,4BAgGpB;IAEO,iBAAiB,IAAI,IAAI,CAGjC;IAED,6EAA6E;IAC7E,OAAO,CAAC,qBAAqB;IAIpB,MAAM,yCAqBd;CACF;AAED,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,qBAAqB;QAC7B,gBAAgB,EAAE,aAAa,CAAC;KACjC;CACF"}

package/dist/timeline-entry.js

@@ -0,0 +1,170 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { LitElement, css, html, nothing } from "lit";
+import { customElement, property, state } from "lit/decorators.js";
+import "./relative-time.js";
+import { tokens } from "./tokens.js";
+/**
+ * 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.
+ *
+ * @element timeline-entry
+ * @slot headline - Optional headline/title for the event.
+ * @slot - The event content; nest any elements here.
+ */
+let TimelineEntry = class TimelineEntry extends LitElement {
+    constructor() {
+        super(...arguments);
+        /** ISO 8601 or SQLite datetime string, rendered as a relative time. */
+        this.datetime = null;
+        /** Whether the headline slot currently has assigned content. */
+        this._hasHeadline = false;
+    }
+    static { this.styles = [
+        tokens,
+        css `
+      :host {
+        display: block;
+        font-family: var(
+          --ui-font,
+          ui-sans-serif,
+          system-ui,
+          sans-serif,
+          "Apple Color Emoji",
+          "Segoe UI Emoji",
+          "Segoe UI Symbol",
+          "Noto Color Emoji"
+        );
+      }
+      .entry {
+        display: flex;
+        gap: 0.75rem;
+      }
+      .rail {
+        position: relative;
+        flex: 0 0 auto;
+        width: 0.75rem;
+      }
+      .line {
+        position: absolute;
+        left: 50%;
+        width: 2px;
+        transform: translateX(-50%);
+        background: var(--ui-border, #e2e8f0);
+      }
+      .line-top {
+        top: 0;
+        height: 0.5rem;
+      }
+      .line-bottom {
+        top: 0.5rem;
+        bottom: 0;
+      }
+      .dot {
+        position: absolute;
+        top: 0.125rem;
+        left: 50%;
+        width: 0.75rem;
+        height: 0.75rem;
+        transform: translateX(-50%);
+        border-radius: 9999px;
+        /* Same primary-token gradient as map-circle/user-avatar, lighter on top. */
+        background: linear-gradient(
+          to bottom,
+          color-mix(in srgb, var(--ui-primary, #4f46e5) 70%, #ffffff) 0%,
+          color-mix(in srgb, var(--ui-primary, #4f46e5) 70%, #000000) 100%
+        );
+      }
+      :host(:first-child) .line-top {
+        display: none;
+      }
+      :host(:last-child) .line-bottom {
+        display: none;
+      }
+      .body {
+        flex: 1 1 auto;
+        min-width: 0;
+        padding-bottom: 1.5rem;
+      }
+      :host(:last-child) .body {
+        padding-bottom: 0;
+      }
+      .head {
+        display: flex;
+        align-items: baseline;
+        gap: 0.5rem;
+        flex-wrap: wrap;
+      }
+      .headline {
+        font-weight: var(--ui-font-weight-semibold, 600);
+        font-size: var(--ui-font-size, 0.875rem);
+        line-height: var(--ui-line-height-tight, 1.25);
+        color: var(--ui-text, #0f172a);
+      }
+      .headline.empty {
+        display: none;
+      }
+      .time {
+        font-size: var(--ui-font-size-sm, 0.75rem);
+        line-height: var(--ui-line-height-tight, 1.25);
+        color: var(--ui-text-muted, #64748b);
+      }
+      .content {
+        margin-top: 0.25rem;
+        font-size: var(--ui-font-size, 0.875rem);
+        line-height: var(--ui-line-height-normal, 1.5);
+        color: var(--ui-text, #0f172a);
+      }
+    `,
+    ]; }
+    connectedCallback() {
+        super.connectedCallback();
+        if (!this.hasAttribute("role"))
+            this.setAttribute("role", "listitem");
+    }
+    /** Collapses the headline when nothing is slotted so the time sits alone. */
+    _onHeadlineSlotChange(event) {
+        this._hasHeadline = event.target.assignedNodes({ flatten: true }).length > 0;
+    }
+    render() {
+        return html `
+      <div class="entry">
+        <div class="rail" aria-hidden="true">
+          <span class="line line-top"></span>
+          <span class="line line-bottom"></span>
+          <span class="dot"></span>
+        </div>
+        <div class="body">
+          <div class="head">
+            <span class="headline ${this._hasHeadline ? "" : "empty"}">
+              <slot name="headline" @slotchange=${this._onHeadlineSlotChange}></slot>
+            </span>
+            ${this.datetime
+            ? html `<relative-time class="time" datetime=${this.datetime}></relative-time>`
+            : nothing}
+          </div>
+          <div class="content"><slot></slot></div>
+        </div>
+      </div>
+    `;
+    }
+};
+__decorate([
+    property()
+], TimelineEntry.prototype, "datetime", void 0);
+__decorate([
+    state()
+], TimelineEntry.prototype, "_hasHeadline", void 0);
+TimelineEntry = __decorate([
+    customElement("timeline-entry")
+], TimelineEntry);
+export { TimelineEntry };
+//# sourceMappingURL=timeline-entry.js.map

package/dist/timeline-entry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"timeline-entry.js","sourceRoot":"","sources":["../src/timeline-entry.ts"],"names":[],"mappings":";;;;;;AAAA,OAAO,EAAE,UAAU,EAAE,GAAG,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,KAAK,CAAC;AACrD,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AACnE,OAAO,oBAAoB,CAAC;AAC5B,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAErC;;;;;;;;;;;GAWG;AAEI,IAAM,aAAa,GAAnB,MAAM,aAAc,SAAQ,UAAU;IAAtC;;QACL,uEAAuE;QAC3D,aAAQ,GAAkB,IAAI,CAAC;QAE3C,gEAAgE;QAC/C,iBAAY,GAAG,KAAK,CAAC;IAoIxC,CAAC;aAlIiB,WAAM,GAAG;QACvB,MAAM;QACN,GAAG,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KA6FF;KACF,AAhGqB,CAgGpB;IAEO,iBAAiB;QACxB,KAAK,CAAC,iBAAiB,EAAE,CAAC;QAC1B,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC,MAAM,CAAC;YAAE,IAAI,CAAC,YAAY,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACxE,CAAC;IAED,6EAA6E;IACrE,qBAAqB,CAAC,KAAY;QACxC,IAAI,CAAC,YAAY,GAAI,KAAK,CAAC,MAA0B,CAAC,aAAa,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC;IACpG,CAAC;IAEQ,MAAM;QACb,OAAO,IAAI,CAAA;;;;;;;;;oCASqB,IAAI,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO;kDAClB,IAAI,CAAC,qBAAqB;;cAE9D,IAAI,CAAC,QAAQ;YACb,CAAC,CAAC,IAAI,CAAA,wCAAwC,IAAI,CAAC,QAAQ,mBAAmB;YAC9E,CAAC,CAAC,OAAO;;;;;KAKlB,CAAC;IACJ,CAAC;CACF,CAAA;AAvIa;IAAX,QAAQ,EAAE;+CAAgC;AAG1B;IAAhB,KAAK,EAAE;mDAA8B;AAL3B,aAAa;IADzB,aAAa,CAAC,gBAAgB,CAAC;GACnB,aAAa,CAyIzB","sourcesContent":["import { LitElement, css, html, nothing } from \"lit\";\nimport { customElement, property, state } from \"lit/decorators.js\";\nimport \"./relative-time.js\";\nimport { tokens } from \"./tokens.js\";\n\n/**\n * One event on a `timeline-container`: a dot on the vertical line, an optional\n * headline, a relative timestamp (\"3 hours ago\"), and freely nested content.\n * The connecting line is drawn here — its segment above the dot is hidden on\n * the first entry and the segment below is hidden on the last, so the line caps\n * exactly at the first and last dots. Only meaningful inside a\n * `timeline-container`; demonstrated through it.\n *\n * @element timeline-entry\n * @slot headline - Optional headline/title for the event.\n * @slot - The event content; nest any elements here.\n */\n@customElement(\"timeline-entry\")\nexport class TimelineEntry extends LitElement {\n  /** ISO 8601 or SQLite datetime string, rendered as a relative time. */\n  @property() datetime: string | null = null;\n\n  /** Whether the headline slot currently has assigned content. */\n  @state() private _hasHeadline = false;\n\n  static override styles = [\n    tokens,\n    css`\n      :host {\n        display: block;\n        font-family: var(\n          --ui-font,\n          ui-sans-serif,\n          system-ui,\n          sans-serif,\n          \"Apple Color Emoji\",\n          \"Segoe UI Emoji\",\n          \"Segoe UI Symbol\",\n          \"Noto Color Emoji\"\n        );\n      }\n      .entry {\n        display: flex;\n        gap: 0.75rem;\n      }\n      .rail {\n        position: relative;\n        flex: 0 0 auto;\n        width: 0.75rem;\n      }\n      .line {\n        position: absolute;\n        left: 50%;\n        width: 2px;\n        transform: translateX(-50%);\n        background: var(--ui-border, #e2e8f0);\n      }\n      .line-top {\n        top: 0;\n        height: 0.5rem;\n      }\n      .line-bottom {\n        top: 0.5rem;\n        bottom: 0;\n      }\n      .dot {\n        position: absolute;\n        top: 0.125rem;\n        left: 50%;\n        width: 0.75rem;\n        height: 0.75rem;\n        transform: translateX(-50%);\n        border-radius: 9999px;\n        /* Same primary-token gradient as map-circle/user-avatar, lighter on top. */\n        background: linear-gradient(\n          to bottom,\n          color-mix(in srgb, var(--ui-primary, #4f46e5) 70%, #ffffff) 0%,\n          color-mix(in srgb, var(--ui-primary, #4f46e5) 70%, #000000) 100%\n        );\n      }\n      :host(:first-child) .line-top {\n        display: none;\n      }\n      :host(:last-child) .line-bottom {\n        display: none;\n      }\n      .body {\n        flex: 1 1 auto;\n        min-width: 0;\n        padding-bottom: 1.5rem;\n      }\n      :host(:last-child) .body {\n        padding-bottom: 0;\n      }\n      .head {\n        display: flex;\n        align-items: baseline;\n        gap: 0.5rem;\n        flex-wrap: wrap;\n      }\n      .headline {\n        font-weight: var(--ui-font-weight-semibold, 600);\n        font-size: var(--ui-font-size, 0.875rem);\n        line-height: var(--ui-line-height-tight, 1.25);\n        color: var(--ui-text, #0f172a);\n      }\n      .headline.empty {\n        display: none;\n      }\n      .time {\n        font-size: var(--ui-font-size-sm, 0.75rem);\n        line-height: var(--ui-line-height-tight, 1.25);\n        color: var(--ui-text-muted, #64748b);\n      }\n      .content {\n        margin-top: 0.25rem;\n        font-size: var(--ui-font-size, 0.875rem);\n        line-height: var(--ui-line-height-normal, 1.5);\n        color: var(--ui-text, #0f172a);\n      }\n    `,\n  ];\n\n  override connectedCallback(): void {\n    super.connectedCallback();\n    if (!this.hasAttribute(\"role\")) this.setAttribute(\"role\", \"listitem\");\n  }\n\n  /** Collapses the headline when nothing is slotted so the time sits alone. */\n  private _onHeadlineSlotChange(event: Event): void {\n    this._hasHeadline = (event.target as HTMLSlotElement).assignedNodes({ flatten: true }).length > 0;\n  }\n\n  override render() {\n    return html`\n      <div class=\"entry\">\n        <div class=\"rail\" aria-hidden=\"true\">\n          <span class=\"line line-top\"></span>\n          <span class=\"line line-bottom\"></span>\n          <span class=\"dot\"></span>\n        </div>\n        <div class=\"body\">\n          <div class=\"head\">\n            <span class=\"headline ${this._hasHeadline ? \"\" : \"empty\"}\">\n              <slot name=\"headline\" @slotchange=${this._onHeadlineSlotChange}></slot>\n            </span>\n            ${this.datetime\n              ? html`<relative-time class=\"time\" datetime=${this.datetime}></relative-time>`\n              : nothing}\n          </div>\n          <div class=\"content\"><slot></slot></div>\n        </div>\n      </div>\n    `;\n  }\n}\n\ndeclare global {\n  interface HTMLElementTagNameMap {\n    \"timeline-entry\": TimelineEntry;\n  }\n}\n"]}

package/docs/action-bar.md

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

package/docs/app-shell.md

@@ -0,0 +1,85 @@
+# `<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.
+
+## Install
+
+```js
+import "@f-ewald/components/app-shell.js";
+```
+
+## Usage
+
+```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>
+```
+
+## Attributes / properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `sidebarCollapsed` | `sidebar-collapsed` | `boolean` | `false` | Collapses the sidebar to an icon rail on desktop. |
+| `detailOpen` | `detail-open` | `boolean` | `false` | Shows the right-hand detail region (inline column, or overlay on mobile). |
+| `detailWidth` | `detail-width` | `"compact" | "comfortable"` | `"compact"` | Detail width: `compact` (20rem) or `comfortable` (25rem). |
+
+## Events
+
+| Event | Description |
+| --- | --- |
+| `sidebar-toggle` | The built-in toggle changed the sidebar state. |
+| `detail-close` | The scrim or Escape dismissed the mobile detail overlay. |
+
+## Slots
+
+_None._
+
+## CSS custom properties
+
+| Custom property |
+| --- |
+| `--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` |

package/docs/app-sidebar.md

@@ -0,0 +1,69 @@
+# `<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.
+
+## Install
+
+```js
+import "@f-ewald/components/app-sidebar.js";
+```
+
+## Usage
+
+```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>
+```
+
+## Attributes / properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `collapsed` | `collapsed` | `boolean` | `false` | Collapses the sidebar to an icon rail (centers icons, hides labels). |
+
+## Events
+
+_None._
+
+## Slots
+
+_None._
+
+## CSS custom properties
+
+| Custom property |
+| --- |
+| `--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` |

package/docs/content-divider.md

@@ -0,0 +1,47 @@
+# `<content-divider>`
+
+A horizontal divider: a thin rule that visually separates two pieces of
+content that are not otherwise contained in a box or frame and would bleed
+into each other. With a `label` it renders the common "───  OR  ───"
+pattern — text centered between two line segments; without one it is a
+single full-width rule. Exposed to assistive technology as a horizontal
+separator, so it renders correctly with zero external CSS.
+
+## Install
+
+```js
+import "@f-ewald/components/content-divider.js";
+```
+
+## Usage
+
+```html
+<content-divider></content-divider>
+
+<content-divider label="OR"></content-divider>
+```
+
+## Attributes / properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `label` | `label` | `string` | `""` | Optional centered label; empty renders a plain full-width rule. |
+
+## Events
+
+_None._
+
+## Slots
+
+_None._
+
+## CSS custom properties
+
+| Custom property |
+| --- |
+| `--ui-border` |
+| `--ui-font` |
+| `--ui-font-size-sm` |
+| `--ui-font-weight-medium` |
+| `--ui-line-height-tight` |
+| `--ui-text-muted` |

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