@12-apps/ui 1.0.0 → 1.3.0

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

@@ -54,47 +54,65 @@ export interface DescriptionItemProps {
  * />
  * ```
  */
+// Vertical stacks the label above the value; horizontal sets them side by side
+// with the label sized to its content.
+const containerSx = (isHorizontal: boolean) => ({
+  display: 'flex',
+  flexDirection: isHorizontal ? ('row' as const) : ('column' as const),
+  alignItems: isHorizontal ? 'center' : 'flex-start',
+  gap: isHorizontal ? 1 : 0,
+});
+
+const labelStyle = (isHorizontal: boolean) => ({
+  textTransform: 'uppercase' as const,
+  marginBottom: isHorizontal ? 0 : '0.25rem',
+  minWidth: isHorizontal ? ('fit-content' as const) : undefined,
+  flexShrink: isHorizontal ? 0 : undefined,
+});
+
+const makeTestId =
+  (dataTestId?: string) =>
+  (suffix: string): string =>
+    dataTestId ? `${dataTestId}-${suffix}` : `description-item-${suffix}`;
+
 export const DescriptionItem: React.FC<DescriptionItemProps> = ({
   label,
   value,
   orientation = 'vertical',
   className,
   'data-testid': dataTestId,
-}) => (
-  <Box
-    className={className}
-    sx={{
-      display: 'flex',
-      flexDirection: orientation === 'vertical' ? 'column' : 'row',
-      alignItems: orientation === 'horizontal' ? 'center' : 'flex-start',
-      gap: orientation === 'horizontal' ? 1 : 0,
-    }}
-    data-testid={dataTestId || 'description-item'}
-  >
-    <Text
-      variant="caption"
-      size="xs"
-      color="secondary"
-      style={{
-        textTransform: 'uppercase',
-        marginBottom: orientation === 'vertical' ? '0.25rem' : 0,
-        minWidth: orientation === 'horizontal' ? 'fit-content' : undefined,
-        flexShrink: orientation === 'horizontal' ? 0 : undefined,
-      }}
-      data-testid={dataTestId ? `${dataTestId}-label` : 'description-item-label'}
+}) => {
+  const isHorizontal = orientation === 'horizontal';
+  const testId = makeTestId(dataTestId);
+
+  return (
+    <Box
+      className={className}
+      sx={containerSx(isHorizontal)}
+      data-testid={dataTestId || 'description-item'}
     >
-      {label}
-    </Text>
-    <Box data-testid={dataTestId ? `${dataTestId}-value` : 'description-item-value'}>
-      {typeof value === 'string' || typeof value === 'number' ? (
-        <Text variant="body" size="sm" weight="semibold">
-          {value}
-        </Text>
-      ) : (
-        value
-      )}
+      <Text
+        variant="caption"
+        size="xs"
+        color="secondary"
+        style={labelStyle(isHorizontal)}
+        data-testid={testId('label')}
+      >
+        {label}
+      </Text>
+      <Box data-testid={testId('value')}>
+        {/* Plain text gets the component's own typography; anything else is
+            rendered as given. */}
+        {typeof value === 'string' || typeof value === 'number' ? (
+          <Text variant="body" size="sm" weight="semibold">
+            {value}
+          </Text>
+        ) : (
+          value
+        )}
+      </Box>
     </Box>
-  </Box>
-);
+  );
+};
 
 DescriptionItem.displayName = 'DescriptionItem';

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

@@ -133,7 +133,7 @@ export const KeyboardNavigation: Story = {
     // Tab to primary button
     await userEvent.tab();
     const primaryButton = canvas.getByRole('button', { name: 'Primary' });
-    await expect(primaryButton).toHaveFocus();
+    await waitFor(() => expect(primaryButton).toHaveFocus());
 
     // Press Enter to activate
     await userEvent.keyboard('{Enter}');
@@ -142,12 +142,12 @@ export const KeyboardNavigation: Story = {
     // Tab to secondary button
     await userEvent.tab();
     const secondaryButton = canvas.getByRole('button', { name: 'Secondary' });
-    await expect(secondaryButton).toHaveFocus();
+    await waitFor(() => expect(secondaryButton).toHaveFocus());
 
     // Tab to help link
     await userEvent.tab();
     const helpLink = canvas.getByRole('link', { name: 'Help' });
-    await expect(helpLink).toHaveFocus();
+    await waitFor(() => expect(helpLink).toHaveFocus());
   },
 };
 
@@ -203,14 +203,14 @@ export const FocusManagement: Story = {
 
     // Test focus indicators are visible
     await userEvent.tab();
-    await expect(button).toHaveFocus();
+    await waitFor(() => expect(button).toHaveFocus());
 
     await userEvent.tab();
-    await expect(link).toHaveFocus();
+    await waitFor(() => expect(link).toHaveFocus());
 
     // Test focus trap doesn't exist (buttons should be focusable)
     await userEvent.tab();
-    await expect(link).not.toHaveFocus();
+    await waitFor(() => expect(link).not.toHaveFocus());
   },
 };
 

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

@@ -12,23 +12,211 @@ import React from 'react';
 
 import type { EmptyStateProps } from './EmptyState.types';
 
-export const EmptyState: React.FC<EmptyStateProps> = React.memo(({
-  variant = 'default',
-  title,
-  description,
-  illustration,
-  primaryAction,
-  secondaryAction,
-  helpLink,
-  onRefresh,
-  refreshLabel = 'Refresh',
-  onCreate,
-  createLabel = 'Create New',
-  className,
-  dataTestId,
-}) => {
+type EmptyStateVariant = NonNullable<EmptyStateProps['variant']>;
+
+const makeTestId =
+  (dataTestId?: string) =>
+  (suffix: string): string =>
+    dataTestId ? `${dataTestId}-${suffix}` : `empty-state-${suffix}`;
+
+interface ActionSpec {
+  key: string;
+  variant: 'contained' | 'outlined';
+  onClick: () => void;
+  label: string;
+  icon?: React.ReactNode;
+}
+
+// The four buttons are one button with different props. Listing them keeps their
+// order — primary, create, secondary, refresh — visible in one place.
+const actionsOf = (
+  props: EmptyStateProps,
+  refreshLabel: string,
+  createLabel: string,
+): ActionSpec[] => {
+  const { primaryAction, secondaryAction, onCreate, onRefresh } = props;
+  const specs: ActionSpec[] = [];
+
+  if (primaryAction) {
+    specs.push({
+      key: 'primary-action',
+      variant: 'contained',
+      onClick: primaryAction.onClick,
+      label: primaryAction.label,
+    });
+  }
+  if (onCreate) {
+    specs.push({
+      key: 'create-button',
+      variant: 'contained',
+      onClick: onCreate,
+      label: createLabel,
+      icon: <AddIcon />,
+    });
+  }
+  if (secondaryAction) {
+    specs.push({
+      key: 'secondary-action',
+      variant: 'outlined',
+      onClick: secondaryAction.onClick,
+      label: secondaryAction.label,
+    });
+  }
+  if (onRefresh) {
+    specs.push({
+      key: 'refresh-button',
+      variant: 'outlined',
+      onClick: onRefresh,
+      label: refreshLabel,
+      icon: <RefreshIcon />,
+    });
+  }
+
+  return specs;
+};
+
+const Illustration: React.FC<{
+  illustration: React.ReactNode;
+  variant: EmptyStateVariant;
+  testId: string;
+}> = ({ illustration, variant, testId }) => (
+  <Box
+    data-testid={testId}
+    sx={{
+      maxWidth: variant === 'illustrated' ? 240 : 120,
+      width: '100%',
+      height: 'auto',
+      opacity: variant === 'minimal' ? 0.6 : 0.8,
+      display: variant === 'minimal' ? 'none' : 'block',
+    }}
+  >
+    {illustration}
+  </Box>
+);
+
+const Actions: React.FC<{
+  specs: ActionSpec[];
+  testId: (suffix: string) => string;
+}> = ({ specs, testId }) => {
+  const theme = useTheme();
+
+  return (
+    <Stack
+      direction={{ xs: 'column', sm: 'row' }}
+      spacing={2}
+      alignItems="center"
+      sx={{ mt: theme.spacing(2) }}
+    >
+      {specs.map((spec) => (
+        <Button
+          key={spec.key}
+          variant={spec.variant}
+          onClick={spec.onClick}
+          startIcon={spec.icon}
+          data-testid={testId(spec.key)}
+          sx={{ minWidth: 120 }}
+        >
+          {spec.label}
+        </Button>
+      ))}
+    </Stack>
+  );
+};
+
+const HelpLink: React.FC<{
+  helpLink: NonNullable<EmptyStateProps['helpLink']>;
+  testId: string;
+}> = ({ helpLink, testId }) => {
+  const theme = useTheme();
+
+  return (
+    <Link
+      href={helpLink.href}
+      target={helpLink.external ? '_blank' : undefined}
+      rel={helpLink.external ? 'noopener noreferrer' : undefined}
+      data-testid={testId}
+      sx={{
+        mt: theme.spacing(1),
+        color: theme.palette.primary.main,
+        textDecoration: 'none',
+        '&:hover': {
+          textDecoration: 'underline',
+        },
+      }}
+    >
+      {helpLink.label}
+      {helpLink.external && ' ↗'}
+    </Link>
+  );
+};
+
+const Content: React.FC<{
+  title: string;
+  description?: string;
+  titleId: string;
+  testId: (suffix: string) => string;
+  actions: ActionSpec[];
+  showActions: boolean;
+  helpLink?: EmptyStateProps['helpLink'];
+}> = ({ title, description, titleId, testId, actions, showActions, helpLink }) => {
+  const theme = useTheme();
+
+  return (
+    <Stack spacing={2} alignItems="center">
+      <Typography
+        id={titleId}
+        variant="h6"
+        component="h3"
+        data-testid={testId('title')}
+        sx={{
+          fontWeight: theme.typography.fontWeightMedium,
+          color: theme.palette.text.primary,
+          maxWidth: 400,
+        }}
+      >
+        {title}
+      </Typography>
+
+      {description && (
+        <Typography
+          variant="body2"
+          color="text.secondary"
+          data-testid={testId('description')}
+          sx={{
+            maxWidth: 480,
+            lineHeight: 1.6,
+          }}
+        >
+          {description}
+        </Typography>
+      )}
+
+      {showActions && <Actions specs={actions} testId={testId} />}
+
+      {helpLink && <HelpLink helpLink={helpLink} testId={testId('help-link')} />}
+    </Stack>
+  );
+};
+
+export const EmptyState: React.FC<EmptyStateProps> = React.memo((props) => {
+  const {
+    variant = 'default',
+    title,
+    description,
+    illustration,
+    helpLink,
+    refreshLabel = 'Refresh',
+    createLabel = 'Create New',
+    className,
+    dataTestId,
+  } = props;
   const theme = useTheme();
   const titleId = React.useId();
+  const testId = makeTestId(dataTestId);
+
+  const actions = actionsOf(props, refreshLabel, createLabel);
+  // The `action` variant reserves the action row even when nothing fills it.
+  const showActions = variant === 'action' || actions.length > 0;
 
   return (
     <Box
@@ -49,132 +237,27 @@ export const EmptyState: React.FC<EmptyStateProps> = React.memo(({
     >
       {/* Illustration */}
       {illustration && (
-        <Box
-          data-testid={dataTestId ? `${dataTestId}-icon` : 'empty-state-icon'}
-          sx={{
-            maxWidth: variant === 'illustrated' ? 240 : 120,
-            width: '100%',
-            height: 'auto',
-            opacity: variant === 'minimal' ? 0.6 : 0.8,
-            display: variant === 'minimal' ? 'none' : 'block',
-          }}
-        >
-          {illustration}
-        </Box>
+        <Illustration
+          illustration={illustration}
+          variant={variant}
+          testId={testId('icon')}
+        />
       )}
 
       {/* Content */}
-      <Stack spacing={2} alignItems="center">
-        <Typography
-          id={titleId}
-          variant="h6"
-          component="h3"
-          data-testid={dataTestId ? `${dataTestId}-title` : 'empty-state-title'}
-          sx={{
-            fontWeight: theme.typography.fontWeightMedium,
-            color: theme.palette.text.primary,
-            maxWidth: 400,
-          }}
-        >
-          {title}
-        </Typography>
-
-        {description && (
-          <Typography
-            variant="body2"
-            color="text.secondary"
-            data-testid={dataTestId ? `${dataTestId}-description` : 'empty-state-description'}
-            sx={{
-              maxWidth: 480,
-              lineHeight: 1.6,
-            }}
-          >
-            {description}
-          </Typography>
-        )}
-
-        {/* Actions */}
-        {(variant === 'action' || primaryAction || secondaryAction || onCreate || onRefresh) && (
-          <Stack
-            direction={{ xs: 'column', sm: 'row' }}
-            spacing={2}
-            alignItems="center"
-            sx={{ mt: theme.spacing(2) }}
-          >
-            {primaryAction && (
-              <Button
-                variant="contained"
-                onClick={primaryAction.onClick}
-                data-testid={dataTestId ? `${dataTestId}-primary-action` : 'empty-state-primary-action'}
-                sx={{ minWidth: 120 }}
-              >
-                {primaryAction.label}
-              </Button>
-            )}
-
-            {onCreate && (
-              <Button
-                variant="contained"
-                onClick={onCreate}
-                startIcon={<AddIcon />}
-                data-testid={dataTestId ? `${dataTestId}-create-button` : 'empty-state-create-button'}
-                sx={{ minWidth: 120 }}
-              >
-                {createLabel}
-              </Button>
-            )}
-
-            {secondaryAction && (
-              <Button
-                variant="outlined"
-                onClick={secondaryAction.onClick}
-                data-testid={dataTestId ? `${dataTestId}-secondary-action` : 'empty-state-secondary-action'}
-                sx={{ minWidth: 120 }}
-              >
-                {secondaryAction.label}
-              </Button>
-            )}
-
-            {onRefresh && (
-              <Button
-                variant="outlined"
-                onClick={onRefresh}
-                startIcon={<RefreshIcon />}
-                data-testid={dataTestId ? `${dataTestId}-refresh-button` : 'empty-state-refresh-button'}
-                sx={{ minWidth: 120 }}
-              >
-                {refreshLabel}
-              </Button>
-            )}
-
-          </Stack>
-        )}
-
-        {/* Help Link */}
-        {helpLink && (
-          <Link
-            href={helpLink.href}
-            target={helpLink.external ? '_blank' : undefined}
-            rel={helpLink.external ? 'noopener noreferrer' : undefined}
-            data-testid={dataTestId ? `${dataTestId}-help-link` : 'empty-state-help-link'}
-            sx={{
-              mt: theme.spacing(1),
-              color: theme.palette.primary.main,
-              textDecoration: 'none',
-              '&:hover': {
-                textDecoration: 'underline',
-              },
-            }}
-          >
-            {helpLink.label}
-            {helpLink.external && ' ↗'}
-          </Link>
-        )}
-      </Stack>
+      <Content
+        title={title}
+        description={description}
+        titleId={titleId}
+        testId={testId}
+        actions={actions}
+        showActions={showActions}
+        helpLink={helpLink}
+      />
     </Box>
   );
 });
 
 EmptyState.displayName = 'EmptyState';
 
-export default EmptyState;
+export default EmptyState;

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

@@ -1,5 +1,5 @@
 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 { ErrorState } from './ErrorState';
 
@@ -122,7 +122,7 @@ export const KeyboardNavigation: Story = {
     await step('Focus retry button via Tab', async () => {
       await userEvent.tab();
       const retryButton = canvas.getByTestId('error-state-retry-button');
-      await expect(retryButton).toHaveFocus();
+      await waitFor(() => expect(retryButton).toHaveFocus());
     });
 
     await step('Activate button with Enter key', async () => {

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

@@ -2,9 +2,87 @@ import ErrorOutlineIcon from '@mui/icons-material/ErrorOutline';
 import RefreshIcon from '@mui/icons-material/Refresh';
 import WarningAmberIcon from '@mui/icons-material/WarningAmber';
 import { Box, Button, Stack, Typography, useTheme } from '@mui/material';
+import type { Theme } from '@mui/material';
 import React from 'react';
 
-import type { ErrorStateProps } from './ErrorState.types';
+import type { ErrorStateProps, ErrorStateSeverity } from './ErrorState.types';
+
+const makeTestId =
+  (dataTestId?: string) =>
+  (suffix: string): string =>
+    dataTestId ? `${dataTestId}-${suffix}` : `error-state-${suffix}`;
+
+const paletteFor = (theme: Theme, severity: ErrorStateSeverity) =>
+  severity === 'error' ? theme.palette.error : theme.palette.warning;
+
+const ErrorIcon: React.FC<{
+  severity: ErrorStateSeverity;
+  icon?: React.ReactNode;
+  testId: string;
+}> = ({ severity, icon, testId }) => {
+  const theme = useTheme();
+  const color = paletteFor(theme, severity);
+  const Fallback = severity === 'error' ? ErrorOutlineIcon : WarningAmberIcon;
+
+  return (
+    <Box
+      data-testid={testId}
+      sx={{
+        display: 'flex',
+        alignItems: 'center',
+        justifyContent: 'center',
+        width: 80,
+        height: 80,
+        borderRadius: '50%',
+        backgroundColor: color.light,
+        opacity: 0.9,
+      }}
+    >
+      {icon || <Fallback sx={{ fontSize: 48, color: color.main }} />}
+    </Box>
+  );
+};
+
+const ErrorText: React.FC<{
+  title?: string;
+  message: string;
+  titleId: string;
+  testId: (suffix: string) => string;
+}> = ({ title, message, titleId, testId }) => {
+  const theme = useTheme();
+
+  return (
+    <Stack spacing={1} alignItems="center">
+      {title && (
+        <Typography
+          id={titleId}
+          variant="h6"
+          component="h3"
+          data-testid={testId('title')}
+          sx={{
+            fontWeight: theme.typography.fontWeightMedium,
+            color: theme.palette.text.primary,
+          }}
+        >
+          {title}
+        </Typography>
+      )}
+
+      <Typography
+        id={`${titleId}-message`}
+        variant="body2"
+        color="text.secondary"
+        data-testid={testId('message')}
+        sx={{
+          maxWidth: 400,
+          lineHeight: 1.6,
+        }}
+      >
+        {message}
+      </Typography>
+    </Stack>
+  );
+};
 
 export const ErrorState: React.FC<ErrorStateProps> = React.memo(
   ({
@@ -19,15 +97,7 @@ export const ErrorState: React.FC<ErrorStateProps> = React.memo(
   }) => {
     const theme = useTheme();
     const titleId = React.useId();
-
-    const color = severity === 'error' ? theme.palette.error : theme.palette.warning;
-
-    const defaultIcon =
-      severity === 'error' ? (
-        <ErrorOutlineIcon sx={{ fontSize: 48, color: color.main }} />
-      ) : (
-        <WarningAmberIcon sx={{ fontSize: 48, color: color.main }} />
-      );
+    const testId = makeTestId(dataTestId);
 
     return (
       <Box
@@ -47,51 +117,9 @@ export const ErrorState: React.FC<ErrorStateProps> = React.memo(
           gap: theme.spacing(2),
         }}
       >
-        <Box
-          data-testid={dataTestId ? `${dataTestId}-icon` : 'error-state-icon'}
-          sx={{
-            display: 'flex',
-            alignItems: 'center',
-            justifyContent: 'center',
-            width: 80,
-            height: 80,
-            borderRadius: '50%',
-            backgroundColor: color.light,
-            opacity: 0.9,
-          }}
-        >
-          {icon || defaultIcon}
-        </Box>
-
-        <Stack spacing={1} alignItems="center">
-          {title && (
-            <Typography
-              id={titleId}
-              variant="h6"
-              component="h3"
-              data-testid={dataTestId ? `${dataTestId}-title` : 'error-state-title'}
-              sx={{
-                fontWeight: theme.typography.fontWeightMedium,
-                color: theme.palette.text.primary,
-              }}
-            >
-              {title}
-            </Typography>
-          )}
+        <ErrorIcon severity={severity} icon={icon} testId={testId('icon')} />
 
-          <Typography
-            id={`${titleId}-message`}
-            variant="body2"
-            color="text.secondary"
-            data-testid={dataTestId ? `${dataTestId}-message` : 'error-state-message'}
-            sx={{
-              maxWidth: 400,
-              lineHeight: 1.6,
-            }}
-          >
-            {message}
-          </Typography>
-        </Stack>
+        <ErrorText title={title} message={message} titleId={titleId} testId={testId} />
 
         {onRetry && (
           <Button
@@ -99,7 +127,7 @@ export const ErrorState: React.FC<ErrorStateProps> = React.memo(
             color={severity}
             onClick={onRetry}
             startIcon={<RefreshIcon />}
-            data-testid={dataTestId ? `${dataTestId}-retry-button` : 'error-state-retry-button'}
+            data-testid={testId('retry-button')}
             sx={{
               mt: theme.spacing(1),
               minWidth: 120,