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

package/dist/anchored.d.ts

@@ -1,45 +1,2 @@
-import * as React from "react";
-import { AnchorTarget, AnchorTarget as AnchorTarget$1, AnchoredPlacement, AnchoredPlacement as AnchoredPlacement$1, ViewProjector, ViewProjector as ViewProjector$1 } from "@embedpdf/web";
-//#region src/anchored.d.ts
-/**
- * What a page surface provides via context: the pure projection snapshot,
- * bound to React's reactivity.
- */
-interface ProjectorBinding {
-  projector: ViewProjector$1;
-  /**
-   * Changes identity exactly when projection may have changed for
-   * STATE-driven reasons — the Stage uses its `visiblePages()` value (a
-   * stable reference that already folds camera, viewport, scene and DPR).
-   * Consumers re-render because the binding's identity changes with it;
-   * nothing reads this field, but it is what makes the memoized binding
-   * change, so do not "optimize" it away.
-   */
-  revision: unknown;
-  /** Browser-driven invalidation ONLY (PageView scroll/resize — see
-   *  `observeClientGeometry`). The Stage deliberately provides none. */
-  subscribe?: (callback: () => void) => () => void;
-}
-/** Installed by page surfaces (<Stage>, <PageView>) — not by app code. */
-declare const ProjectorProvider: React.Provider<ProjectorBinding | null>;
-/** The surface's projector binding. Reading it subscribes the caller to
- *  projection changes (the binding's identity IS the revision). */
-declare function useProjectorBinding(): ProjectorBinding;
-interface AnchoredProps {
-  anchor: AnchorTarget$1 | null;
-  /** Which side of the anchor to sit on. Default 'top'. */
-  placement?: AnchoredPlacement$1;
-  /** Gap in screen px between the anchor box and the content. Default 8. */
-  gap?: number;
-  children: React.ReactNode;
-}
-/**
- * Position `children` around a content-space anchor, on whichever page
- * surface is in scope. Projection runs during render from the shared pure
- * helper; pointer isolation keeps a click inside anchored UI from reaching
- * the surface's own listener (which would read it as click-outside).
- */
-declare function Anchored({ anchor, placement, gap, children }: AnchoredProps): import("react/jsx-runtime").JSX.Element | null;
-//#endregion
-export { type AnchorTarget, Anchored, type AnchoredPlacement, AnchoredProps, ProjectorBinding, ProjectorProvider, type ViewProjector, useProjectorBinding };
-//# sourceMappingURL=anchored.d.ts.map
+import { a as AnchoredSide, c as ProjectorProvider, d as ViewProjector, f as useOptionalProjectorBinding, i as AnchoredProps, l as ShownPages, n as Anchored, o as PageViewEnv, p as useProjectorBinding, r as AnchoredPlacement, s as ProjectorBinding, t as AnchorTarget, u as ShownPagesProvider } from "./anchored-DeX95xSd.js";
+export { type AnchorTarget, Anchored, type AnchoredPlacement, AnchoredProps, type AnchoredSide, type PageViewEnv, ProjectorBinding, ProjectorProvider, ShownPages, ShownPagesProvider, type ViewProjector, useOptionalProjectorBinding, useProjectorBinding };

package/dist/anchored.js

@@ -1,48 +1,85 @@
 import { jsx } from "react/jsx-runtime";
-import { createContext, useContext, useEffect, useLayoutEffect, useReducer, useRef } from "react";
+import { observeAnchoredFit, projectAnchoredTarget, sameAnchoredFit } from "@embedpdf/web";
+import { createContext, useContext, useEffect, useLayoutEffect, useReducer, useState } from "react";
 import { createPortal } from "react-dom";
-import { projectAnchoredTarget } from "@embedpdf/web";
 //#region src/anchored.tsx
 const ProjectorContext = createContext(null);
 /** Installed by page surfaces (<Stage>, <PageView>) — not by app code. */
 const ProjectorProvider = ProjectorContext.Provider;
+const ShownPagesContext = createContext(null);
+/** Installed by page surfaces (<Stage>, <PageView>) — not by app code. */
+const ShownPagesProvider = ShownPagesContext.Provider;
+/** The surface's projector binding, or null outside any page surface — for
+*  chrome that degrades (and warns) instead of throwing. */
+function useOptionalProjectorBinding() {
+	return useContext(ProjectorContext);
+}
 /** The surface's projector binding. Reading it subscribes the caller to
-*  projection changes (the binding's identity IS the revision). */
+*  projection changes (the binding's identity is the revision). */
 function useProjectorBinding() {
 	const binding = useContext(ProjectorContext);
 	if (!binding) throw new Error("No ViewProjector in scope: mount anchored UI under <Stage> (overlay slot) or <PageView>.");
 	return binding;
 }
 /**
-* Position `children` around a content-space anchor, on whichever page
-* surface is in scope. Projection runs during render from the shared pure
-* helper; pointer isolation keeps a click inside anchored UI from reaching
-* the surface's own listener (which would read it as click-outside).
+* Position `children` around a page-space anchor, on whichever page surface
+* is in scope. Projection runs during render from the shared pure helper.
+* Once the content's size is measured, it flips to the opposite side when
+* the chosen one has no room, and stays inside the view, unless `pinned`.
+* Its wrapper's `data-placement` is where it sits now: `placement`, or the
+* opposite side after a flip, so what opens from the content can open away
+* from the box.
+* Pointer isolation keeps a click inside anchored UI from reaching the
+* surface's own listener (which would read it as a click outside).
+*
+* Anchored UI on a page that isn't shown renders nothing and reads only the
+* pages on screen, so a document with hundreds of badges costs only the ones
+* in view while people scroll and zoom.
 */
-function Anchored({ anchor, placement = "top", gap = 8, children }) {
+function Anchored(props) {
+	const shown = useContext(ShownPagesContext);
+	if (!props.anchor?.bounds) return null;
+	if (shown && !shown.has(props.anchor.page.objectNumber)) return null;
+	return /* @__PURE__ */ jsx(PlacedAnchored, { ...props });
+}
+/** Anchored UI on a page that is shown: it follows the camera. */
+function PlacedAnchored({ anchor, placement = "top", gap = 8, pinned = false, children }) {
 	const { projector, subscribe } = useProjectorBinding();
+	const [element, setElement] = useState(null);
+	const [fit, setFit] = useState(null);
 	const [, force] = useReducer((x) => x + 1, 0);
 	useLayoutEffect(() => subscribe ? subscribe(force) : void 0, [subscribe]);
 	useLayoutEffect(() => {
 		if (projector.space === "client") force();
 	}, [projector, anchor]);
-	const ref = useRef(null);
+	useLayoutEffect(() => {
+		if (!element) return;
+		return observeAnchoredFit(element, projector.space, (next) => setFit((current) => sameAnchoredFit(current, next) ? current : next));
+	}, [element, projector.space]);
 	useEffect(() => {
-		const el = ref.current;
-		if (!el) return;
-		const stop = (e) => e.stopPropagation();
-		el.addEventListener("pointerdown", stop);
-		return () => el.removeEventListener("pointerdown", stop);
-	});
-	if (!anchor) return null;
-	const pos = projectAnchoredTarget(projector, anchor, placement, gap);
+		if (!element) return;
+		const stop = (event) => event.stopPropagation();
+		element.addEventListener("pointerdown", stop);
+		return () => element.removeEventListener("pointerdown", stop);
+	}, [element]);
+	if (!anchor?.bounds) return null;
+	const pos = projectAnchoredTarget(projector, {
+		...anchor,
+		bounds: anchor.bounds
+	}, {
+		placement,
+		gap,
+		pinned
+	}, fit);
 	if (!pos) return null;
 	const node = /* @__PURE__ */ jsx("div", {
-		ref,
+		ref: setElement,
+		"data-placement": pos.placement,
 		style: {
 			position: projector.space === "client" ? "fixed" : "absolute",
 			left: pos.left,
 			top: pos.top,
+			width: "max-content",
 			transform: pos.transform,
 			pointerEvents: "auto"
 		},
@@ -55,6 +92,6 @@ function Anchored({ anchor, placement = "top", gap = 8, children }) {
 	return node;
 }
 //#endregion
-export { Anchored, ProjectorProvider, useProjectorBinding };
+export { Anchored, ProjectorProvider, ShownPagesProvider, useOptionalProjectorBinding, useProjectorBinding };
 
 //# sourceMappingURL=anchored.js.map

package/dist/anchored.js.map

@@ -1 +1 @@
-{"version":3,"file":"anchored.js","names":[],"sources":["../src/anchored.tsx"],"sourcesContent":["/**\n * Anchored overlays — ONE primitive for every piece of UI that floats over\n * page content (selection menus, draft menus, future popovers).\n *\n * The factoring:\n *   - PLUGINS produce anchors (a content-space rect on a page, plus points\n *     to dodge) as capability reads.\n *   - The projection SNAPSHOT contract and the placement math are shared,\n *     framework-neutral, in `@embedpdf/web` ({@link ViewProjector},\n *     `projectAnchoredTarget`).\n *   - SURFACES (<Stage>, <PageView>) provide a {@link ProjectorBinding}:\n *     the snapshot plus REACT's way of knowing when it changed.\n *   - <Anchored> renders at the projected position, isolates pointer\n *     events, and portals when the space demands it.\n *\n * THE SCHEDULING LAW (this is what keeps menus glued to the content): a\n * state-driven projection change (the Stage camera) reaches consumers as a\n * NEW BINDING IDENTITY through context — surface and overlay re-render in\n * the SAME React commit, so they can never paint a frame apart. No\n * listener sets, no post-commit notifications, no second menu-only render.\n * `subscribe` exists ONLY for genuinely browser-driven invalidation (a\n * PageView moving because the document scrolled), where no state change\n * announces the move.\n */\nimport * as React from 'react';\nimport { createContext, useContext, useEffect, useLayoutEffect, useReducer, useRef } from 'react';\nimport { createPortal } from 'react-dom';\nimport {\n  projectAnchoredTarget,\n  type AnchoredPlacement,\n  type AnchorTarget,\n  type ViewProjector,\n} from '@embedpdf/web';\n\nexport type { AnchoredPlacement, AnchorTarget, ViewProjector } from '@embedpdf/web';\n\n/**\n * What a page surface provides via context: the pure projection snapshot,\n * bound to React's reactivity.\n */\nexport interface ProjectorBinding {\n  projector: ViewProjector;\n  /**\n   * Changes identity exactly when projection may have changed for\n   * STATE-driven reasons — the Stage uses its `visiblePages()` value (a\n   * stable reference that already folds camera, viewport, scene and DPR).\n   * Consumers re-render because the binding's identity changes with it;\n   * nothing reads this field, but it is what makes the memoized binding\n   * change, so do not \"optimize\" it away.\n   */\n  revision: unknown;\n  /** Browser-driven invalidation ONLY (PageView scroll/resize — see\n   *  `observeClientGeometry`). The Stage deliberately provides none. */\n  subscribe?: (callback: () => void) => () => void;\n}\n\nconst ProjectorContext = createContext<ProjectorBinding | null>(null);\n\n/** Installed by page surfaces (<Stage>, <PageView>) — not by app code. */\nexport const ProjectorProvider = ProjectorContext.Provider;\n\n/** The surface's projector binding. Reading it subscribes the caller to\n *  projection changes (the binding's identity IS the revision). */\nexport function useProjectorBinding(): ProjectorBinding {\n  const binding = useContext(ProjectorContext);\n  if (!binding) {\n    throw new Error(\n      'No ViewProjector in scope: mount anchored UI under <Stage> (overlay slot) or <PageView>.',\n    );\n  }\n  return binding;\n}\n\nexport interface AnchoredProps {\n  anchor: AnchorTarget | null;\n  /** Which side of the anchor to sit on. Default 'top'. */\n  placement?: AnchoredPlacement;\n  /** Gap in screen px between the anchor box and the content. Default 8. */\n  gap?: number;\n  children: React.ReactNode;\n}\n\n/**\n * Position `children` around a content-space anchor, on whichever page\n * surface is in scope. Projection runs during render from the shared pure\n * helper; pointer isolation keeps a click inside anchored UI from reaching\n * the surface's own listener (which would read it as click-outside).\n */\nexport function Anchored({ anchor, placement = 'top', gap = 8, children }: AnchoredProps) {\n  const { projector, subscribe } = useProjectorBinding();\n\n  // Browser-driven invalidation only (PageView). State-driven changes come\n  // through the binding identity — no local bump involved.\n  const [, force] = useReducer((x: number) => x + 1, 0);\n  useLayoutEffect(() => (subscribe ? subscribe(force) : undefined), [subscribe]);\n  // Client-space surfaces measure the DOM, which does not exist during the\n  // surface's first render — force one post-commit pass so the position\n  // appears as soon as it is measurable. (Solves measurability, not\n  // reactivity.)\n  useLayoutEffect(() => {\n    if (projector.space === 'client') force();\n  }, [projector, anchor]);\n\n  const ref = useRef<HTMLDivElement>(null);\n  useEffect(() => {\n    const el = ref.current;\n    if (!el) return;\n    const stop = (e: Event) => e.stopPropagation();\n    el.addEventListener('pointerdown', stop);\n    return () => el.removeEventListener('pointerdown', stop);\n  });\n\n  if (!anchor) return null;\n  const pos = projectAnchoredTarget(projector, anchor, placement, gap);\n  if (!pos) return null;\n\n  const node = (\n    <div\n      ref={ref}\n      style={{\n        position: projector.space === 'client' ? 'fixed' : 'absolute',\n        left: pos.left,\n        top: pos.top,\n        transform: pos.transform,\n        pointerEvents: 'auto',\n      }}\n    >\n      {children}\n    </div>\n  );\n  if (projector.space === 'client') {\n    if (typeof document === 'undefined') return null;\n    return createPortal(node, document.body);\n  }\n  return node;\n}\n"],"mappings":";;;;;AAwDA,MAAM,mBAAmB,cAAuC,IAAI;;AAGpE,MAAa,oBAAoB,iBAAiB;;;AAIlD,SAAgB,sBAAwC;CACtD,MAAM,UAAU,WAAW,gBAAgB;CAC3C,IAAI,CAAC,SACH,MAAM,IAAI,MACR,0FACF;CAEF,OAAO;AACT;;;;;;;AAiBA,SAAgB,SAAS,EAAE,QAAQ,YAAY,OAAO,MAAM,GAAG,YAA2B;CACxF,MAAM,EAAE,WAAW,cAAc,oBAAoB;CAIrD,MAAM,GAAG,SAAS,YAAY,MAAc,IAAI,GAAG,CAAC;CACpD,sBAAuB,YAAY,UAAU,KAAK,IAAI,KAAA,GAAY,CAAC,SAAS,CAAC;CAK7E,sBAAsB;EACpB,IAAI,UAAU,UAAU,UAAU,MAAM;CAC1C,GAAG,CAAC,WAAW,MAAM,CAAC;CAEtB,MAAM,MAAM,OAAuB,IAAI;CACvC,gBAAgB;EACd,MAAM,KAAK,IAAI;EACf,IAAI,CAAC,IAAI;EACT,MAAM,QAAQ,MAAa,EAAE,gBAAgB;EAC7C,GAAG,iBAAiB,eAAe,IAAI;EACvC,aAAa,GAAG,oBAAoB,eAAe,IAAI;CACzD,CAAC;CAED,IAAI,CAAC,QAAQ,OAAO;CACpB,MAAM,MAAM,sBAAsB,WAAW,QAAQ,WAAW,GAAG;CACnE,IAAI,CAAC,KAAK,OAAO;CAEjB,MAAM,OACJ,oBAAC,OAAD;EACO;EACL,OAAO;GACL,UAAU,UAAU,UAAU,WAAW,UAAU;GACnD,MAAM,IAAI;GACV,KAAK,IAAI;GACT,WAAW,IAAI;GACf,eAAe;EACjB;EAEC;CACE,CAAA;CAEP,IAAI,UAAU,UAAU,UAAU;EAChC,IAAI,OAAO,aAAa,aAAa,OAAO;EAC5C,OAAO,aAAa,MAAM,SAAS,IAAI;CACzC;CACA,OAAO;AACT"}
+{"version":3,"file":"anchored.js","names":[],"sources":["../src/anchored.tsx"],"sourcesContent":["/**\n * Anchored overlays — one primitive for every piece of UI that floats over\n * page content (selection menus, draft menus, future popovers).\n *\n * The factoring:\n *   - plugins produce anchors (a page-space rect on a page, plus points\n *     to dodge) as capability reads.\n *   - The projection snapshot contract and the placement math are shared,\n *     framework-neutral, in `@embedpdf/web` ({@link ViewProjector},\n *     `projectAnchoredTarget`).\n *   - surfaces (<Stage>, <PageView>) provide a {@link ProjectorBinding}:\n *     the snapshot plus react's way of knowing when it changed.\n *   - <Anchored> renders at the projected position, flips to the other\n *     side and stays inside the view once it knows its size (unless\n *     pinned), says where it sits in `data-placement`, isolates pointer\n *     events, and portals when the space demands it. On a page that isn't\n *     shown it renders nothing and doesn't follow the camera at all (see\n *     {@link ShownPages}).\n *\n * The scheduling law (this is what keeps menus glued to the content): a\n * state-driven projection change (the Stage camera) reaches consumers as a\n * new binding identity through context — surface and overlay re-render in\n * the same React commit, so they can never paint a frame apart. No\n * listener sets, no post-commit notifications, no second menu-only render.\n * `subscribe` exists only for genuinely browser-driven invalidation (a\n * PageView moving because the document scrolled), where no state change\n * announces the move.\n */\nimport * as React from 'react';\nimport { createContext, useContext, useEffect, useLayoutEffect, useReducer, useState } from 'react';\nimport { createPortal } from 'react-dom';\nimport {\n  observeAnchoredFit,\n  projectAnchoredTarget,\n  sameAnchoredFit,\n  type AnchoredFit,\n  type AnchoredPlacement,\n  type AnchoredRect,\n  type AnchorTarget,\n  type ViewProjector,\n} from '@embedpdf/web';\n\nexport type {\n  AnchoredPlacement,\n  AnchoredSide,\n  AnchorTarget,\n  PageViewEnv,\n  ViewProjector,\n} from '@embedpdf/web';\n\n/**\n * What a page surface provides via context: the pure projection snapshot,\n * bound to React's reactivity.\n */\nexport interface ProjectorBinding {\n  projector: ViewProjector;\n  /**\n   * Changes identity exactly when projection may have changed for\n   * state-driven reasons — the Stage uses its `visiblePages()` value (a\n   * stable reference that already folds camera, viewport, scene and DPR).\n   * Consumers re-render because the binding's identity changes with it;\n   * nothing reads this field, but it is what makes the memoized binding\n   * change, so do not \"optimize\" it away.\n   */\n  revision: unknown;\n  /** Browser-driven invalidation only (PageView scroll/resize — see\n   *  `observeClientGeometry`). The Stage deliberately provides none. */\n  subscribe?: (callback: () => void) => () => void;\n}\n\nconst ProjectorContext = createContext<ProjectorBinding | null>(null);\n\n/** Installed by page surfaces (<Stage>, <PageView>) — not by app code. */\nexport const ProjectorProvider = ProjectorContext.Provider;\n\n/**\n * The pages a surface shows right now, by object number. It is a value of its\n * own, next to the projection, because it changes only when a page comes on\n * screen or leaves it: anchored UI on other pages reads only this, so it\n * isn't rendered again on every camera frame.\n */\nexport type ShownPages = ReadonlySet<number>;\n\nconst ShownPagesContext = createContext<ShownPages | null>(null);\n\n/** Installed by page surfaces (<Stage>, <PageView>) — not by app code. */\nexport const ShownPagesProvider = ShownPagesContext.Provider;\n\n/** The surface's projector binding, or null outside any page surface — for\n *  chrome that degrades (and warns) instead of throwing. */\nexport function useOptionalProjectorBinding(): ProjectorBinding | null {\n  return useContext(ProjectorContext);\n}\n\n/** The surface's projector binding. Reading it subscribes the caller to\n *  projection changes (the binding's identity is the revision). */\nexport function useProjectorBinding(): ProjectorBinding {\n  const binding = useContext(ProjectorContext);\n  if (!binding) {\n    throw new Error(\n      'No ViewProjector in scope: mount anchored UI under <Stage> (overlay slot) or <PageView>.',\n    );\n  }\n  return binding;\n}\n\nexport interface AnchoredProps {\n  /**\n   * The box on a page to sit next to, in page coordinates: `{ page, bounds }`,\n   * with `avoid` points to keep clear of. `null`, or a target without\n   * `bounds` (a search match with no geometry), hides it.\n   */\n  anchor: (Omit<AnchorTarget, 'bounds'> & { bounds?: AnchoredRect }) | null;\n  /**\n   * Where to sit: a side of the box, centred, or lined up with the side's\n   * start or end (`'top-end'`). Default 'top'.\n   */\n  placement?: AnchoredPlacement;\n  /**\n   * Gap in screen px between the box and the content, and between the content\n   * and the view's edge. Negative overlaps the box. Default 8.\n   */\n  gap?: number;\n  /**\n   * Stay where `placement` puts it: never flip to the other side, never move\n   * to stay in view, and scroll away with the box. For badges and status;\n   * menus leave it off. Default false.\n   */\n  pinned?: boolean;\n  children: React.ReactNode;\n}\n\n/**\n * Position `children` around a page-space anchor, on whichever page surface\n * is in scope. Projection runs during render from the shared pure helper.\n * Once the content's size is measured, it flips to the opposite side when\n * the chosen one has no room, and stays inside the view, unless `pinned`.\n * Its wrapper's `data-placement` is where it sits now: `placement`, or the\n * opposite side after a flip, so what opens from the content can open away\n * from the box.\n * Pointer isolation keeps a click inside anchored UI from reaching the\n * surface's own listener (which would read it as a click outside).\n *\n * Anchored UI on a page that isn't shown renders nothing and reads only the\n * pages on screen, so a document with hundreds of badges costs only the ones\n * in view while people scroll and zoom.\n */\nexport function Anchored(props: AnchoredProps) {\n  const shown = useContext(ShownPagesContext);\n  if (!props.anchor?.bounds) return null;\n  if (shown && !shown.has(props.anchor.page.objectNumber)) return null;\n  return <PlacedAnchored {...props} />;\n}\n\n/** Anchored UI on a page that is shown: it follows the camera. */\nfunction PlacedAnchored({\n  anchor,\n  placement = 'top',\n  gap = 8,\n  pinned = false,\n  children,\n}: AnchoredProps) {\n  const { projector, subscribe } = useProjectorBinding();\n  const [element, setElement] = useState<HTMLDivElement | null>(null);\n  // The content's size and the view's: measured after the first commit, and\n  // again whenever either resizes. A camera move changes neither.\n  const [fit, setFit] = useState<AnchoredFit | null>(null);\n\n  // Browser-driven invalidation only (PageView). State-driven changes come\n  // through the binding identity — no local bump involved.\n  const [, force] = useReducer((x: number) => x + 1, 0);\n  useLayoutEffect(() => (subscribe ? subscribe(force) : undefined), [subscribe]);\n  // Client-space surfaces measure the DOM, which does not exist during the\n  // surface's first render — force one post-commit pass so the position\n  // appears as soon as it is measurable. (Solves measurability, not\n  // reactivity.)\n  useLayoutEffect(() => {\n    if (projector.space === 'client') force();\n  }, [projector, anchor]);\n\n  useLayoutEffect(() => {\n    if (!element) return;\n    return observeAnchoredFit(element, projector.space, (next) =>\n      setFit((current) => (sameAnchoredFit(current, next) ? current : next)),\n    );\n  }, [element, projector.space]);\n\n  useEffect(() => {\n    if (!element) return;\n    const stop = (event: Event) => event.stopPropagation();\n    element.addEventListener('pointerdown', stop);\n    return () => element.removeEventListener('pointerdown', stop);\n  }, [element]);\n\n  if (!anchor?.bounds) return null;\n  const pos = projectAnchoredTarget(\n    projector,\n    { ...anchor, bounds: anchor.bounds },\n    { placement, gap, pinned },\n    fit,\n  );\n  if (!pos) return null;\n\n  const node = (\n    <div\n      ref={setElement}\n      data-placement={pos.placement}\n      style={{\n        position: projector.space === 'client' ? 'fixed' : 'absolute',\n        left: pos.left,\n        top: pos.top,\n        // Its own width, wherever it sits: the size the placement measured.\n        width: 'max-content',\n        transform: pos.transform,\n        pointerEvents: 'auto',\n      }}\n    >\n      {children}\n    </div>\n  );\n  if (projector.space === 'client') {\n    if (typeof document === 'undefined') return null;\n    return createPortal(node, document.body);\n  }\n  return node;\n}\n"],"mappings":";;;;;AAsEA,MAAM,mBAAmB,cAAuC,IAAI;;AAGpE,MAAa,oBAAoB,iBAAiB;AAUlD,MAAM,oBAAoB,cAAiC,IAAI;;AAG/D,MAAa,qBAAqB,kBAAkB;;;AAIpD,SAAgB,8BAAuD;CACrE,OAAO,WAAW,gBAAgB;AACpC;;;AAIA,SAAgB,sBAAwC;CACtD,MAAM,UAAU,WAAW,gBAAgB;CAC3C,IAAI,CAAC,SACH,MAAM,IAAI,MACR,0FACF;CAEF,OAAO;AACT;;;;;;;;;;;;;;;;AA2CA,SAAgB,SAAS,OAAsB;CAC7C,MAAM,QAAQ,WAAW,iBAAiB;CAC1C,IAAI,CAAC,MAAM,QAAQ,QAAQ,OAAO;CAClC,IAAI,SAAS,CAAC,MAAM,IAAI,MAAM,OAAO,KAAK,YAAY,GAAG,OAAO;CAChE,OAAO,oBAAC,gBAAD,EAAgB,GAAI,MAAQ,CAAA;AACrC;;AAGA,SAAS,eAAe,EACtB,QACA,YAAY,OACZ,MAAM,GACN,SAAS,OACT,YACgB;CAChB,MAAM,EAAE,WAAW,cAAc,oBAAoB;CACrD,MAAM,CAAC,SAAS,cAAc,SAAgC,IAAI;CAGlE,MAAM,CAAC,KAAK,UAAU,SAA6B,IAAI;CAIvD,MAAM,GAAG,SAAS,YAAY,MAAc,IAAI,GAAG,CAAC;CACpD,sBAAuB,YAAY,UAAU,KAAK,IAAI,KAAA,GAAY,CAAC,SAAS,CAAC;CAK7E,sBAAsB;EACpB,IAAI,UAAU,UAAU,UAAU,MAAM;CAC1C,GAAG,CAAC,WAAW,MAAM,CAAC;CAEtB,sBAAsB;EACpB,IAAI,CAAC,SAAS;EACd,OAAO,mBAAmB,SAAS,UAAU,QAAQ,SACnD,QAAQ,YAAa,gBAAgB,SAAS,IAAI,IAAI,UAAU,IAAK,CACvE;CACF,GAAG,CAAC,SAAS,UAAU,KAAK,CAAC;CAE7B,gBAAgB;EACd,IAAI,CAAC,SAAS;EACd,MAAM,QAAQ,UAAiB,MAAM,gBAAgB;EACrD,QAAQ,iBAAiB,eAAe,IAAI;EAC5C,aAAa,QAAQ,oBAAoB,eAAe,IAAI;CAC9D,GAAG,CAAC,OAAO,CAAC;CAEZ,IAAI,CAAC,QAAQ,QAAQ,OAAO;CAC5B,MAAM,MAAM,sBACV,WACA;EAAE,GAAG;EAAQ,QAAQ,OAAO;CAAO,GACnC;EAAE;EAAW;EAAK;CAAO,GACzB,GACF;CACA,IAAI,CAAC,KAAK,OAAO;CAEjB,MAAM,OACJ,oBAAC,OAAD;EACE,KAAK;EACL,kBAAgB,IAAI;EACpB,OAAO;GACL,UAAU,UAAU,UAAU,WAAW,UAAU;GACnD,MAAM,IAAI;GACV,KAAK,IAAI;GAET,OAAO;GACP,WAAW,IAAI;GACf,eAAe;EACjB;EAEC;CACE,CAAA;CAEP,IAAI,UAAU,UAAU,UAAU;EAChC,IAAI,OAAO,aAAa,aAAa,OAAO;EAC5C,OAAO,aAAa,MAAM,SAAS,IAAI;CACzC;CACA,OAAO;AACT"}

package/dist/annotation-B48UT2ln.d.ts

@@ -0,0 +1,302 @@
+import { n as StateHook, t as SettingsHook } from "./state-0K1I5cM4.js";
+import { r as AnchoredPlacement } from "./anchored-DeX95xSd.js";
+import { c as PageContextValue } from "./runtime-V3MVMb91.js";
+import { EventHook } from "@embedpdf/core";
+import * as React$1 from "react";
+import { Annotation, AnnotationAnchor, AnnotationCapability, AnnotationFilter, AnnotationProperties, AnnotationRef, CommentThread, CommentsApi, FilePickerProvider, HandleRole, ToolDefaults } from "@embedpdf/plugin-annotation";
+import { AnnotationFlags, CreationDraftAnchor, CreationDraftAnchor as CreationDraftAnchor$1, FieldValues, LineEnding, LineEndings, Point, RenderItem, RenderItem as RenderItem$1, RotationAnchor, Style, TextAlign, TextStyle } from "@embedpdf/core-annotation";
+//#region src/annotation-hooks.d.ts
+/**
+ * The annotation state: `status` (`'loading'` until every annotation is in,
+ * then `'ready'`), the `selected` annotations, the one `hovered` under the
+ * pointer and the text box being typed in (`editing`). Re-renders only when a
+ * field changes, or the value `select` picks. Empty without a document.
+ */
+declare const useAnnotationState: StateHook<{
+  status: import("@embedpdf/core").ResourceStatus;
+  selected: readonly import("@embedpdf/plugin-annotation").Annotation[];
+  hovered: import("@embedpdf/plugin-annotation").Annotation | null;
+  editing: import("@embedpdf/plugin-annotation").Annotation | null;
+}>;
+/**
+ * The annotation settings (`snap`, `chrome`, `afterCreate`, `tools`), or the
+ * value `select` picks. They belong to the plugin, so they read without a
+ * document; change them with `useAnnotation().updateSettings()`.
+ */
+declare const useAnnotationSettings: SettingsHook<import("@embedpdf/plugin-annotation").AnnotationSettings>;
+//#endregion
+//#region src/annotation-menu.d.ts
+interface AnnotationMenuProps {
+  children: React$1.ReactNode;
+  /** Gap in screen px between the selection box and the menu (default 15). */
+  gap?: number;
+  /** Where to place the menu relative to the selection box. Default 'top'. */
+  placement?: AnchoredPlacement;
+}
+/**
+ * Your own menu next to the selection (one anchor, also for a selection over
+ * several pages), clear of the rotation handle. It hides while the selection
+ * is dragged, resized or turned. What's in it is yours: build it from
+ * `useAnnotation()` and `useAnnotationState()`.
+ */
+declare function AnnotationMenu({ children, gap, placement }: AnnotationMenuProps): import("react/jsx-runtime").JSX.Element | null;
+interface AnnotationDraftMenuProps {
+  /** Render prop receiving the shape being drawn (`subtype`, `pointCount`,
+   *  `minPoints`, `canFinish`, …). The verbs are capability calls:
+   *  `useAnnotation().draft.finish()` and `.draft.cancel()`. */
+  children: (anchor: CreationDraftAnchor) => React$1.ReactNode;
+  /** Gap in screen px between the draft anchor and the menu (default 8). */
+  gap?: number;
+  /** Where to place the menu relative to the draft anchor. Default 'top'. */
+  placement?: AnchoredPlacement;
+}
+/** Floats over a live multi-click creation draft (polygon, polyline, …). */
+declare function AnnotationDraftMenu({ children, gap, placement }: AnnotationDraftMenuProps): import("react/jsx-runtime").JSX.Element | null;
+interface AnnotationRotationBadgeProps {
+  /** Render prop receiving the rotation in progress (`angle`, degrees
+   *  clockwise, as the commit will apply it). Without it, the badge shows the
+   *  angle in the `chrome.readout` colors, when `chrome.readout.enabled`. */
+  children?: (rotation: RotationAnchor) => React$1.ReactNode;
+  /** Gap in screen px between the pointer and the badge (default 16). */
+  gap?: number;
+  /** Where to place the badge relative to the pointer. Default 'right'. */
+  placement?: AnchoredPlacement;
+}
+/**
+ * Follows the pointer while a selection is being turned, upright however the
+ * page is shown: it floats over the page like the menus, not in it. Shows
+ * nothing when no rotation is in progress.
+ */
+declare function AnnotationRotationBadge({ children, gap, placement }: AnnotationRotationBadgeProps): import("react/jsx-runtime").JSX.Element | null;
+//#endregion
+//#region src/annotation.d.ts
+/** The box a renderer draws into: the size to draw at, how it's turned, and how it's scaled. */
+interface AnnotationFrame {
+  /** Its width in pixels at the annotation's 100% size, before its turn: draw at this. */
+  width: number;
+  /** Its height in pixels at the annotation's 100% size, before its turn: draw at this. */
+  height: number;
+  /**
+   * How it's turned on screen, degrees clockwise: the page's turn and the
+   * annotation's own. 0 is upright; turn your content by `-rotation` to keep
+   * it upright.
+   */
+  rotation: number;
+  /**
+   * How much the layer scales what you draw, with the page: the zoom, or for
+   * an annotation that keeps its size on screen, the zoom up to 1.
+   */
+  scale: number;
+}
+/**
+ * What a renderer's component gets: the annotation, the frame to draw into,
+ * and the layer's own drawing of it to keep or wrap. The layer keeps handling
+ * the pointer (select, move, resize) unless the renderer is `interactive`.
+ */
+interface AnnotationRendererProps {
+  /** The annotation, as `get()` returns it. */
+  annotation: Annotation;
+  /**
+   * The box you draw into. The layer places, turns and scales it like the
+   * annotation's own drawing, also during a drag, a resize or a turn. Fill it
+   * (`width: 100%; height: 100%`) and draw at the annotation's 100% size: your
+   * text and borders scale with the page.
+   */
+  frame: AnnotationFrame;
+  /** The layer's own drawing of it, filling the frame. Render it to keep the original look and add to it. */
+  native: React$1.ReactNode;
+  /** The engine's picture of the annotation as an image (`url`), or `null`. `native` draws it in place. */
+  appearance: {
+    url: string;
+  } | null;
+  /** True while the pointer is over it. */
+  hovered: boolean;
+  /** True while it's selected. */
+  selected: boolean;
+  /** True when what you draw takes the pointer (see `interactive` on the renderer). */
+  interactive: boolean;
+}
+/**
+ * What a sibling plugin's renderer gets for the annotations its behavior owns
+ * (the form plugin's fill controls). It places its own controls: `item` is the
+ * layer's projection of the annotation (its box, style, text and raster box,
+ * in page coordinates), and `page.transform.toPixels()` turns those into the
+ * layer's pixels.
+ */
+interface BehaviorRendererProps {
+  annotation: Annotation;
+  item: RenderItem;
+  page: PageContextValue;
+  /** The layer's own drawing of it, where the layer draws it. */
+  native: React$1.ReactNode;
+  hovered: boolean;
+  selected: boolean;
+  interactive: boolean;
+}
+/** What an `interactive` function is asked: the annotation, and the active tool. */
+interface AnnotationInteractiveContext {
+  annotation: Annotation;
+  toolId: string;
+}
+/**
+ * One rule: "draw these annotations with this component". `for` gets the
+ * annotation with all its fields; the first renderer that matches wins.
+ * Without `interactive` the component only draws: the layer keeps handling
+ * the pointer. With `interactive` (or a function asked whenever it matters)
+ * the component takes the pointer, and the annotation can't be selected or
+ * moved while it does.
+ *
+ * Define the list once, outside your component or in `useMemo`: the layer
+ * registers each entry, and a new list every render registers them again.
+ *
+ * `{ behavior, component }` draws what a sibling plugin's behavior owns (the
+ * form plugin's fill controls); the plugin decides when it's engaged.
+ */
+type AnnotationRenderer = {
+  behavior: string;
+  component: React$1.ComponentType<BehaviorRendererProps>;
+} | {
+  /** A stable id for the registration (optional; generated). */
+  id?: string;
+  for: (annotation: Annotation) => boolean;
+  component: React$1.ComponentType<AnnotationRendererProps>;
+  interactive?: boolean | ((context: AnnotationInteractiveContext) => boolean);
+  /**
+   * Scale what you draw with the page (the default): you draw at the
+   * annotation's 100% size. `false`: you draw at its size on screen, and
+   * size things yourself from `frame.scale`.
+   */
+  scale?: boolean;
+};
+/** What a handle component you draw yourself gets. */
+interface HandleProps {
+  /** The handle's center, in pixels on the page. */
+  at: Point;
+  /** The `size` from the settings, px. */
+  size: number;
+  /** The selection's rotation (degrees clockwise), so a square handle can turn with it. */
+  rotation: number;
+  /** A box's `'corner'` or `'side'`, or one `'point'` of a line or a polygon. */
+  kind: HandleRole;
+  /** True while it's being dragged. */
+  active: boolean;
+}
+/** What a rotation handle component gets: a handle's props, and where its stalk starts on the box. */
+interface RotationHandleProps extends Omit<HandleProps, 'kind'> {
+  /** Where the stalk starts on the box, in pixels on the page. */
+  from: Point;
+}
+/** Your own handles, drawn in place of the layer's. The viewer still decides where they can be grabbed. */
+interface AnnotationLayerComponents {
+  Handle?: React$1.ComponentType<HandleProps>;
+  RotationHandle?: React$1.ComponentType<RotationHandleProps>;
+}
+interface AnnotationLayerProps {
+  /** Your own look for some annotations ({@link AnnotationRenderer}). */
+  renderers?: AnnotationRenderer[];
+  /** Your own handles and rotation handle. */
+  components?: AnnotationLayerComponents;
+}
+/** What `useRichTextEditor()` gives the element you draw a text box with. */
+interface RichTextEditor {
+  /** Put it on your element: it becomes the editor. */
+  ref: (element: HTMLElement | null) => void;
+  /** The box's body style as CSS: font, size, color and alignment. While typing it takes the pointer too. */
+  style: React$1.CSSProperties;
+  /** True while someone types in the box. */
+  editing: boolean;
+}
+/**
+ * Make your own element the editor of a text box you draw yourself (a
+ * renderer for free text): it draws the runs, turns typing back into runs,
+ * keeps the caret when the style changes, and handles pasting, input methods
+ * and the format shortcuts. The formatting calls (`text.toggleFormat`,
+ * `selection.update`) work on it as they do on the built-in one.
+ */
+declare function useRichTextEditor(annotation: Annotation): RichTextEditor;
+/**
+ * Draws a page's annotations, the selection's outline and handles, the tool's
+ * preview and the text boxes being typed in. Put it above the rendered page:
+ * while it's there, the render layer leaves the annotations out of the
+ * page's picture.
+ */
+declare function AnnotationLayer({ renderers, components }?: AnnotationLayerProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * The default file-picker provider: the built-in file dialog (from
+ * `@embedpdf/web`), honouring the tool's `accept` filter. This is the adapter
+ * fulfilling the plugin's DOM-free port — the dialog lives in the framework
+ * layer, never in the plugin.
+ */
+declare const filePickerProvider: FilePickerProvider;
+/**
+ * Install the file-picker provider for the active document — the one port
+ * behind every click-then-pick tool (a stamp `'prompt'` source, the file-
+ * attachment tool). Call once at a document-scoped spot (not inside
+ * `<AnnotationLayer>`, which is per page). Defaults to
+ * {@link filePickerProvider}, so a bare `useFilePickerProvider()` makes all of
+ * them work out of the box; pass a custom provider (asset library, cloud
+ * drive — switch on `req.subtype` / `req.toolId`) or `null` to make
+ * click-then-pick tools inert. Cleared on unmount.
+ */
+declare function useFilePickerProvider(provider?: FilePickerProvider | null): void;
+declare function useAnnotation(): AnnotationCapability;
+/** Listen to one annotation event while the component is mounted: `useAnnotationEvent((annotation) => annotation.onCreated, handler)`. */
+declare function useAnnotationEvent<T>(select: (annotation: AnnotationCapability) => EventHook<T>, handler: (event: T) => void): void;
+/**
+ * The annotations matching `filter` (some pages, one kind), in drawing order,
+ * as the user sees them; the same array while they stay the same. Empty
+ * without a document.
+ */
+declare function useAnnotationList(filter?: AnnotationFilter): readonly Annotation[];
+/**
+ * A tool's defaults: the fields its next annotation starts with, over the
+ * engine's. The component re-renders when they change, so a color picker
+ * always shows the current color. Empty without a document.
+ */
+declare function useAnnotationDefaults(toolId: string): ToolDefaults;
+/**
+ * What a style panel shows: the selection's properties (`selection.getProperties()`),
+ * or, given a tool id, the tool's (`tools.getProperties(id)`). The component
+ * re-renders when they change. Empty without a document.
+ */
+declare function useAnnotationProperties(toolId?: string): AnnotationProperties;
+/**
+ * An anchor for `<Anchored>` that keeps a card or a badge attached to one
+ * annotation: its page and the box around what it shows, following a move
+ * as it happens. `null` for `null`, or an annotation that isn't here. The
+ * component re-renders when the annotation moves, not while people scroll or
+ * zoom: a note that keeps its size on screen hands `<Anchored>` its
+ * `boundsIn`.
+ */
+declare function useAnnotationAnchor(ref: AnnotationRef | null): AnnotationAnchor | null;
+/**
+ * A {@link CommentThread} enriched with its page's live display position —
+ * the framework-layer join (`enrichCommentThreads` in `@embedpdf/web`).
+ * Identity stays `page` (like every annotation surface); these two fields
+ * are presentation, tracking page moves and deletes.
+ */
+interface CommentThreadView extends CommentThread {
+  /** Current 0-based display index of the thread's page; `-1` when the page
+   *  is no longer in the document (one-frame teardown race on delete). */
+  pageIndex: number;
+  /** The page's `/PageLabels` label when the PDF declares one ("iv", "A-2"),
+   *  else the 1-based position as a string — print it verbatim. */
+  pageLabel: string;
+}
+/** The comments API: the `comments` part of `useAnnotation()`. Pair it with
+ *  {@link useCommentThreads} for the threads to show. */
+declare function useComments(): CommentsApi;
+/**
+ * Every comment thread in the document, display-ordered (page position →
+ * top of page → creation date) and enriched with `pageIndex`/`pageLabel`.
+ * Subscribed to both stores: annotation writes (own, remote, hydration)
+ * recompute the threads; page moves/deletes re-run the join. Reference-
+ * stable between changes — safe to memo child renders on the array.
+ */
+declare function useCommentThreads(): CommentThreadView[];
+/** The enriched thread containing any member ref (root, reply, grouped part,
+ *  state annotation), or null. */
+declare function useCommentThread(ref: AnnotationRef | null): CommentThreadView | null;
+//#endregion
+export { useCommentThreads as A, useAnnotationSettings as B, useAnnotation as C, useAnnotationList as D, useAnnotationEvent as E, AnnotationDraftMenuProps as F, AnnotationMenu as I, AnnotationMenuProps as L, useFilePickerProvider as M, useRichTextEditor as N, useAnnotationProperties as O, AnnotationDraftMenu as P, AnnotationRotationBadge as R, filePickerProvider as S, useAnnotationDefaults as T, useAnnotationState as V, RichTextEditor as _, AnnotationLayerComponents as a, TextAlign as b, AnnotationRendererProps as c, CreationDraftAnchor$1 as d, FieldValues as f, RenderItem$1 as g, LineEndings as h, AnnotationLayer as i, useComments as j, useCommentThread as k, BehaviorRendererProps as l, LineEnding as m, AnnotationFrame as n, AnnotationLayerProps as o, HandleProps as p, AnnotationInteractiveContext as r, AnnotationRenderer as s, AnnotationFlags as t, CommentThreadView as u, RotationHandleProps as v, useAnnotationAnchor as w, TextStyle as x, Style as y, AnnotationRotationBadgeProps as z };
+//# sourceMappingURL=annotation-B48UT2ln.d.ts.map