@bquery/bquery 1.5.0 → 1.7.0

package/src/component/html.ts

@@ -1,53 +1,153 @@
-/**
- * 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])}`, '');
-};
+import {
+  isTrustedHtml,
+  type SanitizedHtml,
+  toSanitizedHtml,
+  unwrapTrustedHtml,
+} from '../security/trusted-html';
+const BOOLEAN_ATTRIBUTE_MARKER: unique symbol = Symbol('bquery.booleanAttribute');
+const BOOLEAN_ATTRIBUTE_NAME = /^[^\0-\x20"'/>=]+$/;
+
+/**
+ * Public shape of a boolean HTML attribute created by {@link bool}.
+ *
+ * This type is returned from {@link bool} and can be interpolated into
+ * {@link html} / {@link safeHtml} templates to conditionally include or omit
+ * an attribute by name. The internal marker property used for runtime checks
+ * remains private and is not part of the public API.
+ *
+ * @example
+ * ```ts
+ * const disabled = bool('disabled', isDisabled);
+ * const button = html`<button ${disabled}>Click</button>`;
+ * ```
+ */
+export interface BooleanAttribute {
+  readonly enabled: boolean;
+  readonly name: string;
+}
+
+interface BooleanAttributeValue extends BooleanAttribute {
+  readonly [BOOLEAN_ATTRIBUTE_MARKER]: true;
+}
+
+const isBooleanAttributeValue = (value: unknown): value is BooleanAttributeValue => {
+  if (typeof value !== 'object' || value === null) {
+    return false;
+  }
+
+  const candidate = value as Partial<BooleanAttributeValue>;
+  return (
+    candidate[BOOLEAN_ATTRIBUTE_MARKER] === true &&
+    typeof candidate.enabled === 'boolean' &&
+    typeof candidate.name === 'string'
+  );
+};
+
+const stringifyTemplateValue = (value: unknown): string => {
+  if (isBooleanAttributeValue(value)) {
+    return value.enabled ? value.name : '';
+  }
+
+  return String(value ?? '');
+};
+
+const escapeMap: Record<string, string> = {
+  '&': '&amp;',
+  '<': '&lt;',
+  '>': '&gt;',
+  '"': '&quot;',
+  "'": '&#x27;',
+  '`': '&#x60;',
+};
+
+const escapeTemplateValue = (value: unknown): string => {
+  if (isBooleanAttributeValue(value)) {
+    return value.enabled ? value.name : '';
+  }
+
+  return stringifyTemplateValue(value).replace(/[&<>"'`]/g, (char) => escapeMap[char]);
+};
+
+/**
+ * Creates a boolean-attribute marker for the {@link html} and {@link safeHtml} template tags.
+ *
+ * When the condition is truthy, the attribute name is rendered without a value.
+ * When the condition is falsy, an empty string is rendered and any surrounding
+ * template-literal whitespace is preserved.
+ *
+ * @param name - HTML attribute name to emit
+ * @param enabled - Whether the boolean attribute should be present
+ * @returns Internal marker consumed by template tags
+ *
+ * @example
+ * ```ts
+ * html`<button ${bool('disabled', isDisabled)}>Save</button>`;
+ * // Result when isDisabled = true: '<button disabled>Save</button>'
+ * ```
+ */
+export const bool = (name: string, enabled: unknown): BooleanAttribute => {
+  if (!BOOLEAN_ATTRIBUTE_NAME.test(name)) {
+    throw new TypeError(`Invalid boolean attribute name: ${name}`);
+  }
+
+  const attribute: BooleanAttributeValue = {
+    [BOOLEAN_ATTRIBUTE_MARKER]: true,
+    enabled: Boolean(enabled),
+    name,
+  };
+
+  return Object.freeze(attribute);
+};
+
+/**
+ * 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}${stringifyTemplateValue(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 Branded escaped HTML string safe for bQuery template composition
+ *
+ * @example
+ * ```ts
+ * const userInput = '<script>alert("xss")</script>';
+ * const safe = safeHtml`<div>${userInput}</div>`;
+ * // Result: '<div>&lt;script&gt;alert(&quot;xss&quot;)&lt;/script&gt;</div>'
+ * ```
+ */
+export const safeHtml = (strings: TemplateStringsArray, ...values: unknown[]): SanitizedHtml => {
+  const escape = (value: unknown): string => {
+    if (isTrustedHtml(value)) return unwrapTrustedHtml(value);
+    return escapeTemplateValue(value);
+  };
+
+  return toSanitizedHtml(
+    strings.reduce(
+      (acc, part, index) => `${acc}${part}${index < values.length ? escape(values[index]) : ''}`,
+      ''
+    )
+  );
+};

package/src/component/index.ts

@@ -36,7 +36,17 @@
  */
 
 export { component, defineComponent } from './component';
-export { html, safeHtml } from './html';
+export { bool, html, safeHtml } from './html';
 export { registerDefaultComponents } from './library';
+export { useComputed, useEffect, useSignal } from './scope';
 export type { DefaultComponentLibraryOptions, RegisteredDefaultComponents } from './library';
-export type { ComponentDefinition, ComponentRenderContext, PropDefinition } from './types';
+export type {
+  AttributeChange,
+  ComponentDefinition,
+  ComponentRenderContext,
+  ComponentStateKey,
+  ComponentSignalLike,
+  ComponentSignals,
+  PropDefinition,
+  ShadowMode,
+} from './types';

package/src/component/library.ts

@@ -87,20 +87,25 @@ const storeHandler = (element: HTMLElement, key: string, value: EventListener):
   handlerStore.set(element, handlers);
 };
 
-const getShadowLabelText = (element: HTMLElement): string => {
-  return element.shadowRoot?.querySelector('.label')?.textContent ?? '';
-};
-
 /**
  * Detect a value-only input update, patch the live control in place, and
  * return whether the component can skip a full shadow DOM re-render.
  *
  * @param element - The host custom element whose shadow DOM is being updated
- * @param props - The next reflected input props for the pending update
+ * @param newProps - The next reflected input props for the pending update
+ * @param oldProps - The previous reflected input props from the last render
  */
 const canSkipInputRender = (
   element: HTMLElement,
-  props: {
+  newProps: {
+    label: string;
+    type: string;
+    value: string;
+    placeholder: string;
+    name: string;
+    disabled: boolean;
+  },
+  oldProps: {
     label: string;
     type: string;
     value: string;
@@ -109,17 +114,29 @@ const canSkipInputRender = (
     disabled: boolean;
   }
 ): boolean => {
-  const control = element.shadowRoot?.querySelector('input.control') as HTMLInputElement | null;
+  if (oldProps.label !== newProps.label) return false;
+  if (oldProps.type !== newProps.type) return false;
+  if (oldProps.placeholder !== newProps.placeholder) return false;
+  if (oldProps.name !== newProps.name) return false;
+  if (oldProps.disabled !== newProps.disabled) return false;
+
+  // Verify shadow DOM still matches expected non-value props before skipping re-render
+  const shadowRoot = element.shadowRoot;
+  if (!shadowRoot) return false;
+
+  const labelEl = shadowRoot.querySelector('.label');
+  if ((labelEl?.textContent ?? '') !== newProps.label) return false;
+
+  const control = shadowRoot.querySelector('input.control') as HTMLInputElement | null;
   if (!control) return false;
 
-  if (getShadowLabelText(element) !== props.label) return false;
-  if ((control.getAttribute('type') ?? 'text') !== props.type) return false;
-  if ((control.getAttribute('placeholder') ?? '') !== props.placeholder) return false;
-  if ((control.getAttribute('name') ?? '') !== props.name) return false;
-  if (control.disabled !== props.disabled) return false;
+  if (control.type !== newProps.type) return false;
+  if (control.placeholder !== newProps.placeholder) return false;
+  if (control.name !== newProps.name) return false;
+  if (control.disabled !== newProps.disabled) return false;
 
-  if (control.value !== props.value) {
-    control.value = props.value;
+  if (control.value !== newProps.value) {
+    control.value = newProps.value;
   }
 
   return true;
@@ -130,11 +147,20 @@ const canSkipInputRender = (
  * return whether the component can skip a full shadow DOM re-render.
  *
  * @param element - The host custom element whose shadow DOM is being updated
- * @param props - The next reflected textarea props for the pending update
+ * @param newProps - The next reflected textarea props for the pending update
+ * @param oldProps - The previous reflected textarea props from the last render
  */
 const canSkipTextareaRender = (
   element: HTMLElement,
-  props: {
+  newProps: {
+    label: string;
+    value: string;
+    placeholder: string;
+    name: string;
+    rows: number;
+    disabled: boolean;
+  },
+  oldProps: {
     label: string;
     value: string;
     placeholder: string;
@@ -143,19 +169,31 @@ const canSkipTextareaRender = (
     disabled: boolean;
   }
 ): boolean => {
-  const control = element.shadowRoot?.querySelector(
+  if (oldProps.label !== newProps.label) return false;
+  if (oldProps.placeholder !== newProps.placeholder) return false;
+  if (oldProps.name !== newProps.name) return false;
+  if (oldProps.rows !== newProps.rows) return false;
+  if (oldProps.disabled !== newProps.disabled) return false;
+
+  // Verify shadow DOM still matches expected non-value props before skipping re-render
+  const shadowRoot = element.shadowRoot;
+  if (!shadowRoot) return false;
+
+  const labelEl = shadowRoot.querySelector('.label');
+  if ((labelEl?.textContent ?? '') !== newProps.label) return false;
+
+  const control = shadowRoot.querySelector(
     'textarea.control'
   ) as HTMLTextAreaElement | null;
   if (!control) return false;
 
-  if (getShadowLabelText(element) !== props.label) return false;
-  if ((control.getAttribute('placeholder') ?? '') !== props.placeholder) return false;
-  if ((control.getAttribute('name') ?? '') !== props.name) return false;
-  if (control.getAttribute('rows') !== String(props.rows)) return false;
-  if (control.disabled !== props.disabled) return false;
+  if (control.placeholder !== newProps.placeholder) return false;
+  if (control.name !== newProps.name) return false;
+  if (Number(control.rows) !== newProps.rows) return false;
+  if (control.disabled !== newProps.disabled) return false;
 
-  if (control.value !== props.value) {
-    control.value = props.value;
+  if (control.value !== newProps.value) {
+    control.value = newProps.value;
   }
   return true;
 };
@@ -328,8 +366,8 @@ export const registerDefaultComponents = (
      * Skip the full shadow DOM re-render when only the reflected input value
      * changed, because the live control has already been patched in place.
      */
-    beforeUpdate(props) {
-      if (canSkipInputRender(this, props)) {
+    beforeUpdate(newProps, oldProps) {
+      if (canSkipInputRender(this, newProps, oldProps)) {
         return false;
       }
       return true;
@@ -399,8 +437,8 @@ export const registerDefaultComponents = (
      * Skip the full shadow DOM re-render when only the reflected textarea value
      * changed, because the live control has already been patched in place.
      */
-    beforeUpdate(props) {
-      if (canSkipTextareaRender(this, props)) {
+    beforeUpdate(newProps, oldProps) {
+      if (canSkipTextareaRender(this, newProps, oldProps)) {
         return false;
       }
       return true;

package/src/component/scope.ts

@@ -0,0 +1,212 @@
+/**
+ * Component-scoped reactive primitives.
+ *
+ * Provides `useSignal`, `useComputed`, and `useEffect` that automatically
+ * dispose when their owning component disconnects from the DOM.
+ *
+ * @module bquery/component
+ */
+
+import type { Computed } from '../reactive/computed';
+import { computed } from '../reactive/computed';
+import { detectDevEnvironment } from '../core/env';
+import type { Signal } from '../reactive/core';
+import { signal } from '../reactive/core';
+import { effect } from '../reactive/effect';
+import type { CleanupFn } from '../reactive/index';
+
+/**
+ * Holds disposable resources created inside a component scope.
+ * All registered disposers run when the component disconnects.
+ * @internal
+ */
+export interface ComponentScope {
+  /** Register a cleanup function to run on dispose */
+  addDisposer(fn: CleanupFn): void;
+  /** Dispose all registered resources */
+  dispose(): void;
+}
+
+/** Currently active component scope. @internal */
+let currentScope: ComponentScope | undefined;
+
+/**
+ * Sets the active component scope.
+ * @internal
+ */
+export function setCurrentScope(scope: ComponentScope | undefined): ComponentScope | undefined {
+  const previousScope = currentScope;
+  currentScope = scope;
+  return previousScope;
+}
+
+/**
+ * Returns the active component scope, or undefined if none.
+ * @internal
+ */
+export function getCurrentScope(): ComponentScope | undefined {
+  return currentScope;
+}
+
+/**
+ * Creates a new component scope that tracks disposable resources.
+ * @internal
+ */
+export function createComponentScope(): ComponentScope {
+  const disposers: CleanupFn[] = [];
+
+  return {
+    addDisposer(fn: CleanupFn): void {
+      disposers.push(fn);
+    },
+    dispose(): void {
+      for (const fn of disposers) {
+        try {
+          fn();
+        } catch (error) {
+          if (
+            detectDevEnvironment() &&
+            typeof console !== 'undefined' &&
+            typeof console.error === 'function'
+          ) {
+            console.error('bQuery component: Error disposing scoped resource', error);
+          }
+        }
+      }
+      disposers.length = 0;
+    },
+  };
+}
+
+/**
+ * Creates a reactive signal scoped to the current component.
+ *
+ * The signal is automatically disposed when the component disconnects
+ * from the DOM, removing all subscribers and preventing memory leaks.
+ *
+ * Must be called during a component lifecycle hook such as `connected`,
+ * `beforeMount`, `onAdopted`, or `onAttributeChanged`.
+ *
+ * Do not create scoped primitives from `render()`. Repeated renders can
+ * accumulate render-scoped resources until disconnect; prefer lifecycle hooks.
+ *
+ * @template T - The type of the signal value
+ * @param initialValue - The initial value of the signal
+ * @returns A new Signal instance that auto-disposes with the component
+ * @throws {Error} If called outside a component scope
+ *
+ * @example
+ * ```ts
+ * import { component, html, useSignal } from '@bquery/bquery/component';
+ *
+ * component('my-counter', {
+ *   connected() {
+ *     const count = useSignal(0);
+ *     // count.dispose() is called automatically on disconnect
+ *   },
+ *   render({ state }) {
+ *     return html`<span>${state.count}</span>`;
+ *   },
+ * });
+ * ```
+ */
+export function useSignal<T>(initialValue: T): Signal<T> {
+  const scope = currentScope;
+  if (!scope) {
+    throw new Error(
+      'bQuery component: useSignal() must be called inside a component lifecycle hook. Avoid calling it directly from render()'
+    );
+  }
+  const s = signal(initialValue);
+  scope.addDisposer(() => s.dispose());
+  return s;
+}
+
+/**
+ * Creates a computed value scoped to the current component.
+ *
+ * The computed value's internal effect is automatically cleaned up
+ * when the component disconnects from the DOM.
+ *
+ * Must be called during a component lifecycle hook such as `connected`,
+ * `beforeMount`, `onAdopted`, or `onAttributeChanged`.
+ *
+ * Do not create scoped primitives from `render()`. Repeated renders can
+ * accumulate render-scoped resources until disconnect; prefer lifecycle hooks.
+ *
+ * @template T - The type of the computed value
+ * @param fn - Derivation function that reads reactive sources
+ * @returns A new Computed instance that auto-cleans-up with the component
+ * @throws {Error} If called outside a component scope
+ *
+ * @example
+ * ```ts
+ * import { component, html, useSignal, useComputed } from '@bquery/bquery/component';
+ *
+ * component('my-doubler', {
+ *   connected() {
+ *     const count = useSignal(1);
+ *     const doubled = useComputed(() => count.value * 2);
+ *   },
+ *   render({ state }) {
+ *     return html`<span>${state.doubled}</span>`;
+ *   },
+ * });
+ * ```
+ */
+export function useComputed<T>(fn: () => T): Computed<T> {
+  const scope = currentScope;
+  if (!scope) {
+    throw new Error(
+      'bQuery component: useComputed() must be called inside a component lifecycle hook. Avoid calling it directly from render()'
+    );
+  }
+  const c = computed(fn);
+  scope.addDisposer(() => c.dispose());
+  return c;
+}
+
+/**
+ * Creates a side effect scoped to the current component.
+ *
+ * The effect runs immediately and re-runs when its reactive dependencies
+ * change. It is automatically disposed when the component disconnects
+ * from the DOM.
+ *
+ * Must be called during a component lifecycle hook such as `connected`,
+ * `beforeMount`, `onAdopted`, or `onAttributeChanged`.
+ *
+ * Do not create scoped primitives from `render()`. Repeated renders can
+ * accumulate render-scoped resources until disconnect; prefer lifecycle hooks.
+ *
+ * @param fn - The effect function; may return a cleanup function
+ * @returns A cleanup function to manually stop the effect early
+ * @throws {Error} If called outside a component scope
+ *
+ * @example
+ * ```ts
+ * import { component, useSignal, useEffect } from '@bquery/bquery/component';
+ *
+ * component('my-logger', {
+ *   connected() {
+ *     const count = useSignal(0);
+ *     useEffect(() => {
+ *       console.log('Count changed:', count.value);
+ *       return () => console.log('Cleanup');
+ *     });
+ *   },
+ *   render() { return '<p>Logger</p>'; },
+ * });
+ * ```
+ */
+export function useEffect(fn: () => void | CleanupFn): CleanupFn {
+  const scope = currentScope;
+  if (!scope) {
+    throw new Error(
+      'bQuery component: useEffect() must be called inside a component lifecycle hook. Avoid calling it directly from render()'
+    );
+  }
+  const cleanup = effect(fn);
+  scope.addDisposer(cleanup);
+  return cleanup;
+}