@htmlbricks/hb-order-list 0.71.35 → 0.71.36

package/README.md

@@ -1,38 +1,117 @@
-## `hb-order-list` — order list
+# hb-order-list
 
-**Category:** commerce  
-**Tags:** commerce, order
+**Category:** commerce · **Tags:** commerce, order
 
-### What it does
+## Overview
 
-Order summary view driven by a payment JSON object: order number header, optional tracking area, list of line items with image and name, and a footer showing the order total including tax and optional shipment fee. Exposes the item image via the `item_image` CSS part.
+`hb-order-list` is a read-only order summary for commerce flows. It renders a header with the order number, a scrollable list of line items (thumbnail and name), and a footer that shows the computed grand total. The view is driven entirely by a single **`payment`** payload (serialized JSON when used from HTML).
 
-### Custom element
+The layout is built with Bulma **`container`** and **`columns`**. Typography and surfaces follow Bulma’s **`--bulma-*`** theme variables on `:host`. See [Bulma CSS variables](https://bulma.io/documentation/features/css-variables/) and `extra/docs.ts` for the registered tokens.
+
+## What it renders
+
+1. **Header** — “Order N.” plus `payment.orderNumber`, and a static “tracking” label in a narrow column (placeholder copy in the current markup).
+2. **Line items** — For each entry in `payment.items`, one row with the product **`image`** (see CSS part `item_image`), the **`name`**, and a static “quantity” label (the numeric `quantity` field is used for totals but not shown as text in the template).
+3. **Footer** — Static “cancel” and placeholder middle text (`bbb` in the template), plus the **computed total** formatted as `{total}{currencySymbol}` (no thousands separator; symbol appended after the number).
+
+Grand total is computed in the component as:
+
+- **Subtotal** — sum of `unitaryPrice * (quantity ?? 1)` for all items.
+- **Tax** — sum of `unitaryPrice * (quantity ?? 1) * taxPercentage / 100`, rounded to two decimal places.
+- **Total** — subtotal + tax + `(shipmentFee ?? 0)`.
+
+If `payment` is supplied as a **string** (typical from HTML attributes), the component parses it as JSON. Missing `countryCode` defaults to `"IT"`. Missing `currencySymbol` is inferred from `countryCode` (`IT` / `EU` → `€`, `US` → `$`).
+
+## `payment` JSON shape (`OrderPayment`)
+
+The attribute / property matches **`OrderPayment`** in `types/webcomponent.type.d.ts`: checkout cart fields plus order metadata.
+
+| Field | Type | Required | Notes |
+|-------|------|----------|--------|
+| `orderNumber` | string | Yes | Shown in the header after “Order N.” |
+| `countryCode` | `"IT"` \| `"US"` \| `"EU"` | Yes | Drives default currency when `currencySymbol` is omitted. |
+| `currencySymbol` | `"€"` \| `"$"` | No | Shown after the numeric total. Defaults from `countryCode` when missing. |
+| `shipmentFee` | number | No | Added once to the grand total. |
+| `items` | array | Yes | Each line item must satisfy the row UI (including **`image`**). |
+
+Each **`items[]`** entry extends the shared shop line type with a required **`image`** URL (or path) for the thumbnail.
+
+| Field | Type | Required | Notes |
+|-------|------|----------|--------|
+| `id` | string | Yes | Stable key for the `{#each}` block. |
+| `name` | string | Yes | Product title next to the image. |
+| `unitaryPrice` | number | Yes | Unit price before tax. |
+| `taxPercentage` | number | Yes | Percent applied per line (`8` means 8%). |
+| `quantity` | number | No | Defaults to `1` for subtotal and tax. |
+| `unit` | string | No | Part of shared `IShopItem`; not displayed in this template. |
+| `image` | string | Yes | `src` for the row thumbnail; exposed via `::part(item_image)`. |
+
+Types re-use **`IShopItem`** / **`IShoppingPayment`** from `checkout-shopping-cart` (`builder/src/wc/checkout-shopping-cart/types/webcomponent.type.d.ts`) with **`image`** required on each item.
+
+## Custom element
 
 `hb-order-list`
 
-### Attributes (snake_case; use string values in HTML)
+## Attributes (snake_case; string values in HTML)
+
+Web component attributes are strings. Pass structured data as **JSON text** on the `payment` attribute (numbers and booleans inside that JSON follow normal JSON rules).
+
+| Attribute | Required | Description |
+|-----------|----------|-------------|
+| `id` | No | Optional host identifier. |
+| `style` | No | Optional inline host styles (present on the public `Component` type). |
+| `payment` | Yes for real data | JSON string describing `OrderPayment` (see table above). The Svelte props type marks `payment` as required; the implementation still provides an empty placeholder when nothing is passed—set `payment` whenever you want line items and totals. From HTML, use a serialized JSON string; in Svelte/JS you may pass an object. |
 
-- `id`, `style` (optional): strings.
-- `payment` (required): JSON string — `OrderPayment` with `orderNumber`, `countryCode`, `items` (shop line items plus `image` per row), plus cart/tax fields from shared checkout types.
+## Events
 
-### Events
+None. `Events` in `types/webcomponent.type.d.ts` is an empty object.
 
-None declared.
+## Styling
 
-### Styling (Bulma)
+Registered theme hooks (see `extra/docs.ts` / `styleSetup`):
 
-Layout uses Bulma `container` and `columns` / `column` with fractional widths (`is-10`, `is-2`, etc.). Theme tokens are registered on `:host` via Bulma’s light theme and `setup-theme`. Customize colors and spacing from the page by setting `--bulma-*` variables (for example `--bulma-text`, `--bulma-scheme-main`, `--bulma-column-gap`); see `extra/docs.ts` and `styles/bulma.scss`.
+| CSS variable | Role |
+|--------------|------|
+| `--bulma-text` | Foreground for order number, names, totals, and body copy. |
+| `--bulma-scheme-main` | Surface / background. |
+| `--bulma-column-gap` | Horizontal gap between Bulma columns. |
 
-### Usage notes
+## CSS parts
 
-- **CSS parts:** `item_image`.
-- Serialize `payment` as a single JSON attribute; see `builder/src/wc/order-list/types/webcomponent.type.d.ts` and examples in `extra/docs.ts`.
+| Part | Target |
+|------|--------|
+| `item_image` | The `<img>` thumbnail for each line item (`part="item_image"`). |
 
-### Minimal HTML example
+## HTML slots
+
+None.
+
+## Usage notes
+
+- Serialize **`payment`** as one JSON string on the attribute; escape quotes for inline HTML or build the string in JavaScript.
+- Ensure every item includes **`image`**, **`id`**, **`name`**, **`unitaryPrice`**, and **`taxPercentage`** so totals and rows stay consistent with the typings.
+- Country and currency should stay aligned (`countryCode` + optional `currencySymbol`) for a coherent footer.
+
+## Examples
+
+### Minimal order
 
 ```html
 <hb-order-list
-  payment='{"orderNumber":"1001","countryCode":"EU","items":[{"id":"1","name":"Item","unitaryPrice":10,"taxPercentage":22,"image":"https://example.com/a.jpg"}]}'
+  payment='{"orderNumber":"1001","countryCode":"EU","items":[{"id":"1","name":"Sample item","unitaryPrice":10,"taxPercentage":22,"image":"https://example.com/product.jpg"}]}'
 ></hb-order-list>
 ```
+
+### Order with shipment fee and explicit currency
+
+```html
+<hb-order-list
+  payment='{"orderNumber":"ORD-1002","countryCode":"EU","currencySymbol":"€","shipmentFee":4.99,"items":[{"id":"a","name":"Item A","unitaryPrice":5,"taxPercentage":7,"quantity":2,"image":"https://example.com/a.jpg"},{"id":"b","name":"Item B","unitaryPrice":2,"taxPercentage":7,"image":"https://example.com/b.jpg"}]}'
+></hb-order-list>
+```
+
+## Related files
+
+- `component.wc.svelte` — markup and total calculation.
+- `types/webcomponent.type.d.ts` — `Component`, `OrderPayment`, and item typing.
+- `extra/docs.ts` — Storybook args, `styleSetup`, and named examples (`default`, `withShipment`, `singleItem`, `usd`).

package/manifest.json

@@ -121,7 +121,7 @@
         "name": "--bulma-text",
         "valueType": "color",
         "defaultValue": "#363636",
-        "description": "Primary text color."
+        "description": "Primary foreground for order number, line item names, totals, and other body copy."
       },
       {
         "name": "--bulma-scheme-main",
@@ -131,7 +131,7 @@
       },
       {
         "name": "--bulma-column-gap",
-        "valueType": "other",
+        "valueType": "string",
         "defaultValue": "0.75rem",
         "description": "Gap between grid columns."
       }
@@ -139,7 +139,7 @@
     "parts": [
       {
         "name": "item_image",
-        "description": ""
+        "description": "Product thumbnail on each line item row."
       }
     ]
   },
@@ -261,5 +261,5 @@
   "size": {},
   "iifePath": "main.iife.js",
   "repoName": "@htmlbricks/hb-order-list",
-  "version": "0.71.35"
+  "version": "0.71.36"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@htmlbricks/hb-order-list",
-  "version": "0.71.35",
+  "version": "0.71.36",
   "contributors": [],
   "description": "Order summary view driven by a payment JSON object: order number header, optional tracking area, list of line items with image and name, and a footer showing the order total including tax and optional shipment fee. Exposes the item image via the item_image CSS part.",
   "licenses": [