@colixsystems/widget-sdk 0.9.0 → 0.11.0

package/README.md

@@ -6,7 +6,16 @@ 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.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**.
+
+### What's new in 0.11.0
+
+- **`useNavigation()` is wired.** Returns the host-provided navigation surface `{ goTo, goBack, push, replace, back, currentRoute }` for internal page-to-page navigation. Missing methods degrade to no-ops on the Studio canvas preview. Additive.
+- **`Linking` primitive re-exported.** `Linking.openURL(url)` opens an external URL with the OS handler — web (`react-native-web`) maps to `window.open` / `location.href`; native hands off to the system. Use this for external URLs; use `useNavigation().goTo(pageId)` for internal pages.
+
+### 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 +80,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`, `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)`).
 - `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,33 @@ 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: "useNavigation",
+    signature: "useNavigation()",
+    returnShape: {
+      goTo: "(pageId: string, params?: object) => void",
+      goBack: "() => void",
+      push: "(pageId: string, params?: object) => void",
+      replace: "(pageId: string, params?: object) => void",
+      back: "() => void",
+      currentRoute: "{ pageId: string, params: object }",
+    },
+    requiredContextSlice: ["navigation"],
+    scopes: null,
+  },
   {
     name: "useDatastoreQuery",
     signature: "useDatastoreQuery(tableId, options?)",
@@ -196,6 +223,13 @@ const PRIMITIVES = [
     rnComponent: "StyleSheet",
     docsUrl: "https://reactnative.dev/docs/stylesheet",
   },
+  {
+    name: "Linking",
+    description:
+      "Static API for external links. `Linking.openURL(url)` opens a URL with the OS handler (web: window.open / location.href via react-native-web). `canOpenURL` reports whether the scheme is registered. See https://reactnative.dev/docs/linking.",
+    rnComponent: "Linking",
+    docsUrl: "https://reactnative.dev/docs/linking",
+  },
 ];
 
 const CATEGORIES = [

package/dist/contract.js

@@ -55,6 +55,33 @@ 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: "useNavigation",
+    signature: "useNavigation()",
+    returnShape: {
+      goTo: "(pageId: string, params?: object) => void",
+      goBack: "() => void",
+      push: "(pageId: string, params?: object) => void",
+      replace: "(pageId: string, params?: object) => void",
+      back: "() => void",
+      currentRoute: "{ pageId: string, params: object }",
+    },
+    requiredContextSlice: ["navigation"],
+    scopes: null,
+  },
   {
     name: "useDatastoreQuery",
     signature: "useDatastoreQuery(tableId, options?)",
@@ -191,6 +218,13 @@ const PRIMITIVES = [
     rnComponent: "StyleSheet",
     docsUrl: "https://reactnative.dev/docs/stylesheet",
   },
+  {
+    name: "Linking",
+    description:
+      "Static API for external links. `Linking.openURL(url)` opens a URL with the OS handler (web: window.open / location.href via react-native-web). `canOpenURL` reports whether the scheme is registered. See https://reactnative.dev/docs/linking.",
+    rnComponent: "Linking",
+    docsUrl: "https://reactnative.dev/docs/linking",
+  },
 ];
 
 const CATEGORIES = [

package/dist/hooks.js

@@ -352,6 +352,42 @@ 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;
+}
+
+/**
+ * Returns the host-provided navigation surface:
+ *   `{ goTo, goBack, push, replace, back, currentRoute }`.
+ *
+ * `goTo(pageId, params?)` navigates to an internal app page. `goBack()`
+ * pops the stack. `push` / `replace` / `back` are aliases that map to
+ * the platform's native navigator (react-router on web, react-navigation
+ * on native). Missing methods degrade to no-ops on the Studio canvas
+ * preview, where there is no live router.
+ *
+ * For EXTERNAL URLs use the `Linking` primitive — `Linking.openURL(url)`
+ * works on both platforms.
+ */
+export function useNavigation() {
+  const ctx = useWidgetContextOrThrow("useNavigation");
+  return ctx.navigation;
+}
+
 /**
  * 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,45 @@ 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[];
+};
+
+/**
+ * The host-provided navigation surface. `goTo(pageId, params?)` navigates
+ * to an internal app page; `goBack()` pops the stack. Missing methods
+ * degrade to no-ops on the Studio canvas preview where no live router is
+ * mounted. For external URLs use the `Linking` primitive.
+ */
+export function useNavigation(): {
+  goTo(pageId: string, params?: Record<string, unknown>): void;
+  goBack(): void;
+  push(pageId: string, params?: Record<string, unknown>): void;
+  replace(pageId: string, params?: Record<string, unknown>): void;
+  back(): void;
+  currentRoute: { pageId: string; params: Record<string, unknown> };
+};
+
+/**
+ * Static API for external URLs. `openURL(url)` opens a URL with the OS
+ * handler (web: react-native-web maps to `window.open` / `location.href`;
+ * native: hands off to the system). `canOpenURL` reports whether the
+ * scheme is registered.
+ */
+export const Linking: {
+  openURL(url: string): Promise<unknown>;
+  canOpenURL(url: string): Promise<boolean>;
+};
+
 /**
  * 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,8 @@ export {
   usePayments,
   useTheme,
   useI18n,
+  useUser,
+  useNavigation,
 } from "./hooks.js";
 export {
   Text,
@@ -29,6 +31,7 @@ export {
   ActivityIndicator,
   Switch,
   StyleSheet,
+  Linking,
 } from "./primitives.js";
 export { lintSource, bannedIdentifiers } from "./linter.js";
 export { CONTRACT, isHookAllowed, requiredContextKeys } from "./contract.js";

package/dist/index.native.js

@@ -16,6 +16,8 @@ export {
   usePayments,
   useTheme,
   useI18n,
+  useUser,
+  useNavigation,
 } from "./hooks.js";
 export {
   Text,
@@ -29,6 +31,7 @@ export {
   ActivityIndicator,
   Switch,
   StyleSheet,
+  Linking,
 } from "./primitives.native.js";
 export { lintSource, bannedIdentifiers } from "./linter.js";
 export { CONTRACT, isHookAllowed, requiredContextKeys } from "./contract.js";

package/dist/primitives.js

@@ -55,3 +55,8 @@ export const SectionList = ReactNative.SectionList;
 export const ActivityIndicator = ReactNative.ActivityIndicator;
 export const Switch = ReactNative.Switch;
 export const StyleSheet = ReactNative.StyleSheet;
+// Static API (not a component): `Linking.openURL(url)` opens an external
+// URL — on web react-native-web uses window.open / location.href, on native
+// the OS hands it off to the system handler. `canOpenURL` reports whether
+// the URL scheme is registered.
+export const Linking = ReactNative.Linking;

package/dist/primitives.native.js

@@ -18,4 +18,5 @@ export {
   ActivityIndicator,
   Switch,
   StyleSheet,
+  Linking,
 } from "react-native";

package/package.json

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