@brett_lamy/docstream 1.7.0 → 1.9.0

package/src/demo/PathBreadcrumb.tsx

@@ -0,0 +1,367 @@
+/* The Code view's path header: a VS Code style breadcrumb for the active file.
+
+   One button per path part (the demo `src` first, then the folders, then the file), with a chevron
+   between them. A folder button opens a menu of that folder's siblings (everything in its parent
+   folder, the current one marked); the file button lists the files beside it. Picking a file selects
+   it, picking a folder opens the first file inside it. When the segments don't fit the container the
+   middle collapses into a single `…` that lists the hidden segments.
+
+   Plain accessible DOM (nav > ol, buttons, role="menu"), so docstream needs nothing beyond React.
+   The menu is portalled and `position: fixed`, so the viewer's overflow never clips it. The segment,
+   sibling and fit maths are pure and exported (see PathBreadcrumb.test.ts). */
+import {
+  useCallback,
+  useEffect,
+  useId,
+  useLayoutEffect,
+  useRef,
+  useState,
+  type CSSProperties,
+  type KeyboardEvent as ReactKeyboardEvent,
+} from "react"
+import { createPortal } from "react-dom"
+import { Check, ChevronRight, FileCode2, Folder } from "lucide-react"
+
+export interface CrumbSegment {
+  /** Unique within the breadcrumb. */
+  key: string
+  name: string
+  /** `src`: a part of the demo id (it names the demo's root); `dir`/`file`: a part of the file path. */
+  kind: "src" | "dir" | "file"
+  /** The folder or file path within the demo's file list. Empty for `src` segments. */
+  path: string
+}
+
+export interface CrumbEntry {
+  kind: "dir" | "file"
+  name: string
+  /** The entry's path within the demo's file list (empty for a demo root). */
+  path: string
+  /** The file to open when the entry is picked: itself for a file, the first file inside for a folder. */
+  target: string
+}
+
+/** The hidden stretch of a collapsed breadcrumb: segments `start` up to (not including) `end`. */
+export interface CrumbRange {
+  start: number
+  end: number
+}
+
+/** `src` parts, then the folders, then the file. */
+export function buildCrumbs(src: string, filePath: string): CrumbSegment[] {
+  const out: CrumbSegment[] = []
+  for (const name of src.split("/").filter(Boolean)) out.push({ key: `s${out.length}:${name}`, name, kind: "src", path: "" })
+  const parts = filePath.split("/").filter(Boolean)
+  parts.forEach((name, index) => {
+    const path = parts.slice(0, index + 1).join("/")
+    out.push({ key: `p:${path}`, name, kind: index === parts.length - 1 ? "file" : "dir", path })
+  })
+  return out
+}
+
+const parentOf = (path: string) => path.slice(0, Math.max(0, path.lastIndexOf("/")))
+
+/** The first file (in list order) at or below `folder`; `""` is the demo root. */
+export function firstFileIn(paths: readonly string[], folder: string): string | undefined {
+  return folder === "" ? paths[0] : paths.find((p) => p.startsWith(`${folder}/`))
+}
+
+/** The direct children of `folder` (`""` is the root): folders first, then files, each A to Z. */
+export function childEntries(paths: readonly string[], folder: string): CrumbEntry[] {
+  const prefix = folder === "" ? "" : `${folder}/`
+  const dirs = new Map<string, CrumbEntry>()
+  const files: CrumbEntry[] = []
+  for (const path of paths) {
+    if (!path.startsWith(prefix)) continue
+    const rest = path.slice(prefix.length)
+    const slash = rest.indexOf("/")
+    if (slash < 0) files.push({ kind: "file", name: rest, path, target: path })
+    else {
+      const name = rest.slice(0, slash)
+      if (!dirs.has(name)) dirs.set(name, { kind: "dir", name, path: prefix + name, target: path })
+    }
+  }
+  const byName = (a: CrumbEntry, b: CrumbEntry) => a.name.localeCompare(b.name, undefined, { numeric: true })
+  return [...[...dirs.values()].sort(byName), ...files.sort(byName)]
+}
+
+/** The menu a segment opens: the entries beside it. A `src` segment is the demo root, so it lists the
+ *  root; the file segment lists only the files in its folder. */
+export function siblingEntries(paths: readonly string[], segment: CrumbSegment): CrumbEntry[] {
+  if (segment.kind === "src") return childEntries(paths, "")
+  const entries = childEntries(paths, parentOf(segment.path))
+  return segment.kind === "file" ? entries.filter((e) => e.kind === "file") : entries
+}
+
+/** The menu behind `…`: the hidden segments, each opening like a folder picked in a sibling menu. */
+export function hiddenEntries(paths: readonly string[], segments: readonly CrumbSegment[], range: CrumbRange): CrumbEntry[] {
+  return segments.slice(range.start, range.end).flatMap((segment) => {
+    const target = firstFileIn(paths, segment.path)
+    return target === undefined ? [] : [{ kind: segment.kind === "file" ? ("file" as const) : ("dir" as const), name: segment.name, path: segment.path, target }]
+  })
+}
+
+/** Whether the active file is this entry, or inside this folder. */
+export function entryContains(entry: Pick<CrumbEntry, "path">, active: string): boolean {
+  return entry.path !== "" && (active === entry.path || active.startsWith(`${entry.path}/`))
+}
+
+/**
+ * Which middle segments to hide so the breadcrumb fits `available` px. `widths` are the full item
+ * widths (each includes its own chevron), `ellipsisWidth` the width of the `…` item. The first and
+ * last segments always stay; as many trailing segments as fit are kept; null when everything fits
+ * (or there is nothing to hide). With no room at all you still get first, `…`, last.
+ */
+export function collapseRange(widths: readonly number[], ellipsisWidth: number, available: number): CrumbRange | null {
+  const n = widths.length
+  if (n < 3) return null
+  if (widths.reduce((sum, w) => sum + w, 0) <= available) return null
+  let tail = 0
+  for (let end = n - 1; end >= 2; end--) {
+    tail += widths[end]
+    if (widths[0] + ellipsisWidth + tail > available) return { start: 1, end: Math.min(n - 1, end + 1) }
+  }
+  return { start: 1, end: 2 }
+}
+
+const useIsoLayoutEffect = typeof window === "undefined" ? useEffect : useLayoutEffect
+
+interface OpenMenu {
+  id: string
+  anchor: HTMLElement
+  label: string
+  entries: CrumbEntry[]
+}
+
+export interface PathBreadcrumbProps {
+  /** The demo id, shown as the leading segments. */
+  src: string
+  /** The active file's path. */
+  path: string
+  /** Every file path in the demo. */
+  paths: readonly string[]
+  onSelect: (path: string) => void
+  className?: string
+}
+
+export function PathBreadcrumb({ src, path, paths, onSelect, className }: PathBreadcrumbProps) {
+  const segments = buildCrumbs(src, path)
+  const nav = useRef<HTMLElement | null>(null)
+  const measure = useRef<HTMLOListElement | null>(null)
+  const [range, setRange] = useState<CrumbRange | null>(null)
+  const [menu, setMenu] = useState<OpenMenu | null>(null)
+  const menuId = useId()
+  const signature = segments.map((s) => s.name).join("/")
+
+  const fit = useCallback(() => {
+    const el = nav.current
+    const items = measure.current ? Array.from(measure.current.children) : []
+    if (!el || items.length < 2) return
+    const available = el.clientWidth
+    if (!available) return // hidden (display: none) or not laid out: keep what we have
+    const widths = items.map((item) => item.getBoundingClientRect().width)
+    const ellipsis = widths.pop() as number
+    const next = collapseRange(widths, ellipsis, available)
+    setRange((prev) => (prev?.start === next?.start && prev?.end === next?.end ? prev : next))
+  }, [])
+
+  useIsoLayoutEffect(fit, [fit, signature])
+  useEffect(() => {
+    const el = nav.current
+    if (!el || typeof ResizeObserver === "undefined") return
+    const observer = new ResizeObserver(fit)
+    observer.observe(el)
+    if (measure.current) observer.observe(measure.current)
+    return () => observer.disconnect()
+  }, [fit])
+
+  const close = useCallback((refocus: boolean) => {
+    setMenu((current) => {
+      if (current && refocus && current.anchor.isConnected) current.anchor.focus()
+      return null
+    })
+  }, [])
+
+  const choose = (entry: CrumbEntry) => {
+    setMenu(null)
+    onSelect(entry.target)
+    // The segments are re-keyed for the new file; park focus on its last segment.
+    requestAnimationFrame(() => nav.current?.querySelector<HTMLElement>("[data-crumb-last]")?.focus())
+  }
+
+  const open = (id: string, anchor: HTMLElement, label: string, entries: CrumbEntry[]) =>
+    setMenu((current) => (current?.id === id ? null : { id, anchor, label, entries }))
+
+  const visible: (CrumbSegment | "…")[] = range
+    ? [...segments.slice(0, range.start), "…", ...segments.slice(range.end)]
+    : segments
+
+  return (
+    <nav ref={nav} className={className ? `docs-demo-crumbs ${className}` : "docs-demo-crumbs"} aria-label="Breadcrumb">
+      <ol className="docs-demo-crumbs-list">
+        {visible.map((item, index) => {
+          const hidden = item === "…"
+          const id = hidden ? "…" : item.key
+          const last = !hidden && item.kind === "file"
+          const expanded = menu?.id === id
+          const label = hidden ? "Hidden path segments" : item.kind === "src" ? "Demo files" : `Files in ${parentOf(item.path) || "the demo root"}`
+          const entries = () => (hidden ? hiddenEntries(paths, segments, range as CrumbRange) : siblingEntries(paths, item))
+          return (
+            <li key={id} className="docs-demo-crumb-item" data-last={last || undefined}>
+              {index > 0 ? <ChevronRight className="docs-demo-crumb-sep" width={12} height={12} aria-hidden="true" /> : null}
+              <button
+                type="button"
+                className="docs-demo-crumb"
+                data-crumb-last={last || undefined}
+                data-current={last || undefined}
+                aria-current={last ? "page" : undefined}
+                aria-haspopup="menu"
+                aria-expanded={expanded}
+                aria-controls={expanded ? menuId : undefined}
+                aria-label={hidden ? "Show hidden path segments" : undefined}
+                title={hidden ? undefined : item.kind === "src" ? undefined : item.path}
+                onClick={(event) => open(id, event.currentTarget, label, entries())}
+                onKeyDown={(event) => {
+                  if (event.key !== "ArrowDown" && event.key !== "ArrowUp") return
+                  event.preventDefault()
+                  if (!expanded) setMenu({ id, anchor: event.currentTarget, label, entries: entries() })
+                }}
+              >
+                {last ? <FileCode2 width={13} height={13} aria-hidden="true" /> : null}
+                <span className="docs-demo-crumb-text">{hidden ? "…" : item.name}</span>
+              </button>
+            </li>
+          )
+        })}
+      </ol>
+      {/* The same segments, unclipped and unseen: measured to decide what fits. */}
+      <ol ref={measure} className="docs-demo-crumbs-list docs-demo-crumbs-measure" aria-hidden="true">
+        {[...segments.map((s) => s.name), "…"].map((name, index) => (
+          <li key={`${index}:${name}`} className="docs-demo-crumb-item">
+            {index > 0 ? <ChevronRight className="docs-demo-crumb-sep" width={12} height={12} /> : null}
+            <span className="docs-demo-crumb">
+              {index === segments.length - 1 ? <FileCode2 width={13} height={13} /> : null}
+              <span className="docs-demo-crumb-text">{name}</span>
+            </span>
+          </li>
+        ))}
+      </ol>
+      {menu ? <CrumbMenu key={menu.id} id={menuId} menu={menu} active={path} onPick={choose} onClose={close} /> : null}
+    </nav>
+  )
+}
+
+function CrumbMenu({ id, menu, active, onPick, onClose }: {
+  id: string
+  menu: OpenMenu
+  active: string
+  onPick: (entry: CrumbEntry) => void
+  onClose: (refocus: boolean) => void
+}) {
+  const ref = useRef<HTMLDivElement | null>(null)
+  const { anchor } = menu
+  const [at, setAt] = useState(() => {
+    const rect = anchor.getBoundingClientRect()
+    return { x: rect.left, y: rect.bottom + 4 }
+  })
+
+  // Place under the trigger, kept inside the viewport (flipped above when there is no room below),
+  // and focus the current entry.
+  useIsoLayoutEffect(() => {
+    const el = ref.current
+    if (!el) return
+    const rect = anchor.getBoundingClientRect()
+    const { width, height } = el.getBoundingClientRect()
+    const x = Math.max(8, Math.min(rect.left, window.innerWidth - width - 8))
+    const below = rect.bottom + 4
+    const y = below + height > window.innerHeight - 8 && rect.top - 4 - height >= 8 ? rect.top - 4 - height : below
+    setAt({ x, y })
+    const items = Array.from(el.querySelectorAll<HTMLElement>("[role=menuitem]"))
+    ;(items.find((item) => item.hasAttribute("data-current")) ?? items[0])?.focus({ preventScroll: true })
+  }, [anchor])
+
+  useEffect(() => {
+    const onDown = (event: PointerEvent) => {
+      const target = event.target as Node
+      if (!ref.current?.contains(target) && !anchor.contains(target)) onClose(false)
+    }
+    const onScroll = (event: Event) => {
+      if (!ref.current?.contains(event.target as Node)) onClose(false)
+    }
+    const dismiss = () => onClose(false)
+    document.addEventListener("pointerdown", onDown, true)
+    window.addEventListener("scroll", onScroll, true)
+    window.addEventListener("resize", dismiss)
+    return () => {
+      document.removeEventListener("pointerdown", onDown, true)
+      window.removeEventListener("scroll", onScroll, true)
+      window.removeEventListener("resize", dismiss)
+    }
+  }, [anchor, onClose])
+
+  const onKeyDown = (event: ReactKeyboardEvent<HTMLDivElement>) => {
+    const items = Array.from(event.currentTarget.querySelectorAll<HTMLElement>("[role=menuitem]"))
+    const index = items.indexOf(document.activeElement as HTMLElement)
+    let next = -1
+    if (event.key === "ArrowDown") next = (index + 1) % items.length
+    else if (event.key === "ArrowUp") next = (index - 1 + items.length) % items.length
+    else if (event.key === "Home") next = 0
+    else if (event.key === "End") next = items.length - 1
+    else if (event.key === "Escape") {
+      event.preventDefault()
+      event.stopPropagation()
+      onClose(true)
+      return
+    } else if (event.key === "Tab") {
+      onClose(true) // focus returns to the trigger; the Tab then moves on from there
+      return
+    } else if (event.key.length === 1 && !event.metaKey && !event.ctrlKey && !event.altKey) {
+      const key = event.key.toLowerCase()
+      const from = Math.max(index, 0)
+      for (let step = 1; step <= items.length; step++) {
+        const candidate = (from + step) % items.length
+        if (items[candidate].textContent?.trim().toLowerCase().startsWith(key)) {
+          next = candidate
+          break
+        }
+      }
+    }
+    if (next < 0) return
+    event.preventDefault()
+    items[next]?.focus()
+  }
+
+  const host = anchor.closest("[data-docstream], .docs-article") ?? document.body
+  return createPortal(
+    <div
+      ref={ref}
+      id={id}
+      role="menu"
+      aria-label={menu.label}
+      className="docs-demo-crumb-menu"
+      style={{ "--crumb-x": `${Math.round(at.x)}px`, "--crumb-y": `${Math.round(at.y)}px` } as CSSProperties}
+      onKeyDown={onKeyDown}
+    >
+      {menu.entries.map((entry) => {
+        const current = entryContains(entry, active)
+        return (
+          <button
+            key={`${entry.kind}:${entry.path}:${entry.name}`}
+            type="button"
+            role="menuitem"
+            tabIndex={-1}
+            className="docs-demo-crumb-option"
+            data-current={current || undefined}
+            aria-current={current || undefined}
+            onClick={() => onPick(entry)}
+          >
+            {entry.kind === "dir" ? <Folder width={13} height={13} aria-hidden="true" /> : <FileCode2 width={13} height={13} aria-hidden="true" />}
+            <span className="docs-demo-crumb-option-text">{entry.name}</span>
+            {current ? <Check className="docs-demo-crumb-check" width={13} height={13} aria-hidden="true" /> : null}
+          </button>
+        )
+      })}
+    </div>,
+    host,
+  )
+}

package/src/docs/DocsRenderer.tsx

@@ -31,6 +31,10 @@ import { OpenApiOperation } from "../openapi/OpenApiOperation"
 import { Mermaid } from "./Mermaid"
 import { HighlightedCode } from "./HighlightedCode"
 import { CitationSources, InlineReference } from "./reference"
+import { DocumentProperties } from "./DocumentProperties"
+import { TaskCheckbox, TaskStateChangeContext, type TaskStateChangeHandler } from "./TaskCheckbox"
+import { getTaskState } from "../gitbook/tasks"
+import { plainText } from "../gitbook/inline"
 
 type MathRenderer = (formula: string) => string
 let mathRenderer: MathRenderer | null = null
@@ -312,6 +316,7 @@ function Tabs({ block, liveRenderer, sourceRenderer }: { block: Extract<Block, {
 }
 
 function BlockView({ block, liveRenderer, sourceRenderer }: { block: Block } & Renderers) {
+  const onTaskStateChange = useContext(TaskStateChangeContext)
   switch (block.type) {
     case "paragraph":
       return (
@@ -476,8 +481,9 @@ function BlockView({ block, liveRenderer, sourceRenderer }: { block: Block } & R
       return (
         <Tag className={block.task ? "docs-tasklist" : undefined}>
           {block.items.map((item, i) => (
-            <li key={i}>
-              {block.task && <input type="checkbox" checked={!!item.checked} readOnly />}
+            <li key={i} data-task-state={block.task ? getTaskState(item) : undefined}>
+              {block.task && <TaskCheckbox state={getTaskState(item)} label={item.children.filter((b) => b.type === "paragraph").map((b) => b.type === "paragraph" ? plainText(b.children) : "").join(" ") || "Task"}
+                onChange={onTaskStateChange ? (state) => onTaskStateChange(item, state) : undefined} />}
               <Blocks blocks={item.children} inline liveRenderer={liveRenderer} sourceRenderer={sourceRenderer} />
             </li>
           ))}
@@ -582,6 +588,10 @@ function Blocks({ blocks, inline, liveRenderer, sourceRenderer }: { blocks: Bloc
 }
 
 export interface DocRenderOptions {
+  /** Make rendered task checkboxes interactive. Update the supplied item and re-render to persist a choice. */
+  onTaskStateChange?: TaskStateChangeHandler
+  /** Show the document's frontmatter as a property sheet (default true). */
+  documentProperties?: boolean | { defaultOpen?: boolean }
   /** Resolves `{% demo %}` blocks. Provided through context, so nested renderers inherit it. */
   demoResolver?: DemoResolver
   /**
@@ -605,8 +615,9 @@ export interface DocRenderOptions {
   pageActions?: boolean | DocPageActionsOptions
 }
 
-function withDemoContext({ demoResolver, demoRuntime, demoDependencies, demoVFS }: DocRenderOptions, children: ReactNode) {
+function withDemoContext({ demoResolver, demoRuntime, demoDependencies, demoVFS, onTaskStateChange }: DocRenderOptions, children: ReactNode) {
   let out = children
+  if (onTaskStateChange) out = <TaskStateChangeContext.Provider value={onTaskStateChange}>{out}</TaskStateChangeContext.Provider>
   if (demoVFS) out = <DocstreamDemoVFSContext.Provider value={demoVFS}>{out}</DocstreamDemoVFSContext.Provider>
   if (demoRuntime || demoDependencies) {
     out = <DemoRuntimeProvider runtime={demoRuntime} dependencies={demoDependencies}>{out}</DemoRuntimeProvider>
@@ -650,12 +661,15 @@ export function MarkdownContent({
   demoVFS,
   pageActions,
   className,
+  documentProperties = true,
+  onTaskStateChange,
 }: { markdown: string; className?: string } & Renderers & DocRenderOptions) {
   const doc = useMemo(() => parseMarkdown(markdown), [markdown])
   return withDemoContext(
-    { demoResolver, demoRuntime, demoDependencies, demoVFS },
+    { demoResolver, demoRuntime, demoDependencies, demoVFS, onTaskStateChange },
     <div data-docstream="" className={className}>
       <PageActionsBar markdown={markdown} options={pageActions} />
+      {documentProperties && doc.properties ? <DocumentProperties properties={doc.properties} defaultOpen={typeof documentProperties === "object" && documentProperties.defaultOpen} /> : null}
       <Blocks blocks={doc.children} liveRenderer={liveRenderer} sourceRenderer={sourceRenderer} />
       <CitationSources citations={doc.citations} />
     </div>,
@@ -672,11 +686,14 @@ export function DocsRenderer({
   demoVFS,
   pageActions,
   markdown,
+  documentProperties = true,
+  onTaskStateChange,
 }: { doc: DocumentNode; /** Source for page actions; defaults to `serializeMarkdown(doc)`. */ markdown?: string } & Renderers & DocRenderOptions) {
   return withDemoContext(
-    { demoResolver, demoRuntime, demoDependencies, demoVFS },
+    { demoResolver, demoRuntime, demoDependencies, demoVFS, onTaskStateChange },
     <article className="docs-article">
       <PageActionsBar markdown={markdown ?? (() => serializeMarkdown(doc))} options={pageActions} />
+      {documentProperties && doc.properties ? <DocumentProperties properties={doc.properties} defaultOpen={typeof documentProperties === "object" && documentProperties.defaultOpen} /> : null}
       <Blocks blocks={doc.children} liveRenderer={liveRenderer} sourceRenderer={sourceRenderer} />
       <CitationSources citations={doc.citations} />
     </article>,

package/src/docs/DocumentProperties.tsx

@@ -0,0 +1,84 @@
+import { useEffect, useState } from "react"
+import { ChevronRight, Plus, X } from "lucide-react"
+import { parseDocument, stringify } from "yaml"
+import type { DocumentPropertiesNode } from "../gitbook/ast"
+import { readDocumentProperties, removeDocumentProperty, setDocumentProperty, type DocumentPropertyValue } from "../gitbook/properties"
+
+export interface DocumentPropertiesProps {
+  properties: DocumentPropertiesNode
+  /** Omit for read-only properties. Edits retain the YAML document's comments and formatting. */
+  onChange?: (properties: DocumentPropertiesNode) => void
+  defaultOpen?: boolean
+  className?: string
+}
+
+function textValue(value: DocumentPropertyValue): string {
+  return value === null ? "" : typeof value === "object" ? stringify(value).trimEnd() : String(value)
+}
+
+function PropertyField({ name, value, onChange }: { name: string; value: DocumentPropertyValue; onChange: (value: DocumentPropertyValue) => void }) {
+  const rendered = textValue(value)
+  const [draft, setDraft] = useState(rendered)
+  const [error, setError] = useState<string>()
+  useEffect(() => { setDraft(rendered); setError(undefined) }, [rendered])
+  if (typeof value === "boolean") return <input type="checkbox" aria-label={name} checked={value} onChange={(event) => onChange(event.currentTarget.checked)} />
+  const complex = value !== null && typeof value === "object"
+  const multiline = complex || (typeof value === "string" && value.includes("\n"))
+  const change = (text: string) => {
+    setDraft(text)
+    if (!complex && typeof value !== "number") onChange(text)
+    else if (typeof value === "number" && text !== "" && Number.isFinite(Number(text))) onChange(Number(text))
+  }
+  const commit = () => {
+    if (!complex) return
+    try {
+      const yaml = parseDocument(draft)
+      if (yaml.errors.length) throw yaml.errors[0]
+      const next = yaml.toJS({ maxAliasCount: 100 }) as DocumentPropertyValue
+      JSON.stringify(next)
+      setError(undefined)
+      onChange(next)
+    } catch (cause) { setError(cause instanceof Error ? cause.message : String(cause)) }
+  }
+  return <div className="docs-property-field">
+    {multiline ? <textarea aria-label={name} value={draft} rows={Math.min(6, draft.split("\n").length)} aria-invalid={!!error || undefined}
+      onChange={(event) => change(event.currentTarget.value)} onBlur={commit} />
+      : <input type={typeof value === "number" ? "number" : "text"} aria-label={name} value={draft} placeholder="Empty"
+        onChange={(event) => change(event.currentTarget.value)} />}
+    {error ? <span role="alert" className="docs-properties-error">{error}</span> : null}
+  </div>
+}
+
+/** The shared, accessible property sheet used by the renderer and the editor. */
+export function DocumentProperties({ properties, onChange, defaultOpen = false, className }: DocumentPropertiesProps) {
+  const { values, error } = readDocumentProperties(properties)
+  const [adding, setAdding] = useState(false)
+  const [name, setName] = useState("")
+  const keys = Object.keys(values)
+  return <details className={["docs-document-properties", className].filter(Boolean).join(" ")} data-document-properties="" open={defaultOpen || undefined}>
+    <summary><ChevronRight size={13} aria-hidden="true" /><span>Properties</span><span className="docs-properties-count">{keys.length}</span></summary>
+    {error ? <div className="docs-properties-error" role="alert">
+      <p>{error}</p>
+      {onChange ? <textarea aria-label="Document properties YAML" value={properties.yaml} onChange={(event) => onChange({ ...properties, yaml: event.currentTarget.value })} />
+        : <pre>{properties.yaml}</pre>}
+    </div> : <>
+      <dl className="docs-properties-list">
+        {keys.map((key) => <div key={key} className="docs-property-row">
+          <dt>{key}</dt>
+          <dd>{onChange ? <PropertyField name={key} value={values[key]} onChange={(value) => onChange(setDocumentProperty(properties, key, value))} />
+            : <span className="docs-property-value">{values[key] === null ? "Empty" : typeof values[key] === "boolean" ? String(values[key]) : textValue(values[key])}</span>}</dd>
+          {onChange ? <button type="button" className="docs-property-remove" aria-label={`Remove ${key} property`} onClick={() => onChange(removeDocumentProperty(properties, key))}><X size={13} /></button> : null}
+        </div>)}
+      </dl>
+      {onChange ? adding ? <form className="docs-property-add" onSubmit={(event) => {
+        event.preventDefault()
+        const key = name.trim()
+        if (!key || Object.hasOwn(values, key)) return
+        onChange(setDocumentProperty(properties, key, "")); setName(""); setAdding(false)
+      }}><input aria-label="Property name" placeholder="Property name" autoFocus value={name} onChange={(event) => setName(event.currentTarget.value)} />
+        <button type="submit" disabled={!name.trim() || Object.hasOwn(values, name.trim())}>Add</button>
+        <button type="button" onClick={() => { setAdding(false); setName("") }}>Cancel</button></form>
+        : <button type="button" className="docs-property-add" onClick={() => setAdding(true)}><Plus size={13} />Add property</button> : null}
+    </>}
+  </details>
+}

package/src/docs/TaskCheckbox.tsx

@@ -0,0 +1,111 @@
+import { createContext, useEffect, useId, useRef, useState, type CSSProperties } from "react"
+import { createPortal } from "react-dom"
+import { Ban, Check, Circle, CircleCheck, CircleHelp, CircleMinus, CirclePause, CircleX, Clock3 } from "lucide-react"
+import type { ListItemNode, TaskState } from "../gitbook/ast"
+import { TASK_STATES } from "../gitbook/tasks"
+
+/** The icons used by the checkbox, tooltip and state picker. */
+export const TASK_STATE_ICONS = {
+  pending: Circle,
+  "in-progress": Clock3,
+  implemented: CircleHelp,
+  blocked: Ban,
+  parked: CirclePause,
+  refuted: CircleX,
+  verified: CircleCheck,
+  cancelled: CircleMinus,
+} as const
+
+export type TaskStateChangeHandler = (item: ListItemNode, state: TaskState) => void
+export const TaskStateChangeContext = createContext<TaskStateChangeHandler | undefined>(undefined)
+
+export interface TaskCheckboxProps {
+  state: TaskState
+  /** A normal click clears any marked state; clicking pending sets verified. */
+  onChange?: (state: TaskState) => void
+  label?: string
+  className?: string
+}
+
+const TOKENS = ["--foreground", "--muted-foreground", "--popover", "--popover-foreground", "--border", "--primary", "--accent", "--accent-foreground"]
+
+/** An accessible multi-state task checkbox. Right-click or Shift+F10 opens its keyboard-navigable state menu. */
+export function TaskCheckbox({ state, onChange, label = "Task", className }: TaskCheckboxProps) {
+  const input = useRef<HTMLInputElement>(null)
+  const menu = useRef<HTMLDivElement>(null)
+  const tipId = useId()
+  const [popup, setPopup] = useState<{ x: number; y: number; style: CSSProperties }>()
+  const [tip, setTip] = useState<{ x: number; y: number }>()
+  const hoverTimer = useRef<ReturnType<typeof setTimeout> | undefined>(undefined)
+  const meta = TASK_STATES.find((item) => item.id === state) ?? TASK_STATES[0]
+  const StateIcon = TASK_STATE_ICONS[meta.id]
+  const mixed = state !== "pending" && state !== "verified"
+  useEffect(() => { if (input.current) input.current.indeterminate = mixed }, [mixed, state])
+  useEffect(() => () => clearTimeout(hoverTimer.current), [])
+  const hideTip = () => { clearTimeout(hoverTimer.current); setTip(undefined) }
+  const showTip = () => {
+    clearTimeout(hoverTimer.current)
+    hoverTimer.current = setTimeout(() => {
+      const box = input.current?.getBoundingClientRect()
+      if (box) setTip({ x: Math.max(80, Math.min(window.innerWidth - 80, box.x + box.width / 2)), y: box.top > 36 ? box.top - 6 : box.bottom + 30 })
+    }, 400)
+  }
+  const open = (x?: number, y?: number) => {
+    if (!onChange || !input.current) return
+    hideTip()
+    const box = input.current.getBoundingClientRect()
+    const computed = getComputedStyle(input.current)
+    const style = Object.fromEntries(TOKENS.map((token) => [token, computed.getPropertyValue(token)])) as CSSProperties
+    style.fontFamily = computed.fontFamily
+    style.colorScheme = computed.colorScheme
+    setPopup({ x: Math.max(8, Math.min(window.innerWidth - 292, x ?? box.left)), y: Math.max(8, Math.min(window.innerHeight - 330, y ?? box.bottom + 4)), style })
+  }
+  const close = (restoreFocus = false) => { setPopup(undefined); if (restoreFocus) input.current?.focus({ preventScroll: true }) }
+  useEffect(() => {
+    if (!popup) return
+    menu.current?.querySelector<HTMLButtonElement>(`[data-state="${state}"]`)?.focus()
+    const outside = (event: PointerEvent) => { if (event.target instanceof Node && !menu.current?.contains(event.target)) close() }
+    const scroll = (event: Event) => { if (!(event.target instanceof Node && menu.current?.contains(event.target))) close() }
+    document.addEventListener("pointerdown", outside, true)
+    window.addEventListener("resize", scroll)
+    window.addEventListener("scroll", scroll, true)
+    return () => { document.removeEventListener("pointerdown", outside, true); window.removeEventListener("resize", scroll); window.removeEventListener("scroll", scroll, true) }
+  }, [popup])
+  return <span className={["docs-task-control", className].filter(Boolean).join(" ")} data-task-state={state}>
+    <input ref={input} type="checkbox" className="docs-task-checkbox" aria-label={`${label}: ${meta.label}`} aria-describedby={tip ? tipId : undefined}
+      aria-checked={mixed ? "mixed" : state === "verified"} aria-readonly={!onChange || undefined} aria-haspopup={onChange ? "menu" : undefined}
+      aria-expanded={onChange ? !!popup : undefined} checked={state === "verified"} readOnly={!onChange}
+      onClick={(event) => { if (!onChange) event.preventDefault() }}
+      onChange={() => { hideTip(); onChange?.(state === "pending" ? "verified" : "pending") }}
+      onMouseDown={(event) => { if (event.button === 0) event.preventDefault() }}
+      onMouseEnter={showTip} onMouseLeave={hideTip} onFocus={showTip} onBlur={hideTip}
+      onContextMenu={(event) => { if (onChange) { event.preventDefault(); open(event.clientX, event.clientY) } }}
+      onKeyDown={(event) => {
+        if (event.key === "ContextMenu" || (event.shiftKey && event.key === "F10")) { event.preventDefault(); open() }
+      }} />
+    <StateIcon className="docs-task-state-icon" size={20} strokeWidth={1.7} aria-hidden="true" data-state-icon={state} />
+    {tip && !popup ? createPortal(<div role="tooltip" id={tipId} className="docs-task-tooltip" style={{ left: tip.x, top: tip.y }}>{meta.label}</div>, document.body) : null}
+    {popup ? createPortal(<div ref={menu} role="menu" aria-label="Task state" className="docs-task-state-menu" style={{ ...popup.style, left: popup.x, top: popup.y }}
+      onContextMenu={(event) => event.preventDefault()}
+      onKeyDown={(event) => {
+        const items = [...(menu.current?.querySelectorAll<HTMLButtonElement>('[role="menuitemradio"]') ?? [])]
+        const current = items.indexOf(document.activeElement as HTMLButtonElement)
+        let next: number | undefined
+        if (event.key === "ArrowDown") next = (current + 1) % items.length
+        if (event.key === "ArrowUp") next = (current - 1 + items.length) % items.length
+        if (event.key === "Home") next = 0
+        if (event.key === "End") next = items.length - 1
+        if (event.key === "Escape" || event.key === "Tab") { event.preventDefault(); close(true) }
+        if (next !== undefined) { event.preventDefault(); items[next]?.focus() }
+      }}>
+      {TASK_STATES.map((item) => {
+        const Icon = TASK_STATE_ICONS[item.id]
+        return <button type="button" role="menuitemradio" key={item.id} data-state={item.id} aria-checked={item.id === state}
+          onClick={() => { onChange?.(item.id); close(true) }}>
+          <Icon size={19} strokeWidth={1.7} aria-hidden="true" data-state-icon={item.id} />
+          <span>{item.label}</span>{item.id === state ? <Check size={14} aria-hidden="true" /> : <span />}
+        </button>
+      })}
+    </div>, document.body) : null}
+  </span>
+}