@embedpdf/plugin-interaction 3.0.0-next.14 → 3.0.0-next.15

package/dist/contract-F3gsFtSf.d.ts

@@ -1,239 +0,0 @@
-import { PageObjectNumber } from "@embedpdf/core";
-import { PageRotation, Point } from "@embedpdf/core-geometry";
-//#region src/types.d.ts
-type ToolId = string;
-type Cursor = string;
-interface Modifiers {
-  shift: boolean;
-  alt: boolean;
-  ctrl: boolean;
-  meta: boolean;
-}
-/**
- * The single active arbiter of what the pointer does. `pan` and `pointer` are
- * built in; features add more (`highlight`, `square`, `redact`…) via
- * `registerTool`. A tool carries no behaviour itself — it turns on capability
- * TAGS that handlers opt into (`enables`), so tools compose features without
- * coupling to them.
- */
-interface Tool {
-  id: ToolId;
-  cursor: Cursor;
-  /**
-   * Cursor over the viewport's page GAPS. A tool's cursor answers "what would
-   * a click do here" — and most tools act only on pages, so gaps fall back to
-   * the neutral arrow (`'default'`). A tool that works anywhere (pan) declares
-   * its own (`'grab'`). Hover claims still outrank both.
-   */
-  gapCursor?: Cursor;
-  enables: ReadonlySet<string>;
-  /**
-   * TOUCH CONSENT, rung 1 — "arming this tool is consent to create with a
-   * finger": while it is active, single-finger touch routes to the hub
-   * wholesale (draw/markup/redact tools), and navigation moves to two
-   * fingers — the drawing-app convention. Default false: a finger navigates
-   * first, and only per-point claims ({@link InteractionHandler.claimsTouch})
-   * carve out tool gestures.
-   */
-  touchDirect?: boolean;
-}
-type Phase = 'down' | 'move' | 'up' | 'cancel';
-/** The physical device class behind a sample — `PointerEvent.pointerType`.
- *  Adapters fill it so handlers (and arbitration above the hub) can apply
- *  modality policy: touch navigates first, pen/mouse are tool-first. */
-type PointerKind = 'mouse' | 'pen' | 'touch';
-/**
- * One normalized pointer event. `viewport` is the source container's px (the pan
- * handler uses the delta). `page` is the resolved page hit — its `pon` + content
- * point (y-down, PDF units, via the page's transform) — present when the pointer
- * is over a page, absent over gaps. A viewport source (Stage) resolves `page` per
- * event (so a drag can cross pages); a per-page source (PageView) always sets it.
- */
-interface PointerSample {
-  phase: Phase;
-  viewport: Point;
-  /** `scale` is the hit page's VIEW px per content unit — handlers use it to
-   *  convert screen-px chrome settings into content-space tolerances, so grab
-   *  zones stay screen-constant across zoom. `rotation` is the hit page's TOTAL
-   *  display rotation (document /Rotate + view rotation) — per-event
-   *  environmental context like `scale`, for placement rules that depend on how
-   *  the page is DISPLAYED (an upright stamp). `zoom` is the page's zoom
-   *  RELATIVE to its 100% baseline (`transform.zoom` — dimensionless, 1 =
-   *  Acrobat's 100%), for zoom-relative policies (the `/F` NoZoom exemption);
-   *  distinct from `scale`, which is a units conversion. Absent when the
-   *  source can't say. */
-  page?: {
-    pon: PageObjectNumber;
-    point: Point;
-    scale?: number;
-    rotation?: PageRotation;
-    zoom?: number;
-  };
-  modifiers: Modifiers;
-  /**
-   * Click count for a `down` (1 = single, 2 = double, 3 = triple), from the
-   * browser's native multi-click detection (`MouseEvent.detail`). Lets handlers
-   * do word/line selection without re-implementing timing. Defaults to 1.
-   */
-  clickCount?: number;
-  /** The device class that produced this sample (see {@link PointerKind}).
-   *  Absent when the source can't say — treat as 'mouse'. */
-  pointerType?: PointerKind;
-  /**
-   * Present when the sample was SYNTHESIZED from a recognized gesture rather
-   * than a raw press. 'long-press': a touch contact held still — the gesture
-   * controller forwards it as a down (with `clickCount: 2`, so word-selection
-   * keeps working unchanged), and this marker is the honest signal for
-   * handlers that must tell a long-press from a genuine double-click
-   * (haptics, pickup affordances). Absent on every raw pointer sample.
-   */
-  gesture?: 'long-press';
-  /**
-   * The LENS this sample came from — the stage plugin id the emitting surface
-   * binding was attached to (a document may be viewed through several stage
-   * lenses at once). Handlers registered with a matching `source` scope only
-   * see their own lens's input, so one lens's drag can never be captured by
-   * another lens's handler. Absent when the source doesn't say (custom
-   * dispatchers, single-lens embeds) — such samples route to every handler.
-   */
-  source?: string;
-  /**
-   * Project this event onto a SPECIFIC page's content space, unclamped — valid
-   * (and expected) outside the page's bounds. `page` answers "what is under the
-   * cursor" and re-resolves per event; `project` answers "where is the cursor
-   * in MY page's frame" for a gesture anchored to the page it started on (an
-   * annotation drag sliding along the page edge). Null when the source can't
-   * project onto that page (not laid out / a per-page source's foreign page).
-   */
-  project?(pon: PageObjectNumber): Point | null;
-}
-/**
- * A pointer handler contributed by a feature plugin. The ONE registration
- * mechanism (replacing v2's registerMode / registerHandlers / registerAlways /
- * enableForMode quartet): a handler declares which tools it's live under and a
- * priority; the hub routes each gesture to the first handler that captures it.
- */
-interface InteractionHandler {
-  id: string;
-  /** Higher wins the gesture. */
-  priority: number;
-  /** Usually `tool.enables.has('my-tag')`. */
-  enabledFor(tool: Tool): boolean;
-  /** Return true to CAPTURE: subsequent move/up route here until pointer-up. */
-  onDown(sample: PointerSample): boolean;
-  onMove?(sample: PointerSample): void;
-  onUp?(sample: PointerSample): void;
-  /**
-   * The gesture was ABORTED, not completed — the pointer was cancelled by the
-   * system, or navigation took it over (a second finger converted the drag
-   * into a pinch). Discard the in-flight work instead of committing it (a
-   * half-drawn shape, a mid-drag selection). Falls back to {@link onUp} when
-   * absent, since committing is the lesser evil to a stuck gesture.
-   */
-  onCancel?(sample: PointerSample): void;
-  /** Pointer moved with no active gesture — cursor feedback only. */
-  onHover?(sample: PointerSample): void;
-  /**
-   * TOUCH CONSENT, rung 2 — "the selected thing owns its drags". Touch
-   * navigation asks this BEFORE a contact is classified: return true and the
-   * whole contact routes to the hub as a tool gesture (down/move/up) instead
-   * of pan/pinch/tap. Implement it ONLY where the user has already narrowed
-   * intent to this point — the annotation handler claims the selected
-   * annotation's body and its handles, nothing else. A pure read: it must
-   * not mutate anything (the down that follows does the mutating). Handlers
-   * without it never claim, so plain surfaces keep navigating.
-   */
-  claimsTouch?(sample: PointerSample): boolean;
-}
-/**
- * A tool's runtime cursor skin: "while THIS tool is armed, keyword X looks
- * like Y." Everything cursor-shaped in the hub speaks KEYWORDS — a tool
- * declares its base ('crosshair', 'copy'), hover claims name what is under
- * the pointer ('text' over text, 'move' over an annotation) — and the skin
- * restyles those keywords, typically as image cursors carrying the tool's
- * icon. Applied uniformly to the winning claim and to the declared base, so
- * same keyword = same meaning = same look. Unmapped keywords render as-is (a
- * foreign 'move' over an annotation drops the tool identity), and page gaps
- * are never skinned — the identity appears exactly where the action is
- * possible, and the skin can only restyle where the tool already acts.
- */
-type ToolCursorSkin = Record<Cursor, Cursor>;
-interface InteractionState {
-  activeToolId: ToolId;
-  cursor: Cursor;
-}
-type InteractionAction = {
-  type: 'SET_TOOL';
-  toolId: ToolId;
-} | {
-  type: 'SET_CURSOR';
-  cursor: Cursor;
-};
-interface InteractionCapability {
-  activeTool(): Tool;
-  activeToolId(): ToolId;
-  cursor(): Cursor;
-  tools(): Tool[];
-  activateTool(id: ToolId): void;
-  /** Fires after the active tool changes — lets a feature react (e.g. a markup
-   *  tool taking over the selection visual). Returns an unsubscribe fn. */
-  onToolChange(cb: () => void): () => void;
-  /**
-   * Reskin a tool's cursor keywords at runtime — how an app gives the armed
-   * tool an image cursor built from its own toolbar icon (`Cursor` is any CSS
-   * cursor string, `url(data:…) x y, crosshair` included). See
-   * {@link ToolCursorSkin} for what the map means. `null` removes the skin.
-   */
-  setToolCursor(id: ToolId, skin: ToolCursorSkin | null): void;
-  registerTool(tool: Tool): () => void;
-  /**
-   * Register a pointer handler. `source` scopes it to ONE lens: the handler
-   * then only sees samples stamped with that source (see
-   * {@link PointerSample.source}) — mandatory for per-lens handlers like the
-   * stage's pan-scroll, or two stages on one document would capture each
-   * other's drags. UNSTAMPED samples still route everywhere (only a definite
-   * mismatch filters), so custom dispatchers keep working.
-   */
-  registerHandler(handler: InteractionHandler, options?: {
-    source?: string;
-  }): () => void;
-  setCursor(token: string, cursor: Cursor | null, priority?: number): void;
-  dispatch(sample: PointerSample): void;
-  /**
-   * The touch-arbitration pre-flight: would any eligible handler claim a
-   * contact at this sample ({@link InteractionHandler.claimsTouch})? Walked
-   * in the same priority order `dispatch` uses, first claim wins. Pure —
-   * nothing is captured or mutated; the gesture controller calls it at
-   * touch-down to route the contact (tool vs navigation), then dispatches
-   * normally.
-   */
-  wouldClaimTouch(sample: PointerSample): boolean;
-}
-declare const InteractionToken: import("@embedpdf/core").CapabilityToken<InteractionCapability>;
-/**
- * Resolve a sample against a gesture's HOME page. Page-anchored gestures track
- * the page they started on even when the cursor wanders off it — `s.page`
- * re-resolves per event (a foreign page is a DIFFERENT coordinate frame), so
- * prefer the source's unclamped projection and fall back to the page hit only
- * when it is the same page. Null → this sample can't speak for the home page.
- * Shared by every gesture owner (annotation edit/draw, form placement).
- */
-declare const samplePointOn: (s: PointerSample, pon: PageObjectNumber) => Point | null;
-interface InteractionConfig {
-  /** Tool active when a document opens. Default `'pointer'`. */
-  defaultTool?: ToolId;
-}
-//#endregion
-//#region src/feedback.types.d.ts
-interface PlatformFeedback {
-  selection(): void;
-  impact(weight?: 'light' | 'medium' | 'heavy'): void;
-  notify(kind: 'success' | 'warning' | 'error'): void;
-}
-declare const FeedbackToken: import("@embedpdf/core").CapabilityToken<PlatformFeedback>;
-interface FeedbackPluginOptions {
-  provider?: PlatformFeedback;
-}
-//#endregion
-export { samplePointOn as _, InteractionAction as a, InteractionHandler as c, Modifiers as d, Phase as f, ToolId as g, Tool as h, Cursor as i, InteractionState as l, PointerSample as m, FeedbackToken as n, InteractionCapability as o, PointerKind as p, PlatformFeedback as r, InteractionConfig as s, FeedbackPluginOptions as t, InteractionToken as u };
-//# sourceMappingURL=contract-F3gsFtSf.d.ts.map