174 lines
6.4 KiB
Markdown
174 lines
6.4 KiB
Markdown
# 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 |