0.0.1

Author: jonathantneal

.github/workflows/check.yml

@@ -0,0 +1,30 @@
+name: Check
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v1
+        with:
+          bun-version: latest
+
+      - name: Install dependencies
+        run: bun install
+
+      - name: Validate TypeScript types
+        run: bun run check
+
+      - name: Test TypeScript types
+        run: bun run test

.gitignore

@@ -0,0 +1,4 @@
+.DS_Store
+*.lock*
+*.log
+node_modules

.vscode/settings.json

@@ -0,0 +1,32 @@
+{
+	"editor.codeActionsOnSave": {
+		"source.fixAll.biome": "always",
+		"source.organizeImports.biome": "always"
+	},
+	"editor.defaultFormatter": "biomejs.biome",
+	"editor.formatOnPaste": true,
+	"editor.formatOnSave": true,
+	"editor.detectIndentation": false,
+	"editor.insertSpaces": false,
+	"editor.tabSize": 4,
+	"files.exclude": {
+		"node_modules": true,
+		"bun.lock*": true
+	},
+	"css.lint.unknownProperties": "ignore",
+	"html.format.extraLiners": "body",
+	"html.format.indentInnerHtml": true,
+	"html.format.wrapLineLength": 180,
+	"[html]": {
+		"editor.defaultFormatter": "vscode.html-language-features"
+	},
+	"[javascript]": {
+		"editor.defaultFormatter": "biomejs.biome"
+	},
+	"[json]": {
+		"editor.defaultFormatter": "biomejs.biome"
+	},
+	"[typescript]": {
+		"editor.defaultFormatter": "biomejs.biome"
+	}
+}

CustomElement.d.ts

@@ -0,0 +1,29 @@
+/** Base class for a custom element. */
+export declare class CustomElement extends HTMLElement {
+	/** List of attributes to observe for changes, invoking `attributeChangedCallback`. */
+	static observedAttributes?: string[]
+
+	/** Indicates whether the custom element participates in form submission. */
+	static formAssociated?: boolean
+
+	/** Called when one of the element's observed attributes changes. */
+	attributeChangedCallback?(name: string, oldValue: string | null, newValue: string | null): void
+
+	/** Called when the element is added to a document. */
+	connectedCallback?(): void
+
+	/** Called when the element is removed from a document. */
+	disconnectedCallback?(): void
+
+	/** Called when the element is associated or disassociated with a form. */
+	formAssociatedCallback?(form: HTMLFormElement | null): void
+
+	/** Called when the disabled state of the element changes. */
+	formDisabledCallback?(isDisabled: boolean): void
+
+	/** Called when the associated form is reset. */
+	formResetCallback?(): void
+
+	/** Called when the browser automatically fills out the element. */
+	formStateRestoreCallback?(state: string | File | FormData, reason: "autocomplete" | "restore"): void
+}

CustomElement.js

@@ -0,0 +1 @@
+export {}

CustomElementConstructor.d.ts

@@ -0,0 +1,13 @@
+import type { CustomElement } from './CustomElement.d.ts'
+
+/** Constructor interface for custom elements. */
+export interface CustomElementConstructor<T = CustomElement> {
+	/** Creates a new instance of the custom element. */
+	new (...args: any[]): HTMLElement & T
+
+	/** List of attributes to observe for changes, invoking `attributeChangedCallback`. */
+	observedAttributes?: string[]
+
+	/** Indicates whether the custom element participates in form submission. */
+	formAssociated?: boolean
+}

CustomElementConstructor.js

@@ -0,0 +1 @@
+export {}

CustomElementRegistry.d.ts

@@ -0,0 +1,19 @@
+import type { CustomElementConstructor } from "./CustomElementConstructor.d.ts"
+
+/** Provides methods for registering custom elements and querying registered elements. [MDN Reference](https://developer.mozilla.org/docs/Web/API/CustomElementRegistry) */
+export declare class CustomElementRegistry {
+	/** Adds a definition for a custom element to the custom element registry. [MDN Reference](https://developer.mozilla.org/docs/Web/API/CustomElementRegistry/define) */
+	define(name: string, constructor: CustomElementConstructor, options?: ElementDefinitionOptions): void
+
+	/** Returns the constructor for a previously-defined custom element. [MDN Reference](https://developer.mozilla.org/docs/Web/API/CustomElementRegistry/get) */
+	get(name: string): CustomElementConstructor | undefined
+
+	/** Returns the name for a previously-defined custom element. [MDN Reference](https://developer.mozilla.org/docs/Web/API/CustomElementRegistry/getName) */
+	getName(constructor: CustomElementConstructor): string | null
+
+	/** Upgrades all shadow-containing custom elements in the given root. [MDN Reference](https://developer.mozilla.org/docs/Web/API/CustomElementRegistry/upgrade) */
+	upgrade(root: Node): void
+
+	/** Returns a Promise that resolves when the named element is defined. [MDN Reference](https://developer.mozilla.org/docs/Web/API/CustomElementRegistry/whenDefined) */
+	whenDefined(name: string): Promise<CustomElementConstructor>
+}

CustomElementRegistry.js

@@ -0,0 +1 @@
+export {}

README.md

@@ -0,0 +1,82 @@
+# Typed Custom Elements
+
+[![NPM Version][npm-img]][npm-url]
+[![Build Status][cli-img]][cli-url]
+
+**Typed Custom Elements** is a collection of TypeScript types to help you author type-safe Web Components, with proper type checking for custom elements, their constructors, and the custom elements registry.
+
+## Features
+
+- ✅ Typed custom element class definitions
+- ✅ Typed static properties and lifecycle methods
+- ✅ Typed custom element constructors
+- ✅ Type-safe interaction with the Custom Elements Registry
+- ✅ Zero dependencies
+- ✅ ESM compatible
+
+👉 [Try it now in StackBlitz](https://stackblitz.com/github/jsxtools/typed-custom-elements/tree/main/demo)
+
+## Installation
+
+```shell
+npm install typed-custom-elements
+```
+
+## Usage
+
+### Basic Custom Elements
+
+```ts
+import type { CustomElement } from "typed-custom-elements"
+
+class MyElement extends HTMLElement implements CustomElement {
+  // type safety and code completion for static propertes, lifecycle methods, etc.
+  static formAssociated = true
+  static observedAttributes = ["name"]
+
+  attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null) {
+    // type-safe callback handling
+  }
+}
+```
+
+### Custom Element Constructors
+
+```ts
+import type { CustomElementConstructor } from "typed-custom-elements"
+
+const MyElementConstructor: CustomElementConstructor = class extends HTMLElement {
+  // type safety and code completion for static propertes, lifecycle methods, etc.
+}
+```
+
+### Custom Elements Registry
+
+```ts
+import type { CustomElementRegistry } from "typed-custom-elements"
+
+declare const customElements: CustomElementRegistry
+
+// type-safe custom element registration
+customElements.define('my-element', class extends HTMLElement {
+  // type safety, code completion, you get the point
+})
+```
+
+## Why Use Typed Custom Elements?
+
+Working with Web Components in TypeScript often means relying on implicit or loosely typed structures.
+This package brings clarity and confidence to your component authoring by enforcing:
+
+- Proper typing for lifecycle callbacks.
+- Static property inference (`formAssociated`, `observedAttributes`).
+- Safer registration and instantiation via constructors and registries.
+
+## License
+
+This project is licensed under the [MIT No Attribution License](https://opensource.org/license/mit-0).
+
+[npm-img]: https://img.shields.io/npm/v/typed-custom-elements
+[npm-url]: https://www.npmjs.com/package/typed-custom-elements
+[cli-img]: https://github.com/jsxtools/typed-custom-elements/actions/workflows/check.yml/badge.svg
+[cli-url]: https://github.com/jsxtools/typed-custom-elements/actions/workflows/check.yml