@entropy-softworks/ui 2026.7.31

package/src/components/item-icon.tsx

@@ -0,0 +1,111 @@
+import React, { useEffect, useState } from "react";
+import { Image, Platform, View } from "react-native";
+import { Ionicons } from "@expo/vector-icons";
+import { useColorScheme } from "nativewind";
+import { resolveIcon } from "../services/favicon";
+import { useUploadBlobUrl } from "../hooks/useUploadBlobUrl";
+
+export interface ItemIconProps {
+  /**
+   * Stored icon reference. Either a literal URL, a `custom:<uploadId>`
+   * marker (fetched through the auth-aware transport), or null/empty
+   * to fall back to the favicon proxy.
+   */
+  iconUrl?: string | null;
+  /** Site URL the favicon proxy derives a public URL from. */
+  siteUrl?: string | null;
+  /** Tile size in pixels (square). Defaults to 40. */
+  size?: number;
+  /** Inner image size. Defaults to roughly 60% of `size`. */
+  imageSize?: number;
+  /** Tile corner radius. Defaults to 25% of `size`. */
+  borderRadius?: number;
+  /** Tile background override. Defaults to the secondary surface. */
+  background?: string;
+  /** Globe-glyph color override. Defaults to muted-foreground. */
+  fallbackColor?: string;
+  /** Favicon proxy path on the configured API server. Defaults to `/favicon`. */
+  faviconPath?: string;
+  /** Upload-fetch path prefix. Defaults to `/uploads`. */
+  uploadsPath?: string;
+}
+
+// react-native-web forwards `loading` and `decoding` to the underlying
+// <img>; RN's TS types don't expose these props, so we cast through a
+// Record<string, string> for the web branch.
+const WEB_LAZY_PROPS =
+  Platform.OS === "web" ? ({ loading: "lazy", decoding: "async" } as Record<string, string>) : {};
+
+/**
+ * Per-item icon: shows the custom upload, falls back to the favicon
+ * proxy, then to a generic globe glyph on a tile-toned square. Shared
+ * between RN clients (mobile) and RN-Web (extension popup).
+ */
+export const ItemIcon = React.memo(function ItemIcon({
+  iconUrl,
+  siteUrl,
+  size = 40,
+  imageSize,
+  borderRadius,
+  background,
+  fallbackColor,
+  faviconPath = "/favicon",
+  uploadsPath = "/uploads",
+}: ItemIconProps) {
+  const { colorScheme } = useColorScheme();
+  const isDark = colorScheme === "dark";
+
+  const resolved = resolveIcon({ iconUrl, siteUrl, faviconPath });
+  const uploadId = resolved.kind === "upload" ? resolved.uploadId : null;
+  const upload = useUploadBlobUrl(uploadId, uploadsPath);
+
+  const directUri = resolved.kind === "url" ? resolved.uri : null;
+  const [urlErrored, setUrlErrored] = useState(false);
+  useEffect(() => {
+    setUrlErrored(false);
+  }, [directUri]);
+
+  const renderUri = uploadId ? upload.uri : directUri;
+  const renderErrored = uploadId ? upload.errored : urlErrored;
+  const onError = () => {
+    if (uploadId) {
+      upload.setErrored(true);
+    } else {
+      setUrlErrored(true);
+    }
+  };
+
+  const tileBg = background ?? (isDark ? "rgb(38, 38, 38)" : "rgb(245, 245, 245)");
+  const tileRadius = borderRadius ?? size * 0.25;
+  const innerSize = imageSize ?? Math.round(size * 0.6);
+  const globeColor = fallbackColor ?? (isDark ? "rgb(163, 163, 163)" : "rgb(115, 115, 115)");
+
+  const showFallback = !renderUri || renderErrored;
+
+  return (
+    <View
+      style={{
+        width: size,
+        height: size,
+        borderRadius: tileRadius,
+        backgroundColor: tileBg,
+        alignItems: "center",
+        justifyContent: "center",
+        overflow: "hidden",
+      }}
+    >
+      {showFallback ? (
+        <Ionicons name="globe-outline" size={Math.round(innerSize * 0.85)} color={globeColor} />
+      ) : (
+        <Image
+          source={{ uri: renderUri ?? "" }}
+          style={{ width: innerSize, height: innerSize }}
+          resizeMode="contain"
+          onError={onError}
+          accessibilityIgnoresInvertColors
+          {...WEB_LAZY_PROPS}
+        />
+      )}
+    </View>
+  );
+});

package/src/components/label.tsx

@@ -0,0 +1,25 @@
+import React from "react";
+import * as LabelPrimitive from "@rn-primitives/label";
+import { cn } from "../utils/cn";
+
+const FormLabel = React.forwardRef<
+  React.ElementRef<typeof LabelPrimitive.Root>,
+  React.ComponentPropsWithoutRef<typeof LabelPrimitive.Root>
+>(({ className, ...props }, ref) => (
+  <LabelPrimitive.Root ref={ref} className={cn("", className)} {...props} />
+));
+FormLabel.displayName = "FormLabel";
+
+const FormLabelText = React.forwardRef<
+  React.ElementRef<typeof LabelPrimitive.Text>,
+  React.ComponentPropsWithoutRef<typeof LabelPrimitive.Text>
+>(({ className, ...props }, ref) => (
+  <LabelPrimitive.Text
+    ref={ref}
+    className={cn("text-sm font-medium text-foreground dark:text-white", className)}
+    {...props}
+  />
+));
+FormLabelText.displayName = "FormLabelText";
+
+export { FormLabel, FormLabelText };

package/src/components/legal-dialog.tsx

@@ -0,0 +1,47 @@
+import React from "react";
+import { ScrollView, Text, useWindowDimensions, View } from "react-native";
+import { Dialog } from "./dialog";
+import { EntropyByline } from "./entropy-mark";
+
+export interface LegalDialogProps {
+  visible: boolean;
+  onClose: () => void;
+  /** e.g. "Terms of Service" / "Privacy Policy". */
+  title: string;
+  /** Body copy. Split into paragraphs on blank lines. App-supplied so each
+   * app customises the wording; the dialog itself is themed by the palette. */
+  content?: string;
+}
+
+/**
+ * Reusable legal popup (Terms / Privacy / etc). A scrollable dialog instead
+ * of a dedicated route — apps pass their own `content` and inherit the
+ * active theme. Built on the shared `Dialog`.
+ */
+export function LegalDialog({ visible, onClose, title, content }: LegalDialogProps) {
+  const { height } = useWindowDimensions();
+  const paragraphs = (content ?? `${title} for this application.`)
+    .trim()
+    .split(/\n{2,}/)
+    .map((p) => p.trim())
+    .filter(Boolean);
+
+  return (
+    <Dialog visible={visible} onClose={onClose} title={title} maxWidth={560} draggable>
+      <ScrollView style={{ maxHeight: height * 0.6 }} showsVerticalScrollIndicator={false}>
+        <View style={{ gap: 12, paddingBottom: 4 }}>
+          {paragraphs.map((p, i) => (
+            <Text key={i} className="text-sm leading-5 text-muted-foreground">
+              {p}
+            </Text>
+          ))}
+          <View style={{ marginTop: 16 }}>
+            <EntropyByline size={16} />
+          </View>
+        </View>
+      </ScrollView>
+    </Dialog>
+  );
+}
+
+export default LegalDialog;

package/src/components/license-gate.tsx

@@ -0,0 +1,28 @@
+import React from "react";
+import { ENABLE_LICENSING } from "../flags";
+
+export interface LicenseGateProps {
+  children: React.ReactNode;
+  /** Rendered while a license check is pending/denied once licensing is wired. */
+  fallback?: React.ReactNode;
+}
+
+/**
+ * Structural licensing gate. With `EXPO_PUBLIC_ENABLE_LICENSING` unset/false
+ * (self-host default) it's a pass-through. SaaS production ships the flag
+ * `true`; the actual licensing/subscription check lives in a separate app and
+ * plugs in here later. Wrapping the app root with this now means the gate
+ * exists identically everywhere — flipping the env var (and adding the check)
+ * is the only change needed to enforce it.
+ */
+export function LicenseGate({ children }: LicenseGateProps) {
+  if (!ENABLE_LICENSING) {
+    return <>{children}</>;
+  }
+  // TODO(saas): delegate to the licensing app — validate subscription/seat and
+  // render `fallback` when invalid. Until then, enabling the flag is a no-op
+  // pass-through so the wiring can ship ahead of the integration.
+  return <>{children}</>;
+}
+
+export default LicenseGate;

package/src/components/logo.tsx

@@ -0,0 +1,34 @@
+import React from "react";
+import { View } from "react-native";
+import { Text } from "./text";
+import { useAppConfig } from "../context/AppConfigContext";
+
+export interface BrandHeaderProps {
+  /** Icon size in pixels. Wordmark text scales relative. */
+  size?: number;
+  /** Hide the wordmark and show just the icon. Useful in tight headers. */
+  iconOnly?: boolean;
+}
+
+/**
+ * Brand header — pairs the configured `AppConfig.Logo` with the `appName`
+ * wordmark. Apps register their logo + name via `AppConfigProvider`; this
+ * widget renders them at a uniform size across screens (welcome, login,
+ * settings header, extension popup header).
+ */
+export function BrandHeader({ size = 32, iconOnly = false }: BrandHeaderProps) {
+  const { appName, Logo } = useAppConfig();
+  return (
+    <View className="flex-row items-center" style={{ gap: 10 }}>
+      <Logo width={size} height={size} />
+      {iconOnly ? null : (
+        <Text
+          className="font-sans-bold text-foreground"
+          style={{ fontSize: Math.round(size * 0.6), letterSpacing: -0.5 }}
+        >
+          {appName}
+        </Text>
+      )}
+    </View>
+  );
+}

package/src/components/onboarding-wizard.tsx

@@ -0,0 +1,353 @@
+import React, { useEffect, useState } from "react";
+import { ActivityIndicator, Pressable, ScrollView, Text, View } from "react-native";
+import { SafeAreaView } from "react-native-safe-area-context";
+import { usePalette } from "../utils/palette";
+
+/**
+ * Optional brand color overrides so onboarding matches the host app's sign-in
+ * styling instead of the generic theme palette. Any omitted key falls back to
+ * the active palette.
+ */
+export interface OnboardingTheme {
+  background?: string;
+  card?: string;
+  border?: string;
+  foreground?: string;
+  mutedForeground?: string;
+  primary?: string;
+  primaryForeground?: string;
+  /** Icon-tile background on OnboardingOptionCard. */
+  iconBackground?: string;
+}
+
+// Generic, app-agnostic first-run onboarding wizard. The host app supplies the
+// step content (e.g. "secure your account" with MFA/passkey, "connect your
+// accounts" with Plaid); this shell owns the chrome: progress dots, title,
+// scroll body, and the continue/skip/finish footer. Reusable across finance
+// apps (Simple Finance, Paperhands) and beyond — it knows nothing about MFA,
+// Plaid, or any domain.
+
+export interface OnboardingStepApi {
+  /** Advance to the next step (or finish on the last step). */
+  next: () => void;
+  /** Go back to the previous step (no-op on the first). */
+  back: () => void;
+  index: number;
+  total: number;
+  isLast: boolean;
+}
+
+export interface OnboardingStepDef {
+  key: string;
+  title: string;
+  subtitle?: string;
+  /** Step body. Receives the wizard api so its own actions can advance. */
+  content: (api: OnboardingStepApi) => React.ReactNode;
+  /** Show a "skip" affordance that advances without completing the step. */
+  canSkip?: boolean;
+  /** Override the primary button label for this step. */
+  primaryLabel?: string;
+  /** Hide the footer primary button (the step drives its own advance). */
+  hidePrimary?: boolean;
+  /**
+   * Gate advancing: when false the primary button is disabled (e.g. a required
+   * step the user hasn't satisfied yet, like mandatory MFA enrollment).
+   * Defaults to true.
+   */
+  canContinue?: boolean;
+  /**
+   * Already-satisfied step. Counts toward the total + shows a filled progress
+   * dot, but its body is never rendered — the wizard starts at the first
+   * not-done step and skips done ones. Lets a resumed onboarding show absolute
+   * position ("Step 3 of 3") instead of remaining-only ("1 of 1").
+   */
+  done?: boolean;
+}
+
+export interface OnboardingWizardProps {
+  steps: OnboardingStepDef[];
+  /** Called after the final step's continue/skip. Mark onboarding complete here. */
+  onComplete: () => void | Promise<void>;
+  /** Branding slot rendered above the progress + card (e.g. logo + app name). */
+  header?: React.ReactNode;
+  /** Card max width on large screens / web so it reads as an overlay, not full-bleed. */
+  maxWidth?: number;
+  /** Show the "Step X of N" label under the progress dots. Default true. */
+  showStepLabel?: boolean;
+  /** Brand color overrides so the chrome matches the app's sign-in styling. */
+  theme?: OnboardingTheme;
+  skipLabel?: string;
+  finishLabel?: string;
+  continueLabel?: string;
+}
+
+export function OnboardingWizard({
+  steps,
+  onComplete,
+  header,
+  maxWidth = 440,
+  showStepLabel = true,
+  theme,
+  skipLabel = "Skip for now",
+  finishLabel = "Finish",
+  continueLabel = "Continue",
+}: OnboardingWizardProps) {
+  const { palette } = usePalette();
+  const c = {
+    background: theme?.background ?? palette.background,
+    card: theme?.card ?? palette.card,
+    border: theme?.border ?? palette.border,
+    foreground: theme?.foreground ?? palette.foreground,
+    mutedForeground: theme?.mutedForeground ?? palette.mutedForeground,
+    primary: theme?.primary ?? palette.primary,
+    primaryForeground: theme?.primaryForeground ?? palette.primaryForeground,
+  };
+  // Start at the first not-done step; done steps before it are completed
+  // milestones (filled dots, never rendered).
+  const [index, setIndex] = useState(() => {
+    const i = steps.findIndex((s) => !s.done);
+    return i === -1 ? 0 : i;
+  });
+  const [finishing, setFinishing] = useState(false);
+
+  const finish = async () => {
+    setFinishing(true);
+    try {
+      await onComplete();
+    } finally {
+      setFinishing(false);
+    }
+  };
+
+  // Every step satisfied — nothing to render; complete once.
+  const allDone = steps.every((s) => s.done);
+  useEffect(() => {
+    if (allDone) {
+      void finish();
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [allDone]);
+
+  const step = steps[index];
+  // Next/prev among the not-done steps only (done ones are skipped over).
+  const nextActive = steps.findIndex((s, i) => i > index && !s.done);
+  const isLast = nextActive === -1;
+
+  const next = async () => {
+    if (isLast) {
+      await finish();
+      return;
+    }
+    setIndex(nextActive);
+  };
+  const back = () => {
+    let prev = -1;
+    for (let i = 0; i < index; i += 1) {
+      if (!steps[i]?.done) {
+        prev = i;
+      }
+    }
+    if (prev >= 0) {
+      setIndex(prev);
+    }
+  };
+
+  const api: OnboardingStepApi = { next, back, index, total: steps.length, isLast };
+
+  if (!step) {
+    return null;
+  }
+
+  return (
+    <SafeAreaView style={{ flex: 1, backgroundColor: c.background }}>
+      <ScrollView
+        contentContainerStyle={{
+          flexGrow: 1,
+          alignItems: "center",
+          justifyContent: "center",
+          padding: 24,
+        }}
+        showsVerticalScrollIndicator={false}
+        keyboardShouldPersistTaps="handled"
+      >
+        {/* constrained, centered column — an overlay card on web, full-width on phones */}
+        <View style={{ width: "100%", maxWidth }}>
+          {header ? <View style={{ alignItems: "center", marginBottom: 22 }}>{header}</View> : null}
+
+          {/* progress: dots + step label */}
+          <View style={{ alignItems: "center", gap: 8, marginBottom: 16 }}>
+            <View style={{ flexDirection: "row", gap: 6 }}>
+              {steps.map((s, i) => (
+                <View
+                  key={s.key}
+                  style={{
+                    width: i === index ? 22 : 7,
+                    height: 7,
+                    borderRadius: 999,
+                    backgroundColor: i <= index || s.done ? c.primary : c.border,
+                  }}
+                />
+              ))}
+            </View>
+            {showStepLabel ? (
+              <Text style={{ color: c.mutedForeground, fontFamily: "Geist-Medium", fontSize: 12 }}>
+                Step {index + 1} of {steps.length}
+              </Text>
+            ) : null}
+          </View>
+
+          {/* card panel */}
+          <View
+            style={{
+              backgroundColor: c.card,
+              borderRadius: 24,
+              borderWidth: 1,
+              borderColor: c.border,
+              padding: 20,
+              gap: 8,
+            }}
+          >
+            <Text style={{ color: c.foreground, fontFamily: "Geist-Bold", fontSize: 22 }}>
+              {step.title}
+            </Text>
+            {step.subtitle ? (
+              <Text
+                style={{
+                  color: c.mutedForeground,
+                  fontFamily: "Geist-Regular",
+                  fontSize: 14,
+                  lineHeight: 20,
+                }}
+              >
+                {step.subtitle}
+              </Text>
+            ) : null}
+            <View style={{ marginTop: 10 }}>{step.content(api)}</View>
+
+            <View style={{ gap: 10, marginTop: 14 }}>
+              {!step.hidePrimary ? (
+                <Pressable
+                  onPress={next}
+                  disabled={finishing || step.canContinue === false}
+                  style={{
+                    backgroundColor: c.primary,
+                    borderRadius: 14,
+                    paddingVertical: 15,
+                    alignItems: "center",
+                    opacity: finishing || step.canContinue === false ? 0.5 : 1,
+                  }}
+                >
+                  {finishing ? (
+                    <ActivityIndicator color={c.primaryForeground} />
+                  ) : (
+                    <Text
+                      style={{ color: c.primaryForeground, fontFamily: "Geist-Bold", fontSize: 16 }}
+                    >
+                      {step.primaryLabel ?? (isLast ? finishLabel : continueLabel)}
+                    </Text>
+                  )}
+                </Pressable>
+              ) : null}
+              {step.canSkip ? (
+                <Pressable
+                  onPress={next}
+                  disabled={finishing}
+                  style={{ alignItems: "center", paddingVertical: 4 }}
+                >
+                  <Text
+                    style={{ color: c.mutedForeground, fontFamily: "Geist-Medium", fontSize: 14 }}
+                  >
+                    {skipLabel}
+                  </Text>
+                </Pressable>
+              ) : null}
+            </View>
+          </View>
+        </View>
+      </ScrollView>
+    </SafeAreaView>
+  );
+}
+
+export interface OnboardingOptionCardProps {
+  icon?: React.ReactNode;
+  title: string;
+  subtitle?: string;
+  /** Trailing element (e.g. a spinner or chevron). */
+  right?: React.ReactNode;
+  onPress?: () => void;
+  /** Highlight the card (e.g. completed/selected) with the primary color. */
+  selected?: boolean;
+  /** Brand color overrides to match the app's sign-in styling. */
+  theme?: OnboardingTheme;
+}
+
+/**
+ * Tappable card for onboarding step bodies — an icon tile, title + subtitle,
+ * and optional trailing slot. Domain-agnostic; apps drop these into a wizard
+ * step to offer choices (add passkey, connect a bank, …).
+ */
+export function OnboardingOptionCard({
+  icon,
+  title,
+  subtitle,
+  right,
+  onPress,
+  selected,
+  theme,
+}: OnboardingOptionCardProps) {
+  const { palette } = usePalette();
+  const c = {
+    card: theme?.card ?? palette.card,
+    border: theme?.border ?? palette.border,
+    foreground: theme?.foreground ?? palette.foreground,
+    mutedForeground: theme?.mutedForeground ?? palette.mutedForeground,
+    primary: theme?.primary ?? palette.primary,
+    iconBackground: theme?.iconBackground ?? palette.muted,
+  };
+  return (
+    <Pressable
+      onPress={onPress}
+      disabled={!onPress}
+      style={{
+        flexDirection: "row",
+        alignItems: "center",
+        gap: 12,
+        padding: 16,
+        borderRadius: 14,
+        borderWidth: 1,
+        borderColor: selected ? c.primary : c.border,
+        backgroundColor: c.card,
+        opacity: onPress ? 1 : 0.9,
+      }}
+    >
+      {icon ? (
+        <View
+          style={{
+            width: 42,
+            height: 42,
+            borderRadius: 12,
+            alignItems: "center",
+            justifyContent: "center",
+            backgroundColor: c.iconBackground,
+          }}
+        >
+          {icon}
+        </View>
+      ) : null}
+      <View style={{ flex: 1 }}>
+        <Text style={{ color: c.foreground, fontFamily: "Geist-Medium", fontSize: 15 }}>
+          {title}
+        </Text>
+        {subtitle ? (
+          <Text style={{ color: c.mutedForeground, fontFamily: "Geist-Regular", fontSize: 12 }}>
+            {subtitle}
+          </Text>
+        ) : null}
+      </View>
+      {right}
+    </Pressable>
+  );
+}
+
+export default OnboardingWizard;