@cplace/test-mcp-server 0.1.15 → 1.1.0

package/dist/widget-specifications/_research_from_ga_products/cf-cplace-visualizations-scriptingLineChart/research.md

@@ -0,0 +1,279 @@
+# Widget Research: cf.cplace.visualizations.scriptingLineChart
+
+## Widget Overview
+
+**Widget ID:** `cf.cplace.visualizations.scriptingLineChart`
+
+**Widget Name:** cplaceJS based Line Chart
+
+**Repository:** cplace-paw
+
+**Module:** cf.cplace.scriptingVisualizations
+
+## Description
+
+The cplaceJS based Line Chart widget enables users to create interactive line chart visualizations using custom JavaScript code (cplaceJS) within cplace. It provides programmatic access to the Highcharts API, allowing for dynamic data visualization based on search results or page data.
+
+## Purpose
+
+This widget allows administrators and power users to build custom line chart visualizations by writing JavaScript code that processes page data and returns formatted series data for rendering. Unlike configuration-based widgets, this widget provides full programmatic control over data transformation and chart series generation through cplaceJS scripting.
+
+## Core Functionality
+
+### Key Characteristics
+
+1. **Script-Based Data Generation**: The widget executes custom cplaceJS code to generate chart series data dynamically
+2. **Search Integration**: Can query pages using the integrated search configuration
+3. **Highcharts-Powered**: Leverages the Highcharts library for rendering interactive line charts
+4. **Time-Based Visualization**: Designed for displaying time-series data with built-in timeframe filtering
+5. **Customizable Appearance**: Supports custom colors, legends, tooltips, and date formatting
+
+### Technical Implementation
+
+The widget extends `LineChartWidgetDefinition` and overrides the `getSeries()` method to:
+- Execute custom cplaceJS code provided in the widget configuration
+- Provide bindings to the script:
+  - `pages`: Iterable of pages from the search results (wrapped as WrappedCustomEntity)
+  - `messages`: Message provider for the embedding page's type definition
+- Return a JSONArray in Highcharts series format
+
+**Key Code Location:**
+`ScriptingLineChartWidgetDefinition.java:56-92`
+
+## Configuration Options
+
+### Required Configuration
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| **SCRIPT** | SingleStringAttributeDef | cplaceJS code that generates the series data. Must return an array in Highcharts series format |
+| **SEARCH** | SingleStringAttributeDef | Search configuration to find pages. Results are available as `pages` binding in the script |
+
+### Optional Configuration
+
+| Attribute | Type | Default | Description |
+|-----------|------|---------|-------------|
+| **LOCALIZED_TITLE** | SingleLocalizedStringAttributeDef | - | Localized widget title |
+| **LABEL** | SingleStringAttributeDef | - | Y-axis label text |
+| **HEIGHT** | SingleNumberAttributeDef | - | Fixed height for the widget in pixels |
+| **DEFAULT_TIMEFRAME** | SingleNumberAttributeDef | 3 | Default timeframe in months (0, 3, 6, or 12) |
+| **SHOW_LEGEND** | SingleBooleanAttributeDef | true | Show/hide the chart legend |
+| **SHOW_TOOLTIPS** | SingleBooleanAttributeDef | false | Enable/disable tooltips on data points |
+| **SHOW_TIMEFRAMES** | SingleBooleanAttributeDef | true | Show/hide timeframe selector buttons |
+| **COLORS** | MultiStringAttributeDef | - | Custom color palette for series (hex color codes) |
+| **DATE_FORMAT** | SingleStringAttributeDef | - | Custom date format string for x-axis labels |
+| **LEGEND_POSITION** | SingleStringAttributeDef | "bottom" | Legend position: "bottom" or "right" |
+
+**Configuration Type Definition Location:**
+`ScriptingVisualizationsWidgetTypes.java:33-86`
+
+## Use Cases
+
+### When to Use This Widget
+
+1. **Custom Data Transformation**: When you need to aggregate, calculate, or transform page data before visualizing it as a line chart
+2. **Complex Business Logic**: When chart data requires business logic that cannot be expressed through configuration alone
+3. **Dynamic Series Generation**: When the number or nature of chart series depends on runtime data
+4. **Advanced Calculations**: When you need to compute trends, moving averages, or other derived metrics
+5. **Multi-Source Data**: When combining data from multiple page types or attributes into a single visualization
+
+### Example Scenarios
+
+- **Project Timeline Visualization**: Aggregate project milestones and display progress over time
+- **Resource Utilization Tracking**: Calculate and display resource allocation trends across multiple projects
+- **Performance Metrics Dashboard**: Compute and visualize KPIs based on custom formulas
+- **Budget Burn-Down Charts**: Calculate cumulative spending over time with custom logic
+- **Custom Status Tracking**: Convert status changes into time-series data for trend analysis
+
+### When NOT to Use This Widget
+
+- **Simple Attribute Visualization**: Use the Tuple Line Chart widget (`cf.cplace.visualizations.tupleLineChart`) instead if you just need to display attribute values from tuple data without transformation
+- **No Scripting Requirement**: If configuration-based widgets meet your needs, prefer them for maintainability
+- **Limited JavaScript Knowledge**: This widget requires JavaScript/cplaceJS expertise
+
+## Script Requirements
+
+### Expected Script Output
+
+The cplaceJS script must return a JSONArray in Highcharts series format:
+
+```javascript
+[
+  {
+    id: "series1",
+    name: "Series Name",
+    data: [[timestamp1, value1], [timestamp2, value2], ...]
+  },
+  {
+    id: "series2",
+    name: "Another Series",
+    data: [[timestamp1, value1], [timestamp2, value2], ...]
+  }
+]
+```
+
+### Available Bindings
+
+- **`pages`**: SafeLazyIterable of WrappedCustomEntity objects from the search results
+- **`messages`**: Message provider for the embedding page's type definition (for i18n)
+
+### Script Execution Context
+
+- Scripts are executed using the cplaceJS engine with monitoring/performance tracking
+- Performance threshold: Scripts are monitored for detailed logging
+- Error handling: Script exceptions are caught and displayed as widget errors
+
+**Script Evaluation Location:**
+`ScriptingLineChartWidgetDefinition.java:73-90`
+
+## Related Widgets
+
+### Sibling Widgets in the Same Module
+
+1. **cplaceJS based Highcharts Visualization** (`cf.cplace.visualizations.scriptingHighcharts`)
+   - More generic version that supports any Highcharts chart type
+   - Requires returning full Highcharts configuration instead of just series data
+   - Offers more flexibility but requires more configuration
+
+### Related Widgets in cf.cplace.visualizations Module
+
+1. **Tuple Line Chart** (`cf.cplace.visualizations.tupleLineChart`)
+   - Configuration-based line chart for tuple attributes
+   - No scripting required
+   - Best for simple attribute visualization from tuple data
+
+2. **Base Line Chart** (`cf.cplace.visualizations.lineChart`)
+   - Base widget definition class
+   - Provides core line chart rendering functionality
+   - Both Scripting Line Chart and Tuple Line Chart extend this
+
+### Widget Hierarchy
+
+```
+LineChartWidgetDefinition (abstract base)
+├── ScriptingLineChartWidgetDefinition (script-based, flexible)
+└── TupleLineChartWidgetDefinition (config-based, simpler)
+```
+
+## Technical Details
+
+### Frontend Components
+
+- **Directive**: Uses the shared `cfCplaceLineChartVisualizationWidget` directive
+- **Controller**: `LineChartWidgetCtrl` (extends `AbstractHighchartsWidgetCtrl`)
+- **Frontend Location**: `cf.cplace.visualizations/assets/ts/directives/lineChartDirective.ts`
+
+### Features Provided by Frontend
+
+- Interactive timeframe selection (show all, or filter by months)
+- Show/hide all series buttons
+- Responsive chart resizing
+- Custom date formatting
+- Label value transformation support
+- Legend positioning (bottom/right)
+
+### Data Flow
+
+1. Widget configuration is loaded with search and script
+2. Backend executes search to find pages
+3. cplaceJS script is evaluated with `pages` and `messages` bindings
+4. Script returns series array in Highcharts format
+5. Series data is filtered by selected timeframe (client-side)
+6. Highcharts renders the visualization
+
+### Error Handling
+
+- **Script Errors**: ScriptException and TypeConversionException are caught and displayed as widget errors
+- **Missing Series**: If series is not set, an error is thrown
+- **Invalid Data**: If series array cannot be converted to JSONArray, an error is displayed
+
+## Prerequisites & Dependencies
+
+### Required Knowledge
+
+- JavaScript/cplaceJS programming
+- Understanding of Highcharts series data format
+- cplace search API knowledge
+- Understanding of the cplace data model
+
+### Plugin Dependencies
+
+- **cf.cplace.visualizations**: Provides base LineChartWidgetDefinition class
+- **Highcharts Library**: JavaScript charting library (included in cplace platform)
+- **cplaceJS Engine**: For executing custom scripts
+
+### Module
+
+- Part of the `cf.cplace.scriptingVisualizations` module
+- Plugin class: `ScriptingVisualizationsPlugin`
+- Must be activated: Implements `MustBeActivated` interface
+
+## Migration & Compatibility
+
+### Title Migration
+
+The widget supports migration from unlocalized to localized titles:
+- Legacy `TITLE` attribute (SingleStringAttributeDef) - deprecated
+- Current `LOCALIZED_TITLE` attribute (SingleLocalizedStringAttributeDef)
+- Migration occurs when widget configuration is edited
+
+**Migration Code Location:**
+`ScriptingLineChartWidgetDefinition.java:137-139`
+
+## Contextual Help
+
+The widget provides contextual help when configuring the script attribute:
+- Describes the purpose: "cplaceJS for Line Chart allows for interactive Line charts to be used inside cplace"
+- Explains available bindings (`messages`, `pages`)
+- Provides guidance on expected series array format
+
+**Contextual Help Location:**
+`ScriptingLineChartContextualHelp.java`
+
+## Key Differences from Other Line Chart Widgets
+
+| Feature | Scripting Line Chart | Tuple Line Chart |
+|---------|---------------------|------------------|
+| Data Source | Custom cplaceJS script | Tuple attribute configuration |
+| Flexibility | High - full programmatic control | Low - configuration only |
+| Complexity | Requires JavaScript knowledge | Simple configuration |
+| Use Case | Complex transformations, calculations | Direct attribute visualization |
+| Setup Effort | Higher - write and test script | Lower - select attributes |
+| Maintainability | Lower - custom code | Higher - declarative config |
+
+## Performance Considerations
+
+- Scripts are executed server-side on widget load
+- Performance monitoring is enabled with detailed logging threshold
+- Widget ID is used in monitoring: `cplaceJS.lineChartEvaluation.{widgetId}`
+- Consider optimizing scripts for large datasets
+- Client-side timeframe filtering reduces initial data load
+
+## Best Practices
+
+1. **Script Optimization**: Keep scripts efficient, especially when processing many pages
+2. **Error Handling**: Test scripts thoroughly with various data scenarios
+3. **Date Format**: Use timestamps (milliseconds since epoch) for x-axis data points
+4. **Series IDs**: Provide unique IDs for each series for proper rendering
+5. **Data Sorting**: Pre-sort data points by timestamp for better chart performance
+6. **Timeframe Support**: Include all data in series; frontend will filter by timeframe
+7. **Testing**: Use the test setup handlers for development and testing
+
+## Related Files
+
+### Backend
+- Definition: `cf.cplace.scriptingVisualizations/src/main/java/cf/cplace/scriptingVisualizations/script/ScriptingLineChartWidgetDefinition.java`
+- Types: `cf.cplace.scriptingVisualizations/src/main/java/cf/cplace/scriptingVisualizations/ScriptingVisualizationsWidgetTypes.java`
+- Help: `cf.cplace.scriptingVisualizations/src/main/java/cf/cplace/scriptingVisualizations/script/ScriptingLineChartContextualHelp.java`
+- Plugin: `cf.cplace.scriptingVisualizations/src/main/java/cf/cplace/scriptingVisualizations/ScriptingVisualizationsPlugin.java`
+
+### Frontend
+- Controller: `cf.cplace.visualizations/assets/ts/directives/lineChartDirective.ts`
+
+### Localization
+- English: `cf.cplace.scriptingVisualizations/src/main/resources/cf/cplace/scriptingVisualizations/messages_en.properties`
+- German: `cf.cplace.scriptingVisualizations/src/main/resources/cf/cplace/scriptingVisualizations/messages_de.properties`
+
+## Summary
+
+The **cplaceJS based Line Chart** widget is a powerful tool for creating custom time-series visualizations in cplace. It bridges the gap between configuration-based widgets and fully custom implementations by allowing JavaScript code to transform and prepare data while leveraging the robust Highcharts rendering engine and pre-built line chart UI components. It's ideal for scenarios requiring business logic, data aggregation, or complex calculations before visualization, making it a key tool for advanced cplace customization.

package/dist/widget-specifications/_research_from_ga_products/cf-cplace-visualizations-tupleLineChart/research.md

@@ -0,0 +1,221 @@
+# Tuple Line Chart Widget Research
+
+## Widget Information
+- **Widget ID**: `cf.cplace.visualizations.tupleLineChart`
+- **Widget Name**: Tuple Line Chart
+- **Repository**: `cplace-paw`
+- **Definition Class**: `cf.cplace.visualizations.script.TupleLineChartWidgetDefinition`
+- **Parent Class**: `LineChartWidgetDefinition`
+
+## Description
+
+The Tuple Line Chart widget visualizes time-series data stored in tuple entities by displaying numeric or enumeration values over time in a line chart format. It enables users to track and compare multiple data points across tuple collections attached to pages, making it ideal for monitoring trends, progressions, and changes in associated tuple data.
+
+## Purpose
+
+This widget is specifically designed to work with cplace's tuple concept - a lightweight data structure that represents a collection of related attribute values. The widget:
+
+1. **Extracts data from tuple references**: It reads tuple entities that are referenced by a main page through a reference attribute
+2. **Plots time-series data**: It takes date and value attributes from these tuples to create line chart visualizations
+3. **Supports multiple value series**: It can display multiple attributes from the same tuple type simultaneously
+4. **Handles both numeric and enumeration data**: It supports number attributes and enumeration attributes (with optional icons)
+
+## Use Cases
+
+### 1. Tracking Numeric Values Over Time
+**Example: Vehicle Kilometrage Tracking**
+- A "Vehicle" page has a reference to multiple "Kilometrage" tuples
+- Each tuple contains:
+  - Date attribute: when the reading was taken
+  - Numeric attributes: actual kilometers, projected kilometers
+- The widget displays both the actual and projected kilometrage over time on the same chart
+
+**When to use**: When you need to track quantitative measurements or metrics that change over time for an entity.
+
+### 2. Monitoring Status Changes
+**Example: Vehicle Inspection Status**
+- A "Vehicle" page has a reference to multiple "TÜV Status" tuples
+- Each tuple contains:
+  - Date attribute: when the inspection occurred
+  - Enumeration attributes: status (passed/failed), projected status
+- The widget displays status changes as enumeration values (with icons like traffic lights)
+
+**When to use**: When you need to track categorical states or statuses that change over time for an entity.
+
+### 3. Comparing Multiple Metrics
+**Example: Multi-Series Analysis**
+- Display multiple related measurements from the same tuple
+- Example: Track both actual and projected values to compare expectations vs. reality
+- Example: Monitor multiple performance indicators from the same data collection
+
+**When to use**: When you need to compare related data points from the same time-series data source.
+
+### 4. Page-Specific vs. Search-Based Visualization
+
+The widget supports two modes:
+
+**Embedded Mode (Single Page)**:
+- Widget is embedded directly on a page
+- Displays tuple data from that specific page only
+- Shows multiple series for different tuple value attributes
+- Use case: Detail page showing historical data for one entity
+
+**Search Mode (Multiple Pages)**:
+- Widget uses a search query to find multiple pages
+- Creates separate series for each page
+- If multiple value attributes are selected, creates combined series (e.g., "Page Name (Attribute)")
+- Use case: Dashboard or overview page comparing data across multiple entities
+
+## Core Concepts
+
+### Tuple Structure
+A tuple is a special type in cplace marked with `.asTuple()`. It represents a data point with:
+- A date attribute (for temporal positioning)
+- One or more value attributes (numeric or enumeration)
+- Typically used in multi-reference attributes to create collections
+
+### Configuration Elements
+
+#### 1. Search Configuration
+- **Search**: Optional search query to define which pages to visualize
+- If empty, uses the embedding page itself
+
+#### 2. Tuple Attribute Selection
+- **Tuple Attribute**: The reference attribute on the main entity that points to tuple entities
+- Must reference exactly one tuple type
+- Example: "kilometerStaende" attribute on "Fahrzeug" type
+
+#### 3. Date Attribute
+- **Tuple Date**: The date attribute within the tuple type
+- Defines the X-axis (time dimension)
+- Must be a date attribute with day specificity
+
+#### 4. Value Attributes
+- **Tuple Values**: One or more attributes from the tuple to visualize
+- Can be:
+  - **Number attributes**: Displayed as continuous values
+  - **Enumeration attributes**: Displayed as discrete categorical values (with optional icons)
+- All selected value attributes must be of the same type (all numeric or all enum)
+- If enum, all must share the same enumeration elements
+
+#### 5. Chart Customization
+Standard line chart options:
+- **Title**: Localized widget title
+- **Label (Y-Axis)**: Label for the vertical axis
+- **Colors**: Custom color palette for series
+- **Show Legend**: Toggle legend visibility
+- **Legend Position**: Bottom or right
+- **Show Tooltips**: Enable/disable data point tooltips
+- **Show Timeframes**: Enable timeframe selection (3m, 6m, 12m, all)
+- **Default Timeframe**: Default time window (0, 3, 6, or 12 months)
+- **Date Format**: Custom date formatting for X-axis
+- **Height**: Fixed widget height
+
+## Technical Details
+
+### Data Validation
+
+The widget performs extensive validation:
+
+1. **Unique Tuple Type**: The tuple attribute must reference exactly one tuple type
+2. **Valid Tuple Type**: The referenced type must be marked as a tuple (`.isTuple()`)
+3. **Valid Date Attribute**: The date attribute must exist in the tuple type
+4. **Valid Value Attributes**: All value attributes must exist and be valid
+5. **Consistent Types**: All value attributes must be either all numeric or all enumeration
+6. **Consistent Enum Elements**: If using enumerations, all must have identical element sets
+
+Error messages guide users through configuration issues.
+
+### Data Processing
+
+**Series Generation**:
+1. For each page found by the search (or the embedding page):
+   - Retrieve all tuple entities via the tuple attribute
+   - For each tuple:
+     - Extract the date value (X coordinate)
+     - Extract each value attribute (Y coordinates)
+     - Create data points [timestamp, value]
+
+2. Series organization:
+   - **Single Page Mode**: One series per value attribute
+     - Series name: Attribute label
+   - **Multi-Page Mode with single value**: One series per page
+     - Series name: Page name
+   - **Multi-Page Mode with multiple values**: One series per page-attribute combination
+     - Series name: "Page Name (Attribute Label)"
+
+**Enumeration Handling**:
+- Enum values are converted to numeric indices (reversed order)
+- Icons are rendered in tooltips and Y-axis labels
+- Labels are mapped from numeric values to display strings/icons
+
+### Parent Class: LineChartWidgetDefinition
+
+The TupleLineChartWidgetDefinition extends `LineChartWidgetDefinition`, which provides:
+- Base line chart rendering using Highcharts
+- Common chart configuration (colors, legend, tooltips, timeframes)
+- Abstract methods for series generation that the tuple version implements
+- Widget template substitution and rendering
+
+### Frontend Implementation
+
+The widget uses:
+- **TypeScript Controller**: `LineChartWidgetCtrl` (shared with base line chart)
+- **Library**: Highcharts for chart rendering
+- **Features**:
+  - Interactive legend
+  - Timeframe selection buttons
+  - Show/hide all series buttons
+  - Responsive design
+  - Custom value formatters for enumerations
+
+## Relationship to Other Widgets
+
+### Comparison with Base Line Chart
+- **Base LineChart**: Generic line chart that works with any search results and date attributes
+- **Tuple LineChart**: Specialized for tuple references, extracts nested tuple data
+
+### Part of Visualizations Plugin
+The widget is part of the `cf.cplace.visualizations` plugin which provides various chart widgets for data visualization.
+
+## Prerequisites
+
+To use this widget:
+1. A custom type must be defined as a tuple (using `.asTuple()`)
+2. The tuple type must have:
+   - At least one date attribute
+   - At least one numeric or enumeration attribute
+3. A main entity type must have a multi-reference attribute pointing to the tuple type
+4. Pages of the main entity type must have tuple instances created and referenced
+
+## Migration Support
+
+The widget includes migration support for:
+- Attribute name changes
+- Type migrations
+- Configuration updates
+- Preserves data when custom types are modified
+
+## Example Configuration (from Test Data)
+
+**Scenario**: Vehicle with Kilometrage Tracking
+
+```
+Main Type: Fahrzeug (Vehicle)
+Tuple Type: Kilometerstand (Kilometrage)
+- Datum (Date): Date of reading
+- Kilometer (Number): Actual kilometers
+- Projected Kilometer (Number): Expected kilometers
+
+Widget Configuration:
+- Tuple Attribute: "kilometerStaende"
+- Tuple Date: "datum"
+- Tuple Values: ["kilometer", "projectedKilometer"]
+- Label: "Kilometerstand"
+```
+
+This creates a line chart showing both actual and projected kilometrage over time for a specific vehicle.
+
+## Summary
+
+The Tuple Line Chart widget is a specialized visualization tool for time-series data stored in cplace tuple entities. It excels at displaying trends and progressions for structured, temporal data attached to pages, supporting both numeric and categorical values with rich configuration options. It's particularly valuable for tracking metrics, monitoring status changes, and comparing projected vs. actual values over time.