@heyramzi/ui 1.54.2 → 2.0.0

package/src/components/theme/theme-provider.svelte

@@ -2,25 +2,27 @@
 	// =========================
 	// IMPORTS
 	// =========================
-	import { ModeWatcher, userPrefersMode, type UserPrefersMode } from "mode-watcher";
+	import { ModeWatcher, userPrefersMode } from "mode-watcher";
 	import type { ComponentProps } from "svelte";
 
 	// =========================
 	// TYPES
 	// =========================
 	type WatcherProps = ComponentProps<typeof ModeWatcher>;
+	// mode-watcher exports its store class under the name UserPrefersMode, so the value type comes from the store.
+	type ThemeMode = (typeof userPrefersMode)["current"];
 
 	interface Props extends Omit<WatcherProps, "defaultMode"> {
 		/**
 		 * The choice the server already knows, for a browser that has none stored. A stored
 		 * choice wins, so it seeds a first visit and never overrides a click.
 		 */
-		initial?: UserPrefersMode;
+		initial?: ThemeMode;
 		/**
 		 * Fires when the person changes the mode, never on load. An app that saves the choice
 		 * on its server posts it here.
 		 */
-		onChange?: (mode: UserPrefersMode) => void;
+		onChange?: (mode: ThemeMode) => void;
 	}
 
 	// =========================
@@ -32,7 +34,7 @@
 	// EFFECTS
 	// =========================
 	// The first run is the mode read from storage on mount, which nobody chose.
-	let seen: UserPrefersMode | null = null;
+	let seen: ThemeMode | null = null;
 	$effect(() => {
 		const next = userPrefersMode.current;
 		if (seen !== null && next !== seen) onChange?.(next);

package/src/components/toolbar/index.ts

@@ -0,0 +1,5 @@
+/**
+ * One toolbar row for a list page. Wide, it shows search, tabs and a view switch inline. Narrow,
+ * each of those folds into a menu and the row never wraps.
+ */
+export { default as Toolbar } from "./toolbar.svelte";

package/src/components/toolbar/toolbar.svelte

@@ -0,0 +1,168 @@
+<script lang="ts" generics="Tab extends string, View extends string">
+	// =========================
+	// IMPORTS
+	// =========================
+	import type { Snippet } from "svelte";
+	import { CaretDown, MagnifyingGlass } from "phosphor-svelte";
+	import { SegmentedFilter } from "../segmented/index.js";
+	import type { TabDef } from "../segmented/animated-tabs.svelte";
+	import { toolbarTriggerClass } from "../list-page/toolbar-trigger.js";
+	import ToolbarSearch from "../list-page/toolbar-search.svelte";
+	import { Input } from "../../shadcn/input/index.js";
+	import * as DropdownMenu from "../../shadcn/dropdown-menu/index.js";
+	import * as Popover from "../../shadcn/popover/index.js";
+	import { cn } from "../../lib/utils.js";
+
+	// =========================
+	// TYPES
+	// =========================
+	interface Props {
+		/** The search text. Leave it out for no search. */
+		search?: string;
+		searchPlaceholder?: string;
+		/** The label of the narrow search button. Translate at the call site. */
+		searchLabel?: string;
+		/** A strip of tabs, such as All, Open and Done. */
+		tabs?: readonly TabDef<Tab>[];
+		tab?: Tab;
+		tabsLabel?: string;
+		/** How the page shows its records: a list, a board, a grid. Each one needs an icon. */
+		views?: readonly (TabDef<View> & { icon: NonNullable<TabDef<View>["icon"]> })[];
+		view?: View;
+		viewLabel?: string;
+		/** Controls that stay on the row at every width, such as filter chips. They scroll sideways before they wrap. */
+		filters?: Snippet;
+		/** The primary action and its neighbours, pinned to the right edge. */
+		actions?: Snippet;
+		class?: string;
+	}
+
+	// =========================
+	// PROPS
+	// =========================
+	let {
+		search = $bindable(),
+		searchPlaceholder = "Search...",
+		searchLabel = "Search",
+		tabs,
+		tab = $bindable(),
+		tabsLabel = "Show",
+		views,
+		view = $bindable(),
+		viewLabel = "View",
+		filters,
+		actions,
+		class: className,
+	}: Props = $props();
+
+	// =========================
+	// DERIVED
+	// =========================
+	let currentTab = $derived(tabs?.find((t) => t.value === tab));
+	let currentView = $derived(views?.find((v) => v.value === view));
+	let searching = $derived(Boolean(search));
+</script>
+
+<!-- =========================== -->
+<!-- MARKUP -->
+<!-- =========================== -->
+<!-- WHY a container query: the toolbar sits in a pane that is narrower than the screen, and a
+     breakpoint reads the screen. WHY nowrap: a second row pushes the content down and moves the
+     page as a search is opened. Search, tabs and view are the three that fold, each into the one
+     menu that holds them; both forms are in the DOM and the query shows one, so there is no
+     measuring and no flash on first paint. -->
+<div class={cn("@container/toolbar min-w-0", className)}>
+	<div class="flex flex-nowrap items-center gap-2">
+		{#if search !== undefined}
+			<div class="w-56 shrink-0 @max-2xl/toolbar:hidden">
+				<ToolbarSearch bind:value={search} placeholder={searchPlaceholder} />
+			</div>
+			<Popover.Root>
+				<Popover.Trigger
+					aria-label={searchLabel}
+					class={cn(toolbarTriggerClass({ active: searching }), "@2xl/toolbar:hidden")}
+				>
+					<MagnifyingGlass class="size-3.5" aria-hidden="true" />
+				</Popover.Trigger>
+				<Popover.Content align="start" class="w-64 p-2">
+					<Input bind:value={search} placeholder={searchPlaceholder} aria-label={searchLabel} class="h-8" />
+				</Popover.Content>
+			</Popover.Root>
+		{/if}
+
+		{#if tabs && tab !== undefined}
+			<SegmentedFilter
+				options={tabs}
+				bind:value={tab}
+				ariaLabel={tabsLabel}
+				block={false}
+				class="@max-2xl/toolbar:hidden"
+			/>
+			<DropdownMenu.Root>
+				<DropdownMenu.Trigger
+					aria-label={tabsLabel}
+					class={cn(toolbarTriggerClass(), "min-w-0 @2xl/toolbar:hidden")}
+				>
+					<span class="truncate">{currentTab?.label}</span>
+					<CaretDown class="size-3 shrink-0" aria-hidden="true" />
+				</DropdownMenu.Trigger>
+				<DropdownMenu.Content align="start">
+					<DropdownMenu.RadioGroup bind:value={tab}>
+						{#each tabs as item (item.value)}
+							<DropdownMenu.RadioItem value={item.value}>
+								{item.label}
+								{#if item.count != null}
+									<span class="ms-auto pe-2 text-xs text-muted-foreground tabular-nums">{item.count}</span>
+								{/if}
+							</DropdownMenu.RadioItem>
+						{/each}
+					</DropdownMenu.RadioGroup>
+				</DropdownMenu.Content>
+			</DropdownMenu.Root>
+		{/if}
+
+		{#if filters}
+			<div class="no-scrollbar flex min-w-0 flex-1 items-center gap-2 overflow-x-auto">
+				{@render filters()}
+			</div>
+		{:else}
+			<div class="flex-1"></div>
+		{/if}
+
+		{#if views && view !== undefined}
+			<SegmentedFilter
+				options={views}
+				bind:value={view}
+				ariaLabel={viewLabel}
+				block={false}
+				class="@max-2xl/toolbar:hidden"
+			/>
+			<DropdownMenu.Root>
+				<DropdownMenu.Trigger
+					aria-label={viewLabel}
+					class={cn(toolbarTriggerClass(), "@2xl/toolbar:hidden")}
+				>
+					{#if currentView}
+						<currentView.icon class="size-3.5" aria-hidden="true" />
+					{/if}
+				</DropdownMenu.Trigger>
+				<DropdownMenu.Content align="end">
+					<DropdownMenu.RadioGroup bind:value={view}>
+						{#each views as item (item.value)}
+							<DropdownMenu.RadioItem value={item.value}>
+								<item.icon class="size-4" aria-hidden="true" />
+								{item.label}
+							</DropdownMenu.RadioItem>
+						{/each}
+					</DropdownMenu.RadioGroup>
+				</DropdownMenu.Content>
+			</DropdownMenu.Root>
+		{/if}
+
+		{#if actions}
+			<div class="flex shrink-0 items-center gap-2">
+				{@render actions()}
+			</div>
+		{/if}
+	</div>
+</div>

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();
+  });
+});