@fpkit/acss 0.5.13 → 0.6.0

package/src/components/form/input.stories.tsx

@@ -68,18 +68,86 @@ export const DefaultRequired: Story = {
   },
 } as Story;
 
+/**
+ * Disabled input using WCAG-compliant aria-disabled pattern.
+ *
+ * Key accessibility features implemented by the optimized useDisabledState hook:
+ * - Uses aria-disabled instead of native disabled attribute
+ * - Remains keyboard focusable (in tab order)
+ * - Prevents all interactions (typing, onChange events)
+ * - Screen readers can discover and announce disabled state
+ * - Automatic className merging (.is-disabled + custom classes)
+ */
 export const InputDisabled: Story = {
   parameters: {
     docs: {
       description: {
-        story:
-          'Displays a disabled input `aria-disabled="true"` on any input type',
+        story: `
+Displays a disabled input with \`aria-disabled="true"\`.
+
+**Why aria-disabled instead of disabled?**
+- Keeps input in tab order for screen reader users
+- Allows focus for screen reader announcement
+- Better contrast control for WCAG AA compliance
+- Can show tooltips/help text even when disabled
+
+Try tabbing to the input - it receives focus!
+Try typing - interactions are prevented by the hook.
+        `,
       },
     },
   },
   args: {
     type: "text",
-    isDisabled: true,
+    disabled: true,
+    placeholder: "This input is disabled",
+  },
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+    const input = canvas.getByRole("textbox");
+
+    await step("Disabled input has aria-disabled attribute", async () => {
+      expect(input).toHaveAttribute("aria-disabled", "true");
+    });
+
+    await step("Disabled input remains focusable", async () => {
+      await userEvent.tab();
+      expect(input).toHaveFocus();
+    });
+
+    await step("Disabled input has .is-disabled class", async () => {
+      expect(input).toHaveClass("is-disabled");
+    });
+
+    await step("Disabled input prevents typing interactions", async () => {
+      const initialValue = input.getAttribute("value") || "";
+      await userEvent.type(input, "test");
+      // Value should remain unchanged due to disabled state
+      expect(input).toHaveValue(initialValue);
+    });
+  },
+} as Story;
+
+/**
+ * Disabled input with custom classes.
+ *
+ * Demonstrates the hook's automatic className merging feature.
+ * The .is-disabled class is automatically combined with custom classes.
+ */
+export const DisabledWithCustomClass: Story = {
+  args: {
+    type: "text",
+    disabled: true,
+    classes: "custom-input highlight-disabled",
+    placeholder: "Disabled with custom classes",
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Shows how the optimized hook automatically merges `.is-disabled` with custom classes (`custom-input highlight-disabled`).",
+      },
+    },
   },
 } as Story;
 

package/src/components/form/inputs.tsx

@@ -1,78 +1,170 @@
 import React from "react";
 import FP from "../fp";
+import type { InputProps } from "./form.types";
+import { useDisabledState } from "../../hooks/use-disabled-state";
+import { resolveDisabledState } from "../../utils/accessibility";
 
-export type InputProps = {
-  /**
-   * The type of the input.
-   */
-  type?: "text" | "password" | "email" | "number" | "tel" | "url" | "search";
+export type { InputProps } from "./form.types";
 
-  /**
-   * Set the element as disabled
-   */
-  isDisabled?: boolean;
-} & React.ComponentProps<typeof FP>;
+/**
+ * Input component - Accessible text input with validation support
+ *
+ * A flexible input component that supports various input types, validation states,
+ * and proper ARIA attributes for accessibility. Integrates seamlessly with the
+ * Field component for complete form control composition.
+ *
+ * @component
+ * @example
+ * // Basic text input
+ * <Input
+ *   id="username"
+ *   name="username"
+ *   placeholder="Enter username"
+ *   required
+ * />
+ *
+ * @example
+ * // Input with error state
+ * <Input
+ *   id="email"
+ *   type="email"
+ *   validationState="invalid"
+ *   errorMessage="Please enter a valid email"
+ *   aria-describedby="email-error"
+ * />
+ *
+ * @example
+ * // Controlled input with validation
+ * <Input
+ *   id="password"
+ *   type="password"
+ *   value={password}
+ *   onChange={(e) => setPassword(e.target.value)}
+ *   minLength={8}
+ *   required
+ * />
+ *
+ * @param {InputProps} props - Component props
+ * @returns {JSX.Element} Input element with proper accessibility attributes
+ *
+ * @see {@link https://www.w3.org/WAI/WCAG21/Understanding/error-identification.html|WCAG 3.3.1 Error Identification}
+ * @see {@link https://www.w3.org/WAI/WCAG21/Understanding/name-role-value.html|WCAG 4.1.2 Name, Role, Value}
+ */
+export const Input = React.forwardRef<HTMLInputElement, InputProps>(
+  (
+    {
+      type = "text",
+      name,
+      value,
+      defaultValue,
+      placeholder,
+      id,
+      styles,
+      classes,
+      isDisabled, // Legacy support
+      disabled,
+      readOnly,
+      required = false,
+      validationState = "none",
+      errorMessage,
+      hintText,
+      onChange,
+      onBlur,
+      onFocus,
+      onKeyDown,
+      onEnter,
+      maxLength,
+      minLength,
+      pattern,
+      autoComplete,
+      autoFocus = false,
+      inputMode,
+      ...props
+    },
+    ref
+  ) => {
+    // Support both `disabled` and `isDisabled` props (legacy compatibility)
+    const isInputDisabled = resolveDisabledState(disabled, isDisabled);
 
-export const Input = ({
-  type = "text",
-  name,
-  value,
-  placeholder,
-  id,
-  styles,
-  classes,
-  isDisabled,
-  disabled,
-  readonly,
-  required,
-  ref,
-  onChange,
-  onBlur,
-  onPointerDown,
-  ...props
-}: InputProps): JSX.Element => {
-  const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
-    if (onChange && !disabled) {
-      onChange?.(e);
-    }
-  };
+    // Use the disabled state hook with enhanced API for automatic className merging
+    const { disabledProps, handlers } = useDisabledState<HTMLInputElement>(
+      isInputDisabled,
+      {
+        handlers: {
+          onChange,
+          onBlur,
+          onKeyDown: (e: React.KeyboardEvent<HTMLInputElement>) => {
+            // Handle Enter key press for accessibility
+            if (e.key === "Enter" && onEnter) {
+              onEnter(e);
+            }
+            // Always call consumer's onKeyDown if provided
+            if (onKeyDown) {
+              onKeyDown(e);
+            }
+          },
+          // Note: onFocus is NOT wrapped to allow focus on disabled inputs
+          // This is handled automatically by useDisabledState
+        },
+        // Automatic className merging - hook combines disabled class with user classes
+        className: classes,
+      }
+    );
 
-  const handleBlur = (e: React.FocusEvent<HTMLInputElement>) => {
-    if (onBlur && !disabled) {
-      onBlur?.(e);
-    }
-  };
+    // Determine aria-invalid based on validation state
+    const isInvalid = validationState === "invalid";
 
-  const handleKeyDown = (e: React.KeyboardEvent<HTMLInputElement>) => {
-    if (onPointerDown && !disabled) {
-      e.preventDefault();
-      onPointerDown?.(e);
+    // Generate describedby IDs for error and hint text
+    const describedByIds: string[] = [];
+    if (errorMessage && id) {
+      describedByIds.push(`${id}-error`);
+    }
+    if (hintText && id) {
+      describedByIds.push(`${id}-hint`);
     }
-  };
+    const ariaDescribedBy =
+      describedByIds.length > 0 ? describedByIds.join(" ") : undefined;
+
+    // Generate accessible placeholder if not provided
+    const accessiblePlaceholder =
+      placeholder || (required ? `* ${type} input` : `${type} input`);
+
+    return (
+      <FP
+        as="input"
+        ref={ref}
+        id={id}
+        type={type}
+        name={name}
+        value={value}
+        defaultValue={defaultValue}
+        placeholder={accessiblePlaceholder}
+        className={disabledProps.className}
+        styles={styles}
+        readOnly={readOnly}
+        required={required}
+        maxLength={maxLength}
+        minLength={minLength}
+        pattern={pattern}
+        autoComplete={autoComplete}
+        autoFocus={autoFocus}
+        inputMode={inputMode}
+        // Event handlers (wrapped by useDisabledState)
+        {...handlers}
+        onFocus={onFocus}
+        // ARIA attributes
+        aria-disabled={disabledProps["aria-disabled"]}
+        aria-readonly={readOnly}
+        aria-required={required}
+        aria-invalid={isInvalid}
+        aria-describedby={ariaDescribedBy}
+        // Data attributes for styling
+        data-validation={validationState}
+        {...props}
+      />
+    );
+  }
+);
 
-  return (
-    <FP
-      as="input"
-      id={id}
-      type={type}
-      placeholder={placeholder || `${required ? "*" : ""} ${type} input `}
-      className={classes}
-      styles={styles}
-      onChange={handleChange}
-      onBlur={handleBlur}
-      onKeyDown={handleKeyDown}
-      value={value}
-      name={name}
-      ref={ref}
-      aria-disabled={isDisabled}
-      tabIndex={isDisabled ? -1 : undefined}
-      aria-readonly={readonly}
-      aria-required={required}
-      required={required}
-      readOnly={readonly}
-      {...props}
-    />
-  );
-};
 Input.displayName = "Input";
 export default Input;

package/src/components/form/select.tsx

@@ -1,7 +1,9 @@
 import UI from '../ui'
 import React from 'react'
+import { useDisabledState } from '../../hooks/use-disabled-state'
 
-export type SelectProps = React.ComponentProps<typeof UI>
+export type { SelectProps } from './form.types'
+import type { SelectProps } from './form.types'
 
 export type SelectOptionsProps = {
   /**
@@ -13,7 +15,7 @@ export type SelectOptionsProps = {
    * Value for the select option. Can be a number or string.
    */
   selectValue: string
-} & SelectProps
+}
 
 /**
  * Option component for select.
@@ -23,80 +25,134 @@ export type SelectOptionsProps = {
  */
 export const Option = ({ selectValue, selectLabel }: SelectOptionsProps) => {
   return (
-    <option role="option" value={selectValue}>
+    <option value={selectValue}>
       {selectLabel || selectValue}
     </option>
   )
 }
 
 /**
- * Select component props.
- * @param {string} [id] - Unique id for the select.
- * @param {string} [name] - Name for the select input.
- * @param {React.CSSProperties} [styles] - Inline styles.
- * @param {string} [classes] - CSS classes.
- * @param {boolean} [disabled] - Whether select is disabled.
- * @param {React.ReactNode} [children] - Child elements.
- * @param {boolean} [required] - Whether select is required.
- * @param {string | number | string[] | undefined} [selected] - Selected option value(s).
- * @param {React.FocusEventHandler<HTMLSelectElement>} [onBlur] - Blur event handler.
- * @param {React.ChangeEventHandler<HTMLSelectElement>} [onChange] - Change event handler.
- * @param {(e: React.ChangeEvent<HTMLSelectElement>) => void} [onSelectionChange] - Selection change handler.
- * @param {(e: React.PointerEvent<HTMLSelectElement>) => void} [onPointerDown] - Pointer down handler.
- * @param {React.Ref<HTMLSelectElement>} [ref] - Ref for the select element.
+ * Select component - Accessible dropdown selection input with validation support
+ *
+ * A flexible select component that supports validation states, proper ARIA attributes
+ * for accessibility, and an onEnter handler for keyboard interactions. Enables keyboard-only
+ * users to trigger actions after making a selection.
+ *
+ * @component
+ * @example
+ * // Basic select
+ * <Select id="country" name="country" required>
+ *   <option value="us">United States</option>
+ *   <option value="uk">United Kingdom</option>
+ * </Select>
+ *
+ * @example
+ * // Select with Enter key handler for quick submission
+ * <Select
+ *   id="status"
+ *   name="status"
+ *   onEnter={(e) => handleSubmit()}
+ *   onSelectionChange={(e) => setStatus(e.target.value)}
+ * >
+ *   <option value="active">Active</option>
+ *   <option value="inactive">Inactive</option>
+ * </Select>
+ *
+ * @param {SelectProps} props - Component props
+ * @returns {JSX.Element} Select element with proper accessibility attributes
+ *
+ * @see {@link https://www.w3.org/WAI/WCAG21/Understanding/keyboard.html|WCAG 2.1.1 Keyboard}
+ * @see {@link https://www.w3.org/WAI/WCAG21/Understanding/name-role-value.html|WCAG 4.1.2 Name, Role, Value}
  */
-export const Select = ({
-  id,
-  name,
-  styles,
-  classes,
-  disabled,
-  children,
-  required,
-  selected,
-  onBlur,
-  onSelectionChange,
-  onPointerDown,
-  ref,
-  ...props
-}: SelectProps) => {
-  const handleOnChange = (e: React.ChangeEvent<HTMLSelectElement>) => {
-    if (onSelectionChange && !disabled) onSelectionChange?.(e)
-  }
+export const Select = React.forwardRef<HTMLSelectElement, SelectProps>(
+  (
+    {
+      id,
+      name,
+      styles,
+      classes,
+      disabled,
+      children,
+      required,
+      selected,
+      validationState = 'none',
+      errorMessage,
+      hintText,
+      onBlur,
+      onSelectionChange,
+      onPointerDown,
+      onKeyDown,
+      onEnter,
+      ...props
+    },
+    ref
+  ) => {
+    // Use the disabled state hook with enhanced API for automatic className merging
+    const { disabledProps, handlers } = useDisabledState<HTMLSelectElement>(
+      disabled,
+      {
+        handlers: {
+          onChange: onSelectionChange,
+          onPointerDown,
+          onBlur,
+          onKeyDown: (e: React.KeyboardEvent<HTMLSelectElement>) => {
+            // Handle Enter key press for accessibility
+            // Enables keyboard-only users to trigger actions after selection
+            if (e.key === 'Enter' && onEnter) {
+              onEnter(e)
+            }
+            // Always call consumer's onKeyDown if provided
+            if (onKeyDown) {
+              onKeyDown(e)
+            }
+          },
+        },
+        // Automatic className merging - hook combines disabled class with user classes
+        className: classes,
+      }
+    )
 
-  const handlePointerDown = (e: React.PointerEvent<HTMLSelectElement>) => {
-    if (onPointerDown && !disabled) onPointerDown?.(e)
-  }
+    // Determine aria-invalid based on validation state
+    const isInvalid = validationState === 'invalid'
 
-  const handleOnBlur = (e: React.FocusEvent<HTMLSelectElement>) => {
-    if (onBlur && !disabled) onBlur?.(e)
+    // Generate describedby IDs for error and hint text
+    const describedByIds: string[] = []
+    if (errorMessage && id) {
+      describedByIds.push(`${id}-error`)
+    }
+    if (hintText && id) {
+      describedByIds.push(`${id}-hint`)
+    }
+    const ariaDescribedBy =
+      describedByIds.length > 0 ? describedByIds.join(' ') : undefined
+
+    return (
+      <UI
+        as="select"
+        id={id}
+        ref={ref}
+        name={name}
+        className={disabledProps.className}
+        defaultValue={selected}
+        {...handlers}
+        required={required}
+        aria-required={required}
+        aria-disabled={disabledProps['aria-disabled']}
+        aria-invalid={isInvalid}
+        aria-describedby={ariaDescribedBy}
+        style={styles}
+        {...props}
+      >
+        {children || <option value="" />}
+      </UI>
+    )
   }
+)
 
-  return (
-    <UI
-      as="select"
-      id={id}
-      ref={ref}
-      name={name}
-      className={classes}
-      selected={selected}
-      onChange={handleOnChange}
-      onPointerDown={handlePointerDown}
-      onBlur={handleOnBlur}
-      required={required}
-      aria-required={required} // Accessibility
-      disabled={disabled}
-      aria-disabled={disabled ? true : false}
-      style={styles}
-      {...props} // Accessibility
-    >
-      <option value="" />
-    </UI>
-  )
-}
+Select.displayName = 'Select'
 
-export default Select
-Select.displayName = 'Select' // Remove this line
-Select.Option = Option // Remove this line
+// Type assertion to allow adding static property to ForwardRefExoticComponent
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+;(Select as any).Option = Option
 
-// export const MemoizedSelect = React.memo(Select)
+export default Select