@12-apps/ui 1.0.0

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

@@ -0,0 +1,270 @@
+import { Typography } from '@mui/material';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { expect, fn, userEvent, within } from 'storybook/test';
+
+import { EmptyState } from '../EmptyState/EmptyState';
+
+import { AsyncStateContainer } from './AsyncStateContainer';
+import { ErrorState } from '../ErrorState/ErrorState';
+import { LoadingState } from '../LoadingState/LoadingState';
+
+const meta: Meta<typeof AsyncStateContainer> = {
+  title: 'DataDisplay/AsyncStates/AsyncStateContainer/Tests',
+  component: AsyncStateContainer,
+  parameters: {
+    layout: 'padded',
+    chromatic: { disableSnapshot: false },
+  },
+  tags: ['autodocs', 'test', 'component:AsyncStateContainer'],
+};
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const TestContent = () => (
+  <Typography data-testid="success-content">Content Loaded</Typography>
+);
+
+export const SuccessStateTest: Story = {
+  name: '🧪 Success State Rendering',
+  args: {
+    isLoading: false,
+    error: null,
+    isEmpty: false,
+    children: <TestContent />,
+  },
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+
+    await step('Verify container has success state', async () => {
+      const container = canvas.getByTestId('async-state-container');
+      await expect(container).toHaveAttribute('data-state', 'success');
+    });
+
+    await step('Verify children content is rendered', async () => {
+      const content = canvas.getByTestId('success-content');
+      await expect(content).toHaveTextContent('Content Loaded');
+    });
+  },
+};
+
+export const LoadingStateTest: Story = {
+  name: '🧪 Loading State Rendering',
+  args: {
+    isLoading: true,
+    error: null,
+    isEmpty: false,
+    children: <TestContent />,
+  },
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+
+    await step('Verify container has loading state', async () => {
+      const container = canvas.getByTestId('async-state-container');
+      await expect(container).toHaveAttribute('data-state', 'loading');
+    });
+
+    await step('Verify children content is NOT rendered', async () => {
+      const content = canvas.queryByTestId('success-content');
+      await expect(content).not.toBeInTheDocument();
+    });
+
+    await step('Verify loading component is rendered', async () => {
+      const loading = canvas.getByTestId('loading-state');
+      await expect(loading).toBeInTheDocument();
+    });
+  },
+};
+
+export const ErrorStateTest: Story = {
+  name: '🧪 Error State Rendering',
+  args: {
+    isLoading: false,
+    error: 'Something went wrong',
+    isEmpty: false,
+    children: <TestContent />,
+  },
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+
+    await step('Verify container has error state', async () => {
+      const container = canvas.getByTestId('async-state-container');
+      await expect(container).toHaveAttribute('data-state', 'error');
+    });
+
+    await step('Verify children content is NOT rendered', async () => {
+      const content = canvas.queryByTestId('success-content');
+      await expect(content).not.toBeInTheDocument();
+    });
+
+    await step('Verify error component is rendered', async () => {
+      const error = canvas.getByTestId('error-state');
+      await expect(error).toBeInTheDocument();
+    });
+
+    await step('Verify error message is displayed', async () => {
+      const message = canvas.getByTestId('error-state-message');
+      await expect(message).toHaveTextContent('Something went wrong');
+    });
+  },
+};
+
+export const EmptyStateTest: Story = {
+  name: '🧪 Empty State Rendering',
+  args: {
+    isLoading: false,
+    error: null,
+    isEmpty: true,
+    children: <TestContent />,
+  },
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+
+    await step('Verify container has empty state', async () => {
+      const container = canvas.getByTestId('async-state-container');
+      await expect(container).toHaveAttribute('data-state', 'empty');
+    });
+
+    await step('Verify children content is NOT rendered', async () => {
+      const content = canvas.queryByTestId('success-content');
+      await expect(content).not.toBeInTheDocument();
+    });
+
+    await step('Verify empty state component is rendered', async () => {
+      const empty = canvas.getByTestId('empty-state');
+      await expect(empty).toBeInTheDocument();
+    });
+  },
+};
+
+export const PriorityTest: Story = {
+  name: '🧪 Priority: Loading > Error > Empty',
+  args: {
+    isLoading: true,
+    error: 'This should not show',
+    isEmpty: true,
+    children: <TestContent />,
+  },
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+
+    await step('Verify loading state takes priority', async () => {
+      const container = canvas.getByTestId('async-state-container');
+      await expect(container).toHaveAttribute('data-state', 'loading');
+    });
+
+    await step('Verify loading component is rendered, not error', async () => {
+      const loading = canvas.getByTestId('loading-state');
+      await expect(loading).toBeInTheDocument();
+
+      const error = canvas.queryByTestId('error-state');
+      await expect(error).not.toBeInTheDocument();
+    });
+  },
+};
+
+export const CustomComponentsTest: Story = {
+  name: '🧪 Custom Components via Props',
+  args: {
+    isLoading: false,
+    error: null,
+    isEmpty: true,
+    emptyComponent: (
+      <EmptyState
+        title="No items found"
+        description="Create your first item"
+        onCreate={fn()}
+        dataTestId="custom-empty"
+      />
+    ),
+    children: <TestContent />,
+  },
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+
+    await step('Verify custom empty component is used', async () => {
+      const customEmpty = canvas.getByTestId('custom-empty');
+      await expect(customEmpty).toBeInTheDocument();
+    });
+
+    await step('Verify custom empty title', async () => {
+      const title = canvas.getByTestId('custom-empty-title');
+      await expect(title).toHaveTextContent('No items found');
+    });
+  },
+};
+
+export const CustomLoadingWithRetry: Story = {
+  name: '🧪 Error State with Retry Interaction',
+  args: {
+    isLoading: false,
+    error: 'Network error',
+    isEmpty: false,
+    errorComponent: (
+      <ErrorState
+        title="Connection Failed"
+        message="Network error"
+        onRetry={fn()}
+        dataTestId="custom-error"
+      />
+    ),
+    children: <TestContent />,
+  },
+  play: async ({ canvasElement, _args, step }) => {
+    const canvas = within(canvasElement);
+
+    await step('Verify custom error component', async () => {
+      const customError = canvas.getByTestId('custom-error');
+      await expect(customError).toBeInTheDocument();
+    });
+
+    await step('Click retry button', async () => {
+      const retryButton = canvas.getByTestId('custom-error-retry-button');
+      await userEvent.click(retryButton);
+    });
+  },
+};
+
+export const RenderPropsTest: Story = {
+  name: '🧪 Render Props Pattern',
+  args: {
+    isLoading: true,
+    error: null,
+    isEmpty: false,
+    renderLoading: () => (
+      <LoadingState variant="skeleton" message="Custom render prop" dataTestId="render-prop-loading" />
+    ),
+    children: <TestContent />,
+  },
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+
+    await step('Verify render prop loading is used', async () => {
+      const loading = canvas.getByTestId('render-prop-loading');
+      await expect(loading).toBeInTheDocument();
+    });
+
+    await step('Verify custom message', async () => {
+      const message = canvas.getByTestId('render-prop-loading-message');
+      await expect(message).toHaveTextContent('Custom render prop');
+    });
+  },
+};
+
+export const ErrorObjectTest: Story = {
+  name: '🧪 Error Object Handling',
+  args: {
+    isLoading: false,
+    error: new Error('TypeError: Cannot read property'),
+    isEmpty: false,
+    children: <TestContent />,
+  },
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+
+    await step('Verify error message from Error object', async () => {
+      const message = canvas.getByTestId('error-state-message');
+      await expect(message).toHaveTextContent('TypeError: Cannot read property');
+    });
+  },
+};

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

@@ -0,0 +1,116 @@
+import { Box } from '@mui/material';
+import React from 'react';
+
+import { EmptyState } from '../EmptyState/EmptyState';
+import { ErrorState } from '../ErrorState/ErrorState';
+import { LoadingState } from '../LoadingState/LoadingState';
+
+import type { AsyncStateContainerProps } from './AsyncStateContainer.types';
+
+/**
+ * AsyncStateContainer - A composition-based wrapper for handling async data states
+ *
+ * Priority order: loading > error > empty > children
+ *
+ * @example
+ * // With component props (composition pattern)
+ * <AsyncStateContainer
+ *   isLoading={isLoading}
+ *   error={error}
+ *   isEmpty={data.length === 0}
+ *   loadingComponent={<LoadingState variant="skeleton" />}
+ *   errorComponent={<ErrorState message={error} onRetry={refetch} />}
+ *   emptyComponent={<EmptyState title="No items" onCreate={handleCreate} />}
+ * >
+ *   <DataGrid data={data} />
+ * </AsyncStateContainer>
+ *
+ * @example
+ * // With render props for more control
+ * <AsyncStateContainer
+ *   isLoading={isLoading}
+ *   error={error}
+ *   isEmpty={data.length === 0}
+ *   renderLoading={() => <CustomLoader />}
+ *   renderError={(error) => <CustomError error={error} />}
+ *   renderEmpty={() => <CustomEmpty />}
+ * >
+ *   <DataGrid data={data} />
+ * </AsyncStateContainer>
+ */
+export const AsyncStateContainer: React.FC<AsyncStateContainerProps> = React.memo(
+  ({
+    isLoading = false,
+    error,
+    isEmpty = false,
+    children,
+    loadingComponent,
+    renderLoading,
+    errorComponent,
+    renderError,
+    emptyComponent,
+    renderEmpty,
+    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';
+    };
+
+    // Priority: loading > error > empty > children
+    if (isLoading) {
+      return (
+        <Box
+          className={className}
+          data-testid={dataTestId || 'async-state-container'}
+          data-state="loading"
+        >
+          {loadingComponent || renderLoading?.() || <LoadingState />}
+        </Box>
+      );
+    }
+
+    if (error) {
+      const errorMessage = getErrorMessage();
+      return (
+        <Box
+          className={className}
+          data-testid={dataTestId || 'async-state-container'}
+          data-state="error"
+        >
+          {errorComponent || renderError?.(errorMessage) || <ErrorState message={errorMessage} />}
+        </Box>
+      );
+    }
+
+    if (isEmpty) {
+      return (
+        <Box
+          className={className}
+          data-testid={dataTestId || 'async-state-container'}
+          data-state="empty"
+        >
+          {emptyComponent || renderEmpty?.() || <EmptyState title="No data available" />}
+        </Box>
+      );
+    }
+
+    return (
+      <Box
+        className={className}
+        data-testid={dataTestId || 'async-state-container'}
+        data-state="success"
+      >
+        {children}
+      </Box>
+    );
+  },
+);
+
+AsyncStateContainer.displayName = 'AsyncStateContainer';
+
+export default AsyncStateContainer;

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

@@ -0,0 +1,70 @@
+import type React from 'react';
+
+export interface AsyncStateContainerProps {
+  /**
+   * Whether the container is in a loading state
+   * @default false
+   */
+  isLoading?: boolean;
+
+  /**
+   * Error message or object. When truthy, shows the error state.
+   */
+  error?: string | Error | null;
+
+  /**
+   * Whether the data is empty (shows empty state when true and not loading/error)
+   * @default false
+   */
+  isEmpty?: boolean;
+
+  /**
+   * The content to render when data is available
+   */
+  children: React.ReactNode;
+
+  /**
+   * Component to render during loading state
+   * Takes precedence over renderLoading
+   */
+  loadingComponent?: React.ReactNode;
+
+  /**
+   * Render function for loading state
+   * Called when loadingComponent is not provided
+   */
+  renderLoading?: () => React.ReactNode;
+
+  /**
+   * Component to render during error state
+   * Takes precedence over renderError
+   */
+  errorComponent?: React.ReactNode;
+
+  /**
+   * Render function for error state
+   * Receives the error message as parameter
+   */
+  renderError?: (error: string) => React.ReactNode;
+
+  /**
+   * Component to render during empty state
+   * Takes precedence over renderEmpty
+   */
+  emptyComponent?: React.ReactNode;
+
+  /**
+   * Render function for empty state
+   */
+  renderEmpty?: () => React.ReactNode;
+
+  /**
+   * Custom className for the container
+   */
+  className?: string;
+
+  /**
+   * Test ID for component testing
+   */
+  dataTestId?: string;
+}

package/src/components/data-display/AsyncStateContainer/index.ts

@@ -0,0 +1,2 @@
+export { AsyncStateContainer } from './AsyncStateContainer';
+export type { AsyncStateContainerProps } from './AsyncStateContainer.types';