quoin-editor 0.1.0 → 0.2.0

package/README.md

@@ -37,18 +37,20 @@ export function Editor() {
 
 A document is an array of `QuoinBlock`, each `{ id, type, data }`. Five block types ship by default: `MARKDOWN`, `CALLOUT`, `CODE`, `IMAGE` and `FILE`. The main entry point is marked `'use client'`, so render `BlockCanvas` from a client component.
 
+If your application has Tailwind of its own, import the stylesheet from your CSS into a layer you have named instead of from JavaScript, so you decide which of the two wins. See [Cascade layers and import order](#cascade-layers-and-import-order).
+
 ## The controlled-component contract
 
 `BlockCanvas` behaves like a controlled `<input value onChange>`. Update `blocks` synchronously from `onChange`.
 
-If you apply the edit late, typing reverts. A debounce, a `startTransition`, or an async store all break the contract for the same reason a debounced parent breaks a controlled input: the canvas renders the keystroke, your state has not caught up, and the next render hands the old document back.
+Applying the edit late is tolerated, as long as what you eventually hand back is one of the arrays the canvas gave you. It recognises its own output even when the echo is several keystrokes behind, so `startTransition` and a debounced `setBlocks` both keep typing intact.
 
 ```tsx
 import { startTransition, useState } from 'react';
 import { BlockCanvas, type QuoinBlock } from 'quoin-editor';
 import 'quoin-editor/styles.css';
 
-export function BrokenEditor() {
+export function TransitionEditor() {
   const [blocks, setBlocks] = useState<QuoinBlock[]>([]);
   return (
     <BlockCanvas
@@ -59,6 +61,8 @@ export function BrokenEditor() {
 }
 ```
 
+What breaks is a store that rebuilds the document on the way through, so what comes back is a structural copy rather than the array the canvas emitted. Arriving behind the canvas's own state, that copy reads as a foreign document and replaces live text with an older snapshot. The damage is not a clean revert: the characters the snapshot predates are dropped and the ones typed after them are kept, so `ZZTYPED hello world` can land as `ZZYED hello wold`. A Redux or Zustand round trip that clones the document, and a server-synced store, are the usual sources.
+
 Debounce the side effect, not the state. `useAutosave` does exactly that: it tracks the values you give it, waits for the edits to settle, then calls your `save`, and it retries a failed save with exponential backoff.
 
 ```tsx
@@ -122,6 +126,46 @@ export function EditorWithDiscard({ saved }: { saved: QuoinBlock[] }) {
 
 The structural comparison is shallow over each block's `data`. A host whose block `data` contains nested objects rebuilt on every render, and which does not echo `onChange` back into `blocks`, can still lose an edit. All five core block types have flat data, so this only affects custom blocks. Keep `data` flat, or keep it referentially stable.
 
+### Undoing a deletion
+
+`onChange` reports a new array and nothing about what changed, so a host that wants a "Block deleted / Undo" toast would have to diff two arrays to find out. `onDelete` tells it instead: it fires 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 that block, so by the time your handler runs the new array has already been reported. Restoring is an ordinary document load: splice the block back at its index and supply the result as `blocks`.
+
+Do that on a later tick or a later interaction, such as the click of an Undo toast, which is what the sample below does. A restore applied synchronously inside `onDelete` is batched together with the echo of the deletion, so what reaches the canvas is structurally equal to the document it last had from you, which it reads as an unrelated re-render and ignores. Nothing throws; the deletion simply stands.
+
+```tsx
+import { useState } from 'react';
+import { BlockCanvas, type QuoinBlock } from 'quoin-editor';
+import 'quoin-editor/styles.css';
+
+export function EditorWithUndo({ saved }: { saved: QuoinBlock[] }) {
+  const [blocks, setBlocks] = useState<QuoinBlock[]>(saved);
+  const [removed, setRemoved] = useState<{ block: QuoinBlock; index: number } | null>(null);
+
+  function restore() {
+    if (!removed) return;
+    const next = [...blocks];
+    next.splice(removed.index, 0, removed.block);
+    setBlocks(next);
+    setRemoved(null);
+  }
+
+  return (
+    <>
+      <BlockCanvas blocks={blocks} onChange={setBlocks} onDelete={(block, index) => setRemoved({ block, index })} />
+      {removed && (
+        <button type="button" onClick={restore}>
+          Undo delete
+        </button>
+      )}
+    </>
+  );
+}
+```
+
+A restored block comes back at rest, even one that was inserted moments before it was deleted, so the undo does not pull the caret out of whatever is being written.
+
 ## Hoist `blockTypes` and your handlers
 
 `BlockCanvas` builds its configuration from `blockTypes`, `upload`, `resolveAssetUrl` and `onError`, and memoises it on their identity. Pass a new array or a new function on every render and the memo is busted, which re-renders every block editor on the page.
@@ -228,6 +272,74 @@ A definition has these fields:
 
 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.
 
+### Reaching uploads from a custom block
+
+A block editor receives only `data` and `onChange`, but the canvas configuration reaches it through context, so an upload control inside a custom block needs no wiring from you.
+
+`UploadField` is the control the image and file blocks use, and it is exported for yours. It reads `upload` from the canvas it is rendered in, disables itself while a file is in flight, announces the progress to assistive technology, renders a rejection's message beside the button, and says that uploads are not configured when the host wired none.
+
+```tsx
+import { UploadField, type BlockEditorProps } from 'quoin-editor';
+
+type SlidesData = { storageKey: string; filename: string };
+
+export function SlidesEditor({ data, onChange }: BlockEditorProps<SlidesData>) {
+  return (
+    <div>
+      <p>{data.storageKey === '' ? 'No deck yet' : data.filename}</p>
+      <UploadField
+        category="slides"
+        label="Upload slides"
+        accept=".pdf"
+        onUploaded={(result) => onChange({ storageKey: result.storageKey, filename: result.filename })}
+      />
+    </div>
+  );
+}
+```
+
+Register that editor with `defineBlock` as above, and the canvas's `upload` function receives `'slides'` as its category. `UploadField` takes `category`, `label`, an optional `accept` and `onUploaded`.
+
+`FilePickerButton` is the picker underneath it: a labelled button laid over a transparent file input, which hands you the chosen `File` and uploads nothing itself. Take that one when you want your own busy and error presentation.
+
+For anything neither control covers, `useQuoin()` returns `blockTypes`, `upload`, `resolveAssetUrl` and `onError`. It throws outside a `QuoinProvider`, so call it from a block the canvas is rendering.
+
+```tsx
+import { useQuoin, type BlockEditorProps } from 'quoin-editor';
+
+type AttachmentData = { storageKey: string; filename: string };
+
+export function AttachmentEditor({ data, onChange }: BlockEditorProps<AttachmentData>) {
+  const { upload, resolveAssetUrl, onError } = useQuoin();
+
+  async function store(file: File) {
+    if (!upload) return;
+    try {
+      const stored = await upload(file, 'attachment');
+      onChange({ storageKey: stored.storageKey, filename: stored.filename });
+    } catch (error) {
+      onError(error instanceof Error ? error : new Error('The upload failed.'));
+    }
+  }
+
+  return (
+    <div>
+      {data.storageKey !== '' && <a href={resolveAssetUrl(data.storageKey)}>{data.filename}</a>}
+      <input
+        type="file"
+        disabled={!upload}
+        onChange={(event) => {
+          const file = event.target.files?.[0];
+          if (file) void store(file);
+        }}
+      />
+    </div>
+  );
+}
+```
+
+`upload` is absent when the host wired none, which is why the control above disables itself rather than failing on the pick. `resolveAssetUrl` defaults to returning the key unchanged, and `onError` to `console.error`.
+
 The preview is also how you bring your own markdown renderer. Register a `MARKDOWN` definition last, reuse the core editor, and swap the preview:
 
 ```tsx
@@ -312,49 +424,115 @@ export function Reader({ blocks }: { blocks: QuoinBlock[] }) {
 
 ## Theming
 
-`quoin-editor/styles.css` is compiled Tailwind CSS v4 and defines these custom properties:
+`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:
 
 ```css
 :root {
-  --background: oklch(1 0 0);
-  --foreground: oklch(0.145 0 0);
-  --muted: oklch(0.97 0 0);
-  --muted-foreground: oklch(0.556 0 0);
-  --popover: oklch(1 0 0);
-  --popover-foreground: oklch(0.145 0 0);
-  --border: oklch(0.922 0 0);
-  --input: oklch(0.922 0 0);
-  --ring: oklch(0.708 0 0);
-  --primary: oklch(0.205 0 0);
-  --primary-foreground: oklch(0.985 0 0);
-  --accent: oklch(0.97 0 0);
-  --accent-foreground: oklch(0.205 0 0);
-  --secondary: oklch(0.97 0 0);
-  --secondary-foreground: oklch(0.205 0 0);
-  --destructive: oklch(0.577 0.245 27.325);
-  --radius: 0.625rem;
+  --quoin-background: oklch(1 0 0);
+  --quoin-foreground: oklch(0.145 0 0);
+  --quoin-muted: oklch(0.97 0 0);
+  --quoin-muted-foreground: oklch(0.556 0 0);
+  --quoin-secondary: oklch(0.97 0 0);
+  --quoin-secondary-foreground: oklch(0.205 0 0);
+  --quoin-popover: oklch(1 0 0);
+  --quoin-popover-foreground: oklch(0.145 0 0);
+  --quoin-border: oklch(0.922 0 0);
+  --quoin-input: oklch(0.922 0 0);
+  --quoin-ring: oklch(0.708 0 0);
+  --quoin-primary: oklch(0.205 0 0);
+  --quoin-primary-foreground: oklch(0.985 0 0);
+  --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-radius: 0.625rem;
+}
+
+.dark {
+  --quoin-background: oklch(0.145 0 0);
+  --quoin-foreground: oklch(0.985 0 0);
+  --quoin-muted: oklch(0.269 0 0);
+  --quoin-muted-foreground: oklch(0.708 0 0);
+  --quoin-secondary: oklch(0.269 0 0);
+  --quoin-secondary-foreground: oklch(0.985 0 0);
+  --quoin-popover: oklch(0.205 0 0);
+  --quoin-popover-foreground: oklch(0.985 0 0);
+  --quoin-border: oklch(1 0 0 / 10%);
+  --quoin-input: oklch(1 0 0 / 15%);
+  --quoin-ring: oklch(0.556 0 0);
+  --quoin-primary: oklch(0.922 0 0);
+  --quoin-primary-foreground: oklch(0.205 0 0);
+  --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-radius: 0.625rem;
+}
+```
+
+Out of the box that is a neutral grey editor that works in both modes with nothing configured.
+
+Those are the only custom properties the stylesheet declares. Apart from them it reads `--tw-*`, which belong to the Tailwind runtime it is compiled with, and the `--radix-*` values Radix writes on its own portalled elements while they are open. Tailwind's theme tokens are imported by reference, so the package resolves `--spacing`, `--text-base`, `--container-md` and the rest at build time and declares none of them on your page.
+
+### The prefix arrived in 0.2.0
+
+Until 0.2.0 these names were unprefixed: `--background`, `--accent`, `--border` and the rest. That was sold as free theme inheritance, and for a shadcn-style host it was. It also meant Quoin read whatever a host happened to keep under those names.
+
+The stock Vite React + TypeScript template is the case that forced the change. It declares `--accent` as a bright purple and `--border` on `:root` with meanings of its own, so a fresh `npm create vite` project that installed Quoin drew the selected slash-palette row on that purple while keeping Quoin's own near-black `--accent-foreground`. The pair measures around 3.2:1, under the 4.5:1 that WCAG AA asks for, with nothing done wrong by the consumer.
+
+A fallback form such as `var(--quoin-accent, var(--accent))` does not fix that, because the colliding value is exactly what gets read when only the unprefixed name is set. So the prefix is unconditional, and the inheritance is no longer free. If your theme stopped reaching Quoin when you upgraded, this is why, and the next section is how to hand it over again.
+
+### Mapping your own tokens
+
+Point the prefixed names at your own in one block on `.quoin`. The canvas root carries that class, and so do the menus, palette, select and dialog Quoin renders into `document.body`, so one rule covers all of them.
+
+```css
+.quoin {
+  --quoin-background: var(--background);
+  --quoin-foreground: var(--foreground);
+  --quoin-muted: var(--muted);
+  --quoin-muted-foreground: var(--muted-foreground);
+  --quoin-secondary: var(--secondary);
+  --quoin-secondary-foreground: var(--secondary-foreground);
+  --quoin-popover: var(--popover);
+  --quoin-popover-foreground: var(--popover-foreground);
+  --quoin-border: var(--border);
+  --quoin-input: var(--input);
+  --quoin-ring: var(--ring);
+  --quoin-primary: var(--primary);
+  --quoin-primary-foreground: var(--primary-foreground);
+  --quoin-accent: var(--accent);
+  --quoin-accent-foreground: var(--accent-foreground);
+  --quoin-destructive: var(--destructive);
+  --quoin-radius: var(--radius);
 }
 ```
 
-Override any of them from your own CSS. They are declared inside `@layer base`, so a plain `:root` rule of yours wins without `!important`:
+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.
 
 ```css
 :root {
-  --primary: oklch(0.55 0.2 260);
-  --radius: 0.5rem;
+  --quoin-primary: oklch(0.55 0.2 260);
+  --quoin-radius: 0.5rem;
+}
+
+.dark {
+  --quoin-primary: oklch(0.72 0.17 260);
 }
 ```
 
-A project that already defines shadcn-style tokens with these names inherits its theme for free, with nothing to configure.
+### Dark mode
+
+Dark mode keys on a `.dark` class on an ancestor (for example `<html class="dark">`), not on `prefers-color-scheme`. Quoin redefines its own tokens under `.dark`, and its `dark:` variants follow the same class, so the two cannot disagree when a visitor's OS theme differs from your app's theme.
 
-Dark mode keys on a `.dark` class on an ancestor (for example `<html class="dark">`), not on `prefers-color-scheme`. Quoin redefines the same variables under `.dark`, and its `dark:` variants follow the same class, so the two cannot disagree when a visitor's OS theme differs from your app's theme.
+### Resets
 
 Quoin does not reset your page. The stylesheet contains no `html`, `body`, heading, list or other element rules, and no universal `*` reset. Its own reset (box sizing, zero margins, unstyled lists and form controls) applies only inside a `.quoin` element: the canvas root, and the menus, palette, select and dialog that Quoin renders into `document.body`, which carry the class themselves. Your headings, paragraphs, lists and buttons keep whatever styles you gave them, or the browser's.
 
 All of Quoin's own rules are in cascade layers, so an **unlayered** global reset of yours beats them. A host that ships one (Bootstrap's reboot, or a hand-rolled `* { margin: 0; padding: 0; border: 0 }`) will see Quoin's padding and borders vanish. Tailwind 4's preflight is itself layered and is fine. Either declare your reset in a layer that comes before Quoin's, or scope it away from `.quoin`:
 
 ```css
-@layer reset, theme, base, components, utilities;
+@layer reset, theme, base, components, quoin, utilities;
 
 @layer reset {
   * { margin: 0; padding: 0; border: 0; }
@@ -367,6 +545,34 @@ 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.
 
+### 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.
+
+That changed in 0.2.0, and it had to. Until then the package imported Tailwind's utilities into the bare `utilities` layer, so in a Tailwind host they appended into the host's own `utilities` layer, after the host's rules, and beat them on source order. One bare `.hidden { display: none }` from the package was enough to keep every element carrying `hidden md:block` hidden at every width, across the whole application.
+
+The package cannot settle this on its own, because a browser orders layers by first appearance. A host whose own Tailwind is parsed first registers `theme`, `base`, `components` and `utilities` before `quoin` appears, so `quoin` sorts last and still wins. Name the order yourself, as the first thing in your stylesheet, and import Quoin into it:
+
+```css
+@layer theme, base, components, quoin, utilities;
+@import "quoin-editor/styles.css" layer(quoin);
+```
+
+With `quoin` named before `utilities`, your own utilities outrank Quoin's, including the responsive ones, while Quoin still outranks your `components`.
+
+Naming it first instead puts every layer of yours above the package:
+
+```css
+@layer quoin, theme, base, components, utilities;
+@import "quoin-editor/styles.css" layer(quoin);
+```
+
+Layer position settles more than which utility wins. It also settles who owns a custom property both of you declare on `:root`, which is why it is worth deciding rather than inheriting. Quoin no longer declares any name Tailwind owns, because it imports Tailwind's theme by reference, but a package that does, including Quoin before 0.2.0, resizes every `p-4` on the page from whichever layer sorts last.
+
+**Upgrading alone does not fix this.** Import 0.2.0 the way 0.1.1 was imported, with no layer statement of your own, and a host's `hidden md:block` still computes to `display: none`, exactly as before. The layer the package ships is what makes the fix available to you; the two lines above are what apply it.
+
+Importing the stylesheet from a root layout, or with a plain `import 'quoin-editor/styles.css'` in JavaScript, gives you no say in where the layer lands. The bundler decides, and in a Tailwind host that usually means Quoin's layer sorts last. That is fine for an application with no Tailwind of its own, and it is what the samples in this README do for brevity. A Tailwind host should use the two lines above and drop the JavaScript import.
+
 ## Headless
 
 `quoin-editor/headless` is the text-editing core with no UI in it: pure transforms over a string and a selection, plus two hooks. It has no component or UI library dependency, and its bundle carries no `'use client'` banner, so the pure functions can be imported from a React Server Component.
@@ -393,7 +599,7 @@ export function bold(text: string, start: number, end: number): string {
 }
 ```
 
-`useMarkdownKeymap` and `useAutoGrow` are hooks, so they can only be called from a client component, even though the module that exports them is safe to import anywhere.
+`useMarkdownKeymap` and `useAutoGrow` are importable from a React Server Component, because the module that exports them carries no `'use client'` banner. Being hooks, they are callable only from a client component.
 
 ```tsx
 'use client';
@@ -426,11 +632,21 @@ export function Notes() {
 
 The keymap swallows a `/` typed at the start of a word (at the start of the text, or after a newline, space or tab, outside a code fence) and calls `onOpenPalette` instead, so open a palette of your own there, or insert the slash yourself.
 
-The same functions and hooks are also exported from the main `quoin-editor` entry, alongside `TEXT_COMMANDS`, the built-in slash-palette entries.
+Everything in the table is re-exported from the main `quoin-editor` entry too, alongside `TEXT_COMMANDS`, the built-in slash-palette entries. Import from `quoin-editor/headless` when you want the transforms without the components behind them, and from `quoin-editor` when you are already importing `BlockCanvas`.
+
+```ts
+import { toggleLinePrefix } from 'quoin-editor';
+
+export function heading(text: string, start: number, end: number): string {
+  return toggleLinePrefix('h2', text, start, end).value;
+}
+```
+
+The main entry carries a `'use client'` banner, so a React Server Component has to import from `quoin-editor/headless` rather than from `quoin-editor`.
 
 ## Exports
 
-From `quoin`: `BlockCanvas`, `QuoinProvider`, `useQuoin`, `defineBlock`, `blockByType`, `paletteBlocks`, `coreBlocks`, `TEXT_COMMANDS`, `useBlockList`, `useAutosave`, `useAutoGrow`, and the headless transforms and hooks, with their types (`QuoinBlock`, `UploadFn`, `UploadResult`, `BlockDefinition`, `AnyBlockDefinition`, `BlockEditorProps`, `BlockPreviewProps`, `BlockCanvasProps` 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).
 
 From `quoin-editor/headless`: the transforms and the two hooks listed above, with no UI.