@charcuterie/ui 4.19.0 → 4.20.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@charcuterie/ui",
-  "version": "4.19.0",
+  "version": "4.20.1",
   "description": "The Charcuterie components. Tokens for look, @charcuterie/logic for state, ARIA that agents can actually drive.",
   "license": "MIT",
   "type": "module",
@@ -40,7 +40,17 @@
       "types": "./dist/tokens.d.ts",
       "default": "./dist/tokens.js"
     },
-    "./src/*": "./src/*"
+    "./src/*": "./src/*",
+    "./html-editor": {
+      "source": "./src/htmlEditor/index.ts",
+      "types": "./dist/htmlEditor/index.d.ts",
+      "default": "./dist/htmlEditor/index.js"
+    },
+    "./html-view": {
+      "source": "./src/htmlEditor/view.ts",
+      "types": "./dist/htmlEditor/view.d.ts",
+      "default": "./dist/htmlEditor/view.js"
+    }
   },
   "files": [
     "dist",
@@ -66,6 +76,14 @@
     "@codemirror/state": "^6",
     "@codemirror/view": "^6",
     "@lezer/common": "^1",
+    "@tiptap/core": "^3.31.4",
+    "@tiptap/extension-image": "^3.31.4",
+    "@tiptap/extension-text-align": "^3.31.4",
+    "@tiptap/extension-text-style": "^3.31.4",
+    "@tiptap/pm": "^3.31.4",
+    "@tiptap/react": "^3.31.4",
+    "@tiptap/starter-kit": "^3.31.4",
+    "parse5": "^8.0.1",
     "react": ">=19",
     "react-dom": ">=19",
     "react-router": ">=7"
@@ -89,6 +107,30 @@
     "@lezer/common": {
       "optional": true
     },
+    "@tiptap/core": {
+      "optional": true
+    },
+    "@tiptap/extension-image": {
+      "optional": true
+    },
+    "@tiptap/extension-text-align": {
+      "optional": true
+    },
+    "@tiptap/extension-text-style": {
+      "optional": true
+    },
+    "@tiptap/pm": {
+      "optional": true
+    },
+    "@tiptap/react": {
+      "optional": true
+    },
+    "@tiptap/starter-kit": {
+      "optional": true
+    },
+    "parse5": {
+      "optional": true
+    },
     "react-router": {
       "optional": true
     }
@@ -102,8 +144,16 @@
     "@codemirror/view": "^6",
     "@lezer/common": "^1",
     "@storybook/react": "^10.3.6",
+    "@tiptap/core": "^3.31.4",
+    "@tiptap/extension-image": "^3.31.4",
+    "@tiptap/extension-text-align": "^3.31.4",
+    "@tiptap/extension-text-style": "^3.31.4",
+    "@tiptap/pm": "^3.31.4",
+    "@tiptap/react": "^3.31.4",
+    "@tiptap/starter-kit": "^3.31.4",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
+    "parse5": "^8.0.1",
     "react": "^19.2.8",
     "react-dom": "^19.2.8",
     "react-router": "^8.3.0",

package/src/htmlEditor/HtmlEditor.mdx

@@ -0,0 +1,61 @@
+import { Canvas, Controls, Meta } from "@storybook/addon-docs/blocks";
+import * as HtmlEditorStories from "./HtmlEditor.stories";
+
+<Meta of={HtmlEditorStories} />
+
+# HtmlEditor
+
+Rich authoring for records stored as **HTML**. It lives in the opt-in
+`@charcuterie/ui/html-editor` subpath. Markdown remains a separate format.
+
+<Canvas of={HtmlEditorStories.Playground} />
+
+## Preserve untouched records
+
+`defaultValue` initializes the document once. Focus, selection, blur and toolbar navigation
+never call `onChange`. An optional `name` renders a hidden form control whose original HTML
+bytes stay intact until a real edit. Changes emit sanitized HTML. A changed external default
+does not replace the document or its undo history; use a React `key` to switch records.
+
+```tsx
+import { Field } from "@charcuterie/ui"
+import { HtmlEditor } from "@charcuterie/ui/html-editor"
+
+<Field label="Project notes">
+  <HtmlEditor key={record.id} defaultValue={record.notes} name="notes" />
+</Field>
+```
+
+The editor supports bold, italic, underline, lists, alignment, links, text colours, images and
+undo/redo. Keyboard shortcuts and document history come from Tiptap/ProseMirror; controls,
+overflow, dialogs and field wiring come from Charcuterie. Apps supply optional icons.
+
+<Canvas of={HtmlEditorStories.AllVariants} />
+
+## HTML is untrusted
+
+Initial content and rich clipboard HTML pass through the same HTML5 parser and closed
+document allowlist as `HtmlView`. Scripts, foreign namespaces, event handlers, arbitrary
+attributes and resource-loading CSS are removed. URL attributes use the shared link/image
+scheme guards. Colours and text alignment are the only retained inline CSS properties.
+This is a safe display/edit projection, not an automatic rewrite of the stored source.
+
+On the first real edit, unsupported markup is omitted from the edited HTML. Preserve the
+original field for an untouched save. This format is intended for document notes, not arbitrary
+web pages. Server-side authorization and storage validation remain the app's responsibility.
+
+<Canvas of={HtmlEditorStories.AllStates} />
+
+## Install only when used
+
+The subpath's optional peers are `parse5`, `@tiptap/core`, `@tiptap/react`, `@tiptap/pm`,
+`@tiptap/starter-kit`, `@tiptap/extension-image`, `@tiptap/extension-text-style` and
+`@tiptap/extension-text-align`. Importing the main UI entry loads none of them. A reader-only app uses `@charcuterie/ui/html-view`
+and installs only `parse5`.
+
+<Canvas of={HtmlEditorStories.Responsive} />
+<Canvas of={HtmlEditorStories.Interactive} />
+
+## Props
+
+<Controls />

package/src/htmlEditor/HtmlEditor.stories.tsx

@@ -0,0 +1,192 @@
+import { playgroundParameters } from "@charcuterie/storybook-config/story-parameters"
+import type { Meta, StoryObj } from "@storybook/react"
+import { useState } from "react"
+import { Button } from "../Button/Button.tsx"
+import {
+  ContainerBoard,
+  StoryCell,
+  StoryGrid,
+} from "../board.storyHelpers.tsx"
+import { Field } from "../Field/Field.tsx"
+import { HtmlEditor } from "./HtmlEditor.tsx"
+import { HtmlView } from "./HtmlView.tsx"
+import {
+  HOSTILE_HTML,
+  HTML_DOCUMENT,
+  ORIGINAL_HTML,
+} from "./htmlDocument.storyHelpers.ts"
+
+const meta = {
+  title: "Components/Controls/HtmlEditor",
+  component: HtmlEditor,
+  parameters: { layout: "padded" },
+  args: {
+    defaultValue: HTML_DOCUMENT,
+    label: "Notes",
+    isDisabled: false,
+    isReadOnly: false,
+  },
+  argTypes: { icons: { control: false } },
+} satisfies Meta<typeof HtmlEditor>
+export default meta
+type Story = StoryObj<typeof meta>
+
+export const Playground: Story = {
+  parameters: playgroundParameters,
+}
+export const AllVariants: Story = {
+  render: () => (
+    <StoryGrid columns={2}>
+      <StoryCell align="stretch" label="Existing rich HTML">
+        <HtmlEditor
+          defaultValue={HTML_DOCUMENT}
+          label="Rich notes"
+          toolbarLabel="Rich note formatting"
+        />
+      </StoryCell>
+      <StoryCell align="stretch" label="Inside a Field">
+        <Field
+          label="Recipe notes"
+          description="Stored as HTML; existing notes stay untouched until an edit."
+        >
+          <HtmlEditor
+            defaultValue="<p>Inspect the fit.</p>"
+            toolbarLabel="Recipe note formatting"
+          />
+        </Field>
+      </StoryCell>
+      <StoryCell align="stretch" label="Empty">
+        <HtmlEditor
+          label="Empty notes"
+          toolbarLabel="Empty note formatting"
+        />
+      </StoryCell>
+    </StoryGrid>
+  ),
+}
+export const AllStates: Story = {
+  render: () => (
+    <StoryGrid columns={2}>
+      <StoryCell align="stretch" label="Editing">
+        <HtmlEditor
+          defaultValue={HTML_DOCUMENT}
+          label="Editable notes"
+          toolbarLabel="Editable note formatting"
+        />
+      </StoryCell>
+      <StoryCell align="stretch" label="Read only">
+        <HtmlEditor
+          defaultValue={HTML_DOCUMENT}
+          isReadOnly
+          label="Read-only notes"
+          toolbarLabel="Read-only note formatting"
+        />
+      </StoryCell>
+      <StoryCell align="stretch" label="Disabled">
+        <HtmlEditor
+          defaultValue={HTML_DOCUMENT}
+          isDisabled
+          label="Disabled notes"
+          toolbarLabel="Disabled note formatting"
+        />
+      </StoryCell>
+      <StoryCell align="stretch" label="Invalid">
+        <Field
+          error="Add notes before saving."
+          isRequired
+          label="Required notes"
+        >
+          <HtmlEditor toolbarLabel="Required note formatting" />
+        </Field>
+      </StoryCell>
+    </StoryGrid>
+  ),
+}
+export const Responsive: Story = {
+  render: () => (
+    <ContainerBoard>
+      {(width) => (
+        <HtmlEditor
+          defaultValue={HTML_DOCUMENT}
+          label={`Notes at ${width}`}
+          toolbarLabel={`Formatting at ${width}`}
+        />
+      )}
+    </ContainerBoard>
+  ),
+}
+export const Interactive: Story = {
+  render: () => {
+    const [value, setValue] = useState(ORIGINAL_HTML)
+    const [defaultValue, setDefaultValue] =
+      useState(ORIGINAL_HTML)
+    const [changes, setChanges] = useState(0)
+    const [submitted, setSubmitted] = useState("")
+    return (
+      <div className="space-y-4">
+        <form
+          aria-label="Notes form"
+          className="space-y-4"
+          onSubmit={(event) => {
+            event.preventDefault()
+            setSubmitted(
+              String(
+                new FormData(event.currentTarget).get(
+                  "notes",
+                ),
+              ),
+            )
+          }}
+        >
+          <Field label="Saved notes">
+            <HtmlEditor
+              defaultValue={defaultValue}
+              name="notes"
+              onChange={(next) => {
+                setValue(next)
+                setChanges((count) => count + 1)
+              }}
+            />
+          </Field>
+          <div className="flex flex-wrap gap-2">
+            <Button type="submit">Save notes</Button>
+            <Button
+              appearance="outline"
+              onClick={() =>
+                setDefaultValue(
+                  "<p>External default changed</p>",
+                )
+              }
+            >
+              Change external default
+            </Button>
+          </div>
+        </form>
+        <p>Document edits: {changes}</p>
+        <section aria-label="Stored HTML">
+          <pre className="whitespace-pre-wrap wrap-anywhere">
+            {value}
+          </pre>
+        </section>
+        <section aria-label="Submitted HTML">
+          <pre className="whitespace-pre-wrap wrap-anywhere">
+            {submitted}
+          </pre>
+        </section>
+        <HtmlView
+          label="Saved note preview"
+          value={value}
+        />
+      </div>
+    )
+  },
+}
+export const Hostile: Story = {
+  args: {
+    defaultValue: HOSTILE_HTML,
+    label: "Untrusted notes",
+  },
+}
+export const Blank: Story = {
+  args: { defaultValue: "", label: "New notes" },
+}

package/src/htmlEditor/HtmlEditor.test.tsx

@@ -0,0 +1,308 @@
+import { composeStories } from "@storybook/react"
+import {
+  expect,
+  userEvent,
+  waitFor,
+  within,
+} from "storybook/test"
+import { test } from "vitest"
+import { userEvent as browserUserEvent } from "vitest/browser"
+
+import { expectNoAxeViolations } from "../expectNoAxeViolations.testHelpers.ts"
+import { mountStory } from "../mountStory.testHelpers.ts"
+import { expectAgentDrivable } from "../testing/index.ts"
+import * as stories from "./HtmlEditor.stories.tsx"
+import { ORIGINAL_HTML } from "./htmlDocument.storyHelpers.ts"
+
+const {
+  Playground,
+  Interactive,
+  AllStates,
+  Hostile,
+  Blank,
+  Responsive,
+} = composeStories(stories)
+
+const pressAction = async (
+  canvas: ReturnType<typeof within>,
+  body: ReturnType<typeof within>,
+  name: string,
+) => {
+  const action = canvas.queryByRole("button", { name })
+  if (action) {
+    await userEvent.click(action)
+    return
+  }
+  await userEvent.click(
+    canvas.getByRole("button", { name: "More actions" }),
+  )
+  await userEvent.click(body.getByRole("button", { name }))
+}
+
+test("formatting a selection emits rich HTML and announces the active format", async () => {
+  const { canvas, body } = await mountStory(Interactive)
+  const editor = await canvas.findByRole("textbox", {
+    name: "Saved notes",
+  })
+  await userEvent.click(editor)
+  await browserUserEvent.keyboard("{Control>}a{/Control}")
+  await pressAction(canvas, body, "Bold")
+  await expect(
+    editor.querySelector("strong"),
+  ).toHaveTextContent("Original & untouched")
+  await expect(
+    canvas.getByRole("button", { name: "Bold" }),
+  ).toHaveAttribute("aria-pressed", "true")
+  await expect(
+    canvas.getByLabelText("Stored HTML"),
+  ).toHaveTextContent("<strong>")
+})
+
+test("link dialog rejects script schemes; canceling does not edit the document", async () => {
+  const { canvas, body } = await mountStory(Interactive)
+  const editor = await canvas.findByRole("textbox", {
+    name: "Saved notes",
+  })
+  await userEvent.click(editor)
+  await browserUserEvent.keyboard("{Control>}a{/Control}")
+  await pressAction(canvas, body, "Edit link")
+  const dialog = body.getByRole("dialog", {
+    name: "Edit link",
+  })
+  const fields = within(dialog)
+  await waitFor(() =>
+    expect(
+      fields.getByRole("textbox", { name: "URL" }),
+    ).toHaveFocus(),
+  )
+  await userEvent.type(
+    fields.getByRole("textbox", { name: "URL" }),
+    "javascript:attack()",
+  )
+  await userEvent.click(
+    fields.getByRole("button", { name: "Apply" }),
+  )
+  await expect(
+    fields.getByText("Enter a safe link URL."),
+  ).toBeInTheDocument()
+  await expect(
+    canvas.getByLabelText("Submitted HTML").textContent,
+  ).toBe("")
+  await expectNoAxeViolations(dialog)
+  await userEvent.click(
+    fields.getByRole("button", { name: "Cancel" }),
+  )
+  await expect(
+    canvas.getByText("Document edits: 0"),
+  ).toBeInTheDocument()
+  await expect(
+    canvas.getByLabelText("Stored HTML"),
+  ).toHaveTextContent(ORIGINAL_HTML)
+})
+
+test("applying a safe relative link edits the draft without submitting its record form", async () => {
+  const { canvas, body } = await mountStory(Interactive)
+  const editor = await canvas.findByRole("textbox", {
+    name: "Saved notes",
+  })
+  await userEvent.click(editor)
+  await browserUserEvent.keyboard("{Control>}a{/Control}")
+  await pressAction(canvas, body, "Edit link")
+  const dialog = body.getByRole("dialog", {
+    name: "Edit link",
+  })
+  await userEvent.type(
+    within(dialog).getByRole("textbox", { name: "URL" }),
+    "/recipe",
+  )
+  await userEvent.click(
+    within(dialog).getByRole("button", { name: "Apply" }),
+  )
+  await expect(editor.querySelector("a")).toHaveAttribute(
+    "href",
+    "/recipe",
+  )
+  await expect(editor.querySelector("a")).toHaveTextContent(
+    "Original & untouched",
+  )
+  await expect(
+    canvas.getByLabelText("Submitted HTML").textContent,
+  ).toBe("")
+  await userEvent.click(
+    canvas.getByRole("button", { name: "Save notes" }),
+  )
+  await expect(
+    canvas.getByLabelText("Submitted HTML").textContent,
+  ).toBe(canvas.getByLabelText("Stored HTML").textContent)
+})
+
+test("the editor and shared toolbar are named controls with keyboard access", async () => {
+  const { canvas, canvasElement } =
+    await mountStory(Playground)
+  await waitFor(() =>
+    expectAgentDrivable(canvas, {
+      role: "textbox",
+      name: "Notes",
+    }),
+  )
+  expectAgentDrivable(canvas, {
+    role: "toolbar",
+    name: "HTML formatting",
+  })
+  await expect(
+    canvas.getByRole("textbox", { name: "Notes" }),
+  ).toHaveAttribute("aria-multiline", "true")
+  await expectNoAxeViolations(canvasElement)
+})
+
+test("mount, focus, selection, blur and an untouched form submission preserve exact original HTML", async () => {
+  const { canvas } = await mountStory(Interactive)
+  const editor = await canvas.findByRole("textbox", {
+    name: "Saved notes",
+  })
+  await userEvent.click(editor)
+  await userEvent.keyboard("{ArrowRight}{ArrowLeft}")
+  await userEvent.click(
+    canvas.getByRole("button", { name: "Save notes" }),
+  )
+  await expect(
+    canvas.getByLabelText("Stored HTML"),
+  ).toHaveTextContent(ORIGINAL_HTML)
+  await expect(
+    canvas.getByLabelText("Submitted HTML"),
+  ).toHaveTextContent(ORIGINAL_HTML)
+  await expect(
+    canvas.getByText("Document edits: 0"),
+  ).toBeInTheDocument()
+})
+
+test("external defaults never overwrite the document; real edits emit HTML and keep undo/redo", async () => {
+  const { canvas } = await mountStory(Interactive)
+  const editor = await canvas.findByRole("textbox", {
+    name: "Saved notes",
+  })
+  await userEvent.click(
+    canvas.getByRole("button", {
+      name: "Change external default",
+    }),
+  )
+  await expect(editor).toHaveTextContent(
+    "Original & untouched",
+  )
+  await expect(
+    canvas.getByText("Document edits: 0"),
+  ).toBeInTheDocument()
+  await userEvent.click(editor)
+  await browserUserEvent.keyboard(
+    "{Control>}{End}{/Control} plus",
+  )
+  await waitFor(() =>
+    expect(
+      canvas.getByLabelText("Stored HTML"),
+    ).toHaveTextContent("plus"),
+  )
+  await browserUserEvent.keyboard("{Control>}z{/Control}")
+  await expect(editor).not.toHaveTextContent("plus")
+  await browserUserEvent.keyboard(
+    "{Control>}{Shift>}z{/Shift}{/Control}",
+  )
+  await expect(editor).toHaveTextContent("plus")
+  await expect(
+    canvas.getByLabelText("Stored HTML"),
+  ).not.toHaveTextContent("data-old-format")
+})
+
+test("read-only and disabled editors refuse typing and formatting", async () => {
+  const { canvas } = await mountStory(AllStates)
+  const readOnly = await canvas.findByRole("textbox", {
+    name: "Read-only notes",
+  })
+  await expect(readOnly).toHaveAttribute(
+    "contenteditable",
+    "false",
+  )
+  await expect(readOnly).toHaveAttribute(
+    "aria-readonly",
+    "true",
+  )
+  const disabled = canvas.getByRole("textbox", {
+    name: "Disabled notes",
+  })
+  await expect(disabled).toHaveAttribute(
+    "aria-disabled",
+    "true",
+  )
+  await expect(disabled).toHaveAttribute("tabindex", "-1")
+  await expect(
+    within(
+      canvas.getByRole("toolbar", {
+        name: "Read-only note formatting",
+      }),
+    ).getByRole("button", { name: "Bold" }),
+  ).toBeDisabled()
+  const required = canvas.getByRole("textbox", {
+    name: "Required notes",
+  })
+  await expect(required).toHaveAttribute(
+    "aria-invalid",
+    "true",
+  )
+  await expect(required).toHaveAttribute(
+    "aria-required",
+    "true",
+  )
+})
+
+test("initial untrusted HTML is filtered before entering the editing DOM", async () => {
+  const { canvas } = await mountStory(Hostile)
+  const editor = await canvas.findByRole("textbox", {
+    name: "Untrusted notes",
+  })
+  await expect(editor).toHaveTextContent("Visible notes")
+  await expect(
+    editor.querySelector(
+      "script,style,iframe,svg,math,[onclick],[onerror],a[href],img",
+    ),
+  ).toBeNull()
+})
+
+test("rich clipboard HTML crosses the same safe policy before it becomes a document edit", async () => {
+  const { canvas } = await mountStory(Blank)
+  const editor = await canvas.findByRole("textbox", {
+    name: "New notes",
+  })
+  await userEvent.click(editor)
+  const data = new DataTransfer()
+  data.setData(
+    "text/html",
+    '<p onclick="attack()"><strong>Pasted</strong> notes<a href="java&#x09;script:attack()">unsafe</a></p><img src="javascript:attack()" onerror="attack()"><script>attack()</script>',
+  )
+  editor.dispatchEvent(
+    new ClipboardEvent("paste", {
+      bubbles: true,
+      cancelable: true,
+      clipboardData: data,
+    }),
+  )
+  await expect(editor).toHaveTextContent(
+    "Pasted notesunsafe",
+  )
+  await expect(
+    editor.querySelector("strong"),
+  ).toHaveTextContent("Pasted")
+  await expect(
+    editor.querySelector(
+      "script,img,[onclick],[onerror],a[href]",
+    ),
+  ).toBeNull()
+})
+
+test("a narrow container uses the shared toolbar overflow without page overflow", async () => {
+  const { canvas } = await mountStory(Responsive)
+  for (const editor of await canvas.findAllByRole(
+    "textbox",
+  ))
+    await expect(editor.scrollWidth).toBeLessThanOrEqual(
+      editor.clientWidth + 1,
+    )
+})