panelui-native 0.75.1 → 0.77.0

package/src/components/alert/index.tsx

@@ -91,9 +91,9 @@ const AlertRoot = forwardRef<View, AlertProps>(
       <AlertContext.Provider value={variant}>
         <View
           ref={ref}
+          {...props}
           accessibilityRole="alert"
           className={root({ className })}
-          {...props}
         >
           {icon ? (
             <>

package/src/components/avatar/avatar-source.ts

@@ -0,0 +1,18 @@
+import type { ImageSourcePropType } from 'react-native';
+
+function stableValue(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(stableValue).join(',')}]`;
+  if (value && typeof value === 'object') {
+    return `{${Object.entries(value)
+      .filter(([, entry]) => entry !== undefined)
+      .sort(([left], [right]) => left.localeCompare(right))
+      .map(([key, entry]) => `${JSON.stringify(key)}:${stableValue(entry)}`)
+      .join(',')}}`;
+  }
+  return JSON.stringify(value) ?? String(value);
+}
+
+/** Stable across equivalent inline source objects, but changes with request inputs. */
+export function avatarSourceIdentity(source: ImageSourcePropType | undefined) {
+  return source === undefined ? undefined : stableValue(source);
+}

package/src/components/avatar/index.tsx

@@ -22,6 +22,7 @@ import {
   avatarGroupOverlap,
   type AvatarSizeName,
 } from './avatar-group';
+import { avatarSourceIdentity } from './avatar-source';
 
 const avatarVariants = tv({
   slots: {
@@ -53,16 +54,20 @@ export interface AvatarProps extends ViewProps, VariantProps<typeof avatarVarian
 
 const AvatarRoot = forwardRef<View, AvatarProps>(
   ({ className, size, source, fallback, imageProps, children, ...props }, ref) => {
-    const [errored, setErrored] = useState(false);
+    const [failedSource, setFailedSource] = useState<string>();
     const { root, image, fallback: fallbackSlot } = avatarVariants({ size });
-    const showImage = !!source && !errored;
+    const sourceIdentity = avatarSourceIdentity(source);
+    const showImage = !!source && failedSource !== sourceIdentity;
 
     const face = showImage ? (
       <Image
-        source={source}
-        onError={() => setErrored(true)}
         className={image()}
         {...imageProps}
+        source={source}
+        onError={(event) => {
+          setFailedSource(sourceIdentity);
+          imageProps?.onError?.(event);
+        }}
       />
     ) : (
       <Text className={fallbackSlot()}>{fallback ?? '?'}</Text>
@@ -149,11 +154,9 @@ export interface AvatarGroupProps extends ViewProps {
  * A row of avatars, each overlapping the one after it, with the people who did
  * not fit counted at the end.
  *
- * The faces are drawn back to front — the first is on top — which is why the
- * row lays itself out in reverse: later siblings paint over earlier ones, so
- * the stacking order and the reading order pull against each other and one of
- * them has to be flipped. Flipping the layout keeps the children in the order
- * they were written.
+ * The faces stay in logical child order for assistive traversal. Explicit
+ * z-indices, rather than a reversed render/layout order, put the first face on
+ * top while the overflow count remains the final list item.
  *
  * Each face gets a ring in the page background so it separates from the one
  * underneath whatever surface the stack sits on.
@@ -172,10 +175,21 @@ const AvatarGroup = forwardRef<View, AvatarGroupProps>(
     const { visible, overflow } = avatarGroupCount(faces.length, max, total);
     const slide = avatarGroupOverlap(size, overlap);
 
-    // Back to front: the count sits under the last face, which sits under the
-    // one before it, and so on up to the first.
+    // Logical reading order: visible people first, then the overflow summary.
+    // Painting order is independent and applied to each wrapper below.
     const stack: { key: string; node: ReactNode }[] = [];
 
+    for (let index = 0; index < visible; index += 1) {
+      const face = faces[index]!;
+      stack.push({
+        key: String(face.key ?? index),
+        node: cloneElement(face, {
+          size: face.props.size ?? size,
+          className: cn('border-2 border-background', face.props.className),
+        }),
+      });
+    }
+
     if (overflow > 0) {
       stack.push({
         key: 'overflow',
@@ -190,28 +204,22 @@ const AvatarGroup = forwardRef<View, AvatarGroupProps>(
       });
     }
 
-    for (let index = visible - 1; index >= 0; index -= 1) {
-      const face = faces[index]!;
-      stack.push({
-        key: String(face.key ?? index),
-        node: cloneElement(face, {
-          size: face.props.size ?? size,
-          className: cn('border-2 border-background', face.props.className),
-        }),
-      });
-    }
-
     return (
       <View
         ref={ref}
-        accessibilityRole="list"
-        className={cn('flex-row-reverse self-start', className)}
+        className={cn('flex-row self-start', className)}
         {...props}
+        accessibilityRole="list"
       >
         {stack.map((entry, index) => (
-          // The first node laid out is the trailing one, and it is the only one
-          // with nothing to slide under.
-          <View key={entry.key} style={index === 0 ? undefined : { marginEnd: -slide }}>
+          <View
+            key={entry.key}
+            role="listitem"
+            style={{
+              zIndex: stack.length - index,
+              marginStart: index === 0 ? 0 : -slide,
+            }}
+          >
             {entry.node}
           </View>
         ))}

package/src/components/bottom-sheet/index.tsx

@@ -224,6 +224,15 @@ export interface BottomSheetContentProps extends ViewProps {
    * affordances.
    */
   showClose?: boolean;
+  /**
+   * Show the drag handle at the top of the sheet. On by default, because a
+   * sheet that can be dragged should say so.
+   *
+   * Turn it off when the sheet draws its own — a component wrapping this one
+   * to give the surface a material of its own has to put the handle on that
+   * material, and a handle floating above it belongs to nothing.
+   */
+  showGrabber?: boolean;
   /**
    * Float the sheet clear of the screen edges instead of docking it to the
    * bottom, so it reads as a card laid over the app rather than a drawer
@@ -267,6 +276,7 @@ function BottomSheetContent({
   className,
   dismissible = true,
   showClose = true,
+  showGrabber = true,
   detached = false,
   blur = false,
   size = 'auto',
@@ -398,7 +408,7 @@ function BottomSheetContent({
     // sheet cannot measure RN views directly. Without it the sheet sizes to
     // nothing and the content spills outside its container.
     return (
-      <Host matchContents style={{ position: 'absolute' }}>
+      <Host matchContents ignoreSafeArea="keyboard" style={{ position: 'absolute' }}>
         <NativeBottomSheet
           isPresented={open}
           onDismiss={dismissible ? close : () => {}}
@@ -475,9 +485,11 @@ function BottomSheetContent({
             ]}
           >
             <SheetSurfaceContext.Provider value={surface}>
-              <View className="mb-3 self-center">
-                <View className="h-1 w-10 rounded-full bg-muted-foreground/30" />
-              </View>
+              {showGrabber ? (
+                <View className="mb-3 self-center">
+                  <View className="h-1 w-10 rounded-full bg-muted-foreground/30" />
+                </View>
+              ) : null}
               {textChildren(children)}
               {/*
                 * Last, and lifted above the content.

package/src/components/button/index.tsx

@@ -207,6 +207,21 @@ export interface ButtonProps
    * default capsule.
    */
   glass?: boolean;
+  /**
+   * A glyph beside the label, named from the platform's own symbol set rather
+   * than passed as an element.
+   *
+   * This is how a labelled native button gets an icon at all. Elements have to
+   * be hosted inside the native tree, and a hosted view inside a labelled
+   * button has no width anything can resolve — so a name is not a shortcut
+   * here, it is the only form that works. The platform draws it, at its own
+   * size, in the label's colour.
+   *
+   * iOS only, and `native` only. Android's toolkit has no equivalent symbol
+   * set, so a button there is its label alone; the drawn button takes
+   * `startContent` and always did.
+   */
+  systemImage?: string;
 }
 
 /**
@@ -299,6 +314,7 @@ export const Button = forwardRef<View, ButtonProps>(
       startContent,
       endContent,
       native,
+      systemImage,
       glass = false,
       accessibilityState,
       ...props
@@ -379,9 +395,12 @@ export const Button = forwardRef<View, ButtonProps>(
       const nativeContent = prominent ? '#ffffff' : contentColor;
 
       return (
-        <Host matchContents>
+        <Host matchContents ignoreSafeArea="keyboard">
           <NativeButton
             label={isStringLabel ? children : undefined}
+            // The platform only reads a symbol beside a label it drew itself,
+            // so an icon button — which has no label — never carries one.
+            systemImage={isStringLabel ? systemImage : undefined}
             variant={NATIVE_VARIANT[resolvedVariant ?? 'primary']}
             disabled={isDisabled}
             /*

package/src/components/button-group/index.tsx

@@ -171,11 +171,11 @@ const ButtonGroupRoot = forwardRef<View, ButtonGroupProps>(
       <ButtonGroupProvider value={context}>
         <View
           ref={ref}
+          {...props}
           // A run of related actions is a toolbar; a screen reader announcing
           // the group is what tells someone the buttons in it belong together.
           accessibilityRole="toolbar"
           className={root({ className })}
-          {...props}
         >
           {items.map((child, index) => (
             // Index keys: these fragments have no identity of their own, and

package/src/components/carousel/index.tsx

@@ -74,6 +74,7 @@ import Animated, {
   type SharedValue,
 } from 'react-native-reanimated';
 import { ChevronLeftIcon, ChevronRightIcon } from '../../icons';
+import { useControllableState } from '../../primitives/controllable-state';
 import { Text, textChildren } from '../../primitives/text';
 import { cn } from '../../utils/cn';
 import {
@@ -264,14 +265,20 @@ const CarouselRoot = forwardRef<CarouselHandle, CarouselProps>(function Carousel
   ref
 ) {
   const [size, setSize] = useState({ width: 0, height: 0 });
-  const [internalIndex, setInternalIndex] = useState(defaultIndex);
   const [count, setCountValue] = useState(0);
   const [countKnown, setCountKnown] = useState(false);
   const [touched, setTouched] = useState(false);
   const reducedMotion = useReducedMotion();
 
-  const isControlled = indexProp !== undefined;
-  const requestedIndex = isControlled ? indexProp : internalIndex;
+  const {
+    value: requestedIndex,
+    setValue: setIndex,
+    isControlled,
+  } = useControllableState({
+    value: indexProp,
+    defaultValue: defaultIndex,
+    onChange: onIndexChange,
+  });
 
   const progress = useSharedValue(indexProp ?? defaultIndex);
   const engaged = useSharedValue(0);
@@ -287,14 +294,6 @@ const CarouselRoot = forwardRef<CarouselHandle, CarouselProps>(function Carousel
     setCountKnown(true);
   }, []);
 
-  const setIndex = useCallback(
-    (next: number) => {
-      if (!isControlled) setInternalIndex(next);
-      onIndexChange?.(next);
-    },
-    [isControlled, onIndexChange]
-  );
-
   /*
    * The slide the run is currently travelling to.
    *

package/src/components/collapsible/index.tsx

@@ -180,11 +180,11 @@ const CollapsibleTrigger = forwardRef<View, CollapsibleTriggerProps>(
     return (
       <Pressable
         ref={ref}
+        {...props}
         accessibilityRole="button"
         accessibilityState={{ expanded: open, disabled: isDisabled }}
         disabled={isDisabled}
         className={trigger({ className })}
-        {...props}
         onPress={(event) => {
           onPress?.(event);
           toggle();

package/src/components/field/index.tsx

@@ -140,10 +140,10 @@ const FieldRoot = forwardRef<View, FieldProps>(
       <FieldContext.Provider value={state}>
         <View
           ref={ref}
+          {...props}
           role="group"
           accessibilityState={{ disabled }}
           className={root({ className })}
-          {...props}
         >
           {textChildren(children)}
         </View>
@@ -242,13 +242,13 @@ const FieldError = forwardRef<View, FieldErrorProps>(
     return (
       <View
         ref={ref}
+        {...props}
         // Web-aligned `role`, same as `Separator` already uses — RN's older
         // accessibilityRole list has no alert, the ARIA-aligned one does.
         role="alert"
         accessibilityLiveRegion="polite"
         nativeID={nativeID ?? relationshipIds[3]}
         className={error({ className })}
-        {...props}
       >
         {messages ? (
           messages.length === 1 ? (
@@ -278,7 +278,7 @@ export interface FieldSetProps extends ViewProps {
 const FieldSet = forwardRef<View, FieldSetProps>(
   ({ className, ...props }, ref) => {
     const { set } = fieldVariants();
-    return <View ref={ref} role="group" className={set({ className })} {...props} />;
+    return <View ref={ref} {...props} role="group" className={set({ className })} />;
   }
 );
 FieldSet.displayName = 'Field.Set';
@@ -293,7 +293,7 @@ const FieldLegend = forwardRef<RNText, FieldLegendProps>(
   ({ className, variant = 'legend', ...props }, ref) => {
     const { legend } = fieldVariants({ legendVariant: variant });
     return (
-      <Text ref={ref} role="heading" className={legend({ className })} {...props} />
+      <Text ref={ref} {...props} role="heading" className={legend({ className })} />
     );
   }
 );

package/src/components/label/index.tsx

@@ -81,9 +81,9 @@ const LabelRoot = forwardRef<View, LabelProps>(
       <LabelContext.Provider value={state}>
         <View
           ref={ref}
+          {...props}
           className={root({ className })}
           accessibilityState={{ disabled: isDisabled }}
-          {...props}
         >
           {/* Bare strings are the common case — wrap them so callers don't have to. */}
           {textChildren(children, (text) => <LabelText>{text}</LabelText>)}

package/src/components/marquee/index.tsx

@@ -15,10 +15,11 @@
  * ## How it loops
  *
  * The content is measured once, then laid out end to end enough times to cover
- * the container twice over. One track holds every copy and it is that track,
- * not the copies, that moves — a single animated node for any amount of
- * content. It travels exactly one copy-and-gap and starts over, so the state it
- * ends on is the state it began on and the seam never shows.
+ * the container. One track holds every copy and it is that track, not the
+ * copies, that moves. The track has a fixed copy budget: exceptionally short
+ * content gets extra whitespace instead of multiplying its React subtree
+ * hundreds of times. It travels exactly one layout period and starts over, so
+ * the state it ends on is the state it began on and the seam never shows.
  *
  * The travel is a linear timing driven on the UI thread, so it costs nothing
  * per frame in JavaScript and keeps running while the thread is busy.
@@ -43,8 +44,10 @@
  * Screen readers get one copy. The rest are duplicates of content already
  * announced, and hearing a sponsor list four times over is not thoroughness.
  */
-import { useEffect, useMemo, useState, type ReactNode } from 'react';
+import { useEffect, useMemo, useState, type ComponentType, type ReactNode } from 'react';
 import {
+  Platform,
+  Pressable,
   ScrollView,
   StyleSheet,
   View,
@@ -61,6 +64,7 @@ import Animated, {
   withTiming,
 } from 'react-native-reanimated';
 import { useDirectionSign } from '../../hooks/use-direction';
+import { Text } from '../../primitives/text';
 import { cn } from '../../utils/cn';
 import {
   DEFAULT_MARQUEE_SPEED,
@@ -70,6 +74,9 @@ import {
 
 export type MarqueeDirection = 'horizontal' | 'vertical';
 
+type InertViewProps = ViewProps & { inert?: boolean };
+const InertView = View as ComponentType<InertViewProps>;
+
 export interface MarqueeProps extends Omit<ViewProps, 'children'> {
   className?: string;
   /** The content to repeat. Measured once, then tiled along the axis. */
@@ -81,7 +88,7 @@ export interface MarqueeProps extends Omit<ViewProps, 'children'> {
    * rather than moving faster.
    */
   speed?: number;
-  /** Gap between the end of one copy and the start of the next. */
+  /** Minimum gap between the end of one copy and the start of the next. */
   spacing?: number;
   /** Axis the content travels along. */
   direction?: MarqueeDirection;
@@ -92,6 +99,14 @@ export interface MarqueeProps extends Omit<ViewProps, 'children'> {
   reverse?: boolean;
   /** Set false to hold the content where it is. */
   playing?: boolean;
+  /** Show the built-in user pause/play control while motion is enabled. */
+  showPauseControl?: boolean;
+  /** Visible and spoken label for the moving state. */
+  pauseLabel?: string;
+  /** Visible and spoken label for the user-paused state. */
+  playLabel?: string;
+  /** Reports changes made by the built-in control. */
+  onPlayingChange?: (playing: boolean) => void;
 }
 
 export function Marquee({
@@ -102,6 +117,10 @@ export function Marquee({
   direction = 'horizontal',
   reverse = false,
   playing = true,
+  showPauseControl = true,
+  pauseLabel = 'Pause',
+  playLabel = 'Play',
+  onPlayingChange,
   style,
   onLayout,
   ...props
@@ -114,7 +133,9 @@ export function Marquee({
 
   const [viewport, setViewport] = useState(0);
   const [content, setContent] = useState(0);
+  const [userPaused, setUserPaused] = useState(false);
   const speed = normalizeMarqueeSpeed(speedProp);
+  const moving = playing && !userPaused;
 
   // The distance from one copy to the same point on the next, and therefore
   // both the layout step and the exact loop length. They are the same number
@@ -136,7 +157,7 @@ export function Marquee({
   useEffect(() => {
     cancelAnimation(offset);
     offset.value = 0;
-    if (reducedMotion || !playing || period <= 0 || speed <= 0) return undefined;
+    if (reducedMotion || !moving || period <= 0 || speed <= 0) return undefined;
     offset.value = withRepeat(
       withTiming(period, {
         duration: (period / speed) * 1000,
@@ -146,7 +167,7 @@ export function Marquee({
       false
     );
     return () => cancelAnimation(offset);
-  }, [offset, period, playing, reducedMotion, speed]);
+  }, [offset, period, moving, reducedMotion, speed]);
 
   const trackStyle = useAnimatedStyle(() => {
     const travel = (reverse ? offset.value : -offset.value) * flip;
@@ -200,7 +221,12 @@ export function Marquee({
         accessibilityElementsHidden
         importantForAccessibility="no-hide-descendants"
       >
-        <View onLayout={onContentLayout}>{children}</View>
+        <InertView
+          inert={Platform.OS === 'web' ? true : undefined}
+          onLayout={onContentLayout}
+        >
+          {children}
+        </InertView>
       </ScrollView>
 
       <Animated.View style={[StyleSheet.absoluteFill, trackStyle]} pointerEvents="box-none">
@@ -210,18 +236,36 @@ export function Marquee({
           const spoken = index === 1;
           const at = (index - 1) * period;
           return (
-            <View
+            <InertView
               key={index}
               style={[styles.copy, horizontal ? { left: at } : { top: at }]}
-              pointerEvents="box-none"
+              pointerEvents={spoken ? 'box-none' : 'none'}
+              inert={Platform.OS === 'web' && !spoken ? true : undefined}
+              aria-hidden={!spoken}
               accessibilityElementsHidden={!spoken}
               importantForAccessibility={spoken ? 'auto' : 'no-hide-descendants'}
             >
               {children}
-            </View>
+            </InertView>
           );
         })}
       </Animated.View>
+      {showPauseControl && playing && period > 0 && speed > 0 ? (
+        <Pressable
+          accessibilityRole="button"
+          accessibilityLabel={userPaused ? playLabel : pauseLabel}
+          className="absolute bottom-2 end-2 min-h-12 min-w-12 items-center justify-center rounded-full border border-border bg-background/95 px-3"
+          onPress={() => {
+            const next = !userPaused;
+            setUserPaused(next);
+            onPlayingChange?.(!next);
+          }}
+        >
+          <Text className="text-xs font-medium text-foreground">
+            {userPaused ? playLabel : pauseLabel}
+          </Text>
+        </Pressable>
+      ) : null}
     </View>
   );
 }

package/src/components/marquee/marquee-math.ts

@@ -14,6 +14,13 @@
  */
 export const DEFAULT_MARQUEE_SPEED = 40;
 
+/**
+ * Includes the copy just before and just after the viewport. Keeping this
+ * fixed prevents tiny content (for example a one-point separator) from
+ * multiplying an arbitrary React subtree hundreds of times.
+ */
+export const MAX_MARQUEE_COPIES = 32;
+
 export function normalizeMarqueeSpeed(value: number): number {
   if (!Number.isFinite(value)) return DEFAULT_MARQUEE_SPEED;
   return Math.max(value, 0);
@@ -31,7 +38,23 @@ export function marqueeCopyCount(
 ): { period: number; count: number } {
   const safeViewport = Number.isFinite(viewport) ? Math.max(viewport, 0) : 0;
   const safeContent = Number.isFinite(content) ? Math.max(content, 0) : 0;
-  const period = safeContent > 0 ? safeContent + normalizeMarqueeSpacing(spacing) : 0;
-  if (period <= 0 || safeViewport <= 0) return { period, count: 0 };
-  return { period, count: Math.ceil(safeViewport / period) + 2 };
+  const naturalPeriod =
+    safeContent > 0 ? safeContent + normalizeMarqueeSpacing(spacing) : 0;
+  if (naturalPeriod <= 0 || safeViewport <= 0) {
+    return { period: naturalPeriod, count: 0 };
+  }
+
+  // Two copies sit outside the viewport to cover one complete loop. If the
+  // requested content-and-gap period would need more than the remaining copy
+  // budget, widen the layout period (effectively adding whitespace) instead
+  // of mounting an unbounded number of identical subtrees.
+  const minimumPeriod = safeViewport / (MAX_MARQUEE_COPIES - 2);
+  const period = Math.max(naturalPeriod, minimumPeriod);
+  return {
+    period,
+    count: Math.min(
+      MAX_MARQUEE_COPIES,
+      Math.ceil(safeViewport / period) + 2
+    ),
+  };
 }

package/src/components/plan/index.tsx

@@ -296,11 +296,15 @@ function PlanTitle({ className, children, ...props }: PlanTitleProps) {
   const { title } = planVariants();
 
   if (isStreaming && typeof children === 'string') {
-    return <Shimmer textClassName={cn(title(), className)}>{children}</Shimmer>;
+    return (
+      <Shimmer accessibilityRole="header" textClassName={cn(title(), className)}>
+        {children}
+      </Shimmer>
+    );
   }
 
   return (
-    <Text accessibilityRole="header" className={cn(title(), className)} {...props}>
+    <Text {...props} accessibilityRole="header" className={cn(title(), className)}>
       {children}
     </Text>
   );