panelui-native 0.46.0 → 0.49.0

package/src/components/button/index.tsx

@@ -1,4 +1,4 @@
-import { forwardRef, type ReactNode } from 'react';
+import { createContext, forwardRef, useContext, type ReactNode } from 'react';
 import { View } from 'react-native';
 import { tv, type VariantProps } from 'tailwind-variants';
 import { useCSSVariable } from 'uniwind';
@@ -7,6 +7,7 @@ import {
   type AnimatedPressableProps,
 } from '../../primitives/animated-pressable';
 import { Text, textChildren } from '../../primitives/text';
+import { cn } from '../../utils/cn';
 import { IconColorProvider } from '../../icons';
 import { getNativeUI, getSwiftUIModifiers } from '../../native';
 import { Spinner } from '../spinner';
@@ -72,6 +73,65 @@ const buttonVariants = tv({
 
 type ButtonVariantProps = VariantProps<typeof buttonVariants>;
 
+/** How a button looks. */
+export type ButtonVariant = NonNullable<ButtonVariantProps['variant']>;
+/** How big a button is. `icon` is a square. */
+export type ButtonSize = NonNullable<ButtonVariantProps['size']>;
+
+/* -------------------------------------------------------------------------- *
+ * Grouping
+ *
+ * A button reads this; `ButtonGroup` writes it. The context lives here rather
+ * than beside the group because the button is the consumer, and a component
+ * should not have to import the thing that contains it to find out that it is
+ * contained — which would also make the two import each other.
+ * -------------------------------------------------------------------------- */
+
+export interface ButtonGroupContextValue {
+  /** Fills in for a button that did not choose one. */
+  variant?: ButtonVariant;
+  /** Fills in for a button that did not choose one. */
+  size?: ButtonSize;
+  /** The buttons are joined into one shape, so each drops its own. */
+  attached: boolean;
+  /** Segments share the row equally. */
+  fullWidth: boolean;
+}
+
+const ButtonGroupContext = createContext<ButtonGroupContextValue | null>(null);
+
+/** Announces to every button below it that it is part of one control. */
+export function ButtonGroupProvider({
+  value,
+  children,
+}: {
+  value: ButtonGroupContextValue;
+  children: ReactNode;
+}) {
+  return <ButtonGroupContext.Provider value={value}>{children}</ButtonGroupContext.Provider>;
+}
+
+/** The enclosing group, if there is one. `null` for a button standing alone. */
+export function useButtonGroup(): ButtonGroupContextValue | null {
+  return useContext(ButtonGroupContext);
+}
+
+/**
+ * What an attached button gives up so the group can draw the shape once.
+ *
+ * The radius and the shadow go because the group owns both — a rounded,
+ * shadowed segment inside a rounded, shadowed container is two shapes where
+ * there should be one. The border stays but turns transparent rather than
+ * being removed: it is holding a pixel of the button's height, and dropping it
+ * would make an `outline` segment a hair shorter than a `ghost` one beside it.
+ *
+ * The press feedback changes too. A button on its own shrinks slightly when
+ * pressed, which inside a joined run would pull the segment away from its
+ * neighbours and show the container through the gap. A background is the same
+ * signal without the movement.
+ */
+const ATTACHED = 'rounded-none border-transparent shadow-none active:bg-accent';
+
 const SPINNER_SIZE = { sm: 'sm', md: 'sm', lg: 'md', icon: 'sm' } as const;
 
 /**
@@ -240,10 +300,28 @@ export const Button = forwardRef<View, ButtonProps>(
   ) => {
     const isDisabled = disabled || loading;
     const nativeUI = native ? getNativeUI() : null;
+
+    /*
+     * A group fills in what a button did not say for itself, and never
+     * overrides what it did: a run of buttons should look like one control
+     * without every segment repeating the same two props, and the odd segment
+     * that wants to stand out — the selected one, the destructive one — has to
+     * be able to say so.
+     *
+     * `native` is deliberately outside all of this. The platform draws that
+     * button, so it has no border, radius or shadow for a group to take over,
+     * and joining several of them would produce a row of platform buttons with
+     * a border drawn around it rather than a segmented control.
+     */
+    const group = useButtonGroup();
+    const attached = !native && group?.attached === true;
+    const resolvedVariant = variant ?? group?.variant;
+    const resolvedSize = size ?? group?.size;
+
     const { root, label, spinner } = buttonVariants({
-      variant,
-      size,
-      fullWidth,
+      variant: resolvedVariant,
+      size: resolvedSize,
+      fullWidth: fullWidth ?? (attached && group?.fullWidth),
       disabled: isDisabled,
     });
 
@@ -252,11 +330,11 @@ export const Button = forwardRef<View, ButtonProps>(
     // hardcode a hex that is wrong in one theme or the other.
     const themedColor = useCSSVariable(
       CONTENT_COLOR_VAR[
-        variant === 'destructive' ? 'primary' : (variant ?? 'primary')
+        resolvedVariant === 'destructive' ? 'primary' : (resolvedVariant ?? 'primary')
       ]
     );
     const contentColor =
-      variant === 'destructive'
+      resolvedVariant === 'destructive'
         ? '#ffffff'
         : typeof themedColor === 'string'
           ? themedColor
@@ -265,7 +343,7 @@ export const Button = forwardRef<View, ButtonProps>(
     if (nativeUI) {
       const { Host, Button: NativeButton, RNHostView } = nativeUI;
       const isStringLabel = typeof children === 'string';
-      const prominent = variant === 'primary' || variant === 'destructive';
+      const prominent = resolvedVariant === 'primary' || resolvedVariant === 'destructive';
 
       /*
        * Looks the portable props cannot ask for.
@@ -285,8 +363,10 @@ export const Button = forwardRef<View, ButtonProps>(
       const nativeModifiers = swiftUI
         ? [
             glass ? swiftUI.buttonStyle(prominent ? 'glassProminent' : 'glass') : null,
-            size === 'icon' ? swiftUI.buttonBorderShape('circle') : null,
-            isStringLabel ? swiftUI.controlSize(NATIVE_CONTROL_SIZE[size ?? 'md']) : null,
+            resolvedSize === 'icon' ? swiftUI.buttonBorderShape('circle') : null,
+            isStringLabel
+              ? swiftUI.controlSize(NATIVE_CONTROL_SIZE[resolvedSize ?? 'md'])
+              : null,
           ].filter(Boolean)
         : [];
 
@@ -303,7 +383,7 @@ export const Button = forwardRef<View, ButtonProps>(
         <Host matchContents>
           <NativeButton
             label={isStringLabel ? children : undefined}
-            variant={NATIVE_VARIANT[variant ?? 'primary']}
+            variant={NATIVE_VARIANT[resolvedVariant ?? 'primary']}
             disabled={isDisabled}
             /*
              * A square for an icon button, a height for a labelled one — and
@@ -316,9 +396,9 @@ export const Button = forwardRef<View, ButtonProps>(
              * the result.
              */
             style={
-              size === 'icon'
+              resolvedSize === 'icon'
                 ? { width: NATIVE_ICON_FRAME, height: NATIVE_ICON_FRAME }
-                : { height: NATIVE_HEIGHT[size ?? 'md'] }
+                : { height: NATIVE_HEIGHT[resolvedSize ?? 'md'] }
             }
             modifiers={nativeModifiers.length ? nativeModifiers : undefined}
             onPress={props.onPress}
@@ -337,7 +417,7 @@ export const Button = forwardRef<View, ButtonProps>(
                     sits on ends up off to one side of a circle that is not. */}
                 <View
                   style={
-                    size === 'icon'
+                    resolvedSize === 'icon'
                       ? {
                           padding: NATIVE_ICON_PADDING,
                           alignItems: 'center',
@@ -366,11 +446,13 @@ export const Button = forwardRef<View, ButtonProps>(
           accessibilityRole="button"
           accessibilityState={{ disabled: isDisabled, busy: loading }}
           disabled={isDisabled}
-          className={root({ className })}
+          // Before the spread, so a caller can still ask for the scale back.
+          pressScale={attached ? 1 : undefined}
+          className={root({ className: cn(attached && ATTACHED, className) })}
           {...props}
         >
           {loading ? (
-            <Spinner size={SPINNER_SIZE[size ?? 'md']} className={spinner()} />
+            <Spinner size={SPINNER_SIZE[resolvedSize ?? 'md']} className={spinner()} />
           ) : (
             startContent
           )}

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

@@ -0,0 +1,199 @@
+/**
+ * ButtonGroup — several buttons drawn as one control.
+ *
+ * ```tsx
+ * <ButtonGroup>
+ *   <Button startContent={<ListChecksIcon size={16} />}>Tasks</Button>
+ *   <Button startContent={<CalendarIcon size={16} />}>Agenda</Button>
+ *   <Button startContent={<ChartIcon size={16} />}>Board</Button>
+ * </ButtonGroup>
+ * ```
+ *
+ * The buttons stay buttons. Anything a `Button` does — an icon, a badge, a
+ * loading state, a disabled segment, opening a Popover — it still does inside a
+ * group, because the group is a container rather than a component that takes a
+ * list of items and renders them for you. A list-of-items API has to grow a
+ * prop for every one of those things; this one has none of them and can do all
+ * of them.
+ *
+ * ## Why the container draws the border
+ *
+ * A joined run could be built by giving the first and last segments their
+ * corners and squaring the ones between, then collapsing every shared edge with
+ * a negative margin. That works on the web and is a stack of off-by-one
+ * problems on a phone: the hairlines land on different fractions of a pixel per
+ * device, and a run that wraps has no first or last segment any more.
+ *
+ * So the group draws the shape once — one border, one radius, one shadow,
+ * clipped — and the buttons inside it draw none of their own. The dividers are
+ * real one-pixel views the group puts between its children, which is also why
+ * they are always exactly one pixel and always in the same place.
+ *
+ * ## What it passes down
+ *
+ * `variant` and `size` fill in for a button that did not choose its own, so a
+ * run of six does not repeat the same two props six times. A segment that wants
+ * to stand out — the selected one, the destructive one — sets its own and wins.
+ *
+ * ```tsx
+ * <ButtonGroup size="sm">
+ *   <Button>Day</Button>
+ *   <Button variant="secondary">Week</Button>   {/* the selected one *\/}
+ *   <Button>Month</Button>
+ * </ButtonGroup>
+ * ```
+ *
+ * ## Not a selection control
+ *
+ * This joins buttons; what they mean is yours. For a control that owns which
+ * one is on, reach for `ToggleButtonGroup`, and for switching between panels of
+ * content reach for `Tabs` — a segmented run of buttons that swaps a screen is
+ * navigation, and navigation should say so to a screen reader.
+ */
+import { Children, Fragment, forwardRef, useMemo, type ReactNode } from 'react';
+import { View, type ViewProps } from 'react-native';
+import { tv, type VariantProps } from 'tailwind-variants';
+import {
+  ButtonGroupProvider,
+  type ButtonGroupContextValue,
+  type ButtonSize,
+  type ButtonVariant,
+} from '../button';
+
+/** Which way the run reads. */
+export type ButtonGroupOrientation = 'horizontal' | 'vertical';
+
+const buttonGroupVariants = tv({
+  slots: {
+    root: 'items-stretch',
+    divider: 'bg-border',
+  },
+  variants: {
+    orientation: {
+      horizontal: { root: 'flex-row', divider: 'w-px' },
+      vertical: { root: 'flex-col', divider: 'h-px' },
+    },
+    attached: {
+      // `overflow-hidden` is what squares the inner corners and rounds the
+      // outer ones without any segment knowing which it is.
+      true: { root: 'overflow-hidden border border-input bg-popover shadow-sm' },
+      false: { root: 'gap-2' },
+    },
+    /* Matched to the height the buttons will be, since a radius that suited a
+       36pt run reads as a rectangle around a 48pt one. */
+    size: {
+      sm: { root: 'rounded-lg' },
+      md: { root: 'rounded-xl' },
+      lg: { root: 'rounded-xl' },
+      icon: { root: 'rounded-xl' },
+    },
+    fullWidth: {
+      true: { root: 'w-full' },
+    },
+  },
+  compoundVariants: [
+    // Nothing is being joined, so the radius belongs to each button instead.
+    { attached: false, class: { root: 'rounded-none' } },
+  ],
+  defaultVariants: {
+    orientation: 'horizontal',
+    attached: true,
+    size: 'md',
+  },
+});
+
+type ButtonGroupVariantProps = VariantProps<typeof buttonGroupVariants>;
+
+export interface ButtonGroupProps
+  extends ViewProps,
+    Omit<ButtonGroupVariantProps, 'size' | 'attached'> {
+  className?: string;
+  /** Which way the run reads. Vertical is the toolbar down the side of a canvas. */
+  orientation?: ButtonGroupOrientation;
+  /** Fills in for any button that did not choose its own. */
+  variant?: ButtonVariant;
+  /** Fills in for any button that did not choose its own, and sets the radius. */
+  size?: ButtonSize;
+  /**
+   * Draw the run as one joined shape.
+   *
+   * On by default — that is what a group is. Turn it off for a plain row of
+   * separate buttons that should still share a variant and a size, which is a
+   * toolbar rather than a segmented control.
+   */
+  attached?: boolean;
+  /**
+   * Span the container, with the segments sharing it equally.
+   *
+   * Equally, not by content: a row of segments at their natural widths is a row
+   * whose divisions move when the labels change, and a picker whose halves are
+   * different sizes reads as though one of them matters more.
+   */
+  fullWidth?: boolean;
+  children?: ReactNode;
+}
+
+const ButtonGroupRoot = forwardRef<View, ButtonGroupProps>(
+  (
+    {
+      className,
+      orientation = 'horizontal',
+      variant,
+      size = 'md',
+      attached = true,
+      fullWidth = false,
+      children,
+      ...props
+    },
+    ref
+  ) => {
+    const { root, divider } = buttonGroupVariants({
+      orientation,
+      attached,
+      size,
+      fullWidth,
+    });
+
+    const context = useMemo<ButtonGroupContextValue>(
+      () => ({ variant, size, attached, fullWidth }),
+      [variant, size, attached, fullWidth]
+    );
+
+    /*
+     * `Children.toArray` rather than the raw children: it drops the nulls a
+     * conditional segment leaves behind and flattens fragments, so a run built
+     * by a `map` or by `{canEdit && <Button/>}` gets its dividers in the right
+     * places instead of one before a segment that is not there.
+     */
+    const items = Children.toArray(children);
+
+    return (
+      <ButtonGroupProvider value={context}>
+        <View
+          ref={ref}
+          // A run of related actions is a toolbar; a screen reader announcing
+          // the group is what tells someone the buttons in it belong together.
+          accessibilityRole="toolbar"
+          className={root({ className })}
+          {...props}
+        >
+          {items.map((child, index) => (
+            // Index keys: these fragments have no identity of their own, and
+            // the children keep whatever keys they were already given.
+            <Fragment key={index}>
+              {index > 0 && attached ? <View className={divider()} /> : null}
+              {/* The share of the row is taken by a wrapper rather than by the
+                  button, so a segment that is a Popover trigger — a button
+                  inside something else — still gets one. */}
+              {fullWidth ? <View className="flex-1">{child}</View> : child}
+            </Fragment>
+          ))}
+        </View>
+      </ButtonGroupProvider>
+    );
+  }
+);
+
+ButtonGroupRoot.displayName = 'ButtonGroup';
+
+export const ButtonGroup = ButtonGroupRoot;

package/src/components/color-picker/index.tsx

@@ -28,6 +28,28 @@
  * a control with no alpha is one that has no `ColorPicker.Alpha`, not one with
  * a prop turned off.
  *
+ * ## Folding it away
+ *
+ * A picker is a page's worth of controls in service of one value, and that
+ * value is read far more often than it is changed — so `presentation` puts the
+ * controls behind the row that reads it out:
+ *
+ * ```tsx
+ * <ColorPicker value={accent} onValueChange={setAccent} presentation="popover">
+ *   <ColorPicker.Trigger>
+ *     <ColorPicker.Field label="Accent" />
+ *   </ColorPicker.Trigger>
+ *   <ColorPicker.Content>
+ *     <ColorPicker.Area />
+ *     <ColorPicker.Hue />
+ *   </ColorPicker.Content>
+ * </ColorPicker>
+ * ```
+ *
+ * `Content` re-provides the picker's context around what it holds, because the
+ * panel is portalled above the rest of the screen and is therefore no longer
+ * below the picker in the tree by the time the parts inside it go looking.
+ *
  * Works controlled (`value` + `onValueChange`) or uncontrolled (`defaultValue`).
  */
 import {
@@ -40,6 +62,7 @@ import {
   useMemo,
   useRef,
   useState,
+  type ReactElement,
   type ReactNode,
 } from 'react';
 import {
@@ -81,7 +104,9 @@ import {
   type ColorFormat,
   type HsvaColor,
 } from '../../utils/color';
+import { cn } from '../../utils/cn';
 import { selectionTick } from '../../utils/haptics';
+import { Popover, type PopoverContentProps } from '../popover';
 
 /** Settles a thumb that was moved by something other than a finger. */
 const TIMING = { duration: 140 } as const;
@@ -206,6 +231,16 @@ function useColorPicker(part: string) {
 /** Where a picker starts when it is handed a value it cannot read. */
 const FALLBACK: HsvaColor = { h: 0, s: 1, v: 1, a: 1 };
 
+/** How the controls get onto the screen. */
+export type ColorPickerPresentation = 'inline' | 'popover' | 'bottom-sheet';
+
+/**
+ * Floor for the panel's width when it takes the trigger's. A swatch row is a
+ * narrow trigger, and a square you drag on is not a control that survives being
+ * squeezed to match one.
+ */
+const CONTENT_MIN_WIDTH = 268;
+
 export interface ColorPickerProps extends Omit<ColorPickerVariantProps, 'disabled'> {
   className?: string;
   /** Controlled colour. Leave unset and pass `defaultValue` to run uncontrolled. */
@@ -233,6 +268,19 @@ export interface ColorPickerProps extends Omit<ColorPickerVariantProps, 'disable
    * buzz proportional to speed.
    */
   haptics?: boolean;
+  /**
+   * How the controls get onto the screen.
+   *
+   * `inline` stacks them where they are written, and is the default. The other
+   * two put them behind a `ColorPicker.Trigger` and draw them in a
+   * `ColorPicker.Content` — which is the arrangement a colour usually wants,
+   * since a picker is a page's worth of controls in service of one value that
+   * is looked at far more often than it is changed.
+   */
+  presentation?: ColorPickerPresentation;
+  /** Controlled open state of the panel. Ignored by `inline`. */
+  open?: boolean;
+  onOpenChange?: (open: boolean) => void;
   /** The parts, in the order they should stack. */
   children: ReactNode;
 }
@@ -249,6 +297,9 @@ const ColorPickerRoot = forwardRef<View, ColorPickerProps>(
       disabled = false,
       haptics = false,
       size = 'md',
+      presentation = 'inline',
+      open,
+      onOpenChange,
       children,
     },
     ref
@@ -319,6 +370,16 @@ const ColorPickerRoot = forwardRef<View, ColorPickerProps>(
       [hue, saturation, brightness, opacity, emit, format, disabled, haptics, size]
     );
 
+    if (presentation !== 'inline') {
+      return (
+        <ColorPickerContext.Provider value={context}>
+          <Popover open={open} onOpenChange={onOpenChange} presentation={presentation}>
+            {children}
+          </Popover>
+        </ColorPickerContext.Provider>
+      );
+    }
+
     return (
       <ColorPickerContext.Provider value={context}>
         <View ref={ref} className={slots.root({ className })} collapsable={false}>
@@ -331,6 +392,64 @@ const ColorPickerRoot = forwardRef<View, ColorPickerProps>(
 
 ColorPickerRoot.displayName = 'ColorPicker';
 
+/* ------------------------------------------------------------------ *
+ * Trigger and Content — the picker folded away behind the value.
+ * ------------------------------------------------------------------ */
+
+export interface ColorPickerTriggerProps {
+  /** One element, cloned with an `onPress` that opens the panel. */
+  children: ReactElement<{ onPress?: (...args: unknown[]) => void }>;
+}
+
+/**
+ * What you press to open the picker. `ColorPicker.Field` is the obvious child —
+ * it already reads out the colour it would let you change — but anything that
+ * takes an `onPress` will do.
+ */
+function ColorPickerTrigger({ children }: ColorPickerTriggerProps) {
+  useColorPicker('ColorPicker.Trigger');
+  return <Popover.Trigger>{children}</Popover.Trigger>;
+}
+
+ColorPickerTrigger.displayName = 'ColorPicker.Trigger';
+
+export interface ColorPickerContentProps extends PopoverContentProps {}
+
+/**
+ * The panel the controls are drawn in.
+ *
+ * It re-provides the picker's context around its children, and has to: the
+ * panel is rendered through a portal, above everything else on the screen, so
+ * by the time the parts inside it look for the picker they are no longer
+ * anywhere below it in the tree. Without this the first `ColorPicker.Area`
+ * inside a popover would throw.
+ *
+ * Defaults to the trigger's width, floored, so a panel opened from a labelled
+ * strip lines up under it rather than announcing itself as a different object.
+ */
+function ColorPickerContent({
+  className,
+  width = 'trigger',
+  minWidth = CONTENT_MIN_WIDTH,
+  children,
+  ...props
+}: ColorPickerContentProps) {
+  const ctx = useColorPicker('ColorPicker.Content');
+
+  return (
+    <Popover.Content
+      width={width}
+      minWidth={minWidth}
+      className={cn('gap-3', className)}
+      {...props}
+    >
+      <ColorPickerContext.Provider value={ctx}>{children}</ColorPickerContext.Provider>
+    </Popover.Content>
+  );
+}
+
+ColorPickerContent.displayName = 'ColorPicker.Content';
+
 /* ------------------------------------------------------------------ *
  * The checkerboard behind anything translucent.
  * ------------------------------------------------------------------ */
@@ -1083,6 +1202,14 @@ export interface ColorPickerFieldProps {
   showValue?: boolean;
   /** Extra classes for the swatch. */
   swatchClassName?: string;
+  /**
+   * Makes the strip pressable, and a button to a screen reader.
+   *
+   * Mostly you do not pass this yourself: `ColorPicker.Trigger` clones the
+   * strip with one, which is what turns the row into the thing that opens the
+   * picker.
+   */
+  onPress?: (...args: unknown[]) => void;
   /** Anything to put after the swatch — a copy button, a reset. */
   children?: ReactNode;
 }
@@ -1095,7 +1222,7 @@ export interface ColorPickerFieldProps {
  * A drag through a hundred frames of the same hex costs one render.
  */
 const ColorPickerField = forwardRef<View, ColorPickerFieldProps>(
-  ({ className, label, showValue = true, swatchClassName, children }, ref) => {
+  ({ className, label, showValue = true, swatchClassName, onPress, children }, ref) => {
     const ctx = useColorPicker('ColorPicker.Field');
     const slots = colorPickerVariants({ size: ctx.size });
     const diameter = FIELD_SWATCH[ctx.size];
@@ -1145,13 +1272,21 @@ const ColorPickerField = forwardRef<View, ColorPickerFieldProps>(
       ),
     }));
 
+    // Pressable only when it has somewhere to go. A row that highlights under
+    // a finger and then does nothing is a worse lie than a row that does not
+    // react at all.
+    const Row = onPress ? Pressable : View;
+
     return (
-      <View
+      <Row
         ref={ref}
+        onPress={onPress}
+        disabled={onPress ? ctx.disabled : undefined}
         className={slots.field({ className })}
         // One thing being read out, not three: a label, a value and a swatch
         // announced separately are three stops that each say a third of it.
         accessible
+        accessibilityRole={onPress ? 'button' : undefined}
         accessibilityLabel={label ? `${label}, ${printed}` : printed}
       >
         {label ? <Text className={slots.fieldLabel()}>{label}</Text> : null}
@@ -1168,7 +1303,7 @@ const ColorPickerField = forwardRef<View, ColorPickerFieldProps>(
           <Animated.View style={[StyleSheet.absoluteFill, fillStyle]} />
         </View>
         {children}
-      </View>
+      </Row>
     );
   }
 );
@@ -1606,6 +1741,8 @@ const ColorPickerWheel = forwardRef<View, ColorPickerWheelProps>(
 ColorPickerWheel.displayName = 'ColorPicker.Wheel';
 
 export const ColorPicker = Object.assign(ColorPickerRoot, {
+  Trigger: ColorPickerTrigger,
+  Content: ColorPickerContent,
   Field: ColorPickerField,
   Area: ColorPickerArea,
   Wheel: ColorPickerWheel,