@ssgoi/core 0.0.1

package/src/lib/create-ssgoi-transition-context.ts

@@ -0,0 +1,265 @@
+import type {
+  SsgoiConfig,
+  SsgoiContext,
+  GetTransitionConfig,
+  Transition,
+} from "./types";
+import { getScrollingElement } from "./utils";
+
+/**
+ * SSGOI Transition Context Operation Principles
+ *
+ * Page transition scenario: /home → /about
+ *
+ * 1. OUT animation starts (when /home page disappears)
+ *    - getTransition('unique-id', 'out', '/home') is called
+ *    - Stores { from: '/home' } in pendingTransitions
+ *    - Creates Promise and stores outResolve (not resolved yet)
+ *    - Calls checkAndResolve → waits because 'to' is missing
+ *
+ * 2. IN animation starts (when /about page appears)
+ *    - getTransition('unique-id', 'in', '/about') is called
+ *    - Adds { to: '/about' } to existing pending
+ *    - Creates Promise and stores inResolve
+ *    - Calls checkAndResolve → both 'from' and 'to' are present!
+ *
+ * 3. Transition matching and resolution
+ *    - Finds appropriate transition with from: '/home', to: '/about'
+ *    - Resolves both out and in with the found transition's settings
+ *    - Removes the id from pendingTransitions
+ *
+ * Key point: OUT and IN wait for each other. When both are ready,
+ *           they find the appropriate transition using from/to info
+ *           and resolve simultaneously.
+ *
+ * Edge cases:
+ * - No OUT animation on page refresh or initial entry
+ * - When only IN is called, checkAndResolve doesn't work without 'from'
+ * - Promise isn't resolved, so animation doesn't start
+ */
+
+type PendingTransition = {
+  from?: string;
+  to?: string;
+  outResolve?: (transition: GetTransitionConfig) => void;
+  inResolve?: (transition: GetTransitionConfig) => void;
+};
+
+/**
+ * Creates a transition configuration
+ *
+ * @example
+ * const config = createSggoiTransitionConfig({
+ *   transitions: [
+ *     { from: '/home', to: '/about', transition: fade() },
+ *     { from: '/products', to: '/products/*', transition: slide() }
+ *   ],
+ *   defaultTransition: fade()
+ * });
+ */
+export function createSggoiTransitionContext(
+  options: SsgoiConfig
+): SsgoiContext {
+  let pendingTransition: PendingTransition | null = null;
+
+  // Process symmetric transitions - creates bidirectional transitions automatically
+  const processedTransitions = [...options.transitions];
+  const symmetricTransitions: typeof options.transitions = [];
+  
+  for (const transitionDef of options.transitions) {
+    if (transitionDef.symmetric) {
+      // Check if reverse transition already exists to avoid duplicates
+      const reverseExists = processedTransitions.some(
+        t => t.from === transitionDef.to && t.to === transitionDef.from
+      );
+      
+      if (!reverseExists) {
+        // Create reverse transition for symmetric navigation
+        symmetricTransitions.push({
+          from: transitionDef.to,
+          to: transitionDef.from,
+          transition: transitionDef.transition,
+          // Don't add symmetric flag to the reverse to avoid infinite loop
+        });
+      }
+    }
+  }
+  
+  // Add symmetric transitions to the processed list for matching
+  processedTransitions.push(...symmetricTransitions);
+
+  // Scroll tracking - preserves scroll positions between page transitions
+  let scrollContainer: HTMLElement | null = null;
+  const scrollPositions: Map<string, { x: number; y: number }> = new Map();
+  let currentPath: string | null = null;
+
+  // Scroll listener - captures current scroll position
+  const scrollListener = () => {
+    if (scrollContainer && currentPath) {
+      scrollPositions.set(currentPath, {
+        x: scrollContainer.scrollLeft,
+        y: scrollContainer.scrollTop,
+      });
+    }
+  };
+
+  // Start tracking scroll for a path - initializes scroll container and updates current path
+  const startScrollTracking = (element: HTMLElement, path: string) => {
+    // Initialize scroll container once - finds the scrollable element
+    if (!scrollContainer) {
+      scrollContainer = getScrollingElement(element);
+      scrollContainer.addEventListener("scroll", scrollListener, {
+        passive: true,
+      });
+    }
+
+    // Update current path for scroll position tracking
+    currentPath = path;
+  };
+
+  // Calculate scroll offset - computes difference between pages' scroll positions
+  const calculateScrollOffset = (): { x: number; y: number } => {
+    const from = pendingTransition?.from;
+    const to = pendingTransition?.to;
+
+    const fromScroll =
+      from && scrollPositions.has(from)
+        ? scrollPositions.get(from)!
+        : { x: 0, y: 0 };
+
+    const toScroll =
+      to && scrollPositions.has(to) ? scrollPositions.get(to)! : { x: 0, y: 0 };
+
+    return {
+      x: -toScroll.x + fromScroll.x,
+      y: -toScroll.y + fromScroll.y,
+    };
+  };
+
+  function checkAndResolve() {
+    if (pendingTransition?.from && pendingTransition?.to) {
+      const transition = findMatchingTransition(
+        pendingTransition.from,
+        pendingTransition.to,
+        processedTransitions
+      );
+      const result = transition || options.defaultTransition;
+      const scrollOffset = calculateScrollOffset();
+      const context = { scrollOffset };
+
+      if (result) {
+        if (result.out && pendingTransition.outResolve) {
+          pendingTransition.outResolve((element) =>
+            result.out!(element, context)
+          );
+        }
+        if (result.in && pendingTransition.inResolve) {
+          pendingTransition.inResolve((element) =>
+            result.in!(element, context)
+          );
+        }
+      }
+
+      pendingTransition = null;
+    }
+  }
+
+  const getTransition = async (path: string, type: "out" | "in") => {
+    if (type === "in") {
+      // If IN is called but no OUT is pending, no transition occurs (e.g., page refresh)
+      if (!pendingTransition || !pendingTransition.from) {
+        return () => ({}); // Return empty transition
+      }
+    }
+
+    if (!pendingTransition) {
+      pendingTransition = {};
+    }
+
+    if (type === "out") {
+      pendingTransition.from = path;
+      return new Promise<GetTransitionConfig>((resolve) => {
+        pendingTransition!.outResolve = resolve;
+        checkAndResolve();
+      });
+    } else {
+      pendingTransition.to = path;
+      return new Promise<GetTransitionConfig>((resolve) => {
+        pendingTransition!.inResolve = resolve;
+        checkAndResolve();
+      });
+    }
+  };
+
+  return (path: string) => {
+    return {
+      key: path,
+      in: async (element: HTMLElement) => {
+        // Start scroll tracking for this path when element enters
+        startScrollTracking(element, path);
+
+        const transitionConfig = await getTransition(path, "in");
+        return transitionConfig(element);
+      },
+      out: async (element: HTMLElement) => {
+        const transitionConfig = await getTransition(path, "out");
+        return transitionConfig(element);
+      },
+    };
+  };
+}
+
+/**
+ * Matches a path against a pattern
+ * Supports exact matches and wildcard patterns
+ *
+ * @example
+ * matchPath('/products', '/products') // true
+ * matchPath('/products/123', '/products/*') // true
+ * matchPath('/products/123', '/products') // false
+ * matchPath('/anything', '*') // true
+ */
+function findMatchingTransition<TContext>(
+  from: string,
+  to: string,
+  transitions: Array<{
+    from: string;
+    to: string;
+    transition: Transition<TContext>;
+  }>
+): Transition<TContext> | null {
+  // First try to find exact match for both from and to paths
+  for (const config of transitions) {
+    if (matchPath(from, config.from) && matchPath(to, config.to)) {
+      return config.transition;
+    }
+  }
+
+  // Then try wildcard matches if no exact match found
+  for (const config of transitions) {
+    if (
+      (config.from === "*" || matchPath(from, config.from)) &&
+      (config.to === "*" || matchPath(to, config.to))
+    ) {
+      return config.transition;
+    }
+  }
+
+  return null;
+}
+
+function matchPath(path: string, pattern: string): boolean {
+  // Universal match - asterisk matches any path
+  if (pattern === "*") {
+    return true;
+  }
+
+  // Wildcard match - pattern ending with /* matches path and subpaths
+  if (pattern.endsWith("/*")) {
+    const prefix = pattern.slice(0, -2);
+    return path === prefix || path.startsWith(prefix + "/");
+  }
+
+  // Exact match - paths must be identical
+  return path === pattern;
+}

package/src/lib/create-transition-callback.ts

@@ -0,0 +1,246 @@
+import type { Transition, TransitionCallback } from "./types";
+import { Animator } from "./animator";
+/**
+ * Creates a transition callback that can be used with framework-specific implementations
+ * This is the core logic that frameworks can wrap with their own APIs
+ *
+ * UX Animation Behavior - 4 Main Scenarios:
+ *
+ * 1. No animation running + IN trigger:
+ *    - Start entrance animation (0 → 1)
+ *    - Return cleanup function for exit
+ *
+ * 2. No animation running + OUT trigger:
+ *    - Clone element, start exit animation (1 → 0)
+ *    - Remove clone when complete
+ *
+ * 3. IN animation running + OUT trigger:
+ *    - Stop current IN animation (DOM is disappearing)
+ *    - Clone element for exit animation
+ *    - Create REVERSED IN animation (not OUT animation) with current state
+ *    - This gives natural backward motion instead of jumping to OUT definition
+ *
+ * 4. OUT animation running + IN trigger:
+ *    - Stop current OUT animation (cleanup any cloned elements)
+ *    - Create REVERSED OUT animation (not IN animation) with current state
+ *    - This gives natural backward motion instead of jumping to IN definition
+ *    - Switch to entrance mode
+ *
+ * Closure Structure:
+ * - Outer function: Returns entrance callback
+ * - Inner function (entrance callback): Returns cleanup callback (exit)
+ * - Cleanup callback: Handles exit transitions
+ */
+export function createTransitionCallback(
+  getTransition: () => Transition,
+  options?: {
+    onCleanupEnd?: () => void;
+  }
+): TransitionCallback {
+  let currentAnimation: Animator | null = null;
+  let currentClone: HTMLElement | null = null; // Track current clone element
+  let parentRef: Element | null = null;
+  let nextSiblingRef: Element | null = null;
+  let isEntering = false; // Track current transition direction
+
+  const runEntrance = async (element: HTMLElement) => {
+    // Scenario 4: OUT animation running + IN trigger
+    if (currentAnimation && currentAnimation.getIsAnimating() && !isEntering) {
+      // Stop current OUT animation
+      const currentState = currentAnimation.getCurrentState();
+      currentAnimation.stop();
+
+      // Remove clone immediately
+      if (currentClone) {
+        currentClone.remove();
+        currentClone = null;
+      }
+
+      // Start reversed OUT animation on original element (IN direction)
+      isEntering = true;
+      const transition = getTransition();
+      if (!transition.out) return;
+
+      const outConfig = await Promise.resolve(transition.out(element));
+
+      // Use OUT config but reverse direction (backward)
+      currentAnimation = Animator.fromState(currentState, {
+        from: 1,
+        to: 0,
+        spring: outConfig.spring,
+        onStart: outConfig.onStart,
+        onUpdate: (value) => {
+          outConfig.tick?.(value);
+        },
+        onComplete: () => {
+          currentAnimation = null;
+          isEntering = false;
+          outConfig.onEnd?.();
+        },
+      });
+
+      currentAnimation.backward();
+      return;
+    }
+
+    // Scenario 1: No animation running OR IN already running
+    if (!currentAnimation || !currentAnimation.getIsAnimating()) {
+      // Start new IN animation
+      isEntering = true;
+      const transition = getTransition();
+      if (!transition.in) return;
+
+      const inConfig = await Promise.resolve(transition.in(element));
+
+      // Apply prepare function if provided
+      inConfig.prepare?.(element);
+
+      currentAnimation = new Animator({
+        from: 0,
+        to: 1,
+        spring: inConfig.spring,
+        onStart: inConfig.onStart,
+        onUpdate: (value) => {
+          inConfig.tick?.(value);
+        },
+        onComplete: () => {
+          currentAnimation = null;
+          isEntering = false;
+          inConfig.onEnd?.();
+        },
+      });
+
+      currentAnimation.forward();
+    }
+    // If IN is already running, just continue
+  };
+  function runExitTransition(element: HTMLElement) {
+    // Helper function to insert clone into DOM
+    const insertClone = () => {
+      if (!parentRef || !currentClone) return;
+
+      if (nextSiblingRef && parentRef.contains(nextSiblingRef)) {
+        parentRef.insertBefore(currentClone, nextSiblingRef);
+      } else {
+        parentRef.appendChild(currentClone);
+      }
+    };
+
+    // Helper function to handle cleanup
+    const cleanup = () => {
+      if (currentClone) {
+        currentClone.remove();
+        currentClone = null;
+      }
+      currentAnimation = null;
+      isEntering = false;
+      options?.onCleanupEnd?.();
+    };
+    // Get transition
+    const transition = getTransition();
+    // Clone the element upfront
+    currentClone = element.cloneNode(true) as HTMLElement;
+
+    // Scenario 3: IN animation running + OUT trigger
+    if (currentAnimation && currentAnimation.getIsAnimating() && isEntering) {
+      // Stop current IN animation and create REVERSED IN animation (not OUT)
+      const currentState = currentAnimation.getCurrentState();
+      currentAnimation.stop();
+      isEntering = false;
+
+      // Get the IN config (not OUT) because we want to reverse the IN animation
+      if (!transition.in) {
+        currentClone = null;
+        cleanup();
+        return;
+      }
+
+      Promise.resolve(transition.in(currentClone)).then(async (inConfig) => {
+        const outConfig =
+          currentClone && (await transition.out?.(currentClone));
+
+        if (outConfig?.prepare) {
+          currentClone && outConfig.prepare(currentClone);
+        }
+        // Insert clone only after we have the transition config
+        insertClone();
+
+        // Use IN config but reverse direction (backward)
+        currentAnimation = Animator.fromState(currentState, {
+          from: 0,
+          to: 1,
+          spring: inConfig.spring,
+          onStart: inConfig.onStart,
+          onUpdate: (value) => {
+            inConfig.tick?.(value);
+          },
+          onComplete: () => {
+            inConfig.onEnd?.();
+            cleanup();
+          },
+        });
+
+        currentAnimation.backward();
+      });
+
+      return;
+    }
+
+    // Scenario 2: No animation running OR OUT already running
+    if (
+      !currentAnimation ||
+      !currentAnimation.getIsAnimating() ||
+      !isEntering
+    ) {
+      isEntering = false;
+
+      if (!transition.out) {
+        currentClone = null;
+        cleanup();
+        return;
+      }
+
+      Promise.resolve(transition.out(currentClone)).then((outConfig) => {
+        // Apply prepare function if provided
+
+        currentClone && outConfig.prepare?.(currentClone);
+
+        // Insert clone after preparation
+        insertClone();
+
+        currentAnimation = new Animator({
+          from: 1,
+          to: 0,
+          spring: outConfig.spring,
+          onStart: outConfig.onStart,
+          onUpdate: (value) => {
+            outConfig.tick?.(value);
+          },
+          onComplete: () => {
+            outConfig.onEnd?.();
+            cleanup();
+          },
+        });
+
+        currentAnimation.forward();
+      });
+    }
+    // If OUT is already running, just continue
+  }
+
+  return (element: HTMLElement | null) => {
+    if (!element) return;
+    parentRef = element.parentElement;
+    nextSiblingRef = element.nextElementSibling;
+
+    const transition = getTransition();
+    if (transition.in) {
+      runEntrance(element);
+    }
+
+    // Return cleanup function for exit transition
+    return () => {
+      runExitTransition(element);
+    };
+  };
+}

package/src/lib/index.ts

@@ -0,0 +1,3 @@
+export * from "./types";
+export * from "./transition";
+export * from "./create-ssgoi-transition-context";

package/src/lib/transition.ts

@@ -0,0 +1,76 @@
+import { createTransitionCallback } from "./create-transition-callback";
+import type { Transition, TransitionCallback } from "./types";
+
+/**
+ * Key type for transitions - can be string or symbol
+ */
+type TransitionKey = string | symbol;
+
+/**
+ * Centralized transition management
+ * Uses string/symbol keys for all storage
+ */
+
+// Map to store transition definitions by key
+const transitionDefinitions = new Map<TransitionKey, Transition>();
+
+// Map to store transition callbacks by key
+const transitionCallbacks = new Map<TransitionKey, TransitionCallback>();
+
+/**
+ * Registers a transition with a key and returns the callback
+ * Usage: registerTransition('fade', { in: fadeIn, out: fadeOut })
+ */
+function registerTransition(
+  key: TransitionKey,
+  transition: Transition
+): TransitionCallback {
+  transitionDefinitions.set(key, transition);
+
+  // Return existing callback if it exists
+  let callback = transitionCallbacks.get(key);
+  if (callback) {
+    return callback;
+  }
+
+  // Create new callback
+  callback = createTransitionCallback(
+    () => {
+      const trans = transitionDefinitions.get(key);
+      if (!trans) {
+        console.warn(`Transition "${String(key)}" not found`);
+        return {};
+      }
+      return trans;
+    },
+    {
+      onCleanupEnd: () => unregisterTransition(key),
+    }
+  );
+  transitionCallbacks.set(key, callback);
+  return callback;
+}
+
+/**
+ * Unregisters a transition and cleans up associated resources
+ */
+function unregisterTransition(key: TransitionKey): void {
+  transitionDefinitions.delete(key);
+  transitionCallbacks.delete(key);
+}
+
+/**
+ * Framework-agnostic transition function that can be used as a ref
+ * Usage: <div ref={transition({ key: 'fade', in, out })} />
+ */
+export function transition(options: {
+  key: TransitionKey;
+  in?: Transition["in"];
+  out?: Transition["out"];
+}): TransitionCallback {
+  // Register transition and get callback
+  return registerTransition(options.key, {
+    in: options.in,
+    out: options.out,
+  });
+}

package/src/lib/transitions/blur.ts

@@ -0,0 +1,55 @@
+interface BlurOptions {
+  amount?: number;
+  scale?: boolean;
+  fade?: boolean;
+  spring?: {
+    stiffness?: number;
+    damping?: number;
+  };
+}
+
+export const blur = (options: BlurOptions = {}) => {
+  const {
+    amount = 10,
+    scale = false,
+    fade = true,
+    spring = { stiffness: 300, damping: 30 }
+  } = options;
+
+  return {
+    in: (element: HTMLElement) => ({
+      spring,
+      tick: (progress: number) => {
+        const blurValue = (1 - progress) * amount;
+        const filters = [`blur(${blurValue}px)`];
+        
+        element.style.filter = filters.join(' ');
+        
+        if (scale) {
+          element.style.transform = `scale(${0.8 + progress * 0.2})`;
+        }
+        
+        if (fade) {
+          element.style.opacity = progress.toString();
+        }
+      }
+    }),
+    out: (element: HTMLElement) => ({
+      spring,
+      tick: (progress: number) => {
+        const blurValue = (1 - progress) * amount;
+        const filters = [`blur(${blurValue}px)`];
+        
+        element.style.filter = filters.join(' ');
+        
+        if (scale) {
+          element.style.transform = `scale(${0.8 + progress * 0.2})`;
+        }
+        
+        if (fade) {
+          element.style.opacity = progress.toString();
+        }
+      }
+    })
+  };
+};

package/src/lib/transitions/bounce.ts

@@ -0,0 +1,61 @@
+interface BounceOptions {
+  height?: number;
+  scale?: boolean;
+  fade?: boolean;
+  spring?: {
+    stiffness?: number;
+    damping?: number;
+  };
+}
+
+export const bounce = (options: BounceOptions = {}) => {
+  const {
+    height = 20,
+    scale = true,
+    fade = false,
+    spring = { stiffness: 800, damping: 15 }
+  } = options;
+
+  return {
+    in: (element: HTMLElement) => ({
+      spring,
+      tick: (progress: number) => {
+        const transforms = [];
+        
+        // Bounce effect using sine wave
+        const bounceOffset = Math.sin(progress * Math.PI) * height * (1 - progress);
+        transforms.push(`translateY(${-bounceOffset}px)`);
+        
+        if (scale) {
+          transforms.push(`scale(${0.8 + progress * 0.2})`);
+        }
+        
+        element.style.transform = transforms.join(' ');
+        
+        if (fade) {
+          element.style.opacity = progress.toString();
+        }
+      }
+    }),
+    out: (element: HTMLElement) => ({
+      spring,
+      tick: (progress: number) => {
+        const transforms = [];
+        
+        // Bounce effect using sine wave
+        const bounceOffset = Math.sin(progress * Math.PI) * height * (1 - progress);
+        transforms.push(`translateY(${-bounceOffset}px)`);
+        
+        if (scale) {
+          transforms.push(`scale(${0.8 + progress * 0.2})`);
+        }
+        
+        element.style.transform = transforms.join(' ');
+        
+        if (fade) {
+          element.style.opacity = progress.toString();
+        }
+      }
+    })
+  };
+};