panelui-native 0.44.0 → 0.49.0

package/src/components/accordion/index.tsx

@@ -9,6 +9,14 @@
  * `selectionMode` decides whether opening one section closes the others, which
  * also changes the shape of `value`: a string when single, an array when
  * multiple.
+ *
+ * A closed section costs nothing, because its body is unmounted. That is the
+ * right default and the wrong one for a body with state in it: a half-filled
+ * form, a list scrolled to the middle, a video part-way through. Collapsing
+ * such a section throws that away and reopening it starts over. `keepMounted`
+ * is the way out — the body stays mounted and is hidden from layout instead,
+ * so it takes up no room, the same layout transition carries the change, and
+ * everything inside is exactly where it was left.
  */
 import {
   Children,
@@ -90,6 +98,7 @@ interface AccordionContextValue {
   expanded: string[];
   toggle: (value: string) => void;
   variant: AccordionVariant;
+  keepMounted: boolean;
 }
 
 interface AccordionItemContextValue {
@@ -124,6 +133,13 @@ export interface AccordionProps extends ViewProps {
   onValueChange?: (value: string | string[]) => void;
   /** Hide the hairlines drawn between items. */
   hideSeparator?: boolean;
+  /**
+   * Keep every body mounted while its section is closed, so state inside it —
+   * a part-filled form, a scroll position, a running animation — survives being
+   * collapsed. Costs the render of every section up front; set it per section
+   * on `Accordion.Content` instead when only one of them needs it.
+   */
+  keepMounted?: boolean;
   children?: ReactNode;
 }
 
@@ -140,6 +156,7 @@ const AccordionRoot = forwardRef<View, AccordionProps>(
       defaultValue,
       onValueChange,
       hideSeparator = false,
+      keepMounted = false,
       children,
       ...props
     },
@@ -169,8 +186,8 @@ const AccordionRoot = forwardRef<View, AccordionProps>(
     );
 
     const context = useMemo(
-      () => ({ expanded, toggle, variant }),
-      [expanded, toggle, variant]
+      () => ({ expanded, toggle, variant, keepMounted }),
+      [expanded, toggle, variant, keepMounted]
     );
 
     const { root, separator } = accordionVariants({ variant });
@@ -299,6 +316,12 @@ AccordionIndicator.displayName = 'Accordion.Indicator';
 
 export interface AccordionContentProps extends ViewProps {
   className?: string;
+  /**
+   * Stay mounted while closed instead of unmounting, so state inside the body
+   * survives the section being collapsed. Overrides the accordion's own
+   * setting, either way round.
+   */
+  keepMounted?: boolean;
   children?: ReactNode;
 }
 
@@ -306,17 +329,36 @@ export interface AccordionContentProps extends ViewProps {
  * The collapsible body. Unmounts when closed, per the repo's convention for
  * conditionally shown content — the layout transition on the item animates
  * the height change.
+ *
+ * `keepMounted` swaps the unmount for `display: 'none'`, which is the one way
+ * to hide a view that also takes it out of Yoga's layout. That matters twice
+ * over: the item's height changes by exactly as much as it would have on an
+ * unmount, so the same layout transition plays and the two modes are
+ * indistinguishable to look at — and everything inside stays mounted, so a
+ * text field keeps what was typed into it. A hidden subtree is still in the
+ * accessibility tree, though, so it is explicitly taken out of that too;
+ * otherwise a screen reader would read out a section the eye cannot see.
  */
 const AccordionContent = forwardRef<View, AccordionContentProps>(
-  ({ className, children, ...props }, ref) => {
-    const { variant } = useAccordion('Accordion.Content');
+  ({ className, keepMounted, children, ...props }, ref) => {
+    const { variant, keepMounted: keepMountedDefault } = useAccordion('Accordion.Content');
     const { isExpanded } = useAccordionItem('Accordion.Content');
     const { content, contentText } = accordionVariants({ variant });
 
-    if (!isExpanded) return null;
+    const stayMounted = keepMounted ?? keepMountedDefault;
+    if (!isExpanded && !stayMounted) return null;
+
+    const isHidden = !isExpanded;
 
     return (
-      <View ref={ref} className={content({ className })} {...props}>
+      <View
+        ref={ref}
+        style={isHidden ? { display: 'none' } : undefined}
+        accessibilityElementsHidden={isHidden}
+        importantForAccessibility={isHidden ? 'no-hide-descendants' : 'auto'}
+        className={content({ className })}
+        {...props}
+      >
         {textChildren(children, (text) => (
           <Text className={contentText()}>{text}</Text>
         ))}

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;