@apvee/spfx-react-toolkit 1.0.0

package/lib/hooks/useSPFxSiteInfo.js

@@ -0,0 +1,109 @@
+// useSPFxSiteInfo.ts
+// Hook to access site collection and web information
+import { useSPFxPageContext } from './useSPFxPageContext';
+/**
+ * Hook to access site collection and web information
+ *
+ * Provides comprehensive information about the current SharePoint web (site/subsite)
+ * and parent site collection in a unified, flat structure.
+ *
+ * **Property naming pattern**:
+ * - **Identity properties** (id, url, serverRelativeUrl): Prefixed with `web` or `site` for clarity
+ * - **Web metadata** (title, languageId, logoUrl): No prefix (unique to web, most commonly used)
+ * - **Site properties**: All prefixed with `site` for consistency
+ *
+ * **Web properties** (primary context - 90% use case):
+ * - webId, webUrl, webServerRelativeUrl: Web identity
+ * - title: Web display name (most commonly used)
+ * - languageId: Web language (LCID)
+ * - logoUrl: Site logo URL (for branding)
+ *
+ * **Site collection properties** (parent context - 30-40% specialized):
+ * - siteId, siteUrl, siteServerRelativeUrl: Site collection identity
+ * - siteClassification: Enterprise classification label (e.g., "Confidential", "Public")
+ * - siteGroup: Microsoft 365 Group information (if group-connected)
+ *
+ * Note: In most cases (90%), you'll use web properties. Site collection properties
+ * are for specialized scenarios like subsites navigation, classification displays,
+ * or Microsoft 365 Group detection.
+ *
+ * @returns Site collection and web information
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const {
+ *     webUrl,             // Web URL (identity)
+ *     title,              // Web title (most common)
+ *     languageId,         // Web language
+ *     logoUrl,            // Site logo (branding)
+ *     siteClassification, // Site classification (enterprise)
+ *     siteGroup           // M365 Group info (if group-connected)
+ *   } = useSPFxSiteInfo();
+ *
+ *   return (
+ *     <header>
+ *       {logoUrl && <img src={logoUrl} alt="Site logo" />}
+ *       <h1>{title}</h1>
+ *       <a href={webUrl}>Visit Site</a>
+ *
+ *       {siteClassification && (
+ *         <Label>Classification: {siteClassification}</Label>
+ *       )}
+ *
+ *       {siteGroup && (
+ *         <Badge>
+ *           {siteGroup.isPublic ? 'Public Team' : 'Private Team'}
+ *         </Badge>
+ *       )}
+ *
+ *       <p>Language ID: {languageId}</p>
+ *     </header>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Cross-site navigation (subsite scenario)
+ * function Navigation() {
+ *   const { webUrl, siteUrl, title } = useSPFxSiteInfo();
+ *
+ *   return (
+ *     <nav>
+ *       <a href={siteUrl}>Site Collection Home</a>
+ *       <span> / </span>
+ *       <a href={webUrl}>{title}</a>
+ *     </nav>
+ *   );
+ * }
+ * ```
+ */
+export function useSPFxSiteInfo() {
+    var _a, _b;
+    var pageContext = useSPFxPageContext();
+    var siteObj = pageContext.site;
+    var webObj = pageContext.web;
+    // Try to get additional properties from legacy context
+    var legacy = pageContext.legacyPageContext;
+    return {
+        // Web identity (prefixed)
+        webId: webObj.id.toString(),
+        webUrl: webObj.absoluteUrl,
+        webServerRelativeUrl: webObj.serverRelativeUrl,
+        // Web metadata (no prefix - unique, most common)
+        title: webObj.title,
+        languageId: (_a = webObj.language) !== null && _a !== void 0 ? _a : 1033, // Default to English
+        logoUrl: webObj.logoUrl,
+        // Site collection (all prefixed)
+        siteId: siteObj.id.toString(),
+        siteUrl: siteObj.absoluteUrl,
+        siteServerRelativeUrl: siteObj.serverRelativeUrl,
+        siteClassification: legacy === null || legacy === void 0 ? void 0 : legacy.siteClassification,
+        siteGroup: siteObj.group ? {
+            id: siteObj.group.id.toString(),
+            isPublic: (_b = siteObj.group.isPublic) !== null && _b !== void 0 ? _b : false,
+        } : undefined,
+    };
+}
+//# sourceMappingURL=useSPFxSiteInfo.js.map

package/lib/hooks/useSPFxSiteInfo.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useSPFxSiteInfo.js","sourceRoot":"","sources":["../../src/hooks/useSPFxSiteInfo.ts"],"names":[],"mappings":"AAAA,qBAAqB;AACrB,qDAAqD;AAErD,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAsD1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6EG;AACH,MAAM,UAAU,eAAe;;IAC7B,IAAM,WAAW,GAAG,kBAAkB,EAAE,CAAC;IAEzC,IAAM,OAAO,GAAG,WAAW,CAAC,IAAI,CAAC;IACjC,IAAM,MAAM,GAAG,WAAW,CAAC,GAAG,CAAC;IAE/B,uDAAuD;IACvD,IAAM,MAAM,GAAI,WAId,CAAC,iBAAiB,CAAC;IAErB,OAAO;QACL,0BAA0B;QAC1B,KAAK,EAAE,MAAM,CAAC,EAAE,CAAC,QAAQ,EAAE;QAC3B,MAAM,EAAE,MAAM,CAAC,WAAW;QAC1B,oBAAoB,EAAE,MAAM,CAAC,iBAAiB;QAE9C,iDAAiD;QACjD,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,UAAU,EAAE,MAAA,MAAM,CAAC,QAAQ,mCAAI,IAAI,EAAE,qBAAqB;QAC1D,OAAO,EAAG,MAA0C,CAAC,OAAO;QAE5D,iCAAiC;QACjC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE;QAC7B,OAAO,EAAE,OAAO,CAAC,WAAW;QAC5B,qBAAqB,EAAE,OAAO,CAAC,iBAAiB;QAChD,kBAAkB,EAAE,MAAM,aAAN,MAAM,uBAAN,MAAM,CAAE,kBAAkB;QAC9C,SAAS,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC;YACzB,EAAE,EAAE,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,QAAQ,EAAE;YAC/B,QAAQ,EAAE,MAAA,OAAO,CAAC,KAAK,CAAC,QAAQ,mCAAI,KAAK;SAC1C,CAAC,CAAC,CAAC,SAAS;KACd,CAAC;AACJ,CAAC"}

package/lib/hooks/useSPFxStorage.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Return type for storage hooks
+ */
+export interface SPFxStorageHook<T> {
+    /** Current value */
+    readonly value: T;
+    /** Set new value */
+    readonly setValue: (value: T | ((prev: T) => T)) => void;
+    /** Remove value (reset to default) */
+    readonly remove: () => void;
+}
+/**
+ * Hook to use localStorage scoped to SPFx instance
+ *
+ * Creates a persisted state atom using Jotai's atomWithStorage.
+ * The storage key is automatically scoped to the SPFx instance ID,
+ * ensuring isolation between different web parts/extensions.
+ *
+ * Data persists across page reloads and sessions.
+ *
+ * Use for:
+ * - User preferences
+ * - Form drafts
+ * - Long-lived cache
+ * - Settings
+ *
+ * @param key - Storage key (will be prefixed with instance ID)
+ * @param defaultValue - Default value if not in storage
+ * @returns Storage hook with value, setValue, and remove
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { value, setValue } = useSPFxLocalStorage('view-mode', 'grid');
+ *
+ *   return (
+ *     <div>
+ *       <p>View: {value}</p>
+ *       <button onClick={() => setValue('list')}>List View</button>
+ *       <button onClick={() => setValue('grid')}>Grid View</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare function useSPFxLocalStorage<T>(key: string, defaultValue: T): SPFxStorageHook<T>;
+/**
+ * Hook to use sessionStorage scoped to SPFx instance
+ *
+ * Creates a persisted state atom using Jotai's atomWithStorage.
+ * The storage key is automatically scoped to the SPFx instance ID,
+ * ensuring isolation between different web parts/extensions.
+ *
+ * Data persists only for the current browser session/tab.
+ *
+ * Use for:
+ * - Temporary state
+ * - Session-specific cache
+ * - Tab-specific settings
+ * - Wizard state
+ *
+ * @param key - Storage key (will be prefixed with instance ID)
+ * @param defaultValue - Default value if not in storage
+ * @returns Storage hook with value, setValue, and remove
+ *
+ * @example
+ * ```tsx
+ * function WizardComponent() {
+ *   const { value: step, setValue: setStep } = useSPFxSessionStorage('wizard-step', 1);
+ *
+ *   return (
+ *     <div>
+ *       <p>Step: {step}</p>
+ *       <button onClick={() => setStep(s => s + 1)}>Next</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare function useSPFxSessionStorage<T>(key: string, defaultValue: T): SPFxStorageHook<T>;
+//# sourceMappingURL=useSPFxStorage.d.ts.map

package/lib/hooks/useSPFxStorage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useSPFxStorage.d.ts","sourceRoot":"","sources":["../../src/hooks/useSPFxStorage.ts"],"names":[],"mappings":"AAQA;;GAEG;AACH,MAAM,WAAW,eAAe,CAAC,CAAC;IAChC,oBAAoB;IACpB,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;IAElB,oBAAoB;IACpB,QAAQ,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,IAAI,CAAC;IAEzD,sCAAsC;IACtC,QAAQ,CAAC,MAAM,EAAE,MAAM,IAAI,CAAC;CAC7B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EACnC,GAAG,EAAE,MAAM,EACX,YAAY,EAAE,CAAC,GACd,eAAe,CAAC,CAAC,CAAC,CA2BpB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,EACrC,GAAG,EAAE,MAAM,EACX,YAAY,EAAE,CAAC,GACd,eAAe,CAAC,CAAC,CAAC,CAwDpB"}

package/lib/hooks/useSPFxStorage.js

@@ -0,0 +1,140 @@
+// useSPFxStorage.ts
+// Hooks for persisted storage scoped to SPFx instance
+import { atomWithStorage } from 'jotai/utils';
+import { useAtom } from 'jotai';
+import { useMemo } from 'react';
+import { useSPFxInstanceInfo } from './useSPFxInstanceInfo';
+/**
+ * Hook to use localStorage scoped to SPFx instance
+ *
+ * Creates a persisted state atom using Jotai's atomWithStorage.
+ * The storage key is automatically scoped to the SPFx instance ID,
+ * ensuring isolation between different web parts/extensions.
+ *
+ * Data persists across page reloads and sessions.
+ *
+ * Use for:
+ * - User preferences
+ * - Form drafts
+ * - Long-lived cache
+ * - Settings
+ *
+ * @param key - Storage key (will be prefixed with instance ID)
+ * @param defaultValue - Default value if not in storage
+ * @returns Storage hook with value, setValue, and remove
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { value, setValue } = useSPFxLocalStorage('view-mode', 'grid');
+ *
+ *   return (
+ *     <div>
+ *       <p>View: {value}</p>
+ *       <button onClick={() => setValue('list')}>List View</button>
+ *       <button onClick={() => setValue('grid')}>Grid View</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export function useSPFxLocalStorage(key, defaultValue) {
+    var instanceId = useSPFxInstanceInfo().id;
+    // Create scoped storage key
+    var scopedKey = 'spfx:' + instanceId + ':' + key;
+    // Create atom with storage (memoized to avoid recreation)
+    var storageAtom = useMemo(function () { return atomWithStorage(scopedKey, defaultValue); }, [scopedKey, defaultValue]);
+    var _a = useAtom(storageAtom), value = _a[0], setValue = _a[1];
+    // Remove function (reset to default)
+    var remove = function () {
+        setValue(defaultValue);
+        if (typeof localStorage !== 'undefined') {
+            localStorage.removeItem(scopedKey);
+        }
+    };
+    return {
+        value: value,
+        setValue: setValue,
+        remove: remove,
+    };
+}
+/**
+ * Hook to use sessionStorage scoped to SPFx instance
+ *
+ * Creates a persisted state atom using Jotai's atomWithStorage.
+ * The storage key is automatically scoped to the SPFx instance ID,
+ * ensuring isolation between different web parts/extensions.
+ *
+ * Data persists only for the current browser session/tab.
+ *
+ * Use for:
+ * - Temporary state
+ * - Session-specific cache
+ * - Tab-specific settings
+ * - Wizard state
+ *
+ * @param key - Storage key (will be prefixed with instance ID)
+ * @param defaultValue - Default value if not in storage
+ * @returns Storage hook with value, setValue, and remove
+ *
+ * @example
+ * ```tsx
+ * function WizardComponent() {
+ *   const { value: step, setValue: setStep } = useSPFxSessionStorage('wizard-step', 1);
+ *
+ *   return (
+ *     <div>
+ *       <p>Step: {step}</p>
+ *       <button onClick={() => setStep(s => s + 1)}>Next</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export function useSPFxSessionStorage(key, defaultValue) {
+    var instanceId = useSPFxInstanceInfo().id;
+    // Create scoped storage key
+    var scopedKey = 'spfx:' + instanceId + ':' + key;
+    // Create atom with session storage
+    var storageAtom = useMemo(function () { return atomWithStorage(scopedKey, defaultValue, {
+        getItem: function (key) {
+            if (typeof sessionStorage === 'undefined') {
+                return defaultValue;
+            }
+            var item = sessionStorage.getItem(key);
+            if (item === null) {
+                return defaultValue;
+            }
+            try {
+                return JSON.parse(item);
+            }
+            catch (_a) {
+                return defaultValue;
+            }
+        },
+        setItem: function (key, value) {
+            if (typeof sessionStorage !== 'undefined') {
+                sessionStorage.setItem(key, JSON.stringify(value));
+            }
+        },
+        removeItem: function (key) {
+            if (typeof sessionStorage !== 'undefined') {
+                sessionStorage.removeItem(key);
+            }
+        },
+    }); }, [scopedKey, defaultValue]);
+    var _a = useAtom(storageAtom), value = _a[0], setValue = _a[1];
+    // Remove function (reset to default)
+    var remove = function () {
+        setValue(defaultValue);
+        if (typeof sessionStorage !== 'undefined') {
+            sessionStorage.removeItem(scopedKey);
+        }
+    };
+    return {
+        value: value,
+        setValue: setValue,
+        remove: remove,
+    };
+}
+//# sourceMappingURL=useSPFxStorage.js.map

package/lib/hooks/useSPFxStorage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useSPFxStorage.js","sourceRoot":"","sources":["../../src/hooks/useSPFxStorage.ts"],"names":[],"mappings":"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"}

package/lib/hooks/useSPFxTeams.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Teams theme type
+ */
+export type TeamsTheme = 'default' | 'dark' | 'highContrast';
+/**
+ * Return type for useSPFxTeams hook
+ */
+export interface SPFxTeamsInfo {
+    /** Whether Teams context is supported/available */
+    readonly supported: boolean;
+    /** Teams context object (if available) */
+    readonly context: unknown | undefined;
+    /** Current Teams theme */
+    readonly theme: TeamsTheme | undefined;
+}
+/**
+ * Hook for Microsoft Teams context integration
+ *
+ * Provides access to Microsoft Teams context when SPFx component
+ * is running in Teams environment.
+ *
+ * Automatically initializes Teams SDK (supports both v1 and v2 APIs)
+ * and provides:
+ * - Teams context (team, channel, user info, etc.)
+ * - Teams theme (default, dark, high contrast)
+ * - Supported flag
+ *
+ * The initialization happens asynchronously on first mount.
+ *
+ * Useful for:
+ * - Teams-specific features
+ * - Theme synchronization
+ * - User context access
+ * - Channel/team information
+ * - Teams app integration
+ *
+ * @returns Teams context information
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { supported, context, theme } = useSPFxTeams();
+ *
+ *   if (!supported) {
+ *     return <div>Not in Teams</div>;
+ *   }
+ *
+ *   const teamsContext = context as {
+ *     user?: { id: string };
+ *     team?: { displayName: string };
+ *   };
+ *
+ *   return (
+ *     <div className={`teams-theme-${theme}`}>
+ *       <p>Team: {teamsContext.team?.displayName}</p>
+ *       <p>Theme: {theme}</p>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare function useSPFxTeams(): SPFxTeamsInfo;
+//# sourceMappingURL=useSPFxTeams.d.ts.map

package/lib/hooks/useSPFxTeams.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useSPFxTeams.d.ts","sourceRoot":"","sources":["../../src/hooks/useSPFxTeams.ts"],"names":[],"mappings":"AAQA;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,MAAM,GAAG,cAAc,CAAC;AAE7D;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,mDAAmD;IACnD,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAE5B,0CAA0C;IAC1C,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,SAAS,CAAC;IAEtC,0BAA0B;IAC1B,QAAQ,CAAC,KAAK,EAAE,UAAU,GAAG,SAAS,CAAC;CACxC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,wBAAgB,YAAY,IAAI,aAAa,CA2G5C"}

package/lib/hooks/useSPFxTeams.js

@@ -0,0 +1,198 @@
+// useSPFxTeams.ts
+// Hook for Microsoft Teams context integration
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __generator = (this && this.__generator) || function (thisArg, body) {
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g;
+    return g = { next: verb(0), "throw": verb(1), "return": verb(2) }, typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    function verb(n) { return function (v) { return step([n, v]); }; }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while (g && (g = 0, op[0] && (_ = 0)), _) try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [op[0] & 2, t.value];
+            switch (op[0]) {
+                case 0: case 1: t = op; break;
+                case 4: _.label++; return { value: op[1], done: false };
+                case 5: _.label++; y = op[1]; op = [0]; continue;
+                case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop(); continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+    }
+};
+import { useEffect } from 'react';
+import { useAtom } from 'jotai';
+import { spfxAtoms } from '../core/atoms.internal';
+import { useSPFxContext } from './useSPFxContext';
+/**
+ * Hook for Microsoft Teams context integration
+ *
+ * Provides access to Microsoft Teams context when SPFx component
+ * is running in Teams environment.
+ *
+ * Automatically initializes Teams SDK (supports both v1 and v2 APIs)
+ * and provides:
+ * - Teams context (team, channel, user info, etc.)
+ * - Teams theme (default, dark, high contrast)
+ * - Supported flag
+ *
+ * The initialization happens asynchronously on first mount.
+ *
+ * Useful for:
+ * - Teams-specific features
+ * - Theme synchronization
+ * - User context access
+ * - Channel/team information
+ * - Teams app integration
+ *
+ * @returns Teams context information
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { supported, context, theme } = useSPFxTeams();
+ *
+ *   if (!supported) {
+ *     return <div>Not in Teams</div>;
+ *   }
+ *
+ *   const teamsContext = context as {
+ *     user?: { id: string };
+ *     team?: { displayName: string };
+ *   };
+ *
+ *   return (
+ *     <div className={`teams-theme-${theme}`}>
+ *       <p>Team: {teamsContext.team?.displayName}</p>
+ *       <p>Theme: {theme}</p>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export function useSPFxTeams() {
+    var _this = this;
+    var spfxContext = useSPFxContext().spfxContext;
+    var _a = useAtom(spfxAtoms.teams), state = _a[0], setState = _a[1];
+    useEffect(function () {
+        // Skip if already initialized
+        if (state.initialized) {
+            return;
+        }
+        // Extract Teams SDK from context
+        var ctx = spfxContext;
+        var sdks = ctx.sdks;
+        var teamsSDK = sdks === null || sdks === void 0 ? void 0 : sdks.microsoftTeams;
+        if (!teamsSDK) {
+            setState({ supported: false, initialized: true });
+            return;
+        }
+        var disposed = false;
+        // Helper to apply context and theme
+        var apply = function (context, themeValue) {
+            if (disposed) {
+                return;
+            }
+            var normalizedTheme = ((themeValue === null || themeValue === void 0 ? void 0 : themeValue.toLowerCase()) === 'dark' ? 'dark' :
+                (themeValue === null || themeValue === void 0 ? void 0 : themeValue.toLowerCase()) === 'contrast' || (themeValue === null || themeValue === void 0 ? void 0 : themeValue.toLowerCase()) === 'highcontrast' ? 'highContrast' :
+                    'default');
+            setState({
+                supported: true,
+                context: context,
+                theme: normalizedTheme,
+                initialized: true,
+            });
+        };
+        // Try v2 API (teams 2.0+)
+        var tryV2 = function () { return __awaiter(_this, void 0, void 0, function () {
+            var context, themeValue, _a;
+            var _b, _c;
+            return __generator(this, function (_d) {
+                switch (_d.label) {
+                    case 0:
+                        _d.trys.push([0, 3, , 4]);
+                        if (!((_b = teamsSDK.app) === null || _b === void 0 ? void 0 : _b.getContext)) return [3 /*break*/, 2];
+                        return [4 /*yield*/, teamsSDK.app.getContext()];
+                    case 1:
+                        context = _d.sent();
+                        themeValue = (_c = context === null || context === void 0 ? void 0 : context.app) === null || _c === void 0 ? void 0 : _c.theme;
+                        apply(context, themeValue);
+                        return [2 /*return*/, true];
+                    case 2: return [2 /*return*/, false];
+                    case 3:
+                        _a = _d.sent();
+                        return [2 /*return*/, false];
+                    case 4: return [2 /*return*/];
+                }
+            });
+        }); };
+        // Try v1 API (teams 1.x)
+        var tryV1 = function () {
+            return new Promise(function (resolve) {
+                try {
+                    if (teamsSDK.getContext) {
+                        teamsSDK.getContext(function (context) {
+                            var themeValue = context === null || context === void 0 ? void 0 : context.theme;
+                            apply(context, themeValue);
+                            resolve(true);
+                        });
+                    }
+                    else {
+                        resolve(false);
+                    }
+                }
+                catch (_a) {
+                    resolve(false);
+                }
+            });
+        };
+        // Initialize async
+        var init = function () { return __awaiter(_this, void 0, void 0, function () {
+            var v2Success;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0: return [4 /*yield*/, tryV2()];
+                    case 1:
+                        v2Success = _a.sent();
+                        if (!!v2Success) return [3 /*break*/, 3];
+                        return [4 /*yield*/, tryV1()];
+                    case 2:
+                        _a.sent();
+                        _a.label = 3;
+                    case 3: return [2 /*return*/];
+                }
+            });
+        }); };
+        init().catch(function () {
+            // Fallback: mark as not supported
+            if (!disposed) {
+                setState({ supported: false, initialized: true });
+            }
+        });
+        return function () {
+            disposed = true;
+        };
+    }, [spfxContext, setState, state.initialized]);
+    return {
+        supported: state.supported,
+        context: state.context,
+        theme: state.theme,
+    };
+}
+//# sourceMappingURL=useSPFxTeams.js.map

package/lib/hooks/useSPFxTeams.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useSPFxTeams.js","sourceRoot":"","sources":["../../src/hooks/useSPFxTeams.ts"],"names":[],"mappings":"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"}