cortena-ui 1.4.2 → 1.5.0

package/src/components/help-panel.tsx

@@ -0,0 +1,765 @@
+"use client";
+
+/**
+ * HelpPanel — the extension's own help, answered from its own functional
+ * document.
+ *
+ * §12 of how-to-create-a-cortena-extension, audit rule P-13. Every extension
+ * with a UI ships one: anchored bottom-right, collapsed by default, expanding
+ * into a right-hand vertical panel. It fills `AppShell`'s help slot, so the
+ * shell keeps the button, the open state and the corner geometry (the panel
+ * stops 12px above the cluster so the button that opened it stays clickable).
+ *
+ * ```tsx
+ * <AppShell
+ *   extension={{ id: "tasks", name: "Tasks" }}
+ *   user={user}
+ *   help={{ source: "/docs/functional.md" }}
+ *   helpPanel={helpPanelSlot({
+ *     // lazy: the document is fetched the first time help is opened
+ *     source: () => fetch("/docs/functional.md").then((r) => r.text()),
+ *     documentUrl: "/docs/functional.md",
+ *     context: location.pathname,
+ *   })}
+ * >
+ *   <HelpHotkeys />
+ *   …
+ * </AppShell>
+ * ```
+ *
+ * It is NOT the agent pop-up (§17) and the two must not be merged. Help
+ * answers *about* the extension from a document; the agent *acts* in the
+ * extension through its tools. Same corner, different affordances.
+ *
+ * Giving the functional document a runtime consumer is the whole point: a
+ * stale document becomes a visibly wrong help panel rather than a file nobody
+ * opens. So the panel renders the document itself — outline from its headings,
+ * search over its text, `#heading` deep links, and "open in new tab" for the
+ * whole thing — rather than a hand-written copy of it that can drift.
+ *
+ * `context` is the current route. On open the panel jumps to the section that
+ * route is about, matched against the front matter's `routes:` map first and
+ * against the headings second, so help opens on the part of the document the
+ * user is looking at rather than at the top of it.
+ *
+ * Lives on the `cortena-ui/markdown` entry: it renders markdown, so it carries
+ * react-markdown, and no extension that only draws a Button may pay for that.
+ */
+
+import { ExternalLink, Search, X } from "lucide-react";
+import * as React from "react";
+import { Markdown, markdownSanitizeSchema } from "@/components/markdown";
+import { Spinner } from "@/components/spinner";
+import { cn } from "@/lib/cn";
+
+/* ── the document ────────────────────────────────────────────────────────── */
+
+/**
+ * The markdown, or a loader for it. A function is called the first time the
+ * panel is opened, which is what keeps a long document out of the initial
+ * payload; keep its identity stable (module scope, or `useCallback`) or it is
+ * called again on every parent render.
+ */
+export type HelpSource = string | (() => Promise<string>);
+
+export interface HelpSection {
+  /** Slug of the heading — the `#anchor` the outline links to. `""` for the preamble. */
+  id: string;
+  /** 1–6 for a heading; 0 for the text before the first heading. */
+  depth: number;
+  /** Heading text with inline markdown removed. */
+  title: string;
+  /** The heading and everything under it, verbatim, so it can be re-rendered alone. */
+  markdown: string;
+}
+
+export interface HelpRoute {
+  /** A route the extension serves, e.g. `/board`. */
+  route: string;
+  /** The section it is about: a heading, or that heading's slug. */
+  target: string;
+}
+
+export interface HelpDocument {
+  /** `title:` from the front matter, else the first `#` heading. */
+  title?: string;
+  /** Every scalar key in the front matter. */
+  frontMatter: Record<string, string>;
+  /** The `route:` / `routes:` block, longest route first. */
+  routes: HelpRoute[];
+  /** The document without its front matter. */
+  body: string;
+  sections: HelpSection[];
+}
+
+/** Lowercase, punctuation to hyphens. The same slug the rendered heading gets. */
+function slugify(text: string): string {
+  const slug = text
+    .toLowerCase()
+    .normalize("NFKD")
+    .replace(/[\u0300-\u036f]/g, "")
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  return slug || "section";
+}
+
+/** Slugs in document order, with `-1`, `-2` for repeats, as GitHub numbers them. */
+function createSlugger(): (text: string) => string {
+  const seen = new Map<string, number>();
+  return (text) => {
+    const base = slugify(text);
+    const n = seen.get(base) ?? 0;
+    seen.set(base, n + 1);
+    return n === 0 ? base : `${base}-${n}`;
+  };
+}
+
+/**
+ * Heading text with the inline markdown taken off, so the outline entry and
+ * the slug match what the rendered heading actually says. Without this a
+ * `## [Reports](/reports)` heading slugs to `reports-reports` in the outline
+ * and to `reports` in the document, and the deep link lands nowhere.
+ */
+function plainText(md: string): string {
+  return md
+    .replace(/`([^`]*)`/g, "$1")
+    .replace(/!\[([^\]]*)\]\([^)]*\)/g, "$1")
+    .replace(/\[([^\]]*)\]\([^)]*\)/g, "$1")
+    .replace(/<[^>]*>/g, "")
+    .replace(/[*_~]+/g, "")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+const FRONT_MATTER = /^---[ \t]*\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n|$)/;
+const HEADING = /^(#{1,6})[ \t]+(.+?)[ \t]*#*[ \t]*$/;
+const FENCE = /^[ \t]*(```|~~~)/;
+
+function unquote(value: string): string {
+  const trimmed = value.trim();
+  const quoted = /^(['"])([\s\S]*)\1$/.exec(trimmed);
+  return quoted ? (quoted[2] ?? "") : trimmed;
+}
+
+/**
+ * Parse the document once: front matter, then sections split at ATX headings.
+ *
+ * Exported because the route map and the outline are worth asserting on
+ * without a browser, and because an extension that wants its own navigation
+ * over the same document should read it the same way rather than write a
+ * second parser.
+ */
+export function parseHelpDocument(source: string): HelpDocument {
+  const matter = FRONT_MATTER.exec(source);
+  const body = matter ? source.slice(matter[0].length) : source;
+
+  const frontMatter: Record<string, string> = {};
+  const routes: HelpRoute[] = [];
+  if (matter) {
+    let inRoutes = false;
+    for (const line of (matter[1] ?? "").split(/\r?\n/)) {
+      if (!line.trim() || line.trim().startsWith("#")) continue;
+      const indented = /^[ \t]+/.test(line);
+      const pair = /^[ \t]*([^:]+):[ \t]*(.*)$/.exec(line);
+      if (!pair) continue;
+      const key = unquote(pair[1] ?? "");
+      const value = unquote(pair[2] ?? "");
+      if (inRoutes && indented) {
+        // `  /board: Working the board` — a route, and the section it is about.
+        if (key && value) routes.push({ route: key, target: value });
+        continue;
+      }
+      inRoutes = !indented && (key === "route" || key === "routes") && value === "";
+      if (!inRoutes && !indented && key) frontMatter[key] = value;
+    }
+  }
+  // Longest route first, so `/reports/exports` wins over `/reports`.
+  routes.sort((a, b) => b.route.length - a.route.length);
+
+  const slug = createSlugger();
+  const sections: HelpSection[] = [];
+  let current: HelpSection | undefined;
+  let fence: string | undefined;
+  for (const line of body.split(/\r?\n/)) {
+    const fenced = FENCE.exec(line);
+    if (fenced) {
+      const mark = fenced[1] ?? "";
+      fence = fence === undefined ? mark : fence === mark ? undefined : fence;
+    }
+    const heading = fence === undefined ? HEADING.exec(line) : null;
+    if (heading) {
+      const title = plainText(heading[2] ?? "");
+      current = { id: slug(title), depth: (heading[1] ?? "").length, title, markdown: "" };
+      sections.push(current);
+    } else if (!current) {
+      // Everything before the first heading is one unnamed section, so a
+      // search that matches the opening paragraph still shows it.
+      current = { id: "", depth: 0, title: "", markdown: "" };
+      sections.push(current);
+    }
+    current.markdown += `${line}\n`;
+  }
+  const preamble = sections[0];
+  if (preamble && preamble.depth === 0 && !preamble.markdown.trim()) sections.shift();
+
+  const title = frontMatter.title ?? sections.find((s) => s.depth === 1)?.title;
+  return { title, frontMatter, routes, body, sections };
+}
+
+function normalizeRoute(route: string): string {
+  const path = (route.split(/[?#]/)[0] ?? "").trim().toLowerCase();
+  return path.length > 1 ? path.replace(/\/+$/, "") : path;
+}
+
+function findSection(doc: HelpDocument, target: string): HelpSection | undefined {
+  const wanted = target.trim().toLowerCase();
+  return doc.sections.find(
+    (s) =>
+      s.id !== "" &&
+      (s.id === wanted || s.id === slugify(wanted) || s.title.toLowerCase() === wanted),
+  );
+}
+
+/**
+ * The section a route is about: the front matter's map first (exact, then the
+ * longest matching prefix, so `/tasks/123` finds `/tasks`), then a heading
+ * whose slug is the route or its last segment.
+ */
+export function resolveHelpTarget(doc: HelpDocument, context?: string): string | undefined {
+  if (!context) return undefined;
+  const path = normalizeRoute(context);
+  if (!path) return undefined;
+
+  for (const { route, target } of doc.routes) {
+    const candidate = normalizeRoute(route);
+    const prefix = candidate === "/" ? "/" : `${candidate}/`;
+    if (candidate === path || path.startsWith(prefix)) {
+      const section = findSection(doc, target);
+      if (section) return section.id;
+    }
+  }
+  const segments = path.split("/").filter(Boolean);
+  for (const candidate of [path, segments.at(-1)]) {
+    if (!candidate) continue;
+    const section = findSection(doc, candidate);
+    if (section) return section.id;
+  }
+  return undefined;
+}
+
+/* ── heading anchors ─────────────────────────────────────────────────────── */
+
+interface HastNode {
+  type?: string;
+  tagName?: string;
+  value?: string;
+  properties?: Record<string, unknown>;
+  children?: HastNode[];
+}
+
+function nodeText(node: HastNode): string {
+  if (node.type === "text") return node.value ?? "";
+  return (node.children ?? []).map(nodeText).join("");
+}
+
+/**
+ * Give every heading the slug the outline links to. It runs AFTER sanitize —
+ * the ids are ours, not the document's, so they are added to trusted nodes
+ * rather than smuggled through the sanitizer.
+ */
+function rehypeHelpAnchors() {
+  return (tree: HastNode) => {
+    const slug = createSlugger();
+    const walk = (node: HastNode) => {
+      const tag = node.tagName ?? "";
+      if (/^h[1-6]$/.test(tag)) {
+        node.properties = { ...node.properties, id: slug(plainText(nodeText(node))) };
+      }
+      for (const child of node.children ?? []) walk(child);
+    };
+    walk(tree);
+  };
+}
+
+/* ── keyboard ────────────────────────────────────────────────────────────── */
+
+function isTypingTarget(target: EventTarget | null): boolean {
+  if (!(target instanceof HTMLElement)) return false;
+  if (target.isContentEditable) return true;
+  const tag = target.tagName;
+  if (tag === "TEXTAREA" || tag === "SELECT") return true;
+  if (tag !== "INPUT") return target.closest('[role="textbox"], [role="searchbox"]') !== null;
+  const type = (target as HTMLInputElement).type;
+  return type !== "checkbox" && type !== "radio" && type !== "button" && type !== "submit";
+}
+
+/**
+ * The shell owns the open state and exposes only its button, so with no
+ * `onOpen` the shortcut presses exactly the control a pointer would. Already
+ * open (the button says so) means `?` is a no-op rather than a close.
+ */
+function pressHelpButton(): void {
+  const button = document.querySelector<HTMLElement>('[data-slot="help-button"]');
+  if (!button || button.getAttribute("aria-expanded") === "true") return;
+  button.click();
+}
+
+export interface HelpHotkeysOptions {
+  /** Whether the panel is open. Escape only closes when it is. */
+  open?: boolean;
+  /** Defaults to pressing the shell's help button. */
+  onOpen?: () => void;
+  onClose?: () => void;
+  /** Turn the shortcuts off without unmounting. */
+  disabled?: boolean;
+}
+
+/**
+ * Escape closes, `?` opens — the second only when focus is not in an input,
+ * because `?` is a character before it is a shortcut and stealing it from
+ * someone typing a question into a filter box is worse than having no
+ * shortcut at all.
+ *
+ * `HelpPanel` calls this itself for Escape. Mount `<HelpHotkeys />` in the
+ * shell's children for `?`, which has to be listening while the panel is
+ * closed and therefore unmounted.
+ */
+export function useHelpHotkeys({ open, onOpen, onClose, disabled }: HelpHotkeysOptions = {}): void {
+  const state = React.useRef({ open, onOpen, onClose });
+  state.current = { open, onOpen, onClose };
+  React.useEffect(() => {
+    if (disabled) return;
+    const onKeyDown = (event: KeyboardEvent) => {
+      const { open: isOpen, onOpen: openIt, onClose: closeIt } = state.current;
+      if (event.defaultPrevented || event.metaKey || event.ctrlKey || event.altKey) return;
+      if (event.key === "Escape") {
+        if (isOpen && closeIt) closeIt();
+        return;
+      }
+      if (event.key !== "?" || isOpen || isTypingTarget(event.target)) return;
+      event.preventDefault();
+      (openIt ?? pressHelpButton)();
+    };
+    document.addEventListener("keydown", onKeyDown);
+    return () => document.removeEventListener("keydown", onKeyDown);
+  }, [disabled]);
+}
+
+export interface HelpHotkeysProps extends HelpHotkeysOptions {}
+
+/** `useHelpHotkeys` as a component, for a shell whose children are markup. */
+export function HelpHotkeys(props: HelpHotkeysProps): null {
+  useHelpHotkeys(props);
+  return null;
+}
+
+/**
+ * `documentUrl` when it is safe to hang off an `href`, `undefined` otherwise.
+ *
+ * A relative URL is resolved against the current page first, so "/docs/x.md"
+ * — the ordinary case — passes on any http(s) origin and is not special-cased
+ * into a hole. `javascript:`, `data:`, `blob:` and `vbscript:` all fall out of
+ * the same allow-list rather than each needing to be thought of.
+ */
+export function httpDocumentUrl(documentUrl: string | undefined): string | undefined {
+  if (!documentUrl) return undefined;
+  try {
+    const base = typeof location === "undefined" ? undefined : location.href;
+    const { protocol } = base === undefined ? new URL(documentUrl) : new URL(documentUrl, base);
+    return protocol === "http:" || protocol === "https:" ? documentUrl : undefined;
+  } catch {
+    // Not a URL. No anchor at all beats an anchor that goes nowhere.
+    return undefined;
+  }
+}
+
+/* ── the panel ───────────────────────────────────────────────────────────── */
+
+export interface HelpPanelProps extends Omit<React.ComponentProps<"div">, "title" | "onSelect"> {
+  /** The functional document, as markdown. A function is loaded on first open. */
+  source: HelpSource;
+  /** From the shell's help slot. `false` renders nothing and loads nothing. */
+  open?: boolean;
+  /** Closes the panel: the header button and Escape. */
+  onClose?: () => void;
+  /** The current route. Opens the panel on the section that route is about. */
+  context?: string;
+  /** Header title. Defaults to the front matter's `title:`, then the first `#`. */
+  title?: string;
+  /**
+   * Where "open in new tab" goes — the document's own URL, so the tab can be
+   * shared. Without one the panel opens the text it already has.
+   *
+   * **http(s) only.** The value reaches an `href` the user clicks, and the
+   * panel's source is the extension's functional document, which an extension
+   * may well be fetching from somewhere configurable. A `javascript:` URL in
+   * that slot is script execution one click away, and `data:` opens a document
+   * of the author's choosing on a tab the user believes is the help page.
+   */
+  documentUrl?: string;
+  /** Deepest heading level in the outline. 3 by default; 6 shows every heading. */
+  outlineDepth?: number;
+  /** Start with the search box filled. For the guide and for tests. */
+  defaultQuery?: string;
+}
+
+const headerButton = [
+  "inline-flex size-8 shrink-0 items-center justify-center rounded-[var(--ds-radius-md)]",
+  "text-[color:var(--ds-muted-foreground)] outline-none",
+  "transition-colors duration-[var(--ds-duration-fast)] ease-[var(--ds-ease-out)]",
+  "hover:bg-[var(--ds-hover)] hover:text-[color:var(--ds-foreground)]",
+  "focus-visible:ring-2 focus-visible:ring-[var(--ds-ring)]",
+  "[&_svg]:size-4",
+].join(" ");
+
+/**
+ * Documents already loaded, by the loader that produced them.
+ *
+ * `helpPanelSlot` returns `null` while closed, so closing the panel UNMOUNTS
+ * it and takes its state with it. Every reopen therefore re-ran the loader:
+ * on a `fetch` that is a network round trip per open, and on a slow one the
+ * panel shows a skeleton for a document the user read a minute ago. The cache
+ * is keyed by the loader itself and held weakly, so a caller that memoises its
+ * loader — the documented shape — gets the document back instantly, and one
+ * that builds a new closure each render is simply not cached rather than
+ * leaking.
+ */
+const loadedDocuments = /* @__PURE__ */ new WeakMap<object, string>();
+
+function HelpPanel({
+  source,
+  open = true,
+  onClose,
+  context,
+  title,
+  documentUrl,
+  outlineDepth = 3,
+  defaultQuery = "",
+  className,
+  ...props
+}: HelpPanelProps) {
+  const [text, setText] = React.useState<string | undefined>(
+    typeof source === "string" ? source : loadedDocuments.get(source),
+  );
+  const [failed, setFailed] = React.useState(false);
+  const [query, setQuery] = React.useState(defaultQuery);
+  const [activeId, setActiveId] = React.useState<string>();
+  const bodyRef = React.useRef<HTMLDivElement>(null);
+  const panelRef = React.useRef<HTMLDivElement>(null);
+
+  useHelpHotkeys({ open, onClose });
+
+  /**
+   * Focus moves into the panel when it opens.
+   *
+   * The shell's help button stays where it is, so without this, focus is
+   * still on the button: Escape works (the handler is on the document) but
+   * Tab walks the page BEHIND the panel, and a screen reader announces
+   * nothing at all — the panel is simply not where the user is. The search
+   * box is the target, because searching is what the panel is for.
+   */
+  React.useEffect(() => {
+    if (!open) return;
+    // After paint, so the element exists and Base UI's own focus work — the
+    // pop-up, a dialog the panel is rendered beside — has settled.
+    const frame = requestAnimationFrame(() => {
+      const root = panelRef.current;
+      if (!root || root.contains(document.activeElement)) return;
+      // `preventScroll`: focusing scrolls an element into view by default, and
+      // the panel has just opened on the section the current route is about.
+      // Scrolling it back to the top would undo exactly that.
+      root
+        .querySelector<HTMLElement>('[data-slot="help-panel-search-input"]')
+        ?.focus({ preventScroll: true });
+    });
+    return () => cancelAnimationFrame(frame);
+  }, [open]);
+
+  React.useEffect(() => {
+    if (!open) return;
+    if (typeof source === "string") {
+      setText(source);
+      setFailed(false);
+      return;
+    }
+    const cached = loadedDocuments.get(source);
+    if (cached !== undefined) {
+      setText(cached);
+      setFailed(false);
+      return;
+    }
+    let cancelled = false;
+    setFailed(false);
+    source().then(
+      (loaded) => {
+        loadedDocuments.set(source, loaded);
+        if (!cancelled) setText(loaded);
+      },
+      () => {
+        if (!cancelled) setFailed(true);
+      },
+    );
+    return () => {
+      cancelled = true;
+    };
+  }, [open, source]);
+
+  const doc = React.useMemo(() => parseHelpDocument(text ?? ""), [text]);
+  const needle = query.trim().toLowerCase();
+  const matches = React.useMemo(
+    () =>
+      needle
+        ? doc.sections.filter((section) => section.markdown.toLowerCase().includes(needle))
+        : doc.sections,
+    [doc, needle],
+  );
+  const markdown = needle ? matches.map((section) => section.markdown).join("\n") : doc.body;
+  const outline = matches.filter((s) => s.depth >= 1 && s.depth <= outlineDepth);
+
+  // Where the last programmatic scroll left the panel, so a re-align after the
+  // document reflows can tell "nobody has scrolled since" from "the user has".
+  const scrolledTo = React.useRef<number | undefined>(undefined);
+  const scrollTo = React.useCallback((id: string, onlyIfUntouched = false) => {
+    const scroller = bodyRef.current;
+    const heading = scroller?.querySelector<HTMLElement>(`#${CSS.escape(id)}`);
+    if (!scroller || !heading) return false;
+    if (onlyIfUntouched && scrolledTo.current !== scroller.scrollTop) return false;
+    // Not `scrollIntoView`: the panel is a scroller inside a fixed aside, and
+    // scrollIntoView would scroll the page behind it as well.
+    scroller.scrollTop += heading.getBoundingClientRect().top - scroller.getBoundingClientRect().top;
+    scrolledTo.current = scroller.scrollTop;
+    setActiveId(id);
+    return true;
+  }, []);
+
+  // Open on the section the current route is about, once the document is here.
+  const target = React.useMemo(() => resolveHelpTarget(doc, context), [doc, context]);
+  React.useEffect(() => {
+    if (!open || !target || needle) return;
+    let cancelled = false;
+    scrollTo(target);
+    // Twice more, and only while the user has not scrolled since: the markdown
+    // mounts in the same commit, and the display face lands after that. A
+    // heading that grows 4px once the font arrives leaves the jump short of
+    // the section it was supposed to open on.
+    const again = () => {
+      if (!cancelled) scrollTo(target, scrolledTo.current !== undefined);
+    };
+    const frame = requestAnimationFrame(again);
+    void document.fonts?.ready.then(again);
+    return () => {
+      cancelled = true;
+      cancelAnimationFrame(frame);
+    };
+  }, [open, target, needle, scrollTo]);
+
+  // "Open in new tab" without a URL still has the text, so it opens that. A
+  // `documentUrl` this panel refused counts as not having one.
+  const safeDocumentUrl = httpDocumentUrl(documentUrl);
+  const [fallbackUrl, setFallbackUrl] = React.useState<string>();
+  React.useEffect(() => {
+    if (safeDocumentUrl || text === undefined) return;
+    const url = URL.createObjectURL(new Blob([text], { type: "text/markdown;charset=utf-8" }));
+    setFallbackUrl(url);
+    return () => URL.revokeObjectURL(url);
+  }, [safeDocumentUrl, text]);
+  // The blob: fallback is ours — made here from text already in the panel —
+  // so it is not put through the same check.
+  const href = safeDocumentUrl ?? fallbackUrl;
+
+  if (!open) return null;
+
+  const heading = title ?? doc.title ?? "Help";
+  const loading = text === undefined && !failed;
+
+  return (
+    <div
+      ref={panelRef}
+      data-slot="help-panel"
+      data-loading={loading || undefined}
+      className={cn(
+        "flex h-full min-h-0 w-full flex-col overflow-hidden",
+        "bg-[var(--ds-card)] text-[color:var(--ds-foreground)]",
+        className,
+      )}
+      {...props}
+    >
+      <header
+        data-slot="help-panel-header"
+        className="flex shrink-0 items-center gap-2 border-b border-[var(--ds-border-subtle)] px-4 py-3"
+      >
+        <h2
+          data-slot="help-panel-title"
+          className={cn(
+            "min-w-0 flex-1 truncate font-display font-bold",
+            "text-[length:var(--ds-text-body-sm)] leading-[var(--ds-text-body-sm--line-height)]",
+            "text-[color:var(--ds-foreground)]",
+          )}
+        >
+          {heading}
+        </h2>
+        {href ? (
+          <a
+            data-slot="help-panel-open-full"
+            href={href}
+            target="_blank"
+            rel="noreferrer"
+            aria-label="Open the full document in a new tab"
+            className={headerButton}
+          >
+            <ExternalLink aria-hidden />
+          </a>
+        ) : null}
+        {onClose ? (
+          <button
+            type="button"
+            data-slot="help-panel-close"
+            aria-label="Close help"
+            onClick={onClose}
+            className={headerButton}
+          >
+            <X aria-hidden />
+          </button>
+        ) : null}
+      </header>
+
+      <div
+        data-slot="help-panel-search"
+        className="shrink-0 border-b border-[var(--ds-border-subtle)] px-4 py-3"
+      >
+        <div className="relative">
+          <Search
+            aria-hidden
+            className="pointer-events-none absolute top-1/2 left-2.5 size-4 -translate-y-1/2 text-[color:var(--ds-text-tertiary)]"
+          />
+          <input
+            type="search"
+            data-slot="help-panel-search-input"
+            aria-label={`Search ${heading}`}
+            placeholder="Search this document"
+            value={query}
+            onChange={(event) => setQuery(event.target.value)}
+            className={cn(
+              "h-9 w-full rounded-[var(--ds-radius-md)] border border-[var(--ds-border)]",
+              "bg-[var(--ds-muted)] py-2 pr-3 pl-8",
+              "text-[length:var(--ds-text-caption-lg)] leading-[var(--ds-text-caption-lg--line-height)]",
+              "text-[color:var(--ds-foreground)] placeholder:text-[color:var(--ds-text-tertiary)]",
+              "transition-[border-color,box-shadow] duration-[var(--ds-duration-fast)] ease-[var(--ds-ease-out)]",
+              "outline-none hover:border-[var(--ds-border-strong)]",
+              "focus-visible:border-[var(--ds-ring)] focus-visible:ring-[3px] focus-visible:ring-[var(--ds-ring)]/40",
+              "[&::-webkit-search-cancel-button]:hidden",
+            )}
+          />
+        </div>
+      </div>
+
+      {outline.length > 0 ? (
+        <nav
+          data-slot="help-panel-outline"
+          aria-label={`${heading} sections`}
+          className="max-h-40 shrink-0 overflow-y-auto border-b border-[var(--ds-border-subtle)] px-2 py-2"
+        >
+          <ol className="flex flex-col">
+            {outline.map((section) => (
+              <li key={section.id}>
+                <a
+                  data-slot="help-panel-outline-item"
+                  data-depth={section.depth}
+                  data-active={section.id === activeId || undefined}
+                  href={`#${section.id}`}
+                  onClick={(event) => {
+                    // The anchor is a real deep link — copyable, and it works
+                    // in a new tab — but inside an SPA the panel scrolls
+                    // itself rather than handing the route a hash.
+                    event.preventDefault();
+                    scrollTo(section.id);
+                  }}
+                  className={cn(
+                    "block truncate rounded-[var(--ds-radius-sm)] px-2 py-1 no-underline",
+                    "text-[length:var(--ds-text-caption)] leading-[var(--ds-text-caption--line-height)]",
+                    "text-[color:var(--ds-muted-foreground)] outline-none",
+                    "transition-colors duration-[var(--ds-duration-fast)] ease-[var(--ds-ease-out)]",
+                    "hover:bg-[var(--ds-hover)] hover:text-[color:var(--ds-foreground)]",
+                    "focus-visible:ring-2 focus-visible:ring-[var(--ds-ring)]",
+                    "data-[active]:bg-[var(--ds-primary-soft)] data-[active]:text-[color:var(--ds-primary-soft-foreground)]",
+                    section.depth === 2 && "pl-5",
+                    section.depth >= 3 && "pl-8",
+                  )}
+                >
+                  {section.title}
+                </a>
+              </li>
+            ))}
+          </ol>
+        </nav>
+      ) : null}
+
+      <div
+        ref={bodyRef}
+        data-slot="help-panel-body"
+        className="min-h-0 flex-1 overflow-y-auto px-4 py-3"
+      >
+        {loading ? (
+          <div data-slot="help-panel-loading" className="flex items-center gap-2 py-6">
+            <Spinner />
+            <span className="text-[length:var(--ds-text-caption-lg)] text-[color:var(--ds-muted-foreground)]">
+              Loading help…
+            </span>
+          </div>
+        ) : failed ? (
+          <p
+            data-slot="help-panel-error"
+            className="py-6 text-[length:var(--ds-text-caption-lg)] text-[color:var(--ds-destructive)]"
+          >
+            The help document could not be loaded.
+          </p>
+        ) : needle && matches.length === 0 ? (
+          <p
+            data-slot="help-panel-empty"
+            className="py-6 text-[length:var(--ds-text-caption-lg)] text-[color:var(--ds-muted-foreground)]"
+          >
+            No section matches “{query.trim()}”.
+          </p>
+        ) : (
+          <Markdown
+            compact
+            sanitizeSchema={markdownSanitizeSchema}
+            rehypePlugins={[rehypeHelpAnchors]}
+          >
+            {markdown}
+          </Markdown>
+        )}
+      </div>
+    </div>
+  );
+}
+
+/* ── the shell slot ──────────────────────────────────────────────────────── */
+
+export interface HelpPanelSlotConfig extends Omit<HelpPanelProps, "open" | "onClose"> {}
+
+/** What `AppShell` hands its `helpPanel` render function. */
+interface ShellHelpSlot {
+  open: boolean;
+  source?: string;
+  onClose: () => void;
+}
+
+/**
+ * `AppShell`'s `helpPanel` slot, filled.
+ *
+ * The shell renders whatever the function returns, open or closed, so this
+ * returns `null` while closed — a panel that rendered an empty box would draw
+ * the shell's bordered aside over the corner with nothing in it. `help.source`
+ * from the shell is used when no `source` is passed here.
+ */
+export function helpPanelSlot(
+  config: HelpPanelSlotConfig,
+): (slot: ShellHelpSlot) => React.ReactNode {
+  return ({ open, source, onClose }) =>
+    open ? (
+      <HelpPanel {...config} source={config.source ?? source ?? ""} open onClose={onClose} />
+    ) : null;
+}
+
+export { HelpPanel };