@ssgoi/react 6.3.0 → 6.5.0-beta.0

package/README.md

@@ -6,6 +6,16 @@ try this: [ssgoi.dev](https://ssgoi.dev)
 
 ![https://ssgoi.dev](https://ssgoi.dev/ssgoi.gif)
 
+## 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.
+
 ## What is SSGOI?
 
 SSGOI brings native app-like page transitions to the web. Transform your static page navigations into smooth, delightful experiences that users love.
@@ -36,74 +46,73 @@ pnpm add @ssgoi/react
 import { Ssgoi } from "@ssgoi/react";
 import { fade } from "@ssgoi/react/view-transitions";
 
+const config = {
+  transitions: [fade({ paths: ["/", "/about"] })],
+};
+
 export default function App() {
   return (
-    <Ssgoi config={{ transitions: fade({ paths: ["/", "/about"] }) }}>
-      <div style={{ position: "relative" }}>{/* Your app */}</div>
+    <Ssgoi config={config}>
+      {/* relative + z-0 are required (see "Layout Requirements" below) */}
+      <div className="relative z-0">{/* Your app */}</div>
     </Ssgoi>
   );
 }
 ```
 
-### 2. Wrap your pages
+### 2. Mark your pages
 
 ```tsx
-import { SsgoiTransition } from "@ssgoi/react";
-
 export default function HomePage() {
   return (
-    <SsgoiTransition id="/">
+    <main data-ssgoi-transition="/">
       <h1>Welcome</h1>
       {/* Page content */}
-    </SsgoiTransition>
+    </main>
   );
 }
 ```
 
 **That's it!** Your configured pages now transition smoothly with a fade effect.
 
+## Layout Requirements
+
+The element wrapping `<Ssgoi>` needs `position: relative` and `z-index: 0` (`relative z-0` in Tailwind).
+
+When a page leaves, SSGOI clones it back into the DOM with `position: absolute` so it can animate out while the new page animates in. Without a positioned, stacking-context ancestor the clone jumps to the wrong place or falls behind the background. Add `overflow-x-clip` too if you use horizontal transitions (`slide`, `drill`).
+
 ## Advanced Transitions
 
 ### Route-based Transitions
 
-Define different transitions for different routes:
+Each transition factory returns a path-transition group. Drop the results straight into `config.transitions` — nested arrays are flattened automatically:
 
 ```tsx
+import { fade, drill, zoom } from "@ssgoi/react/view-transitions";
+
 const config = {
   transitions: [
-    // Scroll between tabs
-    { from: "/home", to: "/about", transition: scroll({ direction: "up" }) },
-    { from: "/about", to: "/home", transition: scroll({ direction: "down" }) },
-
-    // Drill in when entering details
-    {
-      from: "/products",
-      to: "/products/*",
-      transition: drill({ direction: "enter" }),
-    },
-
-    // Pinterest-style image transitions
-    { from: "/gallery", to: "/photo/*", transition: pinterest() },
+    // Calm cross-fade between tabs
+    fade({ paths: ["/home", "/about"] }),
+
+    // iOS-style drill-in when entering details
+    drill({ enter: "/products/*", exit: "/products" }),
+
+    // Card-to-detail zoom (needs matching data-zoom-*-key)
+    zoom({ paths: ["/gallery", "/photo/*"], type: "expand" }),
   ],
 };
 ```
 
-### Symmetric Transitions
+Transitions come in three shapes:
 
-Automatically create bidirectional transitions:
-
-```tsx
-{
-  from: '/home',
-  to: '/about',
-  transition: scroll({ direction: 'up' }),
-  symmetric: true  // Automatically creates reverse transition
-}
-```
+- **`{ paths }`** — symmetric: every pair animates with the same physics (`fade`, `hero`, `zoom`, `blind`, `film`, `rotate`, `strip`, `jaemin`)
+- **`{ enter, exit, type? }`** — directional: enter and exit get different physics (`drill`, `sheet`)
+- **`{ paths }`** — ordered: path order decides forward / back direction (`slide`, `scroll`, `axis`)
 
 ### Individual Element Animations
 
-Animate specific elements during mount/unmount:
+Animate specific elements during mount/unmount with `transition()`:
 
 ```tsx
 import { transition } from "@ssgoi/react";
@@ -226,31 +235,36 @@ function List() {
 ```tsx
 // app/layout.tsx
 import { Ssgoi } from "@ssgoi/react";
-import { scroll } from "@ssgoi/react/view-transitions";
+import { drill, fade } from "@ssgoi/react/view-transitions";
+
+const config = {
+  transitions: [
+    drill({ enter: "/post/*", exit: "*" }),
+    fade({ paths: ["/", "/about"] }),
+  ],
+};
 
-export default function RootLayout({ children }) {
+export default function RootLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
   return (
     <html>
       <body>
-        <Ssgoi
-          config={{
-            transitions: scroll({ paths: ["/", "/about"] }),
-          }}
-        >
-          <div style={{ position: "relative", minHeight: "100vh" }}>
-            {children}
-          </div>
+        <Ssgoi config={config}>
+          <div className="relative z-0 min-h-screen">{children}</div>
         </Ssgoi>
       </body>
     </html>
   );
 }
+```
 
+```tsx
 // app/page.tsx
-import { SsgoiTransition } from "@ssgoi/react";
-
 export default function Page() {
-  return <SsgoiTransition id="/">{/* Your page content */}</SsgoiTransition>;
+  return <main data-ssgoi-transition="/">{/* Your page content */}</main>;
 }
 ```
 
@@ -266,12 +280,13 @@ The provider component that manages transition context.
 <Ssgoi config={ssgoiConfig}>{children}</Ssgoi>
 ```
 
-#### `<SsgoiTransition>`
+#### `data-ssgoi-transition`
 
-Wrapper component for pages that should transition.
+Attribute for pages that should transition. Set it on the page boundary element
+inside `<Ssgoi>`.
 
 ```tsx
-<SsgoiTransition id="/page-id">{children}</SsgoiTransition>
+<main data-ssgoi-transition="/page-id">{children}</main>
 ```
 
 ### Hooks
@@ -306,11 +321,19 @@ Apply transitions to individual elements.
 
 ### Page Transitions (`@ssgoi/react/view-transitions`)
 
-- `fade()` - Smooth opacity transition
-- `scroll()` - Vertical scrolling (up/down)
-- `drill()` - Drill in/out effect (enter/exit)
-- `hero()` - Shared element transitions
-- `pinterest()` - Pinterest-style expand effect
+- `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
 
 ### Element Transitions (`@ssgoi/react/transitions`)
 

package/dist/lib/ssgoi-transition.cjs

@@ -1,2 +1,2 @@
 "use client";
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const c=require("react/jsx-runtime"),u=require("./context.cjs"),a=({children:o,id:t,as:e,className:n,...s})=>{const{refFor:i}=u.useSsgoi(),r=e||"div";return c.jsx(r,{ref:i(t),"data-ssgoi-transition":t,className:n,...s,children:o})};exports.SsgoiTransition=a;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const r=require("react/jsx-runtime"),a=({children:t,id:i,as:n,className:o,...s})=>{const e=n||"div";return r.jsx(e,{"data-ssgoi-transition":i,className:o,...s,children:t})};exports.SsgoiTransition=a;

package/dist/lib/ssgoi-transition.d.ts

@@ -8,11 +8,8 @@ type SsgoiTransitionProps<T extends ElementType = "div"> = {
 /**
  * Marks a subtree as a Ssgoi page boundary.
  *
- * The ssgoi context hands out a stable, path-bound ref callback via
- * `refFor(id)` — the same function reference across renders for the same
- * id, so React doesn't see a fresh ref each commit and won't churn the
- * attach/detach cycle. Unmount is detected internally via the shared
- * MutationObserver in the dispatcher; nothing extra to wire up here.
+ * @deprecated Set `data-ssgoi-transition` directly on the page boundary
+ * element inside `<Ssgoi>` instead.
  */
 export declare const SsgoiTransition: <T extends ElementType = "div">({ children, id, as, className, ...rest }: SsgoiTransitionProps<T>) => import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/lib/ssgoi-transition.js

@@ -1,25 +1,12 @@
 "use client";
-import { jsx as e } from "react/jsx-runtime";
-import { useSsgoi as m } from "./context.js";
-const c = ({
-  children: t,
-  id: o,
-  as: n,
-  className: r,
+import { jsx as r } from "react/jsx-runtime";
+const m = ({
+  children: o,
+  id: n,
+  as: t,
+  className: i,
   ...s
-}) => {
-  const { refFor: i } = m();
-  return /* @__PURE__ */ e(
-    n || "div",
-    {
-      ref: i(o),
-      "data-ssgoi-transition": o,
-      className: r,
-      ...s,
-      children: t
-    }
-  );
-};
+}) => /* @__PURE__ */ r(t || "div", { "data-ssgoi-transition": n, className: i, ...s, children: o });
 export {
-  c as SsgoiTransition
+  m as SsgoiTransition
 };

package/dist/lib/ssgoi.cjs

@@ -1,2 +1,2 @@
 "use client";
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const s=require("react/jsx-runtime"),o=require("react"),n=require("./context.cjs"),u=require("@ssgoi/core/internal"),c=o.memo(({config:e,host:t,children:r})=>{const i=o.useMemo(()=>u.createSggoiTransitionContext(e,{host:t}),[e,t]);return s.jsx(n.SsgoiProvider,{value:i,children:r})});exports.Ssgoi=c;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const c=require("react/jsx-runtime"),e=require("react"),i=require("@ssgoi/core/internal"),a={display:"contents"},l=e.memo(({config:t,host:o,children:u})=>{const r=e.useRef(null),s=e.useMemo(()=>i.createSggoiTransitionContext(t,{host:o}),[t,o]);return e.useEffect(()=>{const n=r.current;if(n)return i.observeSsgoiTransitions(n,s)},[s]),c.jsx("div",{ref:r,"data-ssgoi-root":"",style:a,children:u})});exports.Ssgoi=l;

package/dist/lib/ssgoi.js

@@ -1,17 +1,20 @@
 "use client";
-import { jsx as m } from "react/jsx-runtime";
-import i, { useMemo as s } from "react";
-import { SsgoiProvider as n } from "./context.js";
-import { createSggoiTransitionContext as p } from "@ssgoi/core/internal";
-const u = i.memo(
-  ({ config: o, host: r, children: t }) => {
-    const e = s(
-      () => p(o, { host: r }),
-      [o, r]
+import { jsx as i } from "react/jsx-runtime";
+import c, { useRef as m, useMemo as f, useEffect as u } from "react";
+import { createSggoiTransitionContext as a, observeSsgoiTransitions as g } from "@ssgoi/core/internal";
+const l = { display: "contents" }, x = c.memo(
+  ({ config: o, host: t, children: n }) => {
+    const r = m(null), e = f(
+      () => a(o, { host: t }),
+      [o, t]
     );
-    return /* @__PURE__ */ m(n, { value: e, children: t });
+    return u(() => {
+      const s = r.current;
+      if (s)
+        return g(s, e);
+    }, [e]), /* @__PURE__ */ i("div", { ref: r, "data-ssgoi-root": "", style: l, children: n });
   }
 );
 export {
-  u as Ssgoi
+  x as Ssgoi
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ssgoi/react",
-  "version": "6.3.0",
+  "version": "6.5.0-beta.0",
   "description": "React bindings for SSGOI - Native app-like page transitions for React applications",
   "private": false,
   "type": "module",
@@ -66,7 +66,7 @@
   "dependencies": {
     "unplugin": "^2.3.2",
     "@babel/core": "^7.26.10",
-    "@ssgoi/core": "^6.3.0"
+    "@ssgoi/core": "^6.5.0-beta.0"
   },
   "devDependencies": {
     "@types/babel__core": "^7.20.5",

package/dist/lib/context.cjs

@@ -1,2 +0,0 @@
-"use client";
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const o=require("react"),t=o.createContext(null),r=t.Provider,s=()=>{const e=o.useContext(t);if(!e)throw new Error("useSsgoi must be used within Ssgoi provider");return e};exports.SsgoiProvider=r;exports.useSsgoi=s;

package/dist/lib/context.d.ts

@@ -1,3 +0,0 @@
-import { SsgoiContext } from '@ssgoi/core/types';
-export declare const SsgoiProvider: import('react').Provider<SsgoiContext | null>;
-export declare const useSsgoi: () => SsgoiContext;

package/dist/lib/context.js

@@ -1,11 +0,0 @@
-"use client";
-import { createContext as e, useContext as r } from "react";
-const t = e(null), n = t.Provider, i = () => {
-  const o = r(t);
-  if (!o) throw new Error("useSsgoi must be used within Ssgoi provider");
-  return o;
-};
-export {
-  n as SsgoiProvider,
-  i as useSsgoi
-};