quoin-editor 0.4.2 → 1.0.0

package/dist/index.d.ts

@@ -1,154 +1,242 @@
-import * as React from 'react';
+import * as react from 'react';
 import { ComponentType } from 'react';
-import { LucideIcon } from 'lucide-react';
+import { A as AnyBlockDefinition, U as UploadFn, C as CodeHighlighter, a as UploadResult } from './registry-CWBOSAHm.js';
+export { B as BlockDefinition, b as BlockEditorProps, c as BlockPreviewProps, e as CodeToken, f as blockByType, d as defineBlock, p as paletteBlocks } from './registry-CWBOSAHm.js';
+import { Q as QuoinBlock, P as Pos } from './types-DULc8wwg.js';
+export { b as AtomNode, c as AtomSpec, A as Attrs, B as BlockAttrs, d as BlockContent, e as BlockFlow, f as BlockRangeSelection, g as BlockSpec, C as CodecContext, h as EngineBlock, E as EngineDoc, I as Inline, i as InlineCodec, j as InlineNode, M as Mark, k as MarkSpec, l as MarkdownExportContext, N as NodeSelection, m as ParseInlineOptions, S as Schema, a as Selection, n as SerializeInlineOptions, T as TextNode, o as TextSelection } from './types-DULc8wwg.js';
+import { E as Extension, a as Editor, c as EditorState, b as Command } from './types-a1CRBlEh.js';
+export { A as Align, e as Assoc, B as BlockStructureOptions, f as BoundCommands, g as Chain, C as CommandFactories, h as CoreCommands, i as CoreExtensionOptions, j as CreatedBlock, k as DOMParserLike, D as Decoration, l as EditorOptions, F as FromHTMLOptions, I as InputRule, m as InputRuleContext, n as InputRuleRange, o as InsertTextOptions, K as KeyLike, M as MarkdownOptions, p as PasteRule, P as PluginKey, d as PluginSpec, q as PosMap, r as Slice, S as Step, s as StepJSON, t as StepResult, u as TextStats, T as Transaction, v as TransactionOrigin, w as applyTransaction, x as coreExtensions, y as createEditor, z as createPluginKey, G as createState, H as fromHTML, J as getPluginState, L as insertBlockAfter, N as insertText, O as insertTextWithRules, Q as keyName, R as normalizeKey, U as setBlockType, V as toggleMark } from './types-a1CRBlEh.js';
+import { PALETTE } from './engine.js';
+export { AttrsPatch, BlockChange, BlockCodec, BlockDiff, FromMarkdownOptions, InlineChange, SchemaInput, ToMarkdownOptions, addMarkStep, atom, blockInputRules, blockRangeSelection, coreBlockSpecs, countDoc, countText, createBlockCodec, createSchema, defineExtension, diffBlocks, diffInline, fromMarkdown, insertBlocksStep, joinBlocksStep, markInputRules, moveBlocksStep, nodeSelection, normalizeInline, parseInline, redo, removeBlocksStep, removeMarkStep, replaceBlockStep, replaceDocStep, replaceInlineStep, sanitizeHref, serializeInline, setAttrsStep, setIndentStep, splitBlockStep, stepFromJSON, text, textSelection, toMarkdown, toPlainText, typographyRules, undo } from './engine.js';
+import { V as ViewController, R as RenderOptions } from './view-controller-UbpzblGl.js';
+export { A as AtomRenderer, K as KeyInterceptor, a as ViewControllerOptions, W as WidgetRenderer, h as hostKey } from './view-controller-UbpzblGl.js';
+import { BlockRenderer } from './headless.js';
+export { BlockLabel, BlockPlaceholder, BlockRenderProps, BlockShell, DomMap, DomPoint, EditableRegion, EditableRegionProps, EditorView, EditorViewProps, SelectionSink, UseQuoinEditorOptions, VoidBlockFallback, caretFromPoint, defaultRenderers, domMapOf, isCrossSelection, renderInline, useEditorState, useQuoinEditor, useViewController } from './headless.js';
+export { E as EmbedProvider, a as EmbedUrl } from './embed-provider-jXwlRmnp.js';
+export { H as HTMLOptions, t as toHTML } from './to-html-C5t7xyaM.js';
 
-/** A document is an ordered array of these; `type` is looked up in the registered block definitions. */
-type QuoinBlock = {
-    id: string;
-    type: string;
-    data: Record<string, unknown>;
-};
-/** What your upload function resolves with so Quoin can reference the stored file later. */
-type UploadResult = {
-    /** Opaque key your storage uses to find the file again. */
-    storageKey: string;
-    filename: string;
-    size: number;
-    /** Your own record id for the file, if you track one. */
-    assetId?: string;
-};
-/**
- * Stores a file and returns its key. Quoin never performs the request itself.
- * `category` names what the file is for (for example an image or a recording) so you can route it.
- * Reject with an Error whose message is safe to show the user: it is rendered
- * verbatim beside the upload button. A non-Error rejection or an empty message shows a generic "Upload failed." instead.
- * A raw `fetch` rejection such as "Failed to fetch" would surface verbatim, so catch and rethrow with your own wording.
- * The control is disabled while an upload is in flight.
- */
-type UploadFn = (file: File, category: string) => Promise<UploadResult>;
-/** Props for a block's read-only rendering, which is what you see for every block you are not editing. */
-type BlockPreviewProps<D = Record<string, unknown>> = {
-    data: D;
-    /** Id of the block being drawn, for anchors and keys. */
-    blockId?: string;
-};
-/** Props for a block's editing surface; call `onChange` with the whole next data, not a patch. */
-type BlockEditorProps<D = Record<string, unknown>> = {
-    data: D;
-    onChange: (data: D) => void;
-    /** Inserts a new block of the given type after this one. */
-    onInsertBlock?: (type: string) => void;
-    /** Leaves edit mode and returns to the preview. */
-    onDone?: () => void;
-};
+type PaletteName = (typeof PALETTE)[number];
 
-/** The fields every block definition carries, whatever it can do with its data. */
-type BlockDefinitionCommon<D extends object> = {
-    type: string;
-    label: string;
-    icon: LucideIcon;
-    /**
-     * Called when a new block of this type is inserted, to seed its data.
-     * `NoInfer` keeps `D` inferred from `editor` and `preview` alone, so the seed is checked
-     * against the editor's data type instead of widening it.
-     */
-    initialData?: () => NoInfer<D>;
-    /** Whether the block is offered in the slash palette and inserter; defaults to true. */
-    inSlashPalette?: boolean;
-    /**
-     * Renders this block's editor permanently instead of a preview you click to edit.
-     * Also supply a `preview`: a read-only canvas draws the preview rather than the editor,
-     * so without one the block's content is invisible there.
-     */
-    alwaysEditing?: boolean;
+type SlashGroup = 'basic' | 'lists' | 'media' | 'advanced' | 'embeds' | 'ai' | 'custom';
+type CalloutTone = 'info' | 'tip' | 'success' | 'warning' | 'danger';
+/** The block types the menus name. Headings are named by `heading`. */
+type BlockName = 'text' | 'bulletedList' | 'numberedList' | 'todoList' | 'quote' | 'callout' | 'toggle' | 'code' | 'divider' | 'image' | 'file';
+/** The slash commands that insert a block, which the menu explains under their names. */
+type SlashBlockCommand = BlockName | 'heading1' | 'heading2' | 'heading3';
+type ModifierKey = 'ctrl' | 'alt' | 'shift';
+/** The keys a shortcut writes out by name rather than by the character they type. */
+type NamedKey = 'escape' | 'tab' | 'enter' | 'space' | 'backspace' | 'delete' | 'f10';
+type ShortcutGroupName = 'text' | 'blocks' | 'selection' | 'navigation' | 'menus';
+/** The rows of the keyboard shortcuts dialog that no other label names. */
+type ShortcutName = 'lineBreak' | 'flipBlock' | 'selectBlock' | 'openBlockEditor' | 'leaveBlockEditor' | 'selectAll' | 'extendUp' | 'extendDown' | 'lineUp' | 'lineDown' | 'leaveEditor' | 'blockMenu' | 'closeMenu' | 'splitBlock' | 'joinAbove' | 'joinBelow' | 'previousBlockEnd' | 'nextBlockStart';
+/** Every string the editor shows or speaks. A label that depends on a value is a function of it. */
+type QuoinLabels = {
+    document: string;
+    editorHint: string;
+    paragraph: string;
+    heading: (level: number) => string;
+    bulletItem: string;
+    numberedItem: (n: number) => string;
+    task: string;
+    quote: string;
+    /** The name of a callout's text, given the name of its tone from `calloutTones`, which it takes as written. */
+    callout: (tone: string) => string;
+    /** The name of each tone, on its chip and in its menus as inside the name of a callout's text. */
+    calloutTones: Record<CalloutTone, string>;
+    calloutIcon: string;
+    /** The name of the button that shows a callout's tone and opens the menu of tones, given the tone's name. */
+    calloutToneMenu: (tone: string) => string;
+    toggle: string;
+    /** The name of a toggle's chevron, given how many blocks the closed toggle hides, 0 while it is open. */
+    toggleButton: (hidden: number) => string;
+    placeholderEmpty: string;
+    placeholderHeading: (level: number) => string;
+    placeholderList: string;
+    placeholderQuote: string;
+    blockMenu: (type: string) => string;
+    blockNames: Record<BlockName, string>;
+    turnInto: string;
+    color: string;
+    textColor: string;
+    backgroundColor: string;
+    /** The submenus of a callout's block menu that set its tone and its icon. */
+    tone: string;
+    icon: string;
+    duplicate: string;
+    copy: string;
+    copyLink: string;
+    copied: string;
+    moveUp: string;
+    moveDown: string;
+    delete: string;
+    askAi: string;
+    addBelow: string;
+    dragHandle: string;
+    slashMenu: string;
+    noResults: string;
+    /** What the open slash menu says once its list settles, given how many commands match. */
+    resultCount: (n: number) => string;
+    slashDescriptions: Record<SlashBlockCommand, string>;
+    groups: Record<SlashGroup, string>;
+    bold: string;
+    italic: string;
+    underline: string;
+    strike: string;
+    code: string;
+    link: string;
+    highlight: string;
+    align: string;
+    alignLeft: string;
+    alignCenter: string;
+    alignRight: string;
+    alignJustify: string;
+    subscript: string;
+    superscript: string;
+    comment: string;
+    linkUrl: string;
+    linkApply: string;
+    linkRemove: string;
+    linkOpen: string;
+    linkEdit: string;
+    invalidLink: string;
+    colors: Record<PaletteName, string>;
+    blockMoved: (position: number, total: number) => string;
+    blockInserted: (position: number, total: number) => string;
+    blockDeleted: (n: number) => string;
+    blocksSelected: (n: number) => string;
+    /** How to bring deleted blocks back, given the platform's undo shortcut. */
+    undoHint: (shortcut: string) => string;
+    shortcuts: string;
+    shortcutGroupNames: Record<ShortcutGroupName, string>;
+    shortcutNames: Record<ShortcutName, string>;
+    /** Two keys pressed one after the other. */
+    keySequence: (first: string, then: string) => string;
+    /** Two shortcuts that do the same thing. */
+    keyAlternative: (first: string, other: string) => string;
+    /** The modifier keys a shortcut hint names away from a Mac, where it draws their symbols instead. */
+    keyNames: Record<ModifierKey, string>;
+    namedKeys: Record<NamedKey, string>;
+    formattingToolbar: string;
+    mobileToolbar: string;
+    indent: string;
+    outdent: string;
+    undo: string;
+    redo: string;
+    close: string;
+    selectedContent: string;
+    editBlock: (label: string) => string;
+    unsupportedBlock: string;
+    uploading: string;
+    uploaded: (name: string) => string;
+    /** What an upload field shows when the host's upload fails without a message of its own. */
+    uploadFailed: string;
+    /** What an upload field shows in place of working when the canvas was given no upload function. */
+    uploadsUnavailable: string;
+    /** An empty image block: its upload button, the link it can embed instead and what can be dropped or pasted on it. */
+    uploadImage: string;
+    embedLink: string;
+    imageLink: string;
+    dropImage: string;
+    /** An image block: its caption, its toolbar, the handles of its width with their value, and the toolbar's buttons. */
+    imageCaption: string;
+    addCaption: string;
+    imageTools: string;
+    resizeFromLeft: string;
+    resizeFromRight: string;
+    widthValue: (percent: number) => string;
+    replaceImage: string;
+    download: string;
+    /** The alt text of an image: its field, what the field asks for, its button, and the name of an image without one. */
+    altText: string;
+    altTextHint: string;
+    save: string;
+    imageNoAlt: string;
+    /** An empty file block: its upload button and what can be dropped or pasted on it. */
+    uploadFile: string;
+    dropFile: string;
+    /** A file block: its toolbar and the toolbar's replace button. */
+    fileTools: string;
+    replaceFile: string;
+    /** The name of a file's download link, given the file's name. It contains `download`, the link's visible text. */
+    downloadFile: (name: string) => string;
+    /** The size of a file, given in bytes. */
+    fileSize: (bytes: number) => string;
+    /** The name of a file block selected as a whole, given the file's name. */
+    fileBlockName: (name: string) => string;
+    /** A code block: its code, its language, the name of a code in no language, and its copy button. */
+    codeText: string;
+    /** The name of a code block selected as a whole, given the name of its language. */
+    codeBlockName: (language: string) => string;
+    codeLanguage: string;
+    plainText: string;
+    copyCode: string;
+    /** What the preview of a block without content says. */
+    emptyImage: string;
+    emptyFile: string;
+    emptyMarkdown: string;
+    emptyCallout: string;
 };
-/**
- * Describes one block type: how to label it, how to draw it at rest, how to edit it.
- *
- * Supply `editor`, `preview`, or both, and the canvas does the rest. A definition with no
- * `preview` is edit-only: a read-only canvas has nothing to draw for it but its label.
- * A definition with no `editor` can never be edited in the canvas, which is what a block
- * whose content belongs to a server-side record wants; the card offers no edit affordance
- * for it and a click goes through to whatever the preview itself renders.
- *
- * Omitting both is a type error, because such a block would only ever draw its own label.
- */
-type BlockDefinition<D extends object = Record<string, unknown>> = (BlockDefinitionCommon<D> & {
-    editor: ComponentType<BlockEditorProps<D>>;
-    /**
-     * What the block shows when it is not being edited. Optional so a host can register an
-     * edit-only block type, and overridable so a host can supply rich rendering (a full
-     * markdown pipeline, a chart) without Quoin depending on one.
-     */
-    preview?: ComponentType<BlockPreviewProps<D>>;
-}) | (BlockDefinitionCommon<D> & {
-    /** Omitted: this block is never editable in the canvas. */
-    editor?: undefined;
-    /** Required here, because it is the only thing that can draw the block. */
-    preview: ComponentType<BlockPreviewProps<D>>;
-});
-/** A definition with its data type erased, so definitions of different shapes compose in one array. */
-type AnyBlockDefinition = BlockDefinition<Record<string, unknown>>;
-/**
- * Types `data` inside your editor component, then erases the generic on the way out.
- * The erasure is deliberate: `D` appears in both covariant and contravariant positions
- * on `editor`, so without it an array of differently-shaped definitions will not typecheck.
- * `initialData` is checked against the editor's data type. That relies on `NoInfer`, so
- * TypeScript 5.4 or later is required.
- *
- * `D` defaults to `Record<string, unknown>`, so a definition whose components take no
- * annotation still gets a usable `data` rather than a bare `object`.
- */
-declare function defineBlock<D extends object = Record<string, unknown>>(definition: BlockDefinition<D>): AnyBlockDefinition;
-/** The definition for a type, or undefined; the last registration of a type wins, so a host can override a core block. */
-declare function blockByType(definitions: AnyBlockDefinition[], type: string): AnyBlockDefinition | undefined;
-/** The definitions offered in the slash palette, in registration order, one per type, with the last registration of a type winning. */
-declare function paletteBlocks(definitions: AnyBlockDefinition[]): AnyBlockDefinition[];
 
-/** Props for `BlockCanvas`; `blocks` and `onChange` are the whole document contract. */
 type BlockCanvasProps = {
     /**
-     * The document. Update it synchronously from `onChange`, as with a controlled `<input value onChange>`.
-     * Applying the edit late is tolerated: the canvas recognises an array it emitted however late it comes back, and
-     * a structural copy of one within 64 edits, so a transition, a debounced setter or a store that clones the
-     * document on the way through is safe.
-     * A new array that differs from the last one you supplied replaces what the canvas shows, which is how a host
-     * loads, undoes or merges. An array structurally equal to the last one you supplied is ignored, so a "discard
-     * changes" button that hands back the original document does nothing. A host that does not echo `onChange` back
-     * meets the same when it restores a copy of a state from the last 64 edits, which reads as a late echo. Remount
-     * the canvas with a React `key` to force a reset in either case. The comparison is shallow over each block's
-     * `data`: a host whose block `data` holds nested objects rebuilt on every render, and which does not echo
-     * `onChange` back, can still lose an edit. The core block types all have flat data, so this only affects custom
-     * blocks.
+     * The document, controlled like `<input value onChange>`. An array the canvas emitted, or a copy of one, coming back
+     * late is recognised as its echo, and an array structurally equal to the last one supplied is ignored. Any other
+     * array replaces the document. Remount with a React `key` to force a reset.
      */
     blocks: QuoinBlock[];
     onChange: (blocks: QuoinBlock[]) => void;
     /**
-     * Called when a block is removed through its actions menu, with the block and the index it held.
-     * It runs just after the `onChange` that reports the document without it, so a host acting on the
-     * deletion is already looking at the new array. Restore the block by supplying a `blocks` array
-     * with it spliced back at that index, the same way any other document arrives.
-     *
-     * Restore it on a later tick or a later interaction, such as the click of an Undo toast. A
-     * restore applied synchronously inside this callback batches with the echo of the deletion, so
-     * what arrives is structurally equal to the document last supplied and is ignored.
+     * Called for each whole block the writer removed, with the index it held, once `onChange` has reported the document
+     * without it: through a command such as the block menu's Delete, by typing over a selected block, or by pasting over
+     * selected blocks. A line that Backspace or Delete merges into its neighbour or drops when empty is not reported, nor
+     * a line that pasted blocks take the place of. Restore a block by splicing it back at that index into `blocks` once
+     * they no longer hold it, as on a later interaction. A host that applies `onChange` in a transition or after a debounce
+     * has not applied the removal when this runs: splicing into its state here duplicates the block, and supplying again
+     * an array equal to the one it last supplied is ignored.
      */
     onDelete?: (block: QuoinBlock, index: number) => void;
-    /** Defaults to the five core block types. Pass `[...coreBlocks, yours]` to extend them. */
     blockTypes?: AnyBlockDefinition[];
+    /**
+     * Added after the core extensions when the canvas mounts. Remount it with a new `key` to change them. An extension's
+     * `ui` field, an `ExtensionUI`, adds slash commands, block menu items, block renderers and overlays to the canvas.
+     */
+    extensions?: readonly Extension[];
     upload?: UploadFn;
     resolveAssetUrl?: (storageKey: string) => string;
     onError?: (error: Error) => void;
-    /** Renders the document with no inserters, menus, drag handles or editors. */
+    /**
+     * Colours the code of code blocks: one array of tokens per line, whose texts spell the line exactly. Keep the function
+     * stable, as for `labels`. Without it, or when its tokens do not spell the code, the code is drawn as plain text.
+     */
+    highlight?: CodeHighlighter;
     readOnly?: boolean;
-    /** Added to the root element's own classes rather than replacing them. */
+    autoFocus?: boolean;
+    /** The text of an empty paragraph holding the caret, or alone in the document, in place of `labels.placeholderEmpty`. */
+    placeholder?: string;
+    /**
+     * Every string the canvas shows or speaks, English by default. A key left out stays English. Keep the object stable,
+     * hoisted or memoised: a new one each render re-renders everything that reads the canvas configuration.
+     */
+    labels?: Partial<QuoinLabels>;
+    /**
+     * The address the block menu's "Copy link to block" copies. By default the current page with `#block-<id>`, a fragment
+     * the canvas follows on load and on hash changes to select the block and scroll it into view.
+     */
+    blockLink?: (blockId: string) => string;
     className?: string;
     id?: string;
-    /** Names the document for assistive technology; the root then becomes a labelled group. */
     'aria-label'?: string;
 };
-/** The editor: renders `blocks`, reports every edit through `onChange`, and accepts a new `blocks` array from outside at any time. */
-declare function BlockCanvas({ blocks, onChange, onDelete, blockTypes, upload, resolveAssetUrl, onError, readOnly, className, id, 'aria-label': ariaLabel, }: BlockCanvasProps): React.JSX.Element;
+type QuoinEditorHandle = {
+    readonly editor: Editor;
+    readonly controller: ViewController;
+    focus(target?: Pos | 'start' | 'end'): void;
+    toMarkdown(options?: {
+        comments?: boolean;
+    }): string;
+};
+
+declare const BlockCanvas: react.ForwardRefExoticComponent<BlockCanvasProps & react.RefAttributes<QuoinEditorHandle>>;
 
 /** The block types Quoin ships with. Spread them alongside your own definitions. */
 declare const coreBlocks: AnyBlockDefinition[];
@@ -160,9 +248,10 @@ declare const coreBlocks: AnyBlockDefinition[];
  * that writes it and the seed it starts from.
  *
  * Every field is declared because something writes it. The optional ones are written
- * later than the block's first save: an image's `caption` when the author types one, its
- * `width` and `height` once the uploaded bytes have been measured, a file's `size` when
- * the upload reports it.
+ * later than the block's first save, and only once set: an image's `caption` when the
+ * author types one, its `width` and `height` once the uploaded bytes have been measured,
+ * its `url`, `align` and `widthPercent` when the author links, aligns or resizes it, a
+ * file's `size` when the upload reports it and its `mime` when the file declares a type.
  */
 /** `MARKDOWN`. The source text, not rendered HTML: Quoin stores and edits markdown. */
 type MarkdownBlockData = {
@@ -178,19 +267,30 @@ type CodeBlockData = {
     language: string;
     code: string;
 };
-/** `IMAGE`. `storageKey` names the uploaded file; the host's `resolveAssetUrl` turns it into a URL. */
+/**
+ * `IMAGE`. `storageKey` names the uploaded file, which the host's `resolveAssetUrl` turns into a URL, unless `url`
+ * links a picture instead. `caption` is inline markdown, `width` and `height` the measured size of the upload, and
+ * `widthPercent` the share of the line the picture is drawn at.
+ */
 type ImageBlockData = {
     storageKey: string;
     alt: string;
     caption?: string;
     width?: number;
     height?: number;
+    url?: string;
+    align?: 'left' | 'center' | 'right';
+    widthPercent?: number;
 };
-/** `FILE`. `storageKey` names the uploaded file; `filename` is what the author picked. */
+/**
+ * `FILE`. `storageKey` names the uploaded file, which the host's `resolveAssetUrl` turns into a URL; `filename` is the
+ * name the upload kept, `size` its size in bytes and `mime` the type the file declared.
+ */
 type FileBlockData = {
     storageKey: string;
     filename: string;
     size?: number;
+    mime?: string;
 };
 /** Maps each core block's `type` string to its data shape. */
 type CoreBlockData = {
@@ -212,8 +312,8 @@ type UploadFieldProps = {
     /** Called once the upload resolves. The field stays busy until a returned promise settles, and throwing or rejecting is reported through the canvas `onError`. */
     onUploaded: (result: UploadResult) => void | Promise<void>;
 };
-/** A file picker wired to the canvas `upload` function, with its own busy state and inline error. */
-declare function UploadField({ category, label, accept, onUploaded }: UploadFieldProps): React.JSX.Element;
+/** A file picker wired to the canvas `upload` function, with its own busy state, success message and inline error. */
+declare function UploadField({ category, label, accept, onUploaded }: UploadFieldProps): react.JSX.Element;
 
 /** Props for `FilePickerButton`. */
 type FilePickerButtonProps = {
@@ -221,13 +321,15 @@ type FilePickerButtonProps = {
     label: string;
     /** An `accept` attribute for the file input, such as `'image/*'` or `'.pdf'`. */
     accept?: string;
-    /** Greys the button out and disables the input behind it. */
+    /** Greys the button out and disables the input behind it. After a pick, focus the browser dropped while it was disabled comes back once it is enabled again. */
     disabled?: boolean;
+    /** Greys the button out and refuses picks, as `disabled` does, but leaves the input focusable, so focus stays on it while an upload runs. */
+    busy?: boolean;
     /** Called with the chosen file, and again if the same file is picked after a failure. */
     onPick: (file: File) => void;
 };
 /** A button that opens the file picker and hands back the chosen file, performing no upload of its own. */
-declare function FilePickerButton({ label, accept, disabled, onPick }: FilePickerButtonProps): React.JSX.Element;
+declare function FilePickerButton({ label, accept, disabled, busy, onPick }: FilePickerButtonProps): react.JSX.Element;
 
 /** The resolved canvas configuration every block editor reads through `useQuoin`. */
 type QuoinConfig = {
@@ -236,42 +338,127 @@ type QuoinConfig = {
     upload?: UploadFn;
     resolveAssetUrl: (storageKey: string) => string;
     onError: (error: Error) => void;
+    /** Highlights the code of code blocks; without it their code is drawn as plain text. */
+    highlight?: CodeHighlighter;
+    /** The controller of the canvas the block is drawn in; null under a provider no canvas set up. */
+    controller: ViewController | null;
+    labels: QuoinLabels;
 };
 /** What a host passes to `QuoinProvider`: only the block types are required. */
 type QuoinConfigInput = Partial<QuoinConfig> & {
     blockTypes: AnyBlockDefinition[];
 };
-/** Supplies the block registry and the host couplings (upload, asset URLs, error reporting) to every block below it. */
+/** Supplies the block registry, the host couplings (upload, asset URLs, error reporting, code highlighting), the canvas controller and the labels to every block below it. */
 declare function QuoinProvider({ value, children, }: {
     value: QuoinConfigInput;
-    children: React.ReactNode;
-}): React.JSX.Element;
+    children: react.ReactNode;
+}): react.JSX.Element;
 /** Reads the canvas configuration. Throws outside a QuoinProvider rather than returning a silent default. */
 declare function useQuoin(): QuoinConfig;
 
-/** Handed back by `remove` and accepted by `undo` to restore that one block. */
-type UndoToken = number;
-/** The document plus every way to change it; `reset` replaces the whole document and voids outstanding undo tokens. */
-type BlockList = {
-    blocks: QuoinBlock[];
-    insertAt: (index: number, type: string, data?: Record<string, unknown>) => string;
-    update: (id: string, data: Record<string, unknown>) => void;
-    /** Returns a token `undo` restores that block with; only the last 20 removals stay restorable. */
-    remove: (id: string) => UndoToken;
-    undo: (token: UndoToken) => void;
-    move: (index: number, dir: -1 | 1) => void;
-    reorder: (from: number, to: number) => void;
-    reset: (blocks: QuoinBlock[]) => void;
+declare const englishLabels: QuoinLabels;
+
+/** The English labels with the host's overrides on top. A key the host leaves out, or passes as undefined, stays
+ *  English. */
+declare function resolveLabels(overrides?: Partial<QuoinLabels>): QuoinLabels;
+
+type BlockMenuAction = {
+    id: string;
+    label: string;
+    icon: ComponentType<{
+        className?: string;
+    }>;
+    /** A key in the keymap's own form, such as `Mod-d`. */
+    shortcut?: string;
+    destructive?: boolean;
+    run(controller: ViewController, blockIds: string[]): void;
+    available?(state: EditorState, blockIds: string[]): boolean;
 };
-/** Holds a document in a reducer and returns its blocks with insert, update, remove, undo, move, reorder and reset. Reads `initial` once. */
-declare function useBlockList(initial: QuoinBlock[]): BlockList;
+
+type SuggestionRange = {
+    block: string;
+    region: string;
+    from: number;
+    to: number;
+};
+type SlashItem = {
+    id: string;
+    title: string;
+    description?: string;
+    group: SlashGroup;
+    icon?: ComponentType<{
+        className?: string;
+    }>;
+    keywords?: readonly string[];
+    /** A key in the keymap's own form, such as `Mod-Alt-1`. */
+    shortcut?: string;
+    available?(state: EditorState): boolean;
+    /**
+     * The change the item makes, run once the menu has removed the slash and the query, in the same transaction, so one
+     * undo brings the query back. `state` and `range` are those of the moment the item is chosen.
+     */
+    command?(ctx: {
+        state: EditorState;
+        range: SuggestionRange;
+    }): Command;
+    /**
+     * Work no command can do, such as opening a dialog, called once the slash and the query are gone. `range` is the
+     * empty range where they were.
+     */
+    run?(ctx: {
+        controller: ViewController;
+        range: SuggestionRange;
+    }): void;
+};
+type ToolbarItem = {
+    id: string;
+    title: string;
+    icon: ComponentType<{
+        className?: string;
+    }>;
+    shortcut?: string;
+    isActive?(state: EditorState): boolean;
+    available?(state: EditorState): boolean;
+    run(controller: ViewController): void;
+};
+/** What an extension adds to the canvas UI, through its `ui` field. */
+type ExtensionUI = {
+    slashItems?: readonly SlashItem[];
+    bubbleItems?: readonly ToolbarItem[];
+    blockMenuItems?: readonly BlockMenuAction[];
+    renderers?: Readonly<Record<string, BlockRenderer>>;
+    /** What the block types the extension draws are called, in their block menu and while one is selected as a whole. */
+    blockNames?: Readonly<Record<string, string>>;
+    render?: RenderOptions;
+    overlays?: readonly ComponentType<{
+        controller: ViewController;
+    }>[];
+};
+
+/** The labels of the canvas around the caller, English unless its host overrode some. */
+declare function useLabels(): QuoinLabels;
+
+/** The words a shortcut is written in: the modifiers away from a Mac, and the keys written out by name. */
+type KeyLabels = Pick<QuoinLabels, 'keyNames' | 'namedKeys'>;
+type ShortcutPlatform = {
+    /** Whether to write the keys the way a Mac does. Defaults to the platform the page runs on. */
+    isMac?: boolean;
+    /** English by default. */
+    labels?: KeyLabels;
+};
+/**
+ * Writes a shortcut, in the keymap's form such as `Mod-Shift-b` or as `mod+shift+b`, the way the platform does: the
+ * Command and Shift symbols then B on a Mac, and `Ctrl+Shift+B` elsewhere.
+ */
+declare function formatShortcut(shortcut: string, platform?: ShortcutPlatform): string;
 
 /** Where a debounced save stands, for a "Saving..." or "Saved" indicator. */
 type AutosaveStatus = 'idle' | 'saving' | 'saved' | 'retrying' | 'failed';
+
 /** What `useAutosave` tracks, how to build the payload, and how to persist it. */
 type UseAutosaveInput<T> = {
     /** The tracked fields. An edit to any of them marks dirty and restarts the debounce. */
-    deps: React.DependencyList;
+    deps: react.DependencyList;
     build: () => T;
     /**
      * Persists the payload. Return anything: a mutation or a `fetch` that resolves to a body
@@ -310,99 +497,4 @@ type UseAutosaveResult = {
  */
 declare function useAutosave<T>({ deps, build, save, debounceMs, maxBackoffMs, maxRetries, isRetryable, flushOnHide, }: UseAutosaveInput<T>): UseAutosaveResult;
 
-/** Height follows the content, and is recomputed when the box gets narrower or
- *  wider, because a re-wrap changes the line count without changing the value.
- *  Only a width change refits: reacting to the height this hook just set would
- *  feed the observer its own output. */
-declare function useAutoGrow<T extends HTMLTextAreaElement>(value: string): React.RefObject<T>;
-
-/** A slash-palette entry: how it is shown and searched, and the markdown it inserts. */
-type TextCommand = {
-    id: string;
-    label: string;
-    keywords: string[];
-    icon: LucideIcon;
-    hint?: string;
-    insert: string;
-    caretOffset: number;
-    selectLength?: number;
-    /** Needs a blank line above it: a divider after a paragraph line parses as a
-     *  setext heading, and a GFM table cannot interrupt a paragraph at all. */
-    separate: boolean;
-};
-/** The built-in slash-palette commands, in display order. */
-declare const TEXT_COMMANDS: TextCommand[];
-
-/** A text transform result: the next value and where the selection should land. */
-type Edit = {
-    value: string;
-    selectionStart: number;
-    selectionEnd: number;
-};
-/** Applies an edit to a textarea through the native undo stack when the browser allows it, so Ctrl+Z still works. */
-declare function applyEdit(el: HTMLTextAreaElement, edit: Edit, commit: (value: string) => void): void;
-
-type Line = {
-    start: number;
-    end: number;
-    text: string;
-};
-/** The line containing the offset, with its start and end offsets and its text (no trailing newline). */
-declare function lineAt(value: string, offset: number): Line;
-
-/** A line-level markdown prefix: a heading level, a bullet or a numbered item. */
-type LinePrefix = 'h1' | 'h2' | 'h3' | 'bullet' | 'ordered';
-/** Adds the prefix to every line in the selection, or removes it when every line already carries it; fenced code is left alone. */
-declare function toggleLinePrefix(kind: LinePrefix, value: string, selectionStart: number, selectionEnd: number): Edit;
-
-/** Continues a list item on Enter, or climbs out of the list on an empty item or Backspace at the marker; returns null when the caret is not in a list item or is inside a code fence, so the default key behaviour runs. */
-declare function continueList(value: string, caret: number, key: 'Enter' | 'Backspace'): Edit | null;
-
-/** Indents or outdents the selected list items; returns null when the selection is not entirely list items, is inside a code fence, or cannot move further, so Tab keeps its default behaviour. */
-declare function indentList(value: string, selectionStart: number, selectionEnd: number, direction: 1 | -1): Edit | null;
-
-/** An inline markdown wrapper: bold, italic, code or a link. */
-type WrapKind = 'bold' | 'italic' | 'code' | 'link';
-/** Wraps the selection in the markers for the kind, or removes them when it is already wrapped. */
-declare function wrapSelection(kind: WrapKind, value: string, selectionStart: number, selectionEnd: number): Edit;
-/** Turns a pasted URL over a selection into a markdown link; returns null when nothing is selected or the paste is not a bare URL, so the paste goes through unchanged. */
-declare function linkPaste(value: string, selectionStart: number, selectionEnd: number, pasted: string): Edit | null;
-
-/** The fields `insertCommand` needs. `TextCommand` satisfies this structurally. */
-type InsertableCommand = {
-    insert: string;
-    caretOffset: number;
-    selectLength?: number;
-    separate: boolean;
-};
-/** Inserts a command's markdown at the caret, starting a new line (or a blank line if it asks) when the caret is mid-line. */
-declare function insertCommand(command: InsertableCommand, value: string, caret: number): Edit;
-
-/** Whether typing "/" here should open the command palette: only at a word start, with no selection and outside a code fence. */
-declare function shouldOpenPalette(value: string, selectionStart: number, selectionEnd: number): boolean;
-
-/** Renders a "mod+shift+b" style hint as the platform's own label, such as ⌘⇧B on a Mac and Ctrl+Shift+B elsewhere. */
-declare function formatShortcut(hint: string): string;
-
-/** The caret's position and line height, in pixels relative to the textarea's top left corner. */
-type CaretRect = {
-    top: number;
-    left: number;
-    height: number;
-};
-/** A textarea exposes no caret geometry, so the text before the caret is laid
- *  out again in a hidden div that copies the box's own metrics, and a marker at
- *  the end of it is measured. Returns null when the textarea is not laid out
- *  (hidden or detached), because there is nothing to measure. */
-declare function caretRect(el: HTMLTextAreaElement): CaretRect | null;
-
-/** Keyboard and paste handlers that give a plain textarea markdown shortcuts, list continuation, Tab indent and the slash palette trigger. */
-declare function useMarkdownKeymap({ commit, onOpenPalette, }: {
-    commit: (markdown: string) => void;
-    onOpenPalette: () => void;
-}): {
-    onKeyDown: (event: React.KeyboardEvent<HTMLTextAreaElement>) => void;
-    onPaste: (event: React.ClipboardEvent<HTMLTextAreaElement>) => void;
-};
-
-export { type AnyBlockDefinition, type AutosaveStatus, BlockCanvas, type BlockCanvasProps, type BlockDefinition, type BlockEditorProps, type BlockList, type BlockPreviewProps, type CalloutBlockData, type CaretRect, type CodeBlockData, type CoreBlockData, type Edit, type FileBlockData, FilePickerButton, type FilePickerButtonProps, type ImageBlockData, type InsertableCommand, type LinePrefix, type MarkdownBlockData, type QuoinBlock, type QuoinConfig, type QuoinConfigInput, QuoinProvider, TEXT_COMMANDS, type TextCommand, type UndoToken, UploadField, type UploadFieldProps, type UploadFn, type UploadResult, type UseAutosaveInput, type UseAutosaveResult, type WrapKind, applyEdit, blockByType, caretRect, continueList, coreBlocks, defineBlock, formatShortcut, indentList, insertCommand, lineAt, linkPaste, paletteBlocks, shouldOpenPalette, toggleLinePrefix, useAutoGrow, useAutosave, useBlockList, useMarkdownKeymap, useQuoin, wrapSelection };
+export { AnyBlockDefinition, type AutosaveStatus, BlockCanvas, type BlockCanvasProps, type BlockMenuAction, BlockRenderer, type CalloutBlockData, type CodeBlockData, CodeHighlighter, Command, type CoreBlockData, Editor, EditorState, Extension, type ExtensionUI, type FileBlockData, FilePickerButton, type FilePickerButtonProps, type ImageBlockData, type MarkdownBlockData, PALETTE, Pos, QuoinBlock, type QuoinConfig, type QuoinConfigInput, type QuoinEditorHandle, type QuoinLabels, QuoinProvider, RenderOptions, type ShortcutPlatform, type SlashGroup, type SlashItem, type SuggestionRange, type ToolbarItem, UploadField, type UploadFieldProps, UploadFn, UploadResult, type UseAutosaveInput, type UseAutosaveResult, ViewController, coreBlocks, englishLabels, formatShortcut, resolveLabels, useAutosave, useLabels, useQuoin };