@hotelcard/ui 0.0.2

package/README.md

@@ -0,0 +1,410 @@
+# @hotelcard/ui
+
+Shared UI component library for HotelCard applications (mobile app and website).
+
+## Quick Start
+
+### Installation
+
+```bash
+# In your project
+npm install @hotelcard/ui
+
+# Or with local development (file: protocol)
+"@hotelcard/ui": "file:../hotelcard-monorepo/packages/ui"
+```
+
+### Import Components
+
+```tsx
+import { Button, Badge, Rating } from '@hotelcard/ui';
+import type { ButtonProps, BadgeProps } from '@hotelcard/ui';
+```
+
+### Import Styles (REQUIRED)
+
+You **must** import the CSS in your app's entry point (e.g., `main.tsx`):
+
+```tsx
+// main.tsx or App.tsx
+import '@hotelcard/ui/dist/index.css';
+```
+
+**If you skip this step, components will render without styling!**
+
+---
+
+## Available Components
+
+### Button
+
+```tsx
+import { Button } from '@hotelcard/ui';
+
+// Primary button (default)
+<Button onClick={handleClick}>Submit</Button>
+
+// Secondary button
+<Button variant="secondary">Cancel</Button>
+
+// Small size
+<Button size="small">Small Button</Button>
+
+// Link style
+<Button variant="link">Learn More</Button>
+
+// With icons
+<Button leftIcon={<SearchIcon />}>Search</Button>
+
+// Icon-only button
+<Button iconOnly><HeartIcon /></Button>
+```
+
+**Props:**
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `variant` | `'primary' \| 'secondary' \| 'link'` | `'primary'` | Button style |
+| `size` | `'small' \| 'medium'` | `'medium'` | Button size |
+| `iconOnly` | `boolean` | `false` | Icon-only circular button |
+| `leftIcon` | `ReactNode` | - | Icon on the left |
+| `rightIcon` | `ReactNode` | - | Icon on the right |
+| `disabled` | `boolean` | `false` | Disabled state |
+
+### Badge
+
+```tsx
+import { Badge } from '@hotelcard/ui';
+
+// Discount badge
+<Badge color="primary" size="small" style="heavy">
+  -50%
+</Badge>
+
+// Status badge
+<Badge color="success" style="light">
+  Available
+</Badge>
+```
+
+**Props:**
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `color` | `'primary' \| 'secondary' \| 'neutral' \| 'success' \| 'warning'` | `'primary'` | Badge color |
+| `size` | `'small' \| 'large'` | `'large'` | Badge size |
+| `style` | `'heavy' \| 'light'` | `'heavy'` | Solid or light background |
+
+### Rating
+
+```tsx
+import { Rating } from '@hotelcard/ui';
+
+// Star rating
+<Rating value={4.5} />
+
+// Show numeric value
+<Rating value={4.5} showValue />
+
+// Different sizes
+<Rating value={3} size="small" />
+<Rating value={3} size="large" />
+```
+
+**Props:**
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value` | `number` | - | Rating value (0-5) |
+| `maxValue` | `number` | `5` | Maximum stars |
+| `showValue` | `boolean` | `false` | Show numeric value |
+| `size` | `'small' \| 'medium' \| 'large'` | `'medium'` | Star size |
+
+### Icons
+
+```tsx
+import { HeartIcon, StarIcon, ChevronLeftIcon, ChevronRightIcon, PinIcon } from '@hotelcard/ui';
+
+<HeartIcon filled={false} size={24} />
+<StarIcon size={9} />
+<ChevronLeftIcon size={20} />
+<ChevronRightIcon size={20} />
+<PinIcon size={16} />
+```
+
+---
+
+## CSS Variables (Theming)
+
+Components use CSS variables for theming. Your app should define these in a global CSS file:
+
+```css
+:root {
+  /* Colors */
+  --background-action-primary-idle: #C81E4C;
+  --background-action-primary-hover: #a3183d;
+  --content-action-primary-inverse-idle: #ffffff;
+  --content-general-primary: #1F2937;
+  --content-general-secondary: #6B7280;
+  --border-general-divider: #D1D5DB;
+
+  /* Typography */
+  --font-primary: system-ui, -apple-system, sans-serif;
+  --font-weight-medium: 500;
+  --font-weight-semibold: 600;
+
+  /* Spacing & Sizing */
+  --radius-lg: 12px;
+  --radius-full: 9999px;
+
+  /* ... see tokens.css for full list */
+}
+```
+
+Components have fallback values, so they work without custom CSS variables.
+
+---
+
+## Types
+
+```tsx
+import type {
+  ButtonProps,
+  BadgeProps,
+  RatingProps,
+} from '@hotelcard/ui';
+```
+
+---
+
+## Development Guide
+
+### Project Structure
+
+```
+packages/ui/
+├── src/
+│   ├── components/
+│   │   ├── Button/
+│   │   │   ├── Button.tsx
+│   │   │   ├── Button.css       # Prefixed classes (hc-btn-*)
+│   │   │   ├── Button.types.ts
+│   │   │   └── index.ts
+│   │   ├── Badge/
+│   │   ├── Rating/
+│   │   └── icons/
+│   └── index.ts                  # Main exports
+├── dist/                         # Built output
+├── package.json
+└── tsup.config.ts
+```
+
+### Adding a New Component
+
+1. **Create component folder:**
+   ```
+   src/components/NewComponent/
+   ├── NewComponent.tsx
+   ├── NewComponent.css
+   ├── NewComponent.types.ts
+   └── index.ts
+   ```
+
+2. **Use prefixed CSS classes** (NOT CSS modules):
+   ```tsx
+   // NewComponent.tsx
+   import './NewComponent.css';
+
+   const cx = (className: string) => `hc-newcomp-${className}`;
+
+   export const NewComponent = () => (
+     <div className={cx('container')}>
+       <span className={cx('text')}>Hello</span>
+     </div>
+   );
+   ```
+
+3. **Define CSS with prefixes:**
+   ```css
+   /* NewComponent.css */
+   .hc-newcomp-container {
+     display: flex;
+     padding: var(--size-rem-1, 16px);
+   }
+
+   .hc-newcomp-text {
+     color: var(--content-general-primary, #1F2937);
+   }
+   ```
+
+4. **Export from index.ts:**
+   ```tsx
+   // src/index.ts
+   export { NewComponent } from './components/NewComponent';
+   export type { NewComponentProps } from './components/NewComponent';
+   ```
+
+5. **Build and test:**
+   ```bash
+   pnpm build
+   ```
+
+### CSS Class Naming Convention
+
+**Why prefixed classes instead of CSS Modules?**
+
+CSS Modules don't work well with tsup bundling - the class name mappings become empty objects. We use prefixed classes instead:
+
+- `hc-btn-*` for Button
+- `hc-badge-*` for Badge
+- `hc-rating-*` for Rating
+
+This prevents conflicts with consuming app's styles while ensuring styles are always applied.
+
+### Building
+
+```bash
+cd packages/ui
+
+# Build once
+pnpm build
+
+# Watch mode for development
+pnpm dev
+```
+
+### Testing Changes Locally
+
+1. Build the package: `pnpm build`
+2. In consuming app, reinstall: `npm install`
+3. Restart dev server if needed
+
+---
+
+## Publishing to NPM
+
+### Prerequisites
+
+1. NPM account with access to `@hotelcard` organization
+2. Logged in: `npm login`
+
+### Publish Process
+
+```bash
+cd packages/ui
+
+# 1. Make sure everything builds
+pnpm build
+
+# 2. Update version
+npm version patch   # 0.0.2 -> 0.0.3
+# or
+npm version minor   # 0.0.2 -> 0.1.0
+# or
+npm version major   # 0.0.2 -> 1.0.0
+
+# 3. Publish
+npm publish --access public
+
+# 4. Commit version bump
+git add package.json
+git commit -m "chore(ui): release v0.0.3"
+git push
+```
+
+### Version Guidelines
+
+- `patch` (0.0.x): Bug fixes, style tweaks
+- `minor` (0.x.0): New components, new features
+- `major` (x.0.0): Breaking changes (API changes, removed props)
+
+---
+
+## Using in Apps
+
+### hotelcard-app-v2 (Mobile App)
+
+```tsx
+// src/main.tsx
+import '@hotelcard/ui/dist/index.css';  // REQUIRED
+
+// src/library/index.ts (barrel export)
+export { Button, Badge } from '@hotelcard/ui';
+export type { ButtonProps, BadgeProps } from '@hotelcard/ui';
+
+// src/pages/SomePage.tsx
+import { Button, Badge } from '@/library';
+```
+
+### hotelcard-ui (Website)
+
+```tsx
+// src/main.tsx or app entry
+import '@hotelcard/ui/dist/index.css';  // REQUIRED
+
+// Use directly
+import { Button, Badge } from '@hotelcard/ui';
+```
+
+### Updating the Package
+
+```bash
+# After a new version is published
+npm update @hotelcard/ui
+
+# Or for local development
+rm -rf node_modules/.cache
+npm install
+```
+
+---
+
+## Troubleshooting
+
+### "Components render without styles"
+
+Make sure you imported the CSS:
+```tsx
+import '@hotelcard/ui/dist/index.css';
+```
+
+### "Module not found" errors
+
+```bash
+# Clear cache and reinstall
+rm -rf node_modules/.cache
+npm install
+```
+
+### "Types not found"
+
+Make sure you're importing types with `type`:
+```tsx
+import type { ButtonProps } from '@hotelcard/ui';
+```
+
+### Local changes not reflecting
+
+```bash
+# In @hotelcard/ui
+pnpm build
+
+# In consuming app
+npm install
+# Restart dev server
+```
+
+---
+
+## Component Checklist
+
+When adding/modifying components:
+
+- [ ] Uses prefixed CSS classes (not CSS modules)
+- [ ] All CSS variables have fallback values
+- [ ] Props are typed in `.types.ts`
+- [ ] Exported from `src/index.ts`
+- [ ] Build passes: `pnpm build`
+- [ ] Tested in consuming app
+- [ ] README updated if new component
+
+## License
+
+MIT