@bquery/bquery 1.2.0 → 1.3.0

package/src/view/directives/for.ts

@@ -0,0 +1,275 @@
+import { effect, signal, type CleanupFn, type Signal } from '../../reactive/index';
+import { evaluate } from '../evaluate';
+import type { BindingContext, DirectiveHandler } from '../types';
+
+type ProcessElementFn = (
+  el: Element,
+  context: BindingContext,
+  prefix: string,
+  cleanups: CleanupFn[]
+) => void;
+
+type ProcessChildrenFn = (
+  el: Element,
+  context: BindingContext,
+  prefix: string,
+  cleanups: CleanupFn[]
+) => void;
+
+/**
+ * Represents a rendered item in bq-for with its DOM element and associated cleanup functions.
+ * @internal
+ */
+type RenderedItem = {
+  key: unknown;
+  element: Element;
+  cleanups: CleanupFn[];
+  item: unknown;
+  index: number;
+  itemSignal: Signal<unknown>; // Reactive item value for item-dependent bindings
+  indexSignal: Signal<number> | null; // Reactive index for index-dependent bindings
+};
+
+/**
+ * Extracts a key from an item using the key expression or falls back to index.
+ * @internal
+ */
+const getItemKey = (
+  item: unknown,
+  index: number,
+  keyExpression: string | null,
+  itemName: string,
+  indexName: string | undefined,
+  context: BindingContext
+): unknown => {
+  if (!keyExpression) {
+    return index; // Fallback to index-based keying
+  }
+
+  const keyContext: BindingContext = {
+    ...context,
+    [itemName]: item,
+  };
+  if (indexName) {
+    keyContext[indexName] = index;
+  }
+
+  return evaluate(keyExpression, keyContext);
+};
+
+/**
+ * Handles bq-for directive - list rendering with keyed reconciliation.
+ *
+ * Supports optional `:key` attribute for efficient DOM reuse:
+ * ```html
+ * <li bq-for="item in items" :key="item.id">...</li>
+ * ```
+ *
+ * Without a key, falls back to index-based tracking (less efficient for reordering).
+ *
+ * @internal
+ */
+export const createForHandler = (options: {
+  prefix: string;
+  processElement: ProcessElementFn;
+  processChildren: ProcessChildrenFn;
+}): DirectiveHandler => {
+  const { prefix, processElement, processChildren } = options;
+
+  return (el, expression, context, cleanups) => {
+    const parent = el.parentNode;
+    if (!parent) return;
+
+    // Parse expression: "item in items" or "(item, index) in items"
+    // Use \S.* instead of .+ to prevent ReDoS by requiring non-whitespace start
+    const match = expression.match(/^\(?(\w+)(?:\s*,\s*(\w+))?\)?\s+in\s+(\S.*)$/);
+    if (!match) {
+      console.error(`bQuery view: Invalid bq-for expression "${expression}"`);
+      return;
+    }
+
+    const [, itemName, indexName, listExpression] = match;
+
+    // Extract :key attribute if present
+    const keyExpression = el.getAttribute(':key') || el.getAttribute(`${prefix}-key`);
+
+    const template = el.cloneNode(true) as Element;
+    template.removeAttribute(`${prefix}-for`);
+    template.removeAttribute(':key');
+    template.removeAttribute(`${prefix}-key`);
+
+    // Create placeholder comment
+    const placeholder = document.createComment(`bq-for: ${expression}`);
+    parent.replaceChild(placeholder, el);
+
+    // Track rendered items by key for reconciliation
+    let renderedItemsMap = new Map<unknown, RenderedItem>();
+    let renderedOrder: unknown[] = [];
+
+    /**
+     * Creates a new DOM element for an item.
+     */
+    const createItemElement = (item: unknown, index: number, key: unknown): RenderedItem => {
+      const clone = template.cloneNode(true) as Element;
+      const itemCleanups: CleanupFn[] = [];
+
+      // Create reactive signals for item and index
+      const itemSig = signal(item);
+      const indexSig = indexName ? signal(index) : null;
+
+      const childContext: BindingContext = {
+        ...context,
+        [itemName]: itemSig,
+      };
+      if (indexName && indexSig) {
+        childContext[indexName] = indexSig;
+      }
+
+      // Process bindings on the clone
+      processElement(clone, childContext, prefix, itemCleanups);
+      processChildren(clone, childContext, prefix, itemCleanups);
+
+      return {
+        key,
+        element: clone,
+        cleanups: itemCleanups,
+        item,
+        index,
+        itemSignal: itemSig,
+        indexSignal: indexSig,
+      };
+    };
+
+    /**
+     * Removes a rendered item and cleans up its effects.
+     */
+    const removeItem = (rendered: RenderedItem): void => {
+      for (const cleanup of rendered.cleanups) {
+        cleanup();
+      }
+      rendered.element.remove();
+    };
+
+    /**
+     * Updates an existing item's data and index when reused.
+     * Updates the reactive signals so bindings re-render.
+     */
+    const updateItem = (rendered: RenderedItem, newItem: unknown, newIndex: number): void => {
+      // Update item if it changed
+      if (!Object.is(rendered.item, newItem)) {
+        rendered.item = newItem;
+        rendered.itemSignal.value = newItem;
+      }
+
+      // Update index if it changed
+      if (rendered.index !== newIndex) {
+        rendered.index = newIndex;
+        if (rendered.indexSignal) {
+          rendered.indexSignal.value = newIndex;
+        }
+      }
+    };
+
+    const cleanup = effect(() => {
+      const list = evaluate<unknown[]>(listExpression, context);
+
+      if (!Array.isArray(list)) {
+        // Clear all if list is invalid
+        for (const rendered of renderedItemsMap.values()) {
+          removeItem(rendered);
+        }
+        renderedItemsMap.clear();
+        renderedOrder = [];
+        return;
+      }
+
+      // Build new key order and detect changes
+      const newKeys: unknown[] = [];
+      const newItemsByKey = new Map<unknown, { item: unknown; index: number }>();
+      const seenKeys = new Set<unknown>();
+
+      list.forEach((item, index) => {
+        let key = getItemKey(item, index, keyExpression, itemName, indexName, context);
+
+        // Detect duplicate keys - warn developer and fall back to unique composite key
+        if (seenKeys.has(key)) {
+          console.warn(
+            `bq-for: Duplicate key "${String(key)}" detected at index ${index}. ` +
+              `Falling back to index-based key for this item. ` +
+              `Ensure :key expressions produce unique values for each item.`
+          );
+          // Create a unique composite key to avoid corrupting rendered output
+          key = { __bqDuplicateKey: key, __bqIndex: index };
+        }
+        seenKeys.add(key);
+
+        newKeys.push(key);
+        newItemsByKey.set(key, { item, index });
+      });
+
+      // Identify items to remove (in old but not in new)
+      const keysToRemove: unknown[] = [];
+      for (const key of renderedOrder) {
+        if (!newItemsByKey.has(key)) {
+          keysToRemove.push(key);
+        }
+      }
+
+      // Remove deleted items
+      for (const key of keysToRemove) {
+        const rendered = renderedItemsMap.get(key);
+        if (rendered) {
+          removeItem(rendered);
+          renderedItemsMap.delete(key);
+        }
+      }
+
+      // Process new list: create new items, update indices, reorder
+      const newRenderedMap = new Map<unknown, RenderedItem>();
+      let lastInsertedElement: Element | Comment = placeholder;
+
+      for (let i = 0; i < newKeys.length; i++) {
+        const key = newKeys[i];
+        const { item, index } = newItemsByKey.get(key)!;
+        let rendered = renderedItemsMap.get(key);
+
+        if (rendered) {
+          // Reuse existing element
+          updateItem(rendered, item, index);
+          newRenderedMap.set(key, rendered);
+
+          // Check if element needs to be moved
+          const currentNext: ChildNode | null = lastInsertedElement.nextSibling;
+          if (currentNext !== rendered.element) {
+            // Move element to correct position
+            lastInsertedElement.after(rendered.element);
+          }
+          lastInsertedElement = rendered.element;
+        } else {
+          // Create new element
+          rendered = createItemElement(item, index, key);
+          newRenderedMap.set(key, rendered);
+
+          // Insert at correct position
+          lastInsertedElement.after(rendered.element);
+          lastInsertedElement = rendered.element;
+        }
+      }
+
+      // Update tracking state
+      renderedItemsMap = newRenderedMap;
+      renderedOrder = newKeys;
+    });
+
+    // When the bq-for itself is cleaned up, also cleanup all rendered items
+    cleanups.push(() => {
+      cleanup();
+      for (const rendered of renderedItemsMap.values()) {
+        for (const itemCleanup of rendered.cleanups) {
+          itemCleanup();
+        }
+      }
+      renderedItemsMap.clear();
+    });
+  };
+};

package/src/view/directives/html.ts

@@ -0,0 +1,19 @@
+import { effect } from '../../reactive/index';
+import { sanitizeHtml } from '../../security/index';
+import { evaluate } from '../evaluate';
+import type { DirectiveHandler } from '../types';
+
+/**
+ * Handles bq-html directive - sets innerHTML (sanitized by default).
+ * @internal
+ */
+export const handleHtml = (sanitize: boolean): DirectiveHandler => {
+  return (el, expression, context, cleanups) => {
+    const cleanup = effect(() => {
+      const value = evaluate<string>(expression, context);
+      const html = String(value ?? '');
+      el.innerHTML = sanitize ? sanitizeHtml(html) : html;
+    });
+    cleanups.push(cleanup);
+  };
+};

package/src/view/directives/if.ts

@@ -0,0 +1,30 @@
+import { effect } from '../../reactive/index';
+import { evaluate } from '../evaluate';
+import type { DirectiveHandler } from '../types';
+
+/**
+ * Handles bq-if directive - conditional rendering.
+ * @internal
+ */
+export const handleIf: DirectiveHandler = (el, expression, context, cleanups) => {
+  const placeholder = document.createComment(`bq-if: ${expression}`);
+
+  // Store original element state
+  let isInserted = true;
+
+  const cleanup = effect(() => {
+    const condition = evaluate<boolean>(expression, context);
+
+    if (condition && !isInserted) {
+      // Insert element using replaceWith to handle moved elements
+      placeholder.replaceWith(el);
+      isInserted = true;
+    } else if (!condition && isInserted) {
+      // Remove element using replaceWith to handle moved elements
+      el.replaceWith(placeholder);
+      isInserted = false;
+    }
+  });
+
+  cleanups.push(cleanup);
+};

package/src/view/directives/index.ts

@@ -0,0 +1,11 @@
+export { handleBind } from './bind';
+export { handleClass } from './class';
+export { createForHandler } from './for';
+export { handleHtml } from './html';
+export { handleIf } from './if';
+export { handleModel } from './model';
+export { handleOn } from './on';
+export { handleRef } from './ref';
+export { handleShow } from './show';
+export { handleStyle } from './style';
+export { handleText } from './text';

package/src/view/directives/model.ts

@@ -0,0 +1,56 @@
+import { effect, isSignal, type Signal } from '../../reactive/index';
+import { evaluateRaw } from '../evaluate';
+import type { DirectiveHandler } from '../types';
+
+/**
+ * Handles bq-model directive - two-way binding.
+ * @internal
+ */
+export const handleModel: DirectiveHandler = (el, expression, context, cleanups) => {
+  const input = el as HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement;
+  const rawValue = evaluateRaw<Signal<unknown>>(expression, context);
+
+  if (!isSignal(rawValue)) {
+    console.warn(`bQuery view: bq-model requires a signal, got "${expression}"`);
+    return;
+  }
+
+  const sig = rawValue as Signal<unknown>;
+
+  // Initial value sync
+  const isCheckbox = input.type === 'checkbox';
+  const isRadio = input.type === 'radio';
+
+  const updateInput = () => {
+    if (isCheckbox) {
+      (input as HTMLInputElement).checked = Boolean(sig.value);
+    } else if (isRadio) {
+      (input as HTMLInputElement).checked = sig.value === input.value;
+    } else {
+      input.value = String(sig.value ?? '');
+    }
+  };
+
+  // Effect to sync signal -> input
+  const cleanup = effect(() => {
+    updateInput();
+  });
+  cleanups.push(cleanup);
+
+  // Event listener to sync input -> signal
+  const eventType = input.tagName === 'SELECT' ? 'change' : 'input';
+  const handler = () => {
+    if (isCheckbox) {
+      sig.value = (input as HTMLInputElement).checked;
+    } else if (isRadio) {
+      if ((input as HTMLInputElement).checked) {
+        sig.value = input.value;
+      }
+    } else {
+      sig.value = input.value;
+    }
+  };
+
+  input.addEventListener(eventType, handler);
+  cleanups.push(() => input.removeEventListener(eventType, handler));
+};

package/src/view/directives/on.ts

@@ -0,0 +1,41 @@
+import { evaluateRaw } from '../evaluate';
+import type { DirectiveHandler } from '../types';
+
+/**
+ * Handles bq-on:event directive - event binding.
+ * @internal
+ */
+export const handleOn = (eventName: string): DirectiveHandler => {
+  return (el, expression, context, cleanups) => {
+    const handler = (event: Event) => {
+      // Add $event to context for expression evaluation
+      const eventContext = { ...context, $event: event, $el: el };
+
+      // Check if expression contains a function call (has parentheses)
+      // If not, it might be a plain function reference like "handleClick"
+      // Note: Method references like "handlers.onClick" will lose their receiver
+      // when auto-invoked. For methods, use explicit calls: "handlers.onClick($event)"
+      const containsCall = expression.includes('(');
+
+      if (!containsCall) {
+        // Evaluate the expression - if it returns a function, invoke it with $event
+        const result = evaluateRaw<unknown>(expression, eventContext);
+        if (typeof result === 'function') {
+          // Auto-invoke with event. Note: `this` will be undefined for method references.
+          // For proper method binding, use explicit syntax: "obj.method($event)"
+          result(event);
+          return;
+        }
+        // If not a function, the expression was already evaluated (e.g., "count.value++")
+        return;
+      }
+
+      // Otherwise evaluate as expression using evaluateRaw to allow signal mutations
+      // (e.g., "count.value++" or "handleClick($event)")
+      evaluateRaw(expression, eventContext);
+    };
+
+    el.addEventListener(eventName, handler);
+    cleanups.push(() => el.removeEventListener(eventName, handler));
+  };
+};

package/src/view/directives/ref.ts

@@ -0,0 +1,41 @@
+import { isSignal, type Signal } from '../../reactive/index';
+import { evaluateRaw } from '../evaluate';
+import type { DirectiveHandler } from '../types';
+
+/**
+ * Checks if an object has a writable `value` property.
+ * Returns true if `value` is an own data property or an accessor with a setter.
+ * @internal
+ */
+function hasWritableValue(obj: object): obj is { value: Element | null } {
+  const descriptor = Object.getOwnPropertyDescriptor(obj, 'value');
+  if (!descriptor) return false;
+  // Data property: check writable flag
+  if ('value' in descriptor) return descriptor.writable === true;
+  // Accessor property: check for setter
+  return typeof descriptor.set === 'function';
+}
+
+/**
+ * Handles bq-ref directive - element reference.
+ * @internal
+ */
+export const handleRef: DirectiveHandler = (el, expression, context, cleanups) => {
+  const rawValue = evaluateRaw<Signal<Element | null> | { value: Element | null }>(
+    expression,
+    context
+  );
+
+  if (isSignal(rawValue)) {
+    rawValue.value = el;
+    cleanups.push(() => {
+      rawValue.value = null;
+    });
+  } else if (typeof rawValue === 'object' && rawValue !== null && hasWritableValue(rawValue)) {
+    // Object with writable .value property (e.g., { value: null })
+    rawValue.value = el;
+    cleanups.push(() => {
+      rawValue.value = null;
+    });
+  }
+};

package/src/view/directives/show.ts

@@ -0,0 +1,26 @@
+import { effect } from '../../reactive/index';
+import { evaluate } from '../evaluate';
+import type { DirectiveHandler } from '../types';
+
+/**
+ * Handles bq-show directive - toggle visibility.
+ * @internal
+ */
+export const handleShow: DirectiveHandler = (el, expression, context, cleanups) => {
+  const htmlEl = el as HTMLElement;
+  // Capture the computed display value to properly restore visibility.
+  // If inline display is 'none' or empty, we need to use the computed value.
+  // Use ownerDocument.defaultView for cross-document/iframe compatibility.
+  let originalDisplay = htmlEl.style.display;
+  if (!originalDisplay || originalDisplay === 'none') {
+    const computed = htmlEl.ownerDocument.defaultView?.getComputedStyle(htmlEl).display ?? '';
+    originalDisplay = computed !== 'none' ? computed : '';
+  }
+
+  const cleanup = effect(() => {
+    const condition = evaluate<boolean>(expression, context);
+    htmlEl.style.display = condition ? originalDisplay : 'none';
+  });
+
+  cleanups.push(cleanup);
+};

package/src/view/directives/style.ts

@@ -0,0 +1,47 @@
+import { effect } from '../../reactive/index';
+import { evaluate, parseObjectExpression } from '../evaluate';
+import type { DirectiveHandler } from '../types';
+
+/**
+ * Handles bq-style directive - dynamic style binding.
+ * @internal
+ */
+export const handleStyle: DirectiveHandler = (el, expression, context, cleanups) => {
+  const htmlEl = el as HTMLElement;
+  let appliedStyles: Set<string> = new Set();
+
+  const cleanup = effect(() => {
+    const newStyles = new Set<string>();
+
+    if (expression.trimStart().startsWith('{')) {
+      const styleMap = parseObjectExpression(expression);
+      for (const [prop, valueExpr] of Object.entries(styleMap)) {
+        const value = evaluate<string>(valueExpr, context);
+        const cssProp = prop.replace(/([A-Z])/g, '-$1').toLowerCase();
+        htmlEl.style.setProperty(cssProp, String(value ?? ''));
+        newStyles.add(cssProp);
+      }
+    } else {
+      const result = evaluate<Record<string, string>>(expression, context);
+      if (result && typeof result === 'object') {
+        for (const [prop, value] of Object.entries(result)) {
+          const cssProp = prop.replace(/([A-Z])/g, '-$1').toLowerCase();
+          htmlEl.style.setProperty(cssProp, String(value ?? ''));
+          newStyles.add(cssProp);
+        }
+      }
+    }
+
+    // Remove styles that were previously applied but are no longer present
+    for (const cssProp of appliedStyles) {
+      if (!newStyles.has(cssProp)) {
+        htmlEl.style.removeProperty(cssProp);
+      }
+    }
+
+    // Update the set of applied styles
+    appliedStyles = newStyles;
+  });
+
+  cleanups.push(cleanup);
+};

package/src/view/directives/text.ts

@@ -0,0 +1,15 @@
+import { effect } from '../../reactive/index';
+import { evaluate } from '../evaluate';
+import type { DirectiveHandler } from '../types';
+
+/**
+ * Handles bq-text directive - sets text content.
+ * @internal
+ */
+export const handleText: DirectiveHandler = (el, expression, context, cleanups) => {
+  const cleanup = effect(() => {
+    const value = evaluate(expression, context);
+    el.textContent = String(value ?? '');
+  });
+  cleanups.push(cleanup);
+};