Merge branch 'release/3.3.0'

Author: titouanmathis

CHANGELOG.md

@@ -4,6 +4,20 @@ All notable changes to this project will be documented in this file. The format
 
 ## [Unreleased]
 
+## [v3.3.0](https://github.com/studiometa/js-toolkit/compare/3.2.0..3.3.0) (2025-10-29)
+
+### Added
+
+- **withGroup:** add support for namespaces ([#681](https://github.com/studiometa/js-toolkit/pull/681), [3e50e1f9](https://github.com/studiometa/js-toolkit/commit/3e50e1f9))
+
+### Changed
+
+- **withGroup:** improve types ([#681](https://github.com/studiometa/js-toolkit/pull/681), [fa723cfd](https://github.com/studiometa/js-toolkit/commit/fa723cfd))
+
+### Fixed
+
+- **withGroup:** do not include instances disconnected from the DOM in groups ([#680](https://github.com/studiometa/js-toolkit/issues/680), [#681](https://github.com/studiometa/js-toolkit/pull/681), [e214ba38](https://github.com/studiometa/js-toolkit/commit/e214ba38))
+
 ## [v3.2.0](https://github.com/studiometa/js-toolkit/compare/3.1.1..3.2.0) (2025-10-21)
 
 ### Added

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@studiometa/js-toolkit-workspace",
-  "version": "3.2.0",
+  "version": "3.3.0",
   "private": true,
   "type": "module",
   "workspaces": [
@@ -29,12 +29,12 @@
     "build:types": "tsc --build tsconfig.build.json",
     "build:pkg": "node scripts/build.js",
     "build-for-export-size": "node scripts/add-utils-export.js && rm -rf dist && npm run build:pkg && npm run build:cp-files",
-    "postversion": "npm version -ws $npm_package_version"
+    "postversion": "npm version --workspaces $npm_package_version"
   },
   "devDependencies": {
     "@studiometa/prettier-config": "4.4.0",
-    "@types/node": "22.18.11",
-    "oxlint": "1.23.0",
+    "@types/node": "22.18.12",
+    "oxlint": "1.24.0",
     "prettier": "3.6.2",
     "typescript": "5.9.3"
   },

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@studiometa/js-toolkit-demo",
-  "version": "3.2.0",
+  "version": "3.3.0",
   "private": true,
   "type": "module",
   "scripts": {

packages/demo/package.json

@@ -33,6 +33,7 @@ class Bar extends withGroup(Base) {
 ### Parameters
 
 - `BaseClass` (`Base`): The class to add grouping capabilities to
+- `namespace` (`string?`): An optional namespace to avoid conflicts between different group decorators, defaults to an empty string
 
 ### Return value
 
@@ -94,7 +95,63 @@ export default createApp(App);
 <input data-component="SyncedInput" data-option-group="input" type="text" />
 <input data-component="SyncedInput" data-option-group="input" type="text" />
 
-<input data-component="SyncedInput" data-option-group="other-group" type="text" />
+<input
+  data-component="SyncedInput"
+  data-option-group="other-group"
+  type="text" />
+```
+
+:::
+
+::: tip 💡 Two-way binding with [`DataModel`](https://ui.studiometa.dev/-/components/DataModel/)
+
+You should use the [`DataModel` component](https://ui.studiometa.dev/-/components/DataModel/) from the [@studometa/ui package](https://ui.studiometa.dev) along its accompanying [`DataBind`](https://ui.studiometa.dev/-/components/DataBind/), [`DataComputed`](https://ui.studiometa.dev/-/components/DataComputed/) and [`DataEffect`](https://ui.studiometa.dev/-/components/DataEffect/) components if you need to add some reactivity to your existing DOM.
+
+:::
+
+### Using a namespace to avoid group collision
+
+When using multiple groups in the same DOM tree, it can be useful to namespace them to avoid collisions.
+
+In the following example, both `Tabs` and `Accordion` components use a group decorator, but they are namespaced to avoid interference if they share the same `data-option-group` attribute value.
+
+::: code-group
+
+```js {3,9,15-18} twoslash [Tabs.js]
+import { Base, withGroup } from '@studiometa/js-toolkit';
+
+export class Tabs extends withGroup(Base, 'tabs') {
+  static config = {
+    name: 'Tabs',
+  };
+
+  mounted() {
+    console.log('Tabs group:', this.$group);
+  }
+}
+```
+
+```js {3,9,15-18} twoslash [Accordion.js]
+import { Base, withGroup } from '@studiometa/js-toolkit';
+
+export class Accordion extends withGroup(Base, 'accordion') {
+  static config = {
+    name: 'Accordion',
+  };
+
+  mounted() {
+    console.log('Accordion group:', this.$group);
+  }
+}
+```
+
+```js twoslash [app.js]
+import { registerComponent } from '@studiometa/js-toolkit';
+import { Tabs } from './Tabs.js';
+import { Accordion } from './Accordion.js';
+
+registerComponent(Tabs);
+registerComponent(Accordion);
 ```
 
 :::

packages/docs/api/decorators/withGroup.md

@@ -1,6 +1,6 @@
 {
   "name": "@studiometa/js-toolkit-docs",
-  "version": "3.2.0",
+  "version": "3.3.0",
   "type": "module",
   "private": true,
   "scripts": {
@@ -9,10 +9,10 @@
     "preview": "vitepress preview ."
   },
   "devDependencies": {
-    "@shikijs/vitepress-twoslash": "3.13.0",
+    "@shikijs/vitepress-twoslash": "3.14.0",
     "@studiometa/tailwind-config": "2.1.0",
     "tailwindcss": "3.4.18",
     "vitepress": "2.0.0-alpha.12",
-    "vitepress-plugin-llms": "1.8.0"
+    "vitepress-plugin-llms": "1.8.1"
   }
 }

packages/docs/package.json

@@ -14,8 +14,8 @@ export interface WithGroupInterface extends BaseInterface {
 /**
  * Get global groups map.
  */
-function groups(): Map<string, Set<Base>> {
-  return (globalThis.__JS_TOOLKIT_GROUPS__ ??= new Map<string, Set<Base>>());
+function groups<T extends Base = Base>(): Map<string, Set<T>> {
+  return (globalThis.__JS_TOOLKIT_GROUPS__ ??= new Map<string, Set<T>>());
 }
 
 /**
@@ -25,6 +25,7 @@ function groups(): Map<string, Set<Base>> {
  */
 export function withGroup<S extends Base = Base>(
   BaseClass: typeof Base,
+  namespace = '',
 ): BaseDecorator<WithGroupInterface, S, WithGroupProps> {
   // @ts-expect-error Decorators can not be typed.
   return class WithGroup<T extends BaseProps = BaseProps> extends BaseClass<T & WithGroupProps> {
@@ -39,8 +40,16 @@ export function withGroup<S extends Base = Base>(
      * Get the group set.
      */
     get $group() {
-      const { group } = this.$options;
-      return groups().get(group) ?? groups().set(group, new Set()).get(group);
+      const group = `${namespace}${this.$options.group}`;
+      const instances = groups<this>().get(group) ?? groups<this>().set(group, new Set()).get(group);
+
+      for (const instance of instances) {
+        if (!instance.$el.isConnected) {
+          instances.delete(instance);
+        }
+      }
+
+      return instances;
     }
 
     constructor(element: HTMLElement) {

packages/js-toolkit/decorators/withGroup.ts

@@ -1,6 +1,6 @@
 {
   "name": "@studiometa/js-toolkit",
-  "version": "3.2.0",
+  "version": "3.3.0",
   "description": "A set of useful little bits of JavaScript to boost your project! 🚀",
   "publishConfig": {
     "access": "public"

packages/js-toolkit/package.json

@@ -16,12 +16,31 @@ describe('The `withGroup` decorator', () => {
       };
     }
 
-    const foo = new Foo(h('div',));
-    const bar = new Bar(h('div',));
+    const foo = new Foo(h('div', { data: { optionGroup: 'group' } }));
+    const bar = new Bar(h('div', { data: { optionGroup: 'group' } }));
     await mount(foo, bar);
     expect(foo.$group).toBe(bar.$group);
   });
 
+  it('should group mounted components with namespace', async () => {
+    class Foo extends withGroup(Base, 'ns:') {
+      static config: BaseConfig = {
+        name: 'Foo',
+      };
+    }
+
+    class Bar extends withGroup(Base) {
+      static config: BaseConfig = {
+        name: 'Bar',
+      };
+    }
+
+    const foo = new Foo(h('div', { data: { optionGroup: 'group' } }));
+    const bar = new Bar(h('div', { data: { optionGroup: 'group' } }));
+    await mount(foo, bar);
+    expect(foo.$group).not.toContain(bar);
+  });
+
   it('should not include destroyed components', async () => {
     class Foo extends withGroup(Base) {
       static config: BaseConfig = {
@@ -42,4 +61,43 @@ describe('The `withGroup` decorator', () => {
     await destroy(foo);
     expect(foo.$group.has(foo)).toBe(false);
   });
+
+  it('should forget grouped instances not in the DOM anymore', async () => {
+    class Foo extends withGroup(Base) {
+      static config: BaseConfig = {
+        name: 'Foo',
+      };
+    }
+
+    const fragment = new Document();
+    const divA = h('div', {
+      data: { optionGroup: 'group' },
+    });
+    const divB = h('div', {
+      data: { optionGroup: 'group' },
+    });
+
+    fragment.append(divA, divB);
+
+    const instanceA = new Foo(divA);
+    const instanceB = new Foo(divB);
+
+    await mount(instanceA, instanceB);
+
+    expect(divA.isConnected).toBe(true);
+    expect(divB.isConnected).toBe(true);
+    expect(instanceA.$group).toContain(instanceA);
+    expect(instanceA.$group).toContain(instanceB);
+
+    divB.replaceWith(
+      h('div', {
+        data: { optionGroup: 'group' },
+      }),
+    );
+
+    expect(divA.isConnected).toBe(true);
+    expect(divB.isConnected).toBe(false);
+    expect(instanceA.$group).toContain(instanceA);
+    expect(instanceA.$group).not.toContain(instanceB);
+  });
 });

packages/tests/decorators/withGroup.spec.ts

@@ -1,6 +1,6 @@
 {
   "name": "@studiometa/js-toolkit-tests",
-  "version": "3.2.0",
+  "version": "3.3.0",
   "private": true,
   "type": "module",
   "scripts": {