panelui-native 0.77.0 → 0.79.0

package/src/components/theme-selector/theme-preview.tsx

@@ -0,0 +1,205 @@
+/**
+ * The three miniatures a theme selector is made of.
+ *
+ * Drawn from fixed neutrals rather than from theme tokens, which is the one
+ * thing about this file that is not obvious. A preview built out of the active
+ * theme's colours shows the reader the theme they already have, three times —
+ * the light option has to look light while the app around it is dark, or it is
+ * not a preview of anything.
+ *
+ * The greys are the ones a screenshot of an app would actually have: a ground,
+ * a surface sitting on it, a mark, and the lines of text. Two sets, and the
+ * system option draws both.
+ */
+import { useId, type ReactNode } from 'react';
+import Svg, { Circle, ClipPath, Defs, G, Path, Rect } from 'react-native-svg';
+
+/** Which of the three a preview is drawing. */
+export type ThemePreviewMode = 'system' | 'light' | 'dark';
+
+/** How the miniature is drawn. */
+export type ThemePreviewVariant = 'window' | 'card';
+
+interface Palette {
+  /** Behind everything — the desktop, the page, the space around the app. */
+  ground: string;
+  /** The app's own surface. */
+  surface: string;
+  /** A shape on it: an avatar, an image, a control. */
+  mark: string;
+  /** Lines of text. */
+  line: string;
+}
+
+const PALETTE: Record<'light' | 'dark', Palette> = {
+  light: { ground: '#e5e5e5', surface: '#ffffff', mark: '#d4d4d4', line: '#e5e5e5' },
+  dark: { ground: '#171717', surface: '#262626', mark: '#525252', line: '#404040' },
+};
+
+/**
+ * The one colour that is not a grey.
+ *
+ * Fixed for the same reason the greys are, and warm rather than blue: it has to
+ * read as "a colour in the app" on both grounds without looking like the ring
+ * that marks the chosen option.
+ */
+const ACCENT = '#c1704f';
+
+/** Everything is drawn in this box and scaled by the container. */
+const VIEW_BOX = { width: 88, height: 70 };
+
+/**
+ * The lower-right half of the box, cut from the top-right corner to the
+ * bottom-left one. Both text lines sit above it and the accent below it, which
+ * is what makes one card show a light screen and a dark one at the same time.
+ */
+const DIAGONAL = `M${VIEW_BOX.width} 0V${VIEW_BOX.height}H0Z`;
+
+/* -------------------------------------------------------------------------- *
+ * window — an app screen, with the panel inset from the leading edge
+ * -------------------------------------------------------------------------- */
+
+function WindowHalf({ palette, side }: { palette: Palette; side: 'left' | 'right' | 'full' }) {
+  if (side === 'full') {
+    return (
+      <>
+        <Rect x={0} y={0} width={88} height={70} fill={palette.ground} />
+        <Path d="M10 12a4 4 0 0 1 4-4h74v62H10V12Z" fill={palette.surface} />
+        <Circle cx={28} cy={26} r={8} fill={palette.mark} />
+        <Rect x={20} y={42} width={58} height={4} rx={2} fill={palette.line} />
+        <Rect x={20} y={49} width={58} height={4} rx={2} fill={palette.line} />
+        <Rect x={20} y={56} width={29} height={4} rx={2} fill={palette.line} />
+      </>
+    );
+  }
+
+  /*
+   * Half a screen each, and the halves are not mirror images: the panel starts
+   * at the same inset on the left and runs to the edge on the right, so the
+   * seam falls where the two app surfaces meet rather than down the middle of
+   * one of them.
+   */
+  const x = side === 'left' ? 0 : 44;
+  return (
+    <>
+      <Rect x={x} y={0} width={44} height={70} fill={palette.ground} />
+      {side === 'left' ? (
+        <>
+          <Path d="M10 12a4 4 0 0 1 4-4h30v62H10V12Z" fill={palette.surface} />
+          <Circle cx={28} cy={26} r={8} fill={palette.mark} />
+          <Rect x={20} y={42} width={24} height={4} rx={2} fill={palette.line} />
+          <Rect x={20} y={49} width={24} height={4} rx={2} fill={palette.line} />
+          <Rect x={20} y={56} width={24} height={4} rx={2} fill={palette.line} />
+        </>
+      ) : (
+        <>
+          <Path d="M54 12a4 4 0 0 1 4-4h30v62H54V12Z" fill={palette.surface} />
+          <Circle cx={72} cy={26} r={8} fill={palette.mark} />
+          <Rect x={64} y={42} width={24} height={4} rx={2} fill={palette.line} />
+          <Rect x={64} y={49} width={24} height={4} rx={2} fill={palette.line} />
+          <Rect x={64} y={56} width={24} height={4} rx={2} fill={palette.line} />
+        </>
+      )}
+    </>
+  );
+}
+
+/* -------------------------------------------------------------------------- *
+ * card — a framed card, with an accent on it
+ * -------------------------------------------------------------------------- */
+
+/*
+ * The card fills its box rather than floating inside it.
+ *
+ * It used to carry a margin of its own, which then sat on top of the padding
+ * between the artwork and the ring around it — two gaps doing one job, and the
+ * bigger the miniature the further apart they held the two edges.
+ */
+const CARD_FRAME = { x: 0, y: 0, width: 88, height: 70, rx: 16 } as const;
+const CARD_SURFACE = { x: 8, y: 8, width: 72, height: 54, rx: 10 } as const;
+
+function CardBody({ palette }: { palette: Palette }) {
+  return (
+    <>
+      <Rect {...CARD_FRAME} fill={palette.ground} />
+      <Rect {...CARD_SURFACE} fill={palette.surface} />
+      <Rect x={17} y={18} width={34} height={4} rx={2} fill={palette.line} />
+      <Rect x={17} y={26} width={23} height={4} rx={2} fill={palette.line} />
+    </>
+  );
+}
+
+export interface ThemePreviewProps {
+  mode: ThemePreviewMode;
+  variant?: ThemePreviewVariant;
+  width: number;
+}
+
+/**
+ * One miniature.
+ *
+ * `width` rather than a scale factor: the option's box is what decides the
+ * size, and everything inside is drawn against a fixed box and scaled by the
+ * viewBox — so the geometry above never has to know how big it ended up.
+ */
+export function ThemePreview({ mode, variant = 'window', width }: ThemePreviewProps): ReactNode {
+  const height = Math.round((width / VIEW_BOX.width) * VIEW_BOX.height);
+  /*
+   * `useId` returns something with colons in it, which is not a name an SVG
+   * fragment reference accepts — a clip that silently fails to resolve draws
+   * nothing at all, and on a shape covering half the artwork that is the whole
+   * option missing.
+   */
+  const clip = `panelui-theme-${useId().replace(/[^a-zA-Z0-9-]/g, '')}`;
+
+  if (variant === 'card') {
+    return (
+      <Svg width={width} height={height} viewBox="0 0 88 70">
+        <CardBody palette={PALETTE[mode === 'dark' ? 'dark' : 'light']} />
+
+        {mode === 'system' ? (
+          <>
+            {/*
+              The other half, cut corner to corner.
+              
+              The same triangle twice, clipped once to the frame and once to
+              the card inside it, rather than one shape tracing where the
+              diagonal crosses both. Two clips is less arithmetic than one path
+              and stays right if either radius changes; an unclipped triangle
+              squares off the two corners the diagonal runs into.
+            */}
+            <Defs>
+              <ClipPath id={`${clip}-frame`}>
+                <Rect {...CARD_FRAME} />
+              </ClipPath>
+              <ClipPath id={`${clip}-card`}>
+                <Rect {...CARD_SURFACE} />
+              </ClipPath>
+            </Defs>
+            <G clipPath={`url(#${clip}-frame)`}>
+              <Path d={DIAGONAL} fill={PALETTE.dark.ground} />
+            </G>
+            <G clipPath={`url(#${clip}-card)`}>
+              <Path d={DIAGONAL} fill={PALETTE.dark.surface} />
+            </G>
+          </>
+        ) : null}
+
+        <Circle cx={64} cy={47} r={8} fill={ACCENT} />
+      </Svg>
+    );
+  }
+
+  return (
+    <Svg width={width} height={height} viewBox="0 0 88 70">
+      {mode === 'system' ? (
+        <>
+          <WindowHalf palette={PALETTE.light} side="left" />
+          <WindowHalf palette={PALETTE.dark} side="right" />
+        </>
+      ) : (
+        <WindowHalf palette={PALETTE[mode]} side="full" />
+      )}
+    </Svg>
+  );
+}

package/src/components/timeline/index.tsx

@@ -64,6 +64,9 @@ import {
 } from 'react-native';
 import Animated, {
   interpolate,
+  interpolateColor,
+  runOnJS,
+  useAnimatedReaction,
   useAnimatedScrollHandler,
   useAnimatedStyle,
   useReducedMotion,
@@ -73,9 +76,100 @@ import Animated, {
 import { tv } from 'tailwind-variants';
 import { useCSSVariable } from 'uniwind';
 import { IconColorProvider } from '../../icons';
+import { selectionTick } from '../../utils/haptics';
 import { Text, type TextProps, textChildren } from '../../primitives/text';
 import { TIMELINE_WIDE_COLUMN, timelineColumnOffsets, timelineColumnWidth } from './timeline-geometry';
 
+const AnimatedText = Animated.createAnimatedComponent(Text);
+
+/**
+ * A tick as the reading edge passes from one column to the next.
+ *
+ * The comparison runs on the UI thread every frame; the call back to
+ * JavaScript happens once per column crossed, which is the difference between
+ * feedback and a haptic per frame. Fired at the crossing itself rather than
+ * when the scroll settles, so the tick and the column arriving are the same
+ * moment — a haptic that lags what caused it reads as a glitch.
+ */
+function useColumnDetent(
+  scrollX: SharedValue<number>,
+  offsets: number[],
+  enabled: boolean
+) {
+  const nearest = useSharedValue(0);
+
+  useAnimatedReaction(
+    () => {
+      if (!enabled || offsets.length === 0) return 0;
+      let index = 0;
+      let best = Infinity;
+      for (let i = 0; i < offsets.length; i += 1) {
+        const distance = Math.abs(scrollX.value - (offsets[i] ?? 0));
+        if (distance < best) {
+          best = distance;
+          index = i;
+        }
+      }
+      return index;
+    },
+    (index, previous) => {
+      if (!enabled || previous === null || index === previous) return;
+      nearest.value = index;
+      runOnJS(selectionTick)();
+    }
+  );
+}
+
+
+/*
+ * Fallbacks for the two ends of the focus ramp, used only before the theme's
+ * variables have resolved. `interpolateColor` needs two real colours on the
+ * very first frame, and a missing one is a crash rather than a wrong shade.
+ */
+const INK_FALLBACK = { foreground: '#09090b', muted: '#71717a' };
+
+/**
+ * A column's text at full strength while it is the one being read, and muted
+ * while it is not.
+ *
+ * Horizontal only, and it is the piece that was missing. Scale and a small drop
+ * already picked the focused column out of the row, but every word in every
+ * column stayed the same muted grey — so the column you had scrolled to was
+ * nearer and no easier to read than the ones either side of it. Colour is what
+ * says *this is the one*, and it is the only cue that survives being looked at
+ * rather than glanced at.
+ *
+ * The ramp runs to the foreground token, which is what a heading uses. Anything
+ * softer is another grey, and the whole complaint about the old drawing was
+ * that it was grey.
+ *
+ * It is not disabled under reduced motion. The value is driven by scroll
+ * position rather than by a clock — the reader's own finger is what moves it —
+ * so there is no motion here to reduce. What that setting turns off is the
+ * scale and the drop, which is handled where those are.
+ */
+function useColumnInk(component: string) {
+  const { orientation, scrollX } = useTimeline(component);
+  const item = useContext(TimelineItemContext);
+  const foregroundToken = useCSSVariable('--color-foreground');
+  const mutedToken = useCSSVariable('--color-muted-foreground');
+
+  const horizontal = orientation === 'horizontal';
+  const offset = item?.offset ?? 0;
+  const width = Math.max(item?.columnWidth || TIMELINE_WIDE_COLUMN, 1);
+  const foreground =
+    typeof foregroundToken === 'string' ? foregroundToken : INK_FALLBACK.foreground;
+  const muted = typeof mutedToken === 'string' ? mutedToken : INK_FALLBACK.muted;
+
+  const style = useAnimatedStyle(() => {
+    const distance = Math.abs(scrollX.value - offset);
+    const away = interpolate(distance, [0, width], [0, 1], 'clamp');
+    return { color: interpolateColor(away, [0, 1], [foreground, muted]) };
+  });
+
+  return { horizontal, style };
+}
+
 export type TimelineVariant = 'dot' | 'icon' | 'numbered' | 'card' | 'compact';
 /** Semantic colour for a single event, independent of progress. */
 export type TimelineTone = 'default' | 'info' | 'success' | 'warning' | 'danger';
@@ -315,6 +409,13 @@ export interface TimelineProps extends ViewProps {
    * halfway shows two half-columns and no whole one.
    */
   snap?: boolean;
+  /**
+   * Horizontal only: a tick as the reading edge passes from one column to the
+   * next. Needs `snap`, since a scroll that lands anywhere has no detents to
+   * feel. Off by default — a haptic per column is a lot for a long history, and
+   * whether this one is worth feeling is the caller's call.
+   */
+  haptics?: boolean;
   children?: ReactNode;
 }
 
@@ -326,6 +427,7 @@ const TimelineRoot = forwardRef<View, TimelineProps>(
       variant = 'dot',
       orientation = 'vertical',
       snap = true,
+      haptics = false,
       children,
       ...props
     },
@@ -382,6 +484,8 @@ const TimelineRoot = forwardRef<View, TimelineProps>(
       scrollX.value = event.contentOffset.x;
     });
 
+    useColumnDetent(scrollX, offsets, horizontal && snap && haptics);
+
     if (!horizontal) {
       return (
         <TimelineContext.Provider value={context}>
@@ -841,13 +945,17 @@ TimelineIndicator.displayName = 'Timeline.Indicator';
  */
 const TimelineContent = forwardRef<View, ViewProps & { className?: string }>(
   ({ className, children, style, ...props }, ref) => {
-    const { variant, orientation, scrollX, animate } = useTimeline('Timeline.Content');
-    const { completed, tone, offset, columnWidth } =
-      useTimelineItem('Timeline.Content');
+    const { variant, orientation } = useTimeline('Timeline.Content');
+    const { completed, tone } = useTimelineItem('Timeline.Content');
     const { body, panel } = timelineVariants({ variant, tone, completed, orientation });
     const horizontal = orientation === 'horizontal';
 
-    /* Horizontal content stays fully opaque; scale and translation provide focus. */
+    /*
+     * Horizontal content is not dimmed as a block. The column already carries
+     * the focus — it is nearer, and its text runs to the foreground as it comes
+     * to the reading edge — and fading the whole slot on top of that would take
+     * the neighbours out of the timeline rather than out of the way.
+     */
 
     const inner =
       variant === 'card' ? (
@@ -865,14 +973,9 @@ const TimelineContent = forwardRef<View, ViewProps & { className?: string }>(
     }
 
     return (
-      <Animated.View
-        ref={ref}
-        className={body({ className })}
-        {...props}
-        style={style}
-      >
+      <View ref={ref} className={body({ className })} style={style} {...props}>
         {inner}
-      </Animated.View>
+      </View>
     );
   }
 );
@@ -898,10 +1001,16 @@ const TimelineHeading = forwardRef<View, ViewProps & { className?: string }>(
 );
 TimelineHeading.displayName = 'Timeline.Heading';
 
-const TimelineDate = forwardRef<RNText, TextProps>(({ className, ...props }, ref) => {
+const TimelineDate = forwardRef<RNText, TextProps>(({ className, style, ...props }, ref) => {
   const { variant, orientation } = useTimeline('Timeline.Date');
   const { date } = timelineVariants({ variant, orientation });
-  return <Text ref={ref} className={date({ className })} {...props} />;
+  const ink = useColumnInk('Timeline.Date');
+  if (!ink.horizontal) {
+    return <Text ref={ref} className={date({ className })} style={style} {...props} />;
+  }
+  return (
+    <AnimatedText ref={ref} className={date({ className })} style={[style, ink.style]} {...props} />
+  );
 });
 TimelineDate.displayName = 'Timeline.Date';
 
@@ -915,10 +1024,16 @@ const TimelineLabel = forwardRef<RNText, TextProps>(({ className, ...props }, re
 TimelineLabel.displayName = 'Timeline.Label';
 
 /** Muted supporting line — a person's name, a source. */
-const TimelineMeta = forwardRef<RNText, TextProps>(({ className, ...props }, ref) => {
+const TimelineMeta = forwardRef<RNText, TextProps>(({ className, style, ...props }, ref) => {
   const { variant, orientation } = useTimeline('Timeline.Meta');
   const { meta } = timelineVariants({ variant, orientation });
-  return <Text ref={ref} className={meta({ className })} {...props} />;
+  const ink = useColumnInk('Timeline.Meta');
+  if (!ink.horizontal) {
+    return <Text ref={ref} className={meta({ className })} style={style} {...props} />;
+  }
+  return (
+    <AnimatedText ref={ref} className={meta({ className })} style={[style, ink.style]} {...props} />
+  );
 });
 TimelineMeta.displayName = 'Timeline.Meta';
 
@@ -940,10 +1055,21 @@ const TimelineTrailing = forwardRef<RNText, TextProps>(
 TimelineTrailing.displayName = 'Timeline.Trailing';
 
 const TimelineDescription = forwardRef<RNText, TextProps>(
-  ({ className, ...props }, ref) => {
+  ({ className, style, ...props }, ref) => {
     const { variant, orientation } = useTimeline('Timeline.Description');
     const { content } = timelineVariants({ variant, orientation });
-    return <Text ref={ref} className={content({ className })} {...props} />;
+    const ink = useColumnInk('Timeline.Description');
+    if (!ink.horizontal) {
+      return <Text ref={ref} className={content({ className })} style={style} {...props} />;
+    }
+    return (
+      <AnimatedText
+        ref={ref}
+        className={content({ className })}
+        style={[style, ink.style]}
+        {...props}
+      />
+    );
   }
 );
 TimelineDescription.displayName = 'Timeline.Description';

package/src/components/toast/index.tsx

@@ -28,12 +28,16 @@ import { Gesture, GestureDetector } from 'react-native-gesture-handler';
 import Animated, {
   Easing,
   Extrapolation,
+  FadeIn,
   FadeInDown,
   FadeInUp,
+  FadeOut,
   Keyframe,
   interpolate,
   runOnJS,
   useAnimatedStyle,
+  useDerivedValue,
+  useReducedMotion,
   useSharedValue,
   withDecay,
   withSpring,
@@ -58,6 +62,13 @@ import {
 } from './toast-store';
 
 const SPRING = { damping: 20, stiffness: 260, mass: 0.6 } as const;
+
+/**
+ * The deck reshuffling after a dismissal. Slower and softer than the drag's
+ * spring: the cards behind are not what the reader is acting on, and a stack
+ * that snaps draws the eye to the wrong thing.
+ */
+const STACK_SPRING = { duration: 350, dampingRatio: 0.9 } as const;
 /** Drag distance past which a release dismisses. */
 const DISMISS_DISTANCE = 50;
 /** Fling speed past which a release dismisses regardless of distance. */
@@ -91,15 +102,24 @@ const enteringBottom = FadeInDown.springify()
   .withInitialValues({ opacity: 1, transform: [{ translateY: ENTER_OFFSET }] })
   .mass(3);
 
+/*
+ * It leaves the way it arrived, a little quicker.
+ *
+ * The curve was an ease-*in*, which starts slow — it spends the first frames of
+ * the exit barely moving, which is exactly the moment the reader is looking at
+ * the thing that just changed. This is the ease-out used everywhere else in the
+ * library, and the duration is a fifth under the entrance: the arrival earns
+ * the time, the departure does not.
+ */
 const exitKeyframe = (offset: number) =>
   new Keyframe({
     0: { opacity: 1, transform: [{ translateY: 0 }, { scale: 1 }] },
     100: {
-      opacity: 0.5,
+      opacity: 0,
       transform: [{ translateY: offset }, { scale: 0.97 }],
-      easing: Easing.bezier(0.4, 0, 1, 1),
+      easing: Easing.bezier(0.23, 1, 0.32, 1),
     },
-  }).duration(150);
+  }).duration(240);
 
 const exitingTop = exitKeyframe(-ENTER_OFFSET);
 const exitingBottom = exitKeyframe(ENTER_OFFSET);
@@ -315,6 +335,7 @@ function ToastSlot({
   const placement = item.placement ?? 'bottom';
   const translateY = useSharedValue(0);
   const scale = useSharedValue(1);
+  const reducedMotion = useReducedMotion();
   const hide = useCallback(() => toastStore.hide(item.id), [item.id]);
 
   // Drop this toast's measurement when it leaves, so the map cannot grow
@@ -387,22 +408,35 @@ function ToastSlot({
    * The whole deck takes the *newest* toast's height so the cards behind read
    * as a uniform stack rather than a ragged pile.
    */
+  /*
+   * How far back in the deck this toast is: 0 is the front one.
+   *
+   * Sprung rather than read straight off the props. Position used to be
+   * computed from `index` and `total` directly, so dismissing a toast in the
+   * middle teleported every card behind it forward a step between two frames.
+   * The deck reshuffling is the one moment the stack is worth watching, and it
+   * was the one moment it did not move.
+   */
+  const depth = useDerivedValue(() =>
+    reducedMotion ? total - 1 - index : withSpring(total - 1 - index, STACK_SPRING)
+  );
+
   const stackStyle = useAnimatedStyle(() => {
     // Fall back to this toast's own height until the front one is measured.
     const frontHeight = heights.value[frontId] ?? heights.value[item.id];
 
-    // Newest sits at 0; each one behind steps back by STACK_OFFSET and shrinks.
-    const inputRange = [total - 1, total - 2];
-    const offset = interpolate(index, inputRange, [0, STACK_OFFSET * stackSign], {
+    // Front sits at 0; each one behind steps back by STACK_OFFSET and shrinks.
+    const back = depth.value;
+    const offset = interpolate(back, [0, 1], [0, STACK_OFFSET * stackSign], {
       extrapolateLeft: Extrapolation.CLAMP,
     });
-    const stackScale = interpolate(index, inputRange, [1, STACK_SCALE_STEP], {
+    const stackScale = interpolate(back, [0, 1], [1, STACK_SCALE_STEP], {
       extrapolateLeft: Extrapolation.CLAMP,
     });
     // Anything past MAX_VISIBLE fades out rather than piling up forever.
     const opacity = interpolate(
-      index,
-      [total - MAX_VISIBLE, total - MAX_VISIBLE - 1],
+      back,
+      [MAX_VISIBLE - 1, MAX_VISIBLE],
       [1, 0],
       Extrapolation.CLAMP
     );
@@ -443,8 +477,23 @@ function ToastSlot({
 
   return (
     <Animated.View
-      entering={placement === 'top' ? enteringTop : enteringBottom}
-      exiting={placement === 'top' ? exitingTop : exitingBottom}
+      /* Reduced motion keeps the fade — a toast that appears with no transition
+         at all is a jump-cut, and the arrival still has to be noticed — and
+         drops the travel and the scale. */
+      entering={
+        reducedMotion
+          ? FadeIn.duration(150)
+          : placement === 'top'
+            ? enteringTop
+            : enteringBottom
+      }
+      exiting={
+        reducedMotion
+          ? FadeOut.duration(120)
+          : placement === 'top'
+            ? exitingTop
+            : exitingBottom
+      }
       pointerEvents="box-none"
       // Every toast is pinned to the same edge, so they overlap as a deck.
       // Newest on top. Horizontal inset lives here rather than as padding on