pixelize-native-library 1.0.7 → 1.2.0

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

package/lib/module/index.js

@@ -7,7 +7,75 @@
  * only via their subpath — so a lazy barrel import cannot drag a chart engine into an app's
  * bundle, even with every optimizer turned off.
  *
- * Generated re-exports land below; do not add heavy modules by hand.
+ * GENERATED by scripts/gen-index.mjs — do not hand-edit below this comment; run `npm run gen` to
+ * regenerate (CI runs `npm run gen:check` as the drift gate). Adding a light module here is
+ * automatic the next time `npm run gen` runs against its src/modules/<name>/index.ts; nothing here
+ * is ever added "by hand".
  */
-export {};
+
+export { Accordion } from "./modules/accordion/index.js";
+export { AlertDialog } from "./modules/alert-dialog/index.js";
+export { AppBar } from "./modules/app-bar/index.js";
+export { Avatar } from "./modules/avatar/index.js";
+export { AvatarGroup } from "./modules/avatar-group/index.js";
+export { Badge } from "./modules/badge/index.js";
+export { Banner } from "./modules/banner/index.js";
+export { BottomNav } from "./modules/bottom-nav/index.js";
+export { BottomSheet } from "./modules/bottom-sheet/index.js";
+export { Button } from "./modules/button/index.js";
+export { ButtonGroup } from "./modules/button-group/index.js";
+export { Card } from "./modules/card/index.js";
+export { Checkbox } from "./modules/checkbox/index.js";
+export { Chip, ChipGroup } from "./modules/chip/index.js";
+export { Combobox } from "./modules/combobox/index.js";
+export { Composer } from "./modules/composer/index.js";
+export { CopyButton } from "./modules/copy-button/index.js";
+export { Divider } from "./modules/divider/index.js";
+export { Drawer } from "./modules/drawer/index.js";
+export { EmptyState } from "./modules/empty-state/index.js";
+export { Fab, FabGroup } from "./modules/fab/index.js";
+export { FileGrid } from "./modules/file-grid/index.js";
+export { FileUpload } from "./modules/file-upload/index.js";
+export { FilterSheet, FilterChip, countActiveFilters } from "./modules/filter-sheet/index.js";
+export { FolderRow } from "./modules/folder-row/index.js";
+export { FormField } from "./modules/form-field/index.js";
+export { Input } from "./modules/input/index.js";
+export { LimitReachedModal } from "./modules/limit-reached-modal/index.js";
+export { ListItem } from "./modules/list-item/index.js";
+export { Markdown, parseMarkdown } from "./modules/markdown/index.js";
+export { Menu } from "./modules/menu/index.js";
+export { MessageBubble } from "./modules/message-bubble/index.js";
+export { Modal, ModalPortalProvider } from "./modules/modal/index.js";
+export { MoreItems } from "./modules/more-items/index.js";
+export { MultiSelect } from "./modules/multi-select/index.js";
+export { NumberInput } from "./modules/number-input/index.js";
+export { OrgSwitcher } from "./modules/org-switcher/index.js";
+export { Pagination, buildPageRange, clampPage } from "./modules/pagination/index.js";
+export { PinInput } from "./modules/pin-input/index.js";
+export { ProgressBar } from "./modules/progress-bar/index.js";
+export { RadioGroup } from "./modules/radio-group/index.js";
+export { Reorder } from "./modules/reorder/index.js";
+export { Screen } from "./modules/screen/index.js";
+export { SearchBar } from "./modules/search-bar/index.js";
+export { Section } from "./modules/section/index.js";
+export { SectionList } from "./modules/section-list/index.js";
+export { SegmentedControl } from "./modules/segmented-control/index.js";
+export { Select } from "./modules/select/index.js";
+export { Skeleton } from "./modules/skeleton/index.js";
+export { Slider } from "./modules/slider/index.js";
+export { Spinner } from "./modules/spinner/index.js";
+export { StageProgress } from "./modules/stage-progress/index.js";
+export { StatTile } from "./modules/stat-tile/index.js";
+export { LoadingState, ErrorState } from "./modules/state-block/index.js";
+export { Stepper } from "./modules/stepper/index.js";
+export { SwipeableRow } from "./modules/swipeable-row/index.js";
+export { Switch } from "./modules/switch/index.js";
+export { Tabs } from "./modules/tabs/index.js";
+export { Text, Heading } from "./modules/text/index.js";
+export { Textarea } from "./modules/textarea/index.js";
+export { Timeline } from "./modules/timeline/index.js";
+export { ToastProvider, useToast } from "./modules/toast/index.js";
+export { Tooltip } from "./modules/tooltip/index.js";
+export { TypingIndicator } from "./modules/typing-indicator/index.js";
+export { UnreadBadge } from "./modules/unread-badge/index.js";
 //# sourceMappingURL=index.js.map