@fpkit/acss 0.5.12 → 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
 }

package/src/components/heading/heading.stories.tsx

@@ -3,22 +3,62 @@ import { within, expect } from "storybook/test";
 
 import Heading from "./heading";
 
+/**
+ * @deprecated This component is deprecated. Use Title component instead.
+ */
 const meta: Meta<typeof Heading> = {
-  title: "FP.REACT Components/Heading",
+  title: "FP.REACT Components/Heading (Deprecated)",
   component: Heading,
-  tags: ["version:1.0.0"],
+  tags: ["version:1.0.0", "deprecated"],
   parameters: {
     actions: { argTypesRegex: "^on.*" },
     docs: {
       description: {
-        component: "Heading description here...",
+        component: `
+# ⚠️ DEPRECATED: Use Title Component Instead
+
+The \`Heading\` component is **deprecated** and will be removed in **v3.0.0**.
+
+Please migrate to the new [\`Title\`](?path=/docs/fp-react-components-title--docs) component.
+
+## Migration Guide
+
+\`\`\`tsx
+// ❌ Old API (deprecated):
+import { Heading } from '@fpkit/acss';
+<Heading type="h2">Section Title</Heading>
+
+// ✅ New API:
+import { Title } from '@fpkit/acss';
+<Title level="h2">Section Title</Title>
+\`\`\`
+
+### Key Changes
+
+1. **Component Name**: \`Heading\` → \`Title\`
+2. **Prop Name**: \`type\` → \`level\`
+3. **Default Level**: Changed from \`h3\` to \`h2\` (update if you relied on the default)
+
+### Why the Change?
+
+- **Better API**: \`level\` is more semantic than \`type\`
+- **Improved Accessibility**: Enhanced WCAG 2.1 compliance
+- **Better Documentation**: Comprehensive JSDoc comments
+- **Performance**: Memoization to prevent unnecessary re-renders
+
+## Current Behavior
+
+This component still works for backwards compatibility but will log deprecation warnings in development mode.
+
+**Removal Timeline**: v3.0.0 (TBD)
+      `,
       },
     },
   },
   args: {
     children: "Default title",
   },
-} as Story;
+} satisfies Meta<typeof Heading>;
 
 export default meta;
 type Story = StoryObj<typeof Heading>;

package/src/components/heading/heading.tsx

@@ -1,27 +1,93 @@
-import React from 'react'
-import UI from '#components/ui'
-import { type } from 'os'
+import React from "react";
+import Title from "#components/title/title";
 
+/**
+ * @deprecated Use `Title` component instead. This component will be removed in v3.0.0.
+ *
+ * @remarks
+ * The `Heading` component has been deprecated in favor of the new `Title` component
+ * which offers improved API design and better accessibility features.
+ *
+ * **Migration Guide:**
+ * - Rename `Heading` → `Title`
+ * - Rename prop `type` → `level`
+ * - Default level changed from `h3` → `h2` (update if you relied on the default)
+ *
+ * @example
+ * // Before (deprecated):
+ * <Heading type="h2">Section Title</Heading>
+ *
+ * // After:
+ * <Title level="h2">Section Title</Title>
+ *
+ * @see {@link Title} for the new component
+ */
 export type TitleProps = {
-  children: React.ReactNode
-  type: 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6'
-  ui?: string
-} & React.ComponentProps<typeof UI>
+  /**
+   * @deprecated Use `level` prop on the `Title` component instead.
+   */
+  children: React.ReactNode;
 
-const Heading = ({
-  type = 'h3',
-  id,
-  styles,
-  ui,
-  children,
-  ...props
-}: TitleProps) => {
-  return (
-    <UI as={type} id={id} styles={styles} data-ui={ui} {...props}>
-      {children}
-    </UI>
-  )
-}
+  /**
+   * @deprecated Use `level` prop on the `Title` component instead.
+   */
+  type?: "h1" | "h2" | "h3" | "h4" | "h5" | "h6";
 
-export default Heading
-Heading.displayName = 'Heading'
+  /**
+   * @deprecated Use `ui` prop on the `Title` component.
+   */
+  ui?: string;
+} & Omit<React.ComponentPropsWithoutRef<typeof Title>, 'level'>;
+
+/**
+ * Heading - Deprecated component wrapper for Title.
+ *
+ * @deprecated Use {@link Title} component instead. Will be removed in v3.0.0.
+ *
+ * This component provides backwards compatibility for existing code using
+ * the old `Heading` component API. It forwards all props to the new `Title`
+ * component with appropriate prop name mapping.
+ *
+ * **Breaking Changes in v3.0.0:**
+ * - This component will be removed
+ * - Migrate to `Title` component before upgrading
+ *
+ * **Migration Steps:**
+ * 1. Replace all `<Heading>` imports with `<Title>`
+ * 2. Rename `type` prop to `level`
+ * 3. Review default behavior (default changed from h3 to h2)
+ *
+ * @example
+ * // Old API (still works but deprecated):
+ * import { Heading } from '@fpkit/acss';
+ * <Heading type="h2">Section</Heading>
+ *
+ * @example
+ * // New API (recommended):
+ * import { Title } from '@fpkit/acss';
+ * <Title level="h2">Section</Title>
+ *
+ * @param {TitleProps} props - Component props (maps old API to new)
+ * @returns {React.ReactElement} The rendered Title component
+ */
+const Heading = React.forwardRef<HTMLHeadingElement, TitleProps>(
+  ({ type = "h3", ...props }, ref) => {
+    // Development warning for deprecated usage
+    if (process.env.NODE_ENV === "development") {
+      // eslint-disable-next-line no-console
+      console.warn(
+        `[@fpkit/acss] Heading component is deprecated and will be removed in v3.0.0. ` +
+        `Please use the Title component instead.\n` +
+        `Migration: <Heading type="${type}"> → <Title level="${type}">\n` +
+        `See documentation: https://fpkit.dev/components/title`
+      );
+    }
+
+    // Map old 'type' prop to new 'level' prop
+    return <Title level={type} ref={ref} {...props} />;
+  }
+);
+
+Heading.displayName = "Heading (Deprecated)";
+
+export default Heading;