dees-catalog/CLAUDE.md

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

# 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