@vvedantb/ui 0.30.2 → 0.31.1

package/tokens/README.md

@@ -0,0 +1,120 @@
+# `@vvedantb/ui/tokens`
+
+Design tokens and shared Tailwind v4 CSS for the vvedantb web apps. The CSS and Tailwind preset are subpaths of `@vvedantb/ui`; the native JS tokens are named exports of the root (`tokens`, `Tokens`). Source-exported: no build step. Paths in the `File` column are relative to `packages/ui/tokens/`.
+
+## Exports
+
+| Export | File | What it is |
+| --- | --- | --- |
+| `@vvedantb/ui/tokens`, `@vvedantb/ui/tokens/tokens.css` | `src/tokens.css` | Colour, radius, shadow, ease and font tokens (`@theme`), light/dark variables, `dark` variant, the radius utilities `rounded-surface` (`clamp(0.75rem, var(--radius), 1rem)`), `rounded-menu-item` (`min(var(--radius), 0.5rem)`) and `rounded-control` (`min(var(--radius), 0.625rem)`) (0.7.1; `rounded-surface` was in `utilities.css` before), `*` border and `body` defaults. From 0.16.3 `--field-radius` (`rounded-field`) is `min(var(--radius), 0.625rem)`, the same cap as `rounded-control` (was `1.25rem`). 0.7.2 adds `--sidebar-accent` / `sidebar-accent` (sidebar nav row fill: light `var(--surface-tertiary)`, dark `oklch(22.64% 0 0)`). In 0.2.1 it also defines shadcn-style aliases (`primary`, `muted-foreground`, `secondary`, `destructive`, `card`, `popover`, `input`, `ring`) that point at the same tokens. From 0.15.0 it imports `clear-input.css`, `scrollbar-thin.css` and `motion.css`, sets the `--modal-*` and `--tabs-*` motion variables on `:root`, and defines `.glass-panel-strong` (`var(--overlay)`) and `.sidebar-section-label`. |
+| `tokens` and `Tokens` from `@vvedantb/ui` | `src/native.ts` | JS colours, radii and spacing for React Native. `@vvedantb/native-ui` keeps its own copy in `src/tokens.ts`; a test keeps the two equal. |
+| `@vvedantb/ui/tokens/css/base.css` | `src/css/base.css` | `html` touch/accent, `::selection`, control transitions, pointer cursor, range accent (`@layer base`). |
+| `@vvedantb/ui/tokens/css/dialog.css` | `src/css/dialog.css` | Unlayered `max-width: none` for `@vvedantb/ui` compact (bottom-sheet) dialogs. |
+| `@vvedantb/ui/tokens/css/modal.css` | `src/css/modal.css` | `.t-modal`, `.is-open`, `.is-closing` and `t-modal-presence-wait` (`@layer components`). |
+| `@vvedantb/ui/tokens/css/tabs.css` | `src/css/tabs.css` | `.t-tabs` container (0.15.0), `.t-tab` with its press scale, active colour, `.t-tabs-pill`, small-screen `.t-tabs` scrolling. |
+| `@vvedantb/ui/tokens/css/tabs-pills.css` | `src/css/tabs-pills.css` | `--tabs-*` colour variables, `.t-tabs--segmented`, `.t-tabs--pills` and pill hover / active fills. |
+| `@vvedantb/ui/tokens/css/utilities.css` | `src/css/utilities.css` | `@utility hit-target` and `@utility reveal-on-hover`. `rounded-surface` moved to `tokens.css` in 0.7.1. |
+| `@vvedantb/ui/tokens/css/scrollbar-thin.css` | `src/css/scrollbar-thin.css` | `.scrollbar-thin` (`@layer utilities`, always emitted). Imported by `tokens.css` from 0.15.0. |
+| `@vvedantb/ui/tokens/css/clear-input.css` | `src/css/clear-input.css` | `ClearInput` layers (`.t-clear*`) and the `--clear-*` / `--glow-*` timings. Imported by `tokens.css`. From 0.15.1 the layers clip in `.t-clear-clip`, so `.t-clear` keeps the focus ring, and the placeholder layer only shows during `.is-clearing`. |
+| `@vvedantb/ui/tokens/css/motion.css` | `src/css/motion.css` | `.ui-page-enter`, `.ui-enter`, `.ui-enter-up`, `.ui-stagger`, their keyframes and reduced-motion rules, and the `html[data-page-motion="off"]` overrides for `PageMotionProvider`. Imported by `tokens.css`. |
+| `@vvedantb/ui/tokens/css/animations.css` | `src/css/animations.css` | `animate-aurora`, `animate-fade-in-up`, `animate-indeterminate` as `@theme` (CSS-first apps). |
+| `@vvedantb/ui/tokens/css/compat-shadcn-rgb.css`, `@vvedantb/ui/tokens/compat/shadcn-rgb.css` | `src/css/compat-shadcn-rgb.css` | Replaces `tokens.css` for apps with shadcn-style `R G B` channel variables. Defines only the UI-only `--color-*` names as `rgb(var(--x) / alpha)` references, `--radius-field`, `--scrollbar`, `--field-radius` (both `min(var(--radius), 0.625rem)` from 0.16.3), the same three radius utilities as `tokens.css` and `.glass-panel-strong` (solid `--popover` from 0.15.0). Import it **or** `tokens.css`, never both. |
+| `@vvedantb/ui/tokens/css/index.css` | `src/css/index.css` | base + dialog + modal + tabs + tabs-pills + utilities + animations + nav-icons, for new CSS-first apps (`tokens.css` brings scrollbar-thin). |
+| `@vvedantb/ui/tokens/tailwind-preset` | `src/tailwind-preset.mjs` (+ `.d.mts`) | Tailwind preset for apps that load a JS config with `@config`. |
+
+Every file was extracted because the same rule (same at-rule context, selector and body) sits in 3 or more of the five apps. The measured duplication is in `verify/ANALYSIS.md`, and the proof that each app compiles to the same CSS after migrating is in `verify/RESULTS.md`. Blocks that only 2 apps share, or that drift in a way that would change an app's CSS, stay in the apps; `verify/ANALYSIS.md` lists them.
+
+## Use
+
+CSS-first app (no `tailwind.config`):
+
+```css
+@import "tailwindcss";
+@import "@vvedantb/ui/tokens";
+@import "@vvedantb/ui/tokens/css/animations.css";
+@import "@vvedantb/ui/tokens/css/base.css";
+/* ...app @layer base rules... */
+@import "@vvedantb/ui/tokens/css/modal.css";
+@import "@vvedantb/ui/tokens/css/tabs.css";
+/* ...app @layer components rules... */
+/* no --modal-* / --tabs-* needed: tokens.css sets them */
+```
+
+App with a JS config (`@config "../tailwind.config.ts"`):
+
+```ts
+import { tokensPreset } from "@vvedantb/ui/tokens/tailwind-preset";
+
+export default {
+  presets: [tokensPreset()],
+  // or tokensPreset({ color: (name) => `color-mix(in oklch, var(--${name}) calc(<alpha-value> * 100%), transparent)` })
+  content: ["./src/**/*.{ts,tsx}"],
+  theme: { extend: { /* app-only colours, fonts, animations */ } },
+  plugins: [tailwindcssAnimate],
+};
+```
+
+The preset holds `darkMode: "class"`, the shared colour map (`border`, `surface.*`, `danger.*`, `field.*`, shadcn aliases `primary`/`secondary`/`destructive`/`card`/`popover`/`input` ...), `borderRadius` lg/md/sm/field, `boxShadow` soft/panel/insetSoft, `ease-smooth`, `screens` xs to 2xl in px, and the aurora / fade-in-up / indeterminate / accordion keyframes. It does not hold plugins, `content`, fonts, `accent`/`muted`/`ring`/`sidebar` (they differ per app) or accordion timings.
+
+Do not import `css/animations.css` in an app that uses the preset: the preset already defines the same keyframes and animations.
+
+### Where to put the imports
+
+Tailwind inlines an `@import` where it sits, even in the middle of a file (it must be at top level, not inside an `@layer` block). Put each import where the app's own copy of the rules was. Within one layer, later rules win at equal specificity, so moving shared rules above or below app rules can flip the result for elements matched by both. `examples/migration.md` gives the exact position for each app, and `pnpm --filter @vvedantb/ui verify` checks it.
+
+### Variables each file needs
+
+| File | Needs | Provided by |
+| --- | --- | --- |
+| `base.css` | `--accent`, `--foreground` | tokens.css or the app theme |
+| `dialog.css` | none | |
+| `modal.css` | `--modal-open-dur`, `--modal-close-dur`, `--modal-scale`, `--modal-scale-close`, `--modal-ease` | tokens.css (0.15.0), or app `:root` with the compat file |
+| `tabs.css` | `--tabs-dur`, `--tabs-ease` (tokens.css, or app `:root` with the compat file); `--tabs-text-muted`, `--tabs-text-active`, `--tabs-pill-bg` | colours: tabs-pills.css or the app theme |
+| `tabs-pills.css` | `--muted`, `--segment`, `--segment-foreground`, `--default` | tokens.css or the app theme |
+| `utilities.css` | `--breakpoint-sm` (Tailwind default or app theme) | Tailwind |
+| `scrollbar-thin.css` | `--scrollbar` | tokens.css or the app theme |
+| `clear-input.css`, `motion.css` | none (own `:root` defaults) | |
+| `animations.css` | none | |
+| `tailwind-preset` | the CSS variables named in its colour map, `--radius`, `--field-radius` | tokens.css or the app theme |
+
+### Using an existing shadcn RGB theme
+
+See the package `README.md`. With the compat file, `base.css`, `scrollbar-thin.css`, `clear-input.css`, `motion.css`, `utilities.css`, `dialog.css`, `modal.css` and `tabs.css` need no `tokens.css` (`modal.css` and `tabs.css` then need the `--modal-*` / `--tabs-*` values on the app `:root`). `base.css` reads `--accent` and `--foreground` and `tabs-pills.css` reads `--muted`, `--segment` and `--default`. Those are not channel-compatible, so skip `tabs-pills.css` and `index.css` (which includes `base.css`) unless the app defines those variables as full colours.
+
+### Parameters
+
+Where apps share a rule but drifted in one value, the value is a custom property whose fallback is the most common value. Set it on `:root` to keep a different value.
+
+| File | Property | Default | Set by |
+| --- | --- | --- | --- |
+| `base.css` | `--tokens-control-transition-property` | `background-color, border-color, color, box-shadow, transform, opacity` | app-c: `background-color, color, transform, opacity` |
+| `base.css` | `--tokens-control-transition-duration` | `240ms` | app-c: `100ms` |
+
+From 0.15.0 the files that moved out of the apps take `:root` variables too. Every rule is in a Tailwind layer, so an app rule for the same selector (unlayered, or later in the same layer) also wins.
+
+| File | Property | Default |
+| --- | --- | --- |
+| `tokens.css` | `--modal-open-dur`, `--modal-close-dur` | `180ms`, `120ms` |
+| `tokens.css` | `--modal-scale`, `--modal-scale-close` | `0.96`, `0.96` |
+| `tokens.css` | `--modal-ease`, `--tabs-ease` | `cubic-bezier(0.22, 1, 0.36, 1)` |
+| `tokens.css` | `--tabs-dur` | `200ms` |
+| `tokens.css` | `--sidebar-section-label-mix`, `--sidebar-section-label-hover-mix` | `55%`, `80%` (share of `--muted`) |
+| `scrollbar-thin.css` | `--scrollbar-thin-rest`, `--scrollbar-thin-hover` | `40%`, `80%` (share of `--scrollbar`) |
+| `clear-input.css` | `--clear-dur`, `--clear-out-dur`, `--clear-in-dur` | `1000ms`, `400ms`, `400ms` |
+| `clear-input.css` | `--clear-out-fly`, `--clear-in-fly` | `12px`, `12px` |
+| `clear-input.css` | `--clear-out-ease`, `--clear-in-ease` | `cubic-bezier(0.22, 1, 0.36, 1)` |
+| `clear-input.css` | `--glow-delay`, `--glow-peak-at`, `--glow-opacity`, `--glow-spread` | `50ms`, `0.15`, `0.85`, `1.5` |
+| `motion.css` | `--ui-enter-ease` | `cubic-bezier(0.22, 1, 0.36, 1)` |
+| `motion.css` | `--ui-page-enter-dur`, `--ui-enter-dur`, `--ui-enter-up-dur` | `160ms`, `200ms`, `220ms` |
+| `motion.css` | `--ui-stagger-step` | `40ms` (children 1 to 8) |
+
+## Develop
+
+```sh
+pnpm --filter @vvedantb/ui build     # export targets exist + tsc (primitives, shell, app)
+pnpm --filter @vvedantb/ui test      # vitest (app helpers) + offline node --test: exports, CSS structure, Tailwind compile, preset
+pnpm --filter @vvedantb/ui analyze   # rule-level duplication across the app clones -> verify/ANALYSIS.tables.md
+pnpm --filter @vvedantb/ui verify    # before/after compile of every app -> verify/RESULTS.md, examples/migration.md
+```
+
+`analyze` and `verify` need the app clones (`APPS_DIR`, default `/workspace/cvx`; name or symlink the clones `app-a` to `app-e` inside it) and network access the first time: they install Tailwind 4.3.3, the plugins, postcss and jiti into a scratch directory (`VERIFY_DIR`, default `/workspace/pk-tokens-verify`, outside the repo). The migration for each app is data in `verify/migrations/<app>.json`. Each removed block must equal the shared file's block with the same context and selector, or the run fails.

package/tokens/examples/toaster/Fixture.tsx

@@ -44,6 +44,7 @@ export function Fixture() {
           <Button onClick={fire}>Show toast</Button>
         </div>
       </main>
+      {/* No `position`: the package default, top-right. */}
       <SonnerToaster
         theme={dark ? "dark" : "light"}
         toastRadius={compact ? "control" : "surface"}

package/tokens/examples/toaster/README.md

@@ -1,11 +1,12 @@
 # toaster fixture
 
-Renders `SonnerToaster` with every opt-in prop on (`toastRadius="surface"`, `toastIcons="filled24"`, `closeButtonStyle="hoverChip"`, `sonnerVars`, `descriptionMuted`). It fires one sample toast with a title and a description on load. The toast stays open. Use "Show toast" to fire another.
+Renders `SonnerToaster` with every opt-in prop on (`toastRadius="surface"`, `toastIcons="filled24"`, `closeButtonStyle="hoverChip"`, `sonnerVars`, `descriptionMuted`). It passes no `position`, so toasts show at the top right, the package default from 0.31.1. It fires one sample toast with a title and a description on load. The toast stays open. Use "Show toast" to fire another.
 
 | Page | Stylesheet |
 | --- | --- |
 | `/tokens.html` | `tokens.css` plus `utilities.css` (`styles-tokens.css`) |
 | `/compat.html` | `compat-shadcn-rgb.css` plus `utilities.css`, with sample `R G B` variables (`styles-compat.css`) |
+| `/update.html` | `tokens.css` plus `utilities.css` (`styles-tokens.css`). Fires the update toast from `showUpdateAvailableToast` on load, at the top right: title, description and a Refresh action that reloads the page. The Refresh button uses the package default (28px tall, `rounded-control`). "Show update toast" fires it again. |
 
 Each stylesheet declares `glass-panel-strong` (tokens page only) and `smooth-shadow-ring-md`. The app owns those toast classes. The compat page also defines `--success` and `--warning` and maps them to `--color-success` and `--color-warning`.
 
@@ -15,4 +16,4 @@ Run it from this folder (it is not a workspace member, and React resolves from t
 pnpm install --ignore-workspace && pnpm dev
 ```
 
-Open the printed URL plus `/tokens.html` or `/compat.html`. Add `?variant=compact` for the compact density with `toastRadius="control"`. Add `?theme=dark` for dark mode (combine with `&`), or use "Toggle theme". Hover the toast to see the close chip. `Fixture.tsx` is not part of the package typecheck.
+Open the printed URL plus `/tokens.html`, `/compat.html` or `/update.html`. Add `?variant=compact` for the compact density with `toastRadius="control"`. Add `?theme=dark` for dark mode (combine with `&`), or use "Toggle theme". `?variant=compact` applies to the first two pages only. Hover the toast to see the close chip. `Fixture.tsx` and `UpdateToastFixture.tsx` are not part of the package typecheck.

package/tokens/examples/toaster/UpdateToastFixture.tsx

@@ -0,0 +1,53 @@
+import { useEffect, useState } from "react";
+import { toast } from "sonner";
+import { showUpdateAvailableToast } from "../../../app/src/update/updateWatcher";
+import { Button } from "../../../src/ui/button";
+import { SonnerToaster } from "../../../src/ui/sonner";
+
+function initialDark(): boolean {
+  return new URLSearchParams(window.location.search).get("theme") === "dark";
+}
+
+// The toast `startUpdateAvailableWatcher` shows. Refresh reloads this page,
+// which fires the toast again.
+function fireUpdateToast() {
+  showUpdateAvailableToast({ toast });
+}
+
+/** The update toast with its Refresh action, for screenshots. */
+export function UpdateToastFixture() {
+  const [dark, setDark] = useState(initialDark);
+
+  // Sonner portals toasts onto `document.body`, so `.dark` must live on `<html>`.
+  useEffect(() => {
+    document.documentElement.classList.toggle("dark", dark);
+    return () => {
+      document.documentElement.classList.remove("dark");
+    };
+  }, [dark]);
+
+  useEffect(() => {
+    const id = window.setTimeout(fireUpdateToast, 150);
+    return () => window.clearTimeout(id);
+  }, []);
+
+  return (
+    <>
+      <main className="min-h-screen bg-background p-8 text-foreground">
+        <div className="flex gap-3">
+          <Button onClick={() => setDark((d) => !d)}>Toggle theme</Button>
+          <Button onClick={fireUpdateToast}>Show update toast</Button>
+        </div>
+      </main>
+      {/* No `position`: the package default, top-right, as Eva mounts it. */}
+      <SonnerToaster
+        theme={dark ? "dark" : "light"}
+        toastRadius="surface"
+        toastIcons="filled24"
+        closeButtonStyle="hoverChip"
+        sonnerVars
+        descriptionMuted
+      />
+    </>
+  );
+}

package/tokens/examples/toaster/main-update.tsx

@@ -0,0 +1,5 @@
+import { createRoot } from "react-dom/client";
+import { UpdateToastFixture } from "./UpdateToastFixture";
+import "./styles-tokens.css";
+
+createRoot(document.getElementById("root")!).render(<UpdateToastFixture />);

package/tokens/examples/toaster/update.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Update toast fixture</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="./main-update.tsx"></script>
+  </body>
+</html>

package/tokens/examples/toaster/vite.config.ts

@@ -7,6 +7,6 @@ export default defineConfig({
   plugins: [tailwindcss()],
   esbuild: { jsx: "automatic" },
   resolve: { dedupe: ["react", "react-dom"] },
-  build: { rollupOptions: { input: ["tokens.html", "compat.html"] } },
+  build: { rollupOptions: { input: ["tokens.html", "compat.html", "update.html"] } },
   server: { fs: { allow: ["../../.."] } },
 });