@fpkit/acss 0.5.12 → 0.6.0

package/src/components/cards/card.stories.tsx

@@ -1,20 +1,39 @@
 import { StoryObj, Meta } from "@storybook/react-vite";
-// import { within, userEvent, screen } from "storybook/test";
-
 import Card from "./card";
-// import './card.scss'
 
 const content =
   "Enim aliquip excepteur veniam esse culpa. Et exercitation incididunt occaecat incididunt proident consectetur. Voluptate elit reprehenderit nulla reprehenderit excepteur tempor adipisicing officia eiusmod est id aute. Nisi do et nulla fugiat enim id pariatur ex. Culpa aliquip excepteur velit fugiat qui magna deserunt adipisicing dolore quis. Esse proident qui consectetur Lorem id fugiat elit amet proident enim deserunt dolore sit.";
 
 const meta: Meta<typeof Card> = {
   title: "FP.REACT Components/Card",
-  tags: ["rc"],
+  tags: ["rc", "autodocs"],
   component: Card,
   args: {
     children: <p>{content}</p>,
   },
-} as Story;
+  argTypes: {
+    as: {
+      control: 'select',
+      options: ['div', 'article', 'section', 'aside'],
+      description: 'HTML element to render',
+    },
+    interactive: {
+      control: 'boolean',
+      description: 'Enable keyboard navigation and button semantics',
+    },
+    role: {
+      control: 'text',
+      description: 'ARIA role attribute',
+    },
+  },
+  parameters: {
+    docs: {
+      description: {
+        component: 'A flexible, accessible card component with compound component pattern. Supports polymorphic rendering, interactive variants, and WCAG 2.1 AA compliance.',
+      },
+    },
+  },
+} as Meta<typeof Card>;
 
 export default meta;
 type Story = StoryObj<typeof Card>;
@@ -145,3 +164,146 @@ export const FlexibleContent: Story = {
     </div>
   ),
 } as Story;
+
+/**
+ * Interactive Card - Demonstrates clickable card with keyboard navigation
+ */
+export const InteractiveCard: Story = {
+  args: {
+    interactive: true,
+    'aria-label': 'View product details',
+  },
+  render: (args) => (
+    <Card
+      {...args}
+      onClick={() => alert('Card clicked!')}
+      style={{ cursor: 'pointer' }}
+    >
+      <Card.Title>Interactive Product Card</Card.Title>
+      <Card.Content>
+        <p>
+          This card is fully interactive! Click anywhere or use your keyboard
+          (Tab to focus, Enter or Space to activate) to trigger the action.
+        </p>
+        <p style={{ fontSize: '0.875rem', color: '#666', marginTop: '0.5rem' }}>
+          Try it: Tab to focus this card, then press Enter or Space.
+        </p>
+      </Card.Content>
+      <Card.Footer>
+        <span style={{ color: '#007bff', fontWeight: 'bold' }}>
+          Click to learn more →
+        </span>
+      </Card.Footer>
+    </Card>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'Interactive cards support full keyboard navigation (Enter/Space keys) and automatically receive proper ARIA attributes for accessibility.',
+      },
+    },
+  },
+} as Story;
+
+/**
+ * Accessible Card with ARIA - Demonstrates proper ARIA labeling
+ */
+export const AccessibleCard: Story = {
+  render: () => (
+    <Card as="article" aria-labelledby="product-title">
+      <Card.Title id="product-title">Featured Product</Card.Title>
+      <Card.Content as="div">
+        <p>
+          This card uses <code>aria-labelledby</code> to connect the title with
+          the card container, providing an accessible name for screen readers.
+        </p>
+        <p style={{ fontSize: '0.875rem', color: '#666', marginTop: '0.5rem' }}>
+          Screen readers will announce: "Featured Product, article"
+        </p>
+      </Card.Content>
+      <Card.Footer>
+        <button>Add to Cart</button>
+      </Card.Footer>
+    </Card>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'Demonstrates best practices for accessible cards using aria-labelledby to provide context to assistive technologies.',
+      },
+    },
+  },
+} as Story;
+
+/**
+ * Polymorphic Card - Shows different HTML elements
+ */
+export const PolymorphicElements: Story = {
+  render: () => (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '1rem' }}>
+      <Card as="article">
+        <Card.Title as="h2">Article Card</Card.Title>
+        <Card.Content>
+          Renders as <code>&lt;article&gt;</code> element for standalone content
+        </Card.Content>
+      </Card>
+
+      <Card as="section">
+        <Card.Title as="h2">Section Card</Card.Title>
+        <Card.Content>
+          Renders as <code>&lt;section&gt;</code> element for thematic grouping
+        </Card.Content>
+      </Card>
+
+      <Card as="aside">
+        <Card.Title as="h3">Aside Card</Card.Title>
+        <Card.Content>
+          Renders as <code>&lt;aside&gt;</code> element for tangential content
+        </Card.Content>
+      </Card>
+    </div>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'The Card component supports polymorphic rendering via the `as` prop, allowing you to use semantic HTML elements while maintaining consistent styling.',
+      },
+    },
+  },
+} as Story;
+
+/**
+ * Custom Heading Levels - Demonstrates heading hierarchy
+ */
+export const CustomHeadingLevels: Story = {
+  render: () => (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '1rem' }}>
+      <Card>
+        <Card.Title as="h1">Level 1 Heading</Card.Title>
+        <Card.Content>Main page title level</Card.Content>
+      </Card>
+
+      <Card>
+        <Card.Title as="h2">Level 2 Heading</Card.Title>
+        <Card.Content>Section title level</Card.Content>
+      </Card>
+
+      <Card>
+        <Card.Title as="h3">Level 3 Heading (Default)</Card.Title>
+        <Card.Content>Subsection title level - this is the default</Card.Content>
+      </Card>
+
+      <Card>
+        <Card.Title as="h4">Level 4 Heading</Card.Title>
+        <Card.Content>Component title level</Card.Content>
+      </Card>
+    </div>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'Card.Title supports all heading levels (h1-h6) to maintain proper document outline and heading hierarchy.',
+      },
+    },
+  },
+} as Story;

package/src/components/cards/card.test.tsx

@@ -1,30 +1,370 @@
+import React from 'react'
 import { render, screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
 import { Card } from './card'
 
 describe('Card', () => {
-  it('renders children', () => {
-    render(<Card>Hello World</Card>)
-    expect(screen.getByText('Hello World')).toBeInTheDocument()
+  describe('Basic Rendering', () => {
+    it('renders children', () => {
+      render(<Card>Hello World</Card>)
+      expect(screen.getByText('Hello World')).toBeInTheDocument()
+    })
+
+    it('renders with custom styles', () => {
+      const style = { backgroundColor: '#000' }
+      render(
+        <Card data-testid="card" styles={style}>
+          Hello World
+        </Card>,
+      )
+      const card = screen.getByTestId('card')
+      expect(card).toHaveStyle(style)
+    })
+
+    it('renders with custom element using as prop', () => {
+      render(
+        <Card data-testid="card" as="section">
+          Hello World
+        </Card>,
+      )
+      const card = screen.getByTestId('card')
+      expect(card.tagName.toLowerCase()).toBe('section')
+    })
+
+    it('renders with default div element', () => {
+      render(<Card data-testid="card">Content</Card>)
+      const card = screen.getByTestId('card')
+      expect(card.tagName.toLowerCase()).toBe('div')
+    })
+
+    it('applies custom classes', () => {
+      render(
+        <Card data-testid="card" classes="custom-class">
+          Content
+        </Card>,
+      )
+      const card = screen.getByTestId('card')
+      expect(card).toHaveClass('custom-class')
+    })
+
+    it('applies default shadow class', () => {
+      render(<Card data-testid="card">Content</Card>)
+      const card = screen.getByTestId('card')
+      expect(card).toHaveClass('shadow')
+    })
   })
 
-  it('renders with custom styles', () => {
-    const style = { backgroundColor: '#000;' }
-    render(
-      <Card data-testid="card" styles={style}>
-        Hello World
-      </Card>,
-    )
-    const card = screen.getByTestId('card')
-    expect(card).toHaveStyle(style)
+  describe('Compound Components', () => {
+    it('renders Card.Title component', () => {
+      render(
+        <Card>
+          <Card.Title>Test Title</Card.Title>
+        </Card>,
+      )
+      expect(screen.getByText('Test Title')).toBeInTheDocument()
+    })
+
+    it('renders Card.Title as h3 by default', () => {
+      render(
+        <Card>
+          <Card.Title data-testid="title">Test Title</Card.Title>
+        </Card>,
+      )
+      const title = screen.getByTestId('title')
+      expect(title.tagName.toLowerCase()).toBe('h3')
+    })
+
+    it('renders Card.Title with custom heading level', () => {
+      render(
+        <Card>
+          <Card.Title data-testid="title" as="h2">
+            Test Title
+          </Card.Title>
+        </Card>,
+      )
+      const title = screen.getByTestId('title')
+      expect(title.tagName.toLowerCase()).toBe('h2')
+    })
+
+    it('renders Card.Content component', () => {
+      render(
+        <Card>
+          <Card.Content>Test Content</Card.Content>
+        </Card>,
+      )
+      expect(screen.getByText('Test Content')).toBeInTheDocument()
+    })
+
+    it('renders Card.Content as article by default', () => {
+      render(
+        <Card>
+          <Card.Content data-testid="content">Test Content</Card.Content>
+        </Card>,
+      )
+      const content = screen.getByTestId('content')
+      expect(content.tagName.toLowerCase()).toBe('article')
+    })
+
+    it('renders Card.Content with custom element', () => {
+      render(
+        <Card>
+          <Card.Content data-testid="content" as="div">
+            Test Content
+          </Card.Content>
+        </Card>,
+      )
+      const content = screen.getByTestId('content')
+      expect(content.tagName.toLowerCase()).toBe('div')
+    })
+
+    it('renders Card.Footer component', () => {
+      render(
+        <Card>
+          <Card.Footer>Test Footer</Card.Footer>
+        </Card>,
+      )
+      expect(screen.getByText('Test Footer')).toBeInTheDocument()
+    })
+
+    it('renders Card.Footer with custom element', () => {
+      render(
+        <Card>
+          <Card.Footer data-testid="footer" as="footer">
+            Test Footer
+          </Card.Footer>
+        </Card>,
+      )
+      const footer = screen.getByTestId('footer')
+      expect(footer.tagName.toLowerCase()).toBe('footer')
+    })
+
+    it('renders complete card structure', () => {
+      render(
+        <Card>
+          <Card.Title>Title</Card.Title>
+          <Card.Content>Content</Card.Content>
+          <Card.Footer>Footer</Card.Footer>
+        </Card>,
+      )
+      expect(screen.getByText('Title')).toBeInTheDocument()
+      expect(screen.getByText('Content')).toBeInTheDocument()
+      expect(screen.getByText('Footer')).toBeInTheDocument()
+    })
+
+    it('applies custom className to sub-components', () => {
+      render(
+        <Card>
+          <Card.Title data-testid="title" className="custom-title">
+            Title
+          </Card.Title>
+          <Card.Content data-testid="content" className="custom-content">
+            Content
+          </Card.Content>
+          <Card.Footer data-testid="footer" className="custom-footer">
+            Footer
+          </Card.Footer>
+        </Card>,
+      )
+      expect(screen.getByTestId('title')).toHaveClass('card-title', 'custom-title')
+      expect(screen.getByTestId('content')).toHaveClass('card-content', 'custom-content')
+      expect(screen.getByTestId('footer')).toHaveClass('card-footer', 'custom-footer')
+    })
   })
 
-  it('renders with custom element', () => {
-    render(
-      <Card data-testid="card" elm="section">
-        Hello World
-      </Card>,
-    )
-    const card = screen.getByTestId('card')
-    expect(card.tagName.toLowerCase()).toBe('section')
+  describe('Accessibility', () => {
+    it('accepts aria-label prop', () => {
+      render(
+        <Card data-testid="card" aria-label="Product card">
+          Content
+        </Card>,
+      )
+      const card = screen.getByTestId('card')
+      expect(card).toHaveAttribute('aria-label', 'Product card')
+    })
+
+    it('accepts aria-labelledby prop', () => {
+      render(
+        <Card data-testid="card" aria-labelledby="card-title">
+          <Card.Title id="card-title">Title</Card.Title>
+        </Card>,
+      )
+      const card = screen.getByTestId('card')
+      expect(card).toHaveAttribute('aria-labelledby', 'card-title')
+    })
+
+    it('accepts aria-describedby prop', () => {
+      render(
+        <Card data-testid="card" aria-describedby="card-desc">
+          Content
+        </Card>,
+      )
+      const card = screen.getByTestId('card')
+      expect(card).toHaveAttribute('aria-describedby', 'card-desc')
+    })
+
+    it('accepts custom role', () => {
+      render(
+        <Card data-testid="card" role="article">
+          Content
+        </Card>,
+      )
+      const card = screen.getByTestId('card')
+      expect(card).toHaveAttribute('role', 'article')
+    })
+  })
+
+  describe('Interactive Card', () => {
+    it('applies interactive attributes when interactive is true', () => {
+      const handleClick = vi.fn()
+      render(
+        <Card data-testid="card" interactive onClick={handleClick}>
+          Content
+        </Card>,
+      )
+      const card = screen.getByTestId('card')
+      expect(card).toHaveAttribute('role', 'button')
+      expect(card).toHaveAttribute('tabIndex', '0')
+      expect(card).toHaveAttribute('data-card', 'interactive')
+    })
+
+    it('calls onClick when clicked', async () => {
+      const handleClick = vi.fn()
+      const user = userEvent.setup()
+      render(
+        <Card data-testid="card" interactive onClick={handleClick}>
+          Content
+        </Card>,
+      )
+      const card = screen.getByTestId('card')
+      await user.click(card)
+      expect(handleClick).toHaveBeenCalledTimes(1)
+    })
+
+    it('calls onClick when Enter key is pressed', async () => {
+      const handleClick = vi.fn()
+      const user = userEvent.setup()
+      render(
+        <Card data-testid="card" interactive onClick={handleClick}>
+          Content
+        </Card>,
+      )
+      const card = screen.getByTestId('card')
+      card.focus()
+      await user.keyboard('{Enter}')
+      expect(handleClick).toHaveBeenCalledTimes(1)
+    })
+
+    it('calls onClick when Space key is pressed', async () => {
+      const handleClick = vi.fn()
+      const user = userEvent.setup()
+      render(
+        <Card data-testid="card" interactive onClick={handleClick}>
+          Content
+        </Card>,
+      )
+      const card = screen.getByTestId('card')
+      card.focus()
+      await user.keyboard(' ')
+      expect(handleClick).toHaveBeenCalledTimes(1)
+    })
+
+    it('does not call onClick for other keys', async () => {
+      const handleClick = vi.fn()
+      const user = userEvent.setup()
+      render(
+        <Card data-testid="card" interactive onClick={handleClick}>
+          Content
+        </Card>,
+      )
+      const card = screen.getByTestId('card')
+      card.focus()
+      await user.keyboard('a')
+      expect(handleClick).not.toHaveBeenCalled()
+    })
+
+    it('allows custom tabIndex', () => {
+      render(
+        <Card data-testid="card" interactive tabIndex={-1}>
+          Content
+        </Card>,
+      )
+      const card = screen.getByTestId('card')
+      expect(card).toHaveAttribute('tabIndex', '-1')
+    })
+
+    it('allows custom role override for interactive cards', () => {
+      render(
+        <Card data-testid="card" interactive role="link">
+          Content
+        </Card>,
+      )
+      const card = screen.getByTestId('card')
+      expect(card).toHaveAttribute('role', 'link')
+    })
+
+    it('is keyboard focusable when interactive', () => {
+      render(
+        <Card data-testid="card" interactive>
+          Content
+        </Card>,
+      )
+      const card = screen.getByTestId('card')
+      expect(card).toHaveAttribute('tabIndex', '0')
+    })
+  })
+
+  describe('Non-Interactive with onClick', () => {
+    it('allows onClick without interactive prop', async () => {
+      const handleClick = vi.fn()
+      const user = userEvent.setup()
+      render(
+        <Card data-testid="card" onClick={handleClick}>
+          Content
+        </Card>,
+      )
+      const card = screen.getByTestId('card')
+      await user.click(card)
+      expect(handleClick).toHaveBeenCalledTimes(1)
+    })
+
+    it('does not add role="button" without interactive', () => {
+      const handleClick = vi.fn()
+      render(
+        <Card data-testid="card" onClick={handleClick}>
+          Content
+        </Card>,
+      )
+      const card = screen.getByTestId('card')
+      expect(card).not.toHaveAttribute('role')
+    })
+
+    it('does not add tabIndex without interactive', () => {
+      const handleClick = vi.fn()
+      render(
+        <Card data-testid="card" onClick={handleClick}>
+          Content
+        </Card>,
+      )
+      const card = screen.getByTestId('card')
+      expect(card).not.toHaveAttribute('tabIndex')
+    })
+  })
+
+  describe('Display Names', () => {
+    it('has correct display name for Card', () => {
+      expect(Card.displayName).toBe('Card')
+    })
+
+    it('has correct display name for Card.Title', () => {
+      expect(Card.Title.displayName).toBe('Card.Title')
+    })
+
+    it('has correct display name for Card.Content', () => {
+      expect(Card.Content.displayName).toBe('Card.Content')
+    })
+
+    it('has correct display name for Card.Footer', () => {
+      expect(Card.Footer.displayName).toBe('Card.Footer')
+    })
   })
 })