feat(documentation/dees-heading): Add codex documentation overview and dees-heading component demo

changelog.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 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
+- 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
+
 ## 2025-04-18 - 1.5.6 - fix(dependencies)
 Bump dependency versions and update demo code references
 

codex.md

@@ -0,0 +1,43 @@
+# 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.

ts_web/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@design.estate/dees-catalog',
-  version: '1.5.6',
+  version: '1.6.0',
   description: 'A comprehensive library that provides dynamic web components for building sophisticated and modern web applications using JavaScript and TypeScript.'
 }

ts_web/elements/dees-heading.demo.ts

@@ -0,0 +1,14 @@
+import { html } from '@design.estate/dees-element';
+
+export function demoFunc() {
+  return html`
+    <dees-heading level="1">This is a H1 heading</dees-heading>
+    <dees-heading level="2">This is a H2 heading</dees-heading>
+    <dees-heading level="3">This is a H3 heading</dees-heading>
+    <dees-heading level="4">This is a H4 heading</dees-heading>
+    <dees-heading level="5">This is a H5 heading</dees-heading>
+    <dees-heading level="6">This is a H6 heading</dees-heading>
+    <dees-heading level="hr">This is an hr heading</dees-heading>
+    <dees-heading level="hr-small">This is an hr small heading</dees-heading>
+  `;
+}

ts_web/elements/dees-heading.ts

@@ -0,0 +1,115 @@
+import {
+  customElement,
+  html,
+  css,
+  property,
+  cssManager,
+  type TemplateResult,
+  DeesElement,
+  type CSSResult,
+} from '@design.estate/dees-element';
+
+import { demoFunc } from './dees-heading.demo.js';
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'dees-heading': DeesHeading;
+  }
+}
+
+@customElement('dees-heading')
+export class DeesHeading extends DeesElement {
+  // demo
+  public static demo = demoFunc;
+
+  // properties
+  /**
+   * Heading level: 1-6 for h1-h6, or 'hr' for horizontal rule style
+   */
+  @property({ type: String, reflect: true })
+  public level: '1' | '2' | '3' | '4' | '5' | '6' | 'hr' | 'hr-small' = '1';
+
+  // STATIC STYLES
+  public static styles: CSSResult[] = [
+    cssManager.defaultStyles,
+    css`
+      /* Heading styles */
+      h1, h2, h3, h4, h5, h6 {
+        margin: 16px 0 8px;
+        font-weight: 600;
+        color: ${cssManager.bdTheme('#000', '#fff')};
+      }
+      h1 { font-size: 32px; font-family: 'Cal Sans'; letter-spacing: 0.025em;}
+      h2 { font-size: 28px; }
+      h3 { font-size: 24px; }
+      h4 { font-size: 20px; }
+      h5 { font-size: 16px; }
+      h6 { font-size: 14px; }
+      /* Horizontal rule style heading */
+      .heading-hr {
+        display: flex;
+        align-items: center;
+        text-align: center;
+        margin: 16px 0;
+        color: ${cssManager.bdTheme('#000', '#fff')};
+      }
+      /* Fade lines toward and away from text for hr style */
+      .heading-hr::before {
+        content: '';
+        flex: 1;
+        height: 1px;
+        /* fade in toward center */
+        background: ${cssManager.bdTheme(
+          'linear-gradient(to right, transparent, #ccc)',
+          'linear-gradient(to right, transparent, #333)'
+        )};
+        margin: 0 8px;
+      }
+      .heading-hr::after {
+        content: '';
+        flex: 1;
+        height: 1px;
+        /* fade out away from center */
+        background: ${cssManager.bdTheme(
+          'linear-gradient(to right, #ccc, transparent)',
+          'linear-gradient(to right, #333, transparent)'
+        )};
+        margin: 0 8px;
+      }
+      /* Small hr variant with reduced margins */
+      .heading-hr.heading-hr-small {
+        margin: 8px 0;
+        font-size: 12px;
+      }
+      .heading-hr.heading-hr-small::before,
+      .heading-hr.heading-hr-small::after {
+        margin: 0 8px;
+      }
+    `,
+  ];
+
+
+  // INSTANCE
+  public render(): TemplateResult {
+    switch (this.level) {
+      case '1':
+        return html`<h1><slot></slot></h1>`;
+      case '2':
+        return html`<h2><slot></slot></h2>`;
+      case '3':
+        return html`<h3><slot></slot></h3>`;
+      case '4':
+        return html`<h4><slot></slot></h4>`;
+      case '5':
+        return html`<h5><slot></slot></h5>`;
+      case '6':
+        return html`<h6><slot></slot></h6>`;
+      case 'hr':
+        return html`<div class="heading-hr"><slot></slot></div>`;
+      case 'hr-small':
+        return html`<div class="heading-hr heading-hr-small"><slot></slot></div>`;
+      default:
+        return html`<h1><slot></slot></h1>`;
+    }
+  }
+}

ts_web/elements/index.ts

@@ -18,6 +18,7 @@ export * from './dees-editor-markdown.js';
 export * from './dees-editor-markdownoutlet.js';
 export * from './dees-form-submit.js';
 export * from './dees-form.js';
+export * from './dees-heading.js';
 export * from './dees-hint.js';
 export * from './dees-icon.js';
 export * from './dees-input-checkbox.js';