Display warnings and errors in the cart

[fredericoo]

Closes #969

#3276

WHY are these changes introduced?

This PR adds the ability to display warnings to users in the cart, improving the user experience by providing clear feedback when there are issues with their cart.

WHAT is this pull request doing?

• Adds a new InlineWarning component for displaying warning messages in an accessible way
• Implements useCartFeedback hook to collect and normalize errors and warnings from cart fetchers
• Adds CartWarnings component to display warnings in the cart interface
• Updates the cart styling to properly display warning messages
• Integrates the warning system with the existing cart functionality

HOW to test your changes?

1. Add items to cart
2. Trigger a cart warning (e.g., by attempting to add more items than available in inventory)
3. Verify that warnings appear properly in the cart interface
4. Check that warnings are properly styled and accessible

Checklist

• I've read the Contributing Guidelines
• I've considered possible cross-platform impacts (Mac, Linux, Windows)
• I've added a changeset if this PR contains user-facing or noteworthy changes
• I've added tests to cover my changes
• I've added or updated the documentation

[fredericoo]

• Display warnings and errors in the cart #3400 👈 (View in Graphite)
• feat: update SFAPI and CAAPI to 2025-10 #3352 : 6 other dependent PRs (#3284 , #3393 , #3398 and 3 others)
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[shopify]

Oxygen deployed a preview of your Add_MERCHANDISE_SELLING_PLAN_NOT_APPLICABLE_ON_COMPANY_LOCATION_warning_support branch. Details:

Storefront	Status	Preview link	Deployment details	Last update (UTC)
Skeleton (skeleton.hydrogen.shop)	✅ Successful (Logs)	Preview deployment	Inspect deployment	January 28, 2026 6:05 PM
metaobjects	✅ Successful (Logs)	Preview deployment	Inspect deployment	January 23, 2026 4:06 PM
custom-cart-method	✅ Successful (Logs)	Preview deployment	Inspect deployment	January 23, 2026 4:06 PM
third-party-queries-caching	✅ Successful (Logs)	Preview deployment	Inspect deployment	January 23, 2026 4:06 PM
sitemap	✅ Successful (Logs)	Preview deployment	Inspect deployment	January 23, 2026 4:06 PM

Learn more about Hydrogen's GitHub integration.

[kdaviduik]

Please re-request my review when you want me to take a look again :) I saw you made some changes but this comment still applies so I'm assuming it's not yet ready for re-review

[kdaviduik]

fetcherDataMap is in the dependency array but also being updated inside this effect. In the 'submitting' case, changed is unconditionally set to true and a new empty Map is created every time. Since new Map() !== new Map() (reference inequality), React sees this as a state change even though both are empty.

The loop is prevented by the fetcher transitioning to 'loading' state quickly, not by the changed flag. This makes the code fragile — it relies on timing behaviour of React Router rather than explicit loop protection.

The 'loading' case is safer because the data comparison (fetcher.data !== newFetcherDataMap.get(fetcher.key)) naturally terminates the loop once data is stored.

Consider using the functional update pattern instead:

useEffect(() => {
  setFetcherDataMap((prevMap) => {
    let changed = false;
    const newMap = new Map(prevMap);

    for (const fetcher of fetchers) {
      if (!isCartFetcher(fetcher)) continue;

      switch (fetcher.state) {
        case 'submitting':
          if (prevMap.size > 0) {
            return new Map(); // Clear on new submission
          }
          break;
        case 'loading':
          if (fetcher.data && fetcher.data !== prevMap.get(fetcher.key)) {
            changed = true;
            newMap.set(fetcher.key, fetcher.data);
          }
          break;
      }
    }

    return changed ? newMap : prevMap;
  });
}, [fetchers]); // fetcherDataMap removed from deps

[kdaviduik]

The useCartFeedback hook returns errors (line 80), but the CartWarnings component only renders warnings and userErrors.

Is this intentional? If errors shouldn't display here, consider removing them from the hook's return value to avoid confusion. If they should display, we're missing that rendering.

[kdaviduik]

JSDoc doesn't match implementation

The comment says:

Uses role="alert" to announce changes to assistive technology.

But line 19 uses role="status".

Either update the comment to match, or consider making the role conditional:

role={type === 'error' ? 'alert' : 'status'}

Previously I had proposed using `role="status"` but I looked into this more and apparently "alert" is preferred for error messages, whereas "status" is preferred for non-error feedback (eg: cart warnings)

[kdaviduik]

Missing NaN validation

e.target.valueAsNumber returns NaN if the input is empty or invalid. This would submit a cart update with quantity: NaN.

async function submitQuantity(
  e: React.ChangeEvent<HTMLInputElement>,
  fetcher: FetcherWithComponents<any>,
  line: CartLine,
) {
  const value = e.target.valueAsNumber;
  if (Number.isNaN(value) || value < 1) {
    return; // Don't submit invalid quantities
  }
  // ... rest
}

[kdaviduik]

It's not strictly enforced right now, but I think we should never add any anys into the codebase
This could be properly typed using the cart action type:

import type {action as cartAction} from '~/routes/cart';
type CartActionResponse = Awaited<ReturnType<typeof cartAction>>;

fetcher: FetcherWithComponents<CartActionResponse>

[kdaviduik]

If a user changes quantity via up/down arrows (triggering onChange), then clicks away (triggering onBlur), both handlers submit the same value.

The fetcher key deduplication mitigates this, but it's still unnecessary network traffic. Consider tracking whether a pending change exists:

onChange={(e) => {
  if (isKeyboardEvent(e)) return; // Keyboard waits for blur
  void submitQuantity(e, fetcher, line);
}}
onBlur={(e) => {
  // Only submit if there's a pending keyboard change
  // Current implementation submits unconditionally
  void submitQuantity(e, fetcher, line);
}}