quoin-editor 0.1.0 → 0.1.1

package/README.md

@@ -41,14 +41,14 @@ A document is an array of `QuoinBlock`, each `{ id, type, data }`. Five block ty
 
 `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 +59,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
@@ -228,6 +230,46 @@ 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`. 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.
+
+```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
@@ -347,6 +389,32 @@ Override any of them from your own CSS. They are declared inside `@layer base`,
 
 A project that already defines shadcn-style tokens with these names inherits its theme for free, with nothing to configure.
 
+### When a token name collides
+
+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.
+
+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.
+
+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.
+
+```css
+.quoin {
+  --accent: oklch(0.97 0 0);
+  --accent-foreground: oklch(0.205 0 0);
+  --border: oklch(0.922 0 0);
+}
+
+.dark .quoin {
+  --accent: oklch(0.269 0 0);
+  --accent-foreground: oklch(0.985 0 0);
+  --border: oklch(1 0 0 / 10%);
+}
+```
+
+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.
+
+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 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.
 
 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.
@@ -393,7 +461,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 +494,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`, `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/headless`: the transforms and the two hooks listed above, with no UI.
 

package/dist/index.cjs

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