@pure-ds/core 0.4.24 → 0.4.26

package/.github/copilot-instructions.md

@@ -41,6 +41,356 @@ PDS follows the [Pure Web Manifesto](https://pureweb.dev/manifesto): "The browse
 - `public/assets/pds/vscode-custom-data.json`
 - `src/js/pds-core/pds-ontology.js`
 
+**Path resolution helper:** When looking up SSoT files:
+1. First check if `node_modules/@pure-ds/core/` exists (consuming project)
+2. Otherwise use workspace root paths (pure-ds development)
+3. Prefer reading actual files over guessing - the data is authoritative
+
+---
+
+## 📋 pds-form Best Practices
+
+**When generating pds-form code, ALWAYS follow these patterns:**
+
+### 1. Event Handling - Use `pw:submit`, NOT `submit`
+
+```javascript
+// ✅ CORRECT: Listen to pw:submit custom event
+form.addEventListener('pw:submit', async (e) => {
+  const { json, formData, valid, issues } = e.detail;
+  if (valid) {
+    // Handle submission with json or formData
+  }
+});
+
+// ❌ WRONG: Native submit event
+form.addEventListener('submit', (e) => { /* Won't work */ });
+```
+
+### 2. Submit Button Progress - Add `btn-working` automatically
+
+**When user requests a form with async submission, ALWAYS:**
+- Add `btn-working` class to submit button during processing
+- Remove it when done (PDS automatically shows spinner icon)
+- Use a realistic 2-3 second delay for demos
+
+```javascript
+// ✅ CORRECT: Auto-add progress state
+form.addEventListener('pw:submit', async (e) => {
+  const submitBtn = form.querySelector('button[type="submit"]');
+  submitBtn?.classList.add('btn-working');
+  
+  try {
+    await simulateSubmit(e.detail.json); // 2-3 second promise
+    await PDS.toast('Submitted successfully!', { type: 'success' });
+  } finally {
+    submitBtn?.classList.remove('btn-working');
+  }
+});
+
+async function simulateSubmit(data) {
+  await new Promise(resolve => setTimeout(resolve, 2000));
+  console.log('Submitted:', data);
+}
+```
+
+### 3. Progressive Enhancement - Add `data-required` to form wrapper
+
+```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>
+```
+
+### 4. Placeholders - ALWAYS include examples
+
+**Placeholders improve UX significantly. ALWAYS add examples 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
+    }
+  }
+};
+
+// ❌ WRONG: Missing examples - fields will have no placeholders
+const badSchema = {
+  type: "object",
+  properties: {
+    email: { type: "string", format: "email" }  // No placeholder!
+  }
+};
+```
+
+**Rule: When generating a form, infer appropriate placeholders based on field name/type if not specified.**
+
+### 5. Smart Icons - Auto-infer from field names
+
+**When generating forms, automatically add icons for common field types. Match field names (or semantic meaning) to these 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
+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' },
+  "/message": { 'ui:widget': 'textarea', 'ui:icon': 'message' }
+};
+```
+
+**Rule: When generating a contact/signup/profile form, infer and add appropriate icons automatically.**
+
+### 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: 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: 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
+});
+```
+
+**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' });
+
+// 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 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 = {
+  // ✅ ALWAYS add these when "other" enum exists
+  "/otherReason": {
+    "ui:visibleWhen": { "/reason": "other" },
+    "ui:requiredWhen": { "/reason": "other" },
+  },
+};
+```
+
+### 8. Complete Working Example
+
+```javascript
+// Schema with examples for placeholders
+const contactSchema = {
+  type: "object",
+  required: ["name", "email", "message"],
+  properties: {
+    name: {
+      type: "string",
+      title: "Name",
+      minLength: 2,
+      examples: ["John Doe"]
+    },
+    email: {
+      type: "string",
+      format: "email",
+      title: "Email",
+      examples: ["user@example.com"]
+    },
+    message: {
+      type: "string",
+      title: "Message",
+      minLength: 10,
+      examples: ["Your message here..."]
+    }
+  }
+};
+
+// UI schema with smart icons
+const uiSchema = {
+  "/name": { 'ui:icon': 'user' },
+  "/email": { 'ui:icon': 'envelope' },
+  "/message": { 
+    'ui:widget': 'textarea',
+    'ui:rows': 4,
+    'ui:icon': 'message'
+  }
+};
+
+// Setup with pw:submit and btn-working
+const form = document.getElementById('contactForm');
+form.jsonSchema = contactSchema;
+form.uiSchema = uiSchema;
+
+form.addEventListener('pw:submit', async (e) => {
+  const submitBtn = form.querySelector('button[type="submit"]');
+  submitBtn?.classList.add('btn-working');
+  
+  try {
+    // Simulate 2s async operation
+    await new Promise(resolve => setTimeout(resolve, 2000));
+    console.log('Submitted:', e.detail.json);
+    await PDS.toast('Message sent!', { type: 'success' });
+    form.reset();
+  } catch (error) {
+    await PDS.toast('Failed to send', { type: 'error' });
+  } finally {
+    submitBtn?.classList.remove('btn-working');
+  }
+});
+```
+
 ---
 
 ## 🚫 Critical Anti-Patterns (NEVER DO THIS)
@@ -61,7 +411,7 @@ PDS follows the [Pure Web Manifesto](https://pureweb.dev/manifesto): "The browse
 
 ```javascript
 // ❌ NEVER: Browser dialogs - Use PDS.ask() and PDS.toast()
-alert("message");   // → PDS.toast("message", { type: "info" })
+alert("message");   // → await PDS.toast("message", { type: "info" })
 confirm("sure?");   // → await PDS.ask("sure?", { type: "confirm" })
 prompt("name?");    // → await PDS.ask("name?", { type: "prompt" })
 
@@ -71,6 +421,23 @@ prompt("name?");    // → await PDS.ask("name?", { type: "prompt" })
 // ❌ NEVER: Access lazy-loaded component APIs before they're defined
 const form = document.querySelector('pds-form');
 form.getFormData(); // May fail - component not loaded yet
+
+// ❌ NEVER: Use native 'submit' event with pds-form
+form.addEventListener('submit', (e) => { }); // → Use 'pw:submit'
+
+// ❌ NEVER: Forget btn-working class for async operations
+button.onclick = async () => {
+  await fetch('/api'); // No loading indicator!
+};
+// → Add button.classList.add('btn-working') before, remove after
+
+// ❌ NEVER: Hardcode placeholders instead of using schema examples
+const schema = { 
+  properties: { 
+    email: { type: "string" } // Missing examples!
+  }
+};
+// → Add examples: ["user@example.com"]
 ```
 
 ---
@@ -173,7 +540,7 @@ const confirmed = await PDS.ask("Delete this item?", {
   buttons: { ok: { name: "Delete", variant: "danger" } }
 });
 
-PDS.toast("Saved successfully!", { type: "success" });
+await PDS.toast("Saved successfully!", { type: "success" });
 
 // Theme management
 PDS.theme = 'dark';  // 'light' | 'dark' | 'system'
@@ -184,6 +551,20 @@ 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
+
+**For toast notifications:**
+- 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)
+
+---
+
 ## How to Look Things Up
 
 | Question | Action |
@@ -211,3 +592,11 @@ Before generating code:
 8. ✅ **Prefer primitives** — `.card`, `.badge`, `.alert` over custom components
 9. ✅ **Wait for lazy components** — Use `await customElements.whenDefined()` before accessing APIs
 10. ✅ **Include import map** — When using `pds-form` or `pds-drawer`, ensure `#pds/lit` is mapped
+
+**For pds-form specifically:**
+
+11. ✅ **Use `pw:submit` event** — NOT native `submit` event
+12. ✅ **Add `btn-working` class** — For async submit operations, add during processing
+13. ✅ **Use `examples` in JSON schema** — First example becomes placeholder
+14. ✅ **Add smart icons** — Infer icons based on field names (email→envelope, phone→phone)
+15. ✅ **Wrap in `form[data-required]`** — For asterisk enhancement on required fields