@inventure71/paddockjs 4.2.0 → 4.3.0

package/src/config/theme/themeCss.js

@@ -0,0 +1,72 @@
+import { DEFAULT_PADDOCK_THEME_INPUT, LEGACY_THEME_CSS_VARIABLES, LEGACY_TOKEN_ALIASES, PADDOCK_THEME_CSS_VARIABLES, PADDOCK_THEME_SCOPED_CSS_VARIABLES } from './themeTokens.js';
+import { normalizePaddockTheme, resolveActiveThemeMode } from './themeResolver.js';
+import { selectThemePackage } from './themeSelectors.js';
+import { isPlainObject, toKebabCase } from './themeUtils.js';
+
+export function applyPaddockThemeCssVariables(root, theme = DEFAULT_PADDOCK_THEME_INPUT, context = {}) {
+  const resolved = isResolvedTheme(theme) ? theme : normalizePaddockTheme(theme);
+  const activeMode = resolveActiveThemeMode(resolved.mode);
+  root?.setAttribute?.('data-paddock-theme-mode', activeMode);
+  applyResolvedThemeCssVariables(root, resolved.themes?.[resolved.use] ?? resolved, activeMode);
+
+  getComponentElements(root).forEach((element) => {
+    const componentName = element.getAttribute?.('data-paddock-component');
+    const themeName = resolved.componentThemes?.[componentName];
+    const selectedTheme = selectThemePackage(themeName, resolved, context);
+    if (!selectedTheme) {
+      if (element !== root) clearPaddockThemeCssVariables(element);
+      return;
+    }
+    applyResolvedThemeCssVariables(element, selectedTheme, activeMode);
+  });
+}
+
+function applyResolvedThemeCssVariables(target, themePackage, activeMode) {
+  clearPaddockThemeCssVariables(target);
+  const tokens = themePackage?.tokens?.[activeMode] ?? themePackage?.activeTokens ?? {};
+  applyTokenCssVariables(target, tokens);
+  applyComponentSlotCssVariables(target, tokens, themePackage?.components);
+}
+
+function clearPaddockThemeCssVariables(target) {
+  const removeProperty = target?.style?.removeProperty;
+  if (typeof removeProperty !== 'function') return;
+  PADDOCK_THEME_SCOPED_CSS_VARIABLES.forEach((variable) => {
+    removeProperty.call(target.style, variable);
+  });
+}
+
+function applyTokenCssVariables(target, tokens = {}) {
+  Object.entries(PADDOCK_THEME_CSS_VARIABLES).forEach(([key, variable]) => {
+    const value = tokens[key];
+    if (value == null || value === '') return;
+    target?.style?.setProperty?.(variable, String(value));
+  });
+  Object.entries(LEGACY_THEME_CSS_VARIABLES).forEach(([legacyKey, variable]) => {
+    const tokenKey = LEGACY_TOKEN_ALIASES[legacyKey];
+    const value = tokens[tokenKey];
+    if (value == null || value === '') return;
+    target?.style?.setProperty?.(variable, String(value));
+  });
+}
+
+function applyComponentSlotCssVariables(target, tokens = {}, components = {}) {
+  Object.entries(components).forEach(([componentName, slots]) => {
+    Object.entries(slots).forEach(([slot, tokenName]) => {
+      const value = tokens[tokenName];
+      if (value == null || value === '') return;
+      target?.style?.setProperty?.(`--paddock-${toKebabCase(componentName)}-${toKebabCase(slot)}`, String(value));
+    });
+  });
+}
+
+function getComponentElements(root) {
+  const elements = [];
+  if (root?.matches?.('[data-paddock-component]')) elements.push(root);
+  root?.querySelectorAll?.('[data-paddock-component]')?.forEach?.((element) => elements.push(element));
+  return elements;
+}
+
+function isResolvedTheme(theme) {
+  return isPlainObject(theme) && isPlainObject(theme.tokens) && isPlainObject(theme.themes) && isPlainObject(theme.componentThemes);
+}

package/src/config/theme/themeInputs.js

@@ -0,0 +1,155 @@
+import { DEFAULT_COMPONENT_SLOTS, LEGACY_ALIAS_KEYS, LEGACY_TOKEN_ALIASES, THEME_MODES, THEME_TOKEN_KEYS, THEME_TOKEN_SET } from './themeTokens.js';
+import { isPlainObject, warnUnknownThemeKey } from './themeUtils.js';
+
+export function mergeThemeInputs(...inputs) {
+  return inputs.reduce((merged, input) => mergeThemeInputInto(merged, input), {});
+}
+
+export function mergeThemeInputInto(merged, input) {
+  if (!isPlainObject(input)) return merged;
+  const next = { ...merged };
+  if (THEME_MODES.has(input.mode)) next.mode = input.mode;
+  if (typeof input.use === 'string') next.use = input.use;
+  if (typeof input.extends === 'string') next.extends = input.extends;
+
+  const tokenInput = extractTokenInput(input);
+  if (Object.keys(tokenInput).length > 0) {
+    next.tokens = { ...(next.tokens ?? {}), ...tokenInput };
+  }
+
+  if (isPlainObject(input.themes)) {
+    next.themes = { ...(next.themes ?? {}) };
+    Object.entries(input.themes).forEach(([name, themePackage]) => {
+      if (!isPlainObject(themePackage)) return;
+      next.themes[name] = mergeThemeInputInto(next.themes[name] ?? {}, themePackage);
+    });
+  }
+  if (isPlainObject(input.components)) {
+    const legacyComponentThemes = getLegacyComponentThemeMap(input.components);
+    if (legacyComponentThemes) next.componentThemes = { ...(next.componentThemes ?? {}), ...legacyComponentThemes };
+    const componentSlots = getComponentSlotOverrides(input.components);
+    if (Object.keys(componentSlots).length > 0) {
+      next.components = mergeComponentSlots(next.components ?? {}, componentSlots);
+    }
+  }
+  if (isPlainObject(input.componentThemes)) {
+    next.componentThemes = { ...(next.componentThemes ?? {}), ...input.componentThemes };
+  }
+  if (isPlainObject(input.teamThemes)) {
+    next.teamThemes = { ...(next.teamThemes ?? {}), ...input.teamThemes };
+  }
+
+  return next;
+}
+
+export function pickTopLevelThemeInput(input) {
+  if (!isPlainObject(input)) return {};
+  const result = {};
+  ['tokens', 'components', 'componentThemes', 'teamThemes', 'light', 'dark'].forEach((key) => {
+    if (Object.hasOwn(input, key)) result[key] = input[key];
+  });
+  [...THEME_TOKEN_KEYS, ...LEGACY_ALIAS_KEYS].forEach((key) => {
+    if (Object.hasOwn(input, key)) result[key] = input[key];
+  });
+  return result;
+}
+
+export function extractTokenInput(input) {
+  if (!isPlainObject(input)) return {};
+  const result = {};
+  if (isPlainObject(input.light) || isPlainObject(input.dark)) {
+    Object.assign(result, extractModeTokenInput(input.light, input.dark));
+  }
+  const hasResolvedActiveTokens = isPlainObject(input.activeTokens);
+  if (!hasResolvedActiveTokens) {
+    THEME_TOKEN_KEYS.forEach((key) => {
+      if (Object.hasOwn(input, key)) result[key] = input[key];
+    });
+    LEGACY_ALIAS_KEYS.forEach((key) => {
+      if (Object.hasOwn(input, key)) result[LEGACY_TOKEN_ALIASES[key]] = input[key];
+    });
+  }
+  if (isPlainObject(input.tokens)) {
+    const modeTokens = extractModeTokenInput(input.tokens.light, input.tokens.dark);
+    Object.assign(result, modeTokens);
+    Object.entries(input.tokens).forEach(([key, value]) => {
+      if (key === 'light' || key === 'dark') return;
+      const tokenKey = LEGACY_TOKEN_ALIASES[key] ?? key;
+      if (THEME_TOKEN_SET.has(tokenKey)) result[tokenKey] = value;
+      else warnUnknownThemeKey(key);
+    });
+  }
+  return result;
+}
+
+function extractModeTokenInput(lightInput, darkInput) {
+  const result = {};
+  addModeTokens(result, 'light', lightInput);
+  addModeTokens(result, 'dark', darkInput);
+  return result;
+}
+
+function addModeTokens(result, mode, input) {
+  if (!isPlainObject(input)) return;
+  Object.entries(input).forEach(([key, value]) => {
+    const tokenKey = LEGACY_TOKEN_ALIASES[key] ?? key;
+    if (!THEME_TOKEN_SET.has(tokenKey)) {
+      warnUnknownThemeKey(key);
+      return;
+    }
+    const current = isPlainObject(result[tokenKey]) ? result[tokenKey] : {};
+    result[tokenKey] = { ...current, [mode]: value };
+  });
+}
+
+export function getLegacyComponentThemeMap(components) {
+  if (!isPlainObject(components)) return null;
+  const entries = Object.entries(components)
+    .map(([componentName, value]) => [
+      componentName,
+      typeof value === 'string' ? value : isPlainObject(value) && typeof value.theme === 'string' ? value.theme : null,
+    ])
+    .filter(([, selector]) => selector);
+  return entries.length > 0 ? Object.fromEntries(entries) : null;
+}
+
+export function getComponentSlotOverrides(components) {
+  if (!isPlainObject(components)) return {};
+  const result = {};
+  Object.entries(components).forEach(([componentName, slots]) => {
+    const canonicalName = normalizeComponentSlotName(componentName);
+    const schema = DEFAULT_COMPONENT_SLOTS[canonicalName];
+    if (!schema || !isPlainObject(slots)) return;
+    Object.entries(slots).forEach(([slot, tokenName]) => {
+      if (slot === 'theme') return;
+      if (!Object.hasOwn(schema, slot) || !THEME_TOKEN_SET.has(tokenName)) {
+        warnUnknownThemeKey(`${componentName}.${slot}`);
+        return;
+      }
+      result[canonicalName] = {
+        ...(result[canonicalName] ?? {}),
+        [slot]: tokenName,
+      };
+    });
+  });
+  return result;
+}
+
+export function mergeComponentSlots(parent = {}, overrides = {}) {
+  const result = {};
+  Object.entries(parent).forEach(([componentName, slots]) => {
+    result[componentName] = { ...slots };
+  });
+  Object.entries(overrides).forEach(([componentName, slots]) => {
+    if (!Object.hasOwn(DEFAULT_COMPONENT_SLOTS, componentName)) return;
+    result[componentName] = {
+      ...(result[componentName] ?? DEFAULT_COMPONENT_SLOTS[componentName]),
+      ...slots,
+    };
+  });
+  return result;
+}
+
+function normalizeComponentSlotName(name) {
+  return String(name).replace(/-([a-z])/g, (_, char) => char.toUpperCase());
+}

package/src/config/theme/themeResolver.js

@@ -0,0 +1,172 @@
+import { DEFAULT_COMPONENT_THEME_SELECTORS, DEFAULT_THEME_PACKAGE, LEGACY_TOKEN_ALIASES, THEME_COLOR_TOKEN_KEYS, THEME_MODES, THEME_SIZE_TOKEN_KEYS } from './themeTokens.js';
+import { extractTokenInput, getComponentSlotOverrides, getLegacyComponentThemeMap, mergeComponentSlots, mergeThemeInputInto, pickTopLevelThemeInput } from './themeInputs.js';
+import { deriveModeColor, normalizeCssColorToken, normalizeCssSizeToken } from './cssTokens.js';
+import { normalizeComponentThemeSelectors, normalizeThemeSelectors } from './themeSelectors.js';
+import { isPlainObject } from './themeUtils.js';
+
+const ACTIVE_THEME_MODES = new Set(['dark', 'light']);
+const RESOLVED_THEME_CACHE = new Map();
+
+export function normalizePaddockTheme(input = {}) {
+  const mode = THEME_MODES.has(input?.mode) ? input.mode : 'dark';
+  const activeMode = resolveActiveThemeMode(mode);
+  const cacheKey = stableStringify({ input, activeMode });
+  if (RESOLVED_THEME_CACHE.has(cacheKey)) return RESOLVED_THEME_CACHE.get(cacheKey);
+
+  const themeInputs = isPlainObject(input?.themes) ? input.themes : {};
+  const resolving = new Set();
+  const resolvedThemes = {};
+
+  const resolveNamedTheme = (name) => {
+    const themeName = typeof name === 'string' && name !== '' ? name : 'default';
+    if (resolvedThemes[themeName]) return resolvedThemes[themeName];
+    if (resolving.has(themeName)) return resolvedThemes.default ?? DEFAULT_THEME_PACKAGE;
+    resolving.add(themeName);
+
+    const rawPackage = themeName === 'default'
+      ? mergeThemeInputInto(themeInputs.default ?? {}, pickTopLevelThemeInput(input))
+      : themeInputs[themeName];
+    const parentName = themeName === 'default'
+      ? null
+      : typeof rawPackage?.extends === 'string' && rawPackage.extends !== themeName
+        ? rawPackage.extends
+        : 'default';
+    const parent = parentName ? resolveNamedTheme(parentName) : DEFAULT_THEME_PACKAGE;
+    const resolved = resolveThemePackage(rawPackage, parent);
+    resolvedThemes[themeName] = resolved;
+    resolving.delete(themeName);
+    return resolved;
+  };
+
+  resolveNamedTheme('default');
+  Object.keys(themeInputs).forEach((name) => {
+    if (isPlainObject(themeInputs[name])) resolveNamedTheme(name);
+  });
+
+  const requestedUse = typeof input?.use === 'string' ? input.use : 'default';
+  const use = Object.hasOwn(resolvedThemes, requestedUse) ? requestedUse : 'default';
+  const activeTheme = resolvedThemes[use] ?? resolvedThemes.default;
+  const activeTokens = activeTheme.tokens[activeMode];
+  const componentThemes = {
+    ...DEFAULT_COMPONENT_THEME_SELECTORS,
+    ...normalizeComponentThemeSelectors(
+      input?.componentThemes ?? getLegacyComponentThemeMap(input?.components),
+      resolvedThemes,
+    ),
+  };
+  const teamThemes = normalizeThemeSelectors(input?.teamThemes, resolvedThemes);
+  const result = {
+    mode,
+    activeMode,
+    use,
+    tokens: activeTheme.tokens,
+    activeTokens,
+    components: activeTheme.components,
+    themes: resolvedThemes,
+    componentThemes,
+    teamThemes,
+    light: toLegacyThemeTokens(activeTheme.tokens.light),
+    dark: toLegacyThemeTokens(activeTheme.tokens.dark),
+    ...toLegacyThemeTokens(activeTokens),
+  };
+
+  RESOLVED_THEME_CACHE.set(cacheKey, result);
+  return result;
+}
+
+function resolveThemePackage(input, parent = DEFAULT_THEME_PACKAGE) {
+  const tokenInput = extractTokenInput(input);
+  const tokens = {
+    light: {},
+    dark: {},
+  };
+
+  THEME_COLOR_TOKEN_KEYS.forEach((key) => {
+    const fallbackPair = {
+      light: parent.tokens.light[key],
+      dark: parent.tokens.dark[key],
+    };
+    const pair = Object.hasOwn(tokenInput, key)
+      ? resolveColorModePair(key, tokenInput[key], fallbackPair)
+      : fallbackPair;
+    tokens.light[key] = pair.light;
+    tokens.dark[key] = pair.dark;
+  });
+
+  THEME_SIZE_TOKEN_KEYS.forEach((key) => {
+    const fallbackPair = {
+      light: parent.tokens.light[key],
+      dark: parent.tokens.dark[key],
+    };
+    const pair = Object.hasOwn(tokenInput, key)
+      ? resolveSizeModePair(tokenInput[key], fallbackPair)
+      : fallbackPair;
+    tokens.light[key] = pair.light;
+    tokens.dark[key] = pair.dark;
+  });
+
+  return {
+    tokens,
+    components: mergeComponentSlots(parent.components, getComponentSlotOverrides(input?.components)),
+  };
+}
+
+function resolveColorModePair(key, value, fallbackPair) {
+  const pair = isPlainObject(value) ? value : { light: value, dark: value };
+  const light = normalizeCssColorToken(pair.light, null);
+  const dark = normalizeCssColorToken(pair.dark, null);
+  if (light && dark) return { light, dark };
+  if (light) return {
+    light,
+    dark: deriveModeColor('dark', key, light) ?? fallbackPair.dark,
+  };
+  if (dark) return {
+    light: deriveModeColor('light', key, dark) ?? fallbackPair.light,
+    dark,
+  };
+  return fallbackPair;
+}
+
+function resolveSizeModePair(value, fallbackPair) {
+  const pair = isPlainObject(value) ? value : { light: value, dark: value };
+  const light = normalizeCssSizeToken(pair.light, null);
+  const dark = normalizeCssSizeToken(pair.dark, null);
+  if (light && dark) return { light, dark };
+  if (light) return { light, dark: light };
+  if (dark) return { light: dark, dark };
+  return fallbackPair;
+}
+
+function toLegacyThemeTokens(tokens = {}) {
+  const aliases = {};
+  Object.entries(LEGACY_TOKEN_ALIASES).forEach(([legacyKey, tokenKey]) => {
+    aliases[legacyKey] = tokens[tokenKey];
+  });
+  return { ...tokens, ...aliases };
+}
+
+export function resolveActiveThemeMode(mode) {
+  if (ACTIVE_THEME_MODES.has(mode)) return mode;
+  if (globalThis.matchMedia?.('(prefers-color-scheme: light)')?.matches) return 'light';
+  return 'dark';
+}
+
+function stableStringify(value) {
+  return JSON.stringify(sortForStableStringify(value, new WeakSet()));
+}
+
+function sortForStableStringify(value, seen) {
+  if (typeof value === 'bigint') return `bigint:${value.toString()}`;
+  if (typeof value === 'function') return `function:${value.name ?? ''}`;
+  if (typeof value === 'symbol') return value.toString();
+  if (value === undefined) return 'undefined';
+  if (Array.isArray(value)) return value.map((item) => sortForStableStringify(item, seen));
+  if (!isPlainObject(value)) return value;
+  if (seen.has(value)) return '[Circular]';
+  seen.add(value);
+  return Object.fromEntries(
+    Object.keys(value)
+      .sort()
+      .map((key) => [key, sortForStableStringify(value[key], seen)]),
+  );
+}

package/src/config/theme/themeSelectors.js

@@ -0,0 +1,69 @@
+import { COMPONENT_THEME_SELECTOR_ALIASES, PACKAGE_COMPONENT_THEME_KEYS } from './themeTokens.js';
+import { isPlainObject, toKebabCase, warnUnknownThemeKey } from './themeUtils.js';
+
+export function normalizeThemeSelectors(selectors, themes) {
+  if (!isPlainObject(selectors)) return {};
+  return Object.fromEntries(
+    Object.entries(selectors)
+      .map(([key, selector]) => [
+        key,
+        typeof selector === 'string' ? selector : isPlainObject(selector) ? selector.theme : null,
+      ])
+      .filter(([, selector]) => isValidThemeSelector(selector, themes)),
+  );
+}
+
+export function normalizeComponentThemeSelectors(selectors, themes) {
+  if (!isPlainObject(selectors)) return {};
+  const result = {};
+  Object.entries(selectors).forEach(([key, selectorInput]) => {
+    const selector = typeof selectorInput === 'string'
+      ? selectorInput
+      : isPlainObject(selectorInput)
+        ? selectorInput.theme
+        : null;
+    if (!isValidThemeSelector(selector, themes)) return;
+    normalizeComponentThemeSelectorKeys(key).forEach((componentKey) => {
+      if (PACKAGE_COMPONENT_THEME_KEYS.has(componentKey)) result[componentKey] = selector;
+      else warnUnknownThemeKey(key);
+    });
+  });
+  return result;
+}
+
+function normalizeComponentThemeSelectorKeys(key) {
+  const raw = String(key);
+  if (COMPONENT_THEME_SELECTOR_ALIASES[raw]) return COMPONENT_THEME_SELECTOR_ALIASES[raw];
+  return [raw.includes('-') ? raw : toKebabCase(raw)];
+}
+
+function isValidThemeSelector(selector, themes) {
+  if (typeof selector !== 'string' || selector === '') return false;
+  if (selector === 'default' || selector === 'active' || selector === 'selectedTeam' || selector === 'team') return true;
+  if (selector.startsWith('team:')) return selector.length > 5;
+  return Object.hasOwn(themes, selector);
+}
+
+export function selectThemePackage(selector, resolved, context = {}, visitedTeamIds = new Set()) {
+  if (!selector || selector === 'active') return null;
+  if (selector === 'default') return resolved.themes?.default;
+  if (selector === 'team' || selector === 'selectedTeam' || selector.startsWith('team:')) {
+    const teamId = selector.startsWith('team:')
+      ? selector.slice(5)
+      : selector === 'selectedTeam'
+        ? context.selectedTeamId
+        : context.teamId ?? context.selectedTeamId;
+    const teamTheme = selectTeamThemePackage(teamId, resolved, context, visitedTeamIds);
+    return teamTheme ?? resolved.themes?.[resolved.use] ?? resolved.themes?.default;
+  }
+  return resolved.themes?.[selector] ?? null;
+}
+
+function selectTeamThemePackage(teamId, resolved, context, visitedTeamIds) {
+  if (typeof teamId !== 'string' || teamId === '' || visitedTeamIds.has(teamId)) return null;
+  const selector = resolved.teamThemes?.[teamId];
+  if (!selector) return null;
+  visitedTeamIds.add(teamId);
+  if (selector === 'team' || selector === 'selectedTeam') return null;
+  return selectThemePackage(selector, resolved, context, visitedTeamIds);
+}