@pithy-sh/ui-react-native 0.0.0-stage → 0.1.0

package/templates/src/pithy-config.generated.ts

@@ -0,0 +1,99 @@
+// Written from apps/__PITHY_WORKER__'s composed config. Pithy's `ui sync --app` rewrites it when that config
+// changes, and keeps the fields below that are yours.
+//
+// Yours to edit, and kept by a sync: `appScheme`, `universalLinkOrigin`, `google` and `rails`.
+//
+// `rails.ios`, `rails.android` and `rails.web` name the rail each platform sells through: "apple", "google",
+// "stripe", "lemonSqueezy", "paddle", or "none" to show plans and sell nothing. Change one here, or pass
+// `--ios-rail`, `--android-rail` or `--web-rail` to `ui sync --app`. A rail the Worker does not enable is
+// refused. A web rail on a phone opens checkout in the system browser.
+//
+// `origins` holds where the Worker answers in each environment, and a build calls the one
+// `EXPO_PUBLIC_PITHY_ENV` names: dev, staging or prod, dev when it is unset. An origin is null when Pithy
+// could not find it: a Worker that answers only on workers.dev, or one that declares no domain. Set
+// `origins.staging` or `origins.prod` by hand then, and a sync keeps it until the Worker declares one.
+// A dev origin that is not this machine's loopback, such as your network address for a device, is kept too.
+//
+// `auth`, `i18n`, `payments`, `turnstile` and `consent` hold each capability's projection in each environment
+// `origins` names, and a build reads the one for its environment: a sitekey or a catalog can differ between them.
+//
+// Everything else is the Worker's. Change its pithy.config.ts and run `ui sync --app` again.
+// The value stays a plain literal: strings, numbers, true, false, null, arrays and objects. A sync reads it
+// back without running it, so it holds no expression, no variable and no import.
+import type { GeneratedPithyConfig } from "./pithy-config";
+
+const config: GeneratedPithyConfig = {
+  origins: {
+    dev: "http://localhost:8787",
+    staging: null,
+    prod: null,
+  },
+  appScheme: "pithyapp",
+  universalLinkOrigin: null,
+  rails: {
+    ios: "apple",
+    android: "google",
+    web: "none",
+  },
+  google: {
+    webClientId: null,
+    iosClientId: null,
+  },
+  auth: {
+    dev: {
+      enabled: false,
+    },
+    staging: {
+      enabled: false,
+    },
+    prod: {
+      enabled: false,
+    },
+  },
+  i18n: {
+    dev: {
+      enabled: false,
+    },
+    staging: {
+      enabled: false,
+    },
+    prod: {
+      enabled: false,
+    },
+  },
+  payments: {
+    dev: {
+      enabled: false,
+    },
+    staging: {
+      enabled: false,
+    },
+    prod: {
+      enabled: false,
+    },
+  },
+  turnstile: {
+    dev: {
+      enabled: false,
+    },
+    staging: {
+      enabled: false,
+    },
+    prod: {
+      enabled: false,
+    },
+  },
+  consent: {
+    dev: {
+      enabled: false,
+    },
+    staging: {
+      enabled: false,
+    },
+    prod: {
+      enabled: false,
+    },
+  },
+};
+
+export default config;

package/templates/src/pithy-config.ts

@@ -0,0 +1,169 @@
+import type { AuthClientProjection } from "@pithy-sh/auth/src/client/projection";
+import type { ConsentClientProjection } from "@pithy-sh/consent/src/client/projection";
+import type { I18nClientProjection } from "@pithy-sh/i18n/src/client/projection";
+import type { PaymentsClientProjection } from "@pithy-sh/payments/src/client/projection";
+import type { PaymentsPlatformRails } from "@pithy-sh/payments/src/client/railChoice";
+import type { TurnstileClientProjection } from "@pithy-sh/turnstile/src/client/projection";
+import {
+  AUTH_DISABLED,
+  CONSENT_DISABLED,
+  I18N_DISABLED,
+  PAYMENTS_DISABLED,
+  TURNSTILE_DISABLED,
+} from "@pithy-sh/ui-core/src/config";
+import { Platform } from "react-native";
+import generated from "./pithy-config.generated";
+
+/** The environments a build can name. */
+export type AppEnvironment = "dev" | "staging" | "prod";
+
+/**
+ * One capability's projection in each environment, keyed like `origins`: `dev` always, `staging` and `prod` when the
+ * project deploys there. A sitekey or a catalog can differ between environments.
+ */
+export interface PerEnvironment<T> {
+  readonly dev: T;
+  readonly staging?: T;
+  readonly prod?: T;
+}
+
+/**
+ * What `pithy-config.generated.ts` holds: the Worker this app calls, the composed capabilities' projections in each
+ * environment, and the choices that are yours — the app's scheme, its universal-link origin, its Google client ids,
+ * and the rail each platform sells through. `pithy ui sync` rewrites the projections and keeps your choices.
+ */
+export interface GeneratedPithyConfig {
+  /**
+   * Where the Worker answers in each environment. A build calls the one `EXPO_PUBLIC_PITHY_ENV` names, `dev` when it
+   * is unset. `null` is an origin Pithy could not find; set it by hand. An environment the project does not deploy
+   * to is absent.
+   */
+  readonly origins: {
+    readonly dev: string;
+    readonly staging?: string | null;
+    readonly prod?: string | null;
+  };
+  /** The app's own URL scheme. A sign-in returns to a link on it. */
+  readonly appScheme: string;
+  /**
+   * The https origin whose links open the app, or `null` for none. A checkout in the system browser returns here,
+   * and so does a sign-in when it is set; with none, a sign-in returns on the app's scheme.
+   */
+  readonly universalLinkOrigin: string | null;
+  /** The rail each platform sells through. */
+  readonly rails: PaymentsPlatformRails;
+  /** The Google OAuth client ids native Google sign-in needs. Null turns it off. */
+  readonly google: { readonly webClientId: string | null; readonly iosClientId: string | null };
+  readonly auth: PerEnvironment<AuthClientProjection>;
+  readonly i18n: PerEnvironment<I18nClientProjection>;
+  readonly payments: PerEnvironment<PaymentsClientProjection>;
+  readonly turnstile: PerEnvironment<TurnstileClientProjection>;
+  readonly consent: PerEnvironment<ConsentClientProjection>;
+}
+
+const config: GeneratedPithyConfig = generated;
+
+/** Expo inlines `EXPO_PUBLIC_*` variables into the bundle when it builds, so this is read once, at build time. */
+declare const process: { readonly env: { readonly EXPO_PUBLIC_PITHY_ENV?: string } };
+
+/** The environment a build names in `EXPO_PUBLIC_PITHY_ENV`: `dev` when it names none. */
+export function appEnvironment(named: string | undefined): AppEnvironment {
+  if (named === undefined || named === "") return "dev";
+  if (named === "dev" || named === "staging" || named === "prod") return named;
+  throw new Error(`EXPO_PUBLIC_PITHY_ENV is "${named}". Build with dev, staging or prod.`);
+}
+
+/** The environment this build calls. */
+export const environment: AppEnvironment = appEnvironment(process.env.EXPO_PUBLIC_PITHY_ENV);
+
+/**
+ * The projection a build for `environment` reads. A file with none for it was written before the project deployed
+ * there: `pithy ui sync --app` writes one for each environment the project deploys to.
+ */
+export function projectionFor<T>(projections: PerEnvironment<T>, field: string, environment: AppEnvironment): T {
+  const found = projections[environment];
+  if (found === undefined) {
+    throw new Error(
+      `No ${field}.${environment} in src/pithy-config.generated.ts. Run pithy ui sync --app once the project deploys to ${environment}.`,
+    );
+  }
+  return found;
+}
+
+const auth = projectionFor(config.auth, "auth", environment);
+const turnstile = projectionFor(config.turnstile, "turnstile", environment);
+const payments = projectionFor(config.payments, "payments", environment);
+const i18n = projectionFor(config.i18n, "i18n", environment);
+const consent = projectionFor(config.consent, "consent", environment);
+
+/**
+ * The composed capabilities' client-safe config for this build's environment, narrowed once for the whole app.
+ *
+ * Each projection is a union on `enabled`: a capability the Worker does not compose projects `{ enabled: false }`
+ * and nothing else. Narrowing here, once, to the projection or `@pithy-sh/ui-core`'s defaults lets a screen read a
+ * field without a guard. The defaults keep the screens compiling when a capability is removed after the scaffold.
+ */
+export const authConfig = auth.enabled ? auth : AUTH_DISABLED;
+
+/** Turnstile's projection, narrowed the same way. `enabled` is false unless a login widget resolved. */
+export const turnstileConfig = turnstile.enabled ? turnstile : TURNSTILE_DISABLED;
+
+/**
+ * Payments' projection, narrowed the same way. Only the client-safe half of the catalog is here; every store
+ * credential stays in the Worker's secrets store.
+ */
+export const paymentsConfig = payments.enabled ? payments : PAYMENTS_DISABLED;
+
+/** The i18n projection, narrowed the same way. Locale metadata only; catalogs load per locale. */
+export const i18nConfig = i18n.enabled ? i18n : I18N_DISABLED;
+
+/** The i18n projection as the Worker composed it, for the hook that negotiates from it. */
+export const i18nProjection: I18nClientProjection = i18n;
+
+/** Consent's projection, narrowed the same way. The consent screen and the transport call under its base path. */
+export const consentConfig = consent.enabled ? consent : CONSENT_DISABLED;
+
+/** A host that is this machine. */
+const LOOPBACK = /^(https?:\/\/)(localhost|127\.0\.0\.1)(:\d+)?$/;
+
+/**
+ * The origin a build calls. An Android emulator is a machine of its own, and reaches this one's loopback at
+ * `10.0.2.2`. A device on your network reaches neither: set `origins.dev` to this machine's network address.
+ * The web build calls relative paths from the Worker's own origin, so it needs none: `""` when none is set.
+ */
+export function originFor(
+  origins: GeneratedPithyConfig["origins"],
+  environment: AppEnvironment,
+  platform: string,
+): string {
+  const found = origins[environment];
+  if (found === undefined || found === null) {
+    if (platform === "web") return "";
+    throw new Error(
+      `No origin for ${environment}. Set origins.${environment} in src/pithy-config.generated.ts to the Worker's address there.`,
+    );
+  }
+  // A phone sends its bearer credential to this origin, so a deployed one is https.
+  if (platform !== "web" && environment !== "dev" && !found.startsWith("https://")) {
+    throw new Error(
+      `origins.${environment} is ${found}. Set it to the Worker's https address in src/pithy-config.generated.ts.`,
+    );
+  }
+  if (platform !== "android") return found;
+  return found.replace(LOOPBACK, (_match, scheme: string, _host: string, port = "") => `${scheme}10.0.2.2${port}`);
+}
+
+/** The Worker's absolute origin in that environment. Every request on a phone goes here. */
+export const origin: string = originFor(config.origins, environment, Platform.OS);
+
+/** The app's own URL scheme. */
+export const appScheme: string = config.appScheme;
+
+/** The https origin whose links open the app, or `null` when the app claims none. */
+export const universalLinkOrigin: string | null = config.universalLinkOrigin;
+
+/** The rail each platform sells through. */
+export const platformRails: PaymentsPlatformRails = config.rails;
+
+/** The Google OAuth client ids native Google sign-in needs. */
+export const googleClientIds: GeneratedPithyConfig["google"] = config.google;

package/templates/src/pithy-locale.tsx

@@ -0,0 +1,90 @@
+import type { MessageCatalog } from "@pithy-sh/core/src/i18n/catalog";
+import { nativeLocaleEnvironment } from "@pithy-sh/i18n/src/native/environment";
+import { TranslatorProvider, useTranslator } from "@pithy-sh/i18n/src/react/translator";
+import { useNegotiatedLocale } from "@pithy-sh/i18n/src/react/useNegotiatedLocale";
+import { createContext, type ReactNode, useContext, useMemo } from "react";
+import { Text, View } from "react-native";
+import { i18nProjection } from "./pithy-config";
+import { onDevice } from "./platform";
+import { useTheme } from "./theme";
+
+/**
+ * The language the app is in, negotiated once and rendered by every screen under it.
+ *
+ * On a phone the starting point is the device's own languages, through `expo-localization`, and the app follows a
+ * change while it runs; a choice is remembered in AsyncStorage, since a language is not a secret. Direction goes
+ * through `I18nManager`, which React Native applies only after a reload, so when the language in force lays out
+ * the other way the app says so rather than flip half a layout. On the web it is the browser's languages and the
+ * document's `lang` and `dir`, exactly as the React screens negotiate.
+ *
+ * With no i18n capability composed it renders its children untouched, and every screen reads the English it was
+ * scaffolded with.
+ */
+
+/** Which platform's signals and memory the negotiation uses. A module constant: the hook needs the same one every render. */
+const environment = onDevice() ? nativeLocaleEnvironment : undefined;
+
+/** The language in force and how to choose another, for a language picker of your own. */
+export interface LocaleChoice {
+  /** The catalog locale in force. */
+  readonly locale: string;
+  /** Choose a language the project supports. Remembered on this device. */
+  readonly choose: (locale: string) => void;
+}
+
+const LocaleChoiceContext = createContext<LocaleChoice>({ locale: "en", choose: () => undefined });
+
+/** The language in force and how to choose another. */
+export function useLocaleChoice(): LocaleChoice {
+  return useContext(LocaleChoiceContext);
+}
+
+/** What {@link PithyLocale} takes: the app, and your own catalogs if you have any. */
+export interface PithyLocaleProps {
+  readonly children: ReactNode;
+  /**
+   * Your own catalogs, keyed by locale: the top layer, above the kit's translation and each screen's English. A
+   * sentence you want said differently goes here, and so do the words for a language the kit writes nothing in.
+   */
+  readonly messages?: Readonly<Record<string, MessageCatalog | undefined>>;
+}
+
+const EN = {
+  "app/locale.reload_required": "Restart the app to finish changing the language.",
+} satisfies MessageCatalog;
+
+/** The line a reader sees when the language in force needs a restart to lay out the right way round. */
+function ReloadNotice(): ReactNode {
+  const t = useTranslator(EN);
+  const theme = useTheme();
+  return (
+    <View
+      role="alert"
+      style={{
+        padding: theme.spacing.md,
+        backgroundColor: theme.colors.surface,
+        borderBottomWidth: 1,
+        borderBottomColor: theme.colors.border,
+      }}
+    >
+      <Text style={[theme.type.caption, { color: theme.colors.text }]}>{t.t("app/locale.reload_required")}</Text>
+    </View>
+  );
+}
+
+/** Mount the negotiated locale over the app. Until the catalog lands, screens render their own English. */
+export function PithyLocale({ children, messages }: PithyLocaleProps): ReactNode {
+  const negotiated = useNegotiatedLocale(i18nProjection, { messages, environment });
+  const choice = useMemo(
+    () => ({ locale: negotiated.locale, choose: negotiated.choose }),
+    [negotiated.locale, negotiated.choose],
+  );
+  const body = (
+    <LocaleChoiceContext value={choice}>
+      {negotiated.reloadRequired ? <ReloadNotice /> : null}
+      {children}
+    </LocaleChoiceContext>
+  );
+  if (negotiated.source === null) return body;
+  return <TranslatorProvider value={negotiated.source}>{body}</TranslatorProvider>;
+}

package/templates/src/platform.ts

@@ -0,0 +1,111 @@
+import * as Linking from "expo-linking";
+import * as WebBrowser from "expo-web-browser";
+import { Platform } from "react-native";
+
+/**
+ * The few things a screen needs from the platform that React Native does not answer the same way everywhere.
+ *
+ * **Query strings and links are read by hand here, not with `URL` or `URLSearchParams`.** React Native ships both
+ * names, but its `URL` does not parse and its `URLSearchParams` cannot read a value back, so code that works in a
+ * browser and in a test throws on a phone. Everything in this file is plain string work that answers the same on
+ * all three platforms.
+ */
+
+/** The platform a device registers as with the Worker. Anything React Native names other than a phone is the web. */
+export function devicePlatform(): "ios" | "android" | "web" {
+  if (Platform.OS === "ios" || Platform.OS === "android") return Platform.OS;
+  return "web";
+}
+
+/** True on a phone, where there is no page origin and no cookie: the session is a bearer credential. */
+export function onDevice(): boolean {
+  return devicePlatform() !== "web";
+}
+
+/** One percent-encoded query component, decoded; a malformed escape keeps its raw text rather than throwing. */
+function decodeComponent(value: string): string {
+  const spaced = value.replace(/\+/g, " ");
+  try {
+    return decodeURIComponent(spaced);
+  } catch {
+    return spaced;
+  }
+}
+
+/**
+ * A query string as name to value: `"?email=ada%40example.com"` gives `{ email: "ada@example.com" }`. The leading
+ * `?` is optional. The first value of a repeated name wins, as `URLSearchParams.get` answers.
+ */
+export function parseQuery(search: string): Record<string, string> {
+  const params: Record<string, string> = {};
+  const query = search.startsWith("?") ? search.slice(1) : search;
+  for (const pair of query.split("&")) {
+    if (pair === "") continue;
+    const split = pair.indexOf("=");
+    const name = decodeComponent(split === -1 ? pair : pair.slice(0, split));
+    const value = split === -1 ? "" : decodeComponent(pair.slice(split + 1));
+    if (!(name in params)) params[name] = value;
+  }
+  return params;
+}
+
+/** One parameter of a query string, decoded, or `null` when the name is absent. */
+export function searchParam(search: string, name: string): string | null {
+  return parseQuery(search)[name] ?? null;
+}
+
+/** A query string from name to value, with its `?`, or the empty string when there is nothing to write. */
+export function queryString(params: Readonly<Record<string, string>>): string {
+  const pairs = Object.entries(params).map(
+    ([name, value]) => `${encodeURIComponent(name)}=${encodeURIComponent(value)}`,
+  );
+  return pairs.length === 0 ? "" : `?${pairs.join("&")}`;
+}
+
+/** A link split into its parts. `search` keeps its `?`, and is empty when there is none; the fragment is dropped. */
+export interface ParsedLink {
+  /** The scheme, lower-cased: `https`, or the app's own. */
+  readonly scheme: string;
+  /** What follows `//` up to the path: a host, or the first word of a custom-scheme link. */
+  readonly host: string;
+  /** The path, starting with `/`, or empty. */
+  readonly path: string;
+  /** The query, starting with `?`, or empty. */
+  readonly search: string;
+}
+
+/**
+ * Split `myapp://callback?code=…` or `https://app.example.com/return?session=…` into its parts, or answer `null`
+ * for anything that is not `scheme://…`.
+ */
+export function parseLink(link: string): ParsedLink | null {
+  const match = /^([a-zA-Z][a-zA-Z0-9+.-]*):\/\/([^/?#]*)([^?#]*)(\?[^#]*)?/.exec(link);
+  if (!match) return null;
+  return {
+    scheme: (match[1] ?? "").toLowerCase(),
+    host: match[2] ?? "",
+    path: match[3] ?? "",
+    search: match[4] ?? "",
+  };
+}
+
+/**
+ * The app's own deep link to `path`, in the scheme this build answers to. A development build has a scheme of its
+ * own, so the link is asked of `expo-linking` rather than written from the configured scheme.
+ */
+export function appLink(path: string): string {
+  return Linking.createURL(path);
+}
+
+/**
+ * Open an http or https page outside the app: the system browser on a phone, where a checkout or a store page
+ * must not run inside the app's own view, and a new tab on the web. Any other scheme is refused, so an address a
+ * response carried cannot run script or open another app. `false` when it was refused.
+ */
+export async function openExternal(url: string): Promise<boolean> {
+  const scheme = parseLink(url)?.scheme;
+  if (scheme !== "https" && scheme !== "http") return false;
+  if (onDevice()) await WebBrowser.openBrowserAsync(url);
+  else await Linking.openURL(url);
+  return true;
+}

package/templates/src/route-modules.ts

@@ -0,0 +1,76 @@
+import type { RouteModule } from "@pithy-sh/ui-core/src/routes";
+
+/**
+ * ─────────────────────────────────────────────────────────────────────────────
+ * The contexts below ARE the route registration. Do not edit them.
+ *
+ *   src/routes/pithy/   Pithy's screens. Pithy writes only here, and only files that do not exist.
+ *   src/routes/app/     Yours. Pithy never writes here.
+ *
+ * Dropping a file in registers it: no manifest, no command to re-run. Each module declares its own path, so
+ * filenames encode no routing rules:
+ *
+ *   export const path = "/sign-in";
+ *   export default SignIn;
+ *
+ * `app/` wins on a conflict: override a Pithy screen by putting your own file at the same path.
+ *
+ * `require.context` is Metro's directory import, the one `expo-router` itself registers screens with. Its
+ * arguments must be literals, because Metro reads them while it bundles. Both contexts read `src/routes/`, which
+ * your home screen keeps on disk, and pick their folder by filter: a directory Metro cannot find fails the
+ * bundle, and an app with no Pithy screens has no `src/routes/pithy/`. The filter also keeps co-located tests
+ * out of the bundle: `home.test.tsx` beside `home.tsx` would otherwise ship, fixtures and stub tokens included.
+ * ─────────────────────────────────────────────────────────────────────────────
+ */
+
+/** A directory Metro has read: its file names, and a module by name. */
+interface ModuleContext {
+  keys(): string[];
+  (id: string): unknown;
+}
+
+declare const require: {
+  context(path: string, recursive: boolean, filter: RegExp, mode: "sync"): ModuleContext;
+};
+
+/** One loader per file in `context`, in a stable order. */
+export function contextLoaders<T>(context: ModuleContext): (() => Promise<T>)[] {
+  return context
+    .keys()
+    .sort()
+    .map((key) => async () => context(key) as T);
+}
+
+/** Pithy's screens. */
+export const pithyRoutes = contextLoaders<RouteModule>(
+  require.context("./routes", true, /^\.\/pithy\/(?!.*\.(?:test|spec)\.tsx$).*\.tsx$/, "sync"),
+);
+
+/** Your screens. Registered after Pithy's, so one at the same path takes it over. */
+export const appRoutes = contextLoaders<RouteModule>(
+  require.context("./routes", true, /^\.\/app\/(?!.*\.(?:test|spec)\.tsx$).*\.tsx$/, "sync"),
+);
+
+/**
+ * The session module, when the auth screens were written: the router's sign-in guard asks it. Read through a
+ * context rather than imported, so this file is the same with or without it.
+ */
+export const sessionModule: (() => Promise<{ getSession: () => Promise<unknown> }>) | undefined = contextLoaders<{
+  getSession: () => Promise<unknown>;
+}>(require.context("./", false, /^\.\/session\.tsx$/, "sync"))[0];
+
+/** The payments module, when the payments screens were written: the router's entitlement guard asks it. */
+export const paymentsModule: (() => Promise<{ holdsEntitlement: (key: string) => Promise<boolean> }>) | undefined =
+  contextLoaders<{ holdsEntitlement: (key: string) => Promise<boolean> }>(
+    require.context("./", false, /^\.\/payments\.tsx$/, "sync"),
+  )[0];
+
+/**
+ * The store listener the payments screens ship, when they were written: the root layout mounts it for the whole
+ * run. Read synchronously, because a hook has to be there on the first render.
+ */
+export const storeTransactions: (() => void) | undefined = (() => {
+  const context = require.context("./", false, /^\.\/useStoreTransactions\.ts$/, "sync");
+  const key = context.keys()[0];
+  return key === undefined ? undefined : (context(key) as { useStoreTransactions: () => void }).useStoreTransactions;
+})();