@aglyn/plugins-marketing 1.0.0-beta.199 → 1.0.0-beta.201

package/src/lib/components/emails-list-card.js

@@ -20,34 +20,32 @@ import { pluginDocsHelp } from "@aglyn/aglyn";
 import { mdiBullhornOutline, mdiContentCopy, mdiDeleteOutline, mdiEyeOutline, mdiPaletteOutline } from "@aglyn/shared-data-mdi";
 import { AppLink, CardDisplay, MdiIcon, useConfirmationContext } from "@aglyn/shared-ui-jsx";
 import ListFilterChips from "@aglyn/shared-ui-jsx/components/list-filter-chips.component";
+import { ListPagination } from "@aglyn/shared-ui-jsx/components/list-pagination.component";
+import ListQueryNotices, { listQueryRefusals } from "@aglyn/shared-ui-jsx/components/list-query-notices.component";
 import { ListRowActions, ListTable, listActionsColumn } from "@aglyn/shared-ui-jsx/components/list-table.component";
-import { inMemoryListField } from "@aglyn/shared-ui-jsx/const/list-grid-filter";
-import { useListRowsFilter } from "@aglyn/shared-ui-jsx/hooks/use-list-rows-filter";
+import { hiddenFilterVisibility } from "@aglyn/shared-ui-jsx/const/list-filter";
+import { listFilterGridColumns } from "@aglyn/shared-ui-jsx/const/list-grid-filter";
+import { useListGridFilter } from "@aglyn/shared-ui-jsx/hooks/use-list-grid-filter";
 import { TABLE_ROW_HEIGHT } from "@aglyn/shared-ui-jsx/const/table-pagination";
 import { CreateArtifactDrawer } from "@aglyn/shared-ui-jsx-forms";
 import { useSnackbar } from "@aglyn/shared-ui-snackstack";
-import { ceilingedWindow, collectionCeiling } from "@aglyn/tenant-feature-instance/hooks/host-collection-queries";
+import { collectionCeiling } from "@aglyn/tenant-feature-instance/hooks/host-collection-queries";
+import { useListQuery } from "@aglyn/tenant-feature-instance/hooks/use-list-query";
 import { DUPLICATE_MENU_LABEL, useDuplicateResource, useFirestore, useFirestoreCollection } from "@aglyn/tenant-feature-instance";
-import { Alert, Button, Chip, Stack, Typography } from "@mui/material";
+import { Button, Chip, Stack, Typography } from "@mui/material";
 import { useRouter } from "next/navigation";
 import { useCallback, useMemo, useState } from "react";
 import { campaignPlacedOnHost, campaignSendDisplay, CAMPAIGN_SEND_CONTAINER_FIELD } from "@aglyn/shared-ui-email-campaigns/model/campaign-container";
 import { emailListTimeMs, emailSendTimeMs } from "@aglyn/shared-ui-email-campaigns/model/email-record";
 import { useCampaignManageApi, useCampaignSendApi } from "./use-campaign-send-api.js";
-import { EMAIL_STATE_FILTER_FIELD, EMAIL_STATE_OPTIONS, EMAIL_SUBJECT_FILTER_FIELD, emailFilterValues } from "./email-send-filter.js";
+import { CAMPAIGN_SEND_STATUS_OPTIONS, SINGLE_SEND_FILTER_VALUE, campaignEmailsListQuery, campaignSendsScope, emailCampaignQueryClauses } from "../model/campaign-list-query.js";
 import { useMarketingHubPath } from "./use-marketing-hub-path.js";
-import { campaignContainersQuery, campaignSendsQuery } from "./campaign-queries.js";
+import { campaignContainersQuery, campaignSendsCollection } from "./campaign-queries.js";
 import { orgSiteHubPath, orgSiteName, orgSiteOptions, useMarketingOrgId, useMarketingOrgMount } from "./marketing-org-mount.js";
-/** How many messages one read of this list covers. */ const EMAIL_CEILING = 30;
 /**
  * How many campaigns the Campaign filter and the create drawer offer — the
- * same read serves both.
+ * same read serves both. A picker's options, not a list.
  */ const CONTAINER_CEILING = 50;
-/**
- * The Campaign filter's value for an email filed under no campaign. An empty
- * value reads as "no value" to the filter, so a clause on it would never
- * apply; a sentinel is a value like any campaign id.
- */ const SINGLE_SEND_FILTER_VALUE = '__single__';
 /**
  * Why discard is refused, keyed by the state that refuses it.
  *
@@ -75,31 +73,22 @@ import { orgSiteHubPath, orgSiteName, orgSiteOptions, useMarketingOrgId, useMark
  * are neutral, because a finished send and a draft are not events.
  */ const STATE_COLOR = {
     sending: 'info',
-    stopped: 'warning'
+    stopped: 'warning',
+    // Waiting on staff, not on the merchant (AGL-3356): worth finding on a scan.
+    held: 'warning'
 };
 /*
- * What the messages grid's Filters panel offers (AGL-3317). The card reads
- * every message under its ceiling, so the panel and the search answer over
- * all of them. State is what the email is DOING (`campaignSendDisplay`),
- * not the status it stores.
- */ const EMAIL_FILTER_FIELDS = [
-    EMAIL_SUBJECT_FILTER_FIELD,
-    EMAIL_STATE_FILTER_FIELD,
-    // Matched on a derived key, so the row's own container field stays what
-    // was stored for the row menu that reads it.
-    inMemoryListField('emailCampaignId', 'select', 'campaignFilterKey'),
-    inMemoryListField('site', 'text', 'siteName')
-];
-const EMAIL_FILTER_HEADERS = {
+ * What the messages grid's Filters panel offers, each clause and the search
+ * on the list's Firestore query (AGL-3321, `campaignEmailsListQuery`). The
+ * State column is what the email is DOING (`campaignSendDisplay`), which no
+ * query can ask, so the panel offers the Status it STORES instead.
+ */ const EMAIL_FILTER_HEADERS = {
     subject: 'Subject',
-    state: 'State',
+    status: 'Status',
     emailCampaignId: 'Campaign',
-    site: 'Site'
+    site: 'Site',
+    createdAtMs: 'Created'
 };
-/** What the quick search reads on a message row. */ const EMAIL_SEARCH_FIELDS = [
-    'subjectText',
-    'siteName'
-];
 const emailsDocsHelp = pluginDocsHelp('emailCampaigns', {
     anchor: '#opens--clicks',
     excerpt: 'Every message this site has sent or has scheduled, each with its own ' + 'report: what was delivered, who opened it, and which links they followed.'
@@ -112,23 +101,19 @@ const emailsDocsHelp = pluginDocsHelp('emailCampaigns', {
  * 14th, and to whom" — and they were previously the same list because a
  * campaign document WAS a single send.
  *
- * ## Ordered in the browser, deliberately
- *
- * No SEND date is on every message: a sent one carries `sentAt` and a
- * scheduled one carries `sendAtMs`, written by two different branches of the
- * send path, and a draft carries neither — so `orderBy` on either would not
- * mis-sort this list, it would DROP half of it. `collectionCeiling` reads a
- * bounded window in document-id order and probes one past the ceiling, so the
- * rows are sorted here and the reader is told when there are more.
+ * ## Asked of Firestore, a page at a time
  *
- * Every writer stamps a `createdAtMs`, which is the field this list could be
- * ordered on in Firestore. Moving it there is a query change with the same
- * hazard as the two above — `orderBy` drops a document missing the field —
- * so it needs the corpus proven to carry one, not just the writers.
+ * No SEND date is on every message — a sent one carries `sentAt`, a
+ * scheduled one `sendAtMs`, a draft neither — so the list is ordered on
+ * `createdAtMs`, the one date every writer stamps when it mints a record
+ * (and `backfill-campaign-list-fields.mjs` stamped on the ones before).
+ * Newest first, paged by the query itself.
  *
- * The page is therefore a SLICE of a window this card already holds, not a
- * query: paging an id-ordered walk and re-sorting each page by date would run
- * in one order within a page and another across them.
+ * The Filters panel and the search box are the grid's; every clause and the
+ * search word go onto that ONE query (AGL-3321, `campaignEmailsListQuery`),
+ * so each page is a page of matches — an email that matches on page four is
+ * found — and a combination one query cannot hold is refused by name above
+ * the table, never answered over the rows that happen to be loaded.
  *
  * ## Under a site, and over the organization
  *
@@ -147,32 +132,34 @@ const emailsDocsHelp = pluginDocsHelp('emailCampaigns', {
     const siteMarketingHub = useMarketingHubPath();
     const marketingHub = orgMount ? orgMount.basePath : siteMarketingHub;
     const router = useRouter();
-    const { data: emailDocs } = useFirestoreCollection(()=>{
-        const sends = campaignSendsQuery(firestore, orgId, hostId);
-        return sends ? collectionCeiling(sends, EMAIL_CEILING) : null;
-    }, [
-        firestore,
-        orgId,
-        hostId
-    ], {
+    /*
+   * The Filters panel and the search, bound to the grid. Held here rather
+   * than in a saved view: this list keeps no views.
+   */ const declaration = campaignEmailsListQuery(!hostId);
+    const gridFilter = useListGridFilter({
+        selectFields: [
+            'status',
+            'emailCampaignId',
+            'site'
+        ]
+    });
+    const emailPage = useListQuery({
+        collection: campaignSendsCollection(firestore, orgId),
+        declaration,
+        request: {
+            clauses: emailCampaignQueryClauses(gridFilter.clauses),
+            search: gridFilter.searchWords,
+            base: campaignSendsScope(hostId)
+        },
+        deps: [
+            firestore,
+            orgId,
+            hostId
+        ],
         idField: '$id'
     });
-    const { rows: readEmails, truncated } = ceilingedWindow(emailDocs, EMAIL_CEILING);
-    /*
-   * Newest first on the time each message SITS at — its send time where it
-   * has one, its creation where it does not.
-   *
-   * A draft has neither `sentAt` nor `sendAtMs`, so sorting on the send time
-   * alone gave every draft the key 0 and filed the email a merchant is in the
-   * middle of writing at the very bottom of the list, behind whatever paging
-   * it has. `emailListTimeMs` is the same ordering with that one gap closed;
-   * a SENT message still orders by when it went out, never by when it was
-   * drafted.
-   */ const emails = useMemo(()=>[
-            ...readEmails
-        ].sort((a, b)=>emailListTimeMs(b) - emailListTimeMs(a)), [
-        readEmails
-    ]);
+    const emails = emailPage.rows;
+    const filtering = gridFilter.clauses.length > 0 || gridFilter.searchWords.some((word)=>word.trim());
     /*
    * A message's own pages, beneath the Emails page this list is on — the
    * site's or the organization's. A template is a site's design, so over the
@@ -183,11 +170,11 @@ const emailsDocsHelp = pluginDocsHelp('emailCampaigns', {
     /** The site a row is sent as, which every action on it must name. */ const rowHostId = useCallback((email)=>hostId != null ? hostId : (email == null ? void 0 : email.hostId) ? String(email.hostId) : null, [
         hostId
     ]);
-    const hostOfEmail = useMemo(()=>new Map(readEmails.map((email)=>[
+    const hostOfEmail = useMemo(()=>new Map(emails.map((email)=>[
                 String(email.$id),
                 (email == null ? void 0 : email.hostId) ? String(email.hostId) : null
             ])), [
-        readEmails
+        emails
     ]);
     const { confirm } = useConfirmationContext();
     const { enqueueSnackbar } = useSnackbar();
@@ -406,18 +393,8 @@ const emailsDocsHelp = pluginDocsHelp('emailCampaigns', {
             })).sort((a, b)=>a.label.localeCompare(b.label)), [
         campaignDocs
     ]);
-    const filterRows = useMemo(()=>emails.map((email)=>_extends({}, email, emailFilterValues(email), {
-                campaignFilterKey: email.emailCampaignId ? String(email.emailCampaignId) : SINGLE_SEND_FILTER_VALUE,
-                siteName: orgMount && (email == null ? void 0 : email.hostId) ? orgSiteName(orgMount, email.hostId) : ''
-            })), [
-        emails,
-        orgMount
-    ]);
-    const filterFields = useMemo(()=>orgMount ? EMAIL_FILTER_FIELDS : EMAIL_FILTER_FIELDS.filter((field)=>field.column !== 'site'), [
-        orgMount
-    ]);
-    const filterOptions = useMemo(()=>({
-            state: EMAIL_STATE_OPTIONS,
+    const filterOptions = useMemo(()=>_extends({
+            status: CAMPAIGN_SEND_STATUS_OPTIONS,
             emailCampaignId: [
                 {
                     value: SINGLE_SEND_FILTER_VALUE,
@@ -425,16 +402,13 @@ const emailsDocsHelp = pluginDocsHelp('emailCampaigns', {
                 },
                 ...campaignOptions
             ]
+        }, hostId ? {} : {
+            site: orgSites
         }), [
-        campaignOptions
+        campaignOptions,
+        hostId,
+        orgSites
     ]);
-    const listFilter = useListRowsFilter({
-        rows: filterRows,
-        fields: filterFields,
-        options: filterOptions,
-        headers: EMAIL_FILTER_HEADERS,
-        search: EMAIL_SEARCH_FIELDS
-    });
     /*==========================================
    * CREATE, THEN GO TO THE EMAIL'S OWN PAGE.
    *
@@ -520,9 +494,9 @@ const emailsDocsHelp = pluginDocsHelp('emailCampaigns', {
         router
     ]);
     /*
-   * One row per message, in the order above; the whole window is in hand, so
-   * the grid pages it. The subject is a link AND the row opens the report: a
-   * click handler cannot be middle-clicked or opened in a new tab.
+   * One row per message, in the query's order. The subject is a link AND the
+   * row opens the report: a click handler cannot be middle-clicked or opened
+   * in a new tab.
    */ const columns = [
         {
             field: 'subject',
@@ -573,8 +547,6 @@ const emailsDocsHelp = pluginDocsHelp('emailCampaigns', {
             field: 'when',
             headerName: 'When',
             width: 190,
-            // Sorted on the time the list is ordered by, so a draft sorts by its
-            // creation rather than as the oldest thing on the page.
             valueGetter: (_value, row)=>emailListTimeMs(row),
             renderCell: ({ row })=>{
                 const at = emailSendTimeMs(row);
@@ -615,6 +587,8 @@ const emailsDocsHelp = pluginDocsHelp('emailCampaigns', {
             width: 72
         })
     ];
+    const gridColumns = listFilterGridColumns(columns, declaration.fields, filterOptions, EMAIL_FILTER_HEADERS);
+    /** Nothing stored at all — not a filter that matched nothing. */ const none = emailPage.status !== 'loading' && emails.length === 0 && !filtering && emailPage.page === 0;
     return /*#__PURE__*/ _jsxs(CardDisplay, {
         header: 'Messages',
         help: emailsDocsHelp,
@@ -630,52 +604,77 @@ const emailsDocsHelp = pluginDocsHelp('emailCampaigns', {
         contentGutterY: true,
         children: [
             duplicate.dialog,
-            /*#__PURE__*/ _jsxs(Stack, {
+            /*#__PURE__*/ _jsx(Stack, {
                 spacing: 2,
-                children: [
-                    emails.length === 0 ? /*#__PURE__*/ _jsxs(Stack, {
-                        spacing: 2,
-                        sx: {
-                            alignItems: 'flex-start'
-                        },
-                        children: [
-                            /*#__PURE__*/ _jsx(Typography, {
-                                variant: "body2",
-                                color: "text.secondary",
-                                children: 'Nothing has been sent or scheduled yet. Write one here, or ' + 'from a campaign, and it appears in this list with its own ' + 'report.'
+                children: none ? /*#__PURE__*/ _jsxs(Stack, {
+                    spacing: 2,
+                    sx: {
+                        alignItems: 'flex-start'
+                    },
+                    children: [
+                        /*#__PURE__*/ _jsx(Typography, {
+                            variant: "body2",
+                            color: "text.secondary",
+                            children: 'Nothing has been sent or scheduled yet. Write one here, or ' + 'from a campaign, and it appears in this list with its own ' + 'report.'
+                        }),
+                        /*#__PURE__*/ _jsx(Button, {
+                            variant: "contained",
+                            onClick: ()=>setCreateOpen(true),
+                            children: 'New email'
+                        })
+                    ]
+                }) : /*#__PURE__*/ _jsxs(_Fragment, {
+                    children: [
+                        /*#__PURE__*/ _jsx(ListFilterChips, {
+                            fields: declaration.fields,
+                            headers: EMAIL_FILTER_HEADERS,
+                            clauses: gridFilter.clauses,
+                            onChange: gridFilter.setClauses,
+                            options: filterOptions
+                        }),
+                        /*#__PURE__*/ _jsx(ListQueryNotices, {
+                            refused: listQueryRefusals(emailPage.plan.refused, {
+                                fields: declaration.fields,
+                                headers: EMAIL_FILTER_HEADERS,
+                                options: filterOptions
                             }),
-                            /*#__PURE__*/ _jsx(Button, {
-                                variant: "contained",
-                                onClick: ()=>setCreateOpen(true),
-                                children: 'New email'
-                            })
-                        ]
-                    }) : /*#__PURE__*/ _jsxs(_Fragment, {
-                        children: [
-                            /*#__PURE__*/ _jsx(ListFilterChips, _extends({}, listFilter.chipsProps)),
-                            /*#__PURE__*/ _jsx(ListTable, _extends({
-                                "aria-label": "Messages",
-                                rows: listFilter.rows,
-                                columns: listFilter.filterColumns(columns),
-                                rowHeight: TABLE_ROW_HEIGHT,
-                                onOpen: (_id, row)=>router.push(emailHref(row))
-                            }, listFilter.gridProps, {
-                                initialState: {
-                                    columns: {
-                                        columnVisibilityModel: {
-                                            emailCampaignId: false
-                                        }
-                                    }
-                                },
-                                noRowsLabel: "No messages match these filters"
-                            }))
-                        ]
-                    }),
-                    truncated ? /*#__PURE__*/ _jsx(Alert, {
-                        severity: "info",
-                        children: `Showing ${EMAIL_CEILING} messages. ${hostId ? 'This site' : 'This organization'} has sent or ` + 'scheduled more than that, and the rest are not in this list.'
-                    }) : null
-                ]
+                            notices: emailPage.plan.notices
+                        }),
+                        /*#__PURE__*/ _jsx(ListTable, {
+                            "aria-label": "Messages",
+                            rows: emails,
+                            columns: gridColumns,
+                            rowHeight: TABLE_ROW_HEIGHT,
+                            onOpen: (_id, row)=>router.push(emailHref(row)),
+                            loading: emailPage.status === 'loading',
+                            /*
+               * The panel and the search are the grid's; every clause and
+               * the search word are on the list's query (AGL-3321), and the
+               * grid neither filters nor sorts the page it is handed: the
+               * query's one order, newest first, is the list's.
+               */ filterMode: "server",
+                            filterModel: gridFilter.filterModel,
+                            onFilterModelChange: gridFilter.onFilterModelChange,
+                            quickFilter: true,
+                            disableColumnSorting: true,
+                            hideFooter: true,
+                            initialState: {
+                                columns: {
+                                    columnVisibilityModel: hiddenFilterVisibility(declaration.fields, columns.map((column)=>column.field))
+                                }
+                            },
+                            noRowsLabel: "No messages match these filters"
+                        }),
+                        /*#__PURE__*/ _jsx(ListPagination, {
+                            page: emailPage.page,
+                            pageSize: emailPage.pageSize,
+                            rowCount: emails.length,
+                            hasMore: emailPage.hasMore,
+                            onPageChange: emailPage.setPage,
+                            onPageSizeChange: emailPage.setPageSize
+                        })
+                    ]
+                })
             }),
             /*#__PURE__*/ _jsx(CreateArtifactDrawer, {
                 open: createOpen,