@embedpdf/core-ui 3.0.0-next.0

package/dist/index.d.ts

@@ -0,0 +1,364 @@
+//#region src/schema.d.ts
+/**
+ * @embedpdf/core-ui — the structure-only schema vocabulary.
+ *
+ * The schema contains ONLY what a designer decides and the runtime cannot
+ * compute: order, grouping, importance, and each item's degradation ladder.
+ * Everything the runtime CAN compute is banned from it by construction:
+ * no breakpoints, no show/hide lists, no locale overrides, no dividers, no
+ * spacers, no hand-written overflow menus. Fit is measured and solved at
+ * runtime (see solver.ts); the overflow menu is derived (see projection.ts).
+ */
+/** Presentation ladder for a command button, richest first. */
+type Variant = 'icon+label' | 'icon' | 'label';
+/**
+ * Who yields space first. 1 = first to degrade/overflow · 3 = default ·
+ * 5 = pinned: may still degrade variants, but NEVER leaves the bar.
+ */
+type Importance = 1 | 2 | 3 | 4 | 5;
+declare const PINNED: Importance;
+interface BarItem {
+  /** The command this button runs — the only required field. */
+  readonly command: string;
+  /** Degradation ladder, richest first. Default: ['icon']. */
+  readonly variants?: readonly Variant[];
+  readonly importance?: Importance;
+}
+/**
+ * An app-rendered slot (e.g. the inline zoom strip). Each named variant is
+ * measured like any command button. The ladder MUST terminate in a command
+ * (`terminal`) so the item always has a menu form when it overflows — this
+ * is what makes the overflow projection total.
+ */
+interface CustomItem {
+  readonly slot: string;
+  /** Named presentation variants, richest first. Default: ['default']. */
+  readonly variants?: readonly string[];
+  /** The command that stands in for this slot in menus (its last resort). */
+  readonly terminal: string;
+  readonly importance?: Importance;
+}
+type BarChild = BarItem | CustomItem | string;
+interface BarGroup {
+  readonly id: string;
+  /** Titles the group's menu form (labeled submenu / section heading). */
+  readonly labelKey?: string;
+  /** Presentation hint: 'tabs' renders as a tab strip and projects as radio rows. */
+  readonly role?: 'buttons' | 'tabs';
+  /**
+   * Stage 1 of the GROUP degradation ladder: under pressure, move trailing
+   * children (rightmost first, at the CHILD's importance) into a derived
+   * group-local disclosure — a trigger rendered inside the group opening a
+   * menu of the hidden children. Never sheds the last visible child: below
+   * that floor the group `collapse`s (stage 2) or overflows whole. This is
+   * v2's `overflow-tabs-button`, computed instead of authored.
+   */
+  readonly shed?: boolean;
+  /**
+   * Stage 2: what the WHOLE group degrades to once its children have
+   * exhausted their ladders (and shedding, if enabled, has hit its floor): a
+   * single menu button or a select-style picker. Groups with neither `shed`
+   * nor `collapse` send children to the global overflow menu one by one.
+   */
+  readonly collapse?: 'menu' | 'select';
+  readonly importance?: Importance;
+  readonly items: readonly BarChild[];
+}
+/**
+ * Alignment regions. Separators derive between adjacent visible groups
+ * within a section — never across sections, never from schema data.
+ *
+ * The names are direction-aware (RTL flips start/end) and `center` is a
+ * SOFT contract: "balance this segment in the space left over by start and
+ * end". With symmetric flanks that coincides with true centering; with a
+ * heavy flank the segment drifts rather than fights — segments never
+ * overlap, matching how every toolbar convention (including v2's
+ * spacer-flanked tabs) treats its middle region. Strict geometric centering
+ * would be a solver concern (a tighter budget: 2×max(start,end)+center),
+ * deliberately not offered until a product needs it.
+ */
+interface BarSections {
+  readonly start?: readonly BarGroup[];
+  readonly center?: readonly BarGroup[];
+  readonly end?: readonly BarGroup[];
+}
+interface BarSchema {
+  readonly id: string;
+  readonly sections: BarSections;
+}
+/** A run of command rows; separators derive between sections. */
+interface MenuSection {
+  /** Optional section heading (i18n key). */
+  readonly labelKey?: string;
+  readonly items: readonly string[];
+}
+interface MenuSchema {
+  readonly id: string;
+  readonly sections: readonly MenuSection[];
+}
+/**
+ * The shell FRAME — region arrangement and visibility. Regions are a FIXED
+ * vocabulary (each carries semantics the shell must own: the toolbar's
+ * measurement physics, the document gate, aria landmarks); what's YOURS is
+ * where they sit, whether they show, and — through the region slots — what
+ * fills them. Part of the chrome value because it is structure: owned, never
+ * merged. Free-form layout is deliberately not offered — wanting a different
+ * frame architecture is what headless is for.
+ */
+interface FrameSchema {
+  /** Where the main bar lives. Its mode band rides the CONTENT side (below a
+   *  top bar, above a bottom bar). Default: 'top'. */
+  readonly toolbar?: 'top' | 'bottom';
+  /** Document tab strip: 'multiple' shows it only with >1 tab. A hidden
+   *  region hides its SLOT too — visibility outranks slotted content.
+   *  Default: 'always'. */
+  readonly tabs?: 'always' | 'multiple' | 'never';
+  /** The header row — a socket only: the chrome ships no header of its own,
+   *  so it renders nothing until a `slot="header"` child fills it. `false`
+   *  removes the socket, keeping a slotted header out. Default: true. */
+  readonly header?: boolean;
+}
+interface ChromeSchema {
+  /** Standalone bars (e.g. the main toolbar). */
+  readonly bars: Readonly<Record<string, BarSchema>>;
+  /** Secondary bars keyed by tool mode — WHICH one shows is derived from the
+   *  interaction hub's active tool, never stored. */
+  readonly modeBars?: Readonly<Record<string, BarSchema>>;
+  /** Named dropdown menus referenced by commands' `menu:` targets. */
+  readonly menus?: Readonly<Record<string, MenuSchema>>;
+  /** Contextual strips (selection menus) — same BarSchema, same fit engine. */
+  readonly strips?: Readonly<Record<string, BarSchema>>;
+  /** Region arrangement & visibility. Omitted = the default frame. */
+  readonly frame?: FrameSchema;
+}
+declare function item(command: string, opts?: Omit<BarItem, 'command'>): BarItem;
+declare function custom(slot: string, opts: Omit<CustomItem, 'slot'>): CustomItem;
+declare function group(id: string, items: readonly BarChild[]): BarGroup;
+declare function group(id: string, opts: Omit<BarGroup, 'id' | 'items'> & {
+  items?: readonly BarChild[];
+}, items?: readonly BarChild[]): BarGroup;
+type NormalizedUnit = {
+  readonly kind: 'command';
+  /** Unique within the bar: `${groupId}:${command}`. Measurement + assignment key. */
+  readonly key: string;
+  readonly command: string;
+  readonly variants: readonly string[];
+  readonly importance: Importance;
+} | {
+  readonly kind: 'custom';
+  readonly key: string;
+  readonly slot: string;
+  readonly variants: readonly string[];
+  readonly terminal: string;
+  readonly importance: Importance;
+};
+interface NormalizedGroup {
+  readonly id: string;
+  readonly labelKey?: string;
+  readonly role: 'buttons' | 'tabs';
+  readonly shed: boolean;
+  readonly collapse?: 'menu' | 'select';
+  readonly importance: Importance;
+  readonly units: readonly NormalizedUnit[];
+}
+interface NormalizedSection {
+  readonly name: 'start' | 'center' | 'end';
+  readonly groups: readonly NormalizedGroup[];
+}
+interface NormalizedBar {
+  readonly id: string;
+  readonly sections: readonly NormalizedSection[];
+}
+declare const DEFAULT_IMPORTANCE: Importance;
+/** Resolve shorthands + defaults; validate uniqueness. Solver/projection input. */
+declare function normalizeBar(bar: BarSchema): NormalizedBar;
+/**
+ * Drop units whose command is currently invisible (permissions, disabled
+ * categories, contextual visibility) BEFORE solving — an invisible unit must
+ * not consume budget or appear in the overflow. Groups that empty out vanish
+ * naturally in the solver's separator math and in the projection.
+ */
+declare function filterBar(bar: NormalizedBar, keep: (unit: NormalizedUnit) => boolean): NormalizedBar;
+/**
+ * Identity + validation. Checks what is checkable without a command registry:
+ * bars normalize cleanly, and every `menu` a strip/bar could reference exists
+ * is left to `validateChrome` (which also takes the known command ids).
+ */
+declare function defineChrome<T extends ChromeSchema>(chrome: T): T;
+/** Dev-time cross-check: every command referenced by the chrome exists. */
+declare function validateChrome(chrome: ChromeSchema, knownCommands: ReadonlySet<string>): string[];
+//#endregion
+//#region src/transforms.d.ts
+interface AddItemSpec {
+  /** Bar id ('main', 'annotate', …) or a modeBars surface key ('mode:annotate'). */
+  readonly bar: string;
+  readonly section: keyof BarSections;
+  /** Target group id. Unknown in the bar → a new group is created at the end
+   *  of `section`; known but in a DIFFERENT section → error (group ids are
+   *  bar-unique, so that is a contradiction, not a request). */
+  readonly group: string;
+  readonly item: BarChild;
+  /** Insert position within the group. Default: append. */
+  readonly at?: number;
+}
+/** Insert `spec.item` into a group of one bar. See AddItemSpec for semantics. */
+declare function addItem(schema: ChromeSchema, spec: AddItemSpec): ChromeSchema;
+/**
+ * Purge commands (or custom slots, by slot name) from every bar, mode bar,
+ * strip, and menu. Groups and menu sections that empty out are dropped;
+ * emptied menus keep their key (commands may still target them) with no rows.
+ */
+declare function removeItems(schema: ChromeSchema, ids: readonly string[]): ChromeSchema;
+/**
+ * Swap a command in place everywhere it appears — bars, mode bars, strips,
+ * and (when the replacement is itself a plain command) menu rows.
+ */
+declare function replaceItem(schema: ChromeSchema, id: string, item: BarChild): ChromeSchema;
+//#endregion
+//#region src/helpers.d.ts
+declare const chromeHelpers: {
+  readonly addItem: typeof addItem;
+  readonly removeItems: typeof removeItems;
+  readonly replaceItem: typeof replaceItem;
+  readonly item: typeof item;
+  readonly group: typeof group;
+  readonly custom: typeof custom;
+  readonly defineChrome: typeof defineChrome;
+};
+type ChromeHelpers = typeof chromeHelpers;
+//#endregion
+//#region src/solver.d.ts
+interface FitMetrics {
+  /** Width of unit `key` rendered at `variant`; undefined = not yet measured. */
+  unit(key: string, variant: string): number | undefined;
+  /** Width of group `id` rendered in its collapsed form ('menu' | 'select'). */
+  groupCollapsed(groupId: string): number | undefined;
+  /** Width of group `id`'s disclosure trigger (shed groups only). */
+  groupTrigger(groupId: string): number | undefined;
+  /** Width of the overflow trigger button. */
+  readonly overflowTrigger: number;
+  /** Gap between adjacent visible units. */
+  readonly gap: number;
+  /** Width of a derived separator between adjacent visible groups (with its gaps). */
+  readonly separator: number;
+}
+type UnitAssignment = {
+  readonly kind: 'variant';
+  readonly variant: string;
+} | {
+  readonly kind: 'shed';
+} | {
+  readonly kind: 'collapsed';
+} | {
+  readonly kind: 'overflow';
+};
+interface GroupAssignment {
+  /** How many children sit behind the group's disclosure trigger. */
+  readonly shedCount: number;
+  /** The group renders as its single collapsed control. */
+  readonly collapsed: boolean;
+  /** No part of the group is visible in the bar. */
+  readonly overflowed: boolean;
+}
+interface FitResult {
+  readonly units: ReadonlyMap<string, UnitAssignment>;
+  readonly groups: ReadonlyMap<string, GroupAssignment>;
+  readonly hasOverflow: boolean;
+  /** Total visible width at this assignment (diagnostics + tests). */
+  readonly width: number;
+  /** False when any consulted measurement was missing (treated as 0). */
+  readonly complete: boolean;
+}
+declare function solve(bar: NormalizedBar, metrics: FitMetrics, containerWidth: number): FitResult;
+//#endregion
+//#region src/projection.d.ts
+type OverflowRow =
+/** A plain command row. The renderer resolves label/icon/active from the registry. */
+{
+  readonly type: 'command';
+  readonly command: string;
+} |
+/** A command that opens a menu — renders as `label ▸` nesting that menu. */
+{
+  readonly type: 'submenu';
+  readonly command: string;
+  readonly menu: string;
+};
+interface OverflowSection {
+  /** From the group's labelKey — render as a section title or a nested submenu. */
+  readonly labelKey?: string;
+  /** 'radio' when the group is a tab strip: exactly one row is active. */
+  readonly role?: 'radio';
+  readonly rows: readonly OverflowRow[];
+}
+/**
+ * The one fact projection needs about a command: does it open a menu?
+ * (Label, icon, and active state stay live in the renderer.) Return null for
+ * unknown commands — they project as plain rows and resolve at render time.
+ */
+type ResolveMenuTarget = (commandId: string) => {
+  menu?: string;
+} | null;
+declare function projectOverflow(bar: NormalizedBar, fit: FitResult, resolve: ResolveMenuTarget): OverflowSection[];
+/**
+ * The content of a group's disclosure trigger: its shed units, in bar order,
+ * in menu form — same totality rules as the global overflow. This is v2's
+ * hand-written `mode-tabs-overflow-menu`, derived.
+ */
+declare function projectShed(group: NormalizedGroup, fit: FitResult, resolve: ResolveMenuTarget): OverflowRow[];
+/** One strip group: a separator boundary, its visible commands in bar order. */
+interface StripGroup {
+  readonly id: string;
+  readonly labelKey?: string;
+  readonly commands: readonly string[];
+}
+/**
+ * Strip projection — a bar projected for UN-measured rendering (a contextual
+ * strip anchored to a selection has no fit pressure to solve). The schema
+ * declares what COULD appear; `visible` (the command registry's runtime truth)
+ * decides what DOES: hidden commands drop out, groups that empty out vanish,
+ * and an all-hidden bar projects to [] — "render nothing" falls out. Custom
+ * units project through their `terminal` command, same totality rule as the
+ * overflow. Upgrading a strip to measured/overflowing rendering later is a
+ * renderer swap (<Toolbar>), never a schema change.
+ */
+declare function projectStrip(bar: NormalizedBar, visible: (command: string) => boolean): StripGroup[];
+//#endregion
+//#region src/shortcuts.d.ts
+/**
+ * Shortcut parsing + matching — pure. No `navigator`: platform is an input
+ * (`isMac`), decided by the embedder, same rule as plugin-i18n's locale.
+ *
+ * Grammar: modifiers and one key joined by '+', e.g. 'Mod+K', 'Ctrl+=',
+ * 'Shift+Alt+D', 'Meta+NumpadAdd'. 'Mod' is ⌘ on mac and Ctrl elsewhere.
+ * Keys longer than one character (F1, Escape, NumpadAdd, ArrowLeft) match
+ * `event.key` OR `event.code` case-insensitively, so numpad shortcuts work.
+ */
+interface ParsedShortcut {
+  readonly key: string;
+  readonly mod: boolean;
+  readonly ctrl: boolean;
+  readonly meta: boolean;
+  readonly alt: boolean;
+  readonly shift: boolean;
+}
+/** The subset of KeyboardEvent the matcher reads — keeps this module DOM-free. */
+interface KeyStroke {
+  readonly key: string;
+  readonly code?: string;
+  readonly ctrlKey: boolean;
+  readonly metaKey: boolean;
+  readonly altKey: boolean;
+  readonly shiftKey: boolean;
+}
+declare function parseShortcut(shortcut: string): ParsedShortcut;
+declare function matchShortcut(parsed: ParsedShortcut, stroke: KeyStroke, opts: {
+  isMac: boolean;
+}): boolean;
+/** Display form for menu rows: '⌘K' on mac, 'Ctrl+K' elsewhere. */
+declare function formatShortcut(shortcut: string, opts: {
+  isMac: boolean;
+}): string;
+//#endregion
+export { type AddItemSpec, type BarChild, type BarGroup, type BarItem, type BarSchema, type BarSections, type ChromeHelpers, type ChromeSchema, type CustomItem, DEFAULT_IMPORTANCE, type FitMetrics, type FitResult, type FrameSchema, type GroupAssignment, type Importance, type KeyStroke, type MenuSchema, type MenuSection, type NormalizedBar, type NormalizedGroup, type NormalizedSection, type NormalizedUnit, type OverflowRow, type OverflowSection, PINNED, type ParsedShortcut, type ResolveMenuTarget, type StripGroup, type UnitAssignment, type Variant, addItem, chromeHelpers, custom, defineChrome, filterBar, formatShortcut, group, item, matchShortcut, normalizeBar, parseShortcut, projectOverflow, projectShed, projectStrip, removeItems, replaceItem, solve, validateChrome };
+//# sourceMappingURL=index.d.ts.map