@pure-ds/core 0.7.57 → 0.7.58

package/packages/pds-cli/lib/pds-mcp-core.js

@@ -70,6 +70,439 @@ function buildSuggestions(items, term, limit = 5) {
   return [...new Set([...starts, ...contains])].slice(0, limit);
 }
 
+function includesAny(text, terms = []) {
+  return terms.some((term) => text.includes(term));
+}
+
+// ─── Topic-specific guidance note builders ───────────────────────────────────
+
+function buildFormWidgetGuidanceNotes(q) {
+  const notes = [];
+
+  if (includesAny(q, ['omnibox', 'ui:widget', 'widget', 'renderer', 'definerenderer', 'uischema', 'ui schema'])) {
+    notes.push({
+      title: 'Use widget keys, not custom element tag names',
+      guidance:
+        'In pds-form uiSchema, use the built-in widget key "omnibox", not the HTML tag name "pds-omnibox". The tag name is the rendered element; the widget key is the renderer lookup key.\n' +
+        'Built-in widget keys: "omnibox", "upload", "richtext", "input-iso-interval", "input-range", "password", "textarea", "date".',
+      evidence: [
+        { source: 'public/assets/pds/components/pds-form.js', detail: 'Built-in renderer is registered under defineRenderer("omnibox", ...).' },
+        { source: 'pds-form-docs.md', detail: 'Available PDS component widgets list.' },
+      ],
+    });
+
+    notes.push({
+      title: 'Pass omnibox settings via ui:options.settings',
+      guidance:
+        'When using the built-in omnibox renderer, put the PdsOmniboxSettings object under uiSchema[path]["ui:options"].settings.\n' +
+        'The renderer reads ui?.["ui:options"]?.settings and assigns it to .settings on <pds-omnibox>.\n\n' +
+        'Example:\n' +
+        'const omniboxSettings = { categories: { Countries: { trigger: ({ search }) => search.length >= 2, getItems: async ({ search }) => [...] } } };\n' +
+        'const uiSchema = { "/country": { "ui:widget": "omnibox", "ui:options": { icon: "globe", settings: omniboxSettings } } };',
+      evidence: [
+        { source: 'public/assets/pds/components/pds-form.js', detail: 'Renderer extracts settings from ui?.["ui:options"]?.settings.' },
+        { source: 'pds-form-docs.md', detail: 'Omnibox examples place settings inside ui:options.settings.' },
+      ],
+    });
+  }
+
+  if (includesAny(q, ['definerenderer', 'renderer', 'custom widget', 'custom renderer', 'omnibox'])) {
+    notes.push({
+      title: 'Prefer built-in renderers before defineRenderer()',
+      guidance:
+        'Do not reach for form.defineRenderer() when pds-form already provides the widget.\n' +
+        'Use defineRenderer() only for truly custom widgets or intentionally different aliases.',
+      evidence: [
+        { source: 'public/assets/pds/components/pds-form.js', detail: 'pds-form registers built-in renderers for omnibox, upload, richtext, input-range, and others.' },
+        { source: 'pds-form-docs.md', detail: 'defineRenderer() is documented as the custom-widget extension point, not the first choice for built-in widgets.' },
+      ],
+    });
+  }
+
+  if (includesAny(q, ['settings', 'uischema', 'ui schema', 'omnibox'])) {
+    notes.push({
+      title: 'Declare settings objects before uiSchema uses them',
+      guidance:
+        'If a const uiSchema references a settings object, declare that settings object first.\n' +
+        'Referencing a later const produces a runtime Temporal Dead Zone (TDZ) error.\n\n' +
+        '✅ const mySettings = { ... };\n' +
+        '   const uiSchema = { "/field": { "ui:options": { settings: mySettings } } };\n\n' +
+        '❌ const uiSchema = { "/field": { "ui:options": { settings: mySettings } } }; // TDZ error!\n' +
+        '   const mySettings = { ... };',
+      evidence: [{ source: 'pds-form-docs.md', detail: 'Examples define settings objects before uiSchema blocks that reference them.' }],
+    });
+  }
+
+  if (includesAny(q, ['daterange', 'iso-interval', 'input-iso-interval', 'travel date', 'date range'])) {
+    notes.push({
+      title: 'Use the built-in ISO interval date-range path',
+      guidance:
+        'For a pds-daterange-backed field in pds-form, prefer format: "iso-interval" or the built-in widget key "input-iso-interval".\n\n' +
+        'Schema: { type: "string", format: "iso-interval" }\n' +
+        'Or uiSchema: { "/dates": { "ui:widget": "input-iso-interval" } }',
+      evidence: [{ source: 'pds-form-docs.md', detail: 'format: "iso-interval" and widget key "input-iso-interval" for pds-daterange rendering.' }],
+    });
+  }
+
+  return notes;
+}
+
+function buildFormSubmitGuidanceNotes(q) {
+  if (!includesAny(q, ['submit', 'pw:submit', 'btn-working', 'onsubmit', 'async', 'handler', 'working'])) return [];
+
+  return [
+    {
+      title: 'pds-form: listen to pw:submit (NOT native submit); use btn-working during async',
+      guidance:
+        'The native "submit" event does NOT fire on pds-form. Always listen to "pw:submit".\n' +
+        'e.detail contains: { json, formData, valid, issues }.\n' +
+        'Add "btn-working" class to the submit button during async operations — PDS shows a spinner automatically.\n\n' +
+        'Complete pattern:\n' +
+        'form.addEventListener(\'pw:submit\', async (e) => {\n' +
+        '  const submitBtn = form.querySelector(\'button[type="submit"]\');\n' +
+        '  submitBtn?.classList.add(\'btn-working\');\n' +
+        '  try {\n' +
+        '    // Simulate or real API call:\n' +
+        '    await new Promise(resolve => setTimeout(resolve, 2000));\n' +
+        '    console.log(\'Submitted:\', e.detail.json);\n' +
+        '    await PDS.toast(\'Saved!\', { type: \'success\' });\n' +
+        '    form.reset();\n' +
+        '  } catch (err) {\n' +
+        '    await PDS.toast(\'Error: \' + err.message, { type: \'error\' });\n' +
+        '  } finally {\n' +
+        '    submitBtn?.classList.remove(\'btn-working\');\n' +
+        '  }\n' +
+        '});',
+      evidence: [
+        { source: 'pds-form-docs.md', detail: 'pw:submit event documentation and btn-working pattern.' },
+        { source: 'custom-elements.json', detail: 'pds-form events list.' },
+      ],
+    },
+  ];
+}
+
+function buildFormIconGuidanceNotes(q) {
+  if (!includesAny(q, ['icon', 'ui:icon', 'placeholder', 'examples', 'schema property', 'text input', 'email input'])) return [];
+
+  return [
+    {
+      title: 'ui:icon is ONLY valid on text-like inputs; use schema examples for placeholders',
+      guidance:
+        'ui:icon (icon-input rendering) is valid ONLY for: text, email, url, tel, search, password.\n' +
+        'NEVER add ui:icon to: date-range, range sliders, textarea, select, checkbox/radio groups, omnibox, or upload.\n\n' +
+        '✅ Correct:\n' +
+        '  "/email": { "ui:icon": "envelope", "ui:autocomplete": "email" }\n' +
+        '  "/name":  { "ui:icon": "user" }\n' +
+        '  "/phone": { "ui:icon": "phone" }\n\n' +
+        '❌ Wrong:\n' +
+        '  "/notes": { "ui:widget": "textarea", "ui:icon": "message" }      // textarea — NO\n' +
+        '  "/dates": { "ui:widget": "date-range", "ui:icon": "calendar" }   // date-range — NO\n' +
+        '  "/budget": { "ui:widget": "input-range", "ui:icon": "coins" }    // range — NO\n\n' +
+        'Placeholders: add an "examples" array to schema properties; the first value becomes the placeholder.\n' +
+        '  name: { type: "string", examples: ["John Doe"] }\n' +
+        '  email: { type: "string", format: "email", examples: ["user@example.com"] }',
+      evidence: [{ source: 'pds-form-docs.md', detail: 'ui:icon scope rules and schema examples for placeholders.' }],
+    },
+  ];
+}
+
+function buildFormConditionalFieldGuidanceNotes(q) {
+  if (!includesAny(q, ['other', 'conditional', 'visiblewhen', 'requiredwhen', '"other"', 'please specify'])) return [];
+
+  return [
+    {
+      title: 'Auto-generate conditional "Other" text field with ui:visibleWhen + ui:requiredWhen',
+      guidance:
+        'When a schema has an "other" enum option, always add a companion conditional text field.\n\n' +
+        'Schema:\n' +
+        '  reason: {\n' +
+        '    type: "string",\n' +
+        '    oneOf: [\n' +
+        '      { const: "search", title: "Search Engine" },\n' +
+        '      { const: "other", title: "Other... (please specify)" }\n' +
+        '    ]\n' +
+        '  },\n' +
+        '  otherReason: { type: "string", examples: ["Tell us more..."] }\n\n' +
+        'uiSchema:\n' +
+        '  "/otherReason": {\n' +
+        '    "ui:visibleWhen": { "/reason": "other" },\n' +
+        '    "ui:requiredWhen": { "/reason": "other" }\n' +
+        '  }',
+      evidence: [{ source: 'pds-form-docs.md', detail: 'ui:visibleWhen and ui:requiredWhen documentation.' }],
+    },
+  ];
+}
+
+function buildFormGuidanceNotes(question) {
+  const q = normalize(question);
+  const isFormQuestion = includesAny(q, [
+    'pds-form', 'uischema', 'ui schema', 'ui:widget', 'widget', 'renderer', 'definerenderer',
+    'omnibox', 'daterange', 'iso-interval', 'input-iso-interval', 'form', 'pw:submit',
+    'btn-working', 'jsonschema', 'json schema',
+  ]);
+  if (!isFormQuestion) return [];
+
+  return [
+    ...buildFormWidgetGuidanceNotes(q),
+    ...buildFormSubmitGuidanceNotes(q),
+    ...buildFormIconGuidanceNotes(q),
+    ...buildFormConditionalFieldGuidanceNotes(q),
+  ];
+}
+
+function buildLocalizationGuidanceNotes(question) {
+  const q = normalize(question);
+  const isLocalization = includesAny(q, [
+    'locali', 'i18n', 'msg(', ' msg ', 'setlocale', 'loadlocale', 'locale',
+    'translat', 'language island', 'getlocalizationstate', 'createjsonlocalization',
+  ]);
+  if (!isLocalization) return [];
+
+  return [
+    {
+      title: 'Import localization helpers from #pds — NOT from #pds/lit',
+      guidance:
+        'msg(), str, setLocale(), loadLocale(), getLocalizationState() are all exported from "#pds".\n' +
+        '#pds/lit only re-exports Lit and lazyProps — do NOT use it for localization.\n\n' +
+        'Configure in pds.config.js:\n' +
+        '  import { PDS } from "@pure-ds/core";\n' +
+        '  const localization = PDS.createJSONLocalization({\n' +
+        '    locale: "en",\n' +
+        '    locales: ["en", "nl"],\n' +
+        '    aliases: { en: ["en", "en-US"], nl: ["nl", "nl-NL"] },\n' +
+        '    basePath: "/assets/locales",\n' +
+        '  });\n' +
+        '  export const config = { mode: "live", preset: "default", localization };\n\n' +
+        'Locale file format (e.g. public/assets/locales/nl-NL.json):\n' +
+        '  { "Hello {0}": { "content": "Hallo {0}" } }\n\n' +
+        'Use in modules:\n' +
+        '  import { PDS, msg } from "#pds";\n' +
+        '  document.body.innerHTML = msg("Hello world");\n\n' +
+        'See LOCALIZATION.md for the full guide.',
+      evidence: [
+        { source: 'LOCALIZATION.md', detail: 'Full localization setup and usage guide.' },
+        { source: 'src/js/pds-core/pds-config.js', detail: 'PDS.createJSONLocalization config shape.' },
+      ],
+    },
+    {
+      title: 'Localization is DOM-contextual via lang attributes — language islands supported',
+      guidance:
+        'msg() resolves translation using the nearest ancestor lang attribute on the DOM.\n' +
+        'localization.locale is the fallback locale, NOT a forced global language.\n\n' +
+        'Language island example:\n' +
+        '  document.documentElement.lang = "en";\n' +
+        '  document.body.innerHTML = `\n' +
+        '    <p>${msg("Hello")}</p>            <!-- English -->\n' +
+        '    <div lang="nl">\n' +
+        '      <p>${msg("Hello")}</p>          <!-- Dutch -->\n' +
+        '    </div>\n' +
+        '  `;',
+      evidence: [{ source: 'LOCALIZATION.md', detail: 'Contextual translation by DOM lang scope.' }],
+    },
+  ];
+}
+
+function buildDomBuildingGuidanceNotes(question) {
+  const q = normalize(question);
+  const isDomBuilding = includesAny(q, [
+    'parse(', 'pds.parse', 'html(', 'pds.html', 'html`', 'parse`',
+    'tagged template', 'event binding', '@click', '.prop=', '?disabled',
+    'create element', 'appendchild', 'documentfragment', 'dom build',
+    'dom element', 'event handler', ' parse ', 'html function', 'parse function',
+  ]);
+  if (!isDomBuilding) return [];
+
+  return [
+    {
+      title: 'parse() → NodeList | html() → DocumentFragment; bindings require tagged template syntax',
+      guidance:
+        'parse() returns a NodeList (legacy-compatible).\n' +
+        'html() returns a DocumentFragment for direct appendChild().\n\n' +
+        'CRITICAL: Event handlers and property bindings REQUIRE tagged template syntax (backticks without parens).\n' +
+        'Regular string mode (with parens) does NOT support bindings — functions get stringified.\n\n' +
+        '── String mode (no bindings): ──\n' +
+        "  const btn = parse('<button class=\"btn-primary\">Save</button>')[0];\n" +
+        '  document.body.appendChild(btn);\n\n' +
+        '── Tagged template (with bindings): ──\n' +
+        '  const handler = () => console.log("clicked");\n' +
+        '  const btn = parse`\n' +
+        '    <button\n' +
+        '      class=${"btn-primary"}\n' +
+        '      ?disabled=${false}\n' +
+        '      @click=${handler}\n' +
+        '    >Click</button>\n' +
+        '  `[0];\n\n' +
+        '── html() tagged template: ──\n' +
+        '  document.body.appendChild(html`\n' +
+        '    <div @click=${handler}>Content</div>\n' +
+        '  `);\n\n' +
+        'Binding prefixes:\n' +
+        '  @event=${fn}       — addEventListener\n' +
+        '  .prop=${val}       — DOM property assignment\n' +
+        '  ?boolean=${bool}   — boolean attribute toggle\n' +
+        '  attr=${val}        — regular attribute (set/remove)',
+      evidence: [{ source: 'src/js/pds.js', detail: 'parse() and html() exports with tagged template engine.' }],
+    },
+  ];
+}
+
+function buildToastDialogGuidanceNotes(question) {
+  const q = normalize(question);
+  const isInteraction = includesAny(q, [
+    'toast', 'dialog', 'pds.ask', 'pds.toast', 'confirm(', 'alert(', 'prompt(',
+    'modal', 'notification', '.ask(', 'beforeclose', 'toaster',
+  ]);
+  if (!isInteraction) return [];
+
+  return [
+    {
+      title: 'Use PDS.ask() and PDS.toast() — NEVER browser dialogs',
+      guidance:
+        'alert()  → await PDS.toast("message", { type: "info" })\n' +
+        'confirm() → await PDS.ask("message", { type: "confirm" })\n' +
+        'prompt()  → await PDS.ask("message", { type: "prompt" })\n\n' +
+        'PDS.toast(message, options) — non-blocking async notification:\n' +
+        '  await PDS.toast("Saved!", { type: "success" });\n' +
+        '  await PDS.toast("Error occurred", { type: "error" });\n' +
+        '  await PDS.toast("Warning", { type: "warning", persistent: true });\n' +
+        '  await PDS.toast("Info", { type: "information", duration: 3000 });\n\n' +
+        'PDS.ask(message, options) — async modal dialog:\n' +
+        '  // Confirm:\n' +
+        '  const confirmed = await PDS.ask("Delete this item?", {\n' +
+        '    type: "confirm",\n' +
+        '    buttons: { ok: { name: "Delete", variant: "danger" } }\n' +
+        '  });\n\n' +
+        '  // Custom with beforeClose guard:\n' +
+        '  await PDS.ask("Publish?", {\n' +
+        '    title: "Final approval",\n' +
+        '    buttons: { ok: { name: "Publish", primary: true }, cancel: { name: "Cancel", cancel: true } },\n' +
+        '    beforeClose: async ({ actionKind }) => {\n' +
+        '      if (actionKind !== "ok") return true;\n' +
+        '      const ok = await checkCanPublish();\n' +
+        '      return { allow: ok };\n' +
+        '    }\n' +
+        '  });\n\n' +
+        'Import PDS: import { PDS } from "#pds";',
+      evidence: [
+        { source: 'src/js/common/toast.js', detail: 'PDS.toast() implementation.' },
+        { source: 'custom-elements.json', detail: 'pds-toaster component API.' },
+      ],
+    },
+  ];
+}
+
+function buildTreeviewGuidanceNotes(question) {
+  const q = normalize(question);
+  const isTreeview = includesAny(q, [
+    'treeview', 'pds-treeview', 'tree view', 'lazy node', 'haschildren',
+    'getchildren', 'node-load', 'expandable node', 'tree node',
+  ]);
+  if (!isTreeview) return [];
+
+  return [
+    {
+      title: 'pds-treeview: options.source + options.getChildren for lazy loading',
+      guidance:
+        'Set tree.options with source (initial payload) and getChildren for deferred fetch.\n' +
+        'Mark expandable nodes with hasChildren: true; children need not be pre-loaded.\n' +
+        'getChildren fires once per node on first expand.\n\n' +
+        'Example:\n' +
+        '  const tree = document.getElementById("myTree");\n' +
+        '  tree.options = {\n' +
+        '    source: [\n' +
+        '      {\n' +
+        '        id: "docs",\n' +
+        '        text: "Documentation",\n' +
+        '        hasChildren: true,\n' +
+        '        children: [\n' +
+        '          { id: "guides", text: "Guides", hasChildren: true },\n' +
+        '          { id: "api",    text: "API",    hasChildren: true }\n' +
+        '        ]\n' +
+        '      }\n' +
+        '    ],\n' +
+        '    getChildren: async ({ nodeId }) => {\n' +
+        '      const res = await fetch(`/api/tree?parent=${encodeURIComponent(nodeId)}`);\n' +
+        '      return res.ok ? res.json() : [];\n' +
+        '    }\n' +
+        '  };\n\n' +
+        'Events for telemetry/retries: "node-load", "node-load-error".\n' +
+        'Prefer shallow initial payloads (root + 1-2 levels); fetch deeper on expand.',
+      evidence: [{ source: 'custom-elements.json', detail: 'pds-treeview options API and events.' }],
+    },
+  ];
+}
+
+function buildLitImportMapGuidanceNotes(question) {
+  const q = normalize(question);
+  const isLit = includesAny(q, [
+    'import map', 'importmap', '#pds/lit', 'pds-form', 'lazyprops', 'lazy-props',
+    'whendefined', 'lit component', 'lit element',
+  ]);
+  if (!isLit) return [];
+
+  return [
+    {
+      title: 'Lit-based components (pds-form) require an import map and customElements.whenDefined()',
+      guidance:
+        'pds-form uses Lit. Add this import map in the HTML <head> BEFORE any module scripts:\n\n' +
+        '  <script type="importmap">\n' +
+        '  {\n' +
+        '    "imports": {\n' +
+        '      "#pds": "/assets/pds/core.js",\n' +
+        '      "#pds/lit": "/assets/pds/external/lit.js"\n' +
+        '    }\n' +
+        '  }\n' +
+        '  </script>\n\n' +
+        'Always await definition before setting properties:\n' +
+        '  await customElements.whenDefined("pds-form");\n' +
+        '  const form = document.querySelector("pds-form");\n' +
+        '  form.jsonSchema = schema; // safe\n\n' +
+        'lazyProps directive (from #pds/lit) for Lit templates:\n' +
+        '  import { lazyProps } from "#pds/lit";\n' +
+        '  html`<pds-fab ${lazyProps({ satellites })}></pds-fab>`\n\n' +
+        'Localization helpers (msg, setLocale, etc.) come from "#pds", NOT "#pds/lit".',
+      evidence: [
+        { source: 'LIT-REQUIREMENTS.md', detail: 'Lit requirements and import map setup.' },
+        { source: 'custom-elements.json', detail: 'pds-form component API.' },
+      ],
+    },
+  ];
+}
+
+function buildEmptyStateGuidanceNotes(question) {
+  const q = normalize(question);
+  if (!includesAny(q, ['empty state', 'empty-state', 'no results', 'onboarding', 'zero state', 'no data'])) return [];
+
+  return [
+    {
+      title: 'Use .empty-state primitive for empty/onboarding states',
+      guidance:
+        'The .empty-state primitive structures an empty or onboarding UI.\n' +
+        'Pattern: heading + supporting text + icon + primary/secondary actions.\n\n' +
+        'Example:\n' +
+        '  <div class="empty-state">\n' +
+        '    <pds-icon icon="inbox" size="xl"></pds-icon>\n' +
+        '    <h3>No items yet</h3>\n' +
+        '    <p class="text-muted">Get started by creating your first item.</p>\n' +
+        '    <button class="btn-primary">Create item</button>\n' +
+        '  </div>',
+      evidence: [{ source: 'src/js/pds-core/pds-ontology.js', detail: '.empty-state primitive definition.' }],
+    },
+  ];
+}
+
+function buildAllGuidanceNotes(question) {
+  return [
+    ...buildFormGuidanceNotes(question),
+    ...buildLocalizationGuidanceNotes(question),
+    ...buildDomBuildingGuidanceNotes(question),
+    ...buildToastDialogGuidanceNotes(question),
+    ...buildTreeviewGuidanceNotes(question),
+    ...buildLitImportMapGuidanceNotes(question),
+    ...buildEmptyStateGuidanceNotes(question),
+  ];
+}
+
 function getToolSchema() {
   return [
     {
@@ -103,7 +536,7 @@ function getToolSchema() {
     },
     {
       name: 'query_design_system',
-      description: 'Run natural-language PDS design system search against SSoT-backed data. Form truth: ui:icon/icon-input rendering is only for regular text-like inputs (text/email/url/tel/search/password), not date/range/textarea/select/choice widgets.',
+      description: 'Run natural-language PDS design system search against SSoT-backed data. Form truth: ui:icon/icon-input rendering is only for regular text-like inputs (text/email/url/tel/search/password), not date/range/textarea/select/choice widgets. For pds-form guidance, prefer built-in widget keys such as "omnibox" over tag names such as "pds-omnibox", and pass omnibox settings through ui:options.settings.',
       inputSchema: {
         type: 'object',
         required: ['question'],
@@ -398,6 +831,7 @@ async function handleQueryDesignSystem(ctx, args = {}) {
 
   const engine = new PDSQuery(pseudoPds);
   const results = await engine.search(question);
+  const guidanceNotes = buildAllGuidanceNotes(question);
 
   return {
     ssoTRoot: normalizePath(ctx.ssoTRoot),
@@ -408,6 +842,7 @@ async function handleQueryDesignSystem(ctx, args = {}) {
     },
     question,
     totalMatches: results.length,
+    guidanceNotes,
     results,
   };
 }