feat: consolidate contributor documentation by merging codex.md and CLAUDE.md into readme.info.md
This commit is contained in:
174
CLAUDE.md
174
CLAUDE.md
@@ -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
|
||||
@@ -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
|
||||
|
||||
|
||||
43
codex.md
43
codex.md
@@ -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.
|
||||
80
readme.info.md
Normal file
80
readme.info.md
Normal file
@@ -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.
|
||||
BIN
readme.plan.md
BIN
readme.plan.md
Binary file not shown.
@@ -118,6 +118,17 @@ export class DeesInputWysiwyg extends DeesInputBase<string> {
|
||||
}
|
||||
|
||||
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<string> {
|
||||
this.history.saveCheckpoint(this.blocks, this.selectedBlockId, cursorPosition);
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user