quoin-editor 0.1.0 → 0.2.0

package/dist/index.d.cts

@@ -87,9 +87,12 @@ declare function paletteBlocks(definitions: AnyBlockDefinition[]): AnyBlockDefin
 /** 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>`:
-     * a host that applies edits late (a debounce, a transition, an async store) will see typing revert,
-     * and should treat the canvas as uncontrolled by passing the initial document and ignoring later echoes.
+     * The document. Update it synchronously from `onChange`, as with a controlled `<input value onChange>`.
+     * Applying the edit late is tolerated as long as what comes back is one of the arrays the canvas emitted:
+     * it recognises its own output even several keystrokes behind, so a transition or a debounced setter is safe.
+     * A store that rebuilds the document on the way through hands back a structural copy instead, which arrives
+     * behind the canvas's own state and reads as a foreign document. That does not revert the edit cleanly: the
+     * characters the copy predates are dropped and the ones typed after them are kept.
      * 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; remount the canvas with a React `key` to
@@ -99,6 +102,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;
@@ -113,11 +127,39 @@ 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[];
 
+/** 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[];
@@ -145,6 +187,7 @@ 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;
@@ -203,4 +246,76 @@ type TextCommand = {
 /** The built-in slash-palette commands, in display order. */
 declare const TEXT_COMMANDS: TextCommand[];
 
-export { type AnyBlockDefinition, type AutosaveStatus, BlockCanvas, type BlockCanvasProps, type BlockDefinition, type BlockEditorProps, type BlockList, type BlockPreviewProps, type QuoinBlock, type QuoinConfig, type QuoinConfigInput, QuoinProvider, TEXT_COMMANDS, type TextCommand, type UndoToken, type UploadFn, type UploadResult, type UseAutosaveInput, type UseAutosaveResult, blockByType, coreBlocks, defineBlock, paletteBlocks, useAutoGrow, useAutosave, useBlockList, useQuoin };
+/** 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 CaretRect, type Edit, FilePickerButton, type FilePickerButtonProps, type InsertableCommand, type LinePrefix, 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

@@ -87,9 +87,12 @@ declare function paletteBlocks(definitions: AnyBlockDefinition[]): AnyBlockDefin
 /** 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>`:
-     * a host that applies edits late (a debounce, a transition, an async store) will see typing revert,
-     * and should treat the canvas as uncontrolled by passing the initial document and ignoring later echoes.
+     * The document. Update it synchronously from `onChange`, as with a controlled `<input value onChange>`.
+     * Applying the edit late is tolerated as long as what comes back is one of the arrays the canvas emitted:
+     * it recognises its own output even several keystrokes behind, so a transition or a debounced setter is safe.
+     * A store that rebuilds the document on the way through hands back a structural copy instead, which arrives
+     * behind the canvas's own state and reads as a foreign document. That does not revert the edit cleanly: the
+     * characters the copy predates are dropped and the ones typed after them are kept.
      * 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; remount the canvas with a React `key` to
@@ -99,6 +102,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;
@@ -113,11 +127,39 @@ 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[];
 
+/** 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[];
@@ -145,6 +187,7 @@ 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;
@@ -203,4 +246,76 @@ type TextCommand = {
 /** The built-in slash-palette commands, in display order. */
 declare const TEXT_COMMANDS: TextCommand[];
 
-export { type AnyBlockDefinition, type AutosaveStatus, BlockCanvas, type BlockCanvasProps, type BlockDefinition, type BlockEditorProps, type BlockList, type BlockPreviewProps, type QuoinBlock, type QuoinConfig, type QuoinConfigInput, QuoinProvider, TEXT_COMMANDS, type TextCommand, type UndoToken, type UploadFn, type UploadResult, type UseAutosaveInput, type UseAutosaveResult, blockByType, coreBlocks, defineBlock, paletteBlocks, useAutoGrow, useAutosave, useBlockList, useQuoin };
+/** 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 CaretRect, type Edit, FilePickerButton, type FilePickerButtonProps, type InsertableCommand, type LinePrefix, 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 };