@fpkit/acss 0.5.13 → 0.6.0

package/src/components/form/textarea.tsx

@@ -1,87 +1,134 @@
 import React from 'react'
 import UI from '../ui'
+import { useDisabledState } from '../../hooks/use-disabled-state'
 
-export type TextareaProps = React.ComponentProps<'textarea'> &
-  React.ComponentProps<typeof UI>
+export type { TextareaProps } from './form.types'
+import type { TextareaProps } from './form.types'
 
 /**
- * Textarea component.
+ * Textarea component - Accessible multi-line text input with validation support
  *
- * @param value - The value of the textarea.
- * @param rows - The number of rows.
- * @param cols - The number of columns.
- * @param id - The id of the textarea.
- * @param name - The name of the textarea.
- * @param required - Whether the textarea is required.
- * @param disabled - Whether the textarea is disabled.
- * @param readOnly - Whether the textarea is read only.
- * @param onBlur - Blur event handler.
- * @param onPointerDown - Pointer down event handler.
- * @param onChange - Change event handler.
- * @param ref - Ref for the textarea.
- * @param styles - Styles object for the textarea.
- * @param textareaRef - Ref specifically for the textarea element.
- * @param props - Other props.
+ * A flexible textarea component that supports validation states, proper ARIA attributes
+ * for accessibility, and an onEnter handler for keyboard interactions. The onEnter handler
+ * fires only on Enter without Shift, allowing Shift+Enter to create new lines as expected.
+ *
+ * @component
+ * @example
+ * // Basic textarea
+ * <Textarea
+ *   id="message"
+ *   name="message"
+ *   placeholder="Enter your message"
+ *   required
+ * />
+ *
+ * @example
+ * // Textarea with Enter key handler for quick submission
+ * <Textarea
+ *   id="comment"
+ *   name="comment"
+ *   onEnter={(e) => handleSubmit()}
+ *   placeholder="Press Enter to submit, Shift+Enter for new line"
+ * />
+ *
+ * @param {TextareaProps} props - Component props
+ * @returns {JSX.Element} Textarea 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 Textarea = ({
-  id,
-  classes,
-  value,
-  rows = 5,
-  cols = 25,
-  name,
-  required,
-  disabled,
-  readOnly,
-  onBlur,
-  onPointerDown,
-  onChange,
-  ref,
-  styles,
-  placeholder,
-  ...props
-}: TextareaProps) => {
-  const handleChange = (e: React.ChangeEvent<HTMLTextAreaElement>) => {
-    if (onChange && !disabled) {
-      onChange?.(e)
-    }
-  }
+export const Textarea = React.forwardRef<HTMLTextAreaElement, TextareaProps>(
+  (
+    {
+      id,
+      classes,
+      value,
+      rows = 5,
+      cols = 25,
+      name,
+      required,
+      disabled,
+      readOnly,
+      validationState = 'none',
+      errorMessage,
+      hintText,
+      onBlur,
+      onPointerDown,
+      onChange,
+      onKeyDown,
+      onEnter,
+      styles,
+      placeholder,
+      ...props
+    },
+    ref
+  ) => {
+    // Use the disabled state hook with enhanced API for automatic className merging
+    const { disabledProps, handlers } = useDisabledState<HTMLTextAreaElement>(
+      disabled,
+      {
+        handlers: {
+          onChange,
+          onBlur,
+          onPointerDown,
+          onKeyDown: (e: React.KeyboardEvent<HTMLTextAreaElement>) => {
+            // Handle Enter key press for accessibility
+            // Only triggers onEnter when Enter is pressed WITHOUT Shift modifier
+            // This allows Shift+Enter to create new lines as expected
+            if (e.key === 'Enter' && !e.shiftKey && 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 handleBlur = (e: React.FocusEvent<HTMLTextAreaElement>) => {
-    if (onBlur && !disabled) {
-      onBlur?.(e)
-    }
-  }
+    // Determine aria-invalid based on validation state
+    const isInvalid = validationState === 'invalid'
 
-  const handlePointerDown = (e: React.PointerEvent<HTMLTextAreaElement>) => {
-    if (onPointerDown && !disabled) {
-      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
+
+    return (
+      <UI
+        as="textarea"
+        id={id}
+        name={name}
+        rows={rows}
+        cols={cols}
+        styles={styles}
+        className={disabledProps.className}
+        data-style="textarea"
+        required={required}
+        value={value}
+        aria-disabled={disabledProps['aria-disabled']}
+        aria-required={required}
+        aria-invalid={isInvalid}
+        aria-describedby={ariaDescribedBy}
+        readOnly={readOnly}
+        {...handlers}
+        ref={ref}
+        placeholder={placeholder || `${required ? '*' : ''} Message`}
+        {...props}
+      />
+    )
   }
+)
 
-  return (
-    <UI
-      as="textarea"
-      id={id}
-      name={name}
-      rows={rows}
-      cols={cols}
-      styles={styles}
-      className={classes}
-      data-style="textarea"
-      required={required}
-      value={value}
-      aria-disabled={disabled}
-      readOnly={readOnly}
-      onChange={handleChange}
-      onBlur={handleBlur}
-      onPointerDown={handlePointerDown}
-      ref={ref}
-      placeholder={placeholder || `${required ? '*' : ''} Message`}
-      {...props}
-    />
-  )
-}
+Textarea.displayName = 'Textarea'
 
 export default Textarea
-Textarea.displayName = 'Textarea'

package/src/components/fp.tsx

@@ -1,28 +1,55 @@
 import React from 'react'
 import { ComponentProps } from '../types'
 
-type PolymorphicRef<C extends React.ElementType> =
-  React.ComponentPropsWithRef<C>['ref']
+/**
+ * @deprecated This type is deprecated. Use `PolymorphicRef` from './ui.tsx' instead.
+ * The UI component provides better type safety and accessibility features.
+ */
+type PolymorphicRef<C extends React.ElementType> = React.Ref<
+  React.ElementRef<C>
+>
 
+/**
+ * @deprecated This type is deprecated. Use `AsProp` from './ui.tsx' instead.
+ * The UI component provides better type safety and accessibility features.
+ */
 type AsProp<C extends React.ElementType> = {
   as?: C
 }
 
+/**
+ * @deprecated This type is deprecated. Use `PropsToOmit` from './ui.tsx' instead.
+ * The UI component provides better type safety and accessibility features.
+ */
 type PropsToOmit<C extends React.ElementType, P> = keyof (AsProp<C> & P)
 
+/**
+ * @deprecated This type is deprecated. Use `PolymorphicComponentProp` from './ui.tsx' instead.
+ * The UI component provides better type safety and accessibility features.
+ */
 type PolymorphicComponentProp<
   C extends React.ElementType,
+  // eslint-disable-next-line @typescript-eslint/no-empty-object-type
   Props = {},
 > = React.PropsWithChildren<Props & AsProp<C>> &
   Omit<React.ComponentPropsWithoutRef<C>, PropsToOmit<C, Props>>
 
+/**
+ * @deprecated This type is deprecated. Use `PolymorphicComponentPropWithRef` from './ui.tsx' instead.
+ * The UI component provides better type safety and accessibility features.
+ */
 type PolymorphicComponentPropWithRef<
   C extends React.ElementType,
+  // eslint-disable-next-line @typescript-eslint/no-empty-object-type
   Props = {},
 > = PolymorphicComponentProp<C, Props> & {
-  ref?: PolymorphicRef<C>
+  ref?: PolymorphicRef<C> | React.ForwardedRef<React.ElementRef<C>>
 }
 
+/**
+ * @deprecated This type is deprecated. Use `UIProps` from './ui.tsx' instead.
+ * The UI component provides better type safety and accessibility features.
+ */
 type FPProps<C extends React.ElementType> = PolymorphicComponentPropWithRef<
   C,
   {
@@ -32,21 +59,62 @@ type FPProps<C extends React.ElementType> = PolymorphicComponentPropWithRef<
   }
 >
 
-/*
+/**
  * FPComponent type definition
  *
- * Defines the component function signature for the FP component.
+ * @deprecated This type is deprecated. Use the `UI` component from './ui.tsx' instead.
+ * The UI component provides enhanced accessibility documentation, better type safety,
+ * and comprehensive WCAG 2.1 AA compliance guidance.
  *
  * @typeParam C - The HTML element type to render
  * @param props - The component props
  * @returns React component
+ *
+ * @example
+ * ```typescript
+ * // Migration from FP to UI
+ * // Before:
+ * import FP from '@fpkit/acss/components/fp';
+ * <FP as="button" styles={{ padding: '1rem' }}>Click me</FP>
+ *
+ * // After:
+ * import UI from '@fpkit/acss/components/ui';
+ * <UI as="button" styles={{ padding: '1rem' }}>Click me</UI>
+ * ```
  */
-type FPComponent = <C extends React.ElementType = 'span'>(
-  props: FPProps<C>,
-) => React.ReactElement | any
+type FPComponent = {
+  <C extends React.ElementType = 'span'>(
+    props: FPProps<C>,
+  ): React.ReactElement | null
+  displayName?: string
+}
 
 /**
- * FP component is a polymorphic component that renders an HTML element with optional styles.
+ * @deprecated **DEPRECATED:** This component is deprecated and will be removed in a future version.
+ * Please use the `UI` component from `./ui.tsx` instead.
+ *
+ * The UI component is a drop-in replacement with the same API but provides:
+ * - Enhanced accessibility documentation and WCAG 2.1 AA compliance guidance
+ * - Better TypeScript type safety with detailed JSDoc comments
+ * - Comprehensive examples for accessible component patterns
+ * - More robust style merging with defaultStyles support
+ *
+ * @example
+ * ```typescript
+ * // Migration Guide
+ * // Before:
+ * import FP from '@fpkit/acss/components/fp';
+ * <FP as="button" styles={{ padding: '1rem' }} classes="btn">
+ *   Click me
+ * </FP>
+ *
+ * // After:
+ * import UI from '@fpkit/acss/components/ui';
+ * <UI as="button" styles={{ padding: '1rem' }} classes="btn">
+ *   Click me
+ * </UI>
+ * ```
+ *
  * @param {Object} props - Component props
  * @param {React.ElementType} props.as - The HTML element to render. Defaults to 'div'.
  * @param {boolean} props.renderStyles - Whether to render styles or not. Defaults to true.
@@ -55,7 +123,7 @@ type FPComponent = <C extends React.ElementType = 'span'>(
  * @param {React.ReactNode} props.children - The children to render inside the component.
  * @returns {React.ReactElement} - A React component that renders an HTML element with optional styles.
  */
-const FP: FPComponent = React.forwardRef(
+const FP = React.forwardRef(
   <C extends React.ElementType>(
     { as, styles, classes, children, defaultStyles, ...props }: FPProps<C>,
     ref?: PolymorphicRef<C>,
@@ -70,7 +138,14 @@ const FP: FPComponent = React.forwardRef(
       </Component>
     )
   },
-)
+) as FPComponent
+
+FP.displayName = 'FP'
+
+/**
+ * @deprecated This interface is deprecated. Use the `UI` component from './ui.tsx' instead.
+ * The UI component provides better type safety and accessibility features.
+ */
 export interface BoxProps extends ComponentProps {
   renderStyles: true
 }