panelui-native 0.13.0 → 0.16.0

package/src/hooks/use-reveal-progress.ts

@@ -0,0 +1,106 @@
+/**
+ * useRevealProgress — how far an element has travelled through the viewport.
+ *
+ * The number every scroll-driven effect is really made of: `0` before the
+ * element has arrived, `1` once it has passed, and a smooth scrub between the
+ * two. What an effect *does* with it — recolour, fade, zoom, step through
+ * frames — is the only part that differs.
+ *
+ * The window is set the way a scroll-trigger's is: `start` and `end` are
+ * positions down the viewport, as fractions of its height. Progress is `0`
+ * while the element's **top** is still below `start`, and reaches `1` when its
+ * **bottom** passes `end` — so a tall block scrubs across its own height rather
+ * than snapping the moment its first line appears.
+ *
+ * ```tsx
+ * const { ref, progress } = useRevealProgress({ start: 0.9, end: 0.5 });
+ *
+ * <Animated.View ref={ref} style={useAnimatedStyle(() => ({
+ *   opacity: progress.value,
+ * }))} />
+ * ```
+ *
+ * The element is measured on the UI thread whenever the scroll position
+ * changes — not every frame, and not once at layout. Once is wrong the moment
+ * anything above it resizes; every frame is a measurement pass for a value that
+ * only changes when the scroller moves.
+ */
+import { useWindowDimensions, type View } from 'react-native';
+import {
+  measure,
+  useAnimatedRef,
+  useDerivedValue,
+  type AnimatedRef,
+  type SharedValue,
+} from 'react-native-reanimated';
+import { useScrollProgress } from '../primitives/scroll-progress';
+
+export interface UseRevealProgressOptions {
+  /**
+   * Where down the viewport the element's top sits when progress is `0`, as a
+   * fraction of the viewport height. `0.9` starts it just before it appears.
+   */
+  start?: number;
+  /**
+   * Where down the viewport the element's bottom sits when progress reaches
+   * `1`. Smaller values mean a longer scrub.
+   */
+  end?: number;
+  /**
+   * Drive the effect from a value of your own instead of from the scroll
+   * position. Anything passed here is used as-is and nothing is measured.
+   */
+  progress?: SharedValue<number>;
+  /** Set false to hold progress at `1`, as though the element had passed. */
+  enabled?: boolean;
+}
+
+export interface UseRevealProgressResult {
+  /** Attach to the element whose travel drives the effect. */
+  ref: AnimatedRef<View>;
+  /** `0` before, `1` after, scrubbed between. */
+  progress: SharedValue<number>;
+}
+
+export function useRevealProgress({
+  start = 0.9,
+  end = 0.5,
+  progress: external,
+  enabled = true,
+}: UseRevealProgressOptions = {}): UseRevealProgressResult {
+  const ref = useAnimatedRef<View>();
+  const scroll = useScrollProgress();
+  const { height: windowHeight } = useWindowDimensions();
+
+  const offset = scroll?.offset;
+  const viewportValue = scroll?.viewport;
+  const topValue = scroll?.top;
+
+  const derived = useDerivedValue(() => {
+    if (!enabled) return 1;
+
+    // Read so the scroll position is a real dependency of this value. The
+    // element's own position is not observable, and the scroller moving
+    // underneath it is the only thing that changes it while it is on screen.
+    const scrolled = offset ? offset.value : 0;
+    const viewport = viewportValue?.value || windowHeight;
+    const viewportTop = topValue?.value ?? 0;
+    if (viewport <= 0 || Number.isNaN(scrolled)) return 0;
+
+    const frame = measure(ref);
+    if (!frame || frame.height <= 0) return 0;
+
+    const top = frame.pageY - viewportTop;
+    const from = start * viewport;
+    const to = end * viewport - frame.height;
+    const span = from - to;
+    if (span <= 0) return top <= to ? 1 : 0;
+
+    const value = (from - top) / span;
+    return value < 0 ? 0 : value > 1 ? 1 : value;
+  });
+
+  // An external value is passed straight through, so a caller driving the
+  // effect by hand never pays for the measurement.
+  return { ref, progress: external ?? derived };
+}

package/src/icons/index.tsx

@@ -510,3 +510,39 @@ export function PaperclipIcon({ size = 16, color, ...props }: IconProps) {
     </Svg>
   );
 }
+
+/** A capsule on a stand — a microphone, for anything voice. */
+export function MicIcon({ size = 16, color, ...props }: IconProps) {
+  const resolved = useResolvedColor(color, '#737373');
+  return (
+    <Svg width={size} height={size} viewBox="0 0 24 24" fill="none" {...props}>
+      <Path
+        d="M12 3a3 3 0 0 0-3 3v6a3 3 0 0 0 6 0V6a3 3 0 0 0-3-3zM5 11v1a7 7 0 0 0 14 0v-1M12 19v3"
+        stroke={resolved}
+        strokeWidth={2}
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      />
+    </Svg>
+  );
+}
+
+/** A filled triangle — start playback. */
+export function PlayIcon({ size = 16, color, ...props }: IconProps) {
+  const resolved = useResolvedColor(color, '#737373');
+  return (
+    <Svg width={size} height={size} viewBox="0 0 24 24" fill="none" {...props}>
+      <Path d="M7 4.5v15l13-7.5z" fill={resolved} stroke={resolved} strokeWidth={2} strokeLinejoin="round" />
+    </Svg>
+  );
+}
+
+/** Two filled bars — hold playback where it is. */
+export function PauseIcon({ size = 16, color, ...props }: IconProps) {
+  const resolved = useResolvedColor(color, '#737373');
+  return (
+    <Svg width={size} height={size} viewBox="0 0 24 24" fill="none" {...props}>
+      <Path d="M8 5h2v14H8zM14 5h2v14h-2z" fill={resolved} stroke={resolved} strokeWidth={1.5} strokeLinejoin="round" />
+    </Svg>
+  );
+}

package/src/index.ts

@@ -25,6 +25,12 @@ export {
   AnimatedPressable,
   type AnimatedPressableProps,
 } from './primitives/animated-pressable';
+export {
+  ScrollProgress,
+  useScrollProgress,
+  type ScrollProgressProps,
+  type ScrollProgressValue,
+} from './primitives/scroll-progress';
 
 // Native UI bridge
 export { hasNativeUI } from './native';
@@ -86,6 +92,18 @@ export {
   type DialogProps,
   type DialogContentProps,
 } from './components/dialog';
+export {
+  Soundwave,
+  type SoundwaveProps,
+  type SoundwaveState,
+  type SoundwaveVariant,
+} from './components/soundwave';
+export {
+  Direction,
+  useDirection,
+  type DirectionProps,
+  type DirectionValue,
+} from './components/direction';
 export {
   Frame,
   type FrameProps,
@@ -95,6 +113,22 @@ export {
   type FrameSectionProps,
   type FrameVariant,
 } from './components/frame';
+export {
+  HeatmapChart,
+  useHeatmapChart,
+  buildHeatmapCalendar,
+  type HeatmapChartProps,
+  type HeatmapCellsProps,
+  type HeatmapSeparatorProps,
+  type HeatmapXAxisProps,
+  type HeatmapYAxisProps,
+  type HeatmapTooltipProps,
+  type HeatmapLegendProps,
+  type HeatmapColumn,
+  type HeatmapBin,
+  type HeatmapCell,
+  type HeatmapLayout,
+} from './components/heatmap-chart';
 export {
   Select,
   type SelectProps,
@@ -222,6 +256,22 @@ export {
 } from './components/scroll-fade';
 export { Separator, type SeparatorProps } from './components/separator';
 export { Shimmer, type ShimmerProps } from './components/shimmer';
+export {
+  ScrollText,
+  type ScrollTextProps,
+  type ScrollTextEffect,
+  type ScrollTextSplit,
+} from './components/scroll-text';
+export {
+  ScrollCanvas,
+  type ScrollCanvasProps,
+  type ScrollCanvasEffect,
+} from './components/scroll-canvas';
+export {
+  ThinkingOrb,
+  type ThinkingOrbProps,
+  type ThinkingOrbState,
+} from './components/thinking-orb';
 export { Skeleton, type SkeletonProps } from './components/skeleton';
 export { Slider, type SliderProps } from './components/slider';
 export { Spinner, type SpinnerProps } from './components/spinner';
@@ -287,9 +337,12 @@ export {
   IconColorProvider,
   InfoIcon,
   ImageIcon,
+  MicIcon,
   MoonIcon,
   PackageIcon,
   PaperclipIcon,
+  PauseIcon,
+  PlayIcon,
   PlusSquareIcon,
   ReceiptIcon,
   SearchIcon,

package/src/native/index.ts

@@ -28,13 +28,15 @@ interface NativeUIModule {
     /**
      * Whether the host resizes itself to the platform content.
      *
-     * Every control here gives the host an explicit height instead, and takes
-     * its width from ordinary layout. The measurement arrives a frame late and
-     * again whenever the platform's content changes, so a host left to work
-     * its own size out renders at nothing and then jumps — on first paint, and
-     * again on first press. The per-axis form does not help; the answer is not
-     * to ask. Only the natively-presented sheet still uses it, where the host
-     * is a zero-size anchor rather than the control itself.
+     * This is on for every control here, and it is the whole answer to the
+     * jump. Sizing the *host* and leaving the control unsized inside it hands
+     * the platform a box it never agreed to: it lays out against its own
+     * intrinsic size, and settles into the box on the first thing that forces
+     * a second pass — which for a button is the first press.
+     *
+     * The per-axis form is for a control with no intrinsic width, like a
+     * slider or a picker: the width comes from ordinary layout and only the
+     * height is reported back.
      */
     matchContents?: boolean | { vertical?: boolean; horizontal?: boolean };
     style?: unknown;
@@ -50,6 +52,12 @@ interface NativeUIModule {
     matchContents?: boolean;
     style?: unknown;
   }>;
+  /**
+   * `style` here is not a React Native style — it is the small portable subset
+   * (`width`, `height`, padding, `backgroundColor`, `borderRadius`, `opacity`)
+   * that the toolkit compiles into real SwiftUI and Compose modifiers. It is
+   * how a control is given a definite size without the host having to guess.
+   */
   Button: ComponentType<Record<string, unknown>>;
   Switch: ComponentType<Record<string, unknown>>;
   Slider: ComponentType<Record<string, unknown>>;

package/src/primitives/keyboard-avoider.tsx

@@ -1,14 +1,32 @@
 /**
- * KeyboardAvoider — a view that lifts itself just clear of the keyboard.
+ * KeyboardAvoider — a view that keeps itself clear of the keyboard.
  *
  * A thin wrapper over `useKeyboardAvoidance` for the common case of "keep this
  * box visible", so a form does not have to wire the ref, layout handler and
  * animated style by hand.
+ *
+ * ```tsx
+ * // In the flow of a scrolling page: lifts by the overlap, follows the scroll.
+ * <KeyboardAvoider active={focused}>…</KeyboardAvoider>
+ *
+ * // Pinned to the bottom edge: rides the keyboard up and back down.
+ * <KeyboardAvoider
+ *   mode="dock"
+ *   bottomInset={insets.bottom}
+ *   className="absolute left-0 right-0"
+ *   style={{ bottom: insets.bottom + 16 }}
+ * >
+ *   …
+ * </KeyboardAvoider>
+ * ```
  */
 import type { ReactNode } from 'react';
 import type { ViewProps } from 'react-native';
 import Animated from 'react-native-reanimated';
-import { useKeyboardAvoidance } from '../hooks/use-keyboard-avoidance';
+import {
+  useKeyboardAvoidance,
+  type KeyboardAvoidanceMode,
+} from '../hooks/use-keyboard-avoidance';
 
 export interface KeyboardAvoiderProps extends ViewProps {
   className?: string;
@@ -21,8 +39,19 @@ export interface KeyboardAvoiderProps extends ViewProps {
    * screen stay put.
    */
   active?: boolean;
-  /** Gap to keep between the content's bottom edge and the keyboard. */
+  /**
+   * `lift` moves in-flow content up by its overlap with the keyboard and keeps
+   * tracking it as the page scrolls. `dock` travels with the keyboard, for a
+   * bar already pinned near the bottom edge.
+   */
+  mode?: KeyboardAvoidanceMode;
+  /** Gap to keep between the content's bottom edge and the keyboard. `lift` only. */
   offset?: number;
+  /**
+   * How far above the bottom edge the bar already sits — usually the safe area
+   * inset it is positioned by. `dock` only.
+   */
+  bottomInset?: number;
   children?: ReactNode;
 }
 
@@ -30,13 +59,21 @@ export function KeyboardAvoider({
   className,
   enabled = true,
   active = true,
+  mode = 'lift',
   offset = 16,
+  bottomInset = 0,
   children,
   style,
   onLayout,
   ...props
 }: KeyboardAvoiderProps) {
-  const avoidance = useKeyboardAvoidance({ enabled, active, offset });
+  const avoidance = useKeyboardAvoidance({
+    enabled,
+    active,
+    mode,
+    offset,
+    bottomInset,
+  });
 
   return (
     <Animated.View

package/src/primitives/scroll-progress.tsx

@@ -0,0 +1,167 @@
+/**
+ * ScrollProgress — publishes a scroll container's position so children can
+ * animate against it.
+ *
+ * Scroll-driven effects all need the same two numbers: where the scroller is,
+ * and how tall its viewport is. Every component that wanted them measuring for
+ * itself would mean one scroll listener per effect and one measurement pass per
+ * effect per frame, for two values that are the same for all of them.
+ *
+ * It wraps the scroll view you already have rather than replacing it — the
+ * child is cloned with an animated scroll handler composed onto it, the same
+ * way `ScrollFade` does — so a `FlatList`, a `SectionList` or your own
+ * scrollable all work, and nothing has to be rewritten to adopt it.
+ *
+ * ```tsx
+ * <ScrollProgress>
+ *   <ScrollView>
+ *     <ScrollText>…</ScrollText>
+ *   </ScrollView>
+ * </ScrollProgress>
+ * ```
+ *
+ * Both values are shared values, so the whole chain from scroll event to
+ * animated style stays on the UI thread and nothing re-renders as you scroll.
+ */
+import {
+  Children,
+  createContext,
+  isValidElement,
+  useContext,
+  useMemo,
+  useRef,
+  type ComponentType,
+  type ReactElement,
+  type ReactNode,
+} from 'react';
+import { View, type LayoutChangeEvent, type ViewProps } from 'react-native';
+import Animated, {
+  useAnimatedScrollHandler,
+  useComposedEventHandler,
+  useSharedValue,
+  type AnimatedScrollViewProps,
+  type SharedValue,
+} from 'react-native-reanimated';
+
+export interface ScrollProgressValue {
+  /** Distance scrolled, in pixels. */
+  offset: SharedValue<number>;
+  /** Height of the visible area. */
+  viewport: SharedValue<number>;
+  /** Total height of the content. */
+  content: SharedValue<number>;
+  /**
+   * Window-space top edge of the scroller. What turns an element's measured
+   * `pageY` into a position inside *this* viewport rather than the screen's —
+   * they differ by whatever sits above the scroller, and assuming they do not
+   * is why scroll effects drift under a header.
+   */
+  top: SharedValue<number>;
+}
+
+const ScrollProgressContext = createContext<ScrollProgressValue | null>(null);
+
+/**
+ * The nearest enclosing scroll container's position, or `null` outside one.
+ *
+ * It returns null rather than throwing because every consumer of this also
+ * takes an explicit `progress` prop — a component that can be driven by hand
+ * should not insist on a provider it does not need.
+ */
+export function useScrollProgress(): ScrollProgressValue | null {
+  return useContext(ScrollProgressContext);
+}
+
+interface ScrollableProps {
+  onScroll?: AnimatedScrollViewProps['onScroll'];
+  onLayout?: (event: LayoutChangeEvent) => void;
+  onContentSizeChange?: (width: number, height: number) => void;
+  scrollEventThrottle?: number;
+}
+
+export interface ScrollProgressProps extends ViewProps {
+  className?: string;
+  /** Exactly one scrollable — a ScrollView, FlatList, or anything like them. */
+  children?: ReactNode;
+}
+
+export function ScrollProgress({ className, children, ...props }: ScrollProgressProps) {
+  const offset = useSharedValue(0);
+  const viewport = useSharedValue(0);
+  const content = useSharedValue(0);
+  const top = useSharedValue(0);
+  const hostRef = useRef<View>(null);
+
+  const child = Children.only(children) as ReactElement<ScrollableProps>;
+
+  // Reanimated can only drive a scroll handler on an animated component, and
+  // what was passed in is not necessarily `Animated.ScrollView`. Keyed on the
+  // element *type*, not the element: rebuilding the wrapper would remount the
+  // list and lose its scroll position.
+  const childType = isValidElement(child)
+    ? (child.type as ComponentType<ScrollableProps>)
+    : null;
+  const AnimatedScrollable = useMemo(
+    () => (childType ? Animated.createAnimatedComponent(childType) : null),
+    [childType]
+  );
+
+  const scrollHandler = useAnimatedScrollHandler({
+    onScroll: (event) => {
+      offset.value = event.contentOffset.y;
+      viewport.value = event.layoutMeasurement.height;
+      content.value = event.contentSize.height;
+    },
+  });
+
+  // A consumer's own `onScroll` is composed rather than dropped — but since the
+  // child is now an animated component, it has to be an animated handler too.
+  const onScroll = useComposedEventHandler([
+    scrollHandler,
+    (child.props.onScroll as typeof scrollHandler | undefined) ?? null,
+  ]);
+
+  // Taken up front as well as on scroll, so anything already on screen animates
+  // from the first frame instead of waiting for the first scroll event.
+  const onLayout = (event: LayoutChangeEvent) => {
+    viewport.value = event.nativeEvent.layout.height;
+    // A frame later than onLayout on both platforms, because measureInWindow
+    // is only meaningful once the view is attached and positioned.
+    requestAnimationFrame(() => {
+      hostRef.current?.measureInWindow((_x, y) => {
+        if (y >= 0) top.value = y;
+      });
+    });
+    child.props.onLayout?.(event);
+  };
+
+  const onContentSizeChange = (width: number, height: number) => {
+    content.value = height;
+    child.props.onContentSizeChange?.(width, height);
+  };
+
+  const value = useMemo<ScrollProgressValue>(
+    () => ({ offset, viewport, content, top }),
+    [offset, viewport, content, top]
+  );
+
+  return (
+    <ScrollProgressContext.Provider value={value}>
+      <View {...props} ref={hostRef} className={className}>
+        {AnimatedScrollable && isValidElement(child) ? (
+          <AnimatedScrollable
+            {...child.props}
+            onScroll={onScroll}
+            onLayout={onLayout}
+            onContentSizeChange={onContentSizeChange}
+            scrollEventThrottle={child.props.scrollEventThrottle ?? 16}
+          />
+        ) : (
+          child
+        )}
+      </View>
+    </ScrollProgressContext.Provider>
+  );
+}
+
+ScrollProgress.displayName = 'ScrollProgress';