@kubex/zinc 1.1.94 → 1.1.96

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,10 @@ declare module "components/remarkd-editor/remarkd-editor.component" {
         private dragIndex;
         private editShell;
         private rawMode;
+        private includeOptions;
+        private includeLoadFailed;
+        private includePickerIndex;
+        private includeQuery;
         private pendingDragHandle;
         private dragStartX;
         private dragStartY;
@@ -9320,6 +9387,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 +9414,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 +9426,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 +9474,24 @@ 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;
+        /**
+         * Resolves an app-relative path the way the console's pagelet handler does:
+         * an app fragment's URLs sit under the app base, and the console puts the app's
+         * `gaid` on the host element. Links rendered here live in the shadow root,
+         * where a click retargets to the host, so that handler never sees them — the
+         * href has to carry the base itself.
+         */
+        private appPath;
+        private hasIncludeBlock;
+        /** Fetches the include list once; every later caller shares the same promise. */
+        private loadIncludeOptions;
         private autosize;
         private toggleRawMode;
         private focusRaw;
@@ -9419,11 +9509,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;
     }
 }
@@ -9525,6 +9617,14 @@ declare module "components/flow-builder/flow.types" {
         inputs?: FlowPort[];
         /** Output ports. Defaults to a single unlabelled output. e.g. TRUE/FALSE for a split. */
         outputs?: FlowPort[];
+        /**
+         * The type's branches are the only ones it has: the canvas offers no delete
+         * on their pills, and clicking a fully-wired node's output adds nothing.
+         * For steps whose branches mirror fixed fields in the consumer's own model
+         * (a success / failure / skip triple, say), where an extra or missing branch
+         * has nowhere to be stored.
+         */
+        fixedOutputs?: boolean;
         /** Initial `data` for a freshly placed node. */
         defaultData?: Record<string, unknown>;
         /**
@@ -9611,12 +9711,17 @@ declare module "components/flow-builder/flow.types" {
     /** Extra pill height per wrapped line (matches the pill's CSS line-height). */
     export const PILL_LINE_HEIGHT = 20;
     /**
-     * Canvas y of a branch pill's top edge. A pill on a wire to a child below is
-     * centred along the run from its node's bottom to the child's top — equal wire
-     * above and below, however long or tight. A sole output's wire is a straight
-     * stem with no bus to respect, so its pill may rise above the bus line to stay
-     * centred; fan branches stop at the bus. Open branches and loop/side wires
-     * keep the fixed drop below the bus.
+     * Canvas y of a branch pill's top edge. A pill on a wire to a child in the next
+     * row down is centred along the run from its node's bottom to the child's top —
+     * equal wire above and below. A sole output's wire is a straight stem with no
+     * bus to respect, so its pill may rise above the bus line to stay centred; fan
+     * branches stop at the bus.
+     *
+     * A branch reaching past the next row sits right under the bus instead: it
+     * reads as belonging to the node it hangs from rather than to whatever it flies
+     * over, and it leaves the whole gap below free for the wire to route around
+     * what is in the way. Open branches and loop/side wires keep the fixed drop
+     * below the bus, where their "+" has room.
      */
     export function branchPillTop(node: Pick<FlowNodeInstance, 'y'>, pillH: number, child?: Pick<FlowNodeInstance, 'y'>, soleOutput?: boolean): number;
     /**
@@ -9643,13 +9748,19 @@ declare module "components/flow-builder/flow.types" {
     /** A function resolving a node type key to its registered type. */
     export type FlowTypeOf = (type: string) => FlowNodeType | undefined;
     /**
-     * Canvas x for each of a node's branch drops: the natural fan position under
-     * the source. Pills never shift sideways to chase their child — the wire into
-     * a pill is always a straight vertical, and any lateral offset to the child is
-     * taken up by the elbow below the pill (which still enters the child from
-     * straight above).
+     * Canvas x for each of a node's branch drops. Neighbours are spaced by what
+     * they actually occupy — two child lanes keep the full spread, while a branch
+     * with nothing wired to it needs only its pill — and the run is then shifted so
+     * the *wired* branches stay centred on the node. A step that declares branches
+     * it is not using therefore still runs straight down, instead of fanning empty
+     * lanes across the canvas; and a fully wired fan is spaced exactly as before.
+     *
+     * Pills never shift sideways to chase their child — the wire into a pill is
+     * always a straight vertical, and any lateral offset to the child is taken up
+     * by the elbow below the pill (which still enters the child from straight
+     * above).
      */
-    export function branchDropXs(node: FlowNodeInstance, typeOf: FlowTypeOf): number[];
+    export function branchDropXs(node: FlowNodeInstance, typeOf: FlowTypeOf, connections?: FlowConnection[]): number[];
     /**
      * The rects a node occupies on the canvas: its card plus each branch-name pill,
      * at the exact positions the canvas draws them.
@@ -10019,20 +10130,40 @@ declare module "components/flow-builder/modules/flow-canvas/flow-canvas.componen
          */
         private _elbowMidOffsets;
         /**
-         * Whether an orthogonal segment passes through any node card (with margin) —
-         * or the approach zone above one, where incoming arrows land. A foreign wire
-         * running just over a card's input port reads as connecting to it, so routes
-         * keep well clear of that strip too.
+         * Whether an orthogonal segment passes through any node card (with margin).
+         * With `keepApproachClear`, the strip above each card - where incoming arrows
+         * land - counts as occupied too: a foreign wire running just over a card's
+         * input port reads as connecting to it.
          */
         private _segmentBlocked;
         private _routeClear;
         /**
          * Orthogonal waypoints from a branch exit to a child's input. The wire always
          * enters the input from above (arrow pointing down), and never passes through
-         * a node card: each candidate route is checked against every card, scanning
-         * alternative lanes / side-steps / detours until one is clear.
+         * a node card.
+         *
+         * The search runs twice: first keeping clear of the strip above every card as
+         * well as the cards themselves, then - if the corridor is genuinely too tight
+         * for that - clear of the cards alone. Only when nothing at all fits does the
+         * wire fall back to the direct line, so a wire drawn over a card now means
+         * there was no way around it rather than that the search gave up.
          */
         private _routePoints;
+        /**
+         * Candidate routes to a child below, tidiest first: the straight drop or the
+         * single elbow, then the same elbow on neighbouring lines, then out around
+         * whatever sits between the two (the shape a loop-back uses - far more
+         * readable than threading a corridor when a wire skips a row it has nothing
+         * to do with), and finally a side-step that jogs out and back.
+         */
+        private _forwardRoutes;
+        /**
+         * Routes that leave the exit, run down the outside of everything they span
+         * vertically, and come back in above the input. Loop-backs always travel this
+         * way rather than squeezing through corridors inside the flow; a forward wire
+         * uses it when the corridor between it and its child is occupied.
+         */
+        private _aroundRoutes;
         private static _pathFrom;
         /**
          * Open output slots ("+" add-points) across all nodes — only rendered while
@@ -10343,6 +10474,13 @@ declare module "components/flow-builder/flow-builder.component" {
         private _duplicateNode;
         /** Canvas position for a node newly placed off a source node's output. */
         private _positionBelowOutput;
+        /**
+         * Whether a node refuses the branch being asked of it: a fixed-output type
+         * has only the branches it declares, so the "new branch" sentinel has nowhere
+         * to go. Checked before the history push, so a refused gesture is a no-op
+         * rather than an empty undo step.
+         */
+        private _refusesBranch;
         /**
          * Resolve an output port id on a node: the "new branch" sentinel materialises a
          * fresh, labelled output port (per-instance), so it exists before connecting.
@@ -10504,6 +10642,8 @@ declare module "components/flow-builder/modules/flow-step/flow-step.component" {
         inputs: string;
         /** JSON array of outputs (`"a"` or `{"id","label"}`), e.g. `'[{"id":"true","label":"TRUE"}]'`. Omit for one default output. */
         outputs: string;
+        /** The declared outputs are the only branches this step has — none can be deleted or added on the canvas. */
+        fixedOutputs: boolean;
         connectedCallback(): void;
         disconnectedCallback(): void;
         protected updated(changed: PropertyValues): void;
@@ -10683,6 +10823,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;
@@ -10758,6 +10900,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. */
@@ -10809,6 +10958,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,6 +11004,21 @@ declare module "components/page-builder/page-builder.component" {
         private _registerSlottedTemplates;
         /** Normalises and installs an externally provided state; resets selection. */
         private _applyExternalState;
+        /**
+         * 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;
         /** 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). */