diff --git a/CLAUDE.md b/CLAUDE.md deleted file mode 100644 index 05934b4..0000000 --- a/CLAUDE.md +++ /dev/null @@ -1,174 +0,0 @@ -# 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 \ No newline at end of file diff --git a/changelog.md b/changelog.md index f076425..8d1a865 100644 --- a/changelog.md +++ b/changelog.md @@ -231,7 +231,7 @@ Add dees-searchbar component with live search and filter demo ## 2025-04-22 - 1.6.0 - feat(documentation/dees-heading) Add codex documentation overview and dees-heading component demo -- Introduce 'codex.md' to provide a high-level overview of project layout, component patterns, and build workflow +- Introduce contributor overview doc (`codex.md`, now consolidated into `readme.info.md`) to provide a high-level overview of project layout, component patterns, and build workflow - Add and update dees-heading component with demo to support multiple heading levels and horizontal rule styles - Update component export index to include dees-heading diff --git a/codex.md b/codex.md deleted file mode 100644 index bc9855b..0000000 --- a/codex.md +++ /dev/null @@ -1,43 +0,0 @@ -# Codex: Project Overview and Codebase Structure - -## Project Overview -- Package: `@design.estate/dees-catalog` -- Focus: Web Components library providing UI elements and layouts for modern web apps. - -## Directory Layout -- ts_web/: TypeScript source files - - elements/: Individual Web Component definitions - - pages/: Page-level templates for composite layouts -- html/: Demo/app entry point loading the bundled scripts -- dist_bundle/: Bundled browser JS and source maps -- dist_ts_web/: ES module outputs for TypeScript/web consumers -- dist_watch/: Watch-mode development bundle with live reload -- test/: Browser-based tests using `@push.rocks/tapbundle` - -## Component Patterns -- Each component in ts_web/elements/: - - Decorated with `@customElement('tag-name')` - - Extends `DeesElement` from `@design.estate/dees-element` - - Uses `@property` for reactive, reflected attributes - - Defines `static styles = [cssManager.defaultStyles, css`...`]` - - Implements `render()` returning a Lit `html` template with slots or markup - - Exposes a demo via `public static demo` linking to `.demo.ts` files - -## Build & Development Workflow -- Install dependencies: `npm install` or `pnpm install` -- Build production bundle: `npm run build` -- Start dev watch mode: `npm run watch` -- Run tests: `npm test` (launches browser fixtures) - -## Theming & Utilities -- Default global styles via `cssManager.defaultStyles` -- Theme-aware values with `cssManager.bdTheme(light, dark)` -- DOM utilities set up in `html/index.ts` using `@design.estate/dees-domtools` - -## Documentation -- `readme.md` provides an overview of all components and basic usage -- Live examples in `.demo.ts` files - accessible via component `demo` static property - -## Updates to this file -If you have pattern insisights or general changes to the codebase, please update this file. \ No newline at end of file diff --git a/readme.info.md b/readme.info.md new file mode 100644 index 0000000..64b9165 --- /dev/null +++ b/readme.info.md @@ -0,0 +1,80 @@ +# Contributor Information + +This reference consolidates the helper notes previously split across `codex.md` and `CLAUDE.md`. Use it to get oriented quickly when working on `@design.estate/dees-catalog`, a TypeScript/Lit web-components library that ships themed UI building blocks for modern web applications. + +## Project Snapshot +- Package: `@design.estate/dees-catalog` +- Description: Comprehensive catalog of reusable web components with cohesive design, advanced form inputs, data displays, and layout scaffolding. +- Entry points: builds ship to `dist_ts_web/` (ES modules) and `dist_bundle/` (browser bundle); demos live in `html/`. +- Type system: strict TypeScript targeting modern browsers (see `tsconfig.json`). + +## Repository Layout +- `ts_web/` – TypeScript source + - `elements/` – component implementations (`00*.ts` shared utilities, `dees-*.ts` components, `*.demo.ts` demos) + - `pages/` – showcase pages aggregating demos + - `index.ts` – main export surface +- `html/` – demo entry point bootstrapping bundles +- `dist_bundle/`, `dist_ts_web/`, `dist_watch/` – build outputs (production, module, and watch bundles) +- `test/` – browser/node tests powered by `@push.rocks/tapbundle` +- `scripts/` – maintenance utilities (e.g., Monaco version sync postinstall) + +## Build & Development Commands +All workflows use pnpm (see `package.json`). + +```bash +pnpm install # install dependencies +pnpm run build # tsbuild tsfolders --allowimplicitany && tsbundle element --production --bundler esbuild +pnpm run watch # tswatch element (development watch/dev server) +pnpm test # tstest test/ --web --verbose --timeout 30 --logfile +pnpm run buildDocs # tsdoc (generates docs) +tsx test/test.file.ts # run a specific test file (file must be named test.*) +``` + +`postinstall` runs `node scripts/update-monaco-version.cjs` to sync the Monaco editor version, so keep the script intact when updating dependencies. + +## Testing Guidelines +- Framework: `@push.rocks/tapbundle` with smartexpect assertions. Always review https://code.foss.global/push.rocks/smartexpect/raw/branch/master/readme.md when adding tests. +- Import pattern: + ```typescript + import { tap, expect } from '@push.rocks/tapbundle'; + ``` +- Test naming: `test.*.both.ts` for dual runtime, `.node.ts` for Node-only, `.browser.ts` for browser-only suites. +- Prefer `pnpm test` for full runs; use `tsx` for focused debugging. Type-check failing tests with `tsc --noEmit`. +- Logs live under `.nogit/testlogs/`; put ad-hoc debug artefacts in `.nogit/debug/`. + +## Component Architecture +- **Base pattern**: Components extend `DeesElement` from `@design.estate/dees-element`, use Lit decorators (`@customElement`, `@property`), and combine `cssManager.defaultStyles` with component styles. Rendering happens via Lit `html` templates; demos sit on a static `demo` property referencing a `.demo.ts` module. +- **Theming**: `cssManager.bdTheme(light, dark)` selects theme-aware values. Shared palettes live in `ts_web/elements/00colors.ts`. +- **Z-index management**: Overlays consult the registry in `ts_web/elements/00zindex.ts` (`ZIndexRegistry`) to coordinate stacking. +- **Component families**: + - Core UI (`dees-button`, `dees-badge`, `dees-icon`, …) focus on consistent theming and interactions. + - Form inputs (`dees-form`, `dees-input-*`) build on `DeesInputBase` and communicate through subjects/events for validation. + - Layout shells (`dees-appui-*`) orchestrate responsive app frames with centralized event rebroadcasts. + - Data views (`dees-table`, `dees-dataview-*`, `dees-statsgrid`) handle large datasets with virtualisation and chart integrations. + - Overlays (`dees-modal`, `dees-contextmenu`, `dees-toast`) respect the z-index registry and use shared window-layer utilities. +- **WYSIWYG editor**: `dees-input-wysiwyg` coordinates specialized handler classes (`WysiwygInputHandler`, `WysiwygKeyboardHandler`, drag/drop & modal managers) and global menus (`DeesSlashMenu`, `DeesFormattingMenu`). Rendering is imperative to preserve caret focus. + +## Implementation Guidelines +- Import external modules through `ts_web/elements/00plugins.ts`: `import * as plugins from './plugins.ts';` then reference `plugins.moduleName`. +- When creating new components: + 1. Extend `DeesElement` and decorate with `@customElement('dees-component')`. + 2. Support theming, slots, and accessibility; provide meaningful default styles. + 3. Expose a `.demo.ts` for the component and re-export via `elements/index.ts`. +- Form components must implement `getValue()` / `setValue()` and emit through `changeSubject` while honoring `disabled` and `required` states. +- Overlay components retrieve z-indices from the registry, register/unregister on show/hide, and use `DeesWindowLayer` for backdrops when appropriate. +- Avoid simplifying away functionality; prefer small, targeted changes and keep compatibility with existing APIs. + +## Common Patterns & Pitfalls +- Focus management: schedule DOM updates with `requestAnimationFrame` inside interactive editors to avoid focus loss. +- Event handling: stop propagation where nested interactive elements coexist; mix pointer and keyboard handling for accessibility. +- Performance: heavy blocks/components may load lazily; charts use debounced observers, tables rely on virtual scrolling. Watch bundle size when adding dependencies. + +## Documentation & Demos +- `readme.md` surfaces component overviews; demos in `.demo.ts` illustrate real usage. +- Update this `readme.info.md` when architectural patterns or workflows change so contributors stay in sync. + +## Recent Highlights +- Z-index registry overhaul enables dynamic stacking control across overlays. +- WYSIWYG refactor separated block handlers for maintainability. +- Dashboard grid enhancements added live drag-and-drop previews and overlap fixes. +- Monaco editor integration now reads the installed version at build time. diff --git a/readme.plan.md b/readme.plan.md index 5e1052e..04bb38a 100644 Binary files a/readme.plan.md and b/readme.plan.md differ diff --git a/ts_web/elements/dees-input-wysiwyg/dees-input-wysiwyg.ts b/ts_web/elements/dees-input-wysiwyg/dees-input-wysiwyg.ts index 261a386..944b7c0 100644 --- a/ts_web/elements/dees-input-wysiwyg/dees-input-wysiwyg.ts +++ b/ts_web/elements/dees-input-wysiwyg/dees-input-wysiwyg.ts @@ -118,6 +118,17 @@ export class DeesInputWysiwyg extends DeesInputBase { } async firstUpdated() { + if (this.value && this.value.trim().length > 0) { + const parsedBlocks = + this.outputFormat === 'html' + ? WysiwygConverters.parseHtmlToBlocks(this.value) + : WysiwygConverters.parseMarkdownToBlocks(this.value); + + if (parsedBlocks.length > 0) { + this.blocks = parsedBlocks; + } + } + this.updateValue(); this.editorContentRef = this.shadowRoot!.querySelector('.editor-content') as HTMLDivElement; @@ -988,4 +999,4 @@ export class DeesInputWysiwyg extends DeesInputBase { this.history.saveCheckpoint(this.blocks, this.selectedBlockId, cursorPosition); } } -} \ No newline at end of file +}