panelui-native 0.71.0 → 0.75.0

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

@@ -13,8 +13,18 @@
  * attribute selectors for a stylesheet to key off. `Steps` resolves its states
  * the same way, so the two read as siblings.
  *
- * Vertical only — a horizontal timeline gives each item roughly a fifth of a
- * phone's width, which is not enough for a date and a title.
+ * ## Two orientations
+ *
+ * Vertical is the default and the ordinary case. Horizontal lays the items out
+ * as columns on a rail that runs off the side of the screen and is swiped
+ * through, which is the arrangement a long span of time wants: a decade of
+ * entries read top to bottom is a page nobody reaches the end of.
+ *
+ * The objection to a horizontal timeline is that each item gets a fifth of a
+ * phone's width, which will not hold a date and a title. The answer is that it
+ * does not have to fit — the rail is wider than the screen, and a column takes
+ * the width its contents need. An item with nothing on it collapses to a tick,
+ * so a quiet stretch compresses and a busy one keeps its room.
  *
  * ```tsx
  * <Timeline variant="icon" value={2}>
@@ -35,15 +45,53 @@
  * </Timeline>
  * ```
  */
-import { createContext, forwardRef, useContext, useMemo } from 'react';
-import { View } from 'react-native';
+import { Children, createContext, forwardRef, isValidElement, useContext, useMemo } from 'react';
+import { ScrollView, View } from 'react-native';
+import Animated, { interpolate, useAnimatedScrollHandler, useAnimatedStyle, useReducedMotion, useSharedValue } from 'react-native-reanimated';
 import { tv } from 'tailwind-variants';
 import { useCSSVariable } from 'uniwind';
 import { IconColorProvider } from "../../icons/index.js";
 import { Text, textChildren } from "../../primitives/text.js";
+import { timelineColumnWidth } from "./timeline-geometry.js";
 
 /** Semantic colour for a single event, independent of progress. */
+
+/** Which way the sequence runs. */
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+const AnimatedScrollView = Animated.createAnimatedComponent(ScrollView);
+
+/*
+ * Horizontal geometry.
+ *
+ * The rail has to land on exactly the same line in every column, and the
+ * simplest way to guarantee that is to make the band above it a fixed height
+ * rather than to position the rail against measured content. So the aside is
+ * `HORIZONTAL_RAIL_TOP` tall in every column, the rail is drawn once across the
+ * whole track at that offset, and each column's tick is pulled up by half its
+ * own height to sit centred on it.
+ */
+const HORIZONTAL_RAIL_TOP = 64;
+const HORIZONTAL_TICK_HEIGHT = 10;
+
+/**
+ * How wide a column is: what it was given, else what its contents ask for.
+ *
+ * Read by the item to size itself and by the root to build the snap offsets, so
+ * it lives here rather than in either — the two disagreeing would put every
+ * snap point half a column out.
+ */
+function itemWidth(props) {
+  let filled = false;
+  Children.forEach(props.children, child => {
+    if (filled || ! /*#__PURE__*/isValidElement(child)) return;
+    const displayName = child.type?.displayName;
+    if (displayName !== 'Timeline.Content') return;
+    const inner = child.props.children;
+    if (inner !== undefined && inner !== null && inner !== false) filled = true;
+  });
+  return timelineColumnWidth(props.width, filled);
+}
+
 /** Variants whose node is a filled disc rather than an outlined ring. */
 const SOLID_VARIANTS = ['dot', 'card'];
 const timelineVariants = tv({
@@ -117,12 +165,30 @@ const timelineVariants = tv({
       false: {
         separator: 'bg-muted'
       }
+    },
+    /*
+     * Horizontal turns the item from a row into a column and the rail from a
+     * line down the side into a line across the top. The aside is a fixed
+     * height because that height *is* where the rail sits — see
+     * HORIZONTAL_RAIL_TOP — and it is left-aligned rather than right, since a
+     * column reads from its own left edge rather than towards a rail beside it.
+     */
+    orientation: {
+      vertical: {},
+      horizontal: {
+        item: 'w-auto shrink-0 flex-col gap-0 pr-6',
+        aside: 'w-auto items-start justify-end gap-1 pb-2 pt-0',
+        rail: 'w-full items-start',
+        body: 'w-auto flex-none pb-0 pt-5',
+        title: 'text-sm'
+      }
     }
   },
   defaultVariants: {
     variant: 'dot',
     tone: 'default',
-    completed: false
+    completed: false,
+    orientation: 'vertical'
   }
 });
 
@@ -204,18 +270,62 @@ const TimelineRoot = /*#__PURE__*/forwardRef(({
   className,
   value = 0,
   variant = 'dot',
+  orientation = 'vertical',
+  snap = true,
   children,
   ...props
 }, ref) => {
+  const horizontal = orientation === 'horizontal';
   const {
     root
   } = timelineVariants({
-    variant
+    variant,
+    orientation
   });
+  const reducedMotion = useReducedMotion();
+  const scrollX = useSharedValue(0);
+  const border = useCSSVariable('--color-border');
+
+  /*
+   * The columns' left edges, from the same width rule the items size
+   * themselves by. These are the snap points, and they are what an item reads
+   * to know how far it is from the reading edge.
+   */
+  const offsets = useMemo(() => {
+    if (!horizontal) return [];
+    const result = [];
+    let sum = 0;
+    Children.forEach(children, child => {
+      if (! /*#__PURE__*/isValidElement(child)) return;
+      result.push(sum);
+      sum += itemWidth(child.props);
+    });
+    return result;
+  }, [children, horizontal]);
   const context = useMemo(() => ({
     activeStep: value,
-    variant
-  }), [value, variant]);
+    variant,
+    orientation,
+    scrollX,
+    offsets,
+    animate: !reducedMotion
+  }), [value, variant, orientation, scrollX, offsets, reducedMotion]);
+  const onScroll = useAnimatedScrollHandler(event => {
+    scrollX.value = event.contentOffset.x;
+  });
+  if (!horizontal) {
+    return /*#__PURE__*/_jsx(TimelineContext.Provider, {
+      value: context,
+      children: /*#__PURE__*/_jsx(View, {
+        ref: ref,
+        className: root({
+          className
+        }),
+        ...props,
+        children: textChildren(children)
+      })
+    });
+  }
   return /*#__PURE__*/_jsx(TimelineContext.Provider, {
     value: context,
     children: /*#__PURE__*/_jsx(View, {
@@ -224,7 +334,34 @@ const TimelineRoot = /*#__PURE__*/forwardRef(({
         className
       }),
       ...props,
-      children: textChildren(children)
+      children: /*#__PURE__*/_jsx(AnimatedScrollView, {
+        horizontal: true,
+        onScroll: onScroll,
+        scrollEventThrottle: 16,
+        showsHorizontalScrollIndicator: false,
+        decelerationRate: "fast",
+        snapToAlignment: "start",
+        snapToOffsets: snap ? offsets : undefined,
+        children: /*#__PURE__*/_jsxs(View, {
+          className: "relative flex-row",
+          children: [/*#__PURE__*/_jsx(View, {
+            accessibilityElementsHidden: true,
+            importantForAccessibility: "no-hide-descendants",
+            pointerEvents: "none",
+            style: {
+              position: 'absolute',
+              left: 0,
+              right: 0,
+              top: HORIZONTAL_RAIL_TOP,
+              borderTopWidth: 1,
+              // Dashed borders only render at a radius of zero, which this
+              // has, and the rule is the whole element.
+              borderStyle: 'dashed',
+              borderColor: typeof border === 'string' ? border : undefined
+            }
+          }), textChildren(children)]
+        })
+      })
     })
   });
 });
@@ -235,12 +372,18 @@ const TimelineItem = /*#__PURE__*/forwardRef(({
   completed,
   tone = 'default',
   last = false,
+  width,
+  style,
   children,
   ...props
 }, ref) => {
   const {
     activeStep,
-    variant
+    variant,
+    orientation,
+    scrollX,
+    offsets,
+    animate
   } = useTimeline('Timeline.Item');
   const isCompleted = completed ?? step <= activeStep;
   const {
@@ -248,22 +391,82 @@ const TimelineItem = /*#__PURE__*/forwardRef(({
   } = timelineVariants({
     variant,
     tone,
-    completed: isCompleted
+    completed: isCompleted,
+    orientation
   });
+  const horizontal = orientation === 'horizontal';
+  const columnWidth = horizontal ? itemWidth({
+    step,
+    width,
+    children
+  }) : undefined;
+  const offset = offsets[step] ?? 0;
   const context = useMemo(() => ({
     step,
     completed: isCompleted,
     tone,
-    showSeparator: !last
-  }), [step, isCompleted, tone, last]);
+    showSeparator: !last,
+    offset,
+    columnWidth: columnWidth ?? 0
+  }), [step, isCompleted, tone, last, offset, columnWidth]);
+
+  /*
+   * A column recedes as it leaves the reading edge, so the one being read is
+   * the one that looks read.
+   *
+   * One column's width either side, not two: a window wide enough to hold
+   * three columns near full strength is a row where nothing is picked out,
+   * and picking one out is the whole job. The neighbours stay legible at the
+   * far end of it — a timeline is worth reading for what came before and
+   * after — they simply stop competing.
+   *
+   * The scale and the drop are what turn a fade into a focus. Four points and
+   * four percent is under the threshold where anybody would call it movement,
+   * and over the one where the column at the edge stops looking flat against
+   * the rest.
+   */
+  const columnStyle = useAnimatedStyle(() => {
+    if (!horizontal || !animate) return {
+      opacity: 1,
+      transform: []
+    };
+    const distance = Math.abs(scrollX.value - offset);
+    const window = Math.max(columnWidth ?? timelineColumnWidth(undefined, true), 1);
+    const away = interpolate(distance, [0, window], [0, 1], 'clamp');
+    return {
+      opacity: 1 - away * 0.4,
+      transform: [{
+        scale: 1 - away * 0.04
+      }, {
+        translateY: away * 4
+      }]
+    };
+  });
+  if (!horizontal) {
+    return /*#__PURE__*/_jsx(TimelineItemContext.Provider, {
+      value: context,
+      children: /*#__PURE__*/_jsx(View, {
+        ref: ref,
+        className: item({
+          className
+        }),
+        style: style,
+        ...props,
+        children: textChildren(children)
+      })
+    });
+  }
   return /*#__PURE__*/_jsx(TimelineItemContext.Provider, {
     value: context,
-    children: /*#__PURE__*/_jsx(View, {
+    children: /*#__PURE__*/_jsx(Animated.View, {
       ref: ref,
       className: item({
         className
       }),
       ...props,
+      style: [style, {
+        width: columnWidth
+      }, columnStyle],
       children: textChildren(children)
     })
   });
@@ -276,21 +479,33 @@ TimelineItem.displayName = 'Timeline.Item';
  */
 const TimelineAside = /*#__PURE__*/forwardRef(({
   className,
+  style,
   ...props
 }, ref) => {
   const {
-    variant
+    variant,
+    orientation
   } = useTimeline('Timeline.Aside');
   const {
     aside
   } = timelineVariants({
-    variant
+    variant,
+    orientation
   });
   return /*#__PURE__*/_jsx(View, {
     ref: ref,
     className: aside({
       className
-    }),
+    })
+    /*
+     * Horizontal: this band's height is where the rail lands, so it is
+     * fixed rather than sized to whatever the column happens to put in it.
+     * A column with a longer label would otherwise push its own tick below
+     * everybody else's and the rail would stop being a line.
+     */,
+    style: orientation === 'horizontal' ? [{
+      height: HORIZONTAL_RAIL_TOP
+    }, style] : style,
     ...props
   });
 });
@@ -308,7 +523,8 @@ const TimelineIndicator = /*#__PURE__*/forwardRef(({
   ...props
 }, ref) => {
   const {
-    variant
+    variant,
+    orientation
   } = useTimeline('Timeline.Indicator');
   const {
     step,
@@ -324,9 +540,36 @@ const TimelineIndicator = /*#__PURE__*/forwardRef(({
   } = timelineVariants({
     variant,
     tone,
-    completed
+    completed,
+    orientation
   });
 
+  /*
+   * Horizontal: a tick sitting on the rail, not a node with a connector
+   * running out of it. The rail is already drawn across the whole track by
+   * the root, so what a column owes it is the mark saying where this entry
+   * falls — pulled up by half its height to straddle the line rather than
+   * hang off it.
+   */
+  if (orientation === 'horizontal') {
+    return /*#__PURE__*/_jsx(View, {
+      className: rail(),
+      children: /*#__PURE__*/_jsx(View, {
+        ref: ref,
+        accessibilityElementsHidden: true,
+        importantForAccessibility: "no-hide-descendants",
+        className: indicator({
+          className: `w-px rounded-none ${completed ? 'bg-primary' : 'bg-muted-foreground'} ${className ?? ''}`
+        }),
+        style: {
+          height: HORIZONTAL_TICK_HEIGHT,
+          marginTop: -HORIZONTAL_TICK_HEIGHT / 2
+        },
+        ...props
+      })
+    });
+  }
+
   // dot/card nodes are small discs with nothing inside, so they keep full
   // saturation — a soft tint at 16px would disappear. Nodes that hold an
   // icon or a number take the tinted fill instead.
@@ -376,14 +619,20 @@ TimelineIndicator.displayName = 'Timeline.Indicator';
 const TimelineContent = /*#__PURE__*/forwardRef(({
   className,
   children,
+  style,
   ...props
 }, ref) => {
   const {
-    variant
+    variant,
+    orientation,
+    scrollX,
+    animate
   } = useTimeline('Timeline.Content');
   const {
     completed,
-    tone
+    tone,
+    offset,
+    columnWidth
   } = useTimelineItem('Timeline.Content');
   const {
     body,
@@ -391,18 +640,54 @@ const TimelineContent = /*#__PURE__*/forwardRef(({
   } = timelineVariants({
     variant,
     tone,
-    completed
+    completed,
+    orientation
   });
-  return /*#__PURE__*/_jsx(View, {
+  const horizontal = orientation === 'horizontal';
+
+  /*
+   * Horizontal: the body recedes further than the column around it.
+   *
+   * The rail is a continuous thing and has to stay readable across the whole
+   * track — the years either side of the one being read are half of what a
+   * timeline is for. The prose under them is not: several columns of it at
+   * equal weight is a wall, and no amount of fading the column as a whole
+   * fixes that without taking the years down with it. So the body takes a
+   * second, steeper curve and the dates keep the first one.
+   */
+  const bodyStyle = useAnimatedStyle(() => {
+    if (!horizontal || !animate) return {
+      opacity: 1
+    };
+    const distance = Math.abs(scrollX.value - offset);
+    const window = Math.max(columnWidth, 1);
+    return {
+      opacity: interpolate(distance, [0, window], [1, 0.3], 'clamp')
+    };
+  });
+  const inner = variant === 'card' ? /*#__PURE__*/_jsx(View, {
+    className: panel(),
+    children: textChildren(children)
+  }) : children;
+  if (!horizontal) {
+    return /*#__PURE__*/_jsx(View, {
+      ref: ref,
+      className: body({
+        className
+      }),
+      style: style,
+      ...props,
+      children: inner
+    });
+  }
+  return /*#__PURE__*/_jsx(Animated.View, {
     ref: ref,
     className: body({
       className
     }),
     ...props,
-    children: variant === 'card' ? /*#__PURE__*/_jsx(View, {
-      className: panel(),
-      children: textChildren(children)
-    }) : children
+    style: [style, bodyStyle],
+    children: inner
   });
 });
 TimelineContent.displayName = 'Timeline.Content';
@@ -413,12 +698,14 @@ const TimelineHeader = /*#__PURE__*/forwardRef(({
   ...props
 }, ref) => {
   const {
-    variant
+    variant,
+    orientation
   } = useTimeline('Timeline.Header');
   const {
     header
   } = timelineVariants({
-    variant
+    variant,
+    orientation
   });
   return /*#__PURE__*/_jsx(View, {
     ref: ref,
@@ -436,12 +723,14 @@ const TimelineHeading = /*#__PURE__*/forwardRef(({
   ...props
 }, ref) => {
   const {
-    variant
+    variant,
+    orientation
   } = useTimeline('Timeline.Heading');
   const {
     heading
   } = timelineVariants({
-    variant
+    variant,
+    orientation
   });
   return /*#__PURE__*/_jsx(View, {
     ref: ref,
@@ -457,12 +746,14 @@ const TimelineDate = /*#__PURE__*/forwardRef(({
   ...props
 }, ref) => {
   const {
-    variant
+    variant,
+    orientation
   } = useTimeline('Timeline.Date');
   const {
     date
   } = timelineVariants({
-    variant
+    variant,
+    orientation
   });
   return /*#__PURE__*/_jsx(Text, {
     ref: ref,
@@ -480,7 +771,8 @@ const TimelineLabel = /*#__PURE__*/forwardRef(({
   ...props
 }, ref) => {
   const {
-    variant
+    variant,
+    orientation
   } = useTimeline('Timeline.Label');
   const {
     tone
@@ -489,7 +781,8 @@ const TimelineLabel = /*#__PURE__*/forwardRef(({
     label
   } = timelineVariants({
     variant,
-    tone
+    tone,
+    orientation
   });
   return /*#__PURE__*/_jsx(Text, {
     ref: ref,
@@ -507,12 +800,14 @@ const TimelineMeta = /*#__PURE__*/forwardRef(({
   ...props
 }, ref) => {
   const {
-    variant
+    variant,
+    orientation
   } = useTimeline('Timeline.Meta');
   const {
     meta
   } = timelineVariants({
-    variant
+    variant,
+    orientation
   });
   return /*#__PURE__*/_jsx(Text, {
     ref: ref,
@@ -528,12 +823,14 @@ const TimelineTitle = /*#__PURE__*/forwardRef(({
   ...props
 }, ref) => {
   const {
-    variant
+    variant,
+    orientation
   } = useTimeline('Timeline.Title');
   const {
     title
   } = timelineVariants({
-    variant
+    variant,
+    orientation
   });
   return /*#__PURE__*/_jsx(Text, {
     ref: ref,
@@ -551,12 +848,14 @@ const TimelineTrailing = /*#__PURE__*/forwardRef(({
   ...props
 }, ref) => {
   const {
-    variant
+    variant,
+    orientation
   } = useTimeline('Timeline.Trailing');
   const {
     trailing
   } = timelineVariants({
-    variant
+    variant,
+    orientation
   });
   return /*#__PURE__*/_jsx(Text, {
     ref: ref,
@@ -572,12 +871,14 @@ const TimelineDescription = /*#__PURE__*/forwardRef(({
   ...props
 }, ref) => {
   const {
-    variant
+    variant,
+    orientation
   } = useTimeline('Timeline.Description');
   const {
     content
   } = timelineVariants({
-    variant
+    variant,
+    orientation
   });
   return /*#__PURE__*/_jsx(Text, {
     ref: ref,
@@ -595,12 +896,14 @@ const TimelineStats = /*#__PURE__*/forwardRef(({
   ...props
 }, ref) => {
   const {
-    variant
+    variant,
+    orientation
   } = useTimeline('Timeline.Stats');
   const {
     stats
   } = timelineVariants({
-    variant
+    variant,
+    orientation
   });
   return /*#__PURE__*/_jsx(View, {
     ref: ref,
@@ -618,13 +921,15 @@ const TimelineStat = /*#__PURE__*/forwardRef(({
   ...props
 }, ref) => {
   const {
-    variant
+    variant,
+    orientation
   } = useTimeline('Timeline.Stat');
   const {
     statLabel,
     statValue
   } = timelineVariants({
-    variant
+    variant,
+    orientation
   });
   return /*#__PURE__*/_jsxs(View, {
     ref: ref,