@use-voltra/core 2.3.0 → 2.3.2

package/build/cjs/index.js

@@ -20,5 +20,6 @@ __exportStar(require("./payload.js"), exports);
 __exportStar(require("./payload/short-names.js"), exports);
 __exportStar(require("./renderer/index.js"), exports);
 __exportStar(require("./types.js"), exports);
+__exportStar(require("./useUpdateOnHMR.js"), exports);
 __exportStar(require("./widget-environment.js"), exports);
 //# sourceMappingURL=index.js.map

package/build/cjs/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,sDAAmC;AACnC,iEAA8C;AAC9C,+CAA4B;AAC5B,2DAAwC;AACxC,sDAAmC;AACnC,6CAA0B;AAC1B,0DAAuC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,sDAAmC;AACnC,iEAA8C;AAC9C,+CAA4B;AAC5B,2DAAwC;AACxC,sDAAmC;AACnC,6CAA0B;AAC1B,sDAAmC;AACnC,0DAAuC"}

package/build/cjs/useUpdateOnHMR.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useUpdateOnHMR = void 0;
+const react_1 = require("react");
+const fastRefreshHub_js_1 = require("./fastRefreshHub.js");
+/**
+ * Force the calling component to re-render whenever Metro applies a Fast Refresh
+ * patch, so freshly patched Voltra payloads are re-rendered. Shared by the iOS and
+ * Android client packages; relies on the process-wide {@link FastRefreshHub}.
+ */
+const useUpdateOnHMR = () => {
+    const [, forceUpdate] = (0, react_1.useState)(0);
+    (0, react_1.useEffect)(() => {
+        if (!__DEV__) {
+            return;
+        }
+        return (0, fastRefreshHub_js_1.getFastRefreshHub)().onPatch(() => {
+            forceUpdate((prev) => prev + 1);
+        });
+    }, []);
+};
+exports.useUpdateOnHMR = useUpdateOnHMR;
+//# sourceMappingURL=useUpdateOnHMR.js.map

package/build/cjs/useUpdateOnHMR.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useUpdateOnHMR.js","sourceRoot":"","sources":["../../src/useUpdateOnHMR.ts"],"names":[],"mappings":";;;AAAA,iCAA2C;AAE3C,2DAAuD;AAIvD;;;;GAIG;AACI,MAAM,cAAc,GAAG,GAAG,EAAE;IACjC,MAAM,CAAC,EAAE,WAAW,CAAC,GAAG,IAAA,gBAAQ,EAAC,CAAC,CAAC,CAAA;IAEnC,IAAA,iBAAS,EAAC,GAAG,EAAE;QACb,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,OAAM;QACR,CAAC;QAED,OAAO,IAAA,qCAAiB,GAAE,CAAC,OAAO,CAAC,GAAG,EAAE;YACtC,WAAW,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,GAAG,CAAC,CAAC,CAAA;QACjC,CAAC,CAAC,CAAA;IACJ,CAAC,EAAE,EAAE,CAAC,CAAA;AACR,CAAC,CAAA;AAZY,QAAA,cAAc,kBAY1B"}

package/build/esm/index.js

@@ -4,5 +4,6 @@ export * from './payload.js';
 export * from './payload/short-names.js';
 export * from './renderer/index.js';
 export * from './types.js';
+export * from './useUpdateOnHMR.js';
 export * from './widget-environment.js';
 //# sourceMappingURL=index.js.map

package/build/esm/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAA;AACnC,cAAc,gCAAgC,CAAA;AAC9C,cAAc,cAAc,CAAA;AAC5B,cAAc,0BAA0B,CAAA;AACxC,cAAc,qBAAqB,CAAA;AACnC,cAAc,YAAY,CAAA;AAC1B,cAAc,yBAAyB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAA;AACnC,cAAc,gCAAgC,CAAA;AAC9C,cAAc,cAAc,CAAA;AAC5B,cAAc,0BAA0B,CAAA;AACxC,cAAc,qBAAqB,CAAA;AACnC,cAAc,YAAY,CAAA;AAC1B,cAAc,qBAAqB,CAAA;AACnC,cAAc,yBAAyB,CAAA"}

package/build/esm/useUpdateOnHMR.js

@@ -0,0 +1,19 @@
+import { useEffect, useState } from 'react';
+import { getFastRefreshHub } from './fastRefreshHub.js';
+/**
+ * Force the calling component to re-render whenever Metro applies a Fast Refresh
+ * patch, so freshly patched Voltra payloads are re-rendered. Shared by the iOS and
+ * Android client packages; relies on the process-wide {@link FastRefreshHub}.
+ */
+export const useUpdateOnHMR = () => {
+    const [, forceUpdate] = useState(0);
+    useEffect(() => {
+        if (!__DEV__) {
+            return;
+        }
+        return getFastRefreshHub().onPatch(() => {
+            forceUpdate((prev) => prev + 1);
+        });
+    }, []);
+};
+//# sourceMappingURL=useUpdateOnHMR.js.map

package/build/esm/useUpdateOnHMR.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useUpdateOnHMR.js","sourceRoot":"","sources":["../../src/useUpdateOnHMR.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAA;AAE3C,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA;AAIvD;;;;GAIG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,GAAG,EAAE;IACjC,MAAM,CAAC,EAAE,WAAW,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAA;IAEnC,SAAS,CAAC,GAAG,EAAE;QACb,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,OAAM;QACR,CAAC;QAED,OAAO,iBAAiB,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE;YACtC,WAAW,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,GAAG,CAAC,CAAC,CAAA;QACjC,CAAC,CAAC,CAAA;IACJ,CAAC,EAAE,EAAE,CAAC,CAAA;AACR,CAAC,CAAA"}

package/build/types/index.d.ts

@@ -4,5 +4,6 @@ export * from './payload.js';
 export * from './payload/short-names.js';
 export * from './renderer/index.js';
 export * from './types.js';
+export * from './useUpdateOnHMR.js';
 export * from './widget-environment.js';
 //# sourceMappingURL=index.d.ts.map

package/build/types/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAA;AACnC,cAAc,gCAAgC,CAAA;AAC9C,cAAc,cAAc,CAAA;AAC5B,cAAc,0BAA0B,CAAA;AACxC,cAAc,qBAAqB,CAAA;AACnC,cAAc,YAAY,CAAA;AAC1B,cAAc,yBAAyB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAA;AACnC,cAAc,gCAAgC,CAAA;AAC9C,cAAc,cAAc,CAAA;AAC5B,cAAc,0BAA0B,CAAA;AACxC,cAAc,qBAAqB,CAAA;AACnC,cAAc,YAAY,CAAA;AAC1B,cAAc,qBAAqB,CAAA;AACnC,cAAc,yBAAyB,CAAA"}

package/build/types/types.d.ts

@@ -9,4 +9,85 @@ export type VoltraElementRef = {
     $r: number;
 };
 export type VoltraNodeJson = VoltraElementJson | VoltraElementJson[] | VoltraElementRef | string;
+export type EventSubscription = {
+    remove: () => void;
+};
+type PreloadImageBaseOptions = {
+    key: string;
+    width?: number;
+    height?: number;
+};
+export type PreloadImageUrlOptions = PreloadImageBaseOptions & {
+    url: string;
+    method?: 'GET' | 'POST' | 'PUT';
+    headers?: Record<string, string>;
+};
+export type PreloadImageSvgOptions = PreloadImageBaseOptions & {
+    svg: string;
+};
+export type PreloadImageOptions = PreloadImageUrlOptions | PreloadImageSvgOptions;
+export type PreloadImageFailure = {
+    key: string;
+    error: string;
+};
+export type PreloadImagesResult = {
+    succeeded: string[];
+    failed: PreloadImageFailure[];
+};
+/**
+ * @deprecated Use `setWidgetServerUpdate` with an `Authorization` header instead. These are
+ * stored in the same place and keep the same replace-the-whole-set semantics.
+ */
+export type WidgetServerCredentials = {
+    token: string;
+    headers?: Record<string, string>;
+};
+/**
+ * Runtime overrides for a widget's `serverUpdate` settings — the twin of the `serverUpdate` key
+ * in app.json, which supplies the defaults.
+ *
+ * Every field is optional and replaces the app.json value when set. `headers` and `query` merge
+ * per key across layers; everything else takes the value from the most specific layer that sets
+ * it. Passing settings without a `widgetId` sets them for every server-driven widget.
+ */
+export type WidgetServerUpdateSettings = {
+    /** Endpoint to fetch from. Must be https, or http to a local dev host in a debug build. */
+    url?: string;
+    /** How often to fetch, in minutes. Clamped to at least 15 and at most 24 hours. */
+    intervalMinutes?: number;
+    /** Set false to stop fetching and drive the widget from the app instead. Defaults to true. */
+    enabled?: boolean;
+    /** HTTP method. Defaults to GET. A body is dropped on GET and HEAD, with a warning. */
+    method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    /** Extra query parameters. Voltra's own keys are reserved and rejected. */
+    query?: Record<string, string>;
+    /** Extra request headers, for example `Authorization`. */
+    headers?: Record<string, string>;
+    /** Request body, sent as `application/json`. */
+    body?: WidgetServerUpdateBody;
+};
+/** A JSON value, as accepted for a server-update request body. */
+export type WidgetServerUpdateBody = string | number | boolean | null | WidgetServerUpdateBody[] | {
+    [key: string]: WidgetServerUpdateBody;
+};
+/** Options selecting which widget a settings call applies to. */
+export type WidgetServerUpdateOptions = {
+    /** Widget id to scope the settings to. Omit to set them for every server-driven widget. */
+    widgetId?: string;
+};
+/**
+ * Fully resolved settings for one widget: every layer flattened and app.json's defaults applied,
+ * exactly what it would fetch with right now.
+ */
+export type WidgetServerUpdateSnapshot = {
+    /** Absent when the widget is server-driven but has no URL yet. */
+    url?: string;
+    intervalMinutes: number;
+    enabled: boolean;
+    method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    query: Record<string, string>;
+    headers: Record<string, string>;
+    body?: WidgetServerUpdateBody;
+};
+export {};
 //# sourceMappingURL=types.d.ts.map

package/build/types/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,cAAc,CAAA;AAE/E,MAAM,MAAM,iBAAiB,GAAG;IAC9B,CAAC,EAAE,MAAM,CAAA;IACT,CAAC,CAAC,EAAE,MAAM,CAAA;IACV,CAAC,CAAC,EAAE,cAAc,CAAA;IAClB,CAAC,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAA;CACpC,CAAA;AAED,MAAM,MAAM,gBAAgB,GAAG;IAC7B,EAAE,EAAE,MAAM,CAAA;CACX,CAAA;AAED,MAAM,MAAM,cAAc,GAAG,iBAAiB,GAAG,iBAAiB,EAAE,GAAG,gBAAgB,GAAG,MAAM,CAAA"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"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"}

package/build/types/useUpdateOnHMR.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Force the calling component to re-render whenever Metro applies a Fast Refresh
+ * patch, so freshly patched Voltra payloads are re-rendered. Shared by the iOS and
+ * Android client packages; relies on the process-wide {@link FastRefreshHub}.
+ */
+export declare const useUpdateOnHMR: () => void;
+//# sourceMappingURL=useUpdateOnHMR.d.ts.map

package/build/types/useUpdateOnHMR.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useUpdateOnHMR.d.ts","sourceRoot":"","sources":["../../src/useUpdateOnHMR.ts"],"names":[],"mappings":"AAMA;;;;GAIG;AACH,eAAO,MAAM,cAAc,YAY1B,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@use-voltra/core",
-  "version": "2.3.0",
+  "version": "2.3.2",
   "description": "Generic renderer and payload utilities for Voltra",
   "main": "build/cjs/index.js",
   "module": "build/esm/index.js",

package/src/index.ts

@@ -4,4 +4,5 @@ export * from './payload.js'
 export * from './payload/short-names.js'
 export * from './renderer/index.js'
 export * from './types.js'
+export * from './useUpdateOnHMR.js'
 export * from './widget-environment.js'

package/src/types.ts

@@ -12,3 +12,99 @@ export type VoltraElementRef = {
 }
 
 export type VoltraNodeJson = VoltraElementJson | VoltraElementJson[] | VoltraElementRef | string
+
+export type EventSubscription = {
+  remove: () => void
+}
+
+type PreloadImageBaseOptions = {
+  key: string
+  width?: number
+  height?: number
+}
+
+export type PreloadImageUrlOptions = PreloadImageBaseOptions & {
+  url: string
+  method?: 'GET' | 'POST' | 'PUT'
+  headers?: Record<string, string>
+}
+
+export type PreloadImageSvgOptions = PreloadImageBaseOptions & {
+  svg: string
+}
+
+export type PreloadImageOptions = PreloadImageUrlOptions | PreloadImageSvgOptions
+
+export type PreloadImageFailure = {
+  key: string
+  error: string
+}
+
+export type PreloadImagesResult = {
+  succeeded: string[]
+  failed: PreloadImageFailure[]
+}
+
+/**
+ * @deprecated Use `setWidgetServerUpdate` with an `Authorization` header instead. These are
+ * stored in the same place and keep the same replace-the-whole-set semantics.
+ */
+export type WidgetServerCredentials = {
+  token: string
+  headers?: Record<string, string>
+}
+
+/**
+ * Runtime overrides for a widget's `serverUpdate` settings — the twin of the `serverUpdate` key
+ * in app.json, which supplies the defaults.
+ *
+ * Every field is optional and replaces the app.json value when set. `headers` and `query` merge
+ * per key across layers; everything else takes the value from the most specific layer that sets
+ * it. Passing settings without a `widgetId` sets them for every server-driven widget.
+ */
+export type WidgetServerUpdateSettings = {
+  /** Endpoint to fetch from. Must be https, or http to a local dev host in a debug build. */
+  url?: string
+  /** How often to fetch, in minutes. Clamped to at least 15 and at most 24 hours. */
+  intervalMinutes?: number
+  /** Set false to stop fetching and drive the widget from the app instead. Defaults to true. */
+  enabled?: boolean
+  /** HTTP method. Defaults to GET. A body is dropped on GET and HEAD, with a warning. */
+  method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'
+  /** Extra query parameters. Voltra's own keys are reserved and rejected. */
+  query?: Record<string, string>
+  /** Extra request headers, for example `Authorization`. */
+  headers?: Record<string, string>
+  /** Request body, sent as `application/json`. */
+  body?: WidgetServerUpdateBody
+}
+
+/** A JSON value, as accepted for a server-update request body. */
+export type WidgetServerUpdateBody =
+  | string
+  | number
+  | boolean
+  | null
+  | WidgetServerUpdateBody[]
+  | { [key: string]: WidgetServerUpdateBody }
+
+/** Options selecting which widget a settings call applies to. */
+export type WidgetServerUpdateOptions = {
+  /** Widget id to scope the settings to. Omit to set them for every server-driven widget. */
+  widgetId?: string
+}
+
+/**
+ * Fully resolved settings for one widget: every layer flattened and app.json's defaults applied,
+ * exactly what it would fetch with right now.
+ */
+export type WidgetServerUpdateSnapshot = {
+  /** Absent when the widget is server-driven but has no URL yet. */
+  url?: string
+  intervalMinutes: number
+  enabled: boolean
+  method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'
+  query: Record<string, string>
+  headers: Record<string, string>
+  body?: WidgetServerUpdateBody
+}

package/src/useUpdateOnHMR.ts

@@ -0,0 +1,24 @@
+import { useEffect, useState } from 'react'
+
+import { getFastRefreshHub } from './fastRefreshHub.js'
+
+declare const __DEV__: boolean | undefined
+
+/**
+ * Force the calling component to re-render whenever Metro applies a Fast Refresh
+ * patch, so freshly patched Voltra payloads are re-rendered. Shared by the iOS and
+ * Android client packages; relies on the process-wide {@link FastRefreshHub}.
+ */
+export const useUpdateOnHMR = () => {
+  const [, forceUpdate] = useState(0)
+
+  useEffect(() => {
+    if (!__DEV__) {
+      return
+    }
+
+    return getFastRefreshHub().onPatch(() => {
+      forceUpdate((prev) => prev + 1)
+    })
+  }, [])
+}