@htmlbricks/hb-shop-item-cell 0.71.35 → 0.71.37

package/README.md

@@ -1,51 +1,159 @@
-## `hb-shop-item-cell` — shop item cell
+# `hb-shop-item-cell` (shop-item-cell)
 
 **Category:** commerce  
-**Tags:** commerce, product
+**Tags:** commerce, product  
+**Package:** `@htmlbricks/hb-shop-item-cell`
 
-### What it does
+## Overview
 
-Vertical shop product card: top image with optional badge, then the same body as `hb-shop-item-row` (title, subtitle, text, stars, reviews, prices, footer) with **Bulma** `card`, `tag`, `title` / `subtitle`, and matching slots.
+`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.
 
-### Custom element
+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).
 
-`hb-shop-item-cell`
+## Custom element
 
-### Attributes (snake_case; use string values in HTML)
+```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
 
-- `id`, `style` (optional): strings.
-- `img`, `url`, `badge`, `title`, `subtitle`, `text`, `reviews`, `reviewsurl`, `price`, `regularprice`, `footer` (required in types): strings (use `""` when empty).
-- `rating`, `ratingscale` (required): numbers as strings.
+Each named slot falls back to the **same-named attribute** when the slot has no content (see `extra/docs.ts`).
 
-### Events
+| 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`. |
 
-None declared.
+There are no documented **`::part`** hooks for this package (`styleSetup.parts` is empty).
 
-### Styling (Bulma)
+## Events
 
-Bundles **Bulma 1.x** (`card`, `image`, `content`, `title`, `tag`, helpers). Set **`--bulma-*`** on the light DOM to match your theme. Star icons still use Bootstrap Icons SVG class names in markup (no icon font required for the default stars).
+No custom events are declared in `types/webcomponent.type.d.ts`.
 
-### Usage notes
+## Theming (CSS custom properties)
 
-- **Slots:** `badge`, `title`, `subtitle`, `text`, `rating`, `reviews`, `price`, `footer`, `regularprice`.
-- Mirror `hb-shop-item-row` content model for consistent catalog UI.
+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`:
 
-### Minimal HTML example
+| 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/120"
-  url="/p/1"
-  badge=""
-  title="Product"
-  subtitle="Short line"
-  text="Description"
+  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="12 reviews"
-  reviewsurl="/p/1#reviews"
-  price="€19"
+  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).

package/manifest.json

@@ -163,19 +163,37 @@
         "name": "--bulma-card-background-color",
         "valueType": "color",
         "defaultValue": "#ffffff",
-        "description": "Card surface."
+        "description": "Background fill for the card shell (image area, content, footer)."
       },
       {
         "name": "--bulma-text",
         "valueType": "color",
         "defaultValue": "#363636",
-        "description": "Body text."
+        "description": "Primary text color for titles, body copy, numeric rating, and bold price."
       },
       {
         "name": "--bulma-text-weak",
         "valueType": "color",
         "defaultValue": "#7a7a7a",
         "description": "Subtitle, muted price, reviews link."
+      },
+      {
+        "name": "--bulma-border",
+        "valueType": "color",
+        "defaultValue": "#dbdbdb",
+        "description": "Card frame and image area separators."
+      },
+      {
+        "name": "--bulma-radius",
+        "valueType": "number",
+        "defaultValue": "0.375rem",
+        "description": "Card and image rounding."
+      },
+      {
+        "name": "--bulma-link",
+        "valueType": "color",
+        "defaultValue": "#485fc7",
+        "description": "Linked title and reviews URL color."
       }
     ],
     "parts": []
@@ -184,39 +202,39 @@
   "htmlSlots": [
     {
       "name": "badge",
-      "description": "badge"
+      "description": "Optional label over the product image inside a rounded tag; defaults to the `badge` attribute when the slot is empty."
     },
     {
       "name": "title",
-      "description": "title"
+      "description": "Main product name in the card title link; defaults to the `title` attribute when the slot is empty."
     },
     {
       "name": "subtitle",
-      "description": "subtitle"
+      "description": "Secondary line under the title (muted); defaults to the `subtitle` attribute when the slot is empty."
     },
     {
       "name": "text",
-      "description": "text"
+      "description": "Product description or marketing copy in the card body; defaults to the `text` attribute when the slot is empty."
     },
     {
       "name": "rating",
-      "description": "rating"
+      "description": "Numeric score shown after the star icons when `rating` is set; defaults to the `rating` attribute as plain text."
     },
     {
       "name": "reviews",
-      "description": "reviews"
+      "description": "Review count or label inside the linked parentheses next to stars; defaults to the `reviews` attribute (link uses `reviewsurl`)."
     },
     {
       "name": "price",
-      "description": "price"
+      "description": "Current or sale price (bold, baseline row); defaults to the `price` attribute when the slot is empty."
     },
     {
       "name": "footer",
-      "description": "footer"
+      "description": "Optional full-width card footer row below content; defaults to the `footer` attribute when the slot is empty."
     },
     {
       "name": "regularprice",
-      "description": "regularprice"
+      "description": "List or compare-at price shown struck-through beside `price`; defaults to the `regularprice` attribute when the slot is empty."
     }
   ],
   "i18n": [],
@@ -318,5 +336,5 @@
   "size": {},
   "iifePath": "main.iife.js",
   "repoName": "@htmlbricks/hb-shop-item-cell",
-  "version": "0.71.35"
+  "version": "0.71.37"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@htmlbricks/hb-shop-item-cell",
-  "version": "0.71.35",
+  "version": "0.71.37",
   "contributors": [],
   "description": "Vertical shop product card: top image with optional badge, then the same body as shop-item-row (title, subtitle, text, stars, reviews, prices, footer) with Bootstrap card styling and matching slots.",
   "licenses": [