@colixsystems/widget-sdk 0.19.0 → 0.22.0

package/README.md

@@ -22,9 +22,10 @@ The data layer lives in **four separate domain-client packages**, each instantia
 | **CORE** | `useNavigation()` | `{ goTo, goBack, push, replace, back, currentRoute }` | `ctx.navigation` — no scope (external URLs use the `Linking` primitive) |
 | **CORE** | `useWidgetEvent(name)` | `(payload?) => void` | `ctx.events.emit` — no scope |
 | **CORE** | `useChildRenderer()` | `{ renderNode(node) }` | `ctx.renderer` — no scope (prefer the `WidgetTree` component) |
+| **CORE** | `useFill()` | `boolean` | `ctx.fill` — no scope. `true` when the host sized this widget to fill its page-grid tile's reserved height (containers + media fill by default; the author can override per tile). Media-style widgets switch to a `flex: 1` / `height: "100%"` layout; others ignore it. Defaults `false`. |
 | **CORE** | `useClipboard()` | `{ copy, paste, hasContent }` | platform clipboard (web `navigator.clipboard` / native `expo-clipboard`); rejects with `ClipboardError` — no scope |
 | **CORE** | `useToast()` | `{ showToast }` | `ctx.toast.showToast` (falls back to a CustomEvent / console) — no scope |
-| **CORE** | `useI18n()` | `{ t, locale }` | `ctx.i18n` — no scope |
+| **CORE** | `useI18n()` | `{ t, locale }` | `ctx.i18n` — no scope. `t(key)` resolves the widget-namespaced key (`widget.<id>.<key>`, declared in `manifest.translations`) then falls back to the raw key. |
 | **DATASTORE** (`ctx.datastore`) | `useDatastoreQuery(table, options?)` | `{ data, loading, error, refetch }` | `records(table).list` (unwraps `{ data, meta }` to `data: []`) — `datastore.read:*` |
 | **DATASTORE** | `useDatastoreRecord(table, id)` | `{ data, loading, error, refetch }` | `records(table).get` — `datastore.read:<table>` |
 | **DATASTORE** | `useDatastoreSchema(tableId)` | `{ schema, loading, error, refetch }` | `schema(tableId)` — `datastore.read:<table>` |
@@ -44,9 +45,44 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.19.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.22.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.19.0
+### What's new in 0.22.0
+
+**New `valueRef` propertySchema type — bind a widget to a single value in the datastore (REQ-WDG-VALUEREF).**
+
+- **`valueRef`** is a composite picker: the Studio Properties Panel renders three cascading dropdowns — pick a **table**, then a **record**, then a **column** — and the bound widget resolves the one cell. It is the discoverable replacement for hand-typing a `tableRef` + a raw record-id `string` + a `columnRef` separately (the old Field Value shape).
+- **Persisted value is an object** `{ tableId, recordId, column }` (new `ValueRefBinding` type), unlike every other ref type, which is a bare string. A widget reads it with `useDatastoreRecord(value.tableId, value.recordId)` then `record[value.column]`; any missing piece means "no value".
+- **tenant-copy** remaps `tableId` to the copied table and **nulls `recordId`** (records are business data and are never copied), so a copied workspace shows the widget's fallback until the new operator re-picks a record. `column` (a name) is preserved verbatim.
+- The built-in **Field Value** widget now uses `valueRef` (back-compatible: already-saved Field Value widgets that stored `tableId`/`recordId`/`column` as separate props keep rendering).
+- **`CONTRACT.version` → `1.12.0`** (additive: one new optional propertySchema type). No existing export or type changed signature.
+
+### What's new in 0.21.1
+
+**Default theme tokens corrected to the product's advertised brand (fix).**
+
+- **`themeTokens.colors.primary` → `#3b82f6` (blue), `colors.secondary` → `#10b981` (green).** Previously these defaulted to a stale coral/slate that no other surface used — the Theme Settings tab and the Player chrome already advertised the blue/green default. A tenant that never customised its theme therefore rendered widgets (`useTheme().colors.primary`) in coral until a first save persisted the blue, a visible divergence between the unsaved and saved-defaults render. No export, signature, type, or token shape changed — default values only.
+- **`CONTRACT.version` → `1.11.1`.** Patch: a default-value fix; the documented contract (token names + shape) is unchanged.
+
+### What's new in 0.21.0
+
+**Widgets can fill their page-grid tile's height (REQ-LAY-08).**
+
+- **New `useFill()` hook.** Returns a `boolean` — `true` when the host has sized this widget to fill the available height of its layout slot (a page-grid tile whose author chose "Fill tile height", or a widget type that fills by default: the layout containers + the media widgets Image / Chart / Map / Video). A widget that has a meaningful filled form switches to a stretch layout (`flex: 1` / `height: "100%"`) when it reads `true`; others ignore it. Defaults to `false`, so calling it is always safe.
+- **New optional `WidgetContext.fill` slice** backs the hook. It is optional (defaults `false`), so existing hosts and widgets are unaffected. The web Player host and the native export host inject the SAME value, so a widget's fill behaviour is identical on both platforms.
+- **`CONTRACT.version` → `1.11.0`** (additive: one new hook + one new optional context slice). No existing export changed signature.
+
+### What's new in 0.20.0
+
+**Widgets can ship their own translations (REQ-L10N-WIDGET).**
+
+- **New optional `manifest.translations` field.** Shape `{ <key>: { en: string, <locale>?: string } }` — `en` is required per key; additional locales are optional. `validateManifest` structurally validates it (≤100 keys, key matches `/^[A-Za-z][A-Za-z0-9_.-]{0,63}$/`, value ≤1 KB, namespaced key ≤128 chars); the marketplace analyzer enforces the same caps.
+- **`useI18n().t(key)` now auto-namespaces.** The host derives a per-widget prefix from the widget id and resolves `widget.<id>.<key>` first, then falls back to the raw key (so shared app keys and pre-1.10 widgets are unaffected). Authors call `t("greeting")` and never type the prefix — the same behaviour on web and in the exported native app (both hosts inject `ctx.widget.id`).
+- **Install-time seeding.** When a widget is installed, the host merges its `translations` into the tenant's localization dictionary under that namespace — non-destructively (it never overwrites an admin's edit, never creates a language the tenant didn't add, and seeds the tenant's base language from the widget's `en` so every key renders). Keys persist across uninstalls; admins prune them with the Translations screen's bulk delete (by id or by `widget.<id>.` prefix).
+- **New exported helpers** `widgetTranslationPrefix(id)` / `widgetTranslationKey(id, key)` (from `@colixsystems/widget-sdk/contract`) are the single source of the key format, shared by `useI18n` and the host seeder.
+- **`CONTRACT.version` → `1.10.0`** (additive: one new optional manifest field + the `useI18n` namespacing behaviour). No existing export changed signature.
+
+### What was in 0.19.0
 
 **The data layer splits into four injected domain clients; the SDK becomes core-only.**
 
@@ -201,6 +237,22 @@ import { defineWidget, validateManifest, useDatastoreQuery, Text, View } from "@
 - `Text`, `View`, `Pressable`, `Image`, `ScrollView`, `TextInput`, `FlatList`, `SectionList`, `ActivityIndicator`, `Switch`, `StyleSheet`, `Linking`, `Icon`, `DateTimePicker` — re-exported from `react-native` (the RN primitives) or implemented in the SDK (`Icon` wraps `lucide-react-native`, `DateTimePicker` wraps `@react-native-community/datetimepicker`). The web build aliases `react-native` to `react-native-web` so widgets render in the browser without any per-platform code; the exported Expo app's Metro bundler resolves the real `react-native` library. `Linking` is a static API (`Linking.openURL(url)`) — use it for external URLs, and use `useNavigation().goTo(pageId)` for internal page navigation. See https://reactnative.dev/docs/ for per-component props.
 - `WidgetContextProvider` — React context provider that the host (Studio, Player, exported app) wraps widgets with.
 
+## Design & visual polish
+
+A widget that works but looks unfinished is only half done. `useTheme()` is the styling contract — compose **with** it rather than just reading from it. This is the same guidance the AI Widget Builder follows when it generates a widget.
+
+**Decide before you build:** the widget's shape (card, list, form, control), its hierarchy (the one thing the eye lands on first), its single accent moment, and its empty/loading/error look — then compose. Specific decisions make a distinctive widget; leaving them to default makes a generic one.
+
+- **Pull spacing and corners from tokens.** Use `theme.spacing` (`xs / sm / md / lg / xl`) for a consistent padding and gap rhythm, and `theme.radii` (`sm / md / lg / pill`) for corners. Don't hardcode raw pixel values.
+- **Build a hierarchy.** A clear title (large, bold, `colors.onSurface`), body text, and muted captions in `colors.onSurfaceMuted` — three weights, not one flat size. Reserve `colors.primary` (with `colors.onPrimary` for text on it) for the single most important action or metric.
+- **Contain and elevate.** Wrap a logical unit in a surface: `colors.surface` + padding + `radii.md` + a `colors.border` hairline or a subtle shadow. Use the status roles (`danger / success / warning / info`) for state.
+- **Respond to touch.** Give every `Pressable` a pressed state via the function-style `style={({ pressed }) => [base, pressed && { opacity: 0.7 }]}`.
+- **Use icons for clarity.** Pair a `lucide-react-native` icon with its label at a consistent size, coloured from the theme.
+- **Use imagery deliberately.** Render pictures with the `Image` primitive (`source` takes a URL or `{ uri }`); resolve workspace assets via `useFile()`. Give every image a sized, `radii`-clipped container so it never renders as a raw rectangle, and never hardcode a credentialed image URL — expose an `image`-type property instead.
+- **Design the empty, loading, and error states.** A blank box on a fresh install reads as broken — show a short helper line when a list is empty, a calm loading line, and a single human sentence in `colors.danger` on error.
+
+**Honest ceilings:** the styling surface is React Native style objects, not full CSS. There are no per-widget gradients, no custom CSS keyframe animations or `transition` strings, and shadows are limited to the five elevation presets (`none / sm / md / lg / xl`). Aim for clean, confident, professional polish within those bounds.
+
 ## Managing app users from a widget
 
 `useUsers()` and `useGroups()` let a widget invite, deactivate, reactivate, and remove members, plus create / delete groups and add / remove their members. Two gates apply: the manifest must declare the scope (the static analyzer + the host's signed `X-Widget-Scopes` header agree), and the calling APP_USER must hold the matching `users.*` / `groups.*` capability (a SystemAcl grant the Studio admin issues via the Roles UI). A widget that declares `users.write:*` but whose caller lacks the grant gets a `DirectoryError` with `code: 'FORBIDDEN'` — surface that as a "you do not have permission" message.

package/dist/contract.cjs

@@ -10,9 +10,9 @@
 
 const DEFAULT_THEME_TOKENS = Object.freeze({
   colors: Object.freeze({
-    primary: "#ff6b5b",
+    primary: "#3b82f6",
     onPrimary: "#ffffff",
-    secondary: "#475569",
+    secondary: "#10b981",
     onSecondary: "#ffffff",
     surface: "#ffffff",
     onSurface: "#111827",
@@ -70,6 +70,26 @@ const HOOKS = [
     requiredContextSlice: ["user"],
     scopes: null,
   },
+  {
+    name: "useFill",
+    signature: "useFill()",
+    description:
+      "Returns true when the host has sized this widget to fill its layout " +
+      'slot\'s available height — a page-grid tile whose author chose "Fill ' +
+      'tile height", or a widget type that fills by default (containers and ' +
+      "media). When true, a widget that has a meaningful filled form (Image, " +
+      "Chart, Map, Video) should switch from its intrinsic height to a stretch " +
+      'style (flex: 1 / height: "100%"); widgets with no useful filled form ' +
+      "may ignore it. Defaults to false wherever the host has not opted the " +
+      "widget into filling, so calling it is always safe. The SAME value is " +
+      "injected by the web Player and the native export (CLAUDE.md §3), so a " +
+      "widget's fill behaviour is identical on both platforms.",
+    returnShape: {
+      "(returns)": "boolean",
+    },
+    requiredContextSlice: ["fill"],
+    scopes: null,
+  },
   {
     name: "useChildRenderer",
     signature: "useChildRenderer()",
@@ -579,6 +599,13 @@ const MANIFEST_SCHEMA = {
       " — NOT the React surface, so SDK imports/hooks are unavailable) }. Do NOT include triggerTableId or apiKeyId — those are tenant-local and bound after install.",
     default: [],
   },
+  translations: {
+    type: "object",
+    required: false,
+    description:
+      "Optional (REQ-L10N-WIDGET). Translation strings the widget ships. Shape { <key>: { en: string, <locale>?: string, ... } } — `en` is REQUIRED per key. At install the host merges these into the tenant's localization dictionary under a per-widget namespace (`widget.<manifest.id>.<key>`); `useI18n().t(\"<key>\")` resolves the namespaced key automatically, so authors never type the prefix. Non-destructive: an existing admin-edited value is never overwritten, and a language the tenant has not added is never created (values for absent locales are dropped; the widget's `en` seeds the tenant's base language so every key renders). Keys persist across uninstalls; admins prune them from the Translations admin (bulk delete by `widget.<id>.` prefix). Limits: ≤100 keys; each key matches /^[A-Za-z][A-Za-z0-9_.-]{0,63}$/; each value ≤1 KB; the namespaced key must fit the dictionary key cap (128 chars).",
+    default: {},
+  },
 };
 
 const WIDGET_CONTEXT_SHAPE = {
@@ -594,6 +621,19 @@ const WIDGET_CONTEXT_SHAPE = {
     required: true,
     fields: { id: "manifest.id", version: "manifest.version" },
   },
+  // REQ-LAY-08 — optional host layout hint backing useFill(). True when the
+  // host sized this widget to fill its layout slot's available height (a
+  // page-grid tile set to "Fill tile height", or a default-fill widget type).
+  // Optional: a host that never fills a widget simply omits it and useFill()
+  // returns false, so existing hosts need no change.
+  fill: {
+    description:
+      "Optional host layout hint (boolean). True when the host sized this " +
+      "widget to fill its layout slot's available height (page-grid tile " +
+      "fill). Backs useFill(); defaults to false when absent.",
+    required: false,
+    fields: {},
+  },
   user: {
     description:
       "Signed-in user, host-provided VERBATIM (snake_case: { id, email, display_name, roles, group_ids }). Not a data-client.",
@@ -901,6 +941,20 @@ function deepFreeze(value) {
   return Object.freeze(value);
 }
 
+// REQ-L10N-WIDGET — a widget's manifest `translations` are merged into the
+// tenant dictionary under a per-widget namespace so they never collide with
+// app keys or another widget's keys. The prefix is DERIVED from the widget id
+// (it "follows the widget"), so authors call `t("greeting")` and the host
+// resolves `widget.<id>.greeting`. This is the ONE definition of the key
+// format: the SDK `useI18n` hook (lookup) and the backend seeder (write) both
+// call it, so the wire key and the lookup key can never drift.
+function widgetTranslationPrefix(id) {
+  return `widget.${id}.`;
+}
+function widgetTranslationKey(id, key) {
+  return `widget.${id}.${key}`;
+}
+
 const CONTRACT = deepFreeze({
   // REQ-WSDK-PLATFORM bump:
   //   - `vettedImports` is a new field (rich allowlist with platforms +
@@ -952,7 +1006,43 @@ const CONTRACT = deepFreeze({
   //    snake_case. Hooks now unwrap the list envelope (res.data ?? []). The
   //    SDK stays duck-typed — it imports none of the four data SDKs. Minor
   //    bump on the contract's pre-1.0 versioning (the breaking channel).
-  version: "1.9.0",
+  //
+  // 1.10.0: additive (REQ-L10N-WIDGET) — manifests may declare an optional
+  //    `translations` map ({ <key>: { en, <locale>? } }, en required). The
+  //    host seeds them into the tenant l10n dictionary under a per-widget
+  //    namespace at install; `useI18n().t(key)` now auto-prefixes the lookup
+  //    with `widget.<ctx.widget.id>.` (then falls back to the raw key, so
+  //    existing widgets and shared app keys keep resolving). New exported
+  //    helpers widgetTranslationPrefix / widgetTranslationKey are the single
+  //    source of the key format, shared by the hook and the backend seeder.
+  //
+  // 1.11.0: additive (REQ-LAY-08) — new useFill() hook + the optional `fill`
+  //    host-context slice it reads. The host sets ctx.fill=true when it has
+  //    sized a widget to fill its layout slot's available height (a page-grid
+  //    tile whose author chose "Fill tile height", or a default-fill widget
+  //    type — containers + media). Widgets that can stretch (Image, Chart,
+  //    Map, Video) switch to flex:1/height:"100%" when useFill() is true; all
+  //    others ignore it. The slice is OPTIONAL (defaults false) so existing
+  //    hosts need no change, and the same value is injected on web and native
+  //    so fill behaviour cannot diverge between the Player and the export.
+  //
+  // 1.11.1: fix — the canonical default `themeTokens.colors` now match the
+  //    product's advertised default brand (primary #3b82f6 blue, secondary
+  //    #10b981 green) instead of the stale coral/slate that no other surface
+  //    used. The Theme Settings tab and Player chrome already defaulted to
+  //    these values, so a tenant that never customised its theme rendered
+  //    widgets in coral until a first save persisted the blue — a divergence
+  //    between the unsaved and saved-defaults render. Aligning the canonical
+  //    tokens removes it (no shape/signature change — default-value fix only).
+  //
+  // 1.12.0: additive (REQ-WDG-VALUEREF) — new `valueRef` propertySchema type.
+  //    A composite "single value from the datastore" picker whose persisted
+  //    value is an object `{ tableId, recordId, column }` (every other ref
+  //    type is a bare string). The Studio Properties Panel renders three
+  //    cascading dropdowns; tenant-copy remaps `tableId` and nulls `recordId`
+  //    (records are business data, never copied). No existing type changed
+  //    shape, so this is additive — minor bump on the pre-1.0 channel.
+  version: "1.12.0",
   hooks: HOOKS,
   primitives: PRIMITIVES,
   manifestSchema: MANIFEST_SCHEMA,
@@ -984,4 +1074,10 @@ function requiredContextKeys() {
   return [...keys];
 }
 
-module.exports = { CONTRACT, isHookAllowed, requiredContextKeys };
+module.exports = {
+  CONTRACT,
+  isHookAllowed,
+  requiredContextKeys,
+  widgetTranslationPrefix,
+  widgetTranslationKey,
+};

package/dist/contract.js

@@ -10,9 +10,9 @@
 
 const DEFAULT_THEME_TOKENS = Object.freeze({
   colors: Object.freeze({
-    primary: "#ff6b5b",
+    primary: "#3b82f6",
     onPrimary: "#ffffff",
-    secondary: "#475569",
+    secondary: "#10b981",
     onSecondary: "#ffffff",
     surface: "#ffffff",
     onSurface: "#111827",
@@ -70,6 +70,26 @@ const HOOKS = [
     requiredContextSlice: ["user"],
     scopes: null,
   },
+  {
+    name: "useFill",
+    signature: "useFill()",
+    description:
+      "Returns true when the host has sized this widget to fill its layout " +
+      'slot\'s available height — a page-grid tile whose author chose "Fill ' +
+      'tile height", or a widget type that fills by default (containers and ' +
+      "media). When true, a widget that has a meaningful filled form (Image, " +
+      "Chart, Map, Video) should switch from its intrinsic height to a stretch " +
+      'style (flex: 1 / height: "100%"); widgets with no useful filled form ' +
+      "may ignore it. Defaults to false wherever the host has not opted the " +
+      "widget into filling, so calling it is always safe. The SAME value is " +
+      "injected by the web Player and the native export (CLAUDE.md §3), so a " +
+      "widget's fill behaviour is identical on both platforms.",
+    returnShape: {
+      "(returns)": "boolean",
+    },
+    requiredContextSlice: ["fill"],
+    scopes: null,
+  },
   {
     name: "useChildRenderer",
     signature: "useChildRenderer()",
@@ -580,6 +600,13 @@ const MANIFEST_SCHEMA = {
       " — NOT the React surface, so SDK imports/hooks are unavailable) }. Do NOT include triggerTableId or apiKeyId — those are tenant-local and bound after install.",
     default: [],
   },
+  translations: {
+    type: "object",
+    required: false,
+    description:
+      "Optional (REQ-L10N-WIDGET). Translation strings the widget ships. Shape { <key>: { en: string, <locale>?: string, ... } } — `en` is REQUIRED per key. At install the host merges these into the tenant's localization dictionary under a per-widget namespace (`widget.<manifest.id>.<key>`); `useI18n().t(\"<key>\")` resolves the namespaced key automatically, so authors never type the prefix. Non-destructive: an existing admin-edited value is never overwritten, and a language the tenant has not added is never created (values for absent locales are dropped; the widget's `en` seeds the tenant's base language so every key renders). Keys persist across uninstalls; admins prune them from the Translations admin (bulk delete by `widget.<id>.` prefix). Limits: ≤100 keys; each key matches /^[A-Za-z][A-Za-z0-9_.-]{0,63}$/; each value ≤1 KB; the namespaced key must fit the dictionary key cap (128 chars).",
+    default: {},
+  },
 };
 
 const WIDGET_CONTEXT_SHAPE = {
@@ -594,6 +621,19 @@ const WIDGET_CONTEXT_SHAPE = {
     required: true,
     fields: { id: "manifest.id", version: "manifest.version" },
   },
+  // REQ-LAY-08 — optional host layout hint backing useFill(). True when the
+  // host sized this widget to fill its layout slot's available height (a
+  // page-grid tile set to "Fill tile height", or a default-fill widget type).
+  // Optional: a host that never fills a widget simply omits it and useFill()
+  // returns false, so existing hosts need no change.
+  fill: {
+    description:
+      "Optional host layout hint (boolean). True when the host sized this " +
+      "widget to fill its layout slot's available height (page-grid tile " +
+      "fill). Backs useFill(); defaults to false when absent.",
+    required: false,
+    fields: {},
+  },
   user: {
     description:
       "Signed-in user, host-provided VERBATIM (snake_case: { id, email, display_name, roles, group_ids }). Not a data-client.",
@@ -873,6 +913,20 @@ function deepFreeze(value) {
   return Object.freeze(value);
 }
 
+// REQ-L10N-WIDGET — a widget's manifest `translations` are merged into the
+// tenant dictionary under a per-widget namespace so they never collide with
+// app keys or another widget's keys. The prefix is DERIVED from the widget id
+// (it "follows the widget"), so authors call `t("greeting")` and the host
+// resolves `widget.<id>.greeting`. This is the ONE definition of the key
+// format: the SDK `useI18n` hook (lookup) and the backend seeder (write) both
+// call it, so the wire key and the lookup key can never drift.
+function widgetTranslationPrefix(id) {
+  return `widget.${id}.`;
+}
+function widgetTranslationKey(id, key) {
+  return `widget.${id}.${key}`;
+}
+
 const CONTRACT = deepFreeze({
   // 1.7.0: additive — new useDatastoreSchema(tableId) hook + the
   // datastore.schema host-context slice it reads (resolves a table's column
@@ -905,7 +959,43 @@ const CONTRACT = deepFreeze({
   //    snake_case. Hooks now unwrap the list envelope (res.data ?? []). The
   //    SDK stays duck-typed — it imports none of the four data SDKs. Minor
   //    bump on the contract's pre-1.0 versioning (the breaking channel).
-  version: "1.9.0",
+  //
+  // 1.10.0: additive (REQ-L10N-WIDGET) — manifests may declare an optional
+  //    `translations` map ({ <key>: { en, <locale>? } }, en required). The
+  //    host seeds them into the tenant l10n dictionary under a per-widget
+  //    namespace at install; `useI18n().t(key)` now auto-prefixes the lookup
+  //    with `widget.<ctx.widget.id>.` (then falls back to the raw key, so
+  //    existing widgets and shared app keys keep resolving). New exported
+  //    helpers widgetTranslationPrefix / widgetTranslationKey are the single
+  //    source of the key format, shared by the hook and the backend seeder.
+  //
+  // 1.11.0: additive (REQ-LAY-08) — new useFill() hook + the optional `fill`
+  //    host-context slice it reads. The host sets ctx.fill=true when it has
+  //    sized a widget to fill its layout slot's available height (a page-grid
+  //    tile whose author chose "Fill tile height", or a default-fill widget
+  //    type — containers + media). Widgets that can stretch (Image, Chart,
+  //    Map, Video) switch to flex:1/height:"100%" when useFill() is true; all
+  //    others ignore it. The slice is OPTIONAL (defaults false) so existing
+  //    hosts need no change, and the same value is injected on web and native
+  //    so fill behaviour cannot diverge between the Player and the export.
+  //
+  // 1.11.1: fix — the canonical default `themeTokens.colors` now match the
+  //    product's advertised default brand (primary #3b82f6 blue, secondary
+  //    #10b981 green) instead of the stale coral/slate that no other surface
+  //    used. The Theme Settings tab and Player chrome already defaulted to
+  //    these values, so a tenant that never customised its theme rendered
+  //    widgets in coral until a first save persisted the blue — a divergence
+  //    between the unsaved and saved-defaults render. Aligning the canonical
+  //    tokens removes it (no shape/signature change — default-value fix only).
+  //
+  // 1.12.0: additive (REQ-WDG-VALUEREF) — new `valueRef` propertySchema type.
+  //    A composite "single value from the datastore" picker whose persisted
+  //    value is an object `{ tableId, recordId, column }` (every other ref
+  //    type is a bare string). The Studio Properties Panel renders three
+  //    cascading dropdowns; tenant-copy remaps `tableId` and nulls `recordId`
+  //    (records are business data, never copied). No existing type changed
+  //    shape, so this is additive — minor bump on the pre-1.0 channel.
+  version: "1.12.0",
   hooks: HOOKS,
   primitives: PRIMITIVES,
   manifestSchema: MANIFEST_SCHEMA,
@@ -937,4 +1027,10 @@ function requiredContextKeys() {
   return [...keys];
 }
 
-export { CONTRACT, isHookAllowed, requiredContextKeys };
+export {
+  CONTRACT,
+  isHookAllowed,
+  requiredContextKeys,
+  widgetTranslationPrefix,
+  widgetTranslationKey,
+};

package/dist/hooks.js

@@ -26,6 +26,10 @@ import React, {
   useRef,
   useState,
 } from "react";
+// REQ-L10N-WIDGET: the per-widget translation key format lives in ONE place
+// (contract.js). useI18n (lookup) and the backend seeder (write) both call it
+// so the namespaced key can never drift between the two sides.
+import { widgetTranslationKey } from "./contract.js";
 
 /** @internal — host-injected context value of shape WidgetContext (see index.d.ts). */
 const HostWidgetContext = createContext(null);
@@ -97,6 +101,25 @@ export function useUser() {
   return ctx.user;
 }
 
+/**
+ * Returns `true` when the host has sized this widget to fill the available
+ * height of its layout slot — today that means a page-grid tile whose author
+ * chose "Fill tile height" (or a widget type that fills by default, like
+ * containers and media). When `true`, a widget that has a meaningful filled
+ * form (Image, Chart, Map, Video, …) should switch from its intrinsic height
+ * to a stretch style (`flex: 1` / `height: "100%"`); widgets with no useful
+ * filled form may ignore it. Defaults to `false` everywhere the host has not
+ * opted the widget into filling, so calling it is always safe.
+ *
+ * The SAME value is injected by the web Player host and the native export
+ * host (CLAUDE.md §3), so a widget's fill behaviour is identical on both
+ * platforms — there is one source file and one `fill` flag driving it.
+ */
+export function useFill() {
+  const ctx = useWidgetContextOrThrow("useFill");
+  return ctx.fill === true;
+}
+
 /**
  * Returns the host's child-node renderer:
  *   { renderNode(node) }.
@@ -166,14 +189,39 @@ export function useI18n() {
   const i18n = ctx.i18n || {};
   const locale = typeof i18n.locale === "string" ? i18n.locale : "en";
   const hostT = typeof i18n.t === "function" ? i18n.t : null;
+  // 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
+  // types the prefix — and so the SAME hook gives this behaviour on web and in
+  // the exported app (both hosts set ctx.widget.id).
+  const widgetId =
+    ctx.widget && typeof ctx.widget.id === "string" && ctx.widget.id
+      ? ctx.widget.id
+      : null;
   const t = useCallback(
     (key, fallback) => {
       if (typeof key !== "string" || !key) {
         return typeof fallback === "string" ? fallback : "";
       }
       if (hostT) {
-        // Try the two-arg form first; if the host's `t` ignores `fallback`
-        // and returns the bare key on a miss, swap in the fallback.
+        // 1) Try the widget-namespaced key first. A genuine hit is a string
+        //    that is neither the bare key nor a `{{t:…}}` placeholder (the
+        //    miss form both hosts emit). No fallback is passed here so a miss
+        //    is unambiguous and we can fall through to the raw key.
+        if (widgetId) {
+          const namespaced = widgetTranslationKey(widgetId, key);
+          const scoped = hostT(namespaced);
+          if (
+            typeof scoped === "string" &&
+            scoped.length > 0 &&
+            scoped !== namespaced &&
+            !scoped.startsWith("{{t:")
+          ) {
+            return scoped;
+          }
+        }
+        // 2) Fall back to the raw key (shared app keys + widgets with no
+        //    manifest translations — unchanged from pre-1.10 behaviour).
         const out = hostT(key, fallback);
         if (typeof out === "string" && out.length > 0 && out !== key) {
           return out;
@@ -183,7 +231,7 @@ export function useI18n() {
       }
       return typeof fallback === "string" ? fallback : key;
     },
-    [hostT],
+    [hostT, widgetId],
   );
   return { t, locale };
 }

package/dist/index.d.ts

@@ -29,6 +29,10 @@ export type WidgetPropertyType =
   | "tableRef"
   | "columnRef"
   | "recordBinding"
+  // REQ-WDG-VALUEREF: composite "single value from the datastore" picker.
+  // Persisted value is `{ tableId, recordId, column }`; the bound widget
+  // resolves the one cell.
+  | "valueRef"
   // REQ-USERMGMT M4 / §4.8: Group picker that emits a bare
   // AppUserGroup UUID into the page JSON.
   | "groupRef"
@@ -56,6 +60,17 @@ export interface WidgetPropertyDef {
 
 export type WidgetPropertySchema = Record<string, WidgetPropertyDef>;
 
+/**
+ * REQ-WDG-VALUEREF: the persisted value of a `valueRef` property. Each
+ * field is optional while the author is mid-pick; a widget treats any
+ * missing piece as "no value".
+ */
+export interface ValueRefBinding {
+  tableId?: string;
+  recordId?: string;
+  column?: string;
+}
+
 export interface WidgetEventDescriptor {
   name: string;
   description?: string;
@@ -184,6 +199,17 @@ export interface WidgetManifest {
    * isolated-vm action runner. See `WidgetManifestAction`.
    */
   actions?: WidgetManifestAction[];
+  /**
+   * Optional translation strings the widget ships (REQ-L10N-WIDGET). Maps a
+   * relative key to its per-locale strings; `en` is required per key. At
+   * install the host merges these into the tenant's localization dictionary
+   * under a per-widget namespace (`widget.<id>.<key>`), so `useI18n().t(key)`
+   * resolves the namespaced key automatically — the author never types the
+   * prefix. Non-destructive (admin edits win; absent languages are not
+   * created) and persists across uninstalls. Caps: ≤100 keys, key matches
+   * /^[A-Za-z][A-Za-z0-9_.-]{0,63}$/, value ≤1 KB.
+   */
+  translations?: Record<string, { en: string } & Record<string, string>>;
 }
 
 export interface ThemeTokens {
@@ -314,6 +340,13 @@ export interface PaymentsClient {
 export interface WidgetContext<TProps = unknown> {
   props: TProps;
   widget: { id: string; instanceId: string; version: string };
+  /**
+   * REQ-LAY-08 — optional host layout hint backing `useFill()`. `true` when
+   * the host sized this widget to fill its layout slot's available height (a
+   * page-grid tile set to "Fill tile height", or a default-fill widget type).
+   * Absent / `false` everywhere the host has not opted the widget into filling.
+   */
+  fill?: boolean;
   /** Active end-user identity, snake_case verbatim. `id` is null when anonymous. */
   user: {
     id: string | null;
@@ -645,6 +678,17 @@ export function useUser(): {
   group_ids: string[];
 };
 
+/**
+ * REQ-LAY-08 — returns `true` when the host has sized this widget to fill its
+ * layout slot's available height (a page-grid tile set to "Fill tile height",
+ * or a default-fill widget type — containers + media). Widgets that can
+ * stretch (Image, Chart, Map, Video, …) should switch to a fill style
+ * (`flex: 1` / `height: "100%"`) when this is `true`; others may ignore it.
+ * Defaults to `false`, so calling it is always safe, and the same value is
+ * injected on web and native so fill behaviour is identical on both platforms.
+ */
+export function useFill(): boolean;
+
 /**
  * The host-provided navigation surface. `goTo(pageId, params?)` navigates
  * to an internal app page; `goBack()` pops the stack. Missing methods

package/dist/index.js

@@ -25,6 +25,7 @@ export {
   useTheme,
   useI18n,
   useUser,
+  useFill,
   useNavigation,
   useChildRenderer,
   WidgetTree,

package/dist/index.native.js

@@ -25,6 +25,7 @@ export {
   useTheme,
   useI18n,
   useUser,
+  useFill,
   useNavigation,
   useChildRenderer,
   WidgetTree,

package/dist/manifest.cjs

@@ -24,10 +24,86 @@ const ACTION_SCRIPT_MAX_BYTES = 200 * 1024;
 const ACTION_TIMEOUT_MIN_MS = 100;
 const ACTION_TIMEOUT_MAX_MS = 5 * 60 * 1000;
 
+// REQ-L10N-WIDGET — caps + patterns for manifest-declared translations.
+// The relative key pattern is deliberately tighter than the dictionary's
+// own KEY_RE: once the host namespaces it (`widget.<id>.<key>`) the result
+// must still satisfy the dictionary cap (128 chars / KEY_RE in
+// backend/src/core/services/l10n.service.js). The locale pattern mirrors that
+// service's LANG_CODE_RE so a manifest can't declare a locale the dictionary
+// would reject.
+const TRANSLATIONS_MAX_KEYS = 100;
+const TRANSLATION_VALUE_MAX_BYTES = 1024;
+const TRANSLATION_KEY_RE = /^[A-Za-z][A-Za-z0-9_.-]{0,63}$/;
+const TRANSLATION_LOCALE_RE = /^[a-z]{2,3}(-[A-Za-z0-9]{2,8})?$/;
+const TRANSLATION_FULL_KEY_MAX = 128;
+
 function utf8ByteLength(s) {
   return new TextEncoder().encode(s).length;
 }
 
+function validateManifestTranslations(translations, manifestId, errors) {
+  if (
+    translations === null ||
+    typeof translations !== "object" ||
+    Array.isArray(translations)
+  ) {
+    errors.push(
+      "manifest.translations must be an object mapping key -> { en, <locale>? }",
+    );
+    return;
+  }
+  const keys = Object.keys(translations);
+  if (keys.length > TRANSLATIONS_MAX_KEYS) {
+    errors.push(
+      `manifest.translations may declare at most ${TRANSLATIONS_MAX_KEYS} keys`,
+    );
+  }
+  for (const key of keys) {
+    if (!TRANSLATION_KEY_RE.test(key)) {
+      errors.push(
+        `manifest.translations key "${key}" must match /^[A-Za-z][A-Za-z0-9_.-]{0,63}$/`,
+      );
+      continue;
+    }
+    if (isNonEmptyString(manifestId)) {
+      const fullKey = `widget.${manifestId}.${key}`;
+      if (fullKey.length > TRANSLATION_FULL_KEY_MAX) {
+        errors.push(
+          `manifest.translations key "${key}" is too long once namespaced (${fullKey.length} > ${TRANSLATION_FULL_KEY_MAX} chars)`,
+        );
+      }
+    }
+    const entry = translations[key];
+    if (entry === null || typeof entry !== "object" || Array.isArray(entry)) {
+      errors.push(
+        `manifest.translations["${key}"] must be an object of locale -> string`,
+      );
+      continue;
+    }
+    if (!isNonEmptyString(entry.en)) {
+      errors.push(
+        `manifest.translations["${key}"].en is required and must be a non-empty string`,
+      );
+    }
+    for (const [locale, value] of Object.entries(entry)) {
+      if (!TRANSLATION_LOCALE_RE.test(locale)) {
+        errors.push(
+          `manifest.translations["${key}"] has invalid locale "${locale}"`,
+        );
+      }
+      if (typeof value !== "string") {
+        errors.push(
+          `manifest.translations["${key}"]["${locale}"] must be a string`,
+        );
+      } else if (utf8ByteLength(value) > TRANSLATION_VALUE_MAX_BYTES) {
+        errors.push(
+          `manifest.translations["${key}"]["${locale}"] exceeds 1 KB`,
+        );
+      }
+    }
+  }
+}
+
 function validateManifestActions(actions, errors) {
   if (!Array.isArray(actions)) {
     errors.push("manifest.actions must be an array (omit it or use [] for none)");
@@ -208,10 +284,16 @@ function validateManifest(m) {
     validateManifestActions(manifest.actions, errors);
   }
 
+  // `translations` is optional (additive in SDK 1.10.0 / REQ-L10N-WIDGET).
+  if (manifest.translations !== undefined) {
+    validateManifestTranslations(manifest.translations, manifest.id, errors);
+  }
+
   return errors.length === 0 ? { ok: true } : { ok: false, errors };
 }
 
 module.exports = {
   validateManifest,
+  validateManifestTranslations,
   canonicalCategory,
 };

package/dist/manifest.js

@@ -24,10 +24,86 @@ const ACTION_SCRIPT_MAX_BYTES = 200 * 1024;
 const ACTION_TIMEOUT_MIN_MS = 100;
 const ACTION_TIMEOUT_MAX_MS = 5 * 60 * 1000;
 
+// REQ-L10N-WIDGET — caps + patterns for manifest-declared translations.
+// The relative key pattern is deliberately tighter than the dictionary's
+// own KEY_RE: once the host namespaces it (`widget.<id>.<key>`) the result
+// must still satisfy the dictionary cap (128 chars / KEY_RE in
+// backend/src/core/services/l10n.service.js). The locale pattern mirrors that
+// service's LANG_CODE_RE so a manifest can't declare a locale the dictionary
+// would reject.
+const TRANSLATIONS_MAX_KEYS = 100;
+const TRANSLATION_VALUE_MAX_BYTES = 1024;
+const TRANSLATION_KEY_RE = /^[A-Za-z][A-Za-z0-9_.-]{0,63}$/;
+const TRANSLATION_LOCALE_RE = /^[a-z]{2,3}(-[A-Za-z0-9]{2,8})?$/;
+const TRANSLATION_FULL_KEY_MAX = 128;
+
 function utf8ByteLength(s) {
   return new TextEncoder().encode(s).length;
 }
 
+function validateManifestTranslations(translations, manifestId, errors) {
+  if (
+    translations === null ||
+    typeof translations !== "object" ||
+    Array.isArray(translations)
+  ) {
+    errors.push(
+      "manifest.translations must be an object mapping key -> { en, <locale>? }",
+    );
+    return;
+  }
+  const keys = Object.keys(translations);
+  if (keys.length > TRANSLATIONS_MAX_KEYS) {
+    errors.push(
+      `manifest.translations may declare at most ${TRANSLATIONS_MAX_KEYS} keys`,
+    );
+  }
+  for (const key of keys) {
+    if (!TRANSLATION_KEY_RE.test(key)) {
+      errors.push(
+        `manifest.translations key "${key}" must match /^[A-Za-z][A-Za-z0-9_.-]{0,63}$/`,
+      );
+      continue;
+    }
+    if (isNonEmptyString(manifestId)) {
+      const fullKey = `widget.${manifestId}.${key}`;
+      if (fullKey.length > TRANSLATION_FULL_KEY_MAX) {
+        errors.push(
+          `manifest.translations key "${key}" is too long once namespaced (${fullKey.length} > ${TRANSLATION_FULL_KEY_MAX} chars)`,
+        );
+      }
+    }
+    const entry = translations[key];
+    if (entry === null || typeof entry !== "object" || Array.isArray(entry)) {
+      errors.push(
+        `manifest.translations["${key}"] must be an object of locale -> string`,
+      );
+      continue;
+    }
+    if (!isNonEmptyString(entry.en)) {
+      errors.push(
+        `manifest.translations["${key}"].en is required and must be a non-empty string`,
+      );
+    }
+    for (const [locale, value] of Object.entries(entry)) {
+      if (!TRANSLATION_LOCALE_RE.test(locale)) {
+        errors.push(
+          `manifest.translations["${key}"] has invalid locale "${locale}"`,
+        );
+      }
+      if (typeof value !== "string") {
+        errors.push(
+          `manifest.translations["${key}"]["${locale}"] must be a string`,
+        );
+      } else if (utf8ByteLength(value) > TRANSLATION_VALUE_MAX_BYTES) {
+        errors.push(
+          `manifest.translations["${key}"]["${locale}"] exceeds 1 KB`,
+        );
+      }
+    }
+  }
+}
+
 function validateManifestActions(actions, errors) {
   if (!Array.isArray(actions)) {
     errors.push("manifest.actions must be an array (omit it or use [] for none)");
@@ -208,10 +284,16 @@ function validateManifest(m) {
     validateManifestActions(manifest.actions, errors);
   }
 
+  // `translations` is optional (additive in SDK 1.10.0 / REQ-L10N-WIDGET).
+  if (manifest.translations !== undefined) {
+    validateManifestTranslations(manifest.translations, manifest.id, errors);
+  }
+
   return errors.length === 0 ? { ok: true } : { ok: false, errors };
 }
 
 export {
   validateManifest,
+  validateManifestTranslations,
   canonicalCategory,
 };

package/dist/property-schema.js

@@ -6,6 +6,14 @@ const VALID_TYPES = new Set([
   "color", "icon", "image",
   "select", "multiselect",
   "tableRef", "columnRef", "recordBinding",
+  // REQ-WDG-VALUEREF: `valueRef` is a composite "single value from the
+  // datastore" picker. Unlike the bare-string refs above, its persisted
+  // value is an OBJECT `{ tableId, recordId, column }` — the author picks a
+  // table, then a record, then a column, and the bound widget resolves the
+  // one cell. The Studio Properties Panel renders three cascading dropdowns
+  // (`ValueRefEditor`). tenant-copy remaps `tableId` and NULLS `recordId`
+  // (records are business data, never copied) — see tenant-copy.service.js.
+  "valueRef",
   // REQ-USERMGMT M4 / §4.8: `groupRef` is a Group picker that emits a bare
   // AppUserGroup UUID into the page JSON. Renders via `GroupSelector` in
   // the Studio Properties Panel. REQ-GEN-07 compliance: no typed UUIDs —
@@ -134,6 +142,23 @@ function coerceLeaf(def, value, path, errors) {
         return value;
       }
       return value.map((item, i) => coerceLeaf(def.items, item, `${path}[${i}]`, errors));
+    case "valueRef": {
+      // REQ-WDG-VALUEREF: a `{ tableId, recordId, column }` binding. Each
+      // sub-field is an optional string (a half-configured binding is valid
+      // while the author is still picking); the bound widget treats any
+      // missing piece as "no value" and shows its fallback.
+      if (!isPlainObject(value)) {
+        errors.push(`${path}: expected object`);
+        return value;
+      }
+      for (const sub of ["tableId", "recordId", "column"]) {
+        const v = value[sub];
+        if (v !== undefined && v !== null && typeof v !== "string") {
+          errors.push(`${path}.${sub}: expected string`);
+        }
+      }
+      return value;
+    }
     case "object": {
       if (!isPlainObject(value)) {
         errors.push(`${path}: expected object`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.19.0",
+  "version": "0.22.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "type": "module",
   "main": "./dist/index.js",
@@ -35,7 +35,7 @@
   ],
   "scripts": {
     "build": "node scripts/build.js",
-    "test": "node --test src/__tests__/contract.test.js src/__tests__/hooks-users.test.js src/__tests__/hooks-groups.test.js src/__tests__/hooks-schema.test.js src/__tests__/hooks-mutation.test.js src/__tests__/hooks-record-permissions.test.js src/__tests__/linter-users-scope.test.js src/__tests__/manifest-actions.test.js"
+    "test": "node --test src/__tests__/contract.test.js src/__tests__/hooks-users.test.js src/__tests__/hooks-groups.test.js src/__tests__/hooks-schema.test.js src/__tests__/hooks-mutation.test.js src/__tests__/hooks-record-permissions.test.js src/__tests__/linter-users-scope.test.js src/__tests__/manifest-actions.test.js src/__tests__/widget-translations.test.js"
   },
   "engines": {
     "node": ">=18"