@colixsystems/widget-sdk 0.3.0 → 0.6.0

package/dist/hooks.js

@@ -1,15 +1,58 @@
-// Widget hooks per docs/architecture/widget-marketplace.md §3.1.
-// Each hook reads from the host-provided WidgetContext via React context, then
-// delegates to the host implementation. Bodies are intentionally slim — the
-// hosts (Studio, Player, exported app) own the runtime semantics.
+// Widget hooks per docs/architecture/widget-marketplace.md §3.1 and the
+// CONTRACT in ./contract.js (the single source of truth — when a hook's
+// signature or return shape changes, update both this file and the
+// CONTRACT entry in lockstep).
+//
+// Each hook reads from the host-provided WidgetContext via React context,
+// then delegates to the host implementation. The hosts (Studio, Player,
+// exported app) own the runtime semantics — this file is the SDK surface
+// widgets call.
 //
 // This file avoids JSX so it can ship as a plain .js without a transform.
 
-import React, { createContext, useContext, useCallback } from "react";
+import React, {
+  createContext,
+  useContext,
+  useCallback,
+  useEffect,
+  useRef,
+  useState,
+} from "react";
 
 /** @internal — host-injected context value of shape WidgetContext (see index.d.ts). */
 const HostWidgetContext = createContext(null);
 
+/**
+ * Structured error thrown by `useDatastoreMutation` callbacks (and surfaced
+ * by `useDatastoreQuery` in its `error` slot). Carries a stable `code` so
+ * widgets can branch on the error class without parsing axios message
+ * strings.
+ *
+ * `code` is one of:
+ *   - "VALIDATION"            — 400 / 422 from the datastore
+ *   - "CONSTRAINT_VIOLATION"  — 409 from the datastore
+ *   - "FORBIDDEN"             — 403 from the datastore
+ *   - "NOT_FOUND"             — 404 from the datastore
+ *   - "INTERNAL"              — anything else (network, 5xx, axios timeout)
+ *
+ * `fieldErrors` (when present) is a flat map of field name to per-field
+ * error message, populated when the datastore returned a structured
+ * 400/422 payload with `errors: [{ field, code }, ...]`.
+ */
+export class DatastoreError extends Error {
+  constructor(code, message, opts) {
+    super(message);
+    this.name = "DatastoreError";
+    this.code = code;
+    if (opts && opts.fieldErrors && typeof opts.fieldErrors === "object") {
+      this.fieldErrors = opts.fieldErrors;
+    }
+    if (opts && opts.cause) {
+      this.cause = opts.cause;
+    }
+  }
+}
+
 /**
  * Wraps children with the host-provided WidgetContext.
  * The host (Studio/Player/native shell) builds the value and renders this provider.
@@ -23,54 +66,247 @@ function useWidgetContextOrThrow(hookName) {
   if (ctx == null) {
     throw new Error(
       `${hookName} must be used inside a WidgetContextProvider. ` +
-        `The host (Studio, Player, or exported app) is responsible for mounting it.`
+        `The host (Studio, Player, or exported app) is responsible for mounting it.`,
     );
   }
   return ctx;
 }
 
-// v0.1 scope: returns the host's datastore-backed query result.
-// The host owns suspense/caching; this hook is a passthrough to ctx.datastore.
+// --------------------------------------------------------------- helpers
+
+/**
+ * Coerce an arbitrary thrown value (axios error, plain Error, string) into
+ * a DatastoreError with a stable `.code`. Reads `error.response.status` if
+ * present (axios shape) and falls back to inspecting the message string.
+ */
+function toDatastoreError(err) {
+  if (err instanceof DatastoreError) return err;
+  const status =
+    err && err.response && typeof err.response.status === "number"
+      ? err.response.status
+      : null;
+  const bodyMessage =
+    err &&
+    err.response &&
+    err.response.data &&
+    typeof err.response.data.error === "string"
+      ? err.response.data.error
+      : null;
+  const fallbackMessage =
+    bodyMessage ||
+    (err && typeof err.message === "string"
+      ? err.message
+      : "Datastore call failed");
+  let code = "INTERNAL";
+  if (status === 400 || status === 422) code = "VALIDATION";
+  else if (status === 409) code = "CONSTRAINT_VIOLATION";
+  else if (status === 403) code = "FORBIDDEN";
+  else if (status === 404) code = "NOT_FOUND";
+  // Surface a structured fieldErrors map when the server emitted one
+  // (record.controller.js shapes 422 bodies as `{ errors: [{ field, code }] }`).
+  let fieldErrors;
+  if (
+    err &&
+    err.response &&
+    err.response.data &&
+    Array.isArray(err.response.data.errors)
+  ) {
+    const map = {};
+    for (const entry of err.response.data.errors) {
+      if (entry && typeof entry.field === "string") {
+        map[entry.field] = entry.message || entry.code || "Invalid value";
+      }
+    }
+    if (Object.keys(map).length > 0) fieldErrors = map;
+  }
+  return new DatastoreError(code, fallbackMessage, {
+    cause: err,
+    fieldErrors,
+  });
+}
+
+// --------------------------------------------------------------- hooks
+
+/**
+ * Stateful datastore query hook. Returns { data, loading, error, refetch }.
+ *
+ * The host's datastore client exposes `records(table).list(query)` which
+ * returns a Promise<Record[]>. We hold the result in component state and
+ * re-fetch when [table, JSON.stringify(query)] changes. `refetch` re-runs
+ * the same call on demand.
+ *
+ * When `table` is falsy (e.g. the user hasn't bound a `tableRef` property
+ * yet), the hook resolves to { data: [], loading: false, error: null,
+ * refetch } so the widget can render its empty state without throwing.
+ */
 export function useDatastoreQuery(table, query) {
   const ctx = useWidgetContextOrThrow("useDatastoreQuery");
   if (!ctx.datastore || typeof ctx.datastore.records !== "function") {
-    throw new Error("useDatastoreQuery: host did not inject a datastore client");
+    throw new Error(
+      "useDatastoreQuery: host did not inject a datastore client",
+    );
   }
-  // The host-injected datastore is expected to expose a `useRecords(table, query)` hook;
-  // v0.1 stub returns the raw promise interface and lets the host wire React Query.
-  return ctx.datastore.records(table).list(query);
+  const [data, setData] = useState([]);
+  const [loading, setLoading] = useState(Boolean(table));
+  const [error, setError] = useState(null);
+
+  // Capture the latest table + query in refs so refetch() — a stable
+  // callback identity — always reads the current arguments without having
+  // to be re-bound on every render.
+  //
+  // We hold ctx.datastore.records in a ref for the same reason: the
+  // Studio / Player / PageRenderer rebuild the WidgetContext value
+  // inside their render closure on every render, so `ctx` is a fresh
+  // object identity every render. If `doFetch` listed `[ctx]` in its
+  // dep array, the callback identity (and therefore the `refetch`
+  // surface) would change every render and any widget that put
+  // `refetch` in a useEffect dep array would loop forever. The effect
+  // that drives the actual initial fetch keeps `[table, queryKey]` so
+  // it only re-runs when the bound table or the query payload changes.
+  const tableRef = useRef(table);
+  const queryRef = useRef(query);
+  const recordsRef = useRef(ctx.datastore.records);
+  tableRef.current = table;
+  queryRef.current = query;
+  recordsRef.current = ctx.datastore.records;
+
+  const runRef = useRef(0);
+
+  const doFetch = useCallback(async () => {
+    const myRun = ++runRef.current;
+    const t = tableRef.current;
+    if (!t) {
+      // No table bound yet — collapse to a stable empty result without
+      // a network round-trip.
+      setLoading(false);
+      setError(null);
+      setData([]);
+      return;
+    }
+    setLoading(true);
+    setError(null);
+    try {
+      const ns = recordsRef.current(t);
+      const rows = await ns.list(queryRef.current);
+      // Discard the result if a newer fetch has started since we kicked off.
+      if (runRef.current !== myRun) return;
+      setData(Array.isArray(rows) ? rows : []);
+      setLoading(false);
+    } catch (err) {
+      if (runRef.current !== myRun) return;
+      setError(toDatastoreError(err));
+      setLoading(false);
+    }
+  }, []);
+
+  // Re-run on mount and whenever [table, JSON.stringify(query)] changes.
+  const queryKey = (() => {
+    try {
+      return JSON.stringify(query);
+    } catch (_e) {
+      return null;
+    }
+  })();
+  useEffect(() => {
+    doFetch();
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [table, queryKey]);
+
+  const refetch = useCallback(async () => {
+    await doFetch();
+  }, [doFetch]);
+
+  return { data, loading, error, refetch };
 }
 
-// v0.1 scope: returns { create, update, delete } from the injected datastore client.
+/**
+ * Datastore mutation hook. Returns { create, update, delete }, each method
+ * returning a Promise. Rejected promises throw a DatastoreError carrying a
+ * stable `.code` (`VALIDATION`, `CONSTRAINT_VIOLATION`, `FORBIDDEN`,
+ * `NOT_FOUND`, `INTERNAL`) plus an optional `fieldErrors` map.
+ */
 export function useDatastoreMutation(table) {
   const ctx = useWidgetContextOrThrow("useDatastoreMutation");
   if (!ctx.datastore || typeof ctx.datastore.records !== "function") {
-    throw new Error("useDatastoreMutation: host did not inject a datastore client");
+    throw new Error(
+      "useDatastoreMutation: host did not inject a datastore client",
+    );
   }
   const ns = ctx.datastore.records(table);
   return {
-    create: (values) => ns.create(values),
-    update: (id, values) => ns.update(id, values),
-    delete: (id) => ns.delete(id),
+    create: async (values) => {
+      try {
+        return await ns.create(values);
+      } catch (err) {
+        throw toDatastoreError(err);
+      }
+    },
+    update: async (id, values) => {
+      try {
+        return await ns.update(id, values);
+      } catch (err) {
+        throw toDatastoreError(err);
+      }
+    },
+    delete: async (id) => {
+      try {
+        return await ns.delete(id);
+      } catch (err) {
+        throw toDatastoreError(err);
+      }
+    },
   };
 }
 
-// v0.1 scope: emits a named event through ctx.events.emit. Page-level event
-// bindings (subscribed by the host) decide what happens next.
+/**
+ * Emit a named widget event through ctx.events.emit. Page-level event
+ * bindings (subscribed by the host) decide what happens next.
+ */
 export function useWidgetEvent(name) {
   const ctx = useWidgetContextOrThrow("useWidgetEvent");
   return useCallback((payload) => ctx.events.emit(name, payload), [ctx, name]);
 }
 
-// v0.1 scope: returns ThemeTokens. Host owns theme resolution per workspace.
+/**
+ * Returns the host-provided theme tokens. The host guarantees every field
+ * documented in CONTRACT.themeTokens is present (defaults merged with
+ * tenant overrides), so widgets read `theme.colors.primary` without
+ * optional chaining.
+ */
 export function useTheme() {
   const ctx = useWidgetContextOrThrow("useTheme");
   return ctx.workspace.theme;
 }
 
-// v0.1 scope: returns { locale, t }. Host owns translation tables;
-// the SDK does not bundle a translation engine.
+/**
+ * Returns { t, locale }. `t(key, fallback)` resolves `{{t:key}}` against
+ * the host's translation table and falls back to `fallback ?? key` when
+ * the key is missing. The host's i18n.t may or may not honour the two-arg
+ * form; we degrade gracefully either way.
+ */
 export function useI18n() {
   const ctx = useWidgetContextOrThrow("useI18n");
-  return ctx.i18n;
+  const i18n = ctx.i18n || {};
+  const locale = typeof i18n.locale === "string" ? i18n.locale : "en";
+  const hostT = typeof i18n.t === "function" ? i18n.t : null;
+  const t = useCallback(
+    (key, fallback) => {
+      if (typeof key !== "string" || !key) {
+        return typeof fallback === "string" ? fallback : "";
+      }
+      if (hostT) {
+        // Try the two-arg form first; if the host's `t` ignores `fallback`
+        // and returns the bare key on a miss, swap in the fallback.
+        const out = hostT(key, fallback);
+        if (typeof out === "string" && out.length > 0 && out !== key) {
+          return out;
+        }
+        // Host returned the key (unresolved) or nothing usable.
+        return typeof fallback === "string" ? fallback : key;
+      }
+      return typeof fallback === "string" ? fallback : key;
+    },
+    [hostT],
+  );
+  return { t, locale };
 }

package/dist/index.d.ts

@@ -42,7 +42,11 @@ export interface WidgetPropertyDef {
   enum?: Array<{ value: unknown; label: string }>;
   items?: WidgetPropertyDef;
   properties?: Record<string, WidgetPropertyDef>;
-  ui?: { widget?: "textarea" | "slider" | "code"; group?: string; order?: number };
+  ui?: {
+    widget?: "textarea" | "slider" | "code";
+    group?: string;
+    order?: number;
+  };
   validation?: { min?: number; max?: number; pattern?: string };
 }
 
@@ -181,7 +185,10 @@ export interface WidgetContext<TProps = unknown> {
   };
   datastore: unknown; // typed by @colixsystems/datastore-client
   events: { emit(eventName: string, payload?: unknown): void };
-  i18n: { locale: string; t(key: string, vars?: Record<string, unknown>): string };
+  i18n: {
+    locale: string;
+    t(key: string, vars?: Record<string, unknown>): string;
+  };
   platform: "web" | "native";
   logger: {
     debug: (...args: unknown[]) => void;
@@ -226,16 +233,16 @@ export function defineWidget<TProps = Record<string, unknown>>(opts: {
 }): WidgetModule<TProps>;
 
 export function validateManifest(
-  manifest: unknown
+  manifest: unknown,
 ): { ok: true } | { ok: false; errors: string[] };
 
 export function validatePropertySchema(
-  schema: unknown
+  schema: unknown,
 ): { ok: true } | { ok: false; errors: string[] };
 
 export function validateProps<T = Record<string, unknown>>(
   schema: WidgetPropertySchema,
-  props: unknown
+  props: unknown,
 ): { ok: true; value: T } | { ok: false; errors: string[] };
 
 export interface Query {
@@ -260,35 +267,65 @@ export interface MutationApi<T> {
 
 export function useDatastoreQuery<T = unknown>(
   table: string,
-  query?: Query
+  query?: Query,
 ): QueryResult<T>;
 
 export function useDatastoreMutation<T = unknown>(
-  table: string
+  table: string,
 ): MutationApi<T>;
 
-export function useWidgetEvent(
-  name: string
-): (payload?: unknown) => void;
+export function useWidgetEvent(name: string): (payload?: unknown) => void;
 
 export function useTheme(): ThemeTokens;
 
 export function useI18n(): {
   locale: string;
-  t(key: string, vars?: Record<string, unknown>): string;
+  t(key: string, fallback?: string): string;
 };
 
+/**
+ * Error class thrown by useDatastoreMutation callbacks (and surfaced by
+ * useDatastoreQuery in its `error` slot). The `code` is a stable
+ * categorisation widgets can branch on.
+ */
+export class DatastoreError extends Error {
+  code:
+    | "VALIDATION"
+    | "CONSTRAINT_VIOLATION"
+    | "FORBIDDEN"
+    | "NOT_FOUND"
+    | "INTERNAL";
+  fieldErrors?: Record<string, string>;
+  constructor(
+    code: DatastoreError["code"],
+    message: string,
+    opts?: {
+      fieldErrors?: Record<string, string>;
+      cause?: unknown;
+    },
+  );
+}
+
 export function WidgetContextProvider(props: {
   value: WidgetContext;
   children?: ReactNode;
 }): JSX.Element;
 
-// Primitives — platform-aware. Type as opaque components.
+// Primitives — re-exported from `react-native` (web build aliases to
+// `react-native-web`). Typed as opaque components here; widget authors
+// targeting TypeScript should install `@types/react-native` for full
+// prop typing.
 export const Text: any;
 export const View: any;
 export const Pressable: any;
 export const Image: any;
 export const ScrollView: any;
+export const TextInput: any;
+export const FlatList: any;
+export const SectionList: any;
+export const ActivityIndicator: any;
+export const Switch: any;
+export const StyleSheet: any;
 
 // Linter
 export interface LintFinding {
@@ -301,3 +338,76 @@ export function lintSource(source: string): {
   ok: boolean;
   findings: LintFinding[];
 };
+
+// --------------------------------------------------------------- CONTRACT
+//
+// Single-source-of-truth contract artefact. See docs/design/ai-widget-contract.md.
+// The runtime value is `Object.freeze`d; the type below describes the
+// public shape consumers can read.
+
+export interface ContractHookEntry {
+  name: string;
+  signature: string;
+  returnShape: Record<string, string>;
+  requiredContextSlice: string[];
+  scopes: string[] | null;
+}
+
+export interface ContractPrimitiveEntry {
+  name: string;
+  description: string;
+  props: Record<
+    string,
+    { type: string; required?: boolean; description?: string }
+  >;
+}
+
+export interface ContractManifestField {
+  type: string;
+  required: boolean;
+  description?: string;
+  default?: unknown;
+  values?: readonly string[];
+  example?: unknown;
+}
+
+export interface ContractBundleShape {
+  name: string;
+  description: string;
+  predicate: string;
+  manifestSource: string;
+  audience: string;
+}
+
+export interface ContractBannedApi {
+  identifier: string;
+  reason: string;
+}
+
+export interface AiWidgetContract {
+  readonly version: string;
+  readonly hooks: ReadonlyArray<ContractHookEntry>;
+  readonly primitives: ReadonlyArray<ContractPrimitiveEntry>;
+  readonly manifestSchema: Readonly<Record<string, ContractManifestField>>;
+  readonly manifestCategories: ReadonlyArray<string>;
+  readonly manifestPlatforms: ReadonlyArray<string>;
+  readonly themeTokens: ThemeTokens;
+  readonly widgetContextShape: Readonly<
+    Record<
+      string,
+      {
+        description: string;
+        required: boolean;
+        fields: Record<string, unknown>;
+      }
+    >
+  >;
+  readonly bundleExportContract: ReadonlyArray<ContractBundleShape>;
+  readonly bannedApis: ReadonlyArray<ContractBannedApi>;
+  readonly allowedBareImports: ReadonlyArray<string>;
+}
+
+export const CONTRACT: AiWidgetContract;
+
+export function isHookAllowed(name: string): boolean;
+export function requiredContextKeys(): string[];

package/dist/index.js

@@ -7,11 +7,25 @@ export { validateManifest, canonicalCategory } from "./manifest.js";
 export { validatePropertySchema, validateProps } from "./property-schema.js";
 export {
   WidgetContextProvider,
+  DatastoreError,
   useDatastoreQuery,
   useDatastoreMutation,
   useWidgetEvent,
   useTheme,
   useI18n,
 } from "./hooks.js";
-export { Text, View, Pressable, Image, ScrollView } from "./primitives.js";
-export { lintSource } from "./linter.js";
+export {
+  Text,
+  View,
+  Pressable,
+  Image,
+  ScrollView,
+  TextInput,
+  FlatList,
+  SectionList,
+  ActivityIndicator,
+  Switch,
+  StyleSheet,
+} from "./primitives.js";
+export { lintSource, bannedIdentifiers } from "./linter.js";
+export { CONTRACT, isHookAllowed, requiredContextKeys } from "./contract.js";

package/dist/index.native.js

@@ -7,11 +7,25 @@ export { validateManifest, canonicalCategory } from "./manifest.js";
 export { validatePropertySchema, validateProps } from "./property-schema.js";
 export {
   WidgetContextProvider,
+  DatastoreError,
   useDatastoreQuery,
   useDatastoreMutation,
   useWidgetEvent,
   useTheme,
   useI18n,
 } from "./hooks.js";
-export { Text, View, Pressable, Image, ScrollView } from "./primitives.native.js";
-export { lintSource } from "./linter.js";
+export {
+  Text,
+  View,
+  Pressable,
+  Image,
+  ScrollView,
+  TextInput,
+  FlatList,
+  SectionList,
+  ActivityIndicator,
+  Switch,
+  StyleSheet,
+} from "./primitives.native.js";
+export { lintSource, bannedIdentifiers } from "./linter.js";
+export { CONTRACT, isHookAllowed, requiredContextKeys } from "./contract.js";

package/dist/linter.cjs

@@ -0,0 +1,104 @@
+// CommonJS-flavoured copy of the linter so backend services (CJS runtime)
+// can `require()` it directly without dynamic-import gymnastics.
+//
+// The ESM `linter.js` is the source-of-truth. This file MUST mirror its
+// rule set byte-for-byte — the contract test in packages/widget-sdk
+// asserts the two are behaviour-equivalent. When you edit one, edit the
+// other in the same PR. (Pattern matches `contract.cjs` / `contract.js`.)
+//
+// The SDK build script copies both into `dist/`.
+
+"use strict";
+
+const { CONTRACT } = require("./contract.cjs");
+
+function _ruleForIdentifier(identifier, reason) {
+  const id = identifier;
+  if (id === "Function") {
+    return {
+      id: "no-function-constructor",
+      label: `${reason} (banned: Function() constructor)`,
+      pattern: /(^|[^A-Za-z0-9_$.])Function\s*\(/,
+    };
+  }
+  if (id === "new Function") {
+    return {
+      id: "no-new-function",
+      label: `${reason} (banned: new Function())`,
+      pattern: /\bnew\s+Function\s*\(/,
+    };
+  }
+  if (id === "import(") {
+    return {
+      id: "no-dynamic-import",
+      label: `${reason} (banned: dynamic import())`,
+      pattern: /(^|[^A-Za-z0-9_$.])import\s*\(/,
+    };
+  }
+  if (id === "eval") {
+    return {
+      id: "no-eval",
+      label: `${reason} (banned: eval)`,
+      pattern: /\beval\s*\(/,
+    };
+  }
+  const escaped = id.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  return {
+    id: `no-${id.toLowerCase()}`,
+    label: `${reason} (banned: ${id})`,
+    pattern: new RegExp(`\\b${escaped}\\b`),
+  };
+}
+
+const CONTRACT_RULES = CONTRACT.bannedApis.map((b) =>
+  _ruleForIdentifier(b.identifier, b.reason),
+);
+
+const EXTRA_RULES = [
+  {
+    id: "no-auth-store-import",
+    label: "widgets must not import the host's auth store",
+    pattern: /useAuthStore/,
+  },
+  {
+    id: "no-axios-import",
+    label:
+      "widgets must not import axios directly; use the injected datastore client",
+    pattern: /from\s+['"]axios['"]|require\s*\(\s*['"]axios['"]\s*\)/,
+  },
+];
+
+const RULES = [...CONTRACT_RULES, ...EXTRA_RULES];
+
+function bannedIdentifiers() {
+  return CONTRACT.bannedApis.map((b) => b.identifier);
+}
+
+function lintSource(source) {
+  if (typeof source !== "string") {
+    return {
+      ok: false,
+      findings: [
+        { rule: "input", label: "source must be a string", line: 0, snippet: "" },
+      ],
+    };
+  }
+  const findings = [];
+  const lines = source.split(/\r?\n/);
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    for (const rule of RULES) {
+      if (rule.pattern.test(line)) {
+        findings.push({
+          rule: rule.id,
+          label: rule.label,
+          line: i + 1,
+          snippet: line.trim().slice(0, 200),
+        });
+      }
+    }
+  }
+  return { ok: findings.length === 0, findings };
+}
+
+module.exports = { lintSource, bannedIdentifiers };