@apvee/spfx-react-toolkit 1.0.0

package/lib/hooks/useSPFxSPHttpClient.js

@@ -0,0 +1,287 @@
+// useSPFxSPHttpClient.ts
+// Hook to access SharePoint REST 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 SharePoint REST APIs with built-in state management
+ *
+ * Provides native SPHttpClient for authenticated SharePoint REST 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 { SPHttpClient } from '@microsoft/sp-http';
+ * ```
+ *
+ * Requirements:
+ * - SPHttpClient available in SPFx context
+ * - Appropriate SharePoint permissions for target APIs
+ *
+ * @param initialBaseUrl - Base URL for SharePoint site (optional, defaults to current site)
+ *
+ * @example Using invoke with state management
+ * ```tsx
+ * function WebInfo() {
+ *   const { invoke, isLoading, error, clearError, baseUrl } = useSPFxSPHttpClient();
+ *   const [webTitle, setWebTitle] = useState<string>('');
+ *
+ *   const loadWeb = () => {
+ *     invoke(client =>
+ *       client.get(
+ *         `${baseUrl}/_api/web?$select=Title`,
+ *         SPHttpClient.configurations.v1
+ *       ).then(res => res.json())
+ *     ).then(web => setWebTitle(web.Title));
+ *   };
+ *
+ *   useEffect(() => { loadWeb(); }, []);
+ *
+ *   if (isLoading) return <Spinner />;
+ *   if (error) return (
+ *     <MessageBar messageBarType={MessageBarType.error}>
+ *       {error.message}
+ *       <Link onClick={() => { clearError(); loadWeb(); }}>Retry</Link>
+ *     </MessageBar>
+ *   );
+ *
+ *   return <h1>{webTitle}</h1>;
+ * }
+ * ```
+ *
+ * @example Using client directly for advanced control
+ * ```tsx
+ * import type { SPHttpClient } from '@microsoft/sp-http';
+ *
+ * function ListItems() {
+ *   const { client, baseUrl } = useSPFxSPHttpClient();
+ *   const [items, setItems] = useState([]);
+ *   const [loading, setLoading] = useState(false);
+ *
+ *   if (!client) return <Spinner label="Initializing HTTP client..." />;
+ *
+ *   const loadItems = async () => {
+ *     setLoading(true);
+ *     try {
+ *       const response = await client.get(
+ *         `${baseUrl}/_api/web/lists/getbytitle('Tasks')/items`,
+ *         SPHttpClient.configurations.v1
+ *       );
+ *       const data = await response.json();
+ *       setItems(data.value);
+ *     } catch (err) {
+ *       console.error(err);
+ *     } finally {
+ *       setLoading(false);
+ *     }
+ *   };
+ *
+ *   return (
+ *     <>
+ *       <button onClick={loadItems} disabled={loading}>Load</button>
+ *       {loading && <Spinner />}
+ *       <DetailsList items={items} />
+ *     </>
+ *   );
+ * }
+ * ```
+ *
+ * @example CRUD operations with invoke
+ * ```tsx
+ * function TasksManager() {
+ *   const { invoke, isLoading, error, baseUrl } = useSPFxSPHttpClient();
+ *   const [tasks, setTasks] = useState([]);
+ *
+ *   const loadTasks = () => {
+ *     invoke(client =>
+ *       client.get(
+ *         `${baseUrl}/_api/web/lists/getbytitle('Tasks')/items`,
+ *         SPHttpClient.configurations.v1
+ *       ).then(res => res.json())
+ *     ).then(data => setTasks(data.value));
+ *   };
+ *
+ *   const createTask = (title: string) => {
+ *     invoke(client =>
+ *       client.post(
+ *         `${baseUrl}/_api/web/lists/getbytitle('Tasks')/items`,
+ *         SPHttpClient.configurations.v1,
+ *         { body: JSON.stringify({ Title: title }) }
+ *       ).then(res => res.json())
+ *     ).then(loadTasks);
+ *   };
+ *
+ *   const updateTask = (id: number, changes: any) => {
+ *     invoke(client =>
+ *       client.post(
+ *         `${baseUrl}/_api/web/lists/getbytitle('Tasks')/items(${id})`,
+ *         SPHttpClient.configurations.v1,
+ *         {
+ *           headers: { 'IF-MATCH': '*', 'X-HTTP-Method': 'MERGE' },
+ *           body: JSON.stringify(changes)
+ *         }
+ *       )
+ *     ).then(loadTasks);
+ *   };
+ *
+ *   const deleteTask = (id: number) => {
+ *     invoke(client =>
+ *       client.post(
+ *         `${baseUrl}/_api/web/lists/getbytitle('Tasks')/items(${id})`,
+ *         SPHttpClient.configurations.v1,
+ *         {
+ *           headers: { 'IF-MATCH': '*', 'X-HTTP-Method': 'DELETE' }
+ *         }
+ *       )
+ *     ).then(loadTasks);
+ *   };
+ *
+ *   return (
+ *     <TasksUI
+ *       tasks={tasks}
+ *       loading={isLoading}
+ *       error={error}
+ *       onCreate={createTask}
+ *       onUpdate={updateTask}
+ *       onDelete={deleteTask}
+ *     />
+ *   );
+ * }
+ * ```
+ *
+ * @example Cross-site queries
+ * ```tsx
+ * function MultiSiteData() {
+ *   const { invoke, setBaseUrl, baseUrl } = useSPFxSPHttpClient(
+ *     'https://contoso.sharepoint.com/sites/hr'
+ *   );
+ *
+ *   const switchToFinance = () => {
+ *     setBaseUrl('https://contoso.sharepoint.com/sites/finance');
+ *   };
+ *
+ *   const loadLists = () => {
+ *     invoke(client =>
+ *       client.get(
+ *         `${baseUrl}/_api/web/lists`,
+ *         SPHttpClient.configurations.v1
+ *       ).then(res => res.json())
+ *     ).then(data => console.log(data.value));
+ *   };
+ * }
+ * ```
+ */
+export function useSPFxSPHttpClient(initialBaseUrl) {
+    var _this = this;
+    var _a, _b;
+    var spfxContext = useSPFxContext().spfxContext;
+    // Extract context data
+    var ctx = spfxContext;
+    // Default to current site if no baseUrl provided
+    var defaultBaseUrl = (initialBaseUrl === null || initialBaseUrl === void 0 ? void 0 : initialBaseUrl.trim()) || ((_b = (_a = ctx.pageContext) === null || _a === void 0 ? void 0 : _a.web) === null || _b === void 0 ? void 0 : _b.absoluteUrl) || '';
+    // Normalize: remove trailing slash for consistency (ES5-compatible)
+    var normalizedBaseUrl = defaultBaseUrl.charAt(defaultBaseUrl.length - 1) === '/'
+        ? defaultBaseUrl.slice(0, -1)
+        : defaultBaseUrl;
+    // State management
+    var client = useState(ctx.spHttpClient)[0];
+    var _c = useState(normalizedBaseUrl), baseUrl = _c[0], setBaseUrlState = _c[1];
+    var _d = useState(false), isLoading = _d[0], setIsLoading = _d[1];
+    var _e = useState(undefined), error = _e[0], setError = _e[1];
+    // Initialize client
+    useEffect(function () {
+        if (!ctx.spHttpClient) {
+            console.warn('SPHttpClient not available in SPFx context');
+        }
+    }, [ctx.spHttpClient]);
+    // Public setter for baseUrl with normalization
+    var setBaseUrl = useCallback(function (url) {
+        var trimmed = url.trim();
+        var normalized = trimmed.charAt(trimmed.length - 1) === '/'
+            ? trimmed.slice(0, -1)
+            : trimmed;
+        setBaseUrlState(normalized);
+    }, []);
+    // 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('SPHttpClient not initialized. Check SPFx context.');
+                    }
+                    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,
+        setBaseUrl: setBaseUrl,
+        baseUrl: baseUrl,
+    };
+}
+//# sourceMappingURL=useSPFxSPHttpClient.js.map

package/lib/hooks/useSPFxSPHttpClient.js.map

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

package/lib/hooks/useSPFxServiceScope.d.ts

@@ -0,0 +1,107 @@
+import type { ServiceScope, ServiceKey } from '@microsoft/sp-core-library';
+/**
+ * Return type for useSPFxServiceScope hook
+ */
+export interface SPFxServiceScopeInfo {
+    /**
+     * Native ServiceScope instance from SPFx.
+     * Provides access to SPFx's dependency injection container.
+     */
+    readonly serviceScope: ServiceScope | undefined;
+    /**
+     * Consume a service from the ServiceScope
+     *
+     * @param serviceKey - The service key to consume (from @microsoft/sp-core-library)
+     * @returns The service instance
+     *
+     * @example
+     * ```tsx
+     * import { ServiceKey } from '@microsoft/sp-core-library';
+     *
+     * const myService = consume<MyService>(MyService.serviceKey);
+     * myService.doSomething();
+     * ```
+     */
+    readonly consume: <T>(serviceKey: ServiceKey<T>) => T;
+}
+/**
+ * Hook for SPFx ServiceScope (Dependency Injection)
+ *
+ * ServiceScope is SPFx's dependency injection container that provides:
+ * - Access to built-in SPFx services
+ * - Access to custom registered services
+ * - Service lifecycle management
+ * - Service isolation per scope
+ *
+ * Common built-in services available:
+ * - PageContext (via @microsoft/sp-page-context)
+ * - HttpClient (via @microsoft/sp-http)
+ * - MSGraphClientFactory (via @microsoft/sp-http)
+ * - SPPermission (via @microsoft/sp-page-context)
+ * - EventAggregator (via @microsoft/sp-core-library)
+ *
+ * Use this hook to:
+ * - Consume custom services registered in your solution
+ * - Access built-in SPFx services not exposed via context
+ * - Implement advanced service-based architectures
+ * - Create testable, decoupled components
+ *
+ * Note: Most common services (HttpClient, GraphClient, etc.)
+ * have dedicated hooks (useSPFxHttpClient, useSPFxGraphClient).
+ * Use this hook for custom services or advanced scenarios.
+ *
+ * @returns ServiceScope information and consume helper
+ *
+ * @example Consuming a custom service
+ * ```tsx
+ * import { ServiceKey } from '@microsoft/sp-core-library';
+ *
+ * // Define service interface
+ * interface IMyService {
+ *   doSomething(): void;
+ * }
+ *
+ * // Service key (typically defined in service file)
+ * const MyServiceKey = ServiceKey.create<IMyService>('my-solution:IMyService', IMyService);
+ *
+ * function MyComponent() {
+ *   const { consume } = useSPFxServiceScope();
+ *
+ *   // Consume the service
+ *   const myService = consume<IMyService>(MyServiceKey);
+ *
+ *   const handleClick = () => {
+ *     myService.doSomething();
+ *   };
+ *
+ *   return <button onClick={handleClick}>Do Something</button>;
+ * }
+ * ```
+ *
+ * @example Accessing EventAggregator
+ * ```tsx
+ * import { ServiceKey } from '@microsoft/sp-core-library';
+ * import { IEventAggregator } from '@microsoft/sp-core-library';
+ *
+ * function MyComponent() {
+ *   const { serviceScope } = useSPFxServiceScope();
+ *
+ *   useEffect(() => {
+ *     // Access EventAggregator service
+ *     const eventAggregator = serviceScope.consume(
+ *       ServiceKey.create<IEventAggregator>('EventAggregator', IEventAggregator)
+ *     );
+ *
+ *     const subscription = eventAggregator.subscribe('MyEvent', (args) => {
+ *       console.log('Event received:', args);
+ *     });
+ *
+ *     return () => subscription.dispose();
+ *   }, [serviceScope]);
+ *
+ *   return <div>Listening for events...</div>;
+ * }
+ * ```
+ */
+export declare function useSPFxServiceScope(): SPFxServiceScopeInfo;
+//# sourceMappingURL=useSPFxServiceScope.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useSPFxServiceScope.d.ts","sourceRoot":"","sources":["../../src/hooks/useSPFxServiceScope.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAE3E;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;OAGG;IACH,QAAQ,CAAC,YAAY,EAAE,YAAY,GAAG,SAAS,CAAC;IAEhD;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC,EAAE,UAAU,EAAE,UAAU,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;CACvD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8EG;AACH,wBAAgB,mBAAmB,IAAI,oBAAoB,CAwB1D"}

package/lib/hooks/useSPFxServiceScope.js

@@ -0,0 +1,105 @@
+// useSPFxServiceScope.ts
+// Hook for SPFx ServiceScope (Dependency Injection)
+import { useCallback } from 'react';
+import { useSPFxContext } from './useSPFxContext';
+/**
+ * Hook for SPFx ServiceScope (Dependency Injection)
+ *
+ * ServiceScope is SPFx's dependency injection container that provides:
+ * - Access to built-in SPFx services
+ * - Access to custom registered services
+ * - Service lifecycle management
+ * - Service isolation per scope
+ *
+ * Common built-in services available:
+ * - PageContext (via @microsoft/sp-page-context)
+ * - HttpClient (via @microsoft/sp-http)
+ * - MSGraphClientFactory (via @microsoft/sp-http)
+ * - SPPermission (via @microsoft/sp-page-context)
+ * - EventAggregator (via @microsoft/sp-core-library)
+ *
+ * Use this hook to:
+ * - Consume custom services registered in your solution
+ * - Access built-in SPFx services not exposed via context
+ * - Implement advanced service-based architectures
+ * - Create testable, decoupled components
+ *
+ * Note: Most common services (HttpClient, GraphClient, etc.)
+ * have dedicated hooks (useSPFxHttpClient, useSPFxGraphClient).
+ * Use this hook for custom services or advanced scenarios.
+ *
+ * @returns ServiceScope information and consume helper
+ *
+ * @example Consuming a custom service
+ * ```tsx
+ * import { ServiceKey } from '@microsoft/sp-core-library';
+ *
+ * // Define service interface
+ * interface IMyService {
+ *   doSomething(): void;
+ * }
+ *
+ * // Service key (typically defined in service file)
+ * const MyServiceKey = ServiceKey.create<IMyService>('my-solution:IMyService', IMyService);
+ *
+ * function MyComponent() {
+ *   const { consume } = useSPFxServiceScope();
+ *
+ *   // Consume the service
+ *   const myService = consume<IMyService>(MyServiceKey);
+ *
+ *   const handleClick = () => {
+ *     myService.doSomething();
+ *   };
+ *
+ *   return <button onClick={handleClick}>Do Something</button>;
+ * }
+ * ```
+ *
+ * @example Accessing EventAggregator
+ * ```tsx
+ * import { ServiceKey } from '@microsoft/sp-core-library';
+ * import { IEventAggregator } from '@microsoft/sp-core-library';
+ *
+ * function MyComponent() {
+ *   const { serviceScope } = useSPFxServiceScope();
+ *
+ *   useEffect(() => {
+ *     // Access EventAggregator service
+ *     const eventAggregator = serviceScope.consume(
+ *       ServiceKey.create<IEventAggregator>('EventAggregator', IEventAggregator)
+ *     );
+ *
+ *     const subscription = eventAggregator.subscribe('MyEvent', (args) => {
+ *       console.log('Event received:', args);
+ *     });
+ *
+ *     return () => subscription.dispose();
+ *   }, [serviceScope]);
+ *
+ *   return <div>Listening for events...</div>;
+ * }
+ * ```
+ */
+export function useSPFxServiceScope() {
+    var spfxContext = useSPFxContext().spfxContext;
+    // Extract serviceScope from context with native type
+    var ctx = spfxContext;
+    var serviceScope = ctx.serviceScope;
+    /**
+     * Helper to consume a service from the ServiceScope
+     * Wraps the serviceScope.consume() method with type safety
+     */
+    var consume = useCallback(function (serviceKey) {
+        if (!serviceScope) {
+            throw new Error('ServiceScope is not available in SPFx context');
+        }
+        // Use native ServiceScope.consume() directly
+        return serviceScope.consume(serviceKey);
+    }, [serviceScope]);
+    return {
+        serviceScope: serviceScope,
+        consume: consume,
+    };
+}
+//# sourceMappingURL=useSPFxServiceScope.js.map

package/lib/hooks/useSPFxServiceScope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useSPFxServiceScope.js","sourceRoot":"","sources":["../../src/hooks/useSPFxServiceScope.ts"],"names":[],"mappings":"AAAA,yBAAyB;AACzB,oDAAoD;AAEpD,OAAO,EAAE,WAAW,EAAE,MAAM,OAAO,CAAC;AACpC,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AA8BlD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8EG;AACH,MAAM,UAAU,mBAAmB;IACzB,IAAA,WAAW,GAAK,cAAc,EAAE,YAArB,CAAsB;IAEzC,qDAAqD;IACrD,IAAM,GAAG,GAAG,WAA8C,CAAC;IAC3D,IAAM,YAAY,GAAG,GAAG,CAAC,YAAY,CAAC;IAEtC;;;OAGG;IACH,IAAM,OAAO,GAAG,WAAW,CAAC,UAAK,UAAyB;QACxD,IAAI,CAAC,YAAY,EAAE,CAAC;YAClB,MAAM,IAAI,KAAK,CAAC,+CAA+C,CAAC,CAAC;QACnE,CAAC;QAED,6CAA6C;QAC7C,OAAO,YAAY,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;IAC1C,CAAC,EAAE,CAAC,YAAY,CAAC,CAAC,CAAC;IAEnB,OAAO;QACL,YAAY,cAAA;QACZ,OAAO,SAAA;KACR,CAAC;AACJ,CAAC"}

package/lib/hooks/useSPFxSiteInfo.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Microsoft 365 Group information for group-connected sites
+ */
+export interface SPFxGroupInfo {
+    /** Group ID (GUID) */
+    readonly id: string;
+    /** Whether group is public (true) or private (false) */
+    readonly isPublic: boolean;
+}
+/**
+ * Return type for useSPFxSiteInfo hook
+ */
+export interface SPFxSiteInfo {
+    /** Web ID (GUID) */
+    readonly webId: string;
+    /** Web absolute URL */
+    readonly webUrl: string;
+    /** Web server relative URL */
+    readonly webServerRelativeUrl: string;
+    /** Web title */
+    readonly title: string;
+    /** Web language ID (LCID) */
+    readonly languageId: number;
+    /** Site logo URL (if configured) */
+    readonly logoUrl?: string;
+    /** Site collection ID (GUID) */
+    readonly siteId: string;
+    /** Site collection absolute URL */
+    readonly siteUrl: string;
+    /** Site collection server relative URL */
+    readonly siteServerRelativeUrl: string;
+    /** Site classification (e.g., "Confidential", "Public") */
+    readonly siteClassification?: string;
+    /** Microsoft 365 Group information (if group-connected) */
+    readonly siteGroup?: SPFxGroupInfo;
+}
+/**
+ * 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 declare function useSPFxSiteInfo(): SPFxSiteInfo;
+//# sourceMappingURL=useSPFxSiteInfo.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useSPFxSiteInfo.d.ts","sourceRoot":"","sources":["../../src/hooks/useSPFxSiteInfo.ts"],"names":[],"mappings":"AAKA;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,sBAAsB;IACtB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAEpB,wDAAwD;IACxD,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC5B;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAE3B,oBAAoB;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAEvB,uBAAuB;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAExB,8BAA8B;IAC9B,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;IAGtC,gBAAgB;IAChB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAEvB,6BAA6B;IAC7B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAE5B,oCAAoC;IACpC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAG1B,gCAAgC;IAChC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAExB,mCAAmC;IACnC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAEzB,0CAA0C;IAC1C,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAC;IAEvC,2DAA2D;IAC3D,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAErC,2DAA2D;IAC3D,QAAQ,CAAC,SAAS,CAAC,EAAE,aAAa,CAAC;CACpC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6EG;AACH,wBAAgB,eAAe,IAAI,YAAY,CAkC9C"}