@entropy-softworks/ui 2026.7.31

package/src/components/tooltip.tsx

@@ -0,0 +1,30 @@
+import React from "react";
+import * as TooltipPrimitive from "@rn-primitives/tooltip";
+import { cn } from "../utils/cn";
+import { Text } from "./text";
+
+const Tooltip = TooltipPrimitive.Root;
+const TooltipTrigger = TooltipPrimitive.Trigger;
+
+const TooltipContent = React.forwardRef<
+  React.ElementRef<typeof TooltipPrimitive.Content>,
+  React.ComponentPropsWithoutRef<typeof TooltipPrimitive.Content> & { className?: string }
+>(({ className, sideOffset = 6, children, ...props }, ref) => (
+  <TooltipPrimitive.Portal>
+    <TooltipPrimitive.Content
+      ref={ref}
+      sideOffset={sideOffset}
+      className={cn("z-50 rounded-md px-3 py-1.5", "bg-foreground dark:bg-white", className)}
+      {...props}
+    >
+      {typeof children === "string" ? (
+        <Text className="text-xs text-background dark:text-black">{children}</Text>
+      ) : (
+        children
+      )}
+    </TooltipPrimitive.Content>
+  </TooltipPrimitive.Portal>
+));
+TooltipContent.displayName = "TooltipContent";
+
+export { Tooltip, TooltipTrigger, TooltipContent };

package/src/components/totp-display.tsx

@@ -0,0 +1,207 @@
+import React, { useEffect, useState } from "react";
+import { Pressable, View } from "react-native";
+import { Ionicons } from "@expo/vector-icons";
+import { useColorScheme } from "nativewind";
+import { MutedText, Text } from "./text";
+import { copyToClipboard } from "../utils/clipboard";
+
+export interface TotpDisplayProps {
+  /** Base32-encoded TOTP secret. Empty string disables the display. */
+  secret: string;
+  /**
+   * Pure function that computes the current TOTP code from `secret`.
+   * Apps inject their own implementation so this widget stays decoupled
+   * from the crypto module — e.g. vault wires
+   * `@vault/shared/crypto/totp.computeTotpCode`.
+   */
+  computeCode: (secret: string) => string;
+  /** TOTP step period in seconds. Defaults to 30. */
+  period?: number;
+  /** Optional callback fired after a successful clipboard write. */
+  onCopy?: (code: string) => void;
+}
+
+const PLACEHOLDER = "------";
+
+/**
+ * TOTP code display with a circular countdown ring. Recomputes the code
+ * on each 30s window boundary; ticks the remaining-seconds value once
+ * per second to drive the ring animation.
+ */
+export function TotpDisplay({
+  secret,
+  computeCode,
+  period = 30,
+  onCopy,
+}: TotpDisplayProps): React.JSX.Element | null {
+  const { colorScheme } = useColorScheme();
+  const isDark = colorScheme === "dark";
+
+  const safeCompute = (s: string): string => {
+    if (!s) {
+      return PLACEHOLDER;
+    }
+    try {
+      return computeCode(s);
+    } catch {
+      return PLACEHOLDER;
+    }
+  };
+
+  const [code, setCode] = useState<string>(() => safeCompute(secret));
+  const [remaining, setRemaining] = useState<number>(() => {
+    const now = Math.floor(Date.now() / 1000);
+    return period - (now % period);
+  });
+
+  useEffect(() => {
+    if (!secret) {
+      return;
+    }
+    let lastWindow = -1;
+    const tick = () => {
+      const now = Math.floor(Date.now() / 1000);
+      const window = Math.floor(now / period);
+      setRemaining(period - (now % period));
+      if (window !== lastWindow) {
+        lastWindow = window;
+        setCode(safeCompute(secret));
+      }
+    };
+    tick();
+    const id = setInterval(tick, 1000);
+    return () => clearInterval(id);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [secret, period]);
+
+  if (!secret) {
+    return null;
+  }
+
+  const copy = async (): Promise<void> => {
+    if (!code || code === PLACEHOLDER) {
+      return;
+    }
+    // Route through the shared helper so the 30s auto-clear applies.
+    // TOTP codes rotate every 30s anyway, but the clipboard residue
+    // still leaks the code to whatever the user pastes next (or to
+    // a shoulder-surfer hitting paste).
+    const ok = await copyToClipboard(code);
+    if (ok) {
+      onCopy?.(code);
+    }
+  };
+
+  const urgent = remaining <= 5;
+  const foreground = isDark ? "rgb(255, 255, 255)" : "rgb(0, 0, 0)";
+  const destructive = "rgb(239, 68, 68)";
+  const border = isDark ? "rgb(38, 38, 38)" : "rgb(229, 229, 229)";
+  const card = isDark ? "rgb(0, 0, 0)" : "rgb(255, 255, 255)";
+  const secondary = isDark ? "rgb(38, 38, 38)" : "rgb(245, 245, 245)";
+  const accent = urgent ? destructive : foreground;
+
+  return (
+    <Pressable
+      onPress={copy}
+      accessibilityRole="button"
+      accessibilityLabel="Copy TOTP code"
+      accessibilityHint="Copies the current one-time code to the clipboard"
+      style={({ pressed }) => ({
+        flexDirection: "row",
+        alignItems: "center",
+        gap: 12,
+        padding: 12,
+        borderRadius: 8,
+        borderWidth: 1,
+        borderColor: border,
+        backgroundColor: pressed ? secondary : card,
+      })}
+    >
+      <CountdownRing remaining={remaining} total={period} color={accent} backgroundColor={border} />
+      <View style={{ flex: 1 }}>
+        <MutedText className="text-xs" style={{ marginBottom: 2 }}>
+          TOTP code
+        </MutedText>
+        <Text
+          style={{
+            color: accent,
+            fontSize: 22,
+            fontWeight: "600",
+            letterSpacing: 4,
+            fontFamily: "ui-monospace, SFMono-Regular, Menlo, monospace",
+          }}
+        >
+          {`${code.slice(0, 3)} ${code.slice(3)}`}
+        </Text>
+      </View>
+      <Ionicons
+        name="copy-outline"
+        size={16}
+        color={isDark ? "rgb(163, 163, 163)" : "rgb(115, 115, 115)"}
+      />
+    </Pressable>
+  );
+}
+
+interface RingProps {
+  remaining: number;
+  total: number;
+  color: string;
+  backgroundColor: string;
+}
+
+function CountdownRing({ remaining, total, color, backgroundColor }: RingProps): React.JSX.Element {
+  const size = 36;
+  const stroke = 3;
+  const radius = (size - stroke) / 2;
+  const circumference = 2 * Math.PI * radius;
+  const fraction = Math.max(0, Math.min(1, remaining / total));
+  const dashOffset = circumference * (1 - fraction);
+
+  // Cast raw SVG tags through React.createElement so RN-Web renders them
+  // as real <svg> / <circle> elements without depending on
+  // `react-native-svg`. Native targets fall back to the View at the
+  // outer level — apps that want native parity should overlay this with
+  // an SVG-backed implementation in their own component layer.
+  const Svg = "svg" as unknown as React.ComponentType<Record<string, unknown>>;
+  const Circle = "circle" as unknown as React.ComponentType<Record<string, unknown>>;
+
+  return (
+    <View style={{ width: size, height: size, alignItems: "center", justifyContent: "center" }}>
+      <Svg width={size} height={size} viewBox={`0 0 ${size} ${size}`}>
+        <Circle
+          cx={size / 2}
+          cy={size / 2}
+          r={radius}
+          fill="none"
+          stroke={backgroundColor}
+          strokeWidth={stroke}
+        />
+        <Circle
+          cx={size / 2}
+          cy={size / 2}
+          r={radius}
+          fill="none"
+          stroke={color}
+          strokeWidth={stroke}
+          strokeLinecap="round"
+          strokeDasharray={circumference}
+          strokeDashoffset={dashOffset}
+          transform={`rotate(-90 ${size / 2} ${size / 2})`}
+          style={{ transition: "stroke-dashoffset 1s linear" }}
+        />
+      </Svg>
+      <Text
+        style={{
+          position: "absolute",
+          color,
+          fontSize: 11,
+          fontWeight: "600",
+          fontFamily: "ui-monospace, SFMono-Regular, Menlo, monospace",
+        }}
+      >
+        {remaining}
+      </Text>
+    </View>
+  );
+}

package/src/components/user-avatar.tsx

@@ -0,0 +1,46 @@
+import React from "react";
+import { View } from "react-native";
+import { useColorScheme } from "nativewind";
+import { cn } from "../utils/cn";
+import { useAuth } from "../hooks/useAuth";
+import { Text } from "./text";
+
+export interface UserAvatarProps {
+  /** Square pixel size. Defaults to 36. */
+  size?: number;
+  /**
+   * Override for the initial letter. By default the avatar pulls the
+   * first character of `display_name`, falling back to `username`, then
+   * `email`, then `?`.
+   */
+  initial?: string;
+}
+
+/**
+ * Initial-letter circular avatar. Pulls the current user from
+ * `useAuth()` and renders a foreground-on-primary disc. Apps that want
+ * a static initial (e.g. an icon strip) pass `initial` explicitly.
+ */
+export const UserAvatar = React.memo(function UserAvatar({ size = 36, initial }: UserAvatarProps) {
+  const { user } = useAuth();
+  const { colorScheme } = useColorScheme();
+  const isDark = colorScheme === "dark";
+  const resolved =
+    initial ??
+    (user?.display_name || user?.username || user?.email || "?")[0]?.toUpperCase() ??
+    "?";
+
+  return (
+    <View
+      className={cn("items-center justify-center rounded-full", isDark ? "bg-white" : "bg-black")}
+      style={{ width: size, height: size }}
+    >
+      <Text
+        className="font-bold"
+        style={{ fontSize: size * 0.44, color: isDark ? "#000000" : "#FFFFFF" }}
+      >
+        {resolved}
+      </Text>
+    </View>
+  );
+});

package/src/context/AppConfigContext.tsx

@@ -0,0 +1,76 @@
+import React, { createContext, useContext, useMemo } from "react";
+import { type Href } from "expo-router";
+import { type ImageStyle, type StyleProp, type ViewStyle } from "react-native";
+
+/**
+ * Per-app route map consumed by the entropy-ui auth screens / hooks.
+ * Apps supply this so the shared screens can navigate without hard-coding
+ * vault- or bootstrap-specific paths.
+ */
+export interface AppRoutes {
+  welcome: Href;
+  login: Href;
+  register: Href;
+  forgotPassword: Href;
+  resetPassword: Href;
+  verifyEmail: Href;
+  mfaChallenge: Href;
+  mfaEnroll: Href;
+  termsOfService: Href;
+  privacyPolicy: Href;
+  serverConfig: Href;
+  importData: Href;
+  /** Where to land authenticated users with no pending onboarding step. */
+  home: Href;
+}
+
+export type LogoComponent = React.ComponentType<{
+  width?: number;
+  height?: number;
+  style?: StyleProp<ViewStyle> | StyleProp<ImageStyle>;
+}>;
+
+export interface AppConfig {
+  /** User-facing brand name. Renders in headings, toasts, MFA issuer, etc. */
+  appName: string;
+  /** Brand logo as a React component (SVG / Image). */
+  Logo: LogoComponent;
+  /** Per-app route map. */
+  routes: AppRoutes;
+  /**
+   * Tagline rendered under the brand on the welcome screen. Defaults to
+   * a generic "An Entropy Softworks platform".
+   */
+  tagline?: string;
+  /**
+   * Optional terms-of-service markdown / plain text. Welcome screen and
+   * the dedicated terms screen render this. When omitted, the screens
+   * render a generic stub.
+   */
+  termsText?: string;
+  /** Optional privacy-policy markdown / plain text. */
+  privacyText?: string;
+}
+
+const AppConfigContext = createContext<AppConfig | null>(null);
+
+export function AppConfigProvider({
+  config,
+  children,
+}: {
+  config: AppConfig;
+  children: React.ReactNode;
+}) {
+  const value = useMemo(() => config, [config]);
+  return <AppConfigContext.Provider value={value}>{children}</AppConfigContext.Provider>;
+}
+
+export function useAppConfig(): AppConfig {
+  const ctx = useContext(AppConfigContext);
+  if (!ctx) {
+    throw new Error(
+      "entropy-ui: useAppConfig must be used inside <AppConfigProvider config={...}>."
+    );
+  }
+  return ctx;
+}

package/src/context/NavigationContext.tsx

@@ -0,0 +1,75 @@
+/**
+ * Pluggable navigation surface used by entropy-ui's auth screens.
+ *
+ * The shared screens used to call `useRouter()` from `expo-router`
+ * directly, which made them un-usable in non-Expo bundles (the browser-
+ * extension popup, future Electron / web targets without the Expo
+ * router runtime). Routing through this context lets every consumer
+ * supply its own router implementation — expo-router on mobile / web,
+ * a stack-reducer adapter inside the extension popup, etc.
+ *
+ * When no consumer is wrapped in `<NavigationProvider>`, `useNavigation`
+ * falls back to `expo-router`'s `useRouter()`, so the existing mobile
+ * client keeps working unchanged.
+ */
+
+import React, { createContext, useContext, useMemo } from "react";
+import { type Href, useRouter } from "expo-router";
+
+export interface RouteTarget {
+  pathname: Href | string;
+  params?: Record<string, unknown>;
+}
+
+export interface AppRouter {
+  push(target: Href | string | RouteTarget): void;
+  replace(target: Href | string | RouteTarget): void;
+  back(): void;
+}
+
+const NavigationContext = createContext<AppRouter | null>(null);
+
+export interface NavigationProviderProps {
+  router: AppRouter;
+  children: React.ReactNode;
+}
+
+/**
+ * Override the default expo-router-backed navigation for everything
+ * rendered below this provider. Apps without expo-router supply this
+ * with their own stack-reducer adapter; everyone else can ignore it.
+ */
+export function NavigationProvider({ router, children }: NavigationProviderProps) {
+  const value = useMemo(() => router, [router]);
+  return <NavigationContext.Provider value={value}>{children}</NavigationContext.Provider>;
+}
+
+/**
+ * Hook used by entropy-ui screens to navigate. Returns the override
+ * router supplied by `NavigationProvider` when present; otherwise
+ * delegates to `expo-router`'s `useRouter()`.
+ */
+export function useNavigation(): AppRouter {
+  const override = useContext(NavigationContext);
+  const expoRouter = useRouter();
+  // Memoize the expo-router adapter so consumers using the returned
+  // value as a `useEffect`/`useCallback` dep don't see a fresh
+  // reference every render. `useRouter()` itself returns a stable
+  // object across renders, so an empty-dep memo would also work, but
+  // depending on `expoRouter` is defensive against future changes.
+  const expoAdapter = useMemo<AppRouter>(
+    () => ({
+      push(target) {
+        expoRouter.push(target as Href);
+      },
+      replace(target) {
+        expoRouter.replace(target as Href);
+      },
+      back() {
+        expoRouter.back();
+      },
+    }),
+    [expoRouter]
+  );
+  return override ?? expoAdapter;
+}

package/src/context/NotificationContext.tsx

@@ -0,0 +1,69 @@
+/**
+ * Notification context — provides a `push()` helper that surfaces
+ * toast-style notifications via `react-native-toast-message`.
+ *
+ * Mount `<NotificationProvider>` somewhere above the components that
+ * consume `useNotificationContext()`. The `<Toast />` component itself
+ * must be rendered separately in the app root (see
+ * `react-native-toast-message` docs).
+ *
+ * The vault notification provider also bridged a WebSocket service into
+ * this context to dispatch server-pushed toasts; that piece is
+ * app-specific and not included here. Consumers that need it can build
+ * a thin wrapper around this provider.
+ */
+
+import React, { createContext, useCallback, useContext, useMemo } from "react";
+import Toast from "react-native-toast-message";
+
+export type NotificationLevel = "success" | "error" | "warning" | "info";
+
+export interface ToastOptions {
+  level: NotificationLevel;
+  title: string;
+  message?: string;
+  /** Milliseconds before auto-dismiss. Defaults to 4000. */
+  ttl_ms?: number;
+}
+
+interface NotificationContextValue {
+  push: (options: ToastOptions) => void;
+}
+
+const NotificationContext = createContext<NotificationContextValue | null>(null);
+
+const LEVEL_TO_TOAST_TYPE: Record<NotificationLevel, "success" | "error" | "info"> = {
+  success: "success",
+  error: "error",
+  // react-native-toast-message only ships success/error/info — warnings
+  // map onto error so they show with the warning-coloured icon.
+  warning: "error",
+  info: "info",
+};
+
+export function NotificationProvider({ children }: { children: React.ReactNode }) {
+  const push = useCallback((options: ToastOptions) => {
+    Toast.show({
+      type: LEVEL_TO_TOAST_TYPE[options.level],
+      text1: options.title,
+      text2: options.message,
+      visibilityTime: options.ttl_ms ?? 4000,
+    });
+  }, []);
+
+  // Memoize the context value so an inline-object identity churn
+  // doesn't re-render every consumer on each NotificationProvider
+  // render. `push` is already `useCallback`-stable, so the memo
+  // effectively pins the value across the provider's lifetime.
+  const value = useMemo(() => ({ push }), [push]);
+
+  return <NotificationContext.Provider value={value}>{children}</NotificationContext.Provider>;
+}
+
+export function useNotificationContext(): NotificationContextValue {
+  const ctx = useContext(NotificationContext);
+  if (!ctx) {
+    throw new Error("useNotificationContext must be used inside <NotificationProvider>");
+  }
+  return ctx;
+}

package/src/context/ThemeContext.tsx

@@ -0,0 +1,83 @@
+import React, { createContext, useContext, useEffect, useState, useMemo, useCallback } from "react";
+import { colorScheme } from "nativewind";
+import AsyncStorage from "@react-native-async-storage/async-storage";
+import { getStoragePrefix } from "../services/api-config";
+
+export type ThemePreference = "light" | "dark" | "system";
+
+function themeKey(): string {
+  return `@${getStoragePrefix()}/theme-preference`;
+}
+
+function applyTheme(isDark: boolean) {
+  colorScheme.set(isDark ? "dark" : "light");
+  if (typeof document !== "undefined") {
+    if (isDark) {
+      document.documentElement.classList.add("dark");
+    } else {
+      document.documentElement.classList.remove("dark");
+    }
+  }
+}
+
+interface ThemeContextValue {
+  preference: ThemePreference;
+  setPreference: (pref: ThemePreference) => void;
+}
+
+const ThemeContext = createContext<ThemeContextValue>({
+  preference: "system",
+  setPreference: () => {},
+});
+
+export function ThemeProvider({ children }: { children: React.ReactNode }) {
+  const [preference, setPreferenceState] = useState<ThemePreference>("system");
+
+  useEffect(() => {
+    AsyncStorage.getItem(themeKey())
+      .then((stored) => {
+        if (stored === "light" || stored === "dark" || stored === "system") {
+          setPreferenceState(stored);
+        }
+      })
+      .catch(() => {});
+  }, []);
+
+  const setPreference = useCallback((pref: ThemePreference) => {
+    AsyncStorage.setItem(themeKey(), pref).catch(() => {});
+    setPreferenceState(pref);
+  }, []);
+
+  useEffect(() => {
+    if (preference !== "system") {
+      applyTheme(preference === "dark");
+      return;
+    }
+
+    if (typeof window !== "undefined" && typeof window.matchMedia === "function") {
+      // Web system mode: react-native-css-interop's internal Appearance
+      // listener uses the removed `MediaQueryList.addListener` API
+      // (Chrome 121+) so it never fires. Drive it ourselves via
+      // `addEventListener` instead.
+      const mq = window.matchMedia("(prefers-color-scheme: dark)");
+      applyTheme(mq.matches);
+      const handler = (e: MediaQueryListEvent) => applyTheme(e.matches);
+      mq.addEventListener("change", handler);
+      return () => mq.removeEventListener("change", handler);
+    }
+
+    // Native system mode: react-native-css-interop's Appearance listener
+    // already tracks OS changes. Calling colorScheme.set("system") would
+    // pass null to the Android native module which rejects non-nullable
+    // parameters and crashes — leave it alone.
+    return undefined;
+  }, [preference]);
+
+  const contextValue = useMemo(() => ({ preference, setPreference }), [preference, setPreference]);
+
+  return <ThemeContext.Provider value={contextValue}>{children}</ThemeContext.Provider>;
+}
+
+export function useTheme() {
+  return useContext(ThemeContext);
+}

package/src/context/__tests__/NavigationContext.test.tsx

@@ -0,0 +1,53 @@
+import React from "react";
+import { renderHook } from "@testing-library/react-native";
+
+import { NavigationProvider, useNavigation, type AppRouter } from "../NavigationContext";
+import * as expoRouterModule from "expo-router";
+
+jest.mock("expo-router", () => {
+  const mockRouter = { push: jest.fn(), replace: jest.fn(), back: jest.fn() };
+  return {
+    __mockRouter: mockRouter,
+    useRouter: () => mockRouter,
+  };
+});
+
+const expoRouter = (expoRouterModule as unknown as { __mockRouter: AppRouter }).__mockRouter;
+
+beforeEach(() => {
+  (expoRouter.push as jest.Mock).mockClear();
+  (expoRouter.replace as jest.Mock).mockClear();
+  (expoRouter.back as jest.Mock).mockClear();
+});
+
+describe("useNavigation", () => {
+  it("falls back to expo-router when no provider is present", () => {
+    const { result } = renderHook(() => useNavigation());
+    result.current.push("/welcome");
+    result.current.replace("/login");
+    result.current.back();
+    expect(expoRouter.push).toHaveBeenCalledWith("/welcome");
+    expect(expoRouter.replace).toHaveBeenCalledWith("/login");
+    expect(expoRouter.back).toHaveBeenCalled();
+  });
+
+  it("uses the override router when wrapped in NavigationProvider", () => {
+    const custom: AppRouter = {
+      push: jest.fn(),
+      replace: jest.fn(),
+      back: jest.fn(),
+    };
+    const { result } = renderHook(() => useNavigation(), {
+      wrapper: ({ children }) => (
+        <NavigationProvider router={custom}>{children}</NavigationProvider>
+      ),
+    });
+    result.current.push("/a");
+    result.current.replace("/b");
+    result.current.back();
+    expect(custom.push).toHaveBeenCalledWith("/a");
+    expect(custom.replace).toHaveBeenCalledWith("/b");
+    expect(custom.back).toHaveBeenCalled();
+    expect(expoRouter.push).not.toHaveBeenCalled();
+  });
+});

package/src/context/index.ts

@@ -0,0 +1,24 @@
+export {
+  AppConfigProvider,
+  useAppConfig,
+  type AppConfig,
+  type AppRoutes,
+  type LogoComponent,
+} from "./AppConfigContext";
+
+export { ThemeProvider, useTheme, type ThemePreference } from "./ThemeContext";
+
+export {
+  NavigationProvider,
+  useNavigation,
+  type AppRouter,
+  type NavigationProviderProps,
+  type RouteTarget,
+} from "./NavigationContext";
+
+export {
+  NotificationProvider,
+  useNotificationContext,
+  type NotificationLevel,
+  type ToastOptions,
+} from "./NotificationContext";