@12-apps/discounts 1.5.0 → 1.6.0

package/src/react/form-kind.ts

@@ -0,0 +1,130 @@
+import { DISCOUNT_SCOPES, type DiscountScope, type DiscountType } from "../engine/kinds";
+
+/**
+ * The KIND of promotion an operator chooses, and the (type, scope) pair it
+ * stands for.
+ *
+ * The engine stores two independent columns — `type` (how the money is
+ * computed) and `scope` (what it is computed over) — and that is right for an
+ * evaluator, which has to answer both questions separately. It is wrong for the
+ * person creating the promotion: most of the sixteen combinations are not
+ * offers anybody sells, and the form used to present all of them. An operator
+ * could pick "Preço de combo" with scope `ORDER`, which the write path then
+ * refused, or pick scope `COMBO` and hunt for the reward input three screens
+ * up.
+ *
+ * So the form asks ONE question — what kind of promotion is this? — and derives
+ * the pair:
+ *
+ * | kind | type | scope | the operator still chooses |
+ * |---|---|---|---|
+ * | `PERCENTAGE` | `PERCENTAGE` | ORDER / CATEGORY / ITEM | the rate, and what it covers |
+ * | `FIXED_AMOUNT` | `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 |
+ * | `FREE_UNITS` | `FREE_UNITS` | `COMBO` | the products, how many, how many free |
+ *
+ * Two consequences worth stating, because both are deliberate:
+ *
+ * **A combo is a DISCOUNT off its items, never a price.** "2 refrigerantes, 2
+ * hambúrgueres e 2 batatas com 15% de desconto" and "…menos R$ 5,00" are the
+ * two offers a merchant describes; a flat "por R$ 49,90" reprices the group and
+ * silently goes wrong the moment one of its items changes price. `BUNDLE_PRICE`
+ * is still a legal type in the engine and in the database — an older rule that
+ * uses it keeps working and keeps being editable, see {@link kindOptions} — it
+ * is simply not offered for a new promotion.
+ *
+ * **`COMBO` scope is not a choice any more.** It was never one: a combo is
+ * defined by its groups, so "combo scope, but with an order-wide discount" is
+ * not an offer. The scope toggle therefore lists the three scopes that are
+ * genuinely a choice, and the two combo kinds carry `COMBO` implicitly.
+ */
+
+/** The kinds offered for a NEW promotion, in the order the toggle shows them. */
+export const DISCOUNT_KINDS = ["PERCENTAGE", "FIXED_AMOUNT", "COMBO", "FREE_UNITS"] as const;
+
+/**
+ * Every kind the form can HOLD, which is one more than it offers: a rule saved
+ * as `BUNDLE_PRICE` before combos became a discount still has to open, edit and
+ * save without losing what it is.
+ */
+export type DiscountKind = (typeof DISCOUNT_KINDS)[number] | "BUNDLE_PRICE";
+
+/**
+ * True when this kind's targets are groups — a builder, not a flat picker, and
+ * `COMBO` scope rather than a scope the operator chose.
+ *
+ * The list is inline rather than an exported constant: nothing outside this
+ * predicate should be branching on the set, and an exported one invites a
+ * second `includes` that drifts from this one.
+ */
+export function isComboKind(kind: string): boolean {
+  return kind === "COMBO" || kind === "FREE_UNITS" || kind === "BUNDLE_PRICE";
+}
+
+/** The scopes the toggle offers: every scope except the one a kind implies. */
+export const SELECTABLE_DISCOUNT_SCOPES: readonly DiscountScope[] = DISCOUNT_SCOPES.filter(
+  (scope) => scope !== "COMBO",
+);
+
+/**
+ * Which kind an existing rule is, read back from the pair it was stored as.
+ *
+ * `FREE_UNITS` is checked before the scope because it is the narrower fact: it
+ * is only ever legal at `COMBO` scope, so the type alone identifies it.
+ */
+export function kindOf(rule: { type: string; scope: string } | null): DiscountKind {
+  if (rule === null) return "PERCENTAGE";
+  if (rule.type === "BUNDLE_PRICE") return "BUNDLE_PRICE";
+  if (rule.type === "FREE_UNITS") return "FREE_UNITS";
+  if (rule.scope === "COMBO") return "COMBO";
+  return rule.type === "FIXED_AMOUNT" ? "FIXED_AMOUNT" : "PERCENTAGE";
+}
+
+/**
+ * The kinds this particular form may show — the four, plus `BUNDLE_PRICE` when
+ * that is what is being edited.
+ *
+ * Appended rather than inserted so the four keep the positions an operator has
+ * learned, and present ONLY on the legacy rule's own form: an operator editing
+ * a percentage promotion is not offered a bundle price they cannot create.
+ */
+export function kindOptions(editing: { type: string; scope: string } | null): DiscountKind[] {
+  const kind = kindOf(editing);
+  return kind === "BUNDLE_PRICE" ? [...DISCOUNT_KINDS, kind] : [...DISCOUNT_KINDS];
+}
+
+/**
+ * A combo's reward is one of the two plain types, chosen separately from the
+ * kind — "15% off the combo" and "R$ 5,00 off the combo" are the same kind of
+ * promotion with different arithmetic.
+ */
+export const COMBO_REWARDS = ["PERCENTAGE", "FIXED_AMOUNT"] as const;
+
+/** Which reward an existing combo was saved with. */
+export function comboRewardOf(rule: { type: string } | null): string {
+  return rule?.type === "FIXED_AMOUNT" ? "FIXED_AMOUNT" : "PERCENTAGE";
+}
+
+/**
+ * The engine pair this form currently describes.
+ *
+ * The one place the four questions on screen become the two columns the API
+ * takes, so nothing downstream has to know that `COMBO` is a kind rather than a
+ * type. A stale `scope` left over from a kind switch is clamped to `ORDER`
+ * rather than trusted: the toggle is unmounted at combo kinds, so its value is
+ * whatever it was before the operator changed their mind.
+ */
+export function typeAndScopeFor(values: {
+  kind: string;
+  comboReward: string;
+  scope: string;
+}): { type: DiscountType; scope: DiscountScope } {
+  if (values.kind === "COMBO") {
+    const type = values.comboReward === "FIXED_AMOUNT" ? "FIXED_AMOUNT" : "PERCENTAGE";
+    return { type, scope: "COMBO" };
+  }
+  if (values.kind === "FREE_UNITS") return { type: "FREE_UNITS", scope: "COMBO" };
+  if (values.kind === "BUNDLE_PRICE") return { type: "BUNDLE_PRICE", scope: "COMBO" };
+  const type = values.kind === "FIXED_AMOUNT" ? "FIXED_AMOUNT" : "PERCENTAGE";
+  return { type, scope: values.scope === "COMBO" ? "ORDER" : (values.scope as DiscountScope) };
+}

package/src/react/free-units-builder.tsx

@@ -0,0 +1,180 @@
+"use client";
+
+import type { JSX } from "react";
+
+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 { blankSlot } from "./combo-slot-builder";
+import { fill, type DiscountsWebCopy } from "./copy";
+import { TargetPickerField } from "./target-picker-field";
+
+/**
+ * "Leve 3, pague 2" — the free-units builder (FUT-268).
+ *
+ * Underneath it is a combo like any other: ONE group of three units, one of
+ * which is free. But an operator describing "leve 3, pague 2" is not building a
+ * combo, and making them add a group, name it, and then find `freeUnits`
+ * somewhere else turns a one-sentence offer into the hardest form on the
+ * screen. So this kind gets a shape of its own: how many the customer takes,
+ * which products count, how many are free.
+ *
+ * **Products only, never categories.** A single group is the whole promotion
+ * here, so "the customer takes 3" has to name things the customer recognises.
+ * The multi-group builder next door still offers both collections — there a
+ * group naming a category is exactly right ("2 refrigerantes").
+ *
+ * The state it edits is the same `ComboRequirement[]` the combo builder edits,
+ * with the list capped at one. That is what lets the two kinds share a
+ * validator, a write path and a stored shape: switching a rule between them
+ * changes which control is on screen, not what is saved.
+ */
+
+/** The one group this kind edits, or a blank one when nothing is chosen yet. */
+function onlySlot(slots: readonly ComboRequirement[]): ComboRequirement {
+  return slots[0] ?? blankSlot();
+}
+
+/** How many the customer pays for: what they take, minus what is free. */
+function paidUnits(taken: number, free: number): number {
+  return Math.max(taken - free, 0);
+}
+
+/**
+ * The read-back sentence, in the operator's own numbers.
+ *
+ * Only once BOTH numbers make one — "leve 3, pague 0" is a giveaway and "leve
+ * 1, pague 1" is not a promotion, and the validator refuses both. Showing the
+ * sentence anyway would read as confirmation of an offer that cannot be saved.
+ */
+function summaryOf(taken: number, free: number, copy: DiscountsWebCopy): string | null {
+  if (!Number.isInteger(taken) || taken < 2 || !Number.isInteger(free) || free < 1) return null;
+  if (free >= taken) return null;
+  return fill(copy.combo.freeUnitsSummary, { units: taken, paid: paidUnits(taken, free) });
+}
+
+/**
+ * The two numbers that ARE the offer: how many the customer takes, and how many
+ * of those are free.
+ *
+ * Split from the builder purely for the function-size gate, but the seam is the
+ * right one anyway — this pair is the sentence, and the picker below it is the
+ * list of things the sentence is about.
+ */
+function FreeUnitsCounts({
+  quantity,
+  freeUnits,
+  copy,
+  error,
+  onQuantity,
+  onFreeUnits,
+}: {
+  quantity: number;
+  freeUnits: string;
+  copy: DiscountsWebCopy;
+  error: string | undefined;
+  onQuantity: (next: number) => void;
+  onFreeUnits: (next: string) => void;
+}): JSX.Element {
+  return (
+    <Box sx={{ display: "grid", gap: 2, gridTemplateColumns: { xs: "1fr", sm: "1fr 1fr" } }}>
+      <Input
+        type="number"
+        label={copy.combo.buyQuantity}
+        value={String(quantity)}
+        onChange={(event) => onQuantity(Number(event.target.value))}
+        data-testid="free-units-quantity"
+      />
+      <Input
+        type="number"
+        label={copy.form.freeUnits}
+        value={freeUnits}
+        onChange={(event) => onFreeUnits(event.target.value)}
+        error={error !== undefined}
+        data-testid="free-units-free"
+      />
+    </Box>
+  );
+}
+
+export function FreeUnitsBuilder({
+  slots,
+  groups,
+  copy,
+  freeUnits,
+  error,
+  onChange,
+  onFreeUnitsChange,
+}: {
+  slots: readonly ComboRequirement[];
+  groups: readonly WireTargetGroup[];
+  copy: DiscountsWebCopy;
+  /** The reward, as typed. Held by the form so the validator can read it. */
+  freeUnits: string;
+  /**
+   * The validator's refusal for that reward, since the input above is a raw
+   * `Input` rather than a bound `Fields.TextField` — a bound field would paint
+   * this itself, but it would also sit outside the sentence it belongs to.
+   */
+  error: string | undefined;
+  onChange: (next: ComboRequirement[]) => void;
+  onFreeUnitsChange: (next: string) => void;
+}): JSX.Element | null {
+  const items = groups.find((group) => group.targetType === "ITEM");
+  if (!items) return null;
+
+  const slot = onlySlot(slots);
+  const summary = summaryOf(slot.quantity, Number(freeUnits), copy);
+  const empty = slot.menuItemIds.length === 0;
+
+  return (
+    <FormControl fullWidth>
+      <FormLabel>{copy.combo.freeUnitsTitle}</FormLabel>
+      <Text variant="caption">{copy.combo.freeUnitsHint}</Text>
+      <Stack spacing={2} sx={{ mt: 1 }} data-testid="free-units-builder">
+        <FreeUnitsCounts
+          quantity={slot.quantity}
+          freeUnits={freeUnits}
+          copy={copy}
+          error={error}
+          onQuantity={(quantity) => onChange([{ ...slot, quantity }])}
+          onFreeUnits={onFreeUnitsChange}
+        />
+        <TargetPickerField
+          group={items}
+          label={fill(copy.combo.freeUnitsPick, { collection: items.label })}
+          placeholder={fill(copy.targets.search, { collection: items.label })}
+          // The refusal is the BUILDER's, not the picker's — the same call the
+          // multi-group builder makes, so the two read alike when a rule is
+          // switched between them.
+          requiredMessage={undefined}
+          ids={slot.menuItemIds}
+          onChange={(ids) => onChange([{ ...slot, menuItemIds: ids }])}
+          copy={copy.categorySelect}
+          dataTestId="free-units-items"
+        />
+        {error !== undefined && (
+          <FormMessage error dataTestId="free-units-free-message">
+            {error}
+          </FormMessage>
+        )}
+        {empty ? (
+          <FormMessage error dataTestId="free-units-message">
+            {copy.form.freeUnitsTargetRequired}
+          </FormMessage>
+        ) : null}
+        {summary !== null && (
+          <Text variant="caption" data-testid="free-units-summary">
+            {summary}
+          </Text>
+        )}
+      </Stack>
+    </FormControl>
+  );
+}

package/src/react/pt-BR.ts

@@ -43,6 +43,13 @@ export const PT_BR_DISCOUNTS_WEB_COPY: DiscountsWebCopy = {
     no: "Não",
   },
   labels: {
+    kind: {
+      PERCENTAGE: "Porcentagem",
+      FIXED_AMOUNT: "Valor fixo",
+      COMBO: "Combo",
+      FREE_UNITS: "Itens grátis",
+      BUNDLE_PRICE: "Preço de combo",
+    },
     type: {
       PERCENTAGE: "Porcentagem",
       FIXED_AMOUNT: "Valor fixo",
@@ -78,6 +85,9 @@ export const PT_BR_DISCOUNTS_WEB_COPY: DiscountsWebCopy = {
     submitEdit: "Salvar alterações",
     name: "Nome da promoção",
     type: "Tipo",
+    kind: "Tipo de promoção",
+    comboReward: "Desconto do combo",
+    comboRewardHint: "O combo sai pelo preço dos itens menos este desconto.",
     percentOff: "Desconto (%)",
     percentPlaceholder: "10",
     amountOff: "Valor do desconto",
@@ -96,6 +106,7 @@ export const PT_BR_DISCOUNTS_WEB_COPY: DiscountsWebCopy = {
     perBuyerLimit: "Limite por cliente",
     maxComboApplications: "Combos por pedido",
     maxComboApplicationsHint: "Deixe em branco para valer quantas vezes couber no carrinho.",
+    maxFreeUnitsApplications: "Vezes por pedido",
     active: "Ativo",
     activeHint: "Desligue para pausar a promoção sem excluí-la.",
     stackable: "Acumulável",
@@ -110,6 +121,7 @@ export const PT_BR_DISCOUNTS_WEB_COPY: DiscountsWebCopy = {
     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.",
+    freeUnitsTargetRequired: "Escolha ao menos um produto para a 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.",
@@ -129,6 +141,12 @@ export const PT_BR_DISCOUNTS_WEB_COPY: DiscountsWebCopy = {
     pick: "{collection} deste grupo",
     empty: "Nenhum grupo ainda. Adicione o primeiro para montar o combo.",
     summary: "O combo leva {units} itens em {groups} grupos.",
+    freeUnitsTitle: "Leve mais, pague menos",
+    freeUnitsHint:
+      "Escolha os produtos, quantos o cliente leva e quantos saem de graça — é o clássico \"leve 3, pague 2\".",
+    buyQuantity: "O cliente leva",
+    freeUnitsPick: "{collection} da promoção",
+    freeUnitsSummary: "Leve {units}, pague {paid}.",
   },
   targets: {
     pick: "{collection} com desconto",