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

package/templates/src/routes/pithy/invitation.tsx

@@ -0,0 +1,239 @@
+import type { MessageCatalog } from "@pithy-sh/core/src/i18n/catalog";
+import { useTranslator } from "@pithy-sh/i18n/src/react/translator";
+import {
+  acceptInvitation,
+  chooseOrganization,
+  type InvitationOffer,
+  readInvitation,
+} from "@pithy-sh/organization/src/client/api";
+import { organizationRefusal } from "@pithy-sh/organization/src/client/lifecycle";
+import { useAction } from "@pithy-sh/ui-core/src/action";
+import { useRead } from "@pithy-sh/ui-core/src/read";
+import { type ScreenProps, screenPath } from "@pithy-sh/ui-core/src/routes";
+import { type ReactNode, useState } from "react";
+import { Pressable, Text, View } from "react-native";
+import { queryString } from "../../platform";
+import { Redirect, routeTable } from "../../router";
+import { getSession, RESUME_PARAM } from "../../session";
+import { type Theme, useTheme } from "../../theme";
+import { transport } from "../../transport";
+
+/**
+ * Where an invitation link lands. Change this if `organization({ invitationAcceptPath })` does: the link in every
+ * invitation email is that path with the token appended as one segment. On a phone the link reaches this screen
+ * when the app answers it as a universal link or an app link.
+ */
+export const path = "/invitations/:token";
+
+// Pithy's screen. Yours to override: put your own file at this path under src/routes/app/ and it wins.
+//
+// **Anybody holding the link sees the offer; only the invited address can take it.** Reading an offer is public, so
+// a stranger sees what they were invited to before being asked to sign in, and comes back here once they have.
+// Accepting is checked by the server against the signed-in address, so a forwarded link does nothing for whoever it
+// was forwarded to.
+//
+// **One refusal, one sentence.** An unknown link, a spent one, a withdrawn one, an expired one and one sent to a
+// different address all come back as the same code, on purpose: telling them apart tells whoever holds the link the
+// same thing. The screen says all of it at once rather than guessing which.
+//
+// **Joining does not change the account in force.** The server writes the membership and stops. This screen then
+// makes the account you joined the one you act in, and leaves remounting every screen, for the chooser's reason:
+// nothing the previous account's data put on a screen may survive the switch.
+const EN = {
+  "organization/invitation.title": "Join {organization}",
+  "organization/invitation.invited_by": "{inviter} invited you as {role}.",
+  "organization/invitation.invited": "You're invited as {role}.",
+  "organization/invitation.expires": "The invitation expires on {date}.",
+  "organization/invitation.as": "You'll join as {email}.",
+  "organization/invitation.accept": "Join",
+  "organization/invitation.sign_in": "Sign in to accept",
+  "organization/invitation.invalid.title": "This invitation can't be used.",
+  "organization/invitation.invalid.body":
+    "It has expired, been used or withdrawn, or was sent to a different address. Ask whoever invited you for a new one.",
+  "organization/invitation.failed": "We couldn't load this invitation.",
+  "organization/invitation.join_failed": "We couldn't finish joining.",
+  "organization/invitation.retry": "Try again",
+} satisfies MessageCatalog;
+
+/** Where to go once the account you joined is in force. The chooser's destination, for the chooser's reason. */
+const DESTINATION = "/";
+
+/** What arriving with a link comes to: the offer, a link that can no longer be used, or a read that failed. */
+type Arrival =
+  | { kind: "offer"; offer: InvitationOffer; email: string | null; signIn: string | null }
+  | { kind: "invalid" }
+  | { kind: "failed" };
+
+/**
+ * What pressing "Join" comes to. `joined` on a failure is the account already joined, so trying again records the
+ * choice rather than spending an invitation that is already spent.
+ */
+type Joining =
+  | { kind: "leave"; to: string; load: boolean }
+  | { kind: "invalid" }
+  | { kind: "failed"; joined: string | null };
+
+const INVITATION_INVALID = "organization/invitation_invalid";
+
+/** This screen's own address for `token`, which is where a sign-in comes back to. */
+function ownPath(token: string): string {
+  return path.replace(":token", encodeURIComponent(token));
+}
+
+async function arrive(token: string): Promise<Arrival> {
+  const [offer, session] = await Promise.all([readInvitation(token, transport.organization), getSession()]);
+  if (!offer.ok) return offer.failure.code === INVITATION_INVALID ? { kind: "invalid" } : { kind: "failed" };
+  if (session !== null) return { kind: "offer", offer: offer.value, email: session.user.email, signIn: null };
+  const signIn = `${screenPath(await routeTable(), "sign-in")}${queryString({ [RESUME_PARAM]: ownPath(token) })}`;
+  return { kind: "offer", offer: offer.value, email: null, signIn };
+}
+
+/** Accept, unless that already happened, then make the account joined the one in force. */
+async function join(token: string, joined: string | null): Promise<Joining> {
+  let organizationId = joined;
+  if (organizationId === null) {
+    const accepted = await acceptInvitation(token, transport.organization);
+    if (!accepted.ok) {
+      return accepted.failure.code === INVITATION_INVALID ? { kind: "invalid" } : { kind: "failed", joined: null };
+    }
+    organizationId = accepted.value.organizationId;
+  }
+  const chosen = await chooseOrganization(organizationId, transport.organization);
+  if (chosen.ok) return { kind: "leave", to: DESTINATION, load: true };
+  if (organizationRefusal(chosen.failure.code) === "suspended") {
+    return { kind: "leave", to: screenPath(await routeTable(), "organization-suspended"), load: false };
+  }
+  return { kind: "failed", joined: organizationId };
+}
+
+export default function Invitation({ params }: ScreenProps<typeof path>): ReactNode {
+  const t = useTranslator(EN);
+  const theme = useTheme();
+  const token = params.token;
+  const arrival = useRead(`invitation:${token}`, () => arrive(token));
+  const joining = useAction((_signal: AbortSignal, joined: string | null) => join(token, joined));
+  const [signingIn, setSigningIn] = useState(false);
+
+  const answer = arrival.loading ? undefined : arrival.value;
+  const result = joining.value;
+  const screen = {
+    flex: 1,
+    padding: theme.spacing.lg,
+    gap: theme.spacing.md,
+    backgroundColor: theme.colors.background,
+  };
+
+  if (result?.kind === "leave") return <Redirect to={result.to} load={result.load} />;
+  if (signingIn && answer?.kind === "offer" && answer.signIn !== null) return <Redirect to={answer.signIn} />;
+
+  if (answer?.kind === "invalid" || result?.kind === "invalid") {
+    return (
+      <View style={screen}>
+        <Text role="heading" style={[theme.type.title, { color: theme.colors.text }]}>
+          {t.t("organization/invitation.invalid.title")}
+        </Text>
+        <Text style={[theme.type.body, { color: theme.colors.muted }]}>
+          {t.t("organization/invitation.invalid.body")}
+        </Text>
+      </View>
+    );
+  }
+
+  if (result?.kind === "failed") {
+    return (
+      <View style={screen}>
+        <Text style={[theme.type.body, { color: theme.colors.text }]}>
+          {t.t("organization/invitation.join_failed")}
+        </Text>
+        <Button
+          theme={theme}
+          disabled={joining.pending}
+          onPress={() => void joining.run(result.joined)}
+          label={t.t("organization/invitation.retry")}
+        />
+      </View>
+    );
+  }
+
+  if (answer?.kind === "failed" || (answer === undefined && arrival.failure !== null && !arrival.loading)) {
+    return (
+      <View style={screen}>
+        <Text style={[theme.type.body, { color: theme.colors.text }]}>{t.t("organization/invitation.failed")}</Text>
+        <Button theme={theme} onPress={arrival.refresh} label={t.t("organization/invitation.retry")} />
+      </View>
+    );
+  }
+
+  if (answer === undefined) return <View style={screen} />;
+  const { offer, email } = answer;
+  return (
+    <View style={screen}>
+      <Text role="heading" style={[theme.type.title, { color: theme.colors.text }]}>
+        {t.t("organization/invitation.title", { organization: offer.organizationName })}
+      </Text>
+      <Text style={[theme.type.body, { color: theme.colors.muted }]}>
+        {offer.inviterName === null
+          ? t.t("organization/invitation.invited", { role: offer.role })
+          : t.t("organization/invitation.invited_by", { inviter: offer.inviterName, role: offer.role })}
+      </Text>
+      <Text style={[theme.type.body, { color: theme.colors.muted }]}>
+        {t.t("organization/invitation.expires", {
+          date: t.formatDate(new Date(offer.expiresAt), { dateStyle: "long" }),
+        })}
+      </Text>
+      {email === null ? (
+        <Button
+          theme={theme}
+          primary
+          onPress={() => setSigningIn(true)}
+          label={t.t("organization/invitation.sign_in")}
+        />
+      ) : (
+        <>
+          <Text style={[theme.type.body, { color: theme.colors.text }]}>
+            {t.t("organization/invitation.as", { email })}
+          </Text>
+          <Button
+            theme={theme}
+            primary
+            disabled={joining.pending}
+            onPress={() => void joining.run(null)}
+            label={t.t("organization/invitation.accept")}
+          />
+        </>
+      )}
+    </View>
+  );
+}
+
+/** One button: the accent for the action the screen wants taken, a bordered surface for a retry. */
+function Button(props: {
+  theme: Theme;
+  label: string;
+  onPress: () => void;
+  disabled?: boolean;
+  primary?: boolean;
+}): ReactNode {
+  const { theme } = props;
+  return (
+    <Pressable
+      role="button"
+      disabled={props.disabled}
+      onPress={props.onPress}
+      style={{
+        alignSelf: "flex-start",
+        borderWidth: 1,
+        borderColor: props.primary ? theme.colors.accent : theme.colors.border,
+        borderRadius: theme.radius,
+        backgroundColor: props.primary ? theme.colors.accent : theme.colors.surface,
+        paddingVertical: theme.spacing.sm,
+        paddingHorizontal: theme.spacing.md,
+        opacity: props.disabled ? 0.6 : 1,
+      }}
+    >
+      <Text style={[theme.type.button, { color: props.primary ? theme.colors.onAccent : theme.colors.text }]}>
+        {props.label}
+      </Text>
+    </Pressable>
+  );
+}

package/templates/src/routes/pithy/organization-suspended.tsx

@@ -0,0 +1,51 @@
+import type { MessageCatalog } from "@pithy-sh/core/src/i18n/catalog";
+import { useTranslator } from "@pithy-sh/i18n/src/react/translator";
+import type { ReactNode } from "react";
+import { Text, View } from "react-native";
+import { Link } from "../../router";
+import { useTheme } from "../../theme";
+
+export const path = "/organization-suspended";
+
+// Where somebody is sent when the organization they act for is suspended, and their own account is not.
+export const role = "organization-suspended";
+
+// Pithy's screen. Yours to override: put your own file at this path under src/routes/app/ and it wins.
+//
+// **Arrived at from a refusal, by role.** A member's request to act in a suspended organization is refused with
+// `organization/organization_suspended`, and the chooser sends them here when every account they belong to is
+// suspended, or when the account they picked was suspended after the list was drawn. Your own screens do the same
+// with `organizationRefusal` from `@pithy-sh/organization/src/client/lifecycle`. Like the other two it names nobody:
+// the organization's owners were told why, so they are who to ask.
+
+/** This screen's English, baked in — the only catalog that survives being copied into your repository. */
+const EN = {
+  "organization/suspended.title": "This organization is suspended.",
+  "organization/suspended.body": "Nobody can use it until it is reinstated. Your own account is not affected.",
+  "organization/suspended.contact": "Its owners were told why. Ask one of them.",
+  "organization/suspended.home": "Go home",
+} satisfies MessageCatalog;
+
+/**
+ * Where "home" is. The app's root, and deliberately not a `ScreenRole`: nothing guards its way there. An
+ * adopter whose home is elsewhere changes this line, which is the one edit a copied screen is for.
+ */
+const HOME = "/";
+
+export default function OrganizationSuspended(): ReactNode {
+  const t = useTranslator(EN);
+  const theme = useTheme();
+
+  return (
+    <View
+      style={{ flex: 1, padding: theme.spacing.lg, gap: theme.spacing.md, backgroundColor: theme.colors.background }}
+    >
+      <Text role="heading" style={[theme.type.title, { color: theme.colors.text }]}>
+        {t.t("organization/suspended.title")}
+      </Text>
+      <Text style={[theme.type.body, { color: theme.colors.text }]}>{t.t("organization/suspended.body")}</Text>
+      <Text style={[theme.type.body, { color: theme.colors.muted }]}>{t.t("organization/suspended.contact")}</Text>
+      <Link to={HOME}>{t.t("organization/suspended.home")}</Link>
+    </View>
+  );
+}

package/templates/src/routes/pithy/otp.tsx

@@ -0,0 +1,223 @@
+import { sendOtp, signInWithOtp } from "@pithy-sh/auth/src/client/api";
+import type { MessageCatalog } from "@pithy-sh/core/src/i18n/catalog";
+import { useTranslator } from "@pithy-sh/i18n/src/react/translator";
+import { screenPath } from "@pithy-sh/ui-core/src/routes";
+import { type ReactNode, useCallback, useRef, useState } from "react";
+import { Pressable, Text, TextInput, View } from "react-native";
+import { authConfig } from "../../pithy-config";
+import { parseQuery, queryString } from "../../platform";
+import { Redirect, routeTable, useGo, usePath, useSearch, useSearchParam } from "../../router";
+import {
+  adoptSignIn,
+  afterSignIn,
+  heldOtpAddress,
+  holdOtpAddress,
+  refusedAccountScreen,
+  releaseOtpAddress,
+  resumeQuery,
+} from "../../session";
+import { type Theme, useTheme } from "../../theme";
+import { transport } from "../../transport";
+import { Turnstile, turnstilePending, turnstileRequest } from "../../turnstile";
+
+export const path = "/otp";
+
+// Pithy's screen. Yours to override: put your own file at this path under src/routes/app/ and it wins.
+//
+// **The sign-in screen sends people here on a phone with no universal link.** It offers one way in, and there that
+// is a code: the Worker hands a magic link only to an https link, since any app can claim a custom scheme. With
+// `universalLinkOrigin` set, the sign-in screen mails a link instead and nothing sends anyone here. To send a code
+// from your own screen, hand it the address and go here: `holdOtpAddress(email); go("/otp")`.
+//
+// **The address is never in the URL.** A path or a query string is written to every request log between the
+// browser and the Worker, so `holdOtpAddress` keeps it in memory and in this tab's session storage. A reload keeps
+// it. A new tab, a bookmark or a link somebody else opens has none, and goes back to sign-in, since a code cannot be
+// checked without the address it was sent to. An older link carrying `?email=` is read once, held, and dropped from
+// the address bar.
+
+/**
+ * This screen's English, baked in: the only catalog that survives being copied into your repository.
+ *
+ * The digit count is a real count, so it goes through `plural`: `otpLength` is configurable, and a locale with more
+ * than two plural forms cannot say "digits" correctly from one string.
+ */
+const EN = {
+  "auth/otp.title": "Enter the code.",
+  "auth/otp.sent.one": "We sent {count} digit to {email}.",
+  "auth/otp.sent.other": "We sent {count} digits to {email}.",
+  "auth/otp.inbox": "your inbox",
+  "auth/otp.failed": "That code didn't work. Try again, or send a new one.",
+  "auth/otp.submit": "Sign in",
+  "auth/otp.resend": "Send a new code",
+} satisfies MessageCatalog;
+
+function Button(props: {
+  label: string;
+  onPress: () => void;
+  disabled: boolean;
+  primary?: boolean;
+  theme: Theme;
+}): ReactNode {
+  const { theme } = props;
+  return (
+    <Pressable
+      role="button"
+      disabled={props.disabled}
+      onPress={props.onPress}
+      style={{
+        borderWidth: 1,
+        borderColor: props.primary ? theme.colors.accent : theme.colors.border,
+        backgroundColor: props.primary ? theme.colors.accent : "transparent",
+        borderRadius: theme.radius,
+        paddingVertical: theme.spacing.sm,
+        paddingHorizontal: theme.spacing.md,
+        alignItems: "center",
+        opacity: props.disabled ? 0.5 : 1,
+      }}
+    >
+      <Text style={[theme.type.button, { color: props.primary ? theme.colors.onAccent : theme.colors.text }]}>
+        {props.label}
+      </Text>
+    </Pressable>
+  );
+}
+
+export default function Otp(): ReactNode {
+  const t = useTranslator(EN);
+  const theme = useTheme();
+  const go = useGo();
+  const search = useSearch();
+  const path = usePath();
+  const carried = useSearchParam("email");
+  const [email] = useState(() => {
+    if (carried) holdOtpAddress(carried);
+    return carried || heldOtpAddress() || "";
+  });
+  const length = authConfig.otpLength;
+  const [digits, setDigits] = useState<string[]>(() => Array.from({ length }, () => ""));
+  const [captcha, setCaptcha] = useState<string | null>(null);
+  const [error, setError] = useState(false);
+  const [busy, setBusy] = useState(false);
+  const inputs = useRef<(TextInput | null)[]>([]);
+  const onToken = useCallback((value: string | null) => setCaptcha(value), []);
+
+  const code = digits.join("");
+
+  // One digit per box. A whole code arriving in one box, from the keyboard's one-time-code suggestion or a paste,
+  // is spread across the row from there.
+  function setDigit(index: number, value: string): void {
+    const typed = value.replace(/\D/g, "");
+    const spread = typed.length > 1 ? typed.slice(0, length - index) : typed.slice(-1);
+    setDigits((current) =>
+      current.map((existing, position) => {
+        if (spread === "") return position === index ? "" : existing;
+        const offset = position - index;
+        return offset >= 0 && offset < spread.length ? (spread[offset] ?? existing) : existing;
+      }),
+    );
+    const next = index + Math.max(spread.length, 1);
+    if (spread !== "" && next < length) inputs.current[next]?.focus();
+  }
+
+  // Both calls take the transport's options and name nothing about it: on a phone they go to the Worker's origin
+  // with the device's headers, on the web they carry the page's cookie.
+  async function verify(): Promise<void> {
+    setBusy(true);
+    setError(false);
+    const result = await signInWithOtp({ email, otp: code }, transport.auth);
+    const held = result.ok && (await adoptSignIn(result.value));
+    setBusy(false);
+    if (held) {
+      releaseOtpAddress();
+      // A sign-in a screen or an application's authorization sent somebody to resumes it, or goes home.
+      const next = await afterSignIn(search);
+      if (next !== null) go(next);
+      return;
+    }
+    // A right code for an account that may not act is refused with what happened to it, not as a wrong code, and
+    // goes on to the screen for that state, by role.
+    const refused = result.ok ? null : refusedAccountScreen(result.failure.code);
+    if (refused) return go(screenPath(await routeTable(), refused));
+    setError(true);
+  }
+
+  async function resend(): Promise<void> {
+    // The gate goes on the send route and not on the verify one, which is where `@pithy-sh/auth` stacks the
+    // humanity check: a code that was already mailed is not a surface worth challenging.
+    await sendOtp({ email, type: "sign-in" }, { ...transport.auth, gate: (body) => turnstileRequest(body, captcha) });
+  }
+
+  if (carried !== null) {
+    const { email: _dropped, ...rest } = parseQuery(search);
+    return <Redirect to={`${path}${queryString(rest)}`} replace />;
+  }
+  if (!email) {
+    const resume = resumeQuery(search);
+    return <Redirect screen="sign-in" replace {...(resume ? { search: resume.slice(1) } : {})} />;
+  }
+
+  return (
+    <View
+      style={{ flex: 1, padding: theme.spacing.lg, gap: theme.spacing.md, backgroundColor: theme.colors.background }}
+    >
+      <Text role="heading" style={[theme.type.title, { color: theme.colors.text }]}>
+        {t.t("auth/otp.title")}
+      </Text>
+      <Text style={[theme.type.body, { color: theme.colors.muted }]}>
+        {t.plural("auth/otp.sent", length, { email: email || t.t("auth/otp.inbox") })}
+      </Text>
+
+      <View style={{ flexDirection: "row", gap: theme.spacing.sm }}>
+        {digits.map((digit, index) => (
+          <TextInput
+            // The inputs are a fixed-length positional row; the position is the identity.
+            // biome-ignore lint/suspicious/noArrayIndexKey: position is the identity here
+            key={index}
+            ref={(element) => {
+              inputs.current[index] = element;
+            }}
+            value={digit}
+            onChangeText={(value) => setDigit(index, value)}
+            keyboardType="number-pad"
+            inputMode="numeric"
+            textContentType="oneTimeCode"
+            autoComplete="one-time-code"
+            style={[
+              theme.type.title,
+              {
+                width: 44,
+                height: 56,
+                textAlign: "center",
+                borderWidth: 1,
+                borderColor: theme.colors.border,
+                borderRadius: theme.radius,
+                backgroundColor: theme.colors.surface,
+                color: theme.colors.text,
+              },
+            ]}
+          />
+        ))}
+      </View>
+
+      {error && <Text style={[theme.type.body, { color: theme.colors.danger }]}>{t.t("auth/otp.failed")}</Text>}
+
+      <View style={{ gap: theme.spacing.sm }}>
+        <Button
+          label={t.t("auth/otp.submit")}
+          primary
+          disabled={busy || code.length < length}
+          onPress={() => void verify()}
+          theme={theme}
+        />
+        {/* Resending goes back through the gated send route, so the widget belongs here too. */}
+        <Turnstile onToken={onToken} />
+        <Button
+          label={t.t("auth/otp.resend")}
+          disabled={busy || turnstilePending(captcha)}
+          onPress={() => void resend()}
+          theme={theme}
+        />
+      </View>
+    </View>
+  );
+}