@pure-ds/storybook 0.4.23 → 0.4.25

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

@@ -11,7 +11,7 @@ function getStep(value) {
 // Default options for pds-form
 const DEFAULT_OPTIONS = {
   widgets: {
-    booleans: "toggle", // 'toggle' | 'checkbox'
+    booleans: "toggle", // 'toggle' | 'toggle-with-icons' | 'checkbox'
     numbers: "input", // 'input' | 'range'
     selects: "standard", // 'standard' | 'dropdown'
   },
@@ -669,10 +669,9 @@ export class SchemaForm extends LitElement {
       return useRange ? "input-range" : "input-number";
     }
     if (schema.type === "boolean") {
-      // Check if toggle should be used
-      const useToggle =
-        this.#getOption("widgets.booleans", "toggle") === "toggle";
-      return useToggle ? "toggle" : "checkbox";
+      // Return the actual boolean widget type
+      const booleanWidget = this.#getOption("widgets.booleans", "toggle");
+      return booleanWidget === "checkbox" ? "checkbox" : booleanWidget;
     }
     return "input-text";
   }
@@ -1489,14 +1488,20 @@ export class SchemaForm extends LitElement {
       this.#emit("pw:after-render-field", { path, schema: node.schema })
     );
 
-    // Add data-toggle for toggle switches
-    const isToggle = node.widgetKey === "toggle";
+    // Add data-toggle for toggle switches (both toggle and toggle-with-icons)
+    const isToggle = node.widgetKey === "toggle" || node.widgetKey === "toggle-with-icons";
+    const useIconToggle = node.widgetKey === "toggle-with-icons";
 
     // Add range-output class for range inputs if enabled
     const isRange = node.widgetKey === "input-range";
     const useRangeOutput =
       isRange && this.#getOption("enhancements.rangeOutput", true);
-    const labelClass = useRangeOutput ? "range-output" : undefined;
+    
+    // Build class list for label
+    const labelClasses = [];
+    if (useRangeOutput) labelClasses.push("range-output");
+    if (useIconToggle) labelClasses.push("with-icons");
+    const labelClass = labelClasses.length > 0 ? labelClasses.join(" ") : undefined;
 
     const renderControlAndLabel = (isToggle) => {
       if (isToggle) return html`${controlTpl} <span data-label>${label}</span>`;
@@ -1855,6 +1860,22 @@ export class SchemaForm extends LitElement {
       `
     );
 
+    // Toggle switch with icons (same as toggle, styling comes from .with-icons class on label)
+    this.defineRenderer(
+      "toggle-with-icons",
+      ({ id, path, value, attrs, set }) => html`
+        <input
+          id=${id}
+          name=${path}
+          type="checkbox"
+          .checked=${!!value}
+          ?disabled=${!!attrs.disabled}
+          ?required=${!!attrs.required}
+          @change=${(e) => set(!!e.target.checked)}
+        />
+      `
+    );
+
     this.defineRenderer(
       "select",
       ({ id, path, value, attrs, set, schema, ui, host }) => {

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-core/pds-config.js

@@ -737,7 +737,6 @@ export const presets = {
       "Data-dense business intelligence app interface with organized hierarchy and professional polish",
     options: {
       liquidGlassEffects: false,
-      backgroundMesh: 2,
     },
     colors: {
       primary: "#0066cc", // corporate blue for primary actions
@@ -815,7 +814,7 @@ presets.default = {
   form: {
     options: {
       widgets: {
-        booleans: "toggle",      // 'toggle' | 'checkbox'
+        booleans: "toggle",      // 'toggle' | 'toggle-with-icons' | 'checkbox'
         numbers: "input",        // 'input' | 'range'
         selects: "standard",     // 'standard' | 'dropdown'
       },

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;
@@ -961,10 +963,27 @@ async function __setupAutoDefinerAndEnhancers(options) {
       enhancers: mergedEnhancers,
       onError: (tag, err) => {
         if (typeof tag === "string" && tag.startsWith("pds-")) {
-          // No config available in this context, using console
-          console.warn(
-            `⚠️ PDS component <${tag}> not found. Assets may not be installed.`
-          );
+          // Check if this is a Lit-dependent component with missing #pds/lit import map
+          const litDependentComponents = ['pds-form', 'pds-drawer'];
+          const isLitComponent = litDependentComponents.includes(tag);
+          const isMissingLitError = err?.message?.includes('#pds/lit') || 
+                                     err?.message?.includes('Failed to resolve module specifier');
+          
+          if (isLitComponent && isMissingLitError) {
+            console.error(
+              `❌ PDS component <${tag}> requires Lit but #pds/lit is not in import map.\n` +
+              `Add this to your HTML <head>:\n` +
+              `<script type="importmap">\n` +
+              `  { "imports": { "#pds/lit": "./path/to/lit.js" } }\n` +
+              `</script>\n` +
+              `See: https://github.com/pure-ds/core#lit-components`
+            );
+          } else {
+            // Generic component not found warning
+            console.warn(
+              `⚠️ PDS component <${tag}> not found. Assets may not be installed.`
+            );
+          }
         } else {
           console.error(`❌ Auto-define error for <${tag}>:`, err);
         }

package/stories/GettingStarted.md

@@ -10,12 +10,26 @@ From zero to hero with PDS.
 npm install @pure-ds/core
 ```
 
-Create `pds.config.js`: 
+**What happens during install:**
+
+PDS automatically sets up your project:
+- ✅ Creates `pds.config.js` with commented examples (if it doesn't exist)
+- ✅ Exports static assets to your web root (components, icons, styles)
+- ✅ Copies AI/Copilot instructions to `.github/copilot-instructions.md`
+- ✅ Adds helper scripts to your `package.json` (`pds:export`, `pds:build-icons`)
+
+The generated `pds.config.js` includes:
 
 ```javascript
+// pds.config.js (auto-generated)
 export const config = {
   mode: "live",
-  preset: "default"
+  preset: "default",
+
+  // Uncomment and customize as needed:
+  // design: { colors: { primary: '#007acc' } },
+  // enhancers: [ /* custom enhancements */ ],
+  // autoDefine: { predefine: ['pds-icon'] }
 }
 ```
 
@@ -23,11 +37,21 @@ Then initialize in your app:
 
 ```javascript
 import { PDS } from '@pure-ds/core';
-import { config } from "../../pds.config.js"; // change to match location (project root)
+import { config } from "./pds.config.js"; // project root
 
 await PDS.start(config); // That's it! Start writing semantic HTML.
 ```
 
+**Manual config generation:**
+
+```bash
+# Create or regenerate config with examples
+npx pds-init-config
+
+# Force overwrite existing config
+npx pds-init-config --force
+```
+
 ### Option B: CDN (Zero Install)
 
 Perfect for quick prototypes and learning: