infinity-ui-elements/README.md

A React TypeScript component library with Tailwind CSS design system

# Infinity UI Elements

A comprehensive React TypeScript component library with a modern design system built on Tailwind CSS. Perfect for building consistent, accessible, and beautiful user interfaces for Infinity products.

## 🎯 Features

- 🎨 **Comprehensive Design System**: 25+ production-ready components with consistent styling
- 📦 **Tree-shakable**: ESM + CJS builds optimized with Rollup
- 🔒 **TypeScript**: Full type safety and IntelliSense support
- ♿ **Accessible**: ARIA compliant components following WAI-ARIA guidelines
- 🎭 **Flexible**: Support for variants, sizes, colors, and custom styling
- 📚 **Well Documented**: Interactive Storybook documentation
- ⚡ **Performance**: Optimized bundle size with zero runtime overhead
- 🌈 **Theme Support**: CSS custom properties for easy theming

---

## 🎨 Design System - Single Source of Truth

**Infinity UI Elements** is not just a component library—it's a complete design system that serves as the **single source of truth** for all design tokens, CSS variables, and styling for Infinity products.

### Why This Matters

When you integrate this library:
- ✅ **All design tokens** (colors, typography, spacing, borders) are automatically available
- ✅ **Designers update once** → changes propagate to all apps via package updates
- ✅ **No duplication** → maintain consistency across products
- ✅ **Easy updates** → `yarn upgrade infinity-ui-elements` to get latest design changes

### What You Get

```tsx
import 'infinity-ui-elements/dist/index.css';
```

This single import gives you access to **hundreds of CSS variables**:

```css
/* Colors (300+ tokens) */
var(--color-teal-500)
var(--color-action-fill-primary-default)
var(--color-surface-ink-neutral-normal)

/* Typography */
var(--font-functional)
var(--text-200)
var(--leading-500)

/* Spacing */
var(--spacing-5)
var(--size-32)

/* Borders & Radius */
var(--border-width-thin)
var(--radius-large)
```

Use these variables anywhere in your custom CSS—no need to redefine them!

**📚 See [DESIGN_TOKENS.md](./DESIGN_TOKENS.md) for complete reference**  
**🚀 See [INTEGRATION.md](./INTEGRATION.md) for integration guide**

---

## 📦 Installation

```bash
yarn add infinity-ui-elements
# or
npm install infinity-ui-elements
```

### Peer Dependencies

Install the required peer dependencies:

```bash
yarn add react react-dom clsx tailwind-merge class-variance-authority
# or
npm install react react-dom clsx tailwind-merge class-variance-authority
```

For Table component (optional):
```bash
yarn add @tanstack/react-table
```

---

## 🚀 Quick Start

### 1. Import CSS

In your main application file (e.g., `App.tsx` or `index.tsx`):

```tsx
import 'infinity-ui-elements/dist/index.css';
```

### 2. Use Components

```tsx
import { Button, TextField, Badge } from 'infinity-ui-elements';

function App() {
  return (
    <div>
      <Button variant="primary" color="primary">
        Get Started
      </Button>
      
      <TextField 
        label="Email"
        placeholder="Enter your email"
        type="email"
      />
      
      <Badge color="positive" variant="light">
        Active
      </Badge>
    </div>
  );
}
```

### 3. Configure Tailwind CSS

The library uses custom utility classes that are pre-built. Configure your Tailwind setup to avoid conflicts:

#### For Tailwind CSS v4:
```js
// tailwind.config.js
export default {
  content: [
    './src/**/*.{js,ts,jsx,tsx}',
    // Don't include node_modules - CSS is already compiled
  ],
}
```

#### For Tailwind CSS v3:
```js
// tailwind.config.js
module.exports = {
  content: [
    './src/**/*.{js,ts,jsx,tsx}',
  ],
  safelist: [
    { pattern: /^(font-size|leading|font-functional|font-display|text-surface|text-action|bg-action|border-action)/ },
  ],
}
```

---

## 🧩 Components

### Form Components

#### Button
A versatile button component with multiple variants, colors, sizes, and loading states.

**Key Features:**
- 3 variants: `primary`, `secondary`, `tertiary`
- 6 color options: `primary`, `positive`, `negative`, `notice`, `info`, `neutral`
- 4 sizes: `xsmall`, `small`, `medium`, `large`
- Leading/trailing icons support
- Loading states with spinners
- Icon-only mode
- Full-width option

```tsx
import { Button } from 'infinity-ui-elements';

<Button variant="primary" color="positive" size="medium">
  Save Changes
</Button>

<Button variant="secondary" color="negative" isLoading>
  Deleting...
</Button>

<Button variant="tertiary" leadingIcon={<PlusIcon />}>
  Add Item
</Button>
```

#### TextField
A text input component with validation, icons, and helper text.

**Key Features:**
- Label with required/optional indicators
- Prefix and suffix support
- Validation states: `positive`, `negative`
- Clear button option
- Helper text and error messages
- Info tooltip integration
- Link support

```tsx
import { TextField } from 'infinity-ui-elements';

<TextField
  label="Email Address"
  placeholder="Enter your email"
  type="email"
  isRequired
  helperText="We'll never share your email"
  showClearButton
/>

<TextField
  label="Amount"
  prefix="$"
  suffix="USD"
  validationState="positive"
  successText="Valid amount"
/>
```

#### TextArea
A multi-line text input with auto-resize capability.

**Key Features:**
- Auto-resize option
- Character count display
- Validation states
- Helper text support
- All TextField features

```tsx
import { TextArea } from 'infinity-ui-elements';

<TextArea
  label="Description"
  placeholder="Enter description..."
  rows={4}
  maxLength={500}
  showCharCount
/>
```

#### Select
A dropdown select component with keyboard navigation.

**Key Features:**
- Searchable options
- Custom option rendering
- Prefix/suffix support
- Loading state
- Empty state customization
- Keyboard navigation
- Clear button

```tsx
import { Select } from 'infinity-ui-elements';

const options = [
  { value: 'us', label: 'United States' },
  { value: 'uk', label: 'United Kingdom' },
  { value: 'ca', label: 'Canada' },
];

<Select
  label="Country"
  options={options}
  placeholder="Select a country"
  onChange={(value, option) => console.log(value)}
  showClearButton
/>
```

#### SearchableDropdown
An advanced dropdown with built-in search functionality.

**Key Features:**
- Real-time search filtering
- Multiple selection support
- Custom option rendering
- Grouped options
- Async data loading

```tsx
import { SearchableDropdown } from 'infinity-ui-elements';

<SearchableDropdown
  label="Select Users"
  options={users}
  searchable
  placeholder="Search users..."
  onChange={(selected) => setSelectedUsers(selected)}
/>
```

#### Checkbox
A checkbox component with indeterminate state support.

**Key Features:**
- Indeterminate state for "select all"
- 3 sizes: `small`, `medium`, `large`
- Validation states
- Helper text and error messages
- Disabled state

```tsx
import { Checkbox } from 'infinity-ui-elements';

<Checkbox 
  label="Accept terms and conditions"
  isRequired
  validationState="error"
  errorText="You must accept the terms"
/>

<Checkbox 
  label="Select all"
  isIndeterminate={someSelected && !allSelected}
  checked={allSelected}
/>
```

#### Radio
A radio button component for single selection.

**Key Features:**
- Custom styling
- Validation states
- Helper text support
- Disabled state
- Multiple sizes

```tsx
import { Radio } from 'infinity-ui-elements';

<Radio
  label="Option 1"
  name="choice"
  value="option1"
  checked={selected === 'option1'}
  onChange={(e) => setSelected(e.target.value)}
/>
```

#### Switch
A toggle switch component for boolean states.

**Key Features:**
- Multiple sizes
- Disabled state
- Label support
- Custom colors
- Loading state

```tsx
import { Switch } from 'infinity-ui-elements';

<Switch
  label="Enable notifications"
  checked={isEnabled}
  onChange={(checked) => setIsEnabled(checked)}
/>
```

---

### Data Display Components

#### Table
A powerful data table built on TanStack Table with advanced features.

**Key Features:**
- Sorting, filtering, pagination
- Row selection
- Expandable detail panels
- Sticky headers
- Loading and empty states
- Custom cell rendering
- Horizontal scrolling
- Row hover effects

```tsx
import { Table } from 'infinity-ui-elements';
import { useReactTable, getCoreRowModel, createColumnHelper } from '@tanstack/react-table';

const columnHelper = createColumnHelper<User>();

const columns = [
  columnHelper.accessor('name', {
    header: 'Name',
    cell: info => info.getValue(),
  }),
  columnHelper.accessor('email', {
    header: 'Email',
  }),
];

const table = useReactTable({
  data,
  columns,
  getCoreRowModel: getCoreRowModel(),
});

<Table 
  table={table}
  enableRowSelection
  showRowHover
  stickyHeader
  detailPanel={(row) => <UserDetails user={row.original} />}
/>
```

#### Badge
A small status indicator component.

**Key Features:**
- 2 variants: `light`, `filled`
- 6 color options
- 3 sizes: `small`, `medium`, `large`
- Optional dot indicator
- Custom content support

```tsx
import { Badge } from 'infinity-ui-elements';

<Badge variant="filled" color="positive">
  Active
</Badge>

<Badge variant="light" color="notice" showDot>
  Pending
</Badge>
```

#### Avatar
A user avatar component with status indicators.

**Key Features:**
- Image or text initials
- Status indicator with custom icons
- 5 color variants
- 2 sizes: `small`, `medium`
- Label and trailing component support
- Fallback for broken images

```tsx
import { Avatar } from 'infinity-ui-elements';

<Avatar
  src="/user-avatar.jpg"
  alt="John Doe"
  size="medium"
  showStatus
  statusColor="positive"
/>

<Avatar color="a1" size="small">
  JD
</Avatar>

<Avatar
  src="/user.jpg"
  label="John Doe"
  trailingComponent={<ChevronDown />}
/>
```

#### Counter
A numeric counter with increment/decrement controls.

**Key Features:**
- Min/max value constraints
- Step control
- Disabled state
- Custom formatting
- Size variants

```tsx
import { Counter } from 'infinity-ui-elements';

<Counter
  value={count}
  onChange={setCount}
  min={0}
  max={100}
  step={1}
/>
```

#### Text
A typography component with consistent styling.

**Key Features:**
- Multiple variants: `display`, `heading`, `body`, `label`, `caption`
- Size options for each variant
- Weight options: `regular`, `medium`, `semibold`, `bold`
- Color options
- Polymorphic `as` prop

```tsx
import { Text } from 'infinity-ui-elements';

<Text variant="heading" size="xlarge" weight="bold">
  Welcome Back
</Text>

<Text variant="body" size="medium" color="muted">
  This is a description
</Text>

<Text variant="label" as="label" htmlFor="input-id">
  Field Label
</Text>
```

---

### Navigation Components

#### Link
A styled link component with various visual states.

**Key Features:**
- Multiple variants
- External link support
- Disabled state
- Icon support
- Underline options

```tsx
import { Link } from 'infinity-ui-elements';

<Link href="/dashboard" variant="primary">
  Go to Dashboard
</Link>

<Link href="https://example.com" external>
  Visit Website
</Link>
```

#### Tabs / TabItem
Tab navigation components for organizing content.

**Key Features:**
- Horizontal and vertical layouts
- Active state management
- Icon support
- Disabled tabs
- Keyboard navigation

```tsx
import { Tabs, TabItem } from 'infinity-ui-elements';

<Tabs>
  <TabItem active>Overview</TabItem>
  <TabItem>Settings</TabItem>
  <TabItem disabled>Analytics</TabItem>
</Tabs>
```

#### Pagination
A pagination component for navigating through pages.

**Key Features:**
- Page number display
- Previous/Next buttons
- First/Last page navigation
- Custom page size
- Controlled and uncontrolled modes

```tsx
import { Pagination } from 'infinity-ui-elements';

<Pagination
  currentPage={page}
  totalPages={10}
  onPageChange={setPage}
  showFirstLast
/>
```

---

### Layout Components

#### ButtonGroup
A component for grouping related buttons.

**Key Features:**
- Horizontal and vertical layouts
- Connected or separated styles
- Size variants
- Full-width option

```tsx
import { ButtonGroup, Button } from 'infinity-ui-elements';

<ButtonGroup>
  <Button variant="secondary">Cancel</Button>
  <Button variant="primary">Save</Button>
</ButtonGroup>
```

#### Divider
A visual separator component.

**Key Features:**
- Horizontal and vertical orientations
- With or without text
- Custom styling
- Spacing control

```tsx
import { Divider } from 'infinity-ui-elements';

<Divider />

<Divider orientation="vertical" />

<Divider>OR</Divider>
```

#### Modal
A modal dialog component for overlays.

**Key Features:**
- Multiple size options
- Header with title and description
- Footer support
- Close on overlay click
- Escape key support
- Scroll locking
- Animation transitions

```tsx
import { Modal } from 'infinity-ui-elements';

<Modal
  isOpen={isOpen}
  onClose={() => setIsOpen(false)}
  title="Confirm Action"
  description="Are you sure you want to proceed?"
  size="medium"
  footer={
    <>
      <Button variant="secondary" onClick={() => setIsOpen(false)}>
        Cancel
      </Button>
      <Button variant="primary" onClick={handleConfirm}>
        Confirm
      </Button>
    </>
  }
>
  <p>Modal content goes here...</p>
</Modal>
```

#### Tooltip
A tooltip component for displaying contextual information.

**Key Features:**
- Multiple placement options
- Trigger on hover or click
- Delay control
- Arrow indicator
- Custom styling

```tsx
import { Tooltip } from 'infinity-ui-elements';

<Tooltip content="This is helpful information">
  <Button>Hover me</Button>
</Tooltip>
```

#### ListItem
A list item component for building lists.

**Key Features:**
- Leading and trailing content
- Multi-line support
- Clickable/interactive
- Custom styling
- Icon support

```tsx
import { ListItem } from 'infinity-ui-elements';

<ListItem
  leadingIcon={<UserIcon />}
  title="John Doe"
  description="john@example.com"
  trailingContent={<ChevronRight />}
  onClick={() => console.log('Clicked')}
/>
```

---

### Form Layout Components

#### FormHeader
A form header component with label and info tooltip.

**Key Features:**
- Required/optional indicators
- Info tooltip
- Link support
- Size variants
- Custom styling

```tsx
import { FormHeader } from 'infinity-ui-elements';

<FormHeader
  label="Email Address"
  isRequired
  infoHeading="Why we need this"
  infoDescription="We use your email for account recovery"
  linkText="Privacy Policy"
  linkHref="/privacy"
/>
```

#### FormFooter
A form footer component for helper text and validation messages.

**Key Features:**
- Validation state styling
- Error/success messages
- Helper text
- Size variants

```tsx
import { FormFooter } from 'infinity-ui-elements';

<FormFooter
  helperText="Password must be at least 8 characters"
  validationState="negative"
/>
```

---

### Interactive Components

#### Dropdown / DropdownMenu
A flexible dropdown menu component.

**Key Features:**
- Custom trigger
- Nested menus
- Keyboard navigation
- Dividers and sections
- Icon support
- Custom item rendering

```tsx
import { Dropdown } from 'infinity-ui-elements';

<Dropdown
  trigger={<Button>Options</Button>}
  items={[
    { title: 'Edit', onClick: handleEdit },
    { title: 'Delete', onClick: handleDelete, color: 'negative' },
  ]}
/>
```

---

## 🎨 Using Design Tokens in Your App

### Using CSS Variables

After importing the library CSS, use design tokens anywhere in your application:

```css
/* YourCustomComponent.css */
.my-card {
  background: var(--color-surface-fill-neutral-intense);
  border: var(--border-width-thin) solid var(--color-surface-outline-neutral-muted);
  border-radius: var(--radius-large);
  padding: var(--spacing-7);
  color: var(--color-surface-ink-neutral-normal);
}

.my-button {
  background: var(--color-action-fill-primary-default);
  color: var(--color-action-ink-on-primary-normal);
  padding: var(--spacing-3) var(--spacing-6);
  font-family: var(--font-functional);
  font-size: var(--text-100);
  border-radius: var(--radius-medium);
}

.my-button:hover {
  background: var(--color-action-fill-primary-hover);
}
```

### Using Inline Styles (React)

```tsx
<div style={{
  backgroundColor: 'var(--color-teal-500)',
  padding: 'var(--spacing-5)',
  borderRadius: 'var(--radius-medium)',
  fontFamily: 'var(--font-functional)',
}}>
  Styled with design tokens
</div>
```

### Overriding Tokens (Advanced)

Only override if absolutely necessary for app-specific themes:

```css
/* app-overrides.css - Import AFTER the library CSS */
:root {
  /* Override specific tokens for your app */
  --app-specific-color: var(--color-teal-700);
}
```

**⚠️ Important:** Do NOT duplicate design tokens in your app. Always use the tokens from this package to maintain consistency. When designers make changes, update the package version to get the latest design system.

**📚 Complete Token Reference:** See [DESIGN_TOKENS.md](./DESIGN_TOKENS.md) for all available variables.

---

## 🛠️ Development

### Prerequisites
- Node.js 18+
- Yarn 4.5.2 (managed via Corepack)

### Setup

```bash
# Install dependencies
yarn install

# Start Storybook for development
yarn storybook

# Build the library
yarn build

# Type checking
yarn type-check
```

### Project Structure

```
src/
├── components/           # All UI components
│   ├── Button/
│   │   ├── Button.tsx           # Component implementation
│   │   ├── Button.stories.tsx   # Storybook stories
│   │   └── index.ts             # Exports
│   └── ...
├── lib/                  # Utilities and helpers
│   ├── utils.ts          # Utility functions
│   └── icons.tsx         # Icon system
├── styles/               # Global styles
│   ├── theme/            # Theme variables
│   ├── animations.css    # Animations
│   └── utilities/        # Utility classes
└── index.ts              # Main entry point
```

### Adding New Components

1. Create component folder in `src/components/`
2. Implement component with TypeScript
3. Add Storybook stories for documentation
4. Export from component's `index.ts`
5. Add export to main `src/index.ts`

---

## 📚 Storybook

View interactive documentation and examples:

```bash
yarn storybook
```

Or visit the deployed Storybook (if available).

---

## 📤 Publishing

### Automated Publishing

```bash
# For bug fixes (1.0.0 -> 1.0.1)
yarn publish:patch

# For new features (1.0.0 -> 1.1.0)
yarn publish:minor

# For breaking changes (1.0.0 -> 2.0.0)
yarn publish:major

# For beta releases
yarn publish:beta
```

### Manual Publishing

```bash
# 1. Login to npm
npm login

# 2. Update version
yarn version:patch  # or version:minor, version:major

# 3. Build
yarn build

# 4. Publish
npm publish
```

### Pre-publish Checklist

- ✅ All tests pass
- ✅ Type checking passes (`yarn type-check`)
- ✅ Storybook builds successfully
- ✅ CHANGELOG.md updated
- ✅ Version bumped in package.json

---

## 🤝 Contributing

Contributions are welcome! Please follow these guidelines:

1. **Fork the repository**
2. **Create a feature branch**: `git checkout -b feature/amazing-feature`
3. **Make your changes** following the coding standards
4. **Add tests** if applicable
5. **Update documentation** (README, Storybook)
6. **Commit changes**: `git commit -m 'Add amazing feature'`
7. **Push to branch**: `git push origin feature/amazing-feature`
8. **Open a Pull Request**

### Component Guidelines

- Use TypeScript with strict mode
- Follow existing naming conventions
- Use Tailwind CSS for styling via class-variance-authority
- Include proper prop types and JSDoc comments
- Create comprehensive Storybook stories
- Ensure accessibility (ARIA attributes, keyboard navigation)
- Export from barrel files (`index.ts`)

---

## 🔍 Browser Support

- Chrome (latest)
- Firefox (latest)
- Safari (latest)
- Edge (latest)

---

## 📝 License

MIT © Himanshu Barmola

---

## 🔗 Links

- [NPM Package](https://www.npmjs.com/package/infinity-ui-elements)
- [GitHub Repository](https://github.com/yourusername/infinity-ui-elements)
- [Storybook Documentation](https://your-storybook-url.com)
- [Report Issues](https://github.com/yourusername/infinity-ui-elements/issues)

---

## 💡 Tips & Best Practices

### Performance
- Import only the components you need (tree-shaking enabled)
- Use the `cn()` utility for conditional classes
- Avoid inline styles when possible

### Styling
- Always import the main CSS file: `import 'infinity-ui-elements/dist/index.css'`
- Use the provided design tokens for consistency
- Extend with custom classes using `className` prop

### Accessibility
- Always provide labels for form components
- Use semantic HTML elements
- Include ARIA attributes where needed
- Test with keyboard navigation

### TypeScript
- All components are fully typed
- Use IntelliSense for prop discovery
- Extend interfaces if needed for custom types

---

## 🆘 Support

Need help? Have questions?

- 📧 Email: support@infinityapp.com
- 💬 GitHub Discussions
- 🐛 Report bugs via GitHub Issues

---

## 🎉 Acknowledgments

Built with:
- [React](https://reactjs.org/)
- [TypeScript](https://www.typescriptlang.org/)
- [Tailwind CSS](https://tailwindcss.com/)
- [Storybook](https://storybook.js.org/)
- [TanStack Table](https://tanstack.com/table)
- [Lucide Icons](https://lucide.dev/)
- [Class Variance Authority](https://cva.style/)

---

**Made with ❤️ by the Infinity Team**