edytor 1.0.0-rc.2 → 1.0.0

package/dist/plugins/uploads.svelte.js

@@ -3,12 +3,14 @@ import { pasteFlow } from '../clipboard/insertClipboardFragment.js';
 import { jsonBlockToSpec } from '../utils/json.js';
 import { id as mint } from '../utils.js';
 /**
- * The view's uploads of pasted and dropped files (`media.files`), one per
- * view: session state, never in the document. The kinds given an `upload`
- * register here; a paste or a drop (a drop replays the paste hooks) of
- * files the kinds take places one empty block per file, each of the kind
- * that takes it (`fallback` last), in the clipboard's order, as one paste
- * (one command, one undo step), and each block shows its upload (`of`).
+ * The view's uploads (`media.files`), one per view, the uploads plugin's:
+ * its uploader (`upload`, an empty block's Upload too) and the uploads of
+ * pasted and dropped files, session state, never in the document. A kind
+ * takes files by its record's `upload`; a paste or a drop (a drop replays
+ * the paste hooks) of files the kinds take places one empty block per
+ * file, each of the kind that takes it (`fallback` last), in the
+ * clipboard's order, as one paste (one command, one undo step), and each
+ * block shows its upload (`of`).
  * The data an upload answers fills the block outside the history
  * (`dispatcher.outside`), so the paste stays the one step that undoes it.
  * A failed upload, or an answer that is no source, leaves the block empty
@@ -20,31 +22,32 @@ import { id as mint } from '../utils.js';
  */
 export class FileUploads {
     edytor;
-    #kinds = [];
+    upload;
     #uploads = new SvelteMap();
-    constructor(edytor) {
+    constructor(edytor, 
+    /** The view's uploader. */
+    upload) {
         this.edytor = edytor;
+        this.upload = upload;
+    }
+    /** The kinds that take files (their records' `upload`), in registration order. */
+    get #kinds() {
+        return [...this.edytor.blocks].flatMap(([type, { upload }]) => upload ? [{ type, ...upload }] : []);
     }
-    /** Take files for `kind` (the first registration of a type wins, as its definition). */
-    register = (kind) => {
-        if (!this.#kinds.some(({ type }) => type === kind.type))
-            this.#kinds.push(kind);
-    };
     /** The kind that takes `file`, if any. */
-    kindOf = (file) => this.#kinds.find((kind) => !kind.fallback && kind.accepts(file)) ??
+    #kindOf = (file) => this.#kinds.find((kind) => !kind.fallback && kind.accepts(file)) ??
         this.#kinds.find((kind) => kind.fallback && kind.accepts(file));
     /** The upload of block `id` in this view (reactive), if any. */
     of = (id) => this.#uploads.get(id);
     /**
-     * The paste hook of every kind that registered (the first one asked
-     * claims for them all): the files a kind takes, unless the HTML beside
-     * them shows text (an office app puts a picture of copied text on the
+     * The paste hook: the files a kind takes, unless the HTML beside them
+     * shows text (an office app puts a picture of copied text on the
      * clipboard).
      */
     paste = ({ e, prevent }) => {
-        if (this.edytor.readonly || !this.#kinds.length)
+        if (this.edytor.readonly)
             return;
-        const files = Array.from(e.clipboardData?.files ?? []).filter((file) => this.kindOf(file));
+        const files = Array.from(e.clipboardData?.files ?? []).filter((file) => this.#kindOf(file));
         if (files.length && !showsText(e.clipboardData?.getData('text/html')))
             prevent(() => this.insert(files));
     };
@@ -52,7 +55,7 @@ export class FileUploads {
     insert = (files) => {
         const { edytor } = this;
         const placed = files.flatMap((file) => {
-            const kind = this.kindOf(file);
+            const kind = this.#kindOf(file);
             return kind ? [{ file, kind, id: mint('b') }] : [];
         });
         if (!placed.length)
@@ -89,7 +92,7 @@ export class FileUploads {
         const block = this.edytor.idToBlock.get(id);
         if (!block?.isInTree || this.edytor.destroyed)
             return;
-        const kind = this.#kinds.find(({ type }) => type === block.type);
+        const kind = block.definition.upload;
         if (!kind || kind.filled(block.data))
             return this.#uploads.delete(id);
         this.#write(id, upload.data);
@@ -112,7 +115,7 @@ export class FileUploads {
         };
         let data;
         try {
-            data = kind.data(file, await kind.upload(file, report));
+            data = kind.data(file, await this.upload(file, report));
         }
         catch {
             data = null;
@@ -136,8 +139,7 @@ export class FileUploads {
     /** The data's write, outside the history; refused (readonly), it is held for the next show. */
     #write = (id, data) => {
         const { edytor } = this;
-        const block = edytor.idToBlock.get(id);
-        edytor.dispatcher.outside(() => block.patchData({ ops: Object.entries(data).map(([key, value]) => ({ path: [key], value })) }));
+        edytor.dispatcher.outside(() => edytor.patchData(id, Object.entries(data).map(([key, value]) => ({ path: [key], value }))));
         if (edytor.dispatcher.last?.status === 'applied')
             this.#uploads.delete(id);
         else
@@ -149,12 +151,17 @@ const showsText = (html) => !!html &&
     typeof DOMParser !== 'undefined' &&
     !!new DOMParser().parseFromString(html, 'text/html').body.textContent?.trim();
 const views = new WeakMap();
-/** The view's file uploads (made at the first ask; `undefined` with no view). */
-export const fileUploads = (edytor) => {
-    if (!edytor)
-        return undefined;
-    let uploads = views.get(edytor);
-    if (!uploads)
-        views.set(edytor, (uploads = new FileUploads(edytor)));
-    return uploads;
+/** The view's uploads, when it lists the uploads plugin. */
+export const fileUploads = (edytor) => edytor && views.get(edytor);
+/**
+ * File uploads (Notion's): the view's one uploader, for every kind whose
+ * record takes files (`upload`: the image, file, video and audio kinds).
+ * Without it, only links are embedded. The first listed claims the view.
+ */
+export const createUploadsPlugin = ({ upload }) => (edytor) => {
+    if (!edytor || views.has(edytor))
+        return {};
+    const uploads = new FileUploads(edytor, upload);
+    views.set(edytor, uploads);
+    return { onPaste: uploads.paste, onEdytorAttached: () => uploads.destroy };
 };

package/dist/plugins.d.ts

@@ -6,13 +6,15 @@ import type { Text } from './text/text.svelte.js';
 import type { TextTransform } from './surface/cells.js';
 import type { SerializableContent } from './utils/json.js';
 import type { HotKey, HotKeyCombination } from './session/keymap.js';
-import type { TextOperations } from './text/text.utils.js';
-import type { BlockOperations } from './block/block.utils.js';
+import type { DocumentWrites } from './crdt/operations.js';
+import type { ResolvedAt } from './session/suggestions.svelte.js';
 import type { EdytorSelection } from './selection/selection.svelte.js';
 import type { InlineBlock } from './block/inlineBlock.svelte.js';
 import type { DocChange, PlanEffect } from './crdt/edytor-doc.js';
 import type { MarkEdge } from './session/editing/text.js';
 import type { Prevent } from './utils.js';
+import type { TriggerMenuController } from './plugins/triggers/TriggerController.svelte.js';
+import type { KindUpload } from './plugins/uploads.svelte.js';
 /** What a placeholder function receives: the empty block's declared values. */
 export type PlaceholderView = {
     type: string;
@@ -20,8 +22,8 @@ export type PlaceholderView = {
     focused: boolean;
     empty: boolean;
 };
-/** An empty block's placeholder text: one string, or one per block (`null`: none). */
-export type Placeholder = string | ((view: PlaceholderView) => string | null);
+/** An empty block's placeholder text: one string, or one per block of the view (`null`: none). */
+export type Placeholder = string | ((view: PlaceholderView, edytor: Edytor) => string | null);
 /**
  * Represents the payload for mark snippets with generic serializable content.
  * @template D - The type of serializable content
@@ -40,12 +42,12 @@ export type { Prevent };
 export type BlockView<D = Record<string, any>> = {
     readonly id: string;
     readonly type: string;
-    readonly data: D;
+    readonly data: Readonly<D>;
     readonly selected: boolean;
     readonly focused: boolean;
     /**
-     * The block's id-only handle (its getters, reactive in a template, and
-     * its commands); `undefined` in a suggestion's preview, which is no block
+     * The block's id-only, read-only handle (its getters, reactive in a
+     * template); `undefined` in a suggestion's preview, which is no block
      * of the document.
      */
     readonly handle: Block | undefined;
@@ -67,11 +69,119 @@ export type BlockSnippetPayload<D = Record<string, any>> = {
     children: Snippet | null;
 };
 /**
- * Represents the payload for change operations on blocks and text.
- * Combines both text operations and block operations with prevention capability.
+ * The view's commands that are no single document write, each one prepared
+ * plan of them, with their payloads: a hook sees each by its name, then its
+ * planned steps as the writes they perform.
  */
-export type ChangePayload = {
+export interface Commands {
+    /** A suggestion placed in the document (`edytor.suggestions`, `suggestion.accept()`). */
+    acceptSuggestion: {
+        suggestion: {
+            id: string;
+            at: ResolvedAt;
+            content: readonly JSONBlock[];
+        };
+    };
+    /**
+     * Find and replace (`plugins/find`): each match's text replaced by
+     * `replacement`, one plan, one undo step.
+     */
+    replaceMatches: {
+        matches: {
+            block: string;
+            offset: number;
+            length: number;
+        }[];
+        replacement: string;
+    };
+    /**
+     * A comment thread's anchor (`plugins/comments`): its `comment:<thread>`
+     * mark over each run of the text it was made on, one plan, one undo step.
+     */
+    addComment: {
+        thread: string;
+        runs: {
+            block: string;
+            offset: number;
+            length: number;
+        }[];
+    };
+    /**
+     * A text range dragged inside the editor and dropped at `to` (block
+     * offsets): its content placed at `to`, then the range deleted — or,
+     * with `copy` (Alt), only placed. Both are prepared before any write:
+     * hooks see the placement's planned steps and the deletion's, and a
+     * veto or a refusal of either writes nothing.
+     */
+    moveText: {
+        from: {
+            start: {
+                block: string;
+                offset: number;
+            };
+            end: {
+                block: string;
+                offset: number;
+            };
+        };
+        to: {
+            block: string;
+            offset: number;
+        };
+        copy: boolean;
+    };
+    /**
+     * A closing marker typed after marked-up text (`**bold**`): the mark
+     * set, the markers removed; `value` typed at `start` of the text.
+     */
+    inlineMarkdown: {
+        value: string;
+        start: number;
+        end: number;
+    };
+    /** A divider at the caret: its steps are the conversion, insertion or split it plans. */
+    insertDivider: Record<string, never>;
+    /** A table's row at `index`, one empty cell per column (`table.insert-row`). */
+    insertTableRow: {
+        index: number;
+    };
+    /** A table's rows, with their cells (`table.delete-row`). */
+    deleteTableRows: {
+        rows: Block[];
+    };
+    /** A table's column at `index`, an empty cell in every row (`table.insert-column`). */
+    insertTableColumn: {
+        index: number;
+        width?: number;
+    };
+    /** A table's column, by id or position, with its cells (`table.delete-column`). */
+    deleteTableColumn: {
+        column: string | number;
+    };
+    /** A table's column moved to position `to` (`table.move-column`). */
+    moveTableColumn: {
+        column: string | number;
+        to: number;
+    };
+    /** A table's rows moved to position `to` among its rows (`table.move-row`). */
+    moveTableRows: {
+        rows: Block[];
+        to: number;
+    };
+    /** The cell a row shows none of in `column`, created (`table.pad`). */
+    fillTableCell: {
+        row: string;
+        column: string | number;
+    };
+}
+/** A change a hook sees: its operation, its payload, the block (and text) it is about. */
+type Change<K, P> = {
+    operation: K;
+    payload: P;
+    /** The block the operation names first (the root for none). */
     block: Block;
+    /** The text segment at the offset a text write names. */
+    text?: Text;
     /**
      * Veto the operation (and, with `cb`, run that in its place): records the
      * veto and returns, so the hook runs to its end; the first call decides.
@@ -79,21 +189,22 @@ export type ChangePayload = {
     prevent: Prevent;
     /**
      * The prepared command's effect (blocks created, removed, merged, moved,
-     * retyped, text ranges written), on a command that is one document plan — a hook can refuse a command by what it would do.
+     * retyped, text ranges written) — a hook can refuse a command by what it
+     * would do. Its planned steps are shown after it, each as the write it
+     * performs.
      */
     effect?: PlanEffect;
-} & ({
-    [K in keyof TextOperations]: {
-        operation: K;
-        text: Text;
-        payload: TextOperations[K];
-    };
-}[keyof TextOperations] | {
-    [K in keyof BlockOperations]: {
-        operation: K;
-        payload: BlockOperations[K];
-    };
-}[keyof BlockOperations]);
+};
+/**
+ * What `onBeforeOperation` receives: a document write under its name with
+ * its arguments (`payload`: `Parameters<DocumentWrites[K]>`), or a view
+ * command with its payload (`Commands`); `operation` narrows `payload`.
+ */
+export type ChangePayload = {
+    [K in keyof DocumentWrites]: Change<K, Parameters<DocumentWrites[K]>>;
+}[keyof DocumentWrites] | {
+    [K in keyof Commands]: Change<K, Commands[K]>;
+}[keyof Commands];
 /**
  * What `onAfterOperation` receives: a {@link ChangePayload} without
  * `prevent` (the operation already ran). The `Omit` distributes over the
@@ -171,20 +282,6 @@ export type TriggerContext = TextRuleContext & {
     /** The text typed after the trigger's `char`. */
     query: string;
 };
-/** One row of a trigger's menu, for an `item` snippet. */
-export type TriggerItemPayload<T = unknown> = {
-    item: T;
-    /** The row's label (`label(item)`). */
-    label: string;
-    /** The row's element id: set it (`id={row.id}`) so the editor names the highlighted row. */
-    id: string;
-    /** It is the keyboard's row. */
-    selected: boolean;
-    /** Pick it. */
-    pick: () => void;
-    /** Make it the keyboard's row (hover). */
-    select: () => void;
-};
 /**
  * A character typed at a text's start or after whitespace opens a menu at
  * the caret (`@` for people, `[[` for pages); the text typed after it is
@@ -208,14 +305,13 @@ export type Trigger<T = any> = {
     label?: (item: T) => string;
     /** A row's key, which keeps its markup across queries: default its `id`, else its label. Two rows may share one. */
     key?: (item: T) => string;
-    /** Replace each row's markup. */
-    item?: Snippet<[TriggerItemPayload<T>]>;
-    /** The menu's accessible name (default: the view's `labels.triggerMenu`, `Suggestions`). */
-    name?: string;
-    /** The text shown when no row matches (default: the view's `labels.noResults`, `No results`). */
-    empty?: string;
-    /** The text shown while a search is pending and no row is shown (default: the view's `labels.searching`, `Searching…`). */
-    searching?: string;
+    /**
+     * The menu's markup and its words; it renders while `controller.isOpen`,
+     * placed at the caret (without it, nothing shows). Its keys stay the
+     * editor's; keep its ARIA with `{@attach controller.popup}` on the list
+     * (name it with `aria-label`) and `{...controller.option(index)}` on each row.
+     */
+    menu?: Snippet<[TriggerMenuController<T>]>;
     /** Whether the menu may open in `block` (default: a block that is not void and not in a code block). */
     enabled?: (block: Block) => boolean;
 };
@@ -228,10 +324,6 @@ export type PluginDefinitions = {
     inlineBlocks?: Record<string, InlineBlockDefinition | Snippet<[InlineBlockSnippetPayload<any>]>>;
     hotkeys?: Partial<Record<HotKeyCombination, HotKey>>;
     commands?: EditorCommand[];
-    /** Text typed at the caret that a rule replaces (markdown, `:smile:` → 😄). */
-    inputRules?: InputRule[];
-    /** Characters that open a menu of rows at the caret (`@` mentions). */
-    triggers?: Trigger[];
 };
 /**
  * Plugin factory function type that creates plugin definitions and operations.
@@ -244,9 +336,8 @@ export type PluginOperations = {
     /** Called before an operation is executed */
     onBeforeOperation?: <C extends ChangePayload>(payload: C) => C['payload'] | void;
     /**
-     * Called after an operation is executed: `dispatcher.last.status` is set
-     * (its `value`, what a handle mutator returns, is recorded after this
-     * hook); `operation` narrows `payload`.
+     * Called after an operation is executed: `dispatcher.last.status` is set;
+     * `operation` narrows `payload`.
      */
     onAfterOperation?: (payload: AfterOperationPayload) => void;
     /** Called when the editor value changes: the same `JSONDoc` shape `<Edytor value>` takes. */
@@ -401,6 +492,12 @@ export type BlockDefinition = {
      * Adopted by the document; checked in development against the snippet.
      */
     rendersContent?: boolean;
+    /**
+     * The files the kind takes (the image's `image/*`, the file block's any):
+     * with the uploads plugin listed, an empty block's Upload sends one and a
+     * pasted or dropped file becomes a block of this kind (`media.files`).
+     */
+    upload?: KindUpload;
     /**
      * A list-like kind (Notion's bullets, numbers, to-dos, toggles): Enter at
      * the start or end of a non-empty block opens another block of this kind
@@ -412,10 +509,18 @@ export type BlockDefinition = {
     /**
      * A container kind (Notion's toggles, callouts, quotes): its content is a
      * header over its children. Enter at the end of a header with children
-     * opens a first child of `defaultChild`; a closed `details` header (the
+     * opens a first child of `defaultChild`, as at the end of an open
+     * `details` header without children; a closed `details` header (the
      * browser owns `open`) opens a sibling after instead, children untouched.
      */
     container?: boolean;
+    /**
+     * A container whose children are a body that shows even while it is
+     * empty (Notion's callout: a title over its content): Enter at the end of
+     * its header opens its first child, as an open toggle's does, and a paste
+     * there leads that body. Needs `container`.
+     */
+    body?: boolean;
     /**
      * The type a new child of this block takes by default (Enter inside a
      * child, a split, an island merged out into it). Adopted by the
@@ -482,17 +587,19 @@ export type BlockDefinition = {
         block: Block;
     }) => void;
     /** Normalize block content
-     * Called at the end of the transaction of each operation on the block: the
-     * block is an id-only handle whose reads show the operation's writes.
-     * If you return a function, it runs in the same transaction.
+     * Called at the end of the transaction of each operation that wrote the
+     * block's content: the block is an id-only handle whose reads show the
+     * operation's writes. If you return a function, it runs in the same
+     * transaction (its writes are the view's operations).
      */
     normalizeContent?: (payload: {
         block: Block;
     }) => (() => void) | void;
     /** Normalize block children
-     * Called at the end of the transaction of each operation on the block: the
-     * block is an id-only handle whose reads show the operation's writes.
-     * If you return a function, it runs in the same transaction.
+     * Called at the end of the transaction of each operation that changed the
+     * block's children: the block is an id-only handle whose reads show the
+     * operation's writes. If you return a function, it runs in the same
+     * transaction (its writes are the view's operations).
      */
     normalizeChildren?: (payload: {
         block: Block;
@@ -502,7 +609,7 @@ export type BlockDefinition = {
 export type InlineBlockView<D = Record<string, any>> = {
     readonly id: string;
     readonly type: string;
-    readonly data: D;
+    readonly data: Readonly<D>;
     readonly selected: boolean;
     /** The atom's id-only handle; a suggested atom has none. */
     readonly handle: InlineBlock | undefined;

package/dist/selection/domSelection.d.ts

@@ -1,13 +1,22 @@
-export type DomSelectionSnapshot = Pick<Selection, 'anchorNode' | 'anchorOffset' | 'direction' | 'focusNode' | 'focusOffset' | 'isCollapsed' | 'rangeCount' | 'toString'> & {
+export type DomSelectionSnapshot = Pick<Selection, 'anchorNode' | 'anchorOffset' | 'focusNode' | 'focusOffset' | 'isCollapsed' | 'rangeCount'> & {
     getRangeAt: (index: number) => Range;
-    nativeSelection: Selection | null;
-    type?: string;
 };
 export declare const getDomSelection: (node?: Node | null) => Selection | null;
 export declare const getActiveElement: (node?: Node | null) => Element | null;
 export declare const clearDomSelection: (node?: Node | null) => void;
+/**
+ * The caret point under (`x`, `y`): `caretPositionFromPoint` (Firefox,
+ * Chromium 128, Safari 26.2), else `caretRangeFromPoint` (the supported
+ * Chromium and Safari before those).
+ */
+export declare const caretAtPoint: (doc: Document, x: number, y: number) => {
+    node: Node;
+    offset: number;
+} | null;
+/** A range in `node`'s document (a node always has one). */
 export declare const createDomRange: (node: Node) => Range;
-export declare const createDomSelectionSnapshotFromRange: (range: Range, nativeSelection?: Selection | null) => DomSelectionSnapshot;
+/** A snapshot of one range, forward. */
+export declare const createDomSelectionSnapshotFromRange: (range: Range) => DomSelectionSnapshot;
 /**
  * Scroll the caret into view after a programmatic selection write.
  *