@tribepad/themis 1.0.0

package/src/elements/NumberField/NumberField.stories.tsx

@@ -0,0 +1,678 @@
+/**
+ * NumberField Component Stories
+ * Storybook stories for NumberField component demonstrating all variants, sizes, and states
+ *
+ * @see numberfield-prd.md for full requirements
+ */
+
+import { useState, type FormEventHandler } from 'react';
+import type { Meta, StoryObj } from '@storybook/nextjs';
+import { NumberField } from './index';
+
+const meta = {
+  title: 'Elements/NumberField',
+  component: NumberField,
+  parameters: {
+    layout: 'centered',
+    docs: {
+      description: {
+        component:
+          'Accessible numeric input component with optional stepper buttons. Built with React Aria NumberField primitive for WCAG 2.2 AAA compliance (7:1 contrast ratio, 44x44px touch targets). Supports locale-aware formatting, constraints, and keyboard navigation.',
+      },
+    },
+  },
+  tags: ['autodocs'],
+  argTypes: {
+    size: {
+      control: 'select',
+      options: ['sm', 'default', 'lg'],
+      description: 'NumberField size variant',
+      table: {
+        defaultValue: { summary: 'default' },
+      },
+    },
+    stepperLayout: {
+      control: 'select',
+      options: ['sides', 'stacked', 'hidden'],
+      description: 'Layout of stepper buttons',
+      table: {
+        defaultValue: { summary: 'sides' },
+      },
+    },
+    label: {
+      control: 'text',
+      description: 'Label text for the number field (required)',
+    },
+    description: {
+      control: 'text',
+      description: 'Helper text displayed below the input',
+    },
+    errorMessage: {
+      control: 'text',
+      description: 'Error message displayed when isInvalid is true',
+    },
+    minValue: {
+      control: 'number',
+      description: 'Minimum allowed value',
+      table: {
+        defaultValue: { summary: '0' },
+      },
+    },
+    maxValue: {
+      control: 'number',
+      description: 'Maximum allowed value',
+      table: {
+        defaultValue: { summary: '4294967295' },
+      },
+    },
+    step: {
+      control: 'number',
+      description: 'Step increment for stepper buttons and arrow keys',
+      table: {
+        defaultValue: { summary: '1' },
+      },
+    },
+    allowNegative: {
+      control: 'boolean',
+      description: 'Allow negative numbers (sets minValue to -2147483647)',
+    },
+    isRequired: {
+      control: 'boolean',
+      description: 'Shows required indicator and sets aria-required',
+    },
+    isReadOnly: {
+      control: 'boolean',
+      description: 'Makes input read-only (hides stepper buttons)',
+    },
+    isDisabled: {
+      control: 'boolean',
+      description: 'Disables the input',
+    },
+    isInvalid: {
+      control: 'boolean',
+      description: 'Shows error styling and displays error message',
+    },
+  },
+} satisfies Meta<typeof NumberField>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// =============================================================================
+// Basic Stories
+// =============================================================================
+
+export const Default: Story = {
+  args: {
+    label: 'Quantity',
+  },
+};
+
+export const WithDefaultValue: Story = {
+  args: {
+    label: 'Quantity',
+    defaultValue: 42,
+    description: 'Pre-filled with default value',
+  },
+};
+
+export const WithDescription: Story = {
+  args: {
+    label: 'Items',
+    description: 'Enter the number of items to order',
+  },
+};
+
+export const WithError: Story = {
+  args: {
+    label: 'Quantity',
+    isInvalid: true,
+    errorMessage: 'Quantity must be at least 1',
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Error state with validation message. Uses destructive styling for border and text.',
+      },
+    },
+  },
+};
+
+export const Required: Story = {
+  args: {
+    label: 'Quantity',
+    isRequired: true,
+    description: 'This field is required',
+  },
+};
+
+export const Disabled: Story = {
+  args: {
+    label: 'Quantity',
+    defaultValue: 10,
+    isDisabled: true,
+  },
+};
+
+export const ReadOnly: Story = {
+  args: {
+    label: 'Order Total',
+    defaultValue: 150,
+    isReadOnly: true,
+    description: 'This value cannot be changed',
+  },
+};
+
+// =============================================================================
+// Stepper Layout Stories
+// =============================================================================
+
+export const StepperSides: Story = {
+  args: {
+    label: 'Quantity',
+    stepperLayout: 'sides',
+    defaultValue: 5,
+    description: 'Default layout with buttons on sides',
+  },
+};
+
+export const StepperStacked: Story = {
+  args: {
+    label: 'Quantity',
+    stepperLayout: 'stacked',
+    defaultValue: 5,
+    description: 'Buttons stacked vertically on right',
+  },
+};
+
+export const StepperHidden: Story = {
+  args: {
+    label: 'Account Number',
+    stepperLayout: 'hidden',
+    description: 'No stepper buttons (keyboard and typing only)',
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Hidden stepper layout for numeric inputs that should not have increment/decrement buttons.',
+      },
+    },
+  },
+};
+
+export const AllStepperLayouts: Story = {
+  render: () => (
+    <div className="flex flex-col gap-6 w-80">
+      <NumberField
+        label="Sides (Default)"
+        stepperLayout="sides"
+        defaultValue={10}
+      />
+      <NumberField
+        label="Stacked"
+        stepperLayout="stacked"
+        defaultValue={10}
+      />
+      <NumberField
+        label="Hidden"
+        stepperLayout="hidden"
+        defaultValue={10}
+      />
+    </div>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'Comparison of all stepper layout options.',
+      },
+    },
+  },
+};
+
+// =============================================================================
+// Size Variants Stories
+// =============================================================================
+
+export const Small: Story = {
+  args: {
+    label: 'Count',
+    size: 'sm',
+    defaultValue: 5,
+    description: 'Compact size (36px height)',
+  },
+};
+
+export const Large: Story = {
+  args: {
+    label: 'Count',
+    size: 'lg',
+    defaultValue: 5,
+    description: 'Large size (48px height)',
+  },
+};
+
+export const AllSizes: Story = {
+  render: () => (
+    <div className="flex flex-col gap-6 w-80">
+      <NumberField label="Small" size="sm" defaultValue={10} />
+      <NumberField label="Default" size="default" defaultValue={20} />
+      <NumberField label="Large" size="lg" defaultValue={30} />
+    </div>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'All 3 size variants: sm (36px), default (40px), lg (48px). All meet WCAG 2.2 touch target requirements.',
+      },
+    },
+  },
+};
+
+// =============================================================================
+// Constraint Stories
+// =============================================================================
+
+export const WithMinMax: Story = {
+  args: {
+    label: 'Rating',
+    minValue: 1,
+    maxValue: 10,
+    defaultValue: 5,
+    description: 'Value constrained between 1 and 10',
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Min/max constraints. Stepper buttons disable at boundaries.',
+      },
+    },
+  },
+};
+
+export const WithStep: Story = {
+  args: {
+    label: 'Quantity',
+    step: 5,
+    defaultValue: 10,
+    description: 'Increments by 5',
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Custom step value. Arrow keys and buttons increment/decrement by this amount.',
+      },
+    },
+  },
+};
+
+export const AllowNegative: Story = {
+  args: {
+    label: 'Temperature',
+    allowNegative: true,
+    defaultValue: 0,
+    description: 'Allows values down to -2147483647',
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Enable negative numbers. Sets minValue to -2147483647 (INT32_MIN + 1).',
+      },
+    },
+  },
+};
+
+// =============================================================================
+// Formatting Stories
+// =============================================================================
+
+export const CurrencyFormatting: Story = {
+  args: {
+    label: 'Price',
+    defaultValue: 99.99,
+    step: 0.01,
+    formatOptions: { style: 'currency', currency: 'USD' },
+    description: 'Formatted as USD currency',
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Currency formatting with Intl.NumberFormat. onChange receives the raw numeric value.',
+      },
+    },
+  },
+};
+
+export const PercentageFormatting: Story = {
+  args: {
+    label: 'Discount',
+    defaultValue: 0.15,
+    step: 0.01,
+    minValue: 0,
+    maxValue: 1,
+    formatOptions: { style: 'percent' },
+    description: 'Formatted as percentage',
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Percentage formatting. Value of 0.15 displays as 15%.',
+      },
+    },
+  },
+};
+
+export const DecimalFormatting: Story = {
+  args: {
+    label: 'Weight',
+    defaultValue: 2.5,
+    step: 0.1,
+    formatOptions: { minimumFractionDigits: 2, maximumFractionDigits: 2 },
+    description: 'Always shows 2 decimal places',
+  },
+};
+
+export const LargeNumbers: Story = {
+  args: {
+    label: 'Revenue',
+    defaultValue: 1500000,
+    formatOptions: { notation: 'compact', compactDisplay: 'short' },
+    description: 'Compact notation for large numbers',
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Compact notation displays large numbers as 1.5M, 2K, etc.',
+      },
+    },
+  },
+};
+
+export const WithGrouping: Story = {
+  args: {
+    label: 'Population',
+    defaultValue: 1234567,
+    step: 1000,
+    description: 'Large number with thousand separators',
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Default locale formatting includes thousand separators.',
+      },
+    },
+  },
+};
+
+// =============================================================================
+// Form Integration Stories
+// =============================================================================
+
+export const WithFormName: Story = {
+  args: {
+    label: 'Quantity',
+    name: 'quantity',
+    defaultValue: 1,
+    description: 'Creates a hidden input for form submission',
+  },
+};
+
+export const FormExample: Story = {
+  render: () => {
+    const handleSubmit: FormEventHandler = (e) => {
+      e.preventDefault();
+      const form = e.currentTarget;
+      const formData = new FormData(form as unknown as globalThis.HTMLFormElement);
+      alert(`Quantity: ${formData.get('quantity')}\nPrice: ${formData.get('price')}`);
+    };
+
+    return (
+      <form onSubmit={handleSubmit} className="flex flex-col gap-4 w-80">
+        <NumberField
+          label="Quantity"
+          name="quantity"
+          defaultValue={1}
+          minValue={1}
+          isRequired
+        />
+        <NumberField
+          label="Price per Item"
+          name="price"
+          defaultValue={9.99}
+          step={0.01}
+          formatOptions={{ style: 'currency', currency: 'USD' }}
+          isRequired
+        />
+        <button
+          type="submit"
+          className="mt-2 rounded-md bg-[var(--primary)] px-4 py-2 text-sm font-medium text-[var(--primary-foreground)]"
+        >
+          Submit Order
+        </button>
+      </form>
+    );
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Form integration example. Submit to see the serialized values.',
+      },
+    },
+  },
+};
+
+// =============================================================================
+// Controlled Mode Stories
+// =============================================================================
+
+export const ControlledMode: Story = {
+  render: () => {
+    const [quantity, setQuantity] = useState<number | null>(10);
+
+    return (
+      <div className="flex flex-col gap-4 w-80">
+        <NumberField
+          label="Quantity"
+          value={quantity}
+          onChange={setQuantity}
+          minValue={0}
+          maxValue={100}
+        />
+        <p className="text-sm text-[var(--muted-foreground)]">
+          Selected: {quantity ?? 'None'}
+        </p>
+        <div className="flex gap-2">
+          <button
+            type="button"
+            onClick={() => setQuantity(0)}
+            className="rounded-md bg-[var(--secondary)] px-3 py-1 text-sm"
+          >
+            Reset to 0
+          </button>
+          <button
+            type="button"
+            onClick={() => setQuantity(50)}
+            className="rounded-md bg-[var(--secondary)] px-3 py-1 text-sm"
+          >
+            Set to 50
+          </button>
+        </div>
+      </div>
+    );
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Controlled mode with external state management.',
+      },
+    },
+  },
+};
+
+// =============================================================================
+// All States Stories
+// =============================================================================
+
+export const AllStates: Story = {
+  render: () => (
+    <div className="flex flex-col gap-6 w-80">
+      <NumberField label="Default" />
+      <NumberField label="With Value" defaultValue={42} />
+      <NumberField label="Required" isRequired description="This field is required" />
+      <NumberField label="Invalid" isInvalid errorMessage="Value is out of range" />
+      <NumberField label="Disabled" isDisabled defaultValue={10} />
+      <NumberField label="Read-only" isReadOnly defaultValue={100} />
+    </div>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'All state variants: default, with value, required, invalid, disabled, and read-only.',
+      },
+    },
+  },
+};
+
+// =============================================================================
+// Real-World Examples
+// =============================================================================
+
+export const ShoppingCart: Story = {
+  render: () => {
+    const [quantity, setQuantity] = useState<number | null>(1);
+    const unitPrice = 29.99;
+    const total = (quantity ?? 0) * unitPrice;
+
+    return (
+      <div className="flex flex-col gap-4 w-96 p-4 border rounded-lg border-[var(--border)]">
+        <h3 className="text-lg font-semibold">Product Name</h3>
+        <p className="text-sm text-[var(--muted-foreground)]">
+          ${unitPrice.toFixed(2)} each
+        </p>
+        <NumberField
+          label="Quantity"
+          value={quantity}
+          onChange={setQuantity}
+          minValue={1}
+          maxValue={99}
+        />
+        <div className="flex justify-between pt-2 border-t border-[var(--border)]">
+          <span className="font-medium">Total:</span>
+          <span className="font-bold">${total.toFixed(2)}</span>
+        </div>
+      </div>
+    );
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Shopping cart quantity selector with dynamic total calculation.',
+      },
+    },
+  },
+};
+
+export const TemperatureControl: Story = {
+  render: () => {
+    const [temp, setTemp] = useState<number | null>(22);
+
+    return (
+      <div className="flex flex-col gap-4 w-80 items-center">
+        <h3 className="text-lg font-semibold">Thermostat</h3>
+        <NumberField
+          label="Temperature"
+          value={temp}
+          onChange={setTemp}
+          minValue={10}
+          maxValue={35}
+          size="lg"
+          formatOptions={{ style: 'unit', unit: 'celsius' }}
+        />
+        <p className="text-4xl font-mono">{temp}°C</p>
+      </div>
+    );
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Temperature control with unit formatting.',
+      },
+    },
+  },
+};
+
+export const AgeInput: Story = {
+  args: {
+    label: 'Age',
+    minValue: 0,
+    maxValue: 150,
+    defaultValue: 25,
+    description: 'Enter your age in years',
+  },
+};
+
+// =============================================================================
+// Accessibility Stories
+// =============================================================================
+
+export const KeyboardNavigation: Story = {
+  render: () => (
+    <div className="flex flex-col gap-4 w-80">
+      <NumberField label="First Field" defaultValue={10} />
+      <NumberField label="Second Field" defaultValue={20} />
+      <NumberField label="Disabled" isDisabled defaultValue={30} />
+      <NumberField label="Third Field" defaultValue={40} />
+      <p className="text-sm text-[var(--muted-foreground)]">
+        Use Tab to move between fields. Arrow Up/Down to change values.
+        Disabled fields are skipped.
+      </p>
+    </div>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'Full keyboard navigation support. Tab between fields, Arrow keys to change values.',
+      },
+    },
+  },
+};
+
+export const CustomAriaLabels: Story = {
+  args: {
+    label: 'Guests',
+    defaultValue: 2,
+    incrementAriaLabel: 'Add one more guest',
+    decrementAriaLabel: 'Remove one guest',
+    description: 'Custom aria-labels for screen readers',
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Custom aria-labels for stepper buttons. Improves screen reader experience.',
+      },
+    },
+  },
+};
+
+// =============================================================================
+// Playground
+// =============================================================================
+
+export const Playground: Story = {
+  args: {
+    label: 'Playground',
+    defaultValue: 10,
+    description: 'Try all the controls!',
+    size: 'default',
+    stepperLayout: 'sides',
+    step: 1,
+    minValue: 0,
+    maxValue: 100,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Interactive playground with all controls available.',
+      },
+    },
+  },
+};