@podoba/react 0.0.30 → 0.0.32

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@podoba/react",
-	"version": "0.0.30",
+	"version": "0.0.32",
 	"type": "module",
 	"description": "podoba React components — React Aria Components + Tailwind primitives + layout, built with uic.",
 	"repository": {
@@ -13,7 +13,8 @@
 	"main": "./src/index.ts",
 	"types": "./src/index.ts",
 	"exports": {
-		".": "./src/index.ts"
+		".": "./src/index.ts",
+		"./editor": "./src/editor/index.ts"
 	},
 	"files": [
 		"src",
@@ -27,17 +28,48 @@
 		"typecheck": "tsc --build"
 	},
 	"dependencies": {
-		"@podoba/tokens": "^0.0.30",
-		"@podoba/tailwind": "^0.0.30",
+		"@podoba/tokens": "^0.0.32",
+		"@podoba/tailwind": "^0.0.32",
 		"react-aria-components": "1.18.0",
 		"class-variance-authority": "0.7.1",
 		"clsx": "2.1.1",
 		"tailwind-merge": "3.6.0",
 		"@radix-ui/react-slot": "1.2.4"
 	},
+	"//tiptap": "Only `@podoba/react/editor` (BlockEditor) needs Tiptap. Optional peers, not dependencies: the base package must not make every consumer install ProseMirror, and a peer keeps ONE @tiptap/pm in the tree — two copies of prosemirror-model break instanceof across the editor.",
 	"peerDependencies": {
 		"react": ">=19",
-		"react-dom": ">=19"
+		"react-dom": ">=19",
+		"@tiptap/react": "^3.27.4",
+		"@tiptap/pm": "^3.27.4",
+		"@tiptap/starter-kit": "^3.27.4",
+		"@tiptap/extension-placeholder": "^3.27.4",
+		"@tiptap/extension-highlight": "^3.27.4",
+		"@tiptap/extension-task-list": "^3.27.4",
+		"@tiptap/extension-task-item": "^3.27.4"
+	},
+	"peerDependenciesMeta": {
+		"@tiptap/react": {
+			"optional": true
+		},
+		"@tiptap/pm": {
+			"optional": true
+		},
+		"@tiptap/starter-kit": {
+			"optional": true
+		},
+		"@tiptap/extension-placeholder": {
+			"optional": true
+		},
+		"@tiptap/extension-highlight": {
+			"optional": true
+		},
+		"@tiptap/extension-task-list": {
+			"optional": true
+		},
+		"@tiptap/extension-task-item": {
+			"optional": true
+		}
 	},
 	"devDependencies": {
 		"react": "^19.2.1",
@@ -45,6 +77,13 @@
 		"@types/react": "^19.2.7",
 		"@types/react-dom": "^19.2.3",
 		"typescript": "^5.9.3",
-		"@types/bun": "^1.3.3"
+		"@types/bun": "^1.3.3",
+		"@tiptap/react": "^3.27.4",
+		"@tiptap/pm": "^3.27.4",
+		"@tiptap/starter-kit": "^3.27.4",
+		"@tiptap/extension-placeholder": "^3.27.4",
+		"@tiptap/extension-highlight": "^3.27.4",
+		"@tiptap/extension-task-list": "^3.27.4",
+		"@tiptap/extension-task-item": "^3.27.4"
 	}
 }

package/src/components/brand-page-header.tsx

@@ -37,7 +37,8 @@ export type BrandPageHeaderProps = {
 	 * gs-style "title to go back": a muted, clickable PARENT link rendered as the
 	 * line ABOVE the title (so the title reads "Parent ⏎ Current"). Pass a real
 	 * router `<Link>` so it's an anchor (cmd/middle-click, deep-link-safe), exactly
-	 * like gs's `parentLink`. The header styles it muted with a hover→fg affordance.
+	 * like gs's `parentLink`. The header uses the source's decorative `fg-subtle`
+	 * (#b3b3b3) with a hover→fg affordance.
 	 */
 	parentLink?: ReactNode
 	/** Optional breadcrumb trail rendered above the greeting. */
@@ -128,7 +129,7 @@ export function BrandPageHeader({
 								// `[&_a]` styles the nested router <Link> (anchor) without @app/ui
 								// importing the router.
 								<>
-									<span className="text-fg-muted transition-colors [&_a:hover]:text-fg [&_a]:text-fg-muted [&_a]:no-underline [&_a]:outline-none [&_a:focus-visible]:underline">
+									<span className="text-fg-subtle transition-colors [&_a:hover]:text-fg [&_a]:text-fg-subtle [&_a]:no-underline [&_a]:outline-none [&_a:focus-visible]:underline">
 										{parentLink}
 									</span>
 									<br />

package/src/components/button.tsx

@@ -19,9 +19,9 @@ export const Button = uic(RACButton, {
 		'data-[pending]:opacity-70 data-[pending]:cursor-progress',
 	variants: {
 		variant: {
-			// primary (gs `_primary`): base neutral-400 (#242423 = surface-inverted) →
-			// hover neutral-600 (#333333) + `0 0 5px rgba(0,0,0,.5)` shadow → active back
-			// to neutral-400 (surface-inverted, no shadow).
+			// primary (gs `_primary`): base brand-primary (#0d0d0d light / brand-green on
+			// dark) → hover neutral-600 (#333333) + `0 0 5px rgba(0,0,0,.5)` shadow →
+			// active back to brand-primary (no shadow).
 			primary:
 				'bg-brand-primary text-fg-inverted hover:bg-neutral-600 hover:shadow-[0_0_5px_0_rgba(0,0,0,0.5)] data-[pressed]:bg-brand-primary data-[pressed]:shadow-none',
 			// secondary: #f7f6f2 (surface-card) + 1px #eceae1 (border); hover bg #eceae1

package/src/components/dialog.tsx

@@ -133,6 +133,10 @@ export const Dialog = ({
 		// Either way the RACDialog render-prop `close` resolves against the active
 		// overlay state, so `close()` works in both modes.
 		<ModalOverlay
+			// Full-screen is an immersive takeover: swap the light scrim for a heavier
+			// backdrop blur so the page behind reads as clearly blurred around the
+			// near-fullscreen canvas. (tailwind-merge dedupes the base blur/scrim.)
+			className={isFlex ? 'bg-black/25 backdrop-blur-lg' : undefined}
 			isOpen={isOpen}
 			defaultOpen={defaultOpen}
 			onOpenChange={onOpenChange}

package/src/components/input.tsx

@@ -20,15 +20,21 @@ import { uic } from '../utils/uic'
  */
 const StyledInput = uic(RACInput, {
 	displayName: 'InputControl',
-	// gs source: borderless cream fill, 8px radius, 14/18 text and 16px inline
-	// padding. Focus keeps an explicit ring for keyboard accessibility.
+	// White fill + border so the field reads as editable. The gs original used a
+	// borderless cream (#f7f6f2 → surface-card) fill, but our Card surface is ALSO
+	// surface-card — and in dark theme surface-card and surface are the SAME colour
+	// (#242423) — so a borderless cream field vanishes on both. Inverted: active =
+	// surface, disabled = the muted cream. border #eceae1 → border · hover #aba89c →
+	// fg-subtle · focus #75e7b8 → brand-green · error → danger. This is the shared
+	// filled-field skin (textarea / combobox / date-field / number-field /
+	// search-field); `fieldSize` adds the single-line height on top.
 	baseClass:
-		'w-full rounded-lg border-0 bg-surface-card px-4 text-small text-fg ' +
+		'w-full rounded-lg border border-border bg-surface px-4 text-small text-fg ' +
 		'outline-none transition-colors duration-200 placeholder:text-fg-muted ' +
-		'data-[hovered]:bg-surface-muted ' +
-		'data-[focused]:ring-2 data-[focused]:ring-ring ' +
-		'data-[invalid]:ring-2 data-[invalid]:ring-danger ' +
-		'data-[disabled]:bg-surface-muted data-[disabled]:opacity-50 data-[disabled]:pointer-events-none',
+		'data-[hovered]:border-fg-subtle ' +
+		'data-[focused]:border-brand-green data-[focused]:ring-2 data-[focused]:ring-ring ' +
+		'data-[invalid]:border-danger data-[invalid]:ring-2 data-[invalid]:ring-danger ' +
+		'data-[disabled]:bg-surface-muted data-[disabled]:opacity-60 data-[disabled]:pointer-events-none',
 	variants: {
 		// `fieldSize` (not `size`) to avoid colliding with the native <input size>
 		// attribute, which RAC's Input inherits (a numeric prop).

package/src/components/rich-text-editor.tsx

@@ -1,12 +1,19 @@
 import { type ClipboardEvent as ReactClipboardEvent, type ReactNode, useEffect, useRef } from 'react'
 import { clsx } from 'clsx'
+import { SAFE_LINK_HINT, safeLinkUrl } from '../utils/safe-link-url'
 import { useInFocusOverlay } from './focus-context'
 
 /**
  * RichTextEditor — a dependency-free contentEditable WYSIWYG that emits an HTML
  * string (round-trips with any `set:html` / `dangerouslySetInnerHTML` renderer,
  * so no value migration and no bundled ProseMirror). Ported from pramen's
- * cms-editor `RichText`; TipTap is the upgrade path if tables/embeds are needed.
+ * cms-editor `RichText`.
+ *
+ * Still the right pick for a short caption/bio field. For document-shaped content
+ * — blocks, a `/` palette, tables/embeds — reach for `BlockEditor` from
+ * `@podoba/react/editor` instead; it is the Tiptap-backed upgrade this component's
+ * `execCommand` core cannot grow into. Both emit the same HTML-string value, so
+ * swapping one for the other needs no data migration.
  *
  * The `prose prose-sm` body relies on the @tailwindcss/typography plugin, which
  * @podoba/tailwind's preset already registers.
@@ -32,7 +39,7 @@ const RT_TOOLS: Array<{ label: string; title: string; run: (exec: (c: string, a?
 			if (!raw) return
 			const url = safeLinkUrl(raw)
 			if (!url) {
-				window.alert('Only http(s), mailto, tel, or relative (/, #) links are allowed.')
+				window.alert(SAFE_LINK_HINT)
 				return
 			}
 			x('createLink', url)
@@ -42,13 +49,6 @@ const RT_TOOLS: Array<{ label: string; title: string; run: (exec: (c: string, a?
 	{ label: 'Clear', title: 'Clear formatting', run: (x) => x('removeFormat') },
 ]
 
-/** Allow-list for a link href: http(s), mailto, tel, or a relative/anchor path.
- * The prefix allow-list inherently rejects `javascript:`/`data:`/`vbscript:`. */
-function safeLinkUrl(raw: string): string | null {
-	const url = raw.trim()
-	return /^(https?:\/\/|mailto:|tel:|\/|#)/i.test(url) ? url : null
-}
-
 /** Cosmetic scrub (NOT a security boundary — sanitise on the server). */
 function scrubHtml(html: string): string {
 	return html

package/src/components/select.tsx

@@ -21,24 +21,26 @@ import { useInFocusOverlay } from './focus-context'
  * RAC handles the listbox ARIA pattern, keyboard navigation, typeahead and
  * focus management. Styling via `uic`. Pass options as `SelectItem` children.
  *
- * Re-skinned 1:1 to gs-platform's designer spec (Figma GraphicStandard 1.5,
- * node 2115-4271 — `Select.module.scss`): a tall (min-h 58px) borderless filled
- * trigger on the cream `surface-card`, matching our `Input` / `Textarea` fill so
- * the form controls stay consistent. gs token map: bg #f7f6f2 → surface-card ·
- * hover #eceae1 → surface-muted · text #0d0d0d → fg · placeholder → fg-muted ·
+ * Re-skinned to gs-platform's designer spec (Figma GraphicStandard 1.5, node
+ * 2115-4271 — `Select.module.scss`): a tall (58px) filled trigger matching our
+ * `Input` / `Textarea` so the form controls stay consistent. gs token map:
+ * hover border #aba89c → fg-subtle · text #0d0d0d → fg · placeholder → fg-muted ·
  * 8px radius → rounded-lg · 6px item radius → rounded-md · error → danger.
  */
 const SelectTrigger = uic(RACButton, {
 	displayName: 'SelectTrigger',
-	// Exact gs source control: 58px tall, 20px inline padding, borderless cream
-	// fill and 8px radius.
+	// gs source control geometry (58px tall, 20px inline padding, 8px radius) with
+	// the shared bordered fill: gs draws it borderless on cream, but our Card is
+	// also surface-card and dark theme collapses surface-card onto surface, so a
+	// borderless cream trigger disappears. White fill + border keeps it visible and
+	// consistent with the other form controls; hover darkens the border.
 	baseClass:
-		'flex h-control-tall w-full items-center justify-between gap-2.5 rounded-lg border-0 bg-surface-card px-5 ' +
+		'flex h-control-tall w-full items-center justify-between gap-2.5 rounded-lg border border-border bg-surface px-5 ' +
 		'text-small text-fg outline-none transition-colors ' +
-		'data-[hovered]:bg-surface-muted ' +
+		'data-[hovered]:border-fg-subtle ' +
 		'data-[focus-visible]:ring-2 data-[focus-visible]:ring-ring ' +
-		'group-data-[invalid]:ring-2 group-data-[invalid]:ring-danger ' +
-		'data-[disabled]:bg-surface-muted data-[disabled]:opacity-50 data-[disabled]:pointer-events-none',
+		'group-data-[invalid]:border-danger group-data-[invalid]:ring-2 group-data-[invalid]:ring-danger ' +
+		'data-[disabled]:bg-surface-muted data-[disabled]:opacity-60 data-[disabled]:pointer-events-none',
 })
 
 export const SelectItem = uic(ListBoxItem, {

package/src/components/text.tsx

@@ -6,10 +6,12 @@ import { uic } from '../utils/uic'
  * They express the `@app/tokens` type ramp as variant props so screens stop
  * hand-writing `text-[NNpx]` literals (the scale, not arbitrary pixels). Two ramps:
  *
- *   • <Text> — the SIZE-ONLY UI ramp (micro · caption · label · compact · callout ·
- *     body · subtitle · title · headline · display). Like the tokens, these set
- *     font-size only; pair with `leading-*` via `className` where a fixed leading
- *     matters. `weight` + `tone` cover the common cases.
+ *   • <Text> — the UI ramp (micro · caption · label · compact · small · callout ·
+ *     body · subtitle · title · headline · display). Four of these carry the gs
+ *     source leading with them (compact 13/16, small 14/18, body 16/22,
+ *     display 28/30); the rest are size-only — pair those with `leading-*` via
+ *     `className` where a fixed leading matters. `weight` + `tone` cover the
+ *     common cases.
  *   • <Heading> — the semantic heading ramp (`level` 1–5 → text-heading1…5), which
  *     DO carry a matching line-height. Renders an <h2> by default; pass `asChild`
  *     to project the styles onto the correct heading element for the document

package/src/editor/block-editor.tsx

@@ -0,0 +1,522 @@
+import { useCallback, useEffect, useId, useLayoutEffect, useMemo, useRef, useState, type ReactNode } from 'react'
+import { createPortal } from 'react-dom'
+import { EditorContent, useEditor, useEditorState, type Editor } from '@tiptap/react'
+import { BubbleMenu } from '@tiptap/react/menus'
+import type { EditorState } from '@tiptap/pm/state'
+import StarterKit from '@tiptap/starter-kit'
+import Placeholder from '@tiptap/extension-placeholder'
+import Highlight from '@tiptap/extension-highlight'
+import TaskList from '@tiptap/extension-task-list'
+import TaskItem from '@tiptap/extension-task-item'
+import { clsx } from 'clsx'
+import { SAFE_LINK_HINT, safeLinkUrl } from '../utils/safe-link-url'
+
+/**
+ * BlockEditor — a Notion-style block/rich-text editor for podoba, on Tiptap 3
+ * (ProseMirror). Opt-in subpath (`@podoba/react/editor`) so the base library stays
+ * free of the ProseMirror weight — importing this is what pulls Tiptap into a bundle.
+ * The Tiptap packages are OPTIONAL PEERS: install them alongside @podoba/react only
+ * if you import this subpath.
+ *
+ * Serialises to an **HTML string** (controlled `value` / `onChange(html)`), so it is a
+ * drop-in upgrade for any `set:html` / `dangerouslySetInnerHTML` renderer with no value
+ * migration. SECURITY: like any editor, it can emit arbitrary HTML — sanitise on the
+ * SERVER on write; the `value`/`onChange` contract here is presentation only.
+ *
+ * CONTROLLED-VALUE CONTRACT: echo `onChange`'s HTML back as `value` VERBATIM. The
+ * editor only re-seeds its document when `value` differs from what it last emitted, so
+ * a parent that normalises/sanitises before echoing would re-seed on every keystroke
+ * and send the caret back to the start. Sanitise on write to your store, not in render.
+ *
+ * Notion features: `/` slash menu (self-contained — insert paragraph/heading/list/
+ * to-do/quote/code/divider), an inline bubble toolbar (bold/italic/strike/highlight/
+ * code/link), and StarterKit's markdown input rules. Styling rides `@tailwindcss/
+ * typography` (`prose`), which @podoba/tailwind already registers, plus design tokens
+ * so it flips under `[data-theme="dark"]`.
+ *
+ * Prefer this over {@link ../components/rich-text-editor RichTextEditor} for
+ * document-shaped content; the dependency-free contentEditable one stays the right
+ * pick for a short caption/bio field where ProseMirror is not worth installing.
+ */
+export type BlockEditorProps = {
+	/** Controlled HTML value. Must be echoed back verbatim — see the contract above. */
+	value: string
+	/** Called with the editor's HTML on every change. */
+	onChange: (html: string) => void
+	/** Empty-document placeholder (also the `/`-hint). */
+	placeholder?: string
+	/** Optional visible label rendered above the editor; names the editable region. */
+	label?: ReactNode
+	/** Set false for a read-only render. */
+	editable?: boolean
+	/** Min height of the editable surface (default 200px). */
+	minHeight?: number | string
+	/** Class on the outer container. */
+	className?: string
+	/** Accessible name when there is no visible `label`. */
+	'aria-label'?: string
+}
+
+type SlashCommand = {
+	title: string
+	hint: string
+	keywords: string[]
+	run: (editor: Editor) => void
+}
+
+// The `/` block palette. Kept generic (no domain blocks) — a CMS/app composes richer
+// block types around this at the document level; this is the text-block vocabulary.
+const SLASH_COMMANDS: readonly SlashCommand[] = [
+	{ title: 'Text', hint: 'Plain paragraph', keywords: ['text', 'paragraph', 'body', 'p'], run: (e) => e.chain().focus().setParagraph().run() },
+	{ title: 'Heading 1', hint: 'Big section heading', keywords: ['h1', 'heading', 'title'], run: (e) => e.chain().focus().toggleHeading({ level: 1 }).run() },
+	{ title: 'Heading 2', hint: 'Medium heading', keywords: ['h2', 'subheading'], run: (e) => e.chain().focus().toggleHeading({ level: 2 }).run() },
+	{ title: 'Heading 3', hint: 'Small heading', keywords: ['h3'], run: (e) => e.chain().focus().toggleHeading({ level: 3 }).run() },
+	{ title: 'Bulleted list', hint: 'Unordered list', keywords: ['bullet', 'unordered', 'ul', 'list'], run: (e) => e.chain().focus().toggleBulletList().run() },
+	{ title: 'Numbered list', hint: 'Ordered list', keywords: ['numbered', 'ordered', 'ol', 'list'], run: (e) => e.chain().focus().toggleOrderedList().run() },
+	{ title: 'To-do list', hint: 'Checklist', keywords: ['todo', 'task', 'checkbox', 'check'], run: (e) => e.chain().focus().toggleTaskList().run() },
+	{ title: 'Quote', hint: 'Block quote', keywords: ['quote', 'blockquote', 'citation'], run: (e) => e.chain().focus().toggleBlockquote().run() },
+	{ title: 'Code', hint: 'Code block', keywords: ['code', 'snippet', 'pre'], run: (e) => e.chain().focus().toggleCodeBlock().run() },
+	{ title: 'Divider', hint: 'Horizontal rule', keywords: ['divider', 'rule', 'hr', 'separator'], run: (e) => e.chain().focus().setHorizontalRule().run() },
+]
+
+/** Open palette: the doc position of the trigger `/`, the query typed after it, and
+ * the highlighted row. Screen position is derived from `from` at paint time, never
+ * stored — so the menu can be re-placed on scroll/resize without stale coordinates. */
+type SlashState = { from: number; query: string; index: number }
+
+/** Filter the palette by title or keyword. Exported for tests. */
+export function filterCommands(query: string): SlashCommand[] {
+	const q = query.trim().toLowerCase()
+	if (!q) return [...SLASH_COMMANDS]
+	return SLASH_COMMANDS.filter((c) => c.title.toLowerCase().includes(q) || c.keywords.some((k) => k.includes(q)))
+}
+
+/** A `/` only opens the palette at the start of a block or after whitespace — never
+ * mid-word, so `and/or`, `https://…` and `/api/v2` stay plain text. Code blocks are
+ * excluded outright: a `/` there is always literal. Exported for tests. */
+export function canOpenSlash(state: EditorState, from: number): boolean {
+	if (from < 0 || from > state.doc.content.size) return false
+	const $from = state.doc.resolve(from)
+	if ($from.parent.type.spec.code) return false
+	if ($from.parentOffset === 0) return true
+	// textBetween returns '' for a non-text node (inline image, mention) — treat that
+	// as a boundary too; only a real word character blocks the trigger.
+	return /^\s*$/.test($from.parent.textBetween($from.parentOffset - 1, $from.parentOffset))
+}
+
+const btn =
+	'inline-flex h-8 min-w-8 items-center justify-center rounded-md px-2 text-small text-fg-muted transition-colors hover:bg-surface-muted hover:text-fg data-[active=true]:bg-surface-muted data-[active=true]:text-fg'
+
+/** Marks the bubble toolbar toggles. `active` keys read off the useEditorState
+ * snapshot below — Tiptap 3 does NOT re-render on transactions, so a plain
+ * `editor.isActive()` read during render would go stale on selection-only changes. */
+const MARK_TOOLS = [
+	{ key: 'bold', title: 'Bold', label: <b>B</b>, run: (e: Editor) => e.chain().focus().toggleBold().run() },
+	{ key: 'italic', title: 'Italic', label: <i>i</i>, run: (e: Editor) => e.chain().focus().toggleItalic().run() },
+	{ key: 'strike', title: 'Strikethrough', label: <s>S</s>, run: (e: Editor) => e.chain().focus().toggleStrike().run() },
+	{ key: 'highlight', title: 'Highlight', label: 'H', run: (e: Editor) => e.chain().focus().toggleHighlight().run() },
+	{ key: 'code', title: 'Inline code', label: '</>', run: (e: Editor) => e.chain().focus().toggleCode().run() },
+] as const
+
+const LinkIcon = () => (
+	<svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
+		<path d="M10 13a5 5 0 0 0 7.54.54l3-3a5 5 0 0 0-7.07-7.07l-1.72 1.71" />
+		<path d="M14 11a5 5 0 0 0-7.54-.54l-3 3a5 5 0 0 0 7.07 7.07l1.71-1.71" />
+	</svg>
+)
+
+export function BlockEditor({ value, onChange, placeholder = "Write, or press '/' for blocks…", label, editable = true, minHeight = 200, className, ...aria }: BlockEditorProps) {
+	const onChangeRef = useRef(onChange)
+	onChangeRef.current = onChange
+	const lastEmitted = useRef<string>(value)
+	// The Placeholder extension is configured once at editor creation, so read the
+	// current prop through a ref — that keeps `placeholder` live without recreating
+	// the whole editor on every change.
+	const placeholderRef = useRef(placeholder)
+	placeholderRef.current = placeholder
+
+	// Slash state lives in a REF as well as in React state: ProseMirror handlers run
+	// synchronously inside the key event, long before React re-renders, so reading a
+	// render-assigned ref would lag a full render (two fast `/`s would double-open).
+	// `setSlash` writes both, so handlers always see what the last one wrote.
+	const slashRef = useRef<SlashState | null>(null)
+	const [slash, setSlashState] = useState<SlashState | null>(null)
+	const setSlash = useCallback((next: SlashState | null) => {
+		slashRef.current = next
+		setSlashState(next)
+	}, [])
+
+	const [linkOpen, setLinkOpen] = useState(false)
+	const linkOpenRef = useRef(false)
+	linkOpenRef.current = linkOpen
+	const [linkDraft, setLinkDraft] = useState('')
+	const [linkError, setLinkError] = useState<string | null>(null)
+	const linkInputRef = useRef<HTMLInputElement>(null)
+
+	const menuRef = useRef<HTMLDivElement>(null)
+	const [menuPos, setMenuPos] = useState<{ left: number; top: number } | null>(null)
+	// The palette portals to <body>, so mount first — a portal has no server render.
+	const [mounted, setMounted] = useState(false)
+	useEffect(() => setMounted(true), [])
+
+	const reactId = useId()
+	const labelId = `${reactId}-label`
+	const listboxId = `${reactId}-slash`
+	const optionId = (i: number) => `${listboxId}-option-${i}`
+
+	// `runSlash` closes over `editor`, which does not exist yet — hand the handlers a
+	// ref instead of relying on Tiptap re-applying options after every render.
+	const runSlashRef = useRef<(cmd: SlashCommand) => void>(() => {})
+
+	const ariaLabel = aria['aria-label']
+	const filtered = useMemo(() => filterCommands(slash?.query ?? ''), [slash?.query])
+	const activeOption = slash ? Math.min(slash.index, Math.max(filtered.length - 1, 0)) : 0
+	const paletteOpen = slash !== null && filtered.length > 0
+
+	const editor = useEditor({
+		editable,
+		// Explicit: Tiptap otherwise renders immediately and warns on every SSR pass.
+		// A published library cannot assume a client-only host.
+		immediatelyRender: false,
+		extensions: [
+			StarterKit.configure({ heading: { levels: [1, 2, 3] }, link: { openOnClick: false, autolink: true } }),
+			Highlight,
+			TaskList,
+			TaskItem.configure({ nested: true }),
+			Placeholder.configure({ placeholder: () => placeholderRef.current }),
+		],
+		content: value || '',
+		editorProps: {
+			attributes: {
+				class: clsx(
+					'prose prose-sm max-w-none px-4 py-3 text-fg outline-none',
+					'prose-headings:text-fg prose-p:text-fg prose-strong:text-fg prose-a:text-accent-strong',
+					'prose-code:text-fg prose-blockquote:text-fg-muted prose-li:text-fg',
+				),
+				style: `min-height:${typeof minHeight === 'number' ? `${minHeight}px` : minHeight}`,
+				// The contenteditable IS the textbox — naming the EditorContent wrapper
+				// instead would leave it nameless to assistive tech.
+				role: 'textbox',
+				'aria-multiline': 'true',
+				...(label ? { 'aria-labelledby': labelId } : {}),
+				...(ariaLabel ? { 'aria-label': ariaLabel } : {}),
+				'aria-expanded': paletteOpen ? 'true' : 'false',
+				...(paletteOpen ? { 'aria-controls': listboxId, 'aria-activedescendant': optionId(activeOption) } : {}),
+			},
+			// The `/` trigger fires on the actual character insert, so it covers every
+			// input method (IME, synthetic input, paste of a single char) with one path.
+			handleTextInput(view, from, _to, text) {
+				if (text !== '/' || slashRef.current) return false
+				if (!canOpenSlash(view.state, from)) return false
+				setSlash({ from, query: '', index: 0 })
+				return false // let the `/` type; onUpdate tracks it as the query prefix
+			},
+			handleKeyDown(_view, event) {
+				const s = slashRef.current
+				if (!s) return false
+				if (event.key === 'Escape') {
+					setSlash(null)
+					return true
+				}
+				const list = filterCommands(s.query)
+				// Nothing to pick — close and let the key through. Swallowing Enter and
+				// the arrows here is what used to strand the caret after `/api/v2`.
+				if (list.length === 0) {
+					setSlash(null)
+					return false
+				}
+				if (event.key === 'ArrowDown') {
+					setSlash({ ...s, index: (s.index + 1) % list.length })
+					return true
+				}
+				if (event.key === 'ArrowUp') {
+					setSlash({ ...s, index: (s.index - 1 + list.length) % list.length })
+					return true
+				}
+				if (event.key === 'Enter' || event.key === 'Tab') {
+					runSlashRef.current(list[Math.min(s.index, list.length - 1)])
+					return true
+				}
+				return false
+			},
+		},
+		onUpdate({ editor }) {
+			const html = editor.getHTML()
+			lastEmitted.current = html
+			onChangeRef.current(html)
+			// Track the `/query` the caret is typing after an open palette.
+			const s = slashRef.current
+			if (!s) return
+			const to = editor.state.selection.from
+			if (to < s.from) return setSlash(null)
+			const text = editor.state.doc.textBetween(s.from, to, '\n', '\n')
+			if (!text.startsWith('/')) return setSlash(null)
+			const query = text.slice(1)
+			// A block query is one word. Whitespace, or a query that matches nothing,
+			// means the user is writing prose — close rather than linger invisibly.
+			if (/\s/.test(query) || filterCommands(query).length === 0) return setSlash(null)
+			setSlash({ ...s, query, index: 0 })
+		},
+		// A pure caret move (click, arrow, select-all) fires no update — close the
+		// palette when the caret leaves the `/query` it belongs to.
+		onSelectionUpdate({ editor }) {
+			const s = slashRef.current
+			if (!s) return
+			const to = editor.state.selection.from
+			if (to < s.from || to > s.from + s.query.length + 1) setSlash(null)
+		},
+		onBlur() {
+			setSlash(null)
+		},
+	})
+
+	// Push EXTERNAL value changes into the editor (switching records, resets) without
+	// clobbering the caret on our own keystrokes.
+	useEffect(() => {
+		if (!editor) return
+		if (value !== lastEmitted.current && value !== editor.getHTML()) {
+			editor.commands.setContent(value || '', { emitUpdate: false })
+			lastEmitted.current = value
+		}
+	}, [value, editor])
+
+	// Tiptap's own re-render pass re-applies options with `editable` pinned to the
+	// live instance value, so the prop has to be pushed through this side channel.
+	useEffect(() => {
+		if (editor) editor.setEditable(editable)
+	}, [editable, editor])
+
+	const runSlash = useCallback(
+		(cmd: SlashCommand | undefined) => {
+			const s = slashRef.current
+			if (!editor || !s || !cmd) return
+			// Clamp: the doc can have shrunk under an open palette (an external
+			// setContent), which would make deleteRange throw on a stale position.
+			const size = editor.state.doc.content.size
+			const from = Math.min(Math.max(s.from, 0), size)
+			const to = Math.min(Math.max(editor.state.selection.from, from), size)
+			editor.chain().focus().deleteRange({ from, to }).run()
+			cmd.run(editor)
+			setSlash(null)
+		},
+		[editor, setSlash],
+	)
+	runSlashRef.current = runSlash
+
+	// Place the palette from the caret's CURRENT viewport coords, clamped into the
+	// viewport and flipped above the caret when it would overflow the bottom.
+	const placeMenu = useCallback(() => {
+		const s = slashRef.current
+		const el = menuRef.current
+		if (!editor || !s || !el) return
+		const size = editor.state.doc.content.size
+		if (s.from > size) return setSlash(null)
+		const caret = editor.view.coordsAtPos(s.from)
+		const rect = el.getBoundingClientRect()
+		const gap = 6
+		const edge = 8
+		let top = caret.bottom + gap
+		if (top + rect.height > window.innerHeight - edge) top = Math.max(edge, caret.top - gap - rect.height)
+		const left = Math.max(edge, Math.min(caret.left, window.innerWidth - rect.width - edge))
+		setMenuPos((prev) => (prev && prev.left === left && prev.top === top ? prev : { left, top }))
+	}, [editor, setSlash])
+
+	useLayoutEffect(() => {
+		if (slash) placeMenu()
+		else setMenuPos(null)
+	}, [slash, placeMenu])
+
+	// Fixed coordinates go stale the moment anything scrolls — including a scroll
+	// inside the editor itself, hence the capture-phase listener.
+	useEffect(() => {
+		if (!slash) return
+		const replace = () => placeMenu()
+		window.addEventListener('scroll', replace, true)
+		window.addEventListener('resize', replace)
+		return () => {
+			window.removeEventListener('scroll', replace, true)
+			window.removeEventListener('resize', replace)
+		}
+	}, [slash, placeMenu])
+
+	// Selection-driven mark states. Tiptap 3's useEditor deliberately does not
+	// re-render on transactions; this subscription is what keeps the toolbar honest.
+	const active = useEditorState({
+		editor,
+		selector: ({ editor }) =>
+			editor
+				? {
+						bold: editor.isActive('bold'),
+						italic: editor.isActive('italic'),
+						strike: editor.isActive('strike'),
+						highlight: editor.isActive('highlight'),
+						code: editor.isActive('code'),
+						link: editor.isActive('link'),
+						hasSelection: !editor.state.selection.empty,
+					}
+				: null,
+	})
+
+	const closeLink = useCallback(() => {
+		setLinkOpen(false)
+		setLinkError(null)
+		linkOpenRef.current = false
+	}, [])
+
+	// The link panel replaces the toolbar in place; a collapsed selection means the
+	// bubble menu is on its way out, so it must not strand an open panel.
+	useEffect(() => {
+		if (linkOpen && active && !active.hasSelection && !active.link) closeLink()
+	}, [linkOpen, active, closeLink])
+
+	useEffect(() => {
+		if (linkOpen) linkInputRef.current?.focus()
+	}, [linkOpen])
+
+	const openLink = () => {
+		if (!editor) return
+		setLinkDraft((editor.getAttributes('link').href as string | undefined) ?? '')
+		setLinkError(null)
+		linkOpenRef.current = true
+		setLinkOpen(true)
+	}
+
+	const applyLink = () => {
+		if (!editor) return
+		if (linkDraft.trim() === '') {
+			editor.chain().focus().extendMarkRange('link').unsetLink().run()
+			closeLink()
+			return
+		}
+		const url = safeLinkUrl(linkDraft)
+		if (!url) return setLinkError(SAFE_LINK_HINT)
+		editor.chain().focus().extendMarkRange('link').setLink({ href: url }).run()
+		closeLink()
+	}
+
+	return (
+		<div className={clsx('flex w-full flex-col gap-2', className)}>
+			{label ? (
+				<span id={labelId} className="text-small font-medium text-fg">
+					{label}
+				</span>
+			) : null}
+			<div className="relative rounded-lg border border-border bg-surface focus-within:border-brand-green">
+				{editor ? (
+					<BubbleMenu
+						editor={editor}
+						// Mirrors Tiptap's default (focus + non-empty selection), plus: stay up
+						// while the link panel owns focus, or typing a URL would dismiss itself.
+						shouldShow={({ editor, view, state, element }) => {
+							const inMenu = element.contains(document.activeElement)
+							if (!editor.isEditable || !(view.hasFocus() || inMenu)) return false
+							return linkOpenRef.current || !state.selection.empty
+						}}
+						className="flex flex-col gap-1 rounded-lg border border-border bg-surface-card p-1 shadow-md"
+					>
+						{linkOpen ? (
+							<>
+								<div className="flex items-center gap-1">
+									<input
+										ref={linkInputRef}
+										type="text"
+										value={linkDraft}
+										aria-label="Link URL"
+										aria-invalid={linkError ? true : undefined}
+										placeholder="https://, mailto:, /path"
+										className="h-8 w-56 rounded-md border border-border bg-surface px-2 text-small text-fg outline-none placeholder:text-fg-subtle focus:border-brand-green"
+										onChange={(e) => {
+											setLinkDraft(e.target.value)
+											setLinkError(null)
+										}}
+										onKeyDown={(e) => {
+											if (e.key === 'Enter') {
+												e.preventDefault()
+												applyLink()
+											}
+											if (e.key === 'Escape') {
+												e.preventDefault()
+												closeLink()
+												editor.chain().focus().run()
+											}
+										}}
+									/>
+									<button type="button" className={btn} onMouseDown={(e) => e.preventDefault()} onClick={applyLink} title="Apply link">
+										Apply
+									</button>
+									<button
+										type="button"
+										className={btn}
+										onMouseDown={(e) => e.preventDefault()}
+										onClick={() => {
+											closeLink()
+											editor.chain().focus().run()
+										}}
+										title="Cancel"
+									>
+										Cancel
+									</button>
+								</div>
+								{linkError ? <span className="px-1 pb-0.5 text-caption text-danger">{linkError}</span> : null}
+							</>
+						) : (
+							<div className="flex items-center gap-0.5">
+								{MARK_TOOLS.map((tool) => (
+									// preventDefault on mousedown keeps the editor selection while the button is clicked.
+									<button
+										key={tool.key}
+										type="button"
+										className={btn}
+										data-active={active?.[tool.key] ?? false}
+										aria-pressed={active?.[tool.key] ?? false}
+										onMouseDown={(e) => e.preventDefault()}
+										onClick={() => tool.run(editor)}
+										title={tool.title}
+									>
+										{tool.label}
+									</button>
+								))}
+								<button type="button" className={btn} data-active={active?.link ?? false} aria-pressed={active?.link ?? false} onMouseDown={(e) => e.preventDefault()} onClick={openLink} title="Link">
+									<LinkIcon />
+								</button>
+							</div>
+						)}
+					</BubbleMenu>
+				) : null}
+
+				<EditorContent editor={editor} />
+
+				{mounted && paletteOpen && slash
+					? createPortal(
+							<div
+								ref={menuRef}
+								id={listboxId}
+								role="listbox"
+								aria-label="Insert block"
+								className="fixed z-50 max-h-72 w-64 overflow-auto rounded-lg border border-border bg-surface-card p-1 shadow-md"
+								style={{ left: menuPos?.left ?? 0, top: menuPos?.top ?? 0, visibility: menuPos ? 'visible' : 'hidden' }}
+							>
+								{filtered.map((cmd, i) => (
+									// role=option must sit on a plain element — a <button> would override it.
+									// Focus stays in the editor; aria-activedescendant on the textbox drives AT.
+									<div
+										key={cmd.title}
+										id={optionId(i)}
+										role="option"
+										aria-selected={i === activeOption}
+										className={clsx('flex w-full cursor-pointer flex-col items-start rounded-md px-3 py-1.5 text-left', i === activeOption ? 'bg-surface-muted' : 'hover:bg-surface-muted')}
+										onMouseDown={(e) => e.preventDefault()}
+										onClick={() => runSlash(cmd)}
+									>
+										<span className="text-small text-fg">{cmd.title}</span>
+										<span className="text-caption text-fg-subtle">{cmd.hint}</span>
+									</div>
+								))}
+							</div>,
+							document.body,
+						)
+					: null}
+			</div>
+		</div>
+	)
+}

package/src/editor/index.ts

@@ -0,0 +1,3 @@
+// @podoba/react/editor — the opt-in Tiptap block editor. Kept behind a subpath so the
+// base @podoba/react bundle never pulls ProseMirror; importing here is the opt-in.
+export { BlockEditor, type BlockEditorProps } from './block-editor'

package/src/utils/safe-link-url.ts

@@ -0,0 +1,13 @@
+/** Allow-list for a link href: http(s), mailto, tel, or a relative/anchor path.
+ * The prefix allow-list inherently rejects `javascript:`/`data:`/`vbscript:`.
+ *
+ * Shared by every editor surface that takes a user-typed URL (RichTextEditor's
+ * toolbar, BlockEditor's link panel) so the allow-list can never drift between them.
+ * This is a UI guard, NOT the security boundary — sanitise HTML on the SERVER on write. */
+export function safeLinkUrl(raw: string): string | null {
+	const url = raw.trim()
+	return /^(https?:\/\/|mailto:|tel:|\/|#)/i.test(url) ? url : null
+}
+
+/** The message shown when {@link safeLinkUrl} rejects an input. */
+export const SAFE_LINK_HINT = 'Only http(s), mailto, tel, or relative (/, #) links are allowed.'

package/src/utils/uic.ts

@@ -82,6 +82,11 @@ const twMerge = extendTailwindMerge({
 			// Custom card/panel radius key (rounded-panel) → dedupes against other
 			// rounded-* utilities. xl/2xl are stock keys tailwind-merge already knows.
 			radius: ['panel'],
+			// Custom blur/shadow keys, so `backdrop-blur-modal-backdrop` dedupes against
+			// a caller's `backdrop-blur-lg` (Dialog size="full" does exactly this) and
+			// `shadow-modal-surface` isn't misread as a shadow COLOR.
+			blur: ['modal-backdrop'],
+			shadow: ['modal-surface'],
 		},
 	},
 })