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

package/dist/form-Bdjk0Z3T.d.cts

@@ -1,537 +0,0 @@
-import { o as AnnotationRenderer } from "./annotation-BCED_p9H.cjs";
-import { FormFieldDTO } from "@embedpdf/plugin-form";
-//#region ../../engine/core/dist/AnnotationListSnapshot-D9R5n2Kf.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$1 = 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$1[];
-  /** `/AcroForm /CO` order; null preserves each malformed/unresolved slot. */
-  calculationOrder: Array<FormFieldRef | null>;
-}
-//#endregion
-//#region src/form.d.ts
-/**
- * The form plugin's renderer entry, ready for
- * `<AnnotationLayer renderers={[formWidgetRenderer]} />`. It answers for the
- * PLUGIN-registered 'form-widgets' Behavior — the form plugin decides when
- * widgets are fill controls vs. editable annotations, never the app.
- */
-declare const formWidgetRenderer: AnnotationRenderer;
-/**
- * Fill-mode form controls for one page, positioned from the form model's own
- * widget geometry — the ANNOTATION-LESS path (a fill-only viewer whose page
- * pixels come from an annotated RenderLayer raster). Active whenever the
- * active tool carries the 'form-fill' tag (the built-in pointer/pan tools
- * do); any other tool stands the controls down. Do not mount next to an
- * AnnotationLayer wired with `formWidgetBehaviors`.
- */
-declare function FormLayer(): import("react/jsx-runtime").JSX.Element | null;
-/** The form capability — values, interchange, design-mode verbs. */
-declare function useForm(): import("@embedpdf/plugin-form").FormCapability;
-/** The reconciled form snapshot (null until the first load lands),
- *  re-rendering on every form model change. */
-declare function useFormSnapshot(): FormSnapshot | null;
-/**
- * The FIELD behind the currently selected widget annotation (single
- * selection), or null. The design-mode join: widget selection lives in the
- * annotation plane, field properties live here.
- */
-declare function useFormField(): FormFieldDTO | null;
-//#endregion
-export { useFormSnapshot as a, useFormField as i, formWidgetRenderer as n, useForm as r, FormLayer as t };
-//# sourceMappingURL=form-Bdjk0Z3T.d.cts.map