@cplace/test-mcp-server 0.1.15 → 1.1.0

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

@@ -0,0 +1,253 @@
+# Extended Tree Table Widget Research
+
+## Widget Overview
+
+**Widget ID:** `cf.cplace.extendedTreeTableWidget`
+
+**Repository:** `cplace-utility-widgets`
+
+**Definition Class:** `cf.cplace.extendedTreeTableWidget.script.ExtendedTreeTableWidgetDefinition`
+
+**Extends:** `TreeTableWidgetDefinition` (base platform widget)
+
+## Purpose
+
+The Extended Tree Table Widget displays page hierarchies in a table format with advanced filtering, search capabilities, and cross-type support. It visualizes hierarchical relationships between pages of different types while showing their attributes in configurable columns.
+
+## Key Capabilities
+
+Based on the `ExtendedTreeSpecificationHandler` documentation (lines 47-58), the widget provides these extensions beyond the base TreeTableWidget:
+
+1. **Search and hierarchy selection** - Dynamically construct hierarchies based on search criteria
+2. **Column filters** - Filter table data by column values
+3. **Connection with other widgets** - Integration with other widgets for coordinated behavior
+4. **Single spaced attribute** - Compact display option
+5. **Configurable default depth** - Control how many levels are expanded by default
+6. **Color for non-relevant cells** - Visual distinction for cells displaying data from different types (default: #BEBEBE)
+
+## Use Cases
+
+### 1. Multi-Type Hierarchical Structures
+
+The widget excels at displaying complex hierarchies where different page types are organized in parent-child relationships. For example:
+
+- **Project Management:** Program → Project → Task → Subtask
+- **Product Structures:** Product Line → Product → Component → Part
+- **Organizational Structures:** Division → Department → Team → Individual
+- **Document Hierarchies:** Category → Document → Section → Paragraph
+
+The test setup demonstrates a hierarchy with 4 levels:
+- Root → Branch → Subbranch → Leaf
+- Root → Branch → Leaf (alternative path)
+
+### 2. Cross-Type Relationship Visualization
+
+When pages of different types form a hierarchy, attributes may not apply to all types. The widget handles this by:
+- Displaying all attributes from all types in the hierarchy
+- Using a configurable color (default gray) for cells where an attribute doesn't apply to a page's type
+- Allowing users to see the complete picture across heterogeneous hierarchies
+
+### 3. Dynamic Hierarchy Construction
+
+Unlike fixed hierarchies, this widget can:
+- Use search filters to determine which pages participate in the hierarchy
+- Select specific reference attributes that define parent-child relationships
+- Support multiple incoming reference types (e.g., a Leaf can have either Branch or Subbranch as parent)
+
+### 4. Connected Widget Scenarios
+
+The widget can interact with other widgets on the page:
+- **Single Selection Widget Integration:** Display hierarchy starting from a selected page
+- **Dynamic Root Node:** The hierarchy root can be determined by another widget's selection
+- **Coordinated Filtering:** Multiple widgets can share context and filter data together
+
+## Configuration Concepts
+
+### Core Configuration Attributes
+
+From `ExtendedTreeTableWidgetTypes.java` and `WidgetTypes.BASE_TREE_TABLE`:
+
+1. **LOCALIZED_TITLE** - Widget display title (localized)
+
+2. **SEARCH** - Search specification defining:
+   - Which page types participate in the hierarchy
+   - Filters to apply to included pages
+   - The search is used to construct the hierarchy dynamically
+
+3. **ATTRIBUTES** - Multi-value attribute defining parent-child relationships:
+   - Each entry specifies: `{parentType, incomingType, name}`
+   - **parentType:** The type of the parent page
+   - **incomingType:** The type of the child page
+   - **name:** The reference attribute name linking child to parent
+   - Multiple entries support complex hierarchies with different relationship types
+   - Example: `{"parentType":"root","incomingType":"branch","name":"parent"}`
+
+4. **ROOT_NODE** - Optional page reference:
+   - Specifies the starting point for the hierarchy
+   - If not set, uses the embedding page or connected widget selection
+   - Falls back to the page where the widget is embedded
+
+5. **COLUMNS** - Column configuration:
+   - Defines which attributes to display as columns
+   - Inherits from `SEARCH_AS_TABLE_MIXIN`
+   - Automatically includes Name and Type columns
+
+6. **FILTERS** - Column-level filters:
+   - Users can filter table data by attribute values
+   - Persists filter state in widget configuration
+
+7. **DEFAULT_DEPTH** - Number of hierarchy levels to expand initially:
+   - Numeric value (precision 0, meaning integer)
+   - Defaults to 1 if not specified
+   - Minimum value is 0 (show only root)
+
+8. **SINGLE_SPACED** - Boolean flag for compact display:
+   - When true, reduces vertical spacing in the table
+   - Defaults to false
+
+9. **COLOR_NOTRELEVANT** - Color for non-applicable attributes:
+   - Hex color code (e.g., "#BEBEBE")
+   - Applied to cells where the attribute doesn't exist for the page's type
+   - Helps distinguish relevant from irrelevant data in multi-type hierarchies
+
+10. **HEIGHT** - Widget height configuration (optional fixed height)
+
+11. **OPTIONAL_SINGLE_SELECTION_WIDGET_ID** - Widget connection:
+    - ID of another widget to coordinate with
+    - Enables selection-based hierarchy updates
+
+### Configuration Modes
+
+The widget supports three modes for determining the hierarchy root:
+
+1. **Connected Table Selection** - Root determined by selection in another widget
+2. **Configured Root** - Explicitly configured ROOT_NODE attribute
+3. **Embedding Page** - The page where the widget is embedded serves as root
+
+Priority order: Connected Selection > Configured Root > Embedding Page
+
+## Technical Architecture
+
+### Class Hierarchy
+
+```
+WidgetDefinition (platform)
+  ↑
+  TreeTableWidgetDefinition (platform)
+  ↑
+  ExtendedTreeTableWidgetDefinition (this plugin)
+```
+
+### Handler Architecture
+
+```
+TreeSpecificationHandler (platform)
+  ↑
+  ExtendedTreeSpecificationHandler (platform)
+```
+
+The `ExtendedTreeSpecificationHandler` implements:
+- `IDelegatingTableController` - Delegates table operations to `WidgetBasedCustomTableController`
+- Tree node traversal based on configured reference attributes
+- Search-based filtering for hierarchy participation
+
+### Hierarchy Construction Algorithm
+
+From `ExtendedTreeSpecificationHandler.java`:
+
+1. **Root Determination:**
+   - Check for connected table selection
+   - Fall back to configured ROOT_NODE
+   - Fall back to embedding page
+
+2. **Child Discovery (getChildren method, line 327):**
+   - For each node, find the node's type definition
+   - Look up which reference attributes point to this type (from ATTRIBUTES config)
+   - Create search filters for pages with references to the current node
+   - Execute search with filters to find children
+   - Sort children by order index
+
+3. **Parent Discovery (getParents method, line 263):**
+   - Reverse process: find which types can be parents
+   - Read the reference attribute values
+   - Return referenced pages as parents
+
+4. **Column Construction:**
+   - Aggregate all attribute definitions from all participating type definitions
+   - Create column descriptors with names, labels, and widths
+   - Deduplicate columns by name
+
+## Comparison with Base TreeTableWidget
+
+The base `TreeTableWidgetDefinition` is abstract and provides minimal functionality. The Extended Tree Table Widget adds:
+
+1. **Search-based hierarchy construction** vs. fixed hierarchies
+2. **Multi-type support** with visual distinction for non-relevant attributes
+3. **Configurable reference attributes** vs. hardcoded relationships
+4. **Dynamic root node** vs. static root
+5. **Widget connectivity** for coordinated behavior
+6. **Advanced filtering** at both search and column levels
+
+The base widget is essentially a template that requires concrete implementation, while the Extended Tree Table Widget provides a complete, configurable solution.
+
+## Dependencies
+
+**Primary Dependency:**
+- `cf.cplace.platform` (version 25.3.80)
+
+**Plugin Information:**
+- Group: `cf.cplace.utilityWidgets`
+- Repository: `cplace-utility-widgets`
+- No frontend assets (TypeScript, Less, CSS)
+- Pure backend implementation using Java
+
+## Example Usage Scenario
+
+A project management workspace needs to display a program structure:
+
+**Type Hierarchy:**
+- Program (root)
+- Project (references Program via "program" attribute)
+- Workpackage (references Project via "project" attribute)
+- Task (references either Project or Workpackage via "parent" attribute)
+
+**Widget Configuration:**
+```json
+{
+  "search": {"filters": [{"types": ["Program", "Project", "Workpackage", "Task"]}]},
+  "attributes": [
+    {"parentType": "Program", "incomingType": "Project", "name": "program"},
+    {"parentType": "Project", "incomingType": "Workpackage", "name": "project"},
+    {"parentType": "Project", "incomingType": "Task", "name": "parent"},
+    {"parentType": "Workpackage", "incomingType": "Task", "name": "parent"}
+  ],
+  "defaultDepth": 2,
+  "singleSpaced": false,
+  "colorNotRelevant": "#EEEEEE"
+}
+```
+
+**Result:**
+- Tree table showing the full structure
+- Columns for all attributes across all four types
+- Gray cells where an attribute doesn't apply (e.g., project-specific attributes shown on Tasks)
+- Two levels expanded by default
+- Users can expand/collapse, filter, and navigate the hierarchy
+
+## Related Widgets
+
+- **TreeTableWidget** (base platform widget) - Abstract base class
+- **Search Widget** - Provides search functionality that this widget extends
+- **Connected Table Widgets** - Can coordinate with Extended Tree Table for dynamic root selection
+
+## Key Messages (Internationalization)
+
+From `messages_en.properties`:
+
+- **App Description:** "A widget which can show a page hierarchy in a table."
+- **App Display Name:** "Extended Tree Table Widget"
+- **Widget Name:** "Extended Tree Table Widget"
+
+## Summary
+
+The Extended Tree Table Widget is a sophisticated hierarchical visualization tool designed for complex, multi-type page structures in cplace. It combines tree navigation with table-based attribute display, supports dynamic hierarchy construction through searches, and handles heterogeneous type hierarchies gracefully. The widget is particularly valuable when visualizing cross-type relationships where not all attributes apply to all types, providing clear visual distinction for irrelevant data while maintaining a unified view of the entire hierarchy.

package/dist/widget-specifications/_research_from_ga_products/cf-cplace-formsWizard-horizontalDivider/research.md

@@ -0,0 +1,261 @@
+# Widget Research: cf.cplace.formsWizard.horizontalDivider
+
+**Research Date:** 2026-01-16
+**Widget ID:** `cf.cplace.formsWizard.horizontalDivider`
+**Repository:** `cplace-forms-wizard`
+**Definition Class:** `cf.cplace.formsWizard/src/main/java/cf/cplace/formsWizard/script/HorizontalDividerWidgetDefinition.java`
+
+---
+
+## 1. Widget Purpose
+
+### Short Description
+The Horizontal Divider widget is a simple visual layout element that renders a horizontal line (`<hr>` HTML element) to create visual separation between groups of attributes or form sections within an Attributes Group widget.
+
+### Core Functionality
+- **Visual Separator:** Provides a visual divider line to separate sections within form layouts
+- **Layout Enhancement:** Improves readability by visually grouping related attributes
+- **No Configuration:** Pure presentation widget with no configurable properties or interactive behavior
+- **Minimalist Design:** Renders a single HTML `<hr>` element with no additional markup or styling
+
+---
+
+## 2. Use Cases
+
+### Primary Use Cases
+
+#### 1. **Sectioning Forms Wizard Steps**
+When configuring Forms Wizard steps, the horizontal divider helps organize attributes into logical sections. For example, separating general step information from navigation settings.
+
+**Example Context (from test data):**
+```
+- Name attribute
+- Wizard reference
+- Title
+- Description
+- Skip to label
+[HORIZONTAL DIVIDER]
+- Step type
+- Identifier
+- Next step
+- Skip to
+- Skip to finish
+```
+
+#### 2. **Visual Grouping in Complex Forms**
+In type definitions or page layouts with many attributes, the horizontal divider creates visual breaks to improve form readability and user comprehension.
+
+#### 3. **Logical Separation in Configuration Pages**
+For administrative or configuration interfaces where different categories of settings need to be distinguished visually.
+
+### When to Use This Widget
+- When you have multiple related groups of attributes within a single Attributes Group widget
+- When you want to improve form readability without creating separate widget sections
+- When you need a lightweight visual separator without additional functionality
+- When organizing Forms Wizard step configurations
+
+### When NOT to Use This Widget
+- For functional separation requiring different widgets (use multiple Attributes Group widgets instead)
+- For interactive or collapsible sections (use appropriate container widgets)
+- Outside of Attributes Group widgets (technically restricted by implementation)
+- When you need styled or customizable dividers (this is a plain HTML `<hr>`)
+
+---
+
+## 3. Configuration Concepts
+
+### Widget Properties
+**No Configuration Properties Available**
+
+The Horizontal Divider widget is intentionally minimalist and provides:
+- **No configurable attributes**
+- **No widget-specific settings**
+- **No styling options** (uses browser/theme default `<hr>` styling)
+- **No interactive behavior**
+- **No localization needed** (visual element only)
+
+### Technical Implementation
+- **Template:** Single `<hr>` HTML tag
+- **Rendering:** Pure HTML with no JavaScript directive
+- **Styling:** Inherits from application theme/CSS
+- **Icon:** Uses Font Awesome `fa-horizontal-rule` icon in widget selector
+
+---
+
+## 4. Context & Relationships
+
+### Related Widgets
+
+#### Forms Wizard Plugin Family
+The horizontal divider is part of the Forms Wizard plugin suite, which includes:
+
+1. **Start Wizard Widget** (`cf.cplace.formsWizard.startWizardWidget`)
+   - Purpose: Button to initiate a Forms Wizard
+   - Relationship: Divider used in wizard configuration layouts
+
+2. **Step Editor Widget** (`cf.cplace.formsWizard.stepEditorWidget`)
+   - Purpose: Configure individual wizard steps
+   - Relationship: Divider helps organize step attribute configurations
+
+3. **Step Preview Widget** (`cf.cplace.formsWizard.stepPreview`)
+   - Purpose: Preview wizard step configuration
+   - Relationship: Divider may appear in preview rendering
+
+4. **Wizard Step Manager** (`cf.cplace.formsWizard.stepManager`)
+   - Purpose: Manage the sequence of wizard steps
+   - Relationship: Divider used in step detail views
+
+5. **Wizard Analysis Widget** (`cf.cplace.formsWizard.wizardAnalysis`)
+   - Purpose: Validate wizard configuration
+   - Relationship: Divider used in analysis result layouts
+
+6. **Wizard Activation Widget** (`cf.cplace.formsWizard.wizardActivation`)
+   - Purpose: Enable/disable wizards
+   - Relationship: Divider separates activation controls from status info
+
+7. **Wizard Localizations Widget** (`cf.cplace.formsWizard.wizardLocalizations`)
+   - Purpose: Manage wizard translations
+   - Relationship: Divider separates different localization sections
+
+### Parent Widget Constraint
+
+**Embedding Restriction:**
+```java
+@Override
+public boolean canBeEmbeddedInsideWidgetOfType(Class<? extends WidgetDefinition> enclosingWidgetDefinitionClass) {
+    return AttributesGroupWidgetDefinition.class.equals(enclosingWidgetDefinitionClass);
+}
+```
+
+The Horizontal Divider widget:
+- **MUST** be embedded inside an `AttributesGroupWidgetDefinition`
+- **CANNOT** be used standalone on pages or in rich strings
+- **CANNOT** be embedded in other widget types (e.g., Connected Attributes Group)
+
+This restriction ensures the divider is only used within its intended context of organizing attribute groups.
+
+### Dependencies & Prerequisites
+
+**No Dependencies:**
+- No required plugins beyond the Forms Wizard plugin itself
+- No required attributes or type definitions
+- No JavaScript dependencies (no TypeScript directive)
+- No specific permission requirements
+
+**Plugin Context:**
+- Part of `FormsWizardPlugin` (`cf.cplace.formsWizard`)
+- Belongs to `formsWizardApp` application context
+- Registered in plugin's widget definition registry
+
+---
+
+## 5. Technical Details
+
+### Implementation Analysis
+
+**File Locations:**
+- **Java Definition:** `/cf.cplace.formsWizard/src/main/java/cf/cplace/formsWizard/script/HorizontalDividerWidgetDefinition.java` (62 lines)
+- **HTML Template:** `/cf.cplace.formsWizard/src/main/resources/cf/cplace/formsWizard/script/horizontalDividerWidgetDefinition.htm` (1 line)
+- **No TypeScript Directive:** Widget has no client-side logic
+
+**Localization:**
+- English: "Horizontal Divider" (`messages_en.properties:126`)
+- German: "Horizontaler Trenner" (`messages_de.properties:126`)
+
+**Widget Characteristics:**
+- **Widget Kind:** `cf.cplace.formsWizard.horizontalDivider`
+- **Icon:** `fa-horizontal-rule` (Font Awesome)
+- **Template Substitution:** Returns empty `WidgetTemplateSubstitution`
+- **Embedding Checks:** Validates app space and parent widget type
+
+### Usage Patterns in Codebase
+
+**Test Data Usage:**
+The widget appears in test resources (`wizard-single-space.xml`) embedded within Attributes Group layouts alongside attribute widgets like:
+- `cf.platform.singleAttribute` (attribute display widgets)
+- Forms Wizard-specific attribute configurations
+
+**Programmatic Usage:**
+Found in `FormsWizardAppTypes.java` where it's used in programmatic type definition layouts:
+```java
+WidgetWithContent.newWidgetWithType("cf.cplace.formsWizard.horizontalDivider")
+```
+
+Appears at least 5 times in the app type definitions (lines 299, 682, 713, 774, 807), consistently used to separate groups of form attributes in wizard-related type definitions.
+
+---
+
+## 6. Design Philosophy
+
+### Why This Widget Exists
+
+The Horizontal Divider widget embodies several design principles:
+
+1. **Separation of Concerns:** Provides pure presentational functionality separate from data display
+2. **Simplicity:** Intentionally minimal with zero configuration to reduce complexity
+3. **Reusability:** Single-purpose widget that can be placed multiple times in a layout
+4. **Standard Compliance:** Uses native HTML `<hr>` element for accessibility and browser compatibility
+
+### Comparison to Alternatives
+
+**Why not just style attribute sections?**
+- Explicit divider provides visual clarity independent of attribute styling
+- Allows flexible positioning between any attributes
+- Maintains clean separation between content and presentation
+
+**Why not use Rich String widgets?**
+- Divider is lighter weight with no content editing overhead
+- Enforces consistent visual treatment across forms
+- Prevents users from adding arbitrary content in divider positions
+
+**Why restrict to Attributes Group only?**
+- Dividers only make semantic sense within attribute groupings
+- Prevents misuse in contexts where other layout mechanisms are more appropriate
+- Maintains clear widget hierarchy and purpose
+
+---
+
+## 7. Key Insights
+
+### Strengths
+- ✅ **Zero Learning Curve:** No configuration means immediate usability
+- ✅ **Lightweight:** Minimal code footprint and runtime overhead
+- ✅ **Consistent:** Same appearance and behavior everywhere
+- ✅ **Accessible:** Standard HTML element with built-in accessibility support
+- ✅ **Flexible Placement:** Can be positioned anywhere within attribute groups
+
+### Limitations
+- ❌ **No Styling Control:** Cannot customize appearance (color, thickness, style)
+- ❌ **Limited Context:** Only works in Attributes Group widgets
+- ❌ **No Functionality:** Pure presentation with no interactive capabilities
+- ❌ **No Conditional Display:** Cannot be shown/hidden based on conditions
+- ❌ **No Labels:** Cannot add section titles (use attribute group title instead)
+
+### Recommendations for Users
+
+**Best Practices:**
+1. Use sparingly - too many dividers can clutter the interface
+2. Group 3-7 related attributes before adding a divider
+3. Combine with descriptive attribute labels for section clarity
+4. Consider using multiple Attributes Group widgets for major section breaks
+5. Use consistent divider placement patterns across similar forms
+
+**Common Patterns:**
+- Place dividers between conceptual groups (e.g., "Basic Info" → divider → "Advanced Settings")
+- Use in wizard step configurations to separate step content from navigation settings
+- Apply in configuration pages to distinguish required vs. optional settings
+
+---
+
+## 8. Summary
+
+The `cf.cplace.formsWizard.horizontalDivider` widget is a purpose-built, minimalist layout element designed for the Forms Wizard plugin. It provides visual separation of attribute groups within form layouts through a simple horizontal line.
+
+**Key Takeaways:**
+- **Purpose:** Visual separator for organizing attributes in form layouts
+- **Scope:** Exclusively for use within Attributes Group widgets
+- **Configuration:** None - zero-configuration widget
+- **Use Case:** Improve form readability in wizard configurations and complex attribute groups
+- **Implementation:** Single `<hr>` HTML element with no JavaScript logic
+
+This widget exemplifies the "do one thing well" principle, serving a specific presentational need without unnecessary complexity or feature bloat.