From f17b880b599e5ab75f58b5cf61b179670569a47e Mon Sep 17 00:00:00 2001 From: Philipp Kunz Date: Tue, 22 Apr 2025 12:30:22 +0000 Subject: [PATCH] feat(documentation/dees-heading): Add codex documentation overview and dees-heading component demo --- changelog.md | 7 ++ codex.md | 43 ++++++++++ ts_web/00_commitinfo_data.ts | 2 +- ts_web/elements/dees-heading.demo.ts | 14 ++++ ts_web/elements/dees-heading.ts | 115 +++++++++++++++++++++++++++ ts_web/elements/index.ts | 1 + 6 files changed, 181 insertions(+), 1 deletion(-) create mode 100644 codex.md create mode 100644 ts_web/elements/dees-heading.demo.ts create mode 100644 ts_web/elements/dees-heading.ts diff --git a/changelog.md b/changelog.md index 031bec2..4ca69d1 100644 --- a/changelog.md +++ b/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 diff --git a/codex.md b/codex.md new file mode 100644 index 0000000..bc9855b --- /dev/null +++ b/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. \ No newline at end of file diff --git a/ts_web/00_commitinfo_data.ts b/ts_web/00_commitinfo_data.ts index 24934ef..c683877 100644 --- a/ts_web/00_commitinfo_data.ts +++ b/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.' } diff --git a/ts_web/elements/dees-heading.demo.ts b/ts_web/elements/dees-heading.demo.ts new file mode 100644 index 0000000..9362097 --- /dev/null +++ b/ts_web/elements/dees-heading.demo.ts @@ -0,0 +1,14 @@ +import { html } from '@design.estate/dees-element'; + +export function demoFunc() { + return html` + This is a H1 heading + This is a H2 heading + This is a H3 heading + This is a H4 heading + This is a H5 heading + This is a H6 heading + This is an hr heading + This is an hr small heading + `; +} \ No newline at end of file diff --git a/ts_web/elements/dees-heading.ts b/ts_web/elements/dees-heading.ts new file mode 100644 index 0000000..6406b1f --- /dev/null +++ b/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`

`; + case '2': + return html`

`; + case '3': + return html`

`; + case '4': + return html`

`; + case '5': + return html`
`; + case '6': + return html`
`; + case 'hr': + return html`
`; + case 'hr-small': + return html`
`; + default: + return html`

`; + } + } +} \ No newline at end of file diff --git a/ts_web/elements/index.ts b/ts_web/elements/index.ts index e69b502..3cec901 100644 --- a/ts_web/elements/index.ts +++ b/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';