edytor 1.0.0-rc.3 → 1.0.0

package/dist/session/commands.d.ts

@@ -1,22 +1,40 @@
-import type { Prepared } from '../crdt/edytor-doc.js';
+/**
+ * The command dispatcher: one per view.
+ *
+ * Every write a view makes is one of the document's operations
+ * (`DocumentWrites`, dispatched under its own name and arguments:
+ * `edytor.insertBlocks(…)`), or a named command that is one prepared plan of
+ * them (`plan`: a table row, a find-and-replace). It is admitted (readonly,
+ * `document.writable`), prepared, shown to every extension hook before any
+ * write — the command itself, then each planned step as the operation it
+ * performs — applied in one transaction, normalized once per touched block at
+ * the end of that transaction (normalizers read handles over the index), and
+ * reported (`refused | noop | applied | failed`). A user command (`run`)
+ * wraps the operations one gesture issues and closes the undo policy table.
+ * `prevent()` is caught here, once (`prevented`).
+ */
+import type { Block } from '../block/block.svelte.js';
+import type { DocumentWrites } from '../crdt/operations.js';
+import type { OpResult, Prepared } from '../crdt/edytor-doc.js';
+import type { DocPosition } from '../crdt/rangeDelete.js';
 import type { SelectionValue } from './selection.js';
 import type { Text } from '../text/text.svelte.js';
 import type { Caret } from '../selection/selection.svelte.js';
 /**
  * The result of the last command a view ran (`edytor.dispatcher.last`): its
- * operation, its status and, for a handle mutator (`block.insertBlockAfter`,
- * `text.insertText`, …), the `value` the mutator returned — `undefined`
- * when the command was refused or did not run.
+ * operation and its status.
  */
-export type CommandResult<T = unknown> = {
+export type CommandResult = {
     operation: string;
     status: 'refused' | 'noop' | 'applied' | 'failed';
-    /** What the command answered: a handle mutator's return value. */
-    value?: T;
     error?: unknown;
     /** The result selection the command authored, selected once. */
     selection?: SelectionValue;
 };
+/** A document write's name. */
+export type Write = keyof DocumentWrites;
+/** A kind's normalizer (`BlockDefinition.normalizeContent`/`normalizeChildren`). */
+export type Normalizer = 'normalizeContent' | 'normalizeChildren';
 export declare class Dispatcher {
     #private;
     private edytor;
@@ -37,9 +55,6 @@ export declare class Dispatcher {
     /** Requested normalization passes: (block id, normalizer). */
     private queue;
     private current;
-    /** The drain is entering `current`'s normalizer (its own request runs it). */
-    private entering;
-    private draining;
     /** A plan the next dispatched operation composes before its own (`lead`). */
     private leading;
     /** What the last `patchData` set to text: typing on the same paths continues its step (a bound field). */
@@ -55,9 +70,10 @@ export declare class Dispatcher {
      * placed. That step's undo withdraws the block, URL included
      * (`hist.undo.withdraw`), and its redo shows it again, so the paste stays
      * one step whatever the upload's delay, and the typing around it groups
-     * as if it never came. Throws, writing nothing, when a transaction is
-     * already open: its writes would take that transaction's origin and join
-     * its step (call it from a later task, as an upload's answer is).
+     * as if it never came. In development, throws, writing nothing, when a
+     * transaction is already open: its writes would take that transaction's
+     * origin and join its step (call it from a later task, as an upload's
+     * answer is).
      */
     outside: <T>(body: () => T) => T;
     /**
@@ -90,6 +106,17 @@ export declare class Dispatcher {
         block: unknown;
         text?: Text;
     }, body: (payload: P, plan?: Prepared) => R, prepare?: (payload: P) => Prepared) => R | undefined;
+    /**
+     * Dispatch `operation` as the plan `prepare` makes of `payload` (a hook's
+     * replacement payload is prepared again), about `block` (the root by
+     * default): hooks see it and each planned step before any write; one
+     * transaction; the blocks it touched normalized and the blocks it moved
+     * shown (closed toggles open); the caret it decides (`plan.at`: a range
+     * deletion, a placed flow) selected. Answers its result: `refused` when
+     * the document refused it, `refused` with the reason `'view'` when the
+     * view did (readonly, a read-only document) or a hook prevented it.
+     */
+    plan: <P>(operation: string, payload: P, prepare: (payload: P) => Prepared, block?: Block, text?: Text) => OpResult;
     /**
      * Run `body` with `lead` (a plan prepared now) composed into the first
      * operation it dispatches: one plan, so a veto of any step, or a refusal,
@@ -110,8 +137,8 @@ export declare class Dispatcher {
      * block offsets (an inline atom counting 1).
      */
     caret: {
-        <T>(text: Text | null | undefined, offset: number, ops?: () => T): T | undefined;
-        <T>(caret: Caret | null | undefined, ops?: () => T): T | undefined;
+        (text: Text | null | undefined, offset: number, ops?: () => OpResult): OpResult | undefined;
+        (caret: Caret | DocPosition | null | undefined, ops?: () => OpResult): OpResult | undefined;
     };
     /**
      * The cut an operation applies as it writes. Inside a user command none
@@ -122,7 +149,6 @@ export declare class Dispatcher {
     private policy;
     /** A continuation continues this view's last step, or cuts before it writes. */
     private decide;
-    private refuse;
     private settle;
     /**
      * Run a prevention's replacement: a command of its own, so a veto of one
@@ -132,12 +158,11 @@ export declare class Dispatcher {
      */
     private replace;
     /**
-     * The planned steps as hooks see them, under the documented
-     * operation names. A step that is the command itself (same name, same
-     * block) is not repeated; a write into a block the plan creates is part
-     * of that creation. (A `removeInline` step is only ever its own command,
-     * `removeInlineBlock`; `formatRange` steps belong to no dispatched plan
-     * yet: no mapping. A document data patch shows on the root.)
+     * The planned steps as hooks see them: each as the operation it performs,
+     * with that operation's arguments (`ARGS`), about the block it writes
+     * (the root for the document's data). A step that is the command itself
+     * (same name, same block) is not repeated; a write into a block the plan
+     * creates is part of that creation.
      */
     private steps;
 }