panelui-native 0.40.0 → 0.41.0

package/src/components/card/index.tsx

@@ -1,5 +1,35 @@
-import { forwardRef } from 'react';
-import { View, type ViewProps } from 'react-native';
+/**
+ * Card — a content surface, and the layer that decorates it.
+ *
+ * ```tsx
+ * <Card>
+ *   <Card.Header>
+ *     <Card.Title>Living room sofa</Card.Title>
+ *     <Card.Description>Three seats, oat linen</Card.Description>
+ *   </Card.Header>
+ *   <Card.Footer>
+ *     <Button fullWidth>Buy now</Button>
+ *   </Card.Footer>
+ * </Card>
+ * ```
+ *
+ * All the padding lives on the slots and none of it on the root, which is why
+ * a card whose media reaches its own corners needs nothing but
+ * `overflow-hidden`.
+ */
+import { forwardRef, useEffect, useMemo } from 'react';
+import { StyleSheet, View, type ViewProps } from 'react-native';
+import Animated, {
+  Easing,
+  cancelAnimation,
+  useAnimatedStyle,
+  useReducedMotion,
+  useSharedValue,
+  withRepeat,
+  withTiming,
+} from 'react-native-reanimated';
+import { LinearGradient } from 'expo-linear-gradient';
+import { useCSSVariable } from 'uniwind';
 import { cn } from '../../utils/cn';
 import { Text, type TextProps } from '../../primitives/text';
 
@@ -55,10 +85,205 @@ const CardFooter = forwardRef<View, CardProps>(({ className, ...props }, ref) =>
 ));
 CardFooter.displayName = 'Card.Footer';
 
+/* -------------------------------------------------------------------------- */
+/* Card.Wash                                                                  */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * How sharply the wash dissolves upward. The exponent is the whole look: at 1
+ * the colour is already at half strength across the middle of the card and
+ * reads as a tinted panel, and it takes about a cube before the top is
+ * genuinely untouched and the colour arrives in the bottom third.
+ */
+const WASH_CURVE = 3;
+/**
+ * Stops the curve is sampled at. Ten is enough that the straight lines the
+ * renderer draws between them are not a shape anyone can see, and the fade
+ * stays continuous — stepping it would put a horizontal seam at every step.
+ */
+const WASH_STOPS = 10;
+/** How long one breath takes at `speed={1}`. */
+const WASH_PERIOD = 4200;
+/**
+ * How far the wash swells and settles over one breath, as a fraction of
+ * `intensity`. Small on purpose: the movement should be noticed only by not
+ * being there, and anything larger reads as a light being switched.
+ */
+const WASH_BREATH = 0.22;
+
+function isToken(value: string | undefined): value is string {
+  return typeof value === 'string' && value.startsWith('--');
+}
+
+/**
+ * Gradients need a transparent stop of the *same* colour — `transparent` is
+ * black at zero alpha on Android, which shows as a grey smear.
+ */
+function withAlpha(color: string, alpha: number): string {
+  if (color.startsWith('#')) {
+    const hex = color.slice(1);
+    const full =
+      hex.length === 3
+        ? hex
+            .split('')
+            .map((c) => c + c)
+            .join('')
+        : hex.slice(0, 6);
+    const r = parseInt(full.slice(0, 2), 16);
+    const g = parseInt(full.slice(2, 4), 16);
+    const b = parseInt(full.slice(4, 6), 16);
+    if (Number.isNaN(r + g + b)) return color;
+    return `rgba(${r}, ${g}, ${b}, ${alpha})`;
+  }
+
+  const channels = color.match(/rgba?\(([^)]+)\)/)?.[1];
+  if (channels) {
+    const [r, g, b] = channels.split(',').map((part) => part.trim());
+    return `rgba(${r}, ${g}, ${b}, ${alpha})`;
+  }
+
+  return color;
+}
+
+export interface CardWashProps extends Omit<ViewProps, 'children'> {
+  className?: string;
+  /**
+   * The colour the wash rises in. A theme token name such as
+   * `--color-primary`, or any colour string. Defaults to `--color-primary`.
+   */
+  tint?: string;
+  /**
+   * How opaque the wash gets at the bottom edge, 0–1. It is meant to be small:
+   * past about 0.25 the card reads as tinted rather than washed, which is a
+   * different thing and usually not the one you wanted.
+   */
+  intensity?: number;
+  /**
+   * Multiplier on how slowly the wash breathes. `0` holds it still, which is
+   * also what a reduced-motion setting does.
+   */
+  speed?: number;
+}
+
+/**
+ * A decorative layer for the back of a card: the tint rising from its bottom
+ * edge and fading out before it reaches the top.
+ *
+ * It fills its parent absolutely and takes no touches, so it goes first inside
+ * a `Card` and everything else is drawn over it. The card needs
+ * `overflow-hidden` — the layer reaches the root's edges, and the root is the
+ * thing with the corner radius.
+ *
+ * ```tsx
+ * <Card className="overflow-hidden">
+ *   <Card.Wash tint="--color-primary" />
+ *   <Card.Header>…</Card.Header>
+ * </Card>
+ * ```
+ *
+ * ## Why the rise is a curve and not a fade
+ *
+ * On a straight ramp the colour is already at half strength across the middle
+ * of the card, and what you see is a panel with a tint on it. On a curve there
+ * is nothing at all across the top two thirds and then the colour arrives —
+ * which is the difference between a card that has been coloured in and a card
+ * something is rising into.
+ */
+const CardWash = forwardRef<View, CardWashProps>(
+  (
+    {
+      className,
+      tint = '--color-primary',
+      intensity = 0.16,
+      speed = 1,
+      style,
+      ...props
+    },
+    ref
+  ) => {
+    const token = useCSSVariable(isToken(tint) ? tint : '--color-primary');
+    const resolved = typeof token === 'string' ? token : undefined;
+    const color = (isToken(tint) ? resolved : tint) ?? resolved ?? '#0a0a0a';
+
+    const reduced = useReducedMotion();
+    const still = reduced || speed <= 0;
+
+    const breath = useSharedValue(0);
+
+    useEffect(() => {
+      if (still) {
+        breath.value = 0;
+        return;
+      }
+      breath.value = 0;
+      breath.value = withRepeat(
+        withTiming(1, {
+          duration: WASH_PERIOD / speed,
+          easing: Easing.inOut(Easing.ease),
+        }),
+        -1,
+        true
+      );
+      return () => cancelAnimation(breath);
+    }, [breath, speed, still]);
+
+    /*
+     * The breath is the layer's opacity rather than its colours: rebuilding
+     * ten `rgba()` strings per frame would be a JavaScript-thread animation of
+     * the kind this library does not do, and a view's opacity is a property
+     * the compositor already knows how to move.
+     */
+    const breathing = useAnimatedStyle(() => ({
+      opacity: 1 - WASH_BREATH + breath.value * WASH_BREATH,
+    }));
+
+    const { colors, locations } = useMemo(() => {
+      const out: string[] = [];
+      const at: number[] = [];
+      for (let i = 0; i < WASH_STOPS; i += 1) {
+        const t = i / (WASH_STOPS - 1);
+        out.push(withAlpha(color, Math.pow(t, WASH_CURVE) * intensity));
+        at.push(t);
+      }
+      return {
+        colors: out as unknown as readonly [string, string, ...string[]],
+        locations: at as unknown as readonly [number, number, ...number[]],
+      };
+    }, [color, intensity]);
+
+    return (
+      <Animated.View
+        ref={ref}
+        // Decorative and non-interactive: it is the back of the card, and a
+        // screen reader announcing "image" over every card would be noise.
+        pointerEvents="none"
+        accessibilityElementsHidden
+        importantForAccessibility="no-hide-descendants"
+        className={cn('absolute inset-0 overflow-hidden', className)}
+        style={[still ? undefined : breathing, style]}
+        {...props}
+      >
+        {/*
+         * Every stop is the tint at a different alpha, never `transparent`:
+         * that is black at zero alpha on Android, and a wash faded to it
+         * arrives through a grey smear on the way.
+         */}
+        <LinearGradient
+          colors={colors}
+          locations={locations}
+          style={StyleSheet.absoluteFill}
+        />
+      </Animated.View>
+    );
+  }
+);
+CardWash.displayName = 'Card.Wash';
+
 export const Card = Object.assign(CardRoot, {
   Header: CardHeader,
   Title: CardTitle,
   Description: CardDescription,
   Content: CardContent,
   Footer: CardFooter,
+  Wash: CardWash,
 });

package/src/components/drawer/index.tsx

@@ -103,6 +103,7 @@ const DISMISS_VELOCITY = 650;
 
 export type DrawerSide = 'start' | 'end' | 'top' | 'bottom';
 export type DrawerSize = 'sm' | 'md' | 'lg' | 'full';
+export type DrawerCloseSide = 'start' | 'end';
 
 /**
  * How much of the screen each size asks for, and the cap it is never allowed
@@ -168,7 +169,7 @@ function useDrawer(component: string): DrawerContextValue {
  * so a header can leave it clear rather than wrap underneath it.
  */
 interface DrawerSurfaceValue {
-  side: DrawerSide;
+  closeSide: DrawerCloseSide;
   showClose: boolean;
 }
 
@@ -270,6 +271,17 @@ export interface DrawerContentProps extends ViewProps {
   swipeToDismiss?: boolean;
   /** Show a close button in the drawer's inner top corner. Default true. */
   showClose?: boolean;
+  /**
+   * Which top corner the close button takes. Logical, like `side`: `end` is the
+   * corner text runs toward, so it is the right one in a left-to-right app and
+   * the left one in a right-to-left one.
+   *
+   * Defaults to the corner *away* from the docked edge, so an `end` drawer's
+   * button does not sit against the screen edge the panel came out of. Set it
+   * when the drawer reads better with the button on the outer corner instead —
+   * a panel people close by reaching for the same corner every time.
+   */
+  closeSide?: DrawerCloseSide;
   /**
    * Frost the screen behind the drawer instead of dimming it. Needs the
    * optional `expo-blur`; without it this dims, rather than failing.
@@ -285,6 +297,7 @@ function DrawerContent({
   dismissible = true,
   swipeToDismiss = true,
   showClose = true,
+  closeSide,
   blur = false,
   children,
   ...props
@@ -384,9 +397,17 @@ function DrawerContent({
       : { transform: [{ translateY: travel.value * outward }] }
   );
 
+  /*
+   * Resolved once and shared, because the button's corner and the header's
+   * clearance are the same decision seen from two places. Letting each work it
+   * out from `side` is how they drift, and a header padded on the wrong side
+   * runs its title straight under the button.
+   */
+  const closeCorner: DrawerCloseSide = closeSide ?? (side === 'end' ? 'start' : 'end');
+
   const surface = useMemo<DrawerSurfaceValue>(
-    () => ({ side, showClose }),
-    [side, showClose]
+    () => ({ closeSide: closeCorner, showClose }),
+    [closeCorner, showClose]
   );
 
   if (!open) return null;
@@ -508,10 +529,11 @@ function DrawerContent({
                    * Taking the same number the padding does is what keeps it
                    * level with the first line of the header on every side.
                    *
-                   * The corner follows the docked edge. An `end` drawer's own
-                   * edge is the trailing one, so its button moves to the
-                   * leading side rather than sitting against the screen edge
-                   * the drawer came out of.
+                   * The corner follows the docked edge by default. An `end`
+                   * drawer's own edge is the trailing one, so its button moves
+                   * to the leading side rather than sitting against the screen
+                   * edge the drawer came out of — and `closeSide` overrides
+                   * that for a panel that wants the same corner every time.
                    */}
                   {showClose ? (
                     <Pressable
@@ -521,7 +543,7 @@ function DrawerContent({
                       hitSlop={8}
                       className={cn(
                         'absolute z-10 h-8 w-8 items-center justify-center rounded-full bg-muted active:opacity-70',
-                        side === 'end' ? 'start-4' : 'end-4'
+                        closeCorner === 'start' ? 'start-4' : 'end-4'
                       )}
                       style={{ top: padding.paddingTop }}
                     >
@@ -569,7 +591,7 @@ function DrawerHeader({
    */
   const clearance = !surface?.showClose
     ? undefined
-    : surface.side === 'end'
+    : surface.closeSide === 'start'
       ? 'ps-14'
       : 'pe-14';
 

package/src/components/map/index.tsx

@@ -128,6 +128,43 @@ function useToken(name: string, fallback: string): string {
   return typeof value === 'string' && value.length > 0 ? value : fallback;
 }
 
+/** True for a theme token name, as opposed to a literal colour. */
+function isToken(value: string | undefined): value is string {
+  return typeof value === 'string' && value.startsWith('--');
+}
+
+/**
+ * The same colour at a given alpha, for a ramp built from one hue.
+ *
+ * Style expressions are handed to the renderer as strings, so this produces
+ * `rgba()` rather than reaching for a colour type the layer would not accept.
+ */
+function withAlpha(color: string, alpha: number): string {
+  if (color.startsWith('#')) {
+    const hex = color.slice(1);
+    const full =
+      hex.length === 3
+        ? hex
+            .split('')
+            .map((c) => c + c)
+            .join('')
+        : hex.slice(0, 6);
+    const r = parseInt(full.slice(0, 2), 16);
+    const g = parseInt(full.slice(2, 4), 16);
+    const b = parseInt(full.slice(4, 6), 16);
+    if (Number.isNaN(r + g + b)) return color;
+    return `rgba(${r}, ${g}, ${b}, ${alpha})`;
+  }
+
+  const channels = color.match(/rgba?\(([^)]+)\)/)?.[1];
+  if (channels) {
+    const [r, g, b] = channels.split(',').map((part) => part.trim());
+    return `rgba(${r}, ${g}, ${b}, ${alpha})`;
+  }
+
+  return color;
+}
+
 interface MapContextValue {
   mapRef: React.RefObject<MapRef | null>;
   cameraRef: React.RefObject<CameraRef | null>;
@@ -1025,6 +1062,28 @@ export interface MapHeatmapProps {
   data: unknown;
   /** Feature property to weight each point by. Unweighted when omitted. */
   weight?: string;
+  /**
+   * Base colour of the field — a theme token by name, or a literal. The ramp
+   * is this colour at rising opacity, so density reads as *more of the same
+   * thing* rather than as a change of subject.
+   *
+   * Defaults to `--color-chart-2`, which is a saturated accent in every theme.
+   * It is deliberately not `--color-chart-1`: that is the series colour a chart
+   * is about, and every theme starts it on something close to the foreground —
+   * near-black in a light theme, near-white in a dark one — which over a
+   * basemap is a smudge rather than a measurement.
+   */
+  color?: string;
+  /**
+   * Replace the derived ramp outright, coolest first. For the conventional
+   * heat ramp, where the hue carries the reading as well as the opacity —
+   * worth it when the field sits over varied terrain and one hue at five
+   * opacities stops being separable from what is underneath it.
+   *
+   * The first stop is drawn at the lowest density, the last at the highest.
+   * Density zero stays fully transparent either way.
+   */
+  colors?: string[];
   /**
    * Spread of a single point, in points, at street zoom. Larger blurs more.
    * The drawn radius shrinks as the map zooms out, so a point keeps covering
@@ -1037,6 +1096,12 @@ export interface MapHeatmapProps {
   opacity?: number;
   /** Above this zoom the layer fades out — see the note on the component. */
   maxZoom?: number;
+  /**
+   * Draw the points themselves as the field fades out, coloured from the same
+   * ramp by weight. Without them, zooming past `maxZoom` leaves an empty map:
+   * the layer gets out of the way, and nothing takes its place.
+   */
+  points?: boolean;
   id?: string;
 }
 
@@ -1050,30 +1115,63 @@ export interface MapHeatmapProps {
  *
  * It fades out past `maxZoom` on purpose. Zoomed far enough in, every point is
  * its own island and the blur says less than the points would — so the layer
- * gets out of the way rather than smearing five records across a street.
+ * gets out of the way rather than smearing five records across a street. Set
+ * `points` and the records themselves fade in as it goes, which is the whole
+ * handover: a field while the question is where, marks once it is which.
  *
  * The radius is tied to zoom for the mirror-image reason. Left as a fixed
  * number of screen points it would mean a different distance at every zoom:
  * a blur that reads as a city at street level covers half a continent once
  * the map is pulled out, and a field measured over land ends up sitting in
  * the sea. Scaling it with the projection keeps the claim the same one.
+ *
+ * Intensity is tied to zoom too, and in the other direction. The same points
+ * are packed into fewer pixels the further out the map goes, so a constant
+ * intensity saturates the whole field at world zoom and shows nothing but its
+ * own ceiling.
  */
 function MapHeatmap({
   data,
   weight,
+  color,
+  colors,
   radius = 24,
   intensity = 1,
   opacity = 0.85,
   maxZoom = 15,
+  points = false,
   id = 'heatmap',
 }: MapHeatmapProps) {
-  const cool = useToken('--color-muted', 'rgba(0,0,0,0.06)');
-  const warm = useToken('--color-chart-1', '#262626');
-  const hot = useToken('--color-chart-2', '#666666');
+  const base = useToken(isToken(color) ? color : '--color-chart-2', '#3b82f6');
+  const resolved = (isToken(color) ? base : color) ?? base;
+
+  /*
+   * One colour at rising opacity rather than five colours, which is how every
+   * other ramp in the library is built: a sequential scale is one quantity
+   * getting larger, and five hues say five categories. `colors` is there for
+   * the case where that is not enough.
+   */
+  const ramp = colors?.length
+    ? colors
+    : [
+        withAlpha(resolved, 0.25),
+        withAlpha(resolved, 0.45),
+        withAlpha(resolved, 0.7),
+        withAlpha(resolved, 0.9),
+        resolved,
+      ];
 
   if (!MapLibre) return null;
   const { GeoJSONSource, Layer } = MapLibre;
 
+  // Density zero is transparent rather than the coolest colour, so the map
+  // shows through everywhere nothing was measured instead of the whole
+  // viewport being tinted by the absence of data.
+  const stops = ramp.flatMap((entry, index) => [
+    0.15 + (0.85 * index) / Math.max(1, ramp.length - 1),
+    entry,
+  ]);
+
   return (
     <GeoJSONSource id={`${id}-source`} data={data}>
       <Layer
@@ -1084,7 +1182,15 @@ function MapHeatmap({
           heatmapWeight: weight
             ? ['interpolate', ['linear'], ['get', weight], 0, 0, 1, 1]
             : 1,
-          heatmapIntensity: intensity,
+          heatmapIntensity: [
+            'interpolate',
+            ['linear'],
+            ['zoom'],
+            0,
+            intensity * 0.6,
+            maxZoom,
+            intensity * 1.2,
+          ],
           // `radius` is the spread at street zoom; below that it is scaled
           // down so it keeps covering the same ground rather than the same
           // number of pixels. The stops are the projection: each zoom level
@@ -1101,21 +1207,13 @@ function MapHeatmap({
             14,
             radius,
           ],
-          // Transparent at zero rather than the coolest colour, so the map
-          // shows through everywhere nothing was measured instead of the whole
-          // viewport being tinted by the absence of data.
           heatmapColor: [
             'interpolate',
             ['linear'],
             ['heatmap-density'],
             0,
             'rgba(0,0,0,0)',
-            0.2,
-            cool,
-            0.6,
-            warm,
-            1,
-            hot,
+            ...stops,
           ],
           heatmapOpacity: [
             'interpolate',
@@ -1128,6 +1226,52 @@ function MapHeatmap({
           ],
         }}
       />
+
+      {/* The handover, in the two zoom levels the field spends fading: the
+          marks arrive as it leaves, so there is never a zoom with neither. */}
+      {points ? (
+        <Layer
+          id={`${id}-points`}
+          type="circle"
+          minzoom={maxZoom - 2}
+          style={{
+            circleRadius: weight
+              ? ['interpolate', ['linear'], ['get', weight], 0, 3, 1, 9]
+              : 5,
+            circleColor: weight
+              ? [
+                  'interpolate',
+                  ['linear'],
+                  ['get', weight],
+                  0,
+                  ramp[0] as string,
+                  1,
+                  ramp[ramp.length - 1] as string,
+                ]
+              : (ramp[ramp.length - 1] as string),
+            circleStrokeWidth: 1,
+            circleStrokeColor: 'rgba(255,255,255,0.75)',
+            circleOpacity: [
+              'interpolate',
+              ['linear'],
+              ['zoom'],
+              maxZoom - 2,
+              0,
+              maxZoom,
+              0.85,
+            ],
+            circleStrokeOpacity: [
+              'interpolate',
+              ['linear'],
+              ['zoom'],
+              maxZoom - 2,
+              0,
+              maxZoom,
+              0.6,
+            ],
+          }}
+        />
+      ) : null}
     </GeoJSONSource>
   );
 }

package/src/components/pagination/index.tsx

@@ -65,9 +65,10 @@ export type PaginationSize = 'sm' | 'default';
 /**
  * What the small size gives back as padding. 44pt is the smallest target a
  * finger reliably hits, and the row is allowed to get tighter than that only
- * because the reach is restored outside the paint.
+ * because the reach is restored outside the paint — so this is exactly the
+ * difference between the small target's 32pt and that 44.
  */
-const SMALL_HIT_SLOP = { top: 4, bottom: 4, left: 4, right: 4 } as const;
+const SMALL_HIT_SLOP = { top: 6, bottom: 6, left: 6, right: 6 } as const;
 
 const paginationVariants = tv({
   slots: {
@@ -91,9 +92,9 @@ const paginationVariants = tv({
       },
       sm: {
         list: 'gap-0.5',
-        item: 'h-9 min-w-9 px-1',
+        item: 'h-8 min-w-8 px-1',
         itemLabel: 'text-xs',
-        ellipsis: 'h-9 w-9',
+        ellipsis: 'h-8 w-8',
         status: 'text-xs',
         summary: 'text-xs',
       },
@@ -304,7 +305,18 @@ const PaginationRoot = forwardRef<View, PaginationProps>(
             // With nothing on the leading edge the controls are the whole row
             // and centre in it; with something there they part to the two ends,
             // which is the shape a table footer wants.
-            className: cn(children ? 'justify-between gap-3' : 'justify-center', className),
+            //
+            // Clipped, because the run is a fixed number of targets and a
+            // narrow enough container cannot hold it. Overflowing, a centred
+            // row hangs the same distance past both edges, and the leading
+            // number ends up half off the screen with nothing to say why.
+            // Inside its own bounds the shortfall at least looks deliberate,
+            // and `siblings`/`boundaries` are the knobs that fix it.
+            className: cn(
+              'overflow-hidden',
+              children ? 'justify-between gap-3' : 'justify-center',
+              className
+            ),
           })}
           {...props}
         >
@@ -312,7 +324,7 @@ const PaginationRoot = forwardRef<View, PaginationProps>(
             <PaginationStatus>{text}</PaginationStatus>
           ))}
 
-          <View className={list()}>
+          <View className={list({ className: 'max-w-full' })}>
             {controls ? <PaginationPrevious label={variant === 'simple'} /> : null}
 
             {variant === 'numbers'