@12-apps/ui 6.19.0 → 6.20.0

package/src/components/data-display/Avatar/Avatar.native.tsx

@@ -0,0 +1,190 @@
+import * as React from 'react';
+import { Animated, StyleSheet, View } from 'react-native';
+
+import type { AvatarSize, AvatarVariant } from './Avatar.base';
+import {
+  AVATAR_DEFAULTS,
+  avatarTestId,
+  contentTypeOf,
+  pickAvatarContent,
+} from './Avatar.helpers';
+import { avatarStatusDotStyle } from './Avatar.look.native';
+import { GROUP_MAX, GROUP_OVERLAP, avatarAccent, statusColor } from './Avatar.metrics';
+import {
+  AvatarSurface,
+  PulseRing,
+  contentNode,
+  useFadeIn,
+  useImageState,
+  type SurfaceArgs,
+} from './Avatar.parts.native';
+import type { AvatarGroupProps, AvatarProps } from './Avatar.types.native';
+import { useUiTheme } from '../../../provider/use-ui-theme.native';
+import type { ColorValue } from '../../../tokens/vocabulary';
+
+interface AvatarModel {
+  args: SurfaceArgs;
+  variant: AvatarVariant;
+  size: AvatarSize;
+  color: ColorValue;
+  pulse: boolean;
+  status?: AvatarProps['status'];
+  opacity: Animated.Value;
+  badgeTestID?: string;
+}
+
+/** Normalises the props and derives everything the surface needs, as the web's model does. */
+function useAvatarModel(raw: AvatarProps): AvatarModel {
+  const {
+    variant,
+    size,
+    glow,
+    pulse,
+    status,
+    fallback,
+    icon,
+    bordered,
+    color,
+    src,
+    alt,
+    children,
+    loading,
+    onError,
+    onClick,
+    onPress,
+    interactive,
+    showFallbackOnError,
+    animationDelay,
+    dataTestId,
+    testID,
+    style,
+    ...rest
+  } = { ...AVATAR_DEFAULTS, ...raw };
+  const theme = useUiTheme();
+  const opacity = useFadeIn(animationDelay);
+  const { imageError, imageLoading, handleError, handleLoad } = useImageState(src, onError);
+  const pick = pickAvatarContent({
+    hasChildren: Boolean(children),
+    hasFallback: Boolean(fallback),
+    hasIcon: Boolean(icon),
+    imageError,
+    showFallbackOnError,
+  });
+  const avatarId = testID ?? dataTestId;
+  const idFor = avatarTestId(avatarId);
+
+  return {
+    variant,
+    size,
+    color,
+    pulse,
+    status,
+    opacity,
+    badgeTestID: idFor('badge'),
+    args: {
+      variant,
+      size,
+      color,
+      glow,
+      bordered,
+      clickable: interactive || Boolean(onClick ?? onPress),
+      imageError,
+      showSpinner: loading || imageLoading,
+      imgSrc: imageError ? undefined : src,
+      alt,
+      ariaLabel: alt || 'Avatar',
+      content: contentNode({
+        pick,
+        children,
+        fallback,
+        icon,
+        ink: avatarAccent(theme, color).contrastText,
+      }),
+      contentType: contentTypeOf(pick),
+      testID: avatarId,
+      idFor,
+      style,
+      onPress: (event) => {
+        onClick?.();
+        onPress?.(event);
+      },
+      onImageError: handleError,
+      onImageLoad: handleLoad,
+      rest,
+    },
+  };
+}
+
+/**
+ * The native `Avatar`: MUI's box on a `Pressable`, the portrait as an `Image`,
+ * and the status dot as a bordered circle in the corner.
+ */
+export const Avatar = React.forwardRef<View, AvatarProps>((raw, ref) => {
+  const theme = useUiTheme();
+  const { args, variant, size, color, pulse, status, opacity, badgeTestID } = useAvatarModel(raw);
+
+  const surface = (
+    <Animated.View style={[styles.relative, { opacity }]}>
+      {pulse ? (
+        <PulseRing size={size} variant={variant} color={avatarAccent(theme, color).main} />
+      ) : null}
+      <AvatarSurface {...args} forwardedRef={ref} />
+    </Animated.View>
+  );
+
+  if (variant !== 'status' || !status) return surface;
+
+  return (
+    <View testID={badgeTestID} style={styles.relative}>
+      {surface}
+      <View style={avatarStatusDotStyle(theme, size, statusColor(theme, status))} />
+    </View>
+  );
+});
+
+Avatar.displayName = 'Avatar';
+
+/**
+ * The native `AvatarGroup`: the same overlap, and the same `+n` avatar past
+ * `max`. The web additionally lifts an avatar on hover, which touch has none of.
+ */
+export const AvatarGroup: React.FC<AvatarGroupProps> = ({
+  children,
+  max = GROUP_MAX,
+  overlap = GROUP_OVERLAP,
+  dataTestId,
+  testID,
+  style,
+}) => {
+  const all = React.Children.toArray(children);
+  const visible = max ? all.slice(0, max) : all;
+  const remaining = all.length - visible.length;
+  const groupId = testID ?? dataTestId;
+
+  return (
+    <View testID={groupId} style={[styles.group, style]}>
+      {visible.map((child, index) => (
+        <View key={`avatar-${index}`} style={index === 0 ? null : { marginLeft: -overlap }}>
+          {child}
+        </View>
+      ))}
+      {remaining > 0 ? (
+        <View style={{ marginLeft: -overlap }}>
+          <Avatar
+            color="neutral"
+            fallback={`+${remaining}`}
+            bordered
+            dataTestId={groupId ? `${groupId}-overflow` : undefined}
+          />
+        </View>
+      ) : null}
+    </View>
+  );
+};
+
+AvatarGroup.displayName = 'AvatarGroup';
+
+const styles = StyleSheet.create({
+  relative: { position: 'relative', alignSelf: 'flex-start' },
+  group: { flexDirection: 'row', alignItems: 'center', alignSelf: 'flex-start' },
+});

package/src/components/data-display/Avatar/Avatar.parts.native.tsx

@@ -0,0 +1,243 @@
+/**
+ * THE PIECES THE NATIVE `Avatar` IS ASSEMBLED FROM.
+ *
+ * Split out of `Avatar.native.tsx` so the component itself reads as structure:
+ * the mount fade, the portrait's load state, the content node, the pulse ring,
+ * the spinner and the surface they all sit on.
+ */
+import * as React from 'react';
+import {
+  Animated,
+  Easing,
+  Image,
+  Platform,
+  Pressable,
+  StyleSheet,
+  View,
+  type GestureResponderEvent,
+  type StyleProp,
+  type ViewStyle,
+} from 'react-native';
+
+import type { AvatarSize, AvatarVariant, ContentType } from './Avatar.base';
+import type { AvatarContentPick } from './Avatar.helpers';
+import {
+  avatarLoadingStyle,
+  avatarRadius,
+  avatarSpinnerStyle,
+  avatarSurfaceStyle,
+  avatarTextStyle,
+} from './Avatar.look.native';
+import { AVATAR_SIZES, FADE_MS, GLYPH_SIZE, PULSE, SPINNER } from './Avatar.metrics';
+import { Icon } from '../../../icons/Icon.native';
+import { useLoopedProgress } from '../../../platform/animation';
+import { renderTextChildren } from '../../../platform/text-children';
+import { useUiTheme } from '../../../provider/use-ui-theme.native';
+import type { UiTheme } from '../../../tokens/theme';
+import type { ColorValue } from '../../../tokens/vocabulary';
+
+const nativeDriver = Platform.OS !== 'web';
+
+/** MUI's `Fade`: in over 300ms, once `animationDelay` has run. */
+export function useFadeIn(animationDelay: number): Animated.Value {
+  const opacity = React.useRef(new Animated.Value(0)).current;
+  React.useEffect(() => {
+    const animation = Animated.sequence([
+      Animated.delay(animationDelay),
+      Animated.timing(opacity, {
+        toValue: 1,
+        duration: FADE_MS,
+        easing: Easing.out(Easing.ease),
+        useNativeDriver: nativeDriver,
+      }),
+    ]);
+    animation.start();
+    return () => animation.stop();
+  }, [animationDelay, opacity]);
+  return opacity;
+}
+
+interface ImageState {
+  imageError: boolean;
+  imageLoading: boolean;
+  handleError: () => void;
+  handleLoad: () => void;
+}
+
+/** The portrait's load lifecycle: loading from the moment there is a `src`. */
+export function useImageState(src: string | undefined, onError?: () => void): ImageState {
+  const [imageError, setImageError] = React.useState(false);
+  const [imageLoading, setImageLoading] = React.useState(Boolean(src));
+
+  React.useEffect(() => {
+    setImageError(false);
+    setImageLoading(Boolean(src));
+  }, [src]);
+
+  const handleError = React.useCallback(() => {
+    setImageError(true);
+    setImageLoading(false);
+    onError?.();
+  }, [onError]);
+
+  return {
+    imageError,
+    imageLoading,
+    handleError,
+    handleLoad: React.useCallback(() => setImageLoading(false), []),
+  };
+}
+
+interface ContentArgs {
+  pick: AvatarContentPick;
+  children?: React.ReactNode;
+  fallback?: string;
+  icon?: React.ReactNode;
+  ink: string;
+}
+
+/** The node behind the winning content slot; the pick itself is shared. */
+export function contentNode({ pick, children, fallback, icon, ink }: ContentArgs): React.ReactNode {
+  if (pick === 'children') return children;
+  if (pick === 'fallback') return fallback;
+  if (pick === 'icon') return icon;
+  return <Icon name={pick === 'broken' ? 'BrokenImage' : 'Person'} size={GLYPH_SIZE} color={ink} />;
+}
+
+/**
+ * MUI's `::after` pulse ring: the accent growing 10px past the box while it
+ * fades out, every two seconds. React Native has no pseudo-element, so it is a
+ * sibling behind the avatar.
+ */
+export function PulseRing({ size, variant, color }: { size: AvatarSize; variant: AvatarVariant; color: string }): React.JSX.Element {
+  const theme = useUiTheme();
+  const progress = useLoopedProgress(true, { durationMs: PULSE.durationMs });
+  const box = AVATAR_SIZES[size].box;
+  return (
+    <Animated.View
+      aria-hidden
+      style={[
+        StyleSheet.absoluteFill,
+        {
+          pointerEvents: 'none',
+          borderRadius: avatarRadius(theme, variant, box),
+          backgroundColor: color,
+          opacity: progress.interpolate({ inputRange: [0, 0.7, 1], outputRange: [PULSE.alpha, 0, 0] }),
+          transform: [
+            {
+              scale: progress.interpolate({
+                inputRange: [0, 0.7, 1],
+                outputRange: [1, (box + PULSE.spread * 2) / box, 1],
+              }),
+            },
+          ],
+        },
+      ]}
+    />
+  );
+}
+
+/** MUI's `rotateAnimation`: the ring turning once every 0.8s. */
+function Spinner({ size, testID }: { size: AvatarSize; testID?: string }): React.JSX.Element {
+  const theme = useUiTheme();
+  const progress = useLoopedProgress(true, { durationMs: SPINNER.durationMs });
+  return (
+    <Animated.View
+      testID={testID}
+      style={[
+        avatarSpinnerStyle(theme, size),
+        {
+          transform: [
+            { rotate: progress.interpolate({ inputRange: [0, 1], outputRange: ['0deg', '360deg'] }) },
+          ],
+        },
+      ]}
+    />
+  );
+}
+
+export interface SurfaceArgs {
+  variant: AvatarVariant;
+  size: AvatarSize;
+  color: ColorValue;
+  glow: boolean;
+  bordered: boolean;
+  clickable: boolean;
+  imageError: boolean;
+  showSpinner: boolean;
+  imgSrc?: string;
+  alt?: string;
+  ariaLabel: string;
+  content: React.ReactNode;
+  contentType: ContentType;
+  testID?: string;
+  idFor: (suffix: string) => string | undefined;
+  style?: StyleProp<ViewStyle>;
+  onPress?: (event: GestureResponderEvent) => void;
+  onImageError: () => void;
+  onImageLoad: () => void;
+  rest: object;
+}
+
+/** What sits in the middle: the portrait, or the winning content slot. */
+function SurfaceInner(a: SurfaceArgs, theme: UiTheme): React.JSX.Element | null {
+  if (a.imgSrc && !a.imageError) {
+    return (
+      <Image
+        source={{ uri: a.imgSrc }}
+        aria-label={a.alt}
+        onError={a.onImageError}
+        onLoad={a.onImageLoad}
+        style={StyleSheet.absoluteFill}
+        accessibilityIgnoresInvertColors
+      />
+    );
+  }
+  if (a.showSpinner) return null;
+  return (
+    <View testID={a.idFor(a.contentType)}>
+      {renderTextChildren(a.content, avatarTextStyle(theme, a.size, a.color, a.imageError), 1)}
+    </View>
+  );
+}
+
+/** The avatar box itself, plus the overlay that covers it while it loads. */
+export function AvatarSurface(a: SurfaceArgs & { forwardedRef?: React.Ref<View> }): React.JSX.Element {
+  const theme = useUiTheme();
+  const box = AVATAR_SIZES[a.size].box;
+  return (
+    <>
+      <Pressable
+        ref={a.forwardedRef}
+        testID={a.testID}
+        role={a.clickable ? 'button' : undefined}
+        aria-label={a.ariaLabel}
+        tabIndex={a.clickable ? 0 : -1}
+        onPress={a.clickable ? a.onPress : undefined}
+        style={[
+          avatarSurfaceStyle(theme, {
+            variant: a.variant,
+            size: a.size,
+            color: a.color,
+            glow: a.glow,
+            bordered: a.bordered,
+            interactive: a.clickable,
+            hasError: a.imageError,
+          }),
+          a.style,
+        ]}
+        {...a.rest}
+      >
+        {SurfaceInner(a, theme)}
+      </Pressable>
+      {a.showSpinner ? (
+        <View
+          testID={a.idFor('loading')}
+          style={avatarLoadingStyle(theme, a.size, avatarRadius(theme, a.variant, box))}
+        >
+          <Spinner size={a.size} testID={a.idFor('loading-spinner')} />
+        </View>
+      ) : null}
+    </>
+  );
+}

package/src/components/data-display/Avatar/Avatar.tsx

@@ -3,28 +3,17 @@ import Person from '@mui/icons-material/Person';
 import { styled } from '@mui/material/styles/index.js';
 import React, { useCallback, useEffect, useState } from 'react';
 
-import type { AvatarProps } from './Avatar.types';
-import { AvatarView, type AvatarViewProps, type ContentType } from './Avatar.view';
-
-/** Applied via a single spread so no per-field default inflates cyclomatic complexity. */
-const AVATAR_DEFAULTS = {
-  variant: 'circle',
-  size: 'md',
-  glow: false,
-  pulse: false,
-  bordered: false,
-  color: 'primary',
-  loading: false,
-  interactive: false,
-  showFallbackOnError: true,
-  animationDelay: 0,
-} satisfies Partial<AvatarProps>;
-
-/**
- * Pick what renders inside the avatar. On an image error (with fallback enabled)
- * the fallback/icon/broken-image wins; otherwise children → fallback → icon → the
- * default person glyph.
- */
+import {
+  AVATAR_DEFAULTS,
+  contentTypeOf,
+  pickAvatarContent,
+  type AvatarContentPick,
+} from './Avatar.helpers';
+import { GROUP_MAX, GROUP_OVERLAP, GROUP_HOVER, BORDER_WIDTH } from './Avatar.metrics';
+import type { AvatarProps, ContentType } from './Avatar.types';
+import { AvatarView, type AvatarViewProps } from './Avatar.view';
+
+/** The node behind the winning content slot; the pick itself is shared. */
 function resolveContent(args: {
   children?: React.ReactNode;
   fallback?: React.ReactNode;
@@ -33,15 +22,21 @@ function resolveContent(args: {
   showFallbackOnError: boolean;
 }): { content: React.ReactNode; contentType: ContentType } {
   const { children, fallback, icon, imageError, showFallbackOnError } = args;
-  if (imageError && showFallbackOnError) {
-    if (fallback) return { content: fallback, contentType: 'fallback' };
-    if (icon) return { content: icon, contentType: 'icon' };
-    return { content: <BrokenImage />, contentType: 'icon' };
-  }
-  if (children) return { content: children, contentType: 'children' };
-  if (fallback) return { content: fallback, contentType: 'fallback' };
-  if (icon) return { content: icon, contentType: 'icon' };
-  return { content: <Person />, contentType: 'default' };
+  const pick = pickAvatarContent({
+    hasChildren: Boolean(children),
+    hasFallback: Boolean(fallback),
+    hasIcon: Boolean(icon),
+    imageError,
+    showFallbackOnError,
+  });
+  const NODES: Record<AvatarContentPick, React.ReactNode> = {
+    children,
+    fallback,
+    icon,
+    broken: <BrokenImage />,
+    default: <Person />,
+  };
+  return { content: NODES[pick], contentType: contentTypeOf(pick) };
 }
 
 /** Fades the avatar in after `animationDelay`ms. */
@@ -112,6 +107,9 @@ function useAvatarModel(raw: AvatarProps, ref: React.Ref<HTMLDivElement>): Avata
     animationDelay,
     className,
     dataTestId,
+    // React Native's spelling of the same id; it names the component on both
+    // sides and must not reach the DOM as an attribute.
+    testID,
     ...rest
   } = { ...AVATAR_DEFAULTS, ...raw };
 
@@ -146,7 +144,7 @@ function useAvatarModel(raw: AvatarProps, ref: React.Ref<HTMLDivElement>): Avata
     content,
     contentType,
     className,
-    dataTestId,
+    dataTestId: testID ?? dataTestId,
     status,
     forwardedRef: ref,
     onClick: handleClick,
@@ -162,17 +160,17 @@ export const Avatar = React.forwardRef<HTMLDivElement, AvatarProps>((props, ref)
 
 Avatar.displayName = 'Avatar';
 
-const AvatarGroupContainer = styled('div')<{ overlap?: number }>(({ theme, overlap = 8 }) => ({
+const AvatarGroupContainer = styled('div')<{ overlap?: number }>(({ theme, overlap = GROUP_OVERLAP }) => ({
   display: 'flex',
   alignItems: 'center',
   '& > *': {
     marginLeft: -overlap,
     transition: 'all 0.3s ease',
     position: 'relative',
-    border: `2px solid ${theme.palette.background.paper}`,
+    border: `${BORDER_WIDTH}px solid ${theme.palette.background.paper}`,
     '&:hover': {
       zIndex: 100,
-      transform: 'scale(1.1) translateY(-4px)',
+      transform: `scale(${GROUP_HOVER.scale}) translateY(-${GROUP_HOVER.lift}px)`,
     },
     '&:first-of-type': {
       marginLeft: 0,
@@ -187,7 +185,7 @@ export const AvatarGroup: React.FC<{
   overlap?: number;
   className?: string;
   dataTestId?: string;
-}> = ({ children, max = 4, overlap = 8, className, dataTestId }) => {
+}> = ({ children, max = GROUP_MAX, overlap = GROUP_OVERLAP, className, dataTestId }) => {
   const childrenArray = React.Children.toArray(children);
   const visibleChildren = max ? childrenArray.slice(0, max) : childrenArray;
   const remainingCount = childrenArray.length - visibleChildren.length;

package/src/components/data-display/Avatar/Avatar.types.native.ts

@@ -0,0 +1,39 @@
+import type {
+  GestureResponderEvent,
+  PressableProps,
+  StyleProp,
+  ViewStyle,
+} from 'react-native';
+
+import type { AvatarBaseProps } from './Avatar.base';
+
+export type {
+  AvatarBaseProps,
+  AvatarSize,
+  AvatarStatus,
+  AvatarVariant,
+  ContentType,
+} from './Avatar.base';
+
+/**
+ * The native `Avatar`. `onClick` keeps its web name — a shared screen should
+ * not have to know which renderer it is on — and `onPress` is accepted too,
+ * because that is what a React Native developer will reach for. Both fire.
+ */
+export type AvatarProps = AvatarBaseProps &
+  Omit<PressableProps, keyof AvatarBaseProps | 'style' | 'onPress'> & {
+    onClick?: () => void;
+    onPress?: (event: GestureResponderEvent) => void;
+    /** Fires when the portrait cannot be loaded. */
+    onError?: () => void;
+    style?: StyleProp<ViewStyle>;
+  };
+
+export interface AvatarGroupProps {
+  children?: React.ReactNode;
+  max?: number;
+  overlap?: number;
+  dataTestId?: string;
+  testID?: string;
+  style?: StyleProp<ViewStyle>;
+}

package/src/components/data-display/Avatar/Avatar.types.ts

@@ -1,84 +1,20 @@
-import type { ColorValue, SizeValue } from '../../../tokens/scales';
 import type { AvatarProps as MuiAvatarProps } from '@mui/material/Avatar/index.js';
 import type React from 'react';
 
-/**
- * The house scale, EXTENDED by one stop rather than replacing it.
- *
- * `xxl` is real — an avatar is the one component with a portrait size above the
- * scale's top — so it is added to `SizeValue` instead of the union being
- * rewritten by hand. Spelling all six out again is how the copy drifts.
- */
-export type AvatarSize = SizeValue | 'xxl';
-export type AvatarVariant = 'circle' | 'square' | 'rounded' | 'status';
-export type AvatarStatus = 'online' | 'offline' | 'away' | 'busy';
+import type { AvatarBaseProps } from './Avatar.base';
 
-export interface AvatarProps extends Omit<MuiAvatarProps, 'variant'> {
-  /**
-   * The variant of the avatar
-   */
-  variant?: AvatarVariant;
-
-  /**
-   * The size of the avatar
-   */
-  size?: AvatarSize;
-
-  /**
-   * Whether the avatar should have a glow effect
-   */
-  glow?: boolean;
-
-  /**
-   * Whether the avatar should have a pulse animation
-   */
-  pulse?: boolean;
-
-  /**
-   * Status indicator (only applies when variant is 'status')
-   */
-  status?: AvatarStatus;
-
-  /**
-   * Fallback text when no src is provided (typically initials)
-   */
-  fallback?: string;
-
-  /**
-   * Custom icon to display
-   */
-  icon?: React.ReactNode;
-
-  /**
-   * Whether to show a border around the avatar
-   */
-  bordered?: boolean;
-
-  /**
-   * Color of the avatar background when no image is provided
-   */
-  color?: ColorValue;
-
-  /**
-   * Whether the avatar is in a loading state
-   */
-  loading?: boolean;
-
-  /**
-   * Whether the avatar should be interactive (show hover effects)
-   */
-  interactive?: boolean;
-
-  /**
-   * Whether to show fallback content on image error
-   */
-  showFallbackOnError?: boolean;
-
-  /**
-   * Animation delay in milliseconds
-   */
-  animationDelay?: number;
+export type {
+  AvatarBaseProps,
+  AvatarSize,
+  AvatarStatus,
+  AvatarVariant,
+  ContentType,
+} from './Avatar.base';
 
+/** The web `Avatar`: the shared contract, plus MUI's own avatar props. */
+export interface AvatarProps
+  extends AvatarBaseProps,
+    Omit<MuiAvatarProps, 'variant' | 'color' | 'children' | 'src' | 'alt'> {
   /**
    * Error handler for image loading
    */
@@ -88,9 +24,4 @@ export interface AvatarProps extends Omit<MuiAvatarProps, 'variant'> {
    * Click handler
    */
   onClick?: (event: React.MouseEvent<HTMLDivElement>) => void;
-
-  /**
-   * Test ID for automated testing
-   */
-  dataTestId?: string;
 }