panelui-native 0.77.0 → 0.79.0

package/src/components/marquee/index.tsx

@@ -44,7 +44,17 @@
  * Screen readers get one copy. The rest are duplicates of content already
  * announced, and hearing a sponsor list four times over is not thoroughness.
  */
-import { useEffect, useMemo, useState, type ComponentType, type ReactNode } from 'react';
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useId,
+  useMemo,
+  useState,
+  type ComponentType,
+  type ReactNode,
+} from 'react';
 import {
   Platform,
   Pressable,
@@ -61,6 +71,7 @@ import Animated, {
   useReducedMotion,
   useSharedValue,
   withRepeat,
+  withSequence,
   withTiming,
 } from 'react-native-reanimated';
 import { useDirectionSign } from '../../hooks/use-direction';
@@ -99,7 +110,13 @@ export interface MarqueeProps extends Omit<ViewProps, 'children'> {
   reverse?: boolean;
   /** Set false to hold the content where it is. */
   playing?: boolean;
-  /** Show the built-in user pause/play control while motion is enabled. */
+  /**
+   * Show the built-in user pause/play control while motion is enabled.
+   *
+   * Defaults to `true` on its own, and to `false` inside a `Marquee.Group` —
+   * the group draws one control for everything in it, and a control per row is
+   * how two of them end up stacked on top of each other.
+   */
   showPauseControl?: boolean;
   /** Visible and spoken label for the moving state. */
   pauseLabel?: string;
@@ -109,7 +126,27 @@ export interface MarqueeProps extends Omit<ViewProps, 'children'> {
   onPlayingChange?: (playing: boolean) => void;
 }
 
-export function Marquee({
+/**
+ * Set by `Marquee.Group` so the marquees inside it stop drawing a pause control
+ * each and take the group's instead.
+ */
+interface MarqueeGroupContextValue {
+  /** True while the group's control is holding everything in it still. */
+  paused: boolean;
+  /**
+   * How a marquee inside the group reports whether it has a loop to stop.
+   *
+   * The group draws one control for everything in it, and it should not offer
+   * to pause content that never measured — the failure mode a marquee already
+   * has, where a child with no intrinsic size never starts. Only the marquees
+   * themselves know that, so they say so.
+   */
+  report: (id: string, live: boolean) => void;
+}
+
+const MarqueeGroupContext = createContext<MarqueeGroupContextValue | null>(null);
+
+function MarqueeRoot({
   className,
   children,
   speed: speedProp = DEFAULT_MARQUEE_SPEED,
@@ -117,7 +154,7 @@ export function Marquee({
   direction = 'horizontal',
   reverse = false,
   playing = true,
-  showPauseControl = true,
+  showPauseControl,
   pauseLabel = 'Pause',
   playLabel = 'Play',
   onPlayingChange,
@@ -135,7 +172,13 @@ export function Marquee({
   const [content, setContent] = useState(0);
   const [userPaused, setUserPaused] = useState(false);
   const speed = normalizeMarqueeSpeed(speedProp);
-  const moving = playing && !userPaused;
+
+  // A group's pause is the same instruction as this one's, so it is read here
+  // rather than pushed down as a `playing` prop — a caller who set `playing`
+  // themselves should not have it overwritten by the container.
+  const group = useContext(MarqueeGroupContext);
+  const showControl = showPauseControl ?? group === null;
+  const moving = playing && !userPaused && !(group?.paused ?? false);
 
   // The distance from one copy to the same point on the next, and therefore
   // both the layout step and the exact loop length. They are the same number
@@ -154,18 +197,43 @@ export function Marquee({
 
   const offset = useSharedValue(0);
 
+  /*
+   * A re-measure is the only thing allowed to move the content back to the
+   * start. The loop length has changed, so an offset taken against the old one
+   * no longer means anything.
+   */
   useEffect(() => {
     cancelAnimation(offset);
     offset.value = 0;
+  }, [offset, period]);
+
+  /*
+   * Pausing freezes where it is. `cancelAnimation` already leaves the shared
+   * value at whatever it had reached, so stopping is simply not starting again
+   * — the content stays exactly where the reader stopped it, which is the
+   * whole point of a pause control on something they are trying to read.
+   *
+   * Resuming picks up from there. The first leg is shortened to the distance
+   * actually left, or the lap after a pause would run at a fraction of the
+   * speed every other lap runs at.
+   */
+  useEffect(() => {
+    cancelAnimation(offset);
     if (reducedMotion || !moving || period <= 0 || speed <= 0) return undefined;
-    offset.value = withRepeat(
-      withTiming(period, {
-        duration: (period / speed) * 1000,
-        easing: Easing.linear,
-      }),
-      -1,
-      false
+
+    const cycle = (period / speed) * 1000;
+    const from = ((offset.value % period) + period) % period;
+    const remaining = period - from;
+
+    offset.value = from;
+    offset.value = withSequence(
+      withTiming(period, { duration: cycle * (remaining / period), easing: Easing.linear }),
+      // Back to the seam in no time at all. The state at `period` is the state
+      // at `0`, so this is a bookkeeping step rather than a visible one.
+      withTiming(0, { duration: 0 }),
+      withRepeat(withTiming(period, { duration: cycle, easing: Easing.linear }), -1, false)
     );
+
     return () => cancelAnimation(offset);
   }, [offset, period, moving, reducedMotion, speed]);
 
@@ -189,6 +257,24 @@ export function Marquee({
     setContent(horizontal ? width : height);
   };
 
+  /*
+   * Whether there is motion here at all: content that measured, a speed to
+   * travel it at, and a `playing` that has not already stopped it from
+   * outside. A control offering to pause a still marquee is the same lie as a
+   * disabled button with no reason on it.
+   */
+  const live = playing && !reducedMotion && period > 0 && speed > 0;
+
+  // Reported to the group, if there is one, so its single control can be
+  // decided the same way this one's is.
+  const id = useId();
+  const report = group?.report;
+  useEffect(() => {
+    if (!report) return undefined;
+    report(id, live);
+    return () => report(id, false);
+  }, [report, id, live]);
+
   // Nothing to loop, so nothing to clip or clone: render the content plainly
   // and let it sit where it falls.
   if (reducedMotion) {
@@ -205,56 +291,61 @@ export function Marquee({
   }
 
   return (
-    <View
-      className={cn('overflow-hidden', className)}
-      style={style}
-      onLayout={onContainerLayout}
-      {...props}
-    >
-      {/* Measured, never seen. A scroller on this axis is what frees the
-          content to report its own size instead of the container's. */}
-      <ScrollView
-        horizontal={horizontal}
-        scrollEnabled={false}
-        style={styles.measure}
-        pointerEvents="none"
-        accessibilityElementsHidden
-        importantForAccessibility="no-hide-descendants"
-      >
-        <InertView
-          inert={Platform.OS === 'web' ? true : undefined}
-          onLayout={onContentLayout}
+    <View className={cn('gap-3', className)} style={style} onLayout={onLayout} {...props}>
+      {/* The track, and only the track. The control below it is not clipped by
+          this and does not travel with it. */}
+      <View className="flex-1 overflow-hidden" onLayout={onContainerLayout}>
+        {/* Measured, never seen. A scroller on this axis is what frees the
+            content to report its own size instead of the container's. */}
+        <ScrollView
+          horizontal={horizontal}
+          scrollEnabled={false}
+          style={styles.measure}
+          pointerEvents="none"
+          accessibilityElementsHidden
+          importantForAccessibility="no-hide-descendants"
         >
-          {children}
-        </InertView>
-      </ScrollView>
-
-      <Animated.View style={[StyleSheet.absoluteFill, trackStyle]} pointerEvents="box-none">
-        {copies.map((index) => {
-          // Index 1 is the copy that starts flush with the container's edge,
-          // and it is the one a screen reader is given.
-          const spoken = index === 1;
-          const at = (index - 1) * period;
-          return (
-            <InertView
-              key={index}
-              style={[styles.copy, horizontal ? { left: at } : { top: at }]}
-              pointerEvents={spoken ? 'box-none' : 'none'}
-              inert={Platform.OS === 'web' && !spoken ? true : undefined}
-              aria-hidden={!spoken}
-              accessibilityElementsHidden={!spoken}
-              importantForAccessibility={spoken ? 'auto' : 'no-hide-descendants'}
-            >
-              {children}
-            </InertView>
-          );
-        })}
-      </Animated.View>
-      {showPauseControl && playing && period > 0 && speed > 0 ? (
+          <InertView
+            inert={Platform.OS === 'web' ? true : undefined}
+            onLayout={onContentLayout}
+          >
+            {children}
+          </InertView>
+        </ScrollView>
+
+        <Animated.View style={[StyleSheet.absoluteFill, trackStyle]} pointerEvents="box-none">
+          {copies.map((index) => {
+            // Index 1 is the copy that starts flush with the container's edge,
+            // and it is the one a screen reader is given.
+            const spoken = index === 1;
+            const at = (index - 1) * period;
+            return (
+              <InertView
+                key={index}
+                style={[styles.copy, horizontal ? { left: at } : { top: at }]}
+                pointerEvents={spoken ? 'box-none' : 'none'}
+                inert={Platform.OS === 'web' && !spoken ? true : undefined}
+                aria-hidden={!spoken}
+                accessibilityElementsHidden={!spoken}
+                importantForAccessibility={spoken ? 'auto' : 'no-hide-descendants'}
+              >
+                {children}
+              </InertView>
+            );
+          })}
+        </Animated.View>
+      </View>
+      {showControl && live ? (
         <Pressable
           accessibilityRole="button"
           accessibilityLabel={userPaused ? playLabel : pauseLabel}
-          className="absolute bottom-2 end-2 min-h-12 min-w-12 items-center justify-center rounded-full border border-border bg-background/95 px-3"
+          /*
+           * Below the content, in flow, the way a group's control already is.
+           * Floating over the track it was clipped by the track's own
+           * `overflow-hidden` — a 48pt target on a strip of badges half that
+           * tall — and it covered the content it was there to let you read.
+           */
+          className="min-h-12 self-end items-center justify-center rounded-full border border-border bg-background px-4"
           onPress={() => {
             const next = !userPaused;
             setUserPaused(next);
@@ -270,6 +361,111 @@ export function Marquee({
   );
 }
 
+export interface MarqueeGroupProps extends ViewProps {
+  className?: string;
+  /** Set false to hold every marquee in the group where it is. */
+  playing?: boolean;
+  /** Show the group's pause/play control. */
+  showPauseControl?: boolean;
+  /** Visible and spoken label for the moving state. */
+  pauseLabel?: string;
+  /** Visible and spoken label for the user-paused state. */
+  playLabel?: string;
+  /** Reports changes made by the group's control. */
+  onPlayingChange?: (playing: boolean) => void;
+  children?: ReactNode;
+}
+
+/**
+ * Rows of travelling content that stop and start together, under one control.
+ *
+ * Moving content needs a way to stop it, so a marquee draws its own pause
+ * button. Stacked — two rows of logos travelling against each other — that is
+ * one button per row, each pinned to its own bottom corner, and the upper one
+ * lands on top of the row beneath it. Two buttons for one piece of motion, and
+ * one of them covering the content it belongs to.
+ *
+ * A group is the answer to both: the marquees inside it stop drawing their own
+ * control, and the group draws a single one below them rather than over them.
+ *
+ * ```tsx
+ * <Marquee.Group>
+ *   <Marquee>{topRow}</Marquee>
+ *   <Marquee reverse>{bottomRow}</Marquee>
+ * </Marquee.Group>
+ * ```
+ *
+ * Each marquee keeps its own `playing` prop. The group's pause is an additional
+ * hold, not a replacement — a row already held still stays still.
+ */
+function MarqueeGroup({
+  className,
+  children,
+  playing = true,
+  showPauseControl = true,
+  pauseLabel = 'Pause',
+  playLabel = 'Play',
+  onPlayingChange,
+  ...props
+}: MarqueeGroupProps) {
+  const [userPaused, setUserPaused] = useState(false);
+  const [liveRows, setLiveRows] = useState<ReadonlySet<string>>(() => new Set());
+  const reducedMotion = useReducedMotion();
+
+  // Each marquee inside says whether it has a loop to stop, and the group's
+  // control is drawn only if at least one of them does.
+  const report = useCallback((id: string, live: boolean) => {
+    setLiveRows((current) => {
+      if (current.has(id) === live) return current;
+      const next = new Set(current);
+      if (live) next.add(id);
+      else next.delete(id);
+      return next;
+    });
+  }, []);
+
+  const value = useMemo(() => ({ paused: userPaused, report }), [userPaused, report]);
+
+  // Nothing is moving, so there is nothing to stop. The control is not hidden
+  // to save space — offering to pause content that is already still is the
+  // same lie as a disabled button with no reason on it.
+  const showControl = showPauseControl && playing && !reducedMotion && liveRows.size > 0;
+
+  return (
+    <MarqueeGroupContext.Provider value={value}>
+      <View {...props} className={cn('w-full gap-3', className)}>
+        {children}
+        {showControl ? (
+          <Pressable
+            accessibilityRole="button"
+            accessibilityLabel={userPaused ? playLabel : pauseLabel}
+            // In flow and at the end, not floating over the last row. The
+            // control belongs to the group, and a group's control that covers
+            // one of its members is describing itself as part of that member.
+            className="min-h-12 self-end items-center justify-center rounded-full border border-border bg-background px-4"
+            onPress={() => {
+              const next = !userPaused;
+              setUserPaused(next);
+              onPlayingChange?.(!next);
+            }}
+          >
+            <Text className="text-xs font-medium text-foreground">
+              {userPaused ? playLabel : pauseLabel}
+            </Text>
+          </Pressable>
+        ) : null}
+      </View>
+    </MarqueeGroupContext.Provider>
+  );
+}
+MarqueeGroup.displayName = 'Marquee.Group';
+
+MarqueeRoot.displayName = 'Marquee';
+
+export const Marquee = Object.assign(MarqueeRoot, {
+  Group: MarqueeGroup,
+});
+
 const styles = StyleSheet.create({
   /* Laid out so it measures, hidden so it does not draw, and behind everything
      so it can never intercept anything. */

package/src/components/panelside/index.tsx

@@ -119,7 +119,7 @@ import { LinearGradient } from 'expo-linear-gradient';
 import { EllipsisIcon, IconColorProvider, MenuIcon, SearchIcon } from '../../icons';
 import { Button } from '../button';
 import { AnimatedPressable } from '../../primitives/animated-pressable';
-import { Text, textChildren } from '../../primitives/text';
+import { Text, textChildren, type TextProps } from '../../primitives/text';
 import { useBackHandler } from '../../hooks/use-back-handler';
 import { useDirectionSign } from '../../hooks/use-direction';
 import { cn } from '../../utils/cn';
@@ -888,17 +888,47 @@ function PanelsideGroupLabel({ className, children, ...props }: PanelsideGroupLa
   );
 }
 
+/**
+ * What a row's parts read off the row, rather than being handed it.
+ *
+ * A label goes medium and un-muted when the row is the current destination,
+ * and an icon takes the matching tint. Passing that to every part would mean
+ * `<Panelside.ItemLabel active={active}>` at every call site, with an `active`
+ * that has to be kept in step with the row's own.
+ */
+interface PanelsideItemContextValue {
+  active: boolean;
+  disabled: boolean;
+  size: PanelsideItemSize;
+  /** The colour an icon in this row should take, resolved once by the row. */
+  tint: string | undefined;
+}
+
+const PanelsideItemContext = createContext<PanelsideItemContextValue | null>(null);
+
+function usePanelsideItem(part: string): PanelsideItemContextValue {
+  const value = useContext(PanelsideItemContext);
+  if (!value) throw new Error(`${part} must be used inside a <Panelside.Item>.`);
+  return value;
+}
+
 export interface PanelsideItemProps extends Omit<PressableProps, 'children'> {
   className?: string;
-  /** Leading element — an icon, an avatar, a coloured dot. */
+  /**
+   * Leading element — an icon, an avatar, a coloured dot. The shorthand for
+   * `Panelside.ItemIcon`.
+   */
   icon?: ReactNode;
-  /** The row's text. Truncated to one line, since chat titles run long. */
+  /**
+   * The row's text, truncated to one line since chat titles run long. The
+   * shorthand for `Panelside.ItemLabel`.
+   */
   label?: string;
   /** Marks the row as the current destination. */
   active?: boolean;
   /**
    * Trailing count or status. A number or string renders as a pill; anything
-   * else renders as given.
+   * else renders as given. The shorthand for `Panelside.ItemBadge`.
    */
   badge?: ReactNode;
   disabled?: boolean;
@@ -908,10 +938,37 @@ export interface PanelsideItemProps extends Omit<PressableProps, 'children'> {
    * worth more than two extra rows.
    */
   size?: PanelsideItemSize;
-  /** Trailing content — usually a `Panelside.Action`. */
+  /**
+   * The row's contents, written out: `Panelside.ItemIcon`,
+   * `Panelside.ItemLabel`, `Panelside.ItemBadge` and `Panelside.Action`, in
+   * whatever order the row wants them. Anything else you draw works too.
+   *
+   * Children and the shorthand props compose — a row can take its label from
+   * `label` and still write a trailing `Panelside.Action` as a child.
+   */
   children?: ReactNode;
 }
 
+/**
+ * One destination, or one conversation.
+ *
+ * There are two ways to fill it, and they are the same row. The shorthand —
+ * `icon`, `label`, `badge` — covers the row every navigation panel has, and is
+ * what most call sites should use. The parts cover everything else: two lines
+ * of text, a label that is not a string, a badge before the label rather than
+ * after it, a trailing control that is not an overflow menu.
+ *
+ * ```tsx
+ * <Panelside.Item icon={<InboxIcon />} label="Inbox" badge={12} />
+ *
+ * <Panelside.Item active>
+ *   <Panelside.ItemIcon><Avatar size="xs" src={author.avatar} /></Panelside.ItemIcon>
+ *   <Panelside.ItemLabel>{thread.title}</Panelside.ItemLabel>
+ *   <Panelside.ItemBadge>{thread.unread}</Panelside.ItemBadge>
+ *   <Panelside.Action onPress={rename} />
+ * </Panelside.Item>
+ * ```
+ */
 function PanelsideItem({
   className,
   icon,
@@ -934,46 +991,122 @@ function PanelsideItem({
       ? restTint
       : undefined;
 
+  const context = useMemo<PanelsideItemContextValue>(
+    () => ({ active, disabled, size, tint }),
+    [active, disabled, size, tint]
+  );
+
+  /*
+   * The row needs something flexible in the middle or its trailing content
+   * floats next to the icon instead of sitting at the end. A label supplies
+   * that, and a written-out `Panelside.ItemLabel` supplies it too — so the
+   * spacer is only for the row that has neither, which is a row of nothing but
+   * an icon and a badge.
+   */
+  const filled = label !== undefined || children !== undefined;
+
   return (
-    <AnimatedPressable
-      className={itemVariants({ active, disabled, size, className })}
-      disabled={disabled}
-      accessibilityRole="button"
-      accessibilityState={{ selected: active, disabled }}
-      accessibilityLabel={label}
-      pressScale={0.985}
+    <PanelsideItemContext.Provider value={context}>
+      <AnimatedPressable
+        className={itemVariants({ active, disabled, size, className })}
+        disabled={disabled}
+        accessibilityRole="button"
+        accessibilityState={{ selected: active, disabled }}
+        accessibilityLabel={label}
+        pressScale={0.985}
+        {...props}
+      >
+        {icon ? <PanelsideItemIcon>{icon}</PanelsideItemIcon> : null}
+
+        {label !== undefined ? <PanelsideItemLabel>{label}</PanelsideItemLabel> : null}
+
+        {filled ? null : <View className="flex-1" />}
+
+        {badge !== undefined && badge !== null ? (
+          <PanelsideItemBadge>{badge}</PanelsideItemBadge>
+        ) : null}
+
+        {children}
+      </AnimatedPressable>
+    </PanelsideItemContext.Provider>
+  );
+}
+
+export interface PanelsideItemIconProps extends ViewProps {
+  className?: string;
+  children?: ReactNode;
+}
+
+/**
+ * The leading slot on a row.
+ *
+ * Whatever is inside it inherits the row's own tint rather than each call site
+ * passing a colour that stops being right the moment the row goes active.
+ */
+function PanelsideItemIcon({ className, children, ...props }: PanelsideItemIconProps) {
+  const { tint } = usePanelsideItem('Panelside.ItemIcon');
+
+  // No wrapper unless one was asked for: an icon is already the right size,
+  // and a `View` around it is a layout node between the row and its glyph.
+  if (className === undefined && Object.keys(props).length === 0) {
+    return <IconColorProvider color={tint}>{children}</IconColorProvider>;
+  }
+
+  return (
+    <View className={className} {...props}>
+      <IconColorProvider color={tint}>{children}</IconColorProvider>
+    </View>
+  );
+}
+
+export interface PanelsideItemLabelProps extends TextProps {
+  className?: string;
+  children?: ReactNode;
+}
+
+/**
+ * The row's text. It takes the flexible middle, so a long title truncates
+ * rather than pushing the badge and the action off the end of the panel.
+ */
+function PanelsideItemLabel({ className, children, ...props }: PanelsideItemLabelProps) {
+  const { active } = usePanelsideItem('Panelside.ItemLabel');
+
+  return (
+    <Text
+      size="base"
+      weight={active ? 'medium' : 'normal'}
+      muted={!active}
+      numberOfLines={1}
+      className={cn('flex-1', className)}
       {...props}
     >
-      {/* Icons inherit the row's state rather than each caller passing a
-          colour that stops being right the moment the row goes active. */}
-      {icon ? <IconColorProvider color={tint}>{icon}</IconColorProvider> : null}
-
-      {label ? (
-        <Text
-          size="base"
-          weight={active ? 'medium' : 'normal'}
-          muted={!active}
-          numberOfLines={1}
-          className="flex-1"
-        >
-          {label}
-        </Text>
-      ) : (
-        <View className="flex-1" />
-      )}
+      {children}
+    </Text>
+  );
+}
 
-      {typeof badge === 'string' || typeof badge === 'number' ? (
-        <View className="rounded-full bg-secondary px-2 py-0.5">
-          <Text size="xs" muted>
-            {badge}
-          </Text>
-        </View>
-      ) : (
-        badge
-      )}
+export interface PanelsideItemBadgeProps extends ViewProps {
+  className?: string;
+  children?: ReactNode;
+}
 
-      {children}
-    </AnimatedPressable>
+/**
+ * The trailing count or status on a row. Text becomes a pill; anything else is
+ * drawn as given, so a dot or a chip needs no opting out of the pill.
+ */
+function PanelsideItemBadge({ className, children, ...props }: PanelsideItemBadgeProps) {
+  usePanelsideItem('Panelside.ItemBadge');
+
+  if (typeof children !== 'string' && typeof children !== 'number') {
+    return <>{children}</>;
+  }
+
+  return (
+    <View className={cn('rounded-full bg-secondary px-2 py-0.5', className)} {...props}>
+      <Text size="xs" muted>
+        {children}
+      </Text>
+    </View>
   );
 }
 
@@ -1456,6 +1589,9 @@ PanelsideContent.displayName = 'Panelside.Content';
 PanelsideGroup.displayName = 'Panelside.Group';
 PanelsideGroupLabel.displayName = 'Panelside.GroupLabel';
 PanelsideItem.displayName = 'Panelside.Item';
+PanelsideItemIcon.displayName = 'Panelside.ItemIcon';
+PanelsideItemLabel.displayName = 'Panelside.ItemLabel';
+PanelsideItemBadge.displayName = 'Panelside.ItemBadge';
 PanelsideAction.displayName = 'Panelside.Action';
 PanelsideFooter.displayName = 'Panelside.Footer';
 PanelsideCta.displayName = 'Panelside.Cta';
@@ -1470,6 +1606,9 @@ export const Panelside = Object.assign(PanelsideRoot, {
   Group: PanelsideGroup,
   GroupLabel: PanelsideGroupLabel,
   Item: PanelsideItem,
+  ItemIcon: PanelsideItemIcon,
+  ItemLabel: PanelsideItemLabel,
+  ItemBadge: PanelsideItemBadge,
   Action: PanelsideAction,
   Footer: PanelsideFooter,
   Cta: PanelsideCta,