@bquery/bquery 1.0.0

package/src/component/index.ts

@@ -0,0 +1,360 @@
+/**
+ * Minimal Web Component helper for building custom elements.
+ *
+ * This module provides a declarative API for defining Web Components
+ * without complex build steps. Features include:
+ * - Type-safe props with automatic attribute coercion
+ * - Reactive state management
+ * - Shadow DOM encapsulation with scoped styles
+ * - Lifecycle hooks (connected, disconnected)
+ * - Event emission helpers
+ *
+ * @module bquery/component
+ *
+ * @example
+ * ```ts
+ * import { component, html } from 'bquery/component';
+ *
+ * component('user-card', {
+ *   props: {
+ *     username: { type: String, required: true },
+ *     avatar: { type: String, default: '/default-avatar.png' },
+ *   },
+ *   styles: `
+ *     .card { padding: 1rem; border: 1px solid #ccc; }
+ *   `,
+ *   render({ props }) {
+ *     return html`
+ *       <div class="card">
+ *         <img src="${props.avatar}" alt="${props.username}" />
+ *         <h3>${props.username}</h3>
+ *       </div>
+ *     `;
+ *   },
+ * });
+ * ```
+ */
+
+/**
+ * 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;
+};
+
+/**
+ * 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 when component is added to DOM */
+    connected?: () => void;
+    /** Lifecycle hook called when component is removed from DOM */
+    disconnected?: () => void;
+    /** Lifecycle hook called after reactive updates trigger a render */
+    updated?: () => void;
+    /** Render function returning HTML string */
+    render: (context: {
+      props: TProps;
+      state: Record<string, unknown>;
+      emit: (event: string, detail?: unknown) => void;
+    }) => string;
+  };
+
+/**
+ * Coerces a string attribute value into a typed prop value.
+ * Supports String, Number, Boolean, Object, Array, and custom converters.
+ *
+ * @internal
+ * @template T - The target type
+ * @param rawValue - The raw string value from the attribute
+ * @param config - The prop definition with type information
+ * @returns The coerced value of type T
+ */
+const coercePropValue = <T>(rawValue: string, config: PropDefinition<T>): T => {
+  const { type } = config;
+
+  if (type === String) return rawValue as T;
+
+  if (type === Number) {
+    const parsed = Number(rawValue);
+    return (Number.isNaN(parsed) ? rawValue : parsed) as T;
+  }
+
+  if (type === Boolean) {
+    const normalized = rawValue.trim().toLowerCase();
+    if (normalized === '' || normalized === 'true' || normalized === '1') {
+      return true as T;
+    }
+    if (normalized === 'false' || normalized === '0') {
+      return false as T;
+    }
+    return Boolean(rawValue) as T;
+  }
+
+  if (type === Object || type === Array) {
+    try {
+      return JSON.parse(rawValue) as T;
+    } catch {
+      return rawValue as T;
+    }
+  }
+
+  if (typeof type === 'function') {
+    const callable = type as (value: unknown) => T;
+    const constructable = type as new (value: unknown) => T;
+    try {
+      return callable(rawValue);
+    } catch {
+      return new constructable(rawValue);
+    }
+  }
+
+  return rawValue as T;
+};
+
+/**
+ * Tagged template literal for creating HTML strings.
+ *
+ * This function handles interpolation of values into HTML templates,
+ * converting null/undefined to empty strings.
+ *
+ * @param strings - Template literal string parts
+ * @param values - Interpolated values
+ * @returns Combined HTML string
+ *
+ * @example
+ * ```ts
+ * const name = 'World';
+ * const greeting = html`<h1>Hello, ${name}!</h1>`;
+ * // Result: '<h1>Hello, World!</h1>'
+ * ```
+ */
+export const html = (strings: TemplateStringsArray, ...values: unknown[]): string => {
+  return strings.reduce((acc, part, index) => `${acc}${part}${values[index] ?? ''}`, '');
+};
+
+/**
+ * Escapes HTML entities in interpolated values for XSS prevention.
+ * Use this when you need to safely embed user content in templates.
+ *
+ * @param strings - Template literal string parts
+ * @param values - Interpolated values to escape
+ * @returns Combined HTML string with escaped values
+ *
+ * @example
+ * ```ts
+ * const userInput = '<script>alert("xss")</script>';
+ * const safe = safeHtml`<div>${userInput}</div>`;
+ * // Result: '<div>&lt;script&gt;alert("xss")&lt;/script&gt;</div>'
+ * ```
+ */
+export const safeHtml = (strings: TemplateStringsArray, ...values: unknown[]): string => {
+  const escapeMap: Record<string, string> = {
+    '&': '&amp;',
+    '<': '&lt;',
+    '>': '&gt;',
+    '"': '&quot;',
+    "'": '&#x27;',
+    '`': '&#x60;',
+  };
+
+  const escape = (value: unknown): string => {
+    const str = String(value ?? '');
+    return str.replace(/[&<>"'`]/g, (char) => escapeMap[char]);
+  };
+
+  return strings.reduce((acc, part, index) => `${acc}${part}${escape(values[index])}`, '');
+};
+
+/**
+ * Defines and registers a custom Web Component.
+ *
+ * This function creates a new custom element with the given tag name
+ * and configuration. The component uses Shadow DOM for encapsulation
+ * and automatically re-renders when observed attributes change.
+ *
+ * @template TProps - Type of the component's props
+ * @param tagName - The custom element tag name (must contain a hyphen)
+ * @param definition - The component configuration
+ *
+ * @example
+ * ```ts
+ * component('counter-button', {
+ *   props: {
+ *     start: { type: Number, default: 0 },
+ *   },
+ *   state: { count: 0 },
+ *   styles: `
+ *     button { padding: 0.5rem 1rem; }
+ *   `,
+ *   connected() {
+ *     console.log('Counter mounted');
+ *   },
+ *   render({ props, state, emit }) {
+ *     return html`
+ *       <button onclick="this.getRootNode().host.increment()">
+ *         Count: ${state.count}
+ *       </button>
+ *     `;
+ *   },
+ * });
+ * ```
+ */
+export const component = <TProps extends Record<string, unknown>>(
+  tagName: string,
+  definition: ComponentDefinition<TProps>
+): void => {
+  /**
+   * Internal Web Component class created for each component definition.
+   * @internal
+   */
+  class BQueryComponent extends HTMLElement {
+    /** Internal state object for the component */
+    private readonly state = { ...(definition.state ?? {}) };
+    /** Typed props object populated from attributes */
+    private props = {} as TProps;
+
+    constructor() {
+      super();
+      this.attachShadow({ mode: 'open' });
+      this.syncProps();
+    }
+
+    /**
+     * Returns the list of attributes to observe for changes.
+     */
+    static get observedAttributes(): string[] {
+      return Object.keys(definition.props ?? {});
+    }
+
+    /**
+     * Called when the element is added to the DOM.
+     */
+    connectedCallback(): void {
+      definition.connected?.call(this);
+      this.render();
+    }
+
+    /**
+     * Called when the element is removed from the DOM.
+     */
+    disconnectedCallback(): void {
+      definition.disconnected?.call(this);
+    }
+
+    /**
+     * Called when an observed attribute changes.
+     */
+    attributeChangedCallback(): void {
+      this.syncProps();
+      this.render(true);
+    }
+
+    /**
+     * Updates a state property and triggers a re-render.
+     *
+     * @param key - The state property key
+     * @param value - The new value
+     */
+    setState(key: string, value: unknown): void {
+      this.state[key] = value;
+      this.render(true);
+    }
+
+    /**
+     * Gets a state property value.
+     *
+     * @param key - The state property key
+     * @returns The current value
+     */
+    getState<T = unknown>(key: string): T {
+      return this.state[key] as T;
+    }
+
+    /**
+     * Synchronizes props from attributes.
+     * @internal
+     */
+    private syncProps(): void {
+      const props = definition.props ?? {};
+      for (const [key, config] of Object.entries(props) as [string, PropDefinition][]) {
+        const attrValue = this.getAttribute(key);
+        if (attrValue == null) {
+          if (config.required && config.default === undefined) {
+            throw new Error(`bQuery component: missing required prop "${key}"`);
+          }
+          (this.props as Record<string, unknown>)[key] = config.default ?? undefined;
+          continue;
+        }
+        (this.props as Record<string, unknown>)[key] = coercePropValue(
+          attrValue,
+          config
+        ) as TProps[keyof TProps];
+      }
+    }
+
+    /**
+     * Renders the component to its shadow root.
+     * @internal
+     */
+    private render(triggerUpdated = false): void {
+      /**
+       * Emits a custom event from the component.
+       */
+      const emit = (event: string, detail?: unknown): void => {
+        this.dispatchEvent(new CustomEvent(event, { detail, bubbles: true, composed: true }));
+      };
+
+      if (!this.shadowRoot) return;
+
+      const markup = definition.render({
+        props: this.props,
+        state: this.state,
+        emit,
+      });
+
+      const styles = definition.styles ? `<style>${definition.styles}</style>` : '';
+      this.shadowRoot.innerHTML = `${styles}${markup}`;
+
+      if (triggerUpdated) {
+        definition.updated?.call(this);
+      }
+    }
+  }
+
+  if (!customElements.get(tagName)) {
+    customElements.define(tagName, BQueryComponent);
+  }
+};

package/src/core/collection.ts

@@ -0,0 +1,339 @@
+import { sanitizeHtml } from '../security/sanitize';
+import { BQueryElement } from './element';
+import { applyAll } from './shared';
+
+/**
+ * Wrapper for multiple DOM elements.
+ * Provides batch operations on a collection of elements with chainable API.
+ *
+ * This class enables jQuery-like operations across multiple elements:
+ * - All mutating methods apply to every element in the collection
+ * - Getter methods return data from the first element
+ * - Supports iteration via forEach, map, filter, and reduce
+ *
+ * @example
+ * ```ts
+ * $$('.items')
+ *   .addClass('highlight')
+ *   .css({ opacity: '0.8' })
+ *   .on('click', () => console.log('clicked'));
+ * ```
+ */
+export class BQueryCollection {
+  /**
+   * Creates a new collection wrapper.
+   * @param elements - Array of DOM elements to wrap
+   */
+  constructor(public readonly elements: Element[]) {}
+
+  /**
+   * Gets the number of elements in the collection.
+   */
+  get length(): number {
+    return this.elements.length;
+  }
+
+  /**
+   * Gets the first element in the collection, if any.
+   * @internal
+   */
+  private first(): Element | undefined {
+    return this.elements[0];
+  }
+
+  /**
+   * Gets a single element as a BQueryElement wrapper.
+   *
+   * @param index - Zero-based index of the element
+   * @returns BQueryElement wrapper or undefined if out of range
+   */
+  eq(index: number): BQueryElement | undefined {
+    const el = this.elements[index];
+    return el ? new BQueryElement(el) : undefined;
+  }
+
+  /**
+   * Gets the first element as a BQueryElement wrapper.
+   *
+   * @returns BQueryElement wrapper or undefined if empty
+   */
+  firstEl(): BQueryElement | undefined {
+    return this.eq(0);
+  }
+
+  /**
+   * Gets the last element as a BQueryElement wrapper.
+   *
+   * @returns BQueryElement wrapper or undefined if empty
+   */
+  lastEl(): BQueryElement | undefined {
+    return this.eq(this.elements.length - 1);
+  }
+
+  /**
+   * Iterates over each element in the collection.
+   *
+   * @param callback - Function to call for each wrapped element
+   * @returns The instance for method chaining
+   */
+  each(callback: (element: BQueryElement, index: number) => void): this {
+    this.elements.forEach((element, index) => {
+      callback(new BQueryElement(element), index);
+    });
+    return this;
+  }
+
+  /**
+   * Maps each element to a new value.
+   *
+   * @param callback - Function to transform each element
+   * @returns Array of transformed values
+   */
+  map<T>(callback: (element: Element, index: number) => T): T[] {
+    return this.elements.map(callback);
+  }
+
+  /**
+   * Filters elements based on a predicate.
+   *
+   * @param predicate - Function to test each element
+   * @returns New BQueryCollection with matching elements
+   */
+  filter(predicate: (element: Element, index: number) => boolean): BQueryCollection {
+    return new BQueryCollection(this.elements.filter(predicate));
+  }
+
+  /**
+   * Reduces the collection to a single value.
+   *
+   * @param callback - Reducer function
+   * @param initialValue - Initial accumulator value
+   * @returns Accumulated result
+   */
+  reduce<T>(callback: (accumulator: T, element: Element, index: number) => T, initialValue: T): T {
+    return this.elements.reduce(callback, initialValue);
+  }
+
+  /**
+   * Converts the collection to an array of BQueryElement wrappers.
+   *
+   * @returns Array of BQueryElement instances
+   */
+  toArray(): BQueryElement[] {
+    return this.elements.map((el) => new BQueryElement(el));
+  }
+
+  /** Add one or more classes to all elements. */
+  addClass(...classNames: string[]): this {
+    applyAll(this.elements, (el) => el.classList.add(...classNames));
+    return this;
+  }
+
+  /** Remove one or more classes from all elements. */
+  removeClass(...classNames: string[]): this {
+    applyAll(this.elements, (el) => el.classList.remove(...classNames));
+    return this;
+  }
+
+  /** Toggle a class on all elements. */
+  toggleClass(className: string, force?: boolean): this {
+    applyAll(this.elements, (el) => el.classList.toggle(className, force));
+    return this;
+  }
+
+  /**
+   * Sets an attribute on all elements or gets from first.
+   *
+   * @param name - Attribute name
+   * @param value - Value to set (optional)
+   * @returns Attribute value when getting, instance when setting
+   */
+  attr(name: string, value?: string): string | this {
+    if (value === undefined) {
+      return this.first()?.getAttribute(name) ?? '';
+    }
+    applyAll(this.elements, (el) => el.setAttribute(name, value));
+    return this;
+  }
+
+  /**
+   * Removes an attribute from all elements.
+   *
+   * @param name - Attribute name to remove
+   * @returns The instance for method chaining
+   */
+  removeAttr(name: string): this {
+    applyAll(this.elements, (el) => el.removeAttribute(name));
+    return this;
+  }
+
+  /**
+   * Sets text content on all elements or gets from first.
+   *
+   * @param value - Text to set (optional)
+   * @returns Text content when getting, instance when setting
+   */
+  text(value?: string): string | this {
+    if (value === undefined) {
+      return this.first()?.textContent ?? '';
+    }
+    applyAll(this.elements, (el) => {
+      el.textContent = value;
+    });
+    return this;
+  }
+
+  /**
+   * Sets sanitized HTML on all elements or gets from first.
+   *
+   * @param value - HTML to set (optional, will be sanitized)
+   * @returns HTML content when getting, instance when setting
+   */
+  html(value?: string): string | this {
+    if (value === undefined) {
+      return this.first()?.innerHTML ?? '';
+    }
+    const sanitized = sanitizeHtml(value);
+    applyAll(this.elements, (el) => {
+      el.innerHTML = sanitized;
+    });
+    return this;
+  }
+
+  /**
+   * Sets HTML on all elements without sanitization.
+   *
+   * @param value - Raw HTML to set
+   * @returns The instance for method chaining
+   * @warning Bypasses XSS protection
+   */
+  htmlUnsafe(value: string): this {
+    applyAll(this.elements, (el) => {
+      el.innerHTML = value;
+    });
+    return this;
+  }
+
+  /**
+   * Applies CSS styles to all elements.
+   *
+   * @param property - Property name or object of properties
+   * @param value - Value when setting single property
+   * @returns The instance for method chaining
+   */
+  css(property: string | Record<string, string>, value?: string): this {
+    if (typeof property === 'string') {
+      if (value !== undefined) {
+        applyAll(this.elements, (el) => {
+          (el as HTMLElement).style.setProperty(property, value);
+        });
+      }
+      return this;
+    }
+
+    applyAll(this.elements, (el) => {
+      for (const [key, val] of Object.entries(property)) {
+        (el as HTMLElement).style.setProperty(key, val);
+      }
+    });
+    return this;
+  }
+
+  /**
+   * Shows all elements.
+   *
+   * @param display - Optional display value (default: '')
+   * @returns The instance for method chaining
+   */
+  show(display: string = ''): this {
+    applyAll(this.elements, (el) => {
+      el.removeAttribute('hidden');
+      (el as HTMLElement).style.display = display;
+    });
+    return this;
+  }
+
+  /**
+   * Hides all elements.
+   *
+   * @returns The instance for method chaining
+   */
+  hide(): this {
+    applyAll(this.elements, (el) => {
+      (el as HTMLElement).style.display = 'none';
+    });
+    return this;
+  }
+
+  /**
+   * Adds an event listener to all elements.
+   *
+   * @param event - Event type
+   * @param handler - Event handler
+   * @returns The instance for method chaining
+   */
+  on(event: string, handler: EventListenerOrEventListenerObject): this {
+    applyAll(this.elements, (el) => el.addEventListener(event, handler));
+    return this;
+  }
+
+  /**
+   * Adds a one-time event listener to all elements.
+   *
+   * @param event - Event type
+   * @param handler - Event handler
+   * @returns The instance for method chaining
+   */
+  once(event: string, handler: EventListener): this {
+    applyAll(this.elements, (el) => el.addEventListener(event, handler, { once: true }));
+    return this;
+  }
+
+  /**
+   * Removes an event listener from all elements.
+   *
+   * @param event - Event type
+   * @param handler - The handler to remove
+   * @returns The instance for method chaining
+   */
+  off(event: string, handler: EventListenerOrEventListenerObject): this {
+    applyAll(this.elements, (el) => el.removeEventListener(event, handler));
+    return this;
+  }
+
+  /**
+   * Triggers a custom event on all elements.
+   *
+   * @param event - Event type
+   * @param detail - Optional event detail
+   * @returns The instance for method chaining
+   */
+  trigger(event: string, detail?: unknown): this {
+    applyAll(this.elements, (el) => {
+      el.dispatchEvent(new CustomEvent(event, { detail, bubbles: true, cancelable: true }));
+    });
+    return this;
+  }
+
+  /**
+   * Removes all elements from the DOM.
+   *
+   * @returns The instance for method chaining
+   */
+  remove(): this {
+    applyAll(this.elements, (el) => el.remove());
+    return this;
+  }
+
+  /**
+   * Clears all child nodes from all elements.
+   *
+   * @returns The instance for method chaining
+   */
+  empty(): this {
+    applyAll(this.elements, (el) => {
+      el.innerHTML = '';
+    });
+    return this;
+  }
+}