quoin-editor 0.1.1 → 0.3.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
@@ -37,6 +41,8 @@ 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`.
@@ -68,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[] }) {
@@ -89,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.
@@ -124,6 +133,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.
@@ -222,17 +271,82 @@ 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.
+- **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
 
-A block editor receives only `data` and `onChange`. The canvas configuration reaches it through `useQuoin()`, which returns `blockTypes`, `upload`, `resolveAssetUrl` and `onError`. It throws outside a `QuoinProvider`, so call it from a block the canvas is rendering.
+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';
@@ -352,77 +466,119 @@ 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 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;
 }
-```
-
-Override any of them from your own CSS. They are declared inside `@layer base`, so a plain `:root` rule of yours wins without `!important`:
 
-```css
-:root {
-  --primary: oklch(0.55 0.2 260);
-  --radius: 0.5rem;
+.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;
 }
 ```
 
-A project that already defines shadcn-style tokens with these names inherits its theme for free, with nothing to configure.
+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.
 
-### When a token name collides
+### The prefix arrived in 0.2.0
 
-The same unprefixed names that make that inheritance free also let a collision happen by accident. A project that already declares one of them for something else hands Quoin a value nobody meant it to read, and Quoin cannot tell that apart from a theme deliberately shared with it.
+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 to know about. It declares `--accent` as a bright purple and `--border` on `:root` with meanings of its own, so a fresh `npm create vite` project that installs Quoin draws 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.
+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.
 
-Declare the tokens you did not mean to share on `.quoin` instead. 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. It sits closer to the elements reading the token than your `:root` rule does, so it wins without `!important` and leaves your own `--accent` untouched.
+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 {
-  --accent: oklch(0.97 0 0);
-  --accent-foreground: oklch(0.205 0 0);
-  --border: oklch(0.922 0 0);
+  --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);
+}
+```
+
+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 {
+  --quoin-primary: oklch(0.55 0.2 260);
+  --quoin-radius: 0.5rem;
 }
 
-.dark .quoin {
-  --accent: oklch(0.269 0 0);
-  --accent-foreground: oklch(0.985 0 0);
-  --border: oklch(1 0 0 / 10%);
+.dark {
+  --quoin-primary: oklch(0.72 0.17 260);
 }
 ```
 
-Both rules are needed once you take a token over: pinning `--accent` on `.quoin` alone would also beat Quoin's own `.dark` value and freeze that token in its light form.
+### Dark mode
 
-Quoin keeps the unprefixed names rather than reading `--quoin-accent`. A prefix would stop the accident, but it would also cancel the free inheritance for every project that is already relying on it, and the package cannot tell a deliberate `--accent` from an accidental one.
+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; }
@@ -435,6 +591,48 @@ 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.
+
+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.
@@ -508,7 +706,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`, `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), 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.