@fpkit/acss 0.5.13 → 0.6.1

package/src/components/form/form.tsx

@@ -1,71 +1,212 @@
-import UI from '#components/fp'
-import React from 'react'
+import UI from "#components/ui";
+import React from "react";
 
-import Input from './inputs'
-import Field from './fields'
-import Select from './select'
-import Textarea from './textarea'
+import Input from "./inputs";
+import Field from "./fields";
+import Select from "./select";
+import Textarea from "./textarea";
 
-export type FormProps = Partial<React.ComponentProps<typeof UI>> &
-  React.ComponentProps<'form'>
+/**
+ * Form submission status type
+ */
+export type FormStatus = "idle" | "submitting" | "success" | "error";
+
+/**
+ * Form component props interface
+ * @interface FormProps
+ * @extends {React.ComponentProps<'form'>}
+ */
+export interface FormProps
+  extends Omit<React.ComponentProps<"form">, "className"> {
+  /**
+   * Unique identifier for the form
+   */
+  id?: string;
+  /**
+   * Name attribute for the form
+   */
+  name?: string;
+  /**
+   * Inline CSS styles object
+   */
+  styles?: React.CSSProperties;
+  /**
+   * CSS class names (preferred over 'className' for consistency with fpkit components)
+   */
+  classes?: string;
+  /**
+   * Form submission action URL
+   */
+  action?: string;
+  /**
+   * HTTP method for form submission
+   * @default 'post'
+   */
+  formMethod?: "get" | "post";
+  /**
+   * Form submission handler - prevents default browser submission
+   * @param {React.FormEvent<HTMLFormElement>} event - Form submit event
+   */
+  onSubmit?: (event: React.FormEvent<HTMLFormElement>) => void;
+  /**
+   * Target for form submission (_blank, _self, _parent, _top)
+   */
+  target?: string;
+  /**
+   * Disable HTML5 validation
+   * @default false
+   */
+  noValidate?: boolean;
+  /**
+   * Current form status for accessibility and styling
+   * @default 'idle'
+   */
+  status?: FormStatus;
+  /**
+   * Accessible name for the form
+   * RECOMMENDED when multiple forms exist on the same page to help screen reader users distinguish between them.
+   * Use descriptive labels like "Contact form", "Login form", "Search form"
+   * @example "Contact form"
+   * @see {@link https://www.w3.org/WAI/WCAG21/Understanding/headings-and-labels.html|WCAG 2.4.6 Headings and Labels}
+   */
+  "aria-label"?: string;
+  /**
+   * ID of element that labels the form
+   * Alternative to aria-label. Use when a visible heading already labels the form.
+   * @example "contact-form-title"
+   * @see {@link https://www.w3.org/WAI/WCAG21/Understanding/headings-and-labels.html|WCAG 2.4.6 Headings and Labels}
+   */
+  "aria-labelledby"?: string;
+  /**
+   * Child elements (form fields, buttons, etc.)
+   */
+  children: React.ReactNode;
+}
 
 /**
- * Form component
- * @param {Object} props - Form component props
- * @param {string} [id] - Unique identifier for form
- * @param {string} [name] - Name for form
- * @param {Object} [styles] - Inline styles
- * @param {string} [classes] - Additional classes
- * @param {ReactNode} children - Child elements
- * @param {string} [action] - Form action URL
- * @param {('get'|'post')} [formMethod='post'] - Form method
- * @param {Function} [onSubmit] - Submit callback
- * @param {string} [target] - Form submit target
- * @param {boolean} [noValidate=false] - Disable validation
- * @param {Object} ...props - Additional props
+ * Form component - Accessible HTML form wrapper with validation support
+ *
+ * A flexible form component that provides proper ARIA attributes, form submission
+ * handling, and validation state management. Supports both controlled and uncontrolled
+ * form patterns, with status management for loading states and error handling.
+ *
+ * @component
+ * @example
+ * // Basic form with validation
+ * <Form onSubmit={handleSubmit} aria-label="Contact form">
+ *   <Form.Field label="Name" labelFor="name" required>
+ *     <Form.Input id="name" name="name" required />
+ *   </Form.Field>
+ *   <button type="submit">Submit</button>
+ * </Form>
+ *
+ * @example
+ * // Form with loading state
+ * <Form
+ *   status={isSubmitting ? 'submitting' : 'idle'}
+ *   onSubmit={handleSubmit}
+ * >
+ *   <Form.Field label="Email" labelFor="email">
+ *     <Form.Input id="email" type="email" disabled={isSubmitting} />
+ *   </Form.Field>
+ *   <button type="submit" disabled={isSubmitting}>
+ *     {isSubmitting ? 'Submitting...' : 'Submit'}
+ *   </button>
+ * </Form>
+ *
+ * @example
+ * // Uncontrolled form with native submission
+ * <Form action="/api/contact" formMethod="post">
+ *   <Form.Field label="Message" labelFor="message">
+ *     <Form.Textarea id="message" name="message" required />
+ *   </Form.Field>
+ *   <button type="submit">Send</button>
+ * </Form>
+ *
+ * @param {FormProps} props - Component props
+ * @returns {JSX.Element} Form element with proper accessibility attributes
+ *
+ * @see {@link https://www.w3.org/WAI/WCAG21/Understanding/name-role-value.html|WCAG 4.1.2 Name, Role, Value}
+ * @see {@link https://www.w3.org/WAI/WCAG21/Understanding/error-identification.html|WCAG 3.3.1 Error Identification}
  */
-export const Form = ({
-  id,
-  name,
-  styles,
-  classes,
-  children,
-  action,
-  formMethod,
-  onSubmit,
-  target,
-  noValidate,
-  ...props
-}: FormProps) => {
-  const onSubmitCallback = (e: React.FormEvent<HTMLFormElement>) => {
-    if (onSubmit) {
-      e.preventDefault()
-      onSubmit?.(e)
-    }
+export const Form = React.forwardRef<HTMLFormElement, FormProps>(
+  (
+    {
+      id,
+      name,
+      styles,
+      classes,
+      children,
+      action,
+      formMethod = "post",
+      onSubmit,
+      target,
+      noValidate = false,
+      status = "idle",
+      ...props
+    },
+    ref: React.ForwardedRef<HTMLFormElement>
+  ) => {
+    /**
+     * Form submission handler
+     * Prevents default browser submission only when onSubmit handler is provided
+     * @param {React.FormEvent<HTMLFormElement>} event - Form submit event
+     */
+    const handleSubmit = (event: React.FormEvent<HTMLFormElement>) => {
+      if (onSubmit) {
+        event.preventDefault();
+        onSubmit(event);
+      }
+      // If no onSubmit handler, allow native form submission
+    };
+
+    // Determine if form is busy (submitting)
+    const isBusy = status === "submitting";
+
+    return (
+      <UI
+        as="form"
+        // @ts-expect-error - ForwardedRef includes legacy string refs in its type union,
+        // but modern React (18+) and our polymorphic types correctly exclude them.
+        // String refs are deprecated and will not be passed at runtime.
+        ref={ref}
+        id={id}
+        name={name}
+        className={classes}
+        styles={styles}
+        action={action}
+        method={formMethod}
+        onSubmit={handleSubmit}
+        target={target}
+        noValidate={noValidate}
+        // Accessibility attributes
+        aria-busy={isBusy}
+        // Data attribute for CSS styling hooks
+        data-status={status}
+        {...props}
+      >
+        {children}
+      </UI>
+    );
   }
+);
 
-  return (
-    <UI
-      as="form"
-      id={id}
-      name={name}
-      className={classes}
-      styles={styles}
-      action={action}
-      novalidate={noValidate}
-      method={formMethod}
-      onSubmit={onSubmitCallback}
-      target={target}
-      {...props}
-    >
-      {children}
-    </UI>
-  )
-}
+// Compound component type with sub-components
+type FormComponent = typeof Form & {
+  Field: typeof Field;
+  Input: typeof Input;
+  Select: typeof Select;
+  Textarea: typeof Textarea;
+};
+
+// Display name for React DevTools
+Form.displayName = "Form";
+
+// Compound component pattern - attach sub-components with proper typing
+const FormWithSubComponents = Form as FormComponent;
+FormWithSubComponents.Field = Field;
+FormWithSubComponents.Input = Input;
+FormWithSubComponents.Select = Select;
+FormWithSubComponents.Textarea = Textarea;
 
-export default Form
-Form.displayName = 'Form'
-Form.Field = Field
-Form.Input = Input
-Form.Select = Select
-Form.Textarea = Textarea
+export default FormWithSubComponents;

package/src/components/form/form.types.ts

@@ -0,0 +1,378 @@
+import React from 'react'
+
+/**
+ * Validation state for form inputs
+ */
+export type ValidationState = 'valid' | 'invalid' | 'none'
+
+/**
+ * Input component props interface
+ * Extends native HTML input props with custom validation and accessibility features
+ *
+ * @interface InputProps
+ */
+export interface InputProps extends Omit<React.ComponentPropsWithoutRef<'input'>, 'className'> {
+  /**
+   * Input type attribute
+   * @default 'text'
+   */
+  type?: React.HTMLInputTypeAttribute
+
+  /**
+   * Unique identifier for the input element
+   */
+  id?: string
+
+  /**
+   * Name attribute for form submission
+   */
+  name?: string
+
+  /**
+   * Controlled value
+   */
+  value?: string | number | readonly string[]
+
+  /**
+   * Uncontrolled default value
+   */
+  defaultValue?: string | number | readonly string[]
+
+  /**
+   * Placeholder text
+   */
+  placeholder?: string
+
+  /**
+   * CSS class names (preferred over 'className' for consistency with fpkit components)
+   */
+  classes?: string
+
+  /**
+   * Inline CSS styles object
+   */
+  styles?: React.CSSProperties
+
+  /**
+   * Disabled state (standard prop)
+   */
+  disabled?: boolean
+
+  /**
+   * Disabled state (legacy support)
+   * @deprecated Use `disabled` instead
+   */
+  isDisabled?: boolean
+
+  /**
+   * Read-only state
+   */
+  readOnly?: boolean
+
+  /**
+   * Required field indicator
+   * @default false
+   */
+  required?: boolean
+
+  /**
+   * Current validation state for styling and accessibility
+   * @default 'none'
+   */
+  validationState?: ValidationState
+
+  /**
+   * Error message to display and link via aria-describedby
+   */
+  errorMessage?: string
+
+  /**
+   * Hint text to display and link via aria-describedby
+   */
+  hintText?: string
+
+  /**
+   * Maximum character length
+   */
+  maxLength?: number
+
+  /**
+   * Minimum character length
+   */
+  minLength?: number
+
+  /**
+   * Validation pattern regex
+   */
+  pattern?: string
+
+  /**
+   * Autocomplete attribute for browser autofill
+   */
+  autoComplete?: string
+
+  /**
+   * Auto-focus on mount
+   * @default false
+   */
+  autoFocus?: boolean
+
+  /**
+   * Input mode for virtual keyboards
+   */
+  inputMode?: 'none' | 'text' | 'decimal' | 'numeric' | 'tel' | 'search' | 'email' | 'url'
+
+  /**
+   * Change event handler
+   */
+  onChange?: React.ChangeEventHandler<HTMLInputElement>
+
+  /**
+   * Blur event handler
+   */
+  onBlur?: React.FocusEventHandler<HTMLInputElement>
+
+  /**
+   * Focus event handler
+   */
+  onFocus?: React.FocusEventHandler<HTMLInputElement>
+
+  /**
+   * Key down event handler
+   */
+  onKeyDown?: React.KeyboardEventHandler<HTMLInputElement>
+
+  /**
+   * Accessibility handler for Enter key press
+   * Enables keyboard-only users to trigger actions without requiring mouse interaction
+   * @param {React.KeyboardEvent<HTMLInputElement>} event - Keyboard event
+   *
+   * @see {@link https://www.w3.org/WAI/WCAG21/Understanding/keyboard.html|WCAG 2.1.1 Keyboard}
+   */
+  onEnter?: (event: React.KeyboardEvent<HTMLInputElement>) => void
+}
+
+/**
+ * Textarea component props interface
+ * Extends native HTML textarea props with custom validation and accessibility features
+ *
+ * @interface TextareaProps
+ */
+export interface TextareaProps extends Omit<React.ComponentPropsWithoutRef<'textarea'>, 'className'> {
+  /**
+   * Unique identifier for the textarea element
+   */
+  id?: string
+
+  /**
+   * Name attribute for form submission
+   */
+  name?: string
+
+  /**
+   * Controlled value
+   */
+  value?: string | number | readonly string[]
+
+  /**
+   * Uncontrolled default value
+   */
+  defaultValue?: string | number | readonly string[]
+
+  /**
+   * Placeholder text
+   */
+  placeholder?: string
+
+  /**
+   * CSS class names (preferred over 'className' for consistency with fpkit components)
+   */
+  classes?: string
+
+  /**
+   * Inline CSS styles object
+   */
+  styles?: React.CSSProperties
+
+  /**
+   * Number of visible text rows
+   * @default 5
+   */
+  rows?: number
+
+  /**
+   * Number of visible text columns
+   * @default 25
+   */
+  cols?: number
+
+  /**
+   * Disabled state
+   */
+  disabled?: boolean
+
+  /**
+   * Read-only state
+   */
+  readOnly?: boolean
+
+  /**
+   * Required field indicator
+   * @default false
+   */
+  required?: boolean
+
+  /**
+   * Current validation state for styling and accessibility
+   * @default 'none'
+   */
+  validationState?: ValidationState
+
+  /**
+   * Error message to display and link via aria-describedby
+   */
+  errorMessage?: string
+
+  /**
+   * Hint text to display and link via aria-describedby
+   */
+  hintText?: string
+
+  /**
+   * Change event handler
+   */
+  onChange?: React.ChangeEventHandler<HTMLTextAreaElement>
+
+  /**
+   * Blur event handler
+   */
+  onBlur?: React.FocusEventHandler<HTMLTextAreaElement>
+
+  /**
+   * Focus event handler
+   */
+  onFocus?: React.FocusEventHandler<HTMLTextAreaElement>
+
+  /**
+   * Pointer down event handler
+   */
+  onPointerDown?: React.PointerEventHandler<HTMLTextAreaElement>
+
+  /**
+   * Key down event handler
+   */
+  onKeyDown?: React.KeyboardEventHandler<HTMLTextAreaElement>
+
+  /**
+   * Accessibility handler for Enter key press (without Shift modifier)
+   * Enables keyboard-only users to submit forms with Enter, while Shift+Enter creates new lines
+   * @param {React.KeyboardEvent<HTMLTextAreaElement>} event - Keyboard event
+   *
+   * @see {@link https://www.w3.org/WAI/WCAG21/Understanding/keyboard.html|WCAG 2.1.1 Keyboard}
+   */
+  onEnter?: (event: React.KeyboardEvent<HTMLTextAreaElement>) => void
+
+  /**
+   * Ref for the textarea element
+   */
+  ref?: React.Ref<HTMLTextAreaElement>
+}
+
+/**
+ * Select component props interface
+ * Extends native HTML select props with custom validation and accessibility features
+ *
+ * @interface SelectProps
+ */
+export interface SelectProps extends Omit<React.ComponentPropsWithoutRef<'select'>, 'className'> {
+  /**
+   * Unique identifier for the select element
+   */
+  id?: string
+
+  /**
+   * Name attribute for form submission
+   */
+  name?: string
+
+  /**
+   * CSS class names (preferred over 'className' for consistency with fpkit components)
+   */
+  classes?: string
+
+  /**
+   * Inline CSS styles object
+   */
+  styles?: React.CSSProperties
+
+  /**
+   * Disabled state
+   */
+  disabled?: boolean
+
+  /**
+   * Required field indicator
+   * @default false
+   */
+  required?: boolean
+
+  /**
+   * Selected option value(s)
+   */
+  selected?: string | number | string[]
+
+  /**
+   * Current validation state for styling and accessibility
+   * @default 'none'
+   */
+  validationState?: ValidationState
+
+  /**
+   * Error message to display and link via aria-describedby
+   */
+  errorMessage?: string
+
+  /**
+   * Hint text to display and link via aria-describedby
+   */
+  hintText?: string
+
+  /**
+   * Blur event handler
+   */
+  onBlur?: React.FocusEventHandler<HTMLSelectElement>
+
+  /**
+   * Selection change handler (alternative to onChange)
+   */
+  onSelectionChange?: React.ChangeEventHandler<HTMLSelectElement>
+
+  /**
+   * Pointer down event handler
+   */
+  onPointerDown?: React.PointerEventHandler<HTMLSelectElement>
+
+  /**
+   * Key down event handler
+   */
+  onKeyDown?: React.KeyboardEventHandler<HTMLSelectElement>
+
+  /**
+   * Accessibility handler for Enter key press
+   * Enables keyboard-only users to trigger actions after selection
+   * @param {React.KeyboardEvent<HTMLSelectElement>} event - Keyboard event
+   *
+   * @see {@link https://www.w3.org/WAI/WCAG21/Understanding/keyboard.html|WCAG 2.1.1 Keyboard}
+   */
+  onEnter?: (event: React.KeyboardEvent<HTMLSelectElement>) => void
+
+  /**
+   * Ref for the select element
+   */
+  ref?: React.Ref<HTMLSelectElement>
+
+  /**
+   * Child option elements
+   */
+  children?: React.ReactNode
+}