quoin-editor 0.1.1 → 0.3.0

package/dist/index.d.cts

@@ -42,18 +42,11 @@ type BlockEditorProps<D = Record<string, unknown>> = {
     onDone?: () => void;
 };
 
-/** Describes one block type: how to label it, how to draw it at rest, how to edit it. */
-type BlockDefinition<D extends object = Record<string, unknown>> = {
+/** The fields every block definition carries, whatever it can do with its data. */
+type BlockDefinitionCommon<D extends object> = {
     type: string;
     label: string;
     icon: LucideIcon;
-    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>>;
     /**
      * 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
@@ -69,6 +62,31 @@ type BlockDefinition<D extends object = Record<string, unknown>> = {
      */
     alwaysEditing?: boolean;
 };
+/**
+ * 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>>;
 /**
@@ -77,8 +95,11 @@ type AnyBlockDefinition = BlockDefinition<Record<string, unknown>>;
  * 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>(definition: BlockDefinition<D>): AnyBlockDefinition;
+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. */
@@ -102,6 +123,17 @@ type BlockCanvasProps = {
      */
     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.
+     */
+    onDelete?: (block: QuoinBlock, index: number) => void;
     /** Defaults to the five core block types. Pass `[...coreBlocks, yours]` to extend them. */
     blockTypes?: AnyBlockDefinition[];
     upload?: UploadFn;
@@ -116,11 +148,87 @@ type BlockCanvasProps = {
     '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, blockTypes, upload, resolveAssetUrl, onError, readOnly, className, id, 'aria-label': ariaLabel, }: BlockCanvasProps): React.JSX.Element;
+declare function BlockCanvas({ blocks, onChange, onDelete, blockTypes, upload, resolveAssetUrl, onError, readOnly, className, id, 'aria-label': ariaLabel, }: BlockCanvasProps): React.JSX.Element;
 
 /** The block types Quoin ships with. Spread them alongside your own definitions. */
 declare const coreBlocks: AnyBlockDefinition[];
 
+/**
+ * The `data` shape each core block keeps its content under. A host that persists blocks
+ * itself reads and writes these, so they are part of the public surface rather than an
+ * implementation detail. `core-data.test.tsx` holds every one of them against the editor
+ * 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.
+ */
+/** `MARKDOWN`. The source text, not rendered HTML: Quoin stores and edits markdown. */
+type MarkdownBlockData = {
+    markdown: string;
+};
+/** `CALLOUT`. The prose is under `body`, not `text`. */
+type CalloutBlockData = {
+    tone: string;
+    body: string;
+};
+/** `CODE`. `language` is a free string, written through as the author typed it. */
+type CodeBlockData = {
+    language: string;
+    code: string;
+};
+/** `IMAGE`. `storageKey` names the uploaded file; the host's `resolveAssetUrl` turns it into a URL. */
+type ImageBlockData = {
+    storageKey: string;
+    alt: string;
+    caption?: string;
+    width?: number;
+    height?: number;
+};
+/** `FILE`. `storageKey` names the uploaded file; `filename` is what the author picked. */
+type FileBlockData = {
+    storageKey: string;
+    filename: string;
+    size?: number;
+};
+/** Maps each core block's `type` string to its data shape. */
+type CoreBlockData = {
+    MARKDOWN: MarkdownBlockData;
+    CALLOUT: CalloutBlockData;
+    CODE: CodeBlockData;
+    IMAGE: ImageBlockData;
+    FILE: FileBlockData;
+};
+
+/** Props for `UploadField`; the upload function itself comes from the canvas, not from here. */
+type UploadFieldProps = {
+    /** Names what the file is for, and is passed to the host's `upload` as its second argument. */
+    category: string;
+    /** Labels the control for both the pointer and assistive technology. */
+    label: string;
+    /** An `accept` attribute for the file input, such as `'image/*'` or `'.pdf'`. */
+    accept?: string;
+    /** Called once the upload resolves. Throwing from it is reported through the canvas `onError`. */
+    onUploaded: (result: UploadResult) => 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;
+
+/** Props for `FilePickerButton`. */
+type FilePickerButtonProps = {
+    /** Labels the button and the file input behind it. */
+    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. */
+    disabled?: 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;
+
 /** The resolved canvas configuration every block editor reads through `useQuoin`. */
 type QuoinConfig = {
     blockTypes: AnyBlockDefinition[];
@@ -160,15 +268,16 @@ declare function useBlockList(initial: QuoinBlock[]): BlockList;
 
 /** Where a debounced save stands, for a "Saving..." or "Saved" indicator. */
 type AutosaveStatus = 'idle' | 'saving' | 'saved' | 'retrying';
-type SaveResult = {
-    ok?: boolean;
-} | void;
 /** 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;
     build: () => T;
-    save: (payload: T) => Promise<SaveResult> | SaveResult;
+    /**
+     * Persists the payload. Return anything: a mutation or a `fetch` that resolves to a body
+     * can be passed straight in. A save fails by rejecting, or by resolving to `{ ok: false }`.
+     */
+    save: (payload: T) => unknown;
     debounceMs?: number;
     maxBackoffMs?: number;
 };
@@ -279,4 +388,4 @@ declare function useMarkdownKeymap({ commit, onOpenPalette, }: {
     onPaste: (event: React.ClipboardEvent<HTMLTextAreaElement>) => void;
 };
 
-export { type AnyBlockDefinition, type AutosaveStatus, BlockCanvas, type BlockCanvasProps, type BlockDefinition, type BlockEditorProps, type BlockList, type BlockPreviewProps, type CaretRect, type Edit, type InsertableCommand, type LinePrefix, type QuoinBlock, type QuoinConfig, type QuoinConfigInput, QuoinProvider, TEXT_COMMANDS, type TextCommand, type UndoToken, 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 { 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 };

package/dist/index.d.ts

@@ -42,18 +42,11 @@ type BlockEditorProps<D = Record<string, unknown>> = {
     onDone?: () => void;
 };
 
-/** Describes one block type: how to label it, how to draw it at rest, how to edit it. */
-type BlockDefinition<D extends object = Record<string, unknown>> = {
+/** The fields every block definition carries, whatever it can do with its data. */
+type BlockDefinitionCommon<D extends object> = {
     type: string;
     label: string;
     icon: LucideIcon;
-    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>>;
     /**
      * 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
@@ -69,6 +62,31 @@ type BlockDefinition<D extends object = Record<string, unknown>> = {
      */
     alwaysEditing?: boolean;
 };
+/**
+ * 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>>;
 /**
@@ -77,8 +95,11 @@ type AnyBlockDefinition = BlockDefinition<Record<string, unknown>>;
  * 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>(definition: BlockDefinition<D>): AnyBlockDefinition;
+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. */
@@ -102,6 +123,17 @@ type BlockCanvasProps = {
      */
     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.
+     */
+    onDelete?: (block: QuoinBlock, index: number) => void;
     /** Defaults to the five core block types. Pass `[...coreBlocks, yours]` to extend them. */
     blockTypes?: AnyBlockDefinition[];
     upload?: UploadFn;
@@ -116,11 +148,87 @@ type BlockCanvasProps = {
     '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, blockTypes, upload, resolveAssetUrl, onError, readOnly, className, id, 'aria-label': ariaLabel, }: BlockCanvasProps): React.JSX.Element;
+declare function BlockCanvas({ blocks, onChange, onDelete, blockTypes, upload, resolveAssetUrl, onError, readOnly, className, id, 'aria-label': ariaLabel, }: BlockCanvasProps): React.JSX.Element;
 
 /** The block types Quoin ships with. Spread them alongside your own definitions. */
 declare const coreBlocks: AnyBlockDefinition[];
 
+/**
+ * The `data` shape each core block keeps its content under. A host that persists blocks
+ * itself reads and writes these, so they are part of the public surface rather than an
+ * implementation detail. `core-data.test.tsx` holds every one of them against the editor
+ * 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.
+ */
+/** `MARKDOWN`. The source text, not rendered HTML: Quoin stores and edits markdown. */
+type MarkdownBlockData = {
+    markdown: string;
+};
+/** `CALLOUT`. The prose is under `body`, not `text`. */
+type CalloutBlockData = {
+    tone: string;
+    body: string;
+};
+/** `CODE`. `language` is a free string, written through as the author typed it. */
+type CodeBlockData = {
+    language: string;
+    code: string;
+};
+/** `IMAGE`. `storageKey` names the uploaded file; the host's `resolveAssetUrl` turns it into a URL. */
+type ImageBlockData = {
+    storageKey: string;
+    alt: string;
+    caption?: string;
+    width?: number;
+    height?: number;
+};
+/** `FILE`. `storageKey` names the uploaded file; `filename` is what the author picked. */
+type FileBlockData = {
+    storageKey: string;
+    filename: string;
+    size?: number;
+};
+/** Maps each core block's `type` string to its data shape. */
+type CoreBlockData = {
+    MARKDOWN: MarkdownBlockData;
+    CALLOUT: CalloutBlockData;
+    CODE: CodeBlockData;
+    IMAGE: ImageBlockData;
+    FILE: FileBlockData;
+};
+
+/** Props for `UploadField`; the upload function itself comes from the canvas, not from here. */
+type UploadFieldProps = {
+    /** Names what the file is for, and is passed to the host's `upload` as its second argument. */
+    category: string;
+    /** Labels the control for both the pointer and assistive technology. */
+    label: string;
+    /** An `accept` attribute for the file input, such as `'image/*'` or `'.pdf'`. */
+    accept?: string;
+    /** Called once the upload resolves. Throwing from it is reported through the canvas `onError`. */
+    onUploaded: (result: UploadResult) => 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;
+
+/** Props for `FilePickerButton`. */
+type FilePickerButtonProps = {
+    /** Labels the button and the file input behind it. */
+    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. */
+    disabled?: 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;
+
 /** The resolved canvas configuration every block editor reads through `useQuoin`. */
 type QuoinConfig = {
     blockTypes: AnyBlockDefinition[];
@@ -160,15 +268,16 @@ declare function useBlockList(initial: QuoinBlock[]): BlockList;
 
 /** Where a debounced save stands, for a "Saving..." or "Saved" indicator. */
 type AutosaveStatus = 'idle' | 'saving' | 'saved' | 'retrying';
-type SaveResult = {
-    ok?: boolean;
-} | void;
 /** 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;
     build: () => T;
-    save: (payload: T) => Promise<SaveResult> | SaveResult;
+    /**
+     * Persists the payload. Return anything: a mutation or a `fetch` that resolves to a body
+     * can be passed straight in. A save fails by rejecting, or by resolving to `{ ok: false }`.
+     */
+    save: (payload: T) => unknown;
     debounceMs?: number;
     maxBackoffMs?: number;
 };
@@ -279,4 +388,4 @@ declare function useMarkdownKeymap({ commit, onOpenPalette, }: {
     onPaste: (event: React.ClipboardEvent<HTMLTextAreaElement>) => void;
 };
 
-export { type AnyBlockDefinition, type AutosaveStatus, BlockCanvas, type BlockCanvasProps, type BlockDefinition, type BlockEditorProps, type BlockList, type BlockPreviewProps, type CaretRect, type Edit, type InsertableCommand, type LinePrefix, type QuoinBlock, type QuoinConfig, type QuoinConfigInput, QuoinProvider, TEXT_COMMANDS, type TextCommand, type UndoToken, 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 { 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 };