@use-voltra/core 2.3.1 → 2.4.0

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)
+    })
+  }, [])
+}

package/src/widget-environment.ts

@@ -33,8 +33,48 @@ export type WidgetEnvironment<TConfig extends Record<string, unknown> | undefine
    * doesn't expose it (rare). */
   colorScheme?: 'light' | 'dark'
 
-  /** BCP-47 locale tag — for example `"en-US"` or `"pl-PL"`. */
-  locale?: string
+  // ---------------------------------------------------------------------------
+  // Locale and formatting preferences (ADR 0009)
+  // Always pass these explicitly to `Intl` / `toLocale*` calls: the JS runtime's own default
+  // locale and time zone are the process's, which may not match what the widget is drawn for.
+  // ---------------------------------------------------------------------------
+
+  /** BCP-47 locale tag the widget is being drawn in, including Unicode extensions for user
+   * overrides — for example `"pl-PL"` or `"en-US-u-hc-h23"`. On iOS this is the locale the
+   * widget extension resolved from the languages the app declares; see `preferredLanguages`
+   * for the user's full list. */
+  locale: string
+
+  /** The user's ordered language list as BCP-47 tags, independent of what the app or the
+   * widget extension supports. Use it (or `resolveLocale`) to pick a translation. */
+  preferredLanguages: string[]
+
+  /** Language the app asked Voltra to render widgets in with `setDynamicWidgetLocale`.
+   * `undefined` unless the app set one. `resolveLocale` gives it precedence. */
+  appLocale?: string
+
+  /** Writing direction of `locale`. */
+  layoutDirection: 'ltr' | 'rtl'
+
+  /** Effective clock preference, already reconciled with the user's 12/24-hour setting. Pass it
+   * as `hourCycle` to `Intl.DateTimeFormat`. */
+  hourCycle: 'h12' | 'h23'
+
+  /** IANA time zone of the device, for example `"Europe/Warsaw"`. Pass it as `timeZone` to
+   * `Intl.DateTimeFormat` when formatting `date`. */
+  timeZone: string
+
+  /** Measurement system of the user's region. Absent when the platform cannot tell
+   * (Android below API 28). */
+  measurementSystem?: 'metric' | 'us' | 'uk'
+
+  /** Unicode calendar identifier as `Intl` spells it, for example `"gregory"` or
+   * `"japanese"`. */
+  calendar?: string
+
+  /** First day of the week in the user's region: `1` is Sunday, `2` is Monday … `7` is
+   * Saturday (the `Calendar.firstWeekday` / `java.util.Calendar` numbering). */
+  firstDayOfWeek?: 1 | 2 | 3 | 4 | 5 | 6 | 7
 
   // ---------------------------------------------------------------------------
   // iOS-only runtime values