@pure-ds/core 0.4.26 → 0.4.28

package/.cursorrules

@@ -1,6 +1,6 @@
-# PDS (Pure Design System) - Copilot Instructions
+# PDS (Pure Design System) - AI Generation Instructions
 
-> **CRITICAL**: This workspace uses **Pure Design System (PDS)**. All code generation MUST follow PDS patterns. Never use generic web patterns, inline styles, or hardcoded values.
+> **CRITICAL**: This workspace uses **Pure Design System (PDS)**. All code generation MUST follow PDS and vanilla Web Platform patterns. Never use 3rd party framework patterns, non-PDS utility classes, inline styles, or hardcoded CSS values.
 
 ## Philosophy
 
@@ -31,7 +31,7 @@ PDS follows the [Pure Web Manifesto](https://pureweb.dev/manifesto): "The browse
 | **Web Components** | `custom-elements.json` | Complete component APIs, attributes, methods, events, slots |
 | **HTML Tags** | `public/assets/pds/vscode-custom-data.json` | Component HTML structure, attribute values |
 | **Primitives & Utilities** | `src/js/pds-core/pds-ontology.js` | `.card`, `.badge`, `.btn-*`, `.flex`, `.gap-*`, `.surface-*` |
-| **Enhancements** | `src/js/pds-core/pds-enhancer-metadata.js` | Selectors + `demoHtml` examples for each enhancement |
+| **Enhancements** | `src/js/pds-core/pds-enhancers.js` | Enhancement metadata (`defaultPDSEnhancerMetadata`) + runtime (`defaultPDSEnhancers`) |
 | **Generator Logic** | `src/js/pds-core/pds-generator.js` | How CSS is generated, token naming conventions |
 | **Config** | `pds.config.js` | What's enabled in this workspace |
 
@@ -94,95 +94,147 @@ async function simulateSubmit(data) {
 }
 ```
 
-### 3. Progressive Enhancement - Add `data-required` to form wrapper
+### 3. Adding `data-required` to pds-form generated form: simply add the attribute to the pds-form tag
 
 ```html
-<!-- ✅ CORRECT: Wrap pds-form in form[data-required] -->
-<form data-required>
-  <pds-form id="myForm" hide-actions></pds-form>
-  <div class="form-actions">
-    <button type="submit" class="btn-primary">Submit</button>
-  </div>
-</form>
+<pds-form data-required id="myForm" hide-actions></pds-form>
+```
+
+### 4. Placeholders - ALWAYS include examples
+
+**Placeholders improve UX significantly. Try to add 'examples' array to schema properties:**
+
+**Rule: When generating a form, infer appropriate placeholders based on field name/type if not specified.**
 
-<!-- ❌ WRONG: No data-required enhancement -->
-<pds-form id="myForm"></pds-form>
+### 5. Smart Icons - Infer from field semantics
+
+**When generating forms, automatically add appropriate icons based on field names and semantics.**
+
+**Sources of truth for available icons:**
+- Check `pds.config.js` for project-specific icon configuration
+- Consult icon sprite at `public/assets/img/icons/pds-icons.svg` for available icons
+- See `public/assets/pds/vscode-custom-data.json` for icon attribute values
+
+**Use semantic reasoning to match field names to appropriate icons:**
+
+```javascript
+// ✅ CORRECT: Infer icons based on field semantics
+const uiSchema = {
+  "/email": { 'ui:icon': 'envelope', 'ui:autocomplete': 'email' },
+  "/phone": { 'ui:icon': 'phone', 'ui:autocomplete': 'tel' },
+  "/name": { 'ui:icon': 'user', 'ui:autocomplete': 'name' },
+  "/password": { 'ui:icon': 'lock', 'ui:widget': 'password' },
+  "/website": { 'ui:icon': 'link' },
+  "/address": { 'ui:icon': 'map-pin' },
+  "/date": { 'ui:icon': 'calendar' },
+  "/message": { 'ui:widget': 'textarea', 'ui:icon': 'message' }
+};
 ```
 
-### 4. JSON Schema - Use `examples` for placeholders
+**Rule: When generating forms, analyze field names/types and select semantically appropriate icons from the available icon set.**
+
+### 6. Submit Handler Pattern - ALWAYS provide working async handler
+
+**When generating a pds-form, ALWAYS include a complete, iteration-ready submit handler with:**
+- `pw:submit` event (NOT native submit)
+- `btn-working` class for loading state
+- `PDS.toast()` for user feedback
+- Error handling
+- Realistic async simulation
 
 ```javascript
-// ✅ CORRECT: Use examples array for placeholders
-const schema = {
-  type: "object",
-  properties: {
-    name: {
-      type: "string",
-      title: "Full Name",
-      examples: ["John Doe"]  // First example becomes placeholder
-    },
-    email: {
-      type: "string",
-      format: "email",
-      title: "Email",
-      examples: ["user@example.com"]
-    },
-    age: {
-      type: "integer",
-      title: "Age",
-      examples: [25]  // Works for numbers too
-    }
+// ✅ CORRECT: Complete submit handler pattern
+form.addEventListener('pw:submit', async (e) => {
+  const submitBtn = form.querySelector('button[type="submit"]');
+  submitBtn?.classList.add('btn-working');
+  
+  try {
+    // Simulate async operation (replace with real API call)
+    await new Promise(resolve => setTimeout(resolve, 2000));
+    
+    // Log the data for debugging
+    console.log('Submitted data:', e.detail.json);
+    
+    // Show success toast
+    await PDS.toast('Form submitted successfully!', { type: 'success' });
+    
+    // Optionally reset form
+    form.reset();
+  } catch (error) {
+    // Show error toast
+    await PDS.toast('Submission failed: ' + error.message, { type: 'error' });
+  } finally {
+    // Always remove loading state
+    submitBtn?.classList.remove('btn-working');
   }
-};
+});
 
-// ❌ WRONG: No placeholders or using wrong property
+// ❌ WRONG: Native submit event
+form.addEventListener('submit', (e) => { /* Won't work */ });
+
+// ❌ WRONG: No loading state
+form.addEventListener('pw:submit', async (e) => {
+  await fetch('/api'); // No visual feedback!
+});
+
+// ❌ WRONG: Browser dialogs
+form.addEventListener('pw:submit', async (e) => {
+  alert('Submitted!'); // Use PDS.toast() instead
+});
 ```
 
-### 5. UI Schema - Infer smart icons automatically
+**PDS.toast() is available globally via window.PDS:**
+
+```javascript
+// All toast types
+await PDS.toast('Success message', { type: 'success' });
+await PDS.toast('Error occurred', { type: 'error' });
+await PDS.toast('Warning message', { type: 'warning' });
+await PDS.toast('Info message', { type: 'information' });
 
-**Common field → icon mappings (use these by default):**
+// Custom duration (auto-calculated by default based on message length)
+await PDS.toast('Quick message', { type: 'info', duration: 3000 });
+
+// Persistent (requires manual close)
+await PDS.toast('Important notice', { type: 'warning', persistent: true });
+```
+
+### 7. Conditional "Other" Fields - Auto-generate ui:visibleWhen
+
+**When a schema has an "Other" enum option, ALWAYS auto-generate a conditional text field:**
 
 ```javascript
-const smartIcons = {
-  email: 'envelope',
-  phone: 'phone',
-  name: 'user',
-  password: 'lock',
-  search: 'search',
-  message: 'message',
-  comment: 'comment',
-  address: 'map-marker',
-  website: 'link',
-  date: 'calendar',
-  time: 'clock',
-  subject: 'tag',
-  priority: 'flag',
-  category: 'folder',
-  file: 'file',
-  image: 'image'
+const schema = {
+  type: "object",
+  properties: {
+    reason: {
+      type: "string",
+      title: "How did you hear about us?",
+      oneOf: [
+        { const: "search", title: "Search Engine" },
+        { const: "social", title: "Social Media" },
+        { const: "friend", title: "Friend Referral" },
+        { const: "other", title: "Other... (please specify)" },  // ← "Other" option
+      ],
+    },
+    otherReason: {  // ← Conditional field for "Other"
+      type: "string",
+      title: "Please specify",
+      examples: ["Tell us more..."],
+    },
+  },
 };
 
 const uiSchema = {
-  email: {
-    'ui:widget': 'email',
-    'ui:placeholder': 'user@example.com',
-    'ui:icon': 'envelope',  // Auto-infer
-    'ui:autocomplete': 'email'
-  },
-  phone: {
-    'ui:widget': 'tel',
-    'ui:icon': 'phone',
-    'ui:autocomplete': 'tel'
+  // ✅ ALWAYS add these when "other" enum exists
+  "/otherReason": {
+    "ui:visibleWhen": { "/reason": "other" },
+    "ui:requiredWhen": { "/reason": "other" },
   },
-  message: {
-    'ui:widget': 'textarea',
-    'ui:rows': 4,
-    'ui:icon': 'message'
-  }
 };
 ```
 
-### 6. Complete Working Example
+### 8. Complete Working Example
 
 ```javascript
 // Schema with examples for placeholders
@@ -213,9 +265,9 @@ const contactSchema = {
 
 // UI schema with smart icons
 const uiSchema = {
-  name: { 'ui:icon': 'user' },
-  email: { 'ui:icon': 'envelope' },
-  message: { 
+  "/name": { 'ui:icon': 'user' },
+  "/email": { 'ui:icon': 'envelope' },
+  "/message": { 
     'ui:widget': 'textarea',
     'ui:rows': 4,
     'ui:icon': 'message'
@@ -296,6 +348,45 @@ const schema = {
 
 ---
 
+## ⚡ Lit Components & Import Maps
+
+**Components that require Lit:** `pds-form`
+
+This component uses `import { ... } from "#pds/lit"` and **requires** an import map:
+
+```html
+<!-- REQUIRED in HTML <head> for Lit components -->
+<script type="importmap">
+{
+  "imports": {
+    "#pds/lit": "/assets/js/lit.js"
+  }
+}
+</script>
+```
+
+**When generating code with lazy-loaded components, ALWAYS wait for definition:**
+
+```javascript
+// ✅ CORRECT: Wait for component to load
+await customElements.whenDefined('pds-form');
+const form = document.querySelector('pds-form');
+form.getFormData(); // Safe
+
+// ✅ CORRECT: Alternative pattern
+const FormClass = await customElements.get('pds-form');
+if (FormClass) {
+  const form = document.createElement('pds-form');
+  // ...
+}
+
+// ❌ WRONG: Direct access without waiting
+const form = document.querySelector('pds-form');
+form.getFormData(); // May throw error
+```
+
+---
+
 ## ✅ Quick Reference Patterns
 
 ```html
@@ -324,7 +415,7 @@ const schema = {
 <pds-icon icon="heart" size="sm"></pds-icon>
 <pds-icon icon="check" size="lg" color="var(--color-success-500)"></pds-icon>
 
-<!-- Enhancements: data attributes (see pds-enhancer-metadata.js) -->
+<!-- Enhancements: data attributes (see pds-enhancers.js → defaultPDSEnhancerMetadata) -->
 <nav data-dropdown>
   <button>Menu</button>
   <menu><li><a href="#">Item</a></li></menu>
@@ -341,10 +432,12 @@ const schema = {
 
 <!-- Tabs: web component -->
 <pds-tabstrip>
-  <button slot="tab">Tab 1</button>
-  <div slot="panel">Content 1</div>
-  <button slot="tab">Tab 2</button>
-  <div slot="panel">Content 2</div>
+  <pds-tabpanel label="Tab 1">
+    <p>Content for Tab 1</p>
+  </pds-tabpanel>
+  <pds-tabpanel label="Tab 2">
+    <p>Content for Tab 2</p>
+  </pds-tabpanel>
 </pds-tabstrip>
 ```
 
@@ -369,14 +462,15 @@ const results = await PDS.query("border gradient classes");
 ## 📚 Additional Resources
 
 **For comprehensive pds-form documentation:**
-- Read [pds-form-docs.md](pds-form-docs.md) for complete API reference
-- See [packages/pds-storybook/stories/components/PdsForm.stories.js](packages/pds-storybook/stories/components/PdsForm.stories.js) for real examples
-- Check [custom-elements.json](custom-elements.json) for component API details
+- Read [pds-form-docs.md](../pds-form-docs.md) for complete API reference
+- See [packages/pds-storybook/stories/components/PdsForm.stories.js](../packages/pds-storybook/stories/components/PdsForm.stories.js) for real examples
+- Check [custom-elements.json](../custom-elements.json) for component API details
 
 **For toast notifications:**
-- Use `PDS.toast()` method (see [src/js/common/toast.js](src/js/common/toast.js) for implementation)
+- Use `PDS.toast()` method (see [src/js/common/toast.js](../src/js/common/toast.js) for implementation)
 - Automatically ensures pds-toaster exists and is loaded before displaying
-- See pds-toaster component API in [custom-elements.json](custom-elements.json)
+- See pds-toaster component API in [custom-elements.json](../custom-elements.json)
+
 ---
 
 ## How to Look Things Up
@@ -387,7 +481,7 @@ const results = await PDS.query("border gradient classes");
 | "What components are available?" | Read `custom-elements.json` |
 | "What utility classes exist?" | Read `pds-ontology.js` → `layoutPatterns`, `utilities` |
 | "What primitives exist?" | Read `pds-ontology.js` → `primitives` |
-| "How do I enhance HTML?" | Read `pds-enhancer-metadata.js` → `demoHtml` |
+| "How do I enhance HTML?" | Read `pds-enhancers.js` → `defaultPDSEnhancerMetadata` → `demoHtml` |
 | "How are tokens named?" | Read `pds-generator.js` or `pds.css-data.json` |
 
 ---
@@ -401,7 +495,7 @@ Before generating code:
 3. ✅ **No hardcoded values** — Colors, spacing, radii all have tokens
 4. ✅ **No alert/confirm/prompt** — Use `PDS.ask()` and `PDS.toast()`
 5. ✅ **Use semantic HTML** — `<button>`, `<nav>`, `<article>`, `<label>`, `<details>`
-6. ✅ **Apply enhancements via data-* attributes** — See `pds-enhancer-metadata.js`
+6. ✅ **Apply enhancements via data-* attributes** — See `pds-enhancers.js` → `defaultPDSEnhancerMetadata`
 7. ✅ **Components as last resort** — Only when native HTML can't achieve it
 8. ✅ **Prefer primitives** — `.card`, `.badge`, `.alert` over custom components
 9. ✅ **Wait for lazy components** — Use `await customElements.whenDefined()` before accessing APIs

package/.github/copilot-instructions.md

@@ -1,4 +1,4 @@
-# PDS (Pure Design System) - Copilot Instructions
+# PDS (Pure Design System) - AI Generation Instructions
 
 > **CRITICAL**: This workspace uses **Pure Design System (PDS)**. All code generation MUST follow PDS and vanilla Web Platform patterns. Never use 3rd party framework patterns, non-PDS utility classes, inline styles, or hardcoded CSS values.
 
@@ -31,7 +31,7 @@ PDS follows the [Pure Web Manifesto](https://pureweb.dev/manifesto): "The browse
 | **Web Components** | `custom-elements.json` | Complete component APIs, attributes, methods, events, slots |
 | **HTML Tags** | `public/assets/pds/vscode-custom-data.json` | Component HTML structure, attribute values |
 | **Primitives & Utilities** | `src/js/pds-core/pds-ontology.js` | `.card`, `.badge`, `.btn-*`, `.flex`, `.gap-*`, `.surface-*` |
-| **Enhancements** | `src/js/pds-core/pds-enhancer-metadata.js` | Selectors + `demoHtml` examples for each enhancement |
+| **Enhancements** | `src/js/pds-core/pds-enhancers.js` | Enhancement metadata (`defaultPDSEnhancerMetadata`) + runtime (`defaultPDSEnhancers`) |
 | **Generator Logic** | `src/js/pds-core/pds-generator.js` | How CSS is generated, token naming conventions |
 | **Config** | `pds.config.js` | What's enabled in this workspace |
 
@@ -94,138 +94,44 @@ async function simulateSubmit(data) {
 }
 ```
 
-### 3. Progressive Enhancement - Add `data-required` to form wrapper
+### 3. Adding `data-required` to pds-form generated form: simply add the attribute to the pds-form tag
 
 ```html
-<!-- ✅ CORRECT: Wrap pds-form in form[data-required] -->
-<form data-required>
-  <pds-form id="myForm" hide-actions></pds-form>
-  <div class="form-actions">
-    <button type="submit" class="btn-primary">Submit</button>
-  </div>
-</form>
-
-<!-- ❌ WRONG: No data-required enhancement -->
-<pds-form id="myForm"></pds-form>
+<pds-form data-required id="myForm" hide-actions></pds-form>
 ```
 
 ### 4. Placeholders - ALWAYS include examples
 
-**Placeholders improve UX significantly. ALWAYS add examples to schema properties:**
+**Placeholders improve UX significantly. Try to add 'examples' array to schema properties:**
 
-```javascript
-// ✅ CORRECT: Every field has an example (becomes placeholder)
-const schema = {
-  type: "object",
-  properties: {
-    name: {
-      type: "string",
-      title: "Full Name",
-      examples: ["John Doe"]  // First example becomes placeholder
-    },
-    email: {
-      type: "string",
-      format: "email",
-      title: "Email Address",
-      examples: ["john@example.com"]  // Shows expected format
-    },
-    phone: {
-      type: "string",
-      title: "Phone Number",
-      examples: ["+1 (555) 123-4567"]  // Pattern example
-    },
-    age: {
-      type: "integer",
-      title: "Age",
-      examples: [25]  // Works for numbers too
-    },
-    bio: {
-      type: "string",
-      title: "About You",
-      examples: ["Tell us about yourself..."]  // Long text hint
-    }
-  }
-};
+**Rule: When generating a form, infer appropriate placeholders based on field name/type if not specified.**
 
-// ❌ WRONG: Missing examples - fields will have no placeholders
-const badSchema = {
-  type: "object",
-  properties: {
-    email: { type: "string", format: "email" }  // No placeholder!
-  }
-};
-```
+### 5. Smart Icons - Infer from field semantics
 
-**Rule: When generating a form, infer appropriate placeholders based on field name/type if not specified.**
+**When generating forms, automatically add appropriate icons based on field names and semantics.**
 
-### 5. Smart Icons - Auto-infer from field names
+**Sources of truth for available icons:**
+- Check `pds.config.js` for project-specific icon configuration
+- Consult icon sprite at `public/assets/img/icons/pds-icons.svg` for available icons
+- See `public/assets/pds/vscode-custom-data.json` for icon attribute values
 
-**When generating forms, automatically add icons for common field types. Match field names (or semantic meaning) to these icons:**
+**Use semantic reasoning to match field names to appropriate icons:**
 
 ```javascript
-// Icon inference map - use these patterns by default
-const iconInference = {
-  // Contact & Identity
-  'email': 'envelope',
-  'phone': 'phone',
-  'mobile': 'phone',
-  'name': 'user',
-  'username': 'user',
-  'firstname': 'user',
-  'lastname': 'user',
-  'password': 'lock',
-  
-  // Location
-  'address': 'map-pin',
-  'street': 'map-pin',
-  'city': 'building',
-  'location': 'map-marker',
-  'country': 'globe',
-  
-  // Communication
-  'message': 'message',
-  'comment': 'comment',
-  'feedback': 'comment',
-  
-  // Web & Links
-  'website': 'link',
-  'url': 'link',
-  'link': 'link',
-  
-  // Time & Dates
-  'date': 'calendar',
-  'birthday': 'calendar',
-  'time': 'clock',
-  
-  // Categorization
-  'subject': 'tag',
-  'tag': 'tag',
-  'category': 'folder',
-  'priority': 'flag',
-  
-  // Files
-  'file': 'file',
-  'upload': 'upload',
-  'image': 'image',
-  'photo': 'image',
-  
-  // Search
-  'search': 'search',
-  'query': 'search'
-};
-
-// ✅ CORRECT: Auto-generate uiSchema with icons
+// ✅ CORRECT: Infer icons based on field semantics
 const uiSchema = {
   "/email": { 'ui:icon': 'envelope', 'ui:autocomplete': 'email' },
   "/phone": { 'ui:icon': 'phone', 'ui:autocomplete': 'tel' },
   "/name": { 'ui:icon': 'user', 'ui:autocomplete': 'name' },
   "/password": { 'ui:icon': 'lock', 'ui:widget': 'password' },
   "/website": { 'ui:icon': 'link' },
+  "/address": { 'ui:icon': 'map-pin' },
+  "/date": { 'ui:icon': 'calendar' },
   "/message": { 'ui:widget': 'textarea', 'ui:icon': 'message' }
 };
 ```
 
-**Rule: When generating a contact/signup/profile form, infer and add appropriate icons automatically.**
+**Rule: When generating forms, analyze field names/types and select semantically appropriate icons from the available icon set.**
 
 ### 6. Submit Handler Pattern - ALWAYS provide working async handler
 
@@ -509,7 +415,7 @@ form.getFormData(); // May throw error
 <pds-icon icon="heart" size="sm"></pds-icon>
 <pds-icon icon="check" size="lg" color="var(--color-success-500)"></pds-icon>
 
-<!-- Enhancements: data attributes (see pds-enhancer-metadata.js) -->
+<!-- Enhancements: data attributes (see pds-enhancers.js → defaultPDSEnhancerMetadata) -->
 <nav data-dropdown>
   <button>Menu</button>
   <menu><li><a href="#">Item</a></li></menu>
@@ -526,10 +432,12 @@ form.getFormData(); // May throw error
 
 <!-- Tabs: web component -->
 <pds-tabstrip>
-  <button slot="tab">Tab 1</button>
-  <div slot="panel">Content 1</div>
-  <button slot="tab">Tab 2</button>
-  <div slot="panel">Content 2</div>
+  <pds-tabpanel label="Tab 1">
+    <p>Content for Tab 1</p>
+  </pds-tabpanel>
+  <pds-tabpanel label="Tab 2">
+    <p>Content for Tab 2</p>
+  </pds-tabpanel>
 </pds-tabstrip>
 ```
 
@@ -573,7 +481,7 @@ const results = await PDS.query("border gradient classes");
 | "What components are available?" | Read `custom-elements.json` |
 | "What utility classes exist?" | Read `pds-ontology.js` → `layoutPatterns`, `utilities` |
 | "What primitives exist?" | Read `pds-ontology.js` → `primitives` |
-| "How do I enhance HTML?" | Read `pds-enhancer-metadata.js` → `demoHtml` |
+| "How do I enhance HTML?" | Read `pds-enhancers.js` → `defaultPDSEnhancerMetadata` → `demoHtml` |
 | "How are tokens named?" | Read `pds-generator.js` or `pds.css-data.json` |
 
 ---
@@ -587,7 +495,7 @@ Before generating code:
 3. ✅ **No hardcoded values** — Colors, spacing, radii all have tokens
 4. ✅ **No alert/confirm/prompt** — Use `PDS.ask()` and `PDS.toast()`
 5. ✅ **Use semantic HTML** — `<button>`, `<nav>`, `<article>`, `<label>`, `<details>`
-6. ✅ **Apply enhancements via data-* attributes** — See `pds-enhancer-metadata.js`
+6. ✅ **Apply enhancements via data-* attributes** — See `pds-enhancers.js` → `defaultPDSEnhancerMetadata`
 7. ✅ **Components as last resort** — Only when native HTML can't achieve it
 8. ✅ **Prefer primitives** — `.card`, `.badge`, `.alert` over custom components
 9. ✅ **Wait for lazy components** — Use `await customElements.whenDefined()` before accessing APIs