@apvee/spfx-react-toolkit 1.0.0

package/lib/hooks/useSPFxTenantProperty.d.ts

@@ -0,0 +1,389 @@
+/**
+ * Return type for useSPFxTenantProperty hook
+ */
+export interface SPFxTenantPropertyResult<T> {
+    /**
+     * The loaded property value from tenant app catalog.
+     * Undefined if not loaded yet or on error.
+     */
+    readonly data: T | undefined;
+    /**
+     * Property description metadata (optional).
+     * SharePoint StorageEntity only supports description, not comment.
+     */
+    readonly description: string | undefined;
+    /**
+     * Loading state for read operations.
+     * True during initial load or manual load() calls.
+     */
+    readonly isLoading: boolean;
+    /**
+     * Last error from read operations.
+     * Cleared on successful load or write.
+     */
+    readonly error: Error | undefined;
+    /**
+     * Loading state for write operations.
+     * True during write() calls.
+     */
+    readonly isWriting: boolean;
+    /**
+     * Last error from write operations.
+     * Cleared on successful write or load.
+     */
+    readonly writeError: Error | undefined;
+    /**
+     * Whether the current user has permission to write tenant properties.
+     * False if user lacks Manage Web permissions on tenant app catalog.
+     */
+    readonly canWrite: boolean;
+    /**
+     * Manually load/reload the property from tenant app catalog.
+     * Updates data, description, comment, isLoading, and error states.
+     *
+     * @returns Promise that resolves when load completes
+     *
+     * @example
+     * ```tsx
+     * const { data, load } = useSPFxTenantProperty<string>('appVersion', false);
+     *
+     * // Load on button click
+     * <button onClick={load}>Refresh</button>
+     * ```
+     */
+    readonly load: () => Promise<void>;
+    /**
+     * Write property to tenant app catalog.
+     * Creates property if it doesn't exist, updates if it does.
+     * Updates isWriting and writeError states.
+     *
+     * Smart serialization:
+     * - Primitives (string, number, boolean, null, bigint) → String(content)
+     * - Date objects → ISO string
+     * - Objects/arrays → JSON.stringify(content)
+     *
+     * @param content - Data to write
+     * @param description - Optional description metadata (SharePoint only supports description, not comment)
+     * @returns Promise that resolves when write completes
+     *
+     * @example
+     * ```tsx
+     * const { write, isWriting } = useSPFxTenantProperty<string>('apiEndpoint');
+     *
+     * const handleSave = async () => {
+     *   await write('https://api.example.com', 'Production API endpoint');
+     * };
+     * ```
+     */
+    readonly write: (content: T, description?: string) => Promise<void>;
+    /**
+     * Remove property from tenant app catalog.
+     * Requires Manage Web permissions.
+     *
+     * @returns Promise that resolves when removal completes
+     *
+     * @example
+     * ```tsx
+     * const { remove } = useSPFxTenantProperty<string>('oldSetting');
+     *
+     * const handleDelete = async () => {
+     *   if (confirm('Delete this property?')) {
+     *     await remove();
+     *   }
+     * };
+     * ```
+     */
+    readonly remove: () => Promise<void>;
+    /**
+     * Computed state: true if data is loaded successfully.
+     * Equivalent to: !isLoading && !error && data !== undefined
+     *
+     * Useful for conditional rendering:
+     * ```tsx
+     * if (!isReady) return <Spinner />;
+     * return <div>{data}</div>;
+     * ```
+     */
+    readonly isReady: boolean;
+}
+/**
+ * Hook to manage tenant-wide properties using SharePoint StorageEntity API
+ *
+ * Provides read/write operations for tenant-scoped properties stored in the
+ * SharePoint tenant app catalog. Properties are accessible across all sites
+ * in the tenant and support metadata (description only).
+ *
+ * Features:
+ * - Tenant-wide centralized storage (not site-specific)
+ * - Smart serialization for primitives, Date, and complex objects
+ * - Permission checking (canWrite flag)
+ * - Optional metadata (description only - SharePoint limitation)
+ * - Type-safe with TypeScript generics
+ * - Memory leak safe with mounted state tracking
+ * - Automatic app catalog URL discovery
+ * - Remove operation for cleanup
+ *
+ * Requirements:
+ * - Tenant app catalog must be provisioned
+ * - Read: Any authenticated user
+ * - Write/Remove: Site Collection Administrator role on tenant app catalog site
+ *
+ * Permission Notes:
+ * - Being a Tenant Admin is NOT sufficient for write operations
+ * - You must be explicitly added as Site Collection Administrator to the tenant app catalog
+ * - Navigate to the app catalog site → Site Settings → Site Collection Administrators
+ * - Add your user account if write operations fail with permission errors
+ *
+ * Storage Format:
+ * - Primitives (string, number, boolean, null) → stored as string
+ * - Date → stored as ISO 8601 string
+ * - Objects/arrays → stored as JSON string
+ *
+ * @param key - Unique property key (e.g., 'appVersion', 'apiEndpoint', 'featureFlags')
+ * @param autoFetch - Whether to automatically load property on mount. Default: true
+ *
+ * @returns Object with data, metadata, loading states, error states, and CRUD functions
+ *
+ * @example Basic usage - string property
+ * ```tsx
+ * function VersionDisplay() {
+ *   const { data, isLoading, error, write, canWrite } =
+ *     useSPFxTenantProperty<string>('appVersion');
+ *
+ *   if (isLoading) return <Spinner label="Loading version..." />;
+ *   if (error) return <MessageBar messageBarType={MessageBarType.error}>
+ *     Failed to load: {error.message}
+ *   </MessageBar>;
+ *
+ *   const handleUpdate = async () => {
+ *     if (!canWrite) {
+ *       alert('Insufficient permissions');
+ *       return;
+ *     }
+ *
+ *     try {
+ *       await write('2.0.1', 'Current application version');
+ *       console.log('Version updated!');
+ *     } catch (err) {
+ *       console.error('Update failed:', err);
+ *     }
+ *   };
+ *
+ *   return (
+ *     <div>
+ *       <Text>Current Version: {data ?? 'Not Set'}</Text>
+ *       {canWrite && <PrimaryButton onClick={handleUpdate}>Update Version</PrimaryButton>}
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example Number property
+ * ```tsx
+ * const { data, write } = useSPFxTenantProperty<number>('maxUploadSize');
+ *
+ * // Stored as "10485760" (10MB in bytes)
+ * await write(10485760, 'Maximum file upload size in bytes');
+ *
+ * // Read returns: 10485760 (number)
+ * console.log(typeof data); // "number"
+ * ```
+ *
+ * @example Boolean flag
+ * ```tsx
+ * const { data: maintenanceMode, write } = useSPFxTenantProperty<boolean>('maintenanceMode');
+ *
+ * // Stored as "true" or "false"
+ * await write(true, 'Maintenance mode enabled');
+ *
+ * if (maintenanceMode) {
+ *   return <MessageBar>System is under maintenance</MessageBar>;
+ * }
+ * ```
+ *
+ * @example Date property
+ * ```tsx
+ * const { data, write } = useSPFxTenantProperty<string>('lastDeployment');
+ *
+ * // Write date as ISO string
+ * await write(new Date().toISOString(), 'Last deployment timestamp');
+ *
+ * // Read and convert back to Date
+ * const lastDeploy = data ? new Date(data) : undefined;
+ * ```
+ *
+ * @example Complex object with JSON
+ * ```tsx
+ * interface FeatureFlags {
+ *   enableChat: boolean;
+ *   enableAnalytics: boolean;
+ *   maxUsers: number;
+ * }
+ *
+ * const { data, write, isLoading } = useSPFxTenantProperty<FeatureFlags>('featureFlags');
+ *
+ * // Stored as JSON string
+ * await write({
+ *   enableChat: true,
+ *   enableAnalytics: false,
+ *   maxUsers: 1000
+ * }, 'Global feature flags configuration');
+ *
+ * // Read returns parsed object
+ * if (data?.enableChat) {
+ *   return <ChatPanel />;
+ * }
+ * ```
+ *
+ * @example Permission-aware UI
+ * ```tsx
+ * function TenantConfigPanel() {
+ *   const { data, canWrite, write, isWriting, error, writeError } =
+ *     useSPFxTenantProperty<string>('apiEndpoint');
+ *
+ *   const [editValue, setEditValue] = React.useState(data ?? '');
+ *
+ *   React.useEffect(() => {
+ *     setEditValue(data ?? '');
+ *   }, [data]);
+ *
+ *   if (!canWrite) {
+ *     return (
+ *       <MessageBar messageBarType={MessageBarType.info}>
+ *         You don't have permission to edit tenant properties.
+ *         Contact your SharePoint administrator.
+ *       </MessageBar>
+ *     );
+ *   }
+ *
+ *   const handleSave = async () => {
+ *     try {
+ *       await write(editValue, 'Production API endpoint URL');
+ *     } catch (err) {
+ *       console.error('Save failed:', err);
+ *     }
+ *   };
+ *
+ *   return (
+ *     <Stack tokens={{ childrenGap: 10 }}>
+ *       <TextField
+ *         label="API Endpoint"
+ *         value={editValue}
+ *         onChange={(_, val) => setEditValue(val ?? '')}
+ *         disabled={isWriting}
+ *       />
+ *       <PrimaryButton
+ *         onClick={handleSave}
+ *         disabled={isWriting || editValue === data}
+ *       >
+ *         {isWriting ? 'Saving...' : 'Save'}
+ *       </PrimaryButton>
+ *       {writeError && (
+ *         <MessageBar messageBarType={MessageBarType.error}>
+ *           {writeError.message}
+ *         </MessageBar>
+ *       )}
+ *     </Stack>
+ *   );
+ * }
+ * ```
+ *
+ * @example With metadata viewing
+ * ```tsx
+ * function PropertyViewer() {
+ *   const { data, description, isLoading } =
+ *     useSPFxTenantProperty<string>('appConfig');
+ *
+ *   if (isLoading) return <Spinner />;
+ *
+ *   return (
+ *     <Stack tokens={{ childrenGap: 5 }}>
+ *       <Text variant="large">Value: {data}</Text>
+ *       {description && <Text variant="small">Description: {description}</Text>}
+ *     </Stack>
+ *   );
+ * }
+ * ```
+ *
+ * @example Lazy loading with manual trigger
+ * ```tsx
+ * const { data, load, isLoading, write } = useSPFxTenantProperty<Config>(
+ *   'appConfig',
+ *   false  // Don't auto-fetch
+ * );
+ *
+ * return (
+ *   <div>
+ *     <button onClick={load} disabled={isLoading}>
+ *       {isLoading ? 'Loading...' : 'Load Config'}
+ *     </button>
+ *     {data && <ConfigDisplay config={data} />}
+ *   </div>
+ * );
+ * ```
+ *
+ * @example Property removal
+ * ```tsx
+ * function PropertyManager() {
+ *   const { data, remove, canWrite } = useSPFxTenantProperty<string>('deprecatedSetting');
+ *
+ *   const handleDelete = async () => {
+ *     if (!confirm('Delete this property? This cannot be undone.')) return;
+ *
+ *     try {
+ *       await remove();
+ *       console.log('Property deleted');
+ *     } catch (err) {
+ *       console.error('Delete failed:', err);
+ *     }
+ *   };
+ *
+ *   if (!data) return <Text>Property not found</Text>;
+ *
+ *   return (
+ *     <Stack tokens={{ childrenGap: 10 }}>
+ *       <Text>Value: {data}</Text>
+ *       {canWrite && (
+ *         <DefaultButton onClick={handleDelete} text="Delete Property" />
+ *       )}
+ *     </Stack>
+ *   );
+ * }
+ * ```
+ *
+ * @example Multi-property dashboard
+ * ```tsx
+ * function TenantDashboard() {
+ *   const version = useSPFxTenantProperty<string>('appVersion');
+ *   const maintenance = useSPFxTenantProperty<boolean>('maintenanceMode');
+ *   const lastUpdate = useSPFxTenantProperty<string>('lastUpdate');
+ *   const config = useSPFxTenantProperty<AppConfig>('appConfig');
+ *
+ *   const isLoading = version.isLoading || maintenance.isLoading ||
+ *                     lastUpdate.isLoading || config.isLoading;
+ *
+ *   if (isLoading) return <Spinner label="Loading dashboard..." />;
+ *
+ *   return (
+ *     <Stack tokens={{ childrenGap: 20 }}>
+ *       <Text variant="xxLarge">Tenant Configuration</Text>
+ *
+ *       <Stack tokens={{ childrenGap: 10 }}>
+ *         <Label>App Version: {version.data ?? 'Not Set'}</Label>
+ *         <Label>Maintenance Mode: {maintenance.data ? 'ON' : 'OFF'}</Label>
+ *         <Label>Last Update: {lastUpdate.data ? new Date(lastUpdate.data).toLocaleString() : 'Never'}</Label>
+ *       </Stack>
+ *
+ *       {config.data && (
+ *         <Stack tokens={{ childrenGap: 5 }}>
+ *           <Text variant="large">Configuration</Text>
+ *           <pre>{JSON.stringify(config.data, null, 2)}</pre>
+ *         </Stack>
+ *       )}
+ *     </Stack>
+ *   );
+ * }
+ * ```
+ */
+export declare function useSPFxTenantProperty<T = unknown>(key: string, autoFetch?: boolean): SPFxTenantPropertyResult<T>;
+//# sourceMappingURL=useSPFxTenantProperty.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useSPFxTenantProperty.d.ts","sourceRoot":"","sources":["../../src/hooks/useSPFxTenantProperty.ts"],"names":[],"mappings":"AASA;;GAEG;AACH,MAAM,WAAW,wBAAwB,CAAC,CAAC;IACzC;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,CAAC,GAAG,SAAS,CAAC;IAE7B;;;OAGG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;IAEzC;;;OAGG;IACH,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAE5B;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,SAAS,CAAC;IAElC;;;OAGG;IACH,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAE5B;;;OAGG;IACH,QAAQ,CAAC,UAAU,EAAE,KAAK,GAAG,SAAS,CAAC;IAEvC;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAE3B;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAEnC;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,QAAQ,CAAC,KAAK,EAAE,CAAC,OAAO,EAAE,CAAC,EAAE,WAAW,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAEpE;;;;;;;;;;;;;;;;OAgBG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAErC;;;;;;;;;OASG;IACH,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AAkBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsRG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,GAAG,OAAO,EAC/C,GAAG,EAAE,MAAM,EACX,SAAS,GAAE,OAAc,GACxB,wBAAwB,CAAC,CAAC,CAAC,CA0V7B"}