@kubex/zinc 1.1.92 → 1.1.95

package/dist/zn.d.ts

@@ -1316,6 +1316,7 @@ declare module "components/toggle/toggle.component" {
      *
      * @csspart base - The component's base wrapper containing the toggle switch.
      * @csspart control - The toggle switch control (the circular button that slides).
+     * @csspart label - The toggle's label.
      * @csspart description - The container that wraps the toggle's description.
      *
      * @cssproperty --zn-toggle-margin - The margin around the toggle switch. Defaults to `8px 0`.
@@ -1900,6 +1901,14 @@ declare module "components/slash-menu/slash-menu-items" {
     export function parseSlashItems(value: string | null | undefined): SlashMenuItem[];
     /** Filters and ranks items against a query. An empty query keeps every item in its declared order. */
     export function filterSlashItems(items: SlashMenuItem[], query: string): SlashMenuItem[];
+    /** The identity an item is remembered by in a menu's recently used list. */
+    export function slashItemKey(item: SlashMenuItem): string;
+    /** The keys of the items most recently chosen from the menu stored under `key`, newest first. */
+    export function readRecentSlashItems(key: string): string[];
+    /** Moves an item to the front of the recently used list stored under `key`, and returns the list. */
+    export function recordRecentSlashItem(key: string, item: SlashMenuItem): string[];
+    /** Forgets the recently used items stored under `key`. */
+    export function clearRecentSlashItems(key: string): void;
 }
 declare module "utilities/caret-position" {
     export interface CaretCoordinates {
@@ -1926,7 +1935,7 @@ declare module "utilities/caret-position" {
 declare module "components/slash-menu/slash-menu.component" {
     import ZincElement from "internal/zinc-element";
     import ZnIcon from "components/icon/index";
-    import type { CSSResultGroup, PropertyValues } from 'lit';
+    import type { CSSResultGroup, PropertyValues, TemplateResult } from 'lit';
     import type { Placement, VirtualElement } from '@floating-ui/dom';
     import type { SlashMenuItem } from "components/slash-menu/slash-menu-items";
     export const SLASH_ITEM_SELECT = "zn-slash-item-select";
@@ -1942,12 +1951,19 @@ declare module "components/slash-menu/slash-menu.component" {
      *  component driving the menu (e.g. `zn-textarea`) re-emits it as `zn-slash-select`.
      *
      * @csspart panel - The floating panel that holds the list.
-     * @csspart heading - The panel's heading.
+     * @csspart list - The scrolling list of items.
      * @csspart item - An item in the list.
+     * @csspart icon - The chip holding an item's icon.
      * @csspart group-heading - A group heading between items.
+     * @csspart divider - The rule closing the recently used section, when the items below it have no heading of their own.
      * @csspart footer - The truncation footer, shown when not every match fits.
+     * @csspart hints - The pinned footer of keyboard hints.
+     * @csspart hint - A single keyboard hint within the footer.
+     * @csspart hint-key - The key shown against a hint.
      *
      * @cssproperty --slash-menu-width - The width of the panel.
+     * @cssproperty --slash-menu-border-radius - The corner radius of the panel.
+     * @cssproperty --slash-menu-item-border-radius - The corner radius of the items and their icon chips.
      * @cssproperty --slash-menu-max-height - The maximum height of the panel before it scrolls.
      */
     export default class ZnSlashMenu extends ZincElement {
@@ -1956,6 +1972,7 @@ declare module "components/slash-menu/slash-menu.component" {
             'zn-icon': typeof ZnIcon;
         };
         private panel;
+        private list;
         private stopAutoUpdate?;
         /** Whether the menu is showing. */
         open: boolean;
@@ -1963,7 +1980,7 @@ declare module "components/slash-menu/slash-menu.component" {
         items: SlashMenuItem[];
         /** The query the items were matched against, shown in the heading. */
         query: string;
-        /** The heading shown when there is no query. */
+        /** The name the list is announced by when there is no query. */
         heading: string;
         /** Shown in place of the list when there are no items. */
         emptyText: string;
@@ -1971,6 +1988,18 @@ declare module "components/slash-menu/slash-menu.component" {
         maxItems: number;
         /** Hides the insertion key (the item's value) normally shown against each item. */
         hideKeys: boolean;
+        /** Hides the pinned footer of keyboard hints. */
+        hideHints: boolean;
+        /**
+         * Remembers the items chosen here and lists the most recent of them first, under their own heading.
+         * The key scopes the list to where the menu is used, so each place keeps its own history in
+         * `localStorage`. Leave unset to offer no recently used section.
+         */
+        recentKey: string;
+        /** The most recently used items to list. */
+        maxRecent: number;
+        /** The heading shown above the recently used items. */
+        recentHeading: string;
         /** The element or caret rect the panel is positioned against. */
         anchor: Element | VirtualElement | null;
         /** The preferred placement of the panel. */
@@ -1978,11 +2007,22 @@ declare module "components/slash-menu/slash-menu.component" {
         /** The gap between the caret and the panel. */
         distance: number;
         private activeIndex;
+        private recentKeys;
+        /** How many recently used items the last update listed, to spot the list appearing or reordering. */
+        private recentCount;
+        private get listItems();
+        /**
+         * The remembered items that are in the current list, newest first. Only offered without a query —
+         * once the user is searching, the ranked matches are the better answer.
+         */
+        private get recentItems();
         private get visibleItems();
         /** The item that Enter would insert. */
         get activeItem(): SlashMenuItem | undefined;
         show(): void;
         hide(): void;
+        /** Forgets the items remembered under `recent-key`. */
+        clearRecent(): void;
         /** Sets the active item by index, wrapping at both ends and skipping disabled items. */
         setActiveIndex(index: number): void;
         /** Moves the active item by `delta` places. */
@@ -2005,7 +2045,9 @@ declare module "components/slash-menu/slash-menu.component" {
         protected updated(changed: PropertyValues): void;
         private renderItem;
         private renderItems;
-        render(): import("lit-html").TemplateResult<1>;
+        private renderHint;
+        private renderHints;
+        render(): TemplateResult<1>;
     }
 }
 declare module "components/slash-menu/slash-menu-controller" {
@@ -2079,10 +2121,22 @@ declare module "components/slash-menu/slash-menu-controller" {
         private replace;
     }
 }
+declare module "components/slash-menu/index" {
+    import ZnSlashMenu from "components/slash-menu/slash-menu.component";
+    export * from "components/slash-menu/slash-menu.component";
+    export * from "components/slash-menu/slash-menu-controller";
+    export * from "components/slash-menu/slash-menu-items";
+    export default ZnSlashMenu;
+    global {
+        interface HTMLElementTagNameMap {
+            'zn-slash-menu': ZnSlashMenu;
+        }
+    }
+}
 declare module "components/slash-item/slash-item.component" {
     import ZincElement from "internal/zinc-element";
     import type { CSSResultGroup } from 'lit';
-    import type { SlashMenuItem } from "components/slash-menu/slash-menu-items";
+    import type { SlashMenuItem } from "components/slash-menu/index";
     /**
      * @summary Declares a single insertion for a slash menu. Renders nothing itself — it describes an
      *  entry for the component it is slotted into, e.g. `<zn-textarea>`'s `slash-items` slot.
@@ -2131,18 +2185,6 @@ declare module "components/slash-item/index" {
         }
     }
 }
-declare module "components/slash-menu/index" {
-    import ZnSlashMenu from "components/slash-menu/slash-menu.component";
-    export * from "components/slash-menu/slash-menu.component";
-    export * from "components/slash-menu/slash-menu-controller";
-    export * from "components/slash-menu/slash-menu-items";
-    export default ZnSlashMenu;
-    global {
-        interface HTMLElementTagNameMap {
-            'zn-slash-menu': ZnSlashMenu;
-        }
-    }
-}
 declare module "components/input/input.component" {
     import { type SlashMenuItem } from "components/slash-menu/slash-menu-items";
     import ZincElement from "internal/zinc-element";
@@ -2336,10 +2378,15 @@ declare module "components/input/input.component" {
         slashPreset: string;
         /** The characters that open the slash menu. */
         slashTrigger: string;
-        /** The heading shown above the slash menu's items. */
+        /** The name the slash menu's list is announced by. */
         slashHeading: string;
         /** Hides the insertion keys normally shown against the slash menu's items. */
         slashHideKeys: boolean;
+        /**
+         * Lists the items most recently chosen here above the rest, remembered in `localStorage` under this
+         * key. Share a key between the fields that should share a history; leave unset to offer no such list.
+         */
+        slashRecentKey: string;
         /**
          * Resolves additional items each time the menu opens, for lists that come from elsewhere (e.g. an
          * API). Receives the current query and may return a promise. JavaScript only.
@@ -5232,10 +5279,12 @@ declare module "components/inline-edit/inline-edit.component" {
         slashPreset: string;
         /** The characters that open the slash menu. */
         slashTrigger: string;
-        /** The heading shown above the slash menu's items. */
+        /** The name the slash menu's list is announced by. */
         slashHeading: string;
         /** Hides the insertion keys normally shown against the slash menu's items. */
         slashHideKeys: boolean;
+        /** Lists the slash menu items most recently chosen here above the rest, remembered under this key. */
+        slashRecentKey: string;
         /** Resolves additional slash menu items each time the menu opens. JavaScript only. */
         slashItemsProvider?: (query: string) => SlashMenuItem[] | Promise<SlashMenuItem[]>;
         options: {
@@ -6679,10 +6728,15 @@ declare module "components/textarea/textarea.component" {
         slashPreset: string;
         /** The characters that open the slash menu. */
         slashTrigger: string;
-        /** The heading shown above the slash menu's items. */
+        /** The name the slash menu's list is announced by. */
         slashHeading: string;
         /** Hides the insertion keys normally shown against the slash menu's items. */
         slashHideKeys: boolean;
+        /**
+         * Lists the items most recently chosen here above the rest, remembered in `localStorage` under this
+         * key. Share a key between the fields that should share a history; leave unset to offer no such list.
+         */
+        slashRecentKey: string;
         /**
          * Resolves additional items each time the menu opens, for lists that come from elsewhere (e.g. an
          * API). Receives the current query and may return a promise. JavaScript only.
@@ -7149,7 +7203,7 @@ declare module "components/linked-select/linked-select.component" {
         [key: string]: string;
     }
     interface linkedSelectOptions {
-        [key: string]: linkedSelectOption[];
+        [key: string]: linkedSelectOption;
     }
     /**
      * @summary Short summary of the component's intended use.
@@ -7177,6 +7231,8 @@ declare module "components/linked-select/linked-select.component" {
         linkedSelect: string;
         cacheKey: string;
         label: string;
+        /** Automatically select the first option of the linked group when no value is set. */
+        selectFirst: boolean;
         input: ZnSelect;
         private linkedSelectElement;
         private readonly formControlController;
@@ -7193,6 +7249,8 @@ declare module "components/linked-select/linked-select.component" {
         handleLinkedSelectChange: () => void;
         handleChange(e: Event): void;
         handleSelectChange: (e: ZnSelectEvent) => void;
+        /** The options of the group the linked select currently points at. */
+        private currentOptions;
         render(): import("lit-html").TemplateResult<1>;
     }
 }
@@ -8719,10 +8777,12 @@ declare module "components/translations/translations.component" {
         slashPreset: string;
         /** The characters that open the slash menu. */
         slashTrigger: string;
-        /** The heading shown above the slash menu's items. */
+        /** The name the slash menu's list is announced by. */
         slashHeading: string;
         /** Hides the insertion keys normally shown against the slash menu's items. */
         slashHideKeys: boolean;
+        /** Lists the slash menu items most recently chosen here above the rest, remembered under this key. */
+        slashRecentKey: string;
         /** Resolves additional slash menu items each time the menu opens. JavaScript only. */
         slashItemsProvider?: (query: string) => SlashMenuItem[] | Promise<SlashMenuItem[]>;
         /** When true, hides the individual language navbar and defers language control to a parent zn-translation-group. */
@@ -9020,6 +9080,7 @@ declare module "components/priority-list/priority-list.component" {
      *
      * @cssproperty --zn-priority-list-item-gap - The gap between list items. Defaults to `var(--zn-spacing-2x-small)`.
      * @cssproperty --zn-priority-list-item-padding - The padding inside each item. Defaults to `var(--zn-spacing-small) var(--zn-spacing-medium)`.
+     * @cssproperty --zn-priority-list-actions-gap - The gap between an item's slotted actions. Defaults to `var(--zn-spacing-x-small)`.
      * @cssproperty --zn-priority-list-handle-color - The color of the drag handle. Defaults to `var(--zn-color-neutral-500)`.
      * @cssproperty --zn-priority-list-priority-color - The color of the priority number. Defaults to `var(--zn-color-neutral-600)`.
      */
@@ -9272,6 +9333,8 @@ declare module "components/remarkd-editor/remarkd-editor.component" {
      * @csspart raw - The full-document textarea shown in raw source mode.
      * @csspart slash-menu - The `zn-slash-menu` opened by typing "/" in an empty block.
      * @csspart image-controls - The caption / alignment / size panel shown when an image block is clicked.
+     * @csspart include - The chip rendered in place of an `include::` directive.
+     * @csspart include-picker - The inline Include picker opened from the toolbar or "/include".
      */
     export default class ZnRemarkdEditor extends ZincElement implements ZincFormControl {
         static styles: CSSResultGroup;
@@ -9281,6 +9344,7 @@ declare module "components/remarkd-editor/remarkd-editor.component" {
         private readonly formControlController;
         private readonly slashController;
         private editingDraft;
+        private includeRequest;
         private rawEntryValue;
         private suppressValueSync;
         private suppressBlurCommit;
@@ -9288,6 +9352,11 @@ declare module "components/remarkd-editor/remarkd-editor.component" {
         private slashMenuElement;
         private blocks;
         private editingIndex;
+        /**
+         * Lists the blocks most recently inserted here above the rest of the slash menu, remembered in
+         * `localStorage` under this key. Leave unset to offer no recently used section.
+         */
+        slashRecentKey: string;
         /** Renders the slash menu only once it has been needed. */
         private hasSlashMenu;
         private imagePickerIndex;
@@ -9296,6 +9365,9 @@ declare module "components/remarkd-editor/remarkd-editor.component" {
         private dragIndex;
         private editShell;
         private rawMode;
+        private includeOptions;
+        private includePickerIndex;
+        private includeQuery;
         private pendingDragHandle;
         private dragStartX;
         private dragStartY;
@@ -9314,6 +9386,12 @@ declare module "components/remarkd-editor/remarkd-editor.component" {
          * to `uploadUrl` and the returned `uploadPath` is embedded as the image URL.
          */
         attachmentUrl: string;
+        /**
+         * Endpoint listing the Includes this document may embed, as
+         * `{"items":[{id,title,description,scope,keywords,languages,url}]}`. Labels the
+         * chips rendered for `include::` directives and feeds the include picker.
+         */
+        includeUrl: string;
         /** Adds a toolbar toggle that swaps the block view for the full remarkd source. */
         allowRaw: boolean;
         /** Makes the editor required for form submission. */
@@ -9335,6 +9413,7 @@ declare module "components/remarkd-editor/remarkd-editor.component" {
         protected firstUpdated(_changedProperties: PropertyValues): void;
         disconnectedCallback(): void;
         handleValueChange(): void;
+        handleIncludeUrlChange(): void;
         /**
          * Splits remarkd source into blocks on blank lines, keeping fenced /
          * delimited containers (``` ==== !!!! .... ----) as single blocks.
@@ -9346,6 +9425,8 @@ declare module "components/remarkd-editor/remarkd-editor.component" {
         private handleRenderedClick;
         /** Parses a block that is purely an image (with optional caption/align lines). */
         private parseImageBlock;
+        /** Parses a block that is nothing but an include directive. */
+        private parseIncludeBlock;
         private serializeImageBlock;
         private toggleCheckbox;
         private startEdit;
@@ -9392,10 +9473,16 @@ declare module "components/remarkd-editor/remarkd-editor.component" {
         private createDragGhost;
         private moveDragGhost;
         private pickImage;
+        private pickInclude;
+        private closeIncludePicker;
+        private insertInclude;
         private closeImagePicker;
         private handleImagePicked;
         private insertImage;
         private uploadImage;
+        private hasIncludeBlock;
+        /** Fetches the include list once; every later caller shares the same promise. */
+        private loadIncludeOptions;
         private autosize;
         private toggleRawMode;
         private focusRaw;
@@ -9413,11 +9500,13 @@ declare module "components/remarkd-editor/remarkd-editor.component" {
         private commitRaw;
         private handleToolbarInsert;
         private renderImageControls;
+        private renderIncludeChip;
         private renderBlock;
         render(): import("lit-html").TemplateResult<1>;
         private renderRaw;
         /** The block views, with the inline image picker spliced in when active. */
         private renderBody;
+        private renderIncludePicker;
         private renderImagePicker;
     }
 }
@@ -10526,9 +10615,23 @@ declare module "components/page-builder/page.types" {
         label?: string;
         /** Section content, keyed by field name (the inspector's `name` attributes). */
         data: Record<string, unknown>;
-        /** Slot contents for container sections, sized to the type's `slots`. Empty slots are null. */
+        /** Container instances only: the editor-chosen layout. */
+        layout?: PageContainerLayout;
+        /** Container instances only: one ordered stack per cell, row-major. */
+        cells?: PageSection[][];
+        /**
+         * @deprecated The pre-cells fixed-slot shape. Read on load and migrated to
+         * `cells`; never written back.
+         */
         children?: (PageSection | null)[];
     }
+    /** A container instance's editor-chosen layout. */
+    export interface PageContainerLayout {
+        /** One weight per column; the array length IS the column count. */
+        widths: number[];
+        /** When true the builder offers a trailing empty row instead of a pinned cell count. */
+        grow: boolean;
+    }
     /** The complete serialisable state of a page. Order = render order. */
     export interface PageState {
         sections: PageSection[];
@@ -10554,16 +10657,48 @@ declare module "components/page-builder/page.types" {
         configTemplate?: HTMLTemplateElement;
         /** Programmatic inspector body — takes precedence over `configTemplate`. */
         renderConfig?: (section: PageSection, update: (data: Record<string, unknown>) => void) => TemplateResult;
+        /** Marks this type a container: its card renders a grid of cells on the canvas. */
+        container?: boolean;
+        /**
+         * Column weights a new instance of this container starts with. Stored as parsed, not
+         * guaranteed sanitised — route through `sanitiseWidths`/`defaultLayout` before use.
+         */
+        defaultWidths?: number[];
+        /** Whether a new instance of this container starts growable. */
+        defaultGrow?: boolean;
         /**
-         * Number of child slots this section offers on the canvas (a container tile);
-         * rendered as a 3-column grid. Containers cannot be placed inside other containers.
+         * @deprecated Use `container` with `columns`/`widths`. Read as a container of
+         * `DEFAULT_WIDTHS` columns with the cell count pinned to this number.
          */
         slots?: number;
-        /** Section type keys allowed in this container's slots. Omit to allow any non-container type. */
+        /**
+         * Section type keys allowed in this container's cells. On a `container` type,
+         * omitting it allows any type, subject to the nesting cap — that is how nesting
+         * is reachable without enumerating types. The deprecated `slots=` alias keeps the
+         * old rule instead: omitting it there allows any non-container type.
+         */
         accepts?: string[];
     }
-    /** A container section's slot contents, padded/truncated to the type's slot count. */
-    export function sectionChildren(section: PageSection, type: PageSectionType): (PageSection | null)[];
+    /** Beyond 6 columns a card is under ~170px on the 1024px canvas — unreadable. */
+    export const MAX_COLUMNS = 6;
+    /** A single weight beyond 12 makes the other columns unusably thin. */
+    export const MAX_WIDTH = 12;
+    /** Container nesting levels: a top-level container is 1, one inside a cell is 2. */
+    export const MAX_CONTAINER_LEVELS = 2;
+    /** Global section budget; also the sanity clamp on an incoming `cells` length. */
+    export const MAX_SECTIONS = 500;
+    /** What a bare `container` declaration seeds. */
+    export const DEFAULT_WIDTHS: readonly number[];
+    /** Container-ness is a property of the registered type, never of the instance. */
+    export function isContainer(type: PageSectionType | undefined): boolean;
+    /**
+     * Coerces a weights list into a usable one: each entry a whole number from 1 to
+     * MAX_WIDTH (anything unusable becomes 1), at most MAX_COLUMNS entries, falling
+     * back to DEFAULT_WIDTHS only when nothing usable remains.
+     */
+    export function sanitiseWidths(raw: unknown): number[];
+    /** The layout a newly placed instance of a container type starts with. */
+    export function defaultLayout(type: PageSectionType | undefined): PageContainerLayout;
     /** Drag-and-drop MIME carrying a section type id from the palette to the canvas. */
     export const PAGE_TYPE_MIME = "application/x-zn-page-type";
     /** Drag-and-drop MIME carrying a placed section's id when reordering. */
@@ -10571,9 +10706,89 @@ declare module "components/page-builder/page.types" {
     export function emptyPageState(): PageState;
     /** Unique-enough id for a new section, stable across edits once assigned. */
     export function generateSectionId(): string;
-    /** Card summary: the section's first non-empty string value, else the type description. */
+    /**
+     * Card summary: the label of the first value chosen from a select, else the first
+     * non-empty string value, else the type description. Options win over field order
+     * so a tile reads as its linked item however its other fields were filled in.
+     */
     export function sectionSummary(section: PageSection, type?: PageSectionType): string;
 }
+declare module "components/page-builder/page-tree" {
+    import { type PageSection, type PageSectionType } from "components/page-builder/page.types";
+    /** Drops trailing cells that hold nothing. Interior empties are meaningful and kept. */
+    export function trimTrailingEmptyCells(cells: PageSection[][]): PageSection[][];
+    /** Pads to a whole number of rows, always leaving at least one row to drop into. */
+    export function padCells(cells: PageSection[][], columns: number): PageSection[][];
+    /**
+     * The canonical cell list for a container. A growable container never keeps a
+     * trailing all-empty row (the renderer supplies the `+` row itself, so keeping
+     * one would show two); a fixed container's trailing empty row is its layout and
+     * survives untouched.
+     */
+    export function normaliseCells(cells: PageSection[][], columns: number, grow: boolean): PageSection[][];
+    /**
+     * Re-chunks the same ordered list of stacks into a different column count. Only
+     * trailing empties are dropped, so no section can be lost by a column change.
+     */
+    export function recolumnCells(cells: PageSection[][], columns: number): PageSection[][];
+    /** Row-major view of the flat cell list, for rendering. */
+    export function cellRows(cells: PageSection[][], columns: number): PageSection[][][];
+    export function containerWidths(section: PageSection, type?: PageSectionType): number[];
+    export function containerColumns(section: PageSection, type?: PageSectionType): number;
+    export function containerGrow(section: PageSection, type?: PageSectionType): boolean;
+    /** A container's cells, normalised. Empty for a non-container. */
+    export function containerCells(section: PageSection, type?: PageSectionType): PageSection[][];
+    /** Depth-first search across top-level sections and every cell stack. */
+    export function findSection(sections: PageSection[], id: string | null): PageSection | undefined;
+    /** New section array with `id` replaced by `patch(section)`, wherever it lives. */
+    export function patchSection(sections: PageSection[], id: string, patch: (section: PageSection) => PageSection): PageSection[];
+    /** Detaches a section from wherever it lives, returning it and the remaining tree. */
+    export function extractSection(sections: PageSection[], id: string): [PageSection | undefined, PageSection[]];
+    /** Inserts a section into a container's cell at a stack position. */
+    export function insertIntoCell(sections: PageSection[], containerId: string, cellIndex: number, insertIndex: number, section: PageSection, columns: number): PageSection[];
+    /**
+     * Nesting level of the container with this id: 1 at the top level, 2 inside a
+     * cell, 0 when not found. Only containers have cells, so every cell level is a
+     * container level.
+     */
+    export function containerDepth(sections: PageSection[], containerId: string, depth?: number): number;
+    /** Deep copy with a fresh id for the section and every descendant. */
+    export function cloneWithNewIds(section: PageSection): PageSection;
+    /** Resolves a type key to its registered type — the registry's `get`. */
+    export type TypeLookup = (type: string) => PageSectionType | undefined;
+    /**
+     * Height of a container's subtree: 1 for a container with no nested containers,
+     * otherwise 1 + the tallest nested container's height. 0 for a non-container, so
+     * it composes with containerDepth to bound how deep a moved subtree would reach:
+     * dropping a section into a container at depth d puts the section's own deepest
+     * descendant at d + containerHeight(section).
+     */
+    export function containerHeight(section: PageSection): number;
+    /**
+     * Re-applies each container's own grow/columns normalisation throughout the
+     * tree, so a growable container never carries a trailing all-empty row once
+     * committed — not only when read out via containerCells. A section whose
+     * current type isn't a registered container is left untouched, preserving its
+     * cells verbatim per the unknown-type contract.
+     */
+    export function normaliseGrowth(sections: PageSection[], lookup: TypeLookup): PageSection[];
+    /**
+     * Rewrites the pre-cells `children` shape as `cells`. The old grid was always
+     * DEFAULT_WIDTHS wide, and the slot count was the layout, so cells are padded
+     * out to the declared slot count, then rounded up to a whole number of
+     * DEFAULT_WIDTHS-wide rows; never trimmed.
+     */
+    export function migrateSection(section: PageSection, type?: PageSectionType): PageSection;
+    /**
+     * Normalises externally supplied sections: migrates the old shape, gives every
+     * section a unique id, drops malformed entries, sanitises layouts, caps nesting
+     * and clamps sizes. Pure — warnings are returned for the caller to log.
+     */
+    export function normaliseSections(sections: unknown, lookup: TypeLookup): {
+        sections: PageSection[];
+        warnings: string[];
+    };
+}
 declare module "components/page-builder/page-registry" {
     import type { PageSectionType } from "components/page-builder/page.types";
     /**
@@ -10673,6 +10888,8 @@ declare module "components/page-builder/modules/page-section-card/page-section-c
         selected: boolean;
         /** Set when the section's type has no registered template — renders greyed. */
         unknown: boolean;
+        /** Set when the builder pins this section to the page — drops the remove action. */
+        locked: boolean;
         protected updated(changed: PropertyValues): void;
         private _action;
         private _actionKeydown;
@@ -10690,7 +10907,7 @@ declare module "components/page-builder/modules/page-section-card/index" {
     }
 }
 declare module "components/page-builder/page-builder.component" {
-    import { type CSSResultGroup, type PropertyValues } from 'lit';
+    import { type CSSResultGroup, type PropertyValues, type TemplateResult } from 'lit';
     import { type PageSection, type PageSectionType, type PageState } from "components/page-builder/page.types";
     import ZincElement from "internal/zinc-element";
     import ZnCollapsible from "components/collapsible/index";
@@ -10698,6 +10915,7 @@ declare module "components/page-builder/page-builder.component" {
     import ZnInput from "components/input/index";
     import ZnPagePaletteItem from "components/page-builder/modules/page-palette-item/index";
     import ZnPageSectionCard from "components/page-builder/modules/page-section-card/index";
+    import ZnToggle from "components/toggle/index";
     /**
      * @summary A config-driven page composer: a palette of predefined section types, a linear
      *   canvas of section cards, and an inspector for editing each section's content.
@@ -10715,10 +10933,14 @@ declare module "components/page-builder/page-builder.component" {
      * @event zn-page-selection-change - Emitted when the selected section changes. `event.detail.sectionId`.
      *
      * @slot config - `<template type="…">` declarations; never displayed. Each template's attributes
-     *   (type, label, icon, icon-library, color, category, description, slots, accepts) declare a
-     *   palette entry and its content declares the inspector form for that type. `slots` makes the
-     *   section a container with that many child slots; `accepts` is a comma-separated list of the
-     *   type keys its slots allow.
+     *   (type, label, icon, icon-library, color, category, description, container, columns, widths,
+     *   grow, slots, accepts) declare a palette entry and its content declares the inspector form for
+     *   that type. `container` makes the type a container whose editor-configurable layout starts from
+     *   `columns` (seeds equal widths) or `widths` (explicit weights, wins over `columns`); `grow` seeds
+     *   a growable instance. `accepts` is a comma-separated list of the type keys its cells allow —
+     *   omitted on a `container` type, any type is allowed subject to the nesting cap. `slots` is
+     *   @deprecated: it declares a fixed-slot container of `DEFAULT_WIDTHS` columns pinned to that many
+     *   cells, and keeps the old any-non-container-type rule when `accepts` is omitted.
      * @slot header-left - Actions shown on the left of the header bar.
      * @slot header-right - Actions shown on the right of the header bar.
      *
@@ -10727,6 +10949,8 @@ declare module "components/page-builder/page-builder.component" {
      * @csspart palette - The left palette panel.
      * @csspart canvas - The centre section-card canvas.
      * @csspart inspector - The right panel while a section is selected.
+     * @csspart inspector-header - The inspector's fixed header (icon, section name, type, close).
+     * @csspart inspector-body - The inspector's scrolling form area.
      */
     export default class ZnPageBuilder extends ZincElement {
         static styles: CSSResultGroup;
@@ -10736,6 +10960,7 @@ declare module "components/page-builder/page-builder.component" {
             'zn-input': typeof ZnInput;
             'zn-page-palette-item': typeof ZnPagePaletteItem;
             'zn-page-section-card': typeof ZnPageSectionCard;
+            'zn-toggle': typeof ZnToggle;
         };
         private readonly formControlController;
         /** The name of the control, submitted as a name/value pair with form data. */
@@ -10746,6 +10971,13 @@ declare module "components/page-builder/page-builder.component" {
         config: string;
         heading: string;
         subheading: string;
+        /**
+         * Section type key that must lead the page. The builder hoists an existing section of
+         * that type to the top, or inserts an empty one, and pins it there: it can't be
+         * removed, reordered or dragged into a slot, and nothing can be dropped above it.
+         * Its content stays fully editable in the inspector.
+         */
+        requiredFirst: string;
         /** Section types to make available, registered into the internal registry. */
         sectionTypes: PageSectionType[];
         /** Collapses the left palette. Auto-set when the builder becomes narrow. */
@@ -10765,10 +10997,10 @@ declare module "components/page-builder/page-builder.component" {
         /** Index of the drop zone whose "+" type picker is open, if any. */
         private _pickerIndex;
         private _dragOverIndex;
-        /** The container slot a drag is currently over, if any. */
-        private _slotDragOver;
-        /** The container slot whose "+" type picker is open, if any. */
-        private _slotPicker;
+        /** The cell a drag is currently over, if any. */
+        private _cellDragOver;
+        /** The cell whose "+" type picker is open, if any. */
+        private _cellPicker;
         /** The stamped config form for the selected section; rebuilt on selection change. */
         private _form;
         private readonly _hasSlot;
@@ -10797,6 +11029,7 @@ declare module "components/page-builder/page-builder.component" {
         /** Sets a custom validation message. Pass an empty string to restore validity. */
         setCustomValidity(_message?: string): void;
         handleConfigChange(): void;
+        handleRequiredFirstChange(): void;
         handleSectionTypesChange(): void;
         registerSectionType(type: PageSectionType): this;
         registerSectionTypes(types: PageSectionType[]): this;
@@ -10842,42 +11075,82 @@ declare module "components/page-builder/page-builder.component" {
         private _registerSlottedTemplates;
         /** Normalises and installs an externally provided state; resets selection. */
         private _applyExternalState;
-        /** Finds a section by id, searching top-level sections and slotted children. */
-        private _findSection;
-        /** New sections array with the section patched wherever it lives (top level or slot). */
-        private _patchSection;
-        /** Detaches a section wherever it lives: removed from the top level, or its slot nulled. */
-        private _extract;
-        /** Installs a new state from a user edit and notifies listeners. */
+        /**
+         * Id of the section pinned to the top of the page, or null when `required-first`
+         * is unset. Derived from the state rather than stored on it, so nothing about the
+         * lock leaks into the persisted config.
+         */
+        private get _pinnedId();
+        private _isPinned;
+        /** Lowest top-level index a section may be added or moved to. */
+        private get _firstFreeIndex();
+        /**
+         * Sections reordered so `required-first` leads the page: an existing section of that
+         * type is hoisted to the front, otherwise an empty one is prepended. Returns the
+         * argument unchanged when there is nothing to do, so callers can compare by identity.
+         */
+        private _requireFirst;
+        /**
+         * Installs a new state from a user edit and notifies listeners. Re-applies
+         * growth normalisation across the tree first, so a growable container never
+         * carries a trailing empty row past this point — the read path (`containerCells`)
+         * already hides it, but state/value/zn-page-change/auto-save must not diverge
+         * from what the canvas renders.
+         */
         private _commit;
         private _selectedSection;
         private _select;
         private _pushHistory;
         undo: () => void;
         redo: () => void;
+        /** A fresh section of a registered type, seeded with layout/cells when it's a container. */
+        private _newSection;
         /** Adds a section of a registered type at `index` (default: end). Returns null for unknown types. */
         addSection(type: string, index?: number): PageSection | null;
-        /** Adds a new section of a registered type into a container's slot. Returns null if not allowed. */
-        addSectionToSlot(type: string, containerId: string, slotIndex: number): PageSection | null;
         private _removeSection;
         private _duplicateSection;
-        /** Moves a section (top-level or slotted) to a top-level position. */
+        /** Locates a section living inside a container cell. */
+        private _findCellOwner;
+        /** Moves a section (top-level or inside a cell) to a top-level position. */
         private _moveSection;
-        /**
-         * Moves a section into a container's slot. Dropping onto an occupied slot swaps
-         * the two children (slot-to-slot reordering); top-level sections and containers
-         * only enter empty slots / never enter slots respectively.
-         */
-        private _moveToSlot;
+        /** Id of the section currently being dragged — dataTransfer is unreadable during dragover. */
+        private _draggingId;
         private _onCardDragStart;
         /** Whether a drag carries one of the builder's own payloads. */
         private _isPageDrag;
-        private _onSlotDragOver;
-        private _onSlotDrop;
         private _onZoneDragOver;
         private _onZoneDrop;
         private _onCanvasDragOver;
         private _onCanvasDrop;
+        /**
+         * Whether `typeKey`'s registered type is allowed into this container by its
+         * `accepts`/`slots=` rule — the nesting depth cap is a separate concern,
+         * checked by each caller against its own notion of how tall the dropped
+         * subtree is.
+         */
+        private _acceptsType;
+        /**
+         * Whether `typeKey` may be dropped into this container's cells from the
+         * palette. A newly created section always has height 1, so the depth cap
+         * only needs the target's own depth.
+         */
+        private _acceptsInCell;
+        /**
+         * Whether a dragged, already-placed section may land in this container's
+         * cells. Unlike a palette drop, the moved subtree can already be several
+         * containers tall (it may itself hold a nested container), so the cap has to
+         * account for that height, not just the target's depth: dropping `moved` at
+         * a new depth of `containerDepth(container) + 1` puts its own deepest
+         * descendant at `containerDepth(container) + containerHeight(moved)`.
+         */
+        private _canMoveIntoCell;
+        private _onCellDragOver;
+        private _onCellDrop;
+        /** Adds a new section of a registered type into a container cell. */
+        addSectionToCell(type: string, containerId: string, cellIndex: number, insertIndex?: number): PageSection | null;
+        private _moveToCell;
+        /** Types offerable in a container's cells. */
+        private _cellTypes;
         private _onCardKeydown;
         private _renderPalette;
         private _renderPaletteItem;
@@ -10887,10 +11160,17 @@ declare module "components/page-builder/page-builder.component" {
         /** The one card template both the page list and slot cells render. */
         private _renderSectionCard;
         private _renderCard;
-        private _renderSlot;
-        /** Types allowed in a container's slots: non-containers, filtered by its accepts list. */
-        private _slotTypes;
-        /** The one type-picker template both drop zones and slot cells render. */
+        /**
+         * A card, or — for a container — its card plus its own cell grid. Shared by the
+         * top-level section list and container-cell stacks, so nesting renders at every level.
+         */
+        private _renderNode;
+        /** A container's cell grid: one track per width, one stack per cell. */
+        private _renderCells;
+        private _renderCell;
+        /** Thin insertion target between two cards in a stack. */
+        private _renderCellStrip;
+        /** The one type-picker template both drop zones and container cells render. */
         private _renderTypePicker;
         private _renderDropZone;
         /**
@@ -10904,8 +11184,16 @@ declare module "components/page-builder/page-builder.component" {
         private _onInspectorInput;
         private _updateSectionData;
         private _renameSection;
+        /** Replaces a container's layout, keeping cells consistent with it. */
+        private _setLayout;
+        private _setColumns;
+        private _setWidth;
+        private _setGrow;
+        /** Pads with empty rows, or trims trailing empty rows down to the last occupied one. */
+        private _setRows;
+        private _renderLayoutGroup;
         private _renderInspector;
-        render(): import("lit-html").TemplateResult<1>;
+        render(): TemplateResult<1>;
     }
 }
 declare module "components/page-builder/index" {
@@ -11362,6 +11650,289 @@ declare module "components/theme-editor/index" {
         }
     }
 }
+declare module "components/schedule-builder/schedule-builder.component" {
+    import { type CSSResultGroup } from 'lit';
+    import ZincElement from "internal/zinc-element";
+    import ZnIcon from "components/icon/index";
+    import ZnInput from "components/input/index";
+    import ZnOption from "components/option/index";
+    import ZnSelect from "components/select/index";
+    import type { ZincFormControl } from "internal/zinc-element";
+    /** The seven weekday keys used throughout the schedule. */
+    export type ScheduleDay = 'mon' | 'tue' | 'wed' | 'thu' | 'fri' | 'sat' | 'sun';
+    /** A single opening period within a day. Times are `HH:MM` in the schedule's own timezone. */
+    export interface ScheduleRange {
+        start: string;
+        end: string;
+    }
+    /**
+     * A dated deviation from the weekly pattern. Exceptions are never edited by the builder, they only
+     * annotate it — the surrounding application owns them.
+     */
+    export interface ScheduleException {
+        id?: string;
+        /** Human readable name, e.g. `Christmas Eve — early close`. */
+        label?: string;
+        /** A single calendar date (`YYYY-MM-DD`). */
+        date?: string;
+        /** Inclusive start of a multi-day exception (`YYYY-MM-DD`). */
+        from?: string;
+        /** Inclusive end of a multi-day exception (`YYYY-MM-DD`). */
+        to?: string;
+        /** Weekdays the exception applies to. Defaults to every weekday inside the date window. */
+        days?: ScheduleDay[];
+        /** When true the affected days close outright and `ranges` is ignored. */
+        closed?: boolean;
+        /** Replacement opening hours for the affected days. */
+        ranges?: ScheduleRange[];
+    }
+    export type ScheduleDayMap = Record<ScheduleDay, ScheduleRange[]>;
+    /** The shape serialised into the form value. */
+    export interface ScheduleValue {
+        timezone?: string;
+        days: ScheduleDayMap;
+        exceptions: ScheduleException[];
+    }
+    export type ScheduleView = 'calendar' | 'form';
+    /** The named sets accepted by `timezones`, alongside explicit IANA names. */
+    export type ScheduleTimezoneSet = 'en' | 'offsets' | 'common' | 'all';
+    /**
+     * @summary Builds a weekly opening-hours schedule as a drag-to-paint calendar or a compact list of
+     * time ranges, and posts the result as JSON.
+     * @documentation https://zinc.style/components/schedule-builder
+     * @status experimental
+     * @since 1.0
+     *
+     * @dependency zn-icon
+     * @dependency zn-input
+     * @dependency zn-option
+     * @dependency zn-select
+     *
+     * @event zn-change - Emitted when the schedule changes.
+     *
+     * @slot label - The schedule's label. Alternatively, use the `label` attribute.
+     * @slot help-text - Text that describes how to use the schedule. Alternatively, use the `help-text` attribute.
+     *
+     * @csspart form-control - The form control that wraps the builder, label and help text.
+     * @csspart base - The component's base wrapper.
+     * @csspart toolbar - The row above the builder holding the hint, legend and view toggle.
+     * @csspart calendar - The calendar view wrapper.
+     * @csspart list - The form (list) view wrapper.
+     * @csspart summary - The summary panel beside the calendar.
+     *
+     * @cssproperty --slot-height - The height of a single time slot in the calendar. Defaults to `18px`.
+     * @cssproperty --gutter-width - The width of the calendar's time gutter. Defaults to `64px`.
+     * @cssproperty --open-color - The fill used for open hours.
+     * @cssproperty --reduced-color - The fill used for hours an exception removes.
+     */
+    export default class ZnScheduleBuilder extends ZincElement implements ZincFormControl {
+        static styles: CSSResultGroup;
+        static formAssociated: boolean;
+        static dependencies: {
+            'zn-icon': typeof ZnIcon;
+            'zn-input': typeof ZnInput;
+            'zn-option': typeof ZnOption;
+            'zn-select': typeof ZnSelect;
+        };
+        private readonly formControlController;
+        private readonly hasSlotController;
+        private readonly localize;
+        private readonly internals;
+        private canvas;
+        private _days;
+        private _exceptions;
+        private _dragPreview;
+        private _editing;
+        private _dragMode;
+        private _dragAnchor;
+        private _dragPointerId;
+        /** The name of the form control, submitted as a name/value pair with form data. */
+        name: string;
+        /** The schedule as a JSON string. This is what gets posted with the form. */
+        value: string;
+        /** The default value, used when resetting the containing form. */
+        defaultValue: string;
+        /** The schedule's label. If you need to display HTML, use the `label` slot instead. */
+        label: string;
+        /** The schedule's help text. If you need to display HTML, use the `help-text` slot instead. */
+        helpText: string;
+        /** Which view is showing. */
+        view: ScheduleView;
+        /** The word used for hours the schedule covers, in the legend and in labels. */
+        openLabel: string;
+        /** The word used for hours the schedule doesn't cover, in the legend and against empty days. */
+        closedLabel: string;
+        /** Hides the calendar/form view toggle. */
+        noToggle: boolean;
+        /** Hides the summary panel beside the calendar. */
+        hideSummary: boolean;
+        /** The first hour shown in the calendar. */
+        startHour: number;
+        /** The last hour shown in the calendar. */
+        endHour: number;
+        /** The granularity of the calendar grid and the time inputs, in minutes. */
+        interval: number;
+        /** The weekday the week starts on. */
+        weekStart: ScheduleDay;
+        /** Displays times as 12 or 24 hour. The serialised value is always 24 hour `HH:MM`. */
+        timeFormat: '12' | '24';
+        /**
+         * The IANA timezone the hours are shown in. Accepts `auto` for the viewer's own timezone. Defaults
+         * to `save-timezone`, so nothing is converted until you ask for it. Changing this only re-labels
+         * the same underlying hours; the value never moves.
+         */
+        displayTimezone: string;
+        /**
+         * The IANA timezone the value is stored in. Defaults to `UTC` as soon as the schedule is
+         * timezone-aware (a display timezone is set, or the picker is shown), and to no timezone at all
+         * otherwise — in which case the times are stored exactly as they are shown.
+         */
+        saveTimezone: string;
+        /** Shows the timezone picker, letting the user read the schedule in any timezone. */
+        showTimezone: boolean;
+        /**
+         * The timezones offered by the picker, as IANA names or one of the named sets — `en` (the four US
+         * zones, the UK and Australia, under those names), `offsets` (one zone per UTC offset, the
+         * default), `common` (every offset plus the world's major centres) or `all` (the complete IANA
+         * list). Names and sets can be mixed, e.g. `en Asia/Tokyo`.
+         */
+        timezones: string[];
+        /**
+         * The date (`YYYY-MM-DD`) used to resolve timezone offsets. A weekly pattern has no date of its
+         * own, so one has to be picked to know whether daylight saving applies; today is used by default.
+         */
+        referenceDate: string;
+        /** Disables the schedule. */
+        disabled: boolean;
+        /** Renders the schedule without any editing affordances. */
+        readonly: boolean;
+        /** Makes the schedule a required field, invalid until at least one period is open. */
+        required: boolean;
+        /** The id of the form to associate with, when the control sits outside of it. */
+        form: string;
+        constructor();
+        /**
+         * The schedule as a plain object, with `days` in the save timezone. Assigning to it replaces the
+         * whole schedule.
+         */
+        get schedule(): ScheduleValue;
+        set schedule(schedule: ScheduleValue | null | undefined);
+        /** The exceptions annotating the schedule. Also readable from, and written into, the value. */
+        get exceptions(): ScheduleException[];
+        set exceptions(exceptions: ScheduleException[] | null | undefined);
+        /** Gets the validity state object. */
+        get validity(): ValidityState;
+        /** Gets the validation message. */
+        get validationMessage(): string;
+        /** Whether the schedule carries a timezone at all. */
+        private get _isZoned();
+        /** The timezone the value is stored in. Empty means the times are stored exactly as shown. */
+        private get _saveZone();
+        /** The timezone the grid and list are drawn in. */
+        private get _displayZone();
+        /** The moment used to resolve daylight saving for both zones. */
+        private get _reference();
+        /** Minutes to add to a stored time to get the time shown. */
+        private get _offsetDelta();
+        private get _orderedDays();
+        private get _interval();
+        private get _startMinute();
+        private get _endMinute();
+        private get _slotCount();
+        private get _slotsPerHour();
+        private get _isEditable();
+        private get _hasHours();
+        connectedCallback(): void;
+        firstUpdated(): void;
+        handleValueChange(): void;
+        handleValidationStateChange(): void;
+        /** Checks validity but does not show a validation message. */
+        checkValidity(): boolean;
+        /** Gets the associated form, if one exists. */
+        getForm(): HTMLFormElement | null;
+        /** Checks for validity and shows the browser's validation message if the control is invalid. */
+        reportValidity(): boolean;
+        /** Sets a custom validation message. Pass an empty string to restore validity. */
+        setCustomValidity(message: string): void;
+        /** Replaces the hours for a single day, in the save timezone. */
+        setDay(day: ScheduleDay, ranges: ScheduleRange[]): void;
+        /** Reads the hours for a single day, in the save timezone. */
+        getDay(day: ScheduleDay): ScheduleRange[];
+        /** The hours as currently shown, in the display timezone. */
+        get displayedDays(): ScheduleDayMap;
+        /** Replaces the hours for a single day, given in the display timezone. */
+        setDisplayDay(day: ScheduleDay, ranges: ScheduleRange[]): void;
+        formResetCallback(): void;
+        formStateRestoreCallback(restoredValue: string): void;
+        private _customValidity;
+        private _cloneDays;
+        private _serialise;
+        /** Accepts a JSON string, a full `ScheduleValue`, or a bare day map. */
+        private _applySchedule;
+        private _syncFormValue;
+        private _commit;
+        private _formatTime;
+        private _formatRange;
+        private _formatDate;
+        private _summariseDay;
+        /** The stored hours rotated into the display timezone. */
+        private get _storedAsShown();
+        /** The hours as drawn, which is the drag preview while a drag is in flight. */
+        private get _shownDays();
+        /** Stores hours that were edited in display coordinates, rotating them back to the save timezone. */
+        private _commitShownDays;
+        /** The exceptions that touch a given weekday and actually change its hours. */
+        private _exceptionsForDay;
+        /**
+         * The week spans an exception takes away, in display coordinates. Computed as spans rather than
+         * per-day ranges because a timezone rotation can move an exception's hours onto another weekday.
+         */
+        private get _shownReductionSpans();
+        /** The week minute a calendar cell sits on, measured from Monday 00:00. */
+        private _slotMinute;
+        private _slotState;
+        private _pointerPosition;
+        /** Paints the rectangle between the drag anchor and the cursor onto a copy of the shown schedule. */
+        private _buildDragPreview;
+        private _handleCanvasPointerDown;
+        private _handleCanvasPointerMove;
+        private _handleCanvasPointerUp;
+        private _handleCanvasPointerCancel;
+        private _handleViewToggle;
+        /** Picks a sensible slot for a newly added range: the first hour-wide gap in the day. */
+        private _nextFreeRange;
+        private _handleAddRange;
+        private _handleRemoveRange;
+        private _handleRangeEdit;
+        private _handleEditorKeyDown;
+        private _handleEditorFocusOut;
+        private _renderToolbar;
+        /** The picker's options: the configured list plus whatever zones are already in play. */
+        private get _timezoneOptions();
+        private _handleTimezoneChange;
+        private _renderTimezonePicker;
+        private _renderCalendar;
+        private _renderCalendarColumn;
+        private _renderSummary;
+        private _renderList;
+        private _renderListRow;
+        private _renderRangeChip;
+        private _renderRangeEditor;
+        /** The exception annotation shown against a day in the form view. */
+        private _dayNote;
+        render(): import("lit-html").TemplateResult<1>;
+    }
+}
+declare module "components/schedule-builder/index" {
+    import ZnScheduleBuilder from "components/schedule-builder/schedule-builder.component";
+    export * from "components/schedule-builder/schedule-builder.component";
+    export default ZnScheduleBuilder;
+    global {
+        interface HTMLElementTagNameMap {
+            'zn-schedule-builder': ZnScheduleBuilder;
+        }
+    }
+}
 declare module "utilities/form" {
     export { clearFormStoreValues } from "internal/form";
 }
@@ -11722,6 +12293,7 @@ declare module "zinc" {
     export { default as ThemeEditor } from "components/theme-editor/index";
     export { default as SlashMenu } from "components/slash-menu/index";
     export { default as SlashItem } from "components/slash-item/index";
+    export { default as ScheduleBuilder } from "components/schedule-builder/index";
     export { default as ZincElement } from "internal/zinc-element";
     export * from "utilities/on";
     export * from "utilities/query";