@vvedantb/ui 0.1.5 → 0.2.0

package/README.md

@@ -0,0 +1,24 @@
+# @vvedantb/ui
+
+Shared React 19 web UI. Source-exported: no build step.
+
+| Import | What it is |
+| --- | --- |
+| `@vvedantb/ui` | Primitives (Radix-based) and AI elements. |
+| `@vvedantb/ui/cn` | `cn` class helper (clsx + tailwind-merge). |
+| `@vvedantb/ui/shell` | Router-free `SidebarHeader` and `PillTabs`. |
+| `@vvedantb/ui/app` | Alt-click confirm skip, update watcher, settings chrome, `useStableAuth`. See `app/README.md` in the repository. |
+| `@vvedantb/ui/tokens` | `tokens.css`: colour, radius, shadow, ease and font tokens for Tailwind v4. |
+| `@vvedantb/ui/tokens/css/*.css` | `index`, `base`, `dialog`, `modal`, `tabs`, `tabs-pills`, `utilities`, `scrollbar-thin`, `animations`. |
+| `@vvedantb/ui/tokens/tailwind-preset` | Tailwind preset for apps that load a JS config with `@config`. |
+| `@vvedantb/ui/tokens/native` | JS colours, radii and spacing. No CSS, no React DOM. |
+
+```css
+@import "tailwindcss";
+@import "@vvedantb/ui/tokens";
+@source "../node_modules/@vvedantb/ui/src/**/*.{ts,tsx}";
+```
+
+`@clerk/clerk-react`, `@tanstack/react-hotkeys` and `zod` are optional peers. Install them only if you import `@vvedantb/ui/app`.
+
+Full documentation: the repository `README.md`. Upgrading from `@vvedantb/tokens`, `@vvedantb/shell` or `@vvedantb/app-kit`: `MIGRATION.md`.

package/app/src/auth/useStableAuth.ts

@@ -0,0 +1,69 @@
+import { useAuth } from "@clerk/clerk-react";
+import { useEffect, useState } from "react";
+
+/** The two Clerk `useAuth` fields the hook reads. */
+export type ClerkAuthSlice = {
+  isLoaded: boolean;
+  isSignedIn: boolean | undefined;
+};
+
+export type StableAuthOptions = {
+  /** How long a sign-in loss reads as "still loading". Default 2000 ms. */
+  debounceMs?: number;
+};
+
+// Tracks sign-in during this session to detect stale deploy auth loss.
+let wasEverSignedIn = false;
+
+/**
+ * Test-only. Clears the module-level "was ever signed in" flag so one test
+ * cannot leak state into the next. Do not call from app code.
+ */
+export function resetStableAuthSession(): void {
+  wasEverSignedIn = false;
+}
+
+/**
+ * Build a `useAuth` wrapper that debounces a brief signed-in to signed-out
+ * flicker (for example after a deploy) by reporting `isLoaded: false` for
+ * `debounceMs`, so Convex does not cascade on a transient auth loss.
+ */
+export function createUseStableAuth<T extends ClerkAuthSlice>(
+  useAuthHook: () => T,
+  options: StableAuthOptions = {},
+): () => T {
+  const debounceMs = options.debounceMs ?? 2000;
+
+  return function useStableAuth(): T {
+    const auth = useAuthHook();
+    const [overrideLoading, setOverrideLoading] = useState(false);
+
+    useEffect(() => {
+      if (auth.isSignedIn) {
+        wasEverSignedIn = true;
+        setOverrideLoading(false);
+        return;
+      }
+
+      if (wasEverSignedIn && auth.isLoaded && !auth.isSignedIn) {
+        setOverrideLoading(true);
+        const timer = setTimeout(() => {
+          wasEverSignedIn = false;
+          setOverrideLoading(false);
+        }, debounceMs);
+        return () => clearTimeout(timer);
+      }
+
+      setOverrideLoading(false);
+    }, [auth.isLoaded, auth.isSignedIn]);
+
+    if (overrideLoading) {
+      return { ...auth, isLoaded: false };
+    }
+    return auth;
+  };
+}
+
+/** `useAuth` from `@clerk/clerk-react` with the 2000 ms debounce. */
+export const useStableAuth: () => ReturnType<typeof useAuth> =
+  createUseStableAuth(useAuth);

package/app/src/cn.ts

@@ -0,0 +1,6 @@
+type ClassPart = string | false | null | undefined;
+
+/** Minimal class join. Drops falsy parts; does not merge conflicting Tailwind classes. */
+export function cn(...parts: ClassPart[]): string {
+  return parts.filter(Boolean).join(" ");
+}

package/app/src/confirm/ConfirmSkipHint.tsx

@@ -0,0 +1,35 @@
+import { formatForDisplay, type Hotkey } from "@tanstack/react-hotkeys";
+import { cn } from "../cn.js";
+import { z } from "zod";
+import { useAltHeld } from "./useAltHeld.js";
+
+// `Hotkey` covers combinations, not a bare modifier, so the literal is parsed
+// in rather than asserted. `formatForDisplay` renders it as ⌥ / Alt.
+const ALT_HOTKEY = z.custom<Hotkey>().parse("Alt");
+
+/** Platform-native "⌥-click skips confirmation" / "Alt-click skips confirmation". */
+export function skipConfirmTitle(actionTitle?: string): string {
+  const skip = `${formatForDisplay(ALT_HOTKEY)}-click skips confirmation`;
+  return actionTitle ? `${actionTitle} · ${skip}` : skip;
+}
+
+/**
+ * Visible only while Alt is held. Stays mounted (hidden) otherwise so an open
+ * Radix menu item keeps a stable child tree. Sits after the action label so every
+ * confirmable control shows that this click will skip the dialog.
+ */
+export function ConfirmSkipHint({ className }: { className?: string }) {
+  const altHeld = useAltHeld();
+  return (
+    <kbd
+      className={cn(
+        "ml-auto shrink-0 rounded bg-surface-secondary px-1 py-0.5 font-mono text-[10px] text-muted",
+        !altHeld && "hidden",
+        className,
+      )}
+      aria-hidden
+    >
+      {formatForDisplay(ALT_HOTKEY)}
+    </kbd>
+  );
+}

package/app/src/confirm/confirmSkip.ts

@@ -0,0 +1,26 @@
+/**
+ * Whether this activation should skip the confirmation dialog.
+ *
+ * `event.altKey` covers the click itself. `altHeld` covers Radix `onSelect`
+ * (and keyboard activation) which do not carry the modifier.
+ */
+export function shouldSkipConfirm(
+  altHeld: boolean,
+  event?: { altKey?: boolean } | null,
+): boolean {
+  return altHeld || event?.altKey === true;
+}
+
+/** Open the dialog, or run the action immediately when Alt is held. */
+export function requestConfirm(
+  altHeld: boolean,
+  open: () => void,
+  confirm: () => void,
+  event?: { altKey?: boolean } | null,
+): void {
+  if (shouldSkipConfirm(altHeld, event)) {
+    confirm();
+    return;
+  }
+  open();
+}

package/app/src/confirm/useAltHeld.ts

@@ -0,0 +1,128 @@
+import { useSyncExternalStore } from "react";
+
+/**
+ * Whether Alt (Option on macOS) is held right now.
+ *
+ * Subscribes to the window so every confirmable control can restyle when the
+ * modifier goes down, and so Alt+click still works when the activating event
+ * is a Radix `onSelect` that does not carry `altKey`.
+ *
+ * Cleared on blur / visibility hide so a missed keyup after alt-tab cannot
+ * leave the app stuck in skip-confirm mode.
+ */
+
+/** The only two fields the store reads off a keyboard event. */
+export type AltKeyEvent = { key: string; altKey: boolean };
+
+/** What the binding feeds the store. `clear` is any event that can swallow a keyup. */
+export type AltHeldSignals = {
+  keyDown: (event: AltKeyEvent) => void;
+  keyUp: (event: AltKeyEvent) => void;
+  clear: () => void;
+};
+
+/** Wires the signals to a real event source and returns the unbind. */
+export type AltHeldBinding = (signals: AltHeldSignals) => () => void;
+
+export type AltHeldStore = {
+  subscribe: (onStoreChange: () => void) => () => void;
+  getSnapshot: () => boolean;
+};
+
+/**
+ * The binding is injected so the state machine can be driven without a DOM.
+ * Listeners attach lazily and, crucially, the held flag resets when the last
+ * subscriber leaves: with nothing bound, a keyup can no longer be observed, so
+ * a flag left at `true` would survive into the next mount and silently skip the
+ * confirmation dialog on a plain click.
+ */
+export function createAltHeldStore(bind: AltHeldBinding): AltHeldStore {
+  let altHeld = false;
+  let unbind: (() => void) | null = null;
+  const listeners = new Set<() => void>();
+
+  function setHeld(next: boolean): void {
+    if (altHeld === next) return;
+    altHeld = next;
+    for (const listener of listeners) listener();
+  }
+
+  const signals: AltHeldSignals = {
+    keyDown: (event) => {
+      if (event.key === "Alt" || event.altKey) setHeld(true);
+    },
+    keyUp: (event) => {
+      // A keyup for some other key still reports altKey while Alt is down, so
+      // only a released Alt — or a keyup without the modifier — clears.
+      if (event.key === "Alt" || !event.altKey) setHeld(false);
+    },
+    clear: () => setHeld(false),
+  };
+
+  return {
+    subscribe: (onStoreChange) => {
+      if (unbind === null) unbind = bind(signals);
+      listeners.add(onStoreChange);
+      return () => {
+        listeners.delete(onStoreChange);
+        if (listeners.size > 0) return;
+        unbind?.();
+        unbind = null;
+        // Nothing is listening for the keyup any more; start the next mount
+        // from a known-unheld state rather than a stale `true`.
+        altHeld = false;
+      };
+    },
+    getSnapshot: () => altHeld,
+  };
+}
+
+function isInOpenMenu(target: EventTarget | null): boolean {
+  return (
+    target instanceof Element &&
+    target.closest("[role='menu'], [data-radix-menu-content]") !== null
+  );
+}
+
+/** Default binding: window key events plus blur and tab-hide clears. */
+export const bindToWindow: AltHeldBinding = (signals) => {
+  if (typeof window === "undefined") return () => {};
+  const onKeyDown = (event: KeyboardEvent): void => {
+    // A bare Alt press can steal focus to the browser menu bar and dismiss an
+    // open Radix menu. Cancel it only when it lands inside one.
+    if (event.key === "Alt" && isInOpenMenu(event.target)) {
+      event.preventDefault();
+    }
+    signals.keyDown(event);
+  };
+  const onKeyUp = (event: KeyboardEvent): void => signals.keyUp(event);
+  const onBlur = (): void => signals.clear();
+  const onVisibilityChange = (): void => {
+    if (document.hidden) signals.clear();
+  };
+  window.addEventListener("keydown", onKeyDown);
+  window.addEventListener("keyup", onKeyUp);
+  window.addEventListener("blur", onBlur);
+  document.addEventListener("visibilitychange", onVisibilityChange);
+  return () => {
+    window.removeEventListener("keydown", onKeyDown);
+    window.removeEventListener("keyup", onKeyUp);
+    window.removeEventListener("blur", onBlur);
+    document.removeEventListener("visibilitychange", onVisibilityChange);
+  };
+};
+
+const altHeldStore = createAltHeldStore(bindToWindow);
+
+/** Current value without subscribing. Safe to read inside event handlers. */
+export function getAltHeld(): boolean {
+  return altHeldStore.getSnapshot();
+}
+
+export function useAltHeld(): boolean {
+  return useSyncExternalStore(
+    altHeldStore.subscribe,
+    altHeldStore.getSnapshot,
+    () => false,
+  );
+}

package/app/src/confirm/useRequestConfirm.ts

@@ -0,0 +1,25 @@
+import { requestConfirm } from "./confirmSkip.js";
+import { getAltHeld } from "./useAltHeld.js";
+
+type ConfirmEvent = { altKey?: boolean } | null;
+
+function request(
+  open: () => void,
+  confirm: () => void,
+  event?: ConfirmEvent,
+): void {
+  requestConfirm(getAltHeld(), open, confirm, event);
+}
+
+const api = { request } as const;
+
+/**
+ * Confirm helper for menu owners. It must not subscribe to Alt: a re-render of
+ * the owner when Alt goes down remounts the open Radix menu and closes it.
+ * `ConfirmSkipHint` is the only subscriber and lives inside the open menu.
+ * The Alt state is read when the request happens. The returned object is
+ * stable and holds no React state, so it is safe to call anywhere.
+ */
+export function useRequestConfirm() {
+  return api;
+}

package/app/src/index.ts

@@ -0,0 +1,43 @@
+export {
+  bindToWindow,
+  createAltHeldStore,
+  getAltHeld,
+  useAltHeld,
+  type AltHeldBinding,
+  type AltHeldSignals,
+  type AltHeldStore,
+  type AltKeyEvent,
+} from "./confirm/useAltHeld.js";
+export { requestConfirm, shouldSkipConfirm } from "./confirm/confirmSkip.js";
+export { useRequestConfirm } from "./confirm/useRequestConfirm.js";
+export { ConfirmSkipHint, skipConfirmTitle } from "./confirm/ConfirmSkipHint.js";
+
+export {
+  fetchDeployFingerprint,
+  fingerprintFromHtml,
+} from "./update/deployFingerprint.js";
+export {
+  startUpdateAvailableWatcher,
+  type UpdateAvailableWatcherOptions,
+  type UpdateToastOptions,
+} from "./update/updateWatcher.js";
+
+export { SettingsSection } from "./settings/SettingsSection.js";
+export { SettingsField } from "./settings/SettingsField.js";
+export { SettingsStack } from "./settings/SettingsStack.js";
+export { SettingsToggleRow } from "./settings/SettingsToggleRow.js";
+export { SettingsEmptyState } from "./settings/SettingsEmptyState.js";
+export {
+  DefaultSettingsLayout,
+  SettingsPage,
+  type SettingsLayoutProps,
+  type SettingsPageProps,
+} from "./settings/SettingsPage.js";
+
+export {
+  createUseStableAuth,
+  resetStableAuthSession,
+  useStableAuth,
+  type ClerkAuthSlice,
+  type StableAuthOptions,
+} from "./auth/useStableAuth.js";

package/app/src/settings/SettingsEmptyState.tsx

@@ -0,0 +1,38 @@
+import type { ComponentType, ReactNode } from "react";
+
+interface SettingsEmptyStateProps {
+  /** Tabler icon component, rendered muted above the copy. */
+  icon: ComponentType<{ size?: number; className?: string }>;
+  title: string;
+  /** One line on what to do about it. */
+  description?: string;
+  /** Primary call to action, e.g. the same button as the section header. */
+  action?: ReactNode;
+}
+
+/**
+ * The "nothing here yet" state for a settings section body.
+ *
+ * Sits inside a SettingsSection rather than floating on the canvas, so an empty
+ * list still reads as part of the card it belongs to.
+ * Shared across apps.
+ */
+export function SettingsEmptyState({
+  icon: Icon,
+  title,
+  description,
+  action,
+}: SettingsEmptyStateProps) {
+  return (
+    <div className="flex flex-col items-center justify-center px-4 py-16 text-center">
+      <Icon size={28} className="mb-5 text-muted opacity-50" />
+      <h4 className="text-sm font-medium text-foreground">{title}</h4>
+      {description ? (
+        <p className="mt-2 max-w-sm text-xs leading-relaxed text-muted">
+          {description}
+        </p>
+      ) : null}
+      {action ? <div className="mt-6">{action}</div> : null}
+    </div>
+  );
+}

package/app/src/settings/SettingsField.tsx

@@ -0,0 +1,42 @@
+import type { ReactNode } from "react";
+
+interface SettingsFieldProps {
+  /** Field name, shown above the control. */
+  label: ReactNode;
+  /** Help text shown under the control. */
+  description?: ReactNode;
+  /** `id` of the control, so clicking the label focuses it. */
+  htmlFor?: string;
+  children: ReactNode;
+}
+
+/**
+ * One labelled control inside a SettingsSection body.
+ *
+ * Every settings form repeats the same label / control / help-text stack, so it
+ * lives here rather than being re-spaced per field. Stack several inside a
+ * section body with `grid gap-5`. Shared across apps.
+ */
+export function SettingsField({
+  label,
+  description,
+  htmlFor,
+  children,
+}: SettingsFieldProps) {
+  return (
+    <div>
+      <label
+        htmlFor={htmlFor}
+        className="mb-2 block text-sm font-medium text-foreground"
+      >
+        {label}
+      </label>
+      {children}
+      {description ? (
+        <p className="mt-1.5 text-pretty text-xs leading-relaxed text-muted">
+          {description}
+        </p>
+      ) : null}
+    </div>
+  );
+}

package/app/src/settings/SettingsPage.tsx

@@ -0,0 +1,88 @@
+import type { ReactNode } from "react";
+import { cn } from "../cn.js";
+import { SettingsStack } from "./SettingsStack.js";
+
+export type SettingsLayoutProps = {
+  title: string;
+  headerRight?: ReactNode;
+  toolbar?: ReactNode;
+  tabs?: ReactNode;
+  fillHeight?: boolean;
+  children: ReactNode;
+};
+
+export interface SettingsPageProps {
+  title: string;
+  /** Sparse primary action(s) in the title row (e.g. Add, Delete). */
+  headerRight?: ReactNode;
+  /** Filters / search / segmented controls. Sits under the title. */
+  toolbar?: ReactNode;
+  /** Route tabs. Sit under the title (and under toolbar if both exist). */
+  tabs?: ReactNode;
+  /**
+   * Wrap children in the standard settings section stack. Set false when the
+   * child already owns its own vertical rhythm.
+   */
+  stack?: boolean;
+  /** Fill the remaining shell height instead of scrolling the page. */
+  fillHeight?: boolean;
+  /**
+   * Page chrome supplied by the app (for example its own page container).
+   * Receives the stacked children. Defaults to a plain `div` layout.
+   */
+  layout?: (props: SettingsLayoutProps) => ReactNode;
+  children: ReactNode;
+}
+
+/** Plain fallback layout: heading, optional slots, then the body. */
+export function DefaultSettingsLayout({
+  title,
+  headerRight,
+  toolbar,
+  tabs,
+  fillHeight = false,
+  children,
+}: SettingsLayoutProps) {
+  return (
+    <div
+      className={cn(
+        "mx-auto flex w-full max-w-3xl flex-col gap-4 px-4 py-6",
+        fillHeight && "h-full min-h-0",
+      )}
+    >
+      <div className="flex items-center justify-between gap-4">
+        <h1 className="text-balance text-lg font-semibold text-foreground">
+          {title}
+        </h1>
+        {headerRight ? <div className="shrink-0">{headerRight}</div> : null}
+      </div>
+      {toolbar ? <div>{toolbar}</div> : null}
+      {tabs ? <div>{tabs}</div> : null}
+      <div className={cn(fillHeight ? "min-h-0 flex-1" : null)}>{children}</div>
+    </div>
+  );
+}
+
+/**
+ * Shared chrome for settings: title row, optional toolbar / tabs, then a
+ * consistent section stack. Apps pass `layout` to wrap their own page
+ * container; this package does not import one.
+ */
+export function SettingsPage({
+  title,
+  headerRight,
+  toolbar,
+  tabs,
+  stack = true,
+  fillHeight = false,
+  layout,
+  children,
+}: SettingsPageProps) {
+  const body = stack ? <SettingsStack>{children}</SettingsStack> : children;
+  const render = layout ?? DefaultSettingsLayout;
+  return (
+    <>
+      {render({ title, headerRight, toolbar, tabs, fillHeight, children: body })}
+    </>
+  );
+}

package/app/src/settings/SettingsSection.tsx

@@ -0,0 +1,92 @@
+import type { ReactNode } from "react";
+
+import { cn } from "../cn.js";
+
+type SettingsSectionBodyVariant = "form" | "list" | "compact";
+
+const BODY_VARIANT_CLASS: Record<SettingsSectionBodyVariant, string> = {
+  form: "px-4 py-5",
+  list: "divide-y divide-separator/50 p-0",
+  compact: "px-4 py-3",
+};
+
+interface SettingsSectionProps {
+  /** Section heading. Kept short — the description carries the detail. */
+  title: ReactNode;
+  /** Supporting copy shown under the heading. */
+  description?: ReactNode;
+  /** Control pinned to the top-right of the heading, e.g. a switch or link. */
+  action?: ReactNode;
+  /** Controls pinned to a bottom bar, e.g. a Save button. */
+  footer?: ReactNode;
+  children?: ReactNode;
+  /**
+   * Body padding contract. Prefer this over freelancing `bodyClassName` padding.
+   * - form: default labelled fields
+   * - list: edge-to-edge divided rows (`p-0`)
+   * - compact: tighter padding for dense controls
+   */
+  bodyVariant?: SettingsSectionBodyVariant;
+  /** Applied to the body wrapper, for one-off layout (grids, etc.). */
+  bodyClassName?: string;
+  className?: string;
+}
+
+/**
+ * The single container for a block of settings.
+ *
+ * Title and description sit on the canvas above the card so they read as a
+ * section caption. The card is only the controls (and optional footer).
+ * Shared across apps.
+ */
+export function SettingsSection({
+  title,
+  description,
+  action,
+  footer,
+  children,
+  bodyVariant = "form",
+  bodyClassName,
+  className,
+}: SettingsSectionProps) {
+  const hasBody = children != null;
+  const hasCard = hasBody || footer != null;
+
+  return (
+    <section className={cn("flex flex-col gap-2", className)}>
+      <header className="flex items-start justify-between gap-4 px-4">
+        <div className="min-w-0">
+          <h3 className="text-balance text-sm font-semibold text-foreground">
+            {title}
+          </h3>
+          {description ? (
+            <p className="mt-0.5 text-pretty text-sm leading-relaxed text-muted">
+              {description}
+            </p>
+          ) : null}
+        </div>
+        {action ? <div className="shrink-0">{action}</div> : null}
+      </header>
+
+      {hasCard ? (
+        <div
+          className={cn(
+            "rounded-lg bg-surface-card [&_input]:bg-field-background [&_textarea]:bg-field-background [&_[data-slot=select-trigger]]:bg-field-background [&_[role=combobox]]:border-border [&_[role=combobox]]:bg-field-background",
+            bodyVariant === "list" && "overflow-hidden",
+          )}
+        >
+          {hasBody ? (
+            <div className={cn(BODY_VARIANT_CLASS[bodyVariant], bodyClassName)}>
+              {children}
+            </div>
+          ) : null}
+          {footer ? (
+            <div className="flex items-center justify-end gap-2 rounded-b-lg bg-surface-secondary px-4 py-3">
+              {footer}
+            </div>
+          ) : null}
+        </div>
+      ) : null}
+    </section>
+  );
+}

package/app/src/settings/SettingsStack.tsx

@@ -0,0 +1,17 @@
+import type { ReactNode } from "react";
+
+import { cn } from "../cn.js";
+
+/**
+ * Vertical rhythm for every settings page body — one gap, no page-local freelancing.
+ * Shared across apps.
+ */
+export function SettingsStack({
+  children,
+  className,
+}: {
+  children: ReactNode;
+  className?: string;
+}) {
+  return <div className={cn("space-y-8", className)}>{children}</div>;
+}