@marktiderman/genesis-native 0.2.0 → 0.3.0

package/src/blocks.tsx

@@ -0,0 +1,144 @@
+/**
+ * Blocks on native: `defineBlock` declarations (from
+ * `@marktiderman/genesis-features/blocks`) with the two things only a native
+ * shell can run, boot steps behind the splash and a root around the screens.
+ * `<GenesisNativeApp blocks={[…]}>` resolves them once, runs their steps,
+ * mounts their roots, puts their slot fills under the app's own `slots`, and
+ * hands their Settings rows to `useBlockSettings`.
+ */
+import { createContext, useContext, type ComponentType, type ReactNode } from "react";
+import type { SlotPropsFor, Slots } from "@marktiderman/genesis-core/slots";
+import type { BlockDef, BlockSettingsRow, Contributed, ResolvedBlocks } from "@marktiderman/genesis-features/blocks";
+import type { BootStep } from "./boot";
+import type { ErrorReport } from "./errors";
+import type { NativeAppSlots } from "./app";
+
+/** What a block's `Root` is given: the app's slots, with every block's fills merged under them. @stability Beta */
+export interface NativeBlockRootProps {
+  slots?: Slots<NativeAppSlots>;
+  slotProps?: SlotPropsFor<NativeAppSlots>;
+  children?: ReactNode;
+}
+
+/**
+ * A block a native shell can run. `contributes.slots` fills `GenesisNativeApp`
+ * slots by name (the app's own `slots` win).
+ *
+ * @stability Beta
+ */
+export interface NativeBlock<Id extends string = string> extends BlockDef<Id, ComponentType<never>> {
+  /** Run behind the splash after the app's own `steps`, before the session. A step that fails fails the boot, so keep them bounded. */
+  readonly bootSteps?: readonly BootStep[];
+  /** Mounted around the screens, inside the shell's error boundary. The first block's root is the outermost. */
+  readonly Root?: ComponentType<NativeBlockRootProps>;
+  /**
+   * Every error the shell catches (render, global, boot, rejection), before
+   * the app's own `onError`. The observability block reports them here. A
+   * throw is ignored.
+   */
+  readonly onError?: (error: Error, report: ErrorReport) => void;
+}
+
+/** @internal Hand an error to each block's `onError`; one that throws never stops the rest. */
+export function reportToBlocks(blocks: readonly NativeBlock[], error: Error, report: ErrorReport): void {
+  for (const block of blocks) {
+    if (!block.onError) continue;
+    try {
+      block.onError(error, report);
+    } catch {
+      // A failing reporter must not take the error path down with it.
+    }
+  }
+}
+
+const BlocksContext = createContext<ResolvedBlocks<NativeBlock> | null>(null);
+
+/** @internal Provided by GenesisNativeApp. */
+export const BlocksProvider = BlocksContext.Provider;
+
+/**
+ * The resolved blocks: their ids, nav entries, Settings rows, routes and the
+ * rest, each tagged with its FeatureId. Throws outside `GenesisNativeApp`.
+ *
+ * @stability Beta
+ */
+export function useBlocks(): ResolvedBlocks<NativeBlock> {
+  const blocks = useContext(BlocksContext);
+  if (!blocks) throw new Error("useBlocks: no blocks. Render inside <GenesisNativeApp>.");
+  return blocks;
+}
+
+/** A Settings section as `SettingsPage` from `@marktiderman/genesis-ui-native` takes it. @stability Beta */
+export interface BlockSettingsSection<R extends { id: string; title: string } = SettingsRowLike> {
+  id: string;
+  title?: string;
+  footnote?: string;
+  rows: R[];
+}
+
+/** The row fields a block can fill. @stability Beta */
+export interface SettingsRowLike {
+  id: string;
+  title: string;
+  subtitle?: string;
+  showChevron?: boolean;
+  onPress?: () => void;
+  testID?: string;
+}
+
+/** @stability Beta */
+export interface UseBlockSettingsOptions {
+  /** Open a row's `href` (expo-router's `router.push`). Without it, rows with an `href` aren't pressable. */
+  navigate?: (href: string) => void;
+  /** Titles for sections a block names that `sections` doesn't have. Default the section id. */
+  sectionTitles?: Readonly<Record<string, string>>;
+}
+
+/**
+ * The app's Settings sections with every block's rows added: each row goes
+ * at the end of the section its `section` names (by `order`, then block
+ * order), and a section no one has yet is added after the rest.
+ *
+ * Calls each row's `useSubtitle` hook, so call it unconditionally at the top
+ * of the Settings screen. The blocks are fixed for the life of the app, so
+ * the hooks run in the same order on every render.
+ *
+ * @stability Beta
+ */
+export function useBlockSettings<R extends SettingsRowLike>(
+  sections: readonly BlockSettingsSection<R>[],
+  options: UseBlockSettingsOptions = {},
+): BlockSettingsSection<R | SettingsRowLike>[] {
+  const blocks = useContext(BlocksContext);
+  const rows = blocks?.settings ?? [];
+  // The same hooks in the same order every render: `rows` never changes once the shell has resolved it.
+  const subtitles = rows.map((row) => row.useSubtitle?.());
+  return mergeBlockSettings(sections, rows, subtitles, options);
+}
+
+/** The merge `useBlockSettings` does, without hooks (subtitles already read). @stability Beta */
+export function mergeBlockSettings<R extends SettingsRowLike>(
+  sections: readonly BlockSettingsSection<R>[],
+  rows: readonly Contributed<BlockSettingsRow>[],
+  subtitles: readonly (string | null | undefined)[] = [],
+  options: UseBlockSettingsOptions = {},
+): BlockSettingsSection<R | SettingsRowLike>[] {
+  const out: BlockSettingsSection<R | SettingsRowLike>[] = sections.map((s) => ({ ...s, rows: [...s.rows] }));
+  rows.forEach((row, i) => {
+    let section = out.find((s) => s.id === row.section);
+    if (!section) {
+      section = { id: row.section, title: options.sectionTitles?.[row.section] ?? row.section, rows: [] };
+      out.push(section);
+    }
+    const { navigate } = options;
+    const href = row.href;
+    section.rows.push({
+      id: row.id,
+      title: row.title,
+      subtitle: subtitles[i] ?? row.subtitle,
+      testID: row.testID,
+      ...(href && navigate ? { showChevron: true, onPress: () => navigate(href) } : {}),
+    });
+  });
+  return out;
+}

package/src/boot.tsx

@@ -0,0 +1,188 @@
+/**
+ * Boot: the async work an app must finish before its first screen (wipe a
+ * session left by a reinstall, hydrate stores, load fonts, restore the query
+ * cache, read the session).
+ *
+ * Steps run once each, in order. A step that finished is never run again, so
+ * "try again" after a failure resumes at the step that failed. Each step has a
+ * timeout (10 seconds by default), so a hung step ends in the fatal screen with
+ * retry instead of trapping the splash. A minimum keeps a fast boot from
+ * flashing the splash.
+ *
+ * `createBoot` is the controller (no React); `BootProvider` + `useBoot()` read
+ * it from components.
+ */
+import { createContext, useContext, useSyncExternalStore, type ReactNode } from "react";
+
+export interface BootStepContext {
+  /**
+   * Aborted when the step times out. Stop work when it fires: a retry waits
+   * for a timed-out run to settle before running the step again.
+   */
+  signal: AbortSignal;
+}
+
+export interface BootStep {
+  /** Unique within the list; names the step in errors. */
+  id: string;
+  run: (context: BootStepContext) => Promise<unknown> | unknown;
+  /** Overrides the boot's `timeoutMs` for this step. */
+  timeoutMs?: number;
+}
+
+export type BootStatus = "idle" | "booting" | "ready" | "failed";
+
+export interface BootState {
+  status: BootStatus;
+  /** Set when `status` is `"failed"`. */
+  error: Error | null;
+  /** The id of the step that failed. */
+  failedStep: string | null;
+  /** Ids of the steps that have finished, in order. */
+  completed: readonly string[];
+}
+
+export interface BootOptions {
+  /** Shortest time the boot takes, so the splash doesn't flash. Default 0. */
+  minimumMs?: number;
+  /** Longest time one step may take. Default 10 000. */
+  timeoutMs?: number;
+}
+
+export interface BootController {
+  getState(): BootState;
+  subscribe(listener: () => void): () => void;
+  /** Run the steps not yet finished. Calling it while a run is in flight returns that run. */
+  start(): Promise<void>;
+  /** After a failure: run again from the step that failed. */
+  retry(): Promise<void>;
+}
+
+/** Thrown when a step takes longer than its timeout. */
+export class BootTimeoutError extends Error {
+  readonly step: string;
+  constructor(step: string, ms: number, reason = "did not finish") {
+    super(`Boot step "${step}" ${reason} within ${ms} ms.`);
+    this.name = "BootTimeoutError";
+    this.step = step;
+  }
+}
+
+const DEFAULT_TIMEOUT_MS = 10_000;
+
+export function toError(value: unknown): Error {
+  if (value instanceof Error) return value;
+  return new Error(typeof value === "string" ? value : "Unknown error", { cause: value });
+}
+
+/** Resolves "settled" when `promise` settles, "pending" after `ms`. */
+function settledWithin(promise: Promise<unknown>, ms: number): Promise<"settled" | "pending"> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  return Promise.race([
+    promise.then(
+      () => "settled" as const,
+      () => "settled" as const,
+    ),
+    new Promise<"pending">((resolve) => {
+      timer = setTimeout(() => resolve("pending"), ms);
+    }),
+  ]).finally(() => clearTimeout(timer));
+}
+
+/** The boot controller: runs `steps` once each, in order, with a timeout per step. */
+export function createBoot(steps: readonly BootStep[], options: BootOptions = {}): BootController {
+  const seen = new Set<string>();
+  for (const step of steps) {
+    if (seen.has(step.id)) throw new Error(`Boot step "${step.id}" is listed twice.`);
+    seen.add(step.id);
+  }
+  const { minimumMs = 0, timeoutMs = DEFAULT_TIMEOUT_MS } = options;
+  const listeners = new Set<() => void>();
+  let state: BootState = { status: "idle", error: null, failedStep: null, completed: [] };
+  let inFlight: Promise<void> | null = null;
+  // A step that timed out keeps running (JavaScript can't stop it; `signal`
+  // asks it to). A retry waits for it rather than running it twice at once.
+  const abandoned = new Map<string, Promise<"ok" | "failed">>();
+
+  const runStep = async (step: BootStep, ms: number): Promise<void> => {
+    const previous = abandoned.get(step.id);
+    if (previous) {
+      if ((await settledWithin(previous, ms)) === "pending") {
+        throw new BootTimeoutError(step.id, ms, "is still running from the last attempt");
+      }
+      abandoned.delete(step.id);
+      // The abandoned run finished after all: it counts.
+      if ((await previous) === "ok") return;
+    }
+    const controller = new AbortController();
+    const running = Promise.resolve().then(() => step.run({ signal: controller.signal }));
+    if ((await settledWithin(running, ms)) === "pending") {
+      controller.abort();
+      abandoned.set(step.id, running.then(() => "ok" as const, () => "failed" as const));
+      throw new BootTimeoutError(step.id, ms);
+    }
+    await running;
+  };
+
+  const set = (next: Partial<BootState>) => {
+    state = { ...state, ...next };
+    for (const listener of listeners) listener();
+  };
+
+  const run = async () => {
+    const started = Date.now();
+    set({ status: "booting", error: null, failedStep: null });
+    for (const step of steps) {
+      if (state.completed.includes(step.id)) continue;
+      try {
+        await runStep(step, step.timeoutMs ?? timeoutMs);
+      } catch (error) {
+        set({ status: "failed", error: toError(error), failedStep: step.id });
+        return;
+      }
+      set({ completed: [...state.completed, step.id] });
+    }
+    const wait = minimumMs - (Date.now() - started);
+    if (wait > 0) await new Promise((resolve) => setTimeout(resolve, wait));
+    set({ status: "ready" });
+  };
+
+  const start = () => {
+    if (state.status === "ready") return Promise.resolve();
+    if (!inFlight) {
+      inFlight = run().finally(() => {
+        inFlight = null;
+      });
+    }
+    return inFlight;
+  };
+
+  return {
+    getState: () => state,
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    start,
+    retry: start,
+  };
+}
+
+const BootContext = createContext<BootController | null>(null);
+
+/** Makes a boot readable with `useBoot()`. */
+export function BootProvider({ boot, children }: { boot: BootController; children: ReactNode }) {
+  return <BootContext.Provider value={boot}>{children}</BootContext.Provider>;
+}
+
+export interface UseBootReturn extends BootState {
+  retry: () => void;
+}
+
+/** The boot's status, and `retry` after a failure. Inside `GenesisNativeApp` or a `BootProvider`. */
+export function useBoot(): UseBootReturn {
+  const boot = useContext(BootContext);
+  if (!boot) throw new Error("useBoot must be used inside <GenesisNativeApp> or <BootProvider>.");
+  const state = useSyncExternalStore(boot.subscribe, boot.getState, boot.getState);
+  return { ...state, retry: () => void boot.retry() };
+}

package/src/dev-warnings.ts

@@ -0,0 +1,43 @@
+/**
+ * Development-only warnings from the libraries a Genesis native app is built on, that the app
+ * can't act on, kept out of LogBox.
+ *
+ * Why it matters: in React Native 0.88 (Expo SDK 58), LogBox no longer lists warnings while no
+ * debugger is attached. The first one instead shows a pill, "Open debugger to view warnings.", pinned to the bottom of the screen,
+ * over the native tab bar (`expo-router/native-tabs`). A tap meant for a tab lands on the pill
+ * (which opens the debugger and goes away), so the first tab tap after a launch, or after a link
+ * opened the app, seems to do nothing. In the starter on Expo SDK 58 the warning was React
+ * Native's own deprecation of `ImageBackground`, read by NativeWind's runtime
+ * (`react-native-css-interop` 0.2 registers every core component at start-up).
+ *
+ * Only warnings with no fix in the app belong here: one the app causes should be fixed, and still
+ * shows. Each pattern names where it comes from and when to remove it. Release builds have no
+ * LogBox, so this does nothing there.
+ *
+ * It has to run before any library loads: NativeWind's runtime warns while the first screen
+ * module is still being required, long before `GenesisNativeApp` renders. So the app's entry
+ * file calls it, then requires expo-router's entry (the starter's `index.ts`):
+ *
+ *   import { LogBox } from "react-native";
+ *   import { ignoreKnownDependencyWarnings } from "@marktiderman/genesis-native/dev-warnings";
+ *   ignoreKnownDependencyWarnings(LogBox, __DEV__);
+ *   require("expo-router/entry");
+ */
+
+export interface LogBoxLike {
+  ignoreLogs(patterns: ReadonlyArray<string | RegExp>): void;
+}
+
+/** The warnings, matched on their text. */
+export const KNOWN_DEPENDENCY_WARNINGS: readonly RegExp[] = [
+  // react-native-css-interop 0.2.x (NativeWind 4) reads `ImageBackground` from React Native's
+  // index, whose getter warns from 0.88. Remove once css-interop stops touching it.
+  /^ImageBackground is deprecated and will be removed in a future release\./,
+];
+
+/** Keep the known dependency warnings out of LogBox (development only). Returns whether it did. */
+export function ignoreKnownDependencyWarnings(logBox: LogBoxLike | undefined, dev: boolean): boolean {
+  if (!dev || !logBox) return false;
+  logBox.ignoreLogs(KNOWN_DEPENDENCY_WARNINGS);
+  return true;
+}