@colixsystems/widget-sdk 0.13.0 → 0.15.0

package/dist/hooks.js

@@ -61,7 +61,9 @@ export function WidgetContextProvider({ value, children }) {
   return React.createElement(HostWidgetContext.Provider, { value }, children);
 }
 
-function useWidgetContextOrThrow(hookName) {
+// Exported for ./toast.js + future hook modules outside hooks.js. Internal
+// utility — widget code should not import this directly.
+export function useWidgetContextOrThrow(hookName) {
   const ctx = useContext(HostWidgetContext);
   if (ctx == null) {
     throw new Error(
@@ -687,6 +689,236 @@ export function usePayments() {
  * the key is missing. The host's i18n.t may or may not honour the two-arg
  * form; we degrade gracefully either way.
  */
+/**
+ * REQ-USERMGMT / REQ-ACL-SYS M3 — structured error thrown by `useUsers` /
+ * `useGroups` callbacks. Carries a stable `code` so widgets can branch
+ * without parsing message strings.
+ *
+ * `code` is one of:
+ *   - "FORBIDDEN"   — 403 from the host (capability or scope missing).
+ *   - "VALIDATION"  — 400 / 422 (bad email, duplicate, etc.).
+ *   - "NOT_FOUND"   — 404 (group / user does not exist or cross-tenant).
+ *   - "INVITE_ONLY" — 409 from accept-invite-style flows where the tenant
+ *                     is invite-only and the email is not on the list.
+ *   - "INTERNAL"    — anything else (network, 5xx).
+ */
+export class DirectoryError extends Error {
+  constructor(code, message, opts) {
+    super(message);
+    this.name = "DirectoryError";
+    this.code = code;
+    if (opts && opts.cause) this.cause = opts.cause;
+  }
+}
+
+function toDirectoryError(err) {
+  if (err instanceof DirectoryError) return err;
+  const status =
+    err && err.response && typeof err.response.status === "number"
+      ? err.response.status
+      : null;
+  const bodyCode =
+    err && err.response && err.response.data && err.response.data.code;
+  const bodyMessage =
+    err && err.response && err.response.data && err.response.data.error;
+  let code = "INTERNAL";
+  if (bodyCode === "INVITE_ONLY") code = "INVITE_ONLY";
+  else if (status === 403) code = "FORBIDDEN";
+  else if (status === 404) code = "NOT_FOUND";
+  else if (status === 400 || status === 422) code = "VALIDATION";
+  else if (status === 409) {
+    // 409 is invite-only on the invite endpoints; treat the rest as
+    // validation conflicts (duplicate email, etc.).
+    code = bodyCode === "INVITE_ONLY" ? "INVITE_ONLY" : "VALIDATION";
+  }
+  const message =
+    (typeof bodyMessage === "string" && bodyMessage) ||
+    (err && typeof err.message === "string"
+      ? err.message
+      : "Directory call failed");
+  return new DirectoryError(code, message, { cause: err });
+}
+
+/**
+ * REQ-USERMGMT / REQ-ACL-SYS M3 — AppUser administration hook.
+ *
+ * Returns `{ users, loading, error, refetch, invite, deactivate,
+ * reactivate, remove }`. The list refetches whenever
+ * `JSON.stringify(query)` changes; the imperative methods reject with a
+ * `DirectoryError`. Reads require the `users.read:*` scope; mutations
+ * additionally require `users.write:*`. The host's signed
+ * `X-Widget-Scopes` header + a tenant-scoped SystemAcl `users.read` /
+ * `users.write` capability grant gate the underlying endpoint
+ * (REQ-ACL-SYS M3 §4.3) — a widget that declares the scopes but whose
+ * caller does not hold the grant gets a `FORBIDDEN`.
+ */
+export function useUsers(query) {
+  const ctx = useWidgetContextOrThrow("useUsers");
+  if (!ctx.users || typeof ctx.users.listUsers !== "function") {
+    throw new Error("useUsers: host did not inject a users client");
+  }
+  const [users, setUsers] = useState([]);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState(null);
+
+  const queryRef = useRef(query);
+  const usersRef = useRef(ctx.users);
+  queryRef.current = query;
+  usersRef.current = ctx.users;
+
+  const runRef = useRef(0);
+
+  const doFetch = useCallback(async () => {
+    const myRun = ++runRef.current;
+    setLoading(true);
+    setError(null);
+    try {
+      const rows = await usersRef.current.listUsers(queryRef.current);
+      if (runRef.current !== myRun) return;
+      setUsers(Array.isArray(rows) ? rows : []);
+      setLoading(false);
+    } catch (err) {
+      if (runRef.current !== myRun) return;
+      setError(toDirectoryError(err));
+      setLoading(false);
+    }
+  }, []);
+
+  const queryKey = (() => {
+    try {
+      return JSON.stringify(query);
+    } catch (_e) {
+      return null;
+    }
+  })();
+  useEffect(() => {
+    doFetch();
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [queryKey]);
+
+  const refetch = useCallback(async () => {
+    await doFetch();
+  }, [doFetch]);
+
+  const invite = useCallback(async (args) => {
+    try {
+      return await usersRef.current.invite(args);
+    } catch (err) {
+      throw toDirectoryError(err);
+    }
+  }, []);
+  const deactivate = useCallback(async (userId) => {
+    try {
+      return await usersRef.current.deactivate(userId);
+    } catch (err) {
+      throw toDirectoryError(err);
+    }
+  }, []);
+  const reactivate = useCallback(async (userId) => {
+    try {
+      return await usersRef.current.reactivate(userId);
+    } catch (err) {
+      throw toDirectoryError(err);
+    }
+  }, []);
+  const remove = useCallback(async (userId) => {
+    try {
+      return await usersRef.current.remove(userId);
+    } catch (err) {
+      throw toDirectoryError(err);
+    }
+  }, []);
+
+  return { users, loading, error, refetch, invite, deactivate, reactivate, remove };
+}
+
+/**
+ * REQ-USERMGMT / REQ-ACL-SYS M3 — AppUserGroup administration hook.
+ *
+ * Returns `{ groups, loading, error, refetch, create, remove, addMember,
+ * removeMember }`. Reads require `groups.read:*`; mutations require
+ * `groups.write:*`. Same X-Widget-Scopes + SystemAcl gating as `useUsers`.
+ */
+export function useGroups(query) {
+  const ctx = useWidgetContextOrThrow("useGroups");
+  if (!ctx.groups || typeof ctx.groups.listGroups !== "function") {
+    throw new Error("useGroups: host did not inject a groups client");
+  }
+  const [groups, setGroups] = useState([]);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState(null);
+
+  const queryRef = useRef(query);
+  const groupsRef = useRef(ctx.groups);
+  queryRef.current = query;
+  groupsRef.current = ctx.groups;
+
+  const runRef = useRef(0);
+
+  const doFetch = useCallback(async () => {
+    const myRun = ++runRef.current;
+    setLoading(true);
+    setError(null);
+    try {
+      const rows = await groupsRef.current.listGroups(queryRef.current);
+      if (runRef.current !== myRun) return;
+      setGroups(Array.isArray(rows) ? rows : []);
+      setLoading(false);
+    } catch (err) {
+      if (runRef.current !== myRun) return;
+      setError(toDirectoryError(err));
+      setLoading(false);
+    }
+  }, []);
+
+  const queryKey = (() => {
+    try {
+      return JSON.stringify(query);
+    } catch (_e) {
+      return null;
+    }
+  })();
+  useEffect(() => {
+    doFetch();
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [queryKey]);
+
+  const refetch = useCallback(async () => {
+    await doFetch();
+  }, [doFetch]);
+
+  const create = useCallback(async (args) => {
+    try {
+      return await groupsRef.current.create(args);
+    } catch (err) {
+      throw toDirectoryError(err);
+    }
+  }, []);
+  const remove = useCallback(async (groupId) => {
+    try {
+      return await groupsRef.current.remove(groupId);
+    } catch (err) {
+      throw toDirectoryError(err);
+    }
+  }, []);
+  const addMember = useCallback(async (groupId, userId) => {
+    try {
+      return await groupsRef.current.addMember(groupId, userId);
+    } catch (err) {
+      throw toDirectoryError(err);
+    }
+  }, []);
+  const removeMember = useCallback(async (groupId, userId) => {
+    try {
+      return await groupsRef.current.removeMember(groupId, userId);
+    } catch (err) {
+      throw toDirectoryError(err);
+    }
+  }, []);
+
+  return { groups, loading, error, refetch, create, remove, addMember, removeMember };
+}
+
 export function useI18n() {
   const ctx = useWidgetContextOrThrow("useI18n");
   const i18n = ctx.i18n || {};

package/dist/icon.js

@@ -0,0 +1,29 @@
+// REQ-WSDK-PLATFORM §6 — `<Icon>` SDK primitive.
+//
+// Wraps lucide-react-native's name-keyed component map behind a small
+// stable API: `<Icon name="check" size={16} color="..." />`. Same source
+// runs on both platforms — lucide-react-native ships a working web build
+// (via the host's Vite shim) and a native build (Metro picks it
+// straight). Unknown names fall back to the `Square` glyph so the
+// canvas always shows something visible.
+//
+// The built-in `Icon` widget at frontend/src/components/widgets/Icon/
+// already implements this exact pattern. Marketplace widgets reach for
+// the SDK primitive instead of importing lucide-react-native directly,
+// keeping the import-surface of a typical widget small (and avoiding the
+// `import * as LucideIcons` pattern which trips eslint's
+// no-restricted-syntax in some configs).
+
+import React from "react";
+import * as LucideIcons from "lucide-react-native";
+
+export function Icon({ name, size, color }) {
+  const candidate =
+    typeof name === "string" && name.length > 0 ? LucideIcons[name] : null;
+  const Component = candidate || LucideIcons.Square;
+  const pixelSize = Number.isFinite(size) && size > 0 ? size : 24;
+  return React.createElement(Component, {
+    size: pixelSize,
+    color: color || "#0f172a",
+  });
+}

package/dist/index.d.ts

@@ -28,6 +28,9 @@ export type WidgetPropertyType =
   | "tableRef"
   | "columnRef"
   | "recordBinding"
+  // REQ-USERMGMT M4 / §4.8: Group picker that emits a bare
+  // AppUserGroup UUID into the page JSON.
+  | "groupRef"
   | "expression"
   | "eventBinding"
   | "object"
@@ -480,6 +483,109 @@ export class DatastoreError extends Error {
   );
 }
 
+/**
+ * REQ-USERMGMT / REQ-ACL-SYS M3 — error class thrown by `useUsers` and
+ * `useGroups` callbacks. The `code` is a stable categorisation widgets
+ * can branch on.
+ */
+export class DirectoryError extends Error {
+  code:
+    | "FORBIDDEN"
+    | "VALIDATION"
+    | "NOT_FOUND"
+    | "INVITE_ONLY"
+    | "INTERNAL";
+  constructor(
+    code: DirectoryError["code"],
+    message: string,
+    opts?: { cause?: unknown },
+  );
+}
+
+// --------------------------------------------------------------- useUsers
+//
+// REQ-USERMGMT / REQ-ACL-SYS M3 — AppUser administration hook.
+
+export interface AppUserRow {
+  id: string;
+  name: string;
+  email?: string;
+  role: "USER" | "INTEGRATION";
+  isActive: boolean;
+}
+
+export interface UsersQuery {
+  q?: string;
+  role?: "USER" | "INTEGRATION" | "ALL";
+  isActive?: boolean;
+  limit?: number;
+  offset?: number;
+}
+
+export interface InviteArgs {
+  email: string;
+  name?: string;
+  groupIds?: string[];
+}
+
+export interface AppUserInviteRow {
+  id: string;
+  email: string;
+  status: string;
+  invitedAt?: string;
+  expiresAt?: string;
+}
+
+export interface UsersApi {
+  users: AppUserRow[];
+  loading: boolean;
+  error: DirectoryError | null;
+  refetch(): Promise<void>;
+  invite(args: InviteArgs): Promise<AppUserInviteRow>;
+  deactivate(userId: string): Promise<AppUserRow>;
+  reactivate(userId: string): Promise<AppUserRow>;
+  remove(userId: string): Promise<void>;
+}
+
+/**
+ * AppUser administration. Reads require the `users.read:*` scope in the
+ * manifest; mutations additionally require `users.write:*`. Widgets that
+ * declare the scopes but whose calling APP_USER lacks the corresponding
+ * SystemAcl `users.*` capability grant get a `FORBIDDEN` DirectoryError.
+ */
+export function useUsers(query?: UsersQuery): UsersApi;
+
+// --------------------------------------------------------------- useGroups
+
+export interface AppUserGroupRow {
+  id: string;
+  name: string;
+  memberCount?: number;
+}
+
+export interface GroupsQuery {
+  q?: string;
+  limit?: number;
+  offset?: number;
+}
+
+export interface GroupsApi {
+  groups: AppUserGroupRow[];
+  loading: boolean;
+  error: DirectoryError | null;
+  refetch(): Promise<void>;
+  create(args: { name: string }): Promise<AppUserGroupRow>;
+  remove(groupId: string): Promise<void>;
+  addMember(groupId: string, userId: string): Promise<void>;
+  removeMember(groupId: string, userId: string): Promise<void>;
+}
+
+/**
+ * AppUserGroup administration. Reads require `groups.read:*`; mutations
+ * require `groups.write:*`. Same SystemAcl gating as `useUsers`.
+ */
+export function useGroups(query?: GroupsQuery): GroupsApi;
+
 export function WidgetContextProvider(props: {
   value: WidgetContext;
   children?: ReactNode;
@@ -501,9 +607,29 @@ export const ActivityIndicator: any;
 export const Switch: any;
 export const StyleSheet: any;
 
+/**
+ * REQ-WSDK-PLATFORM §6 — Lucide icon primitive. Unknown names fall back
+ * to the `Square` glyph so the canvas always shows something visible.
+ *
+ * @example
+ *   import { Icon } from '@colixsystems/widget-sdk';
+ *   <Icon name="check" size={16} color={theme.colors.primary} />
+ */
+export const Icon: (props: {
+  name?: string;
+  size?: number;
+  color?: string;
+}) => any;
+
 // Linter
 export interface LintFinding {
   rule: string;
+  /**
+   * REQ-WSDK-PLATFORM update: findings can now carry a `severity`. The
+   * lint's `ok` flag is true iff no `severity: "error"` finding exists.
+   * `severity: "warning"` findings surface to reviewers but do not block.
+   */
+  severity?: "error" | "warning";
   label: string;
   line: number;
   snippet: string;

package/dist/index.js

@@ -9,11 +9,14 @@ export {
   WidgetContextProvider,
   DatastoreError,
   PaymentError,
+  DirectoryError,
   useDatastoreQuery,
   useDatastoreRecord,
   useFile,
   useDatastoreMutation,
   useDirectory,
+  useUsers,
+  useGroups,
   useWidgetEvent,
   usePayments,
   useTheme,
@@ -23,6 +26,11 @@ export {
   useChildRenderer,
   WidgetTree,
 } from "./hooks.js";
+// REQ-WSDK-PLATFORM §6 — Tier A hooks. Each ships in a per-platform file
+// (./clipboard.js / .native.js, ./toast.js / .native.js); index.js picks
+// the web variant and index.native.js picks the native variant.
+export { useClipboard, ClipboardError } from "./clipboard.js";
+export { useToast } from "./toast.js";
 export {
   Text,
   View,
@@ -36,6 +44,8 @@ export {
   Switch,
   StyleSheet,
   Linking,
+  Icon,
+  DateTimePicker,
 } from "./primitives.js";
 export { lintSource, bannedIdentifiers } from "./linter.js";
 export { CONTRACT, isHookAllowed, requiredContextKeys } from "./contract.js";

package/dist/index.native.js

@@ -9,11 +9,14 @@ export {
   WidgetContextProvider,
   DatastoreError,
   PaymentError,
+  DirectoryError,
   useDatastoreQuery,
   useDatastoreRecord,
   useFile,
   useDatastoreMutation,
   useDirectory,
+  useUsers,
+  useGroups,
   useWidgetEvent,
   usePayments,
   useTheme,
@@ -23,6 +26,9 @@ export {
   useChildRenderer,
   WidgetTree,
 } from "./hooks.js";
+// REQ-WSDK-PLATFORM §6 — Tier A hooks (native variants).
+export { useClipboard, ClipboardError } from "./clipboard.native.js";
+export { useToast } from "./toast.native.js";
 export {
   Text,
   View,
@@ -36,6 +42,8 @@ export {
   Switch,
   StyleSheet,
   Linking,
+  Icon,
+  DateTimePicker,
 } from "./primitives.native.js";
 export { lintSource, bannedIdentifiers } from "./linter.js";
 export { CONTRACT, isHookAllowed, requiredContextKeys } from "./contract.js";