@12-apps/ui 1.0.0 → 1.3.0

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

@@ -1,4 +1,6 @@
-import { Close, Error, Info } from '@mui/icons-material';
+import Close from '@mui/icons-material/Close';
+import Error from '@mui/icons-material/Error';
+import Info from '@mui/icons-material/Info';
 import type { ButtonProps } from '@mui/material';
 import {
   alpha,
@@ -54,8 +56,17 @@ const StyledDialog = styled(Dialog, {
       border: `1px solid ${alpha(theme.palette.divider, 0.2)}`,
     }),
 
+    // The error tint is LAYERED over the paper, not used as the background
+    // itself: `alpha(error, 0.05)` alone leaves the panel 95% transparent, so
+    // the page behind it showed straight through the question and its buttons.
+    // A confirm nobody can read is the one dialog that must never be hard to
+    // read. Same tint, opaque base.
     ...(customVariant === 'destructive' && {
-      backgroundColor: alpha(theme.palette.error.main, 0.05),
+      backgroundColor: theme.palette.background.paper,
+      backgroundImage: `linear-gradient(${alpha(theme.palette.error.main, 0.05)}, ${alpha(
+        theme.palette.error.main,
+        0.05,
+      )})`,
       border: `1px solid ${alpha(theme.palette.error.main, 0.2)}`,
     }),
 
@@ -141,6 +152,155 @@ const CloseButton = styled(IconButton)(({ theme }) => ({
   color: theme.palette.grey[500],
 }));
 
+/**
+ * Per-variant lookups, hoisted out of the render function. They depend on
+ * nothing but their arguments, so keeping them at module scope means they are
+ * not rebuilt on every render — and it keeps the component's own branch count
+ * inside the repo's complexity budget.
+ */
+const variantIcon = (
+  variant: AlertDialogProps['variant'],
+  icon: AlertDialogProps['icon'],
+): React.ReactNode => {
+  if (icon) return icon;
+  return variant === 'destructive' ? <Error color="error" /> : <Info color="primary" />;
+};
+
+/**
+ * Ids for the two elements that give the dialog its accessible name and
+ * description. Derived from the test id so they are stable and unique per
+ * dialog without a generated id that would change on every render.
+ */
+const titleId = (dataTestId: string): string => `${dataTestId}-title`;
+const descriptionId = (dataTestId: string): string => `${dataTestId}-description`;
+
+/**
+ * `alertdialog`, not `dialog`.
+ *
+ * This component interrupts what the operator was doing and will not go away
+ * until they answer — which is exactly the distinction the two roles draw, and
+ * it is what makes a screen reader announce the message itself on open rather
+ * than just the dialog's name. MUI hardcodes `role="dialog"` on the paper, so
+ * it has to be overridden through the paper slot.
+ */
+const ALERT_ROLE = 'alertdialog';
+
+/**
+ * The paper slot's a11y props: the role, plus the name and description wired to
+ * the elements that actually carry them, so the announcement is the QUESTION
+ * rather than the word "dialog".
+ *
+ * Both references are conditional — pointing `aria-labelledby` at an element
+ * that was never rendered leaves a dangling id, which screen readers treat as
+ * no name at all, i.e. worse than omitting it.
+ */
+function ariaSlotProps(
+  dataTestId: string,
+  title: AlertDialogProps['title'],
+  description: AlertDialogProps['description'],
+): { paper: Record<string, string> } {
+  return {
+    paper: {
+      role: ALERT_ROLE,
+      ...(title ? { 'aria-labelledby': titleId(dataTestId) } : {}),
+      ...(description ? { 'aria-describedby': descriptionId(dataTestId) } : {}),
+    },
+  };
+}
+
+/** Both variants render a filled confirm; only the colour distinguishes them. */
+const CONFIRM_BUTTON_VARIANT: ButtonProps['variant'] = 'contained';
+const confirmButtonColor = (variant: AlertDialogProps['variant']): 'error' | 'primary' =>
+  variant === 'destructive' ? 'error' : 'primary';
+
+/** Title row: the variant icon (unless explicitly suppressed with `null`) + the title. */
+function AlertDialogHeader({
+  title,
+  icon,
+  variant,
+  dataTestId,
+}: {
+  title: AlertDialogProps['title'];
+  icon: AlertDialogProps['icon'];
+  variant: AlertDialogProps['variant'];
+  dataTestId: string;
+}): React.ReactElement | null {
+  if (!title) return null;
+  return (
+    <StyledDialogTitle id={titleId(dataTestId)} data-testid={`${dataTestId}-title`}>
+      {icon !== null && (
+        <span data-testid={`${dataTestId}-icon`}>{variantIcon(variant, icon)}</span>
+      )}
+      <Typography variant="h6" component="span">
+        {title}
+      </Typography>
+    </StyledDialogTitle>
+  );
+}
+
+/** Action row: the optional cancel button and the (variant-coloured) confirm. */
+function AlertDialogFooter({
+  variant,
+  cancelText = 'Cancel',
+  confirmText = 'Confirm',
+  showCancel = true,
+  loading = false,
+  confirmDisabled = false,
+  initialFocus = 'confirm',
+  onCancel,
+  onConfirm,
+  dataTestId,
+}: Pick<
+  AlertDialogProps,
+  | 'variant'
+  | 'cancelText'
+  | 'confirmText'
+  | 'showCancel'
+  | 'loading'
+  | 'confirmDisabled'
+  | 'initialFocus'
+> & {
+  onCancel: () => void;
+  onConfirm: () => void;
+  dataTestId: string;
+}): React.ReactElement {
+  return (
+    <StyledDialogActions data-testid={`${dataTestId}-actions`}>
+      {showCancel && (
+        <Button
+          onClick={onCancel}
+          variant="outlined"
+          color="inherit"
+          disabled={loading}
+          autoFocus={initialFocus === 'cancel'}
+          data-testid={`${dataTestId}-cancel-button`}
+        >
+          {cancelText}
+        </Button>
+      )}
+      <Button
+        onClick={onConfirm}
+        variant={CONFIRM_BUTTON_VARIANT}
+        color={confirmButtonColor(variant)}
+        disabled={confirmDisabled || loading}
+        startIcon={
+          loading ? (
+            <CircularProgress
+              size={16}
+              color="inherit"
+              data-testid={`${dataTestId}-loading-spinner`}
+            />
+          ) : undefined
+        }
+        autoFocus={initialFocus !== 'cancel'}
+        data-testid={`${dataTestId}-confirm-button`}
+      >
+        {confirmText}
+      </Button>
+    </StyledDialogActions>
+  );
+}
+
 export const AlertDialog = React.forwardRef<HTMLDivElement, AlertDialogProps>(
   ({
     variant = 'default',
@@ -149,57 +309,24 @@ export const AlertDialog = React.forwardRef<HTMLDivElement, AlertDialogProps>(
     title,
     description,
     icon,
-    cancelText = 'Cancel',
-    confirmText = 'Confirm',
+    cancelText,
+    confirmText,
     onCancel,
     onConfirm,
-    showCancel = true,
-    loading = false,
-    confirmDisabled = false,
+    showCancel,
+    loading,
+    confirmDisabled,
+    initialFocus,
     children,
     onClose,
     'data-testid': dataTestId = 'alert-dialog',
     ...props
   }, ref) => {
-    
     const handleCancel = () => {
       onCancel?.();
       onClose?.({}, 'backdropClick');
     };
 
-    const handleConfirm = () => {
-      onConfirm?.();
-    };
-
-    const getVariantIcon = () => {
-      if (icon) return icon;
-      
-      switch (variant) {
-        case 'destructive':
-          return <Error color="error" />;
-        default:
-          return <Info color="primary" />;
-      }
-    };
-
-    const getConfirmButtonVariant = (): ButtonProps['variant'] => {
-      switch (variant) {
-        case 'destructive':
-          return 'contained';
-        default:
-          return 'contained';
-      }
-    };
-
-    const getConfirmButtonColor = () => {
-      switch (variant) {
-        case 'destructive':
-          return 'error';
-        default:
-          return 'primary';
-      }
-    };
-
     return (
       <StyledDialog
         ref={ref}
@@ -208,6 +335,7 @@ export const AlertDialog = React.forwardRef<HTMLDivElement, AlertDialogProps>(
         pulse={pulse}
         onClose={onClose}
         data-testid={dataTestId}
+        slotProps={ariaSlotProps(dataTestId, title, description)}
         {...props}
       >
         <CloseButton
@@ -219,52 +347,37 @@ export const AlertDialog = React.forwardRef<HTMLDivElement, AlertDialogProps>(
           <Close />
         </CloseButton>
 
-        {title && (
-          <StyledDialogTitle data-testid={`${dataTestId}-title`}>
-            {(icon !== null) && (
-              <span data-testid={`${dataTestId}-icon`}>
-                {getVariantIcon()}
-              </span>
-            )}
-            <Typography variant="h6" component="span">
-              {title}
-            </Typography>
-          </StyledDialogTitle>
-        )}
+        <AlertDialogHeader
+          title={title}
+          icon={icon}
+          variant={variant}
+          dataTestId={dataTestId}
+        />
 
         <StyledDialogContent data-testid={`${dataTestId}-content`}>
           {description && (
-            <DialogContentText data-testid={`${dataTestId}-description`}>
+            <DialogContentText
+              id={descriptionId(dataTestId)}
+              data-testid={`${dataTestId}-description`}
+            >
               {description}
             </DialogContentText>
           )}
           {children}
         </StyledDialogContent>
 
-        <StyledDialogActions data-testid={`${dataTestId}-actions`}>
-          {showCancel && (
-            <Button
-              onClick={handleCancel}
-              variant="outlined"
-              color="inherit"
-              disabled={loading}
-              data-testid={`${dataTestId}-cancel-button`}
-            >
-              {cancelText}
-            </Button>
-          )}
-          <Button
-            onClick={handleConfirm}
-            variant={getConfirmButtonVariant()}
-            color={getConfirmButtonColor()}
-            disabled={confirmDisabled || loading}
-            startIcon={loading ? <CircularProgress size={16} color="inherit" data-testid={`${dataTestId}-loading-spinner`} /> : undefined}
-            autoFocus
-            data-testid={`${dataTestId}-confirm-button`}
-          >
-            {confirmText}
-          </Button>
-        </StyledDialogActions>
+        <AlertDialogFooter
+          variant={variant}
+          cancelText={cancelText}
+          confirmText={confirmText}
+          showCancel={showCancel}
+          loading={loading}
+          confirmDisabled={confirmDisabled}
+          initialFocus={initialFocus}
+          onCancel={handleCancel}
+          onConfirm={() => onConfirm?.()}
+          dataTestId={dataTestId}
+        />
       </StyledDialog>
     );
   }

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

@@ -25,7 +25,7 @@ export interface AlertDialogProps extends Omit<MuiDialogProps, 'variant'> {
   /**
    * Description text
    */
-  description?: string;
+  description?: React.ReactNode;
 
   /**
    * Icon to display in the dialog
@@ -67,6 +67,13 @@ export interface AlertDialogProps extends Omit<MuiDialogProps, 'variant'> {
    */
   confirmDisabled?: boolean;
 
+  /**
+   * Which button owns focus when the dialog opens. Defaults to `confirm`, which
+   * is right for an acknowledgement; a destructive dialog should pass `cancel`
+   * so a stray Enter on the trigger cannot complete the action.
+   */
+  initialFocus?: 'confirm' | 'cancel';
+
   /**
    * Optional data-testid attribute for testing
    */

package/src/components/data-display/AsyncStateContainer/AsyncStateContainer.test.stories.tsx

@@ -1,6 +1,6 @@
 import { Typography } from '@mui/material';
 import type { Meta, StoryObj } from '@storybook/react-vite';
-import { expect, fn, userEvent, within } from 'storybook/test';
+import { expect, fn, userEvent, waitFor, within } from 'storybook/test';
 
 import { EmptyState } from '../EmptyState/EmptyState';
 
@@ -66,7 +66,7 @@ export const LoadingStateTest: Story = {
 
     await step('Verify children content is NOT rendered', async () => {
       const content = canvas.queryByTestId('success-content');
-      await expect(content).not.toBeInTheDocument();
+      await waitFor(() => expect(content).not.toBeInTheDocument());
     });
 
     await step('Verify loading component is rendered', async () => {
@@ -94,7 +94,7 @@ export const ErrorStateTest: Story = {
 
     await step('Verify children content is NOT rendered', async () => {
       const content = canvas.queryByTestId('success-content');
-      await expect(content).not.toBeInTheDocument();
+      await waitFor(() => expect(content).not.toBeInTheDocument());
     });
 
     await step('Verify error component is rendered', async () => {
@@ -127,7 +127,7 @@ export const EmptyStateTest: Story = {
 
     await step('Verify children content is NOT rendered', async () => {
       const content = canvas.queryByTestId('success-content');
-      await expect(content).not.toBeInTheDocument();
+      await waitFor(() => expect(content).not.toBeInTheDocument());
     });
 
     await step('Verify empty state component is rendered', async () => {
@@ -158,7 +158,7 @@ export const PriorityTest: Story = {
       await expect(loading).toBeInTheDocument();
 
       const error = canvas.queryByTestId('error-state');
-      await expect(error).not.toBeInTheDocument();
+      await waitFor(() => expect(error).not.toBeInTheDocument());
     });
   },
 };

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

@@ -38,6 +38,37 @@ import type { AsyncStateContainerProps } from './AsyncStateContainer.types';
  *   <DataGrid data={data} />
  * </AsyncStateContainer>
  */
+// The four states render the same wrapper, differing only in data-state and
+// what goes inside it.
+const StateBox: React.FC<{
+  state: 'loading' | 'error' | 'empty' | 'success';
+  className?: string;
+  dataTestId?: string;
+  children: React.ReactNode;
+}> = ({ state, className, dataTestId, children }) => (
+  <Box
+    className={className}
+    data-testid={dataTestId || 'async-state-container'}
+    data-state={state}
+  >
+    {children}
+  </Box>
+);
+
+const errorMessageOf = (error: unknown): string => {
+  if (!error) return '';
+  if (typeof error === 'string') return error;
+  if (error instanceof Error) return error.message;
+  return 'An unexpected error occurred';
+};
+
+// Each state takes a ready-made node, else a render function, else the default.
+const pickNode = (
+  node: React.ReactNode,
+  render: (() => React.ReactNode) | undefined,
+  fallback: React.ReactNode,
+): React.ReactNode => node || render?.() || fallback;
+
 export const AsyncStateContainer: React.FC<AsyncStateContainerProps> = React.memo(
   ({
     isLoading = false,
@@ -53,60 +84,38 @@ export const AsyncStateContainer: React.FC<AsyncStateContainerProps> = React.mem
     className,
     dataTestId,
   }) => {
-    // Helper to extract error message from various error types
-    const getErrorMessage = (): string => {
-      if (!error) return '';
-      if (typeof error === 'string') return error;
-      if (error instanceof Error) return error.message;
-      return 'An unexpected error occurred';
-    };
+    const box = { className, dataTestId };
 
     // Priority: loading > error > empty > children
     if (isLoading) {
       return (
-        <Box
-          className={className}
-          data-testid={dataTestId || 'async-state-container'}
-          data-state="loading"
-        >
-          {loadingComponent || renderLoading?.() || <LoadingState />}
-        </Box>
+        <StateBox state="loading" {...box}>
+          {pickNode(loadingComponent, renderLoading, <LoadingState />)}
+        </StateBox>
       );
     }
 
     if (error) {
-      const errorMessage = getErrorMessage();
+      const message = errorMessageOf(error);
       return (
-        <Box
-          className={className}
-          data-testid={dataTestId || 'async-state-container'}
-          data-state="error"
-        >
-          {errorComponent || renderError?.(errorMessage) || <ErrorState message={errorMessage} />}
-        </Box>
+        <StateBox state="error" {...box}>
+          {errorComponent || renderError?.(message) || <ErrorState message={message} />}
+        </StateBox>
       );
     }
 
     if (isEmpty) {
       return (
-        <Box
-          className={className}
-          data-testid={dataTestId || 'async-state-container'}
-          data-state="empty"
-        >
-          {emptyComponent || renderEmpty?.() || <EmptyState title="No data available" />}
-        </Box>
+        <StateBox state="empty" {...box}>
+          {pickNode(emptyComponent, renderEmpty, <EmptyState title="No data available" />)}
+        </StateBox>
       );
     }
 
     return (
-      <Box
-        className={className}
-        data-testid={dataTestId || 'async-state-container'}
-        data-state="success"
-      >
+      <StateBox state="success" {...box}>
         {children}
-      </Box>
+      </StateBox>
     );
   },
 );

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

@@ -1,4 +1,7 @@
-import { Email, Notifications, Phone, Settings } from '@mui/icons-material';
+import Email from '@mui/icons-material/Email';
+import Notifications from '@mui/icons-material/Notifications';
+import Phone from '@mui/icons-material/Phone';
+import Settings from '@mui/icons-material/Settings';
 import { Badge, Box, Paper, Stack, Typography } from '@mui/material';
 import type { Meta, StoryObj } from '@storybook/react-vite';
 import React, { useState } from 'react';

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

@@ -1,4 +1,4 @@
-import { Person } from '@mui/icons-material';
+import Person from '@mui/icons-material/Person';
 import { Box,Stack } from '@mui/material';
 import type { Meta, StoryObj } from '@storybook/react-vite';
 import React from 'react';
@@ -494,8 +494,10 @@ export const AvatarGroupTest: Story = {
       await expect(avatar3).toBeInTheDocument();
 
       // Avatar 4 and 5 should not be in the document (hidden by max=3)
-      await expect(canvas.queryByTestId('group-avatar-4')).not.toBeInTheDocument();
-      await expect(canvas.queryByTestId('group-avatar-5')).not.toBeInTheDocument();
+      await waitFor(() => {
+        expect(canvas.queryByTestId('group-avatar-4')).not.toBeInTheDocument();
+        expect(canvas.queryByTestId('group-avatar-5')).not.toBeInTheDocument();
+      });
     });
 
     await step('Verify overflow indicator', async () => {