@12-apps/discounts 1.17.0 → 1.18.0

package/README.md

@@ -356,7 +356,7 @@ of promotion is this — and derives the pair (`src/react/form-kind.ts`):
 |---|---|---|---|
 | Porcentagem | `PERCENTAGE` | ORDER / CATEGORY / ITEM | the rate, and what it covers |
 | Valor fixo | `FIXED_AMOUNT` | ORDER / CATEGORY / ITEM | the amount, and what it covers |
-| Combo | `PERCENTAGE` or `FIXED_AMOUNT` | `COMBO` | the groups, and which of the two rewards |
+| Combo | `PERCENTAGE`, `FIXED_AMOUNT` or `BUNDLE_PRICE` | `COMBO` | the groups, and which of the three rewards |
 | Itens grátis | `FREE_UNITS` | `COMBO` | the products, how many, how many free |
 
 So the offers a merchant describes map one to one onto what they fill in:
@@ -366,6 +366,7 @@ So the offers a merchant describes map one to one onto what they fill in:
 | "leve 3, pague 2" | Itens grátis | 3 hambúrgueres, 1 free |
 | "2 refrigerantes, 2 hambúrgueres e 2 batatas com 20% de desconto" | Combo | three groups of 2, and the rate |
 | the same six items at R$ 5,00 off | Combo | three groups of 2, and the amount |
+| "5 marmitas por R$ 120" | Combo | one group of 5 (a category mixes flavours), and the closed price |
 
 Two consequences of asking the kind instead of the pair:
 
@@ -373,12 +374,27 @@ Two consequences of asking the kind instead of the pair:
   made of, so the scope toggle offers the three that are genuinely a choice.
   Offering the fourth is what let an operator build "preço de combo,
   abrangência: pedido" and have the write path refuse it.
-- **`BUNDLE_PRICE` is no longer offered.** A flat price for the group reprices
-  it, and goes silently wrong the first time one of its items changes price —
-  so a combo gives a percentage or an amount OFF what its items add up to. The
-  type is still legal in the engine and in the database, and the kind toggle
-  grows a fifth option on the form of a rule that already carries it, so an
-  older promotion opens, edits and saves as what it is.
+- **A closed price is a combo's third reward, "Preço fechado" (FUT-4417).**
+  `BUNDLE_PRICE` reprices the matched group whatever its items cost — which is
+  what "5 marmitas por R$ 120" asks for, so the form offers it beside the rate
+  and the amount, says so under the price, and previews it. It is a REWARD,
+  not a kind: a rule saved as `BUNDLE_PRICE` before FUT-4417 opens as a combo
+  with "Preço fechado" chosen, and the kind toggle is always the same four.
+- **"Como fica no carrinho"** previews one combo under the chosen reward: what
+  its items sum to (each group filled with its cheapest product, then its
+  dearest) and what the buyer pays and saves, with the engine's own
+  arithmetic (`src/react/combo-preview.ts`, one application, before the
+  cart-level clamps). It needs the host's ITEM targets to carry
+  `priceRangeCents` (the product's own price and its variations') and
+  `categoryId` (only for products a buyer can add: listed, not paused); a
+  host that sends neither simply gets no preview. In a form at least
+  `PREVIEW_ASIDE_MIN_PX` wide (931 px: the narrowest form whose left column
+  still holds the four-part kind toggle) it sits in its own column beside
+  the form; narrower, it sits under the reward's field.
+- **The create and edit forms open in `UsableModal`** (`size="wide"`): a
+  stacked modal on a computer, which at 1280 gives the form the room for
+  that column, and a bottom sheet on a phone. Every opening mounts a fresh
+  form.
 
 Picking Combo swaps the single target picker for the **group builder**: each
 group is a quantity plus the rows that can fill it, and a group may name

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/discounts",
-  "version": "1.17.0",
+  "version": "1.18.0",
   "type": "module",
   "sideEffects": [
     "**/e2e/**"
@@ -43,8 +43,8 @@
   "dependencies": {
     "@12-apps/app-shell": "^5.14.1",
     "@12-apps/forms-core": "^1.23.0",
-    "@12-apps/shared-helpers": "^2.1.0",
-    "@12-apps/ui": "^6.86.0",
+    "@12-apps/shared-helpers": "^2.2.0",
+    "@12-apps/ui": "^6.95.1",
     "@mui/icons-material": "^6.5.0",
     "zod": "^4.3.5"
   },

package/src/react/api.ts

@@ -66,6 +66,10 @@ export interface WireTarget {
   id: string;
   name: string;
   parentId?: string | null;
+  /** An ITEM row's unit price range (FUT-4417), for the combo preview only. */
+  priceRangeCents?: { minCents: number; maxCents: number } | null;
+  /** An ITEM row's own category, for the same preview. */
+  categoryId?: string | null;
 }
 
 /** One registered collection and its rows. */
@@ -119,7 +123,7 @@ export interface DiscountFormPayload {
 }
 
 /** A money amount as integer cents, or null when blank. */
-function toCents(typed: string, formatters: DiscountsFormatters): number | null {
+export function toCents(typed: string, formatters: DiscountsFormatters): number | null {
   const amount = formatters.parseDecimal(typed);
   return amount === null ? null : Math.round(amount * 100);
 }
@@ -138,7 +142,7 @@ function toCount(typed: string, formatters: DiscountsFormatters): number | null
  * engine computes without a float. The `Math.round` after the ×100 is what
  * keeps "12,5" exactly 1250 rather than 1249.9999999999998.
  */
-function toBasisPoints(typed: string, formatters: DiscountsFormatters): number | null {
+export function toBasisPoints(typed: string, formatters: DiscountsFormatters): number | null {
   const percent = formatters.parseDecimal(typed);
   return percent === null ? null : Math.round(percent * 100);
 }

package/src/react/combo-cart-preview.tsx

@@ -0,0 +1,189 @@
+"use client";
+
+import { createContext, useContext, useRef, type JSX, type ReactNode } from "react";
+
+import { Alert } from "@12-apps/ui/data-display/Alert";
+import { useFormContext } from "@12-apps/ui/form/total-form";
+import { Box } from "@12-apps/ui/mui/Box";
+import { Stack } from "@12-apps/ui/mui/Stack";
+import { Text } from "@12-apps/ui/typography/Text";
+
+import type { ComboRequirement } from "../engine/types";
+
+import { toBasisPoints, toCents, type WireTargetGroup } from "./api";
+import type { DiscountsWebCopy } from "./copy";
+import { comboPreviewOf, type ComboPreview, type ComboRewardValue } from "./combo-preview";
+import { comboPreviewLines, type ComboPreviewLayout } from "./combo-preview-lines";
+import { comboRewardOf } from "./form-kind";
+import type { DiscountsFormatters } from "./format";
+import { KIND_TOGGLE_MIN_PX, useElementWidth } from "./kind-field";
+
+/**
+ * "Como fica no carrinho" on screen (FUT-4417), and where it sits.
+ *
+ * Under the reward's field on a phone or a narrow form; in its own column
+ * beside the form when the form has the room, as the approved prototype draws
+ * it on a computer. What decides is the FORM's own width, measured the way
+ * `KindField` measures it, because the form also lives in a modal narrower
+ * than the screen. In the wide stacked modal the screens open it in
+ * (`DiscountDialog`), a 1280 window gives the form well over the threshold;
+ * a tablet's or a phone's does not, and the preview sits under the field.
+ */
+
+/** The side column's share and gap: `minmax(0, 3fr) minmax(0, 2fr)`, `gap: 3`. */
+const ASIDE_GAP_PX = 24;
+const FORM_SHARE = 3 / 5;
+
+/**
+ * The narrowest form that takes the side column: one whose left column still
+ * holds the kind question as a toggle (`KIND_TOGGLE_MIN_PX`). A column that
+ * squeezed it into a select would trade a control the operator already knows
+ * for a box of text — the preview has room only when nothing else pays for it.
+ */
+const PREVIEW_ASIDE_MIN_PX = Math.ceil(KIND_TOGGLE_MIN_PX / FORM_SHARE + ASIDE_GAP_PX);
+
+/** What the preview reads that is not a form value. */
+interface PreviewInputs {
+  copy: DiscountsWebCopy;
+  formatters: DiscountsFormatters;
+  groups: readonly WireTargetGroup[];
+  slots: readonly ComboRequirement[];
+}
+
+/**
+ * The preview, worked out ONCE per render of the layout and handed down: the
+ * inline box under the reward's field reads it from here rather than summing
+ * the combo a second time.
+ */
+interface PreviewWorld extends PreviewInputs {
+  layout: ComboPreviewLayout;
+  reward: ComboRewardValue;
+  preview: ComboPreview | null;
+}
+
+const PreviewContext = createContext<PreviewWorld | null>(null);
+
+/** The reward the form currently describes, as numbers. */
+function rewardFrom(
+  values: Record<string, string>,
+  formatters: DiscountsFormatters,
+): ComboRewardValue {
+  return {
+    type: comboRewardOf({ type: values.comboReward ?? "" }),
+    percentOffBp: toBasisPoints(values.percentOff ?? "", formatters),
+    amountOffCents: toCents(values.amountOff ?? "", formatters),
+    bundlePriceCents: toCents(values.bundlePrice ?? "", formatters),
+  };
+}
+
+/** The preview the form currently describes, or null when there is nothing honest to sum. */
+function useComboPreview(world: PreviewInputs): {
+  reward: ComboRewardValue;
+  preview: ComboPreview | null;
+} {
+  const { values } = useFormContext();
+  const reward = rewardFrom(values, world.formatters);
+  const preview =
+    values.kind === "COMBO" ? comboPreviewOf(world.slots, world.groups, reward) : null;
+  return { reward, preview };
+}
+
+function PreviewBox({ world }: { world: PreviewWorld }): JSX.Element | null {
+  const { reward, preview } = world;
+  if (preview === null) return null;
+  const lines = comboPreviewLines(preview, reward, world.layout, world.copy, world.formatters);
+  const aside = world.layout === "aside";
+  return (
+    <Alert variant="info" showIcon={false} animate={false} data-testid="combo-cart-preview">
+      <Stack spacing={aside ? 1 : 0.5}>
+        {/* A small label over the figures, as the prototype draws it — not the
+            Alert's own title, which is larger than the lines it heads. */}
+        <Text as="p" variant="caption" weight="semibold" data-testid="combo-cart-preview-heading">
+          {world.copy.comboRewards.preview.title}
+        </Text>
+        <Text variant="body" size="sm" data-testid="combo-cart-preview-items">
+          {lines.items}
+        </Text>
+        {lines.pays !== null && (
+          <Text
+            variant={aside ? "heading" : "body"}
+            {...(aside ? {} : { size: "sm" as const })}
+            data-testid="combo-cart-preview-pays"
+          >
+            {lines.pays}
+          </Text>
+        )}
+        {lines.examples !== null && (
+          <Text variant="caption" data-testid="combo-cart-preview-examples">
+            {lines.examples}
+          </Text>
+        )}
+      </Stack>
+    </Alert>
+  );
+}
+
+/** The preview under the reward's field — rendered only when the form is narrow. */
+export function InlineComboCartPreview(): JSX.Element | null {
+  const world = useContext(PreviewContext);
+  if (world === null || world.layout !== "inline") return null;
+  return <PreviewBox world={world} />;
+}
+
+/**
+ * The form's body, with the preview's column beside it when a combo is being
+ * built and the form is wide enough; otherwise the body alone, as it always
+ * was, and the reward field places the preview under itself.
+ */
+export function ComboPreviewLayout({
+  copy,
+  formatters,
+  groups,
+  slots,
+  children,
+}: PreviewInputs & { children: ReactNode }): JSX.Element {
+  const box = useRef<HTMLDivElement>(null);
+  const width = useElementWidth(box);
+  // The column exists only while there is a preview to put in it: an empty
+  // column beside a combo with no priced group yet is empty space, and the form
+  // would be squeezed for nothing.
+  const { reward, preview } = useComboPreview({
+    copy,
+    formatters,
+    groups,
+    slots,
+  });
+  const layout: ComboPreviewLayout =
+    preview !== null && width !== null && width >= PREVIEW_ASIDE_MIN_PX ? "aside" : "inline";
+  const world: PreviewWorld = {
+    layout,
+    copy,
+    formatters,
+    groups,
+    slots,
+    reward,
+    preview,
+  };
+  return (
+    <PreviewContext.Provider value={world}>
+      <Box
+        ref={box}
+        data-testid="combo-preview-layout"
+        data-layout={layout}
+        sx={
+          layout === "aside"
+            ? {
+                display: "grid",
+                gridTemplateColumns: "minmax(0, 3fr) minmax(0, 2fr)",
+                gap: 3,
+                alignItems: "start",
+              }
+            : { minWidth: 0 }
+        }
+      >
+        <Box sx={{ minWidth: 0 }}>{children}</Box>
+        {layout === "aside" && <PreviewBox world={world} />}
+      </Box>
+    </PreviewContext.Provider>
+  );
+}

package/src/react/combo-preview-lines.ts

@@ -0,0 +1,171 @@
+import { fill, type DiscountsWebCopy } from "./copy";
+import type { ComboPreview, ComboRewardValue } from "./combo-preview";
+import type { DiscountsFormatters } from "./format";
+
+/**
+ * The preview's sentences (FUT-4417), from the figures `comboPreviewOf` worked
+ * out. Pure, so every branch below is a unit test rather than a screenshot.
+ *
+ * Two layouts say the same thing in two shapes, as the approved prototype
+ * draws them:
+ *
+ * - **inline** — under the reward's field, on a phone or a narrow form: two
+ *   lines, the second carrying the whole range ("Cliente paga de R$ 121,05 a
+ *   R$ 143,55 (10% a menos)");
+ * - **aside** — its own column beside a wide form: the second line short and
+ *   emphasised ("Cliente paga 10% a menos"), and a third line of examples at
+ *   both ends of a one-group combo ("Exemplos: 5 de Frango → R$ 121,05 · …").
+ *
+ * The first line is ONE wording for every reward ("5 itens somam de … a …").
+ * The prototype's phone frame said "Itens: de … a …" under the two discounts
+ * and "5 marmitas somam…" under the closed price; the data has no noun like
+ * "marmitas" for a group, so the pack's own counted noun stands in for both.
+ */
+export type ComboPreviewLayout = "inline" | "aside";
+
+interface ComboPreviewLines {
+  items: string;
+  /** What the buyer pays; null while the reward's value is not typed. */
+  pays: string | null;
+  /** The aside's example line; null inline, for several groups, or when both ends cost the same. */
+  examples: string | null;
+}
+
+interface Say {
+  copy: DiscountsWebCopy;
+  money: (cents: number) => string;
+}
+
+function itemsLine(preview: ComboPreview, say: Say): string {
+  const { combo, comboRewards } = say.copy;
+  const units = fill(preview.units === 1 ? combo.unitsOne : combo.unitsOther, {
+    count: preview.units,
+  });
+  const { cheapest, dearest } = preview;
+  return cheapest.groupCents === dearest.groupCents
+    ? fill(comboRewards.preview.itemsExact, {
+        units,
+        sum: say.money(cheapest.groupCents),
+      })
+    : fill(comboRewards.preview.itemsRange, {
+        units,
+        min: say.money(cheapest.groupCents),
+        max: say.money(dearest.groupCents),
+      });
+}
+
+/** "10%" or "R$ 15,00": what a discount reward takes off, as the operator typed it. */
+function offOf(reward: ComboRewardValue, formatters: DiscountsFormatters): string {
+  return reward.type === "PERCENTAGE"
+    ? formatters.percent(reward.percentOffBp)
+    : formatters.money(reward.amountOffCents);
+}
+
+/** The two discounts: a range of what is paid, or the reward itself in the aside. */
+function discountPays(
+  preview: ComboPreview,
+  reward: ComboRewardValue,
+  layout: ComboPreviewLayout,
+  say: Say,
+  off: string,
+): string {
+  const words = say.copy.comboRewards.preview;
+  if (layout === "aside") return fill(words.paysOff, { off });
+  const { cheapest, dearest } = preview;
+  const rate = reward.type === "PERCENTAGE";
+  if (cheapest.paysCents === dearest.paysCents) {
+    const pays = say.money(cheapest.paysCents);
+    return rate ? fill(words.paysExactOff, { pays, off }) : fill(words.paysExact, { pays });
+  }
+  const range = {
+    min: say.money(cheapest.paysCents),
+    max: say.money(dearest.paysCents),
+  };
+  return rate ? fill(words.paysRangeOff, { ...range, off }) : fill(words.paysRange, range);
+}
+
+/** The closed price, in the three places it can sit against the items' range. */
+function pricePays(
+  preview: ComboPreview,
+  price: number,
+  layout: ComboPreviewLayout,
+  say: Say,
+): string {
+  const words = say.copy.comboRewards.preview;
+  const { cheapest, dearest } = preview;
+  const priced = say.money(price);
+  // At or above the dearest sum the engine charges the items (`max(0, …)`).
+  if (dearest.savingCents === 0) return words.noSaving;
+  if (cheapest.savingCents > 0 || cheapest.groupCents === price) {
+    if (layout === "aside") return fill(words.paysExact, { pays: priced });
+    if (cheapest.savingCents === 0) {
+      return fill(words.paysPriceSavingUpTo, {
+        price: priced,
+        max: say.money(dearest.savingCents),
+      });
+    }
+    return cheapest.savingCents === dearest.savingCents
+      ? fill(words.paysPriceSavingExact, {
+          price: priced,
+          saving: say.money(dearest.savingCents),
+        })
+      : fill(words.paysPriceSaving, {
+          price: priced,
+          min: say.money(cheapest.savingCents),
+          max: say.money(dearest.savingCents),
+        });
+  }
+  // Between the two: the cheapest combo costs its items, the dearest the price.
+  const min = say.money(cheapest.paysCents);
+  return layout === "aside"
+    ? fill(words.paysRange, { min, max: priced })
+    : fill(words.paysUpToPrice, {
+        min,
+        price: priced,
+        max: say.money(dearest.savingCents),
+      });
+}
+
+function examplesLine(preview: ComboPreview, reward: ComboRewardValue, say: Say): string | null {
+  const { single, cheapest, dearest } = preview;
+  if (single === null || cheapest.groupCents === dearest.groupCents) return null;
+  const words = say.copy.comboRewards.preview;
+  const example = (name: string, end: typeof cheapest): string => {
+    const values = {
+      quantity: single.quantity,
+      name,
+      pays: say.money(end.paysCents),
+    };
+    return reward.type === "BUNDLE_PRICE" && end.savingCents > 0
+      ? fill(words.exampleSaving, {
+          ...values,
+          saving: say.money(end.savingCents),
+        })
+      : fill(words.example, values);
+  };
+  return fill(words.examples, {
+    cheapest: example(single.cheapestName, cheapest),
+    dearest: example(single.dearestName, dearest),
+  });
+}
+
+export function comboPreviewLines(
+  preview: ComboPreview,
+  reward: ComboRewardValue,
+  layout: ComboPreviewLayout,
+  copy: DiscountsWebCopy,
+  formatters: DiscountsFormatters,
+): ComboPreviewLines {
+  const say: Say = { copy, money: (cents) => formatters.money(cents) };
+  const items = itemsLine(preview, say);
+  if (!preview.rewardTyped) return { items, pays: null, examples: null };
+  const pays =
+    reward.type === "BUNDLE_PRICE"
+      ? pricePays(preview, reward.bundlePriceCents ?? 0, layout, say)
+      : discountPays(preview, reward, layout, say, offOf(reward, formatters));
+  return {
+    items,
+    pays,
+    examples: layout === "aside" ? examplesLine(preview, reward, say) : null,
+  };
+}

package/src/react/combo-preview.ts

@@ -0,0 +1,217 @@
+import { comboSlotAcceptsLine, freshComboPool, matchCombo } from "../engine/combo-match";
+import type { ComboRequirement, DiscountCartLine, DiscountRule } from "../engine/types";
+import { buildTargetPath } from "../server/collections";
+
+import type { WireTarget, WireTargetGroup } from "./api";
+import type { ComboReward } from "./form-kind";
+
+/**
+ * "Como fica no carrinho" — what one combo's items sum to and what the buyer
+ * pays for them, worked out from the store's own prices while the operator is
+ * still typing (FUT-4417).
+ *
+ * The figures are the ENGINE's, not a second derivation of them: each end of
+ * the range is a small synthetic cart — every group filled with its cheapest
+ * product, then with its dearest — handed to `matchCombo`, so the rounding of a
+ * percentage, the cap of a fixed amount at the group's total and the closed
+ * price's "never more than the items" (`applicationReward`,
+ * `engine/combo-match.ts`) are the ones the cart will apply.
+ *
+ * It is ONE application, before the cart-level clamps (R4's remainders and
+ * R9's payable floor, `ComboMatch.rewardCents`): a preview of the offer, not
+ * of a particular cart.
+ *
+ * Prices come from the targets endpoint's ITEM rows (`priceRangeCents`, its own
+ * price and its variations'); a group that can take no priced product makes
+ * the whole preview `null`, because a sum with a missing term is not a figure
+ * worth showing.
+ */
+
+/** The reward as numbers; a value left blank or invalid is `null`. */
+export interface ComboRewardValue {
+  type: ComboReward;
+  percentOffBp: number | null;
+  amountOffCents: number | null;
+  bundlePriceCents: number | null;
+}
+
+/** One end of the range: the combo filled with the cheapest (or dearest) products. */
+export interface ComboPreviewEnd {
+  /** What the matched items cost before the reward. */
+  groupCents: number;
+  /** What the reward takes off them. 0 when the reward's value is not typed yet. */
+  savingCents: number;
+  /** What the buyer pays for this combo. */
+  paysCents: number;
+}
+
+export interface ComboPreview {
+  /** How many units one combo takes. */
+  units: number;
+  cheapest: ComboPreviewEnd;
+  dearest: ComboPreviewEnd;
+  /** Whether the reward has a usable value; without one only the items sum means anything. */
+  rewardTyped: boolean;
+  /**
+   * For a ONE-group combo: the quantity and the product names at each end
+   * (as the catalog stores them), for the example line. `null` for several groups.
+   */
+  single: {
+    quantity: number;
+    cheapestName: string;
+    dearestName: string;
+  } | null;
+}
+
+interface PricedItem {
+  target: WireTarget;
+  line: DiscountCartLine;
+  minCents: number;
+  maxCents: number;
+}
+
+/** Every priced ITEM row as the cart line the matcher would see for it. */
+function pricedItems(groups: readonly WireTargetGroup[]): PricedItem[] {
+  const parents = new Map<string, string | null>(
+    groups
+      .filter((group) => group.targetType === "CATEGORY")
+      .flatMap((group) => group.targets)
+      .map((target) => [target.id, target.parentId ?? null] as const),
+  );
+  return groups
+    .filter((group) => group.targetType === "ITEM")
+    .flatMap((group) => group.targets)
+    .flatMap((target) => {
+      const range = target.priceRangeCents;
+      if (!range || range.minCents < 0 || range.maxCents < range.minCents) return [];
+      const line: DiscountCartLine = {
+        lineId: target.id,
+        menuItemId: target.id,
+        variationMenuItemId: null,
+        categoryPath: buildTargetPath(target.categoryId ?? null, parents),
+        quantity: 1,
+        unitPriceCents: range.minCents,
+      };
+      return [{ target, line, minCents: range.minCents, maxCents: range.maxCents }];
+    });
+}
+
+/** The rule the synthetic carts are matched against: this combo, applied once. */
+function previewRule(slots: readonly ComboRequirement[], reward: ComboRewardValue): DiscountRule {
+  const typed = rewardIsTyped(reward);
+  return {
+    id: "preview",
+    name: "preview",
+    // An untyped reward is matched as a zero percentage, which takes nothing
+    // off and still sums the group.
+    type: typed ? reward.type : "PERCENTAGE",
+    percentOffBp: typed ? reward.percentOffBp : 0,
+    amountOffCents: reward.amountOffCents,
+    bundlePriceCents: reward.bundlePriceCents,
+    scope: "COMBO",
+    targetCategoryIds: [],
+    targetMenuItemIds: [],
+    comboRequirements: slots,
+    maxComboApplications: 1,
+    trigger: "AUTOMATIC",
+    code: null,
+    active: true,
+    startsAt: null,
+    endsAt: null,
+    minSubtotalCents: null,
+    usageLimit: null,
+    usageCount: 0,
+    perBuyerLimit: null,
+    buyerUsageCount: 0,
+    stackable: true,
+    createdAt: new Date(0),
+  };
+}
+
+function rewardIsTyped(reward: ComboRewardValue): boolean {
+  if (reward.type === "PERCENTAGE") return reward.percentOffBp !== null && reward.percentOffBp > 0;
+  if (reward.type === "FIXED_AMOUNT")
+    return reward.amountOffCents !== null && reward.amountOffCents > 0;
+  return reward.bundlePriceCents !== null && reward.bundlePriceCents > 0;
+}
+
+/** One end: each group filled by `pick`'s product, priced at `price`, then matched. */
+function endOf(
+  slots: readonly ComboRequirement[],
+  picks: readonly PricedItem[],
+  price: (item: PricedItem) => number,
+  rule: DiscountRule,
+): ComboPreviewEnd | null {
+  const lines = picks.map((item, index) => ({
+    ...item.line,
+    lineId: `${index}:${item.target.id}`,
+    quantity: slots[index]?.quantity ?? 0,
+    unitPriceCents: price(item),
+  }));
+  const match = matchCombo(rule, freshComboPool(lines));
+  if (match === null) return null;
+  return {
+    groupCents: match.groupCents,
+    savingCents: match.rewardCents,
+    paysCents: match.groupCents - match.rewardCents,
+  };
+}
+
+/** The cheapest and the dearest product one group can take, or null when it can take none. */
+function extremesFor(
+  slot: ComboRequirement,
+  items: readonly PricedItem[],
+): { cheapest: PricedItem; dearest: PricedItem } | null {
+  // The matcher's own predicate, asked one group at a time.
+  const fits = items.filter((item) => comboSlotAcceptsLine(slot, item.line));
+  if (fits.length === 0) return null;
+  const cheapest = fits.reduce((best, item) => (item.minCents < best.minCents ? item : best));
+  const dearest = fits.reduce((best, item) => (item.maxCents > best.maxCents ? item : best));
+  return { cheapest, dearest };
+}
+
+export function comboPreviewOf(
+  slots: readonly ComboRequirement[],
+  groups: readonly WireTargetGroup[],
+  reward: ComboRewardValue,
+): ComboPreview | null {
+  if (
+    slots.length === 0 ||
+    slots.some((slot) => !Number.isInteger(slot.quantity) || slot.quantity <= 0)
+  ) {
+    return null;
+  }
+  const items = pricedItems(groups);
+  const extremes = slots.map((slot) => extremesFor(slot, items));
+  if (extremes.some((pair) => pair === null)) return null;
+  const pairs = extremes as { cheapest: PricedItem; dearest: PricedItem }[];
+  const rule = previewRule(slots, reward);
+  const cheapest = endOf(
+    slots,
+    pairs.map((pair) => pair.cheapest),
+    (item) => item.minCents,
+    rule,
+  );
+  const dearest = endOf(
+    slots,
+    pairs.map((pair) => pair.dearest),
+    (item) => item.maxCents,
+    rule,
+  );
+  if (cheapest === null || dearest === null) return null;
+  const [only] = pairs;
+  return {
+    units: slots.reduce((total, slot) => total + slot.quantity, 0),
+    cheapest,
+    dearest,
+    rewardTyped: rewardIsTyped(reward),
+    single:
+      slots.length === 1 && only
+        ? {
+            quantity: slots[0]?.quantity ?? 0,
+            cheapestName: only.cheapest.target.name,
+            dearestName: only.dearest.target.name,
+          }
+        : null,
+  };
+}