@12-apps/discounts 1.1.0 → 1.3.0

package/src/react/format.ts

@@ -0,0 +1,126 @@
+import { discountWindowState, type DiscountWindowState } from "../engine/kinds";
+
+import { fill, type DiscountsWebCopy } from "./copy";
+
+/**
+ * Money, percentages and dates — as ONE locale's reader expects them, and as
+ * that same reader would type them back.
+ *
+ * The origin hard-coded `pt-BR` and `BRL` in five places, which is the shape of
+ * copy leaking into logic: the number "12,5" is not a translation of "12.5", it
+ * is the same number written for a different reader, and a package that assumes
+ * one of them cannot be adopted by the other. So the locale and the currency
+ * arrive as config, and the FORMATTERS ARE BUILT ONCE per surface — `Intl`
+ * constructors are expensive enough that building one per cell is a measurable
+ * cost on a page of eight columns.
+ *
+ * Parsing is the half that is easy to forget. A form takes what the operator
+ * typed, in their own notation, and a `Number("12,5")` is `NaN` — so the
+ * decimal separator is DERIVED from the locale rather than assumed, which is
+ * the only way "1.234,56" and "1,234.56" can both be read correctly.
+ */
+
+/** The dash a surface renders for "nothing here", shared so it stays one glyph. */
+export const EMPTY = "—";
+
+export interface DiscountsFormatters {
+  /** Integer cents as money, or {@link EMPTY}. */
+  money(cents: number | null): string;
+  /** Basis points as a percentage ("1250" → "12,5%"), or {@link EMPTY}. */
+  percent(basisPoints: number | null): string;
+  /** An ISO instant as a calendar date, read in UTC — see below. */
+  date(iso: string | null): string;
+  /** What the operator typed, as a number. `null` for blank or unreadable. */
+  parseDecimal(typed: string): number | null;
+  /** A number as the operator would type it back ("12.5" → "12,5"). */
+  toInput(value: number): string;
+}
+
+/** The decimal separator this locale writes, read from `Intl` rather than guessed. */
+function decimalSeparator(locale: string): string {
+  const parts = new Intl.NumberFormat(locale).formatToParts(1.1);
+  return parts.find((part) => part.type === "decimal")?.value ?? ".";
+}
+
+/** The group separator, which must be STRIPPED before a parse, not replaced. */
+function groupSeparator(locale: string): string {
+  const parts = new Intl.NumberFormat(locale).formatToParts(1_000);
+  return parts.find((part) => part.type === "group")?.value ?? ",";
+}
+
+export function createFormatters(locale: string, currency: string): DiscountsFormatters {
+  const money = new Intl.NumberFormat(locale, { style: "currency", currency });
+  const percent = new Intl.NumberFormat(locale, { maximumFractionDigits: 2 });
+  const decimal = decimalSeparator(locale);
+  const group = groupSeparator(locale);
+
+  return {
+    money: (cents) => (cents === null ? EMPTY : money.format(cents / 100)),
+    percent: (basisPoints) =>
+      basisPoints === null ? EMPTY : `${percent.format(basisPoints / 100)}%`,
+    /**
+     * Read in UTC on purpose. The column holds a CALENDAR date at UTC midnight,
+     * so formatting it in the browser's zone would show a store west of
+     * Greenwich the day before the one they typed — a promotion that appears to
+     * start yesterday.
+     */
+    date: (iso) => {
+      if (iso === null) return EMPTY;
+      const parsed = new Date(iso);
+      if (Number.isNaN(parsed.getTime())) return iso;
+      return parsed.toLocaleDateString(locale, { timeZone: "UTC" });
+    },
+    parseDecimal: (typed) => {
+      const normalized = typed
+        .trim()
+        .split(group)
+        .join("")
+        .replace(decimal, ".");
+      if (normalized === "") return null;
+      const parsed = Number(normalized);
+      return Number.isFinite(parsed) ? parsed : null;
+    },
+    toInput: (value) => String(value).replace(".", decimal),
+  };
+}
+
+/** What a rule takes off, as an operator reads it. */
+export function formatDiscountValue(
+  row: { type: string; percentOffBp: number | null; amountOffCents: number | null; bundlePriceCents?: number | null },
+  formatters: DiscountsFormatters,
+): string {
+  if (row.type === "PERCENTAGE") return formatters.percent(row.percentOffBp);
+  if (row.type === "BUNDLE_PRICE") return formatters.money(row.bundlePriceCents ?? null);
+  if (row.type === "FREE_UNITS") return EMPTY;
+  return formatters.money(row.amountOffCents);
+}
+
+/**
+ * The active window as a SENTENCE, in whichever of the four shapes applies.
+ *
+ * All four get their own phrasing because 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.
+ */
+export function formatWindow(
+  row: { startsAt: string | null; endsAt: string | null },
+  formatters: DiscountsFormatters,
+  copy: DiscountsWebCopy,
+): string {
+  const { startsAt, endsAt } = row;
+  if (startsAt === null && endsAt === null) return copy.window.always;
+  if (endsAt === null) return fill(copy.window.from, { date: formatters.date(startsAt) });
+  if (startsAt === null) return fill(copy.window.until, { date: formatters.date(endsAt) });
+  return fill(copy.window.between, {
+    from: formatters.date(startsAt),
+    to: formatters.date(endsAt),
+  });
+}
+
+/** Where a rule sits relative to its window — the engine's predicate, re-exported. */
+export function windowStateOf(
+  row: { startsAt: string | null; endsAt: string | null },
+  now: Date,
+): DiscountWindowState {
+  return discountWindowState(row, now);
+}

package/src/react/index.ts

@@ -0,0 +1,72 @@
+/**
+ * `@12-apps/discounts/react` — the promotions ADMIN, as a host mounts it.
+ *
+ * One factory: {@link createWebDiscounts}. Everything else exported here is
+ * either a seam a consumer legitimately needs on its own (the transport, to
+ * substitute the backend; the formatters, to render a discount outside these
+ * screens) or a type it needs to satisfy the config.
+ *
+ * The contract a consumer is held to, in two lines:
+ *
+ *  - **Build the surface ONCE, at module scope.** The members are component
+ *    TYPES; rebuilding per render remounts the whole tree below, and a form
+ *    then cannot be typed into.
+ *  - **`onError` is yours.** These screens tell the OPERATOR what went wrong.
+ *    Whether anyone else learns of it is a host decision, and a no-op default
+ *    would make "nothing is broken" and "nothing is watching" look identical.
+ */
+export {
+  createWebDiscounts,
+  useWebDiscounts,
+  DiscountsSurface,
+  type DiscountsScreenProps,
+  type DiscountsWebConfig,
+  type WebDiscounts,
+} from "./create-web-discounts";
+
+export {
+  missingWebCopy,
+  fill,
+  type DiscountsActionsCopy,
+  type DiscountsCardCopy,
+  type DiscountsFormCopy,
+  type DiscountsScreenCopy,
+  type DiscountsTargetCopy,
+  type DiscountsVocabularyCopy,
+  type DiscountsWebCopy,
+  type DiscountsWindowCopy,
+} from "./copy";
+
+export { PT_BR_DISCOUNTS_WEB_COPY } from "./pt-BR";
+
+export {
+  createFormatters,
+  formatDiscountValue,
+  formatWindow,
+  windowStateOf,
+  EMPTY,
+  type DiscountsFormatters,
+} from "./format";
+
+export {
+  createDiscountsApiClient,
+  toWriteBody,
+  type DiscountFormPayload,
+  type DiscountsApiClient,
+  type DiscountsPage,
+  type DiscountsPagination,
+  type DiscountWireRecord,
+  type WireTarget,
+  type WireTargetGroup,
+} from "./api";
+
+export {
+  httpDiscountsTransport,
+  DiscountsHttpError,
+  type DiscountsResult,
+  type DiscountsTransport,
+} from "./transport";
+
+export { toListItem, type DiscountListItem } from "./row";
+
+export type { CurrencyFieldComponent } from "./discount-form-fields";

package/src/react/pt-BR.ts

@@ -0,0 +1,132 @@
+import type { DiscountsWebCopy } from "./copy";
+
+/**
+ * The pt-BR pack for the discounts admin screens.
+ *
+ * A NAMED PACK a host passes by hand, never a default: choosing a language is a
+ * line in the adopter's diff. See `./copy` for why the port has this many keys.
+ *
+ * Doubles as the SHAPE `missingWebCopy` walks, which is the only reason this
+ * module is imported by `createWebDiscounts` — the key names travel, the words
+ * do not.
+ */
+export const PT_BR_DISCOUNTS_WEB_COPY: DiscountsWebCopy = {
+  screen: {
+    title: "Descontos",
+    aboutTitle: "Sobre os descontos",
+    aboutBody:
+      "Crie promoções automáticas ou cupons com código, para o pedido inteiro, uma categoria, produtos específicos ou um combo.",
+    create: "Novo desconto",
+    empty: "Nenhum desconto cadastrado.",
+    exportFileName: "descontos",
+    loading: "Carregando descontos…",
+    loadFailed: "Não foi possível carregar os descontos",
+    retry: "Tentar novamente",
+    columns: {
+      name: "Nome",
+      value: "Desconto",
+      type: "Tipo",
+      scope: "Abrangência",
+      trigger: "Ativação",
+      window: "Vigência",
+      code: "Código",
+      usageCount: "Usos",
+      active: "Ativo",
+    },
+    yes: "Sim",
+    no: "Não",
+  },
+  labels: {
+    type: {
+      PERCENTAGE: "Porcentagem",
+      FIXED_AMOUNT: "Valor fixo",
+      BUNDLE_PRICE: "Preço de combo",
+      FREE_UNITS: "Itens grátis",
+    },
+    scope: {
+      ORDER: "Pedido",
+      CATEGORY: "Categoria",
+      ITEM: "Item",
+      COMBO: "Combo",
+    },
+    trigger: {
+      AUTOMATIC: "Automático",
+      CODE: "Código",
+    },
+    window: {
+      RUNNING: "Vigente",
+      SCHEDULED: "Agendado",
+      ENDED: "Encerrado",
+    },
+  },
+  window: {
+    always: "Sem prazo",
+    from: "A partir de {date}",
+    until: "Até {date}",
+    between: "{from} a {to}",
+  },
+  form: {
+    createTitle: "Novo desconto",
+    editTitle: "Editar desconto",
+    submitCreate: "Criar desconto",
+    submitEdit: "Salvar alterações",
+    name: "Nome da promoção",
+    type: "Tipo",
+    percentOff: "Desconto (%)",
+    percentPlaceholder: "10",
+    amountOff: "Valor do desconto",
+    trigger: "Ativação",
+    code: "Código do cupom",
+    codePlaceholder: "BEMVINDO10",
+    scope: "Abrangência",
+    startsAt: "Início",
+    endsAt: "Término",
+    minSubtotal: "Pedido mínimo",
+    usageLimit: "Limite de usos",
+    perBuyerLimit: "Limite por cliente",
+    active: "Ativo",
+    activeHint: "Desligue para pausar a promoção sem excluí-la.",
+    stackable: "Acumulável",
+    stackableHint:
+      "Quando desligado, esta promoção é exclusiva: se vencer, nenhuma outra é aplicada.",
+    reviewFields: "Revise os campos destacados.",
+    saveFailed: "Não foi possível salvar o desconto",
+    nameRequired: "Informe o nome da promoção.",
+    invalidPercent: "Informe uma porcentagem maior que 0 e no máximo 100.",
+    invalidAmount: "Informe um valor de desconto maior que zero.",
+    codeRequired: "Informe o código do cupom que o cliente vai digitar.",
+    categoryTargetRequired: "Selecione ao menos uma categoria para este desconto.",
+    itemTargetRequired: "Selecione ao menos um produto para este desconto.",
+    endsBeforeStarts: "A data de término deve ser posterior à data de início.",
+  },
+  targets: {
+    pick: "{collection} com desconto",
+    search: "Buscar em {collection}…",
+    required: "Selecione ao menos uma opção.",
+  },
+  actions: {
+    menu: "Ações",
+    edit: "Editar",
+    delete: "Excluir",
+    deleteTitle: "Excluir o desconto?",
+    deleteDescription: "O desconto para de valer na vitrine e não pode ser restaurado.",
+    deleteManyTitle: "Excluir {count} descontos?",
+    deleteManyDescription: "Deixam de valer na vitrine e não podem ser restaurados.",
+    deleteFailed: "Não foi possível excluir o desconto.",
+    actionFailed: "Não foi possível concluir a ação",
+  },
+  card: {
+    paused: "Pausado",
+    ruleHeading: "Regra",
+    targetsHeading: "Alvos",
+    wholeOrder: "pedido inteiro",
+    oneTarget: "1 alvo",
+    manyTargets: "{count} alvos",
+    withCode: "código {code}",
+    noTargets: "Nenhum alvo",
+    usage: "Usos",
+    minSubtotal: "Pedido mínimo",
+    perBuyerLimit: "Limite por cliente",
+    unlimited: "Sem limite",
+  },
+};

package/src/react/row.ts

@@ -0,0 +1,66 @@
+import type { DiscountWindowState } from "../engine/kinds";
+
+import type { DiscountWireRecord } from "./api";
+import type { DiscountsWebCopy } from "./copy";
+import { formatDiscountValue, formatWindow, windowStateOf, type DiscountsFormatters } from "./format";
+
+/**
+ * One wire record plus the three strings the grid, the cards and the export all
+ * show.
+ *
+ * Derived ONCE per page render rather than inside a cell, and that is two
+ * decisions in one. Basis-point arithmetic and date formatting run once per row
+ * instead of once per re-render; and the grid, the card and the exported file
+ * then read the SAME string, so the three cannot disagree about what a
+ * promotion is worth — which they did, in the origin, until this shape existed.
+ */
+export interface DiscountListItem extends Record<string, unknown> {
+  id: string;
+  name: string;
+  type: string;
+  percentOffBp: number | null;
+  amountOffCents: number | null;
+  bundlePriceCents: number | null;
+  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[];
+  /** Pre-formatted: what it takes off. */
+  valueLabel: string;
+  /** Pre-formatted: the validity sentence. */
+  windowLabel: string;
+  /** Where it sits relative to its window, as a stable wire token. */
+  windowState: DiscountWindowState;
+  /** The record itself, for the edit dialog to re-seed from. */
+  record: DiscountWireRecord;
+}
+
+/**
+ * @param now ONE instant for the whole page, passed in rather than read here:
+ * two rows judged against two different "now"s could disagree about which of
+ * them is still running, and on a list of forty that difference is invisible.
+ */
+export function toListItem(
+  record: DiscountWireRecord,
+  formatters: DiscountsFormatters,
+  copy: DiscountsWebCopy,
+  now: Date,
+): DiscountListItem {
+  return {
+    ...record,
+    bundlePriceCents: record.bundlePriceCents ?? null,
+    valueLabel: formatDiscountValue(record, formatters),
+    windowLabel: formatWindow(record, formatters, copy),
+    windowState: windowStateOf(record, now),
+    record,
+  };
+}

package/src/react/table-config.ts

@@ -0,0 +1,238 @@
+import type {
+  DataViewColumn,
+  DataViewQuery,
+  DataViewState,
+  FilterFieldConfig,
+} from "@12-apps/ui/data-display/DataViews";
+import type { ExportColumn } from "@12-apps/ui/utils";
+
+import {
+  DISCOUNT_SCOPES,
+  DISCOUNT_TRIGGERS,
+  DISCOUNT_TYPES,
+  DISCOUNT_WINDOW_STATES,
+} from "../engine/kinds";
+
+import type { DiscountsWebCopy } from "./copy";
+import { EMPTY } from "./format";
+import type { DiscountListItem } from "./row";
+
+/**
+ * The grid's columns, pills and export, plus the URL ⇄ query plumbing.
+ *
+ * The pill VALUES are the WIRE values and only the labels are translated. That
+ * is what lets a selection be forwarded straight into the backend query with no
+ * second mapping table to drift out of step with the search config — and it is
+ * why `DISCOUNT_WINDOW_STATES` are English tokens rather than the words on the
+ * pill: the origin filtered on its own pt-BR labels, so its wire protocol was
+ * its language.
+ */
+
+/** The grid-owned URL params, forwarded verbatim to the backend query. */
+const OWNED_PARAMS = [
+  "q",
+  "page",
+  "sort",
+  "type_in",
+  "scope_in",
+  "trigger_in",
+  "active",
+  "window",
+] as const;
+
+/** A CODE rule is identified by its coupon, not by the word "code". */
+function triggerCell(row: DiscountListItem, copy: DiscountsWebCopy): string {
+  if (row.trigger === "CODE") return row.code ?? EMPTY;
+  return copy.labels.trigger[row.trigger as keyof typeof copy.labels.trigger] ?? row.trigger;
+}
+
+/** One label out of a pack, falling back to the raw stored value. */
+function labelled(labels: Readonly<Record<string, string>>, value: string): string {
+  // The closed sets live in the database as CHECK constraints, so a value that
+  // arrives unknown means the set was widened server-side — and a list that
+  // renders `PERCENTAGE` is far better than one that renders a crash.
+  return labels[value] ?? value;
+}
+
+export function discountColumns(copy: DiscountsWebCopy): DataViewColumn<DiscountListItem>[] {
+  return [
+    { id: "name", header: copy.screen.columns.name, accessor: "name", searchable: true },
+    // Pre-formatted by the page: a cell must not do arithmetic on basis points.
+    { id: "value", header: copy.screen.columns.value, accessor: (row) => row.valueLabel },
+    {
+      id: "type",
+      header: copy.screen.columns.type,
+      accessor: (row) => labelled(copy.labels.type, row.type),
+    },
+    {
+      id: "scope",
+      header: copy.screen.columns.scope,
+      accessor: (row) => labelled(copy.labels.scope, row.scope),
+    },
+    {
+      id: "trigger",
+      header: copy.screen.columns.trigger,
+      accessor: (row) => triggerCell(row, copy),
+      searchable: true,
+    },
+    { id: "window", header: copy.screen.columns.window, accessor: (row) => row.windowLabel },
+    {
+      id: "usageCount",
+      header: copy.screen.columns.usageCount,
+      accessor: (row) => String(row.usageCount),
+    },
+    {
+      id: "active",
+      header: copy.screen.columns.active,
+      accessor: (row) => (row.active ? copy.screen.yes : copy.screen.no),
+    },
+  ];
+}
+
+/** One closed set as filter options: wire values, translated labels. */
+function pillOptions<TKey extends string>(
+  values: readonly TKey[],
+  labels: Readonly<Record<TKey, string>>,
+): { value: string; label: string }[] {
+  return values.map((value) => ({ value, label: labels[value] }));
+}
+
+export function discountFilters(copy: DiscountsWebCopy): FilterFieldConfig<DiscountListItem>[] {
+  return [
+    {
+      id: "type",
+      label: copy.screen.columns.type,
+      accessor: (row) => row.type,
+      options: pillOptions(DISCOUNT_TYPES, copy.labels.type),
+    },
+    {
+      id: "scope",
+      label: copy.screen.columns.scope,
+      accessor: (row) => row.scope,
+      options: pillOptions(DISCOUNT_SCOPES, copy.labels.scope),
+    },
+    {
+      id: "trigger",
+      label: copy.screen.columns.trigger,
+      accessor: (row) => row.trigger,
+      options: pillOptions(DISCOUNT_TRIGGERS, copy.labels.trigger),
+    },
+    {
+      id: "active",
+      label: copy.screen.columns.active,
+      accessor: (row) => (row.active ? "true" : "false"),
+      options: [
+        { value: "true", label: copy.screen.yes },
+        { value: "false", label: copy.screen.no },
+      ],
+    },
+    {
+      id: "window",
+      label: copy.screen.columns.window,
+      accessor: (row) => row.windowState,
+      options: pillOptions(DISCOUNT_WINDOW_STATES, copy.labels.window),
+    },
+  ];
+}
+
+export function discountExportColumns(
+  copy: DiscountsWebCopy,
+): ExportColumn<DiscountListItem>[] {
+  return [
+    { header: copy.screen.columns.name, value: (row) => row.name },
+    { header: copy.screen.columns.value, value: (row) => row.valueLabel },
+    { header: copy.screen.columns.type, value: (row) => labelled(copy.labels.type, row.type) },
+    { header: copy.screen.columns.scope, value: (row) => labelled(copy.labels.scope, row.scope) },
+    {
+      header: copy.screen.columns.trigger,
+      value: (row) => labelled(copy.labels.trigger, row.trigger),
+    },
+    { header: copy.screen.columns.code, value: (row) => row.code ?? "" },
+    { header: copy.screen.columns.window, value: (row) => row.windowLabel },
+    { header: copy.screen.columns.usageCount, value: (row) => String(row.usageCount) },
+    {
+      header: copy.screen.columns.active,
+      value: (row) => (row.active ? copy.screen.yes : copy.screen.no),
+    },
+  ];
+}
+
+/** A comma-joined `_in` list, or undefined when the pill is untouched. */
+function inList(values: string[] | undefined): string | undefined {
+  return values && values.length > 0 ? values.join(",") : undefined;
+}
+
+/** A single-choice pill, or undefined when both or neither option is picked. */
+function oneOf(values: string[] | undefined, allowed: readonly string[]): string | undefined {
+  const picked = values?.length === 1 ? values[0] : undefined;
+  return picked !== undefined && allowed.includes(picked) ? picked : undefined;
+}
+
+/**
+ * Map the grid's query into the backend's search params. An omitted key clears
+ * its param from the URL, so a dropped filter never lingers.
+ */
+export function discountsQueryToParams(
+  query: DataViewQuery,
+): Record<string, string | undefined> {
+  const sort = query.sortBy[0];
+  return {
+    q: query.search || undefined,
+    page: query.page > 1 ? String(query.page) : undefined,
+    sort: sort && sort.dir ? `${sort.id}:${sort.dir}` : undefined,
+    type_in: inList(query.pills.type),
+    scope_in: inList(query.pills.scope),
+    trigger_in: inList(query.pills.trigger),
+    active: oneOf(query.pills.active, ["true", "false"]),
+    window: oneOf(query.pills.window, DISCOUNT_WINDOW_STATES),
+  };
+}
+
+/** The filter pills encoded in the URL. */
+function pillsFromParams(params: URLSearchParams): Record<string, string[]> {
+  const pills: Record<string, string[]> = {};
+  for (const [param, id] of [
+    ["type_in", "type"],
+    ["scope_in", "scope"],
+    ["trigger_in", "trigger"],
+  ] as const) {
+    const raw = params.get(param);
+    if (raw) pills[id] = raw.split(",");
+  }
+  const active = params.get("active");
+  if (active === "true" || active === "false") pills.active = [active];
+  const window = params.get("window");
+  if (window && DISCOUNT_WINDOW_STATES.some((state) => state === window)) pills.window = [window];
+  return pills;
+}
+
+/**
+ * Seed the grid's client state from the URL, so a bookmarked filtered link is
+ * reflected on first render — otherwise the empty client state emits an
+ * unfiltered query and wipes the params the operator arrived with.
+ */
+export function discountsAppliedState(
+  params: URLSearchParams,
+  copy: DiscountsWebCopy,
+): DataViewState {
+  const [sortField, sortDir] = (params.get("sort") ?? "").split(":");
+  const sortBy: DataViewState["sortBy"] =
+    sortField && sortDir ? [{ id: sortField, dir: sortDir === "desc" ? "desc" : "asc" }] : [];
+  return {
+    search: params.get("q") ?? "",
+    pills: pillsFromParams(params),
+    ranges: {},
+    sortBy,
+    visibleColumns: discountColumns(copy).map((column) => column.id),
+  };
+}
+
+/** The discounts query string for the current URL — only the params we own. */
+export function discountsSearch(params: URLSearchParams): string {
+  const query = new URLSearchParams();
+  for (const key of OWNED_PARAMS) {
+    const value = params.get(key);
+    if (value) query.set(key, value);
+  }
+  return query.toString();
+}