@dou-ui/editor 0.0.0-stage → 0.1.0-alpha.0

package/dist/types/core/output.d.ts

@@ -0,0 +1,64 @@
+import type { ResolvedEditorExtensions } from './extension';
+import type { Block, InlineContent, PartialBlock } from './model';
+/** What a block's writer gets besides the block. */
+export interface BlockOutputContext {
+    /** The block's text, already written in the output format. */
+    content: string;
+    /** The block's text without formatting (e.g. for a code block). */
+    text: string;
+    /** The child blocks, already written. */
+    children: string;
+    /** The block's position, from 1, among the siblings of the same type right before it. */
+    index: number;
+    /** Write other inline content (e.g. a table cell's) in the same format. */
+    inline: (content: InlineContent[]) => string;
+}
+export interface MarkdownBlockContext extends BlockOutputContext {
+    /** The block's text as HTML, for Markdown that holds HTML (e.g. `<summary>`). */
+    html: string;
+    /** Write other inline content as HTML. */
+    inlineHTML: (content: InlineContent[]) => string;
+}
+/** How a block type is written as HTML and Markdown. */
+export interface BlockOutput {
+    html?: (block: Block, context: BlockOutputContext) => string;
+    /**
+     * Consecutive blocks with the same `group` sit in one element, written
+     * as its opening tag (e.g. `ul`, `ol`); in Markdown they are kept
+     * together without blank lines.
+     */
+    group?: string;
+    markdown?: (block: Block, context: MarkdownBlockContext) => string;
+}
+/** How an inline node (e.g. a mention) is written. */
+export interface InlineOutput {
+    html?: (props: Record<string, unknown>) => string;
+    markdown?: (props: Record<string, unknown>) => string;
+}
+/**
+ * How a mark is written: the text between an opening and a closing string.
+ * A mark with a value (a color) gives a function of the value.
+ */
+export type MarkTags = [open: string, close: string];
+export interface MarkOutput {
+    html?: MarkTags | ((value: string) => MarkTags);
+    markdown?: MarkTags | ((value: string) => MarkTags);
+}
+/** What an extension contributes to `blocksToHTML` and `blocksToMarkdown`. */
+export interface EditorExtensionOutput {
+    blocks?: Record<string, BlockOutput>;
+    inlines?: Record<string, InlineOutput>;
+    marks?: Record<string, MarkOutput>;
+}
+export declare const escapeHTML: (text: string) => string;
+/**
+ * Write blocks as HTML, e.g. to show a document outside the editor or to
+ * send it by email. Each extension decides how its blocks look; the
+ * result has no editor classes.
+ */
+export declare function writeHTML(blocks: PartialBlock[], kit: ResolvedEditorExtensions): string;
+export declare const escapeMarkdown: (text: string) => string;
+/** Put `prefix` before every line, and `rest` (default: as many spaces) before the ones after the first. */
+export declare function indentLines(text: string, prefix: string, rest?: string): string;
+/** Write blocks as Markdown (CommonMark with GitHub's extensions). */
+export declare function writeMarkdown(blocks: PartialBlock[], kit: ResolvedEditorExtensions): string;

package/dist/types/core/plugins.d.ts

@@ -0,0 +1,24 @@
+import { Plugin, type Transaction } from 'prosemirror-state';
+/**
+ * Whether a transaction came from another collaborator. Collaborative
+ * bindings mark theirs; the Yjs binding uses the `y-sync$` key.
+ */
+export declare function isRemote(tr: Transaction): boolean;
+/**
+ * Every block gets a unique id. Splitting a block copies its attributes,
+ * so the copy gets a fresh id here; the first occurrence keeps the old one.
+ * Changes from collaborators are left alone, so two editors never fight
+ * over an id.
+ */
+export declare function idPlugin(): Plugin;
+export declare function numberingPlugin(): Plugin;
+export interface PlaceholderOptions {
+    /** The hint in the empty block the cursor is in. */
+    text: () => string;
+    /** The hint in an empty heading. */
+    heading: () => string;
+    /** The hint when the whole document is one empty paragraph. */
+    empty: () => string;
+}
+/** A hint inside the empty block under the cursor, and in an empty document. */
+export declare function placeholderPlugin(options: PlaceholderOptions): Plugin;

package/dist/types/core/prepare.d.ts

@@ -0,0 +1,23 @@
+import { Plugin } from 'prosemirror-state';
+import type { ResolvedEditorExtensions } from './extension';
+import { type Block } from './model';
+/**
+ * The editor's own markup for a block: a content element of `type` holding
+ * `content`, followed by a group holding `children`. Extensions use it in
+ * `prepareHTML` to turn containers such as `<details>` into blocks.
+ */
+export declare function blockElement(doc: Document, type: string, content: Node[], children?: Node[], data?: Record<string, string>): HTMLElement;
+/**
+ * Split a container's children into its own text (the first paragraph, or
+ * the inline nodes before the first block element) and the blocks after it.
+ */
+export declare function splitContainer(element: Element): {
+    content: Node[];
+    children: Node[];
+};
+/** Run every extension's `prepareHTML` over the markup. */
+export declare function prepareElement(root: HTMLElement, kit: ResolvedEditorExtensions): void;
+/** Read HTML as blocks, with the block types, inline nodes and marks of `kit`. */
+export declare function parseHTML(html: string, kit: ResolvedEditorExtensions): Block[];
+/** Pasted HTML goes through the extensions' `prepareHTML` too. */
+export declare function preparePastePlugin(kit: ResolvedEditorExtensions): Plugin;

package/dist/types/core/schema.d.ts

@@ -0,0 +1,38 @@
+import { Schema, type DOMOutputSpec, type MarkSpec, type NodeSpec } from 'prosemirror-model';
+/**
+ * The document is a list of blocks. Each block is a `block` node holding
+ * one piece of content (a paragraph, a heading, a list item…) and,
+ * optionally, a `blockGroup` of child blocks:
+ *
+ *   doc
+ *   └─ block#id
+ *      ├─ paragraph "Hello"
+ *      └─ blockGroup
+ *         └─ block#id
+ *            └─ checkItem "Nested"
+ *
+ * The frame (doc, block, group, paragraph, text, line break) is fixed;
+ * every other content type and mark comes from an extension. Every piece
+ * of state lives in node attributes (never in a node view), so a
+ * collaborative binding can sync it like any other change.
+ */
+/** The DOM of a content node: `div.dou-editor__content--<type>[data-content-type]`. */
+export declare const contentDOM: (type: string, extra?: Record<string, string>) => DOMOutputSpec;
+/** A content type holding formatted text, parsed back from its own DOM. */
+export declare const textBlock: (type: string, spec?: Partial<NodeSpec>) => NodeSpec;
+export interface SchemaParts {
+    blocks: Record<string, NodeSpec>;
+    /** Nodes inside blocks, e.g. table rows and cells. */
+    nodes?: Record<string, NodeSpec>;
+    inlines: Record<string, NodeSpec>;
+    marks: Record<string, MarkSpec>;
+}
+/** The schema for a set of extensions' blocks, inline nodes and marks. */
+export declare function createSchema({ blocks, nodes: inner, inlines, marks }: SchemaParts): Schema;
+/** Links may only point to web pages, mail, phone numbers or relative paths. */
+export declare function isSafeHref(href: string): boolean;
+/** The content types that come with `editorKit`; extensions add more. */
+export type BuiltinContentType = 'paragraph' | 'heading' | 'bulletItem' | 'numberedItem' | 'checkItem' | 'quote' | 'codeBlock' | 'divider' | 'toggle' | 'callout' | 'table';
+export type ContentType = BuiltinContentType | (string & {});
+export type BuiltinMarkType = 'bold' | 'italic' | 'underline' | 'strike' | 'code';
+export type MarkType = BuiltinMarkType | (string & {});

package/dist/types/core/search.d.ts

@@ -0,0 +1,83 @@
+import type { Node as PMNode } from 'prosemirror-model';
+import { Plugin, PluginKey, type EditorState, type Transaction } from 'prosemirror-state';
+import { DecorationSet } from 'prosemirror-view';
+/** What to look for in the editor's text. */
+export interface EditorSearchQuery {
+    /** The text, or a regular expression with `regexp`. */
+    search: string;
+    /** What replacing puts in; with `regexp`, `$1` and `$<name>` refer to groups. */
+    replace?: string;
+    /** Tells upper and lower case apart. */
+    caseSensitive?: boolean;
+    /** Only matches that are whole words. */
+    wholeWord?: boolean;
+    /** `search` is a regular expression (JavaScript syntax). */
+    regexp?: boolean;
+}
+/** A match, as document positions. */
+export interface EditorMatch {
+    from: number;
+    to: number;
+}
+export interface EditorSearchState {
+    query: EditorSearchQuery;
+    /** Whether matches are shown; a query is kept while the panel is closed. */
+    active: boolean;
+    matches: EditorMatch[];
+    /** More matches exist than were counted. */
+    capped: boolean;
+    /** Why the regular expression can't be read, when it can't. */
+    error?: string;
+    /** The match the selection is on. */
+    current?: EditorMatch;
+    decorations: DecorationSet;
+}
+export declare const searchKey: PluginKey<EditorSearchState>;
+/** The query as one global regular expression, or the reason it can't be one. */
+export declare function queryRegExp(query: EditorSearchQuery): RegExp | string;
+/**
+ * Every match of the query in the document's text, in order, at most
+ * `limit` of them. A match stays inside one block; blocks for which
+ * `skip` says yes, such as ones that draw their own text, are left out.
+ */
+export declare function searchDoc(doc: PMNode, query: EditorSearchQuery, options?: {
+    limit?: number;
+    skip?: (node: PMNode) => boolean;
+}): {
+    matches: EditorMatch[];
+    capped: boolean;
+    error?: string;
+};
+/** The text that replaces one match: `query.replace`, with groups filled in for a regular expression. */
+export declare function replacementFor(doc: PMNode, match: EditorMatch, query: EditorSearchQuery): string;
+/** The index of the match the selection is on, or `-1`. */
+export declare function currentMatch(state: EditorState): number;
+/** The index of the first match from `pos` on, wrapping round to the first. */
+export declare function matchAfter(matches: readonly EditorMatch[], pos: number): number;
+type SearchMeta = {
+    query?: EditorSearchQuery;
+    active?: boolean;
+};
+/**
+ * Keeps the matches of the query in step with the document and marks
+ * them; the match the selection is on stands out.
+ */
+export declare function searchPlugin(options?: {
+    skip?: (node: PMNode) => boolean;
+}): Plugin;
+/** Sets the query, or shows or hides the matches, in a transaction. */
+export declare function setSearch(tr: Transaction, meta: SearchMeta): Transaction;
+/**
+ * Selects the first match from the cursor on, as a preview while the
+ * search is typed; `null` when the selection is on a match already or
+ * there is none.
+ */
+export declare function previewMatch(state: EditorState): Transaction | null;
+/** Selects a match and scrolls it into view. */
+export declare function selectMatch(state: EditorState, match: EditorMatch): Transaction;
+/**
+ * Replaces the matches given, last first so the positions stay right, in
+ * one transaction: one step to undo.
+ */
+export declare function replaceMatches(state: EditorState, matches: readonly EditorMatch[], query: EditorSearchQuery): Transaction;
+export {};

package/dist/types/core/selection.d.ts

@@ -0,0 +1,8 @@
+import type { EditorState } from 'prosemirror-state';
+/** Where the selection is, by block. */
+export interface BlockSelectionInfo {
+    block: string | null;
+    blocks: string[];
+}
+export declare function selectionOf(state: EditorState): BlockSelectionInfo;
+export declare function sameSelection(a: BlockSelectionInfo, b: BlockSelectionInfo): boolean;

package/dist/types/core/slash.d.ts

@@ -0,0 +1,21 @@
+import { Plugin, PluginKey, type EditorState } from 'prosemirror-state';
+import type { EditorView } from 'prosemirror-view';
+/**
+ * The slash menu's state: open from the `/` at `from` to the cursor,
+ * with the text typed after it as the query. A Chinese keyboard types
+ * `、` for the same key, so that opens it too.
+ */
+export interface SlashState {
+    from: number;
+    query: string;
+}
+export declare const slashKey: PluginKey<SlashState | null>;
+export interface SlashOptions {
+    /** The menu reads the state; called whenever it changes. */
+    onChange: (state: SlashState | null, view: EditorView) => void;
+    /** Keys go to the open menu first: arrows, `Enter`, `Tab`. Return whether it took the key. */
+    onKey: (event: KeyboardEvent) => boolean;
+}
+export declare function getSlash(state: EditorState): SlashState | null;
+export declare function closeSlash(view: EditorView): void;
+export declare function slashPlugin(options: SlashOptions): Plugin<SlashState | null>;

package/dist/types/core/transaction.d.ts

@@ -0,0 +1,97 @@
+import { Selection, type EditorState, type Transaction } from 'prosemirror-state';
+import { type BlockInfo } from './blocks';
+import { type Block, type BlockProps, type InlineContent, type PartialBlock, type PartialTableRow } from './model';
+import type { ContentType } from './schema';
+import type { EditorView } from 'prosemirror-view';
+/**
+ * Where blocks go: right before or after a block, or among a block's
+ * children (`parent: null` is the top level). `index` counts from 0 and
+ * defaults to the end.
+ */
+export type BlockPlacement = {
+    before: string;
+} | {
+    after: string;
+} | {
+    parent: string | null;
+    index?: number;
+};
+/** The parts of a block to change. `props` are merged into the current ones. */
+export interface BlockPatch {
+    type?: ContentType;
+    props?: BlockProps;
+    /** Inline content, or plain text. */
+    content?: InlineContent[] | string;
+    rows?: PartialTableRow[];
+    /** Replaces all children; `[]` removes them. */
+    children?: PartialBlock[];
+}
+export interface EditorTransactionMeta {
+    /** `false` keeps the change out of undo, e.g. a fix made by the program. */
+    history?: boolean;
+    /** Who made the change; passed on to the `transaction` event. */
+    origin?: string;
+}
+/** Where a selection is put inside a block: at the start of its text or at the end. */
+export type BlockEdge = 'start' | 'end';
+/**
+ * Set on a transaction that is an undo step of its own, for history
+ * providers other than the built-in one (collaboration reads it).
+ */
+export declare const ownStepKey = "douOwnStep";
+/**
+ * Changes made by blocks and ids, applied together as one undo step. Ids
+ * are looked up in the document as it is after the earlier calls.
+ */
+export declare class EditorTransaction {
+    /** The state the changes start from. */
+    readonly before: EditorState;
+    /**
+     * Whether the selection was placed by the user or the program. An editor
+     * that never had focus has its selection at the start, which is no cursor.
+     */
+    private readonly hasCursor;
+    /** The ProseMirror transaction underneath, for anything the methods don't cover. */
+    readonly tr: Transaction;
+    readonly meta: EditorTransactionMeta;
+    /** `focusBlock` was called: the editor takes focus once the changes are applied. */
+    focused: boolean;
+    constructor(
+    /** The state the changes start from. */
+    before: EditorState, meta?: EditorTransactionMeta, 
+    /**
+     * Whether the selection was placed by the user or the program. An editor
+     * that never had focus has its selection at the start, which is no cursor.
+     */
+    hasCursor?: boolean);
+    get changed(): boolean;
+    setMeta(meta: EditorTransactionMeta): this;
+    /** A block as it is now, or `null`. */
+    getBlock(id: string): Block | null;
+    /**
+     * Insert blocks, by default after the block with the cursor (at the end
+     * without one). Returns the new blocks' ids; an id already in the
+     * document is replaced with a fresh one.
+     */
+    insertBlocks(blocks: PartialBlock[], placement?: BlockPlacement): string[];
+    /** Change a block's type, props, content or children. Returns `false` when it isn't found. */
+    updateBlock(id: string, patch: BlockPatch): boolean;
+    /** Remove blocks with their children. The document always keeps one block. */
+    removeBlocks(ids: string[]): boolean;
+    /**
+     * Move blocks, in the order given, to `placement`. Fails when it is
+     * inside one of them.
+     */
+    moveBlocks(ids: string[], placement: BlockPlacement): boolean;
+    /** Put the cursor at the start or end of a block's text (or select a block without text). */
+    focusBlock(id: string, edge?: BlockEdge): boolean;
+    /** After the selection's block, or at the end. */
+    private defaultPlacement;
+}
+/** A cursor at the start or end of a block's text; a node selection for a block without text. */
+export declare function selectionIn(tr: Transaction, info: BlockInfo, edge: BlockEdge): Selection;
+/**
+ * Apply a transaction made with `transact`: one undo step of its own,
+ * unless `history` is `false`. Returns whether anything happened.
+ */
+export declare function applyEditorTransaction(view: EditorView, transaction: EditorTransaction): boolean;

package/dist/types/define-block.d.ts

@@ -0,0 +1,66 @@
+import type { NodeSpec } from 'prosemirror-model';
+import type { NodeViewConstructor } from 'prosemirror-view';
+import { type AppContext, type Component, type InjectionKey, type PropType } from 'vue';
+import type { BlockOption, EditorExtension, Label, MountComponent } from './core/extension';
+import type { BlockProps } from './core/model';
+/** What a block's Vue component receives. */
+export interface BlockViewProps {
+    /** The block's id, type and current props. */
+    block: {
+        id: string;
+        type: string;
+        props: BlockProps;
+    };
+    /** Change props; the change goes into the document, the undo history and collaboration. */
+    updateProps: (props: BlockProps) => void;
+    /** The block is selected as a whole (a block without text was clicked). */
+    selected: boolean;
+    editable: boolean;
+}
+export interface DefineBlockOptions {
+    type: string;
+    /** The props and their defaults. They are stored in the document, as `Block.props`. */
+    props?: Record<string, unknown>;
+    /** `inline` holds formatted text; `none` has no text (an image, an embed). Defaults to `inline`. */
+    content?: 'inline' | 'none';
+    /** Renders the block. Put `<EditorContent />` where the text goes. */
+    component?: Component;
+    /** `Enter` at the end continues with the same type, like a list. */
+    continues?: boolean;
+    /** Entries for the slash menu and the “turn into” menus; one is made from `menu` when given. */
+    menu?: Omit<BlockOption, 'key' | 'type'> & {
+        key?: string;
+    };
+    /** Override the ProseMirror spec, e.g. `parseDOM` for pasting HTML from elsewhere. */
+    spec?: Partial<NodeSpec>;
+}
+/** Where a block component's text goes. */
+export declare const EditorContent: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
+    as: {
+        type: PropType<string>;
+        default: string;
+    };
+}>, () => import("vue").VNode<import("vue").RendererNode, import("vue").RendererElement, {
+    [key: string]: any;
+}>, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<{
+    as: {
+        type: PropType<string>;
+        default: string;
+    };
+}>> & Readonly<{}>, {
+    as: string;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+/** Renders components inside an app, with values provided to them. */
+export declare function componentMounter(appContext: AppContext | null, provides?: [InjectionKey<unknown>, unknown][]): MountComponent;
+/**
+ * A node view that renders a Vue component. Everything the component shows
+ * besides the text is outside the editable content, so its buttons and
+ * inputs work as usual.
+ */
+export declare function vueNodeView(component: Component, appContext: AppContext | null, provides?: [InjectionKey<unknown>, unknown][]): NodeViewConstructor;
+/**
+ * Declare a block type rendered by a Vue component (or by plain DOM), with
+ * its props stored in the document. Returns an extension for `extensions`.
+ */
+export declare function defineBlock(options: DefineBlockOptions): EditorExtension;
+export type { Label };

package/dist/types/document.d.ts

@@ -0,0 +1,46 @@
+import { type EditorExtensionList } from './core/convert';
+import type { Block, EditorDocument, PartialBlock } from './core/model';
+/** A document with no blocks, to start from when nothing is saved yet. */
+export declare const emptyDocument: () => EditorDocument<Block>;
+export interface DocumentProblem {
+    code: 'version' | 'shape' | 'duplicate-id' | 'unknown-type' | 'unknown-mark' | 'unknown-inline';
+    /** The block at fault, when it has an id. */
+    blockId?: string;
+    /**
+     * Where the problem is, as a path into the document, e.g.
+     * `blocks[0].children[2]` or `blocks[1].content[0]`; `version` for the version.
+     */
+    path: string;
+    /** The id, type, mark or inline node at fault, for the editor's message. */
+    text: string;
+    /** An English description, for logs. */
+    message: string;
+}
+export interface CheckDocumentOptions {
+    /** The editor's `extensions`, for the blocks, marks and inline nodes they add; `[editorKit()]` by default, as in the editor. */
+    extensions?: EditorExtensionList;
+}
+/**
+ * The problems of an editor document, before it is saved or shown: an
+ * unknown version, blocks or table rows sharing an id, and block types,
+ * marks and inline nodes the extensions don't define, which the editor
+ * would show as a paragraph or leave out.
+ */
+export declare function checkDocument(document: EditorDocument<PartialBlock>, options?: CheckDocumentOptions): DocumentProblem[];
+/**
+ * Brings a saved document up to the current version, and fills what an
+ * older or hand-written one may lack (`version`, `blocks`). Blocks that are
+ * not objects are dropped; anything else is kept as it is, for the editor
+ * to read as it reads partial blocks. Throws for data that is not an object (an array,
+ * `null`, a string) and for a version it does not know.
+ */
+export declare function migrateDocument(input: unknown): EditorDocument<PartialBlock>;
+/**
+ * The blocks of the `v-model`, as the editor reads them. A document of the
+ * wrong shape (not an object, a bare list of blocks, without `blocks` or a
+ * known `version`) gets a warning in development and is read as well as it
+ * can be: a list as the blocks, anything else missing as no blocks. What
+ * the editor writes back always carries `version: 1`. `undefined`, no
+ * `v-model` bound, is fine.
+ */
+export declare function readBlocks(value: unknown): PartialBlock[] | undefined;

package/dist/types/dom.d.ts

@@ -0,0 +1,17 @@
+import type { EditorView } from 'prosemirror-view';
+/**
+ * The content element (paragraph, heading, …) at height `y` in viewport
+ * coordinates: the last one whose top is above it. Contents follow each
+ * other from top to bottom in document order, nested ones included, so
+ * a binary search does.
+ */
+export declare function contentAt(view: EditorView, y: number): HTMLElement | null;
+/** The block element around a content element. */
+export declare function blockElementOf(content: HTMLElement): HTMLElement | null;
+/** The nearest ancestor that scrolls vertically, or `null` for the page. */
+export declare function scrollParent(element: HTMLElement): HTMLElement | null;
+/** Where the first line of a content element sits: its top and height. */
+export declare function firstLine(content: HTMLElement): {
+    top: number;
+    height: number;
+};