## Overview

Overview of resource allocations and utilization.

The Resource Planner is a sophisticated visualization widget for managing resource allocations across time periods. It combines a hierarchical tree structure with a time-phased grid, enabling users to see how resources are allocated and utilized over configurable intervals.

**Purpose**: Provide a comprehensive view of resource capacity, allocation, and utilization that enables informed planning decisions.

**Use when**:
- You need to visualize resource allocations across multiple projects or teams
- Users must understand utilization levels at a glance through color-coded indicators
- Planning requires comparing different allocation scenarios or data series
- Hierarchical organization of resources (e.g., departments, teams, individuals) needs to be represented

**Alternatives**:
- **Embedded Search Table**: When you only need tabular data without time-phased visualization
- **Highcharts**: When you need pure chart visualization without the interactive tree structure
- **Gantt Chart**: When task scheduling and dependencies are more important than resource utilization

## Use Cases

### Strategic Portfolio Planning
Executives and portfolio managers use this widget to gain visibility across all projects and resources. The focus is on long time horizons (quarters to years) with aggregated views that support strategic resource decisions.

### Operational Resource Management
Team leads and resource managers use this widget for day-to-day allocation decisions. The focus is on shorter time frames (weeks to months) with detailed utilization tracking to identify capacity issues.

### Context-Specific Resource Views
When embedded within a specific project or resource page, the widget shows allocations relevant to that context. This supports focused decision-making without the noise of unrelated data.

### Comparison and Scenario Analysis
The widget supports displaying multiple data series side by side, enabling users to compare planned versus actual allocations, or to evaluate different resource scenarios before committing to changes.

## Behavior and Capabilities

### Hierarchical Tree Structure
Resources are organized in a collapsible tree that can represent organizational hierarchies, project structures, or any parent-child relationship defined in the data model. Users can expand and collapse levels to focus on relevant detail.

### Time-Phased Grid
The main visualization area displays values across configurable time intervals. Users can typically switch between different granularities (daily, weekly, monthly, quarterly, yearly) depending on their planning needs.

### Utilization Color Coding
Values are color-coded based on configurable thresholds, providing instant visual feedback about resource health. Common patterns include traffic-light coloring (green for healthy, yellow for warning, red for critical) or uniform coloring when status indication is not needed.

### Dynamic Time Ranges
Time ranges can be configured relative to the current date (e.g., "from 1 month ago to 12 months ahead"), ensuring the view stays relevant without manual updates.

### Integrated Charts
The widget can display summary charts that aggregate the grid data, providing visual summaries alongside the detailed tree view.

### Configurable Actions
Users can be given access to resource operations directly from the widget, streamlining workflows that involve allocation changes.

## Design Considerations

### Tree Depth vs. Performance
Deeper hierarchies with many nodes can impact rendering performance and user experience. Consider collapsing deeper levels by default and ensuring searches return a reasonable number of nodes.

### Time Granularity Trade-offs
Finer granularity (days, weeks) provides more detail but can make the grid harder to read and slower to render. Coarser granularity (quarters, years) is better for strategic views but may hide short-term fluctuations.

### Utilization Threshold Philosophy
The choice of thresholds and colors communicates what "good" looks like. Tight bands (e.g., 90-110%) suit high-utilization environments where small deviations matter. Wider bands (e.g., 60-100%) allow more flexibility. Uniform coloring removes status indication entirely, making the view purely informational.

### Context-Aware Root Selection
When embedding this widget, consider what should be the "root" of the tree. Using the current page as root creates a focused view; using a broader search creates a portfolio view. The choice significantly affects user experience.

### Comparison Groups
Showing multiple data series adds analytical power but also visual complexity. Use comparison groups when the analytical benefit justifies the added cognitive load.

## Related Widgets

| Widget | Relationship |
|--------|--------------|
| **Highcharts** | Often paired above the Resource Planner to provide summary visualizations of the same data |
| **Embedded Search Table** | Shows related tabular data (requests, assignments) alongside the planner view |
| **Navigation Tiles** | Provides dashboard navigation context when the planner is part of a larger dashboard |
| **Attributes Group** | Displays resource properties and details in sidebar or header positions |