81 lines
5.8 KiB
Markdown
81 lines
5.8 KiB
Markdown
# 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.
|