@cplace/test-mcp-server 0.1.15 → 1.1.0

package/dist/widget-specifications/_research_from_ga_products/cf-cplace-platform-tableWidget/research.md

@@ -0,0 +1,427 @@
+# Table Widget Research (cf.cplace.platform.tableWidget)
+
+## Overview
+
+**Widget ID:** `cf.cplace.platform.tableWidget`
+**Repository:** `main` (cf.cplace.platform)
+**Definition Class:** `cf.cplace.platform/src/main/java/cf/cplace/platform/frontend/widgets/TableWidgetDefinition.java`
+**Icon:** `fa-table`
+**Status:** Beta (requires feature flag `newTableEnabled`)
+
+## Purpose
+
+The Table Widget is a next-generation table display widget that presents search results in a tabular format with advanced features like sorting, filtering, column configuration, and widget connectivity. It serves as a data producer for connected widgets by providing search results and single entity selections.
+
+## Description
+
+The Table Widget displays search results in an interactive, configurable table format. It allows users to view, sort, filter, and organize data with support for multi-column sorting, customizable columns, and dynamic filtering. The widget can act as a data source for other widgets through the connected widget system.
+
+## Core Functionality
+
+### 1. Search & Data Display
+- Executes a configured search and displays results in a table format
+- Supports all search types defined in the cplace platform
+- Presents data in rows and columns with customizable column visibility
+- Provides "no padding" layout for optimal space utilization (`isNoPadding() = true`)
+
+### 2. Widget Producer Capabilities
+The Table Widget implements three producer interfaces, making it a powerful data source:
+
+- **ISearchProducer**: Provides search results to connected widgets
+  - Returns `SearchWithPermissions` with effective table settings applied
+  - Includes execution mode for proper permission handling
+  - Accessed via `getSearchWithPermissions()`
+
+- **ISingleEntitySelectionProducer**: Produces single entity selections
+  - Emits currently selected entity to connected widgets
+  - Supported as a connected widget producer type
+
+- **IMultiEntitySelectionProducer**: Produces multiple entity selections
+  - Allows selection of multiple rows/entities
+  - Can broadcast multi-entity selections to consumers
+
+### 3. Connected Widget Support
+- Can connect to other widgets via `CONNECTED_WIDGET_ID` configuration
+- Supports connections to `ISingleEntitySelectionProducer` widgets
+- Enables master-detail relationships with other widgets
+- Emits table refresh events (`TABLE_REFRESH`, `TABLE_DATA_CHANGED`) for consumer widgets
+
+### 4. Feature Flag Requirement
+- Requires `newTableEnabled` feature flag to be active
+- Throws `NotEmbeddableException` if feature is disabled: "The New Table widget is not enabled."
+- Check performed in `checkShowInSelection()` method
+
+## Configuration Options
+
+The widget configuration is defined in `WidgetTypes.TABLE_WIDGET` and includes:
+
+### Required Configuration
+
+1. **SEARCH** (`SingleStringAttributeDef`)
+   - **Attribute Name:** `search`
+   - **Purpose:** Defines the search query that populates the table
+   - **Type:** Search constraint
+   - **Multiplicity:** Exactly one
+   - **Details:** Core configuration that determines what data is displayed
+
+### Optional Configuration
+
+2. **LOCALIZED_TITLE** (`SingleLocalizedStringAttributeDef`)
+   - **Attribute Name:** `title`
+   - **Purpose:** Widget title displayed to users
+   - **Type:** Localized string
+   - **Multiplicity:** At most one
+   - **Default:** Falls back to widget name message if not provided
+
+3. **COLUMNS** (`SingleStringAttributeDef`)
+   - **Attribute Name:** `columns`
+   - **Purpose:** Defines which columns are visible and their order
+   - **Type:** Search columns constraint
+   - **Multiplicity:** At most one
+   - **Details:** Controls column visibility and arrangement
+
+4. **FILTERS** (`SingleStringAttributeDef`)
+   - **Attribute Name:** `filters`
+   - **Purpose:** Defines filter configurations for columns
+   - **Type:** Search filters constraint
+   - **Multiplicity:** At most one
+   - **Details:** Pre-configured filters applied to the search
+
+5. **MULTI_SORT_COLUMNS** (`SingleStringAttributeDef`)
+   - **Attribute Name:** `multiSortColumns`
+   - **Purpose:** Configures multi-level sorting
+   - **Type:** Custom constraint (FlexigridColumnSortConstraintExtension)
+   - **Multiplicity:** At most one
+   - **Details:** Allows sorting by multiple columns with priority
+
+6. **SHOW_NEW** (`SingleBooleanAttributeDef`)
+   - **Attribute Name:** `showCreateNew`
+   - **Purpose:** Controls visibility of "Create New" button
+   - **Type:** Boolean
+   - **Multiplicity:** Exactly one
+   - **Default:** `true`
+   - **Details:** Enables users to create new entities from the table
+
+7. **PIN_NAME_COLUMN** (`SingleBooleanAttributeDef`)
+   - **Attribute Name:** `pinNameColumn`
+   - **Purpose:** Pins the name/title column for horizontal scrolling
+   - **Type:** Boolean
+   - **Multiplicity:** Exactly one
+   - **Default:** `true`
+   - **Migrated:** Set to `true` automatically during widget configuration migration
+
+8. **CONNECTED_WIDGET_ID** (`SingleStringAttributeDef`)
+   - **Attribute Name:** `connectedWidgetId`
+   - **Purpose:** ID of another table widget to connect with
+   - **Type:** Dynamic string enumeration (ConnectedTableWidgetsEnumerationProvider)
+   - **Multiplicity:** At most one
+   - **Details:** Establishes master-detail relationships between widgets
+
+## Use Cases
+
+### 1. Primary Data Display
+**When to use:** Need to display search results in a structured table format
+
+**Example scenario:**
+- Display all projects in a workspace
+- Show team members with their roles and departments
+- List tasks with status, assignee, and due dates
+
+**Why this widget:**
+- Clean, organized tabular view of data
+- Native sorting and filtering capabilities
+- User-friendly column configuration
+
+### 2. Master Table in Master-Detail Pattern
+**When to use:** One table drives the content of detail widgets
+
+**Example scenario:**
+- Project list table connected to:
+  - Project details widget (shows selected project)
+  - Project team widget (shows team of selected project)
+  - Project timeline widget (shows timeline of selected project)
+
+**Why this widget:**
+- Implements `ISingleEntitySelectionProducer` for single row selection
+- Implements `IMultiEntitySelectionProducer` for multi-row operations
+- Emits selection events to connected widgets
+- Supports `CONNECTED_WIDGET_ID` configuration
+
+### 3. Connected Table (Detail Table)
+**When to use:** Table content depends on selection from another widget
+
+**Example scenario:**
+- Task table that shows tasks for a project selected in a project dropdown
+- Team member table filtered by department selected in a department selector
+
+**Why this widget:**
+- Can connect to selection producers via `CONNECTED_WIDGET_ID`
+- Automatically updates when connected widget selection changes
+- Provides filtered view based on parent context
+
+### 4. Search Result Provider
+**When to use:** Need to provide search results to other widgets (charts, metrics, etc.)
+
+**Example scenario:**
+- Table showing filtered issues
+- Connected pie chart showing issue distribution by status
+- Connected bar chart showing issues by priority
+- Connected metrics showing total count
+
+**Why this widget:**
+- Implements `ISearchProducer` interface
+- Provides `SearchWithPermissions` to consumers
+- Allows multiple connected widgets to visualize the same data set
+- Handles permissions and execution mode properly
+
+### 5. Multi-Column Sorted Lists
+**When to use:** Complex sorting requirements with multiple sort criteria
+
+**Example scenario:**
+- Employee list sorted by department (primary), then by seniority (secondary), then by name
+- Product catalog sorted by category, then by price, then by rating
+
+**Why this widget:**
+- Supports `MULTI_SORT_COLUMNS` configuration
+- Allows users to configure multi-level sorting
+- Maintains sort order across refreshes
+
+### 6. Filtered Data Views
+**When to use:** Pre-configured filters need to be applied to data
+
+**Example scenario:**
+- "My Open Tasks" table with pre-filtered view
+- "High Priority Issues" table showing only urgent items
+- "This Month's Activities" with date range filter
+
+**Why this widget:**
+- Supports `FILTERS` configuration
+- Combines search definition with filter criteria
+- Users can add additional filters on top of pre-configured ones
+
+## Related Components
+
+### Backend Components
+
+1. **TableWidgetState** (`cf.cplace.platform.frontend.rest.table.widget.TableWidgetState`)
+   - Record holding widget state: `tableParameters` and `connectedWidgetId`
+   - Used for client-server communication
+   - Serialized to JSON in widget template
+
+2. **TableWidgetTable** (`cf.cplace.platform.frontend.rest.table.widget.TableWidgetTable`)
+   - Implementation of the table data provider
+   - Loads search, columns, filters, and sort configuration
+   - Identified by `TABLE_WIDGET_TABLE_IDENTIFIER`
+
+3. **TableWidgetTableParameters** (`cf.cplace.platform.frontend.rest.table.widget.TableWidgetTableParameters`)
+   - Contains `widgetId` and `embeddingPageUid`
+   - Used to uniquely identify table instance
+
+4. **Table Registry** (`PlatformComponentRegistry.getTableRegistry()`)
+   - Central registry for table instances
+   - Returns `Table` objects via `TableIdentifier`
+
+### Frontend Components
+
+The widget uses a web component bridge pattern:
+
+1. **Template:** `tableWidgetDefinition.htm`
+   - Loads `cf-wc-bridge` web component
+   - Routes to "table-widget" component in "cf-platform" module
+   - Passes widget state as JSON via `data` attribute
+
+2. **Expected Frontend Module:** `cf-platform` (remote)
+   - Route: `table-widget`
+   - Receives state object with `tableParameters` and `connectedWidgetId`
+
+### Connected Widget Interfaces
+
+1. **IConnectedWidgetProducer** (parent interface)
+   - Base interface for all producer widgets
+   - Defines producer capabilities
+
+2. **ConnectedTableWidgetsEnumerationProvider**
+   - Provides enumeration of available table widgets on the page
+   - Used by `CONNECTED_WIDGET_ID` attribute
+   - Enables widget-to-widget connections
+
+3. **SingleSelectionWidgetEnumerationProvider**
+   - Provides enumeration of widgets producing single selections
+   - Used by consumer widgets to find compatible producers
+
+## Widget Lifecycle
+
+### Initialization
+1. Widget configuration loaded from page
+2. `migrateWidgetConfiguration()` ensures `PIN_NAME_COLUMN` is set
+3. `checkShowInSelection()` verifies `newTableEnabled` feature flag
+4. `getWidgetState()` creates `TableWidgetState` with parameters
+5. State serialized to JSON in template
+6. Web component bridge loads frontend with state
+
+### Runtime
+1. Frontend requests table data via `TableWidgetTable`
+2. Search executed with effective table settings applied
+3. Table registry returns `Table` instance with search and execution mode
+4. User interactions (sorting, filtering, selection) update table state
+5. Selection changes emit events to connected widgets
+6. Connected widgets receive `SearchWithPermissions` or selection data
+
+## Prerequisites and Dependencies
+
+### Required
+- Feature flag `newTableEnabled` must be active in `UixFeatureConfiguration`
+- Valid search definition in configuration
+- Widget must be embedded in a page (`_embeddedIn()` returns non-null)
+
+### Optional
+- Connected widgets (for producer/consumer pattern)
+- Column and filter configurations (for customized views)
+- Multi-sort configuration (for complex sorting)
+
+## Configuration Migration
+
+The widget includes automatic configuration migration:
+
+```java
+public void migrateWidgetConfiguration(WidgetConfiguration conf, WidgetSubstitutionParameters params) {
+    if (conf.get(WidgetTypes.TABLE_WIDGET.PIN_NAME_COLUMN) == null) {
+        conf.set(WidgetTypes.TABLE_WIDGET.PIN_NAME_COLUMN, true);
+    }
+}
+```
+
+This ensures existing widget instances get the default `PIN_NAME_COLUMN = true` value.
+
+## Comparison with Other Table Widgets
+
+### vs. Embedded Search as Table (EMBEDDED_SEARCH_AS_TABLE)
+
+**Table Widget advantages:**
+- Modern web component architecture (vs. legacy AngularJS)
+- Cleaner producer interface implementation
+- Feature-flagged for controlled rollout
+- Better separation of concerns (state management)
+
+**When to use Table Widget:**
+- New implementations on modern infrastructure
+- When feature flag is enabled
+- For new pages requiring table functionality
+
+**When to use Embedded Search as Table:**
+- Legacy pages still on AngularJS
+- When `newTableEnabled` feature flag is not active
+- Existing implementations that don't need migration
+
+### Key Difference
+The Table Widget is the "next generation" table implementation with improved architecture, while Embedded Search as Table is the established, production-stable version.
+
+## Common Patterns
+
+### Pattern 1: Standalone Table
+```
+Configuration:
+- SEARCH: Define search query
+- COLUMNS: Configure visible columns
+- FILTERS: Optional pre-configured filters
+- SHOW_NEW: Enable/disable create button
+- PIN_NAME_COLUMN: Pin first column
+```
+
+### Pattern 2: Master Table with Details
+```
+Table Widget (Master)
+  ├─ SEARCH: Projects search
+  ├─ SHOW_NEW: true
+  └─ Produces: Single entity selection
+
+Connected Single Attribute Widget (Detail 1)
+  └─ CONNECTED_WIDGET_ID: [Table Widget]
+
+Connected Attributes Group Widget (Detail 2)
+  └─ CONNECTED_WIDGET_ID: [Table Widget]
+```
+
+### Pattern 3: Table with Analytics
+```
+Table Widget (Data Source)
+  └─ SEARCH: Tasks search
+  └─ Produces: Search with permissions
+
+Connected Pie Chart Widget
+  └─ CONNECTED_WIDGET_ID: [Table Widget]
+  └─ Shows: Distribution by status
+
+Connected Bar Chart Widget
+  └─ CONNECTED_WIDGET_ID: [Table Widget]
+  └─ Shows: Count by assignee
+
+Connected Number of Results Widget
+  └─ CONNECTED_WIDGET_ID: [Table Widget]
+  └─ Shows: Total count
+```
+
+### Pattern 4: Hierarchical Tables
+```
+Department Table Widget
+  └─ Produces: Single selection
+
+Employee Table Widget
+  ├─ CONNECTED_WIDGET_ID: [Department Table]
+  └─ SEARCH: Filtered by selected department
+```
+
+## Technical Implementation Details
+
+### Widget State Management
+- State class: `TableWidgetState` (Java record)
+- Contains: `tableParameters` (widgetId, embeddingPageUid), `connectedWidgetId`
+- Serialized: JSON format via `toJson()` method
+- Passed to frontend: Via template substitution in `data` attribute
+
+### Search Integration
+- Search retrieved from: `WidgetTypes.TABLE_WIDGET.SEARCH` configuration
+- Table instance: Created via `TableWidgetTable` with widget parameters
+- Search execution: Through table registry with proper permissions
+- Result: `SearchWithPermissions` with effective table settings applied
+
+### Permission Handling
+- Search execution mode determined by table configuration
+- Permissions applied via `SearchWithPermissions`
+- Execution mode passed to connected widgets
+- Ensures security at data source level
+
+## API References
+
+### Java Classes
+- `cf.cplace.platform.frontend.widgets.TableWidgetDefinition`
+- `cf.cplace.platform.frontend.rest.table.widget.TableWidgetState`
+- `cf.cplace.platform.frontend.rest.table.widget.TableWidgetTable`
+- `cf.cplace.platform.frontend.rest.table.widget.TableWidgetTableParameters`
+- `cf.cplace.platform.frontend.templating.WidgetTypes.TABLE_WIDGET`
+
+### Interfaces
+- `cf.cplace.platform.frontend.rest.shared.widget.ISearchProducer`
+- `cf.cplace.platform.frontend.rest.shared.widget.ISingleEntitySelectionProducer`
+- `cf.cplace.platform.frontend.rest.shared.widget.IMultiEntitySelectionProducer`
+- `cf.cplace.platform.frontend.rest.shared.widget.IConnectedWidgetProducer`
+
+### Template
+- `cf.cplace.platform/src/main/resources/cf/cplace/platform/frontend/widgets/tableWidgetDefinition.htm`
+
+## Additional Notes
+
+1. **Beta Status**: Widget is marked with `@Beta` annotation, indicating it may undergo changes
+2. **Feature Flag**: Critical to verify `newTableEnabled` before using in production
+3. **Web Component**: Uses modern web component architecture for frontend rendering
+4. **No Padding**: Widget requests no padding (`isNoPadding() = true`) for full-width table display
+5. **Title Fallback**: If no custom title provided, falls back to widget name message
+6. **Migration Support**: Automatic migration ensures backward compatibility for `PIN_NAME_COLUMN`
+
+## Future Considerations
+
+- Monitor feature flag status in target environments
+- Plan migration path from EMBEDDED_SEARCH_AS_TABLE if needed
+- Consider performance implications with large datasets
+- Evaluate connected widget patterns for complex page layouts
+- Track API stability as widget matures from Beta status

package/dist/widget-specifications/_research_from_ga_products/cf-cplace-pptexport-pgPreviewWidget/research.md

@@ -0,0 +1,151 @@
+# Widget Research: cf.cplace.pptexport.pgPreviewWidget
+
+## Widget Information
+- **Widget ID**: `cf.cplace.pptexport.pgPreviewWidget`
+- **Widget Name**: Presentation Graphic Schedule Preview
+- **Repository**: `cplace-project-planning`
+- **Plugin**: `cf.cplace.pptexport`
+- **Definition Class**: `cf.cplace.pptexport.script.PgPreviewWidgetDefinition`
+
+## Purpose
+
+The PG Preview Widget displays a preview of Presentation Graphic (PG) exports for project schedules. "PG" stands for "Presentation Graphic" and refers to a visual representation of project schedules (Gantt charts) that can be exported to PowerPoint (PPTX) or PDF formats.
+
+**Short Description (1-2 sentences):**
+This widget generates and displays a visual preview of how project schedules will appear when exported as presentation graphics to PowerPoint or PDF. It provides buttons to configure the presentation layout, refresh the preview, and export to different formats.
+
+## Key Functionality
+
+### Core Features
+1. **Preview Generation**: Generates an image preview of project schedules rendered as presentation graphics
+2. **Export Capabilities**: Allows direct export of schedules to PowerPoint (PPTX) or PDF format
+3. **Configuration Access**: Provides access to the PG configurator for customizing the presentation layout
+4. **Dynamic Updates**: Can automatically refresh when connected to a table widget showing schedules
+
+### What the Widget Displays
+- Visual preview of presentation graphics as paginated images
+- Action buttons for exporting, configuring, and refreshing
+- Error and warning messages when configuration is invalid
+- Loading states while generating previews
+
+## Use Cases
+
+### 1. **Schedule Export Preview**
+Users want to see how their project schedules will look before exporting them to presentations.
+
+**Example Scenario**: A project manager preparing a stakeholder presentation wants to preview how their project Gantt chart will appear in PowerPoint before generating the final export.
+
+### 2. **Direct Schedule Export**
+Users need to quickly export project schedules to PowerPoint or PDF for reporting or presentations.
+
+**Example Scenario**: During a project review meeting, a team lead needs to quickly export the current project schedule as a PDF to share with attendees.
+
+### 3. **Connected Table Integration**
+Users want the preview to automatically update based on schedule selections in a connected table widget.
+
+**Example Scenario**: A portfolio manager has a table listing multiple project schedules and wants to preview different schedules by clicking on rows in the table, with the PG preview automatically updating.
+
+### 4. **Iterative Configuration**
+Users need to refine the visual presentation of schedules by iterating between configuration changes and preview.
+
+**Example Scenario**: A project administrator is setting up a presentation profile with custom colors, column widths, and layout options, using the preview to validate each change.
+
+## Configuration Concepts
+
+### Schedule Selection
+The widget supports multiple ways to select which schedules to preview/export:
+
+1. **Explicit Selection** (`SCHEDULES`): Directly select one or more schedule pages
+2. **Embedding Selection**: Use the schedule from the embedding page
+3. **Search-based Selection** (`SCHEDULE_SEARCH`): Use a search query to find schedules
+   - Can be configured to show only a single schedule or multiple schedules
+   - Supports sorting by custom columns
+4. **Relative Selection** (`RELATIVE_SELECTION`): Select schedules via an attribute on the embedding page
+5. **Connected Table** (`CONNECTED_TABLE_WIDGET`): Select schedules from a connected table widget
+
+### Profile Selection
+Profiles define how the presentation graphic is rendered (layout, colors, columns, etc.). The widget supports:
+
+1. **Explicit Profile** (`PROFILE`): Select a specific PG profile page
+2. **First Schedule Profile**: Use the profile configured in the first selected schedule
+3. **cplace.js Script** (`PROFILE_CPLACE_JS`): Use a script to dynamically determine the profile
+
+### Display Options
+
+#### Preview Visibility
+- **Show Preview** (`SHOW_PREVIEW`): Toggle whether the preview image is displayed
+- **Generate Immediately** (`GENERATE_IMMEDIATELY`): Auto-generate preview on widget load (only if preview is visible)
+
+#### Button Visibility
+The widget can show/hide various action buttons:
+- **Refresh Button** (`BUTTON.REFRESH`): Regenerate the preview
+- **Edit Button** (`BUTTON.EDIT`): Open the PG configurator
+- **Export PDF Button** (`BUTTON.EXPORT_PDF`): Export to PDF format
+- **Export PPTX Button** (`BUTTON.EXPORT_PPTX`): Export to PowerPoint format
+
+#### Visual Customization
+- **Title** (`TITLE`): Custom localized widget title
+- **Show Frame** (`SHOW_FRAME`): Display widget frame with title
+- **Height** (`HEIGHT`): Fixed widget height (or dynamic if not specified)
+
+## Context and Relationships
+
+### Related Types
+- **Schedule Type**: Project schedules (Gantt charts) from the project planning plugin
+- **Profile Type** (`cf.cplace.pptexport.profile`): Configuration pages that define PG layout and styling
+
+### Integration Points
+- **Table Widgets**: Can connect to table widgets to reactively update based on row selection
+- **PG Configurator**: Opens a separate configuration interface for designing the presentation layout
+- **Export Handlers**: Backend handlers that generate PPTX and PDF exports
+
+### Embeddability
+The widget can be embedded in:
+- **Pages** (standalone dashboard widgets)
+- **Type Definitions** (as part of a type layout)
+- **Type Definition Layouts** (custom layouts for types)
+
+### Plugin Ecosystem
+- Part of the `cf.cplace.pptexport` plugin
+- Works with schedules from `cf.cplace.projectPlanning`
+- Uses the external library `cf-cplace-pgpptintegration` for PowerPoint generation
+
+## Technical Details
+
+### Widget Configuration Migrations
+The widget includes migrations for:
+1. **Version 0 → 1**:
+   - Renamed `showWidgetFrame` to `SHOW_FRAME` with improved button visibility controls
+   - Migrated single schedule selection to multi-schedule selection
+   - Added support for single schedule mode in searches
+2. **Version 1 → 2**:
+   - Introduced profile selection grouping to support multiple profile selection strategies
+
+### State Management
+The widget maintains state including:
+- Selected schedules and profile
+- Preview generation settings
+- URLs for various actions (preview, export, configuration)
+- Error and warning messages
+- Connected table widget ID (if applicable)
+
+### Preview Generation Process
+1. Validates configuration (schedules and profile must be selected)
+2. Creates an `ExportConfig` for the selected schedules and profile
+3. Sends request to backend with maximum dimensions for rendering
+4. Receives preview as paginated images
+5. Displays images with navigation controls
+
+## Validation Rules
+
+The widget is considered invalid (cannot generate preview) if:
+- No schedules are selected
+- No profile is selected or profile selection fails
+- Both button bar and preview are hidden (invalid configuration)
+
+## Error Handling
+
+The widget displays different types of messages:
+- **Error Messages**: Critical issues preventing preview generation (e.g., no schedules, no profile, invalid config)
+- **Warning Messages**: Non-critical issues (e.g., exceeding schedule export limits)
+- **Preview Generation Errors**: Backend failures during preview generation