quoin-editor 0.2.0 → 0.4.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. */
@@ -132,6 +153,54 @@ declare function BlockCanvas({ blocks, onChange, onDelete, blockTypes, upload, r
 /** 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. */
@@ -199,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;
 };
@@ -318,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, 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 };
+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. */
@@ -132,6 +153,54 @@ declare function BlockCanvas({ blocks, onChange, onDelete, blockTypes, upload, r
 /** 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. */
@@ -199,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;
 };
@@ -318,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, 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 };
+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.js

@@ -52,12 +52,12 @@ function blockByType(definitions, type) {
   return void 0;
 }
 function paletteBlocks(definitions) {
-  const seen = /* @__PURE__ */ new Set();
+  const seen2 = /* @__PURE__ */ new Set();
   const out = [];
   for (let i = definitions.length - 1; i >= 0; i -= 1) {
     const d = definitions[i];
-    if (seen.has(d.type)) continue;
-    seen.add(d.type);
+    if (seen2.has(d.type)) continue;
+    seen2.add(d.type);
     if (d.inSlashPalette === false) continue;
     out.push(d);
   }
@@ -1478,12 +1478,12 @@ function FileBlockEditor({ data, onChange }) {
 // src/blocks/previews.tsx
 import { jsx as jsx18 } from "react/jsx-runtime";
 var HINT = "text-sm text-muted-foreground";
-var TONE_BORDER = {
-  info: "border-primary",
-  tip: "border-accent-foreground",
-  warning: "border-muted-foreground",
-  success: "border-secondary-foreground",
-  danger: "border-destructive"
+var TONE = {
+  info: "border-info bg-info/15",
+  tip: "border-primary bg-primary/15",
+  warning: "border-warning bg-warning/15",
+  success: "border-success bg-success/15",
+  danger: "border-destructive bg-destructive/15"
 };
 function MarkdownPreview({ data }) {
   const markdown = str(data.markdown);
@@ -1510,8 +1510,8 @@ function CalloutPreview({ data }) {
   const body = str(data.body);
   if (body.trim() === "") return /* @__PURE__ */ jsx18("p", { className: HINT, children: "Empty callout" });
   const tone = str(data.tone) || "info";
-  const border = TONE_BORDER[tone] ?? "border-border";
-  return /* @__PURE__ */ jsx18("div", { "data-tone": tone, className: `rounded-md border-l-4 ${border} bg-muted/50 p-3 text-sm`, children: body });
+  const paint = TONE[tone] ?? "border-border bg-muted/50";
+  return /* @__PURE__ */ jsx18("div", { "data-tone": tone, className: `rounded-md border-l-4 ${paint} p-3 text-sm`, children: body });
 }
 
 // src/blocks/core.ts
@@ -1825,9 +1825,8 @@ function BlockEditor({
   onDone
 }) {
   const { blockTypes } = useQuoin();
-  const definition = blockByType(blockTypes, type);
-  if (!definition) return null;
-  const Editor = definition.editor;
+  const Editor = blockByType(blockTypes, type)?.editor;
+  if (!Editor) return null;
   return /* @__PURE__ */ jsx21(Editor, { data, onChange, onInsertBlock, onDone });
 }
 
@@ -1876,6 +1875,15 @@ function sourceOffsetFor(source, probe) {
   return search(source, probe);
 }
 
+// src/dev-warn.ts
+var seen = /* @__PURE__ */ new Set();
+function devWarn(message) {
+  if (typeof process !== "undefined" && process?.env?.NODE_ENV === "production") return;
+  if (seen.has(message)) return;
+  seen.add(message);
+  console.warn(`Quoin: ${message}`);
+}
+
 // src/canvas/BlockCard.tsx
 import { jsx as jsx22, jsxs as jsxs15 } from "react/jsx-runtime";
 var INTERACTIVE_SELECTOR = 'a, button, input, textarea, select, [role="button"], [tabindex], iframe';
@@ -1897,7 +1905,8 @@ function BlockCardImpl({
   const { blockTypes, onError } = useQuoin();
   const definition = blockByType(blockTypes, block.type);
   const Preview = definition?.preview;
-  const [editing, setEditing] = React8.useState(editingByDefault && !readOnly);
+  const editable = Boolean(definition?.editor) && !readOnly;
+  const [editing, setEditing] = React8.useState(editingByDefault && editable);
   const editButtonRef = React8.useRef(null);
   const editorContainerRef = React8.useRef(null);
   const returnFocusOnClose = React8.useRef(false);
@@ -1977,7 +1986,13 @@ function BlockCardImpl({
     reportedType.current = block.type;
     onError(new Error(`No block type is registered for "${block.type}".`));
   }, [definition, block.type, onError]);
-  if (definition?.alwaysEditing && !readOnly) {
+  React8.useEffect(() => {
+    if (!readOnly || !definition || definition.preview) return;
+    devWarn(
+      `the block type "${block.type}" has no \`preview\`, so a read-only canvas can draw only its label. Give its definition a \`preview\` to render the block itself.`
+    );
+  }, [readOnly, definition, block.type]);
+  if (definition?.alwaysEditing && editable) {
     return /* @__PURE__ */ jsx22(
       BlockEditor,
       {
@@ -2017,7 +2032,7 @@ function BlockCardImpl({
     );
   }
   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 });
+  if (!editable) return /* @__PURE__ */ jsx22("div", { children: rest });
   return /* @__PURE__ */ jsxs15("div", { className: "group/card relative", children: [
     /* @__PURE__ */ jsx22(
       "div",
@@ -2473,6 +2488,9 @@ function BlockCanvas({
 
 // src/hooks/useAutosave.ts
 import * as React12 from "react";
+function reportedFailure(result) {
+  return typeof result === "object" && result !== null && "ok" in result && result.ok === false;
+}
 function useAutosave({
   deps,
   build,
@@ -2496,7 +2514,7 @@ function useAutosave({
         setStatus("saving");
         try {
           const res = await saveRef.current(buildRef.current());
-          if (res && res.ok === false) throw new Error("save rejected");
+          if (reportedFailure(res)) throw new Error("save rejected");
           retryRef.current = 0;
           dirtyRef.current = false;
           setStatus("saved");
@@ -2512,10 +2530,10 @@ function useAutosave({
   });
   const seenRef = React12.useRef(null);
   React12.useEffect(() => {
-    const seen = seenRef.current;
+    const seen2 = seenRef.current;
     seenRef.current = deps;
-    if (seen === null) return;
-    const unchanged = seen.length === deps.length && seen.every((v, i) => v === deps[i]);
+    if (seen2 === null) return;
+    const unchanged = seen2.length === deps.length && seen2.every((v, i) => v === deps[i]);
     if (!unchanged) dirtyRef.current = true;
   }, deps);
   React12.useEffect(() => {