@lofcz/embedpdf-plugin-commands 2.15.0 → 3.0.0-next.7

package/dist/index.d.cts

@@ -0,0 +1,150 @@
+import { CapabilityToken, CoreState } from "@embedpdf/core";
+import { KeyStroke } from "@embedpdf/core-ui";
+//#region src/types.d.ts
+/**
+ * @embedpdf/plugin-commands — the contract.
+ *
+ * Commands are the single vocabulary of verbs: toolbars, menus, contextual
+ * strips, shortcuts, and the palette are all projections of this registry.
+ * The plugin ships ZERO commands (mechanism here, definitions in the product
+ * — same split as plugin-i18n's locale packs).
+ *
+ * Command state is a pure DERIVATION over the store: `resolve()` reads other
+ * capabilities' selectors at call time, so any store change is reflected on
+ * the next read and the framework binding's one change stream makes every
+ * consumer reactive. There is no CommandStateChangedEvent, no diffing, no
+ * cache — v2's entire notification apparatus has no v3 equivalent because
+ * the reactive store subsumes it.
+ *
+ * Definitions hold functions, so they live in the plugin's registry (config
+ * + `register()`), never in the store; store state is only the serializable
+ * `disabledCategories`.
+ */
+/** What a derivation or `run` sees: capability resolution bound to the
+ *  command's target document (explicit, else the active one). */
+interface CommandCtx {
+  /** The target document, or null when no document is open. */
+  readonly documentId: string | null;
+  core(): CoreState;
+  /** Resolve a capability; document-scoped tokens bind to the target document. */
+  get<T>(token: CapabilityToken<T>): T;
+  /** Like `get`, but null when unavailable (no provider / no document). */
+  tryGet<T>(token: CapabilityToken<T>): T | null;
+}
+/**
+ * Up to two theme colors accompanying a command's icon — typed FACTS any
+ * renderer can interpret (tint a glyph's slots, show a swatch), never
+ * renderer props. The registry carries it the way it carries `icon`: as
+ * data it doesn't interpret. Deliberately NOT v2's `iconProps` bag —
+ * renderer-specific needs live app-side, joined by command id.
+ */
+interface IconAccent {
+  /** The mark: stroke / markup / font color. */
+  readonly primary?: string;
+  /** The fill, when there is one. */
+  readonly secondary?: string;
+}
+interface CommandDef {
+  /** Convention: 'domain:verb' — 'zoom:in', 'mode:annotate', 'panel:search'. */
+  readonly id: string;
+  /** i18n key, resolved through I18nToken when present (else shown verbatim). */
+  readonly labelKey: string;
+  readonly icon?: string;
+  /** Live color accent for the icon (a tool previewing its drawing defaults).
+   *  A pure derivation over the store, exactly like `active`/`enabled`. */
+  readonly iconAccent?: (ctx: CommandCtx) => IconAccent | null;
+  /** 'Mod+K' style (ui-core grammar). Multiple bindings allowed. */
+  readonly shortcut?: string | readonly string[];
+  /** Feature-gating tags: a disabled category hides its commands everywhere. */
+  readonly categories?: readonly string[];
+  /** Toggles a named dropdown menu (a MenuSchema id in the app's chrome). */
+  readonly menu?: string;
+  /** Toggles a named shell surface, optionally exclusive within a tag ('left'…). */
+  readonly panel?: string | {
+    readonly id: string;
+    readonly exclusive?: string;
+  };
+  /** Toggles a modal surface (exclusive within the built-in 'modal' tag). */
+  readonly modal?: string;
+  readonly enabled?: (ctx: CommandCtx) => boolean;
+  readonly active?: (ctx: CommandCtx) => boolean;
+  readonly visible?: (ctx: CommandCtx) => boolean;
+  /** The verb. Optional for pure surface-target commands. Runs before the
+   *  default target routing when both are present. */
+  readonly run?: (ctx: CommandCtx) => void;
+}
+/** A command as a renderer sees it — everything resolved for the target document. */
+interface ResolvedCommand {
+  readonly id: string;
+  readonly label: string;
+  readonly icon?: string;
+  readonly iconAccent?: IconAccent;
+  readonly shortcuts: readonly string[];
+  readonly menu?: string;
+  readonly enabled: boolean;
+  readonly active: boolean;
+  readonly visible: boolean;
+  readonly categories: readonly string[];
+}
+/** Value equality over resolved commands — `resolve()` mints a fresh object
+ *  per read, so reactive bindings memo by value to re-render on real change. */
+declare const resolvedCommandsEqual: (a: ResolvedCommand | null, b: ResolvedCommand | null) => boolean;
+interface CommandsState {
+  readonly disabledCategories: readonly string[];
+}
+type CommandsAction = {
+  type: 'COMMANDS/DISABLE_CATEGORY';
+  category: string;
+} | {
+  type: 'COMMANDS/ENABLE_CATEGORY';
+  category: string;
+} | {
+  type: 'COMMANDS/SET_DISABLED_CATEGORIES';
+  categories: readonly string[];
+};
+interface CommandsConfig {
+  /** The app's command definitions (content — the plugin ships none). */
+  commands?: readonly CommandDef[];
+  /** Categories disabled at startup (host feature-gating). */
+  disabledCategories?: readonly string[];
+}
+interface CommandsCapability {
+  register(def: CommandDef): void;
+  unregister(id: string): void;
+  has(id: string): boolean;
+  ids(): string[];
+  resolve(id: string, documentId?: string): ResolvedCommand | null;
+  /** Palette query: visible commands whose resolved label matches. */
+  search(query: string, documentId?: string): ResolvedCommand[];
+  /** The one fact the overflow projection needs (ResolveMenuTarget-shaped). */
+  menuTarget(id: string): {
+    menu?: string;
+  } | null;
+  execute(id: string, documentId?: string): void;
+  /** Match a keystroke against every registered shortcut → command id or null. */
+  matchStroke(stroke: KeyStroke, opts: {
+    isMac: boolean;
+  }): string | null;
+  disabledCategories(): readonly string[];
+  isCategoryDisabled(category: string): boolean;
+  disableCategory(category: string): void;
+  enableCategory(category: string): void;
+  setDisabledCategories(categories: readonly string[]): void;
+}
+declare const CommandsToken: CapabilityToken<CommandsCapability>;
+//#endregion
+//#region src/commands.plugin.d.ts
+/**
+ * The commands plugin: workspace-scoped (one vocabulary for the whole
+ * workspace; resolution/execution bind to a target document per call).
+ * Definitions live in this closure — never in the store (they hold
+ * functions); the store slice holds only `disabledCategories`.
+ */
+declare const commandsPlugin: (config?: CommandsConfig) => import("@embedpdf/core").PluginDef<CommandsState, CommandsAction, CommandsCapability>;
+//#endregion
+//#region src/reducer.d.ts
+declare const initialCommandsState: CommandsState;
+declare function commandsReducer(state: CommandsState, action: CommandsAction): CommandsState;
+//#endregion
+export { type CommandCtx, type CommandDef, type CommandsAction, type CommandsCapability, type CommandsConfig, type CommandsState, CommandsToken, type IconAccent, type ResolvedCommand, commandsPlugin, commandsReducer, initialCommandsState, resolvedCommandsEqual };
+//# sourceMappingURL=index.d.cts.map

package/dist/index.d.ts

@@ -1 +1,150 @@
-export * from './lib';
+import { CapabilityToken, CoreState } from "@embedpdf/core";
+import { KeyStroke } from "@embedpdf/core-ui";
+//#region src/types.d.ts
+/**
+ * @embedpdf/plugin-commands — the contract.
+ *
+ * Commands are the single vocabulary of verbs: toolbars, menus, contextual
+ * strips, shortcuts, and the palette are all projections of this registry.
+ * The plugin ships ZERO commands (mechanism here, definitions in the product
+ * — same split as plugin-i18n's locale packs).
+ *
+ * Command state is a pure DERIVATION over the store: `resolve()` reads other
+ * capabilities' selectors at call time, so any store change is reflected on
+ * the next read and the framework binding's one change stream makes every
+ * consumer reactive. There is no CommandStateChangedEvent, no diffing, no
+ * cache — v2's entire notification apparatus has no v3 equivalent because
+ * the reactive store subsumes it.
+ *
+ * Definitions hold functions, so they live in the plugin's registry (config
+ * + `register()`), never in the store; store state is only the serializable
+ * `disabledCategories`.
+ */
+/** What a derivation or `run` sees: capability resolution bound to the
+ *  command's target document (explicit, else the active one). */
+interface CommandCtx {
+  /** The target document, or null when no document is open. */
+  readonly documentId: string | null;
+  core(): CoreState;
+  /** Resolve a capability; document-scoped tokens bind to the target document. */
+  get<T>(token: CapabilityToken<T>): T;
+  /** Like `get`, but null when unavailable (no provider / no document). */
+  tryGet<T>(token: CapabilityToken<T>): T | null;
+}
+/**
+ * Up to two theme colors accompanying a command's icon — typed FACTS any
+ * renderer can interpret (tint a glyph's slots, show a swatch), never
+ * renderer props. The registry carries it the way it carries `icon`: as
+ * data it doesn't interpret. Deliberately NOT v2's `iconProps` bag —
+ * renderer-specific needs live app-side, joined by command id.
+ */
+interface IconAccent {
+  /** The mark: stroke / markup / font color. */
+  readonly primary?: string;
+  /** The fill, when there is one. */
+  readonly secondary?: string;
+}
+interface CommandDef {
+  /** Convention: 'domain:verb' — 'zoom:in', 'mode:annotate', 'panel:search'. */
+  readonly id: string;
+  /** i18n key, resolved through I18nToken when present (else shown verbatim). */
+  readonly labelKey: string;
+  readonly icon?: string;
+  /** Live color accent for the icon (a tool previewing its drawing defaults).
+   *  A pure derivation over the store, exactly like `active`/`enabled`. */
+  readonly iconAccent?: (ctx: CommandCtx) => IconAccent | null;
+  /** 'Mod+K' style (ui-core grammar). Multiple bindings allowed. */
+  readonly shortcut?: string | readonly string[];
+  /** Feature-gating tags: a disabled category hides its commands everywhere. */
+  readonly categories?: readonly string[];
+  /** Toggles a named dropdown menu (a MenuSchema id in the app's chrome). */
+  readonly menu?: string;
+  /** Toggles a named shell surface, optionally exclusive within a tag ('left'…). */
+  readonly panel?: string | {
+    readonly id: string;
+    readonly exclusive?: string;
+  };
+  /** Toggles a modal surface (exclusive within the built-in 'modal' tag). */
+  readonly modal?: string;
+  readonly enabled?: (ctx: CommandCtx) => boolean;
+  readonly active?: (ctx: CommandCtx) => boolean;
+  readonly visible?: (ctx: CommandCtx) => boolean;
+  /** The verb. Optional for pure surface-target commands. Runs before the
+   *  default target routing when both are present. */
+  readonly run?: (ctx: CommandCtx) => void;
+}
+/** A command as a renderer sees it — everything resolved for the target document. */
+interface ResolvedCommand {
+  readonly id: string;
+  readonly label: string;
+  readonly icon?: string;
+  readonly iconAccent?: IconAccent;
+  readonly shortcuts: readonly string[];
+  readonly menu?: string;
+  readonly enabled: boolean;
+  readonly active: boolean;
+  readonly visible: boolean;
+  readonly categories: readonly string[];
+}
+/** Value equality over resolved commands — `resolve()` mints a fresh object
+ *  per read, so reactive bindings memo by value to re-render on real change. */
+declare const resolvedCommandsEqual: (a: ResolvedCommand | null, b: ResolvedCommand | null) => boolean;
+interface CommandsState {
+  readonly disabledCategories: readonly string[];
+}
+type CommandsAction = {
+  type: 'COMMANDS/DISABLE_CATEGORY';
+  category: string;
+} | {
+  type: 'COMMANDS/ENABLE_CATEGORY';
+  category: string;
+} | {
+  type: 'COMMANDS/SET_DISABLED_CATEGORIES';
+  categories: readonly string[];
+};
+interface CommandsConfig {
+  /** The app's command definitions (content — the plugin ships none). */
+  commands?: readonly CommandDef[];
+  /** Categories disabled at startup (host feature-gating). */
+  disabledCategories?: readonly string[];
+}
+interface CommandsCapability {
+  register(def: CommandDef): void;
+  unregister(id: string): void;
+  has(id: string): boolean;
+  ids(): string[];
+  resolve(id: string, documentId?: string): ResolvedCommand | null;
+  /** Palette query: visible commands whose resolved label matches. */
+  search(query: string, documentId?: string): ResolvedCommand[];
+  /** The one fact the overflow projection needs (ResolveMenuTarget-shaped). */
+  menuTarget(id: string): {
+    menu?: string;
+  } | null;
+  execute(id: string, documentId?: string): void;
+  /** Match a keystroke against every registered shortcut → command id or null. */
+  matchStroke(stroke: KeyStroke, opts: {
+    isMac: boolean;
+  }): string | null;
+  disabledCategories(): readonly string[];
+  isCategoryDisabled(category: string): boolean;
+  disableCategory(category: string): void;
+  enableCategory(category: string): void;
+  setDisabledCategories(categories: readonly string[]): void;
+}
+declare const CommandsToken: CapabilityToken<CommandsCapability>;
+//#endregion
+//#region src/commands.plugin.d.ts
+/**
+ * The commands plugin: workspace-scoped (one vocabulary for the whole
+ * workspace; resolution/execution bind to a target document per call).
+ * Definitions live in this closure — never in the store (they hold
+ * functions); the store slice holds only `disabledCategories`.
+ */
+declare const commandsPlugin: (config?: CommandsConfig) => import("@embedpdf/core").PluginDef<CommandsState, CommandsAction, CommandsCapability>;
+//#endregion
+//#region src/reducer.d.ts
+declare const initialCommandsState: CommandsState;
+declare function commandsReducer(state: CommandsState, action: CommandsAction): CommandsState;
+//#endregion
+export { type CommandCtx, type CommandDef, type CommandsAction, type CommandsCapability, type CommandsConfig, type CommandsState, CommandsToken, type IconAccent, type ResolvedCommand, commandsPlugin, commandsReducer, initialCommandsState, resolvedCommandsEqual };
+//# sourceMappingURL=index.d.ts.map