@vvedantb/native-ui 0.6.1 → 0.8.0

package/src/auth/SignInScreen.tsx

@@ -0,0 +1,302 @@
+import { useState, type ReactNode } from "react";
+import { Text, View } from "react-native";
+import { useSignIn, useSignUp } from "@clerk/clerk-expo";
+import { useRouter } from "expo-router";
+import { Button } from "../Button";
+import { textStyle } from "../controlStyles";
+import { Input } from "../Input";
+import { toast } from "../toastStore";
+import { useScheme } from "../useScheme";
+import { AuthScreen, FieldError, OrDivider } from "./AuthScreen";
+import { authErrorMessage } from "./authErrors";
+import { GoogleSignInButton, type AuthNavigationOptions } from "./GoogleSignInButton";
+
+export type SignInMode = "sign-in" | "sign-up";
+
+/** The messages the screen can show. Generic: none names a provider. */
+export const AUTH_MESSAGES = {
+  missingFields: "Enter your email and password",
+  signInFailed: "Sign in failed",
+  invalidCredentials: "Invalid email or password",
+  signUpFailed: "Could not create account",
+  verifyFailed: "Invalid code",
+  missingCode: "Enter the code from the email",
+  needsAnotherStep: "This account needs another step to sign in. Finish it on the web.",
+} as const;
+
+export type SignInScreenProps = AuthNavigationOptions & {
+  /** Default `"sign-in"`. `"sign-up"` creates the account and checks an emailed code. */
+  mode?: SignInMode;
+  /** Default "Welcome back", or "Create account" in `sign-up`. */
+  title?: string;
+  /** Default "Sign in to continue", or "Sign up to get started" in `sign-up`. */
+  subtitle?: string;
+  /** The app URL scheme, such as `"vibot"`, for the Google redirect `scheme://sso-callback`. */
+  scheme: string;
+  /** Default `"sso-callback"`. */
+  redirectPath?: string;
+  /** Default `true`. */
+  showGoogle?: boolean;
+  /** Default "Continue with Google". */
+  googleLabel?: string;
+  /** In `sign-in`: the "Sign up" link in the footer. No link without it. */
+  signUpHref?: string;
+  /** In `sign-up`: the "Sign in" link in the footer. No link without it. */
+  signInHref?: string;
+  /** Sign-up rejects a shorter password before sending it. Default: no check. */
+  minPasswordLength?: number;
+  /** Default `"toast"`. `"inline"` shows errors under the fields. */
+  errorDisplay?: "toast" | "inline";
+  /** Prefix for every `testID`: `sign-in-email`, `sign-in-password`, `sign-in-submit` and the rest. Default the mode. */
+  testIDPrefix?: string;
+  /** Above the title. App brand chrome goes here. */
+  header?: ReactNode;
+  /** Below the footer link row, such as an app credit. */
+  footer?: ReactNode;
+};
+
+/**
+ * Email and password, and Google, sign-in or sign-up. Sign-up sends an email
+ * code and checks it before the session starts. On success it calls
+ * `onSuccess`, or `router.replace(afterAuthHref, replaceOptions)`.
+ *
+ * Forgot-password is not here: an app that needs it keeps its own screen.
+ */
+export function SignInScreen({
+  mode = "sign-in",
+  title,
+  subtitle,
+  scheme,
+  redirectPath,
+  afterAuthHref = "/",
+  replaceOptions,
+  onSuccess,
+  showGoogle = true,
+  googleLabel,
+  signUpHref,
+  signInHref,
+  minPasswordLength,
+  errorDisplay = "toast",
+  testIDPrefix,
+  header,
+  footer,
+}: SignInScreenProps) {
+  const signInState = useSignIn();
+  const signUpState = useSignUp();
+  const router = useRouter();
+  const colorScheme = useScheme();
+  const [email, setEmail] = useState("");
+  const [password, setPassword] = useState("");
+  const [code, setCode] = useState("");
+  const [pendingVerification, setPendingVerification] = useState(false);
+  const [error, setError] = useState("");
+  const [submitting, setSubmitting] = useState(false);
+  const signUp = mode === "sign-up";
+  const id = (name: string) => `${testIDPrefix ?? mode}-${name}`;
+
+  const fail = (heading: string, message: string) => {
+    if (errorDisplay === "inline") setError(message);
+    else toast.error(heading, message === heading ? undefined : { description: message });
+  };
+
+  const done = () => {
+    if (onSuccess) onSuccess();
+    else router.replace(afterAuthHref, replaceOptions);
+  };
+
+  const onSignIn = async () => {
+    const { isLoaded, signIn, setActive } = signInState;
+    if (!isLoaded || !signIn || !setActive || submitting) return;
+    if (!email || !password) return fail(AUTH_MESSAGES.signInFailed, AUTH_MESSAGES.missingFields);
+    setSubmitting(true);
+    setError("");
+    try {
+      const attempt = await signIn.create({ identifier: email, password });
+      if (attempt.status === "complete" && attempt.createdSessionId) {
+        await setActive({ session: attempt.createdSessionId });
+        done();
+      } else {
+        fail(AUTH_MESSAGES.signInFailed, AUTH_MESSAGES.needsAnotherStep);
+      }
+    } catch (caught) {
+      fail(AUTH_MESSAGES.signInFailed, authErrorMessage(caught, AUTH_MESSAGES.invalidCredentials));
+    } finally {
+      setSubmitting(false);
+    }
+  };
+
+  const onSignUp = async () => {
+    const { isLoaded, signUp: attempt } = signUpState;
+    if (!isLoaded || !attempt || submitting) return;
+    if (!email || !password) return fail(AUTH_MESSAGES.signUpFailed, AUTH_MESSAGES.missingFields);
+    if (minPasswordLength && password.length < minPasswordLength) {
+      return fail(AUTH_MESSAGES.signUpFailed, `Use at least ${minPasswordLength} characters for the password`);
+    }
+    setSubmitting(true);
+    setError("");
+    try {
+      await attempt.create({ emailAddress: email, password });
+      await attempt.prepareEmailAddressVerification({ strategy: "email_code" });
+      setPendingVerification(true);
+    } catch (caught) {
+      fail(AUTH_MESSAGES.signUpFailed, authErrorMessage(caught, AUTH_MESSAGES.signUpFailed));
+    } finally {
+      setSubmitting(false);
+    }
+  };
+
+  const onVerify = async () => {
+    const { isLoaded, signUp: attempt, setActive } = signUpState;
+    if (!isLoaded || !attempt || !setActive || submitting) return;
+    if (!code) return fail(AUTH_MESSAGES.verifyFailed, AUTH_MESSAGES.missingCode);
+    setSubmitting(true);
+    setError("");
+    try {
+      const result = await attempt.attemptEmailAddressVerification({ code });
+      if (result.status === "complete" && result.createdSessionId) {
+        await setActive({ session: result.createdSessionId });
+        done();
+      } else {
+        fail(AUTH_MESSAGES.verifyFailed, AUTH_MESSAGES.needsAnotherStep);
+      }
+    } catch (caught) {
+      fail(AUTH_MESSAGES.verifyFailed, authErrorMessage(caught, AUTH_MESSAGES.verifyFailed));
+    } finally {
+      setSubmitting(false);
+    }
+  };
+
+  const linkHref = signUp ? signInHref : signUpHref;
+  const footerRow = (
+    <>
+      {linkHref && !pendingVerification ? (
+        <>
+          <Text className="font-instrument-sans text-sm" style={textStyle("muted", colorScheme)}>
+            {signUp ? "Already have an account?" : "Don't have an account?"}
+          </Text>
+          <Button
+            testID={id(signUp ? "sign-in-link" : "sign-up-link")}
+            variant="link"
+            size="sm"
+            fullWidth={false}
+            onPress={() => router.push(linkHref)}
+          >
+            {signUp ? "Sign in" : "Sign up"}
+          </Button>
+        </>
+      ) : null}
+      {footer}
+    </>
+  );
+  const hasFooter = Boolean((linkHref && !pendingVerification) || footer);
+
+  if (pendingVerification) {
+    return (
+      <AuthScreen
+        testID={id("screen")}
+        title="Check your email"
+        subtitle="Enter the code we sent to your email."
+        header={header}
+        footer={hasFooter ? footerRow : undefined}
+      >
+        <Input
+          testID={id("code")}
+          accessibilityLabel="Verification code"
+          value={code}
+          placeholder="Verification code"
+          keyboardType="number-pad"
+          autoComplete="one-time-code"
+          textContentType="oneTimeCode"
+          autoFocus
+          returnKeyType="go"
+          onChangeText={setCode}
+          onSubmitEditing={() => void onVerify()}
+        />
+        <FieldError testID={id("error")} message={error} />
+        <Button testID={id("verify")} loading={submitting} onPress={() => void onVerify()}>
+          Verify
+        </Button>
+        <Button
+          testID={id("back")}
+          variant="ghost"
+          onPress={() => {
+            setPendingVerification(false);
+            setCode("");
+            setError("");
+          }}
+        >
+          Use a different email
+        </Button>
+      </AuthScreen>
+    );
+  }
+
+  return (
+    <AuthScreen
+      testID={id("screen")}
+      title={title ?? (signUp ? "Create account" : "Welcome back")}
+      subtitle={subtitle ?? (signUp ? "Sign up to get started" : "Sign in to continue")}
+      header={header}
+      footer={hasFooter ? footerRow : undefined}
+    >
+      {showGoogle ? (
+        <>
+          <GoogleSignInButton
+            testID={id("google")}
+            scheme={scheme}
+            redirectPath={redirectPath}
+            afterAuthHref={afterAuthHref}
+            replaceOptions={replaceOptions}
+            onSuccess={onSuccess}
+            onError={(message) => fail(message, message)}
+            label={googleLabel}
+            disabled={submitting}
+          />
+          <OrDivider />
+        </>
+      ) : null}
+      <Input
+        testID={id("email")}
+        accessibilityLabel="Email"
+        autoCapitalize="none"
+        autoComplete="email"
+        textContentType="emailAddress"
+        keyboardType="email-address"
+        returnKeyType="next"
+        value={email}
+        placeholder="Email"
+        onChangeText={setEmail}
+      />
+      <Input
+        testID={id("password")}
+        accessibilityLabel="Password"
+        autoCapitalize="none"
+        autoComplete={signUp ? "new-password" : "password"}
+        textContentType={signUp ? "newPassword" : "password"}
+        secureTextEntry
+        returnKeyType="go"
+        value={password}
+        placeholder="Password"
+        onChangeText={setPassword}
+        onSubmitEditing={() => void (signUp ? onSignUp() : onSignIn())}
+      />
+      <FieldError testID={id("error")} message={error} />
+      <Button
+        testID={id("submit")}
+        loading={submitting}
+        onPress={() => void (signUp ? onSignUp() : onSignIn())}
+      >
+        {signUp ? "Create account" : "Sign in"}
+      </Button>
+      {/* Bot protection mounts its widget here on web sign-up. */}
+      {signUp ? <View nativeID="clerk-captcha" /> : null}
+    </AuthScreen>
+  );
+}
+
+export type SignUpScreenProps = Omit<SignInScreenProps, "mode">;
+
+/** `SignInScreen` with `mode="sign-up"`. */
+export function SignUpScreen(props: SignUpScreenProps) {
+  return <SignInScreen {...props} mode="sign-up" />;
+}

package/src/auth/authErrors.ts

@@ -0,0 +1,19 @@
+import { isClerkAPIResponseError } from "@clerk/clerk-expo";
+
+/** Words that must not reach the user: the auth provider and stack names. */
+const PRODUCT_NAMES = /\b(clerk|convex)\b/i;
+
+/**
+ * A message to show for an auth error. An API error gives its first
+ * `longMessage` or `message` (such as "Password is incorrect."); anything
+ * else, or a message that names the provider, gives `fallback`. Never shows
+ * a raw exception message.
+ */
+export function authErrorMessage(error: unknown, fallback: string): string {
+  if (isClerkAPIResponseError(error)) {
+    const first = error.errors[0];
+    const message = first?.longMessage ?? first?.message;
+    if (message && !PRODUCT_NAMES.test(message)) return message;
+  }
+  return fallback;
+}

package/src/auth/index.ts

@@ -0,0 +1,22 @@
+// Clerk + Convex providers and the shared sign-in and sign-up screens. On
+// `@vvedantb/native-ui/auth` only: they import `@clerk/clerk-expo`, `convex`,
+// `expo-auth-session`, `expo-web-browser` and `expo-router`, and Metro does not
+// tree-shake.
+export { AuthProviders } from "./AuthProviders";
+export type { AuthProvidersProps } from "./AuthProviders";
+export { AuthScreen, OrDivider, FieldError } from "./AuthScreen";
+export type { AuthScreenProps } from "./AuthScreen";
+export { authErrorMessage } from "./authErrors";
+export {
+  GoogleSignInButton,
+  useGoogleSignIn,
+  useWarmUpBrowser,
+  GOOGLE_ERROR_MESSAGE,
+} from "./GoogleSignInButton";
+export type {
+  AuthNavigationOptions,
+  GoogleSignInOptions,
+  GoogleSignInButtonProps,
+} from "./GoogleSignInButton";
+export { SignInScreen, SignUpScreen, AUTH_MESSAGES } from "./SignInScreen";
+export type { SignInMode, SignInScreenProps, SignUpScreenProps } from "./SignInScreen";

package/src/entries/auth.ts

@@ -0,0 +1,5 @@
+// `@vvedantb/native-ui/auth`: `AuthProviders`, `SignInScreen`, `SignUpScreen`,
+// `GoogleSignInButton` and the auth frame. Not on the root entry: it imports
+// `@clerk/clerk-expo`, `convex`, `expo-auth-session`, `expo-web-browser` and
+// `expo-router`, and Metro does not tree-shake.
+export * from "../auth";

package/src/entries/expo-web-root.ts

@@ -0,0 +1,4 @@
+// `@vvedantb/native-ui/expo-web-root`: `ExpoWebRoot` for `app/+html.tsx`. Not on
+// the root entry: it imports `expo-router/html`, and Metro does not tree-shake.
+export { ExpoWebRoot, EXPO_WEB_VIEWPORT, expoWebBackgroundCss } from "../ExpoWebRoot";
+export type { ExpoWebRootProps, ExpoWebRootViewport } from "../ExpoWebRoot";

package/src/entries/layout.ts

@@ -12,3 +12,21 @@ export { SettingsSection } from "../settings/SettingsSection";
 export { SettingsField } from "../settings/SettingsField";
 export { SettingsToggleRow } from "../settings/SettingsToggleRow";
 export { SettingsStack } from "../settings/SettingsStack";
+export { MoreFromProjectV, FromProjectV } from "../settings/MoreFromProjectV";
+export type { MoreFromProjectVProps, FromProjectVProps } from "../settings/MoreFromProjectV";
+export {
+  PROJECT_V_MOBILE_APPS,
+  projectVMobileApp,
+  otherProjectVMobileApps,
+  openProjectVApp,
+  projectVAppOpenSteps,
+  VSTORE_HOME_URL,
+  androidIntentUrl,
+} from "../settings/projectVMobileApps";
+export type {
+  ProjectVMobileApp,
+  ProjectVMobileAppId,
+  ProjectVOpenTarget,
+  ProjectVOpenStep,
+  ProjectVLinking,
+} from "../settings/projectVMobileApps";

package/src/examples/ParityGallery.tsx

@@ -54,12 +54,14 @@ import {
   DialogTitle,
   DialogTrigger,
   EmptyState,
+  FromProjectV,
   GoogleMark,
   IconButton,
   Input,
   Label,
   LabeledSwitchRow,
   ListRow,
+  MoreFromProjectV,
   NEUTRAL_900,
   NativeUiProvider,
   PageHeader,
@@ -682,6 +684,15 @@ function GalleryScreen() {
           </AmbientBackground>
         </Section>
 
+        <Section title="More from Project V">
+          {/* As in Velth's settings: the other four phone apps. A row opens the app, else V Store, else the website. */}
+          <MoreFromProjectV
+            current="velth"
+            onOpen={(id, target) => toast(target ? `Opened ${id} (${target})` : `Could not open ${id}`)}
+          />
+          <FromProjectV />
+        </Section>
+
         <Section title="Camera chrome">
           {/* A dark stand-in for the live preview. */}
           <View className="h-72 justify-between overflow-hidden rounded-lg p-4" style={{ backgroundColor: NEUTRAL_900 }}>

package/src/index.ts

@@ -164,6 +164,24 @@ export { SettingsSection } from "./settings/SettingsSection";
 export { SettingsField } from "./settings/SettingsField";
 export { SettingsToggleRow } from "./settings/SettingsToggleRow";
 export { SettingsStack } from "./settings/SettingsStack";
+export { MoreFromProjectV, FromProjectV } from "./settings/MoreFromProjectV";
+export type { MoreFromProjectVProps, FromProjectVProps } from "./settings/MoreFromProjectV";
+export {
+  PROJECT_V_MOBILE_APPS,
+  projectVMobileApp,
+  otherProjectVMobileApps,
+  openProjectVApp,
+  projectVAppOpenSteps,
+  VSTORE_HOME_URL,
+  androidIntentUrl,
+} from "./settings/projectVMobileApps";
+export type {
+  ProjectVMobileApp,
+  ProjectVMobileAppId,
+  ProjectVOpenTarget,
+  ProjectVOpenStep,
+  ProjectVLinking,
+} from "./settings/projectVMobileApps";
 export { PINK_50, PINK_100, PINK_600, PINK_700, NEUTRAL_100, NEUTRAL_500, NEUTRAL_900, Colors } from "./colors";
 // Family app marks and their pure data (copied from `@vvedantb/ui/brand`), and `GoogleMark`.
 export * from "./brand";

package/src/settings/MoreFromProjectV.tsx

@@ -0,0 +1,105 @@
+import { Linking, Platform, Text, View } from "react-native";
+import { APP_ICONS } from "../brand/AppIcons";
+import { AppMark } from "../brand/AppMark";
+import type { AppName } from "../brand/svg";
+import { cn } from "../cn";
+import { textStyle, typeStyle } from "../controlStyles";
+import { ListRow } from "../ListRow";
+import { tokens } from "../tokens";
+import { useScheme } from "../useScheme";
+import { SettingsSection } from "./SettingsSection";
+import {
+  openProjectVApp,
+  otherProjectVMobileApps,
+  type ProjectVMobileAppId,
+  type ProjectVOpenTarget,
+} from "./projectVMobileApps";
+
+/**
+ * The mark for each phone app. V Store has no mark of its own (it was left out
+ * of the brand marks in 0.3.9), so it shows the Project V mark.
+ */
+const MARK: Record<ProjectVMobileAppId, AppName> = {
+  vibot: "vibot",
+  verve: "verve",
+  velth: "velth",
+  vmem: "vmem",
+  vstore: "projectv",
+};
+
+export type FromProjectVProps = {
+  className?: string;
+  testID?: string;
+};
+
+/** A small muted "from Project V" line with the Project V mark, for the end of a settings screen. */
+export function FromProjectV({ className, testID }: FromProjectVProps) {
+  const scheme = useScheme();
+  const muted = tokens.color.muted[scheme];
+  const ProjectVMark = APP_ICONS.projectv;
+  return (
+    <View
+      testID={testID}
+      accessible
+      accessibilityLabel="from Project V"
+      className={cn("flex-row items-center justify-center gap-1.5 py-2", className)}
+    >
+      <Text className="text-sm font-instrument-sans" style={textStyle("muted", scheme)}>
+        from
+      </Text>
+      <ProjectVMark size={14} color={muted} />
+      <Text
+        className="text-sm font-instrument-sans-semibold"
+        style={[textStyle("muted", scheme), typeStyle("semibold")]}
+      >
+        Project V
+      </Text>
+    </View>
+  );
+}
+
+export type MoreFromProjectVProps = {
+  /** The app showing the section. It is left out of the list. */
+  current: ProjectVMobileAppId;
+  /** `"section"` (default): a settings section listing the other apps. `"footer"`: only the small "from Project V" line. */
+  variant?: "section" | "footer";
+  /** Section title. Default "More from Project V". */
+  title?: string;
+  /** Called after a row opens something: the app, V Store or its website (`null` if nothing opened). */
+  onOpen?: (id: ProjectVMobileAppId, target: ProjectVOpenTarget | null) => void;
+  className?: string;
+};
+
+/**
+ * Settings section listing the other Project V phone apps, each with its mark,
+ * name and one line. A row opens the app if it is installed, else V Store's
+ * home, else its website (`openProjectVApp`).
+ */
+export function MoreFromProjectV({
+  current,
+  variant = "section",
+  title = "More from Project V",
+  onOpen,
+  className,
+}: MoreFromProjectVProps) {
+  if (variant === "footer") return <FromProjectV className={className} />;
+  return (
+    <SettingsSection title={title} bodyVariant="list" className={className}>
+      <View className="flex-col gap-1 p-1">
+        {otherProjectVMobileApps(current).map((app) => (
+          <ListRow
+            key={app.id}
+            testID={`more-from-project-v-${app.id}`}
+            title={app.name}
+            meta={app.description}
+            leading={<AppMark app={MARK[app.id]} size={28} />}
+            accessibilityLabel={`${app.name}, ${app.description}`}
+            onPress={() => {
+              void openProjectVApp(app.id, Linking, Platform.OS).then((target) => onOpen?.(app.id, target));
+            }}
+          />
+        ))}
+      </View>
+    </SettingsSection>
+  );
+}

package/src/settings/projectVMobileApps.ts

@@ -0,0 +1,145 @@
+import { familyApp } from "../brand/familyApps";
+
+/** The Project V phone apps, in display order. */
+export type ProjectVMobileAppId = "vibot" | "verve" | "velth" | "vmem" | "vstore";
+
+export type ProjectVMobileApp = {
+  id: ProjectVMobileAppId;
+  /** Display name. */
+  name: string;
+  /** One line for a settings row. */
+  description: string;
+  /** Android application id. */
+  androidPackage: string;
+  /** The app's URL scheme, without `://`. */
+  scheme: string;
+  /** Home page of the app: the fallback when neither the app nor V Store is installed. */
+  website: string;
+};
+
+/**
+ * V Store's home screen. V Store's `app/[id]` route takes the app's Convex
+ * document `_id`, not its catalog id or Android package, and native-ui cannot
+ * know live Convex ids. So the store step opens V Store's home, not the app's page.
+ */
+export const VSTORE_HOME_URL = "vstore://";
+
+// Names and sites come from `FAMILY_APPS` where it has the app. V Store is not
+// a family app there (that file is a byte-identical copy of `@vvedantb/ui`).
+const vibot = familyApp("vibot");
+const verve = familyApp("verve");
+const velth = familyApp("velth");
+const vmem = familyApp("vmem");
+
+/** The five Project V phone apps, in display order. */
+export const PROJECT_V_MOBILE_APPS: readonly ProjectVMobileApp[] = [
+  {
+    id: "vibot",
+    name: vibot.name,
+    description: "AI chat, agents and tools",
+    androidPackage: "com.projectvdotuk.vibot",
+    scheme: "vibot",
+    website: vibot.url,
+  },
+  {
+    id: "verve",
+    name: verve.name,
+    description: "Notes, pages and writing",
+    androidPackage: "com.projectvdotuk.verve",
+    scheme: "verve",
+    website: verve.url,
+  },
+  {
+    id: "velth",
+    name: velth.name,
+    description: "Health insights and camera scans",
+    androidPackage: "com.projectvdotuk.velth",
+    scheme: "velth",
+    website: velth.url,
+  },
+  {
+    id: "vmem",
+    name: vmem.name,
+    description: "Your personal memory",
+    androidPackage: "com.projectvdotuk.vmem",
+    scheme: "vmem",
+    website: vmem.url,
+  },
+  {
+    id: "vstore",
+    name: "V Store",
+    description: "Install Project V apps",
+    androidPackage: "com.projectvdotuk.vstore",
+    scheme: "vstore",
+    website: "https://v-store-chi.vercel.app",
+  },
+];
+
+/** Entry of `PROJECT_V_MOBILE_APPS` for an app. */
+export function projectVMobileApp(id: ProjectVMobileAppId): ProjectVMobileApp {
+  return PROJECT_V_MOBILE_APPS.find((app) => app.id === id)!;
+}
+
+/** The phone apps other than `current`, in display order. */
+export function otherProjectVMobileApps(current?: ProjectVMobileAppId): ProjectVMobileApp[] {
+  return PROJECT_V_MOBILE_APPS.filter((app) => app.id !== current);
+}
+
+/** Android intent URL that opens the installed app with this package. */
+export function androidIntentUrl(app: ProjectVMobileApp): string {
+  return `intent://#Intent;scheme=${app.scheme};package=${app.androidPackage};end`;
+}
+
+/** How `openProjectVApp` opened an app. */
+export type ProjectVOpenTarget = "app" | "store" | "website";
+
+/** One URL to try, in order. `check`: ask `canOpenURL` first; otherwise try `openURL` and move on if it fails. */
+export type ProjectVOpenStep = {
+  target: ProjectVOpenTarget;
+  url: string;
+  check: boolean;
+};
+
+/**
+ * The URLs `openProjectVApp` tries, in order: the app's scheme; on Android an
+ * intent to its package; V Store's home (`VSTORE_HOME_URL`); the website.
+ */
+export function projectVAppOpenSteps(id: ProjectVMobileAppId, os: string): ProjectVOpenStep[] {
+  const app = projectVMobileApp(id);
+  const steps: ProjectVOpenStep[] = [{ target: "app", url: `${app.scheme}://`, check: true }];
+  if (os === "android") steps.push({ target: "app", url: androidIntentUrl(app), check: false });
+  if (id !== "vstore") steps.push({ target: "store", url: VSTORE_HOME_URL, check: true });
+  steps.push({ target: "website", url: app.website, check: false });
+  return steps;
+}
+
+/** The part of React Native `Linking` that `openProjectVApp` uses. */
+export type ProjectVLinking = {
+  canOpenURL(url: string): Promise<boolean>;
+  openURL(url: string): Promise<unknown>;
+};
+
+/**
+ * Opens a Project V app: the app if installed, else V Store's home if V Store
+ * is installed, else its website. Resolves to what it opened, or
+ * `null` when every URL failed. Pass React Native `Linking` and `Platform.OS`.
+ *
+ * `canOpenURL` needs the schemes declared by the calling app:
+ * `LSApplicationQueriesSchemes` on iOS and `<queries>` on Android 11+.
+ */
+export async function openProjectVApp(
+  id: ProjectVMobileAppId,
+  linking: ProjectVLinking,
+  os: string,
+): Promise<ProjectVOpenTarget | null> {
+  for (const step of projectVAppOpenSteps(id, os)) {
+    try {
+      if (step.check && !(await linking.canOpenURL(step.url))) continue;
+      await linking.openURL(step.url);
+      return step.target;
+    } catch {
+      // Not installed, or no handler: try the next URL.
+    }
+  }
+  return null;
+}