@kennycorrea/ui 0.9.1 → 0.11.0

package/README.md

@@ -1,350 +1,281 @@
 # @kennycorrea/ui
 
-Upfront's house component layer: the atoms over Radix Themes, the token bridge, and the accent
-logic. Shared by the dashboard (`upfront-web-app`), the marketing site (`upfront-web-site`) and
-the admin app (`upfront-admin`).
-
-**The product brief, the roadmap and every design document live in the `upfront` repository**,
-not here. This file covers only what is true about this package.
-
-## Why it exists
-
-Two apps said `variant="secondary"` and `text-ink-muted`, and each carried its own copy of what
-those meant. `docs/ecosystem.md` in the product repository called starting a third app the
-trigger, and this is the trigger being pulled.
-
-**The drift, measured rather than assumed.** It was real, and it was concentrated in the
-components rather than the colours:
-
-| | dashboard | site | visible? |
-| --- | --- | --- | --- |
-| `Button` `secondary` | Themes' `soft` | Themes' `surface` | **yes** |
-| `danger` variant | yes | absent | **yes** |
-| sizes | `sm`/`md`/`lg` | raw Themes `1`–`4` | **yes** |
-| `href` prop | absent | yes | **yes** |
-| `--font-sans` | `'Inter', …` | `ui-sans-serif, …` | no — neither app loads Inter |
-| `--color-ink` fallback | `#1d3b31` | `#1a211f` | only if Radix's CSS fails to load |
-| `--color-hairline` fallback | 12% | 10% | same |
-
-The `.radix-themes` blocks — the *live* colour assignments — had been kept in step by hand and
-agreed. It was the `@theme` fallbacks underneath them that had not, which is drift that is real
-and invisible: the least urgent kind and the easiest to leave lying around for years.
-
-So the honest case for this package is the component API, not the palette.
-
-## The Button disagreement, resolved
-
-**`secondary` now means exactly one thing: Themes' `soft`.** The site's bordered, translucent
-look is still available and is called **`outline`**.
-
-Making one of them simply win would have been a decision about the word rather than about the
-need — the site wants the bordered button because it sits over a dark hero, and the dashboard
-wants the tinted one because it sits on a panel. Both needs are real; only the name was
-ambiguous.
-
-The package's `Button` is the superset: `loading`, `fullWidth`, ref forwarding and `danger` from
-the dashboard, `href` from the site. Nothing was dropped.
-
-## Using it
-
-```ts
-import { Button, Card, Select, UiStringsProvider } from '@kennycorrea/ui';
+A small React + TypeScript component library built on top of
+[Radix Themes](https://www.radix-ui.com/themes). It wraps Radix's components in a consistent,
+opinionated API, adds a few components Radix does not ship, and bridges Radix's design tokens to
+Tailwind utilities.
+
+- **Atoms** — `Button`, `Input`, `Select`, `Checkbox`, `Switch`, `Slider`, `Dialog`, `Drawer`,
+  `Popover`, `Tooltip`, `Toast`, `NotificationCard`, `RichText` and more.
+- **Primitives** — Radix Themes' layout and typography components, re-exported.
+- **Tokens** — `tokens.css` maps Radix Themes variables to Tailwind colour utilities.
+- **Theming** — light/dark/system appearance and a configurable accent list.
+- **No words of its own** — the few strings components need come from `UiStringsProvider`.
+
+## Install
+
+```bash
+npm install @kennycorrea/ui @radix-ui/themes react react-dom
 ```
 
-And in the app's own `index.css`:
+In your stylesheet:
 
 ```css
 @import 'tailwindcss';
 @source '../node_modules/@kennycorrea/ui/dist';
+@import '@radix-ui/themes/styles.css';
 @import '@kennycorrea/ui/tokens.css';
 ```
 
-⚠ **The `@source` line is not optional.** Tailwind does not scan `node_modules`, so without it
-every utility class used *inside* the atoms — `w-full`, `inline-flex` — is missing from the
-generated CSS. The components come out subtly unstyled and nothing appears in the console.
-
-### Colour scales — required
+The `@source` line matters: Tailwind does not scan `node_modules`, so without it the utility
+classes used inside the components are missing from the generated CSS.
 
-The atoms name five Radix scales: **gray**, **jade** (`Badge` success, `Toast` success),
-**amber** (warning), **red** (danger/error) and **blue** (`Toast`/`Alert` info). If the app
-imports Radix Themes piecemeal rather than the whole `@radix-ui/themes/styles.css`, every one of
-them must be imported, **after `base.css`** as Radix documents it, plus the app's own accent:
+Wrap the app in Radix's `<Theme>` and, optionally, `UiStringsProvider`:
 
-```css
-@import '@radix-ui/themes/tokens/base.css';
-@import '@radix-ui/themes/tokens/colors/gray.css';
-@import '@radix-ui/themes/tokens/colors/jade.css';
-@import '@radix-ui/themes/tokens/colors/amber.css';
-@import '@radix-ui/themes/tokens/colors/red.css';
-@import '@radix-ui/themes/tokens/colors/blue.css';
-/* …the accent the app offers, if not one of the above */
-@import '@radix-ui/themes/components.css';
-@import '@radix-ui/themes/utilities.css';
+```tsx
+import { Theme } from '@radix-ui/themes';
+import { Button, UiStringsProvider } from '@kennycorrea/ui';
+
+<Theme appearance="dark" accentColor="teal">
+  <UiStringsProvider strings={{ close: 'Fechar', expand: 'Expandir', collapse: 'Recolher' }}>
+    <Button>Save</Button>
+  </UiStringsProvider>
+</Theme>;
 ```
 
-A missing scale is not an error to CSS — the variables are just undefined, and badges and toasts
-render colourless. Since 0.8.1 the first `Badge` or `Toaster` to mount checks for them and
-`console.warn`s the missing imports by name, outside production builds.
+### Colour scales
 
-## Theming — 0.2.0
+If you import Radix Themes piecemeal instead of `styles.css`, import **gray**, **jade**, **amber**,
+**red** and **blue** (used by status variants) plus your accent, after `base.css`. A missing scale
+is not a CSS error — the variables are just undefined — so in development the first `Badge` or
+`Toaster` to mount warns about missing scales in the console.
 
-**A product configures its own accents, default and storage namespace.** Until 0.2.0 all three
-were hardcoded to the first app that used this package: the fallback accent was jade, the accent
-list was six fixed colours, and preferences were stored under `upfront.theme` / `upfront.accent`.
+## Theming
 
 ```ts
-// Once, in the app.
+import { createTheming, applyTheme } from '@kennycorrea/ui';
+
 export const theming = createTheming({
   accents: ['teal', 'crimson'],
-  defaultAccent: 'teal',
-  storagePrefix: 'myapp',
+  defaultAccent: 'teal', // must be one of `accents` — a type error otherwise
+  storagePrefix: 'myapp', // required: namespaces stored preferences
 });
 
 theming.readAccent(); // 'teal' | 'crimson'
 ```
 
-Any Radix accent name works, and a product with one brand colour passes one. The list is the
-order a picker should render.
+Every accent you offer needs its Radix colour scale imported.
 
-**`defaultAccent` is typed as a member of `accents`**, so naming one that is not on the list is
-`TS2322` rather than a colourless first paint — verified by compiling the mistake.
+### Dark mode and portals
 
-**The literal array needs no `as const`**; the `const` type parameter infers the tuple. A list
-declared separately does, because `const list = ['teal']` widens to `string[]` and is rejected.
+Radix Themes defines its colour variables (`--color-panel-solid`, `--gray-*`, `--accent-*`, …)
+only on and under the `.radix-themes` element that `<Theme>` renders, and switches light/dark
+with a `.light`/`.dark` class on that element. **Anything rendered outside it gets light colours,
+or none, whatever appearance the app is in.**
 
-⚠ **`storagePrefix` is required and has no default.** A default would be one product's name
-silently storing another's preferences, and because separate origins never collide, nothing would
-ever reveal it.
+So no component in this library portals to `document.body`. Floating components (`Drawer`,
+`NotificationCard`) portal into the nearest `.radix-themes` ancestor, wrapped in a nested
+`<Theme>` that inherits appearance and accent — or into a `container` you pass — and render in
+place when there is no Theme above them. Their colours, borders and shadows use only theme
+variables: the appearance is whatever `<Theme>` says, never `prefers-color-scheme`.
 
-⚠ **Every accent needs its Radix colour scale imported** in the app's `main.tsx` — see Colour
-scales below. A missing scale is not an error; it is a colourless app.
+Do the same in your own code: set appearance on `<Theme>`, not with a `dark` class on
+`<html>`/`<body>`.
 
-**A factory, not a `configure()` call.** Module-level mutable state would have to be written
-before the first read, making correctness depend on import order — the same class of silent bug as
-the CSS import order this package already has to warn about. An instance cannot be read before it
-is made.
+## Strings
 
-`applyTheme` stays a free function, because `data-theme` is the contract between it and
-`tokens.css` rather than a preference: two apps disagreeing about the attribute name would each
-need their own stylesheet.
+Components never contain literal text. The handful they need — a spinner's label, a select's
+placeholder, close/expand/collapse names — come from `UiStringsProvider`, which takes a partial
+`UiStrings` object. Defaults are English. Most components also accept the label as a prop.
 
-### What still works unchanged
+## Mobile presentation layer
 
-`readTheme`, `storeTheme`, `readAccent` and `storeAccent` are still exported as free functions,
-bound to an instance with the six default accents, jade, and the `upfront.*` keys. **One
-implementation, not two** — they are literally a pre-made instance, so no call site had to change
-and nobody who already picked a theme loses it. `ACCENTS` remains as a deprecated alias for
-`DEFAULT_ACCENTS`, the same array.
+An opt-in "grouped" surface style — rows in rounded cards on a tinted canvas, as in native
+settings screens. Nothing existing reads these tokens, so atoms render exactly as before.
 
-A new product should call `createTheming` with its own name rather than inherit those.
+| Token | Value |
+| --- | --- |
+| `--surface-grouped` | Card background (white / gray-3 in dark), no border |
+| `--canvas-grouped` | Tinted page background (gray-3 / gray-1 in dark) |
+| `--separator-inset` | Hairline for row separators |
+| `--radius-group` | 12px |
+| `--space-row-y` / `--space-row-x` | 10px / 12px |
+| `--tap-min` | 44px |
+| `--safe-top/right/bottom/left` | `env(safe-area-inset-*)`, `0px` fallback |
+| `--material-bar`, `--material-bar-filter` | Translucent bar colour and `saturate(180%) blur(20px)` |
 
-## What is deliberately not here
+Tailwind utilities: `bg-grouped`, `bg-canvas-grouped`, `border-separator-inset`, `rounded-group`,
+`min-h-tap`, `pt-safe`, `pb-safe`, `px-safe`, `bg-material`.
 
-- **Dictionaries.** Words belong to an app. The two strings the atoms say on their own behalf —
-  a standing spinner's label and an empty select's placeholder — come from `UiStringsProvider`,
-  which each app feeds from its own dictionary. Defaults are English so a host that forgets to
-  wrap gets something legible rather than something wrong.
-- **Auth, stores, API clients.** Same reason, and they were never shared.
-- **`ACCENT_LABELS`.** The accent *list* is structure and lives here; what each one is called is
-  words and does not.
-- **Molecules and organisms.** `FormField`, `ConfirmDialog` and the rest stay in the dashboard
-  until a second app wants one. Moving a component here should be a response to a second
-  consumer, not an anticipation of one.
+Gray-11 and gray-12 text pass WCAG AA on the card, the canvas and the bar (over white or black
+content) in both appearances — see `test/grouped.test.tsx`. Remember `viewport-fit=cover` in the
+viewport meta, or the safe-area insets are always 0.
 
-## Colour scales
+**Before** — a bordered panel:
 
-Each app imports only the Radix colour scales it uses, in `main.tsx`, and **the import order is
-load-bearing** — scales define `--gray-*` literally and `base.css` remaps it onto the chosen
-`grayColor`, so `base.css` must come last. Adding an accent to `ACCENTS` means adding its scale
-in every app that offers it, or it resolves to nothing.
-
-## ⚠ 0.1.0 was broken for any Node consumer
+```tsx
+<div className="panel p-4">
+  <button className="py-2">Profile</button>
+</div>
+```
 
-**Fixed in 0.1.1.** The package compiled with `moduleResolution: bundler`, which leaves relative
-imports extensionless in the output — `export * from './atoms'`. Vite resolves that happily, so
-every build passed and the linked `file:../ui` setup never complained. **Node does not support
-directory imports**, so the moment the package was installed from the registry it failed:
+**After** — a grouped list under a blurred bar:
 
-    Directory import '…/@kennycorrea/ui/dist/atoms' is not supported
-    resolving ES modules imported from …/@kennycorrea/ui/dist/index.js
+```tsx
+<div className="min-h-screen bg-canvas-grouped px-safe">
+  <header className="bg-material pt-safe sticky top-0">Settings</header>
+  <ul className="rounded-group bg-grouped mx-3 divide-y divide-separator-inset">
+    <li><button className="min-h-tap w-full px-3 text-left">Profile</button></li>
+    <li><button className="min-h-tap w-full px-3 text-left">Notifications</button></li>
+  </ul>
+  <div className="pb-safe" />
+</div>
+```
 
-It surfaced in the dashboard's Vitest run, which resolves dependencies with Node semantics. A
-bundler-only consumer would never have noticed, which is why it shipped.
+## Components
 
-The fix is the rule this project already applies in `api/`, whose own brief states it: **an
-explicit `.js` on every relative import**, and `/index.js` for a directory. `tsconfig.json` is now
-`moduleResolution: nodenext`, so `tsc` *refuses* the extensionless form — verified by putting one
-back and watching it error — rather than silently emitting it again.
+### Toast
 
-⚠ **The lesson is about what "the build passes" is worth.** Three apps built, 46 tests passed and
-a browser check confirmed the styling, all while the package was unimportable by Node. Nothing was
-wrong with those checks; they simply all went through the same bundler. The first consumer with
-different resolution semantics found it immediately.
+Mount `<Toaster />` once inside `<Theme>` and call `toast()` from anywhere.
 
-## Releasing
+```tsx
+<Toaster duration={5000} position="bottom-right" />
 
-`npm run build` compiles to `dist/` with type declarations. The version in `package.json` is the
-contract: bump it, and bump the dependency in each consumer.
+toast({ title: 'Saved' });
+toast.success({ title: 'Moved', description: 'Tue 14:30' });
+const id = toast.error({ title: 'Payment failed', duration: Infinity });
+toast.info({ title: 'Deleted', action: { label: 'Undo', onClick: restore } });
+toast.dismiss(id);
+```
 
-**`files` in `package.json` is the published surface**: `dist`, `tokens.css` and this README.
-`src` is deliberately not in it — consumers import from `dist`, and shipping the TypeScript
-source as well would let an app import a path that bypasses the build and the types.
+`position` also takes `'top-center'` and `'bottom-center'`; centred stacks swipe away vertically
+(towards their edge). `offset` is the distance from the anchored edge and accepts any CSS length, so
+the stack can clear a bar: `<Toaster position="top-center" offset="var(--navbar-height)" />`, or
+`<Toaster position="bottom-center" offset="calc(var(--tabbar-height) + 8px)" />`.
 
-`prepublishOnly` runs the build, so `npm publish` cannot ship a stale `dist` — which would
-otherwise publish silently, with a version number that says nothing about it. `dist/` is
-gitignored and present in the tarball, which is the right way round: the build output is not
-worth reviewing in a diff and is worth shipping.
+### Touch feedback and sizing
 
-**The scope is `@kennycorrea` on npm.** `upfront` was not available, so the account was converted
-into an organisation. Settling that before the first publish rather than after was worth doing:
-the name is an import line in three apps, so renaming it was free today and would have cost a
-major version and three coordinated bumps after a release.
+- Button, list rows, `StatTile` and `TabBar` items share one pressed state: `:active` scales to
+  `--press-scale` (0.97) with a gray tint over `--press-duration` (120 ms); off under
+  `prefers-reduced-motion`. Our hover styles are inside `@media (hover: hover)`.
+- `<Button size="touch">` has a 44px minimum height. `<Button iconOnly variant="ghost">` keeps its
+  visual size but gets a 44px hit area on coarse pointers.
+- `Input`, `Textarea` and `Select` render at 16px on coarse pointers so iOS does not zoom on focus.
+  `inputMode` and `enterKeyHint` on `Input` / `Textarea` pass through to the native element:
+  `<Input type="text" inputMode="decimal" enterKeyHint="done" />`.
 
-GitHub Packages was the alternative and would have forced `@kennyrafael/ui`, because it requires
-the scope to match the repository owner. `publishConfig.access: "public"` is set, because a scoped
-package defaults to restricted and restricted needs a paid plan.
+### NotificationCard
 
-### The publish workflow
+A persistent rich toast: it floats in a viewport corner and stays until it is closed.
 
-`.github/workflows/npm-publish.yml`: a `build` job that runs `npm test`, then `publish-npm`
-which needs it.
+```tsx
+import { Button, NotificationCard } from '@kennycorrea/ui';
+
+const [open, setOpen] = useState(true);
+
+<NotificationCard
+  position="bottom-right" // bottom-left | top-right | top-left
+  open={open}
+  onOpenChange={setOpen}
+  onDismiss={(reason) => track(reason)} // 'close-button' | 'escape' | 'programmatic'
+  icon={<AppIcon />}
+  title="Add this app to your computer"
+  description="Open it like any other app."
+  expandLabel="Show me how"
+  collapseLabel="Hide steps"
+  actions={<Button onClick={install}>Install</Button>}
+>
+  <ol>
+    <li>Open the browser menu</li>
+    <li>Choose "Install app"</li>
+  </ol>
+</NotificationCard>;
+```
 
-⚠ **Pushing to `main` does not publish, and is not meant to.** The trigger is
-`release: [created]` — a GitHub *release*, which means a tag and a release object. A commit on
-`main` fires nothing and leaves no run in the Actions tab, which looks identical to a broken
-workflow. `workflow_dispatch` is also enabled, so the first publish and any retry can be run from
-the Actions tab without inventing a version to hang a release off.
+- **Never auto-dismisses.** Controlled (`open`/`onOpenChange`) or uncontrolled (`defaultOpen`).
+- **Slots**: `icon`, `title`, `description`, `children` (collapsible body), `actions` (footer).
+- **Collapsible body** with a built-in toggle (`aria-expanded`/`aria-controls`), controlled
+  (`expanded`/`onExpandedChange`) or uncontrolled (`defaultExpanded`). Labels come from
+  `expandLabel`/`collapseLabel` or the `expand`/`collapse` strings.
+- **Close** button named by `closeLabel` or the `close` string. `onDismiss` reports why it
+  closed; a controlled `open` set to `false` by the host is `'programmatic'`.
+- **Non-modal**: no focus trap, the page stays interactive, and Escape closes it only while focus
+  is inside it.
+- **Quiet**: a `section` labelled by its title and described by its description — not
+  `role="alert"` or a live region, so it is not announced on every page load.
+- 16px from the corner, `min(24rem, 100vw - 2rem)` wide, above page content and below dialogs.
+  Enters and exits with a transform, switched off under `prefers-reduced-motion`.
+- Themed as described under [Dark mode and portals](#dark-mode-and-portals); pass `container`
+  to choose the portal target.
 
-Two things that fail at the `npm publish` step rather than earlier, and are worth checking before
-blaming the workflow:
+Full example, in light and dark: `examples/NotificationCards.tsx`.
 
-- **The token must be a repository or organisation Actions secret**, not an account-level one.
-  GitHub's account-level secrets are for Codespaces; Actions reads repository, environment and
-  organisation secrets. The step references `secrets.npm_token`, and secret names are
-  case-insensitive, so `NPM_TOKEN` matches.
-- **It must be an npm _Automation_ token** (or a granular token with publish rights). A classic
-  *Publish* token fails with `EOTP` the moment the account or org requires 2FA for publishing,
-  because there is no one there to type a one-time password. That failure reads like a bad
-  credential and is not one.
+### Drawer
 
-⚠ **`npm test` has to keep existing.** It is lint, a typecheck and (since 0.5.0) the Vitest suite — and
-it is load-bearing for a reason that has nothing to do with quality:
-without a `test` script the `build` job fails on `Missing script: "test"`, `publish-npm` never
-runs because it needs `build`, and **the release publishes nothing while looking like it worked.**
-That was the state when the workflow was first added.
-
-### Where it is consumed from today
+A bottom sheet with `collapsed`/`expanded` snap points and a draggable handle.
 
-✅ **All three apps depend on a version from the registry**, as of 2026-09-30. The
-`file:../ui` arrangement is gone, and each app now builds on Vercel from its own repository.
+```tsx
+// Non-modal: floating banner, page stays usable.
+<Drawer mode="non-modal" title="Get started" peek={<p>Swipe up.</p>}
+  footer={<Button>Start</Button>}>
+  <ol>…</ol>
+</Drawer>
 
-```jsonc
-// a new consumer
-"@kennycorrea/ui": "^0.2.0"
-
-// web, site and admin, still — see the note below
-"@kennycorrea/ui": "^0.1.1"
+// Modal: scrim, focus trapped, page inert; Escape and the scrim close it.
+<Drawer open={open} onOpenChange={setOpen} defaultSnap="expanded" title="New item"
+  showCloseButton>
+  <form>…</form>
+</Drawer>
 ```
 
-⚠ **Never floor a range at 0.1.0** — its published output cannot be imported by Node. `^0.1.0`
-resolves correctly today because npm picks the newest match, but a range whose floor is unusable
-documents nothing and would let a lockfile built from scratch land back on it.
-
-⚠ **Under `0.x`, `^` does not cross a minor.** `^0.1.1` will **not** take 0.2.0, so moving a
-consumer onto the new theming API is a `package.json` change in each app, not just a lockfile
-refresh. The free functions still work, so an app that does not need `createTheming` can stay
-where it is — and the three existing apps deliberately do, for now. Moving them is a one-line
-change each plus a lockfile, worth doing to stop three consumers drifting a minor behind, and
-worth doing as its own commit rather than inside this one.
+Snap and open state are controllable (`snap`/`onSnapChange`, `open`/`onOpenChange`). The handle
+is a real button with `aria-expanded`. Example: `examples/Drawers.tsx`.
 
-⚠ **A `file:` install was a symlink; a version install is a copy.** Edits here no longer appear in
-a consumer. An app that needs an unreleased change wants `npm link` or a temporary `file:`
-override — never a copied file, which is the drift this package exists to end.
+### Sheet and ResponsiveDialog
 
-## Toasts — 0.3.0
-
-Mount `<Toaster />` once, inside `<Theme>`, and call `toast()` from anywhere — it is a factory
-over a module-level store, so each call stacks another toast and returns its id.
+`Sheet` is a bottom sheet on Radix Dialog (focus trap, Escape, scrim and `aria-modal` are
+Radix's). `detent` is `'medium'` (50% of the visible viewport), `'large'` (92%) or `'fit'` (the
+content, capped at 90%). Pass `detents` to let the user move between several; dragging down from
+the lowest dismisses.
 
 ```tsx
-<Toaster duration={5000} position="bottom-right" />
+<Sheet open={open} onOpenChange={setOpen} title="New booking" detents={['medium', 'large']}
+  defaultDetent="medium" scaleBackground footer={<Button>Save</Button>}>
+  <form>…</form>
+</Sheet>
 
-toast({ title: 'Saved' });                                    // info by default
-toast.success({ title: 'Booking moved', description: 'Tue 14:30' });
-toast.warning({ title: 'Close to the IVA ceiling', duration: 10_000 });
-const id = toast.error({ title: 'Payment failed', duration: Infinity });
-toast.info({ title: 'Cancelled', action: { label: 'Undo', onClick: restore } });
-toast.dismiss(id); // or toast.dismiss() for all
+<ResponsiveDialog open={open} onOpenChange={setOpen} title="Edit" sheetDetent="large"
+  footer={<Button>Save</Button>}>…</ResponsiveDialog>
 ```
 
-`duration` overrides the `Toaster` default per toast. An action closes the toast after its
-`onClick` unless `keepOpen` is set. Passing an existing `id` replaces that toast in place.
-The close button's name comes from `UiStrings.dismiss`, so feed it through `UiStringsProvider`.
+A flick faster than 0.5 px/ms, or a drag of 25% of the height, dismisses. The body scrolls
+normally and hands the gesture to the sheet only when it is at its top and pulled down. The footer
+clears `--safe-bottom` and follows `visualViewport`, so it and the focused field stay above the
+on-screen keyboard. `scaleBackground` scales the rest of the Theme at `large`; a transformed
+ancestor re-parents `position: fixed` descendants, so fixed bars in the page scale with it.
+`ResponsiveDialog` takes `Dialog`'s props plus `sheetDetent` and is a Dialog at `md` (768px) and
+up; crossing the breakpoint while open remounts `children`, so keep form state in the parent.
 
-## Slider — 0.4.0
+### Slider
 
-A thin wrap of Radix Themes' `Slider` at size `2`, like the other atoms. `label` is required and
-becomes the `aria-label`, because a slider has no visible text of its own.
+`label` is required and becomes the `aria-label`. Values are arrays, one per thumb.
+`fillFrom` fills from a value to the thumb; `marks` adds labelled ticks.
 
 ```tsx
-<Slider label="Reminder lead time (hours)" min={1} max={48} step={1}
-  value={[hours]} onValueChange={([h]) => setHours(h)} />
-<Slider label="Price range" defaultValue={[10, 60]} min={0} max={200} /> // two thumbs = range
+<Slider label="Lead time (hours)" min={1} max={48} value={[h]} onValueChange={([v]) => setH(v)} />
+<Slider label="Cycle" min={0} max={29} value={day} onValueChange={setDay} fillFrom={16}
+  marks={[0, 16, 29].map((value) => ({ value, label: String(value) }))} />
 ```
 
-Values are arrays, as in Radix: one entry per thumb.
+## Development
 
-## Slider fill origin and marks — 0.5.0
-
-```tsx
-const marks = [0, 6, 11, 16, 22, 29].map((value) => ({ value, label: String(value) }));
-<Slider label="Budget cycle" min={0} max={29} value={day} onValueChange={setDay}
-  fillFrom={16} marks={marks} />
+```bash
+npm test
 ```
 
-`fillFrom` fills from that value to the thumb, either way. Themes' slider cannot place its
-range, so with `fillFrom` the atom is built on `@radix-ui/react-slider` and styled by
-`.ui-slider*` in `tokens.css` from Themes' public tokens — no `.rt-*` class is touched.
-Without it, nothing changed. Limits and details: [CHANGELOG.md](CHANGELOG.md); a full example
-is in `examples/BudgetCycleSlider.tsx`.
-
-⚠ `--ui-slider-thumb-size` mirrors Themes' size-2 thumb (`--space-2 + --space-1`). The fill
-and the marks are placed from it, so if Themes ever resizes its thumb, change it there.
-
-## Drawer — bottom sheet
-
-A sheet anchored to the bottom of the viewport: full width on phones, `max-w-lg` and centred
-above that (`maxWidthClassName` to change it), safe-area aware, themed from the house tokens.
-
-```tsx
-// Non-modal: a floating banner, the page stays usable, no focus trap.
-<Drawer mode="non-modal" title="Take deposits" peek={<p>Swipe up to see how.</p>}
-  footer={<Button>Get started</Button>}>
-  <ol>…steps…</ol>
-</Drawer>
-
-// Modal: scrim, focus trapped, page inert, Escape and the scrim close it.
-<Drawer open={open} onOpenChange={setOpen} defaultSnap="expanded" title="New client"
-  showCloseButton footer={<Button type="submit" form="f">Save</Button>}>
-  <form id="f">…</form>
-</Drawer>
-```
+runs lint (Biome), a typecheck and the Vitest suite (jsdom + Testing Library). `npm run build`
+compiles to `dist/`. Relative imports carry an explicit `.js` extension so the output works
+under Node's ESM resolution as well as bundlers.
 
-- **Snap points** `collapsed` (header + `peek`) and `expanded` (body, scrolls inside, up to
-  80vh). Controlled with `snap`/`onSnapChange`, or uncontrolled from `defaultSnap`; likewise
-  `open`/`onOpenChange`/`defaultOpen`.
-- **Drag** the header with touch or mouse: it follows the pointer, then settles past 60px or a
-  flick faster than 0.5px/ms. Down from collapsed closes when `dismissible` (the default).
-  A drag from inside the body counts only when the body is scrolled to the top and moving down.
-- **The handle is a real button** with `aria-expanded`/`aria-controls`, so keyboard and screen
-  reader users toggle it the same way.
-- **No words of its own.** The handle and close button names come from `expandLabel`,
-  `collapseLabel` and `closeLabel`, or the new `expand`, `collapse` and `close` keys of
-  `UiStringsProvider`.
-- Motion is a CSS transform, switched off under `prefers-reduced-motion`.
-
-It portals into the nearest `<Theme>` so it inherits the appearance and accent, falling back to
-`<body>`; `container` overrides that.
-
-Built by hand rather than on Radix Dialog because the non-modal half must not do what Dialog
-does to the rest of the page. Both examples are in `examples/Drawers.tsx`.
+Publishing happens from the GitHub workflow on a release; `prepublishOnly` rebuilds `dist`.
+Changes are listed in [CHANGELOG.md](CHANGELOG.md).

package/dist/atoms/ActionSheet/ActionSheet.d.ts

@@ -0,0 +1,30 @@
+import { type ReactNode } from 'react';
+export type ActionSheetTone = 'neutral' | 'brand' | 'danger';
+export interface ActionSheetAction {
+    label: string;
+    /** `danger` is red. Default `neutral`. */
+    tone?: ActionSheetTone;
+    icon?: ReactNode;
+    /** Runs, then the sheet closes. */
+    onSelect: () => void;
+}
+export interface ActionSheetProps {
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+    actions: ActionSheetAction[];
+    title?: ReactNode;
+    message?: ReactNode;
+    /** Overrides the Cancel button's label (otherwise the `cancel` UI string). */
+    cancelLabel?: string;
+    /** Where the portal mounts. Default: the nearest `<Theme>`, else rendered in place. */
+    container?: HTMLElement | null;
+}
+/**
+ * A short list of actions to choose between, on Radix `AlertDialog`: below `md` anchored to the
+ * bottom as a grouped list with a separated Cancel; at `md` and up a small centred dialog.
+ *
+ * AlertDialog rather than Dialog because the user is being asked to decide — it cannot be
+ * dismissed by clicking outside, and focus lands on Cancel, so Enter never fires a destructive
+ * action by accident. Escape and Cancel both close it without running anything.
+ */
+export declare function ActionSheet({ open, onOpenChange, actions, title, message, cancelLabel, container, }: ActionSheetProps): import("react").JSX.Element;