@colixsystems/widget-sdk 0.10.0 → 0.11.0

package/README.md

@@ -6,7 +6,12 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`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**.
+`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
 
@@ -75,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`, `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).
+- `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

@@ -68,6 +68,20 @@ const HOOKS = [
     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?)",
@@ -209,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

@@ -68,6 +68,20 @@ const HOOKS = [
     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?)",
@@ -204,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

@@ -370,6 +370,24 @@ export function 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

@@ -381,6 +381,32 @@ export function useUser(): {
   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

@@ -17,6 +17,7 @@ export {
   useTheme,
   useI18n,
   useUser,
+  useNavigation,
 } from "./hooks.js";
 export {
   Text,
@@ -30,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

@@ -17,6 +17,7 @@ export {
   useTheme,
   useI18n,
   useUser,
+  useNavigation,
 } from "./hooks.js";
 export {
   Text,
@@ -30,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.10.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",