# `hb-shop-item-cell` (shop-item-cell)

**Category:** commerce  
**Tags:** commerce, product  
**Package:** `@htmlbricks/hb-shop-item-cell`

## Overview

`hb-shop-item-cell` is a vertical **shop product card** web component: a top **image** area with an optional **badge**, then a **Bulma**-styled `card` body (title, subtitle, description, star rating, reviews link, prices) and an optional **footer** row. The content model mirrors **`hb-shop-item-row`** so you can reuse the same attributes and slot names across grid and list layouts.

Star icons use **Bootstrap Icons** SVGs embedded in the shadow tree; layout and typography follow **Bulma 1.x** (`card`, `image`, `content`, `title`, `subtitle`, `tag`, flex helpers).

## Custom element

```html
<hb-shop-item-cell …></hb-shop-item-cell>
```

## Layout behavior

- **Image** — The image block (linked figure + optional badge) renders only when the `img` attribute is non-empty. The image link uses `url` when set; otherwise the anchor has no effective destination (treat empty `url` as “image only”).
- **Title** — The main title is a link when `url` is provided; same `url` is used for the image link.
- **Rating row** — The row appears when there is a non-zero **`rating`**, or when **`reviews`** / the **`reviews`** slot supplies content. Star icons render only when **`rating`** is truthy (non-zero in practice). After the stars, the numeric score uses the **`rating`** slot or the `rating` value as text.
- **Stars** — The component renders **`ratingscale`** star positions (default in examples is `5`; you can use e.g. `10` for a 10-point scale). Values support **fractional** ratings for half-star display.
- **Reviews** — The text in parentheses is linked with **`reviewsurl`** when that attribute is set.
- **Prices** — Current **`price`** (bold) and optional struck-through **`regularprice`**; either can be driven by attributes or slots.
- **Footer** — Optional **`footer`** row at the bottom of the card.

## Attributes

Web component **attribute names are `snake_case`**. In HTML, pass **strings** only: use `""` for empty text fields, and encode **numbers** as their string form (e.g. `"4"`, `"5"`).

| Attribute | Required | Type / encoding | Description |
|-----------|----------|-----------------|-------------|
| `id` | No | string | Optional host id on the root element. |
| `style` | No | string | Optional inline style string (see component typings). |
| `img` | Yes* | string | Product image URL. If empty, the image (and image badge) section is omitted. |
| `url` | Yes* | string | Destination for the image and title links; empty disables a useful `href`. |
| `badge` | Yes* | string | Short label on the image (rounded tag). Hidden when empty and the `badge` slot is unused. |
| `title` | Yes* | string | Primary product name (linked with `url`). |
| `subtitle` | Yes* | string | Muted secondary line under the title. |
| `text` | Yes* | string | Body / marketing copy in the card content. |
| `rating` | Yes* | number as string | Score used for stars and numeric display; `0` or empty suppresses the star strip (reviews-only row can still show). |
| `ratingscale` | Yes* | number as string | Number of star icons (scale length), e.g. `"5"` or `"10"`. |
| `reviews` | Yes* | string | Text inside the linked parentheses next to the rating row. |
| `reviewsurl` | Yes* | string | URL for the reviews link. |
| `price` | Yes* | string | Current or sale price (bold). |
| `regularprice` | Yes* | string | Compare-at / list price (struck through beside `price`). |
| `footer` | Yes* | string | Footer strip content below the main card body. |

\*The TypeScript `Component` type lists these fields for authoring; in HTML you still pass **strings** (including empty `""` where something is unused).

## Slots

Each named slot falls back to the **same-named attribute** when the slot has no content (see `extra/docs.ts`).

| Slot | Role |
|------|------|
| `badge` | Label over the product image; default: `badge`. |
| `title` | Main product name in the title link; default: `title`. |
| `subtitle` | Muted line under the title; default: `subtitle`. |
| `text` | Description in the card body; default: `text`. |
| `rating` | Text shown after the stars; default: string form of `rating`. |
| `reviews` | Text inside the parentheses; default: `reviews` (link uses `reviewsurl`). |
| `price` | Bold current price; default: `price`. |
| `regularprice` | Struck-through compare price; default: `regularprice`. |
| `footer` | Full-width footer row; default: `footer`. |

There are no documented **`::part`** hooks for this package (`styleSetup.parts` is empty).

## Events

No custom events are declared in `types/webcomponent.type.d.ts`.

## Theming (CSS custom properties)

The card respects **Bulma CSS variables** on the host page (for example on `body` or `:root`). Typical variables used by this layout are listed in `extra/docs.ts` / `styleSetup`:

| Variable | Role |
|----------|------|
| `--bulma-primary` | Accent / interactive emphasis. |
| `--bulma-card-background-color` | Card shell background (image area, content, footer). |
| `--bulma-text` | Primary text (titles, body, numeric rating, bold price). |
| `--bulma-text-weak` | Muted text (subtitle, reviews line, struck price). |
| `--bulma-border` | Card frame and separators. |
| `--bulma-radius` | Corner rounding for card and media. |
| `--bulma-link` | Linked title and reviews link color. |

See [Bulma: CSS variables](https://bulma.io/documentation/features/css-variables/) for the full variable system.

## Examples

### Full card (image, badge, rating, sale price, footer)

```html
<hb-shop-item-cell
  img="https://placehold.co/320x240/363636/ffffff?text=Product"
  url="https://example.com/p/1"
  badge="New"
  title="Wireless earbuds"
  subtitle="ANC · 32h battery"
  text="Compact charging case and IPX4 splash resistance."
  rating="4"
  ratingscale="5"
  reviews="128 reviews"
  reviewsurl="https://example.com/p/1#reviews"
  price="€79.00"
  regularprice="€99.00"
  footer="Free returns within 30 days"
></hb-shop-item-cell>
```

### Minimal listing (image, title, price)

```html
<hb-shop-item-cell
  img="https://placehold.co/320x240/363636/ffffff?text=Product"
  url=""
  badge=""
  title="Mug — ceramic"
  subtitle=""
  text=""
  rating="0"
  ratingscale="5"
  reviews=""
  reviewsurl=""
  price="€14.00"
  regularprice=""
  footer=""
></hb-shop-item-cell>
```

### Ten-point rating scale

```html
<hb-shop-item-cell
  img="https://placehold.co/320x240/363636/ffffff?text=Product"
  url="https://example.com/p/2"
  badge=""
  title="Desk lamp"
  subtitle="LED dimmable"
  text=""
  rating="9"
  ratingscale="10"
  reviews="See all"
  reviewsurl="https://example.com/p/2#reviews"
  price="€45.00"
  regularprice=""
  footer=""
></hb-shop-item-cell>
```

## Related components

Use **`hb-shop-item-row`** when you need the same product fields in a horizontal row layout; attributes and slots are aligned between the two.

## License

Package metadata references **Apache-2.0** (see `LICENSE.md` in the published package when consuming from npm).