@apvee/spfx-react-toolkit 1.0.0

package/lib/hooks/useSPFxListInfo.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Return type for useSPFxListInfo hook
+ */
+export interface SPFxListInfo {
+    /** List ID (GUID) */
+    readonly id: string;
+    /** List title */
+    readonly title: string;
+    /** List server relative URL */
+    readonly serverRelativeUrl: string;
+    /** List template type (e.g., 100 for Generic List, 101 for Document Library) */
+    readonly baseTemplate?: number;
+    /** Whether list is a document library */
+    readonly isDocumentLibrary?: boolean;
+}
+/**
+ * Hook to access list information
+ *
+ * Provides information about the current SharePoint list/library
+ * when component is rendered in a list context (e.g., list view,
+ * list web part, field customizer).
+ *
+ * Returns undefined if not in a list context.
+ *
+ * Information provided:
+ * - id: Unique identifier
+ * - title: List title
+ * - serverRelativeUrl: Server-relative URL
+ * - baseTemplate: List template type
+ * - isDocumentLibrary: Whether it's a document library
+ *
+ * Note: List context is available in Field Customizers and some
+ * List View WebParts. Standard page WebParts typically don't have
+ * list context. Always check for undefined return value.
+ *
+ * Useful for:
+ * - List-specific operations in Field Customizers
+ * - Conditional rendering based on list type
+ * - Building list URLs
+ * - List metadata display
+ *
+ * @returns List information or undefined if not in list context
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const list = useSPFxListInfo();
+ *
+ *   if (!list) {
+ *     return <div>Not in list context</div>;
+ *   }
+ *
+ *   return (
+ *     <div>
+ *       <h2>{list.title}</h2>
+ *       <p>List ID: {list.id}</p>
+ *       {list.isDocumentLibrary && <p>Document Library</p>}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare function useSPFxListInfo(): SPFxListInfo | undefined;
+//# sourceMappingURL=useSPFxListInfo.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useSPFxListInfo.d.ts","sourceRoot":"","sources":["../../src/hooks/useSPFxListInfo.ts"],"names":[],"mappings":"AAKA;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,qBAAqB;IACrB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAEpB,iBAAiB;IACjB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAEvB,+BAA+B;IAC/B,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IAEnC,gFAAgF;IAChF,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAE/B,yCAAyC;IACzC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,OAAO,CAAC;CACtC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,wBAAgB,eAAe,IAAI,YAAY,GAAG,SAAS,CA4B1D"}

package/lib/hooks/useSPFxListInfo.js

@@ -0,0 +1,70 @@
+// useSPFxListInfo.ts
+// Hook to access list information (when in list context)
+import { useSPFxPageContext } from './useSPFxPageContext';
+/**
+ * Hook to access list information
+ *
+ * Provides information about the current SharePoint list/library
+ * when component is rendered in a list context (e.g., list view,
+ * list web part, field customizer).
+ *
+ * Returns undefined if not in a list context.
+ *
+ * Information provided:
+ * - id: Unique identifier
+ * - title: List title
+ * - serverRelativeUrl: Server-relative URL
+ * - baseTemplate: List template type
+ * - isDocumentLibrary: Whether it's a document library
+ *
+ * Note: List context is available in Field Customizers and some
+ * List View WebParts. Standard page WebParts typically don't have
+ * list context. Always check for undefined return value.
+ *
+ * Useful for:
+ * - List-specific operations in Field Customizers
+ * - Conditional rendering based on list type
+ * - Building list URLs
+ * - List metadata display
+ *
+ * @returns List information or undefined if not in list context
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const list = useSPFxListInfo();
+ *
+ *   if (!list) {
+ *     return <div>Not in list context</div>;
+ *   }
+ *
+ *   return (
+ *     <div>
+ *       <h2>{list.title}</h2>
+ *       <p>List ID: {list.id}</p>
+ *       {list.isDocumentLibrary && <p>Document Library</p>}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export function useSPFxListInfo() {
+    var _a, _b;
+    var pageContext = useSPFxPageContext();
+    // Try to get list from page context
+    var list = pageContext.list;
+    if (!list || !list.id) {
+        return undefined;
+    }
+    // List template type 101 is Document Library
+    var baseTemplate = list.baseTemplate;
+    var isDocumentLibrary = baseTemplate === 101;
+    return {
+        id: list.id.toString(),
+        title: (_a = list.title) !== null && _a !== void 0 ? _a : 'Unknown List',
+        serverRelativeUrl: (_b = list.serverRelativeUrl) !== null && _b !== void 0 ? _b : '',
+        baseTemplate: baseTemplate,
+        isDocumentLibrary: isDocumentLibrary,
+    };
+}
+//# sourceMappingURL=useSPFxListInfo.js.map

package/lib/hooks/useSPFxListInfo.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useSPFxListInfo.js","sourceRoot":"","sources":["../../src/hooks/useSPFxListInfo.ts"],"names":[],"mappings":"AAAA,qBAAqB;AACrB,yDAAyD;AAEzD,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAsB1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,MAAM,UAAU,eAAe;;IAC7B,IAAM,WAAW,GAAG,kBAAkB,EAAE,CAAC;IAEzC,oCAAoC;IACpC,IAAM,IAAI,GAAI,WAOZ,CAAC,IAAI,CAAC;IAER,IAAI,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC;QACtB,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,6CAA6C;IAC7C,IAAM,YAAY,GAAG,IAAI,CAAC,YAAY,CAAC;IACvC,IAAM,iBAAiB,GAAG,YAAY,KAAK,GAAG,CAAC;IAE/C,OAAO;QACL,EAAE,EAAE,IAAI,CAAC,EAAE,CAAC,QAAQ,EAAE;QACtB,KAAK,EAAE,MAAA,IAAI,CAAC,KAAK,mCAAI,cAAc;QACnC,iBAAiB,EAAE,MAAA,IAAI,CAAC,iBAAiB,mCAAI,EAAE;QAC/C,YAAY,cAAA;QACZ,iBAAiB,mBAAA;KAClB,CAAC;AACJ,CAAC"}

package/lib/hooks/useSPFxLocaleInfo.d.ts

@@ -0,0 +1,123 @@
+/**
+ * SPTimeZone interface (preview API in SPFx)
+ * Based on Microsoft Learn documentation
+ * @see https://learn.microsoft.com/en-us/javascript/api/sp-page-context/sptimezone
+ *
+ * Note: This is a preview API that may change in future SPFx versions.
+ * Type definition based on official docs since it's not yet exported in @microsoft/sp-page-context.
+ */
+export interface SPFxTimeZone {
+    /** Time zone ID (numeric identifier) */
+    readonly id: number;
+    /** Offset in minutes from UTC */
+    readonly offset: number;
+    /** Time zone description (e.g., "Pacific Standard Time") */
+    readonly description: string;
+    /** Daylight savings time offset in minutes from UTC */
+    readonly daylightOffset: number;
+    /** Standard time offset in minutes from UTC */
+    readonly standardOffset: number;
+}
+/**
+ * Return type for useSPFxLocaleInfo hook
+ */
+export interface SPFxLocaleInfo {
+    /** Current locale (e.g., "en-US", "it-IT") */
+    readonly locale: string;
+    /** Current UI locale (may differ from content locale) */
+    readonly uiLocale: string;
+    /** Time zone information from SPWeb (preview API) */
+    readonly timeZone: SPFxTimeZone | undefined;
+    /** Whether the language is right-to-left */
+    readonly isRtl: boolean;
+}
+/**
+ * Hook for locale and regional settings
+ *
+ * Provides locale and regional information from SPFx PageContext:
+ * - locale: Current content locale (e.g., "en-US", "it-IT")
+ * - uiLocale: Current UI language locale
+ * - timeZone: Time zone information from SPWeb (preview API)
+ * - isRtl: Right-to-left language detection from CultureInfo
+ *
+ * Uses native SPFx properties (no legacy context):
+ * - cultureInfo.currentCultureName
+ * - cultureInfo.currentUICultureName
+ * - cultureInfo.isRightToLeft
+ * - web.timeZoneInfo (preview API)
+ *
+ * Useful for:
+ * - Internationalization (i18n) with Intl APIs
+ * - Date/time formatting with timezone awareness
+ * - Regional number/currency formatting
+ * - RTL layout detection
+ * - Calendar widget configuration
+ * - Multi-lingual applications
+ *
+ * The locale string can be used directly with JavaScript Intl APIs:
+ * - Intl.DateTimeFormat(locale, options)
+ * - Intl.NumberFormat(locale, options)
+ * - Intl.Collator(locale, options)
+ *
+ * @returns Locale and regional settings
+ *
+ * @example Basic locale usage
+ * ```tsx
+ * function MyComponent() {
+ *   const { locale, isRtl } = useSPFxLocaleInfo();
+ *
+ *   const formatDate = (date: Date) => {
+ *     return new Intl.DateTimeFormat(locale, {
+ *       dateStyle: 'full',
+ *       timeStyle: 'long'
+ *     }).format(date);
+ *   };
+ *
+ *   return (
+ *     <div dir={isRtl ? 'rtl' : 'ltr'}>
+ *       <p>{formatDate(new Date())}</p>
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example Time zone aware formatting
+ * ```tsx
+ * function Calendar() {
+ *   const { locale, timeZone } = useSPFxLocaleInfo();
+ *
+ *   if (!timeZone) return <div>No timezone info</div>;
+ *
+ *   const formatWithTimeZone = (date: Date) => {
+ *     return new Intl.DateTimeFormat(locale, {
+ *       dateStyle: 'medium',
+ *       timeStyle: 'short'
+ *     }).format(date);
+ *   };
+ *
+ *   return (
+ *     <div>
+ *       <h3>Time Zone: {timeZone.description}</h3>
+ *       <p>Offset: {timeZone.offset} minutes from UTC</p>
+ *       <p>{formatWithTimeZone(new Date())}</p>
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example Multi-locale support
+ * ```tsx
+ * function PriceDisplay({ amount }: { amount: number }) {
+ *   const { locale } = useSPFxLocaleInfo();
+ *
+ *   const price = new Intl.NumberFormat(locale, {
+ *     style: 'currency',
+ *     currency: 'USD'
+ *   }).format(amount);
+ *
+ *   return <p>Price: {price}</p>;
+ * }
+ * ```
+ */
+export declare function useSPFxLocaleInfo(): SPFxLocaleInfo;
+//# sourceMappingURL=useSPFxLocaleInfo.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useSPFxLocaleInfo.d.ts","sourceRoot":"","sources":["../../src/hooks/useSPFxLocaleInfo.ts"],"names":[],"mappings":"AAKA;;;;;;;GAOG;AACH,MAAM,WAAW,YAAY;IAC3B,wCAAwC;IACxC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAEpB,iCAAiC;IACjC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAExB,4DAA4D;IAC5D,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAE7B,uDAAuD;IACvD,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAEhC,+CAA+C;IAC/C,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,8CAA8C;IAC9C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAExB,yDAAyD;IACzD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAE1B,qDAAqD;IACrD,QAAQ,CAAC,QAAQ,EAAE,YAAY,GAAG,SAAS,CAAC;IAE5C,4CAA4C;IAC5C,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuFG;AACH,wBAAgB,iBAAiB,IAAI,cAAc,CAmBlD"}

package/lib/hooks/useSPFxLocaleInfo.js

@@ -0,0 +1,109 @@
+// useSPFxLocaleInfo.ts
+// Hook for locale and regional settings
+import { useSPFxPageContext } from './useSPFxPageContext';
+/**
+ * Hook for locale and regional settings
+ *
+ * Provides locale and regional information from SPFx PageContext:
+ * - locale: Current content locale (e.g., "en-US", "it-IT")
+ * - uiLocale: Current UI language locale
+ * - timeZone: Time zone information from SPWeb (preview API)
+ * - isRtl: Right-to-left language detection from CultureInfo
+ *
+ * Uses native SPFx properties (no legacy context):
+ * - cultureInfo.currentCultureName
+ * - cultureInfo.currentUICultureName
+ * - cultureInfo.isRightToLeft
+ * - web.timeZoneInfo (preview API)
+ *
+ * Useful for:
+ * - Internationalization (i18n) with Intl APIs
+ * - Date/time formatting with timezone awareness
+ * - Regional number/currency formatting
+ * - RTL layout detection
+ * - Calendar widget configuration
+ * - Multi-lingual applications
+ *
+ * The locale string can be used directly with JavaScript Intl APIs:
+ * - Intl.DateTimeFormat(locale, options)
+ * - Intl.NumberFormat(locale, options)
+ * - Intl.Collator(locale, options)
+ *
+ * @returns Locale and regional settings
+ *
+ * @example Basic locale usage
+ * ```tsx
+ * function MyComponent() {
+ *   const { locale, isRtl } = useSPFxLocaleInfo();
+ *
+ *   const formatDate = (date: Date) => {
+ *     return new Intl.DateTimeFormat(locale, {
+ *       dateStyle: 'full',
+ *       timeStyle: 'long'
+ *     }).format(date);
+ *   };
+ *
+ *   return (
+ *     <div dir={isRtl ? 'rtl' : 'ltr'}>
+ *       <p>{formatDate(new Date())}</p>
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example Time zone aware formatting
+ * ```tsx
+ * function Calendar() {
+ *   const { locale, timeZone } = useSPFxLocaleInfo();
+ *
+ *   if (!timeZone) return <div>No timezone info</div>;
+ *
+ *   const formatWithTimeZone = (date: Date) => {
+ *     return new Intl.DateTimeFormat(locale, {
+ *       dateStyle: 'medium',
+ *       timeStyle: 'short'
+ *     }).format(date);
+ *   };
+ *
+ *   return (
+ *     <div>
+ *       <h3>Time Zone: {timeZone.description}</h3>
+ *       <p>Offset: {timeZone.offset} minutes from UTC</p>
+ *       <p>{formatWithTimeZone(new Date())}</p>
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example Multi-locale support
+ * ```tsx
+ * function PriceDisplay({ amount }: { amount: number }) {
+ *   const { locale } = useSPFxLocaleInfo();
+ *
+ *   const price = new Intl.NumberFormat(locale, {
+ *     style: 'currency',
+ *     currency: 'USD'
+ *   }).format(amount);
+ *
+ *   return <p>Price: {price}</p>;
+ * }
+ * ```
+ */
+export function useSPFxLocaleInfo() {
+    var pageContext = useSPFxPageContext();
+    // Extract culture info (native SPFx properties)
+    var cultureInfo = pageContext.cultureInfo;
+    var locale = cultureInfo.currentCultureName;
+    var uiLocale = cultureInfo.currentUICultureName;
+    var isRtl = cultureInfo.isRightToLeft;
+    // Extract time zone from web (preview API)
+    // Cast needed because timeZoneInfo is not yet in public types
+    var timeZone = pageContext.web.timeZoneInfo;
+    return {
+        locale: locale,
+        uiLocale: uiLocale,
+        timeZone: timeZone,
+        isRtl: isRtl,
+    };
+}
+//# sourceMappingURL=useSPFxLocaleInfo.js.map

package/lib/hooks/useSPFxLocaleInfo.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useSPFxLocaleInfo.js","sourceRoot":"","sources":["../../src/hooks/useSPFxLocaleInfo.ts"],"names":[],"mappings":"AAAA,uBAAuB;AACvB,wCAAwC;AAExC,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AA4C1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuFG;AACH,MAAM,UAAU,iBAAiB;IAC/B,IAAM,WAAW,GAAG,kBAAkB,EAAE,CAAC;IAEzC,gDAAgD;IAChD,IAAM,WAAW,GAAG,WAAW,CAAC,WAAW,CAAC;IAC5C,IAAM,MAAM,GAAG,WAAW,CAAC,kBAAkB,CAAC;IAC9C,IAAM,QAAQ,GAAG,WAAW,CAAC,oBAAoB,CAAC;IAClD,IAAM,KAAK,GAAG,WAAW,CAAC,aAAa,CAAC;IAExC,2CAA2C;IAC3C,8DAA8D;IAC9D,IAAM,QAAQ,GAAI,WAAW,CAAC,GAAuC,CAAC,YAAY,CAAC;IAEnF,OAAO;QACL,MAAM,QAAA;QACN,QAAQ,UAAA;QACR,QAAQ,UAAA;QACR,KAAK,OAAA;KACN,CAAC;AACJ,CAAC"}

package/lib/hooks/useSPFxLogger.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Log levels
+ */
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+/**
+ * Structured log entry
+ */
+export interface LogEntry {
+    /** Log level */
+    readonly level: LogLevel;
+    /** Log message */
+    readonly message: string;
+    /** Timestamp ISO string */
+    readonly ts: string;
+    /** SPFx instance ID */
+    readonly instanceId: string;
+    /** Host kind */
+    readonly host: string;
+    /** Current user */
+    readonly user: string;
+    /** Site collection URL */
+    readonly siteUrl: string | undefined;
+    /** Web URL */
+    readonly webUrl: string | undefined;
+    /** Correlation ID */
+    readonly correlationId: string | undefined;
+    /** WebPart tag - only available for WebPart contexts */
+    readonly webPartTag?: string;
+    /** Extra metadata */
+    readonly extra?: Record<string, unknown>;
+}
+/**
+ * Return type for useSPFxLogger hook
+ */
+export interface SPFxLoggerInfo {
+    /** Log debug message */
+    readonly debug: (message: string, extra?: Record<string, unknown>) => void;
+    /** Log info message */
+    readonly info: (message: string, extra?: Record<string, unknown>) => void;
+    /** Log warning message */
+    readonly warn: (message: string, extra?: Record<string, unknown>) => void;
+    /** Log error message */
+    readonly error: (message: string, extra?: Record<string, unknown>) => void;
+}
+/**
+ * Hook for structured logging with SPFx context
+ *
+ * Provides structured logging methods that automatically include:
+ * - SPFx instance ID
+ * - Host kind (WebPart, Extension, etc.)
+ * - Current user information
+ * - Site/web URLs
+ * - Correlation ID
+ * - Timestamp
+ *
+ * By default logs to console, but can be configured with custom handler
+ * for integration with Application Insights, Log Analytics, or other
+ * logging services.
+ *
+ * Useful for:
+ * - Diagnostic logging
+ * - Error tracking
+ * - Performance monitoring
+ * - User activity tracking
+ * - Support troubleshooting
+ *
+ * @param handler - Optional custom log handler
+ * @returns Logger methods
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const logger = useSPFxLogger();
+ *
+ *   const handleClick = () => {
+ *     logger.info('Button clicked', { buttonId: 'save' });
+ *   };
+ *
+ *   const handleError = (error: Error) => {
+ *     logger.error('Operation failed', {
+ *       errorMessage: error.message,
+ *       stack: error.stack
+ *     });
+ *   };
+ *
+ *   return <button onClick={handleClick}>Click Me</button>;
+ * }
+ * ```
+ *
+ * @example Custom handler for Application Insights
+ * ```tsx
+ * const customHandler = (entry: LogEntry) => {
+ *   appInsights.trackTrace({
+ *     message: entry.message,
+ *     severityLevel: entry.level,
+ *     properties: {
+ *       instanceId: entry.instanceId,
+ *       correlationId: entry.correlationId,
+ *       ...entry.extra
+ *     }
+ *   });
+ * };
+ *
+ * const logger = useSPFxLogger(customHandler);
+ * ```
+ */
+export declare function useSPFxLogger(handler?: (entry: LogEntry) => void): SPFxLoggerInfo;
+//# sourceMappingURL=useSPFxLogger.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useSPFxLogger.d.ts","sourceRoot":"","sources":["../../src/hooks/useSPFxLogger.ts"],"names":[],"mappings":"AAUA;;GAEG;AACH,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAE3D;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,gBAAgB;IAChB,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC;IAEzB,kBAAkB;IAClB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAEzB,2BAA2B;IAC3B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAEpB,uBAAuB;IACvB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAE5B,gBAAgB;IAChB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,mBAAmB;IACnB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,0BAA0B;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;IAErC,cAAc;IACd,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IAEpC,qBAAqB;IACrB,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,SAAS,CAAC;IAE3C,wDAAwD;IACxD,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAE7B,qBAAqB;IACrB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC1C;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,wBAAwB;IACxB,QAAQ,CAAC,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;IAE3E,uBAAuB;IACvB,QAAQ,CAAC,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;IAE1E,0BAA0B;IAC1B,QAAQ,CAAC,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;IAE1E,wBAAwB;IACxB,QAAQ,CAAC,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;CAC5E;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6DG;AACH,wBAAgB,aAAa,CAC3B,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,QAAQ,KAAK,IAAI,GAClC,cAAc,CAkDhB"}

package/lib/hooks/useSPFxLogger.js

@@ -0,0 +1,117 @@
+// useSPFxLogger.ts
+// Hook for structured logging with SPFx context
+import { useSPFxContext } from './useSPFxContext';
+import { useSPFxInstanceInfo } from './useSPFxInstanceInfo';
+import { useSPFxUserInfo } from './useSPFxUserInfo';
+import { useSPFxSiteInfo } from './useSPFxSiteInfo';
+import { useSPFxCorrelationInfo } from './useSPFxCorrelationInfo';
+/**
+ * Hook for structured logging with SPFx context
+ *
+ * Provides structured logging methods that automatically include:
+ * - SPFx instance ID
+ * - Host kind (WebPart, Extension, etc.)
+ * - Current user information
+ * - Site/web URLs
+ * - Correlation ID
+ * - Timestamp
+ *
+ * By default logs to console, but can be configured with custom handler
+ * for integration with Application Insights, Log Analytics, or other
+ * logging services.
+ *
+ * Useful for:
+ * - Diagnostic logging
+ * - Error tracking
+ * - Performance monitoring
+ * - User activity tracking
+ * - Support troubleshooting
+ *
+ * @param handler - Optional custom log handler
+ * @returns Logger methods
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const logger = useSPFxLogger();
+ *
+ *   const handleClick = () => {
+ *     logger.info('Button clicked', { buttonId: 'save' });
+ *   };
+ *
+ *   const handleError = (error: Error) => {
+ *     logger.error('Operation failed', {
+ *       errorMessage: error.message,
+ *       stack: error.stack
+ *     });
+ *   };
+ *
+ *   return <button onClick={handleClick}>Click Me</button>;
+ * }
+ * ```
+ *
+ * @example Custom handler for Application Insights
+ * ```tsx
+ * const customHandler = (entry: LogEntry) => {
+ *   appInsights.trackTrace({
+ *     message: entry.message,
+ *     severityLevel: entry.level,
+ *     properties: {
+ *       instanceId: entry.instanceId,
+ *       correlationId: entry.correlationId,
+ *       ...entry.extra
+ *     }
+ *   });
+ * };
+ *
+ * const logger = useSPFxLogger(customHandler);
+ * ```
+ */
+export function useSPFxLogger(handler) {
+    var _a = useSPFxInstanceInfo(), instanceId = _a.id, kind = _a.kind;
+    var _b = useSPFxUserInfo(), displayName = _b.displayName, loginName = _b.loginName;
+    var _c = useSPFxSiteInfo(), siteUrl = _c.siteUrl, webUrl = _c.webUrl;
+    var correlationId = useSPFxCorrelationInfo().correlationId;
+    var spfxContext = useSPFxContext().spfxContext;
+    var emit = function (level, message, extra) {
+        // Extract webPartTag only if in WebPart context
+        var webPartTag;
+        if (kind === 'WebPart') {
+            var wpContext = spfxContext;
+            webPartTag = wpContext.webPartTag;
+        }
+        var entry = {
+            level: level,
+            message: message,
+            ts: new Date().toISOString(),
+            instanceId: instanceId,
+            host: kind,
+            user: displayName + ' (' + loginName + ')',
+            siteUrl: siteUrl,
+            webUrl: webUrl,
+            correlationId: correlationId,
+            webPartTag: webPartTag,
+            extra: extra,
+        };
+        if (handler) {
+            handler(entry);
+        }
+        else {
+            // Default: log to console
+            var levelUpper = level.toUpperCase();
+            // For WebPart contexts, display webPartTag instead of instanceId for better readability
+            var displayId = kind === 'WebPart' && webPartTag ? webPartTag : instanceId;
+            var line = '[' + levelUpper + '] ' + entry.ts + ' ' + kind + '/' + displayId + ' – ' + message;
+            // Use appropriate console method
+            var consoleFn = level === 'debug' ? console.log : console[level];
+            consoleFn(line, extra !== null && extra !== void 0 ? extra : {});
+        }
+    };
+    return {
+        debug: function (m, e) { return emit('debug', m, e); },
+        info: function (m, e) { return emit('info', m, e); },
+        warn: function (m, e) { return emit('warn', m, e); },
+        error: function (m, e) { return emit('error', m, e); },
+    };
+}
+//# sourceMappingURL=useSPFxLogger.js.map

package/lib/hooks/useSPFxLogger.js.map

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