@aglyn/plugins-crm 1.0.0-beta.143

package/src/lib/components/reports/contacts-mix-card.js

@@ -0,0 +1,161 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ 'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import * as Aglyn from "@aglyn/aglyn";
+import { CardDisplay } from "@aglyn/shared-ui-jsx";
+import { percent, Section } from "@aglyn/shared-ui-jsx/components/measured-figures.component";
+import { Alert, Stack, Typography } from "@mui/material";
+import { limit, orderBy, query } from "firebase/firestore";
+import { useMemo } from "react";
+import { useFirestore } from "@aglyn/tenant-feature-instance";
+import { contactPrimaryGroup } from "../../model/contact-record.js";
+import { ReportBreakdown } from "./report-breakdown.js";
+import { plural } from "./report-format.js";
+import { reportCacheKey, scopedCollection, visibleToClause } from "./report-scope.js";
+import { useWindowRead } from "./use-aggregate-read.js";
+/**
+ * How many contacts the source mix and the funnel are read from.
+ *
+ * These two charts need a FIELD off each contact — which facet sources it
+ * carries, which lifecycle stage — and Firestore aggregates cannot group by
+ * a map key, so the only way to draw them is to read documents. A thousand
+ * is the same bound the contacts list carries, and past it the card SAYS it
+ * is a sample rather than quietly drawing a thousand as if it were the org.
+ */ const CONTACT_SAMPLE_CEILING = 1000;
+/**
+ * Contacts by source, and the lifecycle funnel, from the newest thousand
+ * contacts (AGL-2604).
+ *
+ * Both are read through THIS group's facet, the way every other field on
+ * the contacts page is: a source is which capture surface this holder saw
+ * the person through, and a stage is where this business's sales team put
+ * them. Reading either off the top of the document would chart another
+ * holder's records — the disclosure the facet shape exists to end.
+ *
+ * Newest by `createdAt` rather than by `updatedAt`, so that the sample is
+ * "the last thousand people captured" — a population a reader can reason
+ * about — and not "the thousand most recently edited", which is whichever
+ * ones a bulk tag touched last.
+ */ export function ContactsMixCard(props) {
+    const { report, totalContacts } = props;
+    const { scope, tokens, groupId, org, nowMs } = report;
+    const firestore = useFirestore();
+    const sample = useWindowRead(()=>query(scopedCollection(firestore, scope, 'contacts'), ...visibleToClause(tokens), orderBy('createdAt', 'desc'), limit(CONTACT_SAMPLE_CEILING + 1)), CONTACT_SAMPLE_CEILING, [
+        firestore,
+        scope,
+        tokens,
+        nowMs
+    ], {
+        cacheKey: reportCacheKey(report, 'contacts:sample')
+    });
+    const status = sample.status;
+    const mix = useMemo(()=>{
+        // Through the viewing group's facet under a site; at the organization
+        // level (AGL-2630) through each person's own primary holder, so the mix
+        // is of the profiles the capturing sites keep.
+        const facets = sample.rows.map((row)=>Aglyn.readContactFacet(row, groupId != null ? groupId : contactPrimaryGroup(row, org).groupId));
+        // A person captured two ways counts under both sources: the chart asks
+        // "how many people came through each door", and a person who came
+        // through two did.
+        const sources = Aglyn.tally(facets.flatMap((facet)=>Object.keys(facet.sources).filter((source)=>facet.sources[source])), (source)=>source);
+        const stageCounts = {};
+        let unstaged = 0;
+        for (const facet of facets){
+            const stage = facet.lifecycleStage;
+            if (Aglyn.isContactLifecycleStage(stage)) {
+                var _stageCounts_stage;
+                stageCounts[stage] = ((_stageCounts_stage = stageCounts[stage]) != null ? _stageCounts_stage : 0) + 1;
+            } else {
+                unstaged += 1;
+            }
+        }
+        return {
+            sources,
+            funnel: Aglyn.funnelFromStages(stageCounts),
+            unstaged
+        };
+    }, [
+        sample,
+        groupId,
+        org
+    ]);
+    // A sample only once the read has settled: while the window is empty
+    // every org "exceeds" zero rows.
+    const sampled = status === 'success' && (sample.truncated || totalContacts.value !== null && totalContacts.value > sample.rows.length);
+    return /*#__PURE__*/ _jsx(CardDisplay, {
+        header: 'Sources and lifecycle',
+        help: Aglyn.pluginDocsHelp('crmReports', {
+            anchor: '#sources-and-lifecycle',
+            excerpt: 'Which capture surfaces your contacts came through, and how many ' + 'have reached each lifecycle stage. Read from the newest thousand ' + 'contacts, through this site’s own view of each person.'
+        }),
+        contentGutterX: true,
+        contentGutterY: true,
+        children: /*#__PURE__*/ _jsxs(Stack, {
+            spacing: 2,
+            children: [
+                sampled ? /*#__PURE__*/ _jsx(Alert, {
+                    severity: "info",
+                    children: `Read from the newest ${sample.rows.length.toLocaleString()} contacts${totalContacts.value !== null ? ` of ${totalContacts.value.toLocaleString()}` : ''} — a sample, not the whole list.`
+                }) : null,
+                /*#__PURE__*/ _jsxs(Section, {
+                    title: 'By source',
+                    children: [
+                        /*#__PURE__*/ _jsx(ReportBreakdown, {
+                            rows: mix.sources.map((row)=>{
+                                var _Aglyn_CONTACT_SOURCE_LABELS_row_key;
+                                return {
+                                    key: row.key,
+                                    label: (_Aglyn_CONTACT_SOURCE_LABELS_row_key = Aglyn.CONTACT_SOURCE_LABELS[row.key]) != null ? _Aglyn_CONTACT_SOURCE_LABELS_row_key : row.key,
+                                    value: row.count
+                                };
+                            }),
+                            emptyText: status === 'loading' ? 'Reading…' : 'No contacts to count yet.'
+                        }),
+                        mix.sources.length ? /*#__PURE__*/ _jsx(Typography, {
+                            variant: "caption",
+                            color: "text.secondary",
+                            children: 'A person captured two ways counts under both.'
+                        }) : null
+                    ]
+                }),
+                /*#__PURE__*/ _jsxs(Section, {
+                    title: 'Lifecycle funnel',
+                    children: [
+                        /*#__PURE__*/ _jsx(ReportBreakdown, {
+                            rows: mix.funnel.steps.map((step)=>({
+                                    key: step.stage,
+                                    label: step.label,
+                                    value: step.reached,
+                                    note: `${plural(step.count, 'person', 'people')} here now` + (step.conversion === null ? '' : ` · ${percent(step.conversion)} of the step before`)
+                                })),
+                            emptyText: status === 'loading' ? 'Reading…' : 'No contacts to place yet.'
+                        }),
+                        sample.rows.length ? /*#__PURE__*/ _jsx(Typography, {
+                            variant: "caption",
+                            color: "text.secondary",
+                            children: `Each step counts everyone who reached it or went further. ${plural(mix.unstaged, 'contact')} with no stage yet · ${mix.funnel.other.toLocaleString()} marked other.`
+                        }) : null
+                    ]
+                })
+            ]
+        })
+    });
+}
+ContactsMixCard.displayName = 'ContactsMixCard';
+export default ContactsMixCard;
+
+//# sourceMappingURL=contacts-mix-card.js.map

package/src/lib/components/reports/contacts-mix-card.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/plugins/crm/src/lib/components/reports/contacts-mix-card.tsx"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n'use client'\n\nimport * as Aglyn from '@aglyn/aglyn'\nimport { CardDisplay } from '@aglyn/shared-ui-jsx'\nimport {\n  percent,\n  Section,\n} from '@aglyn/shared-ui-jsx/components/measured-figures.component'\nimport { Alert, Stack, Typography } from '@mui/material'\nimport { limit, orderBy, query } from 'firebase/firestore'\nimport { useMemo } from 'react'\nimport { useFirestore } from '@aglyn/tenant-feature-instance'\nimport { contactPrimaryGroup } from '../../model/contact-record'\nimport { ReportBreakdown } from './report-breakdown'\nimport { plural } from './report-format'\nimport {\n  type CrmReportScope,\n  reportCacheKey,\n  scopedCollection,\n  visibleToClause,\n} from './report-scope'\nimport { type AggregateRead, useWindowRead } from './use-aggregate-read'\n\n/**\n * How many contacts the source mix and the funnel are read from.\n *\n * These two charts need a FIELD off each contact — which facet sources it\n * carries, which lifecycle stage — and Firestore aggregates cannot group by\n * a map key, so the only way to draw them is to read documents. A thousand\n * is the same bound the contacts list carries, and past it the card SAYS it\n * is a sample rather than quietly drawing a thousand as if it were the org.\n */\nconst CONTACT_SAMPLE_CEILING = 1000\n\nexport interface ContactsMixCardProps {\n  report: CrmReportScope\n  /** The section's count of every contact this reader may see — what decides whether the read is a sample. */\n  totalContacts: AggregateRead<number>\n}\n\n/**\n * Contacts by source, and the lifecycle funnel, from the newest thousand\n * contacts (AGL-2604).\n *\n * Both are read through THIS group's facet, the way every other field on\n * the contacts page is: a source is which capture surface this holder saw\n * the person through, and a stage is where this business's sales team put\n * them. Reading either off the top of the document would chart another\n * holder's records — the disclosure the facet shape exists to end.\n *\n * Newest by `createdAt` rather than by `updatedAt`, so that the sample is\n * \"the last thousand people captured\" — a population a reader can reason\n * about — and not \"the thousand most recently edited\", which is whichever\n * ones a bulk tag touched last.\n */\nexport function ContactsMixCard(props: ContactsMixCardProps) {\n  const { report, totalContacts } = props\n  const { scope, tokens, groupId, org, nowMs } = report\n  const firestore = useFirestore()\n\n  const sample = useWindowRead<Record<string, unknown>>(\n    () =>\n      query(\n        scopedCollection(firestore, scope, 'contacts'),\n        ...visibleToClause(tokens),\n        orderBy('createdAt', 'desc'),\n        limit(CONTACT_SAMPLE_CEILING + 1),\n      ),\n    CONTACT_SAMPLE_CEILING,\n    [firestore, scope, tokens, nowMs],\n    { cacheKey: reportCacheKey(report, 'contacts:sample') },\n  )\n  const status = sample.status\n\n  const mix = useMemo(() => {\n    // Through the viewing group's facet under a site; at the organization\n    // level (AGL-2630) through each person's own primary holder, so the mix\n    // is of the profiles the capturing sites keep.\n    const facets = sample.rows.map((row) =>\n      Aglyn.readContactFacet(\n        row,\n        groupId ?? contactPrimaryGroup(row, org).groupId,\n      ),\n    )\n    // A person captured two ways counts under both sources: the chart asks\n    // \"how many people came through each door\", and a person who came\n    // through two did.\n    const sources = Aglyn.tally(\n      facets.flatMap((facet) =>\n        (Object.keys(facet.sources) as Aglyn.ContactSource[]).filter(\n          (source) => facet.sources[source],\n        ),\n      ),\n      (source) => source,\n    )\n    const stageCounts: Partial<Record<Aglyn.ContactLifecycleStage, number>> = {}\n    let unstaged = 0\n    for (const facet of facets) {\n      const stage = facet.lifecycleStage\n      if (Aglyn.isContactLifecycleStage(stage)) {\n        stageCounts[stage] = (stageCounts[stage] ?? 0) + 1\n      } else {\n        unstaged += 1\n      }\n    }\n    return { sources, funnel: Aglyn.funnelFromStages(stageCounts), unstaged }\n  }, [sample, groupId, org])\n\n  // A sample only once the read has settled: while the window is empty\n  // every org \"exceeds\" zero rows.\n  const sampled =\n    status === 'success' &&\n    (sample.truncated ||\n      (totalContacts.value !== null && totalContacts.value > sample.rows.length))\n\n  return (\n    <CardDisplay\n      header={'Sources and lifecycle'}\n      help={Aglyn.pluginDocsHelp('crmReports', {\n        anchor: '#sources-and-lifecycle',\n        excerpt:\n          'Which capture surfaces your contacts came through, and how many ' +\n          'have reached each lifecycle stage. Read from the newest thousand ' +\n          'contacts, through this site’s own view of each person.',\n      })}\n      contentGutterX\n      contentGutterY\n    >\n      <Stack spacing={2}>\n        {sampled ? (\n          <Alert severity=\"info\">\n            {`Read from the newest ${sample.rows.length.toLocaleString()} contacts${\n              totalContacts.value !== null\n                ? ` of ${totalContacts.value.toLocaleString()}`\n                : ''\n            } — a sample, not the whole list.`}\n          </Alert>\n        ) : null}\n        <Section title={'By source'}>\n          <ReportBreakdown\n            rows={mix.sources.map((row) => ({\n              key: row.key,\n              label:\n                Aglyn.CONTACT_SOURCE_LABELS[row.key as Aglyn.ContactSource] ??\n                row.key,\n              value: row.count,\n            }))}\n            emptyText={\n              status === 'loading' ? 'Reading…' : 'No contacts to count yet.'\n            }\n          />\n          {mix.sources.length ? (\n            <Typography variant=\"caption\" color=\"text.secondary\">\n              {'A person captured two ways counts under both.'}\n            </Typography>\n          ) : null}\n        </Section>\n        <Section title={'Lifecycle funnel'}>\n          <ReportBreakdown\n            rows={mix.funnel.steps.map((step) => ({\n              key: step.stage,\n              label: step.label,\n              value: step.reached,\n              note:\n                `${plural(step.count, 'person', 'people')} here now` +\n                (step.conversion === null\n                  ? ''\n                  : ` · ${percent(step.conversion)} of the step before`),\n            }))}\n            emptyText={\n              status === 'loading' ? 'Reading…' : 'No contacts to place yet.'\n            }\n          />\n          {sample.rows.length ? (\n            <Typography variant=\"caption\" color=\"text.secondary\">\n              {`Each step counts everyone who reached it or went further. ${plural(\n                mix.unstaged,\n                'contact',\n              )} with no stage yet · ${mix.funnel.other.toLocaleString()} marked other.`}\n            </Typography>\n          ) : null}\n        </Section>\n      </Stack>\n    </CardDisplay>\n  )\n}\nContactsMixCard.displayName = 'ContactsMixCard'\n\nexport default ContactsMixCard\n"],"names":["Aglyn","CardDisplay","percent","Section","Alert","Stack","Typography","limit","orderBy","query","useMemo","useFirestore","contactPrimaryGroup","ReportBreakdown","plural","reportCacheKey","scopedCollection","visibleToClause","useWindowRead","CONTACT_SAMPLE_CEILING","ContactsMixCard","props","report","totalContacts","scope","tokens","groupId","org","nowMs","firestore","sample","cacheKey","status","mix","facets","rows","map","row","readContactFacet","sources","tally","flatMap","facet","Object","keys","filter","source","stageCounts","unstaged","stage","lifecycleStage","isContactLifecycleStage","funnel","funnelFromStages","sampled","truncated","value","length","header","help","pluginDocsHelp","anchor","excerpt","contentGutterX","contentGutterY","spacing","severity","toLocaleString","title","key","label","CONTACT_SOURCE_LABELS","count","emptyText","variant","color","steps","step","reached","note","conversion","other","displayName"],"mappings":"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"}

package/src/lib/components/reports/contacts-trend-card.d.ts

@@ -0,0 +1,31 @@
+import { type CrmReportScope } from './report-scope';
+import { type AggregateRead } from './use-aggregate-read';
+export interface ContactsTrendCardProps {
+    report: CrmReportScope;
+    /** The section's one count of every contact this reader may see. */
+    totalContacts: AggregateRead<number>;
+}
+/**
+ * New contacts over the period, against the period before, week by week
+ * (AGL-2604).
+ *
+ * ## Every number here is a server count
+ *
+ * One `getCountFromServer` per week of the period and one for the previous
+ * period — fourteen reads for ninety days, billed as index entries rather
+ * than documents — and NO document is downloaded to be counted. The period
+ * figure is the sum of its weeks rather than a fifteenth read, so the tile
+ * and the bars cannot disagree. The contacts list's head-count learned the
+ * same lesson (AGL-1706): a count taken from a capped listener saturates at
+ * the cap, and the org this page is for is the one with more contacts than
+ * any listener should carry.
+ *
+ * The range is on `createdAt`, the timestamp every contact writer stamps —
+ * the server upsert with `serverTimestamp()`, the console's add-by-hand with
+ * a `Date` — so "new" means first captured, not last touched.
+ */
+export declare function ContactsTrendCard(props: ContactsTrendCardProps): import("react").JSX.Element;
+export declare namespace ContactsTrendCard {
+    var displayName: string;
+}
+export default ContactsTrendCard;

package/src/lib/components/reports/contacts-trend-card.js

@@ -0,0 +1,144 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ 'use client';
+import { _ as _extends } from "@swc/helpers/_/_extends";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { deltaPercent, pluginDocsHelp, weekBuckets } from "@aglyn/aglyn";
+import { CardDisplay } from "@aglyn/shared-ui-jsx";
+import { Section } from "@aglyn/shared-ui-jsx/components/measured-figures.component";
+import { Alert, Stack, Typography } from "@mui/material";
+import { getCountFromServer, query, Timestamp, where } from "firebase/firestore";
+import { useFirestore } from "@aglyn/tenant-feature-instance";
+import { ReportBarChart } from "./report-bar-chart.js";
+import { weekLabel } from "./report-format.js";
+import { reportCacheKey, scopedCollection, visibleToClause } from "./report-scope.js";
+import { ReportStatTile } from "./report-stat-tile.js";
+import { useAggregateRead } from "./use-aggregate-read.js";
+/**
+ * New contacts over the period, against the period before, week by week
+ * (AGL-2604).
+ *
+ * ## Every number here is a server count
+ *
+ * One `getCountFromServer` per week of the period and one for the previous
+ * period — fourteen reads for ninety days, billed as index entries rather
+ * than documents — and NO document is downloaded to be counted. The period
+ * figure is the sum of its weeks rather than a fifteenth read, so the tile
+ * and the bars cannot disagree. The contacts list's head-count learned the
+ * same lesson (AGL-1706): a count taken from a capped listener saturates at
+ * the cap, and the org this page is for is the one with more contacts than
+ * any listener should carry.
+ *
+ * The range is on `createdAt`, the timestamp every contact writer stamps —
+ * the server upsert with `serverTimestamp()`, the console's add-by-hand with
+ * a `Date` — so "new" means first captured, not last touched.
+ */ export function ContactsTrendCard(props) {
+    var _ref, _ref1;
+    const { report, totalContacts } = props;
+    const { scope, tokens, range, routes } = report;
+    const firestore = useFirestore();
+    const trend = useAggregateRead(()=>{
+        const contacts = scopedCollection(firestore, scope, 'contacts');
+        const createdBetween = (from, to)=>getCountFromServer(query(contacts, ...visibleToClause(tokens), where('createdAt', '>=', Timestamp.fromMillis(from)), where('createdAt', '<', Timestamp.fromMillis(to)))).then((snapshot)=>snapshot.data().count);
+        const buckets = weekBuckets(range.from, range.to);
+        return Promise.all([
+            createdBetween(range.previousFrom, range.previousTo),
+            ...buckets.map((bucket)=>createdBetween(bucket.start, bucket.end))
+        ]).then(([previous, ...weekly])=>({
+                previous,
+                current: weekly.reduce((sum, count)=>sum + count, 0),
+                weekly: buckets.map((bucket, index)=>{
+                    var _weekly_index;
+                    return _extends({}, bucket, {
+                        count: (_weekly_index = weekly[index]) != null ? _weekly_index : 0
+                    });
+                })
+            }));
+    }, [
+        firestore,
+        scope,
+        tokens,
+        range
+    ], {
+        cacheKey: reportCacheKey(report, 'contacts:trend')
+    });
+    const figures = trend.value;
+    return /*#__PURE__*/ _jsx(CardDisplay, {
+        header: 'Contacts',
+        help: pluginDocsHelp('crmReports', {
+            anchor: '#contacts',
+            excerpt: 'New contacts in the period against the period before it, week ' + 'by week, and how many contacts this site can see in all. Counted ' + 'on the server by when each contact was first captured.'
+        }),
+        contentGutterX: true,
+        contentGutterY: true,
+        children: /*#__PURE__*/ _jsxs(Stack, {
+            spacing: 2,
+            children: [
+                /*#__PURE__*/ _jsxs(Stack, {
+                    direction: "row",
+                    spacing: 3,
+                    sx: {
+                        flexWrap: 'wrap'
+                    },
+                    children: [
+                        /*#__PURE__*/ _jsx(ReportStatTile, {
+                            label: 'New contacts',
+                            value: figures ? figures.current.toLocaleString() : null,
+                            deltaPct: figures ? deltaPercent(figures.current, figures.previous) : null,
+                            note: figures ? figures.previous ? `${figures.previous.toLocaleString()} in the previous period` : 'none in the previous period' : undefined,
+                            href: routes.section('contacts')
+                        }),
+                        /*#__PURE__*/ _jsx(ReportStatTile, {
+                            label: 'Total contacts',
+                            value: totalContacts.value === null ? null : totalContacts.value.toLocaleString(),
+                            note: 'visible to this site',
+                            href: routes.section('contacts')
+                        })
+                    ]
+                }),
+                trend.status === 'error' || totalContacts.status === 'error' ? /*#__PURE__*/ _jsx(Alert, {
+                    severity: "warning",
+                    children: 'The contact counts could not be read. The rest of the page is unaffected.'
+                }) : null,
+                /*#__PURE__*/ _jsxs(Section, {
+                    title: 'New contacts per week',
+                    children: [
+                        /*#__PURE__*/ _jsx(ReportBarChart, {
+                            labels: ((_ref = figures == null ? void 0 : figures.weekly) != null ? _ref : []).map((week)=>weekLabel(week.start)),
+                            series: [
+                                {
+                                    name: 'New contacts',
+                                    color: 'primary.main',
+                                    values: ((_ref1 = figures == null ? void 0 : figures.weekly) != null ? _ref1 : []).map((week)=>week.count)
+                                }
+                            ],
+                            emptyText: trend.status === 'loading' ? 'Counting…' : 'Nothing in this period.'
+                        }),
+                        /*#__PURE__*/ _jsx(Typography, {
+                            variant: "caption",
+                            color: "text.secondary",
+                            children: 'Each bar is seven days from the start of the period; the last ' + 'may be shorter.'
+                        })
+                    ]
+                })
+            ]
+        })
+    });
+}
+ContactsTrendCard.displayName = 'ContactsTrendCard';
+export default ContactsTrendCard;
+
+//# sourceMappingURL=contacts-trend-card.js.map

package/src/lib/components/reports/contacts-trend-card.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/plugins/crm/src/lib/components/reports/contacts-trend-card.tsx"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n'use client'\n\nimport { deltaPercent, pluginDocsHelp, weekBuckets } from '@aglyn/aglyn'\nimport { CardDisplay } from '@aglyn/shared-ui-jsx'\nimport { Section } from '@aglyn/shared-ui-jsx/components/measured-figures.component'\nimport { Alert, Stack, Typography } from '@mui/material'\nimport { getCountFromServer, query, Timestamp, where } from 'firebase/firestore'\nimport { useFirestore } from '@aglyn/tenant-feature-instance'\nimport { ReportBarChart } from './report-bar-chart'\nimport { weekLabel } from './report-format'\nimport {\n  type CrmReportScope,\n  reportCacheKey,\n  scopedCollection,\n  visibleToClause,\n} from './report-scope'\nimport { ReportStatTile } from './report-stat-tile'\nimport { type AggregateRead, useAggregateRead } from './use-aggregate-read'\n\nexport interface ContactsTrendCardProps {\n  report: CrmReportScope\n  /** The section's one count of every contact this reader may see. */\n  totalContacts: AggregateRead<number>\n}\n\ninterface ContactsTrend {\n  /** New contacts in the period — the sum of the weeks. */\n  current: number\n  /** New contacts in the period before it. */\n  previous: number\n  weekly: Array<{ start: number; end: number; count: number }>\n}\n\n/**\n * New contacts over the period, against the period before, week by week\n * (AGL-2604).\n *\n * ## Every number here is a server count\n *\n * One `getCountFromServer` per week of the period and one for the previous\n * period — fourteen reads for ninety days, billed as index entries rather\n * than documents — and NO document is downloaded to be counted. The period\n * figure is the sum of its weeks rather than a fifteenth read, so the tile\n * and the bars cannot disagree. The contacts list's head-count learned the\n * same lesson (AGL-1706): a count taken from a capped listener saturates at\n * the cap, and the org this page is for is the one with more contacts than\n * any listener should carry.\n *\n * The range is on `createdAt`, the timestamp every contact writer stamps —\n * the server upsert with `serverTimestamp()`, the console's add-by-hand with\n * a `Date` — so \"new\" means first captured, not last touched.\n */\nexport function ContactsTrendCard(props: ContactsTrendCardProps) {\n  const { report, totalContacts } = props\n  const { scope, tokens, range, routes } = report\n  const firestore = useFirestore()\n\n  const trend = useAggregateRead<ContactsTrend>(() => {\n    const contacts = scopedCollection(firestore, scope, 'contacts')\n    const createdBetween = (from: number, to: number) =>\n      getCountFromServer(\n        query(\n          contacts,\n          ...visibleToClause(tokens),\n          where('createdAt', '>=', Timestamp.fromMillis(from)),\n          where('createdAt', '<', Timestamp.fromMillis(to)),\n        ),\n      ).then((snapshot) => snapshot.data().count)\n    const buckets = weekBuckets(range.from, range.to)\n    return Promise.all([\n      createdBetween(range.previousFrom, range.previousTo),\n      ...buckets.map((bucket) => createdBetween(bucket.start, bucket.end)),\n    ]).then(([previous, ...weekly]) => ({\n      previous,\n      current: weekly.reduce((sum, count) => sum + count, 0),\n      weekly: buckets.map((bucket, index) => ({\n        ...bucket,\n        count: weekly[index] ?? 0,\n      })),\n    }))\n  }, [firestore, scope, tokens, range], { cacheKey: reportCacheKey(report, 'contacts:trend') })\n\n  const figures = trend.value\n  return (\n    <CardDisplay\n      header={'Contacts'}\n      help={pluginDocsHelp('crmReports', {\n        anchor: '#contacts',\n        excerpt:\n          'New contacts in the period against the period before it, week ' +\n          'by week, and how many contacts this site can see in all. Counted ' +\n          'on the server by when each contact was first captured.',\n      })}\n      contentGutterX\n      contentGutterY\n    >\n      <Stack spacing={2}>\n        <Stack direction=\"row\" spacing={3} sx={{ flexWrap: 'wrap' }}>\n          <ReportStatTile\n            label={'New contacts'}\n            value={figures ? figures.current.toLocaleString() : null}\n            deltaPct={figures ? deltaPercent(figures.current, figures.previous) : null}\n            note={\n              figures\n                ? figures.previous\n                  ? `${figures.previous.toLocaleString()} in the previous period`\n                  : 'none in the previous period'\n                : undefined\n            }\n            href={routes.section('contacts')}\n          />\n          <ReportStatTile\n            label={'Total contacts'}\n            value={\n              totalContacts.value === null\n                ? null\n                : totalContacts.value.toLocaleString()\n            }\n            note={'visible to this site'}\n            href={routes.section('contacts')}\n          />\n        </Stack>\n        {trend.status === 'error' || totalContacts.status === 'error' ? (\n          <Alert severity=\"warning\">\n            {'The contact counts could not be read. The rest of the page is unaffected.'}\n          </Alert>\n        ) : null}\n        <Section title={'New contacts per week'}>\n          <ReportBarChart\n            labels={(figures?.weekly ?? []).map((week) => weekLabel(week.start))}\n            series={[\n              {\n                name: 'New contacts',\n                color: 'primary.main',\n                values: (figures?.weekly ?? []).map((week) => week.count),\n              },\n            ]}\n            emptyText={\n              trend.status === 'loading' ? 'Counting…' : 'Nothing in this period.'\n            }\n          />\n          <Typography variant=\"caption\" color=\"text.secondary\">\n            {'Each bar is seven days from the start of the period; the last ' +\n              'may be shorter.'}\n          </Typography>\n        </Section>\n      </Stack>\n    </CardDisplay>\n  )\n}\nContactsTrendCard.displayName = 'ContactsTrendCard'\n\nexport default ContactsTrendCard\n"],"names":["deltaPercent","pluginDocsHelp","weekBuckets","CardDisplay","Section","Alert","Stack","Typography","getCountFromServer","query","Timestamp","where","useFirestore","ReportBarChart","weekLabel","reportCacheKey","scopedCollection","visibleToClause","ReportStatTile","useAggregateRead","ContactsTrendCard","props","report","totalContacts","scope","tokens","range","routes","firestore","trend","contacts","createdBetween","from","to","fromMillis","then","snapshot","data","count","buckets","Promise","all","previousFrom","previousTo","map","bucket","start","end","previous","weekly","current","reduce","sum","index","cacheKey","figures","value","header","help","anchor","excerpt","contentGutterX","contentGutterY","spacing","direction","sx","flexWrap","label","toLocaleString","deltaPct","note","undefined","href","section","status","severity","title","labels","week","series","name","color","values","emptyText","variant","displayName"],"mappings":"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"}

package/src/lib/components/reports/forecast-card.d.ts

@@ -0,0 +1,22 @@
+import { type CrmReportScope } from './report-scope';
+export interface ForecastCardProps {
+    report: CrmReportScope;
+}
+/**
+ * Forecast by close month (AGL-2620): the open pipeline laid out by the
+ * month each deal is expected to close, for the next six, per pipeline,
+ * at face value and weighted by the stage.
+ *
+ * Not period-scoped, like the pipeline card and for the same reason: the
+ * forecast is what is open NOW, looked at forward. Deals with no expected
+ * close are their own row rather than a footnote — that row is the size
+ * of the pipeline nobody has scheduled, which is the number the picker
+ * of a close date most needs to see — and deals dated before this month
+ * (overdue) or past the sixth (later) are rows too, so the column adds up
+ * to the pipeline.
+ */
+export declare function ForecastCard(props: ForecastCardProps): import("react").JSX.Element;
+export declare namespace ForecastCard {
+    var displayName: string;
+}
+export default ForecastCard;