@sofereditor/core 0.2.0 → 0.3.0

package/dist/index.d.cts

@@ -144,6 +144,8 @@ interface CellAttrs {
      * scheme — covered cells are placeholders, not gaps.
      */
     covered?: true;
+    /** Alinhamento horizontal do texto da célula. Mesmos valores de bloco. */
+    align?: AlignValue;
 }
 interface Position {
     blockIndex: number;
@@ -253,6 +255,8 @@ interface SerializedCell {
     attrs: CellAttrs;
 }
 interface SerializedBlock {
+    /** Id estável do bloco (cursores colaborativos / keying). Ausente em docs antigos. */
+    id?: string;
     type: BlockType;
     /** Plain concatenated text (no marks). Kept for ergonomic equality checks. */
     text: string;
@@ -290,6 +294,15 @@ declare const BLOCK_SPECS: Record<BlockType, BlockSpec>;
 declare function isKnownBlockType(t: string): t is BlockType;
 declare function defaultAttrsFor(type: BlockType): BlockAttrs;
 
+/**
+ * Gera um id estável de bloco. Usado para ancorar cursores colaborativos
+ * remotos (fallback) e para keying estável no overlay. Persistido no Y.Map do
+ * bloco, então sobrevive a reload (binário Yjs). Docs antigos não têm — os
+ * helpers de cursor lidam com a ausência (caem na RelativePosition).
+ */
+declare function newBlockId(): string;
+/** Lê o id de um bloco Y.Map (undefined em docs antigos sem id). */
+declare function getBlockId(block: Y.Map<unknown>): string | undefined;
 /**
  * Y.js-backed document.
  *
@@ -382,6 +395,23 @@ declare function createCell(attrs?: CellAttrs): Y.Map<unknown>;
 /** Coerce a `rowspan`/`colspan` attribute value into a positive integer. */
 declare function spanOf(value: unknown): number;
 
+interface EncodedCursorPoint {
+    /** base64 de Y.encodeRelativePosition — rastreia o caractere exato. */
+    rel: string;
+    /** Fallback: id do bloco original (ancora no início se o char sumiu). */
+    blockId?: string;
+    /** Fallback: célula da tabela, se aplicável. */
+    cellIndex?: number;
+}
+interface EncodedCursor {
+    anchor: EncodedCursorPoint;
+    focus: EncodedCursorPoint;
+}
+/** Codifica a seleção local em um descritor portável (para o awareness). */
+declare function encodeSelection(doc: EditorDocument, sel: Selection): EncodedCursor | null;
+/** Decodifica um descritor remoto para uma seleção absoluta no doc atual. */
+declare function decodeSelection(doc: EditorDocument, enc: EncodedCursor): Selection | null;
+
 declare function isCollapsed(sel: Selection): boolean;
 declare function positionsEqual(a: Position, b: Position): boolean;
 declare function comparePositions(a: Position, b: Position): number;
@@ -397,6 +427,12 @@ declare function collapsedSelection(pos: Position): Selection;
  */
 declare function sameTextRun(a: Position, b: Position): boolean;
 
+/**
+ * Attributes object that explicitly clears every mark (sets each to `null`).
+ * Spread your desired marks on top to insert text carrying EXACTLY those marks,
+ * overriding any formatting Y.Text would otherwise inherit from an adjacent run.
+ */
+declare const CLEAR_ALL_MARKS: Record<string, null>;
 /**
  * Returns the marks observed across `[start, end)`. For each mark name encountered:
  *   - if every covered character has the same value, returns that value
@@ -412,6 +448,28 @@ declare function deltaLength(delta: DeltaOp[]): number;
  */
 declare function sliceDelta(delta: DeltaOp[], start: number, end: number): DeltaOp[];
 
+/** MIME custom que carrega o slice serializado no clipboard. */
+declare const SOFER_MIME = "application/x-sofer-slice";
+interface ClipboardSlice {
+    /** 1..n blocos; cada delta carrega marks + embeds de imagem. */
+    blocks: SerializedBlock[];
+    /** 1º bloco é fragmento parcial → mescla inline no alvo da colagem. */
+    openStart: boolean;
+    /** último bloco é fragmento parcial → conteúdo após o caret continua nele. */
+    openEnd: boolean;
+}
+/**
+ * Lê a seleção e produz um ClipboardSlice, ou null se:
+ * - colapsada; - âncora/foco em células diferentes; - multi-bloco com tabela.
+ */
+declare function serializeSelection(doc: EditorDocument, sel: Selection): ClipboardSlice | null;
+/** Fallback texto puro: textos dos blocos unidos por "\n". */
+declare function sliceToText(slice: ClipboardSlice): string;
+/** Achata o slice num único delta inline (para colar dentro de uma célula).
+ *  Fronteiras de bloco viram quebra de linha "\n" (células renderizam pre-wrap),
+ *  para não grudar palavras de parágrafos distintos. */
+declare function sliceToInlineDelta(slice: ClipboardSlice): DeltaOp[];
+
 declare const COMMAND_ORIGIN: unique symbol;
 interface CommandContext {
     doc: EditorDocument;
@@ -455,6 +513,26 @@ declare function setBlockType(ctx: CommandContext, type: BlockType, attrs?: Bloc
  * Passing `value === null` deletes the key.
  */
 declare function setBlockAttr<K extends keyof BlockAttrs>(ctx: CommandContext, key: K, value: BlockAttrs[K] | null): void;
+/**
+ * Set a single attribute on the table cell(s) under the selection.
+ * - Caret numa única célula → essa célula (tableRectSelection retorna null
+ *   para seleção colapsada (ou âncora/foco no mesmo owner), então usamos
+ *   a célula focada (redirecionada ao owner real).
+ * - Seleção retangular de várias células → todas as células reais do rect.
+ * Células `covered` são puladas. `value === null` apaga a key.
+ * No-op se a seleção não estiver dentro de uma tabela.
+ */
+declare function setCellAttr<K extends keyof CellAttrs>(ctx: CommandContext, key: K, value: CellAttrs[K] | null): void;
+/** Delete the current selection range and collapse the caret. Used by cut. */
+declare function deleteSelection(ctx: CommandContext): void;
+/**
+ * Replace the current selection with a clipboard slice (A1).
+ * - Single-block slice → inline splice (Dhead + S0 + Dtail), target keeps its type.
+ * - Multi-block slice → openStart merges S0 inline; middle/last blocks inserted
+ *   discretely; openEnd appends the post-caret tail onto the last pasted block.
+ * - Target inside a table cell → slice flattened to inline (no block structure).
+ */
+declare function insertSlice(ctx: CommandContext, slice: ClipboardSlice): void;
 /**
  * Convert every block in the selection to/from a `listItem` of `kind`.
  * If every covered block is already a `listItem` of `kind` → convert them all to paragraphs.
@@ -623,6 +701,24 @@ declare function insertImage(ctx: CommandContext, embed: ImageEmbed): void;
  * around it (CSS float only flows text that comes AFTER the float in DOM order).
  */
 declare function setImageAttrs(ctx: CommandContext, blockIndex: number, embedOffset: number, partial: Partial<ImageEmbed>, cellIndex?: number, newOffset?: number): void;
+/** Location of an embed in the model (block or table cell). */
+interface EmbedLoc {
+    blockIndex: number;
+    offset: number;
+    cellIndex?: number;
+}
+/**
+ * Move a floating image embed from `from` to `to` in a SINGLE Y.Doc
+ * transaction, applying new positional offsets. Atomic delete+insert keeps the
+ * CRDT consistent for collab peers and coalesces into one undo step.
+ *
+ * Guard: only non-inline (re-anchorable) image embeds are moved; everything
+ * else is a no-op. When `from` and `to` resolve to the SAME Y.Text, the insert
+ * index is adjusted for the prior delete (mirrors `setImageAttrs`'s clamp at
+ * lines 1709-1714). Sets the selection to the embed's new 1-char home so the
+ * resize overlay stays attached.
+ */
+declare function moveEmbedAnchor(ctx: CommandContext, from: EmbedLoc, to: EmbedLoc, newOffsetX: number, newOffsetY: number): void;
 declare function isCommandOrigin(origin: unknown): boolean;
 declare const TRACKED_ORIGINS: Set<unknown>;
 
@@ -634,4 +730,4 @@ declare class EditorHistory {
     destroy(): void;
 }
 
-export { type AlignValue, BLOCK_SPECS, type BlockAttrs, type BlockType, COMMAND_ORIGIN, type CellAttrs, type CommandContext, type CommentAttr, DEFAULT_PAGE_SETTINGS, type DeltaOp, type DirValue, EditorDocument, EditorHistory, type ImageEmbed, type ImageLayout, type InsertContent, type LegacySerializedDocument, type LinkAttr, type ListKind, type ListStyleType, MARGIN_PRESETS, MAX_LIST_LEVEL, type MarkAttrs, type MarkName, type MarkValue, PAGE_PRESETS, type PagePreset, type PageSettings, type Position, type Selection, type SerializedBlock, type SerializedCell, type SerializedDocument, TRACKED_ORIGINS, type TableLocation, type TableRect, cellsInRect, clearRectCells, collapsedSelection, comparePositions, createBlock, createCell, createTableBlock, dedentList, defaultAttrsFor, deleteBackward, deleteForward, deleteTable, deleteTableColumn, deleteTableRow, deltaLength, detectPreset, expandTableRect, getMarksInRange, indentList, insertImage, insertParagraph, insertTable, insertTableColumn, insertTableRow, insertText, isCollapsed, isCommandOrigin, isImageEmbed, isKnownBlockType, isLegacySerializedDocument, isMarkUniformInRange, mergeDown, mergeRight, mergeSelection, mmToPx, moveToNextCell, moveToPrevCell, orderedRange, positionsEqual, pxToMm, removeMark, sameTextRun, setBlockAttr, setBlockType, setColumnWidth, setImageAttrs, setMark, sliceDelta, spanOf, splitCell, splitListItem, tableLocationOf, tableRectSelection, toggleList, toggleMark, withDefaults };
+export { type AlignValue, BLOCK_SPECS, type BlockAttrs, type BlockType, CLEAR_ALL_MARKS, COMMAND_ORIGIN, type CellAttrs, type ClipboardSlice, type CommandContext, type CommentAttr, DEFAULT_PAGE_SETTINGS, type DeltaOp, type DirValue, EditorDocument, EditorHistory, type EmbedLoc, type EncodedCursor, type EncodedCursorPoint, type ImageEmbed, type ImageLayout, type InsertContent, type LegacySerializedDocument, type LinkAttr, type ListKind, type ListStyleType, MARGIN_PRESETS, MAX_LIST_LEVEL, type MarkAttrs, type MarkName, type MarkValue, PAGE_PRESETS, type PagePreset, type PageSettings, type Position, SOFER_MIME, type Selection, type SerializedBlock, type SerializedCell, type SerializedDocument, TRACKED_ORIGINS, type TableLocation, type TableRect, cellsInRect, clearRectCells, collapsedSelection, comparePositions, createBlock, createCell, createTableBlock, decodeSelection, dedentList, defaultAttrsFor, deleteBackward, deleteForward, deleteSelection, deleteTable, deleteTableColumn, deleteTableRow, deltaLength, detectPreset, encodeSelection, expandTableRect, getBlockId, getMarksInRange, indentList, insertImage, insertParagraph, insertSlice, insertTable, insertTableColumn, insertTableRow, insertText, isCollapsed, isCommandOrigin, isImageEmbed, isKnownBlockType, isLegacySerializedDocument, isMarkUniformInRange, mergeDown, mergeRight, mergeSelection, mmToPx, moveEmbedAnchor, moveToNextCell, moveToPrevCell, newBlockId, orderedRange, positionsEqual, pxToMm, removeMark, sameTextRun, serializeSelection, setBlockAttr, setBlockType, setCellAttr, setColumnWidth, setImageAttrs, setMark, sliceDelta, sliceToInlineDelta, sliceToText, spanOf, splitCell, splitListItem, tableLocationOf, tableRectSelection, toggleList, toggleMark, withDefaults };

package/dist/index.d.ts

@@ -144,6 +144,8 @@ interface CellAttrs {
      * scheme — covered cells are placeholders, not gaps.
      */
     covered?: true;
+    /** Alinhamento horizontal do texto da célula. Mesmos valores de bloco. */
+    align?: AlignValue;
 }
 interface Position {
     blockIndex: number;
@@ -253,6 +255,8 @@ interface SerializedCell {
     attrs: CellAttrs;
 }
 interface SerializedBlock {
+    /** Id estável do bloco (cursores colaborativos / keying). Ausente em docs antigos. */
+    id?: string;
     type: BlockType;
     /** Plain concatenated text (no marks). Kept for ergonomic equality checks. */
     text: string;
@@ -290,6 +294,15 @@ declare const BLOCK_SPECS: Record<BlockType, BlockSpec>;
 declare function isKnownBlockType(t: string): t is BlockType;
 declare function defaultAttrsFor(type: BlockType): BlockAttrs;
 
+/**
+ * Gera um id estável de bloco. Usado para ancorar cursores colaborativos
+ * remotos (fallback) e para keying estável no overlay. Persistido no Y.Map do
+ * bloco, então sobrevive a reload (binário Yjs). Docs antigos não têm — os
+ * helpers de cursor lidam com a ausência (caem na RelativePosition).
+ */
+declare function newBlockId(): string;
+/** Lê o id de um bloco Y.Map (undefined em docs antigos sem id). */
+declare function getBlockId(block: Y.Map<unknown>): string | undefined;
 /**
  * Y.js-backed document.
  *
@@ -382,6 +395,23 @@ declare function createCell(attrs?: CellAttrs): Y.Map<unknown>;
 /** Coerce a `rowspan`/`colspan` attribute value into a positive integer. */
 declare function spanOf(value: unknown): number;
 
+interface EncodedCursorPoint {
+    /** base64 de Y.encodeRelativePosition — rastreia o caractere exato. */
+    rel: string;
+    /** Fallback: id do bloco original (ancora no início se o char sumiu). */
+    blockId?: string;
+    /** Fallback: célula da tabela, se aplicável. */
+    cellIndex?: number;
+}
+interface EncodedCursor {
+    anchor: EncodedCursorPoint;
+    focus: EncodedCursorPoint;
+}
+/** Codifica a seleção local em um descritor portável (para o awareness). */
+declare function encodeSelection(doc: EditorDocument, sel: Selection): EncodedCursor | null;
+/** Decodifica um descritor remoto para uma seleção absoluta no doc atual. */
+declare function decodeSelection(doc: EditorDocument, enc: EncodedCursor): Selection | null;
+
 declare function isCollapsed(sel: Selection): boolean;
 declare function positionsEqual(a: Position, b: Position): boolean;
 declare function comparePositions(a: Position, b: Position): number;
@@ -397,6 +427,12 @@ declare function collapsedSelection(pos: Position): Selection;
  */
 declare function sameTextRun(a: Position, b: Position): boolean;
 
+/**
+ * Attributes object that explicitly clears every mark (sets each to `null`).
+ * Spread your desired marks on top to insert text carrying EXACTLY those marks,
+ * overriding any formatting Y.Text would otherwise inherit from an adjacent run.
+ */
+declare const CLEAR_ALL_MARKS: Record<string, null>;
 /**
  * Returns the marks observed across `[start, end)`. For each mark name encountered:
  *   - if every covered character has the same value, returns that value
@@ -412,6 +448,28 @@ declare function deltaLength(delta: DeltaOp[]): number;
  */
 declare function sliceDelta(delta: DeltaOp[], start: number, end: number): DeltaOp[];
 
+/** MIME custom que carrega o slice serializado no clipboard. */
+declare const SOFER_MIME = "application/x-sofer-slice";
+interface ClipboardSlice {
+    /** 1..n blocos; cada delta carrega marks + embeds de imagem. */
+    blocks: SerializedBlock[];
+    /** 1º bloco é fragmento parcial → mescla inline no alvo da colagem. */
+    openStart: boolean;
+    /** último bloco é fragmento parcial → conteúdo após o caret continua nele. */
+    openEnd: boolean;
+}
+/**
+ * Lê a seleção e produz um ClipboardSlice, ou null se:
+ * - colapsada; - âncora/foco em células diferentes; - multi-bloco com tabela.
+ */
+declare function serializeSelection(doc: EditorDocument, sel: Selection): ClipboardSlice | null;
+/** Fallback texto puro: textos dos blocos unidos por "\n". */
+declare function sliceToText(slice: ClipboardSlice): string;
+/** Achata o slice num único delta inline (para colar dentro de uma célula).
+ *  Fronteiras de bloco viram quebra de linha "\n" (células renderizam pre-wrap),
+ *  para não grudar palavras de parágrafos distintos. */
+declare function sliceToInlineDelta(slice: ClipboardSlice): DeltaOp[];
+
 declare const COMMAND_ORIGIN: unique symbol;
 interface CommandContext {
     doc: EditorDocument;
@@ -455,6 +513,26 @@ declare function setBlockType(ctx: CommandContext, type: BlockType, attrs?: Bloc
  * Passing `value === null` deletes the key.
  */
 declare function setBlockAttr<K extends keyof BlockAttrs>(ctx: CommandContext, key: K, value: BlockAttrs[K] | null): void;
+/**
+ * Set a single attribute on the table cell(s) under the selection.
+ * - Caret numa única célula → essa célula (tableRectSelection retorna null
+ *   para seleção colapsada (ou âncora/foco no mesmo owner), então usamos
+ *   a célula focada (redirecionada ao owner real).
+ * - Seleção retangular de várias células → todas as células reais do rect.
+ * Células `covered` são puladas. `value === null` apaga a key.
+ * No-op se a seleção não estiver dentro de uma tabela.
+ */
+declare function setCellAttr<K extends keyof CellAttrs>(ctx: CommandContext, key: K, value: CellAttrs[K] | null): void;
+/** Delete the current selection range and collapse the caret. Used by cut. */
+declare function deleteSelection(ctx: CommandContext): void;
+/**
+ * Replace the current selection with a clipboard slice (A1).
+ * - Single-block slice → inline splice (Dhead + S0 + Dtail), target keeps its type.
+ * - Multi-block slice → openStart merges S0 inline; middle/last blocks inserted
+ *   discretely; openEnd appends the post-caret tail onto the last pasted block.
+ * - Target inside a table cell → slice flattened to inline (no block structure).
+ */
+declare function insertSlice(ctx: CommandContext, slice: ClipboardSlice): void;
 /**
  * Convert every block in the selection to/from a `listItem` of `kind`.
  * If every covered block is already a `listItem` of `kind` → convert them all to paragraphs.
@@ -623,6 +701,24 @@ declare function insertImage(ctx: CommandContext, embed: ImageEmbed): void;
  * around it (CSS float only flows text that comes AFTER the float in DOM order).
  */
 declare function setImageAttrs(ctx: CommandContext, blockIndex: number, embedOffset: number, partial: Partial<ImageEmbed>, cellIndex?: number, newOffset?: number): void;
+/** Location of an embed in the model (block or table cell). */
+interface EmbedLoc {
+    blockIndex: number;
+    offset: number;
+    cellIndex?: number;
+}
+/**
+ * Move a floating image embed from `from` to `to` in a SINGLE Y.Doc
+ * transaction, applying new positional offsets. Atomic delete+insert keeps the
+ * CRDT consistent for collab peers and coalesces into one undo step.
+ *
+ * Guard: only non-inline (re-anchorable) image embeds are moved; everything
+ * else is a no-op. When `from` and `to` resolve to the SAME Y.Text, the insert
+ * index is adjusted for the prior delete (mirrors `setImageAttrs`'s clamp at
+ * lines 1709-1714). Sets the selection to the embed's new 1-char home so the
+ * resize overlay stays attached.
+ */
+declare function moveEmbedAnchor(ctx: CommandContext, from: EmbedLoc, to: EmbedLoc, newOffsetX: number, newOffsetY: number): void;
 declare function isCommandOrigin(origin: unknown): boolean;
 declare const TRACKED_ORIGINS: Set<unknown>;
 
@@ -634,4 +730,4 @@ declare class EditorHistory {
     destroy(): void;
 }
 
-export { type AlignValue, BLOCK_SPECS, type BlockAttrs, type BlockType, COMMAND_ORIGIN, type CellAttrs, type CommandContext, type CommentAttr, DEFAULT_PAGE_SETTINGS, type DeltaOp, type DirValue, EditorDocument, EditorHistory, type ImageEmbed, type ImageLayout, type InsertContent, type LegacySerializedDocument, type LinkAttr, type ListKind, type ListStyleType, MARGIN_PRESETS, MAX_LIST_LEVEL, type MarkAttrs, type MarkName, type MarkValue, PAGE_PRESETS, type PagePreset, type PageSettings, type Position, type Selection, type SerializedBlock, type SerializedCell, type SerializedDocument, TRACKED_ORIGINS, type TableLocation, type TableRect, cellsInRect, clearRectCells, collapsedSelection, comparePositions, createBlock, createCell, createTableBlock, dedentList, defaultAttrsFor, deleteBackward, deleteForward, deleteTable, deleteTableColumn, deleteTableRow, deltaLength, detectPreset, expandTableRect, getMarksInRange, indentList, insertImage, insertParagraph, insertTable, insertTableColumn, insertTableRow, insertText, isCollapsed, isCommandOrigin, isImageEmbed, isKnownBlockType, isLegacySerializedDocument, isMarkUniformInRange, mergeDown, mergeRight, mergeSelection, mmToPx, moveToNextCell, moveToPrevCell, orderedRange, positionsEqual, pxToMm, removeMark, sameTextRun, setBlockAttr, setBlockType, setColumnWidth, setImageAttrs, setMark, sliceDelta, spanOf, splitCell, splitListItem, tableLocationOf, tableRectSelection, toggleList, toggleMark, withDefaults };
+export { type AlignValue, BLOCK_SPECS, type BlockAttrs, type BlockType, CLEAR_ALL_MARKS, COMMAND_ORIGIN, type CellAttrs, type ClipboardSlice, type CommandContext, type CommentAttr, DEFAULT_PAGE_SETTINGS, type DeltaOp, type DirValue, EditorDocument, EditorHistory, type EmbedLoc, type EncodedCursor, type EncodedCursorPoint, type ImageEmbed, type ImageLayout, type InsertContent, type LegacySerializedDocument, type LinkAttr, type ListKind, type ListStyleType, MARGIN_PRESETS, MAX_LIST_LEVEL, type MarkAttrs, type MarkName, type MarkValue, PAGE_PRESETS, type PagePreset, type PageSettings, type Position, SOFER_MIME, type Selection, type SerializedBlock, type SerializedCell, type SerializedDocument, TRACKED_ORIGINS, type TableLocation, type TableRect, cellsInRect, clearRectCells, collapsedSelection, comparePositions, createBlock, createCell, createTableBlock, decodeSelection, dedentList, defaultAttrsFor, deleteBackward, deleteForward, deleteSelection, deleteTable, deleteTableColumn, deleteTableRow, deltaLength, detectPreset, encodeSelection, expandTableRect, getBlockId, getMarksInRange, indentList, insertImage, insertParagraph, insertSlice, insertTable, insertTableColumn, insertTableRow, insertText, isCollapsed, isCommandOrigin, isImageEmbed, isKnownBlockType, isLegacySerializedDocument, isMarkUniformInRange, mergeDown, mergeRight, mergeSelection, mmToPx, moveEmbedAnchor, moveToNextCell, moveToPrevCell, newBlockId, orderedRange, positionsEqual, pxToMm, removeMark, sameTextRun, serializeSelection, setBlockAttr, setBlockType, setCellAttr, setColumnWidth, setImageAttrs, setMark, sliceDelta, sliceToInlineDelta, sliceToText, spanOf, splitCell, splitListItem, tableLocationOf, tableRectSelection, toggleList, toggleMark, withDefaults };