@onlynative/inertia 0.0.1-alpha.7 → 0.0.1-alpha.8

package/README.md

@@ -88,7 +88,7 @@ Plus, on any transition: `delay`, `repeat`. Per-property transitions take preced
 
 Numeric: `opacity`, `translateX`, `translateY`, `scale`, `scaleX`, `scaleY`, `rotate`, `rotateX`, `rotateY`, `width`, `height`, `borderRadius`. Color: `backgroundColor`, `borderColor`, `color`, `tintColor` (Image only — `Motion.View` rejects it at compile time). Layout transforms via `transform: [...]`. Color targets are forwarded straight through `withSpring` / `withTiming`; Reanimated's value setter packs the string to RGBA and interpolates on the UI thread.
 
-SVG path morphing ships in the [`@onlynative/inertia-svg`](../svg) adapter (`MotionPath`). Out of scope for `0.x`: shared-element transitions across screens (Reanimated 4 dropped `sharedTransitionTag`; a measure-based replacement is in design).
+SVG path morphing ships in the [`@onlynative/inertia-svg`](../svg) adapter (`MotionPath`). Shared-element transitions across screens are wired through the `layoutId` prop — pair the same id on a source and target `Motion.*` and Inertia FLIPs between them on mount.
 
 ## When not to use the core package alone
 

package/dist/gestureLayer/index.d.mts

@@ -0,0 +1,119 @@
+import { AnimatedStyle } from 'react-native-reanimated';
+import { U as UseGestureHandlers } from '../useGesture-BnBF4OtT.mjs';
+import { T as TransitionConfig, h as GestureLayerTransitions } from '../types-BwyvoH2V.mjs';
+import 'react';
+import 'react-native';
+
+/**
+ * A single gesture-layer style — a flat map of style keys to a value. Numeric
+ * values participate in clamped-max composition (the "strongest active layer
+ * wins" model used by MD3 state-layer haloes); string values are treated as
+ * colors and composed via priority cascade with `interpolateColor`.
+ *
+ * The hook does not validate that string values are valid colors — passing
+ * something like `borderStyle: 'solid'` will crash inside the worklet. Keep
+ * string values to color strings.
+ */
+type GestureLayerStyle = {
+    [key: string]: number | string | undefined;
+};
+/**
+ * Per-state style maps. Every key is optional; missing layers default to
+ * `rest` (or `0` / `'transparent'` if `rest` is also absent for that key).
+ *
+ * - `rest` — base values, applied when no other layer is active.
+ * - `hovered` / `focused` / `focusVisible` / `pressed` — gesture-driven
+ *   states tracked via the underlying `useGesture` hook. Each owns an
+ *   independent 0↔1 progress that fades the layer in/out per the configured
+ *   transition.
+ * - `disabled` — gated by the JS-side `options.disabled` flag rather than a
+ *   gesture. Sits at the top of the priority cascade and overrides every
+ *   gesture layer when active.
+ */
+interface GestureLayerStates {
+    rest?: GestureLayerStyle;
+    hovered?: GestureLayerStyle;
+    focused?: GestureLayerStyle;
+    focusVisible?: GestureLayerStyle;
+    pressed?: GestureLayerStyle;
+    disabled?: GestureLayerStyle;
+}
+interface UseGestureLayerOptions {
+    /**
+     * When `true`, the `disabled` layer becomes active (or `rest` if `disabled`
+     * is undefined). Animates via the top-level transition or the library
+     * default spring; per-layer transitions (`GestureLayerTransitions`) do not
+     * apply to `disabled`.
+     */
+    disabled?: boolean;
+    /**
+     * Transition forwarded to the underlying `useGesture` hook. Either a single
+     * `TransitionConfig` for every gesture layer, or a `GestureLayerTransitions`
+     * map for per-layer fades. Reduced motion collapses every transition to
+     * `no-animation`.
+     */
+    transition?: TransitionConfig | GestureLayerTransitions;
+}
+interface UseGestureLayerResult {
+    /**
+     * Animated style produced by `useAnimatedStyle` — spread on an
+     * `Animated.View` or pass through `<Motion.View style={...} />`.
+     */
+    style: AnimatedStyle<Record<string, unknown>>;
+    /** Handlers to spread on the receiving `Pressable`. */
+    handlers: UseGestureHandlers;
+}
+/**
+ * A "strongest active layer wins" interactive-feedback primitive. Sits one
+ * step above `useGesture()` — the consumer supplies the per-state target
+ * values, the hook handles the four gesture progress shared values, the
+ * disabled override, the worklet, and the transition.
+ *
+ * Composition model:
+ *
+ * - **Numeric keys** (opacity, scale, borderWidth, etc.) compose via
+ *   clamped-max with `rest` as the floor:
+ *   `out = max(rest, ...for each active gesture layer: lerp(rest, layer, progress))`.
+ *   This matches the MD3 state-layer halo pattern — multiple states active
+ *   simultaneously raise the value to the strongest, not the sum.
+ * - **Color keys** (any string value) compose via priority cascade with
+ *   `interpolateColor`, lowest priority first: `hovered → focused →
+ *   focusVisible → pressed`. Clamped-max doesn't apply to colors; this
+ *   matches the cascade used by the declarative `gesture` prop.
+ * - **Disabled** sits at the top of the cascade for both numeric and color
+ *   keys — when active, it lerps the composed value toward the `disabled`
+ *   target.
+ *
+ * Reach for this when you want MD3 / iOS-translucent state-layer overlays
+ * without rewriting the worklet by hand for every consumer; reach for plain
+ * `useGesture()` when you need a composition model this hook doesn't
+ * express (additive, multiply, per-key custom blends).
+ *
+ * @example MD3 state-layer halo
+ * ```tsx
+ * import { useGestureLayer } from '@onlynative/inertia/gesture-layer'
+ * import Animated from 'react-native-reanimated'
+ * import { Pressable } from 'react-native'
+ *
+ * function SwitchHalo({ disabled }: { disabled?: boolean }) {
+ *   const { style, handlers } = useGestureLayer(
+ *     {
+ *       rest: { opacity: 0, backgroundColor: 'transparent' },
+ *       hovered: { opacity: 0.08, backgroundColor: '#000' },
+ *       focused: { opacity: 0.10, backgroundColor: '#000' },
+ *       pressed: { opacity: 0.12, backgroundColor: '#000' },
+ *     },
+ *     { disabled, transition: { type: 'timing', duration: 150 } },
+ *   )
+ *
+ *   return (
+ *     <Pressable {...handlers}>
+ *       <Animated.View style={style} />
+ *     </Pressable>
+ *   )
+ * }
+ * ```
+ */
+declare function useGestureLayer(states: GestureLayerStates, options?: UseGestureLayerOptions): UseGestureLayerResult;
+
+export { type GestureLayerStates, type GestureLayerStyle, type UseGestureLayerOptions, type UseGestureLayerResult, useGestureLayer };

package/dist/gestureLayer/index.d.ts

@@ -0,0 +1,119 @@
+import { AnimatedStyle } from 'react-native-reanimated';
+import { U as UseGestureHandlers } from '../useGesture-BPPp9LhV.js';
+import { T as TransitionConfig, h as GestureLayerTransitions } from '../types-BwyvoH2V.js';
+import 'react';
+import 'react-native';
+
+/**
+ * A single gesture-layer style — a flat map of style keys to a value. Numeric
+ * values participate in clamped-max composition (the "strongest active layer
+ * wins" model used by MD3 state-layer haloes); string values are treated as
+ * colors and composed via priority cascade with `interpolateColor`.
+ *
+ * The hook does not validate that string values are valid colors — passing
+ * something like `borderStyle: 'solid'` will crash inside the worklet. Keep
+ * string values to color strings.
+ */
+type GestureLayerStyle = {
+    [key: string]: number | string | undefined;
+};
+/**
+ * Per-state style maps. Every key is optional; missing layers default to
+ * `rest` (or `0` / `'transparent'` if `rest` is also absent for that key).
+ *
+ * - `rest` — base values, applied when no other layer is active.
+ * - `hovered` / `focused` / `focusVisible` / `pressed` — gesture-driven
+ *   states tracked via the underlying `useGesture` hook. Each owns an
+ *   independent 0↔1 progress that fades the layer in/out per the configured
+ *   transition.
+ * - `disabled` — gated by the JS-side `options.disabled` flag rather than a
+ *   gesture. Sits at the top of the priority cascade and overrides every
+ *   gesture layer when active.
+ */
+interface GestureLayerStates {
+    rest?: GestureLayerStyle;
+    hovered?: GestureLayerStyle;
+    focused?: GestureLayerStyle;
+    focusVisible?: GestureLayerStyle;
+    pressed?: GestureLayerStyle;
+    disabled?: GestureLayerStyle;
+}
+interface UseGestureLayerOptions {
+    /**
+     * When `true`, the `disabled` layer becomes active (or `rest` if `disabled`
+     * is undefined). Animates via the top-level transition or the library
+     * default spring; per-layer transitions (`GestureLayerTransitions`) do not
+     * apply to `disabled`.
+     */
+    disabled?: boolean;
+    /**
+     * Transition forwarded to the underlying `useGesture` hook. Either a single
+     * `TransitionConfig` for every gesture layer, or a `GestureLayerTransitions`
+     * map for per-layer fades. Reduced motion collapses every transition to
+     * `no-animation`.
+     */
+    transition?: TransitionConfig | GestureLayerTransitions;
+}
+interface UseGestureLayerResult {
+    /**
+     * Animated style produced by `useAnimatedStyle` — spread on an
+     * `Animated.View` or pass through `<Motion.View style={...} />`.
+     */
+    style: AnimatedStyle<Record<string, unknown>>;
+    /** Handlers to spread on the receiving `Pressable`. */
+    handlers: UseGestureHandlers;
+}
+/**
+ * A "strongest active layer wins" interactive-feedback primitive. Sits one
+ * step above `useGesture()` — the consumer supplies the per-state target
+ * values, the hook handles the four gesture progress shared values, the
+ * disabled override, the worklet, and the transition.
+ *
+ * Composition model:
+ *
+ * - **Numeric keys** (opacity, scale, borderWidth, etc.) compose via
+ *   clamped-max with `rest` as the floor:
+ *   `out = max(rest, ...for each active gesture layer: lerp(rest, layer, progress))`.
+ *   This matches the MD3 state-layer halo pattern — multiple states active
+ *   simultaneously raise the value to the strongest, not the sum.
+ * - **Color keys** (any string value) compose via priority cascade with
+ *   `interpolateColor`, lowest priority first: `hovered → focused →
+ *   focusVisible → pressed`. Clamped-max doesn't apply to colors; this
+ *   matches the cascade used by the declarative `gesture` prop.
+ * - **Disabled** sits at the top of the cascade for both numeric and color
+ *   keys — when active, it lerps the composed value toward the `disabled`
+ *   target.
+ *
+ * Reach for this when you want MD3 / iOS-translucent state-layer overlays
+ * without rewriting the worklet by hand for every consumer; reach for plain
+ * `useGesture()` when you need a composition model this hook doesn't
+ * express (additive, multiply, per-key custom blends).
+ *
+ * @example MD3 state-layer halo
+ * ```tsx
+ * import { useGestureLayer } from '@onlynative/inertia/gesture-layer'
+ * import Animated from 'react-native-reanimated'
+ * import { Pressable } from 'react-native'
+ *
+ * function SwitchHalo({ disabled }: { disabled?: boolean }) {
+ *   const { style, handlers } = useGestureLayer(
+ *     {
+ *       rest: { opacity: 0, backgroundColor: 'transparent' },
+ *       hovered: { opacity: 0.08, backgroundColor: '#000' },
+ *       focused: { opacity: 0.10, backgroundColor: '#000' },
+ *       pressed: { opacity: 0.12, backgroundColor: '#000' },
+ *     },
+ *     { disabled, transition: { type: 'timing', duration: 150 } },
+ *   )
+ *
+ *   return (
+ *     <Pressable {...handlers}>
+ *       <Animated.View style={style} />
+ *     </Pressable>
+ *   )
+ * }
+ * ```
+ */
+declare function useGestureLayer(states: GestureLayerStates, options?: UseGestureLayerOptions): UseGestureLayerResult;
+
+export { type GestureLayerStates, type GestureLayerStyle, type UseGestureLayerOptions, type UseGestureLayerResult, useGestureLayer };