@devsym/graph-toolkit-react 1.0.0-next.9 → 1.1.0-beta.0

package/AGENTS.md

@@ -141,6 +141,8 @@ export class MyProvider implements IProvider {
 | --- | --- | --- |
 | 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 |
 
@@ -161,6 +163,12 @@ export class MyProvider implements IProvider {
 - 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.
 
+## Storybook Development
+
+- Add `tags: ['autodocs']` to each component story `meta` so Storybook generates a component-level Docs page.
+- Use `parameters.docs.description.component` plus documented `argTypes` to make the Docs page explain the component and its feature stories.
+- Keep component examples in a single `*.stories.tsx` file with representative feature stories instead of separate docs-only pages per feature.
+
 ## Source of Truth
 
 - Primary docs: `README.md`

package/CONTRIBUTING.md

@@ -0,0 +1,64 @@
+# Contributing
+
+Thanks for helping improve Graph Toolkit React. This project is a React-first component library for Microsoft Graph built with Fluent UI v9, TypeScript, Vite, Vitest, and Storybook.
+
+## Getting Started
+
+Install dependencies from the repository root:
+
+```bash
+npm install
+```
+
+Run the standard validation commands before opening a pull request:
+
+```bash
+npm run type-check
+npm run lint
+npm run test
+npm run build
+```
+
+Run Storybook locally when changing components or docs:
+
+```bash
+npm run storybook
+```
+
+## Development Guidelines
+
+- Prefer existing project patterns over new abstractions.
+- Use Fluent UI v9 components and typings for UI surfaces.
+- Keep Microsoft Graph scopes minimal and feature-driven.
+- Prefer Microsoft Graph `id` values for path-based Graph calls when IDs are available.
+- URL-encode dynamic Graph path segments before building request paths.
+- Add or update tests for behavior changes.
+- Add or update Storybook stories for component-facing changes.
+- Add `tags: ['autodocs']` to component story metadata.
+- Document public interfaces, types, functions, and story args with clear JSDoc or Storybook metadata.
+
+## Changesets
+
+User-facing changes should include a changeset:
+
+```bash
+npm run changeset
+```
+
+Choose the smallest appropriate bump and write the summary for package consumers. Documentation-only changes that affect package usage should still include a changeset when they change published guidance.
+
+## Documentation
+
+Update the README, Storybook docs, sample docs, or migration guide when a change affects setup, supported scenarios, permissions, public APIs, or component behavior.
+
+For sample app changes, update [samples/react-msal-sample/README.md](samples/react-msal-sample/README.md).
+
+## Pull Request Checklist
+
+- Validation commands pass locally or in CI.
+- Tests cover new behavior or regressions.
+- Storybook covers new or changed component states.
+- Documentation reflects user-facing behavior.
+- A changeset is included for user-facing changes.
+
+This project follows the [Microsoft Open Source Code of Conduct](CODE_OF_CONDUCT.md).

package/README.md

@@ -0,0 +1,257 @@
+# Graph Toolkit React
+
+React components for Microsoft Graph, built with Fluent UI v9 and a provider model that fits modern React applications.
+
+<p>
+  <a href="https://www.npmjs.com/package/@devsym/graph-toolkit-react"><img src="https://img.shields.io/npm/v/@devsym/graph-toolkit-react/beta?label=npm%20beta" alt="npm beta version"></a>
+  <a href="https://github.com/ThomasPe/graph-toolkit-react/actions/workflows/pr.yml"><img src="https://github.com/ThomasPe/graph-toolkit-react/actions/workflows/pr.yml/badge.svg" alt="Build and Test"></a>
+  <a href="https://github.com/ThomasPe/graph-toolkit-react/actions/workflows/codeql-analysis.yml"><img src="https://github.com/ThomasPe/graph-toolkit-react/actions/workflows/codeql-analysis.yml/badge.svg" alt="CodeQL Security Scan"></a>
+  <a href="https://www.npmjs.com/package/@devsym/graph-toolkit-react"><img src="https://img.shields.io/npm/dm/@devsym/graph-toolkit-react" alt="npm downloads"></a>
+  <a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT license"></a>
+</p>
+
+<p align="center">
+  <img src="docs/assets/readme/banner.png" alt="Graph Toolkit React" width="100%">
+</p>
+
+## Status
+
+Graph Toolkit React is in beta and published on the npm `beta` channel. It is ready for evaluation and early adopters, but public APIs may still change until the package exits prerelease mode and is published on the `latest` tag.
+
+```bash
+npm install @devsym/graph-toolkit-react@beta
+```
+
+This package is a React-first successor inspired by Microsoft Graph Toolkit. It uses Fluent UI v9 components directly instead of wrapping framework-agnostic web components.
+
+## Installation
+
+Install the package and required peer dependencies:
+
+```bash
+npm install @devsym/graph-toolkit-react@beta react react-dom @fluentui/react-components
+```
+
+Install MSAL only when you use `MsalBrowserProvider`:
+
+```bash
+npm install @azure/msal-browser
+```
+
+`@azure/msal-browser` is an optional peer dependency. Teams-hosted apps that use `TeamsHostedProvider` do not need it unless the app uses MSAL elsewhere.
+
+## Quick Start
+
+Use `MockProvider` for local development, demos, and Storybook-style prototyping without authentication setup.
+
+```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>
+  );
+}
+```
+
+For a complete browser-hosted app, try the deployed [React MSAL sample](https://gentle-beach-0f6fe2903.2.azurestaticapps.net) or review [samples/react-msal-sample/README.md](samples/react-msal-sample/README.md).
+
+## Providers
+
+Choose one provider and pass it to `GraphProvider`.
+
+| Scenario | Provider | Notes |
+| --- | --- | --- |
+| Local development and UI prototyping | `MockProvider` | Returns deterministic mock data without Graph calls. |
+| Browser-hosted React SPA | `MsalBrowserProvider` | Uses `@azure/msal-browser` redirect flow. |
+| Microsoft Teams-hosted app | `TeamsHostedProvider` | Uses app-owned TeamsJS login plus a backend Graph token exchange. |
+| Existing auth stack | Custom `IProvider` | Implement token acquisition and state management yourself. |
+
+<p align="center">
+  <img src="docs/assets/readme/provider-flow.svg" alt="Graph Toolkit React provider flow from React components through GraphProvider to Microsoft Graph" width="100%">
+</p>
+
+### Browser SPA With MSAL
+
+```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>
+  );
+}
+```
+
+Register the redirect URI as a single-page application platform in Microsoft Entra ID.
+
+### Teams-Hosted Apps
+
+Use `TeamsHostedProvider` when a Teams app already owns TeamsJS authentication and exchanges tokens through a backend.
+
+```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: scopes => authentication.getAuthToken({ resources: scopes }),
+  exchangeForGraphToken,
+});
+
+await provider.login();
+
+export function App() {
+  return (
+    <GraphProvider provider={provider}>
+      <Person userId="me" view="threelines" showPresence />
+    </GraphProvider>
+  );
+}
+```
+
+## Components
+
+The README keeps component examples intentionally short so it stays useful as new components are added. Explore live examples, props, and behavior in [Storybook](https://thomaspe.github.io/graph-toolkit-react/).
+
+| Component or hook | Purpose | Where to start |
+| --- | --- | --- |
+| `Person` | Render a Microsoft Graph user with Fluent UI `Persona`, profile photo, presence, and configurable text lines. | Storybook examples for profile views, line rendering, direct data, and presence. |
+| `People` | Render compact avatar groups from direct data, explicit user IDs, group membership, or directory defaults. | Storybook examples for avatar layouts, group lookups, direct data, and overflow behavior. |
+| `PeoplePicker` | Search, select, exclude, and manage people using Fluent UI `TagPicker`. | Storybook examples for default selections, exclusions, limits, and controlled selection. |
+| `usePersonData` | Resolve person data for custom UI. | Use when the built-in `Person` layout is not enough. |
+| `usePeopleList` | Resolve and optionally sort a list of people. | Use when apps need to compose their own list or grid UI. |
+| `usePeopleSearch` | Search users for custom picker experiences. | Use when apps need a fully custom search or picker surface. |
+
+`Person`, `People`, and `PeoplePicker` expose `onUpdated` callbacks so apps can react to direct data changes, resolved content loads, and picker state updates with trigger metadata.
+
+## Permissions
+
+Request the smallest set of Microsoft Graph delegated scopes needed by the features you enable.
+
+| Feature | Minimum delegated scope | Notes |
+| --- | --- | --- |
+| Current user profile, `userId="me"` | `User.Read` | Required for basic profile fields. |
+| Other user profile by ID or UPN | `User.ReadBasic.All` | May require admin consent depending on tenant policy. |
+| `People` default directory list | `User.ReadBasic.All` | Used when no explicit people source is provided. |
+| `People` group members via `groupId` | `GroupMember.Read.All` | Required only for direct group membership lookup. |
+| `PeoplePicker` focus suggestions | `User.ReadBasic.All` | Uses the initial `/users` directory list shown before typing. |
+| Presence | `Presence.Read` | UI still renders without presence if unavailable. |
+| Profile photo | `User.Read` | Falls back to initials if no photo is available. |
+
+## Examples and Documentation
+
+- [Storybook](https://thomaspe.github.io/graph-toolkit-react/) for interactive component docs.
+- [samples/react-msal-sample/README.md](samples/react-msal-sample/README.md) for a browser SPA with MSAL redirect auth.
+- [AGENTS.md](AGENTS.md) for a scenario-first reference that coding agents can consume.
+- [docs/COMPONENT_ROADMAP.md](docs/COMPONENT_ROADMAP.md) for planned component work.
+
+## Support and Feedback
+
+Use [GitHub Issues](https://github.com/ThomasPe/graph-toolkit-react/issues) for bugs, questions, and component requests. Include the package version, React version, provider type, affected component, and a minimal reproduction when possible.
+
+## Supported Environments
+
+| Area | Support |
+| --- | --- |
+| React | 18 and 19 |
+| Fluent UI | `@fluentui/react-components` v9 |
+| TypeScript | 5.9 |
+| Development runtime | Node.js 24, matching CI |
+| Package output | ESM, CommonJS, and TypeScript declarations |
+
+## Development
+
+```bash
+npm install
+npm run type-check
+npm run lint
+npm run test
+npm run build
+```
+
+Run Storybook locally:
+
+```bash
+npm run storybook
+```
+
+Build the static Storybook site:
+
+```bash
+npm run build-storybook
+```
+
+Regenerate the README component screenshot from real Storybook renders:
+
+```bash
+npm run screenshots:readme
+```
+
+### Project Structure
+
+```text
+src/
+  components/
+    People/
+    PeoplePicker/
+    Person/
+  hooks/
+  providers/
+  utils/
+stories/
+samples/react-msal-sample/
+docs/
+```
+
+## Release Process
+
+This repository uses Changesets and npm Trusted Publishing through GitHub Actions. User-facing changes should include a changeset file under `.changeset/`.
+
+For maintainer details, see [PUBLISHING.md](PUBLISHING.md).
+
+## Contributing
+
+Contributions are welcome. Start with [CONTRIBUTING.md](CONTRIBUTING.md), which covers local setup, testing expectations, docs updates, and changesets.
+
+This project follows the [Microsoft Open Source Code of Conduct](CODE_OF_CONDUCT.md).
+
+## License
+
+MIT. See [LICENSE](LICENSE) for details.
+
+## Acknowledgments
+
+- [Fluent UI](https://react.fluentui.dev/) for the React component system.
+- [Microsoft Graph](https://graph.microsoft.com) for the API surface behind the components.
+- The Microsoft Graph Toolkit community for the original component patterns that inspired this React-first package.

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,KAAoB,MAAM,OAAO,CAAC;AASzC,OAAO,EAAgB,WAAW,EAAE,MAAM,gBAAgB,CAAC;AA8C3D;;;;;;;;GAQG;AACH,eAAO,MAAM,MAAM,EAAE,KAAK,CAAC,EAAE,CAAC,WAAW,CAoExC,CAAC"}

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

@@ -0,0 +1,103 @@
+/**
+ * People component types
+ */
+import type { AvatarGroupProps } from '@fluentui/react-components';
+import type { PeopleSearchResult } from '../../providers/IPersonDataProvider';
+import type { PersonDetails } from '../Person/Person.types';
+/**
+ * Supported built-in sort fields for resolved people collections.
+ */
+export type PeopleSortField = 'displayName' | 'givenName' | 'surname';
+/**
+ * Sort direction for resolved people collections.
+ */
+export type PeopleSortDirection = 'asc' | 'desc';
+/**
+ * Triggers reported by the {@link PeopleProps.onUpdated} callback.
+ */
+export type PeopleUpdateTrigger = 'peopleChanged' | 'peopleLoaded' | 'peopleLoadFailed';
+/**
+ * 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.
+ * Presence fields and additional custom fields are inherited from {@link PersonDetails}.
+ */
+export type PeoplePerson = PersonDetails & PeopleSearchResult;
+/**
+ * Event payload reported when the {@link People} component finishes a meaningful update.
+ */
+export interface PeopleUpdatedEvent {
+    /**
+     * The reason the component reported the update.
+     */
+    trigger: PeopleUpdateTrigger;
+    /**
+     * The resolved people currently rendered by the component.
+     */
+    people: PeoplePerson[];
+    /**
+     * Whether the component is still loading data.
+     */
+    loading: boolean;
+    /**
+     * The most recent list-loading error, if any.
+     */
+    error: Error | 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[];
+    /**
+     * Additional Graph user fields to request when the component resolves people.
+     */
+    selectFields?: string[];
+    /**
+     * Field used to sort the resolved people collection.
+     */
+    sortBy?: PeopleSortField;
+    /**
+     * Direction used when {@link PeopleProps.sortBy} is provided.
+     *
+     * Defaults to `asc`.
+     */
+    sortDirection?: PeopleSortDirection;
+    /**
+     * 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;
+    /**
+     * Called after the component updates its resolved people collection.
+     *
+     * Use this to react to direct `people` changes, successful list loads, or failed loads.
+     *
+     * @param event - Details about the update trigger and the current resolved people state.
+     */
+    onUpdated?: (event: PeopleUpdatedEvent) => void;
+}
+//# 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;AAC9E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAE5D;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG,aAAa,GAAG,WAAW,GAAG,SAAS,CAAC;AAEtE;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAAG,KAAK,GAAG,MAAM,CAAC;AAEjD;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAAG,eAAe,GAAG,cAAc,GAAG,kBAAkB,CAAC;AAExF;;;;;;GAMG;AACH,MAAM,MAAM,YAAY,GAAG,aAAa,GAAG,kBAAkB,CAAC;AAE9D;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC;;OAEG;IACH,OAAO,EAAE,mBAAmB,CAAC;IAC7B;;OAEG;IACH,MAAM,EAAE,YAAY,EAAE,CAAC;IACvB;;OAEG;IACH,OAAO,EAAE,OAAO,CAAC;IACjB;;OAEG;IACH,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;CACrB;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,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IAExB;;OAEG;IACH,MAAM,CAAC,EAAE,eAAe,CAAC;IAEzB;;;;OAIG;IACH,aAAa,CAAC,EAAE,mBAAmB,CAAC;IAEpC;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;;OAIG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IAEvB;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,kBAAkB,KAAK,IAAI,CAAC;CACjD"}

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

@@ -0,0 +1,6 @@
+/**
+ * People component exports
+ */
+export { People } from './People';
+export type { PeoplePerson, PeopleProps, PeopleUpdatedEvent, PeopleUpdateTrigger } 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,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC"}

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

@@ -1 +1 @@
-{"version":3,"file":"PeoplePicker.d.ts","sourceRoot":"","sources":["../../../src/components/PeoplePicker/PeoplePicker.tsx"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAyC,MAAM,OAAO,CAAC;AAiB9D,OAAO,EAAsB,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAoB7E;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,YAAY,EAAE,KAAK,CAAC,EAAE,CAAC,iBAAiB,CAqJpD,CAAC"}
+{"version":3,"file":"PeoplePicker.d.ts","sourceRoot":"","sources":["../../../src/components/PeoplePicker/PeoplePicker.tsx"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAA4D,MAAM,OAAO,CAAC;AAkBjF,OAAO,EAAsB,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAmE7E;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,YAAY,EAAE,KAAK,CAAC,EAAE,CAAC,iBAAiB,CAuMpD,CAAC"}

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

@@ -10,6 +10,35 @@ import type { PeopleSearchResult } from '../../providers/IPersonDataProvider';
  * so they can be used interchangeably.
  */
 export type PeoplePickerPerson = PeopleSearchResult;
+/**
+ * Triggers reported by the {@link PeoplePickerProps.onUpdated} callback.
+ */
+export type PeoplePickerUpdateTrigger = 'searchResultsUpdated' | 'selectionChanged';
+/**
+ * Event payload reported when the {@link PeoplePicker} component finishes a meaningful update.
+ */
+export interface PeoplePickerUpdatedEvent {
+    /**
+     * The reason the component reported the update.
+     */
+    trigger: PeoplePickerUpdateTrigger;
+    /**
+     * The current picker search query.
+     */
+    searchQuery: string;
+    /**
+     * The people currently selected in the picker.
+     */
+    selectedPeople: PeoplePickerPerson[];
+    /**
+     * The search results currently shown by the picker.
+     */
+    searchResults: PeoplePickerPerson[];
+    /**
+     * Whether the picker is still loading search results.
+     */
+    loading: boolean;
+}
 /**
  * Props for the {@link PeoplePicker} component.
  */
@@ -53,5 +82,11 @@ export interface PeoplePickerProps extends Pick<TagPickerProps, 'appearance' | '
      * shows up to {@link maxSearchResults} items after exclusion.
      */
     excludeUserIds?: string[];
+    /**
+     * Called after the picker updates its search results or selection state.
+     *
+     * @param event - Details about the update trigger and the picker state after the update.
+     */
+    onUpdated?: (event: PeoplePickerUpdatedEvent) => void;
 }
 //# sourceMappingURL=PeoplePicker.types.d.ts.map

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

@@ -1 +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"}
+{"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,MAAM,yBAAyB,GAAG,sBAAsB,GAAG,kBAAkB,CAAC;AAEpF;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC;;OAEG;IACH,OAAO,EAAE,yBAAyB,CAAC;IACnC;;OAEG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB;;OAEG;IACH,cAAc,EAAE,kBAAkB,EAAE,CAAC;IACrC;;OAEG;IACH,aAAa,EAAE,kBAAkB,EAAE,CAAC;IACpC;;OAEG;IACH,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;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;IAE1B;;;;OAIG;IACH,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,wBAAwB,KAAK,IAAI,CAAC;CACvD"}

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

@@ -2,5 +2,5 @@
  * PeoplePicker component exports
  */
 export { PeoplePicker } from './PeoplePicker';
-export type { PeoplePickerProps, PeoplePickerPerson } from './PeoplePicker.types';
+export type { PeoplePickerProps, PeoplePickerPerson, PeoplePickerUpdatedEvent, PeoplePickerUpdateTrigger, } from './PeoplePicker.types';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +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"}
+{"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,EACV,iBAAiB,EACjB,kBAAkB,EAClB,wBAAwB,EACxB,yBAAyB,GAC1B,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,EAA8D,WAAW,EAAc,MAAM,gBAAgB,CAAC;AAsHrH,eAAO,MAAM,MAAM,EAAE,KAAK,CAAC,EAAE,CAAC,WAAW,CAyHxC,CAAC"}
+{"version":3,"file":"Person.d.ts","sourceRoot":"","sources":["../../../src/components/Person/Person.tsx"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAA6B,MAAM,OAAO,CAAC;AAIlD,OAAO,EAA8D,WAAW,EAAc,MAAM,gBAAgB,CAAC;AAqKrH,eAAO,MAAM,MAAM,EAAE,KAAK,CAAC,EAAE,CAAC,WAAW,CA2MxC,CAAC"}

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

@@ -4,6 +4,10 @@
 import type { PersonaProps } from '@fluentui/react-components';
 import type { ReactElement } from 'react';
 export type PersonView = 'avatar' | 'oneline' | 'twolines' | 'threelines' | 'fourlines';
+/**
+ * Triggers reported by the {@link PersonProps.onUpdated} callback.
+ */
+export type PersonUpdateTrigger = 'personDetailsChanged' | 'personLoaded' | 'personLoadFailed';
 /**
  * Normalized details about a person used by the {@link Person} component.
  *
@@ -11,6 +15,21 @@ export type PersonView = 'avatar' | 'oneline' | 'twolines' | 'threelines' | 'fou
  * and is used as the backing data for line mappings and custom renderers.
  */
 export interface PersonDetails {
+    /**
+     * A pre-resolved profile photo URL.
+     *
+     * When supplied, the {@link Person} component can render the avatar image without fetching it
+     * again.
+     */
+    photoUrl?: string | null;
+    /**
+     * The person's first name.
+     */
+    givenName?: string | null;
+    /**
+     * The person's last name.
+     */
+    surname?: string | null;
     /**
      * The person's display name.
      */
@@ -86,6 +105,27 @@ export interface PersonLineRenderContext {
  * @returns A React element, plain string, or `null` to skip the line.
  */
 export type PersonLineRenderer = (context: PersonLineRenderContext) => ReactElement | string | null;
+/**
+ * Event payload reported when the {@link Person} component finishes a meaningful update.
+ */
+export interface PersonUpdatedEvent {
+    /**
+     * The reason the component reported the update.
+     */
+    trigger: PersonUpdateTrigger;
+    /**
+     * The resolved person details currently rendered by the component, when available.
+     */
+    person: PersonDetails | null;
+    /**
+     * Whether the component is still loading data.
+     */
+    loading: boolean;
+    /**
+     * The most recent load error, if any.
+     */
+    error: Error | null;
+}
 export interface PersonProps extends PersonaProps {
     userId?: string;
     userPrincipalName?: string;
@@ -157,6 +197,14 @@ export interface PersonProps extends PersonaProps {
      * would have been shown based on `line4Property`, if any.
      */
     renderLine4?: PersonLineRenderer;
+    /**
+     * Called after the component updates its resolved person state.
+     *
+     * Use this to react to direct `personDetails` changes, successful data loads, or failed loads.
+     *
+     * @param event - Details about the update trigger and the current resolved person state.
+     */
+    onUpdated?: (event: PersonUpdatedEvent) => void;
     fetchImage?: boolean;
 }
 //# 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,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"}
+{"version":3,"file":"Person.types.d.ts","sourceRoot":"","sources":["../../../src/components/Person/Person.types.ts"],"names":[],"mappings":"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"}

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

@@ -2,5 +2,5 @@
  * Person component exports
  */
 export { Person } from './Person';
-export type { PersonLineRenderContext, PersonLineRenderer, PersonProps, } from './Person.types';
+export type { PersonLineRenderContext, PersonLineRenderer, PersonProps, PersonUpdatedEvent, PersonUpdateTrigger, } 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,EACV,uBAAuB,EACvB,kBAAkB,EAClB,WAAW,GACZ,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,EACX,kBAAkB,EAClB,mBAAmB,GACpB,MAAM,gBAAgB,CAAC"}