@colixsystems/widget-sdk 0.37.0 → 0.38.0

package/README.md

@@ -26,7 +26,7 @@ The data layer lives in **four separate domain-client packages**, each instantia
 | **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. `t(key)` resolves the widget-namespaced key (`widget.<id>.<key>`, declared in `manifest.translations`) then falls back to the raw key. |
+| **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. |
 | **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>` |
@@ -47,7 +47,17 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.37.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.38.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.38.0
+
+**Predefined SHARED translation keys (REQ-L10N-SHARED).** The standard strings the default widgets repeat ("Submit", "Cancel", "Save", "Loading…", …) now have a tenant-wide shared namespace `shared.<key>` so an identical string is translated **once** and every widget that uses it inherits the translation.
+
+- **New contract field `CONTRACT.sharedTranslationKeys`** — the predefined map (`{ <key>: { en } }`) and the single source the host seeder reads.
+- **New exported helpers** `sharedTranslationPrefix()` / `sharedTranslationKey(key)` / `isSharedTranslationKey(key)` (from `@colixsystems/widget-sdk/contract`).
+- **`useI18n().t(key)` resolution is now three-step**: the per-widget key (`widget.<id>.<key>`) first, then the shared key (`shared.<key>`) when `key` is one of the predefined shared keys, then the raw key / fallback. So a default widget that calls `t("submit")` picks up the shared translation with no manual key entry, and an author who sets `widget.<id>.submit` in the Translations admin still overrides **that instance only**. An author-invented bare key is never silently shared.
+- **The host auto-registers the shared keys** for a tenant at workspace-content seed time and whenever a marketplace or AI-generated widget is added — idempotent and non-destructive (an admin edit is never overwritten). Authors manage / translate them in the Studio Translations screen like any other key.
+- **`CONTRACT.version` → `1.28.0`** (additive: one new contract field + three helper exports + the `useI18n` shared-key step). No existing export changed signature.
 
 ### What's new in 0.37.0
 

package/dist/contract.cjs

@@ -1285,6 +1285,65 @@ function widgetTranslationKey(id, key) {
   return `widget.${id}.${key}`;
 }
 
+// REQ-L10N-SHARED — predefined SHARED translation keys for the standard
+// strings the default widgets repeat ("Submit", "Cancel", "Loading…", …).
+// They live in ONE tenant-wide namespace (`shared.<key>`) rather than the
+// per-widget namespace, so identical strings translate ONCE and every widget
+// that calls `t("<sharedKey>")` resolves the same dictionary value. An author
+// still overrides any instance by setting `widget.<id>.<key>` in the
+// Translations admin — `useI18n` resolves the per-widget key FIRST, then the
+// shared key, then the raw key, so the override is per-instance.
+//
+// This is the analogue of `widget.<id>.` for cross-widget reuse: one prefix,
+// one definition (the hook reads + the backend seeder writes both call these),
+// so the wire key and the lookup key can never drift.
+const SHARED_TRANSLATION_PREFIX = "shared.";
+function sharedTranslationPrefix() {
+  return SHARED_TRANSLATION_PREFIX;
+}
+function sharedTranslationKey(key) {
+  return `${SHARED_TRANSLATION_PREFIX}${key}`;
+}
+
+// The predefined set. Map of bare key -> { en } (English default only; the
+// tenant adds target-language values once in the Translations admin and every
+// widget inherits them). Adding/removing a key is a CONTRACT change (it grows
+// the dictionary every tenant gets), so the list lives with the contract and
+// the seeder reads it from here — never a second copy.
+const SHARED_TRANSLATION_KEYS = Object.freeze({
+  submit: { en: "Submit" },
+  cancel: { en: "Cancel" },
+  save: { en: "Save" },
+  delete: { en: "Delete" },
+  edit: { en: "Edit" },
+  close: { en: "Close" },
+  confirm: { en: "Confirm" },
+  back: { en: "Back" },
+  next: { en: "Next" },
+  previous: { en: "Previous" },
+  yes: { en: "Yes" },
+  no: { en: "No" },
+  ok: { en: "OK" },
+  loading: { en: "Loading…" },
+  search: { en: "Search" },
+  no_results: { en: "No results" },
+  required: { en: "Required" },
+  retry: { en: "Retry" },
+  add: { en: "Add" },
+  remove: { en: "Remove" },
+});
+
+// True when `key` is one of the predefined shared keys — the discriminator
+// `useI18n` uses to decide whether to try the `shared.<key>` namespace. A key
+// the author invents is NOT shared (it stays per-widget) so authors can't
+// accidentally collide with another widget by reusing a bare name.
+function isSharedTranslationKey(key) {
+  return (
+    typeof key === "string" &&
+    Object.prototype.hasOwnProperty.call(SHARED_TRANSLATION_KEYS, key)
+  );
+}
+
 const CONTRACT = deepFreeze({
   // REQ-WSDK-PLATFORM bump:
   //   - `vettedImports` is a new field (rich allowlist with platforms +
@@ -1486,7 +1545,23 @@ const CONTRACT = deepFreeze({
   //    on `react/jsx-runtime`. Adding them converges the linter onto the same
   //    contract every other surface already honoured (CLAUDE.md §3). No
   //    existing entry changed shape — minor bump on the pre-1.0 channel.
-  version: "1.27.0",
+  //
+  // 1.28.0: additive (REQ-L10N-SHARED) — predefined SHARED translation keys.
+  //    A new tenant-wide namespace `shared.<key>` carries the standard strings
+  //    the default widgets repeat ("Submit", "Cancel", "Loading…", …) so an
+  //    identical string is translated ONCE and every widget that calls
+  //    `t("<sharedKey>")` inherits it. New contract field
+  //    `sharedTranslationKeys` (the predefined map, the single source the
+  //    backend seeder reads) + new exported helpers `sharedTranslationPrefix()`
+  //    / `sharedTranslationKey(key)` / `isSharedTranslationKey(key)`.
+  //    `useI18n().t(key)` now resolves the per-widget key first, THEN the
+  //    shared key (when `key` is one of the predefined shared keys), then the
+  //    raw key — so a default widget picks up the shared translation with no
+  //    manual key entry, and a `widget.<id>.<key>` override still wins per
+  //    instance. No existing hook, primitive, manifest field, or token changed
+  //    shape — minor bump on the pre-1.0 channel.
+  version: "1.28.0",
+  sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
   manifestSchema: MANIFEST_SCHEMA,
@@ -1524,4 +1599,8 @@ module.exports = {
   requiredContextKeys,
   widgetTranslationPrefix,
   widgetTranslationKey,
+  sharedTranslationPrefix,
+  sharedTranslationKey,
+  isSharedTranslationKey,
+  SHARED_TRANSLATION_KEYS,
 };

package/dist/contract.js

@@ -1285,6 +1285,65 @@ function widgetTranslationKey(id, key) {
   return `widget.${id}.${key}`;
 }
 
+// REQ-L10N-SHARED — predefined SHARED translation keys for the standard
+// strings the default widgets repeat ("Submit", "Cancel", "Loading…", …).
+// They live in ONE tenant-wide namespace (`shared.<key>`) rather than the
+// per-widget namespace, so identical strings translate ONCE and every widget
+// that calls `t("<sharedKey>")` resolves the same dictionary value. An author
+// still overrides any instance by setting `widget.<id>.<key>` in the
+// Translations admin — `useI18n` resolves the per-widget key FIRST, then the
+// shared key, then the raw key, so the override is per-instance.
+//
+// This is the analogue of `widget.<id>.` for cross-widget reuse: one prefix,
+// one definition (the hook reads + the backend seeder writes both call these),
+// so the wire key and the lookup key can never drift.
+const SHARED_TRANSLATION_PREFIX = "shared.";
+function sharedTranslationPrefix() {
+  return SHARED_TRANSLATION_PREFIX;
+}
+function sharedTranslationKey(key) {
+  return `${SHARED_TRANSLATION_PREFIX}${key}`;
+}
+
+// The predefined set. Map of bare key -> { en } (English default only; the
+// tenant adds target-language values once in the Translations admin and every
+// widget inherits them). Adding/removing a key is a CONTRACT change (it grows
+// the dictionary every tenant gets), so the list lives with the contract and
+// the seeder reads it from here — never a second copy.
+const SHARED_TRANSLATION_KEYS = Object.freeze({
+  submit: { en: "Submit" },
+  cancel: { en: "Cancel" },
+  save: { en: "Save" },
+  delete: { en: "Delete" },
+  edit: { en: "Edit" },
+  close: { en: "Close" },
+  confirm: { en: "Confirm" },
+  back: { en: "Back" },
+  next: { en: "Next" },
+  previous: { en: "Previous" },
+  yes: { en: "Yes" },
+  no: { en: "No" },
+  ok: { en: "OK" },
+  loading: { en: "Loading…" },
+  search: { en: "Search" },
+  no_results: { en: "No results" },
+  required: { en: "Required" },
+  retry: { en: "Retry" },
+  add: { en: "Add" },
+  remove: { en: "Remove" },
+});
+
+// True when `key` is one of the predefined shared keys — the discriminator
+// `useI18n` uses to decide whether to try the `shared.<key>` namespace. A key
+// the author invents is NOT shared (it stays per-widget) so authors can't
+// accidentally collide with another widget by reusing a bare name.
+function isSharedTranslationKey(key) {
+  return (
+    typeof key === "string" &&
+    Object.prototype.hasOwnProperty.call(SHARED_TRANSLATION_KEYS, key)
+  );
+}
+
 const CONTRACT = deepFreeze({
   // REQ-WSDK-PLATFORM bump:
   //   - `vettedImports` is a new field (rich allowlist with platforms +
@@ -1486,7 +1545,23 @@ const CONTRACT = deepFreeze({
   //    on `react/jsx-runtime`. Adding them converges the linter onto the same
   //    contract every other surface already honoured (CLAUDE.md §3). No
   //    existing entry changed shape — minor bump on the pre-1.0 channel.
-  version: "1.27.0",
+  //
+  // 1.28.0: additive (REQ-L10N-SHARED) — predefined SHARED translation keys.
+  //    A new tenant-wide namespace `shared.<key>` carries the standard strings
+  //    the default widgets repeat ("Submit", "Cancel", "Loading…", …) so an
+  //    identical string is translated ONCE and every widget that calls
+  //    `t("<sharedKey>")` inherits it. New contract field
+  //    `sharedTranslationKeys` (the predefined map, the single source the
+  //    backend seeder reads) + new exported helpers `sharedTranslationPrefix()`
+  //    / `sharedTranslationKey(key)` / `isSharedTranslationKey(key)`.
+  //    `useI18n().t(key)` now resolves the per-widget key first, THEN the
+  //    shared key (when `key` is one of the predefined shared keys), then the
+  //    raw key — so a default widget picks up the shared translation with no
+  //    manual key entry, and a `widget.<id>.<key>` override still wins per
+  //    instance. No existing hook, primitive, manifest field, or token changed
+  //    shape — minor bump on the pre-1.0 channel.
+  version: "1.28.0",
+  sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
   manifestSchema: MANIFEST_SCHEMA,
@@ -1524,4 +1599,8 @@ export {
   requiredContextKeys,
   widgetTranslationPrefix,
   widgetTranslationKey,
+  sharedTranslationPrefix,
+  sharedTranslationKey,
+  isSharedTranslationKey,
+  SHARED_TRANSLATION_KEYS,
 };

package/dist/hooks.js

@@ -26,10 +26,18 @@ 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";
+// REQ-L10N-WIDGET / REQ-L10N-SHARED: the translation key formats live in ONE
+// place (contract.js). useI18n (lookup) and the backend seeder (write) both
+// call them so the namespaced keys can never drift between the two sides.
+// `widgetTranslationKey` builds the per-widget key (`widget.<id>.<key>`);
+// `sharedTranslationKey` builds the tenant-wide predefined key
+// (`shared.<key>`); `isSharedTranslationKey` tells the hook whether a bare key
+// is one of the predefined shared keys and so should try the shared namespace.
+import {
+  widgetTranslationKey,
+  sharedTranslationKey,
+  isSharedTranslationKey,
+} from "./contract.js";
 
 /** @internal — host-injected context value of shape WidgetContext (see index.d.ts). */
 const HostWidgetContext = createContext(null);
@@ -240,7 +248,27 @@ export function useI18n() {
             return scoped;
           }
         }
-        // 2) Fall back to the raw key (shared app keys + widgets with no
+        // 2) REQ-L10N-SHARED: for a predefined SHARED key, try the tenant-wide
+        //    `shared.<key>` namespace next. This is what lets identical
+        //    default-widget strings ("Submit", "Cancel", …) translate ONCE: a
+        //    widget that has no per-instance `widget.<id>.<key>` override
+        //    inherits the shared value. The per-widget step above runs FIRST,
+        //    so an author override of a single instance still wins for that
+        //    instance. Only the predefined keys are tried here — an
+        //    author-invented bare key is never silently shared.
+        if (isSharedTranslationKey(key)) {
+          const shared = sharedTranslationKey(key);
+          const scoped = hostT(shared);
+          if (
+            typeof scoped === "string" &&
+            scoped.length > 0 &&
+            scoped !== shared &&
+            !scoped.startsWith("{{t:")
+          ) {
+            return scoped;
+          }
+        }
+        // 3) 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) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.37.0",
+  "version": "0.38.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "type": "module",
   "main": "./dist/index.js",