Blocks Storefront Pack

The storefront blocks for a shop that sells physical goods: the bag button with its rolling count, the bag drawer, and the real "Add to bag" control that catalog tiles and hero chips pick up. They sit on one shared client cart store and render nothing money-related of their own, because every price on screen is the server's.

@wabbit/tome-blocks-core and @wabbit/tome-storefront are required peers. The site also mounts storefront's route handlers (createStorefrontRouteHandlers) at /api/storefront/*, which is where the cart store's default transport sends its requests.

Register the blocks the usual way:

import { BlockRegistry, BundleRegistry } from '@wabbit/tome-blocks-core/registry'
import { register } from '@wabbit/tome-blocks-storefront-pack'

const blockRegistry = new BlockRegistry()
const bundleRegistry = new BundleRegistry()
register(blockRegistry, bundleRegistry)

Render them with the static renderers, or the hydrated ones (below):

import { renderers } from '@wabbit/tome-blocks-storefront-pack/render/register'

Mount the cart once

One provider per page, in a client component your layout renders around the header, the page and the bag drawer. StorefrontBagProvider mounts the cart store and registers the real Add to bag control in one step:

'use client'
import { StorefrontBagProvider } from '@wabbit/tome-blocks-storefront-pack/adapter'

export function Shop({ children, initial }) {
  return <StorefrontBagProvider initial={initial}>{children}</StorefrontBagProvider>
}

initial is the priced cart read on the server, so the first paint has the right count. Leave it out and the provider reads the cart once on mount.

Module surface

Peer dependencies

Generated from package.json#peerDependencies (the README gate fails if this table and the manifest disagree).

Blocks

Bag Button (storefront-cart-trigger)

Fields: label (default "Bag"), and an optional href that is where the button goes with JavaScript off or no cart provider. The same button is exported as the CartTrigger component for a header's cart slot. Hooks: data-cart-trigger, data-cart-label, data-cart-count (the odometer: data-count-roll, data-count-old, data-count-new, --tome-count-from, --tome-count-to).

Bag Drawer (storefront-cart-drawer)

Fields: heading, emptyState (title, line, link), suggest (count, heading), checkoutHref, checkoutLabel, freeShip (reachedLine), taxNote, shippingNote (the sentence after the tax note, default "Shipping is worked out at checkout."), afterLine, defaultCountry, countries[]. Authored copy wins: with the ./server hydration wired, the store's tax note fills taxNote and the labels of its "After the order" steps (one phrase: "Packed by the maker · shipped with tracking · arrives") fill afterLine only when those are empty; the store's served countries and default country are facts and always apply. Each line shows the product's edition (data-edition-tag, "Batch 14") after its variant when the store names an edition attribute. It is a real modal <dialog>: the page behind it is inert, Escape closes it, focus moves to the close button on open and returns to the control that opened it (or the bag button, if that control has gone). Removing a line under the keyboard keeps focus inside. Hooks: data-cart-drawer, data-drawer-state (open or closed), data-cart-line, data-line-thumb, data-line-name, data-line-variant, data-line-price, data-line-remove, data-line-problem, data-free-ship, data-free-ship-track, data-free-ship-fill (--tome-free-ship-from, --tome-free-ship-to), data-free-ship-reached, data-cart-suggest, data-cart-country, data-cart-totals, data-cart-tax-note, data-cart-checkout, data-cart-empty, data-empty-shelves, data-after-line.

Buy Box (storefront-buy-box)

Fields: productSlug (and optional productId), sku, href, kicker, title, headingLevel, makerLine, priceLabel, compareAtLabel, editionTag, addLabel, maxQuantity, axes[] (key, label, kind, options[] of value, label, swatch), variants[] (sku, priceLabel, compareAtLabel, options[] of axis, value), image, showAssurance, showFolds, folds[]; the featured variant also takes openerKicker, heading, moreLink, notes[] and notesLimit. Prices are labels the author wrote: nothing parses one, and an add sends only { productSlug | productId, variantSku, quantity }.

featured lays itself out on the page grid: its root (data-buy-featured) is a subgrid, so the opener's lanes resolve. On phones the opener, the plate (data-buy-featured-plate, a 4:5 frame), the box (data-buy-featured-box, around data-buy-box) and the margin notes (data-buy-featured-notes, also data-margin-notes) stack. From 768px the plate and the box sit side by side (four columns each) with the notes in three columns under them; from 1024px the plate runs from content-start to the prose line, the box takes the prose track and the notes stand in the right marginalia lane. The pack sets structure only; the well, the shelf line and the type are a theme's.

The picker is one radiogroup per axis (arrow keys move the choice). A choice that cannot be bought with the other axes as chosen carries data-unavailable, a strike-through and the spoken word "unavailable". On a phone, a buy bar is shown exactly when the main Add button's bottom edge is above the top of the viewport. The position is read on mount, on scroll and resize (once a frame), on a hash change and whenever an IntersectionObserver on the button reports, so a page opened already scrolled, a jump past the button and a jump back all land in the right state; hidden, it is inert; shown, the page reserves the room it covers. With the server hydration wired, SKU availability, the dispatch line ("Order by 2pm CT to ship today", else "Ships Tuesday"; only when the store has both a cutoff and a zone), the assurance row and a "Shipping and returns" fold come from the store. Hooks: data-buy-box, data-block-variant, data-buy-kicker, data-buy-name, data-buy-line, data-price, data-price-now, data-price-was, data-edition-tag, data-variant-axis, data-swatch and data-segment (role="radio", aria-checked, data-unavailable; product colour on --swatch), data-qty, data-buy-add (data-buy-add-state), data-availability-line, data-availability-segment="edition|stock|dispatch", data-availability, data-buy-assure, data-buy-folds, data-buy-bar, data-buy-bar-visible, data-restock.

Store Facts (storefront-store-facts)

Fields: layout (strip, assure, proof, steps, line), currentStep, kicker, heading, and fallback facts[] and steps[]. With the server hydration wired the words come from the store settings (the free-shipping threshold "before discounts", the returns summary, facts.extra, afterOrder.steps), but authored copy wins, as in the bag drawer: the store fills the rows only when the author left facts[] (or steps[]) empty, so a panel the author wrote ("Shipping", "Returns", "Help") is never replaced. Left empty, the strip, the product page, the bag drawer, the lookup page and the confirmation cannot disagree. The steps layout draws four built-in icons (packed, shipped, arrives, insert) as inline SVG on currentColor and can mark one step current. Hooks: data-store-facts, data-facts-layout, data-fact, data-fact-label, data-fact-text, data-step, data-step-icon, data-step-current.

Checkout Step (storefront-checkout-step)

Fields: heading, intro, continueLabel, paymentNote, signInHref, signInLabel, emptyState (title, line, link), demoBanner, taxNote, defaultCountry, countries[]. The summary is the cart store's priced cart; the step posts { email?, shipCountry } to ${basePath}/checkout and never an amount. A redirect answer re-reads the bag and leaves for the payment page; a blocked or sold-out answer is shown in words beside the button (an alert that takes focus), and a 503, 429 or 400 shows fixed safe copy, never the server's own text. Hooks: data-checkout-step (data-checkout-state), data-checkout-summary, data-checkout-email, data-checkout-country, data-checkout-continue, data-checkout-blocked.

Order Confirmation (storefront-order-confirmation)

Fields: pendingHeading, pendingLine, slowLine, paidHeading, paidLine, missingLine, lookupHref, lookupLabel, stepsHeading, steps[]. Read-only: it finds the order from ?session_id= or ?token=, reads ${basePath}/order, and while the order is pending asks again every 3 seconds for up to 60, then says it is still confirming and links the lookup. A polite live region announces the change; the cart store re-reads the bag once the order is paid. Hooks: data-order-confirmation, data-order-state (pending, paid, or closed for a cancelled order), data-order-number, data-order-lines, data-order-address, data-step, data-step-icon, data-step-current.

Order Lookup (storefront-order-lookup)

Fields: heading, intro, emailLabel, submitLabel, sentHeading, differentEmailLabel, signInHref, signInLabel, backHref, backLabel. One email field and a honeypot named website. Whatever the server answers (including its rate limits and failures) the visitor reaches the same "Check your email" state with the same line. Hooks: data-order-lookup, data-lookup-state (ask or sent).

Restock Alert (storefront-restock-alert)

Fields: productSlug (required, and optional productId), productTitle, variantSku, heading, promise, emailLabel, submitLabel, sentHeading. One email field, a one-sentence promise (the disclosure, sent with the request and saved by the server as what the person agreed to) and a honeypot named website. It posts { email, productSlug | productId, variantSku, website, disclosure } to ${basePath}/restock and nothing else. Whatever a 200 carries, the visitor reaches the same "Noted" state with the server's line, so the form can never be used to find out who has asked; a request that never reached the server (offline, a 5xx) says so and keeps the form, because "we will email you" would be untrue. With double opt-in on, the server's line tells the visitor to check their inbox. Needs no cart provider. size is default, small (a tighter stack) or compact (a tile's one line, "Email me when it's back": a link to the product when it has an href, else a button that opens the form in place; compactLabel words it). A catalog tile asks for compact when its plate shows a second image, so no form sits over the picture. Hooks: data-restock (data-restock-alert, data-restock-size, data-restock-state = ask or sent), data-restock-link, data-restock-open (the compact line), data-restock-form, data-restock-label, data-restock-promise, data-restock-field, data-restock-email, data-restock-trap, data-restock-error, data-restock-submit, data-restock-sent, data-restock-mark, data-restock-answer. The buy box's disabled Add button also carries data-restock; the alert's root carries data-restock-alert as well, so a theme can tell them apart.

The same form appears without placing the block: the sold-out buy box shows it inline (data-buy-restock), and a catalog tile's restock slot renders it, once ./adapter is imported (see Add to bag below).

The cart store (./cart)

'use client'
import { useCart, useCartSelector } from '@wabbit/tome-blocks-storefront-pack/cart'

function Count() {
  const { count, countFrom, add, openDrawer } = useCart()
  // ...
}

useCart() returns the state and the actions. useCartSelector(select) subscribes to a slice, so a tile re-renders only when its own line changes.

• Optimistic add. add(input, { openDrawer, title }) raises count and inBag at once and rolls them back, with a spoken reason, if the server refuses. The input is { productId, variantSku?, quantity } or { productSlug, variantSku?, quantity }. Identities and quantities are all that ever leave the browser: the server prices every line.
• One request at a time. Calls to the server run in order, because the cart cookie and the line ids are sequential state.
• The transport. createFetchCartTransport({ basePath }) (default /api/storefront) calls ${basePath}/cart with GET, POST, PATCH and DELETE, then reads the priced cart again, because storefront's mutations return an unpriced cart. Pass your own CartTransport to use server actions instead.
• The count roll. countFrom is the count before the latest change; the trigger renders both ends and the stylesheet rolls one out and the other in. With prefers-reduced-motion: reduce, countFrom equals count.
• Free shipping. freeShip holds the remaining amount the visitor last saw (kept in sessionStorage under tome-free-ship-seen) and the current one, so the bar grows from one to the other. With nothing seen it grows from empty.
• The live region. CartProvider renders the page's one visually hidden aria-live="polite" region, [data-bag-announcer]: "Added {title} to your bag. {n} items." and "Couldn't add {title}: {reason}".

Add to bag (./adapter)

Importing @wabbit/tome-blocks-storefront-pack/adapter registers the real control with blocks-core's adapter registry (registerBlockAdapters({ addToBag })). Every catalog tile and hero chip that renders resolveAddToBag(...) then gets:

• a pill ("Add to bag", with the preformatted price inside) that turns into a quantity stepper in place; data-add-state goes idle, adding, in-bag, or error after a refusal
• a link to the product for a piece that needs a variant chosen first
• the restock alert form in restock mode (or for a product that is not purchasable), and inline under a sold-out buy box; ./adapter registers it with setRestockRenderer(renderRestockAlert), getRestockRenderer() reads it, and setRestockRenderer(null) restores a disabled "Sold out" pill
• the plain link to the product when there is no CartProvider above it, so a gallery or a preview still works

The swap and the count roll run only under prefers-reduced-motion: no-preference; keyboard focus follows the swap. <StorefrontBagProvider> provides the adapter through context as well as the registry, which does not depend on which module graph evaluated what.

Hydration (./server)

The static drawer shows its authored fields. Spread the hydrated renderers over the static ones and it also shows the store's own tax note, its "After the order" line, the countries the store ships to, and a "goes with" row from the shop listing:

import { renderers as staticComponents } from '@wabbit/tome-blocks-storefront-pack/render/register'
import {
  createHydratedRenderers,
  registerCartSuggestionSource,
  registerStorefrontAvailabilitySource,
  registerStorefrontFactsSource,
} from '@wabbit/tome-blocks-storefront-pack/server'

registerStorefrontFactsSource(storefrontFactsSource({ getPayload })) // from @wabbit/tome-storefront
registerStorefrontAvailabilitySource(storefrontAvailabilitySource({ getPayload })) // the buy box's stock line
registerCartSuggestionSource(getCatalogListingSource()!)            // from @wabbit/tome-blocks-catalog-pack/server

const components = { ...staticComponents, ...createHydratedRenderers() }

The sources are structural, so the pack imports neither at runtime. A missing or failing source leaves the authored block exactly as it was.

The checkout step and the order confirmation hydrate too. The checkout step takes the store's tax note, countries and default country from the facts source, and asks an optional checkout-context source who is looking, so a signed-in member sees no email field and a demo shop shows its banner:

import { registerCheckoutContextSource } from '@wabbit/tome-blocks-storefront-pack/server'

registerCheckoutContextSource({ get: async () => ({ member: Boolean(await currentMember()), demoBanner: isDemo ? 'Demo shop: test mode.' : null }) })

The order confirmation takes the store's "After the order" steps from the facts source. The order lookup needs no hydration.

Styling and accessibility

Every stylesheet is functional only: --tome-* tokens, no colour literals, targets of at least 44px, and a 2px focus ring from --tome-color-ring. A theme styles the data-* hooks above. --tome-roll sets the duration and easing of the count roll, the stepper swap and the free-shipping growth.

License

Commercial. See LICENSE.md.