56 lines
3.3 KiB
Markdown
56 lines
3.3 KiB
Markdown
# wc-mixin
|
|
|
|
A typed mixin factory that removes custom-element boilerplate.
|
|
|
|
```ts
|
|
import { WebComponent, disable, enable, number, string, type PropChange } from 'wc-mixin';
|
|
|
|
const SPEC = {
|
|
shadow: 'open', // omit for light DOM
|
|
template: '<input class="name"><button>Go</button>',
|
|
css: ':host { display: block; }',
|
|
events: ['click'],
|
|
element: {
|
|
input: 'input.name', // refs.input: HTMLInputElement | null (from the tag)
|
|
thing: '.thing', // refs.thing: Element | null (no tag to go on)
|
|
card: ['.card', HTMLElement], // refs.card: HTMLElement | null (throws if a match isn't one)
|
|
},
|
|
elements: { buttons: 'button' }, // refs.buttons: HTMLButtonElement[]
|
|
props: {
|
|
userId: number(), // user-id number | undefined
|
|
min: number({ default: 1 }), // min number
|
|
ready: enable({ attribute: 'is-ready' }), // is-ready boolean (default false)
|
|
fetch: disable(), // disable-fetch boolean (default true)
|
|
},
|
|
} as const;
|
|
|
|
class ExampleElement extends WebComponent(SPEC) {
|
|
override onConnect() {
|
|
window.addEventListener('resize', () => this.layout(), { signal: this.signal });
|
|
}
|
|
override handleEvent(event: PointerEvent) {}
|
|
override onPropChange(change: PropChange<typeof SPEC>) {
|
|
if (change.name === 'min') change.value; // number
|
|
}
|
|
layout() {}
|
|
}
|
|
|
|
customElements.define('example-element', ExampleElement);
|
|
|
|
ExampleElement.observedAttributes; // readonly ('user-id' | 'min' | 'is-ready' | 'disable-fetch')[]
|
|
```
|
|
|
|
- **Props** are stored as values and reflected to attributes; attribute changes decode back. `onPropChange` fires once per real change from either side.
|
|
- **Attribute names**: an explicit `attribute` is used verbatim; otherwise `kebab(key)`, with `disable-` for `disable()` and `data-` in front when `dataPrefix: true`.
|
|
- **Codecs**: `string`, `number`, `enable`, `disable`, `choice([...])`, `json<T>()`, `prop({ default, decode, encode })`.
|
|
- **Shadow DOM**: `shadow` attaches a root and clones `template` into it; `css` is a shared adopted stylesheet. An existing declarative shadow root is used instead (and `shadow`/`template` are ignored). `root` is the shadow root (even when closed) or the element itself.
|
|
- **Light DOM**: `template` is appended on first connect; `css` is added once per element type, as a `<style>` in `<head>` or adopted into the enclosing shadow root.
|
|
- **Refs**: a selector string is typed from its tag (last compound: `'form > button#go'` → `HTMLButtonElement`), falling back to `Element`. `[selector, Class]` types the ref as `Class`; reading it throws a `TypeError` if a match isn't an instance of `Class`. A key can't be in both `element` and `elements`.
|
|
- **`signal`** aborts on disconnect; a new one is created on each connect. `events` are listened on the host with it.
|
|
- **`base`** extends another autonomous element class; prop names that collide with its members (or `HTMLElement`'s, like `title`/`hidden`) are type errors.
|
|
- Don't declare a subclass field with a prop's name; it would shadow the reflected accessor.
|
|
|
|
## Scripts
|
|
|
|
`npm run lint` (oxlint, type-aware), `npm run format` / `format:check` (oxfmt), `npm run typecheck`, `npm test` (Vitest in headless Chromium + type tests), `npm run build`.
|