panelui-native 0.9.0 → 0.13.0

package/src/components/chip/index.tsx

@@ -0,0 +1,333 @@
+/**
+ * Chip — a compact, interactive token.
+ *
+ * Where Badge only shows and ToggleButton owns a stateful toolbar, Chip is the
+ * thing in between: a small pill you can *press*, mark as *selected*, or
+ * *remove*. It is the filter in a filter bar, the tag on a photo, the removable
+ * recipient in a "To:" field — small, dense, and touchable.
+ *
+ * The close button is its own hit target nested inside the pill, so tapping the
+ * ✕ removes the chip without also firing the chip's own `onPress`. That split
+ * is the whole reason a removable chip needs a component and not just a styled
+ * Badge.
+ *
+ * ```tsx
+ * <Chip>Design</Chip>
+ *
+ * <Chip variant="info" onClose={() => remove('design')}>Design</Chip>
+ *
+ * <Chip selected={on} onPress={() => setOn(!on)}>
+ *   <CheckIcon size={14} />
+ *   <Chip.Label>Available</Chip.Label>
+ * </Chip>
+ * ```
+ */
+import {
+  createContext,
+  forwardRef,
+  useCallback,
+  useContext,
+  useMemo,
+  type ReactNode,
+} from 'react';
+import { Pressable, View, type ViewProps } from 'react-native';
+import { tv, type VariantProps } from 'tailwind-variants';
+import { useCSSVariable } from 'uniwind';
+import { IconColorProvider, XIcon } from '../../icons';
+import {
+  AnimatedPressable,
+  type AnimatedPressableProps,
+} from '../../primitives/animated-pressable';
+import { Text } from '../../primitives/text';
+import { cn } from '../../utils/cn';
+import { selectionTick } from '../../utils/haptics';
+
+const chipVariants = tv({
+  slots: {
+    root: 'flex-row items-center self-start rounded-full border border-transparent',
+    label: 'font-medium',
+    close:
+      'items-center justify-center rounded-full -mr-1 aspect-square opacity-70',
+  },
+  variants: {
+    variant: {
+      /** The resting tag — a quiet neutral fill. */
+      default: { root: 'bg-secondary', label: 'text-secondary-foreground' },
+      /** The accent fill, for the one chip that leads. */
+      primary: { root: 'bg-primary', label: 'text-primary-foreground' },
+      /** Just an outline — the lightest a chip gets while still being a shape. */
+      outline: { root: 'border-border bg-transparent', label: 'text-foreground' },
+      success: {
+        root: 'bg-success-subtle',
+        label: 'text-success-foreground',
+      },
+      warning: {
+        root: 'bg-warning-subtle',
+        label: 'text-warning-foreground',
+      },
+      info: { root: 'bg-info-subtle', label: 'text-info-foreground' },
+      destructive: {
+        root: 'bg-destructive-subtle',
+        label: 'text-destructive-foreground',
+      },
+    },
+    size: {
+      sm: { root: 'h-6 gap-1 px-2', label: 'text-xs' },
+      md: { root: 'h-7 gap-1.5 px-2.5', label: 'text-sm' },
+      lg: { root: 'h-9 gap-2 px-3.5', label: 'text-base' },
+    },
+    /**
+     * The filter "on" state — a loud accent surface that wins over the resting
+     * variant, so any chip can be a filter without picking a second colour.
+     */
+    selected: {
+      true: {
+        root: 'border-primary/24 bg-accent',
+        label: 'text-accent-foreground',
+      },
+    },
+    /** Trims the trailing padding so the close target hugs the right edge. */
+    closable: {
+      true: { root: 'pr-1' },
+    },
+    disabled: {
+      true: { root: 'opacity-[0.56]' },
+    },
+  },
+  compoundVariants: [
+    { size: 'sm', closable: true, class: { close: 'h-4' } },
+    { size: 'md', closable: true, class: { close: 'h-5' } },
+    { size: 'lg', closable: true, class: { close: 'h-6' } },
+  ],
+  defaultVariants: {
+    variant: 'default',
+    size: 'md',
+  },
+});
+
+type ChipVariantProps = VariantProps<typeof chipVariants>;
+export type ChipVariant = NonNullable<ChipVariantProps['variant']>;
+export type ChipSize = NonNullable<ChipVariantProps['size']>;
+
+/** Which foreground token each variant paints its icons and ✕ with. */
+const TINT_VAR: Record<ChipVariant, string> = {
+  default: '--color-secondary-foreground',
+  primary: '--color-primary-foreground',
+  outline: '--color-foreground',
+  success: '--color-success-foreground',
+  warning: '--color-warning-foreground',
+  info: '--color-info-foreground',
+  destructive: '--color-destructive-foreground',
+};
+
+/** The ✕ scales with the pill so it never looks stranded in a large chip. */
+const CLOSE_ICON: Record<ChipSize, number> = { sm: 11, md: 13, lg: 15 };
+
+/* -------------------------------------------------------------------------- */
+/* State context                                                              */
+/* -------------------------------------------------------------------------- */
+
+interface ChipStateValue {
+  selected: boolean;
+  disabled: boolean;
+}
+
+interface ChipContextValue extends ChipStateValue {
+  /** The label classes for this chip's variant/size, so `Chip.Label` matches. */
+  labelClasses: string;
+}
+
+const ChipContext = createContext<ChipContextValue | null>(null);
+
+/**
+ * The chip's own state, for anything rendered inside it — an icon that swaps
+ * when the chip is selected, a count that only shows when it is on.
+ */
+export function useChip(): ChipStateValue {
+  const ctx = useContext(ChipContext);
+  if (!ctx) {
+    throw new Error('useChip must be used within a <Chip>');
+  }
+  return { selected: ctx.selected, disabled: ctx.disabled };
+}
+
+/* -------------------------------------------------------------------------- */
+/* Chip                                                                       */
+/* -------------------------------------------------------------------------- */
+
+export interface ChipProps
+  extends Omit<AnimatedPressableProps, 'children' | 'disabled'>,
+    Omit<ChipVariantProps, 'selected' | 'disabled' | 'closable'> {
+  children?: ReactNode;
+  className?: string;
+  /** Extra classes for the label when `children` is a string. */
+  labelClassName?: string;
+  /**
+   * The filter "on" state. Setting it (even to `false`) makes the chip a
+   * toggle, announced as such — pair it with `onPress` to flip it.
+   */
+  selected?: boolean;
+  disabled?: boolean;
+  /** A leading icon or avatar, before the label. */
+  start?: ReactNode;
+  /**
+   * Shows a trailing ✕ and calls this when it is pressed. The ✕ is its own hit
+   * target, so removing a chip never also fires its `onPress`.
+   */
+  onClose?: () => void;
+  /** Accessibility label for the ✕. Defaults to "Remove". */
+  closeLabel?: string;
+  /**
+   * A tick under the finger when the chip is pressed or removed. Off by
+   * default — needs the optional `expo-haptics`, and is silent without it.
+   */
+  haptics?: boolean;
+}
+
+const ChipRoot = forwardRef<View, ChipProps>(
+  (
+    {
+      children,
+      className,
+      labelClassName,
+      variant = 'default',
+      size = 'md',
+      selected,
+      disabled = false,
+      start,
+      onClose,
+      closeLabel = 'Remove',
+      haptics = false,
+      onPress,
+      ...props
+    },
+    ref
+  ) => {
+    const isToggle = selected !== undefined;
+    const isSelected = selected ?? false;
+    const closable = onClose !== undefined;
+    // Only the whole chip becoming pressable warrants the press animation; a
+    // static attribute tag stays a plain View so it does not invite a tap.
+    const pressable = onPress !== undefined || isToggle;
+
+    const slots = chipVariants({
+      variant,
+      size,
+      selected: isSelected,
+      closable,
+      disabled,
+    });
+
+    // Icons and the ✕ inherit this, so they track the surface they sit on
+    // instead of every caller hardcoding a hex that is wrong in one theme.
+    const tint = useCSSVariable(
+      isSelected ? '--color-accent-foreground' : TINT_VAR[variant]
+    );
+
+    const handlePress = useCallback<NonNullable<AnimatedPressableProps['onPress']>>(
+      (event) => {
+        if (haptics) selectionTick();
+        onPress?.(event);
+      },
+      [haptics, onPress]
+    );
+
+    const handleClose = useCallback(() => {
+      if (haptics) selectionTick();
+      onClose?.();
+    }, [haptics, onClose]);
+
+    const labelClasses = slots.label();
+    const state = useMemo(
+      () => ({ selected: isSelected, disabled, labelClasses }),
+      [isSelected, disabled, labelClasses]
+    );
+
+    const body = (
+      <>
+        {start}
+        {typeof children === 'string' ? (
+          <Text className={slots.label({ className: labelClassName })}>
+            {children}
+          </Text>
+        ) : (
+          children
+        )}
+        {closable ? (
+          <Pressable
+            accessibilityRole="button"
+            accessibilityLabel={closeLabel}
+            // A small pill leaves little room for the ✕; the slop gives the
+            // finger the target the pixels do not.
+            hitSlop={8}
+            disabled={disabled}
+            onPress={handleClose}
+            className={slots.close()}
+          >
+            <XIcon size={CLOSE_ICON[size]} />
+          </Pressable>
+        ) : null}
+      </>
+    );
+
+    const sharedProps = {
+      accessibilityRole: 'button' as const,
+      // A toggle chip is read out as checked/unchecked; a plain pressable one
+      // as a button. A static tag gets neither, so it is not announced as
+      // something to press.
+      accessibilityState: { disabled, ...(isToggle ? { selected: isSelected } : {}) },
+      'aria-pressed': isToggle ? isSelected : undefined,
+      disabled,
+      className: slots.root({ className }),
+    };
+
+    return (
+      <ChipContext.Provider value={state}>
+        <IconColorProvider color={typeof tint === 'string' ? tint : undefined}>
+          {pressable ? (
+            <AnimatedPressable
+              ref={ref}
+              onPress={handlePress}
+              {...sharedProps}
+              {...props}
+            >
+              {body}
+            </AnimatedPressable>
+          ) : (
+            <View ref={ref} className={slots.root({ className })} {...(props as ViewProps)}>
+              {body}
+            </View>
+          )}
+        </IconColorProvider>
+      </ChipContext.Provider>
+    );
+  }
+);
+ChipRoot.displayName = 'Chip';
+
+/* -------------------------------------------------------------------------- */
+/* Chip.Label                                                                 */
+/* -------------------------------------------------------------------------- */
+
+export interface ChipLabelProps {
+  className?: string;
+  children: ReactNode;
+}
+
+/**
+ * The label, when the chip holds more than a string — an icon beside text. It
+ * reads the selected state itself, so composing the two does not mean threading
+ * the colour through by hand.
+ */
+function ChipLabel({ className, children }: ChipLabelProps) {
+  const ctx = useContext(ChipContext);
+  if (!ctx) {
+    throw new Error('Chip.Label must be used within a <Chip>');
+  }
+  return <Text className={cn(ctx.labelClasses, className)}>{children}</Text>;
+}
+ChipLabel.displayName = 'Chip.Label';
+
+export const Chip = Object.assign(ChipRoot, {
+  Label: ChipLabel,
+});

package/src/components/frame/index.tsx

@@ -15,28 +15,67 @@
  *   </Frame.Header>
  *   <Frame.Panel>
  *     <Frame.Row>…</Frame.Row>
- *     <Frame.Row divided>…</Frame.Row>
+ *     <Frame.Row>…</Frame.Row>
  *   </Frame.Panel>
  *   <Frame.Footer>Updated 2 minutes ago</Frame.Footer>
  * </Frame>
  * ```
+ *
+ * The panel draws the hairlines between its own rows. React Native has no
+ * `:first-child`, so the alternative is every caller writing
+ * `divided={index > 0}` on every row and getting it wrong once.
  */
-import { forwardRef, type ReactNode } from 'react';
-import { View, type Text as RNText, type ViewProps } from 'react-native';
+import { Children, cloneElement, forwardRef, isValidElement, type ReactNode } from 'react';
+import {
+  Pressable,
+  View,
+  type PressableProps,
+  type Text as RNText,
+  type ViewProps,
+} from 'react-native';
+import { tv } from 'tailwind-variants';
+import { ChevronRightIcon } from '../../icons';
 import { Text, type TextProps } from '../../primitives/text';
 import { cn } from '../../utils/cn';
 
+const frameVariants = tv({
+  slots: {
+    root: '',
+    panel: 'overflow-hidden rounded-xl border border-border bg-card',
+  },
+  variants: {
+    variant: {
+      default: { root: 'rounded-2xl border border-border bg-surface p-1.5' },
+      // No shell: the panel is the whole widget. For a Frame nested inside a
+      // card that already draws a border, where the shell's own edge sitting
+      // just inside it reads as a double line.
+      plain: { root: '', panel: 'rounded-2xl' },
+    },
+  },
+  defaultVariants: {
+    variant: 'default',
+  },
+});
+
+export type FrameVariant = 'default' | 'plain';
+
 export interface FrameProps extends ViewProps {
   className?: string;
 }
 
-const FrameRoot = forwardRef<View, FrameProps>(({ className, ...props }, ref) => (
-  <View
-    ref={ref}
-    className={cn('rounded-2xl border border-border bg-surface p-1.5', className)}
-    {...props}
-  />
-));
+export interface FrameRootProps extends FrameProps {
+  /**
+   * `plain` drops the outer shell so the panel is the widget — for a Frame
+   * inside a container that already draws its own border.
+   */
+  variant?: FrameVariant;
+}
+
+const FrameRoot = forwardRef<View, FrameRootProps>(
+  ({ className, variant, ...props }, ref) => (
+    <View ref={ref} className={frameVariants({ variant }).root({ className })} {...props} />
+  )
+);
 FrameRoot.displayName = 'Frame';
 
 export interface FrameHeaderProps extends FrameProps {
@@ -103,41 +142,147 @@ const FrameDescription = forwardRef<RNText, TextProps>(
 );
 FrameDescription.displayName = 'Frame.Description';
 
+/**
+ * Marks the parts that take part in the panel's own divider bookkeeping —
+ * a Row draws a line above itself, a Section draws one above its heading.
+ * Anything else the panel is given is left alone.
+ */
+interface Dividable {
+  divided?: boolean;
+}
+
+/**
+ * Draws the hairline above every child but the first. An explicit `divided`
+ * on a child wins, so a row can still opt out or force one.
+ */
+function divideChildren(children: ReactNode) {
+  let seen = 0;
+  return Children.map(children, (child) => {
+    if (!isValidElement<Dividable>(child)) return child;
+    if (!DIVIDABLE.has(child.type)) return child;
+
+    const index = seen++;
+    if (child.props.divided !== undefined) return child;
+    return cloneElement(child, { divided: index > 0 });
+  });
+}
+
+export interface FramePanelProps extends FrameProps {
+  /**
+   * Set false to place the hairlines by hand instead — for a panel whose rows
+   * are generated somewhere the divider order is not obvious.
+   */
+  dividers?: boolean;
+  children?: ReactNode;
+}
+
 /**
  * The inset card holding the frame's content — the raised surface sitting in
  * from the shell's edges, with its own smaller radius.
  */
-const FramePanel = forwardRef<View, FrameProps>(({ className, ...props }, ref) => (
-  <View
-    ref={ref}
-    className={cn('overflow-hidden rounded-xl border border-border bg-card', className)}
-    {...props}
-  />
-));
+const FramePanel = forwardRef<View, FramePanelProps>(
+  ({ className, dividers = true, children, ...props }, ref) => (
+    <View ref={ref} className={frameVariants().panel({ className })} {...props}>
+      {dividers ? divideChildren(children) : children}
+    </View>
+  )
+);
 FramePanel.displayName = 'Frame.Panel';
 
+export interface FrameRowProps extends Omit<PressableProps, 'children'>, Dividable {
+  className?: string;
+  /**
+   * Draw a hairline above this row. `Frame.Panel` sets it for you; pass it
+   * explicitly to override the panel's decision either way.
+   */
+  divided?: boolean;
+  /** Trailing chevron marking the row as leading somewhere. */
+  chevron?: boolean;
+  children?: ReactNode;
+}
+
 /**
- * A row inside a Frame.Panel. Pass `divided` on every row after the first to
- * draw a hairline separator above it (React Native has no :first-child).
+ * A row inside a Frame.Panel. Give it an `onPress` and it becomes a real
+ * pressable — press feedback, a button role — rather than a View with a
+ * handler bolted on.
  */
-export interface FrameRowProps extends FrameProps {
+const FrameRow = forwardRef<View, FrameRowProps>(
+  ({ className, divided, chevron, children, onPress, ...props }, ref) => {
+    const classes = cn(
+      'flex-row items-center gap-3 px-4 py-3.5',
+      divided && 'border-t border-border',
+      onPress && 'active:bg-muted',
+      className
+    );
+
+    const body = (
+      <>
+        {children}
+        {chevron ? <ChevronRightIcon size={16} /> : null}
+      </>
+    );
+
+    if (!onPress) {
+      return (
+        <View ref={ref} className={classes} {...(props as ViewProps)}>
+          {body}
+        </View>
+      );
+    }
+
+    return (
+      <Pressable
+        ref={ref}
+        accessibilityRole="button"
+        onPress={onPress}
+        className={classes}
+        {...props}
+      >
+        {body}
+      </Pressable>
+    );
+  }
+);
+FrameRow.displayName = 'Frame.Row';
+
+export interface FrameSectionProps extends FrameProps, Dividable {
+  /** Heading above the rows. Strings are wrapped for you. */
+  title?: ReactNode;
   divided?: boolean;
+  children?: ReactNode;
 }
 
-const FrameRow = forwardRef<View, FrameRowProps>(
-  ({ className, divided, ...props }, ref) => (
+/**
+ * A labelled cluster of rows inside a Panel, for a widget holding more than
+ * one group. It divides its own rows the way the panel does, so the two nest
+ * without either having to know about the other.
+ */
+const FrameSection = forwardRef<View, FrameSectionProps>(
+  ({ className, title, divided, children, ...props }, ref) => (
     <View
       ref={ref}
-      className={cn(
-        'flex-row items-center gap-3 px-4 py-3.5',
-        divided && 'border-t border-border',
-        className
-      )}
+      className={cn(divided && 'border-t border-border', className)}
       {...props}
-    />
+    >
+      {title ? (
+        <View className="bg-muted/40 px-4 pb-1.5 pt-2.5">
+          {typeof title === 'string' ? (
+            <Text size="xs" weight="medium" muted className="uppercase tracking-wider">
+              {title}
+            </Text>
+          ) : (
+            title
+          )}
+        </View>
+      ) : null}
+      {divideChildren(children)}
+    </View>
   )
 );
-FrameRow.displayName = 'Frame.Row';
+FrameSection.displayName = 'Frame.Section';
+
+/** Parts the panel divides. Declared after them, since it holds references. */
+const DIVIDABLE = new Set<unknown>([FrameRow, FrameSection]);
 
 export interface FrameFooterProps extends FrameProps {
   children?: ReactNode;
@@ -169,6 +314,7 @@ export const Frame = Object.assign(FrameRoot, {
   Action: FrameAction,
   Description: FrameDescription,
   Panel: FramePanel,
+  Section: FrameSection,
   Row: FrameRow,
   Footer: FrameFooter,
 });