@pure-ds/storybook 0.7.57 → 0.7.60

package/.storybook/preview.js

@@ -23,6 +23,9 @@ preloadShiki();
 window.toastFormData = toastFormData;
 
 let pdsCodeLoadPromise = null;
+let pdsStoryObserver = null;
+let pdsStoryObserverContainer = null;
+let pdsStoryAdoptTimeout = null;
 
 async function ensurePdsCodeLoaded() {
   if (typeof customElements !== 'undefined' && customElements.get('pds-code')) {
@@ -527,23 +530,15 @@ const withPDS = (story, context) => {
     // DON'T re-adopt if they already have styles - this preserves component internal stylesheets
     for (const { root, host } of shadowRoots) {
       try {
+        if (root.__pdsLayersAdopted === true) {
+          continue;
+        }
+
         const currentSheets = root.adoptedStyleSheets || [];
-        
-        // Check if this shadow root already has PDS sheets
-        const hasPDSSheets = currentSheets.some(sheet => {
-          try {
-            // Check if it's a PDS sheet by looking for PDS-specific selectors
-            return Array.from(sheet.cssRules || []).some(rule => 
-              rule.selectorText?.includes(':where') || 
-              rule.cssText?.includes('--color-') ||
-              rule.cssText?.includes('--spacing-')
-            );
-          } catch {
-            return false;
-          }
-        });
+        const hasPDSSheets = currentSheets.some(sheet => sheet?._pds === true);
         
         if (hasPDSSheets && currentSheets.length > 0) {
+          root.__pdsLayersAdopted = true;
           //console.log(`⏭️  <${host.toLowerCase()}> already has ${currentSheets.length} sheets - skipping`);
           continue;
         }
@@ -556,6 +551,7 @@ const withPDS = (story, context) => {
         
         // Adopt full layer stack: primitives, components, utilities
         await PDS.adoptLayers(root, ['primitives', 'components', 'utilities'], existingSheets);
+        root.__pdsLayersAdopted = true;
         
         //console.log(`✅ Adopted layers for <${host.toLowerCase()}> (now ${root.adoptedStyleSheets.length} sheets)`);
       } catch (err) {
@@ -578,34 +574,33 @@ const withPDS = (story, context) => {
   setTimeout(adoptAllShadowStyles, 100);
   setTimeout(adoptAllShadowStyles, 300);
   
-  // Re-adopt on any DOM changes (for re-renders) with debouncing
-  let adoptTimeout;
+  // Re-adopt on DOM tree changes with a single managed observer
   setTimeout(() => {
     const container = document.querySelector('#storybook-root');
-    if (container && !container._pdsObserver) {
+    if (container) {
+      if (pdsStoryObserver && pdsStoryObserverContainer !== container) {
+        pdsStoryObserver.disconnect();
+        pdsStoryObserver = null;
+      }
+
+      pdsStoryObserverContainer = container;
+
+      if (pdsStoryObserver) {
+        return;
+      }
+
       const debouncedAdopt = () => {
-        clearTimeout(adoptTimeout);
-        adoptTimeout = setTimeout(() => {
-          console.log('🔄 DOM changed - re-adopting primitives');
+        clearTimeout(pdsStoryAdoptTimeout);
+        pdsStoryAdoptTimeout = setTimeout(() => {
           adoptAllShadowStyles();
-        }, 100); // Increased debounce to 100ms
+        }, 120);
       };
       
-      const observer = new MutationObserver(debouncedAdopt);
-      observer.observe(container, { 
+      pdsStoryObserver = new MutationObserver(debouncedAdopt);
+      pdsStoryObserver.observe(container, {
         childList: true, 
         subtree: true,
-        attributes: true,
-        characterData: true // Also watch text changes
       });
-      container._pdsObserver = observer;
-      
-      // Also re-adopt periodically as fallback (every 1 second)
-      setInterval(() => {
-        if (document.contains(container)) {
-          adoptAllShadowStyles();
-        }
-      }, 1000);
     }
   }, 100);
   
@@ -1712,45 +1707,28 @@ const preview = {
       storySort: {
         method: 'alphabetical',
         order: [
-          'About PDS',
-          ['What Is PDS', 'Getting Started'],
           'PDS',
           [
-            'About PDS',
-            ['What Is PDS', 'Getting Started'],
-            'Foundations',
-            ['Colors', 'Typography', 'HTML Defaults', 'Icons', 'Spacing', 'Smart Surfaces'],
-            'Primitives',
-            ['Buttons', 'Forms', 'Form Groups', 'Alerts', 'Badges', 'Cards', 'Articles', 'Tables', 'Media', 'Accordion'],
-            'Layout',
-            ['Overview', 'System'],
-            'Utilities',
-            ['Grid System'],
-            'Patterns',
-            ['Border Effects', 'Utilities'],
-            'Enhancements',
-            ['Mesh Gradients', 'Interactive States', 'Toggles', 'Dropdowns', 'Range Sliders', 'Required Fields'],
-            'Components',
-            ['*'],
-            'Reference'
+            'General',
+            ['Docs', 'Getting Started', 'What Is PDS'],
+            'DOM Building',
+            ['Docs', 'Using the html template marker'],
+            'State Management',
+            ['Docs', '*'],
+            'PDS api',
+            ['Docs', '*'],
+            '*'
           ],
-          'About PDS',
-          ['What is PDS', 'Getting Started'],
           'Foundations',
-          ['Colors', 'Typography', 'HTML Defaults', 'Icons', 'Spacing', 'Smart Surfaces'],
-          'Primitives',
-          ['Buttons', 'Forms', 'Form Groups', 'Alerts', 'Badges', 'Cards', 'Articles', 'Tables', 'Media', 'Accordion'],
-          'Layout',
-          ['Overview', 'System'],
-          'Utilities',
-          ['Grid System'],
-          'Patterns',
-          ['Border Effects', 'Utilities'],
+          ['*'],
+          'Primitives & Patterns',
+          ['*'],
           'Enhancements',
-          ['Mesh Gradients', 'Interactive States', 'Toggles', 'Dropdowns', 'Range Sliders', 'Required Fields'],
+          ['*'],
           'Components',
           ['*'],
           'Reference',
+          ['*'],
           '*'
         ]
       }

package/dist/pds-reference.json

@@ -1,5 +1,5 @@
 {
-  "generatedAt": "2026-03-25T20:27:42.970Z",
+  "generatedAt": "2026-03-28T12:12:10.967Z",
   "sources": {
     "customElements": "custom-elements.json",
     "ontology": "src\\js\\pds-core\\pds-ontology.js",
@@ -256,6 +256,11 @@
         }
       ],
       "events": [
+        {
+          "name": "day-click",
+          "description": null,
+          "type": "CustomEvent"
+        },
         {
           "name": "month-change",
           "description": null,
@@ -266,6 +271,11 @@
           "description": null,
           "type": "CustomEvent"
         },
+        {
+          "name": "pds-calendar#day-click",
+          "description": "Dispatched when a day cell is selected from the calendar grid",
+          "type": null
+        },
         {
           "name": "pds-calendar#month-change",
           "description": "Dispatched when the visible month/year changes",
@@ -275,6 +285,16 @@
           "name": "pds-calendar#month-rendered",
           "description": "Dispatched after the calendar month is rendered with event fill capability",
           "type": null
+        },
+        {
+          "name": "pds-calendar#task-click",
+          "description": "Dispatched when a task item is clicked",
+          "type": null
+        },
+        {
+          "name": "task-click",
+          "description": null,
+          "type": "CustomEvent"
         }
       ],
       "slots": [],
@@ -1232,14 +1252,65 @@
         },
         {
           "name": "start-angle",
-          "description": "Starting angle in degrees (0=right, 90=down, 180=left, 270=up)\r\nIf not specified, the angle is auto-detected based on the FAB's corner position:\r\n- Bottom-right: 180° (fly left/up)\r\n- Bottom-left: 315° (fly right/up)\r\n- Top-right: 225° (fly left/down)\r\n- Top-left: 45° (fly right/down)",
+          "description": "Starting angle in degrees (0=right, 90=down, 180=left, 270=up)\r\nIf not specified, the angle is auto-detected based on the FAB's corner position:\r\n- Bottom-right: 180-� (fly left/up)\r\n- Bottom-left: 315-� (fly right/up)\r\n- Top-right: 225-� (fly left/down)\r\n- Top-left: 45-� (fly right/down)",
           "type": "number",
           "default": "180 (or auto-detected)",
           "fieldName": "startAngle",
           "property": "startAngle"
+        },
+        {
+          "name": "behavior",
+          "description": "Interaction mode for opening satellites (default: click)",
+          "type": "\"click\"|\"hover\"",
+          "default": "click",
+          "fieldName": "behavior",
+          "property": "behavior"
+        },
+        {
+          "name": "mode",
+          "description": "Layout mode for FAB positioning (default: fixed)",
+          "type": "\"fixed\"|\"inline\"",
+          "default": "fixed",
+          "fieldName": "mode",
+          "property": "mode"
+        },
+        {
+          "name": "fab-class",
+          "description": "Space-separated class list forwarded to the internal button.\r\nUse this instead of host classes for btn-* and icon-only.",
+          "type": "string",
+          "default": null,
+          "fieldName": "fabClass",
+          "property": "fabClass"
         }
       ],
       "properties": [
+        {
+          "name": "behavior",
+          "attribute": "behavior",
+          "description": "Interaction mode for satellite menu.\r\n- click: toggles satellites when main FAB is clicked\r\n- hover: opens on hover/focus and closes when pointer leaves safe area",
+          "type": "'click'|'hover'",
+          "default": "click",
+          "reflects": false,
+          "privacy": "public"
+        },
+        {
+          "name": "fabClass",
+          "attribute": "fab-class",
+          "description": "Space-separated class list forwarded to the internal button.\r\nUse this instead of host classes for btn-* and icon-only.",
+          "type": "string",
+          "default": null,
+          "reflects": false,
+          "privacy": "public"
+        },
+        {
+          "name": "mode",
+          "attribute": "mode",
+          "description": "Layout mode for host positioning.\r\n- fixed: FAB is anchored to viewport bottom-right\r\n- inline: FAB participates in normal document flow",
+          "type": "'fixed'|'inline'",
+          "default": "fixed",
+          "reflects": false,
+          "privacy": "public"
+        },
         {
           "name": "open",
           "attribute": "open",
@@ -1262,7 +1333,7 @@
           "name": "satellites",
           "attribute": null,
           "description": "Array of satellite button configurations",
-          "type": "Array<{key: string, icon?: string, label?: string, action?: string}>",
+          "type": "Array<{key: string, icon?: string, iconColor?: string, bgColor?: string, iconSize?: string, label?: string, action?: string}>",
           "default": null,
           "reflects": false,
           "privacy": "public"
@@ -1279,7 +1350,7 @@
         {
           "name": "startAngle",
           "attribute": "start-angle",
-          "description": "Starting angle in degrees (0=right, 90=down, 180=left, 270=up)\r\nIf not specified, the angle is auto-detected based on the FAB's corner position:\r\n- Bottom-right: 180° (fly left/up)\r\n- Bottom-left: 315° (fly right/up)\r\n- Top-right: 225° (fly left/down)\r\n- Top-left: 45° (fly right/down)",
+          "description": "Starting angle in degrees (0=right, 90=down, 180=left, 270=up)\r\nIf not specified, the angle is auto-detected based on the FAB's corner position:\r\n- Bottom-right: 180-� (fly left/up)\r\n- Bottom-left: 315-� (fly right/up)\r\n- Top-right: 225-� (fly left/down)\r\n- Top-left: 45-� (fly right/down)",
           "type": "number",
           "default": "180 (or auto-detected)",
           "reflects": false,
@@ -4059,6 +4130,12 @@
               "description": null,
               "optional": false
             },
+            {
+              "name": "title",
+              "type": "string | null | undefined",
+              "description": null,
+              "optional": false
+            },
             {
               "name": "closable",
               "type": "boolean",
@@ -4119,12 +4196,12 @@
         },
         {
           "name": "getToastElement",
-          "description": "Get toast element by ID.",
+          "description": "Get toast element by ID.\n\nGet toast element by ID.",
           "parameters": [
             {
               "name": "toastId",
               "type": "string",
-              "description": null,
+              "description": "Toast ID",
               "optional": false
             }
           ],
@@ -8576,47 +8653,52 @@
         "packages\\pds-storybook\\stories\\foundations\\ZIndex.stories.js"
       ]
     },
-    "getting-started": {
-      "slug": "getting-started",
-      "storyTitle": "About PDS/Getting Started",
-      "category": "About PDS",
-      "name": "Getting Started",
-      "description": "Complete beginner guide: installation, philosophy, configuration, enhancements, components, and console API",
+    "general": {
+      "slug": "general",
+      "storyTitle": "PDS/General",
+      "category": "PDS",
+      "name": "General",
+      "description": "Learn about Pure Design System and its revolutionary approach to design systems",
       "tags": [
+        "adoptedt stylesheets",
         "cdn",
         "cli",
         "dark mode",
+        "design system",
         "getting started",
         "guide",
         "introduction",
         "light mode",
         "npm",
         "overview",
-        "themes"
+        "philosophy",
+        "progressive enhancements",
+        "themes",
+        "web components",
+        "what is pds"
       ],
       "pdsParameters": {
         "tags": [
-          "getting started",
+          "what is pds",
           "introduction",
-          "cli",
-          "npm",
-          "cdn",
           "overview",
-          "guide",
-          "themes",
-          "dark mode",
-          "light mode"
+          "design system",
+          "philosophy",
+          "progressive enhancements",
+          "web components",
+          "adoptedt stylesheets"
         ]
       },
       "stories": [],
       "files": [
-        "packages\\pds-storybook\\stories\\GettingStarted.stories.js"
+        "packages\\pds-storybook\\stories\\GettingStarted.stories.js",
+        "packages\\pds-storybook\\stories\\WhatIsPDS.stories.js"
       ]
     },
     "border-effects": {
       "slug": "border-effects",
-      "storyTitle": "Patterns/Border Effects",
-      "category": "Patterns",
+      "storyTitle": "Primitives & Patterns/Border Effects",
+      "category": "Primitives & Patterns",
       "name": "Border Effects",
       "description": "Special border effects including gradients and glows",
       "tags": [
@@ -8646,8 +8728,8 @@
     },
     "interactive-states": {
       "slug": "interactive-states",
-      "storyTitle": "Patterns/Interactive States",
-      "category": "Patterns",
+      "storyTitle": "Primitives & Patterns/Interactive States",
+      "category": "Primitives & Patterns",
       "name": "Interactive States",
       "description": "Interactive states including focus rings, hover effects, active states, disabled states, and working/loading states. All animations respect user preferences and accessibility settings.",
       "tags": [
@@ -8683,8 +8765,8 @@
     },
     "utilities": {
       "slug": "utilities",
-      "storyTitle": "Patterns/Utilities",
-      "category": "Patterns",
+      "storyTitle": "Primitives & Patterns/Utilities",
+      "category": "Primitives & Patterns",
       "name": "Utilities",
       "description": "Utility classes for spacing, sizing, and common patterns",
       "tags": [
@@ -8708,8 +8790,8 @@
     },
     "articles": {
       "slug": "articles",
-      "storyTitle": "Primitives/Articles",
-      "category": "Primitives",
+      "storyTitle": "Primitives & Patterns/Articles",
+      "category": "Primitives & Patterns",
       "name": "Articles",
       "description": "Long-form content layout pattern using semantic article markup and PDS primitives.",
       "tags": [
@@ -8735,8 +8817,8 @@
     },
     "badges-pills": {
       "slug": "badges-pills",
-      "storyTitle": "Primitives/Badges & Pills",
-      "category": "Primitives",
+      "storyTitle": "Primitives & Patterns/Badges & Pills",
+      "category": "Primitives & Patterns",
       "name": "Badges & Pills",
       "description": "Badges and pills for labels, tags, status indicators, and categorization",
       "tags": [
@@ -8765,7 +8847,7 @@
         {
           "exportName": "AllVariations",
           "name": "AllVariations",
-          "id": "primitives-badges-pills--all-variations",
+          "id": "primitives-patterns-badges-pills--all-variations",
           "tags": [],
           "description": null,
           "source": "packages\\pds-storybook\\stories\\primitives\\Badges.stories.js"
@@ -8773,7 +8855,7 @@
         {
           "exportName": "BadgeSizes",
           "name": "BadgeSizes",
-          "id": "primitives-badges-pills--badge-sizes",
+          "id": "primitives-patterns-badges-pills--badge-sizes",
           "tags": [],
           "description": null,
           "source": "packages\\pds-storybook\\stories\\primitives\\Badges.stories.js"
@@ -8781,7 +8863,7 @@
         {
           "exportName": "DefaultBadges",
           "name": "DefaultBadges",
-          "id": "primitives-badges-pills--default-badges",
+          "id": "primitives-patterns-badges-pills--default-badges",
           "tags": [],
           "description": null,
           "source": "packages\\pds-storybook\\stories\\primitives\\Badges.stories.js"
@@ -8789,7 +8871,7 @@
         {
           "exportName": "OutlinedBadges",
           "name": "OutlinedBadges",
-          "id": "primitives-badges-pills--outlined-badges",
+          "id": "primitives-patterns-badges-pills--outlined-badges",
           "tags": [],
           "description": null,
           "source": "packages\\pds-storybook\\stories\\primitives\\Badges.stories.js"
@@ -8797,7 +8879,7 @@
         {
           "exportName": "Pills",
           "name": "Pills",
-          "id": "primitives-badges-pills--pills",
+          "id": "primitives-patterns-badges-pills--pills",
           "tags": [],
           "description": null,
           "source": "packages\\pds-storybook\\stories\\primitives\\Badges.stories.js"
@@ -8809,8 +8891,8 @@
     },
     "buttons": {
       "slug": "buttons",
-      "storyTitle": "Primitives/Buttons",
-      "category": "Primitives",
+      "storyTitle": "Primitives & Patterns/Buttons",
+      "category": "Primitives & Patterns",
       "name": "Buttons",
       "description": "Button primitives with variants, sizes, and icon support. All buttons automatically adapt to your theme with proper focus states and accessibility.",
       "tags": [
@@ -8830,8 +8912,8 @@
     },
     "callouts": {
       "slug": "callouts",
-      "storyTitle": "Primitives/Callouts",
-      "category": "Primitives",
+      "storyTitle": "Primitives & Patterns/Callouts",
+      "category": "Primitives & Patterns",
       "name": "Callouts",
       "description": "Callout components for feedback messages, notifications, and status indicators. Supports icons, titles, dismissible variants, and semantic messages.",
       "tags": [
@@ -8865,8 +8947,8 @@
     },
     "cards": {
       "slug": "cards",
-      "storyTitle": "Primitives/Cards",
-      "category": "Primitives",
+      "storyTitle": "Primitives & Patterns/Cards",
+      "category": "Primitives & Patterns",
       "name": "Cards",
       "description": "Versatile content containers with multiple surface variants. Cards automatically adapt to your theme and support nesting for complex layouts.",
       "tags": [
@@ -8892,8 +8974,8 @@
     },
     "form-elements": {
       "slug": "form-elements",
-      "storyTitle": "Primitives/Form Elements",
-      "category": "Primitives",
+      "storyTitle": "Primitives & Patterns/Form Elements",
+      "category": "Primitives & Patterns",
       "name": "Form Elements",
       "description": "Accessible radio groups and checkbox groups with proper ARIA attributes and semantic HTML.\r\n\r\n## Unified Styling\r\n\r\nRadio groups (\\",
       "tags": [
@@ -8920,8 +9002,8 @@
     },
     "media-elements": {
       "slug": "media-elements",
-      "storyTitle": "Primitives/Media Elements",
-      "category": "Primitives",
+      "storyTitle": "Primitives & Patterns/Media Elements",
+      "category": "Primitives & Patterns",
       "name": "Media Elements",
       "description": "Responsive images, figures with captions, image galleries, and video elements with proper semantic HTML.",
       "tags": [
@@ -8953,8 +9035,8 @@
     },
     "tables": {
       "slug": "tables",
-      "storyTitle": "Primitives/Tables",
-      "category": "Primitives",
+      "storyTitle": "Primitives & Patterns/Tables",
+      "category": "Primitives & Patterns",
       "name": "Tables",
       "description": "Responsive tables with various styling options including striped, bordered, and compact variants.",
       "tags": [
@@ -8986,8 +9068,8 @@
     },
     "backdrop": {
       "slug": "backdrop",
-      "storyTitle": "Utilities/Backdrop",
-      "category": "Utilities",
+      "storyTitle": "Primitives & Patterns/Backdrop",
+      "category": "Primitives & Patterns",
       "name": "Backdrop",
       "description": "Backdrop utilities for modal overlays, drawers, and lightboxes. Provides consistent blur and dimming effects with light/dark variants.",
       "tags": [
@@ -9066,11 +9148,52 @@
         "packages\\pds-storybook\\stories\\utils\\PdsAsk.stories.js"
       ]
     },
-    "pds-object": {
-      "slug": "pds-object",
-      "storyTitle": "PDS/PDS Object",
+    "dom-building": {
+      "slug": "dom-building",
+      "storyTitle": "PDS/DOM Building",
       "category": "PDS",
-      "name": "PDS Object",
+      "name": "DOM Building",
+      "description": "Experimental API. Build DOM with the html template marker using vanilla JavaScript, including Lit-style bindings without a Lit dependency.",
+      "tags": [
+        "api",
+        "autodocs",
+        "pds-ask",
+        "pds-compiled",
+        "pds-enums",
+        "pds-html",
+        "pds-object",
+        "pds-parse",
+        "pds-start",
+        "pds-toast",
+        "reference",
+        "runtime",
+        "utilities"
+      ],
+      "pdsParameters": {
+        "tags": [
+          "runtime",
+          "api",
+          "reference",
+          "pds-object",
+          "pds-start",
+          "pds-compiled",
+          "pds-enums",
+          "pds-ask",
+          "pds-toast",
+          "pds-parse",
+          "pds-html"
+        ]
+      },
+      "stories": [],
+      "files": [
+        "packages\\pds-storybook\\stories\\utils\\PdsHtml.stories.js"
+      ]
+    },
+    "pds-api": {
+      "slug": "pds-api",
+      "storyTitle": "PDS/PDS api",
+      "category": "PDS",
+      "name": "PDS api",
       "description": null,
       "tags": [
         "api",
@@ -9152,37 +9275,22 @@
         "packages\\pds-storybook\\stories\\utils\\PdsToast.stories.js"
       ]
     },
-    "what-is-pds": {
-      "slug": "what-is-pds",
-      "storyTitle": "About PDS/What Is PDS",
-      "category": "About PDS",
-      "name": "What Is PDS",
-      "description": "Learn about Pure Design System and its revolutionary approach to design systems",
+    "state-management": {
+      "slug": "state-management",
+      "storyTitle": "PDS/State Management",
+      "category": "PDS",
+      "name": "State Management",
+      "description": "Experimental API. Reactive state helpers for manual render loops, automatic re-rendering, partial binding updates, and state change events.",
       "tags": [
-        "adoptedt stylesheets",
-        "design system",
-        "introduction",
-        "overview",
-        "philosophy",
-        "progressive enhancements",
-        "web components",
-        "what is pds"
+        "experimental",
+        "reactive",
+        "state",
+        "utilities"
       ],
-      "pdsParameters": {
-        "tags": [
-          "what is pds",
-          "introduction",
-          "overview",
-          "design system",
-          "philosophy",
-          "progressive enhancements",
-          "web components",
-          "adoptedt stylesheets"
-        ]
-      },
+      "pdsParameters": {},
       "stories": [],
       "files": [
-        "packages\\pds-storybook\\stories\\WhatIsPDS.stories.js"
+        "packages\\pds-storybook\\stories\\utils\\State.stories.js"
       ]
     }
   }