v2.5.4

changelog.md

@@ -1,5 +1,51 @@
 # Changelog
 
+## 2026-03-27 - 2.5.4 - fix(build)
+remove npm bundling from build script and align documented jwt default state
+
+- Updates the build script to run tsbundle without the npm target
+- Bumps @git.zone/tstest from ^3.6.1 to ^3.6.3
+- Corrects the README example to show an empty string as the default jwt value
+
+## 2026-03-27 - 2.5.3 - fix(tsconfig)
+add Node.js type definitions to TypeScript compiler options
+
+- Includes the node type library in tsconfig to improve recognition of Node.js globals and APIs during type checking.
+
+## 2026-03-27 - 2.5.2 - fix(build,types)
+migrate smart config filename and tighten TypeScript null handling
+
+- rename npmextra.json to .smartconfig.json and update the published files list
+- update build and test tool dependencies and enable logfile output for tests
+- fix TypeScript compatibility by allowing nullable DOM references, casting keyboard event listeners, and guarding optional scroll durations
+
+## 2026-03-11 - 2.5.1 - fix(breakpoints)
+rename exported functions to reflect constraint-based API: cssForCustom -> cssForConstraint and cssForCustomContainer -> cssForConstraintContainer; update README usage
+
+- Renamed cssForCustom to cssForConstraint
+- Renamed cssForCustomContainer to cssForConstraintContainer
+- Updated README examples to use new names
+- Function behavior and signatures unchanged; only exported names and internal comment updated
+- Consumers must update imports/usages to the new function names (breaking change)
+
+## 2026-03-11 - 2.5.0 - feat(breakpoints)
+document preset viewport helpers, low-level container helpers, and exported types for breakpoints
+
+- Added documentation for preset viewport helpers (they emit both @media and @container wccToolsViewport)
+- Added usage examples and API for low-level helpers: cssForCustom, cssForContainer, cssForCustomContainer, and containerContextStyles
+- Documented exported types: ICssForConstraints and TViewport
+- Clarified that component-level container helpers target named containers and do not emit @media fallbacks
+
+## 2026-03-11 - 2.4.0 - feat(css.breakpoints)
+add constraint-based CSS breakpoint helpers and container context utilities
+
+- Introduce constraint-based API: ICssForConstraints and buildCondition for composing min/max width conditions
+- Add cssForViewport and cssForContainer helpers to centralize @container and @media generation
+- Add curried factories cssForCustom and cssForCustomContainer for reusable custom constraint styles
+- Add containerContextStyles to generate container-name/type host styles used with container queries
+- Refactor existing presets (cssForDesktop, cssForNotebook, cssForTablet, cssForPhablet, cssForPhone) to delegate to the new helpers while preserving behaviour
+- Import css from 'lit' (in addition to CSSResult and unsafeCSS) to support the new containerContextStyles factory
+
 ## 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
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@design.estate/dees-domtools",
-  "version": "2.3.9",
+  "version": "2.5.4",
   "private": false,
   "description": "A package providing tools to simplify complex CSS structures and web development tasks, featuring TypeScript support and integration with various web technologies.",
   "main": "dist_ts/index.js",
@@ -9,34 +9,34 @@
   "author": "Lossless GmbH",
   "license": "MIT",
   "scripts": {
-    "test": "(tstest test/ --verbose)",
+    "test": "(tstest test/ --verbose --logfile)",
-    "build": "(tsbuild --web --allowimplicitany && tsbundle npm)",
+    "build": "(tsbuild --web --allowimplicitany && tsbundle)",
     "format": "(gitzone format)",
     "buildDocs": "tsdoc"
   },
   "devDependencies": {
-    "@git.zone/tsbuild": "^4.1.3",
+    "@git.zone/tsbuild": "^4.4.0",
-    "@git.zone/tsbundle": "^2.9.0",
+    "@git.zone/tsbundle": "^2.10.0",
-    "@git.zone/tstest": "^3.2.0",
+    "@git.zone/tstest": "^3.6.3",
     "@push.rocks/tapbundle": "^6.0.3",
-    "@types/node": "^25.3.3"
+    "@types/node": "^25.5.0"
   },
   "dependencies": {
     "@api.global/typedrequest": "^3.3.0",
     "@design.estate/dees-comms": "^1.0.30",
-    "@push.rocks/lik": "^6.3.1",
+    "@push.rocks/lik": "^6.4.0",
     "@push.rocks/smartdelay": "^3.0.5",
     "@push.rocks/smartjson": "^6.0.0",
     "@push.rocks/smartmarkdown": "^3.0.3",
     "@push.rocks/smartpromise": "^4.2.3",
     "@push.rocks/smartrouter": "^1.3.3",
     "@push.rocks/smartrx": "^3.0.10",
-    "@push.rocks/smartstate": "^2.2.1",
+    "@push.rocks/smartstate": "^2.3.0",
     "@push.rocks/smartstring": "^4.1.0",
     "@push.rocks/smarturl": "^3.1.0",
     "@push.rocks/webrequest": "^4.0.5",
     "@push.rocks/websetup": "^3.0.19",
-    "@push.rocks/webstore": "^2.0.20",
+    "@push.rocks/webstore": "^2.0.21",
     "@tempfix/lenis": "^1.3.20",
     "lit": "^3.3.2",
     "sweet-scroll": "^4.0.0"
@@ -50,7 +50,7 @@
     "dist_ts_web/**/*",
     "assets/**/*",
     "cli.js",
-    "npmextra.json",
+    ".smartconfig.json",
     "readme.md"
   ],
   "browserslist": [

readme.md

@@ -110,7 +110,7 @@ const myStyles = litCss`
 `;
 ```
 
-**Available breakpoint helpers:**
+**Preset viewport helpers** (emit both `@media` and `@container wccToolsViewport`):
 
 - `cssForDesktop(css)` - Styles for 1600px and above
 - `cssForNotebook(css)` - Styles for 1240px and below
@@ -118,6 +118,37 @@ const myStyles = litCss`
 - `cssForPhablet(css)` - Styles for 600px and below
 - `cssForPhone(css)` - Styles for 400px and below
 
+**Low-level helpers** for custom constraints and component-scoped containers:
+
+```typescript
+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:**
+
+- `ICssForConstraints` — `{ maxWidth?: number; minWidth?: number }`
+- `TViewport` — `'native' | 'desktop' | 'tablet' | 'phablet' | 'phone'`
+
 ### Theme Management
 
 Automatic theme detection with system preference support:
@@ -316,7 +347,7 @@ const state = domtools.domToolsStatePart;
 // Get current state
 const currentState = state.getState();
 console.log(currentState.virtualViewport); // 'native'
-console.log(currentState.jwt); // null
+console.log(currentState.jwt); // ''
 
 // Update state
 state.setState({

ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@design.estate/dees-domtools',
-  version: '2.3.9',
+  version: '2.5.4',
   description: 'A package providing tools to simplify complex CSS structures and web development tasks, featuring TypeScript support and integration with various web technologies.'
 }

ts/domtools.classes.domtools.ts

@@ -84,8 +84,8 @@ export class DomTools {
   // ========
   // elements
   public elements: {
-    headElement: HTMLElement;
+    headElement: HTMLElement | null;
-    bodyElement: HTMLElement;
+    bodyElement: HTMLElement | null;
   } = {
     headElement: null,
     bodyElement: null,
@@ -100,7 +100,7 @@ export class DomTools {
   public smartstate = new plugins.smartstate.Smartstate();
   public domToolsStatePart = this.smartstate.getStatePart<IDomToolsState>('domtools', {
     virtualViewport: 'native',
-    jwt: null,
+    jwt: '' as string,
   });
 
   public router = new plugins.smartrouter.SmartRouter({
@@ -117,7 +117,7 @@ export class DomTools {
   public deesComms = new plugins.deesComms.DeesComms();
   public scroller = new Scroller(this);
   public themeManager = new ThemeManager(this);
-  public keyboard: Keyboard = null; // Initialized after DOM ready to avoid accessing document.body before it exists
+  public keyboard: Keyboard | null = null; // Initialized after DOM ready to avoid accessing document.body before it exists
 
   public domToolsReady = plugins.smartpromise.defer();
   public domReady = plugins.smartpromise.defer();
@@ -151,8 +151,8 @@ export class DomTools {
       }
     }
     return await this.runOnceTrackerStringMap.registerUntilTrue(
-      (stringMap) => {
+      (stringMap?: string[]) => {
-        return !stringMap.includes(runningId);
+        return !stringMap?.includes(runningId);
       },
       () => {
         // Check if there was an error and re-throw it
@@ -175,7 +175,7 @@ export class DomTools {
     const styleElement = document.createElement('style');
     styleElement.type = 'text/css';
     styleElement.appendChild(document.createTextNode(stylesText));
-    this.elements.headElement.appendChild(styleElement);
+    this.elements.headElement!.appendChild(styleElement);
   }
 
   /**

ts/domtools.classes.keyboard.ts

@@ -155,13 +155,13 @@ export class Keyboard {
   }
 
   public startListening() {
-    this.domNode.addEventListener('keydown', this.handleKeyDown);
+    this.domNode.addEventListener('keydown', this.handleKeyDown as EventListener);
-    this.domNode.addEventListener('keyup', this.handleKeyUp);
+    this.domNode.addEventListener('keyup', this.handleKeyUp as EventListener);
   }
 
   public stopListening() {
-    this.domNode.removeEventListener('keydown', this.handleKeyDown);
+    this.domNode.removeEventListener('keydown', this.handleKeyDown as EventListener);
-    this.domNode.removeEventListener('keyup', this.handleKeyUp);
+    this.domNode.removeEventListener('keyup', this.handleKeyUp as EventListener);
   }
 
   public clear() {

ts/domtools.classes.scroller.ts

@@ -35,8 +35,10 @@ export class Scroller {
     optionsArg: Parameters<typeof this.sweetScroller.toElement>[1]
   ) {
     this.sweetScroller.toElement(elementArg, optionsArg);
+    if (optionsArg?.duration) {
       await plugins.smartdelay.delayFor(optionsArg.duration);
     }
+  }
 
   /**
    * Detects whether native smooth scrolling is enabled.

ts/domtools.css.breakpoints.ts

@@ -1,6 +1,6 @@
 import { DomTools } from './domtools.classes.domtools.js';
 
-import { CSSResult, unsafeCSS } from 'lit';
+import { css, CSSResult, unsafeCSS } from 'lit';
 
 export const desktop = 1600;
 export const notebook = 1240;
@@ -10,57 +10,90 @@ export const phone = 400;
 
 export type TViewport = 'native' | 'desktop' | 'tablet' | 'phablet' | 'phone';
 
-export const cssForDesktop = (cssArg: CSSResult) => {
+// ---------------------------------------------------------------------------
+// Constraint-based helpers
+// ---------------------------------------------------------------------------
+
+export interface ICssForConstraints {
+  maxWidth?: number;
+  minWidth?: number;
+}
+
+const buildCondition = (constraints: ICssForConstraints): string => {
+  const parts: string[] = [];
+  if (constraints.minWidth) parts.push(`(min-width: ${constraints.minWidth}px)`);
+  if (constraints.maxWidth) parts.push(`(max-width: ${constraints.maxWidth}px)`);
+  return parts.join(' and ');
+};
+
+// ---------------------------------------------------------------------------
+// Viewport-level: @container wccToolsViewport + @media
+// ---------------------------------------------------------------------------
+
+export const cssForViewport = (cssArg: CSSResult, condition: string) => {
   return unsafeCSS(`
-    @container wccToolsViewport (min-width: ${desktop}px) {
+    @container wccToolsViewport ${condition} {
       ${cssArg.cssText}
     }
-    @media (min-width: ${desktop}px) {
+    @media ${condition} {
       ${cssArg.cssText}
     }
   `);
 };
 
+// ---------------------------------------------------------------------------
+// Component-level: @container <name> only
+// ---------------------------------------------------------------------------
+
+export const cssForContainer = (cssArg: CSSResult, condition: string, containerName: string) => {
+  return unsafeCSS(`
+    @container ${containerName} ${condition} {
+      ${cssArg.cssText}
+    }
+  `);
+};
+
+// ---------------------------------------------------------------------------
+// Constraint-based (curried)
+// ---------------------------------------------------------------------------
+
+export const cssForConstraint = (constraints: ICssForConstraints) =>
+  (cssArg: CSSResult) => cssForViewport(cssArg, buildCondition(constraints));
+
+export const cssForConstraintContainer = (constraints: ICssForConstraints, containerName: string) =>
+  (cssArg: CSSResult) => cssForContainer(cssArg, buildCondition(constraints), containerName);
+
+// ---------------------------------------------------------------------------
+// Container context style factory — used by @containerResponsive()
+// ---------------------------------------------------------------------------
+
+export const containerContextStyles = (containerName: string) => css`
+  :host {
+    container-type: inline-size;
+    container-name: ${unsafeCSS(containerName)};
+  }
+`;
+
+// ---------------------------------------------------------------------------
+// Preset viewport breakpoint helpers (existing API, unchanged behaviour)
+// ---------------------------------------------------------------------------
+
+export const cssForDesktop = (cssArg: CSSResult) => {
+  return cssForViewport(cssArg, `(min-width: ${desktop}px)`);
+};
+
 export const cssForNotebook = (cssArg: CSSResult) => {
-  return unsafeCSS(`
+  return cssForViewport(cssArg, `(max-width: ${notebook}px)`);
-    @container wccToolsViewport (max-width: ${notebook}px) {
-      ${cssArg.cssText}
-    }
-    @media (max-width: ${notebook}px) {
-      ${cssArg.cssText}
-    }
-  `);
 };
 
 export const cssForTablet = (cssArg: CSSResult) => {
-  return unsafeCSS(`
+  return cssForViewport(cssArg, `(max-width: ${tablet}px)`);
-    @container wccToolsViewport (max-width: ${tablet}px) {
-      ${cssArg.cssText}
-    }
-    @media (max-width: ${tablet}px) {
-      ${cssArg.cssText}
-    }
-  `);
 };
 
 export const cssForPhablet = (cssArg: CSSResult) => {
-  return unsafeCSS(`
+  return cssForViewport(cssArg, `(max-width: ${phablet}px)`);
-    @container wccToolsViewport (max-width: ${phablet}px) {
-      ${cssArg.cssText}
-    }
-    @media (max-width: ${phablet}px) {
-      ${cssArg.cssText}
-    }
-  `);
 };
 
 export const cssForPhone = (cssArg: CSSResult) => {
-  return unsafeCSS(`
+  return cssForViewport(cssArg, `(max-width: ${phone}px)`);
-    @container wccToolsViewport (max-width: ${phone}px) {
-      ${cssArg.cssText}
-    }
-    @media (max-width: ${phone}px) {
-      ${cssArg.cssText}
-    }
-  `);
 };

tsconfig.json

@@ -4,7 +4,8 @@
     "module": "NodeNext",
     "moduleResolution": "NodeNext",
     "esModuleInterop": true,
-    "verbatimModuleSyntax": true
+    "verbatimModuleSyntax": true,
+    "types": ["node"]
   },
   "exclude": [
     "dist_*/**/*.d.ts"