npm package: @shadowfax-tech/tab
Description: Accessible, flexible tabs component with useTabs hook for SFX UI
Latest version: 0.1.4

# @shadowfax-tech/tab

A fully accessible, flexible tabs component with a powerful `useTabs()` hook for managing tab state. Built with the SFX UI theme system.

## Features

- ♿ **Accessible**: Full ARIA support and keyboard navigation
- 🔧 **Flexible Hook**: `useTabs()` hook for complete tab state management
- 🎯 **TypeScript**: Fully typed with comprehensive interfaces
- 📦 **Dynamic**: Add, remove, and update tabs programmatically
- 🎨 **Theme Integration**: Uses SFX UI Theme design tokens
- 🎛️ **Variants**: Multiple sizes, full-width mode, badges, icons
- 🚀 **Performance**: Optimized with React best practices

## Installation

```bash
npm install @shadowfax-tech/tab
# or
yarn add @shadowfax-tech/tab
```

## Quick Start

```tsx
import { Tabs, useTabs } from '@shadowfax-tech/tab';
import '@shadowfax-tech/tab/styles';

function MyComponent() {
  const { tabs, activeTab, setActiveTab } = useTabs({
    initialTab: 'tab-1',
    tabs: [
      { id: 'tab-1', label: 'Tab 1' },
      { id: 'tab-2', label: 'Tab 2' },
      { id: 'tab-3', label: 'Tab 3' },
    ],
  });

  return (
    <div>
      <Tabs
        tabs={tabs}
        activeTab={activeTab}
        onTabChange={setActiveTab}
      />
      
      <div style={{ padding: '24px' }}>
        {activeTab === 'tab-1' && <div>Tab 1 Content</div>}
        {activeTab === 'tab-2' && <div>Tab 2 Content</div>}
        {activeTab === 'tab-3' && <div>Tab 3 Content</div>}
      </div>
    </div>
  );
}
```

## Tabs with Badges

```tsx
const { tabs, activeTab, setActiveTab } = useTabs({
  initialTab: 'pending',
  tabs: [
    { id: 'pending', label: 'Pending', badge: 12 },
    { id: 'approved', label: 'Approved', badge: 8 },
    { id: 'rejected', label: 'Rejected', badge: 3 },
  ],
});

<Tabs tabs={tabs} activeTab={activeTab} onTabChange={setActiveTab} />
```

## Tabs with Icons

```tsx
import { CalendarIcon, ChartIcon } from './icons';

const { tabs, activeTab, setActiveTab } = useTabs({
  initialTab: 'dashboard',
  tabs: [
    { id: 'dashboard', label: 'Dashboard', icon: <ChartIcon /> },
    { id: 'calendar', label: 'Calendar', icon: <CalendarIcon /> },
  ],
});

<Tabs tabs={tabs} activeTab={activeTab} onTabChange={setActiveTab} />
```

## Dynamic Tab Management

```tsx
const { 
  tabs, 
  activeTab, 
  setActiveTab, 
  addTab, 
  removeTab, 
  updateTab 
} = useTabs({
  initialTab: 'tab-1',
  tabs: [{ id: 'tab-1', label: 'Tab 1' }],
});

// Add a new tab
addTab({ id: 'tab-2', label: 'Tab 2' });

// Remove a tab
removeTab('tab-1');

// Update tab badge
updateTab('tab-2', { badge: 10 });
```

## API Reference

### useTabs Hook

```typescript
const { 
  tabs,           // Array of tab items
  activeTab,      // Currently active tab ID
  setActiveTab,   // Change active tab
  getActiveTab,   // Get active tab object
  addTab,         // Add a new tab
  removeTab,      // Remove a tab
  updateTab,      // Update a tab
  isTabActive     // Check if tab is active
} = useTabs({
  initialTab: 'tab-1',
  tabs: [...],
  onTabChange: (tabId) => { /* callback */ }
});
```

### Tabs Component Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `tabs` | `Tab[]` | **required** | Array of tab items |
| `activeTab` | `string` | **required** | Currently active tab ID |
| `onTabChange` | `(tabId: string) => void` | **required** | Callback when tab is clicked |
| `className` | `string` | - | Additional CSS class |
| `size` | `'small' \| 'medium' \| 'large'` | `'medium'` | Size variant |
| `fullWidth` | `boolean` | `false` | Full width mode |

### Tab Interface

```typescript
interface Tab {
  id: string;              // Unique identifier
  label: string;           // Display text
  badge?: number | string; // Optional badge
  disabled?: boolean;      // Disable the tab
  icon?: React.ReactNode;  // Optional icon
}
```

## Different Sizes

```tsx
<Tabs size="small" {...props} />   {/* Small tabs */}
<Tabs size="medium" {...props} />  {/* Default size */}
<Tabs size="large" {...props} />   {/* Large tabs */}
```

## Full Width Tabs

```tsx
<Tabs fullWidth tabs={tabs} activeTab={activeTab} onTabChange={setActiveTab} />
```

## Disabled Tabs

```tsx
const { tabs, activeTab, setActiveTab } = useTabs({
  initialTab: 'active',
  tabs: [
    { id: 'active', label: 'Active' },
    { id: 'disabled', label: 'Disabled', disabled: true },
    { id: 'enabled', label: 'Enabled' },
  ],
});
```

## Accessibility

The tab component follows WAI-ARIA best practices:

- ✅ Proper `role="tablist"` and `role="tab"` attributes
- ✅ `aria-selected` to indicate active tab
- ✅ `aria-disabled` for disabled tabs
- ✅ Keyboard navigation support (Enter/Space)
- ✅ Focus management with `tabIndex`
- ✅ Semantic HTML with proper button elements

## License

MIT

## Links

- [GitHub](https://github.com/shadowfax-tech/sfx-cargo-ui)
- [Full Documentation](https://github.com/shadowfax-tech/sfx-cargo-ui/tree/main/src/lib/components/tab)
- [npm](https://www.npmjs.com/package/@shadowfax-tech/tab)