@vvedantb/ui 0.7.1 → 0.8.0

package/README.md

@@ -4,7 +4,7 @@ Shared React 19 web UI. Source-exported: no build step.
 
 | Import | What it is |
 | --- | --- |
-| `@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`, and the app shell: `AppShell`, `AppSidebar`, `SidebarRail`, `RailTile`, `SidebarPanel`, `SidebarAccountMenu`, `SignOutDialog` and related helpers), 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` | 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`, and the app shell: `AppShell`, `AppSidebar`, `SidebarRail`, `RailTile`, `SidebarPanel`, `SidebarAccountMenu`, `SignOutDialog` and related helpers), app helpers (confirm skip, update watcher, settings chrome, `useStableAuth`, and from 0.8.0 `createThemeProvider`, `createPageTitleContext`, `PageMotionProvider` and `formatCompactRelativeTime`), `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. |
@@ -299,7 +299,7 @@ import {
 - `SidebarPanel`: legacy (still supported) `headerTrailing`, `onClose`, `closeLabel` and `closeButtonClassName`; compose `Sidebar.Panel` parts instead. `title`, `headerTrailing`, `onClose` (adds the close button; pass it on the mobile drawer only), `closeLabel`, `closeButtonClassName`, `collapsed` (`md:hidden`), `className`, `children`.
 - `SidebarAccountMenu`: legacy (still supported) `badge`, `triggerProps`, `contentProps` and `stackedLabel`; compose `Sidebar.Account*` parts instead. `name`, `email` (two-line label when set), `stackedLabel` (two-line layout even without `email`, default `false`), `imageUrl` (initials without it), `align` (`"center"`), `side` (`"right"`), `sideOffset` (8), `collisionPadding`, `contentClassName`, `children` (menu items). 0.5.2 adds `badge` (unread dot beside the trigger, in a `relative` wrapper around the menu, so the trigger's dimming and press scale skip it: `true` shows it, `false` fades it out, omitted renders no wrapper and no dot), `triggerProps` (spread onto the trigger `Button` after the defaults; `className` merges last) and `contentProps` (spread onto `DropdownMenuContent`, for example `fitViewport` or `aria-label`; no `className`, use `contentClassName`). `SidebarAccountMenuPlaceholder` is the tile-sized loading box.
 - `SignOutDialog`: legacy (still supported) `question` and `title`; compose `ConfirmDialog` parts with `alert={false}` for other copy. `open`, `onOpenChange` (not called with `false` while `pending`), `pending`, `onConfirm`, `description`, `contentClassName`, `title` (`"Sign out"`), `question` (`"Sign out of your account?"`).
-- Class helpers: `railTileClass`, `railTileStateClass(active)`, `railBadgeClass`, `sidebarNavRowClass(isIconOnly)`, `sidebarNavLinkTextClass(isActive)`, `sidebarNavItemClass({ active, iconOnly })`, `sidebarNavIconClass(active)`, `sidebarSectionLabelClass`. See [Menu item corners and sidebar nav rows (0.7.1)](#menu-item-corners-and-sidebar-nav-rows-071).
+- Class helpers: `railTileClass`, `railTileStateClass(active)`, `railBadgeClass`, `sidebarNavRowClass(isIconOnly)`, `sidebarNavLinkTextClass(isActive)`, `sidebarNavItemClass({ active, iconOnly, selected, dragging, dropTarget })`, `sidebarNavIconClass(active)`, `sidebarSectionLabelClass`, and the row parts `sidebarNavItemLeadingClass`, `sidebarNavItemLabelClass`, `sidebarNavItemSubtitleClass`, `sidebarNavItemTrailingClass`, `sidebarNavItemActionsClass` and `sidebarNavItemIndentStyle(indent)`. See [Menu item corners and sidebar nav rows (0.7.1)](#menu-item-corners-and-sidebar-nav-rows-071) and [Sidebar nav row parts (0.7.2)](#sidebar-nav-row-parts-072).
 
 ### Header actions and account badge (0.5.2)
 
@@ -434,7 +434,8 @@ Convention: compound parts are static members of a namespace object, `<Namespace
 | `PanelHeader` | Padded header row for `PanelTitle` and `PanelActions`. |
 | `PanelTitle` / `PanelActions` | The `<h2>` and the trailing actions. |
 | `PanelClose` | Ghost close button. `label` (`"Close navigation"`). Without `onClick` it closes the drawer. |
-| `NavItem` | Panel nav row (`sidebarNavItemClass`). `active` (fill, `font-medium`, `aria-current="page"`), `iconOnly`, `icon` (element; gets `sidebarNavIconClass`), `asChild` for a router link. A `<button type="button">` without `asChild`. |
+| `NavItem` | Panel nav row (`sidebarNavItemClass`). `active` (fill, `font-medium`, `aria-current="page"`), `iconOnly`, `icon` (element; gets `sidebarNavIconClass`), `asChild` for a router link. A `<button type="button">` without `asChild`. 0.7.2: `selected`, `indent`, `dragging`, `dropTarget`; see [Sidebar nav row parts (0.7.2)](#sidebar-nav-row-parts-072). |
+| `NavItemLeading` / `NavItemLabel` / `NavItemTrailing` / `NavItemActions` | Row parts (0.7.2): leading slot, truncated label, always-visible trailing content and hover-revealed actions. `<span>`, or the child with `asChild`. |
 | `AccountMenu` | Dropdown root. `badge` adds the unread dot (`AccountBadge`) in a `relative` wrapper. |
 | `AccountTrigger` | Rail-tile-sized avatar button. `userName` (default `title` and `aria-label`, and the initials), `imageUrl`, plus `Button` props; native `name` goes to the button. |
 | `AccountAvatar` | Avatar image or initials. `userName`, `imageUrl`. |
@@ -693,12 +694,104 @@ Colour mapping. The package has no sidebar colour tokens, so the rows use the ne
 
 | Role | Reference look (light / dark, sRGB) | Package token (light / dark, sRGB) |
 | --- | --- | --- |
-| Hover and active fill | 233 234 236 / 28 28 28 | `surface-tertiary`: 234 234 234 / about 39 39 39. Light matches; dark is a step lighter. It is the rail tile's active fill too, so a rail tile and a nav row stay the same. |
+| Hover and active fill | 233 234 236 / 28 28 28 | `surface-tertiary`: 234 234 234 / about 39 39 39. Light matches; dark is a step lighter. It is the rail tile's active fill too, so a rail tile and a nav row stay the same. From 0.7.2 the rows use `sidebar-accent` (234 234 234 / 28 28 28); see below. |
 | Active text and icon | 9 9 11 / 250 250 250 | `foreground`: 24 24 24 / 252 252 252 |
 | Idle text (80%) | 24 24 25 / 251 252 253 | `foreground` at 80% |
 | Idle icon | 100 101 103 / 159 160 162 | `muted-foreground` (`--muted`): 114 114 114 / 160 160 160 |
 | Focus ring (35%) | 9 9 11 / 250 250 250 | `foreground` at 35% |
 
+## Sidebar nav row parts (0.7.2)
+
+One row style for every sidebar list: plain nav links and rich rows (checkbox, avatar, two-line label, nested folders, `...` menus, drag and drop, rename inputs). `Sidebar.NavItem` is the row; the parts go inside it.
+
+Rich row (the link is the row; the parts are its children):
+
+```tsx
+<Sidebar.NavItem asChild active={isActive} selected={selected} indent={1} dragging={isDragged} dropTarget={isOver}>
+  <Link to="/chat/$id" params={{ id }} draggable onDragStart={onDragStart}>
+    <Sidebar.NavItemLeading>
+      <Checkbox checked={selected} onClick={(event) => event.stopPropagation()} aria-label={`Select ${title}`} />
+    </Sidebar.NavItemLeading>
+    <Sidebar.NavItemLabel>{title}</Sidebar.NavItemLabel>
+    <Sidebar.NavItemTrailing>{generating ? <Spinner size={14} decorative /> : count}</Sidebar.NavItemTrailing>
+    <Sidebar.NavItemActions>
+      <DropdownMenu>
+        <DropdownMenuTrigger asChild>
+          <Button
+            variant="ghost"
+            size="icon-xs"
+            aria-label="Row actions"
+            onClick={(event) => {
+              event.stopPropagation();
+              event.preventDefault();
+            }}
+          >
+            <IconDots size={16} />
+          </Button>
+        </DropdownMenuTrigger>
+        <DropdownMenuContent>...</DropdownMenuContent>
+      </DropdownMenu>
+    </Sidebar.NavItemActions>
+  </Link>
+</Sidebar.NavItem>
+```
+
+Simple row (unchanged from 0.7.1):
+
+```tsx
+<Sidebar.NavItem asChild active={active} icon={<IconHome />}>
+  <Link to="/home"><span className="truncate">Home</span></Link>
+</Sidebar.NavItem>
+```
+
+`Sidebar.NavItem` props added in 0.7.2:
+
+| Prop | Effect |
+| --- | --- |
+| `selected` | The active fill (`bg-sidebar-accent text-foreground`) without `font-medium` or `aria-current`. `data-selected="true"`. |
+| `indent` | Nesting level from 0. Left padding is `calc(1rem + indent * 12px)`: 16px, 28px, 40px, ... Set as inline `paddingLeft`, so any depth works and a `style.paddingLeft` you pass wins. Ignored with `iconOnly`. |
+| `dragging` | `opacity-40 cursor-grabbing`. `data-dragging="true"`. |
+| `dropTarget` | Fill plus `ring-2 ring-inset ring-focus`. `data-drop-target="true"`. |
+
+`active` also sets `data-active="true"`. Each attribute is left off when its prop is false. The styles key off the attributes (`data-[selected=true]:`, `data-[dragging=true]:`, `data-[drop-target=true]:`), so a row that sets them itself (for example from a tree library's drag state) gets the same look. `sidebarNavItemClass` takes the same `selected`, `dragging` and `dropTarget` options for rows that use the class only.
+
+Parts. Each renders a `<span>` with its class (`className` merges last), or merges onto its single child with `asChild`:
+
+| Part | Class | Use |
+| --- | --- | --- |
+| `NavItemLeading` | `sidebarNavItemLeadingClass`: `flex shrink-0 items-center` | Checkbox, icon, avatar, status dot, folder chevron. Put `sidebarNavIconClass(active)` on an icon. A 40px avatar makes the row taller; add `py-2` to the row if you want more room. |
+| `NavItemLabel` | `sidebarNavItemLabelClass`: `min-w-0 flex-1 truncate` | The title. For two lines, put `<span className="block truncate">` and `<span className={sidebarNavItemSubtitleClass}>` (`block truncate text-xs text-muted-foreground`) inside. For rename, `asChild` on the input. |
+| `NavItemTrailing` | `sidebarNavItemTrailingClass`: `ml-auto flex shrink-0 items-center gap-1.5 text-xs text-muted-foreground` | Always visible: counts, unread dots, spinners, badges. |
+| `NavItemActions` | `sidebarNavItemActionsClass` (below) | Hover-revealed `...` button. |
+
+Actions sit in the row flow at the end (`ml-auto`), so an `asChild` link row needs no `relative`. The part is `h-6` with `-my-1`, so a 24px or 28px icon button does not change the 30px row height. It reserves its width while hidden, so the label truncates a little earlier. For the older overlay look, pass `className="absolute right-3"` to the part and `relative` to the row. Visibility:
+
+- `opacity-0` by default, `transition-opacity duration-75`.
+- `group-hover:opacity-100` and `group-focus-within:opacity-100`: the row is a `group`.
+- `has-[[data-state=open]]:opacity-100`: a Radix menu trigger inside it is open.
+- `data-[state=open]:opacity-100`: the part itself is the trigger (`asChild`).
+
+The part adds no handlers. Call `stopPropagation()` (and `preventDefault()` inside a link) on the button so it does not run the row click.
+
+Other rich-row needs:
+
+- Folder rows and drop zones: render the row as a `<div>` or `<button>` (`asChild` on a `<div>` when the row holds its own buttons) and wrap it in your drop zone. Set `dropTarget` while a drag is over it.
+- Indent guide lines: absolutely positioned spans in the row; add `relative` to the row.
+- Context menus and hover cards: wrap `Sidebar.NavItem` as before; `ContextMenuTrigger asChild` can wrap it directly.
+
+Classes a rich row no longer needs beside the parts: `rounded-lg`, `rounded-md`, `text-sm` (and `text-sm` on the title span), `px-3 py-1.5`, `gap-3`, `py-2`/`gap-3` for padding alone, `pl-7`/`pl-8` (use `indent`), `bg-surface-tertiary` for active, hover or selected, `ring-2 ring-inset ring-focus` and `opacity-40 cursor-grabbing` for drag states, `opacity-0 group-hover:opacity-100 group-focus-within:opacity-100 transition-opacity` on the menu button, `mr-2` on a checkbox (the row `gap-2` spaces it), `truncate flex-1 min-w-0` on the title, `text-xs text-muted` on counts, and app row helpers that set any of these (a local list-item class, an outer `group py-px` wrapper, a `ui-sidebar-row` class).
+
+### Fill colour: `sidebar-accent`
+
+Rows (hover, active, selected, drop target) use `bg-sidebar-accent` instead of `bg-surface-tertiary`.
+
+| | Light | Dark |
+| --- | --- | --- |
+| `tokens.css` `--sidebar-accent` | `var(--surface-tertiary)` (about 234 234 234; unchanged) | `oklch(22.64% 0 0)` (28 28 28; was about 39 39 39) |
+| `compat-shadcn-rgb.css` `--color-sidebar-accent` | `rgb(var(--sidebar-accent, var(--secondary)))`: the app's `--sidebar-accent` channels if defined, else `--secondary` as before | same |
+
+Rail tiles keep `surface-tertiary`, so in dark mode the active rail tile is a step lighter than the active row. An app that imports `tokens.css` and defines its own `--sidebar-accent` overrides the fill; it must be a full colour value there (use `compat-shadcn-rgb.css` for `R G B` channels).
+
 ## Toaster
 
 ```tsx
@@ -747,7 +840,7 @@ Components use `text-muted-foreground`, `primary` and `--color-*` theme variable
 Use this when the app defines shadcn-style variables as space-separated channels (`--background: 244 245 246`) and reads them as `rgb(var(--background) / 0.5)`.
 
 1. Import `compat-shadcn-rgb.css` **instead of** `tokens.css`. Never import both.
-2. The app keeps `--background`, `--foreground`, `--card`, `--popover`, `--primary`, `--secondary`, `--muted`, `--accent`, `--destructive`, `--border`, `--input`, `--ring` (each with its `-foreground` where shadcn has one) and `--radius`. The compat file does not define them. It only references them, so the app can change `--primary`, `--ring`, `--radius` or `--font-sans` at runtime.
+2. The app keeps `--background`, `--foreground`, `--card`, `--popover`, `--primary`, `--secondary`, `--muted`, `--accent`, `--destructive`, `--border`, `--input`, `--ring` (each with its `-foreground` where shadcn has one) and `--radius`. The compat file does not define them. It only references them, so the app can change `--primary`, `--ring`, `--radius` or `--font-sans` at runtime. `--sidebar-accent` is optional: sidebar nav rows use it when set, else `--secondary` (0.7.2).
 3. Add the `@source` line for the package sources.
 
 ```css

package/app/src/index.ts

@@ -41,3 +41,34 @@ export {
   type ClerkAuthSlice,
   type StableAuthOptions,
 } from "./auth/useStableAuth.js";
+
+export {
+  applyThemeClass,
+  createThemeProvider,
+  getSystemTheme,
+  type ThemeAttribute,
+  type ThemeProviderKit,
+  type ThemeProviderOptions,
+  type ThemeProviderProps,
+  type ThemeState,
+} from "./theme/createThemeProvider.js";
+
+export {
+  createPageTitleContext,
+  type DocumentTitleOptions,
+  type PageTitleContextKit,
+  type PageTitleContextOptions,
+  type PageTitleValue,
+} from "./page-title/createPageTitleContext.js";
+
+export {
+  PageMotionProvider,
+  useDisablePageMotion,
+  type PageMotionConfigProps,
+  type PageMotionProviderProps,
+} from "./page-motion/PageMotionProvider.js";
+
+export {
+  formatCompactRelativeTime,
+  type CompactRelativeTimeOptions,
+} from "./time/compactRelativeTime.js";

package/app/src/page-motion/PageMotionProvider.tsx

@@ -0,0 +1,44 @@
+import { createContext, use, useLayoutEffect, type ComponentType, type ReactNode } from "react";
+
+/** The props `MotionConfig` from `motion/react` takes here. */
+export type PageMotionConfigProps = {
+  reducedMotion: "always" | "never";
+  children: ReactNode;
+};
+
+export type PageMotionProviderProps = {
+  /** Page motion is off, for example from a user setting. */
+  disabled: boolean;
+  /**
+   * Pass `MotionConfig` from `motion/react`, or a component of the app that
+   * wraps it (for example in `LazyMotion`). Injected so this package does not
+   * import `motion`. Define it at module level, not inline.
+   */
+  motionConfig: ComponentType<PageMotionConfigProps>;
+  children: ReactNode;
+};
+
+const PageMotionContext = createContext(false);
+
+/** Whether page motion is off (`false` outside `PageMotionProvider`). */
+export function useDisablePageMotion(): boolean {
+  return use(PageMotionContext);
+}
+
+/**
+ * Stamps `html[data-page-motion]` (`"off"` or `"on"`) in a layout effect so CSS
+ * page and route transitions can skip, and sets Motion's `reducedMotion` to
+ * `"always"` when disabled and `"never"` otherwise. The attribute stays after
+ * unmount.
+ */
+export function PageMotionProvider({ disabled, motionConfig: MotionConfig, children }: PageMotionProviderProps) {
+  useLayoutEffect(() => {
+    document.documentElement.dataset.pageMotion = disabled ? "off" : "on";
+  }, [disabled]);
+
+  return (
+    <PageMotionContext value={disabled}>
+      <MotionConfig reducedMotion={disabled ? "always" : "never"}>{children}</MotionConfig>
+    </PageMotionContext>
+  );
+}

package/app/src/page-title/createPageTitleContext.tsx

@@ -0,0 +1,99 @@
+import { createContext, use, useEffect, useState, type ReactNode } from "react";
+
+export type PageTitleValue = {
+  pageTitle: string;
+  setPageTitle: (title: string) => void;
+  /** Element a mobile top bar registers (as a ref) so pages can portal actions into it. */
+  mobileActionsSlot: HTMLElement | null;
+  setMobileActionsSlot: (slot: HTMLElement | null) => void;
+};
+
+export type DocumentTitleOptions = {
+  /** Appended after the page title, for example the app name. */
+  suffix?: string;
+  /** Between page title and suffix. Default `" · "`. */
+  separator?: string;
+  /** Title while no page title is set. Default: `document.title` when the provider mounted. */
+  fallback?: string;
+};
+
+export type PageTitleContextOptions = {
+  /**
+   * `usePageTitle()` outside the provider throws this message. When unset it
+   * returns an empty title and no-op setters instead.
+   */
+  missingProviderMessage?: string;
+  /**
+   * Also write `document.title` as `pageTitle + separator + suffix`, or
+   * `fallback` while the page title is empty. Off by default: the provider
+   * does not touch `document.title`. The mount-time title comes back on unmount.
+   */
+  documentTitle?: DocumentTitleOptions;
+};
+
+export type PageTitleContextKit = {
+  PageTitleProvider: (props: { children: ReactNode }) => ReactNode;
+  usePageTitle: () => PageTitleValue;
+  /** Publishes `title` while the caller is mounted; non-string titles publish `""`. Clears on unmount. */
+  usePageTitleSync: (title: ReactNode) => void;
+};
+
+const noop = () => {};
+
+function formatDocumentTitle(pageTitle: string, suffix: string | undefined, separator: string): string {
+  return suffix ? `${pageTitle}${separator}${suffix}` : pageTitle;
+}
+
+/** One page title context per app: the shell reads `pageTitle`, pages publish theirs. */
+export function createPageTitleContext(options: PageTitleContextOptions = {}): PageTitleContextKit {
+  const { missingProviderMessage, documentTitle } = options;
+  const Context = createContext<PageTitleValue | null>(null);
+  const fallbackValue: PageTitleValue = {
+    pageTitle: "",
+    setPageTitle: noop,
+    mobileActionsSlot: null,
+    setMobileActionsSlot: noop,
+  };
+
+  function useDocumentTitle(pageTitle: string): void {
+    const [mountTitle] = useState(() => (documentTitle && typeof document !== "undefined" ? document.title : ""));
+    useEffect(() => {
+      if (!documentTitle) return;
+      const { suffix, separator = " · ", fallback = mountTitle } = documentTitle;
+      document.title = pageTitle ? formatDocumentTitle(pageTitle, suffix, separator) : fallback;
+    }, [pageTitle, mountTitle]);
+    useEffect(() => {
+      if (!documentTitle) return;
+      return () => {
+        document.title = mountTitle;
+      };
+    }, [mountTitle]);
+  }
+
+  function PageTitleProvider({ children }: { children: ReactNode }) {
+    const [pageTitle, setPageTitle] = useState("");
+    const [mobileActionsSlot, setMobileActionsSlot] = useState<HTMLElement | null>(null);
+    useDocumentTitle(pageTitle);
+    return (
+      <Context value={{ pageTitle, setPageTitle, mobileActionsSlot, setMobileActionsSlot }}>{children}</Context>
+    );
+  }
+
+  function usePageTitle(): PageTitleValue {
+    const value = use(Context);
+    if (value !== null) return value;
+    if (missingProviderMessage !== undefined) throw new Error(missingProviderMessage);
+    return fallbackValue;
+  }
+
+  function usePageTitleSync(title: ReactNode): void {
+    const { setPageTitle } = usePageTitle();
+    const isStringTitle = typeof title === "string";
+    useEffect(() => {
+      setPageTitle(isStringTitle ? title : "");
+      return () => setPageTitle("");
+    }, [title, isStringTitle, setPageTitle]);
+  }
+
+  return { PageTitleProvider, usePageTitle, usePageTitleSync };
+}

package/app/src/theme/createThemeProvider.tsx

@@ -0,0 +1,275 @@
+import { createContext, use, useEffect, useState, type ReactNode } from "react";
+
+/** `"class"` or a `data-*` attribute on `<html>`. */
+export type ThemeAttribute = "class" | `data-${string}`;
+
+export type ThemeProviderProps = {
+  children?: ReactNode;
+  /** localStorage key. Default `"theme"`. */
+  storageKey?: string;
+  /** Used when nothing is stored. Default `"system"` with `enableSystem`, else `"light"`. */
+  defaultTheme?: string;
+  /** Resolve `"system"` from `prefers-color-scheme`. Default `true`. */
+  enableSystem?: boolean;
+  /** Set `style.colorScheme` on `<html>` for light and dark. Default `true`. */
+  enableColorScheme?: boolean;
+  /** Where the theme goes on `<html>`. Default `"data-theme"`. */
+  attribute?: ThemeAttribute | ThemeAttribute[];
+  /** Theme names. Default `["light", "dark"]`. */
+  themes?: string[];
+  /** Theme name to the class or attribute value written. */
+  value?: Record<string, string>;
+  /** Shown on `<html>` instead of the stored theme, which is left unchanged. */
+  forcedTheme?: string;
+  /** Turn CSS transitions off for one frame while the theme changes. Default `false`. */
+  disableTransitionOnChange?: boolean;
+  /** Nonce for the style element `disableTransitionOnChange` adds. */
+  nonce?: string;
+};
+
+export type ThemeState = {
+  /** Stored theme, `"system"` included. `undefined` only without `window`. */
+  theme: string | undefined;
+  /** Stores the theme. A function gets the theme of the render it came from. */
+  setTheme: (theme: string | ((theme: string | undefined) => string)) => void;
+  forcedTheme: string | undefined;
+  /** `theme`, with `"system"` resolved to `systemTheme`. */
+  resolvedTheme: string | undefined;
+  /** `themes` plus `"system"` with `enableSystem`. */
+  themes: string[];
+  /** `prefers-color-scheme` with `enableSystem`. Until the first effect runs it is `theme` unless that is `"system"` (as in next-themes). */
+  systemTheme: string | undefined;
+  /** `false` until the provider's first effect has run. */
+  mounted: boolean;
+  /** `mounted && resolvedTheme === "dark"`. */
+  isDark: boolean;
+  /** `setTheme(resolvedTheme === "dark" ? "light" : "dark")`. */
+  toggleTheme: () => void;
+};
+
+export type ThemeProviderOptions = {
+  /** `useTheme()` outside the provider throws this message. When unset it returns an empty state with no-op setters. */
+  missingProviderMessage?: string;
+};
+
+export type ThemeProviderKit = {
+  ThemeProvider: (props: ThemeProviderProps) => ReactNode;
+  useTheme: () => ThemeState;
+};
+
+const COLOR_SCHEMES = ["light", "dark"];
+const MEDIA = "(prefers-color-scheme: dark)";
+const DISABLE_TRANSITIONS_CSS =
+  "*,*::before,*::after{-webkit-transition:none!important;-moz-transition:none!important;-o-transition:none!important;-ms-transition:none!important;transition:none!important}";
+
+const noop = () => {};
+
+const emptyState: ThemeState = {
+  theme: undefined,
+  setTheme: noop,
+  forcedTheme: undefined,
+  resolvedTheme: undefined,
+  themes: [],
+  systemTheme: undefined,
+  mounted: false,
+  isDark: false,
+  toggleTheme: noop,
+};
+
+/** `prefers-color-scheme`, or `"light"` without `window`. */
+export function getSystemTheme(): "light" | "dark" {
+  if (typeof window === "undefined") return "light";
+  return window.matchMedia(MEDIA).matches ? "dark" : "light";
+}
+
+/** Replaces the `light` / `dark` class on `<html>` with `theme`. No-op without `document`. */
+export function applyThemeClass(theme: string): void {
+  if (typeof document === "undefined") return;
+  document.documentElement.classList.remove("light", "dark");
+  document.documentElement.classList.add(theme);
+}
+
+function systemThemeOf(media: { matches: boolean }): "light" | "dark" {
+  return media.matches ? "dark" : "light";
+}
+
+function readTheme(storageKey: string, fallback: string): string | undefined {
+  if (typeof window === "undefined") return undefined;
+  let stored: string | undefined;
+  try {
+    stored = localStorage.getItem(storageKey) || undefined;
+  } catch {
+    // Storage can be unavailable (privacy modes); fall back.
+  }
+  return stored || fallback;
+}
+
+function disableTransitions(nonce: string | undefined): () => void {
+  const style = document.createElement("style");
+  if (nonce) style.setAttribute("nonce", nonce);
+  style.appendChild(document.createTextNode(DISABLE_TRANSITIONS_CSS));
+  document.head.appendChild(style);
+  return () => {
+    // Force a style recalculation before the transitions come back.
+    window.getComputedStyle(document.body);
+    setTimeout(() => {
+      document.head.removeChild(style);
+    }, 1);
+  };
+}
+
+type DomOptions = Required<
+  Pick<ThemeProviderProps, "attribute" | "themes" | "enableSystem" | "enableColorScheme" | "defaultTheme" | "disableTransitionOnChange">
+> &
+  Pick<ThemeProviderProps, "value" | "nonce">;
+
+function applyTheme(theme: string | undefined, options: DomOptions): void {
+  if (!theme) return;
+  const resolved = theme === "system" && options.enableSystem ? systemThemeOf(window.matchMedia(MEDIA)) : theme;
+  const written = options.value ? options.value[resolved] : resolved;
+  const restoreTransitions = options.disableTransitionOnChange ? disableTransitions(options.nonce) : null;
+  const root = document.documentElement;
+  const removable = options.value ? Object.values(options.value) : options.themes;
+  for (const attribute of Array.isArray(options.attribute) ? options.attribute : [options.attribute]) {
+    if (attribute === "class") {
+      root.classList.remove(...removable);
+      if (written) root.classList.add(written);
+    } else if (attribute.startsWith("data-")) {
+      if (written) root.setAttribute(attribute, written);
+      else root.removeAttribute(attribute);
+    }
+  }
+  if (options.enableColorScheme) {
+    const fallback = COLOR_SCHEMES.includes(options.defaultTheme) ? options.defaultTheme : null;
+    // `null` clears the property in browsers; assigned as-is, as next-themes does.
+    Reflect.set(root.style, "colorScheme", COLOR_SCHEMES.includes(resolved) ? resolved : fallback);
+  }
+  restoreTransitions?.();
+}
+
+/**
+ * A theme provider with next-themes 0.4.6 semantics, plus `mounted`, `isDark`
+ * and `toggleTheme`. Each call makes its own context, so an app keeps one kit.
+ *
+ * Parity notes: the options that shape DOM writes (`attribute`, `themes`,
+ * `value`, `enableSystem`, `enableColorScheme`, `defaultTheme`,
+ * `disableTransitionOnChange`, `nonce`) are read once, on the first render, as
+ * in next-themes; `forcedTheme`, and `enableSystem` for the system listener and
+ * the returned state, follow props. A provider nested in another one from the
+ * same kit renders only its children. No inline script is rendered: in a
+ * client-rendered app React never runs it.
+ */
+export function createThemeProvider(options: ThemeProviderOptions = {}): ThemeProviderKit {
+  const { missingProviderMessage } = options;
+  const Context = createContext<ThemeState | undefined>(undefined);
+
+  /** next-themes hands out a new `setTheme` exactly when `theme` changes; apps list it in effect deps. */
+  function useSetTheme(
+    theme: string | undefined,
+    storageKey: string,
+    setThemeState: (theme: string) => void,
+  ): ThemeState["setTheme"] {
+    const make = (): ThemeState["setTheme"] => (next) => {
+      const resolved = typeof next === "function" ? next(theme) : next;
+      setThemeState(resolved);
+      try {
+        localStorage.setItem(storageKey, resolved);
+      } catch {
+        // Storage can be unavailable (privacy modes).
+      }
+    };
+    const [entry, setEntry] = useState(() => ({ theme, setTheme: make() }));
+    if (entry.theme === theme) return entry.setTheme;
+    const next = { theme, setTheme: make() };
+    setEntry(next);
+    return next.setTheme;
+  }
+
+  function Provider({
+    forcedTheme,
+    disableTransitionOnChange = false,
+    enableSystem = true,
+    enableColorScheme = true,
+    storageKey = "theme",
+    themes = COLOR_SCHEMES,
+    defaultTheme = enableSystem ? "system" : "light",
+    attribute = "data-theme",
+    value,
+    nonce,
+    children,
+  }: ThemeProviderProps) {
+    const [theme, setThemeState] = useState(() => readTheme(storageKey, defaultTheme));
+    const [systemTheme, setSystemTheme] = useState<string | undefined>(() =>
+      theme === "system" ? systemThemeOf(window.matchMedia(MEDIA)) : theme,
+    );
+    const [mounted, setMounted] = useState(false);
+    const [domOptions] = useState<DomOptions>(() => ({
+      attribute,
+      themes,
+      value,
+      enableSystem,
+      enableColorScheme,
+      defaultTheme,
+      disableTransitionOnChange,
+      nonce,
+    }));
+    const setTheme = useSetTheme(theme, storageKey, setThemeState);
+
+    useEffect(() => setMounted(true), []);
+
+    // Listener and handler are rebuilt whenever `theme` or `forcedTheme` changes.
+    useEffect(() => {
+      const handleMedia = (media: { matches: boolean }) => {
+        setSystemTheme(systemThemeOf(media));
+        if (theme === "system" && enableSystem && !forcedTheme) applyTheme("system", domOptions);
+      };
+      const media = window.matchMedia(MEDIA);
+      media.addListener(handleMedia);
+      handleMedia(media);
+      return () => media.removeListener(handleMedia);
+    }, [theme, forcedTheme]);
+
+    // Other tabs: follow a new value, or store the default when the key is removed.
+    useEffect(() => {
+      const handleStorage = (event: StorageEvent) => {
+        if (event.key !== storageKey) return;
+        if (event.newValue) setThemeState(event.newValue);
+        else setTheme(defaultTheme);
+      };
+      window.addEventListener("storage", handleStorage);
+      return () => window.removeEventListener("storage", handleStorage);
+    }, [setTheme]);
+
+    useEffect(() => {
+      applyTheme(forcedTheme ?? theme, domOptions);
+    }, [forcedTheme, theme]);
+
+    const resolvedTheme = theme === "system" ? systemTheme : theme;
+    const state: ThemeState = {
+      theme,
+      setTheme,
+      forcedTheme,
+      resolvedTheme,
+      themes: enableSystem ? [...themes, "system"] : themes,
+      systemTheme: enableSystem ? systemTheme : undefined,
+      mounted,
+      isDark: mounted && resolvedTheme === "dark",
+      toggleTheme: () => setTheme(resolvedTheme === "dark" ? "light" : "dark"),
+    };
+    return <Context value={state}>{children}</Context>;
+  }
+
+  function ThemeProvider(props: ThemeProviderProps) {
+    if (use(Context)) return <>{props.children}</>;
+    return <Provider {...props} />;
+  }
+
+  function useTheme(): ThemeState {
+    const state = use(Context);
+    if (state) return state;
+    if (missingProviderMessage !== undefined) throw new Error(missingProviderMessage);
+    return emptyState;
+  }
+
+  return { ThemeProvider, useTheme };
+}

package/app/src/time/compactRelativeTime.ts

@@ -0,0 +1,89 @@
+export type CompactRelativeTimeOptions = {
+  /** Clock in ms. Defaults to `Date.now()`. */
+  now?: number;
+  /**
+   * Returned for anything under a minute old, including future times. When
+   * unset the result is whole seconds (`"42s"`), and a future time gives zero
+   * or a negative count (`"0s"`, `"-300s"`).
+   */
+  justNow?: string;
+  /**
+   * `false` (default): elapsed time only. A day is 24 hours, a month 30 days,
+   * a year 12 of those months.
+   * `true`: days count local calendar days across a DST change, and months and
+   * years are calendar months, as `dayjs().diff(date, unit)` counts them.
+   */
+  calendar?: boolean;
+};
+
+const MS_PER_MINUTE = 60_000;
+const MS_PER_DAY = 86_400_000;
+
+/** Rounds toward zero; `-0` becomes `0`. */
+function truncate(n: number): number {
+  return n < 0 ? Math.ceil(n) || 0 : Math.floor(n);
+}
+
+/** Local UTC offset in minutes, rounded to 15 minutes. */
+function utcOffset(ms: number): number {
+  return -Math.round(new Date(ms).getTimezoneOffset() / 15) * 15;
+}
+
+/** Adds calendar months in local time and clamps the day to the target month. */
+function addMonths(ms: number, months: number): number {
+  const date = new Date(ms);
+  const day = date.getDate();
+  date.setDate(1);
+  date.setMonth(date.getMonth() + months);
+  const daysInMonth = new Date(date.getFullYear(), date.getMonth() + 1, 0).getDate();
+  date.setDate(Math.min(day, daysInMonth));
+  return date.getTime();
+}
+
+/** Fractional calendar months from `a` to `b`, negated (the moment.js formula). */
+function monthDiff(a: number, b: number): number {
+  if (new Date(a).getDate() < new Date(b).getDate()) return -monthDiff(b, a);
+  const from = new Date(a);
+  const to = new Date(b);
+  const whole = (to.getFullYear() - from.getFullYear()) * 12 + (to.getMonth() - from.getMonth());
+  const anchor = addMonths(a, whole);
+  const before = b - anchor < 0;
+  const anchor2 = addMonths(a, whole + (before ? -1 : 1));
+  return +(-(whole + (b - anchor) / (before ? anchor - anchor2 : anchor2 - anchor)) || 0);
+}
+
+/**
+ * Time since `date` as one compact unit: `"now"` or `"42s"`, then `"5m"`,
+ * `"3h"`, `"2d"`, `"4mo"`, `"1y"`. Strings are parsed with `new Date(string)`.
+ * An invalid date gives `"NaNy"`, or `"0mo"` with `calendar`.
+ */
+export function formatCompactRelativeTime(
+  date: string | number | Date,
+  options: CompactRelativeTimeOptions = {},
+): string {
+  const now = options.now ?? Date.now();
+  const then = new Date(date).getTime();
+  const diff = now - then;
+
+  const seconds = truncate(diff / 1000);
+  if (seconds < 60) return options.justNow ?? `${seconds}s`;
+  const minutes = truncate(diff / MS_PER_MINUTE);
+  if (minutes < 60) return `${minutes}m`;
+  const hours = truncate(diff / (60 * MS_PER_MINUTE));
+  if (hours < 24) return `${hours}h`;
+
+  if (!options.calendar) {
+    const days = Math.floor(hours / 24);
+    if (days < 30) return `${days}d`;
+    const months = Math.floor(days / 30);
+    if (months < 12) return `${months}mo`;
+    return `${Math.floor(months / 12)}y`;
+  }
+
+  const zoneDelta = (utcOffset(then) - utcOffset(now)) * MS_PER_MINUTE;
+  const days = truncate((diff - zoneDelta) / MS_PER_DAY);
+  if (days < 30) return `${days}d`;
+  const months = monthDiff(now, then);
+  if (truncate(months) < 12) return `${truncate(months)}mo`;
+  return `${truncate(months / 12)}y`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vvedantb/ui",
-  "version": "0.7.1",
+  "version": "0.8.0",
   "license": "MIT",
   "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",
@@ -52,15 +52,6 @@
   "sideEffects": [
     "./src/ui/sonner.css"
   ],
-  "scripts": {
-    "check:tokens": "node tokens/scripts/check-component-tokens.mjs",
-    "build": "node tokens/scripts/check-exports.mjs && node tokens/scripts/check-component-tokens.mjs && tsc -p tsconfig.json",
-    "typecheck": "tsc -p tsconfig.json && tsc -p tokens/tsconfig.json",
-    "test": "node tokens/scripts/check-component-tokens.mjs && vitest run && node --test tokens/test/*.test.mjs",
-    "verify": "node tokens/scripts/check-component-tokens.mjs && node tokens/verify/run.mjs",
-    "analyze": "node tokens/verify/analyze.mjs",
-    "prepack": "node tokens/scripts/check-exports.mjs"
-  },
   "peerDependencies": {
     "@clerk/clerk-react": ">=5",
     "@radix-ui/react-accordion": "^1.2.12",
@@ -140,10 +131,12 @@
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "cmdk": "^1.1.1",
+    "dayjs": "1.11.19",
     "embla-carousel-react": "^8.6.0",
     "happy-dom": "^18.0.0",
     "motion": "^12.0.0",
     "nanoid": "^5.1.0",
+    "next-themes": "0.4.6",
     "radix-ui": "^1.4.0",
     "react": "^19.1.0",
     "react-dom": "^19.1.0",
@@ -171,5 +164,13 @@
     "zod": {
       "optional": true
     }
+  },
+  "scripts": {
+    "check:tokens": "node tokens/scripts/check-component-tokens.mjs",
+    "build": "node tokens/scripts/check-exports.mjs && node tokens/scripts/check-component-tokens.mjs && tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json && tsc -p tokens/tsconfig.json",
+    "test": "node tokens/scripts/check-component-tokens.mjs && vitest run && node --test tokens/test/*.test.mjs app/tests-node/*.test.mjs",
+    "verify": "node tokens/scripts/check-component-tokens.mjs && node tokens/verify/run.mjs",
+    "analyze": "node tokens/verify/analyze.mjs"
   }
-}
+}

package/shell/src/Sidebar.tsx

@@ -9,7 +9,18 @@ import {
   AccountSeparator,
   AccountTrigger,
 } from "./SidebarAccountMenu";
-import { NavItem, Panel, PanelActions, PanelClose, PanelHeader, PanelTitle } from "./SidebarPanel";
+import {
+  NavItem,
+  NavItemActions,
+  NavItemLabel,
+  NavItemLeading,
+  NavItemTrailing,
+  Panel,
+  PanelActions,
+  PanelClose,
+  PanelHeader,
+  PanelTitle,
+} from "./SidebarPanel";
 import { Rail, RailBody, RailFooter, RailHeader, RailItem, RailSeparator } from "./SidebarRail";
 
 export type {
@@ -36,6 +47,7 @@ export type {
   SidebarPanelHeaderProps,
   SidebarPanelRootProps,
   SidebarPanelTitleProps,
+  SidebarNavItemPartProps,
   SidebarNavItemProps,
 } from "./SidebarPanel";
 export type {
@@ -70,6 +82,10 @@ export const Sidebar = {
   PanelActions,
   PanelClose,
   NavItem,
+  NavItemLeading,
+  NavItemLabel,
+  NavItemTrailing,
+  NavItemActions,
   AccountMenu,
   AccountTrigger,
   AccountAvatar,

package/shell/src/SidebarPanel.tsx

@@ -3,7 +3,17 @@ import { Slot, Slottable } from "@radix-ui/react-slot";
 import { IconX } from "@tabler/icons-react";
 import { Button, type ButtonProps } from "../../src/ui/button";
 import { cn } from "../../src/utils/cn";
-import { panelCloseButtonClass, sidebarHeaderRowClass, sidebarNavIconClass, sidebarNavItemClass } from "./app-shell-classes";
+import {
+  panelCloseButtonClass,
+  sidebarHeaderRowClass,
+  sidebarNavIconClass,
+  sidebarNavItemActionsClass,
+  sidebarNavItemClass,
+  sidebarNavItemIndentStyle,
+  sidebarNavItemLabelClass,
+  sidebarNavItemLeadingClass,
+  sidebarNavItemTrailingClass,
+} from "./app-shell-classes";
 import { useOptionalSidebar } from "./SidebarChrome";
 
 export type SidebarPanelProps = {
@@ -134,23 +144,36 @@ export function PanelClose({ label = "Close navigation", onClick, className, chi
 }
 
 export type SidebarNavItemProps = ComponentPropsWithoutRef<"button"> & {
-  /** Current route: static fill, `font-medium`, `aria-current="page"`. */
+  /** Current route: static fill, `font-medium`, `aria-current="page"`, `data-active="true"`. */
   active?: boolean;
   /** Collapsed panel: centred icon, no horizontal padding. */
   iconOnly?: boolean;
-  /** Leading icon element; gets `sidebarNavIconClass(active)` merged onto it. */
+  /** Leading icon element; gets `sidebarNavIconClass(active)` merged onto it. For other leading content use `Sidebar.NavItemLeading`. */
   icon?: ReactElement;
   /** Render the single child element (for example a router link) as the row. */
   asChild?: boolean;
+  /** Picked (for example in a multi-select list): the active fill without `font-medium`. Sets `data-selected="true"`. */
+  selected?: boolean;
+  /** Nesting level from 0. Each level adds 12px to the 16px left padding. Ignored with `iconOnly`. */
+  indent?: number;
+  /** Row being dragged. Sets `data-dragging="true"`. */
+  dragging?: boolean;
+  /** Row under a drag. Sets `data-drop-target="true"`. */
+  dropTarget?: boolean;
 };
 
-/** Panel nav row (`sidebarNavItemClass`). Renders a native `<button>`, or its child with `asChild`. */
+/** Panel nav row (`sidebarNavItemClass`). Renders a native `<button>`, or its child with `asChild`. Compose `NavItemLeading`, `NavItemLabel`, `NavItemTrailing` and `NavItemActions` inside. */
 export function NavItem({
   active = false,
   iconOnly = false,
   icon,
   asChild = false,
+  selected = false,
+  indent = 0,
+  dragging = false,
+  dropTarget = false,
   className,
+  style,
   children,
   ...props
 }: SidebarNavItemProps) {
@@ -160,6 +183,11 @@ export function NavItem({
       type={asChild ? undefined : "button"}
       {...props}
       aria-current={active ? "page" : undefined}
+      data-active={active || undefined}
+      data-selected={selected || undefined}
+      data-dragging={dragging || undefined}
+      data-drop-target={dropTarget || undefined}
+      style={indent > 0 && !iconOnly ? { ...sidebarNavItemIndentStyle(indent), ...style } : style}
       className={cn(sidebarNavItemClass({ active, iconOnly }), className)}
     >
       {icon ? <Slot className={sidebarNavIconClass(active)}>{icon}</Slot> : null}
@@ -167,3 +195,36 @@ export function NavItem({
     </Row>
   );
 }
+
+export type SidebarNavItemPartProps = ComponentPropsWithoutRef<"span"> & {
+  /** Merge the part classes onto the single child element instead of a `<span>`. */
+  asChild?: boolean;
+};
+
+function NavItemPart({ partClass, asChild = false, className, ...props }: SidebarNavItemPartProps & { partClass: string }) {
+  const Part = asChild ? Slot : "span";
+  return <Part {...props} className={cn(partClass, className)} />;
+}
+
+/** Leading slot of a nav row: checkbox, icon, avatar or status dot (`sidebarNavItemLeadingClass`). */
+export function NavItemLeading(props: SidebarNavItemPartProps) {
+  return <NavItemPart {...props} partClass={sidebarNavItemLeadingClass} />;
+}
+
+/** Truncated label of a nav row (`sidebarNavItemLabelClass`). `asChild` on a rename input keeps the layout. */
+export function NavItemLabel(props: SidebarNavItemPartProps) {
+  return <NavItemPart {...props} partClass={sidebarNavItemLabelClass} />;
+}
+
+/** Always-visible trailing content of a nav row: counts, badges, spinners (`sidebarNavItemTrailingClass`). */
+export function NavItemTrailing(props: SidebarNavItemPartProps) {
+  return <NavItemPart {...props} partClass={sidebarNavItemTrailingClass} />;
+}
+
+/**
+ * Hover-revealed actions of a nav row, such as a `...` menu (`sidebarNavItemActionsClass`).
+ * Adds no handlers: stop propagation (and prevent default inside a link) on the button.
+ */
+export function NavItemActions(props: SidebarNavItemPartProps) {
+  return <NavItemPart {...props} partClass={sidebarNavItemActionsClass} />;
+}

package/shell/src/app-shell-classes.ts

@@ -28,13 +28,14 @@ export const sidebarSectionLabelClass =
   "sidebar-section-label px-4 py-1 text-[11px] leading-4 font-medium tracking-[-0.01em]";
 
 /**
- * Nav row state: idle rows are `foreground/80` and get the fill on hover;
- * the active row is `font-medium text-foreground` on a static fill.
+ * Nav row state: idle rows are `foreground/80` and get the `sidebar-accent`
+ * fill on hover; the active row is `font-medium text-foreground` on a static
+ * fill.
  */
 export function sidebarNavLinkTextClass(isActive: boolean): string {
   return isActive
-    ? "bg-surface-tertiary font-medium text-foreground"
-    : "font-normal text-foreground/80 hover:bg-surface-tertiary hover:text-foreground";
+    ? "bg-sidebar-accent font-medium text-foreground"
+    : "font-normal text-foreground/80 hover:bg-sidebar-accent hover:text-foreground";
 }
 
 /**
@@ -53,13 +54,73 @@ export type SidebarNavItemClassOptions = {
   active?: boolean;
   /** Collapsed panel: centred icon, no horizontal padding. */
   iconOnly?: boolean;
+  /** Picked (for example in a multi-select list): the active fill, without `font-medium`. Same as `data-selected="true"`. */
+  selected?: boolean;
+  /** Row being dragged: `opacity-40 cursor-grabbing`. Same as `data-dragging="true"`. */
+  dragging?: boolean;
+  /** Row under a drag: fill plus an inset `ring-focus` ring. Same as `data-drop-target="true"`. */
+  dropTarget?: boolean;
 };
 
-/** Whole panel nav row: `sidebarNavRowClass` plus `sidebarNavLinkTextClass`. */
-export function sidebarNavItemClass({ active = false, iconOnly = false }: SidebarNavItemClassOptions = {}): string {
-  return cn(sidebarNavRowClass(iconOnly), sidebarNavLinkTextClass(active));
+// Row states an app can also set as data attributes on the row itself.
+const sidebarNavItemDataStateClass =
+  "data-[selected=true]:bg-sidebar-accent data-[selected=true]:text-foreground data-[dragging=true]:cursor-grabbing data-[dragging=true]:opacity-40 data-[drop-target=true]:bg-sidebar-accent data-[drop-target=true]:text-foreground data-[drop-target=true]:ring-2 data-[drop-target=true]:ring-inset data-[drop-target=true]:ring-focus";
+
+/**
+ * Whole panel nav row: `sidebarNavRowClass` plus `sidebarNavLinkTextClass`,
+ * plus `data-selected`, `data-dragging` and `data-drop-target` (`="true"`)
+ * styles. The `selected`, `dragging` and `dropTarget` options apply the same
+ * styles without the attributes.
+ */
+export function sidebarNavItemClass({
+  active = false,
+  iconOnly = false,
+  selected = false,
+  dragging = false,
+  dropTarget = false,
+}: SidebarNavItemClassOptions = {}): string {
+  return cn(
+    sidebarNavRowClass(iconOnly),
+    sidebarNavLinkTextClass(active),
+    sidebarNavItemDataStateClass,
+    selected && "bg-sidebar-accent text-foreground",
+    dragging && "cursor-grabbing opacity-40",
+    dropTarget && "bg-sidebar-accent text-foreground ring-2 ring-inset ring-focus",
+  );
+}
+
+/**
+ * Nested row padding: each `indent` level adds 12px to the row's 16px
+ * (`px-4`) left padding. Put it on the row's `style`.
+ */
+export function sidebarNavItemIndentStyle(indent: number): { paddingLeft: string } {
+  return { paddingLeft: `calc(1rem + ${indent * 12}px)` };
 }
 
+/** Row part: leading checkbox, icon, avatar or status dot. */
+export const sidebarNavItemLeadingClass = "flex shrink-0 items-center";
+
+/**
+ * Row part: the label, which takes the free width and truncates. For two
+ * lines, put `block truncate` spans inside (subtitle: `sidebarNavItemSubtitleClass`).
+ */
+export const sidebarNavItemLabelClass = "min-w-0 flex-1 truncate";
+
+/** Second, muted line inside the label. */
+export const sidebarNavItemSubtitleClass = "block truncate text-xs text-muted-foreground";
+
+/** Row part: always-visible trailing content (counts, badges, spinners). */
+export const sidebarNavItemTrailingClass = "ml-auto flex shrink-0 items-center gap-1.5 text-xs text-muted-foreground";
+
+/**
+ * Row part: actions such as a `...` menu button. In the row flow at the end,
+ * 24px tall without growing the row. Hidden until the row is hovered or has
+ * focus, or a menu trigger inside it (or the part itself) is
+ * `data-state="open"`.
+ */
+export const sidebarNavItemActionsClass =
+  "-my-1 ml-auto flex h-6 shrink-0 items-center opacity-0 transition-opacity duration-75 group-hover:opacity-100 group-focus-within:opacity-100 has-[[data-state=open]]:opacity-100 data-[state=open]:opacity-100";
+
 /** Nav row icon (put it on the `<svg>`): 19px, muted until active. */
 export function sidebarNavIconClass(active: boolean): string {
   return cn("size-[19px] shrink-0", active ? "text-foreground" : "text-muted-foreground");

package/shell/src/index.ts

@@ -46,7 +46,13 @@ export {
   railTileClass,
   railTileStateClass,
   sidebarNavIconClass,
+  sidebarNavItemActionsClass,
   sidebarNavItemClass,
+  sidebarNavItemIndentStyle,
+  sidebarNavItemLabelClass,
+  sidebarNavItemLeadingClass,
+  sidebarNavItemSubtitleClass,
+  sidebarNavItemTrailingClass,
   sidebarNavLinkTextClass,
   sidebarNavRowClass,
   sidebarSectionLabelClass,

package/src/index.ts

@@ -159,7 +159,13 @@ export {
   railTileClass,
   railTileStateClass,
   sidebarNavIconClass,
+  sidebarNavItemActionsClass,
   sidebarNavItemClass,
+  sidebarNavItemIndentStyle,
+  sidebarNavItemLabelClass,
+  sidebarNavItemLeadingClass,
+  sidebarNavItemSubtitleClass,
+  sidebarNavItemTrailingClass,
   sidebarNavLinkTextClass,
   sidebarNavRowClass,
   sidebarSectionLabelClass,

package/tokens/src/css/compat-shadcn-rgb.css

@@ -23,6 +23,9 @@
  * --accent, --accent-foreground, --destructive, --destructive-foreground,
  * --border, --input, --ring and --radius (all colours as "R G B").
  *
+ * `--color-sidebar-accent` (sidebar nav row fill) reads the app's
+ * `--sidebar-accent` when it is defined, else `--secondary`.
+ *
  * `--color-card` and `--color-muted` are references to `--card` and `--muted`.
  * `SonnerToaster sonnerVars` reads them, along with `--color-border` and
  * `--color-foreground`. An app that already maps those names keeps its own
@@ -44,6 +47,7 @@
   --color-surface-secondary-foreground: rgb(var(--foreground));
   --color-surface-tertiary: rgb(var(--secondary));
   --color-surface-tertiary-foreground: rgb(var(--secondary-foreground));
+  --color-sidebar-accent: rgb(var(--sidebar-accent, var(--secondary)));
   --color-overlay: rgb(var(--popover));
   --color-overlay-foreground: rgb(var(--popover-foreground));
   --color-field-background: rgb(var(--card));

package/tokens/src/tokens.css

@@ -56,6 +56,7 @@
   --color-surface-tertiary: var(--surface-tertiary);
   --color-surface-tertiary-foreground: var(--surface-tertiary-foreground);
   --color-surface-card: var(--surface-card);
+  --color-sidebar-accent: var(--sidebar-accent);
   --color-warning: var(--warning);
   --color-warning-foreground: var(--warning-foreground);
 
@@ -155,6 +156,8 @@
     --surface-tertiary: oklch(93.73% 0 0);
     --surface-tertiary-foreground: oklch(21.03% 0 0);
     --surface-card: oklch(98% 0 0);
+    /* Sidebar nav row hover, active and selected fill. */
+    --sidebar-accent: var(--surface-tertiary);
     --warning: oklch(78.19% 0.159 72.33);
     --warning-foreground: oklch(21.03% 0.0059 72.33);
     --radius: 1rem;
@@ -202,6 +205,8 @@
     --surface-tertiary: oklch(27.21% 0.0023 0);
     --surface-tertiary-foreground: oklch(99.11% 0 0);
     --surface-card: oklch(25.7% 0.0023 0);
+    /* sRGB 28 28 28: a step darker than --surface-tertiary. */
+    --sidebar-accent: oklch(22.64% 0 0);
     --warning: oklch(82.03% 0.1392 76.34);
     --warning-foreground: oklch(21.03% 0.0059 76.34);
     --radius: 1rem;

package/app/README.md

@@ -1,100 +0,0 @@
-# App helpers (`@vvedantb/ui`)
-
-Shared web React helpers that were duplicated across apps. Source-exported as the `./app` subpath of `@vvedantb/ui`.
-
-## Install
-
-```sh
-npm install @vvedantb/ui
-```
-
-## Peers
-
-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. 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}";
-```
-
-## Confirm skip (Alt-click)
-
-```tsx
-import { ConfirmSkipHint, skipConfirmTitle, useRequestConfirm } from "@vvedantb/ui";
-
-const { request } = useRequestConfirm();
-
-<DropdownMenuItem
-  title={skipConfirmTitle("Delete")}
-  onSelect={(event) => request(() => setOpen(true), () => remove(), event)}
->
-  Delete <ConfirmSkipHint />
-</DropdownMenuItem>
-```
-
-- `useRequestConfirm` does not subscribe to Alt. It reads `getAltHeld()` when the request happens, so the menu owner does not re-render when Alt goes down. It returns `{ request }` only.
-- `ConfirmSkipHint` stays mounted and gains a `hidden` class when Alt is not held, so an open Radix menu keeps a stable child tree.
-- The Alt store resets when the last subscriber leaves, clears on blur and tab hide, and cancels a bare Alt keydown only inside `[role='menu']` or `[data-radix-menu-content]`.
-- Also exported: `useAltHeld`, `getAltHeld`, `createAltHeldStore`, `bindToWindow`, `shouldSkipConfirm`, `requestConfirm`.
-
-## Update available watcher
-
-```ts
-import { toast } from "sonner";
-import { startUpdateAvailableWatcher } from "@vvedantb/ui";
-
-useEffect(
-  () =>
-    startUpdateAvailableWatcher({
-      origin: window.location.origin,
-      toast,
-      closeConvex: () => void convex.close(),
-      enabled: !import.meta.env.DEV,
-    }),
-  [],
-);
-```
-
-Options: `origin`, `toast`, `closeConvex?`, `pollMs?` (default 60000), `toastId?` (default `app-update-available`), `enabled?` (default true), `reload?` (default `window.location.reload`). On a changed asset fingerprint it shows a sticky "Update available" toast. Refresh calls `closeConvex` (errors ignored), then reloads. `fingerprintFromHtml` and `fetchDeployFingerprint` are exported too. The fingerprint looks for Vite `/assets/*.js` URLs in the index HTML.
-
-## Settings chrome
-
-```tsx
-import { SettingsPage, SettingsSection, SettingsToggleRow } from "@vvedantb/ui";
-
-<SettingsPage
-  title="Notifications"
-  layout={({ title, headerRight, toolbar, tabs, fillHeight, children }) => (
-    <PageContainer title={title} rightSection={headerRight} toolbar={toolbar} tabs={tabs} noScroll={fillHeight}>
-      {children}
-    </PageContainer>
-  )}
->
-  <SettingsSection title="Email" bodyVariant="list">
-    <SettingsToggleRow title="Weekly digest" action={<Switch />} />
-  </SettingsSection>
-</SettingsPage>
-```
-
-Exports: `SettingsSection`, `SettingsField`, `SettingsStack`, `SettingsToggleRow`, `SettingsEmptyState` (icon is `ComponentType<{ size?: number; className?: string }>`), `SettingsPage`. `SettingsField` `layout`: `"stacked"` (default) puts the label above the control. `"horizontal"` renders one row with the label and description on the left and the control on the right. Without `layout`, `SettingsPage` renders a plain `div` with a heading and the optional slots.
-
-## useStableAuth
-
-```ts
-import { useStableAuth } from "@vvedantb/ui"; // 2000 ms debounce, wraps Clerk useAuth
-import { createUseStableAuth } from "@vvedantb/ui";
-
-const useAuth = createUseStableAuth(useClerkAuth, { debounceMs: 3000 });
-```
-
-After a signed-in session, a drop to signed-out reports `isLoaded: false` for the debounce window so Convex does not cascade. State is module-level. `resetStableAuthSession()` clears it and is for tests only.
-
-## Develop
-
-```sh
-pnpm --filter @vvedantb/ui typecheck
-pnpm --filter @vvedantb/ui test
-```
-
-Source is in `app/src` and tests in `app/tests`. Publish steps are in the root `README.md`.

package/tokens/README.md

@@ -1,98 +0,0 @@
-# `@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. 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. |
-| `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-tab`, 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). |
-| `@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`, the same three radius utilities as `tokens.css` and a `glass-panel-strong` fallback. Import it **or** `tokens.css`, never both. |
-| `@vvedantb/ui/tokens/css/index.css` | `src/css/index.css` | base + dialog + utilities + scrollbar-thin + animations, for new CSS-first apps. |
-| `@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... */
-```
-
-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` | app `:root` |
-| `tabs.css` | `--tabs-dur`, `--tabs-ease` (app `:root`); `--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 |
-| `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`, `utilities.css`, `dialog.css`, `modal.css` and `tabs.css` need no `tokens.css`. `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` |
-
-## 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.