superdoc 2.2.0 → 2.3.0

package/dist/superdoc/src/internal/toolbar/built-in/constants.d.ts

@@ -0,0 +1,102 @@
+/**
+ * The single seam that composes the font dropdown options: it turns the active document's
+ * {@link import('../../../../../shared/font-system/src/index.js').DocumentFontOption}s into toolbar font options and unions them
+ * with the bundled defaults. The toolbar only asks for the result; it does not know how a font previews.
+ *
+ * - A consumer-provided `configFonts` list is returned UNCHANGED (custom toolbars own their list).
+ * - With no document options, returns `undefined` so the caller keeps its fallback to {@link TOOLBAR_FONTS}.
+ * - Otherwise: bundled defaults and document fonts are deduped by normalized logical family, then sorted
+ *   alphabetically by the visible font name. `label`/`key` stay the pure logical family (active-state
+ *   matching + the stored value), and the preview renders in `previewFamily`.
+ *
+ * @param {ReadonlyArray<import('../../../../../shared/font-system/src/index.js').DocumentFontOption>} documentOptions
+ * @param {Array} [configFonts] - the consumer's `fonts` config, if any
+ * @returns {Array|undefined}
+ */
+export function composeToolbarFontOptions(documentOptions: ReadonlyArray<import('../../../../../shared/font-system/src/index.js').DocumentFontOption>, configFonts?: any[]): any[] | undefined;
+/**
+ * Map the host-computed, activation-aware font-family options onto the toolbar option shape. PURE: it
+ * receives the already-resolved list from `superdoc.fonts.getFontFamilyOptions()` (the host owns the
+ * `@superdoc/font-system` computation this module must not import). Returns `undefined` for an empty
+ * list so the caller keeps its {@link TOOLBAR_FONTS} fallback. `label` is the Word-facing logical
+ * family (stored on the selection + used for active-state matching), `key` is a stable option key, and
+ * the row preview renders in `previewFamily` (falling back to the label).
+ *
+ * @param {ReadonlyArray<import('../../../../../shared/font-system/src/index.js').FontFamilyOption>} options
+ * @returns {Array|undefined}
+ */
+export function mapFontFamilyOptionsToToolbar(options: ReadonlyArray<import('../../../../../shared/font-system/src/index.js').FontFamilyOption>): any[] | undefined;
+export const TOOLBAR_FONTS: {
+    label: string;
+    key: string;
+    fontWeight: number;
+    props: {
+        style: {
+            fontFamily: string;
+        };
+        'data-item': string;
+    };
+}[];
+export const TOOLBAR_FONT_SIZES: {
+    label: string;
+    key: string;
+    props: {
+        'data-item': string;
+    };
+}[];
+export namespace RESPONSIVE_BREAKPOINTS {
+    let sm: number;
+    let md: number;
+    let lg: number;
+    let xl: number;
+}
+export namespace HEADLESS_ITEM_MAP {
+    let undo: string;
+    let redo: string;
+    let bold: string;
+    let italic: string;
+    let underline: string;
+    let strike: string;
+    let acceptTrackedChangeBySelection: string;
+    let rejectTrackedChangeOnSelection: string;
+    let ruler: string;
+    let formattingMarks: string;
+    let zoom: string;
+    let measurementUnit: string;
+    let documentMode: string;
+    let link: string;
+    let fontFamily: string;
+    let fontSize: string;
+    let list: string;
+    let numberedlist: string;
+    let table: string;
+    let image: string;
+    let tableOfContents: string;
+    let color: string;
+    let highlight: string;
+    let textAlign: string;
+    let lineHeight: string;
+    let linkedStyles: string;
+    let indentleft: string;
+    let indentright: string;
+    let directionLtr: string;
+    let directionRtl: string;
+    let clearFormatting: string;
+    let copyFormat: string;
+}
+export namespace TABLE_ACTION_COMMAND_MAP {
+    let addRowBefore: string;
+    let addRowAfter: string;
+    let deleteRow: string;
+    let addColumnBefore: string;
+    let addColumnAfter: string;
+    let deleteColumn: string;
+    let deleteTable: string;
+    let deleteCellAndTableBorders: string;
+    let mergeCells: string;
+    let splitCell: string;
+    let fixTables: string;
+}
+export const TABLE_ACTION_COMMAND_IDS: string[];
+export const HEADLESS_TOOLBAR_COMMANDS: string[];
+export const HEADLESS_EXECUTE_ITEMS: Set<string>;

package/dist/superdoc/src/internal/toolbar/built-in/default-items.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Set or clear the link item's `href` without disturbing the rest of its
+ * attributes. The static configuration (`ariaLabel`, and anything added later)
+ * lives in the same object as the transient href, so rebuilding that object
+ * from the keys a caller knows about silently drops the others.
+ *
+ * Exported because the built-in toolbar's `updateToolbarState()` writes the
+ * href on its own path, without going through this item's handlers. Both
+ * callers share this one rule so the two cannot drift apart.
+ */
+export function withLinkHref(attributes: any, href: any): any;
+export function makeDefaultItems({ superToolbar, toolbarIcons, toolbarTexts, toolbarFonts, hideButtons, availableWidth, role, isDev, }?: {
+    isDev?: boolean | undefined;
+}): {
+    defaultItems: any[];
+    overflowItems: any[];
+};

package/dist/superdoc/src/internal/toolbar/built-in/font-options.d.ts

@@ -0,0 +1 @@
+export function normalizeFontOption(option: any): any;

package/dist/superdoc/src/internal/toolbar/built-in/font-typeahead.d.ts

@@ -0,0 +1,11 @@
+export function findPrefixMatchIndex(query: string, labels: ReadonlyArray<string>): number;
+export function computeTypeahead(query: string, labels: ReadonlyArray<string>, { autocomplete }?: {
+    autocomplete?: boolean;
+}): {
+    matchIndex: number;
+    display: string;
+    selectionStart: number;
+    selectionEnd: number;
+};
+export function normalizeCustomFontFamily(value: any): string;
+export function normalizeCustomFontSize(value: string): string;

package/dist/superdoc/src/internal/toolbar/built-in/format-negation.d.ts

@@ -0,0 +1,5 @@
+export function isOffValue(value: unknown): boolean;
+/** @type {Record<string, (attrs?: Record<string, unknown>) => boolean>} */
+export const negationChecks: Record<string, (attrs?: Record<string, unknown>) => boolean>;
+export function isNegatedMark(name: string, attrs?: Record<string, unknown>): boolean;
+export default isNegatedMark;

package/dist/superdoc/src/internal/toolbar/built-in/general.d.ts

@@ -0,0 +1 @@
+export function findElementBySelector(selector: string | HTMLElement | null | undefined): HTMLElement | null;

package/dist/superdoc/src/internal/toolbar/built-in/helpers.d.ts

@@ -0,0 +1,5 @@
+export function sanitizeNumber(value: any, defaultNumber: any): any;
+export function throttle(func: any, wait: any, options: any): {
+    (...callArgs: any[]): any;
+    cancel(): void;
+};

package/dist/superdoc/src/internal/toolbar/built-in/list-style-buttons.d.ts

@@ -0,0 +1,10 @@
+export const bulletStyleButtons: {
+    key: string;
+    icon: any;
+    ariaLabel: string;
+}[];
+export const numberedStyleButtons: {
+    key: string;
+    icon: any;
+    ariaLabel: string;
+}[];

package/dist/superdoc/src/internal/toolbar/built-in/scroll-helpers.d.ts

@@ -0,0 +1,4 @@
+export function scrollToElement(targetElement: any, options?: {
+    behavior: string;
+    block: string;
+}): void;

package/dist/superdoc/src/internal/toolbar/built-in/toolbar-focus-helpers.d.ts

@@ -0,0 +1 @@
+export function refocusEditorSurface(superToolbar: any, preferredEditor?: null): void;

package/dist/superdoc/src/internal/toolbar/built-in/toolbarIcons.d.ts

@@ -0,0 +1,76 @@
+export namespace toolbarIcons {
+    export { rotateLeftIconSvg as undo };
+    export { rotateRightIconSvg as redo };
+    export { boldIconSvg as bold };
+    export { italicIconSvg as italic };
+    export { underlineIconSvg as underline };
+    export { fontIconSvg as color };
+    export { linkIconSvg as link };
+    export { imageIconSvg as image };
+    export { tocIconSvg as tableOfContents };
+    export { alignLeftIconSvg as alignLeft };
+    export { alignRightIconSvg as alignRight };
+    export { alignCenterIconSvg as alignCenter };
+    export { alignJustifyIconSvg as alignJustify };
+    export { listIconSvg as bulletList };
+    export { listIconSvg as bulletListDisc };
+    export { listCircleIconSvg as bulletListCircle };
+    export { listSquareIconSvg as bulletListSquare };
+    export { listOlIconSvg as numberedList };
+    export { listDecimalIconSvg as numberedListDecimal };
+    export { listDecimalParenIconSvg as numberedListDecimalParen };
+    export { listUpperRomanIconSvg as numberedListUpperRoman };
+    export { listLowerRomanIconSvg as numberedListLowerRoman };
+    export { listUpperAlphaIconSvg as numberedListUpperAlpha };
+    export { listUpperAlphaParenIconSvg as numberedListUpperAlphaParen };
+    export { listLowerAlphaIconSvg as numberedListLowerAlpha };
+    export { listLowerAlphaParenIconSvg as numberedListLowerAlphaParen };
+    export { outdentIconSvg as indentLeft };
+    export { indentIconSvg as indentRight };
+    export { paragraphLtrIconSvg as directionLtr };
+    export { paragraphRtlIconSvg as directionRtl };
+    export { fileHalfDashedIconSvg as pageBreak };
+    export { paintRollerIconSvg as copyFormat };
+    export { textSlashIconSvg as clearFormatting };
+    export { listCheckIconSvg as trackChanges };
+    export { fileIconSvg as trackChangesFinal };
+    export { eyeIconSvg as trackChangesOriginal };
+    export { calendarCheckIconSvg as trackChangesAccept };
+    export { calendarXmarkIconSvg as trackChangesReject };
+    export { userEditIconSvg as documentMode };
+    export { userEditIconSvg as documentEditingMode };
+    export { commentIconSvg as documentSuggestingMode };
+    export { eyeIconSvg as documentViewingMode };
+    export { circleIconSvg as colorOption };
+    export { checkIconSvg as colorOptionCheck };
+    export { linkIconSvg as linkInput };
+    export { xmarkIconSvg as removeLink };
+    export { upRightFromSquareIconSvg as openLink };
+    export { ellipsisVerticalIconSvg as overflow };
+    export { caretUpIconSvg as dropdownCaretUp };
+    export { caretDownIconSvg as dropdownCaretDown };
+    export { rulerSvg as ruler };
+    export { paintbrushSvg as paintbrush };
+    export { highlighterIcon as highlight };
+    export { magicWandIcon as ai };
+    export { tableIconSvg as table };
+    export { tableColumnsIconSvg as tableActions };
+    export { arrowsLeftRightIconSvg as splitCell };
+    export { arrowsToDotIconSvg as mergeCells };
+    export { plusIconSvg as addRowBefore };
+    export { plusIconSvg as addRowAfter };
+    export { plusIconSvg as addColumnBefore };
+    export { plusIconSvg as addColumnAfter };
+    export { trashIconSvg as deleteRow };
+    export { trashIconSvg as deleteColumn };
+    export { trashIconSvg as deleteTable };
+    export { borderNoneIconSvg as deleteBorders };
+    export { wrenchIconSvg as fixTables };
+    export { upDownIconSvg as lineHeight };
+    export { magnifyingGlassSvg as search };
+    export { scissorsIconSvg as cut };
+    export { copyIconSvg as copy };
+    export { pasteIconSvg as paste };
+    export { strikethroughSvg as strikethrough };
+    export { paragraphIconSvg as formattingMarks };
+}

package/dist/superdoc/src/internal/toolbar/built-in/toolbarTexts.d.ts

@@ -0,0 +1,58 @@
+export namespace toolbarTexts {
+    let bold: string;
+    let fontFamily: string;
+    let ai: string;
+    let fontSize: string;
+    let italic: string;
+    let underline: string;
+    let highlight: string;
+    let strikethrough: string;
+    let color: string;
+    let search: string;
+    let link: string;
+    let image: string;
+    let tableOfContents: string;
+    let table: string;
+    let tableActions: string;
+    let addRowBefore: string;
+    let addRowAfter: string;
+    let addColumnBefore: string;
+    let addColumnAfter: string;
+    let deleteRow: string;
+    let deleteColumn: string;
+    let deleteTable: string;
+    let removeBorders: string;
+    let mergeCells: string;
+    let splitCell: string;
+    let fixTables: string;
+    let textAlign: string;
+    let bulletList: string;
+    let numberedList: string;
+    let indentLeft: string;
+    let indentRight: string;
+    let directionLtr: string;
+    let directionRtl: string;
+    let zoom: string;
+    let measurementUnit: string;
+    let undo: string;
+    let redo: string;
+    let trackChanges: string;
+    let trackChangesAccept: string;
+    let trackChangesReject: string;
+    let trackChangesOriginal: string;
+    let trackChangesFinal: string;
+    let clearFormatting: string;
+    let copyFormat: string;
+    let lineHeight: string;
+    let formatText: string;
+    let ruler: string;
+    let formattingMarks: string;
+    let pageBreak: string;
+    let documentEditingMode: string;
+    let documentSuggestingMode: string;
+    let documentViewingMode: string;
+    let documentEditingModeDescription: string;
+    let documentSuggestingModeDescription: string;
+    let documentViewingModeDescription: string;
+    let linkedStyles: string;
+}

package/dist/superdoc/src/internal/toolbar/built-in/url-safety.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Validate and normalize an href. Returns `{ href }` for safe values, or `null`.
+ * @param {string} value
+ * @returns {{ href: string }|null}
+ */
+export function sanitizeHref(value: string): {
+    href: string;
+} | null;

package/dist/superdoc/src/internal/toolbar/built-in/use-toolbar-item.d.ts

@@ -0,0 +1,48 @@
+export function useToolbarItem(options: any): {
+    unref: () => {};
+    activate: (attrs?: {}, ...args: any[]) => void;
+    deactivate: () => void;
+    setDisabled: (state: any) => void;
+    resetDisabled: () => void;
+    onActivate: any;
+    onDeactivate: any;
+    id: import('vue').Ref<string, string>;
+    name: import('vue').Ref<any, any>;
+    type: any;
+    command: any;
+    noArgumentCommand: any;
+    icon: import('vue').Ref<any, any>;
+    tooltip: import('vue').Ref<any, any>;
+    group: import('vue').Ref<any, any>;
+    attributes: import('vue').Ref<any, any>;
+    disabled: import('vue').Ref<any, any>;
+    active: import('vue').Ref<boolean, boolean>;
+    expand: import('vue').Ref<boolean, boolean>;
+    nestedOptions: import('vue').Ref<never[], never[]>;
+    style: import('vue').Ref<any, any>;
+    isNarrow: import('vue').Ref<any, any>;
+    isWide: import('vue').Ref<any, any>;
+    minWidth: import('vue').Ref<any, any>;
+    argument: import('vue').Ref<any, any>;
+    parentItem: import('vue').Ref<null, null>;
+    iconColor: import('vue').Ref<any, any>;
+    hasCaret: import('vue').Ref<any, any>;
+    splitButton: import('vue').Ref<boolean, boolean>;
+    splitButtonCommand: any;
+    dropdownStyles: import('vue').Ref<any, any>;
+    tooltipVisible: import('vue').Ref<any, any>;
+    tooltipTimeout: import('vue').Ref<any, any>;
+    defaultLabel: import('vue').Ref<any, any>;
+    label: import('vue').Ref<any, any>;
+    hideLabel: import('vue').Ref<any, any>;
+    inlineTextInputVisible: import('vue').Ref<any, any>;
+    hasInlineTextInput: import('vue').Ref<any, any>;
+    restoreEditorFocus: boolean;
+    markName: import('vue').Ref<any, any>;
+    labelAttr: import('vue').Ref<any, any>;
+    childItem: import('vue').Ref<null, null>;
+    allowWithoutEditor: import('vue').Ref<any, any>;
+    dropdownValueKey: import('vue').Ref<any, any>;
+    selectedValue: import('vue').Ref<any, any>;
+    inputRef: import('vue').Ref<any, any>;
+};

package/dist/superdoc/src/internal/toolbar/built-in-toolbar.d.ts

@@ -0,0 +1,237 @@
+import { EventEmitter } from 'eventemitter3';
+/**
+ * Create the rendered built-in toolbar for a `SuperDoc` instance.
+ * @param {object} config
+ * @returns {BuiltInToolbar}
+ */
+export function createBuiltInToolbar(config: object): BuiltInToolbar;
+/**
+ * The rendered built-in toolbar. Shape-compatible with the historical
+ * `superdoc.toolbar` (`SuperToolbar`) surface so existing docs, examples, the
+ * proof lane, and behavior tests resolve against a real object.
+ *
+ * @class
+ * @extends EventEmitter
+ */
+export class BuiltInToolbar extends EventEmitter<string | symbol, any> {
+    /**
+     * @param {object} config Toolbar config forwarded by `SuperDoc`. Requires
+     *   `superdoc`; `selector` is the mount target.
+     */
+    constructor(config?: object);
+    config: {
+        selector: null;
+        toolbarGroups: string[];
+        role: string;
+        icons: {
+            undo: any;
+            redo: any;
+            bold: any;
+            italic: any;
+            underline: any;
+            color: any;
+            link: any;
+            image: any;
+            tableOfContents: any;
+            alignLeft: any;
+            alignRight: any;
+            alignCenter: any;
+            alignJustify: any;
+            bulletList: any;
+            bulletListDisc: any;
+            bulletListCircle: any;
+            bulletListSquare: any;
+            numberedList: any;
+            numberedListDecimal: any;
+            numberedListDecimalParen: any;
+            numberedListUpperRoman: any;
+            numberedListLowerRoman: any;
+            numberedListUpperAlpha: any;
+            numberedListUpperAlphaParen: any;
+            numberedListLowerAlpha: any;
+            numberedListLowerAlphaParen: any;
+            indentLeft: any;
+            indentRight: any;
+            directionLtr: any;
+            directionRtl: any;
+            pageBreak: any;
+            copyFormat: any;
+            clearFormatting: any;
+            trackChanges: any;
+            trackChangesFinal: any;
+            trackChangesOriginal: any;
+            trackChangesAccept: any;
+            trackChangesReject: any;
+            documentMode: any;
+            documentEditingMode: any;
+            documentSuggestingMode: any;
+            documentViewingMode: any;
+            colorOption: any;
+            colorOptionCheck: any;
+            linkInput: any;
+            removeLink: any;
+            openLink: any;
+            overflow: any;
+            dropdownCaretUp: any;
+            dropdownCaretDown: any;
+            ruler: any;
+            paintbrush: any;
+            highlight: any;
+            ai: any;
+            table: any;
+            tableActions: any;
+            splitCell: any;
+            mergeCells: any;
+            addRowBefore: any;
+            addRowAfter: any;
+            addColumnBefore: any;
+            addColumnAfter: any;
+            deleteRow: any;
+            deleteColumn: any;
+            deleteTable: any;
+            deleteBorders: any;
+            fixTables: any;
+            lineHeight: any;
+            search: any;
+            cut: any;
+            copy: any;
+            paste: any;
+            strikethrough: any;
+            formattingMarks: any;
+        };
+        texts: {
+            bold: string;
+            fontFamily: string;
+            ai: string;
+            fontSize: string;
+            italic: string;
+            underline: string;
+            highlight: string;
+            strikethrough: string;
+            color: string;
+            search: string;
+            link: string;
+            image: string;
+            tableOfContents: string;
+            table: string;
+            tableActions: string;
+            addRowBefore: string;
+            addRowAfter: string;
+            addColumnBefore: string;
+            addColumnAfter: string;
+            deleteRow: string;
+            deleteColumn: string;
+            deleteTable: string;
+            removeBorders: string;
+            mergeCells: string;
+            splitCell: string;
+            fixTables: string;
+            textAlign: string;
+            bulletList: string;
+            numberedList: string;
+            indentLeft: string;
+            indentRight: string;
+            directionLtr: string;
+            directionRtl: string;
+            zoom: string;
+            measurementUnit: string;
+            undo: string;
+            redo: string;
+            trackChanges: string;
+            trackChangesAccept: string;
+            trackChangesReject: string;
+            trackChangesOriginal: string;
+            trackChangesFinal: string;
+            clearFormatting: string;
+            copyFormat: string;
+            lineHeight: string;
+            formatText: string;
+            ruler: string;
+            formattingMarks: string;
+            pageBreak: string;
+            documentEditingMode: string;
+            documentSuggestingMode: string;
+            documentViewingMode: string;
+            documentEditingModeDescription: string;
+            documentSuggestingModeDescription: string;
+            documentViewingModeDescription: string;
+            linkedStyles: string;
+        };
+        fonts: null;
+        hideButtons: boolean;
+        responsiveToContainer: boolean;
+        mode: string;
+        excludeItems: never[];
+        groups: null;
+        customButtons: never[];
+        showFormattingMarksButton: boolean;
+        showTableOfContentsButton: boolean;
+    };
+    toolbarItems: any[];
+    overflowItems: any[];
+    isDev: boolean;
+    role: string;
+    superdoc: any;
+    toolbarContainer: null;
+    toolbar: null;
+    _detachFontsChanged: null;
+    /** Active editor compatibility reference (set by `SuperDoc.setActiveEditor`). */
+    activeEditor: any;
+    /** SuperDoc-owned command controller (single command-state truth). */
+    ui: any;
+    /** Latest controller toolbar snapshot. */
+    snapshot: any;
+    /** Controller subscription unsubscribe handle. */
+    _unsubscribeController: any;
+    /** Format-painter mode subscription unsubscribe handle. */
+    _detachFormatPainterModeChange: any;
+    /** Registered custom-button command unregister handles. */
+    _customCommandRegs: Map<any, any>;
+    /** Signature of the last-built font options, to skip redundant rebuilds. */
+    _lastFontOptionsSignature: string;
+    app: import('vue').App<Element> | undefined;
+    getAvailableWidth(): any;
+    getToolbarItemByGroup(groupName: any): any[];
+    getToolbarItemByName(name: any): any;
+    /**
+     * The available linked-style options for the linked-styles dropdown. Projected
+     * from the shared controller's public `superdoc/ui` style catalogue
+     * (`ui.styles.getQuickGallery()`), which reads the Document API style catalogue
+     * (`styles.getCatalog`) and honors `w:qFormat` with a v1-style alphabetical
+     * fallback. Returns normalized `StyleCatalogItem`s (`id`, `name`, optional
+     * `preview.css`, visibility), never raw style-model shapes. Empty when the
+     * styles surface is unreachable (viewing mode, worker-backed editor, pre-ready
+     * editor). Applying a style still routes through the shared `linked-style`
+     * command, which targets `styles.paragraph.setStyle`.
+     * @returns {Array}
+     */
+    getLinkedStyleOptions(): any[];
+    /**
+     * The stable style id active across the current selection's paragraph(s), or
+     * `null` for a mixed selection / when the styles surface is unreachable. Used
+     * to mark the active option in the linked-styles dropdown.
+     * @returns {string|null}
+     */
+    getActiveLinkedStyleId(): string | null;
+    /**
+     * Compatibility hook: `SuperDoc` calls this when the active editor changes.
+     * The shared controller already tracks selection/transaction state, so this
+     * just refreshes font options (the new document may carry different fonts) and
+     * re-projects item state.
+     * @param {object|null} editor
+     */
+    setActiveEditor(editor: object | null): void;
+    onToolbarResize: () => void;
+    updateToolbarState(): void;
+    /**
+     * Main toolbar command entry point used by the rendered components.
+     * @param {{ item: object, argument?: unknown, option?: unknown }} params
+     */
+    emitCommand({ item, argument, option }: {
+        item: object;
+        argument?: unknown;
+        option?: unknown;
+    }): void;
+    destroy(): void;
+    #private;
+}

package/dist/superdoc/src/internal/toolbar/compatibility-catalog.d.ts

@@ -0,0 +1,59 @@
+/** Layout regions a built-in toolbar item can be placed in. */
+export type ToolbarGroup = 'left' | 'center' | 'right';
+/** How a documented built-in toolbar item is (or is not) backed on V2. */
+export type ToolbarItemDisposition = 'controller-routed' | 'host-routed' | 'shell-owned' | 'unsupported' | 'unresolved';
+/** One documented built-in toolbar item and how it maps onto V2. */
+export interface BuiltInToolbarItemEntry {
+    /** Legacy built-in item name (the id v1 toolbars and the docs use). */
+    readonly name: string;
+    /**
+     * Canonical V2 controller command id this item routes to. Present for
+     * `controller-routed` items; `null` for host/shell/unresolved items.
+     */
+    readonly commandId: string | null;
+    /**
+     * Public `SuperDoc`-instance method the built-in shell calls to drive this
+     * item. Present for `host-routed` items; `null` otherwise.
+     */
+    readonly instanceMethod: string | null;
+    /** Disposition bucket. */
+    readonly disposition: ToolbarItemDisposition;
+    /** Default layout group for the rendered shell. */
+    readonly group: ToolbarGroup;
+    /**
+     * Member controller command ids for an item that fans out into a family of
+     * commands (e.g. `tableActions`). Documentation + later renderer use.
+     */
+    readonly memberCommandIds?: readonly string[];
+    /**
+     * Stable explanation. Required for `host-routed`, `shell-owned`, and
+     * `unresolved` items so the non-controller disposition is never opaque.
+     */
+    readonly note?: string;
+}
+/**
+ * The built-in toolbar compatibility catalog. Order groups items the way the
+ * docs present them; it is documentation-only.
+ *
+ * Every documented `Available buttons` entry from
+ * `apps/docs/editor/built-in-ui/toolbar.mdx` appears here exactly once, plus the
+ * `customButtons` shell concept.
+ */
+export declare const BUILT_IN_TOOLBAR_CATALOG: readonly BuiltInToolbarItemEntry[];
+/** All documented built-in toolbar item names known to the catalog. */
+export declare const ALL_BUILT_IN_TOOLBAR_ITEM_NAMES: readonly string[];
+/** Resolve a built-in toolbar item entry by its legacy name, or `null`. */
+export declare function getBuiltInToolbarItem(name: string): BuiltInToolbarItemEntry | null;
+/** All built-in toolbar items declared for a layout group, in catalog order. */
+export declare function listBuiltInToolbarItemsByGroup(group: ToolbarGroup): BuiltInToolbarItemEntry[];
+/**
+ * Resolve a legacy built-in item name to its canonical V2 controller command
+ * id, or `null` when the item is not controller-routed.
+ */
+export declare function resolveToolbarCommandId(name: string): string | null;
+/**
+ * Cross-check the catalog against the V2 command controller catalog so the two
+ * cannot drift. Throws on the first inconsistency. Exercised by the unit tests;
+ * kept exported so a future renderer/build guard can reuse it.
+ */
+export declare function assertCatalogAlignedWithController(): void;