fold-ng 0.5.2 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fold-ng",
-  "version": "0.5.2",
+  "version": "0.6.0",
   "description": "Accessible, dark-first Angular 22 UI component library & design system — signals-first, standalone, zoneless, SSR-ready. Design tokens + WCAG-minded components, themeable to the bone.",
   "keywords": [
     "angular",

package/tokens/scales.css

@@ -54,6 +54,13 @@
   --fold-space-md: 12px;
   --fold-space-lg: 16px;
   --fold-space-xl: 20px;
+  /* Larger steps on the 4px grid — section padding, page-level gaps, hero bands.
+     The scale stays tight (no half-steps): a 4px-grid rhythm is the constraint;
+     rare off-grid needs stay explicit literals, not tokens. */
+  --fold-space-2xl: 24px;
+  --fold-space-3xl: 32px;
+  --fold-space-4xl: 40px;
+  --fold-space-5xl: 48px;
 
   /* Rail-width scale — the shared widths for the nav-rail hierarchy, named to
      pair 1:1 with the `--fold-color-bg-rail-*` colour tokens (primary app menu →

package/tokens/semantic.css

@@ -26,6 +26,18 @@
 
 /* ── Base theme: UMBRA (dark) ─────────────────────────────── */
 :root {
+  /* Page scaffold rhythm — FLUID defaults, read by `fold-page-layout` via
+     `var()`. A page/theme overrides on any ancestor (or the element) to retune;
+     the playground sets them inline. The gutter scales more than the gap:
+     horizontal room is precious on small screens, vertical rhythm less so — so
+     the two carry deliberately different responsive curves. */
+  --fold-page-gutter: clamp(1rem, 4vw, 2rem); /* 16 → 32px  (fluid 400–800px) */
+  --fold-page-gap: clamp(
+    1.25rem,
+    3vw,
+    2rem
+  ); /* 20 → 32px  (fluid ~665–1065px) */
+
   /* Surfaces (bg- = a fill role, darkest chrome → lightest page) */
   --fold-color-bg-page: var(--fold-ref-ink-850); /* page background        */
   --fold-color-bg-header: var(--fold-ref-ink-950); /* top header bar        */

package/types/fold-ng.d.ts

@@ -548,6 +548,7 @@ declare const FOLD_BUILTIN_ICONS: {
     readonly timeline: "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"1.7\" stroke-linecap=\"round\" stroke-linejoin=\"round\"><rect x=\"3\" y=\"5\" width=\"18\" height=\"14\" rx=\"2\"/><path d=\"M3 10h18M8 5v14M13 10v9\"/></svg>";
     readonly library: "<svg viewBox=\"0 0 512 512\" xmlns=\"http://www.w3.org/2000/svg\"><rect x=\"32\" y=\"96\" width=\"64\" height=\"368\" rx=\"16\" ry=\"16\" style=\"fill:none;stroke:currentColor;stroke-linejoin:round;stroke-width:32px\"/><line x1=\"112\" y1=\"224\" x2=\"240\" y2=\"224\" style=\"fill:none;stroke:currentColor;stroke-linecap:round;stroke-linejoin:round;stroke-width:32px\"/><line x1=\"112\" y1=\"400\" x2=\"240\" y2=\"400\" style=\"fill:none;stroke:currentColor;stroke-linecap:round;stroke-linejoin:round;stroke-width:32px\"/><rect x=\"112\" y=\"160\" width=\"128\" height=\"304\" rx=\"16\" ry=\"16\" style=\"fill:none;stroke:currentColor;stroke-linejoin:round;stroke-width:32px\"/><rect x=\"256\" y=\"48\" width=\"96\" height=\"416\" rx=\"16\" ry=\"16\" style=\"fill:none;stroke:currentColor;stroke-linejoin:round;stroke-width:32px\"/><path d=\"M422.46,96.11l-40.4,4.25c-11.12,1.17-19.18,11.57-17.93,23.1l34.92,321.59c1.26,11.53,11.37,20,22.49,18.84l40.4-4.25c11.12-1.17,19.18-11.57,17.93-23.1L445,115C443.69,103.42,433.58,94.94,422.46,96.11Z\" style=\"fill:none;stroke:currentColor;stroke-linejoin:round;stroke-width:32px\"/></svg>";
     readonly "add-doc": "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\"><path d=\"m21.414 5h-4.414v-4.414zm.586 2v17h-20v-21a3 3 0 0 1 3-3h10v7zm-6 7h-3v-3h-2v3h-3v2h3v3h2v-3h3z\"/></svg>";
+    readonly archive: "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"2\" stroke-linecap=\"round\" stroke-linejoin=\"round\"><path d=\"M21 8v13H3V8\"/><rect x=\"1\" y=\"3\" width=\"22\" height=\"5\" rx=\"1\"/><path d=\"M10 12h4\"/></svg>";
     readonly "arrow-back": "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"2\" stroke-linecap=\"round\" stroke-linejoin=\"round\"><path d=\"M19 12H5M12 19l-7-7 7-7\"/></svg>";
     readonly "arrow-right": "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"2\" stroke-linecap=\"round\" stroke-linejoin=\"round\"><path d=\"M5 12h14M12 5l7 7-7 7\"/></svg>";
     readonly bin: "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\"><path d=\"M22,4H17V2a2,2,0,0,0-2-2H9A2,2,0,0,0,7,2V4H2V6H4V21a3,3,0,0,0,3,3H17a3,3,0,0,0,3-3V6h2ZM9,2h6V4H9Zm9,19a1,1,0,0,1-1,1H7a1,1,0,0,1-1-1V6H18Z\"/><rect x=\"9\" y=\"10\" width=\"2\" height=\"8\"/><rect x=\"13\" y=\"10\" width=\"2\" height=\"8\"/></svg>";
@@ -570,6 +571,7 @@ declare const FOLD_BUILTIN_ICONS: {
     readonly "eye-off": "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"2\" stroke-linecap=\"round\" stroke-linejoin=\"round\"><path d=\"M17.94 17.94A10.07 10.07 0 0112 20c-7 0-11-8-11-8a18.45 18.45 0 015.06-5.94M9.9 4.24A9.12 9.12 0 0112 4c7 0 11 8 11 8a18.5 18.5 0 01-2.16 3.19m-6.72-1.07a3 3 0 11-4.24-4.24\"/><line x1=\"1\" y1=\"1\" x2=\"23\" y2=\"23\"/></svg>";
     readonly eye: "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"2\" stroke-linecap=\"round\" stroke-linejoin=\"round\"><path d=\"M1 12s4-8 11-8 11 8 11 8-4 8-11 8-11-8-11-8z\"/><circle cx=\"12\" cy=\"12\" r=\"3\"/></svg>";
     readonly "file-add": "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"2\" stroke-linecap=\"round\" stroke-linejoin=\"round\"><path d=\"M14 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V8z\"/><polyline points=\"14 2 14 8 20 8\"/><line x1=\"12\" y1=\"18\" x2=\"12\" y2=\"12\"/><line x1=\"9\" y1=\"15\" x2=\"15\" y2=\"15\"/></svg>";
+    readonly filter: "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"2\" stroke-linecap=\"round\" stroke-linejoin=\"round\"><path d=\"M22 3H2l8 9.46V19l4 2v-8.54L22 3z\"/></svg>";
     readonly "folder-open": "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"2\" stroke-linecap=\"round\" stroke-linejoin=\"round\"><path d=\"M22 19a2 2 0 0 1-2 2H4a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2h5l2 3h9a2 2 0 0 1 2 2z\"/></svg>";
     readonly folder: "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\"><path d=\"M21,3H12.236l-4-2H3A3,3,0,0,0,0,4V23H24V6A3,3,0,0,0,21,3ZM3,3H7.764l4,2H21a1,1,0,0,1,1,1v.881L2,6.994V4A1,1,0,0,1,3,3ZM2,21V8.994l20-.113V21Z\"/></svg>";
     readonly globe: "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"2\"><path d=\"M12 3C6.5 3 2 9 2 12s4.5 9 10 9 10-6 10-9-4.5-9-10-9z\"/><circle cx=\"12\" cy=\"12\" r=\"3\"/></svg>";
@@ -606,6 +608,9 @@ type FoldIconName = FoldBuiltinIconName | (string & {});
 
 /** Size presets map to an icon-size token; a number is interpreted as pixels. */
 type FoldIconSize = "xs" | "sm" | "md" | "lg" | "xl" | number;
+/** Semantic tint. Unset = inherit the context's `currentColor` (the default —
+ *  an icon matches whatever it sits in); set it to override with a role colour. */
+type FoldIconTone = "primary" | "secondary" | "muted" | "faded";
 /**
  * `fold-icon` — the single surface for all SVG icons.
  *
@@ -625,6 +630,7 @@ type FoldIconSize = "xs" | "sm" | "md" | "lg" | "xl" | number;
  * <fold-icon name="search" />
  * <fold-icon name="bin" size="lg" />
  * <fold-icon name="heart" [size]="18" />
+ * <fold-icon name="star" tone="primary" />  <!-- accent tint, ignores context -->
  * <fold-icon name="edit" title="Edit track" />  <!-- a11y label -->
  * ```
  */
@@ -633,6 +639,9 @@ declare class FoldIconComponent {
     readonly name: _angular_core.InputSignal<FoldIconName>;
     /** Size — token (`xs…xl`) or explicit pixel number. Defaults to `md`. */
     readonly size: _angular_core.InputSignal<FoldIconSize>;
+    /** Semantic tint — `primary` · `secondary` · `muted` · `faded`. Unset (default)
+     *  inherits `currentColor`, so the icon matches whatever it sits in. */
+    readonly tone: _angular_core.InputSignal<FoldIconTone | undefined>;
     /** Optional accessible label. Set → `aria-label`; unset → `aria-hidden`. */
     readonly title: _angular_core.InputSignal<string | undefined>;
     private readonly registry;
@@ -642,9 +651,11 @@ declare class FoldIconComponent {
     readonly href: _angular_core.Signal<string | null>;
     /** Resolves the size input to a CSS length string for `--icon-size`. */
     readonly sizeVar: _angular_core.Signal<string>;
+    /** The tone's colour token, or null to inherit `currentColor` (no override). */
+    readonly toneColor: _angular_core.Signal<string | null>;
     constructor();
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<FoldIconComponent, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<FoldIconComponent, "fold-icon", never, { "name": { "alias": "name"; "required": true; "isSignal": true; }; "size": { "alias": "size"; "required": false; "isSignal": true; }; "title": { "alias": "title"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<FoldIconComponent, "fold-icon", never, { "name": { "alias": "name"; "required": true; "isSignal": true; }; "size": { "alias": "size"; "required": false; "isSignal": true; }; "tone": { "alias": "tone"; "required": false; "isSignal": true; }; "title": { "alias": "title"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
 }
 
 /**
@@ -1439,9 +1450,12 @@ type FoldMenuTogglePlacement = "auto" | "footer" | "header" | "body";
  *
  * ## Options
  * - `collapsible` — render a chevron toggle that flips `expanded`.
- * - `expanded` (two-way) — `false` (default) is the icon rail: items are
- *   icon-only with hover tooltips. `true` widens the rail and items + separators
- *   show their labels inline. Drive it yourself (`[expanded]`) or let the toggle.
+ * - `expanded` (two-way) — `true` widens the rail and reveals inline labels;
+ *   `false` is the icon rail (icon-only, hover tooltips). **Left unbound it
+ *   follows `collapsible`:** `<fold-menu collapsible>` boots **expanded** (you
+ *   added a way to collapse, so open is the natural start), a bare `<fold-menu>`
+ *   boots the icon rail. Bind it (`[expanded]` / `[(expanded)]`) to be
+ *   authoritative — an explicit value always wins.
  *
  * ## Slots
  * | Attribute   | Band                                                        |
@@ -1468,11 +1482,13 @@ declare class FoldMenuComponent {
     /** Show a chevron toggle that flips `expanded`. */
     readonly collapsible: _angular_core.InputSignalWithTransform<boolean, unknown>;
     /**
-     * Two-way: `true` widens the rail and reveals inline labels. A standalone
-     * state — a menu can be statically expanded (a labelled sidebar) without
-     * `collapsible`; `collapsible` only adds the toggle that flips it.
+     * Two-way. `true` widens the rail and reveals inline labels; `false` is the
+     * icon rail. **`undefined` (the default) means "unset"** — the effective state
+     * then follows `collapsible` (see {@link isExpanded}), so a bare `collapsible`
+     * menu opens without the consumer having to bind it. A bound value is always
+     * authoritative.
      */
-    readonly expanded: _angular_core.ModelSignal<boolean>;
+    readonly expanded: _angular_core.ModelSignal<boolean | undefined>;
     /** How items tint on hover / when active (`follow` = section colour). */
     readonly tint: _angular_core.InputSignal<FoldMenuTint>;
     /** Rail depth → background tint (`primary` default / `secondary` / `tertiary`). */
@@ -1483,6 +1499,13 @@ declare class FoldMenuComponent {
     private readonly footRef;
     private readonly hasHeader;
     private readonly hasFooter;
+    /**
+     * The effective expanded state everything renders from: the bound `expanded`
+     * when set, else it follows `collapsible` (a collapsible rail boots open, a
+     * plain one boots as the icon rail). Encodes the sensible default without a
+     * warning — the short `<fold-menu collapsible>` Just Works.
+     */
+    protected readonly isExpanded: _angular_core.Signal<boolean>;
     /**
      * The band the toggle renders into: the `togglePlacement` override when set,
      * else auto — first in the footer, else last in the header, else the body.
@@ -1847,10 +1870,11 @@ declare function provideFoldDataTableLabels(labels: Partial<FoldDataTableLabels>
  * owns the chrome (sticky sortable header, row tone accents, focus/click, the
  * mobile card layout, the loading + empty states).
  *
- * Selection stays controlled too: pass a `selected` set of row keys and handle
- * `selectionChange` — the table renders the checkbox column, the header
- * select-all (with an indeterminate state over the current rows), and the
- * selected-row tint, but never owns the set.
+ * Selection is a two-way model: bind `[(selected)]` with a set of row keys and
+ * the table writes the next set back on any checkbox toggle — it renders the
+ * checkbox column, the header select-all (with an indeterminate state over the
+ * current rows), and the selected-row tint. Bind it one-way (`[selected]`) to
+ * stay fully controlled.
  *
  * The narrow-screen behaviour is the parent's choice, not an imposed one, via
  * `mobileLayout`: `scroll` (default — stay tabular, scroll horizontally),
@@ -1901,14 +1925,17 @@ declare class FoldDataTableComponent<T> {
     readonly stickyFirst: _angular_core.InputSignalWithTransform<boolean, unknown>;
     /** Renders the checkbox column + header select-all. */
     readonly selectable: _angular_core.InputSignalWithTransform<boolean, unknown>;
-    /** Controlled selection — the set of selected row keys. The parent owns it. */
-    readonly selected: _angular_core.InputSignal<ReadonlySet<string | number>>;
+    /**
+     * Selected row keys, as a **two-way model** — bind `[(selected)]` and the
+     * table writes the next set back on any toggle (it never mutates the set in
+     * place). One-way `[selected]` stays fully controlled. The one source of
+     * selection: there is no separate change output.
+     */
+    readonly selected: _angular_core.ModelSignal<ReadonlySet<string | number>>;
     /** Accessible label for a row's checkbox, e.g. `(row) => row.name`. */
     readonly selectionLabel: _angular_core.InputSignal<((row: T) => string) | undefined>;
     /** Per-instance label overrides (merged over the app-wide / English defaults). */
     readonly labels: _angular_core.InputSignal<Partial<FoldDataTableLabels> | undefined>;
-    /** Emits the next selection set on any checkbox toggle (never mutates input). */
-    readonly selectionChange: _angular_core.OutputEmitterRef<Set<string | number>>;
     /** Emits the clicked sortable column's `key`. */
     readonly sortChange: _angular_core.OutputEmitterRef<string>;
     readonly rowClick: _angular_core.OutputEmitterRef<T>;
@@ -1970,7 +1997,7 @@ declare class FoldDataTableComponent<T> {
     onRowFocus(row: T, index: number): void;
     onRowKeydown(event: KeyboardEvent, row: T): void;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<FoldDataTableComponent<any>, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<FoldDataTableComponent<any>, "fold-data-table", never, { "columns": { "alias": "columns"; "required": true; "isSignal": true; }; "rows": { "alias": "rows"; "required": true; "isSignal": true; }; "rowKey": { "alias": "rowKey"; "required": false; "isSignal": true; }; "rowTone": { "alias": "rowTone"; "required": false; "isSignal": true; }; "sort": { "alias": "sort"; "required": false; "isSignal": true; }; "empty": { "alias": "empty"; "required": false; "isSignal": true; }; "loading": { "alias": "loading"; "required": false; "isSignal": true; }; "caption": { "alias": "caption"; "required": false; "isSignal": true; }; "clickable": { "alias": "clickable"; "required": false; "isSignal": true; }; "zebra": { "alias": "zebra"; "required": false; "isSignal": true; }; "hover": { "alias": "hover"; "required": false; "isSignal": true; }; "mobileLayout": { "alias": "mobileLayout"; "required": false; "isSignal": true; }; "density": { "alias": "density"; "required": false; "isSignal": true; }; "stickyFirst": { "alias": "stickyFirst"; "required": false; "isSignal": true; }; "selectable": { "alias": "selectable"; "required": false; "isSignal": true; }; "selected": { "alias": "selected"; "required": false; "isSignal": true; }; "selectionLabel": { "alias": "selectionLabel"; "required": false; "isSignal": true; }; "labels": { "alias": "labels"; "required": false; "isSignal": true; }; "toolbarSurface": { "alias": "toolbarSurface"; "required": false; "isSignal": true; }; }, { "selectionChange": "selectionChange"; "sortChange": "sortChange"; "rowClick": "rowClick"; }, ["cells", "rowCard"], ["[foldToolbar]"], true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<FoldDataTableComponent<any>, "fold-data-table", never, { "columns": { "alias": "columns"; "required": true; "isSignal": true; }; "rows": { "alias": "rows"; "required": true; "isSignal": true; }; "rowKey": { "alias": "rowKey"; "required": false; "isSignal": true; }; "rowTone": { "alias": "rowTone"; "required": false; "isSignal": true; }; "sort": { "alias": "sort"; "required": false; "isSignal": true; }; "empty": { "alias": "empty"; "required": false; "isSignal": true; }; "loading": { "alias": "loading"; "required": false; "isSignal": true; }; "caption": { "alias": "caption"; "required": false; "isSignal": true; }; "clickable": { "alias": "clickable"; "required": false; "isSignal": true; }; "zebra": { "alias": "zebra"; "required": false; "isSignal": true; }; "hover": { "alias": "hover"; "required": false; "isSignal": true; }; "mobileLayout": { "alias": "mobileLayout"; "required": false; "isSignal": true; }; "density": { "alias": "density"; "required": false; "isSignal": true; }; "stickyFirst": { "alias": "stickyFirst"; "required": false; "isSignal": true; }; "selectable": { "alias": "selectable"; "required": false; "isSignal": true; }; "selected": { "alias": "selected"; "required": false; "isSignal": true; }; "selectionLabel": { "alias": "selectionLabel"; "required": false; "isSignal": true; }; "labels": { "alias": "labels"; "required": false; "isSignal": true; }; "toolbarSurface": { "alias": "toolbarSurface"; "required": false; "isSignal": true; }; }, { "selected": "selectedChange"; "sortChange": "sortChange"; "rowClick": "rowClick"; }, ["cells", "rowCard"], ["[foldToolbar]"], true, never>;
 }
 
 /**
@@ -2152,7 +2179,7 @@ type FoldTextToken = (typeof FOLD_TEXT_TOKENS)[number];
 declare const FOLD_ICON_SIZE_TOKENS: readonly ["xs", "sm", "md", "lg", "xl"];
 type FoldIconSizeToken = (typeof FOLD_ICON_SIZE_TOKENS)[number];
 /** Space (gap / padding / margin) scale. */
-declare const FOLD_SPACE_TOKENS: readonly ["xs", "sm", "md", "lg", "xl"];
+declare const FOLD_SPACE_TOKENS: readonly ["xs", "sm", "md", "lg", "xl", "2xl", "3xl", "4xl", "5xl"];
 type FoldSpaceToken = (typeof FOLD_SPACE_TOKENS)[number];
 /** Motion scale — `transition` shorthands (duration + easing). */
 declare const FOLD_MOTION_TOKENS: readonly ["fast", "base", "slow"];
@@ -4187,12 +4214,14 @@ declare class FoldPageTitleDirective {
  * given**. It does *not* cap the column — narrowing a block to a readable measure
  * is the content's job (wrap that block in your own max-width container), never
  * the page scaffold's. The *horizontal* gutter is a single token,
- * `--fold-page-gutter` (default `32px`) — retune it per page/theme, or set it to
- * `0` for a bleeding dashboard. A {@link FoldPageSectionComponent} with `bleed`
- * cancels exactly that token to span the page edge-to-edge (a full-width band
- * amid padded content), so the two never desync — including on a responsive gutter.
- * The *vertical* rhythm between stacked elements is its own token,
- * `--fold-page-gap` (default `32px`), retunable the same way.
+ * `--fold-page-gutter` (fluid default `clamp(1rem, 4vw, 2rem)` — 16→32px) —
+ * retune it per page/theme, or set it to `0` for a bleeding dashboard. A
+ * {@link FoldPageSectionComponent} with `bleed` cancels exactly that token to
+ * span the page edge-to-edge (a full-width band amid padded content), so the two
+ * never desync — including on the fluid gutter. The *vertical* rhythm between
+ * stacked elements is its own token, `--fold-page-gap` (fluid default
+ * `clamp(1.25rem, 3vw, 2rem)` — 20→32px, a gentler curve than the gutter),
+ * retunable the same way.
  *
  * Content projection:
  * - default slot → the page body (sections, cards, banners…).
@@ -4237,20 +4266,29 @@ declare class FoldPageLayoutComponent {
 
 /**
  * `<fold-page-section>` — a titled, semantic **`<section>`** grouping of page
- * content inside a {@link FoldPageLayoutComponent}: an eyebrow `title` + optional
+ * content inside a {@link FoldPageLayoutComponent}: a `title` + optional
  * `description`, a right-aligned actions slot, and the content below.
  *
- * **It is structure, not a box.** The title is a real heading and the region is
- * a `<section>` named by that heading (`aria-labelledby`) — so a page reads as
- * an outline to assistive tech, and the DOM is self-documenting. It paints
- * nothing: transparent, no border, no radius. For a **visual box**, wrap the
- * content in a {@link FoldCardComponent} — the two are orthogonal and compose (a
- * section can hold a card; a card never needs to know about the page).
+ * **It is structure, not a box.** The `title` renders a real **`<h2>`** (a
+ * genuine section heading under the page's `<h1>`, not a decorative eyebrow) and
+ * the region is a `<section>` named by it (`aria-labelledby`) — so a page reads
+ * as an outline to assistive tech. Set `headingLevel` to correct the `aria-level`
+ * where a section nests deeper. It paints nothing: transparent, no border, no
+ * radius. For a **visual box**, wrap the content in a {@link FoldCardComponent} —
+ * the two are orthogonal and compose (a section can hold a card; a card never
+ * needs to know about the page).
  *
  * Content projection:
  * - default slot → the section content.
- * - `[sectionActions]` → the right-aligned header slot (re-projected into the
- *   heading row).
+ * - `[sectionActions]` → the right-aligned header slot, beside the `title`.
+ * - `[sectionHeader]` → a **bespoke** header, used *instead of* `title` when the
+ *   default `<h2>` isn't enough (e.g. project a {@link FoldElementTitleComponent}
+ *   with an icon tile + subtitle). The projected header owns its own heading
+ *   semantics.
+ *
+ * The section's vertical rhythm — the head↔body gap, and the `stack` body's
+ * item gap — is a single token, `--fold-page-section-gap` (default the `lg`
+ * space); retune it per section or theme.
  *
  * Two orthogonal helpers, both independent of the title:
  * - `stack` — lay the body out as an evenly-spaced vertical stack (form fields).
@@ -4268,6 +4306,12 @@ declare class FoldPageLayoutComponent {
  *   …
  * </fold-page-section>
  *
+ * <!-- bespoke header instead of the default h2 -->
+ * <fold-page-section>
+ *   <fold-element-title sectionHeader variant="title" icon="company" title="Contexte" />
+ *   …
+ * </fold-page-section>
+ *
  * <!-- need a box? compose with fold-card -->
  * <fold-page-section title="Documents">
  *   <fold-card surface="sunken">…</fold-card>
@@ -4281,6 +4325,9 @@ declare class FoldPageSectionComponent {
     readonly title: _angular_core.InputSignal<string | undefined>;
     /** An optional leading icon beside the title. */
     readonly icon: _angular_core.InputSignal<FoldIconName | undefined>;
+    /** Tint of the leading icon — forwarded to `fold-icon`'s `tone`. Defaults to
+     *  `secondary` (a muted ink, a step below the title). */
+    readonly iconTone: _angular_core.InputSignal<FoldIconTone>;
     /** A one-line description under the title. */
     readonly description: _angular_core.InputSignal<string | undefined>;
     /** Heading depth exposed to assistive tech (`aria-level`) — set it so sections
@@ -4297,7 +4344,7 @@ declare class FoldPageSectionComponent {
      *  `aria-labelledby` (only when there's a title). */
     protected readonly headingId: string;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<FoldPageSectionComponent, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<FoldPageSectionComponent, "fold-page-section", never, { "title": { "alias": "title"; "required": false; "isSignal": true; }; "icon": { "alias": "icon"; "required": false; "isSignal": true; }; "description": { "alias": "description"; "required": false; "isSignal": true; }; "headingLevel": { "alias": "headingLevel"; "required": false; "isSignal": true; }; "stack": { "alias": "stack"; "required": false; "isSignal": true; }; "bleed": { "alias": "bleed"; "required": false; "isSignal": true; }; }, {}, never, ["[sectionActions]", "*"], true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<FoldPageSectionComponent, "fold-page-section", never, { "title": { "alias": "title"; "required": false; "isSignal": true; }; "icon": { "alias": "icon"; "required": false; "isSignal": true; }; "iconTone": { "alias": "iconTone"; "required": false; "isSignal": true; }; "description": { "alias": "description"; "required": false; "isSignal": true; }; "headingLevel": { "alias": "headingLevel"; "required": false; "isSignal": true; }; "stack": { "alias": "stack"; "required": false; "isSignal": true; }; "bleed": { "alias": "bleed"; "required": false; "isSignal": true; }; }, {}, never, ["[sectionActions]", "[sectionHeader]", "*"], true, never>;
 }
 
 /**
@@ -4432,10 +4479,17 @@ declare class FoldPaginatorComponent {
     readonly currentPage: _angular_core.InputSignal<number>;
     /** Total number of items across all pages (drives `totalPages` + range label). */
     readonly totalItems: _angular_core.InputSignal<number>;
-    /** Number of items per page. Must be > 0. */
-    readonly pageSize: _angular_core.InputSignal<number>;
+    /**
+     * Number of items per page (must be > 0). Optional: when omitted, the first
+     * of {@link pageSizeOptions} is used, so the common case only needs
+     * `currentPage` + `totalItems`. Everything visible derives from the effective
+     * size, so a control-it-later parent stays consistent.
+     */
+    readonly pageSize: _angular_core.InputSignal<number | undefined>;
     /** Selectable page sizes. Set `[]` to hide the size selector entirely. */
     readonly pageSizeOptions: _angular_core.InputSignal<readonly number[]>;
+    /** The size actually in effect: the `pageSize` input, else the first option. */
+    readonly effectivePageSize: _angular_core.Signal<number>;
     /**
      * How many page buttons to render on each side of the current page
      * between the first/last anchors. Example with `siblingCount: 1`:
@@ -4488,11 +4542,11 @@ declare class FoldPaginatorComponent {
     next(): void;
     onPageSizeChange(raw: string): void;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<FoldPaginatorComponent, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<FoldPaginatorComponent, "fold-paginator", never, { "currentPage": { "alias": "currentPage"; "required": true; "isSignal": true; }; "totalItems": { "alias": "totalItems"; "required": true; "isSignal": true; }; "pageSize": { "alias": "pageSize"; "required": true; "isSignal": true; }; "pageSizeOptions": { "alias": "pageSizeOptions"; "required": false; "isSignal": true; }; "siblingCount": { "alias": "siblingCount"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "labels": { "alias": "labels"; "required": false; "isSignal": true; }; }, { "pageChange": "pageChange"; "pageSizeChange": "pageSizeChange"; }, never, never, true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<FoldPaginatorComponent, "fold-paginator", never, { "currentPage": { "alias": "currentPage"; "required": true; "isSignal": true; }; "totalItems": { "alias": "totalItems"; "required": true; "isSignal": true; }; "pageSize": { "alias": "pageSize"; "required": false; "isSignal": true; }; "pageSizeOptions": { "alias": "pageSizeOptions"; "required": false; "isSignal": true; }; "siblingCount": { "alias": "siblingCount"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "labels": { "alias": "labels"; "required": false; "isSignal": true; }; }, { "pageChange": "pageChange"; "pageSizeChange": "pageSizeChange"; }, never, never, true, never>;
 }
 
 type FoldViewNavItem = {
-    /** Unique key — identifies the item and is emitted by `activeChange`. */
+    /** Unique key — identifies the item; a button item writes it to `activeKey`. */
     key: string;
     /** Display label. */
     label: string;
@@ -4517,9 +4571,9 @@ type FoldViewNavItem = {
  * *go somewhere*. Give each item a `link` (or `href`) and it renders a real
  * `<a>` — so cmd/middle-click opens a new tab, the URL is a deep link, and the
  * active item is driven automatically by `routerLinkActive` +
- * `aria-current="page"`. Without a link an item is a `<button>` that emits
- * `activeChange` and reads its active state from `activeKey` (view switching
- * with no route).
+ * `aria-current="page"`. Without a link an item is a `<button>` that drives the
+ * `activeKey` **two-way model** — bind `[(activeKey)]` for view switching with
+ * no route.
  *
  * **Navigation, not the tabs widget.** Reach for this when a tab routes / switches
  * views. When tabs toggle **layered panels in place** (same URL), use
@@ -4546,10 +4600,12 @@ declare class FoldViewNavComponent {
     /** The items to render, in order. */
     readonly items: _angular_core.InputSignal<FoldViewNavItem[]>;
     /**
-     * The active item's `key` — for **button** items (no `link`). Link items ignore
-     * it: their active state comes from the URL via `routerLinkActive`.
+     * The active item's `key`, as a **two-way model** — for **button** items (no
+     * `link`). Bind `[(activeKey)]` and a click writes the new key back; there is
+     * no separate change output (the model is the one way). Link items ignore it:
+     * their active state comes from the URL via `routerLinkActive`.
      */
-    readonly activeKey: _angular_core.InputSignal<string>;
+    readonly activeKey: _angular_core.ModelSignal<string>;
     /** How the active item reads: accent underline, or accent fill. */
     readonly activeStyle: _angular_core.InputSignal<"fill" | "underline">;
     /**
@@ -4582,14 +4638,12 @@ declare class FoldViewNavComponent {
      * `surface` (a filled bar that carries its own rail background).
      */
     readonly background: _angular_core.InputSignal<"transparent" | "surface">;
-    /** Emits the `key` of a clicked **button** item (link items just navigate). */
-    readonly activeChange: _angular_core.OutputEmitterRef<string>;
     /** The nearest layout, if any — lets `direction="auto"` follow it. */
     private readonly layout;
     /** `direction` with `auto` resolved against the wrapping layout. */
     protected readonly resolvedDirection: _angular_core.Signal<"vertical" | "horizontal">;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<FoldViewNavComponent, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<FoldViewNavComponent, "fold-view-nav", never, { "items": { "alias": "items"; "required": true; "isSignal": true; }; "activeKey": { "alias": "activeKey"; "required": false; "isSignal": true; }; "activeStyle": { "alias": "activeStyle"; "required": false; "isSignal": true; }; "direction": { "alias": "direction"; "required": false; "isSignal": true; }; "size": { "alias": "size"; "required": false; "isSignal": true; }; "collapsed": { "alias": "collapsed"; "required": false; "isSignal": true; }; "background": { "alias": "background"; "required": false; "isSignal": true; }; }, { "activeChange": "activeChange"; }, never, never, true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<FoldViewNavComponent, "fold-view-nav", never, { "items": { "alias": "items"; "required": true; "isSignal": true; }; "activeKey": { "alias": "activeKey"; "required": false; "isSignal": true; }; "activeStyle": { "alias": "activeStyle"; "required": false; "isSignal": true; }; "direction": { "alias": "direction"; "required": false; "isSignal": true; }; "size": { "alias": "size"; "required": false; "isSignal": true; }; "collapsed": { "alias": "collapsed"; "required": false; "isSignal": true; }; "background": { "alias": "background"; "required": false; "isSignal": true; }; }, { "activeKey": "activeKeyChange"; }, never, never, true, never>;
 }
 
 /** A tab in a {@link FoldTabsComponent} bar. */
@@ -4629,15 +4683,12 @@ interface FoldTabsContext {
  * difference is **semantics** — use `fold-tabs` for in-page panel switching, and
  * `fold-view-nav` when the tabs actually navigate (route) between views.
  *
+ * `activeKey` is a two-way model — the single way to drive selection. Bind
+ * `[(activeKey)]` and the bar writes the new key back on click / arrow keys:
+ *
  * ```html
  * <fold-nav-layout>
- *   <fold-tabs
- *     nav
- *     #t="foldTabs"
- *     [tabs]="tabs"
- *     [activeKey]="tab()"
- *     (tabChange)="tab.set($event)"
- *   />
+ *   <fold-tabs nav #t="foldTabs" [tabs]="tabs" [(activeKey)]="tab" />
  *   <fold-tab-panel [tabs]="t" key="overview">…</fold-tab-panel>
  *   <fold-tab-panel [tabs]="t" key="settings">…</fold-tab-panel>
  * </fold-nav-layout>
@@ -4651,8 +4702,14 @@ interface FoldTabsContext {
 declare class FoldTabsComponent implements FoldTabsContext {
     /** The tabs to render, in order. */
     readonly tabs: _angular_core.InputSignal<FoldTabItem[]>;
-    /** The `key` of the active tab (the shown panel). */
-    readonly activeKey: _angular_core.InputSignal<string>;
+    /**
+     * The `key` of the active tab (the shown panel), as a **two-way model** — the
+     * single source of selection. Bind `[(activeKey)]` and the bar writes the new
+     * key back on click / arrow keys; to *react* to a change without a writeback,
+     * listen to the model's `(activeKeyChange)`. There is no separate change
+     * output — the model is the one way.
+     */
+    readonly activeKey: _angular_core.ModelSignal<string>;
     /** How the active tab reads: accent underline, or accent fill. */
     readonly activeStyle: _angular_core.InputSignal<"fill" | "underline">;
     /**
@@ -4666,8 +4723,6 @@ declare class FoldTabsComponent implements FoldTabsContext {
     readonly collapsed: _angular_core.InputSignalWithTransform<boolean, unknown>;
     /** `surface` (filled bar, default) or `transparent`. */
     readonly background: _angular_core.InputSignal<"transparent" | "surface">;
-    /** Emits the newly-selected tab's `key`. */
-    readonly tabChange: _angular_core.OutputEmitterRef<string>;
     /** The nearest layout, if any — lets `direction="auto"` follow it. */
     private readonly layout;
     /** `direction` with `auto` resolved against the wrapping layout. */
@@ -4678,6 +4733,9 @@ declare class FoldTabsComponent implements FoldTabsContext {
     tabId(key: string): string;
     panelId(key: string): string;
     protected select(key: string): void;
+    /** Records a new selection by writing the `activeKey` model — the two-way
+     *  binding (or its `activeKeyChange`) carries it to the parent. */
+    private commit;
     /**
      * Roving-tabindex keyboard model (APG Tabs, automatic activation): arrows move
      * — and select — the adjacent tab, `Home`/`End` the ends. Both axes work, so
@@ -4686,7 +4744,7 @@ declare class FoldTabsComponent implements FoldTabsContext {
      */
     protected onKeydown(event: KeyboardEvent): void;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<FoldTabsComponent, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<FoldTabsComponent, "fold-tabs", ["foldTabs"], { "tabs": { "alias": "tabs"; "required": true; "isSignal": true; }; "activeKey": { "alias": "activeKey"; "required": true; "isSignal": true; }; "activeStyle": { "alias": "activeStyle"; "required": false; "isSignal": true; }; "direction": { "alias": "direction"; "required": false; "isSignal": true; }; "size": { "alias": "size"; "required": false; "isSignal": true; }; "collapsed": { "alias": "collapsed"; "required": false; "isSignal": true; }; "background": { "alias": "background"; "required": false; "isSignal": true; }; }, { "tabChange": "tabChange"; }, never, never, true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<FoldTabsComponent, "fold-tabs", ["foldTabs"], { "tabs": { "alias": "tabs"; "required": true; "isSignal": true; }; "activeKey": { "alias": "activeKey"; "required": true; "isSignal": true; }; "activeStyle": { "alias": "activeStyle"; "required": false; "isSignal": true; }; "direction": { "alias": "direction"; "required": false; "isSignal": true; }; "size": { "alias": "size"; "required": false; "isSignal": true; }; "collapsed": { "alias": "collapsed"; "required": false; "isSignal": true; }; "background": { "alias": "background"; "required": false; "isSignal": true; }; }, { "activeKey": "activeKeyChange"; }, never, never, true, never>;
 }
 
 /**
@@ -4700,7 +4758,7 @@ declare class FoldTabsComponent implements FoldTabsContext {
  * content) and still coordinate.
  *
  * ```html
- * <fold-tabs #t="foldTabs" [tabs]="tabs" [activeKey]="tab()" (tabChange)="tab.set($event)" />
+ * <fold-tabs #t="foldTabs" [tabs]="tabs" [(activeKey)]="tab" />
  * <fold-tab-panel [tabs]="t" key="overview">…</fold-tab-panel>
  * ```
  *
@@ -5457,5 +5515,5 @@ declare class FoldPaletteRegistry {
 }
 
 export { FOLD_AUTO_PALETTES, FOLD_BLUR_TOKENS, FOLD_BUILTIN_ICONS, FOLD_DATA_TABLE_DEFAULT_LABELS, FOLD_DATA_TABLE_LABELS, FOLD_INLINE_CONFIRM_DEFAULT_LABELS, FOLD_INLINE_CONFIRM_LABELS, FOLD_MOTION_TOKENS, FOLD_PAGINATOR_DEFAULT_LABELS, FOLD_PAGINATOR_LABELS, FOLD_PALETTE_DEFAULT, FOLD_PANEL_CLOSE_LABEL, FOLD_RADIUS_TOKENS, FOLD_SEMANTIC_COLOR_TOKENS, FOLD_SHADOW_TOKENS, FOLD_SPACE_TOKENS, FOLD_TEXT_TOKENS, FOLD_TOAST_CONFIG, FoldAppShellComponent, FoldAsideLayoutComponent, FoldAvatarComponent, FoldAvatarDetailComponent, FoldAvatarListComponent, FoldBadgeComponent, FoldButtonComponent, FoldButtonIconComponent, FoldCalloutComponent, FoldCardComponent, FoldCheckboxComponent, FoldChoiceRowComponent, FoldContextCardComponent, FoldDataTableCellDirective, FoldDataTableComponent, FoldDataTableRowCardDirective, FoldDisclosureComponent, FoldDropdownComponent, FoldDropdownItemComponent, FoldElementTitleComponent, FoldElevatedDirective, FoldEmptyStateComponent, FoldFieldComponent, FoldFieldIdDirective, FoldFieldListComponent, FoldFileDropzoneComponent, FoldHeroCardComponent, FoldHeroSectionComponent, FoldIconComponent, FoldIconRegistry, FoldIdService, FoldInlineConfirmComponent, FoldInputComponent, FoldLinkComponent, FoldListboxComponent, FoldLoadingStateComponent, FoldMenuComponent, FoldMenuItemComponent, FoldMenuSectionComponent, FoldMenuSeparatorComponent, FoldMultiselectComponent, FoldNavLauncherComponent, FoldNavLayoutComponent, FoldNavTileComponent, FoldNumberInputComponent, FoldOptionComponent, FoldPageLayoutComponent, FoldPageSectionComponent, FoldPageTitleDirective, FoldPaginatorComponent, FoldPaletteRegistry, FoldPanelComponentOutletDirective, FoldPanelHeaderComponent, FoldPanelHostComponent, FoldPanelHostService, FoldPanelRef, FoldPanelToggle, FoldPasswordFieldComponent, FoldPopoverComponent, FoldPopoverTriggerDirective, FoldRangeSliderComponent, FoldRepeatPressDirective, FoldSearchComponent, FoldSelectComponent, FoldSliderComponent, FoldSpinnerComponent, FoldStatusBadgeComponent, FoldStickyColumnDirective, FoldSurfaceDirective, FoldTabPanelComponent, FoldTabsComponent, FoldTimelineComponent, FoldToastComponent, FoldToastContainerComponent, FoldToastService, FoldToggleIconComponent, FoldViewNavComponent, FoldViewToggleComponent, autoUpdate, computePlacement, foldBlurVar, foldCardBandChrome, foldColorProperty, foldColorVar, foldDefaultPasswordRules, foldHashSeed, foldMotionVar, foldRadiusVar, foldRegexRule, foldResolvePalette, foldShadowVar, foldSpaceVar, foldTextVar, observeElementWidth, provideFoldDataTableLabels, provideFoldIcons, provideFoldInlineConfirmLabels, provideFoldPaginatorLabels, provideFoldPalette, provideFoldPanelLabels, provideFoldToasts };
-export type { FoldAutoPaletteName, FoldAvatarListItem, FoldAvatarRing, FoldAvatarRingStyle, FoldAvatarVariant, FoldBadgeVariant, FoldBlurToken, FoldBuiltinIconName, FoldButtonEmphasis, FoldButtonIconShape, FoldButtonIconSize, FoldButtonIconTone, FoldButtonIntent, FoldButtonShape, FoldButtonSize, FoldCalloutAppearance, FoldCalloutVariant, FoldCardBandChrome, FoldCardBandChromeInput, FoldChoiceOption, FoldComponentPanelDescriptor, FoldDataTableLabels, FoldIconName, FoldIconSet, FoldIconSize, FoldInlineConfirmLabels, FoldMenuItemBadgeTone, FoldMenuLevel, FoldMenuTint, FoldMenuTogglePlacement, FoldMotionToken, FoldNumberControls, FoldNumberSpinner, FoldPageItem, FoldPaginatorLabels, FoldPaletteInput, FoldPanelConfig, FoldPanelContent, FoldPanelDescriptor, FoldPanelHandle, FoldPanelLabels, FoldPanelSide, FoldPasswordRule, FoldPlacementInput, FoldPlacementResult, FoldPopoverAlign, FoldPopoverPlacement, FoldPopoverSide, FoldRadiusToken, FoldRangeValue, FoldRect, FoldSelectOption, FoldSemanticColorToken, FoldShadowToken, FoldSpaceToken, FoldSpinnerSize, FoldStickyColumnAnchor, FoldSurfaceName, FoldTabItem, FoldTableColumn, FoldTableEmpty, FoldTableSort, FoldTableSortDir, FoldTableTone, FoldTabsContext, FoldTemplatePanelDescriptor, FoldTextToken, FoldTimelineDatePlacement, FoldTimelineNode, FoldToast, FoldToastConfig, FoldToastVariant, FoldViewNavItem, FoldViewToggleOption };
+export type { FoldAutoPaletteName, FoldAvatarListItem, FoldAvatarRing, FoldAvatarRingStyle, FoldAvatarVariant, FoldBadgeVariant, FoldBlurToken, FoldBuiltinIconName, FoldButtonEmphasis, FoldButtonIconShape, FoldButtonIconSize, FoldButtonIconTone, FoldButtonIntent, FoldButtonShape, FoldButtonSize, FoldCalloutAppearance, FoldCalloutVariant, FoldCardBandChrome, FoldCardBandChromeInput, FoldChoiceOption, FoldComponentPanelDescriptor, FoldDataTableLabels, FoldIconName, FoldIconSet, FoldIconSize, FoldIconTone, FoldInlineConfirmLabels, FoldMenuItemBadgeTone, FoldMenuLevel, FoldMenuTint, FoldMenuTogglePlacement, FoldMotionToken, FoldNumberControls, FoldNumberSpinner, FoldPageItem, FoldPaginatorLabels, FoldPaletteInput, FoldPanelConfig, FoldPanelContent, FoldPanelDescriptor, FoldPanelHandle, FoldPanelLabels, FoldPanelSide, FoldPasswordRule, FoldPlacementInput, FoldPlacementResult, FoldPopoverAlign, FoldPopoverPlacement, FoldPopoverSide, FoldRadiusToken, FoldRangeValue, FoldRect, FoldSelectOption, FoldSemanticColorToken, FoldShadowToken, FoldSpaceToken, FoldSpinnerSize, FoldStickyColumnAnchor, FoldSurfaceName, FoldTabItem, FoldTableColumn, FoldTableEmpty, FoldTableSort, FoldTableSortDir, FoldTableTone, FoldTabsContext, FoldTemplatePanelDescriptor, FoldTextToken, FoldTimelineDatePlacement, FoldTimelineNode, FoldToast, FoldToastConfig, FoldToastVariant, FoldViewNavItem, FoldViewToggleOption };
 //# sourceMappingURL=fold-ng.d.ts.map