v2.5.0

changelog.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 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.0",
   "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",

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.cssForCustom({ 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.cssForCustomContainer({ 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:

ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@design.estate/dees-domtools',
-  version: '2.3.9',
+  version: '2.5.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(`
-    @container wccToolsViewport (max-width: ${notebook}px) {
-      ${cssArg.cssText}
-    }
-    @media (max-width: ${notebook}px) {
-      ${cssArg.cssText}
-    }
-  `);
+  return cssForViewport(cssArg, `(max-width: ${notebook}px)`);
 };
 
 export const cssForTablet = (cssArg: CSSResult) => {
-  return unsafeCSS(`
-    @container wccToolsViewport (max-width: ${tablet}px) {
-      ${cssArg.cssText}
-    }
-    @media (max-width: ${tablet}px) {
-      ${cssArg.cssText}
-    }
-  `);
+  return cssForViewport(cssArg, `(max-width: ${tablet}px)`);
 };
 
 export const cssForPhablet = (cssArg: CSSResult) => {
-  return unsafeCSS(`
-    @container wccToolsViewport (max-width: ${phablet}px) {
-      ${cssArg.cssText}
-    }
-    @media (max-width: ${phablet}px) {
-      ${cssArg.cssText}
-    }
-  `);
+  return cssForViewport(cssArg, `(max-width: ${phablet}px)`);
 };
 
 export const cssForPhone = (cssArg: CSSResult) => {
-  return unsafeCSS(`
-    @container wccToolsViewport (max-width: ${phone}px) {
-      ${cssArg.cssText}
-    }
-    @media (max-width: ${phone}px) {
-      ${cssArg.cssText}
-    }
-  `);
+  return cssForViewport(cssArg, `(max-width: ${phone}px)`);
 };