@12-apps/discounts 1.4.0 → 1.6.0

package/src/react/discount-form-validate.ts

@@ -0,0 +1,172 @@
+import type { ComboRequirement } from "../engine/types";
+
+import { comboUnits } from "./combo-slot-builder";
+import { fill, type DiscountsWebCopy } from "./copy";
+import type { DiscountFormValues } from "./discount-form-values";
+import { isComboKind, typeAndScopeFor } from "./form-kind";
+import type { DiscountsFormatters } from "./format";
+
+/**
+ * Everything the create/edit form refuses locally, split from the form itself
+ * for the 400-line file gate — comments count toward it, and the container plus
+ * these would not fit.
+ *
+ * Every rule here is ALSO the server's (`../server/validate-combo.ts` and the
+ * route's own schema). This half exists to attach the refusal to the input the
+ * operator is looking at, never to be the authority: the surface re-validates,
+ * and a server refusal comes back through `setFieldErrors` and paints the same
+ * inputs red.
+ */
+
+/** 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 KIND actually mounted.
+ *
+ * `type` is derived rather than read: a combo's reward is a percentage or an
+ * amount, and which one it is lives in `comboReward` — so the check runs off
+ * the same mapping the submit does, and the two cannot disagree about which
+ * input holds the number.
+ */
+function checkValue(
+  values: DiscountFormValues,
+  slots: readonly ComboRequirement[],
+  formatters: DiscountsFormatters,
+  copy: DiscountsWebCopy,
+): Record<string, string> {
+  const { type } = typeAndScopeFor(values);
+  if (type === "FIXED_AMOUNT") {
+    return checkMoney(values.amountOff, "amountOff", copy.form.invalidAmount, formatters);
+  }
+  if (type === "BUNDLE_PRICE") {
+    return checkMoney(values.bundlePrice, "bundlePrice", copy.form.invalidBundlePrice, formatters);
+  }
+  if (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 (!isComboKind(values.kind)) return {};
+  // "Leve 3, pague 2" is one group of products, so it is refused in those words
+  // rather than in the multi-group builder's — same stored shape, different
+  // sentence, because the operator is looking at a different control.
+  const free = values.kind === "FREE_UNITS";
+  const empty = free ? copy.form.freeUnitsTargetRequired : copy.form.comboSlotsRequired;
+  // The refusal hangs on `kind` rather than on `scope`: a combo kind does not
+  // mount a scope toggle, so an error attributed there would paint nothing.
+  if (slots.length === 0) return { kind: empty };
+  const errors: Record<string, string> = {};
+  if (slots.some((slot) => !Number.isInteger(slot.quantity) || slot.quantity <= 0)) {
+    errors.kind = copy.form.invalidComboQuantity;
+  } else if (
+    slots.some((slot) => slot.categoryIds.length === 0 && slot.menuItemIds.length === 0)
+  ) {
+    errors.kind = free ? copy.form.freeUnitsTargetRequired : 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. */
+export interface FormTargets {
+  categoryIds: string[];
+  menuItemIds: string[];
+  comboRequirements: ComboRequirement[];
+}
+
+/** The cross-field rules a per-input schema cannot express. */
+export 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;
+  }
+  const { scope } = typeAndScopeFor(values);
+  if (scope === "CATEGORY" && targets.categoryIds.length === 0) {
+    errors.scope = copy.form.categoryTargetRequired;
+  }
+  if (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;
+}
+

package/src/react/discount-form-values.ts

@@ -0,0 +1,90 @@
+import type { DiscountWireRecord } from "./api";
+import { comboRewardOf, kindOf } from "./form-kind";
+import type { DiscountsFormatters } from "./format";
+
+/**
+ * What the create/edit form HOLDS, and what an existing rule opens as.
+ *
+ * Its own module because the form and its validators both need the shape, and
+ * a type imported back out of the component file would make the two a cycle.
+ *
+ * Everything here is a STRING: `total-form` holds strings, because every value
+ * in a text input is one. The two switches (booleans) and the target id lists
+ * (arrays) are therefore not form values at all — they sit in local state
+ * beside the container and are merged in at submit.
+ */
+
+export interface DiscountFormValues extends Record<string, string> {
+  name: string;
+  /** What kind of promotion this is. Decides `type` and `scope` — see `./form-kind`. */
+  kind: string;
+  /** Which of the two rewards a COMBO gives. Ignored by every other kind. */
+  comboReward: 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: "",
+  kind: "PERCENTAGE",
+  comboReward: "PERCENTAGE",
+  percentOff: "",
+  amountOff: "",
+  bundlePrice: "",
+  freeUnits: "",
+  maxComboApplications: "",
+  scope: "ORDER",
+  trigger: "AUTOMATIC",
+  code: "",
+  startsAt: "",
+  endsAt: "",
+  minSubtotal: "",
+  usageLimit: "",
+  perBuyerLimit: "",
+};
+
+export 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,
+    kind: kindOf(editing),
+    comboReward: comboRewardOf(editing),
+    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),
+  };
+}
+

package/src/react/discount-form.tsx

@@ -15,17 +15,22 @@ 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 type { DiscountsWebCopy } from "./copy";
 import {
+  ComboCapField,
   DiscountSwitches,
+  KindField,
   LimitFields,
-  RuleFields,
+  RewardFields,
   ScopeField,
+  TriggerFields,
   WindowFields,
   type CurrencyFieldComponent,
 } from "./discount-form-fields";
-import { comboUnits } from "./combo-slot-builder";
 import { DiscountTargetPicker } from "./discount-target-picker";
+import { validate, type FormTargets } from "./discount-form-validate";
+import { initialValues, type DiscountFormValues } from "./discount-form-values";
+import { kindOptions, typeAndScopeFor } from "./form-kind";
 import type { DiscountsFormatters } from "./format";
 
 /**
@@ -44,211 +49,6 @@ import type { DiscountsFormatters } from "./format";
  * `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);
@@ -318,6 +118,10 @@ function makeSubmit(
     }
     const payload: DiscountFormPayload = {
       ...values,
+      // The one place the form's question becomes the API's two columns. Every
+      // other consumer — the write path, the evaluator, the CHECK constraints —
+      // still sees the `type`/`scope` pair it always did.
+      ...typeAndScopeFor(values),
       ...targets,
       stackable: extra.stackable,
       active: extra.active,
@@ -352,7 +156,8 @@ export function DiscountForm(props: DiscountFormProps): JSX.Element {
     >
       <Stack spacing={2}>
         <Fields.TextField name="name" label={copy.form.name} />
-        <RuleFields copy={copy} currencyField={currencyField} />
+        <KindField copy={copy} kinds={kindOptions(editing)} />
+        <RewardFields copy={copy} currencyField={currencyField} />
         <ScopeField copy={copy} />
         <DiscountTargetPicker
           groups={groups}
@@ -366,6 +171,8 @@ export function DiscountForm(props: DiscountFormProps): JSX.Element {
             onComboRequirementsChange: extra.setComboRequirements,
           }}
         />
+        <ComboCapField copy={copy} />
+        <TriggerFields copy={copy} />
         <WindowFields copy={copy} />
         <LimitFields copy={copy} currencyField={currencyField} />
         <DiscountSwitches

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

@@ -9,16 +9,18 @@ import type { ComboRequirement } from "../engine/types";
 import type { WireTargetGroup } from "./api";
 import { ComboSlotBuilder } from "./combo-slot-builder";
 import { fill, type DiscountsWebCopy } from "./copy";
+import { FreeUnitsBuilder } from "./free-units-builder";
 import { TargetPickerField } from "./target-picker-field";
 
 /**
  * What a scoped discount points at, picked from the host's own collections.
  *
- * This file is the ROUTER: it reads the scope and decides which shape the
+ * This file is the ROUTER: it reads the KIND 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.
+ * `combo-slot-builder`, the one-group "leve 3, pague 2" in
+ * `free-units-builder` — because the builders need the picker 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
@@ -61,17 +63,17 @@ function scopeFor(targetType: string): string {
 }
 
 /**
- * The scope-driven target block.
+ * The kind-driven target block.
  *
- * 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.
+ * Reads the LIVE `kind` and `scope` from the form context, so flipping either
+ * toggle swaps the control 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.
+ * The two combo kinds are a different SHAPE, not another picker (FUT-268): a
+ * combo is a list of quantified groups, so it gets a builder and every
+ * collection at once, while CATEGORY and ITEM each get exactly one collection's
+ * picker. ORDER renders nothing — an order-wide discount covers everything, so
+ * a target list there is not empty, it is meaningless.
  */
 export function DiscountTargetPicker({
   groups,
@@ -82,10 +84,25 @@ export function DiscountTargetPicker({
   copy: DiscountsWebCopy;
   selection: DiscountTargetSelection;
 }): JSX.Element | null {
-  const { values } = useFormContext();
+  const { values, errors, setFieldValue } = useFormContext();
+  const kind = values.kind ?? "PERCENTAGE";
   const scope = values.scope ?? "ORDER";
 
-  if (scope === "COMBO") {
+  if (kind === "FREE_UNITS") {
+    return (
+      <FreeUnitsBuilder
+        slots={selection.comboRequirements}
+        groups={groups}
+        copy={copy}
+        freeUnits={values.freeUnits ?? ""}
+        error={errors.freeUnits}
+        onChange={selection.onComboRequirementsChange}
+        onFreeUnitsChange={(next) => setFieldValue("freeUnits", next)}
+      />
+    );
+  }
+
+  if (kind === "COMBO" || kind === "BUNDLE_PRICE") {
     return (
       <ComboSlotBuilder
         slots={selection.comboRequirements}
@@ -108,6 +125,7 @@ export function DiscountTargetPicker({
       requiredMessage={copy.targets.required}
       ids={ids}
       onChange={onChange}
+      copy={copy.categorySelect}
       dataTestId={`discount-${group.slug}-targets`}
     />
   );