@sofereditor/react 0.1.0 → 0.3.0

package/dist/index.d.cts

@@ -1,5 +1,32 @@
-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';
+import { RefObject, JSX, ReactNode } from 'react';
+import { EditorDocument, EditorHistory, SerializedDocument, Selection, MarkName, MarkAttrs, BlockType, BlockAttrs, AlignValue, ListKind, PageSettings, TableLocation, TableRect, ImageEmbed, EmbedLoc, SerializedBlock, DeltaOp, Position } from '@sofereditor/core';
+
+/**
+ * Subconjunto mínimo da Awareness do y-protocols que o overlay usa. Tipar assim
+ * evita que `@sofereditor/react` dependa de `y-protocols` — o objeto vem de fora
+ * (de `useCollab().binding.awareness`) e é estruturalmente compatível.
+ */
+interface AwarenessLike {
+    clientID: number;
+    getStates(): Map<number, Record<string, unknown>>;
+    on(event: "change", cb: () => void): void;
+    off(event: "change", cb: () => void): void;
+    setLocalStateField(field: string, value: unknown): void;
+}
+interface RemoteCursorsOverlayProps {
+    rootRef: RefObject<HTMLDivElement>;
+    doc: EditorDocument;
+    awareness: AwarenessLike;
+    /** Muda a cada edição/repaginação → re-medir os carets remotos. */
+    revision?: unknown;
+}
+/**
+ * Desenha o caret + seleção + nome de cada usuário remoto sobre o conteúdo
+ * paginado. Posições remotas chegam via awareness (campo `cursor`, codificado
+ * com Y.RelativePosition pelo core) e são resolvidas para coordenadas DOM com
+ * o mesmo bridge da seleção local — ciente de fragmentação por página.
+ */
+declare function RemoteCursorsOverlay({ rootRef, doc, awareness, revision, }: RemoteCursorsOverlayProps): JSX.Element | null;
 
 /**
  * Sub-phase 3.2 — page layout with intra-paragraph fragmentation.
@@ -27,9 +54,16 @@ interface PageGeometry {
     marginBottom: number;
     marginLeft: number;
     marginRight: number;
+    /**
+     * Espaço adicional somado ao marginTop só na 1ª página. Útil para clientes
+     * que rendem um header fixo (timbrado, identificação) na pág 1 via
+     * `renderPageHeader` e não querem que esse espaço seja reservado nas demais.
+     * Quando omitido, todas as páginas têm a mesma `contentHeight`.
+     */
+    firstPageExtraTop?: number;
 }
 declare const A4_PAGE: PageGeometry;
-declare function contentHeight(g: PageGeometry): number;
+declare function contentHeight(g: PageGeometry, pageIndex?: number): number;
 declare function contentWidth(g: PageGeometry): number;
 interface BlockFragment {
     index: number;
@@ -44,12 +78,22 @@ interface TableRowFragment {
     /** First row NOT included (exclusive). */
     rowEnd: number;
 }
+interface ListItemRangeFragment {
+    /** 0, 1, 2... sequential fragment id within the list group. */
+    index: number;
+    /** First top-level item (level 0) included (inclusive). */
+    itemStart: number;
+    /** First top-level item (level 0) NOT included (exclusive). */
+    itemEnd: 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;
+    /** Set when this slot is an item-range fragment of an ordered/bullet list. */
+    listFragment?: ListItemRangeFragment;
 }
 interface PageEntry {
     slots: PageSlot[];
@@ -58,7 +102,19 @@ interface PageLayout {
     pages: PageEntry[];
 }
 declare function defaultPageLayout(topLevelCount: number): PageLayout;
-declare function usePageLayout(rootRef: RefObject<HTMLElement>, geometry: PageGeometry, topLevelCount: number, deps: ReadonlyArray<unknown>): PageLayout;
+type PaginationPhase = "measure" | "stable";
+interface PageLayoutResult {
+    layout: PageLayout;
+    /**
+     * "measure" between a deps change and the post-commit measurement; "stable"
+     * once the layout matches the rendered DOM. Consumers can hide the caret /
+     * suppress visible flashes during "measure" (the DOM is briefly in the
+     * unfragmented intermediate state and the native caret may jump to the start
+     * of the line before useLayoutEffect re-applies the model selection).
+     */
+    phase: PaginationPhase;
+}
+declare function usePageLayout(rootRef: RefObject<HTMLElement>, geometry: PageGeometry, topLevelCount: number, deps: ReadonlyArray<unknown>): PageLayoutResult;
 
 interface UseEditorOptions {
     document?: EditorDocument;
@@ -76,6 +132,8 @@ type PendingMarks = Partial<Record<MarkName, MarkAttrs[MarkName] | null>>;
 interface LinkRequest {
     initialHref: string;
     resolve: (href: string | null) => void;
+    /** Model selection captured when the link was requested (bug #6). */
+    selection: Selection;
 }
 interface PageConfigRequest {
     initial: PageSettings;
@@ -116,6 +174,8 @@ interface UseEditorResult {
     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;
+    setAlign: (value: AlignValue) => void;
+    getAlign: () => AlignValue | "mixed" | undefined;
     isListActive: (kind: ListKind) => boolean;
     toggleList: (kind: ListKind) => void;
     indentList: () => void;
@@ -173,6 +233,11 @@ interface UseEditorResult {
     mergeSelection: () => boolean;
     insertImage: (embed: ImageEmbed) => void;
     setImageAttrs: (blockIndex: number, offset: number, partial: Partial<ImageEmbed>, cellIndex?: number, newOffset?: number) => void;
+    /**
+     * Move a floating image embed from one anchor to another (re-anchor across
+     * blocks/pages) in a single transaction. No-op for inline embeds.
+     */
+    moveEmbedAnchor: (from: EmbedLoc, to: EmbedLoc, newOffsetX: number, newOffsetY: number) => void;
     /** Read a File (image) and insert it inline at the caret as a data-URL embed. */
     insertImageFromFile: (file: File) => Promise<void>;
     /**
@@ -215,8 +280,14 @@ interface EditorProps {
      * `"<n> / <total>"` centered. Pass `null` to omit.
      */
     renderPageFooter?: PageRenderProp | null;
+    /**
+     * Awareness do Yjs (de `useCollab().binding.awareness`). Quando presente,
+     * o editor publica a seleção local e desenha os cursores/seleções dos outros
+     * usuários (presença colaborativa). Omitir = sem cursores remotos.
+     */
+    awareness?: AwarenessLike;
 }
-declare function Editor({ editor: providedEditor, className, pageGeometry, renderPageHeader, renderPageFooter, }: EditorProps): JSX.Element;
+declare function Editor({ editor: providedEditor, className, pageGeometry, renderPageHeader, renderPageFooter, awareness, }: EditorProps): JSX.Element;
 
 /**
  * Modal dialog for entering a link URL. Replaces the bare `window.prompt`
@@ -339,6 +410,11 @@ declare function getCellElement(root: HTMLElement, blockIndex: number, cellIndex
  */
 declare function textOffsetWithin(container: HTMLElement, node: Node, offsetInNode: number): number;
 declare function readDomSelection(root: HTMLElement): Selection | null;
+interface DomPoint {
+    node: Node;
+    offset: number;
+}
+declare function locatePoint(root: HTMLElement, pos: Position): DomPoint | null;
 declare function selectionsEqual(a: Selection, b: Selection): boolean;
 /**
  * `true` when the selection is a rectangular table-cell range — both endpoints
@@ -350,4 +426,4 @@ declare function selectionsEqual(a: Selection, b: Selection): boolean;
 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 };
+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 PageLayoutResult, type PageRenderContext, type PageRenderProp, type PageSlot, type PaginationPhase, type PendingMarks, RemoteCursorsOverlay, type TableRowFragment, Toolbar, type ToolbarProps, type UseEditorOptions, type UseEditorResult, applyDomSelection, contentHeight, contentWidth, defaultPageLayout, deltaLength, findBlockIndex, getBlockElement, getCellElement, getFragmentForOffset, isTableRectSelection, locatePoint, readDomSelection, renderInline, selectionsEqual, sliceDelta, textOffsetWithin, useEditor, useEditorContext, usePageLayout, usePageSettings };

package/dist/index.d.ts

@@ -1,5 +1,32 @@
-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';
+import { RefObject, JSX, ReactNode } from 'react';
+import { EditorDocument, EditorHistory, SerializedDocument, Selection, MarkName, MarkAttrs, BlockType, BlockAttrs, AlignValue, ListKind, PageSettings, TableLocation, TableRect, ImageEmbed, EmbedLoc, SerializedBlock, DeltaOp, Position } from '@sofereditor/core';
+
+/**
+ * Subconjunto mínimo da Awareness do y-protocols que o overlay usa. Tipar assim
+ * evita que `@sofereditor/react` dependa de `y-protocols` — o objeto vem de fora
+ * (de `useCollab().binding.awareness`) e é estruturalmente compatível.
+ */
+interface AwarenessLike {
+    clientID: number;
+    getStates(): Map<number, Record<string, unknown>>;
+    on(event: "change", cb: () => void): void;
+    off(event: "change", cb: () => void): void;
+    setLocalStateField(field: string, value: unknown): void;
+}
+interface RemoteCursorsOverlayProps {
+    rootRef: RefObject<HTMLDivElement>;
+    doc: EditorDocument;
+    awareness: AwarenessLike;
+    /** Muda a cada edição/repaginação → re-medir os carets remotos. */
+    revision?: unknown;
+}
+/**
+ * Desenha o caret + seleção + nome de cada usuário remoto sobre o conteúdo
+ * paginado. Posições remotas chegam via awareness (campo `cursor`, codificado
+ * com Y.RelativePosition pelo core) e são resolvidas para coordenadas DOM com
+ * o mesmo bridge da seleção local — ciente de fragmentação por página.
+ */
+declare function RemoteCursorsOverlay({ rootRef, doc, awareness, revision, }: RemoteCursorsOverlayProps): JSX.Element | null;
 
 /**
  * Sub-phase 3.2 — page layout with intra-paragraph fragmentation.
@@ -27,9 +54,16 @@ interface PageGeometry {
     marginBottom: number;
     marginLeft: number;
     marginRight: number;
+    /**
+     * Espaço adicional somado ao marginTop só na 1ª página. Útil para clientes
+     * que rendem um header fixo (timbrado, identificação) na pág 1 via
+     * `renderPageHeader` e não querem que esse espaço seja reservado nas demais.
+     * Quando omitido, todas as páginas têm a mesma `contentHeight`.
+     */
+    firstPageExtraTop?: number;
 }
 declare const A4_PAGE: PageGeometry;
-declare function contentHeight(g: PageGeometry): number;
+declare function contentHeight(g: PageGeometry, pageIndex?: number): number;
 declare function contentWidth(g: PageGeometry): number;
 interface BlockFragment {
     index: number;
@@ -44,12 +78,22 @@ interface TableRowFragment {
     /** First row NOT included (exclusive). */
     rowEnd: number;
 }
+interface ListItemRangeFragment {
+    /** 0, 1, 2... sequential fragment id within the list group. */
+    index: number;
+    /** First top-level item (level 0) included (inclusive). */
+    itemStart: number;
+    /** First top-level item (level 0) NOT included (exclusive). */
+    itemEnd: 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;
+    /** Set when this slot is an item-range fragment of an ordered/bullet list. */
+    listFragment?: ListItemRangeFragment;
 }
 interface PageEntry {
     slots: PageSlot[];
@@ -58,7 +102,19 @@ interface PageLayout {
     pages: PageEntry[];
 }
 declare function defaultPageLayout(topLevelCount: number): PageLayout;
-declare function usePageLayout(rootRef: RefObject<HTMLElement>, geometry: PageGeometry, topLevelCount: number, deps: ReadonlyArray<unknown>): PageLayout;
+type PaginationPhase = "measure" | "stable";
+interface PageLayoutResult {
+    layout: PageLayout;
+    /**
+     * "measure" between a deps change and the post-commit measurement; "stable"
+     * once the layout matches the rendered DOM. Consumers can hide the caret /
+     * suppress visible flashes during "measure" (the DOM is briefly in the
+     * unfragmented intermediate state and the native caret may jump to the start
+     * of the line before useLayoutEffect re-applies the model selection).
+     */
+    phase: PaginationPhase;
+}
+declare function usePageLayout(rootRef: RefObject<HTMLElement>, geometry: PageGeometry, topLevelCount: number, deps: ReadonlyArray<unknown>): PageLayoutResult;
 
 interface UseEditorOptions {
     document?: EditorDocument;
@@ -76,6 +132,8 @@ type PendingMarks = Partial<Record<MarkName, MarkAttrs[MarkName] | null>>;
 interface LinkRequest {
     initialHref: string;
     resolve: (href: string | null) => void;
+    /** Model selection captured when the link was requested (bug #6). */
+    selection: Selection;
 }
 interface PageConfigRequest {
     initial: PageSettings;
@@ -116,6 +174,8 @@ interface UseEditorResult {
     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;
+    setAlign: (value: AlignValue) => void;
+    getAlign: () => AlignValue | "mixed" | undefined;
     isListActive: (kind: ListKind) => boolean;
     toggleList: (kind: ListKind) => void;
     indentList: () => void;
@@ -173,6 +233,11 @@ interface UseEditorResult {
     mergeSelection: () => boolean;
     insertImage: (embed: ImageEmbed) => void;
     setImageAttrs: (blockIndex: number, offset: number, partial: Partial<ImageEmbed>, cellIndex?: number, newOffset?: number) => void;
+    /**
+     * Move a floating image embed from one anchor to another (re-anchor across
+     * blocks/pages) in a single transaction. No-op for inline embeds.
+     */
+    moveEmbedAnchor: (from: EmbedLoc, to: EmbedLoc, newOffsetX: number, newOffsetY: number) => void;
     /** Read a File (image) and insert it inline at the caret as a data-URL embed. */
     insertImageFromFile: (file: File) => Promise<void>;
     /**
@@ -215,8 +280,14 @@ interface EditorProps {
      * `"<n> / <total>"` centered. Pass `null` to omit.
      */
     renderPageFooter?: PageRenderProp | null;
+    /**
+     * Awareness do Yjs (de `useCollab().binding.awareness`). Quando presente,
+     * o editor publica a seleção local e desenha os cursores/seleções dos outros
+     * usuários (presença colaborativa). Omitir = sem cursores remotos.
+     */
+    awareness?: AwarenessLike;
 }
-declare function Editor({ editor: providedEditor, className, pageGeometry, renderPageHeader, renderPageFooter, }: EditorProps): JSX.Element;
+declare function Editor({ editor: providedEditor, className, pageGeometry, renderPageHeader, renderPageFooter, awareness, }: EditorProps): JSX.Element;
 
 /**
  * Modal dialog for entering a link URL. Replaces the bare `window.prompt`
@@ -339,6 +410,11 @@ declare function getCellElement(root: HTMLElement, blockIndex: number, cellIndex
  */
 declare function textOffsetWithin(container: HTMLElement, node: Node, offsetInNode: number): number;
 declare function readDomSelection(root: HTMLElement): Selection | null;
+interface DomPoint {
+    node: Node;
+    offset: number;
+}
+declare function locatePoint(root: HTMLElement, pos: Position): DomPoint | null;
 declare function selectionsEqual(a: Selection, b: Selection): boolean;
 /**
  * `true` when the selection is a rectangular table-cell range — both endpoints
@@ -350,4 +426,4 @@ declare function selectionsEqual(a: Selection, b: Selection): boolean;
 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 };
+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 PageLayoutResult, type PageRenderContext, type PageRenderProp, type PageSlot, type PaginationPhase, type PendingMarks, RemoteCursorsOverlay, type TableRowFragment, Toolbar, type ToolbarProps, type UseEditorOptions, type UseEditorResult, applyDomSelection, contentHeight, contentWidth, defaultPageLayout, deltaLength, findBlockIndex, getBlockElement, getCellElement, getFragmentForOffset, isTableRectSelection, locatePoint, readDomSelection, renderInline, selectionsEqual, sliceDelta, textOffsetWithin, useEditor, useEditorContext, usePageLayout, usePageSettings };