@12-apps/ui 6.21.0 → 6.22.0

package/src/components/layout/Card/Card.styles.ts

@@ -1,18 +1,34 @@
 import { alpha, keyframes } from '@mui/material/styles/index.js';
 import type { CSSObject, Theme } from '@mui/material/styles/index.js';
 
-import type { CardProps, CardVariant } from './Card.types';
-
-type BorderRadius = NonNullable<CardProps['borderRadius']>;
-
-// Define pulse animation
+import type { CardBorderRadius, CardVariant } from './Card.base';
+import {
+  CARD_BORDER_WIDTH,
+  CARD_ELEVATION,
+  CARD_GLASS,
+  CARD_GLOW,
+  CARD_GRADIENT,
+  CARD_INTERACTIVE_LIFT,
+  CARD_NEUMORPHIC,
+  CARD_PULSE,
+  CARD_RADIUS_FULL,
+  CARD_RADIUS_UNITS,
+  CARD_SECTION_BACKGROUND,
+  neumorphicShadows,
+} from './Card.metrics';
+import { shadowCss, shadowListCss } from '../../../tokens/shadow';
+
+type BorderRadius = CardBorderRadius;
+
+// Define pulse animation. The 15px spread and the 2s period are the shared
+// metrics, so the native ring grows by exactly as much for exactly as long.
 const pulseAnimation = keyframes`
   0% {
     box-shadow: 0 0 0 0 currentColor;
     opacity: 1;
   }
   70% {
-    box-shadow: 0 0 0 15px currentColor;
+    box-shadow: 0 0 0 ${CARD_PULSE.spread}px currentColor;
     opacity: 0;
   }
   100% {
@@ -22,20 +38,10 @@ const pulseAnimation = keyframes`
 `;
 
 const borderRadiusFor = (theme: Theme, radius: BorderRadius): number | string => {
-  switch (radius) {
-    case 'none':
-      return 0;
-    case 'sm':
-      return theme.spacing(0.5);
-    case 'lg':
-      return theme.spacing(2);
-    case 'xl':
-      return theme.spacing(3);
-    case 'full':
-      return '50%';
-    default:
-      return theme.spacing(1);
-  }
+  if (radius === 'full') return CARD_RADIUS_FULL;
+  const units = CARD_RADIUS_UNITS[radius] ?? CARD_RADIUS_UNITS.md;
+  // `none` is a bare 0 rather than `spacing(0)`, as this has always written it.
+  return units === 0 ? 0 : theme.spacing(units);
 };
 
 const pulseSurface = (theme: Theme): CSSObject => ({
@@ -50,27 +56,43 @@ const pulseSurface = (theme: Theme): CSSObject => ({
     bottom: '0',
     borderRadius: 'inherit',
     backgroundColor: theme.palette.primary.main,
-    opacity: 0.3,
-    animation: `${pulseAnimation} 2s infinite`,
+    opacity: CARD_PULSE.alpha,
+    animation: `${pulseAnimation} ${CARD_PULSE.durationMs / 1000}s infinite`,
     pointerEvents: 'none',
-    zIndex: -1,
+    zIndex: CARD_PULSE.zIndex,
   },
 });
 
 const neumorphicShadow = (theme: Theme, lifted: boolean): string => {
-  const spread = lifted ? 12 : 8;
-  const blur = spread * 2;
-
-  return theme.palette.mode === 'dark'
-    ? `${spread}px ${spread}px ${blur}px ${alpha(theme.palette.common.black, 0.3)}, -${spread}px -${spread}px ${blur}px ${alpha(theme.palette.common.white, 0.1)}`
-    : `${spread}px ${spread}px ${blur}px ${alpha(theme.palette.grey[400], lifted ? 0.3 : 0.2)}, -${spread}px -${spread}px ${blur}px ${alpha(theme.palette.common.white, lifted ? 0.9 : 0.8)}`;
+  const { dark, light } = CARD_NEUMORPHIC.alpha;
+  const [near, far] =
+    theme.palette.mode === 'dark'
+      ? [
+          alpha(theme.palette.common.black, dark.near),
+          alpha(theme.palette.common.white, dark.far),
+        ]
+      : [
+          alpha(theme.palette.grey[400], lifted ? light.near.lifted : light.near.rest),
+          alpha(theme.palette.common.white, lifted ? light.far.lifted : light.far.rest),
+        ];
+
+  return shadowListCss(neumorphicShadows(lifted, near, far));
 };
 
 const sectionBackground = (theme: Theme, lifted: boolean): string => {
-  if (theme.palette.mode === 'dark') {
-    return lifted ? 'rgba(0, 0, 0, 0.25)' : 'rgba(0, 0, 0, 0.2)';
-  }
-  return lifted ? 'rgba(0, 0, 0, 0.04)' : 'rgba(0, 0, 0, 0.02)';
+  const wash = CARD_SECTION_BACKGROUND[theme.palette.mode === 'dark' ? 'dark' : 'light'];
+  return lifted ? wash.lifted : wash.rest;
+};
+
+const glowShadow = (theme: Theme, lifted: boolean): string => {
+  const { blurRadius, alpha: opacity } = lifted ? CARD_GLOW.lifted : CARD_GLOW.rest;
+  return shadowCss({
+    offsetX: 0,
+    offsetY: 0,
+    blurRadius,
+    spreadDistance: 0,
+    color: alpha(theme.palette.primary.main, opacity),
+  });
 };
 
 interface Surface {
@@ -85,30 +107,48 @@ interface Surface {
  */
 const VARIANT_SURFACES: Record<CardVariant, (theme: Theme, lifted: boolean) => Surface> = {
   elevated: (_theme, lifted) => ({
-    surface: { elevation: 4 } as CSSObject,
-    hover: { elevation: lifted ? 8 : 4 } as CSSObject,
+    surface: { elevation: CARD_ELEVATION.rest } as CSSObject,
+    hover: { elevation: lifted ? CARD_ELEVATION.lifted : CARD_ELEVATION.rest } as CSSObject,
   }),
   outlined: (theme, lifted) => ({
-    surface: { border: `1px solid ${theme.palette.divider}`, boxShadow: 'none' },
+    surface: {
+      border: `${CARD_BORDER_WIDTH}px solid ${theme.palette.divider}`,
+      boxShadow: 'none',
+    },
     hover: { borderColor: lifted ? theme.palette.primary.main : theme.palette.divider },
   }),
   glass: (theme, lifted) => ({
     surface: {
-      backgroundColor: alpha(theme.palette.background.paper, 0.1),
-      backdropFilter: 'blur(20px)',
-      border: `1px solid ${alpha(theme.palette.primary.main, 0.2)}`,
-      boxShadow: `0 8px 32px ${alpha(theme.palette.common.black, 0.1)}`,
+      backgroundColor: alpha(theme.palette.background.paper, CARD_GLASS.backgroundAlpha.rest),
+      backdropFilter: `blur(${CARD_GLASS.blurPx}px)`,
+      border: `${CARD_BORDER_WIDTH}px solid ${alpha(theme.palette.primary.main, CARD_GLASS.borderAlpha.rest)}`,
+      boxShadow: shadowCss({
+        offsetX: 0,
+        offsetY: CARD_GLASS.shadow.offsetY,
+        blurRadius: CARD_GLASS.shadow.blurRadius,
+        spreadDistance: 0,
+        color: alpha(theme.palette.common.black, CARD_GLASS.shadow.alpha),
+      }),
     },
     hover: {
-      backgroundColor: alpha(theme.palette.background.paper, lifted ? 0.15 : 0.1),
-      border: `1px solid ${alpha(theme.palette.primary.main, 0.3)}`,
+      backgroundColor: alpha(
+        theme.palette.background.paper,
+        lifted ? CARD_GLASS.backgroundAlpha.lifted : CARD_GLASS.backgroundAlpha.rest,
+      ),
+      border: `${CARD_BORDER_WIDTH}px solid ${alpha(theme.palette.primary.main, CARD_GLASS.borderAlpha.lifted)}`,
     },
   }),
   gradient: (theme, lifted) => ({
     surface: {
       background: cardGradient(theme, false),
       color: theme.palette.primary.contrastText,
-      boxShadow: `0 4px 20px ${alpha(theme.palette.primary.main, 0.3)}`,
+      boxShadow: shadowCss({
+        offsetX: 0,
+        offsetY: CARD_GRADIENT.shadow.offsetY,
+        blurRadius: CARD_GRADIENT.shadow.blurRadius,
+        spreadDistance: 0,
+        color: alpha(theme.palette.primary.main, CARD_GRADIENT.shadow.alpha),
+      }),
     },
     hover: { background: cardGradient(theme, lifted) },
   }),
@@ -133,8 +173,8 @@ const VARIANT_SURFACES: Record<CardVariant, (theme: Theme, lifted: boolean) => S
 
 const cardGradient = (theme: Theme, dark: boolean): string =>
   dark
-    ? `linear-gradient(135deg, ${theme.palette.primary.dark}, ${theme.palette.secondary.dark})`
-    : `linear-gradient(135deg, ${theme.palette.primary.main}, ${theme.palette.secondary.main})`;
+    ? `linear-gradient(${CARD_GRADIENT.angleDeg}deg, ${theme.palette.primary.dark}, ${theme.palette.secondary.dark})`
+    : `linear-gradient(${CARD_GRADIENT.angleDeg}deg, ${theme.palette.primary.main}, ${theme.palette.secondary.main})`;
 
 // An unrecognised variant gets the shared base only — no interactive, glow or
 // pulse decoration, as before.
@@ -170,12 +210,12 @@ export const cardStyles = (
   return {
     ...base,
     ...(interactive && { cursor: 'pointer', '&:active': { transform: 'translateY(0)' } }),
-    ...(glow && { boxShadow: `0 0 20px ${alpha(theme.palette.primary.main, 0.3)}` }),
+    ...(glow && { boxShadow: glowShadow(theme, false) }),
     ...(pulse && pulseSurface(theme)),
     ...chosen.surface,
     '&:hover': {
-      ...(interactive && { transform: 'translateY(-2px)' }),
-      ...(glow && { boxShadow: `0 0 30px ${alpha(theme.palette.primary.main, 0.4)}` }),
+      ...(interactive && { transform: `translateY(-${CARD_INTERACTIVE_LIFT}px)` }),
+      ...(glow && { boxShadow: glowShadow(theme, true) }),
       ...chosen.hover,
     },
   };

package/src/components/layout/Card/Card.tsx

@@ -9,7 +9,14 @@ import { useTheme } from '@mui/material/styles/index.js';
 import React from 'react';
 
 import { resolveCardProps } from './Card.helpers';
+import {
+  CARD_CONTENT_PADDING_UNITS,
+  CARD_HEADER_CHILDREN_PADDING_UNITS,
+  CARD_LOADING,
+  CARD_MEDIA_HEIGHT,
+} from './Card.metrics';
 import { cardStyles } from './Card.styles';
+import { childTestId, resolveTestId, withoutTestIdProps } from '../../../platform/test-id';
 import type {
   CardActionsProps,
   CardContentProps,
@@ -31,7 +38,6 @@ export const Card: React.FC<CardProps> = (rawProps) => {
     onFocus,
     onBlur,
     sx,
-    dataTestId,
     // These props are reserved for future implementation but need to be extracted
     // to prevent them from being passed to the underlying MuiCard
     expandable: _expandable,
@@ -45,6 +51,12 @@ export const Card: React.FC<CardProps> = (rawProps) => {
   } = resolveCardProps(rawProps);
 
   const theme = useTheme();
+  // Every spelling of the test id the shared contract allows, mapped to the one
+  // the DOM reads, and stripped from what is spread — `testID` is React
+  // Native's name for it and is not a DOM attribute. The native `Card` does the
+  // same in reverse.
+  const ownTestId = resolveTestId(restProps, 'card');
+  const props = withoutTestIdProps(restProps);
 
   // A loading card is inert: no handlers fire and pointer events are off, so a
   // half-rendered card cannot be clicked through.
@@ -52,18 +64,18 @@ export const Card: React.FC<CardProps> = (rawProps) => {
 
   return (
     <MuiCard
-      data-testid={dataTestId || 'card'}
+      data-testid={ownTestId}
       onClick={idle ? onClick : undefined}
       onFocus={idle ? onFocus : undefined}
       onBlur={idle ? onBlur : undefined}
       sx={{
         ...cardStyles(theme, { variant, interactive, glow, pulse, borderRadius }),
         position: 'relative',
-        opacity: loading ? 0.6 : 1,
+        opacity: loading ? CARD_LOADING.opacity : 1,
         pointerEvents: loading ? 'none' : 'auto',
         ...sx,
       }}
-      {...restProps}
+      {...props}
     >
       {loading && (
         <Box
@@ -72,7 +84,7 @@ export const Card: React.FC<CardProps> = (rawProps) => {
             top: '50%',
             left: '50%',
             transform: 'translate(-50%, -50%)',
-            zIndex: 10,
+            zIndex: CARD_LOADING.spinnerZIndex,
           }}
         >
           <CircularProgress />
@@ -89,41 +101,47 @@ export const CardHeader: React.FC<CardHeaderProps> = ({
   action,
   avatar,
   children,
-  dataTestId,
-  ...props
+  ...others
 }) => {
+  const ownTestId = resolveTestId(others, 'card-header');
+  const props = withoutTestIdProps(others);
+
   if (children) {
-    return <Box sx={{ p: 2 }} data-testid={dataTestId || 'card-header'}>{children}</Box>;
+    return (
+      <Box sx={{ p: CARD_HEADER_CHILDREN_PADDING_UNITS }} data-testid={ownTestId}>
+        {children}
+      </Box>
+    );
   }
 
   return (
     <MuiCardHeader
-      data-testid={dataTestId || 'card-header'}
+      data-testid={ownTestId}
       avatar={avatar}
       action={action}
       title={title}
       subheader={subtitle}
       titleTypographyProps={{
-        'data-testid': dataTestId ? `${dataTestId}-title` : 'card-title',
+        'data-testid': childTestId(others, 'title', 'card'),
       } as Record<string, unknown>}
       subheaderTypographyProps={{
-        'data-testid': dataTestId ? `${dataTestId}-subtitle` : 'card-subtitle',
+        'data-testid': childTestId(others, 'subtitle', 'card'),
       } as Record<string, unknown>}
       {...props}
     />
   );
 };
 
-export const CardContent: React.FC<CardContentProps> = ({ children, dense = false, dataTestId, ...props }) => (
+export const CardContent: React.FC<CardContentProps> = ({ children, dense = false, ...others }) => (
     <MuiCardContent
-      data-testid={dataTestId || 'card-content'}
+      data-testid={resolveTestId(others, 'card-content')}
       sx={{
-        padding: dense ? 1 : 2,
+        padding: dense ? CARD_CONTENT_PADDING_UNITS.dense : CARD_CONTENT_PADDING_UNITS.normal,
         '&:last-child': {
-          paddingBottom: dense ? 1 : 2,
+          paddingBottom: dense ? CARD_CONTENT_PADDING_UNITS.dense : CARD_CONTENT_PADDING_UNITS.normal,
         },
       }}
-      {...props}
+      {...withoutTestIdProps(others)}
     >
       {children}
     </MuiCardContent>
@@ -133,8 +151,7 @@ export const CardActions: React.FC<CardActionsProps> = ({
   children,
   disableSpacing = false,
   alignment = 'left',
-  dataTestId,
-  ...props
+  ...others
 }) => {
   const getJustifyContent = () => {
     switch (alignment) {
@@ -151,12 +168,12 @@ export const CardActions: React.FC<CardActionsProps> = ({
 
   return (
     <MuiCardActions
-      data-testid={dataTestId || 'card-actions'}
+      data-testid={resolveTestId(others, 'card-actions')}
       disableSpacing={disableSpacing}
       sx={{
         justifyContent: getJustifyContent(),
       }}
-      {...props}
+      {...withoutTestIdProps(others)}
     >
       {children}
     </MuiCardActions>
@@ -167,18 +184,17 @@ export const CardMedia: React.FC<CardMediaProps> = ({
   component = 'div',
   image,
   title,
-  height = 200,
+  height = CARD_MEDIA_HEIGHT,
   children,
-  dataTestId,
-  ...props
+  ...others
 }) => (
     <MuiCardMedia
-      data-testid={dataTestId || 'card-media'}
+      data-testid={resolveTestId(others, 'card-media')}
       component={component}
       height={height}
       image={image}
       title={title}
-      {...props}
+      {...withoutTestIdProps(others)}
     >
       {children}
     </MuiCardMedia>

package/src/components/layout/Card/Card.types.native.ts

@@ -0,0 +1,59 @@
+import type {
+  GestureResponderEvent,
+  NativeSyntheticEvent,
+  StyleProp,
+  TargetedEvent,
+  ViewProps,
+  ViewStyle,
+} from 'react-native';
+
+import type {
+  CardActionsBaseProps,
+  CardBaseProps,
+  CardContentBaseProps,
+  CardHeaderBaseProps,
+  CardMediaBaseProps,
+} from './Card.base';
+
+export type {
+  CardActionsAlignment,
+  CardActionsBaseProps,
+  CardBaseProps,
+  CardBorderRadius,
+  CardContentBaseProps,
+  CardEntranceAnimation,
+  CardHeaderBaseProps,
+  CardMediaBaseProps,
+  CardVariant,
+} from './Card.base';
+
+/** Everything a native slot takes on top of its shared contract. */
+type NativeSlotProps<Base> = Base & Omit<ViewProps, keyof Base | 'style'> & {
+  style?: StyleProp<ViewStyle>;
+};
+
+/**
+ * The native `Card`. `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 reaches for. Both fire.
+ *
+ * A card with neither handler and no `interactive` renders as a plain `View`,
+ * the way the web one is a plain `div`: nothing to press, nothing in the
+ * accessibility tree that says otherwise.
+ */
+export type CardProps = CardBaseProps &
+  Omit<ViewProps, keyof CardBaseProps | 'style' | 'onFocus' | 'onBlur'> & {
+    style?: StyleProp<ViewStyle>;
+    onClick?: (event: GestureResponderEvent) => void;
+    onPress?: (event: GestureResponderEvent) => void;
+    onFocus?: (event: NativeSyntheticEvent<TargetedEvent>) => void;
+    onBlur?: (event: NativeSyntheticEvent<TargetedEvent>) => void;
+  };
+
+export type CardHeaderProps = NativeSlotProps<CardHeaderBaseProps>;
+
+export type CardContentProps = NativeSlotProps<CardContentBaseProps>;
+
+export type CardActionsProps = NativeSlotProps<CardActionsBaseProps>;
+
+export type CardMediaProps = NativeSlotProps<CardMediaBaseProps>;

package/src/components/layout/Card/Card.types.ts

@@ -1,57 +1,42 @@
 import type { CardProps as MuiCardProps } from '@mui/material/Card/index.js';
-import type { ReactNode } from 'react';
+import type React from 'react';
 
-export type CardVariant = 'elevated' | 'outlined' | 'glass' | 'gradient' | 'neumorphic' | 'section';
-export type CardEntranceAnimation = 'fade' | 'slide-up' | 'slide-down' | 'slide-left' | 'slide-right' | 'zoom' | 'grow' | 'none';
+import type {
+  CardActionsBaseProps,
+  CardBaseProps,
+  CardContentBaseProps,
+  CardHeaderBaseProps,
+  CardMediaBaseProps,
+} from './Card.base';
 
-export interface CardProps extends Omit<MuiCardProps, 'variant'> {
-  children: ReactNode;
-  variant?: CardVariant;
-  interactive?: boolean;
-  glow?: boolean;
-  pulse?: boolean;
-  borderRadius?: 'none' | 'sm' | 'md' | 'lg' | 'xl' | 'full';
-  loading?: boolean;
-  expandable?: boolean;
-  expanded?: boolean;
-  onExpandToggle?: (expanded: boolean) => void;
-  entranceAnimation?: CardEntranceAnimation;
-  animationDelay?: number;
-  skeleton?: boolean;
-  hoverScale?: number;
+export type {
+  CardActionsAlignment,
+  CardActionsBaseProps,
+  CardBaseProps,
+  CardBorderRadius,
+  CardContentBaseProps,
+  CardEntranceAnimation,
+  CardHeaderBaseProps,
+  CardMediaBaseProps,
+  CardVariant,
+} from './Card.base';
+
+/** The web `Card`: the shared contract, plus everything MUI's own `Card` takes. */
+export interface CardProps
+  extends CardBaseProps,
+    Omit<MuiCardProps, 'variant' | keyof CardBaseProps> {
   onClick?: React.MouseEventHandler<HTMLDivElement>;
   onFocus?: React.FocusEventHandler<HTMLDivElement>;
   onBlur?: React.FocusEventHandler<HTMLDivElement>;
-  dataTestId?: string;
 }
 
-export interface CardHeaderProps {
-  title?: ReactNode;
-  subtitle?: ReactNode;
-  action?: ReactNode;
-  avatar?: ReactNode;
-  children?: ReactNode;
-  dataTestId?: string;
-}
+export type CardHeaderProps = CardHeaderBaseProps;
 
-export interface CardContentProps {
-  children: ReactNode;
-  dense?: boolean;
-  dataTestId?: string;
-}
+export type CardContentProps = CardContentBaseProps;
 
-export interface CardActionsProps {
-  children: ReactNode;
-  disableSpacing?: boolean;
-  alignment?: 'left' | 'center' | 'right' | 'space-between';
-  dataTestId?: string;
-}
+export type CardActionsProps = CardActionsBaseProps;
 
-export interface CardMediaProps {
+/** `component` is the DOM element MUI renders the media as — web only. */
+export interface CardMediaProps extends CardMediaBaseProps {
   component?: React.ElementType;
-  image?: string;
-  title?: string;
-  height?: number | string;
-  children?: ReactNode;
-  dataTestId?: string;
-}
+}