@12-apps/discounts 1.3.0 → 1.4.0

package/README.md

@@ -341,9 +341,44 @@ export const discounts = createWebDiscounts({
 ```
 
 What that one call replaces: a server-driven grid with eight columns, five
-filter pills and a CSV/JSON export; a create/edit form of fourteen inputs, four
-of which appear only when another says so; the target pickers; two card
-layouts; four confirmation popups; and every wire call between them.
+filter pills and a CSV/JSON export; a create/edit form whose value input and
+target block both follow the toggles above them; the target pickers and the
+combo builder; two card layouts; four confirmation popups; and every wire call
+between them.
+
+### Authoring a combo
+
+The four discount types and the four scopes are not independent, and the form
+is where that stops being a table in a README:
+
+| the offer | scope | type | what the operator fills in |
+|---|---|---|---|
+| "leve 3, pague 2" | `COMBO` | `FREE_UNITS` | one group of 3, and 1 free |
+| "2 refrigerantes, 2 hambúrgueres e 2 batatas por R$ 25" | `COMBO` | `BUNDLE_PRICE` | three groups of 2, and the price |
+| the same six items at 20% off | `COMBO` | `PERCENTAGE` | three groups of 2, and the rate |
+
+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
+categories AND products at once, because a real menu mixes them — "any drink,
+or specifically the large fries" is one group. Every registered
+`DiscountableCollection` gets a picker inside every group, so a host that
+registers a third dimension gets it here with no change to this package.
+
+Three consequences worth stating, because each is a bug this shape prevents:
+
+- **The reward input is MOUNTED, not hidden.** The four value columns are
+  mutually exclusive at the database, so a leftover number from a branch the
+  operator flipped away from is a 500 on a form they filled in correctly.
+- **`freeUnits` is bounded by the groups.** "Take 3, three free" is a giveaway,
+  so the form compares it against what one application takes out of the cart
+  and names the ceiling when it refuses.
+- **Position is the array index.** The list an operator builds is the list a
+  card reads back; two groups of the same size are otherwise indistinguishable
+  once stored, which is why `toTargetRows` stamps the index as `position`.
+
+`maxComboApplications` appears at `COMBO` scope and nowhere else — it is the
+only scope where "how many times may one cart claim this" means anything — and
+blank means as often as it fits.
 
 **Build it once, at module scope.** The members are component TYPES, so
 rebuilding per render gives React new types every time and remounts the whole

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/discounts",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "type": "module",
   "description": "The discount/promotion domain: a host-agnostic evaluator (percentage or fixed amount, order/category/item scope, automatic or coupon-triggered, stacking and exclusivity, integer-cent allocation) plus the admin CRUD surface as wiring-contract route descriptors over a store port. No database, no framework, no baked user copy.",
   "exports": {

package/src/react/api.ts

@@ -80,6 +80,12 @@ export interface DiscountFormPayload {
   percentOff: string;
   /** A money amount, as the currency field stores it. */
   amountOff: string;
+  /** What the matched combo group costs, as the currency field stores it. */
+  bundlePrice: string;
+  /** How many of the matched units are free, as typed. */
+  freeUnits: string;
+  /** How many combos one cart may claim. Blank = as often as it fits. */
+  maxComboApplications: string;
   scope: string;
   trigger: string;
   code: string;
@@ -92,6 +98,8 @@ export interface DiscountFormPayload {
   active: boolean;
   categoryIds: string[];
   menuItemIds: string[];
+  /** The combo's groups, in the operator's own order. Empty at every other scope. */
+  comboRequirements: readonly ComboRequirement[];
 }
 
 /** A money amount as integer cents, or null when blank. */
@@ -130,12 +138,28 @@ export function toWriteBody(
   input: DiscountFormPayload,
   formatters: DiscountsFormatters,
 ): Record<string, unknown> {
-  const isPercentage = input.type === "PERCENTAGE";
+  const isCombo = input.scope === "COMBO";
   return {
     name: input.name.trim(),
     type: input.type,
-    percentOffBp: isPercentage ? toBasisPoints(input.percentOff, formatters) : null,
-    amountOffCents: isPercentage ? null : toCents(input.amountOff, formatters),
+    // Exactly one value column, chosen by the TYPE, with the other three
+    // forced to null. The four are mutually exclusive at the database
+    // (`discounts_value_check`), so carrying a leftover from a branch the
+    // operator flipped away from is a 500 on a form they filled in correctly —
+    // the same reason the server's own folder nulls them rather than passing
+    // them through.
+    percentOffBp:
+      input.type === "PERCENTAGE" ? toBasisPoints(input.percentOff, formatters) : null,
+    amountOffCents: input.type === "FIXED_AMOUNT" ? toCents(input.amountOff, formatters) : null,
+    bundlePriceCents:
+      input.type === "BUNDLE_PRICE" ? toCents(input.bundlePrice, formatters) : null,
+    freeUnits: input.type === "FREE_UNITS" ? toCount(input.freeUnits, formatters) : null,
+    // The combo SPEC, narrowed to the scope for the reason the id lists below
+    // are: a rule whose scope moved off COMBO keeps neither its groups nor its
+    // cap, or it would go on being matched as a combo by a screen that no
+    // longer shows one.
+    comboRequirements: isCombo ? [...input.comboRequirements] : [],
+    maxComboApplications: isCombo ? toCount(input.maxComboApplications, formatters) : null,
     scope: input.scope,
     trigger: input.trigger,
     code: input.trigger === "CODE" ? toNullable(input.code) : null,

package/src/react/combo-slot-builder.tsx

@@ -0,0 +1,213 @@
+"use client";
+
+import type { JSX } from "react";
+
+import { Button } from "@12-apps/ui/form/Button";
+import { FormControl, FormLabel, FormMessage } from "@12-apps/ui/form/Form";
+import { Input } from "@12-apps/ui/form/Input";
+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 type { WireTargetGroup } from "./api";
+import { fill, type DiscountsWebCopy } from "./copy";
+import { TargetPickerField } from "./target-picker-field";
+
+/**
+ * The combo builder — how an operator says "2 refrigerantes, 2 hambúrgueres e
+ * 2 batatas" (FUT-268).
+ *
+ * A combo is a list of GROUPS. Each group is a quantity and the rows that can
+ * fill it, and a cart matches the combo when every group is satisfiable at
+ * once. That shape is already the engine's (`ComboRequirement`), the
+ * validator's and the schema's — `discount_combo_slots` with its own targets —
+ * so this file adds no concept. It adds the only thing that was missing: a way
+ * to author one.
+ *
+ * Two decisions worth stating, because both are visible in the markup:
+ *
+ * **A group can name categories AND items at once.** "2 refrigerantes" is a
+ * category; "2 batatas médias" is an item; and a real menu mixes them inside
+ * one group ("any drink, or specifically the large fries"). So each group gets
+ * every registered collection's picker rather than a scope toggle — the union
+ * is what `ComboRequirement` already stores, and forcing a choice would make
+ * the common offer unexpressible.
+ *
+ * **Position is the array index, and it is meaningful.** The list an operator
+ * builds is the list a card reads back; two groups of the same size are
+ * otherwise indistinguishable once stored. Removing a group therefore
+ * renumbers the ones after it, which is what an operator expects from a list
+ * they are editing — and `toTargetRows` stamps the index as `position` on the
+ * way to the database.
+ */
+
+/** How many units one application of the combo takes out of the cart. */
+export function comboUnits(slots: readonly ComboRequirement[]): number {
+  return slots.reduce((total, slot) => total + (Number.isFinite(slot.quantity) ? slot.quantity : 0), 0);
+}
+
+/** An empty group: one unit, nothing chosen yet. */
+export function blankSlot(): ComboRequirement {
+  return { quantity: 1, categoryIds: [], menuItemIds: [] };
+}
+
+/** Replace one group, leaving the rest (and their order) alone. */
+function replaceAt(
+  slots: readonly ComboRequirement[],
+  index: number,
+  next: ComboRequirement,
+): ComboRequirement[] {
+  return slots.map((slot, position) => (position === index ? next : slot));
+}
+
+/** Which id list of a group a collection reads and writes. */
+function idsFor(slot: ComboRequirement, targetType: string): readonly string[] {
+  return targetType === "CATEGORY" ? slot.categoryIds : slot.menuItemIds;
+}
+
+function withIds(slot: ComboRequirement, targetType: string, ids: string[]): ComboRequirement {
+  return targetType === "CATEGORY" ? { ...slot, categoryIds: ids } : { ...slot, menuItemIds: ids };
+}
+
+/**
+ * One group: its quantity, one picker per registered collection, and the
+ * control that removes it.
+ *
+ * The quantity is a `number` input rather than a masked one — it counts units,
+ * not money, so there is no locale in it. It is held as a NUMBER in state
+ * rather than as the form's string, because the summary line above adds them up
+ * and the validator compares them against `freeUnits`; parsing on every read
+ * would put the same `Number()` in three places.
+ */
+function ComboSlotRow({
+  slot,
+  index,
+  groups,
+  copy,
+  onChange,
+  onRemove,
+}: {
+  slot: ComboRequirement;
+  index: number;
+  groups: readonly WireTargetGroup[];
+  copy: DiscountsWebCopy;
+  onChange: (next: ComboRequirement) => void;
+  onRemove: () => void;
+}): JSX.Element {
+  const position = index + 1;
+  const empty = slot.categoryIds.length === 0 && slot.menuItemIds.length === 0;
+  return (
+    <Box
+      data-testid={`combo-slot-${index}`}
+      sx={{ border: 1, borderColor: "divider", borderRadius: 1, p: 2 }}
+    >
+      <Stack direction="row" alignItems="center" justifyContent="space-between" spacing={1}>
+        <Text weight="medium">{fill(copy.combo.slot, { position })}</Text>
+        <Button
+          variant="text"
+          onClick={onRemove}
+          // The label carries the POSITION, so a screen reader announces which
+          // group this removes — "remove" alone is three identical buttons.
+          aria-label={fill(copy.combo.removeSlot, { position })}
+          data-testid={`combo-slot-${index}-remove`}
+        >
+          ✕
+        </Button>
+      </Stack>
+      <Stack spacing={2} sx={{ mt: 1 }}>
+        <Input
+          type="number"
+          label={copy.combo.quantity}
+          value={String(slot.quantity)}
+          onChange={(event) => onChange({ ...slot, quantity: Number(event.target.value) })}
+          data-testid={`combo-slot-${index}-quantity`}
+        />
+        {groups.map((group) => (
+          <TargetPickerField
+            key={group.targetType}
+            group={group}
+            label={fill(copy.combo.pick, { collection: group.label })}
+            placeholder={fill(copy.targets.search, { collection: group.label })}
+            // The refusal belongs to the GROUP, not to either picker: a group
+            // naming a category is complete even with no items in it. So the
+            // message hangs below both, once, and only when both are empty.
+            requiredMessage={undefined}
+            ids={idsFor(slot, group.targetType)}
+            onChange={(ids) => onChange(withIds(slot, group.targetType, ids))}
+            dataTestId={`combo-slot-${index}-${group.slug}`}
+          />
+        ))}
+        {empty && (
+          <FormMessage error dataTestId={`combo-slot-${index}-message`}>
+            {copy.form.comboSlotTargetRequired}
+          </FormMessage>
+        )}
+      </Stack>
+    </Box>
+  );
+}
+
+/**
+ * The whole builder: the heading, the groups, the add button and the read-back.
+ *
+ * The read-back line is not decoration. A combo is the one promotion whose
+ * meaning is spread across several controls, and "the combo takes 6 items in 3
+ * groups" is the sentence that catches a mistyped quantity before a save — the
+ * same number `freeUnits` is validated against, computed once and shown.
+ */
+export function ComboSlotBuilder({
+  slots,
+  groups,
+  copy,
+  onChange,
+}: {
+  slots: readonly ComboRequirement[];
+  groups: readonly WireTargetGroup[];
+  copy: DiscountsWebCopy;
+  onChange: (next: ComboRequirement[]) => void;
+}): JSX.Element {
+  return (
+    <FormControl fullWidth>
+      <FormLabel>{copy.combo.title}</FormLabel>
+      <Text variant="caption">{copy.combo.hint}</Text>
+      <Stack spacing={2} sx={{ mt: 1 }} data-testid="combo-slots">
+        {slots.map((slot, index) => (
+          <ComboSlotRow
+            // The index IS the identity here: `position` is the array index,
+            // and a group carries no id of its own until the database gives it
+            // one. Removing a group renumbers the rest, which is exactly what
+            // the operator sees happen.
+            key={index}
+            slot={slot}
+            index={index}
+            groups={groups}
+            copy={copy}
+            onChange={(next) => onChange(replaceAt(slots, index, next))}
+            onRemove={() => onChange(slots.filter((_, position) => position !== index))}
+          />
+        ))}
+        {slots.length === 0 && (
+          <Text variant="caption" data-testid="combo-slots-empty">
+            {copy.combo.empty}
+          </Text>
+        )}
+        <Stack direction="row" alignItems="center" justifyContent="space-between" spacing={2}>
+          <Button
+            variant="outline"
+            onClick={() => onChange([...slots, blankSlot()])}
+            data-testid="combo-add-slot"
+          >
+            {copy.combo.addSlot}
+          </Button>
+          {slots.length > 0 && (
+            <Text variant="caption" data-testid="combo-summary">
+              {fill(copy.combo.summary, { units: comboUnits(slots), groups: slots.length })}
+            </Text>
+          )}
+        </Stack>
+      </Stack>
+    </FormControl>
+  );
+}

package/src/react/copy.ts

@@ -101,6 +101,12 @@ export interface DiscountsFormCopy {
   /** The example inside the empty percentage input. */
   readonly percentPlaceholder: string;
   readonly amountOff: string;
+  /** The combo's total price, shown only for a BUNDLE_PRICE rule. */
+  readonly bundlePrice: string;
+  /** How many of the matched units are given away, for a FREE_UNITS rule. */
+  readonly freeUnits: string;
+  /** Under it: what "leve 3 pague 2" means in this rule's own numbers. */
+  readonly freeUnitsHint: string;
   readonly trigger: string;
   readonly code: string;
   /** The example inside the empty coupon input. */
@@ -111,6 +117,9 @@ export interface DiscountsFormCopy {
   readonly minSubtotal: string;
   readonly usageLimit: string;
   readonly perBuyerLimit: string;
+  /** How many times ONE cart may claim the combo. Blank = as often as it fits. */
+  readonly maxComboApplications: string;
+  readonly maxComboApplicationsHint: string;
   readonly active: string;
   readonly activeHint: string;
   readonly stackable: string;
@@ -123,12 +132,59 @@ export interface DiscountsFormCopy {
   readonly nameRequired: string;
   readonly invalidPercent: string;
   readonly invalidAmount: string;
+  readonly invalidBundlePrice: string;
+  readonly invalidFreeUnits: string;
+  /**
+   * "Take 3, three free" is a giveaway, not a promotion — the free count has to
+   * be smaller than what one application takes out of the cart. `{units}` is
+   * that number, so the operator is told the ceiling rather than just refused.
+   */
+  readonly freeUnitsExceedCombo: string;
   readonly codeRequired: string;
   readonly categoryTargetRequired: string;
   readonly itemTargetRequired: string;
+  /** COMBO scope with no groups: there is nothing for the reward to apply to. */
+  readonly comboSlotsRequired: string;
+  /** A group naming nothing can never be filled, so the combo never fires. */
+  readonly comboSlotTargetRequired: string;
+  readonly invalidComboQuantity: string;
+  readonly invalidMaxComboApplications: string;
   readonly endsBeforeStarts: string;
 }
 
+/**
+ * The combo builder — the "2 refrigerantes + 2 hambúrgueres + 2 batatas" half
+ * of a promotion (FUT-268).
+ *
+ * A combo is a list of GROUPS, each a quantity and the rows that can fill it,
+ * and the reward is whichever value the type asks for. So this group covers the
+ * builder's chrome; the reward's own input is a `form` key beside the other
+ * value fields, because to the operator it is one.
+ */
+export interface DiscountsComboCopy {
+  /** The section heading over the group list. */
+  readonly title: string;
+  /** One sentence saying what a group is, in the merchant's terms. */
+  readonly hint: string;
+  /** The button that appends a group. */
+  readonly addSlot: string;
+  /** The accessible name of one group's remove control. `{position}`. */
+  readonly removeSlot: string;
+  /** One group's heading. `{position}` is 1-based — an operator counts from 1. */
+  readonly slot: string;
+  /** The units this group takes. */
+  readonly quantity: string;
+  /** The group's picker label, `{collection}` — the registration's own label. */
+  readonly pick: string;
+  /** Shown when COMBO is chosen and no group exists yet. */
+  readonly empty: string;
+  /**
+   * The offer read back in the operator's own numbers, so a combo can be
+   * checked without saving it. `{units}` and `{groups}`.
+   */
+  readonly summary: string;
+}
+
 /** The target pickers, and what an empty selection says. */
 export interface DiscountsTargetCopy {
   /** The picker's label, `{collection}` — the registration's own label. */
@@ -185,6 +241,7 @@ export interface DiscountsWebCopy {
   readonly labels: DiscountsVocabularyCopy;
   readonly window: DiscountsWindowCopy;
   readonly form: DiscountsFormCopy;
+  readonly combo: DiscountsComboCopy;
   readonly targets: DiscountsTargetCopy;
   readonly actions: DiscountsActionsCopy;
   readonly card: DiscountsCardCopy;

package/src/react/discount-form-fields.tsx

@@ -6,6 +6,7 @@ import { Switch } from "@12-apps/ui/form/Switch";
 import { Fields, 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 { DISCOUNT_SCOPES, DISCOUNT_TRIGGERS, DISCOUNT_TYPES } from "../engine/kinds";
 
@@ -21,6 +22,32 @@ import type { DiscountsWebCopy } from "./copy";
  * hand-written list is how a form offers a fifth type the database refuses.
  */
 
+/**
+ * A field with a sentence under it.
+ *
+ * `Fields.TextField` has no helper-text slot — deliberately, it is a thin bind
+ * over `Input` — and two of the combo inputs are meaningless without one:
+ * "itens grátis" and "combos por pedido" are both numbers whose UNIT an
+ * operator cannot guess. So the caption is composed here rather than pushed
+ * into `@12-apps/ui`, where it would be a prop every other consumer ignores.
+ */
+function HintedField({
+  name,
+  label,
+  hint,
+}: {
+  name: string;
+  label: string;
+  hint: string;
+}): JSX.Element {
+  return (
+    <Stack spacing={0.5}>
+      <Fields.TextField name={name} label={label} type="number" />
+      <Text variant="caption">{hint}</Text>
+    </Stack>
+  );
+}
+
 /** One closed set as a toggle's options, labelled by the pack. */
 function optionsFor<TKey extends string>(
   values: readonly TKey[],
@@ -29,7 +56,22 @@ function optionsFor<TKey extends string>(
   return values.map((value) => ({ value, label: labels[value] }));
 }
 
-/** Percentage or amount — whichever the chosen type actually stores. */
+/**
+ * The reward, in whichever unit the chosen type actually stores.
+ *
+ * One input per type, and the wrong one must never be mounted: the four value
+ * columns are mutually exclusive at the database (`discounts_value_check`), so
+ * a leftover value from another branch is a 500 on a form the operator filled
+ * in correctly. Mounting rather than hiding is what guarantees it — an unmounted
+ * field cannot carry a stale number to submit.
+ *
+ * The two combo rewards read differently from the two plain ones, and that is
+ * the whole point of FUT-268: BUNDLE_PRICE is what the matched group COSTS
+ * ("2 refrigerantes, 2 hambúrgueres e 2 batatas por R$ 49,90"), FREE_UNITS is
+ * how many of the matched units are given away ("leve 3, pague 2"). Both are
+ * money-or-count fields like the two above them; what makes them combos is the
+ * scope, and the scope is what the builder below hangs off.
+ */
 function ValueField({
   copy,
   currencyField,
@@ -42,6 +84,14 @@ function ValueField({
   if (values.type === "FIXED_AMOUNT") {
     return <Currency name="amountOff" label={copy.form.amountOff} />;
   }
+  if (values.type === "BUNDLE_PRICE") {
+    return <Currency name="bundlePrice" label={copy.form.bundlePrice} />;
+  }
+  if (values.type === "FREE_UNITS") {
+    return (
+      <HintedField name="freeUnits" label={copy.form.freeUnits} hint={copy.form.freeUnitsHint} />
+    );
+  }
   return (
     <Fields.TextField
       name="percentOff"
@@ -111,6 +161,26 @@ export function ScopeField({ copy }: { copy: DiscountsWebCopy }): JSX.Element {
   );
 }
 
+/**
+ * How many times one cart may claim the combo.
+ *
+ * Only at COMBO scope, because it is the only scope where the question means
+ * anything: an order-wide or category discount applies once by construction. A
+ * blank field is "as often as it fits", which is the merchant's usual answer
+ * and therefore the default rather than a number they have to type.
+ */
+function ComboCapField({ copy }: { copy: DiscountsWebCopy }): JSX.Element | null {
+  const { values } = useFormContext();
+  if (values.scope !== "COMBO") return null;
+  return (
+    <HintedField
+      name="maxComboApplications"
+      label={copy.form.maxComboApplications}
+      hint={copy.form.maxComboApplicationsHint}
+    />
+  );
+}
+
 /** The active window. Both sides optional; the end date is EXCLUSIVE. */
 export function WindowFields({ copy }: { copy: DiscountsWebCopy }): JSX.Element {
   return (
@@ -135,6 +205,7 @@ export function LimitFields({
       <Currency name="minSubtotal" label={copy.form.minSubtotal} />
       <Fields.TextField name="usageLimit" label={copy.form.usageLimit} type="number" />
       <Fields.TextField name="perBuyerLimit" label={copy.form.perBuyerLimit} type="number" />
+      <ComboCapField copy={copy} />
     </Box>
   );
 }

package/src/react/discount-form.tsx

@@ -12,8 +12,10 @@ import {
 } from "@12-apps/ui/form/total-form";
 import { Stack } from "@12-apps/ui/mui/Stack";
 
+import type { ComboRequirement } from "../engine/types";
+
 import type { DiscountFormPayload, DiscountsApiClient, DiscountWireRecord, WireTargetGroup } from "./api";
-import type { DiscountsWebCopy } from "./copy";
+import { fill, type DiscountsWebCopy } from "./copy";
 import {
   DiscountSwitches,
   LimitFields,
@@ -22,6 +24,7 @@ import {
   WindowFields,
   type CurrencyFieldComponent,
 } from "./discount-form-fields";
+import { comboUnits } from "./combo-slot-builder";
 import { DiscountTargetPicker } from "./discount-target-picker";
 import type { DiscountsFormatters } from "./format";
 
@@ -46,6 +49,9 @@ interface DiscountFormValues extends Record<string, string> {
   type: string;
   percentOff: string;
   amountOff: string;
+  bundlePrice: string;
+  freeUnits: string;
+  maxComboApplications: string;
   scope: string;
   trigger: string;
   code: string;
@@ -67,6 +73,9 @@ const BLANK: DiscountFormValues = {
   type: "PERCENTAGE",
   percentOff: "",
   amountOff: "",
+  bundlePrice: "",
+  freeUnits: "",
+  maxComboApplications: "",
   scope: "ORDER",
   trigger: "AUTOMATIC",
   code: "",
@@ -89,6 +98,10 @@ function initialValues(
     type: editing.type,
     percentOff: editing.percentOffBp === null ? "" : formatters.toInput(editing.percentOffBp / 100),
     amountOff: cents(editing.amountOffCents),
+    bundlePrice: cents(editing.bundlePriceCents ?? null),
+    freeUnits: editing.freeUnits == null ? "" : String(editing.freeUnits),
+    maxComboApplications:
+      editing.maxComboApplications == null ? "" : String(editing.maxComboApplications),
     scope: editing.scope,
     trigger: editing.trigger,
     code: editing.code ?? "",
@@ -100,31 +113,125 @@ function initialValues(
   };
 }
 
-/** The value half: a rate in (0, 100], or an amount above zero. */
+/** A whole number above zero, as typed. `null` when it is neither. */
+function positiveCount(typed: string): number | null {
+  const trimmed = typed.trim();
+  if (trimmed === "") return null;
+  const value = Number(trimmed);
+  return Number.isInteger(value) && value > 0 ? value : null;
+}
+
+/** A money field that has to hold something above zero. */
+function checkMoney(
+  typed: string,
+  field: string,
+  message: string,
+  formatters: DiscountsFormatters,
+): Record<string, string> {
+  const amount = formatters.parseDecimal(typed);
+  return amount === null || amount <= 0 ? { [field]: message } : {};
+}
+
+/**
+ * The free count, which is the one reward bounded by another field.
+ *
+ * "Take 3, three free" is a giveaway rather than a promotion, so it is compared
+ * against what ONE application of the combo takes out of the cart. The ceiling
+ * is named in the message: an operator told only "too many" has to guess the
+ * number.
+ */
+function checkFreeUnits(
+  typed: string,
+  slots: readonly ComboRequirement[],
+  copy: DiscountsWebCopy,
+): Record<string, string> {
+  const free = positiveCount(typed);
+  if (free === null) return { freeUnits: copy.form.invalidFreeUnits };
+  const units = comboUnits(slots);
+  if (free >= units) {
+    return {
+      freeUnits: fill(copy.form.freeUnitsExceedCombo, { units, max: Math.max(units - 1, 0) }),
+    };
+  }
+  return {};
+}
+
+/** The rate, in the 0–100 an operator thinks in rather than basis points. */
+function checkPercent(
+  typed: string,
+  formatters: DiscountsFormatters,
+  copy: DiscountsWebCopy,
+): Record<string, string> {
+  const percent = formatters.parseDecimal(typed);
+  return percent === null || percent <= 0 || percent > 100
+    ? { percentOff: copy.form.invalidPercent }
+    : {};
+}
+
+/** The reward, checked against the input the chosen type actually mounted. */
 function checkValue(
   values: DiscountFormValues,
+  slots: readonly ComboRequirement[],
   formatters: DiscountsFormatters,
   copy: DiscountsWebCopy,
 ): Record<string, string> {
-  if (values.type === "PERCENTAGE") {
-    const percent = formatters.parseDecimal(values.percentOff);
-    if (percent === null || percent <= 0 || percent > 100) {
-      return { percentOff: copy.form.invalidPercent };
-    }
-    return {};
+  if (values.type === "FIXED_AMOUNT") {
+    return checkMoney(values.amountOff, "amountOff", copy.form.invalidAmount, formatters);
+  }
+  if (values.type === "BUNDLE_PRICE") {
+    return checkMoney(values.bundlePrice, "bundlePrice", copy.form.invalidBundlePrice, formatters);
   }
-  const amount = formatters.parseDecimal(values.amountOff);
-  return amount === null || amount <= 0 ? { amountOff: copy.form.invalidAmount } : {};
+  if (values.type === "FREE_UNITS") return checkFreeUnits(values.freeUnits, slots, copy);
+  return checkPercent(values.percentOff, formatters, copy);
+}
+
+/**
+ * The combo half: the groups themselves, and the per-cart cap.
+ *
+ * Every rule here is also the server's (`validate-combo.ts`), and deliberately
+ * so — this half exists to attach the refusal to the input the operator is
+ * looking at, never to be the authority.
+ */
+function checkCombo(
+  values: DiscountFormValues,
+  slots: readonly ComboRequirement[],
+  copy: DiscountsWebCopy,
+): Record<string, string> {
+  if (values.scope !== "COMBO") return {};
+  if (slots.length === 0) return { scope: copy.form.comboSlotsRequired };
+  const errors: Record<string, string> = {};
+  if (slots.some((slot) => !Number.isInteger(slot.quantity) || slot.quantity <= 0)) {
+    errors.scope = copy.form.invalidComboQuantity;
+  } else if (
+    slots.some((slot) => slot.categoryIds.length === 0 && slot.menuItemIds.length === 0)
+  ) {
+    errors.scope = copy.form.comboSlotTargetRequired;
+  }
+  if (values.maxComboApplications.trim() !== "" && positiveCount(values.maxComboApplications) === null) {
+    errors.maxComboApplications = copy.form.invalidMaxComboApplications;
+  }
+  return errors;
+}
+
+/** What the pickers and the builder currently hold, in one argument. */
+interface FormTargets {
+  categoryIds: string[];
+  menuItemIds: string[];
+  comboRequirements: ComboRequirement[];
 }
 
 /** The cross-field rules a per-input schema cannot express. */
 function validate(
   values: DiscountFormValues,
-  targets: { categoryIds: string[]; menuItemIds: string[] },
+  targets: FormTargets,
   formatters: DiscountsFormatters,
   copy: DiscountsWebCopy,
 ): Record<string, string> {
-  const errors: Record<string, string> = { ...checkValue(values, formatters, copy) };
+  const slots = targets.comboRequirements;
+  const errors: Record<string, string> = {
+    ...checkValue(values, slots, formatters, copy),
+    ...checkCombo(values, slots, copy),
+  };
   if (values.trigger === "CODE" && values.code.trim() === "") {
     errors.code = copy.form.codeRequired;
   }
@@ -148,15 +255,23 @@ function useNonStringState(editing: DiscountWireRecord | null) {
   const [stackable, setStackable] = useState<boolean>(editing?.stackable ?? true);
   const [categoryIds, setCategoryIds] = useState<string[]>(editing?.categoryIds ?? []);
   const [menuItemIds, setMenuItemIds] = useState<string[]>(editing?.menuItemIds ?? []);
+  // The combo's groups are the third array, and the one whose ORDER matters:
+  // the list the operator built is the list a card reads back, and the server
+  // stamps each group's index as its stored `position`.
+  const [comboRequirements, setComboRequirements] = useState<ComboRequirement[]>(() =>
+    editing?.comboRequirements ? [...editing.comboRequirements] : [],
+  );
   return {
     active,
     stackable,
     categoryIds,
     menuItemIds,
+    comboRequirements,
     setActive,
     setStackable,
     setCategoryIds,
     setMenuItemIds,
+    setComboRequirements,
   };
 }
 
@@ -190,7 +305,11 @@ function makeSubmit(
   const { api, copy, formatters, editing, onSaved, onError } = props;
   return async function handleSubmit(values, { setFieldErrors }): Promise<void> {
     setError(null);
-    const targets = { categoryIds: extra.categoryIds, menuItemIds: extra.menuItemIds };
+    const targets: FormTargets = {
+      categoryIds: extra.categoryIds,
+      menuItemIds: extra.menuItemIds,
+      comboRequirements: extra.comboRequirements,
+    };
     const invalid = validate(values, targets, formatters, copy);
     if (Object.keys(invalid).length > 0) {
       setFieldErrors(invalid);
@@ -241,8 +360,10 @@ export function DiscountForm(props: DiscountFormProps): JSX.Element {
           selection={{
             categoryIds: extra.categoryIds,
             menuItemIds: extra.menuItemIds,
+            comboRequirements: extra.comboRequirements,
             onCategoryIdsChange: extra.setCategoryIds,
             onMenuItemIdsChange: extra.setMenuItemIds,
+            onComboRequirementsChange: extra.setComboRequirements,
           }}
         />
         <WindowFields copy={copy} />

package/src/react/discount-target-picker.tsx

@@ -1,23 +1,24 @@
 "use client";
 
-import { useState, type JSX } from "react";
+import type { JSX } from "react";
 
-import { Autocomplete } from "@12-apps/ui/form/Autocomplete";
-import { CategorySelect } from "@12-apps/ui/form/CategorySelect";
-import { FormControl, FormLabel, FormMessage } from "@12-apps/ui/form/Form";
 import { useFormContext } from "@12-apps/ui/form/total-form";
 
+import type { ComboRequirement } from "../engine/types";
+
+import type { WireTargetGroup } from "./api";
+import { ComboSlotBuilder } from "./combo-slot-builder";
 import { fill, type DiscountsWebCopy } from "./copy";
-import type { WireTarget, WireTargetGroup } from "./api";
+import { TargetPickerField } from "./target-picker-field";
 
 /**
  * What a scoped discount points at, picked from the host's own collections.
  *
- * There is no shared multi-select in `@12-apps/ui`, so this composes
- * `Autocomplete` in multiple mode — chips plus type-to-filter, the same control
- * `AddressAutocomplete` is built on. A collection that NESTS gets
- * `CategorySelect` instead: a flat combobox would put a subcategory beside its
- * parent with nothing to tell them apart.
+ * This file is the ROUTER: it reads the scope and decides which shape the
+ * targets take. The controls themselves live next door — one collection's
+ * picker in `target-picker-field`, the quantified group list in
+ * `combo-slot-builder` — because the combo builder needs the former per group
+ * and a file cannot import its own importer.
  *
  * Which collections exist is not decided here. The surface reads them from
  * `GET /discounts/targets`, which answers whatever the host registered — so
@@ -32,62 +33,15 @@ import type { WireTarget, WireTargetGroup } from "./api";
  * leaving a stale one on screen would suggest otherwise.
  */
 
-/** One labelled multi-select of targets, with its own input-text state. */
-function TargetField({
-  label,
-  placeholder,
-  requiredMessage,
-  options,
-  ids,
-  onChange,
-  dataTestId,
-}: {
-  label: string;
-  placeholder: string;
-  requiredMessage: string;
-  options: WireTarget[];
-  ids: readonly string[];
-  onChange: (next: string[]) => void;
-  dataTestId: string;
-}): JSX.Element {
-  const [query, setQuery] = useState("");
-  const byId = new Map(options.map((option) => [option.id, option]));
-  // An id whose option is missing — a target archived since the rule was saved
-  // — still renders as a chip, so saving cannot silently drop it.
-  const selected = ids.map((id) => byId.get(id) ?? { id, name: id });
-
-  return (
-    <FormControl fullWidth>
-      <FormLabel error={ids.length === 0}>{label}</FormLabel>
-      <div data-testid={dataTestId}>
-        <Autocomplete<WireTarget>
-          multiple
-          value={query}
-          onChange={setQuery}
-          suggestions={options}
-          selectedItems={selected}
-          onSelectedItemsChange={(items) => onChange(items.map((item) => item.id))}
-          getKey={(option) => option.id}
-          getLabel={(option) => option.name}
-          placeholder={placeholder}
-          inputAriaLabel={label}
-        />
-      </div>
-      {ids.length === 0 && (
-        <FormMessage error dataTestId={`${dataTestId}-message`}>
-          {requiredMessage}
-        </FormMessage>
-      )}
-    </FormControl>
-  );
-}
-
-/** The ids currently chosen for one dimension. */
+/** What the form currently has chosen, in every shape a scope can need. */
 interface DiscountTargetSelection {
   categoryIds: string[];
   menuItemIds: string[];
+  /** The combo's groups, in the operator's own order. Empty at every other scope. */
+  comboRequirements: readonly ComboRequirement[];
   onCategoryIdsChange: (next: string[]) => void;
   onMenuItemIdsChange: (next: string[]) => void;
+  onComboRequirementsChange: (next: ComboRequirement[]) => void;
 }
 
 /** Which selection a dimension reads and writes. */
@@ -112,6 +66,12 @@ function scopeFor(targetType: string): string {
  * Reads the LIVE `scope` from the form context, so flipping the toggle swaps
  * the picker immediately without the parent form having to mirror the value
  * into its own state.
+ *
+ * COMBO is the third branch (FUT-268) and it is a different SHAPE, not another
+ * picker: a combo is a list of quantified groups, so it gets the builder and
+ * every collection at once, while CATEGORY and ITEM each get exactly one
+ * collection's picker. ORDER still renders nothing — an order-wide discount
+ * covers everything, so a target list there is not empty, it is meaningless.
  */
 export function DiscountTargetPicker({
   groups,
@@ -124,36 +84,31 @@ export function DiscountTargetPicker({
 }): JSX.Element | null {
   const { values } = useFormContext();
   const scope = values.scope ?? "ORDER";
-  const group = groups.find((entry) => scopeFor(entry.targetType) === scope);
-  if (!group) return null;
-
-  const { ids, onChange } = bind(group.targetType, selection);
-  const label = fill(copy.targets.pick, { collection: group.label });
-  const dataTestId = `discount-${group.slug}-targets`;
 
-  if (group.nests) {
+  if (scope === "COMBO") {
     return (
-      <CategorySelect
-        label={label}
-        fullWidth
-        allowParentSelection
-        options={group.targets}
-        value={ids}
-        onChange={onChange}
-        error={ids.length === 0 ? copy.targets.required : undefined}
-        dataTestId={dataTestId}
+      <ComboSlotBuilder
+        slots={selection.comboRequirements}
+        groups={groups}
+        copy={copy}
+        onChange={selection.onComboRequirementsChange}
       />
     );
   }
+
+  const group = groups.find((entry) => scopeFor(entry.targetType) === scope);
+  if (!group) return null;
+
+  const { ids, onChange } = bind(group.targetType, selection);
   return (
-    <TargetField
-      label={label}
+    <TargetPickerField
+      group={group}
+      label={fill(copy.targets.pick, { collection: group.label })}
       placeholder={fill(copy.targets.search, { collection: group.label })}
       requiredMessage={copy.targets.required}
-      options={group.targets}
       ids={ids}
       onChange={onChange}
-      dataTestId={dataTestId}
+      dataTestId={`discount-${group.slug}-targets`}
     />
   );
 }

package/src/react/pt-BR.ts

@@ -75,6 +75,10 @@ export const PT_BR_DISCOUNTS_WEB_COPY: DiscountsWebCopy = {
     percentOff: "Desconto (%)",
     percentPlaceholder: "10",
     amountOff: "Valor do desconto",
+    bundlePrice: "Preço do combo",
+    freeUnits: "Itens grátis",
+    freeUnitsHint:
+      "Quantas unidades do combo saem de graça. Em um grupo de 3, deixar 1 grátis é o clássico \"leve 3, pague 2\".",
     trigger: "Ativação",
     code: "Código do cupom",
     codePlaceholder: "BEMVINDO10",
@@ -84,6 +88,8 @@ export const PT_BR_DISCOUNTS_WEB_COPY: DiscountsWebCopy = {
     minSubtotal: "Pedido mínimo",
     usageLimit: "Limite de usos",
     perBuyerLimit: "Limite por cliente",
+    maxComboApplications: "Combos por pedido",
+    maxComboApplicationsHint: "Deixe em branco para valer quantas vezes couber no carrinho.",
     active: "Ativo",
     activeHint: "Desligue para pausar a promoção sem excluí-la.",
     stackable: "Acumulável",
@@ -94,11 +100,30 @@ export const PT_BR_DISCOUNTS_WEB_COPY: DiscountsWebCopy = {
     nameRequired: "Informe o nome da promoção.",
     invalidPercent: "Informe uma porcentagem maior que 0 e no máximo 100.",
     invalidAmount: "Informe um valor de desconto maior que zero.",
+    invalidBundlePrice: "Informe o preço do combo, maior que zero.",
+    invalidFreeUnits: "Informe quantos itens saem de graça, a partir de 1.",
+    freeUnitsExceedCombo:
+      "O combo tem {units} itens; deixe grátis no máximo {max} para ainda ser uma promoção.",
     codeRequired: "Informe o código do cupom que o cliente vai digitar.",
     categoryTargetRequired: "Selecione ao menos uma categoria para este desconto.",
     itemTargetRequired: "Selecione ao menos um produto para este desconto.",
+    comboSlotsRequired: "Monte o combo: adicione ao menos um grupo de itens.",
+    comboSlotTargetRequired: "Escolha o que pode entrar em cada grupo do combo.",
+    invalidComboQuantity: "Informe quantas unidades cada grupo leva, a partir de 1.",
+    invalidMaxComboApplications: "Informe quantos combos cabem por pedido, a partir de 1.",
     endsBeforeStarts: "A data de término deve ser posterior à data de início.",
   },
+  combo: {
+    title: "Monte o combo",
+    hint: "Cada grupo é uma parte do combo: quantas unidades leva e o que pode entrar nela.",
+    addSlot: "Adicionar grupo",
+    removeSlot: "Remover o grupo {position}",
+    slot: "Grupo {position}",
+    quantity: "Quantidade",
+    pick: "{collection} deste grupo",
+    empty: "Nenhum grupo ainda. Adicione o primeiro para montar o combo.",
+    summary: "O combo leva {units} itens em {groups} grupos.",
+  },
   targets: {
     pick: "{collection} com desconto",
     search: "Buscar em {collection}…",

package/src/react/target-picker-field.tsx

@@ -0,0 +1,138 @@
+"use client";
+
+import { useState, type JSX } from "react";
+
+import { Autocomplete } from "@12-apps/ui/form/Autocomplete";
+import { CategorySelect } from "@12-apps/ui/form/CategorySelect";
+import { FormControl, FormLabel, FormMessage } from "@12-apps/ui/form/Form";
+
+import type { WireTarget, WireTargetGroup } from "./api";
+
+/**
+ * One collection's picker, in the two shapes a collection can take.
+ *
+ * Its own module because BOTH callers need it and they are not each other's
+ * parent: the scope-driven block renders one per discount, and the combo
+ * builder renders one per collection per GROUP. Importing it from either would
+ * make the two files a cycle, and copying it is how a nesting collection ends
+ * up a flat combobox in one of the two places — the exact bug this seam exists
+ * to prevent.
+ *
+ * There is no shared multi-select in `@12-apps/ui`, so the flat case composes
+ * `Autocomplete` in multiple mode — chips plus type-to-filter, the same control
+ * `AddressAutocomplete` is built on. A collection that NESTS gets
+ * `CategorySelect` instead: a flat combobox would put a subcategory beside its
+ * parent with nothing to tell them apart.
+ */
+
+/** One labelled multi-select of targets, with its own input-text state. */
+function TargetField({
+  label,
+  placeholder,
+  requiredMessage,
+  options,
+  ids,
+  onChange,
+  dataTestId,
+}: {
+  label: string;
+  placeholder: string;
+  requiredMessage: string | undefined;
+  options: readonly WireTarget[];
+  ids: readonly string[];
+  onChange: (next: string[]) => void;
+  dataTestId: string;
+}): JSX.Element {
+  const [query, setQuery] = useState("");
+  const byId = new Map(options.map((option) => [option.id, option]));
+  // An id whose option is missing — a target archived since the rule was saved
+  // — still renders as a chip, so saving cannot silently drop it.
+  const selected = ids.map((id) => byId.get(id) ?? { id, name: id });
+
+  const missing = requiredMessage !== undefined && ids.length === 0;
+
+  return (
+    <FormControl fullWidth>
+      <FormLabel error={missing}>{label}</FormLabel>
+      <div data-testid={dataTestId}>
+        <Autocomplete<WireTarget>
+          multiple
+          value={query}
+          onChange={setQuery}
+          suggestions={[...options]}
+          selectedItems={selected}
+          onSelectedItemsChange={(items) => onChange(items.map((item) => item.id))}
+          getKey={(option) => option.id}
+          getLabel={(option) => option.name}
+          placeholder={placeholder}
+          inputAriaLabel={label}
+        />
+      </div>
+      {missing && (
+        <FormMessage error dataTestId={`${dataTestId}-message`}>
+          {requiredMessage}
+        </FormMessage>
+      )}
+    </FormControl>
+  );
+}
+
+/**
+ * One collection's picker, for whoever is asking.
+ *
+ * Extracted because the COMBO builder needs the same control per GROUP, and a
+ * second copy is how a nesting collection ends up rendered as a flat combobox
+ * in one of the two places — the bug this seam exists to prevent. The caller
+ * supplies the label and the test id, because "Categorias com desconto" and
+ * "Categorias deste grupo" are different sentences about the same control.
+ *
+ * `requiredMessage` is OPTIONAL, and that is the difference between the two
+ * callers rather than an oversight. At CATEGORY/ITEM scope an empty picker IS
+ * the error, so the message hangs on it. Inside a combo group it is not: a
+ * group naming two categories and no items is complete, so the group as a whole
+ * carries the refusal and neither picker does.
+ */
+export function TargetPickerField({
+  group,
+  label,
+  placeholder,
+  requiredMessage,
+  ids,
+  onChange,
+  dataTestId,
+}: {
+  group: WireTargetGroup;
+  label: string;
+  placeholder: string;
+  requiredMessage: string | undefined;
+  ids: readonly string[];
+  onChange: (next: string[]) => void;
+  dataTestId: string;
+}): JSX.Element {
+  if (group.nests) {
+    return (
+      <CategorySelect
+        label={label}
+        fullWidth
+        allowParentSelection
+        options={[...group.targets]}
+        value={[...ids]}
+        onChange={onChange}
+        error={requiredMessage !== undefined && ids.length === 0 ? requiredMessage : undefined}
+        dataTestId={dataTestId}
+      />
+    );
+  }
+  return (
+    <TargetField
+      label={label}
+      placeholder={placeholder}
+      requiredMessage={requiredMessage}
+      options={group.targets}
+      ids={ids}
+      onChange={onChange}
+      dataTestId={dataTestId}
+    />
+  );
+}
+