@vvedantb/ui 0.7.2 → 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. |

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.2",
+  "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/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. 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. |
-| `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.