docs(components): document the remaining nine Shadcn divergences — every tracked component now says why it diverges (#3059)

Completes the triage. All 17 locally-modified components now carry a
`localEdits` note; `--check` reports 0 UNDOCUMENTED.

None of the nine are droppable either. Like the first eight, every one is
a deliberate fix or API extension:

  command   ADR-0054 C4 `contentProps` + the `sr-only` DialogTitle Radix
            requires. Upstream drops each addition with its usages, so a
            sync deletes ~38 lines and still type-checks — verified.
  select    Wraps Root to swallow `onValueChange("")`. Radix's hidden
            native mirror registers options a commit after the trigger,
            so a value arriving mid-hydration echoes back empty and wipes
            the field, latching forms whose `visibleWhen` reads it (#2968).
  table     `containerClassName`, to stop the wrapper becoming a second
            height-unbounded scroll container inside DataTable.
  chart     `block … w-full` instead of `flex justify-center`, or
            ResponsiveContainer measures no width and charts draw axes
            with no marks (#1634, 9b16317); plus hand-written Recharts
            prop types that actually type-check (2e11aa7).
  sidebar   Tailwind v4 syntax, a `data-collapsible`-always-present
            refactor, and an `eslint-disable react-hooks/purity` the
            random skeleton width needs.
  badge     `whitespace-nowrap`, or CJK labels break per-character in a
            cramped table cell (objectui#2762 P0-1).
  slider    Forwards `aria-label` to the Thumb.
  sheet     `hideOverlay` prop.
  calendar  Tailwind v4 syntax on `--cell-size`.

Two claims I checked rather than asserted, because both could have
shipped as confident wrong statements:

- Removing sidebar's `eslint-disable` really does fail Lint — it is an
  error from `react-hooks/purity`, not a warning, and Lint gates CI.
- `theme(spacing.4)` → `1rem` is **cosmetic**, not a fix. Tailwind 4.3.3
  still resolves the v3 dot-notation, and both spellings compile to the
  identical `calc(var(--sidebar-width-icon) + 1rem)`. The note says so;
  only the `[--var]` → `(--var)` half of that migration is load-bearing.

Also corrects a misleading `--check` label. The counts are set
differences, so a locally-edited line appears on BOTH sides — once as
ours, once as the upstream original it replaced. Calling that "N upstream
line(s) pending" reads as updates waiting to be collected, which is how I
misread sidebar's 21 as reclaimable work; it is mostly the mirror image
of sidebar's own edits. Now "N not matching upstream verbatim". The
`outdated` bucket keeps its wording — there `localOnly` is 0, so the
count genuinely is new upstream work.

Manifest and script only; no component source changes.

Co-authored-by: Jack Zhuang <277994282+os-zhuang@users.noreply.github.com>
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>

Author: os-zhuang

packages/components/shadcn-components.json

@@ -53,7 +53,8 @@
     "badge": {
       "source": "https://ui.shadcn.com/r/styles/default/badge.json",
       "dependencies": [],
-      "registryDependencies": []
+      "registryDependencies": [],
+      "localEdits": "Adds `whitespace-nowrap`: a badge is a single-line pill by definition, and without it CJK labels (e.g. 待审批) break per-character inside a cramped table cell and stack vertically (objectui#2762 P0-1). The reasoning is also comment-documented in the file."
     },
     "breadcrumb": {
       "source": "https://ui.shadcn.com/r/styles/default/breadcrumb.json",
@@ -75,7 +76,8 @@
       ],
       "registryDependencies": [
         "button"
-      ]
+      ],
+      "localEdits": "Tailwind v4 syntax: upstream still ships v3’s `[--var]` arbitrary values, which on Tailwind 4.x compile to a bare custom-property name instead of `var(--var)` — invalid CSS that browsers drop. Applied repo-wide in 925051db6. Here it covers `h-`, `w-`, `px-`, `size-` and `max-w-` on `--cell-size`."
     },
     "card": {
       "source": "https://ui.shadcn.com/r/styles/default/card.json",
@@ -97,7 +99,8 @@
         "recharts",
         "lucide-react"
       ],
-      "registryDependencies": []
+      "registryDependencies": [],
+      "localEdits": "Three local edits. (1) The container is `block … w-full` rather than upstream’s `flex justify-center`: a flex box gives ResponsiveContainer no measurable width, so charts render axes but no marks (#1634, commit 9b163173b). (2) Tooltip/Legend props are hand-written instead of derived from Recharts’ own types, which did not type-check here (2e11aa72f). (3) Tailwind v4 syntax: upstream still ships v3’s `[--var]` arbitrary values, which on Tailwind 4.x compile to a bare custom-property name instead of `var(--var)` — invalid CSS that browsers drop. Applied repo-wide in 925051db6."
     },
     "checkbox": {
       "source": "https://ui.shadcn.com/r/styles/default/checkbox.json",
@@ -120,7 +123,8 @@
       ],
       "registryDependencies": [
         "dialog"
-      ]
+      ],
+      "localEdits": "Two local additions to CommandDialog. (1) `contentProps`, so callers can attach a stable locator/ARIA name to the underlying dialog element — a `data-testid` spread onto CommandDialog lands on the Radix Dialog root, which renders no DOM (ADR-0054 C4). (2) `sr-only` DialogTitle/DialogDescription, which Radix requires for an accessible name. Upstream has neither, and drops each addition together with its usages — so syncing deletes ~38 lines and still type-checks clean. Verified: `--update command --force` compiles."
     },
     "context-menu": {
       "source": "https://ui.shadcn.com/r/styles/default/context-menu.json",
@@ -248,7 +252,8 @@
       "dependencies": [
         "radix-ui"
       ],
-      "registryDependencies": []
+      "registryDependencies": [],
+      "localEdits": "Wraps SelectPrimitive.Root to swallow `onValueChange(\"\")`. Radix mirrors the value into a hidden native `<select>`; SelectContent registers its options a commit AFTER the trigger mounts, so a value arriving mid-hydration (an edit form whose record lands after first paint) finds no matching `<option>`, and Radix echoes back an empty string that silently wipes the field — latching the form when a `visibleWhen` predicate reads it (#2968). SelectItem rejects `value=\"\"`, so `\"\"` is never a real user choice. Also tailwind v4 syntax: upstream still ships v3’s `[--var]` arbitrary values, which on Tailwind 4.x compile to a bare custom-property name instead of `var(--var)` — invalid CSS that browsers drop. Applied repo-wide in 925051db6."
     },
     "separator": {
       "source": "https://ui.shadcn.com/r/styles/default/separator.json",
@@ -262,7 +267,8 @@
       "dependencies": [
         "radix-ui"
       ],
-      "registryDependencies": []
+      "registryDependencies": [],
+      "localEdits": "Adds a `hideOverlay` prop that suppresses `<SheetOverlay />`, for sheets that must not dim the page behind them. Upstream renders the overlay unconditionally."
     },
     "sidebar": {
       "source": "https://ui.shadcn.com/r/styles/default/sidebar.json",
@@ -275,7 +281,8 @@
         "sheet",
         "skeleton",
         "tooltip"
-      ]
+      ],
+      "localEdits": "Three systematic edits, not 24 independent ones. (1) Tailwind v4 syntax: upstream still ships v3’s `[--var]` arbitrary values, which on Tailwind 4.x compile to a bare custom-property name instead of `var(--var)` — invalid CSS that browsers drop. Applied repo-wide in 925051db6. (2) `theme(spacing.4)` → `1rem`: cosmetic only — verified that Tailwind 4.3.3 still resolves the v3 `theme()` dot-notation, and both spellings compile to the identical `calc(var(--sidebar-width-icon) + 1rem)`. Unlike (1) this one is NOT load-bearing; it is just avoiding a deprecated idiom. (3) `data-collapsible` is set unconditionally and each rule qualified with `group-data-[state=collapsed]:`, where upstream blanks the attribute when expanded — same result, but the attribute stays in the DOM for styling and test locators. Also carries an `eslint-disable react-hooks/purity` the skeleton’s random width needs under this repo’s lint config; syncing removes it and Lint fails."
     },
     "skeleton": {
       "source": "https://ui.shadcn.com/r/styles/default/skeleton.json",
@@ -287,7 +294,8 @@
       "dependencies": [
         "radix-ui"
       ],
-      "registryDependencies": []
+      "registryDependencies": [],
+      "localEdits": "Forwards `aria-label` to `SliderPrimitive.Thumb`. Upstream renders the Thumb with only a className, so the accessible name never reaches the element screen readers focus."
     },
     "sonner": {
       "source": "https://ui.shadcn.com/r/styles/default/sonner.json",
@@ -308,7 +316,8 @@
     "table": {
       "source": "https://ui.shadcn.com/r/styles/default/table.json",
       "dependencies": [],
-      "registryDependencies": []
+      "registryDependencies": [],
+      "localEdits": "Adds `containerClassName` to override the scroll-wrapper `<div>`. The wrapper is its own `overflow-auto` container by default; inside an already-bounded scroll region (DataTable’s `flex-1 min-h-0 overflow-auto`) that creates a SECOND, height-unbounded scroll container whose horizontal scrollbar sits below every row, reachable only after scrolling to the last one. `containerClassName=\"overflow-visible\"` hands both axes to the outer container. Rationale is spelled out in the file’s JSDoc."
     },
     "tabs": {
       "source": "https://ui.shadcn.com/r/styles/default/tabs.json",

scripts/shadcn-sync.js

@@ -256,7 +256,12 @@ async function checkComponent(name, manifest) {
         // `--update` refuses these; the local lines would be deleted.
         status = 'modified';
         message = `${localOnly.length} local line(s) upstream lacks — --update would refuse`;
-        if (upstreamOnly.length > 0) message += `, ${upstreamOnly.length} upstream line(s) pending`;
+        // Deliberately NOT "N updates available". Both counts are set
+        // differences, so a line we edited locally appears on both sides: once
+        // as ours, once as the upstream original it replaced. For a modified
+        // component this number is mostly the mirror image of its own local
+        // edits, not new upstream work waiting to be collected.
+        if (upstreamOnly.length > 0) message += `, ${upstreamOnly.length} not matching upstream verbatim`;
         // Divergence with a recorded reason is a decision; divergence without
         // one is an open question. Surfacing the split makes the untriaged
         // components a visible to-do instead of undifferentiated noise.