@12-apps/discounts 1.16.0 → 1.18.0

package/README.md

@@ -356,7 +356,7 @@ of promotion is this — and derives the pair (`src/react/form-kind.ts`):
 |---|---|---|---|
 | Porcentagem | `PERCENTAGE` | ORDER / CATEGORY / ITEM | the rate, and what it covers |
 | Valor fixo | `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 |
+| Combo | `PERCENTAGE`, `FIXED_AMOUNT` or `BUNDLE_PRICE` | `COMBO` | the groups, and which of the three rewards |
 | Itens grátis | `FREE_UNITS` | `COMBO` | the products, how many, how many free |
 
 So the offers a merchant describes map one to one onto what they fill in:
@@ -366,6 +366,7 @@ So the offers a merchant describes map one to one onto what they fill in:
 | "leve 3, pague 2" | Itens grátis | 3 hambúrgueres, 1 free |
 | "2 refrigerantes, 2 hambúrgueres e 2 batatas com 20% de desconto" | Combo | three groups of 2, and the rate |
 | the same six items at R$ 5,00 off | Combo | three groups of 2, and the amount |
+| "5 marmitas por R$ 120" | Combo | one group of 5 (a category mixes flavours), and the closed price |
 
 Two consequences of asking the kind instead of the pair:
 
@@ -373,12 +374,27 @@ Two consequences of asking the kind instead of the pair:
   made of, so the scope toggle offers the three that are genuinely a choice.
   Offering the fourth is what let an operator build "preço de combo,
   abrangência: pedido" and have the write path refuse it.
-- **`BUNDLE_PRICE` is no longer offered.** A flat price for the group reprices
-  it, and goes silently wrong the first time one of its items changes price —
-  so a combo gives a percentage or an amount OFF what its items add up to. The
-  type is still legal in the engine and in the database, and the kind toggle
-  grows a fifth option on the form of a rule that already carries it, so an
-  older promotion opens, edits and saves as what it is.
+- **A closed price is a combo's third reward, "Preço fechado" (FUT-4417).**
+  `BUNDLE_PRICE` reprices the matched group whatever its items cost — which is
+  what "5 marmitas por R$ 120" asks for, so the form offers it beside the rate
+  and the amount, says so under the price, and previews it. It is a REWARD,
+  not a kind: a rule saved as `BUNDLE_PRICE` before FUT-4417 opens as a combo
+  with "Preço fechado" chosen, and the kind toggle is always the same four.
+- **"Como fica no carrinho"** previews one combo under the chosen reward: what
+  its items sum to (each group filled with its cheapest product, then its
+  dearest) and what the buyer pays and saves, with the engine's own
+  arithmetic (`src/react/combo-preview.ts`, one application, before the
+  cart-level clamps). It needs the host's ITEM targets to carry
+  `priceRangeCents` (the product's own price and its variations') and
+  `categoryId` (only for products a buyer can add: listed, not paused); a
+  host that sends neither simply gets no preview. In a form at least
+  `PREVIEW_ASIDE_MIN_PX` wide (931 px: the narrowest form whose left column
+  still holds the four-part kind toggle) it sits in its own column beside
+  the form; narrower, it sits under the reward's field.
+- **The create and edit forms open in `UsableModal`** (`size="wide"`): a
+  stacked modal on a computer, which at 1280 gives the form the room for
+  that column, and a bottom sheet on a phone. Every opening mounts a fresh
+  form.
 
 Picking Combo swaps the single target picker for the **group builder**: each
 group is a quantity plus the rows that can fill it, and a group may name

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/discounts",
-  "version": "1.16.0",
+  "version": "1.18.0",
   "type": "module",
   "sideEffects": [
     "**/e2e/**"
@@ -41,10 +41,10 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@12-apps/app-shell": "^5.13.1",
-    "@12-apps/forms-core": "^1.21.0",
-    "@12-apps/shared-helpers": "^2.1.0",
-    "@12-apps/ui": "^6.58.0",
+    "@12-apps/app-shell": "^5.14.1",
+    "@12-apps/forms-core": "^1.23.0",
+    "@12-apps/shared-helpers": "^2.2.0",
+    "@12-apps/ui": "^6.95.1",
     "@mui/icons-material": "^6.5.0",
     "zod": "^4.3.5"
   },
@@ -80,7 +80,7 @@
     "@12-apps/eslint-config": "^1.22.0",
     "@12-apps/i18n": "^1.3.0",
     "@12-apps/typescript-config": "^1.21.0",
-    "@12-apps/wiring": "^1.16.0",
+    "@12-apps/wiring": "^1.17.0",
     "@electric-sql/pglite": "^0.2.17",
     "@emotion/react": "^11.14.0",
     "@emotion/styled": "^11.14.0",

package/src/react/api.ts

@@ -66,6 +66,10 @@ export interface WireTarget {
   id: string;
   name: string;
   parentId?: string | null;
+  /** An ITEM row's unit price range (FUT-4417), for the combo preview only. */
+  priceRangeCents?: { minCents: number; maxCents: number } | null;
+  /** An ITEM row's own category, for the same preview. */
+  categoryId?: string | null;
 }
 
 /** One registered collection and its rows. */
@@ -119,7 +123,7 @@ export interface DiscountFormPayload {
 }
 
 /** A money amount as integer cents, or null when blank. */
-function toCents(typed: string, formatters: DiscountsFormatters): number | null {
+export function toCents(typed: string, formatters: DiscountsFormatters): number | null {
   const amount = formatters.parseDecimal(typed);
   return amount === null ? null : Math.round(amount * 100);
 }
@@ -138,7 +142,7 @@ function toCount(typed: string, formatters: DiscountsFormatters): number | null
  * 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 {
+export function toBasisPoints(typed: string, formatters: DiscountsFormatters): number | null {
   const percent = formatters.parseDecimal(typed);
   return percent === null ? null : Math.round(percent * 100);
 }

package/src/react/clock-input.tsx

@@ -0,0 +1,107 @@
+"use client";
+
+import { useState, type JSX } from "react";
+
+import { FormMessage } from "@12-apps/ui/form/Form";
+import { Input } from "@12-apps/ui/form/Input";
+import { Stack } from "@12-apps/ui/mui/Stack";
+
+import { toMinutes } from "../engine/schedule";
+
+/**
+ * A 24-hour `HH:MM` box that is NOT `<input type="time">` (FUT-4143).
+ *
+ * The native control renders itself in the BROWSER's language, not the page's:
+ * on an English machine "Das 16:00" reads "04:00 PM" to a Brazilian merchant on
+ * a Portuguese screen, and no attribute overrides it. The host's own hours
+ * screens dropped it for the same reason (FUT-872), and this is the same field:
+ * text, masked, with the phone's digit keypad.
+ *
+ * The mask inserts the colon as the operator types, so four digits make
+ * `09:00` and "0900123" can never exist — the same rule as the host's
+ * `maskTime`, restated because a package cannot import a host. A half-typed
+ * `09:` is a fine intermediate state and is not shouted at; a COMPLETE time no
+ * day has (25:00, 12:60) is marked on the spot, in the pack's words.
+ */
+
+/**
+ * Keep four digits and put the colon after the second.
+ *
+ * Except while EDITING a time that already has its colon: select "09" in
+ * "09:00" and type "1" and the box holds "1:00", whose digits re-masked would
+ * read "10:0". So when the previous value had a separator and the new one
+ * still does, each side keeps its own digits — "1:00" stays, then "15:00".
+ * Any separator counts ("25/10" reads 25:10), and the result is still at most
+ * two digits a side.
+ */
+function maskTime(raw: string, previous: string): string {
+  const separator = /\D/u.exec(raw);
+  if (separator !== null && previous.includes(":")) {
+    const hours = raw.slice(0, separator.index).replace(/\D/gu, "").slice(0, 2);
+    const minutes = raw.slice(separator.index + 1).replace(/\D/gu, "").slice(0, 2);
+    return `${hours}:${minutes}`;
+  }
+  const digits = raw.replace(/\D/gu, "").slice(0, 4);
+  if (digits.length <= 2) return digits;
+  return `${digits.slice(0, 2)}:${digits.slice(2)}`;
+}
+
+/** A finished `HH:MM` that names no minute of a day. */
+function isImpossibleTime(value: string): boolean {
+  return /^\d{2}:\d{2}$/u.test(value) && toMinutes(value) === null;
+}
+
+export function ClockInput({
+  value,
+  label,
+  invalidMessage,
+  incompleteMessage,
+  submitted = false,
+  dataTestId,
+  onChange,
+}: {
+  value: string;
+  /** The accessible name — "Das" and "às" sit side by side. */
+  label: string;
+  /** Under a time that does not exist. */
+  invalidMessage: string;
+  /** Under a half-typed time once the box is left — never while typing. */
+  incompleteMessage: string;
+  /**
+   * The form refused this row's times at Criar: an unfinished clock says so
+   * now, left or not, and the row does not repeat it (FUT-4143).
+   */
+  submitted?: boolean;
+  dataTestId: string;
+  onChange: (next: string) => void;
+}): JSX.Element {
+  const [left, setLeft] = useState(false);
+  const impossible = isImpossibleTime(value);
+  const whole = /^\d{2}:\d{2}$/u.test(value);
+  const unfinished = !whole && ((left && value !== "") || submitted);
+  const message = impossible ? invalidMessage : unfinished ? incompleteMessage : undefined;
+  return (
+    <Stack spacing={0.5}>
+      <Input
+        type="text"
+        size="sm"
+        placeholder="00:00"
+        value={value}
+        error={message !== undefined}
+        aria-label={label}
+        inputProps={{ inputMode: "numeric", maxLength: 5, autoComplete: "off" }}
+        onBlur={() => setLeft(true)}
+        onChange={(event) => {
+          setLeft(false);
+          onChange(maskTime(event.target.value, value));
+        }}
+        data-testid={dataTestId}
+      />
+      {message !== undefined && (
+        <FormMessage error dataTestId={`${dataTestId}-message`}>
+          {message}
+        </FormMessage>
+      )}
+    </Stack>
+  );
+}

package/src/react/combo-cart-preview.tsx

@@ -0,0 +1,189 @@
+"use client";
+
+import { createContext, useContext, useRef, type JSX, type ReactNode } from "react";
+
+import { Alert } from "@12-apps/ui/data-display/Alert";
+import { 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 type { ComboRequirement } from "../engine/types";
+
+import { toBasisPoints, toCents, type WireTargetGroup } from "./api";
+import type { DiscountsWebCopy } from "./copy";
+import { comboPreviewOf, type ComboPreview, type ComboRewardValue } from "./combo-preview";
+import { comboPreviewLines, type ComboPreviewLayout } from "./combo-preview-lines";
+import { comboRewardOf } from "./form-kind";
+import type { DiscountsFormatters } from "./format";
+import { KIND_TOGGLE_MIN_PX, useElementWidth } from "./kind-field";
+
+/**
+ * "Como fica no carrinho" on screen (FUT-4417), and where it sits.
+ *
+ * Under the reward's field on a phone or a narrow form; in its own column
+ * beside the form when the form has the room, as the approved prototype draws
+ * it on a computer. What decides is the FORM's own width, measured the way
+ * `KindField` measures it, because the form also lives in a modal narrower
+ * than the screen. In the wide stacked modal the screens open it in
+ * (`DiscountDialog`), a 1280 window gives the form well over the threshold;
+ * a tablet's or a phone's does not, and the preview sits under the field.
+ */
+
+/** The side column's share and gap: `minmax(0, 3fr) minmax(0, 2fr)`, `gap: 3`. */
+const ASIDE_GAP_PX = 24;
+const FORM_SHARE = 3 / 5;
+
+/**
+ * The narrowest form that takes the side column: one whose left column still
+ * holds the kind question as a toggle (`KIND_TOGGLE_MIN_PX`). A column that
+ * squeezed it into a select would trade a control the operator already knows
+ * for a box of text — the preview has room only when nothing else pays for it.
+ */
+const PREVIEW_ASIDE_MIN_PX = Math.ceil(KIND_TOGGLE_MIN_PX / FORM_SHARE + ASIDE_GAP_PX);
+
+/** What the preview reads that is not a form value. */
+interface PreviewInputs {
+  copy: DiscountsWebCopy;
+  formatters: DiscountsFormatters;
+  groups: readonly WireTargetGroup[];
+  slots: readonly ComboRequirement[];
+}
+
+/**
+ * The preview, worked out ONCE per render of the layout and handed down: the
+ * inline box under the reward's field reads it from here rather than summing
+ * the combo a second time.
+ */
+interface PreviewWorld extends PreviewInputs {
+  layout: ComboPreviewLayout;
+  reward: ComboRewardValue;
+  preview: ComboPreview | null;
+}
+
+const PreviewContext = createContext<PreviewWorld | null>(null);
+
+/** The reward the form currently describes, as numbers. */
+function rewardFrom(
+  values: Record<string, string>,
+  formatters: DiscountsFormatters,
+): ComboRewardValue {
+  return {
+    type: comboRewardOf({ type: values.comboReward ?? "" }),
+    percentOffBp: toBasisPoints(values.percentOff ?? "", formatters),
+    amountOffCents: toCents(values.amountOff ?? "", formatters),
+    bundlePriceCents: toCents(values.bundlePrice ?? "", formatters),
+  };
+}
+
+/** The preview the form currently describes, or null when there is nothing honest to sum. */
+function useComboPreview(world: PreviewInputs): {
+  reward: ComboRewardValue;
+  preview: ComboPreview | null;
+} {
+  const { values } = useFormContext();
+  const reward = rewardFrom(values, world.formatters);
+  const preview =
+    values.kind === "COMBO" ? comboPreviewOf(world.slots, world.groups, reward) : null;
+  return { reward, preview };
+}
+
+function PreviewBox({ world }: { world: PreviewWorld }): JSX.Element | null {
+  const { reward, preview } = world;
+  if (preview === null) return null;
+  const lines = comboPreviewLines(preview, reward, world.layout, world.copy, world.formatters);
+  const aside = world.layout === "aside";
+  return (
+    <Alert variant="info" showIcon={false} animate={false} data-testid="combo-cart-preview">
+      <Stack spacing={aside ? 1 : 0.5}>
+        {/* A small label over the figures, as the prototype draws it — not the
+            Alert's own title, which is larger than the lines it heads. */}
+        <Text as="p" variant="caption" weight="semibold" data-testid="combo-cart-preview-heading">
+          {world.copy.comboRewards.preview.title}
+        </Text>
+        <Text variant="body" size="sm" data-testid="combo-cart-preview-items">
+          {lines.items}
+        </Text>
+        {lines.pays !== null && (
+          <Text
+            variant={aside ? "heading" : "body"}
+            {...(aside ? {} : { size: "sm" as const })}
+            data-testid="combo-cart-preview-pays"
+          >
+            {lines.pays}
+          </Text>
+        )}
+        {lines.examples !== null && (
+          <Text variant="caption" data-testid="combo-cart-preview-examples">
+            {lines.examples}
+          </Text>
+        )}
+      </Stack>
+    </Alert>
+  );
+}
+
+/** The preview under the reward's field — rendered only when the form is narrow. */
+export function InlineComboCartPreview(): JSX.Element | null {
+  const world = useContext(PreviewContext);
+  if (world === null || world.layout !== "inline") return null;
+  return <PreviewBox world={world} />;
+}
+
+/**
+ * The form's body, with the preview's column beside it when a combo is being
+ * built and the form is wide enough; otherwise the body alone, as it always
+ * was, and the reward field places the preview under itself.
+ */
+export function ComboPreviewLayout({
+  copy,
+  formatters,
+  groups,
+  slots,
+  children,
+}: PreviewInputs & { children: ReactNode }): JSX.Element {
+  const box = useRef<HTMLDivElement>(null);
+  const width = useElementWidth(box);
+  // The column exists only while there is a preview to put in it: an empty
+  // column beside a combo with no priced group yet is empty space, and the form
+  // would be squeezed for nothing.
+  const { reward, preview } = useComboPreview({
+    copy,
+    formatters,
+    groups,
+    slots,
+  });
+  const layout: ComboPreviewLayout =
+    preview !== null && width !== null && width >= PREVIEW_ASIDE_MIN_PX ? "aside" : "inline";
+  const world: PreviewWorld = {
+    layout,
+    copy,
+    formatters,
+    groups,
+    slots,
+    reward,
+    preview,
+  };
+  return (
+    <PreviewContext.Provider value={world}>
+      <Box
+        ref={box}
+        data-testid="combo-preview-layout"
+        data-layout={layout}
+        sx={
+          layout === "aside"
+            ? {
+                display: "grid",
+                gridTemplateColumns: "minmax(0, 3fr) minmax(0, 2fr)",
+                gap: 3,
+                alignItems: "start",
+              }
+            : { minWidth: 0 }
+        }
+      >
+        <Box sx={{ minWidth: 0 }}>{children}</Box>
+        {layout === "aside" && <PreviewBox world={world} />}
+      </Box>
+    </PreviewContext.Provider>
+  );
+}

package/src/react/combo-preview-lines.ts

@@ -0,0 +1,171 @@
+import { fill, type DiscountsWebCopy } from "./copy";
+import type { ComboPreview, ComboRewardValue } from "./combo-preview";
+import type { DiscountsFormatters } from "./format";
+
+/**
+ * The preview's sentences (FUT-4417), from the figures `comboPreviewOf` worked
+ * out. Pure, so every branch below is a unit test rather than a screenshot.
+ *
+ * Two layouts say the same thing in two shapes, as the approved prototype
+ * draws them:
+ *
+ * - **inline** — under the reward's field, on a phone or a narrow form: two
+ *   lines, the second carrying the whole range ("Cliente paga de R$ 121,05 a
+ *   R$ 143,55 (10% a menos)");
+ * - **aside** — its own column beside a wide form: the second line short and
+ *   emphasised ("Cliente paga 10% a menos"), and a third line of examples at
+ *   both ends of a one-group combo ("Exemplos: 5 de Frango → R$ 121,05 · …").
+ *
+ * The first line is ONE wording for every reward ("5 itens somam de … a …").
+ * The prototype's phone frame said "Itens: de … a …" under the two discounts
+ * and "5 marmitas somam…" under the closed price; the data has no noun like
+ * "marmitas" for a group, so the pack's own counted noun stands in for both.
+ */
+export type ComboPreviewLayout = "inline" | "aside";
+
+interface ComboPreviewLines {
+  items: string;
+  /** What the buyer pays; null while the reward's value is not typed. */
+  pays: string | null;
+  /** The aside's example line; null inline, for several groups, or when both ends cost the same. */
+  examples: string | null;
+}
+
+interface Say {
+  copy: DiscountsWebCopy;
+  money: (cents: number) => string;
+}
+
+function itemsLine(preview: ComboPreview, say: Say): string {
+  const { combo, comboRewards } = say.copy;
+  const units = fill(preview.units === 1 ? combo.unitsOne : combo.unitsOther, {
+    count: preview.units,
+  });
+  const { cheapest, dearest } = preview;
+  return cheapest.groupCents === dearest.groupCents
+    ? fill(comboRewards.preview.itemsExact, {
+        units,
+        sum: say.money(cheapest.groupCents),
+      })
+    : fill(comboRewards.preview.itemsRange, {
+        units,
+        min: say.money(cheapest.groupCents),
+        max: say.money(dearest.groupCents),
+      });
+}
+
+/** "10%" or "R$ 15,00": what a discount reward takes off, as the operator typed it. */
+function offOf(reward: ComboRewardValue, formatters: DiscountsFormatters): string {
+  return reward.type === "PERCENTAGE"
+    ? formatters.percent(reward.percentOffBp)
+    : formatters.money(reward.amountOffCents);
+}
+
+/** The two discounts: a range of what is paid, or the reward itself in the aside. */
+function discountPays(
+  preview: ComboPreview,
+  reward: ComboRewardValue,
+  layout: ComboPreviewLayout,
+  say: Say,
+  off: string,
+): string {
+  const words = say.copy.comboRewards.preview;
+  if (layout === "aside") return fill(words.paysOff, { off });
+  const { cheapest, dearest } = preview;
+  const rate = reward.type === "PERCENTAGE";
+  if (cheapest.paysCents === dearest.paysCents) {
+    const pays = say.money(cheapest.paysCents);
+    return rate ? fill(words.paysExactOff, { pays, off }) : fill(words.paysExact, { pays });
+  }
+  const range = {
+    min: say.money(cheapest.paysCents),
+    max: say.money(dearest.paysCents),
+  };
+  return rate ? fill(words.paysRangeOff, { ...range, off }) : fill(words.paysRange, range);
+}
+
+/** The closed price, in the three places it can sit against the items' range. */
+function pricePays(
+  preview: ComboPreview,
+  price: number,
+  layout: ComboPreviewLayout,
+  say: Say,
+): string {
+  const words = say.copy.comboRewards.preview;
+  const { cheapest, dearest } = preview;
+  const priced = say.money(price);
+  // At or above the dearest sum the engine charges the items (`max(0, …)`).
+  if (dearest.savingCents === 0) return words.noSaving;
+  if (cheapest.savingCents > 0 || cheapest.groupCents === price) {
+    if (layout === "aside") return fill(words.paysExact, { pays: priced });
+    if (cheapest.savingCents === 0) {
+      return fill(words.paysPriceSavingUpTo, {
+        price: priced,
+        max: say.money(dearest.savingCents),
+      });
+    }
+    return cheapest.savingCents === dearest.savingCents
+      ? fill(words.paysPriceSavingExact, {
+          price: priced,
+          saving: say.money(dearest.savingCents),
+        })
+      : fill(words.paysPriceSaving, {
+          price: priced,
+          min: say.money(cheapest.savingCents),
+          max: say.money(dearest.savingCents),
+        });
+  }
+  // Between the two: the cheapest combo costs its items, the dearest the price.
+  const min = say.money(cheapest.paysCents);
+  return layout === "aside"
+    ? fill(words.paysRange, { min, max: priced })
+    : fill(words.paysUpToPrice, {
+        min,
+        price: priced,
+        max: say.money(dearest.savingCents),
+      });
+}
+
+function examplesLine(preview: ComboPreview, reward: ComboRewardValue, say: Say): string | null {
+  const { single, cheapest, dearest } = preview;
+  if (single === null || cheapest.groupCents === dearest.groupCents) return null;
+  const words = say.copy.comboRewards.preview;
+  const example = (name: string, end: typeof cheapest): string => {
+    const values = {
+      quantity: single.quantity,
+      name,
+      pays: say.money(end.paysCents),
+    };
+    return reward.type === "BUNDLE_PRICE" && end.savingCents > 0
+      ? fill(words.exampleSaving, {
+          ...values,
+          saving: say.money(end.savingCents),
+        })
+      : fill(words.example, values);
+  };
+  return fill(words.examples, {
+    cheapest: example(single.cheapestName, cheapest),
+    dearest: example(single.dearestName, dearest),
+  });
+}
+
+export function comboPreviewLines(
+  preview: ComboPreview,
+  reward: ComboRewardValue,
+  layout: ComboPreviewLayout,
+  copy: DiscountsWebCopy,
+  formatters: DiscountsFormatters,
+): ComboPreviewLines {
+  const say: Say = { copy, money: (cents) => formatters.money(cents) };
+  const items = itemsLine(preview, say);
+  if (!preview.rewardTyped) return { items, pays: null, examples: null };
+  const pays =
+    reward.type === "BUNDLE_PRICE"
+      ? pricePays(preview, reward.bundlePriceCents ?? 0, layout, say)
+      : discountPays(preview, reward, layout, say, offOf(reward, formatters));
+  return {
+    items,
+    pays,
+    examples: layout === "aside" ? examplesLine(preview, reward, say) : null,
+  };
+}