@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

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:

// 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:

// 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

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:

// 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

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

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

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:

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

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:

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

# 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

🧪 Testing

The library uses Jest and React Testing Library for testing:

# 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 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.2

• 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
• Tailwind CSS Documentation
• TypeScript Documentation
• Storybook Documentation
• Material Symbols
• React Testing Library
• Jest Documentation

📦 Package Information

• Package Name: @windstream/react-shared-components
• Current Version: 0.0.2
• License: MIT
• Repository: GitHub
• Issues: GitHub 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