@htmlbricks/hb-order-list 0.71.36 → 0.72.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (6) hide show
  1. package/README.md +47 -80
  2. package/main.iife.js.map +1 -1
  3. package/manifest.json +10 -5
  4. package/package.json +1 -1
  5. package/types/webcomponent.type.d.json +9 -4
  6. package/types/webcomponent.type.d.ts +2 -1
package/README.md CHANGED
@@ -1,100 +1,73 @@
1
- # hb-order-list
1
+ # `hb-order-list` — integrator guide
2
2
 
3
- **Category:** commerce · **Tags:** commerce, order
3
+ **Category:** commerce · **Tags:** commerce, order · **Package:** `@htmlbricks/hb-order-list`
4
4
 
5
- ## Overview
5
+ ## Summary
6
6
 
7
- `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).
7
+ `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).
8
8
 
9
- 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.
9
+ 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`.
10
10
 
11
- ## What it renders
11
+ ## Behavior
12
12
 
13
- 1. **Header** — “Order N.” plus `payment.orderNumber`, and a static “tracking” label in a narrow column (placeholder copy in the current markup).
14
- 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).
15
- 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).
13
+ 1. **Header** — “Order N.” plus `payment.orderNumber`, and a static “tracking” label (placeholder in the current markup).
14
+ 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).
15
+ 3. **Footer** — Static “cancel” and placeholder middle text (`bbb` in the template), plus **total** as `{total}{currencySymbol}`.
16
16
 
17
- Grand total is computed in the component as:
17
+ **Totals:** Subtotal = sum of `unitaryPrice * (quantity ?? 1)`; tax = sum of line VAT rounded at the sum level; total = subtotal + tax + `(shipmentFee ?? 0)`.
18
18
 
19
- - **Subtotal** — sum of `unitaryPrice * (quantity ?? 1)` for all items.
20
- - **Tax** — sum of `unitaryPrice * (quantity ?? 1) * taxPercentage / 100`, rounded to two decimal places.
21
- - **Total** — subtotal + tax + `(shipmentFee ?? 0)`.
19
+ If **`payment`** is a string, it is JSON-parsed. Missing **`countryCode`** defaults to **`"IT"`**. Missing **`currencySymbol`** is inferred from **`countryCode`** (`IT` / `EU` → `€`, `US` → `$`).
22
20
 
23
- 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` → `$`).
21
+ ## Custom element tag
24
22
 
25
- ## `payment` JSON shape (`OrderPayment`)
26
-
27
- The attribute / property matches **`OrderPayment`** in `types/webcomponent.type.d.ts`: checkout cart fields plus order metadata.
28
-
29
- | Field | Type | Required | Notes |
30
- |-------|------|----------|--------|
31
- | `orderNumber` | string | Yes | Shown in the header after “Order N.” |
32
- | `countryCode` | `"IT"` \| `"US"` \| `"EU"` | Yes | Drives default currency when `currencySymbol` is omitted. |
33
- | `currencySymbol` | `"€"` \| `"$"` | No | Shown after the numeric total. Defaults from `countryCode` when missing. |
34
- | `shipmentFee` | number | No | Added once to the grand total. |
35
- | `items` | array | Yes | Each line item must satisfy the row UI (including **`image`**). |
36
-
37
- Each **`items[]`** entry extends the shared shop line type with a required **`image`** URL (or path) for the thumbnail.
38
-
39
- | Field | Type | Required | Notes |
40
- |-------|------|----------|--------|
41
- | `id` | string | Yes | Stable key for the `{#each}` block. |
42
- | `name` | string | Yes | Product title next to the image. |
43
- | `unitaryPrice` | number | Yes | Unit price before tax. |
44
- | `taxPercentage` | number | Yes | Percent applied per line (`8` means 8%). |
45
- | `quantity` | number | No | Defaults to `1` for subtotal and tax. |
46
- | `unit` | string | No | Part of shared `IShopItem`; not displayed in this template. |
47
- | `image` | string | Yes | `src` for the row thumbnail; exposed via `::part(item_image)`. |
48
-
49
- 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.
50
-
51
- ## Custom element
52
-
53
- `hb-order-list`
23
+ ```html
24
+ <hb-order-list …></hb-order-list>
25
+ ```
54
26
 
55
- ## Attributes (snake_case; string values in HTML)
27
+ ## Attributes (HTML / reflected props)
56
28
 
57
- 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).
29
+ Web component attributes are **strings** (snake_case). Structured data is a **JSON** string on **`payment`**.
58
30
 
59
- | Attribute | Required | Description |
60
- |-----------|----------|-------------|
61
- | `id` | No | Optional host identifier. |
62
- | `style` | No | Optional inline host styles (present on the public `Component` type). |
63
- | `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. |
31
+ | Attribute | Role |
32
+ |-----------|------|
33
+ | `id` | Optional host id. |
34
+ | `style` | Optional inline style on the host. |
35
+ | `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. |
64
36
 
65
37
  ## Events
66
38
 
67
- None. `Events` in `types/webcomponent.type.d.ts` is an empty object.
68
-
69
- ## Styling
70
-
71
- Registered theme hooks (see `extra/docs.ts` / `styleSetup`):
39
+ No custom events (`Events` is `{}` in `types/webcomponent.type.d.ts`).
72
40
 
73
- | CSS variable | Role |
74
- |--------------|------|
75
- | `--bulma-text` | Foreground for order number, names, totals, and body copy. |
76
- | `--bulma-scheme-main` | Surface / background. |
77
- | `--bulma-column-gap` | Horizontal gap between Bulma columns. |
41
+ ## CSS custom properties, parts, and slots
78
42
 
79
- ## CSS parts
43
+ **Documented variables** (`extra/docs.ts` / `styleSetup`):
80
44
 
81
- | Part | Target |
82
- |------|--------|
83
- | `item_image` | The `<img>` thumbnail for each line item (`part="item_image"`). |
45
+ | Variable | Default | Notes |
46
+ |----------|---------|--------|
47
+ | `--bulma-text` | `#363636` | Foreground for copy and totals. |
48
+ | `--bulma-scheme-main` | `#ffffff` | Surface background. |
49
+ | `--bulma-column-gap` | `0.75rem` | Column gutter. |
84
50
 
85
- ## HTML slots
51
+ | `::part` | Role |
52
+ |---------|------|
53
+ | `item_image` | Line item `<img>` thumbnail. |
86
54
 
87
- None.
55
+ **Slots:** none.
88
56
 
89
- ## Usage notes
57
+ ## TypeScript typings (authoring)
90
58
 
91
- - Serialize **`payment`** as one JSON string on the attribute; escape quotes for inline HTML or build the string in JavaScript.
92
- - Ensure every item includes **`image`**, **`id`**, **`name`**, **`unitaryPrice`**, and **`taxPercentage`** so totals and rows stay consistent with the typings.
93
- - Country and currency should stay aligned (`countryCode` + optional `currencySymbol`) for a coherent footer.
59
+ From `types/webcomponent.type.d.ts` (see that file for **`OrderPayment`** and line item shapes):
94
60
 
95
- ## Examples
61
+ ```ts
62
+ export type Component = {
63
+ id?: string;
64
+ style?: string;
65
+ payment?: OrderPayment | string;
66
+ };
67
+ export type Events = {};
68
+ ```
96
69
 
97
- ### Minimal order
70
+ ## Minimal HTML
98
71
 
99
72
  ```html
100
73
  <hb-order-list
@@ -102,16 +75,10 @@ None.
102
75
  ></hb-order-list>
103
76
  ```
104
77
 
105
- ### Order with shipment fee and explicit currency
78
+ With shipment fee:
106
79
 
107
80
  ```html
108
81
  <hb-order-list
109
- 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"}]}'
82
+ 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"}]}'
110
83
  ></hb-order-list>
111
84
  ```
112
-
113
- ## Related files
114
-
115
- - `component.wc.svelte` — markup and total calculation.
116
- - `types/webcomponent.type.d.ts` — `Component`, `OrderPayment`, and item typing.
117
- - `extra/docs.ts` — Storybook args, `styleSetup`, and named examples (`default`, `withShipment`, `singleItem`, `usd`).