Move Element to use class mixins

README.md

@@ -7,11 +7,12 @@ for creating reactive web components that behave just like native HTML elements.
 
 </header>
 
-Elements can extend `NudeElement` to get the nicest, most declarative syntax,
-or import individual mixins as helper functions and use them with any `HTMLElement` subclass.
+Elements can extend `Element` to get the nicest, most declarative syntax,
+or import individual mixins and use them with any `HTMLElement` subclass.
 
-**Note:** This is a work in progress, developed in the open.
-Try it and please report issues and provide feedback!
+> [!NOTE]
+> This is a work in progress, developed in the open.
+> Try it and please report issues and provide feedback!
 
 ## Features
 
@@ -24,18 +25,20 @@ Try it and please report issues and provide feedback!
 
 ## Usage
 
-### No hassle, less control: the `NudeElement` class
+### No hassle, less control: the `Element` class
 
-Defining your element as a subclass of `NudeElement` gives you the nicest, most declarative syntax.
+Defining your element as a subclass of `Element` gives you the nicest, most declarative syntax.
+This includes all commonly used mixins automatically, though they are only activated when their relevant properties are used in your element subclass.
 
 ```js
-import NudeElement from "nude-element";
+import Element from "nude-element";
 
-class MySlider extends NudeElement {
+class MySlider extends Element {
 	constructor () {
 		// ...
 	}
 
+	// Automatically activates the props mixin
 	static props = {
 		min: {
 			type: Number,
@@ -67,6 +70,7 @@ class MySlider extends NudeElement {
 		},
 	};
 
+	// Automatically activates the events mixin
 	static events = {
 		// Propagate event from shadow DOM element
 		change: {
@@ -81,6 +85,7 @@ class MySlider extends NudeElement {
 		},
 	};
 
+	// Automatically activates the formAssociated mixin
 	static formAssociated = {
 		like: el => el._el.slider,
 		role: "slider",
@@ -90,126 +95,81 @@ class MySlider extends NudeElement {
 }
 ```
 
-### More hassle, more control: Composable mixins
+### A little hassle, a little more control: The `NudeElement` class
 
-If Nude Element taking over your parent class seems too intrusive,
-you can implement the same API via one-off composable helper functions aka mixins,
-at the cost of handling some of the plumbing yourself.
+`Element` inherits from `NudeElement`, which is nearly identical with one exception:
+Instead of including all commonly used mixins automatically,
+it includes no mixins at all.
+To add mixins, you extend it and add a `mixins` static property.
 
-Each mixin modifies the base class in a certain way (e.g. adds properties & methods) and returns an init function,
-to be called once for each element,
-either at the end of its constructor or when it’s first connected.
-This is what the example above would look like:
+This can be useful when you’re trying to keep bundle size to a minimum, since even if mixins are only activated when your subclass uses them,
+they will won't be tree-shaken away, since bundlers don’t understand how this works.
 
 ```js
-import {
-	defineProps,
-	defineEvents,
-	defineFormAssociated,
-} from "nude-element";
+import { NudeElement, Props, Events, FormAssociated } from "nude-element";
 
-class MySlider extends HTMLElement {
-	constructor () {
-		// ...
+class MySlider extends NudeElement {
+	static mixins = [Props, Events, FormAssociated];
 
-		eventHooks.init.call(this);
-		formAssociatedHooks.init.call(this);
-		propHooks.init.call(this);
-	}
+	// ...
 }
+```
 
-let propHooks = defineProps(MySlider, {
-	min: {
-		type: Number,
-		default: 0,
-	},
-	max: {
-		type: Number,
-		default: 1,
-	},
-	step: {
-		type: Number,
-		default () {
-			return Math.abs((this.max - this.min) / 100);
-		},
-	},
-	defaultValue: {
-		type: Number,
-		default () {
-			return (this.min + this.max) / 2;
-		},
-		reflect: {
-			from: "value",
-		},
-	},
-	value: {
-		type: Number,
-		defaultProp: "defaultValue",
-		reflect: false,
-	},
-});
-
-let eventHooks = defineEvents(MySlider, {
-	// Propagate event from shadow DOM element
-	change: {
-		from () {
-			return this._el.slider;
-		}
-	},
-
-	// Fire event when specific prop changes (even programmatically)
-	valuechange: {
-		propchange: "value",
-	},
-});
-
-let formAssociatedHooks = defineFormAssociated(MySlider, {
-	like: el => el._el.slider,
-	role: "slider",
-	valueProp: "value",
-	changeEvent: "valuechange",
-});
+### With custom base class: Subclass factories
+
+If you need to use a custom base class (e.g. `LitElement`), rather than `HTMLElement`, all Nude mixins are also available as subclass factories,
+include `Element` and `NudeElement`:
+
+```js
+import { ElementMixin } from "nude-element";
+import { LitElement } from "lit";
+
+class MySlider extends ElementMixin(LitElement) {
+	// ...
+}
 ```
 
-Each mixin will also look for a static `hooks` property on the element class and add its lifecycle hooks to it if it exists,
-so you can make things a little easier by defining such a property:
+Individual mixins are also available as subclass factories:
 
 ```js
-import { defineProps } from "nude-element";
-import Hooks from "nude-element/hooks";
+import { Props, Events, FormAssociated } from "nude-element/mixins";
+import { LitElement } from "lit";
 
-class MyElement extends HTMLElement {
-	// Caution: if MyElement has subclasses, this will be shared among them!
-	static hooks = new Hooks();
+class MySlider extends Props(Events(FormAssociated(LitElement))) {
+	// ...
+}
+```
+
+### More hassle, more control: Composable mixins
+
+If Nude Element taking over your parent class seems too intrusive,
+you can pull in mixins and apply them to any base class you want in-place without affecting the inheritance chain,
+at the cost of handling some of the plumbing yourself.
+
+There are three parts:
+1. Apply `applyMixins` to your class to apply the mixins to it
+2. Make sure to call `this.init()` in your constructor, since `applyMixins` cannot modify your constructor, so that’s the only way to run initialization logic
+
+```js
+import { Props, Events, FormAssociated, applyMixins } from "nude-element";
 
+class MySlider extends HTMLElement {
 	constructor () {
 		super();
 
-		// Then you can call the hooks at the appropriate times:
-		this.constructor.hooks.run("init", this);
+		// Your own init logic here...
+
+		this.init?.();
 	}
-}
 
-defineProps(MyElement, {
-	// Props…
-});
+	static {
+		applyMixins(this, [Props, Events, FormAssociated]);
+	}
+}
 ```
 
-Read more:
+Individual mixin docs:
 - [Using Props](src/props/)
 - [Events](src/events/)
-- [Form-associated elements](src/formAssociated/)
-- [Mixins](src/mixins/)
-
-
-## Known Hooks
-
-These hooks are automatically managed when you use the `NudeElement` class.
-If you choose to import mixins directly, you need to manage when to call them yourself.
+- [Slots](src/slots/)
 
-- `prepare`: Runs once per class, as soon as a mixin is added
-- `setup`: Runs once per class, before any element is fully constructed
-- `start`: Runs on element constructor
-- `constructed`: Runs after element constructor (async)
-- `init`: Runs when element is connected for the first time
-- `disconnected`: Runs when element is disconnected

mixins-and-hooks.md

@@ -0,0 +1,13 @@
+| Mixin | Hooks uses | Needs `super`? | Imports mixins |
+|-------|-------------|-----------------|-----------------|
+| mounted | 1) First `connectedCallback` for class; 2) First `connectedCallback` |  |  |
+| shadowStyles | 1) First `connectedCallback` for class; 2) First `connectedCallback` | ✅ (for now, fakes it with `getSupers()`) | `mounted` |
+| globalStyles | 1) First `connectedCallback` for class; 2) First `connectedCallback` | ✅ (for now, fakes it with `getSupers()`) | `mounted` |
+| formAssociated | First `connectedCallback` |  | `mounted` |
+| defineProps | First `connectedCallback` |  |  |
+| defineEvents | 1) First `constructor` (once per class); 2) First `connectedCallback` |  | `defineProps` |
+| defineSlots | First `connectedCallback` |  |  |
+| `has-slotted` | First `connectedCallback` |  |  |
+| named-manual | First `connectedCallback` |  | |
+| slots | 1) First `constructor` (once per class); 2) First `connectedCallback` |  | |
+| states | First `connectedCallback` |  | `mounted` |