@pure-ds/core 0.4.26 → 0.4.28

package/public/assets/pds/custom-elements.json

@@ -1,4 +1,4 @@
-{
+{
   "schemaVersion": "1.0.0",
   "readme": "",
   "modules": [
@@ -506,169 +506,6 @@
         }
       ]
     },
-    {
-      "kind": "javascript-module",
-      "path": "public/assets/pds/components/pds-icon.js",
-      "declarations": [
-        {
-          "kind": "class",
-          "description": "SVG Icon Web Component",
-          "name": "SvgIcon",
-          "members": [
-            {
-              "kind": "field",
-              "name": "spritePromises",
-              "static": true,
-              "default": "new Map()"
-            },
-            {
-              "kind": "field",
-              "name": "inlineSprites",
-              "static": true,
-              "default": "new Map()"
-            },
-            {
-              "kind": "field",
-              "name": "externalIconCache",
-              "static": true,
-              "default": "new Map()"
-            },
-            {
-              "kind": "field",
-              "name": "externalIconPromises",
-              "static": true,
-              "default": "new Map()"
-            },
-            {
-              "kind": "field",
-              "name": "instances",
-              "static": true,
-              "default": "new Set()"
-            },
-            {
-              "kind": "method",
-              "name": "spriteAvailable",
-              "description": "Check if sprite sheet is available",
-              "privacy": "public",
-              "return": {
-                "type": {
-                  "text": "boolean"
-                }
-              }
-            },
-            {
-              "kind": "method",
-              "name": "fetchExternalIcon",
-              "static": true,
-              "parameters": [
-                {
-                  "name": "iconName",
-                  "description": "The icon name (without .svg extension)",
-                  "type": {
-                    "text": "string"
-                  }
-                }
-              ],
-              "description": "Fetch an external SVG icon and cache it",
-              "return": {
-                "type": {
-                  "text": "Promise<boolean>"
-                }
-              }
-            },
-            {
-              "kind": "method",
-              "name": "ensureInlineSprite",
-              "static": true,
-              "parameters": [
-                {
-                  "name": "spriteURL"
-                }
-              ]
-            },
-            {
-              "kind": "method",
-              "name": "notifyInstances",
-              "static": true
-            }
-          ],
-          "attributes": [
-            {
-              "name": "icon",
-              "type": {
-                "text": "string"
-              },
-              "description": "Icon name from the sprite sheet"
-            },
-            {
-              "name": "size",
-              "type": {
-                "text": "string|number"
-              },
-              "description": "Icon size in pixels or named size (xs, sm, md, lg, xl, 2xl)"
-            },
-            {
-              "name": "color",
-              "type": {
-                "text": "string"
-              },
-              "description": "Icon color (CSS color value, default: currentColor)"
-            },
-            {
-              "name": "label",
-              "type": {
-                "text": "string"
-              },
-              "description": "Accessible label for the icon (adds role=\"img\")"
-            },
-            {
-              "name": "rotate",
-              "type": {
-                "text": "number"
-              },
-              "description": "Rotation angle in degrees"
-            },
-            {
-              "type": {
-                "text": "string"
-              },
-              "description": "Override sprite sheet path",
-              "name": "sprite"
-            },
-            {
-              "type": {
-                "text": "boolean"
-              },
-              "description": "Force fallback icon rendering",
-              "name": "no-sprite"
-            }
-          ],
-          "superclass": {
-            "name": "HTMLElement"
-          },
-          "tagName": "pds-icon",
-          "customElement": true
-        }
-      ],
-      "exports": [
-        {
-          "kind": "js",
-          "name": "SvgIcon",
-          "declaration": {
-            "name": "SvgIcon",
-            "module": "public/assets/pds/components/pds-icon.js"
-          }
-        },
-        {
-          "kind": "custom-element-definition",
-          "name": "pds-icon",
-          "declaration": {
-            "name": "SvgIcon",
-            "module": "public/assets/pds/components/pds-icon.js"
-          }
-        }
-      ]
-    },
     {
       "kind": "javascript-module",
       "path": "public/assets/pds/components/pds-form.js",
@@ -711,6 +548,10 @@
               "kind": "method",
               "name": "submit"
             },
+            {
+              "kind": "method",
+              "name": "reset"
+            },
             {
               "kind": "field",
               "name": "jsonSchema",
@@ -978,6 +819,169 @@
         }
       ]
     },
+    {
+      "kind": "javascript-module",
+      "path": "public/assets/pds/components/pds-icon.js",
+      "declarations": [
+        {
+          "kind": "class",
+          "description": "SVG Icon Web Component",
+          "name": "SvgIcon",
+          "members": [
+            {
+              "kind": "field",
+              "name": "spritePromises",
+              "static": true,
+              "default": "new Map()"
+            },
+            {
+              "kind": "field",
+              "name": "inlineSprites",
+              "static": true,
+              "default": "new Map()"
+            },
+            {
+              "kind": "field",
+              "name": "externalIconCache",
+              "static": true,
+              "default": "new Map()"
+            },
+            {
+              "kind": "field",
+              "name": "externalIconPromises",
+              "static": true,
+              "default": "new Map()"
+            },
+            {
+              "kind": "field",
+              "name": "instances",
+              "static": true,
+              "default": "new Set()"
+            },
+            {
+              "kind": "method",
+              "name": "spriteAvailable",
+              "description": "Check if sprite sheet is available",
+              "privacy": "public",
+              "return": {
+                "type": {
+                  "text": "boolean"
+                }
+              }
+            },
+            {
+              "kind": "method",
+              "name": "fetchExternalIcon",
+              "static": true,
+              "parameters": [
+                {
+                  "name": "iconName",
+                  "description": "The icon name (without .svg extension)",
+                  "type": {
+                    "text": "string"
+                  }
+                }
+              ],
+              "description": "Fetch an external SVG icon and cache it",
+              "return": {
+                "type": {
+                  "text": "Promise<boolean>"
+                }
+              }
+            },
+            {
+              "kind": "method",
+              "name": "ensureInlineSprite",
+              "static": true,
+              "parameters": [
+                {
+                  "name": "spriteURL"
+                }
+              ]
+            },
+            {
+              "kind": "method",
+              "name": "notifyInstances",
+              "static": true
+            }
+          ],
+          "attributes": [
+            {
+              "name": "icon",
+              "type": {
+                "text": "string"
+              },
+              "description": "Icon name from the sprite sheet"
+            },
+            {
+              "name": "size",
+              "type": {
+                "text": "string|number"
+              },
+              "description": "Icon size in pixels or named size (xs, sm, md, lg, xl, 2xl)"
+            },
+            {
+              "name": "color",
+              "type": {
+                "text": "string"
+              },
+              "description": "Icon color (CSS color value, default: currentColor)"
+            },
+            {
+              "name": "label",
+              "type": {
+                "text": "string"
+              },
+              "description": "Accessible label for the icon (adds role=\"img\")"
+            },
+            {
+              "name": "rotate",
+              "type": {
+                "text": "number"
+              },
+              "description": "Rotation angle in degrees"
+            },
+            {
+              "type": {
+                "text": "string"
+              },
+              "description": "Override sprite sheet path",
+              "name": "sprite"
+            },
+            {
+              "type": {
+                "text": "boolean"
+              },
+              "description": "Force fallback icon rendering",
+              "name": "no-sprite"
+            }
+          ],
+          "superclass": {
+            "name": "HTMLElement"
+          },
+          "tagName": "pds-icon",
+          "customElement": true
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "SvgIcon",
+          "declaration": {
+            "name": "SvgIcon",
+            "module": "public/assets/pds/components/pds-icon.js"
+          }
+        },
+        {
+          "kind": "custom-element-definition",
+          "name": "pds-icon",
+          "declaration": {
+            "name": "SvgIcon",
+            "module": "public/assets/pds/components/pds-icon.js"
+          }
+        }
+      ]
+    },
     {
       "kind": "javascript-module",
       "path": "public/assets/pds/components/pds-richtext.js",

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

@@ -1,4 +1,118 @@
-import { enhancerMetadata } from "./pds-enhancer-metadata.js";
+/**
+ * PDS Enhancers - Single Source of Truth
+ * 
+ * This file defines all progressive enhancements for the Pure Design System.
+ * Each enhancer has:
+ * - selector: CSS selector to target elements
+ * - description: Human-readable explanation
+ * - demoHtml: Example usage markup
+ * - run: Enhancement function (added at the end)
+ */
+
+// ============================================================================
+// ENHANCEMENT METADATA DEFINITIONS
+// ============================================================================
+
+const enhancerDefinitions = [
+  {
+    selector: ".accordion",
+    description:
+      "Ensures only one <details> element can be open at a time within the accordion.",
+    demoHtml: `
+      <div class="accordion">
+        <details>
+          <summary>Section 1</summary>
+          <p>Content for section 1</p>
+        </details>
+        <details>
+          <summary>Section 2</summary>
+          <p>Content for section 2</p>
+        </details>
+        <details>
+          <summary>Section 3</summary>
+          <p>Content for section 3</p>
+        </details>
+      </div>
+    `.trim(),
+  },
+  {
+    selector: "nav[data-dropdown]",
+    description:
+      "Enhances a nav element with data-dropdown to function as a dropdown menu.",
+    demoHtml: `
+      <nav data-dropdown>
+        <button class="btn-primary">Menu</button>
+        <menu>
+          <li><a href="#">Item 1</a></li>
+          <li><a href="#">Item 2</a></li>
+        </menu>
+      </nav>
+    `.trim(),
+  },
+  {
+    selector: "label[data-toggle]",
+    description: "Creates a toggle switch element from a checkbox.",
+    demoHtml: `
+      <label data-toggle>
+        <input type="checkbox">
+        <span data-label>Enable notifications</span>
+      </label>
+    `.trim(),
+  },
+  {
+    selector: 'input[type="range"]',
+    description: "Enhances range inputs with an attached <output>.",
+    demoHtml: `
+      <label class="range-output">
+        <span data-label>Volume</span>
+        <input type="range" min="0" max="100" value="40">
+      </label>
+    `.trim(),
+  },
+  {
+    selector: "form[data-required]",
+    description:
+      "Enhances required form fields using an asterisk in the label.",
+    demoHtml: `
+      <form data-required action="#" method="post">
+      <label>
+        <span>Field Label</span>
+        <input type="text" required>
+      </label>
+        <nav class="form-actions">
+          <button type="submit" class="btn-primary">Submit</button>
+        </nav>
+      </form>
+    `.trim(),
+  },
+  {
+    selector: "fieldset[role=group][data-open]",
+    description:
+      "Enhances a checkbox/radio group to be open (have a way to add and remove items).",
+    demoHtml: `
+      <fieldset role="group" data-open>
+        <label>
+          <span data-label>Test</span>
+          <input value="lala" name="test1" type="radio" />
+        </label>
+      </fieldset>
+    `.trim(),
+  },
+  {
+    selector: "button, a[class*='btn-']",
+    description:
+      "Automatically manages spinner icon for buttons with .btn-working class",
+    demoHtml: `
+      <button class="btn-primary btn-working">
+        <span>Saving</span>
+      </button>
+    `.trim(),
+  },
+];
+
+// ============================================================================
+// ENHANCEMENT RUNTIME FUNCTIONS
+// ============================================================================
 
 function enhanceAccordion(elem) {
   if (elem.dataset.enhancedAccordion) return;
@@ -367,6 +481,11 @@ function enhanceButtonWorking(elem) {
   });
 }
 
+// ============================================================================
+// EXPORTS
+// ============================================================================
+
+// Map selectors to their run functions
 const enhancerRunners = new Map([
   [".accordion", enhanceAccordion],
   ["nav[data-dropdown]", enhanceDropdown],
@@ -377,9 +496,23 @@ const enhancerRunners = new Map([
   ["button, a[class*='btn-']", enhanceButtonWorking],
 ]);
 
-export const defaultPDSEnhancers = enhancerMetadata.map((meta) => ({
+/**
+ * Complete enhancers with runtime functions.
+ * Used by PDS.enhancer() and AutoDefiner at runtime.
+ * 
+ * This is the canonical runtime array of enhancer objects.
+ */
+export const defaultPDSEnhancers = enhancerDefinitions.map((meta) => ({
   ...meta,
   run: enhancerRunners.get(meta.selector) || (() => {}),
 }));
 
-export const defaultPDSEnhancerMetadata = enhancerMetadata;
+/**
+ * Metadata-only export for build tools and documentation.
+ * This is semantically identical to enhancerDefinitions but exported
+ * for tooling that wants to explicitly access metadata without run functions.
+ * 
+ * Build tools can safely import defaultPDSEnhancers too - Node.js won't
+ * execute browser-only DOM code in the run functions.
+ */
+export const defaultPDSEnhancerMetadata = enhancerDefinitions;

package/src/js/pds.js

@@ -1033,7 +1033,7 @@ async function __setupAutoDefinerAndEnhancers(options) {
   }
   // Rely on AutoDefiner to run enhancers across light and shadow DOMs
 
-  return { autoDefiner };
+  return { autoDefiner, mergedEnhancers };
 }
 
 async function live(config) {
@@ -1226,6 +1226,7 @@ async function live(config) {
 
     // 5) Set up AutoDefiner + run enhancers (defaults merged with user)
     let autoDefiner = null;
+    let mergedEnhancers = [];
     try {
       const res = await __setupAutoDefinerAndEnhancers({
         autoDefineBaseURL: derivedAutoDefineBaseURL,
@@ -1240,6 +1241,7 @@ async function live(config) {
         autoDefinePreferModule: !(cfgAuto && cfgAuto.baseURL),
       });
       autoDefiner = res.autoDefiner;
+      mergedEnhancers = res.mergedEnhancers || [];
     } catch (error) {
       generatorConfig?.log?.("error", "❌ Failed to initialize AutoDefiner/Enhancers:", error);
     }
@@ -1256,6 +1258,7 @@ async function live(config) {
       design: structuredClone(normalized.generatorConfig.design),
       preset: normalized.generatorConfig.preset,
       theme: resolvedTheme,
+      enhancers: mergedEnhancers,
     });
 
     // Emit event to notify that PDS is ready (unified)
@@ -1394,6 +1397,7 @@ async function staticInit(config) {
 
     // 5) AutoDefiner + Enhancers
     let autoDefiner = null;
+    let mergedEnhancers = [];
     try {
       const res = await __setupAutoDefinerAndEnhancers({
         autoDefineBaseURL,
@@ -1404,6 +1408,7 @@ async function staticInit(config) {
         autoDefinePreferModule: !(cfgAuto && cfgAuto.baseURL),
       });
       autoDefiner = res.autoDefiner;
+      mergedEnhancers = res.mergedEnhancers || [];
     } catch (error) {
       // No config available in static mode, using console
       console.error(
@@ -1421,6 +1426,7 @@ async function staticInit(config) {
       design: structuredClone(normalized.generatorConfig.design),
       preset: normalized.generatorConfig.preset,
       theme: resolvedTheme,
+      enhancers: mergedEnhancers,
     });
 
     // 6) Emit ready event (unified)

package/CSS-INTELLISENSE-LIMITATION.md

@@ -1,98 +0,0 @@
-# ⚠️ CSS IntelliSense - Important Information
-
-## Where CSS IntelliSense Works
-
-✅ **CSS Files (.css)**
-```css
-/* Full autocomplete available */
-.my-class {
-  color: var(--color-primary-500);  /* ← Type var(-- to see all tokens */
-  padding: var(--spacing-4);
-}
-```
-
-✅ **HTML `<style>` Tags**
-```html
-<style>
-  .custom {
-    /* Full autocomplete available */
-    background: var(--color-primary-500);
-  }
-</style>
-```
-
-## Where It Does NOT Work
-
-❌ **Inline `style` Attributes** 
-```html
-<!-- NO IntelliSense here - This is a VS Code limitation -->
-<div style="padding: var(--)"></div>
-```
-
-This is not a PDS bug - it's a VS Code limitation. The `css.customData` setting only applies to CSS files and `<style>` tags, not inline style attributes.
-
-## Workarounds
-
-### 1. Use `<style>` Tags
-```html
-<style>
-  .my-padding {
-    padding: var(--spacing-4);  /* Full IntelliSense works here */
-  }
-</style>
-<div class="my-padding"></div>
-```
-
-### 2. Use Utility Classes
-PDS provides comprehensive utility classes:
-```html
-<div class="flex gap-4 items-center">
-  <div class="card surface-elevated">
-    Content
-  </div>
-</div>
-```
-
-### 3. Use External CSS File
-```css
-/* styles.css - Full IntelliSense */
-.hero {
-  background: var(--color-primary-500);
-  padding: var(--spacing-8);
-}
-```
-
-```html
-<div class="hero">Content</div>
-```
-
-## Verify It's Working
-
-1. **Create a test CSS file** (like `test.css`)
-2. **Type**: `color: var(--`
-3. **You should see**: All 165 CSS custom properties with descriptions
-4. **Hover over a token**: See the actual color/value
-
-If this doesn't work:
-1. Check `.vscode/settings.json` has `css.customData` configured
-2. Reload VS Code (Ctrl+Shift+P → "Developer: Reload Window")
-3. Make sure `pds.css-data.json` exists in `public/assets/pds/`
-
-## For Class Autocomplete
-
-Class autocomplete in HTML `class` attributes also has limitations in VS Code's HTML extension. For best class discovery:
-
-1. **Use Storybook** - Browse all available classes and components
-2. **Check documentation** - See [CSS-INTELLISENSE-QUICK-REF.md](./CSS-INTELLISENSE-QUICK-REF.md)
-3. **Use TypeScript** - Better autocomplete in JS/TS files
-
-## Summary
-
-| Location | CSS Tokens | Utility Classes | Works? |
-|----------|-----------|----------------|---------|
-| `.css` files | ✅ Yes | N/A | ✅ Full Support |
-| `<style>` tags | ✅ Yes | N/A | ✅ Full Support |
-| `style=""` attribute | ❌ No | N/A | ❌ VS Code Limitation |
-| `class=""` attribute | N/A | ⚠️ Limited | ⚠️ VS Code Limitation |
-
-**Bottom line**: Use CSS files or `<style>` tags for the best IntelliSense experience with PDS tokens!