@rific/splash-gate 0.1.2 → 0.2.1

package/README.md

@@ -4,7 +4,7 @@ Name every async condition your Expo app's first screen actually depends on (a l
 
 ## Why
 
-`SplashScreen.preventAutoHideAsync()` only holds the splash up. It's on you to call `hideAsync()` at the right moment. Call it too early (e.g. the instant your theme loads) and anything else your first screen depends on but forgot to wait for, an icon font, a hydrated preference, pops in visibly a moment after the splash lifts. `createSplashGate` makes every condition explicit up front, so nothing can be forgotten silently.
+`SplashScreen.preventAutoHideAsync()` only holds the splash up. It's on you to call `hideAsync()` at the right moment. Call it too early (e.g. the instant your theme loads) and anything else your first screen depends on but forgot to wait for, an icon font, a hydrated preference, pops in visibly a moment after the splash lifts. `createGate` makes every condition explicit up front, so nothing can be forgotten silently.
 
 ## Installation
 
@@ -17,9 +17,9 @@ npm install @rific/splash-gate
 ```ts
 // splashGate.ts, created once, at module scope, listing every condition this app's first
 // screen actually depends on
-import { createSplashGate } from '@rific/splash-gate'
+import { createGate } from '@rific/splash-gate'
 
-export const { markReady, useReady, pendingGates } = createSplashGate(['theme', 'fonts', 'keyboardLayout'])
+export const { markReady, useReady, pendingGates, Gate } = createGate(['theme', 'fonts', 'keyboardLayout'])
 ```
 
 ```tsx
@@ -44,10 +44,11 @@ export const Theme = ({ children }) => {
 // KeyboardLayoutProvider.tsx
 import { useReady } from './splashGate'
 
+const [layout, setLayout] = useState<string | null>(null)
 const [loaded, setLoaded] = useState(false)
 useEffect(() => {
   void AsyncStorage.getItem(STORAGE_KEY).then((stored) => {
-    if (stored) setLayoutState(stored)
+    if (stored) setLayout(stored)
     setLoaded(true) // mark loaded whether or not a saved value was actually found
   })
 }, [])
@@ -56,14 +57,39 @@ useReady('keyboardLayout', loaded)
 
 The splash screen hides exactly once, the moment `theme`, `fonts`, and `keyboardLayout` have all reported ready, in whatever order they actually resolve.
 
+## Guarding against a child that renders before its data does
+
+`useReady` only defers when the splash screen *hides* — it says nothing about when your own children first *render*. That's fine for a plain condition like `fontsLoaded`, but it's a trap for a component that mounts a third-party provider whose internal state locks in on first render (a `useState(() => ...)` lazy initializer wrapping a loaded prop, which is how most context providers are written). Render that provider immediately with a placeholder default and patch the real prop in once it loads, and the provider never notices the patch — it already locked onto the placeholder, permanently, even though the gate reports in correctly and the splash hides at the right moment. From the outside this looks exactly like the setting silently failing to persist.
+
+`Gate` closes that gap: it registers the gate exactly like `useReady` does, and in the same step withholds `children` until `ready` is `true`, so a gate can't be reported without also blocking whatever depends on it from mounting too early.
+
+```tsx
+// KeyboardLayoutProvider.tsx
+import { Gate } from './splashGate' // from createGate(['theme', 'fonts', 'keyboardLayout'])
+
+const [layout, setLayout] = useState<string | null>(null) // null = not loaded yet
+useEffect(() => {
+  void AsyncStorage.getItem(STORAGE_KEY).then((stored) => setLayout(stored ?? 'qwerty'))
+}, [])
+
+// ThirdPartyLayoutProvider's own `layout` state is a lazy useState(() => initialLayout) — it only
+// reads `initialLayout` on its very first mount, so it must not mount until the real value exists.
+return (
+  <Gate gate='keyboardLayout' ready={layout !== null}>
+    <ThirdPartyLayoutProvider initialLayout={layout}>{children}</ThirdPartyLayoutProvider>
+  </Gate>
+)
+```
+
 ## API
 
-### `createSplashGate(gates)`
+### `createGate(gates)`
 
 Takes an array of gate names (typically `as const` for literal-type safety) and returns:
 
 - `markReady(gate)`: marks one gate ready. Safe to call more than once for the same gate, and safe in any order. Hides the splash screen exactly once, once every gate is ready. For a gate that only resolves via a one-shot callback (a library's own `onReady` prop, a promise `.then`), call this directly there.
 - `useReady(gate, ready)`: for a gate whose readiness is already a plain boolean (state from a hook like `useFonts`, or your own derived condition), marks it ready once `ready` becomes `true`. Bound to this gate instance, so there's nothing to pass but the two things that actually vary at each call site.
+- `Gate`: a component, bound to this gate instance. `useReady(gate, ready)` plus render-gating in one step — see above. Renders `children` once `ready` is `true`, otherwise `fallback` (default `null`).
 - `pendingGates()`: the gate names still outstanding, for a debug log during development.
 
 Call this once, at module scope, not inside a component body, or you'll get a fresh gate (and a fresh splash-hide race) on every render.

package/dist/index.d.mts

@@ -1,8 +1,17 @@
+import { ReactNode } from 'react';
+
+interface GateProps<T extends string> {
+    gate: T;
+    ready: boolean;
+    fallback?: ReactNode;
+    children: ReactNode;
+}
 type SplashGate<T extends string> = {
     markReady: (gate: T) => void;
     useReady: (gate: T, ready: boolean) => void;
     pendingGates: () => T[];
+    Gate: (props: GateProps<T>) => ReactNode;
 };
-declare function createSplashGate<T extends string>(gates: readonly T[]): SplashGate<T>;
+declare function createGate<T extends string>(gates: readonly T[]): SplashGate<T>;
 
-export { type SplashGate, createSplashGate };
+export { type GateProps, type SplashGate, createGate };

package/dist/index.d.ts

@@ -1,8 +1,17 @@
+import { ReactNode } from 'react';
+
+interface GateProps<T extends string> {
+    gate: T;
+    ready: boolean;
+    fallback?: ReactNode;
+    children: ReactNode;
+}
 type SplashGate<T extends string> = {
     markReady: (gate: T) => void;
     useReady: (gate: T, ready: boolean) => void;
     pendingGates: () => T[];
+    Gate: (props: GateProps<T>) => ReactNode;
 };
-declare function createSplashGate<T extends string>(gates: readonly T[]): SplashGate<T>;
+declare function createGate<T extends string>(gates: readonly T[]): SplashGate<T>;
 
-export { type SplashGate, createSplashGate };
+export { type GateProps, type SplashGate, createGate };

package/dist/index.js

@@ -30,14 +30,14 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
-  createSplashGate: () => createSplashGate
+  createGate: () => createGate
 });
 module.exports = __toCommonJS(index_exports);
 
 // src/splashGate.ts
 var SplashScreen = __toESM(require("expo-splash-screen"));
 var import_react = require("react");
-function createSplashGate(gates) {
+function createGate(gates) {
   const pending = new Set(gates);
   let hidden = false;
   const tryHide = () => {
@@ -55,10 +55,14 @@ function createSplashGate(gates) {
     }, [ready, gate]);
   };
   const pendingGates = () => Array.from(pending);
+  const Gate = ({ gate, ready, fallback = null, children }) => {
+    useReady(gate, ready);
+    return ready ? children : fallback;
+  };
   tryHide();
-  return { markReady, useReady, pendingGates };
+  return { markReady, useReady, pendingGates, Gate };
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  createSplashGate
+  createGate
 });

package/dist/index.mjs

@@ -1,7 +1,7 @@
 // src/splashGate.ts
 import * as SplashScreen from "expo-splash-screen";
 import { useEffect } from "react";
-function createSplashGate(gates) {
+function createGate(gates) {
   const pending = new Set(gates);
   let hidden = false;
   const tryHide = () => {
@@ -19,9 +19,13 @@ function createSplashGate(gates) {
     }, [ready, gate]);
   };
   const pendingGates = () => Array.from(pending);
+  const Gate = ({ gate, ready, fallback = null, children }) => {
+    useReady(gate, ready);
+    return ready ? children : fallback;
+  };
   tryHide();
-  return { markReady, useReady, pendingGates };
+  return { markReady, useReady, pendingGates, Gate };
 }
 export {
-  createSplashGate
+  createGate
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rific/splash-gate",
-  "version": "0.1.2",
+  "version": "0.2.1",
   "description": "Name every async condition an Expo app's first screen depends on (theme, fonts, saved preferences, auth, ...) and hold the splash screen up until all of them report ready — instead of hand-rolling a fresh ad hoc gate per project",
   "keywords": [
     "expo",
@@ -41,29 +41,28 @@
   "scripts": {
     "build": "tsup src/index.ts --format cjs,esm --dts --clean",
     "build:watch": "tsup src/index.ts --format cjs,esm --dts --watch",
+    "ci": "npm run lint && npm test && npm run typecheck && npm run build",
     "fix": "eslint --fix",
     "lint": "eslint",
     "prepublishOnly": "npm run build",
     "release": "git push --follow-tags",
-    "release:major": "npm version major && git push --follow-tags",
-    "release:minor": "npm version minor && git push --follow-tags",
-    "release:patch": "npm version patch && git push --follow-tags",
+    "release:major": "npm version major && npm run release",
+    "release:minor": "npm version minor && npm run release",
+    "release:patch": "npm version patch && npm run release",
     "test": "jest",
     "test:watch": "jest --watchAll",
     "typecheck": "tsc --noEmit",
-    "preversion": "npm run lint && npm test && npm run build"
+    "preversion": "npm run ci"
   },
+  "prettier": "@infinitetoken/eslint-config/prettier",
   "devDependencies": {
+    "@infinitetoken/eslint-config": "^0.1.4",
+    "@infinitetoken/tsconfig": "^0.1.1",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/react": "^16.3.2",
     "@types/jest": "^30.0.0",
     "@types/react": "^19.0.0",
-    "@typescript-eslint/parser": "^8.59.3",
     "eslint": "^9.39.4",
-    "eslint-config-prettier": "^10.1.8",
-    "eslint-plugin-package-json": "^1.0.0",
-    "eslint-plugin-prettier": "^5.5.5",
-    "eslint-plugin-simple-import-sort": "^13.0.0",
     "expo-splash-screen": "^57.0.5",
     "jest": "^30.4.2",
     "jest-environment-jsdom": "^30.4.1",
@@ -73,8 +72,7 @@
     "ts-jest": "^29.4.9",
     "ts-node": "^10.9.2",
     "tsup": "^8.0.0",
-    "typescript": "^6.0.3",
-    "typescript-eslint": "^8.59.3"
+    "typescript": "^6.0.3"
   },
   "peerDependencies": {
     "expo-splash-screen": ">=57.0.0",

package/src/index.ts

@@ -1,2 +1,2 @@
-export type { SplashGate } from './splashGate'
-export { createSplashGate } from './splashGate'
+export type { GateProps, SplashGate } from './splashGate'
+export { createGate } from './splashGate'

package/src/splashGate.ts

@@ -1,5 +1,16 @@
 import * as SplashScreen from 'expo-splash-screen'
-import { useEffect } from 'react'
+import { ReactNode, useEffect } from 'react'
+
+export interface GateProps<T extends string> {
+  gate: T
+  ready: boolean
+  // Rendered in place of `children` while `ready` is false. Defaults to null — the common case is
+  // that whatever this wraps has nothing sensible to show until its data exists (see Gate below),
+  // and the splash screen is still up for that entire window anyway, so there's normally nothing
+  // to fill this with.
+  fallback?: ReactNode
+  children: ReactNode
+}
 
 export type SplashGate<T extends string> = {
   // Marks one named gate ready. Safe to call more than once for the same gate (a no-op after the
@@ -15,6 +26,14 @@ export type SplashGate<T extends string> = {
   // Gate names still outstanding, in no particular order. For a debug log or a "why is this still
   // up" check during development, not something app code should need to branch on.
   pendingGates: () => T[]
+  // useReady only defers when the splash screen *hides* — it says nothing about when your own
+  // children first *render*. A component that mounts a child whose state locks in on first render
+  // (a lazy useState(() => ...) initializer wrapping a loaded value, as most third-party providers
+  // do) can already be stuck on stale defaults by the time useReady's effect even runs, even though
+  // the gate itself reports in correctly and the splash stays up for the right duration. Gate
+  // closes that gap: it registers the gate (so the splash still waits on it) *and* withholds
+  // `children` until `ready` is true, in one call, so those two things can't drift apart.
+  Gate: (props: GateProps<T>) => ReactNode
 }
 
 // One named condition per thing your first screen actually depends on (a loaded theme, a loaded
@@ -25,7 +44,7 @@ export type SplashGate<T extends string> = {
 // until every named gate has reported in, then it hides itself exactly once, so nothing your
 // app's first screen shows can ever be caught mid-load, wrong-then-corrected, a beat behind the
 // rest.
-export function createSplashGate<T extends string>(gates: readonly T[]): SplashGate<T> {
+export function createGate<T extends string>(gates: readonly T[]): SplashGate<T> {
   const pending = new Set<T>(gates)
   let hidden = false
 
@@ -42,7 +61,7 @@ export function createSplashGate<T extends string>(gates: readonly T[]): SplashG
 
   const useReady = (gate: T, ready: boolean) => {
     // markReady isn't in this dep array. It's this closure's own stable reference (one per
-    // createSplashGate call), not a per-render value, so there's nothing to gain by re-running
+    // createGate call), not a per-render value, so there's nothing to gain by re-running
     // this effect if it somehow changed identity.
     useEffect(() => {
       if (ready) markReady(gate)
@@ -51,10 +70,15 @@ export function createSplashGate<T extends string>(gates: readonly T[]): SplashG
 
   const pendingGates = () => Array.from(pending)
 
+  const Gate = ({ gate, ready, fallback = null, children }: GateProps<T>) => {
+    useReady(gate, ready)
+    return ready ? children : fallback
+  }
+
   // Nothing to wait for (called with an empty list, or every gate was already satisfied some
   // other way). Hide right away instead of leaving the splash up forever with nothing left that
   // could ever call markReady again.
   tryHide()
 
-  return { markReady, useReady, pendingGates }
+  return { markReady, useReady, pendingGates, Gate }
 }