@bquery/bquery 1.2.0 → 1.3.0

package/src/component/index.ts

@@ -1,414 +1,40 @@
-/**
- * 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;
-  /** Optional validator function to validate prop values */
-  validator?: (value: T) => boolean;
-};
-
-/**
- * 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: {
-      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 {
-      try {
-        definition.beforeMount?.call(this);
-        definition.connected?.call(this);
-        this.render();
-      } catch (error) {
-        this.handleError(error as Error);
-      }
-    }
-
-    /**
-     * Called when the element is removed from the DOM.
-     */
-    disconnectedCallback(): void {
-      try {
-        definition.disconnected?.call(this);
-      } catch (error) {
-        this.handleError(error as Error);
-      }
-    }
-
-    /**
-     * Called when an observed attribute changes.
-     */
-    attributeChangedCallback(): void {
-      try {
-        this.syncProps();
-        this.render(true);
-      } catch (error) {
-        this.handleError(error as Error);
-      }
-    }
-
-    /**
-     * Handles errors during component lifecycle.
-     * @internal
-     */
-    private handleError(error: Error): void {
-      if (definition.onError) {
-        definition.onError.call(this, error);
-      } else {
-        console.error(`bQuery component error in <${tagName}>:`, error);
-      }
-    }
-
-    /**
-     * 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);
-        let value: unknown;
-
-        if (attrValue == null) {
-          if (config.required && config.default === undefined) {
-            throw new Error(`bQuery component: missing required prop "${key}"`);
-          }
-          value = config.default ?? undefined;
-        } else {
-          value = coercePropValue(attrValue, config);
-        }
-
-        // Validate the prop value if a validator is provided
-        if (config.validator && value !== undefined) {
-          const isValid = config.validator(value);
-          if (!isValid) {
-            throw new Error(
-              `bQuery component: validation failed for prop "${key}" with value ${JSON.stringify(value)}`
-            );
-          }
-        }
-
-        (this.props as Record<string, unknown>)[key] = value;
-      }
-    }
-
-    /**
-     * Renders the component to its shadow root.
-     * @internal
-     */
-    private render(triggerUpdated = false): void {
-      try {
-        // Check beforeUpdate hook if this is an update
-        if (triggerUpdated && definition.beforeUpdate) {
-          const shouldUpdate = definition.beforeUpdate.call(this, this.props);
-          if (shouldUpdate === false) return;
-        }
-
-        /**
-         * 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);
-        }
-      } catch (error) {
-        this.handleError(error as Error);
-      }
-    }
-  }
-
-  if (!customElements.get(tagName)) {
-    customElements.define(tagName, BQueryComponent);
-  }
-};
+/**
+ * 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>
+ *     `;
+ *   },
+ * });
+ * ```
+ */
+
+export { component, defineComponent } from './component';
+export { html, safeHtml } from './html';
+export type { ComponentDefinition, ComponentRenderContext, PropDefinition } from './types';

package/src/component/props.ts

@@ -0,0 +1,116 @@
+/**
+ * Prop coercion utilities.
+ *
+ * @module bquery/component
+ */
+
+import type { PropDefinition } from './types';
+
+/**
+ * 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
+ */
+export const coercePropValue = <T>(rawValue: string, config: PropDefinition<T>): T => {
+  const { type } = config;
+
+  if (type === String) return rawValue as T;
+
+  if (type === Number) {
+    return Number(rawValue) 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;
+
+    // Explicit construct mode takes precedence
+    if (config.construct === true) {
+      return Reflect.construct(constructable, [rawValue]) as T;
+    }
+    if (config.construct === false) {
+      return callable(rawValue);
+    }
+
+    // Auto-detect: Check if type is constructable
+    // A function is considered constructable if:
+    // 1. It has a prototype with properties beyond just constructor, OR
+    // 2. Its prototype.constructor is not itself (inherited), OR
+    // 3. It's a class (toString starts with "class")
+    const hasPrototype = type.prototype !== undefined && type.prototype !== null;
+    const prototypeProps = hasPrototype ? Object.getOwnPropertyNames(type.prototype) : [];
+    const hasPrototypeMethods = prototypeProps.length > 1;
+    const hasInheritedConstructor = hasPrototype && type.prototype.constructor !== type;
+    const isClassSyntax = /^class\s/.test(Function.prototype.toString.call(type));
+
+    const isConstructable = hasPrototypeMethods || hasInheritedConstructor || isClassSyntax;
+
+    // For constructable types (e.g. Date, custom classes), prefer `new` to avoid
+    // silent wrong-type returns (Date() returns string, new Date() returns Date)
+    if (isConstructable) {
+      try {
+        return Reflect.construct(constructable, [rawValue]) as T;
+      } catch {
+        // Fall back to calling as function if construction fails
+        return callable(rawValue);
+      }
+    }
+
+    // For non-constructable types (arrow functions, plain functions), call directly
+    // but fall back to constructor if result is undefined (common for function constructors)
+    try {
+      const result = callable(rawValue);
+
+      // If calling without `new` returned undefined and the function has a prototype,
+      // it's likely a function constructor that should be called with `new`
+      if (result === undefined && hasPrototype) {
+        try {
+          return Reflect.construct(constructable, [rawValue]) as T;
+        } catch {
+          // Construction also failed, return the undefined
+          return result as T;
+        }
+      }
+
+      return result as T;
+    } catch (error) {
+      // Fall back to constructor if error indicates 'new' is required
+      const isNewRequired =
+        error instanceof TypeError &&
+        /cannot be invoked without 'new'|is not a function/i.test(error.message);
+
+      if (isNewRequired) {
+        return Reflect.construct(constructable, [rawValue]) as T;
+      }
+
+      // Rethrow original error for non-constructable converters
+      throw error;
+    }
+  }
+
+  return rawValue as T;
+};

package/src/component/types.ts

@@ -0,0 +1,85 @@
+/**
+ * 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;
+  };