@portel/photon-core 2.3.0 → 2.5.0

package/src/ui-types/Cards.ts

@@ -0,0 +1,286 @@
+/**
+ * Cards - Purpose-driven type for card-based layouts
+ *
+ * Automatically renders as a grid of cards with customizable fields.
+ *
+ * @example
+ * ```typescript
+ * async products() {
+ *   return new Cards()
+ *     .title('Featured Products')
+ *     .image('imageUrl')
+ *     .heading('name')
+ *     .subtitle('category')
+ *     .description('summary')
+ *     .badge('status')
+ *     .items([
+ *       { name: 'Widget', category: 'Tools', summary: '...', status: 'New', imageUrl: '...' },
+ *     ]);
+ * }
+ * ```
+ */
+
+import { PhotonUIType } from './base.js';
+
+export interface CardFieldMapping {
+  image?: string;
+  heading?: string;
+  subtitle?: string;
+  description?: string;
+  badge?: string;
+  footer?: string;
+  link?: string;
+  meta?: string[];
+}
+
+export interface CardsOptions {
+  title?: string;
+  columns?: 1 | 2 | 3 | 4 | 6;
+  compact?: boolean;
+  clickable?: boolean;
+  hoverable?: boolean;
+  bordered?: boolean;
+  aspectRatio?: 'square' | 'video' | 'portrait' | 'auto';
+}
+
+export class Cards extends PhotonUIType {
+  readonly _photonType = 'cards' as const;
+
+  private _items: Record<string, any>[] = [];
+  private _fields: CardFieldMapping = {};
+  private _options: CardsOptions = {
+    columns: 3,
+    hoverable: true,
+    bordered: true,
+    aspectRatio: 'auto',
+  };
+
+  /**
+   * Create a new Cards layout
+   * @param items Optional initial items
+   */
+  constructor(items?: Record<string, any>[]) {
+    super();
+    if (items) {
+      this._items = items;
+      this._inferFields(items[0]);
+    }
+  }
+
+  /**
+   * Set section title
+   */
+  title(title: string): this {
+    this._options.title = title;
+    return this;
+  }
+
+  /**
+   * Set field for card image
+   */
+  image(field: string): this {
+    this._fields.image = field;
+    return this;
+  }
+
+  /**
+   * Set field for card heading
+   */
+  heading(field: string): this {
+    this._fields.heading = field;
+    return this;
+  }
+
+  /**
+   * Set field for card subtitle
+   */
+  subtitle(field: string): this {
+    this._fields.subtitle = field;
+    return this;
+  }
+
+  /**
+   * Set field for card description
+   */
+  description(field: string): this {
+    this._fields.description = field;
+    return this;
+  }
+
+  /**
+   * Set field for badge/tag
+   */
+  badge(field: string): this {
+    this._fields.badge = field;
+    return this;
+  }
+
+  /**
+   * Set field for footer text
+   */
+  footer(field: string): this {
+    this._fields.footer = field;
+    return this;
+  }
+
+  /**
+   * Set field for click link
+   */
+  link(field: string): this {
+    this._fields.link = field;
+    this._options.clickable = true;
+    return this;
+  }
+
+  /**
+   * Set fields for meta info
+   */
+  meta(...fields: string[]): this {
+    this._fields.meta = fields;
+    return this;
+  }
+
+  /**
+   * Set card items
+   */
+  items(data: Record<string, any>[]): this {
+    this._items = data;
+    if (Object.keys(this._fields).length === 0 && data.length > 0) {
+      this._inferFields(data[0]);
+    }
+    return this;
+  }
+
+  /**
+   * Add a single item
+   */
+  item(data: Record<string, any>): this {
+    this._items.push(data);
+    return this;
+  }
+
+  /**
+   * Set number of columns
+   */
+  columns(count: 1 | 2 | 3 | 4 | 6): this {
+    this._options.columns = count;
+    return this;
+  }
+
+  /**
+   * Use compact card style
+   */
+  compact(enabled: boolean = true): this {
+    this._options.compact = enabled;
+    return this;
+  }
+
+  /**
+   * Enable click interaction
+   */
+  clickable(enabled: boolean = true): this {
+    this._options.clickable = enabled;
+    return this;
+  }
+
+  /**
+   * Enable hover effect
+   */
+  hoverable(enabled: boolean = true): this {
+    this._options.hoverable = enabled;
+    return this;
+  }
+
+  /**
+   * Show card borders
+   */
+  bordered(enabled: boolean = true): this {
+    this._options.bordered = enabled;
+    return this;
+  }
+
+  /**
+   * Set image aspect ratio
+   */
+  aspectRatio(ratio: 'square' | 'video' | 'portrait' | 'auto'): this {
+    this._options.aspectRatio = ratio;
+    return this;
+  }
+
+  /**
+   * Infer field mappings from data
+   */
+  private _inferFields(item: Record<string, any>): void {
+    const keys = Object.keys(item);
+
+    // Look for common field names
+    const findField = (patterns: string[]): string | undefined => {
+      return keys.find(k => patterns.some(p => k.toLowerCase().includes(p)));
+    };
+
+    this._fields.image = findField(['image', 'img', 'photo', 'picture', 'avatar', 'thumbnail']);
+    this._fields.heading = findField(['name', 'title', 'heading']);
+    this._fields.subtitle = findField(['subtitle', 'category', 'type']);
+    this._fields.description = findField(['description', 'summary', 'text', 'body', 'content']);
+    this._fields.badge = findField(['status', 'badge', 'tag', 'label']);
+    this._fields.link = findField(['url', 'link', 'href']);
+  }
+
+  /**
+   * Get item count
+   */
+  get length(): number {
+    return this._items.length;
+  }
+
+  toJSON() {
+    return {
+      _photonType: this._photonType,
+      items: this._items,
+      fields: this._fields,
+      options: this._options,
+    };
+  }
+
+  /**
+   * Render as plain text for MCP clients
+   */
+  toString(): string {
+    const lines: string[] = [];
+
+    if (this._options.title) {
+      lines.push(`## ${this._options.title}`, '');
+    }
+
+    if (this._items.length === 0) {
+      lines.push('(No items)');
+      return lines.join('\n');
+    }
+
+    for (const item of this._items) {
+      // Heading
+      const heading = this._fields.heading ? item[this._fields.heading] : null;
+      if (heading) lines.push(`### ${heading}`);
+
+      // Subtitle
+      const subtitle = this._fields.subtitle ? item[this._fields.subtitle] : null;
+      if (subtitle) lines.push(`*${subtitle}*`);
+
+      // Badge
+      const badge = this._fields.badge ? item[this._fields.badge] : null;
+      if (badge) lines.push(`[${badge}]`);
+
+      // Description
+      const desc = this._fields.description ? item[this._fields.description] : null;
+      if (desc) lines.push('', desc);
+
+      // Link
+      const link = this._fields.link ? item[this._fields.link] : null;
+      if (link) lines.push('', `Link: ${link}`);
+
+      lines.push('');
+    }
+
+    return lines.join('\n').trim();
+  }
+}

package/src/ui-types/Chart.ts

@@ -0,0 +1,239 @@
+/**
+ * Chart - Purpose-driven type for data visualization
+ *
+ * Automatically renders as a chart with the specified type.
+ *
+ * @example
+ * ```typescript
+ * async revenue() {
+ *   return new Chart('line')
+ *     .title('Monthly Revenue')
+ *     .labels(['Jan', 'Feb', 'Mar', 'Apr'])
+ *     .series('Revenue', [1000, 1500, 1200, 1800])
+ *     .series('Costs', [800, 900, 850, 950]);
+ * }
+ *
+ * async distribution() {
+ *   return new Chart('pie')
+ *     .title('User Distribution')
+ *     .data([
+ *       { label: 'Free', value: 1000 },
+ *       { label: 'Pro', value: 500 },
+ *       { label: 'Enterprise', value: 100 },
+ *     ]);
+ * }
+ * ```
+ */
+
+import { PhotonUIType } from './base.js';
+
+export type ChartType = 'line' | 'bar' | 'pie' | 'doughnut' | 'area' | 'scatter' | 'radar';
+
+export interface ChartSeries {
+  name: string;
+  data: number[];
+  color?: string;
+}
+
+export interface ChartDataPoint {
+  label: string;
+  value: number;
+  color?: string;
+}
+
+export interface ChartOptions {
+  title?: string;
+  subtitle?: string;
+  legend?: boolean | 'top' | 'bottom' | 'left' | 'right';
+  stacked?: boolean;
+  showGrid?: boolean;
+  showValues?: boolean;
+  animate?: boolean;
+  height?: number;
+  colors?: string[];
+  xAxisLabel?: string;
+  yAxisLabel?: string;
+}
+
+export class Chart extends PhotonUIType {
+  readonly _photonType = 'chart' as const;
+
+  private _type: ChartType;
+  private _labels: string[] = [];
+  private _series: ChartSeries[] = [];
+  private _data: ChartDataPoint[] = []; // For pie/doughnut
+  private _options: ChartOptions = {
+    legend: true,
+    showGrid: true,
+    animate: true,
+  };
+
+  /**
+   * Create a new Chart
+   * @param type Chart type (line, bar, pie, etc.)
+   */
+  constructor(type: ChartType = 'line') {
+    super();
+    this._type = type;
+  }
+
+  /**
+   * Set chart title
+   */
+  title(title: string): this {
+    this._options.title = title;
+    return this;
+  }
+
+  /**
+   * Set chart subtitle
+   */
+  subtitle(subtitle: string): this {
+    this._options.subtitle = subtitle;
+    return this;
+  }
+
+  /**
+   * Set X-axis labels (for line, bar, area charts)
+   */
+  labels(labels: string[]): this {
+    this._labels = labels;
+    return this;
+  }
+
+  /**
+   * Add a data series (for line, bar, area charts)
+   */
+  series(name: string, data: number[], color?: string): this {
+    this._series.push({ name, data, color });
+    return this;
+  }
+
+  /**
+   * Set pie/doughnut data points
+   */
+  data(points: ChartDataPoint[] | Array<{ label: string; value: number }>): this {
+    this._data = points;
+    return this;
+  }
+
+  /**
+   * Configure legend
+   */
+  legend(position: boolean | 'top' | 'bottom' | 'left' | 'right' = true): this {
+    this._options.legend = position;
+    return this;
+  }
+
+  /**
+   * Enable stacked mode (for bar/area charts)
+   */
+  stacked(enabled: boolean = true): this {
+    this._options.stacked = enabled;
+    return this;
+  }
+
+  /**
+   * Show/hide grid lines
+   */
+  grid(enabled: boolean = true): this {
+    this._options.showGrid = enabled;
+    return this;
+  }
+
+  /**
+   * Show values on chart
+   */
+  showValues(enabled: boolean = true): this {
+    this._options.showValues = enabled;
+    return this;
+  }
+
+  /**
+   * Enable/disable animations
+   */
+  animate(enabled: boolean = true): this {
+    this._options.animate = enabled;
+    return this;
+  }
+
+  /**
+   * Set chart height
+   */
+  height(pixels: number): this {
+    this._options.height = pixels;
+    return this;
+  }
+
+  /**
+   * Set color palette
+   */
+  colors(colors: string[]): this {
+    this._options.colors = colors;
+    return this;
+  }
+
+  /**
+   * Set X-axis label
+   */
+  xAxis(label: string): this {
+    this._options.xAxisLabel = label;
+    return this;
+  }
+
+  /**
+   * Set Y-axis label
+   */
+  yAxis(label: string): this {
+    this._options.yAxisLabel = label;
+    return this;
+  }
+
+  toJSON() {
+    return {
+      _photonType: this._photonType,
+      chartType: this._type,
+      labels: this._labels,
+      series: this._series,
+      data: this._data,
+      options: this._options,
+    };
+  }
+
+  /**
+   * Render as plain text for MCP clients
+   */
+  toString(): string {
+    const lines: string[] = [];
+
+    if (this._options.title) {
+      lines.push(`## ${this._options.title}`);
+      if (this._options.subtitle) lines.push(this._options.subtitle);
+      lines.push('');
+    }
+
+    // Pie/doughnut: show as list
+    if ((this._type === 'pie' || this._type === 'doughnut') && this._data.length > 0) {
+      const total = this._data.reduce((sum, d) => sum + d.value, 0);
+      for (const d of this._data) {
+        const pct = total > 0 ? ((d.value / total) * 100).toFixed(1) : '0';
+        lines.push(`- ${d.label}: ${d.value} (${pct}%)`);
+      }
+      return lines.join('\n');
+    }
+
+    // Series charts: show as table
+    if (this._series.length > 0 && this._labels.length > 0) {
+      const headers = ['', ...this._series.map(s => s.name)];
+      lines.push('| ' + headers.join(' | ') + ' |');
+      lines.push('| ' + headers.map(() => '---').join(' | ') + ' |');
+
+      for (let i = 0; i < this._labels.length; i++) {
+        const row = [this._labels[i], ...this._series.map(s => String(s.data[i] ?? ''))];
+        lines.push('| ' + row.join(' | ') + ' |');
+      }
+    }
+
+    return lines.join('\n');
+  }
+}