@embedpdf/react 3.0.0-next.1 → 3.0.0-next.11

package/dist/AnnotationListSnapshot-C1U3XUxP-6kGwNoxy.d.ts

@@ -0,0 +1,546 @@
+//#region ../../engine/core/dist/AnnotationListSnapshot-C1U3XUxP.d.ts
+//#endregion
+//#region src/identity/PageObjectNumber.d.ts
+/**
+ * PDF indirect object number for a page.
+ *
+ * Resolved via the PDFium runtime helper `EPDFPage_GetObjectNumber(pagePtr)`.
+ * Always > 0 for well-formed PDFs. This replaces the v2 page index as the
+ * primary addressing key. The page index is kept on `PageHandle` as display
+ * metadata only, because it can shift when pages are inserted, deleted, or
+ * reordered while a session is open.
+ */
+type PageObjectNumber = number;
+//#endregion
+//#region src/dto/PdfDestination.d.ts
+/**
+ * An explicit PDF destination (ISO 32000-1 §12.3.2.2): a page, a location,
+ * and a magnification. Produced by outlines/bookmarks, link annotations,
+ * `/OpenAction`, and GoTo actions; named destinations resolve to one of
+ * these through the catalog's `/Dests` dictionary or name tree — the
+ * ENGINE does that resolution, so the viewer only ever sees this explicit
+ * form.
+ *
+ * Coordinates are PDF user space (y-up, points, absolute — NOT
+ * crop-relative). `null` means "retain the current value" (the spec's
+ * meaning for null array entries); a `/XYZ` zoom of `0` is equivalent to
+ * null. The `fitB*` kinds refer to the page's content BOUNDING box rather
+ * than the crop box.
+ *
+ * Viewers translate these onto the stage's reveal primitive — see
+ * `destinationToReveal` in `@embedpdf/plugin-stage`.
+ */
+type PdfDestination = {
+  kind: 'xyz';
+  pageObjectNumber: PageObjectNumber;
+  left?: number | null;
+  top?: number | null;
+  zoom?: number | null;
+} | {
+  kind: 'fit';
+  pageObjectNumber: PageObjectNumber;
+} | {
+  kind: 'fitH';
+  pageObjectNumber: PageObjectNumber;
+  top?: number | null;
+} | {
+  kind: 'fitV';
+  pageObjectNumber: PageObjectNumber;
+  left?: number | null;
+} | {
+  kind: 'fitR';
+  pageObjectNumber: PageObjectNumber;
+  left: number;
+  bottom: number;
+  right: number;
+  top: number;
+} | {
+  kind: 'fitB';
+  pageObjectNumber: PageObjectNumber;
+} | {
+  kind: 'fitBH';
+  pageObjectNumber: PageObjectNumber;
+  top?: number | null;
+} | {
+  kind: 'fitBV';
+  pageObjectNumber: PageObjectNumber;
+  left?: number | null;
+};
+/**
+ * One Hide `/T` or ResetForm `/Fields` entry. Deliberately UNSCOPED: a
+ * dictionary reference carries no page, so resolution (a name to widgets, an
+ * object number to an annotation or field) is the interpreter's job — never
+ * the extractor's.
+ */
+type PdfActionTargetRef = {
+  kind: 'name';
+  name: string;
+} | {
+  kind: 'objectNumber';
+  objectNumber: number;
+};
+/**
+ * Decoded SubmitForm `/Flags` word (ISO 32000-2:2020 Table 240) plus the raw
+ * value. `exclude` is DERIVED from bit 1 — never stored separately, so the
+ * two cannot disagree. Note the two easily-missed positions verified against
+ * the spec: bit 12 is `ExclFKey` (not "ExclFDFTemplate") and bit 13 is
+ * reserved/undefined, so `EmbedForm` is bit 14.
+ */
+interface SubmitFormFlags {
+  raw: number;
+  /** Bit 1: set → `fields` lists EXCLUDED fields. */
+  exclude: boolean;
+  /** Bit 2: submit designated valueless fields too, as name-only entries. */
+  includeNoValueFields: boolean;
+  /** Bits 3/6/9 folded into one verdict: bit 9 SubmitPDF dominates ("all
+   *  other flags shall be ignored except GetMethod"), else bit 6 XFDF, else
+   *  bit 3 HTML Form format, else FDF (the Table 240 default). */
+  format: 'fdf' | 'html' | 'xfdf' | 'pdf';
+  /** Bit 4. ISO makes GetMethod meaningful only with ExportFormat set, and
+   *  the bit-9 rule keeps it alive for SubmitPDF — so `'get'` only for
+   *  `'html'` and `'pdf'`; everything else posts. */
+  method: 'post' | 'get';
+  /** Bit 5 (meaningful only with ExportFormat; passed through — this stack
+   *  does not capture click coordinates). */
+  submitCoordinates: boolean;
+  /** Bit 7 (FDF only): include incremental updates via FDF `Differences`. */
+  includeAppendSaves: boolean;
+  /** Bit 8 (FDF only): include markup annotations. */
+  includeAnnotations: boolean;
+  /** Bit 10: convert date-like values to the standard date format. */
+  canonicalFormat: boolean;
+  /** Bit 11 (FDF, with IncludeAnnotations): only the current user's
+   *  annotations. */
+  exclNonUserAnnots: boolean;
+  /** Bit 12: the submitted FDF excludes its `F` entry. */
+  exclFKey: boolean;
+  /** Bit 14 (bit 13 is reserved): the FDF `F` entry embeds the source PDF. */
+  embedForm: boolean;
+}
+/**
+ * SubmitForm's extracted intent. ATOMIC on purpose: either every required
+ * component resolved (a complete, executable payload) or the node carries no
+ * payload at all — partial states are unrepresentable. An unreadable
+ * REQUIRED component (`/F`) degrades the whole node to `unknown` +
+ * `payload-dropped` at read time instead.
+ */
+interface SubmitFormPayload {
+  /** Resolved `/F` URL — a `<< /FS /URL >>` file specification (7.11.5,
+   *  `/UF` preferred over `/F` per 7.11.2); a bare string `/F` is accepted
+   *  as a producer-compat extension. */
+  url: string;
+  /**
+   * `null` = `/Fields` ABSENT → Include/Exclude is ignored and every field
+   * except NoExport-flagged ones is submitted (Table 239). `[]` =
+   * present-but-empty: include mode submits NOTHING, exclude mode submits
+   * everything eligible — presence and emptiness are different states.
+   */
+  fields: PdfActionTargetRef[] | null;
+  flags: SubmitFormFlags;
+  /** `/CharSet` (PDF 2.0), extracted but not encoded by this stack. */
+  charSet?: string;
+}
+interface PdfActionNodeCommon {
+  /** Raw `/S` name, retained for unknown and future action types. */
+  subtype: string;
+  /** Normalized `/Next` children in PDF order. */
+  next: PdfActionNode[];
+}
+/**
+ * One detached node in a normalized PDF action tree, discriminated on the
+ * interpreter that would execute it. Every executable arm carries its full
+ * payload — a `goto` without a destination or a `uri` without a URI is
+ * unrepresentable. A payload the reader cannot materialize degrades the node
+ * to `unknown` (original `/S` kept on `subtype`) and appends the tree-level
+ * `'payload-dropped'` warning.
+ */
+type PdfActionNode = PdfActionNodeCommon & ({
+  type: 'javascript';
+  script: string;
+} | {
+  type: 'goto';
+  destination: PdfDestination;
+} | {
+  type: 'uri';
+  uri: string;
+  isMap: boolean;
+} | {
+  type: 'named';
+  name: string;
+} | {
+  type: 'hide';
+  targets: PdfActionTargetRef[];
+  hide: boolean;
+} | {
+  type: 'reset-form';
+  /**
+   * `null` = `/Fields` ABSENT → reset every field (`exclude` is
+   * meaningless). `[]` = present-but-empty: with `exclude` false reset
+   * NOTHING, with `exclude` true reset EVERYTHING — PDFium's executor
+   * branches on presence first.
+   */
+  fields: PdfActionTargetRef[] | null;
+  exclude: boolean;
+} |
+/** Reported, never executed. */
+{
+  type: 'goto-remote';
+  filePath: string;
+} | {
+  type: 'goto-embedded';
+  filePath: string;
+} | {
+  type: 'launch';
+  filePath: string;
+} |
+/** ISO allows `/Rendition` to carry `/JS`; preserved, not collected. */
+{
+  type: 'rendition';
+  script?: string;
+} |
+/** Recognized; executable only when `payload` is present. Absent payload
+ *  = extracted by an older runtime (skew) — the node stays
+ *  recognized-inert exactly as before this payload existed. */
+{
+  type: 'submit-form';
+  payload?: SubmitFormPayload;
+} | {
+  type: 'thread';
+} | {
+  type: 'sound';
+} | {
+  type: 'movie';
+} | {
+  type: 'import-data';
+} | {
+  type: 'set-ocg-state';
+} | {
+  type: 'transition';
+} | {
+  type: 'goto-3d-view';
+} | {
+  type: 'unknown';
+});
+type PdfActionWarning = 'cycle-dropped' | 'malformed-next' | 'incomplete' |
+/** A node's payload could not be read; that node degraded to `unknown`. */
+'payload-dropped';
+/**
+ * One extracted action root plus the native reader's safety verdict.
+ * Consumers must never execute a tree whose `incomplete` flag is true.
+ */
+interface PdfActionTree {
+  /** Null when the model was valid but its root exceeded a safety bound. */
+  root: PdfActionNode | null;
+  incomplete: boolean;
+  /** Raw native bits, retained so newer warnings survive older SDKs.
+   *  TS-detected warnings (`payload-dropped`) appear only in `warnings`. */
+  warningFlags: number;
+  warnings: PdfActionWarning[];
+}
+interface PdfFieldActions {
+  keystroke?: PdfActionTree;
+  format?: PdfActionTree;
+  validate?: PdfActionTree;
+  calculate?: PdfActionTree;
+}
+//#endregion
+//#region src/identity/FormFieldRef.d.ts
+/**
+ * How callers address a logical form field.
+ *
+ * - `objectNumber` — the indirect object number of the field dictionary.
+ *   ISO 32000 guarantees every real AcroForm field dictionary is an
+ *   indirect object, and the layer runtime never renumbers (frozen base +
+ *   incremental deltas), so this is the durable identity for the lifetime
+ *   of a document. Preferred for all engine calls.
+ * - `fqn` — the fully qualified field name ("billing.name"). The portable,
+ *   semantic identity used by interchange formats (FDF/XFDF) and analytics;
+ *   survives document rewrites but is only as unique as the producer made
+ *   it. The engine resolves it against the reconciled field tree.
+ */
+type FormFieldRef = {
+  kind: 'objectNumber';
+  fieldObjectNumber: number;
+} | {
+  kind: 'fqn';
+  name: string;
+};
+/** A widget annotation of a field, as the forms subsystem sees it. */
+interface FormWidgetRef {
+  /**
+   * Indirect object number of the widget annotation — the join key to the
+   * annotation subsystem's `objectNumber` refs. `0` when the widget is
+   * stored as a direct object (spec-violating; cannot be addressed).
+   */
+  annotObjectNumber: number;
+  /**
+   * Object number of the page whose /Annots array references the widget.
+   * `0` when the widget is not reachable from any page ("unplaced").
+   */
+  pageObjectNumber: PageObjectNumber;
+}
+//#endregion
+//#region src/forms/value-entry.d.ts
+/** Lossless shape of a field's effective PDF `/V` or `/DV` object. */
+type FormValueEntry = {
+  kind: 'none';
+} | {
+  kind: 'scalar';
+  value: string;
+} | {
+  kind: 'array';
+  values: string[];
+} | {
+  kind: 'unsupported';
+};
+//#endregion
+//#region src/forms/field.d.ts
+/**
+ * The field family — the discriminant of {@link FormFieldDTO}. Narrowing on
+ * it reveals exactly the members that are meaningful for that family, the
+ * same way annotation DTOs narrow on `subtype`.
+ */
+type FormFieldFamily = 'text' | 'checkbox' | 'radio' | 'combobox' | 'listbox' | 'pushbutton' | 'signature' | 'unknown';
+/**
+ * Where the field was found.
+ *
+ * - `acroform` — reachable from the /AcroForm /Fields tree, as the spec
+ *   requires.
+ * - `recovered` — only reachable through a page's /Annots array (a common
+ *   producer bug). The engine reconciles these on every read so they work
+ *   like any other field, but other PDF processors will not see them until
+ *   {@link DocumentFormsService.repair} makes the fix durable.
+ */
+type FormFieldOrigin = 'acroform' | 'recovered';
+/**
+ * The /Ff flags every field family shares. Family-specific flags (comb,
+ * multi-select, radios-in-unison, ...) live as plain booleans on the
+ * family DTOs where they are always meaningful.
+ */
+interface FormFieldFlags {
+  /**
+   * The user must not change the value. The engine's write transactions
+   * still accept programmatic writes to read-only fields (calculated
+   * fields are read-only yet script-written); enforcing fill policy is
+   * the application's job.
+   */
+  readOnly: boolean;
+  required: boolean;
+  noExport: boolean;
+  /** The raw /Ff integer, for anything not surfaced. */
+  raw: number;
+}
+/**
+ * A widget of a toggle (checkbox/radio) field. Toggle widgets always carry
+ * their appearance-state machinery — no nullable fields to probe.
+ */
+interface ToggleFieldWidget extends FormWidgetRef {
+  /**
+   * The widget's appearance state name (the non-"Off" key of its /AP /N
+   * dictionary) — the token toggle writes address widgets by.
+   */
+  onState: string;
+  /**
+   * The widget's export value (/Opt entry when present, else the
+   * on-state). The identity FDF/XFDF carry.
+   */
+  exportValue: string;
+  /** Whether this widget is currently checked. */
+  checked: boolean;
+}
+/** One option of a choice (combo/list box) field. */
+interface FormFieldOption {
+  /** Display label shown to the user. */
+  label: string;
+  /** Export value used by /V, interchange, and `FormFieldValue.choice`. */
+  value: string;
+  /** Whether the option is currently selected. */
+  selected: boolean;
+}
+/**
+ * The trunk every field family shares: identity, provenance, universal
+ * flags, and widget placement. A logical field is the document-scoped
+ * record that holds the value; its widgets are page-scoped views — join
+ * them to the annotation subsystem via `annotObjectNumber`.
+ */
+interface FormFieldBase {
+  /** Durable ref (`objectNumber` whenever the field dictionary is indirect). */
+  ref: FormFieldRef;
+  /** Field dictionary object number; `0` for direct (spec-violating) dicts. */
+  fieldObjectNumber: number;
+  /** Fully qualified name, e.g. `"billing.name"`. */
+  name: string;
+  family: FormFieldFamily;
+  origin: FormFieldOrigin;
+  flags: FormFieldFlags;
+  /** /TU — the accessible tooltip / alternate name. */
+  alternateName: string | null;
+  /** /TM — the export mapping name. */
+  mappingName: string | null;
+  /** Exact effective `/V` object shape; family conveniences below are derived. */
+  valueEntry: FormValueEntry;
+  /** Exact effective `/DV` object shape, including absent and malformed values. */
+  defaultValueEntry: FormValueEntry;
+  /** Effective inherited field `/AA` actions. */
+  actions?: PdfFieldActions;
+  /** The field's widget annotations, in control order. May be empty ("unplaced"). */
+  widgets: FormWidgetRef[];
+}
+/** A text field. Write with `{ type: 'text', value }`. */
+interface TextFieldDTO extends FormFieldBase {
+  family: 'text';
+  value: string;
+  /** /DV — restored by `reset()`. */
+  defaultValue: string;
+  /** /MaxLen; `null` when unlimited. Longer writes are truncated to this length. */
+  maxLength: number | null;
+  multiline: boolean;
+  password: boolean;
+  /** Fixed character cells; meaningful with `maxLength`. */
+  comb: boolean;
+}
+/** A checkbox. Write with `{ type: 'toggle', state: onState | null }`. */
+interface CheckboxFieldDTO extends FormFieldBase {
+  family: 'checkbox';
+  checked: boolean;
+  /** The export value reported while checked ("Off" is never exported). */
+  exportValue: string;
+  widgets: ToggleFieldWidget[];
+}
+/** A radio group: ONE field, N widgets. Write with `{ type: 'toggle', state }`. */
+interface RadioFieldDTO extends FormFieldBase {
+  family: 'radio';
+  /** The checked widget's export value, or `"Off"` when the group is clear. */
+  value: string;
+  /** Widgets sharing an export value check together. */
+  radiosInUnison: boolean;
+  /** The group cannot be cleared once a choice is made. */
+  noToggleToOff: boolean;
+  widgets: ToggleFieldWidget[];
+}
+/** A combo box (dropdown). Write with `{ type: 'choice', values: [v] }`. */
+interface ComboBoxFieldDTO extends FormFieldBase {
+  family: 'combobox';
+  /** An option export value — or free text when `edit` is set. */
+  value: string;
+  /** /DV — restored by `reset()`. */
+  defaultValue: string;
+  /** Free text is allowed in addition to the options. */
+  edit: boolean;
+  options: FormFieldOption[];
+}
+/** A list box. Write with `{ type: 'choice', values }`. */
+interface ListBoxFieldDTO extends FormFieldBase {
+  family: 'listbox';
+  /** Selected option export values, in option order. */
+  selectedValues: string[];
+  /** Whether several options may be selected at once. */
+  multiSelect: boolean;
+  options: FormFieldOption[];
+}
+/** A push button: pure trigger, holds no value. Never written or exported. */
+interface PushButtonFieldDTO extends FormFieldBase {
+  family: 'pushbutton';
+}
+/**
+ * A signature field. Identity and placement only for now — the engine
+ * never writes signature values; signing is a future capability.
+ */
+interface SignatureFieldDTO extends FormFieldBase {
+  family: 'signature';
+}
+/**
+ * Forward-compat placeholder for field types the engine does not model,
+ * mirroring the `unsupported` annotation kind. Round-trips safely.
+ */
+interface UnknownFieldDTO extends FormFieldBase {
+  family: 'unknown';
+  /** The raw /V value as text, for diagnostics. */
+  rawValue: string;
+}
+/**
+ * A logical form field. Discriminated on `family`:
+ *
+ * ```ts
+ * if (field.family === 'listbox') {
+ *   field.selectedValues; // string[]
+ * }
+ * ```
+ */
+type FormFieldDTO = TextFieldDTO | CheckboxFieldDTO | RadioFieldDTO | ComboBoxFieldDTO | ListBoxFieldDTO | PushButtonFieldDTO | SignatureFieldDTO | UnknownFieldDTO;
+//#endregion
+//#region src/forms/snapshot.d.ts
+/**
+ * What kind of interactive form the document declares.
+ *
+ * - `none` — no /AcroForm dictionary. Recovered fields may still exist
+ *   (see {@link FormFieldOrigin}); `repair()` can bootstrap the dictionary.
+ * - `acroform` — a standard AcroForm.
+ * - `xfa` — the /AcroForm carries an /XFA entry. The engine serves the
+ *   AcroForm shell read-only and never executes XFA.
+ */
+type FormKind = 'none' | 'acroform' | 'xfa';
+/**
+ * The document's complete form state at one instant: the reconciled field
+ * tree flattened to terminal fields with fully qualified names.
+ *
+ * Snapshots are detached and immutable — any mutation (a value write, an
+ * annotation edit, a page operation) makes previously returned snapshots
+ * stale. Re-read after mutating; the engine caches the underlying model
+ * per document version, so repeated reads between mutations are cheap.
+ */
+interface FormSnapshot {
+  formKind: FormKind;
+  /**
+   * Whether the /AcroForm sets /NeedAppearances (viewer-generated widget
+   * appearances). The engine bakes appearances on every write regardless;
+   * `repair({ bakeAppearances: true })` can clear the flag document-wide.
+   */
+  needsAppearances: boolean;
+  fields: FormFieldDTO[];
+  /** `/AcroForm /CO` order; null preserves each malformed/unresolved slot. */
+  calculationOrder: Array<FormFieldRef | null>;
+}
+//#endregion
+//#region src/search/types.d.ts
+/**
+ * What to search for — THE one shape, engine → wire → plugin state →
+ * search box. One flat object; the flags define behavior per mode instead
+ * of the mode changing the shape:
+ *
+ * | flag              | literal          | regex                          |
+ * |-------------------|------------------|--------------------------------|
+ * | `matchCase`       | fold case        | `i` flag                       |
+ * | `wholeWord`       | boundary check   | pattern is `\b(?:…)\b`-wrapped |
+ * | `matchDiacritics` | mark fold        | REJECTED (`InvalidArg`)        |
+ *
+ * Literal queries match over FOLDED text; regex queries run the portable
+ * dialect against the RAW page text — which is why `matchDiacritics`
+ * cannot apply to them (diacritic folding is a property of the folded
+ * text plane). Validate with `validateSearchQuery` for early UI feedback;
+ * engines re-validate and reject with `EngineErrorCode.InvalidArg`.
+ */
+interface SearchQuery {
+  /**
+   * The literal text — or, when `regex`, a pattern in the portable
+   * search-regex dialect: JavaScript `u`-mode syntax MINUS backreferences
+   * and lookaround, so every valid pattern also runs on RE2 (the
+   * server-side engine).
+   */
+  text: string;
+  /** Interpret `text` as a regex pattern. Default false (literal). */
+  regex?: boolean;
+  /** Exact-case matching. Default false (case-folded / `i` semantics). */
+  matchCase?: boolean;
+  /** Only match at word boundaries (letters/digits end the word). */
+  wholeWord?: boolean;
+  /**
+   * Treat diacritics as significant ("café" ≠ "cafe"). Default false —
+   * marks are stripped on both sides, which is what viewers ship.
+   * LITERAL ONLY: combined with `regex` the query is rejected.
+   */
+  matchDiacritics?: boolean;
+}
+//#endregion
+export { SearchQuery as n, FormSnapshot as t };
+//# sourceMappingURL=AnnotationListSnapshot-C1U3XUxP-6kGwNoxy.d.ts.map

package/dist/actions.cjs

@@ -0,0 +1,42 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_runtime = require("./runtime.cjs");
+let react = require("react");
+let _embedpdf_web = require("@embedpdf/web");
+let _embedpdf_plugin_stage_contract = require("@embedpdf/plugin-stage/contract");
+let _embedpdf_plugin_actions = require("@embedpdf/plugin-actions");
+//#region src/actions.tsx
+/**
+* Install the UI adapter for the active document's action dispatcher. The
+* DEFAULT policy — the origin×phase visibility matrix, sanitizeExternalUri
+* URI opens, browser print/alert fallbacks — is `@embedpdf/web`'s
+* `createDefaultActionsUiAdapter`, written ONCE for every binding; this
+* hook is React glue only (late-bound handlers, stage navigation,
+* identity-safe install/uninstall). The doc.print AUTHORITY gate is
+* upstream (the actions plugin) and not overridable.
+*/
+function useActionsUiAdapter(handlers) {
+	const actions = require_runtime.useOptionalCapability(_embedpdf_plugin_actions.ActionsToken);
+	const stage = require_runtime.useOptionalCapability(_embedpdf_plugin_stage_contract.StageToken);
+	const handlersRef = (0, react.useRef)(handlers);
+	handlersRef.current = handlers;
+	(0, react.useEffect)(() => {
+		if (!actions) return;
+		const adapter = (0, _embedpdf_web.createDefaultActionsUiAdapter)({
+			overrides: () => handlersRef.current,
+			goToPage: (page) => stage?.goToPage(page)
+		});
+		return actions.setUiAdapter(adapter);
+	}, [actions, stage]);
+}
+//#endregion
+exports.useActionsUiAdapter = useActionsUiAdapter;
+Object.keys(_embedpdf_plugin_actions).forEach(function(k) {
+	if (k !== "default" && !Object.prototype.hasOwnProperty.call(exports, k)) Object.defineProperty(exports, k, {
+		enumerable: true,
+		get: function() {
+			return _embedpdf_plugin_actions[k];
+		}
+	});
+});
+
+//# sourceMappingURL=actions.cjs.map

package/dist/actions.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"actions.cjs","names":["useOptionalCapability","ActionsToken","StageToken"],"sources":["../src/actions.tsx"],"sourcesContent":["/**\n * The React view of @embedpdf/plugin-actions — the action engine's UI port.\n *\n * The plugin is DOM-free; opening tabs and printing are this layer's job.\n * `useActionsUiAdapter()` installs the browser-default adapter (the same\n * sanitizer + window.open the link layer uses; print = the browser dialog),\n * overridable per handler. Without it, `adapter`-routed actions (URI, Print)\n * report `no-adapter` diagnostics instead of executing.\n */\n\n// One-line-per-feature: registration travels with the UI.\nexport * from '@embedpdf/plugin-actions';\nimport { useEffect, useRef } from 'react';\nimport { ActionsToken, type ActionUiAdapter } from '@embedpdf/plugin-actions';\nimport { StageToken } from '@embedpdf/plugin-stage/contract';\nimport { createDefaultActionsUiAdapter } from '@embedpdf/web';\n\nimport { useOptionalCapability } from './runtime';\n\n/** Override any subset of the default adapter policy. */\nexport type ActionsUiHandlers = Partial<ActionUiAdapter>;\n\n/**\n * Install the UI adapter for the active document's action dispatcher. The\n * DEFAULT policy — the origin×phase visibility matrix, sanitizeExternalUri\n * URI opens, browser print/alert fallbacks — is `@embedpdf/web`'s\n * `createDefaultActionsUiAdapter`, written ONCE for every binding; this\n * hook is React glue only (late-bound handlers, stage navigation,\n * identity-safe install/uninstall). The doc.print AUTHORITY gate is\n * upstream (the actions plugin) and not overridable.\n */\nexport function useActionsUiAdapter(handlers?: ActionsUiHandlers): void {\n  const actions = useOptionalCapability(ActionsToken);\n  const stage = useOptionalCapability(StageToken);\n  const handlersRef = useRef(handlers);\n  handlersRef.current = handlers;\n\n  useEffect(() => {\n    if (!actions) return;\n    const adapter: ActionUiAdapter = createDefaultActionsUiAdapter({\n      overrides: () => handlersRef.current,\n      goToPage: (page) => stage?.goToPage(page),\n    });\n    return actions.setUiAdapter(adapter);\n  }, [actions, stage]);\n}\n"],"mappings":";;;;;;;;;;;;;;;;AA+BA,SAAgB,oBAAoB,UAAoC;CACtE,MAAM,UAAUA,gBAAAA,sBAAsBC,yBAAAA,YAAY;CAClD,MAAM,QAAQD,gBAAAA,sBAAsBE,gCAAAA,UAAU;CAC9C,MAAM,eAAA,GAAA,MAAA,OAAA,CAAqB,QAAQ;CACnC,YAAY,UAAU;CAEtB,CAAA,GAAA,MAAA,UAAA,OAAgB;EACd,IAAI,CAAC,SAAS;EACd,MAAM,WAAA,GAAA,cAAA,8BAAA,CAAyD;GAC7D,iBAAiB,YAAY;GAC7B,WAAW,SAAS,OAAO,SAAS,IAAI;EAC1C,CAAC;EACD,OAAO,QAAQ,aAAa,OAAO;CACrC,GAAG,CAAC,SAAS,KAAK,CAAC;AACrB"}

package/dist/actions.d.cts

@@ -0,0 +1,18 @@
+import { ActionUiAdapter } from "@embedpdf/plugin-actions";
+export * from "@embedpdf/plugin-actions";
+//#region src/actions.d.ts
+/** Override any subset of the default adapter policy. */
+type ActionsUiHandlers = Partial<ActionUiAdapter>;
+/**
+ * Install the UI adapter for the active document's action dispatcher. The
+ * DEFAULT policy — the origin×phase visibility matrix, sanitizeExternalUri
+ * URI opens, browser print/alert fallbacks — is `@embedpdf/web`'s
+ * `createDefaultActionsUiAdapter`, written ONCE for every binding; this
+ * hook is React glue only (late-bound handlers, stage navigation,
+ * identity-safe install/uninstall). The doc.print AUTHORITY gate is
+ * upstream (the actions plugin) and not overridable.
+ */
+declare function useActionsUiAdapter(handlers?: ActionsUiHandlers): void;
+//#endregion
+export { ActionsUiHandlers, useActionsUiAdapter };
+//# sourceMappingURL=actions.d.cts.map

package/dist/actions.d.ts

@@ -0,0 +1,18 @@
+import { ActionUiAdapter } from "@embedpdf/plugin-actions";
+export * from "@embedpdf/plugin-actions";
+//#region src/actions.d.ts
+/** Override any subset of the default adapter policy. */
+type ActionsUiHandlers = Partial<ActionUiAdapter>;
+/**
+ * Install the UI adapter for the active document's action dispatcher. The
+ * DEFAULT policy — the origin×phase visibility matrix, sanitizeExternalUri
+ * URI opens, browser print/alert fallbacks — is `@embedpdf/web`'s
+ * `createDefaultActionsUiAdapter`, written ONCE for every binding; this
+ * hook is React glue only (late-bound handlers, stage navigation,
+ * identity-safe install/uninstall). The doc.print AUTHORITY gate is
+ * upstream (the actions plugin) and not overridable.
+ */
+declare function useActionsUiAdapter(handlers?: ActionsUiHandlers): void;
+//#endregion
+export { ActionsUiHandlers, useActionsUiAdapter };
+//# sourceMappingURL=actions.d.ts.map

package/dist/actions.js

@@ -0,0 +1,34 @@
+import { useOptionalCapability } from "./runtime.js";
+import { useEffect, useRef } from "react";
+import { createDefaultActionsUiAdapter } from "@embedpdf/web";
+import { StageToken } from "@embedpdf/plugin-stage/contract";
+import { ActionsToken } from "@embedpdf/plugin-actions";
+export * from "@embedpdf/plugin-actions";
+//#region src/actions.tsx
+/**
+* Install the UI adapter for the active document's action dispatcher. The
+* DEFAULT policy — the origin×phase visibility matrix, sanitizeExternalUri
+* URI opens, browser print/alert fallbacks — is `@embedpdf/web`'s
+* `createDefaultActionsUiAdapter`, written ONCE for every binding; this
+* hook is React glue only (late-bound handlers, stage navigation,
+* identity-safe install/uninstall). The doc.print AUTHORITY gate is
+* upstream (the actions plugin) and not overridable.
+*/
+function useActionsUiAdapter(handlers) {
+	const actions = useOptionalCapability(ActionsToken);
+	const stage = useOptionalCapability(StageToken);
+	const handlersRef = useRef(handlers);
+	handlersRef.current = handlers;
+	useEffect(() => {
+		if (!actions) return;
+		const adapter = createDefaultActionsUiAdapter({
+			overrides: () => handlersRef.current,
+			goToPage: (page) => stage?.goToPage(page)
+		});
+		return actions.setUiAdapter(adapter);
+	}, [actions, stage]);
+}
+//#endregion
+export { useActionsUiAdapter };
+
+//# sourceMappingURL=actions.js.map

package/dist/actions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"actions.js","names":[],"sources":["../src/actions.tsx"],"sourcesContent":["/**\n * The React view of @embedpdf/plugin-actions — the action engine's UI port.\n *\n * The plugin is DOM-free; opening tabs and printing are this layer's job.\n * `useActionsUiAdapter()` installs the browser-default adapter (the same\n * sanitizer + window.open the link layer uses; print = the browser dialog),\n * overridable per handler. Without it, `adapter`-routed actions (URI, Print)\n * report `no-adapter` diagnostics instead of executing.\n */\n\n// One-line-per-feature: registration travels with the UI.\nexport * from '@embedpdf/plugin-actions';\nimport { useEffect, useRef } from 'react';\nimport { ActionsToken, type ActionUiAdapter } from '@embedpdf/plugin-actions';\nimport { StageToken } from '@embedpdf/plugin-stage/contract';\nimport { createDefaultActionsUiAdapter } from '@embedpdf/web';\n\nimport { useOptionalCapability } from './runtime';\n\n/** Override any subset of the default adapter policy. */\nexport type ActionsUiHandlers = Partial<ActionUiAdapter>;\n\n/**\n * Install the UI adapter for the active document's action dispatcher. The\n * DEFAULT policy — the origin×phase visibility matrix, sanitizeExternalUri\n * URI opens, browser print/alert fallbacks — is `@embedpdf/web`'s\n * `createDefaultActionsUiAdapter`, written ONCE for every binding; this\n * hook is React glue only (late-bound handlers, stage navigation,\n * identity-safe install/uninstall). The doc.print AUTHORITY gate is\n * upstream (the actions plugin) and not overridable.\n */\nexport function useActionsUiAdapter(handlers?: ActionsUiHandlers): void {\n  const actions = useOptionalCapability(ActionsToken);\n  const stage = useOptionalCapability(StageToken);\n  const handlersRef = useRef(handlers);\n  handlersRef.current = handlers;\n\n  useEffect(() => {\n    if (!actions) return;\n    const adapter: ActionUiAdapter = createDefaultActionsUiAdapter({\n      overrides: () => handlersRef.current,\n      goToPage: (page) => stage?.goToPage(page),\n    });\n    return actions.setUiAdapter(adapter);\n  }, [actions, stage]);\n}\n"],"mappings":";;;;;;;;;;;;;;;;AA+BA,SAAgB,oBAAoB,UAAoC;CACtE,MAAM,UAAU,sBAAsB,YAAY;CAClD,MAAM,QAAQ,sBAAsB,UAAU;CAC9C,MAAM,cAAc,OAAO,QAAQ;CACnC,YAAY,UAAU;CAEtB,gBAAgB;EACd,IAAI,CAAC,SAAS;EACd,MAAM,UAA2B,8BAA8B;GAC7D,iBAAiB,YAAY;GAC7B,WAAW,SAAS,OAAO,SAAS,IAAI;EAC1C,CAAC;EACD,OAAO,QAAQ,aAAa,OAAO;CACrC,GAAG,CAAC,SAAS,KAAK,CAAC;AACrB"}