@docx-editor.dev/pro 0.0.1-placeholder → 2.0.1

package/dist/react/index.d.cts

@@ -0,0 +1,592 @@
+import { C as CustomNodeDefinition, A as ActivatedCustomNode } from '../define-custom-node-CkkDPdB0.cjs';
+export { P as ProLicenseOptions, b as ReviewModuleOptions, e as reviewModule } from '../define-custom-node-CkkDPdB0.cjs';
+import * as react from 'react';
+import { ReactNode } from 'react';
+import { ToolbarTranslate } from '@docx-editor.dev/react';
+import { ReviewItemPlacement, ReviewItemQuery, Editor } from '@docx-editor.dev/core/contracts/editor';
+import '@docx-editor.dev/core/editor';
+import '@docx-editor.dev/core/store';
+
+/**
+ * One card's data plus where it belongs on screen.
+ *
+ * The engine's own placement, unchanged. It is already presentation-ready — author,
+ * initials, date, text, thread — because deriving those from the canonical tree is engine
+ * work, and an adapter deriving them would be document derivation in a host and would have
+ * to be written once per framework.
+ */
+type ReviewItemView = ReviewItemPlacement;
+/**
+ * What {@link useReview} returns: the review rail's data and the four things a card can do.
+ *
+ * @public
+ */
+interface UseReviewReturn {
+    /** Every pending decision in the document, in reading order. */
+    readonly items: readonly ReviewItemView[];
+    /** The item the caret is in, or null. */
+    readonly activeKey: string | null;
+    /** Card to document: selects the item's range and scrolls to it. */
+    readonly setActive: (key: string | null) => void;
+    /** Accept a revision. A no-op on an item whose `readOnly` is true. */
+    readonly accept: (item: ReviewItemView) => void;
+    /** Reject a revision. A no-op on an item whose `readOnly` is true. */
+    readonly reject: (item: ReviewItemView) => void;
+    /**
+     * Discard the item: delete a comment thread, or reject a tracked change.
+     *
+     * One verb for both, so a card can carry one "remove this" control whatever it holds.
+     * Reports whether it landed — a comment the engine refused to delete must not vanish from
+     * the caller's own state while the document still holds it.
+     */
+    readonly remove: (item: ReviewItemView) => boolean;
+    /**
+     * Reply to a comment, or to a revision — which OOXML records as a comment on its range.
+     *
+     * The author is AMBIENT (`DocxEditorConfig.author`); pass one to override it for a single
+     * reply. `CT_Comment` makes `@w:author` required, so the engine refuses a reply with
+     * neither rather than writing an empty attribute — which is why this REPORTS whether the
+     * reply landed. A box that cleared itself on a refusal would throw the text away and show
+     * nothing, and the writer would not learn their reply never existed.
+     */
+    readonly reply: (item: ReviewItemView, text: string, author?: string) => boolean;
+    /**
+     * Where a comment on the current selection would sit, or null when nothing is selected.
+     *
+     * From the engine, not from the DOM — the same rule the card anchors follow.
+     */
+    readonly selectionAnchorY: number | null;
+    /** Comment on the current selection. Reports whether it landed, like {@link reply}. */
+    readonly comment: (text: string, author?: string) => boolean;
+    /** Whether the pane shows cards. Engine state: the toolbar's comments button toggles it. */
+    readonly paneOpen: boolean;
+    /** Open or close the pane — the same toggle the toolbar button runs. */
+    readonly setPaneOpen: (open: boolean) => void;
+    /** True while the engine has no document, so a surface can render nothing rather than empty. */
+    readonly ready: boolean;
+}
+/**
+ * Read the review queue and act on it.
+ *
+ * Subscribes to the editor's own change stream, so the list re-derives when the document does
+ * and not on every render.
+ */
+declare function useReview(query?: ReviewItemQuery): UseReviewReturn;
+/** The same hook against an explicit editor, for hosts that hold their own. */
+declare function useReviewOf(editor: Editor | null, query?: ReviewItemQuery): UseReviewReturn;
+/**
+ * Non-overlapping Y positions for cards you have measured.
+ *
+ * Separate from `useReview` because only the CALLER knows how tall its cards are — a host
+ * rendering its own markup can be told where each anchor is, but not how much room its card
+ * needs. Pass the measured heights back and get positions that do not collide; skip it
+ * entirely and cards sit on their raw anchors, which is correct for a rail that does not stack.
+ *
+ * Takes anything with a key and an anchor, not only cards: a compose box competes for the
+ * same column and has to be stacked WITH them or it lands on top of the card whose text was
+ * just re-selected. Entries must arrive in document order — the run is a single sweep.
+ *
+ * UNITS. Anchors are in layout POINTS, because that is what the engine publishes; measured
+ * heights are in CSS PIXELS, because that is what the DOM reports. Pass `scale` so the two
+ * can be added. Without it a 330px card advanced the run by 330 POINTS — 440px — and two
+ * comments on adjacent lines of one paragraph sat a third of a page apart.
+ */
+declare function useStackedReviewPositions(items: readonly {
+    readonly key: string;
+    readonly anchorY: number | null;
+}[], heights: ReadonlyMap<string, number>, options?: {
+    readonly gap?: number;
+    readonly scale?: number;
+    readonly defaultHeight?: number;
+}): ReadonlyMap<string, number>;
+
+/**
+ * The review item the surrounding card (or balloon) renders, or null outside one.
+ *
+ * The hook a host's own card content is built from: children passed into the rail's cards
+ * — extra actions, a custom body — read the CURRENT item here rather than receiving props,
+ * exactly the way the packaged parts do.
+ *
+ * @public
+ */
+declare function useReviewItem(): ReviewItemView | null;
+/** Shared props for every part. @public */
+interface ReviewPartProps {
+    className?: string;
+    /** Merge this part's wiring onto the single child element instead of the default one. */
+    asChild?: boolean;
+    /** Render nothing — inside the packaged arrangement this removes the part. */
+    hidden?: boolean;
+    children?: ReactNode;
+}
+/** Props for the action parts, which also take an icon. @public */
+interface ReviewActionProps extends ReviewPartProps {
+    /** Icon override; falls back to `children`, then to the part's default glyph. */
+    icon?: ReactNode;
+}
+/** Props for `DocxEditor.Review`. @public */
+interface ReviewProps extends Omit<ReviewPartProps, 'children'> {
+    /**
+     * Label resolver, as `DocxEditor.Toolbar`, `.Menu` and `.ContextMenu` take one. Unresolved
+     * keys fall back to the bundled catalogue rather than to the key.
+     */
+    t?: ToolbarTranslate;
+    /** Class for each card. The rail's own `className` styles the column; this the boxes in it. */
+    card?: {
+        className?: string;
+    };
+    /**
+     * The cards, or a render prop that replaces the packaged card entirely while keeping the
+     * rail's subscription, anchoring, stacking and virtualization. Nodes are treated as part
+     * overrides for the packaged card instead.
+     *
+     * ```tsx
+     * <DocxEditor.Review>{(item) => <MyCard item={item} />}</DocxEditor.Review>
+     * ```
+     */
+    children?: ReactNode | ((item: ReviewItemView) => ReactNode);
+    /**
+     * Host content at the top of the rail, above the cards — filters, legends, summaries.
+     *
+     * Rendered only while the pane is OPEN. A closed rail gives up its width for a 32px strip
+     * of markers, and content laid out for the 300px column has nowhere to go in it; unmounting
+     * is the rail's own business, not something a host should have to subscribe to `paneOpen`
+     * to discover. Furniture that should outlive the toggle belongs outside the rail.
+     */
+    furniture?: ReactNode;
+    /**
+     * Render the packaged arrangement. `false` mounts the rail and its context only, so a host
+     * can lay the cards out itself while keeping the subscription and the anchoring.
+     */
+    preset?: boolean;
+    /**
+     * Stack cards so they never overlap, pushing later ones down. `false` leaves every card on
+     * its raw anchor, which is right for a rail that draws connectors instead.
+     */
+    stack?: boolean;
+    /** Gap (px) between stacked cards. The only source of vertical spacing in the rail. */
+    gap?: number;
+    /** Show only some of the queue — comments in one rail, revisions in another. */
+    filter?: (item: ReviewItemView) => boolean;
+    /**
+     * Show the "changed the document structure" cards. Default `false`: a heavily revised
+     * document carries one per structural site and together they crowd out the cards a
+     * reviewer can act on. The revisions stay marked in the document, where clicking one
+     * opens its balloon — this hides only their rail cards.
+     */
+    structural?: boolean;
+    /**
+     * Show the "changed text formatting" cards. Default `false`, same reasoning as
+     * {@link structural}: a restyled document mints one per run, and the decision is
+     * reachable by clicking the grey-marked text instead. The rail keeps the decisions a
+     * reviewer reads in order — content changes and comments.
+     */
+    formatting?: boolean;
+}
+/**
+ * The review rail.
+ *
+ * Positions absolutely inside the nearest positioned ancestor — put it in
+ * `DocxEditor.Viewport` beside `DocxEditor.Content`, which is what makes the cards scroll
+ * with the pages without a scroll listener.
+ *
+ * @public
+ */
+declare function ReviewRoot({ className, furniture, asChild, hidden, children, t: hostT, card, preset, stack, gap, filter, structural, formatting, }: ReviewProps): react.JSX.Element | null;
+interface ReviewListProps {
+    stack?: boolean;
+    positions?: ReadonlyMap<string, number>;
+    /** Cards the stacking pass collapsed to a header — pushed too far from their text. */
+    collapsed?: ReadonlySet<string>;
+    scale?: number;
+    offset?: number;
+    /** Visible band of the scroller; cards outside it are not mounted. Null renders all. */
+    window?: {
+        top: number;
+        bottom: number;
+    } | null;
+    /**
+     * A render prop takes over the card entirely, keeping the rail's subscription, anchoring
+     * and stacking. Nodes are treated as part overrides for the packaged card.
+     */
+    children?: ReactNode | ((item: ReviewItemView) => ReactNode);
+    className?: string;
+    hidden?: boolean;
+}
+/**
+ * The cards, each positioned at its anchor.
+ *
+ * REPLIES are not cards. A threaded reply belongs inside the comment it answers, and giving
+ * it a card of its own would put two entries in the rail for one conversation.
+ *
+ * @public
+ */
+declare function ReviewList({ stack, positions, collapsed, scale, offset, window: visible, children, className, hidden, }: ReviewListProps): react.JSX.Element | null;
+declare namespace ReviewList {
+    var docxReviewPart: "List";
+}
+/**
+ * The collapsed rail: one marker per item, at its anchor.
+ *
+ * @public
+ */
+declare function ReviewMarkers({ scale, offset, window: visible, className, hidden, }: {
+    scale?: number;
+    offset?: number;
+    /** Visible band of the scroller; markers outside it are not mounted. */
+    window?: {
+        top: number;
+        bottom: number;
+    } | null;
+    className?: string;
+    hidden?: boolean;
+}): react.JSX.Element | null;
+declare namespace ReviewMarkers {
+    var docxReviewPart: "Markers";
+}
+/**
+ * The "comment on this" button, beside the selected text.
+ *
+ * Appears only for a RANGE. A comment on a caret has nothing to point at, and Word writes
+ * none, so the affordance is absent rather than present-and-refusing.
+ *
+ * @public
+ */
+declare function ReviewAddComment({ top, drafting, className, hidden, children, }: ReviewPartProps & {
+    top: number | null;
+    drafting?: boolean;
+}): react.JSX.Element | null;
+declare namespace ReviewAddComment {
+    var docxReviewPart: "AddComment";
+}
+/**
+ * The compose box for a new comment.
+ *
+ * Nothing is written until it is submitted: an empty `w:comment` is a real comment in the
+ * file, and committing on open would leave one behind every time somebody changed their mind.
+ *
+ * @public
+ */
+declare function ReviewDraft({ top, className, hidden }: ReviewPartProps & {
+    top: number;
+}): react.JSX.Element | null;
+declare namespace ReviewDraft {
+    var docxReviewPart: "Draft";
+}
+/**
+ * The decision balloon: CLICKING a format or structural change in the PAGE opens its card
+ * beside the text — author, what changed, when, and accept/reject where the engine can
+ * resolve it — and the card stays until a press lands somewhere that is neither a tracked
+ * change nor the balloon itself. Click-opened on purpose: a hover-opened card vanished
+ * under the pointer travelling toward its own buttons.
+ *
+ * ONLY the kinds whose rail cards are hidden by default. Content changes and comments are
+ * the rail's — a balloon over "added" text repeats a card already beside the page — while
+ * a format or structural change has nothing but its grey/washed marking, so the click on
+ * that marking is where its decision lives.
+ *
+ * Matches the pressed element against the UNFILTERED queue, attribution first and POSITION
+ * last: the `(id, author, date)` triple, then `(id, author)`, then the id, then the span's
+ * own paragraph range against the items' ranges — real files drift on attribution, and the
+ * range is the one thing the painter and the review model cannot disagree about. An
+ * element matching nothing still shows what its DOM carries, just without actions.
+ *
+ * @public
+ */
+declare function ReviewBalloon({ className, hidden }: ReviewPartProps): react.JSX.Element | null;
+declare namespace ReviewBalloon {
+    var docxReviewPart: "Balloon";
+}
+/** Shown when nothing is pending. @public */
+declare function ReviewEmpty({ className, hidden, children }: ReviewPartProps): react.JSX.Element | null;
+declare namespace ReviewEmpty {
+    var docxReviewPart: "Empty";
+}
+/**
+ * One card.
+ *
+ * Clicking it makes the item active, which SELECTS ITS RANGE in the document — the card and
+ * the text it is about are two views of one thing, and a card that highlighted nothing left
+ * the reader hunting for which words a comment meant.
+ *
+ * @public
+ */
+declare function ReviewCard({ className, asChild, hidden, children }: ReviewPartProps): react.JSX.Element | null;
+declare namespace ReviewCard {
+    var docxReviewPart: "Card";
+}
+/** The author's initials, in their colour. @public */
+declare function ReviewAvatar({ className, asChild, hidden, children }: ReviewPartProps): react.JSX.Element | null;
+declare namespace ReviewAvatar {
+    var docxReviewPart: "Avatar";
+}
+/** The author's name. @public */
+declare function ReviewAuthor({ className, asChild, hidden, children }: ReviewPartProps): react.JSX.Element | null;
+declare namespace ReviewAuthor {
+    var docxReviewPart: "Author";
+}
+/**
+ * When the change was made.
+ *
+ * `@w:date` is optional in `CT_TrackChange` and Word omits it when the author turned off
+ * "store randomized IDs"/date stamping, so a missing date renders nothing rather than an
+ * "Invalid Date".
+ *
+ * @public
+ */
+declare function ReviewTime({ className, asChild, hidden, children }: ReviewPartProps): react.JSX.Element | null;
+declare namespace ReviewTime {
+    var docxReviewPart: "Time";
+}
+/**
+ * What the card is about: the comment's text, or what the revision did.
+ *
+ * A revision that carries no characters — a formatting change, a paragraph mark, a row
+ * insertion — still gets a sentence. Word shows one, and a card reading only "Ada Lovelace"
+ * tells the reviewer nothing they can decide on.
+ *
+ * @public
+ */
+declare function ReviewSummary({ className, asChild, hidden, children }: ReviewPartProps): react.JSX.Element | null;
+declare namespace ReviewSummary {
+    var docxReviewPart: "Summary";
+}
+/** Accept the revision behind this card. @public */
+declare function ReviewAccept({ className, asChild, hidden, children, icon: glyph }: ReviewActionProps): react.JSX.Element | null;
+declare namespace ReviewAccept {
+    var docxReviewPart: "Accept";
+}
+/** Reject the revision behind this card. @public */
+declare function ReviewReject({ className, asChild, hidden, children, icon: glyph }: ReviewActionProps): react.JSX.Element | null;
+declare namespace ReviewReject {
+    var docxReviewPart: "Reject";
+}
+/**
+ * Discard what the card holds: delete a comment thread, or reject a tracked change.
+ *
+ * The rail had accept and reject for a change and NOTHING for a comment, so a remark could be
+ * resolved but never removed — a reader who commented by mistake had to go back to the text and
+ * delete the words to be rid of it. One control on both kinds, because "remove this" is the same
+ * intent whichever the card holds; the engine's `deleteReviewItem` decides what it means.
+ *
+ * Absent, not disabled, on a card with nothing to discard — a custom node's, or a revision kind
+ * the engine cannot resolve.
+ *
+ * Revealed on HOVER of the one thing it deletes, and on keyboard focus — the stylesheet owns
+ * that, not this component. A rail of twenty cards each carrying a standing invitation to
+ * delete somebody's remark reads as an invitation to click one by mistake; scoping it to the
+ * node under the pointer also means a reply and the comment it answers never offer two
+ * identical buttons at once, which is the state that makes a reader delete the wrong one.
+ *
+ * CSS rather than an `isActive` gate because a reply is never itself the active item, and
+ * because requiring the reader to open a card before they can be rid of it is a step with
+ * nothing behind it. `visibility`, not `opacity`: hidden must also mean unclickable, and the
+ * space stays reserved so the row does not jump as the pointer crosses it.
+ *
+ * @public
+ */
+declare function ReviewDelete({ className, asChild, hidden, children, icon: glyph }: ReviewActionProps): react.JSX.Element | null;
+declare namespace ReviewDelete {
+    var docxReviewPart: "Delete";
+}
+/** The thread under a comment, in document order. @public */
+declare function ReviewReplies({ className, hidden }: ReviewPartProps): react.JSX.Element | null;
+declare namespace ReviewReplies {
+    var docxReviewPart: "Replies";
+}
+/**
+ * The reply box.
+ *
+ * Open only on the ACTIVE card: a rail with a text field on every card is mostly text fields,
+ * and the caret landing in a tracked change is what says which conversation the reader is in.
+ *
+ * Replying to a revision writes a comment over that revision's range — `w:ins` and `w:del`
+ * have no body and no thread in OOXML, so there is nowhere else for the text to live.
+ *
+ * @public
+ */
+declare function ReviewReply({ className, hidden, children }: ReviewPartProps): react.JSX.Element | null;
+declare namespace ReviewReply {
+    var docxReviewPart: "Reply";
+}
+/**
+ * The review rail compound.
+ *
+ * @public
+ */
+interface DocxEditorReviewNamespace {
+    (props: ReviewProps): ReturnType<typeof ReviewRoot>;
+    readonly List: typeof ReviewList;
+    readonly Empty: typeof ReviewEmpty;
+    readonly Card: typeof ReviewCard;
+    readonly Avatar: typeof ReviewAvatar;
+    readonly Author: typeof ReviewAuthor;
+    readonly Time: typeof ReviewTime;
+    readonly Summary: typeof ReviewSummary;
+    readonly Accept: typeof ReviewAccept;
+    readonly Reject: typeof ReviewReject;
+    /** Discard the card: delete a comment thread, or reject a tracked change. */
+    readonly Delete: typeof ReviewDelete;
+    readonly Replies: typeof ReviewReplies;
+    readonly Reply: typeof ReviewReply;
+    /** The collapsed rail: one marker per item, shown when the pane is closed. */
+    readonly Markers: typeof ReviewMarkers;
+    /** The "comment on this" button beside a selected range. */
+    readonly AddComment: typeof ReviewAddComment;
+    /** The compose box a new comment is written in. */
+    readonly Draft: typeof ReviewDraft;
+    /** The decision balloon opened by clicking a format or structural change in the page. */
+    readonly Balloon: typeof ReviewBalloon;
+}
+/**
+ * The review rail: comments and tracked changes as a compound component.
+ *
+ * `DocxEditorReview` is itself the root; every part hangs off it, so a host arranges the pieces
+ * it wants rather than accepting one fixed layout. Requires the review module to be registered
+ * via `createDocxEditor({ modules: [reviewModule()] })` — without it there is nothing to derive
+ * cards from.
+ *
+ * @example
+ * ```tsx
+ * <DocxEditorReview>
+ *   <DocxEditorReview.List>
+ *     <DocxEditorReview.Card>
+ *       <DocxEditorReview.Author />
+ *       <DocxEditorReview.Summary />
+ *       <DocxEditorReview.Accept />
+ *       <DocxEditorReview.Reject />
+ *     </DocxEditorReview.Card>
+ *   </DocxEditorReview.List>
+ * </DocxEditorReview>
+ * ```
+ *
+ * @public
+ */
+declare const DocxEditorReview: DocxEditorReviewNamespace;
+
+/**
+ * Props for {@link CustomNodeChrome}: which definitions to paint, and where activation goes.
+ *
+ * The two hooks are the COMPONENT-level twins of a definition's own `onClick`/`onHover`. Host UI
+ * state — a popover, a dialog — belongs here rather than on the definition, which is shared by
+ * every surface and has no React context to close over.
+ *
+ * @public
+ */
+interface CustomNodeChromeProps {
+    /** Definitions to style and dispatch on. Defaults to the ones registered on the editor. */
+    readonly nodes?: readonly CustomNodeDefinition[];
+    /** Component-level activation hook — where host UI state (popovers) belongs. */
+    readonly onNodeClick?: (node: ActivatedCustomNode) => void;
+    readonly onNodeHover?: (node: ActivatedCustomNode) => void;
+}
+/**
+ * Paints custom-node chips and dispatches pointer activation on them.
+ *
+ * Renders nothing itself — it installs the per-definition chip styles and the click/hover
+ * listeners, so mount it once anywhere inside the editor provider. Chip colours come from each
+ * definition's `chrome`, which is HOST-authored and never file data.
+ *
+ * @example
+ * ```tsx
+ * <DocxEditor.Root>
+ *   <CustomNodeChrome onNodeClick={(node) => setPopover(node)} />
+ *   <DocxEditor.Viewport><DocxEditor.Content /></DocxEditor.Viewport>
+ * </DocxEditor.Root>
+ * ```
+ *
+ * @public
+ */
+declare function CustomNodeChrome(props: CustomNodeChromeProps): null;
+
+/**
+ * Props for {@link CustomNodeContextMenu}: which definitions get menu sections, and which rows
+ * those sections offer.
+ *
+ * The Edit row renders when either the definition's own `onEdit` or this component's
+ * `onEditNode` is present; the Remove row is on by default but only where the node's canonical id
+ * can be resolved.
+ *
+ * @public
+ */
+interface CustomNodeContextMenuProps {
+    /** Definitions to offer sections for. Defaults to the ones registered on the editor. */
+    readonly nodes?: readonly CustomNodeDefinition[];
+    /**
+     * Component-level edit hook — where host UI state (an edit dialog) belongs, the twin of
+     * `CustomNodeChrome`'s `onNodeClick`. Runs after the definition's own `onEdit`. The row
+     * renders when EITHER hook is present.
+     */
+    readonly onEditNode?: (node: ActivatedCustomNode, definition: CustomNodeDefinition) => void;
+    /**
+     * The "Remove {label}" row, on by default: it deletes the node — wrapper and label, one
+     * undo step — via `removeCustomNode`. Rendered only when the node's id is resolvable
+     * (a registered review module resolves it). `false` removes the row.
+     */
+    readonly remove?: boolean;
+}
+/**
+ * Renders the pointed-at node's card data plus its "Edit {label}" row, or nothing when the
+ * right-click landed elsewhere. Carries `docxRowPlacement: 'start'`, so the context menu
+ * mounts it above the packaged rows.
+ *
+ * @public
+ */
+declare function CustomNodeContextMenu(props: CustomNodeContextMenuProps): react.JSX.Element | null;
+declare namespace CustomNodeContextMenu {
+    var docxRowPlacement: "start";
+}
+
+/**
+ * The definitions a chrome surface should act on: the `nodes` prop when given, else the
+ * definitions registered on the editor (`customNodesModule`). Registering once and letting
+ * every surface default to it is the intended shape; the prop exists for a host that wants
+ * one surface scoped narrower.
+ */
+declare function useCustomNodeDefinitions(nodes: readonly CustomNodeDefinition[] | undefined): readonly CustomNodeDefinition[];
+/**
+ * What {@link resolveCustomNodeActivation} found under a pointer target.
+ *
+ * The RAW decode, before the definition's `fromDocx` has had its say — use
+ * `activatedCustomNodeOf` for the enriched form every host hook receives.
+ *
+ * @public
+ */
+interface ResolvedCustomNodeActivation {
+    /** RAW decode: attrs straight from the tag, `fromDocx` not yet applied. */
+    readonly node: ActivatedCustomNode;
+    readonly definition: CustomNodeDefinition;
+    /** The control's canonical node id, from the chrome layer — for review-item lookups. */
+    readonly controlId: string | null;
+}
+/**
+ * The recognized custom node a pointer target sits on, or null.
+ *
+ * Every input here is DOM the engine painted from file data — the tag is
+ * attacker-controlled and goes through the codec's guards, never into markup.
+ */
+/**
+ * The activation every host hook receives: identity, POST-`fromDocx` attrs, and — when the
+ * review module derived a card for the node — its literal text and canonical node id.
+ *
+ * One enrichment step for every surface (click, hover, edit, context-menu card), so a hook
+ * written against the review rail's attrs shape sees the SAME shape from the chip. Without
+ * a review module the definition's `fromDocx` runs over the raw decode with `text: ''`;
+ * its veto (null) drops the activation, exactly as recognition would have.
+ */
+declare function activatedCustomNodeOf(resolved: ResolvedCustomNodeActivation, editor: Editor | null | undefined): ActivatedCustomNode | null;
+/**
+ * The recognized custom node a pointer target sits on, or null.
+ *
+ * Walks up from `target` to the painted control boundary, reads its `data-tag`, and matches the
+ * decoded identity against `nodes`. Returns null for anything that is not a recognized chip —
+ * ordinary text, an unclaimed SDT, a tag no definition owns.
+ *
+ * Every input is DOM the engine painted from FILE DATA. The tag is attacker-controlled and goes
+ * through the codec's guards; it never reaches markup.
+ *
+ * @public
+ */
+declare function resolveCustomNodeActivation(target: EventTarget | null, nodes: readonly CustomNodeDefinition[]): ResolvedCustomNodeActivation | null;
+
+export { CustomNodeChrome, type CustomNodeChromeProps, CustomNodeContextMenu, type CustomNodeContextMenuProps, DocxEditorReview, type DocxEditorReviewNamespace, type ResolvedCustomNodeActivation, type ReviewActionProps, type ReviewItemView, type ReviewPartProps, type ReviewProps, type UseReviewReturn, activatedCustomNodeOf, resolveCustomNodeActivation, useCustomNodeDefinitions, useReview, useReviewItem, useReviewOf, useStackedReviewPositions };