@colixsystems/widget-sdk 0.16.0 → 0.17.0

package/README.md

@@ -6,7 +6,14 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.16.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.17.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.17.0
+
+REQ-WBLT-FORMBUILDER — a runtime schema resolver so widgets can render by column type.
+
+- **`useDatastoreSchema(tableId)` is wired** + the new `WidgetContext.datastore.schema` slice. Returns `{ schema, loading, error, refetch }` where `schema` is `{ id, name, columns: [{ id, name, dataType, required, relationType, targetTableId, isIdentification }] }` (`null` until loaded). It reads the **existing** ACL-gated `GET /api/v1/tables/:id` — structure only, never row data — so a public-grant table resolves for anonymous visitors exactly like a record read. Use it to resolve a stored `columnId` to its column name / dataType / relation target at runtime (the built-in Form Builder uses it to render an input per column type). Reads need the `datastore.read:<table>` scope. Backed by a new `datastore.schema(tableId)` host facade (web: `widgetHostDatastore`; native: `hostDatastore` in the export's `widgetHost.js`). Additive.
+- **`CONTRACT.version` → `1.7.0`** (additive: one new hook, one new `datastore.schema` context field). No existing export changed signature.
 
 ### What's new in 0.16.0
 
@@ -125,7 +132,7 @@ 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`, `useUsers`, `useGroups`, `useFile`, `useWidgetEvent`, `usePayments`, `useTheme`, `useI18n`, `useUser`, `useNavigation`, `useChildRenderer`, `useClipboard`, `useToast` — hooks that read from the host-provided `WidgetContext` (or, for `useClipboard`, the platform clipboard API directly). `useDirectory(query?)` returns `{ users, loading, error, refetch }` (each user `{ id, name, role }`) and requires the `directory.read:users` scope. `useUsers(query?)` returns `{ users, loading, error, refetch, invite, deactivate, reactivate, remove }` and requires `users.read:*` (mutations also need `users.write:*`); rejections are a `DirectoryError`. `useGroups(query?)` returns `{ groups, loading, error, refetch, create, remove, addMember, removeMember }` and requires `groups.read:*` (mutations also need `groups.write:*`). `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).
+- `useDatastoreQuery`, `useDatastoreRecord`, `useDatastoreSchema`, `useDatastoreMutation`, `useDirectory`, `useUsers`, `useGroups`, `useFile`, `useWidgetEvent`, `usePayments`, `useTheme`, `useI18n`, `useUser`, `useNavigation`, `useChildRenderer`, `useClipboard`, `useToast` — hooks that read from the host-provided `WidgetContext` (or, for `useClipboard`, the platform clipboard API directly). `useDirectory(query?)` returns `{ users, loading, error, refetch }` (each user `{ id, name, role }`) and requires the `directory.read:users` scope. `useUsers(query?)` returns `{ users, loading, error, refetch, invite, deactivate, reactivate, remove }` and requires `users.read:*` (mutations also need `users.write:*`); rejections are a `DirectoryError`. `useGroups(query?)` returns `{ groups, loading, error, refetch, create, remove, addMember, removeMember }` and requires `groups.read:*` (mutations also need `groups.write:*`). `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). `useDatastoreSchema(tableId)` returns `{ schema, loading, error, refetch }` where `schema` is `{ id, name, columns: [{ id, name, dataType, required, relationType, targetTableId, isIdentification }] }` (structure only, no row data) — use it to resolve a stored `columnId` to its column type at runtime; requires the `datastore.read:<table>` scope. `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`, `Linking`, `Icon`, `DateTimePicker` — re-exported from `react-native` (the RN primitives) or implemented in the SDK (`Icon` wraps `lucide-react-native`, `DateTimePicker` wraps `@react-native-community/datetimepicker`). 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. `Linking` is a static API (`Linking.openURL(url)`) — use it for external URLs, and use `useNavigation().goTo(pageId)` for internal page navigation. 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

@@ -130,6 +130,28 @@ const HOOKS = [
     requiredContextSlice: ["datastore.records"],
     scopes: ["datastore.read:*"],
   },
+  {
+    name: "useDatastoreSchema",
+    signature: "useDatastoreSchema(tableId)",
+    description:
+      "Reads a table's structural schema — its columns and their types — so a " +
+      "widget can resolve a stored columnId to the column's name / dataType / " +
+      "relation target at runtime (e.g. a form that renders inputs by column " +
+      "type). Returns { schema, loading, error, refetch } where schema is " +
+      "{ id, name, columns: [{ id, name, dataType, required, relationType, " +
+      "targetTableId, isIdentification }] } (null until loaded). Reads only the " +
+      "structure, never row data; gated by the same datastore.read ACL as " +
+      "record reads, so a public-grant table resolves for anonymous visitors.",
+    returnShape: {
+      schema:
+        "{ id, name, columns: [{ id, name, dataType, required, relationType, targetTableId, isIdentification }] } | null",
+      loading: "boolean",
+      error: "DatastoreError | null",
+      refetch: "() => Promise<void>",
+    },
+    requiredContextSlice: ["datastore.schema"],
+    scopes: ["datastore.read:<table>"],
+  },
   {
     name: "useDatastoreMutation",
     signature: "useDatastoreMutation(tableId)",
@@ -524,9 +546,9 @@ const WIDGET_CONTEXT_SHAPE = {
   },
   datastore: {
     description:
-      "{ records(table) -> { list(query?), get(id), create(values), update(id, values), delete(id) } }.",
+      "{ records(table) -> { list(query?), get(id), create(values), update(id, values), delete(id) }, schema(table) -> Promise<{ id, name, columns: [...] }> }. `records` backs the query/record/mutation hooks; `schema` backs useDatastoreSchema() and resolves a table's column structure (no row data).",
     required: true,
-    fields: { records: "function" },
+    fields: { records: "function", schema: "function" },
   },
   directory: {
     description:
@@ -837,7 +859,13 @@ const CONTRACT = deepFreeze({
   // so the tenant's Theme Settings "Secondary Color" flows through
   // `useTheme().colors.secondary` (Button secondary variant + any widget
   // that wants the brand's second accent).
-  version: "1.6.0",
+  //
+  // 1.7.0: additive — new `useDatastoreSchema(tableId)` hook + the
+  // `datastore.schema` host-context slice it reads. Lets a widget resolve a
+  // stored columnId to its column name / dataType / relation target at
+  // runtime (Form Builder renders inputs by column type). Reads the existing
+  // ACL-gated `GET /tables/:id` — structure only, no row data.
+  version: "1.7.0",
   hooks: HOOKS,
   primitives: PRIMITIVES,
   manifestSchema: MANIFEST_SCHEMA,

package/dist/contract.js

@@ -130,6 +130,28 @@ const HOOKS = [
     requiredContextSlice: ["datastore.records"],
     scopes: ["datastore.read:*"],
   },
+  {
+    name: "useDatastoreSchema",
+    signature: "useDatastoreSchema(tableId)",
+    description:
+      "Reads a table's structural schema — its columns and their types — so a " +
+      "widget can resolve a stored columnId to the column's name / dataType / " +
+      "relation target at runtime (e.g. a form that renders inputs by column " +
+      "type). Returns { schema, loading, error, refetch } where schema is " +
+      "{ id, name, columns: [{ id, name, dataType, required, relationType, " +
+      "targetTableId, isIdentification }] } (null until loaded). Reads only the " +
+      "structure, never row data; gated by the same datastore.read ACL as " +
+      "record reads, so a public-grant table resolves for anonymous visitors.",
+    returnShape: {
+      schema:
+        "{ id, name, columns: [{ id, name, dataType, required, relationType, targetTableId, isIdentification }] } | null",
+      loading: "boolean",
+      error: "DatastoreError | null",
+      refetch: "() => Promise<void>",
+    },
+    requiredContextSlice: ["datastore.schema"],
+    scopes: ["datastore.read:<table>"],
+  },
   {
     name: "useDatastoreMutation",
     signature: "useDatastoreMutation(tableId)",
@@ -518,9 +540,9 @@ const WIDGET_CONTEXT_SHAPE = {
   },
   datastore: {
     description:
-      "{ records(table) -> { list(query?), get(id), create(values), update(id, values), delete(id) } }.",
+      "{ records(table) -> { list(query?), get(id), create(values), update(id, values), delete(id) }, schema(table) -> Promise<{ id, name, columns: [...] }> }. `records` backs the query/record/mutation hooks; `schema` backs useDatastoreSchema() and resolves a table's column structure (no row data).",
     required: true,
-    fields: { records: "function" },
+    fields: { records: "function", schema: "function" },
   },
   directory: {
     description:
@@ -788,7 +810,10 @@ function deepFreeze(value) {
 }
 
 const CONTRACT = deepFreeze({
-  version: "1.6.0",
+  // 1.7.0: additive — new useDatastoreSchema(tableId) hook + the
+  // datastore.schema host-context slice it reads (resolves a table's column
+  // structure at runtime via the existing ACL-gated GET /tables/:id).
+  version: "1.7.0",
   hooks: HOOKS,
   primitives: PRIMITIVES,
   manifestSchema: MANIFEST_SCHEMA,

package/dist/hooks.js

@@ -297,6 +297,81 @@ export function useDatastoreRecord(table, recordId) {
   return { data, loading, error, refetch };
 }
 
+/**
+ * Stateful table-schema resolver hook. Returns { schema, loading, error,
+ * refetch } where `schema` is `{ id, name, columns: [{ id, name, dataType,
+ * required, relationType, targetTableId, isIdentification }] }` (`null` until
+ * loaded).
+ *
+ * The host's datastore client exposes `schema(table)` which resolves to the
+ * table's structural metadata — columns and their types, NOT row data. Use it
+ * to resolve a stored `columnId` to its column name / dataType / relation
+ * target at runtime (e.g. a form that renders an input per column type). It
+ * reads the existing ACL-gated `GET /tables/:id`, so a public-grant table
+ * resolves for anonymous visitors exactly like a record read.
+ *
+ * When `tableId` is falsy (the author hasn't bound a `tableRef` yet) the hook
+ * collapses to { schema: null, loading: false, error: null, refetch } without
+ * a network round-trip. A 404 (table absent / not readable / cross-tenant)
+ * surfaces as a DatastoreError with `code: "NOT_FOUND"`.
+ */
+export function useDatastoreSchema(tableId) {
+  const ctx = useWidgetContextOrThrow("useDatastoreSchema");
+  if (!ctx.datastore || typeof ctx.datastore.schema !== "function") {
+    throw new Error(
+      "useDatastoreSchema: host did not inject a datastore schema client",
+    );
+  }
+  const ready = Boolean(tableId);
+  const [schema, setSchema] = useState(null);
+  const [loading, setLoading] = useState(ready);
+  const [error, setError] = useState(null);
+
+  // Same ref discipline as useDatastoreRecord — `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 tableIdRef = useRef(tableId);
+  const schemaFnRef = useRef(ctx.datastore.schema);
+  tableIdRef.current = tableId;
+  schemaFnRef.current = ctx.datastore.schema;
+
+  const runRef = useRef(0);
+
+  const doFetch = useCallback(async () => {
+    const myRun = ++runRef.current;
+    const t = tableIdRef.current;
+    if (!t) {
+      setLoading(false);
+      setError(null);
+      setSchema(null);
+      return;
+    }
+    setLoading(true);
+    setError(null);
+    try {
+      const result = await schemaFnRef.current(t);
+      if (runRef.current !== myRun) return;
+      setSchema(result || 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
+  }, [tableId]);
+
+  const refetch = useCallback(async () => {
+    await doFetch();
+  }, [doFetch]);
+
+  return { schema, loading, error, refetch };
+}
+
 /**
  * Stateful file-asset resolver hook. Returns { url, file, loading, error,
  * refetch }.

package/dist/index.d.ts

@@ -383,6 +383,59 @@ export function useDatastoreRecord(
   refetch(): Promise<void>;
 };
 
+/**
+ * One column in a table's schema, as returned by `useDatastoreSchema`.
+ * Structural metadata only — never row data.
+ */
+export interface DatastoreSchemaColumn {
+  id: string;
+  name: string;
+  dataType:
+    | "STRING"
+    | "TEXT"
+    | "NUMBER"
+    | "FLOAT"
+    | "BOOL"
+    | "DATE"
+    | "FILE"
+    | "STRING_ARRAY"
+    | "INT_ARRAY"
+    | "RELATION"
+    | "USER"
+    | "USER_GROUP";
+  required: boolean;
+  /** For RELATION columns only. */
+  relationType?: "ONE_TO_ONE" | "ONE_TO_MANY" | "MANY_TO_MANY" | null;
+  /** For RELATION columns only — the id of the table this column points at. */
+  targetTableId?: string | null;
+  /** True when this column is the table's display/identification column. */
+  isIdentification?: boolean;
+}
+
+export interface DatastoreSchema {
+  id: string;
+  name: string;
+  columns: DatastoreSchemaColumn[];
+}
+
+export interface SchemaResult {
+  schema: DatastoreSchema | null;
+  loading: boolean;
+  error: DatastoreError | null;
+  refetch(): Promise<void>;
+}
+
+/**
+ * Stateful table-schema resolver hook. Returns `{ schema, loading, error,
+ * refetch }` where `schema` is the bound table's column structure (`null`
+ * until loaded). Reads the existing ACL-gated `GET /tables/:id` — structure
+ * only, no row data. Use it to resolve a stored `columnId` to its column
+ * name / dataType / relation target at runtime.
+ */
+export function useDatastoreSchema(
+  tableId: string | null | undefined,
+): SchemaResult;
+
 /**
  * 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

@@ -12,6 +12,7 @@ export {
   DirectoryError,
   useDatastoreQuery,
   useDatastoreRecord,
+  useDatastoreSchema,
   useFile,
   useDatastoreMutation,
   useDirectory,

package/dist/index.native.js

@@ -12,6 +12,7 @@ export {
   DirectoryError,
   useDatastoreQuery,
   useDatastoreRecord,
+  useDatastoreSchema,
   useFile,
   useDatastoreMutation,
   useDirectory,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.16.0",
+  "version": "0.17.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__/linter-users-scope.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__/linter-users-scope.test.js"
   },
   "engines": {
     "node": ">=18"