@colixsystems/widget-sdk 0.13.0 → 0.15.0

package/dist/contract.js

@@ -171,6 +171,112 @@ const HOOKS = [
     requiredContextSlice: ["payments.requestPayment"],
     scopes: ["payments.charge:appUser"],
   },
+  // REQ-USERMGMT / REQ-ACL-SYS M3 — AppUser administration. Returns
+  // `{ users, loading, error, refetch, invite, deactivate, reactivate, remove }`.
+  // Reads need `users.read:*` scope; mutations additionally need
+  // `users.write:*`. The `invite` call accepts `{ email, name, groupIds? }`
+  // and returns the resulting AppUserInvite row (the email is sent by the
+  // host). Mutating users from a widget requires the corresponding
+  // SystemAcl `users.write` capability grant in the tenant; widgets that
+  // only call read methods need only `users.read:*`.
+  {
+    name: "useUsers",
+    signature: "useUsers(query?)",
+    description:
+      "AppUser administration. Returns { users, loading, error, refetch, invite, " +
+      "deactivate, reactivate, remove }. Reads need users.read:* scope; mutations " +
+      "need users.write:*. The `invite` call accepts { email, name, groupIds? } " +
+      "and returns the resulting AppUserInvite row (the email is sent by the host).",
+    returnShape: {
+      users: "Array<{ id, name, email?, role, isActive }>",
+      loading: "boolean",
+      error: "DirectoryError | null",
+      refetch: "() => Promise<void>",
+      invite:
+        "({ email, name, groupIds? }) => Promise<Invite>  // rejects with DirectoryError",
+      deactivate: "(userId) => Promise<User>  // rejects with DirectoryError",
+      reactivate: "(userId) => Promise<User>  // rejects with DirectoryError",
+      remove: "(userId) => Promise<void>  // rejects with DirectoryError",
+    },
+    requiredContextSlice: [
+      "users.listUsers",
+      "users.invite",
+      "users.deactivate",
+      "users.reactivate",
+      "users.remove",
+    ],
+    scopes: ["users.read:*"],
+  },
+  // REQ-USERMGMT / REQ-ACL-SYS M3 — AppUserGroup administration. Returns
+  // `{ groups, loading, error, refetch, create, remove, addMember, removeMember }`.
+  // Reads need `groups.read:*`; mutations need `groups.write:*`. Removing a
+  // member requires the corresponding `users.write` capability since it
+  // affects the user's effective access.
+  {
+    name: "useGroups",
+    signature: "useGroups(query?)",
+    description:
+      "AppUserGroup administration. Returns { groups, loading, error, refetch, " +
+      "create, remove, addMember, removeMember }. Reads need groups.read:*; " +
+      "mutations need groups.write:*.",
+    returnShape: {
+      groups: "Array<{ id, name, memberCount }>",
+      loading: "boolean",
+      error: "DirectoryError | null",
+      refetch: "() => Promise<void>",
+      create:
+        "({ name }) => Promise<Group>  // rejects with DirectoryError",
+      remove: "(groupId) => Promise<void>  // rejects with DirectoryError",
+      addMember:
+        "(groupId, userId) => Promise<void>  // rejects with DirectoryError",
+      removeMember:
+        "(groupId, userId) => Promise<void>  // rejects with DirectoryError",
+    },
+    requiredContextSlice: [
+      "groups.listGroups",
+      "groups.create",
+      "groups.remove",
+      "groups.addMember",
+      "groups.removeMember",
+    ],
+    scopes: ["groups.read:*"],
+  },
+  // REQ-WSDK-PLATFORM §6 — Tier A SDK hooks.
+  {
+    name: "useClipboard",
+    signature: "useClipboard()",
+    description:
+      "Cross-platform clipboard access. Returns { copy, paste, hasContent }. " +
+      "All methods return Promises; rejections surface a structured ClipboardError " +
+      "with .code in PERMISSION_DENIED | INTERNAL. On web the browser may " +
+      "require a user gesture for read access — surface the error to the " +
+      "user as a 'try again after clicking' prompt when code === PERMISSION_DENIED.",
+    returnShape: {
+      copy:
+        "(text: string) => Promise<void>  // rejects with ClipboardError",
+      paste:
+        "() => Promise<string>  // rejects with ClipboardError",
+      hasContent: "() => Promise<boolean>  // best-effort, never throws",
+    },
+    requiredContextSlice: [],
+    scopes: null,
+  },
+  {
+    name: "useToast",
+    signature: "useToast()",
+    description:
+      "Surfaces a short auto-dismissing notification. Returns { showToast }. " +
+      "showToast({ kind: 'success' | 'error' | 'info' | 'warning', message }) " +
+      "asks the host to render a workspace-themed toast. If the host hasn't " +
+      "wired a renderer, the web variant dispatches an 'appstudio:widget-toast' " +
+      "CustomEvent on window; native logs to the console. The widget never " +
+      "owns the toast UI — that's the host's responsibility.",
+    returnShape: {
+      showToast: "({ kind, message }) => void",
+    },
+    requiredContextSlice: ["toast.showToast"],
+    scopes: null,
+  },
 ];
 
 // REQ-WSDK-RN-WEB: see contract.cjs for the source-of-truth comment.
@@ -259,6 +365,22 @@ const PRIMITIVES = [
     rnComponent: "Linking",
     docsUrl: "https://reactnative.dev/docs/linking",
   },
+  // REQ-WSDK-PLATFORM §6 — Tier A SDK primitive.
+  {
+    name: "Icon",
+    description:
+      'Lucide icon. `<Icon name="check" size={16} color="..." />`. Unknown names render the Square fallback so the canvas always shows something visible. Names are the lucide icon ids (`https://lucide.dev/icons`). Works on both web and native.',
+    rnComponent: "lucide-react-native",
+    docsUrl: "https://lucide.dev/icons",
+  },
+  // REQ-WSDK-PLATFORM §6 — Tier A SDK primitive.
+  {
+    name: "DateTimePicker",
+    description:
+      'Cross-platform date / time / datetime picker. `<DateTimePicker value={iso} onChange={iso => …} mode="date" | "time" | "datetime" />`. The value prop and the onChange callback both speak ISO 8601 strings (the datastore wire format) — authors never round-trip through `new Date()`. Web renders the browser\'s native input via react-native-web; native uses @react-native-community/datetimepicker.',
+    rnComponent: "@react-native-community/datetimepicker",
+    docsUrl: "https://github.com/react-native-datetimepicker/datetimepicker",
+  },
 ];
 
 const CATEGORIES = [
@@ -427,6 +549,38 @@ const WIDGET_CONTEXT_SHAPE = {
     required: true,
     fields: { requestPayment: "function", getPayment: "function" },
   },
+  // REQ-USERMGMT / REQ-ACL-SYS M3 — AppUser administration facade backing
+  // useUsers(). Reads gated by `users.read:*`; mutations by `users.write:*`.
+  // The host signs an `X-Widget-Scopes` header against JWT_SECRET so an
+  // APP_USER cannot forge scope claims, and the request is additionally
+  // gated by a SystemAcl `users.read` / `users.write` capability grant.
+  users: {
+    description:
+      "AppUser administration. { listUsers(query?) -> Promise<User[]>, invite({ email, name, groupIds? }) -> Promise<Invite>, deactivate(userId) -> Promise<User>, reactivate(userId) -> Promise<User>, remove(userId) -> Promise<void> }. Backs useUsers(); reads require users.read:*, mutations require users.write:*.",
+    required: true,
+    fields: {
+      listUsers: "function",
+      invite: "function",
+      deactivate: "function",
+      reactivate: "function",
+      remove: "function",
+    },
+  },
+  // REQ-USERMGMT / REQ-ACL-SYS M3 — AppUserGroup administration facade
+  // backing useGroups(). Reads gated by `groups.read:*`; mutations by
+  // `groups.write:*`. Same X-Widget-Scopes + SystemAcl gating as users.
+  groups: {
+    description:
+      "AppUserGroup administration. { listGroups(query?) -> Promise<Group[]>, create({ name }) -> Promise<Group>, remove(groupId) -> Promise<void>, addMember(groupId, userId) -> Promise<void>, removeMember(groupId, userId) -> Promise<void> }. Backs useGroups(); reads require groups.read:*, mutations require groups.write:*.",
+    required: true,
+    fields: {
+      listGroups: "function",
+      create: "function",
+      remove: "function",
+      addMember: "function",
+      removeMember: "function",
+    },
+  },
   i18n: {
     description: "{ t(key, fallback?), locale }.",
     required: true,
@@ -443,6 +597,20 @@ const WIDGET_CONTEXT_SHAPE = {
       error: "function",
     },
   },
+  // REQ-WSDK-PLATFORM §6 — backs useToast(). The host installs its own
+  // workspace-themed toast renderer here; if omitted, the SDK's useToast
+  // hook falls back to a CustomEvent on web / console.log on native so
+  // widget code still runs without a host integration.
+  toast: {
+    description:
+      "Optional host toast slot. { showToast({ kind, message }): void }. " +
+      "The host populates this to render workspace-themed notifications " +
+      "from any widget that calls useToast(). When omitted the SDK falls " +
+      "back to dispatching an 'appstudio:widget-toast' CustomEvent on web " +
+      "and console.log on native.",
+    required: false,
+    fields: { showToast: "function" },
+  },
 };
 
 const BUNDLE_EXPORT_CONTRACT = [
@@ -465,6 +633,9 @@ const BUNDLE_EXPORT_CONTRACT = [
   },
 ];
 
+// REQ-WSDK-PLATFORM (docs/design/req-widget-sdk-cross-platform-primitives.md
+// §3.5, §8): `fetch` and `XMLHttpRequest` are NOT banned. See contract.cjs
+// for the source-of-truth comment.
 const BANNED_APIS = [
   { identifier: "eval", reason: "Arbitrary code evaluation." },
   {
@@ -493,21 +664,119 @@ const BANNED_APIS = [
     reason: "Same reason as localStorage.",
   },
   {
-    identifier: "fetch",
-    reason: "Direct network calls bypass the datastore client + tenant auth.",
+    identifier: "import(",
+    reason: "Dynamic import bypasses the loader's allowlist.",
   },
+  { identifier: "globalThis", reason: "Host environment escape." },
+];
+
+// REQ-WSDK-PLATFORM §3.4, §5: vetted package allowlist. See contract.cjs
+// for the source-of-truth comment.
+const VETTED_IMPORTS = [
   {
-    identifier: "XMLHttpRequest",
-    reason: "Direct network calls bypass the datastore client + tenant auth.",
+    specifier: "react",
+    platforms: ["web", "native"],
+    category: "core",
+    description: "React. Hooks, JSX, lifecycle. Unchanged.",
   },
   {
-    identifier: "import(",
-    reason: "Dynamic import bypasses the loader's allowlist.",
+    specifier: "@colixsystems/widget-sdk",
+    platforms: ["web", "native"],
+    category: "core",
+    description:
+      "The AppStudio widget SDK — primitives, hooks, manifest helpers. Unchanged.",
+  },
+  {
+    specifier: "react-native",
+    platforms: ["web", "native"],
+    category: "primitive",
+    description:
+      "Direct RN imports for APIs the SDK hasn't re-exported yet. On web the host bundler aliases this to react-native-web; on native Metro resolves the real library.",
+  },
+  {
+    specifier: "axios",
+    platforms: ["web", "native"],
+    category: "network",
+    description:
+      "HTTP client for third-party APIs. Calls to the host's /api/* surface are blocked at runtime — widgets get no JWT token, so use SDK hooks for workspace data.",
+  },
+  {
+    specifier: "date-fns",
+    platforms: ["web", "native"],
+    category: "utility",
+    description: "Pure-JS date math. Works on both platforms unchanged.",
+  },
+  {
+    specifier: "react-native-svg",
+    platforms: ["web", "native"],
+    category: "drawing",
+    description:
+      "Cross-platform SVG drawing primitives. Used by the built-in Chart widget; works on both platforms.",
+  },
+  {
+    specifier: "lucide-react-native",
+    platforms: ["web", "native"],
+    category: "iconography",
+    description:
+      "Lucide icon set as React components. Used by the built-in Icon widget; works on both platforms.",
+  },
+  {
+    specifier: "react-native-maps",
+    platforms: ["native"],
+    category: "geo",
+    description:
+      "Native map view + markers. Native-only; pair with leaflet/react-leaflet in widget.web.jsx for a web variant.",
+  },
+  {
+    specifier: "leaflet",
+    platforms: ["web"],
+    category: "geo",
+    description:
+      "Web-only mapping library. Use alongside react-leaflet in widget.web.jsx as the web counterpart to react-native-maps.",
+  },
+  {
+    specifier: "react-leaflet",
+    platforms: ["web"],
+    category: "geo",
+    description: "React bindings for leaflet. Web-only.",
+  },
+  {
+    specifier: "expo-av",
+    platforms: ["native"],
+    category: "media",
+    description:
+      "Native audio + video playback. Native-only; pair with browser <audio>/<video> in widget.web.jsx.",
+  },
+  {
+    specifier: "@react-native-community/datetimepicker",
+    platforms: ["native"],
+    category: "input",
+    description:
+      "Native date/time picker. The SDK's <DateTimePicker> primitive already wraps this; reach for it directly only if you need RN-specific options.",
+  },
+  {
+    specifier: "expo-clipboard",
+    platforms: ["native"],
+    category: "system",
+    description:
+      "Native clipboard. The SDK's useClipboard() hook already wraps this; reach for it directly only if you need RN-specific options.",
+  },
+  {
+    specifier: "expo-haptics",
+    platforms: ["native"],
+    category: "system",
+    description:
+      "Native haptic feedback. Pair with navigator.vibrate in widget.web.jsx.",
   },
-  { identifier: "globalThis", reason: "Host environment escape." },
 ];
 
-const ALLOWED_BARE_IMPORTS = ["react", "@colixsystems/widget-sdk"];
+const ALLOWED_BARE_IMPORTS = VETTED_IMPORTS.map((v) => v.specifier);
+
+const HOST_API_URL_PATTERNS = [
+  "/api/v1",
+  "/uploads/",
+  "Authorization: Bearer",
+];
 
 function deepFreeze(value) {
   if (value === null || typeof value !== "object") return value;
@@ -517,7 +786,7 @@ function deepFreeze(value) {
 }
 
 const CONTRACT = deepFreeze({
-  version: "1.2.0",
+  version: "1.5.0",
   hooks: HOOKS,
   primitives: PRIMITIVES,
   manifestSchema: MANIFEST_SCHEMA,
@@ -527,7 +796,9 @@ const CONTRACT = deepFreeze({
   widgetContextShape: WIDGET_CONTEXT_SHAPE,
   bundleExportContract: BUNDLE_EXPORT_CONTRACT,
   bannedApis: BANNED_APIS,
+  vettedImports: VETTED_IMPORTS,
   allowedBareImports: ALLOWED_BARE_IMPORTS,
+  hostApiUrlPatterns: HOST_API_URL_PATTERNS,
 });
 
 function isHookAllowed(name) {

package/dist/datetimepicker.js

@@ -0,0 +1,102 @@
+// REQ-WSDK-PLATFORM §6 — `<DateTimePicker>` SDK primitive.
+//
+// Cross-platform date / time / datetime picker. Wraps
+// `@react-native-community/datetimepicker` (works on both web and native:
+// on web it renders the browser's native `<input type="date|time">`
+// surface through react-native-web's mapping). The wire format is ISO
+// 8601 strings — the same format the datastore speaks, so widget authors
+// never round-trip through `new Date()`.
+//
+// Props:
+//   value: string | null   — ISO 8601 (`2026-05-28` for date mode,
+//                            `2026-05-28T14:30:00.000Z` for datetime).
+//                            `null` defaults to "now".
+//   onChange: (iso: string) => void
+//   mode:    "date" | "time" | "datetime"  — default "date"
+//   minimumDate / maximumDate: string | null  — ISO bounds
+//   disabled: boolean
+//
+// The author writes:
+//   const [day, setDay] = useState(null);
+//   <DateTimePicker value={day} onChange={setDay} mode="date" />
+//
+// …and `day` ends up as an ISO string suitable for storing directly into
+// a DATE column. The previous pattern of importing the RN library
+// directly and managing `Date` objects in widget state is gone — the
+// primitive normalizes both ends.
+
+import React, { useMemo } from "react";
+// eslint-disable-next-line no-restricted-syntax
+import RNDateTimePicker from "@react-native-community/datetimepicker";
+
+function _parseToDate(value) {
+  if (value == null || value === "") return new Date();
+  if (value instanceof Date) return Number.isNaN(value.getTime()) ? new Date() : value;
+  if (typeof value === "string") {
+    const d = new Date(value);
+    return Number.isNaN(d.getTime()) ? new Date() : d;
+  }
+  return new Date();
+}
+
+function _formatToIso(date, mode) {
+  if (!(date instanceof Date) || Number.isNaN(date.getTime())) return null;
+  if (mode === "date") {
+    // Local-date ISO (yyyy-mm-dd) — calendar dates should be timezone-free
+    // so a "May 28" picked in Stockholm doesn't read as "May 27" in NYC.
+    const y = date.getFullYear();
+    const m = String(date.getMonth() + 1).padStart(2, "0");
+    const d = String(date.getDate()).padStart(2, "0");
+    return `${y}-${m}-${d}`;
+  }
+  if (mode === "time") {
+    // Local-time ISO (hh:mm) — time-of-day is timezone-free for the same
+    // reason. Authors who want a full datetime get mode="datetime".
+    const h = String(date.getHours()).padStart(2, "0");
+    const mm = String(date.getMinutes()).padStart(2, "0");
+    return `${h}:${mm}`;
+  }
+  // datetime — full UTC ISO so the wire format round-trips through the
+  // datastore's DATE column unchanged.
+  return date.toISOString();
+}
+
+export function DateTimePicker({
+  value,
+  onChange,
+  mode,
+  minimumDate,
+  maximumDate,
+  disabled,
+}) {
+  const effectiveMode = mode === "time" || mode === "datetime" ? mode : "date";
+  const dateValue = useMemo(() => _parseToDate(value), [value]);
+  const min = useMemo(
+    () => (minimumDate ? _parseToDate(minimumDate) : undefined),
+    [minimumDate],
+  );
+  const max = useMemo(
+    () => (maximumDate ? _parseToDate(maximumDate) : undefined),
+    [maximumDate],
+  );
+
+  const handleChange = (_event, picked) => {
+    if (typeof onChange !== "function") return;
+    if (!(picked instanceof Date)) return;
+    const iso = _formatToIso(picked, effectiveMode);
+    if (iso != null) onChange(iso);
+  };
+
+  // The RN library's `mode` accepts "date" / "time"; for "datetime" we
+  // ask for "datetime" on iOS / Android and let the picker's
+  // implementation handle it. react-native-web's mapping interprets
+  // "datetime" as `<input type="datetime-local">`.
+  return React.createElement(RNDateTimePicker, {
+    value: dateValue,
+    mode: effectiveMode,
+    minimumDate: min,
+    maximumDate: max,
+    disabled: !!disabled,
+    onChange: handleChange,
+  });
+}