@12-apps/discounts 1.7.0 → 1.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/discounts",
-  "version": "1.7.0",
+  "version": "1.9.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": {
@@ -13,6 +13,10 @@
     "./manifest": "./src/manifest/index.ts",
     "./manifest/server": "./src/manifest/server.ts",
     "./manifest/web": "./src/manifest/web.ts",
+    "./en-US": "./src/engine/en-US.ts",
+    "./server/en-US": "./src/server/en-US.ts",
+    "./react/en-US": "./src/react/en-US.ts",
+    "./locales": "./src/locales.ts",
     "./package.json": "./package.json"
   },
   "scripts": {
@@ -28,10 +32,10 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@12-apps/app-shell": "^5.2.0",
+    "@12-apps/app-shell": "^5.3.0",
     "@12-apps/forms-core": "^1.20.0",
     "@12-apps/shared-helpers": "^2.0.2",
-    "@12-apps/ui": "^6.7.0",
+    "@12-apps/ui": "^6.9.0",
     "@mui/icons-material": "^6.5.0",
     "zod": "^4.3.5"
   },
@@ -57,6 +61,7 @@
   },
   "devDependencies": {
     "@12-apps/eslint-config": "^1.21.1",
+    "@12-apps/i18n": "^1.0.0",
     "@12-apps/typescript-config": "^1.20.1",
     "@12-apps/wiring": "^1.10.0",
     "@electric-sql/pglite": "^0.2.17",

package/src/engine/en-US.ts

@@ -0,0 +1,37 @@
+import { MIN_SUBTOTAL_TOKEN, type DiscountRejectionCopy } from "./rejection-copy";
+
+/**
+ * The en-US pack — a NAMED export a host passes by hand
+ * (`rejectionCopy: EN_US_DISCOUNT_REJECTION_COPY`), never a default.
+ *
+ * Deliberately COARSER than the reason set, and the translation keeps it that
+ * way: switched off, not started yet and expired all read the same, because the
+ * difference only leaks how the merchant schedules promotions and the buyer
+ * could not act on it either way. Four distinct English sentences here would be
+ * a disclosure the Portuguese does not make.
+ *
+ * `COMBO_NOT_MATCHED` is the one place that coarsening stops, and for the same
+ * test read the other way: a buyer one soda short of the bundle can finish it,
+ * so telling them WHICH kind of failure this was is the difference between a
+ * dead end and a sale. It does not name the missing item — the evaluator does
+ * not report one, because "which item is missing" has no single answer when a
+ * slot accepts a whole category.
+ *
+ * `MIN_SUBTOTAL_TOKEN` is substituted with the formatted amount, so the
+ * sentence must carry it rather than a number.
+ */
+export const EN_US_DISCOUNT_REJECTION_COPY: DiscountRejectionCopy = {
+  UNKNOWN_CODE: "That coupon is invalid or expired.",
+  INACTIVE: "That coupon is invalid or expired.",
+  NOT_STARTED: "That coupon is invalid or expired.",
+  EXPIRED: "That coupon is invalid or expired.",
+  MIN_SUBTOTAL_NOT_MET: `This coupon needs a minimum order of ${MIN_SUBTOTAL_TOKEN}.`,
+  USAGE_LIMIT_REACHED: "This coupon has reached its usage limit.",
+  BUYER_LIMIT_REACHED: "You have already used this coupon.",
+  NO_ELIGIBLE_ITEMS: "This coupon does not apply to the items in your cart.",
+  COMBO_NOT_MATCHED: "Your cart does not have every item in this bundle yet.",
+  ZERO_VALUE: "This coupon does not apply to the items in your cart.",
+  NOT_STACKABLE: "Another promotion already applied is better than this coupon.",
+  EMPTY_CART: "Your cart is empty.",
+  minSubtotalUnknown: "This coupon needs a minimum order value.",
+};

package/src/locales.ts

@@ -0,0 +1,41 @@
+import { EN_US_DISCOUNT_REJECTION_COPY } from "./engine/en-US";
+import { PT_BR_DISCOUNT_REJECTION_COPY } from "./engine/pt-BR";
+import type { DiscountRejectionCopy } from "./engine/rejection-copy";
+import { EN_US_DISCOUNTS_WEB_COPY } from "./react/en-US";
+import type { DiscountsWebCopy } from "./react/copy";
+import { PT_BR_DISCOUNTS_WEB_COPY } from "./react/pt-BR";
+import type { DiscountsServerCopy } from "./server/copy";
+import { EN_US_DISCOUNTS_SERVER_COPY } from "./server/en-US";
+import { PT_BR_DISCOUNTS_SERVER_COPY } from "./server/pt-BR";
+
+/**
+ * All three surfaces, in both languages, keyed by tag — what a host hands to
+ * `@12-apps/i18n` when the reader's language is a property of the request
+ * rather than of the deployment.
+ *
+ * Three packs rather than one, because the three have different AUDIENCES and
+ * different lifetimes: the rejection copy is read by a shopper at a cart, the
+ * server copy by an operator filling a form, and the web copy by that same
+ * operator on the screen around it. A host may well resolve them from different
+ * places.
+ *
+ * `LocalePack` is mirrored here rather than imported so the package stays
+ * liftable into a repo that has never heard of `@12-apps/i18n`. The named
+ * single-language packs stay exported and unchanged.
+ */
+type LocalePack<T> = { readonly "pt-BR": T; readonly "en-US": T };
+
+export const DISCOUNT_REJECTION_COPY = {
+  "pt-BR": PT_BR_DISCOUNT_REJECTION_COPY,
+  "en-US": EN_US_DISCOUNT_REJECTION_COPY,
+} as const satisfies LocalePack<DiscountRejectionCopy>;
+
+export const DISCOUNTS_SERVER_COPY = {
+  "pt-BR": PT_BR_DISCOUNTS_SERVER_COPY,
+  "en-US": EN_US_DISCOUNTS_SERVER_COPY,
+} as const satisfies LocalePack<DiscountsServerCopy>;
+
+export const DISCOUNTS_WEB_COPY = {
+  "pt-BR": PT_BR_DISCOUNTS_WEB_COPY,
+  "en-US": EN_US_DISCOUNTS_WEB_COPY,
+} as const satisfies LocalePack<DiscountsWebCopy>;

package/src/react/combo-slot-builder.tsx

@@ -137,6 +137,7 @@ function ComboSlotRow({
             ids={idsFor(slot, group.targetType)}
             onChange={(ids) => onChange(withIds(slot, group.targetType, ids))}
             copy={copy.categorySelect}
+          autocompleteCopy={copy.autocomplete}
             dataTestId={`combo-slot-${index}-${group.slug}`}
           />
         ))}

package/src/react/copy.ts

@@ -1,4 +1,4 @@
-import type { CategorySelectCopy, ConfirmActionCopy } from "@12-apps/ui/copy";
+import type { AutocompleteCopy, CategorySelectCopy, ConfirmActionCopy } from "@12-apps/ui/copy";
 import type { DataViewsCopy } from "@12-apps/ui/data-display/DataViews";
 import type {
   DiscountScope,
@@ -289,6 +289,13 @@ export interface DiscountsWebCopy {
    */
   readonly confirmAction: ConfirmActionCopy;
   readonly categorySelect: CategorySelectCopy;
+  /**
+   * The flat half of the target picker. A group that NESTS renders a
+   * `CategorySelect`; one that does not renders an `Autocomplete`, and that
+   * component stopped shipping defaults for its loading row, its empty row and
+   * its placeholder in the same wave.
+   */
+  readonly autocomplete: AutocompleteCopy;
   readonly dataViews: DataViewsCopy;
 }
 

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

@@ -126,6 +126,7 @@ export function DiscountTargetPicker({
       ids={ids}
       onChange={onChange}
       copy={copy.categorySelect}
+          autocompleteCopy={copy.autocomplete}
       dataTestId={`discount-${group.slug}-targets`}
     />
   );

package/src/react/en-US.ts

@@ -0,0 +1,199 @@
+import {
+  EN_US_AUTOCOMPLETE_COPY,
+  EN_US_CATEGORY_SELECT_COPY,
+  EN_US_CONFIRM_ACTION_COPY,
+  EN_US_DATA_VIEWS_COPY,
+} from "@12-apps/ui/en-US";
+
+import type { DiscountsWebCopy } from "./copy";
+
+/**
+ * The en-US pack for the discounts admin screens.
+ *
+ * A NAMED PACK a host passes by hand, never a default. The four composed packs
+ * come from `@12-apps/ui`'s own English side rather than being restated here,
+ * exactly as the pt-BR pack composes the Portuguese ones.
+ *
+ * The `{token}` substitutions are the package's own and are NOT translated —
+ * `fill()` replaces them, so a renamed token is a sentence that renders its own
+ * placeholder. Their ORDER is free, which is what naming them buys.
+ *
+ * The KEYS of `labels.*` are the engine's wire values (`PERCENTAGE`, `ORDER`,
+ * `RUNNING`, …). Only the words beside them are translated.
+ */
+export const EN_US_DISCOUNTS_WEB_COPY: DiscountsWebCopy = {
+  screen: {
+    title: "Discounts",
+    aboutTitle: "About discounts",
+    aboutBody:
+      "Create automatic promotions or coupon codes — for the whole order, one category, named products, or a bundle.",
+    create: "New discount",
+    empty: "No discounts yet.",
+    // A FILENAME, not a sentence: it is what the export lands on disk as.
+    exportFileName: "discounts",
+    loading: "Loading discounts…",
+    loadFailed: "Could not load the discounts",
+    retry: "Try again",
+    columns: {
+      name: "Name",
+      value: "Discount",
+      type: "Type",
+      scope: "Applies to",
+      trigger: "Trigger",
+      window: "Validity",
+      code: "Code",
+      usageCount: "Uses",
+      active: "Active",
+    },
+    yes: "Yes",
+    no: "No",
+  },
+  labels: {
+    kind: {
+      PERCENTAGE: "Percentage",
+      FIXED_AMOUNT: "Fixed amount",
+      COMBO: "Bundle",
+      FREE_UNITS: "Free items",
+      BUNDLE_PRICE: "Bundle price",
+    },
+    type: {
+      PERCENTAGE: "Percentage",
+      FIXED_AMOUNT: "Fixed amount",
+      BUNDLE_PRICE: "Bundle price",
+      FREE_UNITS: "Free items",
+    },
+    scope: {
+      ORDER: "Order",
+      CATEGORY: "Category",
+      ITEM: "Item",
+      COMBO: "Bundle",
+    },
+    trigger: {
+      AUTOMATIC: "Automatic",
+      CODE: "Code",
+    },
+    window: {
+      RUNNING: "Running",
+      SCHEDULED: "Scheduled",
+      ENDED: "Ended",
+    },
+  },
+  // All four shapes get their own phrasing, for the reason the window helper
+  // records: a dash on one side would leave the operator guessing whether the
+  // promotion has no start or no end, and those mean very different things
+  // when it is not running yet.
+  window: {
+    always: "No end date",
+    from: "From {date}",
+    until: "Until {date}",
+    between: "{from} to {to}",
+  },
+  form: {
+    createTitle: "New discount",
+    editTitle: "Edit discount",
+    submitCreate: "Create discount",
+    submitEdit: "Save changes",
+    name: "Promotion name",
+    type: "Type",
+    kind: "Promotion type",
+    comboReward: "Bundle discount",
+    comboRewardHint: "The bundle sells for the price of its items minus this discount.",
+    percentOff: "Discount (%)",
+    percentPlaceholder: "10",
+    amountOff: "Discount amount",
+    bundlePrice: "Bundle price",
+    freeUnits: "Free items",
+    freeUnitsHint:
+      'How many units of the bundle are free. In a group of 3, making 1 free is the classic "buy 3, pay for 2".',
+    trigger: "Trigger",
+    code: "Coupon code",
+    // A sample CODE, not a word: it shows the shape of one a shopper types.
+    codePlaceholder: "WELCOME10",
+    scope: "Applies to",
+    startsAt: "Starts",
+    endsAt: "Ends",
+    minSubtotal: "Minimum order",
+    usageLimit: "Usage limit",
+    perBuyerLimit: "Limit per customer",
+    maxComboApplications: "Bundles per order",
+    maxComboApplicationsHint: "Leave blank to apply as many times as the cart allows.",
+    maxFreeUnitsApplications: "Times per order",
+    active: "Active",
+    activeHint: "Switch off to pause the promotion without deleting it.",
+    stackable: "Stackable",
+    stackableHint:
+      "When off, this promotion is exclusive: if it wins, no other one is applied.",
+    reviewFields: "Check the highlighted fields.",
+    saveFailed: "Could not save the discount",
+    nameRequired: "Give the promotion a name.",
+    invalidPercent: "Enter a percentage greater than 0 and at most 100.",
+    invalidAmount: "Enter a discount amount greater than zero.",
+    invalidBundlePrice: "Enter the bundle price, greater than zero.",
+    invalidFreeUnits: "Enter how many items are free, from 1 upwards.",
+    freeUnitsExceedCombo:
+      "The bundle has {units} items; make at most {max} free for it to still be a promotion.",
+    freeUnitsTargetRequired: "Pick at least one product for the promotion.",
+    codeRequired: "Enter the coupon code the customer will type.",
+    categoryTargetRequired: "Select at least one category for this discount.",
+    itemTargetRequired: "Select at least one product for this discount.",
+    comboSlotsRequired: "Build the bundle: add at least one group of items.",
+    comboSlotTargetRequired: "Choose what can go in each group of the bundle.",
+    invalidComboQuantity: "Enter how many units each group takes, from 1 upwards.",
+    invalidMaxComboApplications: "Enter how many bundles fit in one order, from 1 upwards.",
+    endsBeforeStarts: "The end date must be after the start date.",
+  },
+  combo: {
+    title: "Build the bundle",
+    hint: "Each group is one part of the bundle: how many units it takes, and what can go in it.",
+    addSlot: "Add group",
+    removeSlot: "Remove group {position}",
+    slot: "Group {position}",
+    quantity: "Quantity",
+    // `{collection}` is the HOST's word for what is being picked, so the
+    // sentence is built around it rather than naming a noun of its own.
+    pick: "{collection} in this group",
+    empty: "No groups yet. Add the first one to build the bundle.",
+    summary: "The bundle takes {units} items across {groups} groups.",
+    freeUnitsTitle: "Buy more, pay less",
+    freeUnitsHint:
+      'Choose the products, how many the customer takes and how many are free — the classic "buy 3, pay for 2".',
+    buyQuantity: "The customer takes",
+    freeUnitsPick: "{collection} in the promotion",
+    freeUnitsSummary: "Take {units}, pay for {paid}.",
+  },
+  targets: {
+    pick: "Discounted {collection}",
+    search: "Search {collection}…",
+    required: "Select at least one option.",
+  },
+  actions: {
+    menu: "Actions",
+    edit: "Edit",
+    delete: "Delete",
+    deleteTitle: "Delete this discount?",
+    deleteDescription: "It stops applying in the storefront and cannot be restored.",
+    deleteManyTitle: "Delete {count} discounts?",
+    deleteManyDescription: "They stop applying in the storefront and cannot be restored.",
+    deleteFailed: "Could not delete the discount.",
+    actionFailed: "Could not complete the action",
+    actionFailedDismiss: "Dismiss",
+  },
+  card: {
+    paused: "Paused",
+    ruleHeading: "Rule",
+    targetsHeading: "Targets",
+    wholeOrder: "the whole order",
+    oneTarget: "1 target",
+    manyTargets: "{count} targets",
+    withCode: "code {code}",
+    noTargets: "No targets",
+    usage: "Uses",
+    minSubtotal: "Minimum order",
+    perBuyerLimit: "Limit per customer",
+    unlimited: "No limit",
+  },
+  confirmAction: EN_US_CONFIRM_ACTION_COPY,
+  dataViews: EN_US_DATA_VIEWS_COPY,
+  categorySelect: EN_US_CATEGORY_SELECT_COPY,
+  autocomplete: EN_US_AUTOCOMPLETE_COPY,
+};

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

@@ -157,6 +157,7 @@ export function FreeUnitsBuilder({
           ids={slot.menuItemIds}
           onChange={(ids) => onChange([{ ...slot, menuItemIds: ids }])}
           copy={copy.categorySelect}
+          autocompleteCopy={copy.autocomplete}
           dataTestId="free-units-items"
         />
         {error !== undefined && (

package/src/react/index.ts

@@ -38,6 +38,7 @@ export {
 } from "./copy";
 
 export { PT_BR_DISCOUNTS_WEB_COPY } from "./pt-BR";
+export { EN_US_DISCOUNTS_WEB_COPY } from "./en-US";
 
 export {
   createFormatters,

package/src/react/pt-BR.ts

@@ -1,4 +1,5 @@
 import {
+  PT_BR_AUTOCOMPLETE_COPY,
   PT_BR_CATEGORY_SELECT_COPY,
   PT_BR_CONFIRM_ACTION_COPY,
   PT_BR_DATA_VIEWS_COPY,
@@ -182,4 +183,5 @@ export const PT_BR_DISCOUNTS_WEB_COPY: DiscountsWebCopy = {
   confirmAction: PT_BR_CONFIRM_ACTION_COPY,
   dataViews: PT_BR_DATA_VIEWS_COPY,
   categorySelect: PT_BR_CATEGORY_SELECT_COPY,
+  autocomplete: PT_BR_AUTOCOMPLETE_COPY,
 };

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

@@ -1,6 +1,6 @@
 "use client";
 
-import type { CategorySelectCopy } from "@12-apps/ui/copy";
+import type { AutocompleteCopy, CategorySelectCopy } from "@12-apps/ui/copy";
 import { useState, type JSX } from "react";
 
 import { Autocomplete } from "@12-apps/ui/form/Autocomplete";
@@ -35,10 +35,12 @@ function TargetField({
   ids,
   onChange,
   dataTestId,
+  autocompleteCopy,
 }: {
   label: string;
   placeholder: string;
   requiredMessage: string | undefined;
+  autocompleteCopy: AutocompleteCopy;
   options: readonly WireTarget[];
   ids: readonly string[];
   onChange: (next: string[]) => void;
@@ -57,6 +59,7 @@ function TargetField({
       <FormLabel error={missing}>{label}</FormLabel>
       <div data-testid={dataTestId}>
         <Autocomplete<WireTarget>
+          copy={autocompleteCopy}
           multiple
           value={query}
           onChange={setQuery}
@@ -102,6 +105,7 @@ export function TargetPickerField({
   onChange,
   dataTestId,
   copy,
+  autocompleteCopy,
 }: {
   group: WireTargetGroup;
   label: string;
@@ -112,6 +116,8 @@ export function TargetPickerField({
   dataTestId: string;
   /** `CategorySelect`'s own words — required since FUT-760, never defaulted. */
   copy: CategorySelectCopy;
+  /** `Autocomplete`'s, for the flat branch. Same rule, same wave. */
+  autocompleteCopy: AutocompleteCopy;
 }): JSX.Element {
   if (group.nests) {
     return (
@@ -130,6 +136,7 @@ export function TargetPickerField({
   }
   return (
     <TargetField
+      autocompleteCopy={autocompleteCopy}
       label={label}
       placeholder={placeholder}
       requiredMessage={requiredMessage}

package/src/server/en-US.ts

@@ -0,0 +1,39 @@
+import type { DiscountsServerCopy } from "./copy";
+
+/**
+ * The en-US pack — a NAMED export a host passes by hand
+ * (`copy: EN_US_DISCOUNTS_SERVER_COPY`), never a default.
+ *
+ * Every sentence names what the operator must change, because these are form
+ * errors: the route reports them with the offending FIELD alongside, so an
+ * admin form can paint that input rather than only flashing a banner. A
+ * translation that generalised them ("invalid data") would keep the field and
+ * lose the instruction.
+ */
+export const EN_US_DISCOUNTS_SERVER_COPY: DiscountsServerCopy = {
+  invalidQuery: "Invalid query parameters.",
+  notFound: "Discount not found.",
+  invalidPercent: "Enter a percentage greater than 0 and at most 100.",
+  invalidAmount: "Enter a discount amount greater than zero.",
+  codeRequired: "Enter the coupon code the customer will type.",
+  categoryTargetRequired: "Select at least one category for this discount.",
+  itemTargetRequired: "Select at least one product for this discount.",
+  // The format is the WIRE's, not a locale's: the route parses YYYY-MM-DD
+  // whichever language reports the failure, so naming any other order here
+  // would send an operator to type something the endpoint rejects.
+  invalidDate: "Invalid date. Use the format YYYY-MM-DD.",
+  endsBeforeStarts: "The end date must be after the start date.",
+  invalidMinSubtotal: "The minimum order must be greater than zero (or left blank).",
+  invalidUsageLimit: "The usage limit must be greater than zero (or left blank).",
+  invalidPerBuyerLimit: "The per-customer limit must be greater than zero (or left blank).",
+  comboScopeRequired: "Bundle price and free items only apply to bundle discounts.",
+  invalidComboSlots: "A bundle needs at least one group of items.",
+  comboTargetRequired: "Select at least one product or category for each group of the bundle.",
+  invalidComboQuantity: "Enter a quantity greater than zero for each group of the bundle.",
+  invalidBundlePrice: "Enter the bundle price, greater than zero.",
+  invalidFreeUnits: "Enter how many items are free, greater than zero.",
+  freeUnitsExceedCombo: "The bundle has to charge for at least one item.",
+  invalidMaxComboApplications:
+    "The bundles-per-cart limit must be greater than zero (or left blank).",
+  foreignTarget: "Select categories and products belonging to this store.",
+};