panelui-native 0.13.0 → 0.14.0

package/src/hooks/index.ts

@@ -17,9 +17,15 @@ export {
 export { useKeyboard, type UseKeyboardResult } from './use-keyboard';
 export {
   useKeyboardAvoidance,
+  type KeyboardAvoidanceMode,
   type UseKeyboardAvoidanceOptions,
   type UseKeyboardAvoidanceResult,
 } from './use-keyboard-avoidance';
+export {
+  useRevealProgress,
+  type UseRevealProgressOptions,
+  type UseRevealProgressResult,
+} from './use-reveal-progress';
 export {
   useScrollSections,
   type UseScrollSectionsOptions,

package/src/hooks/use-keyboard-avoidance.ts

@@ -1,11 +1,24 @@
 /**
- * useKeyboardAvoidance — lift an element just clear of the software keyboard.
+ * useKeyboardAvoidance — keep an element clear of the software keyboard.
  *
  * `KeyboardAvoidingView` shifts or pads an entire subtree by the full keyboard
  * height regardless of where the element actually sits, which over-scrolls
  * short forms and does nothing useful for an element already above the fold.
- * This measures the element and moves it by exactly the overlap — and not at
- * all when there is none.
+ * This works from the element's own position instead.
+ *
+ * Two modes, because "get out of the keyboard's way" and "ride the keyboard"
+ * are different jobs:
+ *
+ * - **`lift`** (default) — for a field sitting in the page's flow. The element
+ *   is measured every frame while the keyboard is up and moved by exactly the
+ *   current overlap, so it follows the scroll: scroll it clear and the lift
+ *   decays to nothing, scroll it back under and the lift returns. Measuring
+ *   once and holding the result is what leaves a field hanging out of its own
+ *   slot the moment the page moves underneath it.
+ * - **`dock`** — for an absolutely-positioned composer, toolbar or search bar
+ *   pinned near the bottom edge. There is nothing to measure: the element
+ *   simply travels with the keyboard, less whatever bottom inset it is already
+ *   sitting above.
  *
  * ## Install the keyboard controller
  *
@@ -31,19 +44,34 @@
  * </Animated.View>
  * ```
  */
-import { useCallback, useEffect } from 'react';
+import { useCallback, useEffect, useState } from 'react';
 import { useWindowDimensions, type LayoutChangeEvent, type View } from 'react-native';
 import {
   measure,
+  runOnJS,
   useAnimatedKeyboard,
   useAnimatedReaction,
   useAnimatedRef,
   useAnimatedStyle,
+  useFrameCallback,
   useSharedValue,
+  withTiming,
   type AnimatedRef,
   type SharedValue,
 } from 'react-native-reanimated';
 
+/** How long a lifted element takes to settle back after it stops being active. */
+const SETTLE_DURATION = 200;
+
+/**
+ * Movement below this is dropped. The element's measured position already
+ * includes the translation applied on the previous frame, so the loop reads
+ * its own output — a dead band keeps sub-pixel rounding from making it hum.
+ */
+const EPSILON = 0.5;
+
+export type KeyboardAvoidanceMode = 'lift' | 'dock';
+
 export interface UseKeyboardAvoidanceOptions {
   /** Set false to leave the element where it is. */
   enabled?: boolean;
@@ -56,14 +84,26 @@ export interface UseKeyboardAvoidanceOptions {
    * is tapped, and they all arrive at the same place on top of each other.
    */
   active?: boolean;
-  /** Gap to keep between the element's bottom edge and the keyboard. */
+  /**
+   * `lift` moves an in-flow element by its overlap with the keyboard and
+   * tracks it as the page scrolls. `dock` travels with the keyboard outright,
+   * for an element already pinned to the bottom edge.
+   */
+  mode?: KeyboardAvoidanceMode;
+  /** Gap to keep between the element's bottom edge and the keyboard. `lift` only. */
   offset?: number;
+  /**
+   * How far above the bottom edge the element already sits — usually the safe
+   * area inset it is offset by. Subtracted from the travel, since the keyboard
+   * covers that strip too. `dock` only.
+   */
+  bottomInset?: number;
 }
 
 export interface UseKeyboardAvoidanceResult {
   /** Attach to the element that should stay visible. */
   ref: AnimatedRef<View>;
-  /** Attach to the same element — it is how the resting position is measured. */
+  /** Attach to the same element, so a re-layout at rest cannot leave it offset. */
   onLayout: (event: LayoutChangeEvent) => void;
   /** Apply to the same element. */
   animatedStyle: ReturnType<typeof useAnimatedStyle>;
@@ -110,96 +150,102 @@ export function hasKeyboardController(): boolean {
 export function useKeyboardAvoidance({
   enabled = true,
   active = true,
+  mode = 'lift',
   offset = 16,
+  bottomInset = 0,
 }: UseKeyboardAvoidanceOptions = {}): UseKeyboardAvoidanceResult {
   const ref = useAnimatedRef<View>();
   const rawHeight = useKeyboardHeight();
   const { height: screenHeight } = useWindowDimensions();
 
-  /** Window-space bottom edge of the element with no translation applied. */
-  const restingBottom = useSharedValue(0);
+  /** The translation currently applied, in pixels. Zero or negative. */
+  const translation = useSharedValue(0);
 
-  // `active` is a plain prop and the reaction below is a worklet, so it is
-  // mirrored rather than closed over — written in an effect, because touching
-  // a shared value during render is a Reanimated strict-mode violation.
+  // `active` is a plain prop and the worklets below cannot read props, so it is
+  // mirrored — written in an effect, because touching a shared value during
+  // render is a Reanimated strict-mode violation.
   const isActive = useSharedValue(active && enabled);
   useEffect(() => {
     isActive.value = active && enabled;
   }, [active, enabled, isActive]);
 
   /*
-   * The resting position is taken the moment this element becomes the one that
-   * should move, on the UI thread, rather than once at layout time.
+   * The whole of `lift` is this callback, and it runs only while the element is
+   * the active one *and* the keyboard is up — see the reaction below.
    *
-   * Measuring at layout is wrong in two ways that both show up as "avoidance
-   * does nothing". A field inside an overlay is laid out before the overlay
-   * knows where it goes — it is parked off-screen at that point, so the stored
-   * position is a large negative number that is nonetheless non-zero, and the
-   * arithmetic below happily concludes there is no overlap. And a field that
-   * has scrolled since it was laid out is measured where it used to be.
+   * The element is re-measured every frame rather than once, because every
+   * interesting thing that moves it happens after the keyboard opens: the page
+   * scrolls, a sheet settles, content above it grows. A position captured at
+   * the moment of focus is right for exactly one frame, and the element spends
+   * the rest of the time holding an offset that belongs to where it used to be.
    *
-   * Keying off "active and the keyboard is up" rather than off the keyboard
-   * alone matters for the second field you tap: moving straight from one field
-   * to another never closes the keyboard, so there is no opening to react to,
-   * and a hook watching only the keyboard would never measure it.
-   *
-   * At the instant it becomes active the element has no translation applied,
-   * so what is measured then is the honest resting position.
+   * What is measured already includes the translation applied on the previous
+   * frame, so that is subtracted back out to recover the honest resting edge.
+   * Without it the callback would chase its own output down the screen.
+   */
+  const track = useFrameCallback(() => {
+    'worklet';
+    const keyboardHeight = Math.abs(rawHeight.value);
+    if (keyboardHeight === 0) return;
+
+    const frame = measure(ref);
+    if (!frame || frame.height <= 0) return;
+
+    const restingBottom = frame.pageY + frame.height - translation.value;
+    const keyboardTop = screenHeight - keyboardHeight;
+    const overlap = restingBottom + offset - keyboardTop;
+    const next = overlap > 0 ? -overlap : 0;
+
+    if (Math.abs(next - translation.value) > EPSILON) translation.value = next;
+  }, false);
+
+  /*
+   * Tracking is switched on the transition rather than left running, so a
+   * screen full of fields costs nothing until one of them is being typed into.
+   * `setActive` lives on the JS side, hence the hop.
    */
+  const [tracking, setTracking] = useState(false);
   useAnimatedReaction(
     () => isActive.value && Math.abs(rawHeight.value) > 0,
-    (shouldLift, wasLifting) => {
-      if (shouldLift === wasLifting) return;
-
-      if (!shouldLift) {
-        // Forget it, so the next time round measures wherever the element has
-        // got to in the meantime.
-        restingBottom.value = 0;
-        return;
-      }
-
-      const frame = measure(ref);
-      if (frame && frame.height > 0 && frame.pageY >= 0) {
-        restingBottom.value = frame.pageY + frame.height;
+    (shouldTrack, wasTracking) => {
+      if (shouldTrack === wasTracking) return;
+      runOnJS(setTracking)(shouldTrack);
+
+      // Moving straight from one field to another never closes the keyboard,
+      // so the field being left has nothing to follow back down — it is sent
+      // home explicitly, or it stays hanging where the keyboard left it.
+      if (!shouldTrack && translation.value !== 0) {
+        translation.value = withTiming(0, { duration: SETTLE_DURATION });
       }
     }
   );
 
-  const seed = useCallback(() => {
-    // Skipped only when a position is already known and the keyboard is up —
-    // the element is lifted then, and this would store the lifted position as
-    // the resting one. With no position yet there is no translation to undo,
-    // so measuring is safe whatever the keyboard is doing.
-    if (restingBottom.value !== 0 && Math.abs(rawHeight.value) > 0) return;
-
-    ref.current?.measureInWindow((_x, y, _width, height) => {
-      if (height > 0 && y >= 0) restingBottom.value = y + height;
-    });
-  }, [ref, rawHeight, restingBottom]);
+  const { setActive } = track;
+  useEffect(() => {
+    setActive(tracking && mode === 'lift');
+    return () => setActive(false);
+  }, [tracking, mode, setActive]);
 
   const onLayout = useCallback(
     (_event: LayoutChangeEvent) => {
-      // Covers the case the reaction above cannot: a keyboard that is already
-      // up when this element mounts, where there is no transition to react to.
-      // measureInWindow is only meaningful once the view is attached and
-      // positioned, which is a frame later than onLayout on both platforms.
-      requestAnimationFrame(seed);
+      // A layout pass while the element is at rest means its slot moved for
+      // some reason other than the keyboard. Anything left over from the last
+      // lift belongs to the old slot.
+      if (!tracking && translation.value !== 0) translation.value = 0;
     },
-    [seed]
+    [tracking, translation]
   );
 
   const animatedStyle = useAnimatedStyle(() => {
-    // Both sources are normalised to a positive height here.
-    const keyboardHeight = Math.abs(rawHeight.value);
-
-    if (!isActive.value || keyboardHeight === 0 || restingBottom.value === 0) {
-      return { transform: [{ translateY: 0 }] };
+    if (mode === 'dock') {
+      if (!isActive.value) return { transform: [{ translateY: 0 }] };
+      // Both sources are normalised to a positive height here.
+      const keyboardHeight = Math.abs(rawHeight.value);
+      const travel = Math.max(keyboardHeight - bottomInset, 0);
+      return { transform: [{ translateY: -travel }] };
     }
 
-    const keyboardTop = screenHeight - keyboardHeight;
-    const overlap = restingBottom.value + offset - keyboardTop;
-
-    return { transform: [{ translateY: overlap > 0 ? -overlap : 0 }] };
+    return { transform: [{ translateY: translation.value }] };
   });
 
   return { ref, onLayout, animatedStyle };

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/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';
@@ -95,6 +101,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 +244,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';

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