@colixsystems/widget-sdk 0.9.0 → 0.10.0

package/README.md

@@ -6,7 +6,11 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.9.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.10.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.10.0
+
+- **`useUser()` is wired.** Returns the active end-user identity `{ id, email, displayName, roles, groupIds }` from the host-provided `WidgetContext`. `id` is `null` for anonymous visitors and on the Studio canvas preview. All fields are guaranteed present (the host fills safe defaults), so widgets read them without optional chaining. Additive — no migration needed for existing widgets.
 
 ### What's new in 0.9.0
 
@@ -71,7 +75,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`, `useDirectory`, `useWidgetEvent`, `usePayments`, `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. `usePayments()` returns `{ requestPayment, getPayment }` and requires the `payments.charge:appUser` scope; `requestPayment(...)` rejects with a `PaymentError`.
+- `useDatastoreQuery`, `useDatastoreMutation`, `useDirectory`, `useWidgetEvent`, `usePayments`, `useTheme`, `useI18n`, `useUser` — 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).
 - `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

@@ -55,6 +55,19 @@ const HOOKS = [
     requiredContextSlice: ["i18n.t", "i18n.locale"],
     scopes: null,
   },
+  {
+    name: "useUser",
+    signature: "useUser()",
+    returnShape: {
+      id: "string | null",
+      email: "string | null",
+      displayName: "string | null",
+      roles: "string[]",
+      groupIds: "string[]",
+    },
+    requiredContextSlice: ["user"],
+    scopes: null,
+  },
   {
     name: "useDatastoreQuery",
     signature: "useDatastoreQuery(tableId, options?)",

package/dist/contract.js

@@ -55,6 +55,19 @@ const HOOKS = [
     requiredContextSlice: ["i18n.t", "i18n.locale"],
     scopes: null,
   },
+  {
+    name: "useUser",
+    signature: "useUser()",
+    returnShape: {
+      id: "string | null",
+      email: "string | null",
+      displayName: "string | null",
+      roles: "string[]",
+      groupIds: "string[]",
+    },
+    requiredContextSlice: ["user"],
+    scopes: null,
+  },
   {
     name: "useDatastoreQuery",
     signature: "useDatastoreQuery(tableId, options?)",

package/dist/hooks.js

@@ -352,6 +352,24 @@ export function useTheme() {
   return ctx.workspace.theme;
 }
 
+/**
+ * Returns the active end-user identity:
+ *   `{ id, email, displayName, roles, groupIds }`.
+ *
+ * `id` is `null` for anonymous visitors (and on the Studio canvas preview,
+ * which renders widgets as if signed-out so the public branch shows). All
+ * fields are guaranteed present by the host (`buildHostWidgetContext`
+ * + the native `WidgetHost`); widgets read them without optional chaining.
+ *
+ * Use this to render the signed-in user's name in a header, branch on
+ * roles, or stamp a created-by field. Email is opaque to widgets that
+ * only need a display name — prefer `displayName` for UI strings.
+ */
+export function useUser() {
+  const ctx = useWidgetContextOrThrow("useUser");
+  return ctx.user;
+}
+
 /**
  * Structured error thrown by `usePayments` callbacks. Carries a stable
  * `code` so widgets can branch without parsing message strings.

package/dist/index.d.ts

@@ -368,6 +368,19 @@ export function useI18n(): {
   t(key: string, fallback?: string): string;
 };
 
+/**
+ * The active end-user identity. `id` is null for anonymous visitors and on
+ * the Studio canvas preview; every field is guaranteed present (the host
+ * fills safe defaults), so widgets read them without optional chaining.
+ */
+export function useUser(): {
+  id: string | null;
+  email: string | null;
+  displayName: string | null;
+  roles: string[];
+  groupIds: string[];
+};
+
 /**
  * Error class thrown by useDatastoreMutation callbacks (and surfaced by
  * useDatastoreQuery in its `error` slot). The `code` is a stable

package/dist/index.js

@@ -16,6 +16,7 @@ export {
   usePayments,
   useTheme,
   useI18n,
+  useUser,
 } from "./hooks.js";
 export {
   Text,

package/dist/index.native.js

@@ -16,6 +16,7 @@ export {
   usePayments,
   useTheme,
   useI18n,
+  useUser,
 } from "./hooks.js";
 export {
   Text,

package/package.json

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