edytor 0.0.11 → 0.1.0-next.16

package/dist/block/block.utils.d.ts

@@ -1,11 +1,57 @@
-import { Block } from './block.svelte.js';
-import { Text } from '../text/text.svelte.js';
-import type { JSONBlock, JSONInlineBlock, JSONText } from '../utils/json.js';
+/**
+ * View-side command adapter for block operations (U2 delegation contract).
+ *
+ * These functions are the `BlockOperations` layer bound onto `Block` via
+ * `batch()`, which dispatches each call as a command (admission, plugin
+ * interception, one transaction: `session/commands.ts`). The functions own
+ * path/offset resolution (target paths → parent blocks, a text's `segStart`,
+ * sibling lookup for `nestBlock`), the plan of an operation
+ * that is one document op (`prepare*`) and its normalization requests.
+ *
+ * OPERATIONS READ AND WRITE ONLY THE DOCUMENT (R3): `Block`/`Text` are id-only
+ * handles whose getters read the index (R4), so what a caller needs after the
+ * write (the new block, the text after an inserted atom, the caret a range op
+ * decided) is the op's document result as a handle (`batch`'s `resolve`) —
+ * inside an outer transaction too.
+ *
+ * STRUCTURAL PERMISSION IS DOCUMENT-OWNED: every op delegates to
+ * `block.model.*` (the facade through `DocBlock`) and treats a `refused` result
+ * as "refused" — no view-side re-checks of the rules the document already
+ * enforces (island sealing, void/island destinations, own-subtree moves,
+ * merges across island boundaries; see `edytor-doc.ts` `canPlace` and
+ * `canMerge`, R5). Removing a view-side semantic guard must never
+ * change document behavior — if a rule matters here it belongs in the
+ * facade, not in this file.
+ *
+ * Content preparation produces `BlockSpec`/`ContentItem` DIRECTLY from
+ * JSON (`jsonBlockToSpec`/`jsonContentToItems` in `utils/json.ts`): specs are
+ * data (K5: `new Block({block})` is gone). The live-content invariant
+ * (text-first/text-last, no adjacent same-kind parts) is derived by the
+ * document's projection on read, so stored content needs no
+ * pre-normalization.
+ */
+import type { Block } from './block.svelte.js';
+import type { Text } from '../text/text.svelte.js';
+import type { Flow, FlowTarget } from '../crdt/flow.js';
+import type { Plan, Prepared } from '../crdt/edytor-doc.js';
+import type { DataPatch } from '../crdt/data.js';
+import type { ResolvedAt } from '../session/suggestions.svelte.js';
+import { type JSONBlock, type JSONInlineBlock, type JSONText } from '../utils/json.js';
 import { InlineBlock } from './inlineBlock.svelte.js';
 export type BlockOperations = {
     removeInlineBlock: {
         index: number;
     };
+    /**
+     * Patch the block's `data` (with `atom`, that inline atom's; on the root,
+     * the document's), in order: each patch sets the value at its path, or
+     * deletes it when it has no `value`. `block.data`'s proxy, `setData` and
+     * `atom.setData` issue it.
+     */
+    patchData: {
+        ops: DataPatch[];
+        atom?: string;
+    };
     addChildBlock: {
         block: JSONBlock;
         index: number;
@@ -24,15 +70,18 @@ export type BlockOperations = {
         index: number;
         text: Text;
     };
+    /** A copy of the block and its subtree right after it, under fresh ids. */
+    duplicateBlock: {};
+    /** The children take the block's slot unless `keepChildren: false` (the whole subtree). */
     removeBlock: {
-        keepChildren: boolean;
+        keepChildren?: boolean;
     };
     unNestBlock: {};
     mergeBlockBackward: {};
     mergeBlockForward: {};
     nestBlock: {};
     setBlock: {
-        value: JSONBlock;
+        value: Partial<JSONBlock>;
     };
     addInlineBlock: {
         index: number;
@@ -42,41 +91,159 @@ export type BlockOperations = {
     moveBlock: {
         path: number[];
     };
+    moveBlocks: {
+        blocks: Block[];
+        path: number[];
+    };
     pushContentIntoBlock: {
         value: (Text | InlineBlock)[];
     };
-    deleteContentForward: {
-        text: Text;
-    };
     normalizeContent: {};
+    normalizeChildren: {};
+    /** @deprecated `edytor.suggestions.add({ end: block.id }, …)`. */
     suggestText: {
         value: (JSONText | JSONInlineBlock)[] | string | null;
     };
+    /** @deprecated `suggestion.accept()`; the command hooks see is `acceptSuggestion`. */
     acceptSuggestedText: {};
+    /** A suggestion placed in the document (`edytor.suggestions`, `suggestion.accept()`). */
+    acceptSuggestion: {
+        suggestion: {
+            id: string;
+            at: ResolvedAt;
+            content: readonly JSONBlock[];
+        };
+    };
     deleteContentAtRange: {
         start: [number, number];
         end: [number, number];
     };
-    deleteContentWithinSelection: {};
+    deleteContentWithinSelection: {
+        replace?: boolean;
+    };
+    insertFlow: {
+        flow: Flow;
+        target: FlowTarget;
+    };
+    deleteBlocks: {
+        blocks: Block[];
+    };
+    /** A divider at the caret: its steps are the conversion, insertion or split it plans. */
+    insertDivider: {};
 };
-export declare function batch<T extends (...args: any[]) => any, O extends keyof BlockOperations>(operation: O, func: T): T;
+/**
+ * Bind an operation onto its wrapper: every call is dispatched as a command
+ * (`session/commands.ts`): admission, hooks before any write (on the command
+ * and, when `prepare` answers one document plan, on each planned step), one
+ * transaction, normalization, the result. `func` receives the prepared plan
+ * and answers the op's document result; `resolve` turns it into wrappers
+ * after the commit patched them.
+ */
+export declare function batch<T extends (...args: any[]) => any, O extends keyof BlockOperations, R = ReturnType<T>>(operation: O, func: T, prepare?: (payload: BlockOperations[O]) => Prepared, resolve?: (this: any, out: ReturnType<T> | undefined, payload: Parameters<T>[0]) => R): (...args: Parameters<T>) => R;
+/**
+ * The handle of block `id` (null: refused at preparation, or gone; undefined:
+ * the command did not run). Inside an outer transaction too: the index shows
+ * the block that transaction created.
+ */
+export declare function blockOf(this: Block, id: string | null | undefined): Block | null | undefined;
+/**
+ * Dispatch `operation` on `block` as the one plan `prepare` answers (a
+ * composed command: hooks see it and each planned step, one transaction).
+ * `then` runs in that transaction once the plan applied, with the payload
+ * hooks left. Answers the applied plan, or null when refused.
+ */
+export declare const dispatchPlan: <O extends keyof BlockOperations>(block: Block, operation: O, payload: BlockOperations[O], prepare: (payload: BlockOperations[O]) => Prepared, touched?: (Block | null | undefined)[], then?: (payload: BlockOperations[O]) => void) => Plan | null;
+/** One child at `index` (a default-kind block without `block`); see {@link addChildBlocks}. */
 export declare function addChildBlock(this: Block, { block, index }: BlockOperations['addChildBlock']): Block;
+/** Children at `index`, clamped to the child list (at its end by default); ids kept or minted. */
 export declare function addChildBlocks(this: Block, { blocks, index }: BlockOperations['addChildBlocks']): Block[];
-export declare function insertBlockAfter(this: Block, { block }: BlockOperations['insertBlockAfter']): Block | null;
-export declare function insertBlockBefore(this: Block, { block }: BlockOperations['insertBlockBefore']): Block | null;
-export declare function splitBlock(this: Block, { index, text }: BlockOperations['splitBlock']): Block | null;
-export declare function removeBlock(this: Block, { keepChildren }?: BlockOperations['removeBlock']): void;
-export declare function mergeBlockBackward(this: Block): Block | null;
-export declare function mergeBlockForward(this: Block): Block | null;
-export declare function moveBlock(this: Block, { path }: BlockOperations['moveBlock']): Block | null;
-export declare function unNestBlock(this: Block): Block | null;
-export declare function nestBlock(this: Block): Block | null;
-export declare function setBlock(this: Block, { value }: BlockOperations['setBlock']): void;
+export declare function prepareInsertAfter(this: Block, { block }: {
+    block: JSONBlock;
+}): Prepared;
+export declare function prepareInsertBefore(this: Block, { block }: {
+    block: JSONBlock;
+}): Prepared;
+export declare function insertBlockAfter(this: Block, payload: BlockOperations['insertBlockAfter'], plan?: Prepared): string | null;
+export declare function insertBlockBefore(this: Block, payload: BlockOperations['insertBlockBefore'], plan?: Prepared): string | null;
+export declare function prepareDuplicate(this: Block): Prepared;
+export declare function duplicateBlock(this: Block, _?: BlockOperations['duplicateBlock'], plan?: Prepared): string | null;
+export declare function prepareSplit(this: Block, { index, text }: BlockOperations['splitBlock']): Prepared;
+/**
+ * A split whose children stay with the block (a container's header): the
+ * tail, of `tail`'s kind, becomes the block's first child (`child`) or its
+ * next sibling. One plan: the document's split step, placed here, without
+ * the move that gives the tail the children.
+ */
+export declare function prepareSplitKeepingChildren(this: Block, { index, text }: BlockOperations['splitBlock'], tail: {
+    type: string;
+    data?: Record<string, unknown>;
+}, child: boolean): Prepared;
+export declare function splitBlock(this: Block, payload: BlockOperations['splitBlock'], plan?: Prepared): string | null;
+export declare function prepareRemove(this: Block, { keepChildren }?: {
+    keepChildren?: boolean;
+}): Prepared;
+export declare function removeBlock(this: Block, payload?: BlockOperations['removeBlock'], plan?: Prepared): void;
+export declare function prepareMergeBackward(this: Block): Prepared;
+export declare function prepareMergeForward(this: Block): Prepared;
+export declare function mergeBlockBackward(this: Block, _?: BlockOperations['mergeBlockBackward'], plan?: Prepared): string | null;
+export declare function mergeBlockForward(this: Block, _?: BlockOperations['mergeBlockForward'], plan?: Prepared): string | null;
+export declare function prepareMove(this: Block, { path }: BlockOperations['moveBlock']): Prepared;
+export declare function moveBlock(this: Block, payload: BlockOperations['moveBlock'], plan?: Prepared): Block | null;
+/**
+ * Grouped move — the operation-layer counterpart of `moveBlock` for
+ * drags/multi-moves (D5). `path` is the same view-tree address shape:
+ * the prefix resolves the destination PARENT block, the last element is
+ * the FINAL index — already discounted for the moved members by the
+ * caller (the `facade.moveBlocks` contract, which counts the
+ * destination's children with the moved members excluded). Structural
+ * permission stays in the facade.
+ */
+export declare function prepareMoves(this: Block, { blocks, path }: BlockOperations['moveBlocks']): Prepared;
+export declare function moveBlocks(this: Block, payload: BlockOperations['moveBlocks'], plan?: Prepared): Block[];
+/**
+ * The facade owns the refusal rules (`unNestBlock`: top-level blocks,
+ * island-sealed blocks and sealed destinations).
+ */
+export declare function prepareUnNest(this: Block): Prepared;
+export declare function unNestBlock(this: Block, _?: BlockOperations['unNestBlock'], plan?: Prepared): Block | null;
+/**
+ * Admission resolves the nest target — the previous sibling — and the
+ * facade owns permission: `nestBlock` refuses void/island/inside-island
+ * targets and island-sealed sources (`canPlace`).
+ */
+export declare function prepareNest(this: Block): Prepared;
+export declare function nestBlock(this: Block, _?: BlockOperations['nestBlock'], plan?: Prepared): Block | null;
+export declare function prepareSet(this: Block, { value }: BlockOperations['setBlock']): Prepared;
+export declare function setBlock(this: Block, payload: BlockOperations['setBlock'], plan?: Prepared): void;
 export declare function pushContentIntoBlock(this: Block, { value }: BlockOperations['pushContentIntoBlock']): void;
-export declare function removeInlineBlock(this: Block, { index }: BlockOperations['removeInlineBlock']): void;
-export declare const groupContent: (content?: (JSONText | JSONInlineBlock)[]) => (JSONText[] | JSONInlineBlock)[];
-export declare function addInlineBlock(this: Block, { index, block, text }: BlockOperations['addInlineBlock']): Text;
+export declare function prepareRemoveInline(this: Block, { index }: {
+    index: number;
+}): Prepared;
+export declare function removeInlineBlock(this: Block, payload: BlockOperations['removeInlineBlock'], plan?: Prepared): void;
+export declare function preparePatch(this: Block, { ops, atom }: BlockOperations['patchData']): Prepared;
+export declare function patchData(this: Block, payload: BlockOperations['patchData'], plan?: Prepared): void;
+/**
+ * Insert an inline atom at `index` of `text`. Answers the atom's id; the
+ * batched operation resolves it to the text after the atom once committed
+ * ({@link textAfterAtom}), where the caret's pending marks follow.
+ */
+export declare function addInlineBlock(this: Block, { index, block, text }: BlockOperations['addInlineBlock']): string;
+/** The text after atom `atom` of this block; the caret's pending marks follow it there (L4). */
+export declare function textAfterAtom(this: Block, atom: string | undefined): Text | null | undefined;
+/**
+ * Normalization runs at the end of the command's transaction
+ * (`Dispatcher.drain`): a normalizer reads handles over the index; when a
+ * plugin hook answers work, the work runs in the same transaction and the
+ * block is requested again (bounded by the dispatcher's pass limit, D25).
+ */
 export declare function normalizeContent(this: Block): void;
+export declare function normalizeChildren(this: Block): void;
+/** @deprecated A thin wrapper over an `{ end: block.id }` suggestion (`edytor.suggestions`). */
 export declare function suggestText(this: Block, { value }: BlockOperations['suggestText']): void;
+/** @deprecated Accepts this block's latest `{ end }` suggestion (`suggestion.accept()`). */
 export declare function acceptSuggestedText(this: Block): void;
-export declare function deleteContentAtRange(this: Block, { start, end }: BlockOperations['deleteContentAtRange']): void;
+export declare function prepareDeleteRange(this: Block, { start: [startIndex, startOffset], end: [endIndex, endOffset] }: {
+    start: number[];
+    end: number[];
+}): Prepared;
+export declare function deleteContentAtRange(this: Block, payload: BlockOperations['deleteContentAtRange'], plan?: Prepared): void;