pixelize-native-library 1.0.7 → 1.2.0

package/lib/module/core/list/VirtualList.js

@@ -0,0 +1,226 @@
+"use strict";
+
+import { useCallback, useMemo } from 'react';
+import { FlatList, Platform } from 'react-native';
+import { useDeviceTier } from "../device/index.js";
+
+/**
+ * `core/list` is internal, so this is a curated allowlist of the list props modules legitimately
+ * need — never `{...rest}`. A prop missing here forces the module to re-express it as layout, which
+ * is how the DataTable header ended up rendered after its own rows.
+ */
+
+/**
+ * FlashList v2's real prop surface for what this list forwards — verified against
+ * `@shopify/flash-list@2.3.2`. It has no `getItemLayout` / `initialNumToRender` /
+ * `maxToRenderPerBatch` / `updateCellsBatchingPeriod` at all; `drawDistance` (dp of content kept
+ * rendered beyond the viewport) is its one windowing knob.
+ */
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+/** FlashList's own default is 250dp; low-end halves it, high-end buys a smoother fling. */
+export function flashListDrawDistance(tier) {
+  switch (tier) {
+    case 'low':
+      return 125;
+    case 'high':
+      return 500;
+    default:
+      return 250;
+  }
+}
+function flatListTuning(tier) {
+  switch (tier) {
+    case 'low':
+      return {
+        initialNumToRender: 6,
+        maxToRenderPerBatch: 4,
+        windowSize: 5,
+        updateCellsBatchingPeriod: 100,
+        removeClippedSubviews: Platform.OS === 'android'
+      };
+    case 'high':
+      return {
+        initialNumToRender: 14,
+        maxToRenderPerBatch: 14,
+        windowSize: 15,
+        updateCellsBatchingPeriod: 30,
+        removeClippedSubviews: Platform.OS === 'android'
+      };
+    default:
+      return {
+        initialNumToRender: 10,
+        maxToRenderPerBatch: 10,
+        windowSize: 10,
+        updateCellsBatchingPeriod: 50,
+        removeClippedSubviews: Platform.OS === 'android'
+      };
+  }
+}
+function resolveFlashList() {
+  if (process.env.JEST_WORKER_ID !== undefined) return null;
+  try {
+    // Optional peer — FlatList fallback when absent.
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const peer = require('@shopify/flash-list');
+    return peer.FlashList ?? null;
+  } catch {
+    return null;
+  }
+}
+
+// Resolved once: inside the render it threw and caught a module-resolution error per render per
+// mounted list whenever the optional peer is absent.
+const FlashList = resolveFlashList();
+
+/** FlashList never passes `separators`; the adapter keeps modules on RN's `ListRenderItem` shape. */
+const NO_SEPARATORS = {
+  highlight: () => undefined,
+  unhighlight: () => undefined,
+  updateProps: () => undefined
+};
+export function VirtualList({
+  data,
+  renderItem,
+  keyExtractor,
+  itemHeight,
+  getItemLayout,
+  keyboardShouldPersistTaps,
+  ListHeaderComponent,
+  ListFooterComponent,
+  ListEmptyComponent,
+  stickyHeaderIndices,
+  contentContainerStyle,
+  numColumns,
+  accessibilityRole = 'list',
+  accessibilityLabel,
+  accessibilityHint,
+  testID
+}) {
+  const tier = useDeviceTier();
+  const tuning = useMemo(() => flatListTuning(tier), [tier]);
+
+  // A fresh function each render would defeat FlashList's own memoization of the layout provider.
+  const uniformLayout = useMemo(() => itemHeight === undefined ? undefined : (_, index) => ({
+    length: itemHeight,
+    offset: itemHeight * index,
+    index
+  }), [itemHeight]);
+  const resolvedLayout = getItemLayout ?? uniformLayout;
+  const flashRenderItem = useMemo(() => ({
+    item,
+    index
+  }) => renderItem({
+    item,
+    index,
+    separators: NO_SEPARATORS
+  }), [renderItem]);
+  if (FlashList) {
+    return /*#__PURE__*/_jsx(FlashList, {
+      testID: testID,
+      data: data,
+      renderItem: flashRenderItem,
+      keyExtractor: keyExtractor,
+      keyboardShouldPersistTaps: keyboardShouldPersistTaps,
+      ListHeaderComponent: ListHeaderComponent,
+      ListFooterComponent: ListFooterComponent,
+      ListEmptyComponent: ListEmptyComponent,
+      stickyHeaderIndices: stickyHeaderIndices,
+      contentContainerStyle: contentContainerStyle,
+      numColumns: numColumns,
+      accessibilityRole: accessibilityRole,
+      accessibilityLabel: accessibilityLabel,
+      accessibilityHint: accessibilityHint,
+      drawDistance: flashListDrawDistance(tier)
+    });
+  }
+  return /*#__PURE__*/_jsx(FlatList, {
+    testID: testID,
+    data: data,
+    renderItem: renderItem,
+    keyExtractor: keyExtractor,
+    getItemLayout: resolvedLayout,
+    keyboardShouldPersistTaps: keyboardShouldPersistTaps,
+    ListHeaderComponent: ListHeaderComponent,
+    ListFooterComponent: ListFooterComponent,
+    ListEmptyComponent: ListEmptyComponent,
+    stickyHeaderIndices: stickyHeaderIndices,
+    contentContainerStyle: contentContainerStyle,
+    numColumns: numColumns,
+    accessibilityRole: accessibilityRole,
+    accessibilityLabel: accessibilityLabel,
+    accessibilityHint: accessibilityHint,
+    initialNumToRender: tuning.initialNumToRender,
+    maxToRenderPerBatch: tuning.maxToRenderPerBatch,
+    windowSize: tuning.windowSize,
+    updateCellsBatchingPeriod: tuning.updateCellsBatchingPeriod,
+    removeClippedSubviews: tuning.removeClippedSubviews
+  });
+}
+
+/** One flattened row. `item === undefined` is the header-only row an empty section still gets. */
+
+export function VirtualSectionList({
+  sections,
+  renderItem,
+  renderSectionHeader,
+  keyExtractor,
+  itemHeight,
+  sectionHeaderHeight,
+  accessibilityLabel,
+  testID
+}) {
+  const flatData = useMemo(() => sections.flatMap((section, sectionIndex) => section.data.length === 0 ? [{
+    section,
+    sectionIndex,
+    item: undefined,
+    index: 0,
+    showHeader: true
+  }] : section.data.map((item, index) => ({
+    section,
+    sectionIndex,
+    item,
+    index,
+    showHeader: index === 0
+  }))), [sections]);
+  const renderFlatItem = useCallback(({
+    item: row
+  }) => /*#__PURE__*/_jsxs(_Fragment, {
+    children: [row.showHeader ? renderSectionHeader(row.section) : null, row.item === undefined ? null : renderItem({
+      item: row.item,
+      section: row.section,
+      index: row.index
+    })]
+  }), [renderItem, renderSectionHeader]);
+  const rowKeyExtractor = useCallback(row => row.item === undefined ? `virtual-section-${row.sectionIndex}-empty` : keyExtractor(row.item, row.index), [keyExtractor]);
+
+  // Header-bearing rows are taller than plain ones, so a single `itemHeight` cannot describe both.
+  const getItemLayout = useMemo(() => {
+    if (itemHeight === undefined || sectionHeaderHeight === undefined) return undefined;
+    let offset = 0;
+    const layouts = flatData.map(row => {
+      const length = (row.showHeader ? sectionHeaderHeight : 0) + (row.item === undefined ? 0 : itemHeight);
+      const entry = {
+        length,
+        offset
+      };
+      offset += length;
+      return entry;
+    });
+    return (_, index) => ({
+      ...(layouts[index] ?? {
+        length: itemHeight,
+        offset: itemHeight * index
+      }),
+      index
+    });
+  }, [flatData, itemHeight, sectionHeaderHeight]);
+  return /*#__PURE__*/_jsx(VirtualList, {
+    testID: testID,
+    data: flatData,
+    renderItem: renderFlatItem,
+    keyExtractor: rowKeyExtractor,
+    getItemLayout: getItemLayout,
+    accessibilityLabel: accessibilityLabel
+  });
+}
+//# sourceMappingURL=VirtualList.js.map

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

@@ -0,0 +1,4 @@
+"use strict";
+
+export { VirtualList, VirtualSectionList } from "./VirtualList.js";
+//# sourceMappingURL=index.js.map

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