thunderous 0.3.3 → 0.4.0

package/dist/index.cjs

@@ -294,6 +294,7 @@ var customElement = (render, options) => {
     #connectedFns = /* @__PURE__ */ new Set();
     #disconnectedFns = /* @__PURE__ */ new Set();
     #adoptedCallbackFns = /* @__PURE__ */ new Set();
+    #formAssociatedCallbackFns = /* @__PURE__ */ new Set();
     #formDisabledCallbackFns = /* @__PURE__ */ new Set();
     #formResetCallbackFns = /* @__PURE__ */ new Set();
     #formStateRestoreCallbackFns = /* @__PURE__ */ new Set();
@@ -325,6 +326,7 @@ var customElement = (render, options) => {
         connectedCallback: (fn) => this.#connectedFns.add(fn),
         disconnectedCallback: (fn) => this.#disconnectedFns.add(fn),
         adoptedCallback: (fn) => this.#adoptedCallbackFns.add(fn),
+        formAssociatedCallback: (fn) => this.#formAssociatedCallbackFns.add(fn),
         formDisabledCallback: (fn) => this.#formDisabledCallbackFns.add(fn),
         formResetCallback: (fn) => this.#formResetCallbackFns.add(fn),
         formStateRestoreCallback: (fn) => this.#formStateRestoreCallbackFns.add(fn),
@@ -348,24 +350,34 @@ var customElement = (render, options) => {
             }
           }
         ),
-        propSignals: new Proxy(
-          {},
-          {
-            get: (_, prop) => {
-              if (!(prop in this.#propSignals)) this.#propSignals[prop] = createSignal(null);
-              const [getter, _setter] = this.#propSignals[prop];
-              const setter = (newValue) => {
-                this[prop] = newValue;
-                _setter(newValue);
-              };
-              return [getter, setter];
-            },
-            set: () => {
-              console.error("Signals must be assigned via setters.");
-              return false;
-            }
+        propSignals: new Proxy({}, {
+          get: (_, prop) => {
+            if (!(prop in this.#propSignals)) this.#propSignals[prop] = createSignal();
+            const [_getter, _setter] = this.#propSignals[prop];
+            const setter = (newValue) => {
+              this[prop] = newValue;
+              _setter(newValue);
+            };
+            const getter = () => {
+              const value = _getter();
+              if (value === void 0)
+                throw new Error(
+                  `
+
+Property: ${prop}
+
+You must set an initial value before calling a property signal's getter.
+`
+                );
+              return value;
+            };
+            return [getter, setter];
+          },
+          set: () => {
+            console.error("Signals must be assigned via setters.");
+            return false;
           }
-        ),
+        }),
         refs: new Proxy(
           {},
           {
@@ -476,6 +488,11 @@ var customElement = (render, options) => {
         fn();
       }
     }
+    formAssociatedCallback() {
+      for (const fn of this.#formAssociatedCallbackFns) {
+        fn();
+      }
+    }
     formDisabledCallback() {
       for (const fn of this.#formDisabledCallbackFns) {
         fn();

package/dist/index.d.cts

@@ -14,8 +14,35 @@ type SignalOptions = {
 type SignalGetter<T> = (options?: SignalOptions) => T;
 type SignalSetter<T> = (newValue: T, options?: SignalOptions) => void;
 type Signal<T = unknown> = [SignalGetter<T>, SignalSetter<T>];
+/**
+ * Create a signal with an initial value.
+ * @example
+ * ```ts
+ * const [getCount, setCount] = createSignal(0);
+ * const increment = () => setCount(getCount() + 1);
+ * const decrement = () => setCount(getCount() - 1);
+ * ```
+ */
 declare const createSignal: <T = undefined>(initVal?: T, options?: SignalOptions) => Signal<T>;
+/**
+ * Create a derived signal that depends on other signals.
+ * @example
+ * ```ts
+ * const [getCount, setCount] = createSignal(0);
+ * const doubleCount = derived(() => getCount() * 2);
+ * ```
+ */
 declare const derived: <T>(fn: () => T) => SignalGetter<T>;
+/**
+ * Create an effect that runs when signals change.
+ * @example
+ * ```ts
+ * const [getCount, setCount] = createSignal(0);
+ * createEffect(() => {
+ *  console.log('Count:', getCount());
+ * });
+ * ```
+ */
 declare const createEffect: (fn: () => void) => void;
 
 declare global {
@@ -29,7 +56,8 @@ type ElementResult = {
     eject: () => CustomElementConstructor;
 };
 type AttributeChangedCallback = (name: string, oldValue: string | null, newValue: string | null) => void;
-type RenderProps = {
+type CustomElementProps = Record<PropertyKey, unknown>;
+type RenderArgs<Props extends CustomElementProps> = {
     elementRef: HTMLElement;
     root: ShadowRoot | HTMLElement;
     internals: ElementInternals;
@@ -40,9 +68,12 @@ type RenderProps = {
     formDisabledCallback: (fn: () => void) => void;
     formResetCallback: (fn: () => void) => void;
     formStateRestoreCallback: (fn: () => void) => void;
+    formAssociatedCallback: (fn: () => void) => void;
     customCallback: (fn: () => void) => `{{callback:${string}}}`;
     attrSignals: Record<string, Signal<string | null>>;
-    propSignals: Record<string, Signal<unknown>>;
+    propSignals: {
+        [K in keyof Props]: Signal<Props[K]>;
+    };
     refs: Record<string, HTMLElement | null>;
     adoptStyleSheet: (stylesheet: Styles) => void;
 };
@@ -54,12 +85,32 @@ type RenderOptions = {
     attachShadow: boolean;
     shadowRootOptions: ShadowRootInit;
 };
-type RenderFunction = (props: RenderProps) => DocumentFragment;
-declare const customElement: (render: RenderFunction, options?: Partial<RenderOptions>) => ElementResult;
+type RenderFunction<Props extends CustomElementProps> = (args: RenderArgs<Props>) => DocumentFragment;
+/**
+ * Create a custom element that can be defined for use in the DOM.
+ * @example
+ * ```ts
+ * const MyElement = customElement(() => {
+ *   return html`<h1>Hello, World!</h1>`;
+ * });
+ * MyElement.define('my-element');
+ * ```
+ */
+declare const customElement: <Props extends CustomElementProps>(render: RenderFunction<Props>, options?: Partial<RenderOptions>) => ElementResult;
 type Registry = {
     register: (tagName: string, element: CustomElementConstructor) => void;
     getTagName: (element: CustomElementConstructor) => string | undefined;
 };
+/**
+ * Create a registry for custom elements.
+ * @example
+ * ```ts
+ * const registry = createRegistry();
+ * registry.register('my-element', MyElement);
+ * const tagName = registry.getTagName(MyElement);
+ * console.log(tagName); // 'MY-ELEMENT'
+ * ```
+ */
 declare const createRegistry: () => Registry;
 
-export { type RenderFunction, type RenderProps, type Signal, type SignalGetter, type SignalSetter, createEffect, createRegistry, createSignal, css, customElement, derived, html };
+export { type RenderArgs, type RenderFunction, type RenderArgs as RenderProps, type Signal, type SignalGetter, type SignalSetter, createEffect, createRegistry, createSignal, css, customElement, derived, html };

package/dist/index.d.ts

@@ -14,8 +14,35 @@ type SignalOptions = {
 type SignalGetter<T> = (options?: SignalOptions) => T;
 type SignalSetter<T> = (newValue: T, options?: SignalOptions) => void;
 type Signal<T = unknown> = [SignalGetter<T>, SignalSetter<T>];
+/**
+ * Create a signal with an initial value.
+ * @example
+ * ```ts
+ * const [getCount, setCount] = createSignal(0);
+ * const increment = () => setCount(getCount() + 1);
+ * const decrement = () => setCount(getCount() - 1);
+ * ```
+ */
 declare const createSignal: <T = undefined>(initVal?: T, options?: SignalOptions) => Signal<T>;
+/**
+ * Create a derived signal that depends on other signals.
+ * @example
+ * ```ts
+ * const [getCount, setCount] = createSignal(0);
+ * const doubleCount = derived(() => getCount() * 2);
+ * ```
+ */
 declare const derived: <T>(fn: () => T) => SignalGetter<T>;
+/**
+ * Create an effect that runs when signals change.
+ * @example
+ * ```ts
+ * const [getCount, setCount] = createSignal(0);
+ * createEffect(() => {
+ *  console.log('Count:', getCount());
+ * });
+ * ```
+ */
 declare const createEffect: (fn: () => void) => void;
 
 declare global {
@@ -29,7 +56,8 @@ type ElementResult = {
     eject: () => CustomElementConstructor;
 };
 type AttributeChangedCallback = (name: string, oldValue: string | null, newValue: string | null) => void;
-type RenderProps = {
+type CustomElementProps = Record<PropertyKey, unknown>;
+type RenderArgs<Props extends CustomElementProps> = {
     elementRef: HTMLElement;
     root: ShadowRoot | HTMLElement;
     internals: ElementInternals;
@@ -40,9 +68,12 @@ type RenderProps = {
     formDisabledCallback: (fn: () => void) => void;
     formResetCallback: (fn: () => void) => void;
     formStateRestoreCallback: (fn: () => void) => void;
+    formAssociatedCallback: (fn: () => void) => void;
     customCallback: (fn: () => void) => `{{callback:${string}}}`;
     attrSignals: Record<string, Signal<string | null>>;
-    propSignals: Record<string, Signal<unknown>>;
+    propSignals: {
+        [K in keyof Props]: Signal<Props[K]>;
+    };
     refs: Record<string, HTMLElement | null>;
     adoptStyleSheet: (stylesheet: Styles) => void;
 };
@@ -54,12 +85,32 @@ type RenderOptions = {
     attachShadow: boolean;
     shadowRootOptions: ShadowRootInit;
 };
-type RenderFunction = (props: RenderProps) => DocumentFragment;
-declare const customElement: (render: RenderFunction, options?: Partial<RenderOptions>) => ElementResult;
+type RenderFunction<Props extends CustomElementProps> = (args: RenderArgs<Props>) => DocumentFragment;
+/**
+ * Create a custom element that can be defined for use in the DOM.
+ * @example
+ * ```ts
+ * const MyElement = customElement(() => {
+ *   return html`<h1>Hello, World!</h1>`;
+ * });
+ * MyElement.define('my-element');
+ * ```
+ */
+declare const customElement: <Props extends CustomElementProps>(render: RenderFunction<Props>, options?: Partial<RenderOptions>) => ElementResult;
 type Registry = {
     register: (tagName: string, element: CustomElementConstructor) => void;
     getTagName: (element: CustomElementConstructor) => string | undefined;
 };
+/**
+ * Create a registry for custom elements.
+ * @example
+ * ```ts
+ * const registry = createRegistry();
+ * registry.register('my-element', MyElement);
+ * const tagName = registry.getTagName(MyElement);
+ * console.log(tagName); // 'MY-ELEMENT'
+ * ```
+ */
 declare const createRegistry: () => Registry;
 
-export { type RenderFunction, type RenderProps, type Signal, type SignalGetter, type SignalSetter, createEffect, createRegistry, createSignal, css, customElement, derived, html };
+export { type RenderArgs, type RenderFunction, type RenderArgs as RenderProps, type Signal, type SignalGetter, type SignalSetter, createEffect, createRegistry, createSignal, css, customElement, derived, html };

package/dist/index.js

@@ -252,6 +252,7 @@ var customElement = (render, options) => {
     #connectedFns = /* @__PURE__ */ new Set();
     #disconnectedFns = /* @__PURE__ */ new Set();
     #adoptedCallbackFns = /* @__PURE__ */ new Set();
+    #formAssociatedCallbackFns = /* @__PURE__ */ new Set();
     #formDisabledCallbackFns = /* @__PURE__ */ new Set();
     #formResetCallbackFns = /* @__PURE__ */ new Set();
     #formStateRestoreCallbackFns = /* @__PURE__ */ new Set();
@@ -283,6 +284,7 @@ var customElement = (render, options) => {
         connectedCallback: (fn) => this.#connectedFns.add(fn),
         disconnectedCallback: (fn) => this.#disconnectedFns.add(fn),
         adoptedCallback: (fn) => this.#adoptedCallbackFns.add(fn),
+        formAssociatedCallback: (fn) => this.#formAssociatedCallbackFns.add(fn),
         formDisabledCallback: (fn) => this.#formDisabledCallbackFns.add(fn),
         formResetCallback: (fn) => this.#formResetCallbackFns.add(fn),
         formStateRestoreCallback: (fn) => this.#formStateRestoreCallbackFns.add(fn),
@@ -306,24 +308,34 @@ var customElement = (render, options) => {
             }
           }
         ),
-        propSignals: new Proxy(
-          {},
-          {
-            get: (_, prop) => {
-              if (!(prop in this.#propSignals)) this.#propSignals[prop] = createSignal(null);
-              const [getter, _setter] = this.#propSignals[prop];
-              const setter = (newValue) => {
-                this[prop] = newValue;
-                _setter(newValue);
-              };
-              return [getter, setter];
-            },
-            set: () => {
-              console.error("Signals must be assigned via setters.");
-              return false;
-            }
+        propSignals: new Proxy({}, {
+          get: (_, prop) => {
+            if (!(prop in this.#propSignals)) this.#propSignals[prop] = createSignal();
+            const [_getter, _setter] = this.#propSignals[prop];
+            const setter = (newValue) => {
+              this[prop] = newValue;
+              _setter(newValue);
+            };
+            const getter = () => {
+              const value = _getter();
+              if (value === void 0)
+                throw new Error(
+                  `
+
+Property: ${prop}
+
+You must set an initial value before calling a property signal's getter.
+`
+                );
+              return value;
+            };
+            return [getter, setter];
+          },
+          set: () => {
+            console.error("Signals must be assigned via setters.");
+            return false;
           }
-        ),
+        }),
         refs: new Proxy(
           {},
           {
@@ -434,6 +446,11 @@ var customElement = (render, options) => {
         fn();
       }
     }
+    formAssociatedCallback() {
+      for (const fn of this.#formAssociatedCallbackFns) {
+        fn();
+      }
+    }
     formDisabledCallback() {
       for (const fn of this.#formDisabledCallbackFns) {
         fn();

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "thunderous",
-	"version": "0.3.3",
+	"version": "0.4.0",
 	"description": "",
 	"type": "module",
 	"main": "./dist/index.cjs",
@@ -30,7 +30,8 @@
 	"homepage": "https://github.com/Thunder-Solutions/Thunderous#readme",
 	"license": "MIT",
 	"scripts": {
-		"demo": "cd demo && rm -rf node_modules && npm i && npm start",
+		"demo": "cd demo && npm start",
+		"www": "cd www && npm run dev",
 		"build": "tsup src/index.ts --format cjs,esm --dts --no-clean"
 	},
 	"devDependencies": {