dees-wcctools/ts_web/readme.md

# @design.estate/dees-wcctools

🛠️ **Web Component Catalogue Tools** — The core dashboard and UI components for building interactive component catalogues

## Overview

This is the main module of `@design.estate/dees-wcctools`, providing the complete dashboard experience for developing, testing, and documenting web components.

## Installation

```bash
pnpm add -D @design.estate/dees-wcctools
```

## Usage

### Sections-based Configuration (Recommended)

```typescript
import { setupWccTools } from '@design.estate/dees-wcctools';
import * as elements from './elements/index.js';
import * as views from './views/index.js';
import * as pages from './pages/index.js';

setupWccTools({
  sections: [
    {
      name: 'Pages',
      type: 'pages',
      items: pages,
    },
    {
      name: 'Views',
      type: 'elements',
      items: views,
      icon: 'web',
    },
    {
      name: 'Elements',
      type: 'elements',
      items: elements,
      filter: (name) => !name.startsWith('internal-'),
      sort: ([a], [b]) => a.localeCompare(b),
    },
  ],
});
```

### Legacy Format (Still Supported)

```typescript
import { setupWccTools } from '@design.estate/dees-wcctools';
import { MyButton } from './components/my-button.js';

setupWccTools({
  'my-button': MyButton,
});
```

## Exports

### Main Entry Point

| Export | Description |
|--------|-------------|
| `setupWccTools` | Initialize the component catalogue dashboard |
| `IWccConfig` | TypeScript interface for sections configuration |
| `IWccSection` | TypeScript interface for individual section |

### Recording Components

| Export | Description |
|--------|-------------|
| `RecorderService` | Service class for screen/viewport recording |
| `WccRecordButton` | Record button UI component |
| `WccRecordingPanel` | Recording options and preview panel |
| `IRecorderEvents` | TypeScript interface for recorder callbacks |
| `IRecordingOptions` | TypeScript interface for recording options |

## Section Configuration

| Property | Type | Description |
|----------|------|-------------|
| `name` | `string` | Display name for the section header |
| `type` | `'elements' \| 'pages'` | Rendering behavior |
| `items` | `Record<string, any>` | Element classes or page factories |
| `filter` | `(name, item) => boolean` | Optional filter function |
| `sort` | `([a, itemA], [b, itemB]) => number` | Optional sort function |
| `icon` | `string` | Material Symbols icon name |
| `collapsed` | `boolean` | Start section collapsed (default: false) |

## Internal Components

The module includes these internal web components:

| Component | Description |
|-----------|-------------|
| `wcc-dashboard` | Main dashboard container with routing |
| `wcc-sidebar` | Navigation sidebar with collapsible sections |
| `wcc-frame` | Responsive viewport with size controls |
| `wcc-properties` | Property panel with live editing |
| `wcc-record-button` | Recording state indicator button |
| `wcc-recording-panel` | Recording workflow UI |

## RecorderService API

For programmatic recording control:

```typescript
import { RecorderService, type IRecorderEvents } from '@design.estate/dees-wcctools';

const events: IRecorderEvents = {
  onDurationUpdate: (duration) => console.log(`Recording: ${duration}s`),
  onRecordingComplete: (blob) => saveBlob(blob),
  onAudioLevelUpdate: (level) => updateMeter(level),
  onError: (error) => console.error(error),
  onStreamEnded: () => console.log('User stopped sharing'),
};

const recorder = new RecorderService(events);

// Load available microphones
const mics = await recorder.loadMicrophones(true);

// Start audio level monitoring
await recorder.startAudioMonitoring(mics[0].deviceId);

// Start recording
await recorder.startRecording({
  mode: 'viewport',
  audioDeviceId: mics[0].deviceId,
  viewportElement: document.querySelector('.viewport'),
});

// Stop recording
recorder.stopRecording();

// Export trimmed video
const trimmedBlob = await recorder.exportTrimmedVideo(videoElement, startTime, endTime);

// Cleanup
recorder.dispose();
```

## Architecture

```
ts_web/
├── index.ts                    # Main exports
├── wcctools.interfaces.ts      # Type definitions
├── elements/
│   ├── wcc-dashboard.ts        # Root dashboard component
│   ├── wcc-sidebar.ts          # Navigation sidebar
│   ├── wcc-frame.ts            # Responsive viewport
│   ├── wcc-properties.ts       # Property editing panel
│   ├── wcc-record-button.ts    # Recording button
│   ├── wcc-recording-panel.ts  # Recording options/preview
│   └── wcctools.helpers.ts     # Shared utilities
├── services/
│   └── recorder.service.ts     # MediaRecorder abstraction
└── pages/
    └── index.ts                # Built-in pages
```

## Features

- 🎨 Interactive component preview
- 📂 Section-based sidebar with filtering & sorting
- 🔧 Real-time property editing with type detection
- 🌓 Theme switching (light/dark)
- 📱 Responsive viewport testing
- 🎬 Screen recording with trimming
- 🔗 URL-based deep linking