@apvee/spfx-react-toolkit 1.0.0

package/lib/hooks/useSPFxAadHttpClient.js

@@ -0,0 +1,299 @@
+// useSPFxAadHttpClient.ts
+// Hook to access Azure AD-secured APIs with state management
+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 } from 'react';
+import { useSPFxContext } from './useSPFxContext';
+/**
+ * Hook to access Azure AD-secured APIs with built-in state management
+ *
+ * Provides native AadHttpClient for authenticated Azure AD-secured API access.
+ * Offers two usage patterns:
+ *
+ * 1. **invoke()** - Automatic state management (loading + error tracking)
+ * 2. **client** - Direct access for full control
+ *
+ * For type safety, import SPFx types:
+ * ```typescript
+ * import type { AadHttpClient } from '@microsoft/sp-http';
+ * ```
+ *
+ * Requirements:
+ * - Add permissions to package-solution.json webApiPermissionRequests
+ * - Admin must grant permissions in SharePoint Admin Center
+ * - AadHttpClientFactory available in SPFx context
+ *
+ * @param initialResourceUrl - Azure AD resource URL or App ID (optional, can be set later)
+ *
+ * @example Using invoke with state management
+ * ```tsx
+ * function OrdersList() {
+ *   const { invoke, isLoading, error, clearError, resourceUrl } = useSPFxAadHttpClient(
+ *     'https://api.contoso.com'
+ *   );
+ *   const [orders, setOrders] = useState<Order[]>([]);
+ *
+ *   const loadOrders = () => {
+ *     invoke(client =>
+ *       client.get(
+ *         `${resourceUrl}/api/orders`,
+ *         AadHttpClient.configurations.v1
+ *       ).then(res => res.json())
+ *     ).then(data => setOrders(data));
+ *   };
+ *
+ *   useEffect(() => { loadOrders(); }, []);
+ *
+ *   if (isLoading) return <Spinner />;
+ *   if (error) return (
+ *     <MessageBar messageBarType={MessageBarType.error}>
+ *       {error.message}
+ *       <Link onClick={() => { clearError(); loadOrders(); }}>Retry</Link>
+ *     </MessageBar>
+ *   );
+ *
+ *   return <ul>{orders.map(o => <li key={o.id}>{o.total}</li>)}</ul>;
+ * }
+ * ```
+ *
+ * @example Using client directly for advanced control
+ * ```tsx
+ * import type { AadHttpClient } from '@microsoft/sp-http';
+ *
+ * function ProductsManager() {
+ *   const { client, resourceUrl } = useSPFxAadHttpClient('https://api.contoso.com');
+ *   const [products, setProducts] = useState([]);
+ *   const [loading, setLoading] = useState(false);
+ *
+ *   if (!client) return <Spinner label="Initializing AAD client..." />;
+ *
+ *   const loadProducts = async () => {
+ *     setLoading(true);
+ *     try {
+ *       const response = await client.get(
+ *         `${resourceUrl}/api/products`,
+ *         AadHttpClient.configurations.v1
+ *       );
+ *       const data = await response.json();
+ *       setProducts(data);
+ *     } catch (err) {
+ *       console.error(err);
+ *     } finally {
+ *       setLoading(false);
+ *     }
+ *   };
+ *
+ *   return (
+ *     <>
+ *       <button onClick={loadProducts} disabled={loading}>Load</button>
+ *       {loading && <Spinner />}
+ *       <DetailsList items={products} />
+ *     </>
+ *   );
+ * }
+ * ```
+ *
+ * @example CRUD operations with invoke
+ * ```tsx
+ * function ItemsManager() {
+ *   const { invoke, isLoading, error, resourceUrl } = useSPFxAadHttpClient(
+ *     'https://api.contoso.com'
+ *   );
+ *   const [items, setItems] = useState([]);
+ *
+ *   const loadItems = () => {
+ *     invoke(client =>
+ *       client.get(
+ *         `${resourceUrl}/api/items`,
+ *         AadHttpClient.configurations.v1
+ *       ).then(res => res.json())
+ *     ).then(data => setItems(data));
+ *   };
+ *
+ *   const createItem = (item: any) => {
+ *     invoke(client =>
+ *       client.post(
+ *         `${resourceUrl}/api/items`,
+ *         AadHttpClient.configurations.v1,
+ *         { body: JSON.stringify(item) }
+ *       ).then(res => res.json())
+ *     ).then(loadItems);
+ *   };
+ *
+ *   const updateItem = (id: string, changes: any) => {
+ *     invoke(client =>
+ *       client.post(
+ *         `${resourceUrl}/api/items/${id}`,
+ *         AadHttpClient.configurations.v1,
+ *         {
+ *           headers: { 'X-HTTP-Method': 'PATCH' },
+ *           body: JSON.stringify(changes)
+ *         }
+ *       )
+ *     ).then(loadItems);
+ *   };
+ *
+ *   const deleteItem = (id: string) => {
+ *     invoke(client =>
+ *       client.post(
+ *         `${resourceUrl}/api/items/${id}`,
+ *         AadHttpClient.configurations.v1,
+ *         { headers: { 'X-HTTP-Method': 'DELETE' } }
+ *       )
+ *     ).then(loadItems);
+ *   };
+ *
+ *   return (
+ *     <ItemsUI
+ *       items={items}
+ *       loading={isLoading}
+ *       error={error}
+ *       onCreate={createItem}
+ *       onUpdate={updateItem}
+ *       onDelete={deleteItem}
+ *     />
+ *   );
+ * }
+ * ```
+ *
+ * @example Lazy initialization with setResourceUrl
+ * ```tsx
+ * function DynamicApi() {
+ *   const { invoke, setResourceUrl, resourceUrl, clearError } = useSPFxAadHttpClient();
+ *   const [data, setData] = useState(null);
+ *
+ *   const loadFromApi = async (apiUrl: string) => {
+ *     clearError();
+ *     setResourceUrl(apiUrl);
+ *
+ *     // Wait for client initialization, then fetch
+ *     setTimeout(() => {
+ *       invoke(client =>
+ *         client.get(
+ *           `${apiUrl}/api/data`,
+ *           AadHttpClient.configurations.v1
+ *         ).then(res => res.json())
+ *       ).then(setData);
+ *     }, 100);
+ *   };
+ *
+ *   return (
+ *     <>
+ *       <button onClick={() => loadFromApi('https://api1.contoso.com')}>API 1</button>
+ *       <button onClick={() => loadFromApi('https://api2.contoso.com')}>API 2</button>
+ *       {data && <pre>{JSON.stringify(data, null, 2)}</pre>}
+ *     </>
+ *   );
+ * }
+ * ```
+ */
+export function useSPFxAadHttpClient(initialResourceUrl) {
+    var _this = this;
+    var spfxContext = useSPFxContext().spfxContext;
+    // Extract factory from context
+    var ctx = spfxContext;
+    // State management
+    var _a = useState(initialResourceUrl), resourceUrl = _a[0], setResourceUrl = _a[1];
+    var _b = useState(undefined), client = _b[0], setClient = _b[1];
+    var _c = useState(false), isLoading = _c[0], setIsLoading = _c[1];
+    var _d = useState(undefined), error = _d[0], setError = _d[1];
+    // Initialize client when resourceUrl changes
+    useEffect(function () {
+        // Reset client immediately when resourceUrl changes
+        setClient(undefined);
+        if (!resourceUrl) {
+            return;
+        }
+        if (!ctx.aadHttpClientFactory) {
+            console.warn('AadHttpClientFactory not available in SPFx context');
+            return;
+        }
+        // Get AadHttpClient for the specified resource
+        ctx.aadHttpClientFactory
+            .getClient(resourceUrl)
+            .then(function (aadClient) {
+            setClient(aadClient);
+        })
+            .catch(function (err) {
+            console.error('Failed to initialize AadHttpClient:', err);
+        });
+    }, [resourceUrl, ctx.aadHttpClientFactory]);
+    // Invoke with automatic state management
+    var invoke = useCallback(function (fn) { return __awaiter(_this, void 0, void 0, function () {
+        var result, err_1, error_1;
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0:
+                    if (!client) {
+                        throw new Error('AadHttpClient not initialized. Set resourceUrl and wait for client initialization.');
+                    }
+                    setIsLoading(true);
+                    setError(undefined);
+                    _a.label = 1;
+                case 1:
+                    _a.trys.push([1, 3, 4, 5]);
+                    return [4 /*yield*/, fn(client)];
+                case 2:
+                    result = _a.sent();
+                    return [2 /*return*/, result];
+                case 3:
+                    err_1 = _a.sent();
+                    error_1 = err_1 instanceof Error ? err_1 : new Error(String(err_1));
+                    setError(error_1);
+                    throw error_1;
+                case 4:
+                    setIsLoading(false);
+                    return [7 /*endfinally*/];
+                case 5: return [2 /*return*/];
+            }
+        });
+    }); }, [client]);
+    // Clear error helper
+    var clearError = useCallback(function () {
+        setError(undefined);
+    }, []);
+    return {
+        client: client,
+        invoke: invoke,
+        isLoading: isLoading,
+        error: error,
+        clearError: clearError,
+        setResourceUrl: setResourceUrl,
+        resourceUrl: resourceUrl,
+    };
+}
+//# sourceMappingURL=useSPFxAadHttpClient.js.map

package/lib/hooks/useSPFxAadHttpClient.js.map

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

package/lib/hooks/useSPFxContainerInfo.d.ts

@@ -0,0 +1,41 @@
+import type { ContainerSize } from '../core/types';
+/**
+ * Return type for useSPFxContainerInfo hook
+ */
+export interface SPFxContainerInfo {
+    /** Container DOM element */
+    readonly element: HTMLElement | undefined;
+    /** Container size (width/height in pixels) */
+    readonly size: ContainerSize | undefined;
+}
+/**
+ * Hook to access container element and its size
+ *
+ * Automatically tracks container size changes using ResizeObserver
+ * Updates in real-time when container is resized
+ *
+ * Useful for:
+ * - Responsive layouts
+ * - Dynamic content sizing
+ * - Breakpoint calculations
+ * - Canvas/chart dimensions
+ *
+ * @returns Container element and size
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { element, size } = useSPFxContainerInfo();
+ *
+ *   return (
+ *     <div>
+ *       {size && (
+ *         <p>Container: {size.width}px × {size.height}px</p>
+ *       )}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare function useSPFxContainerInfo(): SPFxContainerInfo;
+//# sourceMappingURL=useSPFxContainerInfo.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useSPFxContainerInfo.d.ts","sourceRoot":"","sources":["../../src/hooks/useSPFxContainerInfo.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAEnD;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,4BAA4B;IAC5B,QAAQ,CAAC,OAAO,EAAE,WAAW,GAAG,SAAS,CAAC;IAE1C,8CAA8C;IAC9C,QAAQ,CAAC,IAAI,EAAE,aAAa,GAAG,SAAS,CAAC;CAC1C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,oBAAoB,IAAI,iBAAiB,CAaxD"}

package/lib/hooks/useSPFxContainerInfo.js

@@ -0,0 +1,47 @@
+// useSPFxContainerInfo.ts
+// Hook to access container element and size
+import { useAtomValue, useSetAtom } from 'jotai';
+import { spfxAtoms } from '../core/atoms.internal';
+import { useResizeObserver } from '../utils/resize-observer.internal';
+/**
+ * Hook to access container element and its size
+ *
+ * Automatically tracks container size changes using ResizeObserver
+ * Updates in real-time when container is resized
+ *
+ * Useful for:
+ * - Responsive layouts
+ * - Dynamic content sizing
+ * - Breakpoint calculations
+ * - Canvas/chart dimensions
+ *
+ * @returns Container element and size
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { element, size } = useSPFxContainerInfo();
+ *
+ *   return (
+ *     <div>
+ *       {size && (
+ *         <p>Container: {size.width}px × {size.height}px</p>
+ *       )}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export function useSPFxContainerInfo() {
+    // Read container element and size directly from atoms
+    var element = useAtomValue(spfxAtoms.containerEl);
+    var size = useAtomValue(spfxAtoms.containerSize);
+    // Setup ResizeObserver with atom setter
+    var setSize = useSetAtom(spfxAtoms.containerSize);
+    useResizeObserver(element, setSize);
+    return {
+        element: element,
+        size: size,
+    };
+}
+//# sourceMappingURL=useSPFxContainerInfo.js.map

package/lib/hooks/useSPFxContainerInfo.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useSPFxContainerInfo.js","sourceRoot":"","sources":["../../src/hooks/useSPFxContainerInfo.ts"],"names":[],"mappings":"AAAA,0BAA0B;AAC1B,4CAA4C;AAE5C,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,OAAO,CAAC;AACjD,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,OAAO,EAAE,iBAAiB,EAAE,MAAM,mCAAmC,CAAC;AActE;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,UAAU,oBAAoB;IAClC,sDAAsD;IACtD,IAAM,OAAO,GAAG,YAAY,CAAC,SAAS,CAAC,WAAW,CAAC,CAAC;IACpD,IAAM,IAAI,GAAG,YAAY,CAAC,SAAS,CAAC,aAAa,CAAC,CAAC;IAEnD,wCAAwC;IACxC,IAAM,OAAO,GAAG,UAAU,CAAC,SAAS,CAAC,aAAa,CAAC,CAAC;IACpD,iBAAiB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IAEpC,OAAO;QACL,OAAO,SAAA;QACP,IAAI,MAAA;KACL,CAAC;AACJ,CAAC"}

package/lib/hooks/useSPFxContainerSize.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Container size categories (Fluent UI 9 aligned)
+ *
+ * Based on official Fluent UI 9 responsive breakpoints:
+ * @see https://developer.microsoft.com/en-us/fluentui#/styles/web/responsive
+ *
+ * - small:    320-479px   (Mobile portrait)
+ * - medium:   480-639px   (Mobile landscape, small tablets)
+ * - large:    640-1023px  (Tablets, single column)
+ * - xLarge:   1024-1365px (Laptop, desktop standard)
+ * - xxLarge:  1366-1919px (Large desktop, wide screen)
+ * - xxxLarge: >= 1920px   (4K, ultra-wide, multi-column)
+ */
+export type SPFxContainerSize = 'small' | 'medium' | 'large' | 'xLarge' | 'xxLarge' | 'xxxLarge';
+/**
+ * Return type for useSPFxContainerSize hook
+ */
+export interface SPFxContainerSizeInfo {
+    /** Container size category (Fluent UI 9 aligned) */
+    readonly size: SPFxContainerSize;
+    /** Is small container (320-479px) - mobile portrait */
+    readonly isSmall: boolean;
+    /** Is medium container (480-639px) - mobile landscape, small tablets */
+    readonly isMedium: boolean;
+    /** Is large container (640-1023px) - tablets, single column */
+    readonly isLarge: boolean;
+    /** Is extra large container (1024-1365px) - laptop, desktop standard */
+    readonly isXLarge: boolean;
+    /** Is extra extra large container (1366-1919px) - large desktop, wide screen */
+    readonly isXXLarge: boolean;
+    /** Is extra extra extra large container (>= 1920px) - 4K, ultra-wide, multi-column */
+    readonly isXXXLarge: boolean;
+    /** Actual container width in pixels */
+    readonly width: number;
+    /** Actual container height in pixels */
+    readonly height: number;
+}
+/**
+ * Hook to get container size with Fluent UI 9 aligned breakpoints
+ *
+ * Automatically tracks container size changes and categorizes into
+ * Fluent UI 9 compatible size categories.
+ *
+ * Breakpoints (aligned with Fluent UI 9):
+ * - small:    320-479px   (mobile portrait)
+ * - medium:   480-639px   (mobile landscape, small tablets)
+ * - large:    640-1023px  (tablets, single column)
+ * - xLarge:   1024-1365px (laptop, desktop standard)
+ * - xxLarge:  1366-1919px (large desktop, wide screen)
+ * - xxxLarge: >= 1920px   (4K, ultra-wide, multi-column)
+ *
+ * Useful for:
+ * - Responsive layouts based on actual container space
+ * - Adaptive UI that works in sidebars, columns, or full width
+ * - Fluent UI 9 compatible responsive design
+ * - Making layout decisions based on available space
+ *
+ * @returns Container size information and helpers
+ *
+ * @example
+ * ```tsx
+ * function MyWebPart() {
+ *   const { size, isSmall, isXXXLarge, width } = useSPFxContainerSize();
+ *
+ *   // Decision based on size
+ *   if (size === 'small') {
+ *     return <CompactMobileView />;
+ *   }
+ *
+ *   if (size === 'medium' || size === 'large') {
+ *     return <TabletView />;
+ *   }
+ *
+ *   if (size === 'xxxLarge') {
+ *     return <UltraWideView columns={6} />;  // 4K/ultra-wide
+ *   }
+ *
+ *   return <DesktopView columns={size === 'xxLarge' ? 4 : 3} />;
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * function ResponsiveComponent() {
+ *   const { isSmall, isMedium, isLarge, isXLarge, isXXLarge, isXXXLarge } = useSPFxContainerSize();
+ *
+ *   return (
+ *     <div>
+ *       {isSmall && <MobileLayout />}
+ *       {(isMedium || isLarge) && <TabletLayout />}
+ *       {isXLarge && <DesktopLayout columns={3} />}
+ *       {isXXLarge && <DesktopLayout columns={4} />}
+ *       {isXXXLarge && <UltraWideLayout columns={6} />}
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * function AdaptiveCard() {
+ *   const { size, width, height } = useSPFxContainerSize();
+ *
+ *   return (
+ *     <div>
+ *       <p>Container: {width}px × {height}px</p>
+ *       <p>Size category: {size}</p>
+ *       {size === 'small' && <StackedLayout />}
+ *       {size === 'medium' && <TwoColumnLayout />}
+ *       {size === 'large' && <ThreeColumnLayout />}
+ *       {(size === 'xLarge' || size === 'xxLarge') && <MultiColumnLayout />}
+ *       {size === 'xxxLarge' && <UltraWideLayout columns={6} />}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare function useSPFxContainerSize(): SPFxContainerSizeInfo;
+//# sourceMappingURL=useSPFxContainerSize.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useSPFxContainerSize.d.ts","sourceRoot":"","sources":["../../src/hooks/useSPFxContainerSize.ts"],"names":[],"mappings":"AAMA;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,iBAAiB,GACzB,OAAO,GACP,QAAQ,GACR,OAAO,GACP,QAAQ,GACR,SAAS,GACT,UAAU,CAAC;AAEf;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,oDAAoD;IACpD,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;IAEjC,uDAAuD;IACvD,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAE1B,wEAAwE;IACxE,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAE3B,+DAA+D;IAC/D,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAE1B,wEAAwE;IACxE,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAE3B,gFAAgF;IAChF,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAE5B,sFAAsF;IACtF,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAE7B,uCAAuC;IACvC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAEvB,wCAAwC;IACxC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAiDD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+EG;AACH,wBAAgB,oBAAoB,IAAI,qBAAqB,CAoB5D"}

package/lib/hooks/useSPFxContainerSize.js

@@ -0,0 +1,150 @@
+// useSPFxContainerSize.ts
+// Hook for container size detection with SharePoint-aligned breakpoints
+import { useMemo } from 'react';
+import { useSPFxContainerInfo } from './useSPFxContainerInfo';
+/**
+ * Fluent UI 9 container size breakpoints
+ *
+ * Based on official Fluent UI 9 responsive breakpoints:
+ * - Small:    320px  (mobile portrait)
+ * - Medium:   480px  (mobile landscape, small tablets)
+ * - Large:    640px  (tablets, single column)
+ * - XLarge:   1024px (laptop, desktop standard)
+ * - XXLarge:  1366px (large desktop, wide screen)
+ * - XXXLarge: 1920px (4K, ultra-wide, multi-column)
+ *
+ * @see https://developer.microsoft.com/en-us/fluentui#/styles/web/responsive
+ */
+var CONTAINER_SIZE_BREAKPOINTS = {
+    small: 480, // Fluent UI 9: Small → Medium (320-479 → 480+)
+    medium: 640, // Fluent UI 9: Medium → Large (480-639 → 640+)
+    large: 1024, // Fluent UI 9: Large → XLarge (640-1023 → 1024+)
+    xLarge: 1366, // Fluent UI 9: XLarge → XXLarge (1024-1365 → 1366+)
+    xxLarge: 1920, // Fluent UI 9: XXLarge → XXXLarge (1366-1919 → 1920+)
+    xxxLarge: Infinity, // No upper bound for XXXLarge (>= 1920px)
+};
+/**
+ * Get container size category from width
+ *
+ * @param width - Container width in pixels
+ * @returns Container size category
+ */
+function getContainerSize(width) {
+    if (width < CONTAINER_SIZE_BREAKPOINTS.small) {
+        return 'small'; // < 480px
+    }
+    if (width < CONTAINER_SIZE_BREAKPOINTS.medium) {
+        return 'medium'; // 480-639px
+    }
+    if (width < CONTAINER_SIZE_BREAKPOINTS.large) {
+        return 'large'; // 640-1023px
+    }
+    if (width < CONTAINER_SIZE_BREAKPOINTS.xLarge) {
+        return 'xLarge'; // 1024-1365px
+    }
+    if (width < CONTAINER_SIZE_BREAKPOINTS.xxLarge) {
+        return 'xxLarge'; // 1366-1919px
+    }
+    return 'xxxLarge'; // >= 1920px
+}
+/**
+ * Hook to get container size with Fluent UI 9 aligned breakpoints
+ *
+ * Automatically tracks container size changes and categorizes into
+ * Fluent UI 9 compatible size categories.
+ *
+ * Breakpoints (aligned with Fluent UI 9):
+ * - small:    320-479px   (mobile portrait)
+ * - medium:   480-639px   (mobile landscape, small tablets)
+ * - large:    640-1023px  (tablets, single column)
+ * - xLarge:   1024-1365px (laptop, desktop standard)
+ * - xxLarge:  1366-1919px (large desktop, wide screen)
+ * - xxxLarge: >= 1920px   (4K, ultra-wide, multi-column)
+ *
+ * Useful for:
+ * - Responsive layouts based on actual container space
+ * - Adaptive UI that works in sidebars, columns, or full width
+ * - Fluent UI 9 compatible responsive design
+ * - Making layout decisions based on available space
+ *
+ * @returns Container size information and helpers
+ *
+ * @example
+ * ```tsx
+ * function MyWebPart() {
+ *   const { size, isSmall, isXXXLarge, width } = useSPFxContainerSize();
+ *
+ *   // Decision based on size
+ *   if (size === 'small') {
+ *     return <CompactMobileView />;
+ *   }
+ *
+ *   if (size === 'medium' || size === 'large') {
+ *     return <TabletView />;
+ *   }
+ *
+ *   if (size === 'xxxLarge') {
+ *     return <UltraWideView columns={6} />;  // 4K/ultra-wide
+ *   }
+ *
+ *   return <DesktopView columns={size === 'xxLarge' ? 4 : 3} />;
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * function ResponsiveComponent() {
+ *   const { isSmall, isMedium, isLarge, isXLarge, isXXLarge, isXXXLarge } = useSPFxContainerSize();
+ *
+ *   return (
+ *     <div>
+ *       {isSmall && <MobileLayout />}
+ *       {(isMedium || isLarge) && <TabletLayout />}
+ *       {isXLarge && <DesktopLayout columns={3} />}
+ *       {isXXLarge && <DesktopLayout columns={4} />}
+ *       {isXXXLarge && <UltraWideLayout columns={6} />}
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * function AdaptiveCard() {
+ *   const { size, width, height } = useSPFxContainerSize();
+ *
+ *   return (
+ *     <div>
+ *       <p>Container: {width}px × {height}px</p>
+ *       <p>Size category: {size}</p>
+ *       {size === 'small' && <StackedLayout />}
+ *       {size === 'medium' && <TwoColumnLayout />}
+ *       {size === 'large' && <ThreeColumnLayout />}
+ *       {(size === 'xLarge' || size === 'xxLarge') && <MultiColumnLayout />}
+ *       {size === 'xxxLarge' && <UltraWideLayout columns={6} />}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export function useSPFxContainerSize() {
+    var containerSize = useSPFxContainerInfo().size;
+    return useMemo(function () {
+        var _a, _b;
+        var width = (_a = containerSize === null || containerSize === void 0 ? void 0 : containerSize.width) !== null && _a !== void 0 ? _a : 0;
+        var height = (_b = containerSize === null || containerSize === void 0 ? void 0 : containerSize.height) !== null && _b !== void 0 ? _b : 0;
+        var size = getContainerSize(width);
+        return {
+            size: size,
+            isSmall: size === 'small',
+            isMedium: size === 'medium',
+            isLarge: size === 'large',
+            isXLarge: size === 'xLarge',
+            isXXLarge: size === 'xxLarge',
+            isXXXLarge: size === 'xxxLarge',
+            width: width,
+            height: height,
+        };
+    }, [containerSize]);
+}
+//# sourceMappingURL=useSPFxContainerSize.js.map

package/lib/hooks/useSPFxContainerSize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useSPFxContainerSize.js","sourceRoot":"","sources":["../../src/hooks/useSPFxContainerSize.ts"],"names":[],"mappings":"AAAA,0BAA0B;AAC1B,wEAAwE;AAExE,OAAO,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC;AAChC,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAuD9D;;;;;;;;;;;;GAYG;AACH,IAAM,0BAA0B,GAAG;IACjC,KAAK,EAAE,GAAG,EAAM,+CAA+C;IAC/D,MAAM,EAAE,GAAG,EAAK,+CAA+C;IAC/D,KAAK,EAAE,IAAI,EAAK,iDAAiD;IACjE,MAAM,EAAE,IAAI,EAAI,oDAAoD;IACpE,OAAO,EAAE,IAAI,EAAG,sDAAsD;IACtE,QAAQ,EAAE,QAAQ,EAAE,0CAA0C;CACtD,CAAC;AAEX;;;;;GAKG;AACH,SAAS,gBAAgB,CAAC,KAAa;IACrC,IAAI,KAAK,GAAG,0BAA0B,CAAC,KAAK,EAAE,CAAC;QAC7C,OAAO,OAAO,CAAC,CAAK,UAAU;IAChC,CAAC;IACD,IAAI,KAAK,GAAG,0BAA0B,CAAC,MAAM,EAAE,CAAC;QAC9C,OAAO,QAAQ,CAAC,CAAI,YAAY;IAClC,CAAC;IACD,IAAI,KAAK,GAAG,0BAA0B,CAAC,KAAK,EAAE,CAAC;QAC7C,OAAO,OAAO,CAAC,CAAK,aAAa;IACnC,CAAC;IACD,IAAI,KAAK,GAAG,0BAA0B,CAAC,MAAM,EAAE,CAAC;QAC9C,OAAO,QAAQ,CAAC,CAAI,cAAc;IACpC,CAAC;IACD,IAAI,KAAK,GAAG,0BAA0B,CAAC,OAAO,EAAE,CAAC;QAC/C,OAAO,SAAS,CAAC,CAAG,cAAc;IACpC,CAAC;IACD,OAAO,UAAU,CAAC,CAAI,YAAY;AACpC,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+EG;AACH,MAAM,UAAU,oBAAoB;IAC1B,IAAM,aAAa,GAAK,oBAAoB,EAAE,KAA3B,CAA4B;IAEvD,OAAO,OAAO,CAAC;;QACb,IAAM,KAAK,GAAG,MAAA,aAAa,aAAb,aAAa,uBAAb,aAAa,CAAE,KAAK,mCAAI,CAAC,CAAC;QACxC,IAAM,MAAM,GAAG,MAAA,aAAa,aAAb,aAAa,uBAAb,aAAa,CAAE,MAAM,mCAAI,CAAC,CAAC;QAC1C,IAAM,IAAI,GAAG,gBAAgB,CAAC,KAAK,CAAC,CAAC;QAErC,OAAO;YACL,IAAI,MAAA;YACJ,OAAO,EAAE,IAAI,KAAK,OAAO;YACzB,QAAQ,EAAE,IAAI,KAAK,QAAQ;YAC3B,OAAO,EAAE,IAAI,KAAK,OAAO;YACzB,QAAQ,EAAE,IAAI,KAAK,QAAQ;YAC3B,SAAS,EAAE,IAAI,KAAK,SAAS;YAC7B,UAAU,EAAE,IAAI,KAAK,UAAU;YAC/B,KAAK,OAAA;YACL,MAAM,QAAA;SACP,CAAC;IACJ,CAAC,EAAE,CAAC,aAAa,CAAC,CAAC,CAAC;AACtB,CAAC"}