panelui-native 0.12.0 → 0.14.0

package/src/components/input/index.tsx

@@ -29,6 +29,7 @@ import Animated, {
 } from 'react-native-reanimated';
 import { tv, type VariantProps } from 'tailwind-variants';
 import { useCSSVariable } from 'uniwind';
+import type { KeyboardAvoidanceMode } from '../../hooks/use-keyboard-avoidance';
 import { KeyboardAvoider } from '../../primitives/keyboard-avoider';
 import { Text } from '../../primitives/text';
 import { Label } from '../label';
@@ -85,9 +86,11 @@ export interface InputProps
   isRequired?: boolean;
   disabled?: boolean;
   /**
-   * Lift the field above the software keyboard when it would otherwise be
-   * covered. Moves by exactly the overlap, and not at all when the field is
-   * already clear — or when the keyboard belongs to a different field.
+   * Keep the field clear of the software keyboard. Moves by exactly the
+   * overlap, and not at all when the field is already clear — or when the
+   * keyboard belongs to a different field. The overlap is re-read every frame
+   * while the field is focused, so the field keeps its place in the page as it
+   * scrolls under and back out of the keyboard.
    *
    * Install `react-native-keyboard-controller` for this to behave on Android.
    *
@@ -95,8 +98,20 @@ export interface InputProps
    * container, which would remount the field and drop focus.
    */
   avoidKeyboard?: boolean;
-  /** Gap kept between the field and the keyboard when `avoidKeyboard` is set. */
+  /**
+   * How the field gets clear. `lift` moves it up by its overlap and follows
+   * the scroll — right for a field in the flow of a page. `dock` makes it
+   * travel with the keyboard, for a composer already pinned near the bottom
+   * edge; pair it with `keyboardBottomInset`.
+   */
+  keyboardMode?: KeyboardAvoidanceMode;
+  /** Gap kept between the field and the keyboard. `keyboardMode="lift"` only. */
   keyboardOffset?: number;
+  /**
+   * How far above the bottom edge the field already sits — usually the safe
+   * area inset. `keyboardMode="dock"` only.
+   */
+  keyboardBottomInset?: number;
 }
 
 const AnimatedTextInput = Animated.createAnimatedComponent(TextInput);
@@ -114,7 +129,9 @@ export const Input = forwardRef<TextInput, InputProps>(
       variant,
       size,
       avoidKeyboard = false,
+      keyboardMode = 'lift',
       keyboardOffset = 16,
+      keyboardBottomInset = 0,
       onFocus,
       onBlur,
       style,
@@ -231,7 +248,9 @@ export const Input = forwardRef<TextInput, InputProps>(
           // anywhere is tapped, and since they all aim at the same gap above
           // the keyboard, they arrive stacked on top of one another.
           active={focused}
+          mode={keyboardMode}
           offset={keyboardOffset}
+          bottomInset={keyboardBottomInset}
           className={containerClasses}
         >
           {body}

package/src/components/scroll-canvas/index.tsx

@@ -0,0 +1,220 @@
+/**
+ * ScrollCanvas — an image frame whose contents move as you scroll past it.
+ *
+ * The counterpart to `ScrollText`: same scrubbed reveal, applied to a picture
+ * instead of a sentence. The frame stays where the layout puts it and the image
+ * moves *inside* it, which is what separates a parallax from a thing sliding
+ * about the page.
+ *
+ * ```tsx
+ * <ScrollProgress>
+ *   <ScrollView>
+ *     <ScrollCanvas source={{ uri }} effect="parallax" />
+ *   </ScrollView>
+ * </ScrollProgress>
+ * ```
+ *
+ * Four effects, and they are four different jobs:
+ *
+ * - **`parallax`** — the image drifts against the scroll, so the frame reads as
+ *   a window onto something further away.
+ * - **`zoom`** — it settles from slightly oversized to its natural size.
+ * - **`reveal`** — a wipe uncovers it from the bottom edge up.
+ * - **`sequence`** — the scroll position picks a frame out of a series, so the
+ *   reader scrubs an animation with their thumb.
+ *
+ * "Canvas" here is the frame the pictures move behind, not a drawing surface —
+ * nothing is rasterised, and there is no `<canvas>` anywhere near it.
+ */
+import { Image, View, type ImageSourcePropType, type ViewProps } from 'react-native';
+import Animated, {
+  interpolate,
+  useAnimatedStyle,
+  useReducedMotion,
+  type SharedValue,
+} from 'react-native-reanimated';
+import { useRevealProgress } from '../../hooks/use-reveal-progress';
+import { cn } from '../../utils/cn';
+
+const AnimatedImage = Animated.createAnimatedComponent(Image);
+
+/**
+ * How much taller than the frame a parallaxing image is drawn.
+ *
+ * The image has to be oversized or drifting it exposes an edge. This is the
+ * budget the drift is spent out of, so the two are set together — raising
+ * `distance` past what this affords is what puts a bare strip on screen.
+ */
+const PARALLAX_OVERSCAN = 1.25;
+
+/** How far a parallaxing image drifts, as a fraction of the frame's height. */
+const PARALLAX_TRAVEL = 0.1;
+
+export type ScrollCanvasEffect = 'parallax' | 'zoom' | 'reveal' | 'sequence';
+
+export interface ScrollCanvasProps extends Omit<ViewProps, 'children'> {
+  className?: string;
+  /** The image. Ignored by `sequence`, which reads `sources` instead. */
+  source?: ImageSourcePropType;
+  /**
+   * The frames a `sequence` scrubs through, in order. Keep it to a couple of
+   * dozen — every frame is a decoded bitmap held in memory for the whole time
+   * the canvas is mounted.
+   */
+  sources?: ImageSourcePropType[];
+  /** Which of the four scroll effects to apply. */
+  effect?: ScrollCanvasEffect;
+  /** Width ÷ height of the frame. */
+  aspectRatio?: number;
+  /** Multiplier on how far the effect travels. */
+  distance?: number;
+  /**
+   * Where down the viewport the frame's top sits when the effect starts, as a
+   * fraction of the viewport height.
+   */
+  start?: number;
+  /** Where its bottom sits when the effect completes. Smaller is a longer scrub. */
+  end?: number;
+  /** Drive the effect from a value of your own rather than from scroll. */
+  progress?: SharedValue<number>;
+  /** Set false to render the image plainly. */
+  enabled?: boolean;
+  /** Extra classes for the image itself, rather than the frame around it. */
+  imageClassName?: string;
+}
+
+export function ScrollCanvas({
+  className,
+  imageClassName,
+  source,
+  sources,
+  effect = 'parallax',
+  aspectRatio = 16 / 10,
+  distance = 1,
+  start = 1,
+  end = 0.3,
+  progress: external,
+  enabled = true,
+  style,
+  ...props
+}: ScrollCanvasProps) {
+  const reducedMotion = useReducedMotion();
+  const active = enabled && !reducedMotion;
+
+  const { ref, progress } = useRevealProgress({
+    start,
+    end,
+    progress: external,
+    enabled: active,
+  });
+
+  const frames = sources ?? (source ? [source] : []);
+
+  const imageStyle = useAnimatedStyle(() => {
+    const p = progress.value;
+
+    if (effect === 'zoom') {
+      return { transform: [{ scale: interpolate(p, [0, 1], [1 + 0.12 * distance, 1]) }] };
+    }
+    if (effect === 'parallax') {
+      // Centred at half travel, so the drift is symmetric about the frame and
+      // the overscan is spent evenly at both ends instead of all at one.
+      const travel = PARALLAX_TRAVEL * distance * 100;
+      // A percentage of the image's own height, so the drift stays in
+      // proportion to the overscan whatever size the frame ends up.
+      return {
+        transform: [{ translateY: `${interpolate(p, [0, 1], [travel, -travel])}%` }],
+      };
+    }
+    return {};
+  });
+
+  // A wipe rather than a fade: the frame keeps its shape while it fills, so the
+  // layout never moves. Implemented as a cover that retreats, because animating
+  // a height would relayout the image inside it every frame.
+  const coverStyle = useAnimatedStyle(() => ({
+    transform: [{ translateY: `${-progress.value * 100}%` }],
+  }));
+
+  return (
+    <View
+      {...props}
+      ref={ref}
+      style={[{ aspectRatio }, style]}
+      className={cn('w-full overflow-hidden rounded-2xl bg-muted', className)}
+    >
+      {effect === 'sequence' ? (
+        frames.map((frame, index) => (
+          <SequenceFrame
+            key={index}
+            source={frame}
+            index={index}
+            count={frames.length}
+            progress={progress}
+            className={imageClassName}
+          />
+        ))
+      ) : (
+        <AnimatedImage
+          source={frames[0]!}
+          resizeMode="cover"
+          className={cn('h-full w-full', imageClassName)}
+          style={[
+            // Only the parallax is oversized. Growing the others would crop
+            // them for no reason — nothing is drifting to expose an edge.
+            effect === 'parallax'
+              ? { height: `${PARALLAX_OVERSCAN * 100}%`, top: `${(1 - PARALLAX_OVERSCAN) * 50}%` }
+              : null,
+            imageStyle,
+          ]}
+        />
+      )}
+
+      {effect === 'reveal' ? (
+        <Animated.View
+          pointerEvents="none"
+          className="absolute inset-0 bg-background"
+          style={coverStyle}
+        />
+      ) : null}
+    </View>
+  );
+}
+
+ScrollCanvas.displayName = 'ScrollCanvas';
+
+/**
+ * One frame of a sequence.
+ *
+ * Every frame is mounted and its opacity switched, rather than one image whose
+ * source is swapped. A swap crosses back into JS for each step and then waits
+ * on a decode, so a fast scrub shows the previous frame or nothing at all;
+ * mounted frames scrub on the UI thread with no decode left to do.
+ */
+function SequenceFrame({
+  source,
+  index,
+  count,
+  progress,
+  className,
+}: {
+  source: ImageSourcePropType;
+  index: number;
+  count: number;
+  progress: SharedValue<number>;
+  className?: string;
+}) {
+  const style = useAnimatedStyle(() => {
+    // The frame that owns this slice of the scroll is the visible one. Hard
+    // steps, not a crossfade — two frames of an animation overlaid at half
+    // opacity is a double exposure, not a tween.
+    const current = Math.min(count - 1, Math.floor(progress.value * count));
+    return { opacity: current === index ? 1 : 0 };
+  });
+
+  return (
+    <Animated.View className="absolute inset-0" style={style}>
+      <Image source={source} resizeMode="cover" className={cn('h-full w-full', className)} />
+    </Animated.View>
+  );
+}

package/src/components/scroll-text/index.tsx

@@ -0,0 +1,277 @@
+/**
+ * ScrollText — a line of text that resolves word by word as you scroll past it.
+ *
+ * The reader's thumb becomes the playhead. Words arrive left to right as the
+ * block crosses the viewport, and going back up unresolves them — the effect is
+ * scrubbed, not triggered, so it is reversible and lands exactly on both ends.
+ *
+ * ```tsx
+ * <ScrollProgress>
+ *   <ScrollView>
+ *     <ScrollText size="3xl" weight="semibold">
+ *       Every control ships with its accessibility wiring already done.
+ *     </ScrollText>
+ *   </ScrollView>
+ * </ScrollProgress>
+ * ```
+ *
+ * ## Two layouts, and why
+ *
+ * `color`, `fade` and `highlight` render the words as nested `Text` inside one
+ * parent, which is the only way React Native will break them into real lines —
+ * hyphenation, justification, the lot. Nested text cannot be transformed,
+ * though: a `translateY` on it is ignored.
+ *
+ * So `rise` lays the words out as a wrapping row of separate views instead.
+ * That buys transforms and costs real line-breaking — words wrap on their own
+ * boundaries and the spacing is a margin rather than a space. Worth knowing
+ * before picking the effect for a paragraph rather than a heading.
+ */
+import { useMemo } from 'react';
+import { Text as RNText, View, type TextStyle } from 'react-native';
+import Animated, {
+  interpolate,
+  interpolateColor,
+  useAnimatedStyle,
+  useReducedMotion,
+  type SharedValue,
+} from 'react-native-reanimated';
+import { useCSSVariable } from 'uniwind';
+import { useRevealProgress } from '../../hooks/use-reveal-progress';
+import { Text, type TextProps } from '../../primitives/text';
+
+const AnimatedText = Animated.createAnimatedComponent(RNText);
+
+/** How far a word rises from, in pixels, for the `rise` effect. */
+const RISE_DISTANCE = 18;
+
+export type ScrollTextEffect = 'color' | 'fade' | 'rise' | 'highlight';
+export type ScrollTextSplit = 'word' | 'character';
+
+/** Effects that need a transform, and so cannot use nested text. */
+const NEEDS_ROW: ScrollTextEffect[] = ['rise'];
+
+export interface ScrollTextProps extends Omit<TextProps, 'children'> {
+  className?: string;
+  /** The sentence. Split into words or characters, then revealed across them. */
+  children?: string;
+  /**
+   * `color` crossfades each word between two colours, `fade` brings it up from
+   * transparent, `rise` lifts it into place, `highlight` sweeps a background
+   * behind it.
+   */
+  effect?: ScrollTextEffect;
+  /** Reveal a word at a time, or a character at a time. */
+  by?: ScrollTextSplit;
+  /** Colour before a word is reached. Defaults to the muted foreground token. */
+  from?: string;
+  /** Colour once it has been. Defaults to the foreground token. */
+  to?: string;
+  /**
+   * Where down the viewport the block's top sits when the reveal starts, as a
+   * fraction of the viewport height.
+   */
+  start?: number;
+  /** Where its bottom sits when the reveal completes. Smaller is a longer scrub. */
+  end?: number;
+  /**
+   * How much of the whole reveal a single word takes, `0` to `1`. Small values
+   * make a hard edge travelling along the line; large ones make the whole
+   * sentence brighten together.
+   */
+  stagger?: number;
+  /**
+   * Drive the reveal from a value of your own rather than from scroll — a
+   * progress bar, a gesture, a timeline.
+   */
+  progress?: SharedValue<number>;
+  /** Set false to render the text resolved, with no effect at all. */
+  enabled?: boolean;
+}
+
+export function ScrollText({
+  className,
+  children = '',
+  effect = 'color',
+  by = 'word',
+  from,
+  to,
+  start = 0.9,
+  end = 0.5,
+  stagger = 0.35,
+  progress: external,
+  enabled = true,
+  ...textProps
+}: ScrollTextProps) {
+  const reducedMotion = useReducedMotion();
+  const active = enabled && !reducedMotion;
+
+  const { ref, progress } = useRevealProgress({
+    start,
+    end,
+    progress: external,
+    enabled: active,
+  });
+
+  const mutedToken = useCSSVariable('--color-muted-foreground');
+  const foregroundToken = useCSSVariable('--color-foreground');
+  const accentToken = useCSSVariable('--color-accent');
+
+  const dim = from ?? (typeof mutedToken === 'string' ? mutedToken : '#a1a1aa');
+  const lit = to ?? (typeof foregroundToken === 'string' ? foregroundToken : '#0a0a0a');
+  const highlight = typeof accentToken === 'string' ? accentToken : 'rgba(0,0,0,0.08)';
+
+  const tokens = useMemo(() => splitText(children, by), [children, by]);
+
+  // Every token gets the same slice of the reveal, offset along the line. The
+  // slice is a fraction of the whole rather than a fixed duration, so a long
+  // sentence and a short one both finish exactly when the block has passed.
+  const span = Math.max(stagger, 0.01);
+  const stride = tokens.length > 1 ? (1 - span) / (tokens.length - 1) : 0;
+
+  const asRow = NEEDS_ROW.includes(effect);
+
+  if (asRow) {
+    return (
+      <View ref={ref} className="flex-row flex-wrap items-baseline">
+        {tokens.map((token, index) => (
+          <RisingToken
+            key={`${index}-${token}`}
+            text={token}
+            progress={progress}
+            startAt={index * stride}
+            span={span}
+            last={index === tokens.length - 1}
+            textProps={textProps}
+            className={className}
+          />
+        ))}
+      </View>
+    );
+  }
+
+  return (
+    <View ref={ref}>
+      <Text {...textProps} className={className}>
+        {tokens.map((token, index) => (
+          <InkedToken
+            key={`${index}-${token}`}
+            text={token}
+            progress={progress}
+            startAt={index * stride}
+            span={span}
+            effect={effect}
+            dim={dim}
+            lit={lit}
+            highlight={highlight}
+            last={index === tokens.length - 1}
+          />
+        ))}
+      </Text>
+    </View>
+  );
+}
+
+ScrollText.displayName = 'ScrollText';
+
+/**
+ * One word or character inside the parent's text flow, inked by the reveal.
+ *
+ * Nested text, so React Native breaks the sentence into real lines. That rules
+ * out transforms — colour, opacity and background are what nested text will
+ * animate, which is exactly the three effects routed here.
+ */
+function InkedToken({
+  text,
+  progress,
+  startAt,
+  span,
+  effect,
+  dim,
+  lit,
+  highlight,
+  last,
+}: {
+  text: string;
+  progress: SharedValue<number>;
+  startAt: number;
+  span: number;
+  effect: ScrollTextEffect;
+  dim: string;
+  lit: string;
+  highlight: string;
+  last: boolean;
+}) {
+  const style = useAnimatedStyle(() => {
+    const local = Math.min(1, Math.max(0, (progress.value - startAt) / span));
+
+    if (effect === 'fade') {
+      // Not all the way to transparent: a word that vanishes takes the line's
+      // shape with it, and the paragraph reflows as you scroll.
+      return { opacity: interpolate(local, [0, 1], [0.18, 1]), color: lit } as TextStyle;
+    }
+    if (effect === 'highlight') {
+      return {
+        color: interpolateColor(local, [0, 1], [dim, lit]),
+        backgroundColor: interpolateColor(local, [0, 1], ['transparent', highlight]),
+      } as TextStyle;
+    }
+    return { color: interpolateColor(local, [0, 1], [dim, lit]) } as TextStyle;
+  });
+
+  return <AnimatedText style={style}>{last ? text : `${text} `}</AnimatedText>;
+}
+
+/**
+ * One word as its own box, lifted into place.
+ *
+ * A transform needs a view, and a view in a text flow is a word that no longer
+ * takes part in line-breaking — hence the wrapping row above, and hence the
+ * margin below, since a trailing space inside a box is not a space between
+ * boxes.
+ */
+function RisingToken({
+  text,
+  progress,
+  startAt,
+  span,
+  last,
+  textProps,
+  className,
+}: {
+  text: string;
+  progress: SharedValue<number>;
+  startAt: number;
+  span: number;
+  last: boolean;
+  textProps: Omit<TextProps, 'children' | 'className'>;
+  className?: string;
+}) {
+  const style = useAnimatedStyle(() => {
+    const local = Math.min(1, Math.max(0, (progress.value - startAt) / span));
+    return {
+      opacity: local,
+      transform: [{ translateY: interpolate(local, [0, 1], [RISE_DISTANCE, 0]) }],
+    };
+  });
+
+  return (
+    <Animated.View style={[style, last ? undefined : { marginRight: 6 }]}>
+      <Text {...textProps} className={className}>
+        {text}
+      </Text>
+    </Animated.View>
+  );
+}
+
+/**
+ * Splits on whitespace, keeping punctuation attached to the word it belongs to.
+ * Splitting a sentence into bare words and re-joining with single spaces loses
+ * the double space after a full stop and every non-breaking space in it.
+ */
+function splitText(text: string, by: ScrollTextSplit): string[] {
+  const trimmed = text.trim();
+  if (!trimmed) return [];
+  if (by === 'character') return Array.from(trimmed);
+  return trimmed.split(/\s+/);
+}

package/src/components/select/index.tsx

@@ -87,14 +87,6 @@ const selectVariants = tv({
 
 export type SelectPresentation = 'sheet' | 'inline' | 'overlay';
 
-/**
- * Height given to the native host per appearance — a menu is a compact button,
- * a wheel is a full rotor. The host is told its size rather than asked to
- * measure the platform's content, which arrives a frame late and leaves the
- * control collapsed until something forces a second pass.
- */
-const NATIVE_HEIGHT = { menu: 44, wheel: 216 } as const;
-
 interface SelectContextValue {
   value: string | undefined;
   onSelect: (value: string) => void;
@@ -279,7 +271,10 @@ function SelectRoot({
     // The native picker has no empty state, so an unset value shows the first
     // option rather than the placeholder.
     return (
-      <Host style={{ height: NATIVE_HEIGHT[nativeAppearance] }}>
+      // A picker fills the width of the row it sits in and reports its own
+      // height — a menu is a compact button, a wheel a full rotor, and the
+      // platform is the only thing that knows which by how much.
+      <Host matchContents={{ vertical: true }}>
         <Picker
           selectedValue={value ?? options[0]?.value ?? ''}
           onValueChange={(next: string) => onValueChange(next)}

package/src/components/slider/index.tsx

@@ -93,9 +93,6 @@ const sliderVariants = tv({
 /** Thumb width per size. Wider than it is tall, so the pill reads as a grip. */
 const THUMB_WIDTH: Record<'sm' | 'md' | 'lg', number> = { sm: 24, md: 28, lg: 32 };
 
-/** Row height reserved for the platform's own slider. */
-const NATIVE_HEIGHT = 32;
-
 type SliderVariantProps = VariantProps<typeof sliderVariants>;
 
 export interface SliderProps extends Omit<SliderVariantProps, 'disabled'> {
@@ -308,10 +305,10 @@ export const Slider = forwardRef<View, SliderProps>(
       return (
         <View ref={ref} className={slots.root({ className })}>
           {header}
-          {/* Told its height rather than left to measure the platform's own
-              content, which arrives a frame late — a host that has to work its
-              size out renders at nothing and then jumps. */}
-          <Host style={{ height: NATIVE_HEIGHT }}>
+          {/* A slider has no intrinsic width — it fills whatever it is given —
+              so the width comes from ordinary layout and only the height is
+              matched to the platform's content. */}
+          <Host matchContents={{ vertical: true }}>
             <NativeSlider
               value={value}
               onValueChange={(next: number) => {

package/src/components/switch/index.tsx

@@ -33,13 +33,6 @@ const switchVariants = tv({
 
 const TRAVEL: Record<'sm' | 'md', number> = { sm: 16, md: 20 };
 
-/**
- * Row height given to the native host. It is told its size rather than asked
- * to measure the platform's own content, which arrives a frame late and leaves
- * the control collapsed until something forces a second pass.
- */
-const NATIVE_HEIGHT = 32;
-
 export interface SwitchProps extends VariantProps<typeof switchVariants> {
   className?: string;
   value: boolean;
@@ -84,7 +77,11 @@ export const Switch = forwardRef<View, SwitchProps>(
     if (nativeUI) {
       const { Host, Switch: NativeSwitch } = nativeUI;
       return (
-        <Host style={{ height: NATIVE_HEIGHT }}>
+        // A platform toggle has a definite intrinsic size on both platforms,
+        // so the host is left to follow it. Pinning the host to a number
+        // instead is what leaves the control laid out against a box it never
+        // agreed to, and settling into it a frame later.
+        <Host matchContents>
           <NativeSwitch
             value={value}
             onValueChange={(next: boolean) => onValueChange?.(next)}