@12-apps/discounts 1.5.0 → 1.6.0

package/README.md

@@ -349,21 +349,50 @@ 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:
+is where that stops being a table in a README. It asks ONE question — what KIND
+of promotion is this — and derives the pair (`src/react/form-kind.ts`):
 
-| the offer | scope | type | what the operator fills in |
+| the operator picks | type | scope | and is then asked |
 |---|---|---|---|
-| "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 |
+| 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 |
+| Itens grátis | `FREE_UNITS` | `COMBO` | the products, how many, how many free |
 
-Picking `COMBO` swaps the single target picker for the **group builder**: each
+So the offers a merchant describes map one to one onto what they fill in:
+
+| the offer | kind | what the operator fills 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 |
+
+Two consequences of asking the kind instead of the pair:
+
+- **`COMBO` is not a scope anybody picks.** A combo covers the groups it is
+  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.
+
+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.
 
+"Itens grátis" gets a builder of its own instead (`free-units-builder.tsx`):
+one group, PRODUCTS only, and the two numbers side by side — "o cliente leva 3,
+1 sai de graça". It is the same stored shape as a one-group combo, which is
+what lets the two kinds share a validator, a write path and a row; nobody
+describing "leve 3, pague 2" is building a combo, so nobody is asked to.
+
 Three consequences worth stating, because each is a bug this shape prevents:
 
 - **The reward input is MOUNTED, not hidden.** The four value columns are

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/discounts",
-  "version": "1.5.0",
+  "version": "1.6.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": {
@@ -28,10 +28,10 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@12-apps/app-shell": "^5.1.0",
+    "@12-apps/app-shell": "^5.2.0",
     "@12-apps/forms-core": "^1.20.0",
     "@12-apps/shared-helpers": "^2.0.2",
-    "@12-apps/ui": "^6.3.0",
+    "@12-apps/ui": "^6.3.1",
     "@mui/icons-material": "^6.5.0",
     "zod": "^4.3.5"
   },

package/src/engine/combo-match.ts

@@ -368,3 +368,24 @@ export function comboCoveredLineIds(
 export function comboRuleAcceptsLine(rule: DiscountRule, line: DiscountCartLine): boolean {
   return prepareSlots(rule.comboRequirements ?? []).some((slot) => slotAccepts(slot, line));
 }
+
+/**
+ * Whether ONE slot accepts this line — the same predicate, asked per group.
+ *
+ * A storefront advertising a combo has to answer a question the cart never
+ * does: not "does this product take part" but "which GROUP does it fill", so
+ * that "escolha 2 refrigerantes" offers sodas and not burgers. That is
+ * `slotAccepts` with nothing added, and it is exported rather than reimplemented
+ * because a second copy is how a menu ends up offering a product the matcher
+ * will not accept — a combo the buyer can assemble on screen and never earn.
+ *
+ * It takes a `ComboRequirement` rather than a whole rule, because the caller is
+ * iterating a rule's groups and needs to know which one it is looking at.
+ */
+export function comboSlotAcceptsLine(
+  requirement: ComboRequirement,
+  line: DiscountCartLine,
+): boolean {
+  const [slot] = prepareSlots([requirement]);
+  return slot !== undefined && slotAccepts(slot, line);
+}

package/src/engine/combo-offer.ts

@@ -120,6 +120,32 @@ function toOffer(rule: DiscountRule): ComboOffer {
   };
 }
 
+/**
+ * Every combo the store is currently advertising, in the evaluator's canonical
+ * rule order.
+ *
+ * The STORE-level sibling of {@link comboOffersForItem}: same predicate, no
+ * item. A storefront that shows combos as their own shelf — "here are the
+ * bundles this shop is running" rather than "this card takes part in one" —
+ * needs the list before it has a product in hand, and answering it host-side
+ * means a second copy of "live enough to advertise" that drifts from this one
+ * the first time a rule gains a way to be over.
+ *
+ * It says nothing about whether the store can still SELL them: a combo whose
+ * group has no orderable product left is a question about the host's catalog,
+ * which this package cannot see. The caller resolves the groups and drops what
+ * it cannot fill.
+ */
+export function advertisableCombos(
+  rules: readonly DiscountRule[],
+  now: Date,
+): readonly ComboOffer[] {
+  return rules
+    .filter((rule) => isAdvertisable(rule, now))
+    .sort(compareRuleOrder)
+    .map(toOffer);
+}
+
 /**
  * Every live combo one of whose slots this item can fill, in the evaluator's
  * canonical rule order so a card and a cart never disagree about which combo

package/src/index.ts

@@ -77,6 +77,7 @@ export {
  * say about one.
  */
 export {
+  advertisableCombos,
   comboOffersForItem,
   type ComboOffer,
   type ComboOffersInput,
@@ -87,8 +88,14 @@ export {
  * "aplicado 2x", "faltam 2 refrigerantes" — needs the same match the evaluator
  * priced, and re-deriving it host-side is how a receipt and a cart start
  * disagreeing about what was in the bundle.
+ *
+ * `comboSlotAcceptsLine` is the same reason one level down: a storefront
+ * ADVERTISING a combo has to fill "escolha 2 refrigerantes" with sodas rather
+ * than with everything the combo names, and a host answering that itself is how
+ * a menu offers a product the matcher will not accept.
  */
 export {
+  comboSlotAcceptsLine,
   freshComboPool,
   matchCombo,
   type ComboMatch,

package/src/react/copy.ts

@@ -73,6 +73,13 @@ export interface DiscountsScreenCopy {
 
 /** The four closed sets, each labelled in full. */
 export interface DiscountsVocabularyCopy {
+  /**
+   * The KIND toggle's words — the one question the form actually asks (see
+   * `./form-kind`). It is keyed by `DiscountType` because every kind is named
+   * after the type it stands for, `COMBO` included: a combo IS a discount, and
+   * `BUNDLE_PRICE`'s label survives for the legacy rules that still carry it.
+   */
+  readonly kind: LabelsFor<DiscountType | "COMBO">;
   readonly type: LabelsFor<DiscountType>;
   readonly scope: LabelsFor<DiscountScope>;
   readonly trigger: LabelsFor<DiscountTrigger>;
@@ -99,6 +106,11 @@ export interface DiscountsFormCopy {
   readonly submitEdit: string;
   readonly name: string;
   readonly type: string;
+  /** The kind toggle's own label — the form's first real question. */
+  readonly kind: string;
+  /** Which of the two rewards a COMBO gives, and the sentence under it. */
+  readonly comboReward: string;
+  readonly comboRewardHint: string;
   readonly percentOff: string;
   /** The example inside the empty percentage input. */
   readonly percentPlaceholder: string;
@@ -122,6 +134,8 @@ export interface DiscountsFormCopy {
   /** How many times ONE cart may claim the combo. Blank = as often as it fits. */
   readonly maxComboApplications: string;
   readonly maxComboApplicationsHint: string;
+  /** The same cap for "leve 3, pague 2", which nobody calls a combo. */
+  readonly maxFreeUnitsApplications: string;
   readonly active: string;
   readonly activeHint: string;
   readonly stackable: string;
@@ -142,6 +156,8 @@ export interface DiscountsFormCopy {
    * that number, so the operator is told the ceiling rather than just refused.
    */
   readonly freeUnitsExceedCombo: string;
+  /** The free-units builder names PRODUCTS, so its refusal says products. */
+  readonly freeUnitsTargetRequired: string;
   readonly codeRequired: string;
   readonly categoryTargetRequired: string;
   readonly itemTargetRequired: string;
@@ -185,6 +201,20 @@ export interface DiscountsComboCopy {
    * checked without saving it. `{units}` and `{groups}`.
    */
   readonly summary: string;
+  /**
+   * The "leve 3, pague 2" builder (`./free-units-builder`), which is the same
+   * stored shape wearing the sentence an operator would actually say. Its own
+   * keys rather than the group builder's: "Grupo 1" and "Quantidade" are right
+   * for a combo of several groups and wrong for one offer about one shelf.
+   */
+  readonly freeUnitsTitle: string;
+  readonly freeUnitsHint: string;
+  /** How many units the customer takes to earn the free ones. */
+  readonly buyQuantity: string;
+  /** That builder's picker label, `{collection}` — one offer, not one group. */
+  readonly freeUnitsPick: string;
+  /** The read-back, once both numbers make an offer. `{units}` and `{paid}`. */
+  readonly freeUnitsSummary: string;
 }
 
 /** The target pickers, and what an empty selection says. */

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

@@ -8,28 +8,32 @@ 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";
+import { DISCOUNT_TRIGGERS } from "../engine/kinds";
 
 import type { DiscountsWebCopy } from "./copy";
+import { COMBO_REWARDS, isComboKind, SELECTABLE_DISCOUNT_SCOPES, type DiscountKind } from "./form-kind";
 
 /**
  * The form's inputs, split from the form itself for the 400-line file gate —
  * comments count toward it, and the container plus these would not fit.
  *
- * Every option list is built FROM the vocabulary arrays rather than spelled out
+ * Every option list is built FROM a vocabulary array rather than spelled out
  * again: those arrays back the database's CHECK constraints, so an option an
  * operator can pick is by construction a value the column will store. A
  * hand-written list is how a form offers a fifth type the database refuses.
+ *
+ * The KIND is what the form asks first, and every other input here is a
+ * consequence of it (see `./form-kind` for the mapping and why it exists). That
+ * is the difference from the version this replaces, where type and scope were
+ * two free choices and most of their sixteen combinations were not offers.
  */
 
 /**
  * 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.
+ * over `Input` — and the combo cap is meaningless without one: "combos por
+ * pedido" is a number whose blank value an operator cannot guess.
  */
 function HintedField({
   name,
@@ -57,41 +61,106 @@ function optionsFor<TKey extends string>(
 }
 
 /**
- * The reward, in whichever unit the chosen type actually stores.
+ * A money input, supplied by the host.
  *
- * One input per type, and the wrong one must never be mounted: the four value
+ * Currency entry is a host decision — masking, the symbol's side, whether cents
+ * are typed or implied — and `@12-apps/ui` has no opinionated one. So the
+ * surface takes the component rather than shipping a guess; a host with nothing
+ * special passes a plain text field.
+ */
+export type CurrencyFieldComponent = (props: { name: string; label: string }) => JSX.Element;
+
+/**
+ * What kind of promotion this is — the form's first and most consequential
+ * question, and the only one that decides what the rest of it looks like.
+ *
+ * The option list comes from the caller rather than from the constant, because
+ * it is one longer when a legacy `BUNDLE_PRICE` rule is being edited.
+ */
+export function KindField({
+  copy,
+  kinds,
+}: {
+  copy: DiscountsWebCopy;
+  kinds: readonly DiscountKind[];
+}): JSX.Element {
+  return (
+    <Fields.ToggleField
+      name="kind"
+      label={copy.form.kind}
+      options={optionsFor(kinds, copy.labels.kind)}
+    />
+  );
+}
+
+/**
+ * A combo's reward: which of the two, and how much.
+ *
+ * Both are here rather than split between the top of the form and the bottom,
+ * because to a merchant they are one sentence — "este combo dá 15% de
+ * desconto". The two are the ONLY rewards a combo can give: a flat bundle price
+ * reprices the group and goes silently wrong the first time one of its items
+ * changes price, so it is not offered (see `./form-kind`).
+ */
+function ComboRewardFields({
+  copy,
+  currencyField,
+}: {
+  copy: DiscountsWebCopy;
+  currencyField: CurrencyFieldComponent;
+}): JSX.Element {
+  const { values } = useFormContext();
+  const Currency = currencyField;
+  return (
+    <Stack spacing={0.5}>
+      <Box sx={{ display: "grid", gap: 2, gridTemplateColumns: { xs: "1fr", sm: "1fr 1fr" } }}>
+        <Fields.ToggleField
+          name="comboReward"
+          label={copy.form.comboReward}
+          options={optionsFor(COMBO_REWARDS, copy.labels.type)}
+        />
+        {values.comboReward === "FIXED_AMOUNT" ? (
+          <Currency name="amountOff" label={copy.form.amountOff} />
+        ) : (
+          <Fields.TextField
+            name="percentOff"
+            label={copy.form.percentOff}
+            placeholder={copy.form.percentPlaceholder}
+          />
+        )}
+      </Box>
+      <Text variant="caption">{copy.form.comboRewardHint}</Text>
+    </Stack>
+  );
+}
+
+/**
+ * The reward, in whichever unit the chosen KIND actually stores.
+ *
+ * One input per kind, 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.
+ * 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.
+ * `FREE_UNITS` is the one kind with nothing here: its reward is a count of the
+ * units it gives away, which only reads as an offer beside the units it takes,
+ * so the free-units builder carries both.
  */
-function ValueField({
+export function RewardFields({
   copy,
   currencyField,
 }: {
   copy: DiscountsWebCopy;
   currencyField: CurrencyFieldComponent;
-}): JSX.Element {
+}): JSX.Element | null {
   const { values } = useFormContext();
   const Currency = currencyField;
-  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} />
-    );
-  }
+  const kind = values.kind ?? "PERCENTAGE";
+  if (kind === "COMBO") return <ComboRewardFields copy={copy} currencyField={currencyField} />;
+  if (kind === "FREE_UNITS") return null;
+  if (kind === "BUNDLE_PRICE") return <Currency name="bundlePrice" label={copy.form.bundlePrice} />;
+  if (kind === "FIXED_AMOUNT") return <Currency name="amountOff" label={copy.form.amountOff} />;
   return (
     <Fields.TextField
       name="percentOff"
@@ -101,16 +170,6 @@ function ValueField({
   );
 }
 
-/**
- * A money input, supplied by the host.
- *
- * Currency entry is a host decision — masking, the symbol's side, whether cents
- * are typed or implied — and `@12-apps/ui` has no opinionated one. So the
- * surface takes the component rather than shipping a guess; a host with nothing
- * special passes a plain text field.
- */
-export type CurrencyFieldComponent = (props: { name: string; label: string }) => JSX.Element;
-
 /** The coupon input, shown only for a CODE-triggered rule. */
 function CodeField({ copy }: { copy: DiscountsWebCopy }): JSX.Element | null {
   const { values } = useFormContext();
@@ -124,22 +183,10 @@ function CodeField({ copy }: { copy: DiscountsWebCopy }): JSX.Element | null {
   );
 }
 
-/** Type + value + trigger + code, the four that decide WHAT and HOW. */
-export function RuleFields({
-  copy,
-  currencyField,
-}: {
-  copy: DiscountsWebCopy;
-  currencyField: CurrencyFieldComponent;
-}): JSX.Element {
+/** What makes the promotion fire, and the code it fires on. */
+export function TriggerFields({ copy }: { copy: DiscountsWebCopy }): JSX.Element {
   return (
     <Box sx={{ display: "grid", gap: 2, gridTemplateColumns: { xs: "1fr", sm: "1fr 1fr" } }}>
-      <Fields.ToggleField
-        name="type"
-        label={copy.form.type}
-        options={optionsFor(DISCOUNT_TYPES, copy.labels.type)}
-      />
-      <ValueField copy={copy} currencyField={currencyField} />
       <Fields.ToggleField
         name="trigger"
         label={copy.form.trigger}
@@ -150,13 +197,22 @@ export function RuleFields({
   );
 }
 
-/** The scope toggle, which decides which target picker is shown below it. */
-export function ScopeField({ copy }: { copy: DiscountsWebCopy }): JSX.Element {
+/**
+ * What the discount covers — and ONLY for the kinds where that is a question.
+ *
+ * A combo covers the groups it is made of, so `COMBO` scope is not one of four
+ * choices, it is what those two kinds mean. Offering it anyway is what let an
+ * operator build "preço de combo, abrangência: pedido" and have the write path
+ * refuse it.
+ */
+export function ScopeField({ copy }: { copy: DiscountsWebCopy }): JSX.Element | null {
+  const { values } = useFormContext();
+  if (isComboKind(values.kind ?? "PERCENTAGE")) return null;
   return (
     <Fields.ToggleField
       name="scope"
       label={copy.form.scope}
-      options={optionsFor(DISCOUNT_SCOPES, copy.labels.scope)}
+      options={optionsFor(SELECTABLE_DISCOUNT_SCOPES, copy.labels.scope)}
     />
   );
 }
@@ -164,18 +220,30 @@ 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
+ * Only for a combo kind, because it is the only place 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.
+ *
+ * It sits with the builder rather than with the redemption limits next to it:
+ * "combos por pedido" is a fact about THIS combo, and among "limite de usos"
+ * and "limite por cliente" it read as a third redemption cap.
  */
-function ComboCapField({ copy }: { copy: DiscountsWebCopy }): JSX.Element | null {
+export function ComboCapField({ copy }: { copy: DiscountsWebCopy }): JSX.Element | null {
   const { values } = useFormContext();
-  if (values.scope !== "COMBO") return null;
+  const kind = values.kind ?? "PERCENTAGE";
+  if (!isComboKind(kind)) return null;
   return (
     <HintedField
       name="maxComboApplications"
-      label={copy.form.maxComboApplications}
+      // Same column, same rule, two words for it: nobody calls "leve 3, pague
+      // 2" a combo, so "Combos por pedido" reads as a control for a promotion
+      // the operator is not creating.
+      label={
+        kind === "FREE_UNITS"
+          ? copy.form.maxFreeUnitsApplications
+          : copy.form.maxComboApplications
+      }
       hint={copy.form.maxComboApplicationsHint}
     />
   );
@@ -205,7 +273,6 @@ 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>
   );
 }