edytor 4.0.0 → 5.0.0

package/dist/crdt/doc/reads.d.ts

@@ -1,6 +1,6 @@
 import type { EngineApi, EngineDoc, EngineNode } from '../engine-api.js';
 import { type BlockId, type ContentItem, type Destination, type ModelView } from '../placement/model.js';
-import type { DisplayRoles, RunView } from '../text/runs.js';
+import type { DisplayRoles, KindRole, RunView } from '../text/runs.js';
 import { type DataPatch } from '../data.js';
 import { type JSONBlock } from '../../utils/json.js';
 import type { BlockRole, DataTarget, JsonObj, OrderPolicy } from './types.js';
@@ -40,7 +40,7 @@ export declare const docReads: (c: DocBase) => {
         parent: BlockId | null;
         rank: string;
     } | null;
-    is: (id: BlockId, role: (type: string) => boolean) => boolean;
+    kindOf: (id: BlockId) => KindRole | undefined;
     isVoid: (id: BlockId) => boolean;
     isIsland: (id: BlockId) => boolean;
     isLines: (id: BlockId) => boolean;

package/dist/crdt/doc/reads.js

@@ -121,15 +121,15 @@ export const docReads = (c) => {
         return slot.parent === DEAD ? pl : slot;
     };
     // ── roles (island/void) ───────────────────────────────────────────
-    /** The role table's answer for `id`'s shown kind (`false` without one). */
-    const is = (id, role) => {
+    /** The role of `id`'s shown kind (`undefined` without one). */
+    const kindOf = (id) => {
         const t = blockTypeOf(id);
-        return t !== undefined && role(t);
+        return t === undefined ? undefined : roles.of(t);
     };
-    const isVoid = (id) => is(id, roles.childless);
-    const isIsland = (id) => is(id, roles.island);
+    const isVoid = (id) => kindOf(id)?.childless === true;
+    const isIsland = (id) => kindOf(id)?.island === true;
     /** An island that holds only lines (a code block: its role says `lines`). */
-    const isLines = (id) => is(id, (type) => roles.line(type) !== undefined);
+    const isLines = (id) => kindOf(id)?.line !== undefined;
     /** Nearest island-typed display ancestor of `id`, or null. */
     const islandOf = (id, v = view()) => ancestorsOf(id, v).find((a) => isIsland(a)) ?? null;
     /** True iff `id` sits strictly inside an island subtree. */
@@ -139,45 +139,35 @@ export const docReads = (c) => {
         const parent = positionOf(id)?.parent;
         return parent != null && isLines(parent);
     };
-    /** The child kind `role` gives `id`'s kind: a layout's item kind, a table's row kind. */
-    const childKindOf = (role) => (id) => {
-        const type = blockTypeOf(id);
-        return type === undefined ? undefined : roles[role](type);
-    };
-    /** `id` is of its parent's `kindOf` kind, directly in it (a column, a row). */
-    const childOf = (kindOf) => (id) => {
+    /** `id` is of its parent's `kind` kind, directly in it (a column, a row, a cell). */
+    const childOf = (kind) => (id) => {
         const parent = positionOf(id)?.parent;
-        return parent != null && blockTypeOf(id) === kindOf(parent);
+        const k = parent == null ? undefined : kindOf(parent);
+        return parent != null && blockTypeOf(id) === (k && kind(k));
     };
     /** The item kind of `id` when it is a layout (its role says `layout`): its default child. */
-    const itemKindOf = childKindOf('layout');
+    const itemKindOf = (id) => kindOf(id)?.layout;
     /** `id` is a layout (`layout.*`). */
     const isLayout = (id) => itemKindOf(id) !== undefined;
     /** `id` is a layout item: of its layout's item kind, directly in it (a column). */
-    const isLayoutItem = childOf(itemKindOf);
+    const isLayoutItem = childOf((k) => k.layout);
     /** `id` is a layout or holds one in its shown subtree (`layout.nest`). */
     const holdsLayout = (id) => isLayout(id) || childrenIds(id).some(holdsLayout);
     /** `id` is a layout item or sits inside one. */
     const insideItem = (id, v) => [id, ...ancestorsOf(id, v)].some(isLayoutItem);
     // ── tables (`table.*`) ────────────────────────────────────────────
-    /** The row kind of `id` when it is a table (its role says `table`): its default child. */
-    const rowKindOf = childKindOf('table');
     /** `id` is a table (`table.*`). */
-    const isTable = (id) => rowKindOf(id) !== undefined;
+    const isTable = (id) => kindOf(id)?.table !== undefined;
     /** `type` is a row kind of a table kind the roles declare (`tableRow`). */
-    const isRowKind = (type) => type !== undefined && [...roles.tableKinds()].some((t) => roles.table(t) === type);
+    const isRowKind = (type) => type !== undefined && roles.declared().rows.has(type);
     /** `type` is a cell kind: the default child of a row kind (`tableCell`). */
-    const isCellKind = (type) => type !== undefined &&
-        [...roles.tableKinds()].some((t) => {
-            const row = roles.table(t);
-            return row !== undefined && roles.defaultChild(row) === type;
-        });
+    const isCellKind = (type) => type !== undefined && roles.declared().cells.has(type);
     /** `id` is a table's row: of its table's row kind, directly in it. */
-    const isTableRow = childOf(rowKindOf);
+    const isTableRow = childOf((k) => k.table);
     /** `id` is a table's cell: of its row's cell kind, directly in a row of a table. */
     const isTableCell = (id) => {
         const row = positionOf(id)?.parent;
-        return (row != null && isTableRow(row) && blockTypeOf(id) === roles.defaultChild(blockTypeOf(row)));
+        return row != null && isTableRow(row) && blockTypeOf(id) === kindOf(row).child;
     };
     /** The table `id` is, or whose row or cell it is; `null` for any other block. */
     const tableOf = (id) => {
@@ -317,7 +307,7 @@ export const docReads = (c) => {
         pathOf,
         ancestorsOf,
         slotOf,
-        is,
+        kindOf,
         isVoid,
         isIsland,
         isLines,

package/dist/crdt/doc/steps.js

@@ -21,7 +21,7 @@ import { REFUSED, effectOf } from './plan.js';
 export const PART = { head: 0, kept: 1, with: 2, self: 3, after: 4 };
 /** The step writers of one facade. */
 export const planSteps = (c) => {
-    const { doc, runsView, roles, rendersContentOf, view, blockTypeOf, childrenIds, positionOf, ancestorsOf, is, isIsland, itemKindOf, isLayout, displayLength, contentItems, live, isContainer, fitted, emptiable, defaultChild } = c;
+    const { doc, runsView, roles, view, blockTypeOf, childrenIds, positionOf, ancestorsOf, isLines, isIsland, itemKindOf, isLayout, displayLength, contentItems, live, isContainer, fitted, emptiable, defaultChild } = c;
     // ── prepared ops ─────────────────────────────────────────────
     // Every op is `prepare` (pure: `refused`, or a plan of named steps plus
     // its effect summary, against the current version) then `apply(plan)`;
@@ -114,9 +114,9 @@ export const planSteps = (c) => {
      * default kind, any other child keeps its kind (as `typeOf`).
      */
     const leavingIsland = (island, kind, to) => {
-        if (rendersContentOf(to) || (kind !== undefined && !rendersContentOf(kind)))
+        if (roles.of(to).rendersContent || (kind !== undefined && !roles.of(kind).rendersContent))
             return to;
-        return is(island, (type) => roles.line(type) !== undefined) ? defaultChild(null) : kind;
+        return isLines(island) ? defaultChild(null) : kind;
     };
     const settledKind = (from, kid, parent) => {
         let kind = blockTypeOf(kid);
@@ -129,7 +129,7 @@ export const planSteps = (c) => {
             // column's default child is the document's: it holds no items of its own.
             const outer = kind !== defaultChild(null) &&
                 within.some((a) => isContainer(a) && defaultChild(a) === kind);
-            if (!outer && rendersContentOf(to))
+            if (!outer && roles.of(to).rendersContent)
                 kind = to;
         }
         return fitted(parent, kind);

package/dist/crdt/doc/suggest.d.ts

@@ -0,0 +1,167 @@
+/**
+ * Shared suggestions (`docs/archive/shared-suggestions/design.md`, the
+ * `sugg.*` rows of `docs/editor-delete-contract.md`): a suggestion lives in
+ * the document, so every replica, the room and a reload see it.
+ *
+ * - A suggestion is a record node under the root `suggest`, written by its
+ *   **writer**: a client id minted for a suggesting session, bound to its
+ *   author with its first write like any replica. The record's own item
+ *   opens the writer's clocks it owns, up to the writer's next record; its
+ *   creation is in no history step, so no undo or redo moves them.
+ * - **An insertion** is the writer's own text and blocks: a shown unit or
+ *   block of the writer, in the record's clocks, not settled, is pending.
+ * - **A deletion** writes nothing to the text: the writer's id list (fork
+ *   patch YP31, a hold record that holds nothing inside a nested node) in
+ *   the record names the units; a shown one, not settled, is pending. A
+ *   block deletion is the same id list naming the block's node.
+ * - Nothing else is suggested: a move, a merge, a retype, a data change or
+ *   a format is refused (written directly on its author's own pending
+ *   block).
+ * - **A decision** writes only what changes, one engine call over the
+ *   change's ids (`YNode#hold`): the text that goes is the reviewer's hold
+ *   (fork patch YP20, the root records list), the text that stays a settled
+ *   id list written by the reviewer into the record (its client is the
+ *   decider).
+ *
+ * What is pending is a function of the replicated state (items, records,
+ * settled ranges), so replicas converge in any delivery order. It is read
+ * again after any write, from the blocks the records' writers and
+ * proposals are in: a document with no suggestion pays nothing.
+ *
+ * The part is built over a document by {@link suggestionsOf} (the shared
+ * suggestions plugin, the room, a bare document on a server): once built,
+ * the document's `toJSON()` leaves its pending suggestions out. A document
+ * no one built it over reads its suggestions' content as plain content.
+ */
+import type { EngineDoc } from '../engine-api.js';
+import { type BlockId } from '../placement/model.js';
+import type { DocAnchor, EdytorDocConfig, OpResult, Prepared } from './types.js';
+import type { DocBase, DocReads } from './reads.js';
+import type { JSONDoc } from '../../utils/json.js';
+import type { EdytorDocument } from '../document.js';
+/** One change of a suggestion, as a reviewer sees it. */
+export type SuggestedChange = {
+    /** The suggestion it is part of (its record's id). */
+    readonly suggestion: string;
+    /**
+     * `insert`: a run of text it inserts; `delete`: a run it proposes to
+     * delete; `block`: a block it inserts, its text with it; `split`: the
+     * block its split makes; `remove`: a block it proposes to delete.
+     */
+    readonly kind: 'insert' | 'delete' | 'block' | 'split' | 'remove';
+    /** The block it is in or about. */
+    readonly block: BlockId;
+    /** Its run, in the block's display offsets (a block's: the whole block). */
+    readonly offset: number;
+    readonly length: number;
+    readonly text: string;
+};
+/** A suggestion the document holds. */
+export type SuggestionRecord = {
+    readonly id: string;
+    /** Its author (its writer's actor), `undefined` until the binding arrives. */
+    readonly by: string | undefined;
+    /** The agent that wrote it for its author (`'ai'`), when one did. */
+    readonly via: string | undefined;
+    readonly label: string | undefined;
+    /** When it was opened (ms since the epoch). */
+    readonly at: number;
+};
+/**
+ * One part of a decision: an id list written into suggestion `into`'s
+ * record (settled: it stays) or, `into` null, the decider's hold of the
+ * text that goes (fork patch YP20, the root records list): one engine
+ * call either way (`YNode#hold`); or a document operation's calls (their
+ * arguments read when it runs).
+ */
+export type DecisionPart = {
+    into: string | null;
+    ids: number[];
+    blocks?: BlockId[];
+} | {
+    op: string;
+    calls: () => unknown[][];
+};
+/** What the part reads of its document beyond the facade: the facade's `part` (`edytor-doc.ts`). */
+export type SuggestContext = DocBase & DocReads & {
+    config: EdytorDocConfig;
+    /** A facade over another doc, with `config`. */
+    create: (doc: EngineDoc, config: EdytorDocConfig) => SuggestFacade;
+    /** Its changes no index fact shows: counted in the facade's `version`. */
+    v: number;
+    /** The export `toJSON()` gives unless asked for the suggestions. */
+    base: (() => JSONDoc | undefined) | undefined;
+};
+/** The facade the part is built over: its `part`, and the operations it writes through. */
+export type SuggestFacade = {
+    part: SuggestContext;
+    toJSON: (options?: {
+        suggestions?: boolean;
+    }) => JSONDoc;
+    dispose: () => void;
+    apply: (p: Prepared, quiet?: boolean) => OpResult;
+    transact: <R>(fn: () => R) => R;
+    anchorAt: (id: BlockId, offset: number, affinity?: 'left' | 'right') => DocAnchor | null;
+    resolveAnchor: (anchor: DocAnchor) => {
+        blockId: BlockId;
+        offset: number;
+    } | null;
+    /** Its operations by name (`f[op](…args)`). */
+    [op: string]: unknown;
+};
+/**
+ * The shared suggestions of the document `facade` is over, built once:
+ * from then on, its `toJSON()` leaves the pending ones out (`sugg.json.base`).
+ */
+export declare const suggestionsOf: (facade: SuggestFacade) => DocSuggest;
+/**
+ * Build the shared suggestions over `document`, a document read without a
+ * view (on a server, in a worker): its `toJSON()` leaves the pending ones
+ * out from then on, as a view's with the shared suggestions plugin does. A
+ * document no one built them over reads their content as plain content.
+ */
+export declare const adoptSharedSuggestions: (document: EdytorDocument) => void;
+/** The document's shared suggestions ({@link suggestionsOf}), built over facade `f`. */
+declare const docSuggest: (f: SuggestFacade) => {
+    /** A fresh writer this replica writes suggestions under. */
+    writer: () => number;
+    /** The writers this replica minted (a history tags their steps, `StackItem.writer`). */
+    writers: Set<number>;
+    open: (options?: {
+        id?: string;
+        writer?: number;
+        via?: string;
+        label?: string;
+        at?: number;
+    }) => string;
+    apply: (id: string | null, p: Prepared, w?: number) => {
+        result: OpResult;
+        id?: string;
+        at?: {
+            block: BlockId;
+            offset: number;
+        };
+    };
+    decide: (changes: readonly SuggestedChange[], accept: boolean) => DecisionPart[];
+    run: (parts: readonly DecisionPart[], exec?: (op: string, args: unknown[]) => unknown, w?: number) => void;
+    /** The suggestions the document holds, oldest first. */
+    records: () => SuggestionRecord[];
+    /** Whether the document holds any suggestion record. */
+    any: () => boolean;
+    /** Every pending change, in document order. */
+    changes: () => SuggestedChange[];
+    /** The pending changes of block `b` (`[]`: none). */
+    at: (b: BlockId) => readonly SuggestedChange[];
+    /** Bumped by every change of the records. */
+    version: () => number;
+    /** Be told of every change of the records. Returns the unsubscribe. */
+    onChange: (f: () => void) => () => undefined;
+    /** @internal The work done (blocks read, units walked): the scaling rows count it. */
+    debug: {
+        computes: number;
+        units: number;
+    };
+    dispose: () => void;
+};
+export type DocSuggest = ReturnType<typeof docSuggest>;
+export {};