@12-apps/discounts 1.2.0 → 1.4.0

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

@@ -0,0 +1,245 @@
+"use client";
+
+import type { JSX } from "react";
+
+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";
+
+import type { DiscountsWebCopy } from "./copy";
+
+/**
+ * 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
+ * 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.
+ */
+
+/**
+ * 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[],
+  labels: Readonly<Record<TKey, string>>,
+): { value: string; label: string }[] {
+  return values.map((value) => ({ value, label: labels[value] }));
+}
+
+/**
+ * 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,
+}: {
+  copy: DiscountsWebCopy;
+  currencyField: CurrencyFieldComponent;
+}): JSX.Element {
+  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} />
+    );
+  }
+  return (
+    <Fields.TextField
+      name="percentOff"
+      label={copy.form.percentOff}
+      placeholder={copy.form.percentPlaceholder}
+    />
+  );
+}
+
+/**
+ * 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();
+  if (values.trigger !== "CODE") return null;
+  return (
+    <Fields.TextField
+      name="code"
+      label={copy.form.code}
+      placeholder={copy.form.codePlaceholder}
+    />
+  );
+}
+
+/** Type + value + trigger + code, the four that decide WHAT and HOW. */
+export function RuleFields({
+  copy,
+  currencyField,
+}: {
+  copy: DiscountsWebCopy;
+  currencyField: CurrencyFieldComponent;
+}): 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}
+        options={optionsFor(DISCOUNT_TRIGGERS, copy.labels.trigger)}
+      />
+      <CodeField copy={copy} />
+    </Box>
+  );
+}
+
+/** The scope toggle, which decides which target picker is shown below it. */
+export function ScopeField({ copy }: { copy: DiscountsWebCopy }): JSX.Element {
+  return (
+    <Fields.ToggleField
+      name="scope"
+      label={copy.form.scope}
+      options={optionsFor(DISCOUNT_SCOPES, copy.labels.scope)}
+    />
+  );
+}
+
+/**
+ * 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 (
+    <Box sx={{ display: "grid", gap: 2, gridTemplateColumns: { xs: "1fr", sm: "1fr 1fr" } }}>
+      <Fields.TextField name="startsAt" label={copy.form.startsAt} type="date" />
+      <Fields.TextField name="endsAt" label={copy.form.endsAt} type="date" />
+    </Box>
+  );
+}
+
+/** The minimum basket and the two redemption caps. */
+export function LimitFields({
+  copy,
+  currencyField,
+}: {
+  copy: DiscountsWebCopy;
+  currencyField: CurrencyFieldComponent;
+}): JSX.Element {
+  const Currency = currencyField;
+  return (
+    <Box sx={{ display: "grid", gap: 2, gridTemplateColumns: { xs: "1fr", sm: "1fr 1fr 1fr" } }}>
+      <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>
+  );
+}
+
+/** The two booleans, owned by the parent so submit can send them. */
+export function DiscountSwitches({
+  copy,
+  active,
+  stackable,
+  onActive,
+  onStackable,
+}: {
+  copy: DiscountsWebCopy;
+  active: boolean;
+  stackable: boolean;
+  onActive: (next: boolean) => void;
+  onStackable: (next: boolean) => void;
+}): JSX.Element {
+  return (
+    <Stack spacing={1}>
+      <Switch
+        checked={active}
+        onChange={(event) => onActive(event.target.checked)}
+        label={copy.form.active}
+        description={copy.form.activeHint}
+        dataTestId="discount-active"
+      />
+      <Switch
+        checked={stackable}
+        onChange={(event) => onStackable(event.target.checked)}
+        label={copy.form.stackable}
+        description={copy.form.stackableHint}
+        dataTestId="discount-stackable"
+      />
+    </Stack>
+  );
+}

package/src/react/discount-form.tsx

@@ -0,0 +1,393 @@
+"use client";
+
+import { useState, type JSX } from "react";
+
+import { minLength, required } from "@12-apps/forms-core";
+import { Alert } from "@12-apps/ui/data-display/Alert";
+import {
+  Fields,
+  FormContainer,
+  FormErrorSnackbar,
+  SubmitButton,
+} 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 { fill, type DiscountsWebCopy } from "./copy";
+import {
+  DiscountSwitches,
+  LimitFields,
+  RuleFields,
+  ScopeField,
+  WindowFields,
+  type CurrencyFieldComponent,
+} from "./discount-form-fields";
+import { comboUnits } from "./combo-slot-builder";
+import { DiscountTargetPicker } from "./discount-target-picker";
+import type { DiscountsFormatters } from "./format";
+
+/**
+ * The create/edit form — shared by the header's create dialog and the row
+ * menu's edit dialog, so the fields and the submit live in one place.
+ * `editing === null` creates; otherwise it re-states the rule whole.
+ *
+ * Two kinds of value are deliberately NOT `total-form` values, for one reason:
+ * `total-form` holds STRINGS. The two switches (booleans) and the target id
+ * lists (arrays) sit in local state beside the container and are merged in at
+ * submit.
+ *
+ * Every rule checked here is ALSO checked on the server. This half exists for
+ * the operator's sake — instant, field-attached feedback — never as the
+ * authority: the surface re-validates, and a server refusal comes back through
+ * `setFieldErrors` and paints the same inputs red.
+ */
+
+interface DiscountFormValues extends Record<string, string> {
+  name: string;
+  type: string;
+  percentOff: string;
+  amountOff: string;
+  bundlePrice: string;
+  freeUnits: string;
+  maxComboApplications: string;
+  scope: string;
+  trigger: string;
+  code: string;
+  startsAt: string;
+  endsAt: string;
+  minSubtotal: string;
+  usageLimit: string;
+  perBuyerLimit: string;
+}
+
+/** `YYYY-MM-DD` for a native date input, from the wire's ISO instant. */
+function toDateInput(iso: string | null): string {
+  return iso === null ? "" : iso.slice(0, 10);
+}
+
+/** A new rule's defaults: the most common promotion an operator creates. */
+const BLANK: DiscountFormValues = {
+  name: "",
+  type: "PERCENTAGE",
+  percentOff: "",
+  amountOff: "",
+  bundlePrice: "",
+  freeUnits: "",
+  maxComboApplications: "",
+  scope: "ORDER",
+  trigger: "AUTOMATIC",
+  code: "",
+  startsAt: "",
+  endsAt: "",
+  minSubtotal: "",
+  usageLimit: "",
+  perBuyerLimit: "",
+};
+
+function initialValues(
+  editing: DiscountWireRecord | null,
+  formatters: DiscountsFormatters,
+): DiscountFormValues {
+  if (editing === null) return { ...BLANK };
+  const cents = (value: number | null): string =>
+    value === null ? "" : formatters.toInput(Number((value / 100).toFixed(2)));
+  return {
+    name: editing.name,
+    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 ?? "",
+    startsAt: toDateInput(editing.startsAt),
+    endsAt: toDateInput(editing.endsAt),
+    minSubtotal: cents(editing.minSubtotalCents),
+    usageLimit: editing.usageLimit === null ? "" : String(editing.usageLimit),
+    perBuyerLimit: editing.perBuyerLimit === null ? "" : String(editing.perBuyerLimit),
+  };
+}
+
+/** 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 === "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);
+  }
+  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: FormTargets,
+  formatters: DiscountsFormatters,
+  copy: DiscountsWebCopy,
+): Record<string, string> {
+  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;
+  }
+  if (values.scope === "CATEGORY" && targets.categoryIds.length === 0) {
+    errors.scope = copy.form.categoryTargetRequired;
+  }
+  if (values.scope === "ITEM" && targets.menuItemIds.length === 0) {
+    errors.scope = copy.form.itemTargetRequired;
+  }
+  // The window is half-open [start, end): equal dates are an EMPTY window, so
+  // the rule is "after", not "not before".
+  if (values.startsAt !== "" && values.endsAt !== "" && values.endsAt <= values.startsAt) {
+    errors.endsAt = copy.form.endsBeforeStarts;
+  }
+  return errors;
+}
+
+/** The values `total-form` cannot hold, kept beside it and merged at submit. */
+function useNonStringState(editing: DiscountWireRecord | null) {
+  const [active, setActive] = useState<boolean>(editing?.active ?? true);
+  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,
+  };
+}
+
+type NonStringState = ReturnType<typeof useNonStringState>;
+type SubmitHelpers = { setFieldErrors: (errors: Record<string, string | undefined>) => void };
+
+export interface DiscountFormProps {
+  api: DiscountsApiClient;
+  copy: DiscountsWebCopy;
+  formatters: DiscountsFormatters;
+  currencyField: CurrencyFieldComponent;
+  groups: readonly WireTargetGroup[];
+  editing: DiscountWireRecord | null;
+  onSaved: () => void;
+  /** Where a refused or failed write is reported, beyond the operator's screen. */
+  onError: (error: unknown, context: string) => void;
+}
+
+/**
+ * Build the submit handler.
+ *
+ * A factory rather than a closure inside the component, so the component stays
+ * inside the size gate and the validate → send → attribute-the-failure sequence
+ * reads as one block.
+ */
+function makeSubmit(
+  props: DiscountFormProps,
+  extra: NonStringState,
+  setError: (message: string | null) => void,
+): (values: DiscountFormValues, helpers: SubmitHelpers) => Promise<void> {
+  const { api, copy, formatters, editing, onSaved, onError } = props;
+  return async function handleSubmit(values, { setFieldErrors }): Promise<void> {
+    setError(null);
+    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);
+      setError(copy.form.reviewFields);
+      return;
+    }
+    const payload: DiscountFormPayload = {
+      ...values,
+      ...targets,
+      stackable: extra.stackable,
+      active: extra.active,
+    };
+    const result = editing
+      ? await api.update(editing.id, payload)
+      : await api.create(payload);
+    if (result.ok) {
+      onSaved();
+      return;
+    }
+    setError(result.error);
+    // The server attributes what it can — a duplicate code, a rate out of range
+    // — so highlight those inputs instead of only showing the banner.
+    if (result.fieldErrors) setFieldErrors(result.fieldErrors);
+    onError(result, editing ? "discounts.update" : "discounts.create");
+  };
+}
+
+export function DiscountForm(props: DiscountFormProps): JSX.Element {
+  const { copy, formatters, currencyField, groups, editing } = props;
+  const [error, setError] = useState<string | null>(null);
+  const extra = useNonStringState(editing);
+  const handleSubmit = makeSubmit(props, extra, setError);
+
+  return (
+    <FormContainer<DiscountFormValues>
+      initialValues={initialValues(editing, formatters)}
+      schema={{ name: [required(copy.form.nameRequired), minLength(2)] }}
+      onSubmit={handleSubmit}
+      dataTestId="discount-form"
+    >
+      <Stack spacing={2}>
+        <Fields.TextField name="name" label={copy.form.name} />
+        <RuleFields copy={copy} currencyField={currencyField} />
+        <ScopeField copy={copy} />
+        <DiscountTargetPicker
+          groups={groups}
+          copy={copy}
+          selection={{
+            categoryIds: extra.categoryIds,
+            menuItemIds: extra.menuItemIds,
+            comboRequirements: extra.comboRequirements,
+            onCategoryIdsChange: extra.setCategoryIds,
+            onMenuItemIdsChange: extra.setMenuItemIds,
+            onComboRequirementsChange: extra.setComboRequirements,
+          }}
+        />
+        <WindowFields copy={copy} />
+        <LimitFields copy={copy} currencyField={currencyField} />
+        <DiscountSwitches
+          copy={copy}
+          active={extra.active}
+          stackable={extra.stackable}
+          onActive={extra.setActive}
+          onStackable={extra.setStackable}
+        />
+        {error && (
+          <Alert
+            variant="danger"
+            title={copy.form.saveFailed}
+            description={error}
+            data-testid="discount-form-error"
+          />
+        )}
+        <SubmitButton dataTestId="discount-form-submit">
+          {editing ? copy.form.submitEdit : copy.form.submitCreate}
+        </SubmitButton>
+      </Stack>
+      <FormErrorSnackbar />
+    </FormContainer>
+  );
+}