@seahax/elemental 0.4.2 → 0.5.1

package/README.md

@@ -23,16 +23,19 @@ Contains everything you need to build anything from a single component up to a f
 ```ts
 import {
   defineComponent,
+  h,
   useRef,
   useStore,
   useAttributes,
+  useParent,
+  useDocument,
   useRoute,
-  useLoading,
+  useAsync,
   useEffect,
   useChildEffect,
-  useDisconnectEffect,
+  useDisconnectCallback,
+  useElementInternals,
   useHost,
-  h,
 } from '@seahax/elemental';
 
 export const MyComponent = defineComponent((shadow) => {
@@ -65,9 +68,15 @@ export const MyComponent = defineComponent((shadow) => {
   // Use a reference (reactive state) bound to a (shared) store.
   const globalStateRef = useStore(myStore, select, mutate);
 
-  // Use references (reactive state) bound to attributes.
+  // Use references (reactive state) bound to the component's attributes.
   const [dataValueRef, ...] = useAttributes('data-value', ...);
 
+  // Use a reference (reactive state) bound to the component's parent node.
+  const parentNode = useParent();
+
+  // Use a reference (reactive state) bound to the component's owner document.
+  const ownerDocument = useDocument();
+
   // Use a reference (reactive state) bound to route matching.
   const routeMatchRef = useRoute('/path/', {
     match: 'prefix', // 'exact' | 'prefix' | RegExp
@@ -75,7 +84,7 @@ export const MyComponent = defineComponent((shadow) => {
   });
 
   // Use a reference (reactive state) bound to an async loader function.
-  const loadingStateRef = useLoading([
+  const asyncRef = useAsync([
     // dependency references
   ], async (signal, ...dependencyValues) => {
     // Reactive async code runs when the component is connected to the
@@ -91,8 +100,7 @@ export const MyComponent = defineComponent((shadow) => {
     globalStateRef,
     dataValueRef,
     routeMatchRef,
-    routeStateRef,
-    loadingStateRef,
+    asyncRef,
   ], (...dependencyValues) => {
     // Reactive code runs when the component is connected to the document,
     // and when any of the dependencies change.
@@ -116,29 +124,74 @@ export const MyComponent = defineComponent((shadow) => {
     };
   });
 
-  useDisconnectEffect(() => {
-    // Reactive code runs when the component is disconnected from the
-    // document.
+  // Register a document disconnection callback.
+  useDisconnectCallback(() => {
+    // Called when the component is disconnected from the document.
   });
 
-  // Use the host element (generally only useful in reusable hooks).
+  // Use the element's internals.
+  const elementInternals = useElementInternals();
+
+  // Use the component host element.
   const host = useHost();
 });
 ```
 
+## Enable Form Association
+
+```ts
+import {
+  useElementInternals,
+  useForm,
+  useFormDisabled,
+  useFormResetCallback,
+  useFormRestoreCallback,
+} from '@seahax/elemental';
+
+const MyComponent = defineComponent(
+  (shadow) => {
+    // Use the element's internals.
+    const elementInternals = useElementInternals();
+
+    // Use a reference (reactive state) bound to the associated form.
+    const formRef = useForm();
+
+    // Use a reference (reactive state) bound to the form disabled state.
+    const formDisabledRef = useFormDisabled();
+
+    // Register a form reset callback.
+    useFormResetCallback(() => {
+      // Called when the associated form is reset. Only called on connect
+      // if the form was reset while the component was disconnected.
+    });
+
+    // Register a form restore callback.
+    useFormRestoreCallback((state, reason) => {
+      // Called when the associated form is restored. Only called on connect
+      // if the form was restored while the component was disconnected.
+    });
+  },
+  {
+    // Enable form association.
+    formAssociated: true,
+  }
+);
+```
+
 ## Customize The Shadow Root
 
 ```ts
 const MyComponent = defineComponent(
   (shadow) => {
-    // Renderer...
+    ...
   },
   {
-    // Shadow root options.
+    // Use custom shadow root initialization options.
+    // (default: { mode: 'open' }).
     shadow: {
       mode: 'closed',
       ...
-    }
+    },
   }
 );
 ```

package/dist/{store.js → createStore.js}

@@ -1,5 +1,5 @@
-import { createCallbacks as e } from "./internal/callbacks.js";
-//#region src/store.ts
+import { createCallbacks as e } from "./internal/createCallbacks.js";
+//#region src/createStore.ts
 function t(t) {
 	let n = e(), r = t;
 	return {
@@ -15,4 +15,4 @@ function t(t) {
 //#endregion
 export { t as createStore };
 
-//# sourceMappingURL=store.js.map
+//# sourceMappingURL=createStore.js.map

package/dist/createStore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"createStore.js","names":[],"sources":["../src/createStore.ts"],"sourcesContent":["import { createCallbacks } from './internal/createCallbacks.ts';\n\nexport interface Store<TState> {\n  state: TState;\n  subscribe: (callback: (state: TState) => void) => () => void;\n}\n\n/** Create a new store containing an observable state. */\nexport function createStore<TState>(initialState: TState): Store<TState> {\n  const callbacks = createCallbacks();\n  let state = initialState;\n\n  return {\n    get state() {\n      return state;\n    },\n    set state(newState) {\n      if (newState === state) return;\n      state = newState;\n      callbacks.run();\n    },\n    subscribe: (callback) => callbacks.push(() => callback(state)),\n  };\n}\n"],"mappings":";;AAQA,SAAgB,EAAoB,GAAqC;CACvE,IAAM,IAAY,GAAiB,EAC/B,IAAQ;AAEZ,QAAO;EACL,IAAI,QAAQ;AACV,UAAO;;EAET,IAAI,MAAM,GAAU;AACd,SAAa,MACjB,IAAQ,GACR,EAAU,KAAK;;EAEjB,YAAY,MAAa,EAAU,WAAW,EAAS,EAAM,CAAC;EAC/D"}

package/dist/{component.d.ts → defineComponent.d.ts}

@@ -1,16 +1,20 @@
-import { type Ref } from './hooks/ref.ts';
-type SafeProps<TProps> = any extends any ? {
-    [P in keyof TProps as P extends keyof HTMLElement ? never : P]: TProps[P];
-} : never;
+import { type Ref } from './hooks/useRef.ts';
+type UnsafeProps = 'connectedCallback' | 'connectedMoveCallback' | 'disconnectedCallback' | 'adoptedCallback' | 'formResetCallback' | 'formStateRestoreCallback' | 'formDisabledCallback';
+type SafePropKeys<TProps> = Exclude<keyof TProps, keyof HTMLElement | UnsafeProps>;
 export interface ComponentConstructor<TProps extends object> {
+    readonly formAssociated: boolean;
     new (): ComponentWithProps<TProps>;
 }
 export interface ComponentOptions<TProps extends object> {
+    /** Shadow root attachment options. */
     readonly shadow?: Partial<ShadowRootInit>;
+    /** Component custom property descriptors. */
     readonly props?: ComponentPropDescriptors<TProps>;
+    /** True to mark the component as form-associated. */
+    readonly formAssociated?: boolean;
 }
 export type ComponentPropDescriptors<TProps extends object> = {
-    readonly [P in keyof SafeProps<TProps>]: ComponentPropDescriptorFactory<TProps[P]>;
+    readonly [P in SafePropKeys<TProps>]: ComponentPropDescriptorFactory<TProps[P]>;
 };
 export type ComponentPropDescriptorFactory<TType> = (ref: Ref<TType | undefined>, host: HTMLElement) => ComponentPropDescriptor<TType>;
 export interface ComponentPropDescriptor<T> extends Omit<PropertyDescriptor, 'value' | 'get' | 'set'> {
@@ -18,13 +22,13 @@ export interface ComponentPropDescriptor<T> extends Omit<PropertyDescriptor, 'va
     set?(value: T): void;
 }
 export type ComponentWithProps<TProps extends object> = HTMLElement & {
-    -readonly [P in keyof SafeProps<TProps>]: TProps[P];
+    -readonly [P in SafePropKeys<TProps>]: TProps[P];
 };
 export type ComponentShadowRoot<TProps extends object> = Omit<ShadowRoot, 'host'> & {
     readonly host: ComponentWithProps<TProps>;
 };
 export type ComponentPropRefs<TProps extends object> = {
-    readonly [P in keyof SafeProps<TProps>]: Ref<TProps[P] | undefined>;
+    readonly [P in SafePropKeys<TProps>]: Ref<TProps[P] | undefined>;
 };
 /** Define a custom `HTMLElement` that is functional and reactive. */
 export declare function defineComponent<TProps extends object = {}>(render: (shadowRoot: ComponentShadowRoot<TProps>, props: ComponentPropRefs<TProps>) => void, options?: ComponentOptions<TProps>): ComponentConstructor<TProps>;

package/dist/defineComponent.js

@@ -0,0 +1,57 @@
+import { createController as e } from "./internal/createController.js";
+//#region src/defineComponent.ts
+function t(t, { props: n, shadow: r, formAssociated: i = !1 } = {}) {
+	return class extends HTMLElement {
+		static formAssociated = i;
+		#e;
+		#t;
+		#n = {};
+		constructor() {
+			if (super(), this.#e = this.attachShadow({
+				...r,
+				mode: r?.mode ?? "open"
+			}), this.#t = e({
+				host: this,
+				formAssociated: i,
+				render: () => t(this.#e, this.#n),
+				attachInternals: () => super.attachInternals()
+			}), n) {
+				let e = this.#n;
+				for (let [t, r] of Object.entries(n)) {
+					if (t in this) continue;
+					let n = r(e[t] = this.#t.createRef(void 0), this);
+					Object.defineProperty(this, t, n);
+				}
+			}
+			i && this.attachInternals();
+		}
+		attachInternals() {
+			return this.#t.attachInternals();
+		}
+		connectedCallback() {
+			this.#t.connectedCallback();
+		}
+		connectedMoveCallback() {
+			this.#t.connectedMoveCallback();
+		}
+		disconnectedCallback() {
+			this.#t.disconnectedCallback();
+		}
+		adoptedCallback() {
+			this.#t.adoptedCallback();
+		}
+		formDisabledCallback(e) {
+			this.#t.formDisabledCallback(e);
+		}
+		formResetCallback() {
+			this.#t.formResetCallback();
+		}
+		formStateRestoreCallback(e, t) {
+			this.#t.formStateRestoreCallback(e, t);
+		}
+	};
+}
+//#endregion
+export { t as defineComponent };
+
+//# sourceMappingURL=defineComponent.js.map

package/dist/defineComponent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"defineComponent.js","names":["#shadow","#controller","#props"],"sources":["../src/defineComponent.ts"],"sourcesContent":["import { type Ref } from './hooks/useRef.ts';\nimport { type Controller, createController } from './internal/createController.ts';\n\ntype UnsafeProps =\n  | 'connectedCallback'\n  | 'connectedMoveCallback'\n  | 'disconnectedCallback'\n  | 'adoptedCallback'\n  | 'formResetCallback'\n  | 'formStateRestoreCallback'\n  | 'formDisabledCallback';\n\ntype SafePropKeys<TProps> = Exclude<keyof TProps, keyof HTMLElement | UnsafeProps>;\n\nexport interface ComponentConstructor<TProps extends object> {\n  readonly formAssociated: boolean;\n  new (): ComponentWithProps<TProps>;\n}\n\nexport interface ComponentOptions<TProps extends object> {\n  /** Shadow root attachment options. */\n  readonly shadow?: Partial<ShadowRootInit>;\n  /** Component custom property descriptors. */\n  readonly props?: ComponentPropDescriptors<TProps>;\n  /** True to mark the component as form-associated. */\n  readonly formAssociated?: boolean;\n}\n\nexport type ComponentPropDescriptors<TProps extends object> = {\n  readonly [P in SafePropKeys<TProps>]: ComponentPropDescriptorFactory<TProps[P]>;\n};\n\nexport type ComponentPropDescriptorFactory<TType> = (\n  ref: Ref<TType | undefined>,\n  host: HTMLElement,\n) => ComponentPropDescriptor<TType>;\n\nexport interface ComponentPropDescriptor<T> extends Omit<PropertyDescriptor, 'value' | 'get' | 'set'> {\n  get(): T;\n  set?(value: T): void;\n}\n\nexport type ComponentWithProps<TProps extends object> = HTMLElement & {\n  -readonly [P in SafePropKeys<TProps>]: TProps[P];\n};\n\nexport type ComponentShadowRoot<TProps extends object> = Omit<ShadowRoot, 'host'> & {\n  readonly host: ComponentWithProps<TProps>;\n};\n\nexport type ComponentPropRefs<TProps extends object> = {\n  readonly [P in SafePropKeys<TProps>]: Ref<TProps[P] | undefined>;\n};\n\n/** Define a custom `HTMLElement` that is functional and reactive. */\nexport function defineComponent<TProps extends object = {}>(\n  render: (shadowRoot: ComponentShadowRoot<TProps>, props: ComponentPropRefs<TProps>) => void,\n  options?: ComponentOptions<TProps>,\n): ComponentConstructor<TProps>;\nexport function defineComponent(\n  render: (\n    shadowRoot: ComponentShadowRoot<Record<string, unknown>>,\n    props: ComponentPropRefs<Record<string, unknown>>,\n  ) => void,\n  { props, shadow, formAssociated = false }: ComponentOptions<Record<string, unknown>> = {},\n): ComponentConstructor<{}> {\n  return class extends HTMLElement {\n    static readonly formAssociated = formAssociated;\n\n    readonly #shadow: ComponentShadowRoot<Record<string, unknown>>;\n    readonly #controller: Controller;\n    readonly #props: ComponentPropRefs<Record<string, unknown>> = {};\n\n    constructor() {\n      super();\n\n      this.#shadow = this.attachShadow({\n        ...shadow,\n        mode: shadow?.mode ?? 'open',\n      }) as ComponentShadowRoot<Record<string, unknown>>;\n\n      this.#controller = createController({\n        host: this,\n        formAssociated,\n        render: () => render(this.#shadow, this.#props),\n        attachInternals: () => super.attachInternals(),\n      });\n\n      if (props) {\n        const propRefs: Record<string, Ref<unknown>> = this.#props;\n\n        for (const [key, getDescriptor] of Object.entries(props)) {\n          if (key in this) continue;\n          const ref = (propRefs[key] = this.#controller.createRef<any>(undefined));\n          const descriptor = getDescriptor(ref, this);\n          Object.defineProperty(this, key, descriptor);\n        }\n      }\n\n      if (formAssociated) {\n        this.attachInternals();\n      }\n    }\n\n    override attachInternals(): ElementInternals {\n      return this.#controller.attachInternals();\n    }\n\n    protected connectedCallback(): void {\n      this.#controller.connectedCallback();\n    }\n\n    protected connectedMoveCallback(): void {\n      this.#controller.connectedMoveCallback();\n    }\n\n    protected disconnectedCallback(): void {\n      this.#controller.disconnectedCallback();\n    }\n\n    protected adoptedCallback(): void {\n      this.#controller.adoptedCallback();\n    }\n\n    protected formDisabledCallback(disabled: boolean): void {\n      this.#controller.formDisabledCallback(disabled);\n    }\n\n    protected formResetCallback(): void {\n      this.#controller.formResetCallback();\n    }\n\n    protected formStateRestoreCallback(state: string | File | FormData, reason: 'restore' | 'autocomplete'): void {\n      this.#controller.formStateRestoreCallback(state, reason);\n    }\n  };\n}\n"],"mappings":";;AA2DA,SAAgB,EACd,GAIA,EAAE,UAAO,WAAQ,oBAAiB,OAAqD,EAAE,EAC/D;AAC1B,QAAO,cAAc,YAAY;EAC/B,OAAgB,iBAAiB;EAEjC;EACA;EACA,KAA8D,EAAE;EAEhE,cAAc;AAeZ,OAdA,OAAO,EAEP,MAAA,IAAe,KAAK,aAAa;IAC/B,GAAG;IACH,MAAM,GAAQ,QAAQ;IACvB,CAAC,EAEF,MAAA,IAAmB,EAAiB;IAClC,MAAM;IACN;IACA,cAAc,EAAO,MAAA,GAAc,MAAA,EAAY;IAC/C,uBAAuB,MAAM,iBAAiB;IAC/C,CAAC,EAEE,GAAO;IACT,IAAM,IAAyC,MAAA;AAE/C,SAAK,IAAM,CAAC,GAAK,MAAkB,OAAO,QAAQ,EAAM,EAAE;AACxD,SAAI,KAAO,KAAM;KAEjB,IAAM,IAAa,EAAc,EADX,KAAO,MAAA,EAAiB,UAAe,KAAA,EAAU,EACjC,KAAK;AAC3C,YAAO,eAAe,MAAM,GAAK,EAAW;;;AAIhD,GAAI,KACF,KAAK,iBAAiB;;EAI1B,kBAA6C;AAC3C,UAAO,MAAA,EAAiB,iBAAiB;;EAG3C,oBAAoC;AAClC,SAAA,EAAiB,mBAAmB;;EAGtC,wBAAwC;AACtC,SAAA,EAAiB,uBAAuB;;EAG1C,uBAAuC;AACrC,SAAA,EAAiB,sBAAsB;;EAGzC,kBAAkC;AAChC,SAAA,EAAiB,iBAAiB;;EAGpC,qBAA+B,GAAyB;AACtD,SAAA,EAAiB,qBAAqB,EAAS;;EAGjD,oBAAoC;AAClC,SAAA,EAAiB,mBAAmB;;EAGtC,yBAAmC,GAAiC,GAA0C;AAC5G,SAAA,EAAiB,yBAAyB,GAAO,EAAO"}

package/dist/{router.d.ts → getRouter.d.ts}

@@ -1,5 +1,5 @@
-import { type Store } from './store.ts';
-export interface RouterState {
+import { type Store } from './createStore.ts';
+interface RouterState {
     readonly pathname: string;
     readonly hash: string;
 }
@@ -9,3 +9,4 @@ export interface RouterState {
  * called (ie. a singleton).
  */
 export declare function getRouter(): Store<RouterState>;
+export {};

package/dist/getRouter.js

@@ -0,0 +1,33 @@
+import { createStore as e } from "./createStore.js";
+//#region src/getRouter.ts
+var t;
+function n() {
+	if (t) return t;
+	let n = e({
+		pathname: window.location.pathname,
+		hash: window.location.hash
+	}), r = () => {
+		let e = n.state;
+		n.state.pathname !== window.location.pathname && (e = {
+			...e,
+			pathname: window.location.pathname
+		}), n.state.hash !== window.location.hash && (e = {
+			...e,
+			hash: window.location.hash
+		}), n.state = e;
+	};
+	return Object.defineProperties(history, Object.fromEntries(["pushState", "replaceState"].map((e) => {
+		let t = history[e].bind(history);
+		return [e, {
+			value: (...e) => {
+				t(...e), r();
+			},
+			enumerable: !0,
+			configurable: !0
+		}];
+	}))), window.addEventListener("popstate", r), t = n, t;
+}
+//#endregion
+export { n as getRouter };
+
+//# sourceMappingURL=getRouter.js.map

package/dist/getRouter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"getRouter.js","names":[],"sources":["../src/getRouter.ts"],"sourcesContent":["import { createStore, type Store } from './createStore.ts';\n\ninterface RouterState {\n  readonly pathname: string;\n  readonly hash: string;\n}\n\nlet singleton: Store<RouterState> | undefined;\n\n/**\n * Get a router {@link Store} that is updated when the client side route (aka:\n * `History`) changes. This method returns the same store every time it is\n * called (ie. a singleton).\n */\nexport function getRouter(): Store<RouterState> {\n  if (singleton) return singleton;\n\n  const store = createStore<RouterState>({\n    pathname: window.location.pathname,\n    hash: window.location.hash,\n  });\n\n  const onUpdate = (): void => {\n    let state = store.state;\n\n    if (store.state.pathname !== window.location.pathname) {\n      state = { ...state, pathname: window.location.pathname };\n    }\n\n    if (store.state.hash !== window.location.hash) {\n      state = { ...state, hash: window.location.hash };\n    }\n\n    store.state = state;\n  };\n\n  Object.defineProperties(\n    history,\n    Object.fromEntries(\n      (['pushState', 'replaceState'] as const).map((method: 'pushState' | 'replaceState') => {\n        const original = history[method].bind(history) as History['pushState'] & History['replaceState'];\n        const descriptor: PropertyDescriptor = {\n          value: (...args: Parameters<typeof original>) => {\n            original(...args);\n            onUpdate();\n          },\n          enumerable: true,\n          configurable: true,\n        };\n\n        return [method, descriptor];\n      }),\n    ),\n  );\n\n  window.addEventListener('popstate', onUpdate);\n  singleton = store;\n  return singleton;\n}\n"],"mappings":";;AAOA,IAAI;AAOJ,SAAgB,IAAgC;AAC9C,KAAI,EAAW,QAAO;CAEtB,IAAM,IAAQ,EAAyB;EACrC,UAAU,OAAO,SAAS;EAC1B,MAAM,OAAO,SAAS;EACvB,CAAC,EAEI,UAAuB;EAC3B,IAAI,IAAQ,EAAM;AAUlB,EARI,EAAM,MAAM,aAAa,OAAO,SAAS,aAC3C,IAAQ;GAAE,GAAG;GAAO,UAAU,OAAO,SAAS;GAAU,GAGtD,EAAM,MAAM,SAAS,OAAO,SAAS,SACvC,IAAQ;GAAE,GAAG;GAAO,MAAM,OAAO,SAAS;GAAM,GAGlD,EAAM,QAAQ;;AAwBhB,QArBA,OAAO,iBACL,SACA,OAAO,YACJ,CAAC,aAAa,eAAe,CAAW,KAAK,MAAyC;EACrF,IAAM,IAAW,QAAQ,GAAQ,KAAK,QAAQ;AAU9C,SAAO,CAAC,GAAQ;GARd,QAAQ,GAAG,MAAsC;AAE/C,IADA,EAAS,GAAG,EAAK,EACjB,GAAU;;GAEZ,YAAY;GACZ,cAAc;GAGA,CAAW;GAC3B,CACH,CACF,EAED,OAAO,iBAAiB,YAAY,EAAS,EAC7C,IAAY,GACL"}

package/dist/hooks/useAsync.d.ts

@@ -0,0 +1,11 @@
+import { type ReadonlyRef, type Ref, type RefValues } from './useRef.ts';
+export interface AsyncValue<TValue> {
+    readonly value: TValue | undefined;
+    readonly error: unknown;
+    readonly isLoading: boolean;
+}
+export interface AsyncOptions {
+    readonly debounceMs?: number;
+}
+/** Use a reference (reactive state) bound to an async loader function. */
+export declare function useAsync<const TDeps extends readonly ReadonlyRef<any>[], TValue>(deps: TDeps, callback: (signal: AbortSignal, ...values: RefValues<TDeps>) => Promise<TValue>, { debounceMs }?: AsyncOptions): Ref<AsyncValue<TValue>>;

package/dist/hooks/{loading.js → useAsync.js}

@@ -1,6 +1,6 @@
-import { useRef as e } from "./ref.js";
-import { useEffect as t } from "./effect.js";
-//#region src/hooks/loading.ts
+import { useRef as e } from "./useRef.js";
+import { useEffect as t } from "./useEffect.js";
+//#region src/hooks/useAsync.ts
 function n(n, r, { debounceMs: i } = {}) {
 	let a = e({
 		value: void 0,
@@ -27,6 +27,6 @@ function n(n, r, { debounceMs: i } = {}) {
 	}), t([], () => () => o = !0), a;
 }
 //#endregion
-export { n as useLoading };
+export { n as useAsync };
 
-//# sourceMappingURL=loading.js.map
+//# sourceMappingURL=useAsync.js.map

package/dist/hooks/useAsync.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useAsync.js","names":[],"sources":["../../src/hooks/useAsync.ts"],"sourcesContent":["import { useEffect } from './useEffect.ts';\nimport { type ReadonlyRef, type Ref, type RefValues, useRef } from './useRef.ts';\n\nexport interface AsyncValue<TValue> {\n  readonly value: TValue | undefined;\n  readonly error: unknown;\n  readonly isLoading: boolean;\n}\n\nexport interface AsyncOptions {\n  readonly debounceMs?: number;\n}\n\n/** Use a reference (reactive state) bound to an async loader function. */\nexport function useAsync<const TDeps extends readonly ReadonlyRef<any>[], TValue>(\n  deps: TDeps,\n  callback: (signal: AbortSignal, ...values: RefValues<TDeps>) => Promise<TValue>,\n  { debounceMs }: AsyncOptions = {},\n): Ref<AsyncValue<TValue>> {\n  const ref = useRef<AsyncValue<TValue>>({ value: undefined, error: undefined, isLoading: true });\n  let skipDebounce = true;\n\n  useEffect(deps, () => (...values) => {\n    const ac = new AbortController();\n\n    Promise.race(\n      skipDebounce\n        ? [Promise.resolve()]\n        : [\n            new Promise((resolve) => setTimeout(resolve, debounceMs)),\n            new Promise((resolve) => ac.signal.addEventListener('abort', resolve, { once: true })),\n          ],\n    )\n      .then(() => {\n        if (ac.signal.aborted) return;\n        return callback(ac.signal, ...(values as any));\n      })\n      .then((value) => {\n        if (ac.signal.aborted) return;\n        ref.value = { isLoading: false, value, error: undefined };\n      })\n      .catch((error: unknown) => {\n        if (ac.signal.aborted) return;\n        ref.value = { isLoading: false, value: undefined, error };\n      });\n\n    skipDebounce = false;\n    return () => ac.abort();\n  });\n\n  // Skip the debounce again if the component unmounts.\n  useEffect([], () => () => (skipDebounce = true));\n\n  return ref;\n}\n"],"mappings":";;;AAcA,SAAgB,EACd,GACA,GACA,EAAE,kBAA6B,EAAE,EACR;CACzB,IAAM,IAAM,EAA2B;EAAE,OAAO,KAAA;EAAW,OAAO,KAAA;EAAW,WAAW;EAAM,CAAC,EAC3F,IAAe;AAiCnB,QA/BA,EAAU,UAAa,GAAG,MAAW;EACnC,IAAM,IAAK,IAAI,iBAAiB;AAwBhC,SAtBA,QAAQ,KACN,IACI,CAAC,QAAQ,SAAS,CAAC,GACnB,CACE,IAAI,SAAS,MAAY,WAAW,GAAS,EAAW,CAAC,EACzD,IAAI,SAAS,MAAY,EAAG,OAAO,iBAAiB,SAAS,GAAS,EAAE,MAAM,IAAM,CAAC,CAAC,CACvF,CACN,CACE,WAAW;AACN,UAAG,OAAO,QACd,QAAO,EAAS,EAAG,QAAQ,GAAI,EAAe;IAC9C,CACD,MAAM,MAAU;AACX,KAAG,OAAO,YACd,EAAI,QAAQ;IAAE,WAAW;IAAO;IAAO,OAAO,KAAA;IAAW;IACzD,CACD,OAAO,MAAmB;AACrB,KAAG,OAAO,YACd,EAAI,QAAQ;IAAE,WAAW;IAAO,OAAO,KAAA;IAAW;IAAO;IACzD,EAEJ,IAAe,UACF,EAAG,OAAO;GACvB,EAGF,EAAU,EAAE,cAAe,IAAe,GAAM,EAEzC"}

package/dist/hooks/{attributes.d.ts → useAttributes.d.ts}

@@ -1,4 +1,4 @@
-import { type Ref } from './ref.ts';
+import { type Ref } from './useRef.ts';
 /** Use references (reactive state) bound to attributes. */
 export declare function useAttributes<const TNames extends string[]>(...names: TNames): {
     -readonly [P in keyof TNames]: Ref<string | null>;

package/dist/hooks/useAttributes.js

@@ -0,0 +1,37 @@
+import { useInternalController as e } from "./useInternalController.js";
+import { useRef as t } from "./useRef.js";
+import { getOrInsert as n } from "../internal/getOrInsert.js";
+import { useHost as r } from "./useHost.js";
+//#region src/hooks/useAttributes.ts
+var i = /* @__PURE__ */ new WeakMap();
+function a(...a) {
+	if (a.length === 0) return {};
+	let o = r(), s = [], c = n(i, o, (t) => {
+		let { onAfterRender: n, onDisconnect: r } = e(), a = /* @__PURE__ */ new Map();
+		return i.set(t, a), n.push(() => {
+			i.delete(t);
+			let e = new MutationObserver((e) => {
+				for (let { attributeName: n } of e) {
+					if (n == null) continue;
+					let e = a.get(n);
+					e && (e.value = t.getAttribute(n));
+				}
+			});
+			e.observe(t, {
+				attributeFilter: [...a.keys()],
+				attributes: !0
+			}), r.push(() => e.disconnect());
+		}), a;
+	});
+	for (let e of a) {
+		let r = n(c, e, (e) => t(o.getAttribute(e), (t) => {
+			t == null ? o.removeAttribute(e) : o.setAttribute(e, t);
+		}));
+		s.push(r);
+	}
+	return s;
+}
+//#endregion
+export { a as useAttributes };
+
+//# sourceMappingURL=useAttributes.js.map

package/dist/hooks/useAttributes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useAttributes.js","names":[],"sources":["../../src/hooks/useAttributes.ts"],"sourcesContent":["import { getOrInsert } from '../internal/getOrInsert.ts';\nimport { useHost } from './useHost.ts';\nimport { useInternalController } from './useInternalController.ts';\nimport { type Ref, useRef } from './useRef.ts';\n\nconst hostRefMaps = new WeakMap<HTMLElement, Map<string, Ref<string | null>>>();\n\n/** Use references (reactive state) bound to attributes. */\nexport function useAttributes<const TNames extends string[]>(\n  ...names: TNames\n): { -readonly [P in keyof TNames]: Ref<string | null> } {\n  if (names.length === 0) return {} as any;\n  const host = useHost();\n  const refs: Ref<string | null>[] = [];\n  const refMap = getOrInsert(hostRefMaps, host, (host) => {\n    const { onAfterRender, onDisconnect } = useInternalController();\n    const refMap = new Map<string, Ref<string | null>>();\n    hostRefMaps.set(host, refMap);\n\n    onAfterRender.push(() => {\n      hostRefMaps.delete(host);\n\n      const observer = new MutationObserver((mutation) => {\n        for (const { attributeName } of mutation) {\n          if (attributeName == null) continue;\n          const ref = refMap.get(attributeName);\n          if (ref) ref.value = host.getAttribute(attributeName);\n        }\n      });\n\n      observer.observe(host, { attributeFilter: [...refMap.keys()], attributes: true });\n      onDisconnect.push(() => observer.disconnect());\n    });\n\n    return refMap;\n  });\n\n  for (const name of names) {\n    const ref = getOrInsert(refMap, name, (name) => {\n      return useRef(host.getAttribute(name), (value) => {\n        if (value == null) host.removeAttribute(name);\n        else host.setAttribute(name, value);\n      });\n    });\n\n    refs.push(ref);\n  }\n\n  return refs as any;\n}\n"],"mappings":";;;;;AAKA,IAAM,oBAAc,IAAI,SAAuD;AAG/E,SAAgB,EACd,GAAG,GACoD;AACvD,KAAI,EAAM,WAAW,EAAG,QAAO,EAAE;CACjC,IAAM,IAAO,GAAS,EAChB,IAA6B,EAAE,EAC/B,IAAS,EAAY,GAAa,IAAO,MAAS;EACtD,IAAM,EAAE,kBAAe,oBAAiB,GAAuB,EACzD,oBAAS,IAAI,KAAiC;AAkBpD,SAjBA,EAAY,IAAI,GAAM,EAAO,EAE7B,EAAc,WAAW;AACvB,KAAY,OAAO,EAAK;GAExB,IAAM,IAAW,IAAI,kBAAkB,MAAa;AAClD,SAAK,IAAM,EAAE,sBAAmB,GAAU;AACxC,SAAI,KAAiB,KAAM;KAC3B,IAAM,IAAM,EAAO,IAAI,EAAc;AACrC,KAAI,MAAK,EAAI,QAAQ,EAAK,aAAa,EAAc;;KAEvD;AAGF,GADA,EAAS,QAAQ,GAAM;IAAE,iBAAiB,CAAC,GAAG,EAAO,MAAM,CAAC;IAAE,YAAY;IAAM,CAAC,EACjF,EAAa,WAAW,EAAS,YAAY,CAAC;IAC9C,EAEK;GACP;AAEF,MAAK,IAAM,KAAQ,GAAO;EACxB,IAAM,IAAM,EAAY,GAAQ,IAAO,MAC9B,EAAO,EAAK,aAAa,EAAK,GAAG,MAAU;AAChD,GAAI,KAAS,OAAM,EAAK,gBAAgB,EAAK,GACxC,EAAK,aAAa,GAAM,EAAM;IACnC,CACF;AAEF,IAAK,KAAK,EAAI;;AAGhB,QAAO"}

package/dist/hooks/useChildEffect.js

@@ -0,0 +1,24 @@
+import { useInternalController as e } from "./useInternalController.js";
+import { useRef as t } from "./useRef.js";
+import { useEffect as n } from "./useEffect.js";
+import { getOrInsert as r } from "../internal/getOrInsert.js";
+import { useHost as i } from "./useHost.js";
+//#region src/hooks/useChildEffect.ts
+var a = /* @__PURE__ */ new WeakMap();
+function o(o) {
+	let s = i();
+	n([r(a, s, () => {
+		let { onAfterRender: n, onDisconnect: r } = e(), i = t({});
+		return n.push(() => {
+			a.delete(s);
+			let e = new MutationObserver(() => {
+				i.value = {};
+			});
+			e.observe(s, { childList: !0 }), r.push(() => e.disconnect());
+		}), i;
+	})], () => o());
+}
+//#endregion
+export { o as useChildEffect };
+
+//# sourceMappingURL=useChildEffect.js.map

package/dist/hooks/useChildEffect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useChildEffect.js","names":[],"sources":["../../src/hooks/useChildEffect.ts"],"sourcesContent":["import { getOrInsert } from '../internal/getOrInsert.ts';\nimport { useEffect } from './useEffect.ts';\nimport { useHost } from './useHost.ts';\nimport { useInternalController } from './useInternalController.ts';\nimport { type Ref, useRef } from './useRef.ts';\n\nconst hostRefs = new WeakMap<HTMLElement, Ref<{}>>();\n\n/** React to child list changes (non-recursive). */\nexport function useChildEffect(callback: () => (() => void) | void): void {\n  const host = useHost();\n  const ref = getOrInsert(hostRefs, host, () => {\n    const { onAfterRender, onDisconnect } = useInternalController();\n    const ref = useRef({});\n\n    onAfterRender.push(() => {\n      hostRefs.delete(host);\n\n      const observer = new MutationObserver(() => {\n        ref.value = {};\n      });\n\n      observer.observe(host, { childList: true });\n      onDisconnect.push(() => observer.disconnect());\n    });\n\n    return ref;\n  });\n\n  useEffect([ref], () => callback());\n}\n"],"mappings":";;;;;;AAMA,IAAM,oBAAW,IAAI,SAA+B;AAGpD,SAAgB,EAAe,GAA2C;CACxE,IAAM,IAAO,GAAS;AAmBtB,GAAU,CAlBE,EAAY,GAAU,SAAY;EAC5C,IAAM,EAAE,kBAAe,oBAAiB,GAAuB,EACzD,IAAM,EAAO,EAAE,CAAC;AAatB,SAXA,EAAc,WAAW;AACvB,KAAS,OAAO,EAAK;GAErB,IAAM,IAAW,IAAI,uBAAuB;AAC1C,MAAI,QAAQ,EAAE;KACd;AAGF,GADA,EAAS,QAAQ,GAAM,EAAE,WAAW,IAAM,CAAC,EAC3C,EAAa,WAAW,EAAS,YAAY,CAAC;IAC9C,EAEK;GAGE,CAAI,QAAQ,GAAU,CAAC"}

package/dist/hooks/useDisconnect.d.ts

@@ -0,0 +1,2 @@
+/** Register a callback for disconnections. */
+export declare function useDisconnectCallback(callback: () => void): void;

package/dist/hooks/useDisconnect.js

@@ -0,0 +1,9 @@
+import { useInternalController as e } from "./useInternalController.js";
+//#region src/hooks/useDisconnect.ts
+function t(t) {
+	e().onDisconnect.push(t);
+}
+//#endregion
+export { t as useDisconnectCallback };
+
+//# sourceMappingURL=useDisconnect.js.map

package/dist/hooks/useDisconnect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useDisconnect.js","names":[],"sources":["../../src/hooks/useDisconnect.ts"],"sourcesContent":["import { useInternalController } from './useInternalController.ts';\n\n/** Register a callback for disconnections. */\nexport function useDisconnectCallback(callback: () => void): void {\n  useInternalController().onDisconnect.push(callback);\n}\n"],"mappings":";;AAGA,SAAgB,EAAsB,GAA4B;AAChE,IAAuB,CAAC,aAAa,KAAK,EAAS"}

package/dist/hooks/useDocument.d.ts

@@ -0,0 +1,3 @@
+import type { ReadonlyRef } from './useRef.ts';
+/** Use a reference (reactive state) bound to the owner document. */
+export declare function useDocument(): ReadonlyRef<Document>;

package/dist/hooks/useDocument.js

@@ -0,0 +1,9 @@
+import { useInternalController as e } from "./useInternalController.js";
+//#region src/hooks/useDocument.ts
+function t() {
+	return e().refDocument;
+}
+//#endregion
+export { t as useDocument };
+
+//# sourceMappingURL=useDocument.js.map

package/dist/hooks/useDocument.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useDocument.js","names":[],"sources":["../../src/hooks/useDocument.ts"],"sourcesContent":["import { useInternalController } from './useInternalController.ts';\nimport type { ReadonlyRef } from './useRef.ts';\n\n/** Use a reference (reactive state) bound to the owner document. */\nexport function useDocument(): ReadonlyRef<Document> {\n  return useInternalController().refDocument;\n}\n"],"mappings":";;AAIA,SAAgB,IAAqC;AACnD,QAAO,GAAuB,CAAC"}

package/dist/hooks/useEffect.d.ts

@@ -0,0 +1,3 @@
+import type { ReadonlyRef, RefValues } from './useRef.ts';
+/** React to observable (reference) changes. */
+export declare function useEffect<const TDeps extends readonly ReadonlyRef<any>[]>(deps: TDeps, callback: (...values: RefValues<TDeps>) => (() => void) | void): void;

package/dist/hooks/useEffect.js

@@ -0,0 +1,17 @@
+import { useInternalController as e } from "./useInternalController.js";
+import { useDisconnectCallback as t } from "./useDisconnect.js";
+//#region src/hooks/useEffect.ts
+function n(n, r) {
+	let i, a, o = () => {
+		let e = i;
+		i = void 0, e?.();
+	};
+	e().onNotify.push(() => {
+		let e = n.map((e) => e.value);
+		a?.length === e.length && a?.every((t, n) => t === e[n]) || (a = e, o(), i = r(...a));
+	}), t(o);
+}
+//#endregion
+export { n as useEffect };
+
+//# sourceMappingURL=useEffect.js.map

package/dist/hooks/useEffect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useEffect.js","names":[],"sources":["../../src/hooks/useEffect.ts"],"sourcesContent":["import { useDisconnectCallback } from './useDisconnect.ts';\nimport { useInternalController } from './useInternalController.ts';\nimport type { ReadonlyRef, RefValues } from './useRef.ts';\n\n/** React to observable (reference) changes. */\nexport function useEffect<const TDeps extends readonly ReadonlyRef<any>[]>(\n  deps: TDeps,\n  callback: (...values: RefValues<TDeps>) => (() => void) | void,\n): void {\n  let cleanupCallback: (() => void) | void;\n  let values: any[] | undefined;\n\n  const cleanup = () => {\n    const callback = cleanupCallback;\n    cleanupCallback = undefined;\n    callback?.();\n  };\n\n  useInternalController().onNotify.push((): void => {\n    const newValues = deps.map((dep) => dep.value);\n    if (values?.length === newValues.length && values?.every((value, i) => value === newValues[i])) return;\n    values = newValues;\n    cleanup();\n    cleanupCallback = callback(...(values as any));\n  });\n\n  useDisconnectCallback(cleanup);\n}\n"],"mappings":";;;AAKA,SAAgB,EACd,GACA,GACM;CACN,IAAI,GACA,GAEE,UAAgB;EACpB,IAAM,IAAW;AAEjB,EADA,IAAkB,KAAA,GAClB,KAAY;;AAWd,CARA,GAAuB,CAAC,SAAS,WAAiB;EAChD,IAAM,IAAY,EAAK,KAAK,MAAQ,EAAI,MAAM;AAC1C,KAAQ,WAAW,EAAU,UAAU,GAAQ,OAAO,GAAO,MAAM,MAAU,EAAU,GAAG,KAC9F,IAAS,GACT,GAAS,EACT,IAAkB,EAAS,GAAI,EAAe;GAC9C,EAEF,EAAsB,EAAQ"}

package/dist/hooks/useElementInternals.d.ts

@@ -0,0 +1,2 @@
+/** Use the element internals. */
+export declare function useElementInternals(): ElementInternals;

package/dist/hooks/useElementInternals.js

@@ -0,0 +1,9 @@
+import { useInternalController as e } from "./useInternalController.js";
+//#region src/hooks/useElementInternals.ts
+function t() {
+	return e().attachInternals();
+}
+//#endregion
+export { t as useElementInternals };
+
+//# sourceMappingURL=useElementInternals.js.map

package/dist/hooks/useElementInternals.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useElementInternals.js","names":[],"sources":["../../src/hooks/useElementInternals.ts"],"sourcesContent":["import { useInternalController } from './useInternalController.ts';\n\n/** Use the element internals. */\nexport function useElementInternals(): ElementInternals {\n  return useInternalController().attachInternals();\n}\n"],"mappings":";;AAGA,SAAgB,IAAwC;AACtD,QAAO,GAAuB,CAAC,iBAAiB"}

package/dist/hooks/useForm.d.ts

@@ -0,0 +1,9 @@
+import type { ReadonlyRef } from './useRef.ts';
+/** Use a reference (reactive state) bound to the associated form. */
+export declare function useForm(): ReadonlyRef<HTMLFormElement | null>;
+/** Use a reference (reactive state) bound to the form disabled state. */
+export declare function useFormDisabled(): ReadonlyRef<boolean>;
+/** Register a callback for form resets. */
+export declare function useFormResetCallback(callback: () => void): void;
+/** Register a callback for form restorations. */
+export declare function useFormRestoreCallback(callback: (state: string | File | FormData, reason: 'restore' | 'autocomplete') => void): void;

package/dist/hooks/useForm.js

@@ -0,0 +1,23 @@
+import { useInternalController as e } from "./useInternalController.js";
+//#region src/hooks/useForm.ts
+function t() {
+	return a().refForm;
+}
+function n() {
+	return a().refDisabled;
+}
+function r(e) {
+	a().onReset.push(e);
+}
+function i(e) {
+	a().onRestore.push(e);
+}
+function a() {
+	let { formAssociated: t } = e();
+	if (!t) throw Error("form hooks must be called in a form-associated component");
+	return t;
+}
+//#endregion
+export { t as useForm, n as useFormDisabled, r as useFormResetCallback, i as useFormRestoreCallback };
+
+//# sourceMappingURL=useForm.js.map

package/dist/hooks/useForm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useForm.js","names":[],"sources":["../../src/hooks/useForm.ts"],"sourcesContent":["import type { Controller } from '../internal/createController.ts';\nimport { useInternalController } from './useInternalController.ts';\nimport type { ReadonlyRef } from './useRef.ts';\n\n/** Use a reference (reactive state) bound to the associated form. */\nexport function useForm(): ReadonlyRef<HTMLFormElement | null> {\n  return useInternalFormAssociatedController().refForm;\n}\n\n/** Use a reference (reactive state) bound to the form disabled state. */\nexport function useFormDisabled(): ReadonlyRef<boolean> {\n  return useInternalFormAssociatedController().refDisabled;\n}\n\n/** Register a callback for form resets. */\nexport function useFormResetCallback(callback: () => void): void {\n  useInternalFormAssociatedController().onReset.push(callback);\n}\n\n/** Register a callback for form restorations. */\nexport function useFormRestoreCallback(\n  callback: (state: string | File | FormData, reason: 'restore' | 'autocomplete') => void,\n): void {\n  useInternalFormAssociatedController().onRestore.push(callback);\n}\n\nfunction useInternalFormAssociatedController(): Controller['formAssociated'] & {} {\n  const { formAssociated } = useInternalController();\n  if (!formAssociated) throw new Error('form hooks must be called in a form-associated component');\n  return formAssociated;\n}\n"],"mappings":";;AAKA,SAAgB,IAA+C;AAC7D,QAAO,GAAqC,CAAC;;AAI/C,SAAgB,IAAwC;AACtD,QAAO,GAAqC,CAAC;;AAI/C,SAAgB,EAAqB,GAA4B;AAC/D,IAAqC,CAAC,QAAQ,KAAK,EAAS;;AAI9D,SAAgB,EACd,GACM;AACN,IAAqC,CAAC,UAAU,KAAK,EAAS;;AAGhE,SAAS,IAAyE;CAChF,IAAM,EAAE,sBAAmB,GAAuB;AAClD,KAAI,CAAC,EAAgB,OAAU,MAAM,2DAA2D;AAChG,QAAO"}

package/dist/hooks/{host.d.ts → useHost.d.ts}

@@ -1,2 +1,2 @@
-/** Get the component host element. */
+/** Use the component host element. */
 export declare function useHost(): HTMLElement;

package/dist/hooks/useHost.js

@@ -0,0 +1,9 @@
+import { useInternalController as e } from "./useInternalController.js";
+//#region src/hooks/useHost.ts
+function t() {
+	return e().host;
+}
+//#endregion
+export { t as useHost };
+
+//# sourceMappingURL=useHost.js.map

package/dist/hooks/useHost.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useHost.js","names":[],"sources":["../../src/hooks/useHost.ts"],"sourcesContent":["import { useInternalController } from './useInternalController.ts';\n\n/** Use the component host element. */\nexport function useHost(): HTMLElement {\n  return useInternalController().host;\n}\n"],"mappings":";;AAGA,SAAgB,IAAuB;AACrC,QAAO,GAAuB,CAAC"}

package/dist/hooks/useInternalController.d.ts

@@ -0,0 +1,3 @@
+import { type Controller } from '../internal/createController.ts';
+/** @internal Get the controller of the currently rendering component. */
+export declare function useInternalController(): Controller;

package/dist/hooks/useInternalController.js

@@ -0,0 +1,11 @@
+import { controllers as e } from "../internal/controllers.js";
+//#region src/hooks/useInternalController.ts
+function t() {
+	let t = e.at(-1);
+	if (!t) throw Error("hooks must be called by a render function");
+	return t;
+}
+//#endregion
+export { t as useInternalController };
+
+//# sourceMappingURL=useInternalController.js.map

package/dist/hooks/useInternalController.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useInternalController.js","names":[],"sources":["../../src/hooks/useInternalController.ts"],"sourcesContent":["import { controllers } from '../internal/controllers.ts';\nimport { type Controller } from '../internal/createController.ts';\n\n/** @internal Get the controller of the currently rendering component. */\nexport function useInternalController(): Controller {\n  const controller = controllers.at(-1);\n  if (!controller) throw new Error('hooks must be called by a render function');\n  return controller;\n}\n"],"mappings":";;AAIA,SAAgB,IAAoC;CAClD,IAAM,IAAa,EAAY,GAAG,GAAG;AACrC,KAAI,CAAC,EAAY,OAAU,MAAM,4CAA4C;AAC7E,QAAO"}

package/dist/hooks/useParent.d.ts

@@ -0,0 +1,3 @@
+import type { ReadonlyRef } from './useRef.ts';
+/** Use a reference (reactive state) bound to the parent node. */
+export declare function useParent(): ReadonlyRef<ParentNode | null>;