@htmlbricks/hb-order-list 0.71.35 → 0.71.37

package/README.md

@@ -1,38 +1,84 @@
-## `hb-order-list` — order list
+# `hb-order-list` — integrator guide
 
-**Category:** commerce  
-**Tags:** commerce, order
+**Category:** commerce · **Tags:** commerce, order · **Package:** `@htmlbricks/hb-order-list`
 
-### What it does
+## Summary
 
-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 list of line items (thumbnail and name), and a footer with the computed grand total. The view is driven by a **`payment`** payload (JSON string from HTML).
 
-### Custom element
+Layout uses Bulma **`container`** and **`columns`**. Theme via **`--bulma-*`** on `:host`; see [Bulma CSS variables](https://bulma.io/documentation/features/css-variables/) and `extra/docs.ts`.
 
-`hb-order-list`
+## Behavior
 
-### Attributes (snake_case; use string values in HTML)
+1. **Header** — “Order N.” plus `payment.orderNumber`, and a static “tracking” label (placeholder in the current markup).
+2. **Line items** — For each `payment.items` row: product **`image`** (CSS part `item_image`), **`name`**, and a static “quantity” label (numeric `quantity` affects totals only).
+3. **Footer** — Static “cancel” and placeholder middle text (`bbb` in the template), plus **total** as `{total}{currencySymbol}`.
 
-- `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.
+**Totals:** Subtotal = sum of `unitaryPrice * (quantity ?? 1)`; tax = sum of line VAT rounded at the sum level; total = subtotal + tax + `(shipmentFee ?? 0)`.
 
-### Events
+If **`payment`** is a string, it is JSON-parsed. Missing **`countryCode`** defaults to **`"IT"`**. Missing **`currencySymbol`** is inferred from **`countryCode`** (`IT` / `EU` → `€`, `US` → `$`).
 
-None declared.
+## Custom element tag
 
-### Styling (Bulma)
+```html
+<hb-order-list …></hb-order-list>
+```
+
+## Attributes (HTML / reflected props)
+
+Web component attributes are **strings** (snake_case). Structured data is a **JSON** string on **`payment`**.
+
+| Attribute | Role |
+|-----------|------|
+| `id` | Optional host id. |
+| `style` | Optional inline style on the host. |
+| `payment` | JSON string (or object when used from JS) describing **`OrderPayment`** (see `types/webcomponent.type.d.ts`). The implementation falls back to an empty in-memory default when omitted. |
+
+## Events
+
+No custom events (`Events` is `{}` in `types/webcomponent.type.d.ts`).
+
+## CSS custom properties, parts, and slots
+
+**Documented variables** (`extra/docs.ts` / `styleSetup`):
+
+| Variable | Default | Notes |
+|----------|---------|--------|
+| `--bulma-text` | `#363636` | Foreground for copy and totals. |
+| `--bulma-scheme-main` | `#ffffff` | Surface background. |
+| `--bulma-column-gap` | `0.75rem` | Column gutter. |
 
-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`.
+| `::part` | Role |
+|---------|------|
+| `item_image` | Line item `<img>` thumbnail. |
 
-### Usage notes
+**Slots:** none.
 
-- **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`.
+## TypeScript typings (authoring)
+
+From `types/webcomponent.type.d.ts` (see that file for **`OrderPayment`** and line item shapes):
+
+```ts
+export type Component = {
+  id?: string;
+  style?: string;
+  payment?: OrderPayment | string;
+};
+export type Events = {};
+```
+
+## Minimal HTML
+
+```html
+<hb-order-list
+  payment='{"orderNumber":"1001","countryCode":"EU","items":[{"id":"1","name":"Sample item","unitaryPrice":10,"taxPercentage":22,"image":"https://example.com/product.jpg"}]}'
+></hb-order-list>
+```
 
-### Minimal HTML example
+With shipment fee:
 
 ```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":"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"}]}'
 ></hb-order-list>
 ```