panelui-native 0.5.3 → 0.7.0

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

@@ -0,0 +1,280 @@
+/**
+ * ScrollFade — fades the edges of a scroll container.
+ *
+ * Content that runs past a boundary reads better fading out than being cut
+ * off, and the fade doubles as an affordance: an edge that is fading is an
+ * edge with more content behind it.
+ *
+ * Scroll position, content size and viewport size are all held in shared
+ * values and consumed by `useAnimatedStyle`, so the fades track the scroll on
+ * the UI thread without re-rendering React.
+ *
+ * ```tsx
+ * <ScrollFade>
+ *   <ScrollView horizontal>…</ScrollView>
+ * </ScrollFade>
+ * ```
+ */
+import {
+  Children,
+  cloneElement,
+  isValidElement,
+  useMemo,
+  type ComponentType,
+  type ReactElement,
+  type ReactNode,
+} from 'react';
+import {
+  StyleSheet,
+  View,
+  type LayoutChangeEvent,
+  type NativeScrollEvent,
+  type NativeSyntheticEvent,
+  type ViewProps,
+} from 'react-native';
+import { LinearGradient } from 'expo-linear-gradient';
+import Animated, {
+  useAnimatedScrollHandler,
+  useAnimatedStyle,
+  useComposedEventHandler,
+  useDerivedValue,
+  useSharedValue,
+  type AnimatedScrollViewProps,
+  type DerivedValue,
+} from 'react-native-reanimated';
+import { useCSSVariable } from 'uniwind';
+
+/** Past this many pixels from an edge, that edge's fade is fully shown. */
+const DEFAULT_FADE_IN_DISTANCE = 24;
+
+export interface ScrollFadeProps extends ViewProps {
+  className?: string;
+  /** Depth of the fade in pixels. */
+  size?: number;
+  /** Which edges fade. */
+  edges?: 'both' | 'start' | 'end' | 'none';
+  /**
+   * Scroll axis. Inferred from the child's `horizontal` prop when omitted —
+   * pass it explicitly for children that scroll horizontally without that prop
+   * (a `FlatList` with `horizontal` set through `contentContainerStyle`, say).
+   */
+  orientation?: 'horizontal' | 'vertical';
+  /**
+   * Colour the fade resolves to — normally whatever sits behind the
+   * scrollable. Defaults to the theme's background.
+   */
+  color?: string;
+  /** Distance in pixels over which an edge fades from clear to full. */
+  fadeInDistance?: number;
+  /** Set false to render the child with no fades at all. */
+  enabled?: boolean;
+  children?: ReactNode;
+}
+
+interface ScrollableProps {
+  horizontal?: boolean;
+  onScroll?: AnimatedScrollViewProps['onScroll'];
+  onLayout?: (event: LayoutChangeEvent) => void;
+  onContentSizeChange?: (width: number, height: number) => void;
+  scrollEventThrottle?: number;
+}
+
+export function ScrollFade({
+  className,
+  size = 48,
+  edges = 'both',
+  orientation,
+  color,
+  fadeInDistance = DEFAULT_FADE_IN_DISTANCE,
+  enabled = true,
+  children,
+  ...props
+}: ScrollFadeProps) {
+  const offset = useSharedValue(0);
+  const contentLength = useSharedValue(0);
+  const viewportLength = useSharedValue(0);
+
+  const themeBackground = useCSSVariable('--color-background');
+  const fadeColor =
+    color ?? (typeof themeBackground === 'string' ? themeBackground : '#000000');
+
+  const child = Children.only(children) as ReactElement<ScrollableProps>;
+  const horizontal =
+    orientation !== undefined
+      ? orientation === 'horizontal'
+      : isValidElement(child) && !!child.props.horizontal;
+
+  // Reanimated can only drive a scroll handler on an animated component, and
+  // `Animated.ScrollView` is not necessarily what was passed in — the child may
+  // be a FlatList, a SectionList or a custom scrollable. Keyed on the element
+  // *type*, not the element: rebuilding the wrapper would remount the list.
+  const childType = isValidElement(child)
+    ? (child.type as ComponentType<ScrollableProps>)
+    : null;
+  const AnimatedScrollable = useMemo(
+    () => (childType ? Animated.createAnimatedComponent(childType) : null),
+    [childType]
+  );
+
+  const scrollHandler = useAnimatedScrollHandler({
+    onScroll: (event) => {
+      const { contentOffset, contentSize, layoutMeasurement } = event;
+      offset.value = horizontal ? contentOffset.x : contentOffset.y;
+      contentLength.value = horizontal ? contentSize.width : contentSize.height;
+      viewportLength.value = horizontal
+        ? layoutMeasurement.width
+        : layoutMeasurement.height;
+    },
+  });
+
+  // A consumer `onScroll` is composed rather than dropped — but because 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,
+  ]);
+
+  // Measured up front as well as on scroll, so an end edge with content behind
+  // it fades from the first frame rather than waiting for a scroll event.
+  const onLayout = (event: LayoutChangeEvent) => {
+    const { width, height } = event.nativeEvent.layout;
+    viewportLength.value = horizontal ? width : height;
+    child.props.onLayout?.(event);
+  };
+
+  const onContentSizeChange = (width: number, height: number) => {
+    contentLength.value = horizontal ? width : height;
+    child.props.onContentSizeChange?.(width, height);
+  };
+
+  const startOpacity = useDerivedValue(() =>
+    Math.min(offset.value / fadeInDistance, 1)
+  );
+
+  const endOpacity = useDerivedValue(() => {
+    // Nothing to fade towards when the content fits inside the viewport.
+    const remaining = contentLength.value - viewportLength.value - offset.value;
+    return Math.min(Math.max(remaining, 0) / fadeInDistance, 1);
+  });
+
+  const scrollable =
+    AnimatedScrollable && isValidElement(child) ? (
+      <AnimatedScrollable
+        {...child.props}
+        onScroll={onScroll}
+        onLayout={onLayout}
+        onContentSizeChange={onContentSizeChange}
+        scrollEventThrottle={child.props.scrollEventThrottle ?? 16}
+      />
+    ) : (
+      child
+    );
+
+  if (!enabled || edges === 'none') {
+    return (
+      <View {...props} className={className}>
+        {scrollable}
+      </View>
+    );
+  }
+
+  return (
+    <View {...props} className={className}>
+      {scrollable}
+
+      {edges !== 'end' ? (
+        <Fade
+          color={fadeColor}
+          size={size}
+          horizontal={horizontal}
+          opacity={startOpacity}
+          edge="start"
+        />
+      ) : null}
+      {edges !== 'start' ? (
+        <Fade
+          color={fadeColor}
+          size={size}
+          horizontal={horizontal}
+          opacity={endOpacity}
+          edge="end"
+        />
+      ) : null}
+    </View>
+  );
+}
+
+ScrollFade.displayName = 'ScrollFade';
+
+/** One edge's gradient, opaque at the edge and clear inwards. */
+function Fade({
+  color,
+  size,
+  horizontal,
+  opacity,
+  edge,
+}: {
+  color: string;
+  size: number;
+  horizontal: boolean;
+  opacity: DerivedValue<number>;
+  edge: 'start' | 'end';
+}) {
+  const isStart = edge === 'start';
+
+  const position = horizontal
+    ? { top: 0, bottom: 0, width: size, ...(isStart ? { left: 0 } : { right: 0 }) }
+    : { left: 0, right: 0, height: size, ...(isStart ? { top: 0 } : { bottom: 0 }) };
+
+  const style = useAnimatedStyle(() => ({ opacity: opacity.value }));
+
+  // The gradient runs from the edge inwards, so its stops are reversed on the
+  // end edge.
+  const colors: [string, string] = isStart
+    ? [withAlpha(color, 1), withAlpha(color, 0)]
+    : [withAlpha(color, 0), withAlpha(color, 1)];
+
+  return (
+    <Animated.View
+      pointerEvents="none"
+      style={[{ position: 'absolute' }, position, style]}
+    >
+      <LinearGradient
+        colors={colors}
+        start={{ x: 0, y: 0 }}
+        end={horizontal ? { x: 1, y: 0 } : { x: 0, y: 1 }}
+        style={StyleSheet.absoluteFill}
+      />
+    </Animated.View>
+  );
+}
+
+/**
+ * Gradients need a transparent stop of the *same* colour — `transparent` is
+ * black at zero alpha on Android, which shows as a grey smear.
+ */
+function withAlpha(color: string, alpha: number): string {
+  if (color.startsWith('#')) {
+    const hex = color.slice(1);
+    const full =
+      hex.length === 3
+        ? hex
+            .split('')
+            .map((c) => c + c)
+            .join('')
+        : hex.slice(0, 6);
+    const r = parseInt(full.slice(0, 2), 16);
+    const g = parseInt(full.slice(2, 4), 16);
+    const b = parseInt(full.slice(4, 6), 16);
+    if (Number.isNaN(r + g + b)) return color;
+    return `rgba(${r}, ${g}, ${b}, ${alpha})`;
+  }
+
+  const channels = color.match(/rgba?\(([^)]+)\)/)?.[1];
+  if (channels) {
+    const [r, g, b] = channels.split(',').map((part) => part.trim());
+    return `rgba(${r}, ${g}, ${b}, ${alpha})`;
+  }
+
+  return color;
+}

package/src/components/select/index.tsx

@@ -12,6 +12,7 @@ import { Pressable, ScrollView, View } from 'react-native';
 import { tv } from 'tailwind-variants';
 import { useCSSVariable } from 'uniwind';
 import { CheckIcon, ChevronDownIcon } from '../../icons';
+import { getNativeUI } from '../../native';
 import { Text } from '../../primitives/text';
 import { BottomSheet } from '../bottom-sheet';
 
@@ -86,6 +87,21 @@ export interface SelectProps {
   /** Sheet title shown above the options. */
   title?: string;
   disabled?: boolean;
+  /**
+   * Render the platform's own picker instead of the trigger-and-sheet pair.
+   * Requires the optional `@expo/ui` package; without it this prop does
+   * nothing.
+   *
+   * **Theme tokens do not apply** — the platform draws the picker, so
+   * `className` and `title` are ignored. `Select.Item` children still declare
+   * the options.
+   */
+  native?: boolean;
+  /**
+   * Native picker style. `menu` is a compact button opening a dropdown;
+   * `wheel` is an always-visible rotor (iOS; falls back to `menu` elsewhere).
+   */
+  nativeAppearance?: 'menu' | 'wheel';
   children: ReactNode;
 }
 
@@ -96,22 +112,27 @@ function SelectRoot({
   placeholder = 'Select an option',
   title,
   disabled,
+  native,
+  nativeAppearance = 'menu',
   children,
 }: SelectProps) {
   const [open, setOpen] = useState(false);
+  const nativeUI = native ? getNativeUI() : null;
 
-  const selectedLabel = useMemo(() => {
-    let label: string | undefined;
+  const options = useMemo(() => {
+    const collected: SelectItemProps[] = [];
     Children.forEach(children, (child) => {
-      if (
-        isValidElement<SelectItemProps>(child) &&
-        child.props.value === value
-      ) {
-        label = child.props.label;
+      if (isValidElement<SelectItemProps>(child)) {
+        collected.push({ value: child.props.value, label: child.props.label });
       }
     });
-    return label;
-  }, [children, value]);
+    return collected;
+  }, [children]);
+
+  const selectedLabel = useMemo(
+    () => options.find((option) => option.value === value)?.label,
+    [options, value]
+  );
 
   const context = useMemo<SelectContextValue>(
     () => ({
@@ -129,6 +150,30 @@ function SelectRoot({
   });
   const chevronColor = useCSSVariable('--color-muted-foreground');
 
+  if (nativeUI) {
+    const { Host, Picker } = nativeUI;
+    // The native picker has no empty state, so an unset value shows the first
+    // option rather than the placeholder.
+    return (
+      <Host matchContents>
+        <Picker
+          selectedValue={value ?? options[0]?.value ?? ''}
+          onValueChange={(next: string) => onValueChange(next)}
+          appearance={nativeAppearance}
+          enabled={!disabled}
+        >
+          {options.map((option) => (
+            <Picker.Item
+              key={option.value}
+              label={option.label}
+              value={option.value}
+            />
+          ))}
+        </Picker>
+      </Host>
+    );
+  }
+
   return (
     <SelectContext.Provider value={context}>
       <Pressable

package/src/components/shimmer/index.tsx

@@ -0,0 +1,228 @@
+/**
+ * Shimmer — a highlight that sweeps *through* content rather than over it.
+ *
+ * The content is used as a mask, and a gradient band is swept behind it on the
+ * UI thread. Because the content is the mask, the highlight is clipped to the
+ * glyph shapes: text reads as though the letters themselves are catching a
+ * light, which is the "thinking…" treatment familiar from AI chat interfaces.
+ *
+ * ```tsx
+ * <Shimmer>Thinking…</Shimmer>
+ * ```
+ *
+ * Set `as="view"` to shimmer arbitrary children (skeleton blocks, cards) — the
+ * mask is then the rendered subtree's alpha instead of a line of text.
+ */
+import { useEffect, useState, type ReactNode } from 'react';
+import {
+  StyleSheet,
+  View,
+  type LayoutChangeEvent,
+  type StyleProp,
+  type TextStyle,
+  type ViewProps,
+} from 'react-native';
+import MaskedView from '@react-native-masked-view/masked-view';
+import { LinearGradient } from 'expo-linear-gradient';
+import Animated, {
+  cancelAnimation,
+  Easing,
+  useAnimatedStyle,
+  useReducedMotion,
+  useSharedValue,
+  withRepeat,
+  withTiming,
+} from 'react-native-reanimated';
+import { useCSSVariable } from 'uniwind';
+import { Text } from '../../primitives/text';
+import { cn } from '../../utils/cn';
+
+export interface ShimmerProps extends ViewProps {
+  className?: string;
+  /**
+   * `text` renders `children` as a single styled string and masks the sweep to
+   * the glyphs. `view` masks the sweep to whatever subtree you pass.
+   */
+  as?: 'text' | 'view';
+  /** Milliseconds for one sweep. */
+  duration?: number;
+  /** Width of the highlight band, as a multiple of the content width. */
+  spread?: number;
+  /** Colour of the content at rest. Defaults to the theme's muted foreground. */
+  baseColor?: string;
+  /** Colour at the centre of the sweep. Defaults to the theme's foreground. */
+  shimmerColor?: string;
+  /** `loop` restarts from the left; `ping-pong` reverses on each pass. */
+  mode?: 'loop' | 'ping-pong';
+  /** Sweep once instead of repeating. */
+  once?: boolean;
+  /** Sweep right-to-left. */
+  reverse?: boolean;
+  /** Set false to render the content statically without animating. */
+  enabled?: boolean;
+  /** Extra classes for the text when `as="text"`. */
+  textClassName?: string;
+  /** Extra styles for the text when `as="text"`. */
+  textStyle?: StyleProp<TextStyle>;
+  /**
+   * @deprecated Use `shimmerColor`.
+   */
+  color?: string;
+  /**
+   * Peak opacity of the highlight.
+   * @deprecated Set `shimmerColor` to a colour with the alpha you want.
+   */
+  intensity?: number;
+  children?: ReactNode;
+}
+
+export function Shimmer({
+  className,
+  as = 'text',
+  duration = 2000,
+  spread = 2,
+  baseColor,
+  shimmerColor,
+  mode = 'loop',
+  once = false,
+  reverse = false,
+  enabled = true,
+  textClassName,
+  textStyle,
+  color,
+  intensity,
+  children,
+  ...props
+}: ShimmerProps) {
+  const [width, setWidth] = useState(0);
+  const progress = useSharedValue(0);
+  const reducedMotion = useReducedMotion();
+
+  const themeMuted = useCSSVariable('--color-muted-foreground');
+  const themeForeground = useCSSVariable('--color-foreground');
+
+  const base =
+    baseColor ?? (typeof themeMuted === 'string' ? themeMuted : '#a1a1aa');
+  const highlight =
+    shimmerColor ??
+    color ??
+    (typeof themeForeground === 'string' ? themeForeground : '#ffffff');
+
+  // The band is wider than the content so the highlight ramps in and out
+  // instead of appearing at full strength against the edge.
+  const bandWidth = Math.max(width * spread, 1);
+  const animating = enabled && !reducedMotion && width > 0;
+
+  useEffect(() => {
+    if (!animating) {
+      cancelAnimation(progress);
+      progress.value = 0;
+      return;
+    }
+
+    progress.value = 0;
+    progress.value = withRepeat(
+      withTiming(1, { duration, easing: Easing.linear }),
+      once ? 1 : -1,
+      mode === 'ping-pong'
+    );
+
+    return () => cancelAnimation(progress);
+  }, [animating, duration, mode, once, progress]);
+
+  const sweepStyle = useAnimatedStyle(() => {
+    // Travel from fully off one edge to fully off the other.
+    const from = -bandWidth;
+    const to = width;
+    const x = reverse
+      ? to - progress.value * (to - from)
+      : from + progress.value * (to - from);
+    return { transform: [{ translateX: x }] };
+  });
+
+  const onLayout = (event: LayoutChangeEvent) => {
+    setWidth(event.nativeEvent.layout.width);
+    props.onLayout?.(event);
+  };
+
+  const content =
+    as === 'text' ? (
+      <Text className={textClassName} style={[{ color: base }, textStyle]}>
+        {children}
+      </Text>
+    ) : (
+      children
+    );
+
+  // Without a measured width there is nothing to sweep across, and masking an
+  // unmeasured subtree just costs a layer — render the content plainly.
+  if (!animating) {
+    return (
+      <View {...props} onLayout={onLayout} className={className}>
+        {content}
+      </View>
+    );
+  }
+
+  const highlightWithAlpha =
+    intensity !== undefined ? withAlpha(highlight, intensity) : highlight;
+
+  return (
+    <View {...props} onLayout={onLayout} className={cn('overflow-hidden', className)}>
+      <MaskedView maskElement={<View>{content}</View>}>
+        {/* The mask only exposes the glyphs, so this layer is what they are
+            painted with: flat base colour, plus a moving gradient band. */}
+        <View style={{ backgroundColor: base }}>
+          <View style={{ opacity: 0 }}>{content}</View>
+          <Animated.View
+            pointerEvents="none"
+            style={[
+              StyleSheet.absoluteFill,
+              { width: bandWidth, left: 0, right: undefined },
+              sweepStyle,
+            ]}
+          >
+            <LinearGradient
+              colors={[base, highlightWithAlpha, base]}
+              locations={[0, 0.5, 1]}
+              start={{ x: 0, y: 0 }}
+              end={{ x: 1, y: 0 }}
+              style={StyleSheet.absoluteFill}
+            />
+          </Animated.View>
+        </View>
+      </MaskedView>
+    </View>
+  );
+}
+
+Shimmer.displayName = 'Shimmer';
+
+/** Applies an alpha to a `#rgb`/`#rrggbb`/`rgb()` colour. Supports `intensity`. */
+function withAlpha(color: string, alpha: number): string {
+  const clamped = Math.max(0, Math.min(1, alpha));
+
+  if (color.startsWith('#')) {
+    const hex = color.slice(1);
+    const full =
+      hex.length === 3
+        ? hex
+            .split('')
+            .map((c) => c + c)
+            .join('')
+        : hex.slice(0, 6);
+    const r = parseInt(full.slice(0, 2), 16);
+    const g = parseInt(full.slice(2, 4), 16);
+    const b = parseInt(full.slice(4, 6), 16);
+    if (Number.isNaN(r + g + b)) return color;
+    return `rgba(${r}, ${g}, ${b}, ${clamped})`;
+  }
+
+  const channels = color.match(/rgba?\(([^)]+)\)/)?.[1];
+  if (channels) {
+    const [r, g, b] = channels.split(',').map((part) => part.trim());
+    return `rgba(${r}, ${g}, ${b}, ${clamped})`;
+  }
+
+  return color;
+}

package/src/components/surface/index.tsx

@@ -0,0 +1,64 @@
+/**
+ * Surface — an elevated container.
+ *
+ * The variants form a ladder rather than a palette: each step is one level
+ * further from the background, and nesting them is how you build depth without
+ * hardcoding a colour anywhere.
+ *
+ * Both the fill and the corner radius follow the active theme: the variants
+ * resolve to themed `--color-surface-*` tokens, and `rounded-3xl` resolves
+ * through the per-theme radius scale — so Moon's surfaces are tight and
+ * Grass's are soft, without the component knowing anything about either.
+ *
+ * ```tsx
+ * <Surface>
+ *   <Surface variant="secondary">
+ *     <Surface variant="tertiary">…</Surface>
+ *   </Surface>
+ * </Surface>
+ * ```
+ */
+import { forwardRef } from 'react';
+import { StyleSheet, View, type ViewProps } from 'react-native';
+import { tv, type VariantProps } from 'tailwind-variants';
+
+const surfaceVariants = tv({
+  base: 'overflow-hidden rounded-3xl p-4',
+  variants: {
+    variant: {
+      default: 'bg-surface',
+      secondary: 'bg-surface-secondary',
+      tertiary: 'bg-surface-tertiary',
+      transparent: 'bg-transparent',
+    },
+  },
+  defaultVariants: {
+    variant: 'default',
+  },
+});
+
+export interface SurfaceProps
+  extends ViewProps,
+    VariantProps<typeof surfaceVariants> {
+  className?: string;
+}
+
+export const Surface = forwardRef<View, SurfaceProps>(
+  ({ className, variant, style, ...props }, ref) => (
+    <View
+      ref={ref}
+      // `borderCurve` has no Tailwind equivalent. On iOS it gives the
+      // continuous (squircle) corner Apple uses, which is visibly smoother
+      // than a circular arc at this radius; Android ignores it.
+      style={[styles.root, style]}
+      className={surfaceVariants({ variant, className })}
+      {...props}
+    />
+  )
+);
+
+Surface.displayName = 'Surface';
+
+const styles = StyleSheet.create({
+  root: { borderCurve: 'continuous' },
+});