@proyecto-viviana/solid-stately 0.2.2 → 0.2.4

package/src/form/createFormValidationState.d.ts

@@ -0,0 +1,100 @@
+/**
+ * createFormValidationState for solid-stately
+ *
+ * Manages form validation state including realtime and displayed validation results.
+ * Supports both ARIA (live) and native (on submit) validation behaviors.
+ *
+ * Port of react-stately's useFormValidationState.
+ */
+import { type Accessor } from 'solid-js';
+/** Standard HTML ValidityState interface. */
+export interface ValidityState {
+    badInput: boolean;
+    customError: boolean;
+    patternMismatch: boolean;
+    rangeOverflow: boolean;
+    rangeUnderflow: boolean;
+    stepMismatch: boolean;
+    tooLong: boolean;
+    tooShort: boolean;
+    typeMismatch: boolean;
+    valueMissing: boolean;
+    valid: boolean;
+}
+/** Result of validation. */
+export interface ValidationResult {
+    /** Whether the value is invalid. */
+    isInvalid: boolean;
+    /** Details about which validation constraints failed. */
+    validationDetails: ValidityState;
+    /** Error messages to display. */
+    validationErrors: string[];
+}
+/** Map of field names to their validation errors. */
+export type ValidationErrors = Record<string, string | string[]>;
+/** Validation function that returns error messages or true/false. */
+export type ValidationFunction<T> = (value: T) => boolean | string | string[] | null | undefined;
+/** Validation behavior mode. */
+export type ValidationBehavior = 'aria' | 'native';
+export interface FormValidationProps<T> {
+    /** Whether the value is invalid (controlled). */
+    isInvalid?: boolean;
+    /** @deprecated Use isInvalid instead. */
+    validationState?: 'valid' | 'invalid';
+    /** Custom validation function. */
+    validate?: ValidationFunction<T>;
+    /** Validation behavior: 'aria' for realtime, 'native' for on submit. */
+    validationBehavior?: ValidationBehavior;
+    /** Built-in validation result from native input. */
+    builtinValidation?: ValidationResult;
+    /** Field name(s) for server error lookup. */
+    name?: string | string[];
+    /** Current field value. */
+    value: T | null;
+}
+export interface FormValidationState {
+    /** Realtime validation results, updated as the user edits the value. */
+    realtimeValidation: Accessor<ValidationResult>;
+    /** Currently displayed validation results, updated when the user commits their changes. */
+    displayValidation: Accessor<ValidationResult>;
+    /** Updates the current validation result. Not displayed to the user until `commitValidation` is called. */
+    updateValidation(result: ValidationResult): void;
+    /** Resets the displayed validation state to valid when the user resets the form. */
+    resetValidation(): void;
+    /** Commits the realtime validation so it is displayed to the user. */
+    commitValidation(): void;
+}
+/** A valid validity state. */
+export declare const VALID_VALIDITY_STATE: ValidityState;
+/** Default validation result (valid). */
+export declare const DEFAULT_VALIDATION_RESULT: ValidationResult;
+/** Context for server-side validation errors. */
+export declare const FormValidationContext: import("solid-js").Context<ValidationErrors>;
+/** Private prop key for passing validation state to children. */
+export declare const privateValidationStateProp: string;
+/**
+ * Creates form validation state for a field.
+ *
+ * @example
+ * ```tsx
+ * const validationState = createFormValidationState({
+ *   value: inputValue(),
+ *   validate: (value) => {
+ *     if (!value) return 'This field is required';
+ *     if (value.length < 3) return 'Must be at least 3 characters';
+ *     return null;
+ *   },
+ *   validationBehavior: 'aria',
+ * });
+ *
+ * // Access validation state
+ * const isInvalid = () => validationState.displayValidation().isInvalid;
+ * const errors = () => validationState.displayValidation().validationErrors;
+ * ```
+ */
+export declare function createFormValidationState<T>(props: FormValidationProps<T>): FormValidationState;
+/**
+ * Merges multiple validation results into one.
+ */
+export declare function mergeValidation(...results: ValidationResult[]): ValidationResult;
+//# sourceMappingURL=createFormValidationState.d.ts.map

package/src/form/createFormValidationState.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createFormValidationState.d.ts","sourceRoot":"","sources":["createFormValidationState.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EACL,KAAK,QAAQ,EAMd,MAAM,UAAU,CAAC;AAMlB,6CAA6C;AAC7C,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,OAAO,CAAC;IAClB,WAAW,EAAE,OAAO,CAAC;IACrB,eAAe,EAAE,OAAO,CAAC;IACzB,aAAa,EAAE,OAAO,CAAC;IACvB,cAAc,EAAE,OAAO,CAAC;IACxB,YAAY,EAAE,OAAO,CAAC;IACtB,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,OAAO,CAAC;IAClB,YAAY,EAAE,OAAO,CAAC;IACtB,YAAY,EAAE,OAAO,CAAC;IACtB,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,4BAA4B;AAC5B,MAAM,WAAW,gBAAgB;IAC/B,oCAAoC;IACpC,SAAS,EAAE,OAAO,CAAC;IACnB,yDAAyD;IACzD,iBAAiB,EAAE,aAAa,CAAC;IACjC,iCAAiC;IACjC,gBAAgB,EAAE,MAAM,EAAE,CAAC;CAC5B;AAED,qDAAqD;AACrD,MAAM,MAAM,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC;AAEjE,qEAAqE;AACrE,MAAM,MAAM,kBAAkB,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,KAAK,OAAO,GAAG,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI,GAAG,SAAS,CAAC;AAEjG,gCAAgC;AAChC,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG,QAAQ,CAAC;AAEnD,MAAM,WAAW,mBAAmB,CAAC,CAAC;IACpC,iDAAiD;IACjD,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,yCAAyC;IACzC,eAAe,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACtC,kCAAkC;IAClC,QAAQ,CAAC,EAAE,kBAAkB,CAAC,CAAC,CAAC,CAAC;IACjC,wEAAwE;IACxE,kBAAkB,CAAC,EAAE,kBAAkB,CAAC;IACxC,oDAAoD;IACpD,iBAAiB,CAAC,EAAE,gBAAgB,CAAC;IACrC,6CAA6C;IAC7C,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACzB,2BAA2B;IAC3B,KAAK,EAAE,CAAC,GAAG,IAAI,CAAC;CACjB;AAED,MAAM,WAAW,mBAAmB;IAClC,wEAAwE;IACxE,kBAAkB,EAAE,QAAQ,CAAC,gBAAgB,CAAC,CAAC;IAC/C,2FAA2F;IAC3F,iBAAiB,EAAE,QAAQ,CAAC,gBAAgB,CAAC,CAAC;IAC9C,2GAA2G;IAC3G,gBAAgB,CAAC,MAAM,EAAE,gBAAgB,GAAG,IAAI,CAAC;IACjD,oFAAoF;IACpF,eAAe,IAAI,IAAI,CAAC;IACxB,sEAAsE;IACtE,gBAAgB,IAAI,IAAI,CAAC;CAC1B;AAMD,8BAA8B;AAC9B,eAAO,MAAM,oBAAoB,EAAE,aAYlC,CAAC;AASF,yCAAyC;AACzC,eAAO,MAAM,yBAAyB,EAAE,gBAIvC,CAAC;AAMF,iDAAiD;AACjD,eAAO,MAAM,qBAAqB,8CAAsC,CAAC;AAEzE,iEAAiE;AACjE,eAAO,MAAM,0BAA0B,QAAuC,CAAC;AAwD/E;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,yBAAyB,CAAC,CAAC,EACzC,KAAK,EAAE,mBAAmB,CAAC,CAAC,CAAC,GAC5B,mBAAmB,CAwJrB;AAED;;GAEG;AACH,wBAAgB,eAAe,CAC7B,GAAG,OAAO,EAAE,gBAAgB,EAAE,GAC7B,gBAAgB,CAwBlB"}

package/src/form/createFormValidationState.ts

@@ -0,0 +1,389 @@
+/**
+ * createFormValidationState for solid-stately
+ *
+ * Manages form validation state including realtime and displayed validation results.
+ * Supports both ARIA (live) and native (on submit) validation behaviors.
+ *
+ * Port of react-stately's useFormValidationState.
+ */
+
+import {
+  type Accessor,
+  createContext,
+  createEffect,
+  createMemo,
+  createSignal,
+  useContext,
+} from 'solid-js';
+
+// ============================================
+// TYPES
+// ============================================
+
+/** Standard HTML ValidityState interface. */
+export interface ValidityState {
+  badInput: boolean;
+  customError: boolean;
+  patternMismatch: boolean;
+  rangeOverflow: boolean;
+  rangeUnderflow: boolean;
+  stepMismatch: boolean;
+  tooLong: boolean;
+  tooShort: boolean;
+  typeMismatch: boolean;
+  valueMissing: boolean;
+  valid: boolean;
+}
+
+/** Result of validation. */
+export interface ValidationResult {
+  /** Whether the value is invalid. */
+  isInvalid: boolean;
+  /** Details about which validation constraints failed. */
+  validationDetails: ValidityState;
+  /** Error messages to display. */
+  validationErrors: string[];
+}
+
+/** Map of field names to their validation errors. */
+export type ValidationErrors = Record<string, string | string[]>;
+
+/** Validation function that returns error messages or true/false. */
+export type ValidationFunction<T> = (value: T) => boolean | string | string[] | null | undefined;
+
+/** Validation behavior mode. */
+export type ValidationBehavior = 'aria' | 'native';
+
+export interface FormValidationProps<T> {
+  /** Whether the value is invalid (controlled). */
+  isInvalid?: boolean;
+  /** @deprecated Use isInvalid instead. */
+  validationState?: 'valid' | 'invalid';
+  /** Custom validation function. */
+  validate?: ValidationFunction<T>;
+  /** Validation behavior: 'aria' for realtime, 'native' for on submit. */
+  validationBehavior?: ValidationBehavior;
+  /** Built-in validation result from native input. */
+  builtinValidation?: ValidationResult;
+  /** Field name(s) for server error lookup. */
+  name?: string | string[];
+  /** Current field value. */
+  value: T | null;
+}
+
+export interface FormValidationState {
+  /** Realtime validation results, updated as the user edits the value. */
+  realtimeValidation: Accessor<ValidationResult>;
+  /** Currently displayed validation results, updated when the user commits their changes. */
+  displayValidation: Accessor<ValidationResult>;
+  /** Updates the current validation result. Not displayed to the user until `commitValidation` is called. */
+  updateValidation(result: ValidationResult): void;
+  /** Resets the displayed validation state to valid when the user resets the form. */
+  resetValidation(): void;
+  /** Commits the realtime validation so it is displayed to the user. */
+  commitValidation(): void;
+}
+
+// ============================================
+// CONSTANTS
+// ============================================
+
+/** A valid validity state. */
+export const VALID_VALIDITY_STATE: ValidityState = {
+  badInput: false,
+  customError: false,
+  patternMismatch: false,
+  rangeOverflow: false,
+  rangeUnderflow: false,
+  stepMismatch: false,
+  tooLong: false,
+  tooShort: false,
+  typeMismatch: false,
+  valueMissing: false,
+  valid: true,
+};
+
+/** A custom error validity state. */
+const CUSTOM_VALIDITY_STATE: ValidityState = {
+  ...VALID_VALIDITY_STATE,
+  customError: true,
+  valid: false,
+};
+
+/** Default validation result (valid). */
+export const DEFAULT_VALIDATION_RESULT: ValidationResult = {
+  isInvalid: false,
+  validationDetails: VALID_VALIDITY_STATE,
+  validationErrors: [],
+};
+
+// ============================================
+// CONTEXT
+// ============================================
+
+/** Context for server-side validation errors. */
+export const FormValidationContext = createContext<ValidationErrors>({});
+
+/** Private prop key for passing validation state to children. */
+export const privateValidationStateProp = '__formValidationState' + Date.now();
+
+// ============================================
+// HELPERS
+// ============================================
+
+function asArray<T>(v: T | T[] | undefined): T[] {
+  if (!v) {
+    return [];
+  }
+  return Array.isArray(v) ? v : [v];
+}
+
+function runValidate<T>(validate: ValidationFunction<T>, value: T): string[] {
+  if (typeof validate === 'function') {
+    const e = validate(value);
+    if (e && typeof e !== 'boolean') {
+      return asArray(e);
+    }
+  }
+  return [];
+}
+
+function getValidationResult(errors: string[]): ValidationResult | null {
+  return errors.length
+    ? {
+        isInvalid: true,
+        validationErrors: errors,
+        validationDetails: CUSTOM_VALIDITY_STATE,
+      }
+    : null;
+}
+
+function isEqualValidation(
+  a: ValidationResult | null,
+  b: ValidationResult | null
+): boolean {
+  if (a === b) {
+    return true;
+  }
+  return (
+    !!a &&
+    !!b &&
+    a.isInvalid === b.isInvalid &&
+    a.validationErrors.length === b.validationErrors.length &&
+    a.validationErrors.every((ae, i) => ae === b.validationErrors[i]) &&
+    Object.entries(a.validationDetails).every(
+      ([k, v]) => b.validationDetails[k as keyof ValidityState] === v
+    )
+  );
+}
+
+// ============================================
+// HOOK
+// ============================================
+
+/**
+ * Creates form validation state for a field.
+ *
+ * @example
+ * ```tsx
+ * const validationState = createFormValidationState({
+ *   value: inputValue(),
+ *   validate: (value) => {
+ *     if (!value) return 'This field is required';
+ *     if (value.length < 3) return 'Must be at least 3 characters';
+ *     return null;
+ *   },
+ *   validationBehavior: 'aria',
+ * });
+ *
+ * // Access validation state
+ * const isInvalid = () => validationState.displayValidation().isInvalid;
+ * const errors = () => validationState.displayValidation().validationErrors;
+ * ```
+ */
+export function createFormValidationState<T>(
+  props: FormValidationProps<T>
+): FormValidationState {
+  const {
+    isInvalid,
+    validationState,
+    name,
+    builtinValidation: builtinValidationProp,
+    validate,
+    validationBehavior = 'aria',
+  } = props;
+
+  // Backward compatibility
+  const isInvalidProp = createMemo(
+    () => isInvalid ?? (validationState === 'invalid' ? true : undefined)
+  );
+
+  // Controlled error from isInvalid prop
+  const controlledError = createMemo<ValidationResult | null>(() =>
+    isInvalidProp() !== undefined
+      ? {
+          isInvalid: isInvalidProp()!,
+          validationErrors: [],
+          validationDetails: CUSTOM_VALIDITY_STATE,
+        }
+      : null
+  );
+
+  // Client-side validation
+  const clientError = createMemo<ValidationResult | null>(() => {
+    if (!validate || props.value == null) {
+      return null;
+    }
+    const validateErrors = runValidate(validate, props.value);
+    return getValidationResult(validateErrors);
+  });
+
+  // Built-in validation (skip if valid)
+  const builtinValidation = createMemo<ValidationResult | undefined>(() => {
+    if (builtinValidationProp?.validationDetails.valid) {
+      return undefined;
+    }
+    return builtinValidationProp;
+  });
+
+  // Server errors from context
+  const serverErrors = useContext(FormValidationContext);
+  const serverErrorMessages = createMemo(() => {
+    if (name) {
+      return Array.isArray(name)
+        ? name.flatMap((n) => asArray(serverErrors[n]))
+        : asArray(serverErrors[name]);
+    }
+    return [];
+  });
+
+  // Track server errors clearing
+  const [lastServerErrors, setLastServerErrors] = createSignal(serverErrors);
+  const [isServerErrorCleared, setServerErrorCleared] = createSignal(false);
+
+  createEffect(() => {
+    if (serverErrors !== lastServerErrors()) {
+      setLastServerErrors(serverErrors);
+      setServerErrorCleared(false);
+    }
+  });
+
+  const serverError = createMemo<ValidationResult | null>(() =>
+    getValidationResult(isServerErrorCleared() ? [] : serverErrorMessages())
+  );
+
+  // Track validation state
+  const [currentValidity, setCurrentValidity] = createSignal(
+    DEFAULT_VALIDATION_RESULT
+  );
+  const [commitQueued, setCommitQueued] = createSignal(false);
+
+  let nextValidation = DEFAULT_VALIDATION_RESULT;
+  let lastError = DEFAULT_VALIDATION_RESULT;
+
+  // Commit validation effect
+  createEffect(() => {
+    if (!commitQueued()) {
+      return;
+    }
+    setCommitQueued(false);
+    const error = clientError() || builtinValidation() || nextValidation;
+    if (!isEqualValidation(error, lastError)) {
+      lastError = error;
+      setCurrentValidity(error);
+    }
+  });
+
+  // Realtime validation (for native input state)
+  const realtimeValidation = createMemo<ValidationResult>(
+    () =>
+      controlledError() ||
+      serverError() ||
+      clientError() ||
+      builtinValidation() ||
+      DEFAULT_VALIDATION_RESULT
+  );
+
+  // Display validation (what the user sees)
+  const displayValidation = createMemo<ValidationResult>(() => {
+    if (validationBehavior === 'native') {
+      return (
+        controlledError() || serverError() || currentValidity()
+      );
+    }
+    return (
+      controlledError() ||
+      serverError() ||
+      clientError() ||
+      builtinValidation() ||
+      currentValidity()
+    );
+  });
+
+  return {
+    realtimeValidation,
+    displayValidation,
+    updateValidation(value: ValidationResult) {
+      // If validationBehavior is 'aria', update in realtime. Otherwise, store until commit.
+      if (
+        validationBehavior === 'aria' &&
+        !isEqualValidation(currentValidity(), value)
+      ) {
+        setCurrentValidity(value);
+      } else {
+        nextValidation = value;
+      }
+    },
+    resetValidation() {
+      // Update the currently displayed validation state to valid on form reset.
+      const error = DEFAULT_VALIDATION_RESULT;
+      if (!isEqualValidation(error, lastError)) {
+        lastError = error;
+        setCurrentValidity(error);
+      }
+      // Do not commit validation after the next render for native behavior.
+      if (validationBehavior === 'native') {
+        setCommitQueued(false);
+      }
+      setServerErrorCleared(true);
+    },
+    commitValidation() {
+      // Commit validation state so the user sees it on blur/change/submit.
+      if (validationBehavior === 'native') {
+        setCommitQueued(true);
+      }
+      setServerErrorCleared(true);
+    },
+  };
+}
+
+/**
+ * Merges multiple validation results into one.
+ */
+export function mergeValidation(
+  ...results: ValidationResult[]
+): ValidationResult {
+  const errors = new Set<string>();
+  let isInvalid = false;
+  const validationDetails: ValidityState = { ...VALID_VALIDITY_STATE };
+
+  for (const v of results) {
+    for (const e of v.validationErrors) {
+      errors.add(e);
+    }
+    isInvalid = isInvalid || v.isInvalid;
+    for (const key in validationDetails) {
+      const k = key as keyof ValidityState;
+      (validationDetails as unknown as Record<string, boolean>)[k] =
+        (validationDetails as unknown as Record<string, boolean>)[k] ||
+        (v.validationDetails as unknown as Record<string, boolean>)[k];
+    }
+  }
+
+  validationDetails.valid = !isInvalid;
+  return {
+    isInvalid,
+    validationErrors: [...errors],
+    validationDetails,
+  };
+}

package/src/form/index.d.ts

@@ -0,0 +1,2 @@
+export { createFormValidationState, mergeValidation, FormValidationContext, privateValidationStateProp, VALID_VALIDITY_STATE, DEFAULT_VALIDATION_RESULT, type FormValidationState, type FormValidationProps, type ValidationResult, type ValidationErrors, type ValidationFunction, type ValidationBehavior, type ValidityState, } from './createFormValidationState';
+//# sourceMappingURL=index.d.ts.map

package/src/form/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,yBAAyB,EACzB,eAAe,EACf,qBAAqB,EACrB,0BAA0B,EAC1B,oBAAoB,EACpB,yBAAyB,EACzB,KAAK,mBAAmB,EACxB,KAAK,mBAAmB,EACxB,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACvB,KAAK,aAAa,GACnB,MAAM,6BAA6B,CAAC"}

package/src/form/index.ts

@@ -0,0 +1,15 @@
+export {
+  createFormValidationState,
+  mergeValidation,
+  FormValidationContext,
+  privateValidationStateProp,
+  VALID_VALIDITY_STATE,
+  DEFAULT_VALIDATION_RESULT,
+  type FormValidationState,
+  type FormValidationProps,
+  type ValidationResult,
+  type ValidationErrors,
+  type ValidationFunction,
+  type ValidationBehavior,
+  type ValidityState,
+} from './createFormValidationState';

package/src/grid/createGridState.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Grid state management for Table and GridList components.
+ * Based on @react-stately/grid/useGridState.
+ */
+import { type Accessor } from 'solid-js';
+import type { GridState, GridStateOptions, GridCollection } from './types';
+/**
+ * Creates state management for a grid component.
+ * Handles row selection, focus management, and keyboard navigation state.
+ */
+export declare function createGridState<T extends object, C extends GridCollection<T> = GridCollection<T>>(options: Accessor<GridStateOptions<T, C>>): GridState<T, C>;
+//# sourceMappingURL=createGridState.d.ts.map

package/src/grid/createGridState.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createGridState.d.ts","sourceRoot":"","sources":["createGridState.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAA8C,KAAK,QAAQ,EAAE,MAAM,UAAU,CAAC;AACrF,OAAO,KAAK,EACV,SAAS,EACT,gBAAgB,EAChB,cAAc,EAEf,MAAM,SAAS,CAAC;AAGjB;;;GAGG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,cAAc,CAAC,CAAC,CAAC,GAAG,cAAc,CAAC,CAAC,CAAC,EAC/F,OAAO,EAAE,QAAQ,CAAC,gBAAgB,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GACxC,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,CAuSjB"}