zauberflote 1.0.0 → 1.0.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zauberflote",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Shared UI components for the working examples book.",
   "type": "module",
   "main": "src/ui.js",

package/src/ui.js

@@ -2,11 +2,77 @@ const ui = (() => {
   const pendingApps = [];
   let autoMountScheduled = false;
 
+  // Helper to wrap builders with Proxy for better error messages
+  function wrapBuilder(instance, className, chainHistory = []) {
+    const methods = Object.getOwnPropertyNames(Object.getPrototypeOf(instance))
+      .filter(m => m !== 'constructor' && typeof instance[m] === 'function');
+
+    return new Proxy(instance, {
+      get(target, prop) {
+        // Track chain for error messages
+        target._chainHistory = chainHistory;
+
+        if (prop in target) {
+          const value = target[prop];
+          if (typeof value === 'function') {
+            return function(...args) {
+              const result = value.apply(target, args);
+              // If result is a builder object, wrap it too
+              if (result && typeof result === 'object' && result.constructor &&
+                  result.constructor.name.includes('Builder')) {
+                // Format arguments nicely for the chain
+                const formatArg = (a) => {
+                  if (typeof a === 'string') {
+                    const short = a.length > 20 ? a.slice(0, 20) + '...' : a;
+                    return `"${short.replace(/\n/g, ' ')}"`;
+                  }
+                  if (Array.isArray(a)) return `[${a.length} items]`;
+                  if (typeof a === 'object' && a !== null) return '{...}';
+                  return String(a);
+                };
+                const argStr = args.length > 0 ? `(${args.map(formatArg).join(', ')})` : '()';
+                const newChain = [...chainHistory, `.${prop}${argStr}`];
+                return wrapBuilder(result, result.constructor.name, newChain);
+              }
+              return result;
+            };
+          }
+          return value;
+        }
+
+        // Property doesn't exist - provide helpful error
+        if (typeof prop === 'string' && !prop.startsWith('_')) {
+          const suggestion = methods.find(m => m.toLowerCase().includes(prop.toLowerCase()));
+
+          // Format chain nicely - show last 5 calls max
+          const recentChain = chainHistory.slice(-5);
+          const chainStr = recentChain.length > 0
+            ? (chainHistory.length > 5 ? '  ...\n' : '') + recentChain.map(c => `  ${c}`).join('\n')
+            : '  (start of chain)';
+
+          let errorMsg = `\n[ui.js] ❌ ${className} has no method "${prop}"\n\n`;
+          errorMsg += `Available methods:\n  ${methods.join(', ')}\n\n`;
+          errorMsg += `Chain (last ${Math.min(chainHistory.length, 5)} calls):\n${chainStr}\n  .${prop}() ← ERROR HERE\n`;
+          if (suggestion) {
+            errorMsg += `\n💡 Did you mean: "${suggestion}"?\n`;
+          }
+          console.error(errorMsg);
+
+          // Return a function that throws to give a cleaner stack trace
+          return function() {
+            throw new Error(`[ui.js] ${className}.${prop} is not a function. See console for available methods.`);
+          };
+        }
+        return undefined;
+      }
+    });
+  }
+
   function app(title) {
     const builder = new AppBuilder(title);
     pendingApps.push(builder);
     scheduleAutoMount();
-    return builder;
+    return wrapBuilder(builder, 'AppBuilder', [`ui.app("${title || 'App'}")`]);
   }
 
   class AppBuilder {
@@ -82,7 +148,7 @@ const ui = (() => {
       this.app = app;
       this.parent = parent || null;
       this.title = title || 'Section';
-      this.id = slugify(this.title);
+      this.sectionId = slugify(this.title);
       this.readConfig = null;
       this.listTemplate = '';
       this.actions = [];
@@ -100,14 +166,28 @@ const ui = (() => {
       this.jsonConfig = null;
       this.textConfig = null;
       this.markdownConfig = null;
+      this.htmlContent = null;
       this.customRenderer = null;
+      this.renderHook = null;
       this.autoConfig = null;
+      this.mockConfig = null;
       this.suppressOutput = false;
       this.noAutoRefresh = false;
       this.layoutConfig = null;
+      this.templateMode = null;
     }
     id(value) {
-      this.id = value;
+      this.sectionId = value;
+      return this;
+    }
+    mock(generator) {
+      // Signature: Smart Mocking System - show placeholder data when backend is offline.
+      this.mockConfig = generator;
+      return this;
+    }
+    onRender(callback) {
+      // Signature: Lifecycle hook for custom library initialization (Charts, Maps).
+      this.renderHook = callback;
       return this;
     }
     read(path) {
@@ -127,6 +207,11 @@ const ui = (() => {
       this.listTemplate = template || '';
       return this;
     }
+    template(name) {
+      // Signature: chapter-9 geo-search, live-poll (table display mode).
+      this.templateMode = name || 'default';
+      return this;
+    }
     listFrom(path) {
       // Signature: chapter-4/4-4-pagination (items list from query results).
       this.listFromPath = path;
@@ -151,6 +236,11 @@ const ui = (() => {
       this.storeMap = Object.assign({}, this.storeMap, map);
       return this;
     }
+    hidden() {
+      // Signature: hide section output (useful for store-only reads).
+      this.suppressOutput = true;
+      return this;
+    }
     storeView(key, template) {
       // Signature: chapter-3 JWT/CSRF token display.
       this.storeViewConfig = { key, template: template || `{{${key}}}` };
@@ -171,6 +261,11 @@ const ui = (() => {
       this.textConfig = { text: text || '', path };
       return this;
     }
+    html(content) {
+      // Signature: static HTML content block.
+      this.htmlContent = content || '';
+      return this;
+    }
     markdown(text, path) {
       // Signature: chapter-4/4-1-validation, chapter-0 UI language docs.
       this.markdownConfig = { text: text || '', path };
@@ -274,6 +369,15 @@ const ui = (() => {
       this.path = path;
       return this;
     }
+    delete(path) {
+      // Alias for del() - more intuitive name.
+      return this.del(path);
+    }
+    confirm(message) {
+      // Signature: show confirmation dialog before action.
+      this.confirmMessage = message || 'Are you sure?';
+      return this;
+    }
     upload(path) {
       // Signature: chapter-4/4-8-uploads.
       this.method = 'UPLOAD';
@@ -501,7 +605,7 @@ const ui = (() => {
 
     if (section.actions.length > 0) {
       section.actions.forEach((action) => {
-        actionWrap.appendChild(renderActionForm(action, output, section.appStore, sectionInputs, section));
+        actionWrap.appendChild(renderActionForm(action, output, section.appStore, sectionInputs, section, selectBindings));
       });
       root.appendChild(actionWrap);
     }
@@ -546,6 +650,13 @@ const ui = (() => {
       root.appendChild(markdownWrap);
     }
 
+    // Static HTML content
+    if (section.htmlContent) {
+      const htmlWrap = document.createElement('div');
+      htmlWrap.innerHTML = section.htmlContent;
+      root.appendChild(htmlWrap);
+    }
+
     let customWrap = null;
     if (section.customRenderer) {
       customWrap = document.createElement('div');
@@ -592,6 +703,9 @@ const ui = (() => {
           customWrap.appendChild(result);
         }
       }
+      if (section.renderHook) {
+        section.renderHook({ data, store: section.appStore, element: root });
+      }
     };
 
     const refresh = async () => {
@@ -599,16 +713,65 @@ const ui = (() => {
       if (section.readConfig) {
         const payload = buildQueryPayload(section, sectionInputs, section.appStore);
         const path = buildQueryPath(section.readConfig.path, payload);
-        const data = await request(section.readConfig, null, false, payload, section.appStore, path);
+        let data;
+        try {
+          data = await request(section.readConfig, null, false, payload, section.appStore, path);
+          if (!data.ok && section.mockConfig) {
+            throw new Error("Backend error");
+          }
+          root.classList.remove('is-mocked');
+          root.style.borderStyle = '';
+        } catch (e) {
+          if (section.mockConfig || section.readConfig) {
+            console.warn(`⚠️ Mocking data for section "${section.title}"`);
+            let mockData;
+            if (section.mockConfig) {
+              mockData = typeof section.mockConfig === 'function' ? section.mockConfig(section.appStore) : section.mockConfig;
+            } else {
+              // Auto-inference logic
+              if (section.listTemplate) {
+                mockData = [
+                  { id: 1, name: "Sample Item 1", amount: 100, description: "Mocked data" },
+                  { id: 2, name: "Sample Item 2", amount: 200, description: "Mocked data" }
+                ];
+              } else if (section.kpiConfig) {
+                mockData = {};
+                section.kpiConfig.items.forEach(item => { if (item.key) mockData[item.key] = 0; });
+              } else {
+                mockData = { message: "Mocked response" };
+              }
+            }
+            data = { ok: true, status: 200, json: { data: mockData }, data: mockData };
+            root.classList.add('is-mocked');
+            root.style.borderStyle = 'dashed';
+            root.style.borderColor = '#cbd5e1'; // slate-300
+            if (!root.querySelector('.mock-badge')) {
+              const badge = document.createElement('span');
+              badge.className = 'mock-badge ml-2 inline-flex items-center rounded-md bg-amber-50 px-2 py-1 text-xs font-medium text-amber-700 ring-1 ring-inset ring-amber-600/20';
+              badge.textContent = 'MOCKED';
+              root.querySelector('h2').appendChild(badge);
+            }
+          } else {
+            root.classList.remove('is-mocked');
+            root.style.borderStyle = '';
+            const badge = root.querySelector('.mock-badge');
+            if (badge) badge.remove();
+            throw e;
+          }
+        }
+        if (!root.classList.contains('is-mocked')) {
+          const badge = root.querySelector('.mock-badge');
+          if (badge) badge.remove();
+        }
         section.lastData = data.json || null;
         applyStore(section.appStore, section.storeMap, data.json);
-        const hasExplicitView = section.listFromPath || section.listTemplate || section.kpiConfig || section.jsonConfig || section.textConfig || section.markdownConfig || section.customRenderer;
+        const hasExplicitView = section.listFromPath || section.listTemplate || section.templateMode || section.kpiConfig || section.jsonConfig || section.textConfig || section.markdownConfig || section.customRenderer;
         if (!hasExplicitView && !section.autoConfig) {
           section.autoConfig = { path: section.listFromPath || 'data' };
         }
         if (section.listFromPath) {
           renderList(listWrap, section, { data: getPath(section.appStore, section.listFromPath) });
-        } else if (section.listTemplate) {
+        } else if (section.listTemplate || section.templateMode) {
           renderList(listWrap, section, data);
         }
         if (metaEl && section.metaConfig) {
@@ -649,6 +812,8 @@ const ui = (() => {
 
     section.refresh = refresh;
 
+    window.addEventListener(`ui:refresh:${section.sectionId}`, refresh);
+
     return { root, refresh };
   }
 
@@ -830,12 +995,37 @@ const ui = (() => {
       target.appendChild(empty);
       return;
     }
+    // Table template mode
+    if (section.templateMode === 'table' && rows.length > 0) {
+      const table = document.createElement('table');
+      table.className = 'w-full text-sm border-collapse';
+      const keys = Object.keys(rows[0]);
+      const thead = document.createElement('thead');
+      thead.innerHTML = '<tr class="border-b border-slate-200">' + keys.map(k => `<th class="text-left py-2 px-3 font-medium text-slate-600">${k}</th>`).join('') + '</tr>';
+      table.appendChild(thead);
+      const tbody = document.createElement('tbody');
+      rows.forEach(row => {
+        const tr = document.createElement('tr');
+        tr.className = 'border-b border-slate-100 hover:bg-slate-50';
+        tr.innerHTML = keys.map(k => `<td class="py-2 px-3 text-slate-700">${row[k] ?? ''}</td>`).join('');
+        tbody.appendChild(tr);
+      });
+      table.appendChild(tbody);
+      target.appendChild(table);
+      return;
+    }
     rows.forEach((row) => {
       const card = document.createElement('div');
       card.className = 'rounded border border-slate-200 px-3 py-2 space-y-2';
       if (section.listTemplate) {
         const label = document.createElement('div');
-        label.textContent = renderTemplate(section.listTemplate, row);
+        const rendered = renderTemplate(section.listTemplate, row);
+        // Use innerHTML if template contains HTML tags, otherwise textContent
+        if (/<[^>]+>/.test(rendered)) {
+          label.innerHTML = rendered;
+        } else {
+          label.textContent = rendered;
+        }
         card.appendChild(label);
       } else {
         const label = document.createElement('div');
@@ -857,6 +1047,10 @@ const ui = (() => {
           btn.className = 'rounded border border-slate-300 px-3 py-2 text-sm';
           btn.textContent = action.label;
           btn.addEventListener('click', async () => {
+            // Confirmation dialog if configured
+            if (action.confirmMessage && !window.confirm(action.confirmMessage)) {
+              return;
+            }
             const fields = action.fieldList.length > 0 ? action.fieldList : section.rowFields;
             const body = collectFields(fields, rowInputs);
             const path = renderTemplate(action.path, row, section.appStore);
@@ -878,19 +1072,26 @@ const ui = (() => {
     });
   }
 
-  function renderActionForm(action, output, appStore, sectionInputs, section) {
+  function renderActionForm(action, output, appStore, sectionInputs, section, selectBindings) {
     const wrap = document.createElement('div');
     wrap.className = 'grid gap-2 sm:grid-cols-4';
     const fieldInputs = {};
     action.fieldList.forEach((field) => {
       const input = renderField(field, appStore);
       fieldInputs[field.key] = input;
+      if (field.optionsFrom && selectBindings) {
+        selectBindings.push({ field, input });
+      }
       wrap.appendChild(input);
     });
     const btn = document.createElement('button');
     btn.className = 'rounded border border-slate-300 px-3 py-2 text-sm';
     btn.textContent = action.label;
     btn.addEventListener('click', async () => {
+      // Confirmation dialog if configured
+      if (action.confirmMessage && !window.confirm(action.confirmMessage)) {
+        return;
+      }
       const body = Object.assign({}, action.bodyMap, collectFields(action.fieldList, fieldInputs, sectionInputs));
       applySetMap(appStore, action.setMap, body, sectionInputs);
       applyAdjustments(appStore, action.adjustments, sectionInputs);
@@ -1269,6 +1470,10 @@ const ui = (() => {
 
   function getPath(obj, path) {
     if (!obj || !path) return undefined;
+    if (typeof path !== 'string') {
+      console.error(`[ui.js] getPath expected a string path, got ${typeof path}:`, path);
+      return undefined;
+    }
     return path.split('.').reduce((acc, part) => (acc ? acc[part] : undefined), obj);
   }
 
@@ -1276,15 +1481,37 @@ const ui = (() => {
     if (!bindings || bindings.length === 0) return;
     bindings.forEach(({ field, input }) => {
       if (!field.optionsFrom) return;
-      const list = getPath(store, field.optionsFrom);
-      if (!Array.isArray(list)) return;
+
+      // Handle optionsFrom as object { store: "key", value: "id", label: "name" } or string "key"
+      let storePath, valueKey, labelKey;
+      if (typeof field.optionsFrom === 'string') {
+        storePath = field.optionsFrom;
+        valueKey = field.optionValue || 'id';
+        labelKey = field.optionLabel || 'name';
+      } else if (typeof field.optionsFrom === 'object') {
+        storePath = field.optionsFrom.store;
+        valueKey = field.optionsFrom.value || field.optionValue || 'id';
+        labelKey = field.optionsFrom.label || field.optionLabel || 'name';
+      } else {
+        console.error(`[ui.js] optionsFrom must be a string or object, got:`, field.optionsFrom);
+        return;
+      }
+
+      const list = getPath(store, storePath);
+      if (!Array.isArray(list)) {
+        if (list !== undefined) {
+          console.warn(`[ui.js] optionsFrom "${storePath}" is not an array:`, list);
+        }
+        return;
+      }
+
       const current = input.value;
       input.innerHTML = '';
       list.forEach((row) => {
         const option = document.createElement('option');
-        const value = field.optionValue ? getPath(row, field.optionValue) : row.id ?? row.name ?? row.value ?? '';
+        const value = getPath(row, valueKey) ?? row.id ?? row.name ?? row.value ?? '';
         option.value = value;
-        const label = field.optionLabel ? renderTemplate(field.optionLabel, row, store) : String(value);
+        const label = getPath(row, labelKey) ?? String(value);
         option.textContent = label;
         input.appendChild(option);
       });
@@ -1477,9 +1704,36 @@ const ui = (() => {
     }
   }
 
+  function loadScript(url) {
+    return new Promise((resolve, reject) => {
+      if (document.querySelector(`script[src="${url}"]`)) return resolve();
+      const s = document.createElement('script');
+      s.src = url;
+      s.onload = resolve;
+      s.onerror = reject;
+      document.head.appendChild(s);
+    });
+  }
+
+  function loadCSS(url) {
+    if (document.querySelector(`link[href="${url}"]`)) return;
+    const l = document.createElement('link');
+    l.rel = 'stylesheet';
+    l.href = url;
+    document.head.appendChild(l);
+  }
+
   autoMountPending();
 
-  return { app, mount };
+  // Global listener to bridge ui-refresh events to section-specific events
+  window.addEventListener('ui-refresh', (e) => {
+    const id = e.detail && e.detail.id;
+    if (id) {
+      window.dispatchEvent(new CustomEvent(`ui:refresh:${id}`));
+    }
+  });
+
+  return { app, mount, loadScript, loadCSS };
 })();
 
 export default ui;

package/.env

@@ -1 +0,0 @@
-TOKEN=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