@colixsystems/widget-sdk 0.54.0 → 0.56.0

package/README.md

@@ -52,7 +52,15 @@ 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.56.0
+
+**New linter rule `react-not-imported` — widget source must be self-contained (sc-2353).** The automatic JSX runtime binds `jsx`/`jsxs` from `react/jsx-runtime` but never `React` itself, so source that reaches for the bare `React` global (`React.createElement` / `React.Fragment` / `React.memo` / `React.useMemo`) without importing it bundles cleanly, then throws `ReferenceError: React is not defined` the moment a non-initial code path hits the reference. The platform does **not** inject a `React` binding — earlier behaviour that auto-injected one left source that broke as soon as it was downloaded and re-uploaded through a path that doesn't inject. The linter now flags a bare-`React` reference with no `import React from "react"` (or `import * as React`) as an error, so the failure becomes a publish/upload finding (and an AI-agent repair-loop finding) instead of a broken shipped widget. Plain JSX, which needs no React import, is never flagged; a `React` mention inside a comment or string is masked. Author fix: add `import React from "react";` (`react` is already vetted), or prefer a JSX fragment `<>…</>` plus the SDK hooks/primitives over reaching for `React` directly. `CONTRACT` is unchanged (no new field).
 
 ### What's new in 0.54.0
 
@@ -326,6 +334,7 @@ The "split-implementation + vetted package list" pivot.
 - **`fetch` and `XMLHttpRequest` come off `CONTRACT.bannedApis`.** Widgets may call third-party APIs directly. Calls to the host's own `/api/*` surface will 401 because the JWT token is never shared with widget code; the linter emits a soft `no-host-api-url` warning when it sees host-URL substrings so authors learn the rule statically. Use SDK hooks (`useDatastoreQuery`, `useUsers`, `useAsset`, …) for workspace data; use `axios` / `fetch` for third-party APIs.
 - **`import-not-vetted` linter rule (new).** Every bare `import` specifier is validated against `CONTRACT.vettedImports`. Relative imports inside the bundle (`./shared.js`) are allowed so split-impl widgets can share helpers; `../` and absolute paths are rejected.
 - **`import-platform-mismatch` linter rule (new).** A single-source widget that imports a native-only package while `manifest.supportedPlatforms` includes `"web"` fails the lint. The author either drops the platform from the manifest OR ships a `widget.web.jsx` + `widget.native.jsx` pair where the platform-specific import lives in the file that targets its platform.
+- **`react-not-imported` linter rule (new).** Widget source must be self-contained: a reference to the bare `React` global (`React.createElement` / `React.Fragment` / `React.memo` / …) with no `import React from "react"` (or `import * as React`) fails the lint — it would throw `ReferenceError: React is not defined` at render. Plain JSX needs no React import and is never flagged. Add the import, or prefer a JSX fragment `<>…</>` plus the SDK hooks/primitives.
 - **Lint findings carry `severity`.** `"error"` (default) blocks publish; `"warning"` (currently only `no-host-api-url`) surfaces to reviewers without blocking. The `lintSource(...)` return shape stays `{ ok, findings }` — `ok` is true iff no error-severity findings exist.
 - **Four Tier A SDK additions:**
   - `<Icon>` primitive — `<Icon name="check" size={16} color={theme.colors.primary} />`. Wraps `lucide-react-native`; works on both platforms.

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/linter.cjs

@@ -594,6 +594,46 @@ function _lucideIconRules(source) {
   return findings;
 }
 
+// sc-2353 — widget source must be self-contained. The automatic JSX runtime
+// binds jsx/jsxs from react/jsx-runtime but never `React` itself, so a widget
+// that reaches for the bare `React` global (React.createElement / React.Fragment
+// / React.memo / React.useMemo) without importing it renders fine until a
+// non-initial code path hits the reference, then throws "React is not defined".
+// The platform does NOT inject a React binding — require an explicit
+// `import React from "react"` (or `import * as React`) whenever the source
+// references React, so the bundle is self-contained on both hosts and survives
+// a download → re-upload round-trip. Plain JSX needs no React import.
+const _REACT_DEFAULT_IMPORT_RE = /\bimport\s+(?:React\b|\*\s+as\s+React\b)/;
+const _REACT_MEMBER_USE_RE = /\bReact\s*\./;
+function _reactInScopeRules(source) {
+  const findings = [];
+  const code = _stripNonCode(source);
+  if (!_REACT_MEMBER_USE_RE.test(code)) return findings;
+  if (_REACT_DEFAULT_IMPORT_RE.test(code)) return findings;
+  const codeLines = code.split(/\r?\n/);
+  const sourceLines = source.split(/\r?\n/);
+  let line = 0;
+  for (let i = 0; i < codeLines.length; i += 1) {
+    if (_REACT_MEMBER_USE_RE.test(codeLines[i])) {
+      line = i + 1;
+      break;
+    }
+  }
+  findings.push({
+    rule: "react-not-imported",
+    severity: "error",
+    label:
+      "source references the `React` global (e.g. React.createElement / " +
+      "React.Fragment) but never imports it — widget source must be " +
+      'self-contained. Add `import React from "react";` at the top, or drop ' +
+      "the bare `React` reference in favour of a JSX fragment `<>…</>` and the " +
+      "SDK hooks (useState / useMemo / …) and primitives (View / Text / …).",
+    line,
+    snippet: (sourceLines[line - 1] || "").trim().slice(0, 200),
+  });
+  return findings;
+}
+
 // Narrow a split-impl widget's manifest to the platform a single bundle file
 // ships to, so `import-platform-mismatch` lints each file against what it
 // actually targets. Mirror of linter.js.
@@ -653,6 +693,7 @@ function lintSource(source, options) {
   );
   findings.push(..._hostApiUrlRules(source));
   findings.push(..._lucideIconRules(source));
+  findings.push(..._reactInScopeRules(source));
   findings.push(
     ..._scopeRules(source, options && options.manifest).map((f) => ({
       ...f,

package/dist/linter.js

@@ -683,6 +683,46 @@ function _lucideIconRules(source) {
   return findings;
 }
 
+// sc-2353 — widget source must be self-contained. The automatic JSX runtime
+// binds jsx/jsxs from react/jsx-runtime but never `React` itself, so a widget
+// that reaches for the bare `React` global (React.createElement / React.Fragment
+// / React.memo / React.useMemo) without importing it renders fine until a
+// non-initial code path hits the reference, then throws "React is not defined".
+// The platform does NOT inject a React binding — require an explicit
+// `import React from "react"` (or `import * as React`) whenever the source
+// references React, so the bundle is self-contained on both hosts and survives
+// a download → re-upload round-trip. Plain JSX needs no React import.
+const _REACT_DEFAULT_IMPORT_RE = /\bimport\s+(?:React\b|\*\s+as\s+React\b)/;
+const _REACT_MEMBER_USE_RE = /\bReact\s*\./;
+function _reactInScopeRules(source) {
+  const findings = [];
+  const code = _stripNonCode(source);
+  if (!_REACT_MEMBER_USE_RE.test(code)) return findings;
+  if (_REACT_DEFAULT_IMPORT_RE.test(code)) return findings;
+  const codeLines = code.split(/\r?\n/);
+  const sourceLines = source.split(/\r?\n/);
+  let line = 0;
+  for (let i = 0; i < codeLines.length; i += 1) {
+    if (_REACT_MEMBER_USE_RE.test(codeLines[i])) {
+      line = i + 1;
+      break;
+    }
+  }
+  findings.push({
+    rule: "react-not-imported",
+    severity: "error",
+    label:
+      "source references the `React` global (e.g. React.createElement / " +
+      "React.Fragment) but never imports it — widget source must be " +
+      'self-contained. Add `import React from "react";` at the top, or drop ' +
+      "the bare `React` reference in favour of a JSX fragment `<>…</>` and the " +
+      "SDK hooks (useState / useMemo / …) and primitives (View / Text / …).",
+    line,
+    snippet: (sourceLines[line - 1] || "").trim().slice(0, 200),
+  });
+  return findings;
+}
+
 /**
  * Narrow a split-impl widget's manifest to the platform a single bundle file
  * ships to, so `import-platform-mismatch` lints each file against what it
@@ -748,6 +788,8 @@ export function lintSource(source, options) {
   // REQ-WSDK-PLATFORM §3.5: soft host-API URL warning (does not block).
   findings.push(..._hostApiUrlRules(source));
   findings.push(..._lucideIconRules(source));
+  // sc-2353 — widget source must be self-contained (reference React ⇒ import it).
+  findings.push(..._reactInScopeRules(source));
   // REQ-USERMGMT / REQ-ACL-SYS M3 — scope-aware rules. Run after the
   // line-by-line scan so banned-identifier findings stay first in the
   // output.

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.56.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "type": "module",
   "main": "./dist/index.js",
@@ -42,7 +42,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-assets-by-tag.test.js src/__tests__/hooks-filestore-upload.test.js src/__tests__/hooks-mutation.test.js src/__tests__/hooks-record-permissions.test.js src/__tests__/hooks-geolocation.test.js src/__tests__/hooks-subscription.test.js src/__tests__/linter-users-scope.test.js src/__tests__/linter-comments.test.js src/__tests__/lucide-icon-names.test.js src/__tests__/lucideIconName.test.js src/__tests__/manifest-actions.test.js src/__tests__/widget-translations.test.js src/__tests__/devserver.test.js src/__tests__/host-externals.test.js src/__tests__/datetimepicker.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-assets-by-tag.test.js src/__tests__/hooks-filestore-upload.test.js src/__tests__/hooks-mutation.test.js src/__tests__/hooks-record-permissions.test.js src/__tests__/hooks-geolocation.test.js src/__tests__/hooks-subscription.test.js src/__tests__/linter-users-scope.test.js src/__tests__/linter-comments.test.js src/__tests__/linter-platform.test.js src/__tests__/linter-react-import.test.js src/__tests__/lucide-icon-names.test.js src/__tests__/lucideIconName.test.js src/__tests__/manifest-actions.test.js src/__tests__/widget-translations.test.js src/__tests__/devserver.test.js src/__tests__/host-externals.test.js src/__tests__/datetimepicker.test.js"
   },
   "engines": {
     "node": ">=18"