@bquery/bquery 1.3.0 → 1.5.0

package/src/component/types.ts

@@ -1,85 +1,91 @@
-/**
- * Component types and render context definitions.
- *
- * @module bquery/component
- */
-
-/**
- * Defines a single prop's type and configuration.
- *
- * @template T - The TypeScript type of the prop value
- *
- * @example
- * ```ts
- * const myProp: PropDefinition<number> = {
- *   type: Number,
- *   required: false,
- *   default: 0,
- * };
- * ```
- */
-export type PropDefinition<T = unknown> = {
-  /** Constructor or converter function for the prop type */
-  type:
-    | StringConstructor
-    | NumberConstructor
-    | BooleanConstructor
-    | ObjectConstructor
-    | ArrayConstructor
-    | { new (value: unknown): T }
-    | ((value: unknown) => T);
-  /** Whether the prop must be provided */
-  required?: boolean;
-  /** Default value when prop is not provided */
-  default?: T;
-  /** Optional validator function to validate prop values */
-  validator?: (value: T) => boolean;
-  /**
-   * Explicitly control whether to invoke `type` with `new` (constructor) or as a plain function.
-   * - `true`: Always use `new type(value)` (for class constructors, Date, etc.)
-   * - `false`: Always call `type(value)` (for converter functions)
-   * - `undefined` (default): Auto-detect based on heuristics with fallback
-   */
-  construct?: boolean;
-};
-
-/**
- * Render context passed into a component render function.
- */
-export type ComponentRenderContext<TProps extends Record<string, unknown>> = {
-  /** Typed props object populated from attributes */
-  props: TProps;
-  /** Internal mutable state object */
-  state: Record<string, unknown>;
-  /** Emit a custom event from the component */
-  emit: (event: string, detail?: unknown) => void;
-};
-
-/**
- * Complete component definition including props, state, styles, and lifecycle.
- *
- * @template TProps - Type of the component's props
- */
-export type ComponentDefinition<TProps extends Record<string, unknown> = Record<string, unknown>> =
-  {
-    /** Prop definitions with types and defaults */
-    props?: Record<keyof TProps, PropDefinition>;
-    /** Initial internal state */
-    state?: Record<string, unknown>;
-    /** CSS styles scoped to the component's shadow DOM */
-    styles?: string;
-    /** Lifecycle hook called before the component mounts (before first render) */
-    beforeMount?: () => void;
-    /** Lifecycle hook called when component is added to DOM */
-    connected?: () => void;
-    /** Lifecycle hook called when component is removed from DOM */
-    disconnected?: () => void;
-    /** Lifecycle hook called before an update render; return false to prevent */
-    beforeUpdate?: (props: TProps) => boolean | void;
-    /** Lifecycle hook called after reactive updates trigger a render */
-    updated?: () => void;
-    /** Error handler for errors during rendering or lifecycle */
-    onError?: (error: Error) => void;
-    /** Render function returning HTML string */
-    render: (context: ComponentRenderContext<TProps>) => string;
-  };
+/**
+ * Component types and render context definitions.
+ *
+ * @module bquery/component
+ */
+
+/**
+ * Defines a single prop's type and configuration.
+ *
+ * @template T - The TypeScript type of the prop value
+ *
+ * @example
+ * ```ts
+ * const myProp: PropDefinition<number> = {
+ *   type: Number,
+ *   required: false,
+ *   default: 0,
+ * };
+ * ```
+ */
+export type PropDefinition<T = unknown> = {
+  /** Constructor or converter function for the prop type */
+  type:
+    | StringConstructor
+    | NumberConstructor
+    | BooleanConstructor
+    | ObjectConstructor
+    | ArrayConstructor
+    | { new (value: unknown): T }
+    | ((value: unknown) => T);
+  /** Whether the prop must be provided */
+  required?: boolean;
+  /** Default value when prop is not provided */
+  default?: T;
+  /** Optional validator function to validate prop values */
+  validator?: (value: T) => boolean;
+  /**
+   * Explicitly control whether to invoke `type` with `new` (constructor) or as a plain function.
+   * - `true`: Always use `new type(value)` (for class constructors, Date, etc.)
+   * - `false`: Always call `type(value)` (for converter functions)
+   * - `undefined` (default): Auto-detect based on heuristics with fallback
+   */
+  construct?: boolean;
+};
+
+/**
+ * Render context passed into a component render function.
+ */
+export type ComponentRenderContext<TProps extends Record<string, unknown>> = {
+  /** Typed props object populated from attributes */
+  props: TProps;
+  /** Internal mutable state object */
+  state: Record<string, unknown>;
+  /** Emit a custom event from the component */
+  emit: (event: string, detail?: unknown) => void;
+};
+
+/**
+ * Complete component definition including props, state, styles, and lifecycle.
+ *
+ * @template TProps - Type of the component's props
+ */
+type ComponentHook<TResult = void> = ((this: HTMLElement) => TResult) | (() => TResult);
+type ComponentHookWithProps<TProps extends Record<string, unknown>, TResult = void> =
+  | ((this: HTMLElement, props: TProps) => TResult)
+  | ((props: TProps) => TResult);
+type ComponentErrorHook = ((this: HTMLElement, error: Error) => void) | ((error: Error) => void);
+
+export type ComponentDefinition<TProps extends Record<string, unknown> = Record<string, unknown>> =
+  {
+    /** Prop definitions with types and defaults */
+    props?: Record<keyof TProps, PropDefinition>;
+    /** Initial internal state */
+    state?: Record<string, unknown>;
+    /** CSS styles scoped to the component's shadow DOM */
+    styles?: string;
+    /** Lifecycle hook called before the component mounts (before first render) */
+    beforeMount?: ComponentHook;
+    /** Lifecycle hook called when component is added to DOM */
+    connected?: ComponentHook;
+    /** Lifecycle hook called when component is removed from DOM */
+    disconnected?: ComponentHook;
+    /** Lifecycle hook called before an update render; return false to prevent */
+    beforeUpdate?: ComponentHookWithProps<TProps, boolean | void>;
+    /** Lifecycle hook called after reactive updates trigger a render */
+    updated?: ComponentHook;
+    /** Error handler for errors during rendering or lifecycle */
+    onError?: ComponentErrorHook;
+    /** Render function returning HTML string */
+    render: (context: ComponentRenderContext<TProps>) => string;
+  };

package/src/core/collection.ts

@@ -272,20 +272,33 @@ export class BQueryCollection {
   }
 
   /**
-   * Applies CSS styles to all elements.
+   * Gets or sets CSS styles on all elements.
+   * When getting, returns the computed style value from the first element.
    *
    * @param property - Property name or object of properties
    * @param value - Value when setting single property
-   * @returns The instance for method chaining
+   * @returns The computed style value when getting, instance when setting
    */
-  css(property: string | Record<string, string>, value?: string): this {
+  css(property: string): string;
+  css(property: string, value: string): this;
+  css(property: Record<string, string>): this;
+  css(property: string | Record<string, string>, value?: string): string | this {
     if (typeof property === 'string') {
       if (value !== undefined) {
         applyAll(this.elements, (el) => {
           (el as HTMLElement).style.setProperty(property, value);
         });
+        return this;
+      }
+      const first = this.first();
+      if (!first) {
+        return '';
       }
-      return this;
+      const view = first.ownerDocument?.defaultView;
+      if (!view || typeof view.getComputedStyle !== 'function') {
+        return '';
+      }
+      return view.getComputedStyle(first).getPropertyValue(property);
     }
 
     applyAll(this.elements, (el) => {
@@ -545,6 +558,33 @@ export class BQueryCollection {
     return this;
   }
 
+  /**
+   * Finds all descendant elements matching the selector across all elements
+   * in the collection. Returns a new BQueryCollection with the results.
+   *
+   * @param selector - CSS selector to match
+   * @returns A new BQueryCollection with all matching descendants
+   *
+   * @example
+   * ```ts
+   * $$('.container').find('.item').addClass('highlight');
+   * ```
+   */
+  find(selector: string): BQueryCollection {
+    const seen = new Set<Element>();
+    const results: Element[] = [];
+    for (const el of this.elements) {
+      const found = el.querySelectorAll(selector);
+      for (let i = 0; i < found.length; i++) {
+        if (!seen.has(found[i])) {
+          seen.add(found[i]);
+          results.push(found[i]);
+        }
+      }
+    }
+    return new BQueryCollection(results);
+  }
+
   /**
    * Removes all elements from the DOM.
    *

package/src/core/element.ts

@@ -165,23 +165,34 @@ export class BQueryElement {
    *
    * @param property - A CSS property name or an object of property-value pairs
    * @param value - The value when setting a single property
-   * @returns The instance for method chaining
+   * @returns The computed style value when getting a single property, or the instance for method chaining when setting
    *
    * @example
    * ```ts
-   * // Single property
+   * // Get a computed style value
+   * const color = $('#box').css('color');
+   *
+   * // Set a single property
    * $('#box').css('color', 'red');
    *
-   * // Multiple properties
+   * // Set multiple properties
    * $('#box').css({ color: 'red', 'font-size': '16px' });
    * ```
    */
-  css(property: string | Record<string, string>, value?: string): this {
+  css(property: string): string;
+  css(property: string, value: string): this;
+  css(property: Record<string, string>): this;
+  css(property: string | Record<string, string>, value?: string): string | this {
     if (typeof property === 'string') {
       if (value !== undefined) {
         (this.element as HTMLElement).style.setProperty(property, value);
+        return this;
       }
-      return this;
+      const view = this.element.ownerDocument?.defaultView;
+      if (!view || typeof view.getComputedStyle !== 'function') {
+        return '';
+      }
+      return view.getComputedStyle(this.element).getPropertyValue(property);
     }
 
     for (const [key, val] of Object.entries(property)) {
@@ -563,6 +574,23 @@ export class BQueryElement {
     return this.element.matches(selector);
   }
 
+  /**
+   * Alias for `matches()`. Checks if the element matches a CSS selector.
+   *
+   * @param selector - CSS selector to match against
+   * @returns True if the element matches the selector
+   *
+   * @example
+   * ```ts
+   * if ($('#el').is('.active')) {
+   *   console.log('Element is active');
+   * }
+   * ```
+   */
+  is(selector: string): boolean {
+    return this.matches(selector);
+  }
+
   /**
    * Checks if the element has a specific class.
    *

package/src/core/index.ts

@@ -45,3 +45,4 @@ export {
   isPromise,
   isString,
 } from './utils';
+export type { DebouncedFn, ThrottledFn } from './utils';

package/src/core/utils/function.ts

@@ -4,6 +4,20 @@
  * @module bquery/core/utils/function
  */
 
+/** A debounced function with a cancel method to clear the pending timeout. */
+export interface DebouncedFn<TArgs extends unknown[]> {
+  (...args: TArgs): void;
+  /** Cancels the pending debounced invocation. */
+  cancel(): void;
+}
+
+/** A throttled function with a cancel method to reset the throttle timer. */
+export interface ThrottledFn<TArgs extends unknown[]> {
+  (...args: TArgs): void;
+  /** Resets the throttle timer, allowing the next call to execute immediately. */
+  cancel(): void;
+}
+
 /**
  * Creates a debounced function that delays execution until after
  * the specified delay has elapsed since the last call.
@@ -11,7 +25,7 @@
  * @template TArgs - The argument types of the function
  * @param fn - The function to debounce
  * @param delayMs - Delay in milliseconds
- * @returns A debounced version of the function
+ * @returns A debounced version of the function with a `cancel()` method
  *
  * @example
  * ```ts
@@ -22,19 +36,36 @@
  * search('h');
  * search('he');
  * search('hello'); // Only this call executes after 300ms
+ *
+ * search('cancel me');
+ * search.cancel(); // Cancels the pending invocation
  * ```
  */
 export function debounce<TArgs extends unknown[]>(
   fn: (...args: TArgs) => void,
   delayMs: number
-): (...args: TArgs) => void {
+): DebouncedFn<TArgs> {
   let timeoutId: ReturnType<typeof setTimeout> | undefined;
-  return (...args: TArgs) => {
-    if (timeoutId) {
-      clearTimeout(timeoutId);
+  const debounced: DebouncedFn<TArgs> = Object.assign(
+    (...args: TArgs) => {
+      if (timeoutId !== undefined) {
+        clearTimeout(timeoutId);
+      }
+      timeoutId = setTimeout(() => {
+        timeoutId = undefined;
+        fn(...args);
+      }, delayMs);
+    },
+    {
+      cancel: () => {
+        if (timeoutId !== undefined) {
+          clearTimeout(timeoutId);
+          timeoutId = undefined;
+        }
+      },
     }
-    timeoutId = setTimeout(() => fn(...args), delayMs);
-  };
+  );
+  return debounced;
 }
 
 /**
@@ -43,7 +74,7 @@ export function debounce<TArgs extends unknown[]>(
  * @template TArgs - The argument types of the function
  * @param fn - The function to throttle
  * @param intervalMs - Minimum interval between calls in milliseconds
- * @returns A throttled version of the function
+ * @returns A throttled version of the function with a `cancel()` method
  *
  * @example
  * ```ts
@@ -52,20 +83,30 @@ export function debounce<TArgs extends unknown[]>(
  * }, 100);
  *
  * window.addEventListener('scroll', handleScroll);
+ *
+ * handleScroll.cancel(); // Resets throttle, next call executes immediately
  * ```
  */
 export function throttle<TArgs extends unknown[]>(
   fn: (...args: TArgs) => void,
   intervalMs: number
-): (...args: TArgs) => void {
+): ThrottledFn<TArgs> {
   let lastRun = 0;
-  return (...args: TArgs) => {
-    const now = Date.now();
-    if (now - lastRun >= intervalMs) {
-      lastRun = now;
-      fn(...args);
+  const throttled: ThrottledFn<TArgs> = Object.assign(
+    (...args: TArgs) => {
+      const now = Date.now();
+      if (now - lastRun >= intervalMs) {
+        lastRun = now;
+        fn(...args);
+      }
+    },
+    {
+      cancel: () => {
+        lastRun = 0;
+      },
     }
-  };
+  );
+  return throttled;
 }
 
 /**