@tpzdsp/next-toolkit 1.2.9 → 1.4.0

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

@@ -0,0 +1,465 @@
+/* eslint-disable storybook/no-renderer-packages */
+import type { Meta, StoryObj } from '@storybook/react';
+
+import { TextArea } from './TextArea';
+
+const meta = {
+  title: 'Components/Form/TextArea',
+  component: TextArea,
+  parameters: {
+    layout: 'centered',
+    docs: {
+      description: {
+        component: 'A styled textarea component with error state support and customizable styling.',
+      },
+    },
+  },
+  tags: ['autodocs'],
+  argTypes: {
+    hasError: {
+      control: 'boolean',
+      description: 'Whether the textarea should display in error state',
+      defaultValue: false,
+    },
+    rows: {
+      control: { type: 'number', min: 1, max: 20 },
+      description: 'Number of visible text lines',
+      defaultValue: 4,
+    },
+    cols: {
+      control: { type: 'number', min: 10, max: 100 },
+      description: 'Number of visible character widths',
+    },
+    placeholder: {
+      control: 'text',
+      description: 'Placeholder text for the textarea',
+    },
+    disabled: {
+      control: 'boolean',
+      description: 'Whether the textarea is disabled',
+      defaultValue: false,
+    },
+    required: {
+      control: 'boolean',
+      description: 'Whether the textarea is required',
+      defaultValue: false,
+    },
+    maxLength: {
+      control: { type: 'number', min: 0 },
+      description: 'Maximum number of characters allowed',
+    },
+  },
+} satisfies Meta<typeof TextArea>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: {
+    placeholder: 'Enter your message...',
+    rows: 4,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Default textarea with standard styling.',
+      },
+    },
+  },
+};
+
+export const WithError: Story = {
+  args: {
+    hasError: true,
+    placeholder: 'This textarea has an error',
+    value: 'Invalid content that caused an error',
+    rows: 4,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Textarea in error state with red border styling.',
+      },
+    },
+  },
+};
+
+export const Disabled: Story = {
+  args: {
+    disabled: true,
+    placeholder: 'This textarea is disabled',
+    value: 'This content cannot be edited',
+    rows: 4,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Disabled textarea with reduced opacity and gray background.',
+      },
+    },
+  },
+};
+
+export const Required: Story = {
+  render: () => (
+    <div className="w-96">
+      <label htmlFor="required-textarea" className="block text-sm font-medium mb-1">
+        Description <span className="text-red-500">*</span>
+      </label>
+
+      <TextArea
+        id="required-textarea"
+        required
+        placeholder="Please provide a detailed description"
+        rows={5}
+        aria-describedby="required-help"
+      />
+
+      <p id="required-help" className="text-gray-600 text-xs mt-1">
+        * This field is required
+      </p>
+    </div>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'Required textarea field with visual indicator (red asterisk) and helper text.',
+      },
+    },
+  },
+};
+
+export const WithCharacterLimit: Story = {
+  render: () => (
+    <div className="w-96">
+      <label htmlFor="limited-textarea" className="block text-sm font-medium mb-1">
+        Comment (max 280 characters)
+      </label>
+
+      <TextArea
+        id="limited-textarea"
+        placeholder="What's on your mind?"
+        maxLength={280}
+        rows={4}
+        aria-describedby="char-count"
+      />
+
+      <p id="char-count" className="text-gray-600 text-xs mt-1">
+        280 characters remaining
+      </p>
+    </div>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'Textarea with character limit and counter (note: counter is static in this demo).',
+      },
+    },
+  },
+};
+
+export const DifferentSizes: Story = {
+  render: () => (
+    <div className="space-y-6 w-96">
+      <div>
+        <label htmlFor="small-textarea" className="block text-sm font-medium mb-1">
+          Small (3 rows)
+        </label>
+
+        <TextArea id="small-textarea" placeholder="Short description..." rows={3} />
+      </div>
+
+      <div>
+        <label htmlFor="medium-textarea" className="block text-sm font-medium mb-1">
+          Medium (5 rows)
+        </label>
+
+        <TextArea id="medium-textarea" placeholder="Medium description..." rows={5} />
+      </div>
+
+      <div>
+        <label htmlFor="large-textarea" className="block text-sm font-medium mb-1">
+          Large (8 rows)
+        </label>
+
+        <TextArea id="large-textarea" placeholder="Long description..." rows={8} />
+      </div>
+    </div>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'Textareas with different row heights for various use cases.',
+      },
+    },
+  },
+};
+
+export const FormExample: Story = {
+  render: () => (
+    <form className="space-y-6 w-96">
+      <div>
+        <label htmlFor="subject" className="block text-sm font-medium mb-1">
+          Subject <span className="text-red-500">*</span>
+        </label>
+
+        <input
+          id="subject"
+          type="text"
+          className="w-full rounded-md border p-2"
+          placeholder="Brief subject line"
+          required
+        />
+      </div>
+
+      <div>
+        <label htmlFor="message" className="block text-sm font-medium mb-1">
+          Message <span className="text-red-500">*</span>
+        </label>
+
+        <TextArea
+          id="message"
+          placeholder="Enter your detailed message here..."
+          rows={6}
+          required
+          aria-describedby="message-help"
+        />
+
+        <p id="message-help" className="text-gray-600 text-xs mt-1">
+          Please provide as much detail as possible
+        </p>
+      </div>
+
+      <div>
+        <label htmlFor="notes" className="block text-sm font-medium mb-1">
+          Additional Notes
+        </label>
+
+        <TextArea id="notes" placeholder="Any additional information (optional)" rows={3} />
+      </div>
+
+      <button
+        type="submit"
+        className="w-full bg-blue-600 text-white py-2 px-4 rounded-md hover:bg-blue-700
+          focus:outline-none focus:ring-2 focus:ring-blue-500"
+      >
+        Send Message
+      </button>
+    </form>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Complete form example showing textareas in a realistic context with proper labels and validation.',
+      },
+    },
+  },
+};
+
+export const ErrorStates: Story = {
+  render: () => (
+    <div className="space-y-6 w-96">
+      <div>
+        <label htmlFor="error-required" className="block text-sm font-medium mb-1">
+          Required Field <span className="text-red-500">*</span>
+        </label>
+
+        <TextArea
+          id="error-required"
+          hasError
+          placeholder="This field is required"
+          rows={4}
+          aria-invalid="true"
+          aria-describedby="required-error"
+        />
+
+        <p id="required-error" className="text-red-600 text-xs mt-1" role="alert">
+          This field is required.
+        </p>
+      </div>
+
+      <div>
+        <label htmlFor="error-length" className="block text-sm font-medium mb-1">
+          Description (min 10 characters)
+        </label>
+
+        <TextArea
+          id="error-length"
+          hasError
+          value="Too short"
+          rows={4}
+          minLength={10}
+          aria-invalid="true"
+          aria-describedby="length-error"
+        />
+
+        <p id="length-error" className="text-red-600 text-xs mt-1" role="alert">
+          Description must be at least 10 characters long.
+        </p>
+      </div>
+
+      <div>
+        <label htmlFor="error-content" className="block text-sm font-medium mb-1">
+          Content Review
+        </label>
+
+        <TextArea
+          id="error-content"
+          hasError
+          value="This content contains inappropriate language..."
+          rows={4}
+          aria-invalid="true"
+          aria-describedby="content-error"
+        />
+
+        <p id="content-error" className="text-red-600 text-xs mt-1" role="alert">
+          Please review your content and remove inappropriate language.
+        </p>
+      </div>
+    </div>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Examples of textarea error states with proper ARIA attributes and error messages for accessibility.',
+      },
+    },
+  },
+};
+
+export const CustomStyling: Story = {
+  render: () => (
+    <div className="space-y-6 w-96">
+      <div>
+        <label htmlFor="large-textarea" className="block text-sm font-medium mb-1">
+          Large Text
+        </label>
+
+        <TextArea
+          id="large-textarea"
+          placeholder="Large text size"
+          className="text-lg p-3"
+          rows={4}
+        />
+      </div>
+
+      <div>
+        <label htmlFor="custom-border" className="block text-sm font-medium mb-1">
+          Custom Border
+        </label>
+
+        <TextArea
+          id="custom-border"
+          placeholder="Custom border color"
+          className="border-2 border-purple-500 focus:border-purple-700"
+          rows={4}
+        />
+      </div>
+
+      <div>
+        <label htmlFor="no-rounded" className="block text-sm font-medium mb-1">
+          Square Corners
+        </label>
+
+        <TextArea
+          id="no-rounded"
+          placeholder="No border radius"
+          className="rounded-none"
+          rows={4}
+        />
+      </div>
+
+      <div>
+        <label htmlFor="full-width" className="block text-sm font-medium mb-1">
+          Full Width
+        </label>
+
+        <TextArea
+          id="full-width"
+          placeholder="Full width textarea"
+          className="w-full resize-none"
+          rows={4}
+        />
+      </div>
+    </div>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Examples of custom styling using className prop. The component uses tailwind-merge to properly handle class overrides.',
+      },
+    },
+  },
+};
+
+export const Accessibility: Story = {
+  render: () => (
+    <div className="space-y-6 w-96">
+      <div className="bg-blue-50 border border-blue-200 rounded p-4">
+        <h3 className="font-bold text-blue-800 mb-2">Accessibility Features:</h3>
+
+        <ul className="list-disc list-inside space-y-1 text-blue-700 text-sm">
+          <li>Proper label association with htmlFor/id</li>
+
+          <li>ARIA attributes for error states</li>
+
+          <li>Descriptive error messages</li>
+
+          <li>Keyboard navigation support</li>
+
+          <li>Screen reader compatibility</li>
+
+          <li>Character count announcements</li>
+        </ul>
+      </div>
+
+      <div>
+        <label htmlFor="accessible-textarea" className="block text-sm font-medium mb-1">
+          Accessible Textarea Example
+        </label>
+
+        <TextArea
+          id="accessible-textarea"
+          placeholder="Enter your feedback..."
+          rows={5}
+          aria-describedby="textarea-help"
+          maxLength={500}
+        />
+
+        <p id="textarea-help" className="text-gray-600 text-xs mt-1">
+          Your feedback helps us improve our services. Maximum 500 characters.
+        </p>
+      </div>
+
+      <div>
+        <label htmlFor="accessible-error" className="block text-sm font-medium mb-1">
+          Textarea with Error
+        </label>
+
+        <TextArea
+          id="accessible-error"
+          hasError
+          value="This content needs review..."
+          rows={4}
+          aria-invalid="true"
+          aria-describedby="accessible-error-msg"
+        />
+
+        <p id="accessible-error-msg" className="text-red-600 text-xs mt-1" role="alert">
+          Please provide more specific details in your description.
+        </p>
+      </div>
+    </div>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Comprehensive accessibility example showing proper ARIA attributes, error handling, and screen reader support.',
+      },
+    },
+  },
+};

package/src/components/form/TextArea.test.tsx

@@ -0,0 +1,236 @@
+import { describe, expect, it } from 'vitest';
+
+import { render, screen } from '@testing-library/react';
+
+import { TextArea } from './TextArea';
+
+// Constants for repeated class names
+const ROUNDED_MD = 'rounded-md';
+const BORDER = 'border';
+const P_1 = 'p-1';
+const DISABLED_OPACITY = 'disabled:opacity-60';
+const DISABLED_BG = 'disabled:bg-gray-100';
+const BORDER_ERROR = 'border-error';
+
+describe('TextArea', () => {
+  describe('general', () => {
+    it('renders a textarea element', () => {
+      render(<TextArea />);
+
+      const textarea = screen.getByRole('textbox');
+
+      expect(textarea).toBeInTheDocument();
+      expect(textarea.tagName).toBe('TEXTAREA');
+    });
+
+    it('applies default classes', () => {
+      render(<TextArea />);
+
+      const textarea = screen.getByRole('textbox');
+
+      expect(textarea).toHaveClass(ROUNDED_MD, BORDER, P_1, DISABLED_OPACITY, DISABLED_BG);
+    });
+
+    it('applies error styling when hasError is true', () => {
+      render(<TextArea hasError />);
+
+      const textarea = screen.getByRole('textbox');
+
+      expect(textarea).toHaveClass(BORDER_ERROR);
+    });
+
+    it('does not apply error styling when hasError is false', () => {
+      render(<TextArea hasError={false} />);
+
+      const textarea = screen.getByRole('textbox');
+
+      expect(textarea).not.toHaveClass(BORDER_ERROR);
+    });
+
+    it('does not apply error styling when hasError is undefined', () => {
+      render(<TextArea />);
+
+      const textarea = screen.getByRole('textbox');
+
+      expect(textarea).not.toHaveClass(BORDER_ERROR);
+    });
+
+    it('merges custom className with default classes', () => {
+      render(<TextArea className="custom-class" />);
+
+      const textarea = screen.getByRole('textbox');
+
+      expect(textarea).toHaveClass(ROUNDED_MD, BORDER, P_1, 'custom-class');
+    });
+
+    it('allows custom className to override default classes', () => {
+      render(<TextArea className="p-4" />);
+
+      const textarea = screen.getByRole('textbox');
+
+      expect(textarea).toHaveClass('p-4');
+      expect(textarea).toHaveClass(BORDER); // Base border class remains
+      expect(textarea).not.toHaveClass(P_1); // Overridden by p-4
+    });
+
+    it('forwards standard textarea props', () => {
+      render(
+        <TextArea
+          placeholder="Enter description"
+          value="test content"
+          name="description"
+          id="description-textarea"
+          rows={5}
+          cols={50}
+          readOnly
+        />,
+      );
+
+      const textarea = screen.getByRole('textbox');
+
+      expect(textarea).toHaveAttribute('placeholder', 'Enter description');
+      expect(textarea).toHaveValue('test content'); // Use toHaveValue instead of toHaveAttribute
+      expect(textarea).toHaveAttribute('name', 'description');
+      expect(textarea).toHaveAttribute('id', 'description-textarea');
+      expect(textarea).toHaveAttribute('rows', '5');
+      expect(textarea).toHaveAttribute('cols', '50');
+      expect(textarea).toHaveAttribute('readonly');
+    });
+
+    it('applies disabled styling when disabled', () => {
+      render(<TextArea disabled />);
+
+      const textarea = screen.getByRole('textbox');
+
+      expect(textarea).toBeDisabled();
+      expect(textarea).toHaveClass(DISABLED_OPACITY, DISABLED_BG);
+    });
+
+    it('combines hasError with custom className', () => {
+      render(<TextArea hasError className="w-full" />);
+
+      const textarea = screen.getByRole('textbox');
+
+      expect(textarea).toHaveClass(BORDER_ERROR, 'w-full', ROUNDED_MD, BORDER, P_1);
+    });
+
+    it('supports required attribute', () => {
+      render(<TextArea required />);
+
+      const textarea = screen.getByRole('textbox');
+
+      expect(textarea).toBeRequired();
+    });
+
+    it('supports aria attributes', () => {
+      render(
+        <TextArea
+          aria-label="Description"
+          aria-describedby="description-help"
+          aria-invalid="true"
+        />,
+      );
+
+      const textarea = screen.getByRole('textbox');
+
+      expect(textarea).toHaveAttribute('aria-label', 'Description');
+      expect(textarea).toHaveAttribute('aria-describedby', 'description-help');
+      expect(textarea).toHaveAttribute('aria-invalid', 'true');
+    });
+
+    it('handles complex className override scenarios', () => {
+      render(<TextArea hasError className="border-green-500 p-4" />);
+
+      const textarea = screen.getByRole('textbox');
+
+      // Custom classes should override defaults due to twMerge
+      expect(textarea).toHaveClass('border-green-500', 'p-4');
+      expect(textarea).toHaveClass(ROUNDED_MD); // Default class preserved
+      expect(textarea).toHaveClass(BORDER); // Base border class is still present
+      expect(textarea).not.toHaveClass(P_1); // Overridden by p-4
+      expect(textarea).not.toHaveClass(BORDER_ERROR); // Overridden by border-green-500
+    });
+
+    it('supports textarea-specific attributes', () => {
+      render(<TextArea rows={10} cols={80} wrap="soft" maxLength={500} minLength={10} />);
+
+      const textarea = screen.getByRole('textbox');
+
+      expect(textarea).toHaveAttribute('rows', '10');
+      expect(textarea).toHaveAttribute('cols', '80');
+      expect(textarea).toHaveAttribute('wrap', 'soft');
+      expect(textarea).toHaveAttribute('maxlength', '500');
+      expect(textarea).toHaveAttribute('minlength', '10');
+    });
+  });
+
+  describe('accessibility', () => {
+    it('is accessible by role', () => {
+      render(<TextArea />);
+
+      expect(screen.getByRole('textbox')).toBeInTheDocument();
+    });
+
+    it('supports form labels via id', () => {
+      render(
+        <>
+          <label htmlFor="test-textarea">Description</label>
+
+          <TextArea id="test-textarea" />
+        </>,
+      );
+
+      const textarea = screen.getByLabelText('Description');
+
+      expect(textarea).toBeInTheDocument();
+      expect(textarea.tagName).toBe('TEXTAREA');
+    });
+
+    it('supports error state for screen readers', () => {
+      render(<TextArea hasError aria-invalid="true" />);
+
+      const textarea = screen.getByRole('textbox');
+
+      expect(textarea).toHaveAttribute('aria-invalid', 'true');
+      expect(textarea).toHaveClass(BORDER_ERROR);
+    });
+
+    it('supports textarea with associated help text', () => {
+      render(
+        <>
+          <label htmlFor="description">Description</label>
+
+          <TextArea id="description" aria-describedby="description-help" />
+
+          <div id="description-help">Please provide a detailed description</div>
+        </>,
+      );
+
+      const textarea = screen.getByLabelText('Description');
+
+      expect(textarea).toHaveAttribute('aria-describedby', 'description-help');
+    });
+  });
+
+  describe('form integration', () => {
+    it('works with controlled components', () => {
+      const { rerender } = render(<TextArea value="initial value" readOnly />);
+
+      let textarea = screen.getByRole('textbox');
+
+      expect(textarea).toHaveValue('initial value');
+
+      rerender(<TextArea value="updated value" readOnly />);
+      textarea = screen.getByRole('textbox');
+      expect(textarea).toHaveValue('updated value');
+    });
+
+    it('supports placeholder text', () => {
+      render(<TextArea placeholder="Enter your thoughts here..." />);
+
+      const textarea = screen.getByPlaceholderText('Enter your thoughts here...');
+
+      expect(textarea).toBeInTheDocument();
+    });
+  });
+});