@embedpdf/plugin-commands 3.0.0-next.13 → 3.0.0-next.15

package/dist/contract/host.cjs

@@ -0,0 +1,18 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_contract = require("../contract-BlOznyrj.cjs");
+//#region src/host-contract.ts
+/**
+* @embedpdf/plugin-commands/contract/host — the host lens: the keystroke
+* matcher and the menu a command opens, for the toolbar's "More" menu. The
+* same runtime token as the public contract, typed wider.
+*/
+const CommandsToken = (0, require("@embedpdf/core").createHostToken)(require_contract.CommandsToken);
+//#endregion
+exports.COMMANDS_DEFAULTS = require_contract.COMMANDS_DEFAULTS;
+exports.CommandsToken = CommandsToken;
+exports.boundCommandOf = require_contract.boundCommandOf;
+exports.resolvedCommandsEqual = require_contract.resolvedCommandsEqual;
+exports.unknownCommandWarning = require_contract.unknownCommandWarning;
+exports.unregisteredCommand = require_contract.unregisteredCommand;
+
+//# sourceMappingURL=host.cjs.map

package/dist/contract/host.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"host.cjs","names":["PublicCommandsToken"],"sources":["../../src/host-contract.ts"],"sourcesContent":["/**\n * @embedpdf/plugin-commands/contract/host — the host lens: the keystroke\n * matcher and the menu a command opens, for the toolbar's \"More\" menu. The\n * same runtime token as the public contract, typed wider.\n */\nimport { createHostToken } from '@embedpdf/core';\nimport type { KeyStroke } from '@embedpdf/core-ui';\n\nimport type { CommandId, CommandRefusal, CommandsCapability } from './contract';\nimport { CommandsToken as PublicCommandsToken } from './token';\n\nexport * from './contract';\n\n/** The command a keystroke's shortcut names, and why it won't run when it's refused. */\nexport interface ShortcutMatch {\n  readonly commandId: CommandId;\n  /** Set when the command is turned off or not allowed; `null` when it may run (or just can't right now). */\n  readonly refusal: CommandRefusal | null;\n}\n\nexport interface CommandsHostCapability extends CommandsCapability {\n  /**\n   * The command whose shortcut a keystroke matches, for the active document, or `null`. Of\n   * several with the same keys, one that isn't refused wins; a refused one counts only while\n   * its `visible` says it would show. With `inTextField` (the key was typed in one), only a\n   * command whose `shortcutInTextFields` says so matches.\n   */\n  matchStroke(\n    stroke: KeyStroke,\n    options: { isMac: boolean; inTextField?: boolean },\n  ): ShortcutMatch | null;\n  /** The menu a command opens, for the \"More\" menu's nested menus; `null` for an unknown id. */\n  getMenuTarget(id: CommandId): { menu?: string } | null;\n}\n\nexport const CommandsToken = createHostToken<CommandsHostCapability>(PublicCommandsToken);\n"],"mappings":";;;;;;;;AAmCA,MAAa,iBAAA,2BAAA,CAAA,CAAA,gBAAA,CAAwDA,iBAAAA,aAAmB"}

package/dist/contract/host.d.cts

@@ -0,0 +1,3 @@
+import { S as unregisteredCommand, _ as RegisterCommandOptions, a as CommandExecutedEvent, b as resolvedCommandsEqual, c as CommandId, d as CommandsConfig, f as CommandsSettings, g as NotAllowedMode, h as IconAccent, i as CommandDef, l as CommandRefusal, m as ExecuteResult, n as COMMANDS_DEFAULTS, o as CommandExecutionFailedEvent, p as ExecuteOptions, r as CommandContext, s as CommandFamily, t as BoundCommand, u as CommandsCapability, v as ResolvedCommand, x as unknownCommandWarning, y as boundCommandOf } from "../contract-DAV5VR3P.cjs";
+import { n as CommandsToken, r as ShortcutMatch, t as CommandsHostCapability } from "../host-contract-Cqz-V6kP.cjs";
+export { BoundCommand, COMMANDS_DEFAULTS, CommandContext, CommandDef, CommandExecutedEvent, CommandExecutionFailedEvent, CommandFamily, CommandId, CommandRefusal, CommandsCapability, CommandsConfig, CommandsHostCapability, CommandsSettings, CommandsToken, ExecuteOptions, ExecuteResult, IconAccent, NotAllowedMode, RegisterCommandOptions, ResolvedCommand, ShortcutMatch, boundCommandOf, resolvedCommandsEqual, unknownCommandWarning, unregisteredCommand };

package/dist/contract/host.d.ts

@@ -0,0 +1,3 @@
+import { S as unregisteredCommand, _ as RegisterCommandOptions, a as CommandExecutedEvent, b as resolvedCommandsEqual, c as CommandId, d as CommandsConfig, f as CommandsSettings, g as NotAllowedMode, h as IconAccent, i as CommandDef, l as CommandRefusal, m as ExecuteResult, n as COMMANDS_DEFAULTS, o as CommandExecutionFailedEvent, p as ExecuteOptions, r as CommandContext, s as CommandFamily, t as BoundCommand, u as CommandsCapability, v as ResolvedCommand, x as unknownCommandWarning, y as boundCommandOf } from "../contract-DAV5VR3P.js";
+import { n as CommandsToken, r as ShortcutMatch, t as CommandsHostCapability } from "../host-contract-DkuusR8r.js";
+export { BoundCommand, COMMANDS_DEFAULTS, CommandContext, CommandDef, CommandExecutedEvent, CommandExecutionFailedEvent, CommandFamily, CommandId, CommandRefusal, CommandsCapability, CommandsConfig, CommandsHostCapability, CommandsSettings, CommandsToken, ExecuteOptions, ExecuteResult, IconAccent, NotAllowedMode, RegisterCommandOptions, ResolvedCommand, ShortcutMatch, boundCommandOf, resolvedCommandsEqual, unknownCommandWarning, unregisteredCommand };

package/dist/contract/host.js

@@ -0,0 +1,13 @@
+import { a as unregisteredCommand, i as unknownCommandWarning, n as boundCommandOf, o as CommandsToken$1, r as resolvedCommandsEqual, t as COMMANDS_DEFAULTS } from "../contract-Cj5BTtO7.js";
+import { createHostToken } from "@embedpdf/core";
+//#region src/host-contract.ts
+/**
+* @embedpdf/plugin-commands/contract/host — the host lens: the keystroke
+* matcher and the menu a command opens, for the toolbar's "More" menu. The
+* same runtime token as the public contract, typed wider.
+*/
+const CommandsToken = createHostToken(CommandsToken$1);
+//#endregion
+export { COMMANDS_DEFAULTS, CommandsToken, boundCommandOf, resolvedCommandsEqual, unknownCommandWarning, unregisteredCommand };
+
+//# sourceMappingURL=host.js.map

package/dist/contract/host.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"host.js","names":["PublicCommandsToken"],"sources":["../../src/host-contract.ts"],"sourcesContent":["/**\n * @embedpdf/plugin-commands/contract/host — the host lens: the keystroke\n * matcher and the menu a command opens, for the toolbar's \"More\" menu. The\n * same runtime token as the public contract, typed wider.\n */\nimport { createHostToken } from '@embedpdf/core';\nimport type { KeyStroke } from '@embedpdf/core-ui';\n\nimport type { CommandId, CommandRefusal, CommandsCapability } from './contract';\nimport { CommandsToken as PublicCommandsToken } from './token';\n\nexport * from './contract';\n\n/** The command a keystroke's shortcut names, and why it won't run when it's refused. */\nexport interface ShortcutMatch {\n  readonly commandId: CommandId;\n  /** Set when the command is turned off or not allowed; `null` when it may run (or just can't right now). */\n  readonly refusal: CommandRefusal | null;\n}\n\nexport interface CommandsHostCapability extends CommandsCapability {\n  /**\n   * The command whose shortcut a keystroke matches, for the active document, or `null`. Of\n   * several with the same keys, one that isn't refused wins; a refused one counts only while\n   * its `visible` says it would show. With `inTextField` (the key was typed in one), only a\n   * command whose `shortcutInTextFields` says so matches.\n   */\n  matchStroke(\n    stroke: KeyStroke,\n    options: { isMac: boolean; inTextField?: boolean },\n  ): ShortcutMatch | null;\n  /** The menu a command opens, for the \"More\" menu's nested menus; `null` for an unknown id. */\n  getMenuTarget(id: CommandId): { menu?: string } | null;\n}\n\nexport const CommandsToken = createHostToken<CommandsHostCapability>(PublicCommandsToken);\n"],"mappings":";;;;;;;;AAmCA,MAAa,gBAAgB,gBAAwCA,eAAmB"}

package/dist/contract-BlOznyrj.cjs

@@ -0,0 +1,91 @@
+let _embedpdf_core = require("@embedpdf/core");
+let _embedpdf_core_ui = require("@embedpdf/core-ui");
+//#region src/token.ts
+/** The package token, created once here; `contract.ts` re-exports it and
+*  `host-contract.ts` widens it to the host capability. */
+const CommandsToken = (0, _embedpdf_core.createCapabilityToken)("commands", { hint: `add commandsPlugin() from '@embedpdf/plugin-commands' to your plugins list` });
+//#endregion
+//#region src/contract.ts
+/**
+* Whether two resolved commands show the same, for readers that compare what a command looks
+* like rather than which object holds it (a group of commands, or one command for two documents).
+*/
+const resolvedCommandsEqual = (left, right) => {
+	if (left === right) return true;
+	if (!left || !right) return false;
+	return left.id === right.id && left.label === right.label && left.icon === right.icon && left.iconAccent?.primary === right.iconAccent?.primary && left.iconAccent?.secondary === right.iconAccent?.secondary && left.menu === right.menu && left.enabled === right.enabled && left.active === right.active && left.visible === right.visible && left.disabledReason === right.disabledReason && left.shortcuts.length === right.shortcuts.length && left.shortcuts.every((shortcut, index) => shortcut === right.shortcuts[index]);
+};
+/**
+* What a component or a toolbar draws for a command id no plugin registered: labelled with its
+* id, neither enabled nor visible, the way a turned-off command is.
+*/
+const unregisteredCommand = (id) => ({
+	id,
+	label: id,
+	shortcuts: [],
+	enabled: false,
+	active: false,
+	visible: false,
+	categories: []
+});
+/** What a component that asks for an id no plugin registered hears, in development. */
+const unknownCommandWarning = (id, known) => `no command "${id}"${(0, _embedpdf_core_ui.didYouMean)(id, known)}: it shows as neither visible nor enabled`;
+/**
+* A resolved command, bound for a button: `run` executes it through `execute`, and `shortcut` is
+* its first shortcut formatted for the platform. Which platform is the caller's to know
+* (`isMacPlatform()` in `@embedpdf/web`).
+*/
+function boundCommandOf(command, execute, options) {
+	const [first] = command.shortcuts;
+	return {
+		...command,
+		run: () => execute(command.id),
+		shortcut: first === void 0 ? null : (0, _embedpdf_core_ui.formatShortcut)(first, { isMac: options.isMac })
+	};
+}
+/** What the commands settings are when the app registers none. */
+const COMMANDS_DEFAULTS = {
+	commands: [],
+	disabledCategories: [],
+	disabledCommands: [],
+	notAllowed: "hide"
+};
+//#endregion
+Object.defineProperty(exports, "COMMANDS_DEFAULTS", {
+	enumerable: true,
+	get: function() {
+		return COMMANDS_DEFAULTS;
+	}
+});
+Object.defineProperty(exports, "CommandsToken", {
+	enumerable: true,
+	get: function() {
+		return CommandsToken;
+	}
+});
+Object.defineProperty(exports, "boundCommandOf", {
+	enumerable: true,
+	get: function() {
+		return boundCommandOf;
+	}
+});
+Object.defineProperty(exports, "resolvedCommandsEqual", {
+	enumerable: true,
+	get: function() {
+		return resolvedCommandsEqual;
+	}
+});
+Object.defineProperty(exports, "unknownCommandWarning", {
+	enumerable: true,
+	get: function() {
+		return unknownCommandWarning;
+	}
+});
+Object.defineProperty(exports, "unregisteredCommand", {
+	enumerable: true,
+	get: function() {
+		return unregisteredCommand;
+	}
+});
+
+//# sourceMappingURL=contract-BlOznyrj.cjs.map

package/dist/contract-BlOznyrj.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract-BlOznyrj.cjs","names":[],"sources":["../src/token.ts","../src/contract.ts"],"sourcesContent":["/** The package token, created once here; `contract.ts` re-exports it and\n *  `host-contract.ts` widens it to the host capability. */\nimport { createCapabilityToken } from '@embedpdf/core';\n\nimport type { CommandsCapability } from './contract';\n\nexport const CommandsToken = createCapabilityToken<CommandsCapability>('commands', {\n  hint: `add commandsPlugin() from '@embedpdf/plugin-commands' to your plugins list`,\n});\n","/**\n * @embedpdf/plugin-commands/contract — the commands that toolbars, menus,\n * shortcuts and a command palette all show and run.\n *\n * A command's state is read from live state: `resolveCommand` asks the other\n * capabilities when it's called, so every reader follows the kernel's one\n * change stream, with no events. Definitions hold functions, so they live in\n * the settings and the plugin's registry, never in state.\n */\nimport type {\n  CapabilityToken,\n  DeepPartial,\n  EventHook,\n  OperationOptions,\n  Permission,\n  PluginErrorInfo,\n  SettingsApi,\n  Unsubscribe,\n} from '@embedpdf/core';\nimport { didYouMean, formatShortcut } from '@embedpdf/core-ui';\n\nexport { CommandsToken } from './token';\n\nexport type CommandId = string;\n\n/**\n * What a command's derivations and `run` see: capabilities resolved for the command's document\n * (the one named, else the document in scope, else the active one).\n */\nexport interface CommandContext {\n  /** The command's document, or `null` when none is open. */\n  readonly documentId: string | null;\n  /** What the caller passed: `execute(id, { args })`. */\n  readonly args?: unknown;\n  /** Fires when the caller cancels `execute()`: pass it on to the calls `run` makes. */\n  readonly signal?: AbortSignal;\n  /** A capability, for the command's document when the plugin is document-scoped. Throws when it isn't available. */\n  get<T>(token: CapabilityToken<T>): T;\n  /** Like `get`, but `null` when the capability isn't available (no plugin, no document). */\n  tryGet<T>(token: CapabilityToken<T>): T | null;\n}\n\n/**\n * Up to two colors that go with a command's icon, such as a tool's current color: data a\n * renderer may use (tint the icon, show a swatch), like `icon` itself.\n */\nexport interface IconAccent {\n  /** The mark: a stroke, the markup or the text color. */\n  readonly primary?: string;\n  /** The fill, when there is one. */\n  readonly secondary?: string;\n}\n\n/** One command, as you define it. */\nexport interface CommandDef {\n  /** A unique name, by convention `area:action`: `'zoom:in'`, `'review:approve'`. */\n  readonly id: string;\n  /** What the user sees. With `labelKey` too, it's what shows when no language has the key. */\n  readonly label?: string;\n  /**\n   * A translation key for the label, read through the i18n plugin. Without the plugin, or a\n   * string for the key, the command shows `label`, else the key.\n   */\n  readonly labelKey?: string;\n  /** Your icon's name; your buttons turn it into an icon. */\n  readonly icon?: string;\n  /** Colors for the icon, read from live state like `active`. */\n  readonly iconAccent?: (context: CommandContext) => IconAccent | null;\n  /** A key such as `'Mod+K'` (`Mod` is Cmd on a Mac, Ctrl elsewhere), or a list of them. */\n  readonly shortcut?: string | readonly string[];\n  /**\n   * Whether its shortcut also runs while the cursor is in a text field where the shortcuts\n   * listen (a search box, a comment), as the viewer's Find does. Default false: a key typed in\n   * a field is the field's.\n   */\n  readonly shortcutInTextFields?: boolean;\n  /**\n   * The features it belongs to, so turning one off turns it off: `['annotations.highlight']`.\n   * Turning off a feature turns off every feature under it, on whole dotted parts: `annotations`\n   * covers `annotations.highlight`, not `annotationsExtra`.\n   */\n  readonly categories?: readonly string[];\n  /**\n   * The scope permissions it needs, such as `'doc.annotate.modify'`, checked against its\n   * document. Without them it's hidden, or shown disabled with its reason under the\n   * `notAllowed: 'disable'` setting. With no document open there is nothing to check.\n   */\n  readonly requires?: readonly Permission[];\n  /**\n   * Whether the session may run it, from the plugins' `can*` checks\n   * (`documents.canPrint()`), for a command whose permission is a plugin's to know. When it\n   * says no, the command isn't allowed, as with `requires`. Asked only while a document is\n   * open; one that throws allows it.\n   */\n  readonly allowed?: (context: CommandContext) => boolean;\n  /**\n   * The translation key of the sentence that says why `allowed` refused it, with `{label}` for\n   * its label: `'commands.notAllowed.doc-print'`. Without it, or a string for it,\n   * `commands.notAllowed.default`.\n   */\n  readonly notAllowedKey?: string;\n\n  // ── what the command opens ───────────────────────────────────────────────\n  // A command that opens a panel, menu or dialog says so instead of opening\n  // it in `run`: it then needs no `run`, it shows as active while the surface\n  // is open, and a button can show that it opens a menu.\n  /** Opens and closes a menu of yours, by its id. */\n  readonly menu?: string;\n  /**\n   * Opens and closes a panel, closing the others with the same `exclusive` tag. With `focus`,\n   * opening it asks for the cursor (the shell's `open(id, { focus: true })`).\n   */\n  readonly panel?:\n    | string\n    | { readonly id: string; readonly exclusive?: string; readonly focus?: boolean };\n  /** Opens and closes a dialog; one dialog is open at a time. */\n  readonly modal?: string;\n\n  // ── read from live state, again whenever anything changes ────────────────\n  /** When it can run. Default: always. */\n  readonly enabled?: (context: CommandContext) => boolean;\n  /** When it shows as pressed, such as the current tool. */\n  readonly active?: (context: CommandContext) => boolean;\n  /** When it shows at all. Default: always. */\n  readonly visible?: (context: CommandContext) => boolean;\n\n  /** What it does; `execute()` resolves once it has. Not needed for a `menu`, `panel` or `modal`. */\n  readonly run?: (context: CommandContext) => void | Promise<unknown>;\n}\n\n/**\n * A command for each of a set of names, made from one definition, such as `tool:<id>` for every\n * tool a document has. Its commands resolve and run like any other, and `listCommands()` lists\n * one per name. A command defined with the same id wins over the family's.\n */\nexport interface CommandFamily {\n  /** Where the commands' ids start: `'tool:'` makes `tool:highlight`. */\n  readonly prefix: string;\n  /** The names the command's document has, in order. Return the same array while nothing changed. */\n  readonly names: (context: CommandContext) => readonly string[];\n  /** The command for one name. A family's commands have no shortcuts. */\n  readonly command: (name: string) => Omit<CommandDef, 'id' | 'shortcut'>;\n}\n\n/** A command as a button shows it: everything read for its document. */\nexport interface ResolvedCommand {\n  readonly id: string;\n  readonly label: string;\n  readonly icon?: string;\n  readonly iconAccent?: IconAccent;\n  readonly shortcuts: readonly string[];\n  readonly menu?: string;\n  readonly enabled: boolean;\n  readonly active: boolean;\n  readonly visible: boolean;\n  readonly categories: readonly string[];\n  /**\n   * Why it's disabled, as a sentence for its tooltip: set when the scope doesn't allow it and\n   * the `notAllowed` setting is `'disable'`.\n   */\n  readonly disabledReason?: string;\n}\n\n/**\n * Why a command won't run whatever the moment: it's turned off in this viewer\n * (`disabledCategories`, `disabledCommands`), or the scope doesn't allow it (`requires`).\n * A command that only can't run right now (`enabled`, `visible`) has no refusal.\n */\nexport interface CommandRefusal {\n  readonly reason: 'turned-off' | 'not-allowed';\n  /** A sentence for the user, translated through the i18n plugin when it's there. */\n  readonly message: string;\n}\n\n/**\n * Whether two resolved commands show the same, for readers that compare what a command looks\n * like rather than which object holds it (a group of commands, or one command for two documents).\n */\nexport const resolvedCommandsEqual = (\n  left: ResolvedCommand | null,\n  right: ResolvedCommand | null,\n): boolean => {\n  if (left === right) return true;\n  if (!left || !right) return false;\n  return (\n    left.id === right.id &&\n    left.label === right.label &&\n    left.icon === right.icon &&\n    left.iconAccent?.primary === right.iconAccent?.primary &&\n    left.iconAccent?.secondary === right.iconAccent?.secondary &&\n    left.menu === right.menu &&\n    left.enabled === right.enabled &&\n    left.active === right.active &&\n    left.visible === right.visible &&\n    left.disabledReason === right.disabledReason &&\n    left.shortcuts.length === right.shortcuts.length &&\n    left.shortcuts.every((shortcut, index) => shortcut === right.shortcuts[index])\n  );\n};\n\n/**\n * What a component or a toolbar draws for a command id no plugin registered: labelled with its\n * id, neither enabled nor visible, the way a turned-off command is.\n */\nexport const unregisteredCommand = (id: CommandId): ResolvedCommand => ({\n  id,\n  label: id,\n  shortcuts: [],\n  enabled: false,\n  active: false,\n  visible: false,\n  categories: [],\n});\n\n/** What a component that asks for an id no plugin registered hears, in development. */\nexport const unknownCommandWarning = (id: CommandId, known: Iterable<CommandId>): string =>\n  `no command \"${id}\"${didYouMean(id, known)}: it shows as neither visible nor enabled`;\n\n/** A command with everything a button needs: what it shows, `run`, and its shortcut for a tooltip. */\nexport interface BoundCommand extends ResolvedCommand {\n  /** Run the command for the document it was read for. */\n  readonly run: () => Promise<ExecuteResult>;\n  /** Its first shortcut, formatted for the platform (`'⌘K'` on a Mac, `'Ctrl+K'` elsewhere), or `null`. */\n  readonly shortcut: string | null;\n}\n\n/**\n * A resolved command, bound for a button: `run` executes it through `execute`, and `shortcut` is\n * its first shortcut formatted for the platform. Which platform is the caller's to know\n * (`isMacPlatform()` in `@embedpdf/web`).\n */\nexport function boundCommandOf(\n  command: ResolvedCommand,\n  execute: (id: CommandId) => Promise<ExecuteResult>,\n  options: { readonly isMac: boolean },\n): BoundCommand {\n  const [first] = command.shortcuts;\n  return {\n    ...command,\n    run: () => execute(command.id),\n    shortcut: first === undefined ? null : formatShortcut(first, { isMac: options.isMac }),\n  };\n}\n\n/**\n * The commands plugin's settings. `commandsPlugin(config)` registers them over\n * {@link COMMANDS_DEFAULTS}, and `updateSettings()` changes them while the app runs.\n */\nexport interface CommandsSettings {\n  /** The commands your viewer has. A later definition with an id that's taken replaces the earlier one. */\n  readonly commands: readonly (CommandDef | CommandFamily)[];\n  /**\n   * Categories turned off, with every category under them: their commands are hidden and\n   * refused wherever they appear.\n   */\n  readonly disabledCategories: readonly string[];\n  /** Commands turned off one by one, by id: hidden and refused wherever they appear. */\n  readonly disabledCommands: readonly CommandId[];\n  /**\n   * What a command the scope doesn't allow does: `'hide'` leaves it out, `'disable'` shows it\n   * disabled, with the reason in its `disabledReason`.\n   */\n  readonly notAllowed: NotAllowedMode;\n}\n\n/** How a command shows when the scope doesn't allow it: hidden, or disabled with its reason. */\nexport type NotAllowedMode = 'hide' | 'disable';\n\n/** What the commands settings are when the app registers none. */\nexport const COMMANDS_DEFAULTS: CommandsSettings = {\n  commands: [],\n  disabledCategories: [],\n  disabledCommands: [],\n  notAllowed: 'hide',\n};\n\n/** What `commandsPlugin(config)` takes: any of the settings, merged over the defaults. */\nexport type CommandsConfig = DeepPartial<CommandsSettings>;\n\nexport interface RegisterCommandOptions {\n  /** Replace a command with the same id; without it, a taken id throws `conflict`. */\n  replace?: boolean;\n}\n\nexport interface ExecuteOptions extends OperationOptions {\n  /** The document to run it for; the document in scope, else the active one, when left out. */\n  documentId?: string;\n  /** Passed to the command's `run` and derivations as `args`. */\n  args?: unknown;\n}\n\n/** How `execute()` went: it ran, or it was refused before running, and why. */\nexport type ExecuteResult =\n  | { readonly status: 'executed' }\n  | { readonly status: 'rejected'; readonly reason: 'not-found' | 'disabled' | 'hidden' };\n\n// ── events ──\nexport interface CommandExecutedEvent {\n  readonly commandId: CommandId;\n  readonly documentId: string | null;\n  readonly args: unknown;\n}\nexport interface CommandExecutionFailedEvent {\n  readonly commandId: CommandId;\n  readonly documentId: string | null;\n  readonly error: PluginErrorInfo;\n}\n\n/**\n * The commands. A call that leaves out the document is for the document in scope when the\n * capability was resolved for one (`ctx.forDocument`, a `<DocumentScope>`), and for the active\n * document otherwise.\n */\nexport interface CommandsCapability extends SettingsApi<CommandsSettings> {\n  // ── the commands ──\n  /**\n   * Add a command while the app runs, and get a function that removes it. A taken id throws\n   * `conflict` unless `replace`.\n   */\n  registerCommand(definition: CommandDef, options?: RegisterCommandOptions): Unsubscribe;\n  /** `registerCommand` for several definitions; the function removes all of them. */\n  registerCommands(\n    definitions: readonly CommandDef[],\n    options?: RegisterCommandOptions,\n  ): Unsubscribe;\n  /** Whether a command has this id; with a family, every id that starts with its prefix does. */\n  hasCommand(id: CommandId): boolean;\n  /** A command as you defined it, or `null`. */\n  getCommand(id: CommandId): CommandDef | null;\n  /** Every command's id for the active document, in the order they were added. The same array until one changes. */\n  listCommandIds(): readonly CommandId[];\n\n  // ── what a button shows ──\n  /** A command as a button shows it, or `null` for an unknown id. The same object while nothing about it changed. */\n  resolveCommand(id: CommandId, documentId?: string): ResolvedCommand | null;\n  /** Every command, resolved, in the order they were added. The same array while nothing changed. */\n  listCommands(documentId?: string): readonly ResolvedCommand[];\n  /** The visible commands whose label or id contains the query, for a command palette. */\n  searchCommands(query: string, documentId?: string): readonly ResolvedCommand[];\n  /** Every shortcut with its command, for a keyboard help sheet. The same array until the commands change. */\n  listShortcuts(): readonly { readonly commandId: CommandId; readonly shortcut: string }[];\n\n  // ── running them ──\n  /**\n   * Run a command; resolves once its `run` has, with `{ status: 'executed' }` and\n   * `onExecuted`, or `{ status: 'rejected', reason }` for a command that is unknown, hidden or\n   * disabled (a command turned off is hidden). A `run` that throws fires `onExecutionFailed` and rejects with its `PluginError`;\n   * the signal rejects `operation-cancelled`.\n   */\n  execute(id: CommandId, options?: ExecuteOptions): Promise<ExecuteResult>;\n  /** Whether a command can run now: it exists, and is enabled and visible. */\n  canExecute(id: CommandId, documentId?: string): boolean;\n  /**\n   * Why a command won't run whatever the moment: it's turned off, or not allowed for its\n   * document. `null` when it may run (or only can't right now), and for an unknown id.\n   */\n  getRefusal(id: CommandId, documentId?: string): CommandRefusal | null;\n\n  // ── turning commands off ──\n  /** The categories turned off. */\n  getDisabledCategories(): readonly string[];\n  /** Whether a category is turned off: it, or a category it's under (`annotations` for `annotations.highlight`). */\n  isCategoryDisabled(category: string): boolean;\n  /** Turn a category off, with every category under it: the `disabledCategories` setting gains it. */\n  disableCategory(category: string): void;\n  /** Turn a category on again. */\n  enableCategory(category: string): void;\n  /** Replace the categories that are off. */\n  setDisabledCategories(categories: readonly string[]): void;\n  /** The commands turned off one by one. */\n  getDisabledCommands(): readonly CommandId[];\n  /** Whether a command is turned off: by its id, or through one of its categories. */\n  isCommandDisabled(id: CommandId): boolean;\n  /** Turn one command off: the `disabledCommands` setting gains it. */\n  disableCommand(id: CommandId): void;\n  /** Turn a command on again; it stays off while one of its categories is. */\n  enableCommand(id: CommandId): void;\n  /** Replace the commands that are off one by one. */\n  setDisabledCommands(ids: readonly CommandId[]): void;\n\n  // ── events ──\n  /** A command ran. */\n  readonly onExecuted: EventHook<CommandExecutedEvent>;\n  /** A command's `run` threw; `execute` rejects with the same error. */\n  readonly onExecutionFailed: EventHook<CommandExecutionFailedEvent>;\n}\n"],"mappings":";;;;;AAMA,MAAa,iBAAA,GAAA,eAAA,sBAAA,CAA0D,YAAY,EACjF,MAAM,6EACR,CAAC;;;;;;;AC0KD,MAAa,yBACX,MACA,UACY;CACZ,IAAI,SAAS,OAAO,OAAO;CAC3B,IAAI,CAAC,QAAQ,CAAC,OAAO,OAAO;CAC5B,OACE,KAAK,OAAO,MAAM,MAClB,KAAK,UAAU,MAAM,SACrB,KAAK,SAAS,MAAM,QACpB,KAAK,YAAY,YAAY,MAAM,YAAY,WAC/C,KAAK,YAAY,cAAc,MAAM,YAAY,aACjD,KAAK,SAAS,MAAM,QACpB,KAAK,YAAY,MAAM,WACvB,KAAK,WAAW,MAAM,UACtB,KAAK,YAAY,MAAM,WACvB,KAAK,mBAAmB,MAAM,kBAC9B,KAAK,UAAU,WAAW,MAAM,UAAU,UAC1C,KAAK,UAAU,OAAO,UAAU,UAAU,aAAa,MAAM,UAAU,MAAM;AAEjF;;;;;AAMA,MAAa,uBAAuB,QAAoC;CACtE;CACA,OAAO;CACP,WAAW,CAAC;CACZ,SAAS;CACT,QAAQ;CACR,SAAS;CACT,YAAY,CAAC;AACf;;AAGA,MAAa,yBAAyB,IAAe,UACnD,eAAe,GAAG,IAAA,GAAA,kBAAA,WAAA,CAAc,IAAI,KAAK,EAAE;;;;;;AAe7C,SAAgB,eACd,SACA,SACA,SACc;CACd,MAAM,CAAC,SAAS,QAAQ;CACxB,OAAO;EACL,GAAG;EACH,WAAW,QAAQ,QAAQ,EAAE;EAC7B,UAAU,UAAU,KAAA,IAAY,QAAA,GAAA,kBAAA,eAAA,CAAsB,OAAO,EAAE,OAAO,QAAQ,MAAM,CAAC;CACvF;AACF;;AA2BA,MAAa,oBAAsC;CACjD,UAAU,CAAC;CACX,oBAAoB,CAAC;CACrB,kBAAkB,CAAC;CACnB,YAAY;AACd"}

package/dist/contract-Cj5BTtO7.js

@@ -0,0 +1,56 @@
+import { createCapabilityToken } from "@embedpdf/core";
+import { didYouMean, formatShortcut } from "@embedpdf/core-ui";
+//#region src/token.ts
+/** The package token, created once here; `contract.ts` re-exports it and
+*  `host-contract.ts` widens it to the host capability. */
+const CommandsToken = createCapabilityToken("commands", { hint: `add commandsPlugin() from '@embedpdf/plugin-commands' to your plugins list` });
+//#endregion
+//#region src/contract.ts
+/**
+* Whether two resolved commands show the same, for readers that compare what a command looks
+* like rather than which object holds it (a group of commands, or one command for two documents).
+*/
+const resolvedCommandsEqual = (left, right) => {
+	if (left === right) return true;
+	if (!left || !right) return false;
+	return left.id === right.id && left.label === right.label && left.icon === right.icon && left.iconAccent?.primary === right.iconAccent?.primary && left.iconAccent?.secondary === right.iconAccent?.secondary && left.menu === right.menu && left.enabled === right.enabled && left.active === right.active && left.visible === right.visible && left.disabledReason === right.disabledReason && left.shortcuts.length === right.shortcuts.length && left.shortcuts.every((shortcut, index) => shortcut === right.shortcuts[index]);
+};
+/**
+* What a component or a toolbar draws for a command id no plugin registered: labelled with its
+* id, neither enabled nor visible, the way a turned-off command is.
+*/
+const unregisteredCommand = (id) => ({
+	id,
+	label: id,
+	shortcuts: [],
+	enabled: false,
+	active: false,
+	visible: false,
+	categories: []
+});
+/** What a component that asks for an id no plugin registered hears, in development. */
+const unknownCommandWarning = (id, known) => `no command "${id}"${didYouMean(id, known)}: it shows as neither visible nor enabled`;
+/**
+* A resolved command, bound for a button: `run` executes it through `execute`, and `shortcut` is
+* its first shortcut formatted for the platform. Which platform is the caller's to know
+* (`isMacPlatform()` in `@embedpdf/web`).
+*/
+function boundCommandOf(command, execute, options) {
+	const [first] = command.shortcuts;
+	return {
+		...command,
+		run: () => execute(command.id),
+		shortcut: first === void 0 ? null : formatShortcut(first, { isMac: options.isMac })
+	};
+}
+/** What the commands settings are when the app registers none. */
+const COMMANDS_DEFAULTS = {
+	commands: [],
+	disabledCategories: [],
+	disabledCommands: [],
+	notAllowed: "hide"
+};
+//#endregion
+export { unregisteredCommand as a, unknownCommandWarning as i, boundCommandOf as n, CommandsToken as o, resolvedCommandsEqual as r, COMMANDS_DEFAULTS as t };
+
+//# sourceMappingURL=contract-Cj5BTtO7.js.map

package/dist/contract-Cj5BTtO7.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract-Cj5BTtO7.js","names":[],"sources":["../src/token.ts","../src/contract.ts"],"sourcesContent":["/** The package token, created once here; `contract.ts` re-exports it and\n *  `host-contract.ts` widens it to the host capability. */\nimport { createCapabilityToken } from '@embedpdf/core';\n\nimport type { CommandsCapability } from './contract';\n\nexport const CommandsToken = createCapabilityToken<CommandsCapability>('commands', {\n  hint: `add commandsPlugin() from '@embedpdf/plugin-commands' to your plugins list`,\n});\n","/**\n * @embedpdf/plugin-commands/contract — the commands that toolbars, menus,\n * shortcuts and a command palette all show and run.\n *\n * A command's state is read from live state: `resolveCommand` asks the other\n * capabilities when it's called, so every reader follows the kernel's one\n * change stream, with no events. Definitions hold functions, so they live in\n * the settings and the plugin's registry, never in state.\n */\nimport type {\n  CapabilityToken,\n  DeepPartial,\n  EventHook,\n  OperationOptions,\n  Permission,\n  PluginErrorInfo,\n  SettingsApi,\n  Unsubscribe,\n} from '@embedpdf/core';\nimport { didYouMean, formatShortcut } from '@embedpdf/core-ui';\n\nexport { CommandsToken } from './token';\n\nexport type CommandId = string;\n\n/**\n * What a command's derivations and `run` see: capabilities resolved for the command's document\n * (the one named, else the document in scope, else the active one).\n */\nexport interface CommandContext {\n  /** The command's document, or `null` when none is open. */\n  readonly documentId: string | null;\n  /** What the caller passed: `execute(id, { args })`. */\n  readonly args?: unknown;\n  /** Fires when the caller cancels `execute()`: pass it on to the calls `run` makes. */\n  readonly signal?: AbortSignal;\n  /** A capability, for the command's document when the plugin is document-scoped. Throws when it isn't available. */\n  get<T>(token: CapabilityToken<T>): T;\n  /** Like `get`, but `null` when the capability isn't available (no plugin, no document). */\n  tryGet<T>(token: CapabilityToken<T>): T | null;\n}\n\n/**\n * Up to two colors that go with a command's icon, such as a tool's current color: data a\n * renderer may use (tint the icon, show a swatch), like `icon` itself.\n */\nexport interface IconAccent {\n  /** The mark: a stroke, the markup or the text color. */\n  readonly primary?: string;\n  /** The fill, when there is one. */\n  readonly secondary?: string;\n}\n\n/** One command, as you define it. */\nexport interface CommandDef {\n  /** A unique name, by convention `area:action`: `'zoom:in'`, `'review:approve'`. */\n  readonly id: string;\n  /** What the user sees. With `labelKey` too, it's what shows when no language has the key. */\n  readonly label?: string;\n  /**\n   * A translation key for the label, read through the i18n plugin. Without the plugin, or a\n   * string for the key, the command shows `label`, else the key.\n   */\n  readonly labelKey?: string;\n  /** Your icon's name; your buttons turn it into an icon. */\n  readonly icon?: string;\n  /** Colors for the icon, read from live state like `active`. */\n  readonly iconAccent?: (context: CommandContext) => IconAccent | null;\n  /** A key such as `'Mod+K'` (`Mod` is Cmd on a Mac, Ctrl elsewhere), or a list of them. */\n  readonly shortcut?: string | readonly string[];\n  /**\n   * Whether its shortcut also runs while the cursor is in a text field where the shortcuts\n   * listen (a search box, a comment), as the viewer's Find does. Default false: a key typed in\n   * a field is the field's.\n   */\n  readonly shortcutInTextFields?: boolean;\n  /**\n   * The features it belongs to, so turning one off turns it off: `['annotations.highlight']`.\n   * Turning off a feature turns off every feature under it, on whole dotted parts: `annotations`\n   * covers `annotations.highlight`, not `annotationsExtra`.\n   */\n  readonly categories?: readonly string[];\n  /**\n   * The scope permissions it needs, such as `'doc.annotate.modify'`, checked against its\n   * document. Without them it's hidden, or shown disabled with its reason under the\n   * `notAllowed: 'disable'` setting. With no document open there is nothing to check.\n   */\n  readonly requires?: readonly Permission[];\n  /**\n   * Whether the session may run it, from the plugins' `can*` checks\n   * (`documents.canPrint()`), for a command whose permission is a plugin's to know. When it\n   * says no, the command isn't allowed, as with `requires`. Asked only while a document is\n   * open; one that throws allows it.\n   */\n  readonly allowed?: (context: CommandContext) => boolean;\n  /**\n   * The translation key of the sentence that says why `allowed` refused it, with `{label}` for\n   * its label: `'commands.notAllowed.doc-print'`. Without it, or a string for it,\n   * `commands.notAllowed.default`.\n   */\n  readonly notAllowedKey?: string;\n\n  // ── what the command opens ───────────────────────────────────────────────\n  // A command that opens a panel, menu or dialog says so instead of opening\n  // it in `run`: it then needs no `run`, it shows as active while the surface\n  // is open, and a button can show that it opens a menu.\n  /** Opens and closes a menu of yours, by its id. */\n  readonly menu?: string;\n  /**\n   * Opens and closes a panel, closing the others with the same `exclusive` tag. With `focus`,\n   * opening it asks for the cursor (the shell's `open(id, { focus: true })`).\n   */\n  readonly panel?:\n    | string\n    | { readonly id: string; readonly exclusive?: string; readonly focus?: boolean };\n  /** Opens and closes a dialog; one dialog is open at a time. */\n  readonly modal?: string;\n\n  // ── read from live state, again whenever anything changes ────────────────\n  /** When it can run. Default: always. */\n  readonly enabled?: (context: CommandContext) => boolean;\n  /** When it shows as pressed, such as the current tool. */\n  readonly active?: (context: CommandContext) => boolean;\n  /** When it shows at all. Default: always. */\n  readonly visible?: (context: CommandContext) => boolean;\n\n  /** What it does; `execute()` resolves once it has. Not needed for a `menu`, `panel` or `modal`. */\n  readonly run?: (context: CommandContext) => void | Promise<unknown>;\n}\n\n/**\n * A command for each of a set of names, made from one definition, such as `tool:<id>` for every\n * tool a document has. Its commands resolve and run like any other, and `listCommands()` lists\n * one per name. A command defined with the same id wins over the family's.\n */\nexport interface CommandFamily {\n  /** Where the commands' ids start: `'tool:'` makes `tool:highlight`. */\n  readonly prefix: string;\n  /** The names the command's document has, in order. Return the same array while nothing changed. */\n  readonly names: (context: CommandContext) => readonly string[];\n  /** The command for one name. A family's commands have no shortcuts. */\n  readonly command: (name: string) => Omit<CommandDef, 'id' | 'shortcut'>;\n}\n\n/** A command as a button shows it: everything read for its document. */\nexport interface ResolvedCommand {\n  readonly id: string;\n  readonly label: string;\n  readonly icon?: string;\n  readonly iconAccent?: IconAccent;\n  readonly shortcuts: readonly string[];\n  readonly menu?: string;\n  readonly enabled: boolean;\n  readonly active: boolean;\n  readonly visible: boolean;\n  readonly categories: readonly string[];\n  /**\n   * Why it's disabled, as a sentence for its tooltip: set when the scope doesn't allow it and\n   * the `notAllowed` setting is `'disable'`.\n   */\n  readonly disabledReason?: string;\n}\n\n/**\n * Why a command won't run whatever the moment: it's turned off in this viewer\n * (`disabledCategories`, `disabledCommands`), or the scope doesn't allow it (`requires`).\n * A command that only can't run right now (`enabled`, `visible`) has no refusal.\n */\nexport interface CommandRefusal {\n  readonly reason: 'turned-off' | 'not-allowed';\n  /** A sentence for the user, translated through the i18n plugin when it's there. */\n  readonly message: string;\n}\n\n/**\n * Whether two resolved commands show the same, for readers that compare what a command looks\n * like rather than which object holds it (a group of commands, or one command for two documents).\n */\nexport const resolvedCommandsEqual = (\n  left: ResolvedCommand | null,\n  right: ResolvedCommand | null,\n): boolean => {\n  if (left === right) return true;\n  if (!left || !right) return false;\n  return (\n    left.id === right.id &&\n    left.label === right.label &&\n    left.icon === right.icon &&\n    left.iconAccent?.primary === right.iconAccent?.primary &&\n    left.iconAccent?.secondary === right.iconAccent?.secondary &&\n    left.menu === right.menu &&\n    left.enabled === right.enabled &&\n    left.active === right.active &&\n    left.visible === right.visible &&\n    left.disabledReason === right.disabledReason &&\n    left.shortcuts.length === right.shortcuts.length &&\n    left.shortcuts.every((shortcut, index) => shortcut === right.shortcuts[index])\n  );\n};\n\n/**\n * What a component or a toolbar draws for a command id no plugin registered: labelled with its\n * id, neither enabled nor visible, the way a turned-off command is.\n */\nexport const unregisteredCommand = (id: CommandId): ResolvedCommand => ({\n  id,\n  label: id,\n  shortcuts: [],\n  enabled: false,\n  active: false,\n  visible: false,\n  categories: [],\n});\n\n/** What a component that asks for an id no plugin registered hears, in development. */\nexport const unknownCommandWarning = (id: CommandId, known: Iterable<CommandId>): string =>\n  `no command \"${id}\"${didYouMean(id, known)}: it shows as neither visible nor enabled`;\n\n/** A command with everything a button needs: what it shows, `run`, and its shortcut for a tooltip. */\nexport interface BoundCommand extends ResolvedCommand {\n  /** Run the command for the document it was read for. */\n  readonly run: () => Promise<ExecuteResult>;\n  /** Its first shortcut, formatted for the platform (`'⌘K'` on a Mac, `'Ctrl+K'` elsewhere), or `null`. */\n  readonly shortcut: string | null;\n}\n\n/**\n * A resolved command, bound for a button: `run` executes it through `execute`, and `shortcut` is\n * its first shortcut formatted for the platform. Which platform is the caller's to know\n * (`isMacPlatform()` in `@embedpdf/web`).\n */\nexport function boundCommandOf(\n  command: ResolvedCommand,\n  execute: (id: CommandId) => Promise<ExecuteResult>,\n  options: { readonly isMac: boolean },\n): BoundCommand {\n  const [first] = command.shortcuts;\n  return {\n    ...command,\n    run: () => execute(command.id),\n    shortcut: first === undefined ? null : formatShortcut(first, { isMac: options.isMac }),\n  };\n}\n\n/**\n * The commands plugin's settings. `commandsPlugin(config)` registers them over\n * {@link COMMANDS_DEFAULTS}, and `updateSettings()` changes them while the app runs.\n */\nexport interface CommandsSettings {\n  /** The commands your viewer has. A later definition with an id that's taken replaces the earlier one. */\n  readonly commands: readonly (CommandDef | CommandFamily)[];\n  /**\n   * Categories turned off, with every category under them: their commands are hidden and\n   * refused wherever they appear.\n   */\n  readonly disabledCategories: readonly string[];\n  /** Commands turned off one by one, by id: hidden and refused wherever they appear. */\n  readonly disabledCommands: readonly CommandId[];\n  /**\n   * What a command the scope doesn't allow does: `'hide'` leaves it out, `'disable'` shows it\n   * disabled, with the reason in its `disabledReason`.\n   */\n  readonly notAllowed: NotAllowedMode;\n}\n\n/** How a command shows when the scope doesn't allow it: hidden, or disabled with its reason. */\nexport type NotAllowedMode = 'hide' | 'disable';\n\n/** What the commands settings are when the app registers none. */\nexport const COMMANDS_DEFAULTS: CommandsSettings = {\n  commands: [],\n  disabledCategories: [],\n  disabledCommands: [],\n  notAllowed: 'hide',\n};\n\n/** What `commandsPlugin(config)` takes: any of the settings, merged over the defaults. */\nexport type CommandsConfig = DeepPartial<CommandsSettings>;\n\nexport interface RegisterCommandOptions {\n  /** Replace a command with the same id; without it, a taken id throws `conflict`. */\n  replace?: boolean;\n}\n\nexport interface ExecuteOptions extends OperationOptions {\n  /** The document to run it for; the document in scope, else the active one, when left out. */\n  documentId?: string;\n  /** Passed to the command's `run` and derivations as `args`. */\n  args?: unknown;\n}\n\n/** How `execute()` went: it ran, or it was refused before running, and why. */\nexport type ExecuteResult =\n  | { readonly status: 'executed' }\n  | { readonly status: 'rejected'; readonly reason: 'not-found' | 'disabled' | 'hidden' };\n\n// ── events ──\nexport interface CommandExecutedEvent {\n  readonly commandId: CommandId;\n  readonly documentId: string | null;\n  readonly args: unknown;\n}\nexport interface CommandExecutionFailedEvent {\n  readonly commandId: CommandId;\n  readonly documentId: string | null;\n  readonly error: PluginErrorInfo;\n}\n\n/**\n * The commands. A call that leaves out the document is for the document in scope when the\n * capability was resolved for one (`ctx.forDocument`, a `<DocumentScope>`), and for the active\n * document otherwise.\n */\nexport interface CommandsCapability extends SettingsApi<CommandsSettings> {\n  // ── the commands ──\n  /**\n   * Add a command while the app runs, and get a function that removes it. A taken id throws\n   * `conflict` unless `replace`.\n   */\n  registerCommand(definition: CommandDef, options?: RegisterCommandOptions): Unsubscribe;\n  /** `registerCommand` for several definitions; the function removes all of them. */\n  registerCommands(\n    definitions: readonly CommandDef[],\n    options?: RegisterCommandOptions,\n  ): Unsubscribe;\n  /** Whether a command has this id; with a family, every id that starts with its prefix does. */\n  hasCommand(id: CommandId): boolean;\n  /** A command as you defined it, or `null`. */\n  getCommand(id: CommandId): CommandDef | null;\n  /** Every command's id for the active document, in the order they were added. The same array until one changes. */\n  listCommandIds(): readonly CommandId[];\n\n  // ── what a button shows ──\n  /** A command as a button shows it, or `null` for an unknown id. The same object while nothing about it changed. */\n  resolveCommand(id: CommandId, documentId?: string): ResolvedCommand | null;\n  /** Every command, resolved, in the order they were added. The same array while nothing changed. */\n  listCommands(documentId?: string): readonly ResolvedCommand[];\n  /** The visible commands whose label or id contains the query, for a command palette. */\n  searchCommands(query: string, documentId?: string): readonly ResolvedCommand[];\n  /** Every shortcut with its command, for a keyboard help sheet. The same array until the commands change. */\n  listShortcuts(): readonly { readonly commandId: CommandId; readonly shortcut: string }[];\n\n  // ── running them ──\n  /**\n   * Run a command; resolves once its `run` has, with `{ status: 'executed' }` and\n   * `onExecuted`, or `{ status: 'rejected', reason }` for a command that is unknown, hidden or\n   * disabled (a command turned off is hidden). A `run` that throws fires `onExecutionFailed` and rejects with its `PluginError`;\n   * the signal rejects `operation-cancelled`.\n   */\n  execute(id: CommandId, options?: ExecuteOptions): Promise<ExecuteResult>;\n  /** Whether a command can run now: it exists, and is enabled and visible. */\n  canExecute(id: CommandId, documentId?: string): boolean;\n  /**\n   * Why a command won't run whatever the moment: it's turned off, or not allowed for its\n   * document. `null` when it may run (or only can't right now), and for an unknown id.\n   */\n  getRefusal(id: CommandId, documentId?: string): CommandRefusal | null;\n\n  // ── turning commands off ──\n  /** The categories turned off. */\n  getDisabledCategories(): readonly string[];\n  /** Whether a category is turned off: it, or a category it's under (`annotations` for `annotations.highlight`). */\n  isCategoryDisabled(category: string): boolean;\n  /** Turn a category off, with every category under it: the `disabledCategories` setting gains it. */\n  disableCategory(category: string): void;\n  /** Turn a category on again. */\n  enableCategory(category: string): void;\n  /** Replace the categories that are off. */\n  setDisabledCategories(categories: readonly string[]): void;\n  /** The commands turned off one by one. */\n  getDisabledCommands(): readonly CommandId[];\n  /** Whether a command is turned off: by its id, or through one of its categories. */\n  isCommandDisabled(id: CommandId): boolean;\n  /** Turn one command off: the `disabledCommands` setting gains it. */\n  disableCommand(id: CommandId): void;\n  /** Turn a command on again; it stays off while one of its categories is. */\n  enableCommand(id: CommandId): void;\n  /** Replace the commands that are off one by one. */\n  setDisabledCommands(ids: readonly CommandId[]): void;\n\n  // ── events ──\n  /** A command ran. */\n  readonly onExecuted: EventHook<CommandExecutedEvent>;\n  /** A command's `run` threw; `execute` rejects with the same error. */\n  readonly onExecutionFailed: EventHook<CommandExecutionFailedEvent>;\n}\n"],"mappings":";;;;;AAMA,MAAa,gBAAgB,sBAA0C,YAAY,EACjF,MAAM,6EACR,CAAC;;;;;;;AC0KD,MAAa,yBACX,MACA,UACY;CACZ,IAAI,SAAS,OAAO,OAAO;CAC3B,IAAI,CAAC,QAAQ,CAAC,OAAO,OAAO;CAC5B,OACE,KAAK,OAAO,MAAM,MAClB,KAAK,UAAU,MAAM,SACrB,KAAK,SAAS,MAAM,QACpB,KAAK,YAAY,YAAY,MAAM,YAAY,WAC/C,KAAK,YAAY,cAAc,MAAM,YAAY,aACjD,KAAK,SAAS,MAAM,QACpB,KAAK,YAAY,MAAM,WACvB,KAAK,WAAW,MAAM,UACtB,KAAK,YAAY,MAAM,WACvB,KAAK,mBAAmB,MAAM,kBAC9B,KAAK,UAAU,WAAW,MAAM,UAAU,UAC1C,KAAK,UAAU,OAAO,UAAU,UAAU,aAAa,MAAM,UAAU,MAAM;AAEjF;;;;;AAMA,MAAa,uBAAuB,QAAoC;CACtE;CACA,OAAO;CACP,WAAW,CAAC;CACZ,SAAS;CACT,QAAQ;CACR,SAAS;CACT,YAAY,CAAC;AACf;;AAGA,MAAa,yBAAyB,IAAe,UACnD,eAAe,GAAG,GAAG,WAAW,IAAI,KAAK,EAAE;;;;;;AAe7C,SAAgB,eACd,SACA,SACA,SACc;CACd,MAAM,CAAC,SAAS,QAAQ;CACxB,OAAO;EACL,GAAG;EACH,WAAW,QAAQ,QAAQ,EAAE;EAC7B,UAAU,UAAU,KAAA,IAAY,OAAO,eAAe,OAAO,EAAE,OAAO,QAAQ,MAAM,CAAC;CACvF;AACF;;AA2BA,MAAa,oBAAsC;CACjD,UAAU,CAAC;CACX,oBAAoB,CAAC;CACrB,kBAAkB,CAAC;CACnB,YAAY;AACd"}

package/dist/contract-DAV5VR3P.d.cts

@@ -0,0 +1,295 @@
+import { CapabilityToken, DeepPartial, EventHook, OperationOptions, Permission, PluginErrorInfo, SettingsApi, Unsubscribe } from "@embedpdf/core";
+//#region src/token.d.ts
+declare const CommandsToken: import("@embedpdf/core").CapabilityToken<CommandsCapability>;
+//#endregion
+//#region src/contract.d.ts
+type CommandId = string;
+/**
+ * What a command's derivations and `run` see: capabilities resolved for the command's document
+ * (the one named, else the document in scope, else the active one).
+ */
+interface CommandContext {
+  /** The command's document, or `null` when none is open. */
+  readonly documentId: string | null;
+  /** What the caller passed: `execute(id, { args })`. */
+  readonly args?: unknown;
+  /** Fires when the caller cancels `execute()`: pass it on to the calls `run` makes. */
+  readonly signal?: AbortSignal;
+  /** A capability, for the command's document when the plugin is document-scoped. Throws when it isn't available. */
+  get<T>(token: CapabilityToken<T>): T;
+  /** Like `get`, but `null` when the capability isn't available (no plugin, no document). */
+  tryGet<T>(token: CapabilityToken<T>): T | null;
+}
+/**
+ * Up to two colors that go with a command's icon, such as a tool's current color: data a
+ * renderer may use (tint the icon, show a swatch), like `icon` itself.
+ */
+interface IconAccent {
+  /** The mark: a stroke, the markup or the text color. */
+  readonly primary?: string;
+  /** The fill, when there is one. */
+  readonly secondary?: string;
+}
+/** One command, as you define it. */
+interface CommandDef {
+  /** A unique name, by convention `area:action`: `'zoom:in'`, `'review:approve'`. */
+  readonly id: string;
+  /** What the user sees. With `labelKey` too, it's what shows when no language has the key. */
+  readonly label?: string;
+  /**
+   * A translation key for the label, read through the i18n plugin. Without the plugin, or a
+   * string for the key, the command shows `label`, else the key.
+   */
+  readonly labelKey?: string;
+  /** Your icon's name; your buttons turn it into an icon. */
+  readonly icon?: string;
+  /** Colors for the icon, read from live state like `active`. */
+  readonly iconAccent?: (context: CommandContext) => IconAccent | null;
+  /** A key such as `'Mod+K'` (`Mod` is Cmd on a Mac, Ctrl elsewhere), or a list of them. */
+  readonly shortcut?: string | readonly string[];
+  /**
+   * Whether its shortcut also runs while the cursor is in a text field where the shortcuts
+   * listen (a search box, a comment), as the viewer's Find does. Default false: a key typed in
+   * a field is the field's.
+   */
+  readonly shortcutInTextFields?: boolean;
+  /**
+   * The features it belongs to, so turning one off turns it off: `['annotations.highlight']`.
+   * Turning off a feature turns off every feature under it, on whole dotted parts: `annotations`
+   * covers `annotations.highlight`, not `annotationsExtra`.
+   */
+  readonly categories?: readonly string[];
+  /**
+   * The scope permissions it needs, such as `'doc.annotate.modify'`, checked against its
+   * document. Without them it's hidden, or shown disabled with its reason under the
+   * `notAllowed: 'disable'` setting. With no document open there is nothing to check.
+   */
+  readonly requires?: readonly Permission[];
+  /**
+   * Whether the session may run it, from the plugins' `can*` checks
+   * (`documents.canPrint()`), for a command whose permission is a plugin's to know. When it
+   * says no, the command isn't allowed, as with `requires`. Asked only while a document is
+   * open; one that throws allows it.
+   */
+  readonly allowed?: (context: CommandContext) => boolean;
+  /**
+   * The translation key of the sentence that says why `allowed` refused it, with `{label}` for
+   * its label: `'commands.notAllowed.doc-print'`. Without it, or a string for it,
+   * `commands.notAllowed.default`.
+   */
+  readonly notAllowedKey?: string;
+  /** Opens and closes a menu of yours, by its id. */
+  readonly menu?: string;
+  /**
+   * Opens and closes a panel, closing the others with the same `exclusive` tag. With `focus`,
+   * opening it asks for the cursor (the shell's `open(id, { focus: true })`).
+   */
+  readonly panel?: string | {
+    readonly id: string;
+    readonly exclusive?: string;
+    readonly focus?: boolean;
+  };
+  /** Opens and closes a dialog; one dialog is open at a time. */
+  readonly modal?: string;
+  /** When it can run. Default: always. */
+  readonly enabled?: (context: CommandContext) => boolean;
+  /** When it shows as pressed, such as the current tool. */
+  readonly active?: (context: CommandContext) => boolean;
+  /** When it shows at all. Default: always. */
+  readonly visible?: (context: CommandContext) => boolean;
+  /** What it does; `execute()` resolves once it has. Not needed for a `menu`, `panel` or `modal`. */
+  readonly run?: (context: CommandContext) => void | Promise<unknown>;
+}
+/**
+ * A command for each of a set of names, made from one definition, such as `tool:<id>` for every
+ * tool a document has. Its commands resolve and run like any other, and `listCommands()` lists
+ * one per name. A command defined with the same id wins over the family's.
+ */
+interface CommandFamily {
+  /** Where the commands' ids start: `'tool:'` makes `tool:highlight`. */
+  readonly prefix: string;
+  /** The names the command's document has, in order. Return the same array while nothing changed. */
+  readonly names: (context: CommandContext) => readonly string[];
+  /** The command for one name. A family's commands have no shortcuts. */
+  readonly command: (name: string) => Omit<CommandDef, 'id' | 'shortcut'>;
+}
+/** A command as a button shows it: everything read for its 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[];
+  /**
+   * Why it's disabled, as a sentence for its tooltip: set when the scope doesn't allow it and
+   * the `notAllowed` setting is `'disable'`.
+   */
+  readonly disabledReason?: string;
+}
+/**
+ * Why a command won't run whatever the moment: it's turned off in this viewer
+ * (`disabledCategories`, `disabledCommands`), or the scope doesn't allow it (`requires`).
+ * A command that only can't run right now (`enabled`, `visible`) has no refusal.
+ */
+interface CommandRefusal {
+  readonly reason: 'turned-off' | 'not-allowed';
+  /** A sentence for the user, translated through the i18n plugin when it's there. */
+  readonly message: string;
+}
+/**
+ * Whether two resolved commands show the same, for readers that compare what a command looks
+ * like rather than which object holds it (a group of commands, or one command for two documents).
+ */
+declare const resolvedCommandsEqual: (left: ResolvedCommand | null, right: ResolvedCommand | null) => boolean;
+/**
+ * What a component or a toolbar draws for a command id no plugin registered: labelled with its
+ * id, neither enabled nor visible, the way a turned-off command is.
+ */
+declare const unregisteredCommand: (id: CommandId) => ResolvedCommand;
+/** What a component that asks for an id no plugin registered hears, in development. */
+declare const unknownCommandWarning: (id: CommandId, known: Iterable<CommandId>) => string;
+/** A command with everything a button needs: what it shows, `run`, and its shortcut for a tooltip. */
+interface BoundCommand extends ResolvedCommand {
+  /** Run the command for the document it was read for. */
+  readonly run: () => Promise<ExecuteResult>;
+  /** Its first shortcut, formatted for the platform (`'⌘K'` on a Mac, `'Ctrl+K'` elsewhere), or `null`. */
+  readonly shortcut: string | null;
+}
+/**
+ * A resolved command, bound for a button: `run` executes it through `execute`, and `shortcut` is
+ * its first shortcut formatted for the platform. Which platform is the caller's to know
+ * (`isMacPlatform()` in `@embedpdf/web`).
+ */
+declare function boundCommandOf(command: ResolvedCommand, execute: (id: CommandId) => Promise<ExecuteResult>, options: {
+  readonly isMac: boolean;
+}): BoundCommand;
+/**
+ * The commands plugin's settings. `commandsPlugin(config)` registers them over
+ * {@link COMMANDS_DEFAULTS}, and `updateSettings()` changes them while the app runs.
+ */
+interface CommandsSettings {
+  /** The commands your viewer has. A later definition with an id that's taken replaces the earlier one. */
+  readonly commands: readonly (CommandDef | CommandFamily)[];
+  /**
+   * Categories turned off, with every category under them: their commands are hidden and
+   * refused wherever they appear.
+   */
+  readonly disabledCategories: readonly string[];
+  /** Commands turned off one by one, by id: hidden and refused wherever they appear. */
+  readonly disabledCommands: readonly CommandId[];
+  /**
+   * What a command the scope doesn't allow does: `'hide'` leaves it out, `'disable'` shows it
+   * disabled, with the reason in its `disabledReason`.
+   */
+  readonly notAllowed: NotAllowedMode;
+}
+/** How a command shows when the scope doesn't allow it: hidden, or disabled with its reason. */
+type NotAllowedMode = 'hide' | 'disable';
+/** What the commands settings are when the app registers none. */
+declare const COMMANDS_DEFAULTS: CommandsSettings;
+/** What `commandsPlugin(config)` takes: any of the settings, merged over the defaults. */
+type CommandsConfig = DeepPartial<CommandsSettings>;
+interface RegisterCommandOptions {
+  /** Replace a command with the same id; without it, a taken id throws `conflict`. */
+  replace?: boolean;
+}
+interface ExecuteOptions extends OperationOptions {
+  /** The document to run it for; the document in scope, else the active one, when left out. */
+  documentId?: string;
+  /** Passed to the command's `run` and derivations as `args`. */
+  args?: unknown;
+}
+/** How `execute()` went: it ran, or it was refused before running, and why. */
+type ExecuteResult = {
+  readonly status: 'executed';
+} | {
+  readonly status: 'rejected';
+  readonly reason: 'not-found' | 'disabled' | 'hidden';
+};
+interface CommandExecutedEvent {
+  readonly commandId: CommandId;
+  readonly documentId: string | null;
+  readonly args: unknown;
+}
+interface CommandExecutionFailedEvent {
+  readonly commandId: CommandId;
+  readonly documentId: string | null;
+  readonly error: PluginErrorInfo;
+}
+/**
+ * The commands. A call that leaves out the document is for the document in scope when the
+ * capability was resolved for one (`ctx.forDocument`, a `<DocumentScope>`), and for the active
+ * document otherwise.
+ */
+interface CommandsCapability extends SettingsApi<CommandsSettings> {
+  /**
+   * Add a command while the app runs, and get a function that removes it. A taken id throws
+   * `conflict` unless `replace`.
+   */
+  registerCommand(definition: CommandDef, options?: RegisterCommandOptions): Unsubscribe;
+  /** `registerCommand` for several definitions; the function removes all of them. */
+  registerCommands(definitions: readonly CommandDef[], options?: RegisterCommandOptions): Unsubscribe;
+  /** Whether a command has this id; with a family, every id that starts with its prefix does. */
+  hasCommand(id: CommandId): boolean;
+  /** A command as you defined it, or `null`. */
+  getCommand(id: CommandId): CommandDef | null;
+  /** Every command's id for the active document, in the order they were added. The same array until one changes. */
+  listCommandIds(): readonly CommandId[];
+  /** A command as a button shows it, or `null` for an unknown id. The same object while nothing about it changed. */
+  resolveCommand(id: CommandId, documentId?: string): ResolvedCommand | null;
+  /** Every command, resolved, in the order they were added. The same array while nothing changed. */
+  listCommands(documentId?: string): readonly ResolvedCommand[];
+  /** The visible commands whose label or id contains the query, for a command palette. */
+  searchCommands(query: string, documentId?: string): readonly ResolvedCommand[];
+  /** Every shortcut with its command, for a keyboard help sheet. The same array until the commands change. */
+  listShortcuts(): readonly {
+    readonly commandId: CommandId;
+    readonly shortcut: string;
+  }[];
+  /**
+   * Run a command; resolves once its `run` has, with `{ status: 'executed' }` and
+   * `onExecuted`, or `{ status: 'rejected', reason }` for a command that is unknown, hidden or
+   * disabled (a command turned off is hidden). A `run` that throws fires `onExecutionFailed` and rejects with its `PluginError`;
+   * the signal rejects `operation-cancelled`.
+   */
+  execute(id: CommandId, options?: ExecuteOptions): Promise<ExecuteResult>;
+  /** Whether a command can run now: it exists, and is enabled and visible. */
+  canExecute(id: CommandId, documentId?: string): boolean;
+  /**
+   * Why a command won't run whatever the moment: it's turned off, or not allowed for its
+   * document. `null` when it may run (or only can't right now), and for an unknown id.
+   */
+  getRefusal(id: CommandId, documentId?: string): CommandRefusal | null;
+  /** The categories turned off. */
+  getDisabledCategories(): readonly string[];
+  /** Whether a category is turned off: it, or a category it's under (`annotations` for `annotations.highlight`). */
+  isCategoryDisabled(category: string): boolean;
+  /** Turn a category off, with every category under it: the `disabledCategories` setting gains it. */
+  disableCategory(category: string): void;
+  /** Turn a category on again. */
+  enableCategory(category: string): void;
+  /** Replace the categories that are off. */
+  setDisabledCategories(categories: readonly string[]): void;
+  /** The commands turned off one by one. */
+  getDisabledCommands(): readonly CommandId[];
+  /** Whether a command is turned off: by its id, or through one of its categories. */
+  isCommandDisabled(id: CommandId): boolean;
+  /** Turn one command off: the `disabledCommands` setting gains it. */
+  disableCommand(id: CommandId): void;
+  /** Turn a command on again; it stays off while one of its categories is. */
+  enableCommand(id: CommandId): void;
+  /** Replace the commands that are off one by one. */
+  setDisabledCommands(ids: readonly CommandId[]): void;
+  /** A command ran. */
+  readonly onExecuted: EventHook<CommandExecutedEvent>;
+  /** A command's `run` threw; `execute` rejects with the same error. */
+  readonly onExecutionFailed: EventHook<CommandExecutionFailedEvent>;
+}
+//#endregion
+export { CommandsToken as C, unregisteredCommand as S, RegisterCommandOptions as _, CommandExecutedEvent as a, resolvedCommandsEqual as b, CommandId as c, CommandsConfig as d, CommandsSettings as f, NotAllowedMode as g, IconAccent as h, CommandDef as i, CommandRefusal as l, ExecuteResult as m, COMMANDS_DEFAULTS as n, CommandExecutionFailedEvent as o, ExecuteOptions as p, CommandContext as r, CommandFamily as s, BoundCommand as t, CommandsCapability as u, ResolvedCommand as v, unknownCommandWarning as x, boundCommandOf as y };
+//# sourceMappingURL=contract-DAV5VR3P.d.cts.map