@blaaiz/docs-core 0.1.0

package/dist/ui.d.ts

@@ -0,0 +1,428 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+import { D as DocsConfig, N as Navigation, l as NavPage } from './navigation-CGqFIPlP.js';
+
+/**
+ * Accordion components — the Mintlify `<Accordion>` and `<AccordionGroup>`.
+ * Built on the native `<details>` element, so they are interactive with zero
+ * client JavaScript and render in a Server Component. The hairline uses the
+ * framework's border token, so it follows the site's palette and the dark theme.
+ *
+ * @packageDocumentation
+ */
+/**
+ * A single collapsible section.
+ *
+ * @public
+ */
+declare function Accordion({ title, children }: {
+    title: string;
+    children?: ReactNode;
+}): react.JSX.Element;
+/**
+ * A group of accordions.
+ *
+ * @public
+ */
+declare function AccordionGroup({ children }: {
+    children?: ReactNode;
+}): react.JSX.Element;
+
+/**
+ * The Mintlify-style API operation layout: one two-column row for the whole
+ * operation, so the code rail starts level with the endpoint title. Pass it to
+ * fumadocs-openapi — the slots type is structural, so this module needs no
+ * fumadocs dependency and the site keeps ownership of that package.
+ *
+ * @example
+ * ```tsx
+ * export const APIPage = createOpenAPIPage({
+ *   content: { renderOperationLayout: apiOperationLayout },
+ * });
+ * ```
+ *
+ * @packageDocumentation
+ */
+/**
+ * The slots fumadocs-openapi hands to `renderOperationLayout`.
+ *
+ * @public
+ */
+interface ApiOperationSlots {
+    readonly header: ReactNode;
+    readonly description: ReactNode;
+    readonly apiPlayground: ReactNode;
+    readonly authSchemes: ReactNode;
+    readonly parameters: ReactNode;
+    readonly body: ReactNode;
+    readonly responses: ReactNode;
+    readonly callbacks: ReactNode;
+    readonly apiExample: ReactNode;
+}
+/**
+ * Render an API operation as title → description → playground → request details
+ * on the left, with the code/response rail as the right column. Pair with
+ * `@blaaiz/docs-core/styles/api-reference.css`, which anchors the rail to the
+ * viewport.
+ *
+ * @param slots - the operation slots from fumadocs-openapi
+ * @returns the two-column operation layout
+ * @public
+ */
+declare function apiOperationLayout(slots: ApiOperationSlots): ReactNode;
+
+/**
+ * Sidebar helpers for the API reference: a coloured HTTP-method badge and a
+ * page-tree transformer that prefixes each API page's sidebar entry with it —
+ * the Mintlify look (POST · GET · … next to the endpoint name). Server-
+ * compatible; styled by `styles/api-reference.css`.
+ *
+ * @packageDocumentation
+ */
+/**
+ * A coloured HTTP-method pill (GET, POST, …).
+ *
+ * @param props - the HTTP method
+ * @public
+ */
+declare function MethodBadge({ method }: {
+    method: string;
+}): react.JSX.Element;
+/**
+ * The minimal page-tree item this transformer touches. Structural, so the
+ * framework needs no fumadocs types; a site passes the result straight into
+ * `loader({ pageTree: { transformers } })`.
+ *
+ * @public
+ */
+interface SidebarItem {
+    readonly type?: string;
+    readonly url?: string;
+    name?: ReactNode;
+}
+/**
+ * A page-tree transformer with a `file` hook, generic over the tree's own item
+ * type so it slots into fumadocs' `loader({ pageTree: { transformers } })`
+ * without a cast: `file` returns exactly the item type it was given.
+ *
+ * @public
+ */
+interface SidebarBadgeTransformer {
+    file<T extends SidebarItem>(node: T): T;
+}
+/**
+ * A page-tree transformer that prefixes every API page's sidebar entry with its
+ * HTTP-method badge, matching endpoint URLs against the `methods` map the
+ * generator emits (`content/api-methods.json`).
+ *
+ * @example
+ * ```ts
+ * import methods from '@/content/api-methods.json';
+ * loader({ pageTree: { transformers: [apiMethodBadges(methods)] } });
+ * ```
+ *
+ * @param methods - map of page URL to HTTP method
+ * @returns a transformer with a `file` hook
+ * @public
+ */
+declare function apiMethodBadges(methods: Readonly<Record<string, string>>): SidebarBadgeTransformer;
+
+/**
+ * The sign-in screen for a workspace-gated docs site.
+ *
+ * A site renders one element — `<AuthScreen config={config} .../>` — and gets
+ * the whole gate: brand, the allowed-domain note, the providers its config
+ * declares (email, shared secret, Google), and an inline error banner. The
+ * shared-secret provider is a two-step flow — email, then secret — rendered by
+ * the `step` prop. The framework owns the layout and copy; the site owns only
+ * its config. Server-rendered: every form is a native POST, no client JS.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Map a sign-in error code (carried on `?error=` after a failed attempt) to a
+ * human sentence. Unknown codes get a safe generic message.
+ *
+ * @param code - the error code, or undefined
+ * @param domains - the allowed email domains, for the domain-mismatch message
+ * @returns the message to show, or null when there is no error
+ * @public
+ */
+declare function authErrorMessage(code: string | undefined, domains: readonly string[]): string | null;
+/**
+ * Props for {@link AuthScreen}.
+ *
+ * @public
+ */
+interface AuthScreenProps {
+    /** The site configuration; drives brand, providers, and allowed domains. */
+    readonly config: DocsConfig;
+    /** The path to return to after sign-in (from the gate's `?from=`). */
+    readonly from?: string;
+    /** A sign-in error code to surface inline (from `?error=`). */
+    readonly error?: string;
+    /**
+     * Which step of the shared-secret flow to render. `'email'` (default) shows
+     * the email field; `'secret'` shows the secret field for the already-validated
+     * {@link AuthScreenProps.email}. Ignored unless the secret provider is enabled.
+     */
+    readonly step?: 'email' | 'secret';
+    /** The domain-checked email to show on the secret step (from the site's cookie). */
+    readonly email?: string;
+    /**
+     * Whether to offer the shared-secret flow. Defaults to whether config declares
+     * the secret provider; pass `false` when its env secret is absent. When on, it
+     * supersedes plain email sign-in.
+     */
+    readonly secretEnabled?: boolean;
+    /**
+     * Whether to offer the Google button. Defaults to whether config declares the
+     * Google provider; pass `false` to hide it when its env vars are absent.
+     */
+    readonly googleEnabled?: boolean;
+    /** The email sign-in endpoint. Default `/api/auth/email`. */
+    readonly emailAction?: string;
+    /** The shared-secret sign-in endpoint (both steps post here). Default `/api/auth/secret`. */
+    readonly secretAction?: string;
+    /** The Google sign-in start path. Default `/api/auth/google/start`. */
+    readonly googleStartPath?: string;
+    /** The sign-in page path, for the "use a different email" link. Default `/signin`. */
+    readonly signInPath?: string;
+}
+/**
+ * Render the sign-in screen.
+ *
+ * @param props - see {@link AuthScreenProps}
+ * @public
+ */
+declare function AuthScreen(props: AuthScreenProps): ReactNode;
+
+/**
+ * Callout components — the Mintlify `<Note>`, `<Warning>`, `<Info>`, and `<Tip>`
+ * blocks. Server-compatible: no client state, so they render in a React Server
+ * Component without a `'use client'` boundary.
+ *
+ * The box is styled by the `.cl` classes in `@blaaiz/docs-core/styles/docs.css`,
+ * which a site already imports. That is what makes a callout follow the dark
+ * theme: the class set carries a light and a dark palette per tone, where the
+ * inline colours these components used before could only ever be light.
+ *
+ * @packageDocumentation
+ */
+type Tone = 'note' | 'warning' | 'info' | 'tip';
+/**
+ * A tinted callout box with the tone's icon.
+ *
+ * @public
+ */
+declare function Callout({ tone, children }: {
+    tone?: Tone;
+    children?: ReactNode;
+}): react.JSX.Element;
+/** Mintlify `<Note>`. @public */
+declare function Note({ children }: {
+    children?: ReactNode;
+}): react.JSX.Element;
+/** Mintlify `<Warning>`. @public */
+declare function Warning({ children }: {
+    children?: ReactNode;
+}): react.JSX.Element;
+/** Mintlify `<Info>`. @public */
+declare function Info({ children }: {
+    children?: ReactNode;
+}): react.JSX.Element;
+/** Mintlify `<Tip>`. @public */
+declare function Tip({ children }: {
+    children?: ReactNode;
+}): react.JSX.Element;
+
+/**
+ * Card components — the Mintlify `<Card>` and `<CardGroup>`. Server-compatible.
+ *
+ * Colours come from the framework's `--color-fd-*` theme variables, so a card
+ * follows the site's palette and the dark theme. Nothing here is a fixed hue.
+ *
+ * @packageDocumentation
+ */
+/**
+ * A card. When `href` is set it renders as a link.
+ *
+ * @public
+ */
+declare function Card({ title, href, children, }: {
+    title?: string;
+    href?: string;
+    children?: ReactNode;
+}): react.JSX.Element;
+/**
+ * A responsive grid of cards. `cols` sets the column count (default 2).
+ *
+ * @public
+ */
+declare function CardGroup({ cols, children }: {
+    cols?: number;
+    children?: ReactNode;
+}): react.JSX.Element;
+
+/**
+ * Resolve a `docs.json` icon name to an inline SVG. Unknown names resolve to
+ * nothing, so the sidebar simply shows no icon rather than a broken one.
+ *
+ * @param name - the icon name from `docs.json`, or undefined
+ * @returns the icon element, or undefined
+ * @public
+ */
+declare function docsIcon(name: string | undefined): ReactNode;
+
+/**
+ * A general error screen with per-kind states.
+ *
+ * One component covers every full-page error a docs site shows — a missing page
+ * (404), a forbidden account (403), a runtime failure (500), an offline state —
+ * each with its own icon, eyebrow, and default copy. A site picks the `kind`
+ * and, for runtime errors, passes a retry action; the framework owns the rest.
+ * Server-compatible: the site's `error.tsx` wrapper carries the `'use client'`
+ * boundary and hands in the retry button.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * The error states the screen renders.
+ *
+ * @public
+ */
+type ErrorKind = 'not-found' | 'forbidden' | 'server' | 'offline' | 'unknown';
+/**
+ * The default eyebrow, title, description, and icon for a {@link ErrorKind}.
+ *
+ * @public
+ */
+interface ErrorPreset {
+    readonly code: string;
+    readonly title: string;
+    readonly description: string;
+    readonly icon: ReactNode;
+}
+/**
+ * The default preset for an error kind — its icon, eyebrow, and copy.
+ *
+ * @param kind - the error state
+ * @returns the preset a site can render or override
+ * @public
+ */
+declare function errorPreset(kind: ErrorKind): ErrorPreset;
+/**
+ * Props for {@link ErrorScreen}. Everything but `kind` is optional: the kind's
+ * preset fills the eyebrow, title, description, and icon unless overridden.
+ *
+ * @public
+ */
+interface ErrorScreenProps {
+    /** Which error state to render. Default `unknown`. */
+    readonly kind?: ErrorKind;
+    /** Override the eyebrow code (e.g. a specific status). */
+    readonly code?: string;
+    /** Override the title. */
+    readonly title?: string;
+    /** Override the description. */
+    readonly description?: string;
+    /** When set, render a primary button linking here (e.g. `/docs`). */
+    readonly homeHref?: string;
+    /** Label for the home button. Default "Back to docs". */
+    readonly homeLabel?: string;
+    /** An extra action rendered beside the home button (e.g. a retry button). */
+    readonly action?: ReactNode;
+}
+/**
+ * Render the error screen.
+ *
+ * @param props - see {@link ErrorScreenProps}
+ * @public
+ */
+declare function ErrorScreen(props: ErrorScreenProps): ReactNode;
+
+/**
+ * Steps components — the Mintlify `<Steps>` and `<Step>`. Server-compatible.
+ *
+ * The spine uses the framework's border token, so it follows the site's palette
+ * and the dark theme.
+ *
+ * @packageDocumentation
+ */
+/**
+ * An ordered list of steps.
+ *
+ * @public
+ */
+declare function Steps({ children }: {
+    children?: ReactNode;
+}): react.JSX.Element;
+/**
+ * A single step with an optional title.
+ *
+ * @public
+ */
+declare function Step({ title, children }: {
+    title?: string;
+    children?: ReactNode;
+}): react.JSX.Element;
+
+/**
+ * The Mintlify-compatible MDX component map.
+ *
+ * Pass this to an MDX renderer (for example `next-mdx-remote`'s `compileMDX`)
+ * so real Mintlify guides render unchanged. A site no longer needs to shim
+ * these itself.
+ *
+ * @public
+ */
+declare const mdxComponents: {
+    Note: typeof Note;
+    Warning: typeof Warning;
+    Info: typeof Info;
+    Tip: typeof Tip;
+    Card: typeof Card;
+    CardGroup: typeof CardGroup;
+    Accordion: typeof Accordion;
+    AccordionGroup: typeof AccordionGroup;
+    Steps: typeof Steps;
+    Step: typeof Step;
+};
+
+/**
+ * The navigation sidebar. Renders a {@link Navigation} tree (produced by
+ * `parseNavigation`) as tabs, groups, and page links. Framework-agnostic: it
+ * emits plain anchors and takes an optional `resolveHref` so a site controls
+ * its own routing. Server-compatible.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Map a navigation page to a URL. Override to control routing — the default
+ * assumes one specific site shape, which is why {@link DocsSidebar} is
+ * deprecated.
+ *
+ * @public
+ */
+type ResolveHref = (page: NavPage) => string;
+/**
+ * Render the documentation sidebar.
+ *
+ * @deprecated Use fumadocs' `DocsLayout` with `loader({ icon: docsIcon })`,
+ * which both shipped sites use. This component predates that wiring: it renders
+ * plain anchors with no active state, no collapsible groups, and no search, and
+ * its default `resolveHref` assumes a routing shape (`/reference`, and
+ * `introduction` at the root) that no site now uses. Pass your own
+ * {@link ResolveHref} if you keep it. It stays exported, and behaves exactly as
+ * before, until the next major version.
+ *
+ * @public
+ */
+declare function DocsSidebar({ nav, resolveHref, }: {
+    nav: Navigation;
+    resolveHref?: ResolveHref;
+}): react.JSX.Element;
+
+export { Accordion, AccordionGroup, type ApiOperationSlots, AuthScreen, type AuthScreenProps, Callout, Card, CardGroup, DocsSidebar, type ErrorKind, type ErrorPreset, ErrorScreen, type ErrorScreenProps, Info, MethodBadge, Note, type ResolveHref, type SidebarBadgeTransformer, type SidebarItem, Step, Steps, Tip, Warning, apiMethodBadges, apiOperationLayout, authErrorMessage, docsIcon, errorPreset, mdxComponents };