@yaakdoc/react 0.0.0-stage → 0.2.0

package/dist/site-DyK7ZcqQ.js

@@ -0,0 +1,371 @@
+import { n as RunInYaakLink } from "./run-in-yaak-CMMcDS7S.js";
+import { absoluteUrl, authLabel, methodLabel } from "@yaakdoc/core";
+import { createContext, use } from "react";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+//#region src/context.tsx
+const YaakdocContext = createContext(null);
+function YaakdocProvider({ document, site, page, children }) {
+	return /* @__PURE__ */ jsx(YaakdocContext, {
+		value: {
+			document,
+			site,
+			page
+		},
+		children
+	});
+}
+function useYaakdocContext() {
+	const value = use(YaakdocContext);
+	if (!value) throw new Error("yaakdoc hooks must be used inside <YaakdocProvider>. Note: islands are hydrated in isolation and cannot use these hooks; pass data via props instead.");
+	return value;
+}
+/** The prepared documentation (requests, folders, tree, environment...). */
+const useDocument = () => useYaakdocContext().document;
+/** Site configuration and branding. */
+const useSite = () => useYaakdocContext().site;
+/** The page currently being rendered. */
+const usePage = () => useYaakdocContext().page;
+/** Theme-specific options from `themeOptions` in the config. */
+const useThemeOptions = () => useYaakdocContext().site.themeOptions;
+function useRequest(id) {
+	const request = useDocument().requests[id];
+	if (!request) throw new Error(`Unknown request id "${id}"`);
+	return request;
+}
+function useFolder(id) {
+	const folder = useDocument().folders[id];
+	if (!folder) throw new Error(`Unknown folder id "${id}"`);
+	return folder;
+}
+//#endregion
+//#region src/site-url.ts
+/**
+* Absolute URL of a site path (one starting with `/`, including the base) when the public site
+* URL is configured; `null` otherwise (or for URLs that aren't site paths).
+*/
+function toAbsoluteUrl(site, path) {
+	return site.url && path.startsWith("/") ? absoluteUrl(site.url, site.base, path) : null;
+}
+//#endregion
+//#region src/hooks.ts
+/**
+* Data for "Copy page/section" actions, or `null` when they are disabled (or there is no Markdown
+* twin). `absoluteUrl` is `null` when the public site URL isn't configured.
+*/
+function usePageActions(markdownUrl) {
+	const site = useSite();
+	if (!markdownUrl || !site.llms.enabled || !site.llms.copyButton) return null;
+	return {
+		markdownUrl,
+		absoluteUrl: toAbsoluteUrl(site, markdownUrl),
+		openIn: site.llms.openIn
+	};
+}
+/** Name and export URL for the "Run in Yaak" button, or `null` when it is disabled. */
+function useRunInYaak() {
+	const site = useSite();
+	if (!site.runInYaak) return null;
+	const { name, dataUrl } = site.runInYaak;
+	return {
+		name,
+		dataUrl: toAbsoluteUrl(site, dataUrl) ?? dataUrl
+	};
+}
+//#endregion
+//#region src/overrides.tsx
+const ComponentsContext = createContext({});
+/**
+* Provides component overrides. Every base component created with {@link overridable} renders the
+* override registered under its name instead, so themes can swap any piece (MDX-style) – including
+* pieces rendered internally by other base components.
+*/
+function ComponentsProvider({ components, children }) {
+	const parent = use(ComponentsContext);
+	return /* @__PURE__ */ jsx(ComponentsContext, {
+		value: {
+			...parent,
+			...components
+		},
+		children
+	});
+}
+const useComponents = () => use(ComponentsContext);
+/**
+* Wraps a default component so it can be replaced through {@link ComponentsProvider}.
+* The override receives the same props plus `Default`, the original implementation, so it can
+* decorate rather than replace.
+*/
+function overridable(name, Default) {
+	function Overridable(props) {
+		const Override = use(ComponentsContext)[name];
+		if (Override && Override !== Wrapped) return /* @__PURE__ */ jsx(Override, {
+			...props,
+			Default
+		});
+		return /* @__PURE__ */ jsx(Default, { ...props });
+	}
+	const Wrapped = Object.assign(Overridable, {
+		displayName: name,
+		Default
+	});
+	return Wrapped;
+}
+//#endregion
+//#region src/primitives/basic.tsx
+/** Renders trusted, pre-sanitized HTML (descriptions are sanitized at build time). */
+const Html = overridable("Html", function Html({ html, as: As = "div", ...props }) {
+	return /* @__PURE__ */ jsx(As, {
+		"data-yd": "html",
+		...props,
+		dangerouslySetInnerHTML: { __html: html }
+	});
+});
+/** Rendered Markdown (a description). */
+const Markdown = overridable("Markdown", function Markdown({ html, className }) {
+	if (!html) return null;
+	return /* @__PURE__ */ jsx(Html, {
+		html,
+		className,
+		"data-yd": "markdown"
+	});
+});
+/** HTTP method (or gRPC / WS) badge. Style via `[data-method="get"]` etc. */
+const MethodBadge = overridable("MethodBadge", function MethodBadge({ request, className }) {
+	const label = methodLabel(request);
+	return /* @__PURE__ */ jsx("span", {
+		"data-yd": "method",
+		"data-method": label.toLowerCase(),
+		"data-kind": request.kind,
+		className,
+		children: label
+	});
+});
+/**
+* Request URL with `{{variables}}` and `:path` parameters wrapped in spans
+* (`[data-yd="url-variable"]`, `[data-yd="url-param"]`) for styling.
+*/
+const RequestUrl = overridable("RequestUrl", function RequestUrl({ url, className }) {
+	const parts = url.split(/(\{\{[^}]+\}\}|:[A-Za-z_][\w-]*(?=\/|$|\?|\.|#))/g).filter(Boolean);
+	return /* @__PURE__ */ jsx("code", {
+		"data-yd": "url",
+		className,
+		children: parts.map((part, index) => part.startsWith("{{") ? /* @__PURE__ */ jsx("span", {
+			"data-yd": "url-variable",
+			children: part
+		}, index) : part.startsWith(":") && index > 0 ? /* @__PURE__ */ jsx("span", {
+			"data-yd": "url-param",
+			children: part
+		}, index) : part)
+	});
+});
+/** Generic two-column table for headers and parameters. */
+const KeyValueTable = overridable("KeyValueTable", function KeyValueTable({ items, caption, columns = ["Name", "Value"], className, showInherited = true }) {
+	if (items.length === 0) return null;
+	return /* @__PURE__ */ jsxs("table", {
+		"data-yd": "kv-table",
+		className,
+		children: [
+			caption ? /* @__PURE__ */ jsx("caption", { children: caption }) : null,
+			/* @__PURE__ */ jsx("thead", { children: /* @__PURE__ */ jsxs("tr", { children: [/* @__PURE__ */ jsx("th", {
+				scope: "col",
+				children: columns[0]
+			}), /* @__PURE__ */ jsx("th", {
+				scope: "col",
+				children: columns[1]
+			})] }) }),
+			/* @__PURE__ */ jsx("tbody", { children: items.map((item, index) => /* @__PURE__ */ jsxs("tr", {
+				"data-enabled": item.enabled,
+				children: [/* @__PURE__ */ jsxs("td", { children: [
+					/* @__PURE__ */ jsx("code", {
+						"data-yd": "kv-name",
+						children: item.name
+					}),
+					!item.enabled ? /* @__PURE__ */ jsx("span", {
+						"data-yd": "optional",
+						children: "optional"
+					}) : null,
+					showInherited && "inheritedFrom" in item && item.inheritedFrom ? /* @__PURE__ */ jsx("span", {
+						"data-yd": "inherited",
+						title: `Inherited from ${item.inheritedFrom.model} "${item.inheritedFrom.name}"`,
+						children: item.inheritedFrom.model
+					}) : null
+				] }), /* @__PURE__ */ jsx("td", { children: item.value ? /* @__PURE__ */ jsx("code", {
+					"data-yd": "kv-value",
+					children: item.value
+				}) : null })]
+			}, index)) })
+		]
+	});
+});
+/** Describes the effective authentication of a request/folder. */
+const AuthInfo = overridable("AuthInfo", function AuthInfo({ auth, className }) {
+	if (!auth) return /* @__PURE__ */ jsx("p", {
+		"data-yd": "auth",
+		"data-auth": "none",
+		className,
+		children: "No authentication required."
+	});
+	const fields = auth.fields;
+	return /* @__PURE__ */ jsxs("p", {
+		"data-yd": "auth",
+		"data-auth": auth.type,
+		className,
+		children: [
+			/* @__PURE__ */ jsx("strong", { children: authLabel(auth.type) }),
+			auth.type === "apikey" ? /* @__PURE__ */ jsxs(Fragment, { children: [
+				" ",
+				"— send ",
+				/* @__PURE__ */ jsx("code", { children: String(fields.key || "X-API-Key") }),
+				" in the",
+				" ",
+				fields.location === "query" ? "query string" : "headers",
+				"."
+			] }) : auth.type === "bearer" ? /* @__PURE__ */ jsxs(Fragment, { children: [
+				" ",
+				"— send ",
+				/* @__PURE__ */ jsxs("code", { children: [
+					"Authorization: ",
+					String(fields.prefix || "Bearer"),
+					" <token>"
+				] }),
+				"."
+			] }) : auth.type === "basic" ? /* @__PURE__ */ jsxs(Fragment, { children: [
+				" ",
+				"— send ",
+				/* @__PURE__ */ jsx("code", { children: "Authorization: Basic <base64(username:password)>" }),
+				"."
+			] }) : null,
+			auth.inheritedFrom ? /* @__PURE__ */ jsxs("span", {
+				"data-yd": "inherited",
+				children: [
+					" ",
+					"Inherited from ",
+					auth.inheritedFrom.model,
+					" \"",
+					auth.inheritedFrom.name,
+					"\"."
+				]
+			}) : null
+		]
+	});
+});
+//#endregion
+//#region src/primitives/site.tsx
+/** Site logo (light/dark variants) linking to the docs home, falling back to the title. */
+const Logo = overridable("Logo", function Logo({ className, showTitle = true }) {
+	const site = useSite();
+	const logo = site.logo;
+	const href = logo?.href ?? site.base;
+	const size = {
+		width: logo?.width,
+		height: logo?.height
+	};
+	return /* @__PURE__ */ jsxs("a", {
+		href,
+		"data-yd": "logo",
+		className,
+		children: [
+			logo?.light ? /* @__PURE__ */ jsx("img", {
+				src: logo.light,
+				alt: logo.alt,
+				"data-yd-logo": logo.dark ? "light" : "both",
+				...size
+			}) : null,
+			logo?.dark ? /* @__PURE__ */ jsx("img", {
+				src: logo.dark,
+				alt: logo.alt,
+				"data-yd-logo": logo.light ? "dark" : "both",
+				...size
+			}) : null,
+			showTitle ? /* @__PURE__ */ jsx("span", {
+				"data-yd": "site-title",
+				children: site.title
+			}) : null
+		]
+	});
+});
+/** Header links from `branding.links`. */
+const SiteLinks = overridable("SiteLinks", function SiteLinks({ className }) {
+	const site = useSite();
+	if (site.links.length === 0) return null;
+	return /* @__PURE__ */ jsx("ul", {
+		"data-yd": "site-links",
+		className,
+		children: site.links.map((link) => /* @__PURE__ */ jsx("li", { children: /* @__PURE__ */ jsx("a", {
+			href: link.href,
+			"data-icon": link.icon,
+			.../^https?:/.test(link.href) ? {
+				target: "_blank",
+				rel: "noopener"
+			} : {},
+			children: link.label
+		}) }, link.href))
+	});
+});
+/** Footer text from `branding.footer` plus an llms.txt link. */
+const Footer = overridable("Footer", function Footer({ className }) {
+	const site = useSite();
+	return /* @__PURE__ */ jsxs("footer", {
+		"data-yd": "footer",
+		className,
+		children: [site.footerHtml ? /* @__PURE__ */ jsx(Html, {
+			html: site.footerHtml,
+			"data-yd": "footer-text"
+		}) : null, site.llms.txtUrl ? /* @__PURE__ */ jsx("a", {
+			href: site.llms.txtUrl,
+			"data-yd": "llms-link",
+			children: "llms.txt"
+		}) : null]
+	});
+});
+const declarations = (vars) => Object.entries(vars).filter(([, value]) => value).map(([key, value]) => `${key}:${value.replace(/[;{}<]/g, "")}`).join(";");
+/**
+* Branding as CSS custom properties on :root:
+* `--yd-color-primary`, `--yd-color-accent`, `--yd-color-background`, `--yd-color-foreground`,
+* `--yd-font-sans`, `--yd-font-mono` (with per-mode overrides under `[data-theme]`).
+*/
+function brandingCss(site) {
+	const { colors, fonts } = site;
+	const base = declarations({
+		"--yd-color-primary": colors.primary,
+		"--yd-color-accent": colors.accent,
+		"--yd-font-sans": fonts.sans,
+		"--yd-font-mono": fonts.mono
+	});
+	const mode = (c) => declarations({
+		"--yd-color-primary": c?.primary,
+		"--yd-color-accent": c?.accent,
+		"--yd-color-background": c?.background,
+		"--yd-color-foreground": c?.foreground
+	});
+	const light = mode(colors.light);
+	const dark = mode(colors.dark);
+	return [
+		base && `:root{${base}}`,
+		light && `:root[data-theme="light"]{${light}}`,
+		dark && `:root[data-theme="dark"]{${dark}}@media (prefers-color-scheme:dark){:root:not([data-theme]){${dark}}}`
+	].filter(Boolean).join("");
+}
+function BrandingStyles() {
+	const css = brandingCss(useSite());
+	return css ? /* @__PURE__ */ jsx("style", {
+		"data-yd": "branding",
+		dangerouslySetInnerHTML: { __html: css }
+	}) : null;
+}
+/**
+* "Run in Yaak" link for the site's shareable export (renders nothing unless `runInYaak` is enabled
+* in the config).
+*/
+const RunInYaak = overridable("RunInYaak", function RunInYaak({ badge, className }) {
+	const runInYaak = useRunInYaak();
+	if (!runInYaak) return null;
+	return /* @__PURE__ */ jsx(RunInYaakLink, {
+		name: runInYaak.name,
+		dataUrl: runInYaak.dataUrl,
+		...badge ? { badge } : {},
+		...className ? { className } : {}
+	});
+});
+//#endregion
+export { useRequest as C, usePage as S, useThemeOptions as T, useRunInYaak as _, SiteLinks as a, useDocument as b, Html as c, MethodBadge as d, RequestUrl as f, usePageActions as g, useComponents as h, RunInYaak as i, KeyValueTable as l, overridable as m, Footer as n, brandingCss as o, ComponentsProvider as p, Logo as r, AuthInfo as s, BrandingStyles as t, Markdown as u, toAbsoluteUrl as v, useSite as w, useFolder as x, YaakdocProvider as y };

package/dist/theme.d.ts

@@ -0,0 +1,45 @@
+import { _ as ThemeRuntime, g as ThemeComponents, o as LayoutProps } from "./types-BY2lOvlK.js";
+//#region src/theme.d.ts
+/**
+ * Node-side theme manifest. This module must stay free of React/runtime imports: it is loaded by the
+ * yaakdoc engine in Node to discover the theme's files and Vite plugins.
+ */
+/** Anything with a `parse` method (e.g. a Zod schema) can validate theme options. */
+export type OptionsValidator = {
+  parse(input: unknown): unknown;
+};
+export type ThemeDefinition = {
+  /** Theme name, e.g. "kiseki". */
+  name: string;
+  /**
+   * Server entry module (relative to the manifest file, or absolute). Its default export is a
+   * `ThemeRuntime`: `{ Layout, components?, Head? }`. Processed by Vite, so TSX source is fine.
+   */
+  entry: string;
+  /**
+   * Client entry module that hydrates islands, e.g.
+   * `hydrateIslands([...builtinIslands, MyIsland])`. Defaults to hydrating the built-in islands.
+   */
+  client?: string;
+  /** CSS entry files (relative to the manifest), loaded in order. */
+  styles?: string[];
+  /** Vite plugins the theme needs (e.g. Tailwind). */
+  vitePlugins?: () => any[] | Promise<any[]>;
+  /** Shiki themes for syntax highlighting (default: github-light / github-dark). */
+  highlight?: {
+    light: string;
+    dark: string;
+  };
+  /** Validates/defaults `themeOptions` from the config. */
+  options?: OptionsValidator;
+  /** What `yaakdoc eject` copies (globs relative to the manifest directory). */
+  eject?: {
+    files?: string[];
+    /** Packages the ejected theme imports; printed after ejecting. */
+    dependencies?: string[];
+  };
+};
+/** Defines a yaakdoc theme. */
+export declare function defineTheme(definition: ThemeDefinition): ThemeDefinition;
+//#endregion
+export type { LayoutProps, ThemeComponents, ThemeRuntime };

package/dist/theme.js

@@ -0,0 +1,7 @@
+//#region src/theme.ts
+/** Defines a yaakdoc theme. */
+function defineTheme(definition) {
+	return definition;
+}
+//#endregion
+export { defineTheme };

package/dist/types-BY2lOvlK.d.ts

@@ -0,0 +1,101 @@
+import { EnvironmentRef, PreparedDocument } from "@yaakdoc/core";
+import { ComponentType, ReactNode } from "react";
+import { Branding, HeadTag, ResolvedConfig } from "@yaakdoc/config";
+//#region src/types.d.ts
+type ColorMode = "light" | "dark";
+type ColorModePreference = Branding["defaultColorMode"];
+type SiteColors = NonNullable<Branding["colors"]>;
+type ModeColors = NonNullable<SiteColors["light"]>;
+type SiteFonts = NonNullable<Branding["fonts"]>;
+type LlmProvider = ResolvedConfig["llms"]["openIn"][number];
+/** An environment readers can switch to. */
+type EnvironmentOption = EnvironmentRef;
+/** Logo with local paths resolved to public URLs. */
+type SiteLogo = {
+  light?: string;
+  dark?: string;
+  alt: string;
+  href: string;
+  width?: number;
+  height?: number;
+};
+/** Site-wide, serializable data derived from the yaakdoc config and the export. */
+type SiteData = {
+  title: string;
+  description: string;
+  /** Absolute public URL of the deployed site, if configured. */
+  url: string | null;
+  /** Base path, always with leading and trailing slash. */
+  base: string;
+  pages: ResolvedConfig["pages"];
+  logo: SiteLogo | null;
+  favicon: string | null;
+  colors: SiteColors;
+  fonts: SiteFonts;
+  links: Branding["links"];
+  /** Footer rendered from Markdown. */
+  footerHtml: string | null;
+  defaultColorMode: ColorModePreference;
+  colorModeToggle: boolean;
+  llms: ResolvedConfig["llms"] & {
+    /** URL of llms.txt, when enabled. */
+    txtUrl: string | null;
+    fullTxtUrl: string | null;
+  };
+  showVariables: boolean;
+  /** "Run in Yaak" button, when enabled. */
+  runInYaak: {
+    name: string;
+    /** URL of the importable export (may be relative to the site when `url` is unknown). */
+    dataUrl: string;
+  } | null;
+  head: HeadTag[];
+  themeOptions: Record<string, unknown>;
+  /** e.g. "yaakdoc 1.0.0" */
+  generator: string;
+};
+type PageKind = "index" | "folder" | "request" | "not-found";
+type PageData = {
+  kind: PageKind;
+  /** Folder or request id for `folder` / `request` pages. */
+  id: string | null;
+  /** Route path, e.g. `/` or `/docs/products/get-a-product/`. */
+  path: string;
+  /** Document title (without the site title suffix). */
+  title: string;
+  description: string;
+  /** Markdown twin of this page, if any. */
+  markdownUrl: string | null;
+};
+type Assets = {
+  styles: string[];
+  scripts: string[];
+  /** Inline styles (dev mode). `id` is used for HMR (`data-vite-dev-id`). */
+  inlineStyles: Array<{
+    id: string;
+    css: string;
+  }>;
+  modulePreloads: string[];
+};
+type LayoutProps = {
+  page: PageData;
+};
+type ThemeComponents = Partial<Record<string, ComponentType<any>>>;
+/** Runtime part of a theme (rendered by the SSR entry). */
+type ThemeRuntime = {
+  Layout: ComponentType<LayoutProps>;
+  /** Overrides for base components (by component name, e.g. `MethodBadge`). */
+  components?: ThemeComponents;
+  /** Extra elements rendered in <head>. */
+  Head?: ComponentType<{
+    page: PageData;
+  }>;
+};
+type RenderContext = {
+  document: PreparedDocument;
+  site: SiteData;
+  page: PageData;
+  children?: ReactNode;
+};
+//#endregion
+export { ThemeRuntime as _, HeadTag as a, ModeColors as c, RenderContext as d, SiteColors as f, ThemeComponents as g, SiteLogo as h, EnvironmentOption as i, PageData as l, SiteFonts as m, ColorMode as n, LayoutProps as o, SiteData as p, ColorModePreference as r, LlmProvider as s, Assets as t, PageKind as u };

package/package.json

@@ -1,6 +1,88 @@
 {
   "name": "@yaakdoc/react",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "description": "Unstyled, composable React components and the island runtime for yaakdoc themes.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "@yaakdoc/source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./islands": {
+      "@yaakdoc/source": "./src/islands/index.ts",
+      "types": "./dist/islands.d.ts",
+      "default": "./dist/islands.js"
+    },
+    "./client": {
+      "@yaakdoc/source": "./src/client.ts",
+      "types": "./dist/client.d.ts",
+      "default": "./dist/client.js"
+    },
+    "./server": {
+      "@yaakdoc/source": "./src/server.tsx",
+      "types": "./dist/server.d.ts",
+      "default": "./dist/server.js"
+    },
+    "./theme": {
+      "@yaakdoc/source": "./src/theme.ts",
+      "types": "./dist/theme.d.ts",
+      "default": "./dist/theme.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "sideEffects": false,
+  "keywords": [
+    "yaak",
+    "yaakdoc",
+    "react",
+    "components",
+    "headless",
+    "theme"
+  ],
+  "author": "József Sallai @jozsefsallai",
+  "license": "MIT",
+  "files": [
+    "/dist",
+    "/README.md",
+    "/LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jozsefsallai/yaakdoc.git",
+    "directory": "packages/react"
+  },
+  "bugs": {
+    "url": "https://github.com/jozsefsallai/yaakdoc/issues"
+  },
+  "homepage": "https://github.com/jozsefsallai/yaakdoc#readme",
+  "engines": {
+    "node": ">=20.19"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@repo/tsconfig": "0.0.0",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "react": "^19.3.1",
+    "react-dom": "^19.3.1"
+  },
+  "dependencies": {
+    "@yaakdoc/config": "^0.2.0",
+    "@yaakdoc/core": "^0.2.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch --no-clean",
+    "test": "vitest run",
+    "check-types": "tsc",
+    "lint": "biome lint .",
+    "lint:fix": "biome lint . --write",
+    "format": "biome format . --write"
+  }
 }