@andreaswissel/uiflow
Version:
Adaptive UI density management library with progressive disclosure, element dependencies, A/B testing, and intelligent behavior-based adaptation
281 lines • 8.54 kB
TypeScript
/**
* UIFlow - Adaptive UI density management library
* Licensed under CC BY-NC 4.0
*/
import type { UIFlowConfig, UIFlowInstance, Category, UserType, UserPattern, AreaStats, FlowConfiguration, AreaId, ElementId, DensityLevel, ElementData, ElementOptions, HighlightOptions, InteractionData, DataSourceConfig, DataSourceInterface } from './types.js';
export declare class UIFlow implements UIFlowInstance {
config: Required<UIFlowConfig>;
private elements;
private areas;
private usageHistory;
private initialized;
private defaultDensity;
private syncTimer;
private remoteOverrides;
private highlights;
private highlightStyles;
private dataManager;
constructor(options?: Partial<UIFlowConfig>);
/**
* Initialize UIFlow with configuration
*/
init(options?: Partial<UIFlowConfig>): Promise<UIFlowInstance>;
/**
* Categorize a UI element with optional area specification
*/
categorize(element: HTMLElement, category: Category, area?: AreaId, options?: ElementOptions): UIFlowInstance;
/**
* Get density level for specific area (0-1)
* Checks remote overrides first, then local data
*/
getDensityLevel(area?: AreaId): DensityLevel;
/**
* Get all area densities
*/
getAreaDensities(): Record<AreaId, DensityLevel>;
/**
* Set density level for specific area manually
*/
setDensityLevel(level: DensityLevel, area?: AreaId, options?: {
skipAPI?: boolean;
}): UIFlowInstance;
/**
* Check if element should be visible based on current density
*/
shouldShowElement(category: Category, area?: AreaId): boolean;
/**
* Enhanced element visibility check including dependencies
*/
shouldShowElementWithDependencies(elementId: ElementId): boolean;
/**
* Override density for specific area (admin control)
*/
setRemoteOverride(area: AreaId, density: DensityLevel): void;
/**
* Remove remote override for area
*/
clearRemoteOverride(area: AreaId): void;
/**
* Get current override status
*/
getOverrides(): Record<AreaId, DensityLevel>;
/**
* Check if area has remote override
*/
hasOverride(area: AreaId): boolean;
/**
* Highlight an element with specific style and optional tooltip
*/
highlightElement(elementId: ElementId, style?: string, options?: HighlightOptions): UIFlowInstance;
/**
* Remove highlight from element
*/
removeHighlight(elementId: ElementId): UIFlowInstance;
/**
* Flag element as new with optional help text
*/
flagAsNew(elementId: ElementId, helpText?: string, duration?: number): UIFlowInstance;
/**
* Show tooltip for element
*/
showTooltip(elementId: ElementId, text: string, options?: Partial<HighlightOptions>): UIFlowInstance;
/**
* Clear all highlights
*/
clearAllHighlights(): UIFlowInstance;
/**
* Get currently highlighted elements
*/
getHighlights(): ElementId[];
/**
* Add a data source dynamically
*/
addDataSource(name: string, type: string, config: DataSourceConfig, isPrimary?: boolean): UIFlowInstance;
/**
* Remove a data source
*/
removeDataSource(name: string): UIFlowInstance;
/**
* Get data source by name (for advanced usage)
*/
getDataSource(name: string): DataSourceInterface | undefined;
/**
* Force sync with data sources and apply updates
*/
forceSync(): Promise<void>;
/**
* Simulate usage over time for testing
*/
simulateUsage(area: AreaId, interactions: InteractionData[], daysToSimulate?: number): void;
/**
* Simulate realistic user behavior patterns
*/
simulateUserType(type: UserType | UserPattern, areas?: AreaId | AreaId[]): void;
/**
* Enable/disable demo mode for testing
*/
setDemoMode(enabled: boolean): void;
/**
* Directly set density for demos (bypasses learning)
*/
boostDensity(area: AreaId, targetDensity: number): void;
/**
* Reset area to initial state
*/
resetArea(area: AreaId): void;
/**
* Get comprehensive stats for an area
*/
getAreaStats(area: AreaId): AreaStats;
/**
* Get stats for all areas
*/
getOverviewStats(): Record<AreaId, AreaStats>;
private demoModeOriginal?;
private loadedConfiguration?;
private sequenceTracker;
private activeRules;
private ruleCheckTimer;
private abTestVariant?;
private abTestMetrics;
/**
* Public getters for controlled access to private properties
*/
getElementCount(): number;
getAreaCount(): number;
getElementsForArea(area: AreaId): ElementData[];
isInitialized(): boolean;
/**
* Get elements for demo features (controlled access)
*/
getNewVisibleElements(): Array<{
elementId: ElementId;
helpText: string | undefined;
}>;
getVisibleElementsWithHelp(): Array<{
elementId: ElementId;
helpText: string;
}>;
getVisibleElementsSorted(): Array<{
elementId: ElementId;
category: Category;
helpText: string | undefined;
}>;
/**
* Validate element dependencies
*/
validateDependencies(elementId: ElementId): boolean;
private validateSingleDependency;
private validateUsageCount;
private validateSequence;
private validateTimeBased;
private parseTimeWindow;
/**
* Track element sequences for dependency validation and user journey analysis
*/
private trackElementSequence;
private addToSequence;
/**
* Analyze user journey patterns and detect competency progression
*/
private analyzeUserJourney;
/**
* Adapt UIFlow behavior based on detected user journey patterns
*/
private adaptToUserJourney;
/**
* Flag new elements in an area for discovery
*/
private flagNewElementsInArea;
/**
* Load configuration from JSON with optional A/B testing
*/
loadConfiguration(config: FlowConfiguration): Promise<UIFlowInstance>;
/**
* Select A/B test variant based on traffic allocation
*/
private selectABTestVariant;
private hashString;
/**
* Merge base configuration with variant configuration
*/
private mergeConfiguration;
/**
* Initialize A/B test metrics tracking
*/
private initializeABTestMetrics;
/**
* Track A/B test metrics
*/
trackABTestMetric(metric: string, value?: number): void;
/**
* Get A/B test results
*/
getABTestResults(): {
variant: string | undefined;
metrics: Record<string, number>;
};
/**
* Export current configuration
*/
exportConfiguration(): FlowConfiguration;
/**
* Initialize rule engine with configuration rules
*/
private initializeRuleEngine;
/**
* Process all active rules
*/
private processRules;
/**
* Evaluate if a rule trigger condition is met
*/
private evaluateRuleTrigger;
private evaluateUsagePattern;
private evaluateTimeBased;
private evaluateElementInteraction;
/**
* Execute a rule action
*/
private executeRuleAction;
private unlockElement;
private unlockCategory;
private showTutorial;
/**
* Destroy instance and cleanup timers
*/
destroy(): void;
private getElementId;
private updateElementVisibility;
private updateAreaElementsVisibility;
private updateAllElementsVisibility;
private setupObservers;
private recordInteraction;
/**
* Update visibility of elements that may have dependencies satisfied
*/
private updateDependentElements;
private trackInteraction;
private recordUsageHistory;
private adaptDensity;
private getRecentUsageByArea;
private getAcceleratedTime;
private loadStoredData;
private saveData;
private emit;
private setupDataSources;
private syncWithDataSources;
private pushToDataSources;
private applyRemoteSettings;
private startSyncTimer;
private stopSyncTimer;
private applyHighlight;
private createTooltip;
private positionTooltip;
private injectHighlightStyles;
}
export declare function createUIFlow(options?: Partial<UIFlowConfig>): UIFlow;
declare const _default: UIFlow;
export default _default;
export type * from './types.js';
//# sourceMappingURL=index.d.ts.map