@flight-framework/transitions 0.1.0

package/README.md

@@ -0,0 +1,232 @@
+# @flight-framework/transitions
+
+Smooth page, layout, and component transitions for Flight Framework.
+
+## Features
+
+- 🚀 **Native View Transitions API** - Uses browser-native API when available
+- 🎨 **20+ Built-in Presets** - Fade, slide, scale, flip, morph, and more
+- ⚡ **Zero Dependencies** - Core bundle ~3kb gzipped
+- 🎯 **Framework Agnostic** - Works with React, Vue, Svelte, Solid, and more
+- ♿ **Accessible** - Respects `prefers-reduced-motion` by default
+- 📱 **SSR Safe** - Works with server-side rendering
+- 🔧 **Highly Configurable** - Global config or per-page overrides
+
+## Installation
+
+```bash
+npm install @flight-framework/transitions
+```
+
+## Quick Start
+
+### Global Configuration
+
+```typescript
+// flight.config.ts
+import { defineConfig } from '@flight-framework/core';
+
+export default defineConfig({
+  transitions: {
+    enabled: true,
+    pageTransition: 'fade',
+    duration: 200,
+  },
+});
+```
+
+### React Usage
+
+```tsx
+// RootLayout.tsx
+import { TransitionProvider, PageTransition } from '@flight-framework/transitions/react';
+
+export default function RootLayout({ children }) {
+  return (
+    <TransitionProvider config={{ pageTransition: 'fade' }}>
+      <Header />
+      <PageTransition>
+        {children}
+      </PageTransition>
+      <Footer />
+    </TransitionProvider>
+  );
+}
+```
+
+### Page-Specific Transitions
+
+```tsx
+// routes/dashboard.page.tsx
+import { definePageTransition } from '@flight-framework/transitions';
+
+definePageTransition({
+  default: 'slide-left',
+  backTransition: 'slide-right',
+  duration: 250,
+});
+
+export default function DashboardPage() {
+  return <div>Dashboard</div>;
+}
+```
+
+## Presets
+
+### Fade
+- `fade` - Simple opacity fade
+- `fade-scale` - Fade with subtle scale
+- `fade-blur` - Fade with blur effect
+- `fade-slow` - Slow fade for emphasis
+- `fade-fast` - Quick fade for snappy UI
+
+### Slide
+- `slide-left` - Slide in from left
+- `slide-right` - Slide in from right
+- `slide-up` - Slide in from top
+- `slide-down` - Slide in from bottom
+- `slide-fade` - Subtle offset slide
+- `slide-scale` - iOS-like slide with scale
+
+### Scale
+- `scale` - Scale in/out
+- `scale-up` - Zoom in effect
+- `scale-down` - Zoom out effect
+- `scale-fade` - Subtle scale with fade
+- `pop` - Bouncy scale animation
+- `expand` - Expand from center
+
+### Special
+- `flip-x` - 3D horizontal flip
+- `flip-y` - 3D vertical flip
+- `rotate` - Rotation with fade
+- `morph` - Shared element morphing
+- `wipe-left` - Reveal wipe effect
+- `circle-reveal` - Circular reveal from center
+- `none` - Disable transitions
+
+## Custom Transitions
+
+```typescript
+import { definePageTransition } from '@flight-framework/transitions';
+
+definePageTransition({
+  default: {
+    name: 'my-custom',
+    leave: {
+      from: { opacity: '1', transform: 'scale(1)' },
+      to: { opacity: '0', transform: 'scale(0.9) rotate(5deg)' },
+    },
+    enter: {
+      from: { opacity: '0', transform: 'translateY(20px)' },
+      to: { opacity: '1', transform: 'translateY(0)' },
+    },
+    duration: { leave: 150, enter: 200 },
+    easing: 'cubic-bezier(0.4, 0, 0.2, 1)',
+  },
+});
+```
+
+## Shared Element Transitions
+
+```tsx
+// ProductList.tsx
+<Link href={`/product/${id}`}>
+  <SharedElement name={`product-${id}`}>
+    <img src={product.image} alt={product.name} />
+  </SharedElement>
+</Link>
+
+// ProductDetail.tsx
+<SharedElement name={`product-${id}`}>
+  <img src={product.image} alt={product.name} className="large" />
+</SharedElement>
+```
+
+## Programmatic Navigation
+
+```typescript
+import { navigateWithTransition } from '@flight-framework/transitions/router';
+
+// With default transition
+await navigateWithTransition('/dashboard');
+
+// With custom transition
+await navigateWithTransition('/settings', {
+  transition: 'slide-left',
+  replace: false,
+});
+
+// Disable transition
+await navigateWithTransition('/login', {
+  transition: false,
+});
+```
+
+## React Hooks
+
+```tsx
+import { 
+  useTransition,
+  useIsTransitioning,
+  useTransitionDirection,
+  useReducedMotion,
+} from '@flight-framework/transitions/react';
+
+function MyComponent() {
+  const { state, startTransition } = useTransition();
+  const isTransitioning = useIsTransitioning();
+  const direction = useTransitionDirection();
+  const prefersReduced = useReducedMotion();
+  
+  return (
+    <div>
+      {isTransitioning && <LoadingIndicator />}
+      <p>Direction: {direction}</p>
+    </div>
+  );
+}
+```
+
+## CSS-Only Usage
+
+For CSS-only transitions without JavaScript:
+
+```css
+/* Import base transitions */
+@import '@flight-framework/transitions/css';
+
+/* Import View Transitions API styles */
+@import '@flight-framework/transitions/css/view-transitions';
+```
+
+```html
+<div class="flight-transition flight-transition-fade">
+  Content with transition
+</div>
+```
+
+## Configuration Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `enabled` | `boolean` | `true` | Enable/disable transitions globally |
+| `viewTransitions` | `boolean` | `true` | Use native View Transitions API |
+| `pageTransition` | `string \| object` | `'fade'` | Default page transition |
+| `layoutTransition` | `string \| object` | `false` | Default layout transition |
+| `duration` | `number` | `200` | Animation duration in ms |
+| `easing` | `string` | `cubic-bezier(0.4, 0, 0.2, 1)` | Easing function |
+| `reduceMotion` | `'respect-system' \| 'always-reduce' \| 'ignore'` | `'respect-system'` | Reduced motion handling |
+| `crossDocument` | `boolean` | `false` | Enable MPA transitions |
+
+## Browser Support
+
+| Feature | Chrome | Firefox | Safari | Edge |
+|---------|--------|---------|--------|------|
+| View Transitions API | 111+ | ❌ (fallback) | 18.4+ | 111+ |
+| CSS Fallback | ✅ | ✅ | ✅ | ✅ |
+| Web Animations API | ✅ | ✅ | ✅ | ✅ |
+
+## License
+
+MIT © Flight Contributors

package/dist/adapters/react/index.d.ts

@@ -0,0 +1,210 @@
+import React, { FC, ReactNode, CSSProperties } from 'react';
+import { i as TransitionsConfig, j as TransitionState, P as PageTransitionConfig, T as TransitionPreset, C as CustomTransition } from '../../types-BT3SCjiY.js';
+import { T as TransitionManager } from '../../transition-manager-CuO0S_Yn.js';
+
+/**
+ * @flight-framework/transitions - React Adapter
+ *
+ * React components and hooks for Flight Transitions.
+ */
+
+interface TransitionContextValue {
+    /** Current transition state */
+    state: TransitionState;
+    /** Transition manager instance */
+    manager: TransitionManager;
+    /** Whether transitions are enabled */
+    isEnabled: boolean;
+    /** Whether View Transitions API is supported */
+    isViewTransitionSupported: boolean;
+    /** Start a page transition programmatically */
+    startTransition: (to: string, config?: PageTransitionConfig) => Promise<void>;
+    /** Skip the current transition */
+    skipTransition: () => void;
+}
+interface TransitionProviderProps {
+    children: ReactNode;
+    /** Initial transition configuration */
+    config?: TransitionsConfig;
+    /** Use a custom transition manager */
+    manager?: TransitionManager;
+}
+/**
+ * TransitionProvider - Provides transition context to the app
+ *
+ * @example
+ * ```tsx
+ * // In your root layout
+ * import { TransitionProvider } from '@flight-framework/transitions/react';
+ *
+ * export default function RootLayout({ children }) {
+ *   return (
+ *     <TransitionProvider config={{ pageTransition: 'fade' }}>
+ *       {children}
+ *     </TransitionProvider>
+ *   );
+ * }
+ * ```
+ */
+declare const TransitionProvider: FC<TransitionProviderProps>;
+/**
+ * useTransition - Access the transition context
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { state, startTransition } = useTransition();
+ *
+ *   return (
+ *     <div>
+ *       {state.isTransitioning && <LoadingSpinner />}
+ *       <button onClick={() => startTransition('/about')}>
+ *         Go to About
+ *       </button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useTransition(): TransitionContextValue;
+/**
+ * useTransitionState - Get just the transition state
+ */
+declare function useTransitionState(): TransitionState;
+/**
+ * useIsTransitioning - Check if a transition is in progress
+ */
+declare function useIsTransitioning(): boolean;
+/**
+ * useTransitionDirection - Get the current transition direction
+ */
+declare function useTransitionDirection(): 'forward' | 'back' | 'auto';
+/**
+ * useReducedMotion - Check if user prefers reduced motion
+ */
+declare function useReducedMotion(): boolean;
+interface PageTransitionProps {
+    children: ReactNode;
+    /** Transition type (overrides context config) */
+    type?: TransitionPreset | CustomTransition;
+    /** Duration override */
+    duration?: number;
+    /** Mode for sequencing enter/leave */
+    mode?: 'in-out' | 'out-in' | 'simultaneous';
+    /** Callback when transition starts */
+    onStart?: () => void;
+    /** Callback when transition ends */
+    onEnd?: () => void;
+    /** CSS class for the wrapper */
+    className?: string;
+    /** Inline styles for the wrapper */
+    style?: CSSProperties;
+}
+/**
+ * PageTransition - Wraps page content with transition animations
+ *
+ * @example
+ * ```tsx
+ * // In a layout
+ * export default function Layout({ children }) {
+ *   return (
+ *     <PageTransition type="slide-left">
+ *       {children}
+ *     </PageTransition>
+ *   );
+ * }
+ * ```
+ */
+declare const PageTransition: FC<PageTransitionProps>;
+interface TransitionElementProps {
+    children: ReactNode;
+    /** Show or hide the element */
+    show: boolean;
+    /** Transition type */
+    type?: TransitionPreset | CustomTransition;
+    /** Duration override */
+    duration?: number;
+    /** Animate on initial mount */
+    appear?: boolean;
+    /** Unmount when hidden */
+    unmountOnHide?: boolean;
+    /** Callbacks */
+    onEnter?: () => void;
+    onEnterComplete?: () => void;
+    onLeave?: () => void;
+    onLeaveComplete?: () => void;
+    /** Wrapper element tag name */
+    as?: 'div' | 'span' | 'section' | 'article' | 'main' | 'aside' | 'header' | 'footer' | 'nav';
+    /** CSS class */
+    className?: string;
+    /** Inline styles */
+    style?: CSSProperties;
+}
+/**
+ * Transition - Animate element enter/leave
+ *
+ * @example
+ * ```tsx
+ * function Modal({ isOpen, onClose, children }) {
+ *   return (
+ *     <Transition show={isOpen} type="fade-scale">
+ *       <div className="modal">
+ *         {children}
+ *       </div>
+ *     </Transition>
+ *   );
+ * }
+ * ```
+ */
+declare const Transition: FC<TransitionElementProps>;
+interface SharedElementProps {
+    children: ReactNode;
+    /** Unique name for matching across pages */
+    name: string;
+    /** Wrapper element tag name */
+    as?: 'div' | 'span' | 'section' | 'article' | 'main' | 'aside' | 'header' | 'footer' | 'img';
+    /** CSS class */
+    className?: string;
+    /** Inline styles */
+    style?: CSSProperties;
+}
+/**
+ * SharedElement - Mark an element for shared element transitions
+ *
+ * @example
+ * ```tsx
+ * // On list page
+ * <SharedElement name={`product-${product.id}`}>
+ *   <img src={product.image} />
+ * </SharedElement>
+ *
+ * // On detail page
+ * <SharedElement name={`product-${product.id}`}>
+ *   <img src={product.image} />
+ * </SharedElement>
+ * ```
+ */
+declare const SharedElement: FC<SharedElementProps>;
+interface TransitionLinkProps extends React.AnchorHTMLAttributes<HTMLAnchorElement> {
+    /** Transition type for this navigation */
+    transition?: TransitionPreset | CustomTransition | false;
+    /** Replace instead of push */
+    replace?: boolean;
+    /** Prefetch on hover */
+    prefetch?: boolean;
+}
+/**
+ * TransitionLink - Link component with transition support
+ *
+ * Use with @flight-framework/router or wrap your router's Link component.
+ *
+ * @example
+ * ```tsx
+ * <TransitionLink href="/about" transition="slide-left">
+ *   About Us
+ * </TransitionLink>
+ * ```
+ */
+declare const TransitionLink: FC<TransitionLinkProps>;
+
+export { PageTransition, type PageTransitionProps, SharedElement, type SharedElementProps, Transition, type TransitionElementProps, TransitionLink, type TransitionLinkProps, TransitionProvider, type TransitionProviderProps, useIsTransitioning, useReducedMotion, useTransition, useTransitionDirection, useTransitionState };

package/dist/adapters/react/index.js

@@ -0,0 +1,261 @@
+import { createTransitionManager, getTransitionManager } from '../../chunk-7R3FXL3A.js';
+import { prefersReducedMotion } from '../../chunk-4SF4GHDQ.js';
+import { createContext, useRef, useState, useEffect, useMemo, useContext, createElement, useCallback } from 'react';
+import { jsx } from 'react/jsx-runtime';
+
+var TransitionContext = createContext(null);
+var TransitionProvider = ({
+  children,
+  config,
+  manager: customManager
+}) => {
+  const managerRef = useRef(null);
+  if (!managerRef.current) {
+    managerRef.current = customManager ?? createTransitionManager(config);
+  }
+  const manager = managerRef.current;
+  const [state, setState] = useState(manager.getState());
+  useEffect(() => {
+    const unsubscribe = manager.subscribe((newState) => {
+      setState(newState);
+    });
+    return unsubscribe;
+  }, [manager]);
+  useEffect(() => {
+    if (config) {
+      manager.configure(config);
+    }
+  }, [config, manager]);
+  useEffect(() => {
+    return () => {
+      if (!customManager) {
+        manager.destroy();
+      }
+    };
+  }, [manager, customManager]);
+  const value = useMemo(() => ({
+    state,
+    manager,
+    isEnabled: manager.isEnabled(),
+    isViewTransitionSupported: manager.isViewTransitionSupported(),
+    startTransition: (to, pageConfig) => manager.startPageTransition(to, pageConfig),
+    skipTransition: () => manager.skipTransition()
+  }), [state, manager]);
+  return /* @__PURE__ */ jsx(TransitionContext.Provider, { value, children });
+};
+function useTransition() {
+  const context = useContext(TransitionContext);
+  if (!context) {
+    const manager = getTransitionManager();
+    return {
+      state: manager.getState(),
+      manager,
+      isEnabled: manager.isEnabled(),
+      isViewTransitionSupported: manager.isViewTransitionSupported(),
+      startTransition: (to, config) => manager.startPageTransition(to, config),
+      skipTransition: () => manager.skipTransition()
+    };
+  }
+  return context;
+}
+function useTransitionState() {
+  const { state } = useTransition();
+  return state;
+}
+function useIsTransitioning() {
+  const { state } = useTransition();
+  return state.isTransitioning;
+}
+function useTransitionDirection() {
+  const { state } = useTransition();
+  return state.direction;
+}
+function useReducedMotion() {
+  const [reduced, setReduced] = useState(() => prefersReducedMotion());
+  useEffect(() => {
+    const mediaQuery = window.matchMedia("(prefers-reduced-motion: reduce)");
+    const handler = (event) => {
+      setReduced(event.matches);
+    };
+    mediaQuery.addEventListener("change", handler);
+    return () => mediaQuery.removeEventListener("change", handler);
+  }, []);
+  return reduced;
+}
+var PageTransition = ({
+  children,
+  type,
+  duration,
+  mode = "out-in",
+  onStart,
+  onEnd,
+  className,
+  style
+}) => {
+  const { state } = useTransition();
+  const containerRef = useRef(null);
+  useEffect(() => {
+    if (state.isTransitioning && state.phase === "leaving") {
+      onStart?.();
+    }
+    if (!state.isTransitioning && state.phase === "idle") {
+      onEnd?.();
+    }
+  }, [state.isTransitioning, state.phase, onStart, onEnd]);
+  const transitionClass = useMemo(() => {
+    const classes = ["flight-page-transition"];
+    if (className) {
+      classes.push(className);
+    }
+    if (state.isTransitioning) {
+      classes.push("flight-transitioning");
+      classes.push(`flight-transition-${state.phase}`);
+      classes.push(`flight-direction-${state.direction}`);
+    }
+    return classes.join(" ");
+  }, [className, state.isTransitioning, state.phase, state.direction]);
+  const inlineStyle = useMemo(() => {
+    const styles = { ...style };
+    if (duration !== void 0) {
+      styles["--flight-transition-duration"] = `${duration}ms`;
+    }
+    if (type && typeof type === "string") {
+      styles["--flight-transition-type"] = type;
+    }
+    return styles;
+  }, [style, duration, type]);
+  return /* @__PURE__ */ jsx("div", { ref: containerRef, className: transitionClass, style: inlineStyle, children });
+};
+var Transition = ({
+  children,
+  show,
+  type = "fade",
+  duration,
+  appear = false,
+  unmountOnHide = true,
+  onEnter,
+  onEnterComplete,
+  onLeave,
+  onLeaveComplete,
+  as: Component = "div",
+  className,
+  style
+}) => {
+  const [shouldRender, setShouldRender] = useState(show);
+  const [phase, setPhase] = useState(
+    show ? "entered" : "left"
+  );
+  const isInitialMount = useRef(true);
+  useEffect(() => {
+    const isMount = isInitialMount.current;
+    isInitialMount.current = false;
+    if (show) {
+      setShouldRender(true);
+      if (!isMount || appear) {
+        setPhase("entering");
+        onEnter?.();
+        const timer = setTimeout(() => {
+          setPhase("entered");
+          onEnterComplete?.();
+        }, duration ?? 200);
+        return () => clearTimeout(timer);
+      } else {
+        setPhase("entered");
+      }
+    } else {
+      setPhase("leaving");
+      onLeave?.();
+      const timer = setTimeout(() => {
+        setPhase("left");
+        onLeaveComplete?.();
+        if (unmountOnHide) {
+          setShouldRender(false);
+        }
+      }, duration ?? 200);
+      return () => clearTimeout(timer);
+    }
+  }, [show, appear, duration, unmountOnHide, onEnter, onEnterComplete, onLeave, onLeaveComplete]);
+  if (!shouldRender) {
+    return null;
+  }
+  const transitionClass = [
+    "flight-transition",
+    `flight-transition-${phase}`,
+    typeof type === "string" ? `flight-transition-${type}` : void 0,
+    className
+  ].filter(Boolean).join(" ");
+  const inlineStyle = {
+    ...style
+  };
+  if (duration !== void 0) {
+    inlineStyle["--flight-transition-duration"] = `${duration}ms`;
+  }
+  return createElement(
+    Component,
+    { className: transitionClass, style: inlineStyle },
+    children
+  );
+};
+var SharedElement = ({
+  children,
+  name,
+  as: Component = "div",
+  className,
+  style
+}) => {
+  const ref = useRef(null);
+  useEffect(() => {
+    const element = ref.current;
+    if (element) {
+      element.style.viewTransitionName = name;
+      return () => {
+        element.style.viewTransitionName = "";
+      };
+    }
+  }, [name]);
+  return createElement(
+    Component,
+    {
+      ref,
+      className,
+      style,
+      "data-transition-name": name
+    },
+    children
+  );
+};
+var TransitionLink = ({
+  children,
+  href,
+  transition,
+  replace = false,
+  prefetch = false,
+  onClick,
+  ...props
+}) => {
+  const { startTransition, manager } = useTransition();
+  const handleClick = useCallback(async (e) => {
+    onClick?.(e);
+    if (e.defaultPrevented) return;
+    if (e.button !== 0 || e.metaKey || e.ctrlKey || e.shiftKey || e.altKey) {
+      return;
+    }
+    if (href && !href.startsWith("/") && !href.startsWith(window.location.origin)) {
+      return;
+    }
+    e.preventDefault();
+    const targetPath = href?.startsWith("/") ? href : new URL(href ?? "", window.location.origin).pathname;
+    await startTransition(targetPath, transition !== void 0 ? { default: transition } : void 0);
+    if (replace) {
+      window.history.replaceState({}, "", targetPath);
+    } else {
+      window.history.pushState({}, "", targetPath);
+    }
+    window.dispatchEvent(new PopStateEvent("popstate"));
+  }, [href, transition, replace, onClick, startTransition]);
+  return /* @__PURE__ */ jsx("a", { href, onClick: handleClick, ...props, children });
+};
+
+export { PageTransition, SharedElement, Transition, TransitionLink, TransitionProvider, useIsTransitioning, useReducedMotion, useTransition, useTransitionDirection, useTransitionState };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map