Add composable product details parts

[sbolinger-godaddy]

Why

This PR makes our components more customizable without making them more difficult for an agent to use. I'm doing this over multiple PRs so it's easier to review.

ProductDetails was a single component. Changing its layout meant forking it or adding more props, which is the prop-explosion problem described in Soul-Crushing Components. This PR splits it into compound parts. The packaged component stays the default.

AAB and other agents should keep using the packaged components, such as <ProductDetails />. Nothing about that path changes. The parts are an opt-in option for when a layout genuinely needs more customization.

The parts are designed so they can't produce impossible states. They read state from ProductDetailsRoot and take no product, SKU, price or quantity props. Whatever the layout, only a server-verified SKU can be added.

What

• ProductDetailsRoot loads the route's :productId and shows the loading, error and not-found states itself. Parts only render once the product exists.
• Display parts: ProductDetailsGallery, ProductDetailsTitle, ProductDetailsPrice, ProductDetailsDescription, ProductDetailsBackLink.
• Purchase parts: ProductDetailsPurchase (the packaged purchase area), ProductDetailsOptions, ProductDetailsOption, ProductDetailsPurchaseStatus, ProductDetailsAvailability, ProductDetailsQuantity, ProductDetailsAddToCart. Every part that needs the root uses the ProductDetails* prefix, so none can be confused with ProductCard (PR 2) or the standalone AddToCartButton.
• Hooks: useProductDetails() is read-only. useProductDetailsOption(attribute) supports custom controls such as swatches, and select accepts only that attribute's real values.
• All parts are flat named exports, for RSC compatibility, and accept className. Parts can be rendered more than once, such as in a sticky mobile purchase bar, and each copy gets its own element IDs.
• ProductDetails is now composed from these parts and is visually unchanged: screenshots are pixel-identical to 0.2.0. Its markup differs: each part has a wrapper <div>, and the disabled add button's aria-describedby points at a hidden reason element instead of the visible guidance paragraph.

Guardrails

• Changing a selection resets quantity and image, whichever part made the change.
• One status part means two contradictory messages can't appear at once.
• A part rendered outside the root throws an error that names it.
• In development builds, a layout that renders no control for a required option logs a console warning naming the missing ones. The warning describes the current render, because a control can mount later, such as in an accordion.
• Before a SKU is verified, the disabled add-to-cart button has an accessible description explaining why. Once a SKU is verified, AddToCartButton still disables itself without a reason when the quantity is over stock or invalid, or the cart is loading. 0.2.0 behaves the same way; that's a follow-up.

Notes

• Each part puts className on a commerce-part wrapper that the package's CSS reset skips. The package CSS has no cascade layers, so before this change the reset beat a Tailwind v4 host's layered utilities. Host classes now control margin, padding, border, color and grid placement on every part. Inner elements keep the package's own styles, so a host font size on ProductDetailsTitle doesn't change the heading's size.
• The bundle still has no "use client" directive. That is a follow-up, as are ProductCard (PR 2) and the cart drawer (PR 3).

Testing

Package checks: typecheck, lint, build and all 51 storefront tests pass. 9 of the tests are new. They cover:

• custom layouts and swatches
• the quantity reset
• the missing-option warning, and that it doesn't run in production
• the error outside the root
• unique IDs when parts render twice, including the SKU list
• a CSS check that no package rule can override a host class on a part's outer element; it fails without the fix

The example app builds.

Release check against 0.2.0: I built a standalone Vite test app outside the monorepo (commerce-component-test-app) that installs the package the way a host would. It uses only exports that exist in 0.2.0, so the same app code runs on both versions:

1. Installed @godaddy/gd-commerce-storefront@0.2.0 from npm and recorded a baseline.
2. Installed this PR from a pnpm pack tarball and ran the same checks.

The app runs against a mock /api/commerce server with five products that cover every purchase path:

• a simple product with untracked stock, a compare-at price and two images
• a product with one attribute, one value sold out
• a product with two attributes, one combination that doesn't exist
• a product chosen from a labeled SKU list, one sold out
• a missing product (404)

Mock contract: a contract script takes the product queries from gd-commerce-server's source, validates them against the catalog-api-v2 storefront.graphql schema, and runs them with the mock's responses as data. Every response matches the real server's response exactly: no missing, extra, wrongly typed or wrongly null fields. The script fails on a deliberately broken mock.

Results on both versions:

• Behavior: a Playwright smoke test passes all 10 checks with no console errors and no broken ID references. It covers catalog quick-add, gallery, option verification, sold-out and impossible combinations, quantity reset, deep-linked selections, SKU-list selection, not-found and the cart drawer.
• Visuals: 13 of 13 screenshots are pixel-identical, compared with pixelmatch at threshold 0.

The pixel comparison caught two regressions where wrappers picked up a 24px space-y-6 gap that 0.2.0's markup never got. The first was below the option dropdowns, fixed in 1cea7c6. The second was below the status and availability messages, fixed in 0a4780b.

Composable parts (PR builds only): a separate parts.html page in the test app runs 4 more checks, all passing:

• every part with a host class inside @layer utilities, checked through computed margin, padding, border and color
• purchase parts rendered twice in a sticky bar
• an option that mounts after a click, checked for the warning's wording
• the README layout, which must be pixel-identical to <ProductDetails />

Every smoke and parts check also fails on duplicate IDs, and on label[for] or aria-* references that point at a missing ID.

🤖 Generated with Claude Code

[changeset-bot]

🦋 Changeset detected

Latest commit: 0a4780b

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@godaddy/gd-commerce-storefront	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[wcole1-godaddy]

Thanks for splitting ProductDetails into parts. The design is good, and the root keeps the old purchase logic. Typecheck, lint, build and the 47 tests pass locally. I also rendered the old and new ProductDetails in six product states and compared the HTML, and the differences are small. I listed them in the comment on the changeset.

I'm requesting changes for the items below, and the inline comments have the details.

Blocking:

1. Parts share one useId() from the root, so rendering a part twice creates duplicate DOM IDs.
2. The README says host className can control margins. In a Tailwind v4 host, margins don't work on ProductDetailsTitle, ProductDetailsDescription or ProductOption, and borders don't work on any part.
3. Please settle the public names before release, because renaming later is a breaking change.

Should fix:
4. The missing option warning fires for controls that mount after the first render.
5. The README example is labeled as the packaged layout, but it isn't the same.
6. The changeset and the PR description overstate a couple of things.

Follow ups that are fine in a later PR:

• useProductDetails() exposes images but not the current image index, so a custom gallery can't reset when the selection changes. The PR says the image resets "whichever part made the change".
• There's no setter for a custom quantity control, and no hook for a custom SKU list control.
• Tests to add: a custom layout with a SKU list product, image reset, ProductPurchaseStatus in the unavailable and variant error states, and select(null).
• The root reads only :productId, and hosts can't customize its loading, error and not found states.

[wcole1-godaddy]

All parts build their IDs from the single fieldId that the root creates with useId(), so rendering a part twice produces duplicate IDs. A sticky mobile purchase bar next to <ProductPurchase /> is a common layout that does this.

I wrote a quick test that renders <ProductPurchase /> plus a second <ProductQuantity /> and <ProductAddToCart />. It produced a duplicate …-quantity ID when the SKU was ready, and a duplicate …-purchase-reason ID when it wasn't. With the duplicate quantity ID, the second label points at the first input. SkuOption has the same problem with …-sku-option.

Suggested fix: call useId() inside ProductQuantity, ProductAddToCart and SkuOption, and remove fieldId from the context. Please add a test that renders a part twice and checks that the IDs are unique.

[sbolinger-godaddy]

Fixed in 0a4780b. ProductDetailsQuantity, ProductDetailsAddToCart and the SKU list each call useId(), and fieldId is gone from the context. Two new tests cover this. One renders ProductDetailsPurchase plus a second quantity and add button, and checks that IDs stay unique in both the incomplete and ready states. The other renders ProductDetailsOptions twice for a SKU-list product. The test app now also has a sticky-bar layout and fails any page that has duplicate IDs or dangling for/aria-* references.

[wcole1-godaddy]

Host classes can't control margins on some parts. The package CSS ships without cascade layers. Its base reset sets margin: 0 on h1, p and fieldset (styles.css:27) and border-width: 0 on every element. A Tailwind v4 host puts its utilities in @layer utilities, and CSS outside a layer always wins over CSS inside a layer, whatever the specificity.

I loaded the built dist/styles.css in headless Chrome to check, and got these results:

• a layered mt-4 on an h1 or p inside .commerce-storefront gives 0px
• a layered mt-4 on a div gives 16px
• a layered border on a div gives 0px
• an unlayered .mt-4 on a p gives 16px only when it loads after the package CSS, because the specificity ties with the reset

So in a Tailwind v4 host, className='mt-4' works on ProductDetailsGallery, ProductDetailsPrice, ProductQuantity and ProductAddToCart. It does nothing on ProductDetailsTitle, ProductDetailsDescription and ProductOption, and borders don't work on any part.

Either make a div the outer element that receives className on those three parts, or rewrite the paragraph to state these limits. Either way, please add a test that checks the host class takes effect. The current test only checks that the class name is on the element.

[sbolinger-godaddy]

Thanks for checking this in Chrome. Fixed in 0a4780b. A div outer element alone would fix margins but not borders or color, because the reset sets border-width, color and font-family on every element. So each part now puts className on a commerce-part wrapper, and those three resets skip .commerce-part. A plain div needs neither reset.

I added a test that renders every part with a host class. It matches the shipped dist/styles.css rules against each outer element, and fails if any package rule sets margin, padding, border, color or font-family there. It fails on the previous CSS. The test app also loads a probe class inside @layer utilities and checks computed styles on every part in Chrome; all of them now pass. The README now spells out the limit: elements inside a part keep the package styles, so a host font size on ProductDetailsTitle does not resize the heading.

[wcole1-godaddy]

The check runs once, when the required controls first become known. A control that mounts later, such as one in a closed accordion, a tab or a mobile options sheet, triggers a false warning that says the product "can never be added to the cart".

I confirmed it with a test that renders <ProductOption attribute='size' /> only after a button click. The warning fired once, and the product could still be bought after the section was opened.

Could you change the message to say that no control for "size" is rendered right now, instead of saying the product can never be added? The warning also runs in production builds, so please consider limiting it to development.

[sbolinger-godaddy]

Fixed in 0a4780b. The warning now says No control for "size" is rendered right now, so this product cannot be added to the cart until one is, and adds that it can be ignored if the control mounts later. It is skipped when process.env.NODE_ENV === "production", the same check @tanstack/react-query uses, so hosts already define it. A test covers the production case, and the test app mounts the size option after a click and checks the wording.

[wcole1-godaddy]

The example below is labeled "the packaged layout, written out", but it leaves out the grid wrapper and the spacing classes that ProductDetails passes in. Margins moved out of the parts, so anyone who copies the example gets a single column with no space between the parts. Please show the real layout from product-details.tsx, or change the label to something like "a minimal layout".

[sbolinger-godaddy]

Fixed in 0a4780b. The README now shows the real layout from product-details.tsx, with the grid and spacing classes. A note says that without them, the parts stack in one column. The test app renders a copy of the example and checks that it is pixel-identical to <ProductDetails />.

[wcole1-godaddy]

Please settle the names before release, because changing them later is a breaking change.

The display parts use the ProductDetails* prefix, but the purchase parts use Product*, e.g., ProductOption, ProductQuantity and ProductAddToCart, even though they also work only inside ProductDetailsRoot. PR 2 adds ProductCard parts, so the shorter Product* names may collide with those or suggest that they work there too. ProductAddToCart and the existing AddToCartButton would also be two add-to-cart exports with different rules, and an agent can easily mix them up.

One option is to use the ProductDetails* prefix for every part that requires the root.

[sbolinger-godaddy]

Agreed. Renamed in 0a4780b. Every part that needs the root now uses the ProductDetails* prefix: ProductDetailsPurchase, ProductDetailsOptions, ProductDetailsOption, ProductDetailsPurchaseStatus, ProductDetailsAvailability, ProductDetailsQuantity and ProductDetailsAddToCart. The hook and types follow: useProductDetailsOption, ProductDetailsOptionState, ProductDetailsOptionValueState and ProductDetailsPartProps. PurchaseStatus became ProductDetailsStatus, because ProductDetailsPurchaseStatus is the component. The README also points out that AddToCartButton is the standalone button.

[wcole1-godaddy]

"ProductDetails is unchanged" isn't quite accurate. I rendered the old and new ProductDetails in six states and compared the HTML. Apart from class order, which has no visual effect, the new version has these differences:

• it wraps the add button in a <div>
• it adds a hidden reason <span> and points aria-describedby at it, instead of at the visible guidance paragraph
• it adds aria-describedby in the variant error state, where the old version had none

The differences look fine to me, but "visually unchanged" would be accurate.

The PR description has a similar problem. It says the disabled add button always has an accessible description. When the quantity is higher than the stock, the quantity is invalid, or the cart is still loading, AddToCartButton disables itself without giving a reason. The old version behaved the same way, so either fix it in AddToCartButton or soften the claim.

[sbolinger-godaddy]

Fixed in 0a4780b. The changeset now says ProductDetails is visually unchanged and lists the markup differences. The screenshots are still pixel-identical to 0.2.0. The new wrappers briefly added a 24px gap under the status messages, which the pixel diff caught, and I fixed it in the same commit. I softened the PR description: the reason is guaranteed only before a SKU is verified. I left the AddToCartButton reasons for quantity over stock and the cart loading as a follow-up, because 0.2.0 behaves the same way.

[sbolinger-godaddy]

Thanks for the thorough review. All six items are addressed in 0a4780b, and each inline comment has a reply with details. I left the follow-ups you listed for a later PR:

• the image index in useProductDetails()
• a quantity setter and a SKU-list hook
• the extra tests you suggested
• root loading, error and not-found customization
• AddToCartButton reasons when the quantity is over stock or the cart is loading

Checks: typecheck, lint and build pass, and all 51 tests pass. In the test app, the smoke run passes and its 13 screenshots are pixel-identical to 0.2.0. The 4 new parts checks pass: layered host classes, parts rendered twice, a late-mounting option, and the README layout matching <ProductDetails />.

[wcole1-godaddy]

Thanks for working through the feedback. The duplicate IDs, naming, warning, README and changeset items are all fixed, and typecheck, lint, build and all 51 tests pass locally.

One possible follow-up, not blocking: host classes that share a name with a class the package ships, such as mt-4 or flex, still lose to the package's copy, so mt-4 lg:mt-0 or flex lg:hidden won't respond at breakpoints.