@ssgoi/react 3.2.1 → 3.3.0

package/README.md

@@ -106,14 +106,14 @@ Animate specific elements during mount/unmount:
 
 ```tsx
 import { transition } from '@ssgoi/react';
-import { fadeIn, slideUp } from '@ssgoi/react/transitions';
+import { fade, slide } from '@ssgoi/react/transitions';
 
 function Card() {
   return (
     <div ref={transition({
       key: 'card',
-      in: fadeIn(),
-      out: slideUp()
+      in: fade(),
+      out: slide({ direction: 'up' })
     })}>
       <h2>Animated Card</h2>
     </div>
@@ -121,6 +121,111 @@ function Card() {
 }
 ```
 
+### Auto Key Plugin
+
+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.
+
+#### Setup with Next.js
+
+```tsx
+// next.config.ts
+import type { NextConfig } from "next";
+import SsgoiAutoKey from "@ssgoi/react/unplugin/webpack";
+
+const nextConfig: NextConfig = {
+  webpack: (config) => {
+    config.plugins.push(SsgoiAutoKey());
+    return config;
+  },
+};
+
+export default nextConfig;
+```
+
+#### Setup with Vite
+
+```ts
+// vite.config.ts
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import SsgoiAutoKey from "@ssgoi/react/unplugin/vite";
+
+export default defineConfig({
+  plugins: [react(), SsgoiAutoKey()],
+});
+```
+
+#### 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>
+  );
+}
+
+// Even simpler with single transition
+function SimpleCard() {
+  return (
+    <div ref={transition(fade())}>
+      <h2>Fades in on mount</h2>
+    </div>
+  );
+}
+```
+
+**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' })
+    })}>
+      <h2>Animated Card</h2>
+    </div>
+  );
+}
+```
+
+**List Items (Always Use Explicit Keys):**
+```tsx
+// For list items, always provide explicit keys for stability
+function List() {
+  return (
+    <ul>
+      {items.map((item) => (
+        <li
+          key={item.id}
+          ref={transition({
+            key: `list-item-${item.id}`,
+            in: fade(),
+            out: slide({ direction: 'up' })
+          })}
+        >
+          {item.name}
+        </li>
+      ))}
+    </ul>
+  );
+}
+```
+
 ## Next.js App Router Example
 
 ```tsx
@@ -195,8 +300,8 @@ Apply transitions to individual elements.
 ```tsx
 <div ref={transition({
   key: 'unique-key',
-  in: fadeIn(),
-  out: fadeOut()
+  in: fade(),
+  out: fade()
 })}>
   Content
 </div>
@@ -212,12 +317,13 @@ Apply transitions to individual elements.
 - `pinterest()` - Pinterest-style expand effect
 
 ### Element Transitions (`@ssgoi/react/transitions`)
-- `fadeIn()` / `fadeOut()`
-- `slideUp()` / `slideDown()` / `slideLeft()` / `slideRight()`
-- `scaleIn()` / `scaleOut()`
-- `bounce()`
-- `blur()`
-- `rotate()`
+- `fade()` - Fade in/out
+- `scale()` - Scale in/out
+- `slide()` - Slide (direction: up/down/left/right)
+- `rotate()` - Rotate
+- `bounce()` - Bounce
+- `blur()` - Blur
+- `fly()` - Fly (custom x, y position)
 
 ## Spring Physics Configuration
 

package/dist/index.d.ts

@@ -1,5 +1,2 @@
-export { transition } from './transition';
-export * from './types';
-export { Ssgoi } from './ssgoi';
-export { SsgoiTransition } from './ssgoi-transition';
-export { TransitionScope } from './transition-scope';
+export * from './lib/index'
+export {}

package/dist/lib/index.d.ts

@@ -0,0 +1,5 @@
+export { transition } from './transition';
+export * from './types';
+export { Ssgoi } from './ssgoi';
+export { SsgoiTransition } from './ssgoi-transition';
+export { TransitionScope } from './transition-scope';

package/dist/lib/presets/index.d.ts

@@ -0,0 +1 @@
+export * from '@ssgoi/core/presets';

package/dist/{transition.d.ts → lib/transition.d.ts}

@@ -2,7 +2,6 @@ import { Transition, TransitionKey, TransitionScope } from '@ssgoi/core';
 type TransitionOptions = Transition<undefined> & {
     key?: TransitionKey;
     scope?: TransitionScope;
-    ref?: object;
 };
 /**
  * React ref callback for element transitions
@@ -10,6 +9,12 @@ type TransitionOptions = Transition<undefined> & {
  * OUT transition is automatically triggered by MutationObserver
  * when the element is removed from the DOM - works with React 18+
  *
+ * The returned ref callback has a stable reference (cached by key),
+ * so it won't cause unnecessary re-renders when used with React refs.
+ *
+ * Note: key is optional in the type signature because it can be auto-injected
+ * by babel-plugin-ssgoi at build time. However, it is required at runtime.
+ *
  * @example
  * ```tsx
  * <div ref={transition({
@@ -19,5 +24,5 @@ type TransitionOptions = Transition<undefined> & {
  * })} />
  * ```
  */
-export declare const transition: (options: TransitionOptions) => (element: HTMLElement | null) => void;
+export declare const transition: (options: TransitionOptions) => import('@ssgoi/core').RefCallback;
 export {};

package/dist/lib/transitions/index.d.ts

@@ -0,0 +1 @@
+export * from '@ssgoi/core/transitions';

package/dist/lib/types.d.ts

@@ -0,0 +1 @@
+export * from '@ssgoi/core/types';

package/dist/lib/view-transitions/index.d.ts

@@ -0,0 +1 @@
+export * from '@ssgoi/core/view-transitions';

package/dist/presets/index.d.ts

@@ -1 +1,2 @@
-export * from '@ssgoi/core/presets';
+export * from '../lib/presets/index'
+export {}

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

@@ -1,2 +1,2 @@
 "use client";
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const o=require("@ssgoi/core"),c=i=>{const r=o.transition(i);return t=>{if(t){const n=r(t);n&&o.watchUnmount(t,n)}}};exports.transition=c;
+"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;

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

@@ -1,14 +1,15 @@
 "use client";
-import { transition as a, watchUnmount as r } from "@ssgoi/core";
-const s = (o) => {
-  const i = a(o);
-  return (t) => {
-    if (t) {
-      const n = i(t);
-      n && r(t, n);
-    }
-  };
+import { transition as i } 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; "
+    );
+  return i(
+    r,
+    "auto"
+  );
 };
 export {
-  s as transition
+  o as transition
 };

package/dist/transitions/index.d.ts

@@ -1 +1,2 @@
-export * from '@ssgoi/core/transitions';
+export * from '../lib/transitions/index'
+export {}

package/dist/types.d.ts

@@ -1 +1,2 @@
-export * from '@ssgoi/core/types';
+export * from './lib/types'
+export {}

package/dist/unplugin/esbuild.cjs

@@ -0,0 +1 @@
+"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});const e=require("./index.cjs"),u=e.unplugin.esbuild;exports.default=u;

package/dist/unplugin/esbuild.d.ts

@@ -0,0 +1,2 @@
+declare const _default: (options?: import('./index').SsgoiAutoKeyOptions | undefined) => import('esbuild').Plugin;
+export default _default;

package/dist/unplugin/esbuild.js

@@ -0,0 +1,5 @@
+import { unplugin as u } from "./index.js";
+const i = u.esbuild;
+export {
+  i as default
+};

package/dist/unplugin/index.cjs

@@ -0,0 +1 @@
+"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});const S=require("unplugin"),j=require("@babel/core"),P={include:[".tsx",".jsx"],exclude:[/node_modules/]};function h(){return function({types:e}){return{name:"babel-plugin-ssgoi-auto-key",visitor:{CallExpression(r,l){const n=r.node.callee;if(!e.isIdentifier(n)||n.name!=="transition"||r.node._ssgoiProcessed)return;r.node._ssgoiProcessed=!0;const a=r.node.arguments;if(a.length===0)return;const s=a[0];if(e.isObjectExpression(s)&&s.properties.length>=2&&e.isSpreadElement(s.properties[0])&&e.isObjectProperty(s.properties[s.properties.length-1])&&e.isIdentifier(s.properties[s.properties.length-1].key)&&s.properties[s.properties.length-1].key.name==="key")return;const d=l.filename||"unknown",x=d.split("/").pop()||d,m=r.node.loc,b=m?.start?.line??0,k=m?.start?.column??0,c=`${x}:${b}:${k}`;let u=null;const p=r.findParent(i=>i.isJSXElement()||i.isJSXFragment());if(p&&e.isJSXElement(p.node)){const i=p.node.openingElement.attributes.find(t=>e.isJSXAttribute(t)&&e.isJSXIdentifier(t.name)&&t.name.name==="key");i&&(e.isJSXExpressionContainer(i.value)?e.isJSXEmptyExpression(i.value.expression)||(u=i.value.expression):e.isStringLiteral(i.value)&&(u=i.value))}let f;u?f=e.templateLiteral([e.templateElement({raw:`${c}:`,cooked:`${c}:`}),e.templateElement({raw:"",cooked:""},!0)],[u]):f=e.stringLiteral(c);const g=e.objectProperty(e.identifier("key"),f);if(e.isObjectExpression(s)){if(s.properties.some(t=>e.isObjectProperty(t)&&e.isIdentifier(t.key)&&t.key.name==="key"))return;s.properties.push(g)}else e.isExpression(s)&&!e.isSpreadElement(s)&&(a[0]=e.objectExpression([e.spreadElement(s),g]))}}}}}function y(o,e){return e.include.some(n=>o.endsWith(n))?!e.exclude.some(n=>typeof n=="string"?o.includes(n):n.test(o)):!1}const v=o=>{const e={...P,...o};return{name:"unplugin-ssgoi-auto-key",enforce:"pre",transformInclude(r){return y(r,e)},transform(r,l){if(!y(l,e))return null;try{const n=j.transformSync(r,{filename:l,plugins:[h()],parserOpts:{plugins:["jsx","typescript"]},generatorOpts:{retainLines:!0},sourceMaps:!0,configFile:!1,babelrc:!1});if(n&&n.code)return{code:n.code,map:n.map}}catch(n){console.error(`[unplugin-ssgoi-auto-key] Error transforming ${l}:`,n)}return null}}},E=S.createUnplugin(v);exports.default=E;exports.unplugin=E;

package/dist/unplugin/index.d.ts

@@ -0,0 +1,14 @@
+export interface SsgoiAutoKeyOptions {
+    /**
+     * File extensions to process
+     * @default ['.tsx', '.jsx']
+     */
+    include?: string[];
+    /**
+     * File patterns to exclude
+     * @default [/node_modules/]
+     */
+    exclude?: (string | RegExp)[];
+}
+export declare const unplugin: import('unplugin').UnpluginInstance<SsgoiAutoKeyOptions | undefined, boolean>;
+export default unplugin;

package/dist/unplugin/index.js

@@ -0,0 +1,116 @@
+import { createUnplugin as b } from "unplugin";
+import { transformSync as S } from "@babel/core";
+const j = {
+  include: [".tsx", ".jsx"],
+  exclude: [/node_modules/]
+};
+function P() {
+  return function({
+    types: e
+  }) {
+    return {
+      name: "babel-plugin-ssgoi-auto-key",
+      visitor: {
+        CallExpression(r, l) {
+          const n = r.node.callee;
+          if (!e.isIdentifier(n) || n.name !== "transition" || r.node._ssgoiProcessed)
+            return;
+          r.node._ssgoiProcessed = !0;
+          const a = r.node.arguments;
+          if (a.length === 0)
+            return;
+          const s = a[0];
+          if (e.isObjectExpression(s) && s.properties.length >= 2 && e.isSpreadElement(s.properties[0]) && e.isObjectProperty(
+            s.properties[s.properties.length - 1]
+          ) && e.isIdentifier(
+            s.properties[s.properties.length - 1].key
+          ) && s.properties[s.properties.length - 1].key.name === "key")
+            return;
+          const m = l.filename || "unknown", x = m.split("/").pop() || m, d = r.node.loc, E = d?.start?.line ?? 0, k = d?.start?.column ?? 0, c = `${x}:${E}:${k}`;
+          let u = null;
+          const p = r.findParent(
+            (i) => i.isJSXElement() || i.isJSXFragment()
+          );
+          if (p && e.isJSXElement(p.node)) {
+            const i = p.node.openingElement.attributes.find(
+              (t) => e.isJSXAttribute(t) && e.isJSXIdentifier(t.name) && t.name.name === "key"
+            );
+            i && (e.isJSXExpressionContainer(i.value) ? e.isJSXEmptyExpression(i.value.expression) || (u = i.value.expression) : e.isStringLiteral(i.value) && (u = i.value));
+          }
+          let f;
+          u ? f = e.templateLiteral(
+            [
+              e.templateElement({
+                raw: `${c}:`,
+                cooked: `${c}:`
+              }),
+              e.templateElement({ raw: "", cooked: "" }, !0)
+            ],
+            [u]
+          ) : f = e.stringLiteral(c);
+          const g = e.objectProperty(e.identifier("key"), f);
+          if (e.isObjectExpression(s)) {
+            if (s.properties.some(
+              (t) => e.isObjectProperty(t) && e.isIdentifier(t.key) && t.key.name === "key"
+            ))
+              return;
+            s.properties.push(g);
+          } else e.isExpression(s) && !e.isSpreadElement(s) && (a[0] = e.objectExpression([
+            e.spreadElement(s),
+            g
+          ]));
+        }
+      }
+    };
+  };
+}
+function y(o, e) {
+  return e.include.some((n) => o.endsWith(n)) ? !e.exclude.some((n) => typeof n == "string" ? o.includes(n) : n.test(o)) : !1;
+}
+const h = (o) => {
+  const e = {
+    ...j,
+    ...o
+  };
+  return {
+    name: "unplugin-ssgoi-auto-key",
+    enforce: "pre",
+    transformInclude(r) {
+      return y(r, e);
+    },
+    transform(r, l) {
+      if (!y(l, e))
+        return null;
+      try {
+        const n = S(r, {
+          filename: l,
+          plugins: [P()],
+          parserOpts: {
+            plugins: ["jsx", "typescript"]
+          },
+          generatorOpts: {
+            retainLines: !0
+          },
+          sourceMaps: !0,
+          configFile: !1,
+          babelrc: !1
+        });
+        if (n && n.code)
+          return {
+            code: n.code,
+            map: n.map
+          };
+      } catch (n) {
+        console.error(
+          `[unplugin-ssgoi-auto-key] Error transforming ${l}:`,
+          n
+        );
+      }
+      return null;
+    }
+  };
+}, X = /* @__PURE__ */ b(h);
+export {
+  X as default,
+  X as unplugin
+};

package/dist/unplugin/rollup.cjs

@@ -0,0 +1 @@
+"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});const e=require("./index.cjs"),u=e.unplugin.rollup;exports.default=u;

package/dist/unplugin/rollup.d.ts

@@ -0,0 +1,2 @@
+declare const _default: (options?: import('./index').SsgoiAutoKeyOptions | undefined) => import('rollup').Plugin<any> | import('rollup').Plugin<any>[];
+export default _default;

package/dist/unplugin/rollup.js

@@ -0,0 +1,5 @@
+import { unplugin as l } from "./index.js";
+const p = l.rollup;
+export {
+  p as default
+};

package/dist/unplugin/vite.cjs

@@ -0,0 +1 @@
+"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});const e=require("./index.cjs"),t=e.unplugin.vite;exports.default=t;

package/dist/unplugin/vite.d.ts

@@ -0,0 +1,2 @@
+declare const _default: (options?: import('./index').SsgoiAutoKeyOptions | undefined) => import('vite').Plugin<any> | import('vite').Plugin<any>[];
+export default _default;

package/dist/unplugin/vite.js

@@ -0,0 +1,5 @@
+import { unplugin as t } from "./index.js";
+const i = t.vite;
+export {
+  i as default
+};

package/dist/unplugin/webpack.cjs

@@ -0,0 +1 @@
+"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});const e=require("./index.cjs"),u=e.unplugin.webpack;exports.default=u;

package/dist/unplugin/webpack.d.ts

@@ -0,0 +1,2 @@
+declare const _default: (options?: import('./index').SsgoiAutoKeyOptions | undefined) => import('webpack').WebpackPluginInstance;
+export default _default;

package/dist/unplugin/webpack.js

@@ -0,0 +1,5 @@
+import { unplugin as p } from "./index.js";
+const e = p.webpack;
+export {
+  e as default
+};

package/dist/view-transitions/index.d.ts

@@ -1 +1,2 @@
-export * from '@ssgoi/core/view-transitions';
+export * from '../lib/view-transitions/index'
+export {}

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@ssgoi/react",
-  "version": "3.2.1",
+  "version": "3.3.0",
   "description": "React bindings for SSGOI - Native app-like page transitions for React applications",
   "private": false,
   "type": "module",
   "files": [
     "dist",
+    "plugin",
     "!dist/**/*.test.*",
     "!dist/**/*.spec.*"
   ],
@@ -42,12 +43,45 @@
       "import": "./dist/presets/index.js",
       "require": "./dist/presets/index.cjs",
       "default": "./dist/presets/index.js"
+    },
+    "./unplugin": {
+      "types": "./dist/unplugin/index.d.ts",
+      "import": "./dist/unplugin/index.js",
+      "require": "./dist/unplugin/index.cjs",
+      "default": "./dist/unplugin/index.js"
+    },
+    "./unplugin/webpack": {
+      "types": "./dist/unplugin/webpack.d.ts",
+      "import": "./dist/unplugin/webpack.js",
+      "require": "./dist/unplugin/webpack.cjs",
+      "default": "./dist/unplugin/webpack.js"
+    },
+    "./unplugin/vite": {
+      "types": "./dist/unplugin/vite.d.ts",
+      "import": "./dist/unplugin/vite.js",
+      "require": "./dist/unplugin/vite.cjs",
+      "default": "./dist/unplugin/vite.js"
+    },
+    "./unplugin/rollup": {
+      "types": "./dist/unplugin/rollup.d.ts",
+      "import": "./dist/unplugin/rollup.js",
+      "require": "./dist/unplugin/rollup.cjs",
+      "default": "./dist/unplugin/rollup.js"
+    },
+    "./unplugin/esbuild": {
+      "types": "./dist/unplugin/esbuild.d.ts",
+      "import": "./dist/unplugin/esbuild.js",
+      "require": "./dist/unplugin/esbuild.cjs",
+      "default": "./dist/unplugin/esbuild.js"
     }
   },
   "dependencies": {
-    "@ssgoi/core": "^3.2.0"
+    "unplugin": "^2.3.2",
+    "@babel/core": "^7.26.10",
+    "@ssgoi/core": "^3.3.0"
   },
   "devDependencies": {
+    "@types/babel__core": "^7.20.5",
     "@eslint/js": "^9.30.1",
     "@types/react": "^19.1.8",
     "@types/react-dom": "^19.1.6",