@shortstravelmgmt/component-lib 0.1.0

package/README.md

@@ -0,0 +1,209 @@
+# @shortstravelmgmt/component-lib
+
+A reusable React component library built with Storybook, designed for the STM Hub travel management platform. This library provides a consistent design system with accessible, customizable components organized using [Atomic Design](https://atomicdesign.bradfrost.com/) methodology.
+
+[![npm version](https://badge.fury.io/js/%40shortstravelmgmt%2Fcomponent-lib.svg)](https://www.npmjs.com/package/@shortstravelmgmt/component-lib)
+[![Chromatic](https://github.com/ShortsTravel/component-lib/actions/workflows/chromatic.yml/badge.svg)](https://github.com/ShortsTravel/component-lib/actions/workflows/chromatic.yml)
+[![CI](https://github.com/ShortsTravel/component-lib/actions/workflows/ci.yml/badge.svg)](https://github.com/ShortsTravel/component-lib/actions/workflows/ci.yml)
+
+## 🚀 Features
+
+- **Atomic Design** - Organized into atoms, molecules, organisms, templates, and pages
+- **React 18+** - Built with modern React features
+- **TypeScript** - Full type safety and IntelliSense support
+- **Storybook** - Interactive component documentation and testing
+- **Chromatic** - Visual regression testing and review
+- **Accessible** - WCAG 2.1 AA compliant components
+- **Themeable** - CSS custom properties for easy theming
+- **Tree-shakeable** - Only import what you need
+
+## 📦 Installation
+
+```bash
+npm install @shortstravelmgmt/component-lib
+# or
+yarn add @shortstravelmgmt/component-lib
+# or
+pnpm add @shortstravelmgmt/component-lib
+```
+
+## 🎯 Quick Start
+
+```tsx
+import { 
+  // Atoms
+  Button, 
+  Badge, 
+  Avatar,
+  // Organisms
+  Card, 
+  CardHeader, 
+  CardBody,
+  // Molecules
+  SearchField,
+  FormField,
+} from '@shortstravelmgmt/component-lib';
+import '@shortstravelmgmt/component-lib/styles.css';
+
+function App() {
+  return (
+    <Card>
+      <CardHeader>Trip Details</CardHeader>
+      <CardBody>
+        <Badge variant="success">Confirmed</Badge>
+        <Button variant="primary">View Itinerary</Button>
+      </CardBody>
+    </Card>
+  );
+}
+```
+
+## 🧬 Atomic Design Structure
+
+This library follows [Atomic Design](https://atomicdesign.bradfrost.com/) methodology by Brad Frost:
+
+### 🔵 Atoms
+Basic building blocks - the smallest functional units.
+
+- **Button** - Primary interaction element with variants and sizes
+- **Badge** - Status indicators and labels  
+- **Avatar** - User profile images or initials
+- **Input / Textarea** - Text entry fields
+- **Icons** - Visual symbols (30+ icons)
+
+### 🧪 Molecules
+Simple groups of atoms working together as a unit.
+
+- **SearchField** - Search input with icon, clear button, and submit
+- **FormField** - Label, input, helper text, and error message
+- **NavItem** - Icon, label, and optional badge
+
+### 🦠 Organisms
+Complex components composed of molecules and atoms.
+
+- **Card** - Content container with header, body, and footer
+- **Sidenav** - Collapsible side navigation
+- **Topbar** - Application header with account selector
+
+### 📄 Templates
+Page-level layouts defining content structure.
+
+- **AppLayout** - Main application layout with Sidenav + Topbar
+
+### 📱 Pages
+Templates with real representative content.
+
+- **DashboardPage** - Example dashboard with stats and data tables
+
+### Icons
+- Travel icons (Plane, Car, Hotel, Bus, Rail, Limo)
+- UI icons (Search, Filter, Calendar, Download, etc.)
+- Navigation icons (Chevrons, Arrows)
+- Status icons (Check, Warning, X)
+
+## 📚 Documentation
+
+Visit our [Storybook](https://storybook.stm-hub.com) for interactive documentation, examples, and API reference.
+
+## 🎨 Theming
+
+The library uses CSS custom properties for theming. Override them in your CSS:
+
+```css
+:root {
+  /* Primary colors */
+  --color-primary: #0A53EF;
+  --color-primary-dark: #1A43D1;
+  --color-primary-light: #E6ECFB;
+
+  /* Neutral colors */
+  --color-basecolor: #F5F5F5;
+  --border-color: #EDEDED;
+  
+  /* Typography */
+  --font-family-base: 'Roboto Flex', system-ui, sans-serif;
+}
+```
+
+See `src/styles/tokens.css` for the complete list of design tokens.
+
+## 🛠 Development
+
+### Prerequisites
+
+- Node.js 18+
+- npm 9+
+
+### Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/ShortsTravel/component-lib.git
+cd component-lib
+
+# Install dependencies
+npm install
+
+# Start Storybook
+npm run storybook
+```
+
+### Available Scripts
+
+| Script | Description |
+|--------|-------------|
+| `npm run storybook` | Start Storybook dev server |
+| `npm run build-storybook` | Build static Storybook |
+| `npm run build:lib` | Build the library for publishing |
+| `npm run lint` | Run ESLint |
+| `npm test` | Run tests |
+| `npm run chromatic` | Run visual regression tests |
+
+## 📤 Publishing
+
+The package is automatically published to npm when a release is created:
+
+1. Update version in `package.json`
+2. Create a new GitHub release with the version tag
+3. GitHub Actions will build and publish to npm
+
+### Manual publishing
+
+```bash
+npm run build:lib
+npm publish --access public
+```
+
+## 🔄 CI/CD
+
+- **CI Pipeline** - Runs on every push/PR: lint, typecheck, build
+- **Chromatic** - Visual regression testing on every PR
+- **Publish** - Automatic npm publishing on releases
+
+## 🤝 Contributing
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+### Component Guidelines
+
+- Use TypeScript for all components
+- Include JSDoc comments for props
+- Create Storybook stories for all variants
+- Ensure accessibility (ARIA labels, keyboard navigation)
+- Use CSS Modules for styling
+- Export types alongside components
+
+## 📄 License
+
+MIT © [Short's Travel Management](https://stm-hub.com)
+
+## 🔗 Links
+
+- [Storybook Documentation](https://storybook.stm-hub.com)
+- [Chromatic Visual Tests](https://www.chromatic.com/library?appId=YOUR_APP_ID)
+- [npm Package](https://www.npmjs.com/package/@shortstravelmgmt/component-lib)
+- [GitHub Repository](https://github.com/ShortsTravel/component-lib)