@colixsystems/widget-sdk 0.21.1 → 0.23.0

package/README.md

@@ -45,7 +45,35 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.21.1` — 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.23.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.23.0
+
+**Curated cross-platform package expansion to the vetted import allowlist (REQ-WSDK-PKG-EXPAND).**
+
+- The linter's vetted import allowlist (`CONTRACT.vettedImports`) gains a curated set of popular React Native packages, each of which runs on **both** web and native (directly, or via a documented platform-split counterpart):
+  - **`react-native-reanimated`** (`web`/`native`) — declarative animations.
+  - **`react-native-gesture-handler`** (`web`/`native`) — native-driven touch gestures.
+  - **`react-native-safe-area-context`** (`web`/`native`) — safe-area insets.
+  - **`@shopify/flash-list`** (`web`/`native`) — high-performance virtualised list.
+  - **`react-native-paper`** (`web`/`native`) — Material Design components.
+  - **`react-native-vector-icons`** (`web`/`native`) — icon font families.
+  - **`@react-native-community/slider`** (`web`/`native`) — slider input.
+  - **`expo-linear-gradient`** (`web`/`native`) — the cross-platform gradient.
+  - **`lottie-react-native`** (`native`) + **`lottie-react`** (`web`) — Lottie animations, split-impl.
+  - **`react-native-webview`** (`native`) — embedded web content (pair with an `<iframe>` on web).
+- **Parity (CLAUDE.md §3):** the compiler now pins the native-module members in the exported Expo app's `package.json` and emits the **`react-native-reanimated/plugin`** in `babel.config.js` **unconditionally** (previously only for the sidebar-drawer shell), so a baked widget that imports any of these resolves and bundles on native exactly as it renders in the web Player.
+- **`CONTRACT.version` → `1.13.0`** (additive: new vetted import entries only). No existing export, type, manifest field, hook, or banned-API list changed.
+
+### 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
 

package/dist/contract.cjs

@@ -913,6 +913,89 @@ const VETTED_IMPORTS = [
     description:
       "Native haptic feedback. Pair with navigator.vibrate in widget.web.jsx.",
   },
+  // REQ-WSDK-PKG-EXPAND — curated cross-platform package expansion. Each entry
+  // below runs on web AND native (directly, or via the documented platform-split
+  // counterpart). Native-module packages additionally carry a pinned version in
+  // the compiler's generatePackageJson so a baked marketplace widget resolves in
+  // the Expo export (CLAUDE.md §3 parity). See the `adding-vetted-packages` skill
+  // for the full add checklist (contract ×2, version bump, compiler pin, docs).
+  {
+    specifier: "react-native-reanimated",
+    platforms: ["web", "native"],
+    category: "animation",
+    description:
+      "Declarative, performant animations. Works on both platforms; the export always emits the required react-native-reanimated/plugin in babel.config.js so a widget using worklets bundles on native.",
+  },
+  {
+    specifier: "react-native-gesture-handler",
+    platforms: ["web", "native"],
+    category: "gesture",
+    description:
+      "Native-driven touch gestures (pan, pinch, swipe, long-press). Works on both platforms; wrap interactive trees in GestureHandlerRootView.",
+  },
+  {
+    specifier: "react-native-safe-area-context",
+    platforms: ["web", "native"],
+    category: "layout",
+    description:
+      "Safe-area insets (notch / status bar). useSafeAreaInsets() returns zeros on web and the real insets on native, so the same layout code is safe on both.",
+  },
+  {
+    specifier: "@shopify/flash-list",
+    platforms: ["web", "native"],
+    category: "list",
+    description:
+      "High-performance virtualised list with a FlatList-compatible API. Prefer it over FlatList for long datasets; renders on both platforms.",
+  },
+  {
+    specifier: "react-native-paper",
+    platforms: ["web", "native"],
+    category: "ui",
+    description:
+      "Material Design component library built on react-native + react-native-web, so the same components render identically on both platforms.",
+  },
+  {
+    specifier: "react-native-vector-icons",
+    platforms: ["web", "native"],
+    category: "iconography",
+    description:
+      "Icon font families (MaterialIcons, FontAwesome, Ionicons, …). Works on both platforms; prefer the SDK's <Icon> (lucide) primitive for the common case.",
+  },
+  {
+    specifier: "@react-native-community/slider",
+    platforms: ["web", "native"],
+    category: "input",
+    description:
+      "Cross-platform slider input. Controlled — value + onValueChange. Works on both platforms.",
+  },
+  {
+    specifier: "expo-linear-gradient",
+    platforms: ["web", "native"],
+    category: "drawing",
+    description:
+      "Linear-gradient fill (<LinearGradient colors={[...]} />). The cross-platform gradient — works on both platforms (react-native-linear-gradient is native-only; prefer this).",
+  },
+  {
+    specifier: "lottie-react-native",
+    platforms: ["native"],
+    category: "animation",
+    description:
+      "After Effects (Bodymovin) JSON animations. Native-only; pair with lottie-react in widget.web.jsx for the web variant.",
+  },
+  {
+    specifier: "lottie-react",
+    platforms: ["web"],
+    category: "animation",
+    description:
+      "Web Lottie player. Web-only counterpart to lottie-react-native; bundle it into widget.web.jsx.",
+  },
+  {
+    specifier: "react-native-webview",
+    platforms: ["native"],
+    category: "media",
+    description:
+      "Embeds web content in a native WebView. Native-only; on web render an <iframe> (or a View with the URL) in widget.web.jsx.",
+  },
 ];
 
 // Back-compat shape — every existing consumer (widgetLoader, the static
@@ -1034,7 +1117,26 @@ const CONTRACT = deepFreeze({
   //    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).
-  version: "1.11.1",
+  //
+  // 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.
+  //
+  // 1.13.0: additive (REQ-WSDK-PKG-EXPAND) — the vetted import allowlist gains
+  //    a curated cross-platform package set: react-native-reanimated,
+  //    react-native-gesture-handler, react-native-safe-area-context,
+  //    @shopify/flash-list, react-native-paper, react-native-vector-icons,
+  //    @react-native-community/slider, expo-linear-gradient, react-native-webview,
+  //    and lottie-react-native (+ lottie-react as its web counterpart). No
+  //    existing entry changed shape and no other contract field moved, so this
+  //    is additive — minor bump on the pre-1.0 channel. The compiler pins the
+  //    native-module members in the exported Expo app's package.json and now
+  //    always emits the react-native-reanimated/plugin (CLAUDE.md §3 parity).
+  version: "1.13.0",
   hooks: HOOKS,
   primitives: PRIMITIVES,
   manifestSchema: MANIFEST_SCHEMA,

package/dist/contract.js

@@ -896,6 +896,89 @@ const VETTED_IMPORTS = [
     description:
       "Native haptic feedback. Pair with navigator.vibrate in widget.web.jsx.",
   },
+  // REQ-WSDK-PKG-EXPAND — curated cross-platform package expansion. Each entry
+  // below runs on web AND native (directly, or via the documented platform-split
+  // counterpart). Native-module packages additionally carry a pinned version in
+  // the compiler's generatePackageJson so a baked marketplace widget resolves in
+  // the Expo export (CLAUDE.md §3 parity). See the `adding-vetted-packages` skill
+  // for the full add checklist (contract ×2, version bump, compiler pin, docs).
+  {
+    specifier: "react-native-reanimated",
+    platforms: ["web", "native"],
+    category: "animation",
+    description:
+      "Declarative, performant animations. Works on both platforms; the export always emits the required react-native-reanimated/plugin in babel.config.js so a widget using worklets bundles on native.",
+  },
+  {
+    specifier: "react-native-gesture-handler",
+    platforms: ["web", "native"],
+    category: "gesture",
+    description:
+      "Native-driven touch gestures (pan, pinch, swipe, long-press). Works on both platforms; wrap interactive trees in GestureHandlerRootView.",
+  },
+  {
+    specifier: "react-native-safe-area-context",
+    platforms: ["web", "native"],
+    category: "layout",
+    description:
+      "Safe-area insets (notch / status bar). useSafeAreaInsets() returns zeros on web and the real insets on native, so the same layout code is safe on both.",
+  },
+  {
+    specifier: "@shopify/flash-list",
+    platforms: ["web", "native"],
+    category: "list",
+    description:
+      "High-performance virtualised list with a FlatList-compatible API. Prefer it over FlatList for long datasets; renders on both platforms.",
+  },
+  {
+    specifier: "react-native-paper",
+    platforms: ["web", "native"],
+    category: "ui",
+    description:
+      "Material Design component library built on react-native + react-native-web, so the same components render identically on both platforms.",
+  },
+  {
+    specifier: "react-native-vector-icons",
+    platforms: ["web", "native"],
+    category: "iconography",
+    description:
+      "Icon font families (MaterialIcons, FontAwesome, Ionicons, …). Works on both platforms; prefer the SDK's <Icon> (lucide) primitive for the common case.",
+  },
+  {
+    specifier: "@react-native-community/slider",
+    platforms: ["web", "native"],
+    category: "input",
+    description:
+      "Cross-platform slider input. Controlled — value + onValueChange. Works on both platforms.",
+  },
+  {
+    specifier: "expo-linear-gradient",
+    platforms: ["web", "native"],
+    category: "drawing",
+    description:
+      "Linear-gradient fill (<LinearGradient colors={[...]} />). The cross-platform gradient — works on both platforms (react-native-linear-gradient is native-only; prefer this).",
+  },
+  {
+    specifier: "lottie-react-native",
+    platforms: ["native"],
+    category: "animation",
+    description:
+      "After Effects (Bodymovin) JSON animations. Native-only; pair with lottie-react in widget.web.jsx for the web variant.",
+  },
+  {
+    specifier: "lottie-react",
+    platforms: ["web"],
+    category: "animation",
+    description:
+      "Web Lottie player. Web-only counterpart to lottie-react-native; bundle it into widget.web.jsx.",
+  },
+  {
+    specifier: "react-native-webview",
+    platforms: ["native"],
+    category: "media",
+    description:
+      "Embeds web content in a native WebView. Native-only; on web render an <iframe> (or a View with the URL) in widget.web.jsx.",
+  },
 ];
 
 const ALLOWED_BARE_IMPORTS = VETTED_IMPORTS.map((v) => v.specifier);
@@ -987,7 +1070,26 @@ const CONTRACT = deepFreeze({
   //    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).
-  version: "1.11.1",
+  //
+  // 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.
+  //
+  // 1.13.0: additive (REQ-WSDK-PKG-EXPAND) — the vetted import allowlist gains
+  //    a curated cross-platform package set: react-native-reanimated,
+  //    react-native-gesture-handler, react-native-safe-area-context,
+  //    @shopify/flash-list, react-native-paper, react-native-vector-icons,
+  //    @react-native-community/slider, expo-linear-gradient, react-native-webview,
+  //    and lottie-react-native (+ lottie-react as its web counterpart). No
+  //    existing entry changed shape and no other contract field moved, so this
+  //    is additive — minor bump on the pre-1.0 channel. The compiler pins the
+  //    native-module members in the exported Expo app's package.json and now
+  //    always emits the react-native-reanimated/plugin (CLAUDE.md §3 parity).
+  version: "1.13.0",
   hooks: HOOKS,
   primitives: PRIMITIVES,
   manifestSchema: MANIFEST_SCHEMA,

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;

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.21.1",
+  "version": "0.23.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "type": "module",
   "main": "./dist/index.js",