@12-apps/ui 1.4.0 → 1.5.0

package/src/components/form/Label/Label.styles.ts

@@ -0,0 +1,206 @@
+import { alpha } from '@mui/material';
+import type { CSSObject, Theme } from '@mui/material';
+
+import type { LabelProps } from './Label.types';
+
+type Size = NonNullable<LabelProps['size']>;
+type Variant = NonNullable<LabelProps['variant']>;
+type Weight = NonNullable<LabelProps['weight']>;
+
+const SIZES: Record<Size, (theme: Theme) => CSSObject> = {
+  xs: (theme) => ({ fontSize: '0.75rem', lineHeight: 1.2, padding: theme.spacing(0.25, 0.5) }),
+  sm: (theme) => ({ fontSize: '0.875rem', lineHeight: 1.3, padding: theme.spacing(0.5, 0.75) }),
+  md: (theme) => ({ fontSize: '1rem', lineHeight: 1.5, padding: theme.spacing(0.75, 1) }),
+  lg: (theme) => ({ fontSize: '1.125rem', lineHeight: 1.6, padding: theme.spacing(1, 1.25) }),
+  xl: (theme) => ({ fontSize: '1.25rem', lineHeight: 1.7, padding: theme.spacing(1.25, 1.5) }),
+};
+
+export const sizeStyles = (theme: Theme, size: Size): CSSObject => (SIZES[size] ?? SIZES.md)(theme);
+
+const WEIGHTS: Record<Weight, number> = {
+  light: 300,
+  regular: 400,
+  medium: 500,
+  semibold: 600,
+  bold: 700,
+};
+
+const fontWeight = (weight: Weight) => WEIGHTS[weight] ?? WEIGHTS.regular;
+
+export interface LabelStyleFlags {
+  variant: Variant;
+  size: Size;
+  color: NonNullable<LabelProps['color']>;
+  weight: Weight;
+  transform: NonNullable<LabelProps['transform']>;
+  align: NonNullable<LabelProps['align']>;
+  error: boolean;
+  disabled: boolean;
+  glow: boolean;
+  pulse: boolean;
+  ripple: boolean;
+  srOnly: boolean;
+  nowrap: boolean;
+  truncate: boolean;
+  clickable: boolean;
+}
+
+/**
+ * The text colour, which error and disabled override before the palette is
+ * consulted at all. Resolved once and threaded through — the variant styles
+ * read it up to four times each.
+ */
+export const textColor = (theme: Theme, flags: LabelStyleFlags): string => {
+  if (flags.error) return theme.palette.error.main;
+  if (flags.disabled) return theme.palette.text.disabled;
+  if (flags.color === 'default') return theme.palette.text.primary;
+  return theme.palette[flags.color].main;
+};
+
+/** The ripple that expands from the centre on press, for clickable labels. */
+const rippleStyles = (theme: Theme): CSSObject => ({
+  overflow: 'hidden',
+  '&::after': {
+    content: '""',
+    position: 'absolute',
+    top: '50%',
+    left: '50%',
+    width: 0,
+    height: 0,
+    borderRadius: '50%',
+    backgroundColor: alpha(theme.palette.primary.main, 0.3),
+    transform: 'translate(-50%, -50%)',
+    transition: 'width 0.6s, height 0.6s',
+  },
+  '&:active::after': { width: '300%', height: '300%' },
+});
+
+interface SurfaceInput {
+  theme: Theme;
+  flags: LabelStyleFlags;
+  /** The resolved text colour, or the primary accent when it resolves to none. */
+  accent: string;
+}
+
+/**
+ * Each variant's own additions. Every arm previously re-spread the same base,
+ * glow, pulse and ripple objects and re-derived the colour for each use; the
+ * shared prefix is applied once by `labelStyles`.
+ *
+ * The hover rules are only attached when the label is clickable, which is what
+ * the `onClick ? {…} : {}` in every arm was saying.
+ */
+const SURFACES: Record<Variant, (input: SurfaceInput) => CSSObject> = {
+  filled: ({ theme, flags, accent }) => ({
+    backgroundColor: alpha(accent, 0.1),
+    borderRadius: theme.spacing(0.5),
+    '&:hover': flags.clickable ? { backgroundColor: alpha(accent, 0.15) } : {},
+  }),
+
+  outlined: ({ theme, flags, accent }) => ({
+    border: `1px solid ${alpha(accent, 0.5)}`,
+    borderRadius: theme.spacing(0.5),
+    '&:hover': flags.clickable
+      ? { borderColor: accent, backgroundColor: alpha(accent, 0.05) }
+      : {},
+  }),
+
+  glass: ({ theme, flags }) => ({
+    backgroundColor: alpha(theme.palette.background.paper, 0.1),
+    backdropFilter: 'blur(10px)',
+    border: `1px solid ${alpha(theme.palette.divider, 0.2)}`,
+    borderRadius: theme.spacing(0.5),
+    '&:hover': flags.clickable
+      ? {
+          backgroundColor: alpha(theme.palette.background.paper, 0.15),
+          borderColor: alpha(theme.palette.primary.main, 0.3),
+        }
+      : {},
+  }),
+
+  gradient: ({ theme, flags }) => {
+    const key = flags.color === 'default' ? 'primary' : flags.color;
+    // The gradient paints the glyphs themselves rather than the box behind them.
+    const clip = {
+      WebkitBackgroundClip: 'text',
+      WebkitTextFillColor: 'transparent',
+      backgroundClip: 'text',
+    };
+
+    return {
+      background: `linear-gradient(135deg, ${theme.palette[key].light}, ${theme.palette[key].main})`,
+      ...clip,
+      '&:hover': flags.clickable
+        ? {
+            background: `linear-gradient(135deg, ${theme.palette[key].main}, ${theme.palette[key].dark})`,
+            ...clip,
+          }
+        : {},
+    };
+  },
+
+  minimal: ({ theme, flags }) => ({
+    padding: 0,
+    '&:hover': flags.clickable ? { color: theme.palette.primary.main } : {},
+  }),
+
+  default: () => ({}),
+};
+
+/** How the text sits: its alignment, weight, casing and overflow behaviour. */
+const textLayout = (theme: Theme, flags: LabelStyleFlags): CSSObject => {
+  const { srOnly, clickable, align, weight, transform, nowrap, truncate } = flags;
+
+  return {
+    display: srOnly ? 'none' : 'inline-flex',
+    alignItems: 'center',
+    gap: theme.spacing(0.5),
+    transition: theme.transitions.create(['all'], {
+      duration: theme.transitions.duration.standard,
+    }),
+    cursor: clickable ? 'pointer' : 'default',
+    textAlign: align,
+    fontWeight: fontWeight(weight),
+    textTransform: transform,
+    whiteSpace: nowrap ? 'nowrap' : 'normal',
+    overflow: truncate ? 'hidden' : 'visible',
+    textOverflow: truncate ? 'ellipsis' : 'clip',
+    position: 'relative' as const,
+  };
+};
+
+export const labelStyles = (theme: Theme, flags: LabelStyleFlags): CSSObject => {
+  const { variant, size, clickable } = flags;
+  const color = textColor(theme, flags);
+  const accent = color || theme.palette.primary.main;
+
+  return {
+    ...textLayout(theme, flags),
+    ...sizeStyles(theme, size),
+    color,
+    ...(flags.glow && { textShadow: `0 0 10px ${alpha(accent, 0.5)}` }),
+    ...(flags.pulse && {
+      animation: 'pulse 2s infinite',
+      '@keyframes pulse': {
+        '0%': { opacity: 1 },
+        '50%': { opacity: 0.6 },
+        '100%': { opacity: 1 },
+      },
+    }),
+    ...(flags.ripple && clickable && rippleStyles(theme)),
+    ...(SURFACES[variant] ?? SURFACES.default)({ theme, flags, accent }),
+  };
+};
+
+/** Visually hidden but still read aloud, for the `srOnly` label. */
+export const SR_ONLY_SX: CSSObject = {
+  position: 'absolute',
+  width: '1px',
+  height: '1px',
+  padding: 0,
+  margin: '-1px',
+  overflow: 'hidden',
+  clip: 'rect(0, 0, 0, 0)',
+  whiteSpace: 'nowrap',
+  border: 0,
+};

package/src/components/form/Label/Label.test.stories.tsx

@@ -2,7 +2,7 @@ import InfoIcon from '@mui/icons-material/Info';
 import { Box, Stack,TextField } from '@mui/material';
 import type { Meta, StoryObj } from '@storybook/react-vite';
 import React from 'react';
-import { expect, fn,userEvent, waitFor, within } from 'storybook/test';
+import { expect, fireEvent, fn,userEvent, waitFor, within } from 'storybook/test';
 
 import { Label } from './Label';
 
@@ -247,23 +247,23 @@ export const KeyboardNavigation: Story = {
       const firstInput = firstInputContainer.querySelector('input');
 
       // Focus first label
-      firstLabel.focus();
-      await expect(firstLabel).toHaveFocus();
+      await userEvent.click(firstLabel);
+      await waitFor(() => expect(firstLabel).toHaveFocus());
 
       // Tab to input
       await userEvent.tab();
-      await expect(firstInput).toHaveFocus();
+      await waitFor(() => expect(firstInput).toHaveFocus());
     });
 
     await step('Tab navigation backward', async () => {
       await userEvent.tab({ shift: true });
       const firstLabel = canvas.getByTestId('first-label');
-      await expect(firstLabel).toHaveFocus();
+      await waitFor(() => expect(firstLabel).toHaveFocus());
     });
 
     await step('Enter key activation on clickable label', async () => {
       const firstLabel = canvas.getByTestId('first-label');
-      firstLabel.focus();
+      await userEvent.click(firstLabel);
       await userEvent.keyboard('{Enter}');
       // Verify click handler would be called
     });
@@ -641,14 +641,20 @@ export const PerformanceTest: Story = {
     await step('Test scroll performance', async () => {
       const scrollContainer = canvas.getByTestId('scroll-container');
 
-      // Simulate rapid scrolling
-      for (let i = 0; i < 10; i++) {
-        scrollContainer.scrollTop = i * 40;
-        await new Promise((resolve) => window.setTimeout(resolve, 50));
-      }
-
-      // Verify no janky behavior
-      await expect(scrollContainer).toBeInTheDocument();
+      // Scrolling is the one thing this story is about, so it has to move the
+      // container; what it must not do is assert a pixel offset, which depends
+      // on the viewport the story happens to render in.
+      // eslint-disable-next-line test-flakiness/no-viewport-dependent -- the subject under test is scrolling itself
+      scrollContainer.scrollTop = scrollContainer.scrollHeight;
+      fireEvent.scroll(scrollContainer);
+
+      // The labels are not virtualised, so scrolling must leave every one of
+      // them mounted — which is what the old toBeInTheDocument() on the
+      // container itself could never have caught, since the container was
+      // already there before the loop ran.
+      await waitFor(() => {
+        expect(canvas.getAllByTestId(/^label-\d+$/)).toHaveLength(100);
+      });
     });
   },
 };

package/src/components/form/Label/Label.tsx

@@ -1,296 +1,51 @@
-import {
-  alpha,
-  Box,
-  CircularProgress,
-  Tooltip,
-  Typography,
-  useTheme,
-} from '@mui/material';
+import { Box, Tooltip, Typography, useTheme } from '@mui/material';
 import React, { forwardRef } from 'react';
 
-import type { LabelProps } from './Label.types';
-
-export const Label = forwardRef<globalThis.HTMLLabelElement, LabelProps>(({
-  children,
-  htmlFor,
-  required = false,
-  disabled = false,
-  error = false,
-  variant = 'default',
-  size = 'md',
-  color = 'default',
-  glow = false,
-  pulse = false,
-  ripple = false,
-  loading = false,
-  className,
-  style,
-  tooltip,
-  helperText,
-  asteriskPlacement = 'end',
-  icon,
-  iconPosition = 'start',
-  onClick,
-  onFocus,
-  onBlur,
-  srOnly = false,
-  weight = 'regular',
-  transform = 'none',
-  align = 'left',
-  nowrap = false,
-  truncate = false,
-  dataTestId,
-  ...props
-}, ref) => {
-  const theme = useTheme();
-
-  const getSizeStyles = () => {
-    switch (size) {
-      case 'xs':
-        return {
-          fontSize: '0.75rem',
-          lineHeight: 1.2,
-          padding: theme.spacing(0.25, 0.5),
-        };
-      case 'sm':
-        return {
-          fontSize: '0.875rem',
-          lineHeight: 1.3,
-          padding: theme.spacing(0.5, 0.75),
-        };
-      case 'md':
-        return {
-          fontSize: '1rem',
-          lineHeight: 1.5,
-          padding: theme.spacing(0.75, 1),
-        };
-      case 'lg':
-        return {
-          fontSize: '1.125rem',
-          lineHeight: 1.6,
-          padding: theme.spacing(1, 1.25),
-        };
-      case 'xl':
-        return {
-          fontSize: '1.25rem',
-          lineHeight: 1.7,
-          padding: theme.spacing(1.25, 1.5),
-        };
-      default:
-        return {
-          fontSize: '1rem',
-          lineHeight: 1.5,
-          padding: theme.spacing(0.75, 1),
-        };
-    }
-  };
-
-  const getColorStyles = () => {
-    if (error) {
-      return { color: theme.palette.error.main };
-    }
-    if (disabled) {
-      return { color: theme.palette.text.disabled };
-    }
-    if (color === 'default') {
-      return { color: theme.palette.text.primary };
-    }
-    return { color: theme.palette[color].main };
-  };
-
-  const getVariantStyles = () => {
-    const baseStyles = {
-      display: srOnly ? 'none' : 'inline-flex',
-      alignItems: 'center',
-      gap: theme.spacing(0.5),
-      transition: theme.transitions.create(['all'], {
-        duration: theme.transitions.duration.standard,
-      }),
-      cursor: onClick ? 'pointer' : 'default',
-      textAlign: align,
-      fontWeight: getFontWeight(),
-      textTransform: transform,
-      whiteSpace: nowrap ? 'nowrap' : 'normal',
-      overflow: truncate ? 'hidden' : 'visible',
-      textOverflow: truncate ? 'ellipsis' : 'clip',
-      position: 'relative' as const,
-      ...getSizeStyles(),
-      ...getColorStyles(),
-    };
-
-    const glowStyles = glow ? {
-      textShadow: `0 0 10px ${alpha(getColorStyles().color || theme.palette.primary.main, 0.5)}`,
-    } : {};
-
-    const pulseStyles = pulse ? {
-      animation: 'pulse 2s infinite',
-      '@keyframes pulse': {
-        '0%': { opacity: 1 },
-        '50%': { opacity: 0.6 },
-        '100%': { opacity: 1 },
-      },
-    } : {};
-
-    const rippleStyles = ripple && onClick ? {
-      overflow: 'hidden',
-      '&::after': {
-        content: '""',
-        position: 'absolute',
-        top: '50%',
-        left: '50%',
-        width: 0,
-        height: 0,
-        borderRadius: '50%',
-        backgroundColor: alpha(theme.palette.primary.main, 0.3),
-        transform: 'translate(-50%, -50%)',
-        transition: 'width 0.6s, height 0.6s',
-      },
-      '&:active::after': {
-        width: '300%',
-        height: '300%',
-      },
-    } : {};
+import { withDefaults } from '../../../utils/withDefaults';
 
-    switch (variant) {
-      case 'filled':
-        return {
-          ...baseStyles,
-          ...glowStyles,
-          ...pulseStyles,
-          ...rippleStyles,
-          backgroundColor: alpha(getColorStyles().color || theme.palette.primary.main, 0.1),
-          borderRadius: theme.spacing(0.5),
-          '&:hover': onClick ? {
-            backgroundColor: alpha(getColorStyles().color || theme.palette.primary.main, 0.15),
-          } : {},
-        };
-
-      case 'outlined':
-        return {
-          ...baseStyles,
-          ...glowStyles,
-          ...pulseStyles,
-          ...rippleStyles,
-          border: `1px solid ${alpha(getColorStyles().color || theme.palette.primary.main, 0.5)}`,
-          borderRadius: theme.spacing(0.5),
-          '&:hover': onClick ? {
-            borderColor: getColorStyles().color || theme.palette.primary.main,
-            backgroundColor: alpha(getColorStyles().color || theme.palette.primary.main, 0.05),
-          } : {},
-        };
-
-      case 'glass':
-        return {
-          ...baseStyles,
-          ...glowStyles,
-          ...pulseStyles,
-          ...rippleStyles,
-          backgroundColor: alpha(theme.palette.background.paper, 0.1),
-          backdropFilter: 'blur(10px)',
-          border: `1px solid ${alpha(theme.palette.divider, 0.2)}`,
-          borderRadius: theme.spacing(0.5),
-          '&:hover': onClick ? {
-            backgroundColor: alpha(theme.palette.background.paper, 0.15),
-            borderColor: alpha(theme.palette.primary.main, 0.3),
-          } : {},
-        };
-
-      case 'gradient': {
-        const gradientColor = color === 'default' ? 'primary' : color;
-        return {
-          ...baseStyles,
-          ...glowStyles,
-          ...pulseStyles,
-          ...rippleStyles,
-          background: `linear-gradient(135deg, ${theme.palette[gradientColor].light}, ${theme.palette[gradientColor].main})`,
-          WebkitBackgroundClip: 'text',
-          WebkitTextFillColor: 'transparent',
-          backgroundClip: 'text',
-          '&:hover': onClick ? {
-            background: `linear-gradient(135deg, ${theme.palette[gradientColor].main}, ${theme.palette[gradientColor].dark})`,
-            WebkitBackgroundClip: 'text',
-            WebkitTextFillColor: 'transparent',
-            backgroundClip: 'text',
-          } : {},
-        };
-      }
-
-      case 'minimal':
-        return {
-          ...baseStyles,
-          ...glowStyles,
-          ...pulseStyles,
-          ...rippleStyles,
-          padding: 0,
-          '&:hover': onClick ? {
-            color: theme.palette.primary.main,
-          } : {},
-        };
-
-      default:
-        return {
-          ...baseStyles,
-          ...glowStyles,
-          ...pulseStyles,
-          ...rippleStyles,
-        };
-    }
-  };
+import { LabelBody } from './Label.parts';
+import { labelStyles, sizeStyles, SR_ONLY_SX, textColor } from './Label.styles';
+import type { LabelStyleFlags } from './Label.styles';
+import type { LabelProps } from './Label.types';
 
-  const getFontWeight = () => {
-    switch (weight) {
-      case 'light': return 300;
-      case 'regular': return 400;
-      case 'medium': return 500;
-      case 'semibold': return 600;
-      case 'bold': return 700;
-      default: return 400;
-    }
-  };
+const DEFAULTS = {
+  required: false,
+  disabled: false,
+  error: false,
+  variant: 'default',
+  size: 'md',
+  color: 'default',
+  glow: false,
+  pulse: false,
+  ripple: false,
+  loading: false,
+  asteriskPlacement: 'end',
+  iconPosition: 'start',
+  srOnly: false,
+  weight: 'regular',
+  transform: 'none',
+  align: 'left',
+  nowrap: false,
+  truncate: false,
+} satisfies Partial<LabelProps>;
+
+type ResolvedProps = LabelProps & Required<Pick<LabelProps, keyof typeof DEFAULTS>>;
+
+export const Label = forwardRef<globalThis.HTMLLabelElement, LabelProps>((props, ref) => {
+  const {
+    children, htmlFor, required, disabled, error, variant, size, color,
+    glow, pulse, ripple, loading, className, style, tooltip, helperText,
+    asteriskPlacement, icon, iconPosition, onClick, onFocus, onBlur,
+    srOnly, weight, transform, align, nowrap, truncate, dataTestId,
+    ...rest
+  } = withDefaults(props, DEFAULTS) as ResolvedProps;
 
-  const renderAsterisk = () => {
-    if (!required) return null;
-    return (
-      <Box
-        component="span"
-        sx={{
-          color: theme.palette.error.main,
-          marginLeft: asteriskPlacement === 'end' ? theme.spacing(0.5) : 0,
-          marginRight: asteriskPlacement === 'start' ? theme.spacing(0.5) : 0,
-        }}
-      >
-        *
-      </Box>
-    );
-  };
-
-  const renderIcon = () => {
-    if (!icon) return null;
-    return (
-      <Box
-        component="span"
-        sx={{
-          display: 'inline-flex',
-          alignItems: 'center',
-          fontSize: 'inherit',
-        }}
-      >
-        {icon}
-      </Box>
-    );
-  };
+  const theme = useTheme();
 
-  const renderLoading = () => {
-    if (!loading) return null;
-    return (
-      <CircularProgress
-        size={getSizeStyles().fontSize}
-        sx={{
-          color: getColorStyles().color,
-          marginLeft: theme.spacing(0.5),
-        }}
-      />
-    );
+  const flags: LabelStyleFlags = {
+    variant, size, color, weight, transform, align,
+    error, disabled, glow, pulse, ripple, srOnly, nowrap, truncate,
+    clickable: Boolean(onClick),
   };
 
   const labelContent = (
@@ -303,51 +58,44 @@ export const Label = forwardRef<globalThis.HTMLLabelElement, LabelProps>(({
       onBlur={onBlur}
       className={className}
       data-testid={dataTestId}
-      sx={{
-        ...getVariantStyles(),
-        ...style,
-      }}
-      {...props}
+      sx={{ ...labelStyles(theme, flags), ...style }}
+      {...rest}
     >
-      {asteriskPlacement === 'start' && renderAsterisk()}
-      {iconPosition === 'start' && renderIcon()}
-      {children}
-      {iconPosition === 'end' && renderIcon()}
-      {asteriskPlacement === 'end' && renderAsterisk()}
-      {renderLoading()}
+      <LabelBody
+        required={required}
+        asteriskPlacement={asteriskPlacement}
+        icon={icon}
+        iconPosition={iconPosition}
+        loading={loading}
+        fontSize={sizeStyles(theme, size).fontSize as string}
+        color={textColor(theme, flags)}
+      >
+        {children}
+      </LabelBody>
     </Box>
   );
 
-  const wrappedContent = tooltip ? (
-    <Tooltip title={tooltip} arrow>
-      {labelContent}
-    </Tooltip>
-  ) : labelContent;
+  // A screen-reader-only label is rendered on its own: the tooltip, the styling
+  // and the helper text all describe something nothing can see.
+  if (srOnly) {
+    return (
+      <Box component="label" htmlFor={htmlFor} data-testid={dataTestId} sx={SR_ONLY_SX}>
+        {children}
+      </Box>
+    );
+  }
 
   return (
     <>
-      {srOnly && (
-        <Box
-          component="label"
-          htmlFor={htmlFor}
-          data-testid={dataTestId}
-          sx={{
-            position: 'absolute',
-            width: '1px',
-            height: '1px',
-            padding: 0,
-            margin: '-1px',
-            overflow: 'hidden',
-            clip: 'rect(0, 0, 0, 0)',
-            whiteSpace: 'nowrap',
-            border: 0,
-          }}
-        >
-          {children}
-        </Box>
+      {tooltip ? (
+        <Tooltip title={tooltip} arrow>
+          {labelContent}
+        </Tooltip>
+      ) : (
+        labelContent
       )}
-      {!srOnly && wrappedContent}
-      {helperText && !srOnly && (
+
+      {helperText && (
         <Typography
           variant="caption"
           sx={{
@@ -364,4 +112,4 @@ export const Label = forwardRef<globalThis.HTMLLabelElement, LabelProps>(({
   );
 });
 
-Label.displayName = 'Label';
+Label.displayName = 'Label';