SIR reference
On this page
- Contract
- Islands
- add-to-cart
- cart-drawer
- qty-stepper
- carousel
- accordion
- image-gallery
- wishlist-toggle
- search
- variant-picker
- Other helpers
- Events
- Shared values
- Detail and data shapes
- CartAddDetail
- CartErrorDetail
- WishlistToggleDetail
- CartLineUpdateDetail
- CartLineRemoveDetail
- CustomerDetail
- WishlistDetail
- ProfileSaveDetail
- AddressSaveDetail
- WishlistRemoveDetail
- ReviewSubmitDetail
- AccountSavedDetail
- AccountErrorDetail
- VariantChangeDetail
- VariantData
- VariantMoney
- ThemeAddress
SIR (Storefront Interaction Runtime) is the host-shipped script that makes server-rendered markup interactive with no theme JavaScript: mark an element with data-bp-island="<name>" and the attributes below, and the runtime wires it up. This page is generated from the normative contract, packages/sir/src/contract.ts, and the typed helpers in packages/theme/src/sir.ts. For when to use SIR rather than a React island, read Interactivity.
Contract
| What | Value |
|---|---|
Contract version (SIR_CONTRACT_VERSION) |
1 |
Island attribute (ISLAND_ATTR) |
data-bp-island |
Enhanced marker (ENHANCED_ATTR) |
data-bp-enhanced: set on a root once wired, so re-scans never wire it twice |
| Islands | add-to-cart, cart-drawer, qty-stepper, carousel, accordion, image-gallery, wishlist-toggle, search, variant-picker |
A theme targets a contract version (manifest.sirContractVersion); the host accepts it when that is at most its own SIR_CONTRACT_VERSION. Attributes are read exactly as listed: anything else on the element is ignored. Every helper returns plain attributes to spread on the element; undefined optional values are left out:
import { sir } from '@bizzpocket/theme';
<div {...sir.accordion({ 'data-single': 'true' })}>...</div>Islands
| Island | Helper | Behaviour source |
|---|---|---|
add-to-cart |
sir.addToCart() |
behaviors/add-to-cart.ts |
cart-drawer |
sir.cartDrawer() |
behaviors/cart-drawer.ts |
qty-stepper |
sir.qtyStepper() |
behaviors/qty-stepper.ts |
carousel |
sir.carousel() |
behaviors/carousel.ts |
accordion |
sir.accordion() |
behaviors/accordion.ts |
image-gallery |
sir.imageGallery() |
behaviors/image-gallery.ts |
wishlist-toggle |
sir.wishlistToggle() |
behaviors/wishlist-toggle.ts |
search |
sir.search() |
behaviors/search.ts |
variant-picker |
sir.variantPicker() |
behaviors/variant-picker.ts |
add-to-cart
A button (or element) that adds a product to the cart. On activation it dispatches bizzpocket:cart:add; the runtime's cart bridge turns that into a real cart mutation (cartClient.addItem) which in turn opens the drawer via the existing bizzpocket:cart:open event.
Helper: sir.addToCart(attrs) → data-bp-island="add-to-cart" plus the attributes you pass (type AddToCartAttrs).
| Attribute | Required | Value | Meaning |
|---|---|---|---|
data-product-id |
yes | string |
Required. Product id to add. |
data-variant-id |
no | string |
Optional selected variant id. |
data-qty |
no | string |
Optional quantity (defaults to 1). Read as an integer >= 1. |
data-handle |
no | string |
Optional product handle/slug. Forwarded to cartClient.addItem so /api/cart/items can resolve the authoritative server-side price instead of falling back to the deterministic guest stub price. |
data-label-add |
no | string |
Inside a variant-picker: the label for an in-stock variant. |
data-label-oos |
no | string |
Inside a variant-picker: the label for an out-of-stock variant. |
data-label-select |
no | string |
Inside a variant-picker: the label while not every option is chosen. |
cart-drawer
An element (typically the header cart button) that opens the existing persistent CartDrawer by dispatching bizzpocket:cart:open.
Helper: sir.cartDrawer(attrs) → data-bp-island="cart-drawer" plus the attributes you pass (type CartDrawerAttrs).
No attributes besides the island marker.
qty-stepper
A − / value / + control. The runtime wires the buttons and keeps an input (or text node) in sync, emitting a native change event and a bizzpocket:qty:change CustomEvent on the root.
Expected child markup (matched by attribute, not tag):
[data-bp-qty-decrement]— the minus button[data-bp-qty-increment]— the plus button[data-bp-qty-input]— an <input> whose value holds the quantity (falls back to text content if not an input)
It feeds add-to-cart: on enhance and on every change it writes its value to the data-qty of the add-to-cart buttons it is linked to. A link is either data-bp-qty-for="<productId>" (every [data-bp-island="add-to-cart"] with that data-product-id, anywhere on the page), or, without one, the add-to-cart buttons inside the stepper's product root: its nearest [data-bp-product-root] or variant-picker root. A stepper in no product root (a cart line) feeds nothing.
Helper: sir.qtyStepper(attrs) → data-bp-island="qty-stepper" plus the attributes you pass (type QtyStepperAttrs).
| Attribute | Required | Value | Meaning |
|---|---|---|---|
data-min |
no | string |
Optional minimum (default 1). |
data-max |
no | string |
Optional maximum (default Infinity). |
data-step |
no | string |
Optional step (default 1). |
data-bp-qty-for |
no | string |
Optional: the product id of the add-to-cart button(s) this stepper sets the quantity of. |
carousel
A horizontal scroll/snap track with prev/next controls, keyboard support and aria. Respects prefers-reduced-motion (jumps instead of smooth).
Expected child markup:
[data-bp-carousel-track]— the scrollable container (role applied here)[data-bp-carousel-prev]— previous button[data-bp-carousel-next]— next button[data-bp-carousel-dots]— optional, empty: filled with one dot button per slide (each child of the track); the visible slide's dot getsaria-current.
At the start (end) of the track, prev (next) gets disabled and aria-disabled="true"; both update on scroll and resize.
Helper: sir.carousel(attrs) → data-bp-island="carousel" plus the attributes you pass (type CarouselAttrs).
| Attribute | Required | Value | Meaning |
|---|---|---|---|
data-step-px |
no | string |
Optional scroll amount in px per step (default = track clientWidth * 0.9). |
accordion
Expand/collapse sections with aria-expanded + keyboard.
Expected child markup (one or more pairs):
[data-bp-accordion-trigger]— the header button;aria-controlsSHOULD point at the panel id (else the runtime falls back to the next sibling).[data-bp-accordion-panel]— the collapsible region.
Helper: sir.accordion(attrs) → data-bp-island="accordion" plus the attributes you pass (type AccordionAttrs).
| Attribute | Required | Value | Meaning |
|---|---|---|---|
data-single |
no | 'true' | 'false' |
When 'true', only one panel may be open at a time. |
image-gallery
Thumbnails that swap the main image's src/srcset/sizes/alt.
Expected child markup:
[data-bp-gallery-main]— the main <img>.[data-bp-gallery-thumb]— each thumbnail; carries the full-size source indata-src, and optionallydata-srcset/data-sizes/data-alt. May be a button or an <img>.
A thumb without data-srcset removes the main image's srcset, so its data-src shows (a srcset would override the swap). A main image inside a <picture> loses the picture's <source>s on the first swap, for the same reason. An unsafe URL in data-srcset drops that srcset.
Helper: sir.imageGallery(attrs) → data-bp-island="image-gallery" plus the attributes you pass (type ImageGalleryAttrs).
No attributes besides the island marker.
Child elements (ImageGalleryThumbAttrs): Per-thumb attributes for image-gallery.
| Attribute | Required | Value | Meaning |
|---|---|---|---|
data-bp-gallery-thumb |
yes | '' |
|
data-src |
yes | string |
Required full-size image source to swap into the main image. |
data-srcset |
no | string |
Optional srcset for the main image after the swap (e.g. responsiveImage(...).srcSet). |
data-sizes |
no | string |
Optional sizes for the main image after the swap. |
data-alt |
no | string |
Optional alt text for the main image after swap. |
wishlist-toggle
Toggles a product's wishlist state. Reflects state via aria-pressed, dispatches bizzpocket:wishlist:toggle, and calls the existing customer-account wishlist endpoint. Its opening state is the shopper's: it asks once with bizzpocket:wishlist:request and sets aria-pressed / data-wished from every bizzpocket:wishlist:updated.
Helper: sir.wishlistToggle(attrs) → data-bp-island="wishlist-toggle" plus the attributes you pass (type WishlistToggleAttrs).
| Attribute | Required | Value | Meaning |
|---|---|---|---|
data-product-id |
yes | string |
Required product id. |
data-wished |
no | 'true' | 'false' |
Optional initial state ('true' = already wished). Mirrors aria-pressed. |
search
A search form/control that navigates to the existing /search?q= route on submit.
Expected child markup:
[data-bp-search-input]— the text input holding the query. The root may be a <form>; if so, submit is intercepted.
Helper: sir.search(attrs) → data-bp-island="search" plus the attributes you pass (type SearchAttrs).
| Attribute | Required | Value | Meaning |
|---|---|---|---|
data-action |
no | string |
Optional target route (default '/search'). The query is sent as ?q=. |
variant-picker
Option buttons that choose a product variant, with no React.
Expected markup inside the root (matched by attribute, not tag):
<script type="application/json" data-bp-variant-data>: a JSON array ofVariantData. Required; without it the root is a no-op.- option buttons,
VariantOptionAttrs. Buttons of one option name are one radio group: arrow keys move the choice, one tab stop per group. The state attribute isaria-checkedon arole="radio"button, elsearia-pressed. A value no in-stock variant can reach getsdata-unavailable=""+aria-disabled="true"and stays focusable; picking it still selects it (the button then says out of stock). - optional targets, each updated on a pick:
[data-bp-variant-price]: text = the price, formatted withIntl.NumberFormat(data-locale, { style: 'currency' })like<Money>;[data-bp-variant-compare]: the compare-at price;hiddenwhen none;[data-bp-variant-sku]: the SKU;[data-bp-variant-stock]:data-label-in-stock/data-label-out-of-stock;- an empty value hides the target's closest
[data-bp-variant-row](else the target); - the add-to-cart island (
data-bp-island="add-to-cart"): itsdata-variant-idis set, it isdisabledunless the variant is in stock, and its text (or its[data-bp-variant-label]child) becomesdata-label-add,data-label-oosordata-label-select; [data-bp-variant-live]: a polite live region that announces the price and stock; the runtime adds a visually hidden one when absent.
- the main picture may live anywhere on the page:
<img data-bp-variant-image-for="<productId>">gets the variant'ssrc/srcset/alt.
Opening state: ?variant=<id> when it names a variant, else the options of the buttons the server rendered as selected (render the first in-stock variant, so nothing changes when the runtime starts). A pick writes ?variant=<id> with history.replaceState (unless data-update-url="false"), dispatches bizzpocket:variant:change and sets the shared key variant:<productId> (see SHARED_STORE_KEY).
Helper: sir.variantPicker(attrs) → data-bp-island="variant-picker" plus the attributes you pass (type VariantPickerAttrs).
| Attribute | Required | Value | Meaning |
|---|---|---|---|
data-product-id |
yes | string |
Required. The product id, used in events and to find the main image. |
data-locale |
no | string |
BCP 47 locale for prices (default: the browser's). Use the one your server <Money> used. |
data-update-url |
no | 'true' | 'false' |
'false' keeps the URL as it is (e.g. a quick-view card). |
Child elements (VariantOptionAttrs): One option value button inside a variant-picker root.
| Attribute | Required | Value | Meaning |
|---|---|---|---|
data-bp-variant-option |
yes | string |
The option name, e.g. Size. |
data-value |
yes | string |
The value, e.g. M. |
Other helpers
Besides one helper per island, sir has:
| Helper | What it does |
|---|---|
sir.variantState(variants: ReadonlyArray<V>) |
The opening state for server rendering: the first in-stock variant chosen, values no in-stock variant reaches marked unavailable. The SIR behaviour starts from the same state, so nothing moves when it wakes up. |
sir.variantOption(o: { name: string; value: string; selected: boolean; unavailable?: boolean }) |
One option value button: <button type="button" {...sir.variantOption({ name, value, selected })}>. |
sir.variantGroup(name: string) |
One option group (a radio group the arrow keys move inside). |
sir.variantData(variants: ReadonlyArray<VariantData>) |
The variant table: <script {...sir.variantData(variants)} />, inside the variantPicker root. |
sir.variantTarget(target: VariantTarget) |
Mark an element the pick updates: <span {...sir.variantTarget('price')}>. |
sir.variantImage(productId: string) |
The main <img>, anywhere on the page: its src/srcset/alt follow the chosen variant. |
sir.imageGalleryThumb(attrs: Omit<ImageGalleryThumbAttrs, 'data-bp-gallery-thumb'>) |
Per-thumbnail attributes inside an imageGallery root (no island marker). |
Events
Every event is a CustomEvent on window (SIR_EVENTS in the contract). "Theme → host" events are requests a theme may dispatch; "host → theme" events are answers to listen for.
| Event | Constant | detail |
Meaning |
|---|---|---|---|
bizzpocket:cart:add |
SIR_EVENTS.cartAdd |
CartAddDetail |
add-to-cart island → request an add. Existing event (wishlist view dispatches it too). |
bizzpocket:cart:open |
SIR_EVENTS.cartOpen |
— | Open the persistent CartDrawer. Existing event (cart-drawer.tsx listens). |
bizzpocket:cart:updated |
SIR_EVENTS.cartUpdated |
— | Cart mutated; carries the fresh (host-shaped) Cart in detail. Existing event. |
bizzpocket:cart:request |
SIR_EVENTS.cartRequest |
— | Theme → host: "tell me the current cart". The host answers with a cart:updated carrying it. For an island that mounts AFTER the boot sync already fired — a header inside a streamed Suspense boundary mounts late — which otherwise shows no count until the next mutation. |
bizzpocket:cart:error |
SIR_EVENTS.cartError |
CartErrorDetail |
Host → theme: a cart:add failed. Carries CartErrorDetail — the backend's error code (e.g. VARIANT_REQUIRED, OUT_OF_STOCK) and a shopper-readable message, so the theme can say why instead of the button silently doing nothing. |
bizzpocket:wishlist:toggle |
SIR_EVENTS.wishlistToggle |
WishlistToggleDetail |
Wishlist toggled; carries { productId, wished }. |
bizzpocket:cart:update |
SIR_EVENTS.cartLineUpdate |
CartLineUpdateDetail |
A theme cart block requests a line-quantity change. Per docs/migration/COMMERCE-BLOCKS-SPEC.md ("Host-integration = CustomEvent ports"); carries { lineId, quantity }. The cart bridge forwards this to cartClient.updateQty. |
bizzpocket:cart:remove |
SIR_EVENTS.cartLineRemove |
CartLineRemoveDetail |
A theme cart block requests a line removal; carries { lineId }. |
bizzpocket:cart:synced |
SIR_EVENTS.cartSynced |
— | Host → theme: the cart was re-synced with authoritative data after a line mutation. Carries the THEME-shaped { lines, totals } (the same shape as the cart block's initialCart prop — see lib/theme-render/commerce-props.ts). CartArtcraft (and themes following the same spec) listen for this to refresh in place. |
bizzpocket:customer:updated |
SIR_EVENTS.customerUpdated |
CustomerDetail |
Host → theme: the signed-in shopper (or null for a guest). Carries CustomerDetail. Read by useCustomer() in @bizzpocket/theme/client. |
bizzpocket:customer:request |
SIR_EVENTS.customerRequest |
— | Theme → host: "tell me the current customer"; answered with customer:updated. |
bizzpocket:wishlist:updated |
SIR_EVENTS.wishlistUpdated |
WishlistDetail |
Host → theme: the wishlist's product ids. Carries WishlistDetail. Read by useWishlist() in @bizzpocket/theme/client. |
bizzpocket:wishlist:request |
SIR_EVENTS.wishlistRequest |
— | Theme → host: "tell me the current wishlist"; answered with wishlist:updated. |
bizzpocket:profile:save |
SIR_EVENTS.profileSave |
ProfileSaveDetail |
Theme account block → save profile fields (+ optional password change). |
bizzpocket:address:save |
SIR_EVENTS.addressSave |
AddressSaveDetail |
Theme account block → create/update/delete a saved address. |
bizzpocket:wishlist:remove |
SIR_EVENTS.wishlistRemove |
WishlistRemoveDetail |
Theme wishlist grid → remove a product from the wishlist. |
bizzpocket:review:submit |
SIR_EVENTS.reviewSubmit |
ReviewSubmitDetail |
Theme PDP → submit a product review (persisted pending seller approval). |
bizzpocket:account:saved |
SIR_EVENTS.accountSaved |
AccountSavedDetail |
Host → theme: an account write succeeded. Carries AccountSavedDetail. |
bizzpocket:account:error |
SIR_EVENTS.accountError |
AccountErrorDetail |
Host → theme: an account write failed. Carries AccountErrorDetail. |
bizzpocket:variant:change |
SIR_EVENTS.variantChange |
VariantChangeDetail |
variant-picker → page: the shopper picked a variant (or a combination with none). Carries VariantChangeDetail. Not fired for the opening state. |
bizzpocket:qty:change |
QTY_CHANGE_EVENT (qty-stepper.ts) |
— | qty-stepper → its root: the quantity changed (detail: { value }, bubbles). A native change fires on the input too. |
bizzpocket:ring-sizer:change |
RING_SIZER_CHANGE_EVENT (line-attributes.ts) |
— | Theme → host, on window: a ring sizer changed, detail: { productId?, mm }. The next add of that product (without productId: the next add on this page) gets a ring_size cart-line attribute. |
bizzpocket:engraving:change |
ENGRAVING_CHANGE_EVENT (line-attributes.ts) |
— | Theme → host, on window: an engraving form changed, detail: { value } or { productId, state: { text?, font?, position? } }. Becomes the engraving cart-line attribute; a cleared text removes it. |
Shared values
Page-wide shared values (read by useShared() in @bizzpocket/theme/client). The store is globalThis[SHARED_STORE_KEY], a Map<string, unknown> that whoever writes first creates. A writer sets map.set(key, value) and then dispatches new CustomEvent(sharedEvent(key), { detail: value }) on window. Living on globalThis (not in a module) lets separately bundled islands and the SIR runtime share it. The store key is __bpShared; the event for a key is bizzpocket:shared:<key> (sharedEvent(key)); variant-picker writes variant:<productId> (variantSharedKey(productId)). Read them with useShared() from @bizzpocket/theme/client.
Detail and data shapes
CartAddDetail
detail shape of bizzpocket:cart:add (matches the wishlist view's dispatch). handle is OPTIONAL because not every dispatcher sends it (e.g. ProductDetailArtcraft's PDP add-to-cart omits it) — the cart bridge falls back to the current PDP route's handle when absent (see cart-bridge.ts). When present, it lets /api/cart/items resolve the AUTHORITATIVE server-side price instead of the deterministic guest stub (cart-store.ts's resolvePrice).
| Field | Required | Type | Meaning |
|---|---|---|---|
productId |
yes | string |
|
variantId |
no | string |
|
quantity |
yes | number |
|
handle |
no | string |
|
attributes |
no | Record<string, string> |
Optional cart-line attributes (≤ 5 snake_case keys, ≤ 120 chars each), merged over what the host captured from the page's configurators (ring_size, engraving — see line-attributes.ts). |
CartErrorDetail
detail shape of bizzpocket:cart:error.
| Field | Required | Type | Meaning |
|---|---|---|---|
productId |
yes | string |
'' for a failed line update / remove (see lineId). |
variantId |
no | string |
|
lineId |
no | string |
The cart line, when a cart:update / cart:remove failed. |
code |
yes | string |
Backend error code; UNKNOWN when the failure carried none (network). |
message |
yes | string |
WishlistToggleDetail
detail shape of bizzpocket:wishlist:toggle.
| Field | Required | Type | Meaning |
|---|---|---|---|
productId |
yes | string |
|
wished |
yes | boolean |
CartLineUpdateDetail
detail shape of bizzpocket:cart:update.
| Field | Required | Type | Meaning |
|---|---|---|---|
lineId |
yes | string |
|
quantity |
yes | number |
CartLineRemoveDetail
detail shape of bizzpocket:cart:remove.
| Field | Required | Type | Meaning |
|---|---|---|---|
lineId |
yes | string |
CustomerDetail
SIR — Storefront Interaction Runtime, contract v1. This file IS the normative contract (spec §3.6). Marketplace themes are SSR-only and ship ZERO third-party client JS; all interactivity comes from this host-shipped, always-loaded runtime, which progressively enhances server-rendered markup carrying stable data-bp-island="<name>" hooks. First-party themes MAY also use it. The contract is expressed as TYPES + the const tables below — there is no separate doc file. Each island's expected data-* attributes are described by its *Attrs interface; the runtime reads exactly these attributes and nothing else, so a theme author can rely on this file as the source of truth. Versioning: a theme declares the SIR contract version it targets (manifest.sirContractVersion); the host accepts it only if sirContractVersion <= SIR_CONTRACT_VERSION (spec §3.5). Bumping this number is a breaking change to the declarative surface below. / /** Normative contract version. Bump on any breaking change to the surface below. / export const SIR_CONTRACT_VERSION = 1 as const; /* The fixed set of v1 island names (spec §3.6). / export const SIR_ISLANDS = [ 'add-to-cart', 'cart-drawer', 'qty-stepper', 'carousel', 'accordion', 'image-gallery', 'wishlist-toggle', 'search', // Additive (SDK 3.1): no contract-version bump, a v1 theme that does not use it is unaffected. 'variant-picker', ] as const; export type SirIslandName = (typeof SIR_ISLANDS)[number]; /* The attribute every island root carries. / export const ISLAND_ATTR = 'data-bp-island' as const; /* Marker set on a root once enhanced, to keep re-scans idempotent. / export const ENHANCED_ATTR = 'data-bp-enhanced' as const; /* CustomEvents the runtime emits/consumes. These names are REUSED from the existing storefront (cart-client.ts, cart-drawer.tsx, wishlist view) — the runtime does not invent a parallel mechanism. All are dispatched on window. / export const SIR_EVENTS = { /** add-to-cart island → request an add. Existing event (wishlist view dispatches it too). / cartAdd: 'bizzpocket:cart:add', /* Open the persistent CartDrawer. Existing event (cart-drawer.tsx listens). / cartOpen: 'bizzpocket:cart:open', /* Cart mutated; carries the fresh (host-shaped) Cart in detail. Existing event. / cartUpdated: 'bizzpocket:cart:updated', /* Theme → host: "tell me the current cart". The host answers with a cart:updated carrying it. For an island that mounts AFTER the boot sync already fired — a header inside a streamed Suspense boundary mounts late — which otherwise shows no count until the next mutation. / cartRequest: 'bizzpocket:cart:request', /** Host → theme: a cart:add failed. Carries {@link CartErrorDetail} — the backend's error code (e.g. VARIANT_REQUIRED, OUT_OF_STOCK) and a shopper-readable message, so the theme can say why instead of the button silently doing nothing. / cartError: 'bizzpocket:cart:error', /** Wishlist toggled; carries { productId, wished }. / wishlistToggle: 'bizzpocket:wishlist:toggle', /* A theme cart block requests a line-quantity change. Per docs/migration/COMMERCE-BLOCKS-SPEC.md ("Host-integration = CustomEvent ports"); carries { lineId, quantity }. The cart bridge forwards this to cartClient.updateQty. / cartLineUpdate: 'bizzpocket:cart:update', /** A theme cart block requests a line removal; carries { lineId }. / cartLineRemove: 'bizzpocket:cart:remove', /* Host → theme: the cart was re-synced with authoritative data after a line mutation. Carries the THEME-shaped { lines, totals } (the same shape as the cart block's initialCart prop — see lib/theme-render/commerce-props.ts). CartArtcraft (and themes following the same spec) listen for this to refresh in place. / cartSynced: 'bizzpocket:cart:synced', // bizzpocket:checkout:{submit,pending,success,error} were removed with the // theme checkout-form blocks: /checkout is the platform smart checkout // (spec 2026-10-06 §5.2), which places orders itself — no theme dispatches // or listens to a checkout event any more. /** Host → theme: the signed-in shopper (or null for a guest). Carries {@link CustomerDetail}. Read by useCustomer() in @bizzpocket/theme/client. / customerUpdated: 'bizzpocket:customer:updated', /** Theme → host: "tell me the current customer"; answered with customer:updated. / customerRequest: 'bizzpocket:customer:request', /* Host → theme: the wishlist's product ids. Carries {@link WishlistDetail}. Read by useWishlist() in @bizzpocket/theme/client. / wishlistUpdated: 'bizzpocket:wishlist:updated', /** Theme → host: "tell me the current wishlist"; answered with wishlist:updated. / wishlistRequest: 'bizzpocket:wishlist:request', /* Theme account block → save profile fields (+ optional password change). / profileSave: 'bizzpocket:profile:save', /* Theme account block → create/update/delete a saved address. / addressSave: 'bizzpocket:address:save', /* Theme wishlist grid → remove a product from the wishlist. / wishlistRemove: 'bizzpocket:wishlist:remove', /* Theme PDP → submit a product review (persisted pending seller approval). / reviewSubmit: 'bizzpocket:review:submit', /* Host → theme: an account write succeeded. Carries AccountSavedDetail. / accountSaved: 'bizzpocket:account:saved', /* Host → theme: an account write failed. Carries AccountErrorDetail. / accountError: 'bizzpocket:account:error', /* variant-picker → page: the shopper picked a variant (or a combination with none). Carries {@link VariantChangeDetail}. Not fired for the opening state. / variantChange: 'bizzpocket:variant:change', } as const; /** Page-wide shared values (read by useShared() in @bizzpocket/theme/client). The store is globalThis[SHARED_STORE_KEY], a Map<string, unknown> that whoever writes first creates. A writer sets map.set(key, value) and then dispatches new CustomEvent(sharedEvent(key), { detail: value }) on window. Living on globalThis (not in a module) lets separately bundled islands and the SIR runtime share it. / export const SHARED_STORE_KEY = '__bpShared' as const; /** The window event announcing a new value for a shared key: bizzpocket:shared:<key>. / export function sharedEvent(key: string): string { return bizzpocket:shared:${key}; } /* The shared key variant-picker writes: variant:<productId>. Its value is the {@link VariantChangeDetail} of the current choice (also set for the opening state, so an island that mounts later reads it). / export function variantSharedKey(productId: string): string { return variant:${productId}; } /** A money value in a variant table. amount is in major units (649.5). / export interface VariantMoney { amount: number; /* ISO 4217 code, e.g. INR. / currency: string; } /* One row of the variant table a variant-picker root carries in its <script type="application/json" data-bp-variant-data>. / export interface VariantData { id: string; /** Option name → value, e.g. { Size: 'M', Colour: 'Red' }. / options: Record<string, string>; price: VariantMoney; compareAtPrice?: VariantMoney | null; sku?: string | null; inStock: boolean; /* The variant's own picture. Without one, the main image goes back to what the page opened with. / image?: { src: string; alt: string; srcset?: string } | null; } /* detail of bizzpocket:variant:change, and the value of the variant:<productId> shared key. / export interface VariantChangeDetail { productId: string; /* null when the chosen options match no variant (or not every option is chosen). / variantId: string | null; variant: VariantData | null; } /* detail shape of bizzpocket:cart:add (matches the wishlist view's dispatch). handle is OPTIONAL because not every dispatcher sends it (e.g. ProductDetailArtcraft's PDP add-to-cart omits it) — the cart bridge falls back to the current PDP route's handle when absent (see cart-bridge.ts). When present, it lets /api/cart/items resolve the AUTHORITATIVE server-side price instead of the deterministic guest stub (cart-store.ts's resolvePrice). / export interface CartAddDetail { productId: string; variantId?: string; quantity: number; handle?: string; /** Optional cart-line attributes (≤ 5 snake_case keys, ≤ 120 chars each), merged over what the host captured from the page's configurators (ring_size, engraving — see line-attributes.ts). / attributes?: Record<string, string>; } /** detail shape of bizzpocket:cart:error. / export interface CartErrorDetail { /* '' for a failed line update / remove (see lineId). / productId: string; variantId?: string; /* The cart line, when a cart:update / cart:remove failed. / lineId?: string; /* Backend error code; UNKNOWN when the failure carried none (network). / code: string; message: string; } /* detail of bizzpocket:customer:updated; null means a guest.
type CustomerDetail = {
id: string;WishlistDetail
detail of bizzpocket:wishlist:updated.
| Field | Required | Type | Meaning |
|---|---|---|---|
productIds |
yes | string[] |
ProfileSaveDetail
detail of bizzpocket:profile:save (see AccountDashboardArtcraft.handleProfileSave).
| Field | Required | Type | Meaning |
|---|---|---|---|
name |
yes | string |
|
email |
yes | string |
|
phone |
yes | string |
|
currentPassword |
no | string |
|
newPassword |
no | string |
|
confirmPassword |
no | string |
AddressSaveDetail
detail of bizzpocket:address:save.
| Field | Required | Type | Meaning |
|---|---|---|---|
address |
yes | ThemeAddress |
WishlistRemoveDetail
detail of bizzpocket:wishlist:remove (see WishlistGridArtcraft.handleRemove).
| Field | Required | Type | Meaning |
|---|---|---|---|
productId |
yes | string |
ReviewSubmitDetail
detail of bizzpocket:review:submit (see ProductDetailArtcraft.handleReviewSubmit).
| Field | Required | Type | Meaning |
|---|---|---|---|
productId |
yes | string |
|
rating |
yes | number |
|
comment |
no | string |
|
name |
no | string |
Present on the theme event but ignored server-side (identity comes from the session). |
email |
no | string |
|
handle |
no | string |
AccountSavedDetail
detail of bizzpocket:account:saved.
| Field | Required | Type | Meaning |
|---|---|---|---|
kind |
yes | 'profile' | 'address-add' | 'address-update' | 'address-delete' | 'wishlist-remove' | 'review' |
AccountErrorDetail
detail of bizzpocket:account:error.
| Field | Required | Type | Meaning |
|---|---|---|---|
kind |
yes | AccountSavedDetail['kind'] |
|
message |
yes | string |
VariantChangeDetail
detail of bizzpocket:variant:change, and the value of the variant:<productId> shared key.
| Field | Required | Type | Meaning |
|---|---|---|---|
productId |
yes | string |
|
variantId |
yes | string | null |
null when the chosen options match no variant (or not every option is chosen). |
variant |
yes | VariantData | null |
VariantData
One row of the variant table a variant-picker root carries in its <script type="application/json" data-bp-variant-data>.
| Field | Required | Type | Meaning |
|---|---|---|---|
id |
yes | string |
|
options |
yes | Record<string, string> |
Option name → value, e.g. { Size: 'M', Colour: 'Red' }. |
price |
yes | VariantMoney |
|
compareAtPrice |
no | VariantMoney | null |
|
sku |
no | string | null |
|
inStock |
yes | boolean |
|
image |
no | { src: string; alt: string; srcset?: string } | null |
The variant's own picture. Without one, the main image goes back to what the page opened with. |
VariantMoney
A money value in a variant table. amount is in major units (649.5).
| Field | Required | Type | Meaning |
|---|---|---|---|
amount |
yes | number |
|
currency |
yes | string |
ISO 4217 code, e.g. INR. |
ThemeAddress
Theme-shaped address as emitted by AccountDashboardArtcraft.handleSaveAddr. NOTE the field names differ from the backend's saved-address shape — the account bridge maps address1/address2/province/zip → line1/line2/state/ pincode before calling the proxy.
| Field | Required | Type | Meaning |
|---|---|---|---|
id |
yes | string |
|
firstName |
yes | string |
|
lastName |
yes | string |
|
company |
no | string |
|
address1 |
yes | string |
|
address2 |
no | string |
|
city |
yes | string |
|
province |
no | string |
|
zip |
yes | string |
|
country |
yes | string |
|
phone |
no | string |
|
_delete |
no | boolean |
Present + true when the intent is a delete (handleDeleteAddr). |