pixelize-native-library 1.0.6 → 1.2.0

package/lib/module/core/media/MediaImage.js

@@ -0,0 +1,51 @@
+"use strict";
+
+import { memo } from 'react';
+import { Image as RNImage } from 'react-native';
+import { getExpoImage, hasExpoImage } from "./expoImage.js";
+import { jsx as _jsx } from "react/jsx-runtime";
+const RN_RESIZE_MODE = {
+  cover: 'cover',
+  contain: 'contain',
+  fill: 'stretch'
+};
+
+/**
+ * The library's single image element. Routes through `expo-image` when the app injected it
+ * (`setExpoImage`) — native downsampling to the target box, memory+disk cache, `recyclingKey` —
+ * and degrades to RN's `Image` when it did not.
+ *
+ * `expo-image` is an OPTIONAL peer dependency: reading it through `getExpoImage()` alone crashes
+ * on first render for any app that never wired it up, which is why the branch exists.
+ */
+export const MediaImage = /*#__PURE__*/memo(function MediaImage({
+  source,
+  contentFit,
+  recyclingKey,
+  transition,
+  style,
+  accessibilityLabel,
+  testID
+}) {
+  if (!hasExpoImage()) {
+    return /*#__PURE__*/_jsx(RNImage, {
+      testID: testID,
+      source: source,
+      resizeMode: RN_RESIZE_MODE[contentFit],
+      accessibilityLabel: accessibilityLabel,
+      style: style
+    });
+  }
+  const ExpoImage = getExpoImage();
+  return /*#__PURE__*/_jsx(ExpoImage, {
+    testID: testID,
+    source: source,
+    contentFit: contentFit,
+    cachePolicy: "memory-disk",
+    transition: transition,
+    recyclingKey: recyclingKey,
+    accessibilityLabel: accessibilityLabel,
+    style: style
+  });
+});
+//# sourceMappingURL=MediaImage.js.map

package/lib/module/core/media/expoImage.js

@@ -0,0 +1,20 @@
+"use strict";
+
+let imageComponent = null;
+
+/** Injects expo-image at runtime — never imports the package at module scope. */
+export function setExpoImage(Image) {
+  imageComponent = Image;
+}
+
+/** Throws when unset — components render images through `MediaImage`, which degrades instead. */
+export function getExpoImage() {
+  if (!imageComponent) {
+    throw new Error('expo-image is not configured. Call setExpoImage(Image) from expo-image at app startup, ' + 'or install expo-image as a peer dependency.');
+  }
+  return imageComponent;
+}
+export function hasExpoImage() {
+  return imageComponent !== null;
+}
+//# sourceMappingURL=expoImage.js.map

package/lib/module/core/media/index.js

@@ -0,0 +1,6 @@
+"use strict";
+
+export { setExpoImage, getExpoImage, hasExpoImage } from "./expoImage.js";
+export { MediaImage } from "./MediaImage.js";
+export { setDocumentPicker, setImagePicker, getDocumentPicker, getImagePicker } from "./pickers.js";
+//# sourceMappingURL=index.js.map

package/lib/module/core/media/pickers.js

@@ -0,0 +1,23 @@
+"use strict";
+
+let documentPicker = null;
+let imagePicker = null;
+export function setDocumentPicker(module) {
+  documentPicker = module;
+}
+export function setImagePicker(module) {
+  imagePicker = module;
+}
+export function getDocumentPicker() {
+  if (!documentPicker) {
+    throw new Error('expo-document-picker is not configured. Call setDocumentPicker from expo-document-picker at app startup.');
+  }
+  return documentPicker;
+}
+export function getImagePicker() {
+  if (!imagePicker) {
+    throw new Error('expo-image-picker is not configured. Call setImagePicker from expo-image-picker at app startup.');
+  }
+  return imagePicker;
+}
+//# sourceMappingURL=pickers.js.map

package/lib/module/core/motion/MODULE.md

@@ -0,0 +1,101 @@
+# core/motion
+
+The single global control for every animation in the library. **Internal only** — nothing here is
+exported from the package, so a consumer app cannot (and does not need to) configure motion. You
+tune the whole library by editing one file in this repo.
+
+## Tuning everything at once
+
+Edit **`config.ts`**. Nothing else.
+
+| Knob | Effect |
+|---|---|
+| `MOTION_ENABLED` | `false` kills every animation library-wide. Components render their final state instantly. |
+| `MOTION_SCALE` | Global speed dial. `0.5` = everything twice as fast, `2` = twice as slow. The fastest way to feel a change across all 72 components. |
+| `MOTION_DURATION` | The five named speeds. Components never write a raw number. |
+| `MOTION_EASING` | Four curves — `standard`, `decelerate` (entering), `accelerate` (leaving), `emphasized`. |
+| `MOTION_SPRING` | Three spring presets, used only where the device tier allows. |
+| `MOTION_TRANSFORM` | Shared magnitudes — press scale, slide offsets, scrim opacity. Keeps every component's motion the same size. |
+| `MOTION_TIER` | Per-device-tier policy: duration scale, whether springs and decorative motion are allowed. |
+
+Want a snappier library? Drop `MOTION_SCALE` to `0.8`. Want to check a layout without motion in the
+way? Set `MOTION_ENABLED = false`. Neither needs a component touched.
+
+## Using it in a component
+
+```ts
+const motion = useMotion();
+
+// A tween — already native-driver, already tier- and reduce-motion-resolved.
+motion.timing(opacity, 1, { duration: "fast", easing: "decelerate" }).start();
+
+// Snap instead of tween when the user asked for less motion.
+if (!motion.enabled) opacity.setValue(1);
+
+// Decorative motion (shimmer, parallax, stagger) is high-tier only.
+if (motion.decorative) startShimmer();
+```
+
+Allocate the value itself with **`useAnimatedValue(initial)`**, never
+`useRef(new Animated.Value(initial)).current` — the latter constructs a node on every render and
+hands `useRef` one it immediately discards. `initial` is read on the first render only, exactly like
+`useRef`, so the two are interchangeable.
+
+Three ready-made patterns cover most needs:
+
+- **`usePressMotion(disabled?)`** — scale + opacity dip on press. Spread `onPressIn`/`onPressOut`
+  onto the `Pressable` and `style` onto an `Animated.View`. The returned object is `useMemo`'d on the
+  stable `Animated.Value`s, so `press.style` keeps its identity and a consumer `useMemo` keyed on it
+  can hit. **`disabled` allocates nothing** — it returns one shared `{ opacity: 1, transform: [{
+  scale: 1 }] }`, so `list-item` / `stat-tile` rows that are display-only cost no `Animated.Value`
+  at all (5000 rows used to build 10,000 that never moved). `style.opacity` and `style.transform[0]
+  .scale` are therefore `Animated.Value | number`.
+- **`useEnterExit(visible, offsetY?)`** — fade + slide a subtree in, and unmount it once the exit
+  settles. Returns `{ mounted, style }`.
+- **`useReveal(visible, offsetY?)`** — the same fade + slide for a subtree whose mounting the caller
+  already controls. Returns `{ style }` only.
+
+**Pick between the last two by who owns the unmount.** `useReveal` holds no state, so it costs no
+extra render — but it also never removes anything from the tree. Ignoring `useEnterExit`'s `mounted`
+is the bug it exists to prevent: the caller pays a mount-state transition it never reads, and five
+modules were doing exactly that. Use `useReveal` when the subtree is already gated (`open ? … :
+null`, or an RN `<Modal>`); use `useEnterExit` only when you actually render its `mounted`.
+
+## The rules any new motion must follow
+
+1. **Animate only `opacity` and `transform`.** Never height, width, margin, padding or
+   `borderColor` — those cannot run on the native driver and force a layout pass every frame. This
+   constraint is the reason the library can animate freely without costing frames on low-end Android.
+2. **Always `useNativeDriver: true`.** One documented exception exists library-wide: `Drawer`'s
+   keyboard-avoidance `paddingBottom` (see `Drawer.tsx:115,122`, and its eslint override).
+3. **Never gate an unmount on the animation reporting `finished`.** An interrupted animation then
+   leaves the subtree mounted forever — collapsed content stays in the tree, screen readers still
+   read it, and heavy children never release. Drive the unmount from a timer, as `useEnterExit`
+   does.
+4. **Stop in-flight animations on effect cleanup and unmount**, or a stale callback sets state on an
+   unmounted component.
+5. **No per-row motion that runs during scroll.** `card`, `list-item`, table rows and grid cells
+   render per cell at 5000-row scale — their motion is press-triggered only, never a mount animation
+   and never a loop.
+6. **Reduce-motion (WCAG 2.3.3) always wins** over the device tier. `useMotion()` resolves this;
+   don't re-implement the check.
+
+## Tests
+
+`__tests__/` covers the gate itself: the duration/spring/decorative matrix across all three tiers ×
+reduce-motion, that `motionEasing` stays lazy and cached, and the preset hooks' snap-on-reduce-motion
+and cleanup paths. Two things a test in this folder cannot pin, so don't assume they are covered:
+`MOTION_SCALE` is `1`, so dropping the factor changes nothing observable (the concrete duration
+numbers in `config.test.ts` are what fails loudly when someone retunes it); and under Jest the
+native animated module is a stub, so `useNativeDriver: true` freezes an `Animated.Value` at its
+initial value — tests that need to watch a value move mock
+`react-native/src/private/animated/NativeAnimatedHelper` to force the JS driver.
+
+## Device tiers
+
+`useDeviceTier()` resolves `low | mid | high` (see `core/device/MODULE.md` for how); `MOTION_TIER`
+maps that to policy. Low-end runs shorter durations (a dropped frame is less visible), no springs,
+and no decorative motion. High-end gets the full treatment. Reduce-motion overrides all of it.
+
+`useMotion` calls `resolveDeviceTier(reducedMotion)`, not `useDeviceTier()` — the hook would read
+the reduce-motion store a second time for the same answer.

package/lib/module/core/motion/config.js

@@ -0,0 +1,112 @@
+"use strict";
+
+/**
+ * THE global motion control for the whole library. Tweak this file to retune every animated
+ * component at once — no component defines its own duration, easing or spring.
+ *
+ * Two hard perf rules every preset obeys, and any new one must too:
+ *   1. Animate ONLY `opacity` and `transform`. Never height/width/margin/padding — those cannot
+ *      run on the native driver and force a layout pass per frame.
+ *   2. Always `useNativeDriver: true`.
+ */
+
+import { Easing } from "react-native";
+/** Master switch. `false` makes every component render its final state with no animation. */
+export const MOTION_ENABLED = true;
+
+/** Global speed dial. 0.5 = twice as fast, 2 = twice as slow. Tune the whole library from here. */
+export const MOTION_SCALE = 1;
+export const MOTION_DURATION = {
+  instant: 0,
+  /** Press feedback, ripples, small state flips. */
+  fast: 150,
+  /** The default: expand/collapse, indicators, tab switches. */
+  normal: 280,
+  /** Sheets, drawers, full-width surfaces. */
+  slow: 360,
+  /** Onboarding and first-run emphasis only. */
+  deliberate: 500
+};
+
+/** Cubic-bezier control points. Kept as data so this module has no import-time RN dependency. */
+export const MOTION_EASING_CURVE = {
+  standard: [0.2, 0, 0, 1],
+  /** Entering the screen — fast start, soft landing. */
+  decelerate: [0, 0, 0, 1],
+  /** Leaving the screen — soft start, quick exit. */
+  accelerate: [0.3, 0, 1, 1],
+  emphasized: [0.2, 0, 0, 1.2]
+};
+let easingCache = {};
+
+/** Built on first use, never at module scope — pure tests that mock `react-native` have no `Easing`. */
+export function motionEasing(key) {
+  const cached = easingCache[key];
+  if (cached) return cached;
+  const [x1, y1, x2, y2] = MOTION_EASING_CURVE[key];
+  const built = Easing.bezier(x1, y1, x2, y2);
+  easingCache[key] = built;
+  return built;
+}
+
+/** Test-only: drops memoized easings so a suite can swap the `react-native` mock. */
+export function resetMotionEasingCache() {
+  easingCache = {};
+}
+export const MOTION_SPRING = {
+  gentle: {
+    damping: 20,
+    stiffness: 180,
+    mass: 1
+  },
+  snappy: {
+    damping: 26,
+    stiffness: 320,
+    mass: 1
+  },
+  bouncy: {
+    damping: 14,
+    stiffness: 260,
+    mass: 1
+  }
+};
+
+/** Shared magnitudes so every component's motion reads as one system. */
+export const MOTION_TRANSFORM = {
+  /** Press scale for buttons, cards, list rows. */
+  pressScale: 0.97,
+  pressOpacity: 0.92,
+  /** Vertical offset for content revealing in place. */
+  offsetY: 6,
+  /** Larger offset for sheets and toasts. */
+  surfaceOffsetY: 24,
+  /** Overlay scrim opacity at rest. */
+  scrimOpacity: 0.5
+};
+export const MOTION_TIER = {
+  low: {
+    durationScale: 0.6,
+    springs: false,
+    decorative: false,
+    blur: false
+  },
+  mid: {
+    durationScale: 1,
+    springs: true,
+    decorative: false,
+    blur: false
+  },
+  high: {
+    durationScale: 1,
+    springs: true,
+    decorative: true,
+    blur: true
+  }
+};
+
+/** Resolves a duration through the global switch, the global scale, and the device tier. */
+export function resolveDuration(key, tier, reducedMotion) {
+  if (!MOTION_ENABLED || reducedMotion) return 0;
+  return Math.round(MOTION_DURATION[key] * MOTION_SCALE * MOTION_TIER[tier].durationScale);
+}
+//# sourceMappingURL=config.js.map

package/lib/module/core/motion/index.js

@@ -0,0 +1,7 @@
+"use strict";
+
+export { MOTION_DURATION, MOTION_EASING_CURVE, MOTION_ENABLED, MOTION_SCALE, MOTION_SPRING, MOTION_TIER, MOTION_TRANSFORM, motionEasing, resetMotionEasingCache, resolveDuration } from "./config.js";
+export { useAnimatedValue } from "./useAnimatedValue.js";
+export { useMotion } from "./useMotion.js";
+export { useEnterExit, usePressMotion, useReveal } from "./presets.js";
+//# sourceMappingURL=index.js.map

package/lib/module/core/motion/presets.js

@@ -0,0 +1,192 @@
+"use strict";
+
+/**
+ * Ready-made motion for the two patterns that repeat across the library: press feedback, and
+ * mount/unmount reveal. Components use these instead of hand-rolling an `Animated.Value` each,
+ * so retuning `config.ts` retunes everything.
+ */
+
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { Animated } from "react-native";
+import { useAnimatedValue } from "./useAnimatedValue.js";
+import { useMotion } from "./useMotion.js";
+const NOOP = () => undefined;
+
+/** Shared by every disabled caller — `list-item` and `stat-tile` render thousands of these. */
+const PRESS_AT_REST = {
+  style: {
+    opacity: 1,
+    transform: [{
+      scale: 1
+    }]
+  },
+  onPressIn: NOOP,
+  onPressOut: NOOP
+};
+
+/** Scale + opacity dip on press. Native driver, so it never blocks the JS thread mid-scroll. */
+export function usePressMotion(disabled = false) {
+  const motion = useMotion();
+  const values = useRef(null);
+  const running = useRef(null);
+
+  // Lazily allocated: a 5000-row display-only list would otherwise build 10k values that never move.
+  if (!disabled && values.current === null) {
+    values.current = {
+      scale: new Animated.Value(1),
+      opacity: new Animated.Value(1)
+    };
+  }
+  const pressValues = values.current;
+  const animate = useCallback((toScale, toOpacity) => {
+    const current = values.current;
+    if (current === null) return;
+    running.current?.stop();
+    if (!motion.enabled) {
+      current.scale.setValue(toScale);
+      current.opacity.setValue(toOpacity);
+      return;
+    }
+    running.current = Animated.parallel([motion.timing(current.scale, toScale, {
+      duration: "fast"
+    }), motion.timing(current.opacity, toOpacity, {
+      duration: "fast"
+    })]);
+    running.current.start();
+  }, [motion]);
+  useEffect(() => () => running.current?.stop(), []);
+  const onPressIn = useCallback(() => {
+    if (disabled) return;
+    animate(motion.transform.pressScale, motion.transform.pressOpacity);
+  }, [disabled, animate, motion]);
+  const onPressOut = useCallback(() => {
+    if (disabled) return;
+    animate(1, 1);
+  }, [disabled, animate]);
+
+  // The Animated.Values are stable, but a fresh wrapper each render defeats every consumer
+  // `useMemo` keyed on `press.style`.
+  return useMemo(() => pressValues === null ? PRESS_AT_REST : {
+    style: {
+      opacity: pressValues.opacity,
+      transform: [{
+        scale: pressValues.scale
+      }]
+    },
+    onPressIn,
+    onPressOut
+  }, [pressValues, onPressIn, onPressOut]);
+}
+/**
+ * Fade + slide for a subtree whose mounting someone else already controls. Holds no state, so it
+ * costs no extra render — use this instead of `useEnterExit` when the caller ignores `mounted`.
+ */
+export function useReveal(visible, offsetY) {
+  const motion = useMotion();
+  const opacity = useAnimatedValue(visible ? 1 : 0);
+  const translateY = useAnimatedValue(0);
+  const running = useRef(null);
+  const distance = offsetY ?? motion.transform.offsetY;
+  useEffect(() => {
+    running.current?.stop();
+    if (!motion.enabled) {
+      opacity.setValue(visible ? 1 : 0);
+      translateY.setValue(0);
+      return;
+    }
+    running.current = Animated.parallel([motion.timing(opacity, visible ? 1 : 0, {
+      duration: visible ? "normal" : "fast",
+      easing: visible ? "decelerate" : "accelerate"
+    }), motion.timing(translateY, visible ? 0 : -distance / 2, {
+      duration: visible ? "normal" : "fast",
+      easing: visible ? "decelerate" : "accelerate"
+    })]);
+    running.current.start();
+  }, [visible, motion, opacity, translateY, distance]);
+  useEffect(() => () => running.current?.stop(), []);
+  return {
+    style: {
+      opacity,
+      transform: [{
+        translateY
+      }]
+    }
+  };
+}
+/**
+ * Fade + slide a subtree in, and keep it mounted only until the exit settles. The unmount is
+ * driven by a timer, not the animation callback: an interrupted animation must still unmount, or
+ * collapsed content leaks into the tree forever.
+ */
+export function useEnterExit(visible, offsetY) {
+  const motion = useMotion();
+  const [mounted, setMounted] = useState(visible);
+  const opacity = useAnimatedValue(visible ? 1 : 0);
+  const translateY = useAnimatedValue(0);
+  const skipFirstEnter = useRef(visible);
+  const running = useRef(null);
+  const exitTimer = useRef(null);
+  const distance = offsetY ?? motion.transform.offsetY;
+  useEffect(() => {
+    const clearExit = () => {
+      if (exitTimer.current !== null) {
+        clearTimeout(exitTimer.current);
+        exitTimer.current = null;
+      }
+    };
+    running.current?.stop();
+    if (visible) {
+      clearExit();
+      setMounted(true);
+      if (!motion.enabled || skipFirstEnter.current) {
+        skipFirstEnter.current = false;
+        opacity.setValue(1);
+        translateY.setValue(0);
+        return;
+      }
+      opacity.setValue(0);
+      translateY.setValue(-distance);
+      running.current = Animated.parallel([motion.timing(opacity, 1, {
+        easing: "decelerate"
+      }), motion.timing(translateY, 0, {
+        easing: "decelerate"
+      })]);
+      running.current.start();
+      return;
+    }
+    const exitMs = motion.duration("fast");
+    if (!motion.enabled || exitMs === 0) {
+      clearExit();
+      setMounted(false);
+      return;
+    }
+    running.current = Animated.parallel([motion.timing(opacity, 0, {
+      duration: "fast",
+      easing: "accelerate"
+    }), motion.timing(translateY, -distance / 2, {
+      duration: "fast",
+      easing: "accelerate"
+    })]);
+    running.current.start();
+    clearExit();
+    exitTimer.current = setTimeout(() => {
+      exitTimer.current = null;
+      setMounted(false);
+    }, exitMs);
+    return clearExit;
+  }, [visible, motion, opacity, translateY, distance]);
+  useEffect(() => () => {
+    running.current?.stop();
+    if (exitTimer.current !== null) clearTimeout(exitTimer.current);
+  }, []);
+  return {
+    mounted,
+    style: {
+      opacity,
+      transform: [{
+        translateY
+      }]
+    }
+  };
+}
+//# sourceMappingURL=presets.js.map

package/lib/module/core/motion/useAnimatedValue.js

@@ -0,0 +1,19 @@
+"use strict";
+
+import { useRef } from "react";
+import { Animated } from "react-native";
+
+/**
+ * A render-stable `Animated.Value`, allocated once.
+ *
+ * `useRef(new Animated.Value(0))` — the shape this replaces — evaluates its argument on **every**
+ * render and hands `useRef` a fresh node it then discards. A list row holding two of them throws
+ * away two animated nodes per row per render, which is exactly the churn the press-motion fix
+ * removed from `usePressMotion`. `initial` is read on the first render only, matching `useRef`.
+ */
+export function useAnimatedValue(initial) {
+  const ref = useRef(null);
+  ref.current ??= new Animated.Value(initial);
+  return ref.current;
+}
+//# sourceMappingURL=useAnimatedValue.js.map

package/lib/module/core/motion/useMotion.js

@@ -0,0 +1,46 @@
+"use strict";
+
+/**
+ * The single hook every animated module uses. Resolves the global config in `config.ts` against
+ * the device tier and the OS reduce-motion setting, so no component reads a raw duration.
+ *
+ * Reduce-motion (WCAG 2.3.3) always wins over the tier policy — `enabled` goes false and every
+ * duration resolves to 0, so callers can `setValue` instead of tweening.
+ */
+
+import { useCallback, useMemo } from "react";
+import { Animated } from "react-native";
+import { useReducedMotion } from "../a11y/index.js";
+import { resolveDeviceTier } from "../device/index.js";
+import { MOTION_ENABLED, MOTION_SPRING, MOTION_TIER, MOTION_TRANSFORM, motionEasing, resolveDuration } from "./config.js";
+export function useMotion() {
+  const reducedMotion = useReducedMotion();
+  // Resolved rather than `useDeviceTier()`d: that hook reads the same store, and one `useMotion`
+  // must cost one read.
+  const tier = useMemo(() => resolveDeviceTier(reducedMotion), [reducedMotion]);
+  const duration = useCallback(key => resolveDuration(key, tier, reducedMotion), [tier, reducedMotion]);
+  const easing = useCallback(key => motionEasing(key), []);
+  const spring = useCallback(key => {
+    if (!MOTION_ENABLED || reducedMotion || !MOTION_TIER[tier].springs) return null;
+    return MOTION_SPRING[key];
+  }, [tier, reducedMotion]);
+  const timing = useCallback((value, toValue, options) => Animated.timing(value, {
+    toValue,
+    duration: duration(options?.duration ?? "normal"),
+    easing: motionEasing(options?.easing ?? "standard"),
+    delay: options?.delay ?? 0,
+    useNativeDriver: true
+  }), [duration]);
+  return useMemo(() => ({
+    enabled: MOTION_ENABLED && !reducedMotion,
+    tier,
+    decorative: MOTION_ENABLED && !reducedMotion && MOTION_TIER[tier].decorative,
+    blur: MOTION_TIER[tier].blur,
+    transform: MOTION_TRANSFORM,
+    duration,
+    easing,
+    spring,
+    timing
+  }), [reducedMotion, tier, duration, easing, spring, timing]);
+}
+//# sourceMappingURL=useMotion.js.map

package/lib/module/core/style/index.js

@@ -1,4 +1,6 @@
 "use strict";
 
+export { sx } from "./sx.js";
+export { useThemedStyles } from "./useThemedStyles.js";
 export { createVariants, createTextVariants, createThemedVariants, createThemedTextVariants, variantFactory, themedVariantFactory } from "./variants.js";
 //# sourceMappingURL=index.js.map

package/lib/module/core/style/sx.js

@@ -0,0 +1,76 @@
+"use strict";
+
+import space from "../../theme/tokens/primitives/space.js";
+
+// A local declaration of RN's build-time global, so this file typechecks without depending on the
+// react-native ambient types being loaded. In a module scope it shadows nothing; RN replaces it.
+
+/**
+ * Spacing steps sx() accepts for padding/margin/gap — a deliberately short list (0–32dp) covering
+ * real layout spacing, not the full 17-step `SpaceToken` scale. Bigger jumps (36dp+) are almost
+ * always component *sizing* (an avatar, an icon touch target), not spacing between things — that
+ * belongs to `SizeToken`, not here. `Extract` ties this to `SpaceToken` so it can never list a
+ * step the shared scale doesn't actually have.
+ */
+
+/**
+ * Spacing + flex shorthand for building a plain `ViewStyle` inline — scoped deliberately to the
+ * two things app screens hand-write over and over (padding/margin/gap, flex layout), not a
+ * general CSS-in-JS escape hatch. No color, no typography, no borders — those already have a
+ * typed home (`useThemeColors()`, variant resolvers).
+ */
+
+/**
+ * Builds a plain `ViewStyle` object — pass it straight to any component's `style` prop.
+ *
+ * Builds a fresh object per call, same as an inline `style={{...}}` (never cached like
+ * `StyleSheet.create` or the themed variant resolver above). Fine for ordinary screen code that
+ * re-renders on user interaction; hoist a `StyleSheet.create` instead inside a list item renderer
+ * or anything re-rendering many times a second, where per-render allocation actually adds up.
+ */
+export function sx(props) {
+  const style = {};
+  if (props.p !== undefined) style.padding = space[props.p];
+  if (props.px !== undefined) style.paddingHorizontal = space[props.px];
+  if (props.py !== undefined) style.paddingVertical = space[props.py];
+  if (props.pt !== undefined) style.paddingTop = space[props.pt];
+  if (props.pr !== undefined) style.paddingRight = space[props.pr];
+  if (props.pb !== undefined) style.paddingBottom = space[props.pb];
+  if (props.pl !== undefined) style.paddingLeft = space[props.pl];
+  if (props.m !== undefined) style.margin = space[props.m];
+  if (props.mx !== undefined) style.marginHorizontal = space[props.mx];
+  if (props.my !== undefined) style.marginVertical = space[props.my];
+  if (props.mt !== undefined) style.marginTop = space[props.mt];
+  if (props.mr !== undefined) style.marginRight = space[props.mr];
+  if (props.mb !== undefined) style.marginBottom = space[props.mb];
+  if (props.ml !== undefined) style.marginLeft = space[props.ml];
+  if (props.gap !== undefined) style.gap = space[props.gap];
+  if (props.rowGap !== undefined) style.rowGap = space[props.rowGap];
+  if (props.columnGap !== undefined) style.columnGap = space[props.columnGap];
+  if (props.row) style.flexDirection = props.reverse ? "row-reverse" : "row";else if (props.reverse) style.flexDirection = "column-reverse";
+  if (props.wrap) style.flexWrap = "wrap";
+
+  // `center` sets both axes first so an explicit `align`/`justify` below can still override it.
+  if (props.center) {
+    style.alignItems = "center";
+    style.justifyContent = "center";
+  }
+  if (props.align !== undefined) style.alignItems = props.align;
+  if (props.justify !== undefined) style.justifyContent = props.justify;
+  if (props.alignContent !== undefined) style.alignContent = props.alignContent;
+  if (props.flex !== undefined) style.flex = props.flex;
+  if (props.grow !== undefined) style.flexGrow = props.grow;
+  if (props.shrink !== undefined) style.flexShrink = props.shrink;
+  if (props.basis !== undefined) style.flexBasis = props.basis;
+  if (props.self !== undefined) style.alignSelf = props.self;
+
+  // Dev-only: catches accidental in-place mutation (`styles.x.gap = 4` instead of merging) early.
+  // Skipped in production for zero runtime cost — and skipped here entirely rather than trusting
+  // a bundler to dead-code-eliminate it, since this file has no build-time __DEV__ replacement of
+  // its own. Matters more once a result is hoisted into `StyleSheet.create` and shared by
+  // reference across a whole screen; unlike an inline `style={{...}}` object nobody else touches,
+  // a mutation there corrupts every other spot that reused it.
+  if (typeof __DEV__ !== "undefined" && __DEV__) return Object.freeze(style);
+  return style;
+}
+//# sourceMappingURL=sx.js.map

package/lib/module/core/style/useThemedStyles.js

@@ -0,0 +1,8 @@
+"use strict";
+
+import { useMemo } from 'react';
+/** Memoizes themed style arrays at the component boundary. */
+export function useThemedStyles(factory, theme, deps = []) {
+  return useMemo(() => factory(theme), [theme, factory, ...deps]);
+}
+//# sourceMappingURL=useThemedStyles.js.map