@colixsystems/widget-sdk 0.22.0 → 0.24.0

package/README.md

@@ -45,7 +45,25 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`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**.
+`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
 

package/dist/contract.cjs

@@ -314,6 +314,31 @@ const HOOKS = [
     requiredContextSlice: ["datastore.records"],
     scopes: ["acl.write:records"],
   },
+  // REQ-RT-07 — realtime table subscription.
+  {
+    name: "useDatastoreSubscription",
+    signature: "useDatastoreSubscription(tableId, handlers, options?)",
+    description:
+      "Subscribe to a table's realtime change stream via the injected " +
+      "datastore-client at ctx.datastore.records(tableId).subscribe(...). " +
+      "handlers is { onCreated?, onUpdated?, onDeleted? }; each receives the " +
+      "snake_case record verbatim (same shape REST returns). The socket opens " +
+      "on mount, re-opens when tableId changes, and is torn down on unmount. " +
+      "Returns { status } where status is 'connecting' | 'live' | " +
+      "'reconnecting' | 'fallback'. The server gates each subscribe by the " +
+      "same read ACL REST honours; on an ACL reject, a missing WebSocket, or a " +
+      "host whose client predates realtime, the hook resolves to " +
+      "{ status: 'fallback' } WITHOUT throwing so the widget can poll instead. " +
+      "Reads the same datastore.read scope as useDatastoreQuery — declare " +
+      "datastore.read for the table you subscribe to. Pair with " +
+      "useDatastoreQuery for the initial load and merge the streamed envelopes.",
+    returnShape: {
+      status:
+        "'connecting' | 'live' | 'reconnecting' | 'fallback'  // transport state; 'fallback' → poll",
+    },
+    requiredContextSlice: ["datastore.records"],
+    scopes: ["datastore.read:<table>"],
+  },
   // REQ-WSDK-PLATFORM §6 — Tier A SDK hooks. Mirror of contract.js.
   {
     name: "useClipboard",
@@ -913,6 +938,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
@@ -1042,7 +1150,26 @@ const CONTRACT = deepFreeze({
   //    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",
+  //
+  // 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).
+  //
+  // 1.14.0: additive (REQ-RT-07) — new `useDatastoreSubscription(tableId,
+  //    handlers, options?)` hook reading ctx.datastore.records(t).subscribe.
+  //    Backed by the datastore-client 0.6.0 `subscribe` method (WebSocket to
+  //    `/datastore/ws`). Safe-by-default: resolves to { status: 'fallback' }
+  //    when the host's client predates realtime or no WebSocket is available,
+  //    so widgets degrade to polling on both platforms. No existing hook,
+  //    primitive, or contract field changed — minor bump on the pre-1.0 channel.
+  version: "1.14.0",
   hooks: HOOKS,
   primitives: PRIMITIVES,
   manifestSchema: MANIFEST_SCHEMA,

package/dist/contract.js

@@ -321,6 +321,31 @@ const HOOKS = [
     requiredContextSlice: ["datastore.records"],
     scopes: ["acl.write:records"],
   },
+  // REQ-RT-07 — realtime table subscription.
+  {
+    name: "useDatastoreSubscription",
+    signature: "useDatastoreSubscription(tableId, handlers, options?)",
+    description:
+      "Subscribe to a table's realtime change stream via the injected " +
+      "datastore-client at ctx.datastore.records(tableId).subscribe(...). " +
+      "handlers is { onCreated?, onUpdated?, onDeleted? }; each receives the " +
+      "snake_case record verbatim (same shape REST returns). The socket opens " +
+      "on mount, re-opens when tableId changes, and is torn down on unmount. " +
+      "Returns { status } where status is 'connecting' | 'live' | " +
+      "'reconnecting' | 'fallback'. The server gates each subscribe by the " +
+      "same read ACL REST honours; on an ACL reject, a missing WebSocket, or a " +
+      "host whose client predates realtime, the hook resolves to " +
+      "{ status: 'fallback' } WITHOUT throwing so the widget can poll instead. " +
+      "Reads the same datastore.read scope as useDatastoreQuery — declare " +
+      "datastore.read for the table you subscribe to. Pair with " +
+      "useDatastoreQuery for the initial load and merge the streamed envelopes.",
+    returnShape: {
+      status:
+        "'connecting' | 'live' | 'reconnecting' | 'fallback'  // transport state; 'fallback' → poll",
+    },
+    requiredContextSlice: ["datastore.records"],
+    scopes: ["datastore.read:<table>"],
+  },
   // REQ-WSDK-PLATFORM §6 — Tier A SDK hooks.
   {
     name: "useClipboard",
@@ -896,6 +921,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);
@@ -995,7 +1103,26 @@ const CONTRACT = deepFreeze({
   //    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",
+  //
+  // 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).
+  //
+  // 1.14.0: additive (REQ-RT-07) — new `useDatastoreSubscription(tableId,
+  //    handlers, options?)` hook reading ctx.datastore.records(t).subscribe.
+  //    Backed by the datastore-client 0.6.0 `subscribe` method (WebSocket to
+  //    `/datastore/ws`). Safe-by-default: resolves to { status: 'fallback' }
+  //    when the host's client predates realtime or no WebSocket is available,
+  //    so widgets degrade to polling on both platforms. No existing hook,
+  //    primitive, or contract field changed — minor bump on the pre-1.0 channel.
+  version: "1.14.0",
   hooks: HOOKS,
   primitives: PRIMITIVES,
   manifestSchema: MANIFEST_SCHEMA,

package/dist/hooks.js

@@ -921,6 +921,93 @@ export function useRecordPermissions(tableId, recordId) {
   return { permissions, loading, error, grant, revoke, update, refetch };
 }
 
+/**
+ * REQ-RT-07: subscribe to a table's realtime change stream. Reads
+ * `ctx.datastore.records(table).subscribe({ onCreated, onUpdated, onDeleted,
+ * onStatus })` and wires it to a React lifecycle: the socket is opened on
+ * mount (and re-opened when `table` changes) and torn down on unmount via the
+ * unsubscribe function the client returns. The author's `handlers` callbacks
+ * are held in a ref so re-renders with fresh callback identities never tear
+ * the socket down — only a `table` change does.
+ *
+ * Returns `{ status }` where status is "connecting" | "live" | "reconnecting"
+ * | "fallback". A widget typically pairs this with `useDatastoreQuery` for the
+ * initial load and merges the streamed create/update/delete envelopes into its
+ * local list; when `status === "fallback"` (no socket support on the host, the
+ * subscribe was ACL-rejected, or the connect timed out) the widget should run
+ * its own REST polling instead.
+ *
+ * Cross-platform + safe-by-default: if the host's datastore client doesn't
+ * expose `subscribe` (an older host, or a runtime with no WebSocket), the hook
+ * resolves to `{ status: "fallback" }` WITHOUT throwing, so a widget that
+ * subscribes degrades to polling on both the web Player and the native export
+ * rather than crashing at render (CLAUDE.md §11).
+ *
+ * @param {string} table  Bound table id (falsy → no subscription, status "fallback").
+ * @param {{ onCreated?, onUpdated?, onDeleted? }} [handlers]  Per-event callbacks; each receives the snake_case record.
+ * @param {{ fallbackAfterMs?: number }} [options]
+ * @returns {{ status: "connecting" | "live" | "reconnecting" | "fallback" }}
+ */
+export function useDatastoreSubscription(table, handlers, options) {
+  const ctx = useWidgetContextOrThrow("useDatastoreSubscription");
+  const [status, setStatus] = useState("connecting");
+
+  // Author callbacks live in a ref so a new closure each render does not
+  // re-run the effect (which would tear down + re-open the socket).
+  const handlersRef = useRef(handlers);
+  handlersRef.current = handlers;
+  // `ctx` is a fresh object identity per host render; hold the records
+  // factory in a ref so the effect depends only on `table`.
+  const recordsRef = useRef(
+    ctx.datastore && typeof ctx.datastore.records === "function"
+      ? ctx.datastore.records
+      : null,
+  );
+  recordsRef.current =
+    ctx.datastore && typeof ctx.datastore.records === "function"
+      ? ctx.datastore.records
+      : null;
+
+  const fallbackAfterMs =
+    options && Number.isFinite(options.fallbackAfterMs)
+      ? options.fallbackAfterMs
+      : undefined;
+
+  useEffect(() => {
+    if (!table || typeof recordsRef.current !== "function") {
+      setStatus("fallback");
+      return undefined;
+    }
+    let ns;
+    try {
+      ns = recordsRef.current(table);
+    } catch (_) {
+      setStatus("fallback");
+      return undefined;
+    }
+    if (!ns || typeof ns.subscribe !== "function") {
+      // Host's datastore client predates realtime — degrade to polling.
+      setStatus("fallback");
+      return undefined;
+    }
+    const stop = ns.subscribe(
+      {
+        onCreated: (r) => handlersRef.current?.onCreated?.(r),
+        onUpdated: (r) => handlersRef.current?.onUpdated?.(r),
+        onDeleted: (r) => handlersRef.current?.onDeleted?.(r),
+        onStatus: (s) => setStatus(s),
+      },
+      fallbackAfterMs != null ? { fallbackAfterMs } : undefined,
+    );
+    return () => {
+      if (typeof stop === "function") stop();
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [table, fallbackAfterMs]);
+
+  return { status };
+}
+
 /* ============================================================================
  * FILES CLIENT — ctx.files (@colixsystems/files-client)
  *

package/dist/index.d.ts

@@ -624,6 +624,37 @@ export function useDatastoreSchema(
   tableId: string | null | undefined,
 ): SchemaResult;
 
+// REQ-RT-07 realtime subscription transport state.
+export type DatastoreSubscriptionStatus =
+  | "connecting"
+  | "live"
+  | "reconnecting"
+  | "fallback";
+
+export interface DatastoreSubscriptionHandlers {
+  onCreated?: (record: Record<string, unknown>) => void;
+  onUpdated?: (record: Record<string, unknown>) => void;
+  onDeleted?: (record: Record<string, unknown>) => void;
+}
+
+export interface DatastoreSubscriptionOptions {
+  fallbackAfterMs?: number;
+}
+
+/**
+ * REQ-RT-07: subscribe to a table's realtime change stream via
+ * `ctx.datastore.records(tableId).subscribe(...)`. Opens on mount, re-opens on
+ * `tableId` change, tears down on unmount. Returns `{ status }`; when status
+ * is `"fallback"` (no socket support, ACL-rejected, or connect timed out) run
+ * REST polling instead. Never throws — degrades to `{ status: "fallback" }` on
+ * a host whose datastore client predates realtime.
+ */
+export function useDatastoreSubscription(
+  tableId: string | null | undefined,
+  handlers?: DatastoreSubscriptionHandlers,
+  options?: DatastoreSubscriptionOptions,
+): { status: DatastoreSubscriptionStatus };
+
 /**
  * Stateful file-asset resolver hook. Returns `{ url, file, loading, error,
  * refetch }`. The `url` is an absolute URL composed against the host's API

package/dist/index.js

@@ -20,6 +20,7 @@ export {
   useUsers,
   useGroups,
   useRecordPermissions,
+  useDatastoreSubscription,
   useWidgetEvent,
   usePayments,
   useTheme,

package/dist/index.native.js

@@ -20,6 +20,7 @@ export {
   useUsers,
   useGroups,
   useRecordPermissions,
+  useDatastoreSubscription,
   useWidgetEvent,
   usePayments,
   useTheme,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.22.0",
+  "version": "0.24.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "type": "module",
   "main": "./dist/index.js",
@@ -35,7 +35,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-mutation.test.js src/__tests__/hooks-record-permissions.test.js src/__tests__/linter-users-scope.test.js src/__tests__/manifest-actions.test.js src/__tests__/widget-translations.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-mutation.test.js src/__tests__/hooks-record-permissions.test.js src/__tests__/hooks-subscription.test.js src/__tests__/linter-users-scope.test.js src/__tests__/manifest-actions.test.js src/__tests__/widget-translations.test.js"
   },
   "engines": {
     "node": ">=18"