panelui-native 0.79.0 → 0.80.0

package/src/components/timeline/index.tsx

@@ -49,6 +49,7 @@ import {
   createContext,
   forwardRef,
   isValidElement,
+  useCallback,
   useContext,
   useMemo,
   type ReactElement,
@@ -94,10 +95,27 @@ const AnimatedText = Animated.createAnimatedComponent(Text);
 function useColumnDetent(
   scrollX: SharedValue<number>,
   offsets: number[],
-  enabled: boolean
+  haptics: boolean,
+  onColumnChange?: (index: number) => void
 ) {
   const nearest = useSharedValue(0);
 
+  /*
+   * A stable function for `runOnJS`. The prop itself is a fresh closure on
+   * every render, and handing that to the UI thread re-serialises it on every
+   * frame the reaction is rebuilt.
+   */
+  const report = useCallback(
+    (index: number) => {
+      onColumnChange?.(index);
+    },
+    [onColumnChange]
+  );
+
+  // Nothing to compute unless somebody is listening. The reaction runs on
+  // every scroll frame, so a timeline that wants neither pays nothing.
+  const enabled = haptics || onColumnChange !== undefined;
+
   useAnimatedReaction(
     () => {
       if (!enabled || offsets.length === 0) return 0;
@@ -115,7 +133,8 @@ function useColumnDetent(
     (index, previous) => {
       if (!enabled || previous === null || index === previous) return;
       nearest.value = index;
-      runOnJS(selectionTick)();
+      if (haptics) runOnJS(selectionTick)();
+      if (onColumnChange !== undefined) runOnJS(report)(index);
     }
   );
 }
@@ -184,10 +203,18 @@ const TimelineColumnOffsetContext = createContext<number | null>(null);
  *
  * 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.
+ * rather than to position the rail against measured content.
+ *
+ * So the *column* reserves it, as padding, and the rail is drawn once across
+ * the whole track at that offset. Each column's tick is the first thing after
+ * the padding and is pulled up by half its own height to straddle the line.
+ *
+ * `Timeline.Aside` fills that band with a negative margin equal to its own
+ * height: it draws inside the reserved strip and takes no flow height of its
+ * own. That is what makes it optional. Reserved by the aside instead, a column
+ * without one put its tick at the top of the column and 64 points above the
+ * rail — which is not a mistake anyone makes twice, but is also not a mistake
+ * the component should let anyone make once.
  */
 const HORIZONTAL_RAIL_TOP = 64;
 const HORIZONTAL_TICK_HEIGHT = 10;
@@ -239,6 +266,25 @@ const timelineVariants = tv({
     stats: 'mt-2 flex-row gap-6 rounded-xl border border-border px-3.5 py-2.5',
     statLabel: 'text-xs text-muted-foreground',
     statValue: 'text-sm font-medium text-foreground',
+    /*
+     * The masthead over a horizontal rail: what the run of columns is, said
+     * once, above them.
+     *
+     * `gap-0` between the two lines and tight leading on both, because they
+     * are one thing rather than two — a label and the name it introduces. Set
+     * a step apart with a normal paragraph gap they read as a small heading
+     * followed by a bigger unrelated one, which is what the pair looked like
+     * before.
+     *
+     * The label is a size below the title and muted rather than the same size
+     * in a lighter weight: at the same size the eye reads the grey one first
+     * because it is on the left of the taller one, and the name — the part
+     * anybody is actually looking for — arrives second.
+     */
+    masthead: 'gap-2',
+    mastheadMedia: 'flex-row items-center',
+    mastheadLabel: 'text-lg font-medium leading-tight text-muted-foreground',
+    mastheadTitle: 'text-2xl font-semibold leading-tight text-foreground',
   },
   variants: {
     variant: {
@@ -280,10 +326,25 @@ const timelineVariants = tv({
       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',
+        aside: 'w-auto items-start justify-end gap-0 pb-2 pt-0',
+        // Reserved by the column, not by whatever it happens to contain.
         rail: 'w-full items-start',
         body: 'w-auto flex-none pb-0 pt-5',
         title: 'text-sm',
+        /*
+         * A column's date is its name, not a caption on it. At `text-xs` next
+         * to a `text-xs` meta line the two were a two-line grey block and the
+         * year — the only thing distinguishing one column from the next — had
+         * to be looked for. The meta line stays small above it and the pair
+         * closes up, so they read as one label with an eyebrow rather than as
+         * two.
+         *
+         * Colour is left alone: `useColumnInk` animates it per column so the
+         * one you have landed on is the one in full ink, and a colour in the
+         * class would be overridden by that anyway.
+         */
+        date: 'text-sm font-semibold leading-tight',
+        meta: 'text-[11px] font-medium leading-tight',
       },
     },
   },
@@ -416,6 +477,24 @@ export interface TimelineProps extends ViewProps {
    * whether this one is worth feeling is the caller's call.
    */
   haptics?: boolean;
+  /**
+   * Horizontal only: which column is at the reading edge, reported as it
+   * changes.
+   *
+   * For anything outside the rail that belongs to the column being read — a
+   * masthead naming it, a caption, a picture. Without it that block can only
+   * show the same thing for the whole run, which makes a swipe through ten
+   * columns a swipe under one unchanging heading.
+   *
+   * The index is the column's position among the rendered items, not its
+   * `step`: `step` is the progress value and may be sparse or repeated, so it
+   * cannot address a column.
+   *
+   * It fires on the crossing, not per frame — the reading edge passing from
+   * one column to the next — so it is a state update per column rather than
+   * per scroll event.
+   */
+  onColumnChange?: (index: number) => void;
   children?: ReactNode;
 }
 
@@ -428,6 +507,7 @@ const TimelineRoot = forwardRef<View, TimelineProps>(
       orientation = 'vertical',
       snap = true,
       haptics = false,
+      onColumnChange,
       children,
       ...props
     },
@@ -484,7 +564,7 @@ const TimelineRoot = forwardRef<View, TimelineProps>(
       scrollX.value = event.contentOffset.x;
     });
 
-    useColumnDetent(scrollX, offsets, horizontal && snap && haptics);
+    useColumnDetent(scrollX, offsets, horizontal && snap && haptics, horizontal ? onColumnChange : undefined);
 
     if (!horizontal) {
       return (
@@ -777,7 +857,13 @@ const TimelineItem = forwardRef<View, TimelineItemProps>(
           ref={ref}
           className={item({ className })}
           {...props}
-          style={[style, { width: columnWidth }, columnStyle]}
+          style={[
+            style,
+            // The band above the rail, reserved whether or not this column
+            // writes a `Timeline.Aside` into it.
+            { width: columnWidth, paddingTop: HORIZONTAL_RAIL_TOP },
+            columnStyle,
+          ]}
         >
           {virtualized && !last ? (
             <View
@@ -817,14 +903,15 @@ const TimelineAside = forwardRef<View, ViewProps & { className?: string }>(
         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.
+         * Horizontal: this draws *into* the band the column has already
+         * reserved, rather than being the thing that reserves it — hence the
+         * negative margin cancelling its own height. A column with a longer
+         * label therefore cannot push its own tick below everybody else's, and
+         * a column with no aside at all still has its tick on the rail.
          */
         style={
           orientation === 'horizontal'
-            ? [{ height: HORIZONTAL_RAIL_TOP }, style]
+            ? [{ height: HORIZONTAL_RAIL_TOP, marginTop: -HORIZONTAL_RAIL_TOP }, style]
             : style
         }
         {...props}
@@ -1104,10 +1191,74 @@ const TimelineStat = forwardRef<View, TimelineStatProps>(
 );
 TimelineStat.displayName = 'Timeline.Stat';
 
+export interface TimelineMastheadProps extends ViewProps {
+  className?: string;
+  /**
+   * What sits above the two lines — a logo pair, an avatar stack, a single
+   * mark. Anything; the slot only lays it out in a row.
+   */
+  media?: ReactNode;
+  /** The small line: what kind of thing the run below is. */
+  label?: string;
+  /** The name of it, in the size the eye lands on first. */
+  title?: string;
+  /** Anything else, below the title. */
+  children?: ReactNode;
+}
+
+/**
+ * The block above a horizontal rail, saying what the run of columns is.
+ *
+ * Media, then a small label, then the name — the order a reader takes them in
+ * anyway, and the reason it is a part rather than two `Text`s at every call
+ * site: the pair has to be typeset as one unit, and a masthead written by hand
+ * is a heading above another heading.
+ *
+ * ```tsx
+ * <Timeline.Masthead
+ *   media={
+ *     <Avatar.Group size="sm">
+ *       <Avatar fallback="A"><AppleIcon size={18} /></Avatar>
+ *     </Avatar.Group>
+ *   }
+ *   label="Built for"
+ *   title="iOS and Android"
+ * />
+ *
+ * <Timeline orientation="horizontal">…</Timeline>
+ * ```
+ *
+ * It sits outside the `Timeline`, above it, because it belongs to the whole
+ * run rather than to any column in it — and a column is the only thing a
+ * horizontal `Timeline` lays out.
+ */
+const TimelineMasthead = forwardRef<View, TimelineMastheadProps>(
+  ({ className, media, label, title, children, ...props }, ref) => {
+    const { masthead, mastheadMedia, mastheadLabel, mastheadTitle } = timelineVariants({
+      orientation: 'horizontal',
+    });
+
+    return (
+      <View ref={ref} className={masthead({ className })} {...props}>
+        {media ? <View className={mastheadMedia()}>{media}</View> : null}
+        {label !== undefined || title !== undefined ? (
+          <View>
+            {label !== undefined ? <Text className={mastheadLabel()}>{label}</Text> : null}
+            {title !== undefined ? <Text className={mastheadTitle()}>{title}</Text> : null}
+          </View>
+        ) : null}
+        {children}
+      </View>
+    );
+  }
+);
+TimelineMasthead.displayName = 'Timeline.Masthead';
+
 export const Timeline = Object.assign(TimelineRoot, {
   List: TimelineList,
   Item: TimelineItem,
   Aside: TimelineAside,
+  Masthead: TimelineMasthead,
   Indicator: TimelineIndicator,
   Content: TimelineContent,
   Header: TimelineHeader,

package/src/index.ts

@@ -884,6 +884,9 @@ export {
   type QRCodeContentProps,
   type QRCodeSize,
   type QRCodePresentation,
+  type QRCodeModuleShape,
+  type QRCodeEyeFrameShape,
+  type QRCodeEyeBallShape,
   type ErrorCorrectionLevel,
 } from './components/qr-code';
 export {