panelui-native 0.28.1 → 0.32.0

package/src/components/task/index.tsx

@@ -0,0 +1,329 @@
+/**
+ * Task — one step an agent took, and what it did while it was there.
+ *
+ * The header is the step; the body is the detail nobody reads unless something
+ * went wrong. Open by default, because a task that is running is the thing the
+ * reader is watching — and it stays open afterwards rather than folding itself
+ * away, because unlike a reasoning trace the steps are the record of what
+ * happened and are worth scrolling back through.
+ *
+ * ```tsx
+ * <Task status="running">
+ *   <Task.Trigger title="Searching the codebase" />
+ *   <Task.Content>
+ *     <Task.Item>
+ *       Read <Task.File>calendar/index.tsx</Task.File>
+ *     </Task.Item>
+ *   </Task.Content>
+ * </Task>
+ * ```
+ *
+ * ## Where the props come from
+ *
+ * With the AI SDK a task is a tool-call part: `part.type` is `tool-<name>` and
+ * `part.state` runs `input-streaming` → `input-available` → `output-available`
+ * or `output-error`. Those map onto `status` as pending, running, complete and
+ * error; `part.input` is usually what the body should say.
+ */
+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 { useCSSVariable } from 'uniwind';
+import {
+  AlertTriangleIcon,
+  CheckCircleIcon,
+  ChevronDownIcon,
+  CircleIcon,
+  SearchIcon,
+} from '../../icons';
+import { Collapse } from '../../primitives/collapse';
+import { Text, textChildren } from '../../primitives/text';
+import { cn } from '../../utils/cn';
+import { Shimmer } from '../shimmer';
+
+export type TaskStatus = 'pending' | 'running' | 'complete' | 'error';
+
+const taskVariants = tv({
+  slots: {
+    root: 'w-full gap-2',
+    trigger: 'flex-row items-center gap-2 py-0.5',
+    title: 'flex-1 text-sm text-muted-foreground',
+    /*
+     * Indented behind a rule rather than merely padded. The rule is what says
+     * these lines belong to the step above them instead of being the next few
+     * steps, which matters as soon as there is more than one task in a row.
+     */
+    content: 'ms-2 gap-1.5 border-s border-border ps-4',
+    item: 'text-sm leading-relaxed text-muted-foreground',
+    file: 'flex-row items-center gap-1 self-start rounded-md border border-border bg-muted px-1.5 py-0.5',
+    fileLabel: 'font-mono text-xs text-foreground',
+  },
+  variants: {
+    status: {
+      pending: { title: 'text-muted-foreground/60' },
+      running: {},
+      complete: {},
+      error: { title: 'text-destructive' },
+    },
+  },
+  defaultVariants: {
+    status: 'complete',
+  },
+});
+
+interface TaskContextValue {
+  status: TaskStatus;
+  open: boolean;
+  setOpen: (open: boolean) => void;
+}
+
+const TaskContext = createContext<TaskContextValue | null>(null);
+
+function useTask(component: string): TaskContextValue {
+  const context = useContext(TaskContext);
+  if (!context) {
+    throw new Error(`${component} must be used within a <Task>`);
+  }
+  return context;
+}
+
+export interface TaskProps extends Omit<ViewProps, 'children'> {
+  className?: string;
+  /**
+   * Where the step has got to. Drives the leading glyph, and puts a shimmer on
+   * the title while it is `running`.
+   */
+  status?: TaskStatus;
+  /** Controlled open state. */
+  open?: boolean;
+  /** Initial state when uncontrolled. Open — the steps are the record. */
+  defaultOpen?: boolean;
+  onOpenChange?: (open: boolean) => void;
+  children?: ReactNode;
+}
+
+function TaskRoot({
+  className,
+  status = 'complete',
+  open: openProp,
+  defaultOpen = true,
+  onOpenChange,
+  children,
+  ...props
+}: TaskProps) {
+  const { root } = taskVariants({ status });
+  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(() => ({ status, open, setOpen }), [status, open, setOpen]);
+
+  return (
+    <TaskContext.Provider value={context}>
+      <View {...props} className={cn(root(), className)}>
+        {children}
+      </View>
+    </TaskContext.Provider>
+  );
+}
+TaskRoot.displayName = 'Task';
+
+export interface TaskTriggerProps extends Omit<PressableProps, 'children' | 'style'> {
+  className?: string;
+  /** What the step is. Shimmers while the status is `running`. */
+  title?: string;
+  /** Leading glyph. Derived from `status` when not given. */
+  icon?: ReactNode;
+  /** Replaces the whole row. */
+  children?: ReactNode;
+}
+
+function TaskTrigger({
+  className,
+  title,
+  icon,
+  children,
+  onPress,
+  ...props
+}: TaskTriggerProps) {
+  const { status, open, setOpen } = useTask('Task.Trigger');
+  const slots = taskVariants({ status });
+  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(slots.trigger(), className)}
+      {...props}
+    >
+      {children ?? (
+        <>
+          {icon ?? <TaskStatusIcon status={status} />}
+          {status === 'running' && title ? (
+            <View className="flex-1">
+              <Shimmer textClassName={slots.title()}>{title}</Shimmer>
+            </View>
+          ) : (
+            <Text numberOfLines={1} className={slots.title()}>
+              {title}
+            </Text>
+          )}
+          <Animated.View style={chevronStyle}>
+            <ChevronDownIcon size={16} />
+          </Animated.View>
+        </>
+      )}
+    </Pressable>
+  );
+}
+
+/**
+ * The glyph for each status. A magnifier while running: a step is a search.
+ *
+ * Every one is given an explicit colour. The filled status icons fall back to
+ * `currentColor`, which React Native's SVG does not resolve — it paints black,
+ * which on a dark theme is a black disc floating in the row. They are built to
+ * take their colour from an enclosing `IconColorProvider`, and a task row is
+ * not one, so the tint is resolved here.
+ */
+function TaskStatusIcon({ status }: { status: TaskStatus }) {
+  const muted = useTint('--color-muted-foreground');
+  const success = useTint('--color-success');
+  const destructive = useTint('--color-destructive');
+
+  switch (status) {
+    case 'pending':
+      return <CircleIcon size={16} color={muted} />;
+    case 'error':
+      return <AlertTriangleIcon size={16} color={destructive} />;
+    case 'complete':
+      return <CheckCircleIcon size={16} color={success} />;
+    default:
+      return <SearchIcon size={16} color={muted} />;
+  }
+}
+
+/**
+ * A theme token as a colour an icon will accept.
+ *
+ * `useCSSVariable` answers with whatever the token holds, which for a length or
+ * a number is not a colour at all — so anything that is not a string is dropped
+ * and the icon falls back to what it would have used anyway.
+ */
+function useTint(variable: string): string | undefined {
+  const raw = useCSSVariable(variable);
+  return typeof raw === 'string' ? raw : undefined;
+}
+
+export interface TaskContentProps extends Omit<ViewProps, 'children'> {
+  className?: string;
+  children?: ReactNode;
+}
+
+function TaskContent({ className, children, ...props }: TaskContentProps) {
+  const { open } = useTask('Task.Content');
+  const { content } = taskVariants();
+
+  return (
+    <Collapse open={open} className={cn(content(), className)} {...props}>
+      {children}
+    </Collapse>
+  );
+}
+
+export interface TaskItemProps extends Omit<ViewProps, 'children'> {
+  className?: string;
+  children?: ReactNode;
+}
+
+/** One line of what the step did. */
+function TaskItem({ className, children, ...props }: TaskItemProps) {
+  const { item } = taskVariants();
+
+  return (
+    <View {...props} className={cn('flex-row flex-wrap items-center gap-1', className)}>
+      {textChildren(children, (text) => (
+        <Text className={item()}>{text}</Text>
+      ))}
+    </View>
+  );
+}
+
+export interface TaskFileProps extends Omit<ViewProps, 'children'> {
+  className?: string;
+  /** A glyph for the file's kind, drawn before the name. */
+  icon?: ReactNode;
+  children?: ReactNode;
+}
+
+/**
+ * A filename inside a line, drawn as a chip.
+ *
+ * Bordered rather than merely monospaced, because a path in the middle of a
+ * sentence is otherwise indistinguishable from the sentence — and the paths
+ * are the part of a task line anyone actually scans for.
+ */
+function TaskFile({ className, icon, children, ...props }: TaskFileProps) {
+  const { file, fileLabel } = taskVariants();
+
+  return (
+    <View {...props} className={cn(file(), className)}>
+      {icon}
+      {textChildren(children, (text) => (
+        <Text className={fileLabel()}>{text}</Text>
+      ))}
+    </View>
+  );
+}
+
+TaskTrigger.displayName = 'Task.Trigger';
+TaskContent.displayName = 'Task.Content';
+TaskItem.displayName = 'Task.Item';
+TaskFile.displayName = 'Task.File';
+
+export const Task = Object.assign(TaskRoot, {
+  Trigger: TaskTrigger,
+  Content: TaskContent,
+  Item: TaskItem,
+  File: TaskFile,
+});

package/src/components/textarea/index.tsx

@@ -0,0 +1,381 @@
+/**
+ * Textarea — a field for text that runs to several lines.
+ *
+ * It shares Input's focus treatment: the border crosses between two colours on
+ * the UI thread over 150ms rather than snapping, because a border that switches
+ * wholesale reads as a redraw instead of as the field answering you.
+ *
+ * Height comes from `rows` rather than from a class, so it composes with `size`
+ * instead of fighting it — three rows of 14px text and three rows of 16px text
+ * are different heights, and both are three rows. `autoGrow` then lets the
+ * field follow its content up to `maxRows`, after which it scrolls, which is
+ * the behaviour a composer wants: it starts small, opens up as you write, and
+ * stops before it eats the screen.
+ *
+ * ```tsx
+ * <Textarea label="Notes" placeholder="Anything we should know?" />
+ * <Textarea autoGrow rows={2} maxRows={8} showCount maxLength={280} />
+ * ```
+ *
+ * For a single line, reach for `Input`.
+ */
+import { forwardRef, useCallback, useEffect, useMemo, useState } from 'react';
+import {
+  TextInput,
+  View,
+  type NativeSyntheticEvent,
+  type TextInputContentSizeChangeEventData,
+  type TextInputProps,
+} from 'react-native';
+import Animated, {
+  interpolateColor,
+  useAnimatedStyle,
+  useSharedValue,
+  withTiming,
+} from 'react-native-reanimated';
+import { tv, type VariantProps } from 'tailwind-variants';
+import { useCSSVariable } from 'uniwind';
+import type { KeyboardAvoidanceMode } from '../../hooks/use-keyboard-avoidance';
+import { KeyboardAvoider } from '../../primitives/keyboard-avoider';
+import { Text } from '../../primitives/text';
+import { Label } from '../label';
+
+/** Long enough to read as a transition, short enough not to lag a fast tab. */
+const FOCUS_DURATION = 150;
+
+/**
+ * Type size and the leading it is given, per `size`.
+ *
+ * The height of the box is derived from these rather than set as a class,
+ * because `rows` is a count and a count only becomes a height once you know how
+ * tall a line is. They are the same numbers the classes below carry; keeping
+ * them here as well is what lets `rows` and `size` compose.
+ */
+const METRICS = {
+  sm: { fontSize: 14, lineHeight: 20, padding: 10 },
+  md: { fontSize: 16, lineHeight: 22, padding: 12 },
+  lg: { fontSize: 16, lineHeight: 24, padding: 14 },
+} as const;
+
+const textareaVariants = tv({
+  slots: {
+    container: 'w-full gap-1.5',
+    /*
+     * No height here: it is computed from `rows` and applied as a style. Text
+     * starts at the top rather than floating in the middle of an empty box, and
+     * the leading is wanted — between several lines it separates them, where in
+     * a one-line field it would push the text off centre.
+     */
+    field: 'w-full rounded-lg border text-foreground',
+    footer: 'w-full flex-row items-start justify-between gap-3',
+    description: 'text-sm text-muted-foreground',
+    error: 'text-sm text-destructive',
+    count: 'shrink-0 text-sm tabular-nums text-muted-foreground',
+  },
+  variants: {
+    variant: {
+      // The border colour is animated, so it is deliberately not set here —
+      // only the background belongs to the class.
+      outline: { field: 'bg-background' },
+      filled: { field: 'bg-muted' },
+    },
+    size: {
+      sm: { field: 'px-3 text-[14px]' },
+      md: { field: 'px-3.5 text-[16px]' },
+      lg: { field: 'px-4 text-[16px]' },
+    },
+    disabled: {
+      true: { field: 'opacity-[0.64]' },
+    },
+    /** Past the limit the counter is the error, so it is tinted like one. */
+    over: {
+      true: { count: 'text-destructive' },
+    },
+  },
+  defaultVariants: {
+    variant: 'outline',
+    size: 'md',
+  },
+});
+
+type TextareaVariantProps = VariantProps<typeof textareaVariants>;
+
+export interface TextareaProps
+  extends Omit<TextInputProps, 'multiline' | 'numberOfLines'>,
+    Omit<TextareaVariantProps, 'disabled' | 'over'> {
+  className?: string;
+  containerClassName?: string;
+  label?: string;
+  description?: string;
+  /** Error message. When set, the field renders in its invalid state. */
+  errorMessage?: string;
+  /** Marks the field required — an asterisk on the label, and the a11y state. */
+  isRequired?: boolean;
+  disabled?: boolean;
+  /** How many lines of text the field is tall before it scrolls or grows. */
+  rows?: number;
+  /**
+   * Grow with the text, one line at a time, up to `maxRows` — after which the
+   * field holds its height and scrolls instead. Without it the field stays at
+   * `rows` and scrolls from the first line past it.
+   */
+  autoGrow?: boolean;
+  /** The tallest `autoGrow` will go. Ignored without it. */
+  maxRows?: number;
+  /**
+   * Show how much of `maxLength` is used, under the field. Needs `maxLength`;
+   * a counter with no limit to count towards says nothing.
+   */
+  showCount?: boolean;
+  /**
+   * Keep the field clear of the software keyboard. Moves by exactly the
+   * overlap, and not at all when the field is already clear — or when the
+   * keyboard belongs to a different field. The overlap is re-read every frame
+   * while the field is focused, so the field keeps its place in the page as it
+   * scrolls under and back out of the keyboard.
+   *
+   * Install `react-native-keyboard-controller` for this to behave on Android.
+   *
+   * Do not toggle this at runtime — it changes which component renders the
+   * container, which would remount the field and drop focus.
+   */
+  avoidKeyboard?: boolean;
+  /**
+   * How the field gets clear. `lift` moves it up by its overlap and follows
+   * the scroll — right for a field in the flow of a page. `dock` makes it
+   * travel with the keyboard, for a composer already pinned near the bottom
+   * edge; pair it with `keyboardBottomInset`.
+   */
+  keyboardMode?: KeyboardAvoidanceMode;
+  /** Gap kept between the field and the keyboard. `keyboardMode="lift"` only. */
+  keyboardOffset?: number;
+  /**
+   * How far above the bottom edge the field already sits — usually the safe
+   * area inset. `keyboardMode="dock"` only.
+   */
+  keyboardBottomInset?: number;
+}
+
+const AnimatedTextInput = Animated.createAnimatedComponent(TextInput);
+
+export const Textarea = forwardRef<TextInput, TextareaProps>(
+  (
+    {
+      className,
+      containerClassName,
+      label,
+      description,
+      errorMessage,
+      isRequired,
+      disabled,
+      variant,
+      size = 'md',
+      rows = 4,
+      autoGrow = false,
+      maxRows = 10,
+      showCount = false,
+      avoidKeyboard = false,
+      keyboardMode = 'lift',
+      keyboardOffset = 16,
+      keyboardBottomInset = 0,
+      onFocus,
+      onBlur,
+      onContentSizeChange,
+      style,
+      ...props
+    },
+    ref
+  ) => {
+    const [focused, setFocused] = useState(false);
+    const invalid = !!errorMessage;
+
+    const metrics = METRICS[size];
+    /* Both paddings plus the lines themselves — the box a row count asks for. */
+    const heightFor = useCallback(
+      (lines: number) => lines * metrics.lineHeight + metrics.padding * 2,
+      [metrics]
+    );
+
+    const minHeight = heightFor(rows);
+    const maxHeight = autoGrow ? heightFor(Math.max(rows, maxRows)) : undefined;
+
+    /*
+     * What the text actually measures, once it has been laid out. It only ever
+     * raises the floor — the field never shrinks below `rows`, and never grows
+     * past `maxRows`, so the clamping happens here rather than in the style.
+     */
+    const [contentHeight, setContentHeight] = useState(0);
+    const grownHeight = autoGrow
+      ? Math.min(
+          Math.max(minHeight, contentHeight + metrics.padding * 2),
+          maxHeight ?? Number.POSITIVE_INFINITY
+        )
+      : minHeight;
+
+    const length = props.value?.length ?? props.defaultValue?.length ?? 0;
+    const over = !!props.maxLength && length >= props.maxLength;
+
+    const placeholderColor = useCSSVariable('--color-muted-foreground');
+    const restColor = useCSSVariable('--color-input');
+    const focusColor = useCSSVariable('--color-ring');
+    const errorColor = useCSSVariable('--color-destructive');
+
+    const slots = textareaVariants({
+      variant,
+      size,
+      disabled: !!disabled,
+      over,
+    });
+
+    /*
+     * Border colour is driven by one 0..1 value rather than by a class per
+     * state. Uniwind can only swap a class wholesale, which is the snap this
+     * is here to avoid, and a shared value crosses between the two colours on
+     * the UI thread without a re-render.
+     */
+    const focus = useSharedValue(0);
+    useEffect(() => {
+      focus.value = withTiming(focused ? 1 : 0, { duration: FOCUS_DURATION });
+    }, [focused, focus]);
+
+    const resting = typeof restColor === 'string' ? restColor : '#e5e5e5';
+    const active = invalid
+      ? typeof errorColor === 'string'
+        ? errorColor
+        : '#ef4444'
+      : typeof focusColor === 'string'
+        ? focusColor
+        : '#a3a3a3';
+    // An invalid field is tinted even at rest — the error is a fact about the
+    // value, not about whether the field happens to be focused.
+    const idle = invalid ? active : resting;
+
+    const borderStyle = useAnimatedStyle(() => ({
+      borderColor: interpolateColor(focus.value, [0, 1], [idle, active]),
+    }));
+
+    const handleFocus = useCallback<NonNullable<TextInputProps['onFocus']>>(
+      (event) => {
+        setFocused(true);
+        onFocus?.(event);
+      },
+      [onFocus]
+    );
+
+    const handleBlur = useCallback<NonNullable<TextInputProps['onBlur']>>(
+      (event) => {
+        setFocused(false);
+        onBlur?.(event);
+      },
+      [onBlur]
+    );
+
+    const handleContentSizeChange = useCallback(
+      (event: NativeSyntheticEvent<TextInputContentSizeChangeEventData>) => {
+        if (autoGrow) {
+          setContentHeight(event.nativeEvent.contentSize.height);
+        }
+        onContentSizeChange?.(event);
+      },
+      [autoGrow, onContentSizeChange]
+    );
+
+    /*
+     * Type metrics go through `style` rather than through classes because the
+     * height is computed from them, and a line height set in two places is a
+     * line height that will disagree with itself.
+     */
+    const boxStyle = useMemo(
+      () => ({
+        height: grownHeight,
+        lineHeight: metrics.lineHeight,
+        paddingTop: metrics.padding,
+        paddingBottom: metrics.padding,
+        // Android starts the caret in the middle of the box without it.
+        textAlignVertical: 'top' as const,
+      }),
+      [grownHeight, metrics]
+    );
+
+    const footer =
+      errorMessage || description || (showCount && props.maxLength) ? (
+        <View className={slots.footer()}>
+          {errorMessage ? (
+            <Text className={slots.error()}>{errorMessage}</Text>
+          ) : description ? (
+            <Text className={slots.description()}>{description}</Text>
+          ) : (
+            <View className="flex-1" />
+          )}
+          {showCount && props.maxLength ? (
+            <Text className={slots.count()}>
+              {length}/{props.maxLength}
+            </Text>
+          ) : null}
+        </View>
+      ) : null;
+
+    const body = (
+      <>
+        {label ? (
+          <Label isRequired={isRequired} isInvalid={invalid} isDisabled={!!disabled}>
+            {label}
+          </Label>
+        ) : null}
+        <AnimatedTextInput
+          ref={ref}
+          multiline
+          editable={!disabled}
+          onFocus={handleFocus}
+          onBlur={handleBlur}
+          onContentSizeChange={handleContentSizeChange}
+          accessibilityLabel={label}
+          accessibilityState={{ disabled: !!disabled }}
+          aria-required={isRequired}
+          aria-invalid={invalid}
+          className={slots.field({ className })}
+          // Caller styles come last, but never last enough to drop the
+          // animated border or the height the row count asked for.
+          style={[boxStyle, borderStyle, style]}
+          placeholderTextColor={
+            typeof placeholderColor === 'string' ? placeholderColor : undefined
+          }
+          {...props}
+        />
+        {footer}
+      </>
+    );
+
+    const containerClasses = slots.container({ className: containerClassName });
+
+    /*
+     * The keyboard hook is deliberately behind a component boundary rather
+     * than an `enabled` flag. Calling it at all has global consequences —
+     * without the keyboard controller installed it falls back to Reanimated's
+     * useAnimatedKeyboard, which switches Android out of adjustResize for the
+     * whole app. A field that never asked to avoid the keyboard must not do
+     * that to every other screen.
+     */
+    if (avoidKeyboard) {
+      return (
+        <KeyboardAvoider
+          // Only while *this* field is the one being typed into. Without it
+          // every avoiding field on the screen lifts the moment any field
+          // anywhere is tapped, and since they all aim at the same gap above
+          // the keyboard, they arrive stacked on top of one another.
+          active={focused}
+          mode={keyboardMode}
+          offset={keyboardOffset}
+          bottomInset={keyboardBottomInset}
+          className={containerClasses}
+        >
+          {body}
+        </KeyboardAvoider>
+      );
+    }
+
+    return <View className={containerClasses}>{body}</View>;
+  }
+);
+
+Textarea.displayName = 'Textarea';