panelui-native 0.66.1 → 0.68.0

package/src/components/message-scroller/index.tsx

@@ -39,9 +39,18 @@ import {
   useMemo,
   useRef,
   useState,
+  type ReactElement,
   type ReactNode,
 } from 'react';
-import { View, type LayoutChangeEvent, type ViewProps } from 'react-native';
+import {
+  FlatList,
+  View,
+  type FlatListProps,
+  type LayoutChangeEvent,
+  type ListRenderItemInfo,
+  type ViewProps,
+  type ViewToken,
+} from 'react-native';
 import Animated, {
   runOnJS,
   useAnimatedRef,
@@ -59,7 +68,10 @@ import { cn } from '../../utils/cn';
 import { textChildren } from '../../primitives/text';
 import {
   distanceFromMessageScrollerTarget,
+  initialMessageScrollerIndex,
   isMessageScrollerTargetVisible,
+  messageScrollerAnchorAt,
+  messageScrollerIndex,
   MESSAGE_SCROLLER_EDGE_THRESHOLD,
 } from './message-scroller-math';
 
@@ -72,8 +84,15 @@ const ANCHOR_PEEK = 24;
 
 export type MessageScrollerPosition = 'start' | 'end' | 'last-anchor';
 
+interface MessageScrollerDriver {
+  scrollToEnd: (animated: boolean) => void;
+  scrollToStart: (animated: boolean) => void;
+  scrollToMessage: (id: string, animated: boolean) => boolean;
+}
+
 interface MessageScrollerContextValue {
   scrollRef: ReturnType<typeof useAnimatedRef<Animated.ScrollView>>;
+  registerDriver: (driver: MessageScrollerDriver | null) => void;
   /** 1 while the reader is at the live edge, 0 otherwise. Drives follow state. */
   atEnd: ReturnType<typeof useSharedValue<number>>;
   /** Live distance from each edge, used by target-specific jump controls. */
@@ -167,6 +186,10 @@ function MessageScrollerRoot({
   const itemY = useRef(new Map<string, number>());
   const anchors = useRef<string[]>([]);
   const following = useRef(autoScroll);
+  const driver = useRef<MessageScrollerDriver | null>(null);
+  const registerDriver = useCallback((next: MessageScrollerDriver | null) => {
+    driver.current = next;
+  }, []);
 
   const registerItem = useCallback((id: string, y: number, anchor: boolean) => {
     itemY.current.set(id, y);
@@ -183,7 +206,8 @@ function MessageScrollerRoot({
   const scrollToEnd = useCallback(
     (animated = true) => {
       following.current = true;
-      scrollRef.current?.scrollToEnd({ animated });
+      if (driver.current) driver.current.scrollToEnd(animated);
+      else scrollRef.current?.scrollToEnd({ animated });
     },
     [scrollRef]
   );
@@ -191,17 +215,23 @@ function MessageScrollerRoot({
   const scrollToStart = useCallback(
     (animated = true) => {
       following.current = false;
-      scrollRef.current?.scrollTo({ y: 0, animated });
+      if (driver.current) driver.current.scrollToStart(animated);
+      else scrollRef.current?.scrollTo({ y: 0, animated });
     },
     [scrollRef]
   );
 
   const scrollToMessage = useCallback(
     (id: string, animated = true) => {
+      if (driver.current) {
+        if (driver.current.scrollToMessage(id, animated)) following.current = false;
+        return;
+      }
       const y = itemY.current.get(id);
-      if (y === undefined) return;
-      following.current = false;
-      scrollRef.current?.scrollTo({ y: Math.max(0, y - ANCHOR_PEEK), animated });
+      if (y !== undefined) {
+        following.current = false;
+        scrollRef.current?.scrollTo({ y: Math.max(0, y - ANCHOR_PEEK), animated });
+      }
     },
     [scrollRef]
   );
@@ -209,6 +239,7 @@ function MessageScrollerRoot({
   const context = useMemo<MessageScrollerContextValue>(
     () => ({
       scrollRef,
+      registerDriver,
       atEnd,
       distanceFromStart,
       distanceFromEnd,
@@ -230,6 +261,7 @@ function MessageScrollerRoot({
     }),
     [
       scrollRef,
+      registerDriver,
       atEnd,
       distanceFromStart,
       distanceFromEnd,
@@ -439,6 +471,201 @@ function MessageScrollerViewport({
 }
 MessageScrollerViewport.displayName = 'MessageScroller.Viewport';
 
+export interface MessageScrollerListItem {
+  /** Stable id used by `scrollToMessage` and as the default React key. */
+  messageId: string;
+  /** Marks the start of a turn for `last-anchor` and visibility reporting. */
+  scrollAnchor?: boolean;
+}
+
+export interface MessageScrollerListProps<T extends MessageScrollerListItem = MessageScrollerListItem>
+  extends Omit<
+    FlatListProps<T>,
+    | 'data'
+    | 'renderItem'
+    | 'keyExtractor'
+    | 'onScroll'
+    | 'onContentSizeChange'
+    | 'onViewableItemsChanged'
+    | 'maintainVisibleContentPosition'
+    | 'onScrollToIndexFailed'
+    | 'onScrollEndDrag'
+    | 'onMomentumScrollEnd'
+    | 'CellRendererComponent'
+  > {
+  className?: string;
+  /** Classes on the virtualized list's padded transcript column. */
+  contentContainerClassName?: string;
+  /**
+   * The complete transcript. Rows outside the native render window stay
+   * unmounted; each item therefore carries its stable navigation metadata.
+   */
+  data: readonly T[];
+  /** Draw one turn from the native list window. */
+  renderItem: (info: ListRenderItemInfo<T>) => ReactElement | null;
+}
+
+/**
+ * The real virtualized transcript path. Only its render window mounts; native
+ * visible-content maintenance keeps prepends still without measuring offscreen
+ * rows in JavaScript.
+ */
+function MessageScrollerList<T extends MessageScrollerListItem>({
+  className,
+  contentContainerClassName,
+  data,
+  renderItem,
+  initialNumToRender = 12,
+  maxToRenderPerBatch = 8,
+  windowSize = 7,
+  ...props
+}: MessageScrollerListProps<T>) {
+  const {
+    atEnd,
+    distanceFromStart,
+    distanceFromEnd,
+    setAtEndJS,
+    autoScroll,
+    preserveScrollOnPrepend,
+    defaultScrollPosition,
+    following,
+    registerDriver,
+    setCurrentAnchorId,
+  } = useScroller('MessageScroller.List');
+  const listRef = useRef<FlatList<T>>(null);
+  const items = useRef(data);
+  items.current = data;
+  const opened = useRef(false);
+  const firstVisibleIndex = useRef<number | null>(null);
+
+  const publishAtEnd = useCallback(
+    (next: boolean) => {
+      following.current = autoScroll && next;
+      setAtEndJS(next);
+    },
+    [autoScroll, following, setAtEndJS]
+  );
+
+  const scrollHandler = useAnimatedScrollHandler({
+    onScroll: (event) => {
+      const { contentOffset, contentSize, layoutMeasurement } = event;
+      distanceFromStart.value = distanceFromMessageScrollerTarget(
+        'start',
+        contentOffset.y,
+        contentSize.height,
+        layoutMeasurement.height
+      );
+      distanceFromEnd.value = distanceFromMessageScrollerTarget(
+        'end',
+        contentOffset.y,
+        contentSize.height,
+        layoutMeasurement.height
+      );
+      const next = isMessageScrollerTargetVisible(distanceFromEnd.value) ? 0 : 1;
+      if (next !== atEnd.value) {
+        atEnd.value = next;
+        runOnJS(publishAtEnd)(next === 1);
+      }
+    },
+  });
+
+  const scrollToIndex = useCallback((index: number, animated: boolean) => {
+    listRef.current?.scrollToIndex({ index, viewOffset: ANCHOR_PEEK, animated });
+  }, []);
+
+  const setAnchorAtIndex = useCallback(
+    (index: number) => setCurrentAnchorId(messageScrollerAnchorAt(items.current, index)),
+    [setCurrentAnchorId]
+  );
+
+  useEffect(() => {
+    registerDriver({
+      scrollToEnd: (animated) => {
+        listRef.current?.scrollToEnd({ animated });
+        setAnchorAtIndex(items.current.length - 1);
+      },
+      scrollToStart: (animated) => {
+        listRef.current?.scrollToOffset({ offset: 0, animated });
+        setAnchorAtIndex(0);
+      },
+      scrollToMessage: (id, animated) => {
+        const index = messageScrollerIndex(items.current, id);
+        if (index === undefined) return false;
+        scrollToIndex(index, animated);
+        setAnchorAtIndex(index);
+        return true;
+      },
+    });
+    return () => registerDriver(null);
+  }, [registerDriver, scrollToIndex, setAnchorAtIndex]);
+
+  useEffect(() => {
+    following.current = autoScroll && atEnd.value === 1;
+  }, [atEnd, autoScroll, following]);
+
+  const onContentSizeChange = () => {
+    if (!opened.current) {
+      opened.current = true;
+      const index = initialMessageScrollerIndex(data, defaultScrollPosition);
+      const target = index ?? data.length - 1;
+      if (index === undefined) listRef.current?.scrollToEnd({ animated: false });
+      else if (index > 0) scrollToIndex(index, false);
+      setAnchorAtIndex(target);
+      return;
+    }
+    if (following.current) listRef.current?.scrollToEnd({ animated: true });
+  };
+
+  const onViewableItemsChanged = useRef(
+    ({ viewableItems }: { viewableItems: ViewToken<T>[] }) => {
+      const first = viewableItems.reduce(
+        (best, token) => (token.index !== null && token.index < best ? token.index : best),
+        Infinity
+      );
+      firstVisibleIndex.current = Number.isFinite(first) ? first : null;
+    }
+  ).current;
+
+  const settleAnchor = () => {
+    if (firstVisibleIndex.current !== null) {
+      setCurrentAnchorId(messageScrollerAnchorAt(items.current, firstVisibleIndex.current));
+    }
+  };
+
+  return (
+    <Animated.FlatList
+      ref={listRef}
+      data={data}
+      renderItem={renderItem}
+      keyExtractor={(item) => item.messageId}
+      accessibilityRole="list"
+      accessibilityLabel="Messages"
+      accessibilityLiveRegion="polite"
+      scrollEventThrottle={16}
+      showsVerticalScrollIndicator={false}
+      initialNumToRender={initialNumToRender}
+      maxToRenderPerBatch={maxToRenderPerBatch}
+      windowSize={windowSize}
+      maintainVisibleContentPosition={
+        preserveScrollOnPrepend ? { minIndexForVisible: 0 } : undefined
+      }
+      className={cn('flex-1', className)}
+      contentContainerClassName={cn('gap-3 p-4 pb-16', contentContainerClassName)}
+      {...props}
+      onScroll={scrollHandler}
+      onContentSizeChange={onContentSizeChange}
+      onViewableItemsChanged={onViewableItemsChanged}
+      onScrollEndDrag={settleAnchor}
+      onMomentumScrollEnd={settleAnchor}
+      onScrollToIndexFailed={({ index, averageItemLength }) => {
+        listRef.current?.scrollToOffset({ offset: index * averageItemLength, animated: false });
+        setTimeout(() => scrollToIndex(index, false), 0);
+      }}
+    />
+  );
+}
+MessageScrollerList.displayName = 'MessageScroller.List';
+
 /**
  * How far the transcript shifted, measured on the message closest to the top
  * that was there before and is still there.
@@ -601,6 +828,7 @@ MessageScrollerButton.displayName = 'MessageScroller.Button';
 
 export const MessageScroller = Object.assign(MessageScrollerRoot, {
   Viewport: MessageScrollerViewport,
+  List: MessageScrollerList,
   Content: MessageScrollerContent,
   Item: MessageScrollerItem,
   Button: MessageScrollerButton,

package/src/components/message-scroller/message-scroller-math.ts

@@ -22,3 +22,41 @@ export function isMessageScrollerTargetVisible(distance: number): boolean {
 
   return distance > MESSAGE_SCROLLER_EDGE_THRESHOLD;
 }
+
+export interface MessageScrollerIndexedItem {
+  messageId: string;
+  scrollAnchor?: boolean;
+}
+
+/** Index used by initial positioning and id-addressed virtualized jumps. */
+export function messageScrollerIndex(
+  items: readonly MessageScrollerIndexedItem[],
+  id: string
+): number | undefined {
+  const index = items.findIndex((item) => item.messageId === id);
+  return index < 0 ? undefined : index;
+}
+
+/** Initial target for a list; `undefined` means use the physical end. */
+export function initialMessageScrollerIndex(
+  items: readonly MessageScrollerIndexedItem[],
+  position: 'start' | 'end' | 'last-anchor'
+): number | undefined {
+  if (position === 'end') return undefined;
+  if (position === 'start') return items.length ? 0 : undefined;
+  for (let index = items.length - 1; index >= 0; index -= 1) {
+    if (items[index]!.scrollAnchor) return index;
+  }
+  return undefined;
+}
+
+/** Anchor at or before the first visible virtualized row. */
+export function messageScrollerAnchorAt(
+  items: readonly MessageScrollerIndexedItem[],
+  firstVisibleIndex: number
+): string | null {
+  for (let index = Math.min(firstVisibleIndex, items.length - 1); index >= 0; index -= 1) {
+    if (items[index]!.scrollAnchor) return items[index]!.messageId;
+  }
+  return null;
+}

package/src/components/meter/index.tsx

@@ -0,0 +1,318 @@
+import { forwardRef, useEffect } from 'react';
+import { View, type LayoutChangeEvent, type ViewProps } from 'react-native';
+import Animated, {
+  useAnimatedStyle,
+  useReducedMotion,
+  useSharedValue,
+  withSpring,
+  withTiming,
+  type SharedValue,
+} from 'react-native-reanimated';
+import { tv, type VariantProps } from 'tailwind-variants';
+import { Text } from '../../primitives/text';
+import {
+  clamp,
+  colorFor,
+  fractionOf,
+  formatValue,
+  litSegments,
+  type MeterColor,
+  type MeterThreshold,
+} from './meter-scale';
+
+const SPRING = { damping: 20, stiffness: 180, mass: 0.6 } as const;
+/** Milliseconds for a segment to light or go out. */
+const SEGMENT_DURATION = 180;
+/** How faint an unlit segment sits. Present, but plainly not counted. */
+const SEGMENT_UNLIT = 0.22;
+
+const meterVariants = tv({
+  slots: {
+    root: 'w-full gap-2',
+    header: 'flex-row items-center justify-between gap-2',
+    track: 'w-full overflow-hidden rounded-full',
+    indicator: 'h-full rounded-full',
+    segments: 'w-full flex-row',
+    segment: 'flex-1 rounded-full',
+  },
+  variants: {
+    color: {
+      primary: { track: 'bg-primary/16', indicator: 'bg-primary', segment: 'bg-primary' },
+      success: { track: 'bg-success/16', indicator: 'bg-success', segment: 'bg-success' },
+      warning: { track: 'bg-warning/16', indicator: 'bg-warning', segment: 'bg-warning' },
+      destructive: {
+        track: 'bg-destructive/16',
+        indicator: 'bg-destructive',
+        segment: 'bg-destructive',
+      },
+      info: { track: 'bg-info/16', indicator: 'bg-info', segment: 'bg-info' },
+      muted: {
+        track: 'bg-muted',
+        indicator: 'bg-muted-foreground',
+        segment: 'bg-muted-foreground',
+      },
+    },
+    size: {
+      sm: { track: 'h-1.5', segments: 'h-1.5 gap-1', segment: 'h-1.5' },
+      md: { track: 'h-2', segments: 'h-2 gap-1.5', segment: 'h-2' },
+      lg: { track: 'h-3', segments: 'h-3 gap-1.5', segment: 'h-3' },
+    },
+  },
+  defaultVariants: {
+    color: 'primary',
+    size: 'md',
+  },
+});
+
+type MeterVariantProps = VariantProps<typeof meterVariants>;
+
+export interface MeterProps
+  extends Omit<ViewProps, 'children'>,
+    MeterVariantProps {
+  className?: string;
+  /** The measurement, somewhere between `minValue` and `maxValue`. */
+  value: number;
+  /**
+   * The bottom of the scale — the value at which the bar reads as empty.
+   * Defaults to `0`.
+   */
+  minValue?: number;
+  /**
+   * The top of the scale — the value at which the bar reads as full. Defaults
+   * to `100`, so a bare percentage needs neither bound set.
+   */
+  maxValue?: number;
+  /**
+   * What is being measured. Also the accessibility label, and a meter without
+   * one announces a number with nothing attached to it — "seventy-five
+   * percent" of what is not an answer. Pass `accessibilityLabel` instead only
+   * where the caption is drawn some other way.
+   */
+  label?: string;
+  /** Draw the value above the track, opposite the label. */
+  showValueLabel?: boolean;
+  /**
+   * Text for the value label. Overrides the formatted value — use it for a
+   * word where a number reads worse: `Strong`, `Almost full`.
+   *
+   * It is spoken whether or not it is drawn, so it can give a screen reader
+   * better words than the caption without changing the caption. Pair it with
+   * `showValueLabel` to draw it too.
+   */
+  valueLabel?: string;
+  /**
+   * How to write the value, through `Intl.NumberFormat`. A `percent` style
+   * formats how far up the scale the value sits; every other style formats
+   * the value itself, so `{ style: 'unit', unit: 'gigabyte' }` against a
+   * `maxValue` of `256` reads `64 GB` rather than a percentage of it. Falls
+   * back to a rounded percent when omitted.
+   */
+  formatOptions?: Intl.NumberFormatOptions;
+  /**
+   * Points on the scale where the colour changes, each `{ from, color }`. The
+   * highest one the reading has reached wins, so the order you list them in
+   * does not matter; below all of them the `color` prop applies.
+   *
+   * This is the difference between a meter and a bar: the colour is a
+   * judgement about the reading. Which direction is bad is yours to say —
+   * thresholds climbing to `destructive` suit a disk filling up, thresholds
+   * falling to it suit a battery running down.
+   */
+  thresholds?: MeterThreshold[];
+  /**
+   * Draw the scale as this many discrete blocks instead of one continuous
+   * bar. Blocks are all or nothing, which is the point of them: four blocks
+   * say "three out of four" where a bar says "about seventy percent", and a
+   * password is not seventy percent strong.
+   *
+   * Any value above the floor lights at least one block, so a reading that
+   * is not empty never looks it.
+   */
+  segments?: number;
+  /** Extra classes for the fill, or for a lit segment. */
+  indicatorClassName?: string;
+  /** Extra classes for the label + value row. */
+  headerClassName?: string;
+}
+
+interface SegmentProps {
+  index: number;
+  /** How many blocks are lit, as a shared value so lighting stays off the JS thread. */
+  lit: SharedValue<number>;
+  className: string;
+  reducedMotion: boolean;
+}
+
+/**
+ * One block of a segmented meter. It reads the lit count rather than a boolean
+ * so the whole row animates from one shared value, without a render per block.
+ */
+function Segment({ index, lit, className, reducedMotion }: SegmentProps) {
+  const style = useAnimatedStyle(() => {
+    const on = lit.value > index ? 1 : SEGMENT_UNLIT;
+    return {
+      opacity: reducedMotion
+        ? on
+        : withTiming(on, { duration: SEGMENT_DURATION }),
+    };
+  });
+
+  return <Animated.View style={style} className={className} />;
+}
+
+/**
+ * A measurement on a fixed scale: disk used, battery left, a score, a password's
+ * strength. The fill is driven on the UI thread, so a value change costs one
+ * render and nothing per frame.
+ *
+ * A meter is not a progress bar. Progress is a task moving towards an end that
+ * finishing is the point of; a meter is a reading that happens to sit where it
+ * sits, and may go back down. Reach for
+ * [Progress](/docs/components/progress) when something is completing.
+ *
+ * `thresholds` paint the bar by where the reading falls, and `segments` draws
+ * the scale as discrete blocks for readings that are counted rather than
+ * measured.
+ *
+ * The value is read against `minValue` / `maxValue`, which default to 0 and
+ * 100 — so a percentage needs neither. Set them and the meter speaks in
+ * whatever is being measured: bytes, degrees, points. Nothing has to be
+ * converted to a percent on the way in, and the screen reader is told the real
+ * scale rather than a derived one.
+ *
+ * React Native has no meter role, so this announces as a progress bar with its
+ * value, range and unit attached. That is the closest the platform offers, and
+ * it is why `label` matters: the role will not distinguish a reading from a
+ * task, and the name is what does.
+ */
+export const Meter = forwardRef<View, MeterProps>(
+  (
+    {
+      className,
+      indicatorClassName,
+      headerClassName,
+      value,
+      minValue = 0,
+      maxValue = 100,
+      label,
+      showValueLabel = false,
+      valueLabel,
+      formatOptions,
+      thresholds,
+      segments,
+      color,
+      size,
+      accessibilityLabel,
+      ...props
+    },
+    ref
+  ) => {
+    const held = clamp(value, minValue, maxValue);
+    const fraction = fractionOf(value, minValue, maxValue);
+    const resolvedColor = colorFor(held, color ?? 'primary', thresholds);
+    const slots = meterVariants({ color: resolvedColor, size });
+    const reducedMotion = useReducedMotion();
+
+    const trackWidth = useSharedValue(0);
+    const progress = useSharedValue(fraction);
+    // Any reading above the floor lights a block, so "a little" never looks
+    // like "none". Rounding down would leave the first quarter of a
+    // four-block meter dark, which is the reading it is least able to afford.
+    const litCount = segments ? litSegments(fraction, segments) : 0;
+    const lit = useSharedValue(litCount);
+
+    // Reduce motion lands on the value instead of springing to it — the
+    // number is the information, and the overshoot is decoration.
+    useEffect(() => {
+      progress.value = reducedMotion ? fraction : withSpring(fraction, SPRING);
+    }, [fraction, progress, reducedMotion]);
+
+    useEffect(() => {
+      lit.value = litCount;
+    }, [lit, litCount]);
+
+    const onLayout = (event: LayoutChangeEvent) => {
+      trackWidth.value = event.nativeEvent.layout.width;
+    };
+
+    const fillStyle = useAnimatedStyle(() => ({
+      width: trackWidth.value * progress.value,
+    }));
+
+    const spoken = formatValue(held, fraction, valueLabel, formatOptions);
+    const showValue = showValueLabel;
+    const hasHeader = label != null || showValue;
+
+    const accessibility = {
+      accessibilityRole: 'progressbar' as const,
+      accessibilityLabel: accessibilityLabel ?? label,
+      accessibilityValue: {
+        min: minValue,
+        max: maxValue,
+        now: held,
+        // Without this the scale is read as a bare number. `text` is what
+        // carries the unit — the percent sign, the gigabytes, the word.
+        text: spoken,
+      },
+    };
+
+    const bar =
+      segments && segments > 0 ? (
+        <View
+          ref={ref}
+          {...accessibility}
+          className={slots.segments({ className })}
+          {...props}
+        >
+          {Array.from({ length: segments }, (_, index) => (
+            <Segment
+              key={index}
+              index={index}
+              lit={lit}
+              reducedMotion={reducedMotion}
+              className={slots.segment({ className: indicatorClassName })}
+            />
+          ))}
+        </View>
+      ) : (
+        <View
+          ref={ref}
+          {...accessibility}
+          className={slots.track({ className })}
+          onLayout={onLayout}
+          {...props}
+        >
+          <Animated.View
+            style={fillStyle}
+            className={slots.indicator({ className: indicatorClassName })}
+          />
+        </View>
+      );
+
+    if (!hasHeader) return bar;
+
+    return (
+      <View className={slots.root()}>
+        <View className={slots.header({ className: headerClassName })}>
+          {label != null ? (
+            <Text size="sm" weight="medium" numberOfLines={1}>
+              {label}
+            </Text>
+          ) : (
+            <View />
+          )}
+          {showValue ? (
+            <Text size="sm" muted numberOfLines={1}>
+              {spoken}
+            </Text>
+          ) : null}
+        </View>
+        {bar}
+      </View>
+    );
+  }
+);
+
+Meter.displayName = 'Meter';
+
+export type { MeterColor, MeterThreshold };