@vvedantb/ui 0.4.0-rc.0 → 0.4.0-rc.1

package/README.md

@@ -4,18 +4,15 @@ Shared React 19 web UI. Source-exported: no build step.
 
 | Import | What it is |
 | --- | --- |
-| `@vvedantb/ui` | Primitives (Radix-based), AI elements, `playChime` and `useReplyChime`. |
-| `@vvedantb/ui/sonner` | `SonnerToaster`, its helpers and `toast`. |
-| `@vvedantb/ui/composer` | `InputArea` (recommended) and its building blocks. Also the deprecated 0.3 `Composer`, `ComposerShell`, `ComposerGhostText`, `ComposerIconButton`, `useComposerPrediction` and the pure prediction helpers. |
-| `@vvedantb/ui/audio` | `playChime`, `useReplyChime`, `playTone` and the shared audio floor. |
-| `@vvedantb/ui/cn` | `cn` class helper (clsx + tailwind-merge). |
-| `@vvedantb/ui/shell` | Router-free `SidebarHeader`, `PillTabs` and `SessionsHoverCard`. |
-| `@vvedantb/ui/app` | Alt-click confirm skip, update watcher, settings chrome, `useStableAuth`. See `app/README.md` in the repository. |
-| `@vvedantb/ui/tokens` | `tokens.css`: colour, radius, shadow, ease and font tokens for Tailwind v4. |
-| `@vvedantb/ui/tokens/css/*.css` | `index`, `base`, `dialog`, `modal`, `tabs`, `tabs-pills`, `utilities`, `scrollbar-thin`, `animations`, `compat-shadcn-rgb`. |
-| `@vvedantb/ui/tokens/compat/shadcn-rgb.css` | Same file as `tokens/css/compat-shadcn-rgb.css`. |
-| `@vvedantb/ui/tokens/tailwind-preset` | Tailwind preset for apps that load a JS config with `@config`. |
-| `@vvedantb/ui/tokens/native` | JS colours, radii and spacing. No CSS, no React DOM. |
+| `@vvedantb/ui` | The only JavaScript entry. Primitives (Radix-based), AI elements, audio (`playChime`, `useReplyChime`, `playTone`), `toast` and `SonnerToaster`, the composer (`InputArea`, deprecated 0.3 `Composer`), shell (`SidebarHeader`, `PillTabs`, `SessionsHoverCard`), app helpers (confirm skip, update watcher, settings chrome, `useStableAuth`), `cn`, and the native tokens `tokens` and `Tokens`. See `app/README.md` in the repository for the app helpers. |
+| `@vvedantb/ui/tokens` | `tokens.css`: colour, radius, shadow, ease and font tokens for Tailwind v4. CSS. |
+| `@vvedantb/ui/tokens/tokens.css` | Same file as `@vvedantb/ui/tokens`. CSS. |
+| `@vvedantb/ui/tokens/css/*.css` | `index`, `base`, `dialog`, `modal`, `tabs`, `tabs-pills`, `utilities`, `scrollbar-thin`, `animations`, `compat-shadcn-rgb`. CSS. |
+| `@vvedantb/ui/tokens/compat/shadcn-rgb.css` | Same file as `tokens/css/compat-shadcn-rgb.css`. CSS. |
+| `@vvedantb/ui/tokens/tailwind-preset` | Tailwind preset (`.mjs`) for `@config "@vvedantb/ui/tokens/tailwind-preset"`. Kept as a build-tool entry: Tailwind needs a resolvable package path, and it is not a React API. |
+| `@vvedantb/ui/package.json` | Package metadata. |
+
+Removed in 0.4.0-rc.1: the `/cn`, `/sonner`, `/audio`, `/shell`, `/app`, `/composer` and `/tokens/native` subpaths. Import from `@vvedantb/ui`. See [`MIGRATION.md`](MIGRATION.md).
 
 ```css
 @import "tailwindcss";
@@ -34,7 +31,7 @@ useReplyChime({ enabled: soundOn, isStreaming, threadId });
 - `playChime()`: soft rising two-note chime (WebAudio). One shared `AudioContext`, created on first use. It is a no-op on the server and when autoplay blocks audio. Calls less than 1 second apart play once.
 - `playTone(tone | tones)`: plays `{ frequency, startOffsetS?, durationS?, peakGain?, type? }` through the same floor.
 - Audio floor: every package sound shares one 1 second minimum gap. Route your own sounds through it with `withAudioFloor(() => play())` or `if (tryAcquireAudioFloor()) play()`.
-- These are also available from `@vvedantb/ui/audio`, which does not load the rest of the root barrel.
+- The root barrel has no top-level side effects, so an app that imports only the audio symbols bundles only audio code.
 - `useReplyChime`: chimes once when `isStreaming` goes from `true` to `false` for the same `threadId`. It is silent on the first sight of a thread, when `threadId` changes, and when `threadId` is null or undefined. While `enabled` is `false` it still tracks the edge, so enabling mid-turn does not replay a finish.
 
 ## Composer
@@ -44,7 +41,7 @@ useReplyChime({ enabled: soundOn, isStreaming, threadId });
 `InputArea` is the chat composer extracted from an app: a pill that grows into a card, a plus menu, dictate, stop and send, ghost text, a `/` menu, and slots for banners, a queue, attachments and chips. It is presentational. It makes no requests and reads no router, billing or storage. The app passes data in and handles callbacks. It adds its own `TooltipProvider` and `LazyMotion`, so it needs no app provider.
 
 ```tsx
-import { InputArea, InputBanners, buildComposerSlashItems } from "@vvedantb/ui/composer";
+import { InputArea, InputBanners, buildComposerSlashItems } from "@vvedantb/ui";
 
 <InputArea
   value={draft}
@@ -84,16 +81,16 @@ import { InputArea, InputBanners, buildComposerSlashItems } from "@vvedantb/ui/c
 | `getPrediction`, `predictionEnabled` | off, `true` | Ghost text. Tab accepts, Esc dismisses. Paused while the `/` menu is open. |
 | `className`, `containerClassName`, `borderClassName`, `submitButtonClassName`, `submitIconClassName`, `placeholder` | none | The app passes its own class strings for an exact match. |
 
-Building blocks: `InputActions`, `ConnectionStatusMenuItem` (icon, label, description, `connected`, `onClick`, `title`), `InputBanners`, `PromoBanner` (`show`, `onUpgrade`, `onDismiss`, text as children), `FadePresence`, `ComposerSlashMenu`, `ComposerSlashRow`, and the hooks and helpers listed in the changelog. Parity against the original: `composer/examples/parity/PARITY.md`. App migration: `composer/MIGRATION.md`.
+Building blocks: `InputActions`, `ConnectionStatusMenuItem` (icon, label, description, `connected`, `onClick`, `title`), `InputBanners`, `PromoBanner` (`show`, `onUpgrade`, `onDismiss`, text as children), `FadePresence`, `ComposerSlashMenu`, `ComposerSlashRow`, and the hooks and helpers listed in the changelog. Parity against the original: `composer/examples/parity/PARITY.md`. App migration: `composer/MIGRATION-INPUTAREA.md`.
 
 ### Composer (deprecated)
 
-> **Deprecated in 0.4.0.** Use `InputArea`. The 0.3 `Composer` was written from scratch and does not match the app composer. It stays exported and unchanged for existing consumers, and is not removed in 0.4.0.
+> **Deprecated in 0.4.0-rc.1.** Use `InputArea`. The 0.3 `Composer` was written from scratch and does not match the app composer. It stays exported and unchanged for existing consumers, and is not removed in 0.4.0-rc.1.
 
 Chat composer with an autosizing textarea, a footer with a plus-menu slot, action slots and a send or stop button. It also shows optional ghost-text predictions. It makes no network calls: the app supplies `getPrediction`.
 
 ```tsx
-import { Composer, ComposerIconButton } from "@vvedantb/ui"; // or "@vvedantb/ui/composer"
+import { Composer, ComposerIconButton } from "@vvedantb/ui";
 
 <Composer
   value={draft}
@@ -164,7 +161,7 @@ Rules for a custom input:
 To build without `Composer`, assemble the parts yourself. `useComposerPrediction` takes the draft string and reads no element. `ComposerGhostText` draws the draft invisibly, then the ghost text, so give it the same padding and font classes as your editor and place it under the editor.
 
 ```tsx
-import { ComposerGhostText, ComposerShell, useComposerPrediction } from "@vvedantb/ui/composer";
+import { ComposerGhostText, ComposerShell, useComposerPrediction } from "@vvedantb/ui";
 
 function MentionComposer({ draft, setDraft, send }: Props) {
   const prediction = useComposerPrediction({ value: draft, enabled: true, getPrediction });
@@ -184,7 +181,7 @@ Fixture: `composer/examples/` (see its README). It has a `tokens.css` page and a
 ## Sessions hover card
 
 ```tsx
-import { SessionsHoverCard } from "@vvedantb/ui/shell";
+import { SessionsHoverCard } from "@vvedantb/ui";
 
 <SessionsHoverCard
   header="Session title"
@@ -200,8 +197,7 @@ import { SessionsHoverCard } from "@vvedantb/ui/shell";
 ## Toaster
 
 ```tsx
-import { toast } from "sonner";
-import { SonnerToaster } from "@vvedantb/ui"; // or "@vvedantb/ui/sonner"
+import { SonnerToaster, toast } from "@vvedantb/ui";
 
 <SonnerToaster
   theme={theme}
@@ -261,6 +257,6 @@ The compat file includes a fallback `glass-panel-strong` (`rgb(var(--card) / 0.9
 
 A fixture that renders the main components against sample light and dark RGB variables is in `tokens/examples/compat-shadcn-rgb/`.
 
-`@clerk/clerk-react`, `@tanstack/react-hotkeys` and `zod` are optional peers. Install them only if you import `@vvedantb/ui/app`.
+`@clerk/clerk-react`, `@tanstack/react-hotkeys`, `motion` and `zod` are optional peers (`peerDependenciesMeta`). Install `@clerk/clerk-react` only to use `useStableAuth`, `@tanstack/react-hotkeys` and `zod` only for the features that use them, and `motion` only to use the motion presets, `InputArea`, the 0.3 `Composer` or the AI elements and primitives that animate.
 
 Full documentation: the repository `README.md`. Upgrading from `@vvedantb/tokens`, `@vvedantb/shell` or `@vvedantb/app-kit`: `MIGRATION.md`.

package/app/README.md

@@ -1,4 +1,4 @@
-# `@vvedantb/ui/app`
+# App helpers (`@vvedantb/ui`)
 
 Shared web React helpers that were duplicated across apps. Source-exported as the `./app` subpath of `@vvedantb/ui`.
 
@@ -10,9 +10,9 @@ npm install @vvedantb/ui
 
 ## Peers
 
-Required: `react` and `react-dom` (>=19). Optional peers of `@vvedantb/ui`, needed only for this subpath: `@clerk/clerk-react` (`useStableAuth`), `@tanstack/react-hotkeys` and `zod`.
+Required: `react` and `react-dom` (>=19). Optional peers of `@vvedantb/ui`, needed only for the app helpers: `@clerk/clerk-react` (`useStableAuth`), `@tanstack/react-hotkeys` and `zod`.
 
-`sonner` is not a dependency. The update watcher takes the toast API as an option. This subpath uses a local class join (`cn`), not the `cn` from `@vvedantb/ui`. Tailwind must scan `node_modules/@vvedantb/ui/app/src/**/*.{ts,tsx}` so the class names are generated, and the app needs the `@vvedantb/ui/tokens` names (`bg-surface-card`, `divide-separator`, `text-muted-foreground` and so on).
+`sonner` is not a dependency. The update watcher takes the toast API as an option. The app source uses a local class join, which the root does not export (the root `cn` is the clsx and tailwind-merge one). Tailwind must scan `node_modules/@vvedantb/ui/app/src/**/*.{ts,tsx}` so the class names are generated, and the app needs the `@vvedantb/ui/tokens` names (`bg-surface-card`, `divide-separator`, `text-muted-foreground` and so on).
 
 ```css
 @source "../node_modules/@vvedantb/ui/app/src/**/*.{ts,tsx}";
@@ -21,7 +21,7 @@ Required: `react` and `react-dom` (>=19). Optional peers of `@vvedantb/ui`, need
 ## Confirm skip (Alt-click)
 
 ```tsx
-import { ConfirmSkipHint, skipConfirmTitle, useRequestConfirm } from "@vvedantb/ui/app";
+import { ConfirmSkipHint, skipConfirmTitle, useRequestConfirm } from "@vvedantb/ui";
 
 const { request } = useRequestConfirm();
 
@@ -42,7 +42,7 @@ const { request } = useRequestConfirm();
 
 ```ts
 import { toast } from "sonner";
-import { startUpdateAvailableWatcher } from "@vvedantb/ui/app";
+import { startUpdateAvailableWatcher } from "@vvedantb/ui";
 
 useEffect(
   () =>
@@ -61,7 +61,7 @@ Options: `origin`, `toast`, `closeConvex?`, `pollMs?` (default 60000), `toastId?
 ## Settings chrome
 
 ```tsx
-import { SettingsPage, SettingsSection, SettingsToggleRow } from "@vvedantb/ui/app";
+import { SettingsPage, SettingsSection, SettingsToggleRow } from "@vvedantb/ui";
 
 <SettingsPage
   title="Notifications"
@@ -82,8 +82,8 @@ Exports: `SettingsSection`, `SettingsField`, `SettingsStack`, `SettingsToggleRow
 ## useStableAuth
 
 ```ts
-import { useStableAuth } from "@vvedantb/ui/app"; // 2000 ms debounce, wraps Clerk useAuth
-import { createUseStableAuth } from "@vvedantb/ui/app";
+import { useStableAuth } from "@vvedantb/ui"; // 2000 ms debounce, wraps Clerk useAuth
+import { createUseStableAuth } from "@vvedantb/ui";
 
 const useAuth = createUseStableAuth(useClerkAuth, { debounceMs: 3000 });
 ```

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@vvedantb/ui",
-  "version": "0.4.0-rc.0",
+  "version": "0.4.0-rc.1",
   "license": "MIT",
-  "description": "Shared React 19 UI for web apps: primitives, shell pieces, app helpers, design tokens, shared Tailwind v4 CSS and a Tailwind preset.",
+  "description": "Shared React 19 UI for web apps: one JavaScript entry (primitives, shell pieces, app helpers, native tokens), design-token CSS, shared Tailwind v4 CSS and a Tailwind preset.",
   "type": "module",
   "publishConfig": {
     "access": "public"
@@ -17,36 +17,8 @@
       "types": "./src/index.ts",
       "default": "./src/index.ts"
     },
-    "./cn": {
-      "types": "./src/utils/cn.ts",
-      "default": "./src/utils/cn.ts"
-    },
-    "./sonner": {
-      "types": "./src/sonner.ts",
-      "default": "./src/sonner.ts"
-    },
-    "./audio": {
-      "types": "./src/audio/index.ts",
-      "default": "./src/audio/index.ts"
-    },
-    "./composer": {
-      "types": "./src/composer/index.ts",
-      "default": "./src/composer/index.ts"
-    },
-    "./shell": {
-      "types": "./shell/src/index.ts",
-      "default": "./shell/src/index.ts"
-    },
-    "./app": {
-      "types": "./app/src/index.ts",
-      "default": "./app/src/index.ts"
-    },
     "./tokens": "./tokens/src/tokens.css",
     "./tokens/tokens.css": "./tokens/src/tokens.css",
-    "./tokens/native": {
-      "types": "./tokens/src/native.ts",
-      "default": "./tokens/src/native.ts"
-    },
     "./tokens/css/index.css": "./tokens/src/css/index.css",
     "./tokens/css/base.css": "./tokens/src/css/base.css",
     "./tokens/css/dialog.css": "./tokens/src/css/dialog.css",
@@ -193,6 +165,9 @@
     "@tanstack/react-hotkeys": {
       "optional": true
     },
+    "motion": {
+      "optional": true
+    },
     "zod": {
       "optional": true
     }

package/src/composer/Composer.tsx

@@ -303,7 +303,7 @@ const ComposerGhostText = React.forwardRef<HTMLDivElement, ComposerGhostTextProp
  * Chat composer: autosizing textarea, plus-menu and action slots, send/stop
  * button and optional ghost-text predictions. The ref points at the textarea.
  */
-/** @deprecated Use `InputArea` from `@vvedantb/ui/composer`. Kept unchanged for existing consumers. */
+/** @deprecated Use `InputArea` from `@vvedantb/ui`. Kept unchanged for existing consumers. */
 const Composer = React.forwardRef<HTMLTextAreaElement, ComposerProps>(function Composer(
   {
     value: valueProp,

package/src/composer/input-area/InputArea.tsx

@@ -37,6 +37,12 @@ const COMPACT_START_ADDON =
 const COMPACT_END_ADDON =
   "order-last shrink-0 justify-end gap-1 py-0 pr-1.5 pl-1 has-[>button]:mr-0";
 
+/**
+ * Default ghost text class. It matches the original app composer, whose theme
+ * defines the bare muted utility. Pass `predictionTextClassName` to use another class.
+ */
+export const DEFAULT_PREDICTION_TEXT_CLASS = "text-muted"; // check-tokens-allow: text-muted
+
 export const DEFAULT_ATTACH_ACCEPT =
   "image/png,image/jpeg,image/jpg,image/webp,application/pdf";
 
@@ -94,6 +100,8 @@ export type InputAreaProps = {
   /** Returns a continuation for the draft. Omit to turn ghost text off. */
   getPrediction?: (text: string) => Promise<string>;
   predictionEnabled?: boolean;
+  /** Classes on the ghost suggestion span. Default matches the original app composer. */
+  predictionTextClassName?: string;
 
   /** Wrapper around banners, queue and the input. */
   className?: string;
@@ -138,6 +146,7 @@ export function InputArea({
   renderSlashItem,
   getPrediction,
   predictionEnabled = true,
+  predictionTextClassName = DEFAULT_PREDICTION_TEXT_CLASS,
   className,
   containerClassName,
   borderClassName,
@@ -402,7 +411,7 @@ export function InputArea({
                         )}
                       >
                         {input}
-                        <span className="text-muted-foreground">
+                        <span className={predictionTextClassName}>
                           {prediction.suggestion}
                         </span>
                       </div>

package/src/index.ts

@@ -100,3 +100,24 @@ export * from "./ai-elements/suggestion";
 export * from "./audio";
 
 export * from "./composer";
+export { toast } from "sonner";
+
+// Shell: router-free pieces. Shell's own `cn` and `ClassValue` are not re-exported;
+// use the root `cn` (clsx + tailwind-merge).
+export { SidebarHeader } from "../shell/src/SidebarHeader";
+export type { SidebarHeaderProps } from "../shell/src/SidebarHeader";
+export { PillTabs } from "../shell/src/PillTabs";
+export type { PillTabItem, PillTabsProps } from "../shell/src/PillTabs";
+export { SessionsHoverCard } from "../shell/src/SessionsHoverCard";
+export type {
+  SessionsHoverCardContext,
+  SessionsHoverCardProps,
+  SessionsHoverCardSurface,
+} from "../shell/src/SessionsHoverCard";
+
+// App helpers: confirm skip, update watcher, settings chrome, stable auth.
+export * from "../app/src/index";
+
+// Native tokens (JS values that match tokens.css).
+export { tokens } from "../tokens/src/native";
+export type { Tokens } from "../tokens/src/native";

package/tokens/README.md

@@ -1,13 +1,13 @@
 # `@vvedantb/ui/tokens`
 
-Design tokens and shared Tailwind v4 CSS for the vvedantb web apps, plus JS tokens for React Native. These are subpaths of `@vvedantb/ui`, source-exported: no build step. Paths in the `File` column are relative to `packages/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, `*` border and `body` defaults. 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. |
-| `@vvedantb/ui/tokens/native` | `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. |
+| `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`). |

package/src/sonner.ts

@@ -1,2 +0,0 @@
-export * from "./ui/sonner";
-export { toast } from "sonner";