panelui-native 0.68.0 → 0.73.0

package/src/components/live-line-chart/index.tsx

@@ -30,10 +30,17 @@
  * they mean opposite things.
  *
  * The cost is a frame callback for as long as the chart is mounted. It is
- * stopped by `paused`, by `status="loading"` and on unmount, and it is never
- * started when the platform asks for reduced motion — in that case the window
- * advances as each point arrives instead, which is the same picture sampled
- * less often.
+ * stopped by `paused`, by `status="loading"`, while the app is backgrounded
+ * and on unmount, and it is never started when the platform asks for reduced
+ * motion — in that case the window advances as each point arrives instead,
+ * which is the same picture sampled less often.
+ *
+ * Screen readers receive one image-role snapshot: its name, current or
+ * selected value, direction, time window and paused state. It changes when the
+ * React data changes, never on the UI-thread clock frame, and requests no live
+ * announcement. The visual axes, badges and tooltip repeat that snapshot and
+ * stay out of the accessibility tree; controls placed in Header remain normal
+ * controls.
  *
  * ## Colour follows the recent direction
  *
@@ -56,7 +63,13 @@ import {
   useState,
   type ReactNode,
 } from 'react';
-import { StyleSheet, View, type LayoutChangeEvent, type ViewProps } from 'react-native';
+import {
+  AppState,
+  StyleSheet,
+  View,
+  type LayoutChangeEvent,
+  type ViewProps,
+} from 'react-native';
 import { Gesture, GestureDetector } from 'react-native-gesture-handler';
 import Animated, {
   runOnJS,
@@ -92,6 +105,13 @@ import {
   type Plot,
 } from '../../utils/chart';
 import { cn } from '../../utils/cn';
+import { liveLineAccessibility } from './live-line-accessibility';
+import {
+  liveLineClockRuns,
+  normalizeLiveLinePoints,
+  normalizeLiveLineWindow,
+  reconcileLiveLineActivePoint,
+} from './live-line-lifecycle';
 
 const AnimatedPath = Animated.createAnimatedComponent(Path);
 
@@ -224,9 +244,16 @@ function runOf(
 
 export interface LiveLineChartProps extends ViewProps {
   className?: string;
-  /** The readings so far, oldest first. Append to it as they arrive. */
+  /**
+   * Names the chart's single screen-reader snapshot. Falls back to the Header
+   * title, then to "Live line chart".
+   */
+  accessibilityLabel?: string;
+  /** Additional guidance after the snapshot. No gesture is invented for it. */
+  accessibilityHint?: string;
+  /** The readings so far. Invalid values are dropped and timestamps are ordered. */
   data: LiveLinePoint[];
-  /** How much time the plot spans, in seconds. */
+  /** How much time the plot spans, in seconds. Invalid values use 30. */
   window?: number;
   /** Freeze the window where it is. The readings still arrive; the clock stops. */
   paused?: boolean;
@@ -239,7 +266,7 @@ export interface LiveLineChartProps extends ViewProps {
   /**
    * The most readings kept. Older ones are dropped, since they are off the
    * window and cannot come back — an unbounded feed otherwise grows an array
-   * for as long as the screen is open.
+   * for as long as the screen is open. Must be positive and finite.
    */
   maxPoints?: number;
   /** Width ÷ height of the plot. */
@@ -276,6 +303,8 @@ const LiveLineChartRoot = forwardRef<LiveLineChartHandle, LiveLineChartProps>(
       momentumColors,
       color,
       onActivePointChange,
+      accessibilityLabel,
+      accessibilityHint,
       children,
       ...props
     },
@@ -290,12 +319,13 @@ const LiveLineChartRoot = forwardRef<LiveLineChartHandle, LiveLineChartProps>(
     const domainMax = useSharedValue(0);
     const activeTime = useSharedValue(-1);
     const reducedMotion = useReducedMotion();
+    const [appState, setAppState] = useState(AppState.currentState ?? 'active');
     // Stripped of punctuation: `useId` returns something like `:r1:`, and a
     // colon inside a `url(#…)` reference does not resolve — which in RN SVG is
     // a clip that silently does nothing rather than an error.
     const clipId = `panelui-live-clip-${useId().replace(/[^a-zA-Z0-9]/g, '')}`;
 
-    const windowMs = Math.max(windowSeconds, 1) * 1000;
+    const windowMs = normalizeLiveLineWindow(windowSeconds) * 1000;
     const loading = status === 'loading';
 
     const hasYAxis = useMemo(() => {
@@ -308,6 +338,34 @@ const LiveLineChartRoot = forwardRef<LiveLineChartHandle, LiveLineChartProps>(
       return found;
     }, [children]);
 
+    const semanticParts = useMemo(() => {
+      let title: string | undefined;
+      let value: string | undefined;
+      let headerFormat: ((reading: number) => string) | undefined;
+      let tipFormat: ((reading: number) => string) | undefined;
+      let tooltipFormat: ((reading: number) => string) | undefined;
+      Children.forEach(children, (child) => {
+        if (!isValidElement(child)) return;
+        const part = (child.type as { displayName?: string }).displayName;
+        if (part === 'LiveLineChart.Header') {
+          const header = child.props as LiveLineChartHeaderProps;
+          title ??= header.title;
+          value ??= header.value;
+          headerFormat ??= header.formatValue;
+        } else if (part === 'LiveLineChart.Tip') {
+          tipFormat ??= (child.props as LiveLineChartTipProps).formatValue;
+        } else if (part === 'LiveLineChart.Tooltip') {
+          tooltipFormat ??= (child.props as LiveLineChartTooltipProps).formatValue;
+        }
+      });
+      return {
+        title,
+        value,
+        formatLatest: headerFormat ?? tipFormat,
+        formatActive: tooltipFormat ?? headerFormat ?? tipFormat,
+      };
+    }, [children]);
+
     const pad = { ...PADDING, left: hasYAxis ? Y_AXIS_WIDTH : PADDING.left };
     const plot: Plot = {
       left: pad.left,
@@ -322,7 +380,7 @@ const LiveLineChartRoot = forwardRef<LiveLineChartHandle, LiveLineChartProps>(
      * the one chart nobody bounded to be the one left running overnight.
      */
     const points = useMemo(
-      () => (data.length > maxPoints ? data.slice(data.length - maxPoints) : data),
+      () => normalizeLiveLinePoints(data, maxPoints),
       [data, maxPoints]
     );
 
@@ -331,6 +389,11 @@ const LiveLineChartRoot = forwardRef<LiveLineChartHandle, LiveLineChartProps>(
       values.value = points.map((point) => point.value);
     }, [points, times, values]);
 
+    useEffect(() => {
+      const subscription = AppState.addEventListener('change', setAppState);
+      return () => subscription.remove();
+    }, []);
+
     const liveLatest = points.length ? points[points.length - 1]! : null;
 
     /*
@@ -393,7 +456,7 @@ const LiveLineChartRoot = forwardRef<LiveLineChartHandle, LiveLineChartProps>(
       now.value = Date.now();
     }, false);
 
-    const running = !paused && !loading && !reducedMotion;
+    const running = liveLineClockRuns({ paused, loading, reducedMotion, appState });
 
     useEffect(() => {
       frame.setActive(running);
@@ -411,6 +474,13 @@ const LiveLineChartRoot = forwardRef<LiveLineChartHandle, LiveLineChartProps>(
       now.value = Date.now();
     }, [running, paused, points, now]);
 
+    // A frame callback is suspended with the app. Land on the wall clock as
+    // soon as it becomes active instead of showing the backgrounded window for
+    // one frame and relying on the platform to schedule a callback promptly.
+    useEffect(() => {
+      if (appState === 'active' && !paused) now.value = Date.now();
+    }, [appState, paused, now]);
+
     useImperativeHandle(
       ref,
       () => ({
@@ -434,6 +504,21 @@ const LiveLineChartRoot = forwardRef<LiveLineChartHandle, LiveLineChartProps>(
     if (!paused) heldMomentum.current = liveMomentum;
     const momentum = paused ? heldMomentum.current : liveMomentum;
 
+    const defaultFormat = (reading: number) => compactNumber(reading);
+    const semantic = liveLineAccessibility({
+      name: accessibilityLabel ?? semanticParts.title,
+      status,
+      latest,
+      activePoint,
+      momentum,
+      windowSeconds: windowMs / 1000,
+      paused,
+      now: Date.now(),
+      valueOverride: semanticParts.value,
+      formatLatest: semanticParts.formatLatest ?? defaultFormat,
+      formatActive: semanticParts.formatActive ?? defaultFormat,
+    });
+
     const base = useSeriesColor(color, 1);
     const successToken = useCSSVariable('--color-success');
     const destructiveToken = useCSSVariable('--color-destructive');
@@ -458,6 +543,13 @@ const LiveLineChartRoot = forwardRef<LiveLineChartHandle, LiveLineChartProps>(
       [onActivePointChange]
     );
 
+    useEffect(() => {
+      const next = reconcileLiveLineActivePoint(activePoint, points);
+      if (next === activePoint) return;
+      if (!next) activeTime.value = -1;
+      setActivePoint(next);
+    }, [activePoint, points, activeTime, setActivePoint]);
+
     const onLayout = (event: LayoutChangeEvent) => {
       const { width, height } = event.nativeEvent.layout;
       setSize((current) =>
@@ -519,8 +611,21 @@ const LiveLineChartRoot = forwardRef<LiveLineChartHandle, LiveLineChartProps>(
     return (
       <LiveLineChartContext.Provider value={context}>
         <View {...props} style={props.style} className={cn('w-full', className)}>
+          <View
+            accessible
+            accessibilityRole="image"
+            accessibilityLabel={semantic.label}
+            accessibilityHint={accessibilityHint}
+            style={{ position: 'absolute', left: -10_000, width: 1, height: 1 }}
+          />
           {header}
-          <View onLayout={onLayout} style={{ aspectRatio }} className="w-full">
+          <View
+            onLayout={onLayout}
+            style={{ aspectRatio }}
+            className="w-full"
+            accessibilityElementsHidden
+            importantForAccessibility="no-hide-descendants"
+          >
             {plot.width > 0 ? (
               <>
                 <Svg width="100%" height="100%" style={StyleSheet.absoluteFill}>
@@ -1026,6 +1131,14 @@ function LiveLineChartTooltip({ formatValue, className }: LiveLineChartTooltipPr
     [setActivePoint]
   );
 
+  useEffect(
+    () => () => {
+      activeTime.value = -1;
+      setActivePoint(null);
+    },
+    [activeTime, setActivePoint]
+  );
+
   const pan = useMemo(() => {
     const resolve = (x: number) => {
       'worklet';
@@ -1259,7 +1372,11 @@ function LiveLineChartHeader({
       {...props}
       className={cn('flex-row items-start justify-between gap-3 pb-3', className)}
     >
-      <View className="flex-1 gap-0.5">
+      <View
+        className="flex-1 gap-0.5"
+        accessibilityElementsHidden
+        importantForAccessibility="no-hide-descendants"
+      >
         {title ? (
           <Text size="xs" muted>
             {title}

package/src/components/live-line-chart/live-line-accessibility.ts

@@ -0,0 +1,61 @@
+export interface LiveLineAccessiblePoint {
+  time: number;
+  value: number;
+}
+
+export interface LiveLineAccessibilityInput {
+  name?: string;
+  status: 'loading' | 'ready';
+  latest: LiveLineAccessiblePoint | null;
+  activePoint: LiveLineAccessiblePoint | null;
+  momentum: 'up' | 'down' | 'flat';
+  windowSeconds: number;
+  paused: boolean;
+  now: number;
+  valueOverride?: string;
+  formatLatest: (value: number) => string;
+  formatActive: (value: number) => string;
+}
+
+/** One bounded snapshot for a stream, rather than one node per arriving point. */
+export function liveLineAccessibility({
+  name,
+  status,
+  latest,
+  activePoint,
+  momentum,
+  windowSeconds,
+  paused,
+  now,
+  valueOverride,
+  formatLatest,
+  formatActive,
+}: LiveLineAccessibilityInput) {
+  const parts = [name?.trim() || 'Live line chart'];
+
+  if (status === 'loading') {
+    parts.push('Loading');
+    if (paused) parts.push('Paused');
+    return { label: parts.join('. ') };
+  }
+
+  if (!latest) {
+    parts.push('No readings');
+    if (paused) parts.push('Paused');
+    return { label: parts.join('. ') };
+  }
+
+  if (activePoint) {
+    const secondsAgo = Math.max(0, Math.round((now - activePoint.time) / 1000));
+    parts.push(`Selected value, ${formatActive(activePoint.value)}`);
+    parts.push(secondsAgo === 0 ? 'Just now' : `${secondsAgo} seconds ago`);
+  } else {
+    parts.push(`Current value, ${valueOverride ?? formatLatest(latest.value)}`);
+    const direction = momentum === 'up' ? 'rising' : momentum === 'down' ? 'falling' : 'steady';
+    parts.push(`Trend, ${direction}`);
+  }
+
+  parts.push(`${windowSeconds}-second window`);
+  if (paused) parts.push('Paused');
+  return { label: parts.join('. ') };
+}

package/src/components/live-line-chart/live-line-lifecycle.ts

@@ -0,0 +1,63 @@
+import type { AppStateStatus } from 'react-native';
+
+export interface LiveLineReading {
+  time: number;
+  value: number;
+}
+
+export const DEFAULT_LIVE_LINE_WINDOW = 30;
+export const DEFAULT_LIVE_LINE_MAX_POINTS = 500;
+
+export function normalizeLiveLineWindow(seconds: number): number {
+  return Number.isFinite(seconds) && seconds > 0
+    ? Math.max(seconds, 1)
+    : DEFAULT_LIVE_LINE_WINDOW;
+}
+
+export function normalizeLiveLineMaxPoints(maxPoints: number): number {
+  return Number.isFinite(maxPoints) && maxPoints > 0
+    ? Math.max(1, Math.floor(maxPoints))
+    : DEFAULT_LIVE_LINE_MAX_POINTS;
+}
+
+/**
+ * Builds the one ordered, finite buffer every renderer and interaction reads.
+ * For duplicate timestamps the last input wins, matching a corrected reading
+ * arriving with the same identity as the one it replaces.
+ */
+export function normalizeLiveLinePoints<T extends LiveLineReading>(
+  data: readonly T[],
+  maxPoints: number,
+): T[] {
+  const byTime = new Map<number, T>();
+  for (const point of data) {
+    if (Number.isFinite(point.time) && Number.isFinite(point.value)) {
+      byTime.set(point.time, point);
+    }
+  }
+  return [...byTime.values()]
+    .sort((left, right) => left.time - right.time)
+    .slice(-normalizeLiveLineMaxPoints(maxPoints));
+}
+
+export function liveLineClockRuns(options: {
+  paused: boolean;
+  loading: boolean;
+  reducedMotion: boolean;
+  appState: AppStateStatus;
+}): boolean {
+  return (
+    !options.paused &&
+    !options.loading &&
+    !options.reducedMotion &&
+    options.appState === 'active'
+  );
+}
+
+export function reconcileLiveLineActivePoint<T extends LiveLineReading>(
+  active: T | null,
+  points: readonly T[],
+): T | null {
+  if (!active) return null;
+  return points.find((point) => point.time === active.time) ?? null;
+}

package/src/components/marker/index.tsx

@@ -100,21 +100,21 @@ const MarkerRoot = forwardRef<View, MarkerProps>(
     const body = !onPress ? (
       <View
         ref={ref}
+        {...(props as ViewProps)}
         accessibilityState={{ disabled: !!disabled }}
         className={root({ className })}
-        {...(props as ViewProps)}
       >
         {inner}
       </View>
     ) : (
       <AnimatedPressable
         ref={ref}
+        {...props}
         accessibilityRole="button"
         accessibilityState={{ disabled: !!disabled }}
         disabled={disabled}
         onPress={onPress}
         className={root({ className })}
-        {...props}
       >
         {inner}
       </AnimatedPressable>

package/src/components/marquee/index.tsx

@@ -0,0 +1,234 @@
+/**
+ * Marquee — content that travels across its container and never runs out.
+ *
+ * For a strip of logos, a ticker of prices, a row of testimonials: anything
+ * whose job is to keep moving past a boundary rather than to be scrolled.
+ *
+ * ```tsx
+ * <Marquee spacing={24} speed={40}>
+ *   <View className="flex-row gap-6">
+ *     {sponsors.map((s) => <Logo key={s.id} src={s.logo} />)}
+ *   </View>
+ * </Marquee>
+ * ```
+ *
+ * ## How it loops
+ *
+ * The content is measured once, then laid out end to end enough times to cover
+ * the container twice over. One track holds every copy and it is that track,
+ * not the copies, that moves — a single animated node for any amount of
+ * content. It travels exactly one copy-and-gap and starts over, so the state it
+ * ends on is the state it began on and the seam never shows.
+ *
+ * The travel is a linear timing driven on the UI thread, so it costs nothing
+ * per frame in JavaScript and keeps running while the thread is busy.
+ *
+ * ## Measurement needs room
+ *
+ * The copy that gets measured sits in a hidden scroller, because that is what
+ * lets the content report the width it *wants* rather than the width the
+ * container would give it. Content with no intrinsic size of its own — a child
+ * stretched to `flex-1`, an image with no dimensions — measures as nothing and
+ * the marquee will not start.
+ *
+ * ## Reading direction and reduced motion
+ *
+ * A horizontal marquee travels toward the end of the line, so it reverses in a
+ * right-to-left subtree. `reverse` flips it again from wherever it landed.
+ *
+ * With the operating system set to reduce motion the content is rendered once
+ * and held still. A ticker that never stops is the exact thing that setting is
+ * there to turn off, so this is not a shorter animation — it is none.
+ *
+ * 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 ReactNode } from 'react';
+import {
+  ScrollView,
+  StyleSheet,
+  View,
+  type LayoutChangeEvent,
+  type ViewProps,
+} from 'react-native';
+import Animated, {
+  cancelAnimation,
+  Easing,
+  useAnimatedStyle,
+  useReducedMotion,
+  useSharedValue,
+  withRepeat,
+  withTiming,
+} from 'react-native-reanimated';
+import { useDirectionSign } from '../../hooks/use-direction';
+import { cn } from '../../utils/cn';
+import {
+  DEFAULT_MARQUEE_SPEED,
+  marqueeCopyCount,
+  normalizeMarqueeSpeed,
+} from './marquee-math';
+
+export type MarqueeDirection = 'horizontal' | 'vertical';
+
+export interface MarqueeProps extends Omit<ViewProps, 'children'> {
+  className?: string;
+  /** The content to repeat. Measured once, then tiled along the axis. */
+  children: ReactNode;
+  /**
+   * Travel speed in points per second. 40 by default, which is slow enough
+   * that a word stays readable as it crosses. The cycle time follows from this
+   * and the measured content, so longer content takes proportionally longer
+   * rather than moving faster.
+   */
+  speed?: number;
+  /** Gap between the end of one copy and the start of the next. */
+  spacing?: number;
+  /** Axis the content travels along. */
+  direction?: MarqueeDirection;
+  /**
+   * Send it the other way: toward the start of the line, or upward. Applied
+   * after the reading direction, not instead of it.
+   */
+  reverse?: boolean;
+  /** Set false to hold the content where it is. */
+  playing?: boolean;
+}
+
+export function Marquee({
+  className,
+  children,
+  speed: speedProp = DEFAULT_MARQUEE_SPEED,
+  spacing = 0,
+  direction = 'horizontal',
+  reverse = false,
+  playing = true,
+  style,
+  onLayout,
+  ...props
+}: MarqueeProps) {
+  const horizontal = direction === 'horizontal';
+  const reducedMotion = useReducedMotion();
+  // Only the horizontal axis has a reading direction to follow; up is up.
+  const sign = useDirectionSign();
+  const flip = horizontal ? sign : 1;
+
+  const [viewport, setViewport] = useState(0);
+  const [content, setContent] = useState(0);
+  const speed = normalizeMarqueeSpeed(speedProp);
+
+  // 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
+  // on purpose: taking the gap from anywhere else is how a seam appears.
+  const layout = useMemo(
+    () => marqueeCopyCount(viewport, content, spacing),
+    [viewport, content, spacing]
+  );
+  const { period } = layout;
+
+  const copies = useMemo(() => {
+    // Enough to span the container, plus one trailing into view and one
+    // already past it — the two the travel consumes before the loop restarts.
+    return Array.from({ length: layout.count }, (_, index) => index);
+  }, [layout.count]);
+
+  const offset = useSharedValue(0);
+
+  useEffect(() => {
+    cancelAnimation(offset);
+    offset.value = 0;
+    if (reducedMotion || !playing || period <= 0 || speed <= 0) return undefined;
+    offset.value = withRepeat(
+      withTiming(period, {
+        duration: (period / speed) * 1000,
+        easing: Easing.linear,
+      }),
+      -1,
+      false
+    );
+    return () => cancelAnimation(offset);
+  }, [offset, period, playing, reducedMotion, speed]);
+
+  const trackStyle = useAnimatedStyle(() => {
+    const travel = (reverse ? offset.value : -offset.value) * flip;
+    return {
+      transform: [horizontal ? { translateX: travel } : { translateY: travel }],
+    };
+  }, [horizontal, reverse, flip]);
+
+  // The container's own measurement is what sizes the loop, so an `onLayout`
+  // passed in is called alongside it rather than replacing it.
+  const onContainerLayout = (event: LayoutChangeEvent) => {
+    const { width, height } = event.nativeEvent.layout;
+    setViewport(horizontal ? width : height);
+    onLayout?.(event);
+  };
+
+  const onContentLayout = (event: LayoutChangeEvent) => {
+    const { width, height } = event.nativeEvent.layout;
+    setContent(horizontal ? width : height);
+  };
+
+  // Nothing to loop, so nothing to clip or clone: render the content plainly
+  // and let it sit where it falls.
+  if (reducedMotion) {
+    return (
+      <View
+        className={cn('overflow-hidden', className)}
+        style={style}
+        onLayout={onLayout}
+        {...props}
+      >
+        {children}
+      </View>
+    );
+  }
+
+  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"
+      >
+        <View onLayout={onContentLayout}>{children}</View>
+      </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 (
+            <View
+              key={index}
+              style={[styles.copy, horizontal ? { left: at } : { top: at }]}
+              pointerEvents="box-none"
+              accessibilityElementsHidden={!spoken}
+              importantForAccessibility={spoken ? 'auto' : 'no-hide-descendants'}
+            >
+              {children}
+            </View>
+          );
+        })}
+      </Animated.View>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  /* Laid out so it measures, hidden so it does not draw, and behind everything
+     so it can never intercept anything. */
+  measure: { opacity: 0, zIndex: -1 },
+  copy: { position: 'absolute' },
+});

package/src/components/marquee/marquee-math.ts

@@ -0,0 +1,37 @@
+/**
+ * The arithmetic behind the loop, kept out of the component so it can be tested
+ * without rendering one.
+ *
+ * Every value here reaches a Reanimated timing or a layout offset, and both
+ * treat `NaN` and `Infinity` as a frame that never resolves rather than as an
+ * error. A marquee handed a bad number should hold still, not wedge — so the
+ * guards live at the boundary, once, instead of at each use.
+ */
+
+/**
+ * Points per second. Slow enough that a word stays readable as it crosses,
+ * which is the speed a ticker is actually for.
+ */
+export const DEFAULT_MARQUEE_SPEED = 40;
+
+export function normalizeMarqueeSpeed(value: number): number {
+  if (!Number.isFinite(value)) return DEFAULT_MARQUEE_SPEED;
+  return Math.max(value, 0);
+}
+
+export function normalizeMarqueeSpacing(value: number): number {
+  if (!Number.isFinite(value)) return 0;
+  return Math.max(value, 0);
+}
+
+export function marqueeCopyCount(
+  viewport: number,
+  content: number,
+  spacing: number
+): { period: number; count: number } {
+  const safeViewport = Number.isFinite(viewport) ? Math.max(viewport, 0) : 0;
+  const safeContent = Number.isFinite(content) ? Math.max(content, 0) : 0;
+  const period = safeContent > 0 ? safeContent + normalizeMarqueeSpacing(spacing) : 0;
+  if (period <= 0 || safeViewport <= 0) return { period, count: 0 };
+  return { period, count: Math.ceil(safeViewport / period) + 2 };
+}