@colixsystems/widget-sdk 0.12.0 → 0.13.0

package/README.md

@@ -6,7 +6,11 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.12.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
 
@@ -85,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`, `useDatastoreRecord`, `useDatastoreMutation`, `useDirectory`, `useFile`, `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)`). `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.
+- `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()",
@@ -407,6 +416,12 @@ const WIDGET_CONTEXT_SHAPE = {
     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()",
@@ -401,6 +410,12 @@ const WIDGET_CONTEXT_SHAPE = {
     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

@@ -517,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

@@ -382,6 +382,22 @@ export function useDatastoreRecord(
  * 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: {

package/dist/index.js

@@ -20,6 +20,8 @@ export {
   useI18n,
   useUser,
   useNavigation,
+  useChildRenderer,
+  WidgetTree,
 } from "./hooks.js";
 export {
   Text,

package/dist/index.native.js

@@ -20,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.12.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",