quoin-editor 0.2.0 → 0.4.0

package/README.md

@@ -22,6 +22,10 @@ yarn add quoin-editor
 
 Quoin needs React 18.2 or later (React 19 is supported) and TypeScript 5.4 or later if you use TypeScript. The block registry relies on the built-in `NoInfer` utility type, which arrived in 5.4.
 
+**Tailwind is not required, and either major version works.** See [Tailwind, or no Tailwind](#tailwind-or-no-tailwind) for the one thing a v4 host has to do.
+
+The package is around 200 kB packed. It depends on `@dnd-kit` for dragging, five Radix primitives, `cmdk` for the slash palette, `lucide-react` for the icons, and `clsx`, `tailwind-merge` and `class-variance-authority` for class composition. That is the price of the canvas: the cards, the drag gutter, the inserters, the palette and the dialogs. If you want the text editing and none of the UI, [`quoin-editor/headless`](#headless) has no component or UI library dependency at all.
+
 ## Quickstart
 
 ```tsx
@@ -70,8 +74,9 @@ import { useState } from 'react';
 import { BlockCanvas, useAutosave, type QuoinBlock } from 'quoin-editor';
 import 'quoin-editor/styles.css';
 
-async function saveDocument(blocks: QuoinBlock[]): Promise<void> {
-  await fetch('/api/document', { method: 'PUT', body: JSON.stringify(blocks) });
+async function saveDocument(blocks: QuoinBlock[]) {
+  const response = await fetch('/api/document', { method: 'PUT', body: JSON.stringify(blocks) });
+  return response.json() as Promise<{ revision: number }>;
 }
 
 export function AutosavingEditor({ initial }: { initial: QuoinBlock[] }) {
@@ -91,6 +96,8 @@ export function AutosavingEditor({ initial }: { initial: QuoinBlock[] }) {
 }
 ```
 
+`save` may return anything, so a mutation, an axios call or a `fetch` that resolves to a body goes straight in with no wrapper to discard the value. A save fails by rejecting, or by resolving to an explicit `{ ok: false }`; everything else, `undefined` included, is a success. `status` moves `idle` to `saving` to `saved`, or to `retrying` while it backs off, and `retry()` tries again at once.
+
 ### Loading, undoing and discarding
 
 You can hand the canvas a new `blocks` array at any time to load, undo or merge a document. A new array replaces what the canvas shows when it differs from the last array you supplied.
@@ -264,13 +271,50 @@ A definition has these fields:
 | `type` | yes | The string stored on each block. It is how the registry finds the definition. |
 | `label` | yes | The name shown in menus and the slash palette. |
 | `icon` | yes | A [lucide](https://lucide.dev) icon component. Quoin depends on `lucide-react@^1`; add that same major to your own dependencies to import icons, so you do not end up with a second copy and mismatched icon types. |
-| `editor` | yes | The editing surface. It receives `data` and `onChange`. Call `onChange` with the whole next `data`, not a patch. |
-| `preview` | no | What the block shows when it is not being edited. Omit it for an edit-only block. |
+| `editor` | one of the two | The editing surface. It receives `data` and `onChange`. Call `onChange` with the whole next `data`, not a patch. Omit it for a block that is never editable here. |
+| `preview` | one of the two | What the block shows when it is not being edited. Omit it for an edit-only block. |
 | `initialData` | no | Seeds `data` when a block of this type is inserted. It is checked against the editor's data type. |
 | `inSlashPalette` | no | Set to `false` to keep the type out of the slash palette and the inserter. Defaults to `true`. |
 | `alwaysEditing` | no | Renders the editor permanently instead of a preview you click to edit. |
 
-A definition that sets `alwaysEditing` should also supply a `preview`. A `readOnly` canvas draws the preview and never the editor, so without a preview the block's content is invisible there.
+Supply `editor`, `preview` or both. Omitting both is a type error, because such a block could only ever draw its own label.
+
+**Omit `editor` for a block that is not yours to edit** here: content that belongs to a server-side record, a generated summary, an audit trail. The card then offers no way in, with no edit button and no click target, and `preview` becomes required because it is the only thing left that can draw the block.
+
+```tsx
+import { ShieldCheck } from 'lucide-react';
+import { defineBlock } from 'quoin-editor';
+
+const audit = defineBlock<{ approver: string }>({
+  type: 'AUDIT',
+  label: 'Audit trail',
+  icon: ShieldCheck,
+  preview: ({ data }) => <p>Signed off by {data.approver}</p>,
+});
+```
+
+**Omit `preview` only for a block you never show read-only.** A `readOnly` canvas draws previews and never editors, so such a block shows nothing there but its own label. Quoin warns once per type in the console when that happens, naming the type. The same applies to `alwaysEditing`, which is also an editor and is also not drawn on a read-only canvas.
+
+### What the core blocks store
+
+Each core block keeps its content under its own keys. A host that persists blocks reads and writes these, so they are exported as types: import them rather than retyping the shapes.
+
+| Type | `data` | Exported as |
+| --- | --- | --- |
+| `MARKDOWN` | `markdown: string` | `MarkdownBlockData` |
+| `CALLOUT` | `tone: string`, `body: string` | `CalloutBlockData` |
+| `CODE` | `language: string`, `code: string` | `CodeBlockData` |
+| `IMAGE` | `storageKey: string`, `alt: string`, `caption?: string`, `width?: number`, `height?: number` | `ImageBlockData` |
+| `FILE` | `storageKey: string`, `filename: string`, `size?: number` | `FileBlockData` |
+
+`CoreBlockData` maps each `type` string to its shape, for a host writing one function over all five.
+
+Two of these are worth saying out loud, because both have been guessed wrong:
+
+- **The callout's prose is `body`, not `text`.** The label over the field reads "Callout text", which is what the author sees; `body` is what the block stores. `tone` is one of `info`, `tip`, `warning`, `success` or `danger`, each drawn in its own colour; anything else falls back to the neutral border and fill.
+- **Markdown blocks store markdown source, not rendered HTML.** Quoin edits and stores the source and renders it as plain text; supply a `preview` if you want it rendered.
+
+The optional fields are written after a 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. `src/blocks/data.test.ts` reads the keys back out of each editor's source and fails if one drifts from the table above.
 
 ### Reaching uploads from a custom block
 
@@ -422,6 +466,8 @@ export function Reader({ blocks }: { blocks: QuoinBlock[] }) {
 
 `readOnly` renders each block's `preview` with no inserters, menus, drag handles or editors. `onChange` is still required by the type, and is never called. `aria-label` names the document for assistive technology, and `className` and `id` go on the root element.
 
+Because it draws previews and never editors, a block type registered without a `preview` has nothing to show here but its own label. Quoin warns once per type in the console when that happens, so give every type you render read-only a `preview`. It is not an error channel: `onError` is for the document, this is for the registration, so it goes to the developer and not to the reader.
+
 ## Theming
 
 `quoin-editor/styles.css` is compiled Tailwind CSS v4. Every colour and every radius it draws with comes from a custom property under a `--quoin-` prefix. It ships a default for all of them, on `:root` for light and on `.dark` for dark:
@@ -444,6 +490,9 @@ export function Reader({ blocks }: { blocks: QuoinBlock[] }) {
   --quoin-accent: oklch(0.97 0 0);
   --quoin-accent-foreground: oklch(0.205 0 0);
   --quoin-destructive: oklch(0.577 0.245 27.325);
+  --quoin-info: oklch(0.55 0.17 250);
+  --quoin-success: oklch(0.55 0.14 155);
+  --quoin-warning: oklch(0.65 0.16 65);
   --quoin-radius: 0.625rem;
 }
 
@@ -464,6 +513,9 @@ export function Reader({ blocks }: { blocks: QuoinBlock[] }) {
   --quoin-accent: oklch(0.269 0 0);
   --quoin-accent-foreground: oklch(0.985 0 0);
   --quoin-destructive: oklch(0.704 0.191 22.216);
+  --quoin-info: oklch(0.72 0.14 250);
+  --quoin-success: oklch(0.74 0.15 155);
+  --quoin-warning: oklch(0.79 0.15 65);
   --quoin-radius: 0.625rem;
 }
 ```
@@ -502,10 +554,15 @@ Point the prefixed names at your own in one block on `.quoin`. The canvas root c
   --quoin-accent: var(--accent);
   --quoin-accent-foreground: var(--accent-foreground);
   --quoin-destructive: var(--destructive);
+  --quoin-info: var(--info);
+  --quoin-success: var(--success);
+  --quoin-warning: var(--warning);
   --quoin-radius: var(--radius);
 }
 ```
 
+`--quoin-info`, `--quoin-success` and `--quoin-warning` arrived in 0.4.0 and are read only by the callout block, for its rule and the wash behind it, never for type. If your own theme has no equivalent, leave those three out of the block and the defaults above stand; the rest of the editor does not touch them.
+
 That one block covers both modes: the tokens on the right already flip with your own dark class, and each mapping beats Quoin's `:root` and `.dark` defaults alike. Write it unlayered, or in a layer that sorts after `quoin`, so it outranks those defaults.
 
 To change one token rather than adopt a whole theme, declare it on `:root`, and pair it with a `.dark` rule if you theme dark at all. Pinning a token on `:root` alone also beats Quoin's `.dark` value for it, which would freeze that one token in its light form.
@@ -545,6 +602,20 @@ All of Quoin's own rules are in cascade layers, so an **unlayered** global reset
 
 The layer statement has to come before Quoin's stylesheet is parsed, so put it first in your own CSS or in an inline `<style>` in the document head.
 
+### Tailwind, or no Tailwind
+
+`quoin-editor/styles.css` is compiled output. Every value in it is already resolved, so it is a plain stylesheet, not a Tailwind plugin, and a project with no Tailwind at all can import it and be done.
+
+If you do use Tailwind, both major versions work, and what you have to do differs:
+
+| Your setup | What to do |
+| --- | --- |
+| **Tailwind v4** | Name the layer order and import Quoin into it, as [below](#cascade-layers-and-import-order). Without it Quoin's layer sorts last and its utilities beat yours. |
+| **Tailwind v3** | Nothing. v3 emits its own utilities unlayered, and an unlayered rule beats a layered one whatever the order, so yours win over Quoin's by construction. |
+| **No Tailwind** | Nothing. Import the stylesheet and the editor is styled. |
+
+**On Tailwind v3, 0.2.0 is the first version that builds at all.** 0.1.1 and earlier emitted bare `@layer base` and `@layer utilities`, which the v3 PostCSS plugin refuses two different ways: importing the stylesheet from a component raises `'@layer base' is used but no matching '@tailwind base' directive is present`, and `@import`ing it from a stylesheet that does carry the `@tailwind` directives raises `TypeError: layerRule.nodes is not iterable`. Nesting everything under `quoin` in 0.2.0 removed both. If you worked around this by copying the stylesheet into `public/`, you can stop.
+
 ### Cascade layers and import order
 
 Everything the stylesheet paints is inside one top-level cascade layer called `quoin`, with nested layers for its own theme, base and utilities inside it. Nothing it ships lands in a bare `theme`, `base`, `components` or `utilities` layer. It carries only the utilities Quoin's own components use, so the set of class names it can collide with at all is small and fixed.
@@ -646,7 +717,7 @@ The main entry carries a `'use client'` banner, so a React Server Component has
 
 ## Exports
 
-From `quoin-editor`: `BlockCanvas`, `QuoinProvider`, `useQuoin`, `defineBlock`, `blockByType`, `paletteBlocks`, `coreBlocks`, `UploadField`, `FilePickerButton`, `TEXT_COMMANDS`, `useBlockList`, `useAutosave`, `useAutoGrow`, and the headless transforms and hooks, with their types (`QuoinBlock`, `UploadFn`, `UploadResult`, `BlockDefinition`, `AnyBlockDefinition`, `BlockEditorProps`, `BlockPreviewProps`, `BlockCanvasProps`, `UploadFieldProps`, `FilePickerButtonProps` and others).
+From `quoin-editor`: `BlockCanvas`, `QuoinProvider`, `useQuoin`, `defineBlock`, `blockByType`, `paletteBlocks`, `coreBlocks`, `UploadField`, `FilePickerButton`, `TEXT_COMMANDS`, `useBlockList`, `useAutosave`, `useAutoGrow`, and the headless transforms and hooks, with their types (`QuoinBlock`, `UploadFn`, `UploadResult`, `BlockDefinition`, `AnyBlockDefinition`, `BlockEditorProps`, `BlockPreviewProps`, `BlockCanvasProps`, `UploadFieldProps`, `FilePickerButtonProps` and others), and the [core block data shapes](#what-the-core-blocks-store): `MarkdownBlockData`, `CalloutBlockData`, `CodeBlockData`, `ImageBlockData`, `FileBlockData` and `CoreBlockData`.
 
 From `quoin-editor/headless`: the transforms and the two hooks listed above, with no UI.
 

package/dist/index.cjs

@@ -104,12 +104,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);
   }
@@ -1519,12 +1519,12 @@ function FileBlockEditor({ data, onChange }) {
 // src/blocks/previews.tsx
 var import_jsx_runtime18 = require("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);
@@ -1551,8 +1551,8 @@ function CalloutPreview({ data }) {
   const body = str(data.body);
   if (body.trim() === "") return /* @__PURE__ */ (0, import_jsx_runtime18.jsx)("p", { className: HINT, children: "Empty callout" });
   const tone = str(data.tone) || "info";
-  const border = TONE_BORDER[tone] ?? "border-border";
-  return /* @__PURE__ */ (0, import_jsx_runtime18.jsx)("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__ */ (0, import_jsx_runtime18.jsx)("div", { "data-tone": tone, className: `rounded-md border-l-4 ${paint} p-3 text-sm`, children: body });
 }
 
 // src/blocks/core.ts
@@ -1866,9 +1866,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__ */ (0, import_jsx_runtime21.jsx)(Editor, { data, onChange, onInsertBlock, onDone });
 }
 
@@ -1917,6 +1916,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
 var import_jsx_runtime22 = require("react/jsx-runtime");
 var INTERACTIVE_SELECTOR = 'a, button, input, textarea, select, [role="button"], [tabindex], iframe';
@@ -1938,7 +1946,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);
@@ -2018,7 +2027,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__ */ (0, import_jsx_runtime22.jsx)(
       BlockEditor,
       {
@@ -2058,7 +2073,7 @@ function BlockCardImpl({
     );
   }
   const rest = Preview ? /* @__PURE__ */ (0, import_jsx_runtime22.jsx)(Preview, { data: block.data, blockId: block.id }) : /* @__PURE__ */ (0, import_jsx_runtime22.jsx)("p", { className: "py-1 text-sm text-muted-foreground", children: definition?.label ?? block.type });
-  if (readOnly) return /* @__PURE__ */ (0, import_jsx_runtime22.jsx)("div", { children: rest });
+  if (!editable) return /* @__PURE__ */ (0, import_jsx_runtime22.jsx)("div", { children: rest });
   return /* @__PURE__ */ (0, import_jsx_runtime22.jsxs)("div", { className: "group/card relative", children: [
     /* @__PURE__ */ (0, import_jsx_runtime22.jsx)(
       "div",
@@ -2514,6 +2529,9 @@ function BlockCanvas({
 
 // src/hooks/useAutosave.ts
 var React12 = __toESM(require("react"), 1);
+function reportedFailure(result) {
+  return typeof result === "object" && result !== null && "ok" in result && result.ok === false;
+}
 function useAutosave({
   deps,
   build,
@@ -2537,7 +2555,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");
@@ -2553,10 +2571,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(() => {