@qin_sunrise/tab/README.md

A lightweight tab management package based on zustand state management for React applications

# @qin_sunrise/tab

A lightweight tab management package based on zustand state management for React applications.

## Features

- ?? Lightweight and fast, based on zustand
- ?? Built-in persistence support
- ?? TypeScript support
- ?? Flexible configuration options
- ?? UI-agnostic - provides functionality only, no UI components
- ?? Easy to integrate

## Installation

```bash
npm install @qin_sunrise/tab
# or
yarn add @qin_sunrise/tab
# or
pnpm add @qin_sunrise/tab
```

## Quick Start

### Basic Usage

```tsx
import { useTabManager, useTabs, useActiveTabId } from '@qin_sunrise/tab';

function App() {
  const { addTab, removeTabById, switchRouteByTab } = useTabManager();
  const tabs = useTabs();
  const activeTabId = useActiveTabId();

  // Add new tab
  const handleAddTab = (route) => {
    addTab(route);
  };

  // Remove tab
  const handleRemoveTab = (tabId) => {
    removeTabById(tabId);
  };

  // Switch to tab
  const handleTabClick = (tab) => {
    switchRouteByTab(tab);
  };

  return (
    <div>
      {/* Your tab UI */}
    </div>
  );
}
```

### With Configuration

```tsx
import { createTabStore } from '@qin_sunrise/tab';

// Create store with configuration
const tabStore = createTabStore({
  cache: true, // Enable persistence
  storageKey: 'my-tabs', // Custom storage key
  homePath: '/dashboard' // Custom home path
});
```

## API Reference

### Type Definitions

#### `Tab`
```tsx
interface Tab {
  fixedIndex?: number | null; // Fixed index
  fullPath: string; // Full path
  i18nKey?: string | null; // Internationalization key
  icon?: string; // Icon
  id: string; // Tab ID
  keepAlive: boolean; // Whether to keep alive
  label: string; // Tab title
  localIcon?: string; // Local icon
  newLabel?: string; // New title
  oldLabel?: string | null; // Old title
  routeKey: string; // Route key
  routePath: string; // Route path
}
```

#### `TabConfig`
```tsx
interface TabConfig {
  cache?: boolean; // Whether to enable cache
  storageKey?: string; // Storage key name
  homePath?: string; // Home path
}
```

### Hooks

#### `useTabStore(config?)`
Get tab store instance.

#### `useTabs()`
Get all tabs.

#### `useActiveTabId()`
Get current active tab ID.

#### `useActiveFirstLevelMenuKey()`
Get active first level menu key.

#### `useRemoveCacheKey()`
Get remove cache key.

#### `useTabActions()`
Get all tab action functions.

#### `useTabManager(navigate?)`
Get tab manager with navigation support.

#### `useCacheTabs()`
Hook for automatically caching tabs before page unload.

#### `useTabScroll()`
Get tab scroll utilities.

### Store Actions

#### `addTab(tab: Tab)`
Add new tab to store.

#### `updateTab(index: number, tab: Tab)`
Update tab at specified index.

#### `setActiveTabId(tabId: string)`
Set active tab ID.

#### `setActiveFirstLevelMenuKey(key: string)`
Set active first level menu key.

#### `setTabs(tabs: Tab[])`
Set all tabs.

#### `changeTabLabel(index: number, label?: string)`
Change tab title.

#### `removeTabById(tabId: string)`
Remove tab by ID.

#### `clearAllTabs()`
Clear all tabs except fixed tabs.

#### `clearLeftTabs(tabId: string)`
Clear tabs to the left of specified tab.

#### `clearRightTabs(tabId: string)`
Clear tabs to the right of specified tab.

#### `clearOtherTabs(tabId: string)`
Clear all tabs except specified tab and fixed tabs.

#### `setRemoveCacheKey(keys: string[] | null)`
Set remove cache key.

### Utility Functions

#### `getTabByRoute(route: Route, homePath?: string)`
Convert route to tab object.

#### `isTabInTabs(tabId: string, tabs: Tab[])`
Check if tab exists in tab array.

#### `getFixedTabs(tabs: Tab[])`
Get all fixed tabs.

#### `getTabById(tabId: string, tabs: Tab[])`
Get tab by ID.

#### `isTabRetain(tabId: string, tabs: Tab[])`
Check if tab is retained (fixed) tab.

#### `getActiveFirstLevelMenuKey(route: Route)`
Get active first level menu key from route.

## Examples

### Basic Tab Management

```tsx
import { useTabManager, useTabs } from '@qin_sunrise/tab';

function TabBar() {
  const { addTab, removeTabById, switchRouteByTab } = useTabManager();
  const tabs = useTabs();

  return (
    <div className="tab-bar">
      {tabs.map((tab) => (
        <div key={tab.id} className="tab" onClick={() => switchRouteByTab(tab)}>
          <span>{tab.label}</span>
          <button onClick={() => removeTabById(tab.id)}>�</button>
        </div>
      ))}
    </div>
  );
}
```

### Route Integration

```tsx
import { useTabManager } from '@qin_sunrise/tab';
import { useRouter } from 'your-router';

function App() {
  const router = useRouter();
  const { addTab } = useTabManager(router.navigate);

  // Add tab when route changes
  useEffect(() => {
    addTab({
      fullPath: router.pathname,
      pathname: router.pathname,
      id: router.route,
      handle: {
        title: router.route,
        keepAlive: true
      }
    });
  }, [router.pathname]);

  return <YourApp />;
}
```

### With Persistence

```tsx
import { createTabStore } from '@qin_sunrise/tab';

const tabStore = createTabStore({
  cache: true,
  storageKey: 'my-app-tabs'
});

function App() {
  return (
    <TabProvider store={tabStore}>
      <YourApp />
    </TabProvider>
  );
}
```

## Documentation

- [English](./README.md) (Current)
- [??](./README.zh-CN.md)

## License

MIT