@bquery/bquery 1.5.0 → 1.7.0

package/src/reactive/computed.ts

@@ -1,92 +1,130 @@
-/**
- * Computed reactive values.
- */
-
-import {
-  clearDependencies,
-  getCurrentObserver,
-  registerDependency,
-  scheduleObserver,
-  track,
-  type ReactiveSource,
-} from './internals';
-
-/**
- * A computed value that derives from other reactive sources.
- *
- * Computed values are lazily evaluated and cached. They only
- * recompute when their dependencies change.
- *
- * @template T - The type of the computed value
- */
-export class Computed<T> implements ReactiveSource {
-  private cachedValue!: T;
-  private dirty = true;
-  private subscribers = new Set<() => void>();
-  private readonly markDirty = () => {
-    this.dirty = true;
-    // Create snapshot to avoid issues with subscribers modifying the set during iteration
-    const subscribersSnapshot = Array.from(this.subscribers);
-    for (const subscriber of subscribersSnapshot) {
-      scheduleObserver(subscriber);
-    }
-  };
-
-  /**
-   * Creates a new computed value.
-   * @param compute - Function that computes the value
-   */
-  constructor(private readonly compute: () => T) {}
-
-  /**
-   * Gets the computed value, recomputing if dependencies changed.
-   * During untrack calls, getCurrentObserver returns undefined, preventing dependency tracking.
-   */
-  get value(): T {
-    const current = getCurrentObserver();
-    if (current) {
-      this.subscribers.add(current);
-      registerDependency(current, this);
-    }
-    if (this.dirty) {
-      this.dirty = false;
-      // Clear old dependencies before recomputing
-      clearDependencies(this.markDirty);
-      this.cachedValue = track(this.markDirty, this.compute);
-    }
-    return this.cachedValue;
-  }
-
-  /**
-   * Reads the current computed value without tracking.
-   * Useful when you need the value but don't want to create a dependency.
-   *
-   * @returns The current cached value (recomputes if dirty)
-   */
-  peek(): T {
-    if (this.dirty) {
-      this.dirty = false;
-      // Clear old dependencies before recomputing
-      clearDependencies(this.markDirty);
-      this.cachedValue = track(this.markDirty, this.compute);
-    }
-    return this.cachedValue;
-  }
-
-  /**
-   * Removes an observer from this computed's subscriber set.
-   * @internal
-   */
-  unsubscribe(observer: () => void): void {
-    this.subscribers.delete(observer);
-  }
-}
-
-/**
- * Creates a new computed value.
- *
- * @template T - The type of the computed value
- * @param fn - Function that computes the value from reactive sources
- * @returns A new Computed instance
- */
-export const computed = <T>(fn: () => T): Computed<T> => new Computed(fn);
+/**
+ * Computed reactive values.
+ */
+
+import {
+  clearDependencies,
+  getCurrentObserver,
+  registerDependency,
+  scheduleObserver,
+  track,
+  withoutCurrentObserver,
+  type ReactiveSource,
+} from './internals';
+
+/**
+ * A computed value that derives from other reactive sources.
+ *
+ * Computed values are lazily evaluated and cached. They only
+ * recompute when their dependencies change.
+ *
+ * @template T - The type of the computed value
+ */
+export class Computed<T> implements ReactiveSource {
+  private cachedValue!: T;
+  private hasCachedValue = false;
+  private dirty = true;
+  private disposed = false;
+  private subscribers = new Set<() => void>();
+  private readonly markDirty = () => {
+    if (this.disposed) {
+      return;
+    }
+    this.dirty = true;
+    // Create snapshot to avoid issues with subscribers modifying the set during iteration
+    const subscribersSnapshot = Array.from(this.subscribers);
+    for (const subscriber of subscribersSnapshot) {
+      scheduleObserver(subscriber);
+    }
+  };
+
+  /**
+   * Creates a new computed value.
+   * @param compute - Function that computes the value
+   */
+  constructor(private readonly compute: () => T) {}
+
+  /**
+   * Gets the computed value, recomputing if dependencies changed.
+   * During untrack calls, getCurrentObserver returns undefined, preventing dependency tracking.
+   */
+  get value(): T {
+    if (this.disposed) {
+      if (!this.hasCachedValue) {
+        this.cachedValue = withoutCurrentObserver(() => this.compute());
+        this.hasCachedValue = true;
+      }
+      return this.cachedValue;
+    }
+
+    const current = getCurrentObserver();
+    if (current) {
+      this.subscribers.add(current);
+      registerDependency(current, this);
+    }
+    if (this.dirty) {
+      this.dirty = false;
+      // Clear old dependencies before recomputing
+      clearDependencies(this.markDirty);
+      this.cachedValue = track(this.markDirty, this.compute);
+      this.hasCachedValue = true;
+    }
+    return this.cachedValue;
+  }
+
+  /**
+   * Reads the current computed value without tracking.
+   * Useful when you need the value but don't want to create a dependency.
+   *
+   * @returns The current cached value (recomputes if dirty)
+   */
+  peek(): T {
+    if (this.disposed) {
+      if (!this.hasCachedValue) {
+        this.cachedValue = withoutCurrentObserver(() => this.compute());
+        this.hasCachedValue = true;
+      }
+      return this.cachedValue;
+    }
+
+    if (this.dirty) {
+      this.dirty = false;
+      // Clear old dependencies before recomputing
+      clearDependencies(this.markDirty);
+      this.cachedValue = track(this.markDirty, this.compute);
+      this.hasCachedValue = true;
+    }
+    return this.cachedValue;
+  }
+
+  /**
+   * Removes an observer from this computed's subscriber set.
+   * @internal
+   */
+  unsubscribe(observer: () => void): void {
+    this.subscribers.delete(observer);
+  }
+
+  /**
+   * Disposes the computed value by unsubscribing its internal observer
+   * from all upstream dependencies and clearing subscribers.
+   */
+  dispose(): void {
+    this.disposed = true;
+    if (this.dirty) {
+      this.hasCachedValue = false;
+    }
+    this.dirty = false;
+    clearDependencies(this.markDirty);
+    this.subscribers.clear();
+  }
+}
+
+/**
+ * Creates a new computed value.
+ *
+ * @template T - The type of the computed value
+ * @param fn - Function that computes the value from reactive sources
+ * @returns A new Computed instance
+ */
+export const computed = <T>(fn: () => T): Computed<T> => new Computed(fn);

package/src/reactive/index.ts

@@ -1,37 +1,37 @@
-/**
- * Reactive module providing fine-grained reactivity primitives.
- *
- * @module bquery/reactive
- */
-
-export {
-  Computed,
-  Signal,
-  batch,
-  computed,
-  createUseFetch,
-  effect,
-  isComputed,
-  isSignal,
-  linkedSignal,
-  persistedSignal,
-  readonly,
-  signal,
-  useAsyncData,
-  useFetch,
-  untrack,
-  watch,
-} from './signal';
-
-export type {
-  AsyncDataState,
-  AsyncDataStatus,
-  AsyncWatchSource,
-  CleanupFn,
-  FetchInput,
-  LinkedSignal,
-  Observer,
-  ReadonlySignal,
-  UseAsyncDataOptions,
-  UseFetchOptions,
-} from './signal';
+/**
+ * Reactive module providing fine-grained reactivity primitives.
+ *
+ * @module bquery/reactive
+ */
+
+export {
+  Computed,
+  Signal,
+  batch,
+  computed,
+  createUseFetch,
+  effect,
+  isComputed,
+  isSignal,
+  linkedSignal,
+  persistedSignal,
+  readonly,
+  signal,
+  useAsyncData,
+  useFetch,
+  untrack,
+  watch,
+} from './signal';
+
+export type {
+  AsyncDataState,
+  AsyncDataStatus,
+  AsyncWatchSource,
+  CleanupFn,
+  FetchInput,
+  LinkedSignal,
+  Observer,
+  ReadonlySignal,
+  UseAsyncDataOptions,
+  UseFetchOptions,
+} from './signal';

package/src/reactive/signal.ts

@@ -1,29 +1,29 @@
-/**
- * Reactive primitives inspired by fine-grained reactivity.
- *
- * @module bquery/reactive
- */
-
-export { batch } from './batch';
-export { createUseFetch, useAsyncData, useFetch } from './async-data';
-export { Computed, computed } from './computed';
-export { Signal, signal } from './core';
-export { effect } from './effect';
-export { linkedSignal } from './linked';
-export { persistedSignal } from './persisted';
-export { readonly } from './readonly';
-export { isComputed, isSignal } from './type-guards';
-export { untrack } from './untrack';
-export { watch } from './watch';
-
-export type { CleanupFn, Observer } from './internals';
-export type {
-  AsyncDataState,
-  AsyncDataStatus,
-  AsyncWatchSource,
-  FetchInput,
-  UseAsyncDataOptions,
-  UseFetchOptions,
-} from './async-data';
-export type { LinkedSignal } from './linked';
-export type { ReadonlySignal } from './readonly';
+/**
+ * Reactive primitives inspired by fine-grained reactivity.
+ *
+ * @module bquery/reactive
+ */
+
+export { batch } from './batch';
+export { createUseFetch, useAsyncData, useFetch } from './async-data';
+export { Computed, computed } from './computed';
+export { Signal, signal } from './core';
+export { effect } from './effect';
+export { linkedSignal } from './linked';
+export { persistedSignal } from './persisted';
+export { readonly } from './readonly';
+export { isComputed, isSignal } from './type-guards';
+export { untrack } from './untrack';
+export { watch } from './watch';
+
+export type { CleanupFn, Observer } from './internals';
+export type {
+  AsyncDataState,
+  AsyncDataStatus,
+  AsyncWatchSource,
+  FetchInput,
+  UseAsyncDataOptions,
+  UseFetchOptions,
+} from './async-data';
+export type { LinkedSignal } from './linked';
+export type { ReadonlySignal } from './readonly';

package/src/router/bq-link.ts

@@ -0,0 +1,279 @@
+/**
+ * `<bq-link>` custom element for declarative SPA navigation.
+ *
+ * Exposes an accessible custom element that behaves like a link for
+ * client-side routing. Automatically toggles an active class when the
+ * target path matches the current route.
+ *
+ * @module bquery/router
+ *
+ * @example
+ * ```html
+ * <bq-link to="/">Home</bq-link>
+ * <bq-link to="/about" active-class="selected">About</bq-link>
+ * <bq-link to="/settings" replace exact>Settings</bq-link>
+ * ```
+ */
+
+import { effect, type CleanupFn } from '../reactive/index';
+import { navigate } from './navigation';
+import { getActiveRouter, routeSignal } from './state';
+
+/**
+ * Default CSS class applied when the link's target path is active.
+ * @internal
+ */
+const DEFAULT_ACTIVE_CLASS = 'active';
+
+/** @internal */
+const tokenizeClassNames = (value: string): string[] => {
+  return value
+    .split(/\s+/)
+    .map((token) => token.trim())
+    .filter((token) => token.length > 0);
+};
+
+/** @internal SSR-safe base class for environments without HTMLElement. */
+const BQ_LINK_BASE =
+  typeof HTMLElement !== 'undefined' ? HTMLElement : (class {} as unknown as typeof HTMLElement);
+
+/**
+ * `<bq-link>` — A navigation custom element for bQuery routers.
+ *
+ * Attributes:
+ * - `to` — Target path (required). Example: `to="/dashboard"`.
+ * - `replace` — If present, replaces the current history entry instead of pushing.
+ * - `exact` — If present, the active class is only applied on an exact path match.
+ * - `active-class` — CSS class added when the route is active (default: `'active'`).
+ *
+ * The custom element itself acts as the interactive link target using
+ * `role="link"` and keyboard handling. It does not render a native `<a>`,
+ * so browser-native link affordances like context-menu "open in new tab"
+ * are not provided automatically.
+ *
+ * @example
+ * ```ts
+ * import { registerBqLink } from '@bquery/bquery/router';
+ *
+ * // Register the <bq-link> element (idempotent)
+ * registerBqLink();
+ *
+ * // Then use in HTML:
+ * // <bq-link to="/about">About</bq-link>
+ * ```
+ */
+export class BqLinkElement extends BQ_LINK_BASE {
+  /** @internal */
+  private _cleanup: CleanupFn | null = null;
+
+  /** @internal */
+  private _trackedActiveClasses = new Map<string, boolean>();
+
+  static get observedAttributes(): string[] {
+    return ['to', 'replace', 'exact', 'active-class'];
+  }
+
+  /** The target path for navigation. */
+  get to(): string {
+    const to = this.getAttribute('to');
+    return to == null || to.trim() === '' ? '/' : to;
+  }
+
+  set to(value: string) {
+    this.setAttribute('to', value);
+  }
+
+  /** Whether to replace the current history entry. */
+  get replace(): boolean {
+    return this.hasAttribute('replace');
+  }
+
+  set replace(value: boolean) {
+    if (value) {
+      this.setAttribute('replace', '');
+    } else {
+      this.removeAttribute('replace');
+    }
+  }
+
+  /** Whether to match the path exactly for active class. */
+  get exact(): boolean {
+    return this.hasAttribute('exact');
+  }
+
+  set exact(value: boolean) {
+    if (value) {
+      this.setAttribute('exact', '');
+    } else {
+      this.removeAttribute('exact');
+    }
+  }
+
+  /** CSS class applied when the route is active. */
+  get activeClass(): string {
+    return this.getAttribute('active-class') ?? DEFAULT_ACTIVE_CLASS;
+  }
+
+  set activeClass(value: string) {
+    this.setAttribute('active-class', value);
+  }
+
+  /** @internal */
+  connectedCallback(): void {
+    // Set role for accessibility if not an <a> already
+    if (!this.getAttribute('role')) {
+      this.setAttribute('role', 'link');
+    }
+
+    // Make focusable if not already
+    if (!this.hasAttribute('tabindex')) {
+      this.setAttribute('tabindex', '0');
+    }
+
+    // Attach click handler
+    this.addEventListener('click', this._handleClick);
+    this.addEventListener('keydown', this._handleKeydown);
+
+    // Set up reactive active-class tracking
+    this._setupActiveTracking();
+  }
+
+  /** @internal */
+  disconnectedCallback(): void {
+    this.removeEventListener('click', this._handleClick);
+    this.removeEventListener('keydown', this._handleKeydown);
+
+    if (this._cleanup) {
+      this._cleanup();
+      this._cleanup = null;
+    }
+
+    this._clearTrackedActiveClasses();
+  }
+
+  /** @internal */
+  attributeChangedCallback(name: string, _oldValue: string | null, _newValue: string | null): void {
+    // Re-setup active tracking when relevant attributes change
+    if (name === 'to' || name === 'exact' || name === 'active-class') {
+      if (this.isConnected) {
+        this._setupActiveTracking();
+      }
+    }
+  }
+
+  /**
+   * Sets up the reactive effect that toggles the active CSS class
+   * based on the current route.
+   * @internal
+   */
+  private _setupActiveTracking(): void {
+    // Clean up previous effect
+    if (this._cleanup) {
+      this._cleanup();
+      this._cleanup = null;
+    }
+
+    this._clearTrackedActiveClasses();
+
+    const targetPath = this.to;
+    const exactMatch = this.exact;
+    const cssClasses = tokenizeClassNames(this.activeClass);
+    this._trackedActiveClasses = new Map(
+      cssClasses.map((cssClass) => [cssClass, this.classList.contains(cssClass)])
+    );
+
+    this._cleanup = effect(() => {
+      const current = routeSignal.value.path;
+      const isMatch = exactMatch
+        ? current === targetPath
+        : targetPath === '/'
+          ? current === '/'
+          : current === targetPath ||
+            current.startsWith(targetPath.endsWith('/') ? targetPath : targetPath + '/');
+
+      for (const cssClass of cssClasses) {
+        const wasPresentInitially = this._trackedActiveClasses.get(cssClass) ?? false;
+        this.classList.toggle(cssClass, isMatch || wasPresentInitially);
+      }
+
+      // Update aria-current for accessibility
+      if (isMatch) {
+        this.setAttribute('aria-current', 'page');
+      } else {
+        this.removeAttribute('aria-current');
+      }
+    });
+  }
+
+  /** @internal */
+  private _clearTrackedActiveClasses(): void {
+    for (const [cssClass, wasPresentInitially] of this._trackedActiveClasses) {
+      this.classList.toggle(cssClass, wasPresentInitially);
+    }
+    this._trackedActiveClasses.clear();
+  }
+
+  /**
+   * Handles click events for SPA navigation.
+   * @internal
+   */
+  private _handleClick = (e: Event): void => {
+    if (!(e instanceof MouseEvent)) return;
+    if (e.defaultPrevented) return;
+    if (e.button !== 0) return; // Only left clicks
+    if (e.ctrlKey || e.metaKey || e.shiftKey || e.altKey) return;
+
+    e.preventDefault();
+    this._navigate();
+  };
+
+  /**
+   * Handles keyboard activation (Enter).
+   * @internal
+   */
+  private _handleKeydown = (e: Event): void => {
+    if (e instanceof KeyboardEvent && e.key === 'Enter') {
+      e.preventDefault();
+      this._navigate();
+    }
+  };
+
+  /**
+   * Performs the actual navigation.
+   * @internal
+   */
+  private _navigate(): void {
+    const targetPath = this.to;
+    if (!targetPath) return;
+    if (!getActiveRouter()) return;
+
+    void navigate(targetPath, { replace: this.replace }).catch((err) => {
+      console.error('bq-link: Navigation failed:', err);
+    });
+  }
+}
+
+/**
+ * Registers the `<bq-link>` custom element.
+ *
+ * This function is idempotent — calling it multiple times is safe.
+ * The element is registered under the tag name `bq-link`.
+ *
+ * @example
+ * ```ts
+ * import { registerBqLink } from '@bquery/bquery/router';
+ *
+ * registerBqLink();
+ *
+ * // Now use <bq-link to="/about">About</bq-link> in HTML
+ * ```
+ */
+export const registerBqLink = (): void => {
+  if (
+    typeof HTMLElement !== 'undefined' &&
+    typeof customElements !== 'undefined' &&
+    !customElements.get('bq-link')
+  ) {
+    customElements.define('bq-link', BqLinkElement);
+  }
+};