@yaakdoc/react 0.0.0-stage → 0.1.0

package/dist/islands.d.ts

@@ -0,0 +1,170 @@
+import { n as createIsland, t as IslandComponent } from "./island-BWyuL4_6.js";
+import { i as EnvironmentOption, n as ColorMode, r as ColorModePreference, s as LlmProvider } from "./types-BY2lOvlK.js";
+import { $ as useTabs, J as TabList, Q as tabPanelProps, X as tabElementIds, Y as TabListProps, Z as tabGroupIds, et as visibleTabPanelSelector, q as TAB_STORAGE_KEY } from "./index-CoQ7pnuB.js";
+//#region src/islands/browser.d.ts
+/** Browser helpers shared by the islands. */
+/** `localStorage` access that never throws (private mode, blocked storage...). */
+export declare const storage: {
+  get(key: string): string | null;
+  set(key: string, value: string): void;
+};
+/** Resolves a (possibly relative) URL against the current page. */
+export declare const resolveUrl: (url: string) => string;
+//#endregion
+//#region src/islands/color-mode.d.ts
+export declare const COLOR_MODE_STORAGE_KEY = "yaakdoc-color-mode";
+/** Applies a preference to <html data-theme> and persists it. */
+export declare function applyColorMode(preference: ColorModePreference): void;
+/**
+ * Headless color mode state. Hydration-safe: renders `fallback` on the server and during hydration,
+ * then switches to the real value.
+ */
+export declare function useColorMode(fallback?: ColorModePreference): {
+  preference: "dark" | "light" | "system";
+  resolved: ColorMode;
+  setPreference: (next: ColorModePreference) => void;
+  toggle: () => void;
+};
+/**
+ * Inline script for <head> that applies the stored/system color mode before first paint, and keeps
+ * following the system setting while the preference is "system".
+ */
+export declare function colorModeScript(defaultMode: ColorModePreference): string;
+type ColorModeToggleProps = {
+  className?: string;
+  label?: string;
+};
+/** Unstyled light/dark toggle. Both icons are rendered; show one via `[data-theme]` CSS. */
+export declare const ColorModeToggle: IslandComponent<ColorModeToggleProps>;
+//#endregion
+//#region src/islands/copy.d.ts
+type CopySource = {
+  /** Literal text to copy. */
+  text?: string;
+  /** CSS selector of an element whose text content is copied. */
+  target?: string;
+  /** URL whose response body is copied (e.g. a page's Markdown twin). */
+  url?: string;
+};
+/** Headless copy-to-clipboard state. `copied` resets after `timeout` ms. */
+export declare function useCopy(timeout?: number): {
+  state: "copied" | "error" | "idle";
+  copied: boolean;
+  copy: (source: CopySource) => Promise<void>;
+};
+type CopyButtonProps = CopySource & {
+  label?: string;
+  copiedLabel?: string;
+  className?: string;
+};
+/** Unstyled copy button. Copies `text`, the text of `target`, or the body of `url`. */
+export declare const CopyButton: IslandComponent<CopyButtonProps>;
+//#endregion
+//#region src/islands/environment.d.ts
+export declare const ENVIRONMENT_STORAGE_KEY = "yaakdoc-environment";
+/**
+ * Shows the content variants of one environment. Variants are elements with
+ * `data-yd-env="<environment id>"`; `<html data-environment>` drives the CSS (see
+ * {@link environmentCss}) and the `hidden` attributes are kept in sync for accessibility.
+ */
+export declare function applyEnvironment(id: string): void;
+/** Headless environment switcher state, synced across switchers and remembered. */
+export declare function useEnvironment(environments: readonly EnvironmentOption[], defaultId: string): {
+  selected: string;
+  select: (id: string) => void;
+  current: import("@yaakdoc/core").EnvironmentRef | undefined;
+};
+/** Inline <head> script: applies the remembered environment before first paint. */
+export declare function environmentScript(ids: readonly string[]): string;
+/** CSS that shows the variants of the environment set on <html> (falls back to `hidden`). */
+export declare function environmentCss(ids: readonly string[]): string;
+type EnvironmentSwitcherProps = {
+  environments: EnvironmentOption[];
+  defaultId: string;
+  className?: string;
+  label?: string;
+};
+/** Unstyled environment switcher (native select). */
+export declare const EnvironmentSwitcher: IslandComponent<EnvironmentSwitcherProps>;
+//#endregion
+//#region src/islands/llm.d.ts
+export declare const LLM_PROVIDERS: Record<LlmProvider, {
+  label: string;
+  url: (prompt: string) => string;
+}>;
+export declare const llmPrompt: (markdownUrl: string) => string;
+/** URL that opens an assistant with a prompt pointing at the (absolute) Markdown URL. */
+export declare function openInUrl(provider: LlmProvider, markdownUrl: string): string;
+type OpenInLinkProps = {
+  provider: LlmProvider;
+  /** Markdown URL; relative URLs are made absolute on click using the current location. */
+  markdownUrl: string;
+  className?: string;
+  label?: string;
+};
+/** Link that opens ChatGPT/Claude/... with the page's Markdown as context. */
+export declare const OpenInLink: IslandComponent<OpenInLinkProps>;
+//#endregion
+//#region src/islands/nav.d.ts
+/** Headless open/close state for a navigation element (`data-open` is set on the target). */
+export declare function useNavToggle(target: string): {
+  open: boolean;
+  setOpen: (next: boolean) => void;
+  toggle: () => void;
+};
+type NavToggleProps = {
+  target: string;
+  label?: string;
+  className?: string;
+};
+/** Unstyled menu button for small screens. */
+export declare const NavToggle: IslandComponent<NavToggleProps>;
+/**
+ * Filters `[data-yd-nav-item]` elements inside `target` by their text. Folders
+ * (`[data-yd-nav-folder]`) without visible matches are hidden; matching folders are expanded.
+ */
+export declare function filterNav(target: string, query: string): number;
+type NavFilterProps = {
+  target: string;
+  placeholder?: string;
+  className?: string;
+  shortcut?: string;
+};
+/** Unstyled filter input for the navigation. Press `/` to focus. */
+export declare const NavFilter: IslandComponent<NavFilterProps>;
+/**
+ * Highlights the navigation link of the section currently in view (single-page mode). Sections are
+ * elements with `data-yd-section`; links are `a[href="#<id>"]` inside `target`.
+ */
+export declare function useScrollSpy(target: string): void;
+/** Renders nothing; marks the active nav link while scrolling. */
+export declare const ScrollSpy: IslandComponent<{
+  target: string;
+}>;
+//#endregion
+//#region src/islands/run-in-yaak.d.ts
+/** Official "Run in Yaak" badge image. */
+export declare const RUN_IN_YAAK_BADGE = "https://yaak.app/static/button.svg";
+/** Link that opens Yaak and prompts to import the export/spec at `dataUrl` (must be absolute). */
+export declare function runInYaakUrl(name: string, dataUrl: string): string;
+/**
+ * "Run in Yaak" link for an export URL. Relative URLs (sites without a configured public URL) are
+ * made absolute on the client, after hydration.
+ */
+export declare function useRunInYaakHref(name: string, dataUrl: string): string;
+type RunInYaakLinkProps = {
+  name: string;
+  dataUrl: string;
+  /** Render the official badge image instead of text. */
+  badge?: boolean;
+  label?: string;
+  className?: string;
+};
+/** Unstyled "Run in Yaak" link (or the official badge with `badge`). */
+export declare const RunInYaakLink: IslandComponent<RunInYaakLinkProps>;
+//#endregion
+//#region src/islands/index.d.ts
+/** All built-in islands. Pass to `hydrateIslands()` (alongside your own) in a theme's client entry. */
+export declare const builtinIslands: ReadonlyArray<IslandComponent<any>>;
+//#endregion
+export { type ColorMode, type ColorModePreference, type ColorModeToggleProps, type CopyButtonProps, type CopySource, type EnvironmentOption, type EnvironmentSwitcherProps, type IslandComponent, type LlmProvider, type NavFilterProps, type NavToggleProps, type OpenInLinkProps, type RunInYaakLinkProps, TAB_STORAGE_KEY, TabList, type TabListProps, createIsland, tabElementIds, tabGroupIds, tabPanelProps, useTabs, visibleTabPanelSelector };

package/dist/islands.js

@@ -0,0 +1,152 @@
+import { a as ENVIRONMENT_STORAGE_KEY, c as environmentCss, d as resolveUrl, f as storage, i as useRunInYaakHref, l as environmentScript, m as createIsland, n as RunInYaakLink, o as EnvironmentSwitcher, r as runInYaakUrl, s as applyEnvironment, t as RUN_IN_YAAK_BADGE, u as useEnvironment } from "./run-in-yaak-CMMcDS7S.js";
+import { a as CopyButton, c as TabList, d as tabPanelProps, f as useTabs, i as openInUrl, l as tabElementIds, n as OpenInLink, o as useCopy, p as visibleTabPanelSelector, r as llmPrompt, s as TAB_STORAGE_KEY, t as LLM_PROVIDERS, u as tabGroupIds } from "./llm-Ddn5hWnS.js";
+import { a as useColorMode, i as colorModeScript, n as ColorModeToggle, r as applyColorMode, t as COLOR_MODE_STORAGE_KEY } from "./color-mode-B-vJCVkP.js";
+import { useCallback, useEffect, useState } from "react";
+import { jsx } from "react/jsx-runtime";
+//#region src/islands/nav.tsx
+/** Headless open/close state for a navigation element (`data-open` is set on the target). */
+function useNavToggle(target) {
+	const [open, setOpen] = useState(false);
+	const set = useCallback((next) => {
+		setOpen(next);
+		const element = document.querySelector(target);
+		if (element) element.dataset.open = String(next);
+		document.documentElement.dataset.navOpen = String(next);
+	}, [target]);
+	useEffect(() => {
+		const element = document.querySelector(target);
+		const onKey = (event) => event.key === "Escape" && set(false);
+		const onClick = (event) => {
+			if (event.target.closest("a")) set(false);
+		};
+		window.addEventListener("keydown", onKey);
+		element?.addEventListener("click", onClick);
+		return () => {
+			window.removeEventListener("keydown", onKey);
+			element?.removeEventListener("click", onClick);
+		};
+	}, [target, set]);
+	return {
+		open,
+		setOpen: set,
+		toggle: () => set(!open)
+	};
+}
+function NavToggleImpl({ target, label = "Toggle navigation", className }) {
+	const { open, toggle } = useNavToggle(target);
+	return /* @__PURE__ */ jsx("button", {
+		type: "button",
+		"data-yd": "nav-toggle",
+		"data-state": open ? "open" : "closed",
+		"aria-expanded": open,
+		"aria-label": label,
+		className,
+		onClick: toggle,
+		children: /* @__PURE__ */ jsx("span", {
+			"aria-hidden": "true",
+			children: "☰"
+		})
+	});
+}
+/** Unstyled menu button for small screens. */
+const NavToggle = createIsland("yd:nav-toggle", NavToggleImpl);
+/**
+* Filters `[data-yd-nav-item]` elements inside `target` by their text. Folders
+* (`[data-yd-nav-folder]`) without visible matches are hidden; matching folders are expanded.
+*/
+function filterNav(target, query) {
+	const root = document.querySelector(target);
+	if (!root) return 0;
+	const needle = query.trim().toLowerCase();
+	let visible = 0;
+	for (const item of root.querySelectorAll("[data-yd-nav-item]")) {
+		const text = (item.dataset.ydNavLabel ?? item.textContent ?? "").toLowerCase();
+		const match = !needle || text.includes(needle);
+		item.hidden = !match;
+		if (match) visible++;
+	}
+	const folders = [...root.querySelectorAll("[data-yd-nav-folder]")].reverse();
+	for (const folder of folders) {
+		const label = (folder.dataset.ydNavLabel ?? "").toLowerCase();
+		const hasMatch = !needle || label.includes(needle) || folder.querySelector("[data-yd-nav-item]:not([hidden])") !== null;
+		folder.hidden = !hasMatch;
+		if (needle && hasMatch) {
+			folder.querySelector("details")?.setAttribute("open", "");
+			if (label.includes(needle)) for (const child of folder.querySelectorAll("[hidden]")) child.hidden = false;
+		}
+	}
+	return visible;
+}
+function NavFilterImpl({ target, placeholder = "Filter...", className, shortcut = "/" }) {
+	const [query, setQuery] = useState("");
+	useEffect(() => {
+		const onKey = (event) => {
+			const active = document.activeElement;
+			if (event.key !== shortcut || active?.matches("input, textarea, [contenteditable]")) return;
+			event.preventDefault();
+			document.querySelector("[data-yd=\"nav-filter\"]")?.focus();
+		};
+		window.addEventListener("keydown", onKey);
+		return () => window.removeEventListener("keydown", onKey);
+	}, [shortcut]);
+	return /* @__PURE__ */ jsx("input", {
+		type: "search",
+		"data-yd": "nav-filter",
+		className,
+		placeholder,
+		"aria-label": placeholder,
+		value: query,
+		onChange: (event) => {
+			setQuery(event.target.value);
+			filterNav(target, event.target.value);
+		}
+	});
+}
+/** Unstyled filter input for the navigation. Press `/` to focus. */
+const NavFilter = createIsland("yd:nav-filter", NavFilterImpl);
+/**
+* Highlights the navigation link of the section currently in view (single-page mode). Sections are
+* elements with `data-yd-section`; links are `a[href="#<id>"]` inside `target`.
+*/
+function useScrollSpy(target) {
+	useEffect(() => {
+		const nav = document.querySelector(target);
+		const sections = document.querySelectorAll("[data-yd-section]");
+		if (!nav || sections.length === 0 || typeof IntersectionObserver === "undefined") return;
+		let current = null;
+		const observer = new IntersectionObserver((entries) => {
+			const top = entries.filter((entry) => entry.isIntersecting).sort((a, b) => a.boundingClientRect.top - b.boundingClientRect.top)[0];
+			if (!top) return;
+			const link = nav.querySelector(`a[href$="#${CSS.escape(top.target.id)}"]`);
+			if (!link || link === current) return;
+			current?.removeAttribute("aria-current");
+			link.setAttribute("aria-current", "location");
+			current = link;
+			for (let el = link.parentElement; el && el !== nav; el = el.parentElement) if (el instanceof HTMLDetailsElement && !el.open) el.open = true;
+		}, { rootMargin: "-10% 0px -70% 0px" });
+		for (const section of sections) observer.observe(section);
+		return () => observer.disconnect();
+	}, [target]);
+}
+function ScrollSpyImpl({ target }) {
+	useScrollSpy(target);
+	return null;
+}
+/** Renders nothing; marks the active nav link while scrolling. */
+const ScrollSpy = createIsland("yd:scroll-spy", ScrollSpyImpl);
+//#endregion
+//#region src/islands/index.ts
+/** All built-in islands. Pass to `hydrateIslands()` (alongside your own) in a theme's client entry. */
+const builtinIslands = [
+	ColorModeToggle,
+	CopyButton,
+	EnvironmentSwitcher,
+	TabList,
+	NavToggle,
+	NavFilter,
+	ScrollSpy,
+	OpenInLink,
+	RunInYaakLink
+];
+//#endregion
+export { COLOR_MODE_STORAGE_KEY, ColorModeToggle, CopyButton, ENVIRONMENT_STORAGE_KEY, EnvironmentSwitcher, LLM_PROVIDERS, NavFilter, NavToggle, OpenInLink, RUN_IN_YAAK_BADGE, RunInYaakLink, ScrollSpy, TAB_STORAGE_KEY, TabList, applyColorMode, applyEnvironment, builtinIslands, colorModeScript, createIsland, environmentCss, environmentScript, filterNav, llmPrompt, openInUrl, resolveUrl, runInYaakUrl, storage, tabElementIds, tabGroupIds, tabPanelProps, useColorMode, useCopy, useEnvironment, useNavToggle, useRunInYaakHref, useScrollSpy, useTabs, visibleTabPanelSelector };

package/dist/llm-Ddn5hWnS.js

@@ -0,0 +1,205 @@
+import { d as resolveUrl, f as storage, m as createIsland } from "./run-in-yaak-CMMcDS7S.js";
+import { useCallback, useEffect, useRef, useState } from "react";
+import { jsx } from "react/jsx-runtime";
+//#region src/islands/tabs.tsx
+const TAB_STORAGE_KEY = "yaakdoc-tab";
+/** Tab group names of a request's code examples and example responses. */
+const tabGroupIds = {
+	examples: (anchor) => `ex-${anchor}`,
+	responses: (anchor) => `res-${anchor}`
+};
+/** Ids linking a tab to its panel. `variant` tells apart copies of a panel (one per environment). */
+function tabElementIds(group, id, variant = 0) {
+	return {
+		tab: `${group}-tab-${id}`,
+		panel: `${group}-panel-${id}${variant ? `-${variant}` : ""}`
+	};
+}
+/** Props for a server-rendered panel controlled by {@link TabList}. */
+function tabPanelProps(group, id, options) {
+	const ids = tabElementIds(group, id, options.variant);
+	return {
+		role: "tabpanel",
+		id: ids.panel,
+		"aria-labelledby": ids.tab,
+		"data-yd-tab-panel": id,
+		hidden: !options.selected
+	};
+}
+/** Selector of an element (default: the code) inside the visible panel of a tab group. */
+const visibleTabPanelSelector = (group, inner = "pre") => `[data-yd-tab-group="${group}"] [data-yd-tab-panel]:not([hidden]) ${inner}`;
+const TAB_EVENT = "yaakdoc:tab";
+function showPanel(group, id) {
+	const container = document.querySelector(`[data-yd-tab-group="${CSS.escape(group)}"]`);
+	if (!container) return;
+	for (const panel of container.querySelectorAll("[data-yd-tab-panel]")) panel.hidden = panel.dataset.ydTabPanel !== id;
+}
+/**
+* Headless tab state for a panel group rendered on the server. Panels are elements with
+* `data-yd-tab-panel="<id>"` inside `[data-yd-tab-group="<group>"]`. The selection is synced across
+* all groups on the page (pick "Python" once, see Python everywhere) and remembered.
+*/
+function useTabs(group, ids, sync = true) {
+	const [selected, setSelected] = useState(ids[0] ?? "");
+	const select = useCallback((id, broadcast = true) => {
+		if (!ids.includes(id)) return;
+		setSelected(id);
+		showPanel(group, id);
+		if (sync && broadcast) {
+			storage.set(TAB_STORAGE_KEY, id);
+			window.dispatchEvent(new CustomEvent(TAB_EVENT, { detail: {
+				id,
+				group
+			} }));
+		}
+	}, [
+		group,
+		ids,
+		sync
+	]);
+	useEffect(() => {
+		if (!sync) return;
+		const stored = storage.get(TAB_STORAGE_KEY);
+		if (stored) select(stored, false);
+		const onTab = (event) => {
+			const detail = event.detail;
+			if (detail.group !== group) select(detail.id, false);
+		};
+		window.addEventListener(TAB_EVENT, onTab);
+		return () => window.removeEventListener(TAB_EVENT, onTab);
+	}, [
+		group,
+		select,
+		sync
+	]);
+	return {
+		selected,
+		select
+	};
+}
+function TabListImpl({ group, tabs, sync = true, className, tabClassName, label = "Code examples" }) {
+	const { selected, select } = useTabs(group, tabs.map((tab) => tab.id), sync);
+	const onKeyDown = (event, index) => {
+		const delta = event.key === "ArrowRight" ? 1 : event.key === "ArrowLeft" ? -1 : 0;
+		if (!delta) return;
+		event.preventDefault();
+		const next = tabs[(index + delta + tabs.length) % tabs.length];
+		select(next.id);
+		(event.currentTarget.parentElement?.children[tabs.indexOf(next)])?.focus();
+	};
+	return /* @__PURE__ */ jsx("div", {
+		role: "tablist",
+		"aria-label": label,
+		"data-yd": "tab-list",
+		className,
+		children: tabs.map((tab, index) => /* @__PURE__ */ jsx("button", {
+			type: "button",
+			role: "tab",
+			id: tabElementIds(group, tab.id).tab,
+			"aria-selected": selected === tab.id,
+			"aria-controls": tabElementIds(group, tab.id).panel,
+			tabIndex: selected === tab.id ? 0 : -1,
+			"data-state": selected === tab.id ? "active" : "inactive",
+			className: [tabClassName, tab.className].filter(Boolean).join(" ") || void 0,
+			onClick: () => select(tab.id),
+			onKeyDown: (event) => onKeyDown(event, index),
+			children: tab.label
+		}, tab.id))
+	});
+}
+/** Accessible tab list controlling server-rendered panels (see {@link useTabs}). */
+const TabList = createIsland("yd:tab-list", TabListImpl);
+//#endregion
+//#region src/islands/copy.tsx
+async function resolveCopyText(source) {
+	if (source.text !== void 0) return source.text;
+	if (source.url) {
+		const response = await fetch(source.url);
+		if (!response.ok) throw new Error(`Failed to fetch ${source.url}: ${response.status}`);
+		return response.text();
+	}
+	if (source.target) {
+		const matches = [...document.querySelectorAll(source.target)];
+		return (matches.find((el) => el.getClientRects().length > 0) ?? matches[0])?.textContent ?? "";
+	}
+	return "";
+}
+/** Headless copy-to-clipboard state. `copied` resets after `timeout` ms. */
+function useCopy(timeout = 2e3) {
+	const [state, setState] = useState("idle");
+	const timer = useRef(void 0);
+	useEffect(() => () => clearTimeout(timer.current), []);
+	const copy = useCallback(async (source) => {
+		try {
+			if (typeof ClipboardItem !== "undefined" && navigator.clipboard?.write) await navigator.clipboard.write([new ClipboardItem({ "text/plain": resolveCopyText(source).then((text) => new Blob([text], { type: "text/plain" })) })]);
+			else await navigator.clipboard.writeText(await resolveCopyText(source));
+			setState("copied");
+		} catch (error) {
+			console.error("[yaakdoc] Copy failed", error);
+			setState("error");
+		}
+		clearTimeout(timer.current);
+		timer.current = setTimeout(() => setState("idle"), timeout);
+	}, [timeout]);
+	return {
+		state,
+		copied: state === "copied",
+		copy
+	};
+}
+function CopyButtonImpl({ label = "Copy", copiedLabel = "Copied!", className, ...source }) {
+	const { state, copy } = useCopy();
+	return /* @__PURE__ */ jsx("button", {
+		type: "button",
+		"data-yd": "copy-button",
+		"data-state": state,
+		className,
+		onClick: () => copy(source),
+		"aria-live": "polite",
+		children: state === "copied" ? copiedLabel : label
+	});
+}
+/** Unstyled copy button. Copies `text`, the text of `target`, or the body of `url`. */
+const CopyButton = createIsland("yd:copy-button", CopyButtonImpl);
+//#endregion
+//#region src/islands/llm.tsx
+const LLM_PROVIDERS = {
+	chatgpt: {
+		label: "ChatGPT",
+		url: (q) => `https://chatgpt.com/?hints=search&q=${encodeURIComponent(q)}`
+	},
+	claude: {
+		label: "Claude",
+		url: (q) => `https://claude.ai/new?q=${encodeURIComponent(q)}`
+	},
+	perplexity: {
+		label: "Perplexity",
+		url: (q) => `https://www.perplexity.ai/search?q=${encodeURIComponent(q)}`
+	}
+};
+const llmPrompt = (markdownUrl) => `Read ${markdownUrl} so I can ask questions about this API documentation.`;
+/** URL that opens an assistant with a prompt pointing at the (absolute) Markdown URL. */
+function openInUrl(provider, markdownUrl) {
+	return LLM_PROVIDERS[provider].url(llmPrompt(markdownUrl));
+}
+function OpenInLinkImpl({ provider, markdownUrl, className, label }) {
+	return /* @__PURE__ */ jsx("a", {
+		"data-yd": "open-in",
+		"data-provider": provider,
+		className,
+		href: openInUrl(provider, markdownUrl),
+		target: "_blank",
+		rel: "noopener noreferrer",
+		onClick: (event) => {
+			const absolute = resolveUrl(markdownUrl);
+			if (absolute === markdownUrl) return;
+			event.preventDefault();
+			window.open(openInUrl(provider, absolute), "_blank", "noopener,noreferrer");
+		},
+		children: label ?? `Open in ${LLM_PROVIDERS[provider].label}`
+	});
+}
+/** Link that opens ChatGPT/Claude/... with the page's Markdown as context. */
+const OpenInLink = createIsland("yd:open-in", OpenInLinkImpl);
+//#endregion
+export { CopyButton as a, TabList as c, tabPanelProps as d, useTabs as f, openInUrl as i, tabElementIds as l, OpenInLink as n, useCopy as o, visibleTabPanelSelector as p, llmPrompt as r, TAB_STORAGE_KEY as s, LLM_PROVIDERS as t, tabGroupIds as u };