panelui-native 0.76.0 → 0.78.0

package/src/components/treemap-chart/index.tsx

@@ -66,18 +66,26 @@ import {
   isValidElement,
   useContext,
   useEffect,
+  useId,
   useImperativeHandle,
   useMemo,
   useRef,
   useState,
   type ReactNode,
 } from 'react';
-import { Pressable, View, type LayoutChangeEvent, type ViewProps } from 'react-native';
+import {
+  Pressable,
+  View,
+  type LayoutChangeEvent,
+  type PressableProps,
+  type ViewProps,
+} from 'react-native';
 import Animated, {
   Easing,
   cancelAnimation,
   useAnimatedProps,
   useDerivedValue,
+  useAnimatedStyle,
   useReducedMotion,
   useSharedValue,
   withRepeat,
@@ -89,7 +97,10 @@ import { useCSSVariable } from 'uniwind';
 import { Text } from '../../primitives/text';
 import { compactNumber, inkOn, useSeriesColor } from '../../utils/chart';
 import { cn } from '../../utils/cn';
+import { useSkeletonHandoff } from '../../hooks/use-skeleton-handoff';
 
+const AnimatedG = Animated.createAnimatedComponent(G);
+const AnimatedPressable = Animated.createAnimatedComponent(Pressable);
 const AnimatedRect = Animated.createAnimatedComponent(Rect);
 const AnimatedLinearGradient = Animated.createAnimatedComponent(LinearGradient);
 
@@ -820,6 +831,9 @@ function TreemapChartSkeleton({ duration = 1400, color }: TreemapChartSkeletonPr
   const token = useCSSVariable('--color-skeleton');
   const base = color ?? (typeof token === 'string' ? token : 'rgba(128,128,128,0.2)');
   const highlight = useSeriesColor(undefined, 1);
+  // Unique per instance: a fixed id makes two of these on one screen share a
+  // gradient, and the second one to mount wins.
+  const gradientId = `panelui-treemap-skeleton-${useId().replace(/[^a-zA-Z0-9]/g, '')}`;
 
   const sweep = useSharedValue(0);
   const reducedMotion = useReducedMotion();
@@ -843,12 +857,16 @@ function TreemapChartSkeleton({ duration = 1400, color }: TreemapChartSkeletonPr
     x2: `${(sweep.value * 1.4 - 0.4 + 0.4) * 100}%`,
   }));
 
-  if (!loading || width <= 0 || height <= 0) return null;
+  // Held through the fade rather than to the frame the data lands: the box has
+  // to dissolve while the tiles grow through it, or the panel is empty for as
+  // long as the first tile takes to become visible.
+  const { mounted, opacity } = useSkeletonHandoff(loading);
+  const fadeProps = useAnimatedProps(() => ({ opacity: opacity.value }));
 
-  const gradientId = 'panelui-treemap-skeleton';
+  if (!mounted || width <= 0 || height <= 0) return null;
 
   return (
-    <G>
+    <AnimatedG animatedProps={fadeProps}>
       <Defs>
         <AnimatedLinearGradient id={gradientId} animatedProps={animatedProps} y1="0" y2="0">
           <Stop offset="0" stopColor={base} />
@@ -864,7 +882,7 @@ function TreemapChartSkeleton({ duration = 1400, color }: TreemapChartSkeletonPr
         rx={cornerRadius}
         fill={`url(#${gradientId})`}
       />
-    </G>
+    </AnimatedG>
   );
 }
 TreemapChartSkeleton.displayName = 'TreemapChart.Skeleton';
@@ -906,7 +924,7 @@ function TreemapChartLabels({
   formatValue,
   className,
 }: TreemapChartLabelsProps) {
-  const { tiles, minLabelSize, status, activeIndex, setActiveIndex } =
+  const { tiles, minLabelSize, reveal, windows, status, activeIndex, setActiveIndex } =
     useChart('TreemapChart.Labels');
   /*
    * The tiles down the ramp are drawn part-transparent, so what a label sits on
@@ -929,8 +947,10 @@ function TreemapChartLabels({
         const percent = Math.round(tile.share * 100);
         const ink = inkOn(tile.color, behind, tile.strength);
         return (
-          <Pressable
+          <TreemapChartLabel
             key={`${tile.label}-${index}`}
+            reveal={reveal}
+            window={windows[index] ?? FULL_WINDOW}
             accessibilityRole="button"
             accessibilityState={{ selected: activeIndex === index }}
             accessibilityLabel={`${tile.label}, ${format(tile.value, tile)}, ${percent} percent`}
@@ -962,12 +982,49 @@ function TreemapChartLabels({
                 {percent}%
               </Text>
             ) : null}
-          </Pressable>
+          </TreemapChartLabel>
         );
       })}
     </>
   );
 }
+
+const FULL_WINDOW = { from: 0, to: 1 };
+
+/**
+ * One tile's text, faded in on that tile's own slice of the reveal.
+ *
+ * Held at full opacity from the frame the data lands — which is what it used to
+ * do — every name and number sits at its final position over tiles that have no
+ * size yet, and the chart spends its whole entrance looking like a wireframe of
+ * itself. The label belongs to the tile, so it arrives with it.
+ */
+function TreemapChartLabel({
+  reveal,
+  window,
+  children,
+  style,
+  ...props
+}: {
+  reveal: SharedValue<number>;
+  window: { from: number; to: number };
+} & Omit<PressableProps, 'children'> & { children: ReactNode; className?: string }) {
+  const animatedStyle = useAnimatedStyle(() => {
+    const span = window.to - window.from || 1;
+    const raw = (reveal.value - window.from) / span;
+    const clamped = raw < 0 ? 0 : raw > 1 ? 1 : raw;
+    // Squared, so the text is still faint through the first half of the tile's
+    // growth and only reads once there is a tile to read it on.
+    return { opacity: clamped * clamped };
+  });
+
+  return (
+    <AnimatedPressable {...props} style={[style, animatedStyle]}>
+      {children}
+    </AnimatedPressable>
+  );
+}
+
 TreemapChartLabels.displayName = 'TreemapChart.Labels';
 TreemapChartLabels.slot = 'overlay' as const;
 

package/src/components/waterfall-chart/index.tsx

@@ -43,6 +43,7 @@ import {
   isValidElement,
   useContext,
   useEffect,
+  useId,
   useImperativeHandle,
   useMemo,
   useRef,
@@ -73,7 +74,9 @@ import {
 } from '../../primitives/finite-chart';
 import { barPath, compactNumber, type Plot } from '../../utils/chart';
 import { cn } from '../../utils/cn';
+import { useSkeletonHandoff } from '../../hooks/use-skeleton-handoff';
 
+const AnimatedG = Animated.createAnimatedComponent(G);
 const AnimatedPath = Animated.createAnimatedComponent(Path);
 const AnimatedLinearGradient = Animated.createAnimatedComponent(LinearGradient);
 
@@ -983,6 +986,9 @@ function WaterfallChartSkeleton({
   const base = color ?? (typeof token === 'string' ? token : 'rgba(128,128,128,0.2)');
   const highlightToken = useCSSVariable('--color-chart-1');
   const highlight = typeof highlightToken === 'string' ? highlightToken : FALLBACK_TOTAL;
+  // Unique per instance: a fixed id makes two of these on one screen share a
+  // gradient, and the second one to mount wins.
+  const gradientId = `panelui-waterfall-skeleton-${useId().replace(/[^a-zA-Z0-9]/g, '')}`;
 
   const sweep = useSharedValue(0);
   const reducedMotion = useReducedMotion();
@@ -1032,12 +1038,16 @@ function WaterfallChartSkeleton({
     return path;
   }, [plot, horizontal, total, barGap, barWidth, cornerRadius]);
 
-  if (!loading || !d) return null;
+  // Held through the fade rather than to the frame the data lands: the bars
+  // grow out of the stubs, and cutting the stubs at the status change leaves
+  // the panel empty until the first bar has length.
+  const { mounted, opacity } = useSkeletonHandoff(loading);
+  const fadeProps = useAnimatedProps(() => ({ opacity: opacity.value }));
 
-  const gradientId = 'panelui-waterfall-skeleton';
+  if (!mounted || !d) return null;
 
   return (
-    <G>
+    <AnimatedG animatedProps={fadeProps}>
       <Defs>
         <AnimatedLinearGradient id={gradientId} animatedProps={animatedProps} y1="0" y2="0">
           <Stop offset="0" stopColor={base} />
@@ -1046,7 +1056,7 @@ function WaterfallChartSkeleton({
         </AnimatedLinearGradient>
       </Defs>
       <Path d={d} fill={`url(#${gradientId})`} />
-    </G>
+    </AnimatedG>
   );
 }
 WaterfallChartSkeleton.displayName = 'WaterfallChart.Skeleton';

package/src/hooks/index.ts

@@ -30,6 +30,11 @@ export {
   type UseRevealProgressOptions,
   type UseRevealProgressResult,
 } from './use-reveal-progress';
+export {
+  useSkeletonHandoff,
+  SKELETON_FADE,
+  type UseSkeletonHandoffResult,
+} from './use-skeleton-handoff';
 export {
   useScrollSections,
   type UseScrollSectionsOptions,

package/src/hooks/use-scroll-sections.ts

@@ -24,7 +24,7 @@
  * <SectionRail value={sections.active} onValueChange={sections.scrollTo}>…</SectionRail>
  * ```
  */
-import { useCallback, useMemo, useRef, useState } from 'react';
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import type {
   LayoutChangeEvent,
   NativeScrollEvent,
@@ -54,6 +54,7 @@ export interface UseScrollSectionsResult {
   /** Spread onto the ScrollView. */
   scrollProps: {
     onScroll: (event: NativeSyntheticEvent<NativeScrollEvent>) => void;
+    onMomentumScrollEnd: () => void;
     scrollEventThrottle: number;
   };
   /** `onLayout` for a section's wrapper: `onLayout={measure(id)}`. */
@@ -62,6 +63,13 @@ export interface UseScrollSectionsResult {
   scrollTo: (id: string) => void;
 }
 
+/**
+ * How long a programmatic scroll is given to arrive before the scroll handler
+ * starts believing positions again. Only reached when the scroll had nowhere to
+ * go and no momentum end ever fires.
+ */
+const JUMP_TIMEOUT = 900;
+
 export function useScrollSections({
   ids,
   offset = 120,
@@ -70,6 +78,7 @@ export function useScrollSections({
 }: UseScrollSectionsOptions): UseScrollSectionsResult {
   const ref = useRef<ScrollView | null>(null);
   const offsets = useRef<Record<string, number>>({});
+  const settle = useRef<ReturnType<typeof setTimeout> | null>(null);
   const [active, setActive] = useState<string | undefined>(ids[0]);
 
   // Read inside the scroll handler, which must not be re-created on every
@@ -84,8 +93,23 @@ export function useScrollSections({
     []
   );
 
+  /*
+   * The section a `scrollTo` is travelling to, while it is still travelling.
+   *
+   * An animated scroll passes every section between here and there, and the
+   * scroll handler cannot tell those apart from sections the reader arrived at
+   * themselves — so it reported each one as active in turn. Downstream that is
+   * a real change of section every 16ms: a rail lighting up rows nobody chose,
+   * a haptic for each, and a jump that ends somewhere the reader watched it
+   * pass through. None of it happened; the reader asked for one section.
+   */
+  const jumpingTo = useRef<string | null>(null);
+
   const onScroll = useCallback(
     (event: NativeSyntheticEvent<NativeScrollEvent>) => {
+      // Mid-jump, the position is the animation's and not the reader's.
+      if (jumpingTo.current !== null) return;
+
       const { contentOffset, layoutMeasurement, contentSize } = event.nativeEvent;
       const list = idsRef.current;
       if (!list.length) return;
@@ -112,15 +136,40 @@ export function useScrollSections({
     (id: string) => {
       const top = offsets.current[id];
       if (top === undefined) return;
+      jumpingTo.current = id;
+      if (settle.current) clearTimeout(settle.current);
+      /*
+       * A backstop, not the normal way out. `onMomentumScrollEnd` does not fire
+       * for a scroll that had nowhere to go — a jump to the section already on
+       * screen — and without this the handler would stay muted for good.
+       */
+      settle.current = setTimeout(() => {
+        jumpingTo.current = null;
+      }, JUMP_TIMEOUT);
       setActive(id);
       ref.current?.scrollTo({ y: Math.max(top - scrollPadding, 0), animated: true });
     },
     [scrollPadding]
   );
 
+  const onMomentumScrollEnd = useCallback(() => {
+    if (settle.current) {
+      clearTimeout(settle.current);
+      settle.current = null;
+    }
+    jumpingTo.current = null;
+  }, []);
+
+  useEffect(
+    () => () => {
+      if (settle.current) clearTimeout(settle.current);
+    },
+    []
+  );
+
   const scrollProps = useMemo(
-    () => ({ onScroll, scrollEventThrottle: 16 }),
-    [onScroll]
+    () => ({ onScroll, onMomentumScrollEnd, scrollEventThrottle: 16 }),
+    [onScroll, onMomentumScrollEnd]
   );
 
   return { ref, active, scrollProps, measure, scrollTo };

package/src/hooks/use-skeleton-handoff.ts

@@ -0,0 +1,69 @@
+/**
+ * Keeps a chart's placeholder on screen a beat past the data arriving, and
+ * dissolves it while the real marks grow in.
+ *
+ * A skeleton cut at the exact frame `status` flips leaves the plot empty: the
+ * placeholder is gone and the reveal has not started, so there is a blank frame
+ * between two states that were both supposed to show something. Outliving the
+ * status change by the length of the fade is what closes that gap, and it is
+ * why the loading state reads as *becoming* the chart rather than as being
+ * replaced by it.
+ *
+ * The fade runs on the UI thread; the unmount is scheduled back once, at the
+ * end, so nothing re-renders per frame.
+ *
+ * ```tsx
+ * const { mounted, opacity } = useSkeletonHandoff(status === 'loading');
+ * const animatedProps = useAnimatedProps(() => ({ opacity: opacity.value }));
+ * if (!mounted) return null;
+ * return <AnimatedG animatedProps={animatedProps}>{…}</AnimatedG>;
+ * ```
+ */
+import { useEffect, useState } from 'react';
+import {
+  runOnJS,
+  useReducedMotion,
+  useSharedValue,
+  withTiming,
+  type SharedValue,
+} from 'react-native-reanimated';
+
+/** Milliseconds for a placeholder to dissolve once the data arrives. */
+export const SKELETON_FADE = 220;
+
+export interface UseSkeletonHandoffResult {
+  /** True while the placeholder should render — through the fade, not just the wait. */
+  mounted: boolean;
+  /** The placeholder's opacity, `1` while loading and tweened to `0` after. */
+  opacity: SharedValue<number>;
+}
+
+export function useSkeletonHandoff(
+  loading: boolean,
+  duration: number = SKELETON_FADE
+): UseSkeletonHandoffResult {
+  const opacity = useSharedValue(loading ? 1 : 0);
+  // Mounted a beat longer than `loading`, so there is something to fade.
+  const [mounted, setMounted] = useState(loading);
+  const reducedMotion = useReducedMotion();
+
+  useEffect(() => {
+    if (loading) {
+      opacity.value = 1;
+      setMounted(true);
+      return;
+    }
+    // Reduced motion still wants the placeholder gone; it is the dissolve that
+    // is the motion, not the disappearance.
+    if (reducedMotion) {
+      opacity.value = 0;
+      setMounted(false);
+      return;
+    }
+    opacity.value = withTiming(0, { duration }, (finished) => {
+      if (finished) runOnJS(setMounted)(false);
+    });
+  }, [loading, reducedMotion, duration, opacity]);
+
+  return { mounted, opacity };
+}

package/src/index.ts

@@ -744,6 +744,7 @@ export {
 export {
   Marquee,
   type MarqueeProps,
+  type MarqueeGroupProps,
   type MarqueeDirection,
 } from './components/marquee';
 export {
@@ -843,6 +844,14 @@ export {
   type PostVote,
 } from './components/post';
 export { Progress, type ProgressProps } from './components/progress';
+export {
+  ProgressButton,
+  useProgressButton,
+  type ProgressButtonProps,
+  type ProgressButtonLabelProps,
+  type ProgressButtonVariant,
+  type ProgressButtonSize,
+} from './components/progress-button';
 export {
   QRCode,
   type QRCodeProps,
@@ -1070,6 +1079,7 @@ export {
   type SplitViewPaneProps,
   type SplitViewDragAreaProps,
   type SplitViewHandleProps,
+  type SplitViewVariant,
 } from './components/split-view';
 export {
   Steps,

package/src/native/index.ts

@@ -39,6 +39,23 @@ interface NativeUIModule {
      * height is reported back.
      */
     matchContents?: boolean | { vertical?: boolean; horizontal?: boolean };
+    /**
+     * Which safe areas the host lets the platform inset its content for.
+     *
+     * Every host here passes `keyboard`, and it is not optional. A host is a
+     * hosting controller, and a hosting controller insets its content for the
+     * keyboard by default — so a control docked above the keyboard has its
+     * content moved *inside* the box React Native gave it, over whatever is
+     * above it, while React Native's own layout says nothing has moved. That
+     * is a composer whose buttons sit on its text until the next layout pass
+     * puts them back.
+     *
+     * React Native owns the layout of everything in this library, so a
+     * platform that moves content inside a box we positioned is never right.
+     * `keyboard` and not `all`: the notch and the home indicator are the
+     * platform's business and stay its business.
+     */
+    ignoreSafeArea?: 'all' | 'container' | 'keyboard';
     style?: unknown;
     [key: string]: unknown;
   }>;