panelui-native 0.25.0 → 0.30.0

package/src/components/reasoning/index.tsx

@@ -0,0 +1,297 @@
+/**
+ * Reasoning — the model's working, shown while it happens and folded away after.
+ *
+ * A reasoning trace is interesting for exactly as long as it is the only thing
+ * arriving. Once the answer starts, it is a wall of text above the thing the
+ * reader actually asked for. So it opens itself when the trace starts streaming
+ * and closes itself about a second after it stops — once, and only if it ever
+ * streamed, because a trace that arrives complete was never a live thing to
+ * watch and should not perform.
+ *
+ * The trigger changes with it: a shimmering "Thinking…" while the tokens are
+ * coming, and "Thought for 8 seconds" afterwards. The duration is measured from
+ * the first streaming frame rather than taken on trust, so it is the time the
+ * reader actually waited.
+ *
+ * ```tsx
+ * <Reasoning isStreaming={streaming}>
+ *   <Reasoning.Trigger />
+ *   <Reasoning.Content>{text}</Reasoning.Content>
+ * </Reasoning>
+ * ```
+ *
+ * ## Where the props come from
+ *
+ * With the AI SDK, `isStreaming` is whether the last part of the last message
+ * is a reasoning part while the request is still streaming, and the content is
+ * every `reasoning` part joined together. Joined, not one component each:
+ * some models emit a run of separate reasoning parts, and one component per
+ * part is a column of "Thinking…" rows for a single thought.
+ */
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  type ReactNode,
+} from 'react';
+import { Pressable, View, type PressableProps, type ViewProps } from 'react-native';
+import Animated, {
+  useAnimatedStyle,
+  useReducedMotion,
+  useSharedValue,
+  withTiming,
+} from 'react-native-reanimated';
+import { tv } from 'tailwind-variants';
+import { ChevronDownIcon, SparklesIcon } from '../../icons';
+import { Collapse } from '../../primitives/collapse';
+import { Text, textChildren } from '../../primitives/text';
+import { cn } from '../../utils/cn';
+import { Shimmer } from '../shimmer';
+
+/**
+ * How long the finished trace stays open before folding away.
+ *
+ * Long enough that the fold reads as a consequence of the trace ending rather
+ * than as part of it, short enough that nobody is waiting on it.
+ */
+const AUTO_CLOSE_DELAY = 1000;
+
+const reasoningVariants = tv({
+  slots: {
+    root: 'w-full gap-2',
+    trigger: 'flex-row items-center gap-2 py-0.5',
+    label: 'text-sm text-muted-foreground',
+    content: 'gap-2 ps-6',
+    contentText: 'text-sm leading-relaxed text-muted-foreground',
+  },
+});
+
+interface ReasoningContextValue {
+  isStreaming: boolean;
+  open: boolean;
+  setOpen: (open: boolean) => void;
+  /** Seconds the trace took, once it has finished. */
+  duration: number | undefined;
+}
+
+const ReasoningContext = createContext<ReasoningContextValue | null>(null);
+
+function useReasoning(component: string): ReasoningContextValue {
+  const context = useContext(ReasoningContext);
+  if (!context) {
+    throw new Error(`${component} must be used within a <Reasoning>`);
+  }
+  return context;
+}
+
+export interface ReasoningProps extends Omit<ViewProps, 'children'> {
+  className?: string;
+  /**
+   * Whether the trace is still arriving. Drives the shimmer on the trigger,
+   * opens the panel on the way in and closes it a beat after it goes false.
+   */
+  isStreaming?: boolean;
+  /**
+   * How long the trace took, in seconds. Measured from the first streaming
+   * frame when it is not given, which is the number worth showing — it is what
+   * the reader actually waited.
+   */
+  duration?: number;
+  /** Controlled open state. */
+  open?: boolean;
+  /**
+   * Initial state when uncontrolled. Defaults to whether it is streaming, so a
+   * live trace is open and a finished one arrives folded. Passing `false`
+   * explicitly also opts out of the auto-open.
+   */
+  defaultOpen?: boolean;
+  onOpenChange?: (open: boolean) => void;
+  children?: ReactNode;
+}
+
+function ReasoningRoot({
+  className,
+  isStreaming = false,
+  duration: durationProp,
+  open: openProp,
+  defaultOpen,
+  onOpenChange,
+  children,
+  ...props
+}: ReasoningProps) {
+  const { root } = reasoningVariants();
+  const [internalOpen, setInternalOpen] = useState(defaultOpen ?? isStreaming);
+  const [measured, setMeasured] = useState<number>();
+
+  const isControlled = openProp !== undefined;
+  const open = isControlled ? openProp : internalOpen;
+
+  const setOpen = useCallback(
+    (next: boolean) => {
+      if (!isControlled) setInternalOpen(next);
+      onOpenChange?.(next);
+    },
+    [isControlled, onOpenChange]
+  );
+
+  /*
+   * A caller that said `defaultOpen={false}` meant it. Without this the panel
+   * would spring open the moment the trace started, which is the one thing that
+   * request was asking not to happen.
+   */
+  const optedOut = defaultOpen === false;
+  const everStreamed = useRef(isStreaming);
+  const startedAt = useRef<number | null>(null);
+  const [autoClosed, setAutoClosed] = useState(false);
+
+  // Timed here rather than taken on trust: `duration` is optional, and the
+  // honest number is the wall clock between the first token and the last.
+  useEffect(() => {
+    if (isStreaming) {
+      everStreamed.current = true;
+      startedAt.current ??= Date.now();
+      return;
+    }
+    if (startedAt.current !== null) {
+      setMeasured(Math.max(1, Math.round((Date.now() - startedAt.current) / 1000)));
+      startedAt.current = null;
+    }
+  }, [isStreaming]);
+
+  useEffect(() => {
+    if (isStreaming && !open && !optedOut) setOpen(true);
+  }, [isStreaming, open, optedOut, setOpen]);
+
+  /*
+   * Once only. Without the latch, reopening a finished trace by hand would be
+   * undone a second later by the same effect, and the panel would refuse to
+   * stay open for the one reader who wanted to read it.
+   */
+  useEffect(() => {
+    if (!everStreamed.current || isStreaming || !open || autoClosed) return;
+    const timer = setTimeout(() => {
+      setOpen(false);
+      setAutoClosed(true);
+    }, AUTO_CLOSE_DELAY);
+    return () => clearTimeout(timer);
+  }, [isStreaming, open, autoClosed, setOpen]);
+
+  const context = useMemo(
+    () => ({ isStreaming, open, setOpen, duration: durationProp ?? measured }),
+    [isStreaming, open, setOpen, durationProp, measured]
+  );
+
+  return (
+    <ReasoningContext.Provider value={context}>
+      <View {...props} className={cn(root(), className)}>
+        {children}
+      </View>
+    </ReasoningContext.Provider>
+  );
+}
+ReasoningRoot.displayName = 'Reasoning';
+
+export interface ReasoningTriggerProps
+  extends Omit<PressableProps, 'children' | 'style'> {
+  className?: string;
+  /**
+   * What the row says. Given the streaming state and the measured duration, so
+   * a caller can put its own words to both without reimplementing the timing.
+   */
+  label?: (isStreaming: boolean, duration?: number) => ReactNode;
+  /** Replaces the whole row, icon and chevron included. */
+  children?: ReactNode;
+}
+
+/** The row that says how long it thought, and folds the trace away. */
+function ReasoningTrigger({ className, label, children, onPress, ...props }: ReasoningTriggerProps) {
+  const { isStreaming, open, setOpen, duration } = useReasoning('Reasoning.Trigger');
+  const { trigger, label: labelClass } = reasoningVariants();
+  const reducedMotion = useReducedMotion();
+  const progress = useSharedValue(open ? 1 : 0);
+
+  useEffect(() => {
+    progress.value = reducedMotion
+      ? open
+        ? 1
+        : 0
+      : withTiming(open ? 1 : 0, { duration: 180 });
+  }, [open, reducedMotion, progress]);
+
+  const chevronStyle = useAnimatedStyle(() => ({
+    transform: [{ rotate: `${progress.value * 180}deg` }],
+  }));
+
+  const body = label ? (
+    label(isStreaming, duration)
+  ) : isStreaming ? (
+    <Shimmer textClassName={labelClass()}>Thinking…</Shimmer>
+  ) : (
+    <Text className={labelClass()}>
+      {duration === undefined
+        ? 'Thought for a few seconds'
+        : `Thought for ${duration} ${duration === 1 ? 'second' : 'seconds'}`}
+    </Text>
+  );
+
+  return (
+    <Pressable
+      accessibilityRole="button"
+      accessibilityState={{ expanded: open }}
+      onPress={(event) => {
+        onPress?.(event);
+        setOpen(!open);
+      }}
+      className={cn(trigger(), className)}
+      {...props}
+    >
+      {children ?? (
+        <>
+          <SparklesIcon size={16} />
+          <View className="flex-1">{body}</View>
+          <Animated.View style={chevronStyle}>
+            <ChevronDownIcon size={16} />
+          </Animated.View>
+        </>
+      )}
+    </Pressable>
+  );
+}
+
+export interface ReasoningContentProps extends Omit<ViewProps, 'children'> {
+  className?: string;
+  /** The trace. A string is wrapped for you; anything else is left alone. */
+  children?: ReactNode;
+}
+
+/**
+ * The trace itself.
+ *
+ * Kept mounted and collapsed to nothing rather than unmounted, because it is
+ * usually still growing while it is folded — and a body that remounts on every
+ * open would drop whatever the reader had scrolled to.
+ */
+function ReasoningContent({ className, children, ...props }: ReasoningContentProps) {
+  const { open } = useReasoning('Reasoning.Content');
+  const { content, contentText } = reasoningVariants();
+
+  return (
+    <Collapse open={open} className={cn(content(), className)} {...props}>
+      {textChildren(children, (text) => (
+        <Text className={contentText()}>{text}</Text>
+      ))}
+    </Collapse>
+  );
+}
+
+ReasoningTrigger.displayName = 'Reasoning.Trigger';
+ReasoningContent.displayName = 'Reasoning.Content';
+
+export const Reasoning = Object.assign(ReasoningRoot, {
+  Trigger: ReasoningTrigger,
+  Content: ReasoningContent,
+});

package/src/components/section-rail/index.tsx

@@ -50,7 +50,7 @@ import Animated, {
 import { useSafeAreaInsets } from 'react-native-safe-area-context';
 import { useCSSVariable } from 'uniwind';
 import { Portal } from '../../primitives/portal';
-import { Text } from '../../primitives/text';
+import { Text, textChildren } from '../../primitives/text';
 import { cn } from '../../utils/cn';
 import { selectionTick } from '../../utils/haptics';
 
@@ -242,7 +242,7 @@ function SectionRailRoot({
         }}
         {...props}
       >
-        {children}
+        {textChildren(children)}
       </View>
     </SectionRailContext.Provider>
   );
@@ -276,7 +276,7 @@ function SectionRailTrigger({ className, children, ...props }: SectionRailTrigge
       )}
       {...props}
     >
-      {children}
+      {textChildren(children)}
     </Pressable>
   );
 }
@@ -407,7 +407,7 @@ function SectionRailPanel({ className, children, ...props }: SectionRailContentP
       {...props}
     >
       <ScrollView bounces={false} showsVerticalScrollIndicator={false}>
-        {children}
+        {textChildren(children)}
       </ScrollView>
     </Animated.View>
   );

package/src/components/select/index.tsx

@@ -51,7 +51,8 @@ import { useCSSVariable } from 'uniwind';
 import { CheckIcon, ChevronDownIcon } from '../../icons';
 import { getNativeUI } from '../../native';
 import { Portal } from '../../primitives/portal';
-import { Text } from '../../primitives/text';
+import { Text, textChildren } from '../../primitives/text';
+import { useBackHandler } from '../../hooks/use-back-handler';
 import { BottomSheet } from '../bottom-sheet';
 
 const selectVariants = tv({
@@ -223,6 +224,11 @@ function SelectRoot({
     onOpenChange?.(false);
   }, [chevron, onOpenChange]);
 
+  // An open overlay list catches the Android back button, closing itself
+  // instead of popping the screen behind it. The `sheet` presentation gets the
+  // same behaviour from its BottomSheet; the native picker owns its own back.
+  useBackHandler(open && presentation === 'overlay' && !nativeUI, close);
+
   const toggle = useCallback(() => {
     if (open) {
       close();
@@ -333,7 +339,7 @@ function SelectRoot({
                 </Text>
               ) : null}
               <ScrollView bounces={false} className="max-h-96">
-                <View className="gap-1 pb-2">{children}</View>
+                <View className="gap-1 pb-2">{textChildren(children)}</View>
               </ScrollView>
             </SelectContext.Provider>
           </BottomSheet.Content>
@@ -353,7 +359,7 @@ function SelectRoot({
               exiting={FadeOut.duration(120)}
               className={slots.list()}
             >
-              {children}
+              {textChildren(children)}
             </Animated.View>
           ) : null}
         </View>
@@ -410,7 +416,7 @@ function SelectRoot({
               className={slots.list()}
             >
               <ScrollView bounces={false} showsVerticalScrollIndicator={false}>
-                {children}
+                {textChildren(children)}
               </ScrollView>
             </Animated.View>
           </SelectContext.Provider>

package/src/components/sources/index.tsx

@@ -0,0 +1,278 @@
+/**
+ * Sources — where an answer came from, folded under a count.
+ *
+ * A cited answer usually cites more places than anyone wants listed above it,
+ * so the list opens from a single line: "Used 6 sources". Folded is the resting
+ * state, unlike `Reasoning`, because a citation list is a thing you go and
+ * check rather than a thing you watch arrive.
+ *
+ * ```tsx
+ * <Sources>
+ *   <Sources.Trigger count={sources.length} />
+ *   <Sources.Content>
+ *     {sources.map((source) => (
+ *       <Sources.Source key={source.url} href={source.url} title={source.title} />
+ *     ))}
+ *   </Sources.Content>
+ * </Sources>
+ * ```
+ *
+ * ## Where the props come from
+ *
+ * With the AI SDK these are the `source-url` parts of an assistant message:
+ * `part.url` is the `href` and `part.title` the `title`. A part carries no
+ * title of its own when the model did not supply one, in which case the host
+ * of the URL is a better label than the whole of it.
+ */
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useState,
+  type ReactNode,
+} from 'react';
+import {
+  Linking,
+  Pressable,
+  View,
+  type PressableProps,
+  type ViewProps,
+} from 'react-native';
+import Animated, {
+  useAnimatedStyle,
+  useReducedMotion,
+  useSharedValue,
+  withTiming,
+} from 'react-native-reanimated';
+import { tv } from 'tailwind-variants';
+import { ChevronDownIcon, LinkIcon } from '../../icons';
+import { Collapse } from '../../primitives/collapse';
+import { Text } from '../../primitives/text';
+import { cn } from '../../utils/cn';
+
+const sourcesVariants = tv({
+  slots: {
+    root: 'w-full gap-2',
+    trigger: 'flex-row items-center gap-2 py-0.5',
+    triggerLabel: 'text-sm font-medium text-muted-foreground',
+    content: 'gap-0.5',
+    source: 'flex-row items-center gap-2 rounded-xl px-2 py-2 active:bg-accent',
+    sourceTitle: 'flex-1 text-sm text-foreground',
+    sourceHost: 'text-xs text-muted-foreground',
+  },
+});
+
+interface SourcesContextValue {
+  open: boolean;
+  setOpen: (open: boolean) => void;
+}
+
+const SourcesContext = createContext<SourcesContextValue | null>(null);
+
+function useSources(component: string): SourcesContextValue {
+  const context = useContext(SourcesContext);
+  if (!context) {
+    throw new Error(`${component} must be used within a <Sources>`);
+  }
+  return context;
+}
+
+export interface SourcesProps extends Omit<ViewProps, 'children'> {
+  className?: string;
+  /** Controlled open state. */
+  open?: boolean;
+  /** Initial state when uncontrolled. Folded, which is where a citation list belongs. */
+  defaultOpen?: boolean;
+  onOpenChange?: (open: boolean) => void;
+  children?: ReactNode;
+}
+
+function SourcesRoot({
+  className,
+  open: openProp,
+  defaultOpen = false,
+  onOpenChange,
+  children,
+  ...props
+}: SourcesProps) {
+  const { root } = sourcesVariants();
+  const [internalOpen, setInternalOpen] = useState(defaultOpen);
+  const isControlled = openProp !== undefined;
+  const open = isControlled ? openProp : internalOpen;
+
+  const setOpen = useCallback(
+    (next: boolean) => {
+      if (!isControlled) setInternalOpen(next);
+      onOpenChange?.(next);
+    },
+    [isControlled, onOpenChange]
+  );
+
+  const context = useMemo(() => ({ open, setOpen }), [open, setOpen]);
+
+  return (
+    <SourcesContext.Provider value={context}>
+      <View {...props} className={cn(root(), className)}>
+        {children}
+      </View>
+    </SourcesContext.Provider>
+  );
+}
+SourcesRoot.displayName = 'Sources';
+
+export interface SourcesTriggerProps
+  extends Omit<PressableProps, 'children' | 'style'> {
+  className?: string;
+  /** How many sources the list holds. Reads "Used 6 sources". */
+  count?: number;
+  /** Replaces the whole row. */
+  children?: ReactNode;
+}
+
+function SourcesTrigger({
+  className,
+  count = 0,
+  children,
+  onPress,
+  ...props
+}: SourcesTriggerProps) {
+  const { open, setOpen } = useSources('Sources.Trigger');
+  const { trigger, triggerLabel } = sourcesVariants();
+  const reducedMotion = useReducedMotion();
+  const progress = useSharedValue(open ? 1 : 0);
+
+  useEffect(() => {
+    progress.value = reducedMotion
+      ? open
+        ? 1
+        : 0
+      : withTiming(open ? 1 : 0, { duration: 180 });
+  }, [open, reducedMotion, progress]);
+
+  const chevronStyle = useAnimatedStyle(() => ({
+    transform: [{ rotate: `${progress.value * 180}deg` }],
+  }));
+
+  return (
+    <Pressable
+      accessibilityRole="button"
+      accessibilityState={{ expanded: open }}
+      onPress={(event) => {
+        onPress?.(event);
+        setOpen(!open);
+      }}
+      className={cn(trigger(), className)}
+      {...props}
+    >
+      {children ?? (
+        <>
+          <Text className={triggerLabel()}>
+            Used {count} {count === 1 ? 'source' : 'sources'}
+          </Text>
+          <Animated.View style={chevronStyle}>
+            <ChevronDownIcon size={16} />
+          </Animated.View>
+        </>
+      )}
+    </Pressable>
+  );
+}
+
+export interface SourcesContentProps extends Omit<ViewProps, 'children'> {
+  className?: string;
+  children?: ReactNode;
+}
+
+function SourcesContent({ className, children, ...props }: SourcesContentProps) {
+  const { open } = useSources('Sources.Content');
+  const { content } = sourcesVariants();
+
+  return (
+    <Collapse open={open} className={cn(content(), className)} {...props}>
+      {children}
+    </Collapse>
+  );
+}
+
+export interface SourcesSourceProps
+  extends Omit<PressableProps, 'children' | 'style'> {
+  className?: string;
+  /** Where the row goes. Opened with the platform's own handler. */
+  href?: string;
+  /**
+   * What the row says. Falls back to the URL's host, which is a better label
+   * than a hundred characters of path — and models often send no title at all.
+   */
+  title?: string;
+  /** Leading glyph. A link by default; a favicon suits a real citation list. */
+  icon?: ReactNode;
+  children?: ReactNode;
+}
+
+/** One citation. */
+function SourcesSource({
+  className,
+  href,
+  title,
+  icon,
+  children,
+  onPress,
+  ...props
+}: SourcesSourceProps) {
+  const { source, sourceTitle, sourceHost } = sourcesVariants();
+  const host = useMemo(() => hostOf(href), [href]);
+
+  return (
+    <Pressable
+      accessibilityRole="link"
+      accessibilityLabel={title ?? host ?? href}
+      onPress={(event) => {
+        onPress?.(event);
+        // No `canOpenURL` guard: it needs the scheme declared up front on iOS,
+        // and a source is always http(s), which is always openable.
+        if (href) void Linking.openURL(href).catch(() => undefined);
+      }}
+      className={cn(source(), className)}
+      {...props}
+    >
+      {children ?? (
+        <>
+          {icon ?? <LinkIcon size={14} />}
+          <Text numberOfLines={1} className={sourceTitle()}>
+            {title ?? host ?? href}
+          </Text>
+          {title && host ? (
+            <Text numberOfLines={1} className={sourceHost()}>
+              {host}
+            </Text>
+          ) : null}
+        </>
+      )}
+    </Pressable>
+  );
+}
+
+/**
+ * The host of a URL, without a URL parser.
+ *
+ * `URL` exists in Hermes but throws on anything malformed, and a model's
+ * citation is not a thing to trust with an exception. A label is worth having
+ * even when the string it came from is not a URL at all.
+ */
+function hostOf(href: string | undefined): string | undefined {
+  if (!href) return undefined;
+  const match = /^[a-z][a-z0-9+.-]*:\/\/([^/?#]+)/i.exec(href);
+  return match?.[1]?.replace(/^www\./i, '');
+}
+
+SourcesTrigger.displayName = 'Sources.Trigger';
+SourcesContent.displayName = 'Sources.Content';
+SourcesSource.displayName = 'Sources.Source';
+
+export const Sources = Object.assign(SourcesRoot, {
+  Trigger: SourcesTrigger,
+  Content: SourcesContent,
+  Source: SourcesSource,
+});

package/src/components/steps/index.tsx

@@ -26,7 +26,7 @@ import { Pressable, View, type Text as RNText, type ViewProps } from 'react-nati
 import { tv } from 'tailwind-variants';
 import { useCSSVariable } from 'uniwind';
 import { CheckIcon } from '../../icons';
-import { Text, type TextProps } from '../../primitives/text';
+import { Text, type TextProps, textChildren } from '../../primitives/text';
 import { Spinner } from '../spinner';
 
 export type StepState = 'active' | 'completed' | 'inactive' | 'loading';
@@ -163,7 +163,7 @@ const StepsRoot = forwardRef<View, StepsProps>(
     return (
       <StepsContext.Provider value={context}>
         <View ref={ref} className={root({ className })} {...props}>
-          {children}
+          {textChildren(children)}
         </View>
       </StepsContext.Provider>
     );
@@ -210,7 +210,7 @@ const StepsItem = forwardRef<View, StepsItemProps>(
     return (
       <StepItemContext.Provider value={context}>
         <View ref={ref} className={item({ className })} {...props}>
-          {children}
+          {textChildren(children)}
         </View>
       </StepItemContext.Provider>
     );
@@ -240,7 +240,7 @@ const StepsTrigger = forwardRef<View, StepsTriggerProps>(
         className={trigger({ className })}
         {...props}
       >
-        {children}
+        {textChildren(children)}
       </Pressable>
     );
   }