@pure-ds/core 0.5.61 → 0.6.1

package/public/assets/pds/components/pds-richtext.js

@@ -341,7 +341,13 @@ export class RichText extends HTMLElement {
   async #adoptStyles() {
     // Component stylesheet (tokens + semantic vars)
     const componentStyles = PDS.createStylesheet(/*css*/ `@layer richtext {
-      :host { display:block; color: var(--rt-fg, var(--color-text-primary)); font: var(--font-body-sm, 14px/1.35 system-ui,-apple-system,Segoe UI,Roboto,sans-serif); }
+      :host {
+        display: block;
+        color: var(--rt-fg, var(--color-text-primary));
+        font-family: var(--rt-font-family, var(--font-family-body));
+        font-size: var(--rt-font-size, var(--font-size-base));
+        line-height: var(--rt-line-height, var(--font-line-height-normal));
+      }
       :host([disabled]) { opacity: .6; pointer-events: none; }
       .box { border: 1px solid var(--rt-border, var(--color-border, currentColor)); border-radius: var(--radius-md,8px); background: var(--rt-bg, var(--color-input-bg)); }
       .box:focus-within { 
@@ -353,11 +359,15 @@ export class RichText extends HTMLElement {
         }
       }
       
-      .toolbar {background-color: var(--surface-subtle-bg);  display:flex; gap: var(--spacing-2,10px); align-items:center; border-bottom: 1px solid var(--rt-border, var(--color-border-muted)); border-radius: var(--radius-md,8px) var(--radius-md,8px) 0 0; }
-      .tbtn { transition: none; display:inline-flex; align-items:center; justify-content:center; width:22px; height:22px; border-radius: var(--radius-sm,6px); cursor:pointer; user-select:none; color: inherit; background: transparent; border:none; }
+      .toolbar { background-color: var(--surface-subtle-bg); display: flex; gap: var(--spacing-0, 2px); align-items: center; padding: var(--spacing-0, 2px); border-bottom: 1px solid var(--rt-border, var(--color-border-muted)); border-radius: var(--radius-md,8px) var(--radius-md,8px) 0 0; width: 100%; max-width: 100%; flex-wrap: nowrap; box-sizing: border-box; overflow: hidden; }
+      .tbtn { transition: none; display:inline-flex; align-items:center; justify-content:center; width:22px; height:22px; border-radius: var(--radius-sm,6px); cursor:pointer; user-select:none; color: inherit; background: transparent; border:none;
+
+        padding: var(--spacing-0) var(--spacing-6, 8px);
+
+       }
       .tbtn:hover { background: var(--color-surface-hover, color-mix(in oklab, CanvasText 12%, transparent)); }
       .edwrap { position:relative; }
-      .ed { display: block; min-height:90px; max-height: 400px; overflow:auto; padding: var(--spacing-1, 0) var(--spacing-2, 0); outline:none; word-break:break-word; border-radius: 0 0 var(--radius-md,8px) var(--radius-md,8px); background: var(--rt-editor-bg, var(--color-input-bg)); }
+      .ed { display: block; font-weight: normal; min-height:90px; max-height: 400px; overflow:auto; padding: var(--spacing-1, 0) var(--spacing-2, 0); outline:none; word-break:break-word; border-radius: 0 0 var(--radius-md,8px) var(--radius-md,8px); background: var(--rt-editor-bg, var(--color-input-bg)); }
       .ed[contenteditable="true"]:empty::before { content: attr(data-ph); color: var(--rt-muted, var(--color-text-muted)); pointer-events:none; }
       .send { margin-left:auto; display:inline-flex; gap: var(--spacing-2,8px); align-items:center; }
       button.icon { background:transparent; border:0; color:inherit; cursor:pointer; padding:6px; border-radius: var(--radius-sm,6px); }
@@ -589,9 +599,28 @@ export class RichText extends HTMLElement {
 
   #toggleCode() {
     // Wrap selection with <code> or unwrap if already in code
-    const sel = window.getSelection();
+    const root = this.shadowRoot;
+    const getSel = () =>
+      root && typeof root.getSelection === "function"
+        ? root.getSelection()
+        : window.getSelection();
+    let sel = getSel();
     if (!sel || sel.rangeCount === 0) return;
-    const range = sel.getRangeAt(0);
+    let range = sel.getRangeAt(0);
+    const inEditor = (r) => {
+      const node =
+        r.commonAncestorContainer.nodeType === 1
+          ? r.commonAncestorContainer
+          : r.commonAncestorContainer.parentNode;
+      return !!(node && this.#editorDiv && this.#editorDiv.contains(node));
+    };
+    if (!inEditor(range)) {
+      this.#focus();
+      sel = getSel();
+      if (!sel || sel.rangeCount === 0) return;
+      range = sel.getRangeAt(0);
+      if (!inEditor(range)) return;
+    }
     // Simple toggle: if ancestor <code>, unwrap; else wrap
     const codeAncestor = this.#closestAncestor(
       range.commonAncestorContainer,
@@ -604,7 +633,28 @@ export class RichText extends HTMLElement {
       parent.removeChild(codeAncestor);
     } else {
       const wrapper = document.createElement("code");
-      range.surroundContents(wrapper);
+      if (range.collapsed) {
+        const caret = document.createTextNode("\u200B");
+        wrapper.appendChild(caret);
+        range.insertNode(wrapper);
+        const next = document.createRange();
+        next.setStart(caret, 1);
+        next.collapse(true);
+        sel.removeAllRanges();
+        sel.addRange(next);
+      } else {
+        try {
+          range.surroundContents(wrapper);
+        } catch {
+          const contents = range.extractContents();
+          wrapper.appendChild(contents);
+          range.insertNode(wrapper);
+        }
+        const next = document.createRange();
+        next.selectNodeContents(wrapper);
+        sel.removeAllRanges();
+        sel.addRange(next);
+      }
     }
   }
 

package/public/assets/pds/components/pds-theme.js

@@ -13,6 +13,39 @@ const THEME_OPTIONS = [
 
 const DEFAULT_LABEL = "Theme";
 const LAYERS = ["tokens", "primitives", "components", "utilities"];
+const DEFAULT_THEMES = ["light", "dark"];
+const VALID_THEMES = new Set(DEFAULT_THEMES);
+
+const normalizePresetThemes = (preset) => {
+  const themes = Array.isArray(preset?.themes)
+    ? preset.themes.map((theme) => String(theme).toLowerCase())
+    : DEFAULT_THEMES;
+  const normalized = themes.filter((theme) => VALID_THEMES.has(theme));
+  return normalized.length ? normalized : DEFAULT_THEMES;
+};
+
+const resolveThemePreference = (preference) => {
+  const normalized = String(preference || "").toLowerCase();
+  if (VALID_THEMES.has(normalized)) return normalized;
+
+  if (typeof document !== "undefined") {
+    const applied = document.documentElement?.getAttribute("data-theme");
+    if (VALID_THEMES.has(applied)) return applied;
+  }
+
+  if (typeof window !== "undefined" && window.matchMedia) {
+    const prefersDark = window.matchMedia("(prefers-color-scheme: dark)").matches;
+    return prefersDark ? "dark" : "light";
+  }
+
+  return "light";
+};
+
+const isPresetThemeCompatible = (preset, themePreference) => {
+  const resolvedTheme = resolveThemePreference(themePreference);
+  const themes = normalizePresetThemes(preset);
+  return themes.includes(resolvedTheme);
+};
 
 class PdsTheme extends HTMLElement {
   static get observedAttributes() {
@@ -123,6 +156,21 @@ class PdsTheme extends HTMLElement {
       return;
     }
 
+    const currentPreset = PDS.currentConfig?.design || null;
+    if (currentPreset && !isPresetThemeCompatible(currentPreset, value)) {
+      const resolvedTheme = resolveThemePreference(value);
+      const presetName =
+        currentPreset?.name ||
+        PDS.currentPreset?.name ||
+        PDS.currentConfig?.preset ||
+        "current preset";
+      console.warn(
+        `PDS theme "${resolvedTheme}" not supported by preset "${presetName}".`
+      );
+      this.#syncCheckedState();
+      return;
+    }
+
     if (PDS.theme !== value) {
       PDS.theme = value;
     }
@@ -157,10 +205,20 @@ class PdsTheme extends HTMLElement {
 
   #syncCheckedState() {
     const currentTheme = PDS.theme || "system";
+    const currentPreset = PDS.currentConfig?.design || null;
+    const supportedThemes = normalizePresetThemes(currentPreset);
     this.shadowRoot
       .querySelectorAll('input[type="radio"]')
       .forEach((radio) => {
         radio.checked = radio.value === currentTheme;
+        if (radio.value === "system") {
+          radio.disabled = false;
+        } else if (currentPreset) {
+          const resolved = resolveThemePreference(radio.value);
+          radio.disabled = !supportedThemes.includes(resolved);
+        } else {
+          radio.disabled = false;
+        }
       });
   }
 }

package/readme.md

@@ -6,7 +6,7 @@
 [![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](#license)
 [![npm version](https://img.shields.io/npm/v/@pure-ds/core.svg)](https://www.npmjs.com/package/@pure-ds/core)
 
-![Pure Design System logo](public/assets/img/logo.png)
+![Pure Design System logo](public/assets/img/pds-logo.svg)
 
 ## With Great Standards Comes Great Power
 
@@ -571,7 +571,7 @@ PDS.dispatchEvent(new CustomEvent('pds:toast', {
 <script type="importmap">
   {
     "imports": {
-      "#showdown": "https://cdn.jsdelivr.net/npm/showdown@2.1.0/dist/showdown.mjs"
+      "#showdown": "https://cdn.jsdelivr.net/npm/showdown@2.1.0/+esm"
     }
   }
 </script>

package/src/js/pds-core/pds-config.js

@@ -187,6 +187,7 @@ import { enums } from "./pds-enums.js";
  * @property {PDSAutoDefineConfig} [autoDefine]
  * @property {string} [managerURL]
  * @property {any} [manager]
+ * @property {boolean} [liveEdit]
  * @property {any} [log]
  */
 
@@ -565,16 +566,31 @@ const __INIT_CONFIG_SPEC__ = {
   properties: {
     mode: { type: "string" },
     preset: { type: "string" },
-    design: { type: "object" },
+    design: __DESIGN_CONFIG_SPEC__,
     enhancers: { type: ["object", "array"] },
     applyGlobalStyles: { type: "boolean" },
     manageTheme: { type: "boolean" },
     themeStorageKey: { type: "string" },
     preloadStyles: { type: "boolean" },
     criticalLayers: { type: "array", items: { type: "string" } },
-    autoDefine: { type: "object" },
+    autoDefine: {
+      type: "object",
+      allowUnknown: false,
+      properties: {
+        predefine: { type: "array", items: { type: "string" } },
+        mapper: { type: __ANY_TYPE__ },
+        enhancers: { type: ["object", "array"] },
+        scanExisting: { type: "boolean" },
+        observeShadows: { type: "boolean" },
+        patchAttachShadow: { type: "boolean" },
+        debounceMs: { type: "number" },
+        onError: { type: __ANY_TYPE__ },
+        baseURL: { type: "string" },
+      },
+    },
     managerURL: { type: "string" },
     manager: { type: __ANY_TYPE__ },
+    liveEdit: { type: "boolean" },
     log: { type: __ANY_TYPE__ },
   },
 };
@@ -799,6 +815,7 @@ export const presets = {
     id: "paper-and-ink",
     name: "Paper & Ink",
     tags: ["app", "featured"],
+    themes: ["light"], // Not optimized for dark mode 
     description: "Ultra-minimal design with focus on typography and whitespace",
     colors: {
       primary: "#171717",
@@ -1037,6 +1054,7 @@ export const presets = {
   "pastel-play": {
     id: "pastel-play",
     name: "Pastel Play",
+    themes: ["light"], // Not optimized for dark mode due to pastel contrast challenges
     description:
       "Playful pastels with soft surfaces and friendly rounded shapes",
     colors: {
@@ -1081,7 +1099,7 @@ export const presets = {
       accent: "#06b6d4", // cyan signal
       background: "#f8fafc",
       darkMode: {
-        background: "#0b0b0b",
+        background: "#0c0c0c",
         secondary: "#9ca3af",
         // Set a chromatic primary in dark mode to ensure both:
         // - outline/link contrast on dark surface, and

package/src/js/pds-core/pds-enhancers.js

@@ -77,16 +77,55 @@ function enhanceDropdown(elem) {
   }
 
   const resolveDirection = () => {
-    const mode = (elem.getAttribute("data-mode") || "auto").toLowerCase();
+    const mode = (
+      elem.getAttribute("data-direction") ||
+      elem.getAttribute("data-dropdown-direction") ||
+      elem.getAttribute("data-mode") ||
+      "auto"
+    ).toLowerCase();
     if (mode === "up" || mode === "down") return mode;
     const rect = elem.getBoundingClientRect();
+    const menuRect = menu?.getBoundingClientRect?.() || { height: 0 };
+    const menuHeight = Math.max(
+      menu?.offsetHeight || 0,
+      menu?.scrollHeight || 0,
+      menuRect.height || 0,
+      200
+    );
     const spaceBelow = Math.max(0, window.innerHeight - rect.bottom);
     const spaceAbove = Math.max(0, rect.top);
+    if (spaceBelow >= menuHeight) return "down";
+    if (spaceAbove >= menuHeight) return "up";
     return spaceAbove > spaceBelow ? "up" : "down";
   };
 
+  const resolveAlign = () => {
+    const align = (
+      elem.getAttribute("data-align") ||
+      elem.getAttribute("data-dropdown-align") ||
+      "auto"
+    ).toLowerCase();
+    if (align === "left" || align === "right" || align === "start" || align === "end") {
+      return align === "start" ? "left" : align === "end" ? "right" : align;
+    }
+    const rect = elem.getBoundingClientRect();
+    const menuRect = menu?.getBoundingClientRect?.() || { width: 0 };
+    const menuWidth = Math.max(
+      menu?.offsetWidth || 0,
+      menu?.scrollWidth || 0,
+      menuRect.width || 0,
+      240
+    );
+    const spaceRight = Math.max(0, window.innerWidth - rect.left);
+    const spaceLeft = Math.max(0, rect.right);
+    if (spaceRight >= menuWidth) return "left";
+    if (spaceLeft >= menuWidth) return "right";
+    return spaceLeft > spaceRight ? "right" : "left";
+  };
+
   const openMenu = () => {
     elem.dataset.dropdownDirection = resolveDirection();
+    elem.dataset.dropdownAlign = resolveAlign();
     menu.setAttribute("aria-hidden", "false");
     trigger?.setAttribute("aria-expanded", "true");
   };
@@ -264,16 +303,34 @@ function enhanceRequired(elem) {
     elem.dataset.enhancedRequired = "true";
   
   const enhanceRequiredField = (input) => {
-   
-    const label = input.closest("label");
+    let label;
+    if(input.closest("[role$=group]")) { // Handles both radiogroup and group
+      label = input.closest("[role$=group]").querySelector("legend");
+    }
+    else{
+      label = input.closest("label");
+    }
     if (!label) return;
+    
+
     if (label.querySelector(".required-asterisk")) return;
 
     const asterisk = document.createElement("span");
     asterisk.classList.add("required-asterisk");
     asterisk.textContent = "*";
     asterisk.style.marginLeft = "4px";
-    label.querySelector("span").appendChild(asterisk);
+
+    const labelText = label.querySelector("span, [data-label]");
+    if (labelText) {
+      labelText.appendChild(asterisk);
+    } else {
+      const field = label.querySelector("input, select, textarea");
+      if (field) {
+        label.insertBefore(asterisk, field);
+      } else {
+        label.appendChild(asterisk);
+      }
+    }
 
     const form = input.closest("form");
     if (form && !form.querySelector(".required-legend")) {

package/src/js/pds-core/pds-live.js

@@ -4,7 +4,7 @@
  */
 import { Generator } from "./pds-generator.js";
 import { applyStyles, adoptLayers, adoptPrimitives } from "./pds-runtime.js";
-import { presets, defaultLog } from "./pds-config.js";
+import { presets, defaultLog, PDS_CONFIG_RELATIONS } from "./pds-config.js";
 import { defaultPDSEnhancers } from "./pds-enhancers.js";
 import { defaultPDSEnhancerMetadata } from "./pds-enhancers-meta.js";
 import { resolvePublicAssetURL } from "./pds-paths.js";
@@ -19,10 +19,77 @@ import {
   setupAutoDefinerAndEnhancers,
   stripFunctions,
 } from "./pds-start-helpers.js";
+import {
+  isPresetThemeCompatible,
+  resolveThemePreference,
+} from "./pds-theme-utils.js";
 
 let __liveApiReady = false;
 let __queryClass = null;
 
+function getStoredLiveConfig() {
+  if (typeof window === "undefined" || !window.localStorage) return null;
+  try {
+    const raw = window.localStorage.getItem("pure-ds-config");
+    if (!raw) return null;
+    const parsed = JSON.parse(raw);
+    if (parsed && ("preset" in parsed || "design" in parsed)) return parsed;
+  } catch (e) {
+    return null;
+  }
+  return null;
+}
+
+function deepMergeConfig(target = {}, source = {}) {
+  if (!source || typeof source !== "object") return target;
+  const out = Array.isArray(target) ? [...target] : { ...target };
+  for (const [key, value] of Object.entries(source)) {
+    if (value && typeof value === "object" && !Array.isArray(value)) {
+      out[key] = deepMergeConfig(
+        out[key] && typeof out[key] === "object" ? out[key] : {},
+        value
+      );
+    } else {
+      out[key] = value;
+    }
+  }
+  return out;
+}
+
+function applyStoredConfigOverrides(baseConfig) {
+  const stored = getStoredLiveConfig();
+  if (!stored || !baseConfig || typeof baseConfig !== "object") return baseConfig;
+
+  const storedPreset = stored.preset;
+  const storedDesign =
+    stored.design && typeof stored.design === "object" ? stored.design : null;
+
+  if (!storedPreset && !storedDesign) return baseConfig;
+
+  const hasNewShape =
+    "preset" in baseConfig || "design" in baseConfig || "enhancers" in baseConfig;
+
+  let nextConfig = { ...baseConfig };
+
+  if (storedPreset) {
+    nextConfig.preset = storedPreset;
+  }
+
+  if (storedDesign) {
+    if (hasNewShape) {
+      const baseDesign =
+        baseConfig.design && typeof baseConfig.design === "object"
+          ? baseConfig.design
+          : {};
+      nextConfig.design = deepMergeConfig(baseDesign, storedDesign);
+    } else {
+      nextConfig = deepMergeConfig(baseConfig, storedDesign);
+    }
+  }
+
+  return nextConfig;
+}
+
 async function __attachLiveAPIs(PDS, { applyResolvedTheme, setupSystemListenerIfNeeded }) {
   if (__liveApiReady) return;
 
@@ -45,6 +112,7 @@ async function __attachLiveAPIs(PDS, { applyResolvedTheme, setupSystemListenerIf
   PDS.enums = enums;
   PDS.common = commonModule || {};
   PDS.presets = presets;
+  PDS.configRelations = PDS_CONFIG_RELATIONS;
   PDS.enhancerMetadata = defaultPDSEnhancerMetadata;
   PDS.applyStyles = function(generator) {
     return applyStyles(generator || Generator.instance);
@@ -73,6 +141,91 @@ async function __attachLiveAPIs(PDS, { applyResolvedTheme, setupSystemListenerIf
     return await queryEngine.search(question);
   };
 
+  PDS.applyLivePreset = async function(presetId, options = {}) {
+    if (!presetId) return false;
+    if (!PDS.registry?.isLive) {
+      console.warn("PDS.applyLivePreset is only available in live mode.");
+      return false;
+    }
+
+    const baseConfig = PDS.currentConfig || {};
+    const { design: _design, preset: _preset, ...rest } = baseConfig;
+    const inputConfig = {
+      ...structuredClone(stripFunctions(rest)),
+      preset: presetId,
+    };
+
+    const normalized = normalizeInitConfig(inputConfig, {}, {
+      presets,
+      defaultLog,
+    });
+
+    const resolvedTheme = resolveThemePreference(PDS.theme);
+    if (!isPresetThemeCompatible(normalized.generatorConfig.design, resolvedTheme)) {
+      const presetName =
+        normalized.presetInfo?.name ||
+        normalized.generatorConfig?.design?.name ||
+        presetId;
+      console.warn(
+        `PDS theme "${resolvedTheme}" not supported by preset "${presetName}".`
+      );
+    }
+
+    if (baseConfig.theme && !normalized.generatorConfig.theme) {
+      normalized.generatorConfig.theme = baseConfig.theme;
+    }
+
+    const generator = new Generator(normalized.generatorConfig);
+
+    if (normalized.generatorConfig.design?.typography) {
+      try {
+        await loadTypographyFonts(normalized.generatorConfig.design.typography);
+      } catch (error) {
+        normalized.generatorConfig?.log?.(
+          "warn",
+          "Failed to load some fonts from Google Fonts:",
+          error,
+        );
+      }
+    }
+
+    await applyStyles(generator);
+
+    const presetInfo = normalized.presetInfo || { id: presetId, name: presetId };
+    PDS.currentPreset = presetInfo;
+    PDS.currentConfig = Object.freeze({
+      ...baseConfig,
+      preset: normalized.generatorConfig.preset,
+      design: structuredClone(normalized.generatorConfig.design),
+      theme: normalized.generatorConfig.theme || baseConfig.theme,
+    });
+
+    const persist = options?.persist !== false;
+    if (persist && typeof window !== "undefined") {
+      const storageKey = "pure-ds-config";
+      try {
+        const storedRaw = localStorage.getItem(storageKey);
+        const storedParsed = storedRaw ? JSON.parse(storedRaw) : null;
+        const nextStored = {
+          ...(storedParsed && typeof storedParsed === "object"
+            ? storedParsed
+            : {}),
+          preset: presetInfo.id || presetId,
+          design: structuredClone(normalized.generatorConfig.design || {}),
+        };
+        localStorage.setItem(storageKey, JSON.stringify(nextStored));
+      } catch (error) {
+        normalized.generatorConfig?.log?.(
+          "warn",
+          "Failed to store preset:",
+          error,
+        );
+      }
+    }
+
+    return true;
+  };
+
   // Live-only compiled getter
   if (!Object.getOwnPropertyDescriptor(PDS, "compiled")) {
     Object.defineProperty(PDS, "compiled", {
@@ -147,6 +300,8 @@ export async function startLive(PDS, config, { emitReady, applyResolvedTheme, se
     );
   }
 
+  config = applyStoredConfigOverrides(config);
+
   // Attach live-only API surface (ontology, presets, query, etc.)
   await __attachLiveAPIs(PDS, { applyResolvedTheme, setupSystemListenerIfNeeded });
   attachFoucListener(PDS);
@@ -197,6 +352,16 @@ export async function startLive(PDS, config, { emitReady, applyResolvedTheme, se
 
     // 2) Normalize first-arg API: support { preset, design, enhancers }
     const normalized = normalizeInitConfig(config, {}, { presets, defaultLog });
+    if (manageTheme && !isPresetThemeCompatible(normalized.generatorConfig.design, resolvedTheme)) {
+      const presetName =
+        normalized.presetInfo?.name ||
+        normalized.generatorConfig?.design?.name ||
+        normalized.generatorConfig?.preset ||
+        "current preset";
+      console.warn(
+        `PDS theme "${resolvedTheme}" not supported by preset "${presetName}".`
+      );
+    }
     const userEnhancers = normalized.enhancers;
     const { log: logFn, ...configToClone } = normalized.generatorConfig;
     const generatorConfig = structuredClone(configToClone);
@@ -345,6 +510,20 @@ export async function startLive(PDS, config, { emitReady, applyResolvedTheme, se
       enhancers: mergedEnhancers,
     });
 
+    
+    if (config?.liveEdit && typeof document !== "undefined") {
+      try {
+        if (!document.querySelector("pds-live-edit")) {
+          setTimeout(() => {
+            const liveEditor = document.createElement("pds-live-edit");
+            document.body.appendChild(liveEditor);  
+          }, 1000);
+        }
+      } catch (error) {
+        generatorConfig?.log?.("warn", "Live editor failed to start:", error);
+      }
+    }
+
     emitReady({
       mode: "live",
       generator,

package/src/js/pds-core/pds-ontology.js

@@ -246,6 +246,14 @@ export const ontology = {
       tags: ["form", "schema", "auto-generate"],
       category: "form"
     },
+    { 
+      id: "pds-live-edit", 
+      name: "Live Edit", 
+      description: "Contextual live editing for PDS design settings",
+      selectors: ["pds-live-edit"],
+      tags: ["editor", "live", "config", "tooling"],
+      category: "tooling"
+    },
     { 
       id: "pds-splitpanel", 
       name: "Split Panel", 

package/src/js/pds-core/pds-theme-utils.js

@@ -0,0 +1,33 @@
+const DEFAULT_THEMES = ["light", "dark"];
+const VALID_THEMES = new Set(DEFAULT_THEMES);
+
+export function normalizePresetThemes(preset) {
+  const themes = Array.isArray(preset?.themes)
+    ? preset.themes.map((theme) => String(theme).toLowerCase())
+    : DEFAULT_THEMES;
+  const normalized = themes.filter((theme) => VALID_THEMES.has(theme));
+  return normalized.length ? normalized : DEFAULT_THEMES;
+}
+
+export function resolveThemePreference(preference, { preferDocument = true } = {}) {
+  const normalized = String(preference || "").toLowerCase();
+  if (VALID_THEMES.has(normalized)) return normalized;
+
+  if (preferDocument && typeof document !== "undefined") {
+    const applied = document.documentElement?.getAttribute("data-theme");
+    if (VALID_THEMES.has(applied)) return applied;
+  }
+
+  if (typeof window !== "undefined" && window.matchMedia) {
+    const prefersDark = window.matchMedia("(prefers-color-scheme: dark)").matches;
+    return prefersDark ? "dark" : "light";
+  }
+
+  return "light";
+}
+
+export function isPresetThemeCompatible(preset, themePreference) {
+  const resolvedTheme = resolveThemePreference(themePreference);
+  const themes = normalizePresetThemes(preset);
+  return themes.includes(resolvedTheme);
+}

package/src/js/pds.d.ts

@@ -104,6 +104,9 @@ export interface CompiledState {
   };
 }
 
+/** Public config types for editor IntelliSense */
+export type PDSInitConfig = import("./pds-core/pds-config.js").PDSInitConfig;
+
 /**
  * Generator - programmatic API to produce tokens, layered CSS and helper modules from a config.
  * Typical usage:

package/src/js/pds.js

@@ -68,6 +68,10 @@ import {
   setupAutoDefinerAndEnhancers,
   stripFunctions,
 } from "./pds-core/pds-start-helpers.js";
+import {
+  isPresetThemeCompatible,
+  resolveThemePreference,
+} from "./pds-core/pds-theme-utils.js";
 
 const __slugifyPreset = (str = "") =>
   String(str)
@@ -261,6 +265,24 @@ Object.defineProperty(PDS, "theme", {
   set(value) {
     try {
       if (typeof window === "undefined") return;
+      const currentPreset = PDS.currentConfig?.design || null;
+      const resolvedTheme = resolveThemePreference(value);
+      if (currentPreset && !isPresetThemeCompatible(currentPreset, resolvedTheme)) {
+        const presetName =
+          currentPreset?.name ||
+          PDS.currentPreset?.name ||
+          PDS.currentConfig?.preset ||
+          "current preset";
+        console.warn(
+          `PDS theme "${resolvedTheme}" not supported by preset "${presetName}".`
+        );
+        PDS.dispatchEvent(
+          new CustomEvent("pds:theme:blocked", {
+            detail: { theme: value, resolvedTheme, preset: presetName },
+          })
+        );
+        return;
+      }
       if (value === null || value === undefined) {
         localStorage.removeItem(__themeStorageKey);
       } else {