@12-apps/ui 6.19.1 → 6.21.0

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

@@ -0,0 +1,54 @@
+import type { AvatarBaseProps, ContentType } from './Avatar.base';
+
+/** Applied via a single spread so no per-field default inflates cyclomatic complexity. */
+export 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<AvatarBaseProps>;
+
+/** What wins the middle of the avatar. `broken` is the icon slot's error glyph. */
+export type AvatarContentPick = ContentType | 'broken';
+
+export interface AvatarContentArgs {
+  hasChildren: boolean;
+  hasFallback: boolean;
+  hasIcon: boolean;
+  imageError: boolean;
+  showFallbackOnError: boolean;
+}
+
+/**
+ * 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.
+ *
+ * The DECISION is shared; each renderer builds its own node from it, because
+ * the two draw a glyph with different things.
+ */
+export function pickAvatarContent(a: AvatarContentArgs): AvatarContentPick {
+  if (a.imageError && a.showFallbackOnError) {
+    if (a.hasFallback) return 'fallback';
+    return a.hasIcon ? 'icon' : 'broken';
+  }
+  if (a.hasChildren) return 'children';
+  if (a.hasFallback) return 'fallback';
+  return a.hasIcon ? 'icon' : 'default';
+}
+
+/** The slot id a pick takes; the broken-image glyph shares the icon slot's. */
+export const contentTypeOf = (pick: AvatarContentPick): ContentType =>
+  pick === 'broken' ? 'icon' : pick;
+
+/** `${dataTestId}-loading`, or nothing at all when the caller named nothing. */
+export const avatarTestId =
+  (dataTestId?: string) =>
+  (suffix: string): string | undefined =>
+    dataTestId ? `${dataTestId}-${suffix}` : undefined;

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

@@ -0,0 +1,123 @@
+import type { TextStyle, ViewStyle } from 'react-native';
+
+import type { AvatarSize, AvatarVariant } from './Avatar.base';
+import {
+  AVATAR_SIZES,
+  BORDER_HALO_ALPHA,
+  BORDER_WIDTH,
+  GLOW,
+  LOADING_OVERLAY,
+  ROUNDED_RADIUS_UNITS,
+  SPINNER,
+  STATUS_DOT,
+  avatarAccent,
+} from './Avatar.metrics';
+import { alpha } from '../../../tokens/color';
+import type { UiTheme } from '../../../tokens/theme';
+import type { ColorValue } from '../../../tokens/vocabulary';
+
+/** `square` is sharp, `rounded` takes a spacing unit, `circle` and `status` are round. */
+export function avatarRadius(theme: UiTheme, variant: AvatarVariant, box: number): number {
+  if (variant === 'square') return 0;
+  if (variant === 'rounded') return theme.spacing(ROUNDED_RADIUS_UNITS);
+  return box / 2;
+}
+
+export interface AvatarSurfaceArgs {
+  variant: AvatarVariant;
+  size: AvatarSize;
+  color: ColorValue;
+  glow: boolean;
+  bordered: boolean;
+  interactive: boolean;
+  hasError: boolean;
+}
+
+/** The avatar box: MUI's square, its radius, the accent behind the initials. */
+export function avatarSurfaceStyle(theme: UiTheme, a: AvatarSurfaceArgs): ViewStyle {
+  const { box } = AVATAR_SIZES[a.size];
+  const accent = avatarAccent(theme, a.color);
+  return {
+    width: box,
+    height: box,
+    borderRadius: avatarRadius(theme, a.variant, box),
+    alignItems: 'center',
+    justifyContent: 'center',
+    overflow: 'hidden',
+    backgroundColor: a.hasError ? theme.palette.danger.main : accent.main,
+    cursor: a.interactive ? 'pointer' : 'auto',
+    ...(a.bordered
+      ? {
+          borderWidth: BORDER_WIDTH,
+          borderColor: theme.palette.background.paper,
+          boxShadow: `0 0 0 1px ${alpha(theme.palette.divider, BORDER_HALO_ALPHA)}`,
+        }
+      : {}),
+    ...(a.glow
+      ? { boxShadow: `0 0 ${GLOW.blur}px ${GLOW.spread}px ${alpha(accent.main, GLOW.alpha)}` }
+      : {}),
+  };
+}
+
+/** The initials, in the accent's contrast ink at the size's own step. */
+export function avatarTextStyle(
+  theme: UiTheme,
+  size: AvatarSize,
+  color: ColorValue,
+  hasError: boolean,
+): TextStyle {
+  const accent = avatarAccent(theme, color);
+  return {
+    fontFamily: theme.typography.fontFamily,
+    fontSize: AVATAR_SIZES[size].fontSize,
+    textAlign: 'center',
+    color: hasError ? theme.palette.danger.contrastText : accent.contrastText,
+  };
+}
+
+/** The wash over a loading avatar, and the ring spinning in it. */
+export function avatarLoadingStyle(theme: UiTheme, size: AvatarSize, radius: number): ViewStyle {
+  const { box } = AVATAR_SIZES[size];
+  return {
+    position: 'absolute',
+    top: 0,
+    left: 0,
+    width: box,
+    height: box,
+    borderRadius: radius,
+    alignItems: 'center',
+    justifyContent: 'center',
+    backgroundColor: alpha(theme.palette.background.paper, LOADING_OVERLAY.paperAlpha),
+  };
+}
+
+export function avatarSpinnerStyle(theme: UiTheme, size: AvatarSize): ViewStyle {
+  const ring = AVATAR_SIZES[size].box * SPINNER.scale;
+  return {
+    width: ring,
+    height: ring,
+    borderRadius: ring / 2,
+    borderWidth: SPINNER.ringWidth,
+    borderColor: alpha(theme.palette.primary.main, SPINNER.trackAlpha),
+    borderTopColor: theme.palette.primary.main,
+  };
+}
+
+/** MUI's `Badge` dot, anchored bottom-right of a circular avatar. */
+export function avatarStatusDotStyle(theme: UiTheme, size: AvatarSize, color: string): ViewStyle {
+  const { box } = AVATAR_SIZES[size];
+  const dot = Math.max(STATUS_DOT.min, box * STATUS_DOT.scale);
+  // MUI's `overlap="circular"` puts the dot's centre 14% in from the corner.
+  const inset = box * STATUS_DOT.anchor - dot / 2;
+  return {
+    position: 'absolute',
+    right: inset,
+    bottom: inset,
+    width: dot,
+    height: dot,
+    borderRadius: dot / 2,
+    backgroundColor: color,
+    borderWidth: STATUS_DOT.borderWidth,
+    borderColor: theme.palette.background.paper,
+  };
+}

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

@@ -0,0 +1,111 @@
+import type { AvatarSize, AvatarStatus } from './Avatar.base';
+import type { UiTheme } from '../../../tokens/theme';
+import type { ColorValue } from '../../../tokens/vocabulary';
+
+/**
+ * THE NUMBERS BOTH `Avatar` RENDERERS DRAW WITH.
+ *
+ * `Avatar.view.tsx` (web, emotion over MUI's `Avatar` and `Badge`) and
+ * `Avatar.native.tsx` (React Native) read this one table: the six boxes and
+ * their type, the status dot, the glow, the shimmer and the spinner. The web
+ * turns the px into rem; native uses the numbers.
+ */
+export interface AvatarSizeMetrics {
+  /** The square the portrait fills, in px. */
+  box: number;
+  /** The initials' type size, in px. */
+  fontSize: number;
+}
+
+export const AVATAR_SIZES: Record<AvatarSize, AvatarSizeMetrics> = {
+  xs: { box: 24, fontSize: 12 },
+  sm: { box: 32, fontSize: 14 },
+  md: { box: 40, fontSize: 16 },
+  lg: { box: 48, fontSize: 18 },
+  xl: { box: 64, fontSize: 24 },
+  xxl: { box: 80, fontSize: 32 },
+};
+
+/** `rounded` takes one spacing unit; `circle` and `status` are round. */
+export const ROUNDED_RADIUS_UNITS = 1;
+
+/** The paper ring an avatar takes inside a group, and the hairline outside it. */
+export const BORDER_WIDTH = 2;
+export const BORDER_HALO_ALPHA = 0.2;
+
+/** `glow`: a 20px halo at five pixels of spread, and a brightness lift. */
+export const GLOW = { blur: 20, spread: 5, alpha: 0.4, brightness: 1.05 } as const;
+
+/** `pulse`: the `::after` ring, from nothing to 10px while it fades out. */
+export const PULSE = { durationMs: 2000, alpha: 0.3, spread: 10 } as const;
+
+/** The shimmer that runs across a loading avatar. */
+export const SHIMMER = { durationMs: 1500, fromAlpha: 0.6, toAlpha: 0.8 } as const;
+
+/** The overlay over a loading avatar, and the ring spinning in it. */
+export const LOADING_OVERLAY = { paperAlpha: 0.7, blur: 2 } as const;
+export const SPINNER = {
+  /** A share of the avatar's box. */
+  scale: 0.4,
+  ringWidth: 2,
+  trackAlpha: 0.3,
+  durationMs: 800,
+} as const;
+
+/**
+ * The status dot: a fifth of the box, never below 8px, inside a paper ring.
+ * `anchor` is MUI's `overlap="circular"` inset — the dot's CENTRE sits 14% of
+ * the box in from the bottom-right corner.
+ */
+export const STATUS_DOT = { scale: 0.2, min: 8, borderWidth: 2, anchor: 0.14 } as const;
+
+/**
+ * The default and broken-image glyphs are ordinary `SvgIcon`s here, not MUI's
+ * own `.MuiAvatar-fallback` (which is 75% of the box): this component passes
+ * them as CHILDREN, so they render at the icon default whatever the box is.
+ */
+export const GLYPH_SIZE = 24;
+
+/** MUI's `Fade` timeout on mount, and the scale-in behind it. */
+export const FADE_MS = 300;
+export const SCALE_IN_MS = 300;
+
+/** `transition: all 0.3s cubic-bezier(0.4, 0, 0.2, 1)`. */
+export const AVATAR_TRANSITION_MS = 300;
+export const AVATAR_TRANSITION_EASING = 'cubic-bezier(0.4, 0, 0.2, 1)';
+
+/** The interactive lift, which is a `:hover` on the web. */
+export const HOVER = { scale: 1.1, lift: 2, shadowY: 8, shadowBlur: 20, shadowAlpha: 0.3, brightness: 1.1 } as const;
+export const ACTIVE_SCALE = 1.05;
+
+/** The focus ring `:focus-visible` draws. */
+export const FOCUS_RING = { width: 3, offset: 2, alpha: 0.5 } as const;
+
+/** An avatar group's default overlap, in px, and its hover lift. */
+export const GROUP_OVERLAP = 8;
+export const GROUP_MAX = 4;
+export const GROUP_HOVER = { scale: 1.1, lift: 4 } as const;
+
+/** The dot's colour per status. `offline` is the ramp, the rest are semantic. */
+export function statusColor(theme: UiTheme, status: AvatarStatus): string {
+  if (status === 'online') return theme.palette.success.main;
+  if (status === 'away') return theme.palette.warning.main;
+  if (status === 'busy') return theme.palette.danger.main;
+  return theme.palette.grey[500];
+}
+
+export interface AvatarAccent {
+  main: string;
+  contrastText: string;
+}
+
+/**
+ * The accent behind the initials. `danger`, NOT `error` — the web map was keyed
+ * on MUI's word while the prop took the house one, so `danger` matched nothing
+ * and fell through to primary: a red avatar rendering blue, silently.
+ */
+export function avatarAccent(theme: UiTheme, color: ColorValue): AvatarAccent {
+  if (color === 'neutral') return { main: theme.palette.grey[700], contrastText: '#fff' };
+  const accent = theme.palette[color];
+  return { main: accent.main, contrastText: accent.contrastText || '#fff' };
+}

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' },
+});