@tribepad/themis 1.0.0

package/src/elements/FormLayout/FormLayout.stories.tsx

@@ -0,0 +1,637 @@
+/**
+ * FormLayout Storybook Stories
+ * Interactive documentation for all FormLayout variants
+ *
+ * @see FormLayout-tasks.md T011
+ * @see FormLayout-design-decisions.md (Visual specifications)
+ */
+
+import type { Meta, StoryObj } from '@storybook/nextjs';
+import { FormLayout } from './FormLayout';
+import { Button } from '../Button/Button';
+import { TextField } from '../TextField/TextField';
+
+const meta = {
+  title: 'Elements/FormLayout',
+  component: FormLayout,
+  parameters: {
+    layout: 'padded',
+    docs: {
+      description: {
+        component: `
+FormLayout provides consistent structure for forms with semantic HTML and accessibility.
+
+**Features:**
+- Configurable heading hierarchy (h1-h6)
+- Optional description text
+- Required field explanation (always visible)
+- Single or double column layouts (responsive)
+- Three density variants (compact, default, comfortable)
+- Optional actions footer
+- **Form-level error messages** (red alert styling)
+- **Form-level success messages** (green checkmark styling)
+- **Auto-hide success messages** (configurable duration)
+- WCAG 2.2 AAA compliant
+- Semantic HTML5 elements
+
+**Design Decisions:**
+- Visual order: Error/Success Messages → Title → Description (optional) → Required Note
+- Error messages use \`role="alert"\` with \`aria-live="assertive"\`
+- Success messages use \`role="status"\` with \`aria-live="polite"\`
+- Success messages can auto-hide after configurable duration
+- Actions: space-between on desktop, stacked on mobile
+- No max-width constraint (parent controls)
+- Plain text required note (no icons)
+        `,
+      },
+    },
+  },
+  tags: ['autodocs'],
+  argTypes: {
+    title: {
+      control: 'text',
+      description: 'Form title (required)',
+    },
+    requiredNote: {
+      control: 'text',
+      description: 'Explanation of required field indicators (required)',
+    },
+    description: {
+      control: 'text',
+      description: 'Form description/explanation (optional)',
+    },
+    columns: {
+      control: 'radio',
+      options: [1, 2],
+      description: 'Number of columns for form fields (1 or 2)',
+    },
+    headingLevel: {
+      control: 'select',
+      options: [1, 2, 3, 4, 5, 6],
+      description: 'Semantic heading level for title (h1-h6)',
+    },
+    density: {
+      control: 'radio',
+      options: ['default', 'compact', 'comfortable'],
+      description: 'Spacing between form fields',
+    },
+    errorMessage: {
+      control: 'text',
+      description: 'Form-level error message (optional)',
+    },
+    successMessage: {
+      control: 'text',
+      description: 'Form-level success message (optional)',
+    },
+    autoHideSuccess: {
+      control: 'boolean',
+      description: 'Auto-hide success message after duration',
+    },
+    autoHideDuration: {
+      control: 'number',
+      description: 'Duration in milliseconds before auto-hiding success message (default: 5000)',
+    },
+  },
+} satisfies Meta<typeof FormLayout>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/**
+ * Default FormLayout with minimal required props
+ * Single column layout with standard density
+ */
+export const Default: Story = {
+  args: {
+    title: 'Contact Form',
+    requiredNote: 'Required fields are marked with *',
+    children: (
+      <>
+        <TextField label="Name" isRequired />
+        <TextField label="Email" type="email" isRequired />
+        <TextField label="Message" />
+      </>
+    ),
+  },
+};
+
+/**
+ * FormLayout with optional description text
+ */
+export const WithDescription: Story = {
+  args: {
+    title: 'Create Account',
+    requiredNote: '* indicates required field',
+    description: 'Fill in your details to create a new account. All information is kept secure.',
+    children: (
+      <>
+        <TextField label="Full Name" isRequired />
+        <TextField label="Email Address" type="email" isRequired />
+        <TextField label="Password" type="password" isRequired />
+        <TextField label="Confirm Password" type="password" isRequired />
+      </>
+    ),
+  },
+};
+
+/**
+ * FormLayout without description (minimal)
+ */
+export const WithoutDescription: Story = {
+  args: {
+    title: 'Quick Form',
+    requiredNote: '* indicates required',
+    children: (
+      <>
+        <TextField label="Name" isRequired />
+        <TextField label="Email" type="email" isRequired />
+      </>
+    ),
+  },
+};
+
+/**
+ * FormLayout with action buttons in footer
+ * Shows space-between alignment (Cancel left, Submit right)
+ */
+export const WithActions: Story = {
+  args: {
+    title: 'Registration Form',
+    requiredNote: 'Required fields are marked with *',
+    description: 'Complete all required fields to register.',
+    children: (
+      <>
+        <TextField label="Username" isRequired />
+        <TextField label="Email" type="email" isRequired />
+        <TextField label="Password" type="password" isRequired />
+      </>
+    ),
+    actions: (
+      <>
+        <Button variant="outline">Cancel</Button>
+        <Button type="submit">Create Account</Button>
+      </>
+    ),
+  },
+};
+
+/**
+ * FormLayout without actions footer
+ */
+export const WithoutActions: Story = {
+  args: {
+    title: 'Profile Information',
+    requiredNote: 'Required fields are marked with *',
+    children: (
+      <>
+        <TextField label="Display Name" isRequired />
+        <TextField label="Bio" />
+        <TextField label="Website" type="url" />
+      </>
+    ),
+  },
+};
+
+/**
+ * Double column layout (responsive)
+ * Single column on mobile, double on tablet/desktop (md breakpoint)
+ */
+export const DoubleColumn: Story = {
+  args: {
+    title: 'User Information',
+    requiredNote: '* indicates required field',
+    description: 'Please provide your contact information.',
+    columns: 2,
+    children: (
+      <>
+        <TextField label="First Name" isRequired />
+        <TextField label="Last Name" isRequired />
+        <TextField label="Email" type="email" isRequired />
+        <TextField label="Company" />
+        <TextField label="Job Title" />
+      </>
+    ),
+    actions: (
+      <>
+        <Button variant="ghost">Cancel</Button>
+        <Button>Save Changes</Button>
+      </>
+    ),
+  },
+};
+
+/**
+ * Single column layout (explicit)
+ */
+export const SingleColumn: Story = {
+  args: {
+    title: 'Feedback Form',
+    requiredNote: 'Required fields are marked with *',
+    columns: 1,
+    children: (
+      <>
+        <TextField label="Name" isRequired />
+        <TextField label="Email" type="email" isRequired />
+        <TextField label="Subject" isRequired />
+        <TextField label="Message" isRequired />
+      </>
+    ),
+  },
+};
+
+/**
+ * Compact density (smaller gaps between fields)
+ * Best for space-constrained layouts
+ */
+export const CompactDensity: Story = {
+  args: {
+    title: 'Login',
+    requiredNote: '* indicates required',
+    density: 'compact',
+    children: (
+      <>
+        <TextField label="Email" type="email" isRequired />
+        <TextField label="Password" type="password" isRequired />
+      </>
+    ),
+    actions: (
+      <>
+        <Button variant="link">Forgot password?</Button>
+        <Button>Sign In</Button>
+      </>
+    ),
+  },
+};
+
+/**
+ * Default density (standard gaps)
+ */
+export const DefaultDensity: Story = {
+  args: {
+    title: 'Settings',
+    requiredNote: 'Required fields are marked with *',
+    density: 'default',
+    children: (
+      <>
+        <TextField label="Display Name" isRequired />
+        <TextField label="Email" type="email" isRequired />
+        <TextField label="Bio" />
+      </>
+    ),
+  },
+};
+
+/**
+ * Comfortable density (larger gaps)
+ * Best for forms with more breathing room
+ */
+export const ComfortableDensity: Story = {
+  args: {
+    title: 'Contact Preferences',
+    requiredNote: '* indicates required field',
+    density: 'comfortable',
+    children: (
+      <>
+        <TextField label="Preferred Name" />
+        <TextField label="Contact Email" type="email" isRequired />
+      </>
+    ),
+  },
+};
+
+/**
+ * Different heading levels (h1-h6)
+ * Demonstrates proper heading hierarchy
+ */
+export const HeadingLevel1: Story = {
+  args: {
+    title: 'Main Registration',
+    requiredNote: 'Required fields are marked with *',
+    headingLevel: 1,
+    children: (
+      <>
+        <TextField label="Name" isRequired />
+        <TextField label="Email" type="email" isRequired />
+      </>
+    ),
+  },
+};
+
+export const HeadingLevel3: Story = {
+  args: {
+    title: 'Section Form',
+    requiredNote: 'Required fields are marked with *',
+    headingLevel: 3,
+    children: (
+      <>
+        <TextField label="Name" isRequired />
+        <TextField label="Email" type="email" isRequired />
+      </>
+    ),
+  },
+};
+
+/**
+ * Complex form with all features
+ * Double column, with description, with actions, comfortable density
+ */
+export const ComplexForm: Story = {
+  args: {
+    title: 'Employee Registration',
+    requiredNote: '* indicates required field',
+    description: 'Please fill out all required information for the new employee.',
+    columns: 2,
+    density: 'comfortable',
+    headingLevel: 1,
+    children: (
+      <>
+        <TextField label="First Name" isRequired />
+        <TextField label="Last Name" isRequired />
+        <TextField label="Email" type="email" isRequired />
+        <TextField label="Department" isRequired />
+        <TextField label="Job Title" isRequired />
+        <TextField label="Manager" />
+      </>
+    ),
+    actions: (
+      <>
+        <Button variant="outline">Cancel</Button>
+        <Button>Submit Registration</Button>
+      </>
+    ),
+  },
+};
+
+/**
+ * Minimal form (bare essentials)
+ */
+export const MinimalForm: Story = {
+  args: {
+    title: 'Subscribe',
+    requiredNote: '* required',
+    children: <TextField label="Email" type="email" isRequired />,
+    actions: <Button>Subscribe</Button>,
+  },
+};
+
+/**
+ * Form with many fields (demonstrates scrolling)
+ */
+export const ManyFields: Story = {
+  args: {
+    title: 'Detailed Profile',
+    requiredNote: 'Required fields are marked with *',
+    description: 'Please provide as much information as possible.',
+    columns: 2,
+    children: (
+      <>
+        <TextField label="First Name" isRequired />
+        <TextField label="Last Name" isRequired />
+        <TextField label="Email" type="email" isRequired />
+        <TextField label="Address Line 1" isRequired />
+        <TextField label="Address Line 2" />
+        <TextField label="City" isRequired />
+        <TextField label="State/Province" isRequired />
+        <TextField label="Postal Code" isRequired />
+        <TextField label="Country" isRequired />
+        <TextField label="Occupation" />
+        <TextField label="Company" />
+        <TextField label="Website" type="url" />
+      </>
+    ),
+    actions: (
+      <>
+        <Button variant="outline">Reset Form</Button>
+        <Button>Save Profile</Button>
+      </>
+    ),
+  },
+};
+
+/**
+ * High contrast theme variant
+ */
+export const HighContrast: Story = {
+  args: {
+    title: 'High Contrast Form',
+    requiredNote: 'Required fields are marked with *',
+    description: 'Form displayed in high contrast mode for better visibility.',
+    children: (
+      <>
+        <TextField label="Name" isRequired />
+        <TextField label="Email" type="email" isRequired />
+        <TextField label="Message" />
+      </>
+    ),
+    actions: (
+      <>
+        <Button variant="outline">Cancel</Button>
+        <Button>Submit</Button>
+      </>
+    ),
+  },
+  parameters: {
+    // This would be configured in Storybook to show high contrast theme
+    backgrounds: { default: 'dark' },
+  },
+};
+
+/**
+ * Colorblind-friendly theme variant
+ */
+export const Colorblind: Story = {
+  args: {
+    title: 'Accessible Form',
+    requiredNote: '* indicates required field',
+    description: 'Form optimized for colorblind users.',
+    children: (
+      <>
+        <TextField label="Name" isRequired />
+        <TextField label="Email" type="email" isRequired />
+      </>
+    ),
+    actions: <Button>Submit</Button>,
+  },
+};
+
+/**
+ * Custom styling example
+ */
+export const CustomStyling: Story = {
+  args: {
+    title: 'Custom Styled Form',
+    requiredNote: 'Required fields are marked with *',
+    className: 'max-w-2xl mx-auto p-6 border border-gray-200 rounded-lg shadow-sm',
+    children: (
+      <>
+        <TextField label="Name" isRequired />
+        <TextField label="Email" type="email" isRequired />
+      </>
+    ),
+    actions: <Button>Submit</Button>,
+  },
+};
+
+/**
+ * Error message display
+ * Shows form-level error with red styling and alert icon
+ */
+export const WithErrorMessage: Story = {
+  args: {
+    title: 'Login Form',
+    requiredNote: 'Required fields are marked with *',
+    errorMessage: 'Invalid email or password. Please try again.',
+    children: (
+      <>
+        <TextField label="Email" type="email" isRequired />
+        <TextField label="Password" type="password" isRequired />
+      </>
+    ),
+    actions: (
+      <>
+        <Button variant="link">Forgot password?</Button>
+        <Button>Sign In</Button>
+      </>
+    ),
+  },
+};
+
+/**
+ * Success message display
+ * Shows form-level success with green styling and checkmark icon
+ */
+export const WithSuccessMessage: Story = {
+  args: {
+    title: 'Profile Updated',
+    requiredNote: 'Required fields are marked with *',
+    successMessage: 'Your profile has been successfully updated.',
+    children: (
+      <>
+        <TextField label="Display Name" isRequired />
+        <TextField label="Email" type="email" isRequired />
+        <TextField label="Bio" />
+      </>
+    ),
+    actions: (
+      <>
+        <Button variant="outline">Cancel</Button>
+        <Button>Save Changes</Button>
+      </>
+    ),
+  },
+};
+
+/**
+ * Both error and success messages
+ * Demonstrates simultaneous display (error appears first)
+ */
+export const WithBothMessages: Story = {
+  args: {
+    title: 'Form Status',
+    requiredNote: 'Required fields are marked with *',
+    errorMessage: 'Some fields contain errors. Please review and correct them.',
+    successMessage: 'Previous changes were saved successfully.',
+    children: (
+      <>
+        <TextField label="Username" isRequired />
+        <TextField label="Email" type="email" isRequired />
+      </>
+    ),
+    actions: <Button>Update</Button>,
+  },
+};
+
+/**
+ * Auto-hide success message (default duration: 5 seconds)
+ * Success message disappears automatically after specified duration
+ */
+export const WithAutoHideSuccess: Story = {
+  args: {
+    title: 'Quick Notification',
+    requiredNote: 'Required fields are marked with *',
+    successMessage: 'Form submitted successfully! This message will disappear in 5 seconds.',
+    autoHideSuccess: true,
+    children: (
+      <>
+        <TextField label="Name" isRequired />
+        <TextField label="Email" type="email" isRequired />
+      </>
+    ),
+    actions: <Button>Submit</Button>,
+  },
+};
+
+/**
+ * Auto-hide success message with custom duration (2 seconds)
+ * Faster auto-hide for quick feedback
+ */
+export const WithCustomAutoHideDuration: Story = {
+  args: {
+    title: 'Quick Feedback',
+    requiredNote: 'Required fields are marked with *',
+    successMessage: 'Saved! This message will disappear in 2 seconds.',
+    autoHideSuccess: true,
+    autoHideDuration: 2000,
+    children: (
+      <>
+        <TextField label="Setting" isRequired />
+        <TextField label="Value" />
+      </>
+    ),
+    actions: <Button>Save</Button>,
+  },
+};
+
+/**
+ * Long error message
+ * Tests layout with longer error text
+ */
+export const WithLongErrorMessage: Story = {
+  args: {
+    title: 'Registration Failed',
+    requiredNote: 'Required fields are marked with *',
+    errorMessage: 'Unable to create your account at this time. The email address you provided is already in use. Please try a different email address or use the "Forgot Password" link if you already have an account.',
+    children: (
+      <>
+        <TextField label="Full Name" isRequired />
+        <TextField label="Email" type="email" isRequired />
+        <TextField label="Password" type="password" isRequired />
+      </>
+    ),
+    actions: (
+      <>
+        <Button variant="outline">Cancel</Button>
+        <Button>Try Again</Button>
+      </>
+    ),
+  },
+};
+
+/**
+ * Error message with double column layout
+ * Shows error messages work well with multi-column forms
+ */
+export const ErrorWithDoubleColumn: Story = {
+  args: {
+    title: 'Payment Information',
+    requiredNote: '* indicates required field',
+    errorMessage: 'Payment processing failed. Please check your card details and try again.',
+    columns: 2,
+    children: (
+      <>
+        <TextField label="Cardholder Name" isRequired />
+        <TextField label="Card Number" isRequired />
+        <TextField label="Expiry Date" isRequired />
+        <TextField label="CVV" isRequired />
+        <TextField label="Billing Address" isRequired />
+        <TextField label="Postal Code" isRequired />
+      </>
+    ),
+    actions: (
+      <>
+        <Button variant="outline">Cancel</Button>
+        <Button>Process Payment</Button>
+      </>
+    ),
+  },
+};