cortena-ui 1.4.2 → 1.6.0

package/dist/components/help-panel.d.ts

@@ -0,0 +1,131 @@
+"use client";
+import * as React from "react";
+//#region src/components/help-panel.d.ts
+/**
+ * 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[];
+}
+/**
+ * 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 declare function parseHelpDocument(source: string): HelpDocument;
+/**
+ * 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 declare function resolveHelpTarget(doc: HelpDocument, context?: string): string | undefined;
+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 declare function useHelpHotkeys({ open, onOpen, onClose, disabled }?: HelpHotkeysOptions): void;
+export interface HelpHotkeysProps extends HelpHotkeysOptions {}
+/** `useHelpHotkeys` as a component, for a shell whose children are markup. */
+export declare function HelpHotkeys(props: HelpHotkeysProps): 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 declare function httpDocumentUrl(documentUrl: string | undefined): string | undefined;
+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;
+}
+declare function HelpPanel({ source, open, onClose, context, title, documentUrl, outlineDepth, defaultQuery, className, ...props }: HelpPanelProps): React.JSX.Element | null;
+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 declare function helpPanelSlot(config: HelpPanelSlotConfig): (slot: ShellHelpSlot) => React.ReactNode;
+//#endregion
+export { HelpPanel };
+//# sourceMappingURL=help-panel.d.ts.map

package/dist/components/help-panel.js

@@ -0,0 +1,545 @@
+"use client";
+"use client";
+import { cn } from "../lib/cn.js";
+import { Spinner } from "./spinner.js";
+import { Markdown, markdownSanitizeSchema } from "./markdown.js";
+import { ExternalLink, Search, X } from "lucide-react";
+import { jsx, jsxs } from "react/jsx-runtime";
+import * as React from "react";
+//#region src/components/help-panel.tsx
+/**
+* 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.
+*/
+/** Lowercase, punctuation to hyphens. The same slug the rendered heading gets. */
+function slugify(text) {
+	return text.toLowerCase().normalize("NFKD").replace(/[\u0300-\u036f]/g, "").replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "section";
+}
+/** Slugs in document order, with `-1`, `-2` for repeats, as GitHub numbers them. */
+function createSlugger() {
+	const seen = /* @__PURE__ */ new Map();
+	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) {
+	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) {
+	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.
+*/
+function parseHelpDocument(source) {
+	const matter = FRONT_MATTER.exec(source);
+	const body = matter ? source.slice(matter[0].length) : source;
+	const frontMatter = {};
+	const routes = [];
+	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) {
+				if (key && value) routes.push({
+					route: key,
+					target: value
+				});
+				continue;
+			}
+			inRoutes = !indented && (key === "route" || key === "routes") && value === "";
+			if (!inRoutes && !indented && key) frontMatter[key] = value;
+		}
+	}
+	routes.sort((a, b) => b.route.length - a.route.length);
+	const slug = createSlugger();
+	const sections = [];
+	let current;
+	let fence;
+	for (const line of body.split(/\r?\n/)) {
+		const fenced = FENCE.exec(line);
+		if (fenced) {
+			const mark = fenced[1] ?? "";
+			fence = fence === void 0 ? mark : fence === mark ? void 0 : fence;
+		}
+		const heading = fence === void 0 ? 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) {
+			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();
+	return {
+		title: frontMatter.title ?? sections.find((s) => s.depth === 1)?.title,
+		frontMatter,
+		routes,
+		body,
+		sections
+	};
+}
+function normalizeRoute(route) {
+	const path = (route.split(/[?#]/)[0] ?? "").trim().toLowerCase();
+	return path.length > 1 ? path.replace(/\/+$/, "") : path;
+}
+function findSection(doc, target) {
+	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.
+*/
+function resolveHelpTarget(doc, context) {
+	if (!context) return void 0;
+	const path = normalizeRoute(context);
+	if (!path) return void 0;
+	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;
+	}
+}
+function nodeText(node) {
+	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) => {
+		const slug = createSlugger();
+		const walk = (node) => {
+			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);
+	};
+}
+function isTypingTarget(target) {
+	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.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() {
+	const button = document.querySelector("[data-slot=\"help-button\"]");
+	if (!button || button.getAttribute("aria-expanded") === "true") return;
+	button.click();
+}
+/**
+* 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.
+*/
+function useHelpHotkeys({ open, onOpen, onClose, disabled } = {}) {
+	const state = React.useRef({
+		open,
+		onOpen,
+		onClose
+	});
+	state.current = {
+		open,
+		onOpen,
+		onClose
+	};
+	React.useEffect(() => {
+		if (disabled) return;
+		const onKeyDown = (event) => {
+			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]);
+}
+/** `useHelpHotkeys` as a component, for a shell whose children are markup. */
+function HelpHotkeys(props) {
+	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.
+*/
+function httpDocumentUrl(documentUrl) {
+	if (!documentUrl) return void 0;
+	try {
+		const base = typeof location === "undefined" ? void 0 : location.href;
+		const { protocol } = base === void 0 ? new URL(documentUrl) : new URL(documentUrl, base);
+		return protocol === "http:" || protocol === "https:" ? documentUrl : void 0;
+	} catch {
+		return;
+	}
+}
+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();
+function HelpPanel({ source, open = true, onClose, context, title, documentUrl, outlineDepth = 3, defaultQuery = "", className, ...props }) {
+	const [text, setText] = React.useState(typeof source === "string" ? source : loadedDocuments.get(source));
+	const [failed, setFailed] = React.useState(false);
+	const [query, setQuery] = React.useState(defaultQuery);
+	const [activeId, setActiveId] = React.useState();
+	const bodyRef = React.useRef(null);
+	const panelRef = React.useRef(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;
+		const frame = requestAnimationFrame(() => {
+			const root = panelRef.current;
+			if (!root || root.contains(document.activeElement)) return;
+			root.querySelector("[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 !== void 0) {
+			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);
+	const scrolledTo = React.useRef(void 0);
+	const scrollTo = React.useCallback((id, onlyIfUntouched = false) => {
+		const scroller = bodyRef.current;
+		const heading = scroller?.querySelector(`#${CSS.escape(id)}`);
+		if (!scroller || !heading) return false;
+		if (onlyIfUntouched && scrolledTo.current !== scroller.scrollTop) return false;
+		scroller.scrollTop += heading.getBoundingClientRect().top - scroller.getBoundingClientRect().top;
+		scrolledTo.current = scroller.scrollTop;
+		setActiveId(id);
+		return true;
+	}, []);
+	const target = React.useMemo(() => resolveHelpTarget(doc, context), [doc, context]);
+	React.useEffect(() => {
+		if (!open || !target || needle) return;
+		let cancelled = false;
+		scrollTo(target);
+		const again = () => {
+			if (!cancelled) scrollTo(target, scrolledTo.current !== void 0);
+		};
+		const frame = requestAnimationFrame(again);
+		document.fonts?.ready.then(again);
+		return () => {
+			cancelled = true;
+			cancelAnimationFrame(frame);
+		};
+	}, [
+		open,
+		target,
+		needle,
+		scrollTo
+	]);
+	const safeDocumentUrl = httpDocumentUrl(documentUrl);
+	const [fallbackUrl, setFallbackUrl] = React.useState();
+	React.useEffect(() => {
+		if (safeDocumentUrl || text === void 0) return;
+		const url = URL.createObjectURL(new Blob([text], { type: "text/markdown;charset=utf-8" }));
+		setFallbackUrl(url);
+		return () => URL.revokeObjectURL(url);
+	}, [safeDocumentUrl, text]);
+	const href = safeDocumentUrl ?? fallbackUrl;
+	if (!open) return null;
+	const heading = title ?? doc.title ?? "Help";
+	const loading = text === void 0 && !failed;
+	return /* @__PURE__ */ jsxs("div", {
+		ref: panelRef,
+		"data-slot": "help-panel",
+		"data-loading": loading || void 0,
+		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,
+		children: [
+			/* @__PURE__ */ jsxs("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",
+				children: [
+					/* @__PURE__ */ jsx("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)]"),
+						children: heading
+					}),
+					href ? /* @__PURE__ */ jsx("a", {
+						"data-slot": "help-panel-open-full",
+						href,
+						target: "_blank",
+						rel: "noreferrer",
+						"aria-label": "Open the full document in a new tab",
+						className: headerButton,
+						children: /* @__PURE__ */ jsx(ExternalLink, { "aria-hidden": true })
+					}) : null,
+					onClose ? /* @__PURE__ */ jsx("button", {
+						type: "button",
+						"data-slot": "help-panel-close",
+						"aria-label": "Close help",
+						onClick: onClose,
+						className: headerButton,
+						children: /* @__PURE__ */ jsx(X, { "aria-hidden": true })
+					}) : null
+				]
+			}),
+			/* @__PURE__ */ jsx("div", {
+				"data-slot": "help-panel-search",
+				className: "shrink-0 border-b border-[var(--ds-border-subtle)] px-4 py-3",
+				children: /* @__PURE__ */ jsxs("div", {
+					className: "relative",
+					children: [/* @__PURE__ */ jsx(Search, {
+						"aria-hidden": true,
+						className: "pointer-events-none absolute top-1/2 left-2.5 size-4 -translate-y-1/2 text-[color:var(--ds-text-tertiary)]"
+					}), /* @__PURE__ */ jsx("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")
+					})]
+				})
+			}),
+			outline.length > 0 ? /* @__PURE__ */ jsx("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",
+				children: /* @__PURE__ */ jsx("ol", {
+					className: "flex flex-col",
+					children: outline.map((section) => /* @__PURE__ */ jsx("li", { children: /* @__PURE__ */ jsx("a", {
+						"data-slot": "help-panel-outline-item",
+						"data-depth": section.depth,
+						"data-active": section.id === activeId || void 0,
+						href: `#${section.id}`,
+						onClick: (event) => {
+							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"),
+						children: section.title
+					}) }, section.id))
+				})
+			}) : null,
+			/* @__PURE__ */ jsx("div", {
+				ref: bodyRef,
+				"data-slot": "help-panel-body",
+				className: "min-h-0 flex-1 overflow-y-auto px-4 py-3",
+				children: loading ? /* @__PURE__ */ jsxs("div", {
+					"data-slot": "help-panel-loading",
+					className: "flex items-center gap-2 py-6",
+					children: [/* @__PURE__ */ jsx(Spinner, {}), /* @__PURE__ */ jsx("span", {
+						className: "text-[length:var(--ds-text-caption-lg)] text-[color:var(--ds-muted-foreground)]",
+						children: "Loading help…"
+					})]
+				}) : failed ? /* @__PURE__ */ jsx("p", {
+					"data-slot": "help-panel-error",
+					className: "py-6 text-[length:var(--ds-text-caption-lg)] text-[color:var(--ds-destructive)]",
+					children: "The help document could not be loaded."
+				}) : needle && matches.length === 0 ? /* @__PURE__ */ jsxs("p", {
+					"data-slot": "help-panel-empty",
+					className: "py-6 text-[length:var(--ds-text-caption-lg)] text-[color:var(--ds-muted-foreground)]",
+					children: [
+						"No section matches “",
+						query.trim(),
+						"”."
+					]
+				}) : /* @__PURE__ */ jsx(Markdown, {
+					compact: true,
+					sanitizeSchema: markdownSanitizeSchema,
+					rehypePlugins: [rehypeHelpAnchors],
+					children: markdown
+				})
+			})
+		]
+	});
+}
+/**
+* `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.
+*/
+function helpPanelSlot(config) {
+	return ({ open, source, onClose }) => open ? /* @__PURE__ */ jsx(HelpPanel, {
+		...config,
+		source: config.source ?? source ?? "",
+		open: true,
+		onClose
+	}) : null;
+}
+//#endregion
+export { HelpHotkeys, HelpPanel, helpPanelSlot, httpDocumentUrl, parseHelpDocument, resolveHelpTarget, useHelpHotkeys };
+
+//# sourceMappingURL=help-panel.js.map