@colixsystems/widget-sdk 0.7.0 → 0.8.0

package/README.md

@@ -6,9 +6,14 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.7.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.8.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.7.0
+### What's new in 0.8.0
+
+- **`useDirectory()` — read-only user directory hook (REQ-DIR-01).** Returns `{ users, loading, error, refetch }` where each user is `{ id, name, role }`. Backed by a new `WidgetContext.directory.listUsers(query)` slice and gated by the new `directory.read:users` scope. Use it to build a chat people-list, an @-mention picker, or to resolve an author id to a display name. The host reads `GET /api/v1/app/users`, which hands non-Studio (Player) callers the reduced `{ id, name, role }` projection — email and other admin-only fields never leave the server for an app end-user. `query` is an optional `{ q, role, isActive, limit, offset }` (`q` substring-matches the display name; `role` is `"USER"` (default), `"INTEGRATION"`, or `"ALL"`). Mutating users is not part of the widget surface — the directory is read-only.
+- **`CONTRACT.version` → `1.1.0`** (additive: one new hook, one new context slice, one new scope). No existing export changed signature.
+
+### What was in 0.7.0
 
 - **`datastoreTemplate` is now part of the public manifest contract.** `CONTRACT.manifestSchema` carries an optional `datastoreTemplate` entry alongside the existing fields. The TypeScript `WidgetManifest` already declared this since 0.3.0, but the runtime contract did not — the agent's system prompt only generated the field set advertised by `CONTRACT.manifestSchema`, which silently omitted `datastoreTemplate` from every AI-generated draft. The mismatch meant most AI-generated DATA widgets shipped without a seeded table, forcing the end-user to hand-build it before the widget would render anything useful. With the schema entry in place, the agent now defaults to including a `datastoreTemplate` whenever the widget reads or writes data, matching the no-code experience the platform promises.
 - **Agent system prompt** ([backend/src/core/services/ai-widget-agent.service.js](../../backend/src/core/services/ai-widget-agent.service.js)) gains a dedicated `===== DATASTORE TEMPLATE =====` section, an updated DATA-widget example with a template, and a CONVERSATION BEHAVIOUR rule pinning the default. The note-list example (TextInput + create + update + delete) now shows the matching template too, including the column-name-match rule (`record.Body` ↔ `"name": "Body"`).
@@ -61,7 +66,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`, `useDatastoreMutation`, `useWidgetEvent`, `useTheme`, `useI18n` — hooks that read from the host-provided `WidgetContext`.
+- `useDatastoreQuery`, `useDatastoreMutation`, `useDirectory`, `useWidgetEvent`, `useTheme`, `useI18n` — 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.
 - `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

@@ -78,6 +78,18 @@ const HOOKS = [
     requiredContextSlice: ["datastore.records"],
     scopes: ["datastore.write:*"],
   },
+  {
+    name: "useDirectory",
+    signature: "useDirectory(query?)",
+    returnShape: {
+      users: "Array<{ id, name, role }>",
+      loading: "boolean",
+      error: "DatastoreError | null",
+      refetch: "() => Promise<void>",
+    },
+    requiredContextSlice: ["directory.listUsers"],
+    scopes: ["directory.read:users"],
+  },
   {
     name: "useWidgetEvent",
     signature: "useWidgetEvent(eventName)",
@@ -312,6 +324,12 @@ const WIDGET_CONTEXT_SHAPE = {
     required: true,
     fields: { records: "function" },
   },
+  directory: {
+    description:
+      "Read-only user directory. { listUsers(query?) -> Promise<Array<{ id, name, role }>> }. Backs useDirectory(); for chat people-lists / @-mention pickers / author-id resolution. Requires the directory.read:users scope.",
+    required: true,
+    fields: { listUsers: "function" },
+  },
   events: {
     description: "{ emit(name, payload) }.",
     required: true,
@@ -409,7 +427,7 @@ function deepFreeze(value) {
 }
 
 const CONTRACT = deepFreeze({
-  version: "1.0.0",
+  version: "1.1.0",
   hooks: HOOKS,
   primitives: PRIMITIVES,
   manifestSchema: MANIFEST_SCHEMA,

package/dist/contract.js

@@ -79,6 +79,18 @@ const HOOKS = [
     requiredContextSlice: ["datastore.records"],
     scopes: ["datastore.write:*"],
   },
+  {
+    name: "useDirectory",
+    signature: "useDirectory(query?)",
+    returnShape: {
+      users: "Array<{ id, name, role }>",
+      loading: "boolean",
+      error: "DatastoreError | null",
+      refetch: "() => Promise<void>",
+    },
+    requiredContextSlice: ["directory.listUsers"],
+    scopes: ["directory.read:users"],
+  },
   {
     name: "useWidgetEvent",
     signature: "useWidgetEvent(eventName)",
@@ -306,6 +318,12 @@ const WIDGET_CONTEXT_SHAPE = {
     required: true,
     fields: { records: "function" },
   },
+  directory: {
+    description:
+      "Read-only user directory. { listUsers(query?) -> Promise<Array<{ id, name, role }>> }. Backs useDirectory(); for chat people-lists / @-mention pickers / author-id resolution. Requires the directory.read:users scope.",
+    required: true,
+    fields: { listUsers: "function" },
+  },
   events: {
     description: "{ emit(name, payload) }.",
     required: true,
@@ -401,7 +419,7 @@ function deepFreeze(value) {
 }
 
 const CONTRACT = deepFreeze({
-  version: "1.0.0",
+  version: "1.1.0",
   hooks: HOOKS,
   primitives: PRIMITIVES,
   manifestSchema: MANIFEST_SCHEMA,

package/dist/hooks.js

@@ -258,6 +258,80 @@ export function useDatastoreMutation(table) {
   };
 }
 
+/**
+ * Stateful user-directory query hook. Returns { users, loading, error,
+ * refetch }.
+ *
+ * The host's directory client exposes `listUsers(query)` which resolves
+ * to an array of `{ id, name, role }` rows — the privacy-reduced
+ * directory projection the backend hands to non-Studio (Player) callers.
+ * Use it to build a chat people-list, an @-mention picker, or to resolve
+ * an author id to a display name. Mutating users is NOT part of this
+ * surface; the directory is read-only from a widget.
+ *
+ * `query` is an optional `{ q?, role?, isActive?, limit?, offset? }`
+ * object. `q` substring-matches the display name; `role` is `"USER"`
+ * (default) or `"INTEGRATION"` or `"ALL"`. The hook re-fetches whenever
+ * `JSON.stringify(query)` changes and exposes `refetch` for on-demand
+ * reloads (e.g. a chat roster refresh).
+ *
+ * Requires the `directory.read:users` scope in the widget manifest's
+ * `requestedScopes`.
+ */
+export function useDirectory(query) {
+  const ctx = useWidgetContextOrThrow("useDirectory");
+  if (!ctx.directory || typeof ctx.directory.listUsers !== "function") {
+    throw new Error("useDirectory: host did not inject a directory client");
+  }
+  const [users, setUsers] = useState([]);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState(null);
+
+  // Same ref discipline as useDatastoreQuery: the host rebuilds the
+  // WidgetContext value every render, so we capture the live query +
+  // client in refs to keep `refetch` a stable identity.
+  const queryRef = useRef(query);
+  const listUsersRef = useRef(ctx.directory.listUsers);
+  queryRef.current = query;
+  listUsersRef.current = ctx.directory.listUsers;
+
+  const runRef = useRef(0);
+
+  const doFetch = useCallback(async () => {
+    const myRun = ++runRef.current;
+    setLoading(true);
+    setError(null);
+    try {
+      const rows = await listUsersRef.current(queryRef.current);
+      if (runRef.current !== myRun) return;
+      setUsers(Array.isArray(rows) ? rows : []);
+      setLoading(false);
+    } catch (err) {
+      if (runRef.current !== myRun) return;
+      setError(toDatastoreError(err));
+      setLoading(false);
+    }
+  }, []);
+
+  const queryKey = (() => {
+    try {
+      return JSON.stringify(query);
+    } catch (_e) {
+      return null;
+    }
+  })();
+  useEffect(() => {
+    doFetch();
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [queryKey]);
+
+  const refetch = useCallback(async () => {
+    await doFetch();
+  }, [doFetch]);
+
+  return { users, loading, error, refetch };
+}
+
 /**
  * Emit a named widget event through ctx.events.emit. Page-level event
  * bindings (subscribed by the host) decide what happens next.

package/dist/index.d.ts

@@ -184,6 +184,9 @@ export interface WidgetContext<TProps = unknown> {
     currentRoute: { pageId: string; params: Record<string, string> };
   };
   datastore: unknown; // typed by @colixsystems/datastore-client
+  directory: {
+    listUsers(query?: DirectoryQuery): Promise<DirectoryUser[]>;
+  };
   events: { emit(eventName: string, payload?: unknown): void };
   i18n: {
     locale: string;
@@ -274,6 +277,43 @@ export function useDatastoreMutation<T = unknown>(
   table: string,
 ): MutationApi<T>;
 
+/**
+ * A single row from the read-only user directory. `role` is `"USER"`
+ * for a human end-user or `"INTEGRATION"` for a service account. The
+ * directory deliberately omits email and other admin-only fields.
+ */
+export interface DirectoryUser {
+  id: string;
+  name: string;
+  role: "USER" | "INTEGRATION";
+}
+
+export interface DirectoryQuery {
+  /** Case-insensitive substring match on the display name. */
+  q?: string;
+  /** `"USER"` (default), `"INTEGRATION"`, or `"ALL"`. */
+  role?: "USER" | "INTEGRATION" | "ALL";
+  /** Filter by active state. */
+  isActive?: boolean;
+  limit?: number;
+  offset?: number;
+}
+
+export interface DirectoryResult {
+  users: DirectoryUser[];
+  loading: boolean;
+  error: DatastoreError | null;
+  refetch(): Promise<void>;
+}
+
+/**
+ * Read-only user directory hook. Resolves the tenant's app users to
+ * `{ id, name, role }` rows for chat people-lists, @-mention pickers, or
+ * author-id → display-name resolution. Requires the
+ * `directory.read:users` scope in the widget manifest.
+ */
+export function useDirectory(query?: DirectoryQuery): DirectoryResult;
+
 export function useWidgetEvent(name: string): (payload?: unknown) => void;
 
 export function useTheme(): ThemeTokens;

package/dist/index.js

@@ -10,6 +10,7 @@ export {
   DatastoreError,
   useDatastoreQuery,
   useDatastoreMutation,
+  useDirectory,
   useWidgetEvent,
   useTheme,
   useI18n,

package/dist/index.native.js

@@ -10,6 +10,7 @@ export {
   DatastoreError,
   useDatastoreQuery,
   useDatastoreMutation,
+  useDirectory,
   useWidgetEvent,
   useTheme,
   useI18n,

package/package.json

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