@bluealba/pae-ui-react-core 4.0.1-feature-setup-e2e-tests-1231 → 4.0.1-feature-feature-flags-1243

package/dist/src/feature-flags/FeatureFlagGuard.d.ts

@@ -0,0 +1,35 @@
+import { FC, ReactNode } from 'react';
+
+/**
+ * Props for the FeatureFlagGuard component
+ */
+export interface FeatureFlagGuardProps {
+    /**
+     * Name of the feature flag to check
+     */
+    flag: string;
+    /**
+     * Content to render when the flag is enabled (or disabled if inverted)
+     */
+    children: ReactNode;
+    /**
+     * Optional content to render when the flag is disabled (or enabled if inverted)
+     * If not provided, nothing will be rendered when the flag is disabled
+     */
+    fallback?: ReactNode;
+    /**
+     * Whether to invert the logic
+     * If true, children are shown when flag is disabled, fallback when enabled
+     * @default false
+     */
+    invert?: boolean;
+    /**
+     * Base URL for the gateway API
+     * @default ''
+     */
+    gatewayUrl?: string;
+}
+/**
+ * Component for conditional rendering based on feature flags
+ */
+export declare const FeatureFlagGuard: FC<FeatureFlagGuardProps>;

package/dist/src/feature-flags/FeatureFlagsProvider.d.ts

@@ -0,0 +1,79 @@
+import { default as React, ReactNode } from 'react';
+
+/**
+ * Shape of the feature flags context
+ */
+export interface FeatureFlagsContextValue {
+    /**
+     * Map of flag names to their boolean enabled state
+     */
+    flags: Map<string, boolean>;
+    /**
+     * Map of flag names to their variant data
+     */
+    variants: Map<string, {
+        variant: string | null;
+        payload: unknown;
+    }>;
+    /**
+     * Whether the initial prefetch is in progress
+     */
+    isLoading: boolean;
+    /**
+     * Any error that occurred during flag fetching
+     */
+    error: Error | null;
+    /**
+     * Check if a cached flag is enabled
+     * @param flagName - Name of the flag to check
+     * @param defaultValue - Default value if flag is not in cache (default: false)
+     * @returns Whether the flag is enabled
+     */
+    checkFlag: (flagName: string, defaultValue?: boolean) => boolean;
+    /**
+     * Get a cached variant value
+     * @param flagName - Name of the flag
+     * @returns Variant data or null if not in cache
+     */
+    getVariant: (flagName: string) => {
+        variant: string | null;
+        payload: unknown;
+    } | null;
+    /**
+     * Manually refresh all prefetched flags
+     * @returns Promise that resolves when refresh is complete
+     */
+    refresh: () => Promise<void>;
+}
+/**
+ * Props for the FeatureFlagsProvider component
+ */
+export interface FeatureFlagsProviderProps {
+    /**
+     * Base URL for the gateway API
+     * @default ''
+     */
+    gatewayUrl?: string;
+    /**
+     * Array of flag names to prefetch on mount and refresh
+     * These flags will be eagerly loaded and cached
+     */
+    prefetchFlags?: string[];
+    /**
+     * Interval in milliseconds for automatic refresh
+     * If not provided, automatic refresh is disabled
+     */
+    refreshInterval?: number;
+    /**
+     * Child components that will have access to the feature flags context
+     */
+    children: ReactNode;
+}
+/**
+ * React Context for feature flags
+ */
+export declare const FeatureFlagsContext: React.Context<FeatureFlagsContextValue>;
+/**
+ * Provider component for feature flags
+ */
+export declare const FeatureFlagsProvider: React.FC<FeatureFlagsProviderProps>;

package/dist/src/feature-flags/index.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Feature Flags React Utilities
+ *
+ * This module provides React hooks and components for working with feature flags
+ * in the Blue Alba Platform. All utilities are compatible with the gateway's
+ * feature flags API (/_/feature-flags).
+ *
+ * @example
+ * ```tsx
+ * import {
+ *   FeatureFlagsProvider,
+ *   useFeatureFlag,
+ *   useFeatureFlags,
+ *   useVariant,
+ *   FeatureFlagGuard
+ * } from '@bluealba/pae-ui-react-core';
+ *
+ * // Wrap your app with the provider
+ * <FeatureFlagsProvider
+ *   gatewayUrl="/api"
+ *   prefetchFlags={['new-ui', 'beta-feature']}
+ *   refreshInterval={60000}
+ * >
+ *   <App />
+ * </FeatureFlagsProvider>
+ *
+ * // Use in components
+ * function MyComponent() {
+ *   const isEnabled = useFeatureFlag('new-ui');
+ *   return isEnabled ? <NewUI /> : <OldUI />;
+ * }
+ * ```
+ */
+export type { FlagEvaluationResult, FeatureFlagVariant, FeatureFlagsResponse, SingleFlagResponse, VariantResponse, UnifiedEvaluationResponse, } from './types';
+export { FeatureFlagsProvider, FeatureFlagsContext, type FeatureFlagsProviderProps, type FeatureFlagsContextValue, } from './FeatureFlagsProvider';
+export { useFeatureFlag } from './useFeatureFlag';
+export { useFeatureFlags } from './useFeatureFlags';
+export { useVariant, type UseVariantResult } from './useVariant';
+export { FeatureFlagGuard, type FeatureFlagGuardProps } from './FeatureFlagGuard';

package/dist/src/feature-flags/types.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Core types for feature flags React utilities
+ * These types align with the gateway API responses
+ */
+/**
+ * Represents a variant in a feature flag evaluation result
+ */
+export interface FeatureFlagVariant {
+    /**
+     * Name of the variant
+     */
+    name: string;
+    /**
+     * Whether the variant is enabled
+     */
+    enabled: boolean;
+    /**
+     * Additional payload data for the variant
+     */
+    payload?: Record<string, any>;
+}
+/**
+ * Result of a feature flag evaluation
+ * Matches the FlagEvaluationResultDto from the gateway API
+ */
+export interface FlagEvaluationResult {
+    /**
+     * Name of the evaluated feature flag
+     */
+    flagName: string;
+    /**
+     * Whether the flag is enabled for the current context
+     */
+    enabled: boolean;
+    /**
+     * Variant information (for multivariant flags)
+     */
+    variant?: FeatureFlagVariant;
+    /**
+     * Timestamp when the flag was evaluated
+     */
+    evaluatedAt: Date;
+}
+/**
+ * Response from bulk evaluate endpoint
+ */
+export interface FeatureFlagsResponse {
+    /**
+     * Array of flag evaluation results
+     */
+    flags: FlagEvaluationResult[];
+    /**
+     * Timestamp when the evaluation was performed
+     */
+    evaluatedAt: Date;
+}
+/**
+ * Response from single flag evaluation endpoint
+ */
+export interface SingleFlagResponse {
+    /**
+     * Name of the feature flag
+     */
+    flagName: string;
+    /**
+     * Whether the flag is enabled
+     */
+    enabled: boolean;
+    /**
+     * Timestamp when the flag was evaluated
+     */
+    evaluatedAt: Date;
+}
+/**
+ * Response from variant endpoint
+ */
+export interface VariantResponse {
+    /**
+     * Name of the feature flag
+     */
+    flagName: string;
+    /**
+     * The selected variant name (undefined if no variant)
+     */
+    variant: string | undefined;
+    /**
+     * Timestamp when the variant was evaluated
+     */
+    evaluatedAt: Date;
+}
+/**
+ * Unified evaluation response from the gateway API
+ * This is returned by the unified endpoint: GET /_/feature-flags/:flagName
+ *
+ * The value field contains:
+ * - For boolean flags: true or false
+ * - For variant flags: variant name (string), null, or undefined
+ */
+export interface UnifiedEvaluationResponse {
+    /**
+     * Name of the feature flag
+     */
+    flagName: string;
+    /**
+     * The evaluated value of the flag
+     * - Boolean flags: true or false
+     * - Variant flags: variant name (string), null, or undefined
+     */
+    value: boolean | string | null | undefined;
+    /**
+     * Timestamp when the flag was evaluated
+     */
+    evaluatedAt: string;
+}

package/dist/src/feature-flags/useFeatureFlag.d.ts

@@ -0,0 +1,25 @@
+/**
+ * useFeatureFlag Hook
+ *
+ * A React hook for evaluating a single boolean feature flag.
+ * This hook first checks if the flag is in the prefetched cache (from FeatureFlagsProvider).
+ * If not found in cache, it fetches the flag individually from the API.
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const isNewUIEnabled = useFeatureFlag('new-ui', false);
+ *
+ *   return isNewUIEnabled ? <NewUI /> : <OldUI />;
+ * }
+ * ```
+ */
+/**
+ * Hook for evaluating a single boolean feature flag
+ *
+ * @param flagName - Name of the feature flag to evaluate
+ * @param defaultValue - Default value to use if flag cannot be evaluated (default: false)
+ * @param gatewayUrl - Base URL for the gateway API (default: '')
+ * @returns Boolean indicating whether the flag is enabled
+ */
+export declare function useFeatureFlag(flagName: string, defaultValue?: boolean, gatewayUrl?: string): boolean;

package/dist/src/feature-flags/useFeatureFlags.d.ts

@@ -0,0 +1,9 @@
+import { FeatureFlagsContextValue } from './FeatureFlagsProvider';
+
+/**
+ * Hook for accessing the feature flags context
+ *
+ * @throws Error if used outside of FeatureFlagsProvider
+ * @returns The full feature flags context
+ */
+export declare function useFeatureFlags(): FeatureFlagsContextValue;

package/dist/src/feature-flags/useVariant.d.ts

@@ -0,0 +1,54 @@
+/**
+ * useVariant Hook
+ *
+ * A React hook for getting the variant value of a multivariant feature flag.
+ * This hook first checks if the variant is in the prefetched cache (from FeatureFlagsProvider).
+ * If not found in cache, it fetches the variant individually from the unified API.
+ *
+ * IMPORTANT: The unified individual API endpoint does NOT return the payload.
+ * To get payload data, you should either:
+ * 1. Use FeatureFlagsProvider with prefetchFlags to cache the variant with payload
+ * 2. Use the bulk evaluate endpoint directly if you need payload for single flags
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { variant, payload, isLoading } = useVariant('checkout-flow');
+ *
+ *   if (isLoading) return <Spinner />;
+ *
+ *   if (variant === 'new-checkout') {
+ *     return <NewCheckout config={payload} />;
+ *   }
+ *
+ *   return <OldCheckout />;
+ * }
+ * ```
+ */
+/**
+ * Return type for the useVariant hook
+ */
+export interface UseVariantResult {
+    /**
+     * The selected variant name, or null if no variant is selected
+     */
+    variant: string | null;
+    /**
+     * The payload data associated with the variant
+     * Note: Only available if the variant was fetched via FeatureFlagsProvider (prefetch)
+     * The individual variant endpoint does not return payload
+     */
+    payload: unknown;
+    /**
+     * Whether the variant is currently being loaded
+     */
+    isLoading: boolean;
+}
+/**
+ * Hook for getting the variant value of a multivariant feature flag
+ *
+ * @param flagName - Name of the feature flag
+ * @param gatewayUrl - Base URL for the gateway API (default: '')
+ * @returns Object containing variant, payload, and loading state
+ */
+export declare function useVariant(flagName: string, gatewayUrl?: string): UseVariantResult;

package/dist/src/index.d.ts

@@ -9,3 +9,4 @@ export * from './components/common';
 export { default as initializeMicroFrontend } from './utils/initializeMicroFrontend';
 export * from './MicrofrontendProps';
 export { setupTestEnvironment } from './test-utils/setupTestEnvironment';
+export * from './feature-flags';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bluealba/pae-ui-react-core",
-  "version": "4.0.1-feature-setup-e2e-tests-1231",
+  "version": "4.0.1-feature-feature-flags-1243",
   "type": "module",
   "main": "./dist/index.cjs.js",
   "module": "./dist/index.esm.js",