dees-catalog/readme.info.md

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).

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:

  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.