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

package/readme.md

@@ -5,16 +5,18 @@
 <h4 align="center">Modern React Components for <a href="https://graph.microsoft.com">Microsoft Graph</a> powered by <a href="https://react.fluentui.dev/">Fluent UI</a></h4>
 
 <p align="center">
-  <img src="https://img.shields.io/badge/alpha-0.1.0-orange" alt="Alpha Release">
+  <a href="https://www.npmjs.com/package/@devsym/graph-toolkit-react"><img src="https://img.shields.io/badge/alpha-0.1.0-orange" alt="Alpha Release"></a>
   <img src="https://img.shields.io/badge/React-18%2F19-blue" alt="React 18/19">
   <img src="https://img.shields.io/badge/Fluent_UI-9.72-purple" alt="Fluent UI 9">
   <img src="https://img.shields.io/badge/TypeScript-5.9-blue" alt="TypeScript 5.9">
 </p>
 
 <h3 align="center">
-  <a href="#getting-started">Get Started</a> • 
-  <a href="#storybook">Storybook</a> • 
-  <a href="#contribute">Contribute</a>
+  <a href="#-getting-started">Get Started</a> • 
+  <a href="#-migration-from-mgt">Migration</a> • 
+  <a href="#-agent-quick-reference">Agent Quick Reference</a> • 
+  <a href="#-storybook">Storybook</a> • 
+  <a href="#-contribute">Contribute</a>
 </h3>
 
 ## 🎯 Project Vision
@@ -50,6 +52,30 @@ npm install @devsym/graph-toolkit-react
 | ------- | ------- | ----------- |
 | `@devsym/graph-toolkit-react` | `0.1.0-alpha.1` | React components for Microsoft Graph powered by Fluent UI |
 
+## 🔄 Migration from MGT
+
+For migration from Microsoft Graph Toolkit (including Teams-hosted scenarios), use [`docs/MGT_MIGRATION.md`](./docs/MGT_MIGRATION.md).
+
+The guide includes:
+
+- Concept mapping (MGT patterns to this package)
+- Step-by-step migration checklist
+- Teams-specific migration section (`TeamsHostedProvider` + backend token exchange)
+- Common migration pitfalls and validation checklist
+
+## 🤖 Agent Quick Reference
+
+If you are using a coding agent (Copilot/Codex/Claude/etc.), use the scenario-first reference in [`AGENTS.md`](./AGENTS.md).
+
+It includes:
+
+- Provider decision matrix by hosting scenario
+- Minimal copy-ready snippets for `MockProvider`, `MsalBrowserProvider`, `TeamsHostedProvider`, and custom `IProvider`
+- Scopes-by-feature mapping
+- Common failures and exact remediation steps
+
+For end-to-end browser-hosted setup with MSAL, also see [`samples/react-msal-sample/README.md`](./samples/react-msal-sample/README.md).
+
 ## 🎨 Components
 
 Currently available in alpha:
@@ -62,15 +88,76 @@ import { Person } from '@devsym/graph-toolkit-react';
 
 <Person 
   userId="user@contoso.com"
-  view="twoLines"
+  view="twolines"
   showPresence
+  presenceOnly={false}
+  size="large"
   textAlignment="center"
-  onClick={() => console.log('Clicked!')}
+  onClick={() => console.log('Persona clicked!')}
+/>
+```
+
+`Person` supports Fluent UI Persona props directly.
+
+MGT-style line customization is also supported:
+
+```tsx
+<Person
+  userId="me"
+  view="threelines"
+  line1Property="givenName"
+  line2Property="mail,userPrincipalName"
+  line3Property="presenceAvailability"
+/>
+```
+
+For full manual override, use React render callbacks as the replacement for MGT line templates:
+
+```tsx
+<Person
+  personDetails={{
+    displayName: 'Megan Bowen',
+    jobTitle: 'CEO',
+    department: 'Leadership',
+    officeLocation: 'Seattle',
+  }}
+  view="fourlines"
+  renderLine1={({ text }) => <span>Name: {text}</span>}
+  renderLine2={({ text }) => <span>Role: {text}</span>}
+  renderLine3={({ text }) => <span>Org: {text}</span>}
+  renderLine4={({ text }) => <span>Location: {text}</span>}
+/>
+```
+
+### People Component
+Display a compact strip of people using Fluent UI `AvatarGroup`.
+
+```tsx
+import { People } from '@devsym/graph-toolkit-react';
+
+<People showMax={4} size={40} />
+```
+
+You can also provide people directly or resolve specific users:
+
+```tsx
+<People
+  userIds={['me', 'user@contoso.com']}
+  showMax={2}
+  showPresence
+/>
+```
+
+```tsx
+<People
+  people={[
+    { id: 'adele', displayName: 'Adele Vance', mail: 'adelev@contoso.com' },
+    { id: 'alex', displayName: 'Alex Wilber', mail: 'alexw@contoso.com' },
+  ]}
 />
 ```
 
 
-<a id="getting-started"></a>
 ## 🚀 Getting Started
 
 ### Prerequisites
@@ -115,13 +202,15 @@ function App() {
   return (
     <FluentProvider theme={webLightTheme}>
       <GraphProvider provider={provider}>
-        <Person userId="AdeleV@contoso.com" view="twoLines" showPresence />
+        <Person userId="AdeleV@contoso.com" view="twolines" showPresence />
       </GraphProvider>
     </FluentProvider>
   );
 }
 ```
 
+For a complete browser-hosted example 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), which wires `MsalBrowserProvider` into `GraphProvider` and demonstrates `Person`, `People`, and `PeoplePicker`.
+
 ### Authentication Providers
 
 The library uses a provider pattern for authentication:
@@ -162,6 +251,8 @@ function App() {
 }
 ```
 
+The provider uses redirect flow. Set the redirect URI to your app's origin and register it as a **Single-page application (SPA)** platform in Azure AD.
+
 #### `TeamsHostedProvider` quick start (consumer-managed Teams login)
 
 Use this when your app is hosted in Microsoft Teams and your app code already handles TeamsJS auth for multiple APIs.
@@ -211,6 +302,9 @@ Use explicit mode selection in your app:
 | ------- | ------------------------ | ----- |
 | Load current user profile (`userId="me"`) | `User.Read` | Required for basic person data (`displayName`, `mail`, etc.) |
 | Load another user by id/upn (`userId="{id}"`) | `User.ReadBasic.All` | May require admin consent depending on tenant policy |
+| Load `People` default suggestions | `User.ReadBasic.All` | Used for the default `/users` directory list when no explicit people source is provided |
+| Load `People` group members (`groupId`) | `GroupMember.Read.All` | Required only when resolving direct group membership |
+| Load PeoplePicker focus suggestions | `User.ReadBasic.All` | Uses the initial `/users` directory list shown before typing |
 | Show presence (`showPresence`) | `Presence.Read` | If not granted, person still renders without presence |
 | Load profile photo (`fetchImage`) | `User.Read` | Falls back to initials if photo is unavailable |
 
@@ -218,7 +312,7 @@ Use explicit mode selection in your app:
 import { IProvider, ProviderState } from '@devsym/graph-toolkit-react';
 
 class MyAuthProvider implements IProvider {
-  state = ProviderState.SignedOut;
+  state: ProviderState = 'SignedOut';
   
   async login(): Promise<void> { /* ... */ }
   async logout(): Promise<void> { /* ... */ }
@@ -226,7 +320,6 @@ class MyAuthProvider implements IProvider {
 }
 ```
 
-<a id="storybook"></a>
 ## 📚 Storybook
 
 Explore all components interactively in our Storybook documentation:
@@ -279,10 +372,13 @@ npm run build-storybook
 ```
 src/
 ├── components/
-│   └── Person/
-│       ├── Person.tsx          # Component implementation
-│       ├── Person.types.ts     # TypeScript definitions
-│       └── __tests__/          # Component tests
+│   ├── Person/
+│   │   ├── Person.tsx          # Component implementation
+│   │   ├── Person.types.ts     # TypeScript definitions
+│   │   └── __tests__/          # Component tests
+│   └── People/
+│       ├── People.tsx          # Component implementation
+│       └── People.types.ts     # TypeScript definitions
 ├── providers/
 │   ├── IProvider.ts            # Provider interface
 │   ├── MockProvider.ts         # Development provider
@@ -290,11 +386,14 @@ src/
 ├── hooks/
 │   ├── useGraphClient.ts       # Graph client hook
 │   ├── usePersonData.ts        # Person data fetching
+│   ├── usePeopleList.ts        # People list fetching
 │   └── useProvider.ts          # Provider access
 └── index.ts                    # Public API
 
 stories/
-└── Person.stories.tsx          # Storybook stories (19 examples)
+├── Person.stories.tsx          # Person stories
+├── People.stories.tsx          # People stories
+└── PeoplePicker.stories.tsx    # PeoplePicker stories
 ```
 
 ## 🎯 Current Status
@@ -304,20 +403,21 @@ stories/
 - ✅ Repository restructured from monorepo to single package
 - ✅ Provider infrastructure with MockProvider for development
 - ✅ Person component using Fluent UI Persona
+- ✅ People component using Fluent UI AvatarGroup
+- ✅ PeoplePicker component using Fluent UI TagPicker
 - ✅ Full Persona configuration support (textAlignment, textPosition, sizing)
 - ✅ Build system (ESM + CJS + TypeScript declarations)
 - ✅ Storybook documentation and GitHub Pages deployment
 - ✅ CI/CD with GitHub Actions
 - ✅ Automatic Storybook deployment to GitHub Pages
-- ✅ Sample app with MSAL sign-in and `Person` (`userId="me"`) at `samples/react-msal-sample`
+- ✅ Sample app with MSAL sign-in and `Person`, `People`, and `PeoplePicker` demos at `samples/react-msal-sample`
 
 **Next Steps**:
-- Additional components (PeoplePicker, PersonCard, Login)
+- Additional components (PersonCard, Login, Agenda) — see [`docs/COMPONENT_ROADMAP.md`](./docs/COMPONENT_ROADMAP.md) for the full ranked list
 - Expanded provider guidance and production auth examples
 - Comprehensive test coverage
 - First stable release (1.0.0)
 
-<a id="contribute"></a>
 ## 🤝 Contribute
 
 This **community-driven project** provides React developers with components for Microsoft Graph. Contributions are welcome!
@@ -350,6 +450,6 @@ MIT License - see [LICENSE](LICENSE) for details.
 
 - **Fluent UI**: [react.fluentui.dev](https://react.fluentui.dev/)
 - **Microsoft Graph**: [graph.microsoft.com](https://graph.microsoft.com)
+- **Component Roadmap**: [docs/COMPONENT_ROADMAP.md](./docs/COMPONENT_ROADMAP.md)
 - **Changelog**: [CHANGELOG.md](CHANGELOG.md)
 - **Publishing**: [PUBLISHING.md](PUBLISHING.md)
-