SSGOI

repository·latest·Indexed 21 days ago

https://github.com/meursyphus/ssgoi

A router-agnostic page transition library for modern web frameworks including Angular, React, Svelte, Vue, Qwik, and Solid. Powered by the Web Animations API, SSGOI provides native app-like transitions for mobile web applications with built-in effects such as drill, slide, zoom, and hero. It supports complex motion presets, custom transitions via defineTransition, and a boundary model for nested transitions using the data-ssgoi-transition attribute.

Tokens
67.3K
Snippets
295
Records
340
Agent score
75%

What's inside ssgoi

  1. Implement Persistent Layouts and Keyed Boundaries

    latest

    In SvelteKit, a persistent +layout.svelte can own an outer boundary while child pages own inner boundaries. When navigating between child routes, the layout boundary remains stable.

    If the router reuses the same DOM node but you need to force a new boundary (e.g., when the path changes but the component doesn't re-mount), wrap the boundary in a Svelte {#key} block using the current pathname.

    <!-- Persistent layout boundary -->
    <div data-ssgoi-transition={$page.url.pathname}>
      <ProductTabs />
      {@render children()}
    </div>
    
    <!-- Forcing a boundary refresh using a keyed block -->
    {#key resolveKey($page.url.pathname)}
      <div data-ssgoi-transition={$page.url.pathname}>
        {@render children()}
      </div>
    {/key}
  2. Why SSGOI uses Web Animations API instead of View Transition API

    latest

    SSGOI does not use the native View Transition API because it requires more control over geometry, temporary visual layers, and live DOM elements to achieve complex motion presets.

    By using the Web Animations API, SSGOI can support:

    • Zoom: Transforming and clipping detail pages around specific images.
    • Film: Handling runtime scenes, live video, and multiple spring physics.
    • Sheet: Managing live backdrops that sit between two pages during a transition.
  3. Configure transition effects and slide directions

    latest

    In the SSGOI configuration, you define how different route segments transition.

    • page: Uses the pathname for both the boundary key and the transition ID.
    • Stable Layouts: For layouts like products-shell, you can keep the outer layout key stable while allowing the inner content to use the page identifier.
    • Slide Direction: The order of paths defined in your root configuration determines the slide direction (e.g., left-to-right or right-to-left).

    Commonly used transition effects include:

    • drill: Used for posts.
    • slide: Used for ordered content like product tabs.
    • zoom: Used for galleries and profiles.
  4. Understand Film and Sheet blur transition requirements

    latest

    Some advanced transitions in SSGOI require more than just standard View Transition captures:

    • Film: This transition moves more than two page captures (e.g., scaling down, swapping vertically, and scaling back up) and often requires temporary DOM elements (like corner lines) to be present during the transition. It also uses multiple easing curves (springs) for scale and translation.
    • Blur (Sheet or Zoom): To achieve a clean blur effect, a separate backdrop layer must be placed between the background page and the foreground page. This ensures the blur halo remains independent of the background's scale and clipping.

    If you are building these manually, you cannot rely solely on the ViewTransition pseudo-tree, as it does not provide runtime insertion points for extra layers. You must either prepare the necessary helper DOM/markup before the capture or manage the extra layers yourself.

  5. Understand the difference between Hero and Zoom transitions

    latest

    SSGOI distinguishes between Hero and Zoom transitions based on what is being animated:

    • Hero: Animates a single shared visual element. It creates a clone of the selected image and moves that clone from its source position to its destination position. This is ideal for simple shared-element transitions (e.g., clicking a photo in a gallery).
    • Zoom: Animates the entire incoming detail page. Instead of moving a single image, it uses the image as an anchor to calculate how the whole page should scale, transform, and clip so that it appears to emerge from the thumbnail. This is used for complex page transitions (e.g., Instagram-style profile expansions).

    Use Hero when you want to move a specific asset, and Zoom when you want the new page to feel like it is unfolding from a specific point.

  6. Why SSGOI uses a custom engine instead of the View Transition API

    latest

    While the browser's View Transition API is useful for simple fades or shared element transitions, SSGOI uses its own engine to provide higher-level 'presets'. This allows the library to manage complex transitions without requiring the application developer to rewrite transition logic for every screen.

    SSGOI maintains control over three critical areas that the standard View Transition API does not fully expose or manage for reusable presets:

    1. Information: Determining which elements correspond, which part of the media is visible, and how scroll changes coordinates.
    2. Scene: Managing where to create moving copies, intermediate layers, and transition-only decoration, and handling their removal.
    3. Policy: Deciding which navigations form a pair, which events (like swipe-back or duplicate events) to skip, and how to handle cleanup or mid-transition navigation arrivals.

    By using its own engine based on the real page DOM and the Web Animations API, SSGOI ensures that effect-specific measurement and scene management stay encapsulated within the library's presets.

  7. Understand the SSGOI Demo Mocking API Architecture

    latest

    The SSGOI demo uses a local mocking API system to simulate server/database behavior without actual network requests. This allows the UI to behave as if it were connected to a real backend.

    Key Concepts:

    • No Real Network: It uses in-memory objects from data.ts or data/. Do not use fetch or HTTP clients.
    • Domain-Driven Design: APIs are organized by 'Domain' (e.g., rooms, users) based on which screen they serve, rather than raw database tables.
    • Frontend-Friendly: Actions should transform raw data into UI-ready formats (e.g., converting a likeCount integer into a displayCount string like '3개').
    • No Latency: Do not add setTimeout or artificial delays. The SSGOI transitions are the focus, and artificial delays make the demo feel sluggish.
    • Local Actions: All methods are async functions. Do not use 'use server'. They are designed to run directly in client state queries without network round-trips.
  8. Understand the View Transition API lifecycle

    latest

    For same-document transitions, the browser follows a specific sequence after document.startViewTransition() is called:

    1. Capture the old view: A snapshot of the current state is taken.
    2. Update the DOM: The application state changes and the DOM is updated.
    3. Capture the new view: A snapshot of the new state is taken.
    4. Animate: The browser animates the old and new views inside the ::view-transition pseudo-element tree.

    While this API allows for fading the whole page or connecting elements via view-transition-name, it lacks the public interfaces needed for complex geometric derivations (like content rects or scroll relationships) required by advanced presets.

  9. Understand the SSGOI Demo Project Structure

    latest

    The SSGOI demo showcases transitions that look like "real apps" using mocked data. The project follows a strict directory structure to keep showcases isolated. Routes in src/app/demo/* act as thin shells, while the actual logic resides in src/demo/{showcase}/.

    Directory Layout:

    • demo/{showcase}/api/{domain}/: Mocked server actions using local mock data.
    • demo/{showcase}/state/{domain}/: State management (using Comwit).
    • demo/{showcase}/page/{route}/: UI components.
    • demo/{showcase}/page/layout/: Showcase-specific layouts (e.g., mobile/desktop shells).

    Dependency Flow: page $\rightarrow$ state $\rightarrow$ api (Bottom-up development: api $\rightarrow$ state $\rightarrow$ page).

  10. Implement Bottom Navigation for Mobile Demos

    latest

    Bottom navigation rules depend on the demo type and whether the screen is a 'detail' view.

    General Rules

    • Detail Screens: Screens with a 'back' icon should not have bottom navigation.
    • Main Screens: Should include bottom navigation.
    • Transition Boundary: Navigation must always be placed inside the transition boundary (sticky) to ensure it stays visible during transitions.

    Implementation Patterns

    1. Multi-tab Demos (e.g., google-photos, kakao-talk):

      • Use @/lib/components/mobile-tabs-shell (MobileTabsShell) and mobile-detail-shell (MobileDetailShell).
      • Organize routes into (tabs) and (detail) groups.
      • (tabs)/layout.tsx renders the MobileTabsShell.
      • (detail)/layout.tsx renders the MobileDetailShell.
      • Set withTransitionBoundary={false} for these layouts.
    2. Single-main-screen Demos (e.g., air-bnb, voyage):

      • Render a sticky navigation at the end of the main page component.
      • Keep default withTransitionBoundary settings so the navigation participates in page transitions.
  11. How SSGOI handles Hero and Zoom transitions automatically

    latest

    SSGOI's Hero and Zoom transitions use content-aware geometry to connect an element in a list to its counterpart on a detail screen. Instead of requiring you to manually pass image ratios or border radii in the transition configuration, the library automatically infers this information from your HTML and CSS when the structure is unambiguous.

    To benefit from automatic inference, your markup should follow these patterns:

    1. Use an <img> element as the keyed element, or a wrapper containing exactly one direct child <img>.
    2. Ensure the image has a valid intrinsic ratio (via naturalWidth/naturalHeight or width/height attributes).
    3. Use standard object-fit: cover or object-fit: contain via computed styles.
    4. Keep object-position centered.
    5. Use simple border radii and overflow: hidden or clip on the wrapper.

    If the structure is ambiguous (e.g., using <picture>, <video>, or non-centered object-position), SSGOI will safely fall back to a standard bounding box (bbox) transition.

  12. Automatic fallback behavior in SSGOI transitions

    latest

    SSGOI is designed to be conservative with its automatic geometry inference to avoid visual glitches (like 'snapping' or distorted faces). If the library cannot confidently determine the image geometry, it will fall back to a standard bounding box (bbox) animation.

    The engine will fall back to bbox transitions if it encounters:

    • <picture> or <video> elements.
    • Multiple direct child images within a wrapper.
    • Deeply nested structures where the shared image is ambiguous.
    • A custom, non-centered object-position.
    • Different intrinsic aspect ratios between the source and destination endpoints.
    • Border radii that cannot be reduced to simple pixel values.
    • Image metadata that is only detectable at one of the two endpoints.

    Note: The engine will only apply content-aware geometry if it can be applied to both endpoints. If one side is ambiguous, both sides revert to the bbox animation.