@sofereditor/react 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,353 @@
+import { RefObject, ReactNode, JSX } from 'react';
+import { EditorDocument, EditorHistory, SerializedDocument, Selection, MarkName, MarkAttrs, BlockType, BlockAttrs, ListKind, PageSettings, TableLocation, TableRect, ImageEmbed, SerializedBlock, DeltaOp } from '@sofereditor/core';
+
+/**
+ * Sub-phase 3.2 — page layout with intra-paragraph fragmentation.
+ *
+ * Two-phase render cycle:
+ *   1. "measure" phase: editor renders with the default (unfragmented) layout
+ *      — every top-level on page 1. After the DOM commits, `usePageLayout`
+ *      reads each top-level's geometry, runs `computeLayout`, and sets the
+ *      real layout (with page splits and fragment offsets).
+ *   2. "stable" phase: editor renders the real layout. No further measurement
+ *      until `deps` change (typically `[topLevels]`), at which point we go
+ *      back to step 1.
+ *
+ * Fragmentation only applies to "fragmentable" top-levels (paragraph, heading,
+ * blockquote — single Y.Text blocks). List groups and code blocks are placed
+ * atomically: if they don't fit they jump to the next page and bleed if larger
+ * than a page.
+ */
+interface PageGeometry {
+    /** Page width in CSS px (A4 @ 96dpi = ~794). */
+    width: number;
+    /** Page height in CSS px (A4 @ 96dpi = ~1123). */
+    height: number;
+    marginTop: number;
+    marginBottom: number;
+    marginLeft: number;
+    marginRight: number;
+}
+declare const A4_PAGE: PageGeometry;
+declare function contentHeight(g: PageGeometry): number;
+declare function contentWidth(g: PageGeometry): number;
+interface BlockFragment {
+    index: number;
+    start: number;
+    end: number;
+}
+interface TableRowFragment {
+    /** 0, 1, 2... sequential fragment id within the table. */
+    index: number;
+    /** First row included (inclusive). */
+    rowStart: number;
+    /** First row NOT included (exclusive). */
+    rowEnd: number;
+}
+interface PageSlot {
+    topLevelIndex: number;
+    /** Set when this slot represents a paragraph/heading/blockquote line-level fragment. */
+    fragment?: BlockFragment;
+    /** Set when this slot is a row-range fragment of a table (Sub-phase 4.6). */
+    tableFragment?: TableRowFragment;
+}
+interface PageEntry {
+    slots: PageSlot[];
+}
+interface PageLayout {
+    pages: PageEntry[];
+}
+declare function defaultPageLayout(topLevelCount: number): PageLayout;
+declare function usePageLayout(rootRef: RefObject<HTMLElement>, geometry: PageGeometry, topLevelCount: number, deps: ReadonlyArray<unknown>): PageLayout;
+
+interface UseEditorOptions {
+    document?: EditorDocument;
+    /**
+     * Quando definido, `insertImageFromFile` chama esta função pra obter a URL
+     * final em vez de embutir o arquivo como data URL base64 no Y.Doc.
+     *
+     * Use isto quando o app tem storage externo (S3, Azure Blob, etc.) e não quer
+     * inflar o documento com imagens base64. O componente `<Editor>` propaga o
+     * mesmo upload para paste/drop/file picker.
+     */
+    uploadImage?: (file: File) => Promise<string>;
+}
+type PendingMarks = Partial<Record<MarkName, MarkAttrs[MarkName] | null>>;
+interface LinkRequest {
+    initialHref: string;
+    resolve: (href: string | null) => void;
+}
+interface PageConfigRequest {
+    initial: PageSettings;
+    resolve: (applied: boolean) => void;
+}
+type CaptionAlign = "left" | "center" | "right";
+interface ImageCaptionResult {
+    caption: string;
+    align: CaptionAlign;
+}
+interface ImageCaptionRequest {
+    initialCaption: string;
+    initialAlign: CaptionAlign;
+    /**
+     * Resolves with the new caption + alignment, or null on cancel. An empty
+     * `caption` string means "remove caption" (align is ignored in that case).
+     */
+    resolve: (result: ImageCaptionResult | null) => void;
+}
+interface UseEditorResult {
+    doc: EditorDocument;
+    history: EditorHistory;
+    /** Snapshot of the model, re-computed on every Y.js update. */
+    snapshot: SerializedDocument;
+    /** Current model selection. Use `setSelection` to move the caret. */
+    selection: Selection;
+    setSelection: (sel: Selection) => void;
+    /** Stable getter — commands read this to know where the caret is. */
+    getSelection: () => Selection;
+    isMarkActive: (name: MarkName, value?: MarkAttrs[MarkName]) => boolean;
+    getActiveMarks: () => Partial<Record<MarkName, MarkAttrs[MarkName] | "mixed">>;
+    toggleMark: (name: MarkName, value?: MarkAttrs[MarkName]) => void;
+    setMark: (name: MarkName, value: MarkAttrs[MarkName]) => void;
+    removeMark: (name: MarkName) => void;
+    /** Returns the type of the focus block (or "mixed" when the selection covers heterogeneous blocks). */
+    getBlockType: () => BlockType | "mixed";
+    /** Returns one block attribute at the focus block, or "mixed" when not uniform across the selection. */
+    getBlockAttr: <K extends keyof BlockAttrs>(key: K) => BlockAttrs[K] | "mixed" | undefined;
+    setBlockType: (type: BlockType, attrs?: BlockAttrs) => void;
+    setBlockAttr: <K extends keyof BlockAttrs>(key: K, value: BlockAttrs[K] | null) => void;
+    isListActive: (kind: ListKind) => boolean;
+    toggleList: (kind: ListKind) => void;
+    indentList: () => void;
+    dedentList: () => void;
+    /** Returns true when handled (current block is a listItem); false to fall back to insertParagraph. */
+    splitListItem: () => boolean;
+    /** Marks queued for the next `insertText` (e.g. user pressed Cmd+B with a collapsed caret). */
+    pendingMarks: PendingMarks;
+    /** Consumed by the input layer right before calling `insertText`. */
+    consumePendingMarks: () => PendingMarks | undefined;
+    linkRequest: LinkRequest | null;
+    /** Open the link dialog; resolves with the entered href, empty string to remove, or null on cancel. */
+    requestLink: (initialHref?: string) => Promise<string | null>;
+    /** Called by the LinkDialog itself when the user submits or cancels. */
+    resolveLinkRequest: (href: string | null) => void;
+    /** Reactive page settings snapshot (re-renders when the Y.Doc docSettings changes). */
+    pageSettings: PageSettings;
+    /** Merge a partial PageSettings into the Y.Doc. Not undoable. */
+    setPageSettings: (partial: Partial<PageSettings>) => void;
+    /** Page-config dialog request (null when closed). */
+    pageConfigRequest: PageConfigRequest | null;
+    /** Open the page-config dialog; resolves true on apply, false on cancel. */
+    requestPageConfig: () => Promise<boolean>;
+    /** Resolver called by `<PageConfigDialog>` on apply/cancel. */
+    resolvePageConfigRequest: (applied: boolean) => void;
+    imageCaptionRequest: ImageCaptionRequest | null;
+    /** Open the image-caption dialog with the current caption + alignment pre-filled. */
+    requestImageCaption: (initialCaption?: string, initialAlign?: CaptionAlign) => Promise<ImageCaptionResult | null>;
+    /** Resolver called by `<ImageCaptionDialog>` on apply/cancel. */
+    resolveImageCaptionRequest: (result: ImageCaptionResult | null) => void;
+    /** True iff the focus position lies inside a table cell. */
+    isInTable: () => boolean;
+    /** Returns `{blockIndex, row, col}` for the focus position, or null when outside a table. */
+    getTableLocation: () => TableLocation | null;
+    insertTable: (rows: number, cols: number) => void;
+    /** Removes the table at `blockIndex`. Defaults to the current focus table. */
+    deleteTable: (blockIndex?: number) => void;
+    insertRowAbove: () => void;
+    insertRowBelow: () => void;
+    deleteCurrentRow: () => void;
+    insertColumnLeft: () => void;
+    insertColumnRight: () => void;
+    deleteCurrentColumn: () => void;
+    moveToNextCell: () => void;
+    moveToPrevCell: () => void;
+    mergeRight: () => boolean;
+    mergeDown: () => boolean;
+    splitCell: () => boolean;
+    setColumnWidth: (blockIndex: number, col: number, widthPx: number) => void;
+    /** Returns the table rectangle if the current selection is a multi-cell range, else null. */
+    getTableRect: () => TableRect | null;
+    /** True when there's a rectangular table-cell selection. */
+    hasTableRectSelection: () => boolean;
+    /** Merge every cell in the rectangular selection. Returns true on success. */
+    mergeSelection: () => boolean;
+    insertImage: (embed: ImageEmbed) => void;
+    setImageAttrs: (blockIndex: number, offset: number, partial: Partial<ImageEmbed>, cellIndex?: number, newOffset?: number) => void;
+    /** Read a File (image) and insert it inline at the caret as a data-URL embed. */
+    insertImageFromFile: (file: File) => Promise<void>;
+    /**
+     * Returns the embed currently selected (single 1-char range over an image),
+     * or null when no embed is solely selected.
+     */
+    getSelectedEmbed: () => {
+        blockIndex: number;
+        offset: number;
+        cellIndex?: number;
+        embed: ImageEmbed;
+    } | null;
+}
+declare function useEditor(opts?: UseEditorOptions): UseEditorResult;
+
+interface PageRenderContext {
+    pageNumber: number;
+    pageCount: number;
+}
+type PageRenderProp = (ctx: PageRenderContext) => ReactNode;
+interface EditorProps {
+    editor?: UseEditorResult;
+    className?: string;
+    /**
+     * Page geometry override. When **omitted**, the editor reads page settings
+     * from `editor.doc` (the `docSettings` Y.Map populated via `setPageSettings`
+     * or `import-docx`). When **set**, this value wins for rendering — but is
+     * NOT written back to the Y.Doc (view-only override; useful when the host
+     * app must pin a size regardless of doc state, e.g. a prova generator).
+     * Pass **null** to disable pagination entirely (flat flow).
+     */
+    pageGeometry?: PageGeometry | null;
+    /**
+     * Custom page header. Receives `{ pageNumber, pageCount }` and renders inside
+     * the top margin of every page (above the content area). Pass `null` to omit.
+     */
+    renderPageHeader?: PageRenderProp | null;
+    /**
+     * Custom page footer. Receives `{ pageNumber, pageCount }`. Defaults to
+     * `"<n> / <total>"` centered. Pass `null` to omit.
+     */
+    renderPageFooter?: PageRenderProp | null;
+}
+declare function Editor({ editor: providedEditor, className, pageGeometry, renderPageHeader, renderPageFooter, }: EditorProps): JSX.Element;
+
+/**
+ * Modal dialog for entering a link URL. Replaces the bare `window.prompt`
+ * previously wired to Cmd+K and the toolbar link button. Renders only when
+ * `editor.linkRequest` is set; consumes that state via `resolveLinkRequest`.
+ *
+ * Uses the native `<dialog>` element for focus trapping, ESC handling, and the
+ * browser-provided backdrop.
+ */
+declare function LinkDialog(): JSX.Element | null;
+
+/**
+ * Modal dialog to configure page size and margins. Mirrors `LinkDialog` —
+ * driven by `editor.pageConfigRequest`. On apply, writes via
+ * `editor.setPageSettings`; on cancel, no write.
+ */
+declare function PageConfigDialog(): JSX.Element | null;
+
+/**
+ * Modal dialog for entering an image caption. Mirrors `LinkDialog` — driven by
+ * `editor.imageCaptionRequest`. Empty input is treated as "remove caption".
+ *
+ * The only configurable property besides the text itself is the caption's
+ * horizontal alignment (left / center / right). Word-style figure-caption
+ * controls stop here intentionally — see `ImageEmbed.captionAlign`.
+ */
+declare function ImageCaptionDialog(): JSX.Element | null;
+
+/**
+ * Reactive snapshot of an `EditorDocument`'s page settings. Re-renders the
+ * component when `docSettings` changes (either locally via `setPageSettings`
+ * or remotely via Y.js sync).
+ *
+ * Caches the snapshot reference to satisfy `useSyncExternalStore`'s stable-
+ * identity requirement — `getPageSettings` returns a fresh object each call,
+ * which would loop the store forever without this caching.
+ */
+declare function usePageSettings(doc: EditorDocument): PageSettings;
+
+interface NodeViewFragment {
+    index: number;
+    start: number;
+    end: number;
+}
+interface NodeViewProps {
+    block: SerializedBlock;
+    index: number;
+    /** Optional nested content. Used by `listItem` to host the nested <ol>/<ul>. */
+    children?: ReactNode;
+    /** Optional fragment slice — when present, the rendered DOM covers only chars [start, end). */
+    fragment?: NodeViewFragment;
+    /**
+     * Optional table-row fragmentation slice for Sub-phase 4.6. When set, only
+     * the rows in `[rowStart, rowEnd)` are rendered, and the resize overlay is
+     * suppressed except on the FIRST fragment.
+     */
+    tableFragment?: {
+        index: number;
+        rowStart: number;
+        rowEnd: number;
+    };
+}
+declare function NodeView({ block, index, children, fragment, tableFragment }: NodeViewProps): JSX.Element;
+
+/**
+ * Convert a Y.Text delta into ReactNodes.
+ *
+ * Wrap order (innermost → outermost): bold → italic → underline → strike → font/color span → link.
+ * Semantic tags carry bold/italic/underline/strike; color and fonts go on a styled <span>.
+ *
+ * Keys are stable on `${blockIndex}-${runningOffset}` so React reconciliation
+ * survives split/merge of runs under collaboration.
+ */
+declare function renderInline(delta: DeltaOp[], keyPrefix: number | string): ReactNode;
+
+interface EditorProviderProps {
+    editor: UseEditorResult;
+    children: ReactNode;
+}
+declare function EditorProvider({ editor, children }: EditorProviderProps): JSX.Element;
+declare function useEditorContext(): UseEditorResult;
+
+interface ToolbarProps {
+    className?: string;
+}
+declare function Toolbar({ className }: ToolbarProps): JSX.Element;
+
+/** Total number of inserted characters. Embeds (non-string inserts) count as 1. */
+declare function deltaLength(delta: DeltaOp[]): number;
+/**
+ * Return the subset of `delta` covering `[start, end)` characters. Attributes
+ * are preserved on each intersecting op. Embeds are atomic length-1 ops:
+ * included whole if their slot intersects the range.
+ */
+declare function sliceDelta(delta: DeltaOp[], start: number, end: number): DeltaOp[];
+
+declare function findBlockIndex(node: Node, root: HTMLElement): number | null;
+/**
+ * Returns the first DOM element for `blockIndex`. For a fragmented block this
+ * is the first fragment. Prefer `getFragmentForOffset` when you need the
+ * fragment that contains a specific offset.
+ */
+declare function getBlockElement(root: HTMLElement, blockIndex: number): HTMLElement | null;
+/**
+ * Returns the DOM element responsible for `offset` inside `blockIndex`.
+ * - Unfragmented block (single element): returns it.
+ * - Fragmented block: returns the fragment whose `[start, end)` covers `offset`.
+ *   For the end-of-block offset, returns the last fragment.
+ */
+declare function getFragmentForOffset(root: HTMLElement, blockIndex: number, offset: number): HTMLElement | null;
+/**
+ * Returns the `<td>` element for `(blockIndex, cellIndex)`. Tables are
+ * unfragmented in 4.1 so there's at most one block element to search inside.
+ */
+declare function getCellElement(root: HTMLElement, blockIndex: number, cellIndex: number): HTMLElement | null;
+/**
+ * Sum length of all text nodes plus 1 for each image embed inside `container`,
+ * up to the boundary defined by `(node, offsetInNode)`. Mirrors how the model
+ * counts characters: embeds are atomic length-1 inserts.
+ */
+declare function textOffsetWithin(container: HTMLElement, node: Node, offsetInNode: number): number;
+declare function readDomSelection(root: HTMLElement): Selection | null;
+declare function selectionsEqual(a: Selection, b: Selection): boolean;
+/**
+ * `true` when the selection is a rectangular table-cell range — both endpoints
+ * inside cells of the same block, addressing different cells. The visual
+ * highlight comes from CSS classes applied by `<TableView>`; we deliberately
+ * leave the native DOM selection empty so the browser doesn't draw a confusing
+ * cross-`<td>` range.
+ */
+declare function isTableRectSelection(sel: Selection): boolean;
+declare function applyDomSelection(root: HTMLElement, modelSel: Selection): void;
+
+export { A4_PAGE, type BlockFragment, type CaptionAlign, Editor, type EditorProps, EditorProvider, type EditorProviderProps, ImageCaptionDialog, type ImageCaptionRequest, type ImageCaptionResult, LinkDialog, type LinkRequest, NodeView, type NodeViewFragment, PageConfigDialog, type PageConfigRequest, type PageEntry, type PageGeometry, type PageLayout, type PageRenderContext, type PageRenderProp, type PageSlot, type PendingMarks, type TableRowFragment, Toolbar, type ToolbarProps, type UseEditorOptions, type UseEditorResult, applyDomSelection, contentHeight, contentWidth, defaultPageLayout, deltaLength, findBlockIndex, getBlockElement, getCellElement, getFragmentForOffset, isTableRectSelection, readDomSelection, renderInline, selectionsEqual, sliceDelta, textOffsetWithin, useEditor, useEditorContext, usePageLayout, usePageSettings };