@12-apps/discounts 1.2.0 → 1.3.0

package/src/react/discount-actions-menu.tsx

@@ -0,0 +1,127 @@
+"use client";
+
+import { useState, type JSX } from "react";
+
+import { CardKebab, useCardActions, useRemoveConfirm } from "@12-apps/ui/data-display/CardKit";
+import { Dialog, DialogContent } from "@12-apps/ui/feedback/Dialog";
+import type { DropdownMenuItem } from "@12-apps/ui/navigation/DropdownMenu";
+
+import type { DiscountsApiClient, WireTargetGroup } from "./api";
+import type { DiscountsWebCopy } from "./copy";
+import { DiscountForm } from "./discount-form";
+import type { CurrencyFieldComponent } from "./discount-form-fields";
+import type { DiscountsFormatters } from "./format";
+import type { DiscountListItem } from "./row";
+
+/**
+ * One rule's self-contained "⋮" menu: it owns its edit dialog inline and its
+ * delete write, reading the refresh and the error channel from
+ * `CardActionsProvider`.
+ *
+ * Reused by BOTH the grid row and the card, so the two can never offer a
+ * different set of actions — which is the whole reason it is one component
+ * rather than a menu per surface.
+ *
+ * There is deliberately no version-history entry. A discount is not versioned
+ * catalog content: restoring "version 3" of a coupon whose redemption counter
+ * has since moved is meaningless, so the surface does not offer it.
+ */
+
+export interface DiscountActionsMenuProps {
+  row: DiscountListItem;
+  api: DiscountsApiClient;
+  copy: DiscountsWebCopy;
+  formatters: DiscountsFormatters;
+  currencyField: CurrencyFieldComponent;
+  /**
+   * The registered collections, for the edit form's target pickers.
+   *
+   * Optional, and the absence is a real state rather than an oversight: while
+   * they are still loading, only DELETE is offered — an edit form opened
+   * without them would show empty pickers, and saving would silently clear a
+   * target list it never had the chance to display.
+   */
+  groups?: readonly WireTargetGroup[];
+  onError: (error: unknown, context: string) => void;
+}
+
+export function DiscountActionsMenu({
+  row,
+  api,
+  copy,
+  formatters,
+  currencyField,
+  groups,
+  onError,
+}: DiscountActionsMenuProps): JSX.Element {
+  const { onRefresh } = useCardActions();
+  const [editOpen, setEditOpen] = useState(false);
+  const canEdit = groups !== undefined;
+
+  const remove = useRemoveConfirm({
+    write: async () => {
+      const result = await api.remove(row.id);
+      if (!result.ok) onError(result, "discounts.delete");
+      return result;
+    },
+    title: copy.actions.deleteTitle,
+    entityName: row.name,
+    description: copy.actions.deleteDescription,
+    confirmText: copy.actions.delete,
+    fallbackError: copy.actions.deleteFailed,
+    dataTestId: "discount-delete-confirm",
+  });
+
+  const items: DropdownMenuItem[] = [];
+  if (canEdit) {
+    items.push({ id: "edit", label: copy.actions.edit, onClick: () => setEditOpen(true) });
+  }
+  items.push({
+    id: "delete",
+    label: copy.actions.delete,
+    color: "danger",
+    onClick: remove.request,
+  });
+
+  return (
+    <>
+      <CardKebab
+        items={items}
+        menuLabel={copy.actions.menu}
+        dataTestId={`discount-actions-${row.id}`}
+      />
+      {remove.dialog}
+      {canEdit && (
+        <Dialog
+          open={editOpen}
+          onClose={() => setEditOpen(false)}
+          title={copy.form.editTitle}
+          size="md"
+          showCloseButton
+          dataTestId="discount-dialog"
+        >
+          {/* Mounted only while open, so the next open re-seeds from the row
+              instead of keeping the last attempt's values. */}
+          {editOpen && (
+            <DialogContent>
+              <DiscountForm
+                key={row.id}
+                api={api}
+                copy={copy}
+                formatters={formatters}
+                currencyField={currencyField}
+                groups={groups}
+                editing={row.record}
+                onError={onError}
+                onSaved={() => {
+                  setEditOpen(false);
+                  onRefresh();
+                }}
+              />
+            </DialogContent>
+          )}
+        </Dialog>
+      )}
+    </>
+  );
+}

package/src/react/discount-card.tsx

@@ -0,0 +1,92 @@
+"use client";
+
+import type { JSX } from "react";
+
+import LocalOfferOutlinedIcon from "@mui/icons-material/LocalOfferOutlined";
+
+import type { KindCardProps } from "@12-apps/ui/data-display/CardKit";
+import { BaseCard } from "@12-apps/ui/data-display/DataViews";
+import { Chip } from "@12-apps/ui/data-display/Chip";
+import { Box } from "@12-apps/ui/mui/Box";
+
+import type { DiscountsWebCopy } from "./copy";
+import { DiscountActionsMenu, type DiscountActionsMenuProps } from "./discount-actions-menu";
+import type { DiscountListItem } from "./row";
+
+/**
+ * One rule as a tile for the grid's card layout.
+ *
+ * The subtitle carries the two numbers an operator scans a promotions board
+ * for: what it takes off, and how long it runs. The chips carry the two facts
+ * that decide WHERE and WHEN it fires. "Paused" is shown only when true —
+ * a card shouting "Active" on every tile would make the one paused promotion
+ * harder to spot, not easier.
+ */
+
+/** The semantic colour a scope's chip carries. Not copy: it is a token. */
+const SCOPE_COLOR: Record<string, "neutral" | "warning" | "success" | "info"> = {
+  ORDER: "neutral",
+  CATEGORY: "warning",
+  ITEM: "success",
+  COMBO: "info",
+};
+
+const TRIGGER_COLOR: Record<string, "success" | "info"> = {
+  AUTOMATIC: "success",
+  CODE: "info",
+};
+
+type DiscountCardProps = KindCardProps &
+  Omit<DiscountActionsMenuProps, "row"> & { row: DiscountListItem };
+
+export function DiscountCard({
+  row,
+  selection,
+  aspectRatio,
+  copy,
+  ...menu
+}: DiscountCardProps & { copy: DiscountsWebCopy }): JSX.Element {
+  const scopeLabel = copy.labels.scope[row.scope as keyof typeof copy.labels.scope] ?? row.scope;
+  const triggerLabel =
+    copy.labels.trigger[row.trigger as keyof typeof copy.labels.trigger] ?? row.trigger;
+  return (
+    <BaseCard
+      aspectRatio={aspectRatio ?? "4:3"}
+      scale={selection.scale}
+      selected={selection.selected}
+      onToggleSelect={selection.onToggleSelect}
+      testId={`discount-card-${row.id}`}
+      title={row.name}
+      subtitle={`${row.valueLabel} · ${row.windowLabel}`}
+      imageFallback={<LocalOfferOutlinedIcon sx={{ fontSize: 40, opacity: 0.35 }} />}
+      menu={<DiscountActionsMenu row={row} copy={copy} {...menu} />}
+    >
+      <Box sx={{ display: "flex", gap: 0.5, flexWrap: "wrap" }}>
+        <Chip
+          label={scopeLabel}
+          size="sm"
+          variant="filled"
+          color={SCOPE_COLOR[row.scope] ?? "neutral"}
+          dataTestId={`discount-card-scope-${row.id}`}
+        />
+        <Chip
+          // A coupon identifies itself; the word "code" beside a code says less.
+          label={row.trigger === "CODE" ? (row.code ?? triggerLabel) : triggerLabel}
+          size="sm"
+          variant="outlined"
+          color={TRIGGER_COLOR[row.trigger] ?? "neutral"}
+          dataTestId={`discount-card-trigger-${row.id}`}
+        />
+        {!row.active && (
+          <Chip
+            label={copy.card.paused}
+            size="sm"
+            variant="outlined"
+            color="neutral"
+            dataTestId={`discount-card-paused-${row.id}`}
+          />
+        )}
+      </Box>
+    </BaseCard>
+  );
+}

package/src/react/discount-form-fields.tsx

@@ -0,0 +1,174 @@
+"use client";
+
+import type { JSX } from "react";
+
+import { Switch } from "@12-apps/ui/form/Switch";
+import { Fields, 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 { DISCOUNT_SCOPES, DISCOUNT_TRIGGERS, DISCOUNT_TYPES } from "../engine/kinds";
+
+import type { DiscountsWebCopy } from "./copy";
+
+/**
+ * The form's inputs, split from the form itself for the 400-line file gate —
+ * comments count toward it, and the container plus these would not fit.
+ *
+ * Every option list is built FROM the vocabulary arrays rather than spelled out
+ * again: those arrays back the database's CHECK constraints, so an option an
+ * operator can pick is by construction a value the column will store. A
+ * hand-written list is how a form offers a fifth type the database refuses.
+ */
+
+/** One closed set as a toggle's options, labelled by the pack. */
+function optionsFor<TKey extends string>(
+  values: readonly TKey[],
+  labels: Readonly<Record<TKey, string>>,
+): { value: string; label: string }[] {
+  return values.map((value) => ({ value, label: labels[value] }));
+}
+
+/** Percentage or amount — whichever the chosen type actually stores. */
+function ValueField({
+  copy,
+  currencyField,
+}: {
+  copy: DiscountsWebCopy;
+  currencyField: CurrencyFieldComponent;
+}): JSX.Element {
+  const { values } = useFormContext();
+  const Currency = currencyField;
+  if (values.type === "FIXED_AMOUNT") {
+    return <Currency name="amountOff" label={copy.form.amountOff} />;
+  }
+  return (
+    <Fields.TextField
+      name="percentOff"
+      label={copy.form.percentOff}
+      placeholder={copy.form.percentPlaceholder}
+    />
+  );
+}
+
+/**
+ * A money input, supplied by the host.
+ *
+ * Currency entry is a host decision — masking, the symbol's side, whether cents
+ * are typed or implied — and `@12-apps/ui` has no opinionated one. So the
+ * surface takes the component rather than shipping a guess; a host with nothing
+ * special passes a plain text field.
+ */
+export type CurrencyFieldComponent = (props: { name: string; label: string }) => JSX.Element;
+
+/** The coupon input, shown only for a CODE-triggered rule. */
+function CodeField({ copy }: { copy: DiscountsWebCopy }): JSX.Element | null {
+  const { values } = useFormContext();
+  if (values.trigger !== "CODE") return null;
+  return (
+    <Fields.TextField
+      name="code"
+      label={copy.form.code}
+      placeholder={copy.form.codePlaceholder}
+    />
+  );
+}
+
+/** Type + value + trigger + code, the four that decide WHAT and HOW. */
+export function RuleFields({
+  copy,
+  currencyField,
+}: {
+  copy: DiscountsWebCopy;
+  currencyField: CurrencyFieldComponent;
+}): JSX.Element {
+  return (
+    <Box sx={{ display: "grid", gap: 2, gridTemplateColumns: { xs: "1fr", sm: "1fr 1fr" } }}>
+      <Fields.ToggleField
+        name="type"
+        label={copy.form.type}
+        options={optionsFor(DISCOUNT_TYPES, copy.labels.type)}
+      />
+      <ValueField copy={copy} currencyField={currencyField} />
+      <Fields.ToggleField
+        name="trigger"
+        label={copy.form.trigger}
+        options={optionsFor(DISCOUNT_TRIGGERS, copy.labels.trigger)}
+      />
+      <CodeField copy={copy} />
+    </Box>
+  );
+}
+
+/** The scope toggle, which decides which target picker is shown below it. */
+export function ScopeField({ copy }: { copy: DiscountsWebCopy }): JSX.Element {
+  return (
+    <Fields.ToggleField
+      name="scope"
+      label={copy.form.scope}
+      options={optionsFor(DISCOUNT_SCOPES, copy.labels.scope)}
+    />
+  );
+}
+
+/** The active window. Both sides optional; the end date is EXCLUSIVE. */
+export function WindowFields({ copy }: { copy: DiscountsWebCopy }): JSX.Element {
+  return (
+    <Box sx={{ display: "grid", gap: 2, gridTemplateColumns: { xs: "1fr", sm: "1fr 1fr" } }}>
+      <Fields.TextField name="startsAt" label={copy.form.startsAt} type="date" />
+      <Fields.TextField name="endsAt" label={copy.form.endsAt} type="date" />
+    </Box>
+  );
+}
+
+/** The minimum basket and the two redemption caps. */
+export function LimitFields({
+  copy,
+  currencyField,
+}: {
+  copy: DiscountsWebCopy;
+  currencyField: CurrencyFieldComponent;
+}): JSX.Element {
+  const Currency = currencyField;
+  return (
+    <Box sx={{ display: "grid", gap: 2, gridTemplateColumns: { xs: "1fr", sm: "1fr 1fr 1fr" } }}>
+      <Currency name="minSubtotal" label={copy.form.minSubtotal} />
+      <Fields.TextField name="usageLimit" label={copy.form.usageLimit} type="number" />
+      <Fields.TextField name="perBuyerLimit" label={copy.form.perBuyerLimit} type="number" />
+    </Box>
+  );
+}
+
+/** The two booleans, owned by the parent so submit can send them. */
+export function DiscountSwitches({
+  copy,
+  active,
+  stackable,
+  onActive,
+  onStackable,
+}: {
+  copy: DiscountsWebCopy;
+  active: boolean;
+  stackable: boolean;
+  onActive: (next: boolean) => void;
+  onStackable: (next: boolean) => void;
+}): JSX.Element {
+  return (
+    <Stack spacing={1}>
+      <Switch
+        checked={active}
+        onChange={(event) => onActive(event.target.checked)}
+        label={copy.form.active}
+        description={copy.form.activeHint}
+        dataTestId="discount-active"
+      />
+      <Switch
+        checked={stackable}
+        onChange={(event) => onStackable(event.target.checked)}
+        label={copy.form.stackable}
+        description={copy.form.stackableHint}
+        dataTestId="discount-stackable"
+      />
+    </Stack>
+  );
+}

package/src/react/discount-form.tsx

@@ -0,0 +1,272 @@
+"use client";
+
+import { useState, type JSX } from "react";
+
+import { minLength, required } from "@12-apps/forms-core";
+import { Alert } from "@12-apps/ui/data-display/Alert";
+import {
+  Fields,
+  FormContainer,
+  FormErrorSnackbar,
+  SubmitButton,
+} from "@12-apps/ui/form/total-form";
+import { Stack } from "@12-apps/ui/mui/Stack";
+
+import type { DiscountFormPayload, DiscountsApiClient, DiscountWireRecord, WireTargetGroup } from "./api";
+import type { DiscountsWebCopy } from "./copy";
+import {
+  DiscountSwitches,
+  LimitFields,
+  RuleFields,
+  ScopeField,
+  WindowFields,
+  type CurrencyFieldComponent,
+} from "./discount-form-fields";
+import { DiscountTargetPicker } from "./discount-target-picker";
+import type { DiscountsFormatters } from "./format";
+
+/**
+ * The create/edit form — shared by the header's create dialog and the row
+ * menu's edit dialog, so the fields and the submit live in one place.
+ * `editing === null` creates; otherwise it re-states the rule whole.
+ *
+ * Two kinds of value are deliberately NOT `total-form` values, for one reason:
+ * `total-form` holds STRINGS. The two switches (booleans) and the target id
+ * lists (arrays) sit in local state beside the container and are merged in at
+ * submit.
+ *
+ * Every rule checked here is ALSO checked on the server. This half exists for
+ * the operator's sake — instant, field-attached feedback — never as the
+ * authority: the surface re-validates, and a server refusal comes back through
+ * `setFieldErrors` and paints the same inputs red.
+ */
+
+interface DiscountFormValues extends Record<string, string> {
+  name: string;
+  type: string;
+  percentOff: string;
+  amountOff: 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: "",
+  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),
+    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),
+  };
+}
+
+/** The value half: a rate in (0, 100], or an amount above zero. */
+function checkValue(
+  values: DiscountFormValues,
+  formatters: DiscountsFormatters,
+  copy: DiscountsWebCopy,
+): Record<string, string> {
+  if (values.type === "PERCENTAGE") {
+    const percent = formatters.parseDecimal(values.percentOff);
+    if (percent === null || percent <= 0 || percent > 100) {
+      return { percentOff: copy.form.invalidPercent };
+    }
+    return {};
+  }
+  const amount = formatters.parseDecimal(values.amountOff);
+  return amount === null || amount <= 0 ? { amountOff: copy.form.invalidAmount } : {};
+}
+
+/** The cross-field rules a per-input schema cannot express. */
+function validate(
+  values: DiscountFormValues,
+  targets: { categoryIds: string[]; menuItemIds: string[] },
+  formatters: DiscountsFormatters,
+  copy: DiscountsWebCopy,
+): Record<string, string> {
+  const errors: Record<string, string> = { ...checkValue(values, formatters, 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);
+  const [stackable, setStackable] = useState<boolean>(editing?.stackable ?? true);
+  const [categoryIds, setCategoryIds] = useState<string[]>(editing?.categoryIds ?? []);
+  const [menuItemIds, setMenuItemIds] = useState<string[]>(editing?.menuItemIds ?? []);
+  return {
+    active,
+    stackable,
+    categoryIds,
+    menuItemIds,
+    setActive,
+    setStackable,
+    setCategoryIds,
+    setMenuItemIds,
+  };
+}
+
+type NonStringState = ReturnType<typeof useNonStringState>;
+type SubmitHelpers = { setFieldErrors: (errors: Record<string, string | undefined>) => void };
+
+export interface DiscountFormProps {
+  api: DiscountsApiClient;
+  copy: DiscountsWebCopy;
+  formatters: DiscountsFormatters;
+  currencyField: CurrencyFieldComponent;
+  groups: readonly WireTargetGroup[];
+  editing: DiscountWireRecord | null;
+  onSaved: () => void;
+  /** Where a refused or failed write is reported, beyond the operator's screen. */
+  onError: (error: unknown, context: string) => void;
+}
+
+/**
+ * Build the submit handler.
+ *
+ * A factory rather than a closure inside the component, so the component stays
+ * inside the size gate and the validate → send → attribute-the-failure sequence
+ * reads as one block.
+ */
+function makeSubmit(
+  props: DiscountFormProps,
+  extra: NonStringState,
+  setError: (message: string | null) => void,
+): (values: DiscountFormValues, helpers: SubmitHelpers) => Promise<void> {
+  const { api, copy, formatters, editing, onSaved, onError } = props;
+  return async function handleSubmit(values, { setFieldErrors }): Promise<void> {
+    setError(null);
+    const targets = { categoryIds: extra.categoryIds, menuItemIds: extra.menuItemIds };
+    const invalid = validate(values, targets, formatters, copy);
+    if (Object.keys(invalid).length > 0) {
+      setFieldErrors(invalid);
+      setError(copy.form.reviewFields);
+      return;
+    }
+    const payload: DiscountFormPayload = {
+      ...values,
+      ...targets,
+      stackable: extra.stackable,
+      active: extra.active,
+    };
+    const result = editing
+      ? await api.update(editing.id, payload)
+      : await api.create(payload);
+    if (result.ok) {
+      onSaved();
+      return;
+    }
+    setError(result.error);
+    // The server attributes what it can — a duplicate code, a rate out of range
+    // — so highlight those inputs instead of only showing the banner.
+    if (result.fieldErrors) setFieldErrors(result.fieldErrors);
+    onError(result, editing ? "discounts.update" : "discounts.create");
+  };
+}
+
+export function DiscountForm(props: DiscountFormProps): JSX.Element {
+  const { copy, formatters, currencyField, groups, editing } = props;
+  const [error, setError] = useState<string | null>(null);
+  const extra = useNonStringState(editing);
+  const handleSubmit = makeSubmit(props, extra, setError);
+
+  return (
+    <FormContainer<DiscountFormValues>
+      initialValues={initialValues(editing, formatters)}
+      schema={{ name: [required(copy.form.nameRequired), minLength(2)] }}
+      onSubmit={handleSubmit}
+      dataTestId="discount-form"
+    >
+      <Stack spacing={2}>
+        <Fields.TextField name="name" label={copy.form.name} />
+        <RuleFields copy={copy} currencyField={currencyField} />
+        <ScopeField copy={copy} />
+        <DiscountTargetPicker
+          groups={groups}
+          copy={copy}
+          selection={{
+            categoryIds: extra.categoryIds,
+            menuItemIds: extra.menuItemIds,
+            onCategoryIdsChange: extra.setCategoryIds,
+            onMenuItemIdsChange: extra.setMenuItemIds,
+          }}
+        />
+        <WindowFields copy={copy} />
+        <LimitFields copy={copy} currencyField={currencyField} />
+        <DiscountSwitches
+          copy={copy}
+          active={extra.active}
+          stackable={extra.stackable}
+          onActive={extra.setActive}
+          onStackable={extra.setStackable}
+        />
+        {error && (
+          <Alert
+            variant="danger"
+            title={copy.form.saveFailed}
+            description={error}
+            data-testid="discount-form-error"
+          />
+        )}
+        <SubmitButton dataTestId="discount-form-submit">
+          {editing ? copy.form.submitEdit : copy.form.submitCreate}
+        </SubmitButton>
+      </Stack>
+      <FormErrorSnackbar />
+    </FormContainer>
+  );
+}