@devsym/graph-toolkit-react 1.0.0-next.5 → 1.0.0-next.6

package/AGENTS.md

@@ -0,0 +1,167 @@
+# 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>
+  );
+}
+```
+
+### 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 |
+| 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devsym/graph-toolkit-react",
-  "version": "1.0.0-next.5",
+  "version": "1.0.0-next.6",
   "description": "React components for Microsoft Graph powered by Fluent UI",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -15,6 +15,8 @@
   "files": [
     "dist",
     "README.md",
+    "AGENTS.md",
+    "MGT_MIGRATION.md",
     "LICENSE"
   ],
   "scripts": {

package/readme.md

@@ -13,6 +13,8 @@
 
 <h3 align="center">
   <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>
@@ -50,6 +52,32 @@ npm install @devsym/graph-toolkit-react
 | ------- | ------- | ----------- |
 | `@devsym/graph-toolkit-react` | `0.1.0-alpha.1` | React components for Microsoft Graph powered by Fluent UI |
 
+<a id="migration-from-mgt"></a>
+## 🔄 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
+
+<a id="agent-quick-reference"></a>
+## 🤖 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: