@colixsystems/widget-sdk 0.21.1 → 0.22.0

package/README.md

@@ -45,7 +45,17 @@ 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.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.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

@@ -1034,7 +1034,15 @@ 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.
+  version: "1.12.0",
   hooks: HOOKS,
   primitives: PRIMITIVES,
   manifestSchema: MANIFEST_SCHEMA,

package/dist/contract.js

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