@framesquared/form 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,781 @@
+import { Component, ComponentConfig, Container, ContainerConfig } from '@framesquared/component';
+import { Panel, PanelConfig } from '@framesquared/ui';
+
+/**
+ * @framesquared/form – Field (base class)
+ *
+ * Abstract base for all form fields.  Provides label rendering,
+ * value management, dirty tracking, validation framework, and
+ * error display.  Subclasses implement the actual input element.
+ */
+
+interface FieldConfig extends ComponentConfig {
+    name?: string;
+    value?: unknown;
+    fieldLabel?: string;
+    labelAlign?: 'left' | 'top' | 'right';
+    labelWidth?: number;
+    labelSeparator?: string;
+    hideLabel?: boolean;
+    emptyText?: string;
+    readOnly?: boolean;
+    disabled?: boolean;
+    validateOnChange?: boolean;
+    validateOnBlur?: boolean;
+    msgTarget?: 'side' | 'under' | 'qtip' | 'title' | 'none';
+    submitValue?: boolean;
+}
+declare class Field extends Component {
+    static $className: string;
+    protected _name: string;
+    protected _originalValue: unknown;
+    protected _value: unknown;
+    protected _errors: string[];
+    protected _wasValid: boolean;
+    protected _wasDirty: boolean;
+    protected _labelEl: HTMLElement | null;
+    protected _bodyWrapEl: HTMLElement | null;
+    protected _errorEl: HTMLElement | null;
+    constructor(config?: FieldConfig);
+    protected initialize(): void;
+    protected afterRender(): void;
+    /**
+     * Called after the full subclass afterRender chain completes.
+     * Subclasses that need post-render init should call super.afterRender()
+     * then do their work — this method sets initial validity once
+     * the input element exists.
+     */
+    protected initFieldValidity(): void;
+    getValue(): unknown;
+    setValue(value: unknown): void;
+    getRawValue(): string;
+    setRawValue(value: string): void;
+    protected onValueChange(oldValue: unknown, newValue: unknown): void;
+    isDirty(): boolean;
+    reset(): void;
+    protected checkDirty(): void;
+    getErrors(): string[];
+    isValid(): boolean;
+    validate(): boolean;
+    /** Subclasses override to add field-specific validation. */
+    protected computeErrors(): string[];
+    markInvalid(errors: string | string[]): void;
+    clearInvalid(): void;
+    protected checkValidity(): void;
+    protected showErrors(): void;
+    protected removeErrorEl(): void;
+    getSubmitValue(): string;
+    getName(): string;
+}
+
+/**
+ * @framesquared/form – TextField
+ *
+ * A text input field with validation (allowBlank, minLength, maxLength,
+ * regex, vtype), character masking, triggers, and keyboard events.
+ */
+
+interface TriggerConfig {
+    type: string;
+    handler?: (field: TextField, trigger: HTMLElement, event: Event) => void;
+    cls?: string;
+}
+interface TextFieldConfig extends FieldConfig {
+    maxLength?: number;
+    minLength?: number;
+    allowBlank?: boolean;
+    regex?: RegExp;
+    regexText?: string;
+    vtype?: string;
+    maskRe?: RegExp;
+    stripCharsRe?: RegExp;
+    inputType?: string;
+    triggers?: TriggerConfig[];
+}
+declare class TextField extends Field {
+    static $className: string;
+    protected _inputEl: HTMLInputElement;
+    constructor(config?: TextFieldConfig);
+    protected afterRender(): void;
+    getInputEl(): HTMLInputElement;
+    getValue(): string;
+    setValue(value: unknown): void;
+    getRawValue(): string;
+    setRawValue(value: string): void;
+    getSubmitValue(): string;
+    protected computeErrors(): string[];
+    protected attachInputEvents(cfg: TextFieldConfig): void;
+    protected renderTrigger(trig: TriggerConfig): void;
+}
+
+/**
+ * @framesquared/form – TextArea
+ * Multi-line text field using <textarea>.  Supports rows, cols,
+ * and auto-grow (grow, growMin, growMax).
+ */
+
+interface TextAreaConfig extends TextFieldConfig {
+    rows?: number;
+    cols?: number;
+    grow?: boolean;
+    growMin?: number;
+    growMax?: number;
+}
+declare class TextArea extends TextField {
+    static $className: string;
+    private _textareaEl;
+    constructor(config?: TextAreaConfig);
+    protected afterRender(): void;
+    getInputEl(): HTMLInputElement;
+    getValue(): string;
+    setValue(value: unknown): void;
+}
+
+/**
+ * @framesquared/form – DisplayField
+ * Read-only display of a value.  No input element, no form submission.
+ */
+
+interface DisplayFieldConfig extends FieldConfig {
+    renderer?: (value: unknown) => string;
+}
+declare class DisplayField extends Field {
+    static $className: string;
+    private _displayEl;
+    constructor(config?: DisplayFieldConfig);
+    protected initialize(): void;
+    protected afterRender(): void;
+    setValue(value: unknown): void;
+    getSubmitValue(): string;
+    private updateDisplay;
+}
+
+/**
+ * @framesquared/form – HiddenField
+ * Renders as <input type="hidden">.  No label, no visible UI.
+ */
+
+declare class HiddenField extends Field {
+    static $className: string;
+    private _hiddenInput;
+    constructor(config?: FieldConfig);
+    protected afterRender(): void;
+    getValue(): string;
+    setValue(value: unknown): void;
+    getSubmitValue(): string;
+}
+
+/**
+ * @framesquared/form – VTypes
+ * Predefined validation types for text fields.
+ */
+interface VTypeEntry {
+    test: (value: string) => boolean;
+    regex: RegExp;
+    text: string;
+}
+declare const VTypes: Record<string, VTypeEntry>;
+
+/**
+ * @framesquared/form – NumberField
+ *
+ * Numeric input with spinner triggers for increment/decrement,
+ * min/max validation, and decimal precision formatting.
+ */
+
+interface NumberFieldConfig extends TextFieldConfig {
+    minValue?: number;
+    maxValue?: number;
+    step?: number;
+    allowDecimals?: boolean;
+    decimalPrecision?: number;
+    decimalSeparator?: string;
+    autoStripChars?: boolean;
+}
+declare class NumberField extends TextField {
+    static $className: string;
+    private _minValue;
+    private _maxValue;
+    private _step;
+    private _allowDecimals;
+    private _decimalPrecision;
+    constructor(config?: NumberFieldConfig);
+    protected initialize(): void;
+    protected afterRender(): void;
+    getNumberValue(): number;
+    setValue(value: unknown): void;
+    private formatInputValue;
+    spinUp(): void;
+    spinDown(): void;
+    setMinValue(value: number): void;
+    setMaxValue(value: number): void;
+    protected computeErrors(): string[];
+}
+
+/**
+ * @framesquared/form – DateField
+ *
+ * A text field for date input.  Formats/parses dates using a
+ * configurable format string.  Has an expand trigger for opening
+ * a DatePicker dropdown.  Validates min/max date boundaries.
+ */
+
+interface DateFieldConfig extends TextFieldConfig {
+    format?: string;
+    minValue?: Date;
+    maxValue?: Date;
+    disabledDates?: string[];
+    disabledDays?: number[];
+    showToday?: boolean;
+}
+declare class DateField extends TextField {
+    static $className: string;
+    private _format;
+    private _minDate;
+    private _maxDate;
+    private _dateValue;
+    constructor(config?: DateFieldConfig);
+    protected initialize(): void;
+    protected afterRender(): void;
+    getDateValue(): Date | null;
+    setValue(value: unknown): void;
+    setMinValue(date: Date): void;
+    setMaxValue(date: Date): void;
+    protected computeErrors(): string[];
+}
+
+/**
+ * @framesquared/form – DatePicker
+ *
+ * Full calendar widget.  Shows a month grid with day cells,
+ * prev/next navigation, today button, and disabled date support.
+ * Fires 'select' when a date is clicked.
+ */
+
+interface DatePickerConfig extends ComponentConfig {
+    value?: Date;
+    minValue?: Date;
+    maxValue?: Date;
+    disabledDays?: number[];
+    disabledDates?: string[];
+    showToday?: boolean;
+}
+declare class DatePicker extends Component {
+    static $className: string;
+    private _viewDate;
+    private _selectedDate;
+    private _minDate;
+    private _maxDate;
+    private _disabledDays;
+    private _gridEl;
+    private _headerEl;
+    constructor(config?: DatePickerConfig);
+    protected initialize(): void;
+    protected afterRender(): void;
+    private buildUI;
+    private renderGrid;
+    private navigate;
+    private isDateDisabled;
+    private startOfDay;
+    getSelectedDate(): Date;
+}
+
+/**
+ * @framesquared/form – ColorPicker
+ *
+ * A grid of color swatches.  Fires 'select' with the hex color string.
+ */
+
+interface ColorPickerConfig extends ComponentConfig {
+    colors?: string[];
+}
+declare class ColorPicker extends Component {
+    static $className: string;
+    private _colors;
+    private _selectedColor;
+    constructor(config?: ColorPickerConfig);
+    protected initialize(): void;
+    protected afterRender(): void;
+    private buildSwatches;
+    getSelectedColor(): string | null;
+}
+
+/**
+ * @framesquared/form – ComboBox
+ *
+ * A text field with a dropdown list of options.  Supports local
+ * and remote query modes, multi-select, forceSelection, typeAhead,
+ * and keyboard navigation.
+ */
+
+interface ComboBoxConfig extends TextFieldConfig {
+    store?: any;
+    displayField?: string;
+    valueField?: string;
+    queryMode?: 'local' | 'remote';
+    queryParam?: string;
+    queryDelay?: number;
+    minChars?: number;
+    triggerAction?: 'all' | 'last' | 'query';
+    forceSelection?: boolean;
+    typeAhead?: boolean;
+    multiSelect?: boolean;
+    delimiter?: string;
+    editable?: boolean;
+    autoSelect?: boolean;
+    pageSize?: number;
+}
+declare class ComboBox extends TextField {
+    static $className: string;
+    _store: any;
+    private _displayField;
+    private _valueField;
+    private _queryMode;
+    private _forceSelection;
+    private _multiSelect;
+    private _delimiter;
+    private _expanded;
+    private _selection;
+    private _boundList;
+    private _selectedValue;
+    constructor(config?: ComboBoxConfig);
+    protected initialize(): void;
+    protected afterRender(): void;
+    expand(): void;
+    collapse(): void;
+    isExpanded(): boolean;
+    select(record: any): void;
+    deselect(record: any): void;
+    getSelection(): any[];
+    private updateMultiDisplay;
+    doQuery(queryString: string): void;
+    findRecord(field: string, value: unknown): any | null;
+    getValue(): any;
+    protected onDestroy(): void;
+}
+
+/**
+ * @framesquared/form – TagField
+ *
+ * A ComboBox variant that shows selected values as removable tag
+ * chips in the input area.  Always multi-select.
+ */
+
+interface TagFieldConfig extends ComboBoxConfig {
+    filterPickList?: boolean;
+    stacked?: boolean;
+    createNewOnEnter?: boolean;
+}
+declare class TagField extends ComboBox {
+    static $className: string;
+    private _tagWrapEl;
+    constructor(config?: TagFieldConfig);
+    protected initialize(): void;
+    protected afterRender(): void;
+    select(record: any): void;
+    deselect(record: any): void;
+    private renderTags;
+    getValue(): any;
+}
+
+/**
+ * @framesquared/form – Checkbox
+ *
+ * A checkbox field using native <input type="checkbox">.
+ * Returns inputValue when checked, uncheckedValue when unchecked.
+ */
+
+interface CheckboxConfig extends FieldConfig {
+    inputValue?: string;
+    uncheckedValue?: string;
+    checked?: boolean;
+    boxLabel?: string;
+}
+declare class Checkbox extends Field {
+    static $className: string;
+    protected _inputEl: HTMLInputElement;
+    protected _checked: boolean;
+    protected _inputValue: string;
+    protected _uncheckedValue: string;
+    constructor(config?: CheckboxConfig);
+    protected initialize(): void;
+    protected afterRender(): void;
+    getValue(): string;
+    isChecked(): boolean;
+    setChecked(checked: boolean): void;
+    getSubmitValue(): string;
+}
+
+/**
+ * @framesquared/form – Radio
+ *
+ * A radio button field.  Uses native <input type="radio"> with
+ * group tracking to ensure single selection per name group.
+ */
+
+declare class Radio extends Checkbox {
+    static $className: string;
+    constructor(config?: CheckboxConfig);
+    protected afterRender(): void;
+    setChecked(checked: boolean): void;
+    getGroupValue(): string;
+    protected onDestroy(): void;
+}
+
+/**
+ * @framesquared/form – CheckboxGroup
+ *
+ * A container for Checkbox fields arranged in columns.
+ * getValue returns array of checked values.
+ */
+
+interface CheckboxGroupConfig extends ContainerConfig {
+    columns?: number;
+    vertical?: boolean;
+}
+declare class CheckboxGroup extends Container {
+    static $className: string;
+    constructor(config?: CheckboxGroupConfig);
+    protected afterRender(): void;
+    getValue(): string[];
+    setValue(values: string[]): void;
+}
+
+/**
+ * @framesquared/form – RadioGroup
+ *
+ * A container for Radio fields.  Only one radio can be selected
+ * at a time (enforced by Radio's group mechanism).
+ */
+
+interface RadioGroupConfig extends ContainerConfig {
+    columns?: number;
+    vertical?: boolean;
+}
+declare class RadioGroup extends Container {
+    static $className: string;
+    constructor(config?: RadioGroupConfig);
+    protected afterRender(): void;
+    getValue(): string;
+    setValue(value: string): void;
+}
+
+/**
+ * @framesquared/form – BoundList
+ *
+ * The dropdown list used by ComboBox.  Renders items from a Store,
+ * supports hover highlighting, keyboard navigation (up/down/enter/esc),
+ * and fires itemclick/select events.
+ */
+
+interface BoundListConfig extends ComponentConfig {
+    store?: any;
+    displayField?: string;
+}
+declare class BoundList extends Component {
+    static $className: string;
+    private _store;
+    private _displayField;
+    private _highlightIndex;
+    constructor(config?: BoundListConfig);
+    protected initialize(): void;
+    protected afterRender(): void;
+    refresh(): void;
+    private renderItems;
+    private highlightItem;
+    private onKeyDown;
+    getStore(): any;
+}
+
+/**
+ * @framesquared/form – BasicForm
+ *
+ * Core form logic separated from UI.  Manages a collection of
+ * Field instances, collects/distributes values, validates,
+ * and handles submit/load via fetch().
+ */
+
+interface SubmitOptions {
+    url?: string;
+    method?: string;
+    params?: Record<string, unknown>;
+    headers?: Record<string, string>;
+    clientValidation?: boolean;
+    jsonSubmit?: boolean;
+}
+interface SubmitResult {
+    success: boolean;
+    data?: any;
+    errors?: any;
+}
+declare class BasicForm {
+    private fields;
+    addField(field: Field): void;
+    removeField(field: Field): void;
+    getFields(): Field[];
+    findField(name: string): Field | undefined;
+    getValues(asString?: boolean, dirtyOnly?: boolean): Record<string, unknown> | string;
+    setValues(values: Record<string, unknown>): void;
+    isValid(): boolean;
+    isDirty(): boolean;
+    reset(): void;
+    clearInvalid(): void;
+    markInvalid(errors: {
+        field: string;
+        message: string;
+    }[]): void;
+    submit(url: string, options?: SubmitOptions): Promise<SubmitResult>;
+    load(url: string, options?: SubmitOptions): Promise<SubmitResult>;
+}
+
+/**
+ * @framesquared/form – FormPanel
+ *
+ * A Panel that manages form fields.  Extends Panel to provide
+ * automatic field collection, validation, value management,
+ * and submit/load via fetch().
+ */
+
+interface FormPanelConfig extends PanelConfig {
+    url?: string;
+    method?: 'GET' | 'POST';
+    standardSubmit?: boolean;
+    jsonSubmit?: boolean;
+    waitMsg?: string;
+    trackResetOnLoad?: boolean;
+    fieldDefaults?: Record<string, unknown>;
+    timeout?: number;
+}
+declare class FormPanel extends Panel {
+    static $className: string;
+    private _basicForm;
+    private _url;
+    private _method;
+    private _jsonSubmit;
+    constructor(config?: FormPanelConfig);
+    protected initialize(): void;
+    protected afterRender(): void;
+    private collectFields;
+    private walkItems;
+    getValues(asString?: boolean, dirtyOnly?: boolean): Record<string, unknown> | string;
+    setValues(values: Record<string, unknown>): void;
+    isFormValid(): boolean;
+    isValid(): boolean;
+    isDirty(): boolean;
+    getFields(): Field[];
+    findField(name: string): Field | undefined;
+    reset(): void;
+    clearInvalid(): void;
+    markInvalid(errors: {
+        field: string;
+        message: string;
+    }[]): void;
+    hasInvalidField(): boolean;
+    submit(options?: SubmitOptions & {
+        clientValidation?: boolean;
+    }): Promise<SubmitResult>;
+    load(options?: SubmitOptions): Promise<void>;
+}
+
+/**
+ * @framesquared/form – Validators
+ *
+ * Built-in validator functions and chain runner.
+ * Each validator returns `true` on success or an error string on failure.
+ */
+declare function presence(value: unknown): true | string;
+declare function length(value: unknown, opts: {
+    min?: number;
+    max?: number;
+}): true | string;
+declare function email(value: unknown): true | string;
+declare function url(value: unknown): true | string;
+declare function alpha(value: unknown): true | string;
+declare function alphanum(value: unknown): true | string;
+declare function range(value: unknown, opts: {
+    min?: number;
+    max?: number;
+}): true | string;
+declare function format(value: unknown, opts: {
+    matcher: RegExp;
+    message?: string;
+}): true | string;
+declare function inclusion(value: unknown, opts: {
+    list: unknown[];
+}): true | string;
+declare function exclusion(value: unknown, opts: {
+    list: unknown[];
+}): true | string;
+declare function custom(value: unknown, opts: {
+    fn: (v: unknown) => true | string;
+}): true | string;
+interface ChainEntry {
+    type: 'presence' | 'length' | 'email' | 'url' | 'alpha' | 'alphanum' | 'range' | 'format' | 'inclusion' | 'exclusion' | 'custom';
+    [key: string]: unknown;
+}
+/**
+ * Run a chain of validators against a value.
+ * Returns an array of error strings (empty if all pass).
+ */
+declare function validateChain(value: unknown, chain: ChainEntry[]): string[];
+
+/**
+ * @framesquared/form – FieldContainer
+ *
+ * A Container that groups multiple Field children under a single
+ * label.  Optionally combines child validation errors.
+ */
+
+interface FieldContainerConfig extends ContainerConfig {
+    fieldLabel?: string;
+    labelSeparator?: string;
+    combineErrors?: boolean;
+}
+declare class FieldContainer extends Container {
+    static $className: string;
+    constructor(config?: FieldContainerConfig);
+    protected afterRender(): void;
+    getErrors(): string[];
+    isValid(): boolean;
+}
+
+/**
+ * @framesquared/form – Slider
+ *
+ * A slider field with draggable thumb(s) on a track.  Supports
+ * min/max, increment snapping, multi-thumb, vertical mode,
+ * and full ARIA attributes.
+ */
+
+interface SliderConfig extends FieldConfig {
+    minValue?: number;
+    maxValue?: number;
+    increment?: number;
+    vertical?: boolean;
+    useTips?: boolean;
+    values?: number[];
+    clickToChange?: boolean;
+    animate?: boolean;
+}
+declare class Slider extends Field {
+    static $className: string;
+    private _min;
+    private _max;
+    private _increment;
+    private _vertical;
+    private _values;
+    private _trackEl;
+    private _thumbEls;
+    private _dragIndex;
+    private _dragCleanup;
+    constructor(config?: SliderConfig);
+    protected initialize(): void;
+    protected afterRender(): void;
+    getValue(): number;
+    setValue(value: unknown): void;
+    getValues(): number[];
+    setMinValue(min: number): void;
+    setMaxValue(max: number): void;
+    setIncrement(inc: number): void;
+    private clamp;
+    private snap;
+    private positionThumbs;
+    private updateAria;
+    private updateAllAria;
+    private setupThumbDrag;
+}
+
+/**
+ * @framesquared/form – FileField
+ *
+ * A file upload field with a hidden <input type="file">,
+ * a browse button, and a text display showing selected filename(s).
+ */
+
+interface FileFieldConfig extends FieldConfig {
+    buttonText?: string;
+    buttonOnly?: boolean;
+    accept?: string;
+    multiple?: boolean;
+}
+declare class FileField extends Field {
+    static $className: string;
+    private _fileInput;
+    private _textDisplay;
+    private _files;
+    constructor(config?: FileFieldConfig);
+    protected initialize(): void;
+    protected afterRender(): void;
+    getValue(): FileList | null;
+    getFileInput(): HTMLInputElement;
+}
+
+/**
+ * @framesquared/form – HtmlEditor
+ *
+ * Rich text editor using contentEditable.  Provides a toolbar with
+ * formatting buttons, source edit mode, and XSS sanitization.
+ */
+
+interface HtmlEditorConfig extends FieldConfig {
+    enableFont?: boolean;
+    enableColors?: boolean;
+    enableLists?: boolean;
+    enableLinks?: boolean;
+    enableSourceEdit?: boolean;
+}
+declare class HtmlEditor extends Field {
+    static $className: string;
+    private _toolbarEl;
+    private _editorEl;
+    private _sourceEl;
+    private _sourceMode;
+    constructor(config?: HtmlEditorConfig);
+    protected initialize(): void;
+    protected afterRender(): void;
+    getValue(): string;
+    setValue(value: unknown): void;
+    execCommand(cmd: string, value?: string): void;
+    toggleSourceEdit(): void;
+    isSourceEdit(): boolean;
+    private sanitize;
+}
+
+/**
+ * @framesquared/form – Spinner
+ *
+ * Abstract base for fields with up/down spin behavior.
+ * Extends TextField with spinner triggers and ArrowUp/ArrowDown keyboard.
+ * Subclasses implement onSpinUp() and onSpinDown().
+ */
+
+interface SpinnerConfig extends TextFieldConfig {
+}
+declare abstract class Spinner extends TextField {
+    static $className: string;
+    constructor(config?: SpinnerConfig);
+    protected afterRender(): void;
+    spinUp(): void;
+    spinDown(): void;
+    protected abstract onSpinUp(): void;
+    protected abstract onSpinDown(): void;
+}
+
+/**
+ * @framesquared/form – DateUtil
+ *
+ * Date utility functions: format, parse, add, diff, isLeapYear, getDaysInMonth.
+ * Format tokens: Y (4-digit year), m (01-12), d (01-31),
+ * H (00-23), i (00-59), s (00-59), g (1-12), A (AM/PM).
+ */
+type DateUnit = 'year' | 'month' | 'day' | 'hour' | 'minute' | 'second';
+declare function formatDate(date: Date, format: string): string;
+declare function parseDate(input: string, format: string): Date;
+declare function addDate(date: Date, unit: DateUnit, amount: number): Date;
+declare function diffDate(date1: Date, date2: Date, unit: DateUnit): number;
+declare function isLeapYear(year: number): boolean;
+declare function getDaysInMonth(year: number, month: number): number;
+declare function getMonthName(month: number): string;
+declare function getMonthShortName(month: number): string;
+
+export { BasicForm, BoundList, type BoundListConfig, Checkbox, type CheckboxConfig, CheckboxGroup, type CheckboxGroupConfig, ColorPicker, type ColorPickerConfig, ComboBox, type ComboBoxConfig, DateField, type DateFieldConfig, DatePicker, type DatePickerConfig, type DateUnit, DisplayField, type DisplayFieldConfig, Field, type FieldConfig, FieldContainer, type FieldContainerConfig, FileField, type FileFieldConfig, FormPanel, type FormPanelConfig, HiddenField, HtmlEditor, type HtmlEditorConfig, NumberField, type NumberFieldConfig, Radio, RadioGroup, type RadioGroupConfig, Slider, type SliderConfig, Spinner, type SpinnerConfig, type SubmitOptions, type SubmitResult, TagField, type TagFieldConfig, TextArea, type TextAreaConfig, TextField, type TextFieldConfig, type TriggerConfig, type VTypeEntry, VTypes, addDate, alpha, alphanum, custom, diffDate, email, exclusion, format, formatDate, getDaysInMonth, getMonthName, getMonthShortName, inclusion, isLeapYear, length, parseDate, presence, range, url, validateChain };