@aglyn/plugins-crm 1.0.0-beta.143

package/src/lib/hooks/use-crm-saved-view.js

@@ -0,0 +1,329 @@
+/**
+ * @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 { CRM_COLLECTIONS, CRM_VIEW_NAME_MAX, crmViewStateEquals, EMPTY_CRM_VIEW_STATE, ORG_SCOPE_TOKEN } from "@aglyn/aglyn";
+import { useFirestore, useScopeTokens, useUser } from "@aglyn/tenant-feature-instance";
+import { addDoc, collection, deleteDoc, doc, updateDoc } from "firebase/firestore";
+import { useRouter, useSearchParams } from "next/navigation";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { crmRoutes } from "../model/crm-routes.js";
+import { crmViewHref, crmViewIdFromParams } from "../model/crm-view-param.js";
+import { useCrmScope } from "./use-crm-scope.js";
+import { useCrmDefaultView } from "./use-crm-default-view.js";
+import { useCrmViews } from "./use-crm-views.js";
+/**
+ * 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 const CRM_VIEW_NONE = 'all';
+/**
+ * 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 function useCrmSavedView(options) {
+    var _ref, _ref1, _ref2, _ref3;
+    var _options_initial, _options_initial1, _options_initial2;
+    const { section, hostId, org, basePath } = options;
+    const initialFilters = (_ref = (_options_initial = options.initial) == null ? void 0 : _options_initial.filters) != null ? _ref : EMPTY_CRM_VIEW_STATE.filters;
+    const initialColumns = (_ref1 = (_options_initial1 = options.initial) == null ? void 0 : _options_initial1.columns) != null ? _ref1 : EMPTY_CRM_VIEW_STATE.columns;
+    const initialSort = (_ref2 = (_options_initial2 = options.initial) == null ? void 0 : _options_initial2.sort) != null ? _ref2 : EMPTY_CRM_VIEW_STATE.sort;
+    const seeded = initialFilters.length > 0;
+    const firestore = useFirestore();
+    const router = useRouter();
+    const searchParams = useSearchParams();
+    const { data: user } = useUser();
+    const uid = (_ref3 = user == null ? void 0 : user.uid) != null ? _ref3 : null;
+    const { scope, orgId, visibleTo, createTokens } = useCrmScope({
+        hostId,
+        org
+    });
+    const reach = useScopeTokens(orgId != null ? orgId : undefined);
+    const { views, ready } = useCrmViews({
+        scope,
+        visibleTo,
+        section,
+        uid
+    });
+    const { defaultViewId, ready: defaultReady, setDefault: writeDefault } = useCrmDefaultView({
+        uid,
+        orgId,
+        section
+    });
+    const sectionPath = useMemo(()=>crmRoutes(basePath).section(section), [
+        basePath,
+        section
+    ]);
+    /*
+   * Which view the address asks for. `all` is the reader stepping out of
+   * their default on purpose; nothing at all defers to the default, except
+   * on a seeded list, which shows what it was opened for.
+   */ const addressed = crmViewIdFromParams(searchParams);
+    const currentId = addressed === CRM_VIEW_NONE ? null : addressed != null ? addressed : seeded ? null : defaultViewId;
+    const current = useMemo(()=>{
+        var _views_find;
+        return currentId ? (_views_find = views.find((view)=>view.$id === currentId)) != null ? _views_find : null : null;
+    }, [
+        views,
+        currentId
+    ]);
+    const missing = Boolean(currentId) && ready && defaultReady && !current;
+    /** What the list opens on for a view — the seed in front — or for none. */ const baseline = useCallback((view)=>{
+        var _view_sort;
+        return view ? {
+            filters: [
+                ...initialFilters,
+                ...view.filters
+            ],
+            columns: view.columns.length ? view.columns : initialColumns,
+            sort: (_view_sort = view.sort) != null ? _view_sort : initialSort
+        } : {
+            filters: initialFilters,
+            columns: initialColumns,
+            sort: initialSort
+        };
+    }, [
+        initialFilters,
+        initialColumns,
+        initialSort
+    ]);
+    const [state, setState] = useState(()=>baseline(null));
+    /** The view whose state the working state was last set from — `''` for none. */ const applied = useRef('');
+    const dirty = !crmViewStateEquals(state, baseline(current));
+    useEffect(()=>{
+        var _ref;
+        const target = (_ref = current == null ? void 0 : current.$id) != null ? _ref : '';
+        if (applied.current === target) return;
+        // A default arriving under a list the reader already narrowed is not
+        // allowed to take that narrowing away; an explicit choice always is.
+        if (target && !addressed && dirty) return;
+        applied.current = target;
+        setState(baseline(current));
+    }, [
+        current,
+        addressed,
+        dirty,
+        baseline
+    ]);
+    const setFilters = useCallback((filters)=>setState((prev)=>_extends({}, prev, {
+                filters
+            })), []);
+    const setColumns = useCallback((columns)=>setState((prev)=>_extends({}, prev, {
+                columns
+            })), []);
+    const setSort = useCallback((sort)=>setState((prev)=>_extends({}, prev, {
+                sort
+            })), []);
+    const reset = useCallback(()=>setState(baseline(current)), [
+        baseline,
+        current
+    ]);
+    const select = useCallback((viewId)=>{
+        // Leaving a view for the plain list under a default has to SAY so,
+        // or the default would reopen on the next render.
+        const value = viewId != null ? viewId : defaultViewId ? CRM_VIEW_NONE : null;
+        router.push(crmViewHref(sectionPath, searchParams, value));
+    }, [
+        router,
+        sectionPath,
+        searchParams,
+        defaultViewId
+    ]);
+    const [busy, setBusy] = useState(false);
+    const guarded = useCallback(async (work)=>{
+        setBusy(true);
+        try {
+            return await work();
+        } finally{
+            setBusy(false);
+        }
+    }, []);
+    const viewRef = useCallback((viewId)=>scope ? doc(firestore, scope[0], scope[1], CRM_COLLECTIONS.views, viewId) : null, [
+        firestore,
+        scope
+    ]);
+    /** The three list-facing fields as the document stores them — without the seed. */ const stored = useCallback(()=>({
+            // The seed is the address's, not the view's: a view saved while a
+            // form's captures were open must not carry that form forever.
+            filters: state.filters.filter((clause)=>!initialFilters.some((seed)=>seed.field === clause.field && seed.op === clause.op && seed.value === clause.value)),
+            columns: state.columns,
+            sort: state.sort
+        }), [
+        state,
+        initialFilters
+    ]);
+    const save = useCallback(async ()=>{
+        const ref = current ? viewRef(current.$id) : null;
+        if (!ref) return;
+        await guarded(()=>updateDoc(ref, _extends({}, stored(), {
+                updatedAt: new Date()
+            })));
+    }, [
+        current,
+        viewRef,
+        guarded,
+        stored
+    ]);
+    const saveAs = useCallback(async (name, shared)=>{
+        const trimmed = name.trim().slice(0, CRM_VIEW_NAME_MAX);
+        if (!trimmed || !scope || !uid) return null;
+        const created = await guarded(()=>addDoc(collection(firestore, scope[0], scope[1], CRM_COLLECTIONS.views), _extends({
+                section,
+                name: trimmed
+            }, stored(), {
+                ownerUid: uid,
+                createdByUid: uid,
+                shared,
+                // A view made at the organization level belongs to the org
+                // (AGL-2630): it names no site, and it is stamped org-wide so
+                // every site's reader lists it — unlike a record, a view is a
+                // working arrangement, not a person's data.
+                hostId: hostId != null ? hostId : null,
+                visibleTo: hostId ? createTokens : [
+                    ORG_SCOPE_TOKEN
+                ],
+                createdAt: new Date(),
+                updatedAt: new Date()
+            })));
+        // The new view's state IS the working state, so nothing is lost when
+        // the address changes and the listing catches up.
+        applied.current = created.id;
+        select(created.id);
+        return created.id;
+    }, [
+        scope,
+        uid,
+        guarded,
+        firestore,
+        section,
+        stored,
+        hostId,
+        createTokens,
+        select
+    ]);
+    const rename = useCallback(async (name)=>{
+        const trimmed = name.trim().slice(0, CRM_VIEW_NAME_MAX);
+        const ref = current ? viewRef(current.$id) : null;
+        if (!trimmed || !ref) return;
+        await guarded(()=>updateDoc(ref, {
+                name: trimmed,
+                updatedAt: new Date()
+            }));
+    }, [
+        current,
+        viewRef,
+        guarded
+    ]);
+    const setShared = useCallback(async (shared)=>{
+        const ref = current ? viewRef(current.$id) : null;
+        if (!ref) return;
+        await guarded(()=>updateDoc(ref, {
+                shared,
+                updatedAt: new Date()
+            }));
+    }, [
+        current,
+        viewRef,
+        guarded
+    ]);
+    const isDefault = Boolean(currentId) && defaultViewId === currentId;
+    const setDefault = useCallback(async (viewId)=>{
+        await guarded(()=>writeDefault(viewId));
+    }, [
+        guarded,
+        writeDefault
+    ]);
+    const remove = useCallback(async ()=>{
+        const ref = current ? viewRef(current.$id) : null;
+        if (!ref || !current) return;
+        await guarded(async ()=>{
+            await deleteDoc(ref);
+            // A default pointing at nothing would open every visit on "missing".
+            if (defaultViewId === current.$id) await writeDefault(null);
+        });
+        applied.current = '';
+        select(null);
+    }, [
+        current,
+        viewRef,
+        guarded,
+        defaultViewId,
+        writeDefault,
+        select
+    ]);
+    const canEdit = Boolean(current && uid && (current.createdByUid === uid || reach.loaded && reach.orgWide));
+    return {
+        section,
+        views,
+        ready: ready && defaultReady,
+        current,
+        currentId,
+        missing,
+        state,
+        setFilters,
+        setColumns,
+        setSort,
+        dirty,
+        canEdit,
+        uid,
+        select,
+        reset,
+        save,
+        saveAs,
+        rename,
+        setShared,
+        remove,
+        defaultViewId,
+        isDefault,
+        setDefault,
+        busy
+    };
+}
+export default useCrmSavedView;
+
+//# sourceMappingURL=use-crm-saved-view.js.map

package/src/lib/hooks/use-crm-saved-view.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/crm/src/lib/hooks/use-crm-saved-view.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'use client'\n\nimport {\n  CRM_COLLECTIONS,\n  CRM_VIEW_NAME_MAX,\n  type CrmViewFilterClause,\n  type CrmViewSection,\n  type CrmViewSort,\n  type CrmViewState,\n  crmViewStateEquals,\n  EMPTY_CRM_VIEW_STATE,\n  ORG_SCOPE_TOKEN,\n} from '@aglyn/aglyn'\nimport {\n  useFirestore,\n  useScopeTokens,\n  useUser,\n} from '@aglyn/tenant-feature-instance'\nimport {\n  addDoc,\n  collection,\n  deleteDoc,\n  doc,\n  updateDoc,\n} from 'firebase/firestore'\nimport { useRouter, useSearchParams } from 'next/navigation'\nimport { useCallback, useEffect, useMemo, useRef, useState } from 'react'\nimport { crmRoutes } from '../model/crm-routes'\nimport { crmViewHref, crmViewIdFromParams } from '../model/crm-view-param'\nimport { type CrmOrgDoc, useCrmScope } from './use-crm-scope'\nimport { useCrmDefaultView } from './use-crm-default-view'\nimport { type CrmSavedViewRow, useCrmViews } from './use-crm-views'\n\n/**\n * The address value that means \"no view, whatever my default is\".\n *\n * Without it, choosing the plain list would clear the key and the default\n * would reapply on the next render — the reader could never leave their\n * own default. Written only when a default exists to be overridden, so an\n * address stays clean for a reader who never set one.\n */\nexport const CRM_VIEW_NONE = 'all'\n\n/** What a section holds of its saved views, and can do with them. */\nexport interface CrmSavedViewController {\n  section: CrmViewSection\n  /** Mine and shared, by name. */\n  views: CrmSavedViewRow[]\n  /** Whether the listing has settled — a missing view is not missing until it has. */\n  ready: boolean\n  /** The view the list is showing, when the address or the default names a listed one. */\n  current: CrmSavedViewRow | null\n  /** The id the address names, listed or not. */\n  currentId: string | null\n  /** The address names a view the listing does not carry. */\n  missing: boolean\n  /** The list's working state: what the reader has narrowed, shown and sorted. */\n  state: CrmViewState\n  setFilters: (filters: CrmViewFilterClause[]) => void\n  setColumns: (columns: string[]) => void\n  setSort: (sort: CrmViewSort | null) => void\n  /** The working state differs from the view it started from. */\n  dirty: boolean\n  /** The reader may change or remove the current view — its creator, or an org-wide member. */\n  canEdit: boolean\n  uid: string | null\n  /** Open a view by id, or the plain list with `null`. */\n  select: (viewId: string | null) => void\n  /** Back to the view's saved state, or the plain list's. */\n  reset: () => void\n  save: () => Promise<void>\n  /** Creates, opens, and answers with the new id. */\n  saveAs: (name: string, shared: boolean) => Promise<string | null>\n  rename: (name: string) => Promise<void>\n  setShared: (shared: boolean) => Promise<void>\n  remove: () => Promise<void>\n  defaultViewId: string | null\n  isDefault: boolean\n  setDefault: (viewId: string | null) => Promise<void>\n  /** A write is in flight. */\n  busy: boolean\n}\n\n/**\n * One section's saved views, resolved against its address (AGL-2617).\n *\n * The controller behind the views control on every CRM list. It owns three\n * things the list used to keep in loose state and lose on reload: which\n * view is open, what the reader has changed since, and how that gets back\n * to the document.\n *\n * ## The address is the truth about which view is open\n *\n * `?view=<id>` names the view; choosing one navigates. So a view is a link,\n * Back returns to the one before it, and a reload lands where the reader\n * was. When the address names nothing, the reader's default for this\n * section (their own profile's) opens instead — unless the list was opened\n * FOR something, a form's captures or one address, in which case the plain\n * list shows what it was asked for and nothing narrows it further.\n *\n * ## The seed is kept, first\n *\n * A Contacts address that carries a seed and a view means both: the seed's\n * clause leads the view's, so the query serves the seed (it reaches the\n * whole collection, as it did before views existed) and the view narrows\n * the window. That is why `initial` folds into every baseline rather than\n * being a starting state the view replaces.\n *\n * ## A view's state is applied once per view\n *\n * When the address names a view, its stored filters, columns and sort\n * become the working state the moment the listing carries it — once. A\n * later change to the document does not overwrite what the reader is in\n * the middle of; a change the reader makes is theirs until they save it or\n * reset. The default applies only onto an untouched plain list, so a reader\n * who started narrowing before their profile arrived keeps what they typed.\n */\nexport function useCrmSavedView(options: {\n  section: CrmViewSection\n  /** The site the list is read under, or `null` at the organization level. */\n  hostId: string | null\n  org?: CrmOrgDoc\n  /** The CRM hub path the section hangs beneath — what the address is built from. */\n  basePath: string\n  /** What the list was opened for: clauses every baseline keeps in front. */\n  initial?: Partial<CrmViewState>\n}): CrmSavedViewController {\n  const { section, hostId, org, basePath } = options\n  const initialFilters = options.initial?.filters ?? EMPTY_CRM_VIEW_STATE.filters\n  const initialColumns = options.initial?.columns ?? EMPTY_CRM_VIEW_STATE.columns\n  const initialSort = options.initial?.sort ?? EMPTY_CRM_VIEW_STATE.sort\n  const seeded = initialFilters.length > 0\n\n  const firestore = useFirestore()\n  const router = useRouter()\n  const searchParams = useSearchParams()\n  const { data: user } = useUser()\n  const uid = (user as { uid?: string } | null | undefined)?.uid ?? null\n  const { scope, orgId, visibleTo, createTokens } = useCrmScope({ hostId, org })\n  const reach = useScopeTokens(orgId ?? undefined)\n  const { views, ready } = useCrmViews({ scope, visibleTo, section, uid })\n  const {\n    defaultViewId,\n    ready: defaultReady,\n    setDefault: writeDefault,\n  } = useCrmDefaultView({ uid, orgId, section })\n\n  const sectionPath = useMemo(\n    () => crmRoutes(basePath).section(section),\n    [basePath, section],\n  )\n\n  /*\n   * Which view the address asks for. `all` is the reader stepping out of\n   * their default on purpose; nothing at all defers to the default, except\n   * on a seeded list, which shows what it was opened for.\n   */\n  const addressed = crmViewIdFromParams(searchParams)\n  const currentId =\n    addressed === CRM_VIEW_NONE\n      ? null\n      : addressed ?? (seeded ? null : defaultViewId)\n  const current = useMemo(\n    () => (currentId ? views.find((view) => view.$id === currentId) ?? null : null),\n    [views, currentId],\n  )\n  const missing = Boolean(currentId) && ready && defaultReady && !current\n\n  /** What the list opens on for a view — the seed in front — or for none. */\n  const baseline = useCallback(\n    (view: CrmSavedViewRow | null): CrmViewState =>\n      view\n        ? {\n            filters: [...initialFilters, ...view.filters],\n            columns: view.columns.length ? view.columns : initialColumns,\n            sort: view.sort ?? initialSort,\n          }\n        : { filters: initialFilters, columns: initialColumns, sort: initialSort },\n    [initialFilters, initialColumns, initialSort],\n  )\n\n  const [state, setState] = useState<CrmViewState>(() => baseline(null))\n  /** The view whose state the working state was last set from — `''` for none. */\n  const applied = useRef<string>('')\n  const dirty = !crmViewStateEquals(state, baseline(current))\n\n  useEffect(() => {\n    const target = current?.$id ?? ''\n    if (applied.current === target) return\n    // A default arriving under a list the reader already narrowed is not\n    // allowed to take that narrowing away; an explicit choice always is.\n    if (target && !addressed && dirty) return\n    applied.current = target\n    setState(baseline(current))\n  }, [current, addressed, dirty, baseline])\n\n  const setFilters = useCallback(\n    (filters: CrmViewFilterClause[]) => setState((prev) => ({ ...prev, filters })),\n    [],\n  )\n  const setColumns = useCallback(\n    (columns: string[]) => setState((prev) => ({ ...prev, columns })),\n    [],\n  )\n  const setSort = useCallback(\n    (sort: CrmViewSort | null) => setState((prev) => ({ ...prev, sort })),\n    [],\n  )\n  const reset = useCallback(() => setState(baseline(current)), [baseline, current])\n\n  const select = useCallback(\n    (viewId: string | null) => {\n      // Leaving a view for the plain list under a default has to SAY so,\n      // or the default would reopen on the next render.\n      const value = viewId ?? (defaultViewId ? CRM_VIEW_NONE : null)\n      router.push(crmViewHref(sectionPath, searchParams, value))\n    },\n    [router, sectionPath, searchParams, defaultViewId],\n  )\n\n  const [busy, setBusy] = useState(false)\n  const guarded = useCallback(async <T,>(work: () => Promise<T>): Promise<T> => {\n    setBusy(true)\n    try {\n      return await work()\n    } finally {\n      setBusy(false)\n    }\n  }, [])\n\n  const viewRef = useCallback(\n    (viewId: string) =>\n      scope ? doc(firestore, scope[0], scope[1], CRM_COLLECTIONS.views, viewId) : null,\n    [firestore, scope],\n  )\n\n  /** The three list-facing fields as the document stores them — without the seed. */\n  const stored = useCallback(\n    (): CrmViewState => ({\n      // The seed is the address's, not the view's: a view saved while a\n      // form's captures were open must not carry that form forever.\n      filters: state.filters.filter(\n        (clause) =>\n          !initialFilters.some(\n            (seed) =>\n              seed.field === clause.field &&\n              seed.op === clause.op &&\n              seed.value === clause.value,\n          ),\n      ),\n      columns: state.columns,\n      sort: state.sort,\n    }),\n    [state, initialFilters],\n  )\n\n  const save = useCallback(async () => {\n    const ref = current ? viewRef(current.$id) : null\n    if (!ref) return\n    await guarded(() => updateDoc(ref, { ...stored(), updatedAt: new Date() }))\n  }, [current, viewRef, guarded, stored])\n\n  const saveAs = useCallback(\n    async (name: string, shared: boolean) => {\n      const trimmed = name.trim().slice(0, CRM_VIEW_NAME_MAX)\n      if (!trimmed || !scope || !uid) return null\n      const created = await guarded(() =>\n        addDoc(collection(firestore, scope[0], scope[1], CRM_COLLECTIONS.views), {\n          section,\n          name: trimmed,\n          ...stored(),\n          ownerUid: uid,\n          createdByUid: uid,\n          shared,\n          // A view made at the organization level belongs to the org\n          // (AGL-2630): it names no site, and it is stamped org-wide so\n          // every site's reader lists it — unlike a record, a view is a\n          // working arrangement, not a person's data.\n          hostId: hostId ?? null,\n          visibleTo: hostId ? createTokens : [ORG_SCOPE_TOKEN],\n          createdAt: new Date(),\n          updatedAt: new Date(),\n        }),\n      )\n      // The new view's state IS the working state, so nothing is lost when\n      // the address changes and the listing catches up.\n      applied.current = created.id\n      select(created.id)\n      return created.id\n    },\n    [scope, uid, guarded, firestore, section, stored, hostId, createTokens, select],\n  )\n\n  const rename = useCallback(\n    async (name: string) => {\n      const trimmed = name.trim().slice(0, CRM_VIEW_NAME_MAX)\n      const ref = current ? viewRef(current.$id) : null\n      if (!trimmed || !ref) return\n      await guarded(() => updateDoc(ref, { name: trimmed, updatedAt: new Date() }))\n    },\n    [current, viewRef, guarded],\n  )\n\n  const setShared = useCallback(\n    async (shared: boolean) => {\n      const ref = current ? viewRef(current.$id) : null\n      if (!ref) return\n      await guarded(() => updateDoc(ref, { shared, updatedAt: new Date() }))\n    },\n    [current, viewRef, guarded],\n  )\n\n  const isDefault = Boolean(currentId) && defaultViewId === currentId\n\n  const setDefault = useCallback(\n    async (viewId: string | null) => {\n      await guarded(() => writeDefault(viewId))\n    },\n    [guarded, writeDefault],\n  )\n\n  const remove = useCallback(async () => {\n    const ref = current ? viewRef(current.$id) : null\n    if (!ref || !current) return\n    await guarded(async () => {\n      await deleteDoc(ref)\n      // A default pointing at nothing would open every visit on \"missing\".\n      if (defaultViewId === current.$id) await writeDefault(null)\n    })\n    applied.current = ''\n    select(null)\n  }, [current, viewRef, guarded, defaultViewId, writeDefault, select])\n\n  const canEdit = Boolean(\n    current &&\n      uid &&\n      (current.createdByUid === uid || (reach.loaded && reach.orgWide)),\n  )\n\n  return {\n    section,\n    views,\n    ready: ready && defaultReady,\n    current,\n    currentId,\n    missing,\n    state,\n    setFilters,\n    setColumns,\n    setSort,\n    dirty,\n    canEdit,\n    uid,\n    select,\n    reset,\n    save,\n    saveAs,\n    rename,\n    setShared,\n    remove,\n    defaultViewId,\n    isDefault,\n    setDefault,\n    busy,\n  }\n}\n\nexport default useCrmSavedView\n"],"names":["CRM_COLLECTIONS","CRM_VIEW_NAME_MAX","crmViewStateEquals","EMPTY_CRM_VIEW_STATE","ORG_SCOPE_TOKEN","useFirestore","useScopeTokens","useUser","addDoc","collection","deleteDoc","doc","updateDoc","useRouter","useSearchParams","useCallback","useEffect","useMemo","useRef","useState","crmRoutes","crmViewHref","crmViewIdFromParams","useCrmScope","useCrmDefaultView","useCrmViews","CRM_VIEW_NONE","useCrmSavedView","options","section","hostId","org","basePath","initialFilters","initial","filters","initialColumns","columns","initialSort","sort","seeded","length","firestore","router","searchParams","data","user","uid","scope","orgId","visibleTo","createTokens","reach","undefined","views","ready","defaultViewId","defaultReady","setDefault","writeDefault","sectionPath","addressed","currentId","current","find","view","$id","missing","Boolean","baseline","state","setState","applied","dirty","target","setFilters","prev","setColumns","setSort","reset","select","viewId","value","push","busy","setBusy","guarded","work","viewRef","stored","filter","clause","some","seed","field","op","save","ref","updatedAt","Date","saveAs","name","shared","trimmed","trim","slice","created","ownerUid","createdByUid","createdAt","id","rename","setShared","isDefault","remove","canEdit","loaded","orgWide"],"mappings":"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"}

package/src/lib/hooks/use-crm-scope.d.ts

@@ -0,0 +1,117 @@
+import { type ConsentGroup, type ConsolePluginPageProps, type ScopeToken } from '@aglyn/aglyn';
+import { type QueryConstraint } from 'firebase/firestore';
+/**
+ * The org document as a CRM surface receives it: the shell's typed billing
+ * projection on a page, or the plain record a card was handed. Read as a
+ * record at the one seam below, so no component casts it itself.
+ */
+export type CrmOrgDoc = ConsolePluginPageProps['org'] | Record<string, unknown> | null | undefined;
+/** Where a CRM surface is mounted: under one site, or over the whole org. */
+export type CrmScopeLevel = 'site' | 'org';
+export interface CrmScope {
+    /** The org data root, or `null` until the org lookup settles or when there is none. */
+    scope: readonly ['orgs', string] | null;
+    /** The owning org, or null while the lookup runs or when there is none. */
+    orgId: string | null;
+    /** Whether the org lookup has settled — `orgId` null after this means no org. */
+    ready: boolean;
+    /** Under a site, or at the organization level (AGL-2630). */
+    level: CrmScopeLevel;
+    /** The mounted site, or `null` at the organization level. */
+    hostId: string | null;
+    /**
+     * The controller this surface is being viewed as, or `null` at the org
+     * level, where there is no one viewing site: a cross-holder reader
+     * resolves each contact's own facet instead (`contactPrimaryGroup`).
+     */
+    consentGroup: ConsentGroup | null;
+    /**
+     * What this viewer may LIST — every listener's `array-contains-any`
+     * predicate, capped at what the operator accepts — or `null` at the org
+     * level, where an org-wide member's listeners carry NO scope clause: the
+     * rules' `canReadScoped()` short-circuits on `isOrgWideMember()`, so the
+     * clause would only ever narrow what the reader is already allowed. Hand
+     * it to {@link crmVisibleToClause}, which spells both cases. Stable across
+     * renders for the same org and site, so it can sit in a query's
+     * dependency list.
+     */
+    visibleTo: readonly ScopeToken[] | null;
+    /**
+     * The site a record this viewer CREATES is captured by: the mounted site,
+     * or at the org level the site the reader picked (`null` until they
+     * have). A create must hold until this is known — the tokens below are
+     * empty without it, and a record stamped with none is visible to nobody.
+     */
+    createHostId: string | null;
+    /** The consent group of {@link createHostId} — what a create records consent for. */
+    createGroup: ConsentGroup | null;
+    /** What a record this viewer CREATES is stamped with; empty until {@link createHostId} is known. */
+    createTokens: readonly ScopeToken[];
+}
+/**
+ * The scope facts every CRM surface needs, resolved once (AGL-2597, one
+ * hook since AGL-2614, two levels since AGL-2630).
+ *
+ * A CRM surface — a list, a record page, a drawer, a card on somebody
+ * else's page — resolves its consent group, builds the token list its
+ * listener filters on, builds the tokens a create stamps, and looks up the
+ * org root. Every section needs the same answers, and for a while the deals
+ * had a hook of their own that answered them under different names
+ * (`readTokens` for `visibleTo`), which is two chances to filter by one set
+ * of tokens and stamp with another. This is the one place the expression
+ * lives: a surface that spelled its own could omit the `'org'` token and
+ * stop listing the org-wide records the rules would have let it read.
+ *
+ * ## Two levels, one call
+ *
+ * Under a site, `hostId` names it and everything follows from the org
+ * document and that id, as it always has. At the ORGANIZATION level the
+ * hub hands every surface `hostId: null`, and the org comes from the mount
+ * the hub published (`useCrmOrgMount`): the org root is known at once,
+ * reads are unscoped, and the site a create stamps from is the one the
+ * reader picked. A surface written against `{ scope, visibleTo,
+ * createTokens }` serves both levels without knowing which it is on — the
+ * two differences it cannot ignore are that `visibleTo` and `consentGroup`
+ * are `null` at the org level, and both are typed to say so.
+ *
+ * `visibleTo` and `createTokens` are different questions with different
+ * answers. The first is the union of everything this viewer may see; the
+ * second is where a new record lands, which `crmScopeTokens` decides from
+ * the org's default and is narrower — a group of one site creates for that
+ * site, and reads the org-wide rows beside its own.
+ *
+ * Pure over the org document the shell already passed, so it costs no read;
+ * only the org lookup behind `useOrgDataScope` is asynchronous, and `ready`
+ * is how a surface tells "not yet" from "no org".
+ */
+export declare function useCrmScope(props: {
+    hostId: string | null | undefined;
+    org?: CrmOrgDoc;
+}): CrmScope;
+/**
+ * The scope clause a CRM listener carries, spelled once for both levels
+ * (AGL-2630).
+ *
+ * Under a site: `where('visibleTo', 'array-contains-any', tokens)`, the
+ * predicate the rules evaluate with `hasAny`, which is what makes a
+ * filtered query provable per document. At the org level: NOTHING — the
+ * reader is an org-wide member, the rules admit them to every row, and a
+ * query that kept the clause would need the org's whole site list on it
+ * and still miss a site the list did not carry. Spread into the query, so
+ * the two cases are one line at every listener: `...crmVisibleToClause(
+ * scope.visibleTo)`.
+ *
+ * A query that drops an `array-contains-any` may need a composite index
+ * the scoped form did not: the equality and range clauses beside it stay,
+ * and Firestore composes them on their own. The org-level entries live in
+ * `cloud/firebase-firestore.indexes.json` beside their scoped twins.
+ */
+export declare function crmVisibleToClause(visibleTo: readonly ScopeToken[] | readonly string[] | null | undefined): QueryConstraint[];
+/**
+ * Whether a listener that filters on `visibleTo` has anything to ask for:
+ * `true` at the org level (no clause is a complete question), and under a
+ * site only when the token list is non-empty — an `array-contains-any`
+ * over nothing is a query Firestore refuses.
+ */
+export declare function crmScopeListable(visibleTo: readonly ScopeToken[] | readonly string[] | null | undefined): boolean;
+export default useCrmScope;

package/src/lib/hooks/use-crm-scope.js

@@ -0,0 +1,147 @@
+/**
+ * @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 { consentGroupForHost, crmReadTokens, crmScopeTokens } from "@aglyn/aglyn";
+import { useOrgDataScope } from "@aglyn/tenant-feature-instance";
+import { where } from "firebase/firestore";
+import { useMemo } from "react";
+import { useCrmOrgMount } from "./use-crm-org-mount.js";
+const NO_TOKENS = Object.freeze([]);
+/**
+ * The scope facts every CRM surface needs, resolved once (AGL-2597, one
+ * hook since AGL-2614, two levels since AGL-2630).
+ *
+ * A CRM surface — a list, a record page, a drawer, a card on somebody
+ * else's page — resolves its consent group, builds the token list its
+ * listener filters on, builds the tokens a create stamps, and looks up the
+ * org root. Every section needs the same answers, and for a while the deals
+ * had a hook of their own that answered them under different names
+ * (`readTokens` for `visibleTo`), which is two chances to filter by one set
+ * of tokens and stamp with another. This is the one place the expression
+ * lives: a surface that spelled its own could omit the `'org'` token and
+ * stop listing the org-wide records the rules would have let it read.
+ *
+ * ## Two levels, one call
+ *
+ * Under a site, `hostId` names it and everything follows from the org
+ * document and that id, as it always has. At the ORGANIZATION level the
+ * hub hands every surface `hostId: null`, and the org comes from the mount
+ * the hub published (`useCrmOrgMount`): the org root is known at once,
+ * reads are unscoped, and the site a create stamps from is the one the
+ * reader picked. A surface written against `{ scope, visibleTo,
+ * createTokens }` serves both levels without knowing which it is on — the
+ * two differences it cannot ignore are that `visibleTo` and `consentGroup`
+ * are `null` at the org level, and both are typed to say so.
+ *
+ * `visibleTo` and `createTokens` are different questions with different
+ * answers. The first is the union of everything this viewer may see; the
+ * second is where a new record lands, which `crmScopeTokens` decides from
+ * the org's default and is narrower — a group of one site creates for that
+ * site, and reads the org-wide rows beside its own.
+ *
+ * Pure over the org document the shell already passed, so it costs no read;
+ * only the org lookup behind `useOrgDataScope` is asynchronous, and `ready`
+ * is how a surface tells "not yet" from "no org".
+ */ export function useCrmScope(props) {
+    var _props_org, _ref;
+    const hostId = props.hostId || null;
+    const org = (_props_org = props.org) != null ? _props_org : null;
+    const mount = useCrmOrgMount();
+    // Under a site the org is looked up from the host index; at the org level
+    // it is the mount's, known at once. A `null` host with no mount is a
+    // surface mounted nowhere, and resolves to no org rather than guessing.
+    const { scope, orgId, ready } = useOrgDataScope(hostId ? {
+        hostId
+    } : {
+        orgId: mount == null ? void 0 : mount.orgId
+    });
+    const level = hostId ? 'site' : 'org';
+    const consentGroup = useMemo(()=>hostId ? consentGroupForHost(org, hostId) : null, [
+        org,
+        hostId
+    ]);
+    const visibleTo = useMemo(()=>consentGroup ? crmReadTokens(consentGroup) : null, [
+        consentGroup
+    ]);
+    const createHostId = (_ref = hostId != null ? hostId : mount == null ? void 0 : mount.createHostId) != null ? _ref : null;
+    const createGroup = useMemo(()=>createHostId ? consentGroupForHost(org, createHostId) : null, [
+        org,
+        createHostId
+    ]);
+    const createTokens = useMemo(()=>createGroup ? crmScopeTokens(org, createGroup) : NO_TOKENS, [
+        org,
+        createGroup
+    ]);
+    return useMemo(()=>({
+            scope,
+            orgId,
+            ready,
+            level,
+            hostId,
+            consentGroup,
+            visibleTo,
+            createHostId,
+            createGroup,
+            createTokens
+        }), [
+        scope,
+        orgId,
+        ready,
+        level,
+        hostId,
+        consentGroup,
+        visibleTo,
+        createHostId,
+        createGroup,
+        createTokens
+    ]);
+}
+/**
+ * The scope clause a CRM listener carries, spelled once for both levels
+ * (AGL-2630).
+ *
+ * Under a site: `where('visibleTo', 'array-contains-any', tokens)`, the
+ * predicate the rules evaluate with `hasAny`, which is what makes a
+ * filtered query provable per document. At the org level: NOTHING — the
+ * reader is an org-wide member, the rules admit them to every row, and a
+ * query that kept the clause would need the org's whole site list on it
+ * and still miss a site the list did not carry. Spread into the query, so
+ * the two cases are one line at every listener: `...crmVisibleToClause(
+ * scope.visibleTo)`.
+ *
+ * A query that drops an `array-contains-any` may need a composite index
+ * the scoped form did not: the equality and range clauses beside it stay,
+ * and Firestore composes them on their own. The org-level entries live in
+ * `cloud/firebase-firestore.indexes.json` beside their scoped twins.
+ */ export function crmVisibleToClause(visibleTo) {
+    if (!visibleTo) return [];
+    return [
+        where('visibleTo', 'array-contains-any', [
+            ...visibleTo
+        ])
+    ];
+}
+/**
+ * Whether a listener that filters on `visibleTo` has anything to ask for:
+ * `true` at the org level (no clause is a complete question), and under a
+ * site only when the token list is non-empty — an `array-contains-any`
+ * over nothing is a query Firestore refuses.
+ */ export function crmScopeListable(visibleTo) {
+    return visibleTo === null || visibleTo === undefined || visibleTo.length > 0;
+}
+export default useCrmScope;
+
+//# sourceMappingURL=use-crm-scope.js.map