@bquery/bquery 1.0.0

package/src/motion/index.ts

@@ -0,0 +1,365 @@
+/**
+ * Motion module providing view transitions, FLIP animations, and spring physics.
+ * Designed to work with modern browser APIs while providing smooth fallbacks.
+ *
+ * @module bquery/motion
+ */
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/**
+ * Options for view transitions.
+ */
+export interface TransitionOptions {
+  /** The DOM update function to execute during transition */
+  update: () => void;
+}
+
+/**
+ * Captured element bounds for FLIP animations.
+ */
+export interface ElementBounds {
+  top: number;
+  left: number;
+  width: number;
+  height: number;
+}
+
+/**
+ * FLIP animation configuration options.
+ */
+export interface FlipOptions {
+  /** Animation duration in milliseconds */
+  duration?: number;
+  /** CSS easing function */
+  easing?: string;
+  /** Callback when animation completes */
+  onComplete?: () => void;
+}
+
+/**
+ * Spring physics configuration.
+ */
+export interface SpringConfig {
+  /** Spring stiffness (default: 100) */
+  stiffness?: number;
+  /** Damping coefficient (default: 10) */
+  damping?: number;
+  /** Mass of the object (default: 1) */
+  mass?: number;
+  /** Velocity threshold for completion (default: 0.01) */
+  precision?: number;
+}
+
+/**
+ * Spring instance for animating values.
+ */
+export interface Spring {
+  /** Start animating to target value */
+  to(target: number): Promise<void>;
+  /** Get current animated value */
+  current(): number;
+  /** Stop the animation */
+  stop(): void;
+  /** Subscribe to value changes */
+  onChange(callback: (value: number) => void): () => void;
+}
+
+// ============================================================================
+// View Transitions
+// ============================================================================
+
+/** Extended document type with View Transitions API */
+type DocumentWithTransition = Document & {
+  startViewTransition?: (callback: () => void) => {
+    finished: Promise<void>;
+    ready: Promise<void>;
+    updateCallbackDone: Promise<void>;
+  };
+};
+
+/**
+ * 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) | TransitionOptions
+): Promise<void> => {
+  const update = typeof updateOrOptions === 'function' ? updateOrOptions : updateOrOptions.update;
+
+  const doc = document as DocumentWithTransition;
+
+  if (doc.startViewTransition) {
+    await doc.startViewTransition(() => update()).finished;
+    return;
+  }
+
+  update();
+};
+
+// ============================================================================
+// FLIP Animations
+// ============================================================================
+
+/**
+ * Capture the current bounds of an element for FLIP animation.
+ *
+ * @param element - The DOM element to measure
+ * @returns The element's current position and size
+ */
+export const capturePosition = (element: Element): ElementBounds => {
+  const rect = element.getBoundingClientRect();
+  return {
+    top: rect.top,
+    left: rect.left,
+    width: rect.width,
+    height: rect.height,
+  };
+};
+
+/**
+ * Perform a FLIP (First, Last, Invert, Play) animation.
+ * Animates an element from its captured position to its current position.
+ *
+ * @param element - The element to animate
+ * @param firstBounds - The previously captured bounds
+ * @param options - Animation configuration
+ * @returns Promise that resolves when animation completes
+ *
+ * @example
+ * ```ts
+ * const first = capturePosition(element);
+ * // ... DOM changes that move the element ...
+ * await flip(element, first, { duration: 300 });
+ * ```
+ */
+export const flip = (
+  element: Element,
+  firstBounds: ElementBounds,
+  options: FlipOptions = {}
+): Promise<void> => {
+  const { duration = 300, easing = 'ease-out', onComplete } = options;
+
+  // Last: Get current position
+  const lastBounds = capturePosition(element);
+
+  // Skip animation if element has zero dimensions (avoid division by zero)
+  if (lastBounds.width === 0 || lastBounds.height === 0) {
+    return Promise.resolve();
+  }
+
+  // Invert: Calculate the delta
+  const deltaX = firstBounds.left - lastBounds.left;
+  const deltaY = firstBounds.top - lastBounds.top;
+  const deltaW = firstBounds.width / lastBounds.width;
+  const deltaH = firstBounds.height / lastBounds.height;
+
+  // Skip animation if no change
+  if (deltaX === 0 && deltaY === 0 && deltaW === 1 && deltaH === 1) {
+    return Promise.resolve();
+  }
+
+  const htmlElement = element as HTMLElement;
+
+  // Apply inverted transform
+  htmlElement.style.transform = `translate(${deltaX}px, ${deltaY}px) scale(${deltaW}, ${deltaH})`;
+  htmlElement.style.transformOrigin = 'top left';
+
+  // Force reflow
+  void htmlElement.offsetHeight;
+
+  // Play: Animate back to current position
+  return new Promise((resolve) => {
+    const animation = htmlElement.animate(
+      [
+        {
+          transform: `translate(${deltaX}px, ${deltaY}px) scale(${deltaW}, ${deltaH})`,
+        },
+        { transform: 'translate(0, 0) scale(1, 1)' },
+      ],
+      { duration, easing, fill: 'forwards' }
+    );
+
+    animation.onfinish = () => {
+      htmlElement.style.transform = '';
+      htmlElement.style.transformOrigin = '';
+      onComplete?.();
+      resolve();
+    };
+  });
+};
+
+/**
+ * FLIP helper for animating a list of elements.
+ * Useful for reordering lists with smooth animations.
+ *
+ * @param elements - Array of elements to animate
+ * @param performUpdate - Function that performs the DOM update
+ * @param options - Animation configuration
+ *
+ * @example
+ * ```ts
+ * await flipList(listItems, () => {
+ *   container.appendChild(container.firstChild); // Move first to last
+ * });
+ * ```
+ */
+export const flipList = async (
+  elements: Element[],
+  performUpdate: () => void,
+  options: FlipOptions = {}
+): Promise<void> => {
+  // First: Capture all positions
+  const positions = new Map<Element, ElementBounds>();
+  for (const el of elements) {
+    positions.set(el, capturePosition(el));
+  }
+
+  // Perform DOM update
+  performUpdate();
+
+  // Animate each element
+  const animations = elements.map((el) => {
+    const first = positions.get(el);
+    if (!first) return Promise.resolve();
+    return flip(el, first, options);
+  });
+
+  await Promise.all(animations);
+};
+
+// ============================================================================
+// Spring Physics
+// ============================================================================
+
+/**
+ * Default spring configuration values.
+ */
+const DEFAULT_SPRING_CONFIG: Required<SpringConfig> = {
+  stiffness: 100,
+  damping: 10,
+  mass: 1,
+  precision: 0.01,
+};
+
+/**
+ * Create a spring-based animation for smooth, physics-based motion.
+ *
+ * @param initialValue - Starting value for the spring
+ * @param config - Spring physics configuration
+ * @returns Spring instance for controlling the animation
+ *
+ * @example
+ * ```ts
+ * const x = spring(0, { stiffness: 120, damping: 14 });
+ * x.onChange((value) => {
+ *   element.style.transform = `translateX(${value}px)`;
+ * });
+ * await x.to(100);
+ * ```
+ */
+export const spring = (initialValue: number, config: SpringConfig = {}): Spring => {
+  const { stiffness, damping, mass, precision } = {
+    ...DEFAULT_SPRING_CONFIG,
+    ...config,
+  };
+
+  let current = initialValue;
+  let velocity = 0;
+  let target = initialValue;
+  let animationFrame: number | null = null;
+  let resolvePromise: (() => void) | null = null;
+  const listeners = new Set<(value: number) => void>();
+
+  const notifyListeners = () => {
+    for (const listener of listeners) {
+      listener(current);
+    }
+  };
+
+  const step = () => {
+    // Spring physics calculation
+    const displacement = current - target;
+    const springForce = -stiffness * displacement;
+    const dampingForce = -damping * velocity;
+    const acceleration = (springForce + dampingForce) / mass;
+
+    velocity += acceleration * (1 / 60); // Assuming 60fps
+    current += velocity * (1 / 60);
+
+    notifyListeners();
+
+    // Check if spring has settled
+    if (Math.abs(velocity) < precision && Math.abs(displacement) < precision) {
+      current = target;
+      velocity = 0;
+      animationFrame = null;
+      notifyListeners();
+      resolvePromise?.();
+      resolvePromise = null;
+      return;
+    }
+
+    animationFrame = requestAnimationFrame(step);
+  };
+
+  return {
+    to(newTarget: number): Promise<void> {
+      target = newTarget;
+
+      if (animationFrame !== null) {
+        cancelAnimationFrame(animationFrame);
+      }
+
+      return new Promise((resolve) => {
+        resolvePromise = resolve;
+        animationFrame = requestAnimationFrame(step);
+      });
+    },
+
+    current(): number {
+      return current;
+    },
+
+    stop(): void {
+      if (animationFrame !== null) {
+        cancelAnimationFrame(animationFrame);
+        animationFrame = null;
+      }
+      velocity = 0;
+      resolvePromise?.();
+      resolvePromise = null;
+    },
+
+    onChange(callback: (value: number) => void): () => void {
+      listeners.add(callback);
+      return () => listeners.delete(callback);
+    },
+  };
+};
+
+/**
+ * Preset spring configurations for common use cases.
+ */
+export const springPresets = {
+  /** Gentle, slow-settling spring */
+  gentle: { stiffness: 80, damping: 15 } as SpringConfig,
+  /** Responsive, snappy spring */
+  snappy: { stiffness: 200, damping: 20 } as SpringConfig,
+  /** Bouncy, playful spring */
+  bouncy: { stiffness: 300, damping: 8 } as SpringConfig,
+  /** Stiff, quick spring with minimal overshoot */
+  stiff: { stiffness: 400, damping: 30 } as SpringConfig,
+};

package/src/platform/buckets.ts

@@ -0,0 +1,115 @@
+/**
+ * Storage Buckets API wrapper.
+ * Provides a simplified interface for storing blobs and binary data.
+ * Falls back to IndexedDB when Storage Buckets API is not available.
+ */
+
+/**
+ * Bucket interface for blob storage operations.
+ */
+export interface Bucket {
+  /**
+   * Store a blob in the bucket.
+   * @param key - Unique identifier for the blob
+   * @param data - Blob data to store
+   */
+  put(key: string, data: Blob): Promise<void>;
+
+  /**
+   * Retrieve a blob from the bucket.
+   * @param key - Blob identifier
+   * @returns The stored blob or null if not found
+   */
+  get(key: string): Promise<Blob | null>;
+
+  /**
+   * Remove a blob from the bucket.
+   * @param key - Blob identifier
+   */
+  remove(key: string): Promise<void>;
+
+  /**
+   * List all keys in the bucket.
+   * @returns Array of blob keys
+   */
+  keys(): Promise<string[]>;
+}
+
+/**
+ * IndexedDB-based bucket implementation.
+ * Used as fallback when Storage Buckets API is unavailable.
+ */
+class IndexedDBBucket implements Bucket {
+  private dbPromise: Promise<IDBDatabase> | null = null;
+  private readonly storeName = 'blobs';
+
+  constructor(private readonly bucketName: string) {}
+
+  private openDB(): Promise<IDBDatabase> {
+    if (this.dbPromise) return this.dbPromise;
+
+    const dbName = `bquery-bucket-${this.bucketName}`;
+    this.dbPromise = new Promise((resolve, reject) => {
+      const request = indexedDB.open(dbName, 1);
+
+      request.onupgradeneeded = () => {
+        const db = request.result;
+        if (!db.objectStoreNames.contains(this.storeName)) {
+          db.createObjectStore(this.storeName);
+        }
+      };
+
+      request.onsuccess = () => resolve(request.result);
+      request.onerror = () => reject(request.error);
+    });
+
+    return this.dbPromise;
+  }
+
+  private async withStore<T>(
+    mode: IDBTransactionMode,
+    operation: (store: IDBObjectStore) => IDBRequest<T>
+  ): Promise<T> {
+    const db = await this.openDB();
+    return new Promise((resolve, reject) => {
+      const tx = db.transaction(this.storeName, mode);
+      const store = tx.objectStore(this.storeName);
+      const request = operation(store);
+      request.onsuccess = () => resolve(request.result);
+      request.onerror = () => reject(request.error);
+    });
+  }
+
+  async put(key: string, data: Blob): Promise<void> {
+    await this.withStore('readwrite', (store) => store.put(data, key));
+  }
+
+  async get(key: string): Promise<Blob | null> {
+    const result = await this.withStore<Blob | undefined>('readonly', (store) => store.get(key));
+    return result ?? null;
+  }
+
+  async remove(key: string): Promise<void> {
+    await this.withStore('readwrite', (store) => store.delete(key));
+  }
+
+  async keys(): Promise<string[]> {
+    const result = await this.withStore<IDBValidKey[]>('readonly', (store) => store.getAllKeys());
+    return result.map((key) => String(key));
+  }
+}
+
+/**
+ * Bucket manager for creating and accessing storage buckets.
+ */
+export const buckets = {
+  /**
+   * Open or create a storage bucket.
+   * @param name - Bucket name
+   * @returns Bucket instance for blob operations
+   */
+  async open(name: string): Promise<Bucket> {
+    // Storage Buckets API is experimental; use IndexedDB fallback
+    return new IndexedDBBucket(name);
+  },
+};

package/src/platform/cache.ts

@@ -0,0 +1,130 @@
+/**
+ * Cache Storage API wrapper.
+ * Provides a simplified interface for caching responses and assets.
+ */
+
+/**
+ * Cache handle interface for managing cached resources.
+ */
+export interface CacheHandle {
+  /**
+   * Add a resource to the cache by URL.
+   * Fetches the resource and stores the response.
+   * @param url - URL to fetch and cache
+   */
+  add(url: string): Promise<void>;
+
+  /**
+   * Add multiple resources to the cache.
+   * @param urls - Array of URLs to fetch and cache
+   */
+  addAll(urls: string[]): Promise<void>;
+
+  /**
+   * Store a custom response in the cache.
+   * @param url - URL key for the cached response
+   * @param response - Response object to cache
+   */
+  put(url: string, response: Response): Promise<void>;
+
+  /**
+   * Retrieve a cached response.
+   * @param url - URL to look up
+   * @returns Cached Response or undefined if not found
+   */
+  match(url: string): Promise<Response | undefined>;
+
+  /**
+   * Remove a cached response.
+   * @param url - URL to remove from cache
+   * @returns True if the entry was deleted
+   */
+  remove(url: string): Promise<boolean>;
+
+  /**
+   * Get all cached request URLs.
+   * @returns Array of cached URLs
+   */
+  keys(): Promise<string[]>;
+}
+
+/**
+ * Internal cache handle implementation.
+ */
+class CacheHandleImpl implements CacheHandle {
+  constructor(private readonly cache: Cache) {}
+
+  async add(url: string): Promise<void> {
+    await this.cache.add(url);
+  }
+
+  async addAll(urls: string[]): Promise<void> {
+    await this.cache.addAll(urls);
+  }
+
+  async put(url: string, response: Response): Promise<void> {
+    await this.cache.put(url, response);
+  }
+
+  async match(url: string): Promise<Response | undefined> {
+    return this.cache.match(url);
+  }
+
+  async remove(url: string): Promise<boolean> {
+    return this.cache.delete(url);
+  }
+
+  async keys(): Promise<string[]> {
+    const requests = await this.cache.keys();
+    return requests.map((req) => req.url);
+  }
+}
+
+/**
+ * Cache manager for accessing the Cache Storage API.
+ */
+export const cache = {
+  /**
+   * Check if Cache Storage API is supported.
+   * @returns True if caches API is available
+   */
+  isSupported(): boolean {
+    return 'caches' in window;
+  },
+
+  /**
+   * Open or create a named cache.
+   * @param name - Cache name
+   * @returns CacheHandle for cache operations
+   */
+  async open(name: string): Promise<CacheHandle> {
+    if (!this.isSupported()) {
+      throw new Error('bQuery: Cache Storage API not supported');
+    }
+    const c = await caches.open(name);
+    return new CacheHandleImpl(c);
+  },
+
+  /**
+   * Delete a named cache.
+   * @param name - Cache name to delete
+   * @returns True if the cache was deleted
+   */
+  async delete(name: string): Promise<boolean> {
+    if (!this.isSupported()) {
+      return false;
+    }
+    return caches.delete(name);
+  },
+
+  /**
+   * List all cache names.
+   * @returns Array of cache names
+   */
+  async keys(): Promise<string[]> {
+    if (!this.isSupported()) {
+      return [];
+    }
+    return caches.keys();
+  },
+};

package/src/platform/index.ts

@@ -0,0 +1,18 @@
+/**
+ * Platform module providing unified endpoints for web platform APIs.
+ * Offers consistent, promise-based interfaces with predictable errors.
+ *
+ * @module bquery/platform
+ */
+
+export { buckets } from './buckets';
+export type { Bucket } from './buckets';
+
+export { cache } from './cache';
+export type { CacheHandle } from './cache';
+
+export { notifications } from './notifications';
+export type { NotificationOptions } from './notifications';
+
+export { storage } from './storage';
+export type { IndexedDBOptions, StorageAdapter } from './storage';

package/src/platform/notifications.ts

@@ -0,0 +1,87 @@
+/**
+ * Web Notifications API wrapper.
+ * Provides a simplified interface for browser notifications.
+ */
+
+/**
+ * Notification options matching the standard NotificationOptions interface.
+ */
+export interface NotificationOptions {
+  /** Body text of the notification */
+  body?: string;
+  /** Icon URL for the notification */
+  icon?: string;
+  /** Badge icon for mobile devices */
+  badge?: string;
+  /** Tag for grouping notifications */
+  tag?: string;
+  /** Whether to require user interaction */
+  requireInteraction?: boolean;
+  /** Vibration pattern for mobile devices */
+  vibrate?: number[];
+  /** Additional data attached to the notification */
+  data?: unknown;
+}
+
+/**
+ * Notifications manager providing a clean interface for web notifications.
+ */
+export const notifications = {
+  /**
+   * Check if notifications are supported.
+   * @returns True if Notification API is available
+   */
+  isSupported(): boolean {
+    return 'Notification' in window;
+  },
+
+  /**
+   * Get current permission status.
+   * @returns Current permission state
+   */
+  getPermission(): NotificationPermission {
+    if (!this.isSupported()) return 'denied';
+    return Notification.permission;
+  },
+
+  /**
+   * Request notification permission from the user.
+   * @returns Promise resolving to the permission result
+   */
+  async requestPermission(): Promise<NotificationPermission> {
+    if (!this.isSupported()) {
+      return 'denied';
+    }
+
+    if (Notification.permission === 'granted') {
+      return 'granted';
+    }
+
+    if (Notification.permission === 'denied') {
+      return 'denied';
+    }
+
+    return Notification.requestPermission();
+  },
+
+  /**
+   * Send a notification.
+   * Requires 'granted' permission.
+   * @param title - Notification title
+   * @param options - Optional notification settings
+   * @returns The Notification instance or null if not permitted
+   */
+  send(title: string, options?: NotificationOptions): Notification | null {
+    if (!this.isSupported()) {
+      console.warn('bQuery: Notifications not supported in this browser');
+      return null;
+    }
+
+    if (Notification.permission !== 'granted') {
+      console.warn('bQuery: Notification permission not granted');
+      return null;
+    }
+
+    return new Notification(title, options);
+  },
+};