panelui-native 0.19.0 → 0.21.0

package/src/components/rating/index.tsx

@@ -0,0 +1,416 @@
+/**
+ * Rating — a row of stars you can read or set.
+ *
+ * A rating is two jobs wearing one shape. Read-only, it is a compact way to
+ * *show* a score — four-and-a-half stars next to a product. Interactive, it is
+ * an *input*: tap a star to pick a whole value, or with `precision={0.5}` press
+ * the left half of a star for a half. Either way the fill is the truth, so the
+ * two modes look identical and only differ in whether a finger changes them.
+ *
+ * Partial fills are drawn by clipping a filled star over an empty one of the
+ * same geometry — the filled layer's width is a fraction of the star's, so a
+ * half star is exactly half and any precision in between is honest. That fill
+ * is animated on the UI thread: setting a value springs the stars to it rather
+ * than snapping, and a drag follows the finger with no spring so it never lags.
+ *
+ * ```tsx
+ * <Rating defaultValue={3} onValueChange={setScore} />
+ *
+ * <Rating value={4.5} precision={0.5} readOnly />
+ *
+ * <Rating label="Rate your stay" showValue color="warning" defaultValue={0} />
+ * ```
+ *
+ * Works controlled (`value` + `onValueChange`) or uncontrolled (`defaultValue`).
+ */
+import { forwardRef, useCallback, useEffect, useRef, useState } from 'react';
+import {
+  View,
+  type AccessibilityActionEvent,
+  type LayoutChangeEvent,
+} from 'react-native';
+import { Gesture, GestureDetector } from 'react-native-gesture-handler';
+import Animated, {
+  runOnJS,
+  useAnimatedStyle,
+  useSharedValue,
+  withSpring,
+  type SharedValue,
+} from 'react-native-reanimated';
+import { tv, type VariantProps } from 'tailwind-variants';
+import { useCSSVariable } from 'uniwind';
+import { StarIcon } from '../../icons';
+import { Text } from '../../primitives/text';
+import { cn } from '../../utils/cn';
+import { selectionTick } from '../../utils/haptics';
+
+/** Springs the fill onto its resting value after a tap or the end of a drag. */
+const SPRING = { damping: 18, stiffness: 220, mass: 0.6 } as const;
+
+const ratingVariants = tv({
+  slots: {
+    root: 'gap-2',
+    header: 'flex-row items-center justify-between gap-3',
+    label: 'text-sm font-medium text-foreground',
+    value: 'text-sm text-muted-foreground',
+    row: 'flex-row items-center self-start',
+  },
+  variants: {
+    size: {
+      sm: { row: 'gap-0.5' },
+      md: { row: 'gap-1' },
+      lg: { row: 'gap-1.5' },
+    },
+    disabled: {
+      true: { root: 'opacity-50' },
+    },
+  },
+  defaultVariants: {
+    size: 'md',
+  },
+});
+
+type RatingVariantProps = VariantProps<typeof ratingVariants>;
+export type RatingSize = NonNullable<RatingVariantProps['size']>;
+export type RatingColor =
+  | 'warning'
+  | 'primary'
+  | 'success'
+  | 'destructive'
+  | 'info'
+  | 'foreground';
+
+/** Star pixel size per size token — the whole control scales from this. */
+const STAR_SIZE: Record<RatingSize, number> = { sm: 18, md: 24, lg: 32 };
+
+/** The CSS token each colour paints its filled stars with. */
+const FILL_VAR: Record<RatingColor, string> = {
+  warning: '--color-warning',
+  primary: '--color-primary',
+  success: '--color-success',
+  destructive: '--color-destructive',
+  info: '--color-info',
+  foreground: '--color-foreground',
+};
+
+function clampJS(value: number, min: number, max: number) {
+  return Math.min(Math.max(value, min), max);
+}
+
+/** Rounds `value` up to the nearest `precision`, so any touch fills at least it. */
+function snap(value: number, precision: number, max: number) {
+  const stepped = Math.ceil(value / precision) * precision;
+  // Guard the float drift that `ceil` on fractional steps can leave behind.
+  return clampJS(Math.round(stepped / precision) * precision, 0, max);
+}
+
+export interface RatingProps extends Omit<RatingVariantProps, 'disabled'> {
+  className?: string;
+  /** Controlled value. Leave unset and pass `defaultValue` to run uncontrolled. */
+  value?: number;
+  /** Starting value when uncontrolled. */
+  defaultValue?: number;
+  /** How many stars. */
+  max?: number;
+  /**
+   * Smallest step a tap can pick, as a fraction of a star. `1` is whole stars,
+   * `0.5` lets the left half of a star mean a half. Reading a value renders any
+   * precision — this only constrains what a finger can set.
+   */
+  precision?: number;
+  /** Fires as the value changes, including live while dragging. */
+  onValueChange?: (value: number) => void;
+  /** Fires once when a tap or drag ends — the place for expensive side effects. */
+  onValueCommit?: (value: number) => void;
+  /** Show the stars but ignore touches — the display half of the component. */
+  readOnly?: boolean;
+  disabled?: boolean;
+  /**
+   * Let a second tap on the current value clear it back to zero, so a rating
+   * given by mistake can be taken back without a separate control.
+   */
+  allowClear?: boolean;
+  /** Which token the filled stars are painted with. */
+  color?: RatingColor;
+  /** Caption above the stars. Also becomes the accessibility label. */
+  label?: string;
+  /** Show the numeric value on the caption row, opposite the label. */
+  showValue?: boolean;
+  /** Format the shown value. Defaults to the number as written. */
+  formatValue?: (value: number) => string;
+  /**
+   * A tick under the finger each time a drag crosses onto a new star. Off by
+   * default — needs the optional `expo-haptics`, and is silent without it.
+   */
+  haptics?: boolean;
+  /** Extra classes for the caption row. */
+  headerClassName?: string;
+  /** Extra classes for the row of stars. */
+  rowClassName?: string;
+}
+
+/**
+ * One star: an empty outline with a filled copy clipped over it. The clip width
+ * is driven by the shared `display` value on the UI thread, so the fill of this
+ * star animates and drags without a React render.
+ */
+function Star({
+  index,
+  display,
+  size,
+  gap,
+  fillColor,
+  emptyColor,
+}: {
+  index: number;
+  display: SharedValue<number>;
+  size: number;
+  gap: number;
+  fillColor: string;
+  emptyColor: string;
+}) {
+  // Clamped inline rather than through a helper: this body runs on the UI
+  // thread, which can only reach worklets, not module-scope functions.
+  const clipStyle = useAnimatedStyle(() => ({
+    width: Math.min(Math.max(display.value - index, 0), 1) * size,
+  }));
+
+  return (
+    <View style={{ width: size, height: size, marginRight: gap }}>
+      <StarIcon size={size} color={emptyColor} />
+      {/* The filled layer is pinned to the left and clipped to a fraction of
+          the star's width, so a partial value shows a partial star. */}
+      <Animated.View
+        style={[{ position: 'absolute', left: 0, top: 0, overflow: 'hidden' }, clipStyle]}
+      >
+        <StarIcon size={size} color={fillColor} filled />
+      </Animated.View>
+    </View>
+  );
+}
+
+export const Rating = forwardRef<View, RatingProps>(
+  (
+    {
+      className,
+      headerClassName,
+      rowClassName,
+      value: valueProp,
+      defaultValue = 0,
+      max = 5,
+      precision = 1,
+      onValueChange,
+      onValueCommit,
+      readOnly = false,
+      disabled = false,
+      allowClear = false,
+      color = 'warning',
+      size = 'md',
+      label,
+      showValue = false,
+      formatValue,
+      haptics = false,
+    },
+    ref
+  ) => {
+    const isControlled = valueProp !== undefined;
+    const [internal, setInternal] = useState(defaultValue);
+    const value = clampJS(isControlled ? valueProp! : internal, 0, max);
+
+    const interactive = !readOnly && !disabled;
+    const slots = ratingVariants({ size, disabled });
+    const starSize = STAR_SIZE[size ?? 'md'];
+    const gap = size === 'sm' ? 2 : size === 'lg' ? 6 : 4;
+
+    // SVG paints with real colour strings, not classes — resolve the tokens.
+    const fillColor = useCSSVariable(FILL_VAR[color]);
+    const emptyColor = useCSSVariable('--color-border');
+    const fill = typeof fillColor === 'string' ? fillColor : '#f59e0b';
+    const empty = typeof emptyColor === 'string' ? emptyColor : '#d4d4d4';
+
+    // Drives every star's clipped fill on the UI thread.
+    const display = useSharedValue(value);
+    const rowWidth = useSharedValue(0);
+
+    // Keep the change/commit handlers reachable from the gesture without
+    // rebuilding it on every render.
+    const changeRef = useRef(onValueChange);
+    changeRef.current = onValueChange;
+    const commitRef = useRef(onValueCommit);
+    commitRef.current = onValueCommit;
+    // The last whole star a drag crossed, so haptics tick once per star.
+    const lastStep = useRef(Math.ceil(value));
+
+    const emitChange = useCallback(
+      (next: number) => {
+        if (!isControlled) setInternal(next);
+        changeRef.current?.(next);
+      },
+      [isControlled]
+    );
+
+    // Follow a controlled value that changes elsewhere, springing to it.
+    useEffect(() => {
+      display.value = withSpring(value, SPRING);
+    }, [value, display]);
+
+    const onRowLayout = (event: LayoutChangeEvent) => {
+      rowWidth.value = event.nativeEvent.layout.width;
+    };
+
+    // Maps an x within the row to a snapped rating. Runs on JS off the worklet.
+    const valueFromX = useCallback(
+      (x: number, width: number) => {
+        if (width <= 0) return value;
+        const raw = clampJS(x / width, 0, 1) * max;
+        return snap(raw, precision, max);
+      },
+      [max, precision, value]
+    );
+
+    const applyLive = useCallback(
+      (x: number, width: number) => {
+        let next = valueFromX(x, width);
+        if (allowClear && next === value && Math.ceil(next) === lastStep.current) {
+          next = 0;
+        }
+        display.value = next;
+        if (haptics && Math.ceil(next) !== lastStep.current) {
+          lastStep.current = Math.ceil(next);
+          selectionTick();
+        }
+        emitChange(next);
+      },
+      [valueFromX, allowClear, value, display, haptics, emitChange]
+    );
+
+    // Resets the haptic step to where the touch started, then applies the first
+    // position. Runs on JS: a ref cannot be written from a gesture worklet.
+    const begin = useCallback(
+      (x: number, width: number) => {
+        lastStep.current = Math.ceil(value);
+        applyLive(x, width);
+      },
+      [value, applyLive]
+    );
+
+    const commit = useCallback(
+      (x: number, width: number) => {
+        let next = valueFromX(x, width);
+        if (allowClear && next === value) next = 0;
+        display.value = withSpring(next, SPRING);
+        lastStep.current = Math.ceil(next);
+        emitChange(next);
+        commitRef.current?.(next);
+      },
+      [valueFromX, allowClear, value, display, emitChange]
+    );
+
+    const pan = Gesture.Pan()
+      .enabled(interactive)
+      .onBegin((event) => {
+        runOnJS(begin)(event.x, rowWidth.value);
+      })
+      .onUpdate((event) => {
+        runOnJS(applyLive)(event.x, rowWidth.value);
+      })
+      .onFinalize((event) => {
+        runOnJS(commit)(event.x, rowWidth.value);
+      });
+
+    const tap = Gesture.Tap()
+      .enabled(interactive)
+      .maxDuration(250)
+      .onEnd((event) => {
+        runOnJS(commit)(event.x, rowWidth.value);
+      });
+
+    const gesture = Gesture.Race(tap, pan);
+
+    // VoiceOver / TalkBack move by a single precision step.
+    const nudge = (dir: 1 | -1) => {
+      const next = clampJS(
+        Math.round((value + dir * precision) / precision) * precision,
+        0,
+        max
+      );
+      if (next === value) return;
+      display.value = withSpring(next, SPRING);
+      lastStep.current = Math.ceil(next);
+      emitChange(next);
+      commitRef.current?.(next);
+    };
+
+    const onAccessibilityAction = (event: AccessibilityActionEvent) => {
+      if (event.nativeEvent.actionName === 'increment') nudge(1);
+      else if (event.nativeEvent.actionName === 'decrement') nudge(-1);
+    };
+
+    const shown = formatValue ? formatValue(value) : String(value);
+    const a11yLabel = label ?? `Rating, ${shown} out of ${max}`;
+
+    const stars = (
+      <View
+        className={slots.row({ className: rowClassName })}
+        onLayout={onRowLayout}
+        // The row is measured for the touch math, so it must not collapse.
+        collapsable={false}
+      >
+        {Array.from({ length: max }, (_, i) => (
+          <Star
+            key={i}
+            index={i}
+            display={display}
+            size={starSize}
+            // No trailing gap after the last star, so the row width is honest.
+            gap={i === max - 1 ? 0 : gap}
+            fillColor={fill}
+            emptyColor={empty}
+          />
+        ))}
+      </View>
+    );
+
+    const header =
+      label || showValue ? (
+        <View className={slots.header({ className: headerClassName })}>
+          {label ? <Text className={slots.label()}>{label}</Text> : <View />}
+          {showValue ? <Text className={slots.value()}>{shown}</Text> : null}
+        </View>
+      ) : null;
+
+    return (
+      <View ref={ref} className={cn(slots.root({ className }))}>
+        {header}
+        {interactive ? (
+          <GestureDetector gesture={gesture}>
+            <View
+              accessible
+              accessibilityRole="adjustable"
+              accessibilityLabel={a11yLabel}
+              accessibilityState={{ disabled }}
+              accessibilityValue={{ min: 0, max, now: value, text: shown }}
+              accessibilityActions={[{ name: 'increment' }, { name: 'decrement' }]}
+              onAccessibilityAction={onAccessibilityAction}
+              // Hold the stars in a self-starting box so the gesture area is
+              // exactly the stars, not the full width of the parent.
+              className="self-start"
+            >
+              {stars}
+            </View>
+          </GestureDetector>
+        ) : (
+          <View
+            accessible
+            accessibilityRole="image"
+            accessibilityLabel={a11yLabel}
+          >
+            {stars}
+          </View>
+        )}
+      </View>
+    );
+  }
+);
+
+Rating.displayName = 'Rating';

package/src/components/signature/index.tsx

@@ -68,7 +68,13 @@ import Animated, {
 } from 'react-native-reanimated';
 import Svg, { Path } from 'react-native-svg';
 import { tv, type VariantProps } from 'tailwind-variants';
-import { PencilIcon, RotateCcwIcon, TrashIcon, type IconProps } from '../../icons';
+import {
+  PencilIcon,
+  RotateCcwIcon,
+  RotateCwIcon,
+  TrashIcon,
+  type IconProps,
+} from '../../icons';
 import {
   AnimatedPressable,
   type AnimatedPressableProps,
@@ -631,8 +637,8 @@ export interface SignatureButtonProps
 }
 
 /**
- * The two pad controls are the same round button with a different icon and a
- * different spoken name, so they are built rather than written twice.
+ * The pad controls are all the same round button with a different icon and a
+ * different spoken name, so they are built rather than written out each time.
  */
 function circleButton(
   Icon: ComponentType<IconProps>,
@@ -671,11 +677,15 @@ function circleButton(
 /** Removes the last stroke. Wire it to `ref.current?.undo()`. */
 const SignatureUndo = circleButton(RotateCcwIcon, 'Undo last stroke', 'Signature.Undo');
 
+/** Puts back the last undone stroke. Wire it to `ref.current?.redo()`. */
+const SignatureRedo = circleButton(RotateCwIcon, 'Redo last stroke', 'Signature.Redo');
+
 /** Drops every stroke. Wire it to `ref.current?.clear()`. */
 const SignatureClear = circleButton(TrashIcon, 'Clear signature', 'Signature.Clear');
 
 export const Signature = Object.assign(SignatureForwarded, {
   Toolbar: SignatureToolbar,
   Undo: SignatureUndo,
+  Redo: SignatureRedo,
   Clear: SignatureClear,
 });

package/src/components/slider/index.tsx

@@ -36,6 +36,7 @@ import Animated, {
 import { tv, type VariantProps } from 'tailwind-variants';
 import { getNativeUI } from '../../native';
 import { Text } from '../../primitives/text';
+import { selectionTick } from '../../utils/haptics';
 
 /**
  * Springs the thumb onto its resting step after a drag or a track tap. Drags
@@ -127,6 +128,12 @@ export interface SliderProps extends Omit<SliderVariantProps, 'disabled'> {
   showValue?: boolean;
   /** Format the shown value. Defaults to the rounded number. */
   formatValue?: (value: number) => string;
+  /**
+   * A tick under the finger each time a drag crosses onto a new step, and once
+   * more when the drag ends. Off by default — needs the optional `expo-haptics`,
+   * and is silent without it.
+   */
+  haptics?: boolean;
   /** Extra classes for the caption row. */
   headerClassName?: string;
   /** Extra classes for the unfilled track. */
@@ -170,6 +177,7 @@ export const Slider = forwardRef<View, SliderProps>(
       label,
       showValue = false,
       formatValue,
+      haptics = false,
       color = 'primary',
       size = 'md',
     },
@@ -197,6 +205,9 @@ export const Slider = forwardRef<View, SliderProps>(
     changeRef.current = onValueChange;
     const commitRef = useRef(onValueCommit);
     commitRef.current = onValueCommit;
+    // The last step a drag ticked on, so haptics fire once per step, not per
+    // pixel of movement within it.
+    const lastTick = useRef(value);
 
     const emitChange = useCallback(
       (next: number) => {
@@ -223,10 +234,14 @@ export const Slider = forwardRef<View, SliderProps>(
       (p: number, commit: boolean) => {
         const raw = min + p * (max - min);
         const snapped = snap(raw, min, max, step);
+        if (haptics && snapped !== lastTick.current) {
+          lastTick.current = snapped;
+          selectionTick();
+        }
         emitChange(snapped);
         if (commit) emitCommit(snapped);
       },
-      [min, max, step, emitChange, emitCommit]
+      [min, max, step, haptics, emitChange, emitCommit]
     );
 
     const pan = Gesture.Pan()
@@ -280,6 +295,10 @@ export const Slider = forwardRef<View, SliderProps>(
     const nudge = (dir: 1 | -1) => {
       const next = snap(value + dir * (step || 1), min, max, step);
       if (next === value) return;
+      if (haptics) {
+        lastTick.current = next;
+        selectionTick();
+      }
       progress.value = withSpring(max > min ? (next - min) / (max - min) : 0, SPRING);
       emitChange(next);
       emitCommit(next);

package/src/icons/index.tsx

@@ -562,6 +562,32 @@ export function PauseIcon({ size = 16, color, ...props }: IconProps) {
   );
 }
 
+/**
+ * A five-pointed star — the mark of a Rating. `filled` paints the interior;
+ * left hollow it is the outline of an unearned star. Both share the same
+ * geometry, so a filled star clipped over an empty one lines up to the pixel.
+ */
+export function StarIcon({
+  size = 20,
+  color,
+  filled = false,
+  ...props
+}: IconProps & { filled?: boolean }) {
+  const resolved = useResolvedColor(color, '#737373');
+  return (
+    <Svg width={size} height={size} viewBox="0 0 24 24" fill="none" {...props}>
+      <Path
+        d="M12 2.5l2.9 5.88 6.49.94-4.7 4.58 1.11 6.46L12 17.82 6.2 20.86l1.11-6.46-4.7-4.58 6.49-.94z"
+        fill={filled ? resolved : 'none'}
+        stroke={resolved}
+        strokeWidth={1.6}
+        strokeLinejoin="round"
+        strokeLinecap="round"
+      />
+    </Svg>
+  );
+}
+
 /** A pencil at an angle — draw, sign, edit by hand. */
 export function PencilIcon({ size = 16, color, ...props }: IconProps) {
   const resolved = useResolvedColor(color, '#737373');
@@ -601,6 +627,29 @@ export function RotateCcwIcon({ size = 16, color, ...props }: IconProps) {
   );
 }
 
+/** An arrow curling clockwise — redo, put back what was undone. */
+export function RotateCwIcon({ size = 16, color, ...props }: IconProps) {
+  const resolved = useResolvedColor(color, '#737373');
+  return (
+    <Svg width={size} height={size} viewBox="0 0 24 24" fill="none" {...props}>
+      <Path
+        d="M21 12a9 9 0 1 1-2.64-6.36L21 8"
+        stroke={resolved}
+        strokeWidth={2}
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      />
+      <Path
+        d="M21 3v5h-5"
+        stroke={resolved}
+        strokeWidth={2}
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      />
+    </Svg>
+  );
+}
+
 /** A bin — discard what is there. */
 export function TrashIcon({ size = 16, color, ...props }: IconProps) {
   const resolved = useResolvedColor(color, '#737373');

package/src/index.ts

@@ -16,6 +16,10 @@ export {
 
 // Primitives
 export { Portal, PortalHost, PortalProvider } from './primitives/portal';
+// The companion to Portal: the layer that makes the screen behind an overlay
+// recede. Public so a custom overlay gets the same backdrop — and the same
+// graceful fall back from blur to dim — as the built-in ones.
+export { Scrim, hasBlur, type ScrimProps } from './primitives/scrim';
 export { Text, type TextProps } from './primitives/text';
 export {
   KeyboardAvoider,
@@ -302,6 +306,12 @@ export {
   type RadioGroupProps,
   type RadioGroupItemProps,
 } from './components/radio-group';
+export {
+  Rating,
+  type RatingProps,
+  type RatingColor,
+  type RatingSize,
+} from './components/rating';
 export {
   ScrollFade,
   type ScrollFadeProps,