@12-apps/discounts 1.2.0 → 1.4.0

package/src/react/api.ts

@@ -0,0 +1,209 @@
+import type { ComboRequirement } from "../engine/types";
+
+import type { DiscountsFormatters } from "./format";
+import type { DiscountsResult, DiscountsTransport } from "./transport";
+
+/**
+ * The wire, and the one place the FORM's shape becomes the API's.
+ *
+ * A form holds strings — every value in a text input is one — while the API
+ * takes integers, basis points and nulls. That coercion is a real rule set, not
+ * plumbing, and it has exactly one rule worth stating: a BLANK field means "no
+ * value" (`null`), never zero, because `0` is a real and different answer for a
+ * limit or a minimum. A host repeating this per call site is how one screen
+ * starts saving `0` where another saves `null`.
+ */
+
+/** A discount as the CRUD endpoints echo it — JSON, so dates are ISO strings. */
+export interface DiscountWireRecord {
+  id: string;
+  name: string;
+  type: string;
+  percentOffBp: number | null;
+  amountOffCents: number | null;
+  bundlePriceCents?: number | null;
+  freeUnits?: number | null;
+  maxComboApplications?: number | null;
+  comboRequirements?: ComboRequirement[];
+  scope: string;
+  trigger: string;
+  code: string | null;
+  startsAt: string | null;
+  endsAt: string | null;
+  minSubtotalCents: number | null;
+  usageLimit: number | null;
+  perBuyerLimit: number | null;
+  usageCount: number;
+  stackable: boolean;
+  active: boolean;
+  categoryIds: string[];
+  menuItemIds: string[];
+  createdAt: string;
+}
+
+/** The pagination envelope the list endpoint answers with. */
+export interface DiscountsPagination {
+  page: number;
+  pageSize: number;
+  total: number;
+  pageCount: number;
+  hasNextPage: boolean;
+  hasPreviousPage: boolean;
+}
+
+export interface DiscountsPage {
+  data: DiscountWireRecord[];
+  pagination: DiscountsPagination;
+}
+
+/** One selectable target, as `GET /discounts/targets` answers it. */
+export interface WireTarget {
+  id: string;
+  name: string;
+  parentId?: string | null;
+}
+
+/** One registered collection and its rows. */
+export interface WireTargetGroup {
+  targetType: string;
+  slug: string;
+  label: string;
+  nests: boolean;
+  targets: WireTarget[];
+}
+
+/** The form's payload, still in FORM shape. */
+export interface DiscountFormPayload {
+  name: string;
+  type: string;
+  /** 0–100 with up to two decimals, in the operator's own notation. */
+  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;
+  startsAt: string;
+  endsAt: string;
+  minSubtotal: string;
+  usageLimit: string;
+  perBuyerLimit: string;
+  stackable: boolean;
+  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. */
+function toCents(typed: string, formatters: DiscountsFormatters): number | null {
+  const amount = formatters.parseDecimal(typed);
+  return amount === null ? null : Math.round(amount * 100);
+}
+
+/** A whole-number cap, or null when blank ("no cap"). */
+function toCount(typed: string, formatters: DiscountsFormatters): number | null {
+  const parsed = formatters.parseDecimal(typed);
+  return parsed === null ? null : Math.trunc(parsed);
+}
+
+/**
+ * A percentage as BASIS POINTS.
+ *
+ * The form takes 0–100 with two decimals because that is how an operator thinks
+ * about a promotion; the column stores basis points because that is how the
+ * 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 {
+  const percent = formatters.parseDecimal(typed);
+  return percent === null ? null : Math.round(percent * 100);
+}
+
+/** Blank → null, so an unused branch's leftover text never reaches a column. */
+function toNullable(value: string): string | null {
+  const trimmed = value.trim();
+  return trimmed === "" ? null : trimmed;
+}
+
+/** The wire body both writes send — a discount is always saved WHOLE. */
+export function toWriteBody(
+  input: DiscountFormPayload,
+  formatters: DiscountsFormatters,
+): Record<string, unknown> {
+  const isCombo = input.scope === "COMBO";
+  return {
+    name: input.name.trim(),
+    type: input.type,
+    // 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,
+    startsAt: toNullable(input.startsAt),
+    endsAt: toNullable(input.endsAt),
+    minSubtotalCents: toCents(input.minSubtotal, formatters),
+    usageLimit: toCount(input.usageLimit, formatters),
+    perBuyerLimit: toCount(input.perBuyerLimit, formatters),
+    stackable: input.stackable,
+    active: input.active,
+    // Narrowed to the scope on the way OUT as well as on the way in: leaving a
+    // stale id list on a rule whose scope changed is how a promotion goes on
+    // covering something its screen no longer shows.
+    categoryIds: input.scope === "CATEGORY" ? input.categoryIds : [],
+    menuItemIds: input.scope === "ITEM" ? input.menuItemIds : [],
+  };
+}
+
+/** The bound wire client the screens use. Nothing else performs I/O. */
+export interface DiscountsApiClient {
+  list(search: string): Promise<DiscountsPage>;
+  targets(): Promise<readonly WireTargetGroup[]>;
+  create(input: DiscountFormPayload): Promise<DiscountsResult<DiscountWireRecord>>;
+  update(id: string, input: DiscountFormPayload): Promise<DiscountsResult<{ id: string }>>;
+  remove(id: string): Promise<DiscountsResult<{ id: string }>>;
+}
+
+export function createDiscountsApiClient(
+  apiBase: string,
+  transport: DiscountsTransport,
+  formatters: DiscountsFormatters,
+): DiscountsApiClient {
+  const collection = `${apiBase}/discounts`;
+  const item = (id: string): string => `${collection}/${encodeURIComponent(id)}`;
+  return {
+    list: (search) => transport.get<DiscountsPage>(search ? `${collection}?${search}` : collection),
+    targets: () =>
+      transport
+        .get<{ data: WireTargetGroup[] }>(`${collection}/targets`)
+        .then((payload) => payload.data),
+    create: (input) =>
+      transport.send<DiscountWireRecord>(collection, "POST", toWriteBody(input, formatters)),
+    update: (id, input) =>
+      transport.send<{ id: string }>(item(id), "PATCH", toWriteBody(input, formatters)),
+    remove: (id) => transport.send<{ id: string }>(item(id), "DELETE"),
+  };
+}

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>
+  );
+}