Merge branch 'main' into shadcn/package-imports

chore(release): version packages

.changeset/few-flies-fry.md

@@ -0,0 +1,5 @@
+---
+"shadcn": minor
+---
+
+add support for package imports

apps/v4/app/(app)/(root)/page.tsx

@@ -63,11 +63,7 @@ export default function IndexPage() {
           </Button>
         </PageActions>
       </PageHeader>
-      <PageNav className="hidden md:flex">
-        <ExamplesNav className="flex-1 overflow-hidden [&>a:first-child]:text-primary" />
-        <ThemeSelector className="mr-4 hidden md:flex" />
-      </PageNav>
-      <div className="container-wrapper flex-1 section-soft pb-6">
+      <div className="container-wrapper flex-1 pb-6">
         <div className="container overflow-hidden">
           <section className="-mx-4 w-[160vw] overflow-hidden rounded-lg border border-border/50 md:hidden md:w-[150vw]">
             <Image

apps/v4/app/(app)/create/components/customizer.tsx

@@ -1,6 +1,7 @@
 "use client"
 
 import * as React from "react"
+import dynamic from "next/dynamic"
 import { type RegistryItem } from "shadcn/schema"
 
 import { useIsMobile } from "@/hooks/use-mobile"
@@ -31,6 +32,13 @@ import { V0Button } from "@/app/(app)/create/components/v0-button"
 import { FONT_HEADING_OPTIONS, FONTS } from "@/app/(app)/create/lib/fonts"
 import { useDesignSystemSearchParams } from "@/app/(app)/create/lib/search-params"
 
+// Only visible when user clicks "Create Project".
+const ProjectForm = dynamic(() =>
+  import("@/app/(app)/create/components/project-form").then(
+    (m) => m.ProjectForm
+  )
+)
+
 export function Customizer({
   itemsByBase,
 }: {
@@ -93,12 +101,15 @@ export function Customizer({
           {isMobile && <BasePicker isMobile={isMobile} anchorRef={anchorRef} />}
         </FieldGroup>
       </CardContent>
-      <CardFooter className="flex min-w-0 gap-2 md:flex-col md:**:[button,a]:w-full">
+      <CardFooter className="flex min-w-0 gap-2 md:flex-col md:rounded-b-none md:**:[button,a]:w-full">
         <CopyPreset className="flex-1 md:flex-none" />
         <RandomButton className="flex-1 md:flex-none" />
         <ActionMenu itemsByBase={itemsByBase} />
         <ResetDialog />
       </CardFooter>
+      <CardFooter className="-mt-3 hidden min-w-0 gap-2 md:flex md:flex-col md:**:[button,a]:w-full">
+        <ProjectForm />
+      </CardFooter>
     </Card>
   )
 }

apps/v4/app/(app)/create/hooks/use-history.tsx

@@ -1,7 +1,8 @@
 "use client"
 
 import * as React from "react"
-import { usePathname, useRouter, useSearchParams } from "next/navigation"
+import { Suspense } from "react"
+import { useRouter, useSearchParams } from "next/navigation"
 
 type HistoryContextValue = {
   canGoBack: boolean
@@ -12,12 +13,28 @@ type HistoryContextValue = {
 
 const HistoryContext = React.createContext<HistoryContextValue | null>(null)
 
-export function HistoryProvider({ children }: { children: React.ReactNode }) {
-  const router = useRouter()
-  const pathname = usePathname()
+// Reads useSearchParams() in its own Suspense boundary so the
+// provider never blanks out children while search params resolve.
+function PresetSync({
+  onPresetChange,
+}: {
+  onPresetChange: (preset: string) => void
+}) {
   const searchParams = useSearchParams()
   const preset = searchParams.get("preset") ?? ""
 
+  React.useEffect(() => {
+    onPresetChange(preset)
+  }, [preset, onPresetChange])
+
+  return null
+}
+
+export function HistoryProvider({ children }: { children: React.ReactNode }) {
+  const router = useRouter()
+
+  const [preset, setPreset] = React.useState("")
+
   const entriesRef = React.useRef<string[]>([preset])
   const indexRef = React.useRef(0)
   const maxIndexRef = React.useRef(0)
@@ -26,6 +43,10 @@ export function HistoryProvider({ children }: { children: React.ReactNode }) {
   const [index, setIndex] = React.useState(0)
   const [maxIndex, setMaxIndex] = React.useState(0)
 
+  const onPresetChange = React.useCallback((nextPreset: string) => {
+    setPreset(nextPreset)
+  }, [])
+
   React.useEffect(() => {
     if (isNavigatingRef.current) {
       isNavigatingRef.current = false
@@ -67,9 +88,10 @@ export function HistoryProvider({ children }: { children: React.ReactNode }) {
     } else {
       params.delete("preset")
     }
+    const pathname = window.location.pathname
     const query = params.toString()
     router.replace(query ? `${pathname}?${query}` : pathname)
-  }, [pathname, router])
+  }, [router])
 
   const goForward = React.useCallback(() => {
     if (indexRef.current >= maxIndexRef.current) {
@@ -88,9 +110,10 @@ export function HistoryProvider({ children }: { children: React.ReactNode }) {
     } else {
       params.delete("preset")
     }
+    const pathname = window.location.pathname
     const query = params.toString()
     router.replace(query ? `${pathname}?${query}` : pathname)
-  }, [pathname, router])
+  }, [router])
 
   React.useEffect(() => {
     const down = (e: KeyboardEvent) => {
@@ -133,7 +156,14 @@ export function HistoryProvider({ children }: { children: React.ReactNode }) {
     [canGoBack, canGoForward, goBack, goForward]
   )
 
-  return <HistoryContext value={value}>{children}</HistoryContext>
+  return (
+    <HistoryContext value={value}>
+      <Suspense>
+        <PresetSync onPresetChange={onPresetChange} />
+      </Suspense>
+      {children}
+    </HistoryContext>
+  )
 }
 
 export function useHistory() {

apps/v4/app/(app)/create/hooks/use-locks.tsx

@@ -24,10 +24,15 @@ const LocksContext = React.createContext<LocksContextValue | null>(null)
 
 export function LocksProvider({ children }: { children: React.ReactNode }) {
   const [locks, setLocks] = React.useState<Set<LockableParam>>(new Set())
+  const locksRef = React.useRef(locks)
+  React.useEffect(() => {
+    locksRef.current = locks
+  }, [locks])
 
+  // Stable callback — reads from ref so it doesn't change on every lock toggle.
   const isLocked = React.useCallback(
-    (param: LockableParam) => locks.has(param),
-    [locks]
+    (param: LockableParam) => locksRef.current.has(param),
+    []
   )
 
   const toggleLock = React.useCallback((param: LockableParam) => {

apps/v4/app/(app)/create/lib/search-params.ts

@@ -41,7 +41,7 @@ import { getPresetCode } from "@/app/(app)/create/lib/preset-code"
 import { resolvePresetOverrides } from "@/app/(app)/create/lib/preset-query"
 
 const designSystemSearchParams = {
-  preset: parseAsString.withDefault("b2D0wqNxT"),
+  preset: parseAsString.withDefault("b0"),
   base: parseAsStringLiteral<BaseName>(BASES.map((b) => b.name)).withDefault(
     DEFAULT_CONFIG.base
   ),

apps/v4/app/(app)/create/page.tsx

@@ -1,13 +1,22 @@
+import { Suspense } from "react"
 import { type Metadata } from "next"
+import dynamic from "next/dynamic"
 
 import { siteConfig } from "@/lib/config"
 import { absoluteUrl } from "@/lib/utils"
+import { Skeleton } from "@/styles/base-nova/ui/skeleton"
 import { Customizer } from "@/app/(app)/create/components/customizer"
 import { PresetHandler } from "@/app/(app)/create/components/preset-handler"
 import { Preview } from "@/app/(app)/create/components/preview"
-import { WelcomeDialog } from "@/app/(app)/create/components/welcome-dialog"
 import { getAllItems } from "@/app/(app)/create/lib/api"
 
+// Only shown on first visit (checks localStorage).
+const WelcomeDialog = dynamic(() =>
+  import("@/app/(app)/create/components/welcome-dialog").then(
+    (m) => m.WelcomeDialog
+  )
+)
+
 export const metadata: Metadata = {
   title: "New Project",
   description:
@@ -37,9 +46,7 @@ export const metadata: Metadata = {
   },
 }
 
-export default async function CreatePage() {
-  const itemsByBase = await getAllItems()
-
+export default function CreatePage() {
   return (
     <div className="relative z-10 flex min-h-0 flex-1 flex-col overflow-hidden section-soft [--customizer-width:--spacing(48)] [--gap:--spacing(4)] md:[--gap:--spacing(6)] 2xl:[--customizer-width:--spacing(56)]">
       <div
@@ -47,10 +54,21 @@ export default async function CreatePage() {
         className="flex min-h-0 flex-1 flex-col gap-(--gap) p-(--gap) pt-[calc(var(--gap)*0.25)] md:flex-row-reverse"
       >
         <Preview />
-        <Customizer itemsByBase={itemsByBase} />
+        <Suspense
+          fallback={
+            <Skeleton className="isolate min-h-[151px] w-full self-start rounded-2xl md:h-full md:max-h-full md:min-h-0 md:w-(--customizer-width)" />
+          }
+        >
+          <CustomizerLoader />
+        </Suspense>
       </div>
       <PresetHandler />
       <WelcomeDialog />
     </div>
   )
 }
+
+async function CustomizerLoader() {
+  const itemsByBase = await getAllItems()
+  return <Customizer itemsByBase={itemsByBase} />
+}

apps/v4/app/(app)/docs/changelog/page.tsx

@@ -10,6 +10,8 @@ import { Button } from "@/styles/radix-nova/ui/button"
 export const revalidate = false
 export const dynamic = "force-static"
 
+const NUMBER_OF_LATEST_PAGES = 2
+
 export function generateMetadata() {
   return {
     title: "Changelog",
@@ -34,8 +36,8 @@ export function generateMetadata() {
 
 export default function ChangelogPage() {
   const pages = getChangelogPages()
-  const latestPages = pages.slice(0, 5)
-  const olderPages = pages.slice(5)
+  const latestPages = pages.slice(0, NUMBER_OF_LATEST_PAGES)
+  const olderPages = pages.slice(NUMBER_OF_LATEST_PAGES)
 
   return (
     <div
@@ -44,7 +46,7 @@ export default function ChangelogPage() {
     >
       <div className="flex min-w-0 flex-1 flex-col">
         <div className="h-(--top-spacing) shrink-0" />
-        <div className="mx-auto flex w-full max-w-[40rem] min-w-0 flex-1 flex-col gap-6 px-4 py-6 text-neutral-800 md:px-0 lg:py-8 dark:text-neutral-300">
+        <div className="mx-auto flex w-full max-w-160 min-w-0 flex-1 flex-col gap-6 px-4 py-6 text-neutral-800 md:px-0 lg:py-8 dark:text-neutral-300">
           <div className="flex flex-col gap-2">
             <div className="flex items-center justify-between">
               <h1 className="scroll-m-24 text-4xl font-semibold tracking-tight sm:text-3xl">

apps/v4/app/globals.css

@@ -337,6 +337,44 @@
     display: inline-block;
   }
 
+  /*
+   * ```text composition trees use box-drawing characters; per-line padding makes
+   * vertical connectors look broken. rehype-pretty-code sets `data-language` on
+   * `pre`/`code` (not `language-*` classes). It also sets `code { display: grid }`,
+   * which can add visible row separation — reset to a normal pre stack for text.
+   */
+  [data-rehype-pretty-code-figure] pre[data-language="text"] code,
+  [data-rehype-pretty-code-figure] pre[data-language="plaintext"] code,
+  [data-slot="docs"] pre[data-language="text"] code,
+  [data-slot="docs"] pre[data-language="plaintext"] code {
+    display: block !important;
+    white-space: pre;
+    line-height: 0.95;
+    font-family:
+      ui-monospace,
+      SFMono-Regular,
+      Menlo,
+      Monaco,
+      Consolas,
+      "Liberation Mono",
+      "Courier New",
+      monospace;
+    font-variant-ligatures: none;
+  }
+
+  [data-rehype-pretty-code-figure] pre[data-language="text"] [data-line],
+  [data-rehype-pretty-code-figure] pre[data-language="plaintext"] [data-line],
+  [data-rehype-pretty-code-figure] code[data-language="text"] [data-line],
+  [data-rehype-pretty-code-figure] code[data-language="plaintext"] [data-line],
+  [data-slot="docs"] pre[data-language="text"] [data-line],
+  [data-slot="docs"] pre[data-language="plaintext"] [data-line] {
+    padding-top: 0;
+    padding-bottom: 0;
+    min-height: unset;
+    line-height: 0.95;
+    display: block;
+  }
+
   [data-line] span {
     color: var(--shiki-light);
 

apps/v4/components/announcement.tsx

@@ -6,7 +6,7 @@ import { Badge } from "@/registry/new-york-v4/ui/badge"
 export function Announcement() {
   return (
     <Badge asChild variant="secondary" className="bg-muted">
-      <Link href="/create">
+      <Link href="/docs/changelog">
         Introducing Luma <ArrowRightIcon />
       </Link>
     </Badge>

apps/v4/content/docs/(root)/cli.mdx

@@ -5,7 +5,7 @@ description: Use the shadcn CLI to add components to your project.
 
 ## init
 
-Use the `init` command to initialize configuration and dependencies for a new project.
+Use the `init` command to initialize configuration and dependencies for an existing project, or create a new project with `--name`.
 
 The `init` command installs dependencies, adds the `cn` util and configures CSS variables for the project.
 
@@ -21,26 +21,26 @@ Usage: shadcn init [options] [components...]
 initialize your project and install dependencies
 
 Arguments:
-  components              name, url or local path to component
+  components                 names, url or local path to component
 
 Options:
   -t, --template <template>  the template to use. (next, vite, start, react-router, laravel, astro)
   -b, --base <base>          the component library to use. (radix, base)
-  -p, --preset [name]        use a preset configuration. (name, URL, or preset code)
-  -n, --name <name>          the name for the new project.
-  -d, --defaults             use default configuration. (default: false)
+  -p, --preset [name]        use a preset configuration
   -y, --yes                  skip confirmation prompt. (default: true)
+  -d, --defaults             use default configuration: --template=next --preset=nova (default: false)
   -f, --force                force overwrite of existing configuration. (default: false)
   -c, --cwd <cwd>            the working directory. defaults to the current directory.
+  -n, --name <name>          the name for the new project.
   -s, --silent               mute output. (default: false)
-  --monorepo                 scaffold a monorepo project.
-  --no-monorepo              skip the monorepo prompt.
-  --reinstall                re-install existing UI components.
-  --no-reinstall             do not re-install existing UI components.
-  --rtl                      enable RTL support.
-  --no-rtl                   disable RTL support.
   --css-variables            use css variables for theming. (default: true)
   --no-css-variables         do not use css variables for theming.
+  --monorepo                 scaffold a monorepo project.
+  --no-monorepo              skip the monorepo prompt.
+  --rtl                      enable RTL support.
+  --no-rtl                   disable RTL support.
+  --reinstall                re-install existing UI components.
+  --no-reinstall             do not re-install existing UI components.
   -h, --help                 display help for command
 ```
 
@@ -85,6 +85,34 @@ Options:
 
 ---
 
+## apply
+
+Use the `apply` command to apply a preset to an existing project.
+
+```bash
+npx shadcn@latest apply --preset a2r6bw
+```
+
+**Options**
+
+```bash
+Usage: shadcn apply [options] [preset]
+
+apply a preset to an existing project
+
+Arguments:
+  preset             the preset to apply
+
+Options:
+  --preset <preset>  preset configuration to apply
+  -y, --yes          skip confirmation prompt. (default: false)
+  -c, --cwd <cwd>    the working directory. defaults to the current directory.
+  -s, --silent       mute output. (default: false)
+  -h, --help         display help for command
+```
+
+---
+
 ## view
 
 Use the `view` command to view items from the registry before installing them.

apps/v4/content/docs/(root)/components-json.mdx

@@ -140,15 +140,87 @@ Setting this option to `false` allows components to be added as JavaScript with
 
 ## aliases
 
-The CLI uses these values and the `paths` config from your `tsconfig.json` or `jsconfig.json` file to place generated components in the correct location.
+The CLI uses these values to place generated components in the correct location and rewrite imports.
 
-Path aliases have to be set up in your `tsconfig.json` or `jsconfig.json` file.
+You can back these aliases with either:
+
+1. `compilerOptions.paths` in your `tsconfig.json` or `jsconfig.json`
+2. `package.json#imports` with TypeScript package import resolution enabled
+
+The aliases in `components.json` are still required when using the CLI. They tell the CLI which import roots map to `components`, `ui`, `lib`, `hooks`, and `utils`.
 
 <Callout className="mt-6">
-  **Important:** If you're using the `src` directory, make sure it is included
-  under `paths` in your `tsconfig.json` or `jsconfig.json` file.
+  **Important:** If you're using package imports, enable
+  `resolvePackageJsonImports` and use `moduleResolution: "bundler"` in your
+  `tsconfig.json`. If you're using `paths`, make sure your aliases include the
+  `src` directory when applicable.
 </Callout>
 
+### Using `tsconfig` or `jsconfig` paths
+
+```json title="tsconfig.json"
+{
+  "compilerOptions": {
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  }
+}
+```
+
+### Using `package.json#imports`
+
+Recommended setup for a single-package app:
+
+```json title="package.json"
+{
+  "imports": {
+    "#components/*": "./src/components/*",
+    "#lib/*": "./src/lib/*",
+    "#hooks/*": "./src/hooks/*"
+  }
+}
+```
+
+```json title="tsconfig.json"
+{
+  "compilerOptions": {
+    "moduleResolution": "bundler",
+    "resolvePackageJsonImports": true
+  }
+}
+```
+
+```json title="components.json"
+{
+  "aliases": {
+    "components": "#components",
+    "ui": "#components/ui",
+    "lib": "#lib",
+    "hooks": "#hooks",
+    "utils": "#lib/utils"
+  }
+}
+```
+
+The aliases in `components.json` still tell the CLI where to place
+`components`, `ui`, `lib`, `hooks`, and `utils`. `package.json#imports`
+provides the runtime and TypeScript resolution for those `#...` specifiers.
+
+The matched `imports` target also controls whether generated `#...` imports keep
+file extensions:
+
+- `"#components/*": "./src/components/*"` can generate imports like
+  `#components/button.tsx`
+- `"#components/*": "./src/components/*.tsx"` generates imports like
+  `#components/button`
+
+For monorepos, see the <Link href="/docs/monorepo">monorepo docs</Link>. Local
+workspace aliases can use `package.json#imports`, while shared workspace
+imports such as `@workspace/ui/components` are resolved from the target
+package's `exports`.
+
 ### aliases.utils
 
 Import alias for your utility functions.

apps/v4/content/docs/(root)/monorepo.mdx

@@ -164,3 +164,85 @@ turbo.json
 4. **For Tailwind CSS v4, leave the `tailwind` config empty in the `components.json` file.**
 
 By following these requirements, the CLI will be able to install ui components, blocks, libs and hooks to the correct paths and handle imports for you.
+
+<Callout className="mt-6">
+  `package.json#imports` works well for package-local aliases inside a
+  workspace, for example inside `packages/ui`. For shared workspace imports such
+  as `@workspace/ui/components`, keep explicit aliases in `components.json`. The
+  CLI uses those aliases to route files across workspace boundaries.
+</Callout>
+
+## Using `package.json#imports`
+
+For a monorepo that uses package imports and does not rely on
+`tsconfig.json` `paths`, use:
+
+- local `#...` aliases for files inside each workspace
+- workspace package `exports` for shared imports such as
+  `@workspace/ui/components`
+
+For example, an app workspace can use local package imports:
+
+```json showLineNumbers title="apps/web/package.json"
+{
+  "name": "web",
+  "private": true,
+  "type": "module",
+  "imports": {
+    "#*": "./src/*"
+  },
+  "dependencies": {
+    "@workspace/ui": "workspace:*"
+  }
+}
+```
+
+```json showLineNumbers title="apps/web/components.json"
+{
+  "aliases": {
+    "components": "#components",
+    "ui": "@workspace/ui/components",
+    "lib": "#lib",
+    "hooks": "#hooks",
+    "utils": "@workspace/ui/lib/utils"
+  }
+}
+```
+
+And the shared UI package can expose its install targets with `exports`:
+
+```json showLineNumbers title="packages/ui/package.json"
+{
+  "name": "@workspace/ui",
+  "private": true,
+  "type": "module",
+  "imports": {
+    "#*": "./src/*"
+  },
+  "exports": {
+    "./globals.css": "./src/styles/globals.css",
+    "./components/*": "./src/components/*.tsx",
+    "./lib/*": "./src/lib/*.ts",
+    "./hooks/*": "./src/hooks/*.ts"
+  }
+}
+```
+
+```json showLineNumbers title="packages/ui/components.json"
+{
+  "aliases": {
+    "components": "#components",
+    "ui": "#components",
+    "lib": "#lib",
+    "hooks": "#hooks",
+    "utils": "#lib/utils"
+  }
+}
+```
+
+In this setup:
+
+- files added from the app to the shared UI package are routed through
+  `@workspace/ui/...`
+- files added inside `packages/ui` use the package-local `#...` aliases
+- the shared package must export any path referenced by another workspace

apps/v4/content/docs/changelog/2026-03-luma.mdx

@@ -0,0 +1,37 @@
+---
+title: March 2026 - Introducing Luma
+description: Rounded geometry. Soft elevation. Breathable layouts. Inspired by macOS Tahoe, minus the glass.
+date: 2026-03-31
+---
+
+Introducing Luma, a new shadcn/ui style. Rounded geometry. Soft elevation. Breathable layouts. Inspired by macOS Tahoe, minus the glass.
+
+<a href="/create">
+  <Image
+    src="/images/luma-light.png"
+    width="2160"
+    height="1832"
+    alt="Luma style preview"
+    className="mt-6 w-full overflow-hidden rounded-lg border dark:hidden"
+  />
+  <Image
+    src="/images/luma-dark.png"
+    width="2160"
+    height="1832"
+    alt="Luma style preview"
+    className="mt-6 hidden w-full overflow-hidden rounded-lg border shadow-sm dark:block"
+  />
+  <span className="sr-only">Try Luma in shadcn/create</span>
+</a>
+
+Luma is a new foundation for your next app. It gives components softer surfaces, more open spacing, and a calmer visual rhythm while keeping the same shadcn/ui workflow.
+
+Like the other new styles, Luma goes beyond theming. It changes the geometry, spacing, and feel of the components so your app starts from a different visual baseline.
+
+Available now in [shadcn/create](/create) for both Radix and Base UI.
+
+<Button asChild size="sm">
+  <Link href="/create?preset=b2D0wqNxT" className="mt-6 no-underline!">
+    Try Luma
+  </Link>
+</Button>

apps/v4/content/docs/changelog/2026-04-component-composition.mdx

@@ -0,0 +1,31 @@
+---
+title: April 2026 - Component Composition
+description: Composition sections across component pages—structured trees that help you and your agents build correct UI.
+date: 2026-04-06
+---
+
+We've added **Composition** sections across the component docs so you can see the correct structure at a glance: what wraps what, which subcomponents belong together, and how to avoid invalid nesting.
+
+```text
+Card
+├── CardHeader
+│   ├── CardTitle
+│   ├── CardDescription
+│   └── CardAction
+├── CardContent
+└── CardFooter
+```
+
+## Why we added this
+
+We've found that **LLMs and coding agents compose elements more reliably** when they can see the full structure: fewer missing wrappers, fewer wrong hierarchies, better matches to the examples.
+
+### Bring docs into your agent
+
+You or your LLM can pull the same component documentation, including composition, usage, and examples, into context from the CLI:
+
+```bash
+npx shadcn@latest docs card
+```
+
+If you're using the [shadcn/skills](/docs/skills), this is done automatically for you.

apps/v4/content/docs/components/base/accordion.mdx

@@ -80,6 +80,20 @@ import {
 </Accordion>
 ```
 
+## Composition
+
+Use the following composition to build an `Accordion`:
+
+```text
+Accordion
+├── AccordionItem
+│   ├── AccordionTrigger
+│   └── AccordionContent
+└── AccordionItem
+    ├── AccordionTrigger
+    └── AccordionContent
+```
+
 ## Examples
 
 ### Basic

apps/v4/content/docs/components/base/alert-dialog.mdx

@@ -94,6 +94,23 @@ import {
 </AlertDialog>
 ```
 
+## Composition
+
+Use the following composition to build an `AlertDialog`:
+
+```text
+AlertDialog
+├── AlertDialogTrigger
+└── AlertDialogContent
+    ├── AlertDialogHeader
+    │   ├── AlertDialogMedia
+    │   ├── AlertDialogTitle
+    │   └── AlertDialogDescription
+    └── AlertDialogFooter
+        ├── AlertDialogCancel
+        └── AlertDialogAction
+```
+
 ## Examples
 
 ### Basic

apps/v4/content/docs/components/base/alert.mdx

@@ -67,6 +67,18 @@ import {
 </Alert>
 ```
 
+## Composition
+
+Use the following composition to build an `Alert`:
+
+```text
+Alert
+├── Icon
+├── AlertTitle
+├── AlertDescription
+└── AlertAction
+```
+
 ## Examples
 
 ### Basic

apps/v4/content/docs/components/base/avatar.mdx

@@ -69,6 +69,32 @@ import { Avatar, AvatarFallback, AvatarImage } from "@/components/ui/avatar"
 </Avatar>
 ```
 
+## Composition
+
+Use the following composition to build an `Avatar`:
+
+```text
+Avatar
+├── AvatarImage
+├── AvatarFallback
+└── AvatarBadge
+```
+
+Use the following composition to build an `AvatarGroup`:
+
+```text
+AvatarGroup
+├── Avatar
+│   ├── AvatarImage
+│   ├── AvatarFallback
+│   └── AvatarBadge
+├── Avatar
+│   ├── AvatarImage
+│   ├── AvatarFallback
+│   └── AvatarBadge
+└── AvatarGroupCount
+```
+
 ## Examples
 
 ### Basic

apps/v4/content/docs/components/base/breadcrumb.mdx

@@ -80,6 +80,23 @@ import {
 </Breadcrumb>
 ```
 
+## Composition
+
+Use the following composition to build a `Breadcrumb`:
+
+```text
+Breadcrumb
+└── BreadcrumbList
+    ├── BreadcrumbItem
+    │   └── BreadcrumbLink
+    ├── BreadcrumbSeparator
+    ├── BreadcrumbItem
+    │   └── BreadcrumbLink
+    ├── BreadcrumbSeparator
+    └── BreadcrumbItem
+        └── BreadcrumbPage
+```
+
 ## Examples
 
 ### Basic

apps/v4/content/docs/components/base/button-group.mdx

@@ -66,6 +66,17 @@ import {
 </ButtonGroup>
 ```
 
+## Composition
+
+Use the following composition to build a `ButtonGroup`:
+
+```text
+ButtonGroup
+├── Button or Input
+├── ButtonGroupSeparator
+└── ButtonGroupText
+```
+
 ## Accessibility
 
 - The `ButtonGroup` component has the `role` attribute set to `group`.

apps/v4/content/docs/components/base/card.mdx

@@ -77,6 +77,20 @@ import {
 </Card>
 ```
 
+## Composition
+
+Use the following composition to build a `Card`:
+
+```text
+Card
+├── CardHeader
+│   ├── CardTitle
+│   ├── CardDescription
+│   └── CardAction
+├── CardContent
+└── CardFooter
+```
+
 ## Examples
 
 ### Size

apps/v4/content/docs/components/base/carousel.mdx

@@ -85,6 +85,19 @@ import {
 </Carousel>
 ```
 
+## Composition
+
+Use the following composition to build a `Carousel`:
+
+```text
+Carousel
+├── CarouselContent
+│   ├── CarouselItem
+│   └── CarouselItem
+├── CarouselPrevious
+└── CarouselNext
+```
+
 ## Examples
 
 ### Sizes

apps/v4/content/docs/components/base/collapsible.mdx

@@ -73,6 +73,16 @@ import {
 </Collapsible>
 ```
 
+## Composition
+
+Use the following composition to build a `Collapsible`:
+
+```text
+Collapsible
+├── CollapsibleTrigger
+└── CollapsibleContent
+```
+
 ## Controlled State
 
 Use the `open` and `onOpenChange` props to control the state.

apps/v4/content/docs/components/base/combobox.mdx

@@ -90,6 +90,62 @@ export function ExampleCombobox() {
 }
 ```
 
+## Composition
+
+### Simple
+
+A single-line input and a flat list (see [Basic](#basic)).
+
+```text
+Combobox
+├── ComboboxInput
+└── ComboboxContent
+    ├── ComboboxEmpty
+    └── ComboboxList
+        ├── ComboboxItem
+        └── ComboboxItem
+```
+
+### With chips
+
+Multi-select with `multiple`, chips, and a chips input (see [Multiple](#multiple)).
+
+```text
+Combobox
+├── ComboboxChips
+│   ├── ComboboxValue
+│   │   └── ComboboxChip
+│   └── ComboboxChipsInput
+└── ComboboxContent
+    ├── ComboboxEmpty
+    └── ComboboxList
+        ├── ComboboxItem
+        └── ComboboxItem
+```
+
+### With groups and collection
+
+Nested items per group using `ComboboxCollection` inside each `ComboboxGroup`, with a separator between groups (see [Groups](#groups)).
+
+```text
+Combobox
+├── ComboboxInput
+└── ComboboxContent
+    ├── ComboboxEmpty
+    └── ComboboxList
+        ├── ComboboxGroup
+        │   ├── ComboboxLabel
+        │   └── ComboboxCollection
+        │       ├── ComboboxItem
+        │       └── ComboboxItem
+        ├── ComboboxSeparator
+        └── ComboboxGroup
+            ├── ComboboxLabel
+            └── ComboboxCollection
+                ├── ComboboxItem
+                └── ComboboxItem
+```
+
 ## Custom Items
 
 Use `itemToStringValue` when your items are objects.

apps/v4/content/docs/components/base/command.mdx

@@ -96,6 +96,24 @@ import {
 </Command>
 ```
 
+## Composition
+
+Use the following composition to build a `Command`:
+
+```text
+Command
+├── CommandInput
+└── CommandList
+    ├── CommandEmpty
+    ├── CommandGroup
+    │   ├── CommandItem
+    │   └── CommandItem
+    ├── CommandSeparator
+    └── CommandGroup
+        ├── CommandItem
+        └── CommandItem
+```
+
 ## Examples
 
 ### Basic

apps/v4/content/docs/components/base/context-menu.mdx

@@ -79,6 +79,37 @@ import {
 </ContextMenu>
 ```
 
+## Composition
+
+Use the following composition to build a `ContextMenu`:
+
+```text
+ContextMenu
+├── ContextMenuTrigger
+└── ContextMenuContent
+    ├── ContextMenuGroup
+    │   ├── ContextMenuLabel
+    │   ├── ContextMenuItem
+    │   └── ContextMenuItem
+    ├── ContextMenuSeparator
+    ├── ContextMenuGroup
+    │   ├── ContextMenuLabel
+    │   ├── ContextMenuCheckboxItem
+    │   └── ContextMenuCheckboxItem
+    ├── ContextMenuSeparator
+    ├── ContextMenuGroup
+    │   ├── ContextMenuLabel
+    │   └── ContextMenuRadioGroup
+    │       ├── ContextMenuRadioItem
+    │       └── ContextMenuRadioItem
+    └── ContextMenuSub
+        ├── ContextMenuSubTrigger
+        └── ContextMenuSubContent
+            └── ContextMenuGroup
+                ├── ContextMenuItem
+                └── ContextMenuItem
+```
+
 ## Examples
 
 ### Basic

apps/v4/content/docs/components/base/date-picker.mdx

@@ -58,6 +58,17 @@ export function DatePickerDemo() {
 
 See the [React DayPicker](https://react-day-picker.js.org) documentation for more information.
 
+## Composition
+
+A date picker is built from `Popover` and `Calendar` (there is no `DatePicker` root component):
+
+```text
+Popover
+├── PopoverTrigger
+└── PopoverContent
+    └── Calendar
+```
+
 ## Examples
 
 ### Basic

apps/v4/content/docs/components/base/dialog.mdx

@@ -85,6 +85,20 @@ import {
 </Dialog>
 ```
 
+## Composition
+
+Use the following composition to build a `Dialog`:
+
+```text
+Dialog
+├── DialogTrigger
+└── DialogContent
+    ├── DialogHeader
+    │   ├── DialogTitle
+    │   └── DialogDescription
+    └── DialogFooter
+```
+
 ## Examples
 
 ### Custom Close Button

apps/v4/content/docs/components/base/drawer.mdx

@@ -88,6 +88,20 @@ import {
 </Drawer>
 ```
 
+## Composition
+
+Use the following composition to build a `Drawer`:
+
+```text
+Drawer
+├── DrawerTrigger
+└── DrawerContent
+    ├── DrawerHeader
+    │   ├── DrawerTitle
+    │   └── DrawerDescription
+    └── DrawerFooter
+```
+
 ## Examples
 
 ### Scrollable Content

apps/v4/content/docs/components/base/dropdown-menu.mdx

@@ -92,6 +92,38 @@ import {
 </DropdownMenu>
 ```
 
+## Composition
+
+Use the following composition to build a `DropdownMenu`:
+
+```text
+DropdownMenu
+├── DropdownMenuTrigger
+└── DropdownMenuContent
+    ├── DropdownMenuGroup
+    │   ├── DropdownMenuLabel
+    │   ├── DropdownMenuItem
+    │   └── DropdownMenuItem
+    ├── DropdownMenuSeparator
+    ├── DropdownMenuGroup
+    │   ├── DropdownMenuLabel
+    │   ├── DropdownMenuCheckboxItem
+    │   └── DropdownMenuCheckboxItem
+    ├── DropdownMenuSeparator
+    ├── DropdownMenuGroup
+    │   ├── DropdownMenuLabel
+    │   └── DropdownMenuRadioGroup
+    │       ├── DropdownMenuRadioItem
+    │       └── DropdownMenuRadioItem
+    └── DropdownMenuSub
+        ├── DropdownMenuSubTrigger
+        └── DropdownMenuSubContent
+            └── DropdownMenuGroup
+                ├── DropdownMenuLabel
+                ├── DropdownMenuItem
+                └── DropdownMenuItem
+```
+
 ## Examples
 
 ### Basic

apps/v4/content/docs/components/base/empty.mdx

@@ -75,6 +75,19 @@ import {
 </Empty>
 ```
 
+## Composition
+
+Use the following composition to build an `Empty` state:
+
+```text
+Empty
+├── EmptyHeader
+│   ├── EmptyMedia
+│   ├── EmptyTitle
+│   └── EmptyDescription
+└── EmptyContent
+```
+
 ## Examples
 
 ### Outline

apps/v4/content/docs/components/base/field.mdx

@@ -87,6 +87,56 @@ import {
 </FieldSet>
 ```
 
+## Composition
+
+### Field
+
+A single control with label, helper text, and validation.
+
+```text
+Field
+├── FieldLabel
+├── Input / Textarea / Switch / Select
+├── FieldDescription
+└── FieldError
+```
+
+### FieldGroup
+
+Related fields in one group. Use `FieldSeparator` between sections when needed.
+
+```text
+FieldGroup
+├── Field
+│   ├── FieldLabel
+│   ├── Input / Textarea / Switch / Select
+│   ├── FieldDescription
+│   └── FieldError
+├── FieldSeparator
+└── Field
+    ├── FieldLabel
+    └── Input / Textarea / Switch / Select
+```
+
+### FieldSet
+
+Semantic grouping with a legend and description, usually containing a `FieldGroup`.
+
+```text
+FieldSet
+├── FieldLegend
+├── FieldDescription
+└── FieldGroup
+    ├── Field
+    │   ├── FieldLabel
+    │   ├── Input / Textarea / Switch / Select
+    │   ├── FieldDescription
+    │   └── FieldError
+    └── Field
+        ├── FieldLabel
+        └── Input / Textarea / Switch / Select
+```
+
 ## Anatomy
 
 The `Field` family is designed for composing accessible forms. A typical field is structured as follows:

apps/v4/content/docs/components/base/hover-card.mdx

@@ -75,6 +75,16 @@ import {
 </HoverCard>
 ```
 
+## Composition
+
+Use the following composition to build a `HoverCard`:
+
+```text
+HoverCard
+├── HoverCardTrigger
+└── HoverCardContent
+```
+
 ## Trigger Delays
 
 Use `delay` and `closeDelay` on the trigger to control when the card opens and

apps/v4/content/docs/components/base/input-group.mdx

@@ -71,6 +71,18 @@ import {
 </InputGroup>
 ```
 
+## Composition
+
+Use the following composition to build an `InputGroup`:
+
+```text
+InputGroup
+├── InputGroupInput or InputGroupTextarea
+├── InputGroupAddon
+├── InputGroupButton
+└── InputGroupText
+```
+
 ## Align
 
 Use the `align` prop on `InputGroupAddon` to position the addon relative to the input.

apps/v4/content/docs/components/base/input-otp.mdx

@@ -82,6 +82,27 @@ import {
 </InputOTP>
 ```
 
+## Composition
+
+Use the following composition to build an `InputOTP`:
+
+```text
+InputOTP
+├── InputOTPGroup
+│   ├── InputOTPSlot
+│   ├── InputOTPSlot
+│   └── InputOTPSlot
+├── InputOTPSeparator
+├── InputOTPGroup
+│   ├── InputOTPSlot
+│   ├── InputOTPSlot
+│   └── InputOTPSlot
+├── InputOTPSeparator
+└── InputOTPGroup
+    ├── InputOTPSlot
+    └── InputOTPSlot
+```
+
 ## Pattern
 
 Use the `pattern` prop to define a custom pattern for the OTP input.

apps/v4/content/docs/components/base/item.mdx

@@ -73,6 +73,22 @@ import {
 </Item>
 ```
 
+## Composition
+
+Use the following composition to build an `Item`:
+
+```text
+ItemGroup
+└── Item
+    ├── ItemHeader
+    ├── ItemMedia
+    ├── ItemContent
+    │   ├── ItemTitle
+    │   └── ItemDescription
+    ├── ItemActions
+    └── ItemFooter
+```
+
 ## Item vs Field
 
 Use `Field` if you need to display a form input such as a checkbox, input, radio, or select.

apps/v4/content/docs/components/base/kbd.mdx

@@ -53,6 +53,17 @@ import { Kbd } from "@/components/ui/kbd"
 <Kbd>Ctrl</Kbd>
 ```
 
+## Composition
+
+Use the following composition to build `Kbd` and `KbdGroup`:
+
+```text
+Kbd
+KbdGroup
+├── Kbd
+└── Kbd
+```
+
 ## Examples
 
 ### Group

apps/v4/content/docs/components/base/menubar.mdx

@@ -88,6 +88,46 @@ import {
 </Menubar>
 ```
 
+## Composition
+
+Use the following composition to build a `Menubar`:
+
+```text
+Menubar
+├── MenubarMenu
+│   ├── MenubarTrigger
+│   └── MenubarContent
+│       ├── MenubarGroup
+│       │   ├── MenubarLabel
+│       │   ├── MenubarItem
+│       │   └── MenubarItem
+│       ├── MenubarSeparator
+│       ├── MenubarGroup
+│       │   ├── MenubarLabel
+│       │   ├── MenubarCheckboxItem
+│       │   └── MenubarCheckboxItem
+│       ├── MenubarSeparator
+│       ├── MenubarGroup
+│       │   ├── MenubarLabel
+│       │   └── MenubarRadioGroup
+│       │       ├── MenubarRadioItem
+│       │       └── MenubarRadioItem
+│       └── MenubarSub
+│           ├── MenubarSubTrigger
+│           └── MenubarSubContent
+│               └── MenubarGroup
+│                   ├── MenubarLabel
+│                   ├── MenubarItem
+│                   └── MenubarItem
+└── MenubarMenu
+    ├── MenubarTrigger
+    └── MenubarContent
+        └── MenubarGroup
+            ├── MenubarLabel
+            ├── MenubarItem
+            └── MenubarItem
+```
+
 ## Examples
 
 ### Checkbox

apps/v4/content/docs/components/base/native-select.mdx

@@ -70,6 +70,34 @@ import {
 </NativeSelect>
 ```
 
+## Composition
+
+### Simple
+
+Options placed directly under `NativeSelect` (no `NativeSelectOptGroup`).
+
+```text
+NativeSelect
+├── NativeSelectOption
+├── NativeSelectOption
+├── NativeSelectOption
+└── NativeSelectOption
+```
+
+### With groups
+
+Use `NativeSelectOptGroup` to organize options into categories.
+
+```text
+NativeSelect
+├── NativeSelectOptGroup
+│   ├── NativeSelectOption
+│   └── NativeSelectOption
+└── NativeSelectOptGroup
+    ├── NativeSelectOption
+    └── NativeSelectOption
+```
+
 ## Examples
 
 ### Groups

apps/v4/content/docs/components/base/navigation-menu.mdx

@@ -82,6 +82,23 @@ import {
 </NavigationMenu>
 ```
 
+## Composition
+
+Use the following composition to build a `NavigationMenu`:
+
+```text
+NavigationMenu
+├── NavigationMenuList
+│   ├── NavigationMenuItem
+│   │   ├── NavigationMenuTrigger
+│   │   └── NavigationMenuContent
+│   │       ├── NavigationMenuLink
+│   │       └── NavigationMenuLink
+│   └── NavigationMenuItem
+│       └── NavigationMenuLink
+└── NavigationMenuIndicator
+```
+
 ## Link Component
 
 Use the `render` prop to compose a custom link component such as Next.js `Link`.

apps/v4/content/docs/components/base/pagination.mdx

@@ -84,6 +84,23 @@ import {
 </Pagination>
 ```
 
+## Composition
+
+Use the following composition to build a `Pagination`:
+
+```text
+Pagination
+└── PaginationContent
+    ├── PaginationItem
+    │   └── PaginationPrevious
+    ├── PaginationItem
+    │   └── PaginationLink
+    ├── PaginationItem
+    │   └── PaginationEllipsis
+    └── PaginationItem
+        └── PaginationNext
+```
+
 ## Examples
 
 ### Simple

apps/v4/content/docs/components/base/popover.mdx

@@ -79,6 +79,16 @@ import {
 </Popover>
 ```
 
+## Composition
+
+Use the following composition to build a `Popover`:
+
+```text
+Popover
+├── PopoverTrigger
+└── PopoverContent
+```
+
 ## Examples
 
 ### Basic

apps/v4/content/docs/components/base/progress.mdx

@@ -62,6 +62,33 @@ import { Progress } from "@/components/ui/progress"
 <Progress value={33} />
 ```
 
+## Composition
+
+### With label and value
+
+Use `ProgressLabel` and `ProgressValue` to add a label and value display.
+
+```tsx showLineNumbers
+import {
+  Progress,
+  ProgressLabel,
+  ProgressValue,
+} from "@/components/ui/progress"
+
+;<Progress value={56} className="w-full max-w-sm">
+  <ProgressLabel>Upload progress</ProgressLabel>
+  <ProgressValue />
+</Progress>
+```
+
+```text
+Progress
+├── ProgressLabel
+├── ProgressValue
+└── ProgressTrack
+    └── ProgressIndicator
+```
+
 ## Examples
 
 ### Label

apps/v4/content/docs/components/base/radio-group.mdx

@@ -72,6 +72,16 @@ import { RadioGroup, RadioGroupItem } from "@/components/ui/radio-group"
 </RadioGroup>
 ```
 
+## Composition
+
+Use the following composition to build a `RadioGroup`:
+
+```text
+RadioGroup
+├── RadioGroupItem
+└── RadioGroupItem
+```
+
 ## Examples
 
 ### Description

apps/v4/content/docs/components/base/resizable.mdx

@@ -78,6 +78,17 @@ import {
 </ResizablePanelGroup>
 ```
 
+## Composition
+
+Use the following composition to build a `ResizablePanelGroup`:
+
+```text
+ResizablePanelGroup
+├── ResizablePanel
+├── ResizableHandle
+└── ResizablePanel
+```
+
 ## Examples
 
 ### Vertical

apps/v4/content/docs/components/base/scroll-area.mdx

@@ -68,6 +68,15 @@ import { ScrollArea, ScrollBar } from "@/components/ui/scroll-area"
 </ScrollArea>
 ```
 
+## Composition
+
+Use the following composition to build a `ScrollArea`:
+
+```text
+ScrollArea
+└── ScrollBar
+```
+
 ## Examples
 
 ### Horizontal

apps/v4/content/docs/components/base/select.mdx

@@ -89,6 +89,26 @@ const items = [
 </Select>
 ```
 
+## Composition
+
+Use the following composition to build a `Select`:
+
+```text
+Select
+├── SelectTrigger
+│   └── SelectValue
+└── SelectContent
+    ├── SelectGroup
+    │   ├── SelectLabel
+    │   ├── SelectItem
+    │   └── SelectItem
+    ├── SelectSeparator
+    └── SelectGroup
+        ├── SelectLabel
+        ├── SelectItem
+        └── SelectItem
+```
+
 ## Examples
 
 ### Align Item With Trigger

apps/v4/content/docs/components/base/sheet.mdx

@@ -79,6 +79,20 @@ import {
 </Sheet>
 ```
 
+## Composition
+
+Use the following composition to build a `Sheet`:
+
+```text
+Sheet
+├── SheetTrigger
+└── SheetContent
+    ├── SheetHeader
+    │   ├── SheetTitle
+    │   └── SheetDescription
+    └── SheetFooter
+```
+
 ## Examples
 
 ### Side

apps/v4/content/docs/components/base/sidebar.mdx

@@ -55,32 +55,6 @@ npx shadcn@latest add sidebar
 
 </CodeTabs>
 
-## Structure
-
-A `Sidebar` component is composed of the following parts:
-
-- `SidebarProvider` - Handles collapsible state.
-- `Sidebar` - The sidebar container.
-- `SidebarHeader` and `SidebarFooter` - Sticky at the top and bottom of the sidebar.
-- `SidebarContent` - Scrollable content.
-- `SidebarGroup` - Section within the `SidebarContent`.
-- `SidebarTrigger` - Trigger for the `Sidebar`.
-
-<Image
-  src="/images/sidebar-structure.png"
-  width="716"
-  height="420"
-  alt="Sidebar Structure"
-  className="mt-6 w-full overflow-hidden rounded-lg border dark:hidden"
-/>
-<Image
-  src="/images/sidebar-structure-dark.png"
-  width="716"
-  height="420"
-  alt="Sidebar Structure"
-  className="mt-6 hidden w-full overflow-hidden rounded-lg border dark:block"
-/>
-
 ## Usage
 
 ```tsx showLineNumbers title="app/layout.tsx"
@@ -123,6 +97,67 @@ export function AppSidebar() {
 }
 ```
 
+## Composition
+
+Use the following composition to build a `Sidebar` layout:
+
+```text
+SidebarProvider
+├── Sidebar
+│   ├── SidebarHeader
+│   ├── SidebarContent
+│   │   ├── SidebarGroup
+│   │   │   ├── SidebarGroupLabel
+│   │   │   ├── SidebarGroupAction
+│   │   │   ├── SidebarGroupContent
+│   │   │   └── SidebarMenu
+│   │   │       ├── SidebarMenuItem
+│   │   │       │   ├── SidebarMenuButton
+│   │   │       │   ├── SidebarMenuAction
+│   │   │       │   └── SidebarMenuBadge
+│   │   │       └── SidebarMenuItem
+│   │   │           ├── SidebarMenuButton
+│   │   │           └── SidebarMenuSub
+│   │   │               ├── SidebarMenuSubItem
+│   │   │               └── SidebarMenuSubItem
+│   │   └── SidebarGroup
+│   │       └── SidebarMenu
+│   │           ├── SidebarMenuItem
+│   │           └── SidebarMenuItem
+│   ├── SidebarFooter
+│   └── SidebarRail
+├── SidebarInset
+└── SidebarTrigger
+```
+
+## Structure
+
+- **SidebarProvider** — Handles collapsible state and provides sidebar context to child components.
+- **Sidebar** — The main collapsible sidebar panel.
+- **SidebarHeader** — Sticky at the top; use for branding, titles, or workspace switchers.
+- **SidebarFooter** — Sticky at the bottom; use for user menus, settings, or actions.
+- **SidebarContent** — Scrollable region between the header and footer.
+- **SidebarGroup** — Groups related navigation with optional label, action, and content areas.
+- **SidebarMenu** / **SidebarMenuItem** — Menu structure for links, badges, actions, and nested submenus.
+- **SidebarRail** — Resize handle for adjusting sidebar width when applicable.
+- **SidebarInset** — Wraps main content when using the `inset` variant.
+- **SidebarTrigger** — Control that toggles the sidebar open or collapsed.
+
+<Image
+  src="/images/sidebar-structure.png"
+  width="716"
+  height="420"
+  alt="Sidebar Structure"
+  className="mt-6 w-full overflow-hidden rounded-lg border dark:hidden"
+/>
+<Image
+  src="/images/sidebar-structure-dark.png"
+  width="716"
+  height="420"
+  alt="Sidebar Structure"
+  className="mt-6 hidden w-full overflow-hidden rounded-lg border dark:block"
+/>
+
 ## SidebarProvider
 
 The `SidebarProvider` component is used to provide the sidebar context to the `Sidebar` component. You should always wrap your application in a `SidebarProvider` component.

apps/v4/content/docs/components/base/table.mdx

@@ -83,6 +83,33 @@ import {
 </Table>
 ```
 
+## Composition
+
+Use the following composition to build a `Table`:
+
+```text
+Table
+├── TableCaption
+├── TableHeader
+│   └── TableRow
+│       ├── TableHead
+│       ├── TableHead
+│       ├── TableHead
+│       └── TableHead
+├── TableBody
+│   ├── TableRow
+│   │   ├── TableCell
+│   │   ├── TableCell
+│   │   ├── TableCell
+│   │   └── TableCell
+│   └── TableRow
+│       ├── TableCell
+│       ├── TableCell
+│       ├── TableCell
+│       └── TableCell
+└── TableFooter
+```
+
 ## Examples
 
 ### Footer

apps/v4/content/docs/components/base/tabs.mdx

@@ -73,6 +73,19 @@ import { Tabs, TabsContent, TabsList, TabsTrigger } from "@/components/ui/tabs"
 </Tabs>
 ```
 
+## Composition
+
+Use the following composition to build `Tabs`:
+
+```text
+Tabs
+├── TabsList
+│   ├── TabsTrigger
+│   └── TabsTrigger
+├── TabsContent
+└── TabsContent
+```
+
 ## Examples
 
 ### Line

apps/v4/content/docs/components/base/toggle-group.mdx

@@ -66,6 +66,16 @@ import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group"
 </ToggleGroup>
 ```
 
+## Composition
+
+Use the following composition to build a `ToggleGroup`:
+
+```text
+ToggleGroup
+├── ToggleGroupItem
+└── ToggleGroupItem
+```
+
 ## Examples
 
 ### Outline

apps/v4/content/docs/components/base/tooltip.mdx

@@ -109,6 +109,16 @@ import {
 </Tooltip>
 ```
 
+## Composition
+
+Use the following composition to build a `Tooltip`:
+
+```text
+Tooltip
+├── TooltipTrigger
+└── TooltipContent
+```
+
 ## Examples
 
 ### Side

apps/v4/content/docs/components/radix/accordion.mdx

@@ -80,6 +80,20 @@ import {
 </Accordion>
 ```
 
+## Composition
+
+Use the following composition to build an `Accordion`:
+
+```text
+Accordion
+├── AccordionItem
+│   ├── AccordionTrigger
+│   └── AccordionContent
+└── AccordionItem
+    ├── AccordionTrigger
+    └── AccordionContent
+```
+
 ## Examples
 
 ### Basic

apps/v4/content/docs/components/radix/alert-dialog.mdx

@@ -94,6 +94,23 @@ import {
 </AlertDialog>
 ```
 
+## Composition
+
+Use the following composition to build an `AlertDialog`:
+
+```text
+AlertDialog
+├── AlertDialogTrigger
+└── AlertDialogContent
+    ├── AlertDialogHeader
+    │   ├── AlertDialogMedia
+    │   ├── AlertDialogTitle
+    │   └── AlertDialogDescription
+    └── AlertDialogFooter
+        ├── AlertDialogCancel
+        └── AlertDialogAction
+```
+
 ## Examples
 
 ### Basic

apps/v4/content/docs/components/radix/alert.mdx

@@ -71,6 +71,18 @@ import {
 </Alert>
 ```
 
+## Composition
+
+Use the following composition to build an `Alert`:
+
+```text
+Alert
+├── Icon
+├── AlertTitle
+├── AlertDescription
+└── AlertAction
+```
+
 ## Examples
 
 ### Basic

apps/v4/content/docs/components/radix/avatar.mdx

@@ -65,6 +65,32 @@ import { Avatar, AvatarFallback, AvatarImage } from "@/components/ui/avatar"
 </Avatar>
 ```
 
+## Composition
+
+Use the following composition to build an `Avatar`:
+
+```text
+Avatar
+├── AvatarImage
+├── AvatarFallback
+└── AvatarBadge
+```
+
+Use the following composition to build an `AvatarGroup`:
+
+```text
+AvatarGroup
+├── Avatar
+│   ├── AvatarImage
+│   ├── AvatarFallback
+│   └── AvatarBadge
+├── Avatar
+│   ├── AvatarImage
+│   ├── AvatarFallback
+│   └── AvatarBadge
+└── AvatarGroupCount
+```
+
 ## Examples
 
 ### Basic

apps/v4/content/docs/components/radix/breadcrumb.mdx

@@ -74,6 +74,23 @@ import {
 </Breadcrumb>
 ```
 
+## Composition
+
+Use the following composition to build a `Breadcrumb`:
+
+```text
+Breadcrumb
+└── BreadcrumbList
+    ├── BreadcrumbItem
+    │   └── BreadcrumbLink
+    ├── BreadcrumbSeparator
+    ├── BreadcrumbItem
+    │   └── BreadcrumbLink
+    ├── BreadcrumbSeparator
+    └── BreadcrumbItem
+        └── BreadcrumbPage
+```
+
 ## Examples
 
 ### Basic

apps/v4/content/docs/components/radix/button-group.mdx

@@ -66,6 +66,17 @@ import {
 </ButtonGroup>
 ```
 
+## Composition
+
+Use the following composition to build a `ButtonGroup`:
+
+```text
+ButtonGroup
+├── Button or Input
+├── ButtonGroupSeparator
+└── ButtonGroupText
+```
+
 ## Accessibility
 
 - The `ButtonGroup` component has the `role` attribute set to `group`.

apps/v4/content/docs/components/radix/card.mdx

@@ -77,6 +77,20 @@ import {
 </Card>
 ```
 
+## Composition
+
+Use the following composition to build a `Card`:
+
+```text
+Card
+├── CardHeader
+│   ├── CardTitle
+│   ├── CardDescription
+│   └── CardAction
+├── CardContent
+└── CardFooter
+```
+
 ## Examples
 
 ### Size

apps/v4/content/docs/components/radix/carousel.mdx

@@ -85,6 +85,19 @@ import {
 </Carousel>
 ```
 
+## Composition
+
+Use the following composition to build a `Carousel`:
+
+```text
+Carousel
+├── CarouselContent
+│   ├── CarouselItem
+│   └── CarouselItem
+├── CarouselPrevious
+└── CarouselNext
+```
+
 ## Examples
 
 ### Sizes

apps/v4/content/docs/components/radix/collapsible.mdx

@@ -77,6 +77,16 @@ import {
 </Collapsible>
 ```
 
+## Composition
+
+Use the following composition to build a `Collapsible`:
+
+```text
+Collapsible
+├── CollapsibleTrigger
+└── CollapsibleContent
+```
+
 ## Controlled State
 
 Use the `open` and `onOpenChange` props to control the state.

apps/v4/content/docs/components/radix/combobox.mdx

@@ -90,6 +90,62 @@ export function ExampleCombobox() {
 }
 ```
 
+## Composition
+
+### Simple
+
+A single-line input and a flat list (see [Basic](#basic)).
+
+```text
+Combobox
+├── ComboboxInput
+└── ComboboxContent
+    ├── ComboboxEmpty
+    └── ComboboxList
+        ├── ComboboxItem
+        └── ComboboxItem
+```
+
+### With chips
+
+Multi-select with `multiple`, chips, and a chips input (see [Multiple](#multiple)).
+
+```text
+Combobox
+├── ComboboxChips
+│   ├── ComboboxValue
+│   │   └── ComboboxChip
+│   └── ComboboxChipsInput
+└── ComboboxContent
+    ├── ComboboxEmpty
+    └── ComboboxList
+        ├── ComboboxItem
+        └── ComboboxItem
+```
+
+### With groups and collection
+
+Nested items per group using `ComboboxCollection` inside each `ComboboxGroup`, with a separator between groups (see [Groups](#groups)).
+
+```text
+Combobox
+├── ComboboxInput
+└── ComboboxContent
+    ├── ComboboxEmpty
+    └── ComboboxList
+        ├── ComboboxGroup
+        │   ├── ComboboxLabel
+        │   └── ComboboxCollection
+        │       ├── ComboboxItem
+        │       └── ComboboxItem
+        ├── ComboboxSeparator
+        └── ComboboxGroup
+            ├── ComboboxLabel
+            └── ComboboxCollection
+                ├── ComboboxItem
+                └── ComboboxItem
+```
+
 ## Custom Items
 
 Use `itemToStringValue` when your items are objects.

apps/v4/content/docs/components/radix/command.mdx

@@ -96,6 +96,24 @@ import {
 </Command>
 ```
 
+## Composition
+
+Use the following composition to build a `Command`:
+
+```text
+Command
+├── CommandInput
+└── CommandList
+    ├── CommandEmpty
+    ├── CommandGroup
+    │   ├── CommandItem
+    │   └── CommandItem
+    ├── CommandSeparator
+    └── CommandGroup
+        ├── CommandItem
+        └── CommandItem
+```
+
 ## Examples
 
 ### Basic

apps/v4/content/docs/components/radix/context-menu.mdx

@@ -79,6 +79,37 @@ import {
 </ContextMenu>
 ```
 
+## Composition
+
+Use the following composition to build a `ContextMenu`:
+
+```text
+ContextMenu
+├── ContextMenuTrigger
+└── ContextMenuContent
+    ├── ContextMenuGroup
+    │   ├── ContextMenuLabel
+    │   ├── ContextMenuItem
+    │   └── ContextMenuItem
+    ├── ContextMenuSeparator
+    ├── ContextMenuGroup
+    │   ├── ContextMenuLabel
+    │   ├── ContextMenuCheckboxItem
+    │   └── ContextMenuCheckboxItem
+    ├── ContextMenuSeparator
+    ├── ContextMenuGroup
+    │   ├── ContextMenuLabel
+    │   └── ContextMenuRadioGroup
+    │       ├── ContextMenuRadioItem
+    │       └── ContextMenuRadioItem
+    └── ContextMenuSub
+        ├── ContextMenuSubTrigger
+        └── ContextMenuSubContent
+            └── ContextMenuGroup
+                ├── ContextMenuItem
+                └── ContextMenuItem
+```
+
 ## Examples
 
 ### Basic

apps/v4/content/docs/components/radix/date-picker.mdx

@@ -56,6 +56,17 @@ export function DatePickerDemo() {
 
 See the [React DayPicker](https://react-day-picker.js.org) documentation for more information.
 
+## Composition
+
+A date picker is built from `Popover` and `Calendar` (there is no `DatePicker` root component):
+
+```text
+Popover
+├── PopoverTrigger
+└── PopoverContent
+    └── Calendar
+```
+
 ## Examples
 
 ### Basic

apps/v4/content/docs/components/radix/dialog.mdx

@@ -85,6 +85,20 @@ import {
 </Dialog>
 ```
 
+## Composition
+
+Use the following composition to build a `Dialog`:
+
+```text
+Dialog
+├── DialogTrigger
+└── DialogContent
+    ├── DialogHeader
+    │   ├── DialogTitle
+    │   └── DialogDescription
+    └── DialogFooter
+```
+
 ## Examples
 
 ### Custom Close Button

apps/v4/content/docs/components/radix/drawer.mdx

@@ -88,6 +88,20 @@ import {
 </Drawer>
 ```
 
+## Composition
+
+Use the following composition to build a `Drawer`:
+
+```text
+Drawer
+├── DrawerTrigger
+└── DrawerContent
+    ├── DrawerHeader
+    │   ├── DrawerTitle
+    │   └── DrawerDescription
+    └── DrawerFooter
+```
+
 ## Examples
 
 ### Scrollable Content

apps/v4/content/docs/components/radix/dropdown-menu.mdx

@@ -92,6 +92,38 @@ import {
 </DropdownMenu>
 ```
 
+## Composition
+
+Use the following composition to build a `DropdownMenu`:
+
+```text
+DropdownMenu
+├── DropdownMenuTrigger
+└── DropdownMenuContent
+    ├── DropdownMenuGroup
+    │   ├── DropdownMenuLabel
+    │   ├── DropdownMenuItem
+    │   └── DropdownMenuItem
+    ├── DropdownMenuSeparator
+    ├── DropdownMenuGroup
+    │   ├── DropdownMenuLabel
+    │   ├── DropdownMenuCheckboxItem
+    │   └── DropdownMenuCheckboxItem
+    ├── DropdownMenuSeparator
+    ├── DropdownMenuGroup
+    │   ├── DropdownMenuLabel
+    │   └── DropdownMenuRadioGroup
+    │       ├── DropdownMenuRadioItem
+    │       └── DropdownMenuRadioItem
+    └── DropdownMenuSub
+        ├── DropdownMenuSubTrigger
+        └── DropdownMenuSubContent
+            └── DropdownMenuGroup
+                ├── DropdownMenuLabel
+                ├── DropdownMenuItem
+                └── DropdownMenuItem
+```
+
 ## Examples
 
 ### Basic

apps/v4/content/docs/components/radix/empty.mdx

@@ -75,6 +75,19 @@ import {
 </Empty>
 ```
 
+## Composition
+
+Use the following composition to build an `Empty` state:
+
+```text
+Empty
+├── EmptyHeader
+│   ├── EmptyMedia
+│   ├── EmptyTitle
+│   └── EmptyDescription
+└── EmptyContent
+```
+
 ## Examples
 
 ### Outline

apps/v4/content/docs/components/radix/field.mdx

@@ -87,6 +87,56 @@ import {
 </FieldSet>
 ```
 
+## Composition
+
+### Field
+
+A single control with label, helper text, and validation.
+
+```text
+Field
+├── FieldLabel
+├── Input / Textarea / Switch / Select
+├── FieldDescription
+└── FieldError
+```
+
+### FieldGroup
+
+Related fields in one group. Use `FieldSeparator` between sections when needed.
+
+```text
+FieldGroup
+├── Field
+│   ├── FieldLabel
+│   ├── Input / Textarea / Switch / Select
+│   ├── FieldDescription
+│   └── FieldError
+├── FieldSeparator
+└── Field
+    ├── FieldLabel
+    └── Input / Textarea / Switch / Select
+```
+
+### FieldSet
+
+Semantic grouping with a legend and description, usually containing a `FieldGroup`.
+
+```text
+FieldSet
+├── FieldLegend
+├── FieldDescription
+└── FieldGroup
+    ├── Field
+    │   ├── FieldLabel
+    │   ├── Input / Textarea / Switch / Select
+    │   ├── FieldDescription
+    │   └── FieldError
+    └── Field
+        ├── FieldLabel
+        └── Input / Textarea / Switch / Select
+```
+
 ## Anatomy
 
 The `Field` family is designed for composing accessible forms. A typical field is structured as follows:

apps/v4/content/docs/components/radix/hover-card.mdx

@@ -75,6 +75,16 @@ import {
 </HoverCard>
 ```
 
+## Composition
+
+Use the following composition to build a `HoverCard`:
+
+```text
+HoverCard
+├── HoverCardTrigger
+└── HoverCardContent
+```
+
 ## Trigger Delays
 
 Use `openDelay` and `closeDelay` on the `HoverCard` to control when the card opens and

apps/v4/content/docs/components/radix/input-group.mdx

@@ -71,6 +71,18 @@ import {
 </InputGroup>
 ```
 
+## Composition
+
+Use the following composition to build an `InputGroup`:
+
+```text
+InputGroup
+├── InputGroupInput or InputGroupTextarea
+├── InputGroupAddon
+├── InputGroupButton
+└── InputGroupText
+```
+
 ## Align
 
 Use the `align` prop on `InputGroupAddon` to position the addon relative to the input.

apps/v4/content/docs/components/radix/input-otp.mdx

@@ -82,6 +82,27 @@ import {
 </InputOTP>
 ```
 
+## Composition
+
+Use the following composition to build an `InputOTP`:
+
+```text
+InputOTP
+├── InputOTPGroup
+│   ├── InputOTPSlot
+│   ├── InputOTPSlot
+│   └── InputOTPSlot
+├── InputOTPSeparator
+├── InputOTPGroup
+│   ├── InputOTPSlot
+│   ├── InputOTPSlot
+│   └── InputOTPSlot
+├── InputOTPSeparator
+└── InputOTPGroup
+    ├── InputOTPSlot
+    └── InputOTPSlot
+```
+
 ## Pattern
 
 Use the `pattern` prop to define a custom pattern for the OTP input.

apps/v4/content/docs/components/radix/item.mdx

@@ -73,6 +73,22 @@ import {
 </Item>
 ```
 
+## Composition
+
+Use the following composition to build an `Item`:
+
+```text
+ItemGroup
+└── Item
+    ├── ItemHeader
+    ├── ItemMedia
+    ├── ItemContent
+    │   ├── ItemTitle
+    │   └── ItemDescription
+    ├── ItemActions
+    └── ItemFooter
+```
+
 ## Item vs Field
 
 Use `Field` if you need to display a form input such as a checkbox, input, radio, or select.

apps/v4/content/docs/components/radix/kbd.mdx

@@ -53,6 +53,17 @@ import { Kbd } from "@/components/ui/kbd"
 <Kbd>Ctrl</Kbd>
 ```
 
+## Composition
+
+Use the following composition to build `Kbd` and `KbdGroup`:
+
+```text
+Kbd
+KbdGroup
+├── Kbd
+└── Kbd
+```
+
 ## Examples
 
 ### Group

apps/v4/content/docs/components/radix/menubar.mdx

@@ -88,6 +88,46 @@ import {
 </Menubar>
 ```
 
+## Composition
+
+Use the following composition to build a `Menubar`:
+
+```text
+Menubar
+├── MenubarMenu
+│   ├── MenubarTrigger
+│   └── MenubarContent
+│       ├── MenubarGroup
+│       │   ├── MenubarLabel
+│       │   ├── MenubarItem
+│       │   └── MenubarItem
+│       ├── MenubarSeparator
+│       ├── MenubarGroup
+│       │   ├── MenubarLabel
+│       │   ├── MenubarCheckboxItem
+│       │   └── MenubarCheckboxItem
+│       ├── MenubarSeparator
+│       ├── MenubarGroup
+│       │   ├── MenubarLabel
+│       │   └── MenubarRadioGroup
+│       │       ├── MenubarRadioItem
+│       │       └── MenubarRadioItem
+│       └── MenubarSub
+│           ├── MenubarSubTrigger
+│           └── MenubarSubContent
+│               └── MenubarGroup
+│                   ├── MenubarLabel
+│                   ├── MenubarItem
+│                   └── MenubarItem
+└── MenubarMenu
+    ├── MenubarTrigger
+    └── MenubarContent
+        └── MenubarGroup
+            ├── MenubarLabel
+            ├── MenubarItem
+            └── MenubarItem
+```
+
 ## Examples
 
 ### Checkbox

apps/v4/content/docs/components/radix/native-select.mdx

@@ -70,6 +70,34 @@ import {
 </NativeSelect>
 ```
 
+## Composition
+
+### Simple
+
+Options placed directly under `NativeSelect` (no `NativeSelectOptGroup`).
+
+```text
+NativeSelect
+├── NativeSelectOption
+├── NativeSelectOption
+├── NativeSelectOption
+└── NativeSelectOption
+```
+
+### With groups
+
+Use `NativeSelectOptGroup` to organize options into categories.
+
+```text
+NativeSelect
+├── NativeSelectOptGroup
+│   ├── NativeSelectOption
+│   └── NativeSelectOption
+└── NativeSelectOptGroup
+    ├── NativeSelectOption
+    └── NativeSelectOption
+```
+
 ## Examples
 
 ### Groups

apps/v4/content/docs/components/radix/navigation-menu.mdx

@@ -82,6 +82,23 @@ import {
 </NavigationMenu>
 ```
 
+## Composition
+
+Use the following composition to build a `NavigationMenu`:
+
+```text
+NavigationMenu
+├── NavigationMenuList
+│   ├── NavigationMenuItem
+│   │   ├── NavigationMenuTrigger
+│   │   └── NavigationMenuContent
+│   │       ├── NavigationMenuLink
+│   │       └── NavigationMenuLink
+│   └── NavigationMenuItem
+│       └── NavigationMenuLink
+└── NavigationMenuIndicator
+```
+
 ## Link Component
 
 Use the `asChild` prop to compose a custom link component such as Next.js `Link`.

apps/v4/content/docs/components/radix/pagination.mdx

@@ -84,6 +84,23 @@ import {
 </Pagination>
 ```
 
+## Composition
+
+Use the following composition to build a `Pagination`:
+
+```text
+Pagination
+└── PaginationContent
+    ├── PaginationItem
+    │   └── PaginationPrevious
+    ├── PaginationItem
+    │   └── PaginationLink
+    ├── PaginationItem
+    │   └── PaginationEllipsis
+    └── PaginationItem
+        └── PaginationNext
+```
+
 ## Examples
 
 ### Simple

apps/v4/content/docs/components/radix/popover.mdx

@@ -79,6 +79,16 @@ import {
 </Popover>
 ```
 
+## Composition
+
+Use the following composition to build a `Popover`:
+
+```text
+Popover
+├── PopoverTrigger
+└── PopoverContent
+```
+
 ## Examples
 
 ### Basic

apps/v4/content/docs/components/radix/radio-group.mdx

@@ -72,6 +72,16 @@ import { RadioGroup, RadioGroupItem } from "@/components/ui/radio-group"
 </RadioGroup>
 ```
 
+## Composition
+
+Use the following composition to build a `RadioGroup`:
+
+```text
+RadioGroup
+├── RadioGroupItem
+└── RadioGroupItem
+```
+
 ## Examples
 
 ### Description

apps/v4/content/docs/components/radix/resizable.mdx

@@ -78,6 +78,17 @@ import {
 </ResizablePanelGroup>
 ```
 
+## Composition
+
+Use the following composition to build a `ResizablePanelGroup`:
+
+```text
+ResizablePanelGroup
+├── ResizablePanel
+├── ResizableHandle
+└── ResizablePanel
+```
+
 ## Examples
 
 ### Vertical

apps/v4/content/docs/components/radix/scroll-area.mdx

@@ -68,6 +68,15 @@ import { ScrollArea, ScrollBar } from "@/components/ui/scroll-area"
 </ScrollArea>
 ```
 
+## Composition
+
+Use the following composition to build a `ScrollArea`:
+
+```text
+ScrollArea
+└── ScrollBar
+```
+
 ## Examples
 
 ### Horizontal

apps/v4/content/docs/components/radix/select.mdx

@@ -81,6 +81,26 @@ import {
 </Select>
 ```
 
+## Composition
+
+Use the following composition to build a `Select`:
+
+```text
+Select
+├── SelectTrigger
+│   └── SelectValue
+└── SelectContent
+    ├── SelectGroup
+    │   ├── SelectLabel
+    │   ├── SelectItem
+    │   └── SelectItem
+    ├── SelectSeparator
+    └── SelectGroup
+        ├── SelectLabel
+        ├── SelectItem
+        └── SelectItem
+```
+
 ## Examples
 
 ### Align Item With Trigger

apps/v4/content/docs/components/radix/sheet.mdx

@@ -79,6 +79,20 @@ import {
 </Sheet>
 ```
 
+## Composition
+
+Use the following composition to build a `Sheet`:
+
+```text
+Sheet
+├── SheetTrigger
+└── SheetContent
+    ├── SheetHeader
+    │   ├── SheetTitle
+    │   └── SheetDescription
+    └── SheetFooter
+```
+
 ## Examples
 
 ### Side

apps/v4/content/docs/components/radix/sidebar.mdx

@@ -55,32 +55,6 @@ npx shadcn@latest add sidebar
 
 </CodeTabs>
 
-## Structure
-
-A `Sidebar` component is composed of the following parts:
-
-- `SidebarProvider` - Handles collapsible state.
-- `Sidebar` - The sidebar container.
-- `SidebarHeader` and `SidebarFooter` - Sticky at the top and bottom of the sidebar.
-- `SidebarContent` - Scrollable content.
-- `SidebarGroup` - Section within the `SidebarContent`.
-- `SidebarTrigger` - Trigger for the `Sidebar`.
-
-<Image
-  src="/images/sidebar-structure.png"
-  width="716"
-  height="420"
-  alt="Sidebar Structure"
-  className="mt-6 w-full overflow-hidden rounded-lg border dark:hidden"
-/>
-<Image
-  src="/images/sidebar-structure-dark.png"
-  width="716"
-  height="420"
-  alt="Sidebar Structure"
-  className="mt-6 hidden w-full overflow-hidden rounded-lg border dark:block"
-/>
-
 ## Usage
 
 ```tsx showLineNumbers title="app/layout.tsx"
@@ -123,6 +97,67 @@ export function AppSidebar() {
 }
 ```
 
+## Composition
+
+Use the following composition to build a `Sidebar` layout:
+
+```text
+SidebarProvider
+├── Sidebar
+│   ├── SidebarHeader
+│   ├── SidebarContent
+│   │   ├── SidebarGroup
+│   │   │   ├── SidebarGroupLabel
+│   │   │   ├── SidebarGroupAction
+│   │   │   ├── SidebarGroupContent
+│   │   │   └── SidebarMenu
+│   │   │       ├── SidebarMenuItem
+│   │   │       │   ├── SidebarMenuButton
+│   │   │       │   ├── SidebarMenuAction
+│   │   │       │   └── SidebarMenuBadge
+│   │   │       └── SidebarMenuItem
+│   │   │           ├── SidebarMenuButton
+│   │   │           └── SidebarMenuSub
+│   │   │               ├── SidebarMenuSubItem
+│   │   │               └── SidebarMenuSubItem
+│   │   └── SidebarGroup
+│   │       └── SidebarMenu
+│   │           ├── SidebarMenuItem
+│   │           └── SidebarMenuItem
+│   ├── SidebarFooter
+│   └── SidebarRail
+├── SidebarInset
+└── SidebarTrigger
+```
+
+## Structure
+
+- **SidebarProvider** — Handles collapsible state and provides sidebar context to child components.
+- **Sidebar** — The main collapsible sidebar panel.
+- **SidebarHeader** — Sticky at the top; use for branding, titles, or workspace switchers.
+- **SidebarFooter** — Sticky at the bottom; use for user menus, settings, or actions.
+- **SidebarContent** — Scrollable region between the header and footer.
+- **SidebarGroup** — Groups related navigation with optional label, action, and content areas.
+- **SidebarMenu** / **SidebarMenuItem** — Menu structure for links, badges, actions, and nested submenus.
+- **SidebarRail** — Resize handle for adjusting sidebar width when applicable.
+- **SidebarInset** — Wraps main content when using the `inset` variant.
+- **SidebarTrigger** — Control that toggles the sidebar open or collapsed.
+
+<Image
+  src="/images/sidebar-structure.png"
+  width="716"
+  height="420"
+  alt="Sidebar Structure"
+  className="mt-6 w-full overflow-hidden rounded-lg border dark:hidden"
+/>
+<Image
+  src="/images/sidebar-structure-dark.png"
+  width="716"
+  height="420"
+  alt="Sidebar Structure"
+  className="mt-6 hidden w-full overflow-hidden rounded-lg border dark:block"
+/>
+
 ## SidebarProvider
 
 The `SidebarProvider` component is used to provide the sidebar context to the `Sidebar` component. You should always wrap your application in a `SidebarProvider` component.

apps/v4/content/docs/components/radix/table.mdx

@@ -83,6 +83,33 @@ import {
 </Table>
 ```
 
+## Composition
+
+Use the following composition to build a `Table`:
+
+```text
+Table
+├── TableCaption
+├── TableHeader
+│   └── TableRow
+│       ├── TableHead
+│       ├── TableHead
+│       ├── TableHead
+│       └── TableHead
+├── TableBody
+│   ├── TableRow
+│   │   ├── TableCell
+│   │   ├── TableCell
+│   │   ├── TableCell
+│   │   └── TableCell
+│   └── TableRow
+│       ├── TableCell
+│       ├── TableCell
+│       ├── TableCell
+│       └── TableCell
+└── TableFooter
+```
+
 ## Examples
 
 ### Footer

apps/v4/content/docs/components/radix/tabs.mdx

@@ -73,6 +73,19 @@ import { Tabs, TabsContent, TabsList, TabsTrigger } from "@/components/ui/tabs"
 </Tabs>
 ```
 
+## Composition
+
+Use the following composition to build `Tabs`:
+
+```text
+Tabs
+├── TabsList
+│   ├── TabsTrigger
+│   └── TabsTrigger
+├── TabsContent
+└── TabsContent
+```
+
 ## Examples
 
 ### Line

apps/v4/content/docs/components/radix/toggle-group.mdx

@@ -66,6 +66,16 @@ import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group"
 </ToggleGroup>
 ```
 
+## Composition
+
+Use the following composition to build a `ToggleGroup`:
+
+```text
+ToggleGroup
+├── ToggleGroupItem
+└── ToggleGroupItem
+```
+
 ## Examples
 
 ### Outline

apps/v4/content/docs/components/radix/tooltip.mdx

@@ -109,6 +109,16 @@ import {
 </Tooltip>
 ```
 
+## Composition
+
+Use the following composition to build a `Tooltip`:
+
+```text
+Tooltip
+├── TooltipTrigger
+└── TooltipContent
+```
+
 ## Examples
 
 ### Side

apps/v4/content/docs/installation/manual.mdx

@@ -19,9 +19,11 @@ Add the following dependencies to your project:
 npm install shadcn class-variance-authority clsx tailwind-merge lucide-react tw-animate-css
 ```
 
-### Configure path aliases
+### Configure import aliases
 
-Configure the path aliases in your `tsconfig.json` file.
+Choose one of the following alias setups.
+
+#### Option A: `tsconfig.json` paths
 
 ```json {3-6} title="tsconfig.json" showLineNumbers
 {
@@ -34,7 +36,31 @@ Configure the path aliases in your `tsconfig.json` file.
 }
 ```
 
-The `@` alias is a preference. You can use other aliases if you want.
+#### Option B: `package.json#imports`
+
+```json title="package.json" showLineNumbers
+{
+  "imports": {
+    "#components/*": "./src/components/*",
+    "#lib/*": "./src/lib/*",
+    "#hooks/*": "./src/hooks/*"
+  }
+}
+```
+
+```json title="tsconfig.json" showLineNumbers
+{
+  "compilerOptions": {
+    "moduleResolution": "bundler",
+    "resolvePackageJsonImports": true
+  }
+}
+```
+
+The `@` alias is a preference. You can use other aliases if you want. If you
+use `package.json#imports`, keep the matching alias roots in `components.json`.
+See the <Link href="/docs/components-json">components.json docs</Link> for the
+matching aliases and package imports behavior.
 
 ### Configure styles
 
@@ -211,6 +237,20 @@ Create a `components.json` file in the root of your project.
 }
 ```
 
+If you're using `package.json#imports`, use the corresponding `#...` aliases instead:
+
+```json title="components.json" showLineNumbers
+{
+  "aliases": {
+    "components": "#components",
+    "utils": "#lib/utils",
+    "ui": "#components/ui",
+    "lib": "#lib",
+    "hooks": "#hooks"
+  }
+}
+```
+
 ### That's it
 
 You can now start adding components to your project.

apps/v4/examples/base/button-render.tsx

@@ -1,5 +1,3 @@
-"use client"
-
 import { buttonVariants } from "@/styles/base-nova/ui/button"
 
 export default function ButtonRender() {

apps/v4/package.json

@@ -22,7 +22,7 @@
     "postinstall": "fumadocs-mdx"
   },
   "dependencies": {
-    "@base-ui/react": "1.1.0",
+    "@base-ui/react": "1.3.0",
     "@dnd-kit/core": "^6.3.1",
     "@dnd-kit/modifiers": "^9.0.0",
     "@dnd-kit/sortable": "^10.0.0",
@@ -76,7 +76,7 @@
     "rehype-pretty-code": "^0.14.1",
     "rimraf": "^6.0.1",
     "server-only": "^0.0.1",
-    "shadcn": "4.1.2",
+    "shadcn": "4.2.0",
     "shiki": "^1.10.1",
     "sonner": "^2.0.0",
     "swr": "^2.3.6",

apps/v4/public/r/registries.json

@@ -239,6 +239,12 @@
     "url": "https://formcn.dev/r/{name}.json",
     "description": "Build production-ready forms with a few clicks using shadcn components and modern tools."
   },
+  {
+    "name": "@flightcn",
+    "homepage": "https://flightcn.yencheng.dev",
+    "url": "https://flightcn.yencheng.dev/r/{name}.json",
+    "description": "Flight routes on interactive maps with great-circle arcs, airport markers, multi-leg journeys, and optional animation, built for mapcn."
+  },
   {
     "name": "@gaia",
     "homepage": "https://ui.heygaia.io",
@@ -647,6 +653,12 @@
     "url": "https://shadcncraft.com/r/{name}.json",
     "description": "A starter collection of polished shadcn/ui components and blocks built to production standards. Part of a larger Figma + React system designed to scale with your product."
   },
+  {
+    "name": "@shark",
+    "homepage": "https://shark.vini.one",
+    "url": "https://shark.vini.one/r/{name}.json",
+    "description": "shadcn/ui-style components built on Ark UI."
+  },
   {
     "name": "@smoothui",
     "homepage": "https://smoothui.dev",
@@ -1000,5 +1012,17 @@
     "homepage": "https://www.openpolicy.sh",
     "url": "https://www.openpolicy.sh/r/{name}.json",
     "description": "Open-source components for building terms, privacy policies and cookie banners."
+  },
+  {
+    "name": "@mksingh",
+    "homepage": "https://mksingh.dev/docs",
+    "url": "https://mksingh.dev/r/{name}.json",
+    "description": "A personal registry of production-ready ShadCN components and utilities. Everything is built to drop into your existing ShadCN project with no extra setup."
+  },
+  {
+    "name": "@flowkit-ui",
+    "homepage": "https://flowkit-ui.vzkiss.com",
+    "url": "https://flowkit-ui.vzkiss.com/r/{name}.json",
+    "description": "Opinionated, accessible components on Base UI and shadcn-style primitives — starting with a Creatable Combobox."
   }
 ]

apps/v4/public/r/styles/base-luma/accordion.json

@@ -4,7 +4,7 @@
   "files": [
     {
       "path": "registry/base-luma/ui/accordion.tsx",
-      "content": "\"use client\"\n\nimport { Accordion as AccordionPrimitive } from \"@base-ui/react/accordion\"\n\nimport { cn } from \"@/registry/base-luma/lib/utils\"\nimport { IconPlaceholder } from \"@/app/(create)/components/icon-placeholder\"\n\nfunction Accordion({ className, ...props }: AccordionPrimitive.Root.Props) {\n  return (\n    <AccordionPrimitive.Root\n      data-slot=\"accordion\"\n      className={cn(\n        \"flex w-full flex-col overflow-hidden rounded-2xl border\",\n        className\n      )}\n      {...props}\n    />\n  )\n}\n\nfunction AccordionItem({ className, ...props }: AccordionPrimitive.Item.Props) {\n  return (\n    <AccordionPrimitive.Item\n      data-slot=\"accordion-item\"\n      className={cn(\"not-last:border-b data-open:bg-muted/50\", className)}\n      {...props}\n    />\n  )\n}\n\nfunction AccordionTrigger({\n  className,\n  children,\n  ...props\n}: AccordionPrimitive.Trigger.Props) {\n  return (\n    <AccordionPrimitive.Header className=\"flex\">\n      <AccordionPrimitive.Trigger\n        data-slot=\"accordion-trigger\"\n        className={cn(\n          \"group/accordion-trigger relative flex flex-1 items-start justify-between gap-6 border border-transparent p-4 text-left text-sm font-medium transition-all outline-none hover:underline aria-disabled:pointer-events-none aria-disabled:opacity-50 **:data-[slot=accordion-trigger-icon]:ml-auto **:data-[slot=accordion-trigger-icon]:size-4 **:data-[slot=accordion-trigger-icon]:text-muted-foreground\",\n          className\n        )}\n        {...props}\n      >\n        {children}\n        <IconPlaceholder\n          lucide=\"ChevronDownIcon\"\n          tabler=\"IconChevronDown\"\n          data-slot=\"accordion-trigger-icon\"\n          hugeicons=\"ArrowDown01Icon\"\n          phosphor=\"CaretDownIcon\"\n          remixicon=\"RiArrowDownSLine\"\n          className=\"pointer-events-none shrink-0 group-aria-expanded/accordion-trigger:hidden\"\n        />\n        <IconPlaceholder\n          lucide=\"ChevronUpIcon\"\n          tabler=\"IconChevronUp\"\n          data-slot=\"accordion-trigger-icon\"\n          hugeicons=\"ArrowUp01Icon\"\n          phosphor=\"CaretUpIcon\"\n          remixicon=\"RiArrowUpSLine\"\n          className=\"pointer-events-none hidden shrink-0 group-aria-expanded/accordion-trigger:inline\"\n        />\n      </AccordionPrimitive.Trigger>\n    </AccordionPrimitive.Header>\n  )\n}\n\nfunction AccordionContent({\n  className,\n  children,\n  ...props\n}: AccordionPrimitive.Panel.Props) {\n  return (\n    <AccordionPrimitive.Panel\n      data-slot=\"accordion-content\"\n      className=\"overflow-hidden px-4 text-sm data-open:animate-accordion-down data-closed:animate-accordion-up\"\n      {...props}\n    >\n      <div\n        className={cn(\n          \"h-(--accordion-panel-height) pt-0 pb-4 data-ending-style:h-0 data-starting-style:h-0 [&_a]:underline [&_a]:underline-offset-3 [&_a]:hover:text-foreground [&_p:not(:last-child)]:mb-4\",\n          className\n        )}\n      >\n        {children}\n      </div>\n    </AccordionPrimitive.Panel>\n  )\n}\n\nexport { Accordion, AccordionItem, AccordionTrigger, AccordionContent }\n",
+      "content": "import { Accordion as AccordionPrimitive } from \"@base-ui/react/accordion\"\n\nimport { cn } from \"@/registry/base-luma/lib/utils\"\nimport { IconPlaceholder } from \"@/app/(create)/components/icon-placeholder\"\n\nfunction Accordion({ className, ...props }: AccordionPrimitive.Root.Props) {\n  return (\n    <AccordionPrimitive.Root\n      data-slot=\"accordion\"\n      className={cn(\n        \"flex w-full flex-col overflow-hidden rounded-2xl border\",\n        className\n      )}\n      {...props}\n    />\n  )\n}\n\nfunction AccordionItem({ className, ...props }: AccordionPrimitive.Item.Props) {\n  return (\n    <AccordionPrimitive.Item\n      data-slot=\"accordion-item\"\n      className={cn(\"not-last:border-b data-open:bg-muted/50\", className)}\n      {...props}\n    />\n  )\n}\n\nfunction AccordionTrigger({\n  className,\n  children,\n  ...props\n}: AccordionPrimitive.Trigger.Props) {\n  return (\n    <AccordionPrimitive.Header className=\"flex\">\n      <AccordionPrimitive.Trigger\n        data-slot=\"accordion-trigger\"\n        className={cn(\n          \"group/accordion-trigger relative flex flex-1 items-start justify-between gap-6 border border-transparent p-4 text-left text-sm font-medium transition-all outline-none hover:underline aria-disabled:pointer-events-none aria-disabled:opacity-50 **:data-[slot=accordion-trigger-icon]:ml-auto **:data-[slot=accordion-trigger-icon]:size-4 **:data-[slot=accordion-trigger-icon]:text-muted-foreground\",\n          className\n        )}\n        {...props}\n      >\n        {children}\n        <IconPlaceholder\n          lucide=\"ChevronDownIcon\"\n          tabler=\"IconChevronDown\"\n          data-slot=\"accordion-trigger-icon\"\n          hugeicons=\"ArrowDown01Icon\"\n          phosphor=\"CaretDownIcon\"\n          remixicon=\"RiArrowDownSLine\"\n          className=\"pointer-events-none shrink-0 group-aria-expanded/accordion-trigger:hidden\"\n        />\n        <IconPlaceholder\n          lucide=\"ChevronUpIcon\"\n          tabler=\"IconChevronUp\"\n          data-slot=\"accordion-trigger-icon\"\n          hugeicons=\"ArrowUp01Icon\"\n          phosphor=\"CaretUpIcon\"\n          remixicon=\"RiArrowUpSLine\"\n          className=\"pointer-events-none hidden shrink-0 group-aria-expanded/accordion-trigger:inline\"\n        />\n      </AccordionPrimitive.Trigger>\n    </AccordionPrimitive.Header>\n  )\n}\n\nfunction AccordionContent({\n  className,\n  children,\n  ...props\n}: AccordionPrimitive.Panel.Props) {\n  return (\n    <AccordionPrimitive.Panel\n      data-slot=\"accordion-content\"\n      className=\"overflow-hidden px-4 text-sm data-open:animate-accordion-down data-closed:animate-accordion-up\"\n      {...props}\n    >\n      <div\n        className={cn(\n          \"h-(--accordion-panel-height) pt-0 pb-4 data-ending-style:h-0 data-starting-style:h-0 [&_a]:underline [&_a]:underline-offset-3 [&_a]:hover:text-foreground [&_p:not(:last-child)]:mb-4\",\n          className\n        )}\n      >\n        {children}\n      </div>\n    </AccordionPrimitive.Panel>\n  )\n}\n\nexport { Accordion, AccordionItem, AccordionTrigger, AccordionContent }\n",
       "type": "registry:ui"
     }
   ],

apps/v4/public/r/styles/base-luma/button.json

@@ -4,7 +4,7 @@
   "files": [
     {
       "path": "registry/base-luma/ui/button.tsx",
-      "content": "\"use client\"\n\nimport { Button as ButtonPrimitive } from \"@base-ui/react/button\"\nimport { cva, type VariantProps } from \"class-variance-authority\"\n\nimport { cn } from \"@/registry/base-luma/lib/utils\"\n\nconst buttonVariants = cva(\n  \"group/button inline-flex shrink-0 items-center justify-center rounded-4xl border border-transparent bg-clip-padding text-sm font-medium whitespace-nowrap transition-all outline-none select-none focus-visible:border-ring focus-visible:ring-3 focus-visible:ring-ring/30 active:not-aria-[haspopup]:translate-y-px disabled:pointer-events-none disabled:opacity-50 aria-invalid:border-destructive aria-invalid:ring-3 aria-invalid:ring-destructive/20 dark:aria-invalid:border-destructive/50 dark:aria-invalid:ring-destructive/40 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4\",\n  {\n    variants: {\n      variant: {\n        default: \"bg-primary text-primary-foreground hover:bg-primary/80\",\n        outline:\n          \"border-border bg-background hover:bg-muted hover:text-foreground aria-expanded:bg-muted aria-expanded:text-foreground dark:bg-transparent dark:hover:bg-input/30\",\n        secondary:\n          \"bg-secondary text-secondary-foreground hover:bg-secondary/80 aria-expanded:bg-secondary aria-expanded:text-secondary-foreground\",\n        ghost:\n          \"hover:bg-muted hover:text-foreground aria-expanded:bg-muted aria-expanded:text-foreground dark:hover:bg-muted/50\",\n        destructive:\n          \"bg-destructive/10 text-destructive hover:bg-destructive/20 focus-visible:border-destructive/40 focus-visible:ring-destructive/20 dark:bg-destructive/20 dark:hover:bg-destructive/30 dark:focus-visible:ring-destructive/40\",\n        link: \"text-primary underline-offset-4 hover:underline\",\n      },\n      size: {\n        default:\n          \"h-9 gap-1.5 px-3 has-data-[icon=inline-end]:pr-2.5 has-data-[icon=inline-start]:pl-2.5\",\n        xs: \"h-6 gap-1 px-2.5 text-xs has-data-[icon=inline-end]:pr-2 has-data-[icon=inline-start]:pl-2 [&_svg:not([class*='size-'])]:size-3\",\n        sm: \"h-8 gap-1 px-3 has-data-[icon=inline-end]:pr-2 has-data-[icon=inline-start]:pl-2\",\n        lg: \"h-10 gap-1.5 px-4 has-data-[icon=inline-end]:pr-3 has-data-[icon=inline-start]:pl-3\",\n        icon: \"size-9\",\n        \"icon-xs\": \"size-6 [&_svg:not([class*='size-'])]:size-3\",\n        \"icon-sm\": \"size-8\",\n        \"icon-lg\": \"size-10\",\n      },\n    },\n    defaultVariants: {\n      variant: \"default\",\n      size: \"default\",\n    },\n  }\n)\n\nfunction Button({\n  className,\n  variant = \"default\",\n  size = \"default\",\n  ...props\n}: ButtonPrimitive.Props & VariantProps<typeof buttonVariants>) {\n  return (\n    <ButtonPrimitive\n      data-slot=\"button\"\n      className={cn(buttonVariants({ variant, size, className }))}\n      {...props}\n    />\n  )\n}\n\nexport { Button, buttonVariants }\n",
+      "content": "import { Button as ButtonPrimitive } from \"@base-ui/react/button\"\nimport { cva, type VariantProps } from \"class-variance-authority\"\n\nimport { cn } from \"@/registry/base-luma/lib/utils\"\n\nconst buttonVariants = cva(\n  \"group/button inline-flex shrink-0 items-center justify-center rounded-4xl border border-transparent bg-clip-padding text-sm font-medium whitespace-nowrap transition-all outline-none select-none focus-visible:border-ring focus-visible:ring-3 focus-visible:ring-ring/30 active:not-aria-[haspopup]:translate-y-px disabled:pointer-events-none disabled:opacity-50 aria-invalid:border-destructive aria-invalid:ring-3 aria-invalid:ring-destructive/20 dark:aria-invalid:border-destructive/50 dark:aria-invalid:ring-destructive/40 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4\",\n  {\n    variants: {\n      variant: {\n        default: \"bg-primary text-primary-foreground hover:bg-primary/80\",\n        outline:\n          \"border-border bg-background hover:bg-muted hover:text-foreground aria-expanded:bg-muted aria-expanded:text-foreground dark:bg-transparent dark:hover:bg-input/30\",\n        secondary:\n          \"bg-secondary text-secondary-foreground hover:bg-secondary/80 aria-expanded:bg-secondary aria-expanded:text-secondary-foreground\",\n        ghost:\n          \"hover:bg-muted hover:text-foreground aria-expanded:bg-muted aria-expanded:text-foreground dark:hover:bg-muted/50\",\n        destructive:\n          \"bg-destructive/10 text-destructive hover:bg-destructive/20 focus-visible:border-destructive/40 focus-visible:ring-destructive/20 dark:bg-destructive/20 dark:hover:bg-destructive/30 dark:focus-visible:ring-destructive/40\",\n        link: \"text-primary underline-offset-4 hover:underline\",\n      },\n      size: {\n        default:\n          \"h-9 gap-1.5 px-3 has-data-[icon=inline-end]:pr-2.5 has-data-[icon=inline-start]:pl-2.5\",\n        xs: \"h-6 gap-1 px-2.5 text-xs has-data-[icon=inline-end]:pr-2 has-data-[icon=inline-start]:pl-2 [&_svg:not([class*='size-'])]:size-3\",\n        sm: \"h-8 gap-1 px-3 has-data-[icon=inline-end]:pr-2 has-data-[icon=inline-start]:pl-2\",\n        lg: \"h-10 gap-1.5 px-4 has-data-[icon=inline-end]:pr-3 has-data-[icon=inline-start]:pl-3\",\n        icon: \"size-9\",\n        \"icon-xs\": \"size-6 [&_svg:not([class*='size-'])]:size-3\",\n        \"icon-sm\": \"size-8\",\n        \"icon-lg\": \"size-10\",\n      },\n    },\n    defaultVariants: {\n      variant: \"default\",\n      size: \"default\",\n    },\n  }\n)\n\nfunction Button({\n  className,\n  variant = \"default\",\n  size = \"default\",\n  ...props\n}: ButtonPrimitive.Props & VariantProps<typeof buttonVariants>) {\n  return (\n    <ButtonPrimitive\n      data-slot=\"button\"\n      className={cn(buttonVariants({ variant, size, className }))}\n      {...props}\n    />\n  )\n}\n\nexport { Button, buttonVariants }\n",
       "type": "registry:ui"
     }
   ],