@apvee/spfx-react-toolkit 1.0.0

package/lib/hooks/useSPFxUserPhoto.js

@@ -0,0 +1,346 @@
+// useSPFxUserPhoto.ts
+// Hook to load user photos from Microsoft Graph API
+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 { useState, useCallback, useEffect, useRef } from 'react';
+import { useSPFxMSGraphClient } from './useSPFxMSGraphClient';
+/**
+ * Hook to load user photos from Microsoft Graph API
+ *
+ * Provides easy access to user profile photos with automatic blob URL management.
+ * Supports loading current user's photo or any user's photo by ID or email.
+ *
+ * Features:
+ * - Current user or specific user by ID/email
+ * - Multiple photo sizes (48x48 to 648x648)
+ * - Automatic blob URL creation and cleanup
+ * - Memory leak prevention (revokes URLs on unmount)
+ * - Type-safe with TypeScript
+ * - Auto-fetch on mount (configurable)
+ * - Manual reload function
+ *
+ * Microsoft Graph Permissions Required:
+ * - **User.Read**: Required for current user's photo (/me/photo)
+ * - **User.ReadBasic.All**: Required for other users' photos (/users/{id}/photo)
+ * - **User.Read.All**: Alternative permission for other users (more privileged)
+ *
+ * Permission Notes:
+ * - Application must have appropriate Graph API permissions configured in Azure AD
+ * - Permissions must be consented by admin or user (depending on permission type)
+ * - 404 errors typically mean the user has no photo (not a permission issue)
+ * - 403 errors indicate insufficient permissions
+ *
+ * Graph API Endpoints Used:
+ * - Current user: GET /me/photo/{size}/$value
+ * - By ID: GET /users/{id}/photo/{size}/$value
+ * - By email: GET /users/{email}/photo/{size}/$value
+ *
+ * @param options - Optional. Configuration for loading specific user's photo
+ *
+ * @example Current user photo
+ * ```tsx
+ * function UserAvatar() {
+ *   const { photoUrl, isLoading, error } = useSPFxUserPhoto();
+ *
+ *   if (isLoading) return <Spinner />;
+ *   if (error) return <DefaultAvatar />;
+ *
+ *   return <img src={photoUrl} alt="User" style={{ width: 240, height: 240 }} />;
+ * }
+ * ```
+ *
+ * @example Specific user by email
+ * ```tsx
+ * function TeamMemberAvatar({ email }: { email: string }) {
+ *   const { photoUrl, isLoading } = useSPFxUserPhoto({
+ *     email,
+ *     size: '96x96'
+ *   });
+ *
+ *   return (
+ *     <div>
+ *       {isLoading ? (
+ *         <Spinner />
+ *       ) : (
+ *         <img src={photoUrl || '/default-avatar.png'} alt={email} />
+ *       )}
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example Specific user by ID with reload
+ * ```tsx
+ * function ProfileCard({ userId }: { userId: string }) {
+ *   const { photoUrl, reload, isLoading, error } = useSPFxUserPhoto({
+ *     userId,
+ *     size: '360x360'
+ *   });
+ *
+ *   return (
+ *     <Stack>
+ *       {error ? (
+ *         <MessageBar messageBarType={MessageBarType.error}>
+ *           Failed to load photo: {error.message}
+ *         </MessageBar>
+ *       ) : (
+ *         <img src={photoUrl} alt="Profile" />
+ *       )}
+ *
+ *       <PrimaryButton
+ *         onClick={reload}
+ *         disabled={isLoading}
+ *         text="Refresh Photo"
+ *       />
+ *     </Stack>
+ *   );
+ * }
+ * ```
+ *
+ * @example Multiple sizes for responsive images
+ * ```tsx
+ * function ResponsiveAvatar() {
+ *   const small = useSPFxUserPhoto({ size: '96x96' });
+ *   const large = useSPFxUserPhoto({ size: '240x240' });
+ *
+ *   return (
+ *     <picture>
+ *       <source media="(min-width: 768px)" srcSet={large.photoUrl} />
+ *       <img src={small.photoUrl} alt="User Avatar" />
+ *     </picture>
+ *   );
+ * }
+ * ```
+ *
+ * @example Lazy loading with manual fetch
+ * ```tsx
+ * function LazyAvatar({ email }: { email: string }) {
+ *   const { photoUrl, reload, isLoading } = useSPFxUserPhoto({
+ *     email,
+ *     autoFetch: false  // Don't load on mount
+ *   });
+ *
+ *   return (
+ *     <div>
+ *       {photoUrl ? (
+ *         <img src={photoUrl} alt="Avatar" />
+ *       ) : (
+ *         <button onClick={reload} disabled={isLoading}>
+ *           {isLoading ? 'Loading...' : 'Load Photo'}
+ *         </button>
+ *       )}
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example With error fallback
+ * ```tsx
+ * function SafeAvatar() {
+ *   const { photoUrl, error, isReady } = useSPFxUserPhoto();
+ *
+ *   if (!isReady) {
+ *     return <Persona text="Loading..." size={PersonaSize.size72} />;
+ *   }
+ *
+ *   if (error || !photoUrl) {
+ *     // Fallback to Fluent UI Persona with initials
+ *     return <Persona text="John Doe" size={PersonaSize.size72} />;
+ *   }
+ *
+ *   return <img src={photoUrl} alt="User" className="avatar-round" />;
+ * }
+ * ```
+ *
+ * @example Access raw blob for processing
+ * ```tsx
+ * function PhotoUploader() {
+ *   const { photoBlob, photoUrl } = useSPFxUserPhoto();
+ *
+ *   const handleUploadToAzure = async () => {
+ *     if (!photoBlob) return;
+ *
+ *     const formData = new FormData();
+ *     formData.append('photo', photoBlob, 'profile.jpg');
+ *
+ *     await fetch('/api/upload', {
+ *       method: 'POST',
+ *       body: formData
+ *     });
+ *   };
+ *
+ *   return (
+ *     <div>
+ *       <img src={photoUrl} alt="Preview" />
+ *       <button onClick={handleUploadToAzure}>Upload to Azure</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export function useSPFxUserPhoto(options) {
+    var _this = this;
+    var graphClient = useSPFxMSGraphClient().client;
+    // Destructure options with defaults
+    var _a = options || {}, userId = _a.userId, email = _a.email, _b = _a.size, size = _b === void 0 ? '240x240' : _b, _c = _a.autoFetch, autoFetch = _c === void 0 ? true : _c;
+    // State management
+    var _d = useState(undefined), photoUrl = _d[0], setPhotoUrl = _d[1];
+    var _e = useState(undefined), photoBlob = _e[0], setPhotoBlob = _e[1];
+    var _f = useState(false), isLoading = _f[0], setIsLoading = _f[1];
+    var _g = useState(undefined), error = _g[0], setError = _g[1];
+    // Track component mounted state and current blob URL for cleanup
+    var isMounted = useRef(true);
+    var currentBlobUrl = useRef(undefined);
+    useEffect(function () {
+        isMounted.current = true;
+        return function () {
+            isMounted.current = false;
+            // Cleanup: revoke blob URL to prevent memory leaks
+            if (currentBlobUrl.current) {
+                URL.revokeObjectURL(currentBlobUrl.current);
+                currentBlobUrl.current = undefined;
+            }
+        };
+    }, []);
+    /**
+     * Build Graph API endpoint based on user identifier
+     */
+    var buildPhotoEndpoint = useCallback(function () {
+        // Determine base path
+        var basePath;
+        if (userId) {
+            // Specific user by ID
+            basePath = "/users/".concat(userId);
+        }
+        else if (email) {
+            // Specific user by email
+            basePath = "/users/".concat(email);
+        }
+        else {
+            // Current user
+            basePath = '/me';
+        }
+        // Append photo size endpoint
+        return "".concat(basePath, "/photos/").concat(size, "/$value");
+    }, [userId, email, size]);
+    /**
+     * Load photo from Microsoft Graph
+     */
+    var load = useCallback(function () { return __awaiter(_this, void 0, void 0, function () {
+        var err, endpoint, blob, blobUrl, err_1, error_1;
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0:
+                    if (!graphClient) {
+                        err = new Error('MSGraphClient not available. Cannot load photo.');
+                        console.error('[useSPFxUserPhoto]', err);
+                        if (isMounted.current) {
+                            setError(err);
+                        }
+                        return [2 /*return*/];
+                    }
+                    setIsLoading(true);
+                    setError(undefined);
+                    _a.label = 1;
+                case 1:
+                    _a.trys.push([1, 3, 4, 5]);
+                    endpoint = buildPhotoEndpoint();
+                    return [4 /*yield*/, graphClient
+                            .api(endpoint)
+                            .get()];
+                case 2:
+                    blob = _a.sent();
+                    if (isMounted.current) {
+                        // Revoke previous blob URL if exists
+                        if (currentBlobUrl.current) {
+                            URL.revokeObjectURL(currentBlobUrl.current);
+                        }
+                        blobUrl = URL.createObjectURL(blob);
+                        currentBlobUrl.current = blobUrl;
+                        setPhotoBlob(blob);
+                        setPhotoUrl(blobUrl);
+                    }
+                    return [3 /*break*/, 5];
+                case 3:
+                    err_1 = _a.sent();
+                    if (isMounted.current) {
+                        error_1 = err_1 instanceof Error ? err_1 : new Error(String(err_1));
+                        // Enhanced error messages (ES5-compatible)
+                        if (error_1.message.indexOf('404') !== -1) {
+                            error_1.message = 'Photo not found. User may not have a profile photo.';
+                        }
+                        else if (error_1.message.indexOf('403') !== -1) {
+                            error_1.message = 'Insufficient permissions to access photo. Check Graph API permissions.';
+                        }
+                        else if (error_1.message.indexOf('401') !== -1) {
+                            error_1.message = 'Authentication failed. User may not be signed in.';
+                        }
+                        setError(error_1);
+                        setPhotoUrl(undefined);
+                        setPhotoBlob(undefined);
+                        console.error('[useSPFxUserPhoto] Failed to load photo:', error_1);
+                    }
+                    return [3 /*break*/, 5];
+                case 4:
+                    if (isMounted.current) {
+                        setIsLoading(false);
+                    }
+                    return [7 /*endfinally*/];
+                case 5: return [2 /*return*/];
+            }
+        });
+    }); }, [graphClient, buildPhotoEndpoint]);
+    // Auto-fetch on mount if enabled
+    useEffect(function () {
+        if (autoFetch && graphClient) {
+            load().catch(function () {
+                // Error already handled in load() function
+            });
+        }
+    }, [autoFetch, graphClient, load]);
+    // Computed state: ready when photo loaded successfully
+    var isReady = !isLoading && !error && photoUrl !== undefined;
+    return {
+        photoUrl: photoUrl,
+        photoBlob: photoBlob,
+        isLoading: isLoading,
+        error: error,
+        reload: load,
+        isReady: isReady
+    };
+}
+//# sourceMappingURL=useSPFxUserPhoto.js.map

package/lib/hooks/useSPFxUserPhoto.js.map

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

package/lib/index.d.ts

@@ -0,0 +1,3 @@
+export * from './core';
+export * from './hooks';
+//# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,QAAQ,CAAC;AACvB,cAAc,SAAS,CAAC"}

package/lib/index.js

@@ -0,0 +1,3 @@
+export * from './core';
+export * from './hooks';
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,QAAQ,CAAC;AACvB,cAAc,SAAS,CAAC"}

package/lib/utils/index.d.ts

@@ -0,0 +1 @@
+//# sourceMappingURL=index.d.ts.map

package/lib/utils/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":""}

package/lib/utils/index.js

@@ -0,0 +1,3 @@
+// Empty - no public utilities to export
+// All utilities are internal and used only within the library
+//# sourceMappingURL=index.js.map

package/lib/utils/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,wCAAwC;AACxC,8DAA8D"}

package/lib/utils/resize-observer.internal.d.ts

@@ -0,0 +1,10 @@
+import type { ContainerSize } from '../core/types';
+/**
+ * Hook to observe element size changes using ResizeObserver
+ *
+ * @param element - DOM element to observe
+ * @param onResize - Callback when size changes
+ * @internal
+ */
+export declare function useResizeObserver(element: HTMLElement | undefined, onResize: (size: ContainerSize | undefined) => void): void;
+//# sourceMappingURL=resize-observer.internal.d.ts.map

package/lib/utils/resize-observer.internal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resize-observer.internal.d.ts","sourceRoot":"","sources":["../../src/utils/resize-observer.internal.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAEnD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,WAAW,GAAG,SAAS,EAChC,QAAQ,EAAE,CAAC,IAAI,EAAE,aAAa,GAAG,SAAS,KAAK,IAAI,GAClD,IAAI,CAwBN"}

package/lib/utils/resize-observer.internal.js

@@ -0,0 +1,34 @@
+// resize-observer.ts
+// Utility hook to observe element size changes
+import { useEffect } from 'react';
+/**
+ * Hook to observe element size changes using ResizeObserver
+ *
+ * @param element - DOM element to observe
+ * @param onResize - Callback when size changes
+ * @internal
+ */
+export function useResizeObserver(element, onResize) {
+    useEffect(function () {
+        // If no element or ResizeObserver not supported, clear size
+        if (!element || typeof ResizeObserver === 'undefined') {
+            onResize(undefined);
+            return;
+        }
+        // Create ResizeObserver
+        var observer = new ResizeObserver(function (entries) {
+            for (var _i = 0, entries_1 = entries; _i < entries_1.length; _i++) {
+                var entry = entries_1[_i];
+                var _a = entry.contentRect, width = _a.width, height = _a.height;
+                onResize({ width: width, height: height });
+            }
+        });
+        // Start observing
+        observer.observe(element);
+        // Cleanup on unmount
+        return function () {
+            observer.disconnect();
+        };
+    }, [element, onResize]);
+}
+//# sourceMappingURL=resize-observer.internal.js.map

package/lib/utils/resize-observer.internal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resize-observer.internal.js","sourceRoot":"","sources":["../../src/utils/resize-observer.internal.ts"],"names":[],"mappings":"AAAA,qBAAqB;AACrB,+CAA+C;AAE/C,OAAO,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAGlC;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAC/B,OAAgC,EAChC,QAAmD;IAEnD,SAAS,CAAC;QACR,4DAA4D;QAC5D,IAAI,CAAC,OAAO,IAAI,OAAO,cAAc,KAAK,WAAW,EAAE,CAAC;YACtD,QAAQ,CAAC,SAAS,CAAC,CAAC;YACpB,OAAO;QACT,CAAC;QAED,wBAAwB;QACxB,IAAM,QAAQ,GAAG,IAAI,cAAc,CAAC,UAAC,OAAO;YAC1C,KAAoB,UAAO,EAAP,mBAAO,EAAP,qBAAO,EAAP,IAAO,EAAE,CAAC;gBAAzB,IAAM,KAAK,gBAAA;gBACR,IAAA,KAAoB,KAAK,CAAC,WAAW,EAAnC,KAAK,WAAA,EAAE,MAAM,YAAsB,CAAC;gBAC5C,QAAQ,CAAC,EAAE,KAAK,OAAA,EAAE,MAAM,QAAA,EAAE,CAAC,CAAC;YAC9B,CAAC;QACH,CAAC,CAAC,CAAC;QAEH,kBAAkB;QAClB,QAAQ,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;QAE1B,qBAAqB;QACrB,OAAO;YACL,QAAQ,CAAC,UAAU,EAAE,CAAC;QACxB,CAAC,CAAC;IACJ,CAAC,EAAE,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAC;AAC1B,CAAC"}

package/lib/utils/theme-subscription.internal.d.ts

@@ -0,0 +1,11 @@
+import type { IReadonlyTheme } from '@microsoft/sp-component-base';
+/**
+ * Hook to subscribe to SPFx theme changes
+ * Automatically updates the provided setter when theme changes
+ *
+ * @param spfxContext - SPFx context object
+ * @param setTheme - Setter function to update theme state
+ * @internal
+ */
+export declare function useThemeSubscription(spfxContext: unknown, setTheme: (theme: IReadonlyTheme | undefined) => void): void;
+//# sourceMappingURL=theme-subscription.internal.d.ts.map

package/lib/utils/theme-subscription.internal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"theme-subscription.internal.d.ts","sourceRoot":"","sources":["../../src/utils/theme-subscription.internal.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAuBnE;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,WAAW,EAAE,OAAO,EACpB,QAAQ,EAAE,CAAC,KAAK,EAAE,cAAc,GAAG,SAAS,KAAK,IAAI,GACpD,IAAI,CAmCN"}

package/lib/utils/theme-subscription.internal.js

@@ -0,0 +1,58 @@
+// theme-subscription.ts
+// Utility hook to subscribe to SPFx theme changes
+import { useEffect } from 'react';
+import { ThemeProvider } from '@microsoft/sp-component-base';
+/**
+ * Extract ThemeProvider from SPFx context
+ * Works with any SPFx context type (WebPart, ApplicationCustomizer, etc.)
+ * @internal
+ */
+function getThemeProvider(spfxContext) {
+    var ctx = spfxContext;
+    if (!ctx.serviceScope) {
+        throw new Error('SPFx context does not have serviceScope');
+    }
+    // Consume ThemeProvider from service scope
+    // ServiceScope.consume() is type-safe with ServiceKey<T>
+    return ctx.serviceScope.consume(ThemeProvider.serviceKey);
+}
+/**
+ * Hook to subscribe to SPFx theme changes
+ * Automatically updates the provided setter when theme changes
+ *
+ * @param spfxContext - SPFx context object
+ * @param setTheme - Setter function to update theme state
+ * @internal
+ */
+export function useThemeSubscription(spfxContext, setTheme) {
+    useEffect(function () {
+        var themeProvider = getThemeProvider(spfxContext);
+        // Get initial theme
+        var initialTheme = themeProvider.tryGetTheme();
+        if (initialTheme) {
+            setTheme(initialTheme);
+        }
+        // Create event handler
+        var handler = function (args) {
+            setTheme(args.theme);
+        };
+        // Create observer object for SPFx event system
+        var observer = {
+            instanceId: 'theme-subscription',
+            componentId: 'theme-subscription',
+            isDisposed: false,
+            dispose: function () {
+                // Cleanup handled in useEffect return
+            },
+            update: handler,
+        };
+        // Subscribe to theme changes
+        themeProvider.themeChangedEvent.add(observer, handler);
+        // Cleanup on unmount
+        return function () {
+            observer.isDisposed = true;
+            themeProvider.themeChangedEvent.remove(observer, handler);
+        };
+    }, [spfxContext, setTheme]);
+}
+//# sourceMappingURL=theme-subscription.internal.js.map

package/lib/utils/theme-subscription.internal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"theme-subscription.internal.js","sourceRoot":"","sources":["../../src/utils/theme-subscription.internal.ts"],"names":[],"mappings":"AAAA,wBAAwB;AACxB,kDAAkD;AAElD,OAAO,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAElC,OAAO,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAG7D;;;;GAIG;AACH,SAAS,gBAAgB,CAAC,WAAoB;IAC5C,IAAM,GAAG,GAAG,WAEX,CAAC;IAEF,IAAI,CAAC,GAAG,CAAC,YAAY,EAAE,CAAC;QACtB,MAAM,IAAI,KAAK,CAAC,yCAAyC,CAAC,CAAC;IAC7D,CAAC;IAED,2CAA2C;IAC3C,yDAAyD;IACzD,OAAO,GAAG,CAAC,YAAY,CAAC,OAAO,CAAC,aAAa,CAAC,UAAU,CAAC,CAAC;AAC5D,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,oBAAoB,CAClC,WAAoB,EACpB,QAAqD;IAErD,SAAS,CAAC;QACR,IAAM,aAAa,GAAG,gBAAgB,CAAC,WAAW,CAAC,CAAC;QAEpD,oBAAoB;QACpB,IAAM,YAAY,GAAG,aAAa,CAAC,WAAW,EAAE,CAAC;QACjD,IAAI,YAAY,EAAE,CAAC;YACjB,QAAQ,CAAC,YAAY,CAAC,CAAC;QACzB,CAAC;QAED,uBAAuB;QACvB,IAAM,OAAO,GAAG,UAAC,IAAgC;YAC/C,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACvB,CAAC,CAAC;QAEF,+CAA+C;QAC/C,IAAM,QAAQ,GAAG;YACf,UAAU,EAAE,oBAAoB;YAChC,WAAW,EAAE,oBAAoB;YACjC,UAAU,EAAE,KAAK;YACjB,OAAO,EAAE;gBACP,sCAAsC;YACxC,CAAC;YACD,MAAM,EAAE,OAAO;SAChB,CAAC;QAEF,6BAA6B;QAC7B,aAAa,CAAC,iBAAiB,CAAC,GAAG,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;QAEvD,qBAAqB;QACrB,OAAO;YACL,QAAQ,CAAC,UAAU,GAAG,IAAI,CAAC;YAC3B,aAAa,CAAC,iBAAiB,CAAC,MAAM,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;QAC5D,CAAC,CAAC;IACJ,CAAC,EAAE,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC,CAAC;AAC9B,CAAC"}

package/lib/utils/type-guards.internal.d.ts

@@ -0,0 +1,35 @@
+import type { BaseClientSideWebPart } from '@microsoft/sp-webpart-base';
+import type { BaseApplicationCustomizer } from '@microsoft/sp-application-base';
+import type { BaseListViewCommandSet, BaseFieldCustomizer } from '@microsoft/sp-listview-extensibility';
+import type { SPFxComponent, HostKind } from '../core/types';
+/**
+ * Type guard: Check if instance is a WebPart
+ * Uses duck typing - checks for WebPart-specific properties
+ * @internal
+ */
+export declare function isWebPart<TProps extends {} = {}>(instance: unknown): instance is BaseClientSideWebPart<TProps>;
+/**
+ * Type guard: Check if instance is an ApplicationCustomizer
+ * Uses duck typing - checks for ApplicationCustomizer-specific properties
+ * @internal
+ */
+export declare function isApplicationCustomizer<TProps extends {} = {}>(instance: unknown): instance is BaseApplicationCustomizer<TProps>;
+/**
+ * Type guard: Check if instance is a ListViewCommandSet
+ * Uses duck typing - checks for CommandSet-specific properties
+ * @internal
+ */
+export declare function isListViewCommandSet<TProps extends {} = {}>(instance: unknown): instance is BaseListViewCommandSet<TProps>;
+/**
+ * Type guard: Check if instance is a FieldCustomizer
+ * Uses duck typing - checks for FieldCustomizer-specific properties
+ * @internal
+ */
+export declare function isFieldCustomizer<TProps extends {} = {}>(instance: unknown): instance is BaseFieldCustomizer<TProps>;
+/**
+ * Detect the kind of SPFx component from an instance
+ * Throws if unable to detect
+ * @internal
+ */
+export declare function detectComponentKind<TProps extends {} = {}>(instance: SPFxComponent<TProps>): HostKind;
+//# sourceMappingURL=type-guards.internal.d.ts.map

package/lib/utils/type-guards.internal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"type-guards.internal.d.ts","sourceRoot":"","sources":["../../src/utils/type-guards.internal.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AACxE,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,gCAAgC,CAAC;AAChF,OAAO,KAAK,EAAE,sBAAsB,EAAE,mBAAmB,EAAE,MAAM,sCAAsC,CAAC;AACxG,OAAO,KAAK,EACV,aAAa,EACb,QAAQ,EACT,MAAM,eAAe,CAAC;AAEvB;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,MAAM,SAAS,EAAE,GAAG,EAAE,EAC9C,QAAQ,EAAE,OAAO,GAChB,QAAQ,IAAI,qBAAqB,CAAC,MAAM,CAAC,CAa3C;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,SAAS,EAAE,GAAG,EAAE,EAC5D,QAAQ,EAAE,OAAO,GAChB,QAAQ,IAAI,yBAAyB,CAAC,MAAM,CAAC,CAgB/C;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,SAAS,EAAE,GAAG,EAAE,EACzD,QAAQ,EAAE,OAAO,GAChB,QAAQ,IAAI,sBAAsB,CAAC,MAAM,CAAC,CAa5C;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,SAAS,EAAE,GAAG,EAAE,EACtD,QAAQ,EAAE,OAAO,GAChB,QAAQ,IAAI,mBAAmB,CAAC,MAAM,CAAC,CAiBzC;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,SAAS,EAAE,GAAG,EAAE,EACxD,QAAQ,EAAE,aAAa,CAAC,MAAM,CAAC,GAC9B,QAAQ,CAUV"}

package/lib/utils/type-guards.internal.js

@@ -0,0 +1,88 @@
+// type-guards.ts
+// Type guards for SPFx component detection using structural typing (duck typing)
+/**
+ * Type guard: Check if instance is a WebPart
+ * Uses duck typing - checks for WebPart-specific properties
+ * @internal
+ */
+export function isWebPart(instance) {
+    if (!instance || typeof instance !== 'object')
+        return false;
+    var obj = instance;
+    return ('displayMode' in obj &&
+        'domElement' in obj &&
+        'render' in obj &&
+        typeof obj.render === 'function' &&
+        'context' in obj &&
+        'properties' in obj);
+}
+/**
+ * Type guard: Check if instance is an ApplicationCustomizer
+ * Uses duck typing - checks for ApplicationCustomizer-specific properties
+ * @internal
+ */
+export function isApplicationCustomizer(instance) {
+    if (!instance || typeof instance !== 'object')
+        return false;
+    var obj = instance;
+    if (!('context' in obj) || !obj.context || typeof obj.context !== 'object') {
+        return false;
+    }
+    var context = obj.context;
+    return ('placeholderProvider' in context &&
+        'properties' in obj &&
+        !('displayMode' in obj) // Not a WebPart
+    );
+}
+/**
+ * Type guard: Check if instance is a ListViewCommandSet
+ * Uses duck typing - checks for CommandSet-specific properties
+ * @internal
+ */
+export function isListViewCommandSet(instance) {
+    if (!instance || typeof instance !== 'object')
+        return false;
+    var obj = instance;
+    return ('onExecute' in obj &&
+        typeof obj.onExecute === 'function' &&
+        'tryGetCommand' in obj &&
+        typeof obj.tryGetCommand === 'function' &&
+        'context' in obj &&
+        'properties' in obj);
+}
+/**
+ * Type guard: Check if instance is a FieldCustomizer
+ * Uses duck typing - checks for FieldCustomizer-specific properties
+ * @internal
+ */
+export function isFieldCustomizer(instance) {
+    if (!instance || typeof instance !== 'object')
+        return false;
+    var obj = instance;
+    if (!('context' in obj) || !obj.context || typeof obj.context !== 'object') {
+        return false;
+    }
+    var context = obj.context;
+    return ('field' in context &&
+        'onRenderCell' in obj &&
+        typeof obj.onRenderCell === 'function' &&
+        'properties' in obj);
+}
+/**
+ * Detect the kind of SPFx component from an instance
+ * Throws if unable to detect
+ * @internal
+ */
+export function detectComponentKind(instance) {
+    if (isWebPart(instance))
+        return 'WebPart';
+    if (isApplicationCustomizer(instance))
+        return 'AppCustomizer';
+    if (isListViewCommandSet(instance))
+        return 'CommandSet';
+    if (isFieldCustomizer(instance))
+        return 'FieldCustomizer';
+    throw new Error('[SPFxProvider] Unable to detect SPFx component type. ' +
+        'Instance must be a WebPart, ApplicationCustomizer, CommandSet, or FieldCustomizer.');
+}
+//# sourceMappingURL=type-guards.internal.js.map

package/lib/utils/type-guards.internal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"type-guards.internal.js","sourceRoot":"","sources":["../../src/utils/type-guards.internal.ts"],"names":[],"mappings":"AAAA,iBAAiB;AACjB,iFAAiF;AAUjF;;;;GAIG;AACH,MAAM,UAAU,SAAS,CACvB,QAAiB;IAEjB,IAAI,CAAC,QAAQ,IAAI,OAAO,QAAQ,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAE5D,IAAM,GAAG,GAAG,QAAmC,CAAC;IAEhD,OAAO,CACL,aAAa,IAAI,GAAG;QACpB,YAAY,IAAI,GAAG;QACnB,QAAQ,IAAI,GAAG;QACf,OAAO,GAAG,CAAC,MAAM,KAAK,UAAU;QAChC,SAAS,IAAI,GAAG;QAChB,YAAY,IAAI,GAAG,CACpB,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,uBAAuB,CACrC,QAAiB;IAEjB,IAAI,CAAC,QAAQ,IAAI,OAAO,QAAQ,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAE5D,IAAM,GAAG,GAAG,QAAmC,CAAC;IAEhD,IAAI,CAAC,CAAC,SAAS,IAAI,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO,IAAI,OAAO,GAAG,CAAC,OAAO,KAAK,QAAQ,EAAE,CAAC;QAC3E,OAAO,KAAK,CAAC;IACf,CAAC;IAED,IAAM,OAAO,GAAG,GAAG,CAAC,OAAkC,CAAC;IAEvD,OAAO,CACL,qBAAqB,IAAI,OAAO;QAChC,YAAY,IAAI,GAAG;QACnB,CAAC,CAAC,aAAa,IAAI,GAAG,CAAC,CAAC,gBAAgB;KACzC,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAClC,QAAiB;IAEjB,IAAI,CAAC,QAAQ,IAAI,OAAO,QAAQ,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAE5D,IAAM,GAAG,GAAG,QAAmC,CAAC;IAEhD,OAAO,CACL,WAAW,IAAI,GAAG;QAClB,OAAO,GAAG,CAAC,SAAS,KAAK,UAAU;QACnC,eAAe,IAAI,GAAG;QACtB,OAAO,GAAG,CAAC,aAAa,KAAK,UAAU;QACvC,SAAS,IAAI,GAAG;QAChB,YAAY,IAAI,GAAG,CACpB,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAC/B,QAAiB;IAEjB,IAAI,CAAC,QAAQ,IAAI,OAAO,QAAQ,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAE5D,IAAM,GAAG,GAAG,QAAmC,CAAC;IAEhD,IAAI,CAAC,CAAC,SAAS,IAAI,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO,IAAI,OAAO,GAAG,CAAC,OAAO,KAAK,QAAQ,EAAE,CAAC;QAC3E,OAAO,KAAK,CAAC;IACf,CAAC;IAED,IAAM,OAAO,GAAG,GAAG,CAAC,OAAkC,CAAC;IAEvD,OAAO,CACL,OAAO,IAAI,OAAO;QAClB,cAAc,IAAI,GAAG;QACrB,OAAO,GAAG,CAAC,YAAY,KAAK,UAAU;QACtC,YAAY,IAAI,GAAG,CACpB,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CACjC,QAA+B;IAE/B,IAAI,SAAS,CAAC,QAAQ,CAAC;QAAE,OAAO,SAAS,CAAC;IAC1C,IAAI,uBAAuB,CAAC,QAAQ,CAAC;QAAE,OAAO,eAAe,CAAC;IAC9D,IAAI,oBAAoB,CAAC,QAAQ,CAAC;QAAE,OAAO,YAAY,CAAC;IACxD,IAAI,iBAAiB,CAAC,QAAQ,CAAC;QAAE,OAAO,iBAAiB,CAAC;IAE1D,MAAM,IAAI,KAAK,CACb,uDAAuD;QACvD,oFAAoF,CACrF,CAAC;AACJ,CAAC"}