panelui-native 0.54.0 → 0.56.0

package/lib/module/components/tour/index.js

@@ -0,0 +1,661 @@
+"use strict";
+
+/**
+ * Tour — the walkthrough that introduces a screen one control at a time.
+ *
+ * An empty state explains a screen before there is anything on it; a tour
+ * explains it once there is. It dims everything, cuts a hole around one control
+ * and puts a card beside it, then moves the hole to the next control. What
+ * makes that work is the hole: a caption alone has to describe where to look,
+ * and "the button at the top right" is a sentence people read twice and still
+ * get wrong.
+ *
+ * ```tsx
+ * <Tour open={onboarding} onOpenChange={setOnboarding}>
+ *   <Tour.Step order={0} title="Your library" description="Everything you save lands here.">
+ *     <IconButton icon={<BookmarkIcon />} onPress={openLibrary} />
+ *   </Tour.Step>
+ *
+ *   <Tour.Step order={1} title="Start writing" description="A new note, from anywhere." shape="circle">
+ *     <Fab icon={<PlusIcon />} onPress={compose} />
+ *   </Tour.Step>
+ * </Tour>
+ * ```
+ *
+ * A step wraps the control it is about, so the two live together in the tree
+ * and cannot drift apart — a step whose target has been deleted goes with it
+ * rather than pointing at empty space. `order` is what puts the steps in a
+ * sequence, and it is the author's numbering rather than the tree's, because a
+ * walkthrough usually crosses a header, a list and a tab bar in an order the
+ * layout knows nothing about.
+ *
+ * The target is measured in window coordinates each time its step becomes
+ * current, and again when the window changes size — a rect measured in portrait
+ * describes nothing after a rotation, and a spotlight in the wrong place is
+ * worse than none. A target that has scrolled out of view is the one case this
+ * cannot fix by itself: bring it back with `onStepChange`, which fires with the
+ * step about to be shown.
+ *
+ * The hole is one path with an even-odd fill — the screen rectangle and the
+ * cutout in a single `d`, animated on the UI thread — rather than four views
+ * arranged around a gap. Four views cannot have rounded corners between them,
+ * and the corner is most of what makes the hole read as *this control* instead
+ * of as a rectangle that happens to contain it.
+ */
+import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState } from 'react';
+import { StyleSheet, useWindowDimensions, View } from 'react-native';
+import Animated, { FadeIn, FadeOut, useAnimatedProps, useReducedMotion, useSharedValue, withSpring } from 'react-native-reanimated';
+import { useSafeAreaInsets } from 'react-native-safe-area-context';
+import Svg, { Path } from 'react-native-svg';
+import { ChevronLeftIcon, XIcon } from "../../icons/index.js";
+import { useBackHandler } from "../../hooks/use-back-handler.js";
+import { Portal } from "../../primitives/portal.js";
+import { Text } from "../../primitives/text.js";
+import { cn } from "../../utils/cn.js";
+import { Button } from "../button/index.js";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+const AnimatedPath = Animated.createAnimatedComponent(Path);
+
+/** Room left between the cutout and the target inside it. */
+const DEFAULT_PADDING = 8;
+/** Corner radius of a rectangular cutout. */
+const DEFAULT_RADIUS = 12;
+/** Gap between the cutout and the card. */
+const CARD_OFFSET = 12;
+/** Smallest gap allowed between the card and the edge of the safe area. */
+const SCREEN_MARGIN = 16;
+/** Ceiling on the card's width, so it does not run edge to edge on a tablet. */
+const MAX_CARD_WIDTH = 420;
+/** How the spotlight travels from one target to the next. */
+const SPRING = {
+  damping: 20,
+  stiffness: 180,
+  mass: 0.6
+};
+/** The dim laid over everything outside the cutout. */
+const DEFAULT_OVERLAY = 'rgba(0, 0, 0, 0.66)';
+
+/** The words on the card's controls, for a tour that is not in English. */
+
+const DEFAULT_LABELS = {
+  next: 'Next',
+  back: 'Back',
+  done: 'Done',
+  skip: 'Skip',
+  close: 'End tour'
+};
+
+/**
+ * One step as the root sees it: what to draw the hole around, and what to say
+ * about it. The ref rather than a measured rect, because a rect taken at
+ * registration is stale by the time the step comes up.
+ */
+
+const TourContext = /*#__PURE__*/createContext(null);
+function useTour(component) {
+  const context = useContext(TourContext);
+  if (!context) {
+    throw new Error(`${component} must be used within a <Tour>`);
+  }
+  return context;
+}
+
+/**
+ * The screen with a rounded rectangle taken out of it, as one path.
+ *
+ * Two subpaths and `fillRule="evenodd"`: the outer one covers the screen, the
+ * inner one falls inside it, and even-odd makes the overlap a hole regardless
+ * of which way either is wound. That last part is why the inner rectangle is
+ * written in the natural direction rather than reversed — the winding is not
+ * load-bearing, and a reversed path is the kind of thing that gets tidied up
+ * by someone who cannot see why it was backwards.
+ */
+function cutoutPath(screenWidth, screenHeight, x, y, width, height, radius) {
+  'worklet';
+
+  const r = Math.max(0, Math.min(radius, width / 2, height / 2));
+  const right = x + width;
+  const bottom = y + height;
+  return `M0 0H${screenWidth}V${screenHeight}H0Z ` + `M${x + r} ${y}` + `H${right - r}A${r} ${r} 0 0 1 ${right} ${y + r}` + `V${bottom - r}A${r} ${r} 0 0 1 ${right - r} ${bottom}` + `H${x + r}A${r} ${r} 0 0 1 ${x} ${bottom - r}` + `V${y + r}A${r} ${r} 0 0 1 ${x + r} ${y}Z`;
+}
+
+/**
+ * The target's bounds grown into the shape the hole will take.
+ *
+ * A circle is squared around the target's centre rather than drawn inside its
+ * bounds, because the controls that want one — an avatar, a floating action
+ * button — are square already, and squaring off the longer side is what keeps
+ * a hole round instead of letting it collapse to a slot.
+ */
+function spotlightFor(rect, shape, padding, radius) {
+  if (shape === 'circle') {
+    const diameter = Math.max(rect.width, rect.height) + padding * 2;
+    return {
+      x: rect.x + rect.width / 2 - diameter / 2,
+      y: rect.y + rect.height / 2 - diameter / 2,
+      width: diameter,
+      height: diameter,
+      radius: diameter / 2
+    };
+  }
+  return {
+    x: rect.x - padding,
+    y: rect.y - padding,
+    width: rect.width + padding * 2,
+    height: rect.height + padding * 2,
+    radius
+  };
+}
+function TourRoot({
+  children,
+  open,
+  defaultOpen = false,
+  onOpenChange,
+  step,
+  defaultStep,
+  onStepChange,
+  onFinish,
+  onSkip,
+  padding = DEFAULT_PADDING,
+  radius = DEFAULT_RADIUS,
+  shape = 'rect',
+  placement = 'auto',
+  dismissible = true,
+  showProgress = true,
+  showSkip = true,
+  interactive = false,
+  overlayColor = DEFAULT_OVERLAY,
+  labels,
+  cardClassName
+}) {
+  const [steps, setSteps] = useState([]);
+  const [internalOpen, setInternalOpen] = useState(defaultOpen);
+  const [internalStep, setInternalStep] = useState(defaultStep ?? null);
+  const isOpenControlled = open !== undefined;
+  const isStepControlled = step !== undefined;
+  const resolvedOpen = isOpenControlled ? open : internalOpen;
+  const words = {
+    ...DEFAULT_LABELS,
+    ...labels
+  };
+
+  /*
+   * Steps sort themselves by `order` rather than arriving in it, because the
+   * tree decides when each one mounts and a tour that crosses a header, a list
+   * and a tab bar mounts them in whatever order those render.
+   */
+  const register = useCallback(entry => {
+    setSteps(current => [...current.filter(other => other.order !== entry.order), entry].sort((a, b) => a.order - b.order));
+  }, []);
+  const unregister = useCallback(entry => {
+    setSteps(current => current.filter(other => other !== entry));
+  }, []);
+  const context = useMemo(() => ({
+    register,
+    unregister
+  }), [register, unregister]);
+  const activeOrder = isStepControlled ? step : internalStep ?? steps[0]?.order ?? null;
+  const index = steps.findIndex(entry => entry.order === activeOrder);
+  const active = index >= 0 ? steps[index] : undefined;
+  const isFirst = index <= 0;
+  const isLast = index === steps.length - 1;
+  const setOpen = useCallback(next => {
+    if (!isOpenControlled) setInternalOpen(next);
+    onOpenChange?.(next);
+  }, [isOpenControlled, onOpenChange]);
+  const goTo = useCallback(order => {
+    onStepChange?.(order);
+    if (!isStepControlled) setInternalStep(order);
+  }, [isStepControlled, onStepChange]);
+
+  // Reopening starts the tour over rather than resuming where it was ended.
+  // Somebody who dismissed a walkthrough and asked for it again wants it from
+  // the top; resuming a half-read tour is a state nobody asked to be in.
+  useEffect(() => {
+    if (resolvedOpen && !isStepControlled) setInternalStep(defaultStep ?? null);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [resolvedOpen]);
+  const finish = useCallback(() => {
+    setOpen(false);
+    onFinish?.();
+  }, [setOpen, onFinish]);
+  const skip = useCallback(() => {
+    setOpen(false);
+    onSkip?.();
+  }, [setOpen, onSkip]);
+  const next = useCallback(() => {
+    const following = steps[index + 1];
+    if (following) goTo(following.order);else finish();
+  }, [steps, index, goTo, finish]);
+  const back = useCallback(() => {
+    const previous = steps[index - 1];
+    if (previous) goTo(previous.order);
+  }, [steps, index, goTo]);
+  useBackHandler(resolvedOpen && dismissible, skip);
+  return /*#__PURE__*/_jsxs(TourContext.Provider, {
+    value: context,
+    children: [children, resolvedOpen && steps.length > 0 ? /*#__PURE__*/_jsx(Portal, {
+      children: /*#__PURE__*/_jsx(TourOverlay, {
+        active: active,
+        index: index,
+        total: steps.length,
+        isFirst: isFirst,
+        isLast: isLast,
+        padding: padding,
+        radius: radius,
+        shape: shape,
+        placement: placement,
+        dismissible: dismissible,
+        showProgress: showProgress,
+        showSkip: showSkip,
+        interactive: interactive,
+        overlayColor: overlayColor,
+        words: words,
+        cardClassName: cardClassName,
+        onNext: next,
+        onBack: back,
+        onSkip: skip
+      })
+    }) : null]
+  });
+}
+function TourOverlay({
+  active,
+  index,
+  total,
+  isFirst,
+  isLast,
+  padding,
+  radius,
+  shape,
+  placement,
+  dismissible,
+  showProgress,
+  showSkip,
+  interactive,
+  overlayColor,
+  words,
+  cardClassName,
+  onNext,
+  onBack,
+  onSkip
+}) {
+  const {
+    width: screenWidth,
+    height: screenHeight
+  } = useWindowDimensions();
+  const insets = useSafeAreaInsets();
+  const reducedMotion = useReducedMotion();
+  const [spot, setSpot] = useState(null);
+  const [cardHeight, setCardHeight] = useState(null);
+  const stepPadding = active?.padding ?? padding;
+  const stepRadius = active?.radius ?? radius;
+  const stepShape = active?.shape ?? shape;
+
+  /*
+   * Measured when the step becomes current and again whenever the window
+   * changes size. The second half is the part that is easy to leave out and
+   * impossible to miss once it is wrong: a rect taken in portrait describes
+   * nothing after a rotation, and the hole ends up over the wrong half of a
+   * screen the target is no longer on.
+   */
+  useEffect(() => {
+    const target = active?.target.current;
+    if (!target) {
+      setSpot(null);
+      return;
+    }
+    let cancelled = false;
+    // A frame late on purpose: a step whose target was just scrolled back into
+    // view is measured where it lands, not where it was leaving.
+    const frame = requestAnimationFrame(() => {
+      target.measureInWindow((x, y, width, height) => {
+        if (cancelled || width === 0 && height === 0) return;
+        setSpot(spotlightFor({
+          x,
+          y,
+          width,
+          height
+        }, stepShape, stepPadding, stepRadius));
+      });
+    });
+    return () => {
+      cancelled = true;
+      cancelAnimationFrame(frame);
+    };
+  }, [active, stepShape, stepPadding, stepRadius, screenWidth, screenHeight]);
+
+  /*
+   * The hole's geometry lives on the UI thread so travelling between two
+   * targets is one spring rather than a state update per frame. `settled`
+   * distinguishes the first target — which appears where it belongs — from
+   * every later one, which slides there.
+   */
+  const x = useSharedValue(0);
+  const y = useSharedValue(0);
+  const width = useSharedValue(0);
+  const height = useSharedValue(0);
+  const cornerRadius = useSharedValue(0);
+  const settled = useSharedValue(false);
+  useEffect(() => {
+    // A step with nothing to point at collapses the hole rather than leaving
+    // the last one open: the previous target is no longer what is being talked
+    // about, and a hole over it says it is.
+    if (!spot) {
+      width.value = 0;
+      height.value = 0;
+      settled.value = false;
+      return;
+    }
+    const animate = settled.value && !reducedMotion;
+    const to = (value, next) => {
+      value.value = animate ? withSpring(next, SPRING) : next;
+    };
+    to(x, spot.x);
+    to(y, spot.y);
+    to(width, spot.width);
+    to(height, spot.height);
+    to(cornerRadius, spot.radius);
+    settled.value = true;
+  }, [spot, reducedMotion, x, y, width, height, cornerRadius, settled]);
+  const pathProps = useAnimatedProps(() => ({
+    d: cutoutPath(screenWidth, screenHeight, x.value, y.value, width.value, height.value, cornerRadius.value)
+  }));
+
+  /*
+   * A step with no measurable target — a welcome card, or one whose control has
+   * gone — gets no hole and a card in the middle of the screen. Dimming the
+   * whole screen and saying nothing about where to look is honest; cutting a
+   * hole at the origin is not.
+   */
+  const card = cardFrame({
+    spot,
+    cardHeight,
+    placement: active?.placement ?? placement,
+    screenWidth,
+    screenHeight,
+    insets
+  });
+  const onCardLayout = event => {
+    const measured = event.nativeEvent.layout.height;
+    setCardHeight(current => current !== null && Math.abs(current - measured) < 1 ? current : measured);
+  };
+  return /*#__PURE__*/_jsxs(View, {
+    style: StyleSheet.absoluteFill,
+    pointerEvents: "box-none",
+    children: [/*#__PURE__*/_jsx(TourBackdrop, {
+      interactive: interactive,
+      dismissible: dismissible,
+      spot: spot,
+      screenWidth: screenWidth,
+      screenHeight: screenHeight,
+      onDismiss: onSkip
+    }), /*#__PURE__*/_jsx(Animated.View, {
+      pointerEvents: "none",
+      style: StyleSheet.absoluteFill,
+      entering: reducedMotion ? undefined : FadeIn.duration(180),
+      exiting: reducedMotion ? undefined : FadeOut.duration(140),
+      children: /*#__PURE__*/_jsx(Svg, {
+        width: screenWidth,
+        height: screenHeight,
+        children: /*#__PURE__*/_jsx(AnimatedPath, {
+          animatedProps: pathProps,
+          fill: overlayColor,
+          fillRule: "evenodd"
+        })
+      })
+    }), /*#__PURE__*/_jsx(Animated.View, {
+      entering: reducedMotion ? undefined : FadeIn.duration(200),
+      style: {
+        position: 'absolute',
+        left: card.left,
+        top: card.top,
+        width: card.width
+      },
+      children: /*#__PURE__*/_jsxs(View, {
+        onLayout: onCardLayout,
+        accessibilityViewIsModal: true,
+        accessibilityLiveRegion: "polite",
+        style: {
+          // Held off the first frame's opacity rather than off the screen:
+          // the card has to be laid out to be measured, and its height is
+          // what decides whether it goes above the target or below it.
+          opacity: cardHeight === null ? 0 : 1
+        },
+        className: cn('gap-3 rounded-2xl border border-border bg-overlay p-4 shadow-lg', cardClassName),
+        children: [dismissible ? /*#__PURE__*/_jsx(Button, {
+          variant: "ghost",
+          size: "icon",
+          accessibilityLabel: words.close,
+          onPress: onSkip,
+          className: "absolute end-1 top-1 h-9 w-9",
+          children: /*#__PURE__*/_jsx(XIcon, {
+            size: 16
+          })
+        }) : null, /*#__PURE__*/_jsxs(View, {
+          className: "gap-1 pe-8",
+          children: [showProgress && total > 1 && index >= 0 ? /*#__PURE__*/_jsx(Text, {
+            size: "xs",
+            muted: true,
+            accessibilityLabel: `Step ${index + 1} of ${total}`,
+            children: `${index + 1} of ${total}`
+          }) : null, active?.title ? /*#__PURE__*/_jsx(Text, {
+            accessibilityRole: "header",
+            weight: "semibold",
+            className: "text-overlay-foreground",
+            children: active.title
+          }) : null, active?.description ? /*#__PURE__*/_jsx(Text, {
+            size: "sm",
+            muted: true,
+            children: active.description
+          }) : null]
+        }), /*#__PURE__*/_jsxs(View, {
+          className: "flex-row items-center justify-between gap-2",
+          children: [/*#__PURE__*/_jsx(View, {
+            className: "flex-row items-center gap-1",
+            children: showSkip && !isLast ? /*#__PURE__*/_jsx(Button, {
+              variant: "ghost",
+              size: "sm",
+              onPress: onSkip,
+              children: words.skip
+            }) : null
+          }), /*#__PURE__*/_jsxs(View, {
+            className: "flex-row items-center gap-2",
+            children: [!isFirst ? /*#__PURE__*/_jsx(Button, {
+              variant: "outline",
+              size: "sm",
+              onPress: onBack,
+              startContent: /*#__PURE__*/_jsx(ChevronLeftIcon, {
+                size: 16
+              }),
+              children: words.back
+            }) : null, /*#__PURE__*/_jsx(Button, {
+              variant: "primary",
+              size: "sm",
+              onPress: onNext,
+              children: isLast ? words.done : words.next
+            })]
+          })]
+        })]
+      })
+    }, active?.order ?? 'none')]
+  });
+}
+
+/**
+ * Where the card goes, given the hole and the card's own height.
+ *
+ * Below the target when below fits, above it when it does not, and centred on
+ * the screen when there is no target at all. The card is as wide as the safe
+ * area allows up to a ceiling, because a card narrower than that on a phone
+ * only means a shorter line length and one more thing to get wrong.
+ */
+function cardFrame({
+  spot,
+  cardHeight,
+  placement,
+  screenWidth,
+  screenHeight,
+  insets
+}) {
+  const minX = insets.left + SCREEN_MARGIN;
+  const maxX = screenWidth - insets.right - SCREEN_MARGIN;
+  const width = Math.min(maxX - minX, MAX_CARD_WIDTH);
+  const left = minX + (maxX - minX - width) / 2;
+  const minY = insets.top + SCREEN_MARGIN;
+  const maxY = screenHeight - insets.bottom - SCREEN_MARGIN;
+  const height = cardHeight ?? 0;
+  if (!spot) {
+    return {
+      left,
+      top: Math.max(minY, (screenHeight - height) / 2),
+      width
+    };
+  }
+  const below = spot.y + spot.height + CARD_OFFSET;
+  const above = spot.y - CARD_OFFSET - height;
+  const fitsBelow = below + height <= maxY;
+  const fitsAbove = above >= minY;
+  const goBelow = placement === 'bottom' ? fitsBelow || !fitsAbove : placement === 'top' ? !fitsAbove : fitsBelow;
+
+  // Neither side fits — a target taller than the room around it. Clamping keeps
+  // the card on screen and lets it overlap the dim rather than the other way
+  // round, which is the lesser of the two failures.
+  const top = goBelow ? Math.min(below, maxY - height) : Math.max(above, minY);
+  return {
+    left,
+    top: Math.max(minY, top),
+    width
+  };
+}
+
+/**
+ * The layer that takes the touches the dim does not.
+ *
+ * One Pressable over everything, or four around the cutout when the target has
+ * to stay usable. Four rather than one with a hole, because a view cannot have
+ * a hole — the gap between them is the hole, and it is the only construction
+ * that leaves a rectangle of the screen reachable.
+ */
+function TourBackdrop({
+  interactive,
+  dismissible,
+  spot,
+  screenWidth,
+  screenHeight,
+  onDismiss
+}) {
+  const blocking = {
+    onStartShouldSetResponder: () => true
+  };
+  const press = dismissible ? {
+    onStartShouldSetResponder: () => true,
+    onResponderRelease: onDismiss
+  } : blocking;
+  if (!interactive || !spot) {
+    return /*#__PURE__*/_jsx(View, {
+      style: StyleSheet.absoluteFill,
+      ...press
+    });
+  }
+  const bottom = spot.y + spot.height;
+  const right = spot.x + spot.width;
+  return /*#__PURE__*/_jsxs(_Fragment, {
+    children: [/*#__PURE__*/_jsx(View, {
+      style: {
+        position: 'absolute',
+        left: 0,
+        top: 0,
+        right: 0,
+        height: Math.max(0, spot.y)
+      },
+      ...press
+    }), /*#__PURE__*/_jsx(View, {
+      style: {
+        position: 'absolute',
+        left: 0,
+        top: bottom,
+        right: 0,
+        height: Math.max(0, screenHeight - bottom)
+      },
+      ...press
+    }), /*#__PURE__*/_jsx(View, {
+      style: {
+        position: 'absolute',
+        left: 0,
+        top: spot.y,
+        width: Math.max(0, spot.x),
+        height: spot.height
+      },
+      ...press
+    }), /*#__PURE__*/_jsx(View, {
+      style: {
+        position: 'absolute',
+        left: right,
+        top: spot.y,
+        width: Math.max(0, screenWidth - right),
+        height: spot.height
+      },
+      ...press
+    })]
+  });
+}
+/**
+ * Wraps the control a step is about, and is what gets measured.
+ *
+ * The child is wrapped in a view rather than handed a ref, because the ref has
+ * to survive whatever the child is — a button, a card, a tab bar — and only a
+ * wrapper we own is guaranteed to be measurable. That wrapper is a plain view
+ * with no sizing of its own, so it takes the width its parent gives it: put
+ * layout classes on the step rather than on the child, the way you would on any
+ * other view in that position.
+ *
+ * It renders its child and nothing else while the tour is closed, and stays
+ * mounted either way — a step is a description of a control that is already on
+ * the screen, not something that appears with the walkthrough.
+ */
+function TourStep({
+  order,
+  title,
+  description,
+  shape,
+  padding,
+  radius,
+  placement,
+  className,
+  children,
+  ...props
+}) {
+  const {
+    register,
+    unregister
+  } = useTour('Tour.Step');
+  const target = useRef(null);
+  const entry = useMemo(() => ({
+    order,
+    title,
+    description,
+    shape,
+    padding,
+    radius,
+    placement,
+    target
+  }), [order, title, description, shape, padding, radius, placement]);
+  useEffect(() => {
+    register(entry);
+    return () => unregister(entry);
+  }, [entry, register, unregister]);
+  return /*#__PURE__*/_jsx(View, {
+    ref: target,
+    collapsable: false,
+    className: className,
+    ...props,
+    children: children
+  });
+}
+TourStep.displayName = 'Tour.Step';
+TourRoot.displayName = 'Tour';
+export const Tour = Object.assign(TourRoot, {
+  Step: TourStep
+});
+//# sourceMappingURL=index.js.map