@bquery/bquery 1.2.0 → 1.4.0

package/src/core/utils/type-guards.ts

@@ -0,0 +1,112 @@
+/**
+ * Type guard helpers.
+ *
+ * @module bquery/core/utils/type-guards
+ */
+
+/**
+ * Checks if a value is a DOM Element.
+ *
+ * @param value - The value to check
+ * @returns True if the value is an Element
+ */
+export function isElement(value: unknown): value is Element {
+  return typeof Element !== 'undefined' && value instanceof 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
+ */
+export function isCollection(value: unknown): value is { elements: Element[] } {
+  return Boolean(value && typeof value === 'object' && 'elements' in (value as object));
+}
+
+/**
+ * Checks if a value is a function.
+ *
+ * @param value - The value to check
+ * @returns True if the value is a function
+ */
+export function isFunction(value: unknown): value is (...args: unknown[]) => unknown {
+  return typeof value === 'function';
+}
+
+/**
+ * Checks if a value is a string.
+ *
+ * @param value - The value to check
+ * @returns True if the value is a string
+ */
+export function isString(value: unknown): value is string {
+  return typeof value === '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
+ */
+export function isNumber(value: unknown): value is number {
+  return typeof value === 'number' && !Number.isNaN(value);
+}
+
+/**
+ * Checks if a value is a boolean.
+ *
+ * @param value - The value to check
+ * @returns True if the value is a boolean
+ */
+export function isBoolean(value: unknown): value is boolean {
+  return typeof value === '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
+ */
+export function isArray<T = unknown>(value: unknown): value is T[] {
+  return Array.isArray(value);
+}
+
+/**
+ * Checks if a value is a Date instance.
+ *
+ * @param value - The value to check
+ * @returns True if the value is a Date
+ */
+export function isDate(value: unknown): value is Date {
+  return value instanceof Date;
+}
+
+/**
+ * Checks if a value is a Promise-like object.
+ *
+ * @param value - The value to check
+ * @returns True if the value is a Promise-like object
+ */
+export function isPromise<T = unknown>(value: unknown): value is Promise<T> {
+  return Boolean(
+    value &&
+    (value instanceof Promise ||
+      (typeof value === 'object' &&
+        'then' in (value as object) &&
+        typeof (value as { then?: unknown }).then === 'function'))
+  );
+}
+
+/**
+ * Checks if a value is a non-null object.
+ *
+ * @param value - The value to check
+ * @returns True if the value is an object
+ */
+export function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null;
+}

package/src/full.ts

@@ -1,150 +1,187 @@
-/**
- * bQuery.js — Full Bundle
- *
- * This is the complete bundle containing all modules for CDN usage.
- * Use this when you want all features without tree-shaking concerns.
- *
- * @module bquery/full
- *
- * @example CDN Usage (ES Modules)
- * ```html
- * <script type="module">
- *   import { $, signal, component } from 'https://unpkg.com/bquery@1/dist/full.es.mjs';
- *
- *   const count = signal(0);
- *   $('#counter').text(count.value);
- * </script>
- * ```
- *
- * @example CDN Usage (UMD/Global)
- * ```html
- * <script src="https://unpkg.com/bquery@1/dist/full.umd.js"></script>
- * <script>
- *   const { $, signal } = bQuery;
- *   const count = signal(0);
- * </script>
- * ```
- *
- * @example CDN Usage (IIFE)
- * ```html
- * <script src="https://unpkg.com/bquery@1/dist/full.iife.js"></script>
- * <script>
- *   // bQuery is available as a global variable
- *   const { $, $$ } = bQuery;
- * </script>
- * ```
- */
-
-// ============================================================================
-// Core Module: Selectors, DOM operations, events, utilities
-// ============================================================================
-export { $, $$, BQueryCollection, BQueryElement, utils } from './core/index';
-
-// ============================================================================
-// Reactive Module: Signals, computed values, effects, batching
-// ============================================================================
-export {
-  Computed,
-  Signal,
-  batch,
-  computed,
-  effect,
-  isComputed,
-  isSignal,
-  persistedSignal,
-  readonly,
-  signal,
-  untrack,
-  watch,
-} from './reactive/index';
-export type { CleanupFn, Observer, ReadonlySignal } from './reactive/index';
-
-// ============================================================================
-// Component Module: Web Components helper with Shadow DOM
-// ============================================================================
-export { component, html, safeHtml } from './component/index';
-export type { ComponentDefinition, PropDefinition } from './component/index';
-
-// ============================================================================
-// Motion Module: View transitions, FLIP animations, springs
-// ============================================================================
-export { capturePosition, flip, flipList, spring, springPresets, transition } from './motion/index';
-export type {
-  ElementBounds,
-  FlipOptions,
-  Spring,
-  SpringConfig,
-  TransitionOptions,
-} from './motion/index';
-
-// ============================================================================
-// Security Module: Sanitization, CSP compatibility, Trusted Types
-// ============================================================================
-export {
-  createTrustedHtml,
-  escapeHtml,
-  generateNonce,
-  getTrustedTypesPolicy,
-  hasCSPDirective,
-  isTrustedTypesSupported,
-  sanitize,
-  sanitizeHtml,
-  stripTags,
-} from './security/index';
-export type { SanitizeOptions } from './security/index';
-
-// ============================================================================
-// Platform Module: Storage, buckets, notifications, cache
-// ============================================================================
-export { buckets, cache, notifications, storage } from './platform/index';
-export type {
-  Bucket,
-  CacheHandle,
-  IndexedDBOptions,
-  NotificationOptions,
-  StorageAdapter,
-} from './platform/index';
-
-// ============================================================================
-// Router Module: SPA routing, navigation guards, lazy loading
-// ============================================================================
-export {
-  back,
-  createRouter,
-  currentRoute,
-  forward,
-  interceptLinks,
-  isActive,
-  isActiveSignal,
-  link,
-  navigate,
-  resolve,
-} from './router/index';
-export type {
-  NavigationGuard,
-  Route,
-  RouteDefinition,
-  Router,
-  RouterOptions,
-} from './router/index';
-
-// ============================================================================
-// Store Module: Signal-based state management
-// ============================================================================
-export {
-  createPersistedStore,
-  createStore,
-  destroyStore,
-  getStore,
-  listStores,
-  mapActions,
-  mapState,
-  registerPlugin,
-} from './store/index';
-export type { StateFactory, Store, StoreDefinition, StorePlugin } from './store/index';
-
-// ============================================================================
-// View Module: Declarative DOM bindings without compiler
-// ============================================================================
-export { createTemplate, mount } from './view/index';
-export type { BindingContext, MountOptions, View } from './view/index';
+/**
+ * bQuery.js — Full Bundle
+ *
+ * This is the complete bundle containing all modules for CDN usage.
+ * Use this when you want all features without tree-shaking concerns.
+ *
+ * @module bquery/full
+ *
+ * @example CDN Usage (ES Modules)
+ * ```html
+ * <script type="module">
+ *   import { $, signal, component } from 'https://unpkg.com/bquery@1/dist/full.es.mjs';
+ *
+ *   const count = signal(0);
+ *   $('#counter').text(count.value);
+ * </script>
+ * ```
+ *
+ * @example CDN Usage (UMD/Global)
+ * ```html
+ * <script src="https://unpkg.com/bquery@1/dist/full.umd.js"></script>
+ * <script>
+ *   const { $, signal } = bQuery;
+ *   const count = signal(0);
+ * </script>
+ * ```
+ *
+ * @example CDN Usage (IIFE)
+ * ```html
+ * <script src="https://unpkg.com/bquery@1/dist/full.iife.js"></script>
+ * <script>
+ *   // bQuery is available as a global variable
+ *   const { $, $$ } = bQuery;
+ * </script>
+ * ```
+ */
+
+// ============================================================================
+// Core Module: Selectors, DOM operations, events, utilities
+// ============================================================================
+export { $, $$, BQueryCollection, BQueryElement, utils } from './core/index';
+
+// ============================================================================
+// Reactive Module: Signals, computed values, effects, batching
+// ============================================================================
+export {
+  Computed,
+  Signal,
+  batch,
+  computed,
+  effect,
+  isComputed,
+  isSignal,
+  persistedSignal,
+  readonly,
+  signal,
+  untrack,
+  watch,
+} from './reactive/index';
+export type { CleanupFn, Observer, ReadonlySignal } from './reactive/index';
+
+// ============================================================================
+// Component Module: Web Components helper with Shadow DOM
+// ============================================================================
+export { component, html, safeHtml } from './component/index';
+export type { ComponentDefinition, PropDefinition } from './component/index';
+
+// ============================================================================
+// Motion Module: View transitions, FLIP animations, springs
+// ============================================================================
+export {
+  animate,
+  capturePosition,
+  easeInCubic,
+  easeInOutCubic,
+  easeInOutQuad,
+  easeInQuad,
+  easeOutBack,
+  easeOutCubic,
+  easeOutExpo,
+  easeOutQuad,
+  easingPresets,
+  flip,
+  flipElements,
+  flipList,
+  keyframePresets,
+  linear,
+  prefersReducedMotion,
+  scrollAnimate,
+  sequence,
+  spring,
+  springPresets,
+  stagger,
+  timeline,
+  transition,
+} from './motion/index';
+export type {
+  AnimateOptions,
+  EasingFunction,
+  ElementBounds,
+  FlipGroupOptions,
+  FlipOptions,
+  ScrollAnimateCleanup,
+  ScrollAnimateOptions,
+  SequenceOptions,
+  SequenceStep,
+  Spring,
+  SpringConfig,
+  StaggerFunction,
+  StaggerOptions,
+  TimelineConfig,
+  TimelineControls,
+  TimelineStep,
+  TransitionOptions,
+} from './motion/index';
+
+// ============================================================================
+// Security Module: Sanitization, CSP compatibility, Trusted Types
+// ============================================================================
+export {
+  createTrustedHtml,
+  escapeHtml,
+  generateNonce,
+  getTrustedTypesPolicy,
+  hasCSPDirective,
+  isTrustedTypesSupported,
+  sanitize,
+  sanitizeHtml,
+  stripTags,
+} from './security/index';
+export type { SanitizeOptions } from './security/index';
+
+// ============================================================================
+// Platform Module: Storage, buckets, notifications, cache
+// ============================================================================
+export { buckets, cache, notifications, storage } from './platform/index';
+export type {
+  Bucket,
+  CacheHandle,
+  IndexedDBOptions,
+  NotificationOptions,
+  StorageAdapter,
+} from './platform/index';
+
+// ============================================================================
+// Router Module: SPA routing, navigation guards, lazy loading
+// ============================================================================
+export {
+  back,
+  createRouter,
+  currentRoute,
+  forward,
+  interceptLinks,
+  isActive,
+  isActiveSignal,
+  link,
+  navigate,
+  resolve,
+} from './router/index';
+export type {
+  NavigationGuard,
+  Route,
+  RouteDefinition,
+  Router,
+  RouterOptions,
+} from './router/index';
+
+// ============================================================================
+// Store Module: Signal-based state management
+// ============================================================================
+export {
+  createPersistedStore,
+  createStore,
+  destroyStore,
+  getStore,
+  listStores,
+  mapActions,
+  mapState,
+  registerPlugin,
+} from './store/index';
+export type { StateFactory, Store, StoreDefinition, StorePlugin } from './store/index';
+
+// ============================================================================
+// View Module: Declarative DOM bindings without compiler
+// ============================================================================
+export { createTemplate, mount } from './view/index';
+export type { BindingContext, MountOptions, View } from './view/index';

package/src/index.ts

@@ -1,36 +1,36 @@
-/**
- * bQuery.js — The jQuery for the Modern Web Platform
- *
- * A zero-build, TypeScript-first library that bridges vanilla JavaScript
- * and build-step frameworks with modern features.
- *
- * @module bquery
- * @see https://github.com/bquery/bquery
- */
-
-// Core module: selectors, DOM ops, events, utils
-export * from './core/index';
-
-// Reactive module: signals, computed, effects, binding
-export * from './reactive/index';
-
-// Component module: Web Components helper
-export * from './component/index';
-
-// Motion module: view transitions, FLIP, springs
-export * from './motion/index';
-
-// Security module: sanitizer, CSP, Trusted Types
-export * from './security/index';
-
-// Platform module: storage, buckets, notifications, cache
-export * from './platform/index';
-
-// Router module: SPA routing, navigation guards
-export * from './router/index';
-
-// Store module: state management with signals
-export * from './store/index';
-
-// View module: declarative DOM bindings
-export * from './view/index';
+/**
+ * bQuery.js — The jQuery for the Modern Web Platform
+ *
+ * A zero-build, TypeScript-first library that bridges vanilla JavaScript
+ * and build-step frameworks with modern features.
+ *
+ * @module bquery
+ * @see https://github.com/bquery/bquery
+ */
+
+// Core module: selectors, DOM ops, events, utils
+export * from './core/index';
+
+// Reactive module: signals, computed, effects, binding
+export * from './reactive/index';
+
+// Component module: Web Components helper
+export * from './component/index';
+
+// Motion module: view transitions, FLIP, springs
+export * from './motion/index';
+
+// Security module: sanitizer, CSP, Trusted Types
+export * from './security/index';
+
+// Platform module: storage, buckets, notifications, cache
+export * from './platform/index';
+
+// Router module: SPA routing, navigation guards
+export * from './router/index';
+
+// Store module: state management with signals
+export * from './store/index';
+
+// View module: declarative DOM bindings
+export * from './view/index';

package/src/motion/animate.ts

@@ -0,0 +1,113 @@
+/**
+ * Web Animations helpers.
+ *
+ * @module bquery/motion
+ */
+
+import { prefersReducedMotion } from './reduced-motion';
+import type { AnimateOptions } from './types';
+
+/** @internal */
+const isStyleValue = (value: unknown): value is string | number =>
+  typeof value === 'string' || typeof value === 'number';
+
+/**
+ * Convert camelCase property names to kebab-case for CSS.
+ * @internal
+ */
+const toKebabCase = (str: string): string => {
+  return str.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`);
+};
+
+/** @internal */
+export const applyFinalKeyframeStyles = (
+  element: Element,
+  keyframes: Keyframe[] | PropertyIndexedKeyframes
+): void => {
+  const htmlElement = element as HTMLElement;
+  const style = htmlElement.style;
+
+  if (Array.isArray(keyframes)) {
+    const last = keyframes[keyframes.length - 1];
+    if (!last) return;
+    for (const [prop, value] of Object.entries(last)) {
+      if (prop === 'offset' || prop === 'easing' || prop === 'composite') continue;
+      if (isStyleValue(value)) {
+        // Convert camelCase to kebab-case for CSS properties
+        const cssProp = prop.startsWith('--') ? prop : toKebabCase(prop);
+        style.setProperty(cssProp, String(value));
+      }
+    }
+    return;
+  }
+
+  for (const [prop, value] of Object.entries(keyframes)) {
+    if (prop === 'offset' || prop === 'easing' || prop === 'composite') continue;
+    const finalValue = Array.isArray(value) ? value[value.length - 1] : value;
+    if (isStyleValue(finalValue)) {
+      // Convert camelCase to kebab-case for CSS properties
+      const cssProp = prop.startsWith('--') ? prop : toKebabCase(prop);
+      style.setProperty(cssProp, String(finalValue));
+    }
+  }
+};
+
+/**
+ * Animate an element using the Web Animations API with reduced-motion fallback.
+ *
+ * @param element - Element to animate
+ * @param config - Animation configuration
+ * @returns Promise that resolves when animation completes
+ *
+ * @example
+ * ```ts
+ * await animate(element, {
+ *   keyframes: [{ opacity: 0 }, { opacity: 1 }],
+ *   options: { duration: 200, easing: 'ease-out' },
+ * });
+ * ```
+ */
+export const animate = (element: Element, config: AnimateOptions): Promise<void> => {
+  const { keyframes, options, commitStyles = true, respectReducedMotion = true, onFinish } = config;
+
+  if (respectReducedMotion && prefersReducedMotion()) {
+    if (commitStyles) {
+      applyFinalKeyframeStyles(element, keyframes);
+    }
+    onFinish?.();
+    return Promise.resolve();
+  }
+
+  const htmlElement = element as HTMLElement;
+  if (typeof htmlElement.animate !== 'function') {
+    if (commitStyles) {
+      applyFinalKeyframeStyles(element, keyframes);
+    }
+    onFinish?.();
+    return Promise.resolve();
+  }
+
+  return new Promise((resolve) => {
+    const animation = htmlElement.animate(keyframes, options);
+    let finalized = false;
+    const finalize = () => {
+      if (finalized) return;
+      finalized = true;
+      if (commitStyles) {
+        if (typeof animation.commitStyles === 'function') {
+          animation.commitStyles();
+        } else {
+          applyFinalKeyframeStyles(element, keyframes);
+        }
+      }
+      animation.cancel();
+      onFinish?.();
+      resolve();
+    };
+
+    animation.onfinish = finalize;
+    if (animation.finished) {
+      animation.finished.then(finalize).catch(finalize);
+    }
+  });
+};

package/src/motion/easing.ts

@@ -0,0 +1,40 @@
+/**
+ * Easing helpers.
+ *
+ * @module bquery/motion
+ */
+
+import type { EasingFunction } from './types';
+
+const clamp = (value: number) => Math.min(1, Math.max(0, value));
+
+export const linear: EasingFunction = (t) => clamp(t);
+export const easeInQuad: EasingFunction = (t) => clamp(t * t);
+export const easeOutQuad: EasingFunction = (t) => clamp(1 - (1 - t) * (1 - t));
+export const easeInOutQuad: EasingFunction = (t) =>
+  clamp(t < 0.5 ? 2 * t * t : 1 - Math.pow(-2 * t + 2, 2) / 2);
+export const easeInCubic: EasingFunction = (t) => clamp(t * t * t);
+export const easeOutCubic: EasingFunction = (t) => clamp(1 - Math.pow(1 - t, 3));
+export const easeInOutCubic: EasingFunction = (t) =>
+  clamp(t < 0.5 ? 4 * t * t * t : 1 - Math.pow(-2 * t + 2, 3) / 2);
+export const easeOutBack: EasingFunction = (t) => {
+  const c1 = 1.70158;
+  const c3 = c1 + 1;
+  return clamp(1 + c3 * Math.pow(t - 1, 3) + c1 * Math.pow(t - 1, 2));
+};
+export const easeOutExpo: EasingFunction = (t) => clamp(t === 1 ? 1 : 1 - Math.pow(2, -10 * t));
+
+/**
+ * Named easing presets.
+ */
+export const easingPresets = {
+  linear,
+  easeInQuad,
+  easeOutQuad,
+  easeInOutQuad,
+  easeInCubic,
+  easeOutCubic,
+  easeInOutCubic,
+  easeOutBack,
+  easeOutExpo,
+};