@marktiderman/genesis-native 0.4.4 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (49) hide show
  1. package/README.md +98 -6
  2. package/dist/{block-Onqx7NiK.d.ts → block-DFnC8j5U.d.ts} +53 -3
  3. package/dist/{blocks-C2RDpvaN.d.ts → blocks-CyXjSGwV.d.ts} +12 -93
  4. package/dist/{chunk-75YP72G6.js → chunk-6L36FQBX.js} +95 -7
  5. package/dist/chunk-6L36FQBX.js.map +1 -0
  6. package/dist/chunk-C54LIT4N.js +73 -0
  7. package/dist/chunk-C54LIT4N.js.map +1 -0
  8. package/dist/chunk-MFHOHSEQ.js +249 -0
  9. package/dist/chunk-MFHOHSEQ.js.map +1 -0
  10. package/dist/chunk-VIC2KXMA.js +35 -0
  11. package/dist/chunk-VIC2KXMA.js.map +1 -0
  12. package/dist/devtools.d.ts +5 -4
  13. package/dist/devtools.js +3 -1
  14. package/dist/devtools.js.map +1 -1
  15. package/dist/index.d.ts +28 -4
  16. package/dist/index.js +13 -192
  17. package/dist/index.js.map +1 -1
  18. package/dist/observability.d.ts +33 -7
  19. package/dist/observability.js +20 -7
  20. package/dist/observability.js.map +1 -1
  21. package/dist/persist.d.ts +2 -1
  22. package/dist/persist.js +1 -1
  23. package/dist/push.d.ts +3 -3
  24. package/dist/query-DobJyRvs.d.ts +208 -0
  25. package/dist/screen-boundary-BlT6KBpa.d.ts +43 -0
  26. package/dist/updates.d.ts +2 -2
  27. package/dist/updates.js +3 -0
  28. package/dist/updates.js.map +1 -1
  29. package/dist/web-handoff.d.ts +88 -0
  30. package/dist/web-handoff.js +78 -0
  31. package/dist/web-handoff.js.map +1 -0
  32. package/package.json +9 -4
  33. package/src/app.tsx +16 -2
  34. package/src/errors.tsx +46 -7
  35. package/src/index.ts +24 -0
  36. package/src/observability/block.tsx +132 -5
  37. package/src/observability/index.ts +2 -0
  38. package/src/observability/sentry.ts +41 -6
  39. package/src/observability/sink.ts +30 -1
  40. package/src/query.ts +67 -1
  41. package/src/reload.ts +56 -0
  42. package/src/screen-boundary.tsx +116 -0
  43. package/src/updates/channels.ts +3 -0
  44. package/src/updates/checker.ts +3 -0
  45. package/src/web-handoff.ts +165 -0
  46. package/dist/chunk-75YP72G6.js.map +0 -1
  47. package/dist/chunk-VTJDIKFC.js +0 -39
  48. package/dist/chunk-VTJDIKFC.js.map +0 -1
  49. package/dist/query-DUmVAfsF.d.ts +0 -70
@@ -0,0 +1,208 @@
1
+ import { QueryClientConfig, QueryClient } from '@tanstack/react-query';
2
+ import * as react from 'react';
3
+ import { ReactNode, ComponentType, Component, ErrorInfo } from 'react';
4
+
5
+ /**
6
+ * What a fatal or screen error says under its title: the safe sentence for
7
+ * its kind (offline, signed out…), or nothing for a plain bug. The error's
8
+ * own text can hold an email, an id or a store's internals, so it is shown
9
+ * only in development builds.
10
+ */
11
+ declare function errorDetails(error: Error): string | undefined;
12
+ interface FatalScreenProps {
13
+ error: Error;
14
+ /** Clears the error and remounts the app below the shell (and re-runs a failed boot). */
15
+ retry: () => void;
16
+ }
17
+ /** The default fatal screen: what went wrong and "Try again". */
18
+ declare function FatalScreen({ error, retry }: FatalScreenProps): react.JSX.Element;
19
+ /**
20
+ * The last-resort fatal screen: React Native primitives only, no theme, no
21
+ * context, nothing that can itself fail. Shown when the providers could not
22
+ * start, or when the `fatal` slot threw.
23
+ */
24
+ declare function PlainFatalScreen({ error, retry }: FatalScreenProps): react.JSX.Element;
25
+ interface ErrorReport {
26
+ /** True when the app could not go on (a render error, a failed boot, a fatal global error). */
27
+ fatal: boolean;
28
+ /**
29
+ * `boundary` (the shell's), `screen` (a screen boundary), `global`, `boot`,
30
+ * `rejection`, `query` and `mutation` (a failed query or mutation the
31
+ * shell's query client saw).
32
+ */
33
+ source: "boundary" | "screen" | "global" | "boot" | "rejection" | "query" | "mutation";
34
+ componentStack?: string;
35
+ /** False when nothing caught it (an unhandled promise rejection). Default: handled unless fatal. */
36
+ handled?: boolean;
37
+ /** Low-cardinality labels (`query.key`), never ids. */
38
+ tags?: Readonly<Record<string, string>>;
39
+ }
40
+ type OnError = (error: Error, report: ErrorReport) => void;
41
+ interface GenesisErrorBoundaryProps {
42
+ children?: ReactNode;
43
+ /** What to render instead of the tree that threw. */
44
+ fallback: ComponentType<FatalScreenProps>;
45
+ onError?: OnError;
46
+ /** Change it to clear a caught error (the tree remounts). */
47
+ resetKey?: unknown;
48
+ /** Called by the fallback's retry, after the error is cleared. */
49
+ onRetry?: () => void;
50
+ /** Reported as fatal (the app could not go on). Default true; a screen boundary reports false. */
51
+ fatal?: boolean;
52
+ /** The report's source. Default `boundary`. */
53
+ source?: ErrorReport["source"];
54
+ }
55
+ interface BoundaryState {
56
+ error: Error | null;
57
+ }
58
+ /** An error boundary whose fallback gets `{ error, retry }`. */
59
+ declare class GenesisErrorBoundary extends Component<GenesisErrorBoundaryProps, BoundaryState> {
60
+ state: BoundaryState;
61
+ static getDerivedStateFromError(error: unknown): BoundaryState;
62
+ componentDidCatch(error: unknown, info: ErrorInfo): void;
63
+ componentDidUpdate(previous: GenesisErrorBoundaryProps): void;
64
+ retry: () => void;
65
+ render(): string | number | bigint | boolean | Iterable<ReactNode> | Promise<string | number | bigint | boolean | react.ReactPortal | react.ReactElement<unknown, string | react.JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | react.JSX.Element | null;
66
+ }
67
+ /** React Native's `ErrorUtils` (a global in every RN app), or a stand-in. */
68
+ interface ErrorUtilsLike {
69
+ getGlobalHandler(): ((error: unknown, isFatal?: boolean) => void) | undefined;
70
+ setGlobalHandler(handler: (error: unknown, isFatal?: boolean) => void): void;
71
+ }
72
+ interface GlobalErrorHandlerOptions {
73
+ errorUtils: ErrorUtilsLike;
74
+ onError?: OnError;
75
+ /** A fatal error: show the fatal screen. The previous handler (which would end the app) is not called. */
76
+ onFatal: (error: Error) => void;
77
+ /**
78
+ * True while a fatal screen is already up. Another fatal error then goes to
79
+ * the previous handler, which ends the app (it restarts clean) rather than
80
+ * leaving it stuck behind a screen that may itself be broken.
81
+ */
82
+ alreadyFatal?: () => boolean;
83
+ }
84
+ /**
85
+ * Route global errors to `onError`. A fatal one goes to `onFatal` instead of
86
+ * React Native's default handler, which would close the app; a non-fatal one
87
+ * still reaches the previous handler (LogBox in development). Returns a
88
+ * function that puts the previous handler back.
89
+ */
90
+ declare function installGlobalErrorHandler({ errorUtils, onError, onFatal, alreadyFatal }: GlobalErrorHandlerOptions): () => void;
91
+ /** `globalThis.ErrorUtils` in a React Native runtime, undefined elsewhere. */
92
+ declare function defaultErrorUtils(): ErrorUtilsLike | undefined;
93
+ /** Hermes's `HermesInternal.enablePromiseRejectionTracker`, or a stand-in. */
94
+ type EnableRejectionTracker = (options: {
95
+ allRejections: boolean;
96
+ onUnhandled: (id: number, rejection: unknown) => void;
97
+ onHandled: (id: number) => void;
98
+ }) => void;
99
+ /**
100
+ * Hermes's rejection tracker, when the app runs on Hermes. React Native sends
101
+ * unhandled rejections to `ExceptionsManager` (LogBox in development), never
102
+ * to `ErrorUtils`' global handler, so without this they never reach `onError`.
103
+ */
104
+ declare function defaultRejectionTracker(): EnableRejectionTracker | undefined;
105
+ /**
106
+ * Report unhandled promise rejections to `onError`: non-fatal, and unhandled
107
+ * (`handled: false`), so release health counts them. This replaces React
108
+ * Native's own tracker, so each rejection is also written with
109
+ * `console.warn`, which LogBox shows in development as before.
110
+ */
111
+ declare function installRejectionTracker({ enable, onError }: {
112
+ enable: EnableRejectionTracker;
113
+ onError: OnError;
114
+ }): void;
115
+
116
+ /**
117
+ * Query: a TanStack Query client with offline-safe defaults, and the contract
118
+ * for saving it to the phone. The persister itself is in
119
+ * `@marktiderman/genesis-native/persist`, so an app that saves nothing doesn't
120
+ * install TanStack's persister packages.
121
+ */
122
+
123
+ /** The part of AsyncStorage (or any async key-value store) Genesis uses. */
124
+ interface AsyncStorageLike {
125
+ getItem(key: string): Promise<string | null>;
126
+ setItem(key: string, value: string): Promise<void>;
127
+ removeItem(key: string): Promise<void>;
128
+ }
129
+ /** One day in milliseconds: the default max age of the saved query cache. */
130
+ declare const DAY_MS: number;
131
+ /**
132
+ * A QueryClient for a phone. `networkMode: "offlineFirst"` runs a query or
133
+ * mutation once whatever the network says, then pauses its retries while the
134
+ * device is offline (`onlineManager`, which `connectQueryLifecycle` feeds from
135
+ * NetInfo), continues them when it is back, and refetches stale queries on
136
+ * reconnect. So offline, a query with saved data keeps showing it
137
+ * (`fetchStatus: "paused"`); one with nothing saved stays `pending` and paused
138
+ * until the network returns (check `isPaused`, not only `isPending`, before
139
+ * showing a spinner); and a mutation, which TanStack doesn't retry by default,
140
+ * fails at once instead of waiting. `gcTime` matches the persisted max age, or
141
+ * restored queries would be collected before they are used. Your `config` wins.
142
+ */
143
+ declare function createNativeQueryClient(config?: QueryClientConfig): QueryClient;
144
+ /**
145
+ * The saved query cache. A `scope` (the signed-in user's id, `""` for nobody)
146
+ * is part of what is saved: a cache saved for one user is discarded, on disk
147
+ * too, when another scope restores it.
148
+ */
149
+ interface QueryPersistence {
150
+ /** Load the saved cache into the client, if it was saved for `scope`. */
151
+ restore(scope: string): Promise<void>;
152
+ /** Save on every cache change, for `scope`; returns the unsubscribe. */
153
+ subscribe(scope: string): () => void;
154
+ /**
155
+ * Delete the saved cache. Clear the QueryClient first: the subscription
156
+ * then saves the empty cache, so a save already in flight can't leave the
157
+ * old queries on disk.
158
+ */
159
+ clear(): Promise<void>;
160
+ }
161
+ /** React Native's `AppState`, or a stand-in. */
162
+ interface AppStateLike {
163
+ addEventListener(type: "change", listener: (state: string) => void): {
164
+ remove(): void;
165
+ };
166
+ }
167
+ /** `@react-native-community/netinfo`'s default export, or a stand-in. */
168
+ interface NetInfoLike {
169
+ addEventListener(listener: (state: {
170
+ isConnected: boolean | null;
171
+ }) => void): () => void;
172
+ }
173
+ interface QueryLifecycleOptions {
174
+ appState?: AppStateLike;
175
+ netInfo?: NetInfoLike;
176
+ }
177
+ /**
178
+ * Tell TanStack Query when the app comes to the front (refetch stale
179
+ * queries) and when the network comes and goes. Returns the cleanup.
180
+ */
181
+ declare function connectQueryLifecycle({ appState, netInfo }: QueryLifecycleOptions): () => void;
182
+ /** A failed query or mutation, as `reportQueryErrors` hands it on. */
183
+ type QueryErrorReporter = (error: Error, report: ErrorReport) => void;
184
+ interface ReportQueryErrorsOptions {
185
+ /** True when the device is offline. Default TanStack's `onlineManager`. */
186
+ isOffline?: () => boolean;
187
+ }
188
+ /** The first segment of a query or mutation key, when it is a name; never the ids after it. */
189
+ declare function queryKeyName(key: readonly unknown[] | undefined): string | undefined;
190
+ /**
191
+ * Hand every query and mutation that failed for good (after its retries) to
192
+ * `report`, as a non-fatal `query` or `mutation` error tagged with the key's
193
+ * first segment (`query.key: "tasks"`), never the ids after it.
194
+ *
195
+ * Only errors worth a report (`classifyError(e).report`): being offline,
196
+ * signed out, a record that's gone and the server's expected refusals
197
+ * (forbidden, conflict, a rejected value) are the screen's to show, not
198
+ * bugs. A cancelled query is never reported. One query or mutation opts out
199
+ * with `meta: { reportErrors: false }`.
200
+ *
201
+ * Works on any client (it subscribes to the caches), so it covers a client
202
+ * the app passed in too. Returns the unsubscribe.
203
+ *
204
+ * @stability Beta
205
+ */
206
+ declare function reportQueryErrors(client: QueryClient, report: QueryErrorReporter, options?: ReportQueryErrorsOptions): () => void;
207
+
208
+ export { type AsyncStorageLike as A, DAY_MS as D, type EnableRejectionTracker as E, FatalScreen as F, GenesisErrorBoundary as G, type NetInfoLike as N, type OnError as O, PlainFatalScreen as P, type QueryErrorReporter as Q, type ReportQueryErrorsOptions as R, type AppStateLike as a, type ErrorReport as b, type ErrorUtilsLike as c, type FatalScreenProps as d, type GenesisErrorBoundaryProps as e, type GlobalErrorHandlerOptions as f, type QueryLifecycleOptions as g, type QueryPersistence as h, connectQueryLifecycle as i, createNativeQueryClient as j, defaultErrorUtils as k, defaultRejectionTracker as l, errorDetails as m, installGlobalErrorHandler as n, installRejectionTracker as o, queryKeyName as q, reportQueryErrors as r };
@@ -0,0 +1,43 @@
1
+ import * as react from 'react';
2
+ import { ReactNode, ComponentType } from 'react';
3
+ import { O as OnError } from './query-DobJyRvs.js';
4
+
5
+ /** What Expo Router gives a route's `ErrorBoundary`: the error, and `retry` to render the route again. */
6
+ interface ScreenErrorProps {
7
+ error: Error;
8
+ retry: () => Promise<void>;
9
+ }
10
+ /** The default screen fallback: the screen hit a problem, and "Try again". @stability Beta */
11
+ declare function ScreenErrorScreen({ error, retry }: ScreenErrorProps): react.JSX.Element;
12
+ interface ScreenErrorBoundaryOptions {
13
+ /** What to show. Default `ScreenErrorScreen`. */
14
+ fallback?: ComponentType<ScreenErrorProps>;
15
+ /** Where the error goes. Default `reportError` from genesis-core (the observability block, when it is on). */
16
+ onError?: OnError;
17
+ /** Wrappers around the route boundary, innermost first (Sentry's `wrapExpoRouterErrorBoundary`). */
18
+ wrap?: readonly ((boundary: ComponentType<ScreenErrorProps>) => ComponentType<ScreenErrorProps>)[];
19
+ }
20
+ /**
21
+ * An Expo Router `ErrorBoundary`: reports each error once (non-fatal, source
22
+ * `screen`) and shows `fallback`. Build it once, at module scope.
23
+ *
24
+ * @stability Beta
25
+ */
26
+ declare function createScreenErrorBoundary(options?: ScreenErrorBoundaryOptions): ComponentType<ScreenErrorProps>;
27
+ interface ScreenErrorBoundaryProps {
28
+ children?: ReactNode;
29
+ fallback?: ComponentType<ScreenErrorProps>;
30
+ /** Default `reportError` from genesis-core. */
31
+ onError?: OnError;
32
+ /** Change it to clear a caught error. */
33
+ resetKey?: unknown;
34
+ }
35
+ /**
36
+ * A boundary around part of a screen tree, for apps without Expo Router's
37
+ * per-route boundaries: non-fatal, reported, with "Try again".
38
+ *
39
+ * @stability Beta
40
+ */
41
+ declare function ScreenErrorBoundary({ children, fallback, onError, resetKey }: ScreenErrorBoundaryProps): react.JSX.Element;
42
+
43
+ export { ScreenErrorBoundary as S, type ScreenErrorBoundaryOptions as a, type ScreenErrorBoundaryProps as b, type ScreenErrorProps as c, ScreenErrorScreen as d, createScreenErrorBoundary as e };
package/dist/updates.d.ts CHANGED
@@ -1,13 +1,13 @@
1
- export { b5 as ApplicationLike, b6 as CLOCK_SKEW_MS, b7 as ChannelSwitchResult, b8 as ChannelSwitcher, b9 as ChannelSwitcherOptions, ba as EvaluatePolicyOptions, bb as ForceUpgradeProps, bc as ForceUpgradeScreen, bd as MaintenanceProps, be as MaintenanceScreen, bf as PolicyClientLike, bg as PolicyOrigin, bh as PolicyState, bi as PolicyStore, bj as PolicyStoreOptions, bk as ReleaseNote, bl as ReloadGuard, bm as SupabasePolicySourceOptions, bn as UPDATES_BLOCK_ID, bo as UpdateBanner, bp as UpdateBannerProps, bq as UpdateCheckState, br as UpdateCheckStatus, bs as UpdateChecker, bt as UpdateCheckerOptions, bu as UpdatePlatform, bv as UpdatePolicy, bw as UpdatePolicySource, bx as UpdateVerdict, by as UpdatesAppStateLike, U as UpdatesBlock, bz as UpdatesErrorSource, bA as UpdatesModuleLike, bB as UpdatesOnError, bC as UpdatesOptions, bD as UpdatesProvider, bE as UpdatesRoot, bF as UpdatesRootProps, bG as UpdatesSlots, bH as UpdatesStorageLike, V as VersionSignature, bI as VersionSignatureInput, bJ as WEEK_MS, bK as WhatsNewOptions, bL as WhatsNewProps, bM as WhatsNewSheet, bN as WhatsNewState, bO as WhatsNewStore, bP as createChannelSwitcher, bQ as createPolicyStore, bR as createReloadGuard, bS as createUpdateChecker, bT as createUpdates, bU as createWhatsNewStore, bV as evaluatePolicy, bW as notesSince, bX as sanitizePolicy, bY as staticPolicySource, bZ as supabasePolicySource, b_ as useBlockReload, b$ as useCanReload, c0 as useForceUpgrade, c1 as useMaintenance, c2 as useUpdateBanner, c3 as useUpdateCheck, c4 as useUpdatePolicy, c5 as useUpdateVerdict, c6 as useUpdates, c7 as useVersionSignature, c8 as useWhatsNew, c9 as versionSignature } from './blocks-C2RDpvaN.js';
1
+ export { aT as ApplicationLike, aU as CLOCK_SKEW_MS, aV as ChannelSwitchResult, aW as ChannelSwitcher, aX as ChannelSwitcherOptions, aY as EvaluatePolicyOptions, aZ as ForceUpgradeProps, a_ as ForceUpgradeScreen, a$ as MaintenanceProps, b0 as MaintenanceScreen, b1 as PolicyClientLike, b2 as PolicyOrigin, b3 as PolicyState, b4 as PolicyStore, b5 as PolicyStoreOptions, b6 as ReleaseNote, b7 as ReloadGuard, b8 as SupabasePolicySourceOptions, b9 as UPDATES_BLOCK_ID, ba as UpdateBanner, bb as UpdateBannerProps, bc as UpdateCheckState, bd as UpdateCheckStatus, be as UpdateChecker, bf as UpdateCheckerOptions, bg as UpdatePlatform, bh as UpdatePolicy, bi as UpdatePolicySource, bj as UpdateVerdict, bk as UpdatesAppStateLike, U as UpdatesBlock, bl as UpdatesErrorSource, bm as UpdatesModuleLike, bn as UpdatesOnError, bo as UpdatesOptions, bp as UpdatesProvider, bq as UpdatesRoot, br as UpdatesRootProps, bs as UpdatesSlots, bt as UpdatesStorageLike, V as VersionSignature, bu as VersionSignatureInput, bv as WEEK_MS, bw as WhatsNewOptions, bx as WhatsNewProps, by as WhatsNewSheet, bz as WhatsNewState, bA as WhatsNewStore, bB as createChannelSwitcher, bC as createPolicyStore, bD as createReloadGuard, bE as createUpdateChecker, bF as createUpdates, bG as createWhatsNewStore, bH as evaluatePolicy, bI as notesSince, bJ as sanitizePolicy, bK as staticPolicySource, bL as supabasePolicySource, bM as useBlockReload, bN as useCanReload, bO as useForceUpgrade, bP as useMaintenance, bQ as useUpdateBanner, bR as useUpdateCheck, bS as useUpdatePolicy, bT as useUpdateVerdict, bU as useUpdates, bV as useVersionSignature, bW as useWhatsNew, bX as versionSignature } from './blocks-CyXjSGwV.js';
2
2
  import 'react';
3
3
  import '@marktiderman/genesis-core/slots';
4
4
  import '@marktiderman/genesis-features/blocks';
5
+ import './query-DobJyRvs.js';
5
6
  import '@tanstack/react-query';
6
7
  import '@marktiderman/genesis-design-system';
7
8
  import '@marktiderman/genesis-core/provider';
8
9
  import '@marktiderman/genesis-ui-native/layouts';
9
10
  import '@marktiderman/genesis-ui-native/components';
10
- import './query-DUmVAfsF.js';
11
11
 
12
12
  /**
13
13
  * Version numbers: the store version an app reports (`1.4.0`, `1.10`) and
package/dist/updates.js CHANGED
@@ -1,6 +1,7 @@
1
1
  import { createStore, delay } from './chunk-XE7LC7K6.js';
2
2
  import { versionSignature } from './chunk-6BT4PTGH.js';
3
3
  export { versionSignature } from './chunk-6BT4PTGH.js';
4
+ import { runBeforeReload } from './chunk-VIC2KXMA.js';
4
5
  import { createContext, useContext, useEffect, useSyncExternalStore, useMemo, useState } from 'react';
5
6
  import { View } from 'react-native';
6
7
  import { renderSlot } from '@marktiderman/genesis-core/slots';
@@ -131,6 +132,7 @@ function createUpdateChecker(options) {
131
132
  }
132
133
  store.setState({ status: "reloading", blocked: false });
133
134
  try {
135
+ await runBeforeReload();
134
136
  await updates.reloadAsync(reloadScreenOptions ? { reloadScreenOptions } : void 0);
135
137
  return true;
136
138
  } catch (raw) {
@@ -179,6 +181,7 @@ function createChannelSwitcher(options) {
179
181
  const check = await u.checkForUpdateAsync();
180
182
  if (check.isAvailable || check.isRollBackToEmbedded) await u.fetchUpdateAsync();
181
183
  if (!guard.canReload()) return { kind: "blocked" };
184
+ await runBeforeReload();
182
185
  await u.reloadAsync(reloadScreenOptions ? { reloadScreenOptions } : void 0);
183
186
  return { kind: "reloading" };
184
187
  } catch (raw) {