@apostel/bedrock 0.1.0

package/skills/migrate-to-bedrock/SKILL.md

@@ -0,0 +1,188 @@
+---
+name: migrate-to-bedrock
+description: Migrate a React codebase from Radix UI primitives to @apostel/bedrock. Use when the user asks to migrate off Radix, replace @radix-ui/react-* imports, adopt bedrock, or move a shadcn/ui project onto native platform primitives. Also use when asked why a bedrock trigger throws, why a dialog no longer closes on backdrop click, or why data-state selectors stopped matching.
+---
+
+# Migrating from Radix to bedrock
+
+bedrock is Radix-**shaped**: same compound components, same part names, same
+`asChild`. It is built on the top layer, invoker commands, anchor positioning
+and native form controls instead of on JavaScript that reimplements them.
+
+That means most of a migration is mechanical, and the parts that are not are
+concentrated in four places. Do the mechanical work first; the four judgement
+calls are what the user needs to actually decide.
+
+**Before touching anything, read `docs/gaps.md` in the bedrock repo or at
+<https://bedrock.sams.land/gaps.html> and tell the user what applies to them.**
+Three of the items there stop migrations dead, and finding that out after a
+half-finished refactor is worse than finding out first.
+
+## Step 0 — establish whether this is viable
+
+Check these before writing any code. Report what you find; do not decide alone.
+
+| check | how | if yes |
+| --- | --- | --- |
+| jsdom component tests that click a trigger | `rg -l 'render\(' --glob '*.test.*'` and look for dialog/menu interaction | **This is the big one.** jsdom has no invoker commands, so those clicks do nothing. Every such test needs rewriting against a real browser. Say so before anything else. |
+| triggers that are not `<button>` | `rg -B2 'Trigger asChild' -A3` | Each one is a build error at mount, not a warning. Router `<Link>` inside a `Dialog.Trigger` is the most common. |
+| `data-state` in CSS, Tailwind config, or shared utilities | `rg 'data-state' --glob '!node_modules'` | Repo-wide selector change. `:open` cannot select an ancestor. |
+| overlays with content in them | `rg -A5 'Dialog.Overlay\|AlertDialog.Overlay'` | `::backdrop` is a pseudo-element. A spinner or close button inside the overlay is a redesign. |
+
+If the project has hundreds of jsdom component tests and no Playwright setup,
+that cost dwarfs everything else. Say that plainly rather than starting.
+
+## Step 1 — mechanical changes
+
+Safe to apply across the repo.
+
+```diff
+-import * as Dialog from '@radix-ui/react-dialog'
++import { Dialog } from '@apostel/bedrock'
+```
+
+Then, inside the tree:
+
+| Radix | bedrock | why |
+| --- | --- | --- |
+| `<X.Portal>` | delete the wrapper, keep its children | The top layer means there is nothing to portal past. |
+| `<X.Overlay className="…" />` | delete it; move the classes to `backdrop:` on Content | The overlay is `::backdrop`. |
+| `[data-state="open"]` | `:open` | Native state, no JS mirror. |
+| `[data-state="closed"]` | `:not(:open)` | |
+| `[data-state="checked"]` | `:checked` | |
+| `[data-state="on"]` | `[aria-pressed="true"]` | Toggle and ToggleGroup. |
+| `forceMount` | delete it | Content unmounts when closed and there is no opt-out. Check what depended on it. |
+| `data-[state=open]:animate-in` | `open:` + `starting:` + `transition-discrete` | Tailwind 4 has all three built in. |
+
+For animation, the shape is always the same:
+
+```tsx
+className="
+  scale-95 opacity-0 transition-all transition-discrete duration-150
+  open:scale-100 open:opacity-100
+  starting:open:scale-95 starting:open:opacity-0
+"
+```
+
+`transition-discrete` is what keeps the element displayed while it fades out;
+without it the exit is skipped. On a top-layer element also transition
+`overlay`, or the exit plays *underneath* whatever was above it.
+
+## Step 2 — the four judgement calls
+
+Do not resolve these silently. Each one changes behaviour a user will notice.
+
+### Triggers must be buttons
+
+Radix attaches a click handler to whatever you give it. bedrock does not, and
+throws at mount in development.
+
+```diff
+-<Dialog.Trigger asChild><Link href="/upgrade">Upgrade</Link></Dialog.Trigger>
++<Dialog.Trigger asChild><button type="button" onClick={…}>Upgrade</button></Dialog.Trigger>
+```
+
+The second most common failure is subtler: a `<button>` inside a `<form>`
+defaults to `type="submit"`, and the browser ignores `commandfor` on a submit
+button. Add `type="button"`.
+
+If the element genuinely cannot change — a third-party component that renders a
+`div` — `useDialogTrigger()` hands over the props and the accessibility
+responsibility. Use it as a last resort and say so in a comment.
+
+### Light dismiss is gone
+
+A modal `<dialog>` does not close on a backdrop click. Users report this as "the
+dialog is stuck". Restore it per dialog if the product wants it:
+
+```tsx
+<Dialog.Content {...{ closedby: 'any' }} />
+```
+
+Ask before applying it globally — for a destructive confirmation, *not*
+dismissing on an outside click is usually the better behaviour.
+
+### `onOpenChange` on the default root cannot refuse
+
+It is a `toggle` listener: it reports, it cannot decline.
+
+Grep for handlers that conditionally avoid calling `setOpen` — an
+unsaved-changes guard, a "are you sure" interstitial. Those roots, and only
+those, move to the controlled import:
+
+```diff
+-import { Dialog } from '@apostel/bedrock'
++import { Dialog } from '@apostel/bedrock/controlled'
+```
+
+Everything else keeps the smaller bundle. A handler that just resets a form or
+fires analytics is served by the default root.
+
+### Closed content is unmounted
+
+This is usually a *win* — a form inside a dialog resets itself, and any
+`onOpenChange` handler that existed only to reset state can be deleted. Look for
+those and remove them; that is the cleanup the migration pays for.
+
+It bites in two places: content that was measured while closed, and an
+animation library driving presence. Both need the state hoisting above the
+dialog.
+
+## Step 3 — per-primitive notes
+
+Only what actually differs. Everything not listed is a straight swap.
+
+- **Accordion** — `type="single"` is `<details name>`, so an open item can
+  always be closed; Radix's `collapsible={false}` has no equivalent. `Header`
+  renders the `<summary>` and `Trigger` sits inside it.
+- **Checkbox, Switch, RadioGroup, Slider, Progress** — real elements, so
+  `Indicator`, `Thumb`, `Track` and `Range` render nothing. Their styles move to
+  `::before`, `::-webkit-slider-thumb`, `::-webkit-progress-value`. Watch for
+  icon *components* inside those parts: an `<input>` has no children, so a
+  `<CheckIcon />` inside a checkbox has nowhere to go and becomes CSS.
+- **Slider** — one thumb. A two-thumb range has no native equivalent; flag it.
+- **Select** — a real `<select>`. `Select.Value` is `<selectedcontent>`, so
+  there is no `placeholder` render prop. On phones this gets the OS picker,
+  which is usually desirable and occasionally a design regression.
+- **Tabs** — the unselected panel is unmounted rather than hidden.
+- **Tooltip / HoverCard** — no `Provider`; the delay is a prop on the root. The
+  trigger may be an `<a>`.
+- **Menus** — submenus need no configuration, and Escape closes only the topmost
+  layer. If the code has layer-ordering workarounds, delete them.
+- **NavigationMenu** — `Viewport` renders nothing.
+
+## Step 4 — verify
+
+1. `npx tsc --noEmit` — the prop-level differences surface here.
+2. Run the app and open every migrated overlay **in a browser**. The dev throw
+   for a bad trigger only fires when the component actually mounts, so a trigger
+   behind a rare branch will not appear until it renders.
+3. Check the console for bedrock warnings: they name the pseudo-element to
+   style instead of the part that now renders nothing.
+4. If the project has jsdom tests for these components, they are now testing
+   nothing. Either port them to Playwright or delete them — leaving them green
+   and meaningless is the worst outcome.
+
+## shadcn/ui projects
+
+There is a registry, so most components are one command rather than a rewrite:
+
+```bash
+npx shadcn@latest add https://bedrock.sams.land/r/dialog.json
+```
+
+24 items cover everything that was Radix-backed except `menubar`,
+`navigation-menu`, `toast`, `sheet` and `drawer`. Commit before running it — the
+CLI overwrites `components/ui/*.tsx`, and the diff is the thing worth reading.
+
+Note that `dialog` from the registry is the **uncontrolled** build and has no
+`open` prop; it throws in development telling you to install
+`dialog-controlled` instead. Install whichever the app actually uses.
+
+## What to tell the user at the end
+
+- which files changed, and which of the four judgement calls you applied
+- any trigger you could not fix without changing an element they own
+- whether their tests still test anything
+- the measured bundle difference, if they care: it is in the bedrock README per
+  primitive, and it is not uniform — menus save far less than dialogs do