@12-apps/ui 1.0.0

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

@@ -0,0 +1,254 @@
+import { ContentCopy as ContentCopyIcon } from '@mui/icons-material';
+import { Box, Stack } from '@mui/material';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { Button } from '../../form/Button/Button';
+import { Chip } from '../Chip/Chip';
+import { DescriptionItem } from './DescriptionItem';
+
+const meta: Meta<typeof DescriptionItem> = {
+  title: 'DataDisplay/DescriptionItem',
+  component: DescriptionItem,
+  parameters: {
+    layout: 'centered',
+  },
+  tags: ['autodocs', 'component:DescriptionItem'],
+  argTypes: {
+    label: {
+      control: 'text',
+      description: 'The label text to display',
+    },
+    value: {
+      control: 'text',
+      description: 'The value to display - can be text, number, or any React node',
+    },
+    orientation: {
+      control: 'radio',
+      options: ['vertical', 'horizontal'],
+      description: 'Layout orientation',
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: {
+    label: 'Incident ID',
+    value: 'INC-12345',
+  },
+};
+
+export const WithNumber: Story = {
+  args: {
+    label: 'Services Affected',
+    value: 42,
+  },
+};
+
+export const WithLongText: Story = {
+  args: {
+    label: 'Description',
+    value: 'This is a longer description that demonstrates how the component handles multiple lines of text content.',
+  },
+};
+
+export const WithCustomContent: Story = {
+  render: () => (
+    <DescriptionItem
+      label="Status"
+      value={<Chip label="Active" color="success" size="small" />}
+    />
+  ),
+};
+
+export const HorizontalOrientation: Story = {
+  render: () => (
+    <Stack spacing={2} sx={{ width: 400 }}>
+      <DescriptionItem label="Name" value="John Doe" orientation="horizontal" />
+      <DescriptionItem label="Email" value="john.doe@example.com" orientation="horizontal" />
+      <DescriptionItem label="Status" value={<Chip label="Active" color="success" size="small" />} orientation="horizontal" />
+      <DescriptionItem label="Role" value="Administrator" orientation="horizontal" />
+    </Stack>
+  ),
+};
+
+export const VerticalOrientation: Story = {
+  render: () => (
+    <Stack spacing={3} sx={{ width: 300 }}>
+      <DescriptionItem label="Name" value="John Doe" orientation="vertical" />
+      <DescriptionItem label="Email" value="john.doe@example.com" orientation="vertical" />
+      <DescriptionItem label="Status" value={<Chip label="Active" color="success" size="small" />} orientation="vertical" />
+      <DescriptionItem label="Role" value="Administrator" orientation="vertical" />
+    </Stack>
+  ),
+};
+
+export const WithCopyableValue: Story = {
+  render: () => (
+    <DescriptionItem
+      label="Incident ID"
+      value={
+        <Box sx={{ display: 'flex', alignItems: 'center', gap: 0.5 }}>
+          <span style={{ fontWeight: 600, fontSize: '0.875rem' }}>INC-12345</span>
+          <Button
+            variant="ghost"
+            size="sm"
+            onClick={() => navigator.clipboard.writeText('INC-12345')}
+            sx={{ minWidth: 'auto', padding: 0.25 }}
+            aria-label="Copy incident ID"
+          >
+            <ContentCopyIcon sx={{ fontSize: 16 }} />
+          </Button>
+        </Box>
+      }
+    />
+  ),
+};
+
+export const GridLayout: Story = {
+  render: () => (
+    <Box
+      sx={{
+        display: 'grid',
+        gridTemplateColumns: 'repeat(4, 1fr)',
+        gap: 3,
+        width: 800,
+      }}
+    >
+      <DescriptionItem label="Incident ID" value="INC-12345" />
+      <DescriptionItem label="Started" value="2 hours ago" />
+      <DescriptionItem label="Duration" value="Ongoing" />
+      <DescriptionItem label="Services Affected" value={5} />
+    </Box>
+  ),
+};
+
+export const VerticalStack: Story = {
+  render: () => (
+    <Stack spacing={3} sx={{ width: 300 }}>
+      <DescriptionItem label="Name" value="John Doe" />
+      <DescriptionItem label="Email" value="john.doe@example.com" />
+      <DescriptionItem label="Department" value="Engineering" />
+      <DescriptionItem
+        label="Role"
+        value={<Chip label="Admin" color="primary" size="small" />}
+      />
+    </Stack>
+  ),
+};
+
+export const ResponsiveGrid: Story = {
+  render: () => (
+    <Box
+      sx={{
+        display: 'grid',
+        gridTemplateColumns: { xs: '1fr', sm: 'repeat(2, 1fr)', md: 'repeat(4, 1fr)' },
+        gap: 3,
+        maxWidth: 900,
+      }}
+    >
+      <DescriptionItem label="Order ID" value="ORD-2024-001" />
+      <DescriptionItem label="Customer" value="Acme Corp" />
+      <DescriptionItem label="Total Amount" value="$1,234.56" />
+      <DescriptionItem label="Status" value={<Chip label="Completed" color="success" size="small" />} />
+      <DescriptionItem label="Order Date" value="Jan 15, 2024" />
+      <DescriptionItem label="Shipping Method" value="Express" />
+      <DescriptionItem label="Items" value={3} />
+      <DescriptionItem label="Payment Method" value="Credit Card" />
+    </Box>
+  ),
+};
+
+export const WithEmptyValue: Story = {
+  render: () => (
+    <Stack spacing={3} sx={{ width: 300 }}>
+      <DescriptionItem label="Optional Field" value="N/A" />
+      <DescriptionItem label="No Value" value="-" />
+      <DescriptionItem label="Empty" value="" />
+    </Stack>
+  ),
+};
+
+export const MixedOrientations: Story = {
+  render: () => (
+    <Box sx={{ width: 600 }}>
+      <Stack spacing={3}>
+        <Box>
+          <h3>Vertical Layout (Default)</h3>
+          <Box sx={{ display: 'grid', gridTemplateColumns: 'repeat(3, 1fr)', gap: 3, mt: 2 }}>
+            <DescriptionItem label="Name" value="John Doe" />
+            <DescriptionItem label="Age" value={32} />
+            <DescriptionItem label="City" value="San Francisco" />
+          </Box>
+        </Box>
+
+        <Box>
+          <h3>Horizontal Layout</h3>
+          <Stack spacing={2} sx={{ mt: 2 }}>
+            <DescriptionItem label="Name" value="John Doe" orientation="horizontal" />
+            <DescriptionItem label="Age" value={32} orientation="horizontal" />
+            <DescriptionItem label="City" value="San Francisco" orientation="horizontal" />
+          </Stack>
+        </Box>
+      </Stack>
+    </Box>
+  ),
+};
+
+export const AllVariations: Story = {
+  render: () => (
+    <Stack spacing={4} sx={{ width: 800 }}>
+      <Box>
+        <h3>Text Values (Vertical)</h3>
+        <Box sx={{ display: 'grid', gridTemplateColumns: 'repeat(3, 1fr)', gap: 3, mt: 2 }}>
+          <DescriptionItem label="Short Text" value="Value" />
+          <DescriptionItem label="Medium Text" value="This is a medium length value" />
+          <DescriptionItem label="Long Text" value="This is a much longer text value that will wrap to multiple lines" />
+        </Box>
+      </Box>
+
+      <Box>
+        <h3>Text Values (Horizontal)</h3>
+        <Stack spacing={2} sx={{ mt: 2 }}>
+          <DescriptionItem label="Short Text" value="Value" orientation="horizontal" />
+          <DescriptionItem label="Medium Text" value="This is a medium length value" orientation="horizontal" />
+          <DescriptionItem label="Long Text" value="This is a much longer text value that will wrap to multiple lines" orientation="horizontal" />
+        </Stack>
+      </Box>
+
+      <Box>
+        <h3>Number Values</h3>
+        <Box sx={{ display: 'grid', gridTemplateColumns: 'repeat(3, 1fr)', gap: 3, mt: 2 }}>
+          <DescriptionItem label="Integer" value={42} />
+          <DescriptionItem label="Decimal" value={3.14159} />
+          <DescriptionItem label="Large Number" value={1234567890} />
+        </Box>
+      </Box>
+
+      <Box>
+        <h3>Custom Components</h3>
+        <Box sx={{ display: 'grid', gridTemplateColumns: 'repeat(3, 1fr)', gap: 3, mt: 2 }}>
+          <DescriptionItem
+            label="With Chip"
+            value={<Chip label="Active" color="success" size="small" />}
+          />
+          <DescriptionItem
+            label="With Button"
+            value={<Button size="xs" variant="outline">Action</Button>}
+          />
+          <DescriptionItem
+            label="Multiple Elements"
+            value={
+              <Box sx={{ display: 'flex', gap: 0.5 }}>
+                <Chip label="Tag 1" size="small" />
+                <Chip label="Tag 2" size="small" />
+              </Box>
+            }
+          />
+        </Box>
+      </Box>
+    </Stack>
+  ),
+};

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

@@ -0,0 +1,100 @@
+import { Box } from '@mui/material';
+import type { ReactNode } from 'react';
+
+import { Text } from '../../typography/Text/Text';
+
+export interface DescriptionItemProps {
+  /**
+   * The label text to display
+   */
+  label: string;
+
+  /**
+   * The value to display - can be text, number, or any React node
+   */
+  value: ReactNode;
+
+  /**
+   * Layout orientation
+   * - `vertical`: Label above value (default)
+   * - `horizontal`: Label and value side by side
+   */
+  orientation?: 'vertical' | 'horizontal';
+
+  /**
+   * Optional CSS class name
+   */
+  className?: string;
+
+  /**
+   * Test ID for testing purposes
+   */
+  'data-testid'?: string;
+}
+
+/**
+ * DescriptionItem - A label-value pair component for displaying read-only information
+ *
+ * Used for displaying structured metadata, properties, or descriptive information
+ * in a consistent vertical layout with a label above the value.
+ *
+ * @example
+ * ```tsx
+ * <DescriptionItem
+ *   label="Incident ID"
+ *   value="INC-12345"
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * <DescriptionItem
+ *   label="Status"
+ *   value={<Chip label="Active" color="success" />}
+ * />
+ * ```
+ */
+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'}
+    >
+      {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
+      )}
+    </Box>
+  </Box>
+);
+
+DescriptionItem.displayName = 'DescriptionItem';

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

@@ -0,0 +1 @@
+export type { DescriptionItemProps } from './DescriptionItem';

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

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

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

@@ -0,0 +1,265 @@
+# EmptyState Component
+
+**Purpose:** Friendly placeholder for "no data / no results / error" with illustration and actions.
+
+```ts
+interface EmptyStateProps {
+  variant?: 'default' | 'illustrated' | 'minimal' | 'action';
+  title: string;
+  description?: string;
+  illustration?: React.ReactNode; // SVG/Lottie/etc
+  primaryAction?: { label: string; onClick: () => void };
+  secondaryAction?: { label: string; onClick: () => void };
+  helpLink?: { label: string; href: string; external?: boolean };
+  className?: string;
+  dataTestId?: string;
+}
+```
+
+**Features**
+
+- Clear title + optional description and help link.
+- Optional illustration area sized responsively.
+- Action variant surfaces primary/secondary CTAs.
+
+**A11y**
+
+- Wrap in `role="region"` with `aria-labelledby` to the title id.
+- Provide `alt` text for non-decorative illustrations.
+
+**Stories / Tests**
+
+- No Results; No Permissions; Network Error; With Actions; Illustrated vs Minimal.
+
+## Testing
+
+### Test IDs
+
+All test IDs follow a hierarchical pattern. If `dataTestId` prop is provided, it becomes the prefix for all child test IDs. Otherwise, default IDs are used.
+
+| Element | Default Test ID | With Custom dataTestId |
+|---------|----------------|----------------------|
+| Container | `empty-state` | `{dataTestId}` |
+| Icon/Illustration | `empty-state-icon` | `{dataTestId}-icon` |
+| Title | `empty-state-title` | `{dataTestId}-title` |
+| Description | `empty-state-description` | `{dataTestId}-description` |
+| Primary Action Button | `empty-state-primary-action` | `{dataTestId}-primary-action` |
+| Secondary Action Button | `empty-state-secondary-action` | `{dataTestId}-secondary-action` |
+| Help Link | `empty-state-help-link` | `{dataTestId}-help-link` |
+
+### Testing Best Practices
+
+#### 1. **Structural Testing**
+```typescript
+// Verify component renders with required elements
+const container = screen.getByTestId('empty-state');
+expect(container).toBeInTheDocument();
+
+const title = screen.getByTestId('empty-state-title');
+expect(title).toHaveTextContent('No Results Found');
+```
+
+#### 2. **Conditional Rendering**
+```typescript
+// Test with description
+const description = screen.queryByTestId('empty-state-description');
+expect(description).toBeInTheDocument();
+
+// Test without description
+const noDescription = screen.queryByTestId('empty-state-description');
+expect(noDescription).not.toBeInTheDocument();
+```
+
+#### 3. **Action Button Testing**
+```typescript
+const primaryButton = screen.getByTestId('empty-state-primary-action');
+await userEvent.click(primaryButton);
+expect(mockOnClick).toHaveBeenCalledTimes(1);
+```
+
+#### 4. **Custom Test IDs**
+```typescript
+// Use custom dataTestId for multiple instances
+<EmptyState
+  dataTestId="search-empty"
+  title="No Results"
+/>
+
+const searchEmpty = screen.getByTestId('search-empty');
+const searchTitle = screen.getByTestId('search-empty-title');
+```
+
+### Common Test Scenarios
+
+#### Scenario 1: No Results State
+```typescript
+it('should display no results state with illustration', () => {
+  render(
+    <EmptyState
+      variant="illustrated"
+      title="No Results Found"
+      description="Try adjusting your search criteria"
+      illustration={<SearchIcon />}
+      dataTestId="no-results"
+    />
+  );
+
+  expect(screen.getByTestId('no-results-title')).toHaveTextContent('No Results Found');
+  expect(screen.getByTestId('no-results-description')).toHaveTextContent('Try adjusting your search criteria');
+  expect(screen.getByTestId('no-results-icon')).toBeInTheDocument();
+});
+```
+
+#### Scenario 2: Error State with Action
+```typescript
+it('should display error state with retry action', async () => {
+  const handleRetry = vi.fn();
+
+  render(
+    <EmptyState
+      title="Something went wrong"
+      description="We couldn't load your data"
+      primaryAction={{ label: 'Retry', onClick: handleRetry }}
+      dataTestId="error-state"
+    />
+  );
+
+  const retryButton = screen.getByTestId('error-state-primary-action');
+  expect(retryButton).toHaveTextContent('Retry');
+
+  await userEvent.click(retryButton);
+  expect(handleRetry).toHaveBeenCalledTimes(1);
+});
+```
+
+#### Scenario 3: Permission Denied with Help Link
+```typescript
+it('should display permission denied with help link', () => {
+  render(
+    <EmptyState
+      title="Access Denied"
+      description="You don't have permission to view this content"
+      helpLink={{
+        label: 'Request Access',
+        href: '/request-access',
+        external: false
+      }}
+      dataTestId="access-denied"
+    />
+  );
+
+  const helpLink = screen.getByTestId('access-denied-help-link');
+  expect(helpLink).toHaveAttribute('href', '/request-access');
+  expect(helpLink).not.toHaveAttribute('target', '_blank');
+});
+```
+
+#### Scenario 4: Empty State with Multiple Actions
+```typescript
+it('should display both primary and secondary actions', async () => {
+  const handleCreate = vi.fn();
+  const handleImport = vi.fn();
+
+  render(
+    <EmptyState
+      variant="action"
+      title="No Items Yet"
+      description="Get started by creating or importing items"
+      primaryAction={{ label: 'Create New', onClick: handleCreate }}
+      secondaryAction={{ label: 'Import', onClick: handleImport }}
+      dataTestId="no-items"
+    />
+  );
+
+  const createButton = screen.getByTestId('no-items-primary-action');
+  const importButton = screen.getByTestId('no-items-secondary-action');
+
+  await userEvent.click(createButton);
+  expect(handleCreate).toHaveBeenCalledTimes(1);
+
+  await userEvent.click(importButton);
+  expect(handleImport).toHaveBeenCalledTimes(1);
+});
+```
+
+#### Scenario 5: External Help Link
+```typescript
+it('should open external help link in new tab', () => {
+  render(
+    <EmptyState
+      title="Need Help?"
+      helpLink={{
+        label: 'View Documentation',
+        href: 'https://docs.example.com',
+        external: true
+      }}
+      dataTestId="help-state"
+    />
+  );
+
+  const link = screen.getByTestId('help-state-help-link');
+  expect(link).toHaveAttribute('href', 'https://docs.example.com');
+  expect(link).toHaveAttribute('target', '_blank');
+  expect(link).toHaveAttribute('rel', 'noopener noreferrer');
+  expect(link).toHaveTextContent('View Documentation ↗');
+});
+```
+
+#### Scenario 6: Minimal Variant (No Icon)
+```typescript
+it('should not display icon in minimal variant', () => {
+  render(
+    <EmptyState
+      variant="minimal"
+      title="Nothing Here"
+      illustration={<Icon />}
+      dataTestId="minimal-state"
+    />
+  );
+
+  const icon = screen.queryByTestId('minimal-state-icon');
+  expect(icon).toHaveStyle({ display: 'none' });
+});
+```
+
+### Accessibility Testing
+
+#### 1. **Semantic Structure**
+```typescript
+it('should have proper ARIA attributes', () => {
+  render(<EmptyState title="No Data" dataTestId="a11y-test" />);
+
+  const container = screen.getByTestId('a11y-test');
+  expect(container).toHaveAttribute('role', 'region');
+  expect(container).toHaveAttribute('aria-labelledby');
+});
+```
+
+#### 2. **Keyboard Navigation**
+```typescript
+it('should support keyboard navigation for actions', async () => {
+  const handleAction = vi.fn();
+
+  render(
+    <EmptyState
+      title="Empty"
+      primaryAction={{ label: 'Action', onClick: handleAction }}
+      dataTestId="keyboard-test"
+    />
+  );
+
+  const button = screen.getByTestId('keyboard-test-primary-action');
+  button.focus();
+
+  await userEvent.keyboard('{Enter}');
+  expect(handleAction).toHaveBeenCalledTimes(1);
+});
+```
+
+### Integration Testing Tips
+
+1. **Multiple Instances**: Use unique `dataTestId` props when rendering multiple EmptyState components
+2. **Conditional Rendering**: Always use `queryByTestId` for elements that may not be present
+3. **User Interactions**: Use `@testing-library/user-event` for realistic user interactions
+4. **Async Actions**: Properly await user events and action callbacks
+5. **Snapshot Testing**: Consider snapshots for different variants to catch unintended visual changes