@aglyn/plugins-crm 1.0.0-beta.143

package/src/lib/hooks/use-crm-record-names.js

@@ -0,0 +1,126 @@
+/**
+ * @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.
+ */ import { contactDisplayName, CRM_COLLECTIONS } from "@aglyn/aglyn";
+import { useFirestore } from "@aglyn/tenant-feature-instance";
+import { doc, getDoc } from "firebase/firestore";
+import { useCallback, useEffect, useState } from "react";
+import { contactPrimaryGroup } from "../model/contact-record.js";
+/** The collection each kind of record lives in, under `orgs/{orgId}/`. */ export const CRM_RECORD_COLLECTIONS = {
+    contact: 'contacts',
+    company: CRM_COLLECTIONS.companies,
+    deal: CRM_COLLECTIONS.deals
+};
+/**
+ * What a record is CALLED, from its document.
+ *
+ * A contact's name is read through the viewing group's facet, the way the
+ * people list reads it, so one business renaming a person does not change
+ * what an unrelated business's task list shows; the email stands in for a
+ * contact nobody has named. A company has a name and a deal a title.
+ */ export function crmRecordName(kind, data, groupId) {
+    if (!data) return '';
+    switch(kind){
+        case 'contact':
+            var _data_email;
+            return contactDisplayName(data, groupId) || String((_data_email = data['email']) != null ? _data_email : '');
+        case 'company':
+            var _data_name;
+            return String((_data_name = data['name']) != null ? _data_name : '');
+        case 'deal':
+            var _data_title;
+            return String((_data_title = data['title']) != null ? _data_title : '');
+    }
+}
+/**
+ * Names already read, keyed by `orgId/collection/id`, shared by every
+ * mount for the life of the page.
+ *
+ * A task list names the same handful of records over and over — five tasks
+ * about one deal are five rows and one name — and a person moves between the
+ * tasks section, a contact's page and the dashboard without the records
+ * changing underneath them. `null` records a document that does not exist,
+ * so a task pointing at a deleted record costs one read rather than one per
+ * render. A rename is picked up on the next page load, which is the right
+ * staleness for a label beside a link to the record itself.
+ */ const nameCache = new Map();
+const pending = new Map();
+const cacheKey = (orgId, kind, id)=>`${orgId}/${CRM_RECORD_COLLECTIONS[kind]}/${id}`;
+/** Test seam: forget everything, so a spec's fixtures are what get read. */ export function resetCrmRecordNameCache() {
+    nameCache.clear();
+    pending.clear();
+}
+/**
+ * The names of the records a list of tasks points at, resolved once each.
+ *
+ * Returns a lookup rather than a map so the caller does not have to know the
+ * cache's key shape. An unresolved record answers `undefined` — the cell
+ * renders the link with the id until the name lands, which is one render
+ * later on a warm cache and one round trip on a cold one.
+ */ export function useCrmRecordNames(options) {
+    const { orgId, groupId, org, records } = options;
+    const firestore = useFirestore();
+    // A counter rather than a copy of the cache: the cache is the source of
+    // truth and this only exists to re-render when it grows.
+    const [, setResolved] = useState(0);
+    // The pairs as one string, so the effect runs when the SET changes and not
+    // when the caller builds a new array of the same pairs on every render.
+    const wanted = records.map((record)=>`${record.kind}:${record.id}`).filter((entry, index, all)=>all.indexOf(entry) === index).sort().join('\n');
+    useEffect(()=>{
+        if (!orgId || !wanted) return;
+        let active = true;
+        const reads = [];
+        for (const entry of wanted.split('\n')){
+            const [kind, id] = entry.split(':');
+            const key = cacheKey(orgId, kind, id);
+            if (nameCache.has(key)) continue;
+            let read = pending.get(key);
+            if (!read) {
+                read = getDoc(doc(firestore, 'orgs', orgId, CRM_RECORD_COLLECTIONS[kind], id)).then((snapshot)=>{
+                    const data = snapshot.exists() ? snapshot.data() : undefined;
+                    nameCache.set(key, data ? crmRecordName(kind, data, groupId != null ? groupId : contactPrimaryGroup(data, org).groupId) : null);
+                }).catch(()=>{
+                // A refused or failed read is not cached: the cell keeps showing
+                // the id, and the next mount tries again.
+                }).finally(()=>{
+                    pending.delete(key);
+                });
+                pending.set(key, read);
+            }
+            reads.push(read);
+        }
+        if (!reads.length) return;
+        void Promise.all(reads).then(()=>{
+            if (active) setResolved((count)=>count + 1);
+        });
+        return ()=>{
+            active = false;
+        };
+    }, [
+        firestore,
+        orgId,
+        groupId,
+        wanted
+    ]);
+    return useCallback((kind, id)=>{
+        if (!orgId) return undefined;
+        const hit = nameCache.get(cacheKey(orgId, kind, id));
+        return hit === null ? undefined : hit;
+    }, [
+        orgId
+    ]);
+}
+
+//# sourceMappingURL=use-crm-record-names.js.map

package/src/lib/hooks/use-crm-record-names.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/crm/src/lib/hooks/use-crm-record-names.ts"],"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\nimport { contactDisplayName, CRM_COLLECTIONS } from '@aglyn/aglyn'\nimport { useFirestore } from '@aglyn/tenant-feature-instance'\nimport { doc, getDoc } from 'firebase/firestore'\nimport { useCallback, useEffect, useState } from 'react'\nimport { contactPrimaryGroup } from '../model/contact-record'\n\nexport type CrmRecordKind = 'contact' | 'company' | 'deal'\n\n/** The collection each kind of record lives in, under `orgs/{orgId}/`. */\nexport const CRM_RECORD_COLLECTIONS: Record<CrmRecordKind, string> = {\n  contact: 'contacts',\n  company: CRM_COLLECTIONS.companies,\n  deal: CRM_COLLECTIONS.deals,\n}\n\n/**\n * What a record is CALLED, from its document.\n *\n * A contact's name is read through the viewing group's facet, the way the\n * people list reads it, so one business renaming a person does not change\n * what an unrelated business's task list shows; the email stands in for a\n * contact nobody has named. A company has a name and a deal a title.\n */\nexport function crmRecordName(\n  kind: CrmRecordKind,\n  data: Record<string, unknown> | undefined,\n  groupId: string,\n): string {\n  if (!data) return ''\n  switch (kind) {\n    case 'contact':\n      return contactDisplayName(data, groupId) || String(data['email'] ?? '')\n    case 'company':\n      return String(data['name'] ?? '')\n    case 'deal':\n      return String(data['title'] ?? '')\n  }\n}\n\n/**\n * Names already read, keyed by `orgId/collection/id`, shared by every\n * mount for the life of the page.\n *\n * A task list names the same handful of records over and over — five tasks\n * about one deal are five rows and one name — and a person moves between the\n * tasks section, a contact's page and the dashboard without the records\n * changing underneath them. `null` records a document that does not exist,\n * so a task pointing at a deleted record costs one read rather than one per\n * render. A rename is picked up on the next page load, which is the right\n * staleness for a label beside a link to the record itself.\n */\nconst nameCache = new Map<string, string | null>()\nconst pending = new Map<string, Promise<void>>()\n\nconst cacheKey = (orgId: string, kind: CrmRecordKind, id: string) =>\n  `${orgId}/${CRM_RECORD_COLLECTIONS[kind]}/${id}`\n\n/** Test seam: forget everything, so a spec's fixtures are what get read. */\nexport function resetCrmRecordNameCache(): void {\n  nameCache.clear()\n  pending.clear()\n}\n\n/**\n * The names of the records a list of tasks points at, resolved once each.\n *\n * Returns a lookup rather than a map so the caller does not have to know the\n * cache's key shape. An unresolved record answers `undefined` — the cell\n * renders the link with the id until the name lands, which is one render\n * later on a warm cache and one round trip on a cold one.\n */\nexport function useCrmRecordNames(options: {\n  orgId: string | null | undefined\n  /**\n   * The viewing group a contact is named through, or `null` at the\n   * organization level (AGL-2630), where each contact is named through its\n   * own primary holder, resolved from {@link org}.\n   */\n  groupId: string | null\n  org?: Record<string, unknown> | null\n  records: ReadonlyArray<{ kind: CrmRecordKind; id: string }>\n}): (kind: CrmRecordKind, id: string) => string | undefined {\n  const { orgId, groupId, org, records } = options\n  const firestore = useFirestore()\n  // A counter rather than a copy of the cache: the cache is the source of\n  // truth and this only exists to re-render when it grows.\n  const [, setResolved] = useState(0)\n\n  // The pairs as one string, so the effect runs when the SET changes and not\n  // when the caller builds a new array of the same pairs on every render.\n  const wanted = records\n    .map((record) => `${record.kind}:${record.id}`)\n    .filter((entry, index, all) => all.indexOf(entry) === index)\n    .sort()\n    .join('\\n')\n\n  useEffect(() => {\n    if (!orgId || !wanted) return\n    let active = true\n    const reads: Promise<void>[] = []\n    for (const entry of wanted.split('\\n')) {\n      const [kind, id] = entry.split(':') as [CrmRecordKind, string]\n      const key = cacheKey(orgId, kind, id)\n      if (nameCache.has(key)) continue\n      let read = pending.get(key)\n      if (!read) {\n        read = getDoc(\n          doc(firestore, 'orgs', orgId, CRM_RECORD_COLLECTIONS[kind], id),\n        )\n          .then((snapshot) => {\n            const data = snapshot.exists()\n              ? (snapshot.data() as Record<string, unknown>)\n              : undefined\n            nameCache.set(\n              key,\n              data\n                ? crmRecordName(\n                    kind,\n                    data,\n                    groupId ?? contactPrimaryGroup(data, org).groupId,\n                  )\n                : null,\n            )\n          })\n          .catch(() => {\n            // A refused or failed read is not cached: the cell keeps showing\n            // the id, and the next mount tries again.\n          })\n          .finally(() => {\n            pending.delete(key)\n          })\n        pending.set(key, read)\n      }\n      reads.push(read)\n    }\n    if (!reads.length) return\n    void Promise.all(reads).then(() => {\n      if (active) setResolved((count) => count + 1)\n    })\n    return () => {\n      active = false\n    }\n  }, [firestore, orgId, groupId, wanted])\n\n  return useCallback(\n    (kind: CrmRecordKind, id: string) => {\n      if (!orgId) return undefined\n      const hit = nameCache.get(cacheKey(orgId, kind, id))\n      return hit === null ? undefined : hit\n    },\n    [orgId],\n  )\n}\n"],"names":["contactDisplayName","CRM_COLLECTIONS","useFirestore","doc","getDoc","useCallback","useEffect","useState","contactPrimaryGroup","CRM_RECORD_COLLECTIONS","contact","company","companies","deal","deals","crmRecordName","kind","data","groupId","String","nameCache","Map","pending","cacheKey","orgId","id","resetCrmRecordNameCache","clear","useCrmRecordNames","options","org","records","firestore","setResolved","wanted","map","record","filter","entry","index","all","indexOf","sort","join","active","reads","split","key","has","read","get","then","snapshot","exists","undefined","set","catch","finally","delete","push","length","Promise","count","hit"],"mappings":"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"}

package/src/lib/hooks/use-crm-records-quota.d.ts

@@ -0,0 +1,68 @@
+/**
+ * @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.
+ */
+import { type AglynOrgBilling, type CrmRecordsQuotaResult } from '@aglyn/aglyn';
+import { type Firestore } from 'firebase/firestore';
+/**
+ * The band's verdict, measured ONCE and now — for a write that happens on
+ * a click rather than inside a drawer that stays open (AGL-2644).
+ *
+ * The company picker's "Create …" row lives on every contact page and in
+ * the bulk bar, mounted long before anyone types a new name, so a hook that
+ * read the three aggregates on mount would charge every page view for a
+ * create that mostly never comes. This is the same three reads and the same
+ * fallback as {@link useCrmRecordsQuota}, taken at the moment they decide
+ * something. A read that failed counts as nothing, which is the permissive
+ * direction: an org is refused only by a hard band that was measured full.
+ */
+export declare function readCrmRecordsQuota(firestore: Firestore, scope: readonly ['orgs', string], org: Partial<AglynOrgBilling> | null | undefined): Promise<CrmRecordsQuotaResult>;
+export interface CrmRecordsQuotaState {
+    /** The contacts aggregate, or `null` while pending or denied. */
+    contactsCount: number | null;
+    companiesCount: number | null;
+    dealsCount: number | null;
+    /**
+     * The three summed, with an unanswered one counted as its fallback — a
+     * LOWER bound until `ready`, never an overstatement, so no alert this
+     * number gates can fire on a count larger than the truth.
+     */
+    crmRecordsCount: number;
+    /** The band's verdict on `crmRecordsCount`. */
+    quota: CrmRecordsQuotaResult;
+    /** All three aggregates have answered. */
+    ready: boolean;
+}
+/**
+ * The CRM records band as the browser can measure it (AGL-2611): one
+ * server-side aggregate per counted collection, read once per mount, summed,
+ * and handed to `checkCrmRecordsQuota` — the client twin of the server's
+ * `countCrmRecords`, for the surfaces that write client-direct.
+ *
+ * The contacts list has always read its head-count this way (AGL-1706): the
+ * listener is `limit(1000)` and must never answer "how many". What the band
+ * widening adds is the two collections beside it, so the list's alert and
+ * the company and deal drawers refuse on the same number the rollup bills.
+ *
+ * `scope` may be `null` to read nothing — a drawer that is closed, or a
+ * drawer editing an existing record, has no create to gate and pays for no
+ * aggregate. A denied read stays `null` and falls back: the alert on a full
+ * hard band must not be cleared by a count that could not be taken, and a
+ * defaulted 0 would do exactly that.
+ */
+export declare function useCrmRecordsQuota(scope: readonly ['orgs', string] | null | undefined, org: Partial<AglynOrgBilling> | null | undefined, options?: {
+    contactsFallback?: number | null;
+}): CrmRecordsQuotaState;
+export default useCrmRecordsQuota;

package/src/lib/hooks/use-crm-records-quota.js

@@ -0,0 +1,118 @@
+/**
+ * @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 { checkCrmRecordsQuota, CRM_RECORD_COLLECTIONS } from "@aglyn/aglyn";
+import { useFirestore } from "@aglyn/tenant-feature-instance";
+import { collection, getCountFromServer } from "firebase/firestore";
+import { useEffect, useMemo, useState } from "react";
+/**
+ * One aggregate for one counted collection, or `null` when the read was
+ * denied or unavailable — the fallback rule every reader of the band
+ * shares, so a count that could not be taken stands in as nothing rather
+ * than as a zero that clears an alert.
+ */ async function countCrmCollection(firestore, scope, name) {
+    try {
+        const snapshot = await getCountFromServer(collection(firestore, scope[0], scope[1], name));
+        return snapshot.data().count;
+    } catch (unused) {
+        return null;
+    }
+}
+/**
+ * The band's verdict, measured ONCE and now — for a write that happens on
+ * a click rather than inside a drawer that stays open (AGL-2644).
+ *
+ * The company picker's "Create …" row lives on every contact page and in
+ * the bulk bar, mounted long before anyone types a new name, so a hook that
+ * read the three aggregates on mount would charge every page view for a
+ * create that mostly never comes. This is the same three reads and the same
+ * fallback as {@link useCrmRecordsQuota}, taken at the moment they decide
+ * something. A read that failed counts as nothing, which is the permissive
+ * direction: an org is refused only by a hard band that was measured full.
+ */ export async function readCrmRecordsQuota(firestore, scope, org) {
+    const counts = await Promise.all(CRM_RECORD_COLLECTIONS.map((name)=>countCrmCollection(firestore, scope, name)));
+    const crmRecordsCount = counts.reduce((sum, count)=>sum + (count != null ? count : 0), 0);
+    return checkCrmRecordsQuota(org, crmRecordsCount);
+}
+/**
+ * The CRM records band as the browser can measure it (AGL-2611): one
+ * server-side aggregate per counted collection, read once per mount, summed,
+ * and handed to `checkCrmRecordsQuota` — the client twin of the server's
+ * `countCrmRecords`, for the surfaces that write client-direct.
+ *
+ * The contacts list has always read its head-count this way (AGL-1706): the
+ * listener is `limit(1000)` and must never answer "how many". What the band
+ * widening adds is the two collections beside it, so the list's alert and
+ * the company and deal drawers refuse on the same number the rollup bills.
+ *
+ * `scope` may be `null` to read nothing — a drawer that is closed, or a
+ * drawer editing an existing record, has no create to gate and pays for no
+ * aggregate. A denied read stays `null` and falls back: the alert on a full
+ * hard band must not be cleared by a count that could not be taken, and a
+ * defaulted 0 would do exactly that.
+ */ export function useCrmRecordsQuota(scope, org, options = {}) {
+    const firestore = useFirestore();
+    const { contactsFallback = null } = options;
+    const [counts, setCounts] = useState({});
+    /*
+   * Every state write below is IDENTITY-PRESERVING when nothing changed —
+   * the same answer to the same read hands back the same object — so the
+   * effect reaches a steady state even under a caller whose `scope` tuple
+   * is not referentially stable. A reset that minted a fresh `{}` per run
+   * would re-render, re-fire on the fresh tuple, reset again, and never
+   * settle: a read per render at best, a hung surface at worst.
+   */ useEffect(()=>{
+        if (!scope) return;
+        let active = true;
+        const record = (name, value)=>setCounts((current)=>name in current && current[name] === value ? current : _extends({}, current, {
+                    [name]: value
+                }));
+        for (const name of CRM_RECORD_COLLECTIONS){
+            void countCrmCollection(firestore, scope, name).then((count)=>{
+                if (active) record(name, count);
+            });
+        }
+        return ()=>{
+            active = false;
+        };
+    }, [
+        firestore,
+        scope
+    ]);
+    return useMemo(()=>{
+        var _counts_contacts, _counts_companies, _counts_deals, _ref;
+        const contactsCount = (_counts_contacts = counts['contacts']) != null ? _counts_contacts : null;
+        const companiesCount = (_counts_companies = counts['companies']) != null ? _counts_companies : null;
+        const dealsCount = (_counts_deals = counts['deals']) != null ? _counts_deals : null;
+        const crmRecordsCount = ((_ref = contactsCount != null ? contactsCount : contactsFallback) != null ? _ref : 0) + (companiesCount != null ? companiesCount : 0) + (dealsCount != null ? dealsCount : 0);
+        return {
+            contactsCount,
+            companiesCount,
+            dealsCount,
+            crmRecordsCount,
+            quota: checkCrmRecordsQuota(org, crmRecordsCount),
+            ready: CRM_RECORD_COLLECTIONS.every((name)=>name in counts)
+        };
+    }, [
+        counts,
+        contactsFallback,
+        org
+    ]);
+}
+export default useCrmRecordsQuota;
+
+//# sourceMappingURL=use-crm-records-quota.js.map

package/src/lib/hooks/use-crm-records-quota.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/crm/src/lib/hooks/use-crm-records-quota.ts"],"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\n'use client'\n\nimport {\n  type AglynOrgBilling,\n  checkCrmRecordsQuota,\n  CRM_RECORD_COLLECTIONS,\n  type CrmRecordsQuotaResult,\n} from '@aglyn/aglyn'\nimport { useFirestore } from '@aglyn/tenant-feature-instance'\nimport { collection, type Firestore, getCountFromServer } from 'firebase/firestore'\nimport { useEffect, useMemo, useState } from 'react'\n\n/**\n * One aggregate for one counted collection, or `null` when the read was\n * denied or unavailable — the fallback rule every reader of the band\n * shares, so a count that could not be taken stands in as nothing rather\n * than as a zero that clears an alert.\n */\nasync function countCrmCollection(\n  firestore: Firestore,\n  scope: readonly ['orgs', string],\n  name: string,\n): Promise<number | null> {\n  try {\n    const snapshot = await getCountFromServer(\n      collection(firestore, scope[0], scope[1], name),\n    )\n    return snapshot.data().count\n  } catch {\n    return null\n  }\n}\n\n/**\n * The band's verdict, measured ONCE and now — for a write that happens on\n * a click rather than inside a drawer that stays open (AGL-2644).\n *\n * The company picker's \"Create …\" row lives on every contact page and in\n * the bulk bar, mounted long before anyone types a new name, so a hook that\n * read the three aggregates on mount would charge every page view for a\n * create that mostly never comes. This is the same three reads and the same\n * fallback as {@link useCrmRecordsQuota}, taken at the moment they decide\n * something. A read that failed counts as nothing, which is the permissive\n * direction: an org is refused only by a hard band that was measured full.\n */\nexport async function readCrmRecordsQuota(\n  firestore: Firestore,\n  scope: readonly ['orgs', string],\n  org: Partial<AglynOrgBilling> | null | undefined,\n): Promise<CrmRecordsQuotaResult> {\n  const counts = await Promise.all(\n    CRM_RECORD_COLLECTIONS.map((name) => countCrmCollection(firestore, scope, name)),\n  )\n  const crmRecordsCount = counts.reduce<number>((sum, count) => sum + (count ?? 0), 0)\n  return checkCrmRecordsQuota(org, crmRecordsCount)\n}\n\nexport interface CrmRecordsQuotaState {\n  /** The contacts aggregate, or `null` while pending or denied. */\n  contactsCount: number | null\n  companiesCount: number | null\n  dealsCount: number | null\n  /**\n   * The three summed, with an unanswered one counted as its fallback — a\n   * LOWER bound until `ready`, never an overstatement, so no alert this\n   * number gates can fire on a count larger than the truth.\n   */\n  crmRecordsCount: number\n  /** The band's verdict on `crmRecordsCount`. */\n  quota: CrmRecordsQuotaResult\n  /** All three aggregates have answered. */\n  ready: boolean\n}\n\n/**\n * The CRM records band as the browser can measure it (AGL-2611): one\n * server-side aggregate per counted collection, read once per mount, summed,\n * and handed to `checkCrmRecordsQuota` — the client twin of the server's\n * `countCrmRecords`, for the surfaces that write client-direct.\n *\n * The contacts list has always read its head-count this way (AGL-1706): the\n * listener is `limit(1000)` and must never answer \"how many\". What the band\n * widening adds is the two collections beside it, so the list's alert and\n * the company and deal drawers refuse on the same number the rollup bills.\n *\n * `scope` may be `null` to read nothing — a drawer that is closed, or a\n * drawer editing an existing record, has no create to gate and pays for no\n * aggregate. A denied read stays `null` and falls back: the alert on a full\n * hard band must not be cleared by a count that could not be taken, and a\n * defaulted 0 would do exactly that.\n */\nexport function useCrmRecordsQuota(\n  scope: readonly ['orgs', string] | null | undefined,\n  org: Partial<AglynOrgBilling> | null | undefined,\n  options: { contactsFallback?: number | null } = {},\n): CrmRecordsQuotaState {\n  const firestore = useFirestore()\n  const { contactsFallback = null } = options\n  const [counts, setCounts] = useState<Record<string, number | null>>({})\n\n  /*\n   * Every state write below is IDENTITY-PRESERVING when nothing changed —\n   * the same answer to the same read hands back the same object — so the\n   * effect reaches a steady state even under a caller whose `scope` tuple\n   * is not referentially stable. A reset that minted a fresh `{}` per run\n   * would re-render, re-fire on the fresh tuple, reset again, and never\n   * settle: a read per render at best, a hung surface at worst.\n   */\n  useEffect(() => {\n    if (!scope) return\n    let active = true\n    const record = (name: string, value: number | null) =>\n      setCounts((current) =>\n        name in current && current[name] === value\n          ? current\n          : { ...current, [name]: value },\n      )\n    for (const name of CRM_RECORD_COLLECTIONS) {\n      void countCrmCollection(firestore, scope, name).then((count) => {\n        if (active) record(name, count)\n      })\n    }\n    return () => {\n      active = false\n    }\n  }, [firestore, scope])\n\n  return useMemo(() => {\n    const contactsCount = counts['contacts'] ?? null\n    const companiesCount = counts['companies'] ?? null\n    const dealsCount = counts['deals'] ?? null\n    const crmRecordsCount =\n      (contactsCount ?? contactsFallback ?? 0) +\n      (companiesCount ?? 0) +\n      (dealsCount ?? 0)\n    return {\n      contactsCount,\n      companiesCount,\n      dealsCount,\n      crmRecordsCount,\n      quota: checkCrmRecordsQuota(org, crmRecordsCount),\n      ready: CRM_RECORD_COLLECTIONS.every((name) => name in counts),\n    }\n  }, [counts, contactsFallback, org])\n}\n\nexport default useCrmRecordsQuota\n"],"names":["checkCrmRecordsQuota","CRM_RECORD_COLLECTIONS","useFirestore","collection","getCountFromServer","useEffect","useMemo","useState","countCrmCollection","firestore","scope","name","snapshot","data","count","readCrmRecordsQuota","org","counts","Promise","all","map","crmRecordsCount","reduce","sum","useCrmRecordsQuota","options","contactsFallback","setCounts","active","record","value","current","then","contactsCount","companiesCount","dealsCount","quota","ready","every"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;AAEA,SAEEA,oBAAoB,EACpBC,sBAAsB,QAEjB,eAAc;AACrB,SAASC,YAAY,QAAQ,iCAAgC;AAC7D,SAASC,UAAU,EAAkBC,kBAAkB,QAAQ,qBAAoB;AACnF,SAASC,SAAS,EAAEC,OAAO,EAAEC,QAAQ,QAAQ,QAAO;AAEpD;;;;;CAKC,GACD,eAAeC,mBACbC,SAAoB,EACpBC,KAAgC,EAChCC,IAAY;IAEZ,IAAI;QACF,MAAMC,WAAW,MAAMR,mBACrBD,WAAWM,WAAWC,KAAK,CAAC,EAAE,EAAEA,KAAK,CAAC,EAAE,EAAEC;QAE5C,OAAOC,SAASC,IAAI,GAAGC,KAAK;IAC9B,EAAE,eAAM;QACN,OAAO;IACT;AACF;AAEA;;;;;;;;;;;CAWC,GACD,OAAO,eAAeC,oBACpBN,SAAoB,EACpBC,KAAgC,EAChCM,GAAgD;IAEhD,MAAMC,SAAS,MAAMC,QAAQC,GAAG,CAC9BlB,uBAAuBmB,GAAG,CAAC,CAACT,OAASH,mBAAmBC,WAAWC,OAAOC;IAE5E,MAAMU,kBAAkBJ,OAAOK,MAAM,CAAS,CAACC,KAAKT,QAAUS,OAAOT,gBAAAA,QAAS,IAAI;IAClF,OAAOd,qBAAqBgB,KAAKK;AACnC;AAmBA;;;;;;;;;;;;;;;;CAgBC,GACD,OAAO,SAASG,mBACdd,KAAmD,EACnDM,GAAgD,EAChDS,UAAgD,CAAC,CAAC;IAElD,MAAMhB,YAAYP;IAClB,MAAM,EAAEwB,mBAAmB,IAAI,EAAE,GAAGD;IACpC,MAAM,CAACR,QAAQU,UAAU,GAAGpB,SAAwC,CAAC;IAErE;;;;;;;GAOC,GACDF,UAAU;QACR,IAAI,CAACK,OAAO;QACZ,IAAIkB,SAAS;QACb,MAAMC,SAAS,CAAClB,MAAcmB,QAC5BH,UAAU,CAACI,UACTpB,QAAQoB,WAAWA,OAAO,CAACpB,KAAK,KAAKmB,QACjCC,UACA,aAAKA;oBAAS,CAACpB,KAAK,EAAEmB;;QAE9B,KAAK,MAAMnB,QAAQV,uBAAwB;YACzC,KAAKO,mBAAmBC,WAAWC,OAAOC,MAAMqB,IAAI,CAAC,CAAClB;gBACpD,IAAIc,QAAQC,OAAOlB,MAAMG;YAC3B;QACF;QACA,OAAO;YACLc,SAAS;QACX;IACF,GAAG;QAACnB;QAAWC;KAAM;IAErB,OAAOJ,QAAQ;YACSW,kBACCA,mBACJA,eAEhBgB;QAJH,MAAMA,iBAAgBhB,mBAAAA,MAAM,CAAC,WAAW,YAAlBA,mBAAsB;QAC5C,MAAMiB,kBAAiBjB,oBAAAA,MAAM,CAAC,YAAY,YAAnBA,oBAAuB;QAC9C,MAAMkB,cAAalB,gBAAAA,MAAM,CAAC,QAAQ,YAAfA,gBAAmB;QACtC,MAAMI,kBACJ,EAACY,OAAAA,wBAAAA,gBAAiBP,4BAAjBO,OAAqC,MACrCC,yBAAAA,iBAAkB,MAClBC,qBAAAA,aAAc;QACjB,OAAO;YACLF;YACAC;YACAC;YACAd;YACAe,OAAOpC,qBAAqBgB,KAAKK;YACjCgB,OAAOpC,uBAAuBqC,KAAK,CAAC,CAAC3B,OAASA,QAAQM;QACxD;IACF,GAAG;QAACA;QAAQS;QAAkBV;KAAI;AACpC;AAEA,eAAeQ,mBAAkB"}

package/src/lib/hooks/use-crm-saved-view.d.ts

@@ -0,0 +1,96 @@
+import { type CrmViewFilterClause, type CrmViewSection, type CrmViewSort, type CrmViewState } from '@aglyn/aglyn';
+import { type CrmOrgDoc } from './use-crm-scope';
+import { type CrmSavedViewRow } from './use-crm-views';
+/**
+ * The address value that means "no view, whatever my default is".
+ *
+ * Without it, choosing the plain list would clear the key and the default
+ * would reapply on the next render — the reader could never leave their
+ * own default. Written only when a default exists to be overridden, so an
+ * address stays clean for a reader who never set one.
+ */
+export declare const CRM_VIEW_NONE = "all";
+/** What a section holds of its saved views, and can do with them. */
+export interface CrmSavedViewController {
+    section: CrmViewSection;
+    /** Mine and shared, by name. */
+    views: CrmSavedViewRow[];
+    /** Whether the listing has settled — a missing view is not missing until it has. */
+    ready: boolean;
+    /** The view the list is showing, when the address or the default names a listed one. */
+    current: CrmSavedViewRow | null;
+    /** The id the address names, listed or not. */
+    currentId: string | null;
+    /** The address names a view the listing does not carry. */
+    missing: boolean;
+    /** The list's working state: what the reader has narrowed, shown and sorted. */
+    state: CrmViewState;
+    setFilters: (filters: CrmViewFilterClause[]) => void;
+    setColumns: (columns: string[]) => void;
+    setSort: (sort: CrmViewSort | null) => void;
+    /** The working state differs from the view it started from. */
+    dirty: boolean;
+    /** The reader may change or remove the current view — its creator, or an org-wide member. */
+    canEdit: boolean;
+    uid: string | null;
+    /** Open a view by id, or the plain list with `null`. */
+    select: (viewId: string | null) => void;
+    /** Back to the view's saved state, or the plain list's. */
+    reset: () => void;
+    save: () => Promise<void>;
+    /** Creates, opens, and answers with the new id. */
+    saveAs: (name: string, shared: boolean) => Promise<string | null>;
+    rename: (name: string) => Promise<void>;
+    setShared: (shared: boolean) => Promise<void>;
+    remove: () => Promise<void>;
+    defaultViewId: string | null;
+    isDefault: boolean;
+    setDefault: (viewId: string | null) => Promise<void>;
+    /** A write is in flight. */
+    busy: boolean;
+}
+/**
+ * One section's saved views, resolved against its address (AGL-2617).
+ *
+ * The controller behind the views control on every CRM list. It owns three
+ * things the list used to keep in loose state and lose on reload: which
+ * view is open, what the reader has changed since, and how that gets back
+ * to the document.
+ *
+ * ## The address is the truth about which view is open
+ *
+ * `?view=<id>` names the view; choosing one navigates. So a view is a link,
+ * Back returns to the one before it, and a reload lands where the reader
+ * was. When the address names nothing, the reader's default for this
+ * section (their own profile's) opens instead — unless the list was opened
+ * FOR something, a form's captures or one address, in which case the plain
+ * list shows what it was asked for and nothing narrows it further.
+ *
+ * ## The seed is kept, first
+ *
+ * A Contacts address that carries a seed and a view means both: the seed's
+ * clause leads the view's, so the query serves the seed (it reaches the
+ * whole collection, as it did before views existed) and the view narrows
+ * the window. That is why `initial` folds into every baseline rather than
+ * being a starting state the view replaces.
+ *
+ * ## A view's state is applied once per view
+ *
+ * When the address names a view, its stored filters, columns and sort
+ * become the working state the moment the listing carries it — once. A
+ * later change to the document does not overwrite what the reader is in
+ * the middle of; a change the reader makes is theirs until they save it or
+ * reset. The default applies only onto an untouched plain list, so a reader
+ * who started narrowing before their profile arrived keeps what they typed.
+ */
+export declare function useCrmSavedView(options: {
+    section: CrmViewSection;
+    /** The site the list is read under, or `null` at the organization level. */
+    hostId: string | null;
+    org?: CrmOrgDoc;
+    /** The CRM hub path the section hangs beneath — what the address is built from. */
+    basePath: string;
+    /** What the list was opened for: clauses every baseline keeps in front. */
+    initial?: Partial<CrmViewState>;
+}): CrmSavedViewController;
+export default useCrmSavedView;