@multiplatform.one/components 6.7.0 → 7.0.0

package/src/Avatar/index.tsx

@@ -1,15 +1,36 @@
-import type { ReactNode } from "react";
-import { radiusClassProps, useReadableTextOn, useResolvedKnobs } from "@multiplatform.one/theme";
+import { Children, createContext, isValidElement, useContext, type ReactNode } from "react";
+import { UserIcon } from "@phosphor-icons/react";
+import {
+  MIN_PRESS_TARGET,
+  ensureFocusVisibleRing,
+  getGroupPosition,
+  pressTargetHitSlop,
+  radiusClassProps,
+  stackRadiusProps,
+  useReadableTextOn,
+  useResolvedKnobs,
+} from "@multiplatform.one/theme";
+import type { ControlStateProps } from "@multiplatform.one/theme";
 import type { GetProps, SizeTokens } from "tamagui";
-import { Avatar as TamaguiAvatar, SizableText, withStaticProperties } from "tamagui";
+import {
+  Avatar as TamaguiAvatar,
+  SizableText,
+  View,
+  XStack,
+  getVariableValue,
+  withStaticProperties,
+} from "tamagui";
+import { getSize } from "@tamagui/get-token";
 import { componentColors } from "../componentColors";
-import { getInitials } from "./getInitials";
+import { fallbackTone, getInitials } from "./getInitials";
 
-export { getInitials } from "./getInitials";
+export { fallbackTone, fallbackToneIndex, FALLBACK_TONES, getInitials } from "./getInitials";
+export type { FallbackTone } from "./getInitials";
 
 // ── Types ─────────────────────────────────────────────────────
 
 export type AvatarSize = SizeTokens | number;
+export type AvatarStatus = "online" | "busy" | "away" | "offline";
 
 export interface AvatarProps extends Omit<GetProps<typeof TamaguiAvatar>, "children"> {
   /** Image URL. When missing or failing, the initials / fallback slot shows. */
@@ -26,151 +47,348 @@ export interface AvatarProps extends Omit<GetProps<typeof TamaguiAvatar>, "child
   fallbackColor?: string;
   /** Custom fallback node (replaces initials text). */
   fallback?: ReactNode;
-  /** Size token or number. @default "$3" */
+  /** Size token or number. Omit to follow the size recipe. */
   size?: AvatarSize;
-  /** Circular clip (default true for user avatars). */
+  /** Circular clip (default true for people). Square is for orgs/bots (Primer). */
   circular?: boolean;
+  /**
+   * Nested surface (list row, comment, overlay). Paints `nestedControl`
+   * below the 44px floor; density still steps independently.
+   */
+  nested?: boolean;
+  /** Density compact override (not a size). Wins over the density knob. */
+  compact?: boolean;
+  /** Presence pip (Fluent/Primer). Decorative — not a second focusable. */
+  status?: AvatarStatus;
   /** Advanced: compound children (`Avatar.Image` / `Avatar.Fallback`). */
   children?: ReactNode;
 }
 
-// ── Size knob → avatar size mapping ───────────────────────────
+export interface AvatarGroupProps {
+  children: ReactNode;
+  /** Visible faces before the +N overflow. @default 4 (Primer stack cap) */
+  max?: number;
+  size?: AvatarSize;
+  circular?: boolean;
+  nested?: boolean;
+  compact?: boolean;
+  /**
+   * Overlap stack (Primer AvatarStack). `false` lays square faces flush so
+   * LC-72 outer-corners apply; circles stay identity either way.
+   * @default true
+   */
+  overlap?: boolean;
+}
 
-/** One step below the sizeToken body scale; medium keeps the old $3. */
-const avatarSizeMap: Record<string, SizeTokens> = {
-  $3: "$2",
-  $4: "$3",
-  $5: "$4",
+type GroupCtx = {
+  size?: AvatarSize;
+  circular: boolean;
+  nested: boolean;
+  compact?: boolean;
+  overlap: boolean;
+  index: number;
+  count: number;
 };
 
-// ── Identity-shape declaration (D-09 / LC-60) ─────────────────
+const GroupCtx = createContext<GroupCtx | null>(null);
+
+const identityShapeProps = radiusClassProps("R-IDENTITY", "Avatar");
+const pipShapeProps = radiusClassProps("R-PILL", "Avatar status");
 
 /**
- * Avatar is declared R-IDENTITY in the spec's radius-class table: a circular
- * avatar is a recognized object class, not a styled box, so it keeps its
- * circle at `borderRadius:none`. Knob immunity is only legitimate when it is
- * DECLARED — the `radius:none` sweep generates its allowlist from that table
- * and reads this declaration off the DOM, so an undeclared knob-immune shape
- * stays an LC-18 KNOB-TOTALITY defect.
- *
- * The declaration rides `circular`: a consumer that ejects to `circular=false`
- * has opted the part back onto the radius channel and must not be exempt.
+ * Identity-object scale (R-IDENTITY): an avatar is a medallion, not control
+ * chrome, so its diameter rides the flat Tamagui size ramp — resolved LIVE
+ * from the token scale, never a handwritten px mirror (LC-80). The knob
+ * words land one ramp step below the control token (small $2 = 28, medium
+ * $3 = 36, large $4 = 44 — lossless vs the old map). Sub-$1 tokens clamp to
+ * a 16px legibility floor (the raw $0.5 token is 4px).
  */
-const identityShapeProps = radiusClassProps("R-IDENTITY", "Avatar");
+const AVATAR_MIN_PX = 16;
+const AVATAR_KNOB_TOKEN: Record<string, string> = { small: "$2", medium: "$3", large: "$4" };
+
+function avatarTokenPx(token: string): number | undefined {
+  const resolved = getVariableValue(getSize(token as SizeTokens));
+  return typeof resolved === "number" && Number.isFinite(resolved)
+    ? Math.max(AVATAR_MIN_PX, resolved)
+    : undefined;
+}
+
+const STATUS_COLOR: Record<AvatarStatus, string> = {
+  online: "$green10",
+  busy: "$red10",
+  away: "$yellow10",
+  offline: "$color8",
+};
+
+const CUTOUT_BORDER = 2;
+
+function sizeToPx(size: AvatarSize): number | undefined {
+  if (typeof size === "number") return size;
+  return avatarTokenPx(String(size));
+}
+
+function resolveVisualPx(
+  sizeProp: AvatarSize | undefined,
+  nested: boolean,
+  sizeKnob: string,
+  nestedPx: number,
+): number {
+  const mediumPx = avatarTokenPx(AVATAR_KNOB_TOKEN.medium) ?? 36;
+  if (sizeProp != null) return sizeToPx(sizeProp) ?? mediumPx;
+  if (nested) return nestedPx;
+  const knobToken = AVATAR_KNOB_TOKEN[sizeKnob];
+  return (knobToken ? avatarTokenPx(knobToken) : undefined) ?? mediumPx;
+}
+
+function opticalFont(px: number): SizeTokens {
+  if (px <= 20) return "$1";
+  if (px <= 32) return "$2";
+  return "$3";
+}
 
-// ── Size → font mapping ───────────────────────────────────────
-
-function initialsFontSize(size: AvatarSize | undefined): SizeTokens {
-  if (typeof size === "number") {
-    if (size <= 24) return "$1";
-    if (size <= 40) return "$2";
-    return "$3";
-  }
-  switch (size) {
-    case "$0.5":
-    case "$1":
-    case "$1.5":
-      return "$1";
-    case "$2":
-    case "$2.5":
-    case "$3":
-      return "$2";
-    default:
-      return "$3";
-  }
+// The RN/Tamagui `onPress` type is `((event: GestureResponderEvent) => void)
+// | null | undefined`; the ring helper only ever calls it with zero args, so a
+// bottom-arg function type accepts any handler (and null) without a value cast.
+function activateOnEnterSpace(onPress?: ((...args: never[]) => void) | null) {
+  if (!onPress) return undefined;
+  return {
+    onKeyDown: (e: { key?: string; preventDefault?: () => void }) => {
+      if (e.key === "Enter" || e.key === " ") {
+        e.preventDefault?.();
+        onPress();
+      }
+    },
+  };
 }
 
 // ── Avatar ────────────────────────────────────────────────────
 
-/**
- * Themed Avatar: image + initials fallback + size variants.
- * Convenience props (`src`/`name`) cover the desk assigned-user case;
- * compound `Avatar.Image` / `Avatar.Fallback` remain available for advanced layouts.
- */
 function AvatarRoot({
   src,
   name,
   alt,
   initials,
-  fallbackBackgroundColor = "$accentBackground",
+  fallbackBackgroundColor,
   fallbackColor,
   fallback,
   size: sizeProp,
-  circular = true,
+  circular: circularProp,
+  nested: nestedProp = false,
+  compact,
+  status,
   children,
   backgroundColor,
+  onPress,
+  focusStyle,
+  focusVisibleStyle,
+  hitSlop: hitSlopProp,
   ...props
 }: AvatarProps) {
-  // Consumer size ejects; otherwise the size knob drives avatar geometry
-  // (LC-18) — one step below the body scale keeps the previous $3 default.
-  const { knobProps } = useResolvedKnobs();
-  // UX-P20 / Axiom 15: initials on the accent tint need a luminance-computed
-  // foreground — the accent theme's near-white `$color` measured 3.95:1 in
-  // dark; paper/ink-on-fill lands the readable anchor (dark ink → 4.02+).
+  const group = useContext(GroupCtx);
+  const circular = group ? group.circular : (circularProp ?? true);
+  const nested = nestedProp || Boolean(group?.nested);
+  const densityCompact = compact ?? group?.compact;
+  const resolvedSizeProp = sizeProp ?? group?.size;
+  const { knobProps } = useResolvedKnobs({ compact: densityCompact });
+  const visualPx = resolveVisualPx(
+    resolvedSizeProp,
+    nested,
+    knobProps.size,
+    knobProps.nestedControl.px,
+  );
+  const interactive = typeof onPress === "function";
+  const pressSlop =
+    interactive && visualPx < MIN_PRESS_TARGET ? pressTargetHitSlop(visualPx) : undefined;
   const onAccentInitials = useReadableTextOn("$accentBackground");
-  const size = sizeProp ?? avatarSizeMap[knobProps.sizeToken] ?? "$3";
+  const tone = fallbackBackgroundColor || backgroundColor ? undefined : fallbackTone(name);
+  const fallbackBg = backgroundColor ?? fallbackBackgroundColor ?? tone?.bg ?? "$color4";
+  const onAccent = fallbackBg === "$accentBackground";
+  const fallbackFg =
+    fallbackColor ??
+    (onAccent ? (onAccentInitials ?? "$color") : (tone?.fg ?? componentColors.text.primary));
   const identityProps = circular ? identityShapeProps : null;
-  if (children != null) {
-    return (
-      <TamaguiAvatar
-        circular={circular}
-        size={size}
-        backgroundColor={backgroundColor ?? fallbackBackgroundColor}
-        {...identityProps}
-        {...props}
-      >
-        {children}
-      </TamaguiAvatar>
-    );
-  }
-
-  const label = alt ?? name ?? "Avatar";
+  const position = group ? getGroupPosition(group.index, group.count) : undefined;
+  const squareFlush = Boolean(group && !group.overlap && !circular && position);
+  const stackCorners = squareFlush
+    ? stackRadiusProps(position!, knobProps.borderRadius.borderRadius, "horizontal")
+    : undefined;
+  const cutout = Boolean(group?.overlap);
+  const labeled = Boolean(alt || name);
+  const decorative = !labeled && !interactive;
+  const label = alt ?? name ?? (interactive ? "Avatar" : undefined);
   const initialsText = initials ?? (name ? getInitials(name) : "?");
+  const pipPx = Math.max(8, Math.round(visualPx * 0.28));
 
-  const onAccent = fallbackBackgroundColor === "$accentBackground";
-
-  return (
+  const frame = (
     <TamaguiAvatar
-      circular={circular}
-      size={size}
-      backgroundColor={backgroundColor ?? fallbackBackgroundColor}
-      aria-label={label}
+      circular={circular && !stackCorners}
+      size={visualPx}
+      width={visualPx}
+      height={visualPx}
+      minWidth={visualPx}
+      minHeight={visualPx}
+      maxWidth={visualPx}
+      maxHeight={visualPx}
+      backgroundColor={fallbackBg}
+      overflow="hidden"
+      flexShrink={0}
+      outlineWidth={0}
+      onPress={onPress}
+      {...(!circular && !stackCorners ? knobProps.borderRadius : undefined)}
+      {...stackCorners}
+      {...(cutout
+        ? { borderWidth: CUTOUT_BORDER, borderColor: "$background" }
+        : squareFlush && position !== "first" && position !== "only"
+          ? { borderStartWidth: 1, borderColor: knobProps.borderRadius.borderColor }
+          : undefined)}
       {...identityProps}
       {...props}
+      aria-hidden={decorative || undefined}
+      aria-label={decorative ? undefined : label}
+      role={interactive ? "button" : props.role}
+      tabIndex={interactive ? 0 : undefined}
+      cursor={interactive ? "pointer" : undefined}
+      {...activateOnEnterSpace(onPress)}
+      data-avatar-px={visualPx}
+      data-avatar-nested={nested ? "true" : undefined}
+      data-avatar-interactive={interactive ? "true" : undefined}
+      data-avatar-hitslop={pressSlop ? String(pressSlop.top) : undefined}
+      focusStyle={{ outlineWidth: 0, ...focusStyle }}
+      focusVisibleStyle={
+        interactive
+          ? ensureFocusVisibleRing({
+              outlineOffset: -2,
+              ...(focusVisibleStyle as ControlStateProps),
+            })
+          : focusVisibleStyle
+      }
+      hitSlop={pressSlop ?? hitSlopProp}
     >
-      {src ? <TamaguiAvatar.Image src={src} alt={label} /> : null}
-      <TamaguiAvatar.Fallback
-        backgroundColor={fallbackBackgroundColor}
-        alignItems="center"
-        justifyContent="center"
-        // Omit delayMs so Fallback mounts immediately (tamagui treats
-        // delayMs=0 as "wait for timeout" and starts canRender=false).
-        {...(src ? { delayMs: 600 } : {})}
-      >
-        {fallback ?? (
-          <SizableText
-            fontSize={initialsFontSize(size)}
-            // Luminance-computed on-fill foreground (Axiom 15): the paper/ink
-            // anchor that reads best on the resolved accent tint, not the
-            // accent theme's fixed near-white.
-            color={
-              fallbackColor ??
-              (onAccent ? (onAccentInitials ?? "$color") : componentColors.text.primary)
-            }
-            fontWeight="600"
-            textAlign="center"
+      {children != null ? (
+        children
+      ) : (
+        <>
+          {src ? <TamaguiAvatar.Image src={src} alt={label ?? ""} /> : null}
+          <TamaguiAvatar.Fallback
+            backgroundColor={fallbackBg}
+            alignItems="center"
+            justifyContent="center"
+            {...(src ? { delayMs: 600 } : {})}
           >
-            {initialsText}
-          </SizableText>
-        )}
-      </TamaguiAvatar.Fallback>
+            {fallback ??
+              (initialsText === "?" ? (
+                <View {...({ color: fallbackFg } as Record<string, unknown>)}>
+                  <UserIcon size={Math.round(visualPx * 0.42)} color="currentColor" />
+                </View>
+              ) : (
+                <SizableText
+                  {...knobProps.label}
+                  fontSize={opticalFont(visualPx)}
+                  fontWeight="600"
+                  color={fallbackFg}
+                  textAlign="center"
+                  userSelect="none"
+                >
+                  {initialsText}
+                </SizableText>
+              ))}
+          </TamaguiAvatar.Fallback>
+        </>
+      )}
     </TamaguiAvatar>
   );
+
+  if (!status) return frame;
+
+  return (
+    <View position="relative" width={visualPx} height={visualPx} flexShrink={0}>
+      {frame}
+      <View
+        {...pipShapeProps}
+        position="absolute"
+        bottom={-1}
+        right={-1}
+        width={pipPx}
+        height={pipPx}
+        borderRadius={1000}
+        backgroundColor={STATUS_COLOR[status]}
+        borderWidth={2}
+        borderColor="$background"
+        pointerEvents="none"
+      />
+    </View>
+  );
+}
+
+function AvatarGroup({
+  children,
+  max = 4,
+  size,
+  circular = true,
+  nested = false,
+  compact,
+  overlap = true,
+}: AvatarGroupProps) {
+  const { knobProps } = useResolvedKnobs({ compact });
+  const visualPx = resolveVisualPx(size, nested, knobProps.size, knobProps.nestedControl.px);
+  const overlapPx = overlap ? Math.round(visualPx * 0.32) : 0;
+  const items = Children.toArray(children).filter(isValidElement);
+  const shown = items.slice(0, Math.max(1, max));
+  const extra = items.length - shown.length;
+  const total = shown.length + (extra > 0 ? 1 : 0);
+  const overflowLabel = extra > 9 ? "9+" : `+${extra}`;
+
+  return (
+    <XStack
+      alignItems="center"
+      flexShrink={0}
+      gap={0}
+      data-avatar-group=""
+      data-avatar-overlap={overlap ? "true" : "false"}
+    >
+      {shown.map((child, index) => (
+        <GroupCtx.Provider
+          key={index}
+          value={{ size, circular, nested, compact, overlap, index, count: total }}
+        >
+          <View zIndex={index} marginStart={index > 0 ? -overlapPx : 0} flexShrink={0}>
+            {child}
+          </View>
+        </GroupCtx.Provider>
+      ))}
+      {extra > 0 ? (
+        <GroupCtx.Provider
+          value={{
+            size,
+            circular,
+            nested,
+            compact,
+            overlap,
+            index: shown.length,
+            count: total,
+          }}
+        >
+          <View zIndex={shown.length} marginStart={-overlapPx} flexShrink={0}>
+            <AvatarRoot
+              initials={overflowLabel}
+              fallbackBackgroundColor="$color4"
+              fallbackColor="$color12"
+              circular={circular}
+              nested={nested}
+              compact={compact}
+              size={size}
+            />
+          </View>
+        </GroupCtx.Provider>
+      ) : null}
+    </XStack>
+  );
 }
 
 export const Avatar = withStaticProperties(AvatarRoot, {
   Image: TamaguiAvatar.Image,
   Fallback: TamaguiAvatar.Fallback,
+  Group: AvatarGroup,
 });
 
 export type { AvatarProps as AvatarFrameProps };

package/src/Badge/Badge.spec.tsx

@@ -0,0 +1,83 @@
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { describe, expect, it } from "vitest";
+import { Text } from "tamagui";
+import { Badge } from "./index";
+
+describe("Badge", () => {
+  it("hides when count is 0 and shows with showZero", () => {
+    const hidden = renderWithProviders(
+      <Badge count={0}>
+        <Text>Bell</Text>
+      </Badge>,
+    );
+    expect(hidden.container.querySelector("[data-badge]")).toBeNull();
+    expect(hidden.container.textContent).toContain("Bell");
+
+    const shown = renderWithProviders(
+      <Badge count={0} showZero>
+        <Text>Bell</Text>
+      </Badge>,
+    );
+    expect(shown.container.querySelector('[data-badge="count"]')?.textContent).toContain("0");
+  });
+
+  it("renders max+ visually and exposes the exact count to AT (Carbon)", () => {
+    const { container } = renderWithProviders(
+      <Badge count={150} max={99}>
+        <Text>Bell</Text>
+      </Badge>,
+    );
+    const pill = container.querySelector('[data-badge="count"]');
+    expect(pill?.getAttribute("data-overflow")).toBe("true");
+    expect(pill?.textContent).toContain("99+");
+    expect(pill?.getAttribute("aria-label")).toBe("150");
+    expect(pill?.getAttribute("title")).toBe("150");
+  });
+
+  it("treats negative and non-finite counts as empty", () => {
+    const negative = renderWithProviders(
+      <Badge count={-3}>
+        <Text>Bell</Text>
+      </Badge>,
+    );
+    expect(negative.container.querySelector("[data-badge]")).toBeNull();
+
+    const nan = renderWithProviders(
+      <Badge count={Number.NaN}>
+        <Text>Bell</Text>
+      </Badge>,
+    );
+    expect(nan.container.querySelector("[data-badge]")).toBeNull();
+  });
+
+  it("renders a standalone CounterLabel without a host", () => {
+    const { container } = renderWithProviders(<Badge count={12} />);
+    const pill = container.querySelector('[data-badge="count"]');
+    expect(pill).toBeTruthy();
+    expect(pill?.textContent).toContain("12");
+    expect(container.querySelector("[data-badge]")).toBe(pill);
+  });
+
+  it("names a dot as New activity and keeps it a status, not a control", () => {
+    const { container } = renderWithProviders(
+      <Badge dot>
+        <Text>Bell</Text>
+      </Badge>,
+    );
+    const pill = container.querySelector('[data-badge="dot"]');
+    expect(pill?.getAttribute("aria-label")).toBe("New activity");
+    expect(pill?.getAttribute("role")).toBe("status");
+    expect(pill?.getAttribute("tabindex")).toBeNull();
+  });
+
+  it("declares R-PILL on the count/dot (LC-60)", () => {
+    const { container } = renderWithProviders(
+      <Badge count={1}>
+        <Text>Bell</Text>
+      </Badge>,
+    );
+    const el = container.querySelector("[data-radius-class]");
+    expect(el?.getAttribute("data-radius-class")).toBe("R-PILL");
+    expect(el?.getAttribute("data-radius-part")).toBe("Badge count/dot");
+  });
+});

package/src/Badge/Badge.stories.tsx

@@ -23,6 +23,7 @@ const meta: Meta<typeof Badge> = {
     showZero: { control: "boolean", description: "Show badge when count is 0" },
     dot: { control: "boolean", description: "Show as a dot instead of count" },
     visible: { control: "boolean", description: "Whether the badge is visible" },
+    compact: { control: "boolean", description: "Compact density (steps size down)" },
     color: { control: "select", options: ["red", "blue", "green", "orange", "gray"] },
     position: {
       control: "select",
@@ -125,6 +126,19 @@ export const MaxCount: Story = {
   ),
 };
 
+export const Standalone: Story = {
+  name: "Standalone (CounterLabel)",
+  render: () => (
+    <XStack gap="$3" alignItems="center">
+      <Badge count={3} />
+      <Badge count={12} color="blue" />
+      <Badge count={150} max={99} color="orange" />
+      <Badge dot color="green" />
+      <Badge count={0} showZero color="gray" />
+    </XStack>
+  ),
+};
+
 export const DotVariant: Story = {
   render: () => (
     <XStack gap="$4">
@@ -309,7 +323,7 @@ export const OnButtons: Story = {
 
 export const AllStates: Story = {
   render: () => (
-    <YStack gap="$6">
+    <YStack gap="$6" padding="$3">
       <YStack gap="$2">
         <Text fontWeight="600">Counts</Text>
         <XStack gap="$4">