@colixsystems/widget-sdk 0.40.2 → 0.41.0

package/README.md

@@ -13,7 +13,7 @@ The data layer lives in **four separate domain-client packages**, each instantia
 
 **Wire / casing: snake_case end to end.** The clients send and return snake_case **verbatim** (`created_at`, `group_ids`, `can_read`, `amount_cents`, `data_type`, `is_active`, …). There is **no case transform anywhere** — not on the client and not in the backend; the only casing boundary is Prisma `@map` (snake_case field → camelCase column). Author-defined record column values pass through verbatim. Every `list(...)` returns the `{ data, meta }` envelope; the read hooks unwrap `res.data` for you.
 
-**Hooks read the injected clients** — they do not hold their own HTTP. This is the **complete** hook surface (18 hooks), grouped by the domain client each one reads. **CORE** hooks read host state directly off `WidgetContext` (no data client); the rest delegate to one of the four injected clients. The grouping mirrors the banner sections in [`src/hooks.js`](src/hooks.js).
+**Hooks read the injected clients** — they do not hold their own HTTP. This is the **complete** hook surface (19 hooks), grouped by the domain client each one reads. **CORE** hooks read host state directly off `WidgetContext` (no data client); the rest delegate to one of the four injected clients. The grouping mirrors the banner sections in [`src/hooks.js`](src/hooks.js).
 
 | Group | Hook (signature) | Returns | Reads / scope |
 | ----- | ---------------- | ------- | ------------- |
@@ -24,6 +24,7 @@ The data layer lives in **four separate domain-client packages**, each instantia
 | **CORE** | `useWidgetEvent(name)` | `(payload?) => void` | `ctx.events.emit` — no scope |
 | **CORE** | `useChildRenderer()` | `{ renderNode(node) }` | `ctx.renderer` — no scope (prefer the `WidgetTree` component) |
 | **CORE** | `useFill()` | `boolean` | `ctx.fill` — no scope. `true` when the host sized this widget to fill its page-grid tile's reserved height (containers + media fill by default; the author can override per tile). Media-style widgets switch to a `flex: 1` / `height: "100%"` layout; others ignore it. Defaults `false`. |
+| **CORE** | `useRefresh(handler)` | `void` | `ctx.refresh.subscribe` — no scope. Subscribes the handler to the page-level refresh tick (pull-to-refresh on mobile). Handler may return a Promise — the host waits for `allSettled` before clearing the spinner. The three datastore hooks auto-subscribe their own `refetch`; widgets only call this directly to re-run non-datastore work. No-op on a host that doesn't implement refresh. |
 | **CORE** | `useClipboard()` | `{ copy, paste, hasContent }` | platform clipboard (web `navigator.clipboard` / native `expo-clipboard`); rejects with `ClipboardError` — no scope |
 | **CORE** | `useToast()` | `{ showToast }` | `ctx.toast.showToast` (falls back to a CustomEvent / console) — no scope |
 | **CORE** | `useI18n()` | `{ t, locale }` | `ctx.i18n` — no scope. `t(key)` resolves the widget-namespaced key (`widget.<id>.<key>`, declared in `manifest.translations`) first, then a **predefined shared key** (`shared.<key>`) when `key` is one of the standard strings (`submit`, `cancel`, `save`, `loading`, …), then the raw key. Use a shared key for an identical default string so it translates once and any per-instance `widget.<id>.<key>` override still wins. |
@@ -47,7 +48,11 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.40.2` — 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.41.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.41.0
+
+**New `useRefresh(handler)` hook + page-level refresh signal (sc-1179).** Pull-to-refresh on the mobile web Player + the native Expo export's `RefreshControl` now fans a page-level refresh tick out to every widget on the page. The three datastore hooks — `useDatastoreQuery`, `useDatastoreRecord`, `useAsset` — auto-subscribe their own `refetch`, so a widget built on those hooks gets refreshed for free. Widgets that need to re-run other work (a third-party `fetch`, a derived calculation) call `useRefresh(async () => { … })` directly. The handler may return a Promise — the host waits on `Promise.allSettled` of every subscriber before clearing the spinner. The slot (`ctx.refresh.subscribe`) is optional on the WidgetContext: a host that does not implement refresh (the Studio canvas preview) simply omits it and the hook collapses to a no-op. Additive — `CONTRACT.version` bumped to the next minor since the contract grew a new hook + a new (optional) context slice.
 
 ### What's new in 0.40.2
 

package/dist/contract.cjs

@@ -116,6 +116,26 @@ const HOOKS = [
     requiredContextSlice: ["renderer.renderNode"],
     scopes: null,
   },
+  {
+    name: "useRefresh",
+    signature: "useRefresh(handler)",
+    description:
+      "Subscribe to the page-level refresh tick (pull-to-refresh on " +
+      "mobile, manual refresh button, etc.). The handler is called every " +
+      "time the host triggers a refresh; it may return a Promise — the " +
+      "host waits on all settled handlers before clearing the refresh " +
+      "indicator. The three datastore hooks (useDatastoreQuery, " +
+      "useDatastoreRecord, useAsset) already subscribe automatically — " +
+      "widgets only call useRefresh directly when they need to re-run " +
+      "non-datastore work (a third-party fetch, a derived calculation). " +
+      "Safe to call on a host that does not implement refresh — it is a " +
+      "no-op there.",
+    returnShape: {
+      "(returns)": "void",
+    },
+    requiredContextSlice: ["refresh.subscribe"],
+    scopes: null,
+  },
   {
     name: "useNavigation",
     signature: "useNavigation()",
@@ -924,6 +944,21 @@ const WIDGET_CONTEXT_SHAPE = {
     required: true,
     fields: { renderNode: "function" },
   },
+  // sc-1179 — page-level refresh signal. Host owns the trigger (pull-to-
+  // refresh on mobile, refresh button, etc.); widgets opt in via
+  // useRefresh(handler). The three datastore hooks auto-subscribe; other
+  // widgets subscribe when they need to re-run non-datastore work. Optional
+  // so a host that does not implement refresh can simply omit it — the hook
+  // collapses to a no-op there.
+  refresh: {
+    description:
+      "Optional page-level refresh slot. { subscribe(handler) -> unsubscribe }. " +
+      "Handler is called on every page refresh tick (pull-to-refresh on " +
+      "mobile, manual refresh button); may return a Promise the host " +
+      "awaits before clearing the refresh indicator. Backs useRefresh().",
+    required: false,
+    fields: { subscribe: "function" },
+  },
   events: {
     description: "{ emit(name, payload) }.",
     required: true,
@@ -1582,7 +1617,17 @@ const CONTRACT = deepFreeze({
   //    manual key entry, and a `widget.<id>.<key>` override still wins per
   //    instance. No existing hook, primitive, manifest field, or token changed
   //    shape — minor bump on the pre-1.0 channel.
-  version: "1.28.0",
+  //
+  // 1.29.0: additive (sc-1179) — page-level refresh signal. New hook
+  //    `useRefresh(handler)` and new optional WidgetContext slice
+  //    `refresh: { subscribe(handler) -> unsubscribe }`. The web Player's
+  //    pull-to-refresh gesture and the native Expo export's `RefreshControl`
+  //    both call into the same manager so a refresh tick fans out to every
+  //    widget on the page; the three datastore hooks (useDatastoreQuery /
+  //    useDatastoreRecord / useAsset) auto-subscribe their own `refetch`.
+  //    No existing hook, primitive, manifest field, or token changed shape
+  //    — minor bump on the pre-1.0 channel.
+  version: "1.29.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -116,6 +116,26 @@ const HOOKS = [
     requiredContextSlice: ["renderer.renderNode"],
     scopes: null,
   },
+  {
+    name: "useRefresh",
+    signature: "useRefresh(handler)",
+    description:
+      "Subscribe to the page-level refresh tick (pull-to-refresh on " +
+      "mobile, manual refresh button, etc.). The handler is called every " +
+      "time the host triggers a refresh; it may return a Promise — the " +
+      "host waits on all settled handlers before clearing the refresh " +
+      "indicator. The three datastore hooks (useDatastoreQuery, " +
+      "useDatastoreRecord, useAsset) already subscribe automatically — " +
+      "widgets only call useRefresh directly when they need to re-run " +
+      "non-datastore work (a third-party fetch, a derived calculation). " +
+      "Safe to call on a host that does not implement refresh — it is a " +
+      "no-op there.",
+    returnShape: {
+      "(returns)": "void",
+    },
+    requiredContextSlice: ["refresh.subscribe"],
+    scopes: null,
+  },
   {
     name: "useNavigation",
     signature: "useNavigation()",
@@ -924,6 +944,21 @@ const WIDGET_CONTEXT_SHAPE = {
     required: true,
     fields: { renderNode: "function" },
   },
+  // sc-1179 — page-level refresh signal. Host owns the trigger (pull-to-
+  // refresh on mobile, refresh button, etc.); widgets opt in via
+  // useRefresh(handler). The three datastore hooks auto-subscribe; other
+  // widgets subscribe when they need to re-run non-datastore work. Optional
+  // so a host that does not implement refresh can simply omit it — the hook
+  // collapses to a no-op there.
+  refresh: {
+    description:
+      "Optional page-level refresh slot. { subscribe(handler) -> unsubscribe }. " +
+      "Handler is called on every page refresh tick (pull-to-refresh on " +
+      "mobile, manual refresh button); may return a Promise the host " +
+      "awaits before clearing the refresh indicator. Backs useRefresh().",
+    required: false,
+    fields: { subscribe: "function" },
+  },
   events: {
     description: "{ emit(name, payload) }.",
     required: true,
@@ -1582,7 +1617,17 @@ const CONTRACT = deepFreeze({
   //    manual key entry, and a `widget.<id>.<key>` override still wins per
   //    instance. No existing hook, primitive, manifest field, or token changed
   //    shape — minor bump on the pre-1.0 channel.
-  version: "1.28.0",
+  //
+  // 1.29.0: additive (sc-1179) — page-level refresh signal. New hook
+  //    `useRefresh(handler)` and new optional WidgetContext slice
+  //    `refresh: { subscribe(handler) -> unsubscribe }`. The web Player's
+  //    pull-to-refresh gesture and the native Expo export's `RefreshControl`
+  //    both call into the same manager so a refresh tick fans out to every
+  //    widget on the page; the three datastore hooks (useDatastoreQuery /
+  //    useDatastoreRecord / useAsset) auto-subscribe their own `refetch`.
+  //    No existing hook, primitive, manifest field, or token changed shape
+  //    — minor bump on the pre-1.0 channel.
+  version: "1.29.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/hooks.js

@@ -188,6 +188,49 @@ export function WidgetTree({ node }) {
   return ctx.renderer.renderNode(node);
 }
 
+/**
+ * sc-1179 — subscribe to the page-level refresh tick.
+ *
+ * Pull-to-refresh on mobile (web Player at touch widths + the native Expo
+ * export's `RefreshControl`) triggers a page-wide refresh. Widgets that
+ * need to re-run work on a refresh — re-fetch from a third-party API,
+ * recompute a derived value — pass a handler here:
+ *
+ *   useRefresh(async () => { await refetchMyThirdPartyData(); });
+ *
+ * The handler may return a Promise — the host waits on Promise.allSettled
+ * of every subscriber before clearing the refresh indicator. Handler
+ * identity does not need to be stable: the subscription captures it in a
+ * ref and reads the latest on every tick.
+ *
+ * `useDatastoreQuery` / `useDatastoreRecord` / `useAsset` already
+ * auto-subscribe their own `refetch`, so a widget built on the data hooks
+ * gets refreshed for free — call `useRefresh` directly only for
+ * non-datastore work.
+ *
+ * Safe to call on a host that does not implement refresh — the hook
+ * collapses to a no-op there.
+ */
+export function useRefresh(handler) {
+  const ctx = useWidgetContextOrThrow("useRefresh");
+  const handlerRef = useRef(handler);
+  handlerRef.current = handler;
+  const subscribe = ctx.refresh && ctx.refresh.subscribe;
+  const subscribeRef = useRef(subscribe);
+  subscribeRef.current = subscribe;
+  useEffect(() => {
+    const sub = subscribeRef.current;
+    if (typeof sub !== "function") return undefined;
+    const unsubscribe = sub(() => {
+      const fn = handlerRef.current;
+      if (typeof fn === "function") return fn();
+      return undefined;
+    });
+    return typeof unsubscribe === "function" ? unsubscribe : undefined;
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+}
+
 /**
  * Returns the host-provided navigation surface:
  *   `{ goTo, goBack, push, replace, back, currentRoute }`.
@@ -478,6 +521,10 @@ export function useDatastoreQuery(table, query) {
     await doFetch();
   }, [doFetch]);
 
+  // sc-1179 — auto-subscribe to the page-level refresh tick so a
+  // pull-to-refresh on mobile re-runs the query without per-widget code.
+  useRefresh(refetch);
+
   return { data, loading, error, refetch };
 }
 
@@ -556,6 +603,9 @@ export function useDatastoreRecord(table, recordId) {
     await doFetch();
   }, [doFetch]);
 
+  // sc-1179 — auto-subscribe to the page-level refresh tick.
+  useRefresh(refetch);
+
   return { data, loading, error, refetch };
 }
 
@@ -1137,6 +1187,9 @@ export function useAsset(assetId) {
     await doFetch();
   }, [doFetch]);
 
+  // sc-1179 — auto-subscribe to the page-level refresh tick.
+  useRefresh(refetch);
+
   const url =
     asset && typeof asset.url === "string" && asset.url.length > 0
       ? asset.url

package/dist/index.d.ts

@@ -812,6 +812,21 @@ export const Linking: {
   canOpenURL(url: string): Promise<boolean>;
 };
 
+/**
+ * sc-1179 — subscribe to the page-level refresh tick (pull-to-refresh on
+ * mobile, manual refresh button, etc.). The handler is called every time
+ * the host triggers a refresh; it may return a Promise — the host waits
+ * on all settled subscribers before clearing the refresh indicator.
+ *
+ * `useDatastoreQuery` / `useDatastoreRecord` / `useAsset` already
+ * auto-subscribe their own `refetch`, so widgets only call this directly
+ * to re-run non-datastore work. Safe to call on a host that does not
+ * implement refresh — collapses to a no-op there.
+ */
+export function useRefresh(
+  handler: () => void | Promise<unknown>,
+): void;
+
 /**
  * Error class thrown by useDatastoreMutation callbacks (and surfaced by
  * useDatastoreQuery in its `error` slot). The `code` is a stable

package/dist/index.js

@@ -37,6 +37,7 @@ export {
   useFill,
   useNavigation,
   useChildRenderer,
+  useRefresh,
   WidgetTree,
 } from "./hooks.js";
 // REQ-WSDK-PLATFORM §6 — Tier A hooks. Each ships in a per-platform file

package/dist/index.native.js

@@ -35,6 +35,7 @@ export {
   useFill,
   useNavigation,
   useChildRenderer,
+  useRefresh,
   WidgetTree,
 } from "./hooks.js";
 // REQ-WSDK-PLATFORM §6 — Tier A hooks (native variants).

package/package.json

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