@hotelcard/ui 0.0.46 → 0.0.48

package/README.md

@@ -94,6 +94,7 @@ The package includes built-in translations for `de`, `en`, `fr`, and `it` locale
 | `Input` | Text input with label, helper text, and validation |
 | `Badge` | Status and discount badges |
 | `Card` | Hotel card component |
+| `BaseCard` | Composable card primitives (container, image, content) for building custom cards |
 | `Chip` | Filter and tag chips |
 | `Checkbox` | Checkbox with label |
 | `RadioButton` | Radio button with label |
@@ -130,18 +131,21 @@ The package includes built-in translations for `de`, `en`, `fr`, and `it` locale
 
 | Component | Description |
 |-----------|-------------|
+| `FilterPanel` | Complete filter sidebar with all filter sections (regions, price, category, etc.) |
+| `FilterModal` | Modal wrapper for FilterPanel (web overlay style) |
 | `FilterCheckboxItem` | Base checkbox item for filters |
 | `CollapsibleFilterSection` | Expandable/collapsible filter section wrapper |
-| `PriceRangeFilter` | Price range slider filter |
-| `HotelCategoryFilter` | Hotel star rating filter (1-5 stars) |
-| `ReviewsFilter` | Guest review rating filter |
-| `ExperienceFilter` | Experience/theme filter |
-| `RegionsFilter` | Region/location filter with search |
-| `CheckboxFilter` | Generic checkbox filter component |
-| `MealsFilter` | Meal plan filter (breakfast, half-board, etc.) |
-| `TransportFilter` | Transport options filter |
-| `WellnessFilter` | Wellness amenities filter |
-| `SelectedFiltersRow` | Display row showing active filters with remove option |
+| `PriceRangeFilter` | Price range slider with histogram |
+| `HotelCategoryFilter` | Hotel star rating filter (1-5 stars, Swiss Lodge, No category) |
+| `ReviewsFilter` | Guest review rating filter (Excellent, Very Good, Good, Fair, No rating) |
+| `ExperienceFilter` | Experience/theme filter with counts |
+| `RegionsFilter` | Accordion-style region filter with country/sub-region hierarchy |
+| `MealsFilter` | Meal options filter (breakfast, restaurant) |
+| `TransportFilter` | Transport options filter (parking, EV charging) |
+| `WellnessFilter` | Wellness amenities filter (pool, sauna, massage) |
+| `SelectedFiltersRow` | Display row showing active filters as removable chips |
+| `FilterMinimap` | Map preview with "View in Map" button |
+| `FilterSkeleton` | Loading skeleton for filter panel |
 
 ### Icons
 
@@ -222,6 +226,49 @@ import { Card } from '@hotelcard/ui';
 />
 ```
 
+### BaseCard (Composable Card Primitives)
+
+Use `BaseCard`, `BaseCardImage`, and `BaseCardContent` to build custom cards with consistent styling:
+
+```tsx
+import { BaseCard, BaseCardImage, BaseCardContent } from '@hotelcard/ui';
+
+// Custom booking card using BaseCard primitives
+<BaseCard hoverable onClick={() => navigateToBooking()}>
+  <BaseCardImage
+    src={hotel.imageUrl}
+    alt={hotel.name}
+    height={200}
+    topLeftSlot={<StatusBadge status="confirmed" />}
+    topRightSlot={<FavoriteButton />}
+  />
+  <BaseCardContent padding="large">
+    <h3>{hotel.name}</h3>
+    <p>{hotel.location}</p>
+    <div>Check-in: {checkInDate}</div>
+  </BaseCardContent>
+</BaseCard>
+
+// With aspect ratio instead of fixed height
+<BaseCard borderRadius={16}>
+  <BaseCardImage
+    src={hotel.imageUrl}
+    alt={hotel.name}
+    aspectRatio="16/9"
+    showGradient={true}
+    bottomSlot={<ImageIndicatorDots count={3} active={0} />}
+  />
+  <BaseCardContent padding="medium">
+    {/* Your content */}
+  </BaseCardContent>
+</BaseCard>
+```
+
+BaseCard provides:
+- **BaseCard**: Container with border, radius, shadow, hover effects
+- **BaseCardImage**: Image with overlay slots (top-left, top-right, center, bottom)
+- **BaseCardContent**: Content area with configurable padding ('none' | 'small' | 'medium' | 'large')
+
 ### Modal
 
 ```tsx
@@ -440,7 +487,119 @@ import { SearchControlsBar, type SearchParams, type ViewMode } from '@hotelcard/
 />
 ```
 
-### Filter Components
+### FilterPanel (Complete Filter Sidebar)
+
+```tsx
+import {
+  FilterPanel,
+  type FilterState,
+  type FilterPanelProps,
+  type RegionOption,
+  type ThemeAggregation,
+  type FilterOption,
+} from '@hotelcard/ui';
+
+// FilterPanel displays filter data from search API aggregations
+// It does NOT have default data - pass real aggregation data from your search response
+<FilterPanel
+  // Filter change callback
+  onFilterChange={(filters: FilterState) => {
+    // filters: { regions, experiences, priceRange, discounts, options, meals, categories, ratings, transport, wellness }
+    applyFilters(filters);
+  }}
+
+  // Optional: Show map preview with "View in Map" button
+  onViewMap={() => setViewMode('map')}
+
+  // Price data from API aggregations (required for price filter to display)
+  // Round to nearest 10 for clean slider values
+  minPrice={Math.floor(aggregations.price_stats.min / 10) * 10}
+  maxPrice={Math.ceil(aggregations.price_stats.max / 10) * 10}
+  priceHistogram={aggregations.price_histogram.map(b => b.count)}
+
+  // Region data from API
+  regions={regionOptions}
+  themes={experienceThemes}  // Pre-translated theme names from API
+  filterOptions={filterOptions}  // Pre-translated filter options from API
+
+  // Counts for each filter option (from search aggregations)
+  // Use exact property names from API response:
+  discountCounts={aggregations.discount_counts}
+  optionsCounts={aggregations.options_counts}
+  categoryCounts={categoryCounts}  // Transform from star_ratings array
+  mealsCounts={aggregations.meals_counts}
+  reviewsCounts={aggregations.reviews_counts}
+  transportCounts={aggregations.transport_counts}
+  wellnessCounts={aggregations.wellness_counts}
+  servicesCounts={aggregations.services_counts}
+
+  // Controlled selected values (sync with URL params)
+  selectedDiscounts={['50']}
+  selectedCategories={['4', '5']}
+  selectedRegions={['region_1']}
+  selectedPriceRange={{ min: 100, max: 300 }}
+
+  // Loading state - shows skeleton when true
+  isLoading={isLoading}
+/>
+```
+
+### FilterModal (Modal Wrapper)
+
+For web apps, use `FilterModal` which provides the overlay/modal styling:
+
+```tsx
+import { FilterModal, type FilterModalProps, type SelectedFilter } from '@hotelcard/ui';
+
+<FilterModal
+  isOpen={isFilterModalOpen}
+  onClose={() => setIsFilterModalOpen(false)}
+  resultCount={totalResults}
+  selectedFilters={activeFilterChips}
+  onRemoveFilter={(filter: SelectedFilter) => removeFilter(filter)}
+  onClearAllFilters={() => clearAllFilters()}
+
+  // Pass through ALL FilterPanel props - data comes from search aggregations
+  onFilterChange={handleFilterChange}
+  minPrice={priceStats.minPrice}
+  maxPrice={priceStats.maxPrice}
+  priceHistogram={priceStats.histogram.length > 0 ? priceStats.histogram : undefined}
+  regions={regions}
+  themes={themes}
+  filterOptions={filterOptions}
+  discountCounts={aggregations.discount_counts}
+  optionsCounts={aggregations.options_counts}
+  categoryCounts={categoryCounts}
+  mealsCounts={aggregations.meals_counts}
+  reviewsCounts={aggregations.reviews_counts}
+  transportCounts={aggregations.transport_counts}
+  wellnessCounts={aggregations.wellness_counts}
+  servicesCounts={aggregations.services_counts}
+  selectedDiscounts={selectedDiscounts}
+  selectedCategories={selectedCategories}
+  selectedRegions={selectedRegions}
+  selectedPriceRange={selectedPriceRange}
+  // ... other selected* props
+/>
+```
+
+**Important:** FilterPanel and FilterModal do NOT have hardcoded default data. All filter data (price range, counts, etc.) must come from your search API aggregations. Pass `undefined` for `priceHistogram` when data is loading to show skeleton state.
+
+For Ionic apps, create your own `IonModal` wrapper and pass props through to `FilterPanel`:
+
+```tsx
+import { IonModal } from '@ionic/react';
+import { FilterPanel, type FilterPanelProps } from '@hotelcard/ui';
+
+// Simple pass-through wrapper
+const FilterModal = ({ isOpen, onClose, ...filterPanelProps }) => (
+  <IonModal isOpen={isOpen} onDidDismiss={onClose}>
+    <FilterPanel {...filterPanelProps} />
+  </IonModal>
+);
+```
+
+### Individual Filter Components
 
 ```tsx
 import {
@@ -501,6 +660,9 @@ import type {
   BadgeProps,
   InputProps,
   CardProps,
+  BaseCardProps,
+  BaseCardImageProps,
+  BaseCardContentProps,
   CheckboxProps,
   RadioButtonProps,
   DropdownProps,
@@ -541,21 +703,18 @@ import type {
   ViewMode,
 
   // Filter Component Props
+  FilterPanelProps,
+  FilterModalProps,
+  FilterState,
+  FilterOptions,
+  FilterOption,
+  ThemeAggregation,
+  SelectedFilter,
+  RegionOption,
   FilterCheckboxItemProps,
-  CollapsibleFilterSectionProps,
-  PriceRangeFilterProps,
-  HotelCategoryFilterProps,
+  FilterMinimapProps,
   CategoryOption,
-  ReviewsFilterProps,
   ReviewOption,
-  ExperienceFilterProps,
-  ThemeAggregation,
-  RegionsFilterProps,
-  RegionOption,
-  CheckboxFilterProps,
-  FilterOption,
-  SelectedFiltersRowProps,
-  SelectedFilter,
 
   // Context Types
   UIContextValue,