# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

@design.estate/dees-catalog is a comprehensive web components library built with TypeScript and LitElement. It provides a large collection of UI components for building modern web applications with consistent design and behavior.

## Build and Development Commands

```bash
# Install dependencies
pnpm install

# Build the project
pnpm run build
# This runs: tsbuild tsfolders --allowimplicitany && tsbundle element --production --bundler esbuild

# Run development watch mode
pnpm run watch
# This runs: tswatch element

# Run tests (browser tests)
pnpm test
# This runs: tstest test/ --web --verbose --timeout 30 --logfile

# Run a specific test file
tsx test/test.wysiwyg-basic.browser.ts --verbose

# Build documentation
pnpm run buildDocs
```

### Testing Notes
- Test files follow the pattern: `test.*.browser.ts`, `test.*.node.ts`, or `test.*.both.ts`
- Browser tests run in a headless browser environment
- Use `--logfile` option to store logs in `.nogit/testlogs/`
- For debugging, create files in `.nogit/debug/` and run with `tsx`

## Architecture Overview

### Component Structure
The library is organized into several categories:

1. **Core UI Components** (`dees-button`, `dees-badge`, `dees-icon`, etc.)
   - Basic building blocks with consistent theming
   - All support light/dark themes via `cssManager.bdTheme()`

2. **Form Components** (`dees-form`, `dees-input-*`)
   - Complete form system with validation
   - Base class `DeesInputBase` provides common functionality
   - Form data collection via `DeesForm` container

3. **Layout Components** (`dees-appui-*`)
   - Application shell components
   - `DeesAppuiBase` orchestrates the entire layout
   - Grid-based responsive design

4. **Data Display** (`dees-table`, `dees-dataview-*`, `dees-statsgrid`)
   - Complex data visualization components
   - Interactive tables with sorting/filtering
   - Chart components using ApexCharts

5. **Overlays** (`dees-modal`, `dees-contextmenu`, `dees-toast`)
   - Managed by central z-index registry
   - Window layer system for proper stacking

### Key Architectural Patterns

#### Z-Index Management
All overlay components use a centralized z-index registry system:
- Definition in `ts_web/elements/00zindex.ts`
- Dynamic z-index assignment via `ZIndexRegistry` class
- Components get z-index from registry when showing
- Ensures proper stacking order (dropdowns above modals, etc.)

#### Theme System
- All components support light/dark themes
- Use `cssManager.bdTheme(lightValue, darkValue)` for theme-aware colors
- Consistent color palette defined in `00colors.ts`

#### Component Demo System
- Each component has a static `demo` property
- Demo functions in separate `.demo.ts` files
- Showcase pages aggregate demos (e.g., `input-showcase.ts`)

#### WYSIWYG Editor Architecture
The WYSIWYG editor uses a sophisticated architecture with separated concerns:
- **Main Component**: `dees-input-wysiwyg.ts` - Orchestrates the editor
- **Handler Classes**:
  - `WysiwygInputHandler` - Handles text input and block transformations
  - `WysiwygKeyboardHandler` - Manages keyboard shortcuts and navigation
  - `WysiwygDragDropHandler` - Manages block reordering
  - `WysiwygModalManager` - Shows configuration modals
  - `WysiwygBlockOperations` - Core block manipulation logic
- **Global Menus**: 
  - `DeesSlashMenu` and `DeesFormattingMenu` render globally to avoid focus issues
  - Singleton pattern ensures single instance
- **Programmatic Rendering**: Uses manual DOM manipulation to prevent focus loss

### Component Communication
- Custom events for parent-child communication
- Form components emit standardized events (`change`, `blur`, etc.)
- Complex components like `DeesAppuiBase` re-emit child events

### Build System
- TypeScript compilation with decorators support
- Web component bundling with esbuild
- Element exports in `ts_web/elements/index.ts`
- Distribution builds in `dist_ts_web/`

## Important Implementation Details

### When Creating New Components
1. Extend `DeesElement` from `@design.estate/dees-element`
2. Use `@customElement('dees-componentname')` decorator
3. Implement theme support with `cssManager.bdTheme()`
4. Create a demo function in a separate `.demo.ts` file
5. Export from `elements/index.ts`

### Form Input Components
1. Extend `DeesInputBase` for form inputs
2. Implement `getValue()` and `setValue()` methods
3. Use `changeSubject.next(this)` to emit changes
4. Support `disabled` and `required` properties

### Overlay Components
1. Import z-index from `00zindex.ts`
2. Get z-index from registry when showing: `zIndexRegistry.getNextZIndex()`
3. Register/unregister with the registry
4. Use `DeesWindowLayer` for backdrop if needed

### Testing Components
1. Create test files in `test/` directory
2. Use `@git.zone/tstest` with tap-bundle
3. Test in browser environment for web components
4. Use proper async/await for component lifecycle

## Common Patterns and Pitfalls

### Focus Management
- WYSIWYG editor uses programmatic rendering to prevent focus loss
- Use `requestAnimationFrame` for timing-sensitive focus operations
- Avoid reactive re-renders during user input

### Event Handling
- Prevent event bubbling in nested interactive components
- Use `pointer-events: none/auto` for click-through behavior
- Handle both mouse and keyboard events for accessibility

### Performance Considerations
- Large components (editor, terminal) use lazy loading
- Charts use debounced resize observers
- Tables implement virtual scrolling for large datasets

## File Organization
```
ts_web/
├── elements/           # All component files
│   ├── 00*.ts         # Shared utilities (colors, z-index, plugins)
│   ├── dees-*.ts      # Component implementations
│   ├── dees-*.demo.ts # Component demos
│   ├── interfaces/    # Shared TypeScript interfaces
│   ├── helperclasses/ # Utility classes (FormController)
│   └── wysiwyg/       # WYSIWYG editor subsystem
├── pages/             # Demo showcase pages
└── index.ts           # Main export file
```

## Recent Major Changes
- Z-Index Registry System (2025-12-24): Dynamic stacking order management
- WYSIWYG Refactoring (2025-06-24): Complete architecture overhaul with separated concerns
- Form System Enhancement: Unified validation and data collection
- Theme System: Consistent light/dark theme support across all components