Browser-side TypeScript utilities for bootstrapping DOM work, responsive styling, theme handling, scrolling, metadata setup, and Lit-based web components.

It gives you a singleton-style DomTools runtime plus a few focused exports for CSS breakpoints, base element styling, and low-level integrations with the underlying design.estate and push.rocks packages.

Issue Reporting and Security

For reporting bugs, issues, or security vulnerabilities, please visit community.foss.global/. This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a code.foss.global/ account to submit Pull Requests directly.

Installation

pnpm add @design.estate/dees-domtools

What It Includes

DomTools for one-time app bootstrap and shared browser services
breakpoints helpers for viewport and container-query driven Lit CSS
css.cssGridColumns() for simple grid-template generation
elementBasic helpers for Lit base styles and one-time global CSS setup
TypedRequest re-exported from @api.global/typedrequest
plugins for direct access to the package ecosystem used internally

The plugins export keeps the commonly used downstream namespaces available, including plugins.smartdelay, plugins.smartstate, plugins.smartpromise, plugins.smartrouter, plugins.smartrx, plugins.smarturl, and plugins.typedrequest.

Quick Start

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

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

console.log(domtools.elements.headElement);
console.log(domtools.elements.bodyElement);

setupDomTools() is safe to call repeatedly. By default it returns a shared global instance and avoids duplicate initialization work.

If you need an isolated instance for testing or short-lived usage, pass ignoreGlobal: true. Isolated instances follow the same domToolsReady and domReady lifecycle as the shared singleton.

DomTools Lifecycle

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

const domtools = await DomTools.setupDomTools({
  ignoreGlobal: false,
});

await domtools.domToolsReady.promise;
await domtools.domReady.promise;

setupDomTools() resolves once the instance is initialized and its readiness listeners are installed. domReady resolves later, once document.head and document.body are available.

Main instance properties:

elements.headElement and elements.bodyElement
router from @push.rocks/smartrouter
websetup from @push.rocks/websetup
smartstate and domToolsStatePart
themeManager
scroller
keyboard after domReady
deesComms
convenience.typedrequest, convenience.smartdelay, convenience.smartjson, convenience.smarturl

If you need the already-created global instance synchronously, use DomTools.getGlobalDomToolsSync() after startup has completed.

Cleanup

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

const domtools = await DomTools.setupDomTools({
  ignoreGlobal: true,
});

// ...use the instance

domtools.dispose();

dispose() removes the listeners and DOM resources owned by that DomTools instance. For shared global usage you usually keep the singleton alive for the lifetime of the page, but disposal is useful for tests and intentionally short-lived isolated instances.

DOM, CSS, and External Resources

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

const domtools = await DomTools.setupDomTools();

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

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

await domtools.setExternalScript('https://cdn.example.com/some-script.js');

For page metadata and favicons:

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

const domtools = await DomTools.setupDomTools();

await domtools.setWebsiteInfo({
  metaObject: {
    title: 'Example App',
    description: 'A browser app bootstrapped with DomTools',
  },
  faviconUrl: '/favicon.ico',
});

Theme Management

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

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

themeManager.themeObservable.subscribe((isBright) => {
  console.log('bright mode?', isBright);
});

themeManager.goDark();
themeManager.goBright();
themeManager.toggleDarkBright();

await themeManager.enableAutomaticGlobalThemeChange();

The theme manager starts from prefers-color-scheme and publishes updates through an RxJS ReplaySubject<boolean>.

enableAutomaticGlobalThemeChange() waits for domReady, so it is safe to call before document.body exists.

Keyboard Shortcuts

The keyboard helper is created after document.body exists, so wait for domReady before using it.

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

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

const keyboard = domtools.keyboard!;
const { keyEnum } = keyboard;

keyboard.on([keyEnum.Ctrl, keyEnum.S]).subscribe(() => {
  console.log('save triggered');
});

keyboard.triggerKeyPress([keyEnum.Ctrl, keyEnum.S]);

Scrolling

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

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

scroller.onScroll(() => {
  console.log('scroll event');
});

await scroller.enableLenisScroll({
  disableOnNativeSmoothScroll: true,
});

const section = document.querySelector('#details') as HTMLElement;
await scroller.toElement(section, { duration: 600 });

The scroller uses native scroll listeners by default and switches to Lenis when enabled.

Responsive CSS Helpers

breakpoints is designed for Lit CSS and ships both preset breakpoints and lower-level helpers.

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

const styles = css`
  :host {
    display: block;
    padding: 24px;
  }

  ${breakpoints.cssForTablet(css`
    :host {
      padding: 16px;
    }
  `)}

  ${breakpoints.cssForPhone(css`
    :host {
      padding: 10px;
    }
  `)}
`;

Available values:

breakpoints.desktop => 1600
breakpoints.notebook => 1240
breakpoints.tablet => 1024
breakpoints.phablet => 600
breakpoints.phone => 400

Available helpers:

cssForDesktop()
cssForNotebook()
cssForTablet()
cssForPhablet()
cssForPhone()
cssForViewport()
cssForContainer()
cssForConstraint()
cssForConstraintContainer()
containerContextStyles()

Viewport helpers emit both @media and @container wccToolsViewport rules. Container helpers target a named CSS container only.

CSS Utility

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

const columns = css.cssGridColumns(3, 24);

console.log(columns);

This returns a ready-to-insert grid-template-columns string.

Lit Element Setup

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

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

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

  render() {
    return html`<p>Hello DOM tools</p>`;
  }
}

elementBasic.setup() performs the shared DomTools setup and injects the package's global base styles once.

The returned promise resolves after the shared base styles have been injected, and domtools.globalStylesReady resolves at the same point.

State and One-Time Work

domToolsStatePart starts with this shape:

{
  virtualViewport: 'native',
  jwt: '',
}

You can also guard expensive async work with runOnce():

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

const domtools = await DomTools.setupDomTools();

const result = await domtools.runOnce('load-config', async () => {
  return { ok: true };
});

Repeated callers receive the first result, and repeated failures re-throw the stored error.

Extra Exports

import { TypedRequest, plugins } from '@design.estate/dees-domtools';

TypedRequest is re-exported for typed request flows
plugins exposes the underlying modules used by the package, including smartrouter, smartstate, smartrx, smartpromise, typedrequest, and deesComms

Runtime Notes

This package is browser-oriented and touches window, document, navigator, and matchMedia
keyboard is null until domReady resolves
The published package targets the latest Chrome via browserslist

License and Legal Information

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

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 or third parties, 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 or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.

readme.md

@design.estate/dees-domtools