@capgo/capacitor-transitions 8.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Capgo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,583 @@
+# @capgo/capacitor-transitions
+
+Framework-agnostic page transitions for Capacitor apps. iOS-style navigation without opinions.
+
+## Features
+
+- **Framework Agnostic** - Works with React, Vue, Angular, Svelte, Solid, and any other framework
+- **iOS & Android Animations** - Platform-appropriate transitions out of the box
+- **Web Animations API** - Smooth, GPU-accelerated animations
+- **View Transitions API** - Optional progressive enhancement for supporting browsers
+- **No Design Opinions** - Just transition logic, you bring your own styles
+- **Coordinated Transitions** - Header, content, and footer animate together
+- **Page Caching** - Keep pages in DOM for instant back navigation
+- **Ionic-style iOS Swipe Back** - Optional edge gesture with Capacitor native iOS auto-enable
+- **Lifecycle Hooks** - willEnter, didEnter, willLeave, didLeave events
+
+## Compatibility
+
+| Plugin version | Capacitor compatibility | Maintained |
+| -------------- | ----------------------- | ---------- |
+| v8.\*.\*       | v8.\*.\*                | ✅         |
+| v7.\*.\*       | v7.\*.\*                | On demand  |
+| v6.\*.\*       | v6.\*.\*                | ❌         |
+| v5.\*.\*       | v5.\*.\*                | ❌         |
+
+> **Note:** The major version of this plugin follows the major version of Capacitor. Use the version that matches your Capacitor installation (e.g., plugin v8 for Capacitor 8). Only the latest major version is actively maintained.
+
+## Installation
+
+```bash
+npm install @capgo/capacitor-transitions
+```
+
+## Quick Start
+
+### Vanilla JavaScript / Web Components
+
+```html
+<cap-router-outlet platform="auto">
+  <cap-page>
+    <cap-header slot="header">
+      <h1>My Page</h1>
+    </cap-header>
+    <cap-content slot="content">
+      <p>Page content here</p>
+    </cap-content>
+    <cap-footer slot="footer">
+      <nav>Tab bar</nav>
+    </cap-footer>
+  </cap-page>
+</cap-router-outlet>
+```
+
+```javascript
+import '@capgo/capacitor-transitions';
+
+// Navigate programmatically
+const outlet = document.querySelector('cap-router-outlet');
+outlet.push(newPageElement);
+outlet.pop();
+outlet.setRoot(newRootElement);
+```
+
+### React
+
+```tsx
+import { useRef, useEffect } from 'react';
+import { useNavigate } from 'react-router-dom';
+import { initTransitions, setDirection, setupPage, setupRouterOutlet } from '@capgo/capacitor-transitions/react';
+import '@capgo/capacitor-transitions';
+
+// Initialize once at app startup
+initTransitions({ platform: 'auto' });
+
+function App() {
+  const outletRef = useRef<HTMLElement>(null);
+
+  useEffect(() => {
+    if (outletRef.current) {
+      setupRouterOutlet(outletRef.current, { platform: 'auto', swipeGesture: 'auto' });
+    }
+  }, []);
+
+  return (
+    <cap-router-outlet ref={outletRef}>
+      <Routes>
+        <Route path="/" element={<HomePage />} />
+        <Route path="/details/:id" element={<DetailsPage />} />
+      </Routes>
+    </cap-router-outlet>
+  );
+}
+
+function HomePage() {
+  const navigate = useNavigate();
+  const pageRef = useRef<HTMLElement>(null);
+
+  useEffect(() => {
+    if (pageRef.current) {
+      return setupPage(pageRef.current, {
+        onDidEnter: () => console.log('entered'),
+      });
+    }
+  }, []);
+
+  const goToDetails = (id: number) => {
+    setDirection('forward');
+    navigate(`/details/${id}`);
+  };
+
+  return (
+    <cap-page ref={pageRef}>
+      <cap-header slot="header">
+        <h1>Home</h1>
+      </cap-header>
+      <cap-content slot="content">
+        <button onClick={() => goToDetails(1)}>Go to Details</button>
+      </cap-content>
+      <cap-footer slot="footer">
+        <nav>Tab bar</nav>
+      </cap-footer>
+    </cap-page>
+  );
+}
+```
+
+#### React JSX TypeScript setup
+
+Importing from `@capgo/capacitor-transitions/react` registers the web components and includes React JSX typings for `cap-router-outlet`, `cap-page`, `cap-header`, `cap-content`, and `cap-footer`. In most React projects, the import in the example above is enough.
+
+If TypeScript still shows `Property 'cap-router-outlet' does not exist on type 'JSX.IntrinsicElements'`, add a project declaration file:
+
+```ts
+// src/capgo-transitions.d.ts
+import '@capgo/capacitor-transitions/react';
+```
+
+Then make sure TypeScript includes it:
+
+```json
+{
+  "include": ["src", "src/capgo-transitions.d.ts"]
+}
+```
+
+For Vite, Create React App, and most webpack React apps, putting `capgo-transitions.d.ts` inside `src/` is enough. For Next.js, put it in `src/` or the project root and keep it included in `tsconfig.json`. For custom TypeScript or webpack setups with a separate `types/` folder, add that folder to `tsconfig.json`:
+
+```json
+{
+  "include": ["src", "types"]
+}
+```
+
+### Vue
+
+```vue
+<script setup>
+import { ref, onMounted, onUnmounted } from 'vue';
+import { useRouter } from 'vue-router';
+import { initTransitions, setDirection, setupPage, setupRouterOutlet } from '@capgo/capacitor-transitions/vue';
+import '@capgo/capacitor-transitions';
+
+// Initialize once
+initTransitions({ platform: 'auto' });
+
+const router = useRouter();
+const outletRef = ref(null);
+const pageRef = ref(null);
+let cleanup;
+
+onMounted(() => {
+  if (outletRef.value) {
+    setupRouterOutlet(outletRef.value, { platform: 'auto' });
+  }
+  if (pageRef.value) {
+    cleanup = setupPage(pageRef.value, {
+      onDidEnter: () => console.log('entered'),
+    });
+  }
+});
+
+onUnmounted(() => cleanup?.());
+
+const goToDetails = (id) => {
+  setDirection('forward');
+  router.push(`/details/${id}`);
+};
+</script>
+
+<template>
+  <cap-router-outlet ref="outletRef">
+    <cap-page ref="pageRef">
+      <cap-header slot="header">
+        <h1>Home</h1>
+      </cap-header>
+      <cap-content slot="content">
+        <button @click="goToDetails(1)">Go to Details</button>
+      </cap-content>
+    </cap-page>
+  </cap-router-outlet>
+</template>
+```
+
+### Svelte
+
+```svelte
+<script>
+  import { routerOutlet, page, setDirection } from '@capgo/capacitor-transitions/svelte'
+  import '@capgo/capacitor-transitions'
+
+  function navigate(to, direction = 'forward') {
+    setDirection(direction)
+    // Use your router's navigate function
+  }
+</script>
+
+<cap-router-outlet use:routerOutlet>
+  <cap-page use:page={{ onDidEnter: () => console.log('entered') }}>
+    <cap-header slot="header">
+      <h1>Home</h1>
+    </cap-header>
+    <cap-content slot="content">
+      <button on:click={() => navigate('/details/1')}>Go to Details</button>
+    </cap-content>
+  </cap-page>
+</cap-router-outlet>
+```
+
+### Solid
+
+```tsx
+import { onMount, onCleanup } from 'solid-js';
+import { useNavigate } from '@solidjs/router';
+import { initTransitions, setDirection, setupPage, setupRouterOutlet } from '@capgo/capacitor-transitions/solid';
+import '@capgo/capacitor-transitions';
+
+// Initialize once
+initTransitions({ platform: 'auto' });
+
+function HomePage() {
+  const navigate = useNavigate();
+  let pageRef;
+
+  onMount(() => {
+    if (pageRef) {
+      const cleanup = setupPage(pageRef, {
+        onDidEnter: () => console.log('entered'),
+      });
+      onCleanup(cleanup);
+    }
+  });
+
+  const goToDetails = (id) => {
+    setDirection('forward');
+    navigate(`/details/${id}`);
+  };
+
+  return (
+    <cap-page ref={pageRef}>
+      <cap-header slot="header">
+        <h1>Home</h1>
+      </cap-header>
+      <cap-content slot="content">
+        <button onClick={() => goToDetails(1)}>Go to Details</button>
+      </cap-content>
+    </cap-page>
+  );
+}
+```
+
+### Angular
+
+```typescript
+// app.component.ts
+import { Component, CUSTOM_ELEMENTS_SCHEMA, ElementRef, ViewChild, AfterViewInit } from '@angular/core';
+import '@capgo/capacitor-transitions';
+
+@Component({
+  selector: 'app-root',
+  schemas: [CUSTOM_ELEMENTS_SCHEMA],
+  template: `
+    <cap-router-outlet #outlet platform="auto">
+      <router-outlet></router-outlet>
+    </cap-router-outlet>
+  `,
+})
+export class AppComponent {}
+
+// home.component.ts
+@Component({
+  selector: 'app-home',
+  schemas: [CUSTOM_ELEMENTS_SCHEMA],
+  template: `
+    <cap-page>
+      <cap-header slot="header">
+        <h1>Home</h1>
+      </cap-header>
+      <cap-content slot="content">
+        <button (click)="goToDetails(1)">Go to Details</button>
+      </cap-content>
+    </cap-page>
+  `,
+})
+export class HomeComponent {
+  constructor(private router: Router) {}
+
+  goToDetails(id: number) {
+    this.router.navigate(['/details', id]);
+  }
+}
+```
+
+## Use With @capgo/native-navigation
+
+Use `@capgo/native-navigation` when the native layer should own the navbar or tabbar, and use `@capgo/capacitor-transitions` for the WebView page content underneath that native chrome.
+
+```bash
+npm install @capgo/capacitor-transitions @capgo/native-navigation
+npx cap sync
+```
+
+Configure native chrome first:
+
+```typescript
+import { NativeNavigation } from '@capgo/native-navigation';
+
+await NativeNavigation.configure({
+  contentInsetMode: 'css',
+});
+
+await NativeNavigation.setNavbar({
+  title: 'Inbox',
+  backButton: { visible: false },
+});
+```
+
+Keep the transition outlet focused on pages, not native bars:
+
+```html
+<cap-router-outlet platform="auto" swipe-gesture="auto">
+  <cap-page>
+    <cap-content slot="content" fullscreen>
+      <main class="native-page">Inbox content</main>
+    </cap-content>
+  </cap-page>
+</cap-router-outlet>
+```
+
+```css
+.native-page {
+  padding-top: var(--cap-native-navigation-top);
+  padding-bottom: var(--cap-native-navigation-bottom);
+}
+```
+
+Drive both packages from the same router actions:
+
+```typescript
+import { NativeNavigation } from '@capgo/native-navigation';
+import { setDirection } from '@capgo/capacitor-transitions/react';
+import { router } from './router';
+
+await NativeNavigation.addListener('navbarBack', () => {
+  setDirection('back');
+  router.back();
+});
+
+async function openMessage(id: string) {
+  setDirection('forward');
+  router.push(`/message/${id}`);
+
+  await NativeNavigation.setNavbar({
+    title: 'Message',
+    backButton: { visible: true, title: 'Inbox' },
+  });
+}
+```
+
+Do not render the native top bar again as a moving `<cap-header>`. Native Navigation keeps the bar native; this package animates the web page body.
+
+## API Reference
+
+### Components
+
+#### `<cap-router-outlet>`
+
+Container for page transitions.
+
+| Attribute       | Type                           | Default          | Description                                                                        |
+| --------------- | ------------------------------ | ---------------- | ---------------------------------------------------------------------------------- |
+| `platform`      | `'ios' \| 'android' \| 'auto'` | `'auto'`         | Animation style                                                                    |
+| `duration`      | `number`                       | Platform default | Animation duration in ms                                                           |
+| `keep-in-dom`   | `boolean`                      | `true`           | Keep pages in DOM after navigating away                                            |
+| `max-cached`    | `number`                       | `10`             | Maximum pages to keep cached                                                       |
+| `swipe-gesture` | `boolean \| 'auto'`            | `'auto'`         | Enable edge swipe-back gesture. `'auto'` enables only in native iOS Capacitor apps |
+
+Methods:
+
+- `push(element, config?)` - Navigate forward to new page
+- `pop(config?)` - Navigate back
+- `setRoot(element, config?)` - Replace navigation stack
+- `setSwipeGesture(true | false | 'auto')` - Enable, disable, or auto-detect edge swipe-back gesture
+
+`swipe-gesture="auto"` uses Capacitor's runtime helpers (`Capacitor.isNativePlatform()` and `Capacitor.getPlatform()`) and enables the gesture only for native iOS apps. Use `swipe-gesture="true"` to force it on any platform or `swipe-gesture="false"` to disable it.
+
+#### `<cap-page>`
+
+Page container with header/content/footer slots.
+
+Events:
+
+- `cap-will-enter` - Before page becomes visible
+- `cap-did-enter` - After page becomes visible
+- `cap-will-leave` - Before page leaves
+- `cap-did-leave` - After page leaves
+
+#### `<cap-header>`
+
+Header container. Use with `slot="header"` inside `<cap-page>`.
+
+#### `<cap-content>`
+
+Main scrollable content area. Use with `slot="content"`.
+
+| Attribute    | Type      | Default | Description                   |
+| ------------ | --------- | ------- | ----------------------------- |
+| `fullscreen` | `boolean` | `false` | Content scrolls behind header |
+| `scroll-x`   | `boolean` | `true`  | Enable horizontal scroll      |
+| `scroll-y`   | `boolean` | `true`  | Enable vertical scroll        |
+
+#### `<cap-footer>`
+
+Footer container. Use with `slot="footer"`.
+
+### Transition Directions
+
+| Direction   | Description                            |
+| ----------- | -------------------------------------- |
+| `'forward'` | Push animation (iOS: slide from right) |
+| `'back'`    | Pop animation (iOS: slide to right)    |
+| `'root'`    | Replace animation (fade)               |
+| `'none'`    | No animation                           |
+
+### Helper Functions
+
+All framework bindings export these helper functions:
+
+```typescript
+// Initialize the transition system
+initTransitions({ platform: 'auto' });
+
+// Set the direction for the next navigation
+setDirection('forward' | 'back' | 'root' | 'none');
+
+// Set up a router outlet element
+setupRouterOutlet(element, options);
+
+// Auto-enable the iOS edge swipe-back gesture in native Capacitor iOS apps
+setupRouterOutlet(element, { swipeGesture: 'auto' });
+
+// Force enable or disable from JavaScript
+setupRouterOutlet(element, { swipeGesture: true });
+setupRouterOutlet(element, { swipeGesture: false });
+
+// Set up a page element with lifecycle callbacks (returns cleanup function)
+setupPage(element, { onWillEnter, onDidEnter, onWillLeave, onDidLeave });
+
+// Create a transition-aware navigate function
+const transitionNavigate = createTransitionNavigate(navigate);
+transitionNavigate('/path', 'forward');
+```
+
+### TransitionController
+
+For advanced programmatic control:
+
+```typescript
+import { createTransitionController } from '@capgo/capacitor-transitions';
+
+const controller = createTransitionController({
+  platform: 'auto',
+  duration: 400,
+  useViewTransitions: true,
+});
+
+// Navigate
+await controller.push(element, { direction: 'forward' });
+await controller.pop({ direction: 'back' });
+await controller.setRoot(element, { direction: 'root' });
+
+// Lifecycle hooks
+controller.registerLifecycle('page-id', {
+  onWillEnter: (event) => console.log('Will enter', event),
+  onDidEnter: (event) => console.log('Did enter', event),
+  onWillLeave: (event) => console.log('Will leave', event),
+  onDidLeave: (event) => console.log('Did leave', event),
+});
+```
+
+## Browser Support
+
+- Modern browsers with Web Animations API support
+- Optional View Transitions API (Chrome 111+, Edge 111+, Safari 18+) support
+- Graceful fallback for older browsers
+
+## Design Philosophy
+
+This library is intentionally unopinionated about styling:
+
+1. **Minimal structural CSS** - You bring your own visual system
+2. **No design system** - Works with any UI library or custom styles
+3. **Just transitions** - Focus on smooth page navigation
+4. **Framework agnostic** - Use with React, Vue, Angular, Svelte, Solid, or vanilla JS
+
+The goal is to provide Ionic-quality page transitions without Ionic's design system or framework lock-in.
+
+## Examples
+
+See the `/examples` directory for complete examples:
+
+- `react-app` - React with React Router
+- `vue-app` - Vue 3 with Vue Router
+- `angular-app` - Angular with Angular Router
+- `svelte-app` - Svelte 5
+- `solid-app` - Solid with Solid Router
+- `tanstack-app` - React with TanStack Router
+
+### React Example
+
+The React example demonstrates iOS-style page transitions with smooth animations:
+
+<img src="./docs/react-transition-demo.webp" width="300" alt="React transition demo" />
+
+<table>
+  <tr>
+    <td align="center">
+      <img
+        src="https://github.com/user-attachments/assets/c06a6c5a-c318-44ab-a57c-992ba9cfacd4"
+        width="300"
+        alt="React Home Page"
+      />
+      <br />
+      <strong>Home Page</strong>
+    </td>
+    <td align="center">
+      <img
+        src="https://github.com/user-attachments/assets/6fd808da-6352-4660-8c79-e32184332df8"
+        width="300"
+        alt="React Details Page"
+      />
+      <br />
+      <strong>Details Page</strong>
+    </td>
+    <td align="center">
+      <img
+        src="https://github.com/user-attachments/assets/8516dcf0-4189-40d9-a400-154b73c0135e"
+        width="300"
+        alt="React Nested Page"
+      />
+      <br />
+      <strong>Nested Page</strong>
+    </td>
+  </tr>
+</table>
+
+Features demonstrated:
+
+- Forward navigation with slide-in animation
+- Back navigation with slide-out animation
+- Multi-level page stack
+- Coordinated header/content/footer transitions
+
+To run the React example:
+
+```bash
+cd examples/react-app
+npm install
+npm run dev
+```
+
+## License
+
+MIT