@onlynative/inertia-gradients 0.0.1-alpha.5 → 0.0.1-alpha.7

package/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+All notable changes to `@onlynative/inertia-gradients` are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). Pre-`1.0`, breaking changes may land in minor versions and are called out under their release.
+
+This package ships in lockstep with `@onlynative/inertia` — version numbers track the core release that introduced or last touched the adapter.
+
+## [Unreleased]
+
+## [0.0.1-alpha.6] — 2026-05-22
+
+### Added
+
+- `MotionLinearGradient` over `expo-linear-gradient`. Accepts the same `initial` / `animate` / `transition` shape as the core `Motion.*` primitives, with animatable keys for `colors`, `start`, `end`, and `locations`.
+
+[unreleased]: https://github.com/onlynative/inertia/compare/v0.0.1-alpha.6...HEAD
+[0.0.1-alpha.6]: https://github.com/onlynative/inertia/releases/tag/v0.0.1-alpha.6

package/llms.txt

@@ -0,0 +1,95 @@
+> @onlynative/inertia-gradients — adapter package for @onlynative/inertia.
+> This file is generated from the matching docs page by scripts/build-llms.mjs — do not edit by hand.
+
+> Full docs:    https://onlynative.github.io/inertia/
+> Core overview: see @onlynative/inertia/llms.txt (or docs/static/llms.txt in the repo)
+> Source:        https://github.com/onlynative/inertia
+
+---
+# Gradients
+
+`@onlynative/inertia-gradients` adds an animatable linear gradient built on `expo-linear-gradient`. It is an **optional** sibling package — install it only when you need to animate gradient stops. The core library has no required `expo-linear-gradient` dependency.
+
+`MotionLinearGradient` accepts the same `initial` / `animate` / `transition` shape as the core `Motion.*` primitives, with animatable keys for `colors`, `start`, `end`, and `locations`.
+
+## Install
+
+```bash
+yarn add @onlynative/inertia-gradients expo-linear-gradient
+```
+
+`expo-linear-gradient` works in bare React Native projects as well as Expo — no `expo-modules-core` runtime is required.
+
+## Usage
+
+```tsx
+import { MotionLinearGradient } from '@onlynative/inertia-gradients'
+
+function Hero() {
+  return (
+    <MotionLinearGradient
+      colors={['#0f172a', '#1e293b']}
+      animate={{ colors: ['#7c3aed', '#0ea5e9'] }}
+      transition={{ type: 'timing', duration: 600 }}
+      style={StyleSheet.absoluteFill}
+    />
+  )
+}
+```
+
+The static `colors` prop is required — it sets the visual on first render and **locks the slot count** for the lifetime of the component. To resize the gradient (e.g. swap a 2-stop for a 3-stop), remount via `key={...}`. The component throws in dev if `colors.length` changes between renders.
+
+## Animatable props
+
+| Key         | Shape                      | Notes                                                                                                                         |
+| ----------- | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `colors`    | `readonly string[]`        | Element-wise color interpolation via Reanimated's color setter. Length must match the static `colors` prop.                   |
+| `start`     | `{ x: number, y: number }` | Normalized `[0, 1]` coordinates. `x` and `y` animate independently — useful for rotating gradient direction.                  |
+| `end`       | `{ x: number, y: number }` | Same shape as `start`.                                                                                                        |
+| `locations` | `readonly number[]`        | Optional stop positions. If supplied at mount, must remain supplied and same-length as `colors` for the component's lifetime. |
+
+Per-property transitions work just like the core primitives:
+
+```tsx
+<MotionLinearGradient
+  colors={['#000', '#000']}
+  animate={{
+    colors: ['#7c3aed', '#0ea5e9'],
+    start: { x: 0, y: 0 },
+    end: { x: 1, y: 1 },
+  }}
+  transition={{
+    colors: { type: 'timing', duration: 600 },
+    start: { type: 'spring', tension: 80, friction: 14 },
+    end: { type: 'spring', tension: 80, friction: 14 },
+  }}
+/>
+```
+
+## `initial`
+
+Pass `initial` to override the mount-frame values (so the component starts somewhere other than the static props), or `initial={false}` to start at the `animate` target with no mount animation.
+
+```tsx
+<MotionLinearGradient
+  colors={['#111', '#222']}
+  initial={{ colors: ['#000', '#000'] }}      // fade up from black
+  animate={{ colors: ['#7c3aed', '#0ea5e9'] }}
+/>
+
+<MotionLinearGradient
+  colors={['#111', '#222']}
+  initial={false}                              // skip the mount animation
+  animate={{ colors: ['#7c3aed', '#0ea5e9'] }}
+/>
+```
+
+## Reduced motion
+
+`MotionLinearGradient` participates in [`<MotionConfig reducedMotion>`](./motion-config.md) the same way the core primitives do — when the OS reduce-motion setting is on (or you pass `reducedMotion="always"`), transitions resolve as direct assignment instead of `withSpring` / `withTiming`.
+
+## What this primitive doesn't do (v0.2)
+
+- **Radial / conic gradients** — linear-only for v0.2. Radial lands in v0.3 once the linear API is validated.
+- **Slot-count resize** — the colors array length is locked at mount. To change it, remount via `key={...}`.
+- **Per-stop sequence keyframes** — `animate.colors` accepts a single target array, not a nested array of arrays. For chained gradient transitions, drive the target through state and let React re-render.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlynative/inertia-gradients",
-  "version": "0.0.1-alpha.5",
+  "version": "0.0.1-alpha.7",
   "description": "Animated linear gradient primitive for @onlynative/inertia, built on expo-linear-gradient.",
   "license": "MIT",
   "author": "OnlyNative",
@@ -41,6 +41,7 @@
   "files": [
     "dist",
     "src",
+    "llms.txt",
     "README.md",
     "LICENSE",
     "CHANGELOG.md",
@@ -48,7 +49,7 @@
     "!**/*.test.*"
   ],
   "peerDependencies": {
-    "@onlynative/inertia": ">=0.0.1-alpha.5",
+    "@onlynative/inertia": ">=0.0.1-alpha.7",
     "expo-linear-gradient": ">=14.0.0",
     "react": ">=19.0.0",
     "react-native": ">=0.81.0",
@@ -69,7 +70,7 @@
     "size-limit": "^11.1.0",
     "tsup": "^8.3.5",
     "typescript": "^5.7.3",
-    "@onlynative/inertia": "0.0.1-alpha.5"
+    "@onlynative/inertia": "0.0.1-alpha.7"
   },
   "publishConfig": {
     "access": "public"