@od-oneapp/ai-platform 0.1.0

package/src/generative-ui/catalog.ts

@@ -0,0 +1,653 @@
+/**
+ * @fileoverview Enterprise Generative UI Catalog.
+ * @module @od-oneapp/ai-platform/generative-ui
+ *
+ * Creates and manages component catalogs for AI-driven UI generation.
+ * Wraps component definitions with governance (entitlement filtering,
+ * audit logging, validation) for enterprise deployments.
+ *
+ * @example
+ * ```ts
+ * import { createEnterpriseCatalog, BASE_CATALOG_COMPONENTS } from '@od-oneapp/ai-platform/generative-ui';
+ *
+ * const catalog = createEnterpriseCatalog({
+ *   components: BASE_CATALOG_COMPONENTS,
+ *   enableEntitlementFiltering: true,
+ *   enableAuditLogging: true,
+ * });
+ *
+ * // Get components available for a pro user
+ * const proComponents = catalog.getComponentsForTier('pro');
+ *
+ * // Generate system prompt section
+ * const promptSection = catalog.generatePromptSection('pro');
+ * ```
+ */
+
+import type {
+  CatalogComponent,
+  EnterpriseCatalog,
+  EnterpriseCatalogConfig,
+  UIElement,
+  UITree,
+  UITreeValidationError,
+  UITreeValidationResult,
+} from './types';
+import type { UserTier } from "../governance/entitlements";
+
+
+// ---------------------------------------------------------------------------
+// Tier Ordering
+// ---------------------------------------------------------------------------
+
+const TIER_ORDER: Record<UserTier, number> = {
+  free: 0,
+  pro: 1,
+  enterprise: 2,
+};
+
+/**
+ * Check if a user tier has access to a component's minimum tier requirement.
+ */
+function tierHasAccess(userTier: UserTier, minTier?: UserTier): boolean {
+  if (!minTier) return true;
+  return TIER_ORDER[userTier] >= TIER_ORDER[minTier];
+}
+
+// ---------------------------------------------------------------------------
+// Base Catalog Components
+// ---------------------------------------------------------------------------
+
+/**
+ * Base catalog of generative UI components.
+ * Maps to `@od-oneapp/uni-ui` components for rendering.
+ *
+ * Categories:
+ * - **layout**: Structural containers (Card, Grid, Stack, Section)
+ * - **data**: Data display (DataTable, List, Badge, Tag)
+ * - **chart**: Visualizations (BarChart, LineChart, PieChart, AreaChart)
+ * - **metric**: KPI displays (MetricCard, ProgressBar, StatGroup)
+ * - **action**: Interactive elements (Button, Link, CallToAction)
+ * - **feedback**: Status indicators (Alert, StatusBadge, Skeleton)
+ */
+export const BASE_CATALOG_COMPONENTS: readonly CatalogComponent[] = [
+  // === Layout ===
+  {
+    name: 'Card',
+    description:
+      'Container with border, padding, and optional header/footer. Use as a grouping wrapper.',
+    category: 'layout',
+    acceptsChildren: true,
+    props: [
+      { name: 'title', type: 'string', description: 'Optional card header text', required: false },
+      {
+        name: 'subtitle',
+        type: 'string',
+        description: 'Optional subtitle below the title',
+        required: false,
+      },
+      {
+        name: 'variant',
+        type: 'string',
+        description: 'Visual variant',
+        enum: ['default', 'outlined', 'elevated'],
+        default: 'default',
+      },
+    ],
+  },
+  {
+    name: 'Grid',
+    description: 'Responsive grid layout. Distributes children in a CSS grid.',
+    category: 'layout',
+    acceptsChildren: true,
+    props: [
+      {
+        name: 'columns',
+        type: 'number',
+        description: 'Number of columns (1-6)',
+        required: false,
+        default: 2,
+      },
+      {
+        name: 'gap',
+        type: 'string',
+        description: 'Gap size',
+        enum: ['sm', 'md', 'lg'],
+        default: 'md',
+      },
+    ],
+  },
+  {
+    name: 'Stack',
+    description: 'Vertical or horizontal flex container for stacking children.',
+    category: 'layout',
+    acceptsChildren: true,
+    props: [
+      {
+        name: 'direction',
+        type: 'string',
+        description: 'Stack direction',
+        enum: ['vertical', 'horizontal'],
+        default: 'vertical',
+      },
+      {
+        name: 'gap',
+        type: 'string',
+        description: 'Gap size',
+        enum: ['sm', 'md', 'lg'],
+        default: 'md',
+      },
+      {
+        name: 'align',
+        type: 'string',
+        description: 'Alignment',
+        enum: ['start', 'center', 'end', 'stretch'],
+        default: 'stretch',
+      },
+    ],
+  },
+  {
+    name: 'Section',
+    description:
+      'Semantic section with heading and optional description. Use to organize content areas.',
+    category: 'layout',
+    acceptsChildren: true,
+    props: [
+      { name: 'heading', type: 'string', description: 'Section heading', required: true },
+      {
+        name: 'description',
+        type: 'string',
+        description: 'Optional section description',
+        required: false,
+      },
+    ],
+  },
+
+  // === Data ===
+  {
+    name: 'DataTable',
+    description: 'Tabular data display with headers and rows. Use for structured datasets.',
+    category: 'data',
+    minTier: 'pro',
+    props: [
+      { name: 'headers', type: 'array', description: 'Column header labels', required: true },
+      {
+        name: 'rows',
+        type: 'array',
+        description: 'Array of row arrays (each row is an array of cell values)',
+        required: true,
+      },
+      { name: 'caption', type: 'string', description: 'Optional table caption', required: false },
+      { name: 'striped', type: 'boolean', description: 'Alternate row shading', default: true },
+    ],
+  },
+  {
+    name: 'List',
+    description: 'Ordered or unordered list display.',
+    category: 'data',
+    props: [
+      {
+        name: 'items',
+        type: 'array',
+        description: 'Array of string items to display',
+        required: true,
+      },
+      { name: 'ordered', type: 'boolean', description: 'Use numbered list', default: false },
+    ],
+  },
+  {
+    name: 'Badge',
+    description: 'Small status label or tag. Use inline with text or in table cells.',
+    category: 'data',
+    props: [
+      { name: 'label', type: 'string', description: 'Badge text', required: true },
+      {
+        name: 'variant',
+        type: 'string',
+        description: 'Visual style',
+        enum: ['default', 'success', 'warning', 'error', 'info'],
+        default: 'default',
+      },
+    ],
+  },
+  {
+    name: 'KeyValue',
+    description: 'Key-value pair display. Use for simple attribute lists.',
+    category: 'data',
+    props: [
+      { name: 'label', type: 'string', description: 'Key/label text', required: true },
+      { name: 'value', type: 'string', description: 'Value text', required: true },
+    ],
+  },
+
+  // === Charts (pro+) ===
+  {
+    name: 'BarChart',
+    description: 'Vertical or horizontal bar chart for comparing quantities across categories.',
+    category: 'chart',
+    minTier: 'pro',
+    props: [
+      {
+        name: 'data',
+        type: 'array',
+        description: 'Array of { label, value } objects',
+        required: true,
+      },
+      { name: 'title', type: 'string', description: 'Chart title', required: false },
+      {
+        name: 'orientation',
+        type: 'string',
+        description: 'Bar direction',
+        enum: ['vertical', 'horizontal'],
+        default: 'vertical',
+      },
+      {
+        name: 'color',
+        type: 'string',
+        description: 'Bar color',
+        enum: ['primary', 'secondary', 'success', 'warning', 'error'],
+        default: 'primary',
+      },
+    ],
+  },
+  {
+    name: 'LineChart',
+    description: 'Line chart for showing trends over time or continuous data.',
+    category: 'chart',
+    minTier: 'pro',
+    props: [
+      {
+        name: 'data',
+        type: 'array',
+        description: 'Array of { x, y } or { label, value } objects',
+        required: true,
+      },
+      { name: 'title', type: 'string', description: 'Chart title', required: false },
+      { name: 'xLabel', type: 'string', description: 'X-axis label', required: false },
+      { name: 'yLabel', type: 'string', description: 'Y-axis label', required: false },
+    ],
+  },
+  {
+    name: 'PieChart',
+    description: 'Pie/donut chart for showing proportions of a whole.',
+    category: 'chart',
+    minTier: 'pro',
+    props: [
+      {
+        name: 'data',
+        type: 'array',
+        description: 'Array of { label, value } objects',
+        required: true,
+      },
+      { name: 'title', type: 'string', description: 'Chart title', required: false },
+      { name: 'donut', type: 'boolean', description: 'Show as donut chart', default: false },
+    ],
+  },
+  {
+    name: 'AreaChart',
+    description: 'Filled area chart for showing volume or cumulative trends.',
+    category: 'chart',
+    minTier: 'enterprise',
+    props: [
+      { name: 'data', type: 'array', description: 'Array of { x, y } objects', required: true },
+      { name: 'title', type: 'string', description: 'Chart title', required: false },
+      { name: 'stacked', type: 'boolean', description: 'Stack multiple series', default: false },
+    ],
+  },
+
+  // === Metrics ===
+  {
+    name: 'MetricCard',
+    description:
+      'KPI card showing a single metric with value, label, trend, and optional sparkline.',
+    category: 'metric',
+    props: [
+      {
+        name: 'label',
+        type: 'string',
+        description: 'Metric label (e.g., "Monthly Revenue")',
+        required: true,
+      },
+      {
+        name: 'value',
+        type: 'string',
+        description: 'Formatted value (e.g., "$1.2M", "94%")',
+        required: true,
+      },
+      {
+        name: 'trend',
+        type: 'string',
+        description: 'Trend direction',
+        enum: ['up', 'down', 'stable'],
+        required: false,
+      },
+      {
+        name: 'trendValue',
+        type: 'string',
+        description: 'Trend percentage (e.g., "+12%")',
+        required: false,
+      },
+      {
+        name: 'sentiment',
+        type: 'string',
+        description: 'Color sentiment',
+        enum: ['positive', 'negative', 'neutral', 'warning'],
+        default: 'neutral',
+      },
+    ],
+  },
+  {
+    name: 'ProgressBar',
+    description: 'Progress indicator showing completion percentage.',
+    category: 'metric',
+    props: [
+      { name: 'label', type: 'string', description: 'Progress label', required: true },
+      { name: 'value', type: 'number', description: 'Current value (0-100)', required: true },
+      { name: 'max', type: 'number', description: 'Maximum value', default: 100 },
+      {
+        name: 'variant',
+        type: 'string',
+        description: 'Color variant',
+        enum: ['default', 'success', 'warning', 'error'],
+        default: 'default',
+      },
+    ],
+  },
+  {
+    name: 'StatGroup',
+    description: 'Horizontal group of stats. Use for showing related numbers together.',
+    category: 'metric',
+    props: [
+      {
+        name: 'stats',
+        type: 'array',
+        description: 'Array of { label, value } objects',
+        required: true,
+      },
+    ],
+  },
+
+  // === Actions ===
+  {
+    name: 'CallToAction',
+    description:
+      'Prominent action button with optional description. Use sparingly for primary actions.',
+    category: 'action',
+    minTier: 'pro',
+    props: [
+      { name: 'label', type: 'string', description: 'Button label', required: true },
+      {
+        name: 'description',
+        type: 'string',
+        description: 'Supporting text below the button',
+        required: false,
+      },
+      {
+        name: 'action',
+        type: 'string',
+        description: 'Action identifier (handled by app)',
+        required: true,
+      },
+      {
+        name: 'variant',
+        type: 'string',
+        description: 'Button style',
+        enum: ['primary', 'secondary', 'outline'],
+        default: 'primary',
+      },
+    ],
+  },
+
+  // === Feedback ===
+  {
+    name: 'Alert',
+    description: 'Alert/banner message for drawing attention to important information.',
+    category: 'feedback',
+    props: [
+      { name: 'title', type: 'string', description: 'Alert title', required: true },
+      { name: 'description', type: 'string', description: 'Alert body text', required: false },
+      {
+        name: 'severity',
+        type: 'string',
+        description: 'Alert severity',
+        enum: ['info', 'success', 'warning', 'error'],
+        default: 'info',
+      },
+    ],
+  },
+  {
+    name: 'StatusBadge',
+    description: 'Status indicator with dot and label.',
+    category: 'feedback',
+    props: [
+      { name: 'label', type: 'string', description: 'Status text', required: true },
+      {
+        name: 'status',
+        type: 'string',
+        description: 'Status type',
+        enum: ['online', 'offline', 'busy', 'away', 'error'],
+        required: true,
+      },
+    ],
+  },
+] as const;
+
+// ---------------------------------------------------------------------------
+// Catalog Factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Validates a single UI element against the catalog.
+ */
+function validateElement(
+  element: UIElement,
+  components: Map<string, CatalogComponent>,
+  tier: UserTier,
+  path: string,
+): UITreeValidationError[] {
+  const errors: UITreeValidationError[] = [];
+
+  const component = components.get(element.type);
+
+  if (!component) {
+    errors.push({
+      path,
+      message: `Unknown component type: '${element.type}'`,
+      severity: 'error',
+    });
+    return errors;
+  }
+
+  // Check tier access
+  if (!tierHasAccess(tier, component.minTier)) {
+    errors.push({
+      path,
+      message: `Component '${element.type}' requires ${component.minTier} tier (user has ${tier})`,
+      severity: 'error',
+    });
+  }
+
+  // Check required props
+  for (const propSchema of component.props) {
+    if (propSchema.required && !(propSchema.name in element.props)) {
+      errors.push({
+        path: `${path}.props.${propSchema.name}`,
+        message: `Required prop '${propSchema.name}' missing on '${element.type}'`,
+        severity: 'error',
+      });
+    }
+  }
+
+  // Check for unknown props (warning only)
+  const knownPropNames = new Set(component.props.map(p => p.name));
+  for (const propName of Object.keys(element.props)) {
+    if (!knownPropNames.has(propName)) {
+      errors.push({
+        path: `${path}.props.${propName}`,
+        message: `Unknown prop '${propName}' on '${element.type}'`,
+        severity: 'warning',
+      });
+    }
+  }
+
+  // Check children
+  if (element.children && !component.acceptsChildren) {
+    errors.push({
+      path: `${path}.children`,
+      message: `Component '${element.type}' does not accept children`,
+      severity: 'warning',
+    });
+  }
+
+  // Recursively validate children
+  if (element.children) {
+    for (let i = 0; i < element.children.length; i++) {
+      const child = element.children[i];
+      if (child) {
+        errors.push(...validateElement(child, components, tier, `${path}.children[${i}]`));
+      }
+    }
+  }
+
+  return errors;
+}
+
+/**
+ * Generates a system prompt section describing available components.
+ */
+function buildPromptSection(components: readonly CatalogComponent[]): string {
+  const lines: string[] = [
+    '## Available UI Components',
+    '',
+    'You can compose interfaces using these components. Return a JSON UITree.',
+    '',
+  ];
+
+  // Group by category
+  const byCategory = new Map<string, CatalogComponent[]>();
+  for (const comp of components) {
+    const list = byCategory.get(comp.category) ?? [];
+    list.push(comp);
+    byCategory.set(comp.category, list);
+  }
+
+  for (const [category, comps] of byCategory) {
+    lines.push(`### ${category.charAt(0).toUpperCase() + category.slice(1)}`);
+    lines.push('');
+
+    for (const comp of comps) {
+      const propsDesc = comp.props
+        .map(p => {
+          let desc = `  - \`${p.name}\` (${p.type}${p.required ? ', required' : ''}): ${p.description}`;
+          if (p.enum) desc += ` [${p.enum.join(' | ')}]`;
+          if (p.default !== undefined) desc += ` (default: ${JSON.stringify(p.default)})`;
+          return desc;
+        })
+        .join('\n');
+
+      lines.push(`**${comp.name}**: ${comp.description}`);
+      if (comp.acceptsChildren) lines.push('  - Accepts children: yes');
+      if (propsDesc) lines.push(propsDesc);
+      lines.push('');
+    }
+  }
+
+  lines.push('### UITree JSON Schema');
+  lines.push('');
+  lines.push('```json');
+  lines.push(
+    JSON.stringify(
+      {
+        version: '1.0',
+        root: {
+          type: 'ComponentName',
+          props: { '...': '...' },
+          children: ['...recursive UIElement[]'],
+        },
+      },
+      null,
+      2,
+    ),
+  );
+  lines.push('```');
+
+  return lines.join('\n');
+}
+
+/**
+ * Creates an enterprise generative UI catalog with governance extensions.
+ *
+ * @param config - Catalog configuration.
+ * @returns EnterpriseCatalog instance.
+ *
+ * @example
+ * ```ts
+ * const catalog = createEnterpriseCatalog({
+ *   components: BASE_CATALOG_COMPONENTS,
+ *   enableEntitlementFiltering: true,
+ * });
+ *
+ * // Generate prompt for pro-tier user
+ * const prompt = catalog.generatePromptSection('pro');
+ *
+ * // Validate AI-generated tree
+ * const result = catalog.validateTree(tree, 'pro');
+ * ```
+ */
+export function createEnterpriseCatalog(config: EnterpriseCatalogConfig): EnterpriseCatalog {
+  const allComponents = config.validateComponent
+    ? config.components.filter(config.validateComponent)
+    : [...config.components];
+
+  const componentMap = new Map<string, CatalogComponent>(allComponents.map(c => [c.name, c]));
+
+  return {
+    components: allComponents,
+
+    getComponentsForTier(tier: UserTier): readonly CatalogComponent[] {
+      if (!config.enableEntitlementFiltering) {
+        return allComponents;
+      }
+
+      return allComponents.filter(c => tierHasAccess(tier, c.minTier));
+    },
+
+    getComponent(name: string): CatalogComponent | undefined {
+      return componentMap.get(name);
+    },
+
+    generatePromptSection(tier: UserTier): string {
+      let components = this.getComponentsForTier(tier);
+
+      // Limit components in prompt to control token cost
+      if (config.maxComponentsInPrompt && components.length > config.maxComponentsInPrompt) {
+        components = components.slice(0, config.maxComponentsInPrompt);
+      }
+
+      return buildPromptSection(components);
+    },
+
+    validateTree(tree: UITree, tier: UserTier): UITreeValidationResult {
+      if (tree.version !== '1.0') {
+        return {
+          valid: false,
+          errors: [
+            {
+              path: 'version',
+              message: `Unsupported UITree version: '${tree.version}'. Expected '1.0'.`,
+              severity: 'error',
+            },
+          ],
+        };
+      }
+
+      const errors = validateElement(tree.root, componentMap, tier, 'root');
+      const hasErrors = errors.some(e => e.severity === 'error');
+
+      return {
+        valid: !hasErrors,
+        errors,
+      };
+    },
+  };
+}