@portel/photon-core 1.5.0 → 2.1.0

package/src/rendering/index.ts

@@ -0,0 +1,63 @@
+/**
+ * Smart Rendering Module
+ *
+ * iOS-inspired, React Admin-influenced rendering system that:
+ * - Convention over configuration - works beautifully with zero annotations
+ * - Smart field detection - guesses meaning from field names and types
+ * - Progressive customization - JSDoc annotations for fine-tuning
+ * - List-centric paradigm - everything renders as configurable list items
+ *
+ * Design System based on:
+ * - Material Design 3 tokens: https://m3.material.io/foundations/design-tokens
+ * - Apple HIG (8pt grid): https://developer.apple.com/design/human-interface-guidelines/layout
+ */
+
+export * from './field-analyzer.js';
+export * from './layout-selector.js';
+export * from './components.js';
+export * from './field-renderers.js';
+export * from './template-engine.js';
+export * from '../design-system/index.js';
+
+import { generateFieldAnalyzerJS } from './field-analyzer.js';
+import { generateLayoutSelectorJS } from './layout-selector.js';
+import { generateComponentsJS, generateComponentCSS } from './components.js';
+import { generateFieldRenderersJS, generateFieldRendererCSS } from './field-renderers.js';
+import { generateTemplateEngineJS, generateTemplateEngineCSS } from './template-engine.js';
+import { generateDesignSystemCSS, generateDesignSystemJS } from '../design-system/index.js';
+
+/**
+ * Generate all JavaScript code for embedding in HTML
+ */
+export function generateSmartRenderingJS(): string {
+  return [
+    '// ==========================================================================',
+    '// Photon Design System + Smart Rendering',
+    '// Based on Material Design 3 + Apple HIG',
+    '// ==========================================================================',
+    '',
+    generateDesignSystemJS(),
+    '',
+    generateFieldAnalyzerJS(),
+    '',
+    generateLayoutSelectorJS(),
+    '',
+    generateFieldRenderersJS(),
+    '',
+    generateComponentsJS(),
+    '',
+    generateTemplateEngineJS(),
+  ].join('\n');
+}
+
+/**
+ * Generate all CSS for embedding in HTML
+ */
+export function generateSmartRenderingCSS(): string {
+  return [
+    generateDesignSystemCSS(),
+    generateComponentCSS(),
+    generateFieldRendererCSS(),
+    generateTemplateEngineCSS(),
+  ].join('\n');
+}

package/src/rendering/layout-selector.ts

@@ -0,0 +1,390 @@
+/**
+ * Layout Selector - Auto-detect best layout for data
+ *
+ * Determines the optimal component/layout to render data based on:
+ * 1. Explicit @format annotation (highest priority)
+ * 2. Data shape (array vs object vs primitive)
+ * 3. Data content (has images -> grid, etc.)
+ */
+
+export type LayoutType =
+  | 'text'      // Simple text/markdown display
+  | 'card'      // Single object as card with header + fields
+  | 'list'      // Array of objects as iOS-style list
+  | 'grid'      // Array of objects as visual grid
+  | 'tree'      // Nested object as collapsible tree
+  | 'kv'        // Flat object as key-value table
+  | 'chips'     // Array of strings as chips/tags
+  | 'table'     // Legacy: grid table (backward compat)
+  | 'markdown'  // Legacy: markdown rendering
+  | 'mermaid'   // Legacy: mermaid diagrams
+  | 'code'      // Code block with syntax highlighting
+  | 'json'      // Raw JSON display
+  | 'html';     // Raw HTML (for custom UIs)
+
+export interface LayoutHints {
+  title?: string;       // Field to use as title
+  subtitle?: string;    // Field to use as subtitle
+  icon?: string;        // Field to use as icon
+  badge?: string;       // Field to use as badge
+  detail?: string;      // Field to use as detail
+  image?: string;       // Field to use as image (grid)
+  style?: string;       // List style (plain, grouped, inset, etc.)
+  accessory?: string;   // Accessory type (chevron, switch, etc.)
+  columns?: number;     // Grid columns
+  fields?: string[];    // Specific fields to show
+}
+
+// Map legacy @format values to new layout types
+const FORMAT_TO_LAYOUT: Record<string, LayoutType> = {
+  'table': 'list',        // table -> list (smart rendering)
+  'list': 'list',
+  'grid': 'grid',
+  'card': 'card',
+  'kv': 'kv',
+  'tree': 'tree',
+  'json': 'json',
+  'markdown': 'markdown',
+  'mermaid': 'mermaid',
+  'code': 'code',
+  'text': 'text',
+  'primitive': 'text',
+  'chips': 'chips',
+  'html': 'html',
+};
+
+/**
+ * Select the best layout type for given data
+ */
+export function selectLayout(
+  data: any,
+  format?: string,
+  hints?: LayoutHints
+): LayoutType {
+  // 1. Explicit format takes precedence (backward compat)
+  if (format) {
+    // Handle code:language format
+    if (format.startsWith('code:')) return 'code';
+
+    const layout = FORMAT_TO_LAYOUT[format] || 'json';
+
+    // Smart fallback: if list/table format but data is not an array, use card
+    if ((layout === 'list' || format === 'table') && !Array.isArray(data) && typeof data === 'object' && data !== null) {
+      return 'card';
+    }
+
+    return layout;
+  }
+
+  // 2. Null/undefined
+  if (data === null || data === undefined) {
+    return 'text';
+  }
+
+  // 3. Primitives
+  if (typeof data === 'string') {
+    // Check if it looks like markdown
+    if (hasMarkdownSyntax(data)) return 'markdown';
+    // Check if it looks like mermaid
+    if (data.trim().startsWith('graph ') || data.trim().startsWith('flowchart ')) {
+      return 'mermaid';
+    }
+    return 'text';
+  }
+
+  if (typeof data === 'number' || typeof data === 'boolean') {
+    return 'text';
+  }
+
+  // 4. Arrays
+  if (Array.isArray(data)) {
+    if (data.length === 0) return 'text'; // Empty array
+
+    const first = data[0];
+
+    // Array of strings -> chips
+    if (typeof first === 'string') {
+      return 'chips';
+    }
+
+    // Array of objects
+    if (typeof first === 'object' && first !== null) {
+      // Check if items have image fields -> grid
+      if (hasImageFields(first)) {
+        return 'grid';
+      }
+      // Default: list
+      return 'list';
+    }
+
+    // Mixed or primitive arrays
+    return 'chips';
+  }
+
+  // 5. Objects
+  if (typeof data === 'object') {
+    // Check for special fields
+    if ('diagram' in data && typeof data.diagram === 'string') {
+      return 'mermaid';
+    }
+
+    // Check if deeply nested -> tree
+    if (isNested(data)) {
+      return 'tree';
+    }
+
+    // Flat object -> card (or kv for many fields)
+    const fieldCount = Object.keys(data).length;
+    if (fieldCount > 10) {
+      return 'kv'; // Too many fields for card
+    }
+
+    return 'card';
+  }
+
+  // Fallback
+  return 'json';
+}
+
+/**
+ * Check if object has fields that look like actual images (not just icon characters)
+ * We need to verify the VALUE looks like an image URL, not just the field name
+ */
+export function hasImageFields(obj: object): boolean {
+  const imageFieldNames = /^(image|photo|thumbnail|picture|poster|cover)$/i;
+  const avatarFieldName = /^(avatar)$/i;
+  const imageUrlPattern = /\.(jpg|jpeg|png|gif|webp|svg)(\?.*)?$/i;
+  const dataUrlPattern = /^data:image\//i;
+
+  for (const [key, value] of Object.entries(obj)) {
+    // Skip non-string values
+    if (typeof value !== 'string') continue;
+
+    // Check for image URL patterns in value
+    if (imageUrlPattern.test(value) || dataUrlPattern.test(value)) return true;
+
+    // For image field names (not avatar), check if value looks like a URL
+    if (imageFieldNames.test(key) && (value.startsWith('http') || value.startsWith('/'))) {
+      return true;
+    }
+
+    // For avatar fields specifically, only treat as image if it's actually a URL
+    // Single characters or short strings are icons, not images
+    if (avatarFieldName.test(key) && value.length > 10 && (value.startsWith('http') || value.startsWith('/'))) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Check if object is nested (has object/array values)
+ */
+export function isNested(obj: object, depth: number = 0): boolean {
+  if (depth > 2) return true; // Max depth check
+
+  for (const value of Object.values(obj)) {
+    if (Array.isArray(value) && value.length > 0 && typeof value[0] === 'object') {
+      return true;
+    }
+    if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+      if (isNested(value, depth + 1)) return true;
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Check if string contains markdown syntax
+ */
+export function hasMarkdownSyntax(text: string): boolean {
+  // Check for common markdown patterns
+  const patterns = [
+    /^#{1,6}\s/m,           // Headers
+    /\*\*[^*]+\*\*/,        // Bold
+    /\*[^*]+\*/,            // Italic
+    /\[[^\]]+\]\([^)]+\)/,  // Links
+    /```[\s\S]*```/,        // Code blocks
+    /^\s*[-*+]\s/m,         // Lists
+    /^\s*\d+\.\s/m,         // Numbered lists
+  ];
+
+  return patterns.some(p => p.test(text));
+}
+
+/**
+ * Parse layout hints from nested JSDoc syntax
+ * Example: {@title name, @subtitle email, @style inset}
+ */
+export function parseLayoutHints(hintsString: string): LayoutHints {
+  const hints: LayoutHints = {};
+
+  if (!hintsString) return hints;
+
+  // Split by comma and parse each hint
+  const parts = hintsString.split(',').map(s => s.trim());
+
+  for (const part of parts) {
+    // Match @key value or @key value:renderer
+    const match = part.match(/@(\w+)\s+([^:]+)(?::(\w+))?/);
+    if (match) {
+      const [, key, value, renderer] = match;
+      const cleanValue = value.trim();
+
+      switch (key) {
+        case 'title': hints.title = cleanValue; break;
+        case 'subtitle': hints.subtitle = cleanValue; break;
+        case 'icon': hints.icon = cleanValue; break;
+        case 'badge': hints.badge = cleanValue; break;
+        case 'detail': hints.detail = cleanValue; break;
+        case 'image': hints.image = cleanValue; break;
+        case 'style': hints.style = cleanValue; break;
+        case 'accessory': hints.accessory = cleanValue; break;
+        case 'columns':
+          hints.columns = parseInt(cleanValue, 10);
+          break;
+        case 'fields':
+          hints.fields = cleanValue.split(/\s+/);
+          break;
+      }
+    }
+  }
+
+  return hints;
+}
+
+/**
+ * Generate JavaScript code for layout selector (to embed in HTML)
+ */
+export function generateLayoutSelectorJS(): string {
+  return `
+// Layout Selector - Auto-detect best layout for data
+const FORMAT_TO_LAYOUT = {
+  'table': 'list',
+  'list': 'list',
+  'grid': 'grid',
+  'card': 'card',
+  'kv': 'kv',
+  'tree': 'tree',
+  'json': 'json',
+  'markdown': 'markdown',
+  'mermaid': 'mermaid',
+  'code': 'code',
+  'text': 'text',
+  'primitive': 'text',
+  'chips': 'chips',
+  'html': 'html',
+};
+
+function selectLayout(data, format, hints) {
+  if (format) {
+    if (format.startsWith('code:')) return 'code';
+    var layout = FORMAT_TO_LAYOUT[format] || 'json';
+    // Smart fallback: if list/table format but data is not an array, use card
+    if ((layout === 'list' || format === 'table') && !Array.isArray(data) && typeof data === 'object' && data !== null) {
+      return 'card';
+    }
+    return layout;
+  }
+
+  if (data === null || data === undefined) return 'text';
+
+  if (typeof data === 'string') {
+    if (hasMarkdownSyntax(data)) return 'markdown';
+    if (data.trim().startsWith('graph ') || data.trim().startsWith('flowchart ')) {
+      return 'mermaid';
+    }
+    return 'text';
+  }
+
+  if (typeof data === 'number' || typeof data === 'boolean') return 'text';
+
+  if (Array.isArray(data)) {
+    if (data.length === 0) return 'text';
+    const first = data[0];
+    if (typeof first === 'string') return 'chips';
+    if (typeof first === 'object' && first !== null) {
+      if (hasImageFields(first)) return 'grid';
+      return 'list';
+    }
+    return 'chips';
+  }
+
+  if (typeof data === 'object') {
+    if ('diagram' in data && typeof data.diagram === 'string') return 'mermaid';
+    if (isNested(data)) return 'tree';
+    const fieldCount = Object.keys(data).length;
+    if (fieldCount > 10) return 'kv';
+    return 'card';
+  }
+
+  return 'json';
+}
+
+function hasImageFields(obj) {
+  const imageFieldNames = /^(image|photo|thumbnail|picture|poster|cover)$/i;
+  const avatarFieldName = /^(avatar)$/i;
+  const imageUrlPattern = /\\.(jpg|jpeg|png|gif|webp|svg)(\\?.*)?$/i;
+  const dataUrlPattern = /^data:image\\//i;
+  for (const [key, value] of Object.entries(obj)) {
+    if (typeof value !== 'string') continue;
+    if (imageUrlPattern.test(value) || dataUrlPattern.test(value)) return true;
+    if (imageFieldNames.test(key) && (value.startsWith('http') || value.startsWith('/'))) return true;
+    if (avatarFieldName.test(key) && value.length > 10 && (value.startsWith('http') || value.startsWith('/'))) return true;
+  }
+  return false;
+}
+
+function isNested(obj, depth = 0) {
+  if (depth > 2) return true;
+  for (const value of Object.values(obj)) {
+    if (Array.isArray(value) && value.length > 0 && typeof value[0] === 'object') return true;
+    if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+      if (isNested(value, depth + 1)) return true;
+    }
+  }
+  return false;
+}
+
+function hasMarkdownSyntax(text) {
+  const patterns = [
+    /^#{1,6}\\s/m,
+    /\\*\\*[^*]+\\*\\*/,
+    /\\*[^*]+\\*/,
+    /\\[[^\\]]+\\]\\([^)]+\\)/,
+    /\`\`\`[\\s\\S]*\`\`\`/,
+    /^\\s*[-*+]\\s/m,
+    /^\\s*\\d+\\.\\s/m,
+  ];
+  return patterns.some(p => p.test(text));
+}
+
+function parseLayoutHints(hintsString) {
+  const hints = {};
+  if (!hintsString) return hints;
+  const parts = hintsString.split(',').map(s => s.trim());
+  for (const part of parts) {
+    const match = part.match(/@(\\w+)\\s+([^:]+)(?::(\\w+))?/);
+    if (match) {
+      const [, key, value, renderer] = match;
+      const cleanValue = value.trim();
+      switch (key) {
+        case 'title': hints.title = cleanValue; break;
+        case 'subtitle': hints.subtitle = cleanValue; break;
+        case 'icon': hints.icon = cleanValue; break;
+        case 'badge': hints.badge = cleanValue; break;
+        case 'detail': hints.detail = cleanValue; break;
+        case 'image': hints.image = cleanValue; break;
+        case 'style': hints.style = cleanValue; break;
+        case 'accessory': hints.accessory = cleanValue; break;
+        case 'columns': hints.columns = parseInt(cleanValue, 10); break;
+        case 'fields': hints.fields = cleanValue.split(/\\s+/); break;
+      }
+    }
+  }
+  return hints;
+}
+`;
+}

package/src/rendering/template-engine.ts

@@ -0,0 +1,254 @@
+/**
+ * Template Engine - Custom HTML Template Support
+ *
+ * Enables custom UI templates that map elements to class methods.
+ * Perfect for specialized interfaces like:
+ * - TV remote control
+ * - Numeric keypad
+ * - Dashboard with gauges
+ * - Media player controls
+ *
+ * Template Binding Attributes:
+ * - data-method: Method to call on click
+ * - data-args: JSON arguments to pass
+ * - data-result: Container for method output
+ * - data-bind: Live data binding
+ * - data-if: Conditional visibility
+ */
+
+export interface TemplateBinding {
+  element: string;        // CSS selector
+  method: string;         // Method name
+  args?: any;             // Arguments to pass
+  event?: string;         // Event to listen for (default: 'click')
+}
+
+export interface TemplateConfig {
+  id: string;             // Template identifier
+  path: string;           // Path to template file
+  bindings?: TemplateBinding[];  // Pre-defined bindings (optional)
+}
+
+/**
+ * Parse template HTML and extract data-method bindings
+ */
+export function parseTemplateBindings(html: string): TemplateBinding[] {
+  const bindings: TemplateBinding[] = [];
+
+  // Match elements with data-method attribute
+  const methodRegex = /data-method=["']([^"']+)["']/g;
+  const argsRegex = /data-args=["']([^"']+)["']/g;
+
+  // Note: This is a simplified parser - actual implementation
+  // would use DOM parsing in the browser
+
+  return bindings;
+}
+
+/**
+ * Generate JavaScript for template engine (to embed in HTML)
+ */
+export function generateTemplateEngineJS(): string {
+  return `
+// ==========================================================================
+// Template Engine - Custom UI Template Support
+// ==========================================================================
+
+/**
+ * Initialize template bindings for custom UI
+ * Finds all elements with data-method and binds click handlers
+ */
+function initTemplateBindings(container, invokeMethod) {
+  // Find all elements with data-method attribute
+  const methodElements = container.querySelectorAll('[data-method]');
+
+  methodElements.forEach(el => {
+    const methodName = el.getAttribute('data-method');
+    const argsStr = el.getAttribute('data-args');
+    const eventType = el.getAttribute('data-event') || 'click';
+
+    // Parse args if present
+    let args = {};
+    if (argsStr) {
+      try {
+        args = JSON.parse(argsStr);
+      } catch (e) {
+        console.warn('Invalid data-args JSON:', argsStr);
+      }
+    }
+
+    // Add event listener
+    el.addEventListener(eventType, async (e) => {
+      e.preventDefault();
+      e.stopPropagation();
+
+      // Add loading state
+      el.classList.add('template-loading');
+
+      try {
+        // Invoke the method
+        const result = await invokeMethod(methodName, args);
+
+        // Find result container and update
+        const resultContainer = container.querySelector('[data-result]');
+        if (resultContainer && result !== undefined) {
+          // Use smart rendering for the result
+          const rendered = renderSmartResult(result, null, null);
+          if (rendered) {
+            resultContainer.innerHTML = rendered;
+          } else {
+            resultContainer.textContent = JSON.stringify(result, null, 2);
+          }
+        }
+      } catch (error) {
+        console.error('Template method error:', error);
+        const resultContainer = container.querySelector('[data-result]');
+        if (resultContainer) {
+          resultContainer.innerHTML = '<div class="template-error">' + escapeHtml(error.message) + '</div>';
+        }
+      } finally {
+        el.classList.remove('template-loading');
+      }
+    });
+  });
+
+  // Handle data-bind for live updates
+  const bindElements = container.querySelectorAll('[data-bind]');
+  bindElements.forEach(el => {
+    const bindKey = el.getAttribute('data-bind');
+    // Store reference for later updates
+    el._bindKey = bindKey;
+  });
+
+  // Handle data-if for conditional visibility
+  const ifElements = container.querySelectorAll('[data-if]');
+  ifElements.forEach(el => {
+    const condition = el.getAttribute('data-if');
+    el._ifCondition = condition;
+    // Initially hidden until condition is evaluated
+    el.style.display = 'none';
+  });
+}
+
+/**
+ * Update bound elements with new data
+ */
+function updateTemplateBindings(container, data) {
+  // Update data-bind elements
+  const bindElements = container.querySelectorAll('[data-bind]');
+  bindElements.forEach(el => {
+    const bindKey = el._bindKey || el.getAttribute('data-bind');
+    if (bindKey && data[bindKey] !== undefined) {
+      if (el.tagName === 'INPUT' || el.tagName === 'TEXTAREA') {
+        el.value = data[bindKey];
+      } else {
+        el.textContent = data[bindKey];
+      }
+    }
+  });
+
+  // Update data-if elements
+  const ifElements = container.querySelectorAll('[data-if]');
+  ifElements.forEach(el => {
+    const condition = el._ifCondition || el.getAttribute('data-if');
+    if (condition) {
+      // Evaluate condition against data
+      const value = data[condition];
+      el.style.display = value ? '' : 'none';
+    }
+  });
+}
+
+/**
+ * Load and render a custom template
+ */
+async function loadTemplate(templatePath, container, invokeMethod) {
+  try {
+    // Fetch template content
+    const response = await fetch('/api/template?path=' + encodeURIComponent(templatePath));
+    if (!response.ok) {
+      throw new Error('Failed to load template: ' + response.statusText);
+    }
+
+    const html = await response.text();
+    container.innerHTML = html;
+
+    // Initialize bindings
+    initTemplateBindings(container, invokeMethod);
+
+    return true;
+  } catch (error) {
+    console.error('Template load error:', error);
+    container.innerHTML = '<div class="template-error">Failed to load template: ' + escapeHtml(error.message) + '</div>';
+    return false;
+  }
+}
+`;
+}
+
+/**
+ * Generate CSS for template engine
+ */
+export function generateTemplateEngineCSS(): string {
+  return `
+/* Template Engine Styles */
+.template-loading {
+  opacity: 0.6;
+  pointer-events: none;
+  position: relative;
+}
+
+.template-loading::after {
+  content: '';
+  position: absolute;
+  top: 50%;
+  left: 50%;
+  width: 16px;
+  height: 16px;
+  margin: -8px 0 0 -8px;
+  border: 2px solid var(--accent);
+  border-top-color: transparent;
+  border-radius: 50%;
+  animation: template-spin 0.8s linear infinite;
+}
+
+@keyframes template-spin {
+  to { transform: rotate(360deg); }
+}
+
+.template-error {
+  color: var(--error);
+  padding: 12px;
+  background: rgba(239, 68, 68, 0.1);
+  border-radius: 8px;
+  font-size: 0.875rem;
+}
+
+/* Template button styles */
+[data-method] {
+  cursor: pointer;
+  transition: all 0.15s ease;
+}
+
+[data-method]:hover {
+  filter: brightness(1.1);
+}
+
+[data-method]:active {
+  transform: scale(0.98);
+}
+
+/* Result container */
+[data-result] {
+  min-height: 40px;
+  padding: 8px;
+  border-radius: 8px;
+  background: var(--bg-tertiary);
+}
+
+[data-result]:empty::before {
+  content: '—';
+  color: var(--text-muted);
+}
+`;
+}