@portel/photon-core 2.3.0 → 2.5.0

package/src/ui-types/Form.ts

@@ -0,0 +1,363 @@
+/**
+ * Form - Purpose-driven type for interactive forms
+ *
+ * Automatically renders as a form that submits back to the photon.
+ * Unlike io.ask.form (which is for elicitation during method execution),
+ * Form is a return type that creates a persistent interactive form.
+ *
+ * @example
+ * ```typescript
+ * async settings() {
+ *   return new Form()
+ *     .title('User Settings')
+ *     .text('name', 'Display Name', { required: true })
+ *     .email('email', 'Email Address')
+ *     .select('theme', 'Theme', ['light', 'dark', 'auto'])
+ *     .toggle('notifications', 'Enable Notifications')
+ *     .submit('Save Settings', 'saveSettings');
+ * }
+ *
+ * async saveSettings(params: { name: string; email: string; theme: string; notifications: boolean }) {
+ *   // Handle form submission
+ *   return { success: true };
+ * }
+ * ```
+ */
+
+import { PhotonUIType } from './base.js';
+
+export type FieldType =
+  | 'text'
+  | 'email'
+  | 'password'
+  | 'number'
+  | 'textarea'
+  | 'select'
+  | 'multiselect'
+  | 'toggle'
+  | 'checkbox'
+  | 'radio'
+  | 'date'
+  | 'time'
+  | 'datetime'
+  | 'file'
+  | 'color'
+  | 'range'
+  | 'hidden';
+
+export interface FormField {
+  name: string;
+  type: FieldType;
+  label?: string;
+  placeholder?: string;
+  defaultValue?: any;
+  required?: boolean;
+  disabled?: boolean;
+  options?: Array<string | { label: string; value: any }>;
+  min?: number;
+  max?: number;
+  step?: number;
+  rows?: number;
+  accept?: string; // For file inputs
+  pattern?: string;
+  helpText?: string;
+  group?: string; // For grouping fields
+}
+
+export interface FormOptions {
+  title?: string;
+  description?: string;
+  submitLabel?: string;
+  submitMethod?: string; // Photon method to call on submit
+  cancelLabel?: string;
+  layout?: 'vertical' | 'horizontal' | 'inline';
+  columns?: 1 | 2 | 3;
+  showReset?: boolean;
+  confirmSubmit?: string; // Confirmation message before submit
+}
+
+export class Form extends PhotonUIType {
+  readonly _photonType = 'form' as const;
+
+  private _fields: FormField[] = [];
+  private _options: FormOptions = {
+    layout: 'vertical',
+    columns: 1,
+    submitLabel: 'Submit',
+  };
+
+  /**
+   * Create a new Form
+   */
+  constructor() {
+    super();
+  }
+
+  /**
+   * Set form title
+   */
+  title(title: string): this {
+    this._options.title = title;
+    return this;
+  }
+
+  /**
+   * Set form description
+   */
+  description(text: string): this {
+    this._options.description = text;
+    return this;
+  }
+
+  /**
+   * Add a generic field
+   */
+  field(name: string, type: FieldType, label?: string, options?: Partial<FormField>): this {
+    this._fields.push({
+      name,
+      type,
+      label: label ?? this._formatLabel(name),
+      ...options,
+    });
+    return this;
+  }
+
+  /**
+   * Add a text input
+   */
+  text(name: string, label?: string, options?: Partial<FormField>): this {
+    return this.field(name, 'text', label, options);
+  }
+
+  /**
+   * Add an email input
+   */
+  email(name: string, label?: string, options?: Partial<FormField>): this {
+    return this.field(name, 'email', label, options);
+  }
+
+  /**
+   * Add a password input
+   */
+  password(name: string, label?: string, options?: Partial<FormField>): this {
+    return this.field(name, 'password', label, options);
+  }
+
+  /**
+   * Add a number input
+   */
+  number(name: string, label?: string, options?: Partial<FormField> & { min?: number; max?: number; step?: number }): this {
+    return this.field(name, 'number', label, options);
+  }
+
+  /**
+   * Add a textarea
+   */
+  textarea(name: string, label?: string, options?: Partial<FormField> & { rows?: number }): this {
+    return this.field(name, 'textarea', label, { rows: 4, ...options });
+  }
+
+  /**
+   * Add a select dropdown
+   */
+  select(name: string, label: string | undefined, choices: Array<string | { label: string; value: any }>, options?: Partial<FormField>): this {
+    return this.field(name, 'select', label, { options: choices, ...options });
+  }
+
+  /**
+   * Add a multi-select
+   */
+  multiselect(name: string, label: string | undefined, choices: Array<string | { label: string; value: any }>, options?: Partial<FormField>): this {
+    return this.field(name, 'multiselect', label, { options: choices, ...options });
+  }
+
+  /**
+   * Add a toggle switch
+   */
+  toggle(name: string, label?: string, options?: Partial<FormField>): this {
+    return this.field(name, 'toggle', label, options);
+  }
+
+  /**
+   * Add a checkbox
+   */
+  checkbox(name: string, label?: string, options?: Partial<FormField>): this {
+    return this.field(name, 'checkbox', label, options);
+  }
+
+  /**
+   * Add radio buttons
+   */
+  radio(name: string, label: string | undefined, choices: Array<string | { label: string; value: any }>, options?: Partial<FormField>): this {
+    return this.field(name, 'radio', label, { options: choices, ...options });
+  }
+
+  /**
+   * Add a date picker
+   */
+  date(name: string, label?: string, options?: Partial<FormField>): this {
+    return this.field(name, 'date', label, options);
+  }
+
+  /**
+   * Add a time picker
+   */
+  time(name: string, label?: string, options?: Partial<FormField>): this {
+    return this.field(name, 'time', label, options);
+  }
+
+  /**
+   * Add a datetime picker
+   */
+  datetime(name: string, label?: string, options?: Partial<FormField>): this {
+    return this.field(name, 'datetime', label, options);
+  }
+
+  /**
+   * Add a file upload
+   */
+  file(name: string, label?: string, options?: Partial<FormField> & { accept?: string }): this {
+    return this.field(name, 'file', label, options);
+  }
+
+  /**
+   * Add a color picker
+   */
+  color(name: string, label?: string, options?: Partial<FormField>): this {
+    return this.field(name, 'color', label, options);
+  }
+
+  /**
+   * Add a range slider
+   */
+  range(name: string, label?: string, options?: Partial<FormField> & { min?: number; max?: number; step?: number }): this {
+    return this.field(name, 'range', label, { min: 0, max: 100, step: 1, ...options });
+  }
+
+  /**
+   * Add a hidden field
+   */
+  hidden(name: string, value: any): this {
+    return this.field(name, 'hidden', undefined, { defaultValue: value });
+  }
+
+  /**
+   * Configure submit button
+   */
+  submit(label: string, method?: string): this {
+    this._options.submitLabel = label;
+    if (method) this._options.submitMethod = method;
+    return this;
+  }
+
+  /**
+   * Add cancel button
+   */
+  cancel(label: string = 'Cancel'): this {
+    this._options.cancelLabel = label;
+    return this;
+  }
+
+  /**
+   * Set form layout
+   */
+  layout(type: 'vertical' | 'horizontal' | 'inline'): this {
+    this._options.layout = type;
+    return this;
+  }
+
+  /**
+   * Set number of columns
+   */
+  columns(count: 1 | 2 | 3): this {
+    this._options.columns = count;
+    return this;
+  }
+
+  /**
+   * Show reset button
+   */
+  showReset(enabled: boolean = true): this {
+    this._options.showReset = enabled;
+    return this;
+  }
+
+  /**
+   * Require confirmation before submit
+   */
+  confirmSubmit(message: string): this {
+    this._options.confirmSubmit = message;
+    return this;
+  }
+
+  /**
+   * Group subsequent fields
+   */
+  group(name: string): this {
+    // Mark for next fields
+    // Implementation note: fields added after this call get this group
+    return this;
+  }
+
+  /**
+   * Format field name to label
+   */
+  private _formatLabel(name: string): string {
+    return name
+      .replace(/([A-Z])/g, ' $1')
+      .replace(/[_-]/g, ' ')
+      .replace(/^\w/, c => c.toUpperCase())
+      .trim();
+  }
+
+  toJSON() {
+    return {
+      _photonType: this._photonType,
+      fields: this._fields,
+      options: this._options,
+    };
+  }
+
+  /**
+   * Render as plain text for MCP clients
+   * Shows the form structure (fields are not interactive in plain text)
+   */
+  toString(): string {
+    const lines: string[] = [];
+
+    if (this._options.title) {
+      lines.push(`## ${this._options.title}`);
+    }
+    if (this._options.description) {
+      lines.push(this._options.description);
+    }
+    if (this._options.title || this._options.description) {
+      lines.push('');
+    }
+
+    lines.push('**Form Fields:**');
+    for (const field of this._fields) {
+      if (field.type === 'hidden') continue;
+
+      let line = `- ${field.label ?? field.name}`;
+      if (field.required) line += ' (required)';
+
+      // Show options for select/radio
+      if (field.options && field.options.length > 0) {
+        const opts = field.options.map(o => typeof o === 'string' ? o : o.label);
+        line += `: [${opts.join(', ')}]`;
+      } else {
+        line += `: (${field.type})`;
+      }
+
+      if (field.helpText) line += ` - ${field.helpText}`;
+      lines.push(line);
+    }
+
+    if (this._options.submitLabel) {
+      lines.push('', `[${this._options.submitLabel}]`);
+    }
+
+    return lines.join('\n');
+  }
+}

package/src/ui-types/Progress.ts

@@ -0,0 +1,237 @@
+/**
+ * Progress - Purpose-driven type for progress indicators
+ *
+ * Automatically renders as progress bars or steps.
+ *
+ * @example
+ * ```typescript
+ * // Simple progress bar
+ * async uploadStatus() {
+ *   return new Progress(75)
+ *     .label('Uploading files...')
+ *     .color('blue');
+ * }
+ *
+ * // Multiple progress bars
+ * async projectStatus() {
+ *   return new Progress()
+ *     .bar('Design', 100, { color: 'green' })
+ *     .bar('Development', 65, { color: 'blue' })
+ *     .bar('Testing', 20, { color: 'yellow' });
+ * }
+ *
+ * // Step indicator
+ * async checkoutSteps() {
+ *   return new Progress('steps')
+ *     .step('Cart', 'completed')
+ *     .step('Shipping', 'current')
+ *     .step('Payment', 'pending')
+ *     .step('Confirm', 'pending');
+ * }
+ * ```
+ */
+
+import { PhotonUIType } from './base.js';
+
+export type ProgressStyle = 'bar' | 'steps' | 'circle';
+export type StepStatus = 'pending' | 'current' | 'completed' | 'error';
+
+export interface ProgressBar {
+  label: string;
+  value: number;
+  max?: number;
+  color?: string;
+  showValue?: boolean;
+}
+
+export interface ProgressStep {
+  label: string;
+  status: StepStatus;
+  description?: string;
+  icon?: string;
+}
+
+export interface ProgressOptions {
+  title?: string;
+  style?: ProgressStyle;
+  color?: string;
+  size?: 'sm' | 'md' | 'lg';
+  striped?: boolean;
+  animated?: boolean;
+  showValue?: boolean;
+}
+
+export class Progress extends PhotonUIType {
+  readonly _photonType = 'progress' as const;
+
+  private _bars: ProgressBar[] = [];
+  private _steps: ProgressStep[] = [];
+  private _value: number = 0;
+  private _max: number = 100;
+  private _options: ProgressOptions = {
+    style: 'bar',
+    size: 'md',
+    showValue: true,
+    animated: true,
+  };
+
+  /**
+   * Create a new Progress indicator
+   * @param valueOrStyle Initial value (0-100) or style ('steps', 'circle')
+   */
+  constructor(valueOrStyle?: number | ProgressStyle) {
+    super();
+    if (typeof valueOrStyle === 'number') {
+      this._value = valueOrStyle;
+    } else if (valueOrStyle) {
+      this._options.style = valueOrStyle;
+    }
+  }
+
+  /**
+   * Set progress value (0-100)
+   */
+  value(val: number, max?: number): this {
+    this._value = val;
+    if (max !== undefined) this._max = max;
+    return this;
+  }
+
+  /**
+   * Set label
+   */
+  label(text: string): this {
+    this._options.title = text;
+    return this;
+  }
+
+  /**
+   * Add a progress bar (for multi-bar display)
+   */
+  bar(label: string, value: number, options?: { max?: number; color?: string; showValue?: boolean }): this {
+    this._bars.push({
+      label,
+      value,
+      max: options?.max ?? 100,
+      color: options?.color,
+      showValue: options?.showValue ?? true,
+    });
+    return this;
+  }
+
+  /**
+   * Add a step (for step indicator)
+   */
+  step(label: string, status: StepStatus = 'pending', options?: { description?: string; icon?: string }): this {
+    this._options.style = 'steps';
+    this._steps.push({
+      label,
+      status,
+      ...options,
+    });
+    return this;
+  }
+
+  /**
+   * Set color
+   */
+  color(color: string): this {
+    this._options.color = color;
+    return this;
+  }
+
+  /**
+   * Set size
+   */
+  size(size: 'sm' | 'md' | 'lg'): this {
+    this._options.size = size;
+    return this;
+  }
+
+  /**
+   * Use striped style
+   */
+  striped(enabled: boolean = true): this {
+    this._options.striped = enabled;
+    return this;
+  }
+
+  /**
+   * Enable animation
+   */
+  animated(enabled: boolean = true): this {
+    this._options.animated = enabled;
+    return this;
+  }
+
+  /**
+   * Show/hide value text
+   */
+  showValue(enabled: boolean = true): this {
+    this._options.showValue = enabled;
+    return this;
+  }
+
+  /**
+   * Use circle style
+   */
+  circle(): this {
+    this._options.style = 'circle';
+    return this;
+  }
+
+  toJSON() {
+    return {
+      _photonType: this._photonType,
+      value: this._value,
+      max: this._max,
+      bars: this._bars,
+      steps: this._steps,
+      options: this._options,
+    };
+  }
+
+  /**
+   * Render as plain text for MCP clients
+   */
+  toString(): string {
+    const lines: string[] = [];
+
+    if (this._options.title) {
+      lines.push(this._options.title);
+    }
+
+    // Steps display
+    if (this._steps.length > 0) {
+      const stepMarkers = this._steps.map(s => {
+        switch (s.status) {
+          case 'completed': return `[✓] ${s.label}`;
+          case 'current': return `[●] ${s.label}`;
+          case 'error': return `[✗] ${s.label}`;
+          default: return `[ ] ${s.label}`;
+        }
+      });
+      lines.push(stepMarkers.join(' → '));
+      return lines.join('\n');
+    }
+
+    // Multiple bars
+    if (this._bars.length > 0) {
+      for (const bar of this._bars) {
+        const pct = Math.round((bar.value / (bar.max ?? 100)) * 100);
+        const filled = Math.round(pct / 5);
+        const barStr = '█'.repeat(filled) + '░'.repeat(20 - filled);
+        lines.push(`${bar.label}: [${barStr}] ${pct}%`);
+      }
+      return lines.join('\n');
+    }
+
+    // Single progress bar
+    const pct = Math.round((this._value / this._max) * 100);
+    const filled = Math.round(pct / 5);
+    const barStr = '█'.repeat(filled) + '░'.repeat(20 - filled);
+    lines.push(`[${barStr}] ${pct}%`);
+
+    return lines.join('\n');
+  }
+}