aniview 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2026-02-10
+
+### Added
+
+- `Aniview` — core animated component with spatial and event-driven keyframes
+- `AniviewProvider` — context provider with gesture handling and spring physics
+- `AniviewConfig` — 2D grid layout engine with page mapping, overlaps, and adjacency graphs
+- `AniviewPanel` / `PanelFrame` — pre-styled panel components
+- `useAniview` — hook to access Aniview context (dimensions, events, config)
+- `useAniviewLock` — hook for directional gesture locking
+- Smart color interpolation (transparent-aware, no gray artifacts)
+- Pre-computed animation grid (zero runtime frame searches)
+- Worklet-optimized rendering (UI thread only)
+- Full TypeScript type definitions

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Madelyn Cruz Tan (TitanicEclair)
+
+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,130 @@
+# Aniview
+
+[![npm version](https://badge.fury.io/js/aniview.svg)](https://www.npmjs.com/package/aniview)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![React Native](https://img.shields.io/badge/React%20Native-%3E%3D0.71-blue)](https://reactnative.dev/)
+
+> A high-performance, coordinate-based animation engine for React Native. Create fluid, multi-dimensional page transitions with spatial and event-driven animations.
+
+## Features
+
+- **Pre-computed Animation Grid** - Zero runtime frame searches
+- **Spatial & Event-Driven** - Animate based on position OR custom events
+- **Gesture Coordination** - Built-in lock system for complex UI interactions
+- **Smart Color Interpolation** - Transparent-aware color transitions
+- **Worklet-Optimized** - Runs entirely on the UI thread
+- **2D Layout Engine** - Grid-based page navigation with overlap support
+- **TypeScript First** - Full type safety out of the box
+
+## Quick Start
+
+```bash
+npm install aniview react-native-reanimated react-native-gesture-handler
+```
+
+### Basic Example
+
+```tsx
+import { AniviewProvider, Aniview } from "aniview";
+
+// 1. Define your layout (3x3 grid)
+const config = new AniviewConfig(
+  [
+    [1, 1, 1],
+    [1, 1, 1],
+    [1, 1, 1],
+  ],
+  0, // default page
+  { HOME: 0, PROFILE: 1, SETTINGS: 2 }, // page map
+);
+
+// 2. Wrap your app
+function App() {
+  return (
+    <AniviewProvider config={config}>
+      <Header />
+      <Content />
+    </AniviewProvider>
+  );
+}
+
+// 3. Animate components
+function Header() {
+  return (
+    <Aniview
+      pageId="HOME"
+      frames={{
+        profile: {
+          page: "PROFILE",
+          style: { backgroundColor: "blue" },
+        },
+      }}
+      style={{ height: 100, backgroundColor: "white" }}
+    >
+      <Text>My Header</Text>
+    </Aniview>
+  );
+}
+```
+
+## Documentation
+
+- **[Getting Started](docs/01-getting-started.md)** - Installation and first steps
+- **[Core Concepts](docs/02-core-concepts.md)** - Understanding the architecture
+- **[API Reference](docs/03-api-reference.md)** - Complete API documentation
+- **[Advanced Patterns](docs/04-advanced-patterns.md)** - Composition, Persistence & Virtualization
+- **[Examples & Recipes](docs/05-examples.md)** - Full Example App Walkthrough
+- **[Performance Guide](docs/06-performance.md)** - Optimization techniques
+- **[Testing](docs/07-testing.md)** - How to test Aniview components
+- **[Gesture Control](docs/08-gesture-control.md)** - Lock system and gesture coordination
+- **[Reporting Issues](docs/09-reporting-issues.md)** - Bug reports and feature requests
+
+## Key Concepts
+
+### The Grid System
+
+Aniview uses a **2D grid layout** where each cell represents a "page":
+
+```
+[0, 1, 2]  →  Pages 0, 1, 2 (horizontal row)
+[3, 4, 5]  →  Pages 3, 4, 5 (second row)
+```
+
+Components declare where they "live" (`pageId`) and how they transform when navigating to other pages (`frames`).
+
+### Animation Types
+
+1. **Spatial Animations** - Triggered by page navigation (X/Y position)
+2. **Event-Driven Animations** - Triggered by custom SharedValues (scroll, zoom, etc.)
+
+### The Baking Process
+
+On mount, Aniview:
+
+1. Pre-computes a **grid of all possible states**
+2. Organizes them into **horizontal and vertical lanes**
+3. Marks **constant values** to skip interpolation
+4. All this happens **once**, not on every frame
+
+## Platform Support
+
+Aniview is designed for **React Native** (iOS and Android). It is compatible with:
+
+- **Expo** managed workflow (SDK 49+)
+- **React Native CLI** projects
+- **New Architecture** (Fabric) — fully compatible (pure JS/TS + Reanimated worklets)
+
+## Contributing
+
+We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details.
+
+## License
+
+MIT © Madelyn Cruz Tan
+
+## Credits
+
+Built with:
+
+- [react-native-reanimated](https://github.com/software-mansion/react-native-reanimated)
+- [react-native-gesture-handler](https://github.com/software-mansion/react-native-gesture-handler)

package/dist/Aniview.d.ts

@@ -0,0 +1,63 @@
+import React from 'react';
+import { AniviewProps } from './useAniviewContext';
+/**
+ * **Aniview** — Absolute World Coordinate Animation Engine Component
+ *
+ * The core animated view that interpolates its style properties based on
+ * the camera's position in a virtual 2D world coordinate system. Each
+ * `Aniview` belongs to a specific `pageId` (its "home page") and defines
+ * `frames` — keyframes that describe how the component should look when
+ * the camera is at a different page or when a custom event reaches a
+ * certain value.
+ *
+ * ### How it works (the "Baking" pipeline)
+ *
+ * 1. On mount (or when `frames`/`style`/`dimensions` change), Aniview
+ *    runs a one-time **bake** on the JS thread. This pre-computes a
+ *    lookup grid of style values indexed by world coordinates.
+ * 2. On every frame, `useAnimatedStyle` reads the camera SharedValues
+ *    (`events.x`, `events.y`) and performs O(1) segment lookups +
+ *    linear/color interpolation — no searching, no string parsing.
+ * 3. The baked data also powers **native virtualization**: components
+ *    farther than 1.5× screen width from the camera are hidden via
+ *    `opacity: 0`, keeping the render tree lightweight.
+ *
+ * ### Key design choices
+ *
+ * - **Absolute positioning**: All Aniview children are rendered with
+ *   `position: 'absolute'` and placed via `translateX`/`translateY`
+ *   relative to the camera. This decouples layout from animation.
+ * - **Smart color interpolation**: When transitioning to/from
+ *   `transparent`, the RGB of the non-transparent color is preserved
+ *   to avoid grey flash artifacts.
+ * - **Selective unmounting**: Non-persistent components unmount when
+ *   offscreen (after snapping completes) to reclaim memory. Set
+ *   `persistent={true}` for 3D/GL content that must stay mounted.
+ *
+ * @param props Standard `ViewProps` plus:
+ * @param props.pageId - The page this component belongs to (numeric index or semantic name from `pageMap`)
+ * @param props.frames - Keyframe definitions. Object keys are frame names, values are {@link AniviewFrame}
+ * @param props.persistent - If `true`, stays mounted even when far offscreen. Required for WebGL/Three.js canvases. Default: `false`
+ * @param props.style - Base styles applied when at home position. Numeric and color props here become the interpolation baseline.
+ * @param props.pointerEvents - Standard RN pointer events. Useful for overlay pages that shouldn't block touches.
+ *
+ * @example
+ * ```tsx
+ * <Aniview
+ *   pageId="HOME"
+ *   style={{ width: '100%', height: '100%', backgroundColor: '#fff' }}
+ *   frames={{
+ *     away: { page: 'SETTINGS', opacity: 0 },
+ *     scrolled: { event: 'scrollY', value: 100, style: { transform: [{ translateY: -50 }] } },
+ *   }}
+ * >
+ *   <HomeContent />
+ * </Aniview>
+ * ```
+ *
+ * @see {@link AniviewProvider} for setting up the coordinate system
+ * @see {@link AniviewConfig} for layout and gesture configuration
+ * @see {@link useAniview} for accessing context from child components
+ */
+export default function Aniview(props: AniviewProps): React.JSX.Element | null;
+//# sourceMappingURL=Aniview.d.ts.map

package/dist/Aniview.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Aniview.d.ts","sourceRoot":"","sources":["../src/Aniview.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAoD,MAAM,OAAO,CAAC;AAUzE,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAiMnD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DG;AACH,MAAM,CAAC,OAAO,UAAU,OAAO,CAAC,KAAK,EAAE,YAAY,4BA6lBlD"}