@sofereditor/react 0.2.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.
@@ -105,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;
@@ -145,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;
@@ -202,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>;
     /**
@@ -244,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`
@@ -368,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
@@ -379,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 PageLayoutResult, type PageRenderContext, type PageRenderProp, type PageSlot, type PaginationPhase, 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.
@@ -105,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;
@@ -145,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;
@@ -202,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>;
     /**
@@ -244,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`
@@ -368,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
@@ -379,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 PageLayoutResult, type PageRenderContext, type PageRenderProp, type PageSlot, type PaginationPhase, 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 };