@colixsystems/widget-sdk 0.10.0 → 0.12.0

package/README.md

@@ -6,7 +6,17 @@ 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.12.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.12.0
+
+- **`useDatastoreRecord(tableId, recordId)` is wired.** Returns `{ data, loading, error, refetch }` for a single record fetched through the host's `records(table).get(id)`. Sister to `useDatastoreQuery`; mirrors its ref discipline so `refetch` stays a stable callback identity. A 404 surfaces as `DatastoreError.code === "NOT_FOUND"`. Additive.
+- **`useFile(fileId)` is wired** + new `WidgetContext.files` slice. Returns `{ url, file, loading, error, refetch }` — the `url` is an absolute URL the widget can drop straight into `<Image source>`. Backed by a new `files.get(fileId)` host facade (web: `widgetHostFiles` through `api/client`; native: `hostFiles` in the export's `widgetHost.js`). Additive.
+
+### 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 +85,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`, `useDatastoreRecord`, `useDatastoreMutation`, `useDirectory`, `useFile`, `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)`). `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.
 - `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,45 @@ 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: "useDatastoreRecord",
+    signature: "useDatastoreRecord(tableId, recordId)",
+    returnShape: {
+      data: "Record | null",
+      loading: "boolean",
+      error: "DatastoreError | null",
+      refetch: "() => Promise<void>",
+    },
+    requiredContextSlice: ["datastore.records"],
+    scopes: ["datastore.read:<table>"],
+  },
+  {
+    name: "useFile",
+    signature: "useFile(fileId)",
+    returnShape: {
+      url: "string | null",
+      file: "{ id, url, storedFilename, mimeType, sizeBytes, ... } | null",
+      loading: "boolean",
+      error: "DatastoreError | null",
+      refetch: "() => Promise<void>",
+    },
+    requiredContextSlice: ["files.get"],
+    scopes: null,
+  },
   {
     name: "useDatastoreQuery",
     signature: "useDatastoreQuery(tableId, options?)",
@@ -209,6 +248,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 = [
@@ -355,6 +401,12 @@ const WIDGET_CONTEXT_SHAPE = {
     required: true,
     fields: { listUsers: "function" },
   },
+  files: {
+    description:
+      "Read-only asset resolver. { get(fileId) -> Promise<{ id, url, storedFilename, mimeType, sizeBytes, ... }> }. Backs useFile(); resolves an asset id to an absolute URL the widget can drop into an <Image source>. The url field is always an absolute URL composed against the host's API base.",
+    required: true,
+    fields: { get: "function" },
+  },
   events: {
     description: "{ emit(name, payload) }.",
     required: true,

package/dist/contract.js

@@ -68,6 +68,45 @@ 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: "useDatastoreRecord",
+    signature: "useDatastoreRecord(tableId, recordId)",
+    returnShape: {
+      data: "Record | null",
+      loading: "boolean",
+      error: "DatastoreError | null",
+      refetch: "() => Promise<void>",
+    },
+    requiredContextSlice: ["datastore.records"],
+    scopes: ["datastore.read:<table>"],
+  },
+  {
+    name: "useFile",
+    signature: "useFile(fileId)",
+    returnShape: {
+      url: "string | null",
+      file: "{ id, url, storedFilename, mimeType, sizeBytes, ... } | null",
+      loading: "boolean",
+      error: "DatastoreError | null",
+      refetch: "() => Promise<void>",
+    },
+    requiredContextSlice: ["files.get"],
+    scopes: null,
+  },
   {
     name: "useDatastoreQuery",
     signature: "useDatastoreQuery(tableId, options?)",
@@ -204,6 +243,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 = [
@@ -349,6 +395,12 @@ const WIDGET_CONTEXT_SHAPE = {
     required: true,
     fields: { listUsers: "function" },
   },
+  files: {
+    description:
+      "Read-only asset resolver. { get(fileId) -> Promise<{ id, url, storedFilename, mimeType, sizeBytes, ... }> }. Backs useFile(); resolves an asset id to an absolute URL the widget can drop into an <Image source>. The url field is always an absolute URL composed against the host's API base.",
+    required: true,
+    fields: { get: "function" },
+  },
   events: {
     description: "{ emit(name, payload) }.",
     required: true,

package/dist/hooks.js

@@ -219,6 +219,153 @@ export function useDatastoreQuery(table, query) {
   return { data, loading, error, refetch };
 }
 
+/**
+ * Stateful single-record query hook. Returns { data, loading, error, refetch }
+ * where `data` is one row (`null` until loaded, never an array).
+ *
+ * The host's datastore client exposes `records(table).get(id)` which
+ * resolves to a single record object. We hold the result in component
+ * state and re-fetch when [table, id] changes. `refetch` re-runs the
+ * call on demand.
+ *
+ * When `table` OR `recordId` is falsy (e.g. the author hasn't bound the
+ * record id yet), the hook resolves to { data: null, loading: false,
+ * error: null, refetch } so the widget can render its empty state
+ * without throwing. A 404 surfaces as a DatastoreError with
+ * `code: "NOT_FOUND"`.
+ */
+export function useDatastoreRecord(table, recordId) {
+  const ctx = useWidgetContextOrThrow("useDatastoreRecord");
+  if (!ctx.datastore || typeof ctx.datastore.records !== "function") {
+    throw new Error(
+      "useDatastoreRecord: host did not inject a datastore client",
+    );
+  }
+  const ready = Boolean(table && recordId);
+  const [data, setData] = useState(null);
+  const [loading, setLoading] = useState(ready);
+  const [error, setError] = useState(null);
+
+  // Same ref discipline as useDatastoreQuery — `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 tableRef = useRef(table);
+  const recordIdRef = useRef(recordId);
+  const recordsRef = useRef(ctx.datastore.records);
+  tableRef.current = table;
+  recordIdRef.current = recordId;
+  recordsRef.current = ctx.datastore.records;
+
+  const runRef = useRef(0);
+
+  const doFetch = useCallback(async () => {
+    const myRun = ++runRef.current;
+    const t = tableRef.current;
+    const id = recordIdRef.current;
+    if (!t || !id) {
+      setLoading(false);
+      setError(null);
+      setData(null);
+      return;
+    }
+    setLoading(true);
+    setError(null);
+    try {
+      const ns = recordsRef.current(t);
+      const row = await ns.get(id);
+      if (runRef.current !== myRun) return;
+      setData(row || 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
+  }, [table, recordId]);
+
+  const refetch = useCallback(async () => {
+    await doFetch();
+  }, [doFetch]);
+
+  return { data, loading, error, refetch };
+}
+
+/**
+ * Stateful file-asset resolver hook. Returns { url, file, loading, error,
+ * refetch }.
+ *
+ * The host's file client exposes `files.get(fileId)` which resolves to
+ * `{ url, ...meta }` — the absolute URL is composed against the host's
+ * API base so the widget can drop it straight into an `<Image source>`
+ * without knowing where the API lives. A missing/soft-deleted asset
+ * surfaces as `{ url: null, error: <DatastoreError NOT_FOUND> }`.
+ *
+ * When `fileId` is falsy the hook collapses to { url: null, file: null,
+ * loading: false, error: null, refetch } without a network round-trip,
+ * so a widget rendering before the author has bound an asset stays
+ * loop-free.
+ */
+export function useFile(fileId) {
+  const ctx = useWidgetContextOrThrow("useFile");
+  if (!ctx.files || typeof ctx.files.get !== "function") {
+    throw new Error("useFile: host did not inject a files client");
+  }
+  const ready = Boolean(fileId);
+  const [file, setFile] = useState(null);
+  const [loading, setLoading] = useState(ready);
+  const [error, setError] = useState(null);
+
+  const fileIdRef = useRef(fileId);
+  const getRef = useRef(ctx.files.get);
+  fileIdRef.current = fileId;
+  getRef.current = ctx.files.get;
+
+  const runRef = useRef(0);
+
+  const doFetch = useCallback(async () => {
+    const myRun = ++runRef.current;
+    const id = fileIdRef.current;
+    if (!id) {
+      setLoading(false);
+      setError(null);
+      setFile(null);
+      return;
+    }
+    setLoading(true);
+    setError(null);
+    try {
+      const f = await getRef.current(id);
+      if (runRef.current !== myRun) return;
+      setFile(f || 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
+  }, [fileId]);
+
+  const refetch = useCallback(async () => {
+    await doFetch();
+  }, [doFetch]);
+
+  const url =
+    file && typeof file.url === "string" && file.url.length > 0
+      ? file.url
+      : null;
+  return { url, file, loading, error, refetch };
+}
+
 /**
  * Datastore mutation hook. Returns { create, update, delete }, each method
  * returning a Promise. Rejected promises throw a DatastoreError carrying a
@@ -370,6 +517,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

@@ -363,6 +363,40 @@ export function usePayments(): PaymentsApi;
 
 export function useTheme(): ThemeTokens;
 
+/**
+ * Stateful single-record fetch hook. Returns `{ data, loading, error,
+ * refetch }`. `data` is one row or `null` (never an array).
+ */
+export function useDatastoreRecord(
+  tableId: string | null | undefined,
+  recordId: string | null | undefined,
+): {
+  data: unknown | null;
+  loading: boolean;
+  error: DatastoreError | null;
+  refetch(): Promise<void>;
+};
+
+/**
+ * Stateful file-asset resolver hook. Returns `{ url, file, loading, error,
+ * refetch }`. The `url` is an absolute URL composed against the host's API
+ * base; safe to pass straight to `<Image source>`.
+ */
+export function useFile(fileId: string | null | undefined): {
+  url: string | null;
+  file: {
+    id: string;
+    url: string;
+    storedFilename?: string;
+    mimeType?: string;
+    sizeBytes?: number;
+    [k: string]: unknown;
+  } | null;
+  loading: boolean;
+  error: DatastoreError | null;
+  refetch(): Promise<void>;
+};
+
 export function useI18n(): {
   locale: string;
   t(key: string, fallback?: string): string;
@@ -381,6 +415,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

@@ -10,6 +10,8 @@ export {
   DatastoreError,
   PaymentError,
   useDatastoreQuery,
+  useDatastoreRecord,
+  useFile,
   useDatastoreMutation,
   useDirectory,
   useWidgetEvent,
@@ -17,6 +19,7 @@ export {
   useTheme,
   useI18n,
   useUser,
+  useNavigation,
 } from "./hooks.js";
 export {
   Text,
@@ -30,6 +33,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

@@ -10,6 +10,8 @@ export {
   DatastoreError,
   PaymentError,
   useDatastoreQuery,
+  useDatastoreRecord,
+  useFile,
   useDatastoreMutation,
   useDirectory,
   useWidgetEvent,
@@ -17,6 +19,7 @@ export {
   useTheme,
   useI18n,
   useUser,
+  useNavigation,
 } from "./hooks.js";
 export {
   Text,
@@ -30,6 +33,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.12.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "type": "module",
   "main": "./dist/index.js",