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

package/README.md

@@ -1,51 +1,140 @@
-## `hb-shop-item-row` — shop item row
+# `hb-shop-item-row` (shop-item-row)
 
 **Category:** commerce  
-**Tags:** commerce, product
+**Tags:** commerce, product  
+**Package:** `@htmlbricks/hb-shop-item-row`
 
-### What it does
+## Overview
 
-Horizontal shop product card: image with optional badge, linked title and metadata, description, star rating scale with numeric rating and reviews link, current and strikethrough prices, and optional footer—all overridable via named slots.
+Horizontal shop product row built as a Bulma **card** with a two-column layout: a narrow **thumbnail** column (optional image, optional badge tag) and a **main** column (linked title, muted subtitle, body text, star rating with numeric score, linked reviews line, current and compare-at prices, optional **card footer**). Content can come from **attributes** or from **named slots**; when a slot has no light DOM children, the component falls back to the matching string attribute.
 
-### Custom element
+Use this element in dense product lists, search results, or comparison tables where a wide, single-row preview reads better than a stacked card. For a vertical card with the same content model, see **`hb-shop-item-cell`**.
 
-`hb-shop-item-row`
+### Layout and behavior
 
-### Attributes (snake_case; use string values in HTML)
+- **Thumbnail:** The image and badge render only when `img` is non-empty. The image (and badge overlay) are wrapped in a link that uses `url` when it is set; otherwise the link has no `href`.
+- **Title:** When `title` is set or the `title` slot has content, the title appears as a level-5 heading with a link that uses the same `url` rules as the image.
+- **Rating row:** A rating block appears when `rating` is set, or when the `reviews` slot or `reviews` attribute has content. **Star icons** (Bootstrap Icons–style SVGs) render only when `rating` is truthy (for example, omit or use `"0"` to hide stars). The number of icons equals **`ratingscale`**. Stars support **full** and **half** fills from the numeric `rating` value. The numeric label after the stars uses the **`rating`** slot or attribute. The **reviews** text is shown in parentheses and wrapped in a link that uses `reviewsurl` when set.
+- **Prices:** The current price is bold; **`regularprice`** is shown struck-through beside it when either the attribute or the `regularprice` slot provides content.
+- **Footer:** An optional Bulma **card footer** spans the text column when `footer` or the `footer` slot has content.
 
-- `id`, `style` (optional): strings.
-- `img`, `url`, `badge`, `title`, `subtitle`, `text`, `reviews`, `reviewsurl`, `price`, `regularprice`, `footer` (required in types): strings.
-- `rating`, `ratingscale` (required): numbers as strings.
+## Custom element
 
-### Events
+```html
+<hb-shop-item-row …></hb-shop-item-row>
+```
+
+## Attributes
+
+Web component **attribute names use snake_case**. In plain HTML, **all attribute values are strings**. Use empty `""` for unused text fields where you still need the attribute present for tooling or consistency.
+
+| Attribute | Required | Description |
+| --- | --- | --- |
+| `id` | No | Optional host id (forwarded to the inner card wrapper). |
+| `style` | No | Optional; present on the `Component` typing for host styling. |
+| `img` | Yes* | Image URL. If empty, the thumbnail column does not show an image or badge wrapper. |
+| `url` | Yes* | Product URL for the image and title links. |
+| `badge` | Yes* | Short label (for example sale text); shown in a **danger** rounded tag over the image when combined with `img`. |
+| `title` | Yes* | Primary product name. |
+| `subtitle` | Yes* | Muted secondary line under the title. |
+| `text` | Yes* | Main descriptive copy. |
+| `rating` | Yes* | Numeric score for stars and the numeric label; pass as a string (for example `"4.5"`). Falsy values hide the star row but reviews-only content can still show. |
+| `ratingscale` | Yes* | Number of star icons; pass as a string (for example `"5"`). |
+| `reviews` | Yes* | Text inside the linked parentheses (for example review count). |
+| `reviewsurl` | Yes* | URL for the reviews parentheses link. |
+| `price` | Yes* | Current or promotional price string. |
+| `regularprice` | Yes* | Compare-at price string (struck through when set). |
+| `footer` | Yes* | Optional footer line. |
+
+\*Marked “Yes” because the published **`Component`** interface lists them as required; in markup, supply **`""`** for fields you do not use.
+
+## Events
+
+No custom events are declared in `types/webcomponent.type.d.ts` (`Events` is `{}`).
+
+## Slots
+
+Each named slot falls back to the **same-named attribute** when the slot has no content (see `extra/docs.ts`).
+
+| Slot | Purpose |
+| --- | --- |
+| `badge` | Optional label over the row thumbnail inside a rounded tag; defaults to the `badge` attribute when the slot is empty. |
+| `title` | Main product name in the title link beside the image; defaults to the `title` attribute when the slot is empty. |
+| `subtitle` | Secondary line under the title (muted); defaults to the `subtitle` attribute when the slot is empty. |
+| `text` | Product description or pitch in the main column; defaults to the `text` attribute when the slot is empty. |
+| `rating` | Numeric score shown after the star icons when `rating` is set; defaults to the `rating` attribute as plain text. |
+| `reviews` | Review count or label inside the linked parentheses next to the stars; defaults to the `reviews` attribute (the link uses `reviewsurl`). |
+| `price` | Current or sale price (bold, baseline row); defaults to the `price` attribute when the slot is empty. |
+| `footer` | Optional footer strip under the text column (still inside the card); defaults to the `footer` attribute when the slot is empty. |
+| `regularprice` | List or compare-at price shown struck-through beside `price`; defaults to the `regularprice` attribute when the slot is empty. |
+
+There are no documented **`::part`** hooks for this package (`styleSetup.parts` is empty).
 
-None declared.
+## Styling (Bulma)
 
-### Styling (Bulma)
+Cherry-picked **Bulma 1.x** Sass (`card`, `columns`, `image`, `content`, `title`, `tag`, helpers) is scoped to **`:host`** via `styles/bulma.scss`. Theme tokens are the public **`--bulma-*`** variables; set them on `body`, `:root`, or any ancestor so they inherit into the shadow tree. See [Bulma CSS variables](https://bulma.io/documentation/features/css-variables/) and `extra/docs.ts` for the full `styleSetup` list.
 
-The component bundles cherry-picked Bulma 1 Sass modules scoped to `:host` (see `styles/bulma.scss`). Theme defaults are applied via Bulma’s light theme and `setup-theme`. Override appearance from the light DOM by setting public `--bulma-*` custom properties on `body` or `:root`; they inherit into the shadow root. Documented tokens include `--bulma-primary`, `--bulma-text`, `--bulma-card-background-color`, `--bulma-border`, and `--bulma-shadow` (see `extra/docs.ts`).
+| Variable | Purpose |
+| --- | --- |
+| `--bulma-primary` | Accent and interactive highlights (theme setup). |
+| `--bulma-text` | Body and title text. |
+| `--bulma-card-background-color` | Background for the horizontal card shell (thumbnail column, text column, footer). |
+| `--bulma-border` | Row frame border (component SCSS supplies a fallback if unset). |
+| `--bulma-shadow` | Row frame shadow (fallback in SCSS if unset). |
+| `--bulma-text-weak` | Subtitle, strikethrough context, and secondary lines. |
+| `--bulma-link` | Linked title and reviews URL color. |
+| `--bulma-radius` | Card corners for the horizontal row shell. |
 
-### Usage notes
+The host also uses **`--bulma-block-spacing`** (with a built-in fallback) for default vertical **margin** between rows when the element is stacked in a list.
 
-- **Slots:** `badge`, `title`, `subtitle`, `text`, `rating`, `reviews`, `price`, `footer`, `regularprice`.
-- Storybook exposes `action` for demos only; it is not on the `Component` type.
+## Usage notes
 
-### Minimal HTML example
+- **Slots and attributes** share the same names: each slot’s default content is the corresponding attribute when the slot is empty.
+- **Storybook** exposes an `action` control for demos; it is **not** part of the `Component` props type.
+- **Internationalization:** `extra/docs.ts` does not register `i18n` entries for this package; translate strings in the host app before passing them in.
+
+## Examples
+
+### Full row
 
 ```html
 <hb-shop-item-row
-  img="https://placehold.co/96"
-  url="/p/1"
-  badge="New"
-  title="Product"
-  subtitle="Vendor"
-  text="One line pitch."
+  img="https://placehold.co/200x150"
+  url="/products/running-shoes"
+  badge="-15%"
+  title="Running shoes"
+  subtitle="Unisex · sizes 36–48"
+  text="Lightweight mesh upper and cushioned sole for daily miles."
   rating="5"
   ratingscale="5"
-  reviews="3"
-  reviewsurl="/p/1#reviews"
-  price="€9"
-  regularprice="€12"
+  reviews="2.4k reviews"
+  reviewsurl="/products/running-shoes#reviews"
+  price="€102.00"
+  regularprice="€120.00"
+  footer="Ships in 24h"
+></hb-shop-item-row>
+```
+
+### Title and price only
+
+```html
+<hb-shop-item-row
+  img="https://placehold.co/120x90"
+  url=""
+  badge=""
+  title="Gift card €25"
+  subtitle=""
+  text=""
+  rating=""
+  ratingscale="5"
+  reviews=""
+  reviewsurl=""
+  price="€25.00"
+  regularprice=""
   footer=""
 ></hb-shop-item-row>
 ```
+
+## License
+
+Package metadata references **Apache-2.0** (see `LICENSE.md` in the published package when consuming from npm).

package/manifest.json

@@ -174,7 +174,7 @@
         "name": "--bulma-card-background-color",
         "valueType": "color",
         "defaultValue": "#ffffff",
-        "description": "Card surface."
+        "description": "Background fill for the horizontal card shell (thumbnail column, text column, footer)."
       },
       {
         "name": "--bulma-border",
@@ -187,6 +187,24 @@
         "valueType": "other",
         "defaultValue": "0 0.125em 0.25em rgba(10, 10, 10, 0.1)",
         "description": "Row frame shadow (falls back in component SCSS if unset)."
+      },
+      {
+        "name": "--bulma-text-weak",
+        "valueType": "color",
+        "defaultValue": "#7a7a7a",
+        "description": "Subtitle, strikethrough context, and secondary lines."
+      },
+      {
+        "name": "--bulma-link",
+        "valueType": "color",
+        "defaultValue": "#485fc7",
+        "description": "Linked title and reviews URL color."
+      },
+      {
+        "name": "--bulma-radius",
+        "valueType": "number",
+        "defaultValue": "0.375rem",
+        "description": "Card corners for the horizontal row shell."
       }
     ],
     "parts": []
@@ -195,39 +213,39 @@
   "htmlSlots": [
     {
       "name": "badge",
-      "description": "badge"
+      "description": "Optional label over the row thumbnail inside a rounded tag; defaults to the `badge` attribute when the slot is empty."
     },
     {
       "name": "title",
-      "description": "title"
+      "description": "Main product name in the title link beside the image; 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 pitch in the main column; 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 footer strip under the text column (still inside the card); 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": [],
@@ -329,5 +347,5 @@
   "size": {},
   "iifePath": "main.iife.js",
   "repoName": "@htmlbricks/hb-shop-item-row",
-  "version": "0.71.35"
+  "version": "0.71.37"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@htmlbricks/hb-shop-item-row",
-  "version": "0.71.35",
+  "version": "0.71.37",
   "contributors": [],
   "description": "Horizontal shop product card: image with optional badge, linked title and metadata, description, star rating scale with numeric rating and reviews link, current and strikethrough prices, and optional footer—all overridable via named slots.",
   "licenses": [

package/types/webcomponent.type.d.ts

@@ -17,5 +17,4 @@ export type Component = {
 	footer: string;
 };
 
-export type Events = {
-};
+export type Events = {};