@12-apps/ui 1.0.0

package/src/components/typography/Paragraph/Paragraph.test.stories.tsx

@@ -0,0 +1,238 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { expect,within } from 'storybook/test';
+
+import { Paragraph } from './Paragraph';
+
+const meta: Meta<typeof Paragraph> = {
+  title: 'Typography/Paragraph/Tests',
+  component: Paragraph,
+  parameters: { layout: 'centered', chromatic: { disableSnapshot: false } },
+  tags: ['autodocs', 'test', 'component:Paragraph'],
+};
+export default meta;
+export type Story = StoryObj<typeof meta>;
+
+const sampleText = 'This is a sample paragraph text for testing purposes.';
+
+export const BasicInteraction: Story = {
+  args: {
+    children: sampleText,
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+
+    const paragraph = canvas.getByText(sampleText);
+    expect(paragraph).toBeInTheDocument();
+    expect(paragraph.tagName).toBe('P');
+  },
+};
+
+export const KeyboardNavigation: Story = {
+  args: {
+    children: sampleText,
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+
+    const paragraph = canvas.getByText(sampleText);
+
+    // Paragraph should not be focusable by default
+    paragraph.focus();
+    expect(paragraph).not.toHaveFocus();
+  },
+};
+
+export const ScreenReader: Story = {
+  args: {
+    children: sampleText,
+    'aria-label': 'Sample paragraph',
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+
+    const paragraph = canvas.getByText(sampleText);
+    expect(paragraph).toHaveAttribute('aria-label', 'Sample paragraph');
+    expect(paragraph).toBeInTheDocument();
+  },
+};
+
+export const FocusManagement: Story = {
+  args: {
+    children: sampleText,
+    tabIndex: 0,
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+
+    const paragraph = canvas.getByText(sampleText);
+
+    // When tabIndex is set, paragraph should be focusable
+    paragraph.focus();
+    expect(paragraph).toHaveFocus();
+  },
+};
+
+export const ResponsiveDesign: Story = {
+  args: {
+    children: sampleText,
+    size: 'md',
+  },
+  parameters: {
+    viewport: {
+      viewports: {
+        mobile: { name: 'Mobile', styles: { width: '375px', height: '667px' } },
+        tablet: { name: 'Tablet', styles: { width: '768px', height: '1024px' } },
+        desktop: { name: 'Desktop', styles: { width: '1024px', height: '768px' } },
+      },
+    },
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+
+    const paragraph = canvas.getByText(sampleText);
+    expect(paragraph).toBeInTheDocument();
+
+    // Test that paragraph renders properly at different screen sizes
+    const computedStyle = window.getComputedStyle(paragraph);
+    expect(computedStyle.fontSize).toBeTruthy();
+  },
+};
+
+export const ThemeVariations: Story = {
+  args: {
+    children: sampleText,
+    color: 'primary',
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+
+    const paragraph = canvas.getByText(sampleText);
+    expect(paragraph).toBeInTheDocument();
+
+    // Test that paragraph has the correct color styling
+    const computedStyle = window.getComputedStyle(paragraph);
+    expect(computedStyle.color).toBeTruthy();
+  },
+};
+
+export const VisualStates: Story = {
+  render: () => (
+    <div>
+      <Paragraph variant="default">{sampleText} - Default</Paragraph>
+      <Paragraph variant="lead">{sampleText} - Lead</Paragraph>
+      <Paragraph variant="small">{sampleText} - Small</Paragraph>
+      <Paragraph variant="muted">{sampleText} - Muted</Paragraph>
+    </div>
+  ),
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+
+    const defaultParagraph = canvas.getByText(`${sampleText} - Default`);
+    const leadParagraph = canvas.getByText(`${sampleText} - Lead`);
+    const smallParagraph = canvas.getByText(`${sampleText} - Small`);
+    const mutedParagraph = canvas.getByText(`${sampleText} - Muted`);
+
+    expect(defaultParagraph).toBeInTheDocument();
+    expect(leadParagraph).toBeInTheDocument();
+    expect(smallParagraph).toBeInTheDocument();
+    expect(mutedParagraph).toBeInTheDocument();
+
+    // Test that different variants have different styling
+    const defaultStyle = window.getComputedStyle(defaultParagraph);
+    const leadStyle = window.getComputedStyle(leadParagraph);
+
+    expect(defaultStyle.fontSize).not.toBe(leadStyle.fontSize);
+  },
+};
+
+export const Performance: Story = {
+  args: {
+    children: sampleText,
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+
+    const startTime = Date.now();
+
+    const paragraph = canvas.getByText(sampleText);
+    expect(paragraph).toBeInTheDocument();
+
+    const endTime = Date.now();
+    const renderTime = endTime - startTime;
+
+    // Paragraph should render quickly (under 100ms)
+    expect(renderTime).toBeLessThan(100);
+  },
+};
+
+export const EdgeCases: Story = {
+  render: () => (
+    <div>
+      <Paragraph>{''}</Paragraph>
+      <Paragraph>
+        {
+          'Very long text that should wrap properly and maintain readability even when it extends beyond the normal width of the container and continues for multiple lines to test text wrapping behavior.'
+        }
+      </Paragraph>
+      <Paragraph>{'Special chars: !@#$%^&*()_+-=[]{}|;":,./<>?'}</Paragraph>
+      <Paragraph>{'Numbers: 123456789'}</Paragraph>
+    </div>
+  ),
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+
+    // Test empty content
+    const paragraphs = canvas.getAllByRole('generic', { hidden: true }) || [];
+    expect(paragraphs.length).toBeGreaterThanOrEqual(1);
+
+    // Test special characters
+    const specialCharsText = canvas.getByText(/Special chars:/);
+    expect(specialCharsText).toBeInTheDocument();
+
+    // Test numbers
+    const numbersText = canvas.getByText(/Numbers:/);
+    expect(numbersText).toBeInTheDocument();
+  },
+};
+
+export const Integration: Story = {
+  render: () => (
+    <div>
+      <h3>Article with Multiple Paragraphs</h3>
+      <Paragraph variant="lead" color="primary">
+        This is a lead paragraph that introduces the content.
+      </Paragraph>
+      <Paragraph>This is a regular paragraph that provides the main content.</Paragraph>
+      <Paragraph variant="small" color="secondary">
+        This is a small paragraph with additional information.
+      </Paragraph>
+      <Paragraph variant="muted">This is a muted paragraph for supplementary content.</Paragraph>
+    </div>
+  ),
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+
+    const heading = canvas.getByText('Article with Multiple Paragraphs');
+    const leadParagraph = canvas.getByText('This is a lead paragraph that introduces the content.');
+    const regularParagraph = canvas.getByText(
+      'This is a regular paragraph that provides the main content.',
+    );
+    const smallParagraph = canvas.getByText(
+      'This is a small paragraph with additional information.',
+    );
+    const mutedParagraph = canvas.getByText('This is a muted paragraph for supplementary content.');
+
+    expect(heading).toBeInTheDocument();
+    expect(leadParagraph).toBeInTheDocument();
+    expect(regularParagraph).toBeInTheDocument();
+    expect(smallParagraph).toBeInTheDocument();
+    expect(mutedParagraph).toBeInTheDocument();
+
+    // Test that all paragraphs render with proper spacing
+    const allParagraphs = [leadParagraph, regularParagraph, smallParagraph, mutedParagraph];
+    allParagraphs.forEach((p) => {
+      const computedStyle = window.getComputedStyle(p);
+      expect(computedStyle.marginBottom).toBeTruthy();
+    });
+  },
+};

package/src/components/typography/Paragraph/Paragraph.tsx

@@ -0,0 +1,99 @@
+import type { Theme} from '@mui/material';
+import {Typography } from '@mui/material';
+import { styled } from '@mui/material/styles';
+import React from 'react';
+
+import type { ParagraphProps } from './Paragraph.types';
+
+const getColorFromTheme = (theme: Theme, color: string) => {
+  if (color === 'neutral') {
+    return theme.palette.text.primary;
+  }
+
+  const colorMap: Record<string, string> = {
+    primary: theme.palette.primary.main,
+    secondary: theme.palette.secondary.main,
+    success: theme.palette.success.main,
+    warning: theme.palette.warning.main,
+    danger: theme.palette.error.main,
+  };
+
+  return colorMap[color] || theme.palette.text.primary;
+};
+
+const StyledParagraph = styled(Typography, {
+  shouldForwardProp: (prop) =>
+    !['customVariant', 'customColor', 'customSize'].includes(prop as string),
+})<{
+  customVariant?: string;
+  customColor?: string;
+  customSize?: string;
+}>(({ theme, customVariant = 'default', customColor = 'neutral', customSize = 'md' }) => {
+  const textColor = getColorFromTheme(theme, customColor);
+
+  // Size mapping
+  const sizeMap = {
+    xs: { fontSize: '0.75rem', lineHeight: 1.4 },
+    sm: { fontSize: '0.875rem', lineHeight: 1.5 },
+    md: { fontSize: '1rem', lineHeight: 1.6 },
+    lg: { fontSize: '1.125rem', lineHeight: 1.6 },
+    xl: { fontSize: '1.25rem', lineHeight: 1.7 },
+  };
+
+  const baseStyles = {
+    fontFamily: theme.typography.body1.fontFamily,
+    margin: '0 0 1em 0',
+    transition: 'all 0.2s ease',
+    ...sizeMap[customSize as keyof typeof sizeMap],
+  };
+
+  // Variant-specific styles
+  const variantStyles = {
+    default: {
+      ...baseStyles,
+      color: textColor,
+      fontWeight: 400,
+    },
+    lead: {
+      ...baseStyles,
+      color: textColor,
+      fontWeight: 400,
+      fontSize:
+        customSize === 'md' ? '1.125rem' : sizeMap[customSize as keyof typeof sizeMap]?.fontSize,
+      lineHeight: 1.7,
+      letterSpacing: '0.01em',
+    },
+    muted: {
+      ...baseStyles,
+      color: theme.palette.text.secondary,
+      fontWeight: 400,
+      opacity: 0.8,
+    },
+    small: {
+      ...baseStyles,
+      color: theme.palette.text.secondary,
+      fontSize:
+        customSize === 'md' ? '0.875rem' : sizeMap[customSize as keyof typeof sizeMap]?.fontSize,
+      fontWeight: 400,
+      lineHeight: 1.5,
+    },
+  };
+
+  return variantStyles[customVariant as keyof typeof variantStyles] || variantStyles.default;
+});
+
+export const Paragraph = React.forwardRef<globalThis.HTMLParagraphElement, ParagraphProps>(
+  ({ variant = 'default', color = 'neutral', size = 'md', children, ...props }, ref) => (
+      <StyledParagraph
+        ref={ref}
+        customVariant={variant}
+        customColor={color}
+        customSize={size}
+        {...props}
+      >
+        {children}
+      </StyledParagraph>
+    ),
+);
+
+Paragraph.displayName = 'Paragraph';

package/src/components/typography/Paragraph/Paragraph.types.ts

@@ -0,0 +1,10 @@
+import type React from 'react';
+
+export type ParagraphVariant = 'default' | 'lead' | 'muted' | 'small';
+
+export interface ParagraphProps extends React.HTMLAttributes<globalThis.HTMLParagraphElement> {
+  variant?: ParagraphVariant;
+  color?: 'primary' | 'secondary' | 'success' | 'warning' | 'danger' | 'neutral';
+  size?: 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+  children: React.ReactNode;
+}

package/src/components/typography/Paragraph/index.ts

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

package/src/components/typography/Text/Text.md

@@ -0,0 +1,129 @@
+# Text Component
+
+## Overview
+
+The Text component is a versatile typography component that provides consistent text styling across the application. It supports multiple variants, sizes, colors, and styling options while maintaining accessibility standards.
+
+## Usage
+
+```tsx
+import { Text } from '@procurement/ui';
+
+// Basic usage
+<Text>Basic text content</Text>
+
+// With variant
+<Text variant="heading">Heading text</Text>
+<Text variant="caption">Caption text</Text>
+<Text variant="code">Inline code</Text>
+
+// With colors
+<Text color="primary">Primary text</Text>
+<Text color="secondary">Secondary text</Text>
+<Text color="success">Success text</Text>
+
+// With sizes
+<Text size="xs">Extra small text</Text>
+<Text size="lg">Large text</Text>
+
+// With styling
+<Text weight="bold" italic>Bold italic text</Text>
+<Text underline strikethrough>Decorated text</Text>
+
+// Custom HTML element
+<Text as="p">Paragraph element</Text>
+<Text as="span">Inline span element</Text>
+```
+
+## Props
+
+| Prop            | Type                                                                          | Default     | Description                             |
+| --------------- | ----------------------------------------------------------------------------- | ----------- | --------------------------------------- |
+| `variant`       | `'body' \| 'heading' \| 'caption' \| 'code'`                                  | `'body'`    | Text variant affecting typography style |
+| `color`         | `'primary' \| 'secondary' \| 'success' \| 'warning' \| 'danger' \| 'neutral'` | `'neutral'` | Text color from theme palette. `secondary` uses muted text color for less emphasis |
+| `size`          | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'`                                        | `'md'`      | Text size variant                       |
+| `weight`        | `'light' \| 'normal' \| 'medium' \| 'semibold' \| 'bold'`                     | `'normal'`  | Font weight                             |
+| `as`            | `React.ElementType`                                                           | `'span'`    | HTML element to render                  |
+| `italic`        | `boolean`                                                                     | `false`     | Apply italic styling                    |
+| `underline`     | `boolean`                                                                     | `false`     | Apply underline decoration              |
+| `strikethrough` | `boolean`                                                                     | `false`     | Apply strikethrough decoration          |
+| `children`      | `React.ReactNode`                                                             | -           | Text content                            |
+
+## Colors
+
+The `color` prop determines the text color using the theme palette:
+
+- **neutral** (default): Uses primary text color for maximum readability
+- **secondary**: Uses muted/secondary text color for less emphasis (e.g., descriptions, captions)
+- **primary**: Uses the primary brand color for emphasis
+- **success**: Green color for positive messages
+- **warning**: Orange/yellow color for warnings
+- **danger**: Red color for errors or critical messages
+
+All colors maintain WCAG AA contrast ratios for accessibility.
+
+## Variants
+
+### Body
+
+Default text variant for general content with standard typography settings.
+
+### Heading
+
+Text styled for headings with appropriate font weight and sizing.
+
+### Caption
+
+Smaller text for captions, labels, and secondary information.
+
+### Code
+
+Monospace text with background styling for inline code snippets.
+
+## Accessibility
+
+- Uses semantic HTML elements through the `as` prop
+- Maintains proper color contrast ratios for all color variants
+- Supports screen readers with appropriate text content
+- Respects user's motion preferences for animations
+
+## Best Practices
+
+- Use appropriate variants for content hierarchy
+- Choose colors that maintain good contrast ratios
+- Use the `as` prop to render semantically correct HTML elements
+- Combine styling props thoughtfully to maintain readability
+- Consider responsive design when choosing sizes
+
+## Examples
+
+### Content Hierarchy
+
+```tsx
+<Text variant="heading" size="xl" weight="bold">Main Heading</Text>
+<Text variant="body" size="md">Body text content goes here.</Text>
+<Text variant="caption" size="sm" color="secondary">Additional details</Text>
+```
+
+### Inline Code
+
+```tsx
+<Text>
+  Use the <Text variant="code">useState</Text> hook for state management.
+</Text>
+```
+
+### Decorated Text
+
+```tsx
+<Text weight="bold" color="danger" underline>
+  Important notice
+</Text>
+```
+
+### Custom Elements
+
+```tsx
+<Text as="h2" variant="heading" size="lg">Section Title</Text>
+<Text as="p" variant="body">Paragraph content</Text>
+```