@vvedantb/ui 0.9.0 → 0.10.1

package/README.md

@@ -943,6 +943,6 @@ The compat file includes a fallback `glass-panel-strong` (`rgb(var(--card) / 0.9
 
 A fixture that renders the main components against sample light and dark RGB variables is in `tokens/examples/compat-shadcn-rgb/`.
 
-`@clerk/clerk-react`, `@tanstack/react-hotkeys`, `motion` and `zod` are optional peers (`peerDependenciesMeta`). Install `@clerk/clerk-react` only to use `useStableAuth`, `@tanstack/react-hotkeys` and `zod` only for the features that use them, and `motion` only to use the motion presets, `InputArea`, the 0.3 `Composer` or the AI elements and primitives that animate.
+`@clerk/clerk-react`, `convex`, `@tanstack/react-hotkeys`, `motion` and `zod` are optional peers (`peerDependenciesMeta`), so the package manager does not install or warn about them. The root still imports each of them statically from some module (`useStableAuth` and `ConvexClerkProvider` import Clerk; `ConvexClerkProvider` and `useEnsureUser` import `convex/react`; the motion presets, `ConfirmSkipHint` and others import the rest). So an app that imports `@vvedantb/ui` must have all five resolvable, even if it uses none of those exports: a bundler resolves every import before it tree-shakes. `app/tests-node/convex-esm.test.mjs` pins which root modules import `convex` and Clerk.
 
 Full documentation: the repository `README.md`. Upgrading from `@vvedantb/tokens`, `@vvedantb/shell` or `@vvedantb/app-kit`: `MIGRATION.md`.

package/app/README.md

@@ -10,7 +10,7 @@ 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`.
+Required: `react` and `react-dom` (>=19). Optional peers of `@vvedantb/ui` used by the app helpers: `@clerk/clerk-react` (`useStableAuth`, `ConvexClerkProvider`), `convex` (`ConvexClerkProvider`, `useEnsureUser`), `@tanstack/react-hotkeys` and `zod` (your `z` for `parseClientEnv`). The root imports Clerk and `convex/react` statically, so they must be installed even if you do not use these helpers; see the package README.
 
 `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).
 
@@ -191,3 +191,69 @@ Pure TypeScript, no dependencies. Options:
 - `calendar`: `false` (default) counts elapsed time: a day is 24 hours, a month 30 days, a year 12 such months. `true` counts as `dayjs().diff(date, unit)` does: days by the local calendar across DST changes, and calendar months and years.
 
 Strings are parsed with `new Date(string)`. dayjs parses a date-only string such as `"2026-03-01"` as local midnight, `new Date` as UTC midnight; numbers, `Date` objects and ISO strings with a time give the same result either way. An invalid date gives `"NaNy"` (`"0mo"` with `calendar`).
+
+## Convex provider, VITE env and ensure-user (0.10.0)
+
+React and VITE env helpers for Convex apps. The non-React Convex helpers (`mapLoadedQuery`, `forEachLoadedQuery`, `updateAllCachedQueries`, `patchLoadedQuery`, `OptimisticStore`, `tempId`, `createMemoryOptimisticStore`) live in `@vvedantb/server`, so backend packages, tests and React Native can use them without loading this package.
+
+### `ConvexClerkProvider`
+
+```tsx
+import { ConvexClerkProvider, useStableAuth } from "@vvedantb/ui";
+import { ConvexReactClient } from "convex/react";
+
+const convex = new ConvexReactClient(env.VITE_CONVEX_URL);
+
+<ClerkProvider publishableKey={env.VITE_CLERK_PUBLISHABLE_KEY}>
+  <ConvexClerkProvider client={convex} useAuth={useStableAuth}>
+    <App />
+  </ConvexClerkProvider>
+</ClerkProvider>;
+```
+
+| Props | Renders |
+| --- | --- |
+| `client` is `null` or `undefined` | `children` alone (no provider). |
+| `clerk={false}` | `<ConvexProvider client={client}>`. |
+| otherwise | `<ConvexProviderWithClerk client={client} useAuth={useAuth}>`; `useAuth` defaults to `@clerk/clerk-react`'s. |
+
+`clerk` defaults to `true`. Render it inside `ClerkProvider` unless `clerk` is `false`. Types: `ConvexClerkProviderProps`, `ConvexClerkUseAuth`.
+
+### `parseClientEnv`
+
+```ts
+import { z } from "zod";
+import { parseClientEnv } from "@vvedantb/ui";
+
+export const clientEnv = parseClientEnv(import.meta.env, { z, viteEnv: "fallback" });
+// { VITE_CONVEX_URL: string; VITE_CLERK_PUBLISHABLE_KEY: string; VITE_ENV: "development" | "staging" | "production" }
+
+export const extensionEnv = parseClientEnv(import.meta.env, {
+  z,
+  viteEnv: false,
+  extend: { VITE_CLERK_SYNC_HOST: z.string().url() },
+});
+```
+
+The schema is `z.object({ VITE_CONVEX_URL: z.string().min(1), VITE_CLERK_PUBLISHABLE_KEY: z.string().min(1), VITE_ENV: z.enum(["development", "staging", "production"]), ...extend })`, built with your `z` (zod 3.25+ or 4; the package never imports zod at runtime). Only the schema's keys are read from `rawEnv`. Failure throws the `ZodError` from `.parse`.
+
+| `viteEnv` | `VITE_ENV` |
+| --- | --- |
+| `"strict"` (default) | Must be one of `VITE_ENV_NAMES`. |
+| `"fallback"` | Any other value, or none, becomes `"development"` before parsing. |
+| `false` | Not in the schema or the result. |
+
+Types: `ClientEnv`, `ClientEnvWithoutViteEnv`, `ClientEnvOptions`, `ClientEnvSource`, `ViteEnvMode`, `ViteEnvName`.
+
+### `useEnsureUser`
+
+```tsx
+function EnsureUser() {
+  useEnsureUser(api.users.ensureUserExists);
+  return null;
+}
+```
+
+Calls `mutation({})` every time `useConvexAuth().isAuthenticated` becomes `true` (once on mount if already signed in), and logs a rejection with `console.error`. Needs a Convex auth provider above it (`ConvexClerkProvider` with Clerk on). Pair it with `ensureUser` from `@vvedantb/server`. Type: `EnsureUserMutation`.
+
+Tests: `app/tests/convex/` ports each app's copy and runs it beside the helper (env with zod 4 and zod 3.25; provider variants; ensure-user calls over auth sequences). `app/tests-node/convex-esm.test.mjs` loads the helpers in plain Node.

package/app/src/convex/ConvexClerkProvider.tsx

@@ -0,0 +1,37 @@
+import { useAuth as useClerkAuth } from "@clerk/clerk-react";
+import { ConvexProvider, type ConvexReactClient } from "convex/react";
+import { ConvexProviderWithClerk } from "convex/react-clerk";
+import type { ComponentProps, ReactNode } from "react";
+
+/** The `useAuth` hook `ConvexProviderWithClerk` takes (Clerk's, or a wrapper such as `useStableAuth`). */
+export type ConvexClerkUseAuth = ComponentProps<typeof ConvexProviderWithClerk>["useAuth"];
+
+export type ConvexClerkProviderProps = {
+  /** No client (for example no Convex URL configured): children render without a provider. */
+  client: ConvexReactClient | null | undefined;
+  /** Default: `useAuth` from `@clerk/clerk-react`. */
+  useAuth?: ConvexClerkUseAuth;
+  /** `false` renders a plain `ConvexProvider` (no Clerk auth). Default `true`. */
+  clerk?: boolean;
+  children: ReactNode;
+};
+
+/**
+ * The Convex provider for a Clerk app: `ConvexProviderWithClerk`, a plain
+ * `ConvexProvider` when `clerk` is `false`, or just the children when there is
+ * no client. Render it inside `ClerkProvider` unless `clerk` is `false`.
+ */
+export function ConvexClerkProvider({
+  client,
+  useAuth = useClerkAuth,
+  clerk = true,
+  children,
+}: ConvexClerkProviderProps) {
+  if (!client) return children;
+  if (!clerk) return <ConvexProvider client={client}>{children}</ConvexProvider>;
+  return (
+    <ConvexProviderWithClerk client={client} useAuth={useAuth}>
+      {children}
+    </ConvexProviderWithClerk>
+  );
+}

package/app/src/convex/env.ts

@@ -0,0 +1,76 @@
+// Type-only: the app passes its own `z`, so zod stays an optional peer and the
+// thrown ZodError comes from the app's zod version (3.25+ or 4), as today.
+import type { z } from "zod";
+
+export type ViteEnvName = "development" | "staging" | "production";
+
+export const VITE_ENV_NAMES: readonly ["development", "staging", "production"] = ["development", "staging", "production"];
+
+/** `import.meta.env`, or any record of raw env values. */
+export type ClientEnvSource = Readonly<Record<string, string | boolean | undefined>>;
+
+type BaseShape = {
+  VITE_CONVEX_URL: z.ZodType<string>;
+  VITE_CLERK_PUBLISHABLE_KEY: z.ZodType<string>;
+};
+
+type ViteEnvShape = BaseShape & { VITE_ENV: z.ZodType<ViteEnvName> };
+
+/**
+ * - `"strict"` (default): `VITE_ENV` must be one of `VITE_ENV_NAMES`.
+ * - `"fallback"`: any other value (or none) is read as `"development"`.
+ * - `false`: no `VITE_ENV` key.
+ */
+export type ViteEnvMode = "strict" | "fallback" | false;
+
+export type ClientEnvOptions<Extra extends z.ZodRawShape> = {
+  /** The app's `z` from `"zod"`. */
+  z: typeof z;
+  viteEnv?: ViteEnvMode;
+  /** Extra keys, parsed after the base keys in the same `z.object`. A key here replaces a base key. */
+  extend?: Extra;
+};
+
+/** Parsed env with `VITE_ENV`. */
+export type ClientEnv<Extra extends z.ZodRawShape = Record<never, never>> = z.output<z.ZodObject<ViteEnvShape & Extra>>;
+
+/** Parsed env without `VITE_ENV` (`viteEnv: false`). */
+export type ClientEnvWithoutViteEnv<Extra extends z.ZodRawShape = Record<never, never>> = z.output<
+  z.ZodObject<BaseShape & Extra>
+>;
+
+/**
+ * Parse VITE env with zod: `VITE_CONVEX_URL` and `VITE_CLERK_PUBLISHABLE_KEY`
+ * are `z.string().min(1)`, `VITE_ENV` is `z.enum(VITE_ENV_NAMES)`, then any
+ * `extend` keys. Only those keys are read from `rawEnv`. Throws the ZodError
+ * from `z.object(shape).parse`.
+ */
+export function parseClientEnv<Extra extends z.ZodRawShape = Record<never, never>>(
+  rawEnv: ClientEnvSource,
+  options: ClientEnvOptions<Extra> & { viteEnv: false },
+): ClientEnvWithoutViteEnv<Extra>;
+export function parseClientEnv<Extra extends z.ZodRawShape = Record<never, never>>(
+  rawEnv: ClientEnvSource,
+  options: ClientEnvOptions<Extra> & { viteEnv?: "strict" | "fallback" },
+): ClientEnv<Extra>;
+export function parseClientEnv(
+  rawEnv: ClientEnvSource,
+  options: ClientEnvOptions<z.ZodRawShape>,
+): z.output<z.ZodObject<z.ZodRawShape>> {
+  const zod = options.z;
+  const viteEnv = options.viteEnv ?? "strict";
+  const shape: z.ZodRawShape = {
+    VITE_CONVEX_URL: zod.string().min(1),
+    VITE_CLERK_PUBLISHABLE_KEY: zod.string().min(1),
+    ...(viteEnv === false ? {} : { VITE_ENV: zod.enum(VITE_ENV_NAMES) }),
+    ...options.extend,
+  };
+  const input: Record<string, string | boolean | undefined> = {};
+  for (const key of Object.keys(shape)) input[key] = rawEnv[key];
+  if (viteEnv === "fallback") input.VITE_ENV = viteEnvOrDevelopment(rawEnv.VITE_ENV);
+  return zod.object(shape).parse(input);
+}
+
+function viteEnvOrDevelopment(value: string | boolean | undefined): ViteEnvName {
+  return value === "production" || value === "staging" || value === "development" ? value : "development";
+}

package/app/src/convex/useEnsureUser.ts

@@ -0,0 +1,24 @@
+import { useConvexAuth, useMutation } from "convex/react";
+import type { FunctionReference } from "convex/server";
+import { useEffect } from "react";
+
+/** A public mutation that takes no args, such as `api.users.ensureUserExists`. */
+export type EnsureUserMutation = FunctionReference<"mutation", "public", Record<string, never>>;
+
+/**
+ * Call `mutation({})` each time Convex auth becomes authenticated, logging a
+ * failure with `console.error`. Needs a Convex auth provider above it
+ * (`ConvexClerkProvider` with Clerk on). Kept as an effect: it syncs the
+ * server's users row with the sign-in state, and there is no render-time
+ * alternative.
+ */
+export function useEnsureUser(mutation: EnsureUserMutation): void {
+  const { isAuthenticated } = useConvexAuth();
+  const ensureUser = useMutation(mutation);
+
+  useEffect(() => {
+    if (isAuthenticated) {
+      ensureUser({}).catch(console.error);
+    }
+  }, [isAuthenticated, ensureUser]);
+}

package/app/src/index.ts

@@ -72,3 +72,20 @@ export {
   formatCompactRelativeTime,
   type CompactRelativeTimeOptions,
 } from "./time/compactRelativeTime.js";
+
+export {
+  ConvexClerkProvider,
+  type ConvexClerkProviderProps,
+  type ConvexClerkUseAuth,
+} from "./convex/ConvexClerkProvider.js";
+export {
+  parseClientEnv,
+  VITE_ENV_NAMES,
+  type ClientEnv,
+  type ClientEnvOptions,
+  type ClientEnvSource,
+  type ClientEnvWithoutViteEnv,
+  type ViteEnvMode,
+  type ViteEnvName,
+} from "./convex/env.js";
+export { useEnsureUser, type EnsureUserMutation } from "./convex/useEnsureUser.js";

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@vvedantb/ui",
-  "version": "0.9.0",
+  "version": "0.10.1",
   "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.",
+  "description": "Shared React 19 UI for web apps: one JavaScript entry (primitives, shell pieces, app helpers including the Convex and Clerk provider, VITE env parsing and ensure-user, native tokens), design-token CSS, shared Tailwind v4 CSS and a Tailwind preset.",
   "type": "module",
   "publishConfig": {
     "access": "public"
@@ -94,6 +94,7 @@
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "cmdk": "^1.1.1",
+    "convex": "^1.24.0",
     "embla-carousel-react": "^8.6.0",
     "motion": ">=12.0.0",
     "nanoid": "^5.1.0",
@@ -142,6 +143,7 @@
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "cmdk": "^1.1.1",
+    "convex": "^1.47.0",
     "dayjs": "1.11.19",
     "embla-carousel-react": "^8.6.0",
     "happy-dom": "^18.0.0",
@@ -160,12 +162,16 @@
     "use-stick-to-bottom": "^1.1.0",
     "vaul": "^1.1.0",
     "vitest": "^3.2.0",
-    "zod": "^4.0.0"
+    "zod": "^4.0.0",
+    "zod3": "npm:zod@^3.25.76"
   },
   "peerDependenciesMeta": {
     "@clerk/clerk-react": {
       "optional": true
     },
+    "convex": {
+      "optional": true
+    },
     "@tanstack/react-hotkeys": {
       "optional": true
     },

package/src/index.ts

@@ -222,7 +222,7 @@ export type { SiteFooterLink, SiteFooterProps, SiteFooterSocial } from "./market
 export { PricingModal } from "./marketing/PricingModal";
 export type { PricingModalProps } from "./marketing/PricingModal";
 
-// App helpers: confirm skip, update watcher, settings chrome, stable auth.
+// App helpers: confirm skip, update watcher, settings chrome, stable auth, Convex provider, VITE env and ensure-user.
 export * from "../app/src/index";
 
 // Native tokens (JS values that match tokens.css).