react-native-terra-ui 0.11.17 → 0.12.0

package/src/components/badge/Badge.tsx

@@ -1,78 +1,196 @@
-import { type ComponentRef, forwardRef } from "react";
-import { View } from "react-native";
+import { Text as RNText, View } from "react-native";
 
-import { StyleSheet } from "react-native-unistyles";
+import { StyleSheet, useUnistyles } from "react-native-unistyles";
 
-import { BadgeIndicator } from "./parts/BadgeIndicator";
-import type { BadgeProps } from "./types";
-import { getAnchorPosition } from "./utils";
+import type { ColorToken, RoleTextVariant } from "#theme/types";
+import { resolveThemeColor } from "#utils/resolve-theme-color";
+import { FONT_WEIGHT_VALUE, SYSTEM_FONT } from "#utils/typography";
+import type { BadgeProps, BadgeSize } from "./types";
+import { getCustomBadgeColors, hasLabel } from "./utils";
+
+const SCHEME_NAMES = new Set(["primary", "secondary", "success", "warning", "danger"]);
+
+type BadgeScheme = "primary" | "secondary" | "success" | "warning" | "danger";
+
+/** Label foreground per scheme — mirrors the spec's token table. */
+const FG_TOKEN: Record<BadgeScheme, ColorToken> = {
+  primary: "accent.solid.fg",
+  secondary: "neutral.solid.fg",
+  success: "success.solid.fg",
+  warning: "warning.solid.fg",
+  danger: "danger.solid.fg",
+};
+
+const LABEL_VARIANT: Record<BadgeSize, RoleTextVariant> = {
+  sm: "label-sm",
+  md: "label-md",
+  lg: "label-lg",
+};
 
 /**
- * Overlays a count or status indicator on one corner of the element it wraps.
+ * A dot, or a pill carrying a count or short label.
  *
  * ```tsx
- * <Badge placement="top-right" color="danger" label={3}>
- *   <Toolbar.Button icon="bell" accessibilityLabel="Notifications" />
- * </Badge>
+ * <Text>Appearing</Text>
+ * <Badge color="secondary" size="sm" label={56} />
  * ```
  *
- * The child renders untouched — `Badge` 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.
+ * Stands on its own, inline in a row beside the text it counts. To pin one to
+ * the corner of an icon or button, wrap that element in `WithBadge`, which
+ * renders this and owns only the position.
+ *
+ * `useUnistyles` is called unconditionally, which is what subscribes this
+ * component to theme changes. The background below comes from a variant, which
+ * unistyles applies straight to the native node on a theme switch; without a
+ * re-render React would go on believing the node holds the previous theme's
+ * value. `Chip` documents the same hazard on its root.
  */
-const Badge = forwardRef<ComponentRef<typeof View>, BadgeProps>(function Badge(
-  {
-    children,
-    placement = "top-right",
-    label,
-    color = "danger",
-    size = "md",
-    offset = 0,
-    isVisible = true,
-    fullWidth = false,
-    accessibilityLabel,
-    style,
-    ...rest
-  },
-  ref
-) {
-  styles.useVariants({ fullWidth });
+export const Badge = ({
+  label,
+  color = "danger",
+  size = "md",
+  ring = false,
+  accessibilityLabel,
+  style,
+  ...rest
+}: BadgeProps) => {
+  const { theme } = useUnistyles();
+  // A literal never matches one of the five variant options, so it's cast to
+  // satisfy `useVariants`'s literal-union type while still being compared
+  // against the real value below.
+  styles.useVariants({ color: color as BadgeScheme, size, ring });
+
+  const custom = SCHEME_NAMES.has(color) ? null : getCustomBadgeColors(color);
+  const labelled = hasLabel(label);
+  const foreground = custom ? custom.fg : FG_TOKEN[color as BadgeScheme];
+
+  // An explicit label wins even on a dot; a dot with nothing to announce is
+  // decorative and hidden rather than read out as an unlabelled element.
+  const announced = accessibilityLabel ?? (labelled ? String(label) : undefined);
+  const accessibility = announced
+    ? { accessible: true, accessibilityLabel: announced }
+    : {
+        accessibilityElementsHidden: true,
+        importantForAccessibility: "no-hide-descendants" as const,
+        "aria-hidden": true,
+      };
 
   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)]}>
-          <BadgeIndicator label={label} color={color} size={size} accessibilityLabel={accessibilityLabel} />
-        </View>
+    <View
+      style={[
+        styles.indicator,
+        labelled ? styles.pill : styles.dot,
+        custom ? { backgroundColor: custom.bg } : null,
+        style,
+      ]}
+      {...rest}
+      {...accessibility}
+    >
+      {labelled ? (
+        <RNText
+          style={[styles.label, { color: resolveThemeColor(foreground, theme) }]}
+          maxFontSizeMultiplier={theme.typography.variants[LABEL_VARIANT[size]].maxFontSizeMultiplier}
+          numberOfLines={1}
+        >
+          {label}
+        </RNText>
       ) : null}
     </View>
   );
-});
-
-export { Badge };
+};
 
 // ─── Styles ───────────────────────────────────────────────────────────────────
 //
-// The indicator'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" },
+// `color` is a plain variant rather than a compound one: `Badge` renders solid
+// only, so there is no second paint axis for it to interact with.
+//
+// React Native's box model is border-box, so the ring below eats into the
+// badge rather than growing it — the dot's outer diameter stays exactly what
+// `size` declares, with no compensation arithmetic, ring or not.
+const styles = StyleSheet.create((theme) => {
+  const c = theme.color;
+  // A custom font encodes its weight in the family name, so only the system
+  // font takes a numeric `fontWeight` — the same branch `Chip` makes. Inlined
+  // rather than extracted: the unistyles Babel plugin rewrites this factory,
+  // and an imported function called from inside it is not in scope at runtime.
+  const labelFont = theme.typography.fonts.semibold;
+  const isSystemLabelFont = labelFont === SYSTEM_FONT;
+
+  return {
+    indicator: {
+      alignItems: "center",
+      justifyContent: "center",
+      borderRadius: theme.radius.full,
+      borderColor: c["surface.canvas"],
+      variants: {
+        // No styles of its own; it only has to exist for the compound rows
+        // below to match on. The ring's width depends on size as well.
+        size: { sm: {}, md: {}, lg: {} },
+        ring: {
+          true: {},
+          false: { borderWidth: 0 },
+        },
+        color: {
+          primary: { backgroundColor: c["accent.solid.bg"] },
+          secondary: { backgroundColor: c["neutral.solid.bg"] },
+          success: { backgroundColor: c["success.solid.bg"] },
+          warning: { backgroundColor: c["warning.solid.bg"] },
+          danger: { backgroundColor: c["danger.solid.bg"] },
+        },
       },
+      compoundVariants: [
+        { ring: true, size: "sm", styles: { borderWidth: 1.5 } },
+        { ring: true, size: "md", styles: { borderWidth: 2 } },
+        { ring: true, size: "lg", styles: { borderWidth: 2 } },
+      ],
     },
-  },
-  anchor: {
-    position: "absolute",
-  },
-}));
+    // These diameters are mirrored by `DOT_SIZE` in `./utils.ts`, which the
+    // anchor arithmetic reads. The Babel plugin needs them literal here, so a
+    // test asserts the two stay equal.
+    dot: {
+      variants: {
+        size: {
+          sm: { width: 12, height: 12 },
+          md: { width: 16, height: 16 },
+          lg: { width: 20, height: 20 },
+        },
+      },
+    },
+    pill: {
+      variants: {
+        size: {
+          sm: { height: 18, minWidth: 18, paddingHorizontal: 5 },
+          md: { height: 22, minWidth: 22, paddingHorizontal: 6 },
+          lg: { height: 26, minWidth: 26, paddingHorizontal: 8 },
+        },
+      },
+    },
+    // Spelled out rather than derived from `LABEL_VARIANT`: the unistyles Babel
+    // plugin reads this object statically, so computed variant keys are not
+    // safe here even though they would resolve correctly under test.
+    label: {
+      textAlign: "center",
+      fontFamily: isSystemLabelFont ? undefined : labelFont,
+      fontWeight: isSystemLabelFont ? FONT_WEIGHT_VALUE.semibold : undefined,
+      variants: {
+        size: {
+          sm: {
+            fontSize: theme.typography.variants["label-sm"].fontSize,
+            lineHeight: theme.typography.variants["label-sm"].lineHeight,
+            letterSpacing: theme.typography.variants["label-sm"].letterSpacing,
+          },
+          md: {
+            fontSize: theme.typography.variants["label-md"].fontSize,
+            lineHeight: theme.typography.variants["label-md"].lineHeight,
+            letterSpacing: theme.typography.variants["label-md"].letterSpacing,
+          },
+          lg: {
+            fontSize: theme.typography.variants["label-lg"].fontSize,
+            lineHeight: theme.typography.variants["label-lg"].lineHeight,
+            letterSpacing: theme.typography.variants["label-lg"].letterSpacing,
+          },
+        },
+      },
+    },
+  };
+});

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";