Commerce UI (@dipesh.singh/commerce-ui)

Reusable Commerce & Domain UI Component Kit for Hiljhil Cafe

@dipesh.singh/commerce-ui is the dedicated ecommerce component library for Hiljhil Cafe and its micro-frontends (discovery-ui, product-page-ui, cart-ui, homepage-ui, search-ui, mycommerce).

It sits between the foundational design system (@dipesh.singh/proton) and the application views, encapsulating domain patterns such as pricing, spatial countertop verification, compound product cards, and accessible quantity steppers.

🏗️ Architecture

┌──────────────────────────────────────────────────────────┐
│      Micro-Frontends (discovery, product-page, cart)     │
└──────────────┬────────────────────────────┬──────────────┘
               │                            │
               ▼                            │
┌────────────────────────────────┐          │
│   @dipesh.singh/commerce-ui    │          │
│   (Domain & Commerce Patterns) │          │
└──────────────┬─────────────────┘          │
               │                            │
               ▼                            ▼
┌──────────────────────────────────────────────────────────┐
│                  @dipesh.singh/proton                    │
│            (Design Tokens & UI Primitives)               │
└──────────────────────────────────────────────────────────┘

📦 Components Included

1. HeroBanner (Contentful-Configurable)

Supports both full-width single overlay and 2-column split layouts directly configurable from Contentful:

import { HeroBanner } from '@dipesh.singh/commerce-ui';

// Layout 1: 'single' (Full-bleed background overlay)
<HeroBanner
  layout="single"
  eyebrow="Hiljhil Specialty Roasters • hiljhil.cafe"
  headline="Precision Coffee & Space-Verified Machines"
  description="Artisanal batch-roasted coffees and countertop-verified espresso gear."
  backgroundImage="https://images.unsplash.com/photo-cafe.jpg"
  ctas={[
    { label: 'Explore Catalog', url: '#/collection', variant: 'primary' },
    { label: 'Visit Cafe Bar', url: '#/cafe', variant: 'outline' },
  ]}
>
  {/* Optional interactive widget slot (e.g. spatial clearance check) */}
  <SpatialClearanceBar onSelect={handleFilter} />
</HeroBanner>

// Layout 2: 'side-by-side' (2-column split layout)
<HeroBanner
  layout="side-by-side"
  eyebrow="Featured Hardware Spotlight"
  headline="Breville Barista Touch Impress"
  description="Experience third-wave espresso at home with automated dosing and assisted tamping."
  featuredImage="https://images.unsplash.com/photo-breville.jpg"
  mediaPosition="right"
  ctas={[
    { label: 'Shop Machine ($1,499.95)', url: '#/product/prod_breville_barista_touch', variant: 'primary' },
  ]}
/>

2. ProductCard (Compound Component)

Flexible card supporting both quick single-prop rendering and compound subcomponent composition:

import { ProductCard } from '@dipesh.singh/commerce-ui';

// Quick Mode:
<ProductCard
  product={product}
  onAddToCart={(p) => addToCart(p)}
  onFitmentCheck={(p) => openFitmentModal(p)}
/>

// Compound Mode (full customization):
<ProductCard>
  <ProductCard.Media src={imgUrl} alt={title} badge={<Badge>NEW</Badge>} />
  <ProductCard.Content>
    <ProductCard.Rating score={4.9} count={120} />
    <ProductCard.Title title={title} subtitle={origin} />
    <ProductCard.Fitment fitment={fitmentSpec} />
    <div className="flex justify-between items-center mt-3">
      <ProductCard.Price cents={149900} compareAtCents={169900} />
      <ProtonButton size="sm">Order</ProtonButton>
    </div>
  </ProductCard.Content>
</ProductCard>

2. PriceDisplay

Formats integer cents into localized currency with optional MSRP strikethrough and percentage discount badges:

import { PriceDisplay } from '@dipesh.singh/commerce-ui';

<PriceDisplay cents={149995} compareAtCents={169995} size="lg" />
// Output: $1,499.95  $1,699.95  [Save 12%]

3. QuantityStepper

Accessible +/- stepper with keyboard navigation, min/max limits, and debounced change handling:

import { QuantityStepper } from '@dipesh.singh/commerce-ui';

<QuantityStepper
  value={quantity}
  min={1}
  max={12}
  onChange={(newQty) => updateQuantity(newQty)}
/>

4. FitmentBadge

Conveys kitchen countertop clearance status and headroom verification:

import { FitmentBadge } from '@dipesh.singh/commerce-ui';

<FitmentBadge status="verified" deltaCm={8.2} pulse />
<FitmentBadge status="warning" deltaCm={-2.0} />

5. FilterPills

Scrollable filter pills for category and attribute filtering:

import { FilterPills } from '@dipesh.singh/commerce-ui';

<FilterPills
  options={categories}
  selectedId={activeCategory}
  onSelect={(id) => setActiveCategory(id)}
/>

6. EmptyState

Standardized zero-state graphic, title, and action for empty carts and search results:

import { EmptyState } from '@dipesh.singh/commerce-ui';

<EmptyState
  title="Your Barista Bag is Empty"
  description="Discover single-origin roasts and countertop espresso gear."
  actionLabel="Shop Coffee"
  onAction={() => navigate('#/catalog')}
/>

🛠️ Development & Build Commands

# Start local interactive component playground on http://localhost:5180
npm run dev

# Run strict TypeScript validation
npm run type-check

# Build production distribution (dist/index.js + dist/index.d.ts)
npm run build