@khester/create-dynamics-app 2.6.6 → 2.8.0

package/templates/teams-app/_variants/tab.dashboard/src/App.tsx

@@ -0,0 +1,49 @@
+import * as React from 'react';
+import {
+  FluentProvider,
+  teamsLightTheme,
+  teamsDarkTheme,
+  teamsHighContrastTheme,
+  type Theme,
+  Spinner,
+} from '@fluentui/react-components';
+import { app } from '@microsoft/teams-js';
+import { useHashRoute } from './hooks/useHashRoute';
+import { useTabConfig } from './hooks/useTabConfig';
+import { Dashboard } from './components/Dashboard';
+import { Config } from './pages/Config';
+import { Remove } from './pages/Remove';
+
+const THEMES: Record<string, Theme> = {
+  default: teamsLightTheme,
+  dark: teamsDarkTheme,
+  contrast: teamsHighContrastTheme,
+};
+
+export const App: React.FC = () => {
+  const route = useHashRoute();
+  const { config, loading } = useTabConfig();
+  const [theme, setTheme] = React.useState<Theme>(teamsLightTheme);
+
+  React.useEffect(() => {
+    const init = async () => {
+      try {
+        await app.initialize();
+        const context = await app.getContext();
+        setTheme(THEMES[context.app.theme] ?? teamsLightTheme);
+        app.registerOnThemeChangeHandler((t) => setTheme(THEMES[t] ?? teamsLightTheme));
+      } catch {
+        // Standalone browser mode — keep the light theme.
+      }
+    };
+    void init();
+  }, []);
+
+  let page: React.ReactNode;
+  if (route === '/config') page = <Config />;
+  else if (route === '/remove') page = <Remove />;
+  else if (loading) page = <Spinner label="Loading dashboard…" />;
+  else page = <Dashboard config={config} />;
+
+  return <FluentProvider theme={theme}>{page}</FluentProvider>;
+};

package/templates/teams-app/_variants/tab.dashboard/src/auth-bridge.ts

@@ -0,0 +1,52 @@
+import { app, authentication } from '@microsoft/teams-js';
+import { PublicClientApplication } from '@azure/msal-browser';
+
+/**
+ * Auth bridge — loaded by auth.html inside the window Teams opens for
+ * `authentication.authenticate()`. MSAL's popup flow is blocked inside the Teams
+ * tab iframe, so interactive sign-in happens here: loginRedirect → back to this
+ * page → handleRedirectPromise → notifySuccess back to the tab.
+ */
+const setStatus = (msg: string): void => {
+  const el = document.getElementById('status');
+  if (el) el.textContent = msg;
+};
+
+(async () => {
+  try {
+    await app.initialize();
+
+    const clientId = import.meta.env.VITE_CLIENT_ID ?? '';
+    const tenantId = import.meta.env.VITE_TENANT_ID ?? 'common';
+    if (!clientId) throw new Error('VITE_CLIENT_ID is not set — copy env.local.template to .env.local');
+
+    const pca = new PublicClientApplication({
+      auth: {
+        clientId,
+        authority: `https://login.microsoftonline.com/${tenantId}`,
+        redirectUri: `${window.location.origin}/auth.html`,
+      },
+      cache: { cacheLocation: 'localStorage' },
+    });
+    await pca.initialize();
+
+    setStatus('Completing sign-in…');
+    const response = await pca.handleRedirectPromise();
+    if (response?.account) {
+      setStatus(`Signed in as ${response.account.username}`);
+      authentication.notifySuccess(response.account.username);
+      return;
+    }
+
+    setStatus('Redirecting to sign in…');
+    await pca.loginRedirect({ scopes: ['User.Read'] });
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    setStatus(`Sign-in failed: ${msg}`);
+    try {
+      authentication.notifyFailure(msg);
+    } catch {
+      // Outside a Teams auth window — the status line above is the surface.
+    }
+  }
+})();

package/templates/teams-app/_variants/tab.dashboard/src/components/Dashboard.tsx

@@ -0,0 +1,33 @@
+import * as React from 'react';
+import { Text } from '@fluentui/react-components';
+import { TasksWidget } from './widgets/TasksWidget';
+import { StatsWidget } from './widgets/StatsWidget';
+import type { TabConfig } from '../hooks/useTabConfig';
+
+/** Registry of available widgets — Config.tsx offers exactly these ids. */
+export const WIDGETS: Record<string, { label: string; component: React.FC }> = {
+  tasks: { label: 'My Tasks', component: TasksWidget },
+  stats: { label: 'At a Glance', component: StatsWidget },
+};
+
+export const Dashboard: React.FC<{ config: TabConfig }> = ({ config }) => (
+  <div style={{ display: 'flex', flexDirection: 'column', gap: 16, padding: 16 }}>
+    <Text size={600} weight="semibold">
+      {config.title}
+    </Text>
+    <div
+      style={{
+        display: 'grid',
+        gridTemplateColumns: 'repeat(auto-fill, minmax(280px, 1fr))',
+        gap: 16,
+      }}
+    >
+      {config.widgets.map((id) => {
+        const widget = WIDGETS[id];
+        if (!widget) return null;
+        const Widget = widget.component;
+        return <Widget key={id} />;
+      })}
+    </div>
+  </div>
+);

package/templates/teams-app/_variants/tab.dashboard/src/components/widgets/StatsWidget.tsx

@@ -0,0 +1,25 @@
+import * as React from 'react';
+import { Card, CardHeader, Text } from '@fluentui/react-components';
+
+const SAMPLE_STATS = [
+  { label: 'Open items', value: 12 },
+  { label: 'Due this week', value: 4 },
+  { label: 'Completed', value: 27 },
+];
+
+/** Sample stats widget — replace SAMPLE_STATS with a real data source. */
+export const StatsWidget: React.FC = () => (
+  <Card>
+    <CardHeader header={<Text weight="semibold">At a Glance</Text>} />
+    <div style={{ display: 'flex', gap: 24 }}>
+      {SAMPLE_STATS.map((stat) => (
+        <div key={stat.label} style={{ display: 'flex', flexDirection: 'column' }}>
+          <Text size={700} weight="bold">
+            {stat.value}
+          </Text>
+          <Text size={200}>{stat.label}</Text>
+        </div>
+      ))}
+    </div>
+  </Card>
+);

package/templates/teams-app/_variants/tab.dashboard/src/components/widgets/TasksWidget.tsx

@@ -0,0 +1,20 @@
+import * as React from 'react';
+import { Card, CardHeader, Text, Checkbox } from '@fluentui/react-components';
+
+const SAMPLE_TASKS = [
+  { id: 1, label: 'Review the quarterly report', done: true },
+  { id: 2, label: 'Prepare the customer demo', done: false },
+  { id: 3, label: 'Follow up with the design team', done: false },
+];
+
+/** Sample task-list widget — replace SAMPLE_TASKS with a real data source. */
+export const TasksWidget: React.FC = () => (
+  <Card>
+    <CardHeader header={<Text weight="semibold">My Tasks</Text>} />
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 4 }}>
+      {SAMPLE_TASKS.map((task) => (
+        <Checkbox key={task.id} label={task.label} defaultChecked={task.done} />
+      ))}
+    </div>
+  </Card>
+);

package/templates/teams-app/_variants/tab.dashboard/src/hooks/useHashRoute.ts

@@ -0,0 +1,16 @@
+import { useState, useEffect } from 'react';
+
+/**
+ * Tiny hash router — `#/config` → `/config`. Hash routing keeps the tab a single
+ * static bundle (no server rewrites needed on Static Web Apps), which is why the
+ * manifest's configurationUrl points at `/#/config`.
+ */
+export function useHashRoute(): string {
+  const [hash, setHash] = useState(window.location.hash);
+  useEffect(() => {
+    const onChange = () => setHash(window.location.hash);
+    window.addEventListener('hashchange', onChange);
+    return () => window.removeEventListener('hashchange', onChange);
+  }, []);
+  return hash.replace(/^#/, '') || '/';
+}

package/templates/teams-app/_variants/tab.dashboard/src/hooks/useTabConfig.ts

@@ -0,0 +1,70 @@
+import { useState, useEffect, useCallback } from 'react';
+import { app } from '@microsoft/teams-js';
+
+/** Per-tab dashboard settings, keyed by the Teams entityId (one config per pinned tab). */
+export interface TabConfig {
+  title: string;
+  /** Ids of the widgets to show (see components/widgets). */
+  widgets: string[];
+}
+
+export const DEFAULT_CONFIG: TabConfig = {
+  title: 'Dashboard',
+  widgets: ['tasks', 'stats'],
+};
+
+const STORAGE_KEY = 'tab-config';
+
+/**
+ * Load + persist the tab's config. Storage is localStorage keyed by the Teams
+ * entityId — swap `loadConfig`/`saveConfig` for a backing service when the
+ * dashboard needs org-wide settings.
+ */
+export function useTabConfig(): {
+  config: TabConfig;
+  entityId: string;
+  loading: boolean;
+  saveConfig: (config: TabConfig, entityIdOverride?: string) => void;
+} {
+  const [config, setConfig] = useState<TabConfig>(DEFAULT_CONFIG);
+  const [entityId, setEntityId] = useState('default');
+  const [loading, setLoading] = useState(true);
+
+  useEffect(() => {
+    const load = async () => {
+      let id = 'default';
+      try {
+        await app.initialize();
+        const context = await app.getContext();
+        id = context.page?.id || 'default';
+      } catch {
+        // Outside Teams — allow ?entityId= for local testing.
+        id = new URLSearchParams(window.location.search).get('entityId') || 'default';
+      }
+      setEntityId(id);
+      const stored = localStorage.getItem(`${STORAGE_KEY}-${id}`);
+      if (stored) {
+        try {
+          setConfig(JSON.parse(stored) as TabConfig);
+        } catch {
+          setConfig(DEFAULT_CONFIG);
+        }
+      }
+      setLoading(false);
+    };
+    void load();
+  }, []);
+
+  const saveConfig = useCallback(
+    (next: TabConfig, entityIdOverride?: string) => {
+      // The config page mints a fresh entityId for a first-time pin (the Teams
+      // context has no page id yet during configuration) — persist under it.
+      const id = entityIdOverride ?? entityId;
+      localStorage.setItem(`${STORAGE_KEY}-${id}`, JSON.stringify(next));
+      setConfig(next);
+    },
+    [entityId]
+  );
+
+  return { config, entityId, loading, saveConfig };
+}

package/templates/teams-app/_variants/tab.dashboard/src/hooks/useTeamsAuth.ts

@@ -0,0 +1,121 @@
+import { useState, useEffect, useCallback } from 'react';
+import { app, authentication } from '@microsoft/teams-js';
+import { PublicClientApplication, type AccountInfo } from '@azure/msal-browser';
+
+/**
+ * Teams-first auth: try Teams SSO (`authentication.getAuthToken()`), fall back to
+ * MSAL. Inside the Teams iframe, interactive sign-in must go through the auth
+ * bridge (`auth.html`) — `loginPopup` is blocked there; outside Teams (plain
+ * browser tab) MSAL redirect works directly.
+ *
+ * VITE_CLIENT_ID / VITE_TENANT_ID come from `.env.local` (see env.local.template);
+ * `teams-app-manager.sh identity` writes them after registering the Entra app.
+ */
+const clientId = import.meta.env.VITE_CLIENT_ID ?? '';
+const tenantId = import.meta.env.VITE_TENANT_ID ?? 'common';
+
+const msalInstance = new PublicClientApplication({
+  auth: {
+    clientId,
+    authority: `https://login.microsoftonline.com/${tenantId}`,
+    redirectUri: window.location.origin,
+  },
+  cache: { cacheLocation: 'localStorage' },
+});
+
+export interface AuthState {
+  token: string | null;
+  account: AccountInfo | null;
+  inTeams: boolean;
+  loading: boolean;
+  error: Error | null;
+}
+
+export function useTeamsAuth(): AuthState & { login: () => Promise<void> } {
+  const [state, setState] = useState<AuthState>({
+    token: null,
+    account: null,
+    inTeams: false,
+    loading: true,
+    error: null,
+  });
+
+  const getToken = useCallback(async () => {
+    // 1. Teams SSO — works once the app registration exposes api://{host}/{clientId}
+    //    with the Teams client ids pre-authorized.
+    try {
+      await app.initialize();
+      const ssoToken = await authentication.getAuthToken();
+      setState({ token: ssoToken, account: null, inTeams: true, loading: false, error: null });
+      return;
+    } catch {
+      // Not in Teams, or SSO not consented yet — fall through to MSAL.
+    }
+
+    // 2. MSAL silent — a previous interactive sign-in left an account in the cache.
+    try {
+      await msalInstance.initialize();
+      const redirect = await msalInstance.handleRedirectPromise().catch(() => null);
+      const account = redirect?.account ?? msalInstance.getAllAccounts()[0];
+      if (account) {
+        const result = await msalInstance.acquireTokenSilent({
+          scopes: ['User.Read'],
+          account,
+        });
+        setState({
+          token: result.accessToken,
+          account: result.account,
+          inTeams: false,
+          loading: false,
+          error: null,
+        });
+        return;
+      }
+      setState((prev) => ({ ...prev, loading: false }));
+    } catch (error) {
+      setState((prev) => ({ ...prev, loading: false, error: error as Error }));
+    }
+  }, []);
+
+  /** Interactive sign-in. In Teams → auth bridge popup; in a browser → MSAL redirect. */
+  const login = useCallback(async () => {
+    if (!clientId) {
+      setState((prev) => ({
+        ...prev,
+        error: new Error('VITE_CLIENT_ID is not set — copy env.local.template to .env.local'),
+      }));
+      return;
+    }
+    let inTeams = false;
+    try {
+      await app.initialize();
+      inTeams = true;
+    } catch {
+      // Plain browser tab.
+    }
+
+    try {
+      if (inTeams) {
+        // Teams opens auth.html in a real window where MSAL's redirect flow is
+        // allowed; the bridge calls notifySuccess/notifyFailure when done.
+        await authentication.authenticate({
+          url: `${window.location.origin}/auth.html`,
+          width: 600,
+          height: 535,
+        });
+        await getToken();
+        return;
+      }
+      await msalInstance.initialize();
+      await msalInstance.loginRedirect({ scopes: ['User.Read'] });
+    } catch (error) {
+      setState((prev) => ({ ...prev, error: error as Error }));
+    }
+  }, [getToken]);
+
+  useEffect(() => {
+    void getToken();
+  }, [getToken]);
+
+  return { ...state, login };
+}

package/templates/teams-app/_variants/tab.dashboard/src/pages/Config.tsx

@@ -0,0 +1,118 @@
+import * as React from 'react';
+import {
+  Text,
+  Input,
+  Checkbox,
+  Button,
+  MessageBar,
+  MessageBarBody,
+} from '@fluentui/react-components';
+import { app, pages } from '@microsoft/teams-js';
+import { useTabConfig, type TabConfig } from '../hooks/useTabConfig';
+import { WIDGETS } from '../components/Dashboard';
+
+/**
+ * The channel-tab configuration page (manifest configurableTabs.configurationUrl
+ * → /#/config). Inside Teams, saving goes through pages.config.registerOnSaveHandler;
+ * outside Teams a plain Save button exercises the same persistence for local testing.
+ */
+export const Config: React.FC = () => {
+  const { config, entityId, loading, saveConfig } = useTabConfig();
+  const [draft, setDraft] = React.useState<TabConfig | null>(null);
+  const [inTeams, setInTeams] = React.useState(false);
+  const [saved, setSaved] = React.useState(false);
+
+  const current = draft ?? config;
+  const draftRef = React.useRef(current);
+  draftRef.current = current;
+
+  React.useEffect(() => {
+    const init = async () => {
+      try {
+        await app.initialize();
+        setInTeams(true);
+        pages.config.registerOnSaveHandler((saveEvent) => {
+          const next = draftRef.current;
+          // During first-time configuration the Teams context has no page id yet,
+          // so every tab would collide on 'default' — mint a unique entityId; it
+          // comes back as context.page.id when the pinned tab loads.
+          const saveEntityId =
+            entityId && entityId !== 'default' ? entityId : `dashboard-${Date.now()}`;
+          void pages.config
+            .setConfig({
+              suggestedDisplayName: next.title,
+              entityId: saveEntityId,
+              contentUrl: `${window.location.origin}/`,
+              websiteUrl: `${window.location.origin}/`,
+              removeUrl: `${window.location.origin}/#/remove`,
+            })
+            .then(() => {
+              saveConfig(next, saveEntityId);
+              saveEvent.notifySuccess();
+            })
+            .catch(() => saveEvent.notifyFailure('Failed to save tab configuration'));
+        });
+        void pages.config.setValidityState(true);
+      } catch {
+        setInTeams(false);
+      }
+    };
+    void init();
+  }, [entityId, saveConfig]);
+
+  if (loading) return null;
+
+  const toggleWidget = (id: string, checked: boolean) => {
+    const widgets = checked
+      ? [...current.widgets.filter((w) => w !== id), id]
+      : current.widgets.filter((w) => w !== id);
+    setDraft({ ...current, widgets });
+  };
+
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 12, padding: 16, maxWidth: 480 }}>
+      <Text size={500} weight="semibold">
+        Configure dashboard
+      </Text>
+      <Input
+        value={current.title}
+        onChange={(_, data) => setDraft({ ...current, title: data.value })}
+        placeholder="Dashboard title"
+        aria-label="Dashboard title"
+      />
+      <Text weight="semibold">Widgets</Text>
+      {Object.entries(WIDGETS).map(([id, w]) => (
+        <Checkbox
+          key={id}
+          label={w.label}
+          checked={current.widgets.includes(id)}
+          onChange={(_, data) => toggleWidget(id, data.checked === true)}
+        />
+      ))}
+      {!inTeams && (
+        <>
+          <MessageBar intent="info">
+            <MessageBarBody>Running outside Teams — Save persists locally.</MessageBarBody>
+          </MessageBar>
+          <div>
+            <Button
+              appearance="primary"
+              onClick={() => {
+                saveConfig(current);
+                setSaved(true);
+                setTimeout(() => setSaved(false), 3000);
+              }}
+            >
+              Save
+            </Button>
+          </div>
+          {saved && (
+            <MessageBar intent="success">
+              <MessageBarBody>Saved.</MessageBarBody>
+            </MessageBar>
+          )}
+        </>
+      )}
+    </div>
+  );
+};

package/templates/teams-app/_variants/tab.dashboard/src/pages/Remove.tsx

@@ -0,0 +1,12 @@
+import * as React from 'react';
+import { Text } from '@fluentui/react-components';
+
+/** Shown by Teams when the tab is removed (configurableTabs removeUrl default). */
+export const Remove: React.FC = () => (
+  <div style={{ padding: 16 }}>
+    <Text>
+      Removing this tab deletes its saved dashboard configuration for this channel. The app itself
+      stays installed.
+    </Text>
+  </div>
+);

package/templates/teams-app/_variants/tab.dashboard/src/vite-env.d.ts

@@ -0,0 +1,10 @@
+/// <reference types="vite/client" />
+
+interface ImportMetaEnv {
+  readonly VITE_CLIENT_ID?: string;
+  readonly VITE_TENANT_ID?: string;
+}
+
+interface ImportMeta {
+  readonly env: ImportMetaEnv;
+}

package/templates/teams-app/_variants/tab.dashboard/vite.config.ts

@@ -0,0 +1,19 @@
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import { fileURLToPath, URL } from 'node:url';
+
+export default defineConfig({
+  plugins: [react()],
+  // Teams tabs must be served over HTTPS; `vite --https` or a tunnel in dev.
+  server: { port: 3000 },
+  build: {
+    outDir: 'dist',
+    rollupOptions: {
+      // MPA: the tab plus the auth bridge Teams opens for interactive sign-in.
+      input: {
+        main: fileURLToPath(new URL('./index.html', import.meta.url)),
+        auth: fileURLToPath(new URL('./auth.html', import.meta.url)),
+      },
+    },
+  },
+});

package/templates/teams-app/_variants/tab.sso/appPackage/manifest.template.json

@@ -0,0 +1,31 @@
+{
+  "$schema": "https://developer.microsoft.com/en-us/json-schemas/teams/v1.19/MicrosoftTeams.schema.json",
+  "manifestVersion": "1.19",
+  "id": "{{TEAMS_APP_ID}}",
+  "version": "1.0.0",
+  "developer": {
+    "name": "Contoso",
+    "websiteUrl": "https://example.com",
+    "privacyUrl": "https://example.com/privacy",
+    "termsOfUseUrl": "https://example.com/terms"
+  },
+  "name": { "short": "{{projectName}}", "full": "{{projectName}}" },
+  "description": { "short": "{{projectName}} tab", "full": "{{projectName}} Microsoft Teams tab with single sign-on" },
+  "icons": { "color": "color.png", "outline": "outline.png" },
+  "accentColor": "#6264A7",
+  "staticTabs": [
+    {
+      "entityId": "home",
+      "name": "{{projectName}}",
+      "contentUrl": "https://{{HOSTNAME}}/",
+      "websiteUrl": "https://{{HOSTNAME}}/",
+      "scopes": ["personal"]
+    }
+  ],
+  "permissions": ["identity"],
+  "validDomains": ["{{HOSTNAME}}"],
+  "webApplicationInfo": {
+    "id": "{{CLIENT_ID}}",
+    "resource": "api://{{HOSTNAME}}/{{CLIENT_ID}}"
+  }
+}

package/templates/teams-app/_variants/tab.sso/auth.html

@@ -0,0 +1,15 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>{{projectName}} — Sign in</title>
+    <style>
+      body { font-family: system-ui, -apple-system, "Segoe UI", sans-serif; padding: 24px; color: #555; }
+    </style>
+  </head>
+  <body>
+    <p id="status">Working…</p>
+    <script type="module" src="/src/auth-bridge.ts"></script>
+  </body>
+</html>

package/templates/teams-app/_variants/tab.sso/env.local.template

@@ -0,0 +1,3 @@
+# Copy to .env.local — `teams-app-manager.sh identity` fills these automatically.
+VITE_CLIENT_ID=
+VITE_TENANT_ID=

package/templates/teams-app/_variants/tab.sso/src/App.tsx

@@ -0,0 +1,57 @@
+import * as React from 'react';
+import {
+  FluentProvider,
+  teamsLightTheme,
+  Text,
+  Spinner,
+  Button,
+  MessageBar,
+  MessageBarBody,
+} from '@fluentui/react-components';
+import { useTeamsAuth } from './hooks/useTeamsAuth';
+
+export const App: React.FC = () => {
+  const { token, account, inTeams, loading, error, login } = useTeamsAuth();
+
+  return (
+    <FluentProvider theme={teamsLightTheme}>
+      <div style={{ display: 'flex', flexDirection: 'column', gap: 12, padding: 16 }}>
+        <Text size={600} weight="semibold">{{projectName}}</Text>
+        <Text>Microsoft Teams tab with single sign-on — Fluent UI v9.</Text>
+
+        {loading && <Spinner label="Signing in…" />}
+
+        {!loading && token && (
+          <MessageBar intent="success">
+            <MessageBarBody>
+              Signed in{account ? ` as ${account.username}` : ' via Teams SSO'}
+              {inTeams ? ' (Teams SSO token acquired)' : ' (MSAL fallback)'}
+            </MessageBarBody>
+          </MessageBar>
+        )}
+
+        {!loading && !token && (
+          <>
+            <MessageBar intent="info">
+              <MessageBarBody>
+                Not signed in. Teams SSO needs the Entra app registration in place
+                (run <code>teams-app-manager.sh identity</code>); the button below signs in interactively.
+              </MessageBarBody>
+            </MessageBar>
+            <div>
+              <Button appearance="primary" onClick={() => void login()}>
+                Sign in
+              </Button>
+            </div>
+          </>
+        )}
+
+        {error && (
+          <MessageBar intent="error">
+            <MessageBarBody>{error.message}</MessageBarBody>
+          </MessageBar>
+        )}
+      </div>
+    </FluentProvider>
+  );
+};