@bquery/bquery 1.6.0 → 1.7.0

package/src/component/scope.ts

@@ -0,0 +1,212 @@
+/**
+ * Component-scoped reactive primitives.
+ *
+ * Provides `useSignal`, `useComputed`, and `useEffect` that automatically
+ * dispose when their owning component disconnects from the DOM.
+ *
+ * @module bquery/component
+ */
+
+import type { Computed } from '../reactive/computed';
+import { computed } from '../reactive/computed';
+import { detectDevEnvironment } from '../core/env';
+import type { Signal } from '../reactive/core';
+import { signal } from '../reactive/core';
+import { effect } from '../reactive/effect';
+import type { CleanupFn } from '../reactive/index';
+
+/**
+ * Holds disposable resources created inside a component scope.
+ * All registered disposers run when the component disconnects.
+ * @internal
+ */
+export interface ComponentScope {
+  /** Register a cleanup function to run on dispose */
+  addDisposer(fn: CleanupFn): void;
+  /** Dispose all registered resources */
+  dispose(): void;
+}
+
+/** Currently active component scope. @internal */
+let currentScope: ComponentScope | undefined;
+
+/**
+ * Sets the active component scope.
+ * @internal
+ */
+export function setCurrentScope(scope: ComponentScope | undefined): ComponentScope | undefined {
+  const previousScope = currentScope;
+  currentScope = scope;
+  return previousScope;
+}
+
+/**
+ * Returns the active component scope, or undefined if none.
+ * @internal
+ */
+export function getCurrentScope(): ComponentScope | undefined {
+  return currentScope;
+}
+
+/**
+ * Creates a new component scope that tracks disposable resources.
+ * @internal
+ */
+export function createComponentScope(): ComponentScope {
+  const disposers: CleanupFn[] = [];
+
+  return {
+    addDisposer(fn: CleanupFn): void {
+      disposers.push(fn);
+    },
+    dispose(): void {
+      for (const fn of disposers) {
+        try {
+          fn();
+        } catch (error) {
+          if (
+            detectDevEnvironment() &&
+            typeof console !== 'undefined' &&
+            typeof console.error === 'function'
+          ) {
+            console.error('bQuery component: Error disposing scoped resource', error);
+          }
+        }
+      }
+      disposers.length = 0;
+    },
+  };
+}
+
+/**
+ * Creates a reactive signal scoped to the current component.
+ *
+ * The signal is automatically disposed when the component disconnects
+ * from the DOM, removing all subscribers and preventing memory leaks.
+ *
+ * Must be called during a component lifecycle hook such as `connected`,
+ * `beforeMount`, `onAdopted`, or `onAttributeChanged`.
+ *
+ * Do not create scoped primitives from `render()`. Repeated renders can
+ * accumulate render-scoped resources until disconnect; prefer lifecycle hooks.
+ *
+ * @template T - The type of the signal value
+ * @param initialValue - The initial value of the signal
+ * @returns A new Signal instance that auto-disposes with the component
+ * @throws {Error} If called outside a component scope
+ *
+ * @example
+ * ```ts
+ * import { component, html, useSignal } from '@bquery/bquery/component';
+ *
+ * component('my-counter', {
+ *   connected() {
+ *     const count = useSignal(0);
+ *     // count.dispose() is called automatically on disconnect
+ *   },
+ *   render({ state }) {
+ *     return html`<span>${state.count}</span>`;
+ *   },
+ * });
+ * ```
+ */
+export function useSignal<T>(initialValue: T): Signal<T> {
+  const scope = currentScope;
+  if (!scope) {
+    throw new Error(
+      'bQuery component: useSignal() must be called inside a component lifecycle hook. Avoid calling it directly from render()'
+    );
+  }
+  const s = signal(initialValue);
+  scope.addDisposer(() => s.dispose());
+  return s;
+}
+
+/**
+ * Creates a computed value scoped to the current component.
+ *
+ * The computed value's internal effect is automatically cleaned up
+ * when the component disconnects from the DOM.
+ *
+ * Must be called during a component lifecycle hook such as `connected`,
+ * `beforeMount`, `onAdopted`, or `onAttributeChanged`.
+ *
+ * Do not create scoped primitives from `render()`. Repeated renders can
+ * accumulate render-scoped resources until disconnect; prefer lifecycle hooks.
+ *
+ * @template T - The type of the computed value
+ * @param fn - Derivation function that reads reactive sources
+ * @returns A new Computed instance that auto-cleans-up with the component
+ * @throws {Error} If called outside a component scope
+ *
+ * @example
+ * ```ts
+ * import { component, html, useSignal, useComputed } from '@bquery/bquery/component';
+ *
+ * component('my-doubler', {
+ *   connected() {
+ *     const count = useSignal(1);
+ *     const doubled = useComputed(() => count.value * 2);
+ *   },
+ *   render({ state }) {
+ *     return html`<span>${state.doubled}</span>`;
+ *   },
+ * });
+ * ```
+ */
+export function useComputed<T>(fn: () => T): Computed<T> {
+  const scope = currentScope;
+  if (!scope) {
+    throw new Error(
+      'bQuery component: useComputed() must be called inside a component lifecycle hook. Avoid calling it directly from render()'
+    );
+  }
+  const c = computed(fn);
+  scope.addDisposer(() => c.dispose());
+  return c;
+}
+
+/**
+ * Creates a side effect scoped to the current component.
+ *
+ * The effect runs immediately and re-runs when its reactive dependencies
+ * change. It is automatically disposed when the component disconnects
+ * from the DOM.
+ *
+ * Must be called during a component lifecycle hook such as `connected`,
+ * `beforeMount`, `onAdopted`, or `onAttributeChanged`.
+ *
+ * Do not create scoped primitives from `render()`. Repeated renders can
+ * accumulate render-scoped resources until disconnect; prefer lifecycle hooks.
+ *
+ * @param fn - The effect function; may return a cleanup function
+ * @returns A cleanup function to manually stop the effect early
+ * @throws {Error} If called outside a component scope
+ *
+ * @example
+ * ```ts
+ * import { component, useSignal, useEffect } from '@bquery/bquery/component';
+ *
+ * component('my-logger', {
+ *   connected() {
+ *     const count = useSignal(0);
+ *     useEffect(() => {
+ *       console.log('Count changed:', count.value);
+ *       return () => console.log('Cleanup');
+ *     });
+ *   },
+ *   render() { return '<p>Logger</p>'; },
+ * });
+ * ```
+ */
+export function useEffect(fn: () => void | CleanupFn): CleanupFn {
+  const scope = currentScope;
+  if (!scope) {
+    throw new Error(
+      'bQuery component: useEffect() must be called inside a component lifecycle hook. Avoid calling it directly from render()'
+    );
+  }
+  const cleanup = effect(fn);
+  scope.addDisposer(cleanup);
+  return cleanup;
+}

package/src/component/types.ts

@@ -51,54 +51,48 @@ export type PropDefinition<T = unknown> = {
  * When no explicit state generic is provided, component state falls back to
  * an untyped string-keyed record for backwards compatibility.
  */
-export type ComponentStateShape<
-  TState extends Record<string, unknown> | undefined = undefined,
-> = TState extends Record<string, unknown> ? TState : Record<string, unknown>;
+export type ComponentStateShape<TState extends Record<string, unknown> | undefined = undefined> =
+  TState extends Record<string, unknown> ? TState : Record<string, unknown>;
 
 /**
  * Component state keys are string-based because runtime state access is backed
  * by plain object properties.
  */
-export type ComponentStateKey<
-  TState extends Record<string, unknown> | undefined = undefined,
-> =
+export type ComponentStateKey<TState extends Record<string, unknown> | undefined = undefined> =
   keyof ComponentStateShape<TState> & string;
 
 /**
  * Public component element instance shape exposed by lifecycle hooks and
  * `defineComponent()` return values.
  */
-export type ComponentElement<
-  TState extends Record<string, unknown> | undefined = undefined,
-> = HTMLElement & {
-  /**
-   * Updates a state property and triggers a re-render.
-   *
-   * @param key - The state property key
-   * @param value - The new value
-   */
-  setState<TKey extends ComponentStateKey<TState>>(
-    key: TKey,
-    value: ComponentStateShape<TState>[TKey]
-  ): void;
-  /**
-   * Gets a state property value.
-   *
-   * @param key - The state property key
-   * @returns The current value
-   */
-  getState<TKey extends ComponentStateKey<TState>>(
-    key: TKey
-  ): ComponentStateShape<TState>[TKey];
-  /**
-   * Gets a state property value with an explicit cast for backwards
-   * compatibility with the pre-typed-state API.
-   *
-   * @param key - The state property key
-   * @returns The current value cast to `TResult`
-   */
-  getState<TResult = unknown>(key: string): TResult;
-};
+export type ComponentElement<TState extends Record<string, unknown> | undefined = undefined> =
+  HTMLElement & {
+    /**
+     * Updates a state property and triggers a re-render.
+     *
+     * @param key - The state property key
+     * @param value - The new value
+     */
+    setState<TKey extends ComponentStateKey<TState>>(
+      key: TKey,
+      value: ComponentStateShape<TState>[TKey]
+    ): void;
+    /**
+     * Gets a state property value.
+     *
+     * @param key - The state property key
+     * @returns The current value
+     */
+    getState<TKey extends ComponentStateKey<TState>>(key: TKey): ComponentStateShape<TState>[TKey];
+    /**
+     * Gets a state property value with an explicit cast for backwards
+     * compatibility with the pre-typed-state API.
+     *
+     * @param key - The state property key
+     * @returns The current value cast to `TResult`
+     */
+    getState<TResult = unknown>(key: string): TResult;
+  };
 
 /**
  * Constructor returned by `defineComponent()`.
@@ -185,8 +179,8 @@ type ComponentHookWithProps<
   TState extends Record<string, unknown> | undefined = undefined,
   TResult = void,
 > = {
-   (this: ComponentElement<TState>, newProps: TProps, oldProps: TProps): TResult;
-   (newProps: TProps, oldProps: TProps): TResult;
+  (this: ComponentElement<TState>, newProps: TProps, oldProps: TProps): TResult;
+  (newProps: TProps, oldProps: TProps): TResult;
 };
 type ComponentUpdatedHook<
   TState extends Record<string, unknown> | undefined = undefined,
@@ -200,6 +194,17 @@ type ComponentErrorHook<TState extends Record<string, unknown> | undefined = und
   (error: Error): void;
 };
 
+type ComponentAttributeChangedHook<TState extends Record<string, unknown> | undefined = undefined> =
+  {
+    (
+      this: ComponentElement<TState>,
+      name: string,
+      oldValue: string | null,
+      newValue: string | null
+    ): void;
+    (name: string, oldValue: string | null, newValue: string | null): void;
+  };
+
 type ComponentStateDefinition<TState extends Record<string, unknown> | undefined = undefined> =
   TState extends Record<string, unknown>
     ? {
@@ -222,6 +227,15 @@ type ComponentSignalsDefinition<TSignals extends ComponentSignals = Record<strin
         signals: TSignals;
       };
 
+/**
+ * Controls Shadow DOM mode for the component.
+ *
+ * - `true` or `'open'` — attach an open shadow root (default)
+ * - `'closed'` — attach a closed shadow root
+ * - `false` — no shadow root; render directly into the host element
+ */
+export type ShadowMode = boolean | 'open' | 'closed';
+
 export type ComponentDefinition<
   TProps extends Record<string, unknown> = Record<string, unknown>,
   TState extends Record<string, unknown> | undefined = undefined,
@@ -230,8 +244,25 @@ export type ComponentDefinition<
   ComponentSignalsDefinition<TSignals> & {
     /** Prop definitions with types and defaults */
     props?: Record<keyof TProps, PropDefinition>;
-    /** CSS styles scoped to the component's shadow DOM */
+    /**
+     * CSS styles injected for the component.
+     *
+     * When `shadow` uses a shadow root (`true`, `'open'`, or `'closed'`), these
+     * styles are scoped to that shadow tree. When `shadow` is `false`, the
+     * generated `<style>` element is rendered into the host's light DOM and may
+     * therefore affect surrounding markup according to normal CSS cascade rules.
+     */
     styles?: string;
+    /**
+     * Controls Shadow DOM mode.
+     *
+     * - `true` or `'open'` — open shadow root (default)
+     * - `'closed'` — closed shadow root
+     * - `false` — no shadow root; render into the host element
+     *
+     * @default true
+     */
+    shadow?: ShadowMode;
     /**
      * Extra sanitizer options merged with the framework base allowlist during render.
      * Only opt in attributes/tags whose values you control or validate. Sensitive
@@ -239,12 +270,35 @@ export type ComponentDefinition<
      * or UI-redressing risks if used with untrusted input.
      */
     sanitize?: ComponentSanitizeOptions;
+    /**
+     * Additional attributes to observe beyond those declared in `props`.
+     *
+     * Useful when you want `onAttributeChanged` to fire for attributes
+     * that are not part of the typed props system.
+     */
+    observeAttributes?: string[];
     /** Lifecycle hook called before the component mounts (before first render) */
     beforeMount?: ComponentHook<TState>;
     /** Lifecycle hook called when component is added to DOM */
     connected?: ComponentHook<TState>;
     /** Lifecycle hook called when component is removed from DOM */
     disconnected?: ComponentHook<TState>;
+    /**
+     * Lifecycle hook called when the component is moved to a new document
+     * (e.g. via `document.adoptNode`).
+     */
+    onAdopted?: ComponentHook<TState>;
+    /**
+     * Lifecycle hook called when any observed attribute changes.
+     *
+     * Observed attributes are automatically derived from `props` keys
+     * plus any additional names in `observeAttributes`.
+     *
+     * @param name - The attribute name that changed
+     * @param oldValue - The previous attribute value (null if added)
+     * @param newValue - The new attribute value (null if removed)
+     */
+    onAttributeChanged?: ComponentAttributeChangedHook<TState>;
     /** Lifecycle hook called before an update render; return false to prevent */
     beforeUpdate?: ComponentHookWithProps<TProps, TState, boolean | void>;
     /** Lifecycle hook called after update renders; receives attribute change info when applicable */