@heyramzi/ui 1.54.1 → 2.0.0

package/src/components/toolbar/toolbar.test.ts

@@ -0,0 +1,66 @@
+import { mount, tick, unmount } from "svelte";
+import { afterEach, describe, expect, it } from "vite-plus/test";
+import { List, SquaresFour } from "phosphor-svelte";
+import Toolbar from "./toolbar.svelte";
+
+const tabs = [
+  { value: "all", label: "All", count: 12 },
+  { value: "open", label: "Open", count: 4 },
+];
+const views = [
+  { value: "list", label: "List", icon: List },
+  { value: "grid", label: "Grid", icon: SquaresFour },
+];
+
+let target: HTMLElement;
+let app: Record<string, unknown> | undefined;
+
+function render(props: Record<string, unknown>) {
+  target = document.createElement("div");
+  document.body.append(target);
+  app = mount(Toolbar, { target, props }) as Record<string, unknown>;
+  return target;
+}
+
+afterEach(() => {
+  if (app) void unmount(app);
+  target?.remove();
+  app = undefined;
+});
+
+describe("Toolbar", () => {
+  it("is one row that never wraps", () => {
+    const root = render({ search: "", tabs, tab: "all", views, view: "list" });
+    const row = root.querySelector(".flex");
+    expect(row?.classList.contains("flex-nowrap")).toBe(true);
+    expect(row?.classList.contains("flex-wrap")).toBe(false);
+  });
+
+  it("draws search, tabs and view twice, one for each width, and queries pick one", () => {
+    const root = render({ search: "", tabs, tab: "all", views, view: "list" });
+    const wide = root.querySelectorAll(".\\@max-2xl\\/toolbar\\:hidden");
+    const narrow = root.querySelectorAll(".\\@2xl\\/toolbar\\:hidden");
+    expect(wide.length).toBe(3);
+    expect(narrow.length).toBe(3);
+  });
+
+  it("names the narrow controls so a screen reader can find them", () => {
+    const root = render({ search: "", tabs, tab: "all", views, view: "list", searchLabel: "Find", tabsLabel: "Status", viewLabel: "Layout" });
+    for (const label of ["Find", "Status", "Layout"]) {
+      expect(root.querySelector(`button[aria-label="${label}"]`), label).not.toBeNull();
+    }
+  });
+
+  it("shows the current tab on the narrow menu trigger", async () => {
+    const root = render({ search: "", tabs, tab: "open", views, view: "list" });
+    await tick();
+    expect(root.querySelector('button[aria-label="Show"]')?.textContent?.trim()).toBe("Open");
+  });
+
+  it("leaves out what it isn't given", () => {
+    const root = render({ tabs, tab: "all" });
+    expect(root.querySelector('button[aria-label="Search"]')).toBeNull();
+    expect(root.querySelector('button[aria-label="View"]')).toBeNull();
+    expect(root.querySelector('button[aria-label="Show"]')).not.toBeNull();
+  });
+});

package/src/editor/README.md

@@ -0,0 +1,58 @@
+# @heyramzi/ui/editor
+
+A Svelte 5 rich text editor on [Tiptap](https://tiptap.dev): headings, lists, tables, images, YouTube links, a slash menu, an image toolbar and optional block ids. It saves Tiptap JSON, and a renderer turns that JSON back into HTML on the server, so a crawler sees the body.
+
+Tiptap is a dependency of `@heyramzi/ui`, and a bundler only ships it when you import this subpath.
+
+## Install
+
+```
+pnpm add @heyramzi/ui
+```
+
+`svelte` (5.57 or newer) is a peer. The editor's toolbar uses the kit's `Button` and `Input`, so import the kit's `tokens.css` once and point Tailwind at the package:
+
+```css
+@import "tailwindcss";
+@import "@heyramzi/ui/tokens.css";
+
+@source "../node_modules/@heyramzi/ui";
+```
+
+## Usage
+
+```svelte
+<script lang="ts">
+  import { RichEditor, RichRenderer } from "@heyramzi/ui/editor";
+
+  let doc = $state<Record<string, unknown> | null>(null);
+</script>
+
+<RichEditor content={doc} onchange={(json) => (doc = json)} preset="full" />
+
+<RichRenderer content={doc} />
+```
+
+## What is inside
+
+| Export | What it is |
+| --- | --- |
+| `RichEditor` | The editor. `preset` is `full` or `notes`, `blockIds` stamps a stable id on each block |
+| `RichRenderer` | Renders saved JSON to HTML, on the server too, with a click-to-load YouTube facade |
+| `renderTiptapContent`, `extractHeadings`, `extractYoutubeVideos` | The serializer, for a table of contents or a sitemap |
+| `BlockIdExtension`, `generateBlockId` | The block id extension |
+| `@heyramzi/ui/editor/markdown` | `tiptapToMarkdown` and `markdownToTiptap`. It pulls in markdown-it, so it isn't in the root export |
+| `@heyramzi/ui/editor/block-ops` | Edit a document by block id: replace, insert, delete |
+| `@heyramzi/ui/editor/inline-editor` | A single-block editor for one field |
+| `@heyramzi/ui/editor/content.css` | The typography for editor and renderer. Both import it already |
+
+## Comparison tables
+
+A table whose first row has a `Winner` (or `Gagnant`, `Vainqueur`) header gets a `comparison-table` class, and each cell in that column becomes a pill with `data-winner` set to the first word of the cell, lowercased. `tie` and `other` are styled for you. Colour one product from your own CSS:
+
+```css
+.tiptap-content table.comparison-table .winner-cell[data-winner="acme"] p {
+  background: color-mix(in srgb, var(--color-signal) 14%, transparent);
+  color: var(--color-signal);
+}
+```

package/src/editor/ambient.d.ts

@@ -0,0 +1 @@
+declare module "*.css";

package/src/editor/block-id.ts

@@ -0,0 +1,77 @@
+import { Extension } from "@tiptap/core";
+import type { Node as ProseMirrorNode } from "@tiptap/pm/model";
+import { Plugin, PluginKey } from "@tiptap/pm/state";
+
+// WHY: Top-level block types that need stable IDs for agentic read/write ops.
+// Inline nodes (text, hardBreak) and list items are not top-level in ProseMirror
+// doc structure, so they are excluded.
+const TOP_LEVEL_BLOCK_TYPES = new Set([
+  "paragraph",
+  "heading",
+  "bulletList",
+  "orderedList",
+  "blockquote",
+  "codeBlock",
+  "horizontalRule",
+]);
+
+/** Generate a stable unique ID for a block. Uses crypto.randomUUID() which is
+ * available in Cloudflare Workers, Node 24+, and all modern browsers. */
+export function generateBlockId(): string {
+  return crypto.randomUUID();
+}
+
+function isTopLevelBlock(node: ProseMirrorNode): boolean {
+  return TOP_LEVEL_BLOCK_TYPES.has(node.type.name);
+}
+
+const blockIdPluginKey = new PluginKey("blockId");
+
+/**
+ * TipTap extension that stamps a stable unique `id` on every top-level block,
+ * set on creation and kept on update. Opt in via the `blockIds` prop.
+ */
+export const BlockIdExtension = Extension.create({
+  name: "blockId",
+
+  addGlobalAttributes() {
+    return [
+      {
+        types: Array.from(TOP_LEVEL_BLOCK_TYPES),
+        attributes: {
+          id: {
+            default: null,
+            parseHTML: (element) => element.getAttribute("data-block-id") || null,
+            renderHTML: (attributes) => {
+              if (!attributes.id) return {};
+              return { "data-block-id": attributes.id };
+            },
+          },
+        },
+      },
+    ];
+  },
+
+  addProseMirrorPlugins() {
+    return [
+      new Plugin({
+        key: blockIdPluginKey,
+        appendTransaction(_transactions, _oldState, newState) {
+          const { tr, doc } = newState;
+          let changed = false;
+
+          doc.forEach((node, offset) => {
+            if (!isTopLevelBlock(node)) return;
+            if (node.attrs.id) return;
+
+            const id = generateBlockId();
+            tr.setNodeMarkup(offset, undefined, { ...node.attrs, id });
+            changed = true;
+          });
+
+          return changed ? tr : null;
+        },
+      }),
+    ];
+  },
+});

package/src/editor/block-ops.test.ts

@@ -0,0 +1,237 @@
+import { describe, expect, it } from "vite-plus/test";
+import {
+  listBlocks,
+  appendBlocks,
+  prependBlocks,
+  insertBlocksAfter,
+  replaceBlock,
+  deleteBlock,
+} from "./block-ops.js";
+import { markdownToTiptap } from "./markdown.js";
+
+// Build a test doc from markdown so blocks carry real ids.
+function makeDoc(md: string) {
+  return markdownToTiptap(md);
+}
+
+// ---- listBlocks ----
+describe("listBlocks", () => {
+  it("returns one entry per top-level block", () => {
+    const doc = makeDoc("# Heading\n\nParagraph.\n\n---");
+    const list = listBlocks(doc);
+    expect(list).toHaveLength(3);
+  });
+
+  it("each entry has id, type, text", () => {
+    const doc = makeDoc("Hello world");
+    const list = listBlocks(doc);
+    expect(list[0].id).toBeTruthy();
+    expect(list[0].type).toBe("paragraph");
+    expect(list[0].text).toContain("Hello world");
+  });
+
+  it("id matches the block's attrs.id", () => {
+    const doc = makeDoc("# Title\n\nBody");
+    const list = listBlocks(doc);
+    expect(list[0].id).toBe(doc.content[0].attrs?.id);
+    expect(list[1].id).toBe(doc.content[1].attrs?.id);
+  });
+
+  it("truncates long text to 120 chars", () => {
+    const longText = "x".repeat(200);
+    const doc = makeDoc(longText);
+    const list = listBlocks(doc);
+    expect(list[0].text.length).toBeLessThanOrEqual(120);
+  });
+});
+
+// ---- appendBlocks ----
+describe("appendBlocks", () => {
+  it("adds blocks at the end", () => {
+    const doc = makeDoc("First block");
+    const result = appendBlocks(doc, "Second block");
+    expect(result.content).toHaveLength(2);
+    const types = listBlocks(result).map((b) => b.text);
+    expect(types[0]).toContain("First block");
+    expect(types[1]).toContain("Second block");
+  });
+
+  it("does not mutate the input doc", () => {
+    const doc = makeDoc("Original");
+    const originalLen = doc.content.length;
+    appendBlocks(doc, "Extra");
+    expect(doc.content).toHaveLength(originalLen);
+  });
+
+  it("new blocks have ids", () => {
+    const doc = makeDoc("First");
+    const result = appendBlocks(doc, "Added paragraph");
+    const newBlock = result.content[1];
+    const newId = newBlock.attrs?.id;
+    expect(typeof newId).toBe("string");
+    expect(typeof newId === "string" && newId.length).toBeGreaterThan(0);
+  });
+
+  it("preserves existing block ids", () => {
+    const doc = makeDoc("First");
+    const originalId = doc.content[0].attrs?.id;
+    const result = appendBlocks(doc, "Extra");
+    expect(result.content[0].attrs?.id).toBe(originalId);
+  });
+});
+
+// ---- prependBlocks ----
+describe("prependBlocks", () => {
+  it("adds blocks at the beginning", () => {
+    const doc = makeDoc("Second");
+    const result = prependBlocks(doc, "First");
+    expect(result.content).toHaveLength(2);
+    expect(listBlocks(result)[0].text).toContain("First");
+    expect(listBlocks(result)[1].text).toContain("Second");
+  });
+
+  it("does not mutate the input doc", () => {
+    const doc = makeDoc("Original");
+    const originalLen = doc.content.length;
+    prependBlocks(doc, "New first");
+    expect(doc.content).toHaveLength(originalLen);
+  });
+
+  it("new blocks have ids", () => {
+    const doc = makeDoc("Existing");
+    const result = prependBlocks(doc, "Prepended");
+    expect(typeof result.content[0].attrs?.id).toBe("string");
+  });
+
+  it("preserves existing block ids", () => {
+    const doc = makeDoc("Existing");
+    const existingId = doc.content[0].attrs?.id;
+    const result = prependBlocks(doc, "Prepended");
+    expect(result.content[1].attrs?.id).toBe(existingId);
+  });
+});
+
+// ---- insertBlocksAfter ----
+describe("insertBlocksAfter", () => {
+  it("inserts after the correct block", () => {
+    const doc = makeDoc("# First\n\n## Second\n\n### Third");
+    const secondId = doc.content[1].attrs?.id as string;
+    const result = insertBlocksAfter(doc, secondId, "Inserted");
+    expect(result.content).toHaveLength(4);
+    expect(listBlocks(result)[2].text).toContain("Inserted");
+  });
+
+  it("inserts at the end when afterId is the last block", () => {
+    const doc = makeDoc("A\n\nB");
+    const lastId = doc.content[1].attrs?.id as string;
+    const result = insertBlocksAfter(doc, lastId, "C");
+    expect(result.content).toHaveLength(3);
+    expect(listBlocks(result)[2].text).toContain("C");
+  });
+
+  it("throws for unknown id", () => {
+    const doc = makeDoc("Block");
+    expect(() => insertBlocksAfter(doc, "nonexistent-id", "new")).toThrow(/nonexistent-id/);
+  });
+
+  it("does not mutate the input doc", () => {
+    const doc = makeDoc("A\n\nB");
+    const firstId = doc.content[0].attrs?.id as string;
+    const originalLen = doc.content.length;
+    insertBlocksAfter(doc, firstId, "C");
+    expect(doc.content).toHaveLength(originalLen);
+  });
+
+  it("new blocks have ids", () => {
+    const doc = makeDoc("A");
+    const firstId = doc.content[0].attrs?.id as string;
+    const result = insertBlocksAfter(doc, firstId, "B");
+    expect(typeof result.content[1].attrs?.id).toBe("string");
+  });
+});
+
+// ---- replaceBlock ----
+describe("replaceBlock", () => {
+  it("replaces the target block", () => {
+    const doc = makeDoc("# Old heading\n\nOther");
+    const headingId = doc.content[0].attrs?.id as string;
+    const result = replaceBlock(doc, headingId, "# New heading");
+    expect(result.content).toHaveLength(2);
+    const summary = listBlocks(result);
+    expect(summary[0].text).toContain("New heading");
+    expect(summary[1].text).toContain("Other");
+  });
+
+  it("throws for unknown id", () => {
+    const doc = makeDoc("Block");
+    expect(() => replaceBlock(doc, "no-such-id", "replacement")).toThrow(/no-such-id/);
+  });
+
+  it("does not mutate the input doc", () => {
+    const doc = makeDoc("Original");
+    const id = doc.content[0].attrs?.id as string;
+    const originalText = listBlocks(doc)[0].text;
+    replaceBlock(doc, id, "Replaced");
+    expect(listBlocks(doc)[0].text).toBe(originalText);
+  });
+
+  it("replacement blocks have fresh ids", () => {
+    const doc = makeDoc("Old");
+    const id = doc.content[0].attrs?.id as string;
+    const result = replaceBlock(doc, id, "New");
+    const newId = result.content[0].attrs?.id;
+    expect(typeof newId).toBe("string");
+    // Replacement block gets a fresh id, not the old one.
+    expect(newId).not.toBe(id);
+  });
+
+  it("can replace one block with multiple blocks", () => {
+    const doc = makeDoc("# Heading\n\nPara");
+    const headingId = doc.content[0].attrs?.id as string;
+    const result = replaceBlock(doc, headingId, "# A\n\n# B");
+    expect(result.content).toHaveLength(3);
+  });
+});
+
+// ---- deleteBlock ----
+describe("deleteBlock", () => {
+  it("removes the target block", () => {
+    const doc = makeDoc("A\n\nB\n\nC");
+    const bId = doc.content[1].attrs?.id as string;
+    const result = deleteBlock(doc, bId);
+    expect(result.content).toHaveLength(2);
+    expect(listBlocks(result).map((b) => b.text)).not.toContain("B");
+  });
+
+  it("throws for unknown id", () => {
+    const doc = makeDoc("Block");
+    expect(() => deleteBlock(doc, "ghost-id")).toThrow(/ghost-id/);
+  });
+
+  it("does not mutate the input doc", () => {
+    const doc = makeDoc("A\n\nB");
+    const originalLen = doc.content.length;
+    const firstId = doc.content[0].attrs?.id as string;
+    deleteBlock(doc, firstId);
+    expect(doc.content).toHaveLength(originalLen);
+  });
+
+  it("preserves ids of remaining blocks", () => {
+    const doc = makeDoc("A\n\nB\n\nC");
+    const ids = doc.content.map((n) => n.attrs?.id as string);
+    const result = deleteBlock(doc, ids[1]);
+    expect(result.content[0].attrs?.id).toBe(ids[0]);
+    expect(result.content[1].attrs?.id).toBe(ids[2]);
+  });
+});
+
+// ---- invalid doc ----
+describe("invalid doc input", () => {
+  it("listBlocks throws on null", () => {
+    expect(() => listBlocks(null)).toThrow();
+  });
+
+  it("listBlocks throws on non-doc object", () => {
+    expect(() => listBlocks({ type: "paragraph" })).toThrow();
+  });
+});

package/src/editor/block-ops.ts

@@ -0,0 +1,157 @@
+// WHY: pure, server-safe block edits. No DB, HTTP or DOM, and every op returns
+// a new doc without touching the input.
+
+// Top-level blocks must carry `id` attrs. An unknown id throws.
+
+import { markdownToTiptap } from "./markdown.js";
+
+// =========================
+// TYPES
+// =========================
+
+type TiptapNode = {
+  type: string;
+  attrs?: Record<string, unknown>;
+  content?: TiptapNode[];
+  marks?: { type: string; attrs?: Record<string, unknown> }[];
+  text?: string;
+};
+
+export type TiptapDoc = {
+  type: "doc";
+  content: TiptapNode[];
+};
+
+export type BlockSummary = {
+  id: string;
+  type: string;
+  text: string;
+};
+
+// =========================
+// HELPERS
+// =========================
+
+function extractText(nodes: TiptapNode[] | undefined): string {
+  if (!nodes?.length) return "";
+  return nodes
+    .map((n) => {
+      if (n.type === "text") return n.text ?? "";
+      if (n.type === "hardBreak") return " ";
+      return extractText(n.content);
+    })
+    .join("");
+}
+
+function blockText(node: TiptapNode): string {
+  // For list nodes, join item texts separated by spaces.
+  const raw = extractText(node.content).trim();
+  // Truncate for preview.
+  return raw.length > 120 ? raw.slice(0, 117) + "..." : raw;
+}
+
+function getId(node: TiptapNode): string | null {
+  const id = node.attrs?.id;
+  return typeof id === "string" && id.length > 0 ? id : null;
+}
+
+function requireDoc(doc: unknown): TiptapDoc {
+  const d = doc as TiptapDoc;
+  if (!d || d.type !== "doc" || !Array.isArray(d.content)) {
+    throw new Error("Invalid doc: expected { type: 'doc', content: [...] }");
+  }
+  return d;
+}
+
+function requireBlockById(doc: TiptapDoc, id: string): number {
+  const idx = doc.content.findIndex((n) => getId(n) === id);
+  if (idx === -1) {
+    throw new Error(`Block id "${id}" not found in doc`);
+  }
+  return idx;
+}
+
+function newBlocksFromMd(markdown: string): TiptapNode[] {
+  const parsed = markdownToTiptap(markdown);
+  return parsed.content;
+}
+
+// =========================
+// PUBLIC OPS
+// =========================
+
+/**
+ * Return a flat list of top-level blocks with id, type, and plain-text preview.
+ */
+export function listBlocks(doc: unknown): BlockSummary[] {
+  const d = requireDoc(doc);
+  return d.content.map((node) => ({
+    id: getId(node) ?? "",
+    type: node.type,
+    text: blockText(node),
+  }));
+}
+
+/**
+ * Append blocks parsed from `markdown` after the last block.
+ * Returns a new doc.
+ */
+export function appendBlocks(doc: unknown, markdown: string): TiptapDoc {
+  const d = requireDoc(doc);
+  const added = newBlocksFromMd(markdown);
+  return {
+    type: "doc",
+    content: [...d.content, ...added],
+  };
+}
+
+/**
+ * Prepend blocks parsed from `markdown` before the first block.
+ * Returns a new doc.
+ */
+export function prependBlocks(doc: unknown, markdown: string): TiptapDoc {
+  const d = requireDoc(doc);
+  const added = newBlocksFromMd(markdown);
+  return {
+    type: "doc",
+    content: [...added, ...d.content],
+  };
+}
+
+/**
+ * Insert blocks parsed from `markdown` immediately after the block with `afterId`.
+ * Throws if `afterId` does not exist.
+ * Returns a new doc.
+ */
+export function insertBlocksAfter(doc: unknown, afterId: string, markdown: string): TiptapDoc {
+  const d = requireDoc(doc);
+  const idx = requireBlockById(d, afterId);
+  const added = newBlocksFromMd(markdown);
+  const content = [...d.content.slice(0, idx + 1), ...added, ...d.content.slice(idx + 1)];
+  return { type: "doc", content };
+}
+
+/**
+ * Replace the block with `id` with blocks parsed from `markdown`.
+ * Throws if `id` does not exist.
+ * Returns a new doc.
+ */
+export function replaceBlock(doc: unknown, id: string, markdown: string): TiptapDoc {
+  const d = requireDoc(doc);
+  const idx = requireBlockById(d, id);
+  const added = newBlocksFromMd(markdown);
+  const content = [...d.content.slice(0, idx), ...added, ...d.content.slice(idx + 1)];
+  return { type: "doc", content };
+}
+
+/**
+ * Delete the block with `id`.
+ * Throws if `id` does not exist.
+ * Returns a new doc.
+ */
+export function deleteBlock(doc: unknown, id: string): TiptapDoc {
+  const d = requireDoc(doc);
+  const idx = requireBlockById(d, id);
+  const content = [...d.content.slice(0, idx), ...d.content.slice(idx + 1)];
+  return { type: "doc", content };
+}