@colixsystems/widget-sdk 0.229.0 → 0.230.0

package/README.md

@@ -45,7 +45,7 @@ The data layer lives in **four separate domain-client packages**, each instantia
 | **CORE** | `useGeolocation(options)` (optional: options) | `{ latitude, longitude, accuracy, loading, error, getCurrentPosition, backgroundSupported, backgroundWatching, startBackgroundWatch, stopBackgroundWatch }` | `ctx.device.geolocation` — no scope. Capture is IMPERATIVE: call `getCurrentPosition()` from a user gesture (a tap), never on mount. Resolves to `{ latitude, longitude, accuracy }`; rejects with `GeolocationError` (`.code` in `PERMISSION_DENIED \| UNAVAILABLE \| TIMEOUT \| UNSUPPORTED \| INTERNAL`). Identical on web (`navigator.geolocation`) and the Expo export (`expo-location`). **Background watch (sc-6450)** — `startBackgroundWatch({ enableHighAccuracy, distanceIntervalMeters, timeIntervalMs })` keeps positions arriving while the app is backgrounded; `stopBackgroundWatch()` releases it. NATIVE-ONLY and opt-in per app: gate the control on `backgroundSupported` (false on web, and in an export whose workspace did not opt in). The watch outlives the widget's mount, and its positions land in the same `latitude`/`longitude`/`accuracy` slots. |
 | **CORE** | `useSpeechToText(options)` (optional: options) | `{ transcript, partial, listening, supported, error, start, stop, abort, reset }` | `ctx.device.speech` — no scope. Dictation with the device's **on-device** recogniser: no audio is uploaded and no AI credit is spent. Capture is IMPERATIVE: call `start()` from a user gesture (a tap), never on mount. `transcript` accumulates finalised speech, `partial` holds the uncommitted guess (needs `options.interimResults`); `stop()` keeps it, `abort()` discards it. Rejects with `SpeechToTextError` (`.code` in `PERMISSION_DENIED \| NO_SPEECH \| LANGUAGE_UNSUPPORTED \| NETWORK \| ABORTED \| UNSUPPORTED \| INTERNAL`). **Gate your mic button on `supported`** — Firefox ships no `SpeechRecognition`. Identical on web (`SpeechRecognition`) and the Expo export (`expo-speech-recognition`). |
 | **CORE** | `useCamera(options)` (optional: options) | `{ asset, loading, error, supported, capture, pick, reset }` | `ctx.device.camera` — no scope. Take a photo (`capture()`) or choose one (`pick()`). Capture is IMPERATIVE: call from a user gesture (a tap), never on mount. Both resolve a normalised `{ uri, name, mimeType, width, height, size, file }`, or **`null` when the user dismisses the picker** — dismissal is not an error, so no `try/catch` is needed on the happy path. Rejects with `CameraError` (`.code` in `PERMISSION_DENIED \| UNSUPPORTED \| INTERNAL`). `asset.file` is already the right upload part for the host, so `fd.append("file", asset.file)` → `ctx.assets.upload(fd)` is ONE code path on both. **Gate your camera button on `supported`.** Identical on web (a live `getUserMedia` preview, phones included; a file input only where getUserMedia is absent) and the Expo export (`expo-image-picker`). |
-| **CORE** | `useI18n()` | `{ t, locale }` | `ctx.i18n` — no scope. `t(key)` resolves the widget-namespaced key (`widget.<id>.<key>`, declared in `manifest.translations`) first, then a **predefined shared key** (`shared.<key>`) when `key` is one of the standard strings (`submit`, `cancel`, `save`, `loading`, …), then the raw key. Use a shared key for an identical default string so it translates once and any per-instance `widget.<id>.<key>` override still wins. |
+| **CORE** | `useI18n()` | `{ t, locale, languages, canSetLocale, setLocale }` | `ctx.i18n` — no scope. `t(key)` resolves the widget-namespaced key (`widget.<id>.<key>`, declared in `manifest.translations`) first, then a **predefined shared key** (`shared.<key>`) when `key` is one of the standard strings (`submit`, `cancel`, `save`, `loading`, …), then the raw key. Use a shared key for an identical default string so it translates once and any per-instance `widget.<id>.<key>` override still wins. `languages` lists the app's active languages (`[{ code, name, is_base }]`); `setLocale(code)` switches the whole app live — saved to a signed-in user's account, kept on the device for a visitor, `null` for the app default. Rejects with `.code` `INVALID_LOCALE` \| `UNSUPPORTED`; `canSetLocale` is false where the host cannot switch (the Builder canvas). |
 | **CORE** | `useTranslate()` | `{ translate, translating, error, language, available }` | `ctx.i18n.translate` — no scope. Machine-translates **user-generated content** (record text, file names, API payloads) into the app user's language; `useI18n().t()` is still the answer for your own copy. `translate(str)` → `Promise<string>`, `translate(str[])` → `Promise<string[]>` in ONE request. Target defaults to the app user's language. Cached per session, per pod, and durably per workspace, so repeat text is free. Limits: 50 segments / 5 000 chars each / 20 000 total. Rejects with `TranslateError`; `available` is false where the host cannot translate. |
 | **CORE** | `useLinkPreview(url)` | `{ preview, loading, error, available }` — `preview` is `{ url, title, description, site_name, image_url } \| null` | `ctx.linkPreviews.get` — no scope. A link's title, description, site name and image, fetched by the platform (the device never contacts the linked site). A page with nothing to show resolves with null fields, not an error — render the plain link. A non-http(s) `url` makes no request. Memoized for up to an hour across widgets; concurrent calls for one URL share a request. `error` is a `LinkPreviewError` (`VALIDATION` \| `AUTH_REQUIRED` \| `RATE_LIMITED` \| `NETWORK` \| `INTERNAL`). `available` is false on a host with no link-preview client |
 | **CORE** | `useStableQuery(buildQuery)` | `T \| undefined` (whatever `buildQuery()` returns) | No context slice, no scope. Keeps `buildQuery()`'s result at a STABLE reference across renders when its (JSON-serialised) content hasn't changed, so `useDatastoreQuery(tableId, useStableQuery(() => ({...})))` replaces a hand-rolled `useMemo` with an easy-to-get-wrong deps array. Never throws: a `buildQuery` that itself throws degrades to a stable `undefined`; a result that can't be diffed (e.g. circular) degrades to "always a new reference". |
@@ -84,7 +84,30 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.229.0` — pre-publish. The package surface (types, function names, export paths) is the v1 contract; runtime behaviour for some hooks is stubbed (each hook documents what's wired and what isn't). It is **not yet published to npm**.
+`v0.230.0` — pre-publish. The package surface (types, function names, export paths) is the v1 contract; runtime behaviour for some hooks is stubbed (each hook documents what's wired and what isn't). It is **not yet published to npm**.
+
+### What's new in 0.230.0 (contract 1.185.0)
+
+**A widget can switch the app's language — `useI18n().setLocale(code)`.** `useI18n()` now also returns `languages`, the app's active languages as `[{ code, name, is_base }]`, and `setLocale(code)`, which switches the whole app to that language at once, with no reload. A signed-in user's choice is saved to their account, so it follows them to other devices; a visitor who is not signed in keeps it on this device. `setLocale(null)` returns to the app's default language. It rejects with an `Error` whose `.code` is `INVALID_LOCALE` (not one of `languages`) or `UNSUPPORTED` (the host cannot switch — the Builder canvas). Gate your controls on `canSetLocale` and render them disabled when it is false. The same on the web Player and the exported app.
+
+```jsx
+import { useI18n, Pressable, Text } from "@colixsystems/widget-sdk";
+
+export default function Languages() {
+  const { languages, locale, setLocale, canSetLocale } = useI18n();
+  return languages.map((l) => (
+    <Pressable
+      key={l.code}
+      disabled={!canSetLocale}
+      onPress={() => setLocale(l.code).catch(() => { /* show "try again" */ })}
+    >
+      <Text>{l.code === locale ? `✓ ${l.name}` : l.name}</Text>
+    </Pressable>
+  ));
+}
+```
+
+AppStudio also ships a ready-made **Language picker** built-in widget on the same hook.
 
 ### What's new in 0.229.0 (contract unchanged)
 

package/dist/contract.cjs

@@ -824,9 +824,21 @@ const HOOKS = [
   {
     name: "useI18n",
     signature: "useI18n()",
+    description:
+      "The app's translations and language. t(key, fallback?) resolves an author-written key; locale is the language the app " +
+      "renders in. The app user can switch it from a widget: languages lists the app's active languages as " +
+      "[{ code, name, is_base }] (empty when the host offers none), and setLocale(code) switches the WHOLE app live, with no " +
+      "reload. A signed-in user's choice is saved to their account; a visitor who is not signed in keeps it on this device. " +
+      "setLocale(null) returns to the app's default language. setLocale resolves once the choice is saved and rejects with " +
+      "an Error whose .code is INVALID_LOCALE (the code is not one of languages) or UNSUPPORTED (this host cannot switch, " +
+      "e.g. the Builder canvas) — always catch it. canSetLocale is false on such a host: render the choices disabled then, never a dead button. " +
+      "Identical on web (Player) and the Expo export.",
     returnShape: {
       t: "(key: string, fallback?: string) => string",
       locale: "string",
+      languages: "Array<{ code: string, name: string, is_base: boolean }>",
+      canSetLocale: "boolean",
+      setLocale: "(code: string | null) => Promise<void>  // rejects with Error .code INVALID_LOCALE | UNSUPPORTED",
     },
     requiredContextSlice: ["i18n.t", "i18n.locale"],
     scopes: null,
@@ -3924,12 +3936,14 @@ const WIDGET_CONTEXT_SHAPE = {
     // available:false (same convention as ctx.toast / ctx.device) rather than
     // throwing at render. Both the web Player and the Expo export inject it.
     description:
-      "{ t(key, fallback?), locale, translate? } — `translate` is the injected " +
+      "{ t(key, fallback?), locale, translate?, languages?, setLocale? } — `translate` is the injected " +
       "@colixsystems/translation-client ({ translate(body), status() }) that backs " +
-      "useTranslate() for user-generated content.",
+      "useTranslate() for user-generated content. `languages` ([{ code, name, is_base }]) and " +
+      "`setLocale(code)` back useI18n()'s language switch (sc-11482); a host that cannot " +
+      "switch omits setLocale.",
     required: true,
     fields: { t: "function", locale: "string" },
-    optionalFields: { translate: "object" },
+    optionalFields: { translate: "object", languages: "array", setLocale: "function" },
   },
   logger: {
     description:
@@ -5978,7 +5992,11 @@ const CONTRACT = deepFreeze({
   //    that section's Fit to screen on), and `useFitScreen()` with its
   //    optional `fitScreen` host hint: the widget is a fit section's surface,
   //    so it drops its own frame. Existing manifests and hosts read false.
-  version: "1.184.0",
+  // 1.185.0: additive (sc-11482) — `useI18n()` also returns `languages`,
+  //    `canSetLocale` and `setLocale(code)`, backed by the optional
+  //    `i18n.languages` / `i18n.setLocale` host slice: a widget can switch
+  //    the app's language. Hosts without them read [] / false.
+  version: "1.185.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -824,9 +824,21 @@ const HOOKS = [
   {
     name: "useI18n",
     signature: "useI18n()",
+    description:
+      "The app's translations and language. t(key, fallback?) resolves an author-written key; locale is the language the app " +
+      "renders in. The app user can switch it from a widget: languages lists the app's active languages as " +
+      "[{ code, name, is_base }] (empty when the host offers none), and setLocale(code) switches the WHOLE app live, with no " +
+      "reload. A signed-in user's choice is saved to their account; a visitor who is not signed in keeps it on this device. " +
+      "setLocale(null) returns to the app's default language. setLocale resolves once the choice is saved and rejects with " +
+      "an Error whose .code is INVALID_LOCALE (the code is not one of languages) or UNSUPPORTED (this host cannot switch, " +
+      "e.g. the Builder canvas) — always catch it. canSetLocale is false on such a host: render the choices disabled then, never a dead button. " +
+      "Identical on web (Player) and the Expo export.",
     returnShape: {
       t: "(key: string, fallback?: string) => string",
       locale: "string",
+      languages: "Array<{ code: string, name: string, is_base: boolean }>",
+      canSetLocale: "boolean",
+      setLocale: "(code: string | null) => Promise<void>  // rejects with Error .code INVALID_LOCALE | UNSUPPORTED",
     },
     requiredContextSlice: ["i18n.t", "i18n.locale"],
     scopes: null,
@@ -3920,12 +3932,14 @@ const WIDGET_CONTEXT_SHAPE = {
     // available:false (same convention as ctx.toast / ctx.device) rather than
     // throwing at render. Both the web Player and the Expo export inject it.
     description:
-      "{ t(key, fallback?), locale, translate? } — `translate` is the injected " +
+      "{ t(key, fallback?), locale, translate?, languages?, setLocale? } — `translate` is the injected " +
       "@colixsystems/translation-client ({ translate(body), status() }) that backs " +
-      "useTranslate() for user-generated content.",
+      "useTranslate() for user-generated content. `languages` ([{ code, name, is_base }]) and " +
+      "`setLocale(code)` back useI18n()'s language switch (sc-11482); a host that cannot " +
+      "switch omits setLocale.",
     required: true,
     fields: { t: "function", locale: "string" },
-    optionalFields: { translate: "object" },
+    optionalFields: { translate: "object", languages: "array", setLocale: "function" },
   },
   logger: {
     description:
@@ -5974,7 +5988,11 @@ const CONTRACT = deepFreeze({
   //    that section's Fit to screen on), and `useFitScreen()` with its
   //    optional `fitScreen` host hint: the widget is a fit section's surface,
   //    so it drops its own frame. Existing manifests and hosts read false.
-  version: "1.184.0",
+  // 1.185.0: additive (sc-11482) — `useI18n()` also returns `languages`,
+  //    `canSetLocale` and `setLocale(code)`, backed by the optional
+  //    `i18n.languages` / `i18n.setLocale` host slice: a widget can switch
+  //    the app's language. Hosts without them read [] / false.
+  version: "1.185.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/hooks.js

@@ -954,17 +954,44 @@ export function useWidgetRoute(initial) {
   return [state, setState];
 }
 
+const NO_LANGUAGES = Object.freeze([]);
+
+function localeError(code, message) {
+  const err = new Error(message);
+  err.code = code;
+  return err;
+}
+
 /**
- * Returns { t, locale }. `t(key, fallback)` resolves `{{t:key}}` against
- * the host's translation table and falls back to `fallback ?? key` when
- * the key is missing. The host's i18n.t may or may not honour the two-arg
- * form; we degrade gracefully either way.
+ * Returns { t, locale, languages, canSetLocale, setLocale }. `t(key,
+ * fallback)` resolves `{{t:key}}` against the host's translation table and
+ * falls back to `fallback ?? key` when the key is missing. The host's i18n.t
+ * may or may not honour the two-arg form; we degrade gracefully either way.
+ *
+ * sc-11482 — `setLocale(code)` switches the whole app through the host's own
+ * language switch (the same one its account screen uses).
  */
 export function useI18n() {
   const ctx = useWidgetContextOrThrow("useI18n");
   const i18n = ctx.i18n || {};
   const locale = typeof i18n.locale === "string" ? i18n.locale : "en";
   const hostT = typeof i18n.t === "function" ? i18n.t : null;
+  const languages = Array.isArray(i18n.languages) ? i18n.languages : NO_LANGUAGES;
+  const hostSetLocale = typeof i18n.setLocale === "function" ? i18n.setLocale : null;
+  // Validated here so both hosts refuse an unknown code identically.
+  const setLocale = useCallback(
+    async (code) => {
+      if (!hostSetLocale) {
+        throw localeError("UNSUPPORTED", "The language cannot be changed here.");
+      }
+      const next = typeof code === "string" && code ? code : null;
+      if (next !== null && !languages.some((l) => l && l.code === next)) {
+        throw localeError("INVALID_LOCALE", `"${next}" is not one of this app's languages.`);
+      }
+      await hostSetLocale(next);
+    },
+    [hostSetLocale, languages],
+  );
   // REQ-L10N-WIDGET: the widget's own manifest translations are stored in the
   // tenant dictionary under `widget.<id>.<key>`. Derive the namespace from the
   // host-provided widget id so the author calls `t("greeting")` and never
@@ -1022,7 +1049,7 @@ export function useI18n() {
     },
     [hostT, widgetId],
   );
-  return { t, locale };
+  return { t, locale, languages, canSetLocale: hostSetLocale !== null, setLocale };
 }
 
 /**

package/dist/index.d.ts

@@ -1961,9 +1961,26 @@ export function useAssetsByTag(
   refetch(): Promise<void>;
 };
 
+/** One of the app's active languages, as `useI18n().languages` lists it. */
+export interface AppLanguage {
+  code: string;
+  name: string;
+  is_base: boolean;
+}
+
+/**
+ * The app's translations and language. `setLocale(code)` switches the whole
+ * app live: a signed-in user's choice is saved to their account, a
+ * visitor's stays on the device, and `null` returns to the app's default.
+ * Rejects with an Error whose `.code` is `INVALID_LOCALE` or `UNSUPPORTED`
+ * (`canSetLocale` is false on a host that cannot switch).
+ */
 export function useI18n(): {
   locale: string;
   t(key: string, fallback?: string): string;
+  languages: AppLanguage[];
+  canSetLocale: boolean;
+  setLocale(code: string | null): Promise<void>;
 };
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.229.0",
+  "version": "0.230.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "homepage": "https://github.com/Colix-AB/AppStudio",
   "type": "module",

package/src/contract.js

@@ -824,9 +824,21 @@ const HOOKS = [
   {
     name: "useI18n",
     signature: "useI18n()",
+    description:
+      "The app's translations and language. t(key, fallback?) resolves an author-written key; locale is the language the app " +
+      "renders in. The app user can switch it from a widget: languages lists the app's active languages as " +
+      "[{ code, name, is_base }] (empty when the host offers none), and setLocale(code) switches the WHOLE app live, with no " +
+      "reload. A signed-in user's choice is saved to their account; a visitor who is not signed in keeps it on this device. " +
+      "setLocale(null) returns to the app's default language. setLocale resolves once the choice is saved and rejects with " +
+      "an Error whose .code is INVALID_LOCALE (the code is not one of languages) or UNSUPPORTED (this host cannot switch, " +
+      "e.g. the Builder canvas) — always catch it. canSetLocale is false on such a host: render the choices disabled then, never a dead button. " +
+      "Identical on web (Player) and the Expo export.",
     returnShape: {
       t: "(key: string, fallback?: string) => string",
       locale: "string",
+      languages: "Array<{ code: string, name: string, is_base: boolean }>",
+      canSetLocale: "boolean",
+      setLocale: "(code: string | null) => Promise<void>  // rejects with Error .code INVALID_LOCALE | UNSUPPORTED",
     },
     requiredContextSlice: ["i18n.t", "i18n.locale"],
     scopes: null,
@@ -3920,12 +3932,14 @@ const WIDGET_CONTEXT_SHAPE = {
     // available:false (same convention as ctx.toast / ctx.device) rather than
     // throwing at render. Both the web Player and the Expo export inject it.
     description:
-      "{ t(key, fallback?), locale, translate? } — `translate` is the injected " +
+      "{ t(key, fallback?), locale, translate?, languages?, setLocale? } — `translate` is the injected " +
       "@colixsystems/translation-client ({ translate(body), status() }) that backs " +
-      "useTranslate() for user-generated content.",
+      "useTranslate() for user-generated content. `languages` ([{ code, name, is_base }]) and " +
+      "`setLocale(code)` back useI18n()'s language switch (sc-11482); a host that cannot " +
+      "switch omits setLocale.",
     required: true,
     fields: { t: "function", locale: "string" },
-    optionalFields: { translate: "object" },
+    optionalFields: { translate: "object", languages: "array", setLocale: "function" },
   },
   logger: {
     description:
@@ -5974,7 +5988,11 @@ const CONTRACT = deepFreeze({
   //    that section's Fit to screen on), and `useFitScreen()` with its
   //    optional `fitScreen` host hint: the widget is a fit section's surface,
   //    so it drops its own frame. Existing manifests and hosts read false.
-  version: "1.184.0",
+  // 1.185.0: additive (sc-11482) — `useI18n()` also returns `languages`,
+  //    `canSetLocale` and `setLocale(code)`, backed by the optional
+  //    `i18n.languages` / `i18n.setLocale` host slice: a widget can switch
+  //    the app's language. Hosts without them read [] / false.
+  version: "1.185.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,