hb-page-checkout — integrator guide

Category: commerce · Tags: commerce, checkout, page · Package: @htmlbricks/hb-page-checkout

Summary

hb-page-checkout is a full-width checkout page shell that places the interactive checkout flow beside the order summary. The main column renders hb-checkout (billing or shipping identity, shipment choice, gateways, and payment). The side column renders hb-checkout-shopping-cart with the same payment payload so totals stay aligned.

The host supplies structured data as JSON strings (or objects when using the element from JavaScript) for shipments, gateways, and payment. The component normalizes totals on each reactive update: it derives payment.shipmentFee from the selected or standard shipment when applicable, sums each line as unitaryPrice × (quantity ?? 1) plus tax, adds the shipment fee, rounds the total to two decimals, and assigns payment.currencyCode from an internal mapping (the current implementation resolves every countryCode branch to EUR). Nested children receive stringified shipments, gateways, and payment where their APIs expect serialized props.

Shipment line selection triggered by hb-checkout is handled inside this page (saveShipment): it updates the local shipments array, clears other selections, sets payment.shipmentFee, and does not emit a dedicated saveShipment event to the host. saveUser and paymentCompleted are forwarded to the host unchanged when the child checkout dispatches them. After a successful payment completion detail, the page sets its own completed state to yes and reuses that for both columns.

Custom element tag

<hb-page-checkout …></hb-page-checkout>

Layout and markup

• Bulma container is-fluid with columns; checkout uses column is-7, cart column is-5 (see styles/webcomponent.scss for responsive tweaks).
• No HTML slots and no ::part hooks (see extra/docs.ts).

Attributes (snake_case; HTML values are strings)

Web components reflect string attributes. Complex fields must be JSON. Booleans use yes / no where noted.

| Attribute | Required | Description | |-----------|----------|-------------| | id | No | Optional element id. | | style | No | Present on the public Component type for parity with other packages; the current implementation does not apply a dedicated style prop to the layout (theme via CSS variables instead). | | shipments | No | JSON array of IShipment objects (defaults to []). Parsed when provided as a string. See builder/src/wc/checkout/types/webcomponent.type.d.ts. | | user | Yes | IUser object or JSON string. Forwarded to hb-checkout. | | payment | No | JSON object combining IShoppingPayment and IPayment. Defaults internally to an empty cart with EUR / IT if omitted. See builder/src/wc/checkout-shopping-cart/types/webcomponent.type.d.ts and builder/src/wc/checkout/types/webcomponent.type.d.ts. | | gateways | No | JSON array of IGateway entries (id: paypal | google, labels, optional PayPal / Google Pay fields). Defaults to []. | | completed | No | yes or no. Drives completion UI for both embedded components; set to yes locally after a successful paymentCompleted from checkout. |

Shipment and totals

• If any shipment has selected or standard, payment.shipmentFee is overwritten in an effect with the price of the selected row, or otherwise the standard row.
• payment.total is recalculated as the sum of line totals (including tax) plus payment.shipmentFee (or 0).

Gateways

IGateway supports PayPal (paypalid, …) and Google Pay (gatewayId, gatewayMerchantId, …). Match the shapes expected by hb-checkout / hb-payment-paypal.

Events

| Event | detail | |-------|----------| | saveUser | IUser — updated customer payload from hb-checkout. | | paymentCompleted | { total: number; method: string; completed: true } — emitted when checkout reports a completed payment; the page also sets completed to yes. |

There is no saveShipment event at the page level; selection is kept in the host-provided shipments prop state inside the component.

Styling

The host uses Bulma 1.x CSS variables on :host; nested hb-* widgets inherit compatible --bulma-* tokens. Public variables documented in extra/docs.ts:

| Variable | Role | |----------|------| | --bulma-column-gap | Horizontal gap between checkout and cart columns (default 0.75rem). | | --bulma-text | Base text color inherited by nested checkout UI. | | --bulma-scheme-main | Background inside the page shell. | | --hb-checkout-border | Border around the cart column (also forwarded for related inner nodes). |

See Bulma CSS variables for the full token set.

Bundle dependencies

Publishing metadata lists hb-checkout and hb-checkout-shopping-cart (and their transitive tree: forms, inputs, table, PayPal, dialogs, etc.). Load compatible versions of those packages alongside this element.

Minimal HTML example

<hb-page-checkout
  shipments="[]"
  user='{"fullName":"Jane Doe","addressWithNumber":"Via Roma 1","city":"Rome","nationality":"IT","zip":"00100","fixed":true}'
  payment='{"countryCode":"IT","merchantName":"Demo Shop","currencyCode":"EUR","total":12.2,"items":[{"id":"a","name":"Item A","unitaryPrice":10,"taxPercentage":22,"quantity":1}]}'
  gateways='[{"id":"paypal","label":"PayPal","paypalid":"YOUR_CLIENT_ID"}]'
  completed="no"
></hb-page-checkout>

TypeScript typings (authoring)

See types/webcomponent.type.d.ts: Component (optional shipments, payment, gateways as objects or JSON strings; user as IUser or string; completed) and Events (saveUser, paymentCompleted).