@equinor/fusion-framework-react-components-people-provider 2.0.2 → 2.0.4

package/dist/types/PeopleResolverComponent.d.ts

@@ -0,0 +1,22 @@
+import { type PropsWithChildren } from 'react';
+import { PersonProviderElement, type PersonResolver } from '@equinor/fusion-wc-person';
+export { PersonResolver } from '@equinor/fusion-wc-person';
+declare module 'react' {
+    namespace JSX {
+        interface IntrinsicElements {
+            'fwc-person-provider': React.DetailedHTMLProps<React.HTMLAttributes<PersonProviderElement>, PersonProviderElement>;
+        }
+    }
+}
+/**
+ * Wraps the `fwc-person-provider` web component, wiring the given `PersonResolver` into it
+ * once the underlying custom element is ready.
+ *
+ * @param props - Component props
+ * @param props.resolver - The resolver used to fetch person data, photos, and search results
+ * @param props.children - Elements rendered inside the person provider, typically person-related components
+ * @returns The rendered `fwc-person-provider` element wrapping the given children
+ */
+export declare const PeopleResolverComponent: (props: PropsWithChildren<{
+    resolver: PersonResolver;
+}>) => import("react").JSX.Element;

package/dist/types/PeopleResolverProvider.d.ts

@@ -4,5 +4,16 @@ type PeopleResolverProviderProps = PropsWithChildren<{
     readonly options?: PersonControllerOptions;
     readonly fallback?: ReactNode;
 }>;
-export declare const PeopleResolverProvider: (props: PeopleResolverProviderProps) => import("react/jsx-runtime").JSX.Element;
+/**
+ * Provides person resolution to its children by wiring up a `PersonResolver` built from the
+ * framework's `services` module.
+ *
+ * @param props - Component props
+ * @param props.children - Elements that will have access to the person resolver
+ * @param props.options - Optional controller options, such as a fallback image for missing photos
+ * @param props.fallback - Optional fallback rendered while the resolver component is suspended
+ * @returns The rendered people resolver provider wrapping the given children
+ * @throws Error if the `services` module has not been registered on the framework
+ */
+export declare const PeopleResolverProvider: (props: PeopleResolverProviderProps) => import("react").JSX.Element;
 export default PeopleResolverProvider;

package/dist/types/PersonController.d.ts

@@ -41,13 +41,25 @@ export interface IPersonController {
 export type PersonControllerOptions = {
     fallbackImage?: Blob;
 };
+/**
+ * Default implementation of {@link IPersonController}, backed by a {@link PeopleApiClient} and
+ * a set of {@link Query} caches for people, searches, photos, suggestions, and resolves.
+ */
 export declare class PersonController implements IPersonController {
     #private;
+    /**
+     * @param client - The people API client used to fetch person data, photos, and search results
+     * @param options - Optional controller options, such as a fallback image for missing photos
+     * @throws Error if the photo request fails for a reason other than a fallback-eligible 404
+     */
     constructor(client: PeopleApiClient, options?: PersonControllerOptions);
     /**
      * Suggest persons matching the given search string.
      * Search string can be a part of display name, mail, upn or the full azureId.
      * If systemAccounts is true, it will also include system accounts in the result.
+     *
+     * @param args - The search string, whether to include system accounts, and an optional abort signal
+     * @returns An observable emitting the matching suggestions
      */
     suggest(args: ResolverArgs<{
         search: string;
@@ -55,25 +67,110 @@ export declare class PersonController implements IPersonController {
     }>): Observable<SuggestPersonApiResponse>;
     /**
      * Resolve person details for given identifiers, which can be a mix of azureIds and upns.
+     *
+     * @param args - The identifiers to resolve and an optional abort signal
+     * @returns An observable emitting the resolved person details
      */
     resolve(args: ResolverArgs<{
         resolveIds: string[];
     }>): Observable<ResolvePersonApiResponse>;
+    /**
+     * Search for persons matching the given search string.
+     *
+     * @param args - The search string and an optional abort signal
+     * @returns An observable emitting the search results
+     */
     search(args: {
         search: string;
         signal?: AbortSignal;
     }): Observable<PersonSearchResult>;
-    /** TODO why does this need to have data?!? */
+    /**
+     * Fetch the photo of a person, resolving by azureId when available, falling back to upn.
+     *
+     * TODO(#5088): why does this need to have data?!?
+     *
+     * @param args - A matcher (azureId and/or upn) plus an optional abort signal
+     * @returns An observable emitting the object URL of the person's photo
+     * @throws Error if neither azureId nor upn is provided
+     */
     getPhoto(args: ResolverArgs<MatcherArgs>): Observable<string>;
+    /**
+     * Fetch full person details, resolving by azureId when available, falling back to upn.
+     *
+     * @param args - A matcher (azureId and/or upn) plus an optional abort signal
+     * @returns An observable emitting the person details
+     * @throws Error if neither azureId nor upn is provided
+     */
     getPerson(args: ResolverArgs<MatcherArgs>): Observable<GetPersonResult>;
+    /**
+     * Fetch v2 person info, resolving by azureId when available, falling back to upn.
+     *
+     * @param args - A matcher (azureId and/or upn) plus an optional abort signal
+     * @returns An observable emitting the v2 person info
+     * @throws Error if neither azureId nor upn is provided
+     */
     getPersonInfo(args: ResolverArgs<MatcherArgs>): Observable<ApiPerson<'v2'>>;
+    /**
+     * Resolve a full v4 person by upn, via cache and live lookup.
+     *
+     * @param upn - The person's upn
+     * @param signal - Optional abort signal
+     * @returns An observable emitting the resolved v4 person
+     */
     protected _getPersonByUpn(upn: string, signal?: AbortSignal): Observable<GetPersonResult>;
+    /**
+     * Fetch a full v4 person by azureId.
+     *
+     * @param azureId - The person's azureId
+     * @param signal - Optional abort signal
+     * @returns An observable emitting the fetched v4 person
+     */
     _getPersonByAzureId(azureId: string, signal?: AbortSignal): Observable<GetPersonResult>;
+    /**
+     * Resolve v2 person info by azureId, via cache and live lookup.
+     *
+     * @param azureId - The person's azureId
+     * @param signal - Optional abort signal
+     * @returns An observable emitting the resolved v2 person info
+     */
     protected _getPersonInfoById(azureId: string, signal?: AbortSignal): Observable<ApiPerson<'v2'>>;
+    /**
+     * Resolve v2 person info by upn, via cache and search-based lookup.
+     *
+     * @param upn - The person's upn
+     * @param signal - Optional abort signal
+     * @returns An observable emitting the resolved v2 person info
+     */
     protected _getPersonInfoByUpn(upn: string, signal?: AbortSignal): Observable<ApiPerson<'v2'>>;
+    /**
+     * Fetch a person's photo by azureId as an object URL.
+     *
+     * @param azureId - The person's azureId
+     * @param signal - Optional abort signal
+     * @returns An observable emitting the photo's object URL
+     */
     protected _getPersonPhotoByAzureId(azureId: string, signal?: AbortSignal): Observable<string>;
+    /**
+     * Fetch a person's photo by upn, resolving their azureId first.
+     *
+     * @param upn - The person's upn
+     * @param signal - Optional abort signal
+     * @returns An observable emitting the photo's object URL
+     */
     protected _getPersonPhotoByUpn(upn: string, signal?: AbortSignal): Observable<string>;
+    /**
+     * Search the person-query cache for a matching v4 person.
+     *
+     * @param args - A matcher (azureId and/or upn) used to find the cached entry
+     * @returns An observable emitting the matching cached v4 person, if any
+     */
     protected _personCache$(args: MatcherArgs): Observable<GetPersonResult>;
+    /**
+     * Search the search-query cache for a matching v2 person.
+     *
+     * @param args - A matcher (azureId and/or upn) used to find the cached entry
+     * @returns An observable emitting the matching cached v2 person, if any
+     */
     protected _queryCache$(args: MatcherArgs): Observable<ApiPerson<'v2'>>;
 }
 export {};

package/dist/types/{makeResolver.d.ts → make-resolver.d.ts}

@@ -2,4 +2,4 @@ import { type PersonControllerOptions } from './PersonController';
 import type { IApiProvider } from '@equinor/fusion-framework-module-services';
 export declare const makeResolver: (services: IApiProvider, options?: PersonControllerOptions) => import("react").LazyExoticComponent<({ children }: {
     readonly children?: React.ReactNode;
-}) => import("react/jsx-runtime").JSX.Element>;
+}) => import("react").JSX.Element>;

package/dist/types/version.d.ts

@@ -1 +1 @@
-export declare const version = "2.0.2";
+export declare const version = "2.0.4";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@equinor/fusion-framework-react-components-people-provider",
-  "version": "2.0.2",
+  "version": "2.0.4",
   "description": "",
   "main": "dist/esm/index.js",
   "exports": {
@@ -23,19 +23,19 @@
   },
   "dependencies": {
     "rxjs": "^7.8.1",
-    "@equinor/fusion-framework-module-services": "^8.0.1",
-    "@equinor/fusion-framework-react": "^8.0.0",
-    "@equinor/fusion-query": "^7.0.1",
-    "@equinor/fusion-framework-react-module": "^4.0.0"
+    "@equinor/fusion-framework-module-services": "^8.0.2",
+    "@equinor/fusion-framework-react-module": "^4.0.2",
+    "@equinor/fusion-query": "^7.0.2",
+    "@equinor/fusion-framework-react": "^8.0.1"
   },
   "devDependencies": {
-    "@equinor/fusion-wc-person": "^3.5.3",
+    "@equinor/fusion-wc-person": "^3.5.5",
     "@types/react": "^19.2.7",
     "react": "^19.2.1",
-    "typescript": "^6.0.3",
-    "@equinor/fusion-framework-module-app": "^8.0.2",
-    "@equinor/fusion-framework-module-bookmark": "^4.0.2",
-    "@equinor/fusion-framework-module-event": "^6.0.0"
+    "typescript": "^7.0.2",
+    "@equinor/fusion-framework-module-app": "^8.0.3",
+    "@equinor/fusion-framework-module-bookmark": "^4.0.3",
+    "@equinor/fusion-framework-module-event": "^6.0.1"
   },
   "peerDependencies": {
     "@types/react": "^18.0.0 || ^19.0.0",

package/src/{PeopleResolver.tsx → PeopleResolverComponent.tsx}

@@ -4,10 +4,11 @@ import {
   PersonProviderElement,
   PersonAvatarElement,
   PersonCardElement,
-  PersonResolver,
+  type PersonResolver,
   PersonListItemElement,
   PersonSelectElement,
 } from '@equinor/fusion-wc-person';
+export { PersonResolver } from '@equinor/fusion-wc-person';
 
 declare module 'react' {
   namespace JSX {
@@ -26,14 +27,22 @@ PersonCardElement;
 PersonListItemElement;
 PersonSelectElement;
 
-export { PersonResolver };
-
+/**
+ * Wraps the `fwc-person-provider` web component, wiring the given `PersonResolver` into it
+ * once the underlying custom element is ready.
+ *
+ * @param props - Component props
+ * @param props.resolver - The resolver used to fetch person data, photos, and search results
+ * @param props.children - Elements rendered inside the person provider, typically person-related components
+ * @returns The rendered `fwc-person-provider` element wrapping the given children
+ */
 export const PeopleResolverComponent = (props: PropsWithChildren<{ resolver: PersonResolver }>) => {
   const { resolver, children } = props;
   const ref = useRef<PersonProviderElement | null>(null);
 
   // when the element is ready, set the resolver
   useEffect(() => {
+    // Only assign the resolver once the custom element ref has mounted
     if (ref.current && resolver) {
       ref.current.resolver = resolver;
     }

package/src/PeopleResolverProvider.tsx

@@ -1,7 +1,7 @@
 import { type PropsWithChildren, type ReactNode, Suspense, useMemo } from 'react';
 import type { ServicesModule } from '@equinor/fusion-framework-module-services';
 import { useModule } from '@equinor/fusion-framework-react-module';
-import { makeResolver } from './makeResolver';
+import { makeResolver } from './make-resolver';
 import type { PersonControllerOptions } from './PersonController';
 
 type PeopleResolverProviderProps = PropsWithChildren<{
@@ -9,9 +9,21 @@ type PeopleResolverProviderProps = PropsWithChildren<{
   readonly fallback?: ReactNode;
 }>;
 
+/**
+ * Provides person resolution to its children by wiring up a `PersonResolver` built from the
+ * framework's `services` module.
+ *
+ * @param props - Component props
+ * @param props.children - Elements that will have access to the person resolver
+ * @param props.options - Optional controller options, such as a fallback image for missing photos
+ * @param props.fallback - Optional fallback rendered while the resolver component is suspended
+ * @returns The rendered people resolver provider wrapping the given children
+ * @throws Error if the `services` module has not been registered on the framework
+ */
 export const PeopleResolverProvider = (props: PeopleResolverProviderProps) => {
   const { children, options, fallback } = props;
   const services = useModule<ServicesModule>('services');
+  // Fail fast when the services module has not been registered on the framework
   if (!services) {
     throw Error('missing service module');
   }

package/src/PersonController.ts

@@ -29,6 +29,7 @@ const personMatcher =
   (args: MatcherArgs) =>
   <T extends { azureUniqueId?: string; upn?: string }>(value: T): value is T => {
     const { azureId, upn } = args;
+    // Both identifiers must match when both are supplied to avoid a false-positive match
     if (azureId && upn) {
       return (
         value.upn?.toLocaleLowerCase() === upn.toLocaleLowerCase() &&
@@ -57,6 +58,10 @@ export type PersonControllerOptions = {
   fallbackImage?: Blob;
 };
 
+/**
+ * Default implementation of {@link IPersonController}, backed by a {@link PeopleApiClient} and
+ * a set of {@link Query} caches for people, searches, photos, suggestions, and resolves.
+ */
 export class PersonController implements IPersonController {
   #personQuery: Query<GetPersonResult, ResolverArgs<{ azureId: string }>>;
   #personSearchQuery: Query<PersonSearchResult, ResolverArgs<{ search: string }>>;
@@ -67,6 +72,11 @@ export class PersonController implements IPersonController {
   >;
   #personResolveQuery: Query<ResolvePersonApiResponse, ResolverArgs<{ resolveIds: string[] }>>;
 
+  /**
+   * @param client - The people API client used to fetch person data, photos, and search results
+   * @param options - Optional controller options, such as a fallback image for missing photos
+   * @throws Error if the photo request fails for a reason other than a fallback-eligible 404
+   */
   constructor(client: PeopleApiClient, options?: PersonControllerOptions) {
     const expire = 3 * 60 * 1000;
     this.#personQuery = new Query({
@@ -75,14 +85,17 @@ export class PersonController implements IPersonController {
       key: ({ azureId }) => azureId,
       client: {
         fn: ({ azureId }, signal): Observable<GetPersonResult> => {
+          // Filter out expired positions from the fetched person's result before returning it
           return client
             .get('v4', 'json$', { azureId, expand: ['manager', 'positions'] }, { signal })
             .pipe(
               map((result) => {
                 const { positions = [] } = result;
+                // Drop positions that have already expired so stale data isn't shown
+                const activePositions = positions.filter((x) => new Date(x.appliesTo) > new Date());
                 return {
                   ...result,
-                  positions: positions.filter((x) => new Date(x.appliesTo) > new Date()),
+                  positions: activePositions,
                 };
               }),
             );
@@ -105,11 +118,13 @@ export class PersonController implements IPersonController {
       key: ({ azureId }) => azureId,
       client: {
         fn: ({ azureId }, signal): Observable<Blob> => {
+          // Extract the blob from the response, falling back to a placeholder image on 404
           return client.photo('v2', 'blob$', { azureId }, { signal }).pipe(
             map((result) => {
               return result.blob;
             }),
             catchError((err) => {
+              // Fall back to a placeholder image when the person genuinely has no photo
               if (
                 (err as Error).name === 'ApiProviderError' &&
                 (err as ApiProviderError).response?.status === 404 &&
@@ -130,6 +145,7 @@ export class PersonController implements IPersonController {
       client: {
         fn: ({ search, systemAccounts }, signal) => {
           const types = ['Person'];
+          // System accounts are opt-in since they're excluded from suggestions by default
           if (systemAccounts) {
             types.push('SystemAccount');
           }
@@ -161,33 +177,57 @@ export class PersonController implements IPersonController {
    * Suggest persons matching the given search string.
    * Search string can be a part of display name, mail, upn or the full azureId.
    * If systemAccounts is true, it will also include system accounts in the result.
+   *
+   * @param args - The search string, whether to include system accounts, and an optional abort signal
+   * @returns An observable emitting the matching suggestions
    */
   public suggest(
     args: ResolverArgs<{ search: string; systemAccounts: boolean }>,
   ): Observable<SuggestPersonApiResponse> {
     const { search, systemAccounts, signal } = args;
+    // Unwrap the query result to just its value
     return this.#personSuggestQuery.query({ search, systemAccounts }, { signal }).pipe(queryValue);
   }
 
   /**
    * Resolve person details for given identifiers, which can be a mix of azureIds and upns.
+   *
+   * @param args - The identifiers to resolve and an optional abort signal
+   * @returns An observable emitting the resolved person details
    */
   public resolve(
     args: ResolverArgs<{ resolveIds: string[] }>,
   ): Observable<ResolvePersonApiResponse> {
     const { resolveIds, signal } = args;
+    // Unwrap the query result to just its value
     return this.#personResolveQuery.query({ resolveIds }, { signal }).pipe(queryValue);
   }
 
+  /**
+   * Search for persons matching the given search string.
+   *
+   * @param args - The search string and an optional abort signal
+   * @returns An observable emitting the search results
+   */
   public search(args: { search: string; signal?: AbortSignal }): Observable<PersonSearchResult> {
     const { search, signal } = args;
+    // Unwrap the query result to just its value
     return this.#personSearchQuery.query({ search }, { signal }).pipe(queryValue);
   }
 
-  /** TODO why does this need to have data?!? */
+  /**
+   * Fetch the photo of a person, resolving by azureId when available, falling back to upn.
+   *
+   * TODO(#5088): why does this need to have data?!?
+   *
+   * @param args - A matcher (azureId and/or upn) plus an optional abort signal
+   * @returns An observable emitting the object URL of the person's photo
+   * @throws Error if neither azureId nor upn is provided
+   */
   public getPhoto(args: ResolverArgs<MatcherArgs>): Observable<string> {
     const { azureId, upn, signal } = args;
 
+    // Prefer resolving by azureId when available, falling back to upn
     if (azureId) {
       return this._getPersonPhotoByAzureId(azureId, signal);
     } else if (upn) {
@@ -196,8 +236,16 @@ export class PersonController implements IPersonController {
     throw Error('invalid args provided');
   }
 
+  /**
+   * Fetch full person details, resolving by azureId when available, falling back to upn.
+   *
+   * @param args - A matcher (azureId and/or upn) plus an optional abort signal
+   * @returns An observable emitting the person details
+   * @throws Error if neither azureId nor upn is provided
+   */
   public getPerson(args: ResolverArgs<MatcherArgs>): Observable<GetPersonResult> {
     const { azureId, upn, signal } = args;
+    // Prefer resolving by azureId when available, falling back to upn
     if (azureId) {
       return this._getPersonByAzureId(azureId, signal);
     } else if (upn) {
@@ -206,8 +254,16 @@ export class PersonController implements IPersonController {
     throw Error('invalid args provided');
   }
 
+  /**
+   * Fetch v2 person info, resolving by azureId when available, falling back to upn.
+   *
+   * @param args - A matcher (azureId and/or upn) plus an optional abort signal
+   * @returns An observable emitting the v2 person info
+   * @throws Error if neither azureId nor upn is provided
+   */
   public getPersonInfo(args: ResolverArgs<MatcherArgs>): Observable<ApiPerson<'v2'>> {
     const { azureId, upn, signal } = args;
+    // Prefer resolving by azureId when available, falling back to upn
     if (azureId) {
       return this._getPersonInfoById(azureId, signal);
     } else if (upn) {
@@ -216,95 +272,155 @@ export class PersonController implements IPersonController {
     throw Error('invalid args provided');
   }
 
+  /**
+   * Resolve a full v4 person by upn, via cache and live lookup.
+   *
+   * @param upn - The person's upn
+   * @param signal - Optional abort signal
+   * @returns An observable emitting the resolved v4 person
+   */
   protected _getPersonByUpn(upn: string, signal?: AbortSignal): Observable<GetPersonResult> {
     const abort$ = signal ? fromEvent(signal, 'abort') : EMPTY;
-    return concat(
-      this._personCache$({ upn }),
-      this._getPersonInfoByUpn(upn, signal).pipe(
-        filter(isApiPerson('v2')),
-        switchMap(({ azureUniqueId: azureId }) => {
-          return this._getPersonByAzureId(azureId, signal);
-        }),
-      ),
-    ).pipe(
-      /** */
+    // Resolve the v2 person info by upn, then use its azureId to fetch the full v4 person
+    const personByAzureId$ = this._getPersonInfoByUpn(upn, signal).pipe(
+      filter(isApiPerson('v2')),
+      switchMap(({ azureUniqueId: azureId }) => {
+        return this._getPersonByAzureId(azureId, signal);
+      }),
+    );
+    // Emit from cache first, then fall back to the live lookup, stopping once a v4 person arrives
+    return concat(this._personCache$({ upn }), personByAzureId$).pipe(
       filter(isApiPerson('v4')),
       takeUntil(abort$),
     );
   }
 
+  /**
+   * Fetch a full v4 person by azureId.
+   *
+   * @param azureId - The person's azureId
+   * @param signal - Optional abort signal
+   * @returns An observable emitting the fetched v4 person
+   */
   public _getPersonByAzureId(azureId: string, signal?: AbortSignal): Observable<GetPersonResult> {
+    // Unwrap the query result to just its value
     return this.#personQuery.query({ azureId }, { signal }).pipe(queryValue);
   }
 
+  /**
+   * Resolve v2 person info by azureId, via cache and live lookup.
+   *
+   * @param azureId - The person's azureId
+   * @param signal - Optional abort signal
+   * @returns An observable emitting the resolved v2 person info
+   */
   protected _getPersonInfoById(azureId: string, signal?: AbortSignal): Observable<ApiPerson<'v2'>> {
     const abort$ = signal ? fromEvent(signal, 'abort') : EMPTY;
+    // Emit from caches first, then fall back to a live lookup, keeping only v2 persons
     return concat(
-      /** */
       this._personCache$({ azureId }),
       this._queryCache$({ azureId }),
       this._getPersonByAzureId(azureId, signal),
-    ).pipe(
-      /** */
-      filter(isApiPerson('v2')),
-      takeUntil(abort$),
-    );
+    ).pipe(filter(isApiPerson('v2')), takeUntil(abort$));
   }
 
+  /**
+   * Resolve v2 person info by upn, via cache and search-based lookup.
+   *
+   * @param upn - The person's upn
+   * @param signal - Optional abort signal
+   * @returns An observable emitting the resolved v2 person info
+   */
   protected _getPersonInfoByUpn(upn: string, signal?: AbortSignal): Observable<ApiPerson<'v2'>> {
     const matcher = personMatcher({ upn });
     const abort$ = signal ? fromEvent(signal, 'abort') : EMPTY;
-    return concat(
-      this._personCache$({ upn }),
-      this._queryCache$({ upn }),
-      this.#personSearchQuery.query({ search: upn }, { signal }).pipe(
-        /** extract first match, should only be 0 or 1 */
-        map((x) => x.value.find(matcher)),
-        /** type cast and end stream */
-        find(isApiPerson('v2')),
-      ),
-    ).pipe(find(isApiPerson('v2')), filter(isApiPerson('v2')), takeUntil(abort$));
+    // Search by upn, then narrow the results down to the single matching entry, if any
+    const searchMatch$ = this.#personSearchQuery.query({ search: upn }, { signal }).pipe(
+      map((x) => {
+        // Narrow the search results down to the one entry matching this upn/azureId
+        const match = x.value.find(matcher);
+        return match;
+      }),
+      find(isApiPerson('v2')),
+    );
+    // Emit from caches first, then fall back to the search-based lookup, keeping only v2 persons
+    return concat(this._personCache$({ upn }), this._queryCache$({ upn }), searchMatch$).pipe(
+      find(isApiPerson('v2')),
+      filter(isApiPerson('v2')),
+      takeUntil(abort$),
+    );
   }
 
+  /**
+   * Fetch a person's photo by azureId as an object URL.
+   *
+   * @param azureId - The person's azureId
+   * @param signal - Optional abort signal
+   * @returns An observable emitting the photo's object URL
+   */
   protected _getPersonPhotoByAzureId(azureId: string, signal?: AbortSignal): Observable<string> {
+    // Take just the first emission and convert the blob result to an object URL
     return this.#personPhotoQuery.query({ azureId }, { signal }).pipe(
-      /** make subscription cold */
       take(1),
       map((result) => URL.createObjectURL(result.value)),
     );
   }
 
+  /**
+   * Fetch a person's photo by upn, resolving their azureId first.
+   *
+   * @param upn - The person's upn
+   * @param signal - Optional abort signal
+   * @returns An observable emitting the photo's object URL
+   */
   protected _getPersonPhotoByUpn(upn: string, signal?: AbortSignal) {
+    // Take just the first emission, then fetch the photo using its resolved azureId
     return this._getPersonInfoByUpn(upn, signal).pipe(
-      /** make subscription cold */
       take(1),
       switchMap((x) => this._getPersonPhotoByAzureId(x.azureUniqueId, signal)),
     );
   }
 
+  /**
+   * Search the person-query cache for a matching v4 person.
+   *
+   * @param args - A matcher (azureId and/or upn) used to find the cached entry
+   * @returns An observable emitting the matching cached v4 person, if any
+   */
   protected _personCache$(args: MatcherArgs): Observable<GetPersonResult> {
     const mather = personMatcher(args);
+    // Search the person-query cache for the first matching v4 entry
     return this.#personQuery.cache.state$.pipe(
-      /** make subscription cold */
       take(1),
-      /** map out cached ApiPerson_v2 which matches upn  */
-      map((x) => Object.values(x).find((x) => mather(x.value))?.value),
+      map((x) => {
+        // Search each cached query result entry for the one matching this person
+        const match = Object.values(x).find((x) => mather(x.value));
+        return match?.value;
+      }),
       find(isApiPerson('v4')),
       filter(isApiPerson('v4')),
     );
   }
 
+  /**
+   * Search the search-query cache for a matching v2 person.
+   *
+   * @param args - A matcher (azureId and/or upn) used to find the cached entry
+   * @returns An observable emitting the matching cached v2 person, if any
+   */
   protected _queryCache$(args: MatcherArgs): Observable<ApiPerson<'v2'>> {
     const mather = personMatcher(args);
+    // Search the search-query cache for the first matching v2 entry
     return this.#personSearchQuery.cache.state$.pipe(
-      /** make subscription cold */
       take(1),
       switchMap((entry) => {
-        /** expand cache records */
+        // Expand the cache entry's records and find the one matching this person
         return from(Object.values(entry)).pipe(
-          /** find matching cache record item */
-          map((x) => x.value.find((x) => mather(x))),
-          /** type cast and end stream */
+          map((x) => {
+            // Search each cached entry's results for the one matching this person
+            const match = x.value.find((x) => mather(x));
+            return match;
+          }),
           find(isApiPerson('v2')),
         );
       }),