@pithy-sh/ui-react 0.1.0

package/templates/src/routes/app/home.bare.tsx

@@ -0,0 +1,96 @@
+import type { MessageCatalog } from "@pithy-sh/core/src/i18n/catalog";
+import type { Translator } from "@pithy-sh/core/src/i18n/translator";
+import { HEALTH_PATH } from "@pithy-sh/core/src/worker/health";
+import { useTranslator } from "@pithy-sh/i18n/src/react/translator";
+import { useEffect, useState } from "react";
+
+// Your screen. Pithy wrote this file once and never will again — everything under src/routes/app/ is
+// yours. Add a screen by dropping a file in beside it with its own `path` export.
+export const path = "/";
+
+/** What the health route answers. Every Pithy worker serves it. */
+interface Health {
+  status: string;
+}
+
+function isHealth(value: unknown): value is Health {
+  return typeof value === "object" && value !== null && typeof (value as { status?: unknown }).status === "string";
+}
+
+/**
+ * This screen's English, baked in. Yours, like the rest of the file.
+ *
+ * The three statuses are keys rather than the strings themselves, because two of them are this screen's
+ * own words and not the worker's: `checking` is what it says before the answer arrives, and `unknown`
+ * and `unreachable` are what it says when there is no answer to render. What the worker actually
+ * returns — `ok` — is its value and is shown verbatim.
+ */
+const EN = {
+  "app/home.bare.title": "It runs.",
+  "app/home.bare.body": "The worker says: {status}.",
+  "app/home.bare.checking": "checking",
+  "app/home.bare.unknown": "unknown",
+  "app/home.bare.unreachable": "unreachable",
+} satisfies MessageCatalog;
+
+/**
+ * What the health check came back with: the worker's own word, or one of this screen's two faults.
+ *
+ * A union rather than a rendered string, because only one of the three is translatable. `ok` is the
+ * worker's value and is shown verbatim in every language; `unknown` and `unreachable` are this
+ * screen's own words and come from the catalog. Storing the *rendered* sentence would mean the effect
+ * had to hold a translator, which is what made it re-run on every language change.
+ */
+type Said = { reported: string } | { fault: "unknown" | "unreachable" } | null;
+
+/** The word to show: the worker's own, or this screen's for a fault, or its word for still waiting. */
+function said(t: Translator, health: Said): string {
+  if (health === null) return t.t("app/home.bare.checking");
+  return "reported" in health ? health.reported : t.t(`app/home.bare.${health.fault}`);
+}
+
+export default function Home() {
+  const t = useTranslator(EN);
+  const [status, setStatus] = useState<Said>(null);
+
+  useEffect(() => {
+    let live = true;
+    // Same origin. The SPA and the worker are one deploy on one origin, so paths are relative and
+    // there is no CORS config and no API origin variable — in dev or in production.
+    //
+    // **No cookie mode, and that is the whole of the request's security story.** The health route is
+    // public: it reads nothing about you, so there is no session to send it, and this is the one screen
+    // a project with no auth composed still gets. Every request that *does* carry a session goes through
+    // `@pithy-sh/auth/src/client/api` instead — which is not importable from here, and does not need to
+    // be, because a request with no ambient credential on it is not the rule that primitive exists to
+    // own (#370).
+    //
+    // **`HEALTH_PATH`, not a string.** The worker mounts this route from that same constant. A copy
+    // here would go stale the day it moves and render "The worker says: unknown." — a 200, no error,
+    // nothing in a log (#400). It is yours to change; changing it to a literal is the way to lose that.
+    fetch(HEALTH_PATH)
+      .then((response) => response.json())
+      .then((body: unknown) => {
+        if (live) setStatus(isHealth(body) ? { reported: body.status } : { fault: "unknown" });
+      })
+      .catch(() => {
+        if (live) setStatus({ fault: "unreachable" });
+      });
+    return () => {
+      live = false;
+    };
+    // **No dependencies, because this asks the worker once per mount and the words are not part of
+    // asking.** `t` was listed here, on the reasoning that it is stable for the life of the screen. It
+    // is not: `useTranslator` memoizes on the provider value, and the provider mounts once the locale's
+    // catalog has loaded — so `t` changes identity on that transition and the health check fired twice
+    // on every mount, and again on every language change. The raw state is stored and translated at
+    // render instead, which is where a language change belongs anyway.
+  }, []);
+
+  return (
+    <main className="screen">
+      <h1>{t.t("app/home.bare.title")}</h1>
+      <p className="muted">{t.t("app/home.bare.body", { status: said(t, status) })}</p>
+    </main>
+  );
+}

package/templates/src/routes/app/home.tsx

@@ -0,0 +1,41 @@
+import type { MessageCatalog } from "@pithy-sh/core/src/i18n/catalog";
+import { useTranslator } from "@pithy-sh/i18n/src/react/translator";
+import { signOut, useSession } from "../../session";
+
+// Your screen. Pithy wrote this file once and never will again — everything under src/routes/app/ is
+// yours. Add a screen by dropping a file in beside it with its own `path` export.
+export const path = "/";
+
+// Signed-out visitors are sent to /sign-in. Delete this line to make the screen public.
+export const session = "required";
+
+/**
+ * This screen's English, baked in. Yours, like the rest of the file.
+ *
+ * Keyed under `app/` because this screen is yours rather than a capability's — a capability may only
+ * declare keys under its own name, and none of them is called `app`. Add your own keys here and they
+ * translate through the same layers the kit's do.
+ */
+const EN = {
+  "app/home.title": "You're in.",
+  "app/home.signed_in_as": "Signed in as {email}.",
+  "app/home.someone": "someone",
+  "app/home.sign_out": "Sign out",
+} satisfies MessageCatalog;
+
+export default function Home() {
+  const t = useTranslator(EN);
+  const { session: current } = useSession();
+
+  return (
+    <main className="screen">
+      <h1>{t.t("app/home.title")}</h1>
+      <p className="muted">{t.t("app/home.signed_in_as", { email: current?.user.email ?? t.t("app/home.someone") })}</p>
+      <div className="stack">
+        <button type="button" className="secondary" onClick={() => void signOut()}>
+          {t.t("app/home.sign_out")}
+        </button>
+      </div>
+    </main>
+  );
+}

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

@@ -0,0 +1,42 @@
+import type { MessageCatalog } from "@pithy-sh/core/src/i18n/catalog";
+import { useTranslator } from "@pithy-sh/i18n/src/react/translator";
+import { useEffect } from "react";
+import { navigate, routeTable, screenPath } from "../../router";
+import { getSession } from "../../session";
+import "../../pithy-screens.css";
+
+export const path = "/callback";
+
+// Pithy's screen. Yours to override: put your own file at this path under src/routes/app/ and it wins.
+//
+// `sign-in.tsx` builds the magic link's `callbackURL` from the `path` above, so renaming it moves both
+// ends at once. That is the contract #393 exists for — the round trip is the one flow nobody already
+// signed in can test, so it must not be two strings that only happen to agree.
+
+/** This screen's English, baked in — the only catalog that survives being copied into your repository. */
+const EN = {
+  "auth/callback.title": "Signing you in.",
+  "auth/callback.body": "One moment.",
+} satisfies MessageCatalog;
+
+export default function Callback() {
+  const t = useTranslator(EN);
+
+  useEffect(() => {
+    // The session cookie is already set by the time we get here — the server did the verifying.
+    // This screen just asks who you are and moves on.
+    //
+    // Where "away" is comes from the route table, never a literal: the sign-in screen declares its own
+    // path and claims the role, and this reads whatever it declared.
+    void Promise.all([getSession(), routeTable()]).then(([current, table]) =>
+      navigate(current ? "/" : screenPath(table, "sign-in")),
+    );
+  }, []);
+
+  return (
+    <main className="screen">
+      <h1>{t.t("auth/callback.title")}</h1>
+      <p className="muted">{t.t("auth/callback.body")}</p>
+    </main>
+  );
+}

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

@@ -0,0 +1,127 @@
+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 { useCallback, useRef, useState } from "react";
+import { authConfig } from "../../pithy-config";
+import { navigate, useSearchParam } from "../../router";
+import { Turnstile, turnstilePending, turnstileRequest } from "../../turnstile";
+import "../../pithy-screens.css";
+
+export const path = "/otp";
+
+// Pithy's screen. Yours to override: put your own file at this path under src/routes/app/ and it wins.
+//
+// **Nothing sends anyone here by default.** The sign-in screen offers one way in — the magic link —
+// because two passwordless paths on one screen is two things to explain, two surfaces to rate-limit,
+// and two inboxes' worth of mail for one intent. This screen stays because the server route behind it
+// does: if you would rather have a code, send one from your own screen and route here with
+// `navigate(`/otp?email=${encodeURIComponent(email)}`)`.
+//
+// **The email stays a query parameter, now that `/otp/:email` is expressible.** A path parameter
+// identifies the thing a URL points at, and this URL points at the code entry screen — the address is
+// a prefill, not the resource. `/otp` with no email is a valid screen and renders "your inbox", which
+// a path segment cannot say without an optional-segment rule the router deliberately does not have.
+// Nothing mails a link here either, so the argument for identifiers in the path — that a link is the
+// way in — does not apply. And an address in a path is PII in every access log and referrer along the
+// way: the same argument that favours the path for a token, pointing the other way for an email.
+
+/**
+ * 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` rather than being concatenated onto a
+ * noun: `otpLength` is configurable, and a locale with more than two plural forms has no way to say
+ * "digits" correctly from a single 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;
+
+export default function Otp() {
+  const t = useTranslator(EN);
+  const email = useSearchParam("email") ?? "";
+  const [digits, setDigits] = useState<string[]>(() => Array.from({ length: authConfig.otpLength }, () => ""));
+  const [captcha, setCaptcha] = useState<string | null>(null);
+  const [error, setError] = useState(false);
+  const [busy, setBusy] = useState(false);
+  const inputs = useRef<(HTMLInputElement | null)[]>([]);
+  const onToken = useCallback((value: string | null) => setCaptcha(value), []);
+
+  const code = digits.join("");
+
+  function setDigit(index: number, value: string): void {
+    const digit = value.replace(/\D/g, "").slice(-1);
+    setDigits((current) => current.map((existing, position) => (position === index ? digit : existing)));
+    if (digit && index + 1 < authConfig.otpLength) inputs.current[index + 1]?.focus();
+  }
+
+  // Where the auth routes are. Both calls below name an intent and nothing about transport: the
+  // base-path join, the cookie mode and the failure directions belong to `@pithy-sh/auth`, which can
+  // still fix them after this file is yours.
+  const client = { basePath: authConfig.basePath };
+
+  async function verify(): Promise<void> {
+    setBusy(true);
+    setError(false);
+    const result = await signInWithOtp({ email, otp: code }, client);
+    setBusy(false);
+    if (result.ok) navigate("/");
+    else 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" }, { ...client, gate: (body) => turnstileRequest(body, captcha) });
+  }
+
+  return (
+    <main className="screen">
+      <h1>{t.t("auth/otp.title")}</h1>
+      <p className="muted">
+        {t.plural("auth/otp.sent", authConfig.otpLength, { email: email || t.t("auth/otp.inbox") })}
+      </p>
+
+      <div className="otp">
+        {digits.map((digit, index) => (
+          <input
+            // 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;
+            }}
+            inputMode="numeric"
+            autoComplete="one-time-code"
+            maxLength={1}
+            value={digit}
+            onChange={(event) => setDigit(index, event.target.value)}
+          />
+        ))}
+      </div>
+
+      {error && <p className="muted">{t.t("auth/otp.failed")}</p>}
+
+      <div className="stack">
+        <button type="button" disabled={busy || code.length < authConfig.otpLength} onClick={() => void verify()}>
+          {t.t("auth/otp.submit")}
+        </button>
+        {/* Resending goes back through the gated send route, so the widget belongs here too. */}
+        <Turnstile onToken={onToken} />
+        <button
+          type="button"
+          className="secondary"
+          disabled={busy || turnstilePending(captcha)}
+          onClick={() => void resend()}
+        >
+          {t.t("auth/otp.resend")}
+        </button>
+      </div>
+    </main>
+  );
+}

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

@@ -0,0 +1,160 @@
+import type { MessageCatalog } from "@pithy-sh/core/src/i18n/catalog";
+import { useTranslator } from "@pithy-sh/i18n/src/react/translator";
+import {
+  PAYMENTS_HOSTED_RAILS,
+  type PaymentsHostedRail,
+  returnedCheckoutSession,
+} from "@pithy-sh/payments/src/client/api";
+import { useCheckout, usePaddleCheckout, usePurchase } from "@pithy-sh/payments/src/client/hooks";
+import { useEffect, useState } from "react";
+// `CHECKOUT_FRAME` is imported rather than declared here: the two screens that sell share one class, and
+// `.pithy-checkout` is a hook you are meant to style. Two copies is one styled checkout and one bare one.
+import { CHECKOUT_FRAME, failureText, paymentsClient } from "../../payments";
+import { paymentsConfig } from "../../pithy-config";
+import { Link, useScreenPath } from "../../router";
+import "../../pithy-screens.css";
+
+export const path = "/paywall";
+
+// The screen the router's entitlement guard sends people to. Rename `path` above and the guard follows,
+// because it reads this claim rather than holding a copy of the string (#393).
+export const role = "paywall";
+
+// Buying attaches a purchase to an account, so there has to be one.
+export const session = "required";
+
+// Pithy's screen. Yours to override: put your own file at this path under src/routes/app/ and it wins.
+//
+// It renders and styles; every call it makes belongs to @pithy-sh/payments. That split is the point — this
+// file is written once and never rewritten, and store rules change. A purchase flow copied into here would
+// be one Pithy could not fix for you; one that calls the hooks upgrades with a minor release.
+
+/**
+ * What a product can do on the web: any enabled hosted rail this product is actually listed on.
+ *
+ * The list is `PAYMENTS_HOSTED_RAILS`, from the package. It used to be three names written out here,
+ * which is the shape #336 was about — correct on the day, one rail short a release later, and frozen
+ * the moment this file was copied into a repo. Imported, a rail added to Pithy reaches a paywall
+ * scaffolded a year ago. Apple and Google are not on it: those purchases happen inside a store SDK,
+ * and a web page can say a product exists and nothing more.
+ */
+function purchasable(product: { skus: Record<PaymentsHostedRail, string | null> }): boolean {
+  return PAYMENTS_HOSTED_RAILS.some((rail) => paymentsConfig.rails[rail] && product.skus[rail] !== null);
+}
+
+/**
+ * This screen's English, baked in — the only catalog that survives being copied into your repository.
+ *
+ * A project composing no `i18n` capability renders exactly these sentences. With it composed they
+ * become the last layer: your own catalog first, then the kit's translation, then this.
+ *
+ * `pithy.config.ts` is not in a message. A file name is not copy, and a translator who rendered it in
+ * their own language would name a file that does not exist.
+ */
+const EN = {
+  "payments/paywall.title": "Go further.",
+  "payments/paywall.body": "Pick what you need. You can change your mind later.",
+  "payments/paywall.buy": "Buy {product}",
+  "payments/paywall.in_app": "Available in the app.",
+  "payments/paywall.holdings": "What do I already have?",
+  "payments/paywall.empty.title": "Nothing for sale.",
+  "payments/paywall.empty.body": "This project has no catalog yet. Add products to",
+  "payments/paywall.done.title": "You're set.",
+  "payments/paywall.done.body": "Thanks. Your purchase is on your account.",
+  "payments/paywall.done.home": "Go home",
+} satisfies MessageCatalog;
+
+export default function Paywall() {
+  const t = useTranslator(EN);
+  // Read before the early returns, because it is a hook — and read at all, rather than written out as
+  // `/subscription`, because the subscription screen declares its own path (#393).
+  const subscriptionPath = useScreenPath("subscription");
+  const checkout = useCheckout(paymentsClient);
+  // Paddle's overlay and inline modes never leave this page, so the handoff has to be opened here. Every
+  // other hosted rail has already navigated away by the time `start` resolves and this reads null.
+  const opened = usePaddleCheckout(checkout.handoff, { frameTarget: CHECKOUT_FRAME });
+  const purchase = usePurchase(paymentsClient);
+  const [returned] = useState(() => returnedCheckoutSession());
+
+  // Coming back from hosted Checkout, the success URL carries the session id. Posting it projects the
+  // purchase at once, so the entitlement shows now rather than whenever the webhook lands. The webhook is
+  // still authoritative and still arrives; dropping this call would only cost the buyer a few seconds.
+  //
+  // Stripe only, and by construction rather than by a check: no other rail substitutes a session id into
+  // the return URL, so `returned` is null coming back from one. A Lemon Squeezy buyer waits for the
+  // webhook — that rail has no receipt a client could submit, because its order ids are sequential
+  // integers and any authenticated caller could claim an order by counting.
+  useEffect(() => {
+    if (returned) void purchase.submit("stripe", returned);
+    // The session id is read once, into state, so this runs once per return rather than once per render —
+    // and `submit` is a stable callback, so listing it costs nothing and keeps the list honest.
+  }, [returned, purchase.submit]);
+
+  if (!paymentsConfig.enabled) {
+    return (
+      <main className="screen">
+        <h1>{t.t("payments/paywall.empty.title")}</h1>
+        <p className="muted">
+          {t.t("payments/paywall.empty.body")} <code>pithy.config.ts</code>.
+        </p>
+      </main>
+    );
+  }
+
+  if (returned && purchase.purchase) {
+    return (
+      <main className="screen">
+        <h1>{t.t("payments/paywall.done.title")}</h1>
+        <p className="muted">{t.t("payments/paywall.done.body")}</p>
+        <div className="stack">
+          <Link to="/">{t.t("payments/paywall.done.home")}</Link>
+        </div>
+      </main>
+    );
+  }
+
+  return (
+    <main className="screen">
+      <h1>{t.t("payments/paywall.title")}</h1>
+      <p className="muted">{t.t("payments/paywall.body")}</p>
+
+      {purchase.failure && <p className="muted">{failureText(t, purchase.failure)}</p>}
+      {checkout.failure && <p className="muted">{failureText(t, checkout.failure)}</p>}
+      {opened.failure && <p className="muted">{failureText(t, opened.failure)}</p>}
+
+      <div className="stack">
+        {paymentsConfig.products.map((product) => (
+          <div key={product.id}>
+            <p>
+              <strong>{product.name}</strong>
+            </p>
+            {purchasable(product) ? (
+              <button
+                type="button"
+                disabled={checkout.starting || opened.opening}
+                onClick={() => void checkout.start(product.id)}
+              >
+                {t.t("payments/paywall.buy", { product: product.name })}
+              </button>
+            ) : (
+              // Display only. StoreKit and Play Billing need native app code to present a purchase sheet,
+              // so a web page can say a product exists and where to get it, and nothing more.
+              <p className="muted">{t.t("payments/paywall.in_app")}</p>
+            )}
+          </div>
+        ))}
+      </div>
+
+      {/* Rendered from the handoff rather than from a guess at your config, and rendered *before* the
+          checkout opens: Paddle looks this element up by class name at that moment, and throws if the
+          render revealing it has not committed. That ordering is `usePaddleCheckout`'s job. */}
+      {opened.inline && <div className={CHECKOUT_FRAME} />}
+
+      <div className="stack">
+        <Link className="muted" to={subscriptionPath}>
+          {t.t("payments/paywall.holdings")}
+        </Link>
+      </div>
+    </main>
+  );
+}