@cplace/test-mcp-server 0.1.15 → 1.1.0

package/dist/widget-specifications/_research_from_ga_products/de-2lforge-curves-widget/research.md

@@ -0,0 +1,341 @@
+# Research: de.2lforge.curves.widget
+
+**Research Date:** 2026-01-16
+**Widget ID:** `de.2lforge.curves.widget`
+**Repository:** cplace-2lforge-curves
+**Definition Class:** de.toolforge.curves/src/main/java/de/toolforge/curves/script/CurvesWidgetDefinition.java
+
+---
+
+## 1. Widget Description
+
+The Curves widget is a time-series data visualization and planning widget that displays resource allocation, workload, or numeric values across configurable time intervals in both tabular and chart formats.
+
+It enables users to view, analyze, and edit time-bound numeric data for multiple entities simultaneously, with support for hierarchical grouping, multiple visualization types, and flexible interval configurations (days, weeks, months, quarters, years, or custom dynamic intervals).
+
+---
+
+## 2. Core Purpose and Functionality
+
+### What This Widget Does
+
+The Curves widget serves as a comprehensive solution for **time-based resource planning and capacity visualization**. It:
+
+1. **Displays Time-Series Data**: Shows numeric values distributed across time intervals for pages/entities matching a search or selection
+2. **Provides Dual View**: Combines an interactive table (Handsontable) with synchronized charts (Highcharts) for the same data
+3. **Enables In-Place Editing**: Allows direct editing of time-bound values in table cells (when permissions allow)
+4. **Aggregates Data**: Automatically calculates sums across different dimensions (time, types, hierarchies)
+5. **Supports Multiple Data Patterns**: Handles both interval-based data (start/end dates) and time-bounded resource attributes
+
+### Data Model
+
+The widget works with two primary data patterns:
+
+1. **Interval-Based Data**: Pages with start/end date attributes and a numeric value attribute
+   - Example: Tasks with start date, end date, and effort/cost
+
+2. **Time-Bounded Resources**: Pages with special time-bounded attributes that store values for specific date ranges
+   - More advanced pattern for fine-grained temporal data
+
+---
+
+## 3. Use Cases
+
+### Primary Use Cases
+
+1. **Resource Capacity Planning**
+   - Track team member availability across weeks/months
+   - Visualize allocation percentages over time
+   - Identify over-allocation or gaps in resource coverage
+
+2. **Project Workload Visualization**
+   - Display project effort distribution across time
+   - Compare planned vs. actual effort by time period
+   - Aggregate workload across multiple projects or teams
+
+3. **Financial Planning and Budgeting**
+   - Track budget allocation across fiscal quarters
+   - Visualize cost distribution over project timeline
+   - Monitor cumulative spending patterns
+
+4. **Multi-Type Time-Series Comparison**
+   - Compare different metrics (effort, cost, FTE) side-by-side
+   - Analyze multiple entity types with distinct visualizations
+   - Stack or layer different data series in charts
+
+5. **Hierarchical Reporting**
+   - Group data by custom hierarchies (departments, categories, etc.)
+   - Display aggregated sums at different hierarchy levels
+   - Filter and focus on specific hierarchy branches
+
+### When to Choose This Widget
+
+Users would select the Curves widget when they need to:
+
+- Visualize how numeric values are distributed across time periods
+- Enable users to directly edit time-based allocations
+- Compare multiple entities or types in a unified view
+- See both detailed data (table) and trends (charts) simultaneously
+- Work with configurable time granularity (from days to years)
+- Aggregate and sum data across multiple dimensions
+
+---
+
+## 4. Key Configuration Concepts
+
+### A. Data Source Configuration
+
+**Search-Based Selection:**
+- Configure a search filter to define which pages to display
+- Connect to a table widget for synchronized selection
+- Use external page providers for dynamic data sources
+
+**Options:**
+- `pageSearch`: Search filter (JSON) to retrieve pages
+- `connectedTableWidgetId`: Connect to another table for selection synchronization
+- `pageProvider`: Widget ID of external provider for dynamic page lists
+- `automaticReload`: Auto-refresh on selection changes
+
+### B. Time Configuration
+
+**Date Range:**
+- Absolute dates (fixed start/end)
+- Relative dates (e.g., last 3 months, next 6 weeks)
+- Both configurable in widget settings or adjustable via toolbar
+
+**Interval/Period Types:**
+- Day, Workday (Mon-Fri), Week, Month, Quarter, Year
+- Dynamic Interval: Custom intervals defined by another search/attribute
+- Each interval type has appropriate date formatting
+
+### C. Type Configuration
+
+**Type Configs** define what to display and how:
+- `curveType`: Which page type to analyze
+- `startAttribute` / `endAttribute`: Date range attributes
+- `valueAttribute`: Numeric value to aggregate (or `resourceAttribute` for time-bounded values)
+- `chartType`: Visualization style (bar, line, area, stacked, etc.)
+- `color`: Display color for this type
+- `showPages`: Whether to show individual pages or only aggregated sums
+- `valuePrecision`: Decimal places for numeric display
+- `calendar`: Calendar system for date calculations
+
+Multiple type configs can be configured, allowing simultaneous display of different entity types or metrics.
+
+### D. Attribute Configuration (Hierarchy)
+
+**Hierarchy Configs** enable grouping by attribute values:
+- Group pages by enum values, references, or other attributes
+- Create hierarchical structure in the table
+- Show aggregated sums at each hierarchy level
+- Filter which hierarchies are initially visible
+
+### E. Visualization Options
+
+**Chart Types:**
+- `NONE`: Table only, no chart
+- `LINE`: Line chart
+- `STEP`: Step line chart
+- `BAR`: Bar chart
+- `AREA`: Area chart
+- `STACK_TYPE`: Stacked by type
+- `STACK_ATTR`: Stacked by attribute
+- `HIERARCHY_BAR` / `HIERARCHY_LINE`: Charts with hierarchy grouping
+
+**Display Settings:**
+- `chartHeight`: Height of the chart area
+- `showPages`: Toggle individual page rows vs. only sums
+- `disableToolbar`: Hide the interactive toolbar
+- `showSumRows`: Display sum rows in table
+- `targetRange`: Overlay a target range band on charts
+
+### F. Column Configuration
+
+**Default Columns:**
+- Name: Page/entity name
+- Type: Type configuration display name
+- Sum: Total value across all intervals
+- Displayed: Number of intervals with non-zero values
+- Interval columns: One column per time period
+
+**Custom Columns:**
+- Add additional attribute columns from the page types
+- Configure aggregation (min, max, sum, join)
+- Set column widths and display names
+
+**Column Visibility:**
+- Toggle visibility of type, sum, and displayed columns
+- Configure default and per-user column widths
+
+### G. Export Configuration
+
+- `enableExportData`: Allow data export to Excel/CSV
+- `exportHierarchyType`: How to represent hierarchies in export (rows vs. columns)
+
+---
+
+## 5. Technical Architecture
+
+### Backend Components
+
+**Main Classes:**
+- `CurvesWidgetDefinition`: Widget definition and configuration validation (CurvesWidgetDefinition.java:50)
+- `CurvesWidgetState`: State management and serialization (CurvesWidgetState.java:60)
+- `CurvesWidgetTypes.CURVES_WIDGET`: Configuration attribute definitions (CurvesWidgetTypes.java:51)
+- `CurvesAppTypes.TYPE_CONFIG`: Type configuration page type (CurvesAppTypes.java:49)
+- `CurvesAppTypes.HIERARCHY_CONFIG`: Attribute/hierarchy configuration page type
+
+**Key Handlers:**
+- `CurvesWidgetLoadDataHandler`: Fetch and calculate interval data
+- `CurvesWidgetUpdateDataHandler`: Handle in-place value edits
+- `CurvesWidgetSaveUserColumnWidthConfigHandler`: Persist user column preferences
+- `StartCurvesWidgetExportHandler`: Export data to files
+
+**Data Processing:**
+- Interval calculation based on period type
+- Value aggregation across time ranges
+- Hierarchy grouping and sum calculation
+- Permission checking for edit capabilities
+
+### Frontend Components
+
+**Main Components:**
+- `cv-widget`: Main widget controller (cv-widget.controller.ts)
+- `cv-handsontable`: Interactive table component
+- `cv-highcharts`: Chart visualization component
+- `cv-toolbar`: Configuration toolbar with dropdowns and controls
+
+**Toolbar Controls:**
+- Date range picker
+- Interval/period selector
+- Chart type selector
+- Type config multi-select
+- Attribute config multi-select
+- Show pages toggle
+
+**Data Flow:**
+1. Widget initializes with configuration from `CurvesWidgetState`
+2. Loads data via `loadDataUrl` handler
+3. Processes response into table rows and chart data
+4. Renders synchronized table and chart
+5. User edits trigger update handlers
+6. Changes saved back to entity attributes
+
+### Integration Points
+
+**Connected Widgets:**
+- Can connect to table widgets for selection synchronization
+- Supports external page provider widgets
+- Publishes events for data changes
+
+**Events:**
+- `EVENT_PROVIDE_CURVES_PAGES`: Receive page UIDs from providers
+- `EVENT_PROVIDE_SEARCH`: Receive search JSON from providers
+- `EVENT_ROW_SELECTION_CHANGED`: Respond to table selections
+- `RELOAD_RESOURCE_EVENT`: Trigger data refresh
+- `RENDER_END_EVENT`: Signal rendering completion
+
+---
+
+## 6. Related Features and Dependencies
+
+### Dependencies
+- Handsontable library for interactive tables
+- Highcharts library for chart visualizations
+- cplace platform search and data model APIs
+
+### Related Widgets
+- Table widgets (for connected selection)
+- Page provider widgets (for dynamic data sources)
+
+### Plugin Structure
+The cplace-2lforge-curves repository contains:
+- Main plugin: `de.toolforge.curves`
+- Related plugin: `de.toolforge.timeBoundedResources` (for time-bounded attribute support)
+
+---
+
+## 7. Validation and Configuration Requirements
+
+### Required Configuration
+
+For the widget to be functional (CurvesWidgetDefinition.java:76-85):
+1. At least one type configuration must be selected
+2. Start date must be before end date
+3. If using dynamic intervals: dynamic interval search and attribute must be configured
+
+### Configuration Validation
+
+The widget performs validation:
+- Date range consistency (CurvesWidgetDefinition.java:91-99)
+- Dynamic interval configuration completeness (CurvesWidgetDefinition.java:101-127)
+- Attribute-type compatibility (optional, currently disabled)
+
+### User Configuration Persistence
+
+The widget saves per-user settings:
+- Column widths for default and custom columns
+- Toolbar state (selected types, attributes, date ranges, chart type, interval)
+- User preferences stored in user config, not widget configuration
+
+---
+
+## 8. Advanced Features
+
+### Dynamic Intervals
+Instead of fixed periods (weeks, months), define intervals from another search:
+- Search for "milestone" or "phase" pages
+- Use date attribute for interval boundaries
+- Use another attribute for interval names
+- Creates custom, irregular time periods
+
+### Context Menu
+Configurable right-click context menu in table cells:
+- Custom actions based on cell type (name, type, interval, etc.)
+- Row type filtering (page, hierarchy, sum)
+- Single or multiple selection modes
+- Server-side handlers for custom actions
+
+### Target Range Overlay
+Visual indicator on charts:
+- Define min/max target values
+- Color-coded range band
+- Helps identify over/under-capacity
+
+### Custom Columns
+Beyond default columns, add attributes from entity types:
+- Display any attribute from the page types
+- Aggregate functions for numeric attributes
+- Sort and filter by custom columns
+
+### Editable Cells
+When permissions allow:
+- Direct editing of interval values in table
+- Real-time validation and feedback
+- Updates saved to entity attributes
+- Edit indicators show which cells are editable
+
+---
+
+## 9. Localization and Formatting
+
+- All labels and messages use cplace's localization system
+- Date formatting respects user's language and locale
+- Number formatting (decimal separators, precision) follows locale
+- Chart types, intervals, and enums have localized labels
+
+---
+
+## 10. Performance Considerations
+
+- Asynchronous data loading with progress indicators
+- Background calculation for large datasets
+- Status polling for long-running calculations
+- Request cancellation when configurations change
+- User column width config to avoid re-calculation
+
+---
+
+## Summary
+
+The Curves widget is a sophisticated time-series planning and visualization tool designed for resource management, capacity planning, and temporal data analysis. Its strength lies in combining flexible data source configuration, multiple aggregation dimensions (time, type, hierarchy), dual visualization modes (table + chart), and in-place editing capabilities. It's particularly valuable for teams needing to plan, track, and optimize resource allocation or workload distribution across configurable time periods.

package/dist/widget-specifications/_research_from_ga_products/de-2lforge-toolbar-datePickerWidget/research.md

@@ -0,0 +1,232 @@
+# Research: de.2lforge.toolbar.datePickerWidget
+
+## Widget Overview
+
+### Purpose
+The `de.2lforge.toolbar.datePickerWidget` provides a reusable, toolbar-integrated date picker component that allows users to select a single date through an interactive calendar interface with optional quick selection shortcuts.
+
+### One-Sentence Description
+A toolbar button widget that displays a calendar-based date picker with optional relative date shortcuts, enabling users to select single dates through an interactive dropdown interface.
+
+---
+
+## Core Functionality
+
+### What This Widget Does
+The date picker widget renders as a button in a toolbar that, when clicked, opens a dropdown containing:
+1. **Calendar Interface**: An interactive calendar based on bootstrap-datepicker for selecting specific dates
+2. **Relative Date Selection** (optional): Quick-select buttons for dates relative to today (e.g., +10 days, -30 days)
+3. **Visual State Indicators**: Shows whether the date has been changed from default and displays validation errors
+4. **Reset Capability**: One-click reset to default value when the date has been modified
+
+### Technical Architecture
+
+**Repository**: `cplace-2lforge-toolbar`
+
+**Backend Component**:
+- **Definition Class**: `de/toolforge/toolbar/widgets/DatePickerWidgetDefinition.java:17`
+- **Plugin**: Part of the `ToolbarPlugin` which provides reusable form elements for 2lforge plugins
+- **Widget Kind**: `de.2lforge.toolbar.datePickerWidget`
+
+**Frontend Components**:
+- **Main Component**: `tlf-date-picker` (AngularJS component)
+- **Core Calendar**: `tlf-date-picker-core` (wraps bootstrap-datepicker)
+- **Relative Dates**: `tlf-date-diff` (provides quick date selection)
+- **Module**: `de.toolforge.toolbar.datepickers`
+
+---
+
+## Use Cases
+
+### 1. **Date Selection in Reports and Filters**
+When users need to filter data by a specific date or generate reports for a particular day.
+
+**Example Scenarios**:
+- Selecting a report generation date
+- Filtering project milestones by date
+- Setting a deadline or due date
+- Choosing a start date for an analysis period
+
+### 2. **Quick Date Navigation**
+When users frequently need to select dates relative to today without clicking through calendar months.
+
+**Example Scenarios**:
+- Selecting "10 days from now" for follow-up tasks
+- Choosing "yesterday" for daily reports
+- Setting "30 days ago" as a lookback period start
+- Quick selection of dates like "100 days from today" for long-term planning
+
+### 3. **Date Input in Custom Pages**
+When building custom pages that require date input as part of a form or configuration interface.
+
+**Example Scenarios**:
+- Configuration dialogs requiring date parameters
+- Custom workflow forms with date fields
+- Dashboard filters with date selection
+- Test pages demonstrating date picker functionality
+
+### 4. **Default Date with User Override**
+When a default date should be suggested but users need the ability to change it easily.
+
+**Example Scenarios**:
+- Forms pre-filled with "today" that can be adjusted
+- Date fields with calculated defaults (e.g., project end date based on duration)
+- Reset functionality to quickly return to the default value
+
+---
+
+## Configuration Concepts
+
+### Main Configuration Options
+
+#### 1. **Visual Customization**
+- **`icon`**: FontAwesome icon displayed on the button (default: `fa-calendar` if no label)
+- **`iconClass`**: CSS class for the icon (default: `fa`)
+- **`label`**: Text label displayed on the button
+
+#### 2. **Default Values**
+- **`default`**: Default date when the picker is initialized
+  - Can be set to `null`, a Date object, or special strings like `"today"`
+  - Used as the reset target when user clicks the reset button
+- **`defaultRef`**: Date object as default value (only used if `defaultString` not set)
+- **`defaultString`**: String representation of default date (takes precedence over `defaultRef`)
+
+#### 3. **Picker Behavior**
+- **`pickerOptions`**: Options passed directly to the underlying bootstrap-datepicker
+  - Language settings (e.g., `de-DE`)
+  - Calendar title
+  - Start/end date restrictions
+  - Calendar week display
+  - Date formatting options
+
+**Important Limitations**:
+- Options restricting selectable dates (like `startDate` or `daysOfWeekDisabled`) are not fully compatible with relative date pickers
+- Multidate settings are not supported
+
+#### 4. **Relative Dates**
+- **`relativeDates`**: Enables quick selection of dates relative to today
+  - `false` or omitted: No relative date shortcuts
+  - `true`: Shows default relative date list
+  - Array (e.g., `[-100, -10, 10, 100]`): Custom list of day offsets
+  - String (e.g., `"1,2,3,4,5"`): Comma-separated list of day offsets
+
+**Examples**:
+- `relativeDates="[-30, -7, 0, 7, 30]"` → Buttons for "30 days ago", "7 days ago", "today", "7 days from now", "30 days from now"
+- `relativeDates="true"` → Default set of relative dates
+
+---
+
+## How It Works
+
+### User Interaction Flow
+
+1. **Initial State**: Button displays with icon/label and current date value (if set)
+2. **Opening**: User clicks button → Dropdown opens showing calendar picker
+3. **Date Selection**: User can either:
+   - Click a date in the calendar
+   - Click a relative date button (if configured)
+   - Manually type a date in the input field
+4. **Visual Feedback**:
+   - Button shows "changed" state if date differs from default
+   - Reset icon (×) appears when changed, allowing one-click reset
+   - Invalid dates show warning icon with error message
+5. **Model Update**: Selected date is stored as a Date object at midnight local time
+
+### Data Handling
+
+**Model Value**:
+- Type: `Date | null`
+- Valid values: `null` or valid Date objects
+- Date represents midnight in local time (e.g., for Germany, corresponds to 23:00:00 UTC on previous day)
+
+**Validation**:
+- Built-in validator ensures model is either `null` or a valid Date object
+- Invalid dates trigger error display in the button
+
+**Date Format**:
+- Display uses localized format via `tlfDate` filter
+- Internal picker format: `<day>/<month>/<year>`
+
+---
+
+## Relationships to Other Components
+
+### Part of Toolbar Widget Family
+The date picker widget is one of three toolbar widgets provided by the `ToolbarPlugin`:
+1. **DatePickerWidget** (this widget) - Single date selection
+2. **DropDownWidget** - Dropdown selection
+3. **MiscWidget** - Miscellaneous toolbar elements
+
+### Related Date Components in the Module
+
+The widget is built on a hierarchy of components:
+
+```
+datePickerWidget (Widget Definition)
+  └─> tlf-date-picker (Toolbar Button Component)
+       └─> tlf-date-picker-core (Calendar Core)
+            ├─> bootstrap-datepicker (External library)
+            └─> tlf-date-diff (Relative date selection)
+```
+
+**Sibling Components**:
+- **`tlf-date-range-picker`**: For selecting a range between two dates (start and end)
+- **`tlf-date-range-display`**: For displaying date ranges in a formatted way
+
+**Supporting Components**:
+- **`tlf-date-picker-core`**: Low-level calendar picker without toolbar styling
+- **`tlf-date-diff`**: Relative date list component (can be used standalone)
+
+### Dependencies
+- **AngularJS**: Framework for component architecture
+- **bootstrap-datepicker**: Underlying calendar widget ([documentation](https://bootstrap-datepicker.readthedocs.io/en/v1.5.1/))
+- **FontAwesome**: For icons
+
+---
+
+## Implementation Notes
+
+### When to Use This Widget
+
+**Choose DatePickerWidget when**:
+- You need a single date selection in a toolbar or form
+- A calendar interface improves usability over text input
+- You want visual feedback for changed/invalid states
+- Users benefit from relative date shortcuts
+
+**Consider alternatives when**:
+- You need a date range (use `tlf-date-range-picker` instead)
+- You only need the calendar without toolbar styling (use `tlf-date-picker-core`)
+- You're building a pure relative date selector (use `tlf-date-diff`)
+
+### Key Technical Considerations
+
+1. **Date at Midnight**: All dates are normalized to midnight local time
+2. **Validation**: Built-in validation for Date objects (null or valid Date only)
+3. **Reset Behavior**: Widget tracks changes from default and allows reset
+4. **Relative Dates Limitation**: Date restrictions in picker options may not work correctly with relative date buttons
+5. **Multidate Not Supported**: Only single date selection is supported
+
+### Test Setup
+The widget includes a comprehensive test setup handler (`TestSetupHandler.java:24`) that demonstrates:
+- Different configuration combinations
+- Various relative date options
+- Label and icon variations
+- Default value handling
+- Invalid date handling
+
+The test page (`datePickerWidgetDefinition.htm`) shows extensive examples of all features.
+
+---
+
+## Code References
+
+**Key Files**:
+- Widget Definition: `de/toolforge/toolbar/widgets/DatePickerWidgetDefinition.java:17`
+- Main Component: `de.toolforge.toolbar/assets/ts/tlf-datepickers/tlf-date-picker/tlf-date-picker.component.ts:44`
+- Controller: `de.toolforge.toolbar/assets/ts/tlf-datepickers/tlf-date-picker/tlf-date-picker.controller.ts:6`
+- Template: `de.toolforge.toolbar/assets/ts/tlf-datepickers/tlf-date-picker/tlf-date-picker.template.html:1`
+- Core Calendar: `de.toolforge.toolbar/assets/ts/tlf-datepickers/core/tlf-date-picker-core.component.ts:34`
+- Module: `de.toolforge.toolbar/assets/ts/tlf-datepickers/tlf-datepickers.module.ts:22`
+
+**Plugin Integration**: `de/toolforge/toolbar/ToolbarPlugin.java:45`