@webority-technologies/mobile 0.0.14 → 0.0.20

package/lib/module/components/Skeleton/Skeleton.js

@@ -1,22 +1,57 @@
 "use strict";
 
-import React, { useEffect, useMemo, useRef, useState } from 'react';
-import { Animated, Easing, StyleSheet, View } from 'react-native';
-import { useTheme, createAnimatedValue, setNativeValue } from "../../theme/index.js";
+/**
+ * Skeleton — the leaf placeholder primitive.
+ *
+ * Every Skeleton on screen reads the shared shimmer/pulse clock from
+ * `SkeletonProvider` (see SkeletonClock.tsx). One native-driver loop per
+ * provider drives every instance, so 50 placeholders on a list don't spawn
+ * 50 timers and the shimmer bands never drift out of phase.
+ *
+ * Visual:
+ *   - A View with the base color and `overflow: hidden` + radius gives the
+ *     placeholder its shape.
+ *   - For `animation: 'shimmer'`, an Animated.View carrying a 3-stop
+ *     `LinearGradient` (transparent → highlight → transparent) translates
+ *     across the box. The radius clips it to the right outline automatically.
+ *   - For `animation: 'pulse'`, a full-fill Animated.View fades its opacity
+ *     between 0 and 0.6. Cheap and useful for tiny shapes where a sweep
+ *     would barely be visible.
+ *   - For `animation: 'none'` (or when the OS Reduce Motion preference is
+ *     on), just the base color renders.
+ *
+ * `variant` describes the SHAPE: rect (default), rounded (theme.radius.md),
+ * circle (50%), or text (small radius, slightly inset height). Set width /
+ * height directly for full control.
+ */
+
+import React, { useMemo, useState } from 'react';
+import { Animated, StyleSheet, View } from 'react-native';
+import { useTheme } from "../../theme/index.js";
+
+// `react-native-linear-gradient` is an OPTIONAL peer dep. When it's installed
+// we sweep a real gradient band across the shimmer. When it isn't, we fall
+// back to a solid-color band — still works, just less polished. This keeps
+// the library deployable in apps that don't need gradients elsewhere.
+let LinearGradientImpl = null;
+try {
+  // eslint-disable-next-line @typescript-eslint/no-require-imports
+  LinearGradientImpl = require('react-native-linear-gradient').default;
+} catch {
+  // Optional peer; resolved lazily by consumers that need shimmer polish.
+}
 import { Responsive } from "../../utils/index.js";
+import { useSkeletonClock } from "./SkeletonClock.js";
 import { useSkeletonDefaults } from "./SkeletonProvider.js";
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-const SPEED_DURATION = {
-  slow: 1800,
-  normal: 1200,
-  fast: 800
-};
-const PULSE_DURATION = 1000;
-const AVATAR_SIZE = {
-  sm: 32,
-  md: 48,
-  lg: 64
-};
+
+/** Animation pattern. */
+
+/** Sweep speed for the shimmer band. Ignored for pulse / none. */
+
+/** Pre-defined shape archetype. Plays nicely with `width`/`height` overrides. */
+
+/** `theme.radius` token name or a literal pixel value. */
+import { jsx as _jsx } from "react/jsx-runtime";
 const resolveRadius = (theme, radius) => {
   if (typeof radius === 'number') return radius;
   return theme.radius[radius];
@@ -26,92 +61,128 @@ const resolveWidth = width => {
   if (typeof width === 'number') return width;
   return width;
 };
+const radiusForShape = (theme, shape, width, height, explicit) => {
+  if (explicit !== undefined) return resolveRadius(theme, explicit);
+  switch (shape) {
+    case 'circle':
+      // Half the smallest known dimension. If width is a percentage we can't
+      // resolve here — fall back to height/2 which is the typical caller
+      // intent (square avatars).
+      return Math.floor(typeof width === 'number' ? Math.min(width, height) / 2 : height / 2);
+    case 'rounded':
+      return theme.radius.md;
+    case 'text':
+      return theme.radius.sm;
+    case 'rect':
+    default:
+      return theme.radius.sm;
+  }
+};
 const Skeleton = ({
+  shape = 'rect',
   width = '100%',
   height = 16,
   radius,
   variant,
-  speed,
+  speed: _speedProp,
   colors,
   style,
   testID
 }) => {
   const theme = useTheme();
   const defaults = useSkeletonDefaults();
+  const clock = useSkeletonClock();
   const resolvedVariant = variant ?? defaults.variant ?? 'shimmer';
-  const resolvedSpeed = speed ?? defaults.speed ?? 'normal';
-  const resolvedRadiusToken = radius ?? defaults.radius ?? 'sm';
+  const effectiveVariant = clock.enabled ? resolvedVariant : 'none';
   const backgroundColor = colors?.background ?? defaults.colors?.background ?? theme.colors.skeleton.background;
   const highlightColor = colors?.highlight ?? defaults.colors?.highlight ?? theme.colors.skeleton.highlight;
-  const styles = useMemo(() => buildStyles(theme), [theme]);
-  const borderRadius = resolveRadius(theme, resolvedRadiusToken);
+  const styles = useMemo(() => buildStyles(), []);
   const resolvedWidth = resolveWidth(width);
   const resolvedHeight = Responsive.size(height);
-  const progress = useRef(createAnimatedValue(0)).current;
+  const borderRadius = radiusForShape(theme, shape, resolvedWidth, resolvedHeight, radius);
   const [containerWidth, setContainerWidth] = useState(0);
-  useEffect(() => {
-    setNativeValue(progress, 0);
-    const duration = resolvedVariant === 'pulse' ? PULSE_DURATION : SPEED_DURATION[resolvedSpeed];
-    const animation = resolvedVariant === 'pulse' ? Animated.loop(Animated.sequence([Animated.timing(progress, {
-      toValue: 1,
-      duration: duration / 2,
-      easing: Easing.inOut(Easing.ease),
-      useNativeDriver: true
-    }), Animated.timing(progress, {
-      toValue: 0,
-      duration: duration / 2,
-      easing: Easing.inOut(Easing.ease),
-      useNativeDriver: true
-    })])) : Animated.loop(Animated.timing(progress, {
-      toValue: 1,
-      duration,
-      easing: Easing.linear,
-      useNativeDriver: true
-    }));
-    animation.start();
-    return () => {
-      animation.stop();
-    };
-  }, [progress, resolvedSpeed, resolvedVariant]);
   const handleLayout = event => {
     const next = event.nativeEvent.layout.width;
     if (next !== containerWidth) setContainerWidth(next);
   };
+
+  // The shimmer band is wider than the box so the gradient feathers off the
+  // edges instead of popping at them. Width = 70% of container, capped to a
+  // sensible minimum so tiny placeholders still get a visible sweep.
+  const bandWidth = useMemo(() => {
+    if (containerWidth <= 0) return 0;
+    return Math.max(48, containerWidth * 0.7);
+  }, [containerWidth]);
+
+  // Interpolate the shared 0→1 clock into translateX. The band starts fully
+  // off the left edge and ends fully off the right edge, so each loop sweeps
+  // the full width regardless of how wide the placeholder is.
+  const translateX = useMemo(() => {
+    if (containerWidth <= 0) return 0;
+    return clock.shimmer.interpolate({
+      inputRange: [0, 1],
+      outputRange: [-bandWidth, containerWidth]
+    });
+  }, [clock.shimmer, bandWidth, containerWidth]);
   const overlay = useMemo(() => {
-    if (resolvedVariant === 'pulse') {
+    if (effectiveVariant === 'none') return null;
+    if (effectiveVariant === 'pulse') {
+      // Pulse fades a full-fill highlight overlay in and out. Cheaper than
+      // shimmer and visible at any size.
       return /*#__PURE__*/_jsx(Animated.View, {
         pointerEvents: "none",
         style: [StyleSheet.absoluteFillObject, {
           backgroundColor: highlightColor,
-          opacity: progress.interpolate({
+          opacity: clock.pulse.interpolate({
             inputRange: [0, 1],
-            outputRange: [0, 0.6]
+            outputRange: [0, 0.55]
           })
         }]
       });
     }
     if (containerWidth <= 0) return null;
-    const highlightWidth = Math.max(48, containerWidth * 0.6);
-    const translateX = progress.interpolate({
-      inputRange: [0, 1],
-      outputRange: [-highlightWidth, containerWidth]
-    });
+
+    // 3-stop gradient: transparent → highlight → transparent. Feathered
+    // edges feel premium; a solid band looks like a bug. When the optional
+    // gradient package isn't installed we render the band as a solid
+    // highlight rectangle — visibly different but still recognizably a
+    // shimmer effect.
     return /*#__PURE__*/_jsx(Animated.View, {
       pointerEvents: "none",
-      style: [styles.shimmer, {
-        width: highlightWidth,
-        backgroundColor: highlightColor,
+      style: [styles.shimmerBand, {
+        width: bandWidth,
         transform: [{
           translateX
         }]
-      }]
+      }],
+      children: LinearGradientImpl ? /*#__PURE__*/_jsx(LinearGradientImpl, {
+        colors: ['transparent', highlightColor, 'transparent'],
+        locations: [0, 0.5, 1],
+        start: {
+          x: 0,
+          y: 0.5
+        },
+        end: {
+          x: 1,
+          y: 0.5
+        },
+        style: StyleSheet.absoluteFillObject
+      }) : /*#__PURE__*/_jsx(View, {
+        style: [StyleSheet.absoluteFillObject, {
+          backgroundColor: highlightColor,
+          opacity: 0.55
+        }]
+      })
     });
-  }, [containerWidth, progress, styles.shimmer, highlightColor, resolvedVariant]);
+  }, [effectiveVariant, highlightColor, clock.pulse, containerWidth, styles.shimmerBand, bandWidth, translateX]);
   return /*#__PURE__*/_jsx(View, {
     onLayout: handleLayout,
     accessible: true,
     accessibilityLabel: "Loading",
     accessibilityRole: "progressbar",
+    accessibilityState: {
+      busy: true
+    },
     accessibilityLiveRegion: "polite",
     testID: testID,
     style: [styles.base, {
@@ -132,9 +203,9 @@ const SkeletonCircle = ({
   const diameter = Responsive.size(size);
   return /*#__PURE__*/_jsx(Skeleton, {
     ...rest,
+    shape: "circle",
     width: diameter,
     height: size,
-    radius: "full",
     style: [{
       width: diameter,
       height: diameter,
@@ -168,6 +239,7 @@ const SkeletonText = ({
       const isLast = index === safeLines - 1;
       const lineWidth = isLast && safeLines > 1 ? lastLineWidth : width;
       return /*#__PURE__*/_jsx(Skeleton, {
+        shape: "text",
         width: lineWidth,
         height: lineHeight,
         radius: radius,
@@ -181,129 +253,17 @@ const SkeletonText = ({
   });
 };
 SkeletonText.displayName = 'SkeletonText';
-const SkeletonAvatar = ({
-  size = 'md',
-  ...rest
-}) => {
-  return /*#__PURE__*/_jsx(SkeletonCircle, {
-    ...rest,
-    size: AVATAR_SIZE[size]
-  });
-};
-SkeletonAvatar.displayName = 'SkeletonAvatar';
-const SkeletonCard = ({
-  variant,
-  speed,
-  radius = 'md',
-  style,
-  testID
-}) => {
-  const theme = useTheme();
-  return /*#__PURE__*/_jsxs(View, {
-    style: [{
-      padding: theme.spacing.md
-    }, style],
-    testID: testID,
-    children: [/*#__PURE__*/_jsxs(View, {
-      style: {
-        flexDirection: 'row',
-        alignItems: 'center',
-        marginBottom: theme.spacing.md
-      },
-      children: [/*#__PURE__*/_jsx(SkeletonAvatar, {
-        size: "md",
-        variant: variant,
-        speed: speed
-      }), /*#__PURE__*/_jsxs(View, {
-        style: {
-          flex: 1,
-          marginLeft: theme.spacing.sm
-        },
-        children: [/*#__PURE__*/_jsx(Skeleton, {
-          width: "60%",
-          height: 14,
-          radius: radius,
-          variant: variant,
-          speed: speed,
-          style: {
-            marginBottom: theme.spacing.xs
-          }
-        }), /*#__PURE__*/_jsx(Skeleton, {
-          width: "40%",
-          height: 12,
-          radius: radius,
-          variant: variant,
-          speed: speed
-        })]
-      })]
-    }), /*#__PURE__*/_jsx(SkeletonText, {
-      lines: 2,
-      fontSize: 14,
-      variant: variant,
-      speed: speed,
-      radius: radius
-    })]
-  });
-};
-SkeletonCard.displayName = 'SkeletonCard';
-const SkeletonListItem = ({
-  avatarSize = 'md',
-  variant,
-  speed,
-  radius = 'sm',
-  style,
-  testID
-}) => {
-  const theme = useTheme();
-  return /*#__PURE__*/_jsxs(View, {
-    style: [{
-      flexDirection: 'row',
-      alignItems: 'center',
-      paddingHorizontal: theme.spacing.md,
-      paddingVertical: theme.spacing.sm
-    }, style],
-    testID: testID,
-    children: [/*#__PURE__*/_jsx(SkeletonAvatar, {
-      size: avatarSize,
-      variant: variant,
-      speed: speed
-    }), /*#__PURE__*/_jsxs(View, {
-      style: {
-        flex: 1,
-        marginLeft: theme.spacing.sm
-      },
-      children: [/*#__PURE__*/_jsx(Skeleton, {
-        width: "70%",
-        height: 14,
-        radius: radius,
-        variant: variant,
-        speed: speed,
-        style: {
-          marginBottom: theme.spacing.xs
-        }
-      }), /*#__PURE__*/_jsx(Skeleton, {
-        width: "45%",
-        height: 12,
-        radius: radius,
-        variant: variant,
-        speed: speed
-      })]
-    })]
-  });
-};
-SkeletonListItem.displayName = 'SkeletonListItem';
-const buildStyles = _theme => StyleSheet.create({
+const buildStyles = () => StyleSheet.create({
   base: {
     overflow: 'hidden'
   },
-  shimmer: {
+  shimmerBand: {
     position: 'absolute',
     top: 0,
     bottom: 0,
-    left: 0,
-    opacity: 0.55
+    left: 0
   }
 });
-export { Skeleton, SkeletonCircle, SkeletonText, SkeletonAvatar, SkeletonCard, SkeletonListItem };
+export { Skeleton, SkeletonCircle, SkeletonText };
 export default Skeleton;
 //# sourceMappingURL=Skeleton.js.map

package/lib/module/components/Skeleton/SkeletonClock.js

@@ -0,0 +1,110 @@
+"use strict";
+
+/**
+ * SkeletonClock — single shared animation tick for every <Skeleton> on screen.
+ *
+ * Why this exists: previously every Skeleton primitive ran its own
+ * `Animated.loop` on its own `Animated.Value`. A list of 20 placeholders =
+ * 20 independent native-driver timers, each starting at a slightly different
+ * mount frame, so their shimmer bands drift out of phase within ~1s and the
+ * surface feels noisy. CSS-driven web skeleton libs (react-loading-skeleton,
+ * MUI) avoid this because the browser owns a single timeline. We emulate
+ * that on RN by hoisting the loop into context.
+ *
+ * The clock produces a value in `[0, 1)` that wraps every `duration` ms. Each
+ * Skeleton interpolates that value into its own translateX / opacity output.
+ * One native-driver loop, no drift, ~zero JS cost.
+ */
+
+import React, { createContext, useContext, useEffect, useMemo, useRef } from 'react';
+import { Animated, Easing } from 'react-native';
+import { createAnimatedValue } from "../../theme/index.js";
+import { jsx as _jsx } from "react/jsx-runtime";
+const SHIMMER_DURATION = {
+  slow: 1800,
+  normal: 1200,
+  fast: 800
+};
+const PULSE_DURATION = 1000;
+const SkeletonClockContext = /*#__PURE__*/createContext(null);
+/**
+ * Owns the loops. Mount one of these inside `SkeletonProvider`; every
+ * `<Skeleton>` below it shares the same animated values.
+ */
+export const SkeletonClockProvider = ({
+  speed,
+  enabled,
+  variant: _variant,
+  children
+}) => {
+  const shimmer = useRef(createAnimatedValue(0)).current;
+  const pulse = useRef(createAnimatedValue(0)).current;
+  useEffect(() => {
+    if (!enabled) {
+      // Park the values at a deterministic "off" state so any consumer that
+      // happens to be reading them still gets a visible (static) skeleton.
+      shimmer.setValue(0);
+      pulse.setValue(0.5);
+      return;
+    }
+
+    // Both loops use the native driver — the JS thread doesn't tick for
+    // either. Both run continuously; consumers read whichever they need.
+    // The negligible cost of running the *other* loop is worth keeping
+    // variant switching instant (no remount, no loop teardown).
+    const shimmerLoop = Animated.loop(Animated.timing(shimmer, {
+      toValue: 1,
+      duration: SHIMMER_DURATION[speed],
+      easing: Easing.linear,
+      useNativeDriver: true
+    }));
+    const pulseLoop = Animated.loop(Animated.sequence([Animated.timing(pulse, {
+      toValue: 1,
+      duration: PULSE_DURATION / 2,
+      easing: Easing.inOut(Easing.ease),
+      useNativeDriver: true
+    }), Animated.timing(pulse, {
+      toValue: 0,
+      duration: PULSE_DURATION / 2,
+      easing: Easing.inOut(Easing.ease),
+      useNativeDriver: true
+    })]));
+    shimmerLoop.start();
+    pulseLoop.start();
+    return () => {
+      shimmerLoop.stop();
+      pulseLoop.stop();
+    };
+    // `variant` is intentionally NOT a dependency — both loops always run
+    // so switching variants is a single render with no loop teardown.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [speed, enabled]);
+  const value = useMemo(() => ({
+    shimmer,
+    pulse,
+    enabled
+  }), [shimmer, pulse, enabled]);
+  return /*#__PURE__*/_jsx(SkeletonClockContext.Provider, {
+    value: value,
+    children: children
+  });
+};
+SkeletonClockProvider.displayName = 'SkeletonClockProvider';
+
+/**
+ * Read the active clock. Returns a fallback "always-still" clock when no
+ * provider is mounted, so the primitives still render (statically) outside
+ * one — keeps demo/storybook usage friction-free.
+ */
+export const useSkeletonClock = () => {
+  const ctx = useContext(SkeletonClockContext);
+  if (ctx) return ctx;
+  // Fallback: a permanently-stopped clock. Created once at module scope.
+  return fallbackClock;
+};
+const fallbackClock = {
+  shimmer: createAnimatedValue(0),
+  pulse: createAnimatedValue(0.5),
+  enabled: false
+};
+//# sourceMappingURL=SkeletonClock.js.map