@colixsystems/widget-sdk 0.54.0 → 0.55.0

package/README.md

@@ -52,7 +52,11 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.54.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.55.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.55.0
+
+**Dynamic record selection for `valueRef` (sc-2327).** The `valueRef` binding gains an optional `mode` field: `"static"` (the default — pin a specific `recordId`, the only prior behaviour) or `"latest"` (resolve the most recently created row live, sorting on the host-managed `created_at` descending with `limit: 1`; `recordId` is ignored). The built-in Field Value widget reads it to offer a "Latest entry" that updates as records are added, with no per-host code — the same baked widget source and the same injected `@colixsystems/datastore-client` run on the web Player and the native Expo export. The `ValueRefBinding` type adds `mode?: "static" | "latest"`. Existing bindings carry no `mode` and read as static. `CONTRACT.version` → `1.39.0`. Additive — no existing field changed shape.
 
 ### What's new in 0.54.0
 

package/dist/contract.cjs

@@ -1858,7 +1858,13 @@ const CONTRACT = deepFreeze({
   //    Player and the native export, so no browser-only PDF library is added
   //    to the vetted set. No existing hook, primitive, manifest field, or
   //    token changed shape — minor bump.
-  version: "1.38.0",
+  // 1.39.0: additive (sc-2327) — the `valueRef` propertySchema binding gains
+  //    an optional `mode` field: "static" (a pinned recordId, the default and
+  //    the only prior behaviour) or "latest" (the most recently created row,
+  //    resolved live by `created_at` desc with limit 1; recordId ignored). The
+  //    Field Value widget reads it to show a live "latest entry". Existing
+  //    bindings have no `mode` and read as static — additive, minor bump.
+  version: "1.39.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -1858,7 +1858,13 @@ const CONTRACT = deepFreeze({
   //    Player and the native export, so no browser-only PDF library is added
   //    to the vetted set. No existing hook, primitive, manifest field, or
   //    token changed shape — minor bump.
-  version: "1.38.0",
+  // 1.39.0: additive (sc-2327) — the `valueRef` propertySchema binding gains
+  //    an optional `mode` field: "static" (a pinned recordId, the default and
+  //    the only prior behaviour) or "latest" (the most recently created row,
+  //    resolved live by `created_at` desc with limit 1; recordId ignored). The
+  //    Field Value widget reads it to show a live "latest entry". Existing
+  //    bindings have no `mode` and read as static — additive, minor bump.
+  version: "1.39.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/index.d.ts

@@ -101,6 +101,12 @@ export interface ValueRefBinding {
   tableId?: string;
   recordId?: string;
   column?: string;
+  /**
+   * How the record is chosen. "static" (default, may be omitted) pins
+   * `recordId`; "latest" resolves the most recently created row live and
+   * ignores `recordId`.
+   */
+  mode?: "static" | "latest";
 }
 
 export interface WidgetEventDescriptor {

package/dist/property-schema.js

@@ -183,10 +183,12 @@ function coerceLeaf(def, value, path, errors) {
       }
       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
+      // REQ-WDG-VALUEREF: a `{ tableId, recordId, column, mode }` binding.
+      // Each string sub-field is optional (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.
+      // missing piece as "no value" and shows its fallback. sc-2327: `mode`
+      // selects how the record is chosen — "static" (a pinned recordId, the
+      // default) or "latest" (the newest row, resolved live; recordId ignored).
       if (!isPlainObject(value)) {
         errors.push(`${path}: expected object`);
         return value;
@@ -197,6 +199,14 @@ function coerceLeaf(def, value, path, errors) {
           errors.push(`${path}.${sub}: expected string`);
         }
       }
+      if (
+        value.mode !== undefined &&
+        value.mode !== null &&
+        value.mode !== "static" &&
+        value.mode !== "latest"
+      ) {
+        errors.push(`${path}.mode: expected "static" or "latest"`);
+      }
       return value;
     }
     case "object": {

package/package.json

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