@aglyn/plugins-forms 1.0.0-beta.199 → 1.0.0-beta.200

package/src/lib/components/host-forms-card.component.js

@@ -17,120 +17,42 @@
 import { _ as _extends } from "@swc/helpers/_/_extends";
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import * as Aglyn from "@aglyn/aglyn";
-import { buildRoute, isFormArchived, PageHeaderActions, pluginDocsHelp, readCampaignIds, Route } from "@aglyn/aglyn";
+import { buildRoute, isFormArchived, PageHeaderActions, pluginDocsHelp, Route } from "@aglyn/aglyn";
 import { useConsoleWidgetSlot } from "@aglyn/aglyn/app-utils/console-widget-slot-context";
 import { ICON_VARIANT_SHOW_DETAIL } from "@aglyn/shared-data-enums";
 import { mdiArchiveArrowDownOutline, mdiArchiveArrowUpOutline, mdiContentCopy, mdiEyeOutline, mdiVectorSquare } from "@aglyn/shared-data-mdi";
 import { AppLink, CardDisplay, MdiIcon } 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 ListTable, { ListRowActions, listActionsColumn } from "@aglyn/shared-ui-jsx/components/list-table.component";
-import { inMemoryListField } from "@aglyn/shared-ui-jsx/const/list-grid-filter";
+import { hiddenFilterVisibility } from "@aglyn/shared-ui-jsx/const/list-filter";
+import { listFilterGridColumns } from "@aglyn/shared-ui-jsx/const/list-grid-filter";
 import { TABLE_ROW_HEIGHT } from "@aglyn/shared-ui-jsx/const/table-pagination";
-import { usePagedRowsFilter } from "@aglyn/shared-ui-jsx/hooks/use-paged-rows-filter";
+import { useListGridFilter } from "@aglyn/shared-ui-jsx/hooks/use-list-grid-filter";
 import QuotaReadoutComponent from "@aglyn/shared-ui-jsx/components/quota-readout.component";
 import { CreateArtifactDrawer } from "@aglyn/shared-ui-jsx-forms";
 import { Alert, Button, Stack, Typography } from "@mui/material";
-import { collection, doc, updateDoc } from "firebase/firestore";
-import { DUPLICATE_MENU_LABEL, useConsoleHostRoute, useDuplicateResource, useFirestore, useHostCampaigns, useHostResourceApi, useLiveArtifactCount, usePagedCollection } from "@aglyn/tenant-feature-instance";
-import { collectionPage } from "@aglyn/tenant-feature-instance/hooks/host-collection-queries";
+import { collection, doc, getCountFromServer, query, updateDoc, where } from "firebase/firestore";
+import { DUPLICATE_MENU_LABEL, useConsoleHostRoute, useDuplicateResource, useFirestore, useHostCampaigns, useHostResourceApi, useLiveArtifactCount } from "@aglyn/tenant-feature-instance";
+import { useListQuery } from "@aglyn/tenant-feature-instance/hooks/use-list-query";
 import { useRouter } from "next/navigation";
-import { useCallback, useMemo, useState } from "react";
+import { useCallback, useEffect, useMemo, useState } from "react";
 import { BUNDLE_ID } from "../constants/bundle-common.js";
-/*
- * What the forms grid's Filters panel offers (AGL-3317, AGL-3330): every
- * column the table shows, typed, and the stored fields a site sorts its
- * forms out by, as columns kept out of sight.
- *
- * EVERY ONE NARROWS THE LOADED WINDOW; none is served. The list is a paged
- * listener over the document id (`collectionPage`), so a filter matches over
- * what the window has read, which the first filter widens
- * (`usePagedRowsFilter`) and the caption under the chips owns up to. The
- * query never changes shape, so no filter here needs an index. The figures
- * are the `stats` counters `/api/forms/submit` keeps on the form document
- * itself, read with the row.
- *
- *  - Submissions and Leads are numbers. Leads is ABSENT on a form that does
- *    not route to leads — the column's dash — so `is empty` finds those and
- *    `= 0` finds a routed form that has produced none.
- *  - Last submission, Updated and Created are days. Created is a column
- *    hidden by default: `/api/hosts/resources` stamps it on every form it
- *    makes.
- *  - Status (active or retired), Lead routing (`routing.lead`) and Campaign
- *    (`campaignIds`) are hidden columns, matched on keys derived by
- *    {@link formFilterRow} so the row keeps the stored fields its menu reads.
- *    A form's campaigns are ids, matched member by member and byte for byte,
- *    as the campaigns list matches its `listIds`.
- *
- * Nothing else a form stores is a filter. It keeps no type and no template,
- * and its plan slot is not its own: a retired form keeps one, which is the
- * Status filter's answer.
- */ export const FORM_FILTER_FIELDS = [
-    inMemoryListField('displayName', 'text'),
-    inMemoryListField('slug', 'text'),
-    inMemoryListField('submissions', 'number', 'stats.submissions'),
-    inMemoryListField('leads', 'number', 'stats.leads'),
-    inMemoryListField('lastSubmission', 'date', 'stats.lastSubmissionAtMs'),
-    inMemoryListField('updatedAt', 'date'),
-    inMemoryListField('createdAt', 'date'),
-    inMemoryListField('status', 'select', 'statusKey'),
-    inMemoryListField('leadRouting', 'select', 'leadRoutingKey'),
-    _extends({}, inMemoryListField('campaignIds', 'select', 'campaignKeys'), {
-        tokensPath: 'campaignKeys',
-        verbatimTokens: true
-    })
-];
-export const FORM_FILTER_HEADERS = {
-    displayName: 'Display name',
-    slug: 'Slug',
-    submissions: 'Submissions',
-    leads: 'Leads',
-    lastSubmission: 'Last submission',
-    updatedAt: 'Updated',
-    createdAt: 'Created',
-    status: 'Status',
-    leadRouting: 'Lead routing',
-    campaignIds: 'Campaign'
-};
-const FORM_STATUS_OPTIONS = [
-    {
-        value: 'active',
-        label: 'Active'
-    },
-    {
-        value: 'retired',
-        label: 'Retired'
-    }
-];
-const FORM_LEAD_ROUTING_OPTIONS = [
-    {
-        value: 'on',
-        label: 'On'
-    },
-    {
-        value: 'off',
-        label: 'Off'
-    }
-];
-/** What the quick search reads: the name, the slug and the form's id. */ export const FORM_SEARCH_FIELDS = [
+import { FORM_LEAD_ROUTING_OPTIONS, FORM_LIST_FILTER_FIELDS, FORM_LIST_FILTER_HEADERS, FORM_LIST_QUERY, FORM_LIST_SELECT_FIELDS, FORM_STATUS_OPTIONS, formListRequest } from "./form-list-query.js";
+/**
+ * The filterable columns the table shows. The rest of the declaration —
+ * Status, Lead routing, Campaign — reaches the Filters panel as hidden
+ * columns (`hiddenFilterColumns`).
+ */ const FORM_VISIBLE_FILTER_COLUMNS = [
     'displayName',
     'slug',
-    '$id'
+    'submissions',
+    'leads',
+    'lastSubmission',
+    'updatedAt'
 ];
-const FORM_HIDDEN_COLUMNS = {
-    createdAt: false,
-    status: false,
-    leadRouting: false,
-    campaignIds: false
-};
-/** A form row with the keys its hidden filters match on. */ export const formFilterRow = (form)=>{
-    var _form_routing;
-    return _extends({}, form, {
-        statusKey: isFormArchived(form) ? 'retired' : 'active',
-        leadRoutingKey: (form == null ? void 0 : (_form_routing = form.routing) == null ? void 0 : _form_routing.lead) === true ? 'on' : 'off',
-        campaignKeys: readCampaignIds(form)
-    });
-};
+const FORM_HIDDEN_COLUMNS = hiddenFilterVisibility(FORM_LIST_FILTER_FIELDS, FORM_VISIBLE_FILTER_COLUMNS);
 /**
  * THE FORM CATALOG, WITH ITS SHAPE VISIBLE BEFORE THERE IS ANYTHING IN IT.
  *
@@ -193,6 +115,7 @@ const FORM_HIDDEN_COLUMNS = {
     const [createError, setCreateError] = useState(null);
     const [creating, setCreating] = useState(false);
     const [retireError, setRetireError] = useState(null);
+    /** Bumped by each retire or restore, so the retired count is asked again. */ const [retiredEpoch, setRetiredEpoch] = useState(0);
     /**
    * Retire a form, or put it back (AGL-2671).
    *
@@ -213,8 +136,11 @@ const FORM_HIDDEN_COLUMNS = {
         setRetireError(null);
         try {
             await updateDoc(doc(firestore, 'hosts', hostId, 'forms', formId), {
-                archivedAt: retired ? Date.now() : null
+                archivedAt: retired ? Date.now() : null,
+                // The mirror the list's query asks (AGL-3330).
+                retired
             });
+            setRetiredEpoch((epoch)=>epoch + 1);
         } catch (unused) {
             setRetireError(retired ? 'Could not retire that form. Try again shortly.' : 'Could not restore that form. Try again shortly.');
         }
@@ -222,77 +148,70 @@ const FORM_HIDDEN_COLUMNS = {
         firestore,
         hostId
     ]);
-    /**
-   * The list PAGES, over an ordered walk.
+    /*
+   * THE LIST IS ITS QUERY (AGL-3330, on the AGL-3321 list query plan).
+   *
+   * The grid's Filters panel and search box edit the clauses and the words;
+   * `useListQuery` puts every one of them on ONE Firestore query and pages
+   * that query, so a page is a page of matches and a form whose only match
+   * is past the first page is still found. What one query cannot hold — a
+   * second range, a second array clause — is refused by name above the list
+   * (`ListQueryNotices`) rather than matched over the rows read. See
+   * `form-list-query.ts` for every field and the indexes they cost.
    *
-   * `collectionPage` holds the ordering decision and the reason it is the
-   * document id rather than `displayName` — briefly, `orderBy` matches only
-   * documents that HAVE the field, and the resources route stores an
-   * allow-list it never checks for presence, so ordering on a name would hide
-   * every form created without one rather than mis-sorting the list.
+   * Unfiltered it reads in document order, as it always has: `orderBy` on a
+   * name would drop every form stored without one rather than mis-sort it.
    *
-   * The page is NOT re-sorted: sorting a server-ordered window in the browser
-   * is what makes a pseudo-random sample look like the first page.
-   */ const { status, data: formData, rows: formWindow, hasMore, page, setPage, pageSize, setPageSize } = usePagedCollection((pageLimit)=>collectionPage(collection(firestore, 'hosts', hostId, 'forms'), pageLimit), [
+   * A retired form is a TOMBSTONE, not a row, unless the reader asks for
+   * Status (AGL-2671). The query leaves them out (`retired == false`), so a
+   * page is a page of forms in use; a Status clause replaces that with the
+   * reader's own choice. Retiring a form removes it from the list, and
+   * without the Status filter that would be a one-way door: the row is the
+   * only route back to Restore.
+   */ const [formClauses, setFormClauses] = useState([]);
+    const gridFilter = useListGridFilter({
+        clauses: formClauses,
+        onChange: setFormClauses,
+        selectFields: FORM_LIST_SELECT_FIELDS
+    });
+    const filtering = gridFilter.clauses.length > 0 || gridFilter.searchWords.length > 0;
+    const formsCollection = useMemo(()=>collection(firestore, 'hosts', hostId, 'forms'), [
         firestore,
         hostId
-    ], {
+    ]);
+    const { status, rows: forms, hasMore, page, setPage, pageSize, setPageSize, plan } = useListQuery({
+        collection: formsCollection,
+        declaration: FORM_LIST_QUERY,
+        request: formListRequest(gridFilter.clauses, gridFilter.searchWords),
+        deps: [
+            firestore,
+            hostId
+        ],
         idField: '$id'
     });
     /*
-   * A retired form is a TOMBSTONE, not a row — unless the reader asks for the
-   * tombstones (AGL-2671). Client-side because it has to be: Firestore cannot
-   * ask for the ABSENCE of a field, so a form created through the resources
-   * route (which carries no `archivedAt` at all) and one archived later are
-   * not one value to filter on. The cost is that a tombstone spends a slot in
-   * whichever page it falls in.
-   *
-   * The Filters panel's Status is how the reader asks (AGL-3317). With no
-   * Status clause the list leaves the tombstones out, as it always has, and
-   * reads one page; a Status clause hands the panel every row the window
-   * read, retired included, and the clause itself picks which to show. That
-   * default is the absence of a clause rather than a clause the list starts
-   * with, because a starting clause would widen the window on every visit to
-   * answer a question nobody asked. Retiring a form removes it from the list,
-   * and without the Status filter that would be a one-way door: the row is
-   * the only route back to Restore.
-   */ const [formClauses, setFormClauses] = useState([]);
-    const askedStatus = formClauses.some((clause)=>clause.field === 'status');
-    const formRows = useMemo(()=>formWindow.filter((form)=>askedStatus || !isFormArchived(form)).map(formFilterRow), [
-        formWindow,
-        askedStatus
-    ]);
-    const formWindowRows = useMemo(()=>formData == null ? void 0 : formData.filter((form)=>askedStatus || !isFormArchived(form)).map(formFilterRow), [
-        formData,
-        askedStatus
-    ]);
-    /*
    * The Campaign filter's choices: the campaigns placed on this site, by
-   * name, and any campaign a loaded form is filed under that the site's list
-   * does not name — one since taken off this site — by its id, so the form
-   * filed under it can still be found.
+   * name, and any campaign a clause names that the list does not, by its id,
+   * so the chip can still be read and cleared.
    *
-   * Read only once a loaded form IS filed under a campaign. The names cost
-   * the org lookup and up to fifty campaign documents, which a catalog with
-   * no filed form would pay on every visit for a filter with nothing to find;
-   * there the column has no choices and the panel leaves it out.
-   */ const filedCampaignIds = useMemo(()=>[
-            ...new Set((formData != null ? formData : []).flatMap((form)=>readCampaignIds(form)))
-        ], [
-        formData
-    ]);
+   * Read once the reader opens the Filters panel, not on every visit: the
+   * names cost the org lookup and up to fifty campaign documents, which a
+   * reader who came to open one form would pay for a filter they never
+   * touched. Until they land the column has no choices, and the panel lists
+   * it a moment later.
+   */ const [wantsCampaigns, setWantsCampaigns] = useState(false);
     const siteCampaigns = useHostCampaigns(hostId, {
-        enabled: filedCampaignIds.length > 0
+        enabled: wantsCampaigns || formClauses.some((clause)=>clause.field === 'campaignIds')
     });
     const formFilterOptions = useMemo(()=>{
         const named = siteCampaigns.options.map((option)=>({
                 value: option.value,
                 label: option.label
             }));
-        const unnamed = siteCampaigns.ready ? filedCampaignIds.filter((id)=>!named.some((option)=>option.value === id)).map((id)=>({
-                value: id,
-                label: id
-            })) : [];
+        const unnamed = formClauses.filter((clause)=>clause.field === 'campaignIds').flatMap((clause)=>clause.value.split(',')).map((value)=>value.trim()).filter((value)=>value && !named.some((option)=>option.value === value)).map((value)=>({
+                value,
+                label: value
+            }));
         return {
             status: FORM_STATUS_OPTIONS,
             leadRouting: FORM_LEAD_ROUTING_OPTIONS,
@@ -303,35 +222,35 @@ const FORM_HIDDEN_COLUMNS = {
         };
     }, [
         siteCampaigns.options,
-        siteCampaigns.ready,
-        filedCampaignIds
+        formClauses
     ]);
-    const formFilter = usePagedRowsFilter({
-        data: formWindowRows,
-        rows: formRows,
-        hasMore,
-        page,
-        setPage,
-        pageSize,
-        setPageSize
-    }, {
-        fields: FORM_FILTER_FIELDS,
-        options: formFilterOptions,
-        headers: FORM_FILTER_HEADERS,
-        search: FORM_SEARCH_FIELDS,
-        clauses: formClauses,
-        onChange: setFormClauses
-    });
-    // The rows on screen: the page, or the page of the matches.
-    const forms = formFilter.rows;
     /*
    * The COUNT is a server aggregate, not the length of a page. `forms` is one
    * page, and publishing that as the site's form count would read as room to
    * spare on a site that is already at the ceiling.
    */ const liveFormCount = useLiveArtifactCount(hostId, 'forms');
-    // Pending or refused, the page window stands in: a LOWER bound, never a
-    // confident zero.
-    const formsUsed = liveFormCount != null ? liveFormCount : formWindow.length;
+    // Pending or refused, the page stands in: a LOWER bound, never a confident
+    // zero.
+    const formsUsed = liveFormCount != null ? liveFormCount : forms.length;
+    /*
+   * How many forms are retired, for the "keep their slot" line (AGL-2674).
+   * An aggregate, because the list no longer reads a retired row unless it is
+   * asked for one; asked again after this card retires or restores a form.
+   */ const [retiredCount, setRetiredCount] = useState(null);
+    useEffect(()=>{
+        let active = true;
+        getCountFromServer(query(formsCollection, where('retired', '==', true))).then((snapshot)=>{
+            if (active) setRetiredCount(snapshot.data().count);
+        }).catch(()=>{
+        // The line is a courtesy; without the count it is simply not shown.
+        });
+        return ()=>{
+            active = false;
+        };
+    }, [
+        formsCollection,
+        retiredEpoch
+    ]);
     /**
    * Name first, then create (AGL-700).
    *
@@ -482,21 +401,25 @@ const FORM_HIDDEN_COLUMNS = {
                 return (value == null ? void 0 : (_value_toLocaleString = value.toLocaleString) == null ? void 0 : _value_toLocaleString.call(value)) || '--';
             }
         },
+        /*
+     * Status and Lead routing, hidden until Columns shows them (AGL-3330).
+     * Each is a select the Filters panel offers either way, and draws the
+     * choice its value names. Status reads the FACT, `archivedAt`, rather
+     * than the `retired` mirror the query asks, so a form the backfill has
+     * not reached yet still reads true.
+     */ {
+            field: 'status',
+            headerName: 'Status',
+            minWidth: 110,
+            valueGetter: (_value, row)=>String(isFormArchived(row))
+        },
         {
-            // Hidden until Columns shows it; filterable either way (AGL-3330).
-            field: 'createdAt',
-            headerName: 'Created',
-            minWidth: 170,
-            flex: 1,
-            type: 'date',
-            valueGetter: (value)=>{
-                var _ref;
-                var _value_toDate;
-                return (_ref = value == null ? void 0 : (_value_toDate = value.toDate) == null ? void 0 : _value_toDate.call(value)) != null ? _ref : null;
-            },
-            valueFormatter: (value)=>{
-                var _value_toLocaleString;
-                return (value == null ? void 0 : (_value_toLocaleString = value.toLocaleString) == null ? void 0 : _value_toLocaleString.call(value)) || '--';
+            field: 'leadRouting',
+            headerName: 'Lead routing',
+            minWidth: 120,
+            valueGetter: (_value, row)=>{
+                var _row_routing;
+                return String((row == null ? void 0 : (_row_routing = row.routing) == null ? void 0 : _row_routing.lead) === true);
             }
         },
         listActionsColumn((row)=>{
@@ -613,7 +536,7 @@ const FORM_HIDDEN_COLUMNS = {
                             limit: Aglyn.checkQuota(org, 'formsPerHost', formsUsed).limit,
                             noun: "form"
                         }),
-                        formWindow.some((form)=>isFormArchived(form)) ? /*#__PURE__*/ _jsx(Typography, {
+                        retiredCount ? /*#__PURE__*/ _jsx(Typography, {
                             variant: "caption",
                             color: "text.secondary",
                             children: 'Retired forms keep their slot'
@@ -656,21 +579,43 @@ const FORM_HIDDEN_COLUMNS = {
                         },
                         children: retireError
                     }) : null,
-                    /*#__PURE__*/ _jsx(ListFilterChips, _extends({}, formFilter.chipsProps)),
-                    formFilter.filtering && hasMore ? /*#__PURE__*/ _jsx(Typography, {
-                        variant: "caption",
-                        color: "text.secondary",
-                        children: `Filtering the ${formFilter.read} forms read so far — the next page reads more.`
-                    }) : null,
+                    /*#__PURE__*/ _jsx(ListFilterChips, {
+                        fields: FORM_LIST_FILTER_FIELDS,
+                        headers: FORM_LIST_FILTER_HEADERS,
+                        clauses: gridFilter.clauses,
+                        onChange: gridFilter.setClauses,
+                        options: formFilterOptions
+                    }),
+                    /*#__PURE__*/ _jsx(ListQueryNotices, {
+                        refused: listQueryRefusals(plan.refused, {
+                            fields: FORM_LIST_FILTER_FIELDS,
+                            headers: FORM_LIST_FILTER_HEADERS,
+                            options: formFilterOptions
+                        }),
+                        notices: plan.notices
+                    }),
                     /*#__PURE__*/ _jsx(ListTable, _extends({
                         rowHeight: TABLE_ROW_HEIGHT,
-                        columns: formFilter.filterColumns(columns),
+                        columns: listFilterGridColumns(columns, FORM_LIST_FILTER_FIELDS, formFilterOptions, FORM_LIST_FILTER_HEADERS),
                         initialState: {
                             columns: {
                                 columnVisibilityModel: FORM_HIDDEN_COLUMNS
                             }
+                        },
+                        /*
+           * The grid must NOT also filter. The query answers the panel and
+           * the search, so a second pass in the browser could only drop rows
+           * that already matched — it compares what a column DRAWS, and the
+           * query compares what the document stores.
+           */ filterMode: "server",
+                        filterModel: gridFilter.filterModel,
+                        onFilterModelChange: gridFilter.onFilterModelChange,
+                        quickFilter: true,
+                        // The Campaign filter's names are read once the panel is opened.
+                        onPreferencePanelOpen: (params)=>{
+                            if (params.openedPanelValue === 'filters') setWantsCampaigns(true);
                         }
-                    }, formFilter.gridProps, formFilter.filtering ? {
+                    }, filtering ? {
                         noRowsLabel: 'No forms match these filters'
                     } : {
                         noRowsLabel: 'No forms yet',
@@ -691,7 +636,14 @@ const FORM_HIDDEN_COLUMNS = {
                         // Paged by the footer below, so the grid must not also slice.
                         hideFooter: true
                     })),
-                    /*#__PURE__*/ _jsx(ListPagination, _extends({}, formFilter.pagination)),
+                    /*#__PURE__*/ _jsx(ListPagination, {
+                        page: page,
+                        pageSize: pageSize,
+                        rowCount: forms.length,
+                        hasMore: hasMore,
+                        onPageChange: setPage,
+                        onPageSizeChange: setPageSize
+                    }),
                     /*#__PURE__*/ _jsx(CreateArtifactDrawer, {
                         open: createOpen,
                         onClose: ()=>setCreateOpen(false),