@design.estate/dees-domtools

tools that simplify dom interactions.

readme.md for @design.estate/dees-domtools

🎨 A comprehensive TypeScript toolkit for simplifying DOM manipulation, CSS management, and web component development

Modern web development made elegant. @design.estate/dees-domtools provides a powerful suite of utilities for managing complex CSS structures, handling browser events, implementing smooth scrolling, and building responsive web applications with ease.

Features

Installation

npm install @design.estate/dees-domtools
# or
pnpm add @design.estate/dees-domtools

Quick Start

import { DomTools } from '@design.estate/dees-domtools';

// Initialize DomTools (singleton pattern - safe to call multiple times)
const domtools = await DomTools.setupDomTools();

// Wait for DOM to be ready
await domtools.domReady.promise;

// Now you're ready to rock! 🎸
console.log('DOM is ready, head and body elements are available');

Core API

DomTools Instance

The DomTools class is the heart of the library. It provides a singleton instance that manages all the utilities.

import { DomTools } from '@design.estate/dees-domtools';

// Setup with options
const domtools = await DomTools.setupDomTools({
  ignoreGlobal: false // Set to true to create isolated instance
});

// Access DOM elements (available after domReady)
await domtools.domReady.promise;
const head = domtools.elements.headElement;
const body = domtools.elements.bodyElement;

Key Properties:

Lifecycle Promises:

Responsive Breakpoints

Built-in breakpoint system with both media queries and container queries:

import { breakpoints, css } from '@design.estate/dees-domtools';
import { css as litCss } from 'lit';

// Breakpoint values (in pixels)
breakpoints.desktop   // 1600px
breakpoints.notebook  // 1240px
breakpoints.tablet    // 1024px
breakpoints.phablet   // 600px
breakpoints.phone     // 400px

// Use with Lit components
const myStyles = litCss`
  .container {
    padding: 20px;
  }

  ${breakpoints.cssForTablet(litCss`
    .container {
      padding: 10px;
    }
  `)}

  ${breakpoints.cssForPhone(litCss`
    .container {
      padding: 5px;
    }
  `)}
`;

Preset viewport helpers (emit both @media and @container wccToolsViewport):

Low-level helpers for custom constraints and component-scoped containers:

import { breakpoints } from '@design.estate/dees-domtools';
import { css as litCss } from 'lit';

// Viewport-level with custom constraints (emits @media + @container wccToolsViewport)
breakpoints.cssForConstraint({ maxWidth: 800 })(litCss`.box { padding: 8px; }`)

// Component-level — targets a named container (no @media fallback)
breakpoints.cssForContainer(
  litCss`.grid { columns: 1; }`,
  '(max-width: 600px)',
  'my-component'  // CSS container-name
)

// Component-level with custom constraints (curried)
breakpoints.cssForConstraintContainer({ maxWidth: 500 }, 'my-component')(litCss`
  .grid { gap: 8px; }
`)

// Generate containment styles for :host (used by @containerResponsive decorator)
breakpoints.containerContextStyles('my-component')
// → :host { container-type: inline-size; container-name: my-component; }

Exported types:

Theme Management

Automatic theme detection with system preference support:

const domtools = await DomTools.setupDomTools();
const { themeManager } = domtools;

// Toggle between dark and light
themeManager.toggleDarkBright();

// Set specific theme
themeManager.goDark();
themeManager.goBright();

// Enable automatic global background changes
await themeManager.enableAutomaticGlobalThemeChange();

// Subscribe to theme changes
themeManager.themeObservable.subscribe((isBright) => {
  console.log(`Theme is now: ${isBright ? 'light' : 'dark'}`);
});

// Check current theme
if (themeManager.goBrightBoolean) {
  console.log('Light mode active');
}

Keyboard Shortcuts

Handle keyboard events with ease, including complex combinations:

import { Keyboard, Key } from '@design.estate/dees-domtools';

const domtools = await DomTools.setupDomTools();
await domtools.domReady.promise;

// Access the keyboard instance
const { keyboard } = domtools;

// Listen for Ctrl+S
keyboard.on([Key.Ctrl, Key.S]).subscribe((event) => {
  event.preventDefault();
  console.log('Save triggered!');
});

// Listen for Ctrl+Shift+P
keyboard.on([Key.Ctrl, Key.Shift, Key.P]).subscribe(() => {
  console.log('Command palette opened!');
});

// Programmatically trigger key presses
keyboard.triggerKeyPress([Key.Ctrl, Key.S]);

// Clean up when done
keyboard.stopListening();

Available Keys:

All standard keyboard keys are available in the Key enum, including:

Smooth Scrolling

Powerful scrolling utilities with Lenis integration:

const domtools = await DomTools.setupDomTools();
const { scroller } = domtools;

// Scroll to an element smoothly
const targetElement = document.querySelector('#section-2');
await scroller.toElement(targetElement, {
  duration: 1000,
  easing: 'easeInOutQuad'
});

// Enable Lenis smooth scrolling
await scroller.enableLenisScroll({
  disableOnNativeSmoothScroll: true // Auto-disable if browser has native smooth scroll
});

// Register scroll callbacks
scroller.onScroll(() => {
  console.log('Page scrolled!');
});

// Detect if native smooth scrolling is enabled
const hasNativeSmooth = await scroller.detectNativeSmoothScroll();

CSS Utilities

Helper functions for common CSS patterns:

import { css } from '@design.estate/dees-domtools';

// Create responsive grid columns
const gridTemplate = css.cssGridColumns(4, 16);
// Returns: calc((100%/4) - (48px/4)) calc((100%/4) - (48px/4)) ...

// Use in your styles
const styles = `
  .grid {
    display: grid;
    grid-template-columns: ${gridTemplate};
    gap: 16px;
  }
`;

Global Styles & External Resources

const domtools = await DomTools.setupDomTools();

// Add global CSS
await domtools.setGlobalStyles(`
  body {
    margin: 0;
    font-family: 'Inter', sans-serif;
  }
`);

// Load external CSS
await domtools.setExternalCss('https://fonts.googleapis.com/css2?family=Inter:wght@400;600;700&display=swap');

// Load external JavaScript
await domtools.setExternalScript('https://cdn.example.com/analytics.js');

Website Metadata

Manage your website's metadata easily:

const domtools = await DomTools.setupDomTools();

await domtools.setWebsiteInfo({
  metaObject: {
    title: 'My Awesome App',
    description: 'The best app ever created',
    keywords: ['awesome', 'app', 'web'],
    author: 'Your Name'
  },
  faviconUrl: '/favicon.ico',
  appleTouchIconUrl: '/apple-touch-icon.png'
});

Web Component Base Styles

Kickstart your Lit elements with pre-configured styles:

import { LitElement } from 'lit';
import { elementBasic } from '@design.estate/dees-domtools';

class MyElement extends LitElement {
  static styles = [elementBasic.staticStyles];

  async connectedCallback() {
    super.connectedCallback();
    await elementBasic.setup(this);
  }
}

The elementBasic.staticStyles includes:

State Management

Integrated state management with smartstate:

const domtools = await DomTools.setupDomTools();

// Access the state part
const state = domtools.domToolsStatePart;

// Get current state
const currentState = state.getState();
console.log(currentState.virtualViewport); // 'native'
console.log(currentState.jwt); // ''

// Update state
state.setState({
  virtualViewport: 'tablet',
  jwt: 'your-token-here'
});

// Subscribe to state changes
state.subscribe((newState) => {
  console.log('State updated:', newState);
});

Run Once Pattern

Execute expensive operations only once, even if called multiple times:

const domtools = await DomTools.setupDomTools();

// This will only execute once, even if called multiple times
const result = await domtools.runOnce('myExpensiveOperation', async () => {
  console.log('Running expensive operation...');
  await someExpensiveAsyncOperation();
  return 'result';
});

// Subsequent calls return the same result without re-executing
const sameResult = await domtools.runOnce('myExpensiveOperation', async () => {
  console.log('This will never run!');
  return 'different result';
});

console.log(result === sameResult); // true

Error handling is built-in - if the function throws, all waiting callers receive the same error.

Advanced Usage

Combining Features

Here's a real-world example combining multiple features:

import { DomTools, breakpoints, elementBasic, Key } from '@design.estate/dees-domtools';
import { LitElement, html, css as litCss } from 'lit';
import { customElement } from 'lit/decorators.js';

@customElement('my-app')
class MyApp extends LitElement {
  static styles = [
    elementBasic.staticStyles,
    litCss`
      :host {
        display: block;
        padding: 2rem;
      }

      ${breakpoints.cssForTablet(litCss`
        :host {
          padding: 1rem;
        }
      `)}
    `
  ];

  private domtools?: DomTools;

  async connectedCallback() {
    super.connectedCallback();

    // Setup DomTools
    this.domtools = await elementBasic.setup(this);
    await this.domtools.domReady.promise;

    // Setup keyboard shortcuts
    this.domtools.keyboard.on([Key.Ctrl, Key.K]).subscribe(() => {
      this.openCommandPalette();
    });

    // Subscribe to theme changes
    this.domtools.themeManager.themeObservable.subscribe((isBright) => {
      this.requestUpdate();
    });

    // Enable smooth scrolling
    await this.domtools.scroller.enableLenisScroll({
      disableOnNativeSmoothScroll: true
    });
  }

  private openCommandPalette() {
    console.log('Command palette opened!');
  }

  render() {
    const isDark = !this.domtools?.themeManager.goBrightBoolean;

    return html`
      <div class="app" style="background: ${isDark ? '#1a1a1a' : '#ffffff'}">
        <h1>My Awesome App</h1>
        <button @click=${() => this.domtools?.themeManager.toggleDarkBright()}>
          Toggle Theme
        </button>
      </div>
    `;
  }
}

TypeScript Support

This package is written in TypeScript and provides full type definitions:

import type {
  IDomToolsState,
  IDomToolsContructorOptions,
  TViewport
} from '@design.estate/dees-domtools';

// Custom state interface
interface MyState extends IDomToolsState {
  customProperty: string;
}

// Type-safe viewport handling
const viewport: TViewport = 'tablet';

Browser Support

Targets the latest version of Chrome. For other browsers, you may need to include polyfills.

Why @design.estate/dees-domtools?

This library integrates with the design.estate ecosystem:

This repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the license file within this repository.

Please note: The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH and are not included within the scope of the MIT license granted herein. Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines, and any usage must be approved in writing by Task Venture Capital GmbH.

Company Information

Task Venture Capital GmbH Registered at District court Bremen HRB 35230 HB, Germany

By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.

changelog.md for @design.estate/dees-domtools

2026-03-27 - 2.5.4 - fix(build)

remove npm bundling from build script and align documented jwt default state

2026-03-27 - 2.5.3 - fix(tsconfig)

add Node.js type definitions to TypeScript compiler options

2026-03-27 - 2.5.2 - fix(build,types)

migrate smart config filename and tighten TypeScript null handling

2026-03-11 - 2.5.1 - fix(breakpoints)

rename exported functions to reflect constraint-based API: cssForCustom -> cssForConstraint and cssForCustomContainer -> cssForConstraintContainer; update README usage

2026-03-11 - 2.5.0 - feat(breakpoints)

document preset viewport helpers, low-level container helpers, and exported types for breakpoints

2026-03-11 - 2.4.0 - feat(css.breakpoints)

add constraint-based CSS breakpoint helpers and container context utilities

2026-03-05 - 2.3.9 - fix(deps)

bump dependency and devDependency versions, update lik import paths, add tsbundle config, export test start, and tidy readme install snippet

2026-01-27 - 2.3.8 - fix(domtools)

remove default 'loading...' meta title in WebSetup and use an empty string as the default

2026-01-04 - 2.3.7 - fix(deps)

bump dependencies, update build/test configuration, and reorganize npmextra configuration

2025-11-16 - 2.3.6 - fix(readme)

Normalize README formatting and improve breakpoint helpers section

2025-11-16 - 2.3.5 - fix(dependencies)

bump dependency versions in package.json

2025-11-16 - 2.3.4 - fix(domtools)

Prevent race conditions during DomTools initialization and improve runOnce error handling

2025-06-20 - 2.3.3 - fix(package.json)

Update dependency versions and add pnpm package manager field

2025-02-01 - 2.3.2 - fix(scroller)

Rename method from scrollToElement to toElement for consistency

2025-01-31 - 2.3.1 - fix(scroller)

Removed passive option from scroll event listener

2025-01-31 - 2.3.0 - feat(scroller)

Enhance Scroller class with callback execution and adaptive scroll listener

2025-01-31 - 2.2.0 - feat(core)

Enhance scrolling capabilities by integrating Scroller class and adding lenis support

2025-01-09 - 2.1.1 - fix(themamanager)

Fixed automatic global theme change subscription for background updates.

2025-01-09 - 2.1.0 - feat(themeManager)

Exposed method to enable automatic global theme change.

2024-10-21 - 2.0.65 - fix(ThemeManager)

Refactor ThemeManager class to separate global style setting logic

2024-10-06 - 2.0.64 - fix(pluginexports)

Add missing import for smartrouter in pluginexports.

2024-10-06 - 2.0.63 - fix(dependencies)

Update @push.rocks/smartrouter to version ^1.3.2 for better compatibility

2024-10-06 - 2.0.62 - fix(dependencies)

Update dependencies to resolve potential issues and improve stability

2024-10-04 - 2.0.61 - fix(core)

Correct import statement for SweetScroll.

2024-10-02 - 2.0.60 - fix(dependencies)

Update dependencies to latest versions

2024-10-02 - 2.0.59 - fix(core)

Refactor plugin exports to improve modularity

2024-07-01 - 2.0.58 - fix(dependencies)

Update dependencies and correct font family in styles

2024-04-20 - 2.0.57 - Documentation

Update to project documentation

2023-10-23 - 2.0.42...2.0.55 - Core

Multiple updates and fixes

2023-10-07 - 2.0.41...2.0.51 - Core

Multiple updates and fixes

2023-09-17 - 2.0.40 - Core

Fixes in core functionality

2023-08-07 - 2.0.36...2.0.38 - Core

Multiple updates and fixes

2023-04-05 - 2.0.28...2.0.30 - Core

Multiple updates and fixes

2023-01-07 - 2.0.26...2.0.27 - Core

Multiple updates and fixes

2022-12-31 - 2.0.24...2.0.25 - Core

Multiple updates and fixes

2022-08-01 - 2.0.22...2.0.23 - Core

Multiple updates and fixes

2022-05-01 - 2.0.19...2.0.21 - Core

Multiple updates and fixes

2022-04-22 - 2.0.18...2.0.19 - Core

Multiple updates and fixes

2022-04-21 - 2.0.10...2.0.17 - Core

Multiple updates and fixes

2022-03-18 - 2.0.0 - Core

Major release

2021-11-21 - 1.0.98...1.0.99 - Core

Multiple updates and fixes

2021-09-16 - 1.0.94...1.0.95 - Core

Multiple updates and fixes

2021-09-08 - 1.0.91...1.0.93 - Core

Multiple updates and fixes

2021-09-01 - 1.0.89...1.0.90 - Core

Multiple updates and fixes

2021-08-19 - 1.0.87 - Core

Fixes in core functionality

2021-03-10 - 1.0.84...1.0.86 - Core

Multiple updates and fixes

2020-12-07 - 1.0.79...1.0.83 - Core

Multiple updates and fixes

2020-11-30 - 1.0.74...1.0.77 - Core

Multiple updates and fixes

2020-11-24 - 1.0.66...1.0.70 - Core

Multiple updates and fixes

2020-11-23 - 1.0.64...1.0.65 - Core

Multiple updates and fixes

2020-11-06 - 1.0.61...1.0.63 - Core

Multiple updates and fixes

2020-10-07 - 1.0.53...1.0.55 - Core

Multiple updates and fixes

2020-09-16 - 1.0.49...1.0.52 - Core

Multiple updates and fixes

2020-09-13 - 1.0.45...1.0.47 - Core

Multiple updates and fixes

2020-09-12 - 1.0.41...1.0.44 - Core

Multiple updates and fixes

2020-07-27 - 1.0.38...1.0.40 - Core

Multiple updates and fixes

2020-06-28 - 1.0.29...1.0.36 - Core

Multiple updates and fixes

2020-06-03 - 1.0.26...1.0.28 - Core

Multiple updates and fixes

2020-05-28 - 1.0.21...1.0.25 - Core

Multiple updates and fixes

2020-05-27 - 1.0.18...1.0.20 - Core

Multiple updates and fixes

2020-05-26 - 1.0.16...1.0.17 - Core

Multiple updates and fixes

2020-05-25 - 1.0.14...1.0.15 - Core

Multiple updates and fixes

2020-05-24 - 1.0.11...1.0.13 - Core

Multiple updates and fixes

2020-05-23 - 1.0.3...1.0.10 - Core

Multiple updates and fixes