@ssgoi/angular 6.3.0 → 6.5.0

package/README.md

@@ -2,6 +2,18 @@
 
 Angular bindings for SSGOI that give any Angular 20+ app native-feeling page transitions powered by the `@ssgoi/core` animation engine.
 
+try this: [ssgoi.dev](https://ssgoi.dev)
+
+## AI-Assisted Setup
+
+Using Claude, Cursor, ChatGPT, or another AI assistant? Point it at:
+
+```
+https://ssgoi.dev/llms.txt
+```
+
+It has the full setup guide, every transition, the API, and troubleshooting — everything an agent needs to wire SSGOI into your app.
+
 ## Installation
 
 ```bash
@@ -15,7 +27,8 @@ yarn add @ssgoi/angular
 ## What You Get
 
 - `Ssgoi` directive (selector: `[ssgoi]`) that bootstraps the core transition context on the client and gracefully no-ops during SSR.
-- `SsgoiTransition` directive (selector: `[ssgoiTransition]`) that wires individual route containers into the transition system.
+- `data-ssgoi-transition` route markers discovered automatically inside `[ssgoi]`.
+- Deprecated `SsgoiTransition` directive (selector: `[ssgoiTransition]`) kept for backward compatibility.
 - `injectSsgoi()` helper and `SSGOI_CONTEXT` injection token for retrieving the transition context anywhere in your component tree.
 - Re-exported transition factories under `@ssgoi/angular/view-transitions`.
 
@@ -34,10 +47,11 @@ import { fade } from "@ssgoi/angular/view-transitions";
   standalone: true,
   imports: [RouterOutlet, Ssgoi],
   template: `
+    <!-- position: relative + z-index: 0 are required (the outgoing page is cloned with position:absolute) -->
     <div
       ssgoi
       [config]="ssgoiConfig()"
-      style="position: relative; min-height: 100vh"
+      style="position: relative; z-index: 0; min-height: 100vh"
     >
       <router-outlet />
     </div>
@@ -50,18 +64,16 @@ export class AppComponent {
 }
 ```
 
-### 2. Mark each routed view with `SsgoiTransition`
+### 2. Mark each routed view
 
 ```typescript
 import { Component } from "@angular/core";
-import { SsgoiTransition } from "@ssgoi/angular";
 
 @Component({
   selector: "app-home",
   standalone: true,
-  imports: [SsgoiTransition],
   template: `
-    <section [ssgoiTransition]="'/home'">
+    <section data-ssgoi-transition="/home">
       <h1>Home Page</h1>
     </section>
   `,
@@ -69,12 +81,12 @@ import { SsgoiTransition } from "@ssgoi/angular";
 export class HomeComponent {}
 ```
 
-The value you pass to `[ssgoiTransition]` should uniquely identify the view (commonly the route path).
+The `data-ssgoi-transition` value should uniquely identify the view (commonly the route path).
 
 ## How It Works
 
-- `Ssgoi` wraps `createSggoiTransitionContext` from `@ssgoi/core` and injects it via `SSGOI_CONTEXT`. The directive guards against the server platform so SSR renders stay deterministic.
-- `SsgoiTransition` reads that context with `injectSsgoi()`, sets `data-ssgoi-transition` on the host, and subscribes the element to the core transition runner.
+- `Ssgoi` wraps `createSggoiTransitionContext` from `@ssgoi/core`, injects it via `SSGOI_CONTEXT`, and observes `data-ssgoi-transition` elements under the host. The directive guards against the server platform so SSR renders stay deterministic.
+- The deprecated `SsgoiTransition` directive still sets `data-ssgoi-transition` and registers the host directly for backward compatibility.
 
 Because everything is driven by signals, Angular change detection stays minimal and the bundle remains fully tree-shakeable.
 
@@ -83,25 +95,48 @@ Because everything is driven by signals, Angular change detection stays minimal
 - `Ssgoi`
   - `config: SsgoiConfig` (input, optional) – global transition configuration. Uses `{}` as default.
   - `host: HostAnimation | undefined` (input, optional) – external playback host for debug tooling.
-- `SsgoiTransition`
-  - `ssgoiTransition: string` (required input) – identifier for the target view/container.
+- `data-ssgoi-transition` – identifier for the target view/container.
+- `SsgoiTransition` is deprecated; use `data-ssgoi-transition` directly.
 - `injectSsgoi(): SsgoiContext` – returns the adapter context. During SSR it falls back to a no-op implementation so you can call it unconditionally.
 
 ## Available Transitions
 
-View-level factories:
+Import view-level factories from `@ssgoi/angular/view-transitions`:
 
 ```typescript
 import {
   fade,
-  scroll,
   drill,
-  hero,
   slide,
+  scroll,
+  axis,
+  sheet,
+  hero,
   zoom,
+  strip,
+  blind,
+  film,
+  rotate,
+  jaemin,
 } from "@ssgoi/angular/view-transitions";
 ```
 
+- `fade()` - Calm cross-fade. Safe default for unrelated pages
+- `drill()` - iOS-style hierarchical navigation (list → detail)
+- `slide()` - Horizontal push for tabs / sequential flows
+- `scroll()` - Vertical page scroll for onboarding / paginated views
+- `axis()` - Material/Flutter shared-axis swap for sibling/tab routes
+- `sheet()` - Bottom sheet that slides up (modal-like flows)
+- `hero()` - Shared element transition (matching `data-hero-enter-key` / `data-hero-exit-key`)
+- `zoom()` - Card-to-detail expansion (matching `data-zoom-enter-key` / `data-zoom-exit-key`)
+- `strip()` - 3D Y-axis perspective flip
+- `blind()` - Window-blinds wipe reveal
+- `film()` - Cinematic shrink + tile (gallery / lightbox)
+- `rotate()` - Card flip between siblings
+- `jaemin()` - Playful rotated zoom for special moments
+
+Each factory takes the unified config: `{ paths }` (symmetric), `{ enter, exit, type? }` (directional, e.g. `drill`/`sheet`), or `{ paths }` with order deciding direction (`slide`/`scroll`/`axis`).
+
 ## Sample Configuration
 
 ```typescript

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@ssgoi/angular",
-  "version": "6.3.0",
+  "version": "6.5.0",
   "description": "Angular bindings for SSGOI - Native app-like page transitions for Angular applications",
   "private": false,
   "type": "module",
   "types": "./dist/index.d.ts",
   "dependencies": {
-    "@ssgoi/core": "^6.3.0"
+    "@ssgoi/core": "^6.5.0"
   },
   "peerDependencies": {
     "@angular/common": "^20.0.0",

package/src/lib/index.ts

@@ -1,4 +1,5 @@
 export { Ssgoi } from "./ssgoi.directive";
+/** @deprecated Set `data-ssgoi-transition` directly on an element inside `[ssgoi]` instead. */
 export { SsgoiTransition } from "./ssgoi-transition.directive";
 export { injectSsgoi, SSGOI_CONTEXT } from "./context";
 export * from "./types";

package/src/lib/ssgoi-transition.directive.ts

@@ -10,6 +10,10 @@ import {
 import { isPlatformBrowser } from "@angular/common";
 import { injectSsgoi } from "./context";
 
+/**
+ * @deprecated Set `data-ssgoi-transition` directly on the page boundary
+ * element inside `[ssgoi]` instead.
+ */
 @Directive({
   selector: "[ssgoiTransition]",
   standalone: true,

package/src/lib/ssgoi.directive.ts

@@ -1,27 +1,24 @@
 import {
+  AfterViewInit,
   Directive,
+  ElementRef,
+  OnDestroy,
   input,
   forwardRef,
   PLATFORM_ID,
   inject,
 } from "@angular/core";
 import { isPlatformBrowser } from "@angular/common";
-import { createSggoiTransitionContext } from "@ssgoi/core/internal";
+import {
+  createSggoiTransitionContext,
+  observeSsgoiTransitions,
+} from "@ssgoi/core/internal";
 import type { HostAnimation } from "@ssgoi/core/internal";
 import type { SsgoiConfig, SsgoiContext } from "@ssgoi/core/types";
 import { SSGOI_CONTEXT } from "./context";
 
 function createSsgoiContext(component: Ssgoi): SsgoiContext | undefined {
-  const platformId = inject(PLATFORM_ID);
-
-  // Only create context in browser environment
-  if (!isPlatformBrowser(platformId)) {
-    // Return a no-op context for SSR
-    return undefined;
-  }
-  return createSggoiTransitionContext(component.config(), {
-    host: component.host(),
-  });
+  return component.getContext();
 }
 
 @Directive({
@@ -35,7 +32,34 @@ function createSsgoiContext(component: Ssgoi): SsgoiContext | undefined {
     },
   ],
 })
-export class Ssgoi {
+export class Ssgoi implements AfterViewInit, OnDestroy {
   readonly config = input<SsgoiConfig>({});
   readonly host = input<HostAnimation | undefined>(undefined);
+
+  private readonly el = inject(ElementRef<HTMLElement>);
+  private readonly platformId = inject(PLATFORM_ID);
+  private contextValue?: SsgoiContext;
+  private stopObserving?: () => void;
+
+  getContext(): SsgoiContext | undefined {
+    if (!isPlatformBrowser(this.platformId)) {
+      return undefined;
+    }
+
+    this.contextValue ??= createSggoiTransitionContext(this.config(), {
+      host: this.host(),
+    });
+    return this.contextValue;
+  }
+
+  ngAfterViewInit(): void {
+    const ssgoi = this.getContext();
+    if (!ssgoi) return;
+
+    this.stopObserving = observeSsgoiTransitions(this.el.nativeElement, ssgoi);
+  }
+
+  ngOnDestroy(): void {
+    this.stopObserving?.();
+  }
 }