@embedpdf/react 3.0.0-next.14 → 3.0.0-next.15

package/dist/commands.cjs

@@ -1,52 +1,92 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 require("./rolldown-runtime-DDXJien1.cjs");
-const require_runtime = require("./runtime.cjs");
+const require_runtime = require("./runtime-fzpGv78v.cjs");
+const require_state = require("./state-CsfZy_Eq.cjs");
+let _embedpdf_web = require("@embedpdf/web");
 let react = require("react");
 let _embedpdf_plugin_commands = require("@embedpdf/plugin-commands");
+let _embedpdf_core_ui = require("@embedpdf/core-ui");
+let _embedpdf_plugin_commands_contract_host = require("@embedpdf/plugin-commands/contract/host");
 //#region src/commands.ts
-/** The commands capability (register/execute/search/categories). */
+/**
+* The commands every viewer has: zoom, pages, view rotation, `tool:<id>` for every tool, copy,
+* delete, download and print, with shortcuts and labels in EmbedPDF's eight languages. Spread
+* them into `commandsPlugin({ commands })`.
+*/
+const standardCommands = /* @__PURE__ */ (0, require("@embedpdf/plugin-commands/standard").createStandardCommands)(_embedpdf_web.standardCommandsBrowser);
+/** The commands capability: `execute`, `searchCommands`, `registerCommand`, the categories, the settings calls. */
 function useCommands() {
 	return require_runtime.useCapability(_embedpdf_plugin_commands.CommandsToken);
 }
-/** A command resolved against this subtree's document, reactively. */
+/** Subscribe to one commands event for the mounted lifetime: `useCommandsEvent((commands) => commands.onExecuted, handler)`. */
+function useCommandsEvent(select, handler) {
+	require_runtime.useCapabilityEvent(_embedpdf_plugin_commands.CommandsToken, select, handler);
+}
+/**
+* The commands settings (`commands`, `disabledCategories`, `disabledCommands`, `notAllowed`),
+* with or without a document. Takes a selector.
+*/
+const useCommandsSettings = require_state.settingsHook(_embedpdf_plugin_commands.CommandsToken);
+/** A shortcut as a tooltip shows it, for this platform: `'⌘K'` on a Mac, `'Ctrl+K'` elsewhere. */
+function formatShortcut(shortcut, options = {}) {
+	return (0, _embedpdf_core_ui.formatShortcut)(shortcut, { isMac: options.isMac ?? (0, _embedpdf_web.isMacPlatform)() });
+}
+/**
+* A command for this component's document (the nearest <DocumentScope>, else the active one):
+* its label, icon, state, `run` and `shortcut`. Re-renders when any of them changes. Always a
+* command: an id no plugin registered is labelled with its id, neither visible nor enabled, and
+* warns once in development.
+*/
 function useCommand(id) {
 	const commands = require_runtime.useCapability(_embedpdf_plugin_commands.CommandsToken);
-	const documentId = require_runtime.useDocumentId();
-	return require_runtime.useKernelValue(() => commands.resolve(id, documentId ?? void 0), _embedpdf_plugin_commands.resolvedCommandsEqual);
+	const documentId = require_runtime.useDocumentId() ?? void 0;
+	const resolved = require_runtime.useKernelValue(() => commands.resolveCommand(id, documentId), _embedpdf_plugin_commands.resolvedCommandsEqual);
+	if (resolved === null) require_runtime.devWarn(`useCommand:${id}`, `useCommand(): ${(0, _embedpdf_plugin_commands.unknownCommandWarning)(id, commands.listCommandIds())}`);
+	return (0, react.useMemo)(() => (0, _embedpdf_plugin_commands.boundCommandOf)(resolved ?? (0, _embedpdf_plugin_commands.unregisteredCommand)(id), (commandId) => commands.execute(commandId, { documentId }), { isMac: (0, _embedpdf_web.isMacPlatform)() }), [
+		resolved,
+		commands,
+		documentId,
+		id
+	]);
 }
-/** Is this environment mac-like? Decides how 'Mod' resolves and displays. */
-const isMacPlatform = () => typeof navigator !== "undefined" && /Mac|iP(hone|ad|od)/.test(navigator.platform);
-const isEditableTarget = (target) => {
-	const el = target;
-	if (!el || !el.tagName) return false;
-	return el.tagName === "INPUT" || el.tagName === "TEXTAREA" || el.isContentEditable;
-};
 /**
-* Bind every registered shortcut. One listener for the whole registry —
-* matching is pure (ui-core), execution goes through the one command path.
-* Strokes from editable elements are ignored.
+* Turn every command's shortcut into a working key, for the active document. Call it once, near
+* the top of your viewer. Keys typed into text fields are left alone, and so is a key whose
+* command can't run right now. A command that's turned off or not allowed still takes its key,
+* and `onRefused` says why. The keys work anywhere on the page; with `target`, only while focus
+* is inside that element, for a page with more than one viewer.
 */
 function useCommandShortcuts(options) {
-	const commands = require_runtime.useCapability(_embedpdf_plugin_commands.CommandsToken);
+	const commands = require_runtime.useCapability(_embedpdf_plugin_commands_contract_host.CommandsToken);
 	const isMac = options?.isMac;
+	const target = options?.target;
+	const onRefused = (0, react.useRef)(options?.onRefused);
+	onRefused.current = options?.onRefused;
 	(0, react.useEffect)(() => {
-		const mac = isMac ?? isMacPlatform();
-		const onKeyDown = (event) => {
-			if (event.defaultPrevented || isEditableTarget(event.target)) return;
-			const id = commands.matchStroke(event, { isMac: mac });
-			if (!id) return;
-			event.preventDefault();
-			commands.execute(id);
-		};
-		window.addEventListener("keydown", onKeyDown);
-		return () => window.removeEventListener("keydown", onKeyDown);
-	}, [commands, isMac]);
+		const report = (commandId, refusal) => onRefused.current?.(commandId, refusal);
+		if (!target) return (0, _embedpdf_web.bindCommandShortcuts)(commands, {
+			isMac,
+			onRefused: report
+		});
+		return target.current ? (0, _embedpdf_web.bindCommandShortcuts)(commands, {
+			isMac,
+			target: target.current,
+			onRefused: report
+		}) : void 0;
+	}, [
+		commands,
+		isMac,
+		target
+	]);
 }
 //#endregion
-exports.isMacPlatform = isMacPlatform;
+exports.formatShortcut = formatShortcut;
+exports.standardCommands = standardCommands;
 exports.useCommand = useCommand;
 exports.useCommandShortcuts = useCommandShortcuts;
 exports.useCommands = useCommands;
+exports.useCommandsEvent = useCommandsEvent;
+exports.useCommandsSettings = useCommandsSettings;
 Object.keys(_embedpdf_plugin_commands).forEach(function(k) {
 	if (k !== "default" && !Object.prototype.hasOwnProperty.call(exports, k)) Object.defineProperty(exports, k, {
 		enumerable: true,

package/dist/commands.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"commands.cjs","names":["useCapability","CommandsToken","useDocumentId","useKernelValue","resolvedCommandsEqual"],"sources":["../src/commands.ts"],"sourcesContent":["/**\n * The React surface for @embedpdf/plugin-commands.\n *\n * Command state is a pure derivation over the store, so these hooks are thin:\n * `useCommand` re-resolves on the kernel's one change stream (cached by value\n * equality — locale flips, permission changes, and active-tool changes all\n * propagate with zero events), and `useCommandShortcuts` is the ~20 lines of\n * DOM that turn the registry's pure stroke matcher into a live keymap.\n */\n\n// One-line-per-feature: registration travels with the UI.\n// (resolvedCommandsEqual lives in the plugin now — it's pure value equality\n// over ResolvedCommand, framework-free — and arrives through this star.)\nexport * from '@embedpdf/plugin-commands';\nimport { useEffect } from 'react';\nimport { CommandsToken, resolvedCommandsEqual } from '@embedpdf/plugin-commands';\nimport type { CommandsCapability, ResolvedCommand } from '@embedpdf/plugin-commands';\nimport { useCapability, useDocumentId, useKernelValue } from './runtime';\n\n/** The commands capability (register/execute/search/categories). */\nexport function useCommands(): CommandsCapability {\n  return useCapability(CommandsToken);\n}\n\n/** A command resolved against this subtree's document, reactively. */\nexport function useCommand(id: string): ResolvedCommand | null {\n  const commands = useCapability(CommandsToken);\n  const documentId = useDocumentId();\n  return useKernelValue(() => commands.resolve(id, documentId ?? undefined), resolvedCommandsEqual);\n}\n\n/** Is this environment mac-like? Decides how 'Mod' resolves and displays. */\nexport const isMacPlatform = (): boolean =>\n  typeof navigator !== 'undefined' && /Mac|iP(hone|ad|od)/.test(navigator.platform);\n\nconst isEditableTarget = (target: EventTarget | null): boolean => {\n  const el = target as HTMLElement | null;\n  if (!el || !el.tagName) return false;\n  return el.tagName === 'INPUT' || el.tagName === 'TEXTAREA' || el.isContentEditable;\n};\n\n/**\n * Bind every registered shortcut. One listener for the whole registry —\n * matching is pure (ui-core), execution goes through the one command path.\n * Strokes from editable elements are ignored.\n */\nexport function useCommandShortcuts(options?: { isMac?: boolean }): void {\n  const commands = useCapability(CommandsToken);\n  const isMac = options?.isMac;\n  useEffect(() => {\n    const mac = isMac ?? isMacPlatform();\n    const onKeyDown = (event: KeyboardEvent) => {\n      if (event.defaultPrevented || isEditableTarget(event.target)) return;\n      const id = commands.matchStroke(event, { isMac: mac });\n      if (!id) return;\n      event.preventDefault();\n      commands.execute(id);\n    };\n    window.addEventListener('keydown', onKeyDown);\n    return () => window.removeEventListener('keydown', onKeyDown);\n  }, [commands, isMac]);\n}\n"],"mappings":";;;;;;;AAoBA,SAAgB,cAAkC;CAChD,OAAOA,gBAAAA,cAAcC,0BAAAA,aAAa;AACpC;;AAGA,SAAgB,WAAW,IAAoC;CAC7D,MAAM,WAAWD,gBAAAA,cAAcC,0BAAAA,aAAa;CAC5C,MAAM,aAAaC,gBAAAA,cAAc;CACjC,OAAOC,gBAAAA,qBAAqB,SAAS,QAAQ,IAAI,cAAc,KAAA,CAAS,GAAGC,0BAAAA,qBAAqB;AAClG;;AAGA,MAAa,sBACX,OAAO,cAAc,eAAe,qBAAqB,KAAK,UAAU,QAAQ;AAElF,MAAM,oBAAoB,WAAwC;CAChE,MAAM,KAAK;CACX,IAAI,CAAC,MAAM,CAAC,GAAG,SAAS,OAAO;CAC/B,OAAO,GAAG,YAAY,WAAW,GAAG,YAAY,cAAc,GAAG;AACnE;;;;;;AAOA,SAAgB,oBAAoB,SAAqC;CACvE,MAAM,WAAWJ,gBAAAA,cAAcC,0BAAAA,aAAa;CAC5C,MAAM,QAAQ,SAAS;CACvB,CAAA,GAAA,MAAA,UAAA,OAAgB;EACd,MAAM,MAAM,SAAS,cAAc;EACnC,MAAM,aAAa,UAAyB;GAC1C,IAAI,MAAM,oBAAoB,iBAAiB,MAAM,MAAM,GAAG;GAC9D,MAAM,KAAK,SAAS,YAAY,OAAO,EAAE,OAAO,IAAI,CAAC;GACrD,IAAI,CAAC,IAAI;GACT,MAAM,eAAe;GACrB,SAAS,QAAQ,EAAE;EACrB;EACA,OAAO,iBAAiB,WAAW,SAAS;EAC5C,aAAa,OAAO,oBAAoB,WAAW,SAAS;CAC9D,GAAG,CAAC,UAAU,KAAK,CAAC;AACtB"}
+{"version":3,"file":"commands.cjs","names":["standardCommandsBrowser","useCapability","CommandsToken","settingsHook","useDocumentId","useKernelValue","resolvedCommandsEqual","CommandsHostToken"],"sources":["../src/commands.ts"],"sourcesContent":["/**\n * The React surface for @embedpdf/plugin-commands: the standard commands, a\n * command as a button needs it, the settings, and keyboard shortcuts. A\n * command's state is read from live state, so `useCommand` re-renders on the\n * kernel's one change stream, only when what the command shows changed.\n */\n\n// One-line-per-feature: registration travels with the UI.\nexport * from '@embedpdf/plugin-commands';\nimport { useEffect, useMemo, useRef, type RefObject } from 'react';\nimport { formatShortcut as formatKeys } from '@embedpdf/core-ui';\nimport {\n  CommandsToken,\n  boundCommandOf,\n  resolvedCommandsEqual,\n  unknownCommandWarning,\n  unregisteredCommand,\n} from '@embedpdf/plugin-commands';\nimport type {\n  BoundCommand,\n  CommandId,\n  CommandRefusal,\n  CommandsCapability,\n} from '@embedpdf/plugin-commands';\nimport { CommandsToken as CommandsHostToken } from '@embedpdf/plugin-commands/contract/host';\nimport { createStandardCommands } from '@embedpdf/plugin-commands/standard';\nimport type { EventHook } from '@embedpdf/core';\nimport { bindCommandShortcuts, isMacPlatform, standardCommandsBrowser } from '@embedpdf/web';\nimport { devWarn } from './dev';\nimport { useCapability, useCapabilityEvent, useDocumentId, useKernelValue } from './runtime';\nimport { settingsHook } from './state';\n\n/**\n * The commands every viewer has: zoom, pages, view rotation, `tool:<id>` for every tool, copy,\n * delete, download and print, with shortcuts and labels in EmbedPDF's eight languages. Spread\n * them into `commandsPlugin({ commands })`.\n */\nexport const standardCommands = /* @__PURE__ */ createStandardCommands(standardCommandsBrowser);\n\n/** The commands capability: `execute`, `searchCommands`, `registerCommand`, the categories, the settings calls. */\nexport function useCommands(): CommandsCapability {\n  return useCapability(CommandsToken);\n}\n\n/** Subscribe to one commands event for the mounted lifetime: `useCommandsEvent((commands) => commands.onExecuted, handler)`. */\nexport function useCommandsEvent<T>(\n  select: (commands: CommandsCapability) => EventHook<T>,\n  handler: (event: T) => void,\n): void {\n  useCapabilityEvent(CommandsToken, select, handler);\n}\n\n/**\n * The commands settings (`commands`, `disabledCategories`, `disabledCommands`, `notAllowed`),\n * with or without a document. Takes a selector.\n */\nexport const useCommandsSettings = settingsHook(CommandsToken);\n\n/** A shortcut as a tooltip shows it, for this platform: `'⌘K'` on a Mac, `'Ctrl+K'` elsewhere. */\nexport function formatShortcut(shortcut: string, options: { isMac?: boolean } = {}): string {\n  return formatKeys(shortcut, { isMac: options.isMac ?? isMacPlatform() });\n}\n\n/**\n * A command for this component's document (the nearest <DocumentScope>, else the active one):\n * its label, icon, state, `run` and `shortcut`. Re-renders when any of them changes. Always a\n * command: an id no plugin registered is labelled with its id, neither visible nor enabled, and\n * warns once in development.\n */\nexport function useCommand(id: string): BoundCommand {\n  const commands = useCapability(CommandsToken);\n  const documentId = useDocumentId() ?? undefined;\n  const resolved = useKernelValue(\n    () => commands.resolveCommand(id, documentId),\n    resolvedCommandsEqual,\n  );\n  if (resolved === null) {\n    devWarn(`useCommand:${id}`, `useCommand(): ${unknownCommandWarning(id, commands.listCommandIds())}`);\n  }\n  return useMemo(\n    () =>\n      boundCommandOf(\n        resolved ?? unregisteredCommand(id),\n        (commandId) => commands.execute(commandId, { documentId }),\n        { isMac: isMacPlatform() },\n      ),\n    [resolved, commands, documentId, id],\n  );\n}\n\n/**\n * Turn every command's shortcut into a working key, for the active document. Call it once, near\n * the top of your viewer. Keys typed into text fields are left alone, and so is a key whose\n * command can't run right now. A command that's turned off or not allowed still takes its key,\n * and `onRefused` says why. The keys work anywhere on the page; with `target`, only while focus\n * is inside that element, for a page with more than one viewer.\n */\nexport function useCommandShortcuts(options?: {\n  isMac?: boolean;\n  target?: RefObject<HTMLElement | null>;\n  onRefused?: (commandId: CommandId, refusal: CommandRefusal) => void;\n}): void {\n  const commands = useCapability(CommandsHostToken);\n  const isMac = options?.isMac;\n  const target = options?.target;\n  // The latest callback, so a new function each render doesn't bind the keys again.\n  const onRefused = useRef(options?.onRefused);\n  onRefused.current = options?.onRefused;\n  useEffect(() => {\n    const report = (commandId: CommandId, refusal: CommandRefusal) =>\n      onRefused.current?.(commandId, refusal);\n    if (!target) return bindCommandShortcuts(commands, { isMac, onRefused: report });\n    // The element mounts before this effect runs, so its ref is set by now.\n    return target.current\n      ? bindCommandShortcuts(commands, { isMac, target: target.current, onRefused: report })\n      : undefined;\n  }, [commands, isMac, target]);\n}\n"],"mappings":";;;;;;;;;;;;;;;AAqCA,MAAa,mBAAmC,iBAAA,+CAAA,CAAA,CAAA,uBAAA,CAAuBA,cAAAA,uBAAuB;;AAG9F,SAAgB,cAAkC;CAChD,OAAOC,gBAAAA,cAAcC,0BAAAA,aAAa;AACpC;;AAGA,SAAgB,iBACd,QACA,SACM;CACN,gBAAA,mBAAmBA,0BAAAA,eAAe,QAAQ,OAAO;AACnD;;;;;AAMA,MAAa,sBAAsBC,cAAAA,aAAaD,0BAAAA,aAAa;;AAG7D,SAAgB,eAAe,UAAkB,UAA+B,CAAC,GAAW;CAC1F,QAAA,GAAA,kBAAA,eAAA,CAAkB,UAAU,EAAE,OAAO,QAAQ,UAAA,GAAA,cAAA,cAAA,CAAuB,EAAE,CAAC;AACzE;;;;;;;AAQA,SAAgB,WAAW,IAA0B;CACnD,MAAM,WAAWD,gBAAAA,cAAcC,0BAAAA,aAAa;CAC5C,MAAM,aAAaE,gBAAAA,cAAc,KAAK,KAAA;CACtC,MAAM,WAAWC,gBAAAA,qBACT,SAAS,eAAe,IAAI,UAAU,GAC5CC,0BAAAA,qBACF;CACA,IAAI,aAAa,MACf,gBAAA,QAAQ,cAAc,MAAM,kBAAA,GAAA,0BAAA,sBAAA,CAAuC,IAAI,SAAS,eAAe,CAAC,GAAG;CAErG,QAAA,GAAA,MAAA,QAAA,QAAA,GAAA,0BAAA,eAAA,CAGM,aAAA,GAAA,0BAAA,oBAAA,CAAgC,EAAE,IACjC,cAAc,SAAS,QAAQ,WAAW,EAAE,WAAW,CAAC,GACzD,EAAE,QAAA,GAAA,cAAA,cAAA,CAAqB,EAAE,CAC3B,GACF;EAAC;EAAU;EAAU;EAAY;CAAE,CACrC;AACF;;;;;;;;AASA,SAAgB,oBAAoB,SAI3B;CACP,MAAM,WAAWL,gBAAAA,cAAcM,wCAAAA,aAAiB;CAChD,MAAM,QAAQ,SAAS;CACvB,MAAM,SAAS,SAAS;CAExB,MAAM,aAAA,GAAA,MAAA,OAAA,CAAmB,SAAS,SAAS;CAC3C,UAAU,UAAU,SAAS;CAC7B,CAAA,GAAA,MAAA,UAAA,OAAgB;EACd,MAAM,UAAU,WAAsB,YACpC,UAAU,UAAU,WAAW,OAAO;EACxC,IAAI,CAAC,QAAQ,QAAA,GAAA,cAAA,qBAAA,CAA4B,UAAU;GAAE;GAAO,WAAW;EAAO,CAAC;EAE/E,OAAO,OAAO,WAAA,GAAA,cAAA,qBAAA,CACW,UAAU;GAAE;GAAO,QAAQ,OAAO;GAAS,WAAW;EAAO,CAAC,IACnF,KAAA;CACN,GAAG;EAAC;EAAU;EAAO;CAAM,CAAC;AAC9B"}

package/dist/commands.d.cts

@@ -1,20 +1,47 @@
-import { CommandsCapability, ResolvedCommand } from "@embedpdf/plugin-commands";
+import { t as SettingsHook } from "./state-0K1I5cM4.cjs";
+import { EventHook } from "@embedpdf/core";
+import { RefObject } from "react";
+import { BoundCommand, CommandId, CommandRefusal, CommandsCapability } from "@embedpdf/plugin-commands";
 export * from "@embedpdf/plugin-commands";
 //#region src/commands.d.ts
-/** The commands capability (register/execute/search/categories). */
+/**
+ * The commands every viewer has: zoom, pages, view rotation, `tool:<id>` for every tool, copy,
+ * delete, download and print, with shortcuts and labels in EmbedPDF's eight languages. Spread
+ * them into `commandsPlugin({ commands })`.
+ */
+declare const standardCommands: readonly (import("@embedpdf/plugin-commands").CommandDef | import("@embedpdf/plugin-commands").CommandFamily)[];
+/** The commands capability: `execute`, `searchCommands`, `registerCommand`, the categories, the settings calls. */
 declare function useCommands(): CommandsCapability;
-/** A command resolved against this subtree's document, reactively. */
-declare function useCommand(id: string): ResolvedCommand | null;
-/** Is this environment mac-like? Decides how 'Mod' resolves and displays. */
-declare const isMacPlatform: () => boolean;
+/** Subscribe to one commands event for the mounted lifetime: `useCommandsEvent((commands) => commands.onExecuted, handler)`. */
+declare function useCommandsEvent<T>(select: (commands: CommandsCapability) => EventHook<T>, handler: (event: T) => void): void;
+/**
+ * The commands settings (`commands`, `disabledCategories`, `disabledCommands`, `notAllowed`),
+ * with or without a document. Takes a selector.
+ */
+declare const useCommandsSettings: SettingsHook<import("@embedpdf/plugin-commands").CommandsSettings>;
+/** A shortcut as a tooltip shows it, for this platform: `'⌘K'` on a Mac, `'Ctrl+K'` elsewhere. */
+declare function formatShortcut(shortcut: string, options?: {
+  isMac?: boolean;
+}): string;
+/**
+ * A command for this component's document (the nearest <DocumentScope>, else the active one):
+ * its label, icon, state, `run` and `shortcut`. Re-renders when any of them changes. Always a
+ * command: an id no plugin registered is labelled with its id, neither visible nor enabled, and
+ * warns once in development.
+ */
+declare function useCommand(id: string): BoundCommand;
 /**
- * Bind every registered shortcut. One listener for the whole registry —
- * matching is pure (ui-core), execution goes through the one command path.
- * Strokes from editable elements are ignored.
+ * Turn every command's shortcut into a working key, for the active document. Call it once, near
+ * the top of your viewer. Keys typed into text fields are left alone, and so is a key whose
+ * command can't run right now. A command that's turned off or not allowed still takes its key,
+ * and `onRefused` says why. The keys work anywhere on the page; with `target`, only while focus
+ * is inside that element, for a page with more than one viewer.
  */
 declare function useCommandShortcuts(options?: {
   isMac?: boolean;
+  target?: RefObject<HTMLElement | null>;
+  onRefused?: (commandId: CommandId, refusal: CommandRefusal) => void;
 }): void;
 //#endregion
-export { isMacPlatform, useCommand, useCommandShortcuts, useCommands };
+export { formatShortcut, standardCommands, useCommand, useCommandShortcuts, useCommands, useCommandsEvent, useCommandsSettings };
 //# sourceMappingURL=commands.d.cts.map

package/dist/commands.d.ts

@@ -1,20 +1,47 @@
-import { CommandsCapability, ResolvedCommand } from "@embedpdf/plugin-commands";
+import { t as SettingsHook } from "./state-0K1I5cM4.js";
+import { EventHook } from "@embedpdf/core";
+import { RefObject } from "react";
+import { BoundCommand, CommandId, CommandRefusal, CommandsCapability } from "@embedpdf/plugin-commands";
 export * from "@embedpdf/plugin-commands";
 //#region src/commands.d.ts
-/** The commands capability (register/execute/search/categories). */
+/**
+ * The commands every viewer has: zoom, pages, view rotation, `tool:<id>` for every tool, copy,
+ * delete, download and print, with shortcuts and labels in EmbedPDF's eight languages. Spread
+ * them into `commandsPlugin({ commands })`.
+ */
+declare const standardCommands: readonly (import("@embedpdf/plugin-commands").CommandDef | import("@embedpdf/plugin-commands").CommandFamily)[];
+/** The commands capability: `execute`, `searchCommands`, `registerCommand`, the categories, the settings calls. */
 declare function useCommands(): CommandsCapability;
-/** A command resolved against this subtree's document, reactively. */
-declare function useCommand(id: string): ResolvedCommand | null;
-/** Is this environment mac-like? Decides how 'Mod' resolves and displays. */
-declare const isMacPlatform: () => boolean;
+/** Subscribe to one commands event for the mounted lifetime: `useCommandsEvent((commands) => commands.onExecuted, handler)`. */
+declare function useCommandsEvent<T>(select: (commands: CommandsCapability) => EventHook<T>, handler: (event: T) => void): void;
+/**
+ * The commands settings (`commands`, `disabledCategories`, `disabledCommands`, `notAllowed`),
+ * with or without a document. Takes a selector.
+ */
+declare const useCommandsSettings: SettingsHook<import("@embedpdf/plugin-commands").CommandsSettings>;
+/** A shortcut as a tooltip shows it, for this platform: `'⌘K'` on a Mac, `'Ctrl+K'` elsewhere. */
+declare function formatShortcut(shortcut: string, options?: {
+  isMac?: boolean;
+}): string;
+/**
+ * A command for this component's document (the nearest <DocumentScope>, else the active one):
+ * its label, icon, state, `run` and `shortcut`. Re-renders when any of them changes. Always a
+ * command: an id no plugin registered is labelled with its id, neither visible nor enabled, and
+ * warns once in development.
+ */
+declare function useCommand(id: string): BoundCommand;
 /**
- * Bind every registered shortcut. One listener for the whole registry —
- * matching is pure (ui-core), execution goes through the one command path.
- * Strokes from editable elements are ignored.
+ * Turn every command's shortcut into a working key, for the active document. Call it once, near
+ * the top of your viewer. Keys typed into text fields are left alone, and so is a key whose
+ * command can't run right now. A command that's turned off or not allowed still takes its key,
+ * and `onRefused` says why. The keys work anywhere on the page; with `target`, only while focus
+ * is inside that element, for a page with more than one viewer.
  */
 declare function useCommandShortcuts(options?: {
   isMac?: boolean;
+  target?: RefObject<HTMLElement | null>;
+  onRefused?: (commandId: CommandId, refusal: CommandRefusal) => void;
 }): void;
 //#endregion
-export { isMacPlatform, useCommand, useCommandShortcuts, useCommands };
+export { formatShortcut, standardCommands, useCommand, useCommandShortcuts, useCommands, useCommandsEvent, useCommandsSettings };
 //# sourceMappingURL=commands.d.ts.map

package/dist/commands.js

@@ -1,48 +1,85 @@
-import "./rolldown-runtime-BBjsoOtd.js";
-import { useCapability, useDocumentId, useKernelValue } from "./runtime.js";
-import { useEffect } from "react";
-import { CommandsToken, resolvedCommandsEqual } from "@embedpdf/plugin-commands";
+import { O as devWarn, f as useCapability, h as useDocumentId, p as useCapabilityEvent, x as useKernelValue } from "./runtime-B6xcPsEb.js";
+import { t as settingsHook } from "./state-CbgxhwLA.js";
+import { bindCommandShortcuts, isMacPlatform, standardCommandsBrowser } from "@embedpdf/web";
+import { useEffect, useMemo, useRef } from "react";
+import { CommandsToken, boundCommandOf, resolvedCommandsEqual, unknownCommandWarning, unregisteredCommand } from "@embedpdf/plugin-commands";
+import { formatShortcut as formatShortcut$1 } from "@embedpdf/core-ui";
+import { CommandsToken as CommandsToken$1 } from "@embedpdf/plugin-commands/contract/host";
+import { createStandardCommands } from "@embedpdf/plugin-commands/standard";
 export * from "@embedpdf/plugin-commands";
 //#region src/commands.ts
-/** The commands capability (register/execute/search/categories). */
+/**
+* The commands every viewer has: zoom, pages, view rotation, `tool:<id>` for every tool, copy,
+* delete, download and print, with shortcuts and labels in EmbedPDF's eight languages. Spread
+* them into `commandsPlugin({ commands })`.
+*/
+const standardCommands = /* @__PURE__ */ createStandardCommands(standardCommandsBrowser);
+/** The commands capability: `execute`, `searchCommands`, `registerCommand`, the categories, the settings calls. */
 function useCommands() {
 	return useCapability(CommandsToken);
 }
-/** A command resolved against this subtree's document, reactively. */
+/** Subscribe to one commands event for the mounted lifetime: `useCommandsEvent((commands) => commands.onExecuted, handler)`. */
+function useCommandsEvent(select, handler) {
+	useCapabilityEvent(CommandsToken, select, handler);
+}
+/**
+* The commands settings (`commands`, `disabledCategories`, `disabledCommands`, `notAllowed`),
+* with or without a document. Takes a selector.
+*/
+const useCommandsSettings = settingsHook(CommandsToken);
+/** A shortcut as a tooltip shows it, for this platform: `'⌘K'` on a Mac, `'Ctrl+K'` elsewhere. */
+function formatShortcut(shortcut, options = {}) {
+	return formatShortcut$1(shortcut, { isMac: options.isMac ?? isMacPlatform() });
+}
+/**
+* A command for this component's document (the nearest <DocumentScope>, else the active one):
+* its label, icon, state, `run` and `shortcut`. Re-renders when any of them changes. Always a
+* command: an id no plugin registered is labelled with its id, neither visible nor enabled, and
+* warns once in development.
+*/
 function useCommand(id) {
 	const commands = useCapability(CommandsToken);
-	const documentId = useDocumentId();
-	return useKernelValue(() => commands.resolve(id, documentId ?? void 0), resolvedCommandsEqual);
+	const documentId = useDocumentId() ?? void 0;
+	const resolved = useKernelValue(() => commands.resolveCommand(id, documentId), resolvedCommandsEqual);
+	if (resolved === null) devWarn(`useCommand:${id}`, `useCommand(): ${unknownCommandWarning(id, commands.listCommandIds())}`);
+	return useMemo(() => boundCommandOf(resolved ?? unregisteredCommand(id), (commandId) => commands.execute(commandId, { documentId }), { isMac: isMacPlatform() }), [
+		resolved,
+		commands,
+		documentId,
+		id
+	]);
 }
-/** Is this environment mac-like? Decides how 'Mod' resolves and displays. */
-const isMacPlatform = () => typeof navigator !== "undefined" && /Mac|iP(hone|ad|od)/.test(navigator.platform);
-const isEditableTarget = (target) => {
-	const el = target;
-	if (!el || !el.tagName) return false;
-	return el.tagName === "INPUT" || el.tagName === "TEXTAREA" || el.isContentEditable;
-};
 /**
-* Bind every registered shortcut. One listener for the whole registry —
-* matching is pure (ui-core), execution goes through the one command path.
-* Strokes from editable elements are ignored.
+* Turn every command's shortcut into a working key, for the active document. Call it once, near
+* the top of your viewer. Keys typed into text fields are left alone, and so is a key whose
+* command can't run right now. A command that's turned off or not allowed still takes its key,
+* and `onRefused` says why. The keys work anywhere on the page; with `target`, only while focus
+* is inside that element, for a page with more than one viewer.
 */
 function useCommandShortcuts(options) {
-	const commands = useCapability(CommandsToken);
+	const commands = useCapability(CommandsToken$1);
 	const isMac = options?.isMac;
+	const target = options?.target;
+	const onRefused = useRef(options?.onRefused);
+	onRefused.current = options?.onRefused;
 	useEffect(() => {
-		const mac = isMac ?? isMacPlatform();
-		const onKeyDown = (event) => {
-			if (event.defaultPrevented || isEditableTarget(event.target)) return;
-			const id = commands.matchStroke(event, { isMac: mac });
-			if (!id) return;
-			event.preventDefault();
-			commands.execute(id);
-		};
-		window.addEventListener("keydown", onKeyDown);
-		return () => window.removeEventListener("keydown", onKeyDown);
-	}, [commands, isMac]);
+		const report = (commandId, refusal) => onRefused.current?.(commandId, refusal);
+		if (!target) return bindCommandShortcuts(commands, {
+			isMac,
+			onRefused: report
+		});
+		return target.current ? bindCommandShortcuts(commands, {
+			isMac,
+			target: target.current,
+			onRefused: report
+		}) : void 0;
+	}, [
+		commands,
+		isMac,
+		target
+	]);
 }
 //#endregion
-export { isMacPlatform, useCommand, useCommandShortcuts, useCommands };
+export { formatShortcut, standardCommands, useCommand, useCommandShortcuts, useCommands, useCommandsEvent, useCommandsSettings };
 
 //# sourceMappingURL=commands.js.map

package/dist/commands.js.map

@@ -1 +1 @@
-{"version":3,"file":"commands.js","names":[],"sources":["../src/commands.ts"],"sourcesContent":["/**\n * The React surface for @embedpdf/plugin-commands.\n *\n * Command state is a pure derivation over the store, so these hooks are thin:\n * `useCommand` re-resolves on the kernel's one change stream (cached by value\n * equality — locale flips, permission changes, and active-tool changes all\n * propagate with zero events), and `useCommandShortcuts` is the ~20 lines of\n * DOM that turn the registry's pure stroke matcher into a live keymap.\n */\n\n// One-line-per-feature: registration travels with the UI.\n// (resolvedCommandsEqual lives in the plugin now — it's pure value equality\n// over ResolvedCommand, framework-free — and arrives through this star.)\nexport * from '@embedpdf/plugin-commands';\nimport { useEffect } from 'react';\nimport { CommandsToken, resolvedCommandsEqual } from '@embedpdf/plugin-commands';\nimport type { CommandsCapability, ResolvedCommand } from '@embedpdf/plugin-commands';\nimport { useCapability, useDocumentId, useKernelValue } from './runtime';\n\n/** The commands capability (register/execute/search/categories). */\nexport function useCommands(): CommandsCapability {\n  return useCapability(CommandsToken);\n}\n\n/** A command resolved against this subtree's document, reactively. */\nexport function useCommand(id: string): ResolvedCommand | null {\n  const commands = useCapability(CommandsToken);\n  const documentId = useDocumentId();\n  return useKernelValue(() => commands.resolve(id, documentId ?? undefined), resolvedCommandsEqual);\n}\n\n/** Is this environment mac-like? Decides how 'Mod' resolves and displays. */\nexport const isMacPlatform = (): boolean =>\n  typeof navigator !== 'undefined' && /Mac|iP(hone|ad|od)/.test(navigator.platform);\n\nconst isEditableTarget = (target: EventTarget | null): boolean => {\n  const el = target as HTMLElement | null;\n  if (!el || !el.tagName) return false;\n  return el.tagName === 'INPUT' || el.tagName === 'TEXTAREA' || el.isContentEditable;\n};\n\n/**\n * Bind every registered shortcut. One listener for the whole registry —\n * matching is pure (ui-core), execution goes through the one command path.\n * Strokes from editable elements are ignored.\n */\nexport function useCommandShortcuts(options?: { isMac?: boolean }): void {\n  const commands = useCapability(CommandsToken);\n  const isMac = options?.isMac;\n  useEffect(() => {\n    const mac = isMac ?? isMacPlatform();\n    const onKeyDown = (event: KeyboardEvent) => {\n      if (event.defaultPrevented || isEditableTarget(event.target)) return;\n      const id = commands.matchStroke(event, { isMac: mac });\n      if (!id) return;\n      event.preventDefault();\n      commands.execute(id);\n    };\n    window.addEventListener('keydown', onKeyDown);\n    return () => window.removeEventListener('keydown', onKeyDown);\n  }, [commands, isMac]);\n}\n"],"mappings":";;;;;;;AAoBA,SAAgB,cAAkC;CAChD,OAAO,cAAc,aAAa;AACpC;;AAGA,SAAgB,WAAW,IAAoC;CAC7D,MAAM,WAAW,cAAc,aAAa;CAC5C,MAAM,aAAa,cAAc;CACjC,OAAO,qBAAqB,SAAS,QAAQ,IAAI,cAAc,KAAA,CAAS,GAAG,qBAAqB;AAClG;;AAGA,MAAa,sBACX,OAAO,cAAc,eAAe,qBAAqB,KAAK,UAAU,QAAQ;AAElF,MAAM,oBAAoB,WAAwC;CAChE,MAAM,KAAK;CACX,IAAI,CAAC,MAAM,CAAC,GAAG,SAAS,OAAO;CAC/B,OAAO,GAAG,YAAY,WAAW,GAAG,YAAY,cAAc,GAAG;AACnE;;;;;;AAOA,SAAgB,oBAAoB,SAAqC;CACvE,MAAM,WAAW,cAAc,aAAa;CAC5C,MAAM,QAAQ,SAAS;CACvB,gBAAgB;EACd,MAAM,MAAM,SAAS,cAAc;EACnC,MAAM,aAAa,UAAyB;GAC1C,IAAI,MAAM,oBAAoB,iBAAiB,MAAM,MAAM,GAAG;GAC9D,MAAM,KAAK,SAAS,YAAY,OAAO,EAAE,OAAO,IAAI,CAAC;GACrD,IAAI,CAAC,IAAI;GACT,MAAM,eAAe;GACrB,SAAS,QAAQ,EAAE;EACrB;EACA,OAAO,iBAAiB,WAAW,SAAS;EAC5C,aAAa,OAAO,oBAAoB,WAAW,SAAS;CAC9D,GAAG,CAAC,UAAU,KAAK,CAAC;AACtB"}
+{"version":3,"file":"commands.js","names":["formatKeys","CommandsHostToken"],"sources":["../src/commands.ts"],"sourcesContent":["/**\n * The React surface for @embedpdf/plugin-commands: the standard commands, a\n * command as a button needs it, the settings, and keyboard shortcuts. A\n * command's state is read from live state, so `useCommand` re-renders on the\n * kernel's one change stream, only when what the command shows changed.\n */\n\n// One-line-per-feature: registration travels with the UI.\nexport * from '@embedpdf/plugin-commands';\nimport { useEffect, useMemo, useRef, type RefObject } from 'react';\nimport { formatShortcut as formatKeys } from '@embedpdf/core-ui';\nimport {\n  CommandsToken,\n  boundCommandOf,\n  resolvedCommandsEqual,\n  unknownCommandWarning,\n  unregisteredCommand,\n} from '@embedpdf/plugin-commands';\nimport type {\n  BoundCommand,\n  CommandId,\n  CommandRefusal,\n  CommandsCapability,\n} from '@embedpdf/plugin-commands';\nimport { CommandsToken as CommandsHostToken } from '@embedpdf/plugin-commands/contract/host';\nimport { createStandardCommands } from '@embedpdf/plugin-commands/standard';\nimport type { EventHook } from '@embedpdf/core';\nimport { bindCommandShortcuts, isMacPlatform, standardCommandsBrowser } from '@embedpdf/web';\nimport { devWarn } from './dev';\nimport { useCapability, useCapabilityEvent, useDocumentId, useKernelValue } from './runtime';\nimport { settingsHook } from './state';\n\n/**\n * The commands every viewer has: zoom, pages, view rotation, `tool:<id>` for every tool, copy,\n * delete, download and print, with shortcuts and labels in EmbedPDF's eight languages. Spread\n * them into `commandsPlugin({ commands })`.\n */\nexport const standardCommands = /* @__PURE__ */ createStandardCommands(standardCommandsBrowser);\n\n/** The commands capability: `execute`, `searchCommands`, `registerCommand`, the categories, the settings calls. */\nexport function useCommands(): CommandsCapability {\n  return useCapability(CommandsToken);\n}\n\n/** Subscribe to one commands event for the mounted lifetime: `useCommandsEvent((commands) => commands.onExecuted, handler)`. */\nexport function useCommandsEvent<T>(\n  select: (commands: CommandsCapability) => EventHook<T>,\n  handler: (event: T) => void,\n): void {\n  useCapabilityEvent(CommandsToken, select, handler);\n}\n\n/**\n * The commands settings (`commands`, `disabledCategories`, `disabledCommands`, `notAllowed`),\n * with or without a document. Takes a selector.\n */\nexport const useCommandsSettings = settingsHook(CommandsToken);\n\n/** A shortcut as a tooltip shows it, for this platform: `'⌘K'` on a Mac, `'Ctrl+K'` elsewhere. */\nexport function formatShortcut(shortcut: string, options: { isMac?: boolean } = {}): string {\n  return formatKeys(shortcut, { isMac: options.isMac ?? isMacPlatform() });\n}\n\n/**\n * A command for this component's document (the nearest <DocumentScope>, else the active one):\n * its label, icon, state, `run` and `shortcut`. Re-renders when any of them changes. Always a\n * command: an id no plugin registered is labelled with its id, neither visible nor enabled, and\n * warns once in development.\n */\nexport function useCommand(id: string): BoundCommand {\n  const commands = useCapability(CommandsToken);\n  const documentId = useDocumentId() ?? undefined;\n  const resolved = useKernelValue(\n    () => commands.resolveCommand(id, documentId),\n    resolvedCommandsEqual,\n  );\n  if (resolved === null) {\n    devWarn(`useCommand:${id}`, `useCommand(): ${unknownCommandWarning(id, commands.listCommandIds())}`);\n  }\n  return useMemo(\n    () =>\n      boundCommandOf(\n        resolved ?? unregisteredCommand(id),\n        (commandId) => commands.execute(commandId, { documentId }),\n        { isMac: isMacPlatform() },\n      ),\n    [resolved, commands, documentId, id],\n  );\n}\n\n/**\n * Turn every command's shortcut into a working key, for the active document. Call it once, near\n * the top of your viewer. Keys typed into text fields are left alone, and so is a key whose\n * command can't run right now. A command that's turned off or not allowed still takes its key,\n * and `onRefused` says why. The keys work anywhere on the page; with `target`, only while focus\n * is inside that element, for a page with more than one viewer.\n */\nexport function useCommandShortcuts(options?: {\n  isMac?: boolean;\n  target?: RefObject<HTMLElement | null>;\n  onRefused?: (commandId: CommandId, refusal: CommandRefusal) => void;\n}): void {\n  const commands = useCapability(CommandsHostToken);\n  const isMac = options?.isMac;\n  const target = options?.target;\n  // The latest callback, so a new function each render doesn't bind the keys again.\n  const onRefused = useRef(options?.onRefused);\n  onRefused.current = options?.onRefused;\n  useEffect(() => {\n    const report = (commandId: CommandId, refusal: CommandRefusal) =>\n      onRefused.current?.(commandId, refusal);\n    if (!target) return bindCommandShortcuts(commands, { isMac, onRefused: report });\n    // The element mounts before this effect runs, so its ref is set by now.\n    return target.current\n      ? bindCommandShortcuts(commands, { isMac, target: target.current, onRefused: report })\n      : undefined;\n  }, [commands, isMac, target]);\n}\n"],"mappings":";;;;;;;;;;;;;;;AAqCA,MAAa,mBAAmC,uCAAuB,uBAAuB;;AAG9F,SAAgB,cAAkC;CAChD,OAAO,cAAc,aAAa;AACpC;;AAGA,SAAgB,iBACd,QACA,SACM;CACN,mBAAmB,eAAe,QAAQ,OAAO;AACnD;;;;;AAMA,MAAa,sBAAsB,aAAa,aAAa;;AAG7D,SAAgB,eAAe,UAAkB,UAA+B,CAAC,GAAW;CAC1F,OAAOA,iBAAW,UAAU,EAAE,OAAO,QAAQ,SAAS,cAAc,EAAE,CAAC;AACzE;;;;;;;AAQA,SAAgB,WAAW,IAA0B;CACnD,MAAM,WAAW,cAAc,aAAa;CAC5C,MAAM,aAAa,cAAc,KAAK,KAAA;CACtC,MAAM,WAAW,qBACT,SAAS,eAAe,IAAI,UAAU,GAC5C,qBACF;CACA,IAAI,aAAa,MACf,QAAQ,cAAc,MAAM,iBAAiB,sBAAsB,IAAI,SAAS,eAAe,CAAC,GAAG;CAErG,OAAO,cAEH,eACE,YAAY,oBAAoB,EAAE,IACjC,cAAc,SAAS,QAAQ,WAAW,EAAE,WAAW,CAAC,GACzD,EAAE,OAAO,cAAc,EAAE,CAC3B,GACF;EAAC;EAAU;EAAU;EAAY;CAAE,CACrC;AACF;;;;;;;;AASA,SAAgB,oBAAoB,SAI3B;CACP,MAAM,WAAW,cAAcC,eAAiB;CAChD,MAAM,QAAQ,SAAS;CACvB,MAAM,SAAS,SAAS;CAExB,MAAM,YAAY,OAAO,SAAS,SAAS;CAC3C,UAAU,UAAU,SAAS;CAC7B,gBAAgB;EACd,MAAM,UAAU,WAAsB,YACpC,UAAU,UAAU,WAAW,OAAO;EACxC,IAAI,CAAC,QAAQ,OAAO,qBAAqB,UAAU;GAAE;GAAO,WAAW;EAAO,CAAC;EAE/E,OAAO,OAAO,UACV,qBAAqB,UAAU;GAAE;GAAO,QAAQ,OAAO;GAAS,WAAW;EAAO,CAAC,IACnF,KAAA;CACN,GAAG;EAAC;EAAU;EAAO;CAAM,CAAC;AAC9B"}