feat(css.breakpoints): add constraint-based CSS breakpoint helpers and container context utilities

changelog.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 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
 

ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@design.estate/dees-domtools',
-  version: '2.3.9',
+  version: '2.4.0',
   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.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}
+    }
+  `);
+};
+
+// ---------------------------------------------------------------------------
+// Custom constraints (curried)
+// ---------------------------------------------------------------------------
+
+export const cssForCustom = (constraints: ICssForConstraints) =>
+  (cssArg: CSSResult) => cssForViewport(cssArg, buildCondition(constraints));
+
+export const cssForCustomContainer = (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}
-    }
-  `);
 };