npm package: @frontrowcc/react-components
Description: This is the opinionated component library used to build FrontRow extensions and our core product. It provides a comprehensive set of React components designed for consistent, accessible, and customizable user interfaces.
Latest version: 0.0.6

# FrontRow React Component Library

This is the opinionated component library used to build FrontRow extensions and our core product. It provides a comprehensive set of React components designed for consistent, accessible, and customizable user interfaces.

## Installation

```bash
yarn add @frontrowcc/react-components
```

## Available Components

### Layout & Structure

#### Card

A flexible card component that provides various visual styles and layout options. Perfect for containing content in a visually distinct container with optional styling variants.

```tsx
import { Card } from '@frontrowcc/react-components'
;<Card variant="glassmorphism" width="300px" height="200px" padding="2rem">
  Content with custom dimensions and styling
</Card>
```

**Variants:** `borderless`, `errorToast`, `ghost`, `glassmorphism`, `successToast`, `warningToast`

#### Accordion

A flexible and accessible accordion component built on top of Radix UI's Accordion primitive. Supports both single and multiple panel variants with customizable styling and animations.

```tsx
import { Accordion, Accordions } from '@frontrowcc/react-components'

// Single accordion
<Accordion title="Section Title" defaultValue="item-1">
  This is the accordion content
</Accordion>

// Multiple accordions
const items = [
  { title: "Section 1", content: "Content for section 1" },
  { title: "Section 2", content: "Content for section 2" }
]
<Accordions items={items} />
```

#### Tabs

A flexible and accessible tabs component built with Radix UI that supports multiple styles, scrolling, and advanced features like notifications and error states.

```tsx
import { Tabs } from '@frontrowcc/react-components'

const tabs = [
  { label: 'Account', value: 'account', content: <div>Account settings</div> },
  { label: 'Password', value: 'password', content: <div>Password settings</div> }
]

<Tabs tabs={tabs} type="pills" defaultValue="account" />
```

**Types:** `underlined`, `pills`, `drawer`, `spacedPills`

### User Interface

#### Button

A versatile button component that supports multiple variants, sizes, and states. Built with accessibility and customization in mind.

```tsx
import { Button, LinkButton } from '@frontrowcc/react-components'

<Button variant="primary" size="large" loading>Submit</Button>
<LinkButton href="/internal-route">Internal Route</LinkButton>
```

**Variants:** `primary`, `secondary`, `tertiary`, `minimal`, `outlined`, `translucent`, `yellow`
**Sizes:** `extraSmall`, `small`, `medium`, `large`

#### Avatar

A flexible avatar component that displays either an image or initials. Automatically falls back to displaying the first initial of the display name when no image URL is provided.

```tsx
import { Avatar } from '@frontrowcc/react-components'
;<Avatar
  avatarUrl="https://example.com/avatar.jpg"
  displayName="John Doe"
  size="32"
/>
```

#### Icon

A flexible SVG icon renderer that uses an SVG sprite sheet for displaying various icons in the application.

```tsx
import { Icon } from '@frontrowcc/react-components'

<Icon name="search" size="medium" />
<Icon name="close" width={24} height={24} />
```

**Sizes:** `xsmall`, `small`, `medium`, `large`, `xlarge`, `xxlarge`

#### Spinner

A lightweight, customizable loading spinner component that provides visual feedback for loading states.

```tsx
import { Spinner } from '@frontrowcc/react-components'
;<Spinner width={32} height={32} color="#FF0000" />
```

#### ToggleGroup

A customizable toggle group component that allows users to select a single option from multiple choices. Built on top of Radix UI's Toggle Group component with support for icons and labels.

```tsx
import { ToggleGroup } from '@frontrowcc/react-components'
;<ToggleGroup
  name="layout-selector"
  defaultValue="list"
  onChange={(value) => setViewMode(value)}
  options={[
    { value: 'list', label: 'List View', Icon: ListIcon },
    { value: 'grid', label: 'Grid View', Icon: GridIcon },
    { value: 'card', label: 'Card View', Icon: CardIcon },
  ]}
/>
```

**Features:** Single selection, icon support, accessible, full width option, admin and monochrome styling variants

#### Alert

Visual feedback component for displaying important messages to users.

```tsx
import { Alert } from '@frontrowcc/react-components'
;<Alert variant="success">Operation completed successfully!</Alert>
```

### Data Display

#### Table

A reusable table component built on top of AG Grid Community Edition with features like filtering, sorting, and empty states.

```tsx
import { Table } from '@frontrowcc/react-components'

const columnDefs = [
  { field: 'id', headerName: 'ID' },
  { field: 'name', headerName: 'Name' },
  { field: 'email', headerName: 'Email' }
]

<Table<User> colDefs={columnDefs} rowData={users} />
```

#### Image

A simple yet robust image component with built-in fallback handling and responsive capabilities.

```tsx
import { Image } from '@frontrowcc/react-components'
;<Image imageSrc="https://example.com/image.jpg" alt="Responsive image" fill />
```

#### Tooltip

A flexible tooltip component built on top of Radix UI's Tooltip primitive. Provides informative hover tooltips for desktop and touch-friendly popovers for mobile devices.

```tsx
import { Tooltip } from '@frontrowcc/react-components'
;<Tooltip content="Helpful information" delay={500}>
  <button>Hover me</button>
</Tooltip>
```

#### Tag

A versatile tag/badge component that supports multiple variants, colors, and styles for labeling and categorization.

```tsx
import { Tag } from '@frontrowcc/react-components'

<Tag color="green">Success</Tag>
<Tag color="red" variant="small">Error</Tag>
<Tag variant="bordered" text="primary">Label</Tag>
```

**Colors:** `green`, `grey`, `orange`, `red`, `white`, `yellow`
**Text Colors:** `blue`, `orange`, `primary`, `red`, `white`, `yellow`
**Variants:** `bordered`, `contentPicker`, `disabled`, `livestream`, `neutral`, `notLivestream`, `small`, `square`

### Typography

A comprehensive set of typography components for consistent text styling across the application.

```tsx
import { Text, Heading, Eyebrows } from '@frontrowcc/react-components'

<Heading size="xxl" color="primary">Main Title</Heading>
<Text size="lg" semiBold>Important text content</Text>
<Eyebrows size="md" color="secondary">Category Label</Eyebrows>
```

**Text Sizes:** `xxs`, `xs`, `sm`, `md`, `lg`
**Heading Sizes:** `sm`, `md`, `lg`, `xl`, `xxl`
**Eyebrows Sizes:** `xs`, `sm`, `md`, `lg`
**Colors:** `primary`, `secondary`, `tertiary`, `quaternary`, `success`

### Form Components

A comprehensive collection of form components built for React applications. These components are designed to provide a consistent, accessible, and customizable form experience.

#### TextInput

A flexible text input component that supports icons, helper text, and validation.

```tsx
import { TextInput } from '@frontrowcc/react-components'
;<TextInput
  name="email"
  label="Email Address"
  placeholder="Enter your email"
  required
  helperText="We'll never share your email"
/>
```

#### Select & MultiSelect

Customizable select components built on top of react-select.

```tsx
import { Select, MultiSelect } from '@frontrowcc/react-components'

const options = [
  { value: 'option1', label: 'Option 1' },
  { value: 'option2', label: 'Option 2' }
]

<Select
  name="select"
  label="Choose an option"
  options={options}
  placeholder="Select an option..."
/>
```

#### Checkbox

A customizable checkbox component with support for different sizes.

```tsx
import { Checkbox } from '@frontrowcc/react-components'
;<Checkbox name="terms" label="I agree to the terms" checkSize="md" />
```

**Sizes:** `xs`, `sm`, `md`

#### Radio & RadioGroup

Radio button components for single-selection options.

```tsx
import { Radio, RadioGroup } from '@frontrowcc/react-components'
;<RadioGroup name="options">
  <Radio id="option1" name="options" label="Option 1" value="1" />
  <Radio id="option2" name="options" label="Option 2" value="2" />
</RadioGroup>
```

#### Additional Form Components

- `ColorInput`: Color picker input
- `FileInput`: File upload input
- `PhoneInput`: Phone number input with formatting
- `TextArea`: Multi-line text input
- `Toggle`: Toggle switch component
- `Dropdown`: Enhanced dropdown with various styling options

### Theme Support

#### ThemeProvider

Provides theme context and global styles for the component library.

```tsx
import { ThemeProvider, getGlobalStyles } from '@frontrowcc/react-components'
;<ThemeProvider>
  <App />
</ThemeProvider>
```

## Common Props

Most components share these common props:

- `className`: Additional CSS class names
- `testId`: Test ID for testing purposes
- `disabled`: Whether the component is disabled
- `children`: Content to be rendered inside the component

## Form-Specific Common Props

- `name` (required): Unique identifier for the form field
- `label`: Text label for the field
- `error`: Error message to display
- `required`: Whether the field is required
- `tooltipText`: Tooltip text to show on hover

## Styling

The components use CSS modules for styling and support theming through CSS variables. Key variables include:

- `--primaryColor`: Primary theme color
- `--text-default`: Default text color
- `--text-secondary`: Secondary text color
- `--bg-default`: Default background color
- `--stroke-default`: Border color
- `--radius-sm`: Small border radius
- `--spacing-4`: Small spacing unit
- `--spacing-8`: Medium spacing unit

## Accessibility

All components are built with accessibility in mind:

- ARIA labels and descriptions
- Keyboard navigation support
- Focus management
- Screen reader friendly
- Support for required and error states
- High contrast mode compatibility

## Browser Support

- Modern browsers supporting CSS Grid and Flexbox
- ES6+ JavaScript features
- ResizeObserver and MutationObserver APIs (for applicable components)

## Dependencies

Key dependencies include:

- React 16.8+
- Radix UI primitives (for accessible components)
- AG Grid Community (for Table component)
- react-select (for Select components)
- clsx (for class name management)

## Development

### Creating New Icons

1. Create a new SVG file in `libs/ui/src/Iconography/svg-icons`
2. Use kebab-case for the file name
3. Run `yarn generate` to make it available

### Component Structure

Each component follows this structure:

- Main component file (`Component.tsx`)
- Styles (`Component.module.scss`)
- Tests (`Component.test.tsx`)
- Documentation (`README.md`)
- Types (`types.ts` if needed)

## Contributing

When contributing to this library:

1. Follow the existing component patterns
2. Include comprehensive tests
3. Update documentation
4. Maintain accessibility standards
5. Use CSS properties in alphabetical order
6. Export types in their own exports
7. Use yarn instead of npm for commands

## Changelog

See [CHANGELOG.md](./CHANGELOG.md) for version history and changes.