panelui-native 0.28.1 → 0.30.0

package/src/components/plan/index.tsx

@@ -0,0 +1,325 @@
+/**
+ * Plan — what an agent intends to do, before it does it.
+ *
+ * A card rather than a run of rows, because a plan is a thing the reader is
+ * being asked to approve: it needs an edge around it so that where it starts
+ * and stops is not a matter of interpretation, and a footer that can hold the
+ * button that approves it.
+ *
+ * It streams. `isStreaming` puts a shimmer on the title and the description,
+ * which is the honest way to render a heading that is still arriving — the
+ * alternative is a title that grows a word at a time and reads as finished at
+ * every intermediate length.
+ *
+ * ```tsx
+ * <Plan isStreaming={streaming}>
+ *   <Plan.Header>
+ *     <Plan.Title>Migrate the calendar</Plan.Title>
+ *     <Plan.Description>Four files, no API change.</Plan.Description>
+ *     <Plan.Action><Plan.Trigger /></Plan.Action>
+ *   </Plan.Header>
+ *   <Plan.Content>…</Plan.Content>
+ *   <Plan.Footer><Button>Approve</Button></Plan.Footer>
+ * </Plan>
+ * ```
+ *
+ * ## Where the props come from
+ *
+ * With the AI SDK a plan is usually an `experimental_useObject` stream, where
+ * `isStreaming` is the hook's `isLoading` and the fields arrive one at a time —
+ * which is exactly the case the shimmer exists for, since a partial object has
+ * a title before it has anything else.
+ */
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  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 } from '../../icons';
+import { Collapse } from '../../primitives/collapse';
+import { Text, textChildren } from '../../primitives/text';
+import { cn } from '../../utils/cn';
+import { Shimmer } from '../shimmer';
+
+const planVariants = tv({
+  slots: {
+    root: 'w-full overflow-hidden rounded-2xl border border-border bg-card',
+    header: 'flex-row items-start gap-3 p-4',
+    heading: 'min-w-0 flex-1 gap-1',
+    title: 'text-base font-semibold text-card-foreground',
+    description: 'text-sm text-muted-foreground',
+    action: 'shrink-0 flex-row items-center gap-1',
+    trigger: 'h-8 w-8 items-center justify-center rounded-full active:bg-accent',
+    content: 'gap-2 px-4 pb-4',
+    footer: 'flex-row items-center justify-end gap-2 border-t border-border p-4',
+  },
+});
+
+interface PlanContextValue {
+  isStreaming: boolean;
+  open: boolean;
+  setOpen: (open: boolean) => void;
+}
+
+const PlanContext = createContext<PlanContextValue | null>(null);
+
+function usePlan(component: string): PlanContextValue {
+  const context = useContext(PlanContext);
+  if (!context) {
+    throw new Error(`${component} must be used within a <Plan>`);
+  }
+  return context;
+}
+
+export interface PlanProps extends Omit<ViewProps, 'children'> {
+  className?: string;
+  /** Whether the plan is still being written. Shimmers the title and description. */
+  isStreaming?: boolean;
+  /** Controlled open state of the body. */
+  open?: boolean;
+  /** Initial state when uncontrolled. */
+  defaultOpen?: boolean;
+  onOpenChange?: (open: boolean) => void;
+  children?: ReactNode;
+}
+
+function PlanRoot({
+  className,
+  isStreaming = false,
+  open: openProp,
+  defaultOpen = true,
+  onOpenChange,
+  children,
+  ...props
+}: PlanProps) {
+  const { root } = planVariants();
+  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(
+    () => ({ isStreaming, open, setOpen }),
+    [isStreaming, open, setOpen]
+  );
+
+  return (
+    <PlanContext.Provider value={context}>
+      <View {...props} className={cn(root(), className)}>
+        {children}
+      </View>
+    </PlanContext.Provider>
+  );
+}
+PlanRoot.displayName = 'Plan';
+
+export interface PlanHeaderProps extends ViewProps {
+  className?: string;
+  children?: ReactNode;
+}
+
+/**
+ * The title, the description and whatever acts on them.
+ *
+ * The heading is wrapped in a column of its own so the action stays pinned to
+ * the trailing edge as the title wraps, rather than riding down with it.
+ */
+function PlanHeader({ className, children, ...props }: PlanHeaderProps) {
+  const { header, heading } = planVariants();
+
+  const headings: ReactNode[] = [];
+  const actions: ReactNode[] = [];
+  for (const child of Array.isArray(children) ? children : [children]) {
+    if (isPlanAction(child)) actions.push(child);
+    else headings.push(child);
+  }
+
+  return (
+    <View {...props} className={cn(header(), className)}>
+      <View className={heading()}>{headings}</View>
+      {actions}
+    </View>
+  );
+}
+
+function isPlanAction(child: ReactNode): boolean {
+  return (
+    typeof child === 'object' &&
+    child !== null &&
+    'type' in child &&
+    (child as { type?: unknown }).type === PlanAction
+  );
+}
+
+export interface PlanTitleProps extends ViewProps {
+  className?: string;
+  children?: ReactNode;
+}
+
+/** The plan's name. Shimmers while it is still being written. */
+function PlanTitle({ className, children, ...props }: PlanTitleProps) {
+  const { isStreaming } = usePlan('Plan.Title');
+  const { title } = planVariants();
+
+  if (isStreaming && typeof children === 'string') {
+    return <Shimmer textClassName={cn(title(), className)}>{children}</Shimmer>;
+  }
+
+  return (
+    <Text accessibilityRole="header" className={cn(title(), className)} {...props}>
+      {children}
+    </Text>
+  );
+}
+
+export interface PlanDescriptionProps extends ViewProps {
+  className?: string;
+  children?: ReactNode;
+}
+
+function PlanDescription({ className, children, ...props }: PlanDescriptionProps) {
+  const { isStreaming } = usePlan('Plan.Description');
+  const { description } = planVariants();
+
+  if (isStreaming && typeof children === 'string') {
+    return <Shimmer textClassName={cn(description(), className)}>{children}</Shimmer>;
+  }
+
+  return (
+    <Text className={cn(description(), className)} {...props}>
+      {children}
+    </Text>
+  );
+}
+
+export interface PlanActionProps extends ViewProps {
+  className?: string;
+  children?: ReactNode;
+}
+
+/** Pinned to the header's trailing edge — the toggle, a badge, a menu. */
+function PlanAction({ className, children, ...props }: PlanActionProps) {
+  const { action } = planVariants();
+  return (
+    <View {...props} className={cn(action(), className)}>
+      {children}
+    </View>
+  );
+}
+
+export interface PlanTriggerProps extends Omit<PressableProps, 'children' | 'style'> {
+  className?: string;
+  children?: ReactNode;
+}
+
+/** Folds the body away. Its chevron turns to point at the state it will reach. */
+function PlanTrigger({ className, children, onPress, ...props }: PlanTriggerProps) {
+  const { open, setOpen } = usePlan('Plan.Trigger');
+  const { trigger } = planVariants();
+  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"
+      accessibilityLabel={open ? 'Collapse plan' : 'Expand plan'}
+      accessibilityState={{ expanded: open }}
+      hitSlop={6}
+      onPress={(event) => {
+        onPress?.(event);
+        setOpen(!open);
+      }}
+      className={cn(trigger(), className)}
+      {...props}
+    >
+      {children ?? (
+        <Animated.View style={chevronStyle}>
+          <ChevronDownIcon size={16} />
+        </Animated.View>
+      )}
+    </Pressable>
+  );
+}
+
+export interface PlanContentProps extends Omit<ViewProps, 'children'> {
+  className?: string;
+  children?: ReactNode;
+}
+
+/** The steps. Collapses rather than unmounting, so it can still be growing. */
+function PlanContent({ className, children, ...props }: PlanContentProps) {
+  const { open } = usePlan('Plan.Content');
+  const { content, description } = planVariants();
+
+  return (
+    <Collapse open={open} className={cn(content(), className)} {...props}>
+      {textChildren(children, (text) => (
+        <Text className={description()}>{text}</Text>
+      ))}
+    </Collapse>
+  );
+}
+
+export interface PlanFooterProps extends ViewProps {
+  className?: string;
+  children?: ReactNode;
+}
+
+/** Where the button that approves the plan goes. */
+function PlanFooter({ className, children, ...props }: PlanFooterProps) {
+  const { footer } = planVariants();
+  return (
+    <View {...props} className={cn(footer(), className)}>
+      {children}
+    </View>
+  );
+}
+
+PlanHeader.displayName = 'Plan.Header';
+PlanTitle.displayName = 'Plan.Title';
+PlanDescription.displayName = 'Plan.Description';
+PlanAction.displayName = 'Plan.Action';
+PlanTrigger.displayName = 'Plan.Trigger';
+PlanContent.displayName = 'Plan.Content';
+PlanFooter.displayName = 'Plan.Footer';
+
+export const Plan = Object.assign(PlanRoot, {
+  Header: PlanHeader,
+  Title: PlanTitle,
+  Description: PlanDescription,
+  Action: PlanAction,
+  Trigger: PlanTrigger,
+  Content: PlanContent,
+  Footer: PlanFooter,
+});

package/src/components/popover/index.tsx

@@ -44,6 +44,7 @@ import {
 } from 'react';
 import {
   Pressable,
+  ScrollView,
   useWindowDimensions,
   View,
   type LayoutChangeEvent,
@@ -228,6 +229,40 @@ export interface PopoverContentProps extends ViewProps {
    * content into a column.
    */
   minWidth?: number;
+  /**
+   * Ceiling for the panel's height, in pixels. Always clamped to the room
+   * inside the safe area, which is also the default — a panel is never
+   * positioned so that part of it falls off the screen, because the part that
+   * falls off cannot be scrolled back into view.
+   */
+  maxHeight?: number;
+  /**
+   * Scroll the panel's body when it is taller than `maxHeight`.
+   *
+   * Off by default, because a popover is usually a paragraph or a short form
+   * and a scroller around either one only adds a bounce. Worth turning on for
+   * a list of unknown length, which is the case where the cap actually bites.
+   *
+   * The spacing between children moves to the scroller's content when this is
+   * set; `className` still dresses the panel itself.
+   */
+  scrollable?: boolean;
+  /**
+   * Drop the panel's own surface — its background, border, radius, padding and
+   * shadow — and keep only its position and its size. For a caller that draws
+   * the surface itself, so that something can be put *behind* the content
+   * rather than layered on top of a background that is already painted.
+   *
+   * The panel is still clipped to a rounded rectangle, because a surface drawn
+   * inside it has to have something to be clipped by.
+   */
+  unstyled?: boolean;
+  /**
+   * A layer drawn inside the panel, behind its content — and, crucially,
+   * outside its scroller, so that a surface does not scroll away with the rows
+   * on top of it. Pair it with `unstyled` to own the panel's appearance.
+   */
+  background?: ReactNode;
   /** Tap outside the panel closes it. Default true. */
   dismissible?: boolean;
   /**
@@ -247,6 +282,10 @@ function PopoverContent({
   alignOffset = 0,
   width = 'content-fit',
   minWidth,
+  maxHeight,
+  scrollable = false,
+  unstyled = false,
+  background,
   dismissible = true,
   blur = false,
   children,
@@ -303,6 +342,17 @@ function PopoverContent({
       ? Math.min(Math.max(requestedWidth, minWidth), available)
       : requestedWidth;
 
+  /*
+   * The cap is what keeps a tall panel reachable. `place` clamps the panel
+   * inside the bounds, but a panel taller than the bounds cannot be clamped
+   * into them — it gets pinned to the top edge and the rest runs off the
+   * bottom of the screen, where there is no way to get at it. Capping the
+   * height first means the clamp always has a solution, and `scrollable`
+   * hands the overflow back to the finger.
+   */
+  const room = bounds.bottom - bounds.top;
+  const resolvedMaxHeight = maxHeight === undefined ? room : Math.min(maxHeight, room);
+
   const position =
     trigger && size
       ? place({ trigger, size, placement, align, offset, alignOffset, bounds })
@@ -434,6 +484,7 @@ function PopoverContent({
               top: position?.top ?? -9999,
               left: position?.left ?? -9999,
               maxWidth: bounds.right - bounds.left,
+              maxHeight: resolvedMaxHeight,
               width: resolvedWidth,
             }}
           >
@@ -441,12 +492,28 @@ function PopoverContent({
               accessibilityViewIsModal
               style={[panelStyle, style]}
               className={cn(
-                'gap-1.5 rounded-2xl border border-border bg-popover p-4 shadow-lg',
+                // `unstyled` keeps the clip and drops everything that paints,
+                // so a caller can put its own layer underneath the content.
+                unstyled
+                  ? 'overflow-hidden rounded-2xl'
+                  : 'rounded-2xl border border-border bg-popover p-4 shadow-lg',
+                // The gap belongs to whichever view actually holds the
+                // children — on the panel normally, on the scroller's content
+                // when there is one, since the scroller is then the panel's
+                // only child and a gap around it spaces nothing.
+                scrollable ? 'overflow-hidden' : 'gap-1.5',
                 className
               )}
               {...props}
             >
-              {textChildren(children)}
+              {background}
+              {scrollable ? (
+                <ScrollView bounces={false} showsVerticalScrollIndicator={false}>
+                  <View className="gap-1.5">{textChildren(children)}</View>
+                </ScrollView>
+              ) : (
+                textChildren(children)
+              )}
             </Animated.View>
           </Animated.View>
         </View>

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

@@ -211,13 +211,22 @@ const RadioGroupItem = forwardRef<View, RadioGroupItemProps>(
       </View>
     );
 
+    // Either way the label is a string in a row that is otherwise all views,
+    // so children given instead of the prop are dressed the same way rather
+    // than reaching the pressable bare.
+    const labelled = label ? (
+      <Text className={slots.label()}>{label}</Text>
+    ) : (
+      textChildren(children, (text) => <Text className={slots.label()}>{text}</Text>)
+    );
+
     // The card lays its text out first so the disc sits at the trailing edge;
     // the dot row keeps the classic disc-then-label order.
     const body =
       variant === 'card' ? (
         <>
           <View className="flex-1 gap-1">
-            {label ? <Text className={slots.label()}>{label}</Text> : children}
+            {labelled}
             {description ? (
               <Text className={slots.description()}>{description}</Text>
             ) : null}
@@ -227,7 +236,7 @@ const RadioGroupItem = forwardRef<View, RadioGroupItemProps>(
       ) : (
         <>
           {indicator}
-          {label ? <Text className={slots.label()}>{label}</Text> : children}
+          {labelled}
         </>
       );