@charcuterie/ui 4.18.3 → 4.20.0

package/src/htmlEditor/HtmlView.tsx

@@ -0,0 +1,71 @@
+import type { CSSProperties, ReactNode } from "react"
+import { createElement } from "react"
+
+import { TextLink } from "../TextLink/TextLink.tsx"
+import { toClassName } from "../toClassName.ts"
+import { HTML_CONTENT_CLASS } from "./htmlContentStyles.ts"
+import type { HtmlContentNode } from "./safeHtml.ts"
+import { toHtmlContent } from "./safeHtml.ts"
+
+export type HtmlViewProps = {
+  className?: string
+  /** The readable document's accessible name. */
+  label: string
+  value: string
+}
+
+const toStyle = (
+  value: string | undefined,
+): CSSProperties =>
+  Object.fromEntries(
+    (value ?? "")
+      .split(";")
+      .filter(Boolean)
+      .map((declaration) => {
+        const [name, content] = declaration.split(":")
+        return [
+          name === "text-align" ? "textAlign" : name,
+          content,
+        ]
+      }),
+  )
+
+const renderNode = (
+  node: HtmlContentNode,
+  key: number,
+): ReactNode => {
+  if ("text" in node) return node.text
+  const { style, ...attributes } = node.attributes
+  const children = node.children.map(renderNode)
+  if (node.tag === "a" && attributes.href !== undefined)
+    return (
+      <TextLink
+        href={attributes.href}
+        key={key}
+        style={toStyle(style)}
+        title={attributes.title}
+      >
+        {children}
+      </TextLink>
+    )
+  return createElement(
+    node.tag,
+    { ...attributes, key, style: toStyle(style) },
+    children.length ? children : undefined,
+  )
+}
+
+/** HTML is a distinct stored format. No editor and no innerHTML. */
+export const HtmlView = ({
+  className,
+  label,
+  value,
+}: HtmlViewProps): ReactNode => (
+  <div
+    aria-label={label}
+    className={toClassName(HTML_CONTENT_CLASS, className)}
+    role="document"
+  >
+    {toHtmlContent(value).map(renderNode)}
+  </div>
+)

package/src/htmlEditor/htmlContentStyles.ts

@@ -0,0 +1,3 @@
+/** Identical document paint in the reader and the editing surface. */
+export const HTML_CONTENT_CLASS =
+  "min-w-0 wrap-anywhere text-content-primary [&_p]:my-2 [&_div]:my-2 [&_ul]:my-2 [&_ul]:list-disc [&_ul]:ps-6 [&_ol]:my-2 [&_ol]:list-decimal [&_ol]:ps-6 [&_li]:my-1 [&_blockquote]:my-3 [&_blockquote]:border-s-2 [&_blockquote]:border-border-default [&_blockquote]:ps-4 [&_blockquote]:text-content-secondary [&_pre]:whitespace-pre-wrap [&_pre]:rounded-md [&_pre]:bg-surface-raised [&_pre]:p-3 [&_code]:font-mono [&_h1]:my-3 [&_h1]:text-2xl [&_h1]:font-bold [&_h2]:my-3 [&_h2]:text-xl [&_h2]:font-bold [&_h3]:my-3 [&_h3]:text-lg [&_h3]:font-bold [&_h4]:my-2 [&_h4]:font-semibold [&_h5]:my-2 [&_h5]:font-semibold [&_h6]:my-2 [&_h6]:font-semibold [&_a]:text-intent-accent-content [&_a]:underline [&_img]:max-w-full [&_img]:h-auto [&_img]:rounded-md [&_hr]:my-3 [&_hr]:border-border-default"

package/src/htmlEditor/htmlDocument.storyHelpers.ts

@@ -0,0 +1,7 @@
+export const HTML_DOCUMENT = `<p><strong>Workshop fixture</strong> &amp; setup notes.</p><p>Keep the <em>revision</em> and <u>material</u> together.</p><ul><li>Inspect the mounting holes.</li><li>Store the source file.</li></ul><ol start="3"><li>Build a fresh output.</li><li>Record the result.</li></ol><p style="text-align:center"><a href="https://example.invalid/recipe">Read the recipe</a></p><blockquote><p>Keep a traceable print recipe.</p></blockquote>`
+
+export const ORIGINAL_HTML = `<DIV data-old-format='retained'><p class='legacy'>Original &amp; untouched</p></DIV>`
+
+export const HOSTILE_HTML = `<p onclick="alert(1)">Visible notes</p><script>alert(1)</script><style>body{display:none}</style><iframe src="https://example.invalid/embed"></iframe><a href="java&#x73;cript:alert(1)">Unsafe link</a><img src="data:text/html,attack" onerror="alert(1)"><span style="color:currentcolor;background:url(https://example.invalid/tracker);position:fixed">Only safe text styling</span><svg><a href="javascript:alert(1)">Foreign content</a></svg>`
+
+export const DOCUMENT_IMAGE = `data:image/svg+xml,${encodeURIComponent('<svg xmlns="http://www.w3.org/2000/svg" width="240" height="80"><rect width="240" height="80" rx="8" fill="steelblue"/><circle cx="120" cy="40" r="24" fill="white"/></svg>')}`

package/src/htmlEditor/index.ts

@@ -0,0 +1,7 @@
+/** Opt-in rich HTML surfaces; no HTML conversion in markdown components. */
+export type { HtmlEditorProps } from "./HtmlEditor.tsx"
+export { HtmlEditor } from "./HtmlEditor.tsx"
+export type { HtmlViewProps } from "./HtmlView.tsx"
+export { HtmlView } from "./HtmlView.tsx"
+export type { HtmlContentNode } from "./safeHtml.ts"
+export { toHtmlContent, toSafeHtml } from "./safeHtml.ts"

package/src/htmlEditor/safeHtml.test.ts

@@ -0,0 +1,123 @@
+import { createElement } from "react"
+import { renderToStaticMarkup } from "react-dom/server"
+import { expect, test } from "vitest"
+
+import { HtmlView } from "./HtmlView.tsx"
+
+import {
+  toHtmlContent,
+  toSafeHtml,
+  toSafeHtmlColour,
+} from "./safeHtml.ts"
+
+test("the reader renders safe HTML on the server without a DOM or editor runtime", () => {
+  expect(typeof window).toBe("undefined")
+  const html = renderToStaticMarkup(
+    createElement(HtmlView, {
+      label: "Server notes",
+      value:
+        '<p onclick="attack()">Stored &amp; safe</p><script>attack()</script><a href="javascript:attack()">Read</a>',
+    }),
+  )
+  expect(html).toContain("Stored &amp; safe")
+  expect(html).toContain('role="document"')
+  expect(html).not.toMatch(
+    /onclick|<script|href="javascript/,
+  )
+})
+
+test("keeps readable formatting while removing executable HTML and arbitrary source props", () => {
+  expect(
+    toSafeHtml(
+      '<div id="clobber" class="overlay"><p onclick="attack()"><strong>Keep</strong> &amp; read.</p><script>attack()</script><style>body{display:none}</style><iframe src="/embed">hidden</iframe><svg><text>hidden</text></svg><math><mtext>hidden</mtext></math></div>',
+    ),
+  ).toBe(
+    "<div><p><strong>Keep</strong> &amp; read.</p></div>",
+  )
+})
+
+test.each([
+  "javascript:attack()",
+  "java&#x73;cript:attack()",
+  "JaVa&#x09;Script:attack()",
+  "data:text/html,attack",
+  "file:///private",
+  "vbscript:attack()",
+])(
+  "decodes and rejects an unsafe link scheme: %s",
+  (href) => {
+    expect(
+      toSafeHtml(
+        `<a href="${href}" target="_blank" onclick="attack()">Read</a>`,
+      ),
+    ).toBe('<a rel="noopener noreferrer">Read</a>')
+  },
+)
+
+test.each([
+  "https://example.invalid/notes",
+  "/notes",
+  "./notes",
+  "#section",
+  "mailto:help@example.invalid",
+  "tel:1234",
+])("keeps a permitted link: %s", (href) => {
+  expect(toSafeHtml(`<a href="${href}">Read</a>`)).toBe(
+    `<a href="${href}" rel="noopener noreferrer">Read</a>`,
+  )
+})
+
+test("image attributes are closed and rejected image sources disappear", () => {
+  expect(
+    toSafeHtml(
+      '<img src="/photo.png" alt="A &amp; B" onerror="attack()" srcset="/tracker 2x" width="999999"><img src="javascript:attack()"><img src="data:text/html,attack"><img src="">',
+    ),
+  ).toBe('<img src="/photo.png" alt="A &amp; B">')
+})
+
+test("retains only document colour and alignment; CSS cannot load resources or escape the surface", () => {
+  expect(
+    toSafeHtml(
+      '<p style="position:fixed;inset:0;background:url(/tracker);color:rgb(20, 30, 40);text-align:center;font-size:9999px">Notes</p>',
+    ),
+  ).toBe(
+    '<p style="color:rgb(20, 30, 40);text-align:center">Notes</p>',
+  )
+  expect(
+    toSafeHtml(
+      '<span style="color:expression(attack());background-image:url(/tracker)">Notes</span>',
+    ),
+  ).toBe("<span>Notes</span>")
+  expect(
+    toSafeHtmlColour("red;position:fixed"),
+  ).toBeUndefined()
+  expect(toSafeHtmlColour("url(/tracker)")).toBeUndefined()
+})
+
+test("an HTML5 parse, rather than regex replacement, contains malformed foreign content", () => {
+  const safe = toSafeHtml(
+    '<math><mtext><table><mglyph><style><!--</style><img title="--><img src=x onerror=attack()>">',
+  )
+  expect(safe).not.toMatch(/onerror|<math|<style|<mglyph/)
+  expect(toSafeHtml(safe)).toBe(safe)
+})
+
+test("text entities and repeated sanitization retain visible meaning without writing back to the input", () => {
+  const original =
+    "<P class='old'>5 &lt; 6 &amp; \"quoted\"</P>"
+  const safe = toSafeHtml(original)
+  expect(safe).toBe(
+    "<p>5 &lt; 6 &amp; &quot;quoted&quot;</p>",
+  )
+  expect(toSafeHtml(safe)).toBe(safe)
+  expect(toHtmlContent(original)).toEqual([
+    {
+      tag: "p",
+      attributes: {},
+      children: [{ text: '5 < 6 & "quoted"' }],
+    },
+  ])
+  expect(original).toBe(
+    "<P class='old'>5 &lt; 6 &amp; \"quoted\"</P>",
+  )
+})

package/src/htmlEditor/safeHtml.ts

@@ -0,0 +1,187 @@
+import type { DefaultTreeAdapterMap } from "parse5"
+import { parseFragment } from "parse5"
+
+import {
+  toSafeImageUrl,
+  toSafeLinkUrl,
+} from "../safeUrls.ts"
+
+export type HtmlContentNode =
+  | { text: string }
+  | {
+      attributes: Record<string, string>
+      children: HtmlContentNode[]
+      tag: string
+    }
+
+// One format policy for rendering, initial editor content, paste,
+// and serialized edits. Parsing HTML5 before filtering also decodes
+// character references in URLs; an encoded scheme cannot evade the
+// shared URL guard. Nothing from the source becomes a React prop.
+const TAGS = new Set([
+  "p",
+  "div",
+  "br",
+  "strong",
+  "b",
+  "em",
+  "i",
+  "u",
+  "s",
+  "strike",
+  "span",
+  "a",
+  "img",
+  "ul",
+  "ol",
+  "li",
+  "blockquote",
+  "h1",
+  "h2",
+  "h3",
+  "h4",
+  "h5",
+  "h6",
+  "pre",
+  "code",
+  "hr",
+])
+const DROP_CONTENT = new Set([
+  "script",
+  "style",
+  "template",
+  "iframe",
+  "object",
+  "embed",
+  "svg",
+  "math",
+  "noscript",
+])
+const VOID_TAGS = new Set(["br", "hr", "img"])
+
+export const toSafeHtmlColour = (
+  value: string,
+): string | undefined => {
+  const colour = value.trim().toLowerCase()
+  return /^(#[\da-f]{3}|#[\da-f]{4}|#[\da-f]{6}|#[\da-f]{8}|[a-z]+|(?:rgb|rgba|hsl|hsla)\([\d.,%\s+-]+\))$/.test(
+    colour,
+  )
+    ? colour
+    : undefined
+}
+
+const toSafeStyle = (value: string): string =>
+  value
+    .split(";")
+    .flatMap((declaration) => {
+      const [rawName, ...parts] = declaration.split(":")
+      const name = rawName?.trim().toLowerCase()
+      const content = parts.join(":").trim().toLowerCase()
+
+      if (
+        name === "text-align" &&
+        /^(start|end|left|right|center|justify)$/.test(
+          content,
+        )
+      ) {
+        return [`text-align:${content}`]
+      }
+      if (
+        name === "color" &&
+        toSafeHtmlColour(content) !== undefined
+      ) {
+        return [`color:${content}`]
+      }
+      return []
+    })
+    .join(";")
+
+const toSafeAttributes = (
+  tag: string,
+  attributes: DefaultTreeAdapterMap["element"]["attrs"],
+): Record<string, string> => {
+  const source = Object.fromEntries(
+    attributes
+      .filter((attribute) => !attribute.namespace)
+      .map(({ name, value }) => [name, value]),
+  )
+  const result: Record<string, string> = {}
+  const style = toSafeStyle(source.style ?? "")
+  if (style !== "") result.style = style
+
+  if (tag === "a") {
+    const href = toSafeLinkUrl(source.href ?? "")
+    if (source.href !== undefined && href !== undefined)
+      result.href = href
+    if (source.title) result.title = source.title
+    // Source target/rel attributes never reach the page.
+    result.rel = "noopener noreferrer"
+  }
+  if (tag === "img") {
+    const src = toSafeImageUrl(source.src ?? "")
+    if (src) result.src = src
+    result.alt = source.alt ?? ""
+    if (source.title) result.title = source.title
+  }
+  if (tag === "ol" && /^\d{1,6}$/.test(source.start ?? ""))
+    result.start = source.start ?? "1"
+  return result
+}
+
+const toSafeNodes = (
+  nodes: DefaultTreeAdapterMap["childNode"][],
+): HtmlContentNode[] =>
+  nodes.flatMap((node): HtmlContentNode[] => {
+    if (node.nodeName === "#text" && "value" in node)
+      return [{ text: node.value }]
+    if (!("tagName" in node)) return []
+    if (
+      DROP_CONTENT.has(node.tagName) ||
+      node.namespaceURI !== "http://www.w3.org/1999/xhtml"
+    )
+      return []
+    const children = toSafeNodes(node.childNodes)
+    if (!TAGS.has(node.tagName)) return children
+    const attributes = toSafeAttributes(
+      node.tagName,
+      node.attrs,
+    )
+    // A rejected image is absent, rather than a broken image or an
+    // empty src that makes another request for the document itself.
+    if (node.tagName === "img" && !attributes.src) return []
+    return [{ attributes, children, tag: node.tagName }]
+  })
+
+export const toHtmlContent = (
+  value: string,
+): HtmlContentNode[] =>
+  toSafeNodes(parseFragment(value).childNodes)
+
+const escapeHtml = (value: string) =>
+  value.replace(
+    /[&<>"]/g,
+    (character) =>
+      ({
+        "&": "&amp;",
+        "<": "&lt;",
+        ">": "&gt;",
+        '"': "&quot;",
+      })[character] ?? character,
+  )
+
+const serialize = (node: HtmlContentNode): string => {
+  if ("text" in node) return escapeHtml(node.text)
+  const attributes = Object.entries(node.attributes)
+    .map(
+      ([name, value]) => ` ${name}="${escapeHtml(value)}"`,
+    )
+    .join("")
+  const start = `<${node.tag}${attributes}>`
+  return VOID_TAGS.has(node.tag)
+    ? start
+    : `${start}${node.children.map(serialize).join("")}</${node.tag}>`
+}
+
+/** A display/edit projection, never an instruction to rewrite stored HTML. */
+export const toSafeHtml = (value: string): string =>
+  toHtmlContent(value).map(serialize).join("")

package/src/htmlEditor/view.ts

@@ -0,0 +1,5 @@
+/** Read HTML without importing or installing the rich editor core. */
+export type { HtmlViewProps } from "./HtmlView.tsx"
+export { HtmlView } from "./HtmlView.tsx"
+export type { HtmlContentNode } from "./safeHtml.ts"
+export { toHtmlContent, toSafeHtml } from "./safeHtml.ts"

package/src/index.ts

@@ -158,6 +158,7 @@ export {
 export type {
   DataTableColumn,
   DataTableProps,
+  DataTableReflowAt,
   DataTableSelection,
   DataTableSort,
 } from "./DataTable/DataTable.tsx"
@@ -316,6 +317,8 @@ export type {
   MenuProps,
 } from "./Menu/Menu.tsx"
 export { Menu } from "./Menu/Menu.tsx"
+export type { MetricCardProps } from "./MetricCard/MetricCard.tsx"
+export { MetricCard } from "./MetricCard/MetricCard.tsx"
 export type { ModalProps } from "./Modal/Modal.tsx"
 export { Modal } from "./Modal/Modal.tsx"
 export type {

package/src/markdownEditorCodeMirror/MarkdownView.test.tsx

@@ -367,10 +367,14 @@ test.each([
   async (_case, name) => {
     const { canvas } = await mountStory(NestedLinkText)
 
-    const link = expectAgentDrivable(canvas, {
-      name,
-      role: "link",
-    })
+    // CodeMirror finishes its viewport decorations on a scheduled frame.
+    // Wait for the accessible anchor rather than assuming mount means paint.
+    const link = await waitFor(() =>
+      expectAgentDrivable(canvas, {
+        name,
+        role: "link",
+      }),
+    )
 
     await expect(link.tagName).toBe("A")
   },

package/src/sourceRules.test.ts

@@ -621,7 +621,8 @@ test("the barrel is the only place components are re-exported", async () => {
   // ValuePairs owns compact label-over-value summaries.
   // Chart shares portable SVG geometry with Preact and image consumers.
   // TableViewport owns readable comparisons and full-window expansion.
-  expect(componentNames.length).toBe(74)
+  // MetricCard shares prominent values and category-coloured icons through Card.
+  expect(componentNames.length).toBe(75)
 
   for (const name of componentNames) {
     expect(barrel).toContain(`export { ${name} }`)
@@ -781,6 +782,28 @@ const ENTRY_POINT_RUNTIMES: Record<
       // silently, which is how it shipped broken in three repos.
       "tailwind-merge",
     ],
+    // Retained HTML has its own format family and optional rich editor
+    // peers. The main entry never reaches this parser or editor core.
+    "./html-view": [
+      "@charcuterie/tokens",
+      "parse5",
+      "react",
+      "tailwind-merge",
+    ],
+    "./html-editor": [
+      "@charcuterie/logic",
+      "@charcuterie/logic/browser",
+      "@charcuterie/tokens",
+      "@floating-ui/react",
+      "@tiptap/extension-image",
+      "@tiptap/extension-text-align",
+      "@tiptap/extension-text-style",
+      "@tiptap/react",
+      "@tiptap/starter-kit",
+      "parse5",
+      "react",
+      "tailwind-merge",
+    ],
     // The opt-in live-preview editor. Every `@codemirror/*` and
     // `@lezer/*` package appears **only** here, as an optional peer,
     // which is the entire reason it is a subpath: measured at ~176 KB

package/src/styles.css

@@ -260,3 +260,49 @@
   th:first-child {
   z-index: 3;
 }
+
+/* Column width utilities describe comparison columns, never labelled list cells.
+   These rules are unlayered, like the component's existing structural styles,
+   so a consumer's cq-lg:w-32 cannot crush a list reflowing at cq-xl. */
+.charcuterie-data-table[data-layout="stacked"]
+  > table
+  > :is(thead, tbody)
+  > tr
+  > :is(th, td) {
+  inline-size: auto;
+  min-inline-size: 0;
+  max-inline-size: none;
+}
+@container (width < 32rem) {
+  .charcuterie-data-table[data-reflow-at="md"]
+    > table
+    > :is(thead, tbody)
+    > tr
+    > :is(th, td) {
+    inline-size: auto;
+    min-inline-size: 0;
+    max-inline-size: none;
+  }
+}
+@container (width < 48rem) {
+  .charcuterie-data-table[data-reflow-at="lg"]
+    > table
+    > :is(thead, tbody)
+    > tr
+    > :is(th, td) {
+    inline-size: auto;
+    min-inline-size: 0;
+    max-inline-size: none;
+  }
+}
+@container (width < 64rem) {
+  .charcuterie-data-table[data-reflow-at="xl"]
+    > table
+    > :is(thead, tbody)
+    > tr
+    > :is(th, td) {
+    inline-size: auto;
+    min-inline-size: 0;
+    max-inline-size: none;
+  }
+}