@justanarthur/modo-ui 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,609 @@
-# Temporary Holding Version
+# UI — Fluid Functionalism for modo
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The UI design system is a port of [Fluid Functionalism](https://www.fluidfunctionalism.com)
+(FF) into modo's structure. FF is a shadcn-style component registry by Micka
+Touillaud / mickadesign ([repo](https://github.com/mickadesign/fluid-functionalism),
+MIT). It layers motion springs, a fluid hover highlight, a two-step size ladder,
+an eight-level elevated surface system and Inter weight animation on top of
+Radix or Base UI primitives.
+
+This port differs from the upstream registry in three ways:
+- It uses the **Base UI** flavor.
+- **UnoCSS** (`presetWind4`) replaces Tailwind CSS v4.
+- **[`cn`](https://github.com/shadcn-ui/cn)** replaces clsx + tailwind-merge.
+
+The sibling `../fluid-functionalism` package is a different project: a Radix
+flavor pulled with the shadcn CLI, still on Tailwind.
+
+On top of FF, the overlays morph: they grow out of whatever opened them, with
+a liquid "goo" neck by default. That layer is local code (`lib/use-morph.ts`,
+`lib/morph-layers.tsx`, documented by `primitives/morph`), with techniques
+taken from three more MIT projects (see [Morph sources](#morph-sources)).
+
+## Install
+
+```sh
+npm install @justanarthur/modo-ui
+```
+
+React 18 or later is a peer dependency. Import components from the package
+root, or one item per subpath (`@justanarthur/modo-ui/components/button`,
+`@justanarthur/modo-ui/components/overlays/dialog`, …):
+
+```tsx
+import { Button, Switch } from '@justanarthur/modo-ui'
+```
+
+### Styles
+
+Pick one of three ways in. The components are styled with utility classes,
+so either take them prebuilt or let your own Tailwind or UnoCSS generate them
+by scanning the package's `dist/`. Scanning emits each class once, beside your
+own.
+
+**Prebuilt**: no CSS tooling needed. It includes the reset, the tokens, the
+base styles and every utility the components use:
+
+```ts
+import '@justanarthur/modo-ui/styles.css'
+```
+
+**Tailwind CSS v4**: the theme, the token utilities, the `dark:` variant and
+`@source` for the components ship in one file:
+
+```css
+@import "tailwindcss";
+@import "@justanarthur/modo-ui/tailwind.css";
+```
+
+**UnoCSS** (`presetWind4`): add the preset and the components' content, then
+import the tokens and base styles:
+
+```ts
+// uno.config.ts
+import presetModoUi, { modoUiContent } from '@justanarthur/modo-ui/unocss'
+import { defineConfig, presetWind4 } from 'unocss'
+
+export default defineConfig({
+  presets: [presetWind4(), presetModoUi()],
+  content: { inline: [modoUiContent] },
+})
+```
+
+```ts
+import 'virtual:uno.css'
+import '@justanarthur/modo-ui/base.css'
+```
+
+`tokens.css` holds the CSS variables alone.
+
+### Theme
+
+Every color is a `light-dark()` token, so `color-scheme` picks the side: it
+follows the OS until `<html>` (or any subtree) carries `light` or `dark`.
+`dark:` utilities match inside a `.dark` ancestor, so set the class whenever
+you pin dark mode:
+
+```ts
+document.documentElement.classList.toggle('dark', dark)
+document.documentElement.classList.toggle('light', !dark)
+```
+
+## Source
+
+- Repository: `github.com/mickadesign/fluid-functionalism`
+- Commit: `b3587bdbd83fc66c2a6aae3817ffb856cb09260b`
+- License: MIT © 2026 Micka Touillaud. The full text is in
+  [`LICENSE.fluid-functionalism`](./LICENSE.fluid-functionalism), copied
+  verbatim.
+- Flavor: `registry/base/*` wherever upstream ships a flavored file, and
+  `registry/default/*` otherwise. The Base UI flavor is pinned to
+  `@base-ui/react@1.4.1`, the version upstream was tested with.
+
+Every vendored file opens with a plain `/* */` header. The header names the
+upstream path and commit, carries the MIT notice, and lists every local
+modification. The vendored code below the header keeps upstream's formatting.
+Files written for this port (`preset.ts`, `uno.config.ts`, `vite.ts`, `index.ts`,
+`scripts/build-css.ts`, `modo.components.tsx`,
+`lib/use-controllable-state.ts`, `primitives/code/index.tsx`, `primitives/craft/*`, the morph files
+in `lib/` (`use-morph.ts`, `reduced-motion.ts`, `morph-layers.tsx`, `morph-part.tsx`, `goo-indicator.tsx`,
+`slot.ts`) and `primitives/morph/index.tsx`, `blocks/sidebar-app/index.tsx`,
+and the local components marked "— (local)" below) use this repo's style: single quotes and no semicolons.
+
+### Morph sources
+
+| Project | Repository @ commit | License | What it contributes |
+|---|---|---|---|
+| beUI | `github.com/starc007/ui-components` @ `de52f337e520e7ee37749b36eb1c32df86137bcb` | MIT © 2026 Saurabh Chauhan, [`LICENSE.beui`](./LICENSE.beui) | the gooey popover's rect interpolation, rounded-rect path, source cutout and goo filter; the morph select; the morphing search (idea only) |
+| motion-primitives | `github.com/ibelick/motion-primitives` @ `120f64f6ca60348e251f929e9c81f11ccbe45eda` | MIT © 2024 ibelick, [`LICENSE.motion-primitives`](./LICENSE.motion-primitives) | the morphing popover and morphing dialog (trigger growing into the panel, shared parts) |
+| Sileo | `github.com/hiaaryan/sileo` @ `9793f844349983e140cf33cebbb8f51626d41407` | MIT, [`LICENSE.sileo`](./LICENSE.sileo) | the goo blur as a share of the surface radius; the gooey toast |
+
+Sileo declares MIT in its `package.json` but ships no LICENSE file, so
+`LICENSE.sileo` is the standard MIT text naming the repository's owner.
+beUI's and motion-primitives' are copied verbatim.
+
+Only visuals come from these projects. Base UI keeps all behavior
+(positioning, focus, dismissal, hover and tap, scroll lock), so none of
+their own hooks for it (click-outside, focus traps, dismissal, gestures,
+positioning) are ported.
+
+## Layout
+
+| Path | What it holds |
+|---|---|
+| `AGENTS.md` | The ui-specific guide for coding agents (where things live, the rules that matter most, the checks); `CLAUDE.md` imports it. |
+| `DESIGN.md` | The design language in Google's [DESIGN.md](https://github.com/google-labs-code/design.md) format: the tokens as front matter, the rules as prose. Agents building here follow the `modo-ui` skill (`.claude/skills/modo-ui` at the repo root). |
+| `tokens/*.css` | Colors, typography (`--font-sans`, `--text-*`), motion (`--duration-*`), radius and spacing. |
+| `base.css` | Theme switching, base styles, focus fallback, scrollbars, shimmer/spinner keyframes and `.scroll-fade`. Shipped in the package. |
+| `global.css` | The docs site's stylesheet (`modo.config.ts` `css`): imports `base.css`, then the modo-only focus revert and the docs chrome. |
+| `preset.ts` | The UnoCSS preset (theme and token utilities), shipped as `@justanarthur/modo-ui/unocss`. |
+| `uno.config.ts`, `vite.ts` | The UnoCSS setup of the docs site and the prebuilt CSS (see below). |
+| `index.ts`, `bunup.config.ts`, `scripts/build-css.ts` | The package build: `bun run build` writes the components, their types and the stylesheets to `dist/`. The docs site builds with `bun run build:docs` into `docs-dist/`. |
+| `lib/` | FF's shared system files (upstream `lib/`, `hooks/` and the fluid-hover highlight, flat, upstream names), imported relatively by items. modo only scans the tier folders, so it never mistakes them for items. |
+| `modo.components.tsx` | Components only the docs site uses: the `Icon`, `Select` and `DocsNav` shell-slot adapters and the `ThemeSwitcher` panel item, picked in `modo.config.ts` by export name (`./modo.components.tsx#Select`). |
+| `primitives/<id>/` | FF's "System" pages: `index.tsx` (component + TSDoc prose) and `examples.mdx`, pulled in by `@example {@include ./examples.mdx}`. |
+| `components/[<group>/]<id>/` | FF's "Components" pages, same shape. The `inputs/`, `navigation/` and `overlays/` group folders become sidebar sub-groups and overview sections; the core display items stay ungrouped. |
+| `blocks/<id>/` | Compositions of several items, same shape: `sidebar-app`, FF's sidebar preset `sa1FQfCxH6` as an app shell, with the header and footer blocks it is built from beside it. |
+
+## Upstream → local file map
+
+### Shared system (`lib/`)
+
+| Upstream (`registry/default/…`) | Local | Modifications |
+|---|---|---|
+| `lib/utils.ts` | `lib/utils.ts` | `extendTailwindMerge` → `createCn` from `cn/config`, with the same font-size group extension; the local token utilities join their groups too (compact and `micro` type roles as font-size, `weight-*`, the `duration-*` / `delay-*` motion tiers, `rounded-box\|glyph`) |
+| `lib/springs.ts` | `lib/springs.ts` | `goo` tier added (the morph engine's goo: 250ms to land, bounce 0.15, a 200ms spring back); `exitFallbackMs` also reads a spring exit's `visualDuration` |
+| `lib/font-weight.ts` | — | not ported: its `fontWeights` became the `--weight-*` tokens in `tokens/typography.css` (the `weight-*` utilities) |
+| `lib/popup.ts` | `lib/popup.ts` | `popupMotionClass` dropped (unused since the popups morph) |
+| `lib/shape-context.tsx` | `lib/shape-context.tsx` | `"use client"` dropped |
+| `lib/size-context.tsx` | `lib/size-context.tsx` | `"use client"` dropped; `SizeProvider` moved to `primitives/sizes` (the documented item), with `SizeContext` exported for it; `sizeMap` text classes → `text-body` / `text-body-compact` |
+| `lib/icon-context.tsx` | `lib/icon-context.tsx` | `"use client"` dropped; `size`/`strokeWidth` widened to `number \| string` for lucide v1 + React 18 types |
+| `lib/surface-context.tsx` | `lib/surface-context.tsx` | `"use client"` dropped |
+| `lib/surface-classes.ts` | `lib/surface-classes.ts` | `SURFACE_HOVER_*` and `surfaceHoverClasses` dropped (only Sidebar used them) |
+| `hooks/use-fluid-hover.ts` | `lib/use-fluid-hover.ts` | `"use client"` dropped; `sessionRef` typed `MutableRefObject<number>` (React 18) |
+| `hooks/use-merge-split.tsx` | `lib/use-merge-split.tsx` | `"use client"` dropped; `framer-motion` → `motion/react`; relative imports; the merge/split choreography replaced by per-row blocks melted through `GooLayer`; exports and `SelBlock`'s `key`/rect/`radii`/`instant` kept |
+| `hooks/use-keyboard-nav-gate.ts` | `lib/use-keyboard-nav-gate.ts` | `"use client"` dropped; relative imports |
+| `hooks/use-touch-primary.tsx` | `lib/use-touch-primary.tsx` | `"use client"` dropped |
+| `sidebar-core.tsx` (`useIsMobile`) | `lib/use-is-mobile.ts` | Moved out of the sidebar, unchanged, so the date and time pickers share it |
+| `fluid-hover-highlight.tsx` | `lib/fluid-hover-highlight.tsx` | `"use client"` dropped; `framer-motion` → `motion/react`; relative imports; the fill is a `GooIndicator` (melts from row to row), props unchanged |
+| — (new) | `lib/use-controllable-state.ts` | Local addition: controlled + uncontrolled state, Base UI style |
+| — (new) | `lib/use-morph.ts` | Local addition: the morph engine (source rect → popup box on a spring tier, exit hold for Base UI's unmount), geometry after beUI's popover; goo runs on its own `spring.goo` with a blur of at least 8px that eases to nothing as the surface lands, so the neck pinches off; a close-only `exit` override, an `instant` predicate that ends a run at once, press points from clicks, context menus and long presses (a droplet source for `from="pointer"`), cleanup when the popup unmounts mid-run; focus goes back to the trigger when a closed popup that held it is gone and Base UI skipped the return (the exit hold makes a menu read the pointer leaving the inert popup as a hover close) |
+| — (new) | `lib/reduced-motion.ts` | Local addition: `useReduceMotion`, the one reduced-motion read for the morph layer and the liquid indicators — the OS setting, or a `MotionConfig` asking for it (motion's `useReducedMotionConfig` alone ignores the OS without `<MotionConfig reducedMotion="user">`) |
+| — (new) | `lib/field-classes.ts` | Local addition: the field ladder FF repeats per text field (rest → muted fill on hover or a group's `data-active` → card fill on focus; `data-invalid` keeps a destructive ring), as `fieldVariants` + `fieldIconClasses`, shared by Input, Combobox and Sidebar's input |
+| — (new) | `lib/date-locale.ts` | Local addition: what the date and time pickers read off a react-day-picker (date-fns) locale — the hour cycle (Intl), typed dates, times and months in the locale's formats (date-fns `parse` with `P`…`PPPP`), field names for column labels (`Intl.DisplayNames`) |
+| — (new) | `lib/scroll-column.tsx` | Local addition: `ScrollColumn`, the scrolling option list beside a calendar (months, years, hours, minutes) or a strip above it: the pick gets a dot, a run of `inView` options one band, the followed option stays centred; fluid hover, listbox semantics, arrow keys; `dividedColumns` puts a hairline between neighbours |
+| — (new) | `lib/slot.ts` | Local addition: Dialog's `render` / `asChild` slot shape (`SlotProps`, `slotRender`), shared by every overlay part that wraps a control |
+| — (new) | `lib/morph-part.tsx` | Local addition: `MorphPart` (shared parts over a motion `layoutId`, after motion-primitives' morphing dialog) and the scope contexts overlays provide |
+| — (new) | `lib/goo-indicator.tsx` | Local addition: `GooIndicator` (melts between items, a lingering blob follows it) and `GooLayer` (goo over the shapes' coverage, filled with their own token, on only while moving), on the engine's `GOO_MATRIX` / `GOO_BLUR_RATIO` |
+| — (new) | `lib/morph-layers.tsx` | Local addition: `MorphSurface`, the renderer (shapes layer with beUI's goo filter plus a `--shadow-color` hairline around the melted shape, surface background and shadow, clipped content) |
+
+### Styles
+
+| Upstream | Local |
+|---|---|
+| `app/globals.css` §1 tokens | `tokens/colors.css`, with HEX converted to oklch. The surface ladder and shadows live in `primitives/surface/surface.css`. Local addition: the `--status-*` roles (toast states), by reference to the badge palette, `--destructive` and `--brand`. |
+| `app/globals.css` §2 theme switching | `base.css` (`color-scheme`, `--overlay`) and `surface.css` (`--shadow-N` per scheme) |
+| `app/globals.css` §3 `@theme inline` | `preset.ts` `theme` |
+| `app/globals.css` `--fs-*` + `@utility text-*` | `tokens/typography.css` `--text-*` and `preset.ts` `utilities` |
+| `app/globals.css` §4–6 | `base.css` |
+| `registry/default/lib/springs.ts` (as CSS) | `tokens/motion.css` (plus `--duration-goo` / `--duration-goo-exit`) |
+
+### Items
+
+Every item goes through the same mechanical pass, so the tables below list
+only what is specific to it:
+
+- `"use client"` dropped (no RSC here).
+- Imports rewritten: `@/lib/*` → `../../lib/*`, `@/hooks/*` →
+  `../../lib/*`, `SizeProvider` from `@/lib/size-context` →
+  `../../primitives/sizes`, `@/lib/elevated` → `../../primitives/surface`,
+  `@/components/ui/scroll-area` → `../../primitives/scroll-area`,
+  `@/components/ui/fluid-hover-highlight` → `../../lib/fluid-hover-highlight`,
+  `@/registry/radix/*` → the Base-flavor sibling, `framer-motion` →
+  `motion/react`, `next/link` → a plain anchor.
+- A local `interface <Item>Props` whose members are each declared on one line
+  with the FF docs API-table text (modo's parser lists only members declared
+  in the interface body), modo TSDoc written from the FF docs page, and
+  `export default <Item>`. Upstream's named exports are kept.
+
+#### primitives
+
+| Item | Upstream | Local | Specific modifications |
+|---|---|---|---|
+| `Elevated` | `registry/default/lib/elevated.tsx` (+ `lib/surface-context.tsx`; docs "Surfaces") | `primitives/surface/index.tsx` | `.Provider` static (= `SurfaceProvider`); `useSurface` / `surfaceClasses` re-exported; `className`/`children` re-declared; `surface.css` co-located (modo injects it) |
+| `ScrollArea` | `registry/base/scroll-area.tsx` (docs "Scrollbars") | `primitives/scroll-area/index.tsx` | the root's forwardRef element type written out as `HTMLDivElement` (the parser needs a first type argument without `<`/`,`); `viewportClassName` documented; `.Bar` static (= `ScrollBar`) |
+| `SizeProvider` | `registry/default/lib/size-context.tsx` + `app/docs/sizes/page.tsx` | `primitives/sizes/index.tsx` | upstream's `SizeProvider`, moved here from the vendored context so modo documents it (sized components import it from here), with the hooks, maps and types re-exported; the live demos become static examples (Select/TabsSubtle/InputGroup/CheckboxGroup/Dropdown swapped for Button/Badge/Switch/Tabs, token-inspector overlay dropped); the token table and type scale are written out rather than rendered from `sizeMap` / `typeScale` |
+| `FluidHover` | `app/docs/fluid-hover/{page,demos}.tsx` over `registry/default/hooks/use-fluid-hover.ts` + `fluid-hover-highlight.tsx` | `primitives/fluid-hover/index.tsx` | new container (`FluidHover` + `FluidHover.Item`) around the hook/highlight pair so examples need no hooks; `items`, `renderItem`, `disabledIndices`, `columns`, `highlightClassName` are the container's own API, `axis` and `gapClick` pass through to the hook; row classes are upstream's `rowClass` with per-axis variants; the two scripted-cursor demos are dropped |
+| `Motion` | `registry/default/lib/springs.ts` + `app/docs/motion/page.tsx` | `primitives/motion/index.tsx` | `Motion` is local demo code (FF ships none): it plays one tier's enter spring and exit tween on its children, adding `defaultShow`, `sameExit` and `reducedMotion`; `spring` / `exitFallbackMs` re-exported from the vendored `springs.ts`; the ball-on-track and fake-modal visuals become show/hide of arbitrary children |
+| `Morph` | — (local; see [Morph sources](#morph-sources)) | `primitives/morph/index.tsx` | a docs stage like `Motion`: a trigger and a panel playing one `from` × `effect` pair over `lib/use-morph.ts`; static `.Part` (= `MorphPart`); also documents the liquid indicators (`lib/goo-indicator.tsx`) |
+| `Code` | — (local; FF has no code item) | `primitives/code/index.tsx` | sugar-high tokens colored by the `--syntax-*` tokens, one surface step above its substrate; also the docs chrome's Code slot |
+| `Craft` | — (local; after the before/after pairs on fluidfunctionalism.com/docs/skill) | `primitives/craft/index.tsx` (+ `demos.tsx`) | a docs stage: a bad and a good version side by side with a one-line verdict each; the bad sides live in `demos.tsx` and break one rule each on purpose, the good sides are this package's items |
+
+#### components
+
+| Item | Upstream | Local | Specific modifications |
+|---|---|---|---|
+| `Accordion` | `registry/base/accordion.tsx` | `components/navigation/accordion/index.tsx` | open state runs through `useControllableState` (see [Behavior additions](#behavior-additions)); standalone `Accordion` accepts `highlight` and passes it to its items as their default; the panel morphs out of its row (a shape grows from the press point into the item, content clipped by it, layout height on its bottom edge; the `"item"` tint is that shape melted into the row through `GooFilter`), `effect` / `tier` on `Accordion.Content`; the group's hover highlight and focus ring snap with reflowed rows; statics `.Group/.Item/.Trigger/.Content` |
+| `AlertDialog` | — (local) | `components/overlays/alert-dialog/index.tsx` | Base UI AlertDialog root (always modal, no outside-press dismissal) over Dialog's own parts and `DialogState`, so it morphs like Dialog; `AlertDialog.Content` drops the ✕ by default; statics as Dialog's |
+| `Badge` | `registry/default/badge.tsx` | `components/badge/index.tsx` | `variant` re-declared (it came from cva's `VariantProps` upstream); changes animate: a new label or variant springs the width (inner content span, `spring.moderate`) while the label blur-crossfades, a new color fades, the dot scales in and out; "Changes" example over a local `change-demo.tsx` stage |
+| `Button` | `registry/base/button.tsx` | `components/button/index.tsx` | `variant`/`disabled`/`children` re-declared; extra Sizes / Active / As-child / Loading morph examples; `loading` folds the surface into a circle around the spinner and back (`spring.moderate`, box unchanged), label and spinner crossfade, `aria-busy`, the disabled dim fades; "Loading morph" example over a local `loading-demo.tsx` stage; also serves modo's chrome Button (`shell.Button`) |
+| `Calendar` | — (local, on react-day-picker) | `components/inputs/date-time/calendar/index.tsx` (+ `use-month-window.ts`) | DayPicker props pass through (as shadcn's Calendar); styled through `classNames` and custom `Month` / `Day` / `DayButton` (no react-day-picker stylesheet); one scrolling list of months rendered as a 25-month window that moves as you scroll; a pinned weekday row, muted weekends, today's dot; FF's fills (the pick `bg-foreground text-background` like the primary button, a range `bg-active`, its preview `bg-hover`); month and year columns that mark the month being read and jump on click, before or after the days (`columnsSide`), turning into strips when narrow; `extraColumns` / `extraColumnsSide` for the date picker's time |
+| `Card` | `registry/default/card.tsx` | `components/card/index.tsx` | `next/link` → plain anchors (stretched card link, `CardButton`'s `href` form); statics `.Group/.Header/.Title/.Description/.Action/.Content/.Footer/.Media/.Image/.Eyebrow/.Feature/.Button` |
+| `CheckboxGroup` | `registry/base/checkbox-group.tsx` | `components/inputs/checkbox-group/index.tsx` | uncontrolled mode + group-level callback; item `checked`/`onToggle` optional, falling back to group context; arrow-key focus guarded for `noUncheckedIndexedAccess`; shared `useSelectionRuns`, picks melt and split through the goo; static `.Item` |
+| `ColorPicker` | `registry/default/color-picker.tsx` | `components/inputs/color-picker/index.tsx` | `@/registry/radix/{slider,tooltip}` → the Base siblings `../slider` / `../../overlays/tooltip`; `noUncheckedIndexedAccess` guards on regex captures, `rgb()`/`hsl()`/`oklch()` parts, `itemRects[i]` and the Slider's array value; static `.Popover`; uncontrolled support was already upstream (verified, kept); `ColorPicker.Popover` (goo on `spring.goo`; `from` / `effect` / `hideSource` / `tier`) and the format menu morph out of their triggers, replacing the motion wrappers and the ignored `actionsRef` |
+| `Combobox` | `registry/base/combobox.tsx` | `components/inputs/combobox/index.tsx` | root de-generified (the parser needs a plain function plus a same-file `interface ComboboxProps`): items gained an index signature, `value`/`defaultValue` are `string \| string[]` and `onValueChange` is a union of the two handler shapes; `ComboboxValue<Multiple>` still exported; `creatable` added; `React.*` type refs replaced by named type imports; statics `.Input/.Chips/.Content/.List/.Item/.Empty`; the popup morphs out of the field (morph layer, goo on `spring.goo`; `from` / `effect` / `hideSource` / `tier` on `Combobox.Content`), replacing the `scaleY` wrapper and the `actionsRef` deferred unmount |
+| `Command` | — (local) | `components/overlays/command/index.tsx` | Base UI Autocomplete rendered inline in Dialog's panel (`position="top"`, no ✕), morphing from its trigger with goo; grouped/flat command data filtered by label + keywords; one fluid highlight follows Base UI's highlight; ⌘K/Ctrl+K `hotkey` (one palette answers a press); fresh palette per open; statics `.Trigger/.Content/.Palette/.Shortcut`; `CommandList`/`CommandListRoot` exported for Search |
+| `ContextMenu` | — (local; see [Morph sources](#morph-sources)) | `components/overlays/context-menu/index.tsx` | Base UI ContextMenu (right click, long press) with the morph layer growing from the press point (`from="pointer"` default, goo on `spring.goo`); rows are Dropdown's `MenuItem`, `Dropdown.Label`, `Dropdown.Separator` with fluid hover; `ContextMenu.Item` adds `shortcut`; `size` on the root; statics `.Trigger/.Content/.Item/.Label/.Separator` |
+| `Dialog` | `registry/base/dialog.tsx` | `components/overlays/dialog/index.tsx` | `DialogProps` and `DialogContentProps` fully re-declared (the slot props now come from `lib/slot.ts`); statics attached as expando properties (`Dialog.Trigger = …`), so `<Dialog.Content>` types without a cast; FF's "With a sidebar" example replaced by "Surfaces inside a dialog" (written before the Sidebar was ported); the panel morphs out of its trigger (morph layer, goo on `spring.goo`; `from` / `effect` / `hideSource` / `tier` on `Dialog.Content`), the backdrop fades with the morph's progress, the root holds the open state and scopes `Morph.Part` pairs |
+| `Dropdown` | `registry/base/dropdown.tsx` | `components/overlays/dropdown/index.tsx` | uncontrolled selection and uncontrolled search filtering (below); `items[next].focus()` guarded; statics `.Menu/.Trigger/.Content/.Item/.Label/.Separator/.Search/.Empty`; FF's "Create from the query" section skipped — adding a row to the list is real consumer state; the popup menu morphs out of its trigger (morph layer, goo on `spring.goo`; `from` / `effect` / `hideSource` / `tier` on `Dropdown.Content`), replacing the `scaleY` wrapper and the ignored `actionsRef`; popup rows hand activation to the Menu item's `onClick` so Enter / Space pick |
+| `DatePicker`, `DateRangePicker`, `TimePicker`, `DurationPicker`, `MonthPicker` | — (local; props after shadcn's date picker and utegsk/ui's pickers) | `components/inputs/date-time/<id>/index.tsx` (+ the group's `picker-shell.tsx`, `time-columns.tsx`) | a field on the field ladder whose panel morphs out of it with Combobox's options (goo by default; `from` / `effect` / `hideSource` / `tier`, in place with `effect="morph"` + `hideSource`), or a bottom `Sheet` under 640px; one hour column with AM/PM on a 12-hour clock; `columnsSide` / `timeColumnsSide`; the panel header types the value in the locale's formats; `value` / `defaultValue` / `onValueChange` with `null` for empty — a `Date`, react-day-picker's `DateRange`, `"HH:mm"`, a date-fns `Duration`, a month's first day; `locale` is a react-day-picker locale throughout |
+| — | `registry/default/menu-item.tsx` | `components/overlays/dropdown/menu-item.tsx` | a row with no `checked` derives it from a self-managed panel and toggles the panel's state; `sourceIndex` carries the authored index so selection survives filter re-indexing |
+| — | `registry/default/dropdown-search.tsx` | `components/overlays/dropdown/dropdown-search.tsx` | `filter` mode: `value`/`onValueChange` optional, the field reads and writes the query held by the panel (`DropdownFilterContext`) |
+| `InputCopy` | `registry/default/input-copy.tsx` | `components/inputs/input-copy/index.tsx` | `@/registry/radix/tooltip` → `../../overlays/tooltip`; `useRef<ReturnType<typeof setTimeout> \| null>(null)` (React 18 overloads); defaults spelled into the prop prose; the tooltip comment's "Radix" reads "Base UI"; the copied state morphs: the glyph's two sheets melt through the goo filter into a status-tinted disc behind the check (✕ on failure) and split back |
+| `Input`, `Label`, `InputGroup` | `registry/default/input-group.tsx` | `components/inputs/input/index.tsx` | `InputField` split into `Input` (the ringed box, standalone: own hover outside a group, `invalid`, `size`) and `Label` (a plain `<label>`, rendered through `Field.Label` in a field), composed back by `InputGroup.Field`; item renamed `input`, `Input` the default export; uncontrolled mode (`InputHTMLAttributes`' own `defaultValue` omitted in favour of the local one); static `.Field` |
+| `InputMessage` | `registry/default/input-message.tsx` | `components/inputs/input-message/index.tsx` | uncontrolled twins for value, files, queue and status (below); `FilePreviewTile` turned into a `forwardRef` (it exits inside `<AnimatePresence mode="popLayout">`, which measures through a ref); guards on `queue[0]`, `history[i]`, `suggestions[i]` and the `moveQueued` swap; FF's Playground section skipped and the surrounding transcript dropped (`ChatMessage` is not ported) |
+| — | `registry/default/file-thumbnail.tsx` | `components/inputs/input-message/file-thumbnail.tsx` | the lazy `import("pdfjs-dist")` is kept as-is — verified against modo's esbuild settings, it lands in a ~790 kB chunk fetched only when a PDF is attached; the worker still comes from jsDelivr, so no bundler-side worker config is needed; the `@next/next/no-img-element` eslint-disable dropped |
+| `Popover` | — (local; after beUI's gooey popover and motion-primitives' morphing popover, see [Morph sources](#morph-sources)) | `components/overlays/popover/index.tsx` | Base UI Popover with the morph layer (goo by default); `openOnHover` on the trigger; statics `.Trigger/.Content/.Title/.Description/.Close` |
+| `PreviewCard` | — (local; after beUI's gooey popover, see [Morph sources](#morph-sources)) | `components/overlays/preview-card/index.tsx` | Base UI PreviewCard with the morph layer (goo from the link on `spring.goo`); `delay` / `closeDelay` / `render` on the trigger, a token-styled link by default; `from` without `'pointer'`; statics `.Trigger/.Content` |
+| `RadioGroup` | `registry/base/radio-group.tsx` | `components/inputs/radio-group/index.tsx` | uncontrolled index and value modes; group context carries a `selectIndex` setter every item calls, so items need no `selected`/`onSelect`; arrow-key focus guarded; selected background is a `GooIndicator`; static `.Item` |
+| `Search` | — (local; after beUI's morphing search, see [Morph sources](#morph-sources)) | `components/inputs/search/index.tsx` | pill or icon button springing its own width in place (`spring.slow`), growing over its neighbors (`align`); with `items`, Autocomplete suggestions ooze out of the field via the morph layer (goo on `spring.goo`, `effect`/`tier`) with Command's rows; Escape closes → clears → collapses; blur collapses when empty; `shortcut`; `<search>` landmark + form, `onSubmit` |
+| `Select` | `registry/base/select.tsx` | `components/inputs/select/index.tsx` | members re-declared one per line (the parser drops members whose type spans lines); upstream's uncontrolled `defaultValue` verified and kept rather than rerouted through `useControllableState`; expando statics `.Trigger/.Content/.Item/.Group/.Label/.Separator`; the popup morphs out of its trigger (morph layer, goo on `spring.goo`; `from` / `effect` / `hideSource` / `tier` on `Select.Content`), replacing the `scaleY` wrapper and the `actionsRef` deferred unmount |
+| `Sheet` | — (local; replaces beUI's bottom sheet and drawer, see [Morph sources](#morph-sources)) | `components/overlays/sheet/index.tsx` | Base UI Drawer (swipe to dismiss, snap points, `Drawer.Viewport` for the swipe) with the morph growing from the sheet's own edge; a swipe-dismissed sheet slides on off its edge from the release point (the morph's `exit`); `side`, `snapPoints`, `defaultSnapPoint`; Dialog's parts and `DialogState` (Base UI's Drawer parts are Dialog's); statics as Dialog's plus `.Provider` / `.Indent` |
+| `Sidebar` | `registry/base/sidebar.tsx` (+ `registry/default/sidebar-core.tsx`, `sidebar-menu.tsx`; `app/globals.css` `.scroll-divider`) | `components/navigation/sidebar/index.tsx` (+ `sidebar-core.tsx`, `sidebar-menu.tsx`, `sidebar.css`) | the mobile sheet is the DS's `Sheet` (goo from its edge, swipe to dismiss) instead of a Dialog with a framer slide; no collapsed peek: `openOnHover` on the provider opens the sidebar in flow while the pointer is between its edge and the far side of a trigger beside it, the trigger switching between open and on hover (`panel-*-dashed` glyphs added to the icon context); the active row backgrounds are `GooIndicator`s and the hover highlight the liquid `FluidHoverHighlight`; uncontrolled selection (`value` on the buttons, `value` / `defaultValue` / `onValueChange` on `Sidebar`) and collapsible rows (`Sidebar.MenuItem collapsible`, below); statics `.Provider/.Trigger/.Rail/.Inset/.Input/.Header/.Content/.Footer/.Separator/.Group/.GroupLabel/.GroupAction/.GroupActions/.GroupContent/.Menu/.MenuItem/.MenuButton/.MenuAction/.MenuActions/.MenuBadge/.MenuSkeleton/.MenuSub/.MenuSubItem/.MenuSubButton` through a `SidebarComponent` cast; `fontVariationSettings` → `weight-*`, `text-[Npx]` → type roles, hex focus ring → `ring-focus-ring`, `duration-80\|160\|240` → tiers |
+| `Slider` | `registry/base/slider.tsx` | `components/inputs/slider/index.tsx` | `var(--color-accent)` → `var(--accent)` (no `--color-*` aliases here); uncontrolled support on the public wrapper, with both engines still fully controlled; `SliderProps extends Omit<SliderEngineProps, "value" \| "onChange">`; React 18 ref types (`MutableRefObject`); indexed reads of the value/step/pip arrays asserted |
+| `Switch` | `registry/base/switch.tsx` | `components/inputs/switch/index.tsx` | uncontrolled support; every in-body read goes through the resolved `isChecked` and a `toggle()` that also calls `onToggle`; the thumb is a `GooIndicator` in Base UI's Thumb (stretches as it travels), dragged x held in state |
+| `Table` | `registry/default/table.tsx` | `components/table/index.tsx` | statics `.Header/.Body/.Row/.Head/.Cell`; `TableProps` / `TableRowProps` exported |
+| `Tabs` | `registry/base/tabs.tsx` | `components/navigation/tabs/index.tsx` | `defaultSelectedIndex` added as the index-mode twin of the existing `defaultValue`; indicator and hover pill are `GooIndicator`s (the hover pill returns to the active tab as it fades); statics `.List/.Item/.Panel` |
+| `TabsSubtle` | `registry/base/tabs-subtle.tsx` | `components/navigation/tabs-subtle/index.tsx` | uncontrolled mode; panels may be authored inside the root (below); the tab list's ref write goes through `MutableRefObject`; selected and hover pills are `GooIndicator`s; statics `.Item/.Panel` |
+| `ThinkingIndicator` | `registry/default/thinking-indicator.tsx` | `components/thinking-indicator/index.tsx` | upstream prop JSDoc kept (it already matches the FF API table); the `.shimmer-text` rule it rides lives in `base.css`; local `variant="goo"` (three dots merging and splitting through `GooFilter`, plain label; default stays `shimmer`); reduced motion also follows MotionConfig |
+| `Toast` | — (local; after Sileo, see [Morph sources](#morph-sources)) | `components/overlays/toast/index.tsx` | Base UI Toast (queue, timers, swipe, announcements) with Sileo's pill melting into a body through the shared `GooFilter`; autopilot expand/collapse, six states on the `--status-*` tokens, promise toasts; `Toast` is the provider + viewport, `Toast.Trigger` shows one, `useToast()` the imperative API |
+| `Tooltip` | `registry/base/tooltip.tsx` | `components/overlays/tooltip/index.tsx` | `className`/`children` docs filled in; statics `.Provider` / `.PortalContainer`; the slide + fade replaced by the morph layer (goo from the trigger on `spring.goo`, `from` / `effect` / `tier` props; `followCursor` tooltips fade); a hand-off between grouped tooltips skips the morph (Base UI's `data-instant`) |
+
+#### blocks
+
+| Item | Upstream | Local | Specific modifications |
+|---|---|---|---|
+| `SidebarApp` | the app-sidebar.tsx and page.tsx FF's preset generator emits for `sa1FQfCxH6` (`lib/preset/sidebar-install.ts` @ `c367a0d066bc10e663b3d269bc40539ea8417b25`, later than the pin: the generator postdates it) | `blocks/sidebar-app/index.tsx` (+ `nav-data.ts`) | the selected thread rides `Sidebar`'s `value` and shows in the topbar; the switcher keeps its own pick (`defaultCheckedIndex`); the footer's raw icon buttons are the ghost `Button`; `variant`, `side`, `openOnHover`, `contained` props |
+| — | `registry/blocks/sidebar-workspace-header.tsx` | `blocks/sidebar-app/workspace-header.tsx` | `fontVariationSettings` → `weight-semibold`, `text-[13px]` / `text-[10px]` → `text-body` / `text-micro-compact`; `defaultCheckedIndex` passed through; the peek-only trigger over the tile dropped |
+| — | `registry/blocks/sidebar-user-footer.tsx` | `blocks/sidebar-app/user-footer.tsx` | `text-[13px]` → `text-body` |
+| — | `registry/blocks/sidebar-app/search-field.tsx` | `blocks/sidebar-app/search-field.tsx` | `text-[11px]` → `text-micro` |
+| — | `registry/blocks/sidebar-app/inset-topbar.tsx` | `blocks/sidebar-app/inset-topbar.tsx` | the trigger's peek-time fade dropped (the sidebar opens on hover in flow, so the trigger stays) |
+| — | `registry/default/lib/sidebar-menu-grid.ts` | `blocks/sidebar-app/menu-grid.ts` | the width reads `--anchor-width` only; the `-ml-1` shift dropped (it would move the morph surface's content off its background) |
+
+`Select` in `modo.components.tsx` is not an item: modo's docs chrome renders its Select slot
+with a flat `value` / `onChange` / `options` contract
+(`lib/src/lib/slots.tsx`), and this adapter maps it onto
+`Select.Trigger` / `Select.Content` / `Select.Item` so the chrome runs on the
+design system's own Select. The
+`components/inputs/select` item keeps the upstream API untouched.
+
+`DocsNav` in `modo.components.tsx` is the chrome's Sidebar slot, pinned as
+`shell.Sidebar` (by name alone modo would adopt the documented `Sidebar`, an
+app shell that needs its provider). Each aside is an inset `Sidebar` with its
+own provider, and `global.css` turns the content between them into the inset
+card (the lib's grid columns become `auto`, so they follow the sidebars' width
+springs). Each provider has `openOnHover`, and its `Sidebar.Trigger` sits in
+the card's corner: the trigger, `[` for the nav and `]` for the panel, switch
+a side between open and on hover, and on hover it opens once the pointer is
+in the column under the trigger (so a browser's own edge hover sidebar stays
+out of the way). `DocsNav` owns those keys, so a demo sidebar in the content keeps them only
+while it has focus. Below md each side is a drawer; the panel starts on hover
+below xl. A section of links is a collapsible `Sidebar.Group` with one
+`Sidebar.Menu`, so the current page, the TOC's current heading and the hover
+highlight melt from link to link; a panel section (Theme) keeps its control
+under the group label.
+
+`ThemeSwitcher` in `modo.components.tsx` is not an item either: it is the `Theme` entry in
+`modo.config.ts` `panel.items`, a `Select` of Light / Dark / System (each row
+with its icon, the trigger showing the active one) that reads and sets
+`window.__uiTheme` and re-reads it on `ui:themechange`. All switching logic lives in the pre-paint controller
+described under **Tailwind → UnoCSS**, so the control holds no theme state of
+its own. `demo/scripts/run-design-systems.ts` appends its own `Switcher` panel
+item to whatever a design system declares, so both show up under the runner.
+
+## Tier mapping
+
+The tiers mirror the FF docs navigation. FF's "System" pages become
+`primitives/`; its "Components" become `components/`. Its sidebar preset
+becomes the one block.
+
+| Tier | Item | Upstream source | FF docs page |
+|---|---|---|---|
+| primitives | `surface` (Elevated, `.Provider`, `useSurface`) | `lib/elevated.tsx` + `lib/surface-context.tsx` | surfaces |
+| primitives | `scroll-area` (ScrollArea) | `base/scroll-area.tsx` | scrollbars |
+| primitives | `sizes` (SizeProvider) | `lib/size-context.tsx` | sizes |
+| primitives | `fluid-hover` (FluidHover) | `hooks/use-fluid-hover.ts` + `fluid-hover-highlight.tsx` | fluid-hover |
+| primitives | `motion` (Motion) | `lib/springs.ts` | motion |
+| primitives | `code` (Code) | — (local, sugar-high) | — |
+| primitives | `morph` (Morph) | — (local, `lib/use-morph.ts`) | — |
+| primitives | `craft` (Craft) | — (local, bad/good pairs) | skill (before/after) |
+| components | accordion, button, checkbox-group, combobox, dialog, dropdown, radio-group, select, slider, switch, tabs, tabs-subtle, tooltip | `registry/base/<id>.tsx` | same slug |
+| components | badge, card, color-picker, input-copy, input-message, table, thinking-indicator | `registry/default/<id>.tsx` | same slug |
+| components | `input` (Input, Label, InputGroup) | `registry/default/input-group.tsx` | input-group |
+| components | alert-dialog, command, context-menu, popover, preview-card, search, sheet, toast | — (local, see [Morph sources](#morph-sources)) | — |
+| components | calendar, date-picker, date-range-picker, time-picker, duration-picker, month-picker (group `inputs/date-time`) | — (local, on react-day-picker) | — |
+| components | sidebar | `base/sidebar.tsx` + `default/sidebar-core.tsx` + `default/sidebar-menu.tsx` | sidebar |
+| blocks | `sidebar-app` (SidebarApp) | the preset generator's output + `blocks/sidebar-*` | sidebar, preset `sa1FQfCxH6` |
+
+Button lives in `components/` to mirror the FF docs, and `modo.config.ts`
+points `shell.Button` at it explicitly (an explicit path skips modo's tier
+check). The chrome renders its icon buttons as `<Button variant="ghost"
+size="icon-sm">`, which works because `icon-sm` is upstream's legacy alias for
+`icon-compact`.
+
+Compound components export their root by default, with the parts attached
+as statics (`Select.Item`, `Accordion.Trigger`, …). Upstream's named exports
+are kept as well.
+
+## Omitted
+
+These are not ported: ThinkingSteps, CommandMenu, ChatMessage and
+AskUserQuestions. CommandMenu is the FF docs site's own chrome, which modo's
+shell already provides; ThinkingSteps, ChatMessage and
+AskUserQuestions are the agent-chat composites, left out of this port's scope.
+No ported file imports any of them.
+
+The files only they, or the FF docs site's nav, use are left out too:
+`mobile-drawer`, `nav-item`, `nav-menu`, `lib/theme-context.tsx` (the
+`ThemeSwitcher` panel item and vite.ts's pre-paint controller take its
+place) and the blocks other than the sidebar's (`queued-stack`,
+`dialog-sidebar`). Inside kept files, the same rule removed
+`SURFACE_HOVER_BG`, `SURFACE_HOVER_SHADOW` and `surfaceHoverClasses` from
+`surface-classes.ts` (only the Sidebar docs' callout cards used them; the
+callouts are not ported).
+
+The same goes for the docs-site-only CSS in `app/globals.css`: `.xl-fade-*`,
+`.inview-fade-block`, `.bento-*` and
+`.shiki`, plus the Tailwind directives, the self-hosted Inter `@font-face`
+and the Radix-only scroll-lock margin fix (`body[data-scroll-locked]`).
+
+`surface.css` does keep the inset shadow variants (`--shadow-light-2-inset`,
+`--shadow-light-3-inset` and the per-scheme `--shadow-2-inset` /
+`--shadow-3-inset` aliases), but no ported item consumes them and
+`preset.ts` maps no utility to them.
+
+## Tailwind → UnoCSS
+
+`uno.config.ts` uses `presetWind4` (UnoCSS's Tailwind v4 preset) and
+`preset.ts` (the theme and token utilities the package ships) with
+`outputToCssLayers`. `vite.ts` adds the UnoCSS Vite plugin to modo's Vite
+config. `scripts/build-css.ts` runs the same config over `dist/` for the
+prebuilt `styles.css`, and turns `preset.ts` into `tailwind.css`.
+
+- **Dark mode.** `dark: 'class'` produces `.dark .dark\:x`, the same "inside a
+  `.dark` ancestor" contract as FF's `@custom-variant dark (&:is(.dark *))`.
+  modo ships no theme of its own, so `vite.ts` injects a small controller into
+  `index.html` (`transformIndexHtml`, `head-prepend`). Before first paint it
+  puts `light` or `dark` on `<html>` — the stored preference, or the OS one
+  under `system` — which is also what flips every `light-dark()` token through
+  `color-scheme`. It exposes `window.__uiTheme` (`get` / `set`), persists the
+  choice in `localStorage` under `modo-ui-theme`, and fires `ui:themechange`
+  on every apply, including when the OS flips underneath `system`.
+- **Load order.** The same plugin prepends `import 'virtual:uno.css'` to
+  modo's `\0virtual:modo-config-css` module, so UnoCSS's
+  `@layer properties, theme, base, default` statement lands before
+  `global.css` (and the `base.css` it imports) and fixes the order of the
+  layer its `@layer base` rules join.
+  `vite.ts` is loaded by Node with type stripping, so it may only use erasable
+  TypeScript and hands `uno.config.ts` to UnoCSS by absolute path.
+- **Colors.** Theme colors point at the CSS variables directly (for example
+  `accent: 'var(--accent)'`, `surface.1..8`). wind4 applies opacity modifiers
+  to `var()` colors with `color-mix(in srgb, …)`, so `bg-accent/12` works on
+  the `light-dark()` tokens.
+- **Shadows.** `shadow-surface-N` maps to `var(--shadow-N)`, which is
+  re-pointed per scheme in `surface.css`.
+- **Radius.** wind4's default scale stays (`rounded-lg` = 8px). shape-context
+  pairs `rounded-lg` with 8px JS radii, so the scale must not follow
+  `--radius`.
+- **Font.** `font.sans` repeats the literal family from
+  `tokens/typography.css` rather than `var(--font-sans)`: wind4 emits theme
+  keys as same-named variables, and a self-reference would be a cycle.
+- **Type roles.** `text-display|title|subtitle|body|caption` is a custom rule
+  reading `var(--text-<role>)`.
+- **Transitions.** wind4's arbitrary `transition-[a,b]` only accepts CSS
+  properties it knows. `stroke-width` (icon stroke on hover) and
+  `font-variation-settings` (the Inter weight ladder) are added through
+  `theme.property`.
+- **Layers.** UnoCSS declares `@layer properties, theme, base, default` and
+  puts its reset in `base`. `base.css`'s `@layer base` rules join that layer
+  after the reset, so utilities (in `default`) still win. This is the same
+  arrangement as Tailwind's base/utilities split.
+- **Content.** UnoCSS scans `{lib,primitives,components,blocks}/**/*.{ts,tsx,mdx}`
+  and `modo.components.tsx` from disk (`content.filesystem`, and the same
+  globs in `content.pipeline.include`, since the default pipeline skips
+  `.ts`). Two reasons:
+  - modo serves items pre-bundled, so the sources never pass through Vite's
+    transform pipeline;
+  - example code exists only in each item's `examples.mdx`.
+
+  The class-name literal tables (`SURFACE_BG`, `sizeMap`, …) do the same job
+  for UnoCSS's extractor that they do for Tailwind's scanner.
+- **Focus.** modo's structural `shell.css` draws an unlayered `*:focus-visible`
+  outline. `global.css` reverts it with `outline: revert-layer` (and
+  `outline-offset: revert-layer`), handing focus styling back to `@layer base`
+  and the utilities, so FF's ring (1px `--focus-ring`) is the only one drawn.
+
+Every Tailwind idiom FF uses has a wind4 equivalent, among them:
+- named groups (`group-[.is-active]/row:`)
+- `has-data-[…]:`
+- arbitrary variants (`[[data-side=top]_&]:`, `[&>div[style]]:!block`)
+- `supports-[…]:`
+- arbitrary properties (`[text-box:…]`, `[--popup-enter-y:-4px]`)
+- typed arbitrary values (`ring-[color:…]`)
+- `duration-80`, `!h-auto`
+- `transition-[color,stroke-width]`, `transition-[font-variation-settings]`
+- `bg-accent/12` → `color-mix`, `shadow-surface-3`, `dark:bg-surface-2`
+- the type-role rule and wind4's unchanged `--radius-lg: 0.5rem`
+
+No upstream class string had to change. The current run covers 45 files and
+3299 class tokens (561 unique), and all of them generate.
+
+## `cn`
+
+`lib/utils.ts` exports `cn = createCn({ extend: { classGroups: {
+'font-size': ['text-display', …] } } })` from `cn/config`. `cn` is a compiled
+drop-in for clsx + tailwind-merge with the same `extend` shape.
+
+The font-size extension keeps upstream's fix. Without it, `text-body` would
+be read as a text *color*, and `cn('text-body', 'text-muted-foreground')`
+would drop the size.
+
+## Behavior additions
+
+Base UI components work both controlled and uncontrolled. The FF wrappers
+that were controlled-only gain a `default*` prop, backed by
+`lib/use-controllable-state.ts`: a component is controlled while its
+value prop is not `undefined`, and it reports every change through its
+callback either way. Where FF only had per-item callbacks, a group-level one
+was added and the item's own state props became optional.
+
+| Item | Controlled prop | Added uncontrolled prop | Added change callback |
+|---|---|---|---|
+| Accordion, Accordion.Group | `value` | `defaultValue` (semantics fixed, below) | — (`onValueChange` now also fires uncontrolled) |
+| CheckboxGroup | `checkedIndices` (now optional) | `defaultCheckedIndices` (`Set` or array) | `onCheckedIndicesChange` |
+| Dropdown, Dropdown.Content | `checkedIndex`, `checkedIndices` | `defaultCheckedIndex`, `defaultCheckedIndices` | `onCheckedIndexChange`, `onCheckedIndicesChange` |
+| Input, InputGroup.Field | `value`, `onChange` (now optional) | `defaultValue` | — |
+| InputMessage | `value`, `files`, `queue`, `status` | `defaultValue`, `defaultFiles`, `defaultQueue`, `defaultStatus` | `onValueChange` optional; `onStatusChange` added |
+| RadioGroup | `selectedIndex`, `value` | `defaultSelectedIndex`, `defaultValue` | `onSelectedIndexChange` (`onValueChange` now also fires uncontrolled) |
+| Slider | `value`, `onChange` (now optional) | `defaultValue` | — |
+| Switch | `checked`, `onToggle` (now optional) | `defaultChecked` | `onCheckedChange` |
+| Sidebar | `value` (new: the row whose `value` is selected) | `defaultValue` | `onValueChange` |
+| Sidebar.MenuItem `collapsible` | `open` (new: its sub-menu; upstream's docs held it in page state) | `defaultOpen` | `onOpenChange` |
+| Tabs | `value`, `selectedIndex` | `defaultSelectedIndex` (`defaultValue` is upstream's) | — |
+| TabsSubtle | `selectedIndex`, `onSelect` (now optional) | `defaultSelectedIndex` | — |
+
+Already uncontrolled upstream and left on their own internal state (none of
+these go through `useControllableState`): Select `defaultValue` — checked
+explicitly, see its file header — ColorPicker and ColorPicker.Popover
+(`defaultValue`, `defaultFormat`, `defaultFormatOpen`, `defaultOpen`),
+Combobox `defaultValue`, Tabs `defaultValue`, and the `defaultOpen` of
+Dropdown.Menu. Dialog's `open` / `defaultOpen` now go through
+`useControllableState`, because the morph reads the open state.
+
+Notable local behavior changes beyond the `default*` props:
+
+| Item | Change |
+|---|---|
+| Accordion | Upstream treated the presence of `onValueChange` as "controlled", so an uncontrolled accordion with a listener never opened. Now `value` alone controls, and `defaultValue` seeds an accordion that still reports changes. |
+| RadioGroup | The group context carries a `selectIndex` setter that every item selection calls (after its own `onValueChange` / `onSelect`), so items need no `selected` / `onSelect` of their own. |
+| CheckboxGroup | The group context carries the checked set plus a setter; an item's toggle always reports to the group as well. |
+| TabsSubtle | Panels may now be written inside `<TabsSubtle>`: the root partitions its children, keeps the tabs inside the tab list and renders the panels as its siblings right after it (the root element *is* the `role="tablist"`, so panels cannot nest in it). A panel with no `selectedIndex` / `idPrefix` reads both from context, the prefix falling back to a `useId()` one; a panel rendered outside `<TabsSubtle>` still takes them as props. |
+| Dropdown | `Dropdown.Search` with `filter` hands the query to the panel, which drops the `Dropdown.Item` rows whose `label` doesn't match, re-indexes the survivors for fluid hover, and shows `Dropdown.Empty` only when nothing matched — the work the controlled form asks the consumer to do. Selection stays keyed on the authored index (`sourceIndex`), so it survives re-indexing. |
+| Combobox | `creatable` offers the create row with no callback and the component keeps the items it makes (merged into `items`, deduped by value), so a combobox can grow its own list; `onCreate` is unchanged and still wins when it returns an item. The root is also no longer generic — see the file map. |
+| InputMessage | Attachments are enabled by `onFilesChange` **or** `defaultFiles`; the queue by `onQueueChange` **or** `defaultQueue` (still only alongside a status). With the status uncontrolled the Stop control is offered even without `onStop` and flips the status to `"idle"` itself, which is the edge that auto-dispatches the head of the queue. An uncontrolled draft and file list clear themselves after `onSend`. |
+| Card | `next/link` is gone: the stretched card link and `CardButton`'s `href` form render plain anchors. Examples use inline `data:image/svg+xml` gradients instead of real image files. |
+| Dialog, Select, Combobox | Statics are attached as expando properties (`Dialog.Trigger = …`) rather than through `Object.assign`, so TypeScript infers them without a cast and `check-items` can see them. |
+
+## Dependency deltas (vs upstream `package.json`)
+
+| Upstream | Here | Why |
+|---|---|---|
+| `tailwindcss`, `@tailwindcss/postcss` ^4 | `unocss` 66.10.5 (pinned) | UnoCSS instead of Tailwind |
+| `clsx`, `tailwind-merge` | `cn` ^0.3.0 | Compiled drop-in |
+| `framer-motion` ^12 + `motion` ^12 | `motion` ^13.4.0 | One package; imports use `motion/react` |
+| `@base-ui/react` ^1.4.1 | `@base-ui/react` 1.4.1 (exact) | FF styling relies on its `--anchor-width`, `--available-height` and `data-side` hooks |
+| `lucide-react` ^0.564 | `lucide-react` ^1.47.0 | Workspace version; `icon-context`'s `size`/`strokeWidth` widened to `number \| string` for it |
+| `react` / `react-dom` ^19 | ^18.3 | The workspace pins React 18. React 19's ref typings are adapted per file: `MutableRefObject` casts where a forwarded ref is written, `useRef<T \| null>(null)` instead of the 1-arg null form, and `FilePreviewTile` turned into a `forwardRef` (React 19 passes `ref` as a plain prop; React 18 warns and drops it). |
+| self-hosted `InterVariable.ttf` | `@fontsource-variable/inter` ^5.3.0 (`opsz.css`) | npm-distributed. The opsz axis is needed by the `--weight-*` ladder. |
+| `pdfjs-dist` ^5.7.284 | same | InputMessage PDF thumbnails. It bundles under modo's esbuild as a lazy ~790 kB chunk; the worker is loaded from `cdn.jsdelivr.net`, as upstream does. |
+| `class-variance-authority` ^0.7.1 | same | |
+| `next` (`next/link`, `next/image` lint) | — | No Next.js here |
+| — | `@justanarthur/modo` (workspace) | The design system's own host |
+| — | `sugar-high` ^2.5.1 | Tokenizer for the local `primitives/code` item |
+| — | `react-day-picker` ^10.0.2, `date-fns` ^4.4.0 | The calendar under the date pickers, and its date math, formats and locales (`react-day-picker/locale`); date-fns is declared because the pickers import it directly |
+| — | `vite` ^5.4, `esbuild` ^0.20, `typescript` ^5.4, `@types/react(-dom)` ^18.3 (dev) | `vite` ^5.4 makes UnoCSS's peer reuse modo's Vite 5. The others serve the scripts and `tsc`. |
+
+Every import is declared here, because bun's isolated linker only exposes
+declared packages.
+
+## Docs and examples
+
+What modo's parser (`lib/src/lib/tsdoc.ts`) and example compiler
+(`lib/src/lib/example.ts`) need, and how this package answers it:
+
+- **The item is the file's `export default`** — either `function X(…)` or a
+  `const X = forwardRef<HTMLXElement, XProps>(…)`. The forwardRef form's first
+  type argument must contain no `<` or `,`, which is why ScrollArea spells out
+  `HTMLDivElement` instead of `ComponentRef<typeof …>`, and why Combobox's
+  root lost its generics.
+- **Props come from a same-file `interface XProps`**, and only from members
+  declared in its body — inherited members are invisible, and a member whose
+  type spans several lines is dropped. Every member needs a description, and
+  defaults are read from that prose (`Defaults to \`false\`.`), not from the
+  destructuring. Hence the FF API-table text re-declared on every prop.
+- **Examples live in `examples.mdx`** next to the item, included by the
+  TSDoc's `@example {@include ./examples.mdx}`: a `# <FF section title>`,
+  an optional caption, then one JSX block (or a fenced code block for code to
+  read). Expressions are plain JS (no `as const`), and multi-line JSX text
+  stays inline (modo unwraps MDX's paragraphs inside examples).
+- **Examples are hook-free JSX.** Nothing runs a component body, so
+  interactivity in the docs comes from the `default*` props above instead of
+  `useState`.
+- **Imports are real**: the item is `./index`, other items are
+  `../../<tier>/<id>` (one `../` more from or to a group folder), icons come from `lucide-react`. Every free identifier
+  must be imported (or be an item name or a JS/DOM global), and every
+  `Item.Part` used must really be attached to that item.
+
+Each item follows its FF docs page: the TSDoc holds the one-liner, a concept
+paragraph and the list of statics; `examples.mdx` holds one `# <FF section
+title>` example per docs section. Playground and API Reference sections are never ported (the API
+tables become the prop docs instead). Other per-item deviations:
+
+| Item | Docs deviation |
+|---|---|
+| Button | Extra Sizes / Active / As-child examples, for API-table props the FF page has no section for. |
+| Dialog | "With a sidebar" replaced by "Surfaces inside a dialog" (a Select popover lifting off the dialog's own level) — the same point about composing inside an `xl` panel, with items this port ships. |
+| Sidebar | Layouts split into three examples; "Callouts" (docs-only cards), "Inside a dialog", the "No icon rail" prose (folded into the TSDoc) and "Functional and perfectly aligned" (an alignment-guides overlay) skipped; "Mobile drawer" added. Frames pass `mobileBreakpoint={0}` like FF's, so a rail stays a rail inside them. |
+| SidebarApp | One block page for FF's preset playground: the preset itself (collapsed), open, open on hover, floating on the right. |
+| Dropdown | "Create from the query" skipped: adding a row to the list is real consumer state, which an uncontrolled panel cannot stand in for. |
+| InputMessage | Playground skipped; the transcript around the Attachments / Send Handler demos dropped, since `ChatMessage` is not ported. |
+| FluidHover | The two scripted-cursor demos are dropped — they exist only to film the mechanism. |
+| SizeProvider | Live demos become static examples; the token-inspector overlay is dropped and the demo components are swapped for ones this port ships. |
+| Motion | The ball-on-track and fake-modal visuals become a show/hide of arbitrary children; component chips are plain text. |
+| Card | Images are inline `data:image/svg+xml` gradients. |
+
+## Known limitations
+
+- The 22px mobile display size and the `html[data-size="compact"]` type-scale
+  override are not carried over. Both are FF docs-site chrome. Compact type
+  reaches components through `SizeProvider` / `useTypeScale()`.
+- Theme switching is docs-site glue, not a ported `ThemeProvider`: vite.ts's
+  pre-paint controller and the `ThemeSwitcher` panel item. A `.light` /
+  `.dark` class on a subtree still forces that scheme, which is what the
+  forced-theme previews use.
+- `transition-[…]` with a CSS property outside wind4's list needs a
+  `theme.property` entry in `preset.ts`.
+- Cross-item context (a `SizeProvider` example shrinking a Button, a surface
+  level crossing from Dialog into Dropdown) depends on modo bundling the whole
+  design system in **one** esbuild build with `splitting: true`, so a shared
+  module exists once at runtime. The output lives in this package's
+  `.modo-tmp/build`, which is keyed on the package and not on the port: two
+  `modo dev` servers started in this directory share it. `run-design-systems.ts`
+  avoids that by killing stray `modo dev` processes before it starts.
+- PDF thumbnails in InputMessage need network access: the pdfjs worker is
+  fetched from `cdn.jsdelivr.net` on the first PDF attachment.
+- The inset shadow tokens in `surface.css` are dead weight today — they ship,
+  but nothing in this package reads them.
+
+## How to run
+
+```sh
+cd demo && bun scripts/run-design-systems.ts ui   # http://127.0.0.1:5173
+```
+
+The runner kills stray `modo dev` processes, splices a temporary
+`.modo.config.ts` with the demo switcher panel, and assigns ports from 5173
+upward. To run the package on its own, without the switcher:
+
+```sh
+cd ui && MODO_PORT=5180 bunx modo dev
+```
+
+## How to verify
+
+```sh
+cd ui && bunx tsc -p . --noEmit
+```
+
+modo reports parser and build problems itself, as `[modo:bundle]` lines in
+the dev server's output.