@colixsystems/widget-sdk 0.228.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,39 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.228.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)
+
+**A field's focus ring and a card's border stay inside the widget.** The hosts clip a widget at its own edge, so anything painted outside it is cut off.
+
+- **`<TextField>` and the `<Select>` trigger draw focus inside their own box.** A focused field shows a 2px ring in the accent: its border plus an inset 1px `boxShadow`, in the error colour while the field is invalid. On the web it turns the browser's outer focus outline off, because that outline sat outside the field and was cut off wherever the field touched the widget's edge. `<SearchField>` and the built-in form fields use the same field, so they get it too. The text field also takes `minWidth: 0`, so it shrinks in a row instead of pushing its neighbour past the edge. A caller's `style` still comes last.
+- **New linter rule `full-width-margin-overflow` (severity `warning`, non-blocking).** It flags a style object that sets `width: "100%"` together with a non-zero side margin (`margin`, `marginHorizontal`, `marginLeft`/`Right`/`Start`/`End`, `marginInline`/`InlineStart`/`InlineEnd`; a zero, `undefined` or `null` value is not counted). The percentage is already the parent's whole width, so the margin pushes the box past its parent and the host cuts off its right edge, border included. Drop the width, because a `View` already stretches, and inset with the parent's `padding`. The scan reads one style literal, not the tree, so it stays a warning. Comments are not scanned.
+
+`CONTRACT` is unchanged (no new field), and no export changed signature.
 
 ### What's new in 0.228.0 (contract 1.184.0)
 

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/form-control-tokens.js

@@ -71,6 +71,26 @@ export function focusHaloStyle(t, focused, radius) {
   };
 }
 
+// Web: a field shell draws its own ring, so the host's outer one stays off.
+export const FIELD_OUTLINE_OFF = Object.freeze({ outlineColor: "transparent" });
+
+/**
+ * A field shell's state border (`<TextField>`, a `<Select>` trigger). Focus is
+ * the border plus an inset 1px ring, 2px in all and inside the box, so a parent
+ * clipping at the field's edge cannot cut it. An invalid field rings in the
+ * error colour while it is being fixed.
+ *
+ * @param {object} t — resolved form-control tokens.
+ * @param {{focused: boolean, invalid: boolean}} state
+ */
+export function fieldStateStyle(t, { focused, invalid }) {
+  if (focused) {
+    const color = invalid ? t.errorColor : t.focusColor;
+    return { borderColor: color, boxShadow: `inset 0 0 0 1px ${color}` };
+  }
+  return invalid ? { borderColor: t.errorColor } : null;
+}
+
 /**
  * The colours a switch hands the platform control. A caller's `trackColor`
  * overrides the theme per state, and iOS, which paints the off track from

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/dist/linter.cjs

@@ -1477,6 +1477,92 @@ function _flexBasisPercentRules(source) {
   return findings;
 }
 
+// sc-11277 — `width: "100%"` plus a side margin is wider than its parent.
+//
+// The percentage is the parent's whole content width and the margin is added
+// outside it, so the box overflows by the margin. The hosts clip a widget at
+// its own edge (the Player's sideways guard, a fixed-height slot), which cuts
+// off the right edge of a bordered card or input. A `View` already stretches
+// across a column, so the width is redundant; the inset belongs in the
+// parent's padding.
+//
+// A warning: the scan reads one style literal, not the tree, so a row parent
+// that absorbs the excess still matches.
+const _FULL_WIDTH_RE = /\bwidth\s*:\s*(["'`])100%\1/g;
+const _SIDE_MARGIN_KEY_RE =
+  /\bmargin(?:Horizontal|Left|Right|Start|End|Inline(?:Start|End)?)?\s*:/g;
+const _ZERO_VALUE_RE =
+  /^\s*(?:(["'`]?)-?0(?:\.0*)?(?:px)?\1\s*(?:[,}]|$)|(?:undefined|null)\b)/m;
+
+// The innermost `{ … }` around `at`, as [start, end); null outside any.
+function _enclosingObject(code, at) {
+  let start = -1;
+  for (let i = at - 1, depth = 0; i >= 0; i--) {
+    if (code[i] === "}") depth++;
+    else if (code[i] === "{" && depth-- === 0) {
+      start = i;
+      break;
+    }
+  }
+  if (start < 0) return null;
+  for (let j = at, depth = 0; j < code.length; j++) {
+    if (code[j] === "{") depth++;
+    else if (code[j] === "}" && depth-- === 0) return [start, j + 1];
+  }
+  return null;
+}
+
+// The object's own keys only: a nested object's margin is not this box's.
+// Blanked rather than cut, so an offset here is the same offset in the source.
+function _ownKeysMask(structure, [start, end]) {
+  let body = structure.slice(start, end);
+  let previous;
+  do {
+    previous = body;
+    body = body.replace(/(?<!^)\{[^{}]*\}(?!$)/g, (nested) => " ".repeat(nested.length));
+  } while (body !== previous);
+  return body;
+}
+
+function _hasSideMargin(code, structure, span) {
+  const keys = _ownKeysMask(structure, span);
+  _SIDE_MARGIN_KEY_RE.lastIndex = 0;
+  let key;
+  while ((key = _SIDE_MARGIN_KEY_RE.exec(keys))) {
+    const valueAt = span[0] + key.index + key[0].length;
+    if (!_ZERO_VALUE_RE.test(code.slice(valueAt, valueAt + 40))) return true;
+  }
+  return false;
+}
+
+function _fullWidthMarginRules(source) {
+  const findings = [];
+  const code = _stripNonCode(source, { keepStrings: true });
+  // Strings blanked, so a brace inside a literal never unbalances the match.
+  const structure = _stripNonCode(source);
+  const sourceLines = source.split(/\r?\n/);
+  _FULL_WIDTH_RE.lastIndex = 0;
+  let hit;
+  while ((hit = _FULL_WIDTH_RE.exec(code))) {
+    const span = _enclosingObject(structure, hit.index);
+    if (!span) continue;
+    if (!_hasSideMargin(code, structure, span)) continue;
+    const line = code.slice(0, hit.index).split(/\r?\n/).length;
+    findings.push({
+      rule: "full-width-margin-overflow",
+      severity: "warning",
+      label:
+        `width: "100%" plus a side margin is wider than the parent by that ` +
+        `margin, so the host clips the box's right edge and its border. Drop ` +
+        `the width (a View already stretches) or move the inset to the ` +
+        `parent's padding.`,
+      line,
+      snippet: (sourceLines[line - 1] || "").trim().slice(0, 200),
+    });
+  }
+  return findings;
+}
+
 // sc-4913 — a measured frame INCLUDES the element's own padding, so cells sized
 // from it overflow the content box and the last one wraps into an empty column.
 // Mirror of linter.js (see there for the full rationale).
@@ -2100,6 +2186,8 @@ function lintSource(source, options) {
   // sc-7274 — soft warning: a percentage flexBasis sizes the main axis, so in a
   // column it claims the parent's whole height and overflows.
   findings.push(..._flexBasisPercentRules(source));
+  // sc-11277 — soft warning: a full-width box with a side margin is clipped.
+  findings.push(..._fullWidthMarginRules(source));
   // sc-4913 — soft warning: a measured width that includes the widget's own
   // padding wraps the last grid column into an empty one.
   findings.push(..._measuredPaddingRules(source));

package/dist/linter.js

@@ -1518,6 +1518,92 @@ function _flexBasisPercentRules(source) {
   return findings;
 }
 
+// sc-11277 — `width: "100%"` plus a side margin is wider than its parent.
+//
+// The percentage is the parent's whole content width and the margin is added
+// outside it, so the box overflows by the margin. The hosts clip a widget at
+// its own edge (the Player's sideways guard, a fixed-height slot), which cuts
+// off the right edge of a bordered card or input. A `View` already stretches
+// across a column, so the width is redundant; the inset belongs in the
+// parent's padding.
+//
+// A warning: the scan reads one style literal, not the tree, so a row parent
+// that absorbs the excess still matches.
+const _FULL_WIDTH_RE = /\bwidth\s*:\s*(["'`])100%\1/g;
+const _SIDE_MARGIN_KEY_RE =
+  /\bmargin(?:Horizontal|Left|Right|Start|End|Inline(?:Start|End)?)?\s*:/g;
+const _ZERO_VALUE_RE =
+  /^\s*(?:(["'`]?)-?0(?:\.0*)?(?:px)?\1\s*(?:[,}]|$)|(?:undefined|null)\b)/m;
+
+// The innermost `{ … }` around `at`, as [start, end); null outside any.
+function _enclosingObject(code, at) {
+  let start = -1;
+  for (let i = at - 1, depth = 0; i >= 0; i--) {
+    if (code[i] === "}") depth++;
+    else if (code[i] === "{" && depth-- === 0) {
+      start = i;
+      break;
+    }
+  }
+  if (start < 0) return null;
+  for (let j = at, depth = 0; j < code.length; j++) {
+    if (code[j] === "{") depth++;
+    else if (code[j] === "}" && depth-- === 0) return [start, j + 1];
+  }
+  return null;
+}
+
+// The object's own keys only: a nested object's margin is not this box's.
+// Blanked rather than cut, so an offset here is the same offset in the source.
+function _ownKeysMask(structure, [start, end]) {
+  let body = structure.slice(start, end);
+  let previous;
+  do {
+    previous = body;
+    body = body.replace(/(?<!^)\{[^{}]*\}(?!$)/g, (nested) => " ".repeat(nested.length));
+  } while (body !== previous);
+  return body;
+}
+
+function _hasSideMargin(code, structure, span) {
+  const keys = _ownKeysMask(structure, span);
+  _SIDE_MARGIN_KEY_RE.lastIndex = 0;
+  let key;
+  while ((key = _SIDE_MARGIN_KEY_RE.exec(keys))) {
+    const valueAt = span[0] + key.index + key[0].length;
+    if (!_ZERO_VALUE_RE.test(code.slice(valueAt, valueAt + 40))) return true;
+  }
+  return false;
+}
+
+function _fullWidthMarginRules(source) {
+  const findings = [];
+  const code = _stripNonCode(source, { keepStrings: true });
+  // Strings blanked, so a brace inside a literal never unbalances the match.
+  const structure = _stripNonCode(source);
+  const sourceLines = source.split(/\r?\n/);
+  _FULL_WIDTH_RE.lastIndex = 0;
+  let hit;
+  while ((hit = _FULL_WIDTH_RE.exec(code))) {
+    const span = _enclosingObject(structure, hit.index);
+    if (!span) continue;
+    if (!_hasSideMargin(code, structure, span)) continue;
+    const line = code.slice(0, hit.index).split(/\r?\n/).length;
+    findings.push({
+      rule: "full-width-margin-overflow",
+      severity: "warning",
+      label:
+        `width: "100%" plus a side margin is wider than the parent by that ` +
+        `margin, so the host clips the box's right edge and its border. Drop ` +
+        `the width (a View already stretches) or move the inset to the ` +
+        `parent's padding.`,
+      line,
+      snippet: (sourceLines[line - 1] || "").trim().slice(0, 200),
+    });
+  }
+  return findings;
+}
+
 // sc-4913 — a measured frame INCLUDES the element's own padding.
 //
 // `onLayout` reports the frame width, and padding sits inside that frame. A
@@ -2168,6 +2254,8 @@ export function lintSource(source, options) {
   // sc-7274 — soft warning: a percentage flexBasis sizes the main axis, so in a
   // column it claims the parent's whole height and overflows.
   findings.push(..._flexBasisPercentRules(source));
+  // sc-11277 — soft warning: a full-width box with a side margin is clipped.
+  findings.push(..._fullWidthMarginRules(source));
   // sc-4913 — soft warning: a measured width that includes the widget's own
   // padding wraps the last grid column into an empty one.
   findings.push(..._measuredPaddingRules(source));

package/dist/select-view.js

@@ -13,6 +13,8 @@ import { Icon } from "./icon.js";
 import { TEXT_FIELD_TOKEN_NAMES } from "./text-field-tokens.js";
 import {
   CONTROL_MIN_TARGET,
+  FIELD_OUTLINE_OFF,
+  fieldStateStyle,
   nextOptionIndex,
   resolveFormControlTokens,
   selectedOption,
@@ -253,8 +255,8 @@ export function makeSelect(rn) {
               borderRadius: t.radius,
               backgroundColor: t.background,
             },
-            focused ? { borderColor: t.focusColor } : null,
-            invalid ? { borderColor: t.errorColor } : null,
+            FIELD_OUTLINE_OFF,
+            fieldStateStyle(t, { focused, invalid }),
             style,
           ],
         },

package/dist/text-field-view.js

@@ -6,7 +6,11 @@ import React from "react";
 import { useHostTheme } from "./hooks.js";
 import { DEFAULT_THEME_TOKENS } from "./_theme-tokens.js";
 import { TEXT_FIELD_TOKEN_NAMES } from "./text-field-tokens.js";
-import { resolveFormControlTokens } from "./form-control-tokens.js";
+import {
+  FIELD_OUTLINE_OFF,
+  fieldStateStyle,
+  resolveFormControlTokens,
+} from "./form-control-tokens.js";
 import {
   errorMessage,
   hasNote,
@@ -45,7 +49,6 @@ export function makeTextField(rn) {
       ...others
     } = props;
     const theme = useHostTheme() || DEFAULT_THEME_TOKENS;
-    // Native draws no focus ring, so the border itself shows focus.
     const [focused, setFocused] = React.useState(false);
     const overrides = {};
     const rest = {};
@@ -80,10 +83,11 @@ export function makeTextField(rn) {
           color: t.textColor,
           fontFamily: t.fontFamily,
           fontSize: t.fontSize,
+          // An input will not shrink below its text width in a row otherwise.
+          minWidth: 0,
         },
-        focused ? { borderColor: t.focusColor } : null,
-        // After focus: an invalid field stays marked while it is being fixed.
-        invalid ? { borderColor: t.errorColor } : null,
+        FIELD_OUTLINE_OFF,
+        fieldStateStyle(t, { focused, invalid }),
         // The frame dims a framed field as a whole.
         disabled && !framed ? { opacity: t.disabledOpacity } : null,
         style,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.228.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,