panelui-native 0.25.0 → 0.30.0

package/src/components/bar-chart/index.tsx

@@ -64,6 +64,7 @@ import Svg, { G, Line as SvgLine, Path } from 'react-native-svg';
 import { useCSSVariable } from 'uniwind';
 import { Text } from '../../primitives/text';
 import {
+  bandOf,
   barPath,
   columnValues,
   compactNumber,
@@ -90,9 +91,15 @@ const PADDING_SIDEWAYS = { top: 6, right: 10, bottom: 6, left: 68 };
 const LABEL_WIDTH = 132;
 
 /** Left gutter reserved when a `YAxis` is present, for its labels to sit in. */
-const Y_AXIS_WIDTH = 40;
+const Y_AXIS_WIDTH = 44;
 
-type Layer = 'svg' | 'overlay';
+/** Gap between the value labels and the plot they sit beside. */
+const Y_AXIS_GUTTER = 6;
+
+/** Line height of an `xs` label, for centring one on the grid line it names. */
+const AXIS_LABEL_HEIGHT = 16;
+
+type Layer = 'svg' | 'overlay' | 'header';
 
 export type BarChartStatus = 'loading' | 'ready';
 export type BarChartOrientation = 'vertical' | 'horizontal';
@@ -213,13 +220,14 @@ export interface BarChartHandle {
 function partition(children: ReactNode) {
   const svg: ReactNode[] = [];
   const overlay: ReactNode[] = [];
+  const header: ReactNode[] = [];
   Children.forEach(children, (child, index) => {
     if (!isValidElement(child)) return;
     const layer = (child.type as { layer?: Layer }).layer ?? 'svg';
     const slot = <ChildSlot key={index}>{child}</ChildSlot>;
-    (layer === 'overlay' ? overlay : svg).push(slot);
+    (layer === 'header' ? header : layer === 'overlay' ? overlay : svg).push(slot);
   });
-  return { svg, overlay };
+  return { svg, overlay, header };
 }
 
 function ChildSlot({ children }: { children: ReactNode }) {
@@ -450,24 +458,28 @@ const BarChartRoot = forwardRef<BarChartHandle, BarChartProps>(function BarChart
     ]
   );
 
-  const { svg, overlay } = partition(children);
+  const { svg, overlay, header } = partition(children);
 
+  /*
+   * Two views, because the header is not part of the plot. `aspectRatio` and
+   * the layout measurement belong to the drawing area alone — measured on the
+   * outer view they would take in the header too, and the plot would lose as
+   * much height as the readout took while still claiming the shape asked for.
+   */
   return (
     <BarChartContext.Provider value={context}>
-      <View
-        {...props}
-        onLayout={onLayout}
-        style={[{ aspectRatio }, props.style]}
-        className={cn('w-full', className)}
-      >
-        {plot.width > 0 ? (
-          <>
-            <Svg width="100%" height="100%" style={StyleSheet.absoluteFill}>
-              {svg}
-            </Svg>
-            {overlay}
-          </>
-        ) : null}
+      <View {...props} style={props.style} className={cn('w-full', className)}>
+        {header}
+        <View onLayout={onLayout} style={{ aspectRatio }} className="w-full">
+          {plot.width > 0 ? (
+            <>
+              <Svg width="100%" height="100%" style={StyleSheet.absoluteFill}>
+                {svg}
+              </Svg>
+              {overlay}
+            </>
+          ) : null}
+        </View>
       </View>
     </BarChartContext.Provider>
   );
@@ -730,8 +742,18 @@ BarChartBar.layer = 'svg' as Layer;
 /* Overlay layer                                                              */
 /* -------------------------------------------------------------------------- */
 
+/**
+ * Narrowest a category label may be drawn before the axis starts dropping
+ * some. Roughly three characters at `xs`, which is what a month abbreviation
+ * or a short name needs.
+ */
+const MIN_BAND_LABEL = 34;
+
 export interface BarChartXAxisProps {
-  /** How many labels to show. The rest are dropped, evenly. */
+  /**
+   * How many labels to show. Every category by default, thinned only when the
+   * bands get too narrow to read — pass a number to force it lower.
+   */
   ticks?: number;
   /** Turn a row into its label. Defaults to the value at `xDataKey`. */
   format?: (datum: BarChartDatum, index: number) => string;
@@ -743,40 +765,77 @@ export interface BarChartXAxisProps {
  * than SVG text, so they follow the theme's font and the platform's text
  * scaling — SVG text does neither.
  */
-function BarChartXAxis({ ticks = 6, format, className }: BarChartXAxisProps) {
+function BarChartXAxis({ ticks, format, className }: BarChartXAxisProps) {
   const { data, xDataKey, plot, orientation } = useChart('BarChart.XAxis');
 
   const labels = useMemo(() => {
     if (!data.length) return [];
-    const count = Math.min(ticks, data.length);
-    const step = count > 1 ? (data.length - 1) / (count - 1) : 0;
-    return Array.from({ length: count }, (_unused, index) => {
-      const dataIndex = Math.round(index * step);
-      const datum = data[dataIndex];
-      if (!datum) return null;
-      return {
-        key: dataIndex,
-        text: format ? format(datum, dataIndex) : String(datum[xDataKey] ?? ''),
-      };
-    }).filter((label): label is { key: number; text: string } => label !== null);
-  }, [data, ticks, format, xDataKey]);
+
+    /*
+     * Every category, unless they will not fit. A fixed tick count dropped
+     * names that had room to be drawn — eight months at six ticks lost March
+     * and June for no reason anyone looking at the chart could see. The axis
+     * asks the plot how much room there is instead, and only thins when the
+     * answer is not enough.
+     */
+    const room = Math.max(1, Math.floor(plot.width / MIN_BAND_LABEL));
+    const count = Math.max(1, Math.min(ticks ?? room, data.length));
+
+    // Every nth band, rather than a fractional step rounded to the nearest
+    // index — rounding lands on the same band twice and skips its neighbour.
+    const stride = Math.ceil(data.length / count);
+    const picked: { key: number; text: string }[] = [];
+    for (let index = 0; index < data.length; index += stride) {
+      const datum = data[index];
+      if (!datum) continue;
+      picked.push({
+        key: index,
+        text: format ? format(datum, index) : String(datum[xDataKey] ?? ''),
+      });
+    }
+    return picked;
+  }, [data, ticks, format, xDataKey, plot.width]);
 
   if (orientation === 'horizontal') return null;
 
+  /*
+   * Each label is placed on its own band's centre, not spaced evenly along the
+   * axis. Two things went wrong when they were spread with `justify-between`:
+   * a bar owns a *band* rather than sitting on a point, so the first and last
+   * labels were half a band out at the edges; and the indices `ticks` picks
+   * are not evenly spaced (eight months shown six at a time gives 0,1,3,4,6,7),
+   * so the ones between were spread evenly over gaps that are not.
+   *
+   * The box is backed off by half its own width rather than translated by
+   * `-50%`, which is not reliable across React Native versions.
+   */
+  /*
+   * One box per band, exactly the band's width. Tiling them rather than giving
+   * each a fixed width means they can never overlap each other and the first
+   * and last can never hang off the ends of the plot — the row of labels
+   * occupies precisely the space the bars do.
+   */
+  const bandWidth = data.length > 0 ? plot.width / data.length : 0;
+
   return (
     <View
-      pointerEvents="none"
-      style={{
-        position: 'absolute',
-        left: plot.left,
-        right: PADDING.right,
-        bottom: 0,
-        height: PADDING.bottom,
-      }}
-      className={cn('flex-row items-center justify-between', className)}
+      style={{ position: 'absolute', inset: 0, pointerEvents: 'none' }}
+      className={cn(className)}
     >
       {labels.map((label) => (
-        <Text key={label.key} size="xs" muted numberOfLines={1}>
+        <Text
+          key={label.key}
+          size="xs"
+          muted
+          numberOfLines={1}
+          style={{
+            position: 'absolute',
+            bottom: 0,
+            left: bandOf(label.key, data.length, plot) - bandWidth / 2,
+            width: bandWidth,
+            textAlign: 'center',
+          }}
+        >
           {label.text}
         </Text>
       ))}
@@ -834,8 +893,12 @@ function BarChartYAxis({ ticks = 4, format, className }: BarChartYAxisProps) {
       style={{
         position: 'absolute',
         left: 0,
-        top: plot.top,
-        height: plot.height,
+        // Upright, each label is centred on the grid line it names: the strip
+        // is lifted half a label and grown by a whole one, so `justify-between`
+        // lands the text's middle on the line rather than its top edge on the
+        // first and its bottom edge on the last.
+        top: horizontal ? plot.top : plot.top - AXIS_LABEL_HEIGHT / 2,
+        height: horizontal ? plot.height : plot.height + AXIS_LABEL_HEIGHT,
         width: horizontal ? Math.max(plot.left - 8, 0) : undefined,
       }}
       className={cn(horizontal ? 'items-end' : 'justify-between', className)}
@@ -1011,6 +1074,18 @@ export interface BarChartLegendProps extends ViewProps {
   labels?: Record<string, string>;
 }
 
+/** One series' colour and name. Shared by the legend and the header. */
+function SeriesSwatch({ color, label }: { color: string; label: string }) {
+  return (
+    <View className="flex-row items-center gap-1.5">
+      <View style={{ backgroundColor: color }} className="h-2 w-2 rounded-full" />
+      <Text size="xs" muted>
+        {label}
+      </Text>
+    </View>
+  );
+}
+
 /** A swatch and a name per series, in the order the series were declared. */
 function BarChartLegend({ className, labels, ...props }: BarChartLegendProps) {
   const { series } = useChart('BarChart.Legend');
@@ -1019,18 +1094,11 @@ function BarChartLegend({ className, labels, ...props }: BarChartLegendProps) {
   return (
     <View
       {...props}
-      pointerEvents="none"
+      style={[{ pointerEvents: 'none' }, props.style]}
       className={cn('absolute right-2 top-1 flex-row gap-3', className)}
     >
       {series.map(([key, color]) => (
-        <View key={key} className="flex-row items-center gap-1.5">
-          <View
-            style={{ width: 8, height: 8, borderRadius: 2, backgroundColor: color }}
-          />
-          <Text size="xs" muted>
-            {labels?.[key] ?? key}
-          </Text>
-        </View>
+        <SeriesSwatch key={key} color={color} label={labels?.[key] ?? key} />
       ))}
     </View>
   );
@@ -1038,7 +1106,99 @@ function BarChartLegend({ className, labels, ...props }: BarChartLegendProps) {
 BarChartLegend.displayName = 'BarChart.Legend';
 BarChartLegend.layer = 'overlay' as Layer;
 
+/* -------------------------------------------------------------------------- */
+/* Header layer                                                               */
+/* -------------------------------------------------------------------------- */
+
+export interface BarChartHeaderProps extends ViewProps {
+  className?: string;
+  /** Small line above the value — what the chart is of. */
+  title?: string;
+  /** The readout. The largest thing on the card, and the first thing read. */
+  value?: string;
+  /** One muted line under the value — a period, a comparison, a total. */
+  caption?: string;
+  /** Prettier names for the series keys, as the legend takes. */
+  labels?: Record<string, string>;
+  /**
+   * Draw a swatch and a name per series along the trailing edge. Prefer this to
+   * `BarChart.Legend` on a chart that has a header: the legend floats over the
+   * plot, where it competes with the bars for the same corner.
+   */
+  legend?: boolean;
+  /** Trailing slot — a control, a badge, a range picker. Wins over `legend`. */
+  children?: ReactNode;
+}
+
+/**
+ * The strip above the plot: what the chart is of, what it currently reads, and
+ * what the colours mean.
+ *
+ * It belongs to the chart rather than to the card around it because it is about
+ * the *plot* — the number changes as a finger moves along the bars, and the
+ * legend is the series list the chart itself is holding. The card's header is a
+ * caption on the tray the chart sits in; this is the chart introducing itself.
+ *
+ * The value is not derived here. A readout that follows the finger belongs to
+ * whoever owns the data — take it from `onActiveIndexChange` and pass the
+ * formatted string down, so one header can show a total when nothing is pressed
+ * and a band's value when something is.
+ */
+function BarChartHeader({
+  className,
+  title,
+  value,
+  caption,
+  labels,
+  legend = false,
+  children,
+  ...props
+}: BarChartHeaderProps) {
+  const { series } = useChart('BarChart.Header');
+  const trailing =
+    children ??
+    (legend && series.length ? (
+      <View className="flex-row flex-wrap items-center justify-end gap-x-3 gap-y-1">
+        {series.map(([key, color]) => (
+          <SeriesSwatch key={key} color={color} label={labels?.[key] ?? key} />
+        ))}
+      </View>
+    ) : null);
+
+  return (
+    <View
+      {...props}
+      className={cn('flex-row items-start justify-between gap-3 pb-3', className)}
+    >
+      <View className="flex-1 gap-0.5">
+        {title ? (
+          <Text size="xs" muted>
+            {title}
+          </Text>
+        ) : null}
+        {value ? (
+          <Text size="xl" weight="bold">
+            {value}
+          </Text>
+        ) : null}
+        {caption ? (
+          <Text size="xs" muted>
+            {caption}
+          </Text>
+        ) : null}
+      </View>
+      {/* Shrinkable, unlike a view's default in React Native. Held rigid, a
+          three-series key takes the width it wants and the caption underneath
+          the value wraps to two lines to make room for it. */}
+      {trailing ? <View className="shrink pt-1">{trailing}</View> : null}
+    </View>
+  );
+}
+BarChartHeader.displayName = 'BarChart.Header';
+BarChartHeader.layer = 'header' as Layer;
+
 export const BarChart = Object.assign(BarChartRoot, {
+  Header: BarChartHeader,
   Grid: BarChartGrid,
   Bar: BarChartBar,
   XAxis: BarChartXAxis,

package/src/components/bottom-sheet/index.tsx

@@ -33,7 +33,8 @@ import { getNativeUI } from '../../native';
 import { XIcon } from '../../icons';
 import { Portal } from '../../primitives/portal';
 import { Scrim } from '../../primitives/scrim';
-import { Text } from '../../primitives/text';
+import { Text, textChildren } from '../../primitives/text';
+import { useBackHandler } from '../../hooks/use-back-handler';
 import { cn } from '../../utils/cn';
 
 const SPRING = { damping: 22, stiffness: 280, mass: 0.7 } as const;
@@ -290,6 +291,10 @@ function BottomSheetContent({
 
   const close = useCallback(() => setOpen(false), [setOpen]);
 
+  // The sheet closes on the Android back button while it is up, the same as a
+  // backdrop tap — but only when it is dismissible.
+  useBackHandler(open && dismissible, close);
+
   /*
    * The offset survives a close — the early return below sits after every
    * hook, so this component keeps its state while the sheet is hidden. A
@@ -418,7 +423,7 @@ function BottomSheetContent({
                   paddingBottom: Math.max(insets.bottom, 16),
                 }}
               >
-                {children}
+                {textChildren(children)}
               </View>
             </BottomSheetContext.Provider>
           </RNHostView>
@@ -470,7 +475,7 @@ function BottomSheetContent({
               <View className="mb-3 self-center">
                 <View className="h-1 w-10 rounded-full bg-muted-foreground/30" />
               </View>
-              {children}
+              {textChildren(children)}
               {/*
                 * Last, and lifted above the content.
                 *
@@ -534,21 +539,17 @@ function BottomSheetHeader({
 }: BottomSheetHeaderProps) {
   return (
     <View className={cn('gap-1 pb-3 pe-12', className)} {...props}>
-      {typeof title === 'string' ? (
+      {textChildren(title, (text) => (
         <Text size="lg" weight="semibold">
-          {title}
+          {text}
         </Text>
-      ) : (
-        title
-      )}
-      {typeof description === 'string' ? (
+      ))}
+      {textChildren(description, (text) => (
         <Text size="sm" muted>
-          {description}
+          {text}
         </Text>
-      ) : (
-        description
-      )}
-      {children}
+      ))}
+      {textChildren(children)}
     </View>
   );
 }
@@ -607,7 +608,7 @@ function BottomSheetBody({
       className={cn('flex-1', className)}
       {...props}
     >
-      {children}
+      {textChildren(children)}
     </Animated.ScrollView>
   );
 
@@ -641,7 +642,7 @@ function BottomSheetFooter({
       className={cn('gap-2 border-t border-border pt-3', className)}
       {...props}
     >
-      {children}
+      {textChildren(children)}
     </View>
   );
 }

package/src/components/breadcrumb/index.tsx

@@ -47,7 +47,7 @@ import {
   AnimatedPressable,
   type AnimatedPressableProps,
 } from '../../primitives/animated-pressable';
-import { Text, type TextProps } from '../../primitives/text';
+import { Text, type TextProps, textChildren } from '../../primitives/text';
 import { cn } from '../../utils/cn';
 
 type BreadcrumbSize = 'sm' | 'default';
@@ -102,7 +102,7 @@ const BreadcrumbRoot = forwardRef<View, BreadcrumbProps>(
         className={cn('w-full', className)}
         {...props}
       >
-        {children}
+        {textChildren(children)}
       </View>
     </BreadcrumbContext.Provider>
   )
@@ -202,7 +202,7 @@ const BreadcrumbItem = forwardRef<View, BreadcrumbItemProps>(
       className={cn('flex-row items-center', className)}
       {...props}
     >
-      {children}
+      {textChildren(children)}
     </View>
   )
 );
@@ -235,13 +235,11 @@ const BreadcrumbLink = forwardRef<View, BreadcrumbLinkProps>(
         className={cn('flex-row items-center', className)}
         {...props}
       >
-        {typeof children === 'string' ? (
+        {textChildren(children, (text) => (
           <Text className={crumbText({ size, className: cn('text-muted-foreground', textClassName) })}>
-            {children}
+            {text}
           </Text>
-        ) : (
-          children
-        )}
+        ))}
       </AnimatedPressable>
     );
   }

package/src/components/button/index.tsx

@@ -6,7 +6,7 @@ import {
   AnimatedPressable,
   type AnimatedPressableProps,
 } from '../../primitives/animated-pressable';
-import { Text } from '../../primitives/text';
+import { Text, textChildren } from '../../primitives/text';
 import { IconColorProvider } from '../../icons';
 import { getNativeUI } from '../../native';
 import { Spinner } from '../spinner';
@@ -210,10 +210,16 @@ export const Button = forwardRef<View, ButtonProps>(
           >
             {/* Non-string children are React Native views, and the native
                 button cannot measure those directly — they have to be hosted
-                or they render outside the button's bounds. */}
+                or they render outside the button's bounds. An icon beside a
+                label is the common case, and the label half of it is still
+                bare text once it is in there. */}
             {isStringLabel ? undefined : (
               <RNHostView matchContents>
-                <>{children}</>
+                <>
+                  {textChildren(children, (text) => (
+                    <Text className={label({ className: labelClassName })}>{text}</Text>
+                  ))}
+                </>
               </RNHostView>
             )}
           </NativeButton>
@@ -236,11 +242,9 @@ export const Button = forwardRef<View, ButtonProps>(
           ) : (
             startContent
           )}
-          {typeof children === 'string' ? (
-            <Text className={label({ className: labelClassName })}>{children}</Text>
-          ) : (
-            children
-          )}
+          {textChildren(children, (text) => (
+            <Text className={label({ className: labelClassName })}>{text}</Text>
+          ))}
           {endContent}
         </AnimatedPressable>
       </IconColorProvider>