@hotelcard/ui 0.0.12 → 0.0.15

package/README.md

@@ -29,36 +29,61 @@ npm install react react-dom
 ## Quick Start
 
 ```tsx
-import { Button, Card, Badge } from '@hotelcard/ui';
+import { HotelCardUIProvider, Button, HotelCard } from '@hotelcard/ui';
 
 // Import styles (required - do this once in your app entry)
-import '@hotelcard/ui/dist/index.css';
+import '@hotelcard/ui/styles.css';
 
 function App() {
   return (
-    <div>
+    <HotelCardUIProvider locale="de" currency="CHF">
       <Button variant="primary" onClick={() => alert('Clicked!')}>
         Book Now
       </Button>
 
-      <Card
-        image="https://example.com/hotel.jpg"
-        title="Hotel Schweizerhof"
-        location="Luzern, Switzerland"
-        stars={5}
-        price="CHF 195"
-        originalPrice="CHF 390"
-        onClick={() => console.log('Card clicked')}
-      >
-        <Badge color="primary" size="small">-50%</Badge>
-      </Card>
-    </div>
+      <HotelCard
+        hotel={hotelData}
+        onFavoriteClick={() => toggleFavorite()}
+        onContentClick={() => navigate('/hotel/123')}
+      />
+    </HotelCardUIProvider>
   );
 }
 ```
 
 ---
 
+## Context Provider (Required for Translations)
+
+Wrap your app with `HotelCardUIProvider` to enable translations and configuration:
+
+```tsx
+import { HotelCardUIProvider } from '@hotelcard/ui';
+
+<HotelCardUIProvider
+  locale="de"       // 'de' | 'en' | 'fr' | 'it'
+  currency="CHF"    // Currency code
+  isDesktop={false} // Responsive mode
+>
+  <App />
+</HotelCardUIProvider>
+```
+
+### Translations
+
+The package includes built-in translations for `de`, `en`, `fr`, and `it` locales. These are automatically applied based on the `locale` prop. Components like `HotelCard`, `GuestContent`, and `WhenContent` use these translations internally.
+
+**Custom translations** (optional):
+
+```tsx
+<HotelCardUIProvider
+  locale="de"
+  t={(key, fallback) => myI18n.t(key) || fallback}  // Custom translation function
+>
+```
+
+---
+
 ## Available Components
 
 ### UI Components
@@ -69,7 +94,6 @@ function App() {
 | `Input` | Text input with label, helper text, and validation |
 | `Badge` | Status and discount badges |
 | `Card` | Hotel card component |
-| `CompactCard` | Compact hotel card for carousels |
 | `Chip` | Filter and tag chips |
 | `Checkbox` | Checkbox with label |
 | `RadioButton` | Radio button with label |
@@ -78,9 +102,16 @@ function App() {
 | `Dropdown` | Select dropdown |
 | `Modal` | Modal dialog |
 | `SectionHeader` | Section title with "Show all" button |
-| `WhenContent` | Date/month picker for search (accepts labels as props) |
+| `Block` | Content block with title and optional icon |
+| `ReviewCard` | Guest review card with rating and text |
+| `FAQ` | Expandable FAQ accordion |
+| `Benefits` | Benefits list with icons |
+| `Pin` | Location pin marker |
+| `DateSelector` | Date selector container component |
+| `WhenContent` | Date/month picker for search |
 | `DualCalendar` | Calendar component for date range selection |
 | `GuestContent` | Guest selector with adults, children (with ages), and pet toggle |
+| `HotelCard` | Hotel card for search results with image carousel, rating, and pricing |
 
 ### Icons
 
@@ -189,18 +220,11 @@ import { WhenContent } from '@hotelcard/ui';
   variant="dropdown"
   showApplyButton={true}
   onApply={() => closeDropdown()}
-  labels={{
-    dates: 'Dates',           // Tab label
-    flexible: 'Flexible',     // Tab label
-    anytime: 'Anytime',       // Button label
-    selectMonths: 'When do you want to travel?',
-    apply: 'Apply',           // Button label
-  }}
   locale="de"  // Optional: 'de', 'en', 'fr', 'it'
 />
 ```
 
-**Note**: All text labels are passed as props. The consuming app provides translated strings.
+Translations (dates, flexible, anytime, etc.) are handled automatically via `HotelCardUIProvider`.
 
 ### GuestContent (Guest Selector)
 
@@ -220,22 +244,49 @@ const [petFilter, setPetFilter] = useState(0);
   petFilter={petFilter}
   onPetChange={setPetFilter}
   showPetToggle={true}
-  labels={{
-    adults: 'Adults',
-    children: 'Children',
-    pet: 'Pet',
-    ageOfChild: 'Age of child',
-    age: 'Age',
-    decreaseAdults: 'Decrease adults',
-    increaseAdults: 'Increase adults',
-    decreaseChildren: 'Decrease children',
-    increaseChildren: 'Increase children',
-    togglePets: 'Toggle pets',
-  }}
 />
 ```
 
-**Note**: All text labels are passed as props. The consuming app provides translated strings.
+Translations (Adults, Children, Pet, etc.) are handled automatically via `HotelCardUIProvider`.
+
+### HotelCard
+
+```tsx
+import { HotelCard, type HotelCardHotel } from '@hotelcard/ui';
+
+const hotel: HotelCardHotel = {
+  id: '123',
+  name: 'Grand Hotel Belvedere',
+  slug: 'grand-hotel-belvedere',
+  stars: 5,
+  isSuperior: true,
+  rating: 4.5,
+  location: 'Lauterbrunnen, Switzerland',
+  images: ['/hotel1.jpg', '/hotel2.jpg'],
+  isFavorite: false,
+  benefits: [
+    { id: 'free-breakfast', label: 'Free breakfast' },
+    { id: 'free-cancellation', label: 'Free cancellation' },
+  ],
+  isAvailable: true,
+  currency: 'CHF',
+  price: {
+    current: 195,
+    original: 390,
+    discount: 50,
+  },
+  usp: 'Best price guarantee',
+  badges: ['New'],
+};
+
+<HotelCard
+  hotel={hotel}
+  onFavoriteClick={() => toggleFavorite(hotel.id)}
+  onContentClick={() => navigate(`/hotel/${hotel.slug}`)}
+/>
+```
+
+Translations (rating labels, price text, etc.) are handled automatically via `HotelCardUIProvider`.
 
 ### Checkbox & RadioButton
 
@@ -269,7 +320,6 @@ import type {
   BadgeProps,
   InputProps,
   CardProps,
-  CompactCardProps,
   CheckboxProps,
   RadioButtonProps,
   DropdownProps,
@@ -278,13 +328,32 @@ import type {
   RatingProps,
   DividerProps,
   SectionHeaderProps,
+  BlockProps,
+  ReviewCardProps,
+  FAQProps,
+  FAQItem,
+  BenefitsProps,
+  BenefitItem,
+  PinProps,
+  DateSelectorProps,
   WhenContentProps,
-  WhenContentLabels,
   DateRange,
   GuestContentProps,
-  GuestContentLabels,
   GuestCounts,
   ChildAgeError,
+  HotelCardProps,
+  HotelCardHotel,
+  HotelCardImageProps,
+  HotelCardContentProps,
+
+  // Context Types
+  UIContextValue,
+  HotelCardUIProviderProps,
+  TranslateFunction,
+
+  // Translation Types
+  Locale,
+  TranslationKeys,
 
   // Data Types
   Hotel,
@@ -302,7 +371,7 @@ import type {
 ## Hooks
 
 ```typescript
-import { useDebounce, useResponsive, useWindowData } from '@hotelcard/ui';
+import { useDebounce, useResponsive, useWindowData, useUIContext } from '@hotelcard/ui';
 
 // Debounce a value
 const debouncedSearch = useDebounce(searchTerm, 300);
@@ -312,6 +381,10 @@ const { isDesktop } = useResponsive(); // >= 1024px
 
 // Window/context data
 const { locale, currency } = useWindowData();
+
+// UI Context with translation function
+const { locale, currency, isDesktop, t } = useUIContext();
+t('label.rating-excellent', 'Excellent'); // Returns translated string
 ```
 
 ---
@@ -336,20 +409,18 @@ calculateDiscount(400, 200); // 50
 
 ---
 
-## Context Provider (Optional)
+## Translations
 
-For apps that need shared configuration:
+The package exports bundled translations that can be used directly:
 
-```tsx
-import { HotelCardUIProvider } from '@hotelcard/ui';
+```typescript
+import { translations } from '@hotelcard/ui';
 
-<HotelCardUIProvider
-  locale="de"
-  currency="CHF"
-  isDesktop={false}
->
-  <App />
-</HotelCardUIProvider>
+// Access translations for a specific locale
+console.log(translations.de.form.adults); // "Erwachsene"
+console.log(translations.en.form.adults); // "Adults"
+console.log(translations.fr.form.adults); // "Adultes"
+console.log(translations.it.form.adults); // "Adulti"
 ```
 
 ---
@@ -360,7 +431,7 @@ Components use CSS variables for theming. Import the styles once in your app ent
 
 ```tsx
 // main.tsx or App.tsx
-import '@hotelcard/ui/dist/index.css';
+import '@hotelcard/ui/styles.css';
 ```
 
 ### Customizing with CSS Variables
@@ -400,6 +471,45 @@ Components have built-in fallback values, so they work without custom CSS variab
 
 ---
 
+## Platform Safeguards
+
+This package is designed to work in both web (Next.js) and mobile (Ionic/Capacitor) environments. To maintain platform-agnosticism, the following safeguards are in place:
+
+### Forbidden Imports
+
+ESLint and pre-publish checks will block:
+
+| Import | Reason |
+|--------|--------|
+| `next/router`, `next/image` | Web-only Next.js APIs |
+| `@ionic/react`, `@capacitor/*` | Mobile-only Ionic/Capacitor APIs |
+| `@/*` path aliases | App-specific configuration |
+| `react-native` | Mobile-only framework |
+
+### Forbidden Patterns
+
+| Pattern | Reason | Alternative |
+|---------|--------|-------------|
+| `localStorage.*` | Not available everywhere | Use callback props |
+| `window.location` | Web-only | Use `onNavigate` callback |
+| `useRouter()` | Platform-specific | Use `onClick` callback |
+| `useNavigate()` | Platform-specific | Use `onClick` callback |
+
+### Running Checks
+
+```bash
+pnpm check-imports  # Scan for forbidden patterns
+pnpm lint           # Run ESLint
+```
+
+These checks run automatically before `pnpm publish`.
+
+### Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines on keeping components platform-agnostic.
+
+---
+
 ## License
 
 MIT