@bquery/bquery 1.2.0 → 1.3.0

package/src/view/mount.ts

@@ -0,0 +1,200 @@
+import type { CleanupFn } from '../reactive/index';
+import {
+  createForHandler,
+  handleBind,
+  handleClass,
+  handleHtml,
+  handleIf,
+  handleModel,
+  handleOn,
+  handleRef,
+  handleShow,
+  handleStyle,
+  handleText,
+} from './directives/index';
+import { processChildren, processElement, type DirectiveHandlers } from './process';
+import type { BindingContext, MountOptions, View } from './types';
+
+/**
+ * Mounts a reactive view to an element.
+ *
+ * @param selector - CSS selector or Element
+ * @param context - Binding context with signals, computed, and functions
+ * @param options - Mount options
+ * @returns The mounted View instance
+ *
+ * @security **WARNING:** Directive expressions (bq-text, bq-if, bq-on, etc.) are evaluated
+ * using `new Function()` at runtime. This means:
+ * - Template attributes must come from trusted sources only
+ * - NEVER load templates containing bq-* attributes from user input or untrusted APIs
+ * - If you must use external templates, validate/sanitize attribute values first
+ *
+ * @example
+ * ```ts
+ * import { mount } from 'bquery/view';
+ * import { signal, computed } from 'bquery/reactive';
+ *
+ * const name = signal('World');
+ * const greeting = computed(() => `Hello, ${name.value}!`);
+ * const items = signal([
+ *   { id: 1, text: 'Item 1' },
+ *   { id: 2, text: 'Item 2' },
+ * ]);
+ *
+ * const view = mount('#app', {
+ *   name,
+ *   greeting,
+ *   items,
+ *   addItem: () => {
+ *     items.value = [...items.value, { id: Date.now(), text: 'New Item' }];
+ *   },
+ * });
+ *
+ * // Later, cleanup
+ * view.destroy();
+ * ```
+ */
+export const mount = (
+  selector: string | Element,
+  context: BindingContext,
+  options: MountOptions = {}
+): View => {
+  const { prefix = 'bq', sanitize = true } = options;
+
+  const el = typeof selector === 'string' ? document.querySelector(selector) : selector;
+
+  if (!el) {
+    throw new Error(`bQuery view: Element "${selector}" not found.`);
+  }
+
+  // Reject if root element has bq-for directive
+  // bq-for replaces the element with a placeholder comment, which would leave View.el detached
+  if (el.hasAttribute(`${prefix}-for`)) {
+    throw new Error(
+      `bQuery view: Cannot mount on element with ${prefix}-for directive. ` +
+        `Wrap the ${prefix}-for element in a container instead.`
+    );
+  }
+
+  const cleanups: CleanupFn[] = [];
+
+  const handlers: DirectiveHandlers = {
+    text: handleText,
+    html: handleHtml(sanitize),
+    if: handleIf,
+    show: handleShow,
+    class: handleClass,
+    style: handleStyle,
+    model: handleModel,
+    ref: handleRef,
+    for: createForHandler({
+      prefix,
+      processElement: (node, nodeContext, nodePrefix, nodeCleanups) =>
+        processElement(node, nodeContext, nodePrefix, nodeCleanups, handlers),
+      processChildren: (node, nodeContext, nodePrefix, nodeCleanups) =>
+        processChildren(node, nodeContext, nodePrefix, nodeCleanups, handlers),
+    }),
+    bind: handleBind,
+    on: handleOn,
+  };
+
+  const processWithHandlers = (
+    node: Element,
+    nodeContext: BindingContext,
+    nodeCleanups: CleanupFn[]
+  ) => {
+    // Check if element has bq-for before processing
+    // bq-for replaces the element and handles its children internally
+    const hasFor = node.hasAttribute(`${prefix}-for`);
+
+    processElement(node, nodeContext, prefix, nodeCleanups, handlers);
+
+    // Skip processChildren if bq-for was on this element - it handles children itself
+    if (!hasFor) {
+      processChildren(node, nodeContext, prefix, nodeCleanups, handlers);
+    }
+  };
+
+  // Process the root element and its children
+  processWithHandlers(el, context, cleanups);
+
+  return {
+    el,
+    context,
+
+    update: (newContext: Partial<BindingContext>) => {
+      Object.assign(context, newContext);
+    },
+
+    destroy: () => {
+      for (const cleanup of cleanups) {
+        cleanup();
+      }
+      cleanups.length = 0;
+    },
+  };
+};
+
+/**
+ * Creates a reactive template function.
+ *
+ * @param template - HTML template string
+ * @returns A function that creates a mounted element with the given context
+ *
+ * @example
+ * ```ts
+ * import { createTemplate } from 'bquery/view';
+ * import { signal } from 'bquery/reactive';
+ *
+ * const TodoItem = createTemplate(`
+ *   <li bq-class="{ completed: done }">
+ *     <input type="checkbox" bq-model="done" />
+ *     <span bq-text="text"></span>
+ *   </li>
+ * `);
+ *
+ * const item = TodoItem({
+ *   done: signal(false),
+ *   text: 'Buy groceries',
+ * });
+ *
+ * document.querySelector('#list').append(item.el);
+ * ```
+ */
+export const createTemplate = (
+  template: string,
+  options: MountOptions = {}
+): ((context: BindingContext) => View) => {
+  return (context: BindingContext) => {
+    const container = document.createElement('div');
+    container.innerHTML = template.trim();
+
+    const el = container.firstElementChild;
+    if (!el) {
+      throw new Error('bQuery view: Template must contain a single root element.');
+    }
+
+    // We know at least one element exists (firstElementChild is not null above)
+    // Reject if there are multiple root elements
+    if (container.childElementCount > 1) {
+      throw new Error(
+        `bQuery view: Template must contain exactly one root element, found ${container.childElementCount}.`
+      );
+    }
+
+    const { prefix = 'bq' } = options;
+    // Reject templates with bq-for or bq-if on the root element
+    // These directives replace the element with a placeholder comment, which would leave View.el detached
+    // Since processing happens while el is still in the temporary container, the placeholder
+    // would remain there while view.el is inserted elsewhere, causing desync on future toggles
+    if (el.hasAttribute(`${prefix}-for`) || el.hasAttribute(`${prefix}-if`)) {
+      const directive = el.hasAttribute(`${prefix}-for`) ? 'for' : 'if';
+      throw new Error(
+        `bQuery view: Template root element cannot have ${prefix}-${directive} directive. ` +
+          `Wrap the ${prefix}-${directive} element in a container instead.`
+      );
+    }
+
+    return mount(el, context, options);
+  };
+};

package/src/view/process.ts

@@ -0,0 +1,92 @@
+import type { CleanupFn } from '../reactive/index';
+import type { BindingContext, DirectiveHandler } from './types';
+
+export type DirectiveHandlers = {
+  text: DirectiveHandler;
+  html: DirectiveHandler;
+  if: DirectiveHandler;
+  show: DirectiveHandler;
+  class: DirectiveHandler;
+  style: DirectiveHandler;
+  model: DirectiveHandler;
+  ref: DirectiveHandler;
+  for: DirectiveHandler;
+  bind: (attrName: string) => DirectiveHandler;
+  on: (eventName: string) => DirectiveHandler;
+};
+
+/**
+ * Processes a single element for directives.
+ * @internal
+ */
+export const processElement = (
+  el: Element,
+  context: BindingContext,
+  prefix: string,
+  cleanups: CleanupFn[],
+  handlers: DirectiveHandlers
+): void => {
+  const attributes = Array.from(el.attributes);
+
+  for (const attr of attributes) {
+    const { name, value } = attr;
+
+    if (!name.startsWith(`${prefix}-`)) continue;
+
+    const directive = name.slice(prefix.length + 1); // Remove prefix and dash
+
+    // Handle bq-for specially (creates new scope)
+    if (directive === 'for') {
+      handlers.for(el, value, context, cleanups);
+      return; // Don't process children, bq-for handles it
+    }
+
+    // Handle other directives
+    if (directive === 'text') {
+      handlers.text(el, value, context, cleanups);
+    } else if (directive === 'html') {
+      handlers.html(el, value, context, cleanups);
+    } else if (directive === 'if') {
+      handlers.if(el, value, context, cleanups);
+    } else if (directive === 'show') {
+      handlers.show(el, value, context, cleanups);
+    } else if (directive === 'class') {
+      handlers.class(el, value, context, cleanups);
+    } else if (directive === 'style') {
+      handlers.style(el, value, context, cleanups);
+    } else if (directive === 'model') {
+      handlers.model(el, value, context, cleanups);
+    } else if (directive === 'ref') {
+      handlers.ref(el, value, context, cleanups);
+    } else if (directive.startsWith('bind:')) {
+      const attrName = directive.slice(5);
+      handlers.bind(attrName)(el, value, context, cleanups);
+    } else if (directive.startsWith('on:')) {
+      const eventName = directive.slice(3);
+      handlers.on(eventName)(el, value, context, cleanups);
+    }
+  }
+};
+
+/**
+ * Recursively processes children of an element.
+ * @internal
+ */
+export const processChildren = (
+  el: Element,
+  context: BindingContext,
+  prefix: string,
+  cleanups: CleanupFn[],
+  handlers: DirectiveHandlers
+): void => {
+  const children = Array.from(el.children);
+  for (const child of children) {
+    // Skip if element has bq-for (handled separately)
+    if (!child.hasAttribute(`${prefix}-for`)) {
+      processElement(child, context, prefix, cleanups, handlers);
+      processChildren(child, context, prefix, cleanups, handlers);
+    } else {
+      processElement(child, context, prefix, cleanups, handlers);
+    }
+  }
+};

package/src/view/types.ts

@@ -0,0 +1,44 @@
+/**
+ * Public types for the view module.
+ */
+import type { CleanupFn } from '../reactive/index';
+
+/**
+ * Context object passed to binding expressions.
+ */
+export type BindingContext = Record<string, unknown>;
+
+/**
+ * Configuration options for mount.
+ */
+export type MountOptions = {
+  /** Prefix for directive attributes (default: 'bq') */
+  prefix?: string;
+  /** Whether to sanitize bq-html content (default: true) */
+  sanitize?: boolean;
+};
+
+/**
+ * Mounted view instance.
+ */
+export type View = {
+  /** The root element */
+  el: Element;
+  /** The binding context */
+  context: BindingContext;
+  /** Update the context object. Note: this only mutates the context; reactive re-rendering happens automatically when signals/computed values change. */
+  update: (newContext: Partial<BindingContext>) => void;
+  /** Destroy the view and cleanup effects */
+  destroy: () => void;
+};
+
+/**
+ * Internal directive handler type.
+ * @internal
+ */
+export type DirectiveHandler = (
+  el: Element,
+  expression: string,
+  context: BindingContext,
+  cleanups: CleanupFn[]
+) => void;

package/dist/core/utils.d.ts

@@ -1,313 +0,0 @@
-/**
- * Utility helpers used across the framework.
- * These are intentionally small and framework-agnostic to keep the core tiny.
- *
- * @module bquery/core/utils
- */
-/**
- * Utility object containing common helper functions.
- * All utilities are designed to be tree-shakeable and have zero dependencies.
- */
-export declare const utils: {
-    /**
-     * Creates a deep clone using structuredClone if available, otherwise fallback to JSON.
-     *
-     * @template T - The type of value being cloned
-     * @param value - The value to clone
-     * @returns A deep copy of the value
-     *
-     * @example
-     * ```ts
-     * const original = { nested: { value: 1 } };
-     * const copy = utils.clone(original);
-     * copy.nested.value = 2;
-     * console.log(original.nested.value); // 1
-     * ```
-     */
-    clone<T>(value: T): T;
-    /**
-     * Deep-merges plain objects into a new object.
-     * Later sources override earlier ones for primitive values.
-     * Objects are recursively merged.
-     *
-     * @template T - The type of the merged object
-     * @param sources - Objects to merge
-     * @returns A new object with all sources merged
-     *
-     * @example
-     * ```ts
-     * const result = utils.merge(
-     *   { a: 1, nested: { x: 1 } },
-     *   { b: 2, nested: { y: 2 } }
-     * );
-     * // Result: { a: 1, b: 2, nested: { x: 1, y: 2 } }
-     * ```
-     *
-     * @security This method is protected against prototype pollution attacks.
-     * Keys like `__proto__`, `constructor`, and `prototype` are ignored.
-     */
-    merge<T extends Record<string, unknown>>(...sources: T[]): T;
-    /**
-     * Checks if a key could cause prototype pollution.
-     * These keys are dangerous when used in object merging operations.
-     *
-     * @param key - The key to check
-     * @returns True if the key is a prototype pollution vector
-     *
-     * @internal
-     */
-    isPrototypePollutionKey(key: string): boolean;
-    /**
-     * Creates a debounced function that delays execution until after
-     * the specified delay has elapsed since the last call.
-     *
-     * @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
-     *
-     * @example
-     * ```ts
-     * const search = utils.debounce((query: string) => {
-     *   console.log('Searching:', query);
-     * }, 300);
-     *
-     * search('h');
-     * search('he');
-     * search('hello'); // Only this call executes after 300ms
-     * ```
-     */
-    debounce<TArgs extends unknown[]>(fn: (...args: TArgs) => void, delayMs: number): (...args: TArgs) => void;
-    /**
-     * Creates a throttled function that runs at most once per interval.
-     *
-     * @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
-     *
-     * @example
-     * ```ts
-     * const handleScroll = utils.throttle(() => {
-     *   console.log('Scroll position:', window.scrollY);
-     * }, 100);
-     *
-     * window.addEventListener('scroll', handleScroll);
-     * ```
-     */
-    throttle<TArgs extends unknown[]>(fn: (...args: TArgs) => void, intervalMs: number): (...args: TArgs) => void;
-    /**
-     * Creates a stable unique ID for DOM usage.
-     *
-     * @param prefix - Optional prefix for the ID (default: 'bQuery')
-     * @returns A unique identifier string
-     *
-     * @example
-     * ```ts
-     * const id = utils.uid('modal'); // 'modal_x7k2m9p'
-     * ```
-     */
-    uid(prefix?: string): string;
-    /**
-     * Checks if a value is a DOM Element.
-     *
-     * @param value - The value to check
-     * @returns True if the value is an Element
-     */
-    isElement(value: unknown): value is Element;
-    /**
-     * Checks if a value is a BQueryCollection-like object.
-     *
-     * @param value - The value to check
-     * @returns True if the value has an elements array property
-     */
-    isCollection(value: unknown): value is {
-        elements: Element[];
-    };
-    /**
-     * Checks for emptiness across common value types.
-     *
-     * @param value - The value to check
-     * @returns True if the value is empty (null, undefined, empty string, empty array, or empty object)
-     *
-     * @example
-     * ```ts
-     * utils.isEmpty('');       // true
-     * utils.isEmpty([]);       // true
-     * utils.isEmpty({});       // true
-     * utils.isEmpty(null);     // true
-     * utils.isEmpty('hello');  // false
-     * utils.isEmpty([1, 2]);   // false
-     * ```
-     */
-    isEmpty(value: unknown): boolean;
-    /**
-     * Checks if a value is a plain object (not null, array, or class instance).
-     *
-     * @param value - The value to check
-     * @returns True if the value is a plain object
-     */
-    isPlainObject(value: unknown): value is Record<string, unknown>;
-    /**
-     * Checks if a value is a function.
-     *
-     * @param value - The value to check
-     * @returns True if the value is a function
-     */
-    isFunction(value: unknown): value is (...args: unknown[]) => unknown;
-    /**
-     * Checks if a value is a string.
-     *
-     * @param value - The value to check
-     * @returns True if the value is a string
-     */
-    isString(value: unknown): value is string;
-    /**
-     * Checks if a value is a number (excluding NaN).
-     *
-     * @param value - The value to check
-     * @returns True if the value is a valid number
-     */
-    isNumber(value: unknown): value is number;
-    /**
-     * Checks if a value is a boolean.
-     *
-     * @param value - The value to check
-     * @returns True if the value is a boolean
-     */
-    isBoolean(value: unknown): value is boolean;
-    /**
-     * Checks if a value is an array.
-     *
-     * @template T - The type of array elements
-     * @param value - The value to check
-     * @returns True if the value is an array
-     */
-    isArray<T = unknown>(value: unknown): value is T[];
-    /**
-     * Safely parses a JSON string, returning a default value on error.
-     *
-     * @template T - The expected type of the parsed value
-     * @param json - The JSON string to parse
-     * @param fallback - The default value if parsing fails
-     * @returns The parsed value or the fallback
-     *
-     * @example
-     * ```ts
-     * utils.parseJson('{"name":"bQuery"}', {}); // { name: 'bQuery' }
-     * utils.parseJson('invalid', {}); // {}
-     * ```
-     */
-    parseJson<T>(json: string, fallback: T): T;
-    /**
-     * Picks specified keys from an object.
-     *
-     * @template T - The object type
-     * @template K - The key type
-     * @param obj - The source object
-     * @param keys - Keys to pick
-     * @returns A new object with only the specified keys
-     *
-     * @example
-     * ```ts
-     * const user = { name: 'John', age: 30, email: 'john@example.com' };
-     * utils.pick(user, ['name', 'email']); // { name: 'John', email: 'john@example.com' }
-     * ```
-     */
-    pick<T extends Record<string, unknown>, K extends keyof T>(obj: T, keys: K[]): Pick<T, K>;
-    /**
-     * Omits specified keys from an object.
-     *
-     * @template T - The object type
-     * @template K - The key type
-     * @param obj - The source object
-     * @param keys - Keys to omit
-     * @returns A new object without the specified keys
-     *
-     * @example
-     * ```ts
-     * const user = { name: 'John', age: 30, password: 'secret' };
-     * utils.omit(user, ['password']); // { name: 'John', age: 30 }
-     * ```
-     */
-    omit<T extends Record<string, unknown>, K extends keyof T>(obj: T, keys: K[]): Omit<T, K>;
-    /**
-     * Delays execution for a specified number of milliseconds.
-     *
-     * @param ms - Milliseconds to delay
-     * @returns A promise that resolves after the delay
-     *
-     * @example
-     * ```ts
-     * await utils.sleep(1000); // Wait 1 second
-     * console.log('Done!');
-     * ```
-     */
-    sleep(ms: number): Promise<void>;
-    /**
-     * Generates a random integer between min and max (inclusive).
-     *
-     * @param min - Minimum value
-     * @param max - Maximum value
-     * @returns A random integer in the range [min, max]
-     *
-     * @example
-     * ```ts
-     * const roll = utils.randomInt(1, 6); // Random dice roll
-     * ```
-     */
-    randomInt(min: number, max: number): number;
-    /**
-     * Clamps a number between a minimum and maximum value.
-     *
-     * @param value - The value to clamp
-     * @param min - Minimum value
-     * @param max - Maximum value
-     * @returns The clamped value
-     *
-     * @example
-     * ```ts
-     * utils.clamp(150, 0, 100); // 100
-     * utils.clamp(-10, 0, 100); // 0
-     * utils.clamp(50, 0, 100);  // 50
-     * ```
-     */
-    clamp(value: number, min: number, max: number): number;
-    /**
-     * Capitalizes the first letter of a string.
-     *
-     * @param str - The string to capitalize
-     * @returns The capitalized string
-     *
-     * @example
-     * ```ts
-     * utils.capitalize('hello'); // 'Hello'
-     * ```
-     */
-    capitalize(str: string): string;
-    /**
-     * Converts a string to kebab-case.
-     *
-     * @param str - The string to convert
-     * @returns The kebab-cased string
-     *
-     * @example
-     * ```ts
-     * utils.toKebabCase('myVariableName'); // 'my-variable-name'
-     * ```
-     */
-    toKebabCase(str: string): string;
-    /**
-     * Converts a string to camelCase.
-     *
-     * @param str - The string to convert
-     * @returns The camelCased string
-     *
-     * @example
-     * ```ts
-     * utils.toCamelCase('my-variable-name'); // 'myVariableName'
-     * ```
-     */
-    toCamelCase(str: string): string;
-};
-//# sourceMappingURL=utils.d.ts.map

package/dist/core/utils.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/core/utils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;GAGG;AACH,eAAO,MAAM,KAAK;IAChB;;;;;;;;;;;;;;OAcG;UACG,CAAC,SAAS,CAAC,GAAG,CAAC;IAOrB;;;;;;;;;;;;;;;;;;;;OAoBG;UACG,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,cAAc,CAAC,EAAE,GAAG,CAAC;IAoB5D;;;;;;;;OAQG;iCAC0B,MAAM,GAAG,OAAO;IAI7C;;;;;;;;;;;;;;;;;;;OAmBG;aACM,KAAK,SAAS,OAAO,EAAE,MAC1B,CAAC,GAAG,IAAI,EAAE,KAAK,KAAK,IAAI,WACnB,MAAM,GACd,CAAC,GAAG,IAAI,EAAE,KAAK,KAAK,IAAI;IAU3B;;;;;;;;;;;;;;;;OAgBG;aACM,KAAK,SAAS,OAAO,EAAE,MAC1B,CAAC,GAAG,IAAI,EAAE,KAAK,KAAK,IAAI,cAChB,MAAM,GACjB,CAAC,GAAG,IAAI,EAAE,KAAK,KAAK,IAAI;IAW3B;;;;;;;;;;OAUG;0BACqB,MAAM;IAI9B;;;;;OAKG;qBACc,OAAO,GAAG,KAAK,IAAI,OAAO;IAI3C;;;;;OAKG;wBACiB,OAAO,GAAG,KAAK,IAAI;QAAE,QAAQ,EAAE,OAAO,EAAE,CAAA;KAAE;IAI9D;;;;;;;;;;;;;;;OAeG;mBACY,OAAO,GAAG,OAAO;IAQhC;;;;;OAKG;yBACkB,OAAO,GAAG,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAI/D;;;;;OAKG;sBACe,OAAO,GAAG,KAAK,IAAI,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO;IAIpE;;;;;OAKG;oBACa,OAAO,GAAG,KAAK,IAAI,MAAM;IAIzC;;;;;OAKG;oBACa,OAAO,GAAG,KAAK,IAAI,MAAM;IAIzC;;;;;OAKG;qBACc,OAAO,GAAG,KAAK,IAAI,OAAO;IAI3C;;;;;;OAMG;YACK,CAAC,mBAAmB,OAAO,GAAG,KAAK,IAAI,CAAC,EAAE;IAIlD;;;;;;;;;;;;;OAaG;cACO,CAAC,QAAQ,MAAM,YAAY,CAAC,GAAG,CAAC;IAQ1C;;;;;;;;;;;;;;OAcG;SACE,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,SAAS,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,GAAG,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC;IAUzF;;;;;;;;;;;;;;OAcG;SACE,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,SAAS,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,GAAG,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC;IAQzF;;;;;;;;;;;OAWG;cACO,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIhC;;;;;;;;;;;OAWG;mBACY,MAAM,OAAO,MAAM,GAAG,MAAM;IAI3C;;;;;;;;;;;;;;OAcG;iBACU,MAAM,OAAO,MAAM,OAAO,MAAM,GAAG,MAAM;IAItD;;;;;;;;;;OAUG;oBACa,MAAM,GAAG,MAAM;IAK/B;;;;;;;;;;OAUG;qBACc,MAAM,GAAG,MAAM;IAOhC;;;;;;;;;;OAUG;qBACc,MAAM,GAAG,MAAM;CAKjC,CAAC"}