# @impactsmartsuite/impact-ui

Impact Analytics UI Component Library - A modern, accessible React component library built with TypeScript and Vite (private npm package).

## Features

- 🎨 **48+ Production-Ready Components** - Comprehensive UI component library
- 🔒 **TypeScript First** - Full type safety with TypeScript definitions
- ♿ **Accessibility** - WCAG 2.1 Level AA compliant
- ⚡ **Fast** - Built with Vite for optimal performance
- 🎭 **Storybook** - Interactive component documentation
- 🧪 **Well Tested** - Unit tests with accessibility checks
- 📦 **Tree Shakeable** - Import only what you need

## Installation

```bash
npm install @impactsmartsuite/impact-ui
```

## Usage

### Basic Example

```typescript
import { Button } from '@impactsmartsuite/impact-ui';
import '@impactsmartsuite/impact-ui/styles';

function App() {
  return (
    <Button variant="primary" size="large">
      Click Me
    </Button>
  );
}
```

### TypeScript Support

```typescript
import { Button, type ButtonProps } from '@impactsmartsuite/impact-ui';

const props: ButtonProps = {
  variant: 'primary',
  size: 'large',
  onClick: (e) => console.log('Clicked!'),
};
```

## Development

### Prerequisites

- Node.js 16+
- npm or yarn

### Setup

```bash
# Install dependencies
npm install

# Start development server
npm run dev

# Run Storybook
npm run storybook

# Run tests
npm run test

# Run tests with UI
npm run test:ui
```

### Scripts

- `npm run dev` - Start Vite dev server
- `npm run build` - Build library for production
- `npm run build:lib` - Build library (alias)
- `npm run preview` - Preview production build
- `npm run storybook` - Start Storybook dev server
- `npm run build:storybook` - Build Storybook static site
- `npm run test` - Run tests with Vitest
- `npm run test:ui` - Run tests with UI
- `npm run test:storybook` - Run Storybook play tests (Vitest + Playwright)
- `npm run playwright:install` - Install Chromium only (required for `test:storybook`)
- `npm run lint` - Lint TypeScript files
- `npm run lint:fix` - Fix linting errors
- `npm run lint:a11y` - Check accessibility compliance
- `npm run format` - Format code with Prettier
- `npm run format:check` - Check code formatting
- `npm run type-check` - Type check without emitting files

### Storybook tests and Playwright

To run Storybook play tests (`npm run test:storybook`), install Chromium first:

```bash
npm run playwright:install
```

If you see **"unable to get local issuer certificate"** (common on corporate networks with a custom CA):

1. **Recommended:** Point Node at your CA bundle:  
   `NODE_EXTRA_CA_CERTS=/path/to/your/ca-bundle.pem npm run playwright:install`
2. **Last resort (insecure):** Disable TLS verification only for the install:  
   `NODE_TLS_REJECT_UNAUTHORIZED=0 npm run playwright:install`

## Project Structure

```
frontend/
├── .storybook/          # Storybook configuration
├── src/
│   ├── components/      # UI components
│   ├── styles/          # Global styles
│   ├── test/            # Test utilities
│   └── types/           # TypeScript type definitions
├── dist/                # Build output
├── tsconfig.json        # TypeScript configuration
├── vite.config.ts       # Vite configuration
└── vitest.config.ts     # Vitest configuration
```

## Contributing

1. Create a feature branch
2. Make your changes
3. Run tests: `npm run test`
4. Run linting: `npm run lint`
5. Format code: `npm run format`
6. Type check: `npm run type-check`
7. Submit a pull request

### Code Quality

All code must pass:
- TypeScript compilation without errors
- ESLint checks (including accessibility)
- Prettier formatting
- Unit tests with accessibility checks

## Accessibility

This library follows WCAG 2.1 Level AA standards. All components include:
- Proper semantic HTML
- ARIA attributes where needed
- Keyboard navigation support
- Screen reader compatibility
- Focus management

Run accessibility checks:
```bash
npm run lint:a11y
```

## Browser Support

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

## License

MIT

## Version

Current version: 4.0.0-alpha.1

See [MIGRATION_GUIDE.md](./MIGRATION_GUIDE.md) for upgrading from v3.x.