@ssgoi/react 3.3.0 → 4.0.0

package/README.md

@@ -33,15 +33,13 @@ pnpm add @ssgoi/react
 ### 1. Wrap your app
 
 ```tsx
-import { Ssgoi } from '@ssgoi/react';
-import { fade } from '@ssgoi/react/view-transitions';
+import { Ssgoi } from "@ssgoi/react";
+import { fade } from "@ssgoi/react/view-transitions";
 
 export default function App() {
   return (
     <Ssgoi config={{ defaultTransition: fade() }}>
-      <div style={{ position: 'relative' }}>
-        {/* Your app */}
-      </div>
+      <div style={{ position: "relative" }}>{/* Your app */}</div>
     </Ssgoi>
   );
 }
@@ -50,7 +48,7 @@ export default function App() {
 ### 2. Wrap your pages
 
 ```tsx
-import { SsgoiTransition } from '@ssgoi/react';
+import { SsgoiTransition } from "@ssgoi/react";
 
 export default function HomePage() {
   return (
@@ -74,16 +72,20 @@ Define different transitions for different routes:
 const config = {
   transitions: [
     // Scroll between tabs
-    { from: '/home', to: '/about', transition: scroll({ direction: 'up' }) },
-    { from: '/about', to: '/home', transition: scroll({ direction: 'down' }) },
-    
+    { 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' }) },
-    
+    {
+      from: "/products",
+      to: "/products/*",
+      transition: drill({ direction: "enter" }),
+    },
+
     // Pinterest-style image transitions
-    { from: '/gallery', to: '/photo/*', transition: pinterest() }
+    { from: "/gallery", to: "/photo/*", transition: pinterest() },
   ],
-  defaultTransition: fade()
+  defaultTransition: fade(),
 };
 ```
 
@@ -94,7 +96,7 @@ Automatically create bidirectional transitions:
 ```tsx
 {
   from: '/home',
-  to: '/about', 
+  to: '/about',
   transition: scroll({ direction: 'up' }),
   symmetric: true  // Automatically creates reverse transition
 }
@@ -105,16 +107,18 @@ Automatically create bidirectional transitions:
 Animate specific elements during mount/unmount:
 
 ```tsx
-import { transition } from '@ssgoi/react';
-import { fade, slide } from '@ssgoi/react/transitions';
+import { transition } from "@ssgoi/react";
+import { fade, slide } from "@ssgoi/react/transitions";
 
 function Card() {
   return (
-    <div ref={transition({
-      key: 'card',
-      in: fade(),
-      out: slide({ direction: 'up' })
-    })}>
+    <div
+      ref={transition({
+        key: "card",
+        in: fade(),
+        out: slide({ direction: "up" }),
+      })}
+    >
       <h2>Animated Card</h2>
     </div>
   );
@@ -126,11 +130,12 @@ function Card() {
 The Auto Key Plugin automatically generates unique keys for your transitions based on the file location (`file:line:column`), eliminating the need to manually provide keys.
 
 **Benefits:**
+
 - **Automatic Key Generation**: No need to manually specify `key` in `transition()` calls
 - **Collision-Free**: Keys are based on exact code location
 - **Cleaner Code**: Less boilerplate in your components
 
-**⚠️ Important**: For list items rendered with `.map()`, always provide an explicit `key` for stability. The plugin cannot guarantee stable keys for dynamically generated elements.
+**⚠️ Important**: For list items rendered with `.map()`, just use JSX key prop - the plugin automatically appends it to generate unique keys.
 
 #### Setup with Next.js
 
@@ -153,8 +158,8 @@ export default nextConfig;
 
 ```ts
 // vite.config.ts
-import { defineConfig } from 'vite';
-import react from '@vitejs/plugin-react';
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
 import SsgoiAutoKey from "@ssgoi/react/unplugin/vite";
 
 export default defineConfig({
@@ -165,19 +170,11 @@ export default defineConfig({
 #### Usage Examples
 
 **WITH Auto Key Plugin (Recommended):**
-```tsx
-import { transition } from '@ssgoi/react';
-import { fade, slide } from '@ssgoi/react/transitions';
 
-function Card() {
-  return (
-    <div ref={transition({ in: fade(), out: slide({ direction: 'up' }) })}>
-      <h2>Animated Card</h2>
-    </div>
-  );
-}
+```tsx
+import { transition } from "@ssgoi/react";
+import { fade, slide } from "@ssgoi/react/transitions";
 
-// Even simpler with single transition
 function SimpleCard() {
   return (
     <div ref={transition(fade())}>
@@ -188,35 +185,34 @@ function SimpleCard() {
 ```
 
 **WITHOUT Auto Key Plugin:**
+
 ```tsx
 // Explicit key required for transition state tracking
 function Card() {
   return (
-    <div ref={transition({
-      key: 'my-card',
-      in: fade(),
-      out: slide({ direction: 'up' })
-    })}>
+    <div
+      ref={transition({
+        key: "my-card",
+        ...fade(),
+      })}
+    >
       <h2>Animated Card</h2>
     </div>
   );
 }
 ```
 
-**List Items (Always Use Explicit Keys):**
+**List Items:**
+
 ```tsx
-// For list items, always provide explicit keys for stability
+// In .map() lists, just use JSX key - the plugin appends it automatically
 function List() {
   return (
     <ul>
       {items.map((item) => (
         <li
-          key={item.id}
-          ref={transition({
-            key: `list-item-${item.id}`,
-            in: fade(),
-            out: slide({ direction: 'up' })
-          })}
+          key={item.id} // JSX key is enough - plugin generates file:line:col:${key}
+          ref={transition(fade())}
         >
           {item.name}
         </li>
@@ -230,17 +226,19 @@ function List() {
 
 ```tsx
 // app/layout.tsx
-import { Ssgoi } from '@ssgoi/react';
-import { scroll } from '@ssgoi/react/view-transitions';
+import { Ssgoi } from "@ssgoi/react";
+import { scroll } from "@ssgoi/react/view-transitions";
 
 export default function RootLayout({ children }) {
   return (
     <html>
       <body>
-        <Ssgoi config={{
-          defaultTransition: scroll({ direction: 'up' })
-        }}>
-          <div style={{ position: 'relative', minHeight: '100vh' }}>
+        <Ssgoi
+          config={{
+            defaultTransition: scroll({ direction: "up" }),
+          }}
+        >
+          <div style={{ position: "relative", minHeight: "100vh" }}>
             {children}
           </div>
         </Ssgoi>
@@ -250,14 +248,10 @@ export default function RootLayout({ children }) {
 }
 
 // app/page.tsx
-import { SsgoiTransition } from '@ssgoi/react';
+import { SsgoiTransition } from "@ssgoi/react";
 
 export default function Page() {
-  return (
-    <SsgoiTransition id="/">
-      {/* Your page content */}
-    </SsgoiTransition>
-  );
+  return <SsgoiTransition id="/">{/* Your page content */}</SsgoiTransition>;
 }
 ```
 
@@ -266,26 +260,25 @@ export default function Page() {
 ### Components
 
 #### `<Ssgoi>`
+
 The provider component that manages transition context.
 
 ```tsx
-<Ssgoi config={ssgoiConfig}>
-  {children}
-</Ssgoi>
+<Ssgoi config={ssgoiConfig}>{children}</Ssgoi>
 ```
 
 #### `<SsgoiTransition>`
+
 Wrapper component for pages that should transition.
 
 ```tsx
-<SsgoiTransition id="/page-id">
-  {children}
-</SsgoiTransition>
+<SsgoiTransition id="/page-id">{children}</SsgoiTransition>
 ```
 
 ### Hooks
 
 #### `useTransition()`
+
 Access transition state and controls.
 
 ```tsx
@@ -295,14 +288,17 @@ const { isTransitioning, direction } = useTransition();
 ### Functions
 
 #### `transition()`
+
 Apply transitions to individual elements.
 
 ```tsx
-<div ref={transition({
-  key: 'unique-key',
-  in: fade(),
-  out: fade()
-})}>
+<div
+  ref={transition({
+    key: "unique-key",
+    in: fade(),
+    out: fade(),
+  })}
+>
   Content
 </div>
 ```
@@ -310,6 +306,7 @@ Apply transitions to individual elements.
 ## Built-in Transitions
 
 ### Page Transitions (`@ssgoi/react/view-transitions`)
+
 - `fade()` - Smooth opacity transition
 - `scroll()` - Vertical scrolling (up/down)
 - `drill()` - Drill in/out effect (enter/exit)
@@ -317,6 +314,7 @@ Apply transitions to individual elements.
 - `pinterest()` - Pinterest-style expand effect
 
 ### Element Transitions (`@ssgoi/react/transitions`)
+
 - `fade()` - Fade in/out
 - `scale()` - Scale in/out
 - `slide()` - Slide (direction: up/down/left/right)
@@ -331,12 +329,12 @@ All transitions use spring physics for natural motion:
 
 ```tsx
 slide({
-  direction: 'left',
+  direction: "left",
   spring: {
-    stiffness: 300,  // 1-1000, higher = faster
-    damping: 30      // 0-100, higher = less oscillation
-  }
-})
+    stiffness: 300, // 1-1000, higher = faster
+    damping: 30, // 0-100, higher = less oscillation
+  },
+});
 ```
 
 ## TypeScript Support
@@ -344,7 +342,7 @@ slide({
 SSGOI is written in TypeScript and provides full type definitions:
 
 ```tsx
-import type { SsgoiConfig, TransitionConfig } from '@ssgoi/react';
+import type { SsgoiConfig, TransitionConfig } from "@ssgoi/react";
 
 const config: SsgoiConfig = {
   // Full type safety
@@ -368,6 +366,7 @@ const config: SsgoiConfig = {
 ## Documentation
 
 Visit [https://ssgoi.dev](https://ssgoi.dev) for:
+
 - Complete API reference
 - Interactive examples
 - Advanced patterns
@@ -379,4 +378,4 @@ We welcome contributions! Please see our [contributing guide](https://github.com
 
 ## License
 
-MIT © [MeurSyphus](https://github.com/meursyphus)
+MIT © [MeurSyphus](https://github.com/meursyphus)

package/dist/core/dist/types.cjs

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});function h(e){return("tick"in e||"css"in e)&&!("springs"in e)}function s(e){return"springs"in e}function o(e){return"css"in e&&typeof e.css=="function"}function a(e){return"tick"in e&&typeof e.tick=="function"}function c(e){if(o(e)&&a(e))throw new Error("SingleSpringConfig cannot have both 'tick' and 'css' defined. Use one or the other.")}function l(e){if(e.tick&&e.css)throw new Error("SpringItem cannot have both 'tick' and 'css' defined. Use one or the other.")}async function m(e){const n=await e;return s(n)?(n.springs.forEach(l),n):(c(n),{prepare:n.prepare,wait:n.wait,onStart:n.onStart,onEnd:n.onEnd,springs:[{spring:n.spring,tick:n.tick,css:n.css}],schedule:"parallel"})}function S(e,n){const u=e.schedule??"parallel",f=e.springs.map(r=>{let t;switch(u){case"parallel":t=0;break;case"sequential":t=1;break;case"stagger":t=Math.max(0,Math.min(1,r.offset??0));break;default:t=0}const{css:i,offset:w,...g}=r,d=i?typeof i=="function"?n?{element:n,style:i}:void 0:{element:i.element,style:i.style}:void 0;return{...g,css:d,normalizedOffset:t}}),{schedule:k,...p}=e;return{...p,springs:f}}exports.isCssAnimation=o;exports.isMultiSpring=s;exports.isSingleSpring=h;exports.isTickAnimation=a;exports.normalizeMultiSpringSchedule=S;exports.normalizeToMultiSpring=m;exports.validateAnimationMode=c;exports.validateSpringItem=l;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});function h(e){return("tick"in e||"css"in e)&&!("springs"in e)}function r(e){return"springs"in e}function o(e){return"css"in e&&typeof e.css=="function"}function c(e){return"tick"in e&&typeof e.tick=="function"}function a(e){if(o(e)&&c(e))throw new Error("SingleSpringConfig cannot have both 'tick' and 'css' defined. Use one or the other.")}function l(e){if(e.tick&&e.css)throw new Error("SpringItem cannot have both 'tick' and 'css' defined. Use one or the other.")}async function m(e){const t=await e;return r(t)?(t.springs.forEach(l),t):(a(t),{prepare:t.prepare,wait:t.wait,onStart:t.onStart,onEnd:t.onEnd,springs:[{physics:t.physics,tick:t.tick,css:t.css}],schedule:"parallel"})}function S(e,t){const u=e.schedule??"parallel",f=e.springs.map(s=>{let n;switch(u){case"parallel":n=0;break;case"sequential":n=1;break;case"stagger":n=Math.max(0,Math.min(1,s.offset??0));break;default:n=0}const{css:i,offset:y,...d}=s,g=i?typeof i=="function"?t?{element:t,style:i}:void 0:{element:i.element,style:i.style}:void 0;return{...d,css:g,normalizedOffset:n}}),{schedule:k,...p}=e;return{...p,springs:f}}exports.isCssAnimation=o;exports.isMultiSpring=r;exports.isSingleSpring=h;exports.isTickAnimation=c;exports.normalizeMultiSpringSchedule=S;exports.normalizeToMultiSpring=m;exports.validateAnimationMode=a;exports.validateSpringItem=l;

package/dist/core/dist/types.js

@@ -10,7 +10,7 @@ function p(n) {
 function u(n) {
   return "tick" in n && typeof n.tick == "function";
 }
-function g(n) {
+function h(n) {
   if (p(n) && u(n))
     throw new Error(
       "SingleSpringConfig cannot have both 'tick' and 'css' defined. Use one or the other."
@@ -24,14 +24,14 @@ function d(n) {
 }
 async function S(n) {
   const e = await n;
-  return f(e) ? (e.springs.forEach(d), e) : (g(e), {
+  return f(e) ? (e.springs.forEach(d), e) : (h(e), {
     prepare: e.prepare,
     wait: e.wait,
     onStart: e.onStart,
     onEnd: e.onEnd,
     springs: [
       {
-        spring: e.spring,
+        physics: e.physics,
         tick: e.tick,
         css: e.css
       }
@@ -39,7 +39,7 @@ async function S(n) {
     schedule: "parallel"
   });
 }
-function w(n, e) {
+function y(n, e) {
   const r = n.schedule ?? "parallel", a = n.springs.map(
     (s) => {
       let t;
@@ -59,7 +59,7 @@ function w(n, e) {
       const { css: i, offset: m, ...c } = s, l = i ? typeof i == "function" ? e ? { element: e, style: i } : void 0 : { element: i.element, style: i.style } : void 0;
       return { ...c, css: l, normalizedOffset: t };
     }
-  ), { schedule: h, ...o } = n;
+  ), { schedule: g, ...o } = n;
   return {
     ...o,
     springs: a
@@ -70,8 +70,8 @@ export {
   f as isMultiSpring,
   k as isSingleSpring,
   u as isTickAnimation,
-  w as normalizeMultiSpringSchedule,
+  y as normalizeMultiSpringSchedule,
   S as normalizeToMultiSpring,
-  g as validateAnimationMode,
+  h as validateAnimationMode,
   d as validateSpringItem
 };

package/dist/react/src/lib/transition.cjs

@@ -1,2 +1,2 @@
 "use client";
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const t=require("@ssgoi/core"),i=r=>{if(!r.key)throw new Error("[ssgoi] transition() requires a 'key' property. Either provide it manually or use plugin for auto-injection. import plugin from @ssgoi/react/unplugin/webpack; ");return t.transition(r,"auto")};exports.transition=i;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const r=require("@ssgoi/core"),t=e=>{if(!e.key)throw new Error("[ssgoi] transition() requires a 'key' property. Either provide it manually or use plugin for auto-injection. import plugin from @ssgoi/react/unplugin/webpack; see: https://ssgoi.dev/en/docs/core-concepts/react-plugin");return r.transition(e,"auto")};exports.transition=t;

package/dist/react/src/lib/transition.js

@@ -1,11 +1,11 @@
 "use client";
-import { transition as i } from "@ssgoi/core";
+import { transition as t } from "@ssgoi/core";
 const o = (r) => {
   if (!r.key)
     throw new Error(
-      "[ssgoi] transition() requires a 'key' property. Either provide it manually or use plugin for auto-injection. import plugin from @ssgoi/react/unplugin/webpack; "
+      "[ssgoi] transition() requires a 'key' property. Either provide it manually or use plugin for auto-injection. import plugin from @ssgoi/react/unplugin/webpack; see: https://ssgoi.dev/en/docs/core-concepts/react-plugin"
     );
-  return i(
+  return t(
     r,
     "auto"
   );

package/package.json

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