@ssgoi/solid 6.4.0 → 6.6.4

package/README.md

@@ -0,0 +1,219 @@
+# @ssgoi/solid
+
+Solid bindings for SSGOI - Native app-like page transitions for Solid and SolidStart.
+
+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.
+
+### ✨ Key Features
+
+- **🌍 Works Everywhere** - Unlike the browser's View Transition API, SSGOI works in all modern browsers (Chrome, Firefox, Safari)
+- **🚀 SSR Ready** - Perfect compatibility with SolidStart. No hydration issues, SEO-friendly
+- **🎯 Use Your Router** - Keep your existing routing. `@solidjs/router` and SolidStart work seamlessly
+- **💾 State Persistence** - Remembers animation state during navigation, even with browser back/forward
+- **⚡ Solid Native** - Built on Solid's fine-grained reactivity, so change detection stays minimal
+
+## Installation
+
+```bash
+npm install @ssgoi/solid
+# or
+yarn add @ssgoi/solid
+# or
+pnpm add @ssgoi/solid
+```
+
+## Quick Start
+
+### 1. Wrap your app
+
+```tsx
+import { Ssgoi } from "@ssgoi/solid";
+import { fade } from "@ssgoi/solid/view-transitions";
+
+const config = {
+  transitions: [fade({ paths: ["/", "/about"] })],
+};
+
+export default function App(props) {
+  return (
+    <Ssgoi config={config}>
+      {/* position: relative + z-index: 0 are required (see below) */}
+      <div style="position: relative; z-index: 0; min-height: 100vh">
+        {props.children}
+      </div>
+    </Ssgoi>
+  );
+}
+```
+
+### 2. Mark your pages
+
+Set `data-ssgoi-transition` on each page boundary element inside `<Ssgoi>`:
+
+```tsx
+export default function Home() {
+  return (
+    <main data-ssgoi-transition="/">
+      <h1>Welcome</h1>
+      {/* Page content */}
+    </main>
+  );
+}
+```
+
+**That's it!** Your pages now transition smoothly with the configured effect.
+
+> **Why `position: relative; z-index: 0`?** 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. The clone needs a positioned, stacking-context ancestor or it jumps / falls behind the background. Add `overflow-x-clip` too if you use horizontal transitions (`slide`, `drill`).
+
+## Advanced Transitions
+
+Each transition factory returns a path-transition group. Drop the results straight into `config.transitions` — nested arrays are flattened automatically:
+
+```tsx
+import { Ssgoi } from "@ssgoi/solid";
+import { fade, drill, zoom } from "@ssgoi/solid/view-transitions";
+
+const config = {
+  transitions: [
+    // Calm cross-fade between tabs
+    fade({ paths: ["/", "/about"] }),
+
+    // iOS-style drill-in when entering a detail page
+    drill({ enter: "/products/*", exit: "/products" }),
+
+    // Card-to-detail zoom (needs matching data-zoom-*-key)
+    zoom({ paths: ["/gallery", "/photo/*"], type: "expand" }),
+  ],
+};
+```
+
+Transitions come in three shapes:
+
+- **`{ 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`)
+
+## SolidStart Example
+
+Wrap your root component once, then mark each route:
+
+```tsx
+// src/app.tsx
+import { Router } from "@solidjs/router";
+import { FileRoutes } from "@solidjs/start/router";
+import { Ssgoi } from "@ssgoi/solid";
+import { scroll } from "@ssgoi/solid/view-transitions";
+
+const config = {
+  transitions: [scroll({ paths: ["/", "/about", "/products"] })],
+};
+
+export default function App() {
+  return (
+    <Router
+      root={(props) => (
+        <Ssgoi config={config}>
+          <div style="position: relative; z-index: 0; min-height: 100vh">
+            {props.children}
+          </div>
+        </Ssgoi>
+      )}
+    >
+      <FileRoutes />
+    </Router>
+  );
+}
+```
+
+```tsx
+// src/routes/index.tsx
+export default function Index() {
+  return <main data-ssgoi-transition="/">{/* Your page content */}</main>;
+}
+```
+
+## API Reference
+
+### `<Ssgoi>`
+
+The provider component that manages transition context.
+
+```tsx
+<Ssgoi config={ssgoiConfig}>{/* children */}</Ssgoi>
+```
+
+Props:
+
+- `config: SsgoiConfig` - transition configuration object
+- `host?: HostAnimation` - optional external playback host for debug tooling
+
+### `data-ssgoi-transition`
+
+Attribute for pages that should transition. Set it on the page boundary element inside `<Ssgoi>` — the value (commonly the route path) uniquely identifies the view.
+
+```tsx
+<main data-ssgoi-transition="/page-id">{/* children */}</main>
+```
+
+## Built-in Transitions
+
+Import from `@ssgoi/solid/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
+
+## TypeScript Support
+
+SSGOI is written in TypeScript and provides full type definitions:
+
+```typescript
+import type { SsgoiConfig } from "@ssgoi/solid";
+
+const config: SsgoiConfig = {
+  // Full type safety
+};
+```
+
+## Browser Support
+
+- Chrome/Edge 88+
+- Firefox 78+
+- Safari 14+
+- All modern mobile browsers
+
+## License
+
+MIT © [MeurSyphus](https://github.com/meursyphus)
+
+## Links
+
+- [Documentation](https://ssgoi.dev)
+- [GitHub](https://github.com/meursyphus/ssgoi)
+- [Issues](https://github.com/meursyphus/ssgoi/issues)

package/package.json

@@ -1,11 +1,14 @@
 {
   "name": "@ssgoi/solid",
-  "version": "6.4.0",
+  "version": "6.6.4",
   "description": "Solid.js bindings for SSGOI - Native app-like page transitions for Solid applications",
   "private": false,
   "type": "module",
   "files": [
+    "src/lib",
     "dist",
+    "!src/**/*.test.*",
+    "!src/**/*.spec.*",
     "!dist/**/*.test.*",
     "!dist/**/*.spec.*"
   ],
@@ -14,18 +17,21 @@
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
+      "solid": "./src/lib/index.ts",
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
       "require": "./dist/index.cjs",
       "default": "./dist/index.js"
     },
     "./types": {
+      "solid": "./src/lib/types.ts",
       "types": "./dist/types.d.ts",
       "import": "./dist/types.js",
       "require": "./dist/types.cjs",
       "default": "./dist/types.js"
     },
     "./view-transitions": {
+      "solid": "./src/lib/view-transitions.ts",
       "types": "./dist/view-transitions.d.ts",
       "import": "./dist/view-transitions.js",
       "require": "./dist/view-transitions.cjs",
@@ -33,7 +39,7 @@
     }
   },
   "dependencies": {
-    "@ssgoi/core": "^6.4.0"
+    "@ssgoi/core": "^6.6.4"
   },
   "devDependencies": {
     "@eslint/js": "^9.30.1",

package/src/lib/context.tsx

@@ -0,0 +1,14 @@
+import { createContext, useContext } from "solid-js";
+import type { SsgoiContext } from "./types";
+
+const SsgoiContextInstance = createContext<SsgoiContext | null>(null);
+
+export const SsgoiProvider = SsgoiContextInstance.Provider;
+
+export const useSsgoi = () => {
+  const context = useContext(SsgoiContextInstance);
+  if (!context) {
+    throw new Error("useSsgoi must be used within SsgoiProvider");
+  }
+  return context;
+};

package/src/lib/index.ts

@@ -0,0 +1,5 @@
+export * from "./types";
+export { Ssgoi } from "./ssgoi";
+/** @deprecated Set `data-ssgoi-transition` directly on an element inside `<Ssgoi>` instead. */
+export { SsgoiTransition } from "./ssgoi-transition";
+export * from "@ssgoi/core";

package/src/lib/ssgoi-transition.tsx

@@ -0,0 +1,34 @@
+import { splitProps, type JSX, type ValidComponent } from "solid-js";
+import { Dynamic } from "solid-js/web";
+import { useSsgoi } from "./context";
+
+type SsgoiTransitionProps<T extends ValidComponent = "div"> = {
+  children: JSX.Element;
+  id: string;
+  as?: T;
+  class?: string;
+};
+
+/**
+ * @deprecated Set `data-ssgoi-transition` directly on the page boundary
+ * element inside `<Ssgoi>` instead.
+ */
+export const SsgoiTransition = <T extends ValidComponent = "div">(
+  props: SsgoiTransitionProps<T>,
+) => {
+  const [local, rest] = splitProps(props, ["children", "id", "as", "class"]);
+  const ssgoi = useSsgoi();
+  const component = (local.as || "div") as ValidComponent;
+
+  return (
+    <Dynamic
+      component={component}
+      ref={ssgoi.refFor(local.id)}
+      data-ssgoi-transition={local.id}
+      class={local.class}
+      {...(rest as object)}
+    >
+      {local.children}
+    </Dynamic>
+  );
+};

package/src/lib/ssgoi.tsx

@@ -0,0 +1,35 @@
+import { createEffect, createMemo, onCleanup, type JSX } from "solid-js";
+import type { SsgoiConfig, SsgoiContext } from "./types";
+import { SsgoiProvider } from "./context";
+import {
+  createSggoiTransitionContext,
+  observeSsgoiTransitions,
+} from "@ssgoi/core/internal";
+import type { HostAnimation } from "@ssgoi/core/internal";
+
+interface SsgoiProps {
+  config: SsgoiConfig;
+  host?: HostAnimation;
+  children: JSX.Element;
+}
+
+export const Ssgoi = (props: SsgoiProps) => {
+  let root!: HTMLDivElement;
+  const contextValue = createMemo<SsgoiContext>(() =>
+    createSggoiTransitionContext(props.config, { host: props.host }),
+  );
+
+  createEffect(() => {
+    if (!root) return;
+    const cleanup = observeSsgoiTransitions(root, contextValue());
+    onCleanup(cleanup);
+  });
+
+  return (
+    <SsgoiProvider value={contextValue()}>
+      <div ref={root} data-ssgoi-root="" style={{ display: "contents" }}>
+        {props.children}
+      </div>
+    </SsgoiProvider>
+  );
+};

package/src/lib/types.ts

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

package/src/lib/view-transitions.ts

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