@12-apps/discounts 1.2.0 → 1.3.0

package/src/react/api.ts

@@ -0,0 +1,185 @@
+import type { ComboRequirement } from "../engine/types";
+
+import type { DiscountsFormatters } from "./format";
+import type { DiscountsResult, DiscountsTransport } from "./transport";
+
+/**
+ * The wire, and the one place the FORM's shape becomes the API's.
+ *
+ * A form holds strings — every value in a text input is one — while the API
+ * takes integers, basis points and nulls. That coercion is a real rule set, not
+ * plumbing, and it has exactly one rule worth stating: a BLANK field means "no
+ * value" (`null`), never zero, because `0` is a real and different answer for a
+ * limit or a minimum. A host repeating this per call site is how one screen
+ * starts saving `0` where another saves `null`.
+ */
+
+/** A discount as the CRUD endpoints echo it — JSON, so dates are ISO strings. */
+export interface DiscountWireRecord {
+  id: string;
+  name: string;
+  type: string;
+  percentOffBp: number | null;
+  amountOffCents: number | null;
+  bundlePriceCents?: number | null;
+  freeUnits?: number | null;
+  maxComboApplications?: number | null;
+  comboRequirements?: ComboRequirement[];
+  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[];
+  createdAt: string;
+}
+
+/** The pagination envelope the list endpoint answers with. */
+export interface DiscountsPagination {
+  page: number;
+  pageSize: number;
+  total: number;
+  pageCount: number;
+  hasNextPage: boolean;
+  hasPreviousPage: boolean;
+}
+
+export interface DiscountsPage {
+  data: DiscountWireRecord[];
+  pagination: DiscountsPagination;
+}
+
+/** One selectable target, as `GET /discounts/targets` answers it. */
+export interface WireTarget {
+  id: string;
+  name: string;
+  parentId?: string | null;
+}
+
+/** One registered collection and its rows. */
+export interface WireTargetGroup {
+  targetType: string;
+  slug: string;
+  label: string;
+  nests: boolean;
+  targets: WireTarget[];
+}
+
+/** The form's payload, still in FORM shape. */
+export interface DiscountFormPayload {
+  name: string;
+  type: string;
+  /** 0–100 with up to two decimals, in the operator's own notation. */
+  percentOff: string;
+  /** A money amount, as the currency field stores it. */
+  amountOff: string;
+  scope: string;
+  trigger: string;
+  code: string;
+  startsAt: string;
+  endsAt: string;
+  minSubtotal: string;
+  usageLimit: string;
+  perBuyerLimit: string;
+  stackable: boolean;
+  active: boolean;
+  categoryIds: string[];
+  menuItemIds: string[];
+}
+
+/** A money amount as integer cents, or null when blank. */
+function toCents(typed: string, formatters: DiscountsFormatters): number | null {
+  const amount = formatters.parseDecimal(typed);
+  return amount === null ? null : Math.round(amount * 100);
+}
+
+/** A whole-number cap, or null when blank ("no cap"). */
+function toCount(typed: string, formatters: DiscountsFormatters): number | null {
+  const parsed = formatters.parseDecimal(typed);
+  return parsed === null ? null : Math.trunc(parsed);
+}
+
+/**
+ * A percentage as BASIS POINTS.
+ *
+ * The form takes 0–100 with two decimals because that is how an operator thinks
+ * about a promotion; the column stores basis points because that is how the
+ * 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 {
+  const percent = formatters.parseDecimal(typed);
+  return percent === null ? null : Math.round(percent * 100);
+}
+
+/** Blank → null, so an unused branch's leftover text never reaches a column. */
+function toNullable(value: string): string | null {
+  const trimmed = value.trim();
+  return trimmed === "" ? null : trimmed;
+}
+
+/** The wire body both writes send — a discount is always saved WHOLE. */
+export function toWriteBody(
+  input: DiscountFormPayload,
+  formatters: DiscountsFormatters,
+): Record<string, unknown> {
+  const isPercentage = input.type === "PERCENTAGE";
+  return {
+    name: input.name.trim(),
+    type: input.type,
+    percentOffBp: isPercentage ? toBasisPoints(input.percentOff, formatters) : null,
+    amountOffCents: isPercentage ? null : toCents(input.amountOff, formatters),
+    scope: input.scope,
+    trigger: input.trigger,
+    code: input.trigger === "CODE" ? toNullable(input.code) : null,
+    startsAt: toNullable(input.startsAt),
+    endsAt: toNullable(input.endsAt),
+    minSubtotalCents: toCents(input.minSubtotal, formatters),
+    usageLimit: toCount(input.usageLimit, formatters),
+    perBuyerLimit: toCount(input.perBuyerLimit, formatters),
+    stackable: input.stackable,
+    active: input.active,
+    // Narrowed to the scope on the way OUT as well as on the way in: leaving a
+    // stale id list on a rule whose scope changed is how a promotion goes on
+    // covering something its screen no longer shows.
+    categoryIds: input.scope === "CATEGORY" ? input.categoryIds : [],
+    menuItemIds: input.scope === "ITEM" ? input.menuItemIds : [],
+  };
+}
+
+/** The bound wire client the screens use. Nothing else performs I/O. */
+export interface DiscountsApiClient {
+  list(search: string): Promise<DiscountsPage>;
+  targets(): Promise<readonly WireTargetGroup[]>;
+  create(input: DiscountFormPayload): Promise<DiscountsResult<DiscountWireRecord>>;
+  update(id: string, input: DiscountFormPayload): Promise<DiscountsResult<{ id: string }>>;
+  remove(id: string): Promise<DiscountsResult<{ id: string }>>;
+}
+
+export function createDiscountsApiClient(
+  apiBase: string,
+  transport: DiscountsTransport,
+  formatters: DiscountsFormatters,
+): DiscountsApiClient {
+  const collection = `${apiBase}/discounts`;
+  const item = (id: string): string => `${collection}/${encodeURIComponent(id)}`;
+  return {
+    list: (search) => transport.get<DiscountsPage>(search ? `${collection}?${search}` : collection),
+    targets: () =>
+      transport
+        .get<{ data: WireTargetGroup[] }>(`${collection}/targets`)
+        .then((payload) => payload.data),
+    create: (input) =>
+      transport.send<DiscountWireRecord>(collection, "POST", toWriteBody(input, formatters)),
+    update: (id, input) =>
+      transport.send<{ id: string }>(item(id), "PATCH", toWriteBody(input, formatters)),
+    remove: (id) => transport.send<{ id: string }>(item(id), "DELETE"),
+  };
+}

package/src/react/copy.ts

@@ -0,0 +1,239 @@
+import type {
+  DiscountScope,
+  DiscountTrigger,
+  DiscountType,
+  DiscountWindowState,
+} from "../engine/kinds";
+
+/**
+ * Every word the discounts ADMIN screens put in front of a human — required
+ * host config, with NO defaults.
+ *
+ * The third copy port in this package, after `DiscountRejectionCopy` (what a
+ * buyer is told) and `DiscountsServerCopy` (what an operator is told when a
+ * write is refused). Same rule, for the third time and for the same reason: a
+ * default in the origin's language reads as finished to the next host right up
+ * until a user sees it, and the copy-portability gate exists to refuse exactly
+ * that.
+ *
+ * It is a LOT of keys, and that is the honest count rather than a design
+ * failure. This surface is a grid, a form of fourteen inputs, two pickers, two
+ * card layouts and four confirmation popups; the origin held roughly 1,800
+ * lines, three quarters of which was this. Nothing here has been folded
+ * together to make the interface look smaller — two sentences that happen to
+ * match today in one language are two sentences.
+ *
+ * Grouped by SURFACE rather than alphabetically, because a host fills it in by
+ * walking a screen.
+ *
+ * Interpolation is `{name}`-style and there are exactly four of them, each
+ * documented at its key. A template rather than a function so the pack stays
+ * plain data a host can lint, diff and translate.
+ */
+
+/** The labels for one closed set — every member, so nothing renders raw. */
+type LabelsFor<TKey extends string> = Readonly<Record<TKey, string>>;
+
+/** The list page: its chrome, its columns and its filters. */
+export interface DiscountsScreenCopy {
+  /** The page title, and the last breadcrumb crumb. */
+  readonly title: string;
+  /** The header's explanatory panel — its heading and its paragraph. */
+  readonly aboutTitle: string;
+  readonly aboutBody: string;
+  /** The primary action that opens the create dialog. */
+  readonly create: string;
+  /** Shown when the tenant has no promotions at all. */
+  readonly empty: string;
+  /** The exported file's base name, without extension. */
+  readonly exportFileName: string;
+  /** While the first page is loading. */
+  readonly loading: string;
+  /** The read failed: a heading, and the button that tries again. */
+  readonly loadFailed: string;
+  readonly retry: string;
+  /** Column headers, which are also the export's column keys. */
+  readonly columns: {
+    readonly name: string;
+    readonly value: string;
+    readonly type: string;
+    readonly scope: string;
+    readonly trigger: string;
+    readonly window: string;
+    readonly code: string;
+    readonly usageCount: string;
+    readonly active: string;
+  };
+  /** The two words a boolean column and its filter pill render. */
+  readonly yes: string;
+  readonly no: string;
+}
+
+/** The four closed sets, each labelled in full. */
+export interface DiscountsVocabularyCopy {
+  readonly type: LabelsFor<DiscountType>;
+  readonly scope: LabelsFor<DiscountScope>;
+  readonly trigger: LabelsFor<DiscountTrigger>;
+  readonly window: LabelsFor<DiscountWindowState>;
+}
+
+/** The validity sentence, in all four shapes a nullable window can take. */
+export interface DiscountsWindowCopy {
+  /** Neither bound set — it runs until somebody stops it. */
+  readonly always: string;
+  /** Only a start. `{date}`. */
+  readonly from: string;
+  /** Only an end. `{date}`. */
+  readonly until: string;
+  /** Both. `{from}` and `{to}`. */
+  readonly between: string;
+}
+
+/** The create/edit form: its inputs, and every rule it can refuse for. */
+export interface DiscountsFormCopy {
+  readonly createTitle: string;
+  readonly editTitle: string;
+  readonly submitCreate: string;
+  readonly submitEdit: string;
+  readonly name: string;
+  readonly type: string;
+  readonly percentOff: string;
+  /** The example inside the empty percentage input. */
+  readonly percentPlaceholder: string;
+  readonly amountOff: string;
+  readonly trigger: string;
+  readonly code: string;
+  /** The example inside the empty coupon input. */
+  readonly codePlaceholder: string;
+  readonly scope: string;
+  readonly startsAt: string;
+  readonly endsAt: string;
+  readonly minSubtotal: string;
+  readonly usageLimit: string;
+  readonly perBuyerLimit: string;
+  readonly active: string;
+  readonly activeHint: string;
+  readonly stackable: string;
+  readonly stackableHint: string;
+  /** The banner over a form the operator must fix before it will send. */
+  readonly reviewFields: string;
+  /** The banner over a write the SERVER refused. */
+  readonly saveFailed: string;
+  /** Per-input refusals, each attached to the input it names. */
+  readonly nameRequired: string;
+  readonly invalidPercent: string;
+  readonly invalidAmount: string;
+  readonly codeRequired: string;
+  readonly categoryTargetRequired: string;
+  readonly itemTargetRequired: string;
+  readonly endsBeforeStarts: string;
+}
+
+/** The target pickers, and what an empty selection says. */
+export interface DiscountsTargetCopy {
+  /** The picker's label, `{collection}` — the registration's own label. */
+  readonly pick: string;
+  /** The placeholder inside a searchable picker, `{collection}`. */
+  readonly search: string;
+  /** Shown under a picker the scope requires and nothing is chosen in. */
+  readonly required: string;
+}
+
+/** The row and card menus, and the two destructive confirmations. */
+export interface DiscountsActionsCopy {
+  /** The kebab's accessible name — announced verbatim by a screen reader. */
+  readonly menu: string;
+  readonly edit: string;
+  readonly delete: string;
+  /** The delete popup for ONE rule. */
+  readonly deleteTitle: string;
+  readonly deleteDescription: string;
+  /** The delete popup for a SELECTION. `{count}`. */
+  readonly deleteManyTitle: string;
+  readonly deleteManyDescription: string;
+  /** When a delete fails and the server said nothing useful. */
+  readonly deleteFailed: string;
+  /** The shared snackbar's heading, over whatever an action reported. */
+  readonly actionFailed: string;
+}
+
+/** The two card layouts. */
+export interface DiscountsCardCopy {
+  /** The chip a switched-off rule carries. Shown only when it is off. */
+  readonly paused: string;
+  /** Headings inside an expanded list-card body. */
+  readonly ruleHeading: string;
+  readonly targetsHeading: string;
+  /** What an ORDER-scoped rule covers. */
+  readonly wholeOrder: string;
+  /** How many rows it points at: one, and `{count}` for the rest. */
+  readonly oneTarget: string;
+  readonly manyTargets: string;
+  /** A CODE rule's secondary line, `{code}`. */
+  readonly withCode: string;
+  /** An empty target run inside a card. */
+  readonly noTargets: string;
+  /** Row labels inside the expanded body. */
+  readonly usage: string;
+  readonly minSubtotal: string;
+  readonly perBuyerLimit: string;
+  readonly unlimited: string;
+}
+
+export interface DiscountsWebCopy {
+  readonly screen: DiscountsScreenCopy;
+  readonly labels: DiscountsVocabularyCopy;
+  readonly window: DiscountsWindowCopy;
+  readonly form: DiscountsFormCopy;
+  readonly targets: DiscountsTargetCopy;
+  readonly actions: DiscountsActionsCopy;
+  readonly card: DiscountsCardCopy;
+}
+
+/**
+ * Fill `{name}` placeholders. Unknown names are left alone rather than blanked,
+ * so a pack with a typo shows the typo instead of a hole nobody can trace.
+ */
+export function fill(template: string, values: Readonly<Record<string, string | number>>): string {
+  return template.replace(/\{(\w+)\}/g, (whole, key: string) =>
+    key in values ? String(values[key]) : whole,
+  );
+}
+
+/** Every leaf path of an object, dotted. */
+function leafPaths(value: unknown, prefix = ""): string[] {
+  if (value === null || typeof value !== "object") return prefix === "" ? [] : [prefix];
+  return Object.entries(value as Record<string, unknown>).flatMap(([key, child]) =>
+    leafPaths(child, prefix === "" ? key : `${prefix}.${key}`),
+  );
+}
+
+/** One dotted path out of a pack, or `undefined` where the path does not exist. */
+function read(copy: unknown, path: string): unknown {
+  return path.split(".").reduce<unknown>(
+    (node, key) =>
+      node !== null && typeof node === "object"
+        ? (node as Record<string, unknown>)[key]
+        : undefined,
+    copy,
+  );
+}
+
+/**
+ * The keys a pack is missing or left blank, as dotted paths.
+ *
+ * Walked from a REFERENCE pack rather than from a hand-kept key list: this
+ * interface is seventy-odd keys deep in seven groups, and a list beside it
+ * would be wrong within one release. Only the reference's SHAPE is read, never
+ * its words — `createWebDiscounts` passes the pt-BR pack for that and nothing
+ * of it survives into the answer.
+ */
+export function missingWebCopy(
+  copy: DiscountsWebCopy | undefined,
+  reference: DiscountsWebCopy,
+): string[] {
+  return leafPaths(reference).filter((path) => {
+    const value = read(copy, path);
+    return typeof value !== "string" || value.trim() === "";
+  });
+}

package/src/react/create-web-discounts.tsx

@@ -0,0 +1,162 @@
+"use client";
+
+import { useMemo, type ComponentType, type JSX } from "react";
+
+import { createDiscountsApiClient, type DiscountsApiClient } from "./api";
+import { missingWebCopy, type DiscountsWebCopy } from "./copy";
+import { DiscountForm, type DiscountFormProps } from "./discount-form";
+import type { CurrencyFieldComponent } from "./discount-form-fields";
+import { DiscountsScreen, type DiscountsScreenProps } from "./discounts-screen";
+import { createFormatters, type DiscountsFormatters } from "./format";
+import { PT_BR_DISCOUNTS_WEB_COPY } from "./pt-BR";
+import { httpDiscountsTransport, type DiscountsTransport } from "./transport";
+
+/**
+ * The one thing this package exposes to a FRONTEND host.
+ *
+ * Everything the promotions admin IS — the server-driven grid with its filters
+ * and its export, the create/edit form and its fourteen inputs, the target
+ * pickers, both card layouts, the four confirmations and every wire call
+ * between them — lives inside this package now. The host names where the API is
+ * mounted, supplies every sentence, says which locale its operators read, and
+ * that is the whole wiring.
+ *
+ * ## Build it ONCE, at module scope
+ *
+ * The members are component TYPES. Rebuilding the surface per render gives
+ * React new types every time, which unmounts and remounts the entire tree below
+ * — a form loses what the operator typed on every keystroke that reaches the
+ * page above it. Every `createWeb*` in this org carries the same warning
+ * because it is the same hazard, and it is silent: the screen works, it just
+ * cannot be typed into.
+ */
+
+export interface DiscountsWebConfig {
+  /** The admin mount the routes live under, e.g. `/api/admin/my-store`. */
+  apiBase: string;
+  /**
+   * Every sentence the screens render — REQUIRED, the host's words. A pt-BR
+   * host passes `PT_BR_DISCOUNTS_WEB_COPY`.
+   */
+  copy: DiscountsWebCopy;
+  /**
+   * How money, percentages and dates are written — and READ BACK. A form takes
+   * what the operator typed in their own notation, so this decides parsing as
+   * much as rendering.
+   */
+  locale: string;
+  /** ISO 4217, e.g. `BRL`. */
+  currency: string;
+  /**
+   * Where a failure goes, beyond the operator's own screen — REQUIRED, and for
+   * the same reason `createApiDiscounts` requires a logger.
+   *
+   * The screens already SHOW an operator what went wrong; that is not the same
+   * as anybody knowing. A refused write, a catalog that would not load, a page
+   * read that failed — each of those reaches a person only if a host routes it
+   * somewhere, and a no-op default here would make "nothing is broken" and
+   * "nothing is watching" look identical. A host wires this to its browser
+   * error reporter.
+   *
+   * `context` is a stable dotted token (`discounts.create`, `discounts.list`)
+   * rather than a sentence, so a reporter can group on it.
+   */
+  onError: (error: unknown, context: string) => void;
+  /**
+   * The money input. Currency entry is a host decision — masking, which side
+   * the symbol sits on, whether cents are typed or implied — and there is no
+   * neutral answer to ship. A host with nothing special passes a plain text
+   * field.
+   */
+  currencyField: CurrencyFieldComponent;
+  /** How the surface reaches its data. Default: same-origin fetch. */
+  transport?: DiscountsTransport;
+  /** The crumbs above the title. The host owns its information hierarchy. */
+  breadcrumb?: readonly { label: string; href?: string }[];
+}
+
+export interface WebDiscounts {
+  /** The whole promotions admin. */
+  Screen: ComponentType;
+  /**
+   * The form on its own, for a host embedding it somewhere of its own — an
+   * onboarding step, a wizard. Already bound to the same client and copy.
+   */
+  DiscountForm: ComponentType<
+    Pick<DiscountFormProps, "editing" | "groups" | "onSaved">
+  >;
+  /** The bound wire client, for host glue. */
+  api: DiscountsApiClient;
+  /** The bound formatters, for a host rendering a discount outside these screens. */
+  formatters: DiscountsFormatters;
+}
+
+/** Assert the config at construction, where the wiring is written. */
+function assertConfig(config: DiscountsWebConfig): void {
+  const missing = missingWebCopy(config.copy, PT_BR_DISCOUNTS_WEB_COPY);
+  if (missing.length > 0) {
+    throw new Error(
+      `@12-apps/discounts: createWebDiscounts is missing copy for ${missing.join(", ")} — ` +
+        "every sentence these screens render is host config, with no defaults.",
+    );
+  }
+  if (typeof config.onError !== "function") {
+    throw new Error(
+      "@12-apps/discounts: createWebDiscounts needs an onError — a surface whose " +
+        "failures reach nobody is indistinguishable from one that never fails.",
+    );
+  }
+}
+
+export function createWebDiscounts(config: DiscountsWebConfig): WebDiscounts {
+  assertConfig(config);
+  const { copy, onError, currencyField, breadcrumb } = config;
+  const formatters = createFormatters(config.locale, config.currency);
+  const transport = config.transport ?? httpDiscountsTransport(copy.form.saveFailed);
+  const api = createDiscountsApiClient(config.apiBase, transport, formatters);
+
+  const screenProps: DiscountsScreenProps = {
+    api,
+    copy,
+    formatters,
+    currencyField,
+    onError,
+    ...(breadcrumb ? { breadcrumb } : {}),
+  };
+
+  return {
+    Screen: () => <DiscountsScreen {...screenProps} />,
+    DiscountForm: (props) => (
+      <DiscountForm
+        api={api}
+        copy={copy}
+        formatters={formatters}
+        currencyField={currencyField}
+        onError={onError}
+        {...props}
+      />
+    ),
+    api,
+    formatters,
+  };
+}
+
+/**
+ * The same factory, memoised on config IDENTITY — the shape a host that must
+ * build inside a component should reach for.
+ *
+ * Not a substitute for building at module scope: `useMemo` keyed on the config
+ * object still rebuilds whenever that object is a fresh literal, which it is on
+ * every render unless the host memoised it too. It exists for the case where
+ * the mount path genuinely is dynamic (the api base carries a tenant slug from
+ * the router), and it makes the dependency explicit instead of silent.
+ */
+export function useWebDiscounts(config: DiscountsWebConfig): WebDiscounts {
+  return useMemo(() => createWebDiscounts(config), [config]);
+}
+
+/** The screen as a bare component, for a host that wires everything itself. */
+export type { DiscountsScreenProps };
+export function DiscountsSurface(props: DiscountsScreenProps): JSX.Element {
+  return <DiscountsScreen {...props} />;
+}