@colixsystems/widget-sdk 0.14.1 → 0.15.0

package/dist/linter.js

@@ -57,18 +57,19 @@ const CONTRACT_RULES = CONTRACT.bannedApis.map((b) =>
 
 // Extra rules that don't map 1:1 to a banned identifier in the contract:
 // host-internal imports that widgets must never touch.
+//
+// REQ-WSDK-PLATFORM: `no-axios-import` is GONE. axios is on the vetted
+// import list now (`CONTRACT.vettedImports`) — widgets may call third-party
+// APIs directly. Calls to the host's own /api/* surface are blocked at
+// runtime by the WidgetContextProvider's network gate; the soft
+// `no-host-api-url` rule below flags obvious host-URL substrings so
+// authors learn the rule statically.
 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];
@@ -83,6 +84,158 @@ export function bannedIdentifiers() {
   return CONTRACT.bannedApis.map((b) => b.identifier);
 }
 
+// REQ-WSDK-PLATFORM §3.4, §8: scan the source for every bare import
+// specifier and validate it against `CONTRACT.vettedImports`.
+//
+// Recognised forms (string-level, no AST):
+//   import X from "spec"
+//   import { … } from "spec"
+//   import * as X from "spec"
+//   import "spec"
+//   const X = require("spec")  // CJS — for completeness
+//
+// Relative imports within the bundle (`./foo.js`, `./shared/util.js`) are
+// allowed — REQ-WSDK-PLATFORM §4.2 lets a split-impl widget share helpers
+// between `widget.web.jsx` and `widget.native.jsx`. Parent-directory
+// (`../`) and absolute (`/`, `http(s):`) paths are rejected to keep the
+// bundle scope sealed.
+const IMPORT_SPECIFIER_RE =
+  /(?:^|[\s;])(?:import(?:\s+[^"';]+from)?|require)\s*\(?\s*['"]([^'"]+)['"]/g;
+
+function _classifySpecifier(spec) {
+  if (
+    spec.startsWith("./") ||
+    (spec.startsWith(".") && !spec.startsWith(".."))
+  ) {
+    return "relative-ok";
+  }
+  if (spec.startsWith("../")) return "relative-escape";
+  if (
+    spec.startsWith("/") ||
+    spec.startsWith("http:") ||
+    spec.startsWith("https:") ||
+    spec.startsWith("blob:") ||
+    spec.startsWith("data:")
+  ) {
+    return "absolute";
+  }
+  return "bare";
+}
+
+function _importRules(source, manifest) {
+  const findings = [];
+  const allowed = new Map(
+    CONTRACT.vettedImports.map((v) => [v.specifier, v]),
+  );
+  // Track declared `supportedPlatforms` so a widget that claims "web only"
+  // doesn't import a native-only package (and vice versa) without the
+  // marketplace listing being honest about which platforms ship.
+  const declaredPlatforms =
+    manifest &&
+    Array.isArray(manifest.supportedPlatforms) &&
+    manifest.supportedPlatforms.length > 0
+      ? new Set(manifest.supportedPlatforms)
+      : null;
+
+  const lines = source.split(/\r?\n/);
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i];
+    // Reset lastIndex — the regex is /g and shared across lines.
+    IMPORT_SPECIFIER_RE.lastIndex = 0;
+    let m;
+    while ((m = IMPORT_SPECIFIER_RE.exec(line))) {
+      const spec = m[1];
+      const kind = _classifySpecifier(spec);
+      if (kind === "relative-ok") continue;
+      if (kind === "relative-escape") {
+        findings.push({
+          rule: "no-parent-relative-import",
+          label: `relative import "${spec}" escapes the bundle (\`../\`) — only sibling-file imports (\`./foo.js\`) are allowed`,
+          line: i + 1,
+          snippet: line.trim().slice(0, 200),
+        });
+        continue;
+      }
+      if (kind === "absolute") {
+        findings.push({
+          rule: "no-absolute-import",
+          label: `absolute import "${spec}" is not allowed — use a vetted bare specifier or a sibling-file (\`./foo.js\`) import`,
+          line: i + 1,
+          snippet: line.trim().slice(0, 200),
+        });
+        continue;
+      }
+      // Bare specifier — validate against the vetted list.
+      const entry = allowed.get(spec);
+      if (!entry) {
+        findings.push({
+          rule: "import-not-vetted",
+          label:
+            `import "${spec}" is not on the vetted package list — see ` +
+            `CONTRACT.vettedImports for the current set or open a request to add it`,
+          line: i + 1,
+          snippet: line.trim().slice(0, 200),
+        });
+        continue;
+      }
+      // If the manifest declares supportedPlatforms, every imported
+      // specifier must support every declared platform. A widget that
+      // imports react-native-maps (native-only) cannot honestly claim
+      // supportedPlatforms: ["web", "native"] from a single source file —
+      // it must either drop "web" from the manifest, OR move that import
+      // into widget.native.jsx so the web bundle doesn't see it.
+      if (declaredPlatforms) {
+        for (const wanted of declaredPlatforms) {
+          if (!entry.platforms.includes(wanted)) {
+            findings.push({
+              rule: "import-platform-mismatch",
+              label:
+                `"${spec}" supports [${entry.platforms.join(", ")}] but the ` +
+                `manifest claims supportedPlatforms includes "${wanted}". ` +
+                `Move this import into widget.${wanted === "web" ? "native" : "web"}.jsx, ` +
+                `or drop "${wanted}" from manifest.supportedPlatforms.`,
+              line: i + 1,
+              snippet: line.trim().slice(0, 200),
+            });
+          }
+        }
+      }
+    }
+  }
+  return findings;
+}
+
+// REQ-WSDK-PLATFORM §3.5: soft warning when source contains host-API URL
+// substrings. NOT a hard block — false positives are possible (a widget
+// that happens to call a third-party API also located at `/api`). The
+// marketplace review queue surfaces the warning for a human pass.
+function _hostApiUrlRules(source) {
+  const findings = [];
+  const patterns = CONTRACT.hostApiUrlPatterns || [];
+  const lines = source.split(/\r?\n/);
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i];
+    for (const needle of patterns) {
+      if (line.includes(needle)) {
+        findings.push({
+          rule: "no-host-api-url",
+          severity: "warning",
+          label:
+            `source contains "${needle}" — calls to the AppStudio host API ` +
+            `are blocked at runtime (widgets get no JWT token). Use SDK ` +
+            `hooks for workspace data; \`axios\`/\`fetch\` for third-party APIs.`,
+          line: i + 1,
+          snippet: line.trim().slice(0, 200),
+        });
+        // Only fire once per line — repeated needle hits on the same line
+        // are noise.
+        break;
+      }
+    }
+  }
+  return findings;
+}
+
 // REQ-USERMGMT / REQ-ACL-SYS M3 — scope-required-for-user-mutation.
 //
 // A widget that calls `useUsers().invite()` / `.deactivate()` /
@@ -197,18 +350,29 @@ function _scopeRules(source, manifest) {
 /**
  * Lint a JavaScript source string.
  *
+ * REQ-WSDK-PLATFORM update: findings can now carry a `severity` field
+ * (`"error"` | `"warning"`). The `ok` flag is true iff NO `severity:
+ * "error"` finding exists — warnings (currently just `no-host-api-url`)
+ * surface to the reviewer but do not block publish. Findings without an
+ * explicit `severity` are treated as errors for back-compat with existing
+ * rules.
+ *
  * @param {string} source
- * @param {{ manifest?: { requestedScopes?: string[] } }} [options] — when a
- *   manifest is supplied, scope-aware rules also fire (see
- *   `scope-required-for-user-mutation`).
- * @returns {{ ok: boolean, findings: Array<{ rule: string, label: string, line: number, snippet: string }> }}
+ * @param {{ manifest?: { requestedScopes?: string[], supportedPlatforms?: string[] } }} [options]
+ * @returns {{ ok: boolean, findings: Array<{ rule: string, severity?: "error" | "warning", label: string, line: number, snippet: string }> }}
  */
 export function lintSource(source, options) {
   if (typeof source !== "string") {
     return {
       ok: false,
       findings: [
-        { rule: "input", label: "source must be a string", line: 0, snippet: "" },
+        {
+          rule: "input",
+          severity: "error",
+          label: "source must be a string",
+          line: 0,
+          snippet: "",
+        },
       ],
     };
   }
@@ -220,6 +384,7 @@ export function lintSource(source, options) {
       if (rule.pattern.test(line)) {
         findings.push({
           rule: rule.id,
+          severity: "error",
           label: rule.label,
           line: i + 1,
           snippet: line.trim().slice(0, 200),
@@ -227,9 +392,24 @@ export function lintSource(source, options) {
       }
     }
   }
+  // REQ-WSDK-PLATFORM §3.4: import-specifier validation.
+  findings.push(
+    ..._importRules(source, options && options.manifest).map((f) => ({
+      ...f,
+      severity: f.severity || "error",
+    })),
+  );
+  // REQ-WSDK-PLATFORM §3.5: soft host-API URL warning (does not block).
+  findings.push(..._hostApiUrlRules(source));
   // REQ-USERMGMT / REQ-ACL-SYS M3 — scope-aware rules. Run after the
   // line-by-line scan so banned-identifier findings stay first in the
   // output.
-  findings.push(..._scopeRules(source, options && options.manifest));
-  return { ok: findings.length === 0, findings };
+  findings.push(
+    ..._scopeRules(source, options && options.manifest).map((f) => ({
+      ...f,
+      severity: f.severity || "error",
+    })),
+  );
+  const hasErrors = findings.some((f) => f.severity !== "warning");
+  return { ok: !hasErrors, findings };
 }

package/dist/primitives.js

@@ -60,3 +60,11 @@ export const StyleSheet = ReactNative.StyleSheet;
 // the OS hands it off to the system handler. `canOpenURL` reports whether
 // the URL scheme is registered.
 export const Linking = ReactNative.Linking;
+// REQ-WSDK-PLATFORM §6 — `<Icon>` wraps lucide-react-native. Same source
+// runs on both platforms; see ./icon.js.
+export { Icon } from "./icon.js";
+// REQ-WSDK-PLATFORM §6 — `<DateTimePicker>` wraps
+// @react-native-community/datetimepicker and normalizes its value to
+// ISO 8601 strings. Same source runs on both platforms; see
+// ./datetimepicker.js.
+export { DateTimePicker } from "./datetimepicker.js";

package/dist/primitives.native.js

@@ -20,3 +20,12 @@ export {
   StyleSheet,
   Linking,
 } from "react-native";
+
+// REQ-WSDK-PLATFORM §6 — `<Icon>` is implemented in one file that runs on
+// both platforms (lucide-react-native ships a working build for both).
+export { Icon } from "./icon.js";
+// REQ-WSDK-PLATFORM §6 — `<DateTimePicker>` ditto. The underlying
+// @react-native-community/datetimepicker handles its own
+// per-platform rendering; the SDK wrapper just normalizes the value
+// to ISO strings.
+export { DateTimePicker } from "./datetimepicker.js";

package/dist/toast.js

@@ -0,0 +1,73 @@
+// REQ-WSDK-PLATFORM §6 — `useToast()` hook (web implementation).
+//
+// Surfaces a short auto-dismissing notification. Widget API:
+//
+//   const { showToast } = useToast();
+//   showToast({ kind: "success" | "error" | "info" | "warning", message: "Saved" });
+//
+// Renderer resolution order:
+//   1. If the host provided `ctx.toast.showToast`, call that. The host
+//      owns positioning + theming.
+//   2. Otherwise: dispatch a CustomEvent named "appstudio:widget-toast"
+//      on the window with detail `{ kind, message }`. Hosts that want a
+//      central toast renderer install a `window.addEventListener` for it.
+//   3. As a last resort, `console.log` the toast so dev work surfaces
+//      something even before either of the above is wired.
+//
+// The SDK does NOT render any DOM itself — that responsibility belongs
+// to the host so a single workspace-themed toast component shows the
+// notifications across all widgets.
+
+import { useCallback } from "react";
+import { useWidgetContextOrThrow } from "./hooks.js";
+
+function _normalizeKind(kind) {
+  return kind === "success" || kind === "error" || kind === "warning"
+    ? kind
+    : "info";
+}
+
+export function useToast() {
+  const ctx = useWidgetContextOrThrow("useToast");
+  const hostToast =
+    ctx && ctx.toast && typeof ctx.toast.showToast === "function"
+      ? ctx.toast.showToast
+      : null;
+  const showToast = useCallback(
+    (payload) => {
+      const opts = payload && typeof payload === "object" ? payload : {};
+      const kind = _normalizeKind(opts.kind);
+      const message = typeof opts.message === "string" ? opts.message : "";
+      if (!message) return;
+      if (hostToast) {
+        try {
+          hostToast({ kind, message });
+          return;
+        } catch (err) {
+          // Fall through to the event + console fallback rather than
+          // crashing the widget.
+          if (typeof console !== "undefined" && console.warn) {
+            console.warn("[useToast] host toast handler threw:", err);
+          }
+        }
+      }
+      if (
+        typeof window !== "undefined" &&
+        typeof window.dispatchEvent === "function" &&
+        typeof CustomEvent === "function"
+      ) {
+        window.dispatchEvent(
+          new CustomEvent("appstudio:widget-toast", {
+            detail: { kind, message },
+          }),
+        );
+        return;
+      }
+      if (typeof console !== "undefined" && console.log) {
+        console.log(`[toast:${kind}] ${message}`);
+      }
+    },
+    [hostToast],
+  );
+  return { showToast };
+}

package/dist/toast.native.js

@@ -0,0 +1,46 @@
+// REQ-WSDK-PLATFORM §6 — `useToast()` hook (native implementation).
+//
+// Same API as the web counterpart (./toast.js). Native has no
+// `window.dispatchEvent` fallback — if the host doesn't provide
+// `ctx.toast.showToast`, the hook falls back to `console.log` so the
+// widget at least surfaces something during dev.
+
+import { useCallback } from "react";
+import { useWidgetContextOrThrow } from "./hooks.js";
+
+function _normalizeKind(kind) {
+  return kind === "success" || kind === "error" || kind === "warning"
+    ? kind
+    : "info";
+}
+
+export function useToast() {
+  const ctx = useWidgetContextOrThrow("useToast");
+  const hostToast =
+    ctx && ctx.toast && typeof ctx.toast.showToast === "function"
+      ? ctx.toast.showToast
+      : null;
+  const showToast = useCallback(
+    (payload) => {
+      const opts = payload && typeof payload === "object" ? payload : {};
+      const kind = _normalizeKind(opts.kind);
+      const message = typeof opts.message === "string" ? opts.message : "";
+      if (!message) return;
+      if (hostToast) {
+        try {
+          hostToast({ kind, message });
+          return;
+        } catch (err) {
+          if (typeof console !== "undefined" && console.warn) {
+            console.warn("[useToast] host toast handler threw:", err);
+          }
+        }
+      }
+      if (typeof console !== "undefined" && console.log) {
+        console.log(`[toast:${kind}] ${message}`);
+      }
+    },
+    [hostToast],
+  );
+  return { showToast };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.14.1",
+  "version": "0.15.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "type": "module",
   "main": "./dist/index.js",