@charcuterie/ui 4.19.0 → 4.20.0

package/src/htmlEditor/HtmlEditor.tsx

@@ -0,0 +1,420 @@
+import { useUniqueId } from "@charcuterie/logic"
+import Image from "@tiptap/extension-image"
+import TextAlign from "@tiptap/extension-text-align"
+import {
+  Color,
+  TextStyle,
+} from "@tiptap/extension-text-style"
+import { EditorContent, useEditor } from "@tiptap/react"
+import StarterKit from "@tiptap/starter-kit"
+import type { ReactNode } from "react"
+import { useEffect, useRef, useState } from "react"
+
+import { Button } from "../Button/Button.tsx"
+import { Dialog } from "../Dialog/Dialog.tsx"
+import { Field } from "../Field/Field.tsx"
+import { FOCUS_RING_CLASS } from "../intentStyles.ts"
+import {
+  toSafeImageUrl,
+  toSafeLinkUrl,
+} from "../safeUrls.ts"
+import type { SlotProps } from "../slotProps.ts"
+import type { ToolbarItem } from "../Toolbar/Toolbar.tsx"
+import { Toolbar } from "../Toolbar/Toolbar.tsx"
+import { toClassName } from "../toClassName.ts"
+import { HTML_CONTENT_CLASS } from "./htmlContentStyles.ts"
+import { toSafeHtml, toSafeHtmlColour } from "./safeHtml.ts"
+
+export type HtmlEditorProps = SlotProps & {
+  className?: string
+  /** Initial only. Remount with a key to switch documents. */
+  defaultValue?: string
+  icons?: Readonly<Record<string, ReactNode>>
+  isDisabled?: boolean
+  isReadOnly?: boolean
+  /** Omit inside a Field, which supplies the real label. */
+  label?: string
+  /** Hidden form control; its original bytes survive until an edit. */
+  name?: string
+  onChange?: (value: string) => void
+  toolbarLabel?: string
+}
+
+const EDITOR_CLASS = toClassName(
+  HTML_CONTENT_CLASS,
+  "min-h-40 rounded-md border border-border-default bg-surface-sunken px-3 py-2",
+  FOCUS_RING_CLASS,
+)
+
+const INPUT_CLASS = toClassName(
+  "w-full min-w-0 rounded-md border border-border-default bg-surface-sunken p-2 text-content-primary",
+  FOCUS_RING_CLASS,
+)
+
+/**
+ * A rich editor for records already stored as HTML. Sanitization is
+ * a projection for display and editing, not a migration: mounting,
+ * selecting, focusing and submitting an untouched form never emit
+ * normalized HTML. ProseMirror owns document edits and their undo
+ * history; external defaults never replace that document.
+ */
+export const HtmlEditor = ({
+  className,
+  defaultValue = "",
+  icons,
+  isDisabled = false,
+  isReadOnly = false,
+  label,
+  name,
+  onChange,
+  toolbarLabel = "HTML formatting",
+  ...slotProps
+}: HtmlEditorProps): ReactNode => {
+  const generatedId = useUniqueId("html-editor")
+  const dialogInputRef = useRef<HTMLInputElement>(null)
+  const id = slotProps.id ?? generatedId
+  const [initialValue] = useState(defaultValue)
+  const [formValue, setFormValue] = useState(initialValue)
+  const [dialog, setDialog] = useState<
+    "link" | "image" | "colour" | null
+  >(null)
+  const [error, setError] = useState<string | undefined>()
+  const editor = useEditor(
+    {
+      content: toSafeHtml(initialValue),
+      editable: !isDisabled && !isReadOnly,
+      immediatelyRender: false,
+      shouldRerenderOnTransaction: true,
+      extensions: [
+        StarterKit.configure({
+          link: {
+            openOnClick: false,
+            autolink: false,
+            isAllowedUri: (url) =>
+              toSafeLinkUrl(url) !== undefined,
+          },
+        }),
+        Image.configure({ allowBase64: true }),
+        TextStyle,
+        Color,
+        TextAlign.configure({
+          types: ["heading", "paragraph"],
+          alignments: [
+            "start",
+            "end",
+            "left",
+            "right",
+            "center",
+            "justify",
+          ],
+        }),
+      ],
+      editorProps: {
+        attributes: {
+          id,
+          role: "textbox",
+          "aria-multiline": "true",
+          "aria-label": label ?? "",
+          "aria-labelledby":
+            label === undefined && slotProps.id
+              ? `${slotProps.id}-label`
+              : "",
+          "aria-describedby":
+            slotProps["aria-describedby"] ?? "",
+          "aria-invalid": String(
+            slotProps["aria-invalid"] ?? false,
+          ),
+          "aria-required": String(
+            slotProps["aria-required"] ??
+              slotProps.required ??
+              false,
+          ),
+          "aria-disabled": String(isDisabled),
+          "aria-readonly": String(isReadOnly),
+          tabindex: String(isDisabled ? -1 : 0),
+          class: EDITOR_CLASS,
+        },
+        transformPastedHTML: toSafeHtml,
+      },
+      onUpdate: ({
+        editor: changedEditor,
+        transaction,
+      }) => {
+        if (!transaction.docChanged) return
+        const next = toSafeHtml(changedEditor.getHTML())
+        setFormValue(next)
+        onChange?.(next)
+      },
+    },
+    [],
+  )
+
+  useEffect(() => {
+    editor?.setEditable(!isDisabled && !isReadOnly, false)
+  }, [editor, isDisabled, isReadOnly])
+
+  const hasDisabledActions =
+    isDisabled || isReadOnly || !editor
+  const openDialog = (
+    next: "link" | "image" | "colour",
+  ) => {
+    setError(undefined)
+    setDialog(next)
+  }
+  const toggle = (
+    key: string,
+    title: string,
+    onSelect: () => void,
+    isPressed: boolean,
+  ): ToolbarItem => ({
+    key,
+    type: "control",
+    element: (
+      <Button
+        appearance="ghost"
+        aria-pressed={isPressed}
+        iconStart={icons?.[key]}
+        isDisabled={hasDisabledActions}
+        onClick={onSelect}
+      >
+        {title}
+      </Button>
+    ),
+  })
+  const action = (
+    key: string,
+    title: string,
+    onSelect: () => void,
+  ): ToolbarItem => ({
+    key,
+    label: title,
+    icon: icons?.[key],
+    isDisabled: hasDisabledActions,
+    onSelect,
+  })
+  const closeDialog = () => setDialog(null)
+
+  return (
+    <div
+      className={toClassName(
+        "min-w-0 space-y-2",
+        className,
+      )}
+    >
+      <Toolbar
+        label={toolbarLabel}
+        overflow="panel"
+        overflowIcon={icons?.overflow}
+        items={[
+          toggle(
+            "bold",
+            "Bold",
+            () => {
+              editor?.chain().focus().toggleBold().run()
+            },
+            editor?.isActive("bold") ?? false,
+          ),
+          toggle(
+            "italic",
+            "Italic",
+            () => {
+              editor?.chain().focus().toggleItalic().run()
+            },
+            editor?.isActive("italic") ?? false,
+          ),
+          toggle(
+            "underline",
+            "Underline",
+            () => {
+              editor
+                ?.chain()
+                .focus()
+                .toggleUnderline()
+                .run()
+            },
+            editor?.isActive("underline") ?? false,
+          ),
+          toggle(
+            "bulletList",
+            "Bullet list",
+            () => {
+              editor
+                ?.chain()
+                .focus()
+                .toggleBulletList()
+                .run()
+            },
+            editor?.isActive("bulletList") ?? false,
+          ),
+          toggle(
+            "orderedList",
+            "Numbered list",
+            () => {
+              editor
+                ?.chain()
+                .focus()
+                .toggleOrderedList()
+                .run()
+            },
+            editor?.isActive("orderedList") ?? false,
+          ),
+          action("alignStart", "Align start", () => {
+            editor
+              ?.chain()
+              .focus()
+              .setTextAlign("start")
+              .run()
+          }),
+          action("alignCenter", "Align centre", () => {
+            editor
+              ?.chain()
+              .focus()
+              .setTextAlign("center")
+              .run()
+          }),
+          action("alignEnd", "Align end", () => {
+            editor
+              ?.chain()
+              .focus()
+              .setTextAlign("end")
+              .run()
+          }),
+          action("link", "Edit link", () =>
+            openDialog("link"),
+          ),
+          action("unlink", "Remove link", () => {
+            editor
+              ?.chain()
+              .focus()
+              .extendMarkRange("link")
+              .unsetLink()
+              .run()
+          }),
+          action("colour", "Text colour", () =>
+            openDialog("colour"),
+          ),
+          action("image", "Insert image", () =>
+            openDialog("image"),
+          ),
+          action("undo", "Undo", () => {
+            editor?.chain().focus().undo().run()
+          }),
+          action("redo", "Redo", () => {
+            editor?.chain().focus().redo().run()
+          }),
+        ]}
+      />
+      <EditorContent editor={editor} />
+      {name !== undefined && (
+        <input
+          disabled={isDisabled}
+          name={name}
+          type="hidden"
+          value={formValue}
+        />
+      )}
+      <Dialog
+        initialFocus={dialogInputRef}
+        heading={
+          dialog === "image"
+            ? "Insert image"
+            : dialog === "colour"
+              ? "Text colour"
+              : "Edit link"
+        }
+        isVisible={dialog !== null}
+        onClose={closeDialog}
+      >
+        <form
+          key={dialog}
+          className="space-y-4"
+          onSubmit={(event) => {
+            event.preventDefault()
+            if (!editor || hasDisabledActions) return
+            const data = new FormData(event.currentTarget)
+            const value = String(
+              data.get("value") ?? "",
+            ).trim()
+            if (dialog === "colour") {
+              const colour = toSafeHtmlColour(value)
+              if (!colour) {
+                setError(
+                  "Enter a colour name, hex, RGB or HSL value.",
+                )
+                return
+              }
+              editor.chain().focus().setColor(colour).run()
+            } else if (dialog === "image") {
+              const src = toSafeImageUrl(value)
+              if (!src) {
+                setError("Enter a safe image URL.")
+                return
+              }
+              editor
+                .chain()
+                .focus()
+                .setImage({
+                  src,
+                  alt: String(data.get("alt") ?? ""),
+                })
+                .run()
+            } else {
+              const href = toSafeLinkUrl(value)
+              if (!href) {
+                setError("Enter a safe link URL.")
+                return
+              }
+              editor
+                .chain()
+                .focus()
+                .extendMarkRange("link")
+                .setLink({ href })
+                .run()
+            }
+            closeDialog()
+          }}
+        >
+          <Field
+            error={error}
+            label={dialog === "colour" ? "Colour" : "URL"}
+            isRequired
+          >
+            <input
+              className={INPUT_CLASS}
+              defaultValue={
+                dialog === "link"
+                  ? String(
+                      editor?.getAttributes("link").href ??
+                        "",
+                    )
+                  : ""
+              }
+              name="value"
+              ref={dialogInputRef}
+              required
+            />
+          </Field>
+          {dialog === "image" && (
+            <Field label="Image description">
+              <input className={INPUT_CLASS} name="alt" />
+            </Field>
+          )}
+          <div className="flex flex-wrap gap-2">
+            <Button
+              isDisabled={hasDisabledActions}
+              type="submit"
+            >
+              Apply
+            </Button>
+            <Button
+              appearance="outline"
+              onClick={closeDialog}
+            >
+              Cancel
+            </Button>
+          </div>
+        </form>
+      </Dialog>
+    </div>
+  )
+}

package/src/htmlEditor/HtmlView.mdx

@@ -0,0 +1,37 @@
+import { Canvas, Controls, Meta } from "@storybook/addon-docs/blocks";
+import * as HtmlViewStories from "./HtmlView.stories";
+
+<Meta of={HtmlViewStories} />
+
+# HtmlView
+
+Read saved HTML notes with the same safe document policy and document styling as `HtmlEditor`.
+It renders React nodes, with no `innerHTML` and no editor instance. `value` is controlled because
+a reader has no caret or undo history to preserve. `label` names the document. Its `@charcuterie/ui/html-view` entry requires only the optional
+`parse5` peer and loads no editor core.
+
+<Canvas of={HtmlViewStories.Playground} />
+
+```tsx
+import { HtmlView } from "@charcuterie/ui/html-view"
+
+<HtmlView label="Project notes" value={record.notes} />
+```
+
+The parser decodes HTML entities before checking URL schemes. Only known document tags,
+safe links/images, accessible image text, list start numbers and safe colour/alignment styles
+reach the page. Scripts, embeds, event handlers, arbitrary classes/IDs, foreign namespaces and
+resource-loading CSS cannot reach the DOM. Unknown wrappers retain ordinary readable children;
+executable/foreign content is discarded. Safe links use the shared `TextLink` shape.
+
+Reading a note never writes its filtered projection back to storage. Plain HTML source remains
+available to its owner independently of this component; no conversion to markdown occurs.
+
+<Canvas of={HtmlViewStories.AllVariants} />
+<Canvas of={HtmlViewStories.AllStates} />
+<Canvas of={HtmlViewStories.Responsive} />
+<Canvas of={HtmlViewStories.Interactive} />
+
+## Props
+
+<Controls />

package/src/htmlEditor/HtmlView.stories.tsx

@@ -0,0 +1,119 @@
+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 { HtmlView } from "./HtmlView.tsx"
+import {
+  DOCUMENT_IMAGE,
+  HOSTILE_HTML,
+  HTML_DOCUMENT,
+} from "./htmlDocument.storyHelpers.ts"
+
+const meta = {
+  title: "Components/Data/HtmlView",
+  component: HtmlView,
+  parameters: { layout: "padded" },
+  args: { label: "Saved notes", value: HTML_DOCUMENT },
+} satisfies Meta<typeof HtmlView>
+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="Rich paragraphs and lists"
+      >
+        <HtmlView
+          label="Rich notes"
+          value={HTML_DOCUMENT}
+        />
+      </StoryCell>
+      <StoryCell align="stretch" label="Safe image">
+        <HtmlView
+          label="Illustrated notes"
+          value={`<p>Mounting fixture</p><img src="${DOCUMENT_IMAGE}" alt="Fixture illustration">`}
+        />
+      </StoryCell>
+      <StoryCell align="stretch" label="Relative link">
+        <HtmlView
+          label="Linked notes"
+          value='<p>Read <a href="./instructions">the instructions</a>.</p>'
+        />
+      </StoryCell>
+      <StoryCell
+        align="stretch"
+        label="Code and line breaks"
+      >
+        <HtmlView
+          label="Technical notes"
+          value="<p>Inspect<br>then assemble.</p><pre><code>width = 24 &lt; 32</code></pre>"
+        />
+      </StoryCell>
+    </StoryGrid>
+  ),
+}
+export const AllStates: Story = {
+  render: () => (
+    <StoryGrid columns={2}>
+      <StoryCell align="stretch" label="Saved">
+        <HtmlView
+          label="Saved document"
+          value={HTML_DOCUMENT}
+        />
+      </StoryCell>
+      <StoryCell align="stretch" label="Empty">
+        <HtmlView label="Empty document" value="" />
+      </StoryCell>
+      <StoryCell
+        align="stretch"
+        label="Untrusted HTML is filtered"
+      >
+        <HtmlView
+          label="Filtered document"
+          value={HOSTILE_HTML}
+        />
+      </StoryCell>
+    </StoryGrid>
+  ),
+}
+export const Responsive: Story = {
+  render: () => (
+    <ContainerBoard>
+      {(width) => (
+        <HtmlView
+          label={`Notes at ${width}`}
+          value={`${HTML_DOCUMENT}<p>https://example.invalid/an-extremely-long-source-path-with-no-spaces-in-the-identifier-for-a-recipe-revision</p>`}
+        />
+      )}
+    </ContainerBoard>
+  ),
+}
+export const Interactive: Story = {
+  render: () => {
+    const [value, setValue] = useState(HTML_DOCUMENT)
+    return (
+      <div className="space-y-4">
+        <Button
+          onClick={() =>
+            setValue(
+              "<p>Updated <strong>saved notes</strong>.</p>",
+            )
+          }
+        >
+          Show next revision
+        </Button>
+        <HtmlView label="Current revision" value={value} />
+      </div>
+    )
+  },
+}

package/src/htmlEditor/HtmlView.test.tsx

@@ -0,0 +1,88 @@
+import { composeStories } from "@storybook/react"
+import { expect, userEvent } from "storybook/test"
+import { test } from "vitest"
+
+import { mountStory } from "../mountStory.testHelpers.ts"
+import { expectAgentDrivable } from "../testing/index.ts"
+import * as stories from "./HtmlView.stories.tsx"
+
+const {
+  Playground,
+  AllVariants,
+  AllStates,
+  Interactive,
+  Responsive,
+} = composeStories(stories)
+
+test("the named document renders paragraphs, lists and safe links without an editing surface", async () => {
+  const { canvas, canvasElement } =
+    await mountStory(Playground)
+  expectAgentDrivable(canvas, {
+    role: "document",
+    name: "Saved notes",
+  })
+  await expect(
+    canvas.getByRole("link", { name: "Read the recipe" }),
+  ).toHaveAttribute(
+    "href",
+    "https://example.invalid/recipe",
+  )
+  await expect(
+    canvas.queryByRole("textbox"),
+  ).not.toBeInTheDocument()
+  await expect(
+    canvasElement.querySelectorAll("li"),
+  ).toHaveLength(4)
+})
+
+test("hostile HTML has visible ordinary content and no executable DOM, source props or unsafe URL", async () => {
+  const { canvas } = await mountStory(AllStates)
+  const document = canvas.getByRole("document", {
+    name: "Filtered document",
+  })
+  await expect(document).toHaveTextContent("Visible notes")
+  await expect(
+    document.querySelector(
+      "script,style,iframe,svg,math,[onclick],[onerror],[srcset]",
+    ),
+  ).toBeNull()
+  await expect(
+    document.querySelector("a[href],img"),
+  ).toBeNull()
+  await expect(document).not.toHaveTextContent(
+    "Foreign content",
+  )
+})
+
+test("images retain their description and relative links retain ordinary navigation", async () => {
+  const { canvas } = await mountStory(AllVariants)
+  expectAgentDrivable(canvas, {
+    role: "img",
+    name: "Fixture illustration",
+  })
+  await expect(
+    canvas.getByRole("link", { name: "the instructions" }),
+  ).toHaveAttribute("href", "./instructions")
+})
+
+test("a controlled reader reflects the next saved revision", async () => {
+  const { canvas } = await mountStory(Interactive)
+  await userEvent.click(
+    canvas.getByRole("button", {
+      name: "Show next revision",
+    }),
+  )
+  await expect(
+    canvas.getByRole("document", {
+      name: "Current revision",
+    }),
+  ).toHaveTextContent("Updated saved notes.")
+})
+
+test("long document paths stay inside each container", async () => {
+  const { canvas } = await mountStory(Responsive)
+  for (const document of canvas.getAllByRole("document"))
+    await expect(document.scrollWidth).toBeLessThanOrEqual(
+      document.clientWidth + 1,
+    )
+})