v4 Site Components and UI
Overview
This doc covers the reusable client-side and display layer for the v4 site: apps/v4/components/**, apps/v4/hooks/**, apps/v4/styles/**, and the public registry/static assets under apps/v4/public/**. It does not cover the app routes that place these components on pages or the registry source code outside these globs; route and registry data enter this area through props, public JSON files, and @/lib/* helpers.
The top-level shell is assembled from apps/…/site-header.tsx, apps/…/site-footer.tsx, and navigation components. SiteHeader reads source.pageTree, siteConfig.navItems, and getColors() and wires together desktop navigation (apps/…/main-nav.tsx), mobile navigation (apps/…/mobile-nav.tsx), the global command palette (apps/…/command-menu.tsx), GitHub/mode/designer actions, and the “New” create button. MainNav highlights exact top-level route matches and marks routes listed in PAGES_NEW; MobileNav opens a full-width Radix popover, renders static top-level docs sections, and expands page-tree folders using getCurrentBase() and getPagesFromFolder(), while hiding MCP links when showMcpDocs is false.
The docs navigation UI is split by viewport. apps/…/docs-sidebar.tsx owns the desktop docs sidebar: it renders top-level sections plus page-tree groups, excludes selected folders/pages, stores/restores its scroll position in sessionStorage via DOCS_SIDEBAR_SCROLL_STORAGE_KEY, and recenters the longest matching active item when navigating. apps/…/docs-toc.tsx renders an “On This Page” list or dropdown and uses IntersectionObserver to keep the active heading in sync with visible document sections. Supporting docs controls include breadcrumb/base switching/copy-page files in apps/…/docs-*.tsx, apps/…/docs-page-links.tsx for copying the current markdown and opening prompt URLs in v0/ChatGPT/Claude/Scira, apps/…/components-list.tsx for page-tree component indexes, and narrow section navs such as apps/…/blocks-nav.tsx, apps/…/charts-nav.tsx, and apps/…/colors-nav.tsx.
The command palette in apps/…/command-menu.tsx is the cross-site search and quick action surface. It uses useDocsSearch({ type: "fetch" }) for remote docs search, builds local command groups from nav items, registry styles, page-tree folders, colors, and optional blocks, and tracks debounced searches through trackEvent. Highlighted items set a selected type and copy payload: colors copy OKLCH values, components and blocks copy package-manager-specific shadcn add commands, and styles route to /create?preset=.... The palette defers expensive groups until after the dialog opens, uses useMutationObserver() to detect cmdk highlight changes, and reads the preferred package manager from apps/…/use-config.ts.
Component previews are centered on apps/…/component-preview.tsx. For normal examples it resolves a registry component with getRegistryComponent(name, styleName) and passes the live element plus source panels into apps/…/component-preview-tabs.tsx; for block previews it uses static light/dark screenshots on small screens and an iframe to /view/{styleName}/{name} on desktop. ComponentPreviewTabs handles preview/code chrome, mobile “View Code” expansion, RTL examples, language switching, and direction-provider selection for base/radix/aria styles. Source rendering in apps/…/component-source.tsx pulls either a demo/registry item by name or a filesystem path by src, formats it with formatCode(styleName), highlights it, and wraps it with CodeCollapsibleWrapper plus CopyButton unless explicitly disabled.
Block display is a heavier variant. apps/…/block-display.tsx fetches a registry block item and derives both a file tree and highlighted file contents, then delegates to apps/…/block-viewer.tsx. BlockViewer is a client-side context-driven viewer with preview/code tabs, responsive width controls backed by react-resizable-panels, iframe refresh/open-in-new-tab actions, command copying, v0 launch, a recursive file tree, per-file highlighted code, and screenshot fallback on mobile unless the item metadata says the mobile view should render the component preview. The viewer assumes registry item files have stable target values because the active file state and file tree selection are keyed by target.
Chart display follows the same registry-backed pattern with a smaller surface. apps/…/chart-display.tsx accepts a registry item enriched with highlightedCode, renders /view/{styleName}/{chart.name} through apps/…/chart-iframe.tsx, and exposes copy/code controls in apps/…/chart-toolbar.tsx, apps/…/chart-copy-button.tsx, and apps/…/chart-code-viewer.tsx. The toolbar derives chart labels and icons from name prefixes such as chart-line, chart-bar, chart-area, chart-radar, chart-radial, and chart-tooltip.
Theme state has two layers. Light/dark mode is provided by apps/…/theme-provider.tsx, a next-themes wrapper that uses the class attribute, enables system mode, and adds a d keyboard shortcut outside editable inputs. apps/…/mode-switcher.tsx toggles light/dark mode, updates the browser meta[name="theme-color"] via apps/…/use-meta-color.ts, and exports DarkModeScript, which forwards the d shortcut from iframe previews to the parent window using the dark-mode-forward message type. Palette/theme customization is separate: apps/…/active-theme.tsx applies theme-{activeTheme} and theme-scaled classes to document.body, while apps/…/theme-customizer.tsx and apps/…/theme-selector.tsx let users choose a base theme and copy CSS for OKLCH, Tailwind v4 HSL, or Tailwind v3. Those controls read theme names from @/lib/themes and color tokens from registry base-color data.
Shared hooks under apps/v4/hooks/** provide the local client state used by these components. use-config.ts persists style/package-manager/install-type preferences in a Jotai atomWithStorage named config; use-layout.tsx persists a fixed/full layout choice in localStorage, applies layout classes or data attributes to document.documentElement, syncs across tabs, and ignores nested providers; use-copy-to-clipboard.ts and components/copy-button.tsx implement clipboard copying with navigator.clipboard plus document.execCommand fallback; use-mobile.ts and use-media-query.tsx wrap matchMedia; use-search-registry.ts fetches /r/registries.json, combines it with @/…/directory.json, and stores search/page query params through nuqs; and use-mounted.ts, use-delayed-status.ts, use-colors.ts, and use-mutation-observer.ts are small client helpers used to avoid hydration or DOM-observation edge cases.
The registry directory UI is also in this component layer. apps/…/directory-list.tsx wraps results in DirectoryAddProvider, reads paginated/search-filtered registries from useSearchRegistry(), renders registry logos with dangerouslySetInnerHTML, appends UTM parameters to outgoing homepage links, and keeps pagination hrefs and client-side nuqs state aligned. apps/…/directory-add-button.tsx opens either a dialog or drawer based on useIsMobile(), builds shadcn registry add commands for pnpm/npm/yarn/bun from the selected registry, persists the selected package manager through useConfig(), and tracks copy events.
The public files under apps/v4/public/** are not just static decoration; they are served contracts for previews, installable registry payloads, and schemas. apps/…/*.json contains registry item payloads for UI components, examples, charts, hooks, and blocks; individual items such as button.json embed file content, dependencies, and targets, while block items such as dashboard-01.json include multiple page/component/data files plus categories. apps/…/registry.json aggregates those items for the style registry. apps/…/*.json and apps/…/themes.css expose theme tokens, and apps/…/schema.json, apps/…/registry.json, and apps/…/registry-item.json define the public components/registry schema shapes consumed by clients and documentation. Block preview screenshots live beside their JSON as *-light.png/*-dark.png, and templates are distributed as tarballs under apps/v4/public/r/templates/. apps/…/README.md notes that generated style directories are gitignored and should be rebuilt with pnpm --filter=v4 registry:build --style all; the tracked public registry JSON under apps/v4/public/r/styles is regenerated by the broader registry build.
Coupling
- If apps/…/docs-sidebar.tsx or apps/…/mobile-nav.tsx changes top-level docs sections, exclusions, or MCP visibility, also verify the page-tree helpers and docs source feeding
source.pageTree: both components independently encode section lists and filters, so a route can appear on mobile but not desktop if only one list is updated. - If registry item file metadata changes in apps/…/*.json, verify apps/…/block-display.tsx, apps/…/block-viewer.tsx, and apps/…/component-source.tsx: previews select active files by
target, build file trees fromfiles, and readfiles[0].contentfor simple source panels. - If
/view/{styleName}/{name}routing or style names change outside this doc, verify apps/…/component-preview.tsx, apps/…/block-viewer.tsx, and apps/…/chart-display.tsx; all three hard-code iframe or link URLs using that route shape. - If theme token names or theme lists change, update both the public assets (apps/…/*.json, apps/…/themes.css) and the theme UI (apps/…/active-theme.tsx, apps/…/theme-customizer.tsx, apps/…/theme-selector.tsx). The UI applies body classes and emits CSS snippets that assume token names like
--background,--foreground,--chart-1through--chart-5, and the.darksection. - If copy-event names or analytics payloads change in the event layer, verify apps/…/command-menu.tsx, apps/…/copy-button.tsx, apps/…/block-viewer.tsx, apps/…/chart-copy-button.tsx, apps/…/theme-customizer.tsx, and apps/…/directory-add-button.tsx; they each call
trackEventorcopyToClipboardWithMetawith event-specific property shapes. - If package-manager preferences change, verify apps/…/use-config.ts, apps/…/code-tabs.tsx, apps/…/command-menu.tsx, and apps/…/directory-add-button.tsx; the same persisted
configatom drives install tabs and generated CLI commands. - If public registry schema fields are added or constrained in apps/…/registry-item.json or apps/…/registry.json, verify the generated public registry items under apps/…/*.json and the display components that read those fields. The UI generally does not validate at runtime and will silently omit previews or code when expected fields are missing.
Risks
- apps/…/docs-sidebar.tsx stores scroll state in
sessionStorageand uses DOM measurements in a layout effect. If route matching or active link attributes change, the sidebar can restore to the wrong scroll position or fail to center the active page, leaving desktop docs navigation disorienting after navigation. - apps/…/block-viewer.tsx initializes
activeFilefromhighlightedFiles?.[0].targetand selects files bytarget. If generated registry files omit or duplicatetarget, the code pane can render no file or switch to the wrong file even though the registry item exists. - apps/…/theme-provider.tsx, apps/…/mode-switcher.tsx, and apps/…/active-theme.tsx all mutate theme-related DOM state. If a preview iframe does not include
DarkModeScriptor if body/html theme classes diverge, iframe previews and the surrounding page can show different dark mode or palette state. - apps/…/directory-list.tsx renders registry logos with
dangerouslySetInnerHTMLfrom the directory view. If upstream registry metadata is not sanitized before it reachescreateRegistryDirectoryView(), the directory page can inject arbitrary SVG/HTML into the client-rendered list.