aibos-design-system 1.0.0 → 1.0.1

package/lib/cli-filter-engine.ts

@@ -0,0 +1,271 @@
+/**
+ * Filter Engine: Translator between CLI and Table
+ * 
+ * This is the missing link that makes the CLI control the table.
+ * It parses tokens from the CLI parser and applies them to row data.
+ * 
+ * See docs/CLI_FILTER_INTEGRATION.md for usage examples.
+ */
+
+export interface FilterToken {
+  type: 'key-value' | 'operator' | 'raw';
+  key?: string;
+  operator?: string;
+  value?: string;
+  text?: string;
+}
+
+export interface FilterContext {
+  tokens: FilterToken[];
+  matchCount: number;
+  totalCount: number;
+}
+
+export interface AggregateMetrics {
+  count: number;
+  revenue: { total: number; average: number };
+  health: { total: number; average: number; distribution: Record<string, number> };
+  status: Record<string, number>;
+  riskLevel: 'low' | 'medium' | 'high' | 'critical';
+  description: string;
+}
+
+/**
+ * FilterEngine
+ * 
+ * Accepts parsed CLI tokens and applies them to a dataset.
+ * Handles:
+ * - Enum values (status:healthy)
+ * - Numeric operators (revenue>100000, health<70)
+ * - String matching (owner:"A. Patel")
+ * - AND logic (all filters must match)
+ */
+export class FilterEngine {
+  /**
+   * Parse CLI input into filter tokens
+   * 
+   * Converts raw CLI text like "status:healthy owner:chen revenue>100000"
+   * into structured FilterToken objects.
+   */
+  parseFilters(input: string): FilterToken[] {
+    if (!input.trim()) return [];
+
+    const tokens: FilterToken[] = [];
+    
+    // Match patterns like "key:value", "key>value", "key<value", etc.
+    const regex = /([a-z-]+)([:<>=!]*)"?([^"\s]+)"?/gi;
+    let match;
+
+    while ((match = regex.exec(input)) !== null) {
+      const key = match[1].toLowerCase();
+      const operator = match[2] || '=';
+      const value = match[3];
+
+      tokens.push({
+        type: 'key-value',
+        key,
+        operator,
+        value,
+        text: match[0],
+      });
+    }
+
+    return tokens;
+  }
+
+  /**
+   * Apply parsed filters to rows
+   * 
+   * Returns only rows where ALL filters match (AND logic).
+   * Handles type coercion (numeric, date, enum).
+   */
+  applyFilters(
+    rows: any[],
+    tokens: FilterToken[],
+    fieldMap?: Record<string, string>
+  ): any[] {
+    if (tokens.length === 0) return rows;
+
+    return rows.filter(row => {
+      return tokens.every(token => {
+        if (token.type !== 'key-value') return true;
+
+        const { key, operator, value } = token;
+        if (!key || !value) return true;
+
+        // Map CLI key to actual data field
+        const fieldName = fieldMap?.[key] || key;
+        const rowValue = row[fieldName] || row.dataset?.[fieldName];
+
+        // Type checking and comparison
+        return this.compareValues(rowValue, operator || '=', value);
+      });
+    });
+  }
+
+  /**
+   * Compare row value against filter criteria
+   * 
+   * Handles:
+   * - String equality: "healthy" === "healthy"
+   * - String contains: "patel".includes("tel")
+   * - Numeric comparison: 100000 > 50000
+   * - Date comparison: "2024-01-01" > "2023-12-31"
+   */
+  private compareValues(
+    rowValue: any,
+    operator: string,
+    filterValue: string
+  ): boolean {
+    // Normalize row value
+    const normalizedRow = String(rowValue).toLowerCase().trim();
+    const normalizedFilter = filterValue.toLowerCase().trim();
+
+    // Handle numeric operators
+    if (['>','<','>=','<=','=','!='].includes(operator)) {
+      const rowNum = parseFloat(normalizedRow);
+      const filterNum = parseFloat(normalizedFilter);
+
+      if (!isNaN(rowNum) && !isNaN(filterNum)) {
+        switch (operator) {
+          case '>': return rowNum > filterNum;
+          case '<': return rowNum < filterNum;
+          case '>=': return rowNum >= filterNum;
+          case '<=': return rowNum <= filterNum;
+          case '=': return rowNum === filterNum;
+          case '!=': return rowNum !== filterNum;
+        }
+      }
+    }
+
+    // Handle string matching (equality by default, or contains)
+    if (operator === '=' || operator === ':') {
+      return normalizedRow === normalizedFilter || normalizedRow.includes(normalizedFilter);
+    }
+
+    if (operator === '!=') {
+      return normalizedRow !== normalizedFilter;
+    }
+
+    return false;
+  }
+
+  /**
+   * Get filter statistics
+   */
+  getStats(rows: any[], matchedRows: any[]): FilterContext {
+    return {
+      tokens: [],
+      matchCount: matchedRows.length,
+      totalCount: rows.length,
+    };
+  }
+
+  /**
+   * Generate human-readable filter description
+   * 
+   * Converts "status:healthy revenue>100000" into
+   * "Status is healthy AND Revenue greater than 100000"
+   */
+  describeFilters(tokens: FilterToken[]): string {
+    return tokens
+      .filter(t => t.type === 'key-value' && t.key && t.value)
+      .map(t => {
+        const opSymbol = {
+          ':': 'is',
+          '=': 'equals',
+          '>': 'greater than',
+          '<': 'less than',
+          '>=': 'at least',
+          '<=': 'at most',
+          '!=': 'not equals',
+        }[t.operator || '='] || 'is';
+
+        return `${t.key} ${opSymbol} ${t.value}`;
+      })
+      .join(' AND ');
+  }
+
+  /**
+   * Calculate aggregate metrics from filtered rows
+   * 
+   * Provides high-level insights:
+   * - Total and average revenue
+   * - Average health score
+   * - Status distribution
+   * - Risk assessment
+   * 
+   * This is the "HUD" data for the Decision Engine.
+   */
+  aggregateMetrics(rows: any[]): AggregateMetrics {
+    if (rows.length === 0) {
+      return {
+        count: 0,
+        revenue: { total: 0, average: 0 },
+        health: { total: 0, average: 0, distribution: {} },
+        status: {},
+        riskLevel: 'low',
+        description: 'No data to analyze',
+      };
+    }
+
+    // Revenue metrics
+    const revenues = rows
+      .map(row => parseFloat(row.dataset?.revenue || row.revenue || 0))
+      .filter(v => !isNaN(v));
+    const totalRevenue = revenues.reduce((sum, v) => sum + v, 0);
+    const avgRevenue = revenues.length > 0 ? totalRevenue / revenues.length : 0;
+
+    // Health metrics
+    const healths = rows
+      .map(row => parseFloat(row.dataset?.health || row.health || 0))
+      .filter(v => !isNaN(v));
+    const totalHealth = healths.reduce((sum, v) => sum + v, 0);
+    const avgHealth = healths.length > 0 ? totalHealth / healths.length : 0;
+
+    // Status distribution
+    const statusCounts: Record<string, number> = {};
+    rows.forEach(row => {
+      const status = (row.dataset?.status || row.status || 'unknown').toLowerCase();
+      statusCounts[status] = (statusCounts[status] || 0) + 1;
+    });
+
+    // Health distribution (buckets)
+    const healthBuckets: Record<string, number> = {
+      'critical': 0,    // < 40
+      'poor': 0,        // 40-60
+      'fair': 0,        // 60-80
+      'good': 0,        // 80-95
+      'excellent': 0,   // 95+
+    };
+    healths.forEach(h => {
+      if (h < 40) healthBuckets.critical++;
+      else if (h < 60) healthBuckets.poor++;
+      else if (h < 80) healthBuckets.fair++;
+      else if (h < 95) healthBuckets.good++;
+      else healthBuckets.excellent++;
+    });
+
+    // Risk assessment
+    const watchCount = statusCounts['watch'] || 0;
+    const criticalCount = healthBuckets.critical;
+    const riskScore = (watchCount * 0.5) + (criticalCount * 0.3);
+
+    let riskLevel: 'low' | 'medium' | 'high' | 'critical' = 'low';
+    if (riskScore >= 2) riskLevel = 'critical';
+    else if (riskScore >= 1.5) riskLevel = 'high';
+    else if (riskScore >= 0.75) riskLevel = 'medium';
+
+    // Trend indicator
+    const trend = avgRevenue > 0 ? (avgHealth / 100) > 0.8 ? '↗' : '↘' : '→';
+
+    return {
+      count: rows.length,
+      revenue: { total: totalRevenue, average: avgRevenue },
+      health: { total: totalHealth, average: avgHealth, distribution: healthBuckets },
+      status: statusCounts,
+      riskLevel,
+      description: `${rows.length} accounts analyzed. ${trend} ${avgHealth.toFixed(0)}% avg health. ${riskLevel === 'low' ? '✓ Clean' : `⚠ ${riskLevel.toUpperCase()}`}`,
+    };
+  }
+}

package/lib/cli-parser.ts

@@ -0,0 +1,197 @@
+/**
+ * NEO-ANALOG CLI PARSER
+ * 
+ * Tokenizes user input for data table filters with governance rules.
+ * Syntax: `key:value >operator <number status:active`
+ * 
+ * Example:
+ * - `status:active` → key="status", value="active"
+ * - `>100` → operator=">", value="100"
+ * - `error` → raw value="error"
+ */
+
+export interface FilterToken {
+  type: 'key' | 'operator' | 'value' | 'raw';
+  text: string;
+  start: number;
+  end: number;
+}
+
+export interface ParsedFilter {
+  tokens: FilterToken[];
+  hasKey: boolean;
+  hasOperator: boolean;
+  raw: string;
+}
+
+/**
+ * Parse search input into semantic tokens
+ * Supports: `key:value`, `><=`, `"quoted values"`, and raw words
+ */
+export function parseSearchInput(input: string): FilterToken[] {
+  const tokens: FilterToken[] = [];
+  
+  // Regex pattern:
+  // - ([a-zA-Z0-9_-]+:) = key with colon (e.g., "status:")
+  // - ([><=!]+) = operators (e.g., ">", "<=", "!=")
+  // - (".*?"|[^"\s]+) = quoted strings or unquoted words
+  // - (\s+) = whitespace (ignored)
+  const regex = /([a-zA-Z0-9_-]+:)|([><=!]+)|(".*?"|[^"\s]+)|(\s+)/g;
+  
+  let match;
+  while ((match = regex.exec(input)) !== null) {
+    const [fullMatch, key, operator, value, whitespace] = match;
+    const start = match.index;
+    const end = start + fullMatch.length;
+
+    if (whitespace) continue; // Skip pure whitespace
+
+    if (key) {
+      tokens.push({ type: 'key', text: key, start, end });
+    } else if (operator) {
+      tokens.push({ type: 'operator', text: operator, start, end });
+    } else if (value) {
+      // Remove quotes if present
+      const cleanValue = value.startsWith('"') && value.endsWith('"')
+        ? value.slice(1, -1)
+        : value;
+      tokens.push({ type: 'value', text: cleanValue, start, end });
+    } else {
+      tokens.push({ type: 'raw', text: fullMatch, start, end });
+    }
+  }
+
+  return tokens;
+}
+
+/**
+ * Advanced parser that returns structured filter object
+ */
+export function parseFilter(input: string): ParsedFilter {
+  const tokens = parseSearchInput(input);
+  const hasKey = tokens.some(t => t.type === 'key');
+  const hasOperator = tokens.some(t => t.type === 'operator');
+
+  return {
+    tokens,
+    hasKey,
+    hasOperator,
+    raw: input,
+  };
+}
+
+/**
+ * Generate HTML with syntax highlighting for display
+ * Uses Neo-Analog color scheme:
+ * - Keys (blue) = Data field names
+ * - Operators (amber) = Comparison symbols
+ * - Values (emerald) = Data values
+ * - Raw (gray) = Unrecognized tokens
+ */
+export function highlightCommand(input: string, colorScheme: 'neo-analog' | 'monochrome' = 'neo-analog'): string {
+  const tokens = parseSearchInput(input);
+  let html = '';
+
+  const colors = {
+    'neo-analog': {
+      key: 'text-blue-600 font-semibold',      // Keywords
+      operator: 'text-amber-600 font-bold',    // Operators
+      value: 'text-emerald-700',                // Values
+      raw: 'text-gray-600',                     // Unrecognized
+    },
+    'monochrome': {
+      key: 'text-gray-900 font-semibold',
+      operator: 'text-gray-900 font-bold',
+      value: 'text-gray-900',
+      raw: 'text-gray-600 italic',
+    },
+  };
+
+  const palette = colors[colorScheme];
+
+  tokens.forEach(t => {
+    const colorClass = palette[t.type];
+    html += `<span class="${colorClass}">${escapeHtml(t.text)}</span> `;
+  });
+
+  return html.trim();
+}
+
+/**
+ * Escape HTML special characters
+ */
+function escapeHtml(text: string): string {
+  const map: { [key: string]: string } = {
+    '&': '&amp;',
+    '<': '&lt;',
+    '>': '&gt;',
+    '"': '&quot;',
+    "'": '&#039;',
+  };
+  return text.replace(/[&<>"']/g, char => map[char]);
+}
+
+/**
+ * Extract semantic key-value pairs from parsed tokens
+ * Example: "status:active" → { status: "active" }
+ */
+export function extractKeyValues(tokens: FilterToken[]): Record<string, string[]> {
+  const result: Record<string, string[]> = {};
+
+  for (let i = 0; i < tokens.length; i++) {
+    const token = tokens[i];
+    if (token.type === 'key') {
+      const key = token.text.slice(0, -1); // Remove trailing ':'
+      const nextToken = tokens[i + 1];
+      const value = nextToken?.type === 'value' ? nextToken.text : '';
+      
+      if (!result[key]) result[key] = [];
+      if (value) result[key].push(value);
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Filter array of objects based on parsed CLI input
+ * @param data Array of objects to filter
+ * @param input CLI-style filter string
+ * @param keyMapping Map semantic keys to object properties
+ */
+export function filterData<T extends Record<string, any>>(
+  data: T[],
+  input: string,
+  keyMapping?: Record<string, string>
+): T[] {
+  const parsed = parseFilter(input);
+  const keyValues = extractKeyValues(parsed.tokens);
+
+  // If no structured keys, do simple text search
+  if (!parsed.hasKey) {
+    const searchTerms = parsed.tokens
+      .filter(t => t.type === 'value' || t.type === 'raw')
+      .map(t => t.text.toLowerCase());
+
+    return data.filter(item =>
+      Object.values(item).some(val =>
+        searchTerms.some(term =>
+          String(val).toLowerCase().includes(term)
+        )
+      )
+    );
+  }
+
+  // Filter by key-value pairs
+  return data.filter(item => {
+    for (const [key, values] of Object.entries(keyValues)) {
+      const propKey = keyMapping?.[key] ?? key;
+      const itemValue = String(item[propKey] ?? '').toLowerCase();
+
+      if (!values.some(v => itemValue.includes(v.toLowerCase()))) {
+        return false;
+      }
+    }
+    return true;
+  });
+}

package/lib/utils.ts

@@ -0,0 +1,18 @@
+import { type ClassValue, clsx } from "clsx"
+import { twMerge } from "tailwind-merge"
+
+/**
+ * Utility function to merge Tailwind CSS classes with design system classes
+ * Combines clsx for conditional classes and tailwind-merge for conflict resolution
+ * 
+ * @param inputs - Class values (strings, objects, arrays)
+ * @returns Merged class string
+ * 
+ * @example
+ * cn("na-btn", "na-btn-primary", isActive && "na-btn-active")
+ * cn("px-4", "py-2", className)
+ */
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs))
+}
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aibos-design-system",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Enterprise-grade design system with 254 tokens, 171 semantic classes, and Beast Mode patterns. Zero framework overhead, 100% Figma compliant.",
   "type": "module",
   "keywords": [
@@ -37,7 +37,9 @@
     "format:check": "prettier --check \"**/*.{css,js,ts,json,md}\"",
     "validate": "node scripts/validate-design-tokens.js",
     "validate:all": "pnpm lint && pnpm validate && pnpm enforce:semantics",
-    "quality": "pnpm validate:all"
+    "quality": "pnpm validate:all",
+    "prepublishOnly": "pnpm build",
+    "prepare": "pnpm build"
   },
   "main": "./style.css",
   "exports": {
@@ -50,9 +52,14 @@
     "style.css",
     "input.css",
     "dist/**/*",
+    "lib/**/*.ts",
+    "lib/**/*.js",
     "README.md",
-    "API_REFERENCE.md",
-    "EXTERNAL_USAGE.md"
+    "docs/API_REFERENCE.md",
+    "docs/EXTERNAL_USAGE.md",
+    "docs/QUICK_REFERENCE.md",
+    "docs/INTEGRATION_GUIDE.md",
+    "LICENSE"
   ],
   "devDependencies": {
     "@tailwindcss/postcss": "^4.1.18",