@kubex/zinc 1.1.94 → 1.1.95

package/dist/zn.d.ts

@@ -1901,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 {
@@ -1927,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";
@@ -1943,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 {
@@ -1957,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;
@@ -1964,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;
@@ -1972,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. */
@@ -1979,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. */
@@ -2006,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" {
@@ -2080,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.
@@ -2132,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";
@@ -2337,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.
@@ -5233,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: {
@@ -6680,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.
@@ -8724,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. */
@@ -9278,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;
@@ -9287,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;
@@ -9294,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;
@@ -9302,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;
@@ -9320,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. */
@@ -9341,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.
@@ -9352,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;
@@ -9398,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;
@@ -9419,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;
     }
 }
@@ -10532,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[];
@@ -10560,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;
         /**
-         * 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.
+         * 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;
+        /**
+         * @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. */
@@ -10584,6 +10713,82 @@ declare module "components/page-builder/page.types" {
      */
     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";
     /**
@@ -10683,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;
@@ -10700,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";
@@ -10708,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.
@@ -10725,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.
      *
@@ -10748,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. */
@@ -10758,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. */
@@ -10777,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;
@@ -10809,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;
@@ -10854,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;
@@ -10899,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;
         /**
@@ -10916,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" {