@assure-one/design-system 1.36.0 → 1.38.0

package/README.md

@@ -16,6 +16,7 @@ The single source of truth for visual design across all Assure products.
 - [**`docs/integration/css.md`**](./docs/integration/css.md) — how an application loads our CSS: layer order, import sequence, the compatibility preset, removing `@source`, runtime brand theming.
 - [**`docs/testing.md`**](./docs/testing.md) — rendering the real package in your app's Jest tests (`@assure-one/design-system/testing`, experimental).
 - [**`docs/forms.md`**](./docs/forms.md) — building a form: `Field` + design-system controls + a Server Action + zod, reset and `required`, what each control submits, and testing it with `fillField` / `selectOption` / `pickDate`.
+- [**`docs/data-tables.md`**](./docs/data-tables.md) — building a data table: the headless `useDataTable` controller (sorting, pagination, search, selection, column visibility, filters — each controllable), server `manual` mode, and the URL-state recipe.
 - [**`docs/design-system/icons.md`**](./docs/design-system/icons.md) — the icon catalogue and its server-safe entry (`@assure-one/design-system/icons`, experimental): import an icon in a Server Component without a client boundary.
 - [**`docs/adr/010-design-system-provider.md`**](./docs/adr/010-design-system-provider.md) — the optional `DesignSystemProvider` (messages, locale, link adapter) and the `/next` entry; the quick start is [below](#the-provider-and-the-next-entry-experimental).
 - [**`claude-skills/`**](./claude-skills) — drop-in Claude Code skill for consuming projects.
@@ -52,14 +53,14 @@ Alongside it, the package now also publishes the individual stylesheets the new
 CSS mode is built from. They are **experimental**: nothing requires them yet,
 no component reads them, and importing them changes nothing on its own.
 
-| Subpath | What it is |
-| --- | --- |
-| `./css/tokens.css` | The `--ds-*` design tokens: `:root`, the colour scheme scope and the brand scopes. Usable without any component. |
-| `./css/legacy-aliases.css` | Read-aliases from today's token names to the namespaced ones (`--color-surface: var(--ds-color-surface)`), for as long as your own CSS reads design-system token names. |
-| `./css/tailwind.css` | A Tailwind `@theme` bridge, so `bg-surface/40`, `hover:text-fg-3` and `rounded-control` compile in *your* build instead of silently producing nothing. |
-| `./css/shadcn.css` | The app-vocabulary bridge: `background`, `foreground`, `primary`, `muted`, `destructive`, the radius scale and the rest, each reading one `--app-*` input you can override. |
-| `./css/base.css` | Optional document defaults: body background, ink, font and `color-scheme`. Ships no preflight, no element rules and no font import. |
-| `./css/components.css` | The component utilities compiled with Tailwind's `ds` prefix (`ds:flex`, `ds:bg-surface`), inside `@layer ds` and bound to the `--ds-*` tokens. **Unused until the class-vocabulary flip (W1-11):** no component emits a prefixed class yet, so importing it styles nothing. Published so the file, its size and its hygiene can be reviewed before the flip. |
+| Subpath                    | What it is                                                                                                                                                                                                                                                                                                                                                    |
+| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `./css/tokens.css`         | The `--ds-*` design tokens: `:root`, the colour scheme scope and the brand scopes. Usable without any component.                                                                                                                                                                                                                                              |
+| `./css/legacy-aliases.css` | Read-aliases from today's token names to the namespaced ones (`--color-surface: var(--ds-color-surface)`), for as long as your own CSS reads design-system token names.                                                                                                                                                                                       |
+| `./css/tailwind.css`       | A Tailwind `@theme` bridge, so `bg-surface/40`, `hover:text-fg-3` and `rounded-control` compile in _your_ build instead of silently producing nothing.                                                                                                                                                                                                        |
+| `./css/shadcn.css`         | The app-vocabulary bridge: `background`, `foreground`, `primary`, `muted`, `destructive`, the radius scale and the rest, each reading one `--app-*` input you can override.                                                                                                                                                                                   |
+| `./css/base.css`           | Optional document defaults: body background, ink, font and `color-scheme`. Ships no preflight, no element rules and no font import.                                                                                                                                                                                                                           |
+| `./css/components.css`     | The component utilities compiled with Tailwind's `ds` prefix (`ds:flex`, `ds:bg-surface`), inside `@layer ds` and bound to the `--ds-*` tokens. **Unused until the class-vocabulary flip (W1-11):** no component emits a prefixed class yet, so importing it styles nothing. Published so the file, its size and its hygiene can be reviewed before the flip. |
 
 Import order is `tokens.css` → `legacy-aliases.css` (optional) → `tailwind.css`
 → `shadcn.css` (optional) → `base.css` (optional) → `components.css`, after your own
@@ -119,11 +120,11 @@ export default function RootLayout({ children }) {
 
 - **`messages`** — any subset of the typed catalogue `DsMessages`, by component
   namespace (`select`, `searchInput`, `combobox`, `field`, `fileUpload`; more
-  join as the overlays adopt it). Resolution is always *component prop >
-  provider > English default*, per key. The full English list is
+  join as the overlays adopt it). Resolution is always _component prop >
+  provider > English default_, per key. The full English list is
   `src/foundation/messages/en.json`; parameterised messages are functions
   (`combobox.create: (query) => string`).
-- **`locale`** — a BCP 47 tag, default `"en-US"` on the server *and* the client.
+- **`locale`** — a BCP 47 tag, default `"en-US"` on the server _and_ the client.
   Pass the locale your app already knows server-side; the design system never
   reads `navigator.language` during render, so server and client HTML agree.
 - **`linkComponent` / `imageComponent`** — what `LinkButton` and `Logo` render
@@ -136,6 +137,34 @@ export default function RootLayout({ children }) {
   the props. `toasts` mounts the toast region for `useToast()`; leave it off if
   you already render `ToastProvider`.
 
+## Lint configs for consumers
+
+Two shareable configs ship with the package (**experimental**, W7-18) so a
+product lints for the same things this repository ratchets on itself. Every
+rule is a **warning**: adopt it on the code you have, record the count, and
+ratchet it down.
+
+```js
+// eslint.config.mjs
+import ds from "@assure-one/design-system/eslint-config";
+export default [...ds.configs.recommended];
+
+// stylelint.config.mjs  (stylelint is yours — an optional peer dependency here)
+export { default } from "@assure-one/design-system/stylelint-config";
+```
+
+| Rule                                     | Reports                                                                                  |
+| ---------------------------------------- | ---------------------------------------------------------------------------------------- |
+| `ds/no-raw-controls`                     | raw `<button>`, `<input>`, `<select>`, `<textarea>` where a design-system control exists |
+| `ds/no-radix-imports`                    | a direct `@radix-ui/*` import instead of the primitive that wraps it                     |
+| `ds/no-deep-imports`                     | an import past the published entries (`dist/…`, `src/…` — ADR-011)                       |
+| `ds/no-ds-token-redefinition`            | a `--ds-*` token set inline, outside a file under `presets/`                             |
+| `assure-ds/no-ds-token-redefinition`     | the same in CSS (stylelint; `presets/` and `*.preset.css` are exempt)                    |
+| `assure-ds/no-important-on-ds-selectors` | `!important` on a `ds:`/`data-slot` selector — pass `className`/`classNames` instead     |
+
+Raise a rule to `"error"` in your own config once you are clean. Adoption per
+app is tracked as W7-19.
+
 ## Develop
 
 ```bash
@@ -153,11 +182,11 @@ See [`CONTRIBUTING.md`](./CONTRIBUTING.md) for the full dev loop, including iter
 3-tier token system, authored as DTCG JSON in [`tokens/src`](./tokens/README.md)
 and generated into `src/tokens/` and the `./css/*` entries (ADR-003):
 
-| Tier | Example (namespaced name → value) | Reads |
-| --- | --- | --- |
-| reference | `--ds-ref-brand-pro-fg: #6c42f8` | a literal; the raw ramps, one per brand |
-| system (semantic) | `--ds-color-action-brand-bg: var(--ds-ref-brand-pro-fg)` | the reference tier; **this is the public contract** |
-| component | `--ds-menu-item-hover-bg: var(--ds-color-canvas-sunken)` | the system tier; only where a component must be themable on its own |
+| Tier              | Example (namespaced name → value)                        | Reads                                                               |
+| ----------------- | -------------------------------------------------------- | ------------------------------------------------------------------- |
+| reference         | `--ds-ref-brand-pro-fg: #6c42f8`                         | a literal; the raw ramps, one per brand                             |
+| system (semantic) | `--ds-color-action-brand-bg: var(--ds-ref-brand-pro-fg)` | the reference tier; **this is the public contract**                 |
+| component         | `--ds-menu-item-hover-bg: var(--ds-color-canvas-sunken)` | the system tier; only where a component must be themable on its own |
 
 Components consume **system tokens**, never reference values directly. Themes
 (colour scheme, per-product brand, a runtime brand from `createBrandTheme()`)

package/codemods/README.md

@@ -110,6 +110,7 @@ the list a human has to pick up — spread props, dynamic expressions, conflicti
 | Id    | Class | What it does                                                                                                                                                                  |
 | ----- | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | CM-05 | A     | Button family `iconLeft` / `iconRight` → `iconStart` / `iconEnd` (pure rename; both names of one slot, spreads → "could not be transformed")                                  |
+| CM-13 | A     | `Tooltip delayMs` → `delayDuration` (pure rename, literal or dynamic value; both names, spreads → "could not be transformed")                                                 |
 | CM-07 | A     | `inputSize` → `size` on `Input`, `Textarea`, `SearchInput` (pure rename, literal or dynamic value; both names, spreads → "could not be transformed")                          |
 | CM-02 | A     | Button explicit default size: `size="md"` on every `Button`, `SubmitButton` and `LinkButton` that passes no `size` (pixel-neutral)                                            |
 | CM-04 | R     | Button family legacy `variant` → `variant` + `intent` pair (`primary` → `solid`, `destructive` → `solid` + `danger`, …); `accent`, `dashed`, dynamic → report                 |
@@ -118,6 +119,8 @@ the list a human has to pick up — spread props, dynamic expressions, conflicti
 | CM-12 | R     | Button `type="submit"` where the intent is evident (inside `<form>` in the same file, no `onClick`); everything else untyped → report                                         |
 | CM-10 | R     | `DatePicker onChange={e => f(e.target.value)}` → `onValueChange={value => f(value)}` for the recognisable arrow shapes; handlers by reference, other shapes → report          |
 | CM-08 | R     | `SearchSelect` → `Combobox`: single-mode call sites rewritten (tag, import, `{id,label}` accessors, placeholder → `aria-label`); multi API, extras and unnamed sites → report |
+| CM-09 | R     | `SideDrawer` → `Sheet`: drawers with a `SideDrawer.Header` rewritten (root → `Sheet` + `SheetContent side size`, `onClose` → `onOpenChange`, header → `SheetHeader`/`SheetTitle`/`SheetDescription`, Body/Footer → `SheetBody`/`SheetFooter`, import); no header, dynamic width, spreads → report |
+| CM-18 | A     | `DataTable*` presentational parts → `Table*` (`DataTableHead` → `TableHeader`, `Body`, `Row`, `Cell`, `DataTableHeader` → `TableHead`) where the mapping is 1:1; uncontrolled sorting, a dynamic `sortable` and spreads → "could not be transformed"                    |
 | CM-14 | X     | hidden-input mirror finder: hidden `<input name>` a consumer added because a design-system control posts nothing                                                              |
 | CM-15 | X     | DOM-selector finder: consumer code that depends on the internal DOM of design-system components, mapped to registry `C-DOM-*` ids                                             |
 | CM-16 | X     | `globals.css` analyser: `@source` into the package, duplicate preflight, colliding `@theme` keys, unlayered globals, legacy `var()`                                           |
@@ -149,6 +152,27 @@ the same slot, and which one wins depends on attribute order). Not touched and
 not reported: elements already on the new names, local components with the
 same names, test files.
 
+### CM-13 — `Tooltip delayMs` → `delayDuration`
+
+Class A. W5-12 made `delayMs` a deprecated alias of Radix's `delayDuration`
+on the design-system `Tooltip` (contract C-TOOLTIP-DELAY, removed in 3.0).
+Both name the same milliseconds and `delayDuration` wins when both are
+given, so the rename is behaviour-neutral and a pure rename: only the
+attribute's name is replaced, and its value — a literal or a dynamic
+`delayMs={slow ? 700 : 300}` — keeps its text and formatting. Aliased and
+namespace imports count.
+
+| rule            | Contract        | What happens                        |
+| --------------- | --------------- | ----------------------------------- |
+| `delay-renamed` | C-TOOLTIP-DELAY | `delayMs={…}` → `delayDuration={…}` |
+
+Not touched, and listed under "could not be transformed": an element that
+passes **both** `delayDuration` and `delayMs` (`delayDuration` already wins;
+a rename would make a duplicate attribute — delete `delayMs` by hand), and an
+element with a spread (`<Tooltip delayMs={300} {...props}>` — the spread may
+carry `delayDuration`). Not touched and not reported: elements already on
+`delayDuration`, local components called Tooltip, test files.
+
 ### CM-07 — `inputSize` → `size` on Input, Textarea, SearchInput
 
 Class A. W4-05/06/07 put the three text controls on the control scale:
@@ -440,6 +464,75 @@ reported for a human.
 Not touched: elements already on `Combobox` (idempotency), local components
 with the same name, test files.
 
+### CM-09 — `SideDrawer` → `Sheet`
+
+Class R. W5-08 made `SideDrawer` a deprecated adapter over `Sheet` (contract
+C-SIDEDRAWER, removed in 3.0). A drawer **with a `SideDrawer.Header`** is
+rewritten: the root becomes `Sheet` with `onOpenChange={(open) => !open &&
+onClose()}` (a handler by reference is called, an arrow with an expression
+body is inlined, anything else is called through `(expr)()`); the children
+move into a `SheetContent` that carries the `side` and the mapped `size`
+(`sm` → `sm`, `md` → `lg`; `lg` and the omitted default, 50vw, become `xl`
+and are reported); the header's `title` and `subtitle` become `SheetTitle` and
+`SheetDescription` inside `SheetHeader`; `SideDrawer.Body` / `.Footer` become
+`SheetBody` / `SheetFooter` with their `className`. A header that had its own
+`onClose` button hands the job to the sheet's built-in close button; one that
+had none gets `showCloseButton={false}`. The named import follows once no
+`SideDrawer` element is left in the file.
+
+| rule                | Contract     | What happens                                                                                                             |
+| ------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------ |
+| `renamed`           | C-SIDEDRAWER | root, content, parts and import rewritten (applied, low)                                                                 |
+| `width-approximate` | C-SIDEDRAWER | `width="lg"` or no `width` (50vw) → `size="xl"` (760px); set `--ds-sheet-width` for an exact width (applied, **medium**) |
+| `header-close`      | C-SIDEDRAWER | the header's close button is now the sheet's built-in one, last child of the content (applied, low)                      |
+| `rendering`         | C-SIDEDRAWER | the Sheet parts pad differently (`p-6` header and footer, `px-6` body) and draw no rules between them (applied, low)     |
+| `no-header`         | C-SIDEDRAWER | a drawer without `SideDrawer.Header` has no title to become the `SheetTitle`: left alone (review, high)                  |
+| `width-dynamic`     | C-SIDEDRAWER | `width={expr}` has no `size` step: left alone (review, high)                                                             |
+| `spread-props`      | C-SIDEDRAWER | `{...props}` on the drawer or a part may carry any of the above: left alone (review, medium)                             |
+
+Not touched: elements already on `Sheet` (idempotency), local components with
+the same name, test files. The rewritten children are re-indented one level;
+run the project's formatter afterwards.
+
+### CM-18 — `DataTable*` parts → `Table*`
+
+Class A. W6-03 made the `DataTable*` table parts aliases of the `Table*` parts
+(contract C-DT-PARTS, removed in 3.0): one styling source, the same props. The
+1:1 parts are a pure rename — tag, closing tag and the named import:
+
+| from              | to            |
+| ----------------- | ------------- |
+| `DataTableHead`   | `TableHeader` |
+| `DataTableBody`   | `TableBody`   |
+| `DataTableRow`    | `TableRow`    |
+| `DataTableCell`   | `TableCell`   |
+| `DataTableHeader` | `TableHead`   |
+
+`DataTableHeader sortable sort={…} onSortChange={…}` loses the `sortable`
+attribute: `TableHead` sorts whenever `sort` is passed (`null` = sortable, not
+sorted). What changes in the DOM is the `data-slot` value (`table-*` instead of
+`data-table-*`) and the dropped `scope="col"` — a `<th>` in a `<thead>` is a
+column header already. Classes and pixels are the same, because since W6-03 the
+`DataTable*` parts render the `Table*` parts.
+
+| rule            | Contract   | What happens                                                        |
+| --------------- | ---------- | ------------------------------------------------------------------- |
+| `part-renamed`  | C-DT-PARTS | tag, closing tag and the named import rewritten (applied, low)      |
+
+Reported under "could not be transformed": `DataTableHeader sortable` with no
+controlled `sort`, or with `defaultSort` (`uncontrolled-sort` — `TableHead` has
+no uncontrolled sort state; wire `sort` + `onSortChange`, e.g. from
+`useDataTable`); `sortable={expr}` (`dynamic-sortable`); a spread on the header
+(`spread-props`).
+
+Not touched: the parts that are not parallel copies of a `Table*` part —
+`DataTable` (the card frame), `DataTableToolbar`, `DataTableSearch`,
+`DataTableSpacer`, `DataTableResultsCount`, `DataTableCellName` / `CellMono` /
+`CellId` / `CellDue`, `DataTableCheckbox`, `DataTablePagination` — an aliased
+import (`DataTableCell as Cell`), a namespace import, local components with the
+same names, and test files. A file that still refers to the old name as a value
+(`typeof DataTableCell`) keeps its import and gains the new name next to it.
+
 ### CM-15 — DOM-selector finder
 
 Report-only. It never modifies a file; the runner throws if it tries. What it

package/codemods/lib/registry.mjs

@@ -4,6 +4,7 @@
  */
 export const CODEMODS = [
   { id: "CM-05", module: "../transforms/cm-05-button-icon-slots.mjs" },
+  { id: "CM-13", module: "../transforms/cm-13-tooltip-delay.mjs" },
   { id: "CM-07", module: "../transforms/cm-07-input-size.mjs" },
   { id: "CM-02", module: "../transforms/cm-02-button-explicit-size.mjs" },
   { id: "CM-04", module: "../transforms/cm-04-button-variant-intent.mjs" },
@@ -12,6 +13,8 @@ export const CODEMODS = [
   { id: "CM-12", module: "../transforms/cm-12-button-type-submit.mjs" },
   { id: "CM-10", module: "../transforms/cm-10-date-picker-value-change.mjs" },
   { id: "CM-08", module: "../transforms/cm-08-search-select-to-combobox.mjs" },
+  { id: "CM-09", module: "../transforms/cm-09-side-drawer-to-sheet.mjs" },
+  { id: "CM-18", module: "../transforms/cm-18-data-table-parts.mjs" },
   { id: "CM-14", module: "../transforms/cm-14-hidden-mirrors.mjs" },
   { id: "CM-15", module: "../transforms/cm-15-dom-selectors.mjs" },
   { id: "CM-16", module: "../transforms/cm-16-globals-css.mjs" },

package/codemods/transforms/cm-09-side-drawer-to-sheet.mjs

@@ -0,0 +1,348 @@
+/**
+ * CM-09 — `SideDrawer` → `Sheet` (class R; plan §29 seq 11, registry
+ * `C-SIDEDRAWER`, lands with W5-08).
+ *
+ * W5-08 turned `SideDrawer` into a deprecated adapter over `Sheet`. A drawer
+ * with a `SideDrawer.Header` is a mechanical rewrite onto the Sheet parts;
+ * what has no Sheet equivalent is reported for a human.
+ *
+ * ## What it rewrites
+ *
+ * ```tsx
+ * <SideDrawer open={open} onClose={onClose} width="md" side="left">
+ *   <SideDrawer.Header title={name} subtitle="…" onClose={onClose} />
+ *   <SideDrawer.Body className="…">…</SideDrawer.Body>
+ *   <SideDrawer.Footer>…</SideDrawer.Footer>
+ * </SideDrawer>
+ * ```
+ *
+ * becomes
+ *
+ * ```tsx
+ * <Sheet open={open} onOpenChange={(open) => !open && onClose()}>
+ *   <SheetContent side="left" size="lg">
+ *     <SheetHeader>
+ *       <SheetTitle>{name}</SheetTitle>
+ *       <SheetDescription>…</SheetDescription>
+ *     </SheetHeader>
+ *     <SheetBody className="…">…</SheetBody>
+ *     <SheetFooter>…</SheetFooter>
+ *   </SheetContent>
+ * </Sheet>
+ * ```
+ *
+ * - `onClose` → `onOpenChange`: a handler by reference is called, an arrow
+ *   with an expression body is inlined, anything else is called through
+ *   `(expr)()`
+ * - `width` → `size` on the content: `sm` → `sm` (420px), `md` → `lg`
+ *   (640px); `lg` (50vw) and the omitted default have no step and become
+ *   `xl` (760px), reported as `width-approximate`
+ * - `side` moves to the content
+ * - `SideDrawer.Header title subtitle` → `SheetHeader` with `SheetTitle` and
+ *   `SheetDescription`; the header's `onClose` is dropped because the sheet's
+ *   built-in close button (the last child of the content) closes through
+ *   `onOpenChange`; a header without `onClose` gets `showCloseButton={false}`
+ * - `SideDrawer.Body` → `SheetBody`, `SideDrawer.Footer` → `SheetFooter`
+ *   (`className` kept)
+ * - the named import follows when no `SideDrawer` element is left
+ *
+ * ## What it reports
+ *
+ * | rule                | action  | severity | why                                                                          |
+ * | ------------------- | ------- | -------- | ---------------------------------------------------------------------------- |
+ * | `renamed`           | applied | low      | root, content, parts and import rewritten                                    |
+ * | `width-approximate` | applied | medium   | `lg` / default (50vw) → `xl` (760px); set `--ds-sheet-width` for an exact width |
+ * | `header-close`      | applied | low      | the header's close button is now the sheet's built-in one                    |
+ * | `rendering`         | applied | low      | Sheet parts pad differently (`p-6` header/footer, `px-6` body; no rules between them) |
+ * | `no-header`         | review  | high     | a drawer without `SideDrawer.Header` has no title to become the `SheetTitle` |
+ * | `width-dynamic`     | review  | high     | `width={expr}` cannot be mapped to a `size` step                             |
+ * | `spread-props`      | review  | medium   | `{...props}` on the drawer or a part may carry any of the above              |
+ *
+ * Elements already on `Sheet` are not touched (idempotency). Local components
+ * with the same name are not touched; test files are skipped.
+ */
+import { analyseForms, isWithin } from "../lib/forms.mjs";
+import { applyEdits, openingOf } from "../lib/jsx-edit.mjs";
+
+export const meta = {
+  id: "CM-09",
+  title: "SideDrawer → Sheet (drawers with a header rewritten; the rest reported)",
+  class: "R",
+  oneShot: false,
+  requires: { codemods: [], dsVersion: null },
+  parses: ["code"],
+  includeTests: false,
+  usesTypeScript: true,
+  usesPostcss: false,
+  registryIds: ["C-SIDEDRAWER"],
+};
+
+export const RULES = {
+  renamed: { action: "applied", severity: "low" },
+  "width-approximate": { action: "applied", severity: "medium" },
+  "header-close": { action: "applied", severity: "low" },
+  rendering: { action: "applied", severity: "low" },
+  "no-header": { action: "review", severity: "high" },
+  "width-dynamic": { action: "review", severity: "high" },
+  "spread-props": { action: "review", severity: "medium" },
+};
+
+/** `width` preset → `size` step. `lg` (50vw) has no step; `xl` is the nearest. */
+export const WIDTH_TO_SIZE = { sm: "sm", md: "lg", lg: "xl" };
+
+const PART_TO_SHEET = {
+  "SideDrawer.Header": "SheetHeader",
+  "SideDrawer.Body": "SheetBody",
+  "SideDrawer.Footer": "SheetFooter",
+};
+
+/** Children text for a title/subtitle attribute: a literal becomes text, an expression stays. */
+function childrenOf(ts, sf, attr) {
+  const init = attr.initializer;
+  if (!init) return "";
+  if (ts.isStringLiteral(init)) {
+    return /[{}<>]/.test(init.text) ? `{${init.getText(sf)}}` : init.text;
+  }
+  return init.getText(sf);
+}
+
+/** The `onOpenChange` handler that calls the drawer's `onClose` on close. */
+function closeHandler(ts, sf, attr) {
+  const init = attr.initializer;
+  const inner = init && ts.isJsxExpression(init) ? init.expression : null;
+  if (!inner) return null;
+  if (ts.isIdentifier(inner) || ts.isPropertyAccessExpression(inner)) {
+    return `(open) => !open && ${inner.getText(sf)}()`;
+  }
+  if (ts.isArrowFunction(inner) && inner.parameters.length === 0 && !ts.isBlock(inner.body)) {
+    return `(open) => !open && ${inner.body.getText(sf)}`;
+  }
+  return `(open) => !open && (${inner.getText(sf)})()`;
+}
+
+const attrsOf = (ts, sf, opening) => {
+  const map = new Map();
+  for (const attr of opening.attributes.properties) {
+    if (ts.isJsxAttribute(attr)) map.set(attr.name.getText(sf), attr);
+  }
+  return map;
+};
+
+const indentOf = (sf, node) => {
+  const text = sf.text;
+  const lineStart = text.lastIndexOf("\n", node.getStart(sf)) + 1;
+  return /^[ \t]*/.exec(text.slice(lineStart, node.getStart(sf)))[0];
+};
+
+export function transform(file, { ts }) {
+  const facts = analyseForms(ts, file.source, file.rel);
+  const sf = facts.sf;
+  const findings = [];
+  const edits = [];
+  const needed = new Set();
+  let remaining = 0;
+  let renamedAny = false;
+
+  const drawers = facts.elements.filter(
+    (el) => el.isDs && el.base === "SideDrawer" && el.component === "SideDrawer",
+  );
+
+  for (const el of drawers) {
+    const base = {
+      line: el.line,
+      registryId: "C-SIDEDRAWER",
+      match: `<${el.tag}>`,
+      component: el.component,
+      gate: null,
+      detail: {},
+    };
+    const add = (rule, detail = {}) =>
+      findings.push({ ...base, rule, ...RULES[rule], detail: { ...base.detail, ...detail } });
+
+    const parts = facts.elements.filter(
+      (p) =>
+        p.isDs &&
+        p.base === "SideDrawer" &&
+        p.component !== "SideDrawer" &&
+        isWithin(facts.elements, p.index, el.index) &&
+        !drawers.some(
+          (other) =>
+            other !== el &&
+            isWithin(facts.elements, p.index, other.index) &&
+            isWithin(facts.elements, other.index, el.index),
+        ),
+    );
+    const header = parts.find((p) => p.component === "SideDrawer.Header") ?? null;
+    const width = el.props.get("width");
+
+    let blocked = false;
+    if (el.spread || parts.some((p) => p.spread)) {
+      add("spread-props");
+      blocked = true;
+    }
+    if (width && width.expression) {
+      add("width-dynamic");
+      blocked = true;
+    }
+    if (!header || ts.isJsxElement(header.node)) {
+      add("no-header");
+      blocked = true;
+    }
+    if (blocked || !ts.isJsxElement(el.node)) {
+      remaining += 1;
+      continue;
+    }
+
+    // ── The drawer's own opening tag → <Sheet open onOpenChange> ─────────
+    const opening = el.node.openingElement;
+    const attrs = attrsOf(ts, sf, opening);
+    const inner = [];
+    inner.push({ pos: opening.tagName.getStart(sf), end: opening.tagName.getEnd(), text: "Sheet" });
+    const closing = el.node.closingElement.tagName;
+    inner.push({ pos: closing.getStart(sf), end: closing.getEnd(), text: "Sheet" });
+
+    const onClose = attrs.get("onClose");
+    if (onClose) {
+      const handler = closeHandler(ts, sf, onClose);
+      if (handler) {
+        inner.push({
+          pos: onClose.getStart(sf),
+          end: onClose.getEnd(),
+          text: `onOpenChange={${handler}}`,
+        });
+      }
+    }
+    const removeAttr = (name) => {
+      const list = opening.attributes.properties;
+      const index = list.findIndex((a) => ts.isJsxAttribute(a) && a.name.getText(sf) === name);
+      if (index < 0) return;
+      const from = index === 0 ? opening.attributes.pos : list[index - 1].getEnd();
+      inner.push({ pos: from, end: list[index].getEnd(), text: "" });
+    };
+    removeAttr("width");
+    removeAttr("side");
+
+    // ── The content: side, size, showCloseButton ─────────────────────────
+    const preset = width ? width.literals[0] : "lg";
+    const size = WIDTH_TO_SIZE[preset] ?? "xl";
+    const contentAttrs = [];
+    const side = attrs.get("side");
+    contentAttrs.push(side ? `side=${side.initializer.getText(sf)}` : 'side="right"');
+    contentAttrs.push(`size="${size}"`);
+    const headerAttrs = attrsOf(ts, sf, header.node);
+    if (!headerAttrs.has("onClose")) contentAttrs.push("showCloseButton={false}");
+    needed.add("Sheet").add("SheetContent").add("SheetHeader").add("SheetTitle");
+
+    // ── SideDrawer.Header → SheetHeader with title and description ───────
+    const headerIndent = indentOf(sf, header.node);
+    const headerRows = [];
+    headerRows.push(`<SheetTitle>${childrenOf(ts, sf, headerAttrs.get("title"))}</SheetTitle>`);
+    const subtitle = headerAttrs.get("subtitle");
+    if (subtitle) {
+      needed.add("SheetDescription");
+      const value = childrenOf(ts, sf, subtitle);
+      headerRows.push(
+        subtitle.initializer && ts.isJsxExpression(subtitle.initializer)
+          ? `{${subtitle.initializer.expression.getText(sf)} ? <SheetDescription>${value}</SheetDescription> : null}`
+          : `<SheetDescription>${value}</SheetDescription>`,
+      );
+    }
+    const headerClass = headerAttrs.get("className");
+    const headerOpen = `<SheetHeader${headerClass ? ` ${headerClass.getText(sf)}` : ""}>`;
+    inner.push({
+      pos: header.node.getStart(sf),
+      end: header.node.getEnd(),
+      text: [
+        headerOpen,
+        ...headerRows.map((row) => `${headerIndent}  ${row}`),
+        `${headerIndent}</SheetHeader>`,
+      ].join("\n"),
+    });
+
+    // ── Body / Footer → SheetBody / SheetFooter ──────────────────────────
+    for (const part of parts) {
+      if (part === header) continue;
+      const to = PART_TO_SHEET[part.component];
+      if (!to) continue;
+      needed.add(to);
+      const partOpening = openingOf(ts, part.node);
+      inner.push({
+        pos: partOpening.tagName.getStart(sf),
+        end: partOpening.tagName.getEnd(),
+        text: to,
+      });
+      if (ts.isJsxElement(part.node)) {
+        const tag = part.node.closingElement.tagName;
+        inner.push({ pos: tag.getStart(sf), end: tag.getEnd(), text: to });
+      }
+    }
+
+    // ── Assemble: apply the inner edits to the element's own text, indent
+    // the children one level and wrap them in <SheetContent>. ──────────────
+    const start = el.node.getStart(sf);
+    const end = el.node.getEnd();
+    const local = inner.map((e) => ({ ...e, pos: e.pos - start, end: e.end - start }));
+    const text = applyEdits(file.source.slice(start, end), local);
+    // Where the (edited) opening tag ends: its original length plus what the
+    // edits inside it added or removed.
+    const openingEnd = opening.getEnd() - start;
+    const openEnd = local
+      .filter((e) => e.end <= openingEnd)
+      .reduce((at, e) => at + e.text.length - (e.end - e.pos), openingEnd);
+    const closeStart = text.lastIndexOf("</Sheet>");
+    const indent = indentOf(sf, el.node);
+    const children = text.slice(openEnd, closeStart).replace(/\n(?=[^\n])/g, "\n  ");
+    const trimmed = children.replace(/\s+$/, "");
+    edits.push({
+      pos: start,
+      end,
+      text: `${text.slice(0, openEnd)}\n${indent}  <SheetContent ${contentAttrs.join(" ")}>${trimmed}\n${indent}  </SheetContent>\n${indent}${text.slice(closeStart)}`,
+    });
+
+    renamedAny = true;
+    add("renamed");
+    if (WIDTH_TO_SIZE[preset] === "xl" || !WIDTH_TO_SIZE[preset]) {
+      add("width-approximate", { width: preset, size });
+    }
+    if (headerAttrs.has("onClose")) {
+      add("header-close", {
+        header: headerAttrs.get("onClose").initializer?.getText(sf) ?? null,
+        drawer: onClose?.initializer?.getText(sf) ?? null,
+      });
+    }
+    add("rendering");
+  }
+
+  // The import: `SideDrawer` → the Sheet parts the file now uses, when no
+  // element is left on the old name.
+  if (renamedAny && remaining === 0) {
+    for (const stmt of sf.statements) {
+      if (!ts.isImportDeclaration(stmt) || !ts.isStringLiteral(stmt.moduleSpecifier)) continue;
+      if (!stmt.moduleSpecifier.text.startsWith("@assure-one/design-system")) continue;
+      const bindings = stmt.importClause?.namedBindings;
+      if (!bindings || !ts.isNamedImports(bindings)) continue;
+      const present = new Set(bindings.elements.map((e) => (e.propertyName ?? e.name).text));
+      for (const element of bindings.elements) {
+        const imported = (element.propertyName ?? element.name).text;
+        if (imported !== "SideDrawer" || element.propertyName) continue;
+        const names = [...needed].filter((n) => !present.has(n)).sort();
+        if (names.length) {
+          edits.push({ pos: element.getStart(sf), end: element.getEnd(), text: names.join(", ") });
+        } else {
+          const list = bindings.elements;
+          const index = list.indexOf(element);
+          const from = index === 0 ? element.getStart(sf) : list[index - 1].getEnd();
+          const to = index === 0 && list.length > 1 ? list[1].getStart(sf) : element.getEnd();
+          edits.push({ pos: from, end: to, text: "" });
+        }
+      }
+    }
+  }
+
+  return {
+    output: edits.length ? applyEdits(file.source, edits) : file.source,
+    findings,
+    notTransformed: [],
+    parseErrors: facts.parseErrors,
+  };
+}