quoin-editor 0.1.0 → 0.1.1

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
@@ -145,6 +148,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 +207,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, 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 };

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
@@ -145,6 +148,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 +207,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, 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 };

package/dist/index.js

@@ -1117,7 +1117,10 @@ function MarkdownBlockEditor({ data, onChange, onInsertBlock, onDone }) {
   const palette = useSlashPalette(ref);
   const [shortcutsOpen, setShortcutsOpen] = React5.useState(false);
   const set = (patch) => onChange({ ...data, ...patch });
-  const commit = (next) => onChange({ ...data, markdown: next });
+  const commit = React5.useCallback(
+    (next) => onChange({ ...data, markdown: next }),
+    [data, onChange]
+  );
   const keymap = useMarkdownKeymap({ commit, onOpenPalette: palette.openAtCaret });
   function reopenBox() {
     const el = ref.current;
@@ -1578,6 +1581,7 @@ function newBlockId() {
 
 // src/hooks/useBlockList.ts
 var removalSeq = 0;
+var UNDO_DEPTH = 20;
 function reducer(state, action) {
   switch (action.type) {
     case "insertAt": {
@@ -1596,6 +1600,11 @@ function reducer(state, action) {
       if (index === -1) return state;
       const removals = new Map(state.removals);
       removals.set(action.token, { block: state.blocks[index], index });
+      while (removals.size > UNDO_DEPTH) {
+        const oldest = removals.keys().next();
+        if (oldest.done) break;
+        removals.delete(oldest.value);
+      }
       return { blocks: state.blocks.filter((b) => b.id !== action.id), removals };
     }
     case "undo": {
@@ -1833,18 +1842,48 @@ function BlockEditor({
 }
 
 // src/canvas/source-offset.ts
+function caretPositionAt(x, y) {
+  const doc = document;
+  const position = doc.caretPositionFromPoint?.(x, y);
+  if (position) return position;
+  const range = doc.caretRangeFromPoint?.(x, y);
+  return range ? { offsetNode: range.startContainer, offset: range.startOffset } : null;
+}
+function renderedOffsetAt(container, x, y) {
+  const position = caretPositionAt(x, y);
+  if (!position || position.offsetNode.nodeType !== Node.TEXT_NODE) return null;
+  if (!container.contains(position.offsetNode)) return null;
+  const walker = document.createTreeWalker(container, NodeFilter.SHOW_TEXT);
+  let before = 0;
+  while (walker.nextNode()) {
+    if (walker.currentNode === position.offsetNode) return before + position.offset;
+    before += walker.currentNode.textContent?.length ?? 0;
+  }
+  return null;
+}
 var PROBE_LENGTHS = [40, 20, 8];
-function sourceOffsetFor(source, clickedText) {
-  const text = clickedText.replace(/\s+/g, " ").trim();
-  if (text === "") return 0;
-  const whole = source.indexOf(text);
-  if (whole !== -1) return whole;
+function search(source, probe) {
+  const literal = probe.clickedText.trim();
+  if (literal === "" || literal === probe.rendered.trim()) return source.length;
+  const candidates = [literal, literal.replace(/\s+/g, " ")];
+  for (const text of candidates) {
+    const whole = source.indexOf(text);
+    if (whole !== -1) return whole;
+  }
   for (const length of PROBE_LENGTHS) {
-    if (text.length < length) continue;
-    const at = source.indexOf(text.slice(0, length));
-    if (at !== -1) return at;
+    for (const text of candidates) {
+      if (text.length < length) continue;
+      const at = source.indexOf(text.slice(0, length));
+      if (at !== -1) return at;
+    }
+  }
+  return source.length;
+}
+function sourceOffsetFor(source, probe) {
+  if (probe.renderedOffset !== null && probe.rendered === source) {
+    return Math.max(0, Math.min(probe.renderedOffset, source.length));
   }
-  return 0;
+  return search(source, probe);
 }
 
 // src/canvas/BlockCard.tsx
@@ -1865,14 +1904,14 @@ function BlockCardImpl({
   onUpdate,
   onInsertBlock
 }) {
-  const { blockTypes } = useQuoin();
+  const { blockTypes, onError } = useQuoin();
   const definition = blockByType(blockTypes, block.type);
   const Preview = definition?.preview;
   const [editing, setEditing] = React8.useState(editingByDefault && !readOnly);
   const editButtonRef = React8.useRef(null);
   const editorContainerRef = React8.useRef(null);
   const returnFocusOnClose = React8.useRef(false);
-  const clickedTextRef = React8.useRef(null);
+  const clickedRef = React8.useRef(null);
   const scrollTopRef = React8.useRef(null);
   const handleInsertBlock = React8.useCallback(
     (type) => onInsertBlock?.(index + 1, type),
@@ -1916,8 +1955,8 @@ function BlockCardImpl({
       'textarea, input, [role="combobox"]'
     );
     if (!field) return;
-    const clicked = clickedTextRef.current;
-    clickedTextRef.current = null;
+    const clicked = clickedRef.current;
+    clickedRef.current = null;
     if (clicked === null || !(field instanceof HTMLTextAreaElement)) {
       field.focus();
       if (field instanceof HTMLTextAreaElement) {
@@ -1942,6 +1981,12 @@ function BlockCardImpl({
     returnFocusOnClose.current = false;
     editButtonRef.current?.focus();
   }, [editing]);
+  const reportedType = React8.useRef(null);
+  React8.useEffect(() => {
+    if (definition || reportedType.current === block.type) return;
+    reportedType.current = block.type;
+    onError(new Error(`No block type is registered for "${block.type}".`));
+  }, [definition, block.type, onError]);
   if (definition?.alwaysEditing && !readOnly) {
     return /* @__PURE__ */ jsx22(
       BlockEditor,
@@ -1981,7 +2026,7 @@ function BlockCardImpl({
       }
     );
   }
-  const rest = Preview ? /* @__PURE__ */ jsx22(Preview, { data: block.data, blockId: block.id }) : definition ? /* @__PURE__ */ jsx22("p", { className: "py-1 text-sm text-muted-foreground", children: definition.label }) : null;
+  const rest = Preview ? /* @__PURE__ */ jsx22(Preview, { data: block.data, blockId: block.id }) : /* @__PURE__ */ jsx22("p", { className: "py-1 text-sm text-muted-foreground", children: definition?.label ?? block.type });
   if (readOnly) return /* @__PURE__ */ jsx22("div", { children: rest });
   return /* @__PURE__ */ jsxs15("div", { className: "group/card relative", children: [
     /* @__PURE__ */ jsx22(
@@ -1991,7 +2036,11 @@ function BlockCardImpl({
           const target = e.target;
           if (target.closest(INTERACTIVE_SELECTOR)) return;
           if (hasSelectionWithin(e.currentTarget)) return;
-          clickedTextRef.current = target.textContent ?? "";
+          clickedRef.current = {
+            rendered: e.currentTarget.textContent ?? "",
+            clickedText: target.textContent ?? "",
+            renderedOffset: renderedOffsetAt(e.currentTarget, e.clientX, e.clientY)
+          };
           scrollTopRef.current = (document.scrollingElement ?? document.documentElement).scrollTop;
           setEditing(true);
         },
@@ -2225,6 +2274,15 @@ function SortableBlock({
 
 // src/canvas/BlockCanvas.tsx
 import { jsx as jsx26, jsxs as jsxs19 } from "react/jsx-runtime";
+var UNACKNOWLEDGED_LIMIT = 64;
+function remember(outstanding, blocks) {
+  outstanding.add(blocks);
+  while (outstanding.size > UNACKNOWLEDGED_LIMIT) {
+    const oldest = outstanding.values().next();
+    if (oldest.done) return;
+    outstanding.delete(oldest.value);
+  }
+}
 function Canvas({
   blocks,
   onChange,
@@ -2251,16 +2309,22 @@ function Canvas({
   );
   const lastEmitted = React11.useRef(blocks);
   const lastSupplied = React11.useRef(blocks);
+  const unacknowledged = React11.useRef(/* @__PURE__ */ new Set());
   React11.useEffect(() => {
     if (list.blocks === lastEmitted.current) return;
     lastEmitted.current = list.blocks;
+    remember(unacknowledged.current, list.blocks);
     onChange(list.blocks);
   }, [list.blocks, onChange]);
   React11.useEffect(() => {
     const previous = lastSupplied.current;
     lastSupplied.current = blocks;
-    if (blocks === lastEmitted.current) return;
+    if (unacknowledged.current.has(blocks)) {
+      if (blocks === lastEmitted.current) unacknowledged.current.clear();
+      return;
+    }
     if (sameBlocks(blocks, previous) || sameBlocks(blocks, list.blocks)) return;
+    unacknowledged.current.clear();
     lastEmitted.current = blocks;
     reset(blocks);
   }, [blocks, reset]);
@@ -2465,13 +2529,25 @@ export {
   BlockCanvas,
   QuoinProvider,
   TEXT_COMMANDS,
+  applyEdit,
   blockByType,
+  caretRect,
+  continueList,
   coreBlocks,
   defineBlock,
+  formatShortcut,
+  indentList,
+  insertCommand,
+  lineAt,
+  linkPaste,
   paletteBlocks,
+  shouldOpenPalette,
+  toggleLinePrefix,
   useAutoGrow,
   useAutosave,
   useBlockList,
-  useQuoin
+  useMarkdownKeymap,
+  useQuoin,
+  wrapSelection
 };
 //# sourceMappingURL=index.js.map