@ensera/plugin-frontend 1.0.0 → 1.0.1

package/README.md

@@ -1,15 +1,15 @@
-# @ensera/plugin-frontend
-
-Frontend runtime SDK for Ensera plugins.
-
-## Install
-
-```bash
-npm install @ensera/plugin-frontend
-```
-
-## Purpose
-
-- mounts frontend features inside Ensera Core
-- provides the runtime APIs used by the published templates
-- stays separate from the scaffold template packages
+# @ensera/plugin-frontend
+
+Frontend runtime SDK for Ensera plugins.
+
+## Install
+
+```bash
+npm install @ensera/plugin-frontend
+```
+
+## Purpose
+
+- mounts frontend features inside Ensera Core
+- provides the runtime APIs used by the published templates
+- stays separate from the scaffold template packages

package/dist/index.d.ts

@@ -71,6 +71,23 @@ type PluginCtx = {
      * Backward compatible: older Core can omit.
      */
     launch?: PluginLaunch;
+    /**
+     * Optional: current Core theme snapshot.
+     * Included on INIT so the feature can render with the correct theme on first paint.
+     */
+    theme?: PluginThemeSnapshot;
+};
+type PluginThemeMode = "light" | "dark";
+type PluginThemeSnapshot = {
+    mode: PluginThemeMode;
+};
+type PluginThemeColorRole = "solid" | "surface" | "border" | "text";
+type PluginThemeMessage = {
+    type: "ENSERA_THEME";
+    instanceId?: string;
+    payload: {
+        theme: PluginThemeSnapshot;
+    };
 };
 /**
  * Launch modes for plugin instances
@@ -548,6 +565,28 @@ declare function useSyncedState<T extends JsonValue>(args: {
     initialState: T;
 }): [T, (state: T | ((prev: T) => T)) => void];
 
+declare function normalizePluginThemeMode(value: unknown): PluginThemeMode;
+declare function normalizePluginThemeSnapshot(value?: Partial<PluginThemeSnapshot> | PluginThemeMessage | null): PluginThemeSnapshot;
+declare function applyPluginTheme(value?: Partial<PluginThemeSnapshot> | PluginThemeMessage | null, root?: HTMLElement): PluginThemeSnapshot;
+declare function dispatchPluginThemeChange(value?: Partial<PluginThemeSnapshot> | PluginThemeMessage | null): PluginThemeSnapshot;
+declare function initializePluginTheme(value?: Partial<PluginThemeSnapshot> | PluginThemeMessage | null): PluginThemeSnapshot;
+declare function getPluginThemeSnapshot(): PluginThemeSnapshot;
+declare function subscribePluginTheme(listener: () => void): () => boolean;
+declare function usePluginTheme(): PluginThemeSnapshot;
+declare function adaptFeatureColor(hex: string, args: {
+    mode: PluginThemeMode;
+    role?: PluginThemeColorRole;
+}): string;
+declare function getReadableFeatureTextColor(backgroundHex: string): "#FFFFFF" | "#111111";
+declare function getFeatureColorTokens(hex: string, mode: PluginThemeMode): {
+    solid: string;
+    surface: string;
+    border: string;
+    text: string;
+    contrastText: string;
+};
+declare function syncAdaptiveFeatureColors(root: ParentNode | null | undefined, mode: PluginThemeMode): void;
+
 declare const tokens: {
     readonly spacing: {
         readonly xs: 4;
@@ -749,4 +788,4 @@ declare function setupContextMenuRelay(ctx: {
     instanceId: string;
 }): () => void;
 
-export { Button, type ButtonProps, type ButtonSize, type ButtonVariant, ContextMenuShell, ContextRow, type ContextRowProps, IconButton, type IconButtonProps, type IconButtonSize, type IconButtonVariant, Input, type InputProps, type InputSize, type InputVariant, type JsonObject, type JsonValue, type NotificationAction, type NotificationCapabilities, type NotificationTypeConfig, type PluginActionHandler, type PluginActionHandlerArgs, type PluginActionId, type PluginActionsMap, PluginAuthError, type PluginCtx, type PluginDispatchFn, type PluginDispatchRequest, type PluginDispatchResult, type PluginErrorPayload, PluginFetchError, type PluginFetchExpect, PluginFetchInputError, type PluginFetchOptions, type PluginFetchResponse, type PluginFetchRetry, PluginForbiddenError, type PluginLaunch, type PluginLogLevel, type PluginLogger, PluginNetworkError, PluginNotFoundError, type PluginNotification, type PluginNotificationBulkResponse, type PluginNotificationOptions, type PluginNotificationRequest, type PluginNotificationResponse, type PluginNotificationResultMessage, type PluginNotify, type PluginOpenOverlayMessage, PluginRateLimitError, PluginResponseError, type PluginRuntime, PluginServerError, type PluginStorage, type PluginStorageBackend, PluginStorageError, type PluginStorageIndexedDB, PluginStorageQuotaError, PluginUnknownActionError, PluginValidationError, Row, type RowAlign, type RowHeight, type RowJustify, type RowProps, type SyncCallback, type SyncEventType, type SyncMessage, type SyncPayload, type SyncedState, type Tokens, attachActionDispatcher, broadcast, createPluginFetch, createPluginLogger, createPluginNotify, createPluginRuntime, createPluginStorage, createPluginStorageIndexedDB, createSyncedState, defineActions, initBroadcast, makeStorageNamespace, onBroadcast, openOverlay, runActionSafe, setupContextMenuRelay, tokens, useBroadcastListener, useSyncedState };
+export { Button, type ButtonProps, type ButtonSize, type ButtonVariant, ContextMenuShell, ContextRow, type ContextRowProps, IconButton, type IconButtonProps, type IconButtonSize, type IconButtonVariant, Input, type InputProps, type InputSize, type InputVariant, type JsonObject, type JsonValue, type NotificationAction, type NotificationCapabilities, type NotificationTypeConfig, type PluginActionHandler, type PluginActionHandlerArgs, type PluginActionId, type PluginActionsMap, PluginAuthError, type PluginCtx, type PluginDispatchFn, type PluginDispatchRequest, type PluginDispatchResult, type PluginErrorPayload, PluginFetchError, type PluginFetchExpect, PluginFetchInputError, type PluginFetchOptions, type PluginFetchResponse, type PluginFetchRetry, PluginForbiddenError, type PluginLaunch, type PluginLogLevel, type PluginLogger, PluginNetworkError, PluginNotFoundError, type PluginNotification, type PluginNotificationBulkResponse, type PluginNotificationOptions, type PluginNotificationRequest, type PluginNotificationResponse, type PluginNotificationResultMessage, type PluginNotify, type PluginOpenOverlayMessage, PluginRateLimitError, PluginResponseError, type PluginRuntime, PluginServerError, type PluginStorage, type PluginStorageBackend, PluginStorageError, type PluginStorageIndexedDB, PluginStorageQuotaError, type PluginThemeColorRole, type PluginThemeMessage, type PluginThemeMode, type PluginThemeSnapshot, PluginUnknownActionError, PluginValidationError, Row, type RowAlign, type RowHeight, type RowJustify, type RowProps, type SyncCallback, type SyncEventType, type SyncMessage, type SyncPayload, type SyncedState, type Tokens, adaptFeatureColor, applyPluginTheme, attachActionDispatcher, broadcast, createPluginFetch, createPluginLogger, createPluginNotify, createPluginRuntime, createPluginStorage, createPluginStorageIndexedDB, createSyncedState, defineActions, dispatchPluginThemeChange, getFeatureColorTokens, getPluginThemeSnapshot, getReadableFeatureTextColor, initBroadcast, initializePluginTheme, makeStorageNamespace, normalizePluginThemeMode, normalizePluginThemeSnapshot, onBroadcast, openOverlay, runActionSafe, setupContextMenuRelay, subscribePluginTheme, syncAdaptiveFeatureColors, tokens, useBroadcastListener, usePluginTheme, useSyncedState };

package/dist/index.js

@@ -1260,6 +1260,327 @@ function useSyncedState(args) {
   return [sync.getState(), sync.setState];
 }
 
+// src/theme.ts
+import { useSyncExternalStore } from "react";
+var THEME_EVENT = "ENSERA_THEME_CHANGE";
+var THEME_ATTR = "data-ensera-theme";
+var DARK_ROOT_CLASS = "dark";
+var LIGHT_SURFACE = "#FFFFFF";
+var DARK_SURFACE = "#111827";
+var currentTheme = readThemeFromDom();
+var boundWindowListeners = false;
+var listeners = /* @__PURE__ */ new Set();
+function clamp(value, min, max) {
+  return Math.min(max, Math.max(min, value));
+}
+function normalizeChannel(value) {
+  return parseInt(value, 16);
+}
+function normalizePluginThemeMode(value) {
+  return value === "dark" ? "dark" : "light";
+}
+function normalizePluginThemeSnapshot(value) {
+  const maybeTheme = value && "payload" in value ? value.payload?.theme : value ?? void 0;
+  return {
+    mode: normalizePluginThemeMode(maybeTheme?.mode)
+  };
+}
+function readThemeFromDom() {
+  if (typeof document === "undefined") {
+    return { mode: "light" };
+  }
+  const mode = document.documentElement.getAttribute(THEME_ATTR);
+  return { mode: normalizePluginThemeMode(mode) };
+}
+function notifyThemeListeners() {
+  for (const listener of listeners) {
+    listener();
+  }
+}
+function applyThemeToRoot(root, theme) {
+  root.setAttribute(THEME_ATTR, theme.mode);
+  root.classList.toggle(DARK_ROOT_CLASS, theme.mode === "dark");
+  root.style.colorScheme = theme.mode;
+}
+function bindWindowThemeListeners() {
+  if (boundWindowListeners || typeof window === "undefined") {
+    return;
+  }
+  window.addEventListener(THEME_EVENT, (event) => {
+    const detail = event.detail;
+    currentTheme = normalizePluginThemeSnapshot(detail);
+    notifyThemeListeners();
+  });
+  boundWindowListeners = true;
+}
+function applyPluginTheme(value, root) {
+  const theme = normalizePluginThemeSnapshot(value);
+  currentTheme = theme;
+  if (typeof document !== "undefined") {
+    applyThemeToRoot(root ?? document.documentElement, theme);
+  }
+  notifyThemeListeners();
+  return theme;
+}
+function dispatchPluginThemeChange(value) {
+  const theme = normalizePluginThemeSnapshot(value);
+  currentTheme = theme;
+  if (typeof window !== "undefined") {
+    window.dispatchEvent(
+      new CustomEvent(THEME_EVENT, {
+        detail: theme
+      })
+    );
+  } else {
+    notifyThemeListeners();
+  }
+  return theme;
+}
+function initializePluginTheme(value) {
+  bindWindowThemeListeners();
+  if (value) {
+    return applyPluginTheme(value);
+  }
+  currentTheme = readThemeFromDom();
+  notifyThemeListeners();
+  return currentTheme;
+}
+function getPluginThemeSnapshot() {
+  bindWindowThemeListeners();
+  return currentTheme;
+}
+function subscribePluginTheme(listener) {
+  bindWindowThemeListeners();
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+function usePluginTheme() {
+  bindWindowThemeListeners();
+  return useSyncExternalStore(
+    subscribePluginTheme,
+    getPluginThemeSnapshot,
+    getPluginThemeSnapshot
+  );
+}
+function normalizeHexColor(value) {
+  const raw = String(value ?? "").trim().replace(/^#/, "");
+  if (raw.length === 3) {
+    return `#${raw.split("").map((part) => `${part}${part}`).join("").toUpperCase()}`;
+  }
+  if (raw.length !== 6 || /[^0-9A-Fa-f]/.test(raw)) {
+    return null;
+  }
+  return `#${raw.toUpperCase()}`;
+}
+function parseCssColorToHex(value) {
+  const normalizedHex = normalizeHexColor(value);
+  if (normalizedHex) return normalizedHex;
+  const match = String(value ?? "").trim().match(/^rgba?\((\d+)\s*,\s*(\d+)\s*,\s*(\d+)/i);
+  if (!match) return null;
+  return rgbToHex(Number(match[1]), Number(match[2]), Number(match[3]));
+}
+function hexToRgb(hex) {
+  const normalized = normalizeHexColor(hex);
+  if (!normalized) return null;
+  return {
+    r: normalizeChannel(normalized.slice(1, 3)),
+    g: normalizeChannel(normalized.slice(3, 5)),
+    b: normalizeChannel(normalized.slice(5, 7))
+  };
+}
+function rgbToHex(r, g, b) {
+  const toHex = (value) => clamp(Math.round(value), 0, 255).toString(16).padStart(2, "0");
+  return `#${toHex(r)}${toHex(g)}${toHex(b)}`.toUpperCase();
+}
+function rgbToHsl(r, g, b) {
+  const rn = r / 255;
+  const gn = g / 255;
+  const bn = b / 255;
+  const max = Math.max(rn, gn, bn);
+  const min = Math.min(rn, gn, bn);
+  const delta = max - min;
+  const lightness = (max + min) / 2;
+  if (delta === 0) {
+    return { h: 0, s: 0, l: lightness };
+  }
+  const saturation = lightness > 0.5 ? delta / (2 - max - min) : delta / (max + min);
+  let hue = 0;
+  switch (max) {
+    case rn:
+      hue = (gn - bn) / delta + (gn < bn ? 6 : 0);
+      break;
+    case gn:
+      hue = (bn - rn) / delta + 2;
+      break;
+    default:
+      hue = (rn - gn) / delta + 4;
+      break;
+  }
+  hue /= 6;
+  return { h: hue, s: saturation, l: lightness };
+}
+function hslToRgb(h, s, l) {
+  if (s === 0) {
+    const value = l * 255;
+    return { r: value, g: value, b: value };
+  }
+  const hueToRgb = (p2, q2, t) => {
+    let next = t;
+    if (next < 0) next += 1;
+    if (next > 1) next -= 1;
+    if (next < 1 / 6) return p2 + (q2 - p2) * 6 * next;
+    if (next < 1 / 2) return q2;
+    if (next < 2 / 3) return p2 + (q2 - p2) * (2 / 3 - next) * 6;
+    return p2;
+  };
+  const q = l < 0.5 ? l * (1 + s) : l + s - l * s;
+  const p = 2 * l - q;
+  return {
+    r: hueToRgb(p, q, h + 1 / 3) * 255,
+    g: hueToRgb(p, q, h) * 255,
+    b: hueToRgb(p, q, h - 1 / 3) * 255
+  };
+}
+function mixColors(baseHex, mixHex, ratio) {
+  const base = hexToRgb(baseHex);
+  const mix = hexToRgb(mixHex);
+  if (!base || !mix) return normalizeHexColor(baseHex) ?? baseHex;
+  const clampedRatio = clamp(ratio, 0, 1);
+  const inverse = 1 - clampedRatio;
+  return rgbToHex(
+    base.r * inverse + mix.r * clampedRatio,
+    base.g * inverse + mix.g * clampedRatio,
+    base.b * inverse + mix.b * clampedRatio
+  );
+}
+function toLinear(channel) {
+  const normalized = channel / 255;
+  return normalized <= 0.03928 ? normalized / 12.92 : ((normalized + 0.055) / 1.055) ** 2.4;
+}
+function relativeLuminance(hex) {
+  const rgb = hexToRgb(hex);
+  if (!rgb) return 0;
+  const r = toLinear(rgb.r);
+  const g = toLinear(rgb.g);
+  const b = toLinear(rgb.b);
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+}
+function contrastRatio(foregroundHex, backgroundHex) {
+  const foreground = relativeLuminance(foregroundHex);
+  const background = relativeLuminance(backgroundHex);
+  const lighter = Math.max(foreground, background);
+  const darker = Math.min(foreground, background);
+  return (lighter + 0.05) / (darker + 0.05);
+}
+function ensureContrast(foregroundHex, backgroundHex, minRatio) {
+  const normalizedForeground = normalizeHexColor(foregroundHex) ?? normalizeHexColor(backgroundHex) ?? "#000000";
+  const normalizedBackground = normalizeHexColor(backgroundHex) ?? DARK_SURFACE;
+  if (contrastRatio(normalizedForeground, normalizedBackground) >= minRatio) {
+    return normalizedForeground;
+  }
+  const backgroundIsDark = relativeLuminance(normalizedBackground) < relativeLuminance(normalizedForeground);
+  const targetMix = backgroundIsDark ? LIGHT_SURFACE : "#111111";
+  let next = normalizedForeground;
+  for (let index = 1; index <= 12; index += 1) {
+    next = mixColors(normalizedForeground, targetMix, index * 0.06);
+    if (contrastRatio(next, normalizedBackground) >= minRatio) {
+      return next;
+    }
+  }
+  return next;
+}
+function adaptSolidColor(hex, mode) {
+  const normalized = normalizeHexColor(hex);
+  if (!normalized) return hex;
+  const rgb = hexToRgb(normalized);
+  if (!rgb) return normalized;
+  const hsl = rgbToHsl(rgb.r, rgb.g, rgb.b);
+  let nextLightness = hsl.l;
+  let nextSaturation = hsl.s;
+  if (mode === "light" && hsl.l < 0.42) {
+    nextLightness = 0.56;
+    nextSaturation = clamp(hsl.s * 0.96, 0, 1);
+  } else if (mode === "dark" && hsl.l > 0.72) {
+    nextLightness = 0.56;
+    nextSaturation = clamp(hsl.s * 0.94, 0, 1);
+  }
+  const nextRgb = hslToRgb(hsl.h, nextSaturation, nextLightness);
+  return rgbToHex(nextRgb.r, nextRgb.g, nextRgb.b);
+}
+function adaptFeatureColor(hex, args) {
+  const role = args.role ?? "solid";
+  const solid = adaptSolidColor(hex, args.mode);
+  const surfaceBase = args.mode === "dark" ? DARK_SURFACE : LIGHT_SURFACE;
+  switch (role) {
+    case "surface":
+      return mixColors(solid, surfaceBase, args.mode === "dark" ? 0.78 : 0.86);
+    case "border":
+      return mixColors(solid, surfaceBase, args.mode === "dark" ? 0.52 : 0.6);
+    case "text":
+      return ensureContrast(
+        solid,
+        surfaceBase,
+        args.mode === "dark" ? 4 : 4.5
+      );
+    case "solid":
+    default:
+      return solid;
+  }
+}
+function getReadableFeatureTextColor(backgroundHex) {
+  const lightContrast = contrastRatio(LIGHT_SURFACE, backgroundHex);
+  const darkContrast = contrastRatio("#111111", backgroundHex);
+  return lightContrast >= darkContrast ? LIGHT_SURFACE : "#111111";
+}
+function getFeatureColorTokens(hex, mode) {
+  const solid = adaptFeatureColor(hex, { mode, role: "solid" });
+  const surface = adaptFeatureColor(hex, { mode, role: "surface" });
+  const border = adaptFeatureColor(hex, { mode, role: "border" });
+  const text = adaptFeatureColor(hex, { mode, role: "text" });
+  return {
+    solid,
+    surface,
+    border,
+    text,
+    contrastText: getReadableFeatureTextColor(solid)
+  };
+}
+function syncAdaptiveFeatureColors(root, mode) {
+  if (!root || typeof root.querySelectorAll !== "function") {
+    return;
+  }
+  const elements = root.querySelectorAll("[style]");
+  for (const element of elements) {
+    const originalStyle = element.getAttribute("style");
+    if (!originalStyle) continue;
+    const colorMatch = originalStyle.match(/(?:^|;)\s*color:\s*([^;]+)/i);
+    const backgroundMatch = originalStyle.match(
+      /(?:^|;)\s*background-color:\s*([^;]+)/i
+    );
+    if (colorMatch) {
+      const raw = element.dataset.enseraThemeColor ?? parseCssColorToHex(colorMatch[1]) ?? void 0;
+      if (raw) {
+        element.dataset.enseraThemeColor = raw;
+        element.style.color = adaptFeatureColor(raw, {
+          mode,
+          role: "text"
+        });
+      }
+    }
+    if (backgroundMatch) {
+      const raw = element.dataset.enseraThemeBackground ?? parseCssColorToHex(backgroundMatch[1]) ?? void 0;
+      if (raw) {
+        element.dataset.enseraThemeBackground = raw;
+        element.style.backgroundColor = adaptFeatureColor(raw, {
+          mode,
+          role: "surface"
+        });
+      }
+    }
+  }
+}
+bindWindowThemeListeners();
+
 // src/ui/tokens.ts
 var tokens = {
   // Spacing scale (in pixels)
@@ -1999,6 +2320,8 @@ export {
   PluginUnknownActionError,
   PluginValidationError,
   Row,
+  adaptFeatureColor,
+  applyPluginTheme,
   attachActionDispatcher,
   broadcast,
   createPluginFetch,
@@ -2009,13 +2332,23 @@ export {
   createPluginStorageIndexedDB,
   createSyncedState,
   defineActions,
+  dispatchPluginThemeChange,
+  getFeatureColorTokens,
+  getPluginThemeSnapshot,
+  getReadableFeatureTextColor,
   initBroadcast,
+  initializePluginTheme,
   makeStorageNamespace,
+  normalizePluginThemeMode,
+  normalizePluginThemeSnapshot,
   onBroadcast,
   openOverlay,
   runActionSafe,
   setupContextMenuRelay,
+  subscribePluginTheme,
+  syncAdaptiveFeatureColors,
   tokens,
   useBroadcastListener,
+  usePluginTheme,
   useSyncedState
 };

package/package.json

@@ -1,50 +1,50 @@
-{
-  "name": "@ensera/plugin-frontend",
-  "version": "1.0.0",
-  "description": "Runtime frontend SDK for Ensera plugins.",
-  "type": "module",
-  "main": "./dist/index.js",
-  "module": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
-    },
-    "./package.json": "./package.json"
-  },
-  "files": [
-    "dist",
-    "README.md"
-  ],
-  "sideEffects": false,
-  "scripts": {
-    "build": "tsup src/index.ts --format esm --dts --clean --target es2022 --outDir dist",
-    "dev": "tsup src/index.ts --format esm --dts --watch --target es2022 --outDir dist",
-    "typecheck": "tsc -p tsconfig.json --noEmit",
-    "prepublishOnly": "npm run build && npm run typecheck"
-  },
-  "keywords": [
-    "ensera",
-    "frontend",
-    "sdk",
-    "plugin",
-    "react"
-  ],
-  "publishConfig": {
-    "access": "public"
-  },
-  "engines": {
-    "node": ">=18"
-  },
-  "peerDependencies": {
-    "react": "^18.0.0",
-    "react-dom": "^18.0.0"
-  },
-  "devDependencies": {
-    "@types/react": "^18.3.28",
-    "@types/react-dom": "^18.3.7",
-    "react": "^18.3.1",
-    "react-dom": "^18.3.1"
-  }
-}
+{
+  "name": "@ensera/plugin-frontend",
+  "version": "1.0.1",
+  "description": "Runtime frontend SDK for Ensera plugins.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean --target es2022 --outDir dist",
+    "dev": "tsup src/index.ts --format esm --dts --watch --target es2022 --outDir dist",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "prepublishOnly": "npm run build && npm run typecheck"
+  },
+  "keywords": [
+    "ensera",
+    "frontend",
+    "sdk",
+    "plugin",
+    "react"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0",
+    "react-dom": "^18.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^18.3.28",
+    "@types/react-dom": "^18.3.7",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1"
+  }
+}