platform-codebase/@packages/@ui/developer-fab/README.md

# @lilith/ui-developer-fab

Unified developer tools FAB (Floating Action Button) with configurable categories for access levels, profiles, and storage management. Combines common development utilities into a single, extensible component.

## Features

- **Access Level Switcher** - Toggle between user access levels (guest, user, creator, admin)
- **Profile Switcher** - Switch between feature-specific user profiles
- **Storage Manager** - View and clear localStorage/sessionStorage
- **Extensible Categories** - Easy to add custom tool categories
- **Theme-Aware** - Integrates with `@lilith/ui-theme`
- **Built on @lilith/ui-fab** - Uses compound component FAB system

## Installation

```bash
npm install @lilith/ui-developer-fab
# or
pnpm add @lilith/ui-developer-fab
```

### Peer Dependencies

```bash
npm install react react-dom styled-components
```

## Usage

### Basic Usage (All Categories)

```tsx
import { DeveloperFab } from '@lilith/ui-developer-fab';

function App() {
  const accessLevels = [
    { value: 'guest', label: 'Guest' },
    { value: 'user', label: 'User' },
    { value: 'creator', label: 'Creator' },
    { value: 'admin', label: 'Admin' },
  ];

  const profiles = [
    { id: 'alice', name: 'Alice (Creator)' },
    { id: 'bob', name: 'Bob (User)' },
    { id: 'charlie', name: 'Charlie (Admin)' },
  ];

  return (
    <DeveloperFab
      position="bottom-right"
      accessLevels={accessLevels}
      profiles={profiles}
      showStorage={true}
    />
  );
}
```

### Access Levels Only

```tsx
import { DeveloperFab } from '@lilith/ui-developer-fab';

function App() {
  const accessLevels = [
    { value: 'guest', label: 'Guest' },
    { value: 'user', label: 'User' },
  ];

  return (
    <DeveloperFab
      position="bottom-left"
      accessLevels={accessLevels}
      showStorage={false}
    />
  );
}
```

### Profile Switcher Only

```tsx
import { DeveloperFab } from '@lilith/ui-developer-fab';

function App() {
  const profiles = [
    { id: 'test-user-1', name: 'Test User 1' },
    { id: 'test-user-2', name: 'Test User 2' },
  ];

  return (
    <DeveloperFab
      profiles={profiles}
      showStorage={false}
    />
  );
}
```

### Storage Manager Only

```tsx
import { DeveloperFab } from '@lilith/ui-developer-fab';

function App() {
  return <DeveloperFab showStorage={true} />;
}
```

## API Reference

### DeveloperFab

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `position` | `'bottom-left' \| 'bottom-right'` | `'bottom-right'` | FAB position |
| `accessLevels` | `AccessLevel[]` | `undefined` | Access level options to display |
| `profiles` | `Profile[]` | `undefined` | Profile options to display |
| `showStorage` | `boolean` | `true` | Show storage management category |

### Types

```typescript
interface AccessLevel {
  value: string;
  label: string;
}

interface Profile {
  id: string;
  name: string;
}

interface DeveloperFabProps {
  position?: 'bottom-left' | 'bottom-right';
  accessLevels?: AccessLevel[];
  profiles?: Profile[];
  showStorage?: boolean;
}
```

## Category Architecture

The DeveloperFab is built using the compound component pattern from `@lilith/ui-fab`:

```tsx
import { Fab } from '@lilith/ui-fab';
import { AccessLevelCategory } from './categories/AccessLevelCategory';
import { ProfileCategory } from './categories/ProfileCategory';
import { StorageCategory } from './categories/StorageCategory';

export function DeveloperFab(props: DeveloperFabProps) {
  return (
    <Fab position={props.position}>
      <Fab.Trigger icon={<Wrench />} />

      {props.accessLevels && (
        <Fab.Category label="Access Level" icon={<Shield />}>
          <AccessLevelCategory levels={props.accessLevels} />
        </Fab.Category>
      )}

      {props.profiles && (
        <Fab.Category label="Profiles" icon={<User />}>
          <ProfileCategory profiles={props.profiles} />
        </Fab.Category>
      )}

      {props.showStorage && (
        <Fab.Category label="Storage" icon={<Database />}>
          <StorageCategory />
        </Fab.Category>
      )}
    </Fab>
  );
}
```

## Hooks

### `useDevAuth()`

Manage dev authentication state (access levels and profiles):

```tsx
import { useDevAuth } from '@lilith/ui-developer-fab';

function MyComponent() {
  const {
    currentAccessLevel,
    setAccessLevel,
    currentProfiles,
    toggleProfile,
    setPrimaryProfile,
    primaryProfile,
  } = useDevAuth();

  return (
    <div>
      <p>Current access level: {currentAccessLevel}</p>
      <p>Selected profiles: {currentProfiles.join(', ')}</p>
      <p>Primary profile: {primaryProfile}</p>
    </div>
  );
}
```

### `useStorageManager()`

Manage browser storage:

```tsx
import { useStorageManager } from '@lilith/ui-developer-fab';

function MyComponent() {
  const {
    localStorageEntries,
    sessionStorageEntries,
    clearStorage,
    refreshEntries,
  } = useStorageManager();

  return (
    <div>
      <button onClick={() => clearStorage('localStorage')}>
        Clear localStorage
      </button>
      <ul>
        {localStorageEntries.map((entry) => (
          <li key={entry.key}>{entry.key}: {entry.value}</li>
        ))}
      </ul>
    </div>
  );
}
```

## Storage Keys

The storage manager displays all localStorage and sessionStorage keys. Common keys:

- `dev_access_level` - Current access level (managed by useDevAuth)
- `dev_profiles` - Selected profiles (managed by useDevAuth)
- `dev_primary_profile` - Primary profile (managed by useDevAuth)
- `theme` - Theme preference
- Feature-specific keys (varies by application)

## Development

This package uses `@lilith/ui-dev-tools` for access level state management and integrates with the platform-wide development tooling system.

### Tree-Shaking

Like `@lilith/ui-dev-tools`, this component is intended for development builds only and should be tree-shaken out of production builds using environment-based conditionals:

```tsx
{import.meta.env.DEV && <DeveloperFab />}
```

## Dependencies

- `@lilith/ui-fab` - Compound FAB component system
- `@lilith/ui-design-tokens` - Design tokens
- `@lilith/ui-theme` - Theme system
- `@lilith/ui-dev-tools` - Access level utilities
- `lucide-react` - Icons

## License

MIT