@stll/folio-react 0.4.0 → 0.6.0

package/dist/renderAsync-B7UJsZye.d.ts

@@ -0,0 +1,915 @@
+import React$1, { CSSProperties, ComponentProps, ComponentType, ReactNode, RefAttributes, RefObject } from "react";
+import { EditorState, Plugin, Transaction } from "prosemirror-state";
+import { EditorView } from "prosemirror-view";
+import { XmlFragment } from "yjs";
+import { FolioAIEditApplyMode, FolioAIEditApplyResult, FolioAIEditOperation, FolioAIEditSnapshot, FolioCommentAnchor, FolioReviewChange } from "@stll/folio-core/ai-edits";
+import { ContentControlFilter, SetContentControlContentInput, SetContentControlValueInput } from "@stll/folio-core/content-controls";
+import { FolioEditor } from "@stll/folio-core/controller/folioEditor";
+import { DocxCompatibility } from "@stll/folio-core/docx/compatibility";
+import { FolioSelectiveSaveFlags } from "@stll/folio-core/docx/selectiveSaveFlags";
+import { TripwireResult } from "@stll/folio-core/docx/selectiveSaveTripwire";
+import { SelectionState } from "@stll/folio-core/prosemirror";
+import { AnonymizationMatch } from "@stll/folio-core/prosemirror/plugins/anonymizationDecorations";
+import { TemplateSlashMenuKeyAction, TemplateSlashMenuState } from "@stll/folio-core/prosemirror/plugins/templateSlashMenu";
+import { ColorValue, Document, ParagraphAlignment, SdtProperties, SectionProperties, Style, Theme } from "@stll/folio-core/types/document";
+import { Comment } from "@stll/folio-core/types/content";
+import { DocxInput } from "@stll/folio-core/utils/docxInput";
+import { ScrollToParaIdOptions } from "@stll/folio-core/paged-layout/paragraphFlash";
+import { Layout } from "@stll/folio-core/layout-engine/types";
+import { Checkbox } from "@base-ui/react/checkbox";
+import { Dialog } from "@base-ui/react/dialog";
+import { Menu } from "@base-ui/react/menu";
+import { Popover } from "@base-ui/react/popover";
+import { Select } from "@base-ui/react/select";
+import { EditorMode } from "@stll/folio-core/managers/EditorModeManager";
+import { TableAction } from "@stll/folio-core/utils/tableOperations";
+
+//#region src/paged-editor/hostFonts.d.ts
+/**
+ * Host-app custom fonts — the `fonts` prop on `DocxEditor`.
+ *
+ * The host passes its own brand/web font faces; they register with the browser
+ * through the same best-effort `FontFace` path as embedded document fonts
+ * ({@link registerFontFace}), so a bad entry is skipped rather than throwing.
+ * Once registered, the family name is available for rendering and can be listed
+ * in the font-family picker via the `fontFamilies` prop.
+ *
+ * The prop normalizer ({@link toFontFaceInputs}) is pure (no DOM), so it is
+ * unit-tested directly; the DOM registration is visual-only.
+ */
+/**
+ * Declarative description of one custom font face the host registers with the
+ * editor. Multiple entries can share `family` to register distinct weights.
+ */
+type FontDefinition = {
+  /** CSS `font-family` name to expose; match the family your documents reference. */family: string; /** URL to the font file (woff2, woff, ttf, or otf). */
+  src: string; /** CSS `font-weight` for this face (a number like `700`, or a keyword). Defaults to `normal`. */
+  weight?: number | string;
+};
+//#endregion
+//#region src/paged-editor/PagedEditor.d.ts
+type PagedEditorRef = {
+  /** The headless editor controller (imperative API + events; Seam 6). */getEditor: () => FolioEditor; /** Get the current document. */
+  getDocument: () => Document | null; /** Get the ProseMirror EditorState. */
+  getState: () => EditorState | null; /** Get the ProseMirror EditorView. */
+  getView: () => EditorView | null;
+  /**
+   * Look up the persistent hidden HF EditorView by `rId`. Returns null when
+   * the slot isn't mounted (e.g. document has no HF for that rId, or the
+   * hidden host hasn't mounted yet).
+   */
+  getHfView: (rId: string) => EditorView | null;
+  /**
+   * Force-create the hidden editor view if it has been deferred.
+   * Use from surfaces that need a live view before any user
+   * interaction (e.g. AI chat reading a snapshot of the doc).
+   */
+  ensureView: (options?: {
+    focus?: boolean;
+  }) => void; /** Focus the editor. */
+  focus: () => void; /** Blur the editor. */
+  blur: () => void; /** Check if focused. */
+  isFocused: () => boolean; /** Dispatch a transaction. */
+  dispatch: (tr: Transaction) => void; /** Undo. */
+  undo: () => boolean; /** Redo. */
+  redo: () => boolean; /** Check whether undo is available. */
+  canUndo: () => boolean; /** Check whether redo is available. */
+  canRedo: () => boolean; /** Set selection by PM position. */
+  setSelection: (anchor: number, head?: number) => void; /** Get current layout. */
+  getLayout: () => Layout | null; /** Force re-layout. */
+  relayout: () => void; /** Scroll the visible pages to bring a PM position into view. */
+  scrollToPosition: (pmPos: number) => void; /** Scroll the visible pages to bring a page into view. */
+  scrollToPage: (pageNumber: number) => void;
+  /**
+   * Scroll the paginated view to the paragraph with the given Word `w14:paraId`.
+   * Returns whether a matching paragraph exists in the ProseMirror document.
+   */
+  scrollToParaId: (paraId: string, options?: ScrollToParaIdOptions) => boolean;
+  /** Resolve the page number (1-indexed) that contains the given PM position,
+   *  or null if no layout is available yet. Works for unrendered pages too via
+   *  the page shell map. */
+  getPageNumberForPmPos: (pmPos: number) => number | null;
+};
+//#endregion
+//#region src/ui/folio-ui.d.ts
+/**
+ * Folio chrome (toolbars, dialogs, pickers, find/replace) renders UI primitives
+ * that a consumer can override with its own design system. Each entry in
+ * {@link FolioUIComponents} is a React component (or a part-object of compound
+ * sub-components) folio's chrome renders; the contract grows as more primitives
+ * are decoupled from a hard design-system dependency.
+ *
+ * Compound primitives (Dialog, Select, Menu, Popover) are modeled as
+ * part-objects: a typed record of their sub-parts (`Root`, `Popup`, …). Chrome
+ * destructures the parts it needs from {@link useFolioUI}; the part shape keeps
+ * one key per primitive in the contract and lets the app inject a flat
+ * design-system module as a small adapter object. Each part's props are the
+ * subset of the underlying `@base-ui/react` part's props folio relies on, so an
+ * external component (which accepts a superset) stays assignable as an override.
+ *
+ * Standalone folio uses {@link DEFAULT_COMPONENTS} (built on `@base-ui/react`,
+ * the neutral primitive the app design system also wraps); consumers inject
+ * overrides through `DocxEditor`'s `components` prop.
+ */
+/**
+ * The Button prop subset folio's chrome actually relies on. `variant` and
+ * `size` are deliberately narrow string-literal unions: each is a subset of the
+ * design-system Button's options so an external Button stays assignable as an
+ * override. Native attributes are picked from `<button>` so their types match
+ * exactly.
+ */
+type FolioButtonProps = Pick<ComponentProps<"button">, "onClick" | "onMouseDown" | "className" | "disabled" | "type" | "title" | "aria-label" | "aria-pressed" | "children"> & {
+  variant?: "default" | "ghost";
+  size?: "sm" | "xs" | "icon-xs";
+};
+type FolioDialogRootProps = Pick<Dialog.Root.Props, "open" | "onOpenChange"> & {
+  children?: ReactNode;
+};
+type FolioDialogPortalProps = {
+  children?: ReactNode;
+};
+type FolioDialogBackdropProps = {
+  className?: string;
+};
+type FolioDialogPopupProps = {
+  className?: string;
+  children?: ReactNode;
+};
+type FolioDialogTitleProps = {
+  className?: string;
+  children?: ReactNode;
+};
+type FolioDialogCloseProps = {
+  className?: string;
+  children?: ReactNode;
+};
+type FolioDialog = {
+  Root: ComponentType<FolioDialogRootProps>;
+  Portal: ComponentType<FolioDialogPortalProps>;
+  Backdrop: ComponentType<FolioDialogBackdropProps>;
+  Popup: ComponentType<FolioDialogPopupProps>;
+  Title: ComponentType<FolioDialogTitleProps>;
+  Close: ComponentType<FolioDialogCloseProps>;
+};
+type FolioSelectRootProps = Pick<Select.Root.Props<string>, "value" | "onValueChange" | "disabled" | "items"> & {
+  children?: ReactNode;
+};
+type FolioSelectTriggerProps = Pick<Select.Trigger.Props, "style" | "aria-label"> & {
+  className?: string;
+  children?: ReactNode;
+  size?: "sm" | "default" | "lg";
+};
+type FolioSelectValueProps = Pick<Select.Value.Props, "placeholder"> & {
+  className?: string;
+  children?: ReactNode;
+};
+type FolioSelectPopupProps = {
+  className?: string;
+  children?: ReactNode;
+};
+type FolioSelectItemProps = Pick<Select.Item.Props, "value"> & {
+  className?: string;
+  children?: ReactNode;
+};
+type FolioSelect = {
+  Root: ComponentType<FolioSelectRootProps>;
+  Trigger: ComponentType<FolioSelectTriggerProps>;
+  Value: ComponentType<FolioSelectValueProps>;
+  Popup: ComponentType<FolioSelectPopupProps>;
+  Item: ComponentType<FolioSelectItemProps>;
+};
+type FolioMenuRootProps = {
+  children?: ReactNode;
+};
+type FolioMenuTriggerProps = Pick<Menu.Trigger.Props, "render" | "disabled" | "type" | "aria-label" | "onMouseDown"> & {
+  className?: string;
+  children?: ReactNode;
+  nativeButton?: boolean;
+};
+type FolioMenuPopupProps = {
+  className?: string;
+  children?: ReactNode;
+  align?: Menu.Positioner.Props["align"];
+  side?: Menu.Positioner.Props["side"];
+  sideOffset?: Menu.Positioner.Props["sideOffset"];
+  alignOffset?: Menu.Positioner.Props["alignOffset"];
+};
+type FolioMenuItemProps = Pick<Menu.Item.Props, "onClick"> & {
+  className?: string;
+  children?: ReactNode;
+};
+type FolioMenuCheckboxItemProps = Pick<Menu.CheckboxItem.Props, "checked" | "onCheckedChange"> & {
+  className?: string;
+  children?: ReactNode;
+};
+type FolioMenuGroupProps = {
+  children?: ReactNode;
+};
+type FolioMenuGroupLabelProps = {
+  className?: string;
+  children?: ReactNode;
+};
+type FolioMenuSeparatorProps = {
+  className?: string;
+};
+type FolioMenu = {
+  Root: ComponentType<FolioMenuRootProps>;
+  Trigger: ComponentType<FolioMenuTriggerProps>;
+  Popup: ComponentType<FolioMenuPopupProps>;
+  Item: ComponentType<FolioMenuItemProps>;
+  CheckboxItem: ComponentType<FolioMenuCheckboxItemProps>;
+  Group: ComponentType<FolioMenuGroupProps>;
+  GroupLabel: ComponentType<FolioMenuGroupLabelProps>;
+  Separator: ComponentType<FolioMenuSeparatorProps>;
+};
+type FolioPopoverRootProps = {
+  children?: ReactNode;
+};
+type FolioPopoverTriggerProps = Pick<Popover.Trigger.Props, "disabled" | "render"> & {
+  className?: string;
+  children?: ReactNode;
+  "data-testid"?: string;
+};
+type FolioPopoverPopupProps = Pick<Popover.Popup.Props, "onMouseDown"> & {
+  className?: string;
+  children?: ReactNode;
+  side?: Popover.Positioner.Props["side"];
+  align?: Popover.Positioner.Props["align"];
+  sideOffset?: Popover.Positioner.Props["sideOffset"];
+  alignOffset?: Popover.Positioner.Props["alignOffset"];
+};
+type FolioPopoverCloseProps = Pick<Popover.Close.Props, "render"> & {
+  className?: string;
+  children?: ReactNode;
+};
+type FolioPopover = {
+  Root: ComponentType<FolioPopoverRootProps>;
+  Trigger: ComponentType<FolioPopoverTriggerProps>;
+  Popup: ComponentType<FolioPopoverPopupProps>;
+  Close: ComponentType<FolioPopoverCloseProps>;
+};
+type FolioInputProps = Omit<ComponentProps<"input">, "size" | "ref" | "style"> & RefAttributes<HTMLInputElement> & {
+  style?: CSSProperties;
+  size?: "sm" | "default" | "lg" | number;
+  nativeInput?: boolean;
+};
+type FolioCheckboxProps = Pick<Checkbox.Root.Props, "checked" | "onCheckedChange"> & {
+  className?: string;
+};
+/**
+ * A color preset rendered as a swatch in the picker. Mirrors the design
+ * system's preset shape so an external ColorPicker stays assignable as an
+ * override; `color` is the optional CSS color for the swatch (falls back to
+ * `#${value}`), and `value` is what `onSelect` emits.
+ */
+type ColorPreset = {
+  label: string;
+  value: string;
+  color?: string;
+};
+/**
+ * The ColorPicker prop subset folio's chrome relies on. The picker wraps a
+ * trigger (`children`) in a popover exposing the `presets` plus a custom-color
+ * input; `onSelect` fires with a preset value or a 6-char hex (no `#`), and
+ * `onClear` clears the color. The design-system ColorPicker accepts a superset
+ * (placement, expansion, className) so it stays assignable as an override.
+ */
+type FolioColorPickerProps = {
+  value?: string | undefined;
+  onSelect?: (value: string) => void;
+  onClear?: () => void;
+  presets?: ColorPreset[];
+  columns?: number;
+  children: ReactNode;
+};
+/**
+ * The DatePickerPopover prop subset folio's chrome relies on. `value` accepts
+ * an ISO string, a `Date`, or `null`; `onChange` emits an ISO `yyyy-mm-dd`
+ * string (or `null` when cleared). The design-system picker accepts a superset
+ * (locale, min/max, overdue styling) so it stays assignable as an override.
+ */
+type FolioDatePickerPopoverProps = {
+  value: string | Date | null;
+  onChange: (value: string | null) => void;
+  clearLabel?: string;
+  defaultOpen?: boolean;
+  showIcon?: boolean;
+};
+/**
+ * One entry in the document outline. Mirrors the design system's item shape so
+ * an external OutlineRail stays assignable as an override.
+ */
+type OutlineItem = {
+  id: string;
+  label: string; /** Nesting depth; drives indent + tick taper. */
+  level: number; /** Optional trailing annotation in the panel (e.g. a page number). */
+  meta?: string; /** Optional CSS custom-property name colouring this entry. */
+  color?: string;
+};
+/**
+ * The OutlineRail prop subset folio's chrome relies on. The rail resolves each
+ * item's vertical position via `resolvePct` and navigates via `onJump` (both
+ * receive the resolved scroll container). `activeId` controls the highlighted
+ * entry. The design-system rail accepts a superset so it stays assignable as an
+ * override.
+ */
+type FolioOutlineRailProps = {
+  items: OutlineItem[];
+  scrollContainerRef: RefObject<HTMLElement | null>;
+  resolvePct: (id: string, container: HTMLElement) => number | null;
+  onJump: (id: string, container: HTMLElement) => void;
+  activeId?: string | null;
+  topOffset?: number;
+  panelWidth?: number;
+  ariaLabel?: string;
+};
+type FolioUIComponents = {
+  Button: ComponentType<FolioButtonProps>;
+  Dialog: FolioDialog;
+  Select: FolioSelect;
+  Menu: FolioMenu;
+  Popover: FolioPopover;
+  Input: ComponentType<FolioInputProps>;
+  Checkbox: ComponentType<FolioCheckboxProps>;
+  ColorPicker: ComponentType<FolioColorPickerProps>;
+  DatePickerPopover: ComponentType<FolioDatePickerPopoverProps>;
+  OutlineRail: ComponentType<FolioOutlineRailProps>;
+};
+declare function FolioUIProvider({
+  components,
+  children
+}: {
+  components?: Partial<FolioUIComponents> | undefined;
+  children: ReactNode;
+}): import("react").JSX.Element;
+//#endregion
+//#region src/components/ui/FontPicker.d.ts
+/**
+ * Font Picker — uses Stella's Select component.
+ * Each item rendered in its own font for preview.
+ */
+type FontOption = {
+  name: string;
+  fontFamily: string;
+  category?: "sans-serif" | "serif" | "monospace" | "other";
+};
+//#endregion
+//#region src/components/ui/ListButtons.d.ts
+/**
+ * List formatting buttons: bullet, numbered, indent, outdent.
+ */
+type ListType = "bullet" | "numbered" | "none";
+type ListState = {
+  type: ListType;
+  level: number;
+  isInList: boolean;
+  numId?: number;
+};
+//#endregion
+//#region src/components/toolbarPrimitives.d.ts
+/**
+ * Current formatting state of the selection
+ */
+type SelectionFormatting = {
+  /** Whether selected text is bold */bold?: boolean | undefined; /** Whether selected text is italic */
+  italic?: boolean | undefined; /** Whether selected text is underlined */
+  underline?: boolean | undefined; /** Whether selected text has strikethrough */
+  strike?: boolean | undefined; /** Whether selected text is superscript */
+  superscript?: boolean | undefined; /** Whether selected text is subscript */
+  subscript?: boolean | undefined; /** Font family of selected text */
+  fontFamily?: string | undefined; /** Font size of selected text (in half-points) */
+  fontSize?: number | undefined; /** Text color */
+  color?: string | undefined; /** Highlight color */
+  highlight?: string | undefined; /** Paragraph alignment */
+  alignment?: ParagraphAlignment | undefined; /** List state of the current paragraph */
+  listState?: ListState | undefined; /** Line spacing in twips (OOXML value, 240 = single spacing) */
+  lineSpacing?: number | undefined; /** Paragraph style ID */
+  styleId?: string | undefined; /** Paragraph left indentation in twips */
+  indentLeft?: number | undefined; /** Whether the paragraph is RTL (bidi) */
+  bidi?: boolean | undefined;
+};
+/**
+ * Formatting action types
+ */
+type FormattingAction = "bold" | "italic" | "underline" | "strikethrough" | "superscript" | "subscript" | "clearFormatting" | "bulletList" | "numberedList" | "indent" | "outdent" | "insertPageBreak" | "setRtl" | "setLtr" | {
+  type: "toggleDirection";
+} | {
+  type: "fontFamily";
+  value: string;
+} | {
+  type: "fontSize";
+  value: number;
+} | {
+  type: "textColor";
+  value: ColorValue | string;
+} | {
+  type: "highlightColor";
+  value: string;
+} | {
+  type: "alignment";
+  value: ParagraphAlignment;
+} | {
+  type: "lineSpacing";
+  value: number;
+} | {
+  type: "applyStyle";
+  value: string;
+};
+/**
+ * Props for the Toolbar component
+ */
+type ToolbarProps = {
+  /** Current formatting of the selection */currentFormatting?: SelectionFormatting | undefined; /** Callback when a formatting action is triggered */
+  onFormat?: ((action: FormattingAction) => void) | undefined; /** Callback for undo action */
+  onUndo?: (() => void) | undefined; /** Callback for redo action */
+  onRedo?: (() => void) | undefined; /** Whether undo is available */
+  canUndo?: boolean | undefined; /** Whether redo is available */
+  canRedo?: boolean | undefined; /** Whether the toolbar is disabled */
+  disabled?: boolean | undefined; /** Additional CSS class name */
+  className?: string | undefined; /** Additional inline styles */
+  style?: CSSProperties | undefined; /** Whether to enable keyboard shortcuts (default: true) */
+  enableShortcuts?: boolean | undefined; /** Ref to the editor container for keyboard events */
+  editorRef?: React$1.RefObject<HTMLElement | null> | undefined; /** Custom toolbar items to render */
+  children?: ReactNode | undefined; /** Whether to show font family picker (default: true) */
+  showFontPicker?: boolean | undefined;
+  /**
+   * Custom families for the font-family dropdown (strings and/or `FontOption`
+   * objects). Omit to use the built-in defaults; an empty array renders an
+   * empty dropdown. Normalized to `FontOption[]` before reaching the picker.
+   */
+  fontFamilies?: ReadonlyArray<string | FontOption> | undefined; /** Whether to show font size picker (default: true) */
+  showFontSizePicker?: boolean | undefined; /** Whether to show text color picker (default: true) */
+  showTextColorPicker?: boolean | undefined; /** Whether to show highlight color picker (default: true) */
+  showHighlightColorPicker?: boolean | undefined; /** Whether to show alignment buttons (default: true) */
+  showAlignmentButtons?: boolean | undefined; /** Whether to show list buttons (default: true) */
+  showListButtons?: boolean | undefined; /** Whether to show line spacing picker (default: true) */
+  showLineSpacingPicker?: boolean | undefined; /** Whether to show style picker (default: true) */
+  showStylePicker?: boolean | undefined; /** Whether to show the format painter button (default: true) */
+  showFormatPainter?: boolean | undefined; /** Whether the format painter is armed (drives the button's active state) */
+  formatPainterActive?: boolean | undefined;
+  /**
+   * Arm the format painter: capture the current selection's formatting so the
+   * next selection is painted. `sticky` (double-click) keeps it armed until Esc
+   * or a toggle off; a single click disarms after one paint.
+   */
+  onFormatPainter?: ((sticky: boolean) => void) | undefined; /** Document styles for the style picker */
+  documentStyles?: Style[] | undefined; /** Theme for the style picker */
+  theme?: Theme | null | undefined; /** Callback for print action */
+  onPrint?: (() => void) | undefined; /** Whether to show print button (default: true) */
+  showPrintButton?: boolean | undefined; /** Whether to show zoom control (default: true) */
+  showZoomControl?: boolean | undefined; /** Current zoom level (1.0 = 100%) */
+  zoom?: number | undefined; /** Callback when zoom changes */
+  onZoomChange?: ((zoom: number) => void) | undefined; /** Whether the rulers are currently visible (drives the toggle's active state) */
+  rulerVisible?: boolean | undefined; /** Toggle the rulers on/off. The ruler control renders only when this is provided. */
+  onToggleRuler?: (() => void) | undefined; /** Callback to refocus the editor after toolbar interactions */
+  onRefocusEditor?: (() => void) | undefined; /** Callback when a table should be inserted */
+  onInsertTable?: ((rows: number, columns: number) => void) | undefined; /** Whether to show table insert button (default: true) */
+  showTableInsert?: boolean | undefined; /** Callback when user wants to insert an image */
+  onInsertImage?: (() => void) | undefined; /** Callback when user wants to insert a page break */
+  onInsertPageBreak?: (() => void) | undefined; /** Callback when user wants to insert a table of contents */
+  onInsertTOC?: (() => void) | undefined; /** Callback when user wants to insert a shape */
+  onInsertShape?: (data: {
+    shapeType: string;
+    width: number;
+    height: number;
+    fillColor?: string | undefined;
+    fillType?: string | undefined;
+    outlineWidth?: number | undefined;
+    outlineColor?: string | undefined;
+  }) => void; /** Image context when an image is selected */
+  imageContext?: {
+    wrapType: string;
+    displayMode: string;
+    cssFloat: string | null;
+  } | null; /** Callback when image wrap type changes */
+  onImageWrapType?: ((wrapType: string) => void) | undefined; /** Callback for image transform (rotate/flip) */
+  onImageTransform?: (action: "rotateCW" | "rotateCCW" | "flipH" | "flipV") => void; /** Callback to open image properties dialog (alt text + border) */
+  onOpenImageProperties?: (() => void) | undefined; /** Callback to open page setup dialog */
+  onPageSetup?: (() => void) | undefined; /** Table context when cursor is in a table */
+  tableContext?: {
+    isInTable: boolean;
+    rowCount?: number | undefined;
+    columnCount?: number | undefined;
+    canSplitCell?: boolean | undefined;
+    hasMultiCellSelection?: boolean | undefined;
+    cellBorderColor?: ColorValue | undefined;
+    cellBackgroundColor?: string | undefined;
+  } | null; /** Callback when a table action is triggered */
+  onTableAction?: ((action: TableAction) => void) | undefined;
+};
+//#endregion
+//#region src/components/DocxEditor.props.d.ts
+type DocxEditorProps = {
+  /** Document data — ArrayBuffer, Uint8Array, Blob, or File */documentBuffer?: DocxInput | null; /** Password for Agile-encrypted .docx files (Office 2010+). */
+  password?: string | undefined; /** Pre-parsed document (alternative to documentBuffer) */
+  document?: Document | null;
+  /**
+   * Stable identity of the loaded document (same across internal edits, distinct
+   * per loaded file, e.g. a file/document id). Used to distinguish a genuine
+   * external load from an edited document round-tripped back through state.
+   * Falls back to a document-metadata signature when omitted.
+   */
+  documentKey?: string; /** Callback when document is saved */
+  onSave?: (buffer: ArrayBuffer) => void; /** Author name used for comments and track changes */
+  author?: string; /** Callback when document changes */
+  onChange?: (document: Document) => void; /** Callback when selection changes */
+  onSelectionChange?: (state: SelectionState | null) => void;
+  /**
+   * Callback fired with the resolved PM positions and the
+   * selected plain text on every selection-bearing
+   * transaction. Useful for consumers (e.g. the inspector
+   * "Term to anonymize" prefill) that want the selected
+   * phrase without holding a reference to the editor view.
+   * Atom inline nodes (tab, hard_break) collapse to a
+   * single space in the returned text. Empty string when
+   * the selection is collapsed.
+   */
+  onSelectionTextChange?: (selection: {
+    from: number;
+    to: number;
+    text: string;
+  }) => void; /** Callback on error */
+  onError?: (error: Error) => void; /** Callback when fonts are loaded */
+  onFontsLoaded?: () => void;
+  /**
+   * Custom families shown in the toolbar's font-family dropdown. Strings render
+   * as plain family names; pass `FontOption` objects for a CSS fallback chain
+   * and category grouping. Omit to use folio's built-in defaults; an empty
+   * array renders an empty (but enabled) dropdown. Pass a stable reference — an
+   * inline array is a fresh identity every render.
+   */
+  fontFamilies?: ReadonlyArray<string | FontOption>;
+  /**
+   * Custom font faces the host registers with the browser (its own brand/web
+   * fonts) so runs render in them. Each entry injects one face via the
+   * `FontFace` API; multiple entries can share `family` for different weights.
+   * Registration is best-effort: a malformed entry is skipped, never thrown.
+   * Match `family` to the `fontFamilies` name a user applies. Pass a stable
+   * reference — a new array identity re-registers on every render.
+   */
+  fonts?: ReadonlyArray<FontDefinition>; /** Theme for styling */
+  theme?: Theme | null; /** Whether to show toolbar (default: true) */
+  showToolbar?: boolean; /** Whether to show zoom control (default: true) */
+  showZoomControl?: boolean;
+  /**
+   * Whether to show the review controls — the track-changes toggle and the
+   * markup display-mode selector (All Markup / Simple / No Markup / Original)
+   * (default: true). Turn off for plain-markdown editing, where tracked changes
+   * and markup views are meaningless.
+   */
+  showReviewControls?: boolean;
+  /**
+   * Whether the page header/footer can be edited — the double-click-to-edit
+   * behavior and the "Double-click to add header/footer" hover hints
+   * (default: true). Turn off for plain-markdown editing, which has no running
+   * header/footer.
+   */
+  showHeaderFooterEditing?: boolean; /** Whether to show page margin guides/boundaries (default: false) */
+  showMarginGuides?: boolean; /** Color for margin guides (default: '#c0c0c0') */
+  marginGuideColor?: string;
+  /**
+   * Whether the horizontal and vertical rulers start visible (default: false).
+   * Seeds the initial state of the toolbar's ruler toggle; users show/hide the
+   * rulers at runtime from there (like Word's View > Ruler).
+   */
+  showRuler?: boolean; /** Measurement unit shown on the rulers (default: 'inch'). */
+  rulerUnit?: "inch" | "cm"; /** Initial zoom level (default: 1.0) */
+  initialZoom?: number; /** Whether Ctrl/Cmd+wheel and trackpad-pinch zoom are enabled (default: true) */
+  enableWheelZoom?: boolean; /** Whether the editor is read-only. When true, hides toolbar and rulers */
+  readOnly?: boolean; /** Whether comments/tracked changes should auto-open the review sidebar (default: true) */
+  autoOpenReviewSidebar?: boolean;
+  /**
+   * Override folio's built-in chrome UI primitives (Button, …) with a
+   * consumer's design-system components. Omitted entries fall back to folio's
+   * built-in defaults, so standalone folio works without any injection.
+   */
+  components?: Partial<FolioUIComponents>; /** Custom toolbar actions */
+  toolbarExtra?: ReactNode; /** Additional CSS class name */
+  className?: string; /** Additional inline styles */
+  style?: CSSProperties; /** Placeholder when no document */
+  placeholder?: ReactNode; /** Loading indicator */
+  loadingIndicator?: ReactNode; /** Keep the current parsed document visible while a new buffer is loading. */
+  preserveDocumentWhileLoading?: boolean; /** Initial scroll offset for the editor's document scroll container. */
+  initialScrollTop?: number; /** Callback when the editor's document scroll container scrolls. */
+  onScrollTopChange?: (scrollTop: number) => void; /** Whether to show the document outline sidebar (default: false) */
+  showOutline?: boolean; /** Whether to show print button in toolbar (default: true) */
+  showPrintButton?: boolean; /** Callback when print is triggered */
+  onPrint?: () => void;
+  /**
+   * Insert controls are opt-in: each toolbar control renders only when its
+   * handler is provided (and, for tables, `showTableInsert` is not false). Omit
+   * a handler to keep that control out of the toolbar. Wire these to the
+   * view-level helpers exported from the package (`insertTableInView`,
+   * `insertPageBreakInView`, `insertTableOfContentsInView`, `insertImageFromFile`).
+   */
+  onInsertImage?: (() => void) | undefined; /** Insert a `rows × columns` table at the current selection. */
+  onInsertTable?: ((rows: number, columns: number) => void) | undefined; /** Whether the Insert Table control is shown when `onInsertTable` is set (default: true). */
+  showTableInsert?: boolean | undefined; /** Insert a page break at the current selection. */
+  onInsertPageBreak?: (() => void) | undefined; /** Insert a table of contents generated from the document's headings. */
+  onInsertTOC?: (() => void) | undefined; /** Callback when content is copied */
+  onCopy?: () => void; /** Callback when content is cut */
+  onCut?: () => void; /** Callback when content is pasted */
+  onPaste?: () => void; /** Editor mode: 'editing' (direct edits), 'suggesting' (track changes), or 'viewing' (read-only). Default: 'editing' */
+  mode?: EditorMode; /** Callback when the editing mode changes */
+  onModeChange?: (mode: EditorMode) => void; /** Callback when a readonly user action would mutate the document. */
+  onReadonlyEditAttempt?: () => void;
+  /**
+   * Controlled comments array. When provided, the editor reads comment thread
+   * metadata from this prop and emits every change through `onCommentsChange`.
+   * Use with collaboration backends (Yjs, etc.) so comment threads sync across
+   * peers; PM carries range markers, thread metadata lives outside the doc.
+   */
+  comments?: Comment[]; /** Fires whenever the comments array changes (controlled and uncontrolled). */
+  onCommentsChange?: (comments: Comment[]) => void; /** Callback with the parsed document's editing compatibility report. */
+  onCompatibilityChange?: (compatibility: DocxCompatibility) => void;
+  /**
+   * Fires when the live ProseMirror view is captured (or torn down).
+   * The host wires this so it can drive the AI suggestion overlay
+   * (decoration meta, apply, scroll-to) from outside the editor.
+   */
+  onEditorViewReady?: (view: EditorView | null) => void; /** Yjs-backed collaboration owner. Experimental and opt-in. */
+  collaboration?: DocxEditorCollaboration | undefined;
+  /**
+   * Fires with the current anonymization match list every time
+   * the decoration plugin recomputes it (initial mount, term
+   * push, doc edit, async DOCX load). The host uses this to
+   * mirror per-document counts and "matching workspace terms"
+   * to the inspector facet without polling the plugin state.
+   */
+  onAnonymizationMatchesChange?: (matches: readonly AnonymizationMatch[]) => void;
+  /**
+   * Fires when the user clicks an anonymization highlight in
+   * the rendered document. Hosts use this to push the
+   * selection into a sidebar bridge so the inspector facet can
+   * scroll/flash the matching row.
+   */
+  onAnonymizationTermClick?: ((canonical: string, label: string) => void) | undefined;
+  /**
+   * Canonical to mark as selected in the rendered document.
+   * The first matching rect scrolls into view whenever
+   * `anonymizationSelectionSeq` increments (so repeated
+   * sidebar clicks of the same term re-trigger the scroll).
+   */
+  selectedAnonymizationCanonical?: string | null | undefined; /** Monotonic counter from the bridge store; drives the re-scroll. */
+  anonymizationSelectionSeq?: number | undefined;
+  /**
+   * Render legal-template markers ({{field}}, {{@clause:..}},
+   * {{#if}}/{{#each}}) as rich widgets on the page instead of raw
+   * text. Off for ordinary documents; on for the template editor.
+   */
+  showTemplateDirectives?: boolean | undefined;
+  /**
+   * Fires when the template editor's `/` slash-command trigger opens, its
+   * typed query changes, or it closes. Only active alongside
+   * `showTemplateDirectives`. The host renders the floating menu and inserts
+   * the chosen marker; the plugin owns only the trigger state.
+   */
+  onSlashMenuChange?: ((state: TemplateSlashMenuState) => void) | undefined;
+  /**
+   * Resolves a navigation/commit key (Up / Down / Enter) while the slash menu
+   * is open. Return `true` to let the editor swallow the key (the host moved
+   * the highlight or performed the insertion). Escape is handled inside the
+   * plugin and never reaches this callback.
+   */
+  onSlashMenuKeyAction?: ((action: TemplateSlashMenuKeyAction) => boolean) | undefined;
+  /**
+   * Host-provided text context-menu entries, appended after the built-ins.
+   * `requiresSelection` items only render when text is selected. Selecting one
+   * fires `onCustomContextAction` with the item id and the selection range
+   * captured when the menu opened (right-click can collapse the live PM
+   * selection, so the captured range is the reliable one).
+   */
+  customContextMenuItems?: readonly {
+    id: string;
+    label: string;
+    requiresSelection?: boolean;
+    icon?: ReactNode;
+  }[] | undefined;
+  onCustomContextAction?: ((id: string, selectionRange: {
+    from: number;
+    to: number;
+  }) => void) | undefined;
+  /**
+   * Operational flags for save-path features. Selective save and its tripwire
+   * mode are OFF by default; hosts opt in once their rollout pipeline is ready.
+   */
+  featureFlags?: FolioSelectiveSaveFlags;
+  /**
+   * Receives the structured comparison between selective save and full repack
+   * whenever {@link FolioSelectiveSaveFlags.selectiveSaveTripwire} is enabled.
+   * Saves are never blocked by the tripwire; this is observability only.
+   */
+  onSelectiveSaveTripwire?: (result: TripwireResult) => void;
+};
+type DocxEditorCollaboration = {
+  awareness?: {
+    clientID: number;
+    getStates: () => Map<number, unknown>;
+    off: (event: "change" | "update", handler: () => void) => void;
+    on: (event: "change" | "update", handler: () => void) => void;
+  } | undefined;
+  onSeeded?: (() => void) | undefined;
+  plugins?: Plugin[] | undefined;
+  shouldSeed?: boolean | undefined;
+  yXmlFragment: XmlFragment;
+};
+/**
+ * Imperative handle exposed by the DocxEditor component.
+ */
+type DocxEditorRef = {
+  /** Get the current document */getDocument: () => Document | null; /** Whether the live ProseMirror state has edits that have not been serialized. */
+  hasPendingChanges: () => boolean; /** Get the editor ref */
+  getEditorRef: () => PagedEditorRef | null; /** The headless editor controller (Seam 6), or null before the editor mounts. */
+  getEditor: () => FolioEditor | null; /** Save the document to buffer. Pass { selective: false } to force full repack. */
+  save: (options?: {
+    selective?: boolean;
+  }) => Promise<ArrayBuffer | null>; /** Set zoom level */
+  setZoom: (zoom: number) => void; /** Get current zoom level */
+  getZoom: () => number; /** Focus the editor */
+  focus: () => void; /** Get current page number */
+  getCurrentPage: () => number; /** Get total page count */
+  getTotalPages: () => number; /** Scroll to a specific page */
+  scrollToPage: (pageNumber: number) => void;
+  /**
+   * Scroll the paginated view to the paragraph with the given Word `w14:paraId`.
+   * Pass `options.highlight` to briefly flash it in a custom color.
+   */
+  scrollToParaId: (paraId: string, options?: ScrollToParaIdOptions) => boolean; /** Open print preview */
+  openPrintPreview: () => void; /** Print the document directly */
+  print: () => void; /** Load a pre-parsed document programmatically */
+  loadDocument: (doc: Document) => void; /** Load a DOCX buffer programmatically (ArrayBuffer, Uint8Array, Blob, or File) */
+  loadDocumentBuffer: (buffer: DocxInput) => Promise<void>;
+  /**
+   * Force-create the underlying editor view if it has been deferred.
+   * Surfaces that need a live view before the user interacts with the
+   * document body (notably the AI chat composer, which gates "send"
+   * on snapshot availability) must call this once on mount with
+   * `focus: false`; otherwise the perf deferral keeps the view null
+   * and they wait forever.
+   */
+  ensureEditorView: (options?: {
+    focus?: boolean;
+  }) => void; /** Create the block snapshot that an external AI editor should reference. */
+  createAIEditSnapshot: () => FolioAIEditSnapshot | null; /** Apply AI-authored operations against a previously created block snapshot. */
+  applyAIEditOperations: (options: {
+    snapshot: FolioAIEditSnapshot;
+    operations: FolioAIEditOperation[];
+    mode?: FolioAIEditApplyMode;
+    author?: string;
+  }) => FolioAIEditApplyResult;
+  /**
+   * Accept the tracked-change marks belonging to a previously applied AI edit.
+   * Pass a single id for inserts/standalone deletions, or the full id list
+   * (`applied.revisionIds`) for a replace, which has separate ids for its
+   * deletion and insertion sides. Returns whether a matching range was found.
+   */
+  acceptAIEditOperation: (revisionIds: number | readonly number[]) => boolean;
+  /**
+   * Reject the tracked-change marks belonging to a previously applied AI edit.
+   * Same id semantics as `acceptAIEditOperation`.
+   */
+  rejectAIEditOperation: (revisionIds: number | readonly number[]) => boolean;
+  /**
+   * Undo / redo the last history-recorded edit IN PLACE — e.g. an
+   * `acceptAIEditOperation` / `rejectAIEditOperation` resolution — without
+   * reloading the document, so the view and scroll position are preserved.
+   * Routes to whichever surface is active: the inline header/footer editor
+   * when one is being edited, otherwise the document body. Only edits that
+   * produce document changes are recorded; selection-only changes (scroll /
+   * locate) carry no steps and are never undone. Returns `false` when there
+   * is nothing to undo / redo.
+   *
+   * Ports upstream docx-editor `feat(react): accept/reject and undo/redo
+   * tracked changes via the editor ref` (ff971a7b): folio already exposes
+   * id-scoped accept/reject through `acceptAIEditOperation` /
+   * `rejectAIEditOperation`, so only the in-place undo/redo surface is new.
+   */
+  undo: () => boolean;
+  redo: () => boolean;
+  /**
+   * Scroll the editor viewport so the tracked-change marks belonging to the
+   * given `revisionIds` come into view, and select them. No-op when none of the
+   * revisions are present.
+   */
+  scrollToAIEditOperation: (revisionIds: number | readonly number[]) => boolean;
+  /**
+   * Scroll the editor viewport so the block referenced by `blockId` is in view,
+   * and place the selection inside it. Returns `false` when the block can't be
+   * resolved on the live document (e.g. it was edited away).
+   *
+   * When `snapshot` is supplied, ids resolve against it — required for review
+   * panel pending-suggestion navigation, because block ids are sequential and
+   * a freshly recomputed snapshot would re-number blocks after a structural
+   * accept (insertAfterBlock / deleteBlock). Without `snapshot`, falls back to
+   * a fresh-from-live-doc snapshot.
+   */
+  scrollToBlock: (blockId: string, snapshot?: FolioAIEditSnapshot) => boolean;
+  /**
+   * The tracked changes (insertions and deletions) present in the live
+   * document, read from the current ProseMirror `state.doc`. Empty array
+   * before the editor view mounts.
+   */
+  getTrackedChanges: () => FolioReviewChange[];
+  /**
+   * The comment anchors present in the live document, read from the current
+   * ProseMirror `state.doc`. Empty array before the editor view mounts.
+   */
+  getCommentAnchors: () => FolioCommentAnchor[];
+  /**
+   * The plain text of the current selection, or `""` when the editor has no
+   * view or the selection is collapsed.
+   */
+  getSelectionText: () => string;
+  /**
+   * The plain text of a single rendered page (1-based), joining each of its
+   * layout fragments with a newline. Returns `null` when the page number is
+   * out of range or the layout hasn't been computed yet.
+   */
+  getPageText: (page: number) => string | null;
+  /**
+   * List every block-level content control in the live document, filtered by
+   * tag / alias / id / sdtType. Returns the modeled SdtProperties projection
+   * plus a synthetic identifier so callers can address each control by
+   * insertion order even if tag/alias collide.
+   *
+   * IMPORTANT: the returned `pmPos` values are valid only for the document
+   * state at fetch time. After any mutation that changes earlier content's
+   * size (`setContentControlContent`, `setContentControlValue`,
+   * `removeContentControl`, etc.), later controls shift and stored
+   * `pmPos` values become stale. For batch-fill flows over duplicate-tag
+   * controls, either refetch via `getContentControls()` after each
+   * mutation, or address by stable `{ tag }` / `{ id }` / `{ alias }` so
+   * the lookup uses the document's current shape on every call.
+   */
+  getContentControls: (filter?: ContentControlFilter) => {
+    properties: SdtProperties; /** Index in the PM document tree, outer→inner. */
+    path: number[];
+    /**
+     * PM position of the control's open token in the SOURCE document state.
+     * Disambiguates duplicates within one snapshot, but does not survive
+     * mutations that resize earlier content — see `getContentControls`
+     * for the refetch / address-by-tag guidance.
+     */
+    pmPos: number;
+  }[];
+  /**
+   * Scroll to the first content control matching the filter and place the
+   * caret inside it. Returns false when no match is present.
+   */
+  scrollToContentControl: (filter: ContentControlFilter) => boolean;
+  /**
+   * Replace a control's inner content with plain text or pre-built block
+   * content. Locked controls throw `ContentControlLockedError` unless
+   * `{ force: true }` is passed. Writes go through a normal undoable
+   * transaction.
+   */
+  setContentControlContent: (filter: ContentControlFilter, input: SetContentControlContentInput, options?: {
+    force?: boolean;
+  }) => boolean;
+  /**
+   * Set a structured value on a typed control (dropdown / checkbox / date).
+   * Throws `ContentControlTypeError` when the input shape does not match the
+   * control's sdtType. Writes go through a normal undoable transaction.
+   */
+  setContentControlValue: (filter: ContentControlFilter, input: SetContentControlValueInput, options?: {
+    force?: boolean;
+  }) => boolean;
+  /**
+   * Remove a control. With `{ keepContent: true }` the inner blocks survive
+   * in-place; otherwise the wrapper and its children are dropped. Refuses to
+   * unwrap a `w15:repeatingSection` (would orphan its row items) unless
+   * `{ force: true }` is passed.
+   */
+  removeContentControl: (filter: ContentControlFilter, options?: {
+    keepContent?: boolean;
+    force?: boolean;
+  }) => boolean;
+};
+//#endregion
+//#region src/renderAsync.d.ts
+/** Framework-agnostic handle for an imperatively mounted editor instance. */
+type EditorHandle = {
+  /** Save the document and return the DOCX as a Blob. */save: () => Promise<Blob | null>; /** Get the current parsed document model. */
+  getDocument: () => Document | null; /** Focus the editor. */
+  focus: () => void; /** Unmount the editor and clean up. */
+  destroy: () => void;
+};
+/** React-specific handle with zoom and scroll helpers. */
+type DocxEditorHandle = EditorHandle & {
+  /** Set zoom level (1.0 = 100%). */setZoom: (zoom: number) => void; /** Scroll the visible pages to a raw ProseMirror document position. */
+  scrollToPosition: (pmPos: number) => void; /** Scroll the visible pages to a 1-indexed page number. */
+  scrollToPage: (pageNumber: number) => void;
+};
+/** Options for {@link renderAsync}. */
+type RenderAsyncOptions = Omit<DocxEditorProps, "documentBuffer" | "document"> & {
+  /** BCP-47 locale for bundled folio UI strings (default: `en`). */locale?: string;
+};
+/**
+ * Render a DOCX editor into a container element.
+ *
+ * Resolves once the document has parsed and the first `onChange` fires.
+ * Rejects if `onError` runs before that milestone.
+ */
+declare const renderAsync: (input: DocxInput, container: HTMLElement, options?: RenderAsyncOptions) => Promise<DocxEditorHandle>;
+//#endregion
+export { DocxEditorCollaboration as a, ToolbarProps as c, ColorPreset as d, FolioButtonProps as f, FontDefinition as g, OutlineItem as h, renderAsync as i, EditorMode as l, FolioUIProvider as m, EditorHandle as n, DocxEditorProps as o, FolioUIComponents as p, RenderAsyncOptions as r, DocxEditorRef as s, DocxEditorHandle as t, FontOption as u };