@colixsystems/widget-sdk 0.11.0 → 0.13.0

package/README.md

@@ -6,7 +6,16 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.11.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.13.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.13.0
+
+- **`WidgetTree` component + `useChildRenderer()` hook** wired. Container widgets (Tabs, Card, …) can now render arbitrary author-authored child page-tree nodes through the SDK without importing the host renderer. The host pre-binds the surrounding render context (breakpoint, page ctx, parent) into a closure on `ctx.renderer.renderNode(node)` — the widget just passes the child node. Additive.
+
+### What's new in 0.12.0
+
+- **`useDatastoreRecord(tableId, recordId)` is wired.** Returns `{ data, loading, error, refetch }` for a single record fetched through the host's `records(table).get(id)`. Sister to `useDatastoreQuery`; mirrors its ref discipline so `refetch` stays a stable callback identity. A 404 surfaces as `DatastoreError.code === "NOT_FOUND"`. Additive.
+- **`useFile(fileId)` is wired** + new `WidgetContext.files` slice. Returns `{ url, file, loading, error, refetch }` — the `url` is an absolute URL the widget can drop straight into `<Image source>`. Backed by a new `files.get(fileId)` host facade (web: `widgetHostFiles` through `api/client`; native: `hostFiles` in the export's `widgetHost.js`). Additive.
 
 ### What's new in 0.11.0
 
@@ -80,7 +89,8 @@ import { defineWidget, validateManifest, useDatastoreQuery, Text, View } from "@
 
 - `defineWidget({ manifest, component })` — validates the manifest and produces a widget module the host can register.
 - `validateManifest(m)` / `validatePropertySchema(s)` / `validateProps(schema, props)` — shape validation; no third-party deps.
-- `useDatastoreQuery`, `useDatastoreMutation`, `useDirectory`, `useWidgetEvent`, `usePayments`, `useTheme`, `useI18n`, `useUser`, `useNavigation` — hooks that read from the host-provided `WidgetContext`. `useDirectory(query?)` returns `{ users, loading, error, refetch }` (each user `{ id, name, role }`) and requires the `directory.read:users` scope. `usePayments()` returns `{ requestPayment, getPayment }` and requires the `payments.charge:appUser` scope; `requestPayment(...)` rejects with a `PaymentError`. `useUser()` returns the active end-user identity `{ id, email, displayName, roles, groupIds }` (`id` is `null` for anonymous / preview). `useNavigation()` returns `{ goTo, goBack, push, replace, back, currentRoute }` for internal page navigation — for external URLs use the `Linking` primitive (`Linking.openURL(url)`).
+- `useDatastoreQuery`, `useDatastoreRecord`, `useDatastoreMutation`, `useDirectory`, `useFile`, `useWidgetEvent`, `usePayments`, `useTheme`, `useI18n`, `useUser`, `useNavigation`, `useChildRenderer` — hooks that read from the host-provided `WidgetContext`. `useDirectory(query?)` returns `{ users, loading, error, refetch }` (each user `{ id, name, role }`) and requires the `directory.read:users` scope. `usePayments()` returns `{ requestPayment, getPayment }` and requires the `payments.charge:appUser` scope; `requestPayment(...)` rejects with a `PaymentError`. `useUser()` returns the active end-user identity `{ id, email, displayName, roles, groupIds }` (`id` is `null` for anonymous / preview). `useNavigation()` returns `{ goTo, goBack, push, replace, back, currentRoute }` for internal page navigation — for external URLs use the `Linking` primitive (`Linking.openURL(url)`). `useDatastoreRecord(tableId, recordId)` returns `{ data, loading, error, refetch }` for a single record (data is one row or null). `useFile(fileId)` returns `{ url, file, loading, error, refetch }` — the `url` is an absolute URL composed against the host's API base. `useChildRenderer()` returns `{ renderNode(node) }` — container widgets call it to render arbitrary child page-tree nodes (prefer the `WidgetTree` component for the common case).
+- `WidgetTree({ node })` — component that renders an author-authored child node through the host's renderer; used by Tabs / Card / custom containers to host arbitrary child widgets.
 - `Text`, `View`, `Pressable`, `Image`, `ScrollView`, `TextInput`, `FlatList`, `SectionList`, `ActivityIndicator`, `Switch`, `StyleSheet` — re-exported from `react-native`. The web build aliases `react-native` to `react-native-web` so widgets render in the browser without any per-platform code; the exported Expo app's Metro bundler resolves the real `react-native` library. See https://reactnative.dev/docs/ for per-component props.
 - `WidgetContextProvider` — React context provider that the host (Studio, Player, exported app) wraps widgets with.
 

package/dist/contract.cjs

@@ -68,6 +68,15 @@ const HOOKS = [
     requiredContextSlice: ["user"],
     scopes: null,
   },
+  {
+    name: "useChildRenderer",
+    signature: "useChildRenderer()",
+    returnShape: {
+      renderNode: "(node) => ReactElement",
+    },
+    requiredContextSlice: ["renderer.renderNode"],
+    scopes: null,
+  },
   {
     name: "useNavigation",
     signature: "useNavigation()",
@@ -82,6 +91,31 @@ const HOOKS = [
     requiredContextSlice: ["navigation"],
     scopes: null,
   },
+  {
+    name: "useDatastoreRecord",
+    signature: "useDatastoreRecord(tableId, recordId)",
+    returnShape: {
+      data: "Record | null",
+      loading: "boolean",
+      error: "DatastoreError | null",
+      refetch: "() => Promise<void>",
+    },
+    requiredContextSlice: ["datastore.records"],
+    scopes: ["datastore.read:<table>"],
+  },
+  {
+    name: "useFile",
+    signature: "useFile(fileId)",
+    returnShape: {
+      url: "string | null",
+      file: "{ id, url, storedFilename, mimeType, sizeBytes, ... } | null",
+      loading: "boolean",
+      error: "DatastoreError | null",
+      refetch: "() => Promise<void>",
+    },
+    requiredContextSlice: ["files.get"],
+    scopes: null,
+  },
   {
     name: "useDatastoreQuery",
     signature: "useDatastoreQuery(tableId, options?)",
@@ -376,6 +410,18 @@ const WIDGET_CONTEXT_SHAPE = {
     required: true,
     fields: { listUsers: "function" },
   },
+  files: {
+    description:
+      "Read-only asset resolver. { get(fileId) -> Promise<{ id, url, storedFilename, mimeType, sizeBytes, ... }> }. Backs useFile(); resolves an asset id to an absolute URL the widget can drop into an <Image source>. The url field is always an absolute URL composed against the host's API base.",
+    required: true,
+    fields: { get: "function" },
+  },
+  renderer: {
+    description:
+      "Host child-node renderer. { renderNode(node) -> ReactElement }. Backs WidgetTree / useChildRenderer; lets a container widget (Tabs, Card, …) render arbitrary author-authored child nodes without importing the host renderer. The closure pre-binds breakpoint + page ctx + parent so the widget passes only the child node.",
+    required: true,
+    fields: { renderNode: "function" },
+  },
   events: {
     description: "{ emit(name, payload) }.",
     required: true,

package/dist/contract.js

@@ -68,6 +68,15 @@ const HOOKS = [
     requiredContextSlice: ["user"],
     scopes: null,
   },
+  {
+    name: "useChildRenderer",
+    signature: "useChildRenderer()",
+    returnShape: {
+      renderNode: "(node) => ReactElement",
+    },
+    requiredContextSlice: ["renderer.renderNode"],
+    scopes: null,
+  },
   {
     name: "useNavigation",
     signature: "useNavigation()",
@@ -82,6 +91,31 @@ const HOOKS = [
     requiredContextSlice: ["navigation"],
     scopes: null,
   },
+  {
+    name: "useDatastoreRecord",
+    signature: "useDatastoreRecord(tableId, recordId)",
+    returnShape: {
+      data: "Record | null",
+      loading: "boolean",
+      error: "DatastoreError | null",
+      refetch: "() => Promise<void>",
+    },
+    requiredContextSlice: ["datastore.records"],
+    scopes: ["datastore.read:<table>"],
+  },
+  {
+    name: "useFile",
+    signature: "useFile(fileId)",
+    returnShape: {
+      url: "string | null",
+      file: "{ id, url, storedFilename, mimeType, sizeBytes, ... } | null",
+      loading: "boolean",
+      error: "DatastoreError | null",
+      refetch: "() => Promise<void>",
+    },
+    requiredContextSlice: ["files.get"],
+    scopes: null,
+  },
   {
     name: "useDatastoreQuery",
     signature: "useDatastoreQuery(tableId, options?)",
@@ -370,6 +404,18 @@ const WIDGET_CONTEXT_SHAPE = {
     required: true,
     fields: { listUsers: "function" },
   },
+  files: {
+    description:
+      "Read-only asset resolver. { get(fileId) -> Promise<{ id, url, storedFilename, mimeType, sizeBytes, ... }> }. Backs useFile(); resolves an asset id to an absolute URL the widget can drop into an <Image source>. The url field is always an absolute URL composed against the host's API base.",
+    required: true,
+    fields: { get: "function" },
+  },
+  renderer: {
+    description:
+      "Host child-node renderer. { renderNode(node) -> ReactElement }. Backs WidgetTree / useChildRenderer; lets a container widget (Tabs, Card, …) render arbitrary author-authored child nodes without importing the host renderer. The closure pre-binds breakpoint + page ctx + parent so the widget passes only the child node.",
+    required: true,
+    fields: { renderNode: "function" },
+  },
   events: {
     description: "{ emit(name, payload) }.",
     required: true,

package/dist/hooks.js

@@ -219,6 +219,153 @@ export function useDatastoreQuery(table, query) {
   return { data, loading, error, refetch };
 }
 
+/**
+ * Stateful single-record query hook. Returns { data, loading, error, refetch }
+ * where `data` is one row (`null` until loaded, never an array).
+ *
+ * The host's datastore client exposes `records(table).get(id)` which
+ * resolves to a single record object. We hold the result in component
+ * state and re-fetch when [table, id] changes. `refetch` re-runs the
+ * call on demand.
+ *
+ * When `table` OR `recordId` is falsy (e.g. the author hasn't bound the
+ * record id yet), the hook resolves to { data: null, loading: false,
+ * error: null, refetch } so the widget can render its empty state
+ * without throwing. A 404 surfaces as a DatastoreError with
+ * `code: "NOT_FOUND"`.
+ */
+export function useDatastoreRecord(table, recordId) {
+  const ctx = useWidgetContextOrThrow("useDatastoreRecord");
+  if (!ctx.datastore || typeof ctx.datastore.records !== "function") {
+    throw new Error(
+      "useDatastoreRecord: host did not inject a datastore client",
+    );
+  }
+  const ready = Boolean(table && recordId);
+  const [data, setData] = useState(null);
+  const [loading, setLoading] = useState(ready);
+  const [error, setError] = useState(null);
+
+  // Same ref discipline as useDatastoreQuery — `ctx` is a fresh object
+  // identity on every host render, so we hold the live inputs in refs
+  // to keep `refetch` a stable callback.
+  const tableRef = useRef(table);
+  const recordIdRef = useRef(recordId);
+  const recordsRef = useRef(ctx.datastore.records);
+  tableRef.current = table;
+  recordIdRef.current = recordId;
+  recordsRef.current = ctx.datastore.records;
+
+  const runRef = useRef(0);
+
+  const doFetch = useCallback(async () => {
+    const myRun = ++runRef.current;
+    const t = tableRef.current;
+    const id = recordIdRef.current;
+    if (!t || !id) {
+      setLoading(false);
+      setError(null);
+      setData(null);
+      return;
+    }
+    setLoading(true);
+    setError(null);
+    try {
+      const ns = recordsRef.current(t);
+      const row = await ns.get(id);
+      if (runRef.current !== myRun) return;
+      setData(row || null);
+      setLoading(false);
+    } catch (err) {
+      if (runRef.current !== myRun) return;
+      setError(toDatastoreError(err));
+      setLoading(false);
+    }
+  }, []);
+
+  useEffect(() => {
+    doFetch();
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [table, recordId]);
+
+  const refetch = useCallback(async () => {
+    await doFetch();
+  }, [doFetch]);
+
+  return { data, loading, error, refetch };
+}
+
+/**
+ * Stateful file-asset resolver hook. Returns { url, file, loading, error,
+ * refetch }.
+ *
+ * The host's file client exposes `files.get(fileId)` which resolves to
+ * `{ url, ...meta }` — the absolute URL is composed against the host's
+ * API base so the widget can drop it straight into an `<Image source>`
+ * without knowing where the API lives. A missing/soft-deleted asset
+ * surfaces as `{ url: null, error: <DatastoreError NOT_FOUND> }`.
+ *
+ * When `fileId` is falsy the hook collapses to { url: null, file: null,
+ * loading: false, error: null, refetch } without a network round-trip,
+ * so a widget rendering before the author has bound an asset stays
+ * loop-free.
+ */
+export function useFile(fileId) {
+  const ctx = useWidgetContextOrThrow("useFile");
+  if (!ctx.files || typeof ctx.files.get !== "function") {
+    throw new Error("useFile: host did not inject a files client");
+  }
+  const ready = Boolean(fileId);
+  const [file, setFile] = useState(null);
+  const [loading, setLoading] = useState(ready);
+  const [error, setError] = useState(null);
+
+  const fileIdRef = useRef(fileId);
+  const getRef = useRef(ctx.files.get);
+  fileIdRef.current = fileId;
+  getRef.current = ctx.files.get;
+
+  const runRef = useRef(0);
+
+  const doFetch = useCallback(async () => {
+    const myRun = ++runRef.current;
+    const id = fileIdRef.current;
+    if (!id) {
+      setLoading(false);
+      setError(null);
+      setFile(null);
+      return;
+    }
+    setLoading(true);
+    setError(null);
+    try {
+      const f = await getRef.current(id);
+      if (runRef.current !== myRun) return;
+      setFile(f || null);
+      setLoading(false);
+    } catch (err) {
+      if (runRef.current !== myRun) return;
+      setError(toDatastoreError(err));
+      setLoading(false);
+    }
+  }, []);
+
+  useEffect(() => {
+    doFetch();
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [fileId]);
+
+  const refetch = useCallback(async () => {
+    await doFetch();
+  }, [doFetch]);
+
+  const url =
+    file && typeof file.url === "string" && file.url.length > 0
+      ? file.url
+      : null;
+  return { url, file, loading, error, refetch };
+}
+
 /**
  * Datastore mutation hook. Returns { create, update, delete }, each method
  * returning a Promise. Rejected promises throw a DatastoreError carrying a
@@ -370,6 +517,46 @@ export function useUser() {
   return ctx.user;
 }
 
+/**
+ * Returns the host's child-node renderer:
+ *   { renderNode(node) }.
+ *
+ * Widgets like Tabs / Card / a custom container call `renderNode(child)`
+ * to render an author-authored page-tree node nested inside themselves.
+ * The renderer closes over the surrounding render context (breakpoint,
+ * page ctx, parent) that the host already knows, so the widget doesn't
+ * need to plumb any of that through.
+ *
+ * Prefer the `WidgetTree` component for the common case
+ * (`<WidgetTree node={child} />`); reach for the hook when you need to
+ * branch on the node's shape before rendering.
+ */
+export function useChildRenderer() {
+  const ctx = useWidgetContextOrThrow("useChildRenderer");
+  if (!ctx.renderer || typeof ctx.renderer.renderNode !== "function") {
+    throw new Error(
+      "useChildRenderer: host did not inject a child-node renderer",
+    );
+  }
+  return ctx.renderer;
+}
+
+/**
+ * Renders an author-authored page-tree node through the host's child
+ * renderer. The widget hands off a node (or null) and gets back a React
+ * element rendered with the same dispatch the top-level page uses, so
+ * Tabs / Card / custom container widgets can host arbitrary child
+ * widgets without importing the host.
+ */
+export function WidgetTree({ node }) {
+  const ctx = useWidgetContextOrThrow("WidgetTree");
+  if (!ctx.renderer || typeof ctx.renderer.renderNode !== "function") {
+    return null;
+  }
+  if (!node) return null;
+  return ctx.renderer.renderNode(node);
+}
+
 /**
  * Returns the host-provided navigation surface:
  *   `{ goTo, goBack, push, replace, back, currentRoute }`.

package/dist/index.d.ts

@@ -363,6 +363,56 @@ export function usePayments(): PaymentsApi;
 
 export function useTheme(): ThemeTokens;
 
+/**
+ * Stateful single-record fetch hook. Returns `{ data, loading, error,
+ * refetch }`. `data` is one row or `null` (never an array).
+ */
+export function useDatastoreRecord(
+  tableId: string | null | undefined,
+  recordId: string | null | undefined,
+): {
+  data: unknown | null;
+  loading: boolean;
+  error: DatastoreError | null;
+  refetch(): Promise<void>;
+};
+
+/**
+ * Stateful file-asset resolver hook. Returns `{ url, file, loading, error,
+ * refetch }`. The `url` is an absolute URL composed against the host's API
+ * base; safe to pass straight to `<Image source>`.
+ */
+/**
+ * The host's child-node renderer surface. `renderNode(node)` returns a
+ * React element rendered with the same dispatch the top-level page uses;
+ * the closure pre-binds breakpoint / page ctx / parent.
+ */
+export function useChildRenderer(): {
+  renderNode(node: unknown): unknown;
+};
+
+/**
+ * Renders an author-authored page-tree node through the host's child
+ * renderer. Prefer this over `useChildRenderer()` for the common case
+ * (`<WidgetTree node={child} />`).
+ */
+export const WidgetTree: (props: { node: unknown }) => unknown;
+
+export function useFile(fileId: string | null | undefined): {
+  url: string | null;
+  file: {
+    id: string;
+    url: string;
+    storedFilename?: string;
+    mimeType?: string;
+    sizeBytes?: number;
+    [k: string]: unknown;
+  } | null;
+  loading: boolean;
+  error: DatastoreError | null;
+  refetch(): Promise<void>;
+};
+
 export function useI18n(): {
   locale: string;
   t(key: string, fallback?: string): string;

package/dist/index.js

@@ -10,6 +10,8 @@ export {
   DatastoreError,
   PaymentError,
   useDatastoreQuery,
+  useDatastoreRecord,
+  useFile,
   useDatastoreMutation,
   useDirectory,
   useWidgetEvent,
@@ -18,6 +20,8 @@ export {
   useI18n,
   useUser,
   useNavigation,
+  useChildRenderer,
+  WidgetTree,
 } from "./hooks.js";
 export {
   Text,

package/dist/index.native.js

@@ -10,6 +10,8 @@ export {
   DatastoreError,
   PaymentError,
   useDatastoreQuery,
+  useDatastoreRecord,
+  useFile,
   useDatastoreMutation,
   useDirectory,
   useWidgetEvent,
@@ -18,6 +20,8 @@ export {
   useI18n,
   useUser,
   useNavigation,
+  useChildRenderer,
+  WidgetTree,
 } from "./hooks.js";
 export {
   Text,

package/package.json

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