{ "$schema": "https://ui.shadcn.com/schema/registry-item.json", "name": "documentation-page", "title": "Documentation Page", "description": "Navigation, an in-page table of contents with the current section, content, and page actions.", "dependencies": [ "class-variance-authority", "lucide-react" ], "registryDependencies": [ "button", "https://uaiblocks.dev/r/uai-theme.json", "https://uaiblocks.dev/r/app-sidebar.json", "https://uaiblocks.dev/r/breadcrumb-trail.json", "https://uaiblocks.dev/r/uai-utils.json" ], "files": [ { "path": "src/registry/uai/blocks/documentation-page.tsx", "content": "\"use client\";\n\nimport { cva } from \"class-variance-authority\";\nimport { ArrowLeft, ArrowRight } from \"lucide-react\";\nimport {\n type ComponentProps,\n type CSSProperties,\n createContext,\n useContext,\n useEffect,\n useId,\n useLayoutEffect,\n useRef,\n useState,\n} from \"react\";\nimport { Button } from \"@/components/ui/button\";\nimport {\n AppSidebar,\n type AppSidebarProps,\n type AppSidebarVariant,\n} from \"@/components/ui/uai/app-sidebar\";\nimport {\n BreadcrumbTrail,\n type BreadcrumbTrailProps,\n type BreadcrumbTrailVariant,\n} from \"@/components/ui/uai/breadcrumb-trail\";\nimport { cn } from \"@/lib/uai-utils\";\n\nexport const DOCUMENTATION_PAGE_VARIANTS = [\"columns\", \"stacked\", \"compact\"] as const;\nexport type DocumentationPageVariant = (typeof DOCUMENTATION_PAGE_VARIANTS)[number];\nexport type DocumentationPageProps = ComponentProps<\"div\"> & {\n variant?: DocumentationPageVariant;\n /** The id of the section marked as current in the table of contents. */\n activeSection?: string;\n defaultActiveSection?: string;\n onActiveSectionChange?: (section: string) => void;\n};\n\ntype DocsContext = {\n id: string;\n variant: DocumentationPageVariant;\n activeSection: string;\n setActiveSection: (section: string) => void;\n};\nconst Context = createContext(null);\nfunction useDocs(part: string) {\n const context = useContext(Context);\n if (!context) throw new Error(`${part} must be used within DocumentationPage`);\n return context;\n}\nconst SectionContext = createContext(null);\nconst TocContext = createContext(null);\n\nconst sidebarVariants: Record = {\n columns: \"inset\",\n stacked: \"panel\",\n compact: \"compact\",\n};\nconst breadcrumbVariants: Record = {\n columns: \"chevron\",\n stacked: \"slash\",\n compact: \"chevron\",\n};\n\nconst documentationPageLayoutVariants = cva(\n \"grid min-w-0 grid-cols-[minmax(0,1fr)] [grid-template-areas:'nav'_'toc'_'main']\",\n {\n variants: {\n variant: {\n columns:\n \"gap-5 @min-[720px]:grid-cols-[220px_minmax(0,1fr)] @min-[720px]:grid-rows-[auto_1fr] @min-[720px]:gap-x-8 @min-[720px]:[grid-template-areas:'nav_toc'_'nav_main'] @min-[980px]:grid-cols-[220px_minmax(0,1fr)_180px] @min-[980px]:grid-rows-[auto] @min-[980px]:[grid-template-areas:'nav_main_toc']\",\n stacked:\n \"gap-5 @min-[720px]:grid-cols-[minmax(0,1fr)_200px] @min-[720px]:gap-x-10 @min-[720px]:[grid-template-areas:'nav_nav'_'main_toc']\",\n compact:\n \"gap-3 @min-[720px]:grid-cols-[200px_minmax(0,1fr)] @min-[720px]:grid-rows-[auto_1fr] @min-[720px]:gap-x-5 @min-[720px]:[grid-template-areas:'nav_toc'_'nav_main']\",\n },\n },\n },\n);\n\n/** Documentation with navigation, an in-page table of contents, content, and page actions. */\nexport function DocumentationPage({\n variant = \"columns\",\n activeSection,\n defaultActiveSection = \"\",\n onActiveSectionChange,\n children,\n className,\n ...props\n}: DocumentationPageProps) {\n const id = useId();\n const [internal, setInternal] = useState(defaultActiveSection);\n const current = activeSection ?? internal;\n const latest = useRef({ current, activeSection, onActiveSectionChange });\n latest.current = { current, activeSection, onActiveSectionChange };\n const setActiveSection = useRef((next: string) => {\n const state = latest.current;\n if (next === state.current) return;\n if (state.activeSection === undefined) setInternal(next);\n state.onActiveSectionChange?.(next);\n }).current;\n return (\n \n \n \n {children}\n \n \n \n );\n}\n\n/** Site navigation, an App Sidebar. Compose App Sidebar parts inside it. */\nexport function DocumentationPageNav({ className, ...props }: Omit) {\n const { variant } = useDocs(\"DocumentationPageNav\");\n return (\n \n );\n}\n\n/** The page content, rendered as an article named by DocumentationPageTitle. */\nexport function DocumentationPageMain({ className, ...props }: ComponentProps<\"article\">) {\n const { id, variant } = useDocs(\"DocumentationPageMain\");\n return (\n \n );\n}\n\nexport function DocumentationPageHeader({ className, ...props }: ComponentProps<\"header\">) {\n const { variant } = useDocs(\"DocumentationPageHeader\");\n return (\n \n );\n}\n\n/** Page hierarchy, a Breadcrumb Trail. Compose BreadcrumbTrailItem parts inside it. */\nexport function DocumentationPageBreadcrumb(props: Omit) {\n const { variant } = useDocs(\"DocumentationPageBreadcrumb\");\n return ;\n}\n\nexport function DocumentationPageTitle({ className, ...props }: ComponentProps<\"h1\">) {\n const { id, variant } = useDocs(\"DocumentationPageTitle\");\n return (\n \n );\n}\n\nexport function DocumentationPageDescription({ className, ...props }: ComponentProps<\"p\">) {\n const { variant } = useDocs(\"DocumentationPageDescription\");\n return (\n \n );\n}\n\n/** Page actions such as copying the page link, editing the source, or sending feedback. */\nexport function DocumentationPageActions({\n \"aria-label\": label = \"Page actions\",\n className,\n ...props\n}: ComponentProps<\"div\">) {\n useDocs(\"DocumentationPageActions\");\n return (\n // biome-ignore lint/a11y/useSemanticElements: a labelled group of actions, not a fieldset.\n \n );\n}\n\ntype ActionStyleProps = { emphasis?: \"primary\" | \"secondary\" };\nconst documentationPageActionVariants = cva(\n \"inline-flex cursor-pointer items-center justify-center gap-1.5 rounded-full border-0 px-3 has-[>svg]:px-3 text-[12.5px] font-medium whitespace-nowrap no-underline transition-[background-color,filter,scale] duration-[120ms,120ms,140ms] ease-[ease-out,ease-out,cubic-bezier(0.23,1,0.32,1)] py-0 focus-visible:ring-0 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-ring focus-visible:outline-solid active:scale-[0.97] motion-reduce:transition-none motion-reduce:active:scale-100 [&_svg:not([class*='size-'])]:size-3.5\",\n {\n variants: {\n emphasis: {\n primary: \"bg-primary text-primary-foreground hover:bg-primary hover:brightness-108\",\n secondary:\n \"bg-secondary text-secondary-foreground hover:bg-[color-mix(in_oklab,var(--secondary)_85%,var(--foreground))]\",\n },\n compact: { true: \"h-[26px]\", false: \"h-7\" },\n },\n },\n);\n\nexport function DocumentationPageAction({\n emphasis = \"secondary\",\n type = \"button\",\n className,\n ...props\n}: ComponentProps<\"button\"> & ActionStyleProps) {\n const { variant } = useDocs(\"DocumentationPageAction\");\n return (\n \n );\n}\n\nexport function DocumentationPageActionLink({\n emphasis = \"secondary\",\n className,\n ...props\n}: ComponentProps<\"a\"> & ActionStyleProps) {\n const { variant } = useDocs(\"DocumentationPageActionLink\");\n return (\n \n \n \n );\n}\n\n/** Prose wrapper with spacing, inline code, and code block styles. */\nexport function DocumentationPageContent({ className, ...props }: ComponentProps<\"div\">) {\n useDocs(\"DocumentationPageContent\");\n return (\n *]:mx-0 [&>*]:mb-0 [&>*+*]:mt-4 [&>:first-child]:mt-0\",\n \"[&_p]:max-w-[72ch] [&_p]:text-[color-mix(in_oklab,var(--foreground)_88%,var(--muted-foreground))]\",\n \"[&_code]:rounded-md [&_code]:bg-muted [&_code]:px-1.5 [&_code]:py-px [&_code]:font-mono [&_code]:text-[0.88em]\",\n \"[&_pre]:overflow-x-auto [&_pre]:rounded-[10px] [&_pre]:bg-card [&_pre]:px-3.5 [&_pre]:py-3 [&_pre]:text-[12px]/[18px]\",\n \"[&_pre_code]:bg-transparent [&_pre_code]:p-0 [&_pre_code]:text-[length:inherit] [&_pre_code]:shadow-none\",\n className,\n )}\n {...props}\n />\n );\n}\n\n/** A linkable section. Its `id` is the target of a table of contents link. */\nexport function DocumentationPageSection({\n id,\n className,\n ...props\n}: ComponentProps<\"section\"> & { id: string }) {\n useDocs(\"DocumentationPageSection\");\n const titleId = useId();\n return (\n \n \n \n );\n}\n\nexport function DocumentationPageSectionTitle({ className, ...props }: ComponentProps<\"h2\">) {\n const id = useContext(SectionContext);\n if (!id) {\n throw new Error(\"DocumentationPageSectionTitle must be used within DocumentationPageSection\");\n }\n return (\n \n );\n}\n\n/**\n * In-page links. The link for the section nearest the top of the viewport is marked current;\n * selecting a link marks it current immediately.\n */\nexport function DocumentationPageToc({\n \"aria-label\": label,\n \"aria-labelledby\": labelledBy,\n className,\n ...props\n}: ComponentProps<\"nav\">) {\n const context = useDocs(\"DocumentationPageToc\");\n const titleId = useId();\n const ref = useRef(null);\n const { setActiveSection } = context;\n useEffect(() => {\n if (typeof IntersectionObserver !== \"function\") return;\n const targets = Array.from(ref.current?.querySelectorAll(\"a[href]\") ?? [])\n .map((link) => link.hash.slice(1))\n .map((hash) => (hash ? document.getElementById(decodeURIComponent(hash)) : null))\n .filter((target): target is HTMLElement => Boolean(target));\n if (!targets.length) return;\n const visible = new Set();\n const observer = new IntersectionObserver(\n (entries) => {\n for (const entry of entries) {\n if (entry.isIntersecting) visible.add(entry.target);\n else visible.delete(entry.target);\n }\n const first = targets.find((target) => visible.has(target));\n if (first) setActiveSection(first.id);\n },\n { rootMargin: \"0px 0px -65% 0px\" },\n );\n for (const target of targets) observer.observe(target);\n return () => observer.disconnect();\n }, [setActiveSection]);\n return (\n \n \n \n );\n}\n\nexport function DocumentationPageTocTitle({ className, ...props }: ComponentProps<\"p\">) {\n const id = useContext(TocContext);\n if (!id) throw new Error(\"DocumentationPageTocTitle must be used within DocumentationPageToc\");\n return (\n \n );\n}\n\nconst useIsomorphicLayoutEffect = typeof window === \"undefined\" ? useEffect : useLayoutEffect;\n\nexport function DocumentationPageTocList({ className, children, ...props }: ComponentProps<\"ul\">) {\n const { activeSection } = useDocs(\"DocumentationPageTocList\");\n const ref = useRef(null);\n const [marker, setMarker] = useState<{ y: number; height: number }>();\n useIsomorphicLayoutEffect(() => {\n const list = ref.current;\n if (!list) return;\n const measure = () => {\n const active = list.querySelector(\n \"[data-slot=documentation-page-toc-item][data-active]\",\n );\n if (!active || active.offsetHeight === 0) return setMarker(undefined);\n setMarker({ y: active.offsetTop, height: active.offsetHeight });\n };\n measure();\n if (typeof ResizeObserver !== \"function\") return;\n const observer = new ResizeObserver(measure);\n observer.observe(list);\n return () => observer.disconnect();\n }, [activeSection]);\n // One measured marker (a pseudo-element, so the list keeps only
  • children) slides to the\n // current link; until it is measured the link paints its own border.\n const style = marker\n ? ({\n \"--toc-marker-y\": `${marker.y}px`,\n \"--toc-marker-height\": `${marker.height}px`,\n } as CSSProperties)\n : undefined;\n return (\n \n {children}\n \n );\n}\n\nexport type DocumentationPageTocItemProps = Omit, \"href\"> & {\n /** The id of the target DocumentationPageSection. */\n section: string;\n /** Indent level: 2 for sections, 3 for subsections. */\n level?: 2 | 3;\n};\nexport function DocumentationPageTocItem({\n section,\n level = 2,\n onClick,\n className,\n children,\n ...props\n}: DocumentationPageTocItemProps) {\n const context = useDocs(\"DocumentationPageTocItem\");\n const active = context.activeSection === section;\n return (\n
  • \n {\n onClick?.(event);\n if (!event.defaultPrevented) context.setActiveSection(section);\n }}\n >\n {children}\n \n
    • \n );\n}\n\n/** Previous and next page links at the end of the content. */\nexport function DocumentationPagePager({\n \"aria-label\": label = \"Pagination\",\n className,\n ...props\n}: ComponentProps<\"nav\">) {\n useDocs(\"DocumentationPagePager\");\n return (\n \n );\n}\n\nexport function DocumentationPagePagerLink({\n direction,\n label,\n className,\n children,\n ...props\n}: ComponentProps<\"a\"> & {\n direction: \"previous\" | \"next\";\n /** Visible eyebrow; defaults to \"Previous\" or \"Next\". */\n label?: string;\n}) {\n const { variant } = useDocs(\"DocumentationPagePagerLink\");\n const next = direction === \"next\";\n const Icon = next ? ArrowRight : ArrowLeft;\n return (\n \n \n {next ? null : }\n {label ?? (next ? \"Next\" : \"Previous\")}\n {next ? : null}\n \n {children}\n \n );\n}\n", "type": "registry:component", "target": "@components/uai/documentation-page.tsx" } ], "categories": [ "content", "navigation" ], "type": "registry:block" }