@12-apps/ui 6.17.1 → 6.19.0

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

@@ -0,0 +1,166 @@
+import type { AlertVariant } from './Alert.base';
+import { alpha, darken, lighten } from '../../../tokens/color';
+import { contrastText, type UiGreyStep, type UiTheme } from '../../../tokens/theme';
+
+/**
+ * THE NUMBERS BOTH `Alert` RENDERERS DRAW WITH.
+ *
+ * `Alert.styles.tsx` / `Alert.tsx` (MUI) and `Alert.native.tsx` (React
+ * Native) read this one table. Spacing is in SPACING UNITS where the web
+ * writes `theme.spacing(n)`; durations are ms (the web turns them into `s`
+ * through {@link seconds} so its emitted CSS is byte-for-byte what it was);
+ * everything else is px, a ratio or an alpha. The hover, active and focus
+ * numbers are here too although only the DOM can honour them — a number the
+ * web draws with belongs in the table whether or not native can reach it.
+ */
+
+/** The root: 12px corners, 14px 16px of padding, one 300ms curve for everything. */
+export const ALERT_RADIUS_UNITS = 1.5;
+export const ALERT_PADDING_UNITS = { vertical: 1.75, horizontal: 2 } as const;
+export const ALERT_TRANSITION_MS = 300;
+export const ALERT_EASING = 'cubic-bezier(0.4, 0, 0.2, 1)';
+
+/** Mount: the web's `fadeInScale` keyframes and the icon's `iconRotate`. */
+export const FADE_IN = { ms: 300, scale: 0.95, lift: 10 } as const;
+export const ICON_SPIN = { ms: 600, from: 0.8, mid: 1.1 } as const;
+/** Dismiss: MUI `Collapse` runs 300ms; `onClose` fires 200ms in. */
+export const COLLAPSE_MS = 300;
+export const CLOSE_DELAY_MS = 200;
+
+/** The message column: 8px between title, description and children; 0.95rem body on 1.5. */
+export const MESSAGE_GAP_UNITS = 1;
+export const MESSAGE_FONT_SIZE = 15.2;
+export const MESSAGE_LINE_HEIGHT = 1.5;
+/** A control inside the message gets an edge: 4px above, a hairline at 0.45 of the hue. */
+export const MESSAGE_BUTTON = { marginTopUnits: 0.5, borderAlpha: 0.45 } as const;
+
+/** The title: 1.05rem at 600; MUI's `AlertTitle` lifts it 2px; 4px below it when a description follows. */
+export const TITLE = { fontSize: 16.8, fontWeight: 600, marginTop: -2, marginBottomUnits: 0.5 } as const;
+/** The description: 0.925rem, slightly faded. */
+export const DESCRIPTION = { fontSize: 14.8, opacity: 0.9 } as const;
+
+/** The icon slot: MUI's 22px glyph at 0.9, 14px from the words, 2px down (MUI's 7px stays below). */
+export const ICON_SLOT = { size: 22, opacity: 0.9, marginRightUnits: 1.75, paddingTopUnits: 0.25, paddingBottom: 7 } as const;
+/** The action slot: MUI's `4px 0 0 16px` with the 16px ours, pushed right, 8px into the padding. */
+export const ACTION_SLOT = { paddingLeftUnits: 2, paddingTop: 4, marginRight: -8 } as const;
+/** The close button: MUI's small `IconButton` (5px padding, 18px glyph) at 0.7. */
+export const CLOSE_BUTTON = { padding: 5, iconSize: 18, opacity: 0.7, hoverRotateDeg: 90, hoverScale: 1.1, washAlpha: 0.1 } as const;
+
+/**
+ * A semantic Alert's surface and ink: an OPAQUE tint of the hue with a dark
+ * ink of the same hue — MUI's own `standard` recipe, at its ratios. See
+ * `semanticSurface` in `Alert.styles.tsx` for why not `alpha(main, 0.1)`.
+ */
+export const SEMANTIC_SURFACE = { tint: { light: 0.9, dark: 0.8 }, ink: 0.6, borderAlpha: 0.35 } as const;
+/** `glass`: 85% paper under a 20px blur, a 0.4 divider hairline. */
+export const GLASS = { backgroundAlpha: 0.85, borderAlpha: 0.4, blur: 20, saturatePercent: 180 } as const;
+/** `gradient`: light→dark at 0.9 along 135°, a 0.2 white shimmer sweeping 1000px every 3s. */
+export const GRADIENT = {
+  angleDeg: 135,
+  stopAlpha: 0.9,
+  shimmerAlpha: 0.2,
+  shimmerMs: 3000,
+  shimmerTravel: 1000,
+  hoverBrightness: 1.1,
+  hoverLift: 2,
+  hoverScale: 1.01,
+} as const;
+
+/** Emphasis: the glow's shadow and brightness, the pulse's wash. */
+export const GLOW = { blur: 20, spread: 5, alpha: 0.3, brightness: 1.05 } as const;
+export const PULSE = { alpha: 0.2, ms: 2000, spread: 10 } as const;
+
+/** Pointer states — DOM only, kept so the web derives them. */
+export const HOVER = { lift: 3, scale: 1.01, shadowY: 8, shadowBlur: 20, shadowAlpha: 0.2, iconScale: 1.15, iconRotateDeg: 10 } as const;
+export const ACTIVE = { lift: 1, scale: 0.99, ms: 100 } as const;
+export const FOCUS = { ringWidth: 3, ringAlpha: 0.5, offset: 3, haloSpread: 6, haloAlpha: 0.1, ms: 200 } as const;
+
+/** `neutral` has no palette slot; the web has always drawn it from three greys. */
+export const NEUTRAL_GREY: Record<'main' | 'light' | 'dark', UiGreyStep> = { main: 500, light: 300, dark: 700 };
+
+/** A duration as the CSS the web has always emitted: `2000` → `2s`, `300` → `0.3s`. */
+export const seconds = (ms: number): string => `${ms / 1000}s`;
+
+/** The palette shape the web's `getColorFromTheme` returns — a main plus optional shades. */
+export interface AlertPalette {
+  main: string;
+  light?: string;
+  dark?: string;
+}
+
+/**
+ * The renderer-free twin of the web's `getColorFromTheme`: a variant or
+ * colour name to its palette, `neutral` from the greys, anything unknown
+ * (`glass`, `gradient`) to `info`.
+ */
+export function alertPalette(theme: UiTheme, key: string | undefined): AlertPalette {
+  switch (key) {
+    case 'info':
+    case 'success':
+    case 'warning':
+    case 'danger':
+    case 'primary':
+    case 'secondary':
+      return theme.palette[key];
+    case 'neutral':
+      return {
+        main: theme.palette.grey[NEUTRAL_GREY.main],
+        light: theme.palette.grey[NEUTRAL_GREY.light],
+        dark: theme.palette.grey[NEUTRAL_GREY.dark],
+      };
+    default:
+      return theme.palette.info;
+  }
+}
+
+/** What a variant paints: its fill, its ink, its hairline if any, and the colour of its glyph. */
+export interface AlertSurface {
+  backgroundColor: string;
+  color: string;
+  borderColor?: string;
+  iconColor: string;
+}
+
+export const SEMANTIC_VARIANTS: ReadonlySet<AlertVariant> = new Set(['info', 'success', 'warning', 'danger']);
+
+/** The opaque tint and same-hue ink, inverted for dark mode; the hairline keeps its alpha. */
+export function semanticSurface(theme: UiTheme, palette: AlertPalette): AlertSurface {
+  const dark = theme.mode === 'dark';
+  return {
+    backgroundColor: dark
+      ? darken(palette.main, SEMANTIC_SURFACE.tint.dark)
+      : lighten(palette.main, SEMANTIC_SURFACE.tint.light),
+    color: dark ? lighten(palette.main, SEMANTIC_SURFACE.ink) : darken(palette.main, SEMANTIC_SURFACE.ink),
+    borderColor: alpha(palette.main, SEMANTIC_SURFACE.borderAlpha),
+    iconColor: palette.main,
+  };
+}
+
+export function glassSurface(theme: UiTheme): AlertSurface {
+  return {
+    backgroundColor: alpha(theme.palette.background.paper, GLASS.backgroundAlpha),
+    color: theme.palette.text.primary,
+    borderColor: alpha(theme.palette.divider, GLASS.borderAlpha),
+    iconColor: theme.palette.primary.main,
+  };
+}
+
+/** The gradient's two stops; a renderer with no gradient fill paints `from`. */
+export function gradientStops(palette: AlertPalette): { from: string; to: string } {
+  return {
+    from: alpha(palette.light || palette.main, GRADIENT.stopAlpha),
+    to: alpha(palette.dark || palette.main, GRADIENT.stopAlpha),
+  };
+}
+
+export function gradientSurface(palette: AlertPalette): AlertSurface {
+  const ink = contrastText(palette.main);
+  return { backgroundColor: gradientStops(palette).from, color: ink, iconColor: ink };
+}
+
+/** The surface for a variant, `glass` and `gradient` included. */
+export function alertSurface(theme: UiTheme, variant: AlertVariant, palette: AlertPalette): AlertSurface {
+  if (variant === 'glass') return glassSurface(theme);
+  if (variant === 'gradient') return gradientSurface(palette);
+  return semanticSurface(theme, palette);
+}

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

@@ -0,0 +1,239 @@
+import * as React from 'react';
+import {
+  Animated,
+  Easing,
+  type LayoutChangeEvent,
+  Platform,
+  Pressable,
+  type Role,
+  StyleSheet,
+  Text as RNText,
+  View,
+  type ViewStyle,
+} from 'react-native';
+
+import { defaultAriaLive, resolveAlertProps, testIdFor, VARIANT_ICON } from './Alert.helpers';
+import {
+  actionSlotStyle,
+  alertLook,
+  closeButtonStyle,
+  descriptionStyle,
+  iconSlotStyle,
+  messageSlotStyle,
+  messageTextStyle,
+  titleStyle,
+} from './Alert.look.native';
+import { CLOSE_BUTTON, CLOSE_DELAY_MS, COLLAPSE_MS, FADE_IN, ICON_SLOT, ICON_SPIN, PULSE } from './Alert.metrics';
+import type { AlertProps, AlertVariant } from './Alert.types.native';
+import { Icon } from '../../../icons/Icon.native';
+import { webAria } from '../../../platform/aria';
+import { renderTextChildren } from '../../../platform/text-children';
+import { resolveTestId, withoutTestIdProps } from '../../../platform/test-id';
+import { useUiTheme } from '../../../provider/use-ui-theme.native';
+
+type AnimatedStyle = Animated.WithAnimatedValue<ViewStyle>;
+const nativeDriver = Platform.OS !== 'web';
+
+/** A 0→1 progress that starts on mount when `animate` is set, else sits at 1. */
+function useProgress(animate: boolean, duration: number): Animated.Value {
+  const progress = React.useRef(new Animated.Value(animate ? 0 : 1)).current;
+  React.useEffect(() => {
+    if (!animate) return undefined;
+    const timing = Animated.timing(progress, { toValue: 1, duration, easing: Easing.out(Easing.ease), useNativeDriver: nativeDriver });
+    timing.start();
+    return () => timing.stop();
+  }, [animate, duration, progress]);
+  return progress;
+}
+
+/** The web's `fadeInScale` keyframes: in from 0 opacity, 0.95 scale and 10px above, over 300ms. */
+function useFadeIn(animate: boolean): AnimatedStyle | undefined {
+  const progress = useProgress(animate, FADE_IN.ms);
+  if (!animate) return undefined;
+  return {
+    opacity: progress,
+    transform: [
+      { scale: progress.interpolate({ inputRange: [0, 1], outputRange: [FADE_IN.scale, 1] }) },
+      { translateY: progress.interpolate({ inputRange: [0, 1], outputRange: [-FADE_IN.lift, 0] }) },
+    ],
+  };
+}
+
+/** The web's `iconRotate` keyframes: one full turn, 0.8 → 1.1 → 1, over 600ms. */
+function useIconSpin(animate: boolean): AnimatedStyle | undefined {
+  const progress = useProgress(animate, ICON_SPIN.ms);
+  if (!animate) return undefined;
+  return {
+    transform: [
+      { rotate: progress.interpolate({ inputRange: [0, 1], outputRange: ['0deg', '360deg'] }) },
+      { scale: progress.interpolate({ inputRange: [0, 0.5, 1], outputRange: [ICON_SPIN.from, ICON_SPIN.mid, 1] }) },
+    ],
+  };
+}
+
+/** The web's `::after` pulse: a wash of the hue over the card, fading out every two seconds, behind the words. */
+function Pulse({ color, radius, testID }: { color: string; radius: number; testID: string }): React.JSX.Element {
+  const progress = React.useRef(new Animated.Value(0)).current;
+  React.useEffect(() => {
+    const loop = Animated.loop(
+      Animated.timing(progress, { toValue: 1, duration: PULSE.ms, easing: Easing.linear, useNativeDriver: nativeDriver }),
+    );
+    loop.start();
+    return () => loop.stop();
+  }, [progress]);
+  return (
+    <Animated.View
+      testID={testID}
+      aria-hidden
+      style={[
+        StyleSheet.absoluteFill,
+        {
+          pointerEvents: 'none',
+          borderRadius: radius,
+          backgroundColor: color,
+          opacity: progress.interpolate({ inputRange: [0, 0.7, 1], outputRange: [PULSE.alpha, 0, 0] }),
+        },
+      ]}
+    />
+  );
+}
+
+/**
+ * MUI's `Collapse`: open, it is a plain wrapper with its overflow visible (so
+ * a glow can escape); closing, it clips and shrinks over 300ms, then says so.
+ */
+function Collapse({ open, onCollapsed, children }: { open: boolean; onCollapsed: () => void; children: React.ReactNode }): React.JSX.Element {
+  const [height, setHeight] = React.useState<number | null>(null);
+  const progress = React.useRef(new Animated.Value(1)).current;
+  React.useEffect(() => {
+    if (open) return undefined;
+    const timing = Animated.timing(progress, { toValue: 0, duration: COLLAPSE_MS, easing: Easing.inOut(Easing.ease), useNativeDriver: false });
+    timing.start(({ finished }) => {
+      if (finished) onCollapsed();
+    });
+    return () => timing.stop();
+  }, [open, onCollapsed, progress]);
+  const onLayout = (event: LayoutChangeEvent): void => {
+    if (open) setHeight(event.nativeEvent.layout.height);
+  };
+  const shrink: AnimatedStyle = height == null ? {} : { maxHeight: progress.interpolate({ inputRange: [0, 1], outputRange: [0, height] }) };
+  return (
+    <Animated.View style={[{ overflow: open ? 'visible' : 'hidden', opacity: progress }, shrink]}>
+      <View onLayout={onLayout}>{children}</View>
+    </Animated.View>
+  );
+}
+
+interface IconSlotProps {
+  variant: AlertVariant;
+  icon: React.ReactNode;
+  color: string;
+  animate: boolean;
+  testID: string;
+}
+
+/** The icon slot; `glass` and `gradient` have no glyph of their own, so theirs is empty unless an `icon` is given — as on the web. */
+function IconSlot({ variant, icon, color, animate, testID }: IconSlotProps): React.JSX.Element {
+  const theme = useUiTheme();
+  const spin = useIconSpin(animate);
+  const glyph = VARIANT_ICON[variant];
+  return (
+    <Animated.View testID={testID} style={[iconSlotStyle(theme), spin]}>
+      {icon || (glyph ? <Icon name={glyph} size={ICON_SLOT.size} color={color} /> : null)}
+    </Animated.View>
+  );
+}
+
+function CloseButton({ label, ink, onPress, testID }: { label: string | undefined; ink: string; onPress: () => void; testID: string }): React.JSX.Element {
+  const theme = useUiTheme();
+  return (
+    <Pressable role="button" aria-label={label} testID={testID} onPress={onPress} style={({ pressed }) => closeButtonStyle(theme, pressed)}>
+      <Icon name="Close" size={CLOSE_BUTTON.iconSize} color={ink} />
+    </Pressable>
+  );
+}
+
+interface ContentProps {
+  title?: string;
+  description?: string;
+  children?: React.ReactNode;
+  ink: string;
+  testId: string;
+}
+
+function AlertContent({ title, description, children, ink, testId }: ContentProps): React.JSX.Element {
+  const theme = useUiTheme();
+  return (
+    <View style={messageSlotStyle(theme)}>
+      {title ? (
+        <RNText testID={testIdFor(testId, 'title')} style={titleStyle(theme, ink, Boolean(description))}>
+          {title}
+        </RNText>
+      ) : null}
+      {description ? (
+        <RNText testID={testIdFor(testId, 'message')} style={descriptionStyle(theme, ink)}>
+          {description}
+        </RNText>
+      ) : null}
+      {renderTextChildren(children, messageTextStyle(theme, ink))}
+    </View>
+  );
+}
+
+/** The dismiss sequence the web runs: mark closing, fire `onClose` 200ms in, stay until the collapse has run. */
+function useDismiss(onClose: (() => void) | undefined): { open: boolean; gone: boolean; close: () => void; onCollapsed: () => void } {
+  const [closing, setClosing] = React.useState(false);
+  const [gone, setGone] = React.useState(false);
+  const timer = React.useRef<ReturnType<typeof setTimeout> | null>(null);
+  React.useEffect(() => () => {
+    if (timer.current) clearTimeout(timer.current);
+  }, []);
+  const close = (): void => {
+    setClosing(true);
+    timer.current = setTimeout(() => onClose?.(), CLOSE_DELAY_MS);
+  };
+  const onCollapsed = React.useCallback(() => setGone(true), []);
+  return { open: !closing, gone, close, onCollapsed };
+}
+
+export const Alert = React.forwardRef<View, AlertProps>((alertProps, ref) => {
+  const {
+    variant, color, glow, pulse, icon, showIcon, onClose, title, description, children, animate, role,
+    'aria-atomic': ariaAtomic, 'aria-live': _ariaLive, closable, closeLabel, style, ...others
+  } = resolveAlertProps(alertProps);
+  const theme = useUiTheme();
+  const testId = resolveTestId(others, 'alert') as string;
+  const rest = withoutTestIdProps(others);
+  const look = alertLook(theme, { variant, color, glow, pulse });
+  const fadeIn = useFadeIn(animate);
+  const dismiss = useDismiss(onClose);
+
+  if (dismiss.gone) return null;
+  return (
+    <Collapse open={dismiss.open} onCollapsed={dismiss.onCollapsed}>
+      <Animated.View
+        ref={ref}
+        role={role as Role}
+        aria-live={alertProps['aria-live'] ?? defaultAriaLive(variant)}
+        {...webAria({ 'aria-atomic': ariaAtomic })}
+        tabIndex={0}
+        testID={testId}
+        style={[look.root, fadeIn, style]}
+        {...rest}
+      >
+        {pulse ? <Pulse color={look.palette.main} radius={look.root.borderRadius as number} testID={testIdFor(testId, 'pulse')} /> : null}
+        {showIcon ? <IconSlot variant={variant} icon={icon} color={look.iconColor} animate={animate} testID={testIdFor(testId, 'icon')} /> : null}
+        <AlertContent title={title} description={description} ink={look.ink} testId={testId}>
+          {children}
+        </AlertContent>
+        {closable ? (
+          <View style={actionSlotStyle(theme)}>
+            <CloseButton label={closeLabel} ink={look.ink} onPress={dismiss.close} testID={testIdFor(testId, 'close')} />
+          </View>
+        ) : null}
+      </Animated.View>
+    </Collapse>
+  );
+});
+
+Alert.displayName = 'Alert';