formshell 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,615 @@
+/**
+ * Base class for all field types
+ */
+export declare class BaseField {
+    readonly type: FieldType;
+    id: string;
+    label: string;
+    required: boolean;
+    value: FieldValue;
+    error: string | null;
+    condition?: (formData: FormData_2) => boolean;
+    constructor(config: FieldConfig);
+    /**
+     * Validate the field (to be overridden in subclasses)
+     */
+    validate(value: FieldValue): ValidationResult;
+    /**
+     * Format the value for display
+     */
+    format(value: FieldValue): string;
+    /**
+     * Get the current value
+     */
+    getValue(): FieldValue;
+    /**
+     * Set the value
+     */
+    setValue(value: FieldValue): boolean;
+}
+
+export declare interface BaseFieldConfig {
+    id: string;
+    type: FieldType;
+    label: string;
+    description?: string;
+    required?: boolean;
+    defaultValue?: string | number | boolean | null;
+    condition?: (formData: FormData_2) => boolean;
+}
+
+declare interface BoxCharacters {
+    topLeft: string;
+    topRight: string;
+    bottomLeft: string;
+    bottomRight: string;
+    horizontal: string;
+    vertical: string;
+    doubleTopLeft: string;
+    doubleTopRight: string;
+    doubleBottomLeft: string;
+    doubleBottomRight: string;
+    doubleHorizontal: string;
+    doubleVertical: string;
+    filled: string;
+    empty: string;
+    halfFilled: string;
+    shadow: string[];
+    fade: string[];
+}
+
+/**
+ * Single choice field
+ */
+export declare class ChoiceField extends BaseField {
+    options: Array<string | {
+        value: string;
+        label: string;
+    }>;
+    constructor(config: ChoiceFieldConfig | FieldConfig);
+    validate(value: FieldValue): ValidationResult;
+    setValue(value: FieldValue): boolean;
+    format(value: FieldValue): string;
+}
+
+export declare interface ChoiceFieldConfig extends BaseFieldConfig {
+    type: 'choice';
+    options: string[] | Array<{
+        value: string;
+        label: string;
+    }>;
+}
+
+/**
+ * FormShell Theme - Elegant Design System
+ * Color palette, Unicode icons, box styles for elegant console rendering
+ */
+declare interface ColorPalette {
+    primary: string;
+    secondary: string;
+    accent: string;
+    success: string;
+    error: string;
+    warning: string;
+    info: string;
+    text: {
+        primary: string;
+        secondary: string;
+        muted: string;
+        dark: string;
+    };
+    background: {
+        main: string;
+        secondary: string;
+        accent: string;
+    };
+}
+
+/**
+ * Date field (format DD/MM/YYYY)
+ */
+export declare class DateField extends TextField {
+    constructor(config: FieldConfig);
+    validate(value: FieldValue): ValidationResult;
+}
+
+export declare interface DateFieldConfig extends BaseFieldConfig {
+    type: 'date';
+}
+
+/**
+ * Email field
+ */
+export declare class EmailField extends TextField {
+    constructor(config: FieldConfig);
+    validate(value: FieldValue): ValidationResult;
+}
+
+export declare interface EmailFieldConfig extends BaseFieldConfig {
+    type: 'email';
+    minLength?: number;
+    maxLength?: number;
+}
+
+export declare type FieldConfig = TextFieldConfig | NumberFieldConfig | EmailFieldConfig | URLFieldConfig | DateFieldConfig | ChoiceFieldConfig | MultipleChoiceFieldConfig | RatingFieldConfig | YesNoFieldConfig;
+
+/**
+ * Factory to create fields from type
+ */
+export declare const FieldFactory: {
+    create(config: FieldConfig): BaseField;
+};
+
+export declare interface FieldInstance {
+    readonly type: FieldType;
+    id: string;
+    label: string;
+    required: boolean;
+    value: FieldValue;
+    error: string | null;
+    condition?: (formData: FormData_2) => boolean;
+    validate(value: FieldValue): ValidationResult;
+    format(value: FieldValue): string;
+    getValue(): FieldValue;
+    setValue(value: FieldValue): boolean;
+}
+
+/**
+ * Core TypeScript types for FormShell
+ */
+export declare type FieldType = 'text' | 'number' | 'email' | 'url' | 'date' | 'choice' | 'multiple-choice' | 'rating' | 'yesno';
+
+export declare type FieldValue = string | number | boolean | string[] | null;
+
+declare interface FormatFunctions {
+    title: (text: string) => [string, string];
+    subtitle: (text: string) => [string, string];
+    body: (text: string) => [string, string];
+    success: (text: string) => [string, string];
+    error: (text: string) => [string, string];
+    muted: (text: string) => [string, string];
+    highlight: (text: string) => [string, string];
+    colored: (text: string, color: string) => [string, string];
+}
+
+export declare interface FormConfig {
+    title: string;
+    subtitle?: string;
+    endpoint?: string;
+    steps: FieldConfig[];
+    onComplete?: (data: FormData_2) => void | Promise<void>;
+}
+
+declare interface FormData_2 {
+    [fieldId: string]: FieldValue;
+}
+export { FormData_2 as FormData }
+
+declare class FormShell {
+    title: string;
+    subtitle: string | null;
+    endpoint: string | null;
+    onComplete: ((data: FormData_2) => void | Promise<void>) | null;
+    steps: Step[];
+    private currentStepIndex;
+    private renderer;
+    private started;
+    private completed;
+    private startTime;
+    private helpActive;
+    constructor(config: FormConfig);
+    /**
+     * Initialize steps with appropriate field types
+     */
+    private initializeSteps;
+    /**
+     * Show welcome screen
+     */
+    private showWelcome;
+    /**
+     * Show help screen with commands.
+     * Can be called at any time without interrupting the form flow.
+     * Use formShell.continue() to resume where you left off.
+     */
+    help(): void;
+    /**
+     * Start the form (only from welcome screen)
+     */
+    start(): void;
+    /**
+     * Resume the form after viewing help
+     */
+    continue(): void;
+    /**
+     * Check if a step should be shown based on its condition
+     */
+    private shouldShowStep;
+    /**
+     * Get next visible step index
+     */
+    private getNextVisibleStep;
+    /**
+     * Get previous visible step index
+     */
+    private getPreviousVisibleStep;
+    /**
+     * Advance to next step (internal method)
+     */
+    private _advanceStep;
+    /**
+     * Go back to previous step
+     */
+    back(): void;
+    /**
+     * Answer the current question
+     */
+    answer(value: string | number): void;
+    /**
+     * Shortcut to answer "Yes"
+     */
+    y(): void;
+    /**
+     * Shortcut to answer "No"
+     */
+    n(): void;
+    /**
+     * Skip the current question (only if not required)
+     */
+    skip(): void;
+    /**
+     * Reset the form
+     */
+    reset(): void;
+    /**
+     * Submit data to server
+     */
+    submit(): Promise<void>;
+    /**
+     * Collect all form data
+     */
+    private collectData;
+    /**
+     * Calculate completion percentage
+     */
+    getProgress(): ProgressInfo;
+    /**
+     * Estimate remaining time
+     */
+    getEstimatedTime(): string | null;
+    /**
+     * Render the current step
+     */
+    private renderCurrentStep;
+    /**
+     * Get the visible step number (position among visible steps)
+     */
+    private getVisibleStepNumber;
+    /**
+     * Render a field based on its type
+     */
+    private renderField;
+    /**
+     * Get a placeholder for the field
+     */
+    private getPlaceholder;
+    /**
+     * Show final summary
+     */
+    private showSummary;
+    /**
+     * Cleanup when form is destroyed
+     */
+    destroy(): void;
+}
+export { FormShell }
+export default FormShell;
+
+declare interface Icons {
+    checkmark: string;
+    cross: string;
+    star: string;
+    starEmpty: string;
+    arrow: string;
+    bullet: string;
+    bulletEmpty: string;
+    chevron: string;
+    heart: string;
+    info: string;
+    warning: string;
+    question: string;
+    cursor: string;
+    cursorBlink: string;
+    spinner: string[];
+}
+
+/**
+ * Multiple choice field
+ */
+export declare class MultipleChoiceField extends BaseField {
+    options: Array<string | {
+        value: string;
+        label: string;
+    }>;
+    minChoices: number;
+    maxChoices: number;
+    constructor(config: MultipleChoiceFieldConfig | FieldConfig);
+    validate(value: FieldValue): ValidationResult;
+    setValue(value: FieldValue): boolean;
+    format(value: FieldValue): string;
+}
+
+export declare interface MultipleChoiceFieldConfig extends BaseFieldConfig {
+    type: 'multiple-choice';
+    options: string[] | Array<{
+        value: string;
+        label: string;
+    }>;
+    minChoices?: number;
+    maxChoices?: number;
+}
+
+/**
+ * Numeric field
+ */
+export declare class NumberField extends BaseField {
+    min: number | null;
+    max: number | null;
+    integer: boolean;
+    constructor(config: NumberFieldConfig | FieldConfig);
+    validate(value: FieldValue): ValidationResult;
+    format(value: FieldValue): string;
+}
+
+export declare interface NumberFieldConfig extends BaseFieldConfig {
+    type: 'number';
+    min?: number;
+    max?: number;
+    integer?: boolean;
+}
+
+/**
+ * FormShell TUI Renderer
+ * Handles elegant rendering in the browser console
+ * Includes blinking cursor, animations, Unicode boxes, and CSS styling
+ */
+declare interface ProgressBarResult {
+    bar: string;
+    percentage: number;
+    text: string;
+}
+
+export declare interface ProgressInfo {
+    current: number;
+    total: number;
+    percentage: number;
+}
+
+/**
+ * Rating field (scale 1-5 with stars)
+ */
+export declare class RatingField extends NumberField {
+    constructor(config: RatingFieldConfig | FieldConfig);
+    validate(value: FieldValue): ValidationResult;
+    format(value: FieldValue): string;
+}
+
+export declare interface RatingFieldConfig extends BaseFieldConfig {
+    type: 'rating';
+    min?: number;
+    max?: number;
+}
+
+export declare interface Step {
+    id: string;
+    field: FieldInstance;
+    description: string | null;
+    answered: boolean;
+}
+
+declare interface StylePreset {
+    [key: string]: string | undefined;
+    color: string;
+    fontSize: string;
+    fontWeight?: string;
+    fontStyle?: string;
+    lineHeight?: string;
+    textShadow?: string;
+}
+
+declare interface StylePresets {
+    title: StylePreset;
+    subtitle: StylePreset;
+    body: StylePreset;
+    success: StylePreset;
+    error: StylePreset;
+    muted: StylePreset;
+    highlight: StylePreset;
+}
+
+/**
+ * Free text field
+ */
+export declare class TextField extends BaseField {
+    minLength: number | null;
+    maxLength: number | null;
+    pattern: RegExp | null;
+    constructor(config: TextFieldConfig | FieldConfig);
+    validate(value: FieldValue): ValidationResult;
+}
+
+export declare interface TextFieldConfig extends BaseFieldConfig {
+    type: 'text';
+    minLength?: number;
+    maxLength?: number;
+    pattern?: RegExp;
+}
+
+declare interface TextFormatters {
+    bold: (text: string) => string;
+    italic: (text: string) => string;
+    underline: (text: string) => string;
+    boldUnicode: (text: string) => string;
+}
+
+export declare const Theme: ThemeType;
+
+declare interface ThemeType {
+    colors: ColorPalette;
+    icons: Icons;
+    box: BoxCharacters;
+    text: TextFormatters;
+    styles: StylePresets;
+    createStyle: (styleObj: Record<string, string | undefined>) => string;
+    format: FormatFunctions;
+}
+
+export declare class TUIRenderer {
+    private cursorVisible;
+    private cursorInterval;
+    constructor();
+    /**
+     * Initialize the renderer and start cursor blinking
+     */
+    init(): void;
+    /**
+     * Clear the console
+     */
+    clear(): void;
+    /**
+     * Start the cursor blinking animation
+     */
+    startCursorBlink(): void;
+    /**
+     * Stop the cursor animation
+     */
+    stopCursorBlink(): void;
+    /**
+     * Get the current cursor character
+     */
+    getCursor(): string;
+    /**
+     * Create a decorative horizontal line
+     */
+    createHorizontalLine(width?: number, char?: string): string;
+    /**
+     * Create a box with Unicode borders
+     */
+    createBox(content: string | string[], width?: number, style?: 'single' | 'double'): string[];
+    /**
+     * Create an elegant progress bar
+     */
+    createProgressBar(current: number, total: number, width?: number): ProgressBarResult;
+    /**
+     * Render the main title with style
+     */
+    renderTitle(title: string): void;
+    /**
+     * Render the subtitle with style
+     */
+    renderSubtitle(subtitle: string): void;
+    /**
+     * Render normal text
+     */
+    renderText(text: string, color?: string | null): void;
+    /**
+     * Render a success message
+     */
+    renderSuccess(message: string): void;
+    /**
+     * Render an error message
+     */
+    renderError(message: string): void;
+    /**
+     * Render muted/secondary text
+     */
+    renderMuted(text: string): void;
+    /**
+     * Render highlighted text
+     */
+    renderHighlight(text: string): void;
+    /**
+     * Render a complete box
+     */
+    renderBox(content: string | string[], width?: number, style?: 'single' | 'double'): void;
+    /**
+     * Render a separator line
+     */
+    renderSeparator(width?: number, char?: string): void;
+    /**
+     * Render the progress bar with info
+     */
+    renderProgress(current: number, total: number, label?: string): void;
+    /**
+     * Render a list of options
+     */
+    renderOptions(options: string[], highlightIndex?: number | null): void;
+    /**
+     * Render an input field with cursor
+     */
+    renderInput(label: string, value?: string, showCursor?: boolean): void;
+    /**
+     * Render a yes/no question
+     */
+    renderYesNo(question: string, value?: boolean | null, yesLabel?: string, noLabel?: string): void;
+    /**
+     * Render rating with stars
+     */
+    renderRating(label: string, value?: number, max?: number): void;
+    /**
+     * Render a summary with key-value data
+     */
+    renderSummary(title: string, data: Record<string, unknown>): void;
+    /**
+     * Render a help/commands message
+     */
+    renderHelp(commands: Array<{
+        command: string;
+        description: string;
+    }>, title?: string): void;
+    /**
+     * Render an animated welcome message
+     */
+    renderWelcome(title: string, subtitle?: string | null): void;
+    /**
+     * Render a spinner/loader (static, not animated)
+     */
+    renderLoader(message?: string): void;
+    /**
+     * Cleanup the renderer
+     */
+    destroy(): void;
+}
+
+/**
+ * URL field
+ */
+export declare class URLField extends TextField {
+    constructor(config: FieldConfig);
+    validate(value: FieldValue): ValidationResult;
+}
+
+export declare interface URLFieldConfig extends BaseFieldConfig {
+    type: 'url';
+}
+
+export declare interface ValidationResult {
+    valid: boolean;
+    error?: string;
+}
+
+/**
+ * Yes/No field
+ */
+export declare class YesNoField extends BaseField {
+    constructor(config: FieldConfig);
+    validate(value: FieldValue): ValidationResult;
+    setValue(value: FieldValue): boolean;
+    format(value: FieldValue): string;
+}
+
+export declare interface YesNoFieldConfig extends BaseFieldConfig {
+    type: 'yesno';
+    defaultValue?: boolean;
+}
+
+export { }