react-native-terra-ui 0.11.16 → 0.12.0

package/src/components/badge/WithBadge.tsx

@@ -0,0 +1,79 @@
+import { type ComponentRef, forwardRef } from "react";
+import { View } from "react-native";
+
+import { StyleSheet } from "react-native-unistyles";
+
+import { Badge } from "./Badge";
+import type { WithBadgeProps } from "./types";
+import { getAnchorPosition } from "./utils";
+
+/**
+ * Pins a `Badge` to one corner of the element it wraps.
+ *
+ * ```tsx
+ * <WithBadge placement="top-right" color="danger" label={3}>
+ *   <Toolbar.Button icon="bell" accessibilityLabel="Notifications" />
+ * </WithBadge>
+ * ```
+ *
+ * The child renders untouched — `WithBadge` contributes the positioning context
+ * and the overlay, nothing else. A round child usually wants a negative
+ * `offset`, since the corner being anchored to is the bounding box's, not the
+ * circle's. For a badge that sits inline beside text, use `Badge` on its own.
+ */
+const WithBadge = forwardRef<ComponentRef<typeof View>, WithBadgeProps>(function WithBadge(
+  {
+    children,
+    placement = "top-right",
+    label,
+    color = "danger",
+    size = "md",
+    offset = 0,
+    isVisible = true,
+    fullWidth = false,
+    accessibilityLabel,
+    style,
+    ...rest
+  },
+  ref
+) {
+  styles.useVariants({ fullWidth });
+
+  return (
+    // `style` last so an explicit `alignSelf` beats `fullWidth`.
+    <View ref={ref} style={[styles.wrapper, style]} {...rest}>
+      {children}
+      {isVisible ? (
+        <View pointerEvents="box-none" style={[styles.anchor, getAnchorPosition(placement, size, offset)]}>
+          <Badge label={label} color={color} size={size} ring accessibilityLabel={accessibilityLabel} />
+        </View>
+      ) : null}
+    </View>
+  );
+});
+
+export { WithBadge };
+
+// ─── Styles ───────────────────────────────────────────────────────────────────
+//
+// The badge's insets are computed in `getAnchorPosition`, not declared here:
+// `offset` is an open-ended number, so it could never be a variant condition,
+// and the position involves no theme tokens at all. That leaves this stylesheet
+// with only what genuinely varies declaratively.
+const styles = StyleSheet.create(() => ({
+  wrapper: {
+    position: "relative",
+    variants: {
+      // `alignSelf: 'flex-start'` hugs the child, so the indicator anchors to
+      // the child's bounds rather than the surrounding container's. A child
+      // that was stretching needs `fullWidth` to go on doing so.
+      fullWidth: {
+        true: { alignSelf: "stretch" },
+        false: { alignSelf: "flex-start" },
+      },
+    },
+  },
+  anchor: {
+    position: "absolute",
+  },
+}));

package/src/components/badge/index.ts

@@ -1,2 +1,3 @@
 export { Badge } from "./Badge";
-export type { BadgeColor, BadgePlacement, BadgeProps, BadgeSize } from "./types";
+export type { BadgeColor, BadgePlacement, BadgeProps, BadgeSize, WithBadgeProps } from "./types";
+export { WithBadge } from "./WithBadge";

package/src/components/badge/types.ts

@@ -1,7 +1,7 @@
 import type { ReactNode } from "react";
 import type { ViewProps } from "react-native";
 
-/** Corner of the wrapped child the indicator is anchored to. */
+/** Corner of the wrapped child a `WithBadge` anchors its badge to. */
 export type BadgePlacement = "top-right" | "top-left" | "bottom-right" | "bottom-left";
 
 /** Scale of the dot, pill, and label. */
@@ -9,7 +9,7 @@ export type BadgeSize = "sm" | "md" | "lg";
 
 /**
  * Semantic color scheme, or a raw CSS color literal (`#fff`, `rgb(...)`, `hsl(...)`).
- * A literal paints the indicator with that exact value and derives a readable
+ * A literal paints the badge with that exact value and derives a readable
  * foreground for the label.
  */
 export type BadgeColor =
@@ -21,37 +21,61 @@ export type BadgeColor =
   // literals last so scheme-name autocomplete still surfaces
   | (string & {});
 
-export interface BadgeProps extends ViewProps {
-  /** The element being badged. Rendered untouched; `Badge` only adds the overlay. */
+export interface BadgeProps extends Omit<ViewProps, "children"> {
+  /**
+   * Text in the badge. Omit it (or pass an empty string) for a dot.
+   * `0` renders as a label; a caller hiding a zero count leaves the badge out.
+   */
+  label?: string | number;
+  /** Semantic scheme or raw color literal. Defaults to `'danger'`. */
+  color?: BadgeColor;
+  /** Scale of the badge. Defaults to `'md'`. */
+  size?: BadgeSize;
+  /**
+   * Draws a `surface.canvas` ring around the badge, so it stays legible over
+   * whatever it overlaps. `WithBadge` turns it on. A badge inline beside text
+   * overlaps nothing, so it defaults to `false`: on a card the ring would only
+   * read as an outline.
+   */
+  ring?: boolean;
+  /**
+   * Announced in place of the label. Defaults to the label's own text; an
+   * unlabelled dot is hidden from assistive technology.
+   */
+  accessibilityLabel?: string;
+}
+
+export interface WithBadgeProps extends ViewProps {
+  /** The element being badged. Rendered untouched; `WithBadge` only adds the overlay. */
   children: ReactNode;
   /**
-   * Corner the indicator sits on. Defaults to `'top-right'`.
+   * Corner the badge sits on. Defaults to `'top-right'`.
    *
-   * The indicator overhangs the child, so an ancestor that clips — a `Surface`
+   * The badge overhangs the child, so an ancestor that clips — a `Surface`
    * with a radius, or a `Screen` list row — will cut it off. Pad that container
-   * by the overhang, or lift the `Badge` outside it.
+   * by the overhang, or lift the `WithBadge` outside it.
    */
   placement?: BadgePlacement;
   /**
-   * Text in the indicator. Omit it (or pass an empty string) for a dot.
+   * Text in the badge. Omit it (or pass an empty string) for a dot.
    * `0` renders as a label — use `isVisible` to suppress a zero count.
    */
   label?: string | number;
   /** Semantic scheme or raw color literal. Defaults to `'danger'`. */
   color?: BadgeColor;
-  /** Scale of the indicator. Defaults to `'md'`. */
+  /** Scale of the badge. Defaults to `'md'`. */
   size?: BadgeSize;
   /**
-   * Nudges the indicator along both axes from the corner `placement` picked.
+   * Nudges the badge along both axes from the corner `placement` picked.
    * Positive moves it away from the child's centre, negative pulls it in.
    * A number applies to both axes; `{ x, y }` sets them separately.
    *
    * The corner it anchors to is the child's **bounding box**, so a round child
-   * needs a negative offset to bring the indicator onto the visible edge — a
+   * needs a negative offset to bring the badge onto the visible edge — a
    * circle only meets its box at 45°, about `0.21 × width` away. Defaults to `0`.
    */
   offset?: number | { x?: number; y?: number };
-  /** Renders the indicator. The child renders either way. Defaults to `true`. */
+  /** Renders the badge. The child renders either way. Defaults to `true`. */
   isVisible?: boolean;
   /**
    * Stretches the wrapper along its parent's cross axis, so a child that

package/src/components/badge/utils.ts

@@ -10,7 +10,7 @@ export interface CustomBadgeColors {
   fg: string;
 }
 
-/** The indicator's paint for a raw literal: the literal itself, plus a readable label. */
+/** The badge's paint for a raw literal: the literal itself, plus a readable label. */
 export function getCustomBadgeColors(literal: string): CustomBadgeColors {
   return { bg: literal, fg: readableOn(literal) };
 }
@@ -25,7 +25,7 @@ export function hasLabel(label: string | number | undefined): label is string |
 }
 
 /**
- * Outer diameter of the dot per size. The indicator's own stylesheet repeats
+ * Outer diameter of the dot per size. The badge's own stylesheet repeats
  * these as literals — the unistyles Babel plugin reads that object statically,
  * so it cannot reference this table — and `anchorOffsetsMatchDotRadius` in the
  * test suite is what keeps the two in step.
@@ -44,7 +44,7 @@ export interface AnchorPosition {
 }
 
 /**
- * Absolute insets for the indicator, in pure arithmetic rather than one
+ * Absolute insets for a `WithBadge`'s badge, in pure arithmetic rather than one
  * compound variant per (placement, size) cell: `offset` is an open-ended number
  * and could never be a variant condition, and nothing here touches the theme.
  *

package/src/components/header/parts/HeaderBar.tsx

@@ -1,5 +1,5 @@
 import { type ComponentProps, type ReactNode, useState } from "react";
-import { Text, View } from "react-native";
+import { type LayoutChangeEvent, Text, View } from "react-native";
 
 import Animated from "react-native-reanimated";
 import { ScrollToTopGuard } from "react-native-screens/experimental";
@@ -38,6 +38,13 @@ export function HeaderBar({
 }: HeaderBarProps) {
   const { theme } = useUnistyles();
   const [windowInsets, setWindowInsets] = useState({ left: 0, right: 0 });
+  // Toolbar widths, so a centered title can stay clear of both sides.
+  const [leadingWidth, setLeadingWidth] = useState(0);
+  const [trailingWidth, setTrailingWidth] = useState(0);
+  const onLeadingLayout = (event: LayoutChangeEvent) => setLeadingWidth(event.nativeEvent.layout.width);
+  const onTrailingLayout = (event: LayoutChangeEvent) => setTrailingWidth(event.nativeEvent.layout.width);
+  const hasLeading = leading != null || dismissAction === "back";
+  const hasTrailing = trailing != null || dismissAction === "close";
   styles.useVariants({ titleAlignment });
   const dismiss = (
     <HeaderDismissButton dismissAction={dismissAction} navigation={navigation} onDismiss={onDismiss} />
@@ -62,8 +69,8 @@ export function HeaderBar({
       <View style={[styles.bar, styles.windowInsets(windowInsets.left, windowInsets.right)]}>
         <HeaderSurface color={color} animatedStyle={surfaceStyle} />
         <HeaderWindowInsets onInsetsChange={setWindowInsets} />
-        {(leading != null || dismissAction === "back") && (
-          <Toolbar>
+        {hasLeading && (
+          <Toolbar onLayout={onLeadingLayout}>
             {dismissAction === "back" && dismiss}
             {leading}
           </Toolbar>
@@ -71,7 +78,13 @@ export function HeaderBar({
         <Animated.View
           style={[
             styles.titleContainer,
-            styles.titleInsets(windowInsets.left, windowInsets.right, titleAlignment),
+            styles.titleInsets(
+              windowInsets.left,
+              windowInsets.right,
+              hasLeading ? leadingWidth : 0,
+              hasTrailing ? trailingWidth : 0,
+              titleAlignment
+            ),
             titleStyle,
           ]}
           pointerEvents={isCustomTitle(title) ? "box-none" : "none"}
@@ -80,6 +93,7 @@ export function HeaderBar({
             ? String(title).trim().length > 0 && (
                 <Text
                   style={styles.title}
+                  numberOfLines={1}
                   maxFontSizeMultiplier={theme.typography.variants["title-md"].maxFontSizeMultiplier}
                 >
                   {title}
@@ -87,8 +101,8 @@ export function HeaderBar({
               )
             : title}
         </Animated.View>
-        {(trailing != null || dismissAction === "close") && (
-          <Toolbar style={styles.trailing}>
+        {hasTrailing && (
+          <Toolbar style={styles.trailing} onLayout={onTrailingLayout}>
             {dismissAction === "close" && dismiss}
             {trailing}
           </Toolbar>
@@ -103,8 +117,27 @@ const styles = StyleSheet.create((theme, runtime) => ({
     paddingLeft: Math.max(resolveScreenPadding(theme, runtime.breakpoint).x, left),
     paddingRight: Math.max(resolveScreenPadding(theme, runtime.breakpoint).x, right),
   }),
-  titleInsets: (left: number, right: number, alignment: "center" | "left") =>
-    alignment === "center" ? { left, right } : {},
+  // A centered title spans the region between the window controls and is inset
+  // by the same amount from both of its edges, so it stays centered in that
+  // region. The inset is whichever side reaches further in — bar padding plus
+  // that side's toolbar — so a long title truncates before either toolbar
+  // instead of running underneath it. A left-aligned title is in the flex row
+  // already and needs none of this.
+  titleInsets: (
+    left: number,
+    right: number,
+    leadingWidth: number,
+    trailingWidth: number,
+    alignment: "center" | "left"
+  ) => {
+    if (alignment !== "center") return {};
+    const padding = resolveScreenPadding(theme, runtime.breakpoint).x;
+    const gap = theme.spacing["3"];
+    const reachLeft = Math.max(padding, left) + (leadingWidth > 0 ? leadingWidth + gap : 0) - left;
+    const reachRight = Math.max(padding, right) + (trailingWidth > 0 ? trailingWidth + gap : 0) - right;
+    const inset = Math.max(reachLeft, reachRight);
+    return { left: left + inset, right: right + inset };
+  },
   bar: {
     height: theme.layout.header.height,
     flexDirection: "row",

package/src/components/index.ts

@@ -1,3 +1,4 @@
+export * from "./accordion";
 export * from "./avatar";
 export * from "./badge";
 export * from "./box";

package/src/components/page-indicator/hooks/use-page-indicator-window.ts

@@ -0,0 +1,84 @@
+import { useMemo, useState } from "react";
+
+import { runOnJS, type SharedValue, useAnimatedReaction, useSharedValue } from "react-native-reanimated";
+
+import { isPageIndicatorSharedValue, pageIndicatorMountedRange } from "../utils";
+
+export interface PageIndicatorWindow {
+  /** First dot index to mount, inclusive. */
+  start: number;
+  /** Last dot index to mount, inclusive. */
+  end: number;
+}
+
+/**
+ * The slice of dots a variant should mount, kept in step with the active page.
+ *
+ * Both variants clip to a window of `maxVisible` slots and scroll a track
+ * behind it, so all but a handful of dots are drawn outside the viewport. This
+ * is what lets them skip building those: the range covers the visible window
+ * plus a generous overscan, and moves only when the active page leaves it.
+ *
+ * **Driven by `progress`, not by `current`.** `current` may be a shared value
+ * for scroll-linked motion, in which case React never re-renders on a page
+ * change and a range derived from props would sit still while the track slid
+ * out from under it. `progress` is the one place both spellings of `current`
+ * have already been resolved into a single number.
+ *
+ * The reaction only reaches JS when the page moves *outside* the mounted range
+ * — not on every frame, and not on every page. A one-page step normally costs
+ * no render at all, because the neighbour was already mounted; a long jump
+ * costs one render per window it crosses rather than one per page.
+ *
+ * Known limit: during a jump of many pages the track slides faster than the
+ * range is re-rendered, so dots in the middle of that flight may not be mounted
+ * as they pass. They are identical inactive dots moving too fast to read, and
+ * the alternative — mounting every page between the two — is the cost this
+ * exists to avoid.
+ */
+export function usePageIndicatorWindow(
+  count: number,
+  current: number | SharedValue<number> | undefined,
+  progress: SharedValue<number>,
+  slot: number,
+  dotSize: number,
+  maxVisible: number,
+  activeMainSize = dotSize
+): PageIndicatorWindow {
+  const virtualized = count > maxVisible;
+
+  /*
+    Seeded from `current` so an indicator mounted straight onto a late page
+    draws that page's dots on its first frame rather than the first page's.
+    Zero for a shared value, which cannot be read during render — the reaction
+    below corrects it on the first frame that matters.
+  */
+  const [anchor, setAnchor] = useState(() =>
+    current === undefined || isPageIndicatorSharedValue(current) ? 0 : Math.round(current)
+  );
+
+  const window = useMemo(
+    () => pageIndicatorMountedRange(count, anchor, slot, dotSize, maxVisible, activeMainSize),
+    [count, anchor, slot, dotSize, maxVisible, activeMainSize]
+  );
+
+  /*
+    The live range, on the UI thread, so the reaction can decide for itself
+    whether a page change matters. Reading React state from a worklet is not an
+    option, and crossing to JS to ask would defeat the point of asking.
+  */
+  const mounted = useSharedValue(window);
+  mounted.value = window;
+
+  useAnimatedReaction(
+    () => Math.round(progress.value),
+    (page) => {
+      if (!virtualized) return;
+      const { start, end } = mounted.value;
+      if (page < start || page > end) runOnJS(setAnchor)(page);
+    },
+    [virtualized]
+  );
+
+  return window;
+}

package/src/components/page-indicator/utils.ts

@@ -73,6 +73,17 @@ export function pageIndicatorViewportClipStyle(
   };
 }
 
+/**
+ * Holds the room of dots a variant chose not to mount.
+ *
+ * The track keeps its full width and keeps scrolling by the same amount, so
+ * skipped dots still have to occupy their slots — otherwise the mounted ones
+ * slide up the track and the window shows the wrong pages.
+ */
+export function pageIndicatorSpacerStyle(vertical: boolean, mainSize: number): ViewStyle {
+  return vertical ? { height: mainSize } : { width: mainSize };
+}
+
 function scaleCurveValue(curve: readonly number[], distance: number, tailScale: number): number {
   "worklet";
   if (distance < curve.length) return curve[distance] ?? tailScale;
@@ -178,3 +189,62 @@ export function pageIndicatorWindowScale(
 
   return pageIndicatorWindowSlotScale(positionInWindow, activeSlot, maxVisible);
 }
+
+/**
+ * Dots kept mounted beyond each edge of the visible window.
+ *
+ * One full window's worth. The window itself is `maxVisible` slots wide, so
+ * this leaves a whole screenful of slack on either side — enough that ordinary
+ * navigation (a swipe, a few pages at a time) never outruns the mounted range
+ * between the page change and React re-rendering with a new one.
+ */
+export const PAGE_INDICATOR_WINDOW_OVERSCAN = 5;
+
+/**
+ * Which dot indices are worth mounting, inclusive, for an active page of
+ * `anchor`.
+ *
+ * An indicator draws `maxVisible` slots and clips the rest, and every dot more
+ * than one page from the active one is drawn identically — same size, same
+ * scale, same opacity, same colour. Mounting one view per page therefore costs
+ * an animated style per page to render something nobody can see: at 500 pages
+ * that is 500 worklets for five visible dots, and it lands on every page
+ * change. Bounding what is mounted is what stops the indicator's cost scaling
+ * with the length of the thing it indicates.
+ *
+ * Derived from `computePageIndicatorWindowTranslate`, the same function that
+ * positions the track, so the mounted range and the visible window cannot
+ * disagree about where the window is — including at the ends, where the
+ * translate clamps and the window stops following the active page.
+ *
+ * Below the overflow threshold every dot is visible, so the range is the whole
+ * track and nothing changes.
+ */
+export function pageIndicatorMountedRange(
+  count: number,
+  anchor: number,
+  slot: number,
+  dotSize: number,
+  maxVisible: number,
+  activeMainSize = dotSize,
+  overscan = PAGE_INDICATOR_WINDOW_OVERSCAN
+): { start: number; end: number } {
+  const last = Math.max(0, count - 1);
+  if (count <= maxVisible) return { start: 0, end: last };
+
+  const translate = computePageIndicatorWindowTranslate(
+    count,
+    anchor,
+    slot,
+    dotSize,
+    maxVisible,
+    activeMainSize
+  );
+  // The same expression `pageIndicatorWindowScale` reads the window from.
+  const visibleStart = -translate / slot;
+
+  return {
+    start: Math.max(0, Math.floor(visibleStart) - overscan),
+    end: Math.min(last, Math.ceil(visibleStart) + maxVisible - 1 + overscan),
+  };
+}

package/src/components/page-indicator/variants/DotIndicator/index.tsx

@@ -6,6 +6,7 @@ import Animated, { useAnimatedStyle } from "react-native-reanimated";
 
 import type { ColorToken } from "#theme/types";
 import { usePageIndicatorCore } from "../../hooks/use-page-indicator-core";
+import { usePageIndicatorWindow } from "../../hooks/use-page-indicator-window";
 import { PageIndicatorRoot } from "../../PageIndicatorRoot";
 import {
   computePageIndicatorWindowTranslate,
@@ -71,7 +72,17 @@ export function DotIndicator({
   const fullTrackMainSize = pageIndicatorTrackMainSize(count, slot, dotSize);
   const overflows = count > maxVisible;
 
-  const indices = useMemo(() => Array.from({ length: count }, (_, index) => index), [count]);
+  /*
+    No spacers here, unlike the pill variant: an `InactiveDot` is absolutely
+    positioned from its own index, so a dot that is not mounted leaves a gap
+    exactly where it would have been and the rest do not move.
+  */
+  const { start, end } = usePageIndicatorWindow(count, current, progress, slot, dotSize, maxVisible);
+
+  const indices = useMemo(
+    () => Array.from({ length: end - start + 1 }, (_, offset) => start + offset),
+    [start, end]
+  );
 
   const trackStyle = useAnimatedStyle(() => {
     const translate = computePageIndicatorWindowTranslate(count, progress.value, slot, dotSize, maxVisible);

package/src/components/page-indicator/variants/PillIndicator/index.tsx

@@ -1,17 +1,19 @@
 import { useMemo } from "react";
-import type { StyleProp, ViewStyle } from "react-native";
+import { type StyleProp, View, type ViewStyle } from "react-native";
 
 import type { SharedValue } from "react-native-reanimated";
 import Animated, { useAnimatedStyle } from "react-native-reanimated";
 
 import type { ColorToken } from "#theme/types";
 import { usePageIndicatorCore } from "../../hooks/use-page-indicator-core";
+import { usePageIndicatorWindow } from "../../hooks/use-page-indicator-window";
 import { PageIndicatorRoot } from "../../PageIndicatorRoot";
 import {
   computePageIndicatorWindowTranslate,
   DEFAULT_PAGE_INDICATOR_MAX_VISIBLE,
   PAGE_INDICATOR_SINGLE_PAGE_DURATION,
   pageIndicatorAxisTranslateStyle,
+  pageIndicatorSpacerStyle,
   pageIndicatorTrackMainSize,
   pageIndicatorViewportMainSize,
 } from "../../utils";
@@ -62,7 +64,33 @@ export function PillIndicator({
   const fullTrackMainSize = pageIndicatorTrackMainSize(count, slot, dotSize, activeWidth);
   const overflows = count > maxVisible;
 
-  const indices = useMemo(() => Array.from({ length: count }, (_, index) => index), [count]);
+  const { start, end } = usePageIndicatorWindow(
+    count,
+    current,
+    progress,
+    slot,
+    dotSize,
+    maxVisible,
+    activeWidth
+  );
+
+  const indices = useMemo(
+    () => Array.from({ length: end - start + 1 }, (_, offset) => start + offset),
+    [start, end]
+  );
+
+  /*
+    The track is still `count` slots wide and still scrolls the same way, so the
+    dots that are not mounted have to leave their room behind. Each unmounted
+    dot occupies exactly one slot — it is inactive, and only the active dot is
+    ever wider than `dotSize` — so the space before the window is `start` slots
+    and the space after it is whatever is left.
+
+    Less one gap apiece, because the row's own `gap` supplies the space between
+    a spacer and the first dot beside it.
+  */
+  const leadMainSize = start * slot - gap;
+  const tailMainSize = (count - 1 - end) * slot - gap;
 
   const trackStyle = useAnimatedStyle(() => {
     const displayProgress = pillIndicatorJumpDisplayProgress(
@@ -107,6 +135,7 @@ export function PillIndicator({
           overflows ? trackStyle : null,
         ]}
       >
+        {leadMainSize > 0 && <View style={pageIndicatorSpacerStyle(vertical, leadMainSize)} />}
         {indices.map((index) => (
           <PillIndicatorDot
             key={index}
@@ -121,6 +150,7 @@ export function PillIndicator({
             maxVisible={maxVisible}
           />
         ))}
+        {tailMainSize > 0 && <View style={pageIndicatorSpacerStyle(vertical, tailMainSize)} />}
       </Animated.View>
     </PageIndicatorRoot>
   );