@bquery/bquery 1.5.0 → 1.6.0

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,17 @@ const canSkipInputRender = (
     disabled: boolean;
   }
 ): boolean => {
+  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;
+
   const control = element.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.value !== props.value) {
-    control.value = props.value;
+  if (control.value !== newProps.value) {
+    control.value = newProps.value;
   }
 
   return true;
@@ -130,11 +135,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 +157,19 @@ const canSkipTextareaRender = (
     disabled: boolean;
   }
 ): boolean => {
+  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;
+
   const control = element.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.value !== props.value) {
-    control.value = props.value;
+  if (control.value !== newProps.value) {
+    control.value = newProps.value;
   }
   return true;
 };
@@ -328,8 +342,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 +413,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/types.ts

@@ -4,6 +4,8 @@
  * @module bquery/component
  */
 
+import type { SanitizeOptions } from '../security/types';
+
 /**
  * Defines a single prop's type and configuration.
  *
@@ -43,49 +45,212 @@ export type PropDefinition<T = unknown> = {
   construct?: boolean;
 };
 
+/**
+ * Resolves the concrete runtime state shape exposed by component APIs.
+ *
+ * When no explicit state generic is provided, component state falls back to
+ * an untyped string-keyed record for backwards compatibility.
+ */
+export type ComponentStateShape<
+  TState extends Record<string, unknown> | undefined = undefined,
+> = TState extends Record<string, unknown> ? TState : Record<string, unknown>;
+
+/**
+ * Component state keys are string-based because runtime state access is backed
+ * by plain object properties.
+ */
+export type ComponentStateKey<
+  TState extends Record<string, unknown> | undefined = undefined,
+> =
+  keyof ComponentStateShape<TState> & string;
+
+/**
+ * Public component element instance shape exposed by lifecycle hooks and
+ * `defineComponent()` return values.
+ */
+export type ComponentElement<
+  TState extends Record<string, unknown> | undefined = undefined,
+> = HTMLElement & {
+  /**
+   * Updates a state property and triggers a re-render.
+   *
+   * @param key - The state property key
+   * @param value - The new value
+   */
+  setState<TKey extends ComponentStateKey<TState>>(
+    key: TKey,
+    value: ComponentStateShape<TState>[TKey]
+  ): void;
+  /**
+   * Gets a state property value.
+   *
+   * @param key - The state property key
+   * @returns The current value
+   */
+  getState<TKey extends ComponentStateKey<TState>>(
+    key: TKey
+  ): ComponentStateShape<TState>[TKey];
+  /**
+   * Gets a state property value with an explicit cast for backwards
+   * compatibility with the pre-typed-state API.
+   *
+   * @param key - The state property key
+   * @returns The current value cast to `TResult`
+   */
+  getState<TResult = unknown>(key: string): TResult;
+};
+
+/**
+ * Constructor returned by `defineComponent()`.
+ */
+export type ComponentClass<TState extends Record<string, unknown> | undefined = undefined> =
+  CustomElementConstructor & {
+    new (): ComponentElement<TState>;
+    prototype: ComponentElement<TState>;
+    readonly observedAttributes: string[];
+  };
+
+/**
+ * Minimal reactive source shape supported by component `signals`.
+ *
+ * @template T - Value exposed by the signal-like source
+ */
+export type ComponentSignalLike<T = unknown> = {
+  /** Gets the current reactive value */
+  readonly value: T;
+  /** Gets the current value without dependency tracking */
+  peek(): T;
+};
+
+/**
+ * Named reactive sources that can drive component re-renders.
+ */
+export type ComponentSignals = Record<string, ComponentSignalLike<unknown>>;
+
 /**
  * Render context passed into a component render function.
+ *
+ * @template TProps - Type of the component's props
+ * @template TState - Type of the component's internal state
+ * @template TSignals - Declared reactive sources available during render
  */
-export type ComponentRenderContext<TProps extends Record<string, unknown>> = {
+export type ComponentRenderContext<
+  TProps extends Record<string, unknown>,
+  TState extends Record<string, unknown> | undefined = undefined,
+  TSignals extends ComponentSignals = Record<string, never>,
+> = {
   /** Typed props object populated from attributes */
   props: TProps;
   /** Internal mutable state object */
-  state: Record<string, unknown>;
+  state: ComponentStateShape<TState>;
+  /** External reactive sources subscribed for re-rendering */
+  signals: TSignals;
   /** Emit a custom event from the component */
   emit: (event: string, detail?: unknown) => void;
 };
 
+/**
+ * Describes an observed attribute change that triggered a component update.
+ */
+export type AttributeChange = {
+  /** The observed attribute name */
+  name: string;
+  /** The previous serialized attribute value */
+  oldValue: string | null;
+  /** The next serialized attribute value */
+  newValue: string | null;
+};
+
 /**
  * Complete component definition including props, state, styles, and lifecycle.
  *
  * @template TProps - Type of the component's props
+ * @template TState - Type of the component's internal state
  */
-type ComponentHook<TResult = void> = ((this: HTMLElement) => TResult) | (() => TResult);
-type ComponentHookWithProps<TProps extends Record<string, unknown>, TResult = void> =
-  | ((this: HTMLElement, props: TProps) => TResult)
-  | ((props: TProps) => TResult);
-type ComponentErrorHook = ((this: HTMLElement, error: Error) => void) | ((error: Error) => void);
+/*
+ * Lifecycle hooks use dynamic `this` when declared with method/function syntax.
+ * Arrow functions capture outer scope, so component APIs like `this.getState()`
+ * are only available from method/function syntax.
+ */
+type ComponentSanitizeOptions = Pick<SanitizeOptions, 'allowTags' | 'allowAttributes'>;
+type ComponentHook<
+  TState extends Record<string, unknown> | undefined = undefined,
+  TResult = void,
+> = {
+  (this: ComponentElement<TState>): TResult;
+  (): TResult;
+};
+type ComponentHookWithProps<
+  TProps extends Record<string, unknown>,
+  TState extends Record<string, unknown> | undefined = undefined,
+  TResult = void,
+> = {
+   (this: ComponentElement<TState>, newProps: TProps, oldProps: TProps): TResult;
+   (newProps: TProps, oldProps: TProps): TResult;
+};
+type ComponentUpdatedHook<
+  TState extends Record<string, unknown> | undefined = undefined,
+  TResult = void,
+> = {
+  (this: ComponentElement<TState>, change?: AttributeChange): TResult;
+  (change?: AttributeChange): TResult;
+};
+type ComponentErrorHook<TState extends Record<string, unknown> | undefined = undefined> = {
+  (this: ComponentElement<TState>, error: Error): void;
+  (error: Error): void;
+};
+
+type ComponentStateDefinition<TState extends Record<string, unknown> | undefined = undefined> =
+  TState extends Record<string, unknown>
+    ? {
+        /** Initial internal state */
+        state: TState;
+      }
+    : {
+        /** Initial internal state */
+        state?: Record<string, unknown>;
+      };
+
+type ComponentSignalsDefinition<TSignals extends ComponentSignals = Record<string, never>> =
+  TSignals extends Record<string, never>
+    ? {
+        /** External signals/computed values that should trigger re-renders */
+        signals?: TSignals;
+      }
+    : {
+        /** External signals/computed values that should trigger re-renders */
+        signals: TSignals;
+      };
 
-export type ComponentDefinition<TProps extends Record<string, unknown> = Record<string, unknown>> =
-  {
+export type ComponentDefinition<
+  TProps extends Record<string, unknown> = Record<string, unknown>,
+  TState extends Record<string, unknown> | undefined = undefined,
+  TSignals extends ComponentSignals = Record<string, never>,
+> = ComponentStateDefinition<TState> &
+  ComponentSignalsDefinition<TSignals> & {
     /** 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;
+    /**
+     * Extra sanitizer options merged with the framework base allowlist during render.
+     * Only opt in attributes/tags whose values you control or validate. Sensitive
+     * attributes such as `style` are not value-sanitized and can reintroduce XSS
+     * or UI-redressing risks if used with untrusted input.
+     */
+    sanitize?: ComponentSanitizeOptions;
     /** Lifecycle hook called before the component mounts (before first render) */
-    beforeMount?: ComponentHook;
+    beforeMount?: ComponentHook<TState>;
     /** Lifecycle hook called when component is added to DOM */
-    connected?: ComponentHook;
+    connected?: ComponentHook<TState>;
     /** Lifecycle hook called when component is removed from DOM */
-    disconnected?: ComponentHook;
+    disconnected?: ComponentHook<TState>;
     /** Lifecycle hook called before an update render; return false to prevent */
-    beforeUpdate?: ComponentHookWithProps<TProps, boolean | void>;
-    /** Lifecycle hook called after reactive updates trigger a render */
-    updated?: ComponentHook;
+    beforeUpdate?: ComponentHookWithProps<TProps, TState, boolean | void>;
+    /** Lifecycle hook called after update renders; receives attribute change info when applicable */
+    updated?: ComponentUpdatedHook<TState>;
     /** Error handler for errors during rendering or lifecycle */
-    onError?: ComponentErrorHook;
+    onError?: ComponentErrorHook<TState>;
     /** Render function returning HTML string */
-    render: (context: ComponentRenderContext<TProps>) => string;
+    render: (context: ComponentRenderContext<TProps, TState, TSignals>) => string;
   };

package/src/full.ts

@@ -77,9 +77,14 @@ export type {
 // ============================================================================
 // Component Module: Web Components helper with Shadow DOM
 // ============================================================================
-export { component, html, registerDefaultComponents, safeHtml } from './component/index';
+export { bool, component, html, registerDefaultComponents, safeHtml } from './component/index';
 export type {
+  AttributeChange,
   ComponentDefinition,
+  ComponentRenderContext,
+  ComponentStateKey,
+  ComponentSignalLike,
+  ComponentSignals,
   DefaultComponentLibraryOptions,
   PropDefinition,
   RegisteredDefaultComponents,
@@ -147,8 +152,9 @@ export {
   sanitize,
   sanitizeHtml,
   stripTags,
+  trusted,
 } from './security/index';
-export type { SanitizeOptions } from './security/index';
+export type { SanitizedHtml, SanitizeOptions, TrustedHtml } from './security/index';
 
 // ============================================================================
 // Platform Module: Storage, buckets, notifications, cache

package/src/motion/transition.ts

@@ -1,97 +1,97 @@
-/**
- * View transition helpers.
- *
- * @module bquery/motion
- */
-
-import type { TransitionOptions } from './types';
-import { prefersReducedMotion } from './reduced-motion';
-import { getBqueryConfig } from '../platform/config';
-
-/** Extended document type with View Transitions API */
-type DocumentWithTransition = Document & {
-  startViewTransition?: (callback: () => void | Promise<void>) => {
-    finished: Promise<void>;
-    ready: Promise<void>;
-    updateCallbackDone: Promise<void>;
-    skipTransition?: () => void;
-    types?: {
-      add: (type: string) => void;
-    };
-  };
-};
-
-const sanitizeTokens = (tokens?: string[]): string[] =>
-  (tokens ?? []).map((token) => token.trim()).filter((token) => token.length > 0);
-
-/**
- * Execute a DOM update with view transition animation.
- * Falls back to immediate update when View Transitions API is unavailable.
- *
- * @param updateOrOptions - Update function or options object
- * @returns Promise that resolves when transition completes
- *
- * @example
- * ```ts
- * await transition(() => {
- *   $('#content').text('Updated');
- * });
- * ```
- */
-export const transition = async (
-  updateOrOptions: (() => void | Promise<void>) | TransitionOptions
-): Promise<void> => {
-  const config = getBqueryConfig().transitions;
-  const options: TransitionOptions =
-    typeof updateOrOptions === 'function'
-      ? {
-          update: updateOrOptions,
-          classes: config?.classes,
-          types: config?.types,
-          skipOnReducedMotion: config?.skipOnReducedMotion,
-        }
-      : {
-          ...updateOrOptions,
-          classes: updateOrOptions.classes ?? config?.classes,
-          types: updateOrOptions.types ?? config?.types,
-          skipOnReducedMotion: updateOrOptions.skipOnReducedMotion ?? config?.skipOnReducedMotion,
-        };
-  const update = options.update;
-
-  // SSR/non-DOM environment fallback
-  if (typeof document === 'undefined') {
-    await update();
-    return;
-  }
-
-  const doc = document as DocumentWithTransition;
-  const root = document.documentElement;
-  const classes = sanitizeTokens(options.classes);
-  const types = sanitizeTokens(options.types);
-
-  if (!doc.startViewTransition || (options.skipOnReducedMotion && prefersReducedMotion())) {
-    await update();
-    options.onFinish?.();
-    return;
-  }
-
-  classes.forEach((className: string) => root.classList.add(className));
-
-  try {
-    const viewTransition = doc.startViewTransition(() => update());
-    const transitionTypes = viewTransition.types;
-
-    if (transitionTypes) {
-      for (const type of types) {
-        transitionTypes.add(type);
-      }
-    }
-
-    await viewTransition.ready;
-    options.onReady?.();
-    await viewTransition.finished;
-    options.onFinish?.();
-  } finally {
-    classes.forEach((className: string) => root.classList.remove(className));
-  }
-};
+/**
+ * View transition helpers.
+ *
+ * @module bquery/motion
+ */
+
+import type { TransitionOptions } from './types';
+import { prefersReducedMotion } from './reduced-motion';
+import { getBqueryConfig } from '../platform/config';
+
+/** Extended document type with View Transitions API */
+type DocumentWithTransition = Document & {
+  startViewTransition?: (callback: () => void | Promise<void>) => {
+    finished: Promise<void>;
+    ready: Promise<void>;
+    updateCallbackDone: Promise<void>;
+    skipTransition?: () => void;
+    types?: {
+      add: (type: string) => void;
+    };
+  };
+};
+
+const sanitizeTokens = (tokens?: string[]): string[] =>
+  (tokens ?? []).map((token) => token.trim()).filter((token) => token.length > 0);
+
+/**
+ * Execute a DOM update with view transition animation.
+ * Falls back to immediate update when View Transitions API is unavailable.
+ *
+ * @param updateOrOptions - Update function or options object
+ * @returns Promise that resolves when transition completes
+ *
+ * @example
+ * ```ts
+ * await transition(() => {
+ *   $('#content').text('Updated');
+ * });
+ * ```
+ */
+export const transition = async (
+  updateOrOptions: (() => void | Promise<void>) | TransitionOptions
+): Promise<void> => {
+  const config = getBqueryConfig().transitions;
+  const options: TransitionOptions =
+    typeof updateOrOptions === 'function'
+      ? {
+          update: updateOrOptions,
+          classes: config?.classes,
+          types: config?.types,
+          skipOnReducedMotion: config?.skipOnReducedMotion,
+        }
+      : {
+          ...updateOrOptions,
+          classes: updateOrOptions.classes ?? config?.classes,
+          types: updateOrOptions.types ?? config?.types,
+          skipOnReducedMotion: updateOrOptions.skipOnReducedMotion ?? config?.skipOnReducedMotion,
+        };
+  const update = options.update;
+
+  // SSR/non-DOM environment fallback
+  if (typeof document === 'undefined') {
+    await update();
+    return;
+  }
+
+  const doc = document as DocumentWithTransition;
+  const root = document.documentElement;
+  const classes = sanitizeTokens(options.classes);
+  const types = sanitizeTokens(options.types);
+
+  if (!doc.startViewTransition || (options.skipOnReducedMotion && prefersReducedMotion())) {
+    await update();
+    options.onFinish?.();
+    return;
+  }
+
+  classes.forEach((className: string) => root.classList.add(className));
+
+  try {
+    const viewTransition = doc.startViewTransition(() => update());
+    const transitionTypes = viewTransition.types;
+
+    if (transitionTypes) {
+      for (const type of types) {
+        transitionTypes.add(type);
+      }
+    }
+
+    await viewTransition.ready;
+    options.onReady?.();
+    await viewTransition.finished;
+    options.onFinish?.();
+  } finally {
+    classes.forEach((className: string) => root.classList.remove(className));
+  }
+};