@pure-ds/storybook 0.4.24 → 0.4.26

package/dist/pds-reference.json

@@ -1,5 +1,5 @@
 {
-  "generatedAt": "2026-01-16T09:55:44.354Z",
+  "generatedAt": "2026-01-16T15:44:04.960Z",
   "sources": {
     "customElements": "custom-elements.json",
     "ontology": "src\\js\\pds-core\\pds-ontology.js",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pure-ds/storybook",
-  "version": "0.4.24",
+  "version": "0.4.26",
   "description": "Storybook showcase for Pure Design System with live configuration",
   "type": "module",
   "private": false,
@@ -24,20 +24,20 @@
   ],
   "scripts": {
     "generate-stories": "node scripts/generate-stories.js",
-    "build-reference": "node scripts/build-pds-reference.mjs",
+    "build-reference": "node --no-warnings=ExperimentalWarning scripts/build-pds-reference.mjs",
     "package-build": "node scripts/package-build.js",
     "package-clean": "node -e \"const fs=require('fs'); fs.rmSync('src',{recursive:true,force:true}); fs.rmSync('public/assets',{recursive:true,force:true}); console.log('Cleaned package artifacts')\"",
     "prepack": "npm run package-build",
     "postpack": "npm run package-clean",
     "storybook": "npm run build-reference && storybook dev -p 6006",
-    "build-storybook": "npm run build-reference && storybook build --output-dir storybook-static",
+    "build-storybook": "npm run build-reference && storybook build --output-dir storybook-static --quiet",
     "storybook:dev": "npm run storybook",
     "storybook:build": "npm run build-storybook",
     "pds:export": "pds-export",
     "pds:build-icons": "pds-build-icons"
   },
   "peerDependencies": {
-    "@pure-ds/core": "^0.4.24"
+    "@pure-ds/core": "^0.4.26"
   },
   "dependencies": {
     "@custom-elements-manifest/analyzer": "^0.11.0",

package/src/js/common/toast.js

@@ -0,0 +1,120 @@
+/**
+ * Toast notification utilities for PDS
+ * Ensures pds-toaster component is properly initialized before use
+ */
+
+/**
+ * Ensures pds-toaster exists in DOM and is fully loaded
+ * @returns {Promise<HTMLElement>} The pds-toaster element
+ * @private
+ */
+async function ensureToaster() {
+  let toaster = document.querySelector('pds-toaster');
+  if (!toaster) {
+    toaster = document.createElement('pds-toaster');
+    document.body.appendChild(toaster);
+    await customElements.whenDefined('pds-toaster');
+  }
+  return toaster;
+}
+
+/**
+ * Display a toast notification
+ * 
+ * This method automatically ensures the pds-toaster component exists and is loaded
+ * before displaying the notification. The toaster element is appended to document.body
+ * if not already present.
+ * 
+ * @param {string} message - The message to display
+ * @param {Object} [options={}] - Toast configuration
+ * @param {"information"|"success"|"warning"|"error"} [options.type="information"] - Toast type/severity
+ * @param {number} [options.duration] - Duration in milliseconds (auto-calculated if not provided based on message length)
+ * @param {boolean} [options.closable=true] - Whether the toast can be manually closed
+ * @param {boolean} [options.persistent=false] - If true, toast won't auto-dismiss (requires manual close)
+ * @returns {Promise<string>} Toast ID (can be used to dismiss programmatically)
+ * 
+ * @example
+ * // Simple success toast
+ * await PDS.toast('Changes saved successfully!', { type: 'success' });
+ * 
+ * @example
+ * // Error with custom duration
+ * await PDS.toast('Failed to save changes', { 
+ *   type: 'error',
+ *   duration: 8000 
+ * });
+ * 
+ * @example
+ * // Persistent warning (must be manually closed)
+ * await PDS.toast('This action cannot be undone', { 
+ *   type: 'warning',
+ *   persistent: true 
+ * });
+ * 
+ * @example
+ * // Get toast ID to dismiss later
+ * const toastId = await PDS.toast('Processing...', { persistent: true });
+ * // ... later
+ * const toaster = document.querySelector('pds-toaster');
+ * toaster.dismissToast(toastId);
+ */
+export async function toast(message, options = {}) {
+  const toaster = await ensureToaster();
+  return toaster.toast(message, options);
+}
+
+/**
+ * Display a success toast (convenience method)
+ * 
+ * @param {string} message - The success message
+ * @param {Object} [options={}] - Additional toast options (type is preset to 'success')
+ * @returns {Promise<string>} Toast ID
+ * 
+ * @example
+ * await PDS.toast.success('Profile updated!');
+ */
+toast.success = async function(message, options = {}) {
+  return toast(message, { ...options, type: 'success' });
+};
+
+/**
+ * Display an error toast (convenience method)
+ * 
+ * @param {string} message - The error message
+ * @param {Object} [options={}] - Additional toast options (type is preset to 'error')
+ * @returns {Promise<string>} Toast ID
+ * 
+ * @example
+ * await PDS.toast.error('Failed to connect to server');
+ */
+toast.error = async function(message, options = {}) {
+  return toast(message, { ...options, type: 'error' });
+};
+
+/**
+ * Display a warning toast (convenience method)
+ * 
+ * @param {string} message - The warning message
+ * @param {Object} [options={}] - Additional toast options (type is preset to 'warning')
+ * @returns {Promise<string>} Toast ID
+ * 
+ * @example
+ * await PDS.toast.warning('Session will expire in 5 minutes');
+ */
+toast.warning = async function(message, options = {}) {
+  return toast(message, { ...options, type: 'warning' });
+};
+
+/**
+ * Display an information toast (convenience method)
+ * 
+ * @param {string} message - The information message
+ * @param {Object} [options={}] - Additional toast options (type is preset to 'information')
+ * @returns {Promise<string>} Toast ID
+ * 
+ * @example
+ * await PDS.toast.info('New features available!');
+ */
+toast.info = async function(message, options = {}) {
+  return toast(message, { ...options, type: 'information' });
+};

package/src/js/pds-configurator/pds-config-form.js

@@ -9,20 +9,6 @@ import { AutoComplete } from "pure-web/ac";
 import { figmafyTokens } from "./figma-export.js";
 const STORAGE_KEY = "pure-ds-config";
 
-
-
-async function toast(message, options = {}) {
-  let toaster = document.querySelector("#global-toaster");
-  if (!toaster) {
-    toaster = document.createElement("pds-toaster");
-    toaster.id = "global-toaster";
-    document.body.appendChild(toaster);
-    await customElements.whenDefined("pds-toaster");
-  }
-
-  return toaster.toast(message, options);
-}
-
 customElements.define(
   "pds-config-form",
   class extends LitElement {
@@ -325,7 +311,7 @@ customElements.define(
               .slice(0, 3)
               .map((i) => `• ${i.message}`)
               .join("\n");
-            this._validationToastId = toast(
+            this._validationToastId = await PDS.toast(
               `Design has accessibility issues. Fix before applying.\n${summary}`,
               { type: "error", persistent: true }
             );
@@ -408,11 +394,11 @@ customElements.define(
       }
     }
 
-    toggleInspectorMode() {
+    async toggleInspectorMode() {
       this.inspectorMode = !this.inspectorMode;
       this.dispatchInspectorModeChange();
 
-      toast(
+      await PDS.toast(
         this.inspectorMode
           ? "Code Inspector active - click any element in the showcase to view its code"
           : "Code Inspector deactivated",
@@ -485,7 +471,7 @@ customElements.define(
       return filtered;
     }
 
-    handleFormChange = (event) => {
+    handleFormChange = async (event) => {
       // Get values from the pds-form's serialize method or from event detail
       let values;
       let changedField = null;
@@ -564,7 +550,7 @@ customElements.define(
             .slice(0, 3)
             .map((i) => `• ${i.message}`)
             .join("\n");
-          this._validationToastId = toast(
+          this._validationToastId = await PDS.toast(
             `Design has accessibility issues. Fix before saving.\n${summary}`,
             { type: "error" }
           );
@@ -635,7 +621,7 @@ customElements.define(
         this.saveConfig();
         this.applyStyles(true);
 
-        toast("Configuration reset to defaults", {
+        await PDS.toast("Configuration reset to defaults", {
           type: "info",
           duration: 2000,
         });
@@ -658,7 +644,7 @@ customElements.define(
               .slice(0, 3)
               .map((i) => `• ${i.message}`)
               .join("\n");
-            this._validationToastId = toast(
+            this._validationToastId = await PDS.toast(
               `Preset "${preset.name}" has accessibility issues — not applied.\n${summary}`,
               { type: "error", persistent: true }
             );
@@ -685,14 +671,14 @@ customElements.define(
         this.saveConfig();
         this.applyStyles(true);
 
-        toast(`"${preset.name}" preset loaded successfully!`, {
+        await PDS.toast(`"${preset.name}" preset loaded successfully!`, {
           type: "success",
           duration: 3000,
         });
       }
     };
 
-    handleThemeChange(e) {
+    async handleThemeChange(e) {
       try {
         const value = e.target.value;
         // Update centralized theme via PDS (this persists + applies + sets up listeners)
@@ -701,7 +687,7 @@ customElements.define(
         // Apply immediately and emit styles using the user config (keep config separate)
         this.applyStyles(true);
 
-        toast(`Theme set to ${value}`, { type: "info", duration: 1200 });
+        await PDS.toast(`Theme set to ${value}`, { type: "info", duration: 1200 });
       } catch (ex) {
         console.warn("Failed to change theme:", ex);
       }
@@ -750,9 +736,9 @@ export const pdsConfig = ${JSON.stringify(this.config, null, 2)};
       if (!this.schema) {
         if (!this._loadingToastShown) {
           this._loadingToastShown = true;
-          setTimeout(() => {
+          setTimeout(async () => {
             try {
-              toast("Loading schema...", { duration: 1000 });
+              await PDS.toast("Loading schema...", { duration: 1000 });
             } catch {}
           }, 250);
         }

package/src/js/pds-configurator/pds-demo.js

@@ -3,11 +3,6 @@ import { PDS } from "../../../src/js/pds.js";
 
 import { AutoComplete } from "pure-web/ac";
 
-const toast = (message, options) => {
-  const toaster = document.getElementById("global-toaster");
-  toaster.toast(message, options);
-};
-
 customElements.define(
   "pds-demo",
   class extends LitElement {
@@ -3414,12 +3409,12 @@ customElements.define(
       } catch (err) {
         console.error("Error fetching README:", err);
         const toaster = document.getElementById("global-toaster");
-        toaster.toast("Error loading docs. See console.", { type: "danger" });
+        await PDS.toast("Error loading docs. See console.", { type: "error" });
       }
     }
 
     handleTabChange(event) {
-      toast(`Switched to tab: ${event.detail.newTab}`, { type: "info" });
+      await PDS.toast(`Switched to tab: ${event.detail.newTab}`, { type: "info" });
     }
 
     openDrawer() {
@@ -3502,42 +3497,42 @@ customElements.define(
     }
 
     // Toast handler methods
-    showSuccessToast() {
-      toast("Your changes have been saved successfully!", {
+    async showSuccessToast() {
+      await PDS.toast("Your changes have been saved successfully!", {
         type: "success",
       });
     }
 
-    showInfoToast() {
-      toast("This is an informational message with helpful context.", {
-        type: "info",
+    async showInfoToast() {
+      await PDS.toast("This is an informational message with helpful context.", {
+        type: "information",
       });
     }
 
-    showWarningToast() {
-      toast("Warning: This action cannot be undone!", {
+    async showWarningToast() {
+      await PDS.toast("Warning: This action cannot be undone!", {
         type: "warning",
       });
     }
 
-    showErrorToast() {
-      toast("Error: Something went wrong. Please try again.", {
+    async showErrorToast() {
+      await PDS.toast("Error: Something went wrong. Please try again.", {
         type: "error",
       });
     }
 
-    showLongToast() {
-      toast(
+    async showLongToast() {
+      await PDS.toast(
         "This is a longer toast notification message that demonstrates how the duration is automatically calculated based on the message length. The toast will stay visible longer to give you enough time to read the entire message.",
-        { type: "info" }
+        { type: "information" }
       );
     }
 
-    showPersistentToast() {
-      toast(
+    async showPersistentToast() {
+      await PDS.toast(
         "This is a persistent toast that won't auto-dismiss. Click the × to close it.",
         {
-          type: "info",
+          type: "information",
           persistent: true,
         }
       );

package/src/js/pds.d.ts

@@ -154,6 +154,68 @@ export class PDS extends EventTarget {
   static validateDesign: (designConfig: any, options?: { minContrast?: number }) => { ok: boolean; issues: Array<{ path: string; message: string; ratio: number; min: number; context?: string }> };
   static validateDesigns: (designs: Array<any> | Record<string, any>, options?: { minContrast?: number }) => { ok: boolean; results: Array<{ name?: string; ok: boolean; issues: Array<{ path: string; message: string; ratio: number; min: number; context?: string }> }> };
   
+  /**
+   * Display a toast notification.
+   * 
+   * Automatically ensures the pds-toaster component exists and is loaded before displaying.
+   * 
+   * @param message - The message to display
+   * @param options - Toast configuration
+   * @param options.type - Toast type/severity ("information" | "success" | "warning" | "error")
+   * @param options.duration - Duration in milliseconds (auto-calculated if not provided)
+   * @param options.closable - Whether toast can be manually closed (default: true)
+   * @param options.persistent - If true, toast won't auto-dismiss (default: false)
+   * @returns Toast ID (can be used to dismiss programmatically)
+   * 
+   * @example
+   * await PDS.toast('Changes saved!', { type: 'success' });
+   * 
+   * @example
+   * await PDS.toast('Error occurred', { type: 'error', persistent: true });
+   */
+  static toast(
+    message: string,
+    options?: {
+      type?: 'information' | 'success' | 'warning' | 'error';
+      duration?: number;
+      closable?: boolean;
+      persistent?: boolean;
+    }
+  ): Promise<string>;
+  
+  /**
+   * Display a success toast (convenience method).
+   * 
+   * @param message - The success message
+   * @param options - Additional toast options (type is preset to 'success')
+   * @returns Toast ID
+   * 
+   * @example
+   * await PDS.toast.success('Profile updated!');
+   */
+  static toast: {
+    (message: string, options?: { type?: 'information' | 'success' | 'warning' | 'error'; duration?: number; closable?: boolean; persistent?: boolean }): Promise<string>;
+    success(message: string, options?: { duration?: number; closable?: boolean; persistent?: boolean }): Promise<string>;
+    error(message: string, options?: { duration?: number; closable?: boolean; persistent?: boolean }): Promise<string>;
+    warning(message: string, options?: { duration?: number; closable?: boolean; persistent?: boolean }): Promise<string>;
+    info(message: string, options?: { duration?: number; closable?: boolean; persistent?: boolean }): Promise<string>;
+  };
+  
+  /**
+   * Display a modal dialog for user input or confirmation.
+   * 
+   * @param message - The message or prompt to display
+   * @param options - Dialog configuration
+   * @returns User's response (string for prompt, boolean for confirm, true for alert)
+   * 
+   * @example
+   * const confirmed = await PDS.ask('Delete this item?', { type: 'confirm' });
+   * 
+   * @example
+   * const name = await PDS.ask('Enter your name:', { type: 'prompt' });
+   */
+  static ask(message: string, options?: any): Promise<any>;
+  
   /** 
    * Current configuration after PDS.start() completes - read-only, frozen after initialization.
    * Contains the complete configuration used to initialize PDS, including mode, design, preset, and theme.

package/src/js/pds.js

@@ -56,6 +56,7 @@ import { findComponentForElement } from "./pds-core/pds-ontology.js";
 import { presets, defaultLog } from "./pds-core/pds-config.js";
 import { enums } from "./pds-core/pds-enums.js";
 import { ask } from "./common/ask.js";
+import { toast } from "./common/toast.js";
 import { PDSQuery } from "./pds-core/pds-query.js";
 import * as common from "./common/common.js";
 import { defaultPDSEnhancers } from "./pds-core/pds-enhancers.js";
@@ -87,6 +88,7 @@ PDS.isLiveMode = () => registry.isLive;
 PDS.enums = enums;
 
 PDS.ask = ask;
+PDS.toast = toast;
 
 // Expose common utilities (deepMerge, isObject, etc.)
 PDS.common = common;

package/stories/components/PdsForm.stories.js

@@ -691,15 +691,33 @@ const simpleSchema = {
       type: "string",
       format: "date",
       title: "Date of Birth",
+      examples: ["1990-01-15"],
     },
     newsletter: {
       type: "boolean",
       title: "Subscribe to newsletter",
+      default: false,
     },
   },
   required: ["name", "email"],
 };
 
+// UI Schema with icons for better UX
+const simpleUiSchema = {
+  "/name": {
+    "ui:icon": "user",
+    "ui:iconPosition": "start",
+  },
+  "/email": {
+    "ui:icon": "envelope",
+    "ui:iconPosition": "start",
+  },
+  "/dateOfBirth": {
+    "ui:icon": "calendar",
+    "ui:iconPosition": "start",
+  },
+};
+
 const complexSchema = {
   type: "object",
   properties: {
@@ -744,17 +762,52 @@ const complexSchema = {
 
 export const SimpleForm = {
   render: () => {
+    const handleSubmit = async (e) => {
+      // Add btn-working class to show loading state
+      const submitBtn = e.target.querySelector('button[type="submit"]');
+      submitBtn?.classList.add('btn-working');
+      
+      try {
+        // Simulate async submission (2 second delay)
+        await new Promise(resolve => setTimeout(resolve, 2000));
+        await toastFormData(e.detail);
+      } finally {
+        submitBtn?.classList.remove('btn-working');
+      }
+    };
+
     return html`
       <pds-form
         data-required
         .jsonSchema=${simpleSchema}
-        @pw:submit=${(e) => toastFormData(e.detail)}
+        .uiSchema=${simpleUiSchema}
+        @pw:submit=${handleSubmit}
       ></pds-form>
     `;
   },
 };
 
 const complexUiSchema = {
+  "/personalInfo/firstName": {
+    "ui:icon": "user",
+    "ui:iconPosition": "start",
+  },
+  "/personalInfo/lastName": {
+    "ui:icon": "user",
+    "ui:iconPosition": "start",
+  },
+  "/personalInfo/dateOfBirth": {
+    "ui:icon": "calendar",
+    "ui:iconPosition": "start",
+  },
+  "/address/street": {
+    "ui:icon": "map-pin",
+    "ui:iconPosition": "start",
+  },
+  "/address/city": {
+    "ui:icon": "building",
+    "ui:iconPosition": "start",
+  },
   "address/country": {
     "ui:class": "buttons"
   },
@@ -765,11 +818,23 @@ const complexUiSchema = {
 
 export const ComplexForm = {
   render: () => {
+    const handleSubmit = async (e) => {
+      const submitBtn = e.target.querySelector('button[type="submit"]');
+      submitBtn?.classList.add('btn-working');
+      
+      try {
+        await new Promise(resolve => setTimeout(resolve, 2000));
+        await toastFormData(e.detail);
+      } finally {
+        submitBtn?.classList.remove('btn-working');
+      }
+    };
+
     return html`
       <pds-form
         .jsonSchema=${complexSchema}
         .uiSchema=${complexUiSchema}
-        @pw:submit=${(e) => toastFormData(e.detail)}
+        @pw:submit=${handleSubmit}
       ></pds-form>
     `;
   },
@@ -790,13 +855,26 @@ export const WithInitialData = {
       newsletter: true,
     };
 
+    const handleSubmit = async (e) => {
+      const submitBtn = e.target.querySelector('button[type="submit"]');
+      submitBtn?.classList.add('btn-working');
+      
+      try {
+        await new Promise(resolve => setTimeout(resolve, 2000));
+        await toastFormData(e.detail);
+      } finally {
+        submitBtn?.classList.remove('btn-working');
+      }
+    };
+
     return html`
       <pds-form
         .jsonSchema=${simpleSchema}
+        .uiSchema=${simpleUiSchema}
         .values=${initialValues}
         .options=${options}
         @pw:value-change=${(e) => console.log("?? Value changed:", e.detail)}
-        @pw:submit=${(e) => toastFormData(e.detail)}
+        @pw:submit=${handleSubmit}
       ></pds-form>
     `;
   },

package/stories/utils/toast-utils.js

@@ -123,17 +123,8 @@ export async function toastFormData(data) {
   const truncated = truncateData(obj);
   const formatted = JSON.stringify(truncated, null, 2);
 
-  // Ensure pds-toaster exists and show the toast
-  let toaster = document.querySelector('pds-toaster');
-  if (!toaster) {
-    toaster = document.createElement('pds-toaster');
-    document.body.appendChild(toaster);
-  }
-  
-  // Wait for the custom element to be defined before calling methods
-  await customElements.whenDefined('pds-toaster');
-  
-  toaster.toast(formatted, {
+  // Use PDS.toast() to display the formatted data
+  await PDS.toast(formatted, {
     type: 'success',
     duration: 5000
   });