@bquery/bquery 1.6.0 → 1.7.0

package/src/motion/types.ts

@@ -1,208 +1,271 @@
-/**
- * Shared Motion module types.
- *
- * @module bquery/motion
- */
-
-/**
- * Options for view transitions.
- */
-export interface TransitionOptions {
-  /** The DOM update function to execute during transition */
-  update: () => void | Promise<void>;
-  /** Skip the transition when reduced motion is preferred. */
-  skipOnReducedMotion?: boolean;
-  /** Classes applied to the root element while the transition is active. */
-  classes?: string[];
-  /** Transition types added when supported by the browser. */
-  types?: string[];
-  /** Called after the transition becomes ready. */
-  onReady?: () => void;
-  /** Called after the transition finishes. */
-  onFinish?: () => 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;
-}
-
-/**
- * Stagger delay function signature.
- */
-export type StaggerFunction = (index: number, total: number) => number;
-
-/**
- * Extended options for group FLIP animations.
- */
-export interface FlipGroupOptions extends FlipOptions {
-  /** Optional stagger delay function */
-  stagger?: StaggerFunction;
-}
-
-/**
- * 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;
-}
-
-/**
- * Web Animations helper configuration.
- */
-export interface AnimateOptions {
-  /** Keyframes to animate */
-  keyframes: Keyframe[] | PropertyIndexedKeyframes;
-  /** Animation options (duration, easing, etc.) */
-  options?: KeyframeAnimationOptions;
-  /** Commit final styles to the element (default: true) */
-  commitStyles?: boolean;
-  /** Respect prefers-reduced-motion (default: true) */
-  respectReducedMotion?: boolean;
-  /** Callback when animation completes */
-  onFinish?: () => void;
-}
-
-/**
- * Stagger helper configuration.
- */
-export interface StaggerOptions {
-  /** Start delay in milliseconds (default: 0) */
-  start?: number;
-  /** Origin index or keyword (default: 'start') */
-  from?: 'start' | 'center' | 'end' | number;
-  /** Optional easing function for normalized distance */
-  easing?: EasingFunction;
-}
-
-/**
- * Easing function signature.
- */
-export type EasingFunction = (t: number) => number;
-
-/**
- * Sequence step configuration.
- */
-export interface SequenceStep extends AnimateOptions {
-  /** Target element to animate */
-  target: Element;
-}
-
-/**
- * Sequence run configuration.
- */
-export interface SequenceOptions {
-  /** Optional stagger delay between steps */
-  stagger?: StaggerFunction;
-  /** Callback when sequence completes */
-  onFinish?: () => void;
-}
-
-/**
- * Timeline step configuration.
- */
-export interface TimelineStep {
-  /** Target element to animate */
-  target: Element;
-  /** Keyframes to animate */
-  keyframes: Keyframe[] | PropertyIndexedKeyframes;
-  /** Animation options for this step */
-  options?: KeyframeAnimationOptions;
-  /** Absolute or relative start time in milliseconds */
-  at?: number | `+=${number}` | `-=${number}`;
-  /** Optional label for debugging */
-  label?: string;
-}
-
-/**
- * Timeline configuration.
- */
-export interface TimelineConfig {
-  /** Commit final styles when timeline completes (default: true) */
-  commitStyles?: boolean;
-  /** Respect prefers-reduced-motion (default: true) */
-  respectReducedMotion?: boolean;
-  /** Callback when timeline completes */
-  onFinish?: () => void;
-}
-
-/**
- * Timeline controls.
- */
-export interface TimelineControls {
-  /** Play all steps */
-  play(): Promise<void>;
-  /** Pause animations */
-  pause(): void;
-  /** Resume animations */
-  resume(): void;
-  /** Stop and cancel animations */
-  stop(): void;
-  /** Seek to a specific time in milliseconds */
-  seek(time: number): void;
-  /** Add a step to the timeline */
-  add(step: TimelineStep): void;
-  /** Total timeline duration in milliseconds */
-  duration(): number;
-  /** Subscribe to finish events */
-  onFinish(callback: () => void): () => void;
-}
-
-/**
- * Scroll animation configuration.
- */
-export interface ScrollAnimateOptions extends AnimateOptions {
-  /** IntersectionObserver root */
-  root?: Element | Document | null;
-  /** Root margin for observer */
-  rootMargin?: string;
-  /** Intersection thresholds */
-  threshold?: number | number[];
-  /** Trigger only once (default: true) */
-  once?: boolean;
-  /** Callback when element enters the viewport */
-  onEnter?: (element: Element) => void;
-}
-
-/**
- * Cleanup function for scroll animations.
- */
-export type ScrollAnimateCleanup = () => void;
+/**
+ * Shared Motion module types.
+ *
+ * @module bquery/motion
+ */
+
+/**
+ * Options for view transitions.
+ */
+export interface TransitionOptions {
+  /** The DOM update function to execute during transition */
+  update: () => void | Promise<void>;
+  /** Skip the transition when reduced motion is preferred. */
+  skipOnReducedMotion?: boolean;
+  /** Classes applied to the root element while the transition is active. */
+  classes?: string[];
+  /** Transition types added when supported by the browser. */
+  types?: string[];
+  /** Called after the transition becomes ready. */
+  onReady?: () => void;
+  /** Called after the transition finishes. */
+  onFinish?: () => 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;
+}
+
+/**
+ * Stagger delay function signature.
+ */
+export type StaggerFunction = (index: number, total: number) => number;
+
+/**
+ * Extended options for group FLIP animations.
+ */
+export interface FlipGroupOptions extends FlipOptions {
+  /** Optional stagger delay function */
+  stagger?: StaggerFunction;
+}
+
+/**
+ * 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;
+}
+
+/**
+ * Web Animations helper configuration.
+ */
+export interface AnimateOptions {
+  /** Keyframes to animate */
+  keyframes: Keyframe[] | PropertyIndexedKeyframes;
+  /** Animation options (duration, easing, etc.) */
+  options?: KeyframeAnimationOptions;
+  /** Commit final styles to the element (default: true) */
+  commitStyles?: boolean;
+  /** Respect prefers-reduced-motion (default: true) */
+  respectReducedMotion?: boolean;
+  /** Callback when animation completes */
+  onFinish?: () => void;
+}
+
+/**
+ * Stagger helper configuration.
+ */
+export interface StaggerOptions {
+  /** Start delay in milliseconds (default: 0) */
+  start?: number;
+  /** Origin index or keyword (default: 'start') */
+  from?: 'start' | 'center' | 'end' | number;
+  /** Optional easing function for normalized distance */
+  easing?: EasingFunction;
+}
+
+/**
+ * Easing function signature.
+ */
+export type EasingFunction = (t: number) => number;
+
+/**
+ * Sequence step configuration.
+ */
+export interface SequenceStep extends AnimateOptions {
+  /** Target element to animate */
+  target: Element;
+}
+
+/**
+ * Sequence run configuration.
+ */
+export interface SequenceOptions {
+  /** Optional stagger delay between steps */
+  stagger?: StaggerFunction;
+  /** Callback when sequence completes */
+  onFinish?: () => void;
+}
+
+/**
+ * Timeline step configuration.
+ */
+export interface TimelineStep {
+  /** Target element to animate */
+  target: Element;
+  /** Keyframes to animate */
+  keyframes: Keyframe[] | PropertyIndexedKeyframes;
+  /** Animation options for this step */
+  options?: KeyframeAnimationOptions;
+  /** Absolute or relative start time in milliseconds */
+  at?: number | `+=${number}` | `-=${number}`;
+  /** Optional label for debugging */
+  label?: string;
+}
+
+/**
+ * Timeline configuration.
+ */
+export interface TimelineConfig {
+  /** Commit final styles when timeline completes (default: true) */
+  commitStyles?: boolean;
+  /** Respect prefers-reduced-motion (default: true) */
+  respectReducedMotion?: boolean;
+  /** Callback when timeline completes */
+  onFinish?: () => void;
+}
+
+/**
+ * Timeline controls.
+ */
+export interface TimelineControls {
+  /** Play all steps */
+  play(): Promise<void>;
+  /** Pause animations */
+  pause(): void;
+  /** Resume animations */
+  resume(): void;
+  /** Stop and cancel animations */
+  stop(): void;
+  /** Seek to a specific time in milliseconds */
+  seek(time: number): void;
+  /** Add a step to the timeline */
+  add(step: TimelineStep): void;
+  /** Total timeline duration in milliseconds */
+  duration(): number;
+  /** Subscribe to finish events */
+  onFinish(callback: () => void): () => void;
+}
+
+/**
+ * Scroll animation configuration.
+ */
+export interface ScrollAnimateOptions extends AnimateOptions {
+  /** IntersectionObserver root */
+  root?: Element | Document | null;
+  /** Root margin for observer */
+  rootMargin?: string;
+  /** Intersection thresholds */
+  threshold?: number | number[];
+  /** Trigger only once (default: true) */
+  once?: boolean;
+  /** Callback when element enters the viewport */
+  onEnter?: (element: Element) => void;
+}
+
+/**
+ * Cleanup function for scroll animations.
+ */
+export type ScrollAnimateCleanup = () => void;
+
+/**
+ * Options for the `morphElement` FLIP-based morph animation.
+ */
+export interface MorphOptions {
+  /** Animation duration in milliseconds (default: 300) */
+  duration?: number;
+  /** CSS easing function (default: 'ease') */
+  easing?: string;
+  /** Whether to respect prefers-reduced-motion (default: true) */
+  respectReducedMotion?: boolean;
+  /** Callback when morph completes */
+  onComplete?: () => void;
+}
+
+/**
+ * Options for the `parallax` scroll-linked effect.
+ */
+export interface ParallaxOptions {
+  /** Parallax speed multiplier (default: 0.5). Values < 1 are slower, > 1 are faster. */
+  speed?: number;
+  /** Direction of the parallax effect (default: 'vertical') */
+  direction?: 'vertical' | 'horizontal' | 'both';
+  /** Whether to respect prefers-reduced-motion (default: true) */
+  respectReducedMotion?: boolean;
+}
+
+/**
+ * Cleanup function for the parallax effect.
+ */
+export type ParallaxCleanup = () => void;
+
+/**
+ * Options for the `typewriter` text animation.
+ */
+export interface TypewriterOptions {
+  /** Time in milliseconds between each character (default: 50) */
+  speed?: number;
+  /** Initial delay before starting, in milliseconds (default: 0) */
+  delay?: number;
+  /** Whether to show a blinking cursor (default: false) */
+  cursor?: boolean;
+  /** Cursor character (default: '|') */
+  cursorChar?: string;
+  /** Whether to loop the animation (default: false) */
+  loop?: boolean;
+  /** Pause duration at end before looping, in ms (default: 1000) */
+  loopDelay?: number;
+  /** Whether to respect prefers-reduced-motion (default: true) */
+  respectReducedMotion?: boolean;
+  /** Callback when typing completes (per-loop) */
+  onComplete?: () => void;
+}
+
+/**
+ * Controls for an active typewriter animation.
+ */
+export interface TypewriterControls {
+  /** Stop the animation and clean up */
+  stop(): void;
+  /** Promise that resolves when the animation finishes, or when a looping animation is stopped */
+  done: Promise<void>;
+}

package/src/motion/typewriter.ts

@@ -0,0 +1,164 @@
+/**
+ * Character-by-character typewriter text animation.
+ *
+ * @module bquery/motion
+ */
+
+import { prefersReducedMotion } from './reduced-motion';
+import type { TypewriterControls, TypewriterOptions } from './types';
+
+/**
+ * Animate text appearing character by character in an element.
+ *
+ * @param element - The element to type text into
+ * @param text - The text to display
+ * @param options - Typewriter configuration
+ * @returns Controls with `.stop()` to cancel and `.done` promise
+ *
+ * @example
+ * ```ts
+ * const tw = typewriter(
+ *   document.querySelector('#output')!,
+ *   'Hello, world!',
+ *   { speed: 80, cursor: true },
+ * );
+ *
+ * // Wait for it to finish:
+ * await tw.done;
+ *
+ * // Or cancel early:
+ * tw.stop();
+ * ```
+ */
+export const typewriter = (
+  element: HTMLElement,
+  text: string,
+  options: TypewriterOptions = {}
+): TypewriterControls => {
+  const {
+    speed = 50,
+    delay = 0,
+    cursor = false,
+    cursorChar = '|',
+    loop = false,
+    loopDelay = 1000,
+    respectReducedMotion = true,
+    onComplete,
+  } = options;
+
+  if (typeof document === 'undefined') {
+    return {
+      stop: () => {},
+      done: Promise.resolve(),
+    };
+  }
+
+  const el = element;
+  let stopped = false;
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  let cursorEl: HTMLSpanElement | null = null;
+  let cursorTimer: ReturnType<typeof setInterval> | null = null;
+  let resolvePromise: (() => void) | null = null;
+
+  // Add cursor element if enabled
+  const setupCursor = () => {
+    if (!cursor) return;
+    cursorEl = document.createElement('span');
+    cursorEl.setAttribute('aria-hidden', 'true');
+    cursorEl.textContent = cursorChar;
+    el.appendChild(cursorEl);
+
+    // Blink the cursor
+    let visible = true;
+    cursorTimer = setInterval(() => {
+      if (cursorEl) {
+        visible = !visible;
+        cursorEl.style.opacity = visible ? '1' : '0';
+      }
+    }, 530);
+  };
+
+  const removeCursor = () => {
+    if (cursorTimer !== null) {
+      clearInterval(cursorTimer);
+      cursorTimer = null;
+    }
+    if (cursorEl && cursorEl.parentNode) {
+      cursorEl.parentNode.removeChild(cursorEl);
+      cursorEl = null;
+    }
+  };
+
+  const stop = () => {
+    if (stopped) return;
+    stopped = true;
+    if (timer !== null) {
+      clearTimeout(timer);
+      timer = null;
+    }
+    removeCursor();
+    // Resolve the done promise so callers awaiting it are unblocked
+    resolvePromise?.();
+    resolvePromise = null;
+  };
+
+  // If reduced motion, show text instantly
+  if (respectReducedMotion && prefersReducedMotion()) {
+    el.textContent = text;
+    onComplete?.();
+    return {
+      stop: () => {},
+      done: Promise.resolve(),
+    };
+  }
+
+  const done = new Promise<void>((resolve) => {
+    resolvePromise = resolve;
+
+    const typeLoop = () => {
+      let charIndex = 0;
+      el.textContent = '';
+      setupCursor();
+      const textNode = document.createTextNode('');
+
+      if (cursorEl) {
+        el.insertBefore(textNode, cursorEl);
+      } else {
+        el.appendChild(textNode);
+      }
+
+      const typeNextChar = () => {
+        if (stopped) {
+          return;
+        }
+        if (charIndex < text.length) {
+          textNode.data = text.slice(0, charIndex + 1);
+          charIndex++;
+          timer = setTimeout(typeNextChar, speed);
+        } else {
+          // Typing complete for this iteration
+          onComplete?.();
+
+          if (loop && !stopped) {
+            timer = setTimeout(() => {
+              if (!stopped) {
+                removeCursor();
+                typeLoop();
+              }
+            }, loopDelay);
+          } else {
+            removeCursor();
+            resolve();
+            resolvePromise = null;
+          }
+        }
+      };
+
+      timer = setTimeout(typeNextChar, delay);
+    };
+
+    typeLoop();
+  });
+
+  return { stop, done };
+};

package/src/plugin/index.ts

@@ -0,0 +1,37 @@
+/**
+ * bQuery Plugin System — register plugins that extend bQuery with custom
+ * directives and components.
+ *
+ * @module bquery/plugin
+ *
+ * @example
+ * ```ts
+ * import { use, isInstalled, getInstalledPlugins } from '@bquery/bquery/plugin';
+ *
+ * use({
+ *   name: 'my-plugin',
+ *   install(ctx, options) {
+ *     ctx.directive('tooltip', (el, expr) => { ... });
+ *     ctx.component('my-widget', MyWidgetElement);
+ *   },
+ * });
+ * ```
+ */
+
+// Types
+export type {
+  BQueryPlugin,
+  CustomDirective,
+  CustomDirectiveHandler,
+  PluginInstallContext,
+} from './types';
+
+// Runtime API
+export {
+  use,
+  isInstalled,
+  getInstalledPlugins,
+  getCustomDirective,
+  getCustomDirectives,
+  resetPlugins,
+} from './registry';