panelui-native 0.5.3 → 0.7.0

package/src/components/item/index.tsx

@@ -0,0 +1,387 @@
+/**
+ * Item — a row of content: media on one side, a title and description in the
+ * middle, actions on the other side.
+ *
+ * It is the shape almost every list in an app already has — a settings row, a
+ * file in a picker, a member in a team list, a tool call in a transcript — so
+ * it exists as one composable primitive rather than being rebuilt per screen
+ * with slightly different padding each time.
+ *
+ * ```tsx
+ * <Item variant="outline">
+ *   <Item.Media variant="icon"><ReceiptIcon /></Item.Media>
+ *   <Item.Content>
+ *     <Item.Title>Invoice.pdf</Item.Title>
+ *     <Item.Description>2.4 MB · Updated yesterday</Item.Description>
+ *   </Item.Content>
+ *   <Item.Actions><Button size="sm">Open</Button></Item.Actions>
+ * </Item>
+ * ```
+ *
+ * Two axes, and they are independent. `orientation` on the item decides
+ * whether its own parts sit side by side or stack into a card; `orientation`
+ * on `Item.Group` decides whether the items themselves run down the screen or
+ * across it. A carousel wants both set to the non-default: a horizontal group
+ * of vertical items.
+ */
+import { createContext, forwardRef, useContext, type ReactNode } from 'react';
+import { View, type ViewProps } from 'react-native';
+import { tv, type VariantProps } from 'tailwind-variants';
+import { AnimatedPressable, type AnimatedPressableProps } from '../../primitives/animated-pressable';
+import { Text, type TextProps } from '../../primitives/text';
+import { cn } from '../../utils/cn';
+
+type ItemSize = 'default' | 'sm' | 'xs';
+type ItemOrientation = 'horizontal' | 'vertical';
+
+const itemVariants = tv({
+  slots: {
+    root: 'gap-3 rounded-xl',
+    title: 'font-medium text-foreground',
+    description: 'text-muted-foreground',
+  },
+  variants: {
+    variant: {
+      default: {},
+      outline: { root: 'border border-border' },
+      muted: { root: 'bg-muted' },
+    },
+    size: {
+      default: { root: 'p-4', title: 'text-base', description: 'text-sm' },
+      sm: { root: 'p-3', title: 'text-sm', description: 'text-xs' },
+      xs: { root: 'gap-2 p-2', title: 'text-sm', description: 'text-xs' },
+    },
+    orientation: {
+      /** Media, text and actions side by side — the list-row shape. */
+      horizontal: { root: 'w-full flex-row items-center' },
+      /** Stacked into a card — the shape a horizontal carousel wants. */
+      vertical: { root: 'flex-col items-start' },
+    },
+    disabled: {
+      true: { root: 'opacity-[0.64]' },
+    },
+  },
+  defaultVariants: {
+    variant: 'default',
+    size: 'default',
+    orientation: 'horizontal',
+  },
+});
+
+/** Sub-components inherit the row's density and axis rather than repeating them. */
+const ItemContext = createContext<{ size: ItemSize; orientation: ItemOrientation }>({
+  size: 'default',
+  orientation: 'horizontal',
+});
+
+const mediaVariants = tv({
+  base: 'shrink-0 items-center justify-center',
+  variants: {
+    variant: {
+      /** No box — for an Avatar or anything that styles itself. */
+      default: '',
+      /** Rounded square tile sized for an icon. */
+      icon: 'rounded-lg border border-border bg-muted',
+      /** Clipped frame for an image or thumbnail. */
+      image: 'overflow-hidden rounded-lg bg-muted',
+    },
+    size: {
+      default: '',
+      sm: '',
+      xs: '',
+    },
+  },
+  compoundVariants: [
+    { variant: 'icon', size: 'default', class: 'h-10 w-10' },
+    { variant: 'icon', size: 'sm', class: 'h-8 w-8' },
+    { variant: 'icon', size: 'xs', class: 'h-6 w-6' },
+    { variant: 'image', size: 'default', class: 'h-12 w-12' },
+    { variant: 'image', size: 'sm', class: 'h-10 w-10' },
+    { variant: 'image', size: 'xs', class: 'h-8 w-8' },
+  ],
+  defaultVariants: {
+    variant: 'default',
+    size: 'default',
+  },
+});
+
+export interface ItemProps
+  extends Omit<AnimatedPressableProps, 'children' | 'disabled'>,
+    Omit<VariantProps<typeof itemVariants>, 'disabled'> {
+  className?: string;
+  disabled?: boolean;
+  /**
+   * Row density. `Item.Media`, `Item.Title` and `Item.Description` follow it,
+   * so it only needs setting here.
+   */
+  size?: ItemSize;
+  /**
+   * `horizontal` is the list row: media, text and actions side by side.
+   * `vertical` stacks them into a card, which is what a horizontal carousel
+   * wants — and it is also what `Item.Header` and `Item.Footer` need, since
+   * both are full-width strips.
+   */
+  orientation?: ItemOrientation;
+  children?: ReactNode;
+}
+
+/**
+ * Renders as a pressable when given `onPress`, and as a plain view otherwise,
+ * so a static row does not announce itself as a button.
+ */
+const ItemRoot = forwardRef<View, ItemProps>(
+  (
+    {
+      className,
+      variant,
+      size = 'default',
+      orientation = 'horizontal',
+      disabled,
+      children,
+      onPress,
+      ...props
+    },
+    ref
+  ) => {
+    const { root } = itemVariants({ variant, size, orientation, disabled: !!disabled });
+
+    const body = !onPress ? (
+      <View
+        ref={ref}
+        accessibilityState={{ disabled: !!disabled }}
+        className={root({ className })}
+        {...(props as ViewProps)}
+      >
+        {children}
+      </View>
+    ) : (
+      <AnimatedPressable
+        ref={ref}
+        accessibilityRole="button"
+        accessibilityState={{ disabled: !!disabled }}
+        disabled={disabled}
+        onPress={onPress}
+        className={root({ className })}
+        {...props}
+      >
+        {children}
+      </AnimatedPressable>
+    );
+
+    return (
+      <ItemContext.Provider value={{ size, orientation }}>{body}</ItemContext.Provider>
+    );
+  }
+);
+ItemRoot.displayName = 'Item';
+
+export interface ItemGroupProps extends ViewProps {
+  className?: string;
+  /**
+   * `vertical` stacks the items — the settings-list shape. `horizontal` runs
+   * them across instead, for a carousel; pair it with a scrollable and
+   * `orientation="vertical"` on each item so every entry reads as a card.
+   */
+  orientation?: ItemOrientation;
+  children?: ReactNode;
+}
+
+/** Stack of items. Pair with `Item.Separator` between them. */
+const ItemGroup = forwardRef<View, ItemGroupProps>(
+  ({ className, orientation = 'vertical', children, ...props }, ref) => (
+    <View
+      ref={ref}
+      accessibilityRole="list"
+      className={cn(
+        orientation === 'horizontal'
+          ? 'flex-row items-stretch gap-3'
+          : 'w-full',
+        className
+      )}
+      {...props}
+    >
+      {children}
+    </View>
+  )
+);
+ItemGroup.displayName = 'Item.Group';
+
+export interface ItemSeparatorProps extends ViewProps {
+  className?: string;
+  /** Match the group's axis: a horizontal group needs vertical hairlines. */
+  orientation?: ItemOrientation;
+}
+
+/** Hairline between rows in a group. */
+const ItemSeparator = forwardRef<View, ItemSeparatorProps>(
+  ({ className, orientation = 'vertical', ...props }, ref) => (
+    <View
+      ref={ref}
+      className={cn(
+        orientation === 'horizontal' ? 'h-full w-px' : 'h-px w-full',
+        'bg-border',
+        className
+      )}
+      {...props}
+    />
+  )
+);
+ItemSeparator.displayName = 'Item.Separator';
+
+export interface ItemMediaProps
+  extends ViewProps,
+    VariantProps<typeof mediaVariants> {
+  className?: string;
+  children?: ReactNode;
+}
+
+/** Leading slot: an icon tile, a thumbnail, or an avatar passed through. */
+const ItemMedia = forwardRef<View, ItemMediaProps>(
+  ({ className, variant, size, children, ...props }, ref) => {
+    const item = useContext(ItemContext);
+
+    return (
+      <View
+        ref={ref}
+        className={mediaVariants({ variant, size: size ?? item.size, className })}
+        {...props}
+      >
+        {children}
+      </View>
+    );
+  }
+);
+ItemMedia.displayName = 'Item.Media';
+
+export interface ItemContentProps extends ViewProps {
+  className?: string;
+  children?: ReactNode;
+}
+
+/**
+ * The text column. In a horizontal item it takes the remaining width so the
+ * actions stay pinned to the trailing edge; in a vertical one it just fills
+ * the width, because there is nothing beside it to push against.
+ */
+const ItemContent = forwardRef<View, ItemContentProps>(
+  ({ className, children, ...props }, ref) => {
+    const { orientation } = useContext(ItemContext);
+
+    return (
+      <View
+        ref={ref}
+        className={cn(
+          orientation === 'horizontal' ? 'flex-1' : 'w-full',
+          'gap-0.5',
+          className
+        )}
+        {...props}
+      >
+        {children}
+      </View>
+    );
+  }
+);
+ItemContent.displayName = 'Item.Content';
+
+export interface ItemTitleProps extends TextProps {
+  className?: string;
+}
+
+const ItemTitle = forwardRef<React.ElementRef<typeof Text>, ItemTitleProps>(
+  ({ className, ...props }, ref) => {
+    const { size } = useContext(ItemContext);
+    const { title } = itemVariants({ size });
+
+    return <Text ref={ref} className={title({ className })} {...props} />;
+  }
+);
+ItemTitle.displayName = 'Item.Title';
+
+export interface ItemDescriptionProps extends TextProps {
+  className?: string;
+}
+
+const ItemDescription = forwardRef<
+  React.ElementRef<typeof Text>,
+  ItemDescriptionProps
+>(({ className, ...props }, ref) => {
+  const { size } = useContext(ItemContext);
+  const { description } = itemVariants({ size });
+
+  return <Text ref={ref} className={description({ className })} {...props} />;
+});
+ItemDescription.displayName = 'Item.Description';
+
+export interface ItemActionsProps extends ViewProps {
+  className?: string;
+  children?: ReactNode;
+}
+
+/** Trailing slot: buttons, a chevron, a switch. */
+const ItemActions = forwardRef<View, ItemActionsProps>(
+  ({ className, children, ...props }, ref) => (
+    <View
+      ref={ref}
+      className={cn('shrink-0 flex-row items-center gap-1.5', className)}
+      {...props}
+    >
+      {children}
+    </View>
+  )
+);
+ItemActions.displayName = 'Item.Actions';
+
+export interface ItemHeaderProps extends ViewProps {
+  className?: string;
+  children?: ReactNode;
+}
+
+/**
+ * Full-width strip above the item's main content — an eyebrow label, a badge
+ * row. Needs `orientation="vertical"` on the item, since a strip only makes
+ * sense once the item stacks.
+ */
+const ItemHeader = forwardRef<View, ItemHeaderProps>(
+  ({ className, children, ...props }, ref) => (
+    <View
+      ref={ref}
+      className={cn('w-full flex-row items-center justify-between gap-2', className)}
+      {...props}
+    >
+      {children}
+    </View>
+  )
+);
+ItemHeader.displayName = 'Item.Header';
+
+export interface ItemFooterProps extends ViewProps {
+  className?: string;
+  children?: ReactNode;
+}
+
+/** Full-width strip below the row's main content. */
+const ItemFooter = forwardRef<View, ItemFooterProps>(
+  ({ className, children, ...props }, ref) => (
+    <View
+      ref={ref}
+      className={cn('w-full flex-row items-center gap-2', className)}
+      {...props}
+    >
+      {children}
+    </View>
+  )
+);
+ItemFooter.displayName = 'Item.Footer';
+
+export const Item = Object.assign(ItemRoot, {
+  Group: ItemGroup,
+  Separator: ItemSeparator,
+  Media: ItemMedia,
+  Content: ItemContent,
+  Title: ItemTitle,
+  Description: ItemDescription,
+  Actions: ItemActions,
+  Header: ItemHeader,
+  Footer: ItemFooter,
+});

package/src/components/label/index.tsx

@@ -1,9 +1,11 @@
 /**
  * Label — text that names a form field.
  *
- * Adapted from: heroui-inc/heroui-native src/components/label/ (root +
- * Label.Text anatomy, string children auto-wrapping, the required asterisk,
- * and the isInvalid / isDisabled recolouring).
+ * A string child is wrapped in `Label.Text` automatically, so the common case
+ * stays one line; pass the parts explicitly when the label needs more than
+ * text. `isRequired`, `isInvalid` and `isDisabled` are visual *and* semantic —
+ * they recolour and they set the accessibility state, so the two cannot drift
+ * apart.
  */
 import {
   createContext,

package/src/components/message/index.tsx

@@ -0,0 +1,312 @@
+/**
+ * Message — a chat turn: avatar, bubble, and the metadata around it.
+ *
+ * The pieces are separate because conversations differ in which ones they
+ * need. A support thread wants a sender name and a read receipt; an assistant
+ * transcript wants neither, but does want the bubble to carry tool output and
+ * actions. Composing them beats a component with a dozen optional props.
+ *
+ * `align` is the only thing the root decides, and everything downstream reads
+ * it from context: which side the row sits on, which way the avatar goes,
+ * which corner of the bubble is squared off, and which colour it takes.
+ *
+ * ```tsx
+ * <Message align="end">
+ *   <Message.Content>
+ *     <Message.Bubble>
+ *       <Message.BubbleContent>How can I help?</Message.BubbleContent>
+ *     </Message.Bubble>
+ *   </Message.Content>
+ * </Message>
+ * ```
+ */
+import {
+  Children,
+  cloneElement,
+  createContext,
+  forwardRef,
+  isValidElement,
+  useContext,
+  type ReactNode,
+} from 'react';
+import { View, type ViewProps } from 'react-native';
+import { tv, type VariantProps } from 'tailwind-variants';
+import { Text, type TextProps } from '../../primitives/text';
+import { cn } from '../../utils/cn';
+
+const messageVariants = tv({
+  slots: {
+    root: 'w-full flex-row items-end gap-2',
+    avatar: 'shrink-0',
+    content: 'max-w-[85%] gap-1',
+    header: 'text-xs font-medium text-muted-foreground',
+    bubble: 'rounded-2xl px-3.5 py-2.5',
+    bubbleContent: 'text-base',
+    footer: 'text-xs text-muted-foreground',
+    group: 'w-full gap-1',
+  },
+  variants: {
+    align: {
+      start: {
+        root: 'flex-row justify-start',
+        content: 'items-start',
+        // A squared corner on the side the message comes from points the
+        // bubble back at its sender.
+        bubble: 'rounded-bl-md bg-muted',
+        bubbleContent: 'text-foreground',
+        header: 'text-left',
+        footer: 'text-left',
+      },
+      end: {
+        root: 'flex-row-reverse justify-start',
+        content: 'items-end',
+        bubble: 'rounded-br-md bg-primary',
+        bubbleContent: 'text-primary-foreground',
+        header: 'text-right',
+        footer: 'text-right',
+      },
+    },
+  },
+  defaultVariants: {
+    align: 'start',
+  },
+});
+
+type Align = 'start' | 'end';
+
+interface MessageContextValue {
+  align: Align;
+  /** True when the message is not the first in its group. */
+  stacked: boolean;
+}
+
+const MessageContext = createContext<MessageContextValue>({
+  align: 'start',
+  stacked: false,
+});
+
+/** Reads the alignment set by the nearest Message. */
+function useMessageContext() {
+  return useContext(MessageContext);
+}
+
+const GroupContext = createContext<{ align: Align } | null>(null);
+
+export interface MessageProps
+  extends ViewProps,
+    VariantProps<typeof messageVariants> {
+  className?: string;
+  /**
+   * Which side of the conversation this turn belongs to. `end` is the
+   * outgoing side — the person holding the device.
+   */
+  align?: Align;
+  /**
+   * Continuation of the message above it: tighter spacing, and the avatar slot
+   * is reserved but left empty so bubbles stay aligned. `Message.Group` sets
+   * this for you.
+   */
+  stacked?: boolean;
+  children?: ReactNode;
+}
+
+const MessageRoot = forwardRef<View, MessageProps>(
+  ({ className, align, stacked = false, children, ...props }, ref) => {
+    const group = useContext(GroupContext);
+    const resolvedAlign = align ?? group?.align ?? 'start';
+    const { root } = messageVariants({ align: resolvedAlign });
+
+    return (
+      <MessageContext.Provider value={{ align: resolvedAlign, stacked }}>
+        <View ref={ref} className={root({ className })} {...props}>
+          {children}
+        </View>
+      </MessageContext.Provider>
+    );
+  }
+);
+MessageRoot.displayName = 'Message';
+
+export interface MessageGroupProps extends ViewProps {
+  className?: string;
+  /** Alignment applied to every Message inside that does not set its own. */
+  align?: Align;
+  children?: ReactNode;
+}
+
+/**
+ * Consecutive turns from one sender. Tightens the spacing between them and
+ * marks every message after the first as `stacked`, so only the first shows an
+ * avatar and the rest stay aligned with it.
+ */
+const MessageGroup = forwardRef<View, MessageGroupProps>(
+  ({ className, align = 'start', children, ...props }, ref) => {
+    const { group } = messageVariants({ align });
+
+    // Every turn after the first is a continuation, so it drops its avatar and
+    // sits tight against the one above. A child that sets `stacked` itself
+    // wins — grouping is a default, not a rule.
+    const stackedChildren = Children.map(children, (child, index) =>
+      isValidElement<MessageProps>(child) && child.props.stacked === undefined
+        ? cloneElement(child, { stacked: index > 0 })
+        : child
+    );
+
+    return (
+      <GroupContext.Provider value={{ align }}>
+        <View ref={ref} className={group({ className })} {...props}>
+          {stackedChildren}
+        </View>
+      </GroupContext.Provider>
+    );
+  }
+);
+MessageGroup.displayName = 'Message.Group';
+
+export interface MessageAvatarProps extends ViewProps {
+  className?: string;
+  children?: ReactNode;
+}
+
+/**
+ * Slot for the sender's avatar. On a stacked message the slot is rendered but
+ * left empty, which keeps the bubbles in a column instead of letting the
+ * second one slide under the first one's avatar.
+ */
+const MessageAvatar = forwardRef<View, MessageAvatarProps>(
+  ({ className, children, ...props }, ref) => {
+    const { stacked } = useMessageContext();
+    const { avatar } = messageVariants();
+
+    return (
+      <View ref={ref} className={avatar({ className })} {...props}>
+        {stacked ? <View className="opacity-0">{children}</View> : children}
+      </View>
+    );
+  }
+);
+MessageAvatar.displayName = 'Message.Avatar';
+
+export interface MessageContentProps extends ViewProps {
+  className?: string;
+  children?: ReactNode;
+}
+
+/** Column holding the header, bubble and footer. */
+const MessageContent = forwardRef<View, MessageContentProps>(
+  ({ className, children, ...props }, ref) => {
+    const { align } = useMessageContext();
+    const { content } = messageVariants({ align });
+
+    return (
+      <View ref={ref} className={content({ className })} {...props}>
+        {children}
+      </View>
+    );
+  }
+);
+MessageContent.displayName = 'Message.Content';
+
+export interface MessageHeaderProps extends TextProps {
+  className?: string;
+}
+
+/** Sender name or timestamp above the bubble. */
+const MessageHeader = forwardRef<React.ElementRef<typeof Text>, MessageHeaderProps>(
+  ({ className, ...props }, ref) => {
+    const { align } = useMessageContext();
+    const { header } = messageVariants({ align });
+
+    return <Text ref={ref} size="xs" className={header({ className })} {...props} />;
+  }
+);
+MessageHeader.displayName = 'Message.Header';
+
+export interface MessageBubbleProps extends ViewProps {
+  className?: string;
+  children?: ReactNode;
+}
+
+/** The speech bubble. Takes its colour and squared corner from `align`. */
+const MessageBubble = forwardRef<View, MessageBubbleProps>(
+  ({ className, children, ...props }, ref) => {
+    const { align } = useMessageContext();
+    const { bubble } = messageVariants({ align });
+
+    return (
+      <View ref={ref} className={bubble({ className })} {...props}>
+        {children}
+      </View>
+    );
+  }
+);
+MessageBubble.displayName = 'Message.Bubble';
+
+export interface MessageBubbleContentProps extends TextProps {
+  className?: string;
+}
+
+/** Text inside the bubble, in whichever colour reads against it. */
+const MessageBubbleContent = forwardRef<
+  React.ElementRef<typeof Text>,
+  MessageBubbleContentProps
+>(({ className, ...props }, ref) => {
+  const { align } = useMessageContext();
+  const { bubbleContent } = messageVariants({ align });
+
+  return <Text ref={ref} className={bubbleContent({ className })} {...props} />;
+});
+MessageBubbleContent.displayName = 'Message.BubbleContent';
+
+export interface MessageFooterProps extends TextProps {
+  className?: string;
+}
+
+/** Delivery state, timestamp or actions below the bubble. */
+const MessageFooter = forwardRef<React.ElementRef<typeof Text>, MessageFooterProps>(
+  ({ className, ...props }, ref) => {
+    const { align } = useMessageContext();
+    const { footer } = messageVariants({ align });
+
+    return <Text ref={ref} size="xs" className={footer({ className })} {...props} />;
+  }
+);
+MessageFooter.displayName = 'Message.Footer';
+
+export interface MessageActionsProps extends ViewProps {
+  className?: string;
+  children?: ReactNode;
+}
+
+/** Row of controls under the bubble — copy, retry, feedback. */
+const MessageActions = forwardRef<View, MessageActionsProps>(
+  ({ className, children, ...props }, ref) => {
+    const { align } = useMessageContext();
+
+    return (
+      <View
+        ref={ref}
+        className={cn(
+          'flex-row items-center gap-1',
+          align === 'end' && 'flex-row-reverse',
+          className
+        )}
+        {...props}
+      >
+        {children}
+      </View>
+    );
+  }
+);
+MessageActions.displayName = 'Message.Actions';
+
+export const Message = Object.assign(MessageRoot, {
+  Group: MessageGroup,
+  Avatar: MessageAvatar,
+  Content: MessageContent,
+  Header: MessageHeader,
+  Bubble: MessageBubble,
+  BubbleContent: MessageBubbleContent,
+  Footer: MessageFooter,
+  Actions: MessageActions,
+});