feat(Lit): Add utility to query connected instances of a component

Author: arshia11d

package-lock.json

@@ -1,6 +1,6 @@
 {
 	"name": "@a11d/lit",
-	"version": "0.5.9",
+	"version": "0.6.0",
 	"description": "A thin wrapper around the Lit library",
 	"repository": {
 		"type": "git",

packages/Lit/package.json

@@ -1,3 +1,4 @@
 export * from './query.js'
 export * from './queryAll.js'
-export * from './queryAllAsNodeList.js'
+export * from './queryAllAsNodeList.js'
+export * from './queryConnectedInstances.js'

packages/Lit/query/index.ts

@@ -0,0 +1,28 @@
+import { Component } from '@a11d/lit'
+import { queryConnectedInstances } from './queryConnectedInstances.js'
+
+class QueryConnectedInstancesTestComponent extends Component {
+	@queryConnectedInstances() static readonly connectedInstances: Set<QueryConnectedInstancesTestComponent>
+}
+
+customElements.define('test-query-connected-instances-test-component', QueryConnectedInstancesTestComponent)
+
+describe('queryConnectedInstances', () => {
+	it('should create a getter that returns the same instance of a Set ', () => {
+		expect(QueryConnectedInstancesTestComponent.connectedInstances).toBeInstanceOf(Set)
+		expect(QueryConnectedInstancesTestComponent.connectedInstances).toBe(QueryConnectedInstancesTestComponent.connectedInstances)
+	})
+
+	it('should add the instance to the Set when connected', () => {
+		const instance = new QueryConnectedInstancesTestComponent()
+		expect(QueryConnectedInstancesTestComponent.connectedInstances).not.toContain(instance)
+		document.body.append(instance)
+		expect(QueryConnectedInstancesTestComponent.connectedInstances).toContain(instance)
+		instance.remove()
+		expect(QueryConnectedInstancesTestComponent.connectedInstances).not.toContain(instance)
+		document.body.append(instance)
+		expect(QueryConnectedInstancesTestComponent.connectedInstances).toContain(instance)
+		instance.remove()
+		expect(QueryConnectedInstancesTestComponent.connectedInstances).not.toContain(instance)
+	})
+})

packages/Lit/query/queryConnectedInstances.test.ts

@@ -0,0 +1,34 @@
+import { LitElement } from 'lit'
+
+const propertyName = Symbol('ConnectedInstances')
+
+/**
+ * Decorator that adds a property of type "Set" to a component class
+ * which contains all connected instances of that component.
+ *
+ * @ssr true
+ *
+ * @example
+ * ```
+ * export class Foo extends Component {
+ *     //` @queryConnectedInstances() static readonly instances!: Set<Foo>
+ * }
+ * ```
+ */
+export function queryConnectedInstances() {
+	return (elementConstructor: typeof LitElement, propertyKey: string) => {
+		Object.defineProperty(elementConstructor, propertyName, { value: new Set<LitElement>() })
+
+		elementConstructor.addInitializer(element => element.addController({
+			hostConnected: () => (element.constructor as any)[propertyName].add(element),
+			hostDisconnected: () => (element.constructor as any)[propertyName].delete(element)
+		}))
+
+		Object.defineProperty(elementConstructor, propertyKey, {
+			configurable: false,
+			get(this: typeof LitElement) {
+				return (this as any)[propertyName]
+			},
+		})
+	}
+}