@yaakdoc/react 0.0.0-stage → 0.2.0

package/dist/index-CoQ7pnuB.d.ts

@@ -0,0 +1,471 @@
+import { t as IslandComponent } from "./island-BWyuL4_6.js";
+import { g as ThemeComponents, l as PageData, p as SiteData } from "./types-BY2lOvlK.js";
+import { Auth, Header, KeyValue, PreparedDocument, PreparedFolder, PreparedRequest, TreeNode, methodLabel as methodLabel$1 } from "@yaakdoc/core";
+import { ComponentPropsWithoutRef, ComponentType, ReactNode } from "react";
+//#region src/context.d.ts
+type YaakdocContextValue = {
+  document: PreparedDocument;
+  site: SiteData;
+  page: PageData;
+};
+declare function YaakdocProvider({ document, site, page, children }: YaakdocContextValue & {
+  children: ReactNode;
+}): import("react").JSX.Element;
+/** The prepared documentation (requests, folders, tree, environment...). */
+declare const useDocument: () => PreparedDocument;
+/** Site configuration and branding. */
+declare const useSite: () => SiteData;
+/** The page currently being rendered. */
+declare const usePage: () => PageData;
+/** Theme-specific options from `themeOptions` in the config. */
+declare const useThemeOptions: <T extends Record<string, unknown>>() => T;
+declare function useRequest(id: string): PreparedRequest;
+declare function useFolder(id: string): PreparedFolder;
+//#endregion
+//#region src/hooks.d.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.
+ */
+declare function usePageActions(markdownUrl: string | null): {
+  markdownUrl: string;
+  absoluteUrl: string | null;
+  openIn: ("chatgpt" | "claude" | "perplexity")[];
+} | null;
+/** Name and export URL for the "Run in Yaak" button, or `null` when it is disabled. */
+declare function useRunInYaak(): {
+  name: string;
+  dataUrl: string;
+} | null;
+//#endregion
+//#region src/islands/tabs.d.ts
+declare const TAB_STORAGE_KEY = "yaakdoc-tab";
+/** Tab group names of a request's code examples and example responses. */
+declare const tabGroupIds: {
+  examples: (anchor: string) => string;
+  responses: (anchor: string) => string;
+};
+/** Ids linking a tab to its panel. `variant` tells apart copies of a panel (one per environment). */
+declare function tabElementIds(group: string, id: string, variant?: number): {
+  tab: string;
+  panel: string;
+};
+/** Props for a server-rendered panel controlled by {@link TabList}. */
+declare function tabPanelProps(group: string, id: string, options: {
+  selected: boolean;
+  variant?: number;
+}): {
+  readonly role: "tabpanel";
+  readonly id: string;
+  readonly "aria-labelledby": string;
+  readonly "data-yd-tab-panel": string;
+  readonly hidden: boolean;
+};
+/** Selector of an element (default: the code) inside the visible panel of a tab group. */
+declare const visibleTabPanelSelector: (group: string, inner?: string) => string;
+/**
+ * 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.
+ */
+declare function useTabs(group: string, ids: readonly string[], sync?: boolean): {
+  selected: string;
+  select: (id: string, broadcast?: boolean) => void;
+};
+type TabListProps = {
+  group: string;
+  tabs: Array<{
+    id: string;
+    label: string;
+    className?: string;
+  }>;
+  sync?: boolean;
+  className?: string;
+  tabClassName?: string;
+  label?: string;
+};
+/** Accessible tab list controlling server-rendered panels (see {@link useTabs}). */
+declare const TabList: IslandComponent<TabListProps>;
+//#endregion
+//#region src/overrides.d.ts
+/**
+ * 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.
+ */
+declare function ComponentsProvider({ components, children }: {
+  components: ThemeComponents | undefined;
+  children: ReactNode;
+}): import("react").JSX.Element;
+declare const useComponents: () => ThemeComponents;
+/**
+ * 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.
+ */
+declare function overridable<P extends object>(name: string, Default: ComponentType<P>): ComponentType<P> & {
+  displayName: string;
+  Default: ComponentType<P>;
+};
+//#endregion
+//#region src/primitives/basic.d.ts
+/** Renders trusted, pre-sanitized HTML (descriptions are sanitized at build time). */
+declare const Html: import("react").ComponentType<{
+  html: string;
+  as?: "div" | "span" | "section";
+} & Omit<Omit<import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref">, "children">> & {
+  displayName: string;
+  Default: import("react").ComponentType<{
+    html: string;
+    as?: "div" | "span" | "section";
+  } & Omit<Omit<import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref">, "children">>;
+};
+/** Rendered Markdown (a description). */
+declare const Markdown: import("react").ComponentType<{
+  html: string;
+  className?: string;
+}> & {
+  displayName: string;
+  Default: import("react").ComponentType<{
+    html: string;
+    className?: string;
+  }>;
+};
+/** HTTP method (or gRPC / WS) badge. Style via `[data-method="get"]` etc. */
+declare const MethodBadge: import("react").ComponentType<{
+  request: PreparedRequest;
+  className?: string;
+}> & {
+  displayName: string;
+  Default: import("react").ComponentType<{
+    request: PreparedRequest;
+    className?: string;
+  }>;
+};
+/**
+ * Request URL with `{{variables}}` and `:path` parameters wrapped in spans
+ * (`[data-yd="url-variable"]`, `[data-yd="url-param"]`) for styling.
+ */
+declare const RequestUrl: import("react").ComponentType<{
+  url: string;
+  className?: string;
+}> & {
+  displayName: string;
+  Default: import("react").ComponentType<{
+    url: string;
+    className?: string;
+  }>;
+};
+type KeyValueTableProps = {
+  items: Array<KeyValue | Header>;
+  caption?: ReactNode;
+  columns?: [string, string];
+  className?: string;
+  /** Show an "inherited from ..." note for headers inherited from folders/workspace. */
+  showInherited?: boolean;
+};
+/** Generic two-column table for headers and parameters. */
+declare const KeyValueTable: import("react").ComponentType<KeyValueTableProps> & {
+  displayName: string;
+  Default: import("react").ComponentType<KeyValueTableProps>;
+};
+/** Describes the effective authentication of a request/folder. */
+declare const AuthInfo: import("react").ComponentType<{
+  auth: Auth | null;
+  className?: string;
+}> & {
+  displayName: string;
+  Default: import("react").ComponentType<{
+    auth: Auth | null;
+    className?: string;
+  }>;
+};
+//#endregion
+//#region src/primitives/code.d.ts
+type CodeBlockProps = {
+  /** Pre-highlighted HTML (a Shiki `<pre>`). */
+  html: string;
+  /** Unique id; used by the copy button to find the code. */
+  id: string;
+  language?: string;
+  title?: string;
+  copy?: boolean;
+  className?: string;
+};
+declare const CodeBlock: import("react").ComponentType<CodeBlockProps> & {
+  displayName: string;
+  Default: import("react").ComponentType<CodeBlockProps>;
+};
+type CodeExamplesProps = {
+  request: PreparedRequest;
+  className?: string;
+  title?: string;
+};
+/** Tabbed code examples. Panels are static HTML; only the tab list hydrates. */
+declare const CodeExamples: import("react").ComponentType<CodeExamplesProps> & {
+  displayName: string;
+  Default: import("react").ComponentType<CodeExamplesProps>;
+};
+type ResponseExamplesProps = {
+  request: PreparedRequest;
+  className?: string;
+  title?: string;
+};
+/**
+ * Example responses (from ```response / ```response:<status> blocks in the description), tabbed by
+ * status. Tabs carry `data-status-class` (`2xx`, `4xx`, ...) for styling.
+ */
+declare const ResponseExamples: import("react").ComponentType<ResponseExamplesProps> & {
+  displayName: string;
+  Default: import("react").ComponentType<ResponseExamplesProps>;
+};
+/** `2xx`, `4xx`, ... or `undefined` for responses without a status. */
+declare const statusClass: (status: number | null) => string | undefined;
+//#endregion
+//#region src/primitives/content.d.ts
+type FolderDocProps = {
+  id: string;
+  level?: number;
+  /** Also render the folder's contents (requests and sub folders). */
+  nested?: boolean;
+  className?: string;
+};
+/** A folder section: title, description, inherited auth, then (optionally) its contents. */
+declare const FolderDoc: import("react").ComponentType<FolderDocProps> & {
+  displayName: string;
+  Default: import("react").ComponentType<FolderDocProps>;
+};
+/** Renders a list of tree nodes as documentation sections, recursively. */
+declare const TreeContent: import("react").ComponentType<{
+  nodes: TreeNode[];
+  level?: number;
+}> & {
+  displayName: string;
+  Default: import("react").ComponentType<{
+    nodes: TreeNode[];
+    level?: number;
+  }>;
+};
+/** Overview of the workspace: description, authentication and variables. */
+declare const Overview: import("react").ComponentType<{
+  className?: string;
+  level?: number;
+}> & {
+  displayName: string;
+  Default: import("react").ComponentType<{
+    className?: string;
+    level?: number;
+  }>;
+};
+/** Environment variables table (secrets redacted). */
+declare const Variables: import("react").ComponentType<{
+  level?: number;
+  className?: string;
+}> & {
+  displayName: string;
+  Default: import("react").ComponentType<{
+    level?: number;
+    className?: string;
+  }>;
+};
+/**
+ * The main content for the current page: everything (single-page mode), a folder, a request, or a
+ * not-found message. Themes can use this or compose the pieces themselves.
+ */
+declare const Content: import("react").ComponentType<{
+  className?: string;
+}> & {
+  displayName: string;
+  Default: import("react").ComponentType<{
+    className?: string;
+  }>;
+};
+/** Content of the 404 page. */
+declare const NotFound: import("react").ComponentType<{
+  className?: string;
+}> & {
+  displayName: string;
+  Default: import("react").ComponentType<{
+    className?: string;
+  }>;
+};
+/** List of links to child folders/requests (per-request pages mode). */
+declare const ChildLinks: import("react").ComponentType<{
+  nodes: TreeNode[];
+  className?: string;
+}> & {
+  displayName: string;
+  Default: import("react").ComponentType<{
+    nodes: TreeNode[];
+    className?: string;
+  }>;
+};
+//#endregion
+//#region src/primitives/environment.d.ts
+/**
+ * Renders environment-dependent content once per environment variant. With several variants, each
+ * is wrapped in `<div data-yd-env="<id>">` (only the default is visible until the reader switches).
+ */
+declare function EnvironmentVariants<T extends {
+  environmentId: string | null;
+}>({ variants, children }: {
+  variants: readonly T[];
+  children: (variant: T, index: number) => ReactNode;
+}): import("react").JSX.Element;
+/** Environment switcher for the current document (renders nothing without alternatives). */
+declare const EnvironmentSelect: import("react").ComponentType<{
+  className?: string;
+}> & {
+  displayName: string;
+  Default: import("react").ComponentType<{
+    className?: string;
+  }>;
+};
+//#endregion
+//#region src/primitives/heading.d.ts
+type HeadingLevel = 1 | 2 | 3 | 4 | 5 | 6;
+/** Clamps any number to a valid heading level (1–6). */
+declare const clampHeadingLevel: (level: number) => HeadingLevel;
+/** `<h1>`–`<h6>` chosen by `level` (clamped), for headings whose depth depends on nesting. */
+declare function Heading({ level, ...props }: {
+  level: number;
+} & ComponentPropsWithoutRef<"h2">): import("react").JSX.Element;
+//#endregion
+//#region src/primitives/llm.d.ts
+/**
+ * "Copy page" actions: copy as Markdown, view as Markdown, open in ChatGPT/Claude. Uses a native
+ * `<details>` menu, so it works without JavaScript (except copying).
+ */
+/** Label of a copy action for an item at heading `level`: the page itself (1) or a section. */
+declare const copyActionLabel: (level: number) => "Copy page" | "Copy section";
+declare const PageActions: import("react").ComponentType<{
+  markdownUrl: string | null;
+  /** "Copy page" for the page itself, "Copy section" for sections within a page. */
+  label?: string;
+  className?: string;
+}> & {
+  displayName: string;
+  Default: import("react").ComponentType<{
+    markdownUrl: string | null;
+    /** "Copy page" for the page itself, "Copy section" for sections within a page. */
+    label?: string;
+    className?: string;
+  }>;
+};
+//#endregion
+//#region src/primitives/nav.d.ts
+type NavTreeProps = {
+  nodes?: TreeNode[];
+  className?: string;
+  /** Folders deeper than this are collapsed by default (unless they contain the current page). */
+  openDepth?: number;
+};
+/**
+ * Navigation tree. Folders use native `<details>` (collapsible without JavaScript). Items carry
+ * `data-yd-nav-item` / `data-yd-nav-folder` for the `NavFilter` island, and the current page link
+ * gets `aria-current="page"`.
+ */
+declare const NavTree: import("react").ComponentType<NavTreeProps> & {
+  displayName: string;
+  Default: import("react").ComponentType<NavTreeProps>;
+};
+/** Breadcrumb trail of the current request/folder. */
+declare const Breadcrumbs: import("react").ComponentType<{
+  id: string;
+  className?: string;
+}> & {
+  displayName: string;
+  Default: import("react").ComponentType<{
+    id: string;
+    className?: string;
+  }>;
+};
+//#endregion
+//#region src/primitives/request.d.ts
+declare const RequestBody: import("react").ComponentType<{
+  request: PreparedRequest;
+  className?: string;
+}> & {
+  displayName: string;
+  Default: import("react").ComponentType<{
+    request: PreparedRequest;
+    className?: string;
+  }>;
+};
+type RequestDocProps = {
+  request: PreparedRequest;
+  /** Heading level of the request title. */
+  level?: HeadingLevel;
+  className?: string;
+  /** Render code examples inline (default) or not at all (themes may render them elsewhere). */
+  examples?: boolean;
+};
+/**
+ * Complete documentation section for a request: title, method, URL, description, auth, parameters,
+ * headers, body and code examples. Each sub-part is overridable on its own.
+ */
+declare const RequestDoc: import("react").ComponentType<RequestDocProps> & {
+  displayName: string;
+  Default: import("react").ComponentType<RequestDocProps>;
+};
+//#endregion
+//#region src/primitives/site.d.ts
+/** Site logo (light/dark variants) linking to the docs home, falling back to the title. */
+declare const Logo: import("react").ComponentType<{
+  className?: string;
+  showTitle?: boolean;
+}> & {
+  displayName: string;
+  Default: import("react").ComponentType<{
+    className?: string;
+    showTitle?: boolean;
+  }>;
+};
+/** Header links from `branding.links`. */
+declare const SiteLinks: import("react").ComponentType<{
+  className?: string;
+}> & {
+  displayName: string;
+  Default: import("react").ComponentType<{
+    className?: string;
+  }>;
+};
+/** Footer text from `branding.footer` plus an llms.txt link. */
+declare const Footer: import("react").ComponentType<{
+  className?: string;
+}> & {
+  displayName: string;
+  Default: import("react").ComponentType<{
+    className?: string;
+  }>;
+};
+/**
+ * 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]`).
+ */
+declare function brandingCss(site: Pick<SiteData, "colors" | "fonts">): string;
+declare function BrandingStyles(): import("react").JSX.Element | null;
+/**
+ * "Run in Yaak" link for the site's shareable export (renders nothing unless `runInYaak` is enabled
+ * in the config).
+ */
+declare const RunInYaak: import("react").ComponentType<{
+  badge?: boolean;
+  className?: string;
+}> & {
+  displayName: string;
+  Default: import("react").ComponentType<{
+    badge?: boolean;
+    className?: string;
+  }>;
+};
+//#endregion
+//#region src/site-url.d.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).
+ */
+declare function toAbsoluteUrl(site: Pick<SiteData, "url" | "base">, path: string): string | null;
+//#endregion
+export { useTabs as $, CodeBlock as A, KeyValueTableProps as B, Content as C, Overview as D, NotFound as E, ResponseExamplesProps as F, overridable as G, MethodBadge as H, statusClass as I, TabList as J, useComponents as K, AuthInfo as L, CodeExamples as M, CodeExamplesProps as N, TreeContent as O, ResponseExamples as P, tabPanelProps as Q, Html as R, ChildLinks as S, FolderDocProps as T, RequestUrl as U, Markdown as V, ComponentsProvider as W, tabElementIds as X, TabListProps as Y, tabGroupIds as Z, Heading as _, Logo as a, useFolder as at, EnvironmentSelect as b, brandingCss as c, useSite as ct, RequestDocProps as d, visibleTabPanelSelector as et, Breadcrumbs as f, copyActionLabel as g, PageActions as h, Footer as i, useDocument as it, CodeBlockProps as j, Variables as k, RequestBody as l, useThemeOptions as lt, NavTreeProps as m, toAbsoluteUrl as n, useRunInYaak as nt, RunInYaak as o, usePage as ot, NavTree as p, TAB_STORAGE_KEY as q, BrandingStyles as r, YaakdocProvider as rt, SiteLinks as s, useRequest as st, methodLabel$1 as t, usePageActions as tt, RequestDoc as u, HeadingLevel as v, FolderDoc as w, EnvironmentVariants as x, clampHeadingLevel as y, KeyValueTable as z };

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+import { n as createIsland, t as IslandComponent } from "./island-BWyuL4_6.js";
+import { _ as ThemeRuntime, a as HeadTag, c as ModeColors, d as RenderContext, f as SiteColors, g as ThemeComponents, h as SiteLogo, i as EnvironmentOption, l as PageData, m as SiteFonts, n as ColorMode, o as LayoutProps, p as SiteData, r as ColorModePreference, s as LlmProvider, t as Assets, u as PageKind } from "./types-BY2lOvlK.js";
+import { A as CodeBlock, B as KeyValueTableProps, C as Content, D as Overview, E as NotFound, F as ResponseExamplesProps, G as overridable, H as MethodBadge, I as statusClass, J as TabList, K as useComponents, L as AuthInfo, M as CodeExamples, N as CodeExamplesProps, O as TreeContent, P as ResponseExamples, Q as tabPanelProps, R as Html, S as ChildLinks, T as FolderDocProps, U as RequestUrl, V as Markdown, W as ComponentsProvider, X as tabElementIds, Z as tabGroupIds, _ as Heading, a as Logo, at as useFolder, b as EnvironmentSelect, c as brandingCss, ct as useSite, d as RequestDocProps, et as visibleTabPanelSelector, f as Breadcrumbs, g as copyActionLabel, h as PageActions, i as Footer, it as useDocument, j as CodeBlockProps, k as Variables, l as RequestBody, lt as useThemeOptions, m as NavTreeProps, n as toAbsoluteUrl, nt as useRunInYaak, o as RunInYaak, ot as usePage, p as NavTree, r as BrandingStyles, rt as YaakdocProvider, s as SiteLinks, st as useRequest, t as methodLabel, tt as usePageActions, u as RequestDoc, v as HeadingLevel, w as FolderDoc, x as EnvironmentVariants, y as clampHeadingLevel, z as KeyValueTable } from "./index-CoQ7pnuB.js";
+export { type Assets, AuthInfo, BrandingStyles, Breadcrumbs, ChildLinks, CodeBlock, type CodeBlockProps, CodeExamples, type CodeExamplesProps, type ColorMode, type ColorModePreference, ComponentsProvider, Content, type EnvironmentOption, EnvironmentSelect, EnvironmentVariants, FolderDoc, type FolderDocProps, Footer, type HeadTag, Heading, type HeadingLevel, Html, type IslandComponent, KeyValueTable, type KeyValueTableProps, type LayoutProps, type LlmProvider, Logo, Markdown, MethodBadge, type ModeColors, NavTree, type NavTreeProps, NotFound, Overview, PageActions, type PageData, type PageKind, type RenderContext, RequestBody, RequestDoc, type RequestDocProps, RequestUrl, ResponseExamples, type ResponseExamplesProps, RunInYaak, type SiteColors, type SiteData, type SiteFonts, SiteLinks, type SiteLogo, TabList, type ThemeComponents, type ThemeRuntime, TreeContent, Variables, YaakdocProvider, brandingCss, clampHeadingLevel, copyActionLabel, createIsland, methodLabel, overridable, statusClass, tabElementIds, tabGroupIds, tabPanelProps, toAbsoluteUrl, useComponents, useDocument, useFolder, usePage, usePageActions, useRequest, useRunInYaak, useSite, useThemeOptions, visibleTabPanelSelector };