(null)
const titleRef = usePageArrival(docs.page?.id, scrollRef)
const page = docs.page
if (!page) return
return (
{/* relative: anything sr-only inside stays clipped by this scroller instead of widening the page. */}
{page.sections.map((section) => (
{/* Stays beside its text while a long explanation scrolls, which is the whole reason for two columns. */}
{section.code ? (
) : null}
))}
)
}
/** Text beside its code, for people who came to copy something and want the explanation in the same glance. */
function DocsReference({ docs, brandName, brandHref, className, ...props }: DocsCommonProps) {
return (
)
}
export { DocsReference }
```
### `registry/miseui/blocks/docs-layout-sample.tsx`
```tsx
import type * as React from "react"
import type { DocsGroup } from "./docs-layout-state"
function Term({ children }: { children: React.ReactNode }) {
return {children}
}
const CURL_INVOICE = `curl https://api.paperline.example/v1/invoices \\
-H "Authorization: Bearer pl_test_example" \\
-d customer=cus_example \\
-d amount=128000`
const SDK_SETUP = `import { Paperline } from "paperline"
const client = new Paperline(process.env.PAPERLINE_KEY)`
const CREATE_INVOICE = `const invoice = await client.invoices.create({
customer: "cus_example",
amount: 128000,
dueInDays: 14,
})`
const INVOICE_JSON = `{
"id": "inv_example",
"status": "open",
"amount": 128000,
"hostedUrl": "https://pay.paperline.example/inv_example"
}`
const WEBHOOK_HANDLER = `export async function POST(request: Request) {
const body = await request.text()
const signature = request.headers.get("paperline-signature")
const event = client.webhooks.verify(body, signature)
return new Response(null, { status: 200 })
}`
/** Every key, id and amount here is an example; none of it reaches a real service. */
const SAMPLE_GROUPS: readonly DocsGroup[] = [
{
label: "Get started",
pages: [
{
id: "quick-start",
title: "Quick start",
lead: "Send your first invoice in about five minutes.",
sections: [
{
id: "quick-start-install",
title: "Install the library",
body: Add the package to your project. It works in Node 20 and later, and in any runtime with a standard fetch.
,
code: { title: "Terminal", code: "npm install paperline", language: "bash" },
},
{
id: "quick-start-client",
title: "Create a client",
body: Read the key from your environment, so it never lands in your repository. Test keys start with pl_test_ and never move real money.
,
code: { title: "client.ts", code: SDK_SETUP, language: "ts" },
},
{
id: "quick-start-invoice",
title: "Send an invoice",
body: Amounts are in the smallest unit of the currency, so 128000 means 1,280.00. The customer gets an email with a link to pay.
,
code: { title: "send.ts", code: CREATE_INVOICE, language: "ts" },
},
{
id: "quick-start-next",
title: "Where to go next",
body: Keep the invoice id. You will need it to read the status, and webhooks use it to tell you when the invoice is paid.
,
},
],
},
{
id: "authentication",
title: "Authentication",
lead: "One key per environment, sent as a bearer token.",
sections: [
{
id: "authentication-keys",
title: "Test and live keys",
body: A test key only reaches test data. Create a live key once you are ready, and keep the two in separate environments.
,
},
{
id: "authentication-request",
title: "Sending a request",
body: Put the key in the Authorization header. A request without one gets a 401 and nothing else happens.
,
code: { title: "Terminal", code: CURL_INVOICE, language: "bash" },
},
],
},
],
},
{
label: "Guides",
pages: [
{
id: "invoices",
title: "Invoices",
lead: "What an invoice holds, and the states it moves through.",
sections: [
{
id: "invoices-object",
title: "The invoice object",
body: Status starts at open and moves to paid or void. The hosted link stays valid until then.
,
code: { title: "Response", code: INVOICE_JSON, language: "json" },
},
{
id: "invoices-reminders",
title: "Reminders",
body: By default a reminder goes out three days before the due date and again on the day. Turn either off per invoice.
,
},
],
},
{
id: "webhooks",
title: "Webhooks",
lead: "Hear about a payment without asking for it.",
sections: [
{
id: "webhooks-receive",
title: "Receive an event",
body: Verify the signature before you trust the body, then answer quickly with a 200. Do slow work after the response.
,
code: { title: "route.ts", code: WEBHOOK_HANDLER, language: "ts" },
},
{
id: "webhooks-retries",
title: "Retries",
body: An event that does not get a 200 is sent again, up to five times over a day. The same event can arrive twice, so treat the id as the key.
,
},
],
},
],
},
]
export { SAMPLE_GROUPS }
```
### `registry/miseui/blocks/docs-layout-sidebar.tsx`
```tsx
import type * as React from "react"
import { useEffect, useRef } from "react"
import { cn } from "@/registry/miseui/lib/utils"
import { Sidebar, SidebarContent, SidebarGroup, SidebarItem, SidebarProvider, SidebarTrigger, useSidebar } from "@/registry/miseui/ui/sidebar"
import { TableOfContents } from "@/registry/miseui/ui/table-of-contents"
import { DocsBrand, DocsEmpty, DocsPager, DocsTopBar, PageHeading, PageTocFold, SectionCode, SectionText } from "./docs-layout-parts"
import { useNarrowerThan, usePageArrival, type DocsGroup, type DocsPages } from "./docs-layout-state"
/** Matches @3xl, where the column appears. */
const DRAWER_BELOW_PX = 768
interface DocsCommonProps extends React.ComponentProps<"section"> {
docs: DocsPages
brandName: React.ReactNode
brandHref: string
}
function DocsNav({ docs, groups }: { docs: DocsPages; groups: readonly DocsGroup[] }) {
return (
{groups.map((group) => (
{group.pages.map((page) => (
docs.select(page.id)}>
{page.title}
))}
))}
)
}
/**
* The sidebar's drawer has no Radix trigger, so Radix has nothing to hand focus back to after Escape.
* Skipped when focus already moved on: choosing a page sends it to the new title.
*/
function useDrawerFocusReturn(triggerRef: React.RefObject) {
const { drawerOpen } = useSidebar()
const wasOpenRef = useRef(drawerOpen)
useEffect(() => {
const closed = wasOpenRef.current && !drawerOpen
wasOpenRef.current = drawerOpen
if (!closed) return
const id = window.setTimeout(() => {
const active = document.activeElement
const stranded = !active || active === document.body || active.closest("[data-slot='drawer']") !== null
if (stranded) triggerRef.current?.focus()
})
return () => window.clearTimeout(id)
}, [drawerOpen, triggerRef])
}
function NavTrigger() {
const triggerRef = useRef(null)
useDrawerFocusReturn(triggerRef)
return
}
function SidebarArticle({ docs }: { docs: DocsPages }) {
const scrollRef = useRef(null)
const titleRef = usePageArrival(docs.page?.id, scrollRef)
const page = docs.page
if (!page) return
return (
// relative: anything sr-only inside stays clipped by this scroller instead of widening the page.
{page.sections.map((section) => (
))}
)
}
/** Three columns, for a product with enough pages that people move around: where you are, what you are reading, and what is on this page. */
function DocsSidebar({ docs, groups, brandName, brandHref, className, ...props }: DocsCommonProps & { groups: readonly DocsGroup[] }) {
const rootRef = useRef(null)
const narrow = useNarrowerThan(rootRef, DRAWER_BELOW_PX)
return (
{/* The shortcut stays off: Mod+B belongs to the page, and a docs page has no reason to take it. */}
}>
)
}
export { DocsSidebar, type DocsCommonProps }
```
### `registry/miseui/blocks/docs-layout-state.ts`
```ts
import type * as React from "react"
import { useLayoutEffect, useEffect, useRef, useState } from "react"
import type { CodeLanguage } from "@/registry/miseui/ui/code-block"
interface DocsCode {
code: string
language?: CodeLanguage
/** A file name, or a word such as Terminal. */
title?: string
}
interface DocsSection {
/** Becomes the heading id and the address of the jump, so keep it unique across the document. */
id: string
title: string
body: React.ReactNode
code?: DocsCode
}
interface DocsPage {
id: string
title: string
/** Continues the title in the heading, one tone quieter. */
lead?: string
/** A real address, if your router owns the page. Left out, the block swaps the page itself. */
href?: string
sections: readonly DocsSection[]
}
interface DocsGroup {
label: string
pages: readonly DocsPage[]
}
function flattenPages(groups: readonly DocsGroup[]) {
return groups.flatMap((group) => group.pages)
}
/** The page to show and its neighbours. An unknown id falls back to the first page, not a blank screen. */
function locatePage(pages: readonly DocsPage[], id: string | undefined) {
const found = pages.findIndex((page) => page.id === id)
const index = Math.max(found, 0)
return { page: pages[index] as DocsPage | undefined, previous: pages[index - 1] as DocsPage | undefined, next: pages[index + 1] as DocsPage | undefined }
}
interface DocsPagesOptions {
groups: readonly DocsGroup[]
current?: string
defaultCurrent?: string
onNavigate?: (id: string) => void
}
function useDocsPages({ groups, current, defaultCurrent, onNavigate }: DocsPagesOptions) {
const pages = flattenPages(groups)
const [uncontrolled, setUncontrolled] = useState(defaultCurrent)
const located = locatePage(pages, current ?? uncontrolled)
const select = (id: string) => {
setUncontrolled(id)
onNavigate?.(id)
}
return { ...located, select }
}
type DocsPages = ReturnType
/** A new page starts at its top, and the title takes focus so a screen reader hears where it landed. Not on arrival: that would steal focus from the page. */
function usePageArrival(pageId: string | undefined, scrollRef: React.RefObject | undefined) {
const titleRef = useRef(null)
const lastRef = useRef(pageId)
useEffect(() => {
if (lastRef.current === pageId) return
lastRef.current = pageId
scrollRef?.current?.scrollTo({ top: 0 })
titleRef.current?.focus({ preventScroll: Boolean(scrollRef) })
}, [pageId, scrollRef])
return titleRef
}
/** Measured so the sidebar's drawer can follow the block's own width, which a media query cannot see inside a frame. */
function useNarrowerThan(ref: React.RefObject, width: number) {
const [narrower, setNarrower] = useState(false)
useLayoutEffect(() => {
const element = ref.current
if (!element || typeof ResizeObserver === "undefined") return
const observer = new ResizeObserver(([entry]) => setNarrower(entry.contentRect.width < width))
observer.observe(element)
return () => observer.disconnect()
}, [ref, width])
return narrower
}
export { flattenPages, locatePage, useDocsPages, useNarrowerThan, usePageArrival, type DocsCode, type DocsGroup, type DocsPage, type DocsPages, type DocsPagesOptions, type DocsSection }
```