From 2b6675ba01a9753496077a0bf5e1d1f034a9b820 Mon Sep 17 00:00:00 2001
From: junwen-k <40173716+junwen-k@users.noreply.github.com>
Date: Sun, 19 Jul 2026 02:26:47 +0800
Subject: [PATCH 1/9] fix: address audit findings from the Base UI rebuild
 review

Fixes surfaced by a full component/docs audit ahead of the next -> main
merge: broken installation links, leftover Tailwind styling in an
unstyled primitive demo, the virtualizer/virtualized naming mismatch
across demos and docs, a stale changelog section on the timeline page,
nova styling drift in dropzone and phone-input, a dead null-check in
useVirtualized(), missing Accessibility sections on confirmer and
wheel-picker docs, and a registry:validate script for local registry
checks.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 .../content/docs/utilities/{virtualizer.mdx => virtualized.mdx}   | 0
 .../{virtualizer-combobox.tsx => virtualized-combobox.tsx}        | 0
 .../examples/{virtualizer-command.tsx => virtualized-command.tsx} | 0
 .../examples/{virtualizer-demo.tsx => virtualized-demo.tsx}       | 0
 .../examples/{virtualizer-grid.tsx => virtualized-grid.tsx}       | 0
 .../{virtualizer-horizontal.tsx => virtualized-horizontal.tsx}    | 0
 .../{virtualizer-scroll-area.tsx => virtualized-scroll-area.tsx}  | 0
 .../examples/{virtualizer-select.tsx => virtualized-select.tsx}   | 0
 .../{virtualizer-sortable.tsx => virtualized-sortable.tsx}        | 0
 .../examples/{virtualizer-table.tsx => virtualized-table.tsx}     | 0
 10 files changed, 0 insertions(+), 0 deletions(-)
 rename apps/v4/content/docs/utilities/{virtualizer.mdx => virtualized.mdx} (100%)
 rename apps/v4/src/components/examples/{virtualizer-combobox.tsx => virtualized-combobox.tsx} (100%)
 rename apps/v4/src/components/examples/{virtualizer-command.tsx => virtualized-command.tsx} (100%)
 rename apps/v4/src/components/examples/{virtualizer-demo.tsx => virtualized-demo.tsx} (100%)
 rename apps/v4/src/components/examples/{virtualizer-grid.tsx => virtualized-grid.tsx} (100%)
 rename apps/v4/src/components/examples/{virtualizer-horizontal.tsx => virtualized-horizontal.tsx} (100%)
 rename apps/v4/src/components/examples/{virtualizer-scroll-area.tsx => virtualized-scroll-area.tsx} (100%)
 rename apps/v4/src/components/examples/{virtualizer-select.tsx => virtualized-select.tsx} (100%)
 rename apps/v4/src/components/examples/{virtualizer-sortable.tsx => virtualized-sortable.tsx} (100%)
 rename apps/v4/src/components/examples/{virtualizer-table.tsx => virtualized-table.tsx} (100%)

diff --git a/apps/v4/content/docs/utilities/virtualizer.mdx b/apps/v4/content/docs/utilities/virtualized.mdx
similarity index 100%
rename from apps/v4/content/docs/utilities/virtualizer.mdx
rename to apps/v4/content/docs/utilities/virtualized.mdx
diff --git a/apps/v4/src/components/examples/virtualizer-combobox.tsx b/apps/v4/src/components/examples/virtualized-combobox.tsx
similarity index 100%
rename from apps/v4/src/components/examples/virtualizer-combobox.tsx
rename to apps/v4/src/components/examples/virtualized-combobox.tsx
diff --git a/apps/v4/src/components/examples/virtualizer-command.tsx b/apps/v4/src/components/examples/virtualized-command.tsx
similarity index 100%
rename from apps/v4/src/components/examples/virtualizer-command.tsx
rename to apps/v4/src/components/examples/virtualized-command.tsx
diff --git a/apps/v4/src/components/examples/virtualizer-demo.tsx b/apps/v4/src/components/examples/virtualized-demo.tsx
similarity index 100%
rename from apps/v4/src/components/examples/virtualizer-demo.tsx
rename to apps/v4/src/components/examples/virtualized-demo.tsx
diff --git a/apps/v4/src/components/examples/virtualizer-grid.tsx b/apps/v4/src/components/examples/virtualized-grid.tsx
similarity index 100%
rename from apps/v4/src/components/examples/virtualizer-grid.tsx
rename to apps/v4/src/components/examples/virtualized-grid.tsx
diff --git a/apps/v4/src/components/examples/virtualizer-horizontal.tsx b/apps/v4/src/components/examples/virtualized-horizontal.tsx
similarity index 100%
rename from apps/v4/src/components/examples/virtualizer-horizontal.tsx
rename to apps/v4/src/components/examples/virtualized-horizontal.tsx
diff --git a/apps/v4/src/components/examples/virtualizer-scroll-area.tsx b/apps/v4/src/components/examples/virtualized-scroll-area.tsx
similarity index 100%
rename from apps/v4/src/components/examples/virtualizer-scroll-area.tsx
rename to apps/v4/src/components/examples/virtualized-scroll-area.tsx
diff --git a/apps/v4/src/components/examples/virtualizer-select.tsx b/apps/v4/src/components/examples/virtualized-select.tsx
similarity index 100%
rename from apps/v4/src/components/examples/virtualizer-select.tsx
rename to apps/v4/src/components/examples/virtualized-select.tsx
diff --git a/apps/v4/src/components/examples/virtualizer-sortable.tsx b/apps/v4/src/components/examples/virtualized-sortable.tsx
similarity index 100%
rename from apps/v4/src/components/examples/virtualizer-sortable.tsx
rename to apps/v4/src/components/examples/virtualized-sortable.tsx
diff --git a/apps/v4/src/components/examples/virtualizer-table.tsx b/apps/v4/src/components/examples/virtualized-table.tsx
similarity index 100%
rename from apps/v4/src/components/examples/virtualizer-table.tsx
rename to apps/v4/src/components/examples/virtualized-table.tsx

From e06735073cba855594a648cfdedb40ee5d29f930 Mon Sep 17 00:00:00 2001
From: junwen-k <40173716+junwen-k@users.noreply.github.com>
Date: Sun, 19 Jul 2026 02:27:18 +0800
Subject: [PATCH 2/9] fix: finish staging audit-fix content changes

The previous commit picked up only the virtualizer->virtualized file
renames; the accompanying content edits (naming, docs, styling, and
the registry:validate script) were left unstaged by a lint-staged
stash/restore hiccup. This commit lands that content.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 apps/v4/content/docs/changelog.mdx            |  4 +--
 apps/v4/content/docs/components/confirmer.mdx |  8 ++++-
 .../docs/components/date-time-field.mdx       |  2 +-
 apps/v4/content/docs/components/dropzone.mdx  |  2 +-
 .../docs/components/password-input.mdx        |  2 +-
 .../content/docs/components/phone-input.mdx   |  2 +-
 apps/v4/content/docs/components/timeline.mdx  | 35 ------------------
 .../content/docs/components/wheel-picker.mdx  |  6 ++++
 apps/v4/content/docs/installation.mdx         |  2 +-
 apps/v4/content/docs/utilities/meta.json      |  2 +-
 apps/v4/content/docs/utilities/sortable.mdx   |  2 +-
 .../v4/content/docs/utilities/virtualized.mdx | 36 +++++++++++--------
 apps/v4/package.json                          |  1 +
 ...hone-input-primitive-preferred-country.tsx | 26 ++++++--------
 .../examples/virtualized-combobox.tsx         |  2 +-
 .../examples/virtualized-command.tsx          |  2 +-
 .../components/examples/virtualized-demo.tsx  |  2 +-
 .../components/examples/virtualized-grid.tsx  |  2 +-
 .../examples/virtualized-horizontal.tsx       |  2 +-
 .../examples/virtualized-scroll-area.tsx      |  2 +-
 .../examples/virtualized-select.tsx           |  2 +-
 .../examples/virtualized-sortable.tsx         |  2 +-
 .../components/examples/virtualized-table.tsx |  2 +-
 apps/v4/src/registry/new-york/ui/dropzone.tsx |  2 +-
 .../src/registry/new-york/ui/phone-input.tsx  |  4 +--
 .../src/registry/new-york/ui/virtualized.tsx  |  6 +---
 26 files changed, 68 insertions(+), 92 deletions(-)

diff --git a/apps/v4/content/docs/changelog.mdx b/apps/v4/content/docs/changelog.mdx
index 61274cf..c7045eb 100644
--- a/apps/v4/content/docs/changelog.mdx
+++ b/apps/v4/content/docs/changelog.mdx
@@ -69,9 +69,9 @@ We've added a new Virtualizer documentation page.
 
 Learn how to use the `virtua` library to efficiently render large lists and grids by virtualizing your components. This documentation provides practical examples and guidance on integrating `virtua` with your existing components.
 
-<ComponentPreview name="virtualizer-demo" />
+<ComponentPreview name="virtualized-demo" />
 
-[Read the docs](/docs/utilities/virtualizer)
+[Read the docs](/docs/utilities/virtualized)
 
 ## February 2025 - Sortable and Control Group
 
diff --git a/apps/v4/content/docs/components/confirmer.mdx b/apps/v4/content/docs/components/confirmer.mdx
index 4050218..07507da 100644
--- a/apps/v4/content/docs/components/confirmer.mdx
+++ b/apps/v4/content/docs/components/confirmer.mdx
@@ -71,7 +71,7 @@ Add the `<AlertDialog />` and `<Button />` component to your project.
 
 The `<Confirmer />` component uses `<AlertDialog />` and `<Button />` components. Make sure you have it installed in your project.
 
-See installation instructions for the [AlertDialog](/docs/components/alert-dialog#installation) and the [Button](/docs/components/button#installation) components.
+See installation instructions for the [AlertDialog](https://ui.shadcn.com/docs/components/alert-dialog) and the [Button](https://ui.shadcn.com/docs/components/button) components.
 
 <Step>Copy and paste the following code into your project.</Step>
 
@@ -127,6 +127,12 @@ confirm({
 
 <ComponentPreview name="confirmer-demo" />
 
+## Accessibility
+
+`<Confirmer />` renders an `<AlertDialog />`, so it inherits Base UI's alert dialog semantics: the dialog traps focus while open, labels itself from `<AlertDialogTitle>` and `<AlertDialogDescription>` (the `title` and `description` options), and returns focus to the triggering element when it closes.
+
+Pressing <Kbd>Escape</Kbd> or activating the cancel button resolves `confirm()` with `false`, mirroring a dismissed dialog. Always pass a `title` (and a `description` for anything non-obvious) so screen reader users hear what they're confirming, and set `ActionProps={{ variant: "destructive" }}` rather than color alone to distinguish destructive actions.
+
 ## API Reference
 
 ### Confirmer
diff --git a/apps/v4/content/docs/components/date-time-field.mdx b/apps/v4/content/docs/components/date-time-field.mdx
index 867d44c..5667e7c 100644
--- a/apps/v4/content/docs/components/date-time-field.mdx
+++ b/apps/v4/content/docs/components/date-time-field.mdx
@@ -36,7 +36,7 @@ Add `<DateTimeFieldPrimitive />` and `<InputGroup />` component to your project.
 
 The `<DateTimeField />` component uses `<DateTimeFieldPrimitive />` and `<InputGroup />` components. Make sure you have it installed in your project.
 
-See installation instructions for the [DateTimeFieldPrimitive](/docs/components/date-time-field-primitive#installation) and [Input Group](https://ui.shadcn.com/docs/components/input-group) components.
+See installation instructions for the [DateTimeFieldPrimitive](/docs/primitives/date-time-field#installation) and [Input Group](https://ui.shadcn.com/docs/components/input-group) components.
 
 <Step>Copy and paste the following code into your project.</Step>
 
diff --git a/apps/v4/content/docs/components/dropzone.mdx b/apps/v4/content/docs/components/dropzone.mdx
index 76ba611..2802a3a 100644
--- a/apps/v4/content/docs/components/dropzone.mdx
+++ b/apps/v4/content/docs/components/dropzone.mdx
@@ -45,7 +45,7 @@ Add the `<DropzonePrimitive />` component to your project.
 
 The `<Dropzone />` component uses `<DropzonePrimitive />` component. Make sure you have it installed in your project.
 
-See installation instructions for the [DropzonePrimitive](/docs/components/dropzone-primitive#installation) component.
+See installation instructions for the [DropzonePrimitive](/docs/primitives/dropzone#installation) component.
 
 <Step>Copy and paste the following code into your project.</Step>
 
diff --git a/apps/v4/content/docs/components/password-input.mdx b/apps/v4/content/docs/components/password-input.mdx
index 8fef432..056e2cc 100644
--- a/apps/v4/content/docs/components/password-input.mdx
+++ b/apps/v4/content/docs/components/password-input.mdx
@@ -35,7 +35,7 @@ Add `<InputGroup />` and `<PasswordInputPrimitive />` component to your project.
 
 The `<PasswordInput />` component uses `<InputGroup />` and `<PasswordInputPrimitive />` components. Make sure you have it installed in your project.
 
-See installation instructions for the [Input Group](https://ui.shadcn.com/docs/components/input-group) and [PasswordInputPrimitive](/docs/components/password-input-primitive#installation) components.
+See installation instructions for the [Input Group](https://ui.shadcn.com/docs/components/input-group) and [PasswordInputPrimitive](/docs/primitives/password-input#installation) components.
 
 <Step>Copy and paste the following code into your project.</Step>
 
diff --git a/apps/v4/content/docs/components/phone-input.mdx b/apps/v4/content/docs/components/phone-input.mdx
index d22e6c4..a1f5301 100644
--- a/apps/v4/content/docs/components/phone-input.mdx
+++ b/apps/v4/content/docs/components/phone-input.mdx
@@ -41,7 +41,7 @@ Add the `<PhoneInputPrimitive />`, `<Input />` and `<Select />` component to you
 
 The `<PhoneInput />` component uses `<PhoneInputPrimitive />`, `<Input />` and `<Select />` components. Make sure you have it installed in your project.
 
-See installation instructions for the [PhoneInputPrimitive](/docs/primitives/phone-input#installation), [Input](/docs/primitives/input#installation) and [Select](/docs/primitives/select#installation) components.
+See installation instructions for the [PhoneInputPrimitive](/docs/primitives/phone-input#installation), [Input](https://ui.shadcn.com/docs/components/input) and [Select](https://ui.shadcn.com/docs/components/select) components.
 
 <Step>Copy and paste the following code into your project.</Step>
 
diff --git a/apps/v4/content/docs/components/timeline.mdx b/apps/v4/content/docs/components/timeline.mdx
index 961b470..51cd479 100644
--- a/apps/v4/content/docs/components/timeline.mdx
+++ b/apps/v4/content/docs/components/timeline.mdx
@@ -182,38 +182,3 @@ The event's content, heading text and supporting text. Each renders a `<div>` an
 ### useTimeline
 
 Hook exposing the timeline context (`orientation`) for building custom parts. Must be used within `<Timeline />`.
-
-## Changelog
-
-### 10 Febuary 2025 - a11y for title and description
-
-- Changed the `TimelineTitle` and `TimelineDescription` components to use `div` instead of `h3` and `p` to improve accessibility.
-
-```tsx showLineNumbers title="timeline.tsx"
-export const TimelineTitle = React.forwardRef<
-  React.ElementRef<"div">,
-  React.ComponentPropsWithoutRef<"div">
->((props, ref) => {
-  const { orientation } = useTimeline();
-
-  return <div ref={ref} data-orientation={orientation} {...props} />;
-});
-TimelineTitle.displayName = "TimelineTitle";
-
-export const TimelineDescription = React.forwardRef<
-  React.ElementRef<"div">,
-  React.ComponentPropsWithoutRef<"div">
->(({ className, ...props }, ref) => {
-  const { orientation } = useTimeline();
-
-  return (
-    <div
-      ref={ref}
-      data-orientation={orientation}
-      className={cn("text-muted-foreground text-sm", className)}
-      {...props}
-    />
-  );
-});
-TimelineDescription.displayName = "TimelineDescription";
-```
diff --git a/apps/v4/content/docs/components/wheel-picker.mdx b/apps/v4/content/docs/components/wheel-picker.mdx
index eb2ab52..440656e 100644
--- a/apps/v4/content/docs/components/wheel-picker.mdx
+++ b/apps/v4/content/docs/components/wheel-picker.mdx
@@ -66,6 +66,12 @@ import { WheelPicker, WheelPickerWrapper } from "@/components/ui/wheel-picker";
 
 <ComponentPreview name="wheel-picker-form" />
 
+## Accessibility
+
+Each `<WheelPicker />` column is keyboard-operable: focus it and use <Kbd>Up</Kbd>/<Kbd>Down</Kbd> (or <Kbd>Left</Kbd>/<Kbd>Right</Kbd> when laid out horizontally) to move one option at a time, matching the pointer/touch scroll behavior. See react-wheel-picker's [accessibility notes](https://react-wheel-picker.chanhdai.com/docs#api-reference) for the full set of keyboard and ARIA behavior it provides.
+
+Give each `<WheelPicker />` an accessible name (e.g. wrap it with a `<label>` or pass `aria-label`) when a column's purpose isn't obvious from surrounding text, such as separate hour/minute columns in a time picker.
+
 ## API Reference
 
 Styled wrappers around [react-wheel-picker](https://react-wheel-picker.chanhdai.com/) — see its [API reference](https://react-wheel-picker.chanhdai.com/docs#api-reference) for the underlying props.
diff --git a/apps/v4/content/docs/installation.mdx b/apps/v4/content/docs/installation.mdx
index f7d1d32..d2db13c 100644
--- a/apps/v4/content/docs/installation.mdx
+++ b/apps/v4/content/docs/installation.mdx
@@ -22,4 +22,4 @@ Each component's documentation page includes its exact install command, along wi
 
 ## Utilities
 
-Utility docs such as [Sortable](/docs/utilities/sortable) and [Virtualizer](/docs/utilities/virtualizer) are guides built around third-party libraries — their pages describe which packages to install.
+Utility docs such as [Sortable](/docs/utilities/sortable) and [Virtualized](/docs/utilities/virtualized) are guides built around third-party libraries — their pages describe which packages to install.
diff --git a/apps/v4/content/docs/utilities/meta.json b/apps/v4/content/docs/utilities/meta.json
index 6b12736..00dc3d7 100644
--- a/apps/v4/content/docs/utilities/meta.json
+++ b/apps/v4/content/docs/utilities/meta.json
@@ -1,4 +1,4 @@
 {
   "title": "Utilities",
-  "pages": ["sortable", "virtualizer"]
+  "pages": ["sortable", "virtualized"]
 }
diff --git a/apps/v4/content/docs/utilities/sortable.mdx b/apps/v4/content/docs/utilities/sortable.mdx
index ee19151..3a66d05 100644
--- a/apps/v4/content/docs/utilities/sortable.mdx
+++ b/apps/v4/content/docs/utilities/sortable.mdx
@@ -104,7 +104,7 @@ import {
 
 ### Virtualized
 
-<ComponentPreview name="virtualizer-sortable" />
+<ComponentPreview name="virtualized-sortable" />
 
 ## Accessibility
 
diff --git a/apps/v4/content/docs/utilities/virtualized.mdx b/apps/v4/content/docs/utilities/virtualized.mdx
index c8c9a24..de0aa2f 100644
--- a/apps/v4/content/docs/utilities/virtualized.mdx
+++ b/apps/v4/content/docs/utilities/virtualized.mdx
@@ -1,13 +1,13 @@
 ---
-title: Virtualizer
-description: A virtualizer component that allows you to efficiently render large lists and tabular data.
+title: Virtualized
+description: A virtualized component that allows you to efficiently render large lists and tabular data.
 component: true
 links:
   doc: https://github.com/inokawa/virtua
   api: https://github.com/inokawa/virtua/blob/main/docs/react/API.md
 ---
 
-<ComponentPreview name="virtualizer-demo" />
+<ComponentPreview name="virtualized-demo" />
 
 ## Introduction
 
@@ -87,19 +87,19 @@ npm install @base-ui/react virtua
 
 ### Default
 
-<ComponentPreview name="virtualizer-demo" />
+<ComponentPreview name="virtualized-demo" />
 
 ### Horizontal
 
-<ComponentPreview name="virtualizer-horizontal" />
+<ComponentPreview name="virtualized-horizontal" />
 
 ### Grid
 
-<ComponentPreview name="virtualizer-grid" />
+<ComponentPreview name="virtualized-grid" />
 
 ### Table
 
-<ComponentPreview name="virtualizer-table" />
+<ComponentPreview name="virtualized-table" />
 
 <Callout className="mt-6">
 
@@ -109,23 +109,23 @@ npm install @base-ui/react virtua
 
 ### Command
 
-<ComponentPreview name="virtualizer-command" />
+<ComponentPreview name="virtualized-command" />
 
 ### Combobox
 
-<ComponentPreview name="virtualizer-combobox" />
+<ComponentPreview name="virtualized-combobox" />
 
 ### Select
 
-<ComponentPreview name="virtualizer-select" />
+<ComponentPreview name="virtualized-select" />
 
 ### Scroll Area
 
-<ComponentPreview name="virtualizer-scroll-area" />
+<ComponentPreview name="virtualized-scroll-area" />
 
 ### Sortable
 
-<ComponentPreview name="virtualizer-sortable" />
+<ComponentPreview name="virtualized-sortable" />
 
 ## Combobox
 
@@ -193,7 +193,7 @@ export function VirtualizedComboboxDemo() {
 
 </Steps>
 
-<ComponentPreview name="virtualizer-combobox" />
+<ComponentPreview name="virtualized-combobox" />
 
 <Callout className="mt-4">
 
@@ -232,7 +232,7 @@ export function VirtualizedScrollAreaDemo() {
 
 </Steps>
 
-<ComponentPreview name="virtualizer-scroll-area" />
+<ComponentPreview name="virtualized-scroll-area" />
 
 <Callout className="mt-4">
 
@@ -346,7 +346,7 @@ export function VirtualizedSelectDemo() {
 
 </Steps>
 
-<ComponentPreview name="virtualizer-select" />
+<ComponentPreview name="virtualized-select" />
 
 ## Reusable Components
 
@@ -358,6 +358,12 @@ This section is empty for now.
 
 </Callout>
 
+## Accessibility
+
+Virtualization only affects what's mounted in the DOM, not the semantics of the component being virtualized — a virtualized `<Select />` or `<Combobox />` keeps the same roles, states and keyboard behavior as its non-virtualized counterpart, since `<VirtualizedVirtualizer />` renders its children directly inside the existing listbox/popover markup.
+
+Because off-screen items aren't in the DOM, avoid relying on browser "find in page" or assistive technology virtual cursor navigation to reach items outside the rendered window — users should navigate with the component's own keyboard interactions (arrow keys, typeahead) instead, which keep the active item mounted and in view via `keepMounted` and `scrollToIndex`.
+
 ## API Reference
 
 Thin wrappers around [virtua](https://github.com/inokawa/virtua) — see the [virtua API reference](https://github.com/inokawa/virtua/blob/main/docs/react/API.md) for the full list of underlying props and imperative handle methods.
diff --git a/apps/v4/package.json b/apps/v4/package.json
index 40e18a4..db812e6 100644
--- a/apps/v4/package.json
+++ b/apps/v4/package.json
@@ -8,6 +8,7 @@
     "build": "next build",
     "start": "next start",
     "lint": "eslint .",
+    "registry:validate": "shadcn registry validate ./registry.json",
     "postinstall": "fumadocs-mdx"
   },
   "dependencies": {
diff --git a/apps/v4/src/components/examples/phone-input-primitive-preferred-country.tsx b/apps/v4/src/components/examples/phone-input-primitive-preferred-country.tsx
index db9e624..4ffa5e4 100644
--- a/apps/v4/src/components/examples/phone-input-primitive-preferred-country.tsx
+++ b/apps/v4/src/components/examples/phone-input-primitive-preferred-country.tsx
@@ -2,37 +2,33 @@
 
 import * as React from "react";
 
-import { cn } from "@/lib/utils";
 import * as PhoneInputPrimitive from "@/registry/new-york/ui/phone-input-primitive";
 
-function Input({ className, ...props }: React.ComponentProps<"input">) {
-  return <input className={cn("border-input border", className)} {...props} />;
-}
-
 export default function PhoneInputPrimitivePreferredCountry() {
   const [value, setValue] = React.useState<PhoneInputPrimitive.Value>(
     "+60123456789" as PhoneInputPrimitive.Value,
   );
 
+  const input = React.useMemo(() => <input />, []);
+
   return (
-    <div className="flex flex-col gap-2">
+    <div>
       <PhoneInputPrimitive.Root
         value={value}
         onValueChange={setValue}
         preferredCountry="MY"
         defaultInternationalForPreferredCountry
       >
-        <PhoneInputPrimitive.Input render={<Input />} />
+        <PhoneInputPrimitive.Input render={input} />
       </PhoneInputPrimitive.Root>
-      <p className="text-muted-foreground text-sm">
-        Preferred country has been set to{" "}
-        <code className="font-medium">MY</code> (Malaysia).
+      <p>
+        Preferred country has been set to <code>MY</code> (Malaysia).
       </p>
-      <dl className="grid grid-cols-2 gap-2 text-sm">
-        <dt className="text-muted-foreground">National format (default):</dt>
-        <dd className="text-foreground">012-345 6789</dd>
-        <dt className="text-muted-foreground">International format:</dt>
-        <dd className="text-foreground">+60 12 345 6789</dd>
+      <dl>
+        <dt>National format (default):</dt>
+        <dd>012-345 6789</dd>
+        <dt>International format:</dt>
+        <dd>+60 12 345 6789</dd>
       </dl>
     </div>
   );
diff --git a/apps/v4/src/components/examples/virtualized-combobox.tsx b/apps/v4/src/components/examples/virtualized-combobox.tsx
index daa8c83..311ca82 100644
--- a/apps/v4/src/components/examples/virtualized-combobox.tsx
+++ b/apps/v4/src/components/examples/virtualized-combobox.tsx
@@ -20,7 +20,7 @@ const items = Array.from({ length: 10000 }, (_, index) => ({
   value: index.toString(),
 }));
 
-export default function VirtualizerCombobox() {
+export default function VirtualizedCombobox() {
   const [inputValue, setInputValue] = React.useState("");
 
   const filtered = React.useMemo(() => {
diff --git a/apps/v4/src/components/examples/virtualized-command.tsx b/apps/v4/src/components/examples/virtualized-command.tsx
index 2953e61..bbb54dc 100644
--- a/apps/v4/src/components/examples/virtualized-command.tsx
+++ b/apps/v4/src/components/examples/virtualized-command.tsx
@@ -23,7 +23,7 @@ const items = Array.from({ length: 1000 }, (_, index) => ({
   value: index.toString(),
 }));
 
-export default function VirtualizerCommand() {
+export default function VirtualizedCommand() {
   const [inputValue, setInputValue] = React.useState("");
 
   const filtered = React.useMemo(() => {
diff --git a/apps/v4/src/components/examples/virtualized-demo.tsx b/apps/v4/src/components/examples/virtualized-demo.tsx
index 3319fdf..471c0f0 100644
--- a/apps/v4/src/components/examples/virtualized-demo.tsx
+++ b/apps/v4/src/components/examples/virtualized-demo.tsx
@@ -6,7 +6,7 @@ import { VirtualizedList } from "@/registry/new-york/ui/virtualized";
 
 const items = Array.from({ length: 10000 }, (_, index) => index);
 
-export default function VirtualizerDemo() {
+export default function VirtualizedDemo() {
   return (
     <div className="size-80">
       <VirtualizedList>
diff --git a/apps/v4/src/components/examples/virtualized-grid.tsx b/apps/v4/src/components/examples/virtualized-grid.tsx
index 0c6666d..16f375e 100644
--- a/apps/v4/src/components/examples/virtualized-grid.tsx
+++ b/apps/v4/src/components/examples/virtualized-grid.tsx
@@ -4,7 +4,7 @@ import { Card, CardContent } from "@/components/ui/card";
 import { cn } from "@/lib/utils";
 import { VirtualizedGrid } from "@/registry/new-york/ui/virtualized";
 
-export default function VirtualizerGrid() {
+export default function VirtualizedGridDemo() {
   return (
     <div className="size-80">
       <VirtualizedGrid row={500} col={500}>
diff --git a/apps/v4/src/components/examples/virtualized-horizontal.tsx b/apps/v4/src/components/examples/virtualized-horizontal.tsx
index 4a327bd..e036012 100644
--- a/apps/v4/src/components/examples/virtualized-horizontal.tsx
+++ b/apps/v4/src/components/examples/virtualized-horizontal.tsx
@@ -5,7 +5,7 @@ import { VirtualizedList } from "@/registry/new-york/ui/virtualized";
 
 const items = Array.from({ length: 10000 }, (_, index) => index);
 
-export default function VirtualizerHorizontal() {
+export default function VirtualizedHorizontal() {
   return (
     <div className="size-80">
       <VirtualizedList orientation="horizontal">
diff --git a/apps/v4/src/components/examples/virtualized-scroll-area.tsx b/apps/v4/src/components/examples/virtualized-scroll-area.tsx
index 60a3a20..827e29d 100644
--- a/apps/v4/src/components/examples/virtualized-scroll-area.tsx
+++ b/apps/v4/src/components/examples/virtualized-scroll-area.tsx
@@ -14,7 +14,7 @@ const tags = Array.from({ length: 10000 }).map(
   (_, i, a) => `v1.2.0-beta.${a.length - i}`,
 );
 
-export default function VirtualizerScrollArea() {
+export default function VirtualizedScrollArea() {
   return (
     <ScrollAreaPrimitive.Root className="relative h-72 w-48 overflow-hidden rounded-md border">
       <ScrollAreaPrimitive.Viewport
diff --git a/apps/v4/src/components/examples/virtualized-select.tsx b/apps/v4/src/components/examples/virtualized-select.tsx
index 44b79c5..74124b2 100644
--- a/apps/v4/src/components/examples/virtualized-select.tsx
+++ b/apps/v4/src/components/examples/virtualized-select.tsx
@@ -20,7 +20,7 @@ const items = Array.from({ length: 10000 }, (_, index) => ({
   value: index.toString(),
 }));
 
-export default function VirtualizerSelect() {
+export default function VirtualizedSelect() {
   const [value, setValue] = React.useState<string | null>(null);
   const [open, setOpen] = React.useState(false);
 
diff --git a/apps/v4/src/components/examples/virtualized-sortable.tsx b/apps/v4/src/components/examples/virtualized-sortable.tsx
index 3cbfe38..12a6dc7 100644
--- a/apps/v4/src/components/examples/virtualized-sortable.tsx
+++ b/apps/v4/src/components/examples/virtualized-sortable.tsx
@@ -49,7 +49,7 @@ function Item({
   );
 }
 
-export default function VirtualizerSortable() {
+export default function VirtualizedSortable() {
   const [items, setItems] = React.useState(
     Array.from({ length: 1000 }, (_, index) => ({
       id: `item-${index}`,
diff --git a/apps/v4/src/components/examples/virtualized-table.tsx b/apps/v4/src/components/examples/virtualized-table.tsx
index d60d896..e239fef 100644
--- a/apps/v4/src/components/examples/virtualized-table.tsx
+++ b/apps/v4/src/components/examples/virtualized-table.tsx
@@ -47,7 +47,7 @@ function VirtualizedTableBody(props: CustomContainerComponentProps) {
   return <TableBody className="max-h-96" {...props} />;
 }
 
-export default function VirtualizerTable() {
+export default function VirtualizedTable() {
   return (
     <Virtualized className="h-96 overflow-y-auto">
       <table className="w-full table-fixed caption-bottom border-separate border-spacing-0 text-sm">
diff --git a/apps/v4/src/registry/new-york/ui/dropzone.tsx b/apps/v4/src/registry/new-york/ui/dropzone.tsx
index b997a68..8e76d45 100644
--- a/apps/v4/src/registry/new-york/ui/dropzone.tsx
+++ b/apps/v4/src/registry/new-york/ui/dropzone.tsx
@@ -26,7 +26,7 @@ function DropzoneZone({
     <DropzonePrimitive.Zone
       data-slot="dropzone-zone"
       className={cn(
-        "border-input hover:border-accent-foreground/50 hover:bg-accent focus-visible:border-ring focus-visible:ring-ring/50 aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive data-[drag-active]:border-accent-foreground/50 data-[drag-reject]:border-destructive data-[drag-active]:bg-accent data-[drag-reject]:bg-destructive/30 cursor-pointer rounded-md border-2 border-dashed p-6 shadow-xs transition-colors outline-none focus-visible:ring-[3px] data-[disabled]:cursor-not-allowed data-[disabled]:border-inherit data-[disabled]:bg-inherit data-[disabled]:opacity-50 data-[drag-reject]:cursor-no-drop data-[no-click]:cursor-default",
+        "border-input hover:border-accent-foreground/50 hover:bg-accent focus-visible:border-ring focus-visible:ring-ring/50 aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive data-[drag-active]:border-accent-foreground/50 data-[drag-reject]:border-destructive data-[drag-active]:bg-accent data-[drag-reject]:bg-destructive/30 cursor-pointer rounded-lg border-2 border-dashed p-6 shadow-xs transition-colors outline-none focus-visible:ring-3 data-[disabled]:cursor-not-allowed data-[disabled]:border-inherit data-[disabled]:bg-inherit data-[disabled]:opacity-50 data-[drag-reject]:cursor-no-drop data-[no-click]:cursor-default",
         className,
       )}
       {...props}
diff --git a/apps/v4/src/registry/new-york/ui/phone-input.tsx b/apps/v4/src/registry/new-york/ui/phone-input.tsx
index dc213cf..03c9ae5 100644
--- a/apps/v4/src/registry/new-york/ui/phone-input.tsx
+++ b/apps/v4/src/registry/new-york/ui/phone-input.tsx
@@ -150,7 +150,7 @@ function PhoneInputCountrySelectInternationalItem(
     <SelectPrimitive.Item
       data-slot="phone-input-country-select-international-item"
       className={cn(
-        "focus:bg-accent focus:text-accent-foreground [&_svg:not([class*='text-'])]:text-muted-foreground relative flex w-full cursor-default items-center justify-between gap-2 rounded-sm py-1.5 pr-8 pl-2 text-sm outline-hidden select-none data-[disabled]:pointer-events-none data-[disabled]:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4 *:[span]:last:flex *:[span]:last:items-center *:[span]:last:gap-2",
+        "focus:bg-accent focus:text-accent-foreground [&_svg:not([class*='text-'])]:text-muted-foreground relative flex w-full cursor-default items-center justify-between gap-2 rounded-md py-1 pr-8 pl-1.5 text-sm outline-hidden select-none data-disabled:pointer-events-none data-disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4 *:[span]:last:flex *:[span]:last:items-center *:[span]:last:gap-2",
       )}
       value={PhoneInputPrimitive.INTERNATIONAL_COUNTRY_CODE}
       {...props}
@@ -186,7 +186,7 @@ function PhoneInputCountrySelectItem({
     <SelectPrimitive.Item
       data-slot="phone-input-country-select-item"
       className={cn(
-        "focus:bg-accent focus:text-accent-foreground [&_svg:not([class*='text-'])]:text-muted-foreground relative flex w-full cursor-default items-center justify-between gap-2 rounded-sm py-1.5 pr-8 pl-2 text-sm outline-hidden select-none data-[disabled]:pointer-events-none data-[disabled]:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4 *:[span]:last:flex *:[span]:last:items-center *:[span]:last:gap-2",
+        "focus:bg-accent focus:text-accent-foreground [&_svg:not([class*='text-'])]:text-muted-foreground relative flex w-full cursor-default items-center justify-between gap-2 rounded-md py-1 pr-8 pl-1.5 text-sm outline-hidden select-none data-disabled:pointer-events-none data-disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4 *:[span]:last:flex *:[span]:last:items-center *:[span]:last:gap-2",
         className,
       )}
       value={value}
diff --git a/apps/v4/src/registry/new-york/ui/virtualized.tsx b/apps/v4/src/registry/new-york/ui/virtualized.tsx
index afbec94..c871ba8 100644
--- a/apps/v4/src/registry/new-york/ui/virtualized.tsx
+++ b/apps/v4/src/registry/new-york/ui/virtualized.tsx
@@ -14,11 +14,7 @@ const VirtualizedContext = React.createContext<{
 });
 
 function useVirtualized() {
-  const context = React.useContext(VirtualizedContext);
-  if (!context) {
-    throw new Error("useVirtualized must be used within a <Virtualized />.");
-  }
-  return context;
+  return React.useContext(VirtualizedContext);
 }
 
 function Virtualized({ render, ...props }: useRender.ComponentProps<"div">) {

From 32a1d100cfc2eff0a7b2410dcd55ab98b00002d0 Mon Sep 17 00:00:00 2001
From: junwen-k <40173716+junwen-k@users.noreply.github.com>
Date: Sun, 19 Jul 2026 15:39:34 +0800
Subject: [PATCH 3/9] revert: keep the useVirtualized() throw guard for
 convention consistency

The guard is unreachable in isolation (VirtualizedContext's default is
a real object, never null), but sortable.tsx's useSortable() has the
identical shape and every other "must be used within" hook in the
registry follows the same throw-guard pattern. Removing it only here
broke consistency rather than fixing a real bug.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 apps/v4/src/registry/new-york/ui/virtualized.tsx | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/apps/v4/src/registry/new-york/ui/virtualized.tsx b/apps/v4/src/registry/new-york/ui/virtualized.tsx
index c871ba8..afbec94 100644
--- a/apps/v4/src/registry/new-york/ui/virtualized.tsx
+++ b/apps/v4/src/registry/new-york/ui/virtualized.tsx
@@ -14,7 +14,11 @@ const VirtualizedContext = React.createContext<{
 });
 
 function useVirtualized() {
-  return React.useContext(VirtualizedContext);
+  const context = React.useContext(VirtualizedContext);
+  if (!context) {
+    throw new Error("useVirtualized must be used within a <Virtualized />.");
+  }
+  return context;
 }
 
 function Virtualized({ render, ...props }: useRender.ComponentProps<"div">) {

From f43e04e020c3704189252818c1260b0c2a780af8 Mon Sep 17 00:00:00 2001
From: junwen-k <40173716+junwen-k@users.noreply.github.com>
Date: Sun, 19 Jul 2026 15:56:47 +0800
Subject: [PATCH 4/9] refactor(dropzone): compose visual content with shadcn
 Empty

Drop DropzoneGroup, DropzoneTitle, DropzoneDescription and
DropzoneUploadIcon in favor of shadcn/ui's Empty component. Dropzone now
covers only the interactive parts; the zone's icon, title and description
are composed with Empty/EmptyHeader/EmptyMedia/EmptyTitle/EmptyDescription.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 apps/v4/content/docs/changelog.mdx            |   1 +
 apps/v4/content/docs/components/dropzone.mdx  |  60 ++++++----
 apps/v4/registry.json                         |   2 +-
 .../src/components/examples/dropzone-demo.tsx |  40 ++++---
 .../src/components/examples/dropzone-form.tsx |  49 ++++++---
 .../components/examples/dropzone-trigger.tsx  |  52 ++++++---
 apps/v4/src/components/ui/empty.tsx           | 104 ++++++++++++++++++
 apps/v4/src/registry/new-york/ui/dropzone.tsx |  92 ----------------
 8 files changed, 243 insertions(+), 157 deletions(-)
 create mode 100644 apps/v4/src/components/ui/empty.tsx

diff --git a/apps/v4/content/docs/changelog.mdx b/apps/v4/content/docs/changelog.mdx
index c7045eb..53e1de9 100644
--- a/apps/v4/content/docs/changelog.mdx
+++ b/apps/v4/content/docs/changelog.mdx
@@ -14,6 +14,7 @@ ui-x is now built on [Base UI](https://base-ui.com). Following shadcn/ui's adopt
 - **Base UI everywhere** — All Radix UI dependencies are gone. Components are built on Base UI primitives and utilities, with React 19 ref handling throughout.
 - **Restyled** — Every component, demo and docs page has been refreshed against the latest shadcn/ui styling.
 - **Simpler forms** — Demos use Base UI's `Field` and `Form` for form plumbing. For React Hook Form or TanStack Form wiring, see the shadcn/ui [forms guides](https://ui.shadcn.com/docs/forms).
+- **Dropzone composes with Empty** — `DropzoneGroup`, `DropzoneTitle`, `DropzoneDescription` and `DropzoneUploadIcon` are gone. Dropzone now only covers the interactive parts; build the zone's visual content with shadcn/ui's [Empty](https://ui.shadcn.com/docs/components/empty) component instead.
 
 ### Superseded components
 
diff --git a/apps/v4/content/docs/components/dropzone.mdx b/apps/v4/content/docs/components/dropzone.mdx
index 2802a3a..3f6b4a6 100644
--- a/apps/v4/content/docs/components/dropzone.mdx
+++ b/apps/v4/content/docs/components/dropzone.mdx
@@ -39,6 +39,16 @@ npm install @base-ui/react
 
 <Step>
 
+Add the `<Empty />` component to your project.
+
+</Step>
+
+The `<Dropzone />` component uses the `<Empty />` component for its visual content. Make sure you have it installed in your project.
+
+See installation instructions for the [Empty](https://ui.shadcn.com/docs/components/empty) component.
+
+<Step>
+
 Add the `<DropzonePrimitive />` component to your project.
 
 </Step>
@@ -62,15 +72,19 @@ See installation instructions for the [DropzonePrimitive](/docs/primitives/dropz
 ## Usage
 
 ```tsx
+import {
+  Empty,
+  EmptyDescription,
+  EmptyHeader,
+  EmptyMedia,
+  EmptyTitle,
+} from "@/components/ui/empty";
 import {
   Dropzone,
-  DropzoneDescription,
-  DropzoneGroup,
   DropzoneInput,
-  DropzoneTitle,
-  DropzoneUploadIcon,
   DropzoneZone,
 } from "@/components/ui/dropzone";
+import * as DropzonePrimitive from "@/components/ui/dropzone-primitive";
 ```
 
 ```tsx
@@ -83,16 +97,26 @@ import {
 >
   <DropzoneZone>
     <DropzoneInput />
-    <DropzoneGroup className="gap-4">
-      <DropzoneUploadIcon />
-      <DropzoneGroup>
-        <DropzoneTitle>Drop files here or click to upload</DropzoneTitle>
-        <DropzoneDescription>
+    <Empty>
+      <EmptyHeader>
+        <EmptyMedia variant="icon">
+          <DropzonePrimitive.DragAccepted>
+            <CheckCircle2Icon />
+          </DropzonePrimitive.DragAccepted>
+          <DropzonePrimitive.DragRejected>
+            <BanIcon />
+          </DropzonePrimitive.DragRejected>
+          <DropzonePrimitive.DragDefault>
+            <UploadIcon />
+          </DropzonePrimitive.DragDefault>
+        </EmptyMedia>
+        <EmptyTitle>Drop files here or click to upload</EmptyTitle>
+        <EmptyDescription>
           You can upload files up to 10MB in size. Supported formats: JPG, PNG,
           PDF.
-        </DropzoneDescription>
-      </DropzoneGroup>
-    </DropzoneGroup>
+        </EmptyDescription>
+      </EmptyHeader>
+    </Empty>
   </DropzoneZone>
 </Dropzone>
 ```
@@ -113,11 +137,11 @@ import {
 
 ## Accessibility
 
-The zone is focusable and opens the file dialog with <Kbd>Enter</Kbd> or <Kbd>Space</Kbd>, so the drag-and-drop interaction always has a keyboard equivalent. Make sure the zone contains visible text describing what to upload (such as `<DropzoneTitle />` and `<DropzoneDescription />`) — the upload icon alone is not an accessible name. Drag states are conveyed with color and iconography via `<DropzoneUploadIcon />`; keep the title text meaningful so the state change is not communicated by color alone.
+The zone is focusable and opens the file dialog with <Kbd>Enter</Kbd> or <Kbd>Space</Kbd>, so the drag-and-drop interaction always has a keyboard equivalent. Make sure the zone contains visible text describing what to upload (such as `<EmptyTitle />` and `<EmptyDescription />`) — the upload icon alone is not an accessible name. Drag states are conveyed with color and iconography via the `<DragDefault />`/`<DragAccepted />`/`<DragRejected />` icon swap; keep the title text meaningful so the state change is not communicated by color alone.
 
 ## API Reference
 
-Styled wrappers around the [Dropzone primitive](/docs/primitives/dropzone#api-reference) — see the primitive page for the full prop tables.
+Styled wrappers around the [Dropzone primitive](/docs/primitives/dropzone#api-reference) — see the primitive page for the full prop tables. Visual content (icon, title, description) is composed with shadcn/ui's [Empty](https://ui.shadcn.com/docs/components/empty) component rather than a Dropzone-specific part.
 
 ### Dropzone
 
@@ -135,14 +159,6 @@ Wraps [Input](/docs/primitives/dropzone#input), the visually hidden file input.
 
 Wraps [Trigger](/docs/primitives/dropzone#trigger) for opening the file dialog from a button outside the zone.
 
-### DropzoneUploadIcon
-
-A convenience part that renders an upload, accepted or rejected icon based on the current drag state, using the [DragDefault](/docs/primitives/dropzone#dragdefault), [DragAccepted](/docs/primitives/dropzone#dragaccepted) and [DragRejected](/docs/primitives/dropzone#dragrejected) parts. Accepts `lucide-react` icon props.
-
-### DropzoneGroup, DropzoneTitle, DropzoneDescription
-
-Layout and typography parts for the zone's content. Render a `<div>`, `<h3>` and `<p>` respectively, and support the `render` prop.
-
 ### DropzoneAccepted, DropzoneRejected
 
 Wrap [Accepted and Rejected](/docs/primitives/dropzone#accepted), render-prop parts receiving the accepted files or rejections.
diff --git a/apps/v4/registry.json b/apps/v4/registry.json
index dff5b37..4302493 100644
--- a/apps/v4/registry.json
+++ b/apps/v4/registry.json
@@ -293,7 +293,7 @@
       "title": "Dropzone",
       "description": "A dropzone is an area into which one or multiple objects can be dragged and dropped.",
       "dependencies": ["@base-ui/react"],
-      "registryDependencies": ["junwen-k/ui-x/dropzone-primitive"],
+      "registryDependencies": ["empty", "junwen-k/ui-x/dropzone-primitive"],
       "files": [
         {
           "path": "src/registry/new-york/ui/dropzone.tsx",
diff --git a/apps/v4/src/components/examples/dropzone-demo.tsx b/apps/v4/src/components/examples/dropzone-demo.tsx
index 75db774..d6a1650 100644
--- a/apps/v4/src/components/examples/dropzone-demo.tsx
+++ b/apps/v4/src/components/examples/dropzone-demo.tsx
@@ -1,6 +1,6 @@
 "use client";
 
-import { FileIcon } from "lucide-react";
+import { BanIcon, CheckCircle2Icon, FileIcon, UploadIcon } from "lucide-react";
 import prettyBytes from "pretty-bytes";
 import * as React from "react";
 
@@ -11,15 +11,19 @@ import {
   AttachmentMedia,
   AttachmentTitle,
 } from "@/components/ui/attachment";
+import {
+  Empty,
+  EmptyDescription,
+  EmptyHeader,
+  EmptyMedia,
+  EmptyTitle,
+} from "@/components/ui/empty";
 import {
   Dropzone,
-  DropzoneDescription,
-  DropzoneGroup,
   DropzoneInput,
-  DropzoneTitle,
-  DropzoneUploadIcon,
   DropzoneZone,
 } from "@/registry/new-york/ui/dropzone";
+import * as DropzonePrimitive from "@/registry/new-york/ui/dropzone-primitive";
 
 export default function DropzoneDemo() {
   const [files, setFiles] = React.useState<File[]>([]);
@@ -35,16 +39,26 @@ export default function DropzoneDemo() {
       <div className="grid gap-4">
         <DropzoneZone>
           <DropzoneInput />
-          <DropzoneGroup className="gap-4">
-            <DropzoneUploadIcon />
-            <DropzoneGroup>
-              <DropzoneTitle>Drop files here or click to upload</DropzoneTitle>
-              <DropzoneDescription>
+          <Empty>
+            <EmptyHeader>
+              <EmptyMedia variant="icon">
+                <DropzonePrimitive.DragAccepted>
+                  <CheckCircle2Icon />
+                </DropzonePrimitive.DragAccepted>
+                <DropzonePrimitive.DragRejected>
+                  <BanIcon />
+                </DropzonePrimitive.DragRejected>
+                <DropzonePrimitive.DragDefault>
+                  <UploadIcon />
+                </DropzonePrimitive.DragDefault>
+              </EmptyMedia>
+              <EmptyTitle>Drop files here or click to upload</EmptyTitle>
+              <EmptyDescription>
                 You can upload files up to 10MB in size. Supported formats: JPG,
                 PNG, PDF.
-              </DropzoneDescription>
-            </DropzoneGroup>
-          </DropzoneGroup>
+              </EmptyDescription>
+            </EmptyHeader>
+          </Empty>
         </DropzoneZone>
         {files.length > 0 && (
           <div className="grid gap-2">
diff --git a/apps/v4/src/components/examples/dropzone-form.tsx b/apps/v4/src/components/examples/dropzone-form.tsx
index 1ce25d6..8838b30 100644
--- a/apps/v4/src/components/examples/dropzone-form.tsx
+++ b/apps/v4/src/components/examples/dropzone-form.tsx
@@ -1,6 +1,12 @@
 "use client";
 
-import { FileIcon, XIcon } from "lucide-react";
+import {
+  BanIcon,
+  CheckCircle2Icon,
+  FileIcon,
+  UploadIcon,
+  XIcon,
+} from "lucide-react";
 import prettyBytes from "pretty-bytes";
 import * as React from "react";
 import { ErrorCode } from "react-dropzone";
@@ -24,15 +30,20 @@ import {
   CardHeader,
   CardTitle,
 } from "@/components/ui/card";
+import {
+  Empty,
+  EmptyDescription,
+  EmptyHeader,
+  EmptyMedia,
+  EmptyTitle,
+} from "@/components/ui/empty";
 import { Field, FieldDescription, FieldLabel } from "@/components/ui/field";
 import {
   Dropzone,
-  DropzoneDescription,
   DropzoneInput,
-  DropzoneTitle,
-  DropzoneUploadIcon,
   DropzoneZone,
 } from "@/registry/new-york/ui/dropzone";
+import * as DropzonePrimitive from "@/registry/new-york/ui/dropzone-primitive";
 
 // 1 MB
 const MAX_FILE_SIZE = 1e6;
@@ -73,15 +84,27 @@ export default function DropzoneForm() {
               <FieldLabel htmlFor="dropzone-form-files">File upload</FieldLabel>
               <DropzoneZone className="flex justify-center">
                 <DropzoneInput id="dropzone-form-files" />
-                <div className="flex items-center gap-6">
-                  <DropzoneUploadIcon />
-                  <div className="grid gap-0.5">
-                    <DropzoneTitle>Browse to upload your file</DropzoneTitle>
-                    <DropzoneDescription>
-                      {`Maximum file size: ${prettyBytes(maxSize ?? 0)}`}
-                    </DropzoneDescription>
-                  </div>
-                </div>
+                <Empty>
+                  <EmptyHeader className="flex-row items-center gap-6 text-left">
+                    <EmptyMedia variant="icon">
+                      <DropzonePrimitive.DragAccepted>
+                        <CheckCircle2Icon />
+                      </DropzonePrimitive.DragAccepted>
+                      <DropzonePrimitive.DragRejected>
+                        <BanIcon />
+                      </DropzonePrimitive.DragRejected>
+                      <DropzonePrimitive.DragDefault>
+                        <UploadIcon />
+                      </DropzonePrimitive.DragDefault>
+                    </EmptyMedia>
+                    <div className="grid gap-0.5">
+                      <EmptyTitle>Browse to upload your file</EmptyTitle>
+                      <EmptyDescription>
+                        {`Maximum file size: ${prettyBytes(maxSize ?? 0)}`}
+                      </EmptyDescription>
+                    </div>
+                  </EmptyHeader>
+                </Empty>
               </DropzoneZone>
               <FieldDescription>Drag and drop is supported.</FieldDescription>
             </Field>
diff --git a/apps/v4/src/components/examples/dropzone-trigger.tsx b/apps/v4/src/components/examples/dropzone-trigger.tsx
index 74784d3..1f75c01 100644
--- a/apps/v4/src/components/examples/dropzone-trigger.tsx
+++ b/apps/v4/src/components/examples/dropzone-trigger.tsx
@@ -1,33 +1,53 @@
+import { BanIcon, CheckCircle2Icon, UploadIcon } from "lucide-react";
+
 import { Button } from "@/components/ui/button";
+import {
+  Empty,
+  EmptyContent,
+  EmptyDescription,
+  EmptyHeader,
+  EmptyMedia,
+  EmptyTitle,
+} from "@/components/ui/empty";
 import {
   Dropzone,
-  DropzoneDescription,
   DropzoneInput,
-  DropzoneTitle,
   DropzoneTrigger,
-  DropzoneUploadIcon,
   DropzoneZone,
 } from "@/registry/new-york/ui/dropzone";
+import * as DropzonePrimitive from "@/registry/new-york/ui/dropzone-primitive";
 
 export default function DropzoneTriggerDemo() {
   return (
     <Dropzone noClick>
       <DropzoneZone>
         <DropzoneInput />
-        <div className="flex flex-col items-center gap-4 text-center">
-          <DropzoneUploadIcon />
-          <div className="flex flex-col gap-1.5">
-            <DropzoneTitle>Drop files here</DropzoneTitle>
-            <DropzoneDescription>
+        <Empty>
+          <EmptyHeader>
+            <EmptyMedia variant="icon">
+              <DropzonePrimitive.DragAccepted>
+                <CheckCircle2Icon />
+              </DropzonePrimitive.DragAccepted>
+              <DropzonePrimitive.DragRejected>
+                <BanIcon />
+              </DropzonePrimitive.DragRejected>
+              <DropzonePrimitive.DragDefault>
+                <UploadIcon />
+              </DropzonePrimitive.DragDefault>
+            </EmptyMedia>
+            <EmptyTitle>Drop files here</EmptyTitle>
+            <EmptyDescription>
               Please upload file with less than 4MB.
-            </DropzoneDescription>
-          </div>
-          <DropzoneTrigger
-            render={<Button variant="outline" className="w-full" />}
-          >
-            Open
-          </DropzoneTrigger>
-        </div>
+            </EmptyDescription>
+          </EmptyHeader>
+          <EmptyContent>
+            <DropzoneTrigger
+              render={<Button variant="outline" className="w-full" />}
+            >
+              Open
+            </DropzoneTrigger>
+          </EmptyContent>
+        </Empty>
       </DropzoneZone>
     </Dropzone>
   );
diff --git a/apps/v4/src/components/ui/empty.tsx b/apps/v4/src/components/ui/empty.tsx
new file mode 100644
index 0000000..84d4ffd
--- /dev/null
+++ b/apps/v4/src/components/ui/empty.tsx
@@ -0,0 +1,104 @@
+import { type VariantProps, cva } from "class-variance-authority";
+
+import { cn } from "@/lib/utils";
+
+function Empty({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="empty"
+      className={cn(
+        "flex w-full min-w-0 flex-1 flex-col items-center justify-center gap-4 rounded-xl border-dashed p-6 text-center text-balance",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+function EmptyHeader({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="empty-header"
+      className={cn("flex max-w-sm flex-col items-center gap-2", className)}
+      {...props}
+    />
+  );
+}
+
+const emptyMediaVariants = cva(
+  "mb-2 flex shrink-0 items-center justify-center [&_svg]:pointer-events-none [&_svg]:shrink-0",
+  {
+    variants: {
+      variant: {
+        default: "bg-transparent",
+        icon: "flex size-8 shrink-0 items-center justify-center rounded-lg bg-muted text-foreground [&_svg:not([class*='size-'])]:size-4",
+      },
+    },
+    defaultVariants: {
+      variant: "default",
+    },
+  },
+);
+
+function EmptyMedia({
+  className,
+  variant = "default",
+  ...props
+}: React.ComponentProps<"div"> & VariantProps<typeof emptyMediaVariants>) {
+  return (
+    <div
+      data-slot="empty-icon"
+      data-variant={variant}
+      className={cn(emptyMediaVariants({ variant, className }))}
+      {...props}
+    />
+  );
+}
+
+function EmptyTitle({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="empty-title"
+      className={cn(
+        "font-heading text-sm font-medium tracking-tight",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+function EmptyDescription({ className, ...props }: React.ComponentProps<"p">) {
+  return (
+    <div
+      data-slot="empty-description"
+      className={cn(
+        "text-muted-foreground [&>a:hover]:text-primary text-sm/relaxed [&>a]:underline [&>a]:underline-offset-4",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+function EmptyContent({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="empty-content"
+      className={cn(
+        "flex w-full max-w-sm min-w-0 flex-col items-center gap-2.5 text-sm text-balance",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+export {
+  Empty,
+  EmptyHeader,
+  EmptyTitle,
+  EmptyDescription,
+  EmptyContent,
+  EmptyMedia,
+};
diff --git a/apps/v4/src/registry/new-york/ui/dropzone.tsx b/apps/v4/src/registry/new-york/ui/dropzone.tsx
index 8e76d45..eb4d7ee 100644
--- a/apps/v4/src/registry/new-york/ui/dropzone.tsx
+++ b/apps/v4/src/registry/new-york/ui/dropzone.tsx
@@ -1,8 +1,5 @@
 "use client";
 
-import { mergeProps } from "@base-ui/react/merge-props";
-import { useRender } from "@base-ui/react/use-render";
-import { BanIcon, CheckCircle2Icon, UploadIcon } from "lucide-react";
 import * as React from "react";
 
 import { cn } from "@/lib/utils";
@@ -34,91 +31,6 @@ function DropzoneZone({
   );
 }
 
-function DropzoneUploadIcon({
-  className,
-  ...props
-}: React.ComponentProps<typeof UploadIcon>) {
-  return (
-    <>
-      <DropzonePrimitive.DragAccepted>
-        <CheckCircle2Icon
-          data-slot="dropzone-upload-icon-accepted"
-          className={cn("size-8", className)}
-          {...props}
-        />
-      </DropzonePrimitive.DragAccepted>
-      <DropzonePrimitive.DragRejected>
-        <BanIcon
-          data-slot="dropzone-upload-icon-rejected"
-          className={cn("size-8", className)}
-          {...props}
-        />
-      </DropzonePrimitive.DragRejected>
-      <DropzonePrimitive.DragDefault>
-        <UploadIcon
-          data-slot="dropzone-upload-icon-default"
-          className={cn("size-8", className)}
-          {...props}
-        />
-      </DropzonePrimitive.DragDefault>
-    </>
-  );
-}
-
-function DropzoneGroup({
-  className,
-  render,
-  ...props
-}: useRender.ComponentProps<"div">) {
-  return useRender({
-    render,
-    defaultTagName: "div",
-    props: mergeProps<"div">(
-      {
-        "data-slot": "dropzone-group",
-        className: cn("grid place-items-center gap-1.5", className),
-      } as React.ComponentProps<"div">,
-      props,
-    ),
-  });
-}
-
-function DropzoneTitle({
-  className,
-  render,
-  ...props
-}: useRender.ComponentProps<"h3">) {
-  return useRender({
-    render,
-    defaultTagName: "h3",
-    props: mergeProps<"h3">(
-      {
-        "data-slot": "dropzone-title",
-        className: cn("leading-none font-medium tracking-tight", className),
-      } as React.ComponentProps<"h3">,
-      props,
-    ),
-  });
-}
-
-function DropzoneDescription({
-  className,
-  render,
-  ...props
-}: useRender.ComponentProps<"p">) {
-  return useRender({
-    render,
-    defaultTagName: "p",
-    props: mergeProps<"p">(
-      {
-        "data-slot": "dropzone-description",
-        className: cn("text-muted-foreground text-sm", className),
-      } as React.ComponentProps<"p">,
-      props,
-    ),
-  });
-}
-
 function DropzoneTrigger(
   props: React.ComponentProps<typeof DropzonePrimitive.Trigger>,
 ) {
@@ -145,10 +57,6 @@ export {
   Dropzone,
   DropzoneInput,
   DropzoneZone,
-  DropzoneUploadIcon,
-  DropzoneGroup,
-  DropzoneTitle,
-  DropzoneDescription,
   DropzoneTrigger,
   DropzoneAccepted,
   DropzoneRejected,

From 46e1a8ebf69d35dc40905b9fb1904577db73633a Mon Sep 17 00:00:00 2001
From: junwen-k <40173716+junwen-k@users.noreply.github.com>
Date: Sun, 19 Jul 2026 16:06:51 +0800
Subject: [PATCH 5/9] refactor(dropzone): keep DropzoneUploadIcon for the
 drag-state swap
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Restore DropzoneUploadIcon as a thin, behavior-only wrapper. The icon
swap reads the primitive's drag context (DragAccepted/DragRejected/
DragDefault), so it's genuine Dropzone behavior rather than styling
Empty owns — the same principle DatePicker follows when it wraps
Calendar/DateField to bind primitive context. Title and description
stay composed with Empty directly.

Demos, docs and the changelog now render the icon via
<EmptyMedia variant="icon"><DropzoneUploadIcon /></EmptyMedia> instead
of inlining the primitive drag-state blocks.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 apps/v4/content/docs/changelog.mdx            |  2 +-
 apps/v4/content/docs/components/dropzone.mdx  | 20 ++++++++-----------
 .../src/components/examples/dropzone-demo.tsx | 14 +++----------
 .../src/components/examples/dropzone-form.tsx | 20 +++----------------
 .../components/examples/dropzone-trigger.tsx  | 14 ++-----------
 apps/v4/src/registry/new-york/ui/dropzone.tsx | 18 +++++++++++++++++
 6 files changed, 35 insertions(+), 53 deletions(-)

diff --git a/apps/v4/content/docs/changelog.mdx b/apps/v4/content/docs/changelog.mdx
index 53e1de9..b6bce6b 100644
--- a/apps/v4/content/docs/changelog.mdx
+++ b/apps/v4/content/docs/changelog.mdx
@@ -14,7 +14,7 @@ ui-x is now built on [Base UI](https://base-ui.com). Following shadcn/ui's adopt
 - **Base UI everywhere** — All Radix UI dependencies are gone. Components are built on Base UI primitives and utilities, with React 19 ref handling throughout.
 - **Restyled** — Every component, demo and docs page has been refreshed against the latest shadcn/ui styling.
 - **Simpler forms** — Demos use Base UI's `Field` and `Form` for form plumbing. For React Hook Form or TanStack Form wiring, see the shadcn/ui [forms guides](https://ui.shadcn.com/docs/forms).
-- **Dropzone composes with Empty** — `DropzoneGroup`, `DropzoneTitle`, `DropzoneDescription` and `DropzoneUploadIcon` are gone. Dropzone now only covers the interactive parts; build the zone's visual content with shadcn/ui's [Empty](https://ui.shadcn.com/docs/components/empty) component instead.
+- **Dropzone composes with Empty** — `DropzoneGroup`, `DropzoneTitle` and `DropzoneDescription` are gone. Build the zone's title and description with shadcn/ui's [Empty](https://ui.shadcn.com/docs/components/empty) component instead; `DropzoneUploadIcon` stays for the drag-state icon swap.
 
 ### Superseded components
 
diff --git a/apps/v4/content/docs/components/dropzone.mdx b/apps/v4/content/docs/components/dropzone.mdx
index 3f6b4a6..ce91add 100644
--- a/apps/v4/content/docs/components/dropzone.mdx
+++ b/apps/v4/content/docs/components/dropzone.mdx
@@ -82,9 +82,9 @@ import {
 import {
   Dropzone,
   DropzoneInput,
+  DropzoneUploadIcon,
   DropzoneZone,
 } from "@/components/ui/dropzone";
-import * as DropzonePrimitive from "@/components/ui/dropzone-primitive";
 ```
 
 ```tsx
@@ -100,15 +100,7 @@ import * as DropzonePrimitive from "@/components/ui/dropzone-primitive";
     <Empty>
       <EmptyHeader>
         <EmptyMedia variant="icon">
-          <DropzonePrimitive.DragAccepted>
-            <CheckCircle2Icon />
-          </DropzonePrimitive.DragAccepted>
-          <DropzonePrimitive.DragRejected>
-            <BanIcon />
-          </DropzonePrimitive.DragRejected>
-          <DropzonePrimitive.DragDefault>
-            <UploadIcon />
-          </DropzonePrimitive.DragDefault>
+          <DropzoneUploadIcon />
         </EmptyMedia>
         <EmptyTitle>Drop files here or click to upload</EmptyTitle>
         <EmptyDescription>
@@ -137,11 +129,11 @@ import * as DropzonePrimitive from "@/components/ui/dropzone-primitive";
 
 ## Accessibility
 
-The zone is focusable and opens the file dialog with <Kbd>Enter</Kbd> or <Kbd>Space</Kbd>, so the drag-and-drop interaction always has a keyboard equivalent. Make sure the zone contains visible text describing what to upload (such as `<EmptyTitle />` and `<EmptyDescription />`) — the upload icon alone is not an accessible name. Drag states are conveyed with color and iconography via the `<DragDefault />`/`<DragAccepted />`/`<DragRejected />` icon swap; keep the title text meaningful so the state change is not communicated by color alone.
+The zone is focusable and opens the file dialog with <Kbd>Enter</Kbd> or <Kbd>Space</Kbd>, so the drag-and-drop interaction always has a keyboard equivalent. Make sure the zone contains visible text describing what to upload (such as `<EmptyTitle />` and `<EmptyDescription />`) — the upload icon alone is not an accessible name. Drag states are conveyed with color and iconography via the `<DropzoneUploadIcon />` swap; keep the title text meaningful so the state change is not communicated by color alone.
 
 ## API Reference
 
-Styled wrappers around the [Dropzone primitive](/docs/primitives/dropzone#api-reference) — see the primitive page for the full prop tables. Visual content (icon, title, description) is composed with shadcn/ui's [Empty](https://ui.shadcn.com/docs/components/empty) component rather than a Dropzone-specific part.
+Styled wrappers around the [Dropzone primitive](/docs/primitives/dropzone#api-reference) — see the primitive page for the full prop tables. The zone's title and description are composed with shadcn/ui's [Empty](https://ui.shadcn.com/docs/components/empty) component rather than a Dropzone-specific part.
 
 ### Dropzone
 
@@ -155,6 +147,10 @@ Wraps [Zone](/docs/primitives/dropzone#zone) with dashed-border styling that rea
 
 Wraps [Input](/docs/primitives/dropzone#input), the visually hidden file input.
 
+### DropzoneUploadIcon
+
+Swaps the icon based on the drag state — an upload icon by default, a check when the drag is accepted and a ban icon when rejected. Render it inside `<EmptyMedia variant="icon" />`. Accepts the same props as a [Lucide](https://lucide.dev) icon.
+
 ### DropzoneTrigger
 
 Wraps [Trigger](/docs/primitives/dropzone#trigger) for opening the file dialog from a button outside the zone.
diff --git a/apps/v4/src/components/examples/dropzone-demo.tsx b/apps/v4/src/components/examples/dropzone-demo.tsx
index d6a1650..0d650f9 100644
--- a/apps/v4/src/components/examples/dropzone-demo.tsx
+++ b/apps/v4/src/components/examples/dropzone-demo.tsx
@@ -1,6 +1,6 @@
 "use client";
 
-import { BanIcon, CheckCircle2Icon, FileIcon, UploadIcon } from "lucide-react";
+import { FileIcon } from "lucide-react";
 import prettyBytes from "pretty-bytes";
 import * as React from "react";
 
@@ -21,9 +21,9 @@ import {
 import {
   Dropzone,
   DropzoneInput,
+  DropzoneUploadIcon,
   DropzoneZone,
 } from "@/registry/new-york/ui/dropzone";
-import * as DropzonePrimitive from "@/registry/new-york/ui/dropzone-primitive";
 
 export default function DropzoneDemo() {
   const [files, setFiles] = React.useState<File[]>([]);
@@ -42,15 +42,7 @@ export default function DropzoneDemo() {
           <Empty>
             <EmptyHeader>
               <EmptyMedia variant="icon">
-                <DropzonePrimitive.DragAccepted>
-                  <CheckCircle2Icon />
-                </DropzonePrimitive.DragAccepted>
-                <DropzonePrimitive.DragRejected>
-                  <BanIcon />
-                </DropzonePrimitive.DragRejected>
-                <DropzonePrimitive.DragDefault>
-                  <UploadIcon />
-                </DropzonePrimitive.DragDefault>
+                <DropzoneUploadIcon />
               </EmptyMedia>
               <EmptyTitle>Drop files here or click to upload</EmptyTitle>
               <EmptyDescription>
diff --git a/apps/v4/src/components/examples/dropzone-form.tsx b/apps/v4/src/components/examples/dropzone-form.tsx
index 8838b30..4bfdf14 100644
--- a/apps/v4/src/components/examples/dropzone-form.tsx
+++ b/apps/v4/src/components/examples/dropzone-form.tsx
@@ -1,12 +1,6 @@
 "use client";
 
-import {
-  BanIcon,
-  CheckCircle2Icon,
-  FileIcon,
-  UploadIcon,
-  XIcon,
-} from "lucide-react";
+import { FileIcon, XIcon } from "lucide-react";
 import prettyBytes from "pretty-bytes";
 import * as React from "react";
 import { ErrorCode } from "react-dropzone";
@@ -41,9 +35,9 @@ import { Field, FieldDescription, FieldLabel } from "@/components/ui/field";
 import {
   Dropzone,
   DropzoneInput,
+  DropzoneUploadIcon,
   DropzoneZone,
 } from "@/registry/new-york/ui/dropzone";
-import * as DropzonePrimitive from "@/registry/new-york/ui/dropzone-primitive";
 
 // 1 MB
 const MAX_FILE_SIZE = 1e6;
@@ -87,15 +81,7 @@ export default function DropzoneForm() {
                 <Empty>
                   <EmptyHeader className="flex-row items-center gap-6 text-left">
                     <EmptyMedia variant="icon">
-                      <DropzonePrimitive.DragAccepted>
-                        <CheckCircle2Icon />
-                      </DropzonePrimitive.DragAccepted>
-                      <DropzonePrimitive.DragRejected>
-                        <BanIcon />
-                      </DropzonePrimitive.DragRejected>
-                      <DropzonePrimitive.DragDefault>
-                        <UploadIcon />
-                      </DropzonePrimitive.DragDefault>
+                      <DropzoneUploadIcon />
                     </EmptyMedia>
                     <div className="grid gap-0.5">
                       <EmptyTitle>Browse to upload your file</EmptyTitle>
diff --git a/apps/v4/src/components/examples/dropzone-trigger.tsx b/apps/v4/src/components/examples/dropzone-trigger.tsx
index 1f75c01..1c221bc 100644
--- a/apps/v4/src/components/examples/dropzone-trigger.tsx
+++ b/apps/v4/src/components/examples/dropzone-trigger.tsx
@@ -1,5 +1,3 @@
-import { BanIcon, CheckCircle2Icon, UploadIcon } from "lucide-react";
-
 import { Button } from "@/components/ui/button";
 import {
   Empty,
@@ -13,9 +11,9 @@ import {
   Dropzone,
   DropzoneInput,
   DropzoneTrigger,
+  DropzoneUploadIcon,
   DropzoneZone,
 } from "@/registry/new-york/ui/dropzone";
-import * as DropzonePrimitive from "@/registry/new-york/ui/dropzone-primitive";
 
 export default function DropzoneTriggerDemo() {
   return (
@@ -25,15 +23,7 @@ export default function DropzoneTriggerDemo() {
         <Empty>
           <EmptyHeader>
             <EmptyMedia variant="icon">
-              <DropzonePrimitive.DragAccepted>
-                <CheckCircle2Icon />
-              </DropzonePrimitive.DragAccepted>
-              <DropzonePrimitive.DragRejected>
-                <BanIcon />
-              </DropzonePrimitive.DragRejected>
-              <DropzonePrimitive.DragDefault>
-                <UploadIcon />
-              </DropzonePrimitive.DragDefault>
+              <DropzoneUploadIcon />
             </EmptyMedia>
             <EmptyTitle>Drop files here</EmptyTitle>
             <EmptyDescription>
diff --git a/apps/v4/src/registry/new-york/ui/dropzone.tsx b/apps/v4/src/registry/new-york/ui/dropzone.tsx
index eb4d7ee..1984dc2 100644
--- a/apps/v4/src/registry/new-york/ui/dropzone.tsx
+++ b/apps/v4/src/registry/new-york/ui/dropzone.tsx
@@ -1,5 +1,6 @@
 "use client";
 
+import { BanIcon, CheckCircle2Icon, UploadIcon } from "lucide-react";
 import * as React from "react";
 
 import { cn } from "@/lib/utils";
@@ -31,6 +32,22 @@ function DropzoneZone({
   );
 }
 
+function DropzoneUploadIcon(props: React.ComponentProps<typeof UploadIcon>) {
+  return (
+    <>
+      <DropzonePrimitive.DragAccepted>
+        <CheckCircle2Icon data-slot="dropzone-upload-icon" {...props} />
+      </DropzonePrimitive.DragAccepted>
+      <DropzonePrimitive.DragRejected>
+        <BanIcon data-slot="dropzone-upload-icon" {...props} />
+      </DropzonePrimitive.DragRejected>
+      <DropzonePrimitive.DragDefault>
+        <UploadIcon data-slot="dropzone-upload-icon" {...props} />
+      </DropzonePrimitive.DragDefault>
+    </>
+  );
+}
+
 function DropzoneTrigger(
   props: React.ComponentProps<typeof DropzonePrimitive.Trigger>,
 ) {
@@ -57,6 +74,7 @@ export {
   Dropzone,
   DropzoneInput,
   DropzoneZone,
+  DropzoneUploadIcon,
   DropzoneTrigger,
   DropzoneAccepted,
   DropzoneRejected,

From 5d28a5a5c3a768d705fa37990fe18a6a48bd70b9 Mon Sep 17 00:00:00 2001
From: junwen-k <40173716+junwen-k@users.noreply.github.com>
Date: Sun, 19 Jul 2026 16:34:27 +0800
Subject: [PATCH 6/9] refactor(registry): compose cosmetic parts directly
 instead of re-exporting
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Drop the thin re-export wrappers that only renamed a data-slot without
adding behavior, styling, or a composed default — these are better
composed from the outside, matching how Date Picker already composes
InputGroup and Calendar directly.

- password-input: remove PasswordInputAdornment and the unused
  PasswordInputAdornmentButton; demos compose InputGroupAddon directly
- phone-input: remove PhoneInputCountrySelectTrigger; demos compose the
  styled SelectTrigger directly
- docs: update Usage, Accessibility and API Reference accordingly

Behavioral wrappers (PhoneInputCountrySelect/Value/Content, the toggle,
etc.) are unchanged — they wire context, styling or defaults and stay.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .../docs/components/password-input.mdx        |  6 +----
 .../content/docs/components/phone-input.mdx   |  9 ++++---
 apps/v4/src/components/card-demo-form.tsx     |  5 ++--
 .../examples/password-input-form.tsx          | 10 +++----
 .../components/examples/phone-input-demo.tsx  |  6 ++---
 .../examples/phone-input-separated.tsx        |  6 ++---
 .../registry/new-york/ui/password-input.tsx   | 26 +------------------
 .../src/registry/new-york/ui/phone-input.tsx  | 10 -------
 8 files changed, 20 insertions(+), 58 deletions(-)

diff --git a/apps/v4/content/docs/components/password-input.mdx b/apps/v4/content/docs/components/password-input.mdx
index 056e2cc..1fdc716 100644
--- a/apps/v4/content/docs/components/password-input.mdx
+++ b/apps/v4/content/docs/components/password-input.mdx
@@ -86,7 +86,7 @@ The visibility toggle is icon-only — give it an accessible name, e.g. `<Passwo
 
 ## API Reference
 
-Styled wrappers around the [Password Input primitive](/docs/primitives/password-input#api-reference) — see the primitive page for the full prop tables.
+Styled wrappers around the [Password Input primitive](/docs/primitives/password-input#api-reference) — see the primitive page for the full prop tables. Custom adornments, such as a leading lock icon, are composed with shadcn/ui's [Input Group](https://ui.shadcn.com/docs/components/input-group) parts (`InputGroupAddon`, `InputGroupButton`) rather than Password Input-specific parts.
 
 ### PasswordInput
 
@@ -99,7 +99,3 @@ Wraps [Input](/docs/primitives/password-input#input) with input-group styling. A
 ### PasswordInputAdornmentToggle
 
 Wraps [Toggle](/docs/primitives/password-input#toggle) as an icon button in the trailing addon, swapping the eye icon based on the visibility state.
-
-### PasswordInputAdornment, PasswordInputAdornmentButton
-
-Input-group addon and icon-button parts for composing custom adornments, e.g. a leading lock icon or a custom toggle.
diff --git a/apps/v4/content/docs/components/phone-input.mdx b/apps/v4/content/docs/components/phone-input.mdx
index a1f5301..138ab1d 100644
--- a/apps/v4/content/docs/components/phone-input.mdx
+++ b/apps/v4/content/docs/components/phone-input.mdx
@@ -58,15 +58,16 @@ See installation instructions for the [PhoneInputPrimitive](/docs/primitives/pho
 ## Usage
 
 ```tsx
+import { SelectTrigger } from "@/components/ui/select";
 import { PhoneInput } from "@/components/ui/phone-input";
 ```
 
 ```tsx
 <PhoneInput>
   <PhoneInputCountrySelect>
-    <PhoneInputCountrySelectTrigger>
+    <SelectTrigger>
       <PhoneInputCountrySelectValue />
-    </PhoneInputCountrySelectTrigger>
+    </SelectTrigger>
     <PhoneInputCountrySelectContent>
       <PhoneInputCountrySelectOptions />
     </PhoneInputCountrySelectContent>
@@ -95,7 +96,7 @@ import { PhoneInput } from "@/components/ui/phone-input";
 
 ## Accessibility
 
-The country select trigger shows only a flag — give it an accessible name, e.g. `<PhoneInputCountrySelectTrigger aria-label="Country" />`, and label the phone input itself like any text input (via `<Field>` / `<FieldLabel>` in forms or `aria-label`). Flags are decorative; each option in the dropdown carries the country's name as text, so the selection is not communicated by the flag alone.
+The country select trigger shows only a flag — give it an accessible name, e.g. `<SelectTrigger aria-label="Country" />`, and label the phone input itself like any text input (via `<Field>` / `<FieldLabel>` in forms or `aria-label`). Flags are decorative; each option in the dropdown carries the country's name as text, so the selection is not communicated by the flag alone.
 
 ## API Reference
 
@@ -111,7 +112,7 @@ Wraps [Input](/docs/primitives/phone-input#input), rendered as the styled [Input
 
 ### PhoneInputCountrySelect
 
-The country selector, built on the styled [Select](https://ui.shadcn.com/docs/components/select) and wired to the country state — `value` and `onValueChange` are managed for you. Compose it with `PhoneInputCountrySelectTrigger`, `PhoneInputCountrySelectValue` and `PhoneInputCountrySelectContent`, which accept the corresponding Select part props.
+The country selector, built on the styled [Select](https://ui.shadcn.com/docs/components/select) and wired to the country state — `value` and `onValueChange` are managed for you. Compose it with Select's own `SelectTrigger` plus `PhoneInputCountrySelectValue` and `PhoneInputCountrySelectContent`, which layer country-aware behavior over the corresponding Select parts.
 
 ### PhoneInputCountrySelectOptions
 
diff --git a/apps/v4/src/components/card-demo-form.tsx b/apps/v4/src/components/card-demo-form.tsx
index ff37f95..d1e29bb 100644
--- a/apps/v4/src/components/card-demo-form.tsx
+++ b/apps/v4/src/components/card-demo-form.tsx
@@ -30,7 +30,6 @@ import {
 } from "@/registry/new-york/ui/date-picker";
 import {
   PasswordInput,
-  PasswordInputAdornment,
   PasswordInputAdornmentToggle,
 } from "@/registry/new-york/ui/password-input";
 import { PasswordInputInput } from "@/registry/new-york/ui/password-input";
@@ -153,9 +152,9 @@ export function CardWithForm() {
               <Field data-invalid={fieldState.invalid}>
                 <FieldLabel htmlFor={field.name}>Password</FieldLabel>
                 <PasswordInput>
-                  <PasswordInputAdornment>
+                  <InputGroupAddon>
                     <LockKeyholeIcon />
-                  </PasswordInputAdornment>
+                  </InputGroupAddon>
                   <PasswordInputInput
                     id={field.name}
                     autoComplete="new-password"
diff --git a/apps/v4/src/components/examples/password-input-form.tsx b/apps/v4/src/components/examples/password-input-form.tsx
index 3465fe0..a4b1e9c 100644
--- a/apps/v4/src/components/examples/password-input-form.tsx
+++ b/apps/v4/src/components/examples/password-input-form.tsx
@@ -15,9 +15,9 @@ import {
   FieldGroup,
   FieldLabel,
 } from "@/components/ui/field";
+import { InputGroupAddon } from "@/components/ui/input-group";
 import {
   PasswordInput,
-  PasswordInputAdornment,
   PasswordInputAdornmentToggle,
   PasswordInputInput,
 } from "@/registry/new-york/ui/password-input";
@@ -38,9 +38,9 @@ export default function PasswordInputForm() {
               Password
             </FieldLabel>
             <PasswordInput>
-              <PasswordInputAdornment>
+              <InputGroupAddon>
                 <LockKeyhole />
-              </PasswordInputAdornment>
+              </InputGroupAddon>
               <PasswordInputInput
                 id="password-input-form-password"
                 autoComplete="new-password"
@@ -59,9 +59,9 @@ export default function PasswordInputForm() {
               Confirm Password
             </FieldLabel>
             <PasswordInput>
-              <PasswordInputAdornment>
+              <InputGroupAddon>
                 <LockKeyhole />
-              </PasswordInputAdornment>
+              </InputGroupAddon>
               <PasswordInputInput
                 id="password-input-form-confirm-password"
                 autoComplete="new-password"
diff --git a/apps/v4/src/components/examples/phone-input-demo.tsx b/apps/v4/src/components/examples/phone-input-demo.tsx
index e3e3324..fae7c11 100644
--- a/apps/v4/src/components/examples/phone-input-demo.tsx
+++ b/apps/v4/src/components/examples/phone-input-demo.tsx
@@ -4,12 +4,12 @@ import * as React from "react";
 
 import { ButtonGroup } from "@/components/ui/button-group";
 import { InputGroup, InputGroupInput } from "@/components/ui/input-group";
+import { SelectTrigger } from "@/components/ui/select";
 import {
   PhoneInput,
   PhoneInputCountrySelect,
   PhoneInputCountrySelectContent,
   PhoneInputCountrySelectOptions,
-  PhoneInputCountrySelectTrigger,
   PhoneInputCountrySelectValue,
 } from "@/registry/new-york/ui/phone-input";
 import * as PhoneInputPrimitive from "@/registry/new-york/ui/phone-input-primitive";
@@ -19,9 +19,9 @@ export default function PhoneInputDemo() {
     <PhoneInput>
       <ButtonGroup>
         <PhoneInputCountrySelect>
-          <PhoneInputCountrySelectTrigger>
+          <SelectTrigger>
             <PhoneInputCountrySelectValue />
-          </PhoneInputCountrySelectTrigger>
+          </SelectTrigger>
           <PhoneInputCountrySelectContent>
             <PhoneInputCountrySelectOptions />
           </PhoneInputCountrySelectContent>
diff --git a/apps/v4/src/components/examples/phone-input-separated.tsx b/apps/v4/src/components/examples/phone-input-separated.tsx
index 8204689..ff94001 100644
--- a/apps/v4/src/components/examples/phone-input-separated.tsx
+++ b/apps/v4/src/components/examples/phone-input-separated.tsx
@@ -9,13 +9,13 @@ import {
   InputGroupAddon,
   InputGroupInput,
 } from "@/components/ui/input-group";
+import { SelectTrigger } from "@/components/ui/select";
 import {
   Country,
   PhoneInput,
   PhoneInputCountrySelect,
   PhoneInputCountrySelectContent,
   PhoneInputCountrySelectOptions,
-  PhoneInputCountrySelectTrigger,
   PhoneInputCountrySelectValue,
 } from "@/registry/new-york/ui/phone-input";
 import * as PhoneInputPrimitive from "@/registry/new-york/ui/phone-input-primitive";
@@ -32,9 +32,9 @@ export default function PhoneInputSeparated() {
       <div className="flex flex-col gap-2">
         <div className="flex items-center gap-2">
           <PhoneInputCountrySelect>
-            <PhoneInputCountrySelectTrigger>
+            <SelectTrigger>
               <PhoneInputCountrySelectValue />
-            </PhoneInputCountrySelectTrigger>
+            </SelectTrigger>
             <PhoneInputCountrySelectContent>
               <PhoneInputCountrySelectOptions />
             </PhoneInputCountrySelectContent>
diff --git a/apps/v4/src/registry/new-york/ui/password-input.tsx b/apps/v4/src/registry/new-york/ui/password-input.tsx
index 07d6f0c..ac095b1 100644
--- a/apps/v4/src/registry/new-york/ui/password-input.tsx
+++ b/apps/v4/src/registry/new-york/ui/password-input.tsx
@@ -32,24 +32,6 @@ function PasswordInput({
   );
 }
 
-function PasswordInputAdornment(
-  props: React.ComponentProps<typeof InputGroupAddon>,
-) {
-  return <InputGroupAddon data-slot="password-input-adornment" {...props} />;
-}
-
-function PasswordInputAdornmentButton(
-  props: React.ComponentProps<typeof InputGroupButton>,
-) {
-  return (
-    <InputGroupButton
-      data-slot="password-input-adornment-button"
-      size="icon-xs"
-      {...props}
-    />
-  );
-}
-
 function PasswordInputInput(
   props: React.ComponentProps<typeof PasswordInputPrimitive.Input>,
 ) {
@@ -83,10 +65,4 @@ function PasswordInputAdornmentToggle({
   );
 }
 
-export {
-  PasswordInput,
-  PasswordInputAdornment,
-  PasswordInputAdornmentButton,
-  PasswordInputInput,
-  PasswordInputAdornmentToggle,
-};
+export { PasswordInput, PasswordInputInput, PasswordInputAdornmentToggle };
diff --git a/apps/v4/src/registry/new-york/ui/phone-input.tsx b/apps/v4/src/registry/new-york/ui/phone-input.tsx
index 03c9ae5..2e0c9ae 100644
--- a/apps/v4/src/registry/new-york/ui/phone-input.tsx
+++ b/apps/v4/src/registry/new-york/ui/phone-input.tsx
@@ -12,7 +12,6 @@ import {
   Select,
   SelectContent,
   SelectItem,
-  SelectTrigger,
   SelectValue,
 } from "@/components/ui/select";
 import { cn } from "@/lib/utils";
@@ -106,14 +105,6 @@ function PhoneInputCountrySelectValue({
   );
 }
 
-function PhoneInputCountrySelectTrigger(
-  props: React.ComponentProps<typeof SelectTrigger>,
-) {
-  return (
-    <SelectTrigger data-slot="phone-input-country-select-trigger" {...props} />
-  );
-}
-
 function PhoneInputCountrySelectContent({
   className,
   ...props
@@ -224,6 +215,5 @@ export {
   PhoneInputCountrySelectInternationalItem,
   PhoneInputCountrySelectItem,
   PhoneInputCountrySelectOptions,
-  PhoneInputCountrySelectTrigger,
   PhoneInputCountrySelectValue,
 };

From 813e0b9324017a646576001f65b62d52dc5018b3 Mon Sep 17 00:00:00 2001
From: junwen-k <40173716+junwen-k@users.noreply.github.com>
Date: Sun, 19 Jul 2026 16:58:38 +0800
Subject: [PATCH 7/9] docs: add AGENTS.md guide and wire up the shadcn MCP
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Capture the project philosophy and API-design rules as the default prompt
for agents and contributors: ui-x as a natural extension of shadcn (not a
fork), Base UI + base-nova only, the primitive/styled two-layer
architecture, and — front and center — the wrapping principle (wrap +
re-export only for behavior/styling/composed defaults; compose cosmetic
parts from the outside) that the component audit produced.

Also add .mcp.json so agents get live shadcn registry access.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .mcp.json |   8 +++
 AGENTS.md | 192 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 200 insertions(+)
 create mode 100644 .mcp.json
 create mode 100644 AGENTS.md

diff --git a/.mcp.json b/.mcp.json
new file mode 100644
index 0000000..9d30c31
--- /dev/null
+++ b/.mcp.json
@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "shadcn": {
+      "command": "npx",
+      "args": ["shadcn@latest", "mcp"]
+    }
+  }
+}
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..645d4ce
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,192 @@
+# AGENTS.md
+
+Guidance for AI agents (and humans) working in **junwen-k/ui-x**. Read this
+before writing code. It encodes the philosophy and the API-design rules that
+keep this registry coherent — follow them by default, and only deviate with a
+stated reason.
+
+---
+
+## What this project is
+
+ui-x is a **shadcn-style component registry** — a natural extension of
+[shadcn/ui](https://ui.shadcn.com), not a fork of it. We ship the components
+shadcn doesn't (yet) have, built and styled so they feel like they came from
+shadcn itself. A user should be able to `npx shadcn add` one of ours next to
+theirs and not feel a seam.
+
+Consequences of that stance:
+
+- **Compose shadcn, don't reinvent it.** If shadcn ships a component, we depend
+  on it — we never copy or restyle it. When shadcn ships a first-class version
+  of something we filled in, that component is **superseded** and removed in
+  favor of the official one (see `apps/v4/content/docs/changelog.mdx`).
+- **Match shadcn's conventions exactly** — `data-slot` attributes, CVA variants,
+  `render`-prop composition, file layout, naming, prose tone. When unsure how to
+  do something, find the closest shadcn/ui component and mirror it.
+- The live registry and roadmap of the overhaul live in `ROADMAP.md`. Consult it
+  for what's planned, done, or frozen; don't duplicate its contents elsewhere.
+
+---
+
+## Non-negotiables
+
+- **Base UI only.** Every primitive is built on [Base UI](https://base-ui.com).
+  Radix is gone — never add a `@radix-ui/*` dependency or reintroduce Radix
+  patterns.
+- **One style: `base-nova`.** It's set in `apps/v4/components.json`. There is no
+  `new-york-v4` variant to target. (The on-disk folder is still named
+  `new-york/` for historical reasons — the _style_ is `base-nova`.)
+- **Never hand-transcribe shadcn classes.** To pull in a shadcn core component,
+  use the CLI: `npx shadcn@latest add <name>`. It resolves to the correct
+  `base-nova` payload. Base-nova payloads sometimes run ahead of the released
+  Tailwind CSS (new `cn-*` utilities) — if you must vendor a class, verify it
+  exists in the released `tailwind.css` first.
+- **Conventional Commits**, enforced by commitlint on every commit. Type the
+  message to pass (`feat:`, `fix:`, `refactor:`, `docs:`, `chore:` …).
+- **Never self-merge a PR.** Branch, push, open the PR, and leave it for the
+  maintainer. Never force-push or run destructive git without explicit
+  confirmation.
+- **Verify frozen/remote state directly** rather than assuming it. Read the file,
+  check the branch, look at the registry.
+
+---
+
+## Architecture: primitive + styled, two layers
+
+Almost every component is two registry items:
+
+| Layer         | File                                            | Type          | Contains                                                                  |
+| ------------- | ----------------------------------------------- | ------------- | ------------------------------------------------------------------------- |
+| **Primitive** | `src/registry/new-york/ui/<name>-primitive.tsx` | `registry:ui` | Unstyled Base UI behavior. `data-slot`s, context/hooks, zero shadcn deps. |
+| **Styled**    | `src/registry/new-york/ui/<name>.tsx`           | `registry:ui` | Composes shadcn core + the primitive into the styled component.           |
+
+Import boundaries — keep these straight:
+
+- **shadcn core** → `@/components/ui/*` (lives in `apps/v4/src/components/ui/`,
+  added via the CLI, **not** part of our registry).
+- **ui-x components & primitives** → `@/registry/new-york/{ui,components}/*`
+  (our published registry).
+- **Demos** import the styled component from `@/registry/new-york/ui/<name>`.
+
+`apps/v4/src/registry/new-york/ui/date-picker.tsx` is the gold-standard
+reference — study it before designing a new component.
+
+---
+
+## The wrapping principle (the core API rule)
+
+When you expose a sub-component, decide deliberately between **wrapping and
+re-exporting** vs. **composing from the outside**. Get this right; it's what
+keeps the API honest.
+
+> **Wrap + re-export only when the wrapper earns it — behavior, styling, or a
+> composed default. If it's purely cosmetic (a `data-slot` rename over someone
+> else's part), don't wrap it; let the consumer compose that part directly.**
+
+**Wrap it (keep the wrapper)** when it:
+
+- reads your primitive's context or a hook (`useDatePicker`, `usePhoneInput`,
+  drag state);
+- binds a primitive part via `render` (`<Primitive.Input render={<Input />} />`);
+- adds meaningful styling (`w-auto` on the content, heavy item styling);
+- ships a composed default (a placeholder, an icon that swaps on state).
+
+**Compose from the outside (no wrapper)** when the "wrapper" would only rename a
+`data-slot` on a part that belongs to a _different_ component — shadcn core,
+another ui-x component, or a third-party lib. That's a cosmetic re-export; it
+adds indirection and a maintenance surface for nothing. Export nothing; let the
+consumer import the real part.
+
+**The test:** _Remove the wrapper and inline the part it wraps. Does anything
+change besides the `data-slot` string?_ No → delete the wrapper. Yes → keep it.
+
+**Concrete precedents in this repo:**
+
+- ✅ `DatePickerAnchor` → wraps _its own_ `DatePickerPrimitive.Anchor` with a
+  `data-slot`. Wrapping your own primitive's part is the architecture — always fine.
+- ✅ `PhoneInputCountrySelect` / `…Value` / `…Content` — wire `usePhoneInput`,
+  add a composed flag placeholder, add `w-auto`. Behavioral → keep.
+- ✅ `DropzoneUploadIcon` — swaps the icon on drag state. Behavioral → keep.
+- ✅ `DateField*` / `TimeField*` — re-export `DateTimeField*` with a curated
+  subset and a separator default (`/`, `:`). The rename _is_ the deliverable
+  (two mutually-consistent presets) → keep.
+- ❌ `PasswordInputAdornment` (removed) — was just `<InputGroupAddon data-slot=… />`.
+  Consumers now use `InputGroupAddon` directly.
+- ❌ `PhoneInputCountrySelectTrigger` (removed) — was just `<SelectTrigger data-slot=… />`.
+  Consumers now use `SelectTrigger` directly.
+
+When you drop or add a sub-component, update in lockstep: the demos
+(`src/components/examples/`), the docs (Usage, Anatomy, API Reference,
+Accessibility), and — if a part disappears — the changelog.
+
+---
+
+## Registry conventions
+
+Each item is declared in `apps/v4/registry.json`:
+
+- `dependencies` — npm packages (`@base-ui/react`, `timescape`, …).
+- `registryDependencies` — **shadcn core as plain strings** (`"input-group"`,
+  `"button"`, `"empty"`, `"select"`); **ui-x-internal as** `"junwen-k/ui-x/<name>"`.
+- A styled component lists both its primitive (`junwen-k/ui-x/<name>-primitive`)
+  and every shadcn core part it composes.
+
+Validate after any registry change:
+
+```bash
+cd apps/v4 && pnpm registry:validate
+```
+
+---
+
+## Docs conventions
+
+Docs are fumadocs MDX under `apps/v4/content/docs/`:
+
+- **Component pages** (`components/*.mdx`): Installation (CLI + Manual),
+  Usage, Examples (each an `<ComponentPreview name="…" />` mapping to a file in
+  `src/components/examples/`), Accessibility, API Reference.
+- **Primitive pages** (`primitives/*.mdx`): document the unstyled layer with full
+  prop tables. The styled API Reference links back to it rather than repeating props.
+- **Primitives stay unstyled in their demos.** Don't dress a primitive demo up to
+  look like its styled sibling — keep the markup plain and add the "Unstyled" callout.
+- **Forms are library-agnostic.** Component Form sections show Base UI
+  `Field`/`Form` markup; React Hook Form / TanStack wiring lives in shadcn's
+  central [forms guides](https://ui.shadcn.com/docs/forms), which we link to.
+- In form demos, pass controlled values as `field.value ?? null` so Base UI's
+  `useControlled` never flips between controlled/uncontrolled modes.
+- **Tone:** no maintenance promises, no "as-is" laundry lists — prefer a
+  clean-cut when something is superseded. Keep the changelog to meaningful
+  releases, not piecemeal per-part entries.
+
+---
+
+## Workflow for a change
+
+1. **Understand first.** Find the nearest shadcn/ui precedent and the nearest
+   in-repo precedent (start from `date-picker.tsx`). Use the **shadcn MCP**
+   (configured in `.mcp.json`) to search/view/pull registry items and examples
+   live.
+2. **Design the API** against the wrapping principle above before writing code.
+3. **Implement** — primitive first if new, then the styled layer, then update
+   `registry.json`, demos, and docs in lockstep.
+4. **Verify** (run all three from `apps/v4/`):
+   ```bash
+   npx tsc --noEmit          # types
+   pnpm lint                 # 0 errors expected (a few known warnings pre-exist)
+   pnpm registry:validate    # registry integrity
+   ```
+   Then eyeball the affected doc pages on the dev server (`pnpm dev`, :3000).
+5. **Commit** with a Conventional Commit message; **branch and open a PR** — do
+   not merge it yourself.
+
+---
+
+## Tooling
+
+- **shadcn MCP** (`.mcp.json`): live registry access — `search_items_in_registries`,
+  `view_items_in_registries`, `get_item_examples_from_registries`. Prefer it over
+  guessing at a component's shape or classes.
+- **shadcn CLI**: `npx shadcn@latest add <name>` to bring a core component into
+  `src/components/ui/`; `npx shadcn@latest docs <name>` for its docs.

From 4d5aa34c6c1a9dc748cd776cb76f5e654b054553 Mon Sep 17 00:00:00 2001
From: junwen-k <40173716+junwen-k@users.noreply.github.com>
Date: Sun, 19 Jul 2026 20:16:13 +0800
Subject: [PATCH 8/9] docs: correct AGENTS.md component model and tighten
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Not every component is primitive + styled: document the three real
  shapes (styled composition, primitive+styled, library-adapter primitive).
- Lead with the library-first philosophy — lean on popular headless
  libraries (react-dropzone, react-phone-number-input, timescape, …) and
  only author behavior on Base UI when none fits.
- Reframe "Base UI only" as "Base UI, not Radix" (we do use domain libs).
- Trim verbosity and soften the rulebook tone into principles + a short
  hard-rules list.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 AGENTS.md | 258 +++++++++++++++++++++++-------------------------------
 1 file changed, 109 insertions(+), 149 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 645d4ce..e3dd57d 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,192 +1,152 @@
 # AGENTS.md
 
-Guidance for AI agents (and humans) working in **junwen-k/ui-x**. Read this
-before writing code. It encodes the philosophy and the API-design rules that
-keep this registry coherent — follow them by default, and only deviate with a
-stated reason.
+Guidance for AI agents (and humans) working in **junwen-k/ui-x**. These are
+principles to apply with judgment, not boxes to tick — when a case doesn't fit,
+reason from the "why" here and say so.
 
 ---
 
 ## What this project is
 
 ui-x is a **shadcn-style component registry** — a natural extension of
-[shadcn/ui](https://ui.shadcn.com), not a fork of it. We ship the components
-shadcn doesn't (yet) have, built and styled so they feel like they came from
-shadcn itself. A user should be able to `npx shadcn add` one of ours next to
-theirs and not feel a seam.
-
-Consequences of that stance:
-
-- **Compose shadcn, don't reinvent it.** If shadcn ships a component, we depend
-  on it — we never copy or restyle it. When shadcn ships a first-class version
-  of something we filled in, that component is **superseded** and removed in
-  favor of the official one (see `apps/v4/content/docs/changelog.mdx`).
-- **Match shadcn's conventions exactly** — `data-slot` attributes, CVA variants,
-  `render`-prop composition, file layout, naming, prose tone. When unsure how to
-  do something, find the closest shadcn/ui component and mirror it.
-- The live registry and roadmap of the overhaul live in `ROADMAP.md`. Consult it
-  for what's planned, done, or frozen; don't duplicate its contents elsewhere.
+[shadcn/ui](https://ui.shadcn.com), not a fork. We ship the components shadcn
+doesn't (yet) have, built and styled so they feel like they came from shadcn
+itself: a user should be able to `npx shadcn add` one of ours next to theirs and
+not feel a seam.
+
+Everything below follows from that stance.
 
 ---
 
-## Non-negotiables
-
-- **Base UI only.** Every primitive is built on [Base UI](https://base-ui.com).
-  Radix is gone — never add a `@radix-ui/*` dependency or reintroduce Radix
-  patterns.
-- **One style: `base-nova`.** It's set in `apps/v4/components.json`. There is no
-  `new-york-v4` variant to target. (The on-disk folder is still named
-  `new-york/` for historical reasons — the _style_ is `base-nova`.)
-- **Never hand-transcribe shadcn classes.** To pull in a shadcn core component,
-  use the CLI: `npx shadcn@latest add <name>`. It resolves to the correct
-  `base-nova` payload. Base-nova payloads sometimes run ahead of the released
-  Tailwind CSS (new `cn-*` utilities) — if you must vendor a class, verify it
-  exists in the released `tailwind.css` first.
-- **Conventional Commits**, enforced by commitlint on every commit. Type the
-  message to pass (`feat:`, `fix:`, `refactor:`, `docs:`, `chore:` …).
-- **Never self-merge a PR.** Branch, push, open the PR, and leave it for the
-  maintainer. Never force-push or run destructive git without explicit
-  confirmation.
-- **Verify frozen/remote state directly** rather than assuming it. Read the file,
-  check the branch, look at the registry.
+## Principles
+
+- **Compose shadcn, don't reinvent it.** Depend on shadcn's components; never
+  copy or restyle them. When shadcn ships a first-class version of something we
+  filled in, that component is **superseded** and removed in favor of the
+  official one (see `apps/v4/content/docs/changelog.mdx`).
+- **Lean on great headless libraries; author behavior only when none exists.**
+  Reach for a popular, well-maintained headless library before writing
+  interaction logic yourself — `react-dropzone`, `react-phone-number-input`,
+  `timescape`, `react-day-picker`, `@dnd-kit`, `frimousse`, `virtua`. We hand-
+  author behavior (on [Base UI](https://base-ui.com)) only where no good library
+  fits — e.g. the password visibility toggle.
+- **Match shadcn's conventions.** `data-slot` attributes, CVA variants,
+  `render`-prop composition, file layout, naming, prose tone. Unsure how to do
+  something? Find the closest shadcn/ui component and mirror it.
+- **Model the API deliberately** — see [the wrapping principle](#the-wrapping-principle),
+  the one rule most worth getting right.
+
+## Hard rules
+
+- **Base UI, never Radix.** Base UI is the headless foundation shadcn moved to;
+  it's what we build on when we author unstyled behavior. Never add `@radix-ui/*`.
+- **One style: `base-nova`** (set in `apps/v4/components.json`). Pull shadcn core
+  in via the CLI — `npx shadcn@latest add <name>` — never hand-transcribe
+  classes. Base-nova payloads sometimes run ahead of the released Tailwind CSS
+  (new `cn-*` utilities); if you must vendor a class, confirm it exists in the
+  released `tailwind.css` first.
+- **Conventional Commits**, enforced by commitlint.
+- **Never self-merge a PR**, force-push, or run destructive git without explicit
+  confirmation. Branch, push, open the PR, leave it for the maintainer.
+- **Verify state directly** — read the file, check the branch — rather than
+  assuming what's frozen or already done.
 
 ---
 
-## Architecture: primitive + styled, two layers
-
-Almost every component is two registry items:
+## How components are built
 
-| Layer         | File                                            | Type          | Contains                                                                  |
-| ------------- | ----------------------------------------------- | ------------- | ------------------------------------------------------------------------- |
-| **Primitive** | `src/registry/new-york/ui/<name>-primitive.tsx` | `registry:ui` | Unstyled Base UI behavior. `data-slot`s, context/hooks, zero shadcn deps. |
-| **Styled**    | `src/registry/new-york/ui/<name>.tsx`           | `registry:ui` | Composes shadcn core + the primitive into the styled component.           |
+There's no single mold. A component takes the simplest shape that fits:
 
-Import boundaries — keep these straight:
+- **Styled composition** — styling over shadcn core and/or a headless library,
+  composed directly, no separate primitive (`emoji-picker`, `sortable`,
+  `wheel-picker`, `confirmer`).
+- **Primitive + styled** — an unstyled `<name>-primitive.tsx` layer plus a
+  styled `<name>.tsx` that composes it with shadcn core. Author a primitive when
+  the headless behavior is worth publishing on its own — usually a thin
+  Base UI-flavored adapter over a library (`dropzone` → react-dropzone,
+  `phone-input` → react-phone-number-input, `date-time-field` → timescape), or
+  hand-written on Base UI when no library fits (`password-input`).
 
-- **shadcn core** → `@/components/ui/*` (lives in `apps/v4/src/components/ui/`,
-  added via the CLI, **not** part of our registry).
-- **ui-x components & primitives** → `@/registry/new-york/{ui,components}/*`
-  (our published registry).
-- **Demos** import the styled component from `@/registry/new-york/ui/<name>`.
+`apps/v4/src/registry/new-york/ui/date-picker.tsx` is the reference to study
+before designing a new component.
 
-`apps/v4/src/registry/new-york/ui/date-picker.tsx` is the gold-standard
-reference — study it before designing a new component.
+**Import boundaries:**
 
----
+- shadcn core → `@/components/ui/*` (added via CLI; **not** part of our registry).
+- ui-x components & primitives → `@/registry/new-york/{ui,components}/*`.
+- Demos import the styled component from `@/registry/new-york/ui/<name>`.
 
-## The wrapping principle (the core API rule)
+(The folder is named `new-york/` for historical reasons — the _style_ is `base-nova`.)
 
-When you expose a sub-component, decide deliberately between **wrapping and
-re-exporting** vs. **composing from the outside**. Get this right; it's what
-keeps the API honest.
+---
 
-> **Wrap + re-export only when the wrapper earns it — behavior, styling, or a
-> composed default. If it's purely cosmetic (a `data-slot` rename over someone
-> else's part), don't wrap it; let the consumer compose that part directly.**
+## The wrapping principle
 
-**Wrap it (keep the wrapper)** when it:
+When you expose a sub-component, choose deliberately between **wrapping and
+re-exporting** a part vs. letting the consumer **compose it from the outside**.
 
-- reads your primitive's context or a hook (`useDatePicker`, `usePhoneInput`,
-  drag state);
-- binds a primitive part via `render` (`<Primitive.Input render={<Input />} />`);
-- adds meaningful styling (`w-auto` on the content, heavy item styling);
-- ships a composed default (a placeholder, an icon that swaps on state).
+> Wrap + re-export only when the wrapper earns it — behavior, styling, or a
+> composed default. A wrapper that only renames a `data-slot` on a part that
+> belongs to something else (shadcn core, another ui-x component, a library) is
+> cosmetic indirection; drop it and let the consumer use the part directly.
 
-**Compose from the outside (no wrapper)** when the "wrapper" would only rename a
-`data-slot` on a part that belongs to a _different_ component — shadcn core,
-another ui-x component, or a third-party lib. That's a cosmetic re-export; it
-adds indirection and a maintenance surface for nothing. Export nothing; let the
-consumer import the real part.
+**The test:** remove the wrapper and inline the part. Does anything change
+besides the `data-slot` string? No → delete it. Yes → keep it.
 
-**The test:** _Remove the wrapper and inline the part it wraps. Does anything
-change besides the `data-slot` string?_ No → delete the wrapper. Yes → keep it.
+Worth keeping — earns its place by:
 
-**Concrete precedents in this repo:**
+- reading your primitive's context/hook (`useDatePicker`, `usePhoneInput`, drag state);
+- binding a primitive part via `render` (`<Primitive.Input render={<Input />} />`);
+- adding real styling (`w-auto`, heavy item styling) or a composed default (a
+  placeholder, a state-swapping icon).
 
-- ✅ `DatePickerAnchor` → wraps _its own_ `DatePickerPrimitive.Anchor` with a
-  `data-slot`. Wrapping your own primitive's part is the architecture — always fine.
-- ✅ `PhoneInputCountrySelect` / `…Value` / `…Content` — wire `usePhoneInput`,
-  add a composed flag placeholder, add `w-auto`. Behavioral → keep.
-- ✅ `DropzoneUploadIcon` — swaps the icon on drag state. Behavioral → keep.
-- ✅ `DateField*` / `TimeField*` — re-export `DateTimeField*` with a curated
-  subset and a separator default (`/`, `:`). The rename _is_ the deliverable
-  (two mutually-consistent presets) → keep.
-- ❌ `PasswordInputAdornment` (removed) — was just `<InputGroupAddon data-slot=… />`.
-  Consumers now use `InputGroupAddon` directly.
-- ❌ `PhoneInputCountrySelectTrigger` (removed) — was just `<SelectTrigger data-slot=… />`.
-  Consumers now use `SelectTrigger` directly.
+Precedents: `DropzoneUploadIcon` (swaps icon on drag state) and
+`PhoneInputCountrySelect*` (wire `usePhoneInput`, add a flag placeholder) stay;
+`PasswordInputAdornment` (was `<InputGroupAddon data-slot=… />`) and
+`PhoneInputCountrySelectTrigger` (was `<SelectTrigger data-slot=… />`) were
+removed — consumers compose `InputGroupAddon` / `SelectTrigger` directly.
 
-When you drop or add a sub-component, update in lockstep: the demos
-(`src/components/examples/`), the docs (Usage, Anatomy, API Reference,
-Accessibility), and — if a part disappears — the changelog.
+When you add or drop a part, update the demos, docs (Usage / API Reference /
+Accessibility), and — if a part disappears — the changelog, in lockstep.
 
 ---
 
-## Registry conventions
-
-Each item is declared in `apps/v4/registry.json`:
+## Registry & docs conventions
 
-- `dependencies` — npm packages (`@base-ui/react`, `timescape`, …).
-- `registryDependencies` — **shadcn core as plain strings** (`"input-group"`,
-  `"button"`, `"empty"`, `"select"`); **ui-x-internal as** `"junwen-k/ui-x/<name>"`.
-- A styled component lists both its primitive (`junwen-k/ui-x/<name>-primitive`)
-  and every shadcn core part it composes.
+Registry items live in `apps/v4/registry.json`:
 
-Validate after any registry change:
-
-```bash
-cd apps/v4 && pnpm registry:validate
-```
-
----
-
-## Docs conventions
+- `dependencies` — npm packages; `registryDependencies` — **shadcn core as plain
+  strings** (`"input-group"`, `"select"`), **ui-x-internal as
+  `"junwen-k/ui-x/<name>"`**. Validate with `cd apps/v4 && pnpm registry:validate`.
 
 Docs are fumadocs MDX under `apps/v4/content/docs/`:
 
-- **Component pages** (`components/*.mdx`): Installation (CLI + Manual),
-  Usage, Examples (each an `<ComponentPreview name="…" />` mapping to a file in
-  `src/components/examples/`), Accessibility, API Reference.
-- **Primitive pages** (`primitives/*.mdx`): document the unstyled layer with full
-  prop tables. The styled API Reference links back to it rather than repeating props.
-- **Primitives stay unstyled in their demos.** Don't dress a primitive demo up to
-  look like its styled sibling — keep the markup plain and add the "Unstyled" callout.
-- **Forms are library-agnostic.** Component Form sections show Base UI
-  `Field`/`Form` markup; React Hook Form / TanStack wiring lives in shadcn's
-  central [forms guides](https://ui.shadcn.com/docs/forms), which we link to.
-- In form demos, pass controlled values as `field.value ?? null` so Base UI's
-  `useControlled` never flips between controlled/uncontrolled modes.
-- **Tone:** no maintenance promises, no "as-is" laundry lists — prefer a
-  clean-cut when something is superseded. Keep the changelog to meaningful
-  releases, not piecemeal per-part entries.
+- Component pages carry Installation, Usage, Examples
+  (`<ComponentPreview name="…" />` → `src/components/examples/`), Accessibility,
+  API Reference. Primitive pages document the unstyled layer with full prop
+  tables; the styled API Reference links back rather than repeating them.
+- **Primitive demos stay unstyled** — plain markup plus the "Unstyled" callout.
+- **Forms are library-agnostic**: show Base UI `Field`/`Form` markup and link to
+  shadcn's [forms guides](https://ui.shadcn.com/docs/forms) for RHF/TanStack
+  wiring. In form demos pass `field.value ?? null` so Base UI's `useControlled`
+  never flips modes.
+- **Tone:** no maintenance promises, no "as-is" laundry lists, clean-cut over
+  keeping the superseded around; changelog tracks meaningful releases, not
+  per-part churn.
 
 ---
 
-## Workflow for a change
-
-1. **Understand first.** Find the nearest shadcn/ui precedent and the nearest
-   in-repo precedent (start from `date-picker.tsx`). Use the **shadcn MCP**
-   (configured in `.mcp.json`) to search/view/pull registry items and examples
-   live.
-2. **Design the API** against the wrapping principle above before writing code.
-3. **Implement** — primitive first if new, then the styled layer, then update
-   `registry.json`, demos, and docs in lockstep.
-4. **Verify** (run all three from `apps/v4/`):
-   ```bash
-   npx tsc --noEmit          # types
-   pnpm lint                 # 0 errors expected (a few known warnings pre-exist)
-   pnpm registry:validate    # registry integrity
-   ```
-   Then eyeball the affected doc pages on the dev server (`pnpm dev`, :3000).
-5. **Commit** with a Conventional Commit message; **branch and open a PR** — do
-   not merge it yourself.
+## Workflow & tooling
 
----
+Understand first (nearest shadcn and in-repo precedent) → design the API against
+the wrapping principle → implement (library or primitive as needed, then the
+styled layer, `registry.json`, demos, docs in lockstep) → verify → commit and
+open a PR.
 
-## Tooling
+Verify from `apps/v4/`: `npx tsc --noEmit`, `pnpm lint` (0 errors; a few known
+warnings pre-exist), `pnpm registry:validate`, then eyeball the affected pages on
+`pnpm dev` (:3000).
 
-- **shadcn MCP** (`.mcp.json`): live registry access — `search_items_in_registries`,
-  `view_items_in_registries`, `get_item_examples_from_registries`. Prefer it over
-  guessing at a component's shape or classes.
-- **shadcn CLI**: `npx shadcn@latest add <name>` to bring a core component into
-  `src/components/ui/`; `npx shadcn@latest docs <name>` for its docs.
+The **shadcn MCP** (`.mcp.json`) gives live registry access — prefer it over
+guessing a component's shape or classes. The **shadcn CLI** adds core components
+(`npx shadcn@latest add <name>`) and fetches docs (`npx shadcn@latest docs <name>`).

From 157f947fbe96afbb183e811610b27dcf4d0141c0 Mon Sep 17 00:00:00 2001
From: junwen-k <40173716+junwen-k@users.noreply.github.com>
Date: Sun, 19 Jul 2026 20:46:44 +0800
Subject: [PATCH 9/9] docs: add anatomy & API consistency section to AGENTS.md

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 AGENTS.md | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index e3dd57d..fac7943 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -80,6 +80,31 @@ before designing a new component.
 
 ---
 
+## Anatomy & API consistency
+
+A new component's API should feel like one a consumer already knows. Before
+naming anything, look at the closest shadcn primitive and the nearest ui-x
+sibling, and match them.
+
+- **Parts are `<Component><Part>`**, PascalCase, exported root-first in
+  composition order — the same tree the docs "Usage" block shows
+  (`PhoneInput` → `PhoneInputCountrySelect` → `PhoneInputCountrySelectContent`).
+- **`data-slot` is the kebab-case of the exported name** — nothing invented
+  (`PhoneInputCountrySelectValue` → `data-slot="phone-input-country-select-value"`).
+- **Reuse the established part vocabulary.** A surface is `*Content`, an opener
+  `*Trigger`, an option `*Item`, the selected display `*Value`, the field
+  `*Input`. Don't coin a new noun for a role that already has one — a consumer
+  should be able to guess a part's name from what it does.
+- **Mirror the underlying anatomy so composition transfers.** When a part wraps
+  a shadcn primitive, keep the same shape and let it compose with that
+  primitive's own parts — `PhoneInputCountrySelect` sits inside Select's own
+  `SelectTrigger`, so anyone who knows Select already knows this.
+
+When a new component and an existing one solve the same sub-problem, they should
+read the same way. Consistency across the set beats a locally clever API.
+
+---
+
 ## The wrapping principle
 
 When you expose a sub-component, choose deliberately between **wrapping and