{"id":"whotookazimus/react-flow","name":"react-flow","scope":"whotookazimus","platform":"roblox","description":"React Animation Library for Roblox","version":"0.4.5","latest":"0.4.5","versions":["0.4.1","0.4.3","0.4.4","0.4.5"],"license":"MIT","licenseRating":"safe","licenseCaveats":["License identified from the packaged LICENSE file; the manifest declared none."],"licenseVerified":true,"dependencies":{"evaera/promise":{"version":"^4.0.0","alias":"Promise"},"jsdotlua/react":{"version":"^17.2.1","alias":"React"},"jsdotlua/react-roblox":{"version":"^17.2.1","alias":"ReactRoblox"}},"integrity":"1cc5b76b9bccef66104c5a9411fb84a11451be35c95db23267e4ffc80e638846","likes":0,"downloads":0,"install":"forest install whotookazimus/react-flow","url":"https://forest.dev/p/roblox/whotookazimus/react-flow","files":"https://api.forest.dev/ai/package/roblox/whotookazimus/react-flow/files","readme":"\r\n<h3 align=\"center\">\r\n    <img src=\"https://i.imgur.com/I1CRYmc.png\" alt=\"Slither Icon\" width=\"160\" />\r\n    <br />\r\n\t<br />\r\n\tReact-Flow\r\n</h3>\r\n\r\n<div align=\"center\">\r\n⚡ A blazing fast animation library for React-Lua interfaces, providing stateful animations with unrestricted flexibility and performance. 🤌\r\n</div>\r\n\r\n<div align=\"center\">\r\n<br />\r\n\r\n[![Version](https://img.shields.io/github/v/release/outofbears/react-flow.svg?style=flat-square)](https://github.com/outofbears/react-flow/releases)\r\n[![License](https://img.shields.io/github/license/outofbears/react-flow.svg?style=flat-square)](https://github.com/outofbears/react-flow/blob/main/LICENSE.md)\r\n[![Stars](https://img.shields.io/github/stars/outofbears/react-flow.svg?style=flat-square)](https://github.com/outofbears/react-flow/stargazers)\r\n[![Forks](https://img.shields.io/github/forks/outofbears/react-flow.svg?style=flat-square)](https://github.com/outofbears/react-flow/network/members)\r\n[![Watchers](https://img.shields.io/github/watchers/outofbears/react-flow.svg?style=flat-square)](https://github.com/outofbears/react-flow/watchers)\r\n[![Issues](https://img.shields.io/github/issues/outofbears/react-flow.svg?style=flat-square)](https://github.com/outofbears/react-flow/issues)\r\n[![Pull Requests](https://img.shields.io/github/issues-pr/outofbears/react-flow.svg?style=flat-square)](https://github.com/outofbears/react-flow/pulls)\r\n[![Last Commit](https://img.shields.io/github/last-commit/outofbears/react-flow.svg?style=flat-square)](https://github.com/outofbears/react-flow/commits/main)\r\n\r\n\r\n</div>\r\n\r\n\r\n## 📋 Table of Contents\r\n\r\n- [Features](#-features)\r\n- [Installation](#-installation)\r\n  - [Using Wally](#using-wally-recommended)\r\n  - [Manual Installation](#manual-installation)\r\n- [Hooks](#-hooks)\r\n  - [useSpring](#usespring)\r\n  - [useTween](#usetween)\r\n  - [useGroupAnimation](#usegroupanimation)\r\n- [Supported Value Types](#-supported-value-types)\r\n- [Showcase](#-showcase)\r\n- [Contribution](#-contribution)\r\n- [License](#-license)\r\n\r\n## ✨ Features\r\n\r\n- 🔄 **Stateful Animations** - Animations that automatically respond to your component's state changes, ensuring UI and state stay perfectly synchronized\r\n- ⛓️ **Chainable Animations** - Effortlessly build complex animation sequences that flow naturally from one to another\r\n- 🔀 **Interruptible Flows** - Gracefully handle user interactions by modifying animations mid-flight without jarring visual transitions\r\n- 🧩 **Composable System** - Create reusable animation components that can be combined in endless ways for consistent motion design\r\n- 🛡️ **Memory-Safe Design** - Built with React's lifecycle in mind to prevent memory leaks and ensure proper cleanup\r\n\r\n## 📦 Installation\r\n\r\n### Using Wally (Recommended)\r\n\r\nAdd React-Flow to your `wally.toml` file:\r\n\r\n```toml\r\n[dependencies]\r\nReactFlow = \"outofbears/react-flow@0.4.0\"\r\n```\r\n\r\nThen install with:\r\n```bash\r\nwally install\r\n```\r\n\r\n### Manual Installation\r\n\r\nSimply clone the repository and include it in your project structure.\r\n\r\n### Requiring the Module\r\n\r\nOnce installed, require React-Flow in your code:\r\n\r\n```lua\r\n-- For common Roblox setups:\r\nlocal ReactFlow = require(ReplicatedStorage.Packages.ReactFlow)\r\n```\r\n\r\n## 🔧 Hooks\r\n\r\n### `useSpring`\r\n\r\nCreates spring-based physics animations with React bindings. Springs provide natural, bouncy motion that reacts to changes dynamically.\r\n\r\n**Arguments:**\r\n- **config:** A configuration table with the following properties:\r\n  - **start:** Initial value of the animation (required)\r\n  - **target:** Target value to animate toward (optional)\r\n  - **speed:** Spring stiffness - higher values create faster motion (default: 10)\r\n  - **damper:** Damping ratio - higher values reduce bouncing (default: 1)\r\n\r\n**Returns:**  \r\nA binding that updates as the animation progresses, and an update function to modify the animation.\r\n\r\n**Example:**\r\n```lua\r\nlocal useSpring = ReactFlow.useSpring\r\n\r\n-- Inside your component:\r\nlocal position, updatePosition = useSpring({\r\n    start = UDim2.fromScale(0, 0),           -- Initial Value (required)\r\n    target = UDim2.fromScale(0.5, 0.5),      -- Target value (optional)\r\n\r\n    speed = 20,\r\n    damper = 0.8,\r\n})\r\n\r\n-- Later, update the spring with new parameters:\r\nupdatePosition({\r\n    target = UDim2.fromScale(0.5, 0.5),\r\n\r\n    speed = 15,\r\n    damper = 0.7,\r\n})\r\n\r\n-- Use in your component:\r\nreturn createElement(\"Frame\", {\r\n    Position = position, -- Use binding directly in property\r\n})\r\n```\r\n\r\n---\r\n\r\n### `useTween`\r\n\r\nCreates tween-based animations that follow a specific timing curve. Ideal for animations that need precise timing or easing effects.\r\n\r\n**Arguments:**\r\n- **config:** A configuration table with the following properties:\r\n  - **start:** Initial value of the animation (required)\r\n  - **target:** Target value to animate toward (optional)\r\n  - **info:** TweenInfo instance (required)\r\n\r\n**Returns:**  \r\nA binding that updates as the animation progresses, and an update function to modify the animation.\r\n\r\n**Example:**\r\n```lua\r\nlocal useTween = ReactFlow.useTween\r\n\r\n-- Inside your component:\r\nlocal transparency, updateTransparency = useTween({\r\n    start = 1,      -- Initial value (required)\r\n    target = 0,     -- Target value (optional)\r\n\r\n    -- TweenInfo - controls duration, easing style, and behavior\r\n    info = TweenInfo.new(\r\n        0.5,\r\n        Enum.EasingStyle.Quad,\r\n        Enum.EasingDirection.Out, \r\n    )\r\n})\r\n\r\n-- Later, update the tween:\r\nupdateTransparency({\r\n    target = 0,     -- New target value\r\n\r\n    -- Optional: update tween configuration\r\n    info = TweenInfo.new(0.3, Enum.EasingStyle.Quart, Enum.EasingDirection.InOut),\r\n})\r\n\r\n-- Use in your component:\r\nreturn createElement(\"Frame\", {\r\n    BackgroundTransparency = transparency,\r\n})\r\n```\r\n\r\n---\r\n\r\n### `useGroupAnimation`\r\n\r\nCreates a group of animations that are managed together as a single entity. With `useGroupAnimation`, you can define multiple animation states by combining the following animation primitives: `useAnimation`, `useSpringAnimation`, `useSequenceAnimation`, and `useTweenAnimation`. This allows you to define complex animation states and switch between them seamlessly at runtime, providing an elegant way to handle UI state transitions.\r\n\r\n**Arguments:**\r\n- **animations:** A table mapping state names (e.g., \"active\", \"inactive\") to their animation definitions. Each definition can mix multiple animation types.\r\n- **defaults:** A table providing the default initial values for each animation property.\r\n\r\n**Returns:**  \r\nA table of bindings for each animation property, and a function (commonly named `playAnimation`) that accepts a state name to switch between the defined animation groups.\r\n\r\n**Example:**\r\n\r\n```lua\r\nlocal useGroupAnimation = ReactFlow.useGroupAnimation\r\nlocal useSequenceAnimation = ReactFlow.useSequenceAnimation\r\nlocal useAnimation = ReactFlow.useAnimation\r\n\r\nlocal Spring = ReactFlow.Spring\r\nlocal Tween = ReactFlow.Tween\r\n\r\n-- Inside your component:\r\nlocal animations, playAnimation = useGroupAnimation({\r\n    enable = useSequenceAnimation({\r\n        {\r\n            timestamp = 0,\r\n            transparency = Tween({target = 0, info = TweenInfo.new(0.2)}),\r\n        },\r\n        {\r\n            timestamp = 0.2,\r\n            position = Spring({target = UDim2.fromScale(0.5, 0.5), speed = 20}),\r\n        },\r\n    }),\r\n    disable = useAnimation({\r\n        transparency = Tween({target = 1, info = TweenInfo.new(0.1)}),\r\n        position = Spring({target = UDim2.fromScale(0.5, 1), speed = 25}),\r\n    }),\r\n}, {\r\n    transparency = 1\r\n    position = UDim2.fromScale(0.5, 1),\r\n})\r\n\r\n-- Play the animation with the specificed name:\r\nif enabled then\r\n    playAnimation(\"enable\")\r\nelse\r\n    playAnimation(\r\n        \"disable\",\r\n        true -- Optional second argument to play animation immediately\r\n    )\r\nend\r\n\r\n-- Use the animation bindings in your component:\r\nreturn createElement(\"Frame\", {\r\n    Size = UDim2.new(0, 100, 0, 100),\r\n    BackgroundTransparency = animations.transparency,\r\n    Position = animations.position,\r\n})\r\n```\r\n\r\n---\r\n\r\n### `TransitionFragment`\r\n\r\n`TransitionFragment` is a component that allows elements to be animated on transition in and out by preserving their presence in a cached fragment during enter and leave operations. When children are added or removed, the component maintains them in the DOM while injecting transition state props, enabling easy enter and exit animations.\r\n\r\nThe component automatically injects the following props into child elements:\r\n\r\n- **entering**: `boolean` - True when the element is being added\r\n- **exiting**: `boolean` - True when the element is being removed\r\n- **onEnterComplete**: `() -> ()` - Callback when enter animation completes\r\n- **onExitComplete**: `() -> ()` - Callback when exit animation completes\r\n\r\nThis allows child components to respond to transition states and perform appropriate animations while `TransitionFragment` handles the lifecycle management.\r\n\r\n**Arguments:**\r\n\r\n- **children**: A table containing the elements to be managed with transitions. Elements are automatically cached and transitioned when added or removed.\r\n\r\n**Returns:**\r\n\r\nA `TransitionFragment` component that handles the transition lifecycle and injects transition props into its children.\r\n\r\n**Example:**\r\n\r\n```lua\r\nlocal function Entry(props: {\r\n    entering: boolean,\r\n    exiting: boolean,\r\n    onEnterComplete: () -> (),\r\n    onExitComplete: () -> ()\r\n})\r\n    useEffect(function()\r\n        if props.entering then\r\n            -- Play enter animation and wait for animation to complete\r\n            props.onEnterComplete()\r\n        end\r\n    end, {props.entering})\r\n\r\n    useEffect(function()\r\n        if props.exiting then\r\n            -- Play enter animation and wait for animation to complete\r\n            props.onExitComplete()\r\n        end\r\n    end, {props.exiting})\r\n\r\n    return ...\r\nend\r\n\r\nreturn createElement(ExampleContainer, {}, {\r\n    entries = createElement(TransitionFragment, {}, {\r\n        -- list of Entries\r\n    })\r\n})\r\n```\r\n\r\n## 📊 Supported Value Types\r\n\r\nReact-Flow supports animating the following userdata and native types:\r\n\r\n### Basic Types\r\n- `number` - Numeric values\r\n- `UDim2` - 2D positioning (scale and offset)\r\n- `UDim` - 1D positioning (scale and offset)\r\n- `Vector2` - 2D vectors\r\n- `Vector3` - 3D vectors\r\n- `Color3` - RGB color values\r\n\r\n### Advanced Types\r\n- `CFrame` - Position and orientation \r\n- `ColorSequenceKeypoint` - Color gradient keypoints\r\n- `NumberSequenceKeypoint` - Number gradient keypoints\r\n- `BrickColor` - Legacy colors\r\n- `NumberRange` - Min/max ranges\r\n- `PhysicalProperties` - Physics simulation properties\r\n- `Ray` - Line segments\r\n- `Region3` - 3D spatial regions\r\n- `Region3int16` - Integer-based 3D regions\r\n\r\n## 🎬 Showcase\r\n\r\n<div align=\"center\">\r\n    <img src=\"https://i.imgur.com/y1On24b.gif\" alt=\"RoundControl\" style=\"width: 600px\" />\r\n    <p style=\"font-size: 1.5em; font-weight: 500\">Round Control Interface</p>\r\n</div>\r\n\r\n<div align=\"center\" style=\"margin-top: 2rem\">\r\n    <img src=\"https://i.imgur.com/tdhyG9f.gif\" alt=\"TowerUpgrade\" style=\"width: 600px\"/>\r\n    <p style=\"font-size: 1.5em; font-weight: 500\">Tower Upgrade Interface</p>\r\n</div>\r\n\r\n<div align=\"center\" style=\"margin-top: 2rem\">\r\n    <img src=\"https://i.imgur.com/9u4xaRN.gif\" alt=\"NPCDialogue\" style=\"width: 600px\"/>\r\n    <p style=\"font-size: 1.5em; font-weight: 500\">NPC Dialogue</p>\r\n</div>\r\n\r\n\r\n## 💖 Contribution\r\n\r\nReact-Flow was developed by [@Bear](https://github.com/OutOfBears) with the assistance of [@GreenDeno](https://github.com/GreenDeno)\r\n\r\n## 📝 License\r\n\r\nThis project is licensed under the MIT License - see the [`LICENSE`](LICENSE.md) file for details.\r\n","readmeTruncated":false}