@devsym/graph-toolkit-react 0.1.0-next.2 → 1.0.0-next.11

package/AGENTS.md

@@ -0,0 +1,171 @@
+# AGENTS.md — Graph Toolkit React
+
+This file is for coding agents that consume `@devsym/graph-toolkit-react`.
+Use this as the primary quick reference for implementation choices.
+
+## Package
+
+- Package name: `@devsym/graph-toolkit-react`
+- Peer deps: `react`, `react-dom`, `@fluentui/react-components`
+- Optional peer dep: `@azure/msal-browser` (required only for `MsalBrowserProvider`)
+
+Install:
+
+```bash
+npm install @devsym/graph-toolkit-react react react-dom @fluentui/react-components
+```
+
+If using browser MSAL auth:
+
+```bash
+npm install @azure/msal-browser
+```
+
+## Scenario Decision Matrix
+
+Choose one provider and wire it into `GraphProvider`.
+
+| Scenario | Use | Why |
+| --- | --- | --- |
+| Local development / UI prototyping | `MockProvider` | No auth setup; deterministic mock data |
+| Browser-hosted app (SPA) with Entra/MSA sign-in | `MsalBrowserProvider` | Native browser MSAL flow |
+| Microsoft Teams-hosted app with consumer-managed Teams auth | `TeamsHostedProvider` | Reuses existing Teams token acquisition + backend exchange |
+| Existing custom auth stack | Custom `IProvider` implementation | Full control over token source and lifecycle |
+
+## Minimal Patterns
+
+### 1) MockProvider (fastest start)
+
+```tsx
+import { FluentProvider, webLightTheme } from '@fluentui/react-components';
+import { GraphProvider, MockProvider, Person } from '@devsym/graph-toolkit-react';
+
+const provider = new MockProvider();
+
+export function App() {
+  return (
+    <FluentProvider theme={webLightTheme}>
+      <GraphProvider provider={provider}>
+        <Person userId="AdeleV@contoso.com" view="twolines" showPresence />
+      </GraphProvider>
+    </FluentProvider>
+  );
+}
+```
+
+### 2) Browser SPA with MSAL (`MsalBrowserProvider`)
+
+```tsx
+import { PublicClientApplication } from '@azure/msal-browser';
+import { GraphProvider, MsalBrowserProvider, Person } from '@devsym/graph-toolkit-react';
+
+const msal = new PublicClientApplication({
+  auth: {
+    clientId: 'YOUR_CLIENT_ID',
+    authority: 'https://login.microsoftonline.com/common',
+    redirectUri: window.location.origin,
+  },
+});
+
+const provider = new MsalBrowserProvider(msal, ['User.Read']);
+await provider.initialize();
+
+export function App() {
+  return (
+    <GraphProvider provider={provider}>
+      <Person userId="me" view="threelines" />
+    </GraphProvider>
+  );
+}
+```
+
+The provider uses redirect flow. Set the redirect URI to your app's origin and register it as a **Single-page application (SPA)** in Azure AD.
+
+### 3) Teams-hosted app (`TeamsHostedProvider`)
+
+```tsx
+import {
+  createBackendTokenExchange,
+  GraphProvider,
+  Person,
+  TeamsHostedProvider,
+} from '@devsym/graph-toolkit-react';
+import { authentication } from '@microsoft/teams-js';
+
+const exchangeForGraphToken = createBackendTokenExchange({
+  endpoint: '/api/token/exchange',
+});
+
+const provider = new TeamsHostedProvider({
+  defaultScopes: ['User.Read'],
+  getTeamsSsoToken: async scopes => authentication.getAuthToken({ resources: scopes }),
+  exchangeForGraphToken,
+});
+
+await provider.login();
+
+export function App() {
+  return (
+    <GraphProvider provider={provider}>
+      <Person userId="me" view="threelines" />
+    </GraphProvider>
+  );
+}
+```
+
+### 4) Custom auth (`IProvider`)
+
+```tsx
+import { IProvider, ProviderState } from '@devsym/graph-toolkit-react';
+
+export class MyProvider implements IProvider {
+  state: ProviderState = 'SignedOut';
+
+  async login(): Promise<void> {
+    this.state = 'SignedIn';
+  }
+
+  async logout(): Promise<void> {
+    this.state = 'SignedOut';
+  }
+
+  async getAccessToken(): Promise<string> {
+    return 'ACCESS_TOKEN';
+  }
+}
+```
+
+## Scopes by Feature
+
+| Feature | Minimum delegated scope | Notes |
+| --- | --- | --- |
+| Current user profile (`userId="me"`) | `User.Read` | Required for basic profile fields |
+| Other user profile (`userId="{id/upn}"`) | `User.ReadBasic.All` | May require admin consent |
+| People default suggestions | `User.ReadBasic.All` | Used for the initial `/users` directory list when no explicit people source is provided |
+| PeoplePicker focus suggestions | `User.ReadBasic.All` | Uses the initial `/users` directory list shown before typing |
+| Presence (`showPresence`) | `Presence.Read` | UI still renders without presence |
+| Profile photo (`fetchImage`) | `User.Read` | Falls back to initials if unavailable |
+
+## Common Failures and Fixes
+
+| Symptom | Likely Cause | Action |
+| --- | --- | --- |
+| Redirect URI mismatch / `AADSTS50011` | App registration redirect URI does not match dev URL | Add exact SPA redirect URI used by local dev server |
+| Person stays loading | Provider not initialized / login not completed | Ensure `await provider.initialize()` (MSAL) or `await provider.login()` (Teams/custom) before rendering |
+| Presence missing | `Presence.Read` not granted | Add and consent to `Presence.Read`; keep graceful fallback |
+| `Cannot find module '@azure/msal-browser'` | Using `MsalBrowserProvider` without optional peer dependency installed | Install `@azure/msal-browser` |
+
+## Agent Rules
+
+- Choose the simplest provider that fits the host environment.
+- Keep scopes minimal and feature-driven.
+- Prefer `userId="me"` for first implementation; expand to other users only when needed.
+- Wrap components with `GraphProvider`; avoid direct token handling in UI components.
+- If uncertain, default to `MockProvider` for local iteration, then switch to real auth provider.
+
+## Source of Truth
+
+- Primary docs: `README.md`
+- Migration guide: `docs/MGT_MIGRATION.md`
+- MSAL sample: `samples/react-msal-sample/README.md`
+- API exports and types: package root `dist/index.d.ts` in published artifact

package/dist/components/People/People.d.ts

@@ -0,0 +1,16 @@
+/**
+ * People component - Display a compact group of people as overlapping avatars
+ */
+import React from 'react';
+import { PeopleProps } from './People.types';
+/**
+ * `People` renders a compact avatar strip similar to the MGT `mgt-people` control.
+ *
+ * The component can render a supplied list of people, resolve a list of `userIds`, load
+ * group members, or default to tenant directory users from `/users`.
+ *
+ * @param props - Avatar group configuration and people-loading options
+ * @returns A compact avatar group, a loading spinner, or `null` when no people are available
+ */
+export declare const People: React.FC<PeopleProps>;
+//# sourceMappingURL=People.d.ts.map

package/dist/components/People/People.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"People.d.ts","sourceRoot":"","sources":["../../../src/components/People/People.tsx"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,MAAM,OAAO,CAAC;AAS1B,OAAO,EAAgB,WAAW,EAAE,MAAM,gBAAgB,CAAC;AA6C3D;;;;;;;;GAQG;AACH,eAAO,MAAM,MAAM,EAAE,KAAK,CAAC,EAAE,CAAC,WAAW,CAwCxC,CAAC"}

package/dist/components/People/People.types.d.ts

@@ -0,0 +1,55 @@
+/**
+ * People component types
+ */
+import type { AvatarGroupProps } from '@fluentui/react-components';
+import type { PeopleSearchResult } from '../../providers/IPersonDataProvider';
+/**
+ * A person entry rendered by the {@link People} component.
+ *
+ * This extends the base people search result shape with optional presence fields used
+ * for avatar badges when {@link PeopleProps.showPresence} is enabled.
+ */
+export interface PeoplePerson extends PeopleSearchResult {
+    /**
+     * Current presence activity when available.
+     */
+    presenceActivity?: string | null;
+    /**
+     * Current presence availability when available.
+     */
+    presenceAvailability?: string | null;
+}
+/**
+ * Props for the {@link People} component.
+ */
+export interface PeopleProps extends Omit<AvatarGroupProps, 'children'> {
+    /**
+     * A pre-resolved list of people to render.
+     *
+     * When provided, the component skips list discovery and renders these people directly.
+     */
+    people?: PeoplePerson[];
+    /**
+     * A list of user identifiers to resolve and render.
+     *
+     * Values can be Microsoft Graph user IDs, UPNs, email addresses, or `"me"`.
+     */
+    userIds?: string[];
+    /**
+     * The ID of a Microsoft Entra ID group whose direct user members should be rendered.
+     */
+    groupId?: string;
+    /**
+     * Maximum number of visible avatars before the remaining people are shown in overflow.
+     *
+     * Defaults to `3`, matching the MGT `mgt-people` control.
+     */
+    showMax?: number;
+    /**
+     * Whether presence badges should be shown on each avatar.
+     *
+     * Presence is loaded when the active provider and granted scopes support it.
+     */
+    showPresence?: boolean;
+}
+//# sourceMappingURL=People.types.d.ts.map

package/dist/components/People/People.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"People.types.d.ts","sourceRoot":"","sources":["../../../src/components/People/People.types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AACnE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qCAAqC,CAAC;AAE9E;;;;;GAKG;AACH,MAAM,WAAW,YAAa,SAAQ,kBAAkB;IACtD;;OAEG;IACH,gBAAgB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC;;OAEG;IACH,oBAAoB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACtC;AAED;;GAEG;AACH,MAAM,WAAW,WAAY,SAAQ,IAAI,CAAC,gBAAgB,EAAE,UAAU,CAAC;IACrE;;;;OAIG;IACH,MAAM,CAAC,EAAE,YAAY,EAAE,CAAC;IAExB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IAEnB;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;;OAIG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB"}

package/dist/components/People/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * People component exports
+ */
+export { People } from './People';
+export type { PeoplePerson, PeopleProps } from './People.types';
+//# sourceMappingURL=index.d.ts.map

package/dist/components/People/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/components/People/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAClC,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/components/PeoplePicker/PeoplePicker.d.ts

@@ -0,0 +1,24 @@
+/**
+ * PeoplePicker component - Select one or more people using Microsoft Graph search
+ */
+import React from 'react';
+import { PeoplePickerProps } from './PeoplePicker.types';
+/**
+ * PeoplePicker — a tag-picker backed by Microsoft Graph people search.
+ *
+ * In controlled mode supply `selectedPeople` + `onSelectionChange`.
+ * In uncontrolled mode supply `defaultSelectedPeople` or leave both props unset.
+ *
+ * The component automatically uses {@link MockProvider} mock data when no real
+ * Graph provider is available, making it easy to prototype UIs without auth.
+ *
+ * @example
+ * ```tsx
+ * <PeoplePicker
+ *   placeholder="Search for people..."
+ *   onSelectionChange={(people) => console.log(people)}
+ * />
+ * ```
+ */
+export declare const PeoplePicker: React.FC<PeoplePickerProps>;
+//# sourceMappingURL=PeoplePicker.d.ts.map

package/dist/components/PeoplePicker/PeoplePicker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PeoplePicker.d.ts","sourceRoot":"","sources":["../../../src/components/PeoplePicker/PeoplePicker.tsx"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAyC,MAAM,OAAO,CAAC;AAkB9D,OAAO,EAAsB,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAyD7E;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,YAAY,EAAE,KAAK,CAAC,EAAE,CAAC,iBAAiB,CAyJpD,CAAC"}

package/dist/components/PeoplePicker/PeoplePicker.types.d.ts

@@ -0,0 +1,57 @@
+/**
+ * PeoplePicker component types
+ */
+import type { TagPickerProps } from '@fluentui/react-components';
+import type { PeopleSearchResult } from '../../providers/IPersonDataProvider';
+/**
+ * A person entry used in the PeoplePicker component.
+ *
+ * This is an alias for {@link PeopleSearchResult} — both types share the same shape
+ * so they can be used interchangeably.
+ */
+export type PeoplePickerPerson = PeopleSearchResult;
+/**
+ * Props for the {@link PeoplePicker} component.
+ */
+export interface PeoplePickerProps extends Pick<TagPickerProps, 'appearance' | 'size' | 'disabled'> {
+    /**
+     * Currently selected people (controlled mode).
+     * When provided, the component operates in controlled mode and does not manage its own selection state.
+     */
+    selectedPeople?: PeoplePickerPerson[];
+    /**
+     * Initial selected people (uncontrolled mode).
+     * Ignored when {@link selectedPeople} is provided.
+     */
+    defaultSelectedPeople?: PeoplePickerPerson[];
+    /**
+     * Called when the selection changes.
+     * @param people - The new array of selected people
+     */
+    onSelectionChange?: (people: PeoplePickerPerson[]) => void;
+    /**
+     * Placeholder text shown in the search input when nothing is typed
+     */
+    placeholder?: string;
+    /**
+     * Maximum number of people that can be selected.
+     * When reached the search input is hidden.
+     */
+    maxPeople?: number;
+    /**
+     * Minimum number of characters required before a search is triggered (default: 1)
+     */
+    searchMinChars?: number;
+    /**
+     * Maximum number of search results to show in the dropdown (default: 10)
+     */
+    maxSearchResults?: number;
+    /**
+     * User IDs to exclude from search results.
+     * When provided, these IDs will be filtered out of the dropdown suggestions.
+     * The search will fetch extra results to compensate so that the dropdown still
+     * shows up to {@link maxSearchResults} items after exclusion.
+     */
+    excludeUserIds?: string[];
+}
+//# sourceMappingURL=PeoplePicker.types.d.ts.map

package/dist/components/PeoplePicker/PeoplePicker.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PeoplePicker.types.d.ts","sourceRoot":"","sources":["../../../src/components/PeoplePicker/PeoplePicker.types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AACjE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qCAAqC,CAAC;AAE9E;;;;;GAKG;AACH,MAAM,MAAM,kBAAkB,GAAG,kBAAkB,CAAC;AAEpD;;GAEG;AACH,MAAM,WAAW,iBACf,SAAQ,IAAI,CAAC,cAAc,EAAE,YAAY,GAAG,MAAM,GAAG,UAAU,CAAC;IAChE;;;OAGG;IACH,cAAc,CAAC,EAAE,kBAAkB,EAAE,CAAC;IAEtC;;;OAGG;IACH,qBAAqB,CAAC,EAAE,kBAAkB,EAAE,CAAC;IAE7C;;;OAGG;IACH,iBAAiB,CAAC,EAAE,CAAC,MAAM,EAAE,kBAAkB,EAAE,KAAK,IAAI,CAAC;IAE3D;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;OAEG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB;;OAEG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B;;;;;OAKG;IACH,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;CAC3B"}

package/dist/components/PeoplePicker/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * PeoplePicker component exports
+ */
+export { PeoplePicker } from './PeoplePicker';
+export type { PeoplePickerProps, PeoplePickerPerson } from './PeoplePicker.types';
+//# sourceMappingURL=index.d.ts.map

package/dist/components/PeoplePicker/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/components/PeoplePicker/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,YAAY,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/components/Person/Person.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Person.d.ts","sourceRoot":"","sources":["../../../src/components/Person/Person.tsx"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,MAAM,OAAO,CAAC;AAI1B,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AA2C7C,eAAO,MAAM,MAAM,EAAE,KAAK,CAAC,EAAE,CAAC,WAAW,CAuFxC,CAAC"}
+{"version":3,"file":"Person.d.ts","sourceRoot":"","sources":["../../../src/components/Person/Person.tsx"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,MAAM,OAAO,CAAC;AAI1B,OAAO,EAA8D,WAAW,EAAc,MAAM,gBAAgB,CAAC;AAsHrH,eAAO,MAAM,MAAM,EAAE,KAAK,CAAC,EAAE,CAAC,WAAW,CAyHxC,CAAC"}

package/dist/components/Person/Person.types.d.ts

@@ -1,35 +1,162 @@
 /**
  * Person component types
  */
-import type { CSSProperties } from 'react';
-import { User } from '@microsoft/microsoft-graph-types';
-export type PersonView = 'avatar' | 'oneline' | 'twolines' | 'threelines';
-export type PersonSize = 'small' | 'medium' | 'large' | 'extra-large';
-export type PersonTextAlignment = 'start' | 'center';
-export type PersonTextPosition = 'before' | 'after' | 'below';
+import type { PersonaProps } from '@fluentui/react-components';
+import type { ReactElement } from 'react';
+export type PersonView = 'avatar' | 'oneline' | 'twolines' | 'threelines' | 'fourlines';
+/**
+ * Normalized details about a person used by the {@link Person} component.
+ *
+ * This interface typically comes from Microsoft Graph or an application-specific user store
+ * and is used as the backing data for line mappings and custom renderers.
+ */
 export interface PersonDetails {
-    displayName?: string;
-    mail?: string;
-    jobTitle?: string;
-    department?: string;
-    officeLocation?: string;
-    id?: string;
-    userPrincipalName?: string;
+    /**
+     * The person's display name.
+     */
+    displayName?: string | null;
+    /**
+     * The person's primary mail address (as returned by some Microsoft Graph shapes).
+     */
+    mail?: string | null;
+    /**
+     * The person's job title.
+     */
+    jobTitle?: string | null;
+    /**
+     * The department the person belongs to.
+     */
+    department?: string | null;
+    /**
+     * The person's office location.
+     */
+    officeLocation?: string | null;
+    /**
+     * The unique identifier for the person.
+     */
+    id?: string | null;
+    /**
+     * The person's user principal name (UPN).
+     */
+    userPrincipalName?: string | null;
+    /**
+     * The person's email address (alias for some data sources).
+     */
+    email?: string | null;
+    /**
+     * Current presence activity (for example, "InAMeeting" or "Presenting"), when available.
+     */
+    presenceActivity?: string | null;
+    /**
+     * Current presence availability (for example, "Available", "Busy", "Away"), when available.
+     */
+    presenceAvailability?: string | null;
+    /**
+     * Additional custom fields for the person.
+     *
+     * These fields can also be referenced from `lineXProperty` mappings when supported by the implementation.
+     */
+    [key: string]: unknown;
+}
+/**
+ * Context passed to a {@link PersonLineRenderer} when rendering a line of text.
+ */
+export interface PersonLineRenderContext {
+    /**
+     * The logical line number being rendered (1–4).
+     */
+    line: 1 | 2 | 3 | 4;
+    /**
+     * The resolved person details used for this line.
+     */
+    person: PersonDetails;
+    /**
+     * The default text that would be rendered for this line based on the `lineXProperty` mapping,
+     * if any. This can be used as a fallback or starting point when customizing rendering.
+     */
+    text?: string;
 }
-export interface PersonProps {
+/**
+ * Function used to customize rendering of a single line of person information.
+ *
+ * The renderer can either return a `ReactElement` for full control over layout and styling,
+ * a plain `string` to be rendered as simple text, or `null` to suppress rendering of the line.
+ *
+ * @param context - Information about the line being rendered and its resolved data.
+ * @returns A React element, plain string, or `null` to skip the line.
+ */
+export type PersonLineRenderer = (context: PersonLineRenderContext) => ReactElement | string | null;
+export interface PersonProps extends PersonaProps {
     userId?: string;
     userPrincipalName?: string;
     email?: string;
     personDetails?: PersonDetails;
     view?: PersonView;
     showPresence?: boolean;
-    avatarSize?: PersonSize;
-    textAlignment?: PersonTextAlignment;
-    textPosition?: PersonTextPosition;
-    numericSize?: number;
+    /**
+     * Mapping for the first text line.
+     *
+     * This is the name of a field on {@link PersonDetails} (for example, `"displayName"`), or a
+     * comma-separated list of field names to use as fallbacks in order (for example,
+     * `"displayName,mail,email"`).
+     *
+     * Implementations may also support pseudo-fields for derived values such as presence in
+     * addition to literal `PersonDetails` keys.
+     */
+    line1Property?: string;
+    /**
+     * Mapping for the second text line.
+     *
+     * Accepts a single {@link PersonDetails} field name or a comma-separated list of field names
+     * to be used as fallbacks, in the same way as {@link PersonProps.line1Property}.
+     */
+    line2Property?: string;
+    /**
+     * Mapping for the third text line.
+     *
+     * Accepts a single {@link PersonDetails} field name or a comma-separated list of field names
+     * to be used as fallbacks, in the same way as {@link PersonProps.line1Property}.
+     */
+    line3Property?: string;
+    /**
+     * Mapping for the fourth text line.
+     *
+     * Accepts a single {@link PersonDetails} field name or a comma-separated list of field names
+     * to be used as fallbacks, in the same way as {@link PersonProps.line1Property}.
+     */
+    line4Property?: string;
+    /**
+     * Custom renderer for the first text line.
+     *
+     * When provided, this overrides the default rendering for line 1 and is called with a
+     * {@link PersonLineRenderContext}. The `text` property in the context contains the value that
+     * would have been shown based on `line1Property`, if any.
+     */
+    renderLine1?: PersonLineRenderer;
+    /**
+     * Custom renderer for the second text line.
+     *
+     * When provided, this overrides the default rendering for line 2 and is called with a
+     * {@link PersonLineRenderContext}. The `text` property in the context contains the value that
+     * would have been shown based on `line2Property`, if any.
+     */
+    renderLine2?: PersonLineRenderer;
+    /**
+     * Custom renderer for the third text line.
+     *
+     * When provided, this overrides the default rendering for line 3 and is called with a
+     * {@link PersonLineRenderContext}. The `text` property in the context contains the value that
+     * would have been shown based on `line3Property`, if any.
+     */
+    renderLine3?: PersonLineRenderer;
+    /**
+     * Custom renderer for the fourth text line.
+     *
+     * When provided, this overrides the default rendering for line 4 and is called with a
+     * {@link PersonLineRenderContext}. The `text` property in the context contains the value that
+     * would have been shown based on `line4Property`, if any.
+     */
+    renderLine4?: PersonLineRenderer;
     fetchImage?: boolean;
-    onClick?: (person: User) => void;
-    className?: string;
-    style?: CSSProperties;
 }
 //# sourceMappingURL=Person.types.d.ts.map

package/dist/components/Person/Person.types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Person.types.d.ts","sourceRoot":"","sources":["../../../src/components/Person/Person.types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AAC3C,OAAO,EAAE,IAAI,EAAE,MAAM,kCAAkC,CAAC;AAExD,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,SAAS,GAAG,UAAU,GAAG,YAAY,CAAC;AAC1E,MAAM,MAAM,UAAU,GAAG,OAAO,GAAG,QAAQ,GAAG,OAAO,GAAG,aAAa,CAAC;AACtE,MAAM,MAAM,mBAAmB,GAAG,OAAO,GAAG,QAAQ,CAAC;AACrD,MAAM,MAAM,kBAAkB,GAAG,QAAQ,GAAG,OAAO,GAAG,OAAO,CAAC;AAE9D,MAAM,WAAW,aAAa;IAC5B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,WAAW;IAE1B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,KAAK,CAAC,EAAE,MAAM,CAAC;IAGf,aAAa,CAAC,EAAE,aAAa,CAAC;IAG9B,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,UAAU,CAAC,EAAE,UAAU,CAAC;IAGxB,aAAa,CAAC,EAAE,mBAAmB,CAAC;IACpC,YAAY,CAAC,EAAE,kBAAkB,CAAC;IAClC,WAAW,CAAC,EAAE,MAAM,CAAC;IAGrB,UAAU,CAAC,EAAE,OAAO,CAAC;IAGrB,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,IAAI,KAAK,IAAI,CAAC;IAGjC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,aAAa,CAAC;CACvB"}
+{"version":3,"file":"Person.types.d.ts","sourceRoot":"","sources":["../../../src/components/Person/Person.types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAC/D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,OAAO,CAAC;AAE1C,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,SAAS,GAAG,UAAU,GAAG,YAAY,GAAG,WAAW,CAAC;AAExF;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB;;OAEG;IACH,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B;;OAEG;IACH,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B;;OAEG;IACH,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB;;OAEG;IACH,iBAAiB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB;;OAEG;IACH,gBAAgB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC;;OAEG;IACH,oBAAoB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC;;;;OAIG;IACH,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC;;OAEG;IACH,IAAI,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACpB;;OAEG;IACH,MAAM,EAAE,aAAa,CAAC;IACtB;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,EAAE,uBAAuB,KAAK,YAAY,GAAG,MAAM,GAAG,IAAI,CAAC;AAEpG,MAAM,WAAW,WAAY,SAAQ,YAAY;IAE/C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,KAAK,CAAC,EAAE,MAAM,CAAC;IAGf,aAAa,CAAC,EAAE,aAAa,CAAC;IAG9B,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,YAAY,CAAC,EAAE,OAAO,CAAC;IAEvB;;;;;;;;;OASG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,kBAAkB,CAAC;IACjC;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,kBAAkB,CAAC;IACjC;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,kBAAkB,CAAC;IACjC;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,kBAAkB,CAAC;IAGjC,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB"}

package/dist/components/Person/index.d.ts

@@ -2,5 +2,5 @@
  * Person component exports
  */
 export { Person } from './Person';
-export type { PersonProps } from './Person.types';
+export type { PersonLineRenderContext, PersonLineRenderer, PersonProps, } from './Person.types';
 //# sourceMappingURL=index.d.ts.map

package/dist/components/Person/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/components/Person/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAClC,YAAY,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/components/Person/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAClC,YAAY,EACV,uBAAuB,EACvB,kBAAkB,EAClB,WAAW,GACZ,MAAM,gBAAgB,CAAC"}

package/dist/hooks/usePeopleList.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Hook to load a list of people from Microsoft Graph or a compatible provider
+ */
+import type { PeoplePerson } from '../components/People/People.types';
+/**
+ * Options for the {@link usePeopleList} hook.
+ */
+export interface UsePeopleListOptions {
+    /**
+     * Pre-resolved people to render directly.
+     */
+    people?: PeoplePerson[];
+    /**
+     * User identifiers to resolve into person entries.
+     */
+    userIds?: string[];
+    /**
+     * Group ID whose direct members should be loaded.
+     */
+    groupId?: string;
+    /**
+     * Maximum number of people to load for Graph-backed list queries.
+     *
+     * Ignored when {@link userIds} or direct {@link people} are provided.
+     */
+    maxPeople?: number;
+    /**
+     * Whether presence information should be loaded when supported.
+     */
+    showPresence?: boolean;
+}
+/**
+ * Result returned by the {@link usePeopleList} hook.
+ */
+export interface UsePeopleListResult {
+    /**
+     * The resolved list of people.
+     */
+    people: PeoplePerson[];
+    /**
+     * Whether loading is currently in progress.
+     */
+    loading: boolean;
+    /**
+     * The most recent list-loading error, if any.
+     */
+    error: Error | null;
+}
+/**
+ * Hook to load a compact people list for the {@link People} component.
+ *
+ * Resolution order matches the component inputs:
+ * 1. `people` (render directly)
+ * 2. `userIds` (resolve each identifier)
+ * 3. `groupId` (load direct group members)
+ * 4. default tenant directory users (`/users`)
+ *
+ * @param options - Configuration for how people should be resolved
+ * @returns The resolved people, loading state, and any list-level error
+ */
+export declare const usePeopleList: (options?: UsePeopleListOptions) => UsePeopleListResult;
+//# sourceMappingURL=usePeopleList.d.ts.map

package/dist/hooks/usePeopleList.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usePeopleList.d.ts","sourceRoot":"","sources":["../../src/hooks/usePeopleList.ts"],"names":[],"mappings":"AAAA;;GAEG;AAUH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mCAAmC,CAAC;AAOtE;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC;;OAEG;IACH,MAAM,CAAC,EAAE,YAAY,EAAE,CAAC;IACxB;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;OAEG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC;;OAEG;IACH,MAAM,EAAE,YAAY,EAAE,CAAC;IACvB;;OAEG;IACH,OAAO,EAAE,OAAO,CAAC;IACjB;;OAEG;IACH,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;CACrB;AAwCD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,aAAa,GAAI,UAAU,oBAAoB,KAAG,mBA4N9D,CAAC"}