coles-solid-library 0.4.7 → 0.4.9

package/USAGE.html

@@ -551,6 +551,36 @@ fg.addToArray('pets', ['name', []] as any, { name: 'Fido' });
 fg.validate('pets'); // true now
 fg.removeFromArray('pets', 0);</code></pre>
     <p><strong>Item Shape:</strong> Adding to a FormArray requires a control definition tuple: <code>['propName', validators[]]</code>. Provide an object value with those props.</p>
+  <h3 id="forms-formarray-toplevel">FormArray as Top-Level Form Data</h3>
+    <p>The <code>&lt;Form&gt;</code> component accepts either a <code>FormGroup</code> or a <code>FormArray</code> as its <code>data</code> prop. When using a <code>FormArray</code>, <code>onSubmit</code> receives <code>T[]</code> instead of <code>T</code>.</p>
+    <pre><code>import { Form, FormArray, Validators, Button } from 'coles-solid-library';
+import { For } from 'solid-js';
+
+interface TodoItem { text: string; done: boolean }
+
+const todos = new FormArray&lt;TodoItem&gt;(
+  [
+    [['text', [Validators.Required]], ['done', []]],
+    [Validators.custom&lt;TodoItem[]&gt;('minOne', v =&gt; v.length &gt;= 1)]
+  ],
+  [{ text: 'Buy milk', done: false }]
+);
+
+// onSubmit receives TodoItem[] when data is a FormArray
+&lt;Form data={todos} onSubmit={(items) =&gt; console.log('todos:', items)}&gt;
+  &lt;For each={todos.get()}&gt;
+    {(item, i) =&gt; (
+      &lt;div&gt;
+        &lt;input value={item.text}
+          onInput={e =&gt; todos.setProperty(i(), 'text', e.currentTarget.value)} /&gt;
+        &lt;input type="checkbox" checked={item.done}
+          onChange={e =&gt; todos.setProperty(i(), 'done', e.currentTarget.checked)} /&gt;
+      &lt;/div&gt;
+    )}
+  &lt;/For&gt;
+  &lt;Button type="submit" theme="primary"&gt;Save&lt;/Button&gt;
+&lt;/Form&gt;</code></pre>
+    <p><strong>Note:</strong> When using <code>FormArray</code> as the top-level <code>data</code>, <code>FormField</code> field binding and <code>useFormFieldBinding</code> are not available. Manage array items directly through the FormArray API.</p>
   <h3 id="forms-async">Async Validators</h3>
     <p>Create via <code>Validators.asyncCustom('key', asyncFn, hide?)</code>. <code>validate()</code> is optimistic for async; call <code>await validateAsync()</code> to finalize.</p>
   <h3 id="forms-validation-flow">Validation Flow</h3>
@@ -570,7 +600,7 @@ if (asyncOk) doSubmit();</code></pre>
       <tr><td>FormGroup&lt;T&gt;</td><td><code>get/getR/set/reset/validate/validateAsync/addValidator/removeValidator/addToArray/removeFromArray/getErrors/hasError/hasValidator/getMeta/getArrayItem/markTouched/markDirty/setError</code></td><td>Root form state + validation engine.</td></tr>
       <tr><td>FormArray&lt;T&gt;</td><td><code>get/getAt/getProperty/set/setAt/setProperty/add/remove/replace/validate/validateCurrent/hasError/hasValidator/getErrors/getErrorsAt</code></td><td>Dynamic object array with array + control validators.</td></tr>
       <tr><td>Validators</td><td><code>Required/Email/minLength/maxLength/pattern/custom/asyncCustom</code></td><td>Validator factories; <code>hide</code> predicate suppresses an error.</td></tr>
-      <tr><td>&lt;Form&gt;</td><td><code>data</code>, <code>onSubmit</code></td><td>Context provider + submit orchestration (sync validate).</td></tr>
+      <tr><td>&lt;Form&gt;</td><td><code>data: FormGroup&lt;T&gt; | FormArray&lt;T&gt;</code>, <code>onSubmit</code></td><td>Context provider + submit orchestration. Accepts FormGroup (onSubmit receives T) or FormArray (onSubmit receives T[]).</td></tr>
       <tr><td>&lt;FormField&gt;</td><td><code>name</code>, <code>formName</code>, <code>required?</code>, others</td><td>Floating legend, focus, error projection region.</td></tr>
       <tr><td>&lt;ColeError&gt;</td><td><code>errorName</code></td><td>Registers error display element for key.</td></tr>
       <tr><td>useFormFieldBinding</td><td><code>(key)</code> =&gt; binding object</td><td>Manual binding to a control.</td></tr>

package/dist/components/Checkbox/checkbox.d.ts

@@ -6,6 +6,9 @@ interface CheckboxProps {
     onChange?: (checked: boolean) => void;
     disabled?: boolean;
     ariaLabel?: string;
+    formName?: string;
+    formIndex?: number;
+    formArrayName?: string;
 }
 export declare function Checkbox(props: CheckboxProps): JSX.Element;
 export {};

package/dist/components/Chip/Chip.d.ts

@@ -3,7 +3,7 @@ interface Props {
     class?: string;
     key?: string;
     value: string;
-    remove?: () => any;
+    remove?: (e: MouseEvent) => any;
     onClick?: (e: MouseEvent) => any;
 }
 declare const Chip: Component<Props>;

package/dist/components/Form/form.d.ts

@@ -1,17 +1,19 @@
 import { JSX } from "solid-js";
 import { SetStoreFunction } from "solid-js/store";
 import { FormGroup } from "./formGroup";
+import { FormArray } from "./formHelp/formArray";
 interface FormContext<T extends object> {
     data: T;
     setData: SetStoreFunction<T>;
-    formGroup: FormGroup<T>;
+    formGroup?: FormGroup<T>;
+    formArray?: FormArray<any>;
 }
 declare const FormContext: import("solid-js").Context<FormContext<any> | undefined>;
 export declare const useFormContext: <T extends object = any>() => FormContext<T>;
 interface Props<T extends object> {
-    data: FormGroup<T>;
+    data: FormGroup<T> | FormArray<T>;
     children: JSX.Element;
-    onSubmit: (data: T) => void;
+    onSubmit: (data: T | T[]) => void;
 }
 export declare const Form: <T extends object>(props: Props<T>) => JSX.Element;
 export {};

package/dist/components/Form/formGroup.d.ts

@@ -1,4 +1,5 @@
-import { FormGroupData, ValidationDefault, ValidatorResult, ControlMeta } from "./formHelp/models";
+import { Error as FormError, FormGroupData, ValidatorResult, ControlMeta } from "./formHelp/models";
+import { Accessor } from "solid-js";
 export { FormArray } from "./formHelp/formArray";
 export { Validators } from "./formHelp/validators";
 /**
@@ -13,6 +14,11 @@ export declare class FormGroup<T extends object> {
     private errors;
     private meta;
     private keys;
+    /** Reactive memo that returns a cloned snapshot of the full form state.
+     *  FormArray fields resolve via `.get()` (plain array), others via `CloneStore`. */
+    formChangeValue: Accessor<T>;
+    /** Returns a per-field reactive accessor. Each call creates an independent memo. */
+    fieldChangeValue: <K extends keyof T>(key: K) => Accessor<T[K]>;
     constructor(data: FormGroupData<T>);
     /**
      * INTERNAL: returns the reactive internal store reference (DO NOT MUTATE outside FormGroup).
@@ -81,6 +87,12 @@ export declare class FormGroup<T extends object> {
     getMeta<K extends keyof T>(key: K): ControlMeta<T[K]>;
     markTouched<K extends keyof T>(key: K): void;
     markDirty<K extends keyof T>(key: K): void;
+    /** Returns true if any field in the group has validation errors. */
+    hasAnyError(): boolean;
+    /** Returns true if any field has a validator, optionally matching errKey. */
+    hasAnyValidator(errKey?: string): boolean;
+    /** Returns a flat array of all field errors across the group. */
+    getAllErrors(): FormError[];
     reset(): void;
     /**
      * Sets a new value for a specified form control.
@@ -90,13 +102,12 @@ export declare class FormGroup<T extends object> {
      */
     set<K extends keyof T>(key: K, value: T[K]): void;
     /**
-     * Adds an item to a FormArray control
+     * Adds a FormGroup item to a FormArray control.
      *
      * @param key - The key of the FormArray control
-     * @param controlValidation - The validation for the new item
-     * @param value - Optional initial value for the new item
+     * @param group - The FormGroup instance to add
      */
-    addToArray<K extends keyof T>(key: K, controlValidation: ValidationDefault<ElementType<T[K]> & object, keyof ElementType<T[K]>>, value?: ElementType<T[K]> & object): void;
+    addToArray<K extends keyof T>(key: K, group: FormGroup<ElementType<T[K]> & object>): void;
     /**
      * Removes an item from a FormArray control
      *

package/dist/components/Form/formHelp/formArray.d.ts

@@ -1,174 +1,178 @@
-import { ValidationDefault, ArrayValidation, Error } from "./models";
+import { ValidatorResult, Error } from "./models";
+import { FormGroup } from "../formGroup";
 /**
- * A class that encapsulates an array of form controls along with their validation logic.
+ * A class that encapsulates an array of FormGroup instances along with optional array-level validation.
  *
- * @template T - An object type representing the shape of a single form control's value.
+ * @template T - An object type representing the shape of a single form group's value.
  */
 export declare class FormArray<T extends object> {
     /**
-     * An array of array-level validators. Each validator validates the entire array of form control values.
-     * Each element is a ValidatorResult function that returns a validation result for the entire array.
-     *
+     * Array-level validators that validate the entire array of form group values.
      * @private
      */
     private internalArrayValidation;
     /**
-     * An array of control-level validators. Each element is a tuple where the first value is not used
-     * in this class and the second value is an array of validators that validate a single control value.
-     *
+     * The FormGroup instances managed by this array.
      * @private
      */
-    private internalValidation;
+    private groups;
     /**
-     * A function to update the current state of control-level validations.
-     *
+     * Solid store setter for the groups array.
      * @private
      */
-    private setValidation;
+    private setGroups;
     /**
-     * An array of error arrays. Each inner array holds the errors corresponding to a single form control.
-     *
+     * Array-level errors (from array-level validators only).
+     * Per-item errors live in each FormGroup.
      * @private
      */
-    private errors;
+    private arrayErrors;
     /**
-     * The current values of the form controls in the array.
-     *
+     * Snapshot of initial groups for reset.
      * @private
      */
-    private internalValues;
+    private readonly _initialGroups;
     /**
-     * A function to update the current values of the form controls.
+     * Creates an instance of FormArray.
      *
-     * @private
+     * @param groups - An array of FormGroup instances representing the initial items.
+     * @param arrayValidators - Optional array-level validators (e.g., min/max item count).
      */
-    private setValues;
-    private readonly _initialValidationDefs;
-    private readonly _initialValuesSnapshot;
+    constructor(groups?: FormGroup<T>[], arrayValidators?: ValidatorResult<T[]>[]);
     /**
-     * Creates an instance of FormArray.
-     *
-     * @param arrayValidation - A tuple where the first element is an initial array of control-level validation definitions
-     * and the second element is an array of array-level validators.
-     * @param initialValues - Optional initial values for the form controls.
+     * Returns the number of items in the array.
      */
-    constructor(arrayValidation: ArrayValidation<T>, initialValues?: T | T[]);
+    get length(): number;
     /**
-     * Returns true if any validator (array-level or control-level) exists matching the provided errKey.
+     * Returns true if any validator (array-level or within any group) exists matching the provided errKey.
      * If no errKey provided, returns true when any validator exists at all.
      */
     hasAnyValidator(errKey?: string): boolean;
     /**
-     * Resets the array to its initial validation definitions and values.
-     * Clears any accumulated errors and added dynamic controls.
+     * Resets the array to its initial groups and clears array-level errors.
+     * Each initial FormGroup is reset to its own initial state.
      */
     reset(): void;
     /**
-     * Gets the current values of the form controls in the array.
+     * Gets the current values of all form groups in the array.
      *
-     * @returns A cloned copy of the values array.
+     * @returns An array of cloned plain-object values from each FormGroup.
      */
     get(): T[];
     /**
-     * Gets the value of a specific control in the array.
+     * Gets the value of a specific form group in the array.
      *
-     * @param index - The index of the control.
-     * @returns A cloned copy of the control value.
+     * @param index - The index of the group.
+     * @returns A cloned copy of the group's value, or undefined if out of bounds.
      */
     getAt(index: number): T | undefined;
     /**
-     * Gets a property value from an object at the specified index.
+     * Gets the FormGroup instance at the specified index.
+     *
+     * @param index - The index of the group.
+     * @returns The FormGroup instance, or undefined if out of bounds.
+     */
+    getGroup(index: number): FormGroup<T> | undefined;
+    /**
+     * Returns a shallow copy of all FormGroup instances.
+     */
+    getGroups(): FormGroup<T>[];
+    /**
+     * Gets a property value from the FormGroup at the specified index.
      *
-     * @param index - The index of the control.
+     * @param index - The index of the group.
      * @param key - The property key to retrieve.
      * @returns The property value, or undefined if not found.
      */
     getProperty<K extends keyof T>(index: number, key: K): T[K] | undefined;
     /**
-     * Sets the values of all controls in the array.
+     * Sets the values of all groups. Updates existing groups in-place and
+     * discards any excess groups. Does not create new groups for excess values.
      *
-     * @param values - The new values for the controls.
+     * @param values - The new values for the groups.
      */
     set(values: T[]): void;
     /**
-     * Sets the value of a control at the specified index.
+     * Sets the value of a group at the specified index.
      *
-     * @param index - The index of the control to update.
-     * @param value - The new value for the control.
+     * @param index - The index of the group to update.
+     * @param value - The new value for the group.
      */
     setAt(index: number, value: T): void;
     /**
-     * Sets a property value on an object at the specified index.
+     * Sets a property value on the FormGroup at the specified index.
      *
-     * @param index - The index of the control.
+     * @param index - The index of the group.
      * @param key - The property key to set.
      * @param value - The new value for the property.
      */
     setProperty<K extends keyof T>(index: number, key: K, value: T[K]): void;
     /**
-     * Removes a control at the specified index.
+     * Removes a group at the specified index.
      *
-     * @param index - The index of the control to remove.
+     * @param index - The index of the group to remove.
      */
     remove(index: number): void;
     /**
-     * Replaces a control at the specified index with new validation and value.
+     * Replaces a group at the specified index with a new FormGroup.
      *
-     * @param index - The index of the control to replace.
-     * @param controlValidation - The new validation to apply for the control.
-     * @param value - The new value for the control.
+     * @param index - The index of the group to replace.
+     * @param group - The new FormGroup instance.
      */
-    replace(index: number, controlValidation: ValidationDefault<T, keyof T>, value?: T): void;
+    replace(index: number, group: FormGroup<T>): void;
     /**
-     * Adds a new control to the array with validation and optional value.
+     * Adds a new FormGroup to the array.
      *
-     * @param controlValidation - The validation definition to add.
-     * @param value - Optional value for the new control.
+     * @param group - The FormGroup instance to add.
      */
-    add(controlValidation: ValidationDefault<T, keyof T>, value?: T): void;
+    add(group: FormGroup<T>): void;
     /**
      * Checks if any validation errors exist.
      *
-     * @param index - (Optional) The index of the control to check for errors.
-     * If not provided, it checks the entire form array.
+     * @param index - (Optional) The index of the group to check for errors.
+     * If not provided, checks all groups and array-level errors.
      * @returns `true` if any errors are found, otherwise `false`.
      */
     hasError(index?: number): boolean;
     /**
-     * Checks if a specific validator error exists for a control at the given index.
+     * Checks if a specific validator error exists for a group at the given index.
      *
-     * @param index - The index of the control.
+     * @param index - The index of the group.
      * @param errKey - The key identifying the specific error to check for.
      * @returns `true` if the specific error is present, otherwise `false`.
      */
     hasValidator(index: number, errKey: string): boolean;
     /**
      * Gets all errors for the form array.
+     * Each inner array contains the errors from one FormGroup plus array-level errors.
      *
-     * @returns An array of error arrays for each control.
+     * @returns An array of error arrays for each group.
      */
     getErrors(): Error[][];
     /**
-     * Gets errors for a specific control in the array.
+     * Gets errors for a specific group in the array.
      *
-     * @param index - The index of the control.
-     * @returns An array of errors for the control, or an empty array if not found.
+     * @param index - The index of the group.
+     * @returns An array of errors for the group, or an empty array if not found.
      */
     getErrorsAt(index: number): Error[];
+    /**
+     * Gets only array-level errors (not per-group errors).
+     */
+    getArrayErrors(): Error[];
     /**
      * Validates the form array using current values.
      *
-     * @param index - Optional index to validate just one control.
+     * @param index - Optional index to validate just one group.
      * @returns True if validation passes, false otherwise.
      */
     validateCurrent(index?: number): boolean;
     /**
-     * Validates the provided form control values.
+     * Validates the form array.
      *
-     * @param values - The array of form control values.
-     * @param index - (Optional) The index of a single control to validate.
-     * If not provided, the method validates all controls in the form array.
+     * @param index - (Optional) The index of a single group to validate.
+     * If not provided, validates all groups and array-level validators.
      * @returns `true` if all validations pass, otherwise `false`.
      */
-    validate(values: T[], index?: number): boolean;
+    validate(index?: number): boolean;
 }

package/dist/components/Form/formHelp/models.d.ts

@@ -14,7 +14,6 @@ export type ValidationDefault<T, P extends keyof T> = [T[P], ValidatorResult<T[P
 export type ErrorObject<T> = {
     [P in keyof T]: Error[];
 };
-export type ArrayValidation<T> = [(ValidationDefault<T, keyof T>)[], ValidatorResult<T[]>[]];
 export type ValidatorObject<T> = {
     [P in keyof T]?: ValidatorResult<T[P]>[];
 };

package/dist/components/Form/useDirectFormBinding.d.ts

@@ -0,0 +1,40 @@
+import { FormGroup } from './formGroup';
+import { FormArray } from './formHelp/formArray';
+export interface DirectFormBindingProps {
+    /** Field key — either a FormGroup field name, or a property key within a FormArray item */
+    formName?: string;
+    /** Array index — selects which item in a FormArray to bind to */
+    formIndex?: number;
+    /** FormGroup key that holds the FormArray (for FormArray-within-FormGroup) */
+    formArrayName?: string;
+}
+export interface DirectFormBindingResult {
+    /** The resolved field name (from direct props or FormField context) */
+    formName: string | undefined;
+    /** Read the current bound value */
+    getValue: () => any;
+    /** Write a new value to the bound field */
+    setValue: (val: any) => void;
+    /** Mark the bound field as dirty */
+    markDirty: () => void;
+    /** Validate the bound field. Returns true if valid, false otherwise, undefined if no binding */
+    validate: () => boolean | undefined;
+    /** The FormGroup instance if available */
+    formGroup: FormGroup<any> | undefined;
+    /** The resolved FormArray instance if binding targets an array */
+    formArray: FormArray<any> | undefined;
+    /** True when binding targets a FormArray item */
+    isFormArray: boolean;
+}
+/**
+ * Hook that resolves form binding from direct props, with FormField context as fallback.
+ *
+ * Supports three binding modes:
+ * 1. **FormGroup (simple)**: `formName` binds to `formGroup.data[formName]`
+ * 2. **FormArray (top-level)**: `formIndex` + `formName` binds to `formArray.getAt(formIndex)[formName]`
+ * 3. **FormArray (within FormGroup)**: `formArrayName` + `formIndex` + `formName` binds to
+ *    `formGroup.data[formArrayName].getAt(formIndex)[formName]`
+ *
+ * Priority: direct props > FormField context > undefined
+ */
+export declare function useDirectFormBinding(props: DirectFormBindingProps): DirectFormBindingResult;

package/dist/components/Input/Input.d.ts

@@ -6,6 +6,9 @@ interface InputProps extends JSX.InputHTMLAttributes<HTMLInputElement> {
         currentTarget: HTMLInputElement;
         target: HTMLInputElement;
     }) => void;
+    formName?: string;
+    formIndex?: number;
+    formArrayName?: string;
 }
 declare const Input: Component<InputProps>;
 export { Input };

package/dist/components/Input/inputV2.d.ts

@@ -6,6 +6,9 @@ interface InputProps extends JSX.InputHTMLAttributes<HTMLInputElement> {
         currentTarget: HTMLInputElement;
         target: HTMLInputElement;
     }) => void;
+    formName?: string;
+    formIndex?: number;
+    formArrayName?: string;
 }
 declare const Input: Component<InputProps>;
 export { Input };

package/dist/components/Radio/radioGroup.d.ts

@@ -8,6 +8,9 @@ interface RadioGroupProps {
     onChange?: (value: string | number) => void;
     disabled?: boolean;
     children: JSX.Element | JSX.Element[];
+    formName?: string;
+    formIndex?: number;
+    formArrayName?: string;
 }
 export interface RadioGroupContextType {
     name: string;

package/dist/components/Select/select.component.d.ts

@@ -20,6 +20,9 @@ interface SelectProps<T = string, K = boolean> {
      * 'desktop': always uses desktop dropdown regardless of device.
      */
     mobileMode?: 'auto' | 'popup' | 'desktop';
+    formName?: string;
+    formIndex?: number;
+    formArrayName?: string;
 }
 export declare function Select<T, K extends boolean = false>(props: SelectProps<(K extends true ? T[] : T), K>): JSX.Element;
 export {};

package/dist/components/Select/selectContext.d.ts

@@ -10,6 +10,8 @@ export interface SelectContextValue<T> {
     isDisabled: () => boolean;
     /** Close the dropdown/popup without changing the value */
     closeDropdown: () => void;
+    /** Resolved form field name — passed through so Option can write to FormGroup when Select has no FormField wrapper */
+    formName?: string;
 }
 export declare const useSelectContext: () => SelectContextValue<any>;
 export declare const SelectContextProvider: (props: {

package/dist/components/TextArea/TextArea.d.ts

@@ -11,6 +11,9 @@ interface Props extends JSX.TextareaHTMLAttributes<HTMLTextAreaElement> {
         width?: number;
         height?: number;
     };
+    formName?: string;
+    formIndex?: number;
+    formArrayName?: string;
 }
 export declare const TextArea: Component<Props>;
 export default TextArea;

package/dist/index.d.ts

@@ -23,6 +23,8 @@ export { FormArray } from './components/Form/formHelp/formArray';
 export { Form } from './components/Form/form';
 export { FormField } from './components/FormField/formField';
 export { FormGroup, Validators } from './components/Form/formGroup';
+export { useDirectFormBinding } from './components/Form/useDirectFormBinding';
+export { useFormFieldBinding } from './components/Form/useFormFieldBinding';
 export { addTheme } from './tools/tools';
 export { Table } from './components/TableV2/table';
 export { Row } from './components/TableV2/row';
@@ -32,3 +34,4 @@ export { Header } from './components/TableV2/header';
 export { TabBar } from './components/TabV2/tabs';
 export { type StyleContainer } from './components/TableV2/tableProvider';
 export { ColeError as FieldError } from './components/FormField/coleError';
+export * from './globalWindowManager';