import { Meta } from "@storybook/addon-docs/blocks";

<Meta title="FP.REACT Components/List/Readme" />

# List Component

A flexible, accessible list component supporting unordered (ul), ordered (ol), and definition (dl) lists with WCAG 2.1 AA compliance, customizable styling via CSS custom properties, and full TypeScript support.

## Summary

The `List` component provides a type-safe, semantic way to create all types of HTML lists with built-in accessibility support, ref forwarding for programmatic control, and extensive styling options through CSS variables. Built on the polymorphic UI component, it maintains native HTML semantics while offering modern React patterns like forwardRef and compound components.

**Latest Version:** v1.0.0+

## Features

- 🎯 **Multiple List Types** - Supports ul, ol, and dl with appropriate child elements (li, dt, dd)
- ♿ **WCAG 2.1 AA Compliant** - Semantic HTML with proper screen reader support
- 🎨 **Flexible Variants** - Built-in support for inline, compact, spaced, and custom styled lists
- ⚡ **Performance Optimized** - React.forwardRef for efficient ref handling
- 🔧 **Type-Safe** - Comprehensive TypeScript definitions with extensive JSDoc
- 📦 **Compound Component** - List.ListItem pattern for clean, intuitive API
- 🎨 **CSS Custom Properties** - Extensive theming via CSS variables (rem units only)
- 🧪 **100% Tested** - Complete test coverage with axe-core accessibility validation

## Accessibility

- ✅ Semantic HTML list elements (ul, ol, dl) with native screen reader support
- ✅ Screen readers announce list type and item count automatically
- ✅ role="list" override support for Safari/VoiceOver when list styling is removed
- ✅ Supports aria-label and aria-labelledby for additional context
- ✅ Keyboard navigation works naturally with focusable children
- ✅ Ref forwarding enables programmatic focus management
- ✅ Nested list support maintains semantic structure
- ✅ Focus indicators for interactive list items

**Accessibility Rating:** ✅ A (Excellent) - WCAG 2.1 Level AA

## Props

### List Props

```ts
type ListProps = {
  /** Type of list element to render (default: 'ul') */
  type?: 'ul' | 'ol' | 'dl';

  /** Variant for custom styling via CSS (applied as data-variant attribute) */
  variant?: string;

  /** ARIA role override (use role="list" when removing list styling) */
  role?: string;

  /** Inline CSS styles (can include CSS custom properties) */
  styles?: React.CSSProperties;

  /** CSS class names */
  classes?: string;

  /** HTML id attribute */
  id?: string;

  /** Accessible label for screen readers */
  'aria-label'?: string;
  'aria-labelledby'?: string;

  /** Child elements (typically ListItem components) */
  children: React.ReactNode;
} & Partial<React.ComponentProps<typeof UI>>;
```

### ListItem Props

```ts
type ListItemProps = {
  /** Type of list item element to render (default: 'li') */
  type?: 'li' | 'dt' | 'dd';

  /** HTML id attribute */
  id?: string;

  /** Inline CSS styles */
  styles?: React.CSSProperties;

  /** CSS class names */
  classes?: string;

  /** Child elements */
  children: React.ReactNode;
} & Partial<React.ComponentProps<typeof UI>>;
```

### Default Values

| Prop | Default | Description |
|------|---------|-------------|
| `type` | `'ul'` | Unordered list by default |
| `variant` | `undefined` | No variant styling applied |
| `role` | `undefined` | Uses native semantic role |
| `ListItem.type` | `'li'` | Standard list item |

## Usage Examples

### Basic Unordered List

Simple bullet point list:

```tsx
import { List } from '@fpkit/acss';

function FeatureList() {
  return (
    <List>
      <List.ListItem>Fast performance</List.ListItem>
      <List.ListItem>Easy to use</List.ListItem>
      <List.ListItem>Fully typed</List.ListItem>
    </List>
  );
}
```

### Ordered List

Sequential steps or numbered items:

```tsx
import { List } from '@fpkit/acss';

function Instructions() {
  return (
    <List type="ol" aria-label="Installation steps">
      <List.ListItem>Download the package</List.ListItem>
      <List.ListItem>Extract files to your project</List.ListItem>
      <List.ListItem>Run npm install</List.ListItem>
      <List.ListItem>Start the development server</List.ListItem>
    </List>
  );
}
```

### Definition List

Term and definition pairs (glossary, metadata):

```tsx
import { List } from '@fpkit/acss';

function Glossary() {
  return (
    <List type="dl">
      <List.ListItem type="dt">React</List.ListItem>
      <List.ListItem type="dd">
        A JavaScript library for building user interfaces
      </List.ListItem>

      <List.ListItem type="dt">TypeScript</List.ListItem>
      <List.ListItem type="dd">
        JavaScript with syntax for types
      </List.ListItem>

      <List.ListItem type="dt">SCSS</List.ListItem>
      <List.ListItem type="dd">
        Syntactically Awesome Style Sheets
      </List.ListItem>
    </List>
  );
}
```

### Inline List (Horizontal Navigation)

Perfect for navigation menus:

```tsx
import { List } from '@fpkit/acss';

function Navigation() {
  return (
    <nav>
      <List variant="inline" role="list" aria-label="Main navigation">
        <List.ListItem>
          <a href="/">Home</a>
        </List.ListItem>
        <List.ListItem>
          <a href="/about">About</a>
        </List.ListItem>
        <List.ListItem>
          <a href="/products">Products</a>
        </List.ListItem>
        <List.ListItem>
          <a href="/contact">Contact</a>
        </List.ListItem>
      </List>
    </nav>
  );
}
```

### Unstyled List with Role Restoration

When removing list styling, restore semantics with `role="list"`:

```tsx
import { List } from '@fpkit/acss';

function CleanList() {
  return (
    <List variant="none" role="list" aria-label="Feature highlights">
      <List.ListItem>✓ No bullets</List.ListItem>
      <List.ListItem>✓ Clean design</List.ListItem>
      <List.ListItem>✓ Still accessible</List.ListItem>
    </List>
  );
}
```

**Why `role="list"`?** Safari and VoiceOver remove list semantics when `list-style: none` is applied. Adding `role="list"` explicitly restores the semantic meaning for screen readers.

### Custom Styled List with CSS Variables

Override default styling with CSS custom properties:

```tsx
import { List } from '@fpkit/acss';

function BrandedList() {
  return (
    <List
      variant="custom"
      styles={{
        '--list-marker-color': '#0066cc',
        '--list-marker-content': '"→"',
        '--list-gap': '1rem',
        '--list-item-margin-bottom': '0.75rem',
      }}
    >
      <List.ListItem>Custom arrow marker</List.ListItem>
      <List.ListItem>Brand color applied</List.ListItem>
      <List.ListItem>Increased spacing</List.ListItem>
    </List>
  );
}
```

### Compact Variant

Reduced spacing for tighter layouts:

```tsx
import { List } from '@fpkit/acss';

function CompactList() {
  return (
    <List variant="compact">
      <List.ListItem>Tight spacing</List.ListItem>
      <List.ListItem>Minimal margins</List.ListItem>
      <List.ListItem>Condensed layout</List.ListItem>
    </List>
  );
}
```

### Spaced Variant

Increased spacing for better readability:

```tsx
import { List } from '@fpkit/acss';

function SpacedList() {
  return (
    <List variant="spaced">
      <List.ListItem>Generous spacing</List.ListItem>
      <List.ListItem>Better readability</List.ListItem>
      <List.ListItem>Comfortable layout</List.ListItem>
    </List>
  );
}
```

### Nested Lists

Create hierarchical list structures:

```tsx
import { List } from '@fpkit/acss';

function NestedList() {
  return (
    <List>
      <List.ListItem>
        Frontend Technologies
        <List>
          <List.ListItem>React</List.ListItem>
          <List.ListItem>Vue</List.ListItem>
          <List.ListItem>Svelte</List.ListItem>
        </List>
      </List.ListItem>

      <List.ListItem>
        Backend Technologies
        <List>
          <List.ListItem>Node.js</List.ListItem>
          <List.ListItem>Python</List.ListItem>
          <List.ListItem>Go</List.ListItem>
        </List>
      </List.ListItem>
    </List>
  );
}
```

### Mixed Nested List Types

Combine different list types for complex structures:

```tsx
import { List } from '@fpkit/acss';

function MixedNestedList() {
  return (
    <List type="ul">
      <List.ListItem>
        Installation Methods
        <List type="ol">
          <List.ListItem>Clone the repository</List.ListItem>
          <List.ListItem>Install dependencies</List.ListItem>
          <List.ListItem>Run the build script</List.ListItem>
        </List>
      </List.ListItem>
    </List>
  );
}
```

### With Ref Forwarding

Access the list element programmatically:

```tsx
import { List } from '@fpkit/acss';
import { useRef, useEffect } from 'react';

function ScrollableList() {
  const listRef = useRef<HTMLUListElement>(null);

  const scrollToTop = () => {
    listRef.current?.scrollIntoView({ behavior: 'smooth' });
  };

  useEffect(() => {
    // Programmatically focus the list on mount
    listRef.current?.focus();
  }, []);

  return (
    <>
      <List ref={listRef} tabIndex={-1}>
        <List.ListItem>Item 1</List.ListItem>
        <List.ListItem>Item 2</List.ListItem>
        {/* ... many items ... */}
      </List>
      <button onClick={scrollToTop}>Scroll to top</button>
    </>
  );
}
```

### With Complex Children

Rich content inside list items:

```tsx
import { List } from '@fpkit/acss';

function ProductList() {
  return (
    <List>
      <List.ListItem>
        <h3>Premium Package</h3>
        <p>Includes all features plus priority support</p>
        <button>Learn More</button>
      </List.ListItem>

      <List.ListItem>
        <h3>Standard Package</h3>
        <p>Core features for most users</p>
        <button>Learn More</button>
      </List.ListItem>
    </List>
  );
}
```

### Accessible Feature List

Icon-based list with proper accessibility:

```tsx
import { List } from '@fpkit/acss';
import { CheckIcon } from '../icons';

function FeatureList() {
  return (
    <List variant="none" role="list" aria-label="Product features">
      <List.ListItem>
        <CheckIcon aria-hidden="true" />
        <span>Unlimited projects</span>
      </List.ListItem>

      <List.ListItem>
        <CheckIcon aria-hidden="true" />
        <span>24/7 support</span>
      </List.ListItem>

      <List.ListItem>
        <CheckIcon aria-hidden="true" />
        <span>Advanced analytics</span>
      </List.ListItem>
    </List>
  );
}
```

## Styling

The component uses SCSS with CSS custom properties for theming. All spacing uses **rem units** (16px = 1rem) for accessibility.

### CSS Custom Properties

```css
ul, ol, dl {
  /* Spacing */
  --list-margin-top: 0;
  --list-margin-bottom: 1rem;
  --list-margin-inline: 0;
  --list-padding-inline: 2.5rem;
  --list-gap: 0.5rem;

  /* List marker/bullet styling */
  --list-marker-color: currentColor;
  --list-marker-size: 1em;
  --list-marker-offset: 0.5rem;

  /* Typography */
  --list-font-size: 1rem;
  --list-line-height: 1.5;
  --list-font-family: inherit;
  --list-color: inherit;

  /* List item spacing */
  --list-item-margin-bottom: 0.5rem;
  --list-item-padding-inline: 0;
  --list-item-padding-block: 0;

  /* Definition list specific */
  --dt-font-weight: 600;
  --dt-margin-bottom: 0.25rem;
  --dd-margin-inline-start: 2rem;
  --dd-margin-bottom: 1rem;
}
```

### Built-in Variants

#### `variant="none"`
Removes list styling (bullets, numbers, padding):

```tsx
<List variant="none" role="list">
  <List.ListItem>Clean item</List.ListItem>
</List>
```

#### `variant="inline"`
Horizontal list layout (flexbox):

```tsx
<List variant="inline">
  <List.ListItem>Nav 1</List.ListItem>
  <List.ListItem>Nav 2</List.ListItem>
</List>
```

#### `variant="custom"`
Custom marker support via CSS variables:

```tsx
<List
  variant="custom"
  styles={{
    '--list-marker-content': '"✓"',
    '--list-marker-color': 'green',
  }}
>
  <List.ListItem>Custom marker</List.ListItem>
</List>
```

#### `variant="compact"`
Reduced spacing:

```css
--list-gap: 0.25rem;
--list-item-margin-bottom: 0.25rem;
--list-margin-bottom: 0.5rem;
```

#### `variant="spaced"`
Increased spacing:

```css
--list-gap: 1rem;
--list-item-margin-bottom: 1rem;
```

### Theming Example

Create a custom theme by overriding CSS variables:

```css
/* Dark theme */
.dark-theme ul,
.dark-theme ol,
.dark-theme dl {
  --list-color: #f0f0f0;
  --list-marker-color: #66b3ff;
}

/* Brand theme */
.brand-list {
  --list-marker-color: #d63384;
  --list-marker-size: 1.25em;
  --list-gap: 1rem;
}
```

## Best Practices

### Accessibility

1. **Use Semantic HTML Types**

   ```tsx
   // ✅ GOOD: Semantic list type matches content
   <List type="ol">
     <List.ListItem>Step one</List.ListItem>
   </List>

   // ❌ BAD: Misusing list type
   <List type="ul">
     <List.ListItem>1. Step one</List.ListItem> {/* Don't manually number */}
   </List>
   ```

2. **Restore List Semantics When Styling is Removed**

   ```tsx
   // ✅ GOOD: Role restores semantics for screen readers
   <List variant="none" role="list">
     <List.ListItem>Item</List.ListItem>
   </List>

   // ❌ BAD: Missing role breaks screen reader announcements
   <List variant="none">
     <List.ListItem>Item</List.ListItem>
   </List>
   ```

3. **Provide Context with ARIA Labels**

   ```tsx
   // ✅ GOOD: Clear purpose for screen readers
   <List aria-label="Product features">
     <List.ListItem>Feature 1</List.ListItem>
   </List>

   // ⚠️ OKAY: Context from surrounding content
   <section>
     <h2>Features</h2>
     <List>
       <List.ListItem>Feature 1</List.ListItem>
     </List>
   </section>
   ```

4. **Use Definition Lists Correctly**

   ```tsx
   // ✅ GOOD: Proper term-definition pairs
   <List type="dl">
     <List.ListItem type="dt">Term</List.ListItem>
     <List.ListItem type="dd">Definition</List.ListItem>
   </List>

   // ❌ BAD: Wrong element types
   <List type="dl">
     <List.ListItem type="li">Wrong</List.ListItem>
   </List>
   ```

### Performance

1. **Use Ref Forwarding for DOM Access**

   ```tsx
   // ✅ GOOD: Direct DOM access when needed
   const listRef = useRef<HTMLUListElement>(null);
   <List ref={listRef}>...</List>
   ```

2. **Memoize Complex Children**

   ```tsx
   import { useMemo } from 'react';

   // ✅ GOOD: Prevent unnecessary re-renders
   const listItems = useMemo(() =>
     data.map(item => (
       <List.ListItem key={item.id}>{item.name}</List.ListItem>
     )),
     [data]
   );

   return <List>{listItems}</List>;
   ```

### Styling

1. **Use rem Units for Accessibility**

   ```tsx
   // ✅ GOOD: rem scales with user font size preferences
   <List styles={{ '--list-gap': '1rem' }}>...</List>

   // ❌ BAD: px ignores user preferences
   <List styles={{ '--list-gap': '16px' }}>...</List>
   ```

2. **Match Variant to Use Case**

   ```tsx
   // ✅ GOOD: Inline variant for navigation
   <nav>
     <List variant="inline" role="list">...</List>
   </nav>

   // ✅ GOOD: Compact variant for sidebar
   <aside>
     <List variant="compact">...</List>
   </aside>
   ```

3. **Test Color Contrast**

   ```tsx
   // ✅ GOOD: Ensure marker color meets WCAG AA (4.5:1)
   <List styles={{ '--list-marker-color': '#0066cc' }}>...</List>
   ```

## Technical Details

### Component Architecture

- **Functional Components** with `React.forwardRef` for both List and ListItem
- **Type-Safe** with extracted TypeScript definitions in `list.types.ts`
- **Accessible** by leveraging semantic HTML list elements
- **Composable** via UI component for polymorphic flexibility
- **Compound Component Pattern** - `List.ListItem` for intuitive API

### Browser Support

Works in all modern browsers supporting:
- React 18+
- CSS Custom Properties (IE 11+ with fallbacks)
- Flexbox (for inline variant)
- CSS Logical Properties (margin-block, padding-inline)

### Ref Types

```ts
// List refs
const ulRef = useRef<HTMLUListElement>(null);
const olRef = useRef<HTMLOListElement>(null);
const dlRef = useRef<HTMLDListElement>(null);

// ListItem ref
const itemRef = useRef<HTMLLIElement | HTMLElement>(null);
```

## Testing

### Automated Testing

The component includes comprehensive tests:

```bash
npm test -- list.test.tsx
```

Tests cover:
- ✅ Basic rendering (ul, ol, dl)
- ✅ ListItem rendering (li, dt, dd)
- ✅ Props and attributes
- ✅ Variants and styling
- ✅ Nested lists
- ✅ Ref forwarding
- ✅ Compound component pattern
- ✅ Accessibility with axe-core
- ✅ Edge cases and real-world use cases

### Manual Testing Checklist

#### Screen Reader Testing (NVDA/VoiceOver/JAWS)
- [ ] Announces as "list" with item count
- [ ] Items announced as "bullet" (ul) or number (ol)
- [ ] Definition lists announce "term" and "definition"
- [ ] role="list" restores semantics when styling is removed

#### Keyboard Navigation
- [ ] Tab navigates through focusable children
- [ ] Nested lists maintain logical tab order
- [ ] No keyboard traps

#### Visual Testing
- [ ] Markers display correctly in all list types
- [ ] Variants apply expected styling
- [ ] Nested lists indent properly
- [ ] Works at 200% browser zoom
- [ ] Text reflows at 320px viewport width

## Related Components

- **Navigation** - For complex navigation menus
- **Breadcrumbs** - For navigation trails using ordered lists
- **Menu** - For interactive dropdown menus

## Resources

- [MDN: ul Element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/ul)
- [MDN: ol Element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/ol)
- [MDN: dl Element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dl)
- [WCAG 2.1 Guidelines](https://www.w3.org/WAI/WCAG21/quickref/)
- [Scott O'Hara: Lists and Safari](https://www.scottohara.me/blog/2019/01/12/lists-and-safari.html)

## Changelog

### v1.0.0 (Latest)
- ✨ Initial release with comprehensive features
- ✨ React.forwardRef for proper ref handling
- ✨ Separate TypeScript types in `list.types.ts`
- ✨ WCAG 2.1 AA compliant with semantic HTML
- ✨ SCSS styling with CSS custom properties (rem units only)
- ✨ Built-in variants: none, inline, custom, compact, spaced
- ✨ Compound component pattern (List.ListItem)
- ✨ Comprehensive test suite with axe-core validation
- ✨ 100% test coverage across all list types
- 📝 Extensive JSDoc documentation
- 📝 Complete README with 15+ usage examples
- ♿ Accessibility rating: A (Excellent)

---

**Need Help?** Check the [Storybook examples](./?path=/docs/fp-react-components-list--docs) or review the [component tests](./list.test.tsx) for usage patterns.