@tuturuuu/ui 0.11.1 → 0.12.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.12.0](https://github.com/tutur3u/platform/compare/ui-v0.11.1...ui-v0.12.0) (2026-07-03)
+
+
+### Features
+
+* **inventory:** add revenue share and category bundles ([20b2e1e](https://github.com/tutur3u/platform/commit/20b2e1e5302d1db275766b7b4b92d9bdf69de04a))
+
 ## [0.11.1](https://github.com/tutur3u/platform/compare/ui-v0.11.0...ui-v0.11.1) (2026-07-02)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tuturuuu/ui",
-  "version": "0.11.1",
+  "version": "0.12.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -88,9 +88,9 @@
     "@tuturuuu/apis": "0.7.0",
     "@tuturuuu/hooks": "0.0.2",
     "@tuturuuu/icons": "0.0.6",
-    "@tuturuuu/internal-api": "0.13.0",
+    "@tuturuuu/internal-api": "0.14.0",
     "@tuturuuu/supabase": "0.4.0",
-    "@tuturuuu/utils": "0.12.0",
+    "@tuturuuu/utils": "0.12.1",
     "@types/debug": "^4.1.13",
     "browser-image-compression": "^2.0.2",
     "class-variance-authority": "^0.7.1",
@@ -149,7 +149,7 @@
     "@tanstack/react-table": "^8.21.3",
     "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/react": "^16.3.2",
-    "@tuturuuu/types": "0.13.1",
+    "@tuturuuu/types": "0.14.0",
     "@tuturuuu/typescript-config": "0.1.1",
     "@types/html2canvas": "^1.0.0",
     "@types/lodash": "^4.17.24",

package/src/components/ui/storefront/bundle-selection-dialog.tsx

@@ -0,0 +1,249 @@
+'use client';
+
+import { Check, PackagePlus, Search } from '@tuturuuu/icons';
+import type {
+  InventoryBundle,
+  InventoryBundleCategoryCandidate,
+  InventoryStorefrontListing,
+} from '@tuturuuu/internal-api/inventory';
+import { cn } from '@tuturuuu/utils/format';
+import { useMemo, useState } from 'react';
+import { Badge } from '../badge';
+import { Button } from '../button';
+import { Dialog, DialogContent, DialogHeader, DialogTitle } from '../dialog';
+import { Input } from '../input';
+import type { StorefrontCartLine, StorefrontSurfaceLabels } from './types';
+import {
+  createStorefrontBundleSelectionKey,
+  formatStorefrontPrice,
+  getStorefrontBundleSelectionSubtotal,
+} from './utils';
+
+type BundleSelectionDialogProps = {
+  bundle: InventoryBundle | null;
+  currency: string;
+  labels: StorefrontSurfaceLabels;
+  listing: InventoryStorefrontListing | null;
+  onAdd?: (line: StorefrontCartLine) => void;
+  onOpenChange: (open: boolean) => void;
+  open: boolean;
+  radius: string;
+};
+
+export function StorefrontBundleSelectionDialog({
+  bundle,
+  currency,
+  labels,
+  listing,
+  onAdd,
+  onOpenChange,
+  open,
+  radius,
+}: BundleSelectionDialogProps) {
+  const [query, setQuery] = useState('');
+  const [selected, setSelected] = useState<Record<string, string[]>>({});
+  const normalizedQuery = query.trim().toLowerCase();
+  const selections = useMemo(() => {
+    if (!bundle) return {};
+
+    return Object.fromEntries(
+      bundle.categoryComponents.map((component) => {
+        const candidates = component.candidates ?? [];
+        const items = (selected[component.id] ?? []).flatMap((key) => {
+          const candidate = candidates.find(
+            (item) => getCandidateKey(item) === key
+          );
+          return candidate ? [candidateToSelection(candidate)] : [];
+        });
+        return [component.id, items];
+      })
+    );
+  }, [bundle, selected]);
+  const selectionLine: StorefrontCartLine | null =
+    listing && bundle
+      ? {
+          bundleSelections: selections,
+          listingId: listing.id,
+          quantity: 1,
+          selectionKey: createStorefrontBundleSelectionKey(bundle, selections),
+        }
+      : null;
+  const subtotal =
+    bundle && selectionLine
+      ? getStorefrontBundleSelectionSubtotal(bundle, selectionLine)
+      : null;
+  const isComplete =
+    Boolean(bundle?.categoryComponents.length) &&
+    bundle?.categoryComponents.every(
+      (component) =>
+        (selected[component.id]?.length ?? 0) === component.quantityRequired
+    );
+
+  if (!bundle || !listing) return null;
+
+  return (
+    <Dialog
+      onOpenChange={(nextOpen) => {
+        if (!nextOpen) {
+          setQuery('');
+          setSelected({});
+        }
+        onOpenChange(nextOpen);
+      }}
+      open={open}
+    >
+      <DialogContent className="grid max-h-[90dvh] max-w-[min(42rem,calc(100vw-1rem))] grid-rows-[auto_auto_minmax(0,1fr)_auto] gap-4 overflow-hidden border-border/60 p-5 sm:rounded-2xl">
+        <DialogHeader className="text-left">
+          <DialogTitle>{labels.bundleSelectionTitle}</DialogTitle>
+          <p className="text-muted-foreground text-sm">{listing.title}</p>
+        </DialogHeader>
+        <div className="grid gap-2">
+          <label className="relative block">
+            <Search className="pointer-events-none absolute top-1/2 left-3 h-4 w-4 -translate-y-1/2 text-muted-foreground" />
+            <Input
+              className="h-10 pl-9"
+              onChange={(event) => setQuery(event.target.value)}
+              placeholder={labels.searchBundleItems}
+              value={query}
+            />
+          </label>
+          <p className="rounded-md border border-border bg-muted/25 px-3 py-2 text-muted-foreground text-xs">
+            {labels.cheapestFreePreview}
+          </p>
+        </div>
+        <div className="-mr-1 grid gap-4 overflow-y-auto pr-1">
+          {bundle.categoryComponents.map((component) => {
+            const selectedKeys = selected[component.id] ?? [];
+            const filteredCandidates = (component.candidates ?? []).filter(
+              (candidate) =>
+                !normalizedQuery ||
+                candidate.title.toLowerCase().includes(normalizedQuery)
+            );
+
+            return (
+              <section className="grid gap-2" key={component.id}>
+                <div className="flex items-center justify-between gap-3">
+                  <div className="min-w-0">
+                    <p className="truncate font-medium text-sm">
+                      {component.categoryName}
+                    </p>
+                    <p className="text-muted-foreground text-xs">
+                      {labels.selectedItems
+                        .replace('{selected}', String(selectedKeys.length))
+                        .replace(
+                          '{required}',
+                          String(component.quantityRequired)
+                        )}
+                    </p>
+                  </div>
+                  <Badge
+                    className="border-border bg-background"
+                    variant="outline"
+                  >
+                    {labels.requiredItems.replace(
+                      '{count}',
+                      String(component.quantityRequired)
+                    )}
+                  </Badge>
+                </div>
+                <div className="grid gap-2 sm:grid-cols-2">
+                  {filteredCandidates.map((candidate) => {
+                    const key = getCandidateKey(candidate);
+                    const active = selectedKeys.includes(key);
+                    const full =
+                      !active &&
+                      selectedKeys.length >= component.quantityRequired;
+                    const disabled =
+                      full || candidate.availableQuantity === 0 || !onAdd;
+
+                    return (
+                      <button
+                        className={cn(
+                          'grid min-h-20 gap-1 rounded-lg border bg-background p-3 text-left text-sm transition',
+                          active
+                            ? 'border-[var(--storefront-accent,var(--primary))] bg-[var(--storefront-accent-soft,var(--muted))]'
+                            : 'border-border hover:border-foreground/35',
+                          disabled ? 'cursor-not-allowed opacity-60' : null
+                        )}
+                        disabled={disabled}
+                        key={key}
+                        onClick={() =>
+                          setSelected((current) => ({
+                            ...current,
+                            [component.id]: active
+                              ? selectedKeys.filter((item) => item !== key)
+                              : [...selectedKeys, key],
+                          }))
+                        }
+                        type="button"
+                      >
+                        <span className="flex min-w-0 items-center justify-between gap-2">
+                          <span className="line-clamp-2 font-medium">
+                            {candidate.title}
+                          </span>
+                          {active ? <Check className="h-4 w-4" /> : null}
+                        </span>
+                        <span className="text-muted-foreground text-xs">
+                          {candidate.unitName || candidate.unitId} /{' '}
+                          {candidate.warehouseName || candidate.warehouseId}
+                        </span>
+                        <span className="font-semibold tabular-nums">
+                          {formatStorefrontPrice(candidate.price, currency)}
+                        </span>
+                      </button>
+                    );
+                  })}
+                </div>
+              </section>
+            );
+          })}
+        </div>
+        <div className="flex flex-wrap items-center justify-between gap-3 border-border border-t pt-4">
+          <div className="min-w-0">
+            <p className="text-muted-foreground text-xs">{labels.total}</p>
+            <p className="font-semibold tabular-nums">
+              {formatStorefrontPrice(subtotal ?? 0, currency)}
+            </p>
+          </div>
+          <Button
+            className={cn('min-w-36', radius)}
+            disabled={!isComplete || !selectionLine || !onAdd}
+            onClick={() => {
+              if (!selectionLine || !onAdd) return;
+              onAdd(selectionLine);
+              onOpenChange(false);
+              setQuery('');
+              setSelected({});
+            }}
+            type="button"
+          >
+            <PackagePlus className="h-4 w-4" />
+            {labels.add}
+          </Button>
+        </div>
+      </DialogContent>
+    </Dialog>
+  );
+}
+
+function candidateToSelection(candidate: InventoryBundleCategoryCandidate) {
+  return {
+    listingId: candidate.listingId,
+    productId: candidate.productId,
+    quantity: 1,
+    unitId: candidate.unitId,
+    variantId: candidate.variantId,
+    warehouseId: candidate.warehouseId,
+  };
+}
+
+function getCandidateKey(candidate: InventoryBundleCategoryCandidate) {
+  return [
+    candidate.selectionKind,
+    candidate.listingId ?? '',
+    candidate.variantId ?? '',
+    candidate.productId,
+    candidate.unitId,
+    candidate.warehouseId,
+  ].join(':');
+}

package/src/components/ui/storefront/cart-summary-parts.tsx

@@ -18,7 +18,8 @@ import type {
 } from './types';
 import {
   formatStorefrontPrice,
-  getStorefrontLinePrice,
+  getStorefrontBundleSelectionLabels,
+  getStorefrontCartLineSubtotal,
   getStorefrontVariantLabel,
   storefrontCartLineKey,
 } from './utils';
@@ -229,20 +230,30 @@ function CartLines({
 }) {
   return (
     <div className="-mr-1 grid max-h-72 gap-3 overflow-y-auto pr-1">
-      {cartEntries.map(({ line, listing, variant }) => {
-        const unitPrice = getStorefrontLinePrice(listing, variant);
+      {cartEntries.map(({ bundle, line, listing, variant }) => {
+        const selectedSubtotal = getStorefrontCartLineSubtotal({
+          bundle,
+          line,
+          listing,
+          variant,
+        });
         const variantLabel = variant
           ? getStorefrontVariantLabel(variant)
           : null;
-        const lineTotal = formatStorefrontPrice(
-          unitPrice * line.quantity,
-          currency
+        const selectionLabels = getStorefrontBundleSelectionLabels(
+          bundle,
+          line
         );
+        const lineTotal = formatStorefrontPrice(selectedSubtotal, currency);
 
         return (
           <div
             className="grid grid-cols-[minmax(0,1fr)_auto] gap-x-3 gap-y-1 text-sm"
-            key={storefrontCartLineKey(line.listingId, line.variantId)}
+            key={storefrontCartLineKey(
+              line.listingId,
+              line.variantId,
+              line.selectionKey
+            )}
           >
             <div className="min-w-0">
               <p className="line-clamp-2 break-words font-medium leading-5">
@@ -253,8 +264,17 @@ function CartLines({
                   {variantLabel}
                 </p>
               ) : null}
+              {selectionLabels.length ? (
+                <p className="line-clamp-2 break-words text-muted-foreground text-xs">
+                  {selectionLabels.join(', ')}
+                </p>
+              ) : null}
               <p className="text-muted-foreground text-xs tabular-nums">
-                {line.quantity} × {formatStorefrontPrice(unitPrice, currency)}
+                {line.quantity} ×{' '}
+                {formatStorefrontPrice(
+                  Math.round(selectedSubtotal / Math.max(1, line.quantity)),
+                  currency
+                )}
               </p>
             </div>
             <span

package/src/components/ui/storefront/listing-card.tsx

@@ -21,6 +21,7 @@ export function StorefrontListingCard({
   labels,
   listing,
   onDecrement,
+  onConfigureBundle,
   onIncrement,
   onOpenDetail,
   quantity,
@@ -33,6 +34,7 @@ export function StorefrontListingCard({
   labels: StorefrontSurfaceLabels;
   listing: InventoryStorefrontListing;
   onDecrement?: (listingId: string, variantId?: string | null) => void;
+  onConfigureBundle?: () => void;
   onIncrement?: (
     listingId: string,
     maxQuantity: number,
@@ -45,6 +47,7 @@ export function StorefrontListingCard({
   surfaceClassName: string;
 }) {
   const hasVariants = listingHasVariants(listing);
+  const needsBundleConfiguration = Boolean(onConfigureBundle);
   const limit = getStorefrontListingLimit(listing);
   const disabled = limit === 0 || quantity >= limit;
   const canChange = Boolean(onIncrement || onDecrement);
@@ -139,10 +142,10 @@ export function StorefrontListingCard({
             </p>
           ) : null}
         </div>
-        {hasVariants ? (
+        {hasVariants || needsBundleConfiguration ? (
           <AccentButton
-            disabled={limit === 0 || !openDetail}
-            onClick={openDetail}
+            disabled={limit === 0 || (!openDetail && !onConfigureBundle)}
+            onClick={needsBundleConfiguration ? onConfigureBundle : openDetail}
             radius={radius}
           >
             <SlidersHorizontal className="h-4 w-4" />

package/src/components/ui/storefront/storefront-surface.test.tsx

@@ -1,9 +1,10 @@
 import { fireEvent, render, screen } from '@testing-library/react';
 import type {
+  InventoryBundle,
   InventoryStorefront,
   InventoryStorefrontListing,
 } from '@tuturuuu/internal-api/inventory';
-import { describe, expect, it } from 'vitest';
+import { describe, expect, it, vi } from 'vitest';
 import { StorefrontSurface } from './storefront-surface';
 import { formatStorefrontPrice, sanitizeStorefrontAccentColor } from './utils';
 
@@ -65,6 +66,95 @@ const secondListing: InventoryStorefrontListing = {
   unitId: 'unit-2',
 };
 
+const categoryBundle: InventoryBundle = {
+  availableQuantity: 9,
+  categoryCandidateScope: 'all_stock',
+  categoryComponents: [
+    {
+      bundleId: 'bundle-keychains',
+      candidates: [
+        {
+          availableQuantity: 5,
+          componentId: 'component-keychains',
+          listingId: 'listing-keychain-a',
+          price: 1200,
+          productId: 'product-keychain-a',
+          selectionKind: 'listing',
+          title: 'Acrylic Keychain',
+          unitId: 'unit-1',
+          unitName: 'Each',
+          variantId: null,
+          warehouseId: 'warehouse-1',
+          warehouseName: 'Main',
+        },
+        {
+          availableQuantity: 5,
+          componentId: 'component-keychains',
+          listingId: 'listing-keychain-b',
+          price: 900,
+          productId: 'product-keychain-b',
+          selectionKind: 'listing',
+          title: 'Metal Keychain',
+          unitId: 'unit-1',
+          unitName: 'Each',
+          variantId: null,
+          warehouseId: 'warehouse-1',
+          warehouseName: 'Main',
+        },
+        {
+          availableQuantity: 5,
+          componentId: 'component-keychains',
+          listingId: 'listing-keychain-c',
+          price: 1500,
+          productId: 'product-keychain-c',
+          selectionKind: 'listing',
+          title: 'Charm Keychain',
+          unitId: 'unit-1',
+          unitName: 'Each',
+          variantId: null,
+          warehouseId: 'warehouse-1',
+          warehouseName: 'Main',
+        },
+      ],
+      categoryId: 'category-keychains',
+      categoryName: 'Keychains',
+      discountStrategy: 'cheapest_free',
+      freeQuantity: 1,
+      id: 'component-keychains',
+      quantityRequired: 3,
+      sortOrder: 0,
+    },
+  ],
+  components: [],
+  createdAt: '2026-07-03T00:00:00.000Z',
+  description: 'Choose any three keychains.',
+  id: 'bundle-keychains',
+  imageUrl: null,
+  maxPerOrder: 4,
+  name: 'Buy 2 Get 1 Keychains',
+  price: 0,
+  pricingMode: 'selected_items',
+  slug: 'buy-2-get-1-keychains',
+  status: 'active',
+  storefrontId: storefront.id,
+  updatedAt: '2026-07-03T00:00:00.000Z',
+  wsId: storefront.wsId,
+};
+
+const bundleListing: InventoryStorefrontListing = {
+  ...listing,
+  bundleId: categoryBundle.id,
+  id: 'listing-keychain-bundle',
+  listingType: 'bundle',
+  price: 0,
+  productId: null,
+  title: 'Buy 2 Get 1 Keychains',
+  unitId: null,
+  unitName: null,
+  warehouseId: null,
+  warehouseName: null,
+};
+
 describe('StorefrontSurface', () => {
   it('sanitizes hex accent colors only', () => {
     expect(sanitizeStorefrontAccentColor('#abc')).toBe('#aabbcc');
@@ -143,6 +233,49 @@ describe('StorefrontSurface', () => {
     expect(screen.getByRole('button', { name: /Checkout/ })).toBeEnabled();
   });
 
+  it('opens category bundle selection and adds the configured selection to cart', () => {
+    const onAddCartLine = vi.fn();
+
+    render(
+      <StorefrontSurface
+        bundles={[categoryBundle]}
+        listings={[bundleListing]}
+        mode="store"
+        onAddCartLine={onAddCartLine}
+        storefront={storefront}
+      />
+    );
+
+    fireEvent.click(screen.getByRole('button', { name: /Select options/ }));
+    expect(screen.getByRole('dialog')).toBeInTheDocument();
+    expect(screen.getByText('0 of 3 selected')).toBeInTheDocument();
+    expect(screen.getByRole('button', { name: 'Add' })).toBeDisabled();
+
+    fireEvent.click(screen.getByRole('button', { name: /Acrylic Keychain/ }));
+    fireEvent.click(screen.getByRole('button', { name: /Metal Keychain/ }));
+    fireEvent.click(screen.getByRole('button', { name: /Charm Keychain/ }));
+
+    expect(screen.getByText('3 of 3 selected')).toBeInTheDocument();
+    expect(screen.getByText('$27.00')).toBeInTheDocument();
+    fireEvent.click(screen.getByRole('button', { name: 'Add' }));
+
+    expect(onAddCartLine).toHaveBeenCalledWith(
+      expect.objectContaining({
+        bundleSelections: {
+          'component-keychains': [
+            expect.objectContaining({ listingId: 'listing-keychain-a' }),
+            expect.objectContaining({ listingId: 'listing-keychain-b' }),
+            expect.objectContaining({ listingId: 'listing-keychain-c' }),
+          ],
+        },
+        listingId: bundleListing.id,
+        quantity: 1,
+        selectionKey: expect.stringContaining('component-keychains='),
+      }),
+      5
+    );
+  });
+
   it('keeps long item names and large totals inside the cart row bounds', () => {
     const largeListing: InventoryStorefrontListing = {
       ...listing,

package/src/components/ui/storefront/storefront-surface.tsx

@@ -2,6 +2,7 @@
 
 import { ArrowLeft } from '@tuturuuu/icons';
 import type {
+  InventoryBundle,
   InventoryStorefront,
   InventoryStorefrontListing,
 } from '@tuturuuu/internal-api/inventory';
@@ -14,6 +15,7 @@ import {
   DialogHeader,
   DialogTitle,
 } from '../dialog';
+import { StorefrontBundleSelectionDialog } from './bundle-selection-dialog';
 import { StorefrontCartPopover } from './cart-popover';
 import { StorefrontCartSummary } from './cart-summary';
 import { StorefrontCheckoutOverlay } from './checkout-overlay';
@@ -32,7 +34,7 @@ import type {
 import { mergeStorefrontSurfaceLabels } from './types';
 import {
   getAccentStyle,
-  getStorefrontLinePrice,
+  getStorefrontCartLineSubtotal,
   getStorefrontListingLimit,
   getStorefrontVariantLimit,
   sanitizeStorefrontAccentColor,
@@ -42,6 +44,7 @@ import {
 } from './utils';
 
 export function StorefrontSurface({
+  bundles = [],
   buyerDefaults,
   cartLines = [],
   cartHref,
@@ -65,12 +68,14 @@ export function StorefrontSurface({
   onCheckoutSubmit,
   onDecrement,
   onDetailListingChange,
+  onAddCartLine,
   onIncrement,
   onInstantCheckout,
   selectedListingId,
   storefront,
   storefrontHref,
 }: {
+  bundles?: InventoryBundle[];
   buyerDefaults?: StorefrontBuyerDefaults;
   cartLines?: StorefrontCartLine[];
   cartHref?: string;
@@ -93,6 +98,7 @@ export function StorefrontSurface({
   onCheckoutOpenChange?: (open: boolean) => void;
   onCheckoutSubmit?: (formData: FormData) => void;
   onDecrement?: (listingId: string, variantId?: string | null) => void;
+  onAddCartLine?: (line: StorefrontCartLine, maxQuantity?: number) => void;
   onDetailListingChange?: (listingId: string | null) => void;
   onIncrement?: (
     listingId: string,
@@ -106,6 +112,9 @@ export function StorefrontSurface({
 }) {
   const labels = mergeStorefrontSurfaceLabels(labelOverrides);
   const [isCartPopoverOpen, setIsCartPopoverOpen] = useState(false);
+  const [bundleSelectionListingId, setBundleSelectionListingId] = useState<
+    string | null
+  >(null);
   const accentColor = sanitizeStorefrontAccentColor(storefront.accentColor);
   const radius = storefrontRadiusClasses[storefront.cornerStyle];
   const resolveVariant = (
@@ -119,7 +128,14 @@ export function StorefrontSurface({
     const listing = listings.find((item) => item.id === line.listingId);
     if (!listing) return [];
     return [
-      { line, listing, variant: resolveVariant(listing, line.variantId) },
+      {
+        bundle: listing.bundleId
+          ? bundles.find((bundle) => bundle.id === listing.bundleId)
+          : undefined,
+        line,
+        listing,
+        variant: resolveVariant(listing, line.variantId),
+      },
     ];
   });
   const lineLimit = (entry: (typeof cartEntries)[number]) =>
@@ -132,7 +148,13 @@ export function StorefrontSurface({
   const total = checkoutEntries.reduce((sum, entry) => {
     const quantity = Math.min(entry.line.quantity, lineLimit(entry));
     return (
-      sum + getStorefrontLinePrice(entry.listing, entry.variant) * quantity
+      sum +
+      getStorefrontCartLineSubtotal({
+        bundle: entry.bundle,
+        line: { ...entry.line, quantity },
+        listing: entry.listing,
+        variant: entry.variant,
+      })
     );
   }, 0);
   const cartQuantity = cartLines.reduce((sum, line) => sum + line.quantity, 0);
@@ -152,6 +174,14 @@ export function StorefrontSurface({
   const isPreview = mode === 'preview';
   const isCartPage = mode === 'cart';
   const listingRows = visibleListings;
+  const bundleSelectionListing = bundleSelectionListingId
+    ? listings.find((listing) => listing.id === bundleSelectionListingId)
+    : null;
+  const bundleSelectionBundle = bundleSelectionListing?.bundleId
+    ? (bundles.find(
+        (bundle) => bundle.id === bundleSelectionListing.bundleId
+      ) ?? null)
+    : null;
   const currency = storefront.currency ?? 'USD';
   const handleCheckoutOpen = () => {
     setIsCartPopoverOpen(false);
@@ -337,9 +367,14 @@ export function StorefrontSurface({
                     />
                   ) : (
                     listingRows.map((listing) => {
-                      const line = cartLines.find(
-                        (item) => item.listingId === listing.id
-                      );
+                      const listingBundle = listing.bundleId
+                        ? bundles.find(
+                            (bundle) => bundle.id === listing.bundleId
+                          )
+                        : undefined;
+                      const quantity = cartLines
+                        .filter((item) => item.listingId === listing.id)
+                        .reduce((sum, item) => sum + item.quantity, 0);
 
                       return (
                         <StorefrontListingCard
@@ -349,13 +384,18 @@ export function StorefrontSurface({
                           labels={labels}
                           listing={listing}
                           onDecrement={onDecrement}
+                          onConfigureBundle={
+                            listingBundle?.categoryComponents.length
+                              ? () => setBundleSelectionListingId(listing.id)
+                              : undefined
+                          }
                           onIncrement={onIncrement}
                           onOpenDetail={
                             onDetailListingChange
                               ? (id) => onDetailListingChange(id)
                               : undefined
                           }
-                          quantity={line?.quantity ?? 0}
+                          quantity={quantity}
                           radius={radius}
                           showInventoryBadges={storefront.showInventoryBadges}
                           surfaceClassName={
@@ -390,6 +430,25 @@ export function StorefrontSurface({
         surfaceClassName={storefrontSurfaceClasses[storefront.surfaceStyle]}
       />
 
+      <StorefrontBundleSelectionDialog
+        bundle={bundleSelectionBundle}
+        currency={currency}
+        labels={labels}
+        listing={bundleSelectionListing ?? null}
+        onAdd={(line) => {
+          if (!bundleSelectionListing) return;
+          onAddCartLine?.(
+            line,
+            getStorefrontListingLimit(bundleSelectionListing)
+          );
+        }}
+        onOpenChange={(open) => {
+          if (!open) setBundleSelectionListingId(null);
+        }}
+        open={Boolean(bundleSelectionListing && bundleSelectionBundle)}
+        radius={radius}
+      />
+
       <Dialog
         onOpenChange={(open) => onCheckoutOpenChange?.(open)}
         open={isCheckoutDialogOpen}

package/src/components/ui/storefront/types.ts

@@ -1,15 +1,20 @@
 import type {
+  InventoryBundle,
+  InventoryCheckoutBundleSelections,
   InventoryListingVariant,
   InventoryStorefrontListing,
 } from '@tuturuuu/internal-api/inventory';
 
 export type StorefrontCartLine = {
   listingId: string;
+  bundleSelections?: InventoryCheckoutBundleSelections;
+  selectionKey?: string | null;
   variantId?: string | null;
   quantity: number;
 };
 
 export type StorefrontCartEntry = {
+  bundle?: InventoryBundle;
   line: StorefrontCartLine;
   listing: InventoryStorefrontListing;
   variant?: InventoryListingVariant;
@@ -32,8 +37,10 @@ export type StorefrontSurfaceLabels = {
   available: string;
   browse: string;
   bundle: string;
+  bundleSelectionTitle: string;
   buyNow: string;
   cart: string;
+  cheapestFreePreview: string;
   checkout: string;
   checkoutDisabled: string;
   checkoutDisabledBadge: string;
@@ -45,7 +52,10 @@ export type StorefrontSurfaceLabels = {
   instantCheckout: string;
   orderSummary: string;
   redirectingToCheckout: string;
+  requiredItems: string;
   selectOptions: string;
+  searchBundleItems: string;
+  selectedItems: string;
   viewDetails: string;
   emptyListingsDescription: string;
   emptyListingsTitle: string;
@@ -74,8 +84,10 @@ export const defaultStorefrontSurfaceLabels: StorefrontSurfaceLabels = {
   available: 'available',
   browse: 'Browse',
   bundle: 'Bundle',
+  bundleSelectionTitle: 'Build bundle',
   buyNow: 'Buy now',
   cart: 'Cart',
+  cheapestFreePreview: 'Cheapest eligible item is free.',
   checkout: 'Checkout',
   checkoutDisabled: 'Checkout is disabled in preview',
   checkoutDisabledBadge: 'Checkout disabled',
@@ -87,7 +99,10 @@ export const defaultStorefrontSurfaceLabels: StorefrontSurfaceLabels = {
   instantCheckout: 'Instant checkout',
   orderSummary: 'Order summary',
   redirectingToCheckout: 'Taking you to secure checkout…',
+  requiredItems: 'Select {count} items',
   selectOptions: 'Select options',
+  searchBundleItems: 'Search items',
+  selectedItems: '{selected} of {required} selected',
   viewDetails: 'View details',
   emptyListingsDescription:
     'Publish a listing to make this storefront ready for buyers.',

package/src/components/ui/storefront/utils.ts

@@ -1,10 +1,14 @@
 import type {
+  InventoryBundle,
+  InventoryBundleCategoryCandidate,
+  InventoryBundleCategoryComponent,
   InventoryListingVariant,
   InventoryStorefront,
   InventoryStorefrontListing,
 } from '@tuturuuu/internal-api/inventory';
 import { formatMoneyFromMinor } from '@tuturuuu/utils/money';
 import type { CSSProperties } from 'react';
+import type { StorefrontCartLine } from './types';
 
 // The storefront now ships a single, unified design language. The merchant
 // preset fields (cornerStyle/surfaceStyle/themePreset/layoutStyle) are retained
@@ -130,6 +134,163 @@ export function getStorefrontLinePrice(
   return variant ? variant.price : listing.price;
 }
 
+function getCategorySelectionItems(
+  line: StorefrontCartLine,
+  component: InventoryBundleCategoryComponent
+) {
+  const selections = line.bundleSelections;
+  if (!selections) return [];
+
+  if (Array.isArray(selections)) {
+    return (
+      selections.find((selection) => selection.componentId === component.id)
+        ?.items ?? []
+    );
+  }
+
+  return selections[component.id] ?? [];
+}
+
+function getCandidateKey(candidate: InventoryBundleCategoryCandidate) {
+  return [
+    candidate.selectionKind,
+    candidate.listingId ?? '',
+    candidate.variantId ?? '',
+    candidate.productId,
+    candidate.unitId,
+    candidate.warehouseId,
+  ].join(':');
+}
+
+function resolveBundleCandidate(
+  component: InventoryBundleCategoryComponent,
+  item: ReturnType<typeof getCategorySelectionItems>[number]
+) {
+  return component.candidates?.find((candidate) => {
+    if (item.variantId) {
+      return (
+        candidate.variantId === item.variantId &&
+        candidate.listingId === item.listingId
+      );
+    }
+    if (item.listingId) {
+      return candidate.listingId === item.listingId && !candidate.variantId;
+    }
+    return (
+      candidate.productId === item.productId &&
+      candidate.unitId === item.unitId &&
+      candidate.warehouseId === item.warehouseId
+    );
+  });
+}
+
+export function getStorefrontBundleSelectionSubtotal(
+  bundle: InventoryBundle | undefined,
+  line: StorefrontCartLine
+) {
+  if (!bundle?.categoryComponents?.length || !line.bundleSelections) {
+    return null;
+  }
+
+  let subtotal = 0;
+  for (const component of bundle.categoryComponents) {
+    const pricedItems = getCategorySelectionItems(line, component).map(
+      (item) => {
+        const candidate = resolveBundleCandidate(component, item);
+        return candidate
+          ? {
+              candidate,
+              quantity: item.quantity ?? 1,
+            }
+          : null;
+      }
+    );
+
+    if (pricedItems.some((item) => !item)) return null;
+
+    const validPricedItems = pricedItems.filter(
+      (
+        item
+      ): item is {
+        candidate: InventoryBundleCategoryCandidate;
+        quantity: number;
+      } => Boolean(item)
+    );
+
+    let freeRemaining =
+      component.discountStrategy === 'cheapest_free'
+        ? component.freeQuantity * line.quantity
+        : 0;
+
+    for (const pricedItem of validPricedItems.sort(
+      (a, b) => a.candidate.price - b.candidate.price
+    )) {
+      const units = pricedItem.quantity * line.quantity;
+      const freeUnits = Math.min(units, freeRemaining);
+      freeRemaining -= freeUnits;
+      subtotal += (units - freeUnits) * pricedItem.candidate.price;
+    }
+  }
+
+  return subtotal;
+}
+
+export function getStorefrontBundleSelectionLabels(
+  bundle: InventoryBundle | undefined,
+  line: StorefrontCartLine
+) {
+  if (!bundle?.categoryComponents?.length || !line.bundleSelections) return [];
+
+  return bundle.categoryComponents.flatMap((component) =>
+    getCategorySelectionItems(line, component).flatMap((item) => {
+      const candidate = resolveBundleCandidate(component, item);
+      if (!candidate) return [];
+      const quantity = item.quantity ?? 1;
+      return quantity > 1 ? `${quantity}x ${candidate.title}` : candidate.title;
+    })
+  );
+}
+
+export function getStorefrontCartLineSubtotal({
+  bundle,
+  line,
+  listing,
+  variant,
+}: {
+  bundle?: InventoryBundle;
+  line: StorefrontCartLine;
+  listing: InventoryStorefrontListing;
+  variant?: InventoryListingVariant | null;
+}) {
+  const selectedSubtotal = getStorefrontBundleSelectionSubtotal(bundle, line);
+  if (selectedSubtotal != null) return selectedSubtotal;
+
+  return getStorefrontLinePrice(listing, variant) * line.quantity;
+}
+
+export function createStorefrontBundleSelectionKey(
+  bundle: InventoryBundle,
+  selections: NonNullable<StorefrontCartLine['bundleSelections']>
+) {
+  const chunks = bundle.categoryComponents.map((component) => {
+    const items = Array.isArray(selections)
+      ? (selections.find((selection) => selection.componentId === component.id)
+          ?.items ?? [])
+      : (selections[component.id] ?? []);
+    const keys = items
+      .map((item) => {
+        const candidate = resolveBundleCandidate(component, item);
+        return candidate
+          ? `${getCandidateKey(candidate)}@${item.quantity ?? 1}`
+          : JSON.stringify(item);
+      })
+      .sort();
+    return `${component.id}=${keys.join(',')}`;
+  });
+
+  return chunks.join('|');
+}
+
 /** Lowest active-variant price, for a "from {price}" label on variant listings. */
 export function getStorefrontListingFromPrice(
   listing: InventoryStorefrontListing
@@ -145,9 +306,10 @@ export function getStorefrontListingFromPrice(
 /** Stable identity for a cart line so listing+variant combos stay distinct. */
 export function storefrontCartLineKey(
   listingId: string,
-  variantId?: string | null
+  variantId?: string | null,
+  selectionKey?: string | null
 ) {
-  return `${listingId}::${variantId ?? ''}`;
+  return `${listingId}::${variantId ?? ''}::${selectionKey ?? ''}`;
 }
 
 /** Composes a human label for the selected variant from its option values. */