@abstraks-dev/ui-library 1.0.1

package/dist/components/Form.js

@@ -0,0 +1,412 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = exports.Form = void 0;
+var _react = _interopRequireWildcard(require("react"));
+var _propTypes = require("prop-types");
+var _accessibility = require("../utils/accessibility.js");
+require("../styles/form.scss");
+function _interopRequireWildcard(e, t) { if ("function" == typeof WeakMap) var r = new WeakMap(), n = new WeakMap(); return (_interopRequireWildcard = function (e, t) { if (!t && e && e.__esModule) return e; var o, i, f = { __proto__: null, default: e }; if (null === e || "object" != typeof e && "function" != typeof e) return f; if (o = t ? n : r) { if (o.has(e)) return o.get(e); o.set(e, f); } for (const t in e) "default" !== t && {}.hasOwnProperty.call(e, t) && ((i = (o = Object.defineProperty) && Object.getOwnPropertyDescriptor(e, t)) && (i.get || i.set) ? o(f, t, i) : f[t] = e[t]); return f; })(e, t); }
+function _extends() { return _extends = Object.assign ? Object.assign.bind() : function (n) { for (var e = 1; e < arguments.length; e++) { var t = arguments[e]; for (var r in t) ({}).hasOwnProperty.call(t, r) && (n[r] = t[r]); } return n; }, _extends.apply(null, arguments); }
+/**
+ * Form - A stateless, accessible form component with validation and error handling
+ *
+	   return (
+			   <Animation fadingEntrances="fadeIn" duration="faster">
+					   <form
+							   ref={ref}
+							   className={`${componentName}-wrapper ${additionalClassName}`.trim()}
+							   aria-label={ariaLabel}
+							   aria-labelledby={ariaLabelledBy}
+							   aria-describedby={ariaDescribedBy}
+							   noValidate={noValidate}
+							   autoComplete={autoComplete}
+							   method={method}
+							   action={action}
+							   encType={encType}
+							   target={target}
+							   acceptCharset={acceptCharset}
+							   role={role}
+							   id={id}
+							   onSubmit={handleSubmit}
+							   {...props}
+					   >
+							   {children}
+					   </form>
+			   </Animation>
+	   );
+ *     }
+ *   }}
+ *   validationMode="onBlur"
+ *   ariaLabel="User registration form"
+ * >
+ *   <FormField name="email" required>
+ *     <TextInput />
+ *   </FormField>
+ *   <Button type="submit">Submit</Button>
+ * </Form>
+ */
+const Form = exports.Form = /*#__PURE__*/(0, _react.forwardRef)(({
+  componentName = 'form',
+  additionalClassName = '',
+  children = null,
+  onSubmit,
+  onChange,
+  onValidate,
+  validationMode = 'onSubmit',
+  noValidate = true,
+  autoComplete = 'on',
+  method = 'post',
+  action = '',
+  encType = 'application/x-www-form-urlencoded',
+  target = '_self',
+  acceptCharset = 'UTF-8',
+  ariaLabel = '',
+  ariaDescribedBy = '',
+  ariaLabelledBy = '',
+  disabled = false,
+  isSubmitting = false,
+  errors = {},
+  resetOnSubmit = false,
+  announceErrors = true,
+  announceSuccess = true,
+  id = '',
+  role = 'form',
+  ...props
+}, ref) => {
+  const [formData, setFormData] = (0, _react.useState)({});
+  const [touched, setTouched] = (0, _react.useState)({});
+  const [localErrors, setLocalErrors] = (0, _react.useState)({});
+  const [submissionCount, setSubmissionCount] = (0, _react.useState)(0);
+
+  // Merge external errors with local errors
+  const allErrors = {
+    ...localErrors,
+    ...errors
+  };
+  const hasErrors = Object.keys(allErrors).length > 0;
+
+  /**
+   * Validates a single field
+   * @param {string} fieldName - Name of the field to validate
+   * @param {*} value - Value to validate
+   * @returns {string|null} Error message or null if valid
+   */
+  const validateField = (0, _react.useCallback)((fieldName, value) => {
+    if (!onValidate) return null;
+    return onValidate(fieldName, value, formData);
+  }, [onValidate, formData]);
+
+  /**
+   * Updates form data and handles validation based on mode
+   */
+  const updateFormData = (0, _react.useCallback)((fieldName, value) => {
+    const newFormData = {
+      ...formData,
+      [fieldName]: value
+    };
+    setFormData(newFormData);
+
+    // Real-time validation for onChange mode
+    if (validationMode === 'onChange' || touched[fieldName]) {
+      const error = validateField(fieldName, value);
+      setLocalErrors(prev => ({
+        ...prev,
+        [fieldName]: error
+      }));
+    }
+    onChange?.(newFormData, fieldName, value);
+  }, [formData, validationMode, touched, validateField, onChange]);
+
+  /**
+   * Handles field blur events for onBlur validation
+   */
+  const handleFieldBlur = (0, _react.useCallback)((fieldName, value) => {
+    setTouched(prev => ({
+      ...prev,
+      [fieldName]: true
+    }));
+    if (validationMode === 'onBlur' || validationMode === 'onChange') {
+      const error = validateField(fieldName, value);
+      setLocalErrors(prev => ({
+        ...prev,
+        [fieldName]: error
+      }));
+
+      // Announce validation errors
+      if (error && announceErrors) {
+        (0, _accessibility.announceToScreenReader)(`${fieldName}: ${error}`, 'assertive');
+      }
+    }
+  }, [validationMode, validateField, announceErrors]);
+
+  /**
+   * Validates all form fields
+   * @returns {Object} Object containing all field errors
+   */
+  const validateAllFields = (0, _react.useCallback)(() => {
+    if (!onValidate) return {};
+    const newErrors = {};
+    Object.keys(formData).forEach(fieldName => {
+      const error = validateField(fieldName, formData[fieldName]);
+      if (error) {
+        newErrors[fieldName] = error;
+      }
+    });
+    return newErrors;
+  }, [formData, validateField, onValidate]);
+
+  /**
+   * Handles form submission
+   */
+  const handleSubmit = (0, _react.useCallback)(async event => {
+    event.preventDefault();
+    if (disabled || isSubmitting) return;
+    setSubmissionCount(prev => prev + 1);
+
+    // Validate all fields on submit
+    const validationErrors = validateAllFields();
+    setLocalErrors(validationErrors);
+    const hasValidationErrors = Object.keys(validationErrors).length > 0;
+    if (hasValidationErrors) {
+      // Focus first error field
+      const firstErrorField = Object.keys(validationErrors)[0];
+      const errorElement = document.querySelector(`[name="${firstErrorField}"]`);
+      if (errorElement) {
+        (0, _accessibility.safeFocus)(errorElement);
+      }
+
+      // Announce validation failure
+      if (announceErrors) {
+        const errorCount = Object.keys(validationErrors).length;
+        (0, _accessibility.announceToScreenReader)(`Form submission failed. ${errorCount} field${errorCount !== 1 ? 's' : ''} ${errorCount !== 1 ? 'have' : 'has'} validation errors.`, 'assertive');
+      }
+      return;
+    }
+    try {
+      // Provide form utilities to onSubmit callback
+      const formUtils = {
+        setErrors: setLocalErrors,
+        setFormData,
+        resetForm: () => {
+          setFormData({});
+          setLocalErrors({});
+          setTouched({});
+        },
+        updateField: updateFormData
+      };
+      await onSubmit?.(formData, formUtils, event);
+
+      // Reset form if requested
+      if (resetOnSubmit) {
+        formUtils.resetForm();
+      }
+
+      // Announce success
+      if (announceSuccess) {
+        (0, _accessibility.announceToScreenReader)('Form submitted successfully', 'polite');
+      }
+    } catch (error) {
+      // Let the onSubmit handler manage errors, but provide fallback
+      logError('Form submission error:', error);
+      if (announceErrors) {
+        (0, _accessibility.announceToScreenReader)('Form submission failed', 'assertive');
+      }
+    }
+  }, [disabled, isSubmitting, validateAllFields, onSubmit, formData, resetOnSubmit, announceSuccess, announceErrors, updateFormData]);
+
+  // Generate comprehensive class names
+  const classNames = [componentName, additionalClassName, disabled && `${componentName}--disabled`, isSubmitting && `${componentName}--submitting`, hasErrors && `${componentName}--has-errors`].filter(Boolean).join(' ');
+
+  // Enhanced children with form context
+  const enhancedChildren = _react.default.Children.map(children, child => {
+    if (/*#__PURE__*/_react.default.isValidElement(child)) {
+      // Check if this is a form field that needs form context
+      const fieldName = child.props?.name || child.props?.setName;
+      if (fieldName) {
+        return /*#__PURE__*/_react.default.cloneElement(child, {
+          error: allErrors[fieldName],
+          errorText: allErrors[fieldName],
+          value: formData[fieldName] || child.props.value || '',
+          inputValue: formData[fieldName] || child.props.inputValue || '',
+          onChangeFunc: event => {
+            const value = event.target?.value !== undefined ? event.target.value : event;
+            updateFormData(fieldName, value);
+            child.props?.onChangeFunc?.(event);
+          },
+          onChange: event => {
+            const value = event.target?.value !== undefined ? event.target.value : event;
+            updateFormData(fieldName, value);
+            child.props?.onChange?.(event);
+          },
+          onBlur: event => {
+            const value = event.target?.value !== undefined ? event.target.value : formData[fieldName];
+            handleFieldBlur(fieldName, value);
+            child.props?.onBlur?.(event);
+          },
+          blur: event => {
+            const value = event.target?.value !== undefined ? event.target.value : formData[fieldName];
+            handleFieldBlur(fieldName, value);
+            child.props?.blur?.(event);
+          },
+          disabled: disabled || child.props?.disabled,
+          'aria-invalid': !!allErrors[fieldName],
+          'aria-describedby': allErrors[fieldName] ? `${fieldName}-error` : child.props?.['aria-describedby'],
+          ...child.props
+        });
+      }
+    }
+    return child;
+  });
+  return /*#__PURE__*/_react.default.createElement("form", _extends({
+    ref: ref,
+    className: classNames,
+    "data-testid": componentName,
+    onSubmit: handleSubmit,
+    noValidate: noValidate,
+    autoComplete: autoComplete,
+    method: method,
+    action: action,
+    encType: encType,
+    target: target,
+    acceptCharset: acceptCharset,
+    "aria-label": ariaLabel || undefined,
+    "aria-labelledby": ariaLabelledBy || undefined,
+    "aria-describedby": ariaDescribedBy || undefined,
+    role: role,
+    "aria-invalid": hasErrors,
+    id: id || undefined
+  }, props), /*#__PURE__*/_react.default.createElement("div", {
+    className: "sr-only",
+    "aria-live": "polite",
+    "aria-atomic": "true"
+  }), enhancedChildren, isSubmitting && /*#__PURE__*/_react.default.createElement("div", {
+    className: "sr-only",
+    "aria-live": "polite"
+  }, "Form is being submitted, please wait..."), hasErrors && /*#__PURE__*/_react.default.createElement("div", {
+    className: `${componentName}__errors-summary`,
+    role: "alert"
+  }, /*#__PURE__*/_react.default.createElement("p", {
+    className: `${componentName}__errors-title`
+  }, "Please correct the following errors:"), /*#__PURE__*/_react.default.createElement("ul", {
+    className: `${componentName}__errors-list`
+  }, Object.entries(allErrors).map(([fieldName, error]) => /*#__PURE__*/_react.default.createElement("li", {
+    key: fieldName,
+    className: `${componentName}__error-item`
+  }, /*#__PURE__*/_react.default.createElement("strong", null, fieldName, ":"), " ", error)))));
+});
+Form.propTypes = {
+  /**
+   * Base CSS class name for the component
+   */
+  componentName: _propTypes.string,
+  /**
+   * Additional CSS class names to apply to the form
+   */
+  additionalClassName: _propTypes.string,
+  /**
+   * Form content and fields
+   */
+  children: _propTypes.node.isRequired,
+  /**
+   * Form submission handler
+   * @param {Object} formData - Current form data
+   * @param {Object} formUtils - Utilities for form management
+   * @param {Event} event - Submit event
+   */
+  onSubmit: _propTypes.func,
+  /**
+   * Form change handler called when any field changes
+   * @param {Object} formData - Current form data
+   * @param {string} fieldName - Name of changed field
+   * @param {*} value - New field value
+   */
+  onChange: _propTypes.func,
+  /**
+   * Field validation function
+   * @param {string} fieldName - Name of field to validate
+   * @param {*} value - Field value
+   * @param {Object} formData - Complete form data
+   * @returns {string|null} Error message or null if valid
+   */
+  onValidate: _propTypes.func,
+  /**
+   * When to perform validation
+   */
+  validationMode: (0, _propTypes.oneOf)(['onSubmit', 'onBlur', 'onChange']),
+  /**
+   * HTML form noValidate attribute
+   */
+  noValidate: _propTypes.bool,
+  /**
+   * HTML form autoComplete attribute
+   */
+  autoComplete: _propTypes.string,
+  /**
+   * HTML form method attribute
+   */
+  method: (0, _propTypes.oneOf)(['get', 'post', 'dialog']),
+  /**
+   * HTML form action attribute
+   */
+  action: _propTypes.string,
+  /**
+   * HTML form encType attribute
+   */
+  encType: (0, _propTypes.oneOf)(['application/x-www-form-urlencoded', 'multipart/form-data', 'text/plain']),
+  /**
+   * HTML form target attribute
+   */
+  target: (0, _propTypes.oneOf)(['_self', '_blank', '_parent', '_top']),
+  /**
+   * HTML form acceptCharset attribute
+   */
+  acceptCharset: _propTypes.string,
+  /**
+   * Accessible label for the form
+   */
+  ariaLabel: _propTypes.string,
+  /**
+   * ID of element that describes the form
+   */
+  ariaDescribedBy: _propTypes.string,
+  /**
+   * ID of element that labels the form
+   */
+  ariaLabelledBy: _propTypes.string,
+  /**
+   * Whether the entire form is disabled
+   */
+  disabled: _propTypes.bool,
+  /**
+   * Whether the form is currently being submitted
+   */
+  isSubmitting: _propTypes.bool,
+  /**
+   * External errors object (field name: error message)
+   */
+  errors: _propTypes.object,
+  /**
+   * Whether to reset form data after successful submission
+   */
+  resetOnSubmit: _propTypes.bool,
+  /**
+   * Whether to announce errors to screen readers
+   */
+  announceErrors: _propTypes.bool,
+  /**
+   * Whether to announce successful submissions to screen readers
+   */
+  announceSuccess: _propTypes.bool,
+  /**
+   * HTML id attribute for the form
+   */
+  id: _propTypes.string,
+  /**
+   * ARIA role for the form
+   */
+  role: _propTypes.string
+};
+var _default = exports.default = Form;