@anzusystems/common-admin 1.47.0-beta.dev-1790143991 → 2.0.0-rc.1

package/dist/domains/cached/composables/createCachedChip.d.ts

@@ -0,0 +1,36 @@
+import { Component } from 'vue';
+import { DocId, IntegerId } from '../../../shared/types/common';
+export type CachedChipId = null | undefined | IntegerId | DocId;
+export interface CreateCachedChipOptions {
+    /**
+     * Composable returning the per-id cache getter — invoked inside the chip's
+     * setup so the backing cache store resolves in component scope. The `id`
+     * param is `any` to match `ACachedChip` and accept both numeric- and
+     * doc-id getters regardless of their exact parameter type.
+     */
+    useGetCachedFn: () => (id: any) => unknown;
+    /** Named route the chip links to (e.g. `'/(cms)/desks/[id]'`). */
+    route: string;
+    /** Dot-path into the cached entity for the chip label (e.g. `'name'`). */
+    displayTextPath: string;
+    /** Static props baked onto every instance (e.g. a fixed `textOnly`). */
+    chipProps?: Record<string, unknown>;
+    /** Component name for devtools / warnings. */
+    name?: string;
+}
+/**
+ * Builds a cached-entity chip from a domain's cache composable + route, so each
+ * per-domain `CachedXChip.vue` collapses to a single factory call instead of a
+ * full SFC re-binding `ACachedChip`. Caller-passed attributes (`size`, `color`,
+ * `disable-click`, …) and slots fall through to `ACachedChip`.
+ *
+ * Use in an SFC's plain `<script lang="ts">` (not `setup`):
+ * ```ts
+ * export default createCachedChip({
+ *   useGetCachedFn: () => useCachedDesks().getCachedDesk,
+ *   route: '/(cms)/desks/[id]',
+ *   displayTextPath: 'name',
+ * })
+ * ```
+ */
+export declare function createCachedChip(options: CreateCachedChipOptions): Component;

package/dist/domains/cached/composables/createCachedChip.js

@@ -0,0 +1,28 @@
+import e from "../components/ACachedChip.js";
+import { defineComponent as t, h as n } from "vue";
+//#region src/domains/cached/composables/createCachedChip.ts
+function r(r) {
+	return t({
+		name: r.name ?? "CachedChip",
+		inheritAttrs: !1,
+		props: { id: {
+			type: [Number, String],
+			default: null
+		} },
+		setup(t, { attrs: i, slots: a }) {
+			let o = r.useGetCachedFn();
+			return () => n(e, {
+				id: t.id,
+				getCachedFn: o,
+				route: r.route,
+				displayTextPath: r.displayTextPath,
+				...r.chipProps,
+				...i
+			}, a);
+		}
+	});
+}
+//#endregion
+export { r as createCachedChip };
+
+//# sourceMappingURL=createCachedChip.js.map

package/dist/domains/cached/composables/createCachedChip.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"createCachedChip.js","names":["ACachedChip","ACachedChip_default","createCachedChip","defineComponent","options","getCachedFn","h","props","attrs","slots"],"sources":["../../../../src/domains/cached/composables/createCachedChip.ts"],"sourcesContent":["import { type Component, defineComponent, h, type PropType } from 'vue'\nimport ACachedChip from '@/domains/cached/components/ACachedChip.vue'\nimport type { DocId, IntegerId } from '@/shared/types/common'\n\nexport type CachedChipId = null | undefined | IntegerId | DocId\n\nexport interface CreateCachedChipOptions {\n  /**\n   * Composable returning the per-id cache getter — invoked inside the chip's\n   * setup so the backing cache store resolves in component scope. The `id`\n   * param is `any` to match `ACachedChip` and accept both numeric- and\n   * doc-id getters regardless of their exact parameter type.\n   */\n  useGetCachedFn: () => (id: any) => unknown\n  /** Named route the chip links to (e.g. `'/(cms)/desks/[id]'`). */\n  route: string\n  /** Dot-path into the cached entity for the chip label (e.g. `'name'`). */\n  displayTextPath: string\n  /** Static props baked onto every instance (e.g. a fixed `textOnly`). */\n  chipProps?: Record<string, unknown>\n  /** Component name for devtools / warnings. */\n  name?: string\n}\n\n/**\n * Builds a cached-entity chip from a domain's cache composable + route, so each\n * per-domain `CachedXChip.vue` collapses to a single factory call instead of a\n * full SFC re-binding `ACachedChip`. Caller-passed attributes (`size`, `color`,\n * `disable-click`, …) and slots fall through to `ACachedChip`.\n *\n * Use in an SFC's plain `<script lang=\"ts\">` (not `setup`):\n * ```ts\n * export default createCachedChip({\n *   useGetCachedFn: () => useCachedDesks().getCachedDesk,\n *   route: '/(cms)/desks/[id]',\n *   displayTextPath: 'name',\n * })\n * ```\n */\nexport function createCachedChip(options: CreateCachedChipOptions): Component {\n  return defineComponent({\n    name: options.name ?? 'CachedChip',\n    inheritAttrs: false,\n    // Vue skips type validation for null/undefined on non-required props, so a\n    // null id (the common \"empty\" case) won't warn despite the typed prop.\n    props: {\n      id: { type: [Number, String] as PropType<CachedChipId>, default: null },\n    },\n    setup(props, { attrs, slots }) {\n      const getCachedFn = options.useGetCachedFn()\n      return () =>\n        h(\n          ACachedChip,\n          {\n            id: props.id,\n            getCachedFn,\n            route: options.route,\n            displayTextPath: options.displayTextPath,\n            ...options.chipProps,\n            ...attrs,\n          },\n          slots\n        )\n    },\n  })\n}\n"],"mappings":";;;AAuCA,SAAgBE,EAAiB,GAA6C;CAC5E,OAAOC,EAAgB;EACrB,MAAMC,EAAQ,QAAQ;EACtB,cAAc;EAGd,OAAO,EACL,IAAI;GAAE,MAAM,CAAC,QAAQ,MAAM;GAA6B,SAAS;EAAK,EACxE;EACA,MAAM,GAAO,EAAE,UAAO,YAAS;GAC7B,IAAMC,IAAcD,EAAQ,eAAe;GAC3C,aACEE,EACEN,GACA;IACE,IAAIO,EAAM;IACV;IACA,OAAOH,EAAQ;IACf,iBAAiBA,EAAQ;IACzB,GAAGA,EAAQ;IACX,GAAGI;GACL,GACAC,CACF;EACJ;CACF,CAAC;AACH"}

package/dist/domains/cached/composables/createUserAndTimeTrackingFields.d.ts

@@ -0,0 +1,36 @@
+import { Component } from 'vue';
+import { AnzuUserMinimal } from '../../../shared/types/AnzuUser';
+import { CachedItem } from './defineCached';
+import { UserAndTimeTrackingUsers } from '../../../shared/types/UserAndTimeTracking';
+export interface CreateUserAndTimeTrackingFieldsOptions<U extends AnzuUserMinimal = AnzuUserMinimal> {
+    /**
+     * The admin's user cache composable, e.g. its `useCachedUsers`. Invoked inside the component's
+     * setup, once, so the cache resolves in component scope.
+     */
+    useCachedUsers: () => UserAndTimeTrackingUsers<U>;
+    /**
+     * Named route of a user's detail (e.g. `'/(common)/users/[id]'`); without it the chip is no link. A function is read
+     * on each render, so the link can follow the current user's permission for that route.
+     */
+    userRouteName?: string | (() => string | undefined);
+    /** A user's detail in another admin, `:id` replaced; opens in a new tab. */
+    userExternalUrlTemplate?: string;
+    /** The chip's label, for users that carry a better one than `person.fullName`. */
+    userTitleFn?: (user: CachedItem<U>) => string;
+    /** Component name for devtools / warnings. */
+    name?: string;
+}
+/**
+ * Builds an admin's created / modified rows from its user cache and routes, so each admin's
+ * `XTrackingFields.vue` is a single factory call over `AUserAndTimeTrackingFields`, as each
+ * `CachedXChip.vue` is over `ACachedChip`. `hide-*` and the `user` slot fall through.
+ *
+ * Use in an SFC's plain `<script lang="ts">` (not `setup`):
+ * ```ts
+ * export default createUserAndTimeTrackingFields({
+ *   useCachedUsers,
+ *   userRouteName: '/(common)/users/[id]',
+ * })
+ * ```
+ */
+export declare function createUserAndTimeTrackingFields<U extends AnzuUserMinimal = AnzuUserMinimal>(options: CreateUserAndTimeTrackingFieldsOptions<U>): Component;

package/dist/domains/cached/composables/createUserAndTimeTrackingFields.js

@@ -0,0 +1,29 @@
+import { isFunction as e } from "../../../shared/utils/common.js";
+import t from "../../ui/components/AUserAndTimeTrackingFields.js";
+import { defineComponent as n, h as r } from "vue";
+//#region src/domains/cached/composables/createUserAndTimeTrackingFields.ts
+function i(i) {
+	return n({
+		name: i.name ?? "UserAndTimeTrackingFields",
+		inheritAttrs: !1,
+		props: { data: {
+			type: Object,
+			required: !0
+		} },
+		setup(n, { attrs: a, slots: o }) {
+			let s = i.useCachedUsers();
+			return () => r(t, {
+				data: n.data,
+				users: s,
+				userRouteName: e(i.userRouteName) ? i.userRouteName() : i.userRouteName,
+				userExternalUrlTemplate: i.userExternalUrlTemplate,
+				userTitleFn: i.userTitleFn,
+				...a
+			}, o);
+		}
+	});
+}
+//#endregion
+export { i as createUserAndTimeTrackingFields };
+
+//# sourceMappingURL=createUserAndTimeTrackingFields.js.map

package/dist/domains/cached/composables/createUserAndTimeTrackingFields.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"createUserAndTimeTrackingFields.js","names":["AUserAndTimeTrackingFields","AUserAndTimeTrackingFields_default","createUserAndTimeTrackingFields","defineComponent","options","users","h","props","isFunction","attrs","slots"],"sources":["../../../../src/domains/cached/composables/createUserAndTimeTrackingFields.ts"],"sourcesContent":["import { type Component, defineComponent, h, type PropType } from 'vue'\nimport { isFunction } from '@/shared/utils/common'\nimport AUserAndTimeTrackingFields from '@/domains/ui/components/AUserAndTimeTrackingFields.vue'\nimport type { AnzuUserMinimal } from '@/shared/types/AnzuUser'\nimport type { CachedItem } from '@/domains/cached/composables/defineCached'\nimport type { UserAndTimeTrackingData, UserAndTimeTrackingUsers } from '@/shared/types/UserAndTimeTracking'\n\nexport interface CreateUserAndTimeTrackingFieldsOptions<U extends AnzuUserMinimal = AnzuUserMinimal> {\n  /**\n   * The admin's user cache composable, e.g. its `useCachedUsers`. Invoked inside the component's\n   * setup, once, so the cache resolves in component scope.\n   */\n  useCachedUsers: () => UserAndTimeTrackingUsers<U>\n  /**\n   * Named route of a user's detail (e.g. `'/(common)/users/[id]'`); without it the chip is no link. A function is read\n   * on each render, so the link can follow the current user's permission for that route.\n   */\n  userRouteName?: string | (() => string | undefined)\n  /** A user's detail in another admin, `:id` replaced; opens in a new tab. */\n  userExternalUrlTemplate?: string\n  /** The chip's label, for users that carry a better one than `person.fullName`. */\n  userTitleFn?: (user: CachedItem<U>) => string\n  /** Component name for devtools / warnings. */\n  name?: string\n}\n\n/**\n * Builds an admin's created / modified rows from its user cache and routes, so each admin's\n * `XTrackingFields.vue` is a single factory call over `AUserAndTimeTrackingFields`, as each\n * `CachedXChip.vue` is over `ACachedChip`. `hide-*` and the `user` slot fall through.\n *\n * Use in an SFC's plain `<script lang=\"ts\">` (not `setup`):\n * ```ts\n * export default createUserAndTimeTrackingFields({\n *   useCachedUsers,\n *   userRouteName: '/(common)/users/[id]',\n * })\n * ```\n */\nexport function createUserAndTimeTrackingFields<U extends AnzuUserMinimal = AnzuUserMinimal>(\n  options: CreateUserAndTimeTrackingFieldsOptions<U>\n): Component {\n  return defineComponent({\n    name: options.name ?? 'UserAndTimeTrackingFields',\n    inheritAttrs: false,\n    props: {\n      data: { type: Object as PropType<UserAndTimeTrackingData>, required: true },\n    },\n    setup(props, { attrs, slots }) {\n      const users = options.useCachedUsers()\n      return () =>\n        h(\n          AUserAndTimeTrackingFields,\n          {\n            data: props.data,\n            users,\n            userRouteName: isFunction(options.userRouteName) ? options.userRouteName() : options.userRouteName,\n            userExternalUrlTemplate: options.userExternalUrlTemplate,\n            userTitleFn: options.userTitleFn,\n            ...attrs,\n          },\n          slots\n        )\n    },\n  })\n}\n"],"mappings":";;;;AAuCA,SAAgBE,EACd,GACW;CACX,OAAOC,EAAgB;EACrB,MAAMC,EAAQ,QAAQ;EACtB,cAAc;EACd,OAAO,EACL,MAAM;GAAE,MAAM;GAA6C,UAAU;EAAK,EAC5E;EACA,MAAM,GAAO,EAAE,UAAO,YAAS;GAC7B,IAAMC,IAAQD,EAAQ,eAAe;GACrC,aACEE,EACEN,GACA;IACE,MAAMO,EAAM;IACZ;IACA,eAAeC,EAAWJ,EAAQ,aAAa,IAAIA,EAAQ,cAAc,IAAIA,EAAQ;IACrF,yBAAyBA,EAAQ;IACjC,aAAaA,EAAQ;IACrB,GAAGK;GACL,GACAC,CACF;EACJ;CACF,CAAC;AACH"}

package/dist/domains/cached/composables/defineCached.d.ts

@@ -0,0 +1,55 @@
+import { Ref } from 'vue';
+import { DocId, IntegerId } from '../../../shared/types/common';
+/**
+ * Why a fetch settled without resolving an item:
+ * - `notFound` -- the server answered and the item was not among the results,
+ * - `forbidden` -- the user may not read it (403); asking again in this session cannot change that,
+ * - `error` -- anything else: the network, a timeout, a 5xx, a 401 before the session is renewed, and a
+ *   404 of the whole request, which is a route or a proxy answering rather than an item missing.
+ */
+export type CachedUnresolvedReason = 'notFound' | 'forbidden' | 'error';
+/**
+ * `_unresolved`: the fetch settled without resolving the item, `_unresolvedReason` says why.
+ * Whether a later `add()` asks again depends on the reason (see `defineCached`).
+ */
+export type CachedItem<T extends object> = T & {
+    _loaded: boolean;
+    _unresolved?: boolean;
+    _unresolvedReason?: CachedUnresolvedReason;
+};
+export interface DefineCachedOptions {
+    /**
+     * Ask again, on the next `add()`, for an id the server did not return. Defaults to `true`: an entity
+     * can be created after the first lookup. A cache of users passes `false` -- an id missing from the
+     * table (a system user of another backend) would otherwise be asked for on every page showing it.
+     */
+    retryNotFound?: boolean;
+    /**
+     * How many ids one call of `fetchCallback` gets, each call committed on its own. Defaults to
+     * `FETCH_BY_IDS_BATCH_SIZE`. A backend that takes fewer ids a request needs its own limit here: split
+     * inside the callback, a failing part would take the parts already loaded with it.
+     */
+    batchSize?: number;
+}
+export type AddToCachedArgs<T extends DocId | IntegerId> = Array<T | null | undefined> | Array<Array<T | null | undefined> | T | null | undefined>;
+/**
+ * @template I Identifier type
+ * @template T Source type
+ * @template M Minimal type
+ */
+export declare function defineCached<I extends DocId | IntegerId, T extends Record<DocId | IntegerId, any>, M extends Record<DocId | IntegerId, any>>(mapFullToMinimal: (source: T) => M, mapIdToMinimal: (id: I) => M, fetchCallback: (ids: I[]) => Promise<T[]>, idProp?: string, maxLimit?: number, options?: DefineCachedOptions): {
+    cache: Ref<Map<I, CachedItem<M>>, Map<I, CachedItem<M>>>;
+    toFetch: Ref<Set<I>, Set<I>>;
+    fetch: () => import('@vueuse/shared').Promisify<Promise<T[]>>;
+    immediateFetch: () => Promise<T[]>;
+    add: (...args: AddToCachedArgs<I>) => void;
+    addManual: (data: T) => void;
+    addManualMinimal: (data: M) => void;
+    pin: (id: I | null | undefined) => void;
+    unpin: (id: I | null | undefined) => void;
+    has: (id: I | null | undefined) => boolean;
+    get: (id: I | null | undefined) => CachedItem<M> | undefined;
+    clear: () => void;
+    isLoaded: (id: I | null | undefined) => boolean;
+    isUnresolved: (id: I | null | undefined) => boolean;
+};

package/dist/domains/cached/composables/defineCached.js

@@ -0,0 +1,161 @@
+import { isArray as e, isUndefined as t } from "../../../shared/utils/common.js";
+import "../../../shared/statusCodes.js";
+import { isAnzuApiForbiddenError as n } from "../../../shared/error/AnzuApiForbiddenError.js";
+import { AnzuApiCancelledError as r } from "../../../shared/error/AnzuApiCancelledError.js";
+import { AuthUnavailableError as i } from "../../../shared/error/AuthUnavailableError.js";
+import { SessionExpiredError as a } from "../../../shared/error/SessionExpiredError.js";
+import { isInCauseChain as o } from "../../../shared/error/isInCauseChain.js";
+import { apiErrorStatus as s } from "../../api/utils/apiErrors.js";
+import { useSentry as c } from "../../system/composables/sentry.js";
+import { ref as l } from "vue";
+import { useDebounceFn as u } from "@vueuse/core";
+//#region src/domains/cached/composables/defineCached.ts
+var d = (e) => n(e) || s(e) === 403, f = (e) => d(e) ? "forbidden" : "error", p = (e) => d(e) || s(e) === 401 || o(e, (e) => e instanceof r || e instanceof a || e instanceof i);
+function m(n, r, i, a = "id", o = 1e3, s = {}) {
+	let { retryNotFound: d = !0 } = s, m = s.batchSize && s.batchSize >= 1 ? Math.floor(s.batchSize) : 100, h = l(/* @__PURE__ */ new Map()), g = l(/* @__PURE__ */ new Set()), _ = /* @__PURE__ */ new Map(), v = /* @__PURE__ */ new Set(), { logError: y } = c(), b = (e) => {
+		let n = h.value.get(e);
+		return t(n) ? !1 : n._unresolved !== !0 || n._unresolvedReason === "forbidden" || n._unresolvedReason === "notFound" && !d;
+	}, x = (...t) => {
+		let n = /* @__PURE__ */ new Set();
+		for (let r = 0; r < t.length; r++) {
+			let i = t[r];
+			if (i) {
+				if (e(i)) for (let e = 0; e < i.length; e++) {
+					let t = i[e];
+					t && (b(t) || n.add(t));
+				}
+				else b(i) || n.add(i);
+			}
+		}
+		n.size !== 0 && (w(n), n.forEach((e) => {
+			h.value.set(e, {
+				...r(e),
+				_loaded: !1
+			}), g.value.add(e);
+		}));
+	}, S = (e) => {
+		let t = e[a];
+		t && (w(/* @__PURE__ */ new Set([t])), h.value.set(t, {
+			...n(e),
+			_loaded: !0
+		}), g.value.delete(t));
+	}, C = (e) => {
+		let t = e[a];
+		t && (w(/* @__PURE__ */ new Set([t])), h.value.set(t, {
+			...e,
+			_loaded: !0
+		}), g.value.delete(t));
+	}, w = (e) => {
+		let t = 0;
+		if (e) for (let n of e) h.value.has(n) || (t += 1);
+		let n = h.value.size + t - o;
+		if (n <= 0) return;
+		let r = 0;
+		for (let [t, i] of h.value) {
+			if (r >= n) break;
+			e?.has(t) || _.has(t) || (i._loaded || i._unresolved) && (h.value.delete(t), r += 1);
+		}
+	}, T = (e) => {
+		w();
+		for (let t of e) h.value.set(t[a], {
+			...n(t),
+			_loaded: !0
+		});
+	}, E = (e) => {
+		for (let t of e) g.value.delete(t);
+	}, D = (e, n) => {
+		for (let r of e) {
+			let e = h.value.get(r);
+			t(e) || e._loaded || h.value.set(r, {
+				...e,
+				_unresolved: !0,
+				_unresolvedReason: n
+			});
+		}
+	}, O = async (e) => {
+		try {
+			let t = await i(e);
+			return T(t), D(e, "notFound"), w(), t;
+		} catch (t) {
+			throw D(e, f(t)), w(), t;
+		}
+	}, k = async (e) => {
+		let t = [], n = [];
+		for (let r = 0; r < e.length; r += m) try {
+			t.push(...await O(e.slice(r, r + m)));
+		} catch (e) {
+			n.push(e);
+		}
+		return {
+			items: t,
+			failures: n
+		};
+	}, A = async () => {
+		if (g.value.size === 0) return {
+			items: [],
+			failures: []
+		};
+		let e = Array.from(g.value);
+		E(e);
+		let t = k(e);
+		v.add(t);
+		try {
+			return await t;
+		} finally {
+			v.delete(t);
+		}
+	};
+	async function j() {
+		let { items: e, failures: t } = await A();
+		if (t.length > 0) throw t[0];
+		return e;
+	}
+	let M = (e) => {
+		p(e) || y(e instanceof Error ? e : Error(String(e)), {
+			level: "warning",
+			tags: { cachedFetch: "failed" }
+		});
+	}, N = u(async () => {
+		try {
+			let { items: e, failures: t } = await A();
+			return t.forEach(M), e;
+		} catch (e) {
+			return M(e), [];
+		}
+	}, 1500, { maxWait: 5e3 });
+	return {
+		cache: h,
+		toFetch: g,
+		fetch: () => N(),
+		immediateFetch: async () => {
+			let e = Array.from(v), t = await j(), n = await Promise.all(e);
+			return [...t, ...n.flatMap((e) => e.items)];
+		},
+		add: x,
+		addManual: S,
+		addManualMinimal: C,
+		pin: (e) => {
+			e && _.set(e, (_.get(e) ?? 0) + 1);
+		},
+		unpin: (e) => {
+			if (!e) return;
+			let n = _.get(e);
+			t(n) || (n > 1 ? _.set(e, n - 1) : (_.delete(e), w()));
+		},
+		has: (e) => e ? h.value.has(e) : !1,
+		get: (e) => {
+			if (e) return h.value.get(e);
+		},
+		clear: () => h.value.clear(),
+		isLoaded: (e) => {
+			if (!e) return !1;
+			let t = h.value.get(e);
+			return t ? t._loaded : !1;
+		},
+		isUnresolved: (e) => e ? h.value.get(e)?._unresolved === !0 : !1
+	};
+}
+//#endregion
+export { m as defineCached };
+
+//# sourceMappingURL=defineCached.js.map

package/dist/domains/cached/composables/defineCached.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"defineCached.js","names":["isForbidden","isAnzuApiForbiddenError","error","apiErrorStatus","unresolvedReason","isQuiet","isInCauseChain","cause","AnzuApiCancelledError","SessionExpiredError","AuthUnavailableError","defineCached","options","batchSize","cache","ref","toFetch","pinned","inFlight","useSentry","isCached","item","id","isUndefined","retryNotFound","add","args","toAdd","i","arg","isArray","j","prune","mapIdToMinimal","addManual","data","idProp","mapFullToMinimal","addManualMinimal","incoming","protectedIds","overflow","maxLimit","removed","key","value","updateMap","updateToFetch","ids","markUnresolved","reason","fetchBatch","res","fetchCallback","runBatches","items","failures","start","runQueue","run","apiFetch","logFailure","logError","debouncedFetch","useDebounceFn","pending","own","others","other","count"],"sources":["../../../../src/domains/cached/composables/defineCached.ts"],"sourcesContent":["import { type Ref, ref } from 'vue'\nimport { useDebounceFn } from '@vueuse/core'\nimport type { DocId, IntegerId } from '@/shared/types/common'\nimport { isArray, isUndefined } from '@/shared/utils/common'\nimport { useSentry } from '@/domains/system/composables/sentry'\nimport { apiErrorStatus } from '@/domains/api/utils/apiErrors'\nimport { FETCH_BY_IDS_BATCH_SIZE } from '@/domains/api/composables/useApiFetchByIds'\nimport { isAnzuApiForbiddenError } from '@/shared/error/AnzuApiForbiddenError'\nimport { AnzuApiCancelledError } from '@/shared/error/AnzuApiCancelledError'\nimport { SessionExpiredError } from '@/shared/error/SessionExpiredError'\nimport { AuthUnavailableError } from '@/shared/error/AuthUnavailableError'\nimport { isInCauseChain } from '@/shared/error/isInCauseChain'\nimport { HTTP_STATUS_FORBIDDEN, HTTP_STATUS_UNAUTHORIZED } from '@/shared/statusCodes'\n\n/**\n * Why a fetch settled without resolving an item:\n * - `notFound` -- the server answered and the item was not among the results,\n * - `forbidden` -- the user may not read it (403); asking again in this session cannot change that,\n * - `error` -- anything else: the network, a timeout, a 5xx, a 401 before the session is renewed, and a\n *   404 of the whole request, which is a route or a proxy answering rather than an item missing.\n */\nexport type CachedUnresolvedReason = 'notFound' | 'forbidden' | 'error'\n\n/**\n * `_unresolved`: the fetch settled without resolving the item, `_unresolvedReason` says why.\n * Whether a later `add()` asks again depends on the reason (see `defineCached`).\n */\nexport type CachedItem<T extends object> = T & {\n  _loaded: boolean\n  _unresolved?: boolean\n  _unresolvedReason?: CachedUnresolvedReason\n}\n\nexport interface DefineCachedOptions {\n  /**\n   * Ask again, on the next `add()`, for an id the server did not return. Defaults to `true`: an entity\n   * can be created after the first lookup. A cache of users passes `false` -- an id missing from the\n   * table (a system user of another backend) would otherwise be asked for on every page showing it.\n   */\n  retryNotFound?: boolean\n  /**\n   * How many ids one call of `fetchCallback` gets, each call committed on its own. Defaults to\n   * `FETCH_BY_IDS_BATCH_SIZE`. A backend that takes fewer ids a request needs its own limit here: split\n   * inside the callback, a failing part would take the parts already loaded with it.\n   */\n  batchSize?: number\n}\n\n// A rejected 403 arrives mapped as `AnzuApiForbiddenError`, which carries no status of its own.\nconst isForbidden = (error: unknown) =>\n  isAnzuApiForbiddenError(error) || apiErrorStatus(error) === HTTP_STATUS_FORBIDDEN\n\nconst unresolvedReason = (error: unknown): CachedUnresolvedReason => (isForbidden(error) ? 'forbidden' : 'error')\n\n/**\n * Not a failure to write down: the user may not (403), nobody is logged in (401, or a session found\n * gone on the way out), the auth service did not answer, or the request was stopped. The api layer\n * keeps 401, 403 and an expired session out of its log itself, and writes an unavailable auth service\n * down with the request it stopped; for a cache all of them are the session, not the fetch.\n */\nconst isQuiet = (error: unknown) =>\n  isForbidden(error) ||\n  apiErrorStatus(error) === HTTP_STATUS_UNAUTHORIZED ||\n  isInCauseChain(\n    error,\n    (cause) =>\n      cause instanceof AnzuApiCancelledError ||\n      cause instanceof SessionExpiredError ||\n      cause instanceof AuthUnavailableError\n  )\n\nexport type AddToCachedArgs<T extends DocId | IntegerId> =\n  | Array<T | null | undefined>\n  | Array<Array<T | null | undefined> | T | null | undefined>\n\n/**\n * @template I Identifier type\n * @template T Source type\n * @template M Minimal type\n */\nexport function defineCached<\n  I extends DocId | IntegerId,\n  T extends Record<DocId | IntegerId, any>,\n  M extends Record<DocId | IntegerId, any>,\n>(\n  mapFullToMinimal: (source: T) => M,\n  mapIdToMinimal: (id: I) => M,\n  fetchCallback: (ids: I[]) => Promise<T[]>,\n  idProp = 'id',\n  maxLimit = 1000,\n  options: DefineCachedOptions = {}\n) {\n  const { retryNotFound = true } = options\n  const batchSize =\n    options.batchSize && options.batchSize >= 1 ? Math.floor(options.batchSize) : FETCH_BY_IDS_BATCH_SIZE\n  const cache: Ref<Map<I, CachedItem<M>>> = ref(new Map())\n  const toFetch = ref(new Set()) as Ref<Set<I>>\n  // The ids something shows, each with how many show it (`pin`): the cache drops none of them to stay within its\n  // limit, and goes over it while more than that many are shown. Dropped, a name a chip showed turned it into a\n  // spinner till something added the id again.\n  const pinned = new Map<I, number>()\n  // Settles, never rejects: a run that failed still hands over what its earlier batches loaded.\n  const inFlight = new Set<Promise<{ items: T[]; failures: unknown[] }>>()\n  const { logError } = useSentry()\n\n  /**\n   * Unresolved items are never retried from the queue itself, only on the next `add()`, and only\n   * when asking again can help: a failure (`error`) always, a missing item (`notFound`) unless the\n   * cache opted out, a forbidden one never.\n   */\n  const isCached = (id: I) => {\n    const item = cache.value.get(id)\n    if (isUndefined(item)) return false\n    if (item._unresolved !== true) return true\n    if (item._unresolvedReason === 'forbidden') return true\n    if (item._unresolvedReason === 'notFound') return !retryNotFound\n    return false\n  }\n\n  // Falsy, not only null/undefined: `get`, `has` and `isLoaded` treat 0 and '' as no id, and a blank\n  // factory record (`createdBy: 0`) would otherwise be sent to the server as `filter_in[id]=0`.\n  const add = (...args: AddToCachedArgs<I>) => {\n    const toAdd = new Set<I>()\n    for (let i = 0; i < args.length; i++) {\n      const arg = args[i]\n      if (!arg) continue\n      if (isArray(arg)) {\n        for (let j = 0; j < arg.length; j++) {\n          const item = arg[j]\n          if (!item) continue\n          if (!isCached(item)) toAdd.add(item)\n        }\n        continue\n      }\n      if (!isCached(arg)) toAdd.add(arg)\n    }\n    if (toAdd.size === 0) return\n    prune(toAdd)\n    toAdd.forEach((id) => {\n      cache.value.set(id, {\n        ...mapIdToMinimal(id),\n        _loaded: false,\n      })\n      toFetch.value.add(id)\n    })\n  }\n\n  // Out of the queue as well: an id added and then supplied by hand would still be fetched, and the\n  // answer would overwrite what the caller just put in.\n  const addManual = (data: T) => {\n    const id = data[idProp] as I\n    if (!id) return\n    prune(new Set([id]))\n    cache.value.set(id, {\n      ...mapFullToMinimal(data),\n      _loaded: true,\n    })\n    toFetch.value.delete(id)\n  }\n\n  const addManualMinimal = (data: M) => {\n    const id = data[idProp] as I\n    if (!id) return\n    prune(new Set([id]))\n    cache.value.set(id, {\n      ...data,\n      _loaded: true,\n    })\n    toFetch.value.delete(id)\n  }\n\n  /**\n   * Drops only as many oldest terminal entries as the overflow requires; dropping every one\n   * of them would send currently rendered chips back to their loading state. A pinned entry is\n   * never dropped.\n   * Must include `_unresolved`, otherwise repeated failures grow the cache past `maxLimit`.\n   */\n  const prune = (protectedIds?: Set<I>) => {\n    let incoming = 0\n    if (protectedIds) {\n      // Re-queued unresolved ids are already in the cache and do not grow it.\n      for (const id of protectedIds) if (!cache.value.has(id)) incoming += 1\n    }\n    const overflow = cache.value.size + incoming - maxLimit\n    if (overflow <= 0) return\n    let removed = 0\n    for (const [key, value] of cache.value) {\n      if (removed >= overflow) break\n      if (protectedIds?.has(key) || pinned.has(key)) continue\n      if (value._loaded || value._unresolved) {\n        cache.value.delete(key)\n        removed += 1\n      }\n    }\n  }\n\n  const updateMap = (data: T[]) => {\n    prune()\n    for (const item of data) {\n      cache.value.set(item[idProp] as I, {\n        ...mapFullToMinimal(item),\n        _loaded: true,\n      })\n    }\n  }\n\n  const updateToFetch = (ids: Array<I>) => {\n    for (const id of ids) {\n      toFetch.value.delete(id)\n    }\n  }\n\n  const markUnresolved = (ids: Array<I>, reason: CachedUnresolvedReason) => {\n    for (const id of ids) {\n      const item = cache.value.get(id)\n      if (isUndefined(item) || item._loaded) continue\n      cache.value.set(id, { ...item, _unresolved: true, _unresolvedReason: reason })\n    }\n  }\n\n  const fetchBatch = async (ids: I[]): Promise<T[]> => {\n    try {\n      // Awaited inside the `try`: a callback that throws before it returns a promise (a dam client\n      // that is not configured) has to settle its ids too, or they would spin for good.\n      const res = await fetchCallback(ids)\n      updateMap(res)\n      markUnresolved(ids, 'notFound')\n      // Back within the limit once the batch is settled: the ids added and still on their way could not be dropped\n      // till then, and a large add left the cache over its limit for good, also when the batch failed.\n      prune()\n      return res\n    } catch (error: unknown) {\n      markUnresolved(ids, unresolvedReason(error))\n      prune()\n      throw error\n    }\n  }\n\n  // In the batches the api helpers would split the request into anyway, one after another, each\n  // committed on its own: a failing batch leaves the ones before it loaded instead of taking them along.\n  const runBatches = async (ids: I[]) => {\n    const items: T[] = []\n    const failures: unknown[] = []\n    for (let start = 0; start < ids.length; start += batchSize) {\n      try {\n        items.push(...(await fetchBatch(ids.slice(start, start + batchSize))))\n      } catch (error: unknown) {\n        failures.push(error)\n      }\n    }\n    return { items, failures }\n  }\n\n  /** Fetches the queue; settles with what loaded and every batch's failure, never rejects. */\n  const runQueue = async () => {\n    if (toFetch.value.size === 0) return { items: [] as T[], failures: [] as unknown[] }\n    const ids = Array.from(toFetch.value)\n    // Drained before the request, not after it. A batch that starts while this one is in flight --\n    // a slow answer outlasting the debounce, the `maxWait` timer, an `immediateFetch()` -- would\n    // otherwise send the same ids again. Draining at all keeps a failing batch from being resent.\n    updateToFetch(ids)\n    const run = runBatches(ids)\n    inFlight.add(run)\n    try {\n      return await run\n    } finally {\n      inFlight.delete(run)\n    }\n  }\n\n  async function apiFetch() {\n    const { items, failures } = await runQueue()\n    if (failures.length > 0) throw failures[0]\n    return items\n  }\n\n  const logFailure = (error: unknown) => {\n    if (isQuiet(error)) return\n    logError(error instanceof Error ? error : new Error(String(error)), {\n      level: 'warning',\n      tags: { cachedFetch: 'failed' },\n    })\n  }\n\n  // Caught inside the debounced callback, not on the promise it returns: the maxWait timer\n  // is a second invocation path whose promise never reaches the caller, so a rejection\n  // there would escape as an unhandled rejection.\n  const debouncedFetch = useDebounceFn(\n    async () => {\n      try {\n        // Every batch's failure, not only the first: a 403 in one would otherwise hide a timeout in\n        // the next.\n        const { items, failures } = await runQueue()\n        failures.forEach(logFailure)\n        return items\n      } catch (error: unknown) {\n        logFailure(error)\n        return [] as T[]\n      }\n    },\n    1500,\n    { maxWait: 5000 }\n  )\n\n  /**\n   * Debounced fetch for best performance.\n   * For general usage.\n   *\n   * Called fire-and-forget, so it never rejects. Use `immediateFetch()` to handle errors.\n   */\n  const fetch = () => {\n    return debouncedFetch()\n  }\n\n  /**\n   * Immediate fetch with no debounce and with result in promise.\n   * Use for special cases.\n   *\n   * Waits for the batches already in flight as well and resolves with their items: their ids are out\n   * of the queue, and a caller reading the result (to add the relations of what it fetched) would miss\n   * them. It rejects only when its own batch fails; an id whose batch in flight failed is not in the\n   * result -- check `isUnresolved(id)` for it.\n   */\n  const immediateFetch = async () => {\n    const pending = Array.from(inFlight)\n    const own = await apiFetch()\n    const others = await Promise.all(pending)\n    return [...own, ...others.flatMap((other) => other.items)]\n  }\n\n  /** Something shows the item of `id`: the cache keeps it till as many `unpin` have come. */\n  const pin = (id: I | null | undefined) => {\n    if (!id) return\n    pinned.set(id, (pinned.get(id) ?? 0) + 1)\n  }\n\n  /** What showed the item of `id` no longer does. The cache goes back within its limit once none is left. */\n  const unpin = (id: I | null | undefined) => {\n    if (!id) return\n    const count = pinned.get(id)\n    if (isUndefined(count)) return\n    if (count > 1) {\n      pinned.set(id, count - 1)\n      return\n    }\n    pinned.delete(id)\n    prune()\n  }\n\n  const get = (id: I | null | undefined) => {\n    if (!id) return undefined\n    return cache.value.get(id)\n  }\n\n  const has = (id: I | null | undefined): boolean => {\n    if (!id) return false\n    return cache.value.has(id)\n  }\n\n  const clear = () => {\n    return cache.value.clear()\n  }\n\n  const isLoaded = (id: I | null | undefined): boolean => {\n    if (!id) return false\n    const item = cache.value.get(id)\n    if (!item) return false\n    return item._loaded\n  }\n\n  /** Terminal counterpart of `isLoaded`: the fetch settled without resolving the item. */\n  const isUnresolved = (id: I | null | undefined): boolean => {\n    if (!id) return false\n    return cache.value.get(id)?._unresolved === true\n  }\n\n  return {\n    cache,\n    toFetch,\n    fetch,\n    immediateFetch,\n    add,\n    addManual,\n    addManualMinimal,\n    pin,\n    unpin,\n    has,\n    get,\n    clear,\n    isLoaded,\n    isUnresolved,\n  }\n}\n"],"mappings":"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"}

package/dist/domains/cached/composables/useCachedItem.d.ts

@@ -0,0 +1,26 @@
+import { ComputedRef } from 'vue';
+import { DocId, IntegerId } from '../../../shared/types/common';
+/** How a component that shows an item of a cache keeps it there, and has it asked for (`useCachedItem`). */
+export interface CachedItemPinning<I extends DocId | IntegerId> {
+    /** The id the component shows the item of; none while it shows none (it is given a title of its own). */
+    id: () => I | null | undefined;
+    /** `pin` and `unpin` of the cache (`defineCached`). */
+    pin: (id: I) => void;
+    unpin: (id: I) => void;
+    /** Adds the id to the cache and has it fetched, for an id the cache does not have: one its page never added. */
+    askFor: (id: I) => void;
+}
+/**
+ * `pinning`: the item shown is pinned in its cache while the component shows it, from the start and across a change
+ * of its id, and let go as the component goes. The cache, which keeps 1 000 items, drops no pinned one: a chip whose
+ * name it had dropped spun till something added the id again. An id the cache does not have is asked for once, as it
+ * is shown.
+ */
+export declare function useCachedItem<T extends {
+    _loaded?: boolean;
+    _unresolved?: boolean;
+}, I extends DocId | IntegerId = DocId | IntegerId>(getter: () => T | undefined, pinning?: CachedItemPinning<I>): {
+    cached: ComputedRef<T | undefined>;
+    loaded: ComputedRef<boolean>;
+    unresolved: ComputedRef<boolean>;
+};

package/dist/domains/cached/composables/useCachedItem.js

@@ -0,0 +1,26 @@
+import { computed as e, onScopeDispose as t, watch as n } from "vue";
+//#region src/domains/cached/composables/useCachedItem.ts
+function r(r, i) {
+	if (i) {
+		let e = null;
+		n(i.id, (t) => {
+			let n = e;
+			e = t || null, e && i.pin(e), n && i.unpin(n), e && r() === void 0 && i.askFor(e);
+		}, { immediate: !0 }), t(() => {
+			e && i.unpin(e), e = null;
+		});
+	}
+	let a = e(() => {
+		let e = r();
+		if (e) return e._loaded !== !1 || e._unresolved === !0 ? e : void 0;
+	});
+	return {
+		cached: a,
+		loaded: e(() => a.value !== void 0),
+		unresolved: e(() => a.value?._unresolved === !0)
+	};
+}
+//#endregion
+export { r as useCachedItem };
+
+//# sourceMappingURL=useCachedItem.js.map

package/dist/domains/cached/composables/useCachedItem.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useCachedItem.js","names":["useCachedItem","pinning","shown","watch","before","id","getter","onScopeDispose","cached","computed","value"],"sources":["../../../../src/domains/cached/composables/useCachedItem.ts"],"sourcesContent":["import { type ComputedRef, computed, onScopeDispose, watch } from 'vue'\nimport type { DocId, IntegerId } from '@/shared/types/common'\n\n/** How a component that shows an item of a cache keeps it there, and has it asked for (`useCachedItem`). */\nexport interface CachedItemPinning<I extends DocId | IntegerId> {\n  /** The id the component shows the item of; none while it shows none (it is given a title of its own). */\n  id: () => I | null | undefined\n  /** `pin` and `unpin` of the cache (`defineCached`). */\n  pin: (id: I) => void\n  unpin: (id: I) => void\n  /** Adds the id to the cache and has it fetched, for an id the cache does not have: one its page never added. */\n  askFor: (id: I) => void\n}\n\n/**\n * `pinning`: the item shown is pinned in its cache while the component shows it, from the start and across a change\n * of its id, and let go as the component goes. The cache, which keeps 1 000 items, drops no pinned one: a chip whose\n * name it had dropped spun till something added the id again. An id the cache does not have is asked for once, as it\n * is shown.\n */\nexport function useCachedItem<\n  T extends { _loaded?: boolean; _unresolved?: boolean },\n  I extends DocId | IntegerId = DocId | IntegerId,\n>(\n  getter: () => T | undefined,\n  pinning?: CachedItemPinning<I>\n): { cached: ComputedRef<T | undefined>; loaded: ComputedRef<boolean>; unresolved: ComputedRef<boolean> } {\n  if (pinning) {\n    let shown: I | null = null\n    watch(\n      pinning.id,\n      (id) => {\n        // The new one first: let go first, the one shown before could have the new one dropped.\n        const before = shown\n        shown = id || null\n        if (shown) pinning.pin(shown)\n        if (before) pinning.unpin(before)\n        if (shown && getter() === undefined) pinning.askFor(shown)\n      },\n      { immediate: true }\n    )\n    onScopeDispose(() => {\n      if (shown) pinning.unpin(shown)\n      shown = null\n    })\n  }\n  const cached = computed<T | undefined>(() => {\n    const value = getter()\n    if (!value) return undefined\n    // `_unresolved` settles the item: return the placeholder so consumers stop showing a spinner.\n    return value._loaded !== false || value._unresolved === true ? value : undefined\n  })\n  const loaded = computed(() => cached.value !== undefined)\n  // Apart from `loaded`, because the placeholder is all an unresolved item has: a consumer reading\n  // its fields would draw an empty chip.\n  const unresolved = computed(() => cached.value?._unresolved === true)\n\n  return { cached, loaded, unresolved }\n}\n"],"mappings":";;AAoBA,SAAgBA,EAId,GACA,GACwG;CACxG,IAAIC,GAAS;EACX,IAAIC,IAAkB;EAatB,AAZAC,EACEF,EAAQ,KACP,MAAO;GAEN,IAAMG,IAASF;GAIf,AAHA,IAAQG,KAAM,MACVH,KAAOD,EAAQ,IAAIC,CAAK,GACxBE,KAAQH,EAAQ,MAAMG,CAAM,GAC5BF,KAASI,EAAO,MAAM,KAAA,KAAWL,EAAQ,OAAOC,CAAK;EAC3D,GACA,EAAE,WAAW,GAAK,CACpB,GACAK,QAAqB;GAEnB,AADIL,KAAOD,EAAQ,MAAMC,CAAK,GAC9B,IAAQ;EACV,CAAC;CACH;CACA,IAAMM,IAASC,QAA8B;EAC3C,IAAMC,IAAQJ,EAAO;EACrB,IAAKI,GAEL,OAAOA,EAAM,YAAY,MAASA,EAAM,gBAAgB,KAAOA,IAAQ,KAAA;CACzE,CAAC;CAMD,OAAO;EAAE;EAAQ,QALFD,QAAeD,EAAO,UAAU,KAAA,CAK9B;EAAQ,YAFNC,QAAeD,EAAO,OAAO,gBAAgB,EAEvC;CAAW;AACtC"}

package/dist/domains/collab/components/ACollabCountdown.js

@@ -0,0 +1,7 @@
+import e from "./ACollabCountdown.vue_vue_type_script_setup_true_lang.js";
+//#region src/domains/collab/components/ACollabCountdown.vue
+var t = e;
+//#endregion
+export { t as default };
+
+//# sourceMappingURL=ACollabCountdown.js.map

package/dist/domains/collab/components/ACollabCountdown.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ACollabCountdown.js","names":["_sfc_main","ACollabCountdown_vue_vue_type_script_setup_true_lang_default","ACollabCountdown_default"],"sources":["../../../../src/domains/collab/components/ACollabCountdown.vue"],"sourcesContent":["<script setup lang=\"ts\">\nimport { onMounted, onUnmounted, type Ref, ref, watch } from 'vue'\n\nconst props = withDefaults(\n  defineProps<{\n    label?: string\n    seconds?: number\n    parentheses?: boolean\n  }>(),\n  {\n    label: '',\n    seconds: 60,\n    parentheses: false,\n  }\n)\nconst emit = defineEmits<{\n  (e: 'done'): void\n}>()\n\n// eslint-disable-next-line vue/no-setup-props-reactivity-loss\nconst countdown = ref(props.seconds)\nconst countdownTimer: Ref<ReturnType<typeof setTimeout> | undefined> = ref(undefined)\n\nwatch(\n  countdown,\n  (newValue) => {\n    if (newValue > 0) {\n      countdownTimer.value = setTimeout(() => countdown.value--, 1000)\n    } else {\n      emit('done')\n    }\n  },\n  { immediate: true }\n)\n\nonMounted(() => {\n  countdown.value = props.seconds\n})\n\nonUnmounted(() => {\n  clearTimeout(countdownTimer.value)\n  countdownTimer.value = undefined\n})\n</script>\n\n<template>\n  <span>\n    <span v-if=\"parentheses\">(</span>\n    <span\n      v-if=\"label\"\n      class=\"font-weight-bold mr-1\"\n      >{{ label }}\n    </span>\n    <span>{{ countdown }}</span>\n    <span v-if=\"parentheses\">)</span>\n  </span>\n</template>\n"],"mappings":""}

package/dist/domains/collab/components/ACollabCountdown.vue.d.ts

@@ -0,0 +1,16 @@
+type __VLS_Props = {
+    label?: string;
+    seconds?: number;
+    parentheses?: boolean;
+};
+declare const __VLS_export: import('vue').DefineComponent<__VLS_Props, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {} & {
+    done: () => any;
+}, string, import('vue').PublicProps, Readonly<__VLS_Props> & Readonly<{
+    onDone?: (() => any) | undefined;
+}>, {
+    label: string;
+    seconds: number;
+    parentheses: boolean;
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/domains/collab/components/ACollabCountdown.vue_vue_type_script_setup_true_lang.js

@@ -0,0 +1,36 @@
+import { createCommentVNode as e, createElementBlock as t, createElementVNode as n, defineComponent as r, onMounted as i, onUnmounted as a, openBlock as o, ref as s, toDisplayString as c, watch as l } from "vue";
+//#region src/domains/collab/components/ACollabCountdown.vue?vue&type=script&setup=true&lang.ts
+var u = { key: 0 }, d = {
+	key: 1,
+	class: "font-weight-bold mr-1"
+}, f = { key: 2 }, p = /*@__PURE__*/ r({
+	__name: "ACollabCountdown",
+	props: {
+		label: { default: "" },
+		seconds: { default: 60 },
+		parentheses: {
+			type: Boolean,
+			default: !1
+		}
+	},
+	emits: ["done"],
+	setup(r, { emit: p }) {
+		let m = r, h = p, g = s(m.seconds), _ = s(void 0);
+		return l(g, (e) => {
+			e > 0 ? _.value = setTimeout(() => g.value--, 1e3) : h("done");
+		}, { immediate: !0 }), i(() => {
+			g.value = m.seconds;
+		}), a(() => {
+			clearTimeout(_.value), _.value = void 0;
+		}), (i, a) => (o(), t("span", null, [
+			r.parentheses ? (o(), t("span", u, "(")) : e("", !0),
+			r.label ? (o(), t("span", d, c(r.label), 1)) : e("", !0),
+			n("span", null, c(g.value), 1),
+			r.parentheses ? (o(), t("span", f, ")")) : e("", !0)
+		]));
+	}
+});
+//#endregion
+export { p as default };
+
+//# sourceMappingURL=ACollabCountdown.vue_vue_type_script_setup_true_lang.js.map

package/dist/domains/collab/components/ACollabCountdown.vue_vue_type_script_setup_true_lang.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ACollabCountdown.vue_vue_type_script_setup_true_lang.js","names":["_openBlock","_createElementBlock","_createCommentVNode","_toDisplayString","_createElementVNode","_hoisted_1","_hoisted_2","_hoisted_3","ACollabCountdown_vue_vue_type_script_setup_true_lang_default","__emit","props","__props","emit","countdown","ref","countdownTimer","watch","newValue","onMounted","onUnmounted","openBlock","createElementBlock","createCommentVNode","toDisplayString","createElementVNode"],"sources":["../../../../src/domains/collab/components/ACollabCountdown.vue"],"sourcesContent":["<script setup lang=\"ts\">\nimport { onMounted, onUnmounted, type Ref, ref, watch } from 'vue'\n\nconst props = withDefaults(\n  defineProps<{\n    label?: string\n    seconds?: number\n    parentheses?: boolean\n  }>(),\n  {\n    label: '',\n    seconds: 60,\n    parentheses: false,\n  }\n)\nconst emit = defineEmits<{\n  (e: 'done'): void\n}>()\n\n// eslint-disable-next-line vue/no-setup-props-reactivity-loss\nconst countdown = ref(props.seconds)\nconst countdownTimer: Ref<ReturnType<typeof setTimeout> | undefined> = ref(undefined)\n\nwatch(\n  countdown,\n  (newValue) => {\n    if (newValue > 0) {\n      countdownTimer.value = setTimeout(() => countdown.value--, 1000)\n    } else {\n      emit('done')\n    }\n  },\n  { immediate: true }\n)\n\nonMounted(() => {\n  countdown.value = props.seconds\n})\n\nonUnmounted(() => {\n  clearTimeout(countdownTimer.value)\n  countdownTimer.value = undefined\n})\n</script>\n\n<template>\n  <span>\n    <span v-if=\"parentheses\">(</span>\n    <span\n      v-if=\"label\"\n      class=\"font-weight-bold mr-1\"\n      >{{ label }}\n    </span>\n    <span>{{ countdown }}</span>\n    <span v-if=\"parentheses\">)</span>\n  </span>\n</template>\n"],"mappings":";;;;;;;;;;;;;;;;;EAGA,IAAMU,IAAQC,GAYRC,IAAOH,GAKPI,IAAYC,EAAIJ,EAAM,OAAO,GAC7BK,IAAiED,EAAI,KAAA,CAAS;E,OAEpFE,EACEH,IACC,MAAa;GACZ,AAAII,IAAW,IACb,EAAe,QAAQ,iBAAiB,EAAU,SAAS,GAAI,IAE/DL,EAAK,MAAM;EAEf,GACA,EAAE,WAAW,GAAK,CACpB,GAEAM,QAAgB;GACd,EAAU,QAAQR,EAAM;EAC1B,CAAC,GAEDS,QAAkB;GAEhB,AADA,aAAaJ,EAAe,KAAK,GACjC,EAAe,QAAQ,KAAA;EACzB,CAAC,I,UAICf,EAAA,GAAAC,EASO,QAAA,MAAA;GAROU,EAAA,eAAZX,EAAA,GAAAC,EAAiC,QAAAI,GAAR,GAAC,K;GAElBM,EAAA,SADRX,EAAA,GAAAC,EAIO,QAJPK,GAIOH,EADDQ,EAAA,KAAK,GAAA,CAAA,K;GAEXP,EAA4B,QAAA,MAAAD,EAAnBU,EAAA,KAAS,GAAA,CAAA;GACNF,EAAA,eAAZX,EAAA,GAAAC,EAAiC,QAAAM,GAAR,GAAC,K"}

package/dist/domains/collab/components/ACollabLockedByUser.js

@@ -0,0 +1,7 @@
+import e from "./ACollabLockedByUser.vue_vue_type_script_setup_true_lang.js";
+//#region src/domains/collab/components/ACollabLockedByUser.vue
+var t = e;
+//#endregion
+export { t as default };
+
+//# sourceMappingURL=ACollabLockedByUser.js.map

package/dist/domains/collab/components/ACollabLockedByUser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ACollabLockedByUser.js","names":["_sfc_main","ACollabLockedByUser_vue_vue_type_script_setup_true_lang_default","ACollabLockedByUser_default"],"sources":["../../../../src/domains/collab/components/ACollabLockedByUser.vue"],"sourcesContent":["<script lang=\"ts\" setup>\nimport { computed, type Ref, shallowRef, unref, watch } from 'vue'\nimport AAnzuUserAvatar from '@/domains/ui/components/AAnzuUserAvatar.vue'\nimport { isNull, isNumber, isUndefined } from '@/shared/utils/common'\nimport type { CollabCachedUsersMap } from '@/domains/collab/composables/collabHelpers'\nimport type { IntegerId } from '@/shared/types/common'\nimport type { AnzuUserMinimal } from '@/shared/types/AnzuUser'\nimport { useI18n } from 'vue-i18n'\n\nconst props = withDefaults(\n  defineProps<{\n    id: null | undefined | IntegerId\n    users: CollabCachedUsersMap | Ref<CollabCachedUsersMap>\n    isModerator?: boolean\n  }>(),\n  {\n    isModerator: false,\n  }\n)\n\nconst cached = shallowRef<undefined | AnzuUserMinimal>(undefined)\nconst loaded = shallowRef<boolean>(false)\n\n// eslint-disable-next-line vue/no-setup-props-reactivity-loss\nconst cachedUsers = unref(props.users)\nconst { t } = useI18n()\n\nconst item = computed(() => {\n  if (isNumber(props.id) && props.id > 0) {\n    return cachedUsers.get(props.id)\n  }\n  return undefined\n})\n\nconst tooltip = computed(() => {\n  let prefix = ''\n  if (props.isModerator) {\n    prefix = t('common.collab.moderator') + ': '\n  }\n  if (item.value) {\n    return item.value.person.fullName.length\n      ? prefix + item.value.person.fullName\n      : prefix + item.value.email.split('@')[0]\n  }\n  return undefined\n})\n\nwatch(\n  item,\n  (newValue) => {\n    // Same user still loaded: keep it. A user the cache resolves later (after an `_unresolved` placeholder)\n    // arrives as a new, loaded object under the same id and replaces the placeholder.\n    if (loaded.value && cached.value?.id === newValue?.id && !newValue?._loaded) return\n    loaded.value = false\n    cached.value = undefined\n    if (isUndefined(newValue) || (!newValue._loaded && newValue._unresolved !== true)) return\n    cached.value = newValue\n    loaded.value = true\n  },\n  { immediate: true }\n)\n</script>\n\n<template>\n  <div class=\"d-inline-flex\">\n    <span v-if=\"isNull(id) || isUndefined(id)\" />\n    <template v-else-if=\"loaded\">\n      <VBadge\n        v-if=\"isModerator\"\n        location=\"top right\"\n        color=\"white\"\n        :width=\"12\"\n        :min-width=\"12\"\n        :height=\"14\"\n        :offset-x=\"-5\"\n        :offset-y=\"-5\"\n      >\n        <template #badge>\n          <VIcon\n            color=\"grey-darken-2\"\n            :size=\"14\"\n            icon=\"mdi-crown\"\n          />\n        </template>\n        <AAnzuUserAvatar\n          :user=\"cached ?? undefined\"\n          :size=\"20\"\n          :tooltip=\"tooltip\"\n        />\n      </VBadge>\n      <AAnzuUserAvatar\n        v-else\n        :user=\"cached ?? undefined\"\n        :size=\"20\"\n        :tooltip=\"tooltip\"\n      />\n    </template>\n    <VProgressCircular\n      v-else\n      :size=\"12\"\n      :width=\"2\"\n      indeterminate\n      class=\"ml-auto mr-auto\"\n    />\n  </div>\n</template>\n"],"mappings":""}

package/dist/domains/collab/components/ACollabLockedByUser.vue.d.ts

@@ -0,0 +1,13 @@
+import { Ref } from 'vue';
+import { CollabCachedUsersMap } from '../composables/collabHelpers';
+import { IntegerId } from '../../../shared/types/common';
+type __VLS_Props = {
+    id: null | undefined | IntegerId;
+    users: CollabCachedUsersMap | Ref<CollabCachedUsersMap>;
+    isModerator?: boolean;
+};
+declare const __VLS_export: import('vue').DefineComponent<__VLS_Props, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {
+    isModerator: boolean;
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;