@colixsystems/widget-sdk 0.86.0 → 0.87.0

package/dist/theme-components.js

@@ -90,6 +90,65 @@ export function normaliseThemeComponents(raw) {
   return out;
 }
 
+
+// REQ-THEME-ELEMENT: one value out of the per-widget map. Unlike a component
+// token, there is no declared `type` to coerce against -- the key space is the
+// workspace's widget catalog, not the contract -- so validation here is
+// STRUCTURAL. The authoritative type is the widget's own styleSchema, which the
+// Studio honours by only ever offering fields that widget declares.
+function coerceWidgetStyleValue(value) {
+  if (typeof value === "string") {
+    const trimmed = value.trim();
+    // Long enough for a hex, an enum value or a font name; short enough that a
+    // hand-edited theme_config cannot smuggle a payload into every widget.
+    return trimmed && trimmed.length <= 64 ? trimmed : undefined;
+  }
+  if (typeof value === "number") return Number.isFinite(value) ? value : undefined;
+  if (typeof value === "boolean") return value;
+  if (isPlainObject(value)) return normaliseComponentGradient(value) || undefined;
+  return undefined;
+}
+
+/**
+ * REQ-THEME-ELEMENT: validate `themeConfig.widgetStyles` -- app-wide style values
+ * keyed by WIDGET MANIFEST ID, then by that widget's own styleSchema field name.
+ *
+ * `normaliseThemeComponents` can iterate the CONTRACT because the scope vocabulary
+ * is closed. This map's key space is the workspace's widget catalog, so it must
+ * iterate the INPUT instead -- which is exactly why the bounds below exist:
+ * `theme_config` is an unbounded bag that an unauthenticated GET returns on every
+ * cold Player start and that the compiler bakes into the native export.
+ *
+ * Drops rather than throws, like every other theme validator: a hand-edited blob
+ * must degrade to less styling, never to a broken render.
+ */
+export function normaliseWidgetStyles(raw) {
+  if (!isPlainObject(raw)) return {};
+  const { maxWidgets, maxFieldsPerWidget } = CONTRACT.themeWidgetStyles;
+  const idPattern = CONTRACT.manifestSchema.id.pattern;
+  const out = {};
+  let widgets = 0;
+  for (const [manifestId, fields] of Object.entries(raw)) {
+    if (widgets >= maxWidgets) break;
+    if (!idPattern.test(manifestId) || !isPlainObject(fields)) continue;
+    const kept = {};
+    let count = 0;
+    for (const [field, value] of Object.entries(fields)) {
+      if (count >= maxFieldsPerWidget) break;
+      const coerced = coerceWidgetStyleValue(value);
+      if (coerced === undefined) continue;
+      kept[field] = coerced;
+      count += 1;
+    }
+    // An emptied entry is dropped rather than persisted as `{}`, mirroring
+    // normaliseThemeComponents.
+    if (count === 0) continue;
+    out[manifestId] = kept;
+    widgets += 1;
+  }
+  return out;
+}
+
 /**
  * The per-component style fields that apply to one widget, keyed by the
  * `styleSchema` field name the widget actually reads. A widget may sit in more
@@ -102,18 +161,50 @@ export function normaliseThemeComponents(raw) {
  *
  * @returns {Record<string, string|number>|null} null when nothing applies.
  */
-function componentStyleFor(manifestId, components) {
+function componentStyleFor(manifestId, components, styleSchema, widgetStyles) {
   if (typeof manifestId !== "string") return null;
   const validated = normaliseThemeComponents(components);
   const out = {};
   for (const [scope, definition] of Object.entries(CONTRACT.themeComponents)) {
     const tokens = validated[scope];
+    if (!tokens) continue;
+    // REQ-THEME-WIDGET: two bindings, in this order.
+    //
+    // `universalFields` binds by FIELD NAME and reaches every widget: a
+    // `cardBackground` can only mean a card surface, so a Mason-generated or
+    // marketplace widget that paints one follows "Cards" without appearing in
+    // any allowlist. A widget that does not read the field simply ignores an
+    // unused style prop, so this changes nothing for the ones that don't.
+    //
+    // `targets` stays the allowlist for the BARE names (`background`,
+    // `textColor`, `color`, `fontSize`, `shadow`), which are shared across
+    // scopes -- `appstudio.image` also reads `background`, and the button
+    // scope must not leak into it.
+    const declared = isPlainObject(styleSchema) ? styleSchema : null;
+    for (const [token, field] of Object.entries(definition.universalFields || {})) {
+      // Only onto a widget that DECLARES the field. Without this gate the token
+      // would land on every widget as an unused style prop -- harmless for one
+      // that reads named fields, but a widget spreading `props.style` onto a
+      // View would get an unknown style key. Built-ins thread no styleSchema and
+      // are covered by `targets` below, so their behaviour is unchanged.
+      if (!declared || declared[field] === undefined) continue;
+      if (tokens[token] !== undefined) out[field] = tokens[token];
+    }
     const fields = definition.targets[manifestId];
-    if (!tokens || !fields) continue;
+    if (!fields) continue;
     for (const [token, field] of Object.entries(fields)) {
       if (tokens[token] !== undefined) out[field] = tokens[token];
     }
   }
+  // REQ-THEME-ELEMENT: the per-WIDGET-TYPE values land last of the theme layers,
+  // so they beat both scope bindings -- naming one widget is strictly more
+  // specific than restyling a whole scope. The author's per-instance props.style
+  // is still spread after all of this by the caller.
+  //
+  // No styleSchema gate here, unlike universalFields above: the key IS this
+  // widget's manifest id, so the id match is the authorisation.
+  const perWidget = normaliseWidgetStyles(widgetStyles)[manifestId];
+  if (perWidget) Object.assign(out, perWidget);
   return Object.keys(out).length > 0 ? out : null;
 }
 
@@ -133,8 +224,13 @@ function componentStyleFor(manifestId, components) {
  * @param {object} props — the widget's resolved props (post-`resolveProps`).
  * @returns {object} props, with `style` folded when the theme applies.
  */
-export function applyThemeComponentStyle(manifestId, theme, props) {
-  const themed = componentStyleFor(manifestId, theme && theme.components);
+export function applyThemeComponentStyle(manifestId, theme, props, styleSchema) {
+  const themed = componentStyleFor(
+    manifestId,
+    theme && theme.components,
+    styleSchema,
+    theme && theme.widgetStyles,
+  );
   if (!themed) return props;
   const base = isPlainObject(props) ? props : {};
   const authored = isPlainObject(base.style) ? base.style : null;

package/dist/toast-host.js

@@ -0,0 +1,193 @@
+// REQ-WSDK-PLATFORM §6 — the HOST half of `useToast()`.
+//
+// `toast.js` / `toast.native.js` are the widget half: a widget calls
+// `showToast({ kind, message })` and the SDK forwards it to
+// `ctx.toast.showToast`. This module is what the host puts behind that slot —
+// the queue, the auto-dismiss timing, and the themed values the notification
+// is painted with.
+//
+// It is deliberately presentation-free. The web Player paints the stack with
+// DOM and the Expo export with React Native primitives; sharing everything
+// EXCEPT that JSX is what stops the two hosts from drifting (CLAUDE.md §8).
+
+export const TOAST_DEFAULTS = Object.freeze({
+  durationMs: 4000,
+  maxVisible: 3,
+});
+
+const KINDS = Object.freeze(["success", "error", "warning", "info"]);
+
+// `error` is the widget-facing kind; `danger` is the theme's colour role.
+const KIND_COLOR_ROLE = Object.freeze({
+  success: "success",
+  error: "danger",
+  warning: "warning",
+  info: "info",
+});
+
+export function normalizeToastKind(kind) {
+  return KINDS.indexOf(kind) === -1 ? "info" : kind;
+}
+
+function _elevationToBoxShadow(level) {
+  if (!level || typeof level !== "object") return "none";
+  const offset = level.shadowOffset || {};
+  const x = Number(offset.width) || 0;
+  const y = Number(offset.height) || 0;
+  const blur = Number(level.shadowRadius) || 0;
+  const opacity = Number(level.shadowOpacity) || 0;
+  if (!blur && !y && !x) return "none";
+  return `${x}px ${y}px ${blur * 2}px rgba(0, 0, 0, ${opacity})`;
+}
+
+/**
+ * Resolve the values a host paints one toast with, from the workspace theme.
+ *
+ * Returns primitives only — each host maps them into its own style system, so
+ * the same theme yields the same toast on web and native. `elevation` is the
+ * React Native style object; `boxShadow` is the CSS string derived from it.
+ *
+ * @param {object} theme — the resolved workspace theme (`useTheme()` shape).
+ * @param {string} kind — `success` | `error` | `warning` | `info`.
+ */
+export function resolveToastTokens(theme, kind) {
+  const safeKind = normalizeToastKind(kind);
+  const colors = (theme && theme.colors) || {};
+  const radii = (theme && theme.radii) || {};
+  const spacing = (theme && theme.spacing) || {};
+  const typography = (theme && theme.typography) || {};
+  const sizes = typography.sizes || {};
+  const elevation = ((theme && theme.elevation) || {}).lg || {};
+
+  return {
+    kind: safeKind,
+    // The kind reads as an accent stripe against the neutral surface rather
+    // than a tinted background — contrast then holds in every theme without
+    // per-kind foreground maths.
+    accent: colors[KIND_COLOR_ROLE[safeKind]] || colors.info || "#2563eb",
+    surface: colors.surface || "#ffffff",
+    text: colors.onSurface || "#111827",
+    border: colors.border || "transparent",
+    radius: radii.md || 8,
+    padding: spacing.md || 16,
+    gap: spacing.sm || 8,
+    stackGap: spacing.sm || 8,
+    accentBarWidth: spacing.xs || 4,
+    fontFamily: typography.fontFamily,
+    fontSize: sizes.sm || 14,
+    elevation,
+    boxShadow: _elevationToBoxShadow(elevation),
+  };
+}
+
+/**
+ * Create the host-side toast queue.
+ *
+ * Presentation-free and framework-free: a host subscribes, renders whatever the
+ * listener hands it, and calls `show` from the `ctx.toast.showToast` slot. The
+ * timers are injectable so both hosts and the tests drive identical behaviour.
+ *
+ * @param {object} [opts]
+ * @param {number} [opts.durationMs] — auto-dismiss delay per toast.
+ * @param {number} [opts.maxVisible] — oldest toasts drop past this depth.
+ * @param {Function} [opts.setTimer] / [opts.clearTimer] — timer injection.
+ * @returns {{ show: Function, dismiss: Function, subscribe: Function,
+ *   getToasts: Function, destroy: Function }}
+ */
+export function createToastController(opts) {
+  const options = opts || {};
+  const durationMs =
+    Number(options.durationMs) > 0
+      ? Number(options.durationMs)
+      : TOAST_DEFAULTS.durationMs;
+  const maxVisible =
+    Number(options.maxVisible) > 0
+      ? Number(options.maxVisible)
+      : TOAST_DEFAULTS.maxVisible;
+  const setTimer =
+    typeof options.setTimer === "function" ? options.setTimer : setTimeout;
+  const clearTimer =
+    typeof options.clearTimer === "function" ? options.clearTimer : clearTimeout;
+
+  let toasts = [];
+  let seq = 0;
+  let destroyed = false;
+  const timers = new Map();
+  const listeners = new Set();
+
+  function emit() {
+    const snapshot = toasts;
+    for (const listener of Array.from(listeners)) {
+      try {
+        listener(snapshot);
+      } catch {
+        // A throwing host listener must not take the queue (or the widget
+        // that raised the toast) down with it.
+      }
+    }
+  }
+
+  function clearTimerFor(id) {
+    const handle = timers.get(id);
+    if (handle !== undefined) {
+      clearTimer(handle);
+      timers.delete(id);
+    }
+  }
+
+  function dismiss(id) {
+    if (destroyed) return;
+    const next = toasts.filter((t) => t.id !== id);
+    if (next.length === toasts.length) return;
+    clearTimerFor(id);
+    toasts = next;
+    emit();
+  }
+
+  function show(payload) {
+    if (destroyed) return null;
+    const opts_ = payload && typeof payload === "object" ? payload : {};
+    const message = typeof opts_.message === "string" ? opts_.message : "";
+    // Same guard the SDK hook applies — an empty toast is not a notification.
+    if (!message) return null;
+
+    seq += 1;
+    const toast = {
+      id: `toast-${seq}`,
+      kind: normalizeToastKind(opts_.kind),
+      message,
+    };
+    // Newest first: the host renders the stack top-down, so a fresh
+    // confirmation is never pushed off-screen by older ones.
+    toasts = [toast, ...toasts].slice(0, maxVisible);
+    for (const dropped of timers.keys()) {
+      if (!toasts.some((t) => t.id === dropped)) clearTimerFor(dropped);
+    }
+    timers.set(
+      toast.id,
+      setTimer(() => {
+        timers.delete(toast.id);
+        dismiss(toast.id);
+      }, durationMs),
+    );
+    emit();
+    return toast.id;
+  }
+
+  return {
+    show,
+    dismiss,
+    getToasts: () => toasts,
+    subscribe(listener) {
+      if (typeof listener !== "function" || destroyed) return () => {};
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    destroy() {
+      destroyed = true;
+      for (const id of Array.from(timers.keys())) clearTimerFor(id);
+      listeners.clear();
+      toasts = [];
+    },
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.86.0",
+  "version": "0.87.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "type": "module",
   "main": "./dist/index.js",
@@ -48,7 +48,7 @@
   ],
   "scripts": {
     "build": "node scripts/build.js",
-    "test": "node --test src/__tests__/contract.test.js src/__tests__/hooks-users.test.js src/__tests__/hooks-groups.test.js src/__tests__/hooks-schema.test.js src/__tests__/hooks-assets-by-tag.test.js src/__tests__/hooks-filestore-upload.test.js src/__tests__/hooks-filestore-file.test.js src/__tests__/hooks-mutation.test.js src/__tests__/hooks-payments.test.js src/__tests__/hooks-record-permissions.test.js src/__tests__/hooks-geolocation.test.js src/__tests__/hooks-section-empty.test.js src/__tests__/hooks-widget-event.test.js src/__tests__/hooks-widget-input.test.js src/__tests__/hooks-identification.test.js src/__tests__/hooks-subscription.test.js src/__tests__/hooks-volatile-query-key.test.js src/__tests__/linter-users-scope.test.js src/__tests__/linter-comments.test.js src/__tests__/linter-translation-api.test.js src/__tests__/linter-image-height.test.js src/__tests__/linter-measured-padding.test.js src/__tests__/linter-payment-error.test.js src/__tests__/linter-platform.test.js src/__tests__/linter-react-import.test.js src/__tests__/lucide-icon-names.test.js src/__tests__/lucideIconName.test.js src/__tests__/manifest-actions.test.js src/__tests__/widget-translations.test.js src/__tests__/hooks-translate.test.js src/__tests__/devserver.test.js src/__tests__/host-externals.test.js src/__tests__/datetimepicker.test.js src/__tests__/property-schema-resolve.test.js src/__tests__/theme-components-parity.test.js src/__tests__/theme-depth-tokens.test.js"
+    "test": "node --test src/__tests__/contract.test.js src/__tests__/hooks-users.test.js src/__tests__/hooks-groups.test.js src/__tests__/hooks-schema.test.js src/__tests__/hooks-assets-by-tag.test.js src/__tests__/hooks-filestore-upload.test.js src/__tests__/hooks-filestore-file.test.js src/__tests__/hooks-mutation.test.js src/__tests__/hooks-payments.test.js src/__tests__/hooks-record-permissions.test.js src/__tests__/hooks-geolocation.test.js src/__tests__/hooks-section-empty.test.js src/__tests__/hooks-widget-event.test.js src/__tests__/hooks-widget-input.test.js src/__tests__/hooks-identification.test.js src/__tests__/hooks-subscription.test.js src/__tests__/hooks-volatile-query-key.test.js src/__tests__/linter-users-scope.test.js src/__tests__/linter-comments.test.js src/__tests__/linter-translation-api.test.js src/__tests__/linter-image-height.test.js src/__tests__/linter-measured-padding.test.js src/__tests__/linter-payment-error.test.js src/__tests__/linter-platform.test.js src/__tests__/linter-react-import.test.js src/__tests__/lucide-icon-names.test.js src/__tests__/lucideIconName.test.js src/__tests__/manifest-actions.test.js src/__tests__/widget-translations.test.js src/__tests__/hooks-translate.test.js src/__tests__/devserver.test.js src/__tests__/host-externals.test.js src/__tests__/datetimepicker.test.js src/__tests__/property-schema-resolve.test.js src/__tests__/theme-components-parity.test.js src/__tests__/theme-depth-tokens.test.js src/__tests__/toast-host.test.js"
   },
   "engines": {
     "node": ">=18"