feat(dees-element): add container-responsive APIs (containerResponsive decorator, DeesElement static cssFor* container helpers, and cssManager cssForCustom) and update docs

changelog.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 2026-03-11 - 2.2.0 - feat(dees-element)
+add container-responsive APIs (containerResponsive decorator, DeesElement static cssFor* container helpers, and cssManager cssForCustom) and update docs
+
+- Exported new containerResponsive decorator (ts/decorators.containerresponsive.ts and exported from ts/index.ts)
+- Added component-level static helpers on DeesElement: cssForDesktop, cssForNotebook, cssForTablet, cssForPhablet, cssForPhone, cssForCustom
+- Added cssManager.cssForCustom to provide curried custom breakpoint helper
+- Updated readme with Container-Responsive Components section and usage examples
+- Bumped dependency @design.estate/dees-domtools from ^2.3.8 to ^2.4.0
+- Non-breaking new functionality — recommend minor version bump
+
 ## 2026-01-27 - 2.1.6 - fix(docs, deps, tests)
 update README with expanded usage docs and examples; bump devDependencies and dees-domtools; fix test import path
 

package.json

@@ -20,7 +20,7 @@
     "@types/node": "^25.0.10"
   },
   "dependencies": {
-    "@design.estate/dees-domtools": "^2.3.8",
+    "@design.estate/dees-domtools": "^2.4.0",
     "@push.rocks/isounique": "^1.0.5",
     "@push.rocks/smartrx": "^3.0.10",
     "lit": "^3.3.2"

pnpm-lock.yaml

@@ -9,8 +9,8 @@ importers:
   .:
     dependencies:
       '@design.estate/dees-domtools':
-        specifier: ^2.3.8
+        specifier: ^2.4.0
-        version: 2.3.8
+        version: 2.4.0
       '@push.rocks/isounique':
         specifier: ^1.0.5
         version: 1.0.5
@@ -45,6 +45,9 @@ packages:
   '@api.global/typedrequest@3.2.5':
     resolution: {integrity: sha512-LM/sUTuYnU5xY4gNZrN6ERMiKr+SpDZuSxJkAZz1YazC7ymGfo6uQ8sCnN8eNNQNFqIOkC+BtfYRayfbGwYLLg==}
 
+  '@api.global/typedrequest@3.3.0':
+    resolution: {integrity: sha512-Jwobqla+9k2IBG0duwrCFtc6GU6wsvHS3f0gJJsxTrpapylBW1YSF7NnGHPGs7F9hbATsO6IoUBpR2ScoKyGJA==}
+
   '@api.global/typedserver@3.0.80':
     resolution: {integrity: sha512-dcp0oXsjBL+XdFg1wUUP08uJQid5bQ0Yv3V3Y3lnI2QCbat0FU+Tsb0TZRnZ4+P150Vj/ITBqJUgDzFsF34grA==}
 
@@ -243,8 +246,8 @@ packages:
   '@design.estate/dees-comms@1.0.30':
     resolution: {integrity: sha512-KchMlklJfKAjQiJiR0xmofXtQ27VgZtBIxcMwPE9d+h3jJRv+lPZxzBQVOM0eyM0uS44S5vJMZ11IeV4uDXSHg==}
 
-  '@design.estate/dees-domtools@2.3.8':
+  '@design.estate/dees-domtools@2.4.0':
-    resolution: {integrity: sha512-jUG9GMvPxKMwmRIZ9oLTL3c8hHvHuiwIk8cTrYnuZzGO/uJJ5/czk9o6LRXUuCOOG7TRLtqgOpK8EEQgaadfZA==}
+    resolution: {integrity: sha512-CbleS20q5R8EXMtN0SMGenckrRtcLmCR+e7aslbcd0XMWwN+SWyuRqCg1p6Fr9spW+cVOCo/bhpvrwSVubTuAA==}
 
   '@design.estate/dees-element@2.1.3':
     resolution: {integrity: sha512-TjXWxVcdSPaT1IOk31ckfxvAZnJLuTxhFGsNCKoh63/UE2FVf6slp8//UFvN+ADigiA9ZsY0azkY99XbJCwDDA==}
@@ -623,6 +626,9 @@ packages:
   '@push.rocks/lik@6.2.2':
     resolution: {integrity: sha512-j64FFPPyMXeeUorjKJVF6PWaJUfiIrF3pc41iJH4lOh0UUpBAHpcNzHVxTR58orwbVA/h3Hz+DQd4b1Rq0dFDQ==}
 
+  '@push.rocks/lik@6.3.1':
+    resolution: {integrity: sha512-UWDwGBaVx5yPtAFXqDDBtQZCzETUOA/7myQIXb+YBsuiIw4yQuhNZ23uY2ChQH2Zn6DLqdNSgQcYC0WywMZBNQ==}
+
   '@push.rocks/mongodump@1.1.0':
     resolution: {integrity: sha512-kW0ZUGyf1e4nwloVwBQjNId+MzgTcNS834C+RxH21i1NqyOubbpWZtJtPP+K+s35nSJRyCTy3ICfBMdDBTAm2w==}
 
@@ -717,6 +723,9 @@ packages:
   '@push.rocks/smartjson@5.2.0':
     resolution: {integrity: sha512-710e8UwovRfPgUtaBHcd6unaODUjV5fjxtGcGCqtaTcmvOV6VpasdVfT66xMDzQmWH2E9ZfHDJeso9HdDQzNQA==}
 
+  '@push.rocks/smartjson@6.0.0':
+    resolution: {integrity: sha512-FYfJnmukt66WePn6xrVZ3BLmRQl9W82LcsICK3VU9sGW7kasig090jKXPm+yX8ibQcZAO/KyR/Q8tMIYZNxGew==}
+
   '@push.rocks/smartlog-destination-devtools@1.0.12':
     resolution: {integrity: sha512-zvsIkrqByc0JRaBgIyhh+PSz2SY/e/bmhZdUcr/OW6pudgAcqe2sso68EzrKux0w9OMl1P9ZnzF3FpCZPFWD/A==}
 
@@ -807,8 +816,8 @@ packages:
   '@push.rocks/smartspawn@3.0.3':
     resolution: {integrity: sha512-DyrGPV69wwOiJgKkyruk5hS3UEGZ99xFAqBE9O2nM8VXCRLbbty3xt1Ug5Z092ZZmJYaaGMSnMw3ijyZJFCT0Q==}
 
-  '@push.rocks/smartstate@2.0.27':
+  '@push.rocks/smartstate@2.2.1':
-    resolution: {integrity: sha512-q4UKir7GV3hakJWXQR4DoA4tUVwT5GRkJ/MtanHYF0wZLHfS19+nGmyO9y974zk3eT9hmy3+Lq5cKtU2W6+Y3w==}
+    resolution: {integrity: sha512-fLrilAJNI6QOs0hcBRD9eTwU2Rlo6NlDCKQo9N/zyp0VJ6AV1UVdEZcVIQILu1CO0RUHX9aBAbFunJrb2+Zrkg==}
 
   '@push.rocks/smartstream@3.2.5':
     resolution: {integrity: sha512-PLGGIFDy8JLNVUnnntMSIYN4W081YSbNC7Y/sWpvUT8PAXtbEXXUiDFgK5o3gcI0ptpKQxHAwxhzNlPj0sbFVg==}
@@ -819,6 +828,9 @@ packages:
   '@push.rocks/smarttime@4.1.1':
     resolution: {integrity: sha512-Ha/3J/G+zfTl4ahpZgF6oUOZnUjpLhrBja0OQ2cloFxF9sKT8I1COaSqIfBGDtoK2Nly4UD4aTJ3JcJNOg/kgA==}
 
+  '@push.rocks/smarttime@4.2.3':
+    resolution: {integrity: sha512-8gMg8RUkrCG4p9NcEUZV7V6KpL24+jAMK02g7qyhfA6giz/JJWD0+8w8xjSR+G7qe16KVQ2y3RbvAL9TxmO36g==}
+
   '@push.rocks/smartunique@3.0.9':
     resolution: {integrity: sha512-q6DYQgT7/dqdWi9HusvtWCjdsFzLFXY9LTtaZV6IYNJt6teZOonoygxTdNt9XLn6niBSbLYrHSKvJNTRH/uK+g==}
 
@@ -846,6 +858,9 @@ packages:
   '@push.rocks/webrequest@4.0.1':
     resolution: {integrity: sha512-I60XZZLVf8W5I7YdmUVVu4G92teE3rg3/aKaV00BRg8vJ3VXx3wc59Qj4em7zxQ5o0HvL8m1Aezw3RFMDPyVgA==}
 
+  '@push.rocks/webrequest@4.0.5':
+    resolution: {integrity: sha512-wVSCaXqJ9Vh+rbwVz0wDl46dYz4rnwwSrm5vbVXKbuH6oKTPF0YRoujeJPqRltIn64RVGdLeY9/6ix+ZCrzhsg==}
+
   '@push.rocks/websetup@3.0.19':
     resolution: {integrity: sha512-iKJDwXdMmQdu5siOIgziPRxM51lN1AU9HOr+yMteu1YMDkZT7HKCyisDAr4gC9WZ9a7FzsG8zgthm4dMeA8NTw==}
 
@@ -1270,8 +1285,8 @@ packages:
   '@tempfix/idb@8.0.3':
     resolution: {integrity: sha512-hPJQKO7+oAIY+pDNImrZ9QAINbz9KmwT+yO4iRVwdPanok2YKpaUxdJzIvCUwY0YgAawlvYdffbLvRLV5hbs2g==}
 
-  '@tempfix/lenis@1.3.17':
+  '@tempfix/lenis@1.3.20':
-    resolution: {integrity: sha512-IqbEB2jLGd0CZrr6TQgjPlhIJJwjDD/53e60KmEr2MEMxwRFUn6pg/H2EvxtoeS7ItmQdhWkJwPgtvVRUCctNw==}
+    resolution: {integrity: sha512-ypeB0FuHLHOCQXW4d0RQ69txPJJH+1CHcpsZIUdcv2t1vR0IVyQr2vHihtde9UOXhjzqEnUphWon/UcJNsa0YA==}
     peerDependencies:
       '@nuxt/kit': '>=3.0.0'
       react: '>=17.0.0'
@@ -1748,6 +1763,10 @@ packages:
       typescript:
         optional: true
 
+  croner@10.0.1:
+    resolution: {integrity: sha512-ixNtAJndqh173VQ4KodSdJEI6nuioBWI0V1ITNKhZZsO0pEMoDxz539T4FTTbSZ/xIOSuDnzxLVRqBVSvPNE2g==}
+    engines: {node: '>=18.0'}
+
   croner@9.1.0:
     resolution: {integrity: sha512-p9nwwR4qyT5W996vBZhdvBCnMhicY5ytZkR4D1Xj0wuTDEiMnjwR57Q3RXYY/s0EpX6Ay3vgIcfaR+ewGHsi+g==}
     engines: {node: '>=18.0'}
@@ -3456,6 +3475,18 @@ snapshots:
       '@push.rocks/webrequest': 3.0.37
       '@push.rocks/webstream': 1.0.10
 
+  '@api.global/typedrequest@3.3.0':
+    dependencies:
+      '@api.global/typedrequest-interfaces': 3.0.19
+      '@push.rocks/isounique': 1.0.5
+      '@push.rocks/lik': 6.3.1
+      '@push.rocks/smartbuffer': 3.0.5
+      '@push.rocks/smartdelay': 3.0.5
+      '@push.rocks/smartguard': 3.1.0
+      '@push.rocks/smartpromise': 4.2.3
+      '@push.rocks/webrequest': 4.0.5
+      '@push.rocks/webstream': 1.0.10
+
   '@api.global/typedserver@3.0.80':
     dependencies:
       '@api.global/typedrequest': 3.2.5
@@ -4032,24 +4063,24 @@ snapshots:
       '@push.rocks/smartdelay': 3.0.5
       broadcast-channel: 7.2.0
 
-  '@design.estate/dees-domtools@2.3.8':
+  '@design.estate/dees-domtools@2.4.0':
     dependencies:
-      '@api.global/typedrequest': 3.2.5
+      '@api.global/typedrequest': 3.3.0
       '@design.estate/dees-comms': 1.0.30
-      '@push.rocks/lik': 6.2.2
+      '@push.rocks/lik': 6.3.1
       '@push.rocks/smartdelay': 3.0.5
-      '@push.rocks/smartjson': 5.2.0
+      '@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.0.27
+      '@push.rocks/smartstate': 2.2.1
       '@push.rocks/smartstring': 4.1.0
       '@push.rocks/smarturl': 3.1.0
-      '@push.rocks/webrequest': 3.0.37
+      '@push.rocks/webrequest': 4.0.5
       '@push.rocks/websetup': 3.0.19
       '@push.rocks/webstore': 2.0.20
-      '@tempfix/lenis': 1.3.17
+      '@tempfix/lenis': 1.3.20
       lit: 3.3.2
       sweet-scroll: 4.0.0
     transitivePeerDependencies:
@@ -4060,7 +4091,7 @@ snapshots:
 
   '@design.estate/dees-element@2.1.3':
     dependencies:
-      '@design.estate/dees-domtools': 2.3.8
+      '@design.estate/dees-domtools': 2.4.0
       '@push.rocks/isounique': 1.0.5
       '@push.rocks/smartrx': 3.0.10
       lit: 3.3.2
@@ -4632,6 +4663,17 @@ snapshots:
       '@types/symbol-tree': 3.2.5
       symbol-tree: 3.2.4
 
+  '@push.rocks/lik@6.3.1':
+    dependencies:
+      '@push.rocks/smartdelay': 3.0.5
+      '@push.rocks/smartmatch': 2.0.0
+      '@push.rocks/smartpromise': 4.2.3
+      '@push.rocks/smartrx': 3.0.10
+      '@push.rocks/smarttime': 4.2.3
+      '@types/minimatch': 5.1.2
+      '@types/symbol-tree': 3.2.5
+      symbol-tree: 3.2.4
+
   '@push.rocks/mongodump@1.1.0(socks@2.8.7)':
     dependencies:
       '@push.rocks/lik': 6.2.2
@@ -4940,6 +4982,13 @@ snapshots:
       fast-json-stable-stringify: 2.1.0
       lodash.clonedeep: 4.5.0
 
+  '@push.rocks/smartjson@6.0.0':
+    dependencies:
+      '@push.rocks/smartenv': 6.0.0
+      '@push.rocks/smartstring': 4.1.0
+      fast-json-stable-stringify: 2.1.0
+      lodash.clonedeep: 4.5.0
+
   '@push.rocks/smartlog-destination-devtools@1.0.12':
     dependencies:
       '@push.rocks/smartlog-interfaces': 3.0.2
@@ -5147,7 +5196,7 @@ snapshots:
 
   '@push.rocks/smartrouter@1.3.3':
     dependencies:
-      '@push.rocks/lik': 6.2.2
+      '@push.rocks/lik': 6.3.1
       '@push.rocks/smartrx': 3.0.10
       path-to-regexp: 8.3.0
 
@@ -5218,11 +5267,10 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
-  '@push.rocks/smartstate@2.0.27':
+  '@push.rocks/smartstate@2.2.1':
     dependencies:
-      '@push.rocks/lik': 6.2.2
       '@push.rocks/smarthash': 3.2.6
-      '@push.rocks/smartjson': 5.2.0
+      '@push.rocks/smartjson': 6.0.0
       '@push.rocks/smartpromise': 4.2.3
       '@push.rocks/smartrx': 3.0.10
       '@push.rocks/webstore': 2.0.20
@@ -5249,6 +5297,17 @@ snapshots:
       is-nan: 1.3.2
       pretty-ms: 9.3.0
 
+  '@push.rocks/smarttime@4.2.3':
+    dependencies:
+      '@push.rocks/lik': 6.3.1
+      '@push.rocks/smartdelay': 3.0.5
+      '@push.rocks/smartpromise': 4.2.3
+      croner: 10.0.1
+      date-fns: 4.1.0
+      dayjs: 1.11.19
+      is-nan: 1.3.2
+      pretty-ms: 9.3.0
+
   '@push.rocks/smartunique@3.0.9':
     dependencies:
       '@types/uuid': 9.0.8
@@ -5307,6 +5366,14 @@ snapshots:
       '@push.rocks/smartpromise': 4.2.3
       '@push.rocks/webstore': 2.0.20
 
+  '@push.rocks/webrequest@4.0.5':
+    dependencies:
+      '@push.rocks/smartdelay': 3.0.5
+      '@push.rocks/smartenv': 6.0.0
+      '@push.rocks/smartjson': 6.0.0
+      '@push.rocks/smartpromise': 4.2.3
+      '@push.rocks/webstore': 2.0.20
+
   '@push.rocks/websetup@3.0.19':
     dependencies:
       '@pushrocks/smartdelay': 3.0.1
@@ -5819,7 +5886,7 @@ snapshots:
 
   '@tempfix/idb@8.0.3': {}
 
-  '@tempfix/lenis@1.3.17': {}
+  '@tempfix/lenis@1.3.20': {}
 
   '@tokenizer/inflate@0.4.1':
     dependencies:
@@ -6298,6 +6365,8 @@ snapshots:
     optionalDependencies:
       typescript: 5.9.3
 
+  croner@10.0.1: {}
+
   croner@9.1.0: {}
 
   cross-spawn@7.0.6:

readme.md

@@ -77,6 +77,7 @@ The singleton `cssManager` is the central hub for theming and responsive layout:
 | `cssManager.cssForTablet(css)` | Media-query wrapper for tablet breakpoints |
 | `cssManager.cssForPhablet(css)` | Media-query wrapper for phablet breakpoints |
 | `cssManager.cssForPhone(css)` | Media-query wrapper for phone breakpoints |
+| `cssManager.cssForCustom({ maxWidth, minWidth })` | Custom viewport-level breakpoint (curried) |
 | `cssManager.cssGridColumns(cols, gap)` | Generates CSS grid column widths |
 
 Example — responsive + themed styles:
@@ -106,6 +107,57 @@ class MyCard extends DeesElement {
 }
 ```
 
+### 📦 Container-Responsive Components
+
+For components that need to respond to their **own width** (not the viewport), use the `@containerResponsive()` decorator together with `DeesElement`'s static `cssFor*` methods:
+
+```typescript
+import {
+  DeesElement, customElement, html, css, cssManager,
+  containerResponsive,
+} from '@design.estate/dees-element';
+
+@containerResponsive()
+@customElement('my-stats-grid')
+class MyStatsGrid extends DeesElement {
+  static styles = [
+    cssManager.defaultStyles,
+    css`.grid { display: grid; grid-template-columns: repeat(3, 1fr); gap: 16px; }`,
+
+    // Component-level: when THIS element is narrow
+    this.cssForTablet(css`
+      .grid { grid-template-columns: repeat(2, 1fr); }
+    `),
+
+    // Viewport-level: when the browser window is narrow
+    cssManager.cssForPhone(css`
+      .grid { grid-template-columns: 1fr; }
+    `),
+
+    // Component-level with custom constraint
+    this.cssForCustom({ maxWidth: 500 })(css`
+      .grid { gap: 8px; }
+    `),
+  ];
+
+  render() {
+    return html`<div class="grid"><slot></slot></div>`;
+  }
+}
+```
+
+**How it works:**
+
+| API | Scope | Generated CSS |
+|-----|-------|---------------|
+| `cssManager.cssForPhablet(css)` | Viewport | `@media` + `@container wccToolsViewport` |
+| `cssManager.cssForCustom({maxWidth:800})(css)` | Viewport | `@media` + `@container wccToolsViewport` |
+| `this.cssForPhablet(css)` | Component | `@container <tag-name>` only |
+| `this.cssForCustom({maxWidth:800})(css)` | Component | `@container <tag-name>` only |
+| `@containerResponsive()` | Decorator | Sets `container-type: inline-size` + `container-name` on `:host` |
+
+The `@containerResponsive()` decorator is required for the component-level `this.cssFor*` methods to take effect — it establishes the CSS containment context on `:host`.
+
 ### ⚡ Reactive Properties & State
 
 Use the standard Lit decorators, re-exported for convenience:
@@ -255,6 +307,7 @@ The directives namespace also re-exports these commonly used Lit directives:
 | `unsafeHTML` | Render raw HTML in templates |
 | `render` | Lit render function |
 | `static` / `unsafeStatic` | Static html template helpers |
+| `containerResponsive` | Decorator that adds CSS containment to `:host` |
 | `domtools` | DOM tooling utilities |
 | `directives` | All directives (resolve, subscribe, etc.) |
 | `rxjs` (type) | RxJS type re-export |

ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@design.estate/dees-element',
-  version: '2.1.6',
+  version: '2.2.0',
   description: 'A library for creating custom elements extending the lit element class with additional functionalities.'
 }

ts/classes.cssmanager.ts

@@ -67,6 +67,11 @@ export class CssManager {
     return unsafeCSS(domtools.breakpoints.cssForPhone(contentArg));
   }
 
+  public cssForCustom(constraints: { maxWidth?: number; minWidth?: number }) {
+    return (contentArg: CSSResult) =>
+      unsafeCSS(domtools.breakpoints.cssForCustom(constraints)(contentArg));
+  }
+
   public bdTheme(brightValueArg: string, darkValueArg: string): CSSResult {
     let returnCssVar: string;
 

ts/classes.dees-element.ts

@@ -1,6 +1,48 @@
 import * as plugins from './plugins.js';
+import { type CSSResult } from 'lit';
 
 export class DeesElement extends plugins.lit.LitElement {
+  // STATIC — component-level responsive helpers (use in `static styles = [...]`)
+
+  private static getContainerName(): string {
+    return (this as any).is || this.name.replace(/([a-z])([A-Z])/g, '$1-$2').toLowerCase();
+  }
+
+  static cssForDesktop(cssArg: CSSResult) {
+    return plugins.domtools.breakpoints.cssForContainer(
+      cssArg, `(min-width: ${plugins.domtools.breakpoints.desktop}px)`, this.getContainerName(),
+    );
+  }
+
+  static cssForNotebook(cssArg: CSSResult) {
+    return plugins.domtools.breakpoints.cssForContainer(
+      cssArg, `(max-width: ${plugins.domtools.breakpoints.notebook}px)`, this.getContainerName(),
+    );
+  }
+
+  static cssForTablet(cssArg: CSSResult) {
+    return plugins.domtools.breakpoints.cssForContainer(
+      cssArg, `(max-width: ${plugins.domtools.breakpoints.tablet}px)`, this.getContainerName(),
+    );
+  }
+
+  static cssForPhablet(cssArg: CSSResult) {
+    return plugins.domtools.breakpoints.cssForContainer(
+      cssArg, `(max-width: ${plugins.domtools.breakpoints.phablet}px)`, this.getContainerName(),
+    );
+  }
+
+  static cssForPhone(cssArg: CSSResult) {
+    return plugins.domtools.breakpoints.cssForContainer(
+      cssArg, `(max-width: ${plugins.domtools.breakpoints.phone}px)`, this.getContainerName(),
+    );
+  }
+
+  static cssForCustom(constraints: { maxWidth?: number; minWidth?: number }) {
+    return (cssArg: CSSResult) =>
+      plugins.domtools.breakpoints.cssForCustomContainer(constraints, this.getContainerName())(cssArg);
+  }
+
   // INSTANCE
   @plugins.lit.property({ type: Boolean })
   public accessor goBright: boolean = false;

ts/decorators.containerresponsive.ts

@@ -0,0 +1,19 @@
+import * as domtools from '@design.estate/dees-domtools';
+
+export function containerResponsive() {
+  return function (target: any) {
+    const tagName: string =
+      target.is || target.name.replace(/([a-z])([A-Z])/g, '$1-$2').toLowerCase();
+    const containerStyles = domtools.breakpoints.containerContextStyles(tagName);
+
+    const original = target.styles;
+    if (Array.isArray(original)) {
+      target.styles = [...original, containerStyles];
+    } else if (original) {
+      target.styles = [original, containerStyles];
+    } else {
+      target.styles = [containerStyles];
+    }
+    return target;
+  };
+}

ts/index.ts

@@ -18,6 +18,9 @@ export { domtools };
 // DeesElements exports
 export * from './classes.dees-element.js';
 
+// decorator exports
+export { containerResponsive } from './decorators.containerresponsive.js';
+
 // directives exports
 import * as directives from './directives/index.js';