@x12i/editor 1.0.0 → 1.1.0

package/dist/react.d.ts

@@ -0,0 +1,546 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+import { Block, EditorDocument, OutlineItem, ConversionWarning, AiProvider, AiCommand } from './index.js';
+import * as _tiptap_core from '@tiptap/core';
+import { Extensions, Editor as Editor$1, JSONContent } from '@tiptap/core';
+import { SuggestionProps, SuggestionKeyDownProps } from '@tiptap/suggestion';
+import '@x12i/charts';
+import '@x12i/data';
+import '@x12i/diagrams';
+
+/** The block kinds a person can insert or turn a block into. */
+type BlockKind = "paragraph" | "heading1" | "heading2" | "heading3" | "heading4" | "quote" | "callout" | "toggle" | "bulletList" | "numberedList" | "taskList" | "code" | "equation" | "divider" | "table" | "image" | "video" | "audio" | "file" | "bookmark" | "columns" | "pageBreak" | "toc" | "chart" | "diagram" | "dataView" | "ai";
+declare const BLOCK_KINDS: readonly BlockKind[];
+type BlockMessage = {
+    name: string;
+    description: string;
+    /** Extra words that find the block in the slash menu. Space separated. */
+    keywords: string;
+};
+type SlashGroup = "basic" | "lists" | "media" | "advanced" | "embeds";
+interface Messages {
+    editorLabel: string;
+    placeholder: string;
+    viewLabel: string;
+    toolbar: {
+        label: string;
+        undo: string;
+        redo: string;
+        blockType: string;
+        bold: string;
+        italic: string;
+        underline: string;
+        strike: string;
+        code: string;
+        highlight: string;
+        textColor: string;
+        clearColor: string;
+        link: string;
+        bulletList: string;
+        numberedList: string;
+        taskList: string;
+        indent: string;
+        outdent: string;
+        quote: string;
+        divider: string;
+        table: string;
+        image: string;
+        selectionMenu: string;
+    };
+    /** Names for the color and highlight palettes, by token path. */
+    tokens: Record<string, string>;
+    blocks: Record<BlockKind, BlockMessage>;
+    groups: Record<SlashGroup, string>;
+    callouts: Record<"info" | "success" | "warning" | "danger" | "neutral", string>;
+    slash: {
+        label: string;
+        noResults: string;
+        resultCount: string;
+        instructions: string;
+    };
+    blockMenu: {
+        label: string;
+        trigger: string;
+        duplicate: string;
+        delete: string;
+        turnInto: string;
+        moveUp: string;
+        moveDown: string;
+        insertBelow: string;
+    };
+    table: {
+        addRowBefore: string;
+        addRowAfter: string;
+        addColumnBefore: string;
+        addColumnAfter: string;
+        deleteRow: string;
+        deleteColumn: string;
+        toggleHeaderRow: string;
+        toggleHeaderColumn: string;
+        deleteTable: string;
+        controls: string;
+    };
+    linkDialog: {
+        title: string;
+        urlLabel: string;
+        urlHint: string;
+        invalid: string;
+        required: string;
+        apply: string;
+        remove: string;
+        cancel: string;
+    };
+    imageDialog: {
+        title: string;
+        editTitle: string;
+        urlLabel: string;
+        altLabel: string;
+        altHint: string;
+        altRequired: string;
+        decorative: string;
+        captionLabel: string;
+        urlRequired: string;
+        urlInvalid: string;
+        insert: string;
+        update: string;
+        cancel: string;
+    };
+    code: {
+        language: string;
+        plainText: string;
+        copy: string;
+        copied: string;
+    };
+    task: {
+        done: string;
+        todo: string;
+        emptyLabel: string;
+    };
+    toggle: {
+        expand: string;
+        collapse: string;
+        summaryPlaceholder: string;
+    };
+    equation: {
+        label: string;
+        placeholder: string;
+    };
+    embed: {
+        groupLabel: string;
+        untitled: string;
+        edit: string;
+        remove: string;
+        moveUp: string;
+        moveDown: string;
+        toolbar: string;
+        request: string;
+        previewHint: string;
+        showData: string;
+        dataset: string;
+        prompt: string;
+        result: string;
+        engine: string;
+        unknown: string;
+    };
+    media: {
+        file: string;
+        download: string;
+        bookmark: string;
+        open: string;
+        unsafe: string;
+        image: string;
+        imageDecorative: string;
+        imageEdit: string;
+        video: string;
+        audio: string;
+        urlLabel: string;
+        nameLabel: string;
+        set: string;
+    };
+    ai: {
+        menuLabel: string;
+        improve: string;
+        shorten: string;
+        continue: string;
+        fixGrammar: string;
+        custom: string;
+        customLabel: string;
+        run: string;
+        accept: string;
+        reject: string;
+        cancel: string;
+        generating: string;
+        preview: string;
+        error: string;
+        noSelection: string;
+        done: string;
+        /** Instructions handed to the provider as the `tone` of a rewrite. */
+        prompts: {
+            improve: string;
+            shorten: string;
+            continue: string;
+        };
+    };
+    status: {
+        saved: string;
+        markOn: string;
+        markOff: string;
+        blockMoved: string;
+        blockMovedUp: string;
+        blockMovedDown: string;
+        blockDuplicated: string;
+        blockDeleted: string;
+        blockTurnedInto: string;
+        linkApplied: string;
+        linkRemoved: string;
+        imageInserted: string;
+        copied: string;
+        undone: string;
+        redone: string;
+        aiApplied: string;
+        cannotMove: string;
+    };
+    directions: {
+        up: string;
+        down: string;
+    };
+}
+declare const defaultMessages: Messages;
+type DeepPartial<T> = {
+    [K in keyof T]?: T[K] extends Record<string, unknown> ? DeepPartial<T[K]> : T[K];
+};
+/** Overlays a partial table on a base table. Missing keys keep the base text. */
+declare function mergeMessages(base: Messages, overrides?: DeepPartial<Messages>): Messages;
+/**
+ * Fills `{name}` placeholders and `{name, plural, one {...} other {...}}`
+ * blocks (`#` stands for the number). Unknown names stay as written.
+ */
+declare function formatMessage(template: string, values?: Record<string, string | number>, locale?: string): string;
+/** A translator bound to one message table. */
+interface Translator {
+    messages: Messages;
+    locale: string | undefined;
+    /** Formats a template from the table. */
+    format: (template: string, values?: Record<string, string | number>) => string;
+}
+declare function createTranslator(messages: Messages, locale?: string): Translator;
+/** Reads the translator of the nearest editor. */
+declare function useTranslator(): Translator;
+/** Reads the message table of the nearest editor. */
+declare function useMessages(): Messages;
+
+/** The block types that render through an injected renderer instead of editor content. */
+type EmbedType = "chart" | "diagram" | "data-view" | "ai";
+type ChartBlock = Extract<Block, {
+    type: "chart";
+}>;
+type DiagramBlock = Extract<Block, {
+    type: "diagram";
+}>;
+type DataViewBlock = Extract<Block, {
+    type: "data-view";
+}>;
+type AiBlock = Extract<Block, {
+    type: "ai";
+}>;
+/** The data each embedded block carries. These are the payloads of the stored document. */
+interface EmbedPayloads {
+    chart: ChartBlock["spec"];
+    diagram: {
+        engine: DiagramBlock["engine"];
+        diagram?: DiagramBlock["diagram"];
+        source?: string;
+    };
+    "data-view": {
+        dataset: DataViewBlock["dataset"];
+        view: DataViewBlock["view"];
+    };
+    ai: {
+        prompt: AiBlock["prompt"];
+        result?: AiBlock["result"];
+    };
+}
+interface BlockRendererProps<T extends EmbedType = EmbedType> {
+    type: T;
+    /** The block id from the document. */
+    id: string;
+    payload: EmbedPayloads[T];
+    /** A short, human readable title taken from the payload, when it has one. */
+    title: string;
+    /** False in `EditorView` and when the editor is read-only. */
+    editable: boolean;
+    /** True while the block is the selection of the editor. */
+    selected: boolean;
+}
+/**
+ * Renderers for embedded blocks. The editor never imports chart, diagram or
+ * data components: pass the ones your app uses. A missing renderer falls back
+ * to an accessible JSON summary card.
+ *
+ * Each renderer is mounted as a React component (not called as a function), so
+ * it may use hooks. Keep the renderer functions stable between renders (define
+ * them at module level or memoize the object): a new function identity makes
+ * React remount that block and lose its state. A renderer that throws is
+ * caught by an error boundary and replaced by the fallback card.
+ */
+type BlockRenderers = {
+    [K in EmbedType]?: (props: BlockRendererProps<K>) => ReactNode;
+} & {
+    /** Renders a block of a type this version does not know. Receives the stored data. */
+    unknown?: (props: {
+        id: string;
+        blockType: string;
+        payload: Record<string, unknown>;
+        editable: boolean;
+    }) => ReactNode;
+};
+type BlockPayload<T extends EmbedType = EmbedType> = EmbedPayloads[T];
+/** Called when a person asks to edit an embedded block. Resolve with the new payload, or `null` to cancel. */
+type EditBlockHandler = <T extends EmbedType>(type: T, payload: EmbedPayloads[T]) => Promise<EmbedPayloads[T] | null | undefined> | EmbedPayloads[T] | null | undefined;
+/** Called when a person inserts a chart, diagram, data view or AI block. Resolve with its payload, or `null` to cancel. */
+type RequestBlockHandler = <T extends EmbedType>(type: T) => Promise<EmbedPayloads[T] | null | undefined> | EmbedPayloads[T] | null | undefined;
+/** A command for `EditorApi.exec`. */
+type EditorCommand = "undo" | "redo" | "bold" | "italic" | "underline" | "strike" | "code" | "clearMarks" | "bulletList" | "numberedList" | "taskList" | "indent" | "outdent" | "quote" | "divider" | "paragraph" | "heading1" | "heading2" | "heading3" | "heading4" | "codeBlock" | "moveBlockUp" | "moveBlockDown" | "duplicateBlock" | "deleteBlock" | "selectAll" | "openBlockMenu";
+interface SelectionInfo {
+    /** True when the selection is a caret. */
+    empty: boolean;
+    /** The selected text, or an empty string. */
+    text: string;
+    /** Id of the block the selection starts in, when known. */
+    blockId: string | null;
+    /** Marks active at the selection, such as `bold`. */
+    marks: string[];
+    /** The kind of the block the selection is in, such as `heading2`. */
+    blockKind: BlockKind | null;
+}
+/** The imperative handle of an `Editor`. */
+interface EditorApi {
+    /** The current document in the kit's own format. */
+    getDocument(): EditorDocument;
+    /** Replaces the whole document. Does not call `onChange`. */
+    setDocument(doc: EditorDocument): void;
+    focus(position?: "start" | "end"): void;
+    /** Inserts a block after the selection (or in place of an empty paragraph). Returns the new block id when known. */
+    insertBlock(type: BlockKind | Block["type"], attrs?: Record<string, unknown>): Promise<string | null>;
+    exec(command: EditorCommand): boolean;
+    getMarkdown(): string;
+    getOutline(): OutlineItem[];
+    /** The underlying Tiptap editor, for advanced use. It may be null before the first mount. */
+    getEngine(): _tiptap_core.Editor | null;
+    /** Announces a message through the editor's status region. */
+    announce(message: string): void;
+}
+interface EditorProps {
+    /** Controlled document. */
+    value?: EditorDocument;
+    /** Uncontrolled initial document. */
+    defaultValue?: EditorDocument;
+    /** Called after edits with the new document. */
+    onChange?: (doc: EditorDocument) => void;
+    /** Milliseconds to wait after the last edit before `onChange`. Default 0 (each edit). */
+    debounce?: number;
+    /** Defaults to true. */
+    editable?: boolean;
+    placeholder?: string;
+    autoFocus?: boolean | "start" | "end";
+    blockRenderers?: BlockRenderers;
+    /** Extra Tiptap extensions. They are read once when the editor mounts. */
+    extensions?: Extensions;
+    messages?: DeepPartial<Messages>;
+    /** BCP 47 tag used for plurals, word counts and spell checking. */
+    locale?: string;
+    "aria-label"?: string;
+    "aria-labelledby"?: string;
+    /** Called once with the imperative API when the editor is ready. */
+    onReady?: (api: EditorApi) => void;
+    onSelectionChange?: (selection: SelectionInfo) => void;
+    onEditBlock?: EditBlockHandler;
+    onRequestBlock?: RequestBlockHandler;
+    /** Called with conversion warnings (unknown blocks, dropped marks) when the document loads or changes. */
+    onWarnings?: (warnings: ConversionWarning[]) => void;
+    /** Shows the formatting toolbar above the content. Defaults to true. */
+    toolbar?: boolean;
+    /** Shows a floating menu over selected text. Defaults to true. */
+    selectionMenu?: boolean;
+    /** Enables the "/" slash menu. Defaults to true. */
+    slashMenu?: boolean;
+    /** Connects the AI assistant menu to a provider. Without one the AI menu is hidden. */
+    aiProvider?: AiProvider;
+    className?: string;
+    /** Extra content placed after the toolbar, for example a save button. */
+    toolbarEnd?: ReactNode;
+    ref?: React.Ref<EditorApi>;
+}
+interface EditorViewProps {
+    value: EditorDocument;
+    blockRenderers?: BlockRenderers;
+    messages?: DeepPartial<Messages>;
+    locale?: string;
+    className?: string;
+    "aria-label"?: string;
+    "aria-labelledby"?: string;
+    /** Prefix for heading ids, so two views on a page do not clash. Defaults to `kit-`. */
+    idPrefix?: string;
+}
+
+/**
+ * The block editor. Pass a document (`value` or `defaultValue`) in the kit's
+ * own JSON format and read the edited document back through `onChange` or
+ * the `ref`. The editing engine (Tiptap) stays behind this boundary.
+ *
+ * Until the engine mounts (on the server and during hydration) the component
+ * renders the document read-only, so the content is in the first HTML.
+ */
+declare function Editor(props: EditorProps): react.JSX.Element;
+
+/**
+ * Renders a document read-only without the editor engine, so it works on the
+ * server and in lists of many documents. Embedded blocks render through
+ * `blockRenderers`, like in the editor.
+ */
+declare function EditorView({ value, blockRenderers, messages, locale, className, idPrefix, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledby, }: EditorViewProps): react.JSX.Element;
+
+interface EditorToolbarProps {
+    editor: Editor$1 | null;
+    /** Opens the link dialog. Without it the link button is hidden. */
+    onOpenLink?: () => void;
+    /** Opens the image dialog. Without it the image button is hidden. */
+    onOpenImage?: () => void;
+    /** Opens the block actions menu. Without it the button is hidden. */
+    onOpenBlockMenu?: () => void;
+    /** Opens the AI menu. Without it the button is hidden. */
+    onOpenAi?: () => void;
+    /** Speaks a message through a status region. */
+    announce?: (message: string) => void;
+    /** Extra controls after the built-in ones. */
+    children?: ReactNode;
+    className?: string;
+}
+/**
+ * The formatting toolbar: a WAI-ARIA toolbar with one tab stop, arrow keys
+ * between controls, `aria-pressed` on toggles and a tooltip on every control.
+ */
+declare function EditorToolbar({ editor, onOpenLink, onOpenImage, onOpenBlockMenu, onOpenAi, announce, children, className }: EditorToolbarProps): react.JSX.Element;
+
+type AiStatus = "idle" | "running" | "preview" | "error";
+interface UseAiAssistOptions {
+    provider: AiProvider | undefined;
+    editor: Editor$1 | null;
+    /** Called with a short message at each step, for a live region. */
+    announce?: (message: string) => void;
+}
+interface RunOptions {
+    /** Passed to the provider as `tone`; for `rewrite` it is the instruction. */
+    tone?: string;
+}
+interface UseAiAssist {
+    /** False without a provider; the AI menu stays hidden then. */
+    available: boolean;
+    status: AiStatus;
+    command: AiCommand | null;
+    /** The suggestion so far. Grows while `status` is `running`. */
+    preview: string;
+    error: string | null;
+    /** Streams a suggestion for the selection (or the text before the caret for `continue`). */
+    run: (command: AiCommand, options?: RunOptions) => Promise<void>;
+    /** Writes the suggestion into the document. */
+    accept: () => void;
+    /** Discards the suggestion. */
+    reject: () => void;
+    /** Stops a running request, keeping what arrived as the preview. */
+    cancel: () => void;
+}
+/** Plain text to Tiptap content: blank lines split paragraphs, single newlines become hard breaks. */
+declare function textToContent(text: string): JSONContent[];
+/**
+ * Connects the editor to an `AiProvider`. The kit calls no model itself: the
+ * provider streams text, the hook shows it as a preview, and nothing touches
+ * the document until `accept` is called.
+ */
+declare function useAiAssist({ provider, editor, announce }: UseAiAssistOptions): UseAiAssist;
+
+interface AiAssistMenuProps {
+    assist: UseAiAssist;
+    editor: Editor$1;
+    onClose: () => void;
+}
+/**
+ * A small panel for the AI assistant: pick an action, watch the suggestion
+ * stream in, then accept or reject it. Nothing is written to the document
+ * until Accept. It is not modal; Escape closes it and returns to the text.
+ */
+declare function AiAssistMenu({ assist, editor, onClose }: AiAssistMenuProps): react.JSX.Element;
+
+interface EmbedPreviewProps {
+    type: EmbedType;
+    payload: unknown;
+    title: string;
+}
+/** The default look of a chart, diagram, data view or AI block: a summary card with the raw data. */
+declare function EmbedPreview({ type, payload, title }: EmbedPreviewProps): react.JSX.Element;
+
+/** What node views and menus need from the `Editor` that hosts them. */
+interface EditorUi {
+    editable: boolean;
+    blockRenderers: BlockRenderers;
+    /** Speaks a message through the status live region. */
+    announce: (message: string) => void;
+    onEditBlock: EditBlockHandler | undefined;
+    onRequestBlock: RequestBlockHandler | undefined;
+    /** Opens the image dialog for the image at `pos`, or for a new image. */
+    openImageDialog: (pos?: number) => void;
+    /** Opens the link dialog for the selection. */
+    openLinkDialog: () => void;
+    /** Opens the block menu for the block at the selection. */
+    openBlockMenu: () => void;
+}
+
+interface SlashItem {
+    kind: BlockKind;
+    group: SlashGroup;
+    name: string;
+    description: string;
+}
+/** The React side of the slash menu. The suggestion plugin calls into it. */
+interface SlashBridge {
+    onStart: (props: SuggestionProps<SlashItem, SlashItem>) => void;
+    onUpdate: (props: SuggestionProps<SlashItem, SlashItem>) => void;
+    onKeyDown: (props: SuggestionKeyDownProps) => boolean;
+    onExit: () => void;
+}
+/**
+ * What extensions read from the React tree at the moment they need it.
+ * Extensions are created once; the React component refreshes these getters on
+ * every render, so callbacks and messages are never stale.
+ */
+interface EditorRuntime {
+    ui: () => EditorUi;
+    translator: () => Translator;
+    placeholder: () => string;
+    slashEnabled: () => boolean;
+    slash: SlashBridge | null;
+}
+declare function createRuntime(): EditorRuntime;
+
+interface CreateExtensionsOptions {
+    runtime: EditorRuntime;
+    /** Extensions from the `extensions` prop. */
+    extra?: Extensions;
+}
+/**
+ * The editor schema. Node and mark names match `TIPTAP_NODES` and
+ * `TIPTAP_MARKS`, which the converters in the root entry read and write.
+ */
+declare function createExtensions({ runtime, extra }: CreateExtensionsOptions): Extensions;
+
+/** All insertable blocks with localized names, ordered by group. */
+declare function allSlashItems(messages: Messages): SlashItem[];
+/**
+ * Filters and ranks slash menu items as the person types: names that start
+ * with the query first, then words that start with it, then substrings.
+ * Names, descriptions and keywords are all searched, in the active language.
+ */
+declare function filterSlashItems(query: string, messages: Messages, items?: readonly SlashItem[]): SlashItem[];
+
+export { AiAssistMenu, BLOCK_KINDS, Editor, EditorToolbar, EditorView, EmbedPreview, allSlashItems, createExtensions, createRuntime, createTranslator, defaultMessages, filterSlashItems, formatMessage, mergeMessages, textToContent, useAiAssist, useMessages, useTranslator };
+export type { AiAssistMenuProps, AiStatus, BlockKind, BlockMessage, BlockPayload, BlockRendererProps, BlockRenderers, CreateExtensionsOptions, DeepPartial, EditBlockHandler, EditorApi, EditorCommand, EditorProps, EditorRuntime, EditorToolbarProps, EditorViewProps, EmbedPayloads, EmbedPreviewProps, EmbedType, Messages, RequestBlockHandler, RunOptions, SelectionInfo, SlashGroup, SlashItem, Translator, UseAiAssist, UseAiAssistOptions };