ooxml-ui 0.27.2 → 0.28.0

package/dist/xlsx/ribbon/controls-input.d.ts

@@ -0,0 +1,22 @@
+import type { Command } from 'ooxml-core/xlsx/ui';
+import { type RenderScope } from './controls';
+import type { RibbonControl } from 'ooxml-core/xlsx/ui';
+type SelectControl = Extract<RibbonControl, {
+    kind: 'select';
+}>;
+type GalleryControl = Extract<RibbonControl, {
+    kind: 'gallery';
+}>;
+/** A native `<select>` (number format, ...) or, with `editable`, a combo box (font, size). */
+export declare function renderSelect(scope: RenderScope, control: SelectControl, command: Command): HTMLElement;
+/**
+ * Parses preview SVG markup into a node without scripts, foreign content, event handlers or
+ * script URLs (style names in a preview can come from the workbook).
+ */
+export declare function safeSvg(doc: Document, markup: string): Element | null;
+/**
+ * A gallery command (Format as Table, Cell Styles): a large button with a caret, as Excel shows it
+ * on a ribbon of ordinary width, opening every item as preview tiles in a grid.
+ */
+export declare function renderGallery(scope: RenderScope, control: GalleryControl, command: Command): HTMLElement;
+export {};

package/dist/xlsx/ribbon/controls.d.ts

@@ -0,0 +1,28 @@
+import type { Command } from 'ooxml-core/xlsx/ui';
+import type { EditorContext } from 'ooxml-core/xlsx/ui';
+import { type RibbonControl, type RibbonMenuItem } from 'ooxml-core/xlsx/ui';
+import { type MenuEntry } from './popover';
+export interface RenderScope {
+    ctx: EditorContext;
+    doc: Document;
+    /** Refresh hooks, run on every `requestRender`. */
+    updates: Array<() => void>;
+    /** Command ids the host hid (`hiddenActions`). */
+    isHidden(id: string): boolean;
+}
+export declare const el: <K extends keyof HTMLElementTagNameMap>(doc: Document, tag: K, className?: string) => HTMLElementTagNameMap[K];
+/** `Bold (Ctrl+B)` tooltip text for a command. */
+export declare const tooltip: (ctx: EditorContext, command: Command) => string;
+/** Marks a control with its command id (hidden actions, Tell me, KeyTips, Customize Ribbon). */
+export declare function tagCommand(node: HTMLElement, command: Command): void;
+/** A command button: `large` stacks a 28px icon over its caption; small shows a 16px icon. */
+export declare function commandButton(scope: RenderScope, command: Command, options?: {
+    size?: 'large' | 'small';
+    showLabel?: boolean;
+    toggle?: boolean;
+    caption?: boolean;
+}): HTMLButtonElement;
+/** Menu entries for spec items; items whose command is not registered are left out. */
+export declare function menuEntries(scope: RenderScope, items: RibbonMenuItem[]): MenuEntry[];
+/** Renders a control, or null when its command is not registered. */
+export declare function renderControl(scope: RenderScope, control: RibbonControl, inStack?: boolean): HTMLElement | null;

package/dist/xlsx/ribbon/icons.d.ts

@@ -0,0 +1,8 @@
+/** Adds or replaces a 24x24 line icon for ribbon commands. Returns false for an empty name or path. */
+export declare function registerRibbonIcon(name: string, path: string): boolean;
+export declare function hasRibbonIcon(name: string | undefined): boolean;
+/**
+ * An `<svg>` for `name` at `size` CSS pixels: a ribbon icon (24-unit grid) or, failing that, an
+ * ooxml-ui icon (20-unit grid, registered with `registerIcon`). Unknown names draw nothing.
+ */
+export declare function ribbonIcon(doc: Document, name: string | undefined, size?: number): SVGSVGElement;

package/dist/xlsx/ribbon/keytips.d.ts

@@ -0,0 +1,12 @@
+/**
+ * KeyTips (Alt or F10): badges over the tabs, then over the chosen tab's commands; typing the
+ * letters runs the control. Excel's own keys where this ribbon has the same command, otherwise
+ * two letters from the label, never the prefix of another. Ported from docx-viewer's
+ * ribbon-keytips.ts and ribbon-behavior.ts.
+ */
+import { type KeyTipTarget as Target } from '../../controls';
+/** Tips for the visible controls of `panel`. */
+export declare function collectKeyTips(panel: HTMLElement): Target[];
+/** Level one: tab badges; picking a tab opens it and shows its command badges (level two). */
+export declare function showTabKeyTips(root: HTMLElement, select: (id: string) => void): void;
+export declare function hideKeyTips(): void;

package/dist/xlsx/ribbon/overflow.d.ts

@@ -0,0 +1,3 @@
+export declare const fitPanel: (panel: HTMLElement) => void;
+export declare const attachRibbonOverflow: (root: HTMLElement) => () => void;
+export declare const refitRibbon: (root: HTMLElement) => void;

package/dist/xlsx/ribbon/popover.d.ts

@@ -0,0 +1,30 @@
+/** Closes whichever ribbon popover is open. */
+export declare function closeRibbonPopover(): void;
+export declare function isPopoverOpen(): boolean;
+/**
+ * Shows `pop` under `anchor` (appended to the anchor's shadow root). Returns false, closing it,
+ * when the same anchor was already open, so a caret works as a toggle.
+ */
+export declare function mountPopover(anchor: HTMLElement, pop: HTMLElement, expanded?: HTMLElement, onClose?: () => void): boolean;
+/** Up/Down (and Home/End) move focus through `items`, wrapping. */
+export declare function arrowNavigation(container: HTMLElement, selector: string): void;
+export type MenuEntry = {
+    label: string;
+    icon?: string;
+    shortcut?: string;
+    disabled?: boolean;
+    checked?: boolean;
+    run(): void;
+} | {
+    separator: true;
+};
+/** A vertical command menu under `anchor`; the first enabled item takes focus. */
+export declare function openMenu(anchor: HTMLElement, entries: MenuEntry[], label?: string): HTMLElement | null;
+/** A scrolling option list under a combo box with `current` marked; `preview` sets each font. */
+export declare function openList(anchor: HTMLElement, items: readonly {
+    value: string;
+    label: string;
+}[], current: string, choose: (value: string) => void, options?: {
+    preview?: boolean;
+    expanded?: HTMLElement;
+}): void;

package/dist/xlsx/ribbon/ribbon.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The ribbon renderer: the registered tabs (contextual ones only while their test passes), one panel per
+ * tab with labelled groups and dialog launchers, KeyTips, hidden actions and overflow folding. The tab
+ * row, File button, collapse and peek belong to the shared `office-ui-ribbon`. Structure and look follow docx-viewer's ribbon.ts.
+ */
+import type { EditorContext } from 'ooxml-core/xlsx/ui';
+export interface RibbonHandlers {
+    openBackstage(): void;
+    isHidden(id: string): boolean;
+}
+export interface Ribbon {
+    readonly element: HTMLElement;
+    /** Re-reads every control state (enabled, pressed, values) and the contextual tabs. */
+    refresh(): void;
+    /** Rebuilds all tabs (after a locale change or newly registered tabs). */
+    rebuild(): void;
+    selectTab(id: string): void;
+    activeTab(): string | undefined;
+    /** Alt / F10: focus the selected tab and show the tab KeyTips. */
+    showKeyTips(): void;
+    focus(): void;
+    destroy(): void;
+}
+export declare function createRibbon(ctx: EditorContext, handlers: RibbonHandlers): Ribbon;

package/dist/xlsx/ribbon/tabs/contextual.d.ts

@@ -0,0 +1,3 @@
+import type { RibbonTab } from 'ooxml-core/xlsx/ui';
+export declare function tableDesignTab(): RibbonTab;
+export declare function chartDesignTab(): RibbonTab;

package/dist/xlsx/ribbon/tabs/formulas-data.d.ts

@@ -0,0 +1,3 @@
+import type { RibbonTab } from 'ooxml-core/xlsx/ui';
+export declare function formulasTab(): RibbonTab;
+export declare function dataTab(): RibbonTab;

package/dist/xlsx/ribbon/tabs/home-groups.d.ts

@@ -0,0 +1,6 @@
+import type { RibbonGroup, RibbonMenuItem } from 'ooxml-core/xlsx/ui';
+export declare const sep: RibbonMenuItem;
+export declare const items: (...ids: string[]) => RibbonMenuItem[];
+export declare const SORT_FILTER_MENU: RibbonMenuItem[];
+export declare const AUTOSUM_MENU: RibbonMenuItem[];
+export declare function homeStyleGroups(): RibbonGroup[];

package/dist/xlsx/ribbon/tabs/home.d.ts

@@ -0,0 +1,3 @@
+import type { RibbonTab } from 'ooxml-core/xlsx/ui';
+export { AUTOSUM_MENU, SORT_FILTER_MENU } from './home-groups.js';
+export declare function homeTab(): RibbonTab;

package/dist/xlsx/ribbon/tabs/index.d.ts

@@ -0,0 +1,2 @@
+import type { RibbonTab } from 'ooxml-core/xlsx/ui';
+export declare function commandTabs(): RibbonTab[];

package/dist/xlsx/ribbon/tabs/insert-layout.d.ts

@@ -0,0 +1,3 @@
+import type { RibbonTab } from 'ooxml-core/xlsx/ui';
+export declare function insertTab(): RibbonTab;
+export declare function pageLayoutTab(): RibbonTab;

package/dist/xlsx/ribbon/visibility.d.ts

@@ -0,0 +1 @@
+export declare function applyRibbonVisibility(root: HTMLElement, isHidden: (id: string) => boolean): void;

package/dist/xlsx/sheet-tabs/drag.d.ts

@@ -0,0 +1,12 @@
+/** The sheet index a sheet dropped before visible slot `slot` ends up at (`moveSheet` target). */
+export declare function dropTarget(visible: number[], from: number, slot: number): number;
+/** The visible slot (0..n) whose gap is nearest to `clientX`. */
+export declare function slotAt(tabs: HTMLElement[], clientX: number): number;
+export interface DragHost {
+    strip: HTMLElement;
+    enabled(): boolean;
+    visible(): number[];
+    move(from: number, to: number): void;
+}
+/** Wires pointer dragging on the strip; returns a disposer. */
+export declare function wireTabDrag(host: DragHost): () => void;

package/dist/xlsx/sheet-tabs/index.d.ts

@@ -0,0 +1,4 @@
+import type { EditorContext } from 'ooxml-core/xlsx/ui';
+export { dropTarget, slotAt } from './drag.js';
+export { visibleSheetIndices } from './render.js';
+export declare function mountSheetTabs(ctx: EditorContext, container: HTMLElement): () => void;

package/dist/xlsx/sheet-tabs/rename.d.ts

@@ -0,0 +1,8 @@
+import type { EditorContext } from 'ooxml-core/xlsx/ui';
+export interface RenameHandle {
+    input: HTMLInputElement;
+    /** Commits; false when the name was rejected (the input stays open). */
+    commit(): boolean;
+    cancel(): void;
+}
+export declare function startRename(ctx: EditorContext, tab: HTMLElement, index: number, done: (renamed: boolean) => void): RenameHandle | undefined;

package/dist/xlsx/sheet-tabs/render.d.ts

@@ -0,0 +1,15 @@
+import { type Workbook } from 'ooxml-core/xlsx';
+/** Indices of the sheets that get a tab. */
+export declare const visibleSheetIndices: (workbook: Workbook) => number[];
+export interface TabRenderOptions {
+    workbook: Workbook;
+    active: number;
+    /** Sheet index of the tab that takes part in the tab order (roving tabindex). */
+    focusable: number;
+}
+/** Replaces the strip's tabs; the insertion marker and rename input are re-added by callers. */
+export declare function renderTabs(doc: Document, strip: HTMLElement, options: TabRenderOptions): void;
+/** The tab element of a sheet. */
+export declare const tabFor: (strip: HTMLElement, sheet: number) => HTMLElement | null;
+/** Sheet index of a tab element (or of the tab containing a node). */
+export declare function sheetOf(node: EventTarget | null): number | undefined;

package/dist/xlsx/sheet-tabs/styles.d.ts

@@ -0,0 +1 @@
+export declare const TABS_CSS = "\n.xst {\n\tdisplay: flex;\n\talign-items: stretch;\n\theight: 32px;\n\tbox-sizing: border-box;\n\tborder-top: 1px solid var(--xve-border, #e1dfdd);\n\tbackground: var(--xve-secondary, #f3f2f1);\n\tcolor: var(--xve-foreground, #242424);\n\tfont: 13px/1 'Segoe UI', system-ui, -apple-system, sans-serif;\n\tuser-select: none;\n\toverflow: hidden;\n}\n.xst-nav {\n\tdisplay: flex;\n\talign-items: center;\n\tgap: 2px;\n\tpadding: 0 4px;\n\tflex: none;\n}\n.xst-btn {\n\tdisplay: inline-flex;\n\talign-items: center;\n\tjustify-content: center;\n\twidth: 28px;\n\theight: 26px;\n\tpadding: 0;\n\tborder: 0;\n\tborder-radius: 4px;\n\tbackground: transparent;\n\tcolor: inherit;\n\tfont: inherit;\n\tfont-size: 14px;\n\tcursor: pointer;\n}\n.xst-btn:hover:not(:disabled) { background: var(--xve-accent, #e1dfdd); }\n.xst-btn:disabled { color: var(--xve-muted-foreground, #a19f9d); cursor: default; }\n.xst-btn:focus-visible, .xst-tab:focus-visible {\n\toutline: 2px solid var(--xve-ring, #616161);\n\toutline-offset: -2px;\n}\n.xst-btn[hidden] { display: none; }\n.xst-strip {\n\tposition: relative;\n\tdisplay: flex;\n\talign-items: stretch;\n\tflex: 1;\n\tmin-width: 0;\n\toverflow: hidden;\n\tscroll-behavior: smooth;\n}\n.xst-tab {\n\tposition: relative;\n\tdisplay: inline-flex;\n\talign-items: center;\n\tflex: none;\n\tmax-width: 240px;\n\tpadding: 0 14px;\n\tborder: 0;\n\tborder-right: 1px solid var(--xve-border, #e1dfdd);\n\tbackground: transparent;\n\tcolor: inherit;\n\tfont: inherit;\n\twhite-space: nowrap;\n\tcursor: pointer;\n}\n.xst-tab:hover:not(.xst-active) { background: var(--xve-accent, #e9e8e7); }\n.xst-tab .xst-label { overflow: hidden; text-overflow: ellipsis; }\n.xst-tab::after {\n\tcontent: '';\n\tposition: absolute;\n\tleft: 8px;\n\tright: 8px;\n\tbottom: 2px;\n\theight: 3px;\n\tborder-radius: 2px;\n\tbackground: var(--xst-color, transparent);\n}\n.xst-tab.xst-colored:not(.xst-active) {\n\tbackground: color-mix(in srgb, var(--xst-color) 22%, transparent);\n}\n.xst-tab.xst-active {\n\tbackground: var(--xve-sheet-bg, #ffffff);\n\tcolor: var(--xve-selection-border, #217346);\n\tfont-weight: 600;\n}\n.xst-tab.xst-active::after {\n\tbackground: var(--xve-selection-border, #217346);\n}\n.xst-tab.xst-active.xst-colored::after { background: var(--xst-color); }\n.xst-tab.xst-dragging { opacity: 0.6; }\n.xst-rename {\n\twidth: 120px;\n\theight: 22px;\n\tbox-sizing: border-box;\n\tpadding: 0 4px;\n\tborder: 1px solid var(--xve-selection-border, #217346);\n\tborder-radius: 2px;\n\tfont: inherit;\n\tcolor: var(--xve-foreground, #242424);\n\tbackground: var(--xve-sheet-bg, #ffffff);\n}\n.xst-marker {\n\tposition: absolute;\n\ttop: 4px;\n\tbottom: 4px;\n\twidth: 2px;\n\tmargin-left: -1px;\n\tbackground: var(--xve-selection-border, #217346);\n\tpointer-events: none;\n}\n";

package/dist/xlsx/shell-commands.d.ts

@@ -0,0 +1,13 @@
+import type { Command } from 'ooxml-core/xlsx/ui';
+import type { EditorContext } from 'ooxml-core/xlsx/ui';
+import type { FileCommand } from './events';
+export interface ShellCommandHandlers {
+    fileCommand(command: FileCommand): void;
+    openBackstage(page: 'info' | 'saveAs' | 'options' | 'new'): void;
+    showShortcuts(): void;
+    formulaBarShown(): boolean;
+    setFormulaBarShown(shown: boolean): void;
+}
+/** The next visible sheet from the active one in `step` direction, or undefined at the end. */
+export declare function adjacentSheet(ctx: EditorContext, step: 1 | -1): number | undefined;
+export declare function shellCommands(handlers: ShellCommandHandlers): Command[];

package/dist/xlsx/shortcut-help.d.ts

@@ -0,0 +1,15 @@
+/** The keyboard shortcut help dialog (Ctrl+/ or F1): the global map plus every command's shortcut. */
+import type { EditorContext } from 'ooxml-core/xlsx/ui';
+export interface ShortcutRow {
+    label: string;
+    keys: string;
+}
+/** Rows in display order: the global shortcuts, then commands that declare their own (grid keys). */
+export declare function shortcutRows(ctx: EditorContext, mac?: boolean): ShortcutRow[];
+export interface ShortcutHelp {
+    readonly element: HTMLElement;
+    readonly isOpen: boolean;
+    open(): void;
+    close(): void;
+}
+export declare function createShortcutHelp(ctx: EditorContext, onClose: () => void): ShortcutHelp;

package/dist/xlsx/status-bar.d.ts

@@ -0,0 +1,26 @@
+import type { EditorContext } from 'ooxml-core/xlsx/ui';
+export declare const ZOOM_MIN = 10;
+export declare const ZOOM_MAX = 400;
+export type StatKey = 'average' | 'count' | 'numericCount' | 'min' | 'max' | 'sum';
+declare const MODE_LABELS: {
+    readonly ready: 'Ready';
+    readonly enter: 'Enter';
+    readonly edit: 'Edit';
+    readonly point: 'Point';
+};
+type CellMode = keyof typeof MODE_LABELS;
+/** Excel's mode indicator: the grid's own `mode()` when it has one, else Ready / Edit. */
+export declare function cellMode(ctx: EditorContext): CellMode;
+export interface StatusBarHandlers {
+    showNotes(): void;
+    setZoom(percent: number): void;
+}
+export interface StatusBar {
+    readonly element: HTMLElement;
+    refresh(): void;
+    relocalize(): void;
+}
+/** The statistics text for the current selection, or '' when Excel shows none (one cell). */
+export declare function statisticsText(ctx: EditorContext, shown: ReadonlySet<StatKey>): string;
+export declare function createStatusBar(ctx: EditorContext, handlers: StatusBarHandlers): StatusBar;
+export {};

package/dist/xlsx/test-support/shell.d.ts

@@ -0,0 +1,19 @@
+import { type Workbook } from 'ooxml-core/xlsx';
+import type { Command } from 'ooxml-core/xlsx/ui';
+import { EditorCore } from '../editor-core';
+export interface ShellFixture {
+    core: EditorCore;
+    host: HTMLElement;
+    events: {
+        type: string;
+        detail: unknown;
+    }[];
+}
+/** A core with `workbook` loaded (a blank one by default) and every public event recorded. */
+export declare function shellFixture(workbook?: Workbook | null): ShellFixture;
+/** A command that records its runs; `state` drives enabled/checked/value. */
+export declare function spyCommand(id: string, extra?: Partial<Command>): Command & {
+    runs: unknown[];
+};
+/** Lets queued microtasks (debounced renders) run. */
+export declare const flush: () => Promise<void>;

package/dist/xlsx/theme/index.d.ts

@@ -0,0 +1,5 @@
+export { lightTheme, darkTheme } from 'ooxml-core/xlsx/ui';
+export { themeToCssVars, THEME_KEYS } from 'ooxml-core/xlsx/ui';
+export { applyThemeColors, normalizeThemeMode } from 'ooxml-core/xlsx/ui';
+export { editorStyleText, themeTokenText } from './styles';
+export type { XlsxTheme, EditorThemeMode } from 'ooxml-core/xlsx/ui';

package/dist/xlsx/theme/styles.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Token presets generated from theme/defaults.ts so the TypeScript presets and the shadow-root CSS
+ * cannot drift. `theme="auto"` (the default) follows the OS; explicit values always win.
+ */
+export declare const themeTokenText: string;
+/** The shell stylesheet (tokens, chrome, ribbon, popups, backstage) for the shadow root. */
+export declare const editorStyleText: string;

package/dist/xlsx/title-bar.d.ts

@@ -0,0 +1,17 @@
+import type { EditorContext } from 'ooxml-core/xlsx/ui';
+import { type TellMeHandlers } from 'ooxml-core/xlsx/ui';
+export type SaveState = 'saved' | 'dirty' | 'saving' | 'saved-local';
+export interface TitleBarHandlers extends TellMeHandlers {
+    save(): void;
+    setReadOnly(readOnly: boolean): void;
+}
+export interface TitleBar {
+    readonly element: HTMLElement;
+    setFileName(name: string): void;
+    setSaveState(state: SaveState): void;
+    /** Re-reads read-only, undo/redo and comments state. */
+    refresh(): void;
+    relocalize(): void;
+    focusTellMe(): void;
+}
+export declare function createTitleBar(ctx: EditorContext, handlers: TitleBarHandlers): TitleBar;

package/dist/xlsx/toast.d.ts

@@ -0,0 +1,8 @@
+/** Short notices in the editor's corner (save compatibility, command failures). */
+export type ToastKind = 'info' | 'warning' | 'error';
+export interface Toaster {
+    readonly element: HTMLElement;
+    show(message: string, kind?: ToastKind, timeoutMs?: number): void;
+    clear(): void;
+}
+export declare function createToaster(doc: Document, closeLabel: () => string): Toaster;