# @windstream/react-shared-components

A comprehensive React component library built with TypeScript and Tailwind CSS, designed for Kinetic applications. This library provides a complete set of reusable UI components following the Kinetic design system.

## 🚀 Features

- **TypeScript First**: Full TypeScript support with comprehensive type definitions
- **Tailwind CSS**: Built with Tailwind CSS for consistent design and easy customization
- **Modern React**: Built with React 18+ and modern hooks
- **Accessible**: Components follow accessibility best practices
- **Customizable**: Easy to customize with CSS variables and Tailwind classes
- **Tree-shakeable**: Optimized for bundle size with proper exports
- **Storybook**: Interactive component documentation and development environment
- **Design System**: Comprehensive design tokens following Kinetic brand guidelines
- **Material Icons**: Built-in Material Symbols Rounded icon support

## 📦 Installation

```bash
npm install @windstream/react-shared-components
# or
yarn add @windstream/react-shared-components
# or
pnpm add @windstream/react-shared-components
```

## 🔧 Setup

### Prerequisites

- React 18.0.0 or higher
- React DOM 18.0.0 or higher
- Tailwind CSS 3.4+ (for styling)

### Tailwind CSS Configuration

This library requires Tailwind CSS to be installed and configured in your project. You can extend the library's Tailwind configuration:

```js
// tailwind.config.js
const sharedConfig = require('@windstream/react-shared-components/tailwind.config');

module.exports = {
  ...sharedConfig,
  content: [
    './src/**/*.{js,jsx,ts,tsx}',
    './node_modules/@windstream/react-shared-components/src/**/*.{js,jsx,ts,tsx}',
  ],
};
```

Or import the Tailwind config directly:

```js
// tailwind.config.js
module.exports = {
  presets: [require('@windstream/react-shared-components/tailwind.config')],
  content: [
    './src/**/*.{js,jsx,ts,tsx}',
    './node_modules/@windstream/react-shared-components/src/**/*.{js,jsx,ts,tsx}',
  ],
};
```

## 🎯 Usage

### Basic Usage

```tsx
import { Button, Input, Text } from '@windstream/react-shared-components/core';

function MyComponent() {
  return (
    <div>
      <Text className="heading1">Welcome to Kinetic</Text>
      <Input placeholder="Enter your name" />
      <Button variant="primary">Submit</Button>
    </div>
  );
}
```

### Import Paths

The library provides multiple export paths for different use cases:

```tsx
// Core components (recommended)
import { Button, Input, Text } from '@windstream/react-shared-components/core';

// Utilities
import { cx, clsx } from '@windstream/react-shared-components/utils';

// Styles (required - styles are not automatically included)
import '@windstream/react-shared-components/dist/styles.css';
// Or in CSS: @import '@windstream/react-shared-components/dist/styles.css';

// Tailwind config
const tailwindConfig = require('@windstream/react-shared-components/tailwind.config');
```

### Component Examples

#### Button

```tsx
import { Button } from '@windstream/react-shared-components/core';

// Different variants
<Button variant="primary">Primary Button</Button>
<Button variant="secondary">Secondary Button</Button>
<Button variant="outline">Outline Button</Button>

// Different sizes
<Button className="btn-small">Small</Button>
<Button className="btn-medium">Medium</Button>
<Button className="btn-large">Large</Button>

// With loading state
<Button isLoading>Loading...</Button>

// Full width
<Button fullWidth>Full Width Button</Button>
```

#### Input

```tsx
import { Input, InputField, TextInput } from '@windstream/react-shared-components/core';

// Input, InputField, and TextInput are all aliases for the same component
<Input 
  placeholder="Enter text"
  type="text"
  variant="default"
  size="medium"
/>

<InputField 
  placeholder="Enter text"
  label="Name"
/>

<TextInput 
  placeholder="Enter text"
/>
```

#### Text

```tsx
import { Text } from '@windstream/react-shared-components/core';

<Text className="heading1">Heading 1</Text>
<Text className="body1">Body text</Text>
<Text className="caption">Caption text</Text>
```

### Utilities

The `cx` utility is an enhanced version of `clsx` that intelligently merges Tailwind classes:

```tsx
import { cx, clsx } from '@windstream/react-shared-components/utils';

// cx automatically merges conflicting Tailwind classes
const classes = cx('btn', 'btn-primary', condition && 'btn-secondary');
// If condition is true, btn-secondary will override btn-primary

// clsx is also available for basic class name concatenation
const basicClasses = clsx('btn', condition && 'active');
```

### Hooks

```tsx
import { useBodyScrollLock } from '@windstream/react-shared-components/core';

function Modal({ isOpen }) {
  // Lock body scroll when modal is open
  useBodyScrollLock(isOpen, true);
  
  return (
    // Modal content
  );
}
```

## 🎨 Available Components

All components are available from the `/core` export path:

```tsx
import { 
  Button, 
  Input,
  InputField,
  TextInput,
  Link, 
  List,
  ListItem,
  MaterialIcon, 
  Spinner, 
  Text,
  CallButton,
  Modal,
  Accordion,
  Checkbox,
  Select,
  AlertCard,
  BrandButton,
  Checklist,
  Collapse,
  Divider,
  RadioButton,
  SeeMore,
  SelectPlanButton,
  Skeleton,
  PageSkeleton,
  Tooltip,
  ViewCartButton,
  useBodyScrollLock
} from '@windstream/react-shared-components/core';
```

### Core Components

- **Button** - Versatile button component with multiple variants and sizes
- **Input / InputField / TextInput** - Form input component with validation states (all are aliases)
- **Link** - Accessible link component
- **List / ListItem** - List and list item components
- **MaterialIcon** - Material Design icon component using Material Symbols Rounded
- **Spinner** - Loading spinner component
- **Text** - Typography component with predefined variants (heading1-6, body1-3, etc.)
- **CallButton** - Button component for call-to-action
- **Modal** - Modal dialog component with customizable size, shape, and animations
- **Accordion** - Collapsible accordion component
- **Checkbox** - Checkbox input component
- **Select** - Select dropdown component (powered by react-select)
- **AlertCard** - Alert notification card component
- **BrandButton** - Branded button variant with responsive sizing
- **Checklist** - Checklist component
- **Collapse** - Collapsible content component
- **Divider** - Divider/separator component
- **RadioButton** - Radio button input component
- **SeeMore** - Expandable content component
- **SelectPlanButton** - Plan selection button
- **Skeleton / PageSkeleton** - Loading skeleton components
- **Tooltip** - Tooltip component
- **ViewCartButton** - Shopping cart button component

### Custom Hooks

- **useBodyScrollLock** - Hook to lock/unlock body scroll (useful for modals)

### Component Variants

Each component comes with multiple variants and sizes to fit different use cases:

- **Variants**: default, primary, secondary, outline, unstyled
- **Sizes**: small (btn-small), medium (btn-medium), large (btn-large), x-large (btn-x-large)
- **States**: loading, disabled, error, success

### Typography Variants

The `Text` component supports the following typography variants via className:

- **Headings**: `heading1`, `heading2`, `heading3`, `heading4`, `heading5`, `heading6`
- **Subheadings**: `subheading1`, `subheading2`, `subheading3`, `subheading4`, `subheading5`, `subheading6`
- **Body**: `body1`, `body2`, `body3`
- **Labels**: `label1`, `label2`, `label3`, `label4`, `label5`, `label6`
- **Other**: `footnote`, `micro`

## 🎨 Design System

This library follows the Kinetic design system with comprehensive design tokens:

### Color System

- **Brand Colors**: Primary brand color (#24A76A) with variants (accent, active, hover, disabled, etc.)
- **Semantic Colors**: Success, critical (error), info, inverse
- **Surface Colors**: Background fills, surfaces with states (active, hover, selected, disabled)
- **Text Colors**: Default, brand, critical, secondary, inverse, disabled
- **Border Colors**: Default, brand, critical, focus, hover, disabled
- **Icon Colors**: Brand, critical, default, info, inverse, secondary, success

### Typography

- **Font Families**: 
  - Sans-serif (configurable via CSS variable `--win-site-font`)
  - Material Symbols Rounded (for icons)
  - Figtree (for body text)
- **Font Sizes**: Comprehensive scale from micro (12px) to heading1 (48px)
- **Line Heights**: Standardized line heights for optimal readability

### Spacing & Layout

- **Spacing Scale**: Custom spacing values (1.5, 2, 3, 4, 4.5, 6, 7, 13, 15, 17, 18, 26)
- **Border Radius**: Custom radius values (2.5, 3.5, 2xl, 2.5xl, 4xl)
- **Shadows**: drop, light, cardDrop, card

### Responsive Breakpoints

- `sm`: 640px
- `md`: 768px
- `lg`: 1024px
- `xl`: 1280px
- `max`: 1200px

## 🔧 Development

### Prerequisites

- Node.js 16+
- npm 7+ or yarn 1.22+

### Setup

```bash
# Clone the repository
git clone <repository-url>
cd kinetic-react-shared-components

# Install dependencies
npm install

# Start development mode (watch mode)
npm run dev

# Build the library
npm run build

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Run linting
npm run lint

# Fix linting issues
npm run lint:fix

# Format code
npm run format

# Check code formatting
npm run format:check

# Type check
npm run type-check

# Start Storybook (component documentation)
npm run storybook

# Build Storybook
npm run build-storybook

# Clean build artifacts
npm run clean
```

### Project Structure

```
src/
├── components/          # React components
│   ├── accordion/      # Accordion component
│   ├── alert-card/     # AlertCard component
│   ├── brand-button/   # BrandButton component
│   ├── button/         # Button component
│   ├── call-button/    # CallButton component
│   ├── checkbox/       # Checkbox component
│   ├── checklist/      # Checklist component
│   ├── collapse/       # Collapse component
│   ├── divider/        # Divider component
│   ├── input/          # Input component
│   ├── link/           # Link component
│   ├── list/           # List components
│   ├── material-icon/  # Icon component
│   ├── modal/          # Modal component
│   ├── radio-button/   # RadioButton component
│   ├── see-more/       # SeeMore component
│   ├── select/         # Select component
│   ├── select-plan-button/ # SelectPlanButton component
│   ├── skeleton/       # Skeleton component
│   ├── spinner/        # Spinner component
│   ├── text/           # Text component
│   ├── tooltip/        # Tooltip component
│   └── view-cart-button/ # ViewCartButton component
├── hooks/              # Custom React hooks
├── styles/             # Global styles and Tailwind config
├── utils/              # Utility functions
└── index.ts            # Main export file (exports all components)
```

### Building

The library is built using Rollup with the following outputs:

- **CommonJS**: `dist/index.js` and `dist/utils/index.js`
- **ES Modules**: `dist/index.esm.js` and `dist/utils/index.esm.js`
- **TypeScript declarations**: `dist/index.d.ts`, `dist/core.d.ts`, and `dist/utils/index.d.ts`
- **Styles**: `dist/styles.css` (extracted and minified)

All components are exported from a single entry point (`src/index.ts`), which allows for:
- Simplified build process
- Consistent import path: `@windstream/react-shared-components/core`
- Tree-shaking support for optimal bundle sizes
- Separate utils export path for utility-only imports

### Package Exports

The package provides the following export paths:

- `@windstream/react-shared-components/core` - All components and hooks
- `@windstream/react-shared-components/utils` - Utility functions (cx, clsx)
- `@windstream/react-shared-components/styles.css` - Compiled CSS styles
- `@windstream/react-shared-components/tailwind.config` - Tailwind configuration

## 📦 Publishing

### Prerequisites

Before publishing the package, ensure you have:

1. **npm account**: An account on npmjs.com with access to the `@windstream` organization
2. **Authentication**: Logged in to npm via `npm login` or using an authentication token
3. **Organization access**: Permission to publish packages under the `@windstream` scope

### Publishing Steps

1. **Ensure you're authenticated**:
   ```bash
   npm login
   # Or verify your authentication
   npm whoami
   ```

2. **Update the version** in `package.json`:
   ```bash
   # For patch version (0.0.4 -> 0.0.5)
   npm version patch
   
   # For minor version (0.0.4 -> 0.1.0)
   npm version minor
   
   # For major version (0.0.4 -> 1.0.0)
   npm version major
   ```
   
   Or manually update the `version` field in `package.json` and commit the change.

3. **Build the package**:
   ```bash
   npm run build
   ```
   
   This will:
   - Clean the `dist` directory
   - Build CommonJS and ES Module outputs
   - Generate TypeScript declarations
   - Extract and minify CSS styles

4. **Verify the build**:
   ```bash
   # Check that dist directory contains all necessary files
   ls -la dist/
   ```
   
   Ensure the following files exist:
   - `dist/index.js` (CommonJS)
   - `dist/index.esm.js` (ES Modules)
   - `dist/index.d.ts` (TypeScript declarations)
   - `dist/core.d.ts` (Core types)
   - `dist/utils/index.js` (Utils CommonJS)
   - `dist/utils/index.esm.js` (Utils ES Modules)
   - `dist/utils/index.d.ts` (Utils types)
   - `dist/styles.css` (Compiled CSS)

5. **Run tests** (optional but recommended):
   ```bash
   npm test
   npm run type-check
   ```

6. **Publish to npm**:
   ```bash
   # Dry run to see what would be published
   npm publish --dry-run
   
   # Publish to npm
   npm publish --access public
   ```
   
   Note: The `--access public` flag is required for scoped packages (`@windstream/...`) when publishing to the public npm registry.

7. **Create a git tag** (if you used `npm version`, this is done automatically):
   ```bash
   # If you manually updated the version, create and push the tag
   git tag v0.0.4
   git push origin v0.0.4
   ```

8. **Push changes to repository**:
   ```bash
   git push origin main
   ```

### Version Management

Follow [Semantic Versioning](https://semver.org/) (semver):

- **MAJOR** version (1.0.0): Breaking changes
- **MINOR** version (0.1.0): New features (backward compatible)
- **PATCH** version (0.0.5): Bug fixes (backward compatible)

### Publishing Checklist

Before publishing, verify:

- [ ] All tests pass (`npm test`)
- [ ] Type checking passes (`npm run type-check`)
- [ ] Linting passes (`npm run lint`)
- [ ] Build completes successfully (`npm run build`)
- [ ] Version number is updated in `package.json`
- [ ] README is up to date
- [ ] All changes are committed
- [ ] You're logged in to npm (`npm whoami`)

## 🧪 Testing

The library uses Jest and React Testing Library for testing:

```bash
# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage
```

Test files should be named `*.test.ts` or `*.test.tsx` and placed alongside the components they test.

## 📝 Contributing

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

### Development Guidelines

- Follow the existing code style and conventions
- Write tests for new components and features
- Update documentation for any API changes
- Ensure all components are accessible
- Follow the established component structure

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🤝 Support

For support and questions:

- Create an issue in the GitHub repository
- Contact the Kinetic development team
- Check the documentation and examples

## 🔄 Changelog

### v0.0.4
- Current version
- 23+ React components with full TypeScript support
- Comprehensive design system with Tailwind CSS
- Material Symbols Rounded icon support
- Storybook integration for component documentation
- Custom hooks (useBodyScrollLock)
- Utility functions (cx, clsx) with Tailwind class merging
- Multiple export paths (core, utils, styles, tailwind.config)
- CommonJS and ES Module builds
- Full type definitions

### Components Included
- **Form Components**: Button, Input, Checkbox, RadioButton, Select
- **Layout Components**: List, ListItem, Divider, Collapse, Accordion
- **Feedback Components**: Spinner, Skeleton, PageSkeleton, AlertCard, Tooltip
- **Navigation Components**: Link, Modal, SeeMore
- **Specialized Components**: CallButton, BrandButton, SelectPlanButton, ViewCartButton
- **Typography**: Text component with comprehensive variant system
- **Icons**: MaterialIcon component

## 📚 Additional Resources

- [React Documentation](https://reactjs.org/)
- [Tailwind CSS Documentation](https://tailwindcss.com/)
- [TypeScript Documentation](https://www.typescriptlang.org/)
- [Storybook Documentation](https://storybook.js.org/)
- [Material Symbols](https://fonts.google.com/icons)
- [React Testing Library](https://testing-library.com/react)
- [Jest Documentation](https://jestjs.io/)

## 📦 Package Information

- **Package Name**: `@windstream/react-shared-components`
- **Current Version**: `0.0.4`
- **License**: MIT
- **Repository**: [GitHub](https://github.com/kinetic/react-shared-components)
- **Issues**: [GitHub Issues](https://github.com/kinetic/react-shared-components/issues)

## 🔗 Related Packages

This package is part of the Kinetic ecosystem and works seamlessly with:
- Kinetic design system tokens
- Kinetic applications and services
- Other Windstream/Kinetic React packages


## Publishing Quick steps
- Commit  -> Git commit
- version -> npm version patch
- build -> npm run build
- publish -> npm publish --access public

## npm pack usage in local
- build -> npm run build
- pack -> npm pack
- reference in app -> relatiev path to teh zip 
- eg: "@windstream/react-shared-components": "../kinetic-react-shared-components/windstream-react-shared-components-0.0.86.tgz",