@rootnative/inertia 0.0.0-alpha.5 → 0.0.0-alpha.6

package/CHANGELOG.md

@@ -4,6 +4,12 @@ All notable changes to `@rootnative/inertia` are documented here. The format fol
 
 ## [Unreleased]
 
+### Added
+
+- **`useShadow` now interpolates CSS `boxShadow`.** The classic `shadow*`/`elevation` keys never reach the web renderer, so a `useShadow` elevation crossfade silently dropped its shadow on web — the platform where hover, its most common driver, matters most (gap surfaced by the RootNative UI Card migration). `ShadowConfig` gains `boxShadow?: string | BoxShadowLayer[]`: pass the CSS string form design systems store elevation tokens in (px lengths only; parsed once on the JS thread, `cubicBezier`-style — malformed tokens throw at setup rather than warning) or structured layers mirroring RN's `BoxShadowValue`. Multi-layer shadows interpolate per layer with CSS-transition padding semantics (shorter side padded with invisible layers; a genuine `inset` mismatch throws); blur clamps at 0 under springy overshoot. Emitted as a `boxShadow` style string — passed through as CSS by react-native-web and rendered natively on RN 0.76+ new architecture; keep `shadow*`/`elevation` alongside it for old-arch native. New `BoxShadowLayer` type exported from the root.
+
+## [0.0.0-alpha.5] - 2026-07-21
+
 ### Changed
 
 - **Non-worklet transformers and easings now dev-warn.** `useTransform`'s transformer overload and custom `timing.easing` functions must be worklets (`'worklet'` directive as the first statement). The previous "plain functions are auto-wrapped" promise was unfulfillable: the directive-wrapped fallback closes over the opaque function reference, not the shared values read inside it, so Reanimated cannot extract dependencies (a `useTransform` derived value silently only refreshed on React re-renders — found via a frozen TextField label float in the UI library) and native builds reject the plain function when the closure is serialized to the UI thread. The fallback wrapper remains as a web-only best effort, but both sites now `console.warn` once in dev (suppressed under Jest, where the shared stubs report every function as non-worklet). Docs (`transitions.md`, `layout.md`, `api/hooks.md`) and docstrings corrected to state the real contract.

package/dist/index.d.mts

@@ -555,11 +555,42 @@ interface UseScrollResult {
  */
 declare function useScroll(): UseScrollResult;
 
+/**
+ * CSS `box-shadow` parsing + pairing for `useShadow`.
+ *
+ * Design systems store web elevation tokens as CSS `box-shadow` strings
+ * (`'0px 1px 2px rgba(0,0,0,0.3), 0px 1px 3px 1px rgba(0,0,0,0.15)'`).
+ * Like `cubicBezier`, this module makes those tokens directly consumable:
+ * strings are parsed once on the JS thread into flat layer records the
+ * `useShadow` worklet can interpolate without any frame-time string work.
+ *
+ * Invalid input **throws** rather than warning — shadow tokens are
+ * constructed at theme/module setup, and a malformed token should fail
+ * loudly there, not silently render the wrong elevation.
+ */
+/**
+ * One layer of a `box-shadow`, structurally mirroring React Native's
+ * `BoxShadowValue` (RN 0.76+ `boxShadow` style). Lengths are px numbers.
+ */
+interface BoxShadowLayer {
+    offsetX: number;
+    offsetY: number;
+    /** Must be >= 0, per CSS. @default 0 */
+    blurRadius?: number;
+    /** @default 0 */
+    spreadDistance?: number;
+    /** Any color string Reanimated's `interpolateColor` accepts. @default 'black' */
+    color?: string;
+    /** @default false */
+    inset?: boolean;
+}
+
 /**
  * Shape accepted on either end of a `useShadow` tween. Every field is
  * optional — only keys present on at least one side participate in the
  * output style. Mirrors the flat shadow keys on `Motion.View`'s `animate`
- * surface, plus the nested `shadowOffset` source.
+ * surface, plus the nested `shadowOffset` source and the CSS `boxShadow`
+ * surface.
  */
 interface ShadowConfig {
     shadowOpacity?: number;
@@ -571,6 +602,19 @@ interface ShadowConfig {
     /** Android elevation. iOS shadow consumers can leave this off. */
     elevation?: number;
     shadowColor?: string;
+    /**
+     * CSS `box-shadow` — the shadow surface on web (react-native-web passes
+     * it through as CSS) and on React Native 0.76+ new-architecture native.
+     * Accepts the CSS string form design systems store elevation tokens in
+     * (`'0px 1px 2px rgba(0,0,0,0.3), 0px 1px 3px 1px rgba(0,0,0,0.15)'`;
+     * px lengths only) or structured layers. Multi-layer shadows interpolate
+     * per layer; when one side has fewer layers, it is padded with invisible
+     * layers, CSS-transition style. A malformed string **throws** at render
+     * (like `cubicBezier` — token mistakes should fail loudly at setup).
+     * The classic `shadow*`/`elevation` keys don't reach the web renderer —
+     * provide `boxShadow` alongside them when the tween must show up there.
+     */
+    boxShadow?: string | readonly BoxShadowLayer[];
 }
 interface UseShadowOptions {
     /** Shadow state at `progress === 0`. */
@@ -607,6 +651,19 @@ interface UseShadowOptions {
  * `shadowColor`, `{ width: 0, height: 0 }` for `shadowOffset`). This is a
  * pure interpolator — to "animate" the shadow, drive `progress` with a
  * spring, timing, or gesture upstream.
+ *
+ * The classic `shadow*`/`elevation` keys don't render on web. When the
+ * tween must show up there (or on RN 0.76+ new-arch native via the CSS
+ * shadow model), provide `boxShadow` on both ends — CSS string tokens or
+ * structured layers; multi-layer shadows interpolate per layer:
+ *
+ * ```tsx
+ * const shadowStyle = useShadow({
+ *   from: { boxShadow: theme.elevation.level1 }, // '0px 1px 2px rgba(0,0,0,0.3), 0px 1px 3px 1px rgba(0,0,0,0.15)'
+ *   to:   { boxShadow: theme.elevation.level2 },
+ *   progress,
+ * })
+ * ```
  */
 declare function useShadow({ from, to, progress, }: UseShadowOptions): ReturnType<typeof useAnimatedStyle>;
 
@@ -623,4 +680,4 @@ declare function useShadow({ from, to, progress, }: UseShadowOptions): ReturnTyp
  */
 declare function useVariants<V extends Readonly<Record<string, object>>>(variants: V, initial?: keyof V & string): VariantController<keyof V & string>;
 
-export { AnimatableValue, type ColorStyleKey, EasingInput, type ExtrapolationMode, Motion, MotionComponent, MotionConfig, type MotionConfigProps, type MotionConfigValue, NamedTransitions, Presence, type PresenceContextValue, type ReducedMotion, type ShadowConfig, SpringTransition, TransitionConfig, TransitionInput, TransitionName, type UseColorTransitionOptions, type UseScrollResult, type UseShadowOptions, type UseTransformOptions, VariantController, buildReleaseAnimation, createMotionComponent, cubicBezier, ensureWorkletEasing, resolveAnimatableValue, resolveNamedTransition, resolveTransition, useAnimation, useBooleanSpring, useColorTransition, useMotionConfig, useMotionValue, useNamedTransitions, usePresence, useScroll, useShadow, useShouldReduceMotion, useSpring, useTransform, useVariants };
+export { AnimatableValue, type BoxShadowLayer, type ColorStyleKey, EasingInput, type ExtrapolationMode, Motion, MotionComponent, MotionConfig, type MotionConfigProps, type MotionConfigValue, NamedTransitions, Presence, type PresenceContextValue, type ReducedMotion, type ShadowConfig, SpringTransition, TransitionConfig, TransitionInput, TransitionName, type UseColorTransitionOptions, type UseScrollResult, type UseShadowOptions, type UseTransformOptions, VariantController, buildReleaseAnimation, createMotionComponent, cubicBezier, ensureWorkletEasing, resolveAnimatableValue, resolveNamedTransition, resolveTransition, useAnimation, useBooleanSpring, useColorTransition, useMotionConfig, useMotionValue, useNamedTransitions, usePresence, useScroll, useShadow, useShouldReduceMotion, useSpring, useTransform, useVariants };

package/dist/index.d.ts

@@ -555,11 +555,42 @@ interface UseScrollResult {
  */
 declare function useScroll(): UseScrollResult;
 
+/**
+ * CSS `box-shadow` parsing + pairing for `useShadow`.
+ *
+ * Design systems store web elevation tokens as CSS `box-shadow` strings
+ * (`'0px 1px 2px rgba(0,0,0,0.3), 0px 1px 3px 1px rgba(0,0,0,0.15)'`).
+ * Like `cubicBezier`, this module makes those tokens directly consumable:
+ * strings are parsed once on the JS thread into flat layer records the
+ * `useShadow` worklet can interpolate without any frame-time string work.
+ *
+ * Invalid input **throws** rather than warning — shadow tokens are
+ * constructed at theme/module setup, and a malformed token should fail
+ * loudly there, not silently render the wrong elevation.
+ */
+/**
+ * One layer of a `box-shadow`, structurally mirroring React Native's
+ * `BoxShadowValue` (RN 0.76+ `boxShadow` style). Lengths are px numbers.
+ */
+interface BoxShadowLayer {
+    offsetX: number;
+    offsetY: number;
+    /** Must be >= 0, per CSS. @default 0 */
+    blurRadius?: number;
+    /** @default 0 */
+    spreadDistance?: number;
+    /** Any color string Reanimated's `interpolateColor` accepts. @default 'black' */
+    color?: string;
+    /** @default false */
+    inset?: boolean;
+}
+
 /**
  * Shape accepted on either end of a `useShadow` tween. Every field is
  * optional — only keys present on at least one side participate in the
  * output style. Mirrors the flat shadow keys on `Motion.View`'s `animate`
- * surface, plus the nested `shadowOffset` source.
+ * surface, plus the nested `shadowOffset` source and the CSS `boxShadow`
+ * surface.
  */
 interface ShadowConfig {
     shadowOpacity?: number;
@@ -571,6 +602,19 @@ interface ShadowConfig {
     /** Android elevation. iOS shadow consumers can leave this off. */
     elevation?: number;
     shadowColor?: string;
+    /**
+     * CSS `box-shadow` — the shadow surface on web (react-native-web passes
+     * it through as CSS) and on React Native 0.76+ new-architecture native.
+     * Accepts the CSS string form design systems store elevation tokens in
+     * (`'0px 1px 2px rgba(0,0,0,0.3), 0px 1px 3px 1px rgba(0,0,0,0.15)'`;
+     * px lengths only) or structured layers. Multi-layer shadows interpolate
+     * per layer; when one side has fewer layers, it is padded with invisible
+     * layers, CSS-transition style. A malformed string **throws** at render
+     * (like `cubicBezier` — token mistakes should fail loudly at setup).
+     * The classic `shadow*`/`elevation` keys don't reach the web renderer —
+     * provide `boxShadow` alongside them when the tween must show up there.
+     */
+    boxShadow?: string | readonly BoxShadowLayer[];
 }
 interface UseShadowOptions {
     /** Shadow state at `progress === 0`. */
@@ -607,6 +651,19 @@ interface UseShadowOptions {
  * `shadowColor`, `{ width: 0, height: 0 }` for `shadowOffset`). This is a
  * pure interpolator — to "animate" the shadow, drive `progress` with a
  * spring, timing, or gesture upstream.
+ *
+ * The classic `shadow*`/`elevation` keys don't render on web. When the
+ * tween must show up there (or on RN 0.76+ new-arch native via the CSS
+ * shadow model), provide `boxShadow` on both ends — CSS string tokens or
+ * structured layers; multi-layer shadows interpolate per layer:
+ *
+ * ```tsx
+ * const shadowStyle = useShadow({
+ *   from: { boxShadow: theme.elevation.level1 }, // '0px 1px 2px rgba(0,0,0,0.3), 0px 1px 3px 1px rgba(0,0,0,0.15)'
+ *   to:   { boxShadow: theme.elevation.level2 },
+ *   progress,
+ * })
+ * ```
  */
 declare function useShadow({ from, to, progress, }: UseShadowOptions): ReturnType<typeof useAnimatedStyle>;
 
@@ -623,4 +680,4 @@ declare function useShadow({ from, to, progress, }: UseShadowOptions): ReturnTyp
  */
 declare function useVariants<V extends Readonly<Record<string, object>>>(variants: V, initial?: keyof V & string): VariantController<keyof V & string>;
 
-export { AnimatableValue, type ColorStyleKey, EasingInput, type ExtrapolationMode, Motion, MotionComponent, MotionConfig, type MotionConfigProps, type MotionConfigValue, NamedTransitions, Presence, type PresenceContextValue, type ReducedMotion, type ShadowConfig, SpringTransition, TransitionConfig, TransitionInput, TransitionName, type UseColorTransitionOptions, type UseScrollResult, type UseShadowOptions, type UseTransformOptions, VariantController, buildReleaseAnimation, createMotionComponent, cubicBezier, ensureWorkletEasing, resolveAnimatableValue, resolveNamedTransition, resolveTransition, useAnimation, useBooleanSpring, useColorTransition, useMotionConfig, useMotionValue, useNamedTransitions, usePresence, useScroll, useShadow, useShouldReduceMotion, useSpring, useTransform, useVariants };
+export { AnimatableValue, type BoxShadowLayer, type ColorStyleKey, EasingInput, type ExtrapolationMode, Motion, MotionComponent, MotionConfig, type MotionConfigProps, type MotionConfigValue, NamedTransitions, Presence, type PresenceContextValue, type ReducedMotion, type ShadowConfig, SpringTransition, TransitionConfig, TransitionInput, TransitionName, type UseColorTransitionOptions, type UseScrollResult, type UseShadowOptions, type UseTransformOptions, VariantController, buildReleaseAnimation, createMotionComponent, cubicBezier, ensureWorkletEasing, resolveAnimatableValue, resolveNamedTransition, resolveTransition, useAnimation, useBooleanSpring, useColorTransition, useMotionConfig, useMotionValue, useNamedTransitions, usePresence, useScroll, useShadow, useShouldReduceMotion, useSpring, useTransform, useVariants };

package/dist/index.js

@@ -166,6 +166,127 @@ function useScroll() {
     onScroll: handler
   };
 }
+
+// src/internal/boxShadow.ts
+var LENGTH = /^[+-]?(\d+\.?\d*|\.\d+)(px)?$/i;
+var UNIT_LIKE = /^[+-]?(\d+\.?\d*|\.\d+)[a-z%]+$/i;
+function invalid(input, reason) {
+  return new Error(
+    `[inertia] parseBoxShadow: ${reason} in ${JSON.stringify(input)}. Expected CSS box-shadow syntax with px lengths: '[inset] <offset-x> <offset-y> [blur] [spread] [color], ...'`
+  );
+}
+function splitLayers(input) {
+  const layers = [];
+  let depth = 0;
+  let start = 0;
+  for (let i = 0; i < input.length; i++) {
+    const ch = input[i];
+    if (ch === "(") depth++;
+    else if (ch === ")") depth--;
+    else if (ch === "," && depth === 0) {
+      layers.push(input.slice(start, i));
+      start = i + 1;
+    }
+  }
+  layers.push(input.slice(start));
+  return layers;
+}
+function tokenize(layer) {
+  const tokens = [];
+  let depth = 0;
+  let current = "";
+  for (const ch of layer) {
+    if (ch === "(") depth++;
+    else if (ch === ")") depth--;
+    if (depth === 0 && /\s/.test(ch)) {
+      if (current) tokens.push(current);
+      current = "";
+    } else {
+      current += ch;
+    }
+  }
+  if (current) tokens.push(current);
+  return tokens;
+}
+function parseBoxShadow(input) {
+  const trimmed = input.trim();
+  if (trimmed === "") throw invalid(input, "empty string");
+  if (trimmed.toLowerCase() === "none") return [];
+  return splitLayers(trimmed).map((layerString) => {
+    const tokens = tokenize(layerString.trim());
+    if (tokens.length === 0) throw invalid(input, "empty layer");
+    const lengths = [];
+    let color;
+    let inset = false;
+    for (const token of tokens) {
+      if (token.toLowerCase() === "inset") {
+        if (inset) throw invalid(input, "duplicate 'inset'");
+        inset = true;
+      } else if (LENGTH.test(token)) {
+        lengths.push(parseFloat(token));
+      } else if (UNIT_LIKE.test(token)) {
+        throw invalid(input, `unsupported unit in ${JSON.stringify(token)}`);
+      } else {
+        if (color !== void 0) throw invalid(input, "multiple colors");
+        color = token;
+      }
+    }
+    if (lengths.length < 2 || lengths.length > 4) {
+      throw invalid(input, `expected 2-4 lengths, got ${lengths.length}`);
+    }
+    const [offsetX = 0, offsetY = 0, blurRadius = 0, spreadDistance = 0] = lengths;
+    if (blurRadius < 0) throw invalid(input, "negative blur radius");
+    return {
+      offsetX,
+      offsetY,
+      blurRadius,
+      spreadDistance,
+      color: color ?? "black",
+      inset
+    };
+  });
+}
+function resolveBoxShadowInput(input) {
+  if (input === void 0) return [];
+  if (typeof input === "string") return parseBoxShadow(input);
+  return input.map((layer) => ({
+    offsetX: layer.offsetX,
+    offsetY: layer.offsetY,
+    blurRadius: layer.blurRadius ?? 0,
+    spreadDistance: layer.spreadDistance ?? 0,
+    color: layer.color ?? "black",
+    inset: layer.inset ?? false
+  }));
+}
+function pairBoxShadowLayers(from, to) {
+  const count = Math.max(from.length, to.length);
+  const pairs = [];
+  for (let i = 0; i < count; i++) {
+    const a = from[i];
+    const b = to[i];
+    const fromLayer = a ?? invisibleLayer(b.inset);
+    const toLayer = b ?? invisibleLayer(a.inset);
+    if (fromLayer.inset !== toLayer.inset) {
+      throw new Error(
+        `[inertia] useShadow: boxShadow layer ${i} is 'inset' on one side but not the other \u2014 inset cannot be interpolated. Give both sides the same inset-ness (pad with a transparent layer if needed).`
+      );
+    }
+    pairs.push({ from: fromLayer, to: toLayer });
+  }
+  return pairs;
+}
+function invisibleLayer(inset) {
+  return {
+    offsetX: 0,
+    offsetY: 0,
+    blurRadius: 0,
+    spreadDistance: 0,
+    color: "transparent",
+    inset
+  };
+}
+
+// src/values/useShadow.ts
 function useShadow({
   from,
   to,
@@ -176,6 +297,10 @@ function useShadow({
   const hasElevation = from.elevation !== void 0 || to.elevation !== void 0;
   const hasColor = from.shadowColor !== void 0 || to.shadowColor !== void 0;
   const hasOffset = from.shadowOffset !== void 0 || to.shadowOffset !== void 0;
+  const boxShadowPairs = from.boxShadow !== void 0 || to.boxShadow !== void 0 ? pairBoxShadowLayers(
+    resolveBoxShadowInput(from.boxShadow),
+    resolveBoxShadowInput(to.boxShadow)
+  ) : [];
   const opacityFrom = from.shadowOpacity ?? 0;
   const opacityTo = to.shadowOpacity ?? 0;
   const radiusFrom = from.shadowRadius ?? 0;
@@ -210,6 +335,31 @@ function useShadow({
         height: reactNativeReanimated.interpolate(t, [0, 1], [offsetHFrom, offsetHTo])
       };
     }
+    if (boxShadowPairs.length > 0) {
+      let css = "";
+      let first = true;
+      for (const pair of boxShadowPairs) {
+        const x = reactNativeReanimated.interpolate(t, [0, 1], [pair.from.offsetX, pair.to.offsetX]);
+        const y = reactNativeReanimated.interpolate(t, [0, 1], [pair.from.offsetY, pair.to.offsetY]);
+        const blur = Math.max(
+          0,
+          reactNativeReanimated.interpolate(t, [0, 1], [pair.from.blurRadius, pair.to.blurRadius])
+        );
+        const spread = reactNativeReanimated.interpolate(
+          t,
+          [0, 1],
+          [pair.from.spreadDistance, pair.to.spreadDistance]
+        );
+        const color = reactNativeReanimated.interpolateColor(
+          t,
+          [0, 1],
+          [pair.from.color, pair.to.color]
+        );
+        css += (first ? "" : ", ") + (pair.from.inset ? "inset " : "") + `${x}px ${y}px ${blur}px ${spread}px ${color}`;
+        first = false;
+      }
+      out.boxShadow = css;
+    }
     return out;
   });
 }

package/dist/index.mjs

@@ -171,6 +171,127 @@ function useScroll() {
     onScroll: handler
   };
 }
+
+// src/internal/boxShadow.ts
+var LENGTH = /^[+-]?(\d+\.?\d*|\.\d+)(px)?$/i;
+var UNIT_LIKE = /^[+-]?(\d+\.?\d*|\.\d+)[a-z%]+$/i;
+function invalid(input, reason) {
+  return new Error(
+    `[inertia] parseBoxShadow: ${reason} in ${JSON.stringify(input)}. Expected CSS box-shadow syntax with px lengths: '[inset] <offset-x> <offset-y> [blur] [spread] [color], ...'`
+  );
+}
+function splitLayers(input) {
+  const layers = [];
+  let depth = 0;
+  let start = 0;
+  for (let i = 0; i < input.length; i++) {
+    const ch = input[i];
+    if (ch === "(") depth++;
+    else if (ch === ")") depth--;
+    else if (ch === "," && depth === 0) {
+      layers.push(input.slice(start, i));
+      start = i + 1;
+    }
+  }
+  layers.push(input.slice(start));
+  return layers;
+}
+function tokenize(layer) {
+  const tokens = [];
+  let depth = 0;
+  let current = "";
+  for (const ch of layer) {
+    if (ch === "(") depth++;
+    else if (ch === ")") depth--;
+    if (depth === 0 && /\s/.test(ch)) {
+      if (current) tokens.push(current);
+      current = "";
+    } else {
+      current += ch;
+    }
+  }
+  if (current) tokens.push(current);
+  return tokens;
+}
+function parseBoxShadow(input) {
+  const trimmed = input.trim();
+  if (trimmed === "") throw invalid(input, "empty string");
+  if (trimmed.toLowerCase() === "none") return [];
+  return splitLayers(trimmed).map((layerString) => {
+    const tokens = tokenize(layerString.trim());
+    if (tokens.length === 0) throw invalid(input, "empty layer");
+    const lengths = [];
+    let color;
+    let inset = false;
+    for (const token of tokens) {
+      if (token.toLowerCase() === "inset") {
+        if (inset) throw invalid(input, "duplicate 'inset'");
+        inset = true;
+      } else if (LENGTH.test(token)) {
+        lengths.push(parseFloat(token));
+      } else if (UNIT_LIKE.test(token)) {
+        throw invalid(input, `unsupported unit in ${JSON.stringify(token)}`);
+      } else {
+        if (color !== void 0) throw invalid(input, "multiple colors");
+        color = token;
+      }
+    }
+    if (lengths.length < 2 || lengths.length > 4) {
+      throw invalid(input, `expected 2-4 lengths, got ${lengths.length}`);
+    }
+    const [offsetX = 0, offsetY = 0, blurRadius = 0, spreadDistance = 0] = lengths;
+    if (blurRadius < 0) throw invalid(input, "negative blur radius");
+    return {
+      offsetX,
+      offsetY,
+      blurRadius,
+      spreadDistance,
+      color: color ?? "black",
+      inset
+    };
+  });
+}
+function resolveBoxShadowInput(input) {
+  if (input === void 0) return [];
+  if (typeof input === "string") return parseBoxShadow(input);
+  return input.map((layer) => ({
+    offsetX: layer.offsetX,
+    offsetY: layer.offsetY,
+    blurRadius: layer.blurRadius ?? 0,
+    spreadDistance: layer.spreadDistance ?? 0,
+    color: layer.color ?? "black",
+    inset: layer.inset ?? false
+  }));
+}
+function pairBoxShadowLayers(from, to) {
+  const count = Math.max(from.length, to.length);
+  const pairs = [];
+  for (let i = 0; i < count; i++) {
+    const a = from[i];
+    const b = to[i];
+    const fromLayer = a ?? invisibleLayer(b.inset);
+    const toLayer = b ?? invisibleLayer(a.inset);
+    if (fromLayer.inset !== toLayer.inset) {
+      throw new Error(
+        `[inertia] useShadow: boxShadow layer ${i} is 'inset' on one side but not the other \u2014 inset cannot be interpolated. Give both sides the same inset-ness (pad with a transparent layer if needed).`
+      );
+    }
+    pairs.push({ from: fromLayer, to: toLayer });
+  }
+  return pairs;
+}
+function invisibleLayer(inset) {
+  return {
+    offsetX: 0,
+    offsetY: 0,
+    blurRadius: 0,
+    spreadDistance: 0,
+    color: "transparent",
+    inset
+  };
+}
+
+// src/values/useShadow.ts
 function useShadow({
   from,
   to,
@@ -181,6 +302,10 @@ function useShadow({
   const hasElevation = from.elevation !== void 0 || to.elevation !== void 0;
   const hasColor = from.shadowColor !== void 0 || to.shadowColor !== void 0;
   const hasOffset = from.shadowOffset !== void 0 || to.shadowOffset !== void 0;
+  const boxShadowPairs = from.boxShadow !== void 0 || to.boxShadow !== void 0 ? pairBoxShadowLayers(
+    resolveBoxShadowInput(from.boxShadow),
+    resolveBoxShadowInput(to.boxShadow)
+  ) : [];
   const opacityFrom = from.shadowOpacity ?? 0;
   const opacityTo = to.shadowOpacity ?? 0;
   const radiusFrom = from.shadowRadius ?? 0;
@@ -215,6 +340,31 @@ function useShadow({
         height: interpolate(t, [0, 1], [offsetHFrom, offsetHTo])
       };
     }
+    if (boxShadowPairs.length > 0) {
+      let css = "";
+      let first = true;
+      for (const pair of boxShadowPairs) {
+        const x = interpolate(t, [0, 1], [pair.from.offsetX, pair.to.offsetX]);
+        const y = interpolate(t, [0, 1], [pair.from.offsetY, pair.to.offsetY]);
+        const blur = Math.max(
+          0,
+          interpolate(t, [0, 1], [pair.from.blurRadius, pair.to.blurRadius])
+        );
+        const spread = interpolate(
+          t,
+          [0, 1],
+          [pair.from.spreadDistance, pair.to.spreadDistance]
+        );
+        const color = interpolateColor(
+          t,
+          [0, 1],
+          [pair.from.color, pair.to.color]
+        );
+        css += (first ? "" : ", ") + (pair.from.inset ? "inset " : "") + `${x}px ${y}px ${blur}px ${spread}px ${color}`;
+        first = false;
+      }
+      out.boxShadow = css;
+    }
     return out;
   });
 }

package/llms.txt

@@ -51,7 +51,7 @@ import { MotionScrollView } from '@rootnative/inertia/scroll-view'
 - `useSpring(target, config?)` — spring-only shorthand. Animates a `SharedValue<number>` toward `target` with react-spring vocab (or a spring-typed registered `TransitionName`; non-spring names warn and fall back to the default spring). `target` may be a plain number (effect-driven) or a `SharedValue<number>` (UI-thread reaction); the latter is the gesture-smoothing path.
 - `useBooleanSpring(active, config?)` — sugar over `useSpring` for the recurring "spring 0↔1 progress from a boolean" shape (checkbox checks, accordion expansions, drawer open/closed). Identical mechanics to `useSpring(active ? 1 : 0, config)` — the named form so the call site reads as the boolean it represents.
 - `useTransform(value, inputRange, outputRange, options?)` / `useTransform(transformer)` — interpolate a numeric shared value onto a number or color range, or derive any value from any number of shared values via a worklet. Non-worklet transformers are auto-wrapped.
-- `useShadow({ from, to, progress })` — pure value-layer interpolator between two `ShadowConfig`s (`shadowOpacity` / `shadowRadius` / `shadowOffset` / `elevation` / `shadowColor`) driven by a `SharedValue<number>` (0→1). Returns an animated style fragment to spread onto `style`; only emits keys present on either side, absent sides default to natural zero. The hook does not animate on its own — drive `progress` with a spring, a scroll-derived `useTransform`, or any other shared value source.
+- `useShadow({ from, to, progress })` — pure value-layer interpolator between two `ShadowConfig`s (`shadowOpacity` / `shadowRadius` / `shadowOffset` / `elevation` / `shadowColor`, plus `boxShadow` as a CSS string or `BoxShadowLayer[]` — the shadow surface on web and RN 0.76+ new-arch; multi-layer, CSS-transition padding semantics, malformed strings throw at setup) driven by a `SharedValue<number>` (0→1). Returns an animated style fragment to spread onto `style`; only emits keys present on either side, absent sides default to natural zero. The hook does not animate on its own — drive `progress` with a spring, a scroll-derived `useTransform`, or any other shared value source.
 - `useColorTransition(progress, [from, to], options?)` — pure value-layer interpolator for a single color channel, driven by a `SharedValue<number>` (0→1). Returns an animated style fragment with one color key (default `backgroundColor`; configurable via `options.key` to `color` / `borderColor` / `tintColor` / `shadowColor` / per-side border colors). For raw `SharedValue<string>` output, use `useTransform(progress, [0, 1], [from, to])` instead.
 - `useScroll()` — returns `{ scrollX, scrollY, onScroll }` for use with `Motion.ScrollView`. Scroll events fire on the UI thread.
 - `createMotionComponent<C>(C)` — wrap any component with the same Motion prop surface, inferring style from `C`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rootnative/inertia",
-  "version": "0.0.0-alpha.5",
+  "version": "0.0.0-alpha.6",
   "description": "Declarative animation primitives for React Native, built on react-native-reanimated.",
   "license": "MIT",
   "author": "RootNative",

package/src/index.ts

@@ -52,6 +52,7 @@ export {
   useVariants,
 } from './values'
 export type {
+  BoxShadowLayer,
   ColorStyleKey,
   ExtrapolationMode,
   ShadowConfig,

package/src/internal/boxShadow.ts

@@ -0,0 +1,204 @@
+/**
+ * CSS `box-shadow` parsing + pairing for `useShadow`.
+ *
+ * Design systems store web elevation tokens as CSS `box-shadow` strings
+ * (`'0px 1px 2px rgba(0,0,0,0.3), 0px 1px 3px 1px rgba(0,0,0,0.15)'`).
+ * Like `cubicBezier`, this module makes those tokens directly consumable:
+ * strings are parsed once on the JS thread into flat layer records the
+ * `useShadow` worklet can interpolate without any frame-time string work.
+ *
+ * Invalid input **throws** rather than warning — shadow tokens are
+ * constructed at theme/module setup, and a malformed token should fail
+ * loudly there, not silently render the wrong elevation.
+ */
+
+/**
+ * One layer of a `box-shadow`, structurally mirroring React Native's
+ * `BoxShadowValue` (RN 0.76+ `boxShadow` style). Lengths are px numbers.
+ */
+export interface BoxShadowLayer {
+  offsetX: number
+  offsetY: number
+  /** Must be >= 0, per CSS. @default 0 */
+  blurRadius?: number
+  /** @default 0 */
+  spreadDistance?: number
+  /** Any color string Reanimated's `interpolateColor` accepts. @default 'black' */
+  color?: string
+  /** @default false */
+  inset?: boolean
+}
+
+/** A layer with every field resolved to a concrete value. */
+export interface ResolvedBoxShadowLayer {
+  offsetX: number
+  offsetY: number
+  blurRadius: number
+  spreadDistance: number
+  color: string
+  inset: boolean
+}
+
+const LENGTH = /^[+-]?(\d+\.?\d*|\.\d+)(px)?$/i
+const UNIT_LIKE = /^[+-]?(\d+\.?\d*|\.\d+)[a-z%]+$/i
+
+function invalid(input: string, reason: string): Error {
+  return new Error(
+    `[inertia] parseBoxShadow: ${reason} in ${JSON.stringify(input)}. ` +
+      'Expected CSS box-shadow syntax with px lengths: ' +
+      "'[inset] <offset-x> <offset-y> [blur] [spread] [color], ...'",
+  )
+}
+
+/**
+ * Split a box-shadow string into layer strings on top-level commas —
+ * commas inside color functions (`rgba(0, 0, 0, 0.3)`) don't split.
+ */
+function splitLayers(input: string): string[] {
+  const layers: string[] = []
+  let depth = 0
+  let start = 0
+  for (let i = 0; i < input.length; i++) {
+    const ch = input[i]
+    if (ch === '(') depth++
+    else if (ch === ')') depth--
+    else if (ch === ',' && depth === 0) {
+      layers.push(input.slice(start, i))
+      start = i + 1
+    }
+  }
+  layers.push(input.slice(start))
+  return layers
+}
+
+/**
+ * Split one layer into whitespace-separated tokens, keeping color
+ * functions (which may contain spaces: `rgb(0 0 0 / 40%)`) as one token.
+ */
+function tokenize(layer: string): string[] {
+  const tokens: string[] = []
+  let depth = 0
+  let current = ''
+  for (const ch of layer) {
+    if (ch === '(') depth++
+    else if (ch === ')') depth--
+    if (depth === 0 && /\s/.test(ch)) {
+      if (current) tokens.push(current)
+      current = ''
+    } else {
+      current += ch
+    }
+  }
+  if (current) tokens.push(current)
+  return tokens
+}
+
+/**
+ * Parse a CSS `box-shadow` string into resolved layers. `'none'` parses to
+ * an empty list. Only px (and unitless) lengths are supported — other units
+ * depend on font/viewport context that a style value can't resolve.
+ */
+export function parseBoxShadow(input: string): ResolvedBoxShadowLayer[] {
+  const trimmed = input.trim()
+  if (trimmed === '') throw invalid(input, 'empty string')
+  if (trimmed.toLowerCase() === 'none') return []
+
+  return splitLayers(trimmed).map((layerString) => {
+    const tokens = tokenize(layerString.trim())
+    if (tokens.length === 0) throw invalid(input, 'empty layer')
+
+    const lengths: number[] = []
+    let color: string | undefined
+    let inset = false
+    for (const token of tokens) {
+      if (token.toLowerCase() === 'inset') {
+        if (inset) throw invalid(input, "duplicate 'inset'")
+        inset = true
+      } else if (LENGTH.test(token)) {
+        lengths.push(parseFloat(token))
+      } else if (UNIT_LIKE.test(token)) {
+        throw invalid(input, `unsupported unit in ${JSON.stringify(token)}`)
+      } else {
+        if (color !== undefined) throw invalid(input, 'multiple colors')
+        color = token
+      }
+    }
+
+    if (lengths.length < 2 || lengths.length > 4) {
+      throw invalid(input, `expected 2-4 lengths, got ${lengths.length}`)
+    }
+    // The `= 0` on the offsets never fires (length >= 2 is validated
+    // above); it's here for noUncheckedIndexedAccess.
+    const [offsetX = 0, offsetY = 0, blurRadius = 0, spreadDistance = 0] =
+      lengths
+    if (blurRadius < 0) throw invalid(input, 'negative blur radius')
+
+    return {
+      offsetX,
+      offsetY,
+      blurRadius,
+      spreadDistance,
+      color: color ?? 'black',
+      inset,
+    }
+  })
+}
+
+/** Resolve either input form (CSS string or structured layers) to layers. */
+export function resolveBoxShadowInput(
+  input: string | readonly BoxShadowLayer[] | undefined,
+): ResolvedBoxShadowLayer[] {
+  if (input === undefined) return []
+  if (typeof input === 'string') return parseBoxShadow(input)
+  return input.map((layer) => ({
+    offsetX: layer.offsetX,
+    offsetY: layer.offsetY,
+    blurRadius: layer.blurRadius ?? 0,
+    spreadDistance: layer.spreadDistance ?? 0,
+    color: layer.color ?? 'black',
+    inset: layer.inset ?? false,
+  }))
+}
+
+/**
+ * Pair up `from`/`to` layer lists for interpolation, CSS-transition style:
+ * the shorter list is padded with an invisible layer (all lengths 0,
+ * transparent color) matching the counterpart's `inset` flag. A genuine
+ * `inset` mismatch between paired layers is not interpolable and throws.
+ */
+export function pairBoxShadowLayers(
+  from: ResolvedBoxShadowLayer[],
+  to: ResolvedBoxShadowLayer[],
+): Array<{ from: ResolvedBoxShadowLayer; to: ResolvedBoxShadowLayer }> {
+  const count = Math.max(from.length, to.length)
+  const pairs: Array<{
+    from: ResolvedBoxShadowLayer
+    to: ResolvedBoxShadowLayer
+  }> = []
+  for (let i = 0; i < count; i++) {
+    const a = from[i]
+    const b = to[i]
+    const fromLayer = a ?? invisibleLayer(b!.inset)
+    const toLayer = b ?? invisibleLayer(a!.inset)
+    if (fromLayer.inset !== toLayer.inset) {
+      throw new Error(
+        `[inertia] useShadow: boxShadow layer ${i} is 'inset' on one side ` +
+          'but not the other — inset cannot be interpolated. Give both ' +
+          'sides the same inset-ness (pad with a transparent layer if needed).',
+      )
+    }
+    pairs.push({ from: fromLayer, to: toLayer })
+  }
+  return pairs
+}
+
+function invisibleLayer(inset: boolean): ResolvedBoxShadowLayer {
+  return {
+    offsetX: 0,
+    offsetY: 0,
+    blurRadius: 0,
+    spreadDistance: 0,
+    color: 'transparent',
+    inset,
+  }
+}

package/src/values/index.ts

@@ -20,6 +20,7 @@ export {
 export { useScroll, type UseScrollResult } from './useScroll'
 export {
   useShadow,
+  type BoxShadowLayer,
   type ShadowConfig,
   type UseShadowOptions,
 } from './useShadow'

package/src/values/useShadow.ts

@@ -4,12 +4,20 @@ import {
   useAnimatedStyle,
   type SharedValue,
 } from 'react-native-reanimated'
+import {
+  pairBoxShadowLayers,
+  resolveBoxShadowInput,
+  type BoxShadowLayer,
+} from '../internal/boxShadow'
+
+export type { BoxShadowLayer }
 
 /**
  * Shape accepted on either end of a `useShadow` tween. Every field is
  * optional — only keys present on at least one side participate in the
  * output style. Mirrors the flat shadow keys on `Motion.View`'s `animate`
- * surface, plus the nested `shadowOffset` source.
+ * surface, plus the nested `shadowOffset` source and the CSS `boxShadow`
+ * surface.
  */
 export interface ShadowConfig {
   shadowOpacity?: number
@@ -18,6 +26,19 @@ export interface ShadowConfig {
   /** Android elevation. iOS shadow consumers can leave this off. */
   elevation?: number
   shadowColor?: string
+  /**
+   * CSS `box-shadow` — the shadow surface on web (react-native-web passes
+   * it through as CSS) and on React Native 0.76+ new-architecture native.
+   * Accepts the CSS string form design systems store elevation tokens in
+   * (`'0px 1px 2px rgba(0,0,0,0.3), 0px 1px 3px 1px rgba(0,0,0,0.15)'`;
+   * px lengths only) or structured layers. Multi-layer shadows interpolate
+   * per layer; when one side has fewer layers, it is padded with invisible
+   * layers, CSS-transition style. A malformed string **throws** at render
+   * (like `cubicBezier` — token mistakes should fail loudly at setup).
+   * The classic `shadow*`/`elevation` keys don't reach the web renderer —
+   * provide `boxShadow` alongside them when the tween must show up there.
+   */
+  boxShadow?: string | readonly BoxShadowLayer[]
 }
 
 export interface UseShadowOptions {
@@ -56,6 +77,19 @@ export interface UseShadowOptions {
  * `shadowColor`, `{ width: 0, height: 0 }` for `shadowOffset`). This is a
  * pure interpolator — to "animate" the shadow, drive `progress` with a
  * spring, timing, or gesture upstream.
+ *
+ * The classic `shadow*`/`elevation` keys don't render on web. When the
+ * tween must show up there (or on RN 0.76+ new-arch native via the CSS
+ * shadow model), provide `boxShadow` on both ends — CSS string tokens or
+ * structured layers; multi-layer shadows interpolate per layer:
+ *
+ * ```tsx
+ * const shadowStyle = useShadow({
+ *   from: { boxShadow: theme.elevation.level1 }, // '0px 1px 2px rgba(0,0,0,0.3), 0px 1px 3px 1px rgba(0,0,0,0.15)'
+ *   to:   { boxShadow: theme.elevation.level2 },
+ *   progress,
+ * })
+ * ```
  */
 export function useShadow({
   from,
@@ -76,6 +110,17 @@ export function useShadow({
   const hasOffset =
     from.shadowOffset !== undefined || to.shadowOffset !== undefined
 
+  // boxShadow layers: parse/pair once on the JS thread into flat records so
+  // the worklet only interpolates numbers/colors and concatenates — no
+  // frame-time parsing. `[]` when neither side provides the key.
+  const boxShadowPairs =
+    from.boxShadow !== undefined || to.boxShadow !== undefined
+      ? pairBoxShadowLayers(
+          resolveBoxShadowInput(from.boxShadow),
+          resolveBoxShadowInput(to.boxShadow),
+        )
+      : []
+
   const opacityFrom = from.shadowOpacity ?? 0
   const opacityTo = to.shadowOpacity ?? 0
   const radiusFrom = from.shadowRadius ?? 0
@@ -111,6 +156,36 @@ export function useShadow({
         height: interpolate(t, [0, 1], [offsetHFrom, offsetHTo]),
       }
     }
+    if (boxShadowPairs.length > 0) {
+      let css = ''
+      let first = true
+      for (const pair of boxShadowPairs) {
+        const x = interpolate(t, [0, 1], [pair.from.offsetX, pair.to.offsetX])
+        const y = interpolate(t, [0, 1], [pair.from.offsetY, pair.to.offsetY])
+        // Blur can't go negative (invalid CSS) even if a springy driver
+        // overshoots below 0.
+        const blur = Math.max(
+          0,
+          interpolate(t, [0, 1], [pair.from.blurRadius, pair.to.blurRadius]),
+        )
+        const spread = interpolate(
+          t,
+          [0, 1],
+          [pair.from.spreadDistance, pair.to.spreadDistance],
+        )
+        const color = interpolateColor(
+          t,
+          [0, 1],
+          [pair.from.color, pair.to.color],
+        )
+        css +=
+          (first ? '' : ', ') +
+          (pair.from.inset ? 'inset ' : '') +
+          `${x}px ${y}px ${blur}px ${spread}px ${color}`
+        first = false
+      }
+      out.boxShadow = css
+    }
     return out
   })
 }