@12-apps/discounts 1.2.0 → 1.3.0

package/src/react/discount-list-card.tsx

@@ -0,0 +1,199 @@
+"use client";
+
+import type { JSX } from "react";
+
+import LocalOfferOutlinedIcon from "@mui/icons-material/LocalOfferOutlined";
+
+import {
+  BodyHeading,
+  DetailColumns,
+  Fact,
+  TagList,
+  type KindListCardProps,
+} from "@12-apps/ui/data-display/CardKit";
+import { Chip } from "@12-apps/ui/data-display/Chip";
+import {
+  BaseListCard,
+  type ListCardCellConfig,
+} from "@12-apps/ui/data-display/DataViews";
+
+import type { WireTarget, WireTargetGroup } from "./api";
+import { fill, type DiscountsWebCopy } from "./copy";
+import { DiscountActionsMenu, type DiscountActionsMenuProps } from "./discount-actions-menu";
+import { EMPTY, type DiscountsFormatters } from "./format";
+import type { DiscountListItem } from "./row";
+
+/**
+ * One rule as a full-width row, with an expanded body.
+ *
+ * The reason this layout exists at all is the target list: a `string[]` has no
+ * honest table cell. Truncated to "3 items" it says nothing; printed in full it
+ * destroys the column. In an expanded body it simply wraps.
+ */
+
+/** `RUNNING` is the only good one; the other two are why a rule is not firing. */
+const WINDOW_COLOR: Record<string, "success" | "info" | "neutral"> = {
+  RUNNING: "success",
+  SCHEDULED: "info",
+  ENDED: "neutral",
+};
+
+/**
+ * Target ids resolved to names, falling back to the raw ID.
+ *
+ * The id IS the honest fallback. A rule can name a row that has since been
+ * deleted, and dropping it would show a scope of "Category" over an empty list
+ * — which reads as "applies to nothing" when it in fact still applies to
+ * whatever that id is.
+ */
+function targetNames(
+  ids: readonly string[],
+  groups: readonly WireTargetGroup[] | undefined,
+  targetType: string,
+): string[] {
+  const options: WireTarget[] =
+    groups?.find((group) => group.targetType === targetType)?.targets ?? [];
+  if (options.length === 0) return [...ids];
+  return ids.map((id) => options.find((option) => option.id === id)?.name ?? id);
+}
+
+/** How many rows this rule is pointed at, given its scope. */
+function targetCount(row: DiscountListItem): number {
+  if (row.scope === "CATEGORY") return row.categoryIds.length;
+  if (row.scope === "ITEM") return row.menuItemIds.length;
+  return 0;
+}
+
+/**
+ * Declared HERE and handed to the list's own config, and kept on the card too.
+ *
+ * Not redundancy. Inside a list group the group's config wins and the card's is
+ * ignored — that is what makes the columns line up by construction. Outside
+ * one, the card's own config is the only thing it has: a standalone row with
+ * neither falls back to the named slots and renders no summary at all.
+ */
+export function discountCells(copy: DiscountsWebCopy): ListCardCellConfig<DiscountListItem>[] {
+  return [
+    {
+      id: "discount",
+      primary: (row) => row.name,
+      secondary: (row) =>
+        row.code == null
+          ? (copy.labels.trigger[row.trigger as keyof typeof copy.labels.trigger] ?? row.trigger)
+          : fill(copy.card.withCode, { code: row.code }),
+    },
+    {
+      id: "where",
+      primary: (row) => copy.labels.scope[row.scope as keyof typeof copy.labels.scope] ?? row.scope,
+      secondary: (row) => {
+        if (row.scope === "ORDER") return copy.card.wholeOrder;
+        const count = targetCount(row);
+        return count === 1 ? copy.card.oneTarget : fill(copy.card.manyTargets, { count });
+      },
+    },
+    {
+      id: "window",
+      primary: (row) =>
+        copy.labels.window[row.windowState] ?? row.windowState,
+      secondary: (row) => row.windowLabel,
+    },
+    {
+      id: "value",
+      align: "end",
+      width: "max-content",
+      strong: true,
+      primary: (row) => row.valueLabel,
+    },
+  ];
+}
+
+/** The rule side: when it fires, how often, and whether it is running. */
+function RuleFacts({
+  row,
+  copy,
+  formatters,
+}: {
+  row: DiscountListItem;
+  copy: DiscountsWebCopy;
+  formatters: DiscountsFormatters;
+}): JSX.Element {
+  const cap = row.usageLimit === null ? copy.card.unlimited : String(row.usageLimit);
+  return (
+    <>
+      <BodyHeading>{copy.card.ruleHeading}</BodyHeading>
+      <Fact
+        label={copy.screen.columns.window}
+        value={
+          <Chip
+            label={copy.labels.window[row.windowState] ?? row.windowState}
+            size="sm"
+            variant={row.windowState === "RUNNING" ? "filled" : "outlined"}
+            color={WINDOW_COLOR[row.windowState] ?? "neutral"}
+          />
+        }
+      />
+      <Fact label={copy.card.usage} value={`${row.usageCount} / ${cap}`} />
+      <Fact label={copy.card.minSubtotal} value={formatters.money(row.minSubtotalCents)} />
+      <Fact
+        label={copy.card.perBuyerLimit}
+        value={row.perBuyerLimit === null ? copy.card.unlimited : String(row.perBuyerLimit)}
+      />
+      <Fact label={copy.screen.columns.code} value={row.code ?? EMPTY} />
+    </>
+  );
+}
+
+/** The targets side: what it actually covers. */
+function TargetFacts({
+  row,
+  copy,
+  groups,
+}: {
+  row: DiscountListItem;
+  copy: DiscountsWebCopy;
+  groups: readonly WireTargetGroup[] | undefined;
+}): JSX.Element {
+  const ids = row.scope === "CATEGORY" ? row.categoryIds : row.menuItemIds;
+  const names =
+    row.scope === "ORDER" ? [] : targetNames(ids, groups, row.scope === "CATEGORY" ? "CATEGORY" : "ITEM");
+  return (
+    <>
+      <BodyHeading>{copy.card.targetsHeading}</BodyHeading>
+      {row.scope === "ORDER" ? (
+        <Fact label={copy.screen.columns.scope} value={copy.card.wholeOrder} />
+      ) : (
+        <TagList items={names} empty={copy.card.noTargets} />
+      )}
+    </>
+  );
+}
+
+type DiscountListCardProps = KindListCardProps &
+  Omit<DiscountActionsMenuProps, "row"> & {
+    row: DiscountListItem;
+    copy: DiscountsWebCopy;
+  };
+
+export function DiscountListCard({
+  row,
+  selection,
+  copy,
+  ...menu
+}: DiscountListCardProps): JSX.Element {
+  return (
+    <BaseListCard
+      testId={`discount-list-card-${row.id}`}
+      selected={selection.selected}
+      onToggleSelect={selection.onToggleSelect}
+      cells={discountCells(copy) as readonly ListCardCellConfig<never>[]}
+      row={row}
+      leading={<LocalOfferOutlinedIcon sx={{ fontSize: 22, opacity: 0.5 }} />}
+      menu={<DiscountActionsMenu row={row} copy={copy} {...menu} />}
+    >
+      <DetailColumns
+        left={<RuleFacts row={row} copy={copy} formatters={menu.formatters} />}
+        right={<TargetFacts row={row} copy={copy} groups={menu.groups} />}
+      />
+    </BaseListCard>
+  );
+}

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

@@ -0,0 +1,159 @@
+"use client";
+
+import { useState, type JSX } from "react";
+
+import { Autocomplete } from "@12-apps/ui/form/Autocomplete";
+import { CategorySelect } from "@12-apps/ui/form/CategorySelect";
+import { FormControl, FormLabel, FormMessage } from "@12-apps/ui/form/Form";
+import { useFormContext } from "@12-apps/ui/form/total-form";
+
+import { fill, type DiscountsWebCopy } from "./copy";
+import type { WireTarget, WireTargetGroup } from "./api";
+
+/**
+ * What a scoped discount points at, picked from the host's own collections.
+ *
+ * There is no shared multi-select in `@12-apps/ui`, so this composes
+ * `Autocomplete` in multiple mode — chips plus type-to-filter, the same control
+ * `AddressAutocomplete` is built on. A collection that NESTS gets
+ * `CategorySelect` instead: a flat combobox would put a subcategory beside its
+ * parent with nothing to tell them apart.
+ *
+ * Which collections exist is not decided here. The surface reads them from
+ * `GET /discounts/targets`, which answers whatever the host registered — so
+ * adding a third discountable dimension is a host-side registration and this
+ * file does not change.
+ *
+ * The selection is held by the PARENT form, outside `FormContainer`, and merged
+ * in at submit: `total-form` values are strings and an id list is not one.
+ *
+ * The whole block renders `null` at ORDER scope. An order-wide discount covers
+ * everything, so a target list there is not "empty" — it is meaningless, and
+ * leaving a stale one on screen would suggest otherwise.
+ */
+
+/** One labelled multi-select of targets, with its own input-text state. */
+function TargetField({
+  label,
+  placeholder,
+  requiredMessage,
+  options,
+  ids,
+  onChange,
+  dataTestId,
+}: {
+  label: string;
+  placeholder: string;
+  requiredMessage: string;
+  options: WireTarget[];
+  ids: readonly string[];
+  onChange: (next: string[]) => void;
+  dataTestId: string;
+}): JSX.Element {
+  const [query, setQuery] = useState("");
+  const byId = new Map(options.map((option) => [option.id, option]));
+  // An id whose option is missing — a target archived since the rule was saved
+  // — still renders as a chip, so saving cannot silently drop it.
+  const selected = ids.map((id) => byId.get(id) ?? { id, name: id });
+
+  return (
+    <FormControl fullWidth>
+      <FormLabel error={ids.length === 0}>{label}</FormLabel>
+      <div data-testid={dataTestId}>
+        <Autocomplete<WireTarget>
+          multiple
+          value={query}
+          onChange={setQuery}
+          suggestions={options}
+          selectedItems={selected}
+          onSelectedItemsChange={(items) => onChange(items.map((item) => item.id))}
+          getKey={(option) => option.id}
+          getLabel={(option) => option.name}
+          placeholder={placeholder}
+          inputAriaLabel={label}
+        />
+      </div>
+      {ids.length === 0 && (
+        <FormMessage error dataTestId={`${dataTestId}-message`}>
+          {requiredMessage}
+        </FormMessage>
+      )}
+    </FormControl>
+  );
+}
+
+/** The ids currently chosen for one dimension. */
+interface DiscountTargetSelection {
+  categoryIds: string[];
+  menuItemIds: string[];
+  onCategoryIdsChange: (next: string[]) => void;
+  onMenuItemIdsChange: (next: string[]) => void;
+}
+
+/** Which selection a dimension reads and writes. */
+function bind(
+  targetType: string,
+  selection: DiscountTargetSelection,
+): { ids: string[]; onChange: (next: string[]) => void } {
+  if (targetType === "CATEGORY") {
+    return { ids: selection.categoryIds, onChange: selection.onCategoryIdsChange };
+  }
+  return { ids: selection.menuItemIds, onChange: selection.onMenuItemIdsChange };
+}
+
+/** The scope a collection's picker is shown at. */
+function scopeFor(targetType: string): string {
+  return targetType === "CATEGORY" ? "CATEGORY" : "ITEM";
+}
+
+/**
+ * The scope-driven target block.
+ *
+ * Reads the LIVE `scope` from the form context, so flipping the toggle swaps
+ * the picker immediately without the parent form having to mirror the value
+ * into its own state.
+ */
+export function DiscountTargetPicker({
+  groups,
+  copy,
+  selection,
+}: {
+  groups: readonly WireTargetGroup[];
+  copy: DiscountsWebCopy;
+  selection: DiscountTargetSelection;
+}): JSX.Element | null {
+  const { values } = useFormContext();
+  const scope = values.scope ?? "ORDER";
+  const group = groups.find((entry) => scopeFor(entry.targetType) === scope);
+  if (!group) return null;
+
+  const { ids, onChange } = bind(group.targetType, selection);
+  const label = fill(copy.targets.pick, { collection: group.label });
+  const dataTestId = `discount-${group.slug}-targets`;
+
+  if (group.nests) {
+    return (
+      <CategorySelect
+        label={label}
+        fullWidth
+        allowParentSelection
+        options={group.targets}
+        value={ids}
+        onChange={onChange}
+        error={ids.length === 0 ? copy.targets.required : undefined}
+        dataTestId={dataTestId}
+      />
+    );
+  }
+  return (
+    <TargetField
+      label={label}
+      placeholder={fill(copy.targets.search, { collection: group.label })}
+      requiredMessage={copy.targets.required}
+      options={group.targets}
+      ids={ids}
+      onChange={onChange}
+      dataTestId={dataTestId}
+    />
+  );
+}

package/src/react/discounts-screen.tsx

@@ -0,0 +1,314 @@
+"use client";
+
+import { useMemo, useState, type JSX } from "react";
+import { useSearchParams } from "react-router-dom";
+
+import AddIcon from "@mui/icons-material/Add";
+
+import { useServerDataViews } from "@12-apps/app-shell/react";
+import { CardActionsProvider, useRowConfirm } from "@12-apps/ui/data-display/CardKit";
+import { DataViewsGrid, type DataViewState } from "@12-apps/ui/data-display/DataViews";
+import type { RowAction } from "@12-apps/ui/data-display/DataViews";
+import { ErrorState } from "@12-apps/ui/data-display/ErrorState";
+import { LoadingState } from "@12-apps/ui/data-display/LoadingState";
+import { Dialog, DialogContent } from "@12-apps/ui/feedback/Dialog";
+import { HeaderButton } from "@12-apps/ui/form/HeaderButton";
+import { Dashboard } from "@12-apps/ui/layout/Dashboard";
+import { Text } from "@12-apps/ui/typography/Text";
+import { exportRows } from "@12-apps/ui/utils";
+
+import type { DiscountsApiClient } from "./api";
+import { fill, type DiscountsWebCopy } from "./copy";
+import { DiscountActionsMenu } from "./discount-actions-menu";
+import { DiscountCard } from "./discount-card";
+import { DiscountForm } from "./discount-form";
+import type { CurrencyFieldComponent } from "./discount-form-fields";
+import { DiscountListCard, discountCells } from "./discount-list-card";
+import type { DiscountsFormatters } from "./format";
+import { toListItem, type DiscountListItem } from "./row";
+import {
+  discountColumns,
+  discountExportColumns,
+  discountFilters,
+  discountsAppliedState,
+  discountsQueryToParams,
+  discountsSearch,
+} from "./table-config";
+import { useDiscountsData } from "./use-discounts-data";
+
+/**
+ * The promotions list: a grid in SERVER mode — the URL params ARE the query —
+ * a create dialog in the header, and a self-contained menu per row and card.
+ *
+ * No saved views, deliberately: a saved-view scope is a host registry entry and
+ * a database constraint, and a package cannot add either.
+ */
+
+export interface DiscountsScreenProps {
+  api: DiscountsApiClient;
+  copy: DiscountsWebCopy;
+  formatters: DiscountsFormatters;
+  currencyField: CurrencyFieldComponent;
+  onError: (error: unknown, context: string) => void;
+  /** The crumbs above the title. The host owns its own information hierarchy. */
+  breadcrumb?: readonly { label: string; href?: string }[];
+}
+
+/** The bulk delete's confirmation, described from the SELECTION. */
+function useBulkDelete(
+  api: DiscountsApiClient,
+  copy: DiscountsWebCopy,
+  refresh: () => void,
+  onError: (error: unknown, context: string) => void,
+) {
+  return useRowConfirm<DiscountListItem>({
+    write: async (rows) => {
+      const results = await Promise.all(rows.map((row) => api.remove(row.id)));
+      const failed = results.find((result) => !result.ok);
+      if (failed && !failed.ok) {
+        onError(failed, "discounts.delete");
+        // Throwing is what keeps the popup open carrying the message; the
+        // selection is still there to retry.
+        throw new Error(failed.error);
+      }
+      refresh();
+    },
+    describe: (rows) =>
+      rows.length === 1
+        ? {
+            title: copy.actions.deleteTitle,
+            entityName: rows[0]?.name,
+            description: copy.actions.deleteDescription,
+            confirmText: copy.actions.delete,
+          }
+        : {
+            title: fill(copy.actions.deleteManyTitle, { count: rows.length }),
+            description: copy.actions.deleteManyDescription,
+            confirmText: copy.actions.delete,
+          },
+    errorText: copy.actions.deleteFailed,
+    dataTestId: "discount-bulk-delete-confirm",
+  });
+}
+
+/** The header's controls: the explainer, the export, and the create button. */
+function HeaderControls({
+  rows,
+  copy,
+  onCreate,
+}: {
+  rows: DiscountListItem[];
+  copy: DiscountsWebCopy;
+  onCreate: () => void;
+}): JSX.Element {
+  return (
+    <>
+      <Dashboard.Info title={copy.screen.aboutTitle}>{copy.screen.aboutBody}</Dashboard.Info>
+      <Dashboard.Spacer />
+      <Dashboard.Export
+        formats={[
+          { id: "csv", label: "CSV (.csv)" },
+          { id: "json", label: "JSON (.json)" },
+        ]}
+        onExport={(format) =>
+          exportRows(
+            format === "json" ? "json" : "csv",
+            rows,
+            discountExportColumns(copy),
+            copy.screen.exportFileName,
+          )
+        }
+      />
+      <Dashboard.Action>
+        <HeaderButton
+          text={copy.screen.create}
+          icon={<AddIcon fontSize="small" />}
+          onClick={onCreate}
+          dataTestId="new-discount-button"
+        />
+      </Dashboard.Action>
+    </>
+  );
+}
+
+/** Everything the row menu, both cards and the edit form are bound to. */
+type MenuBinding = Omit<Parameters<typeof DiscountActionsMenu>[0], "row">;
+
+/**
+ * The grid, split from the page container so neither crosses the size gate.
+ *
+ * The row menu, the tile and the list row all receive the SAME binding, which
+ * is what keeps an edit opened from any of the three offering the same pickers.
+ */
+function DiscountsGrid({
+  rows,
+  copy,
+  menu,
+  appliedState,
+  server,
+  onVisibleRowsChange,
+  bulkDelete,
+}: {
+  rows: DiscountListItem[];
+  copy: DiscountsWebCopy;
+  menu: MenuBinding;
+  appliedState: DataViewState;
+  server: ReturnType<typeof useServerDataViews>;
+  onVisibleRowsChange: (next: DiscountListItem[]) => void;
+  bulkDelete: ReturnType<typeof useBulkDelete>;
+}): JSX.Element {
+  return (
+    <>
+      <DataViewsGrid<DiscountListItem>
+        inlineFilters
+        rows={rows}
+        columns={discountColumns(copy)}
+        fields={discountFilters(copy)}
+        appliedState={appliedState}
+        getRowId={(row) => row.id}
+        onVisibleRowsChange={onVisibleRowsChange}
+        dataTestId="discounts-grid"
+        testIdPrefix="discounts"
+        rowActions={
+          [
+            {
+              id: "delete",
+              label: copy.actions.delete,
+              color: "danger",
+              onSelect: (selected) => bulkDelete.request(selected),
+            },
+          ] satisfies RowAction<DiscountListItem>[]
+        }
+        renderRowMenu={(row) => <DiscountActionsMenu row={row} {...menu} />}
+        renderCard={(row, selection) => (
+          <DiscountCard row={row} selection={selection} {...menu} />
+        )}
+        renderListRow={(row, selection) => (
+          <DiscountListCard row={row} selection={selection} {...menu} />
+        )}
+        listGroup={{ cells: discountCells(copy) }}
+        server={server}
+        emptyState={
+          <Text variant="body" as="p">
+            {copy.screen.empty}
+          </Text>
+        }
+      />
+      {bulkDelete.dialog}
+    </>
+  );
+}
+
+/** The create dialog, mounted only while open so the next open re-seeds empty. */
+function CreateDialog({
+  open,
+  onClose,
+  onSaved,
+  menu,
+}: {
+  open: boolean;
+  onClose: () => void;
+  onSaved: () => void;
+  menu: MenuBinding;
+}): JSX.Element {
+  return (
+    <Dialog
+      open={open}
+      onClose={onClose}
+      title={menu.copy.form.createTitle}
+      size="md"
+      showCloseButton
+      dataTestId="discount-dialog"
+    >
+      {open && (
+        <DialogContent>
+          <DiscountForm
+            {...menu}
+            groups={menu.groups ?? []}
+            editing={null}
+            onSaved={onSaved}
+          />
+        </DialogContent>
+      )}
+    </Dialog>
+  );
+}
+
+export function DiscountsScreen(props: DiscountsScreenProps): JSX.Element {
+  const { api, copy, formatters, currencyField, onError, breadcrumb } = props;
+  const [searchParams] = useSearchParams();
+  const data = useDiscountsData(api, discountsSearch(searchParams), onError);
+  const [createOpen, setCreateOpen] = useState(false);
+  const [visibleRows, setVisibleRows] = useState<DiscountListItem[]>([]);
+  const bulkDelete = useBulkDelete(api, copy, data.refresh, onError);
+
+  // ONE instant for the whole render: two rows judged against two different
+  // "now"s could disagree about which of them is still running.
+  const rows = useMemo(() => {
+    const now = new Date();
+    return (data.page?.data ?? []).map((record) => toListItem(record, formatters, copy, now));
+  }, [data.page, formatters, copy]);
+
+  // Seeded ONCE from the URL. Re-applying it on every render would wipe the
+  // operator's column-visibility choices each time the query synced back.
+  const [appliedState] = useState<DataViewState>(() => discountsAppliedState(searchParams, copy));
+
+  const server = useServerDataViews({
+    totalCount: data.page?.pagination.total ?? 0,
+    page: data.page?.pagination.page ?? 1,
+    pageSize: data.page?.pagination.pageSize ?? 20,
+    toParams: discountsQueryToParams,
+  });
+
+  const menu: MenuBinding = { api, copy, formatters, currencyField, groups: data.groups, onError };
+
+  if (data.loading) return <LoadingState dataTestId="discounts-loading" />;
+  if (data.error !== null) {
+    return (
+      <ErrorState
+        title={copy.screen.loadFailed}
+        message={data.error}
+        retryLabel={copy.screen.retry}
+        onRetry={data.refresh}
+      />
+    );
+  }
+
+  return (
+    <Dashboard testIdPrefix="discounts-dashboard">
+      {breadcrumb && <Dashboard.Breadcrumb items={[...breadcrumb]} />}
+      <Dashboard.Header title={copy.screen.title}>
+        <HeaderControls rows={visibleRows} copy={copy} onCreate={() => setCreateOpen(true)} />
+      </Dashboard.Header>
+      <Dashboard.Body>
+        <CreateDialog
+          open={createOpen}
+          menu={menu}
+          onClose={() => setCreateOpen(false)}
+          onSaved={() => {
+            setCreateOpen(false);
+            data.refresh();
+          }}
+        />
+        <CardActionsProvider
+          // The menus read the refresh and the error channel from here; the
+          // tenant is already baked into `apiBase`, so there is nothing for a
+          // slug to do but be a second place it could disagree.
+          tenantSlug=""
+          onRefresh={data.refresh}
+          errorTitle={copy.actions.actionFailed}
+        >
+          <DiscountsGrid
+            rows={rows}
+            copy={copy}
+            menu={menu}
+            appliedState={appliedState}
+            server={server}
+            onVisibleRowsChange={setVisibleRows}
+            bulkDelete={bulkDelete}
+          />
+        </CardActionsProvider>
+      </Dashboard.Body>
+    </Dashboard>
+  );
+}