@cplace/test-mcp-server 0.1.15 → 1.1.0

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

@@ -0,0 +1,275 @@
+# Widget Research: cf.platform.connectedBarChart
+
+## Overview
+
+**Widget ID:** `cf.platform.connectedBarChart`
+**Widget Name:** Bar Chart
+**Repository:** main
+**Definition Class:** `cf.cplace.platform/src/main/java/cf/cplace/platform/frontend/widgets/ConnectedBarChartWidgetDefinition.java`
+
+## Purpose
+
+The Connected Bar Chart widget visualizes an attribute from a table widget or a configurable search as a vertical bar/column chart. It aggregates data by counting the occurrences of distinct values for a selected attribute and displays the results using the Highcharts library.
+
+## Description
+
+The Connected Bar Chart widget displays the distribution of values for a selected attribute across a data set. It connects to either a table widget on the same page or uses its own search configuration to retrieve data, then creates a visual representation showing the frequency of each distinct attribute value as vertical bars (columns).
+
+## Use Cases
+
+### 1. Status Distribution Analysis
+- Visualize how many items are in each status (e.g., "Open", "In Progress", "Done")
+- Useful for project management dashboards to see task distribution across states
+- Helps identify bottlenecks where too many items accumulate in certain statuses
+
+### 2. Category Distribution
+- Show the distribution of items across different categories or types
+- Example: Display how many products belong to each product category
+- Example: Show distribution of issues by priority level (Low, Medium, High, Critical)
+
+### 3. Assignment Analysis
+- Visualize workload distribution by showing how many items are assigned to each person
+- Helps identify unbalanced workloads in teams
+- Useful for resource planning and capacity management
+
+### 4. Time-based Grouping
+- Display items grouped by date-related attributes (e.g., month, quarter, year)
+- Example: Show number of tickets created per month
+- Useful for trend analysis and identifying seasonal patterns
+
+### 5. Enumeration Value Distribution
+- Any enumeration or reference attribute can be visualized
+- Shows how values are distributed across a dataset
+- Helps identify most/least common values in a dataset
+
+## Key Functionality
+
+### Data Source Options
+The widget supports two mutually exclusive data sources:
+
+1. **Connected Table Widget** (Primary Mode)
+   - Links to an existing table widget on the same page
+   - Inherits the table's search configuration and filters
+   - Automatically updates when the table data changes
+   - Configured via `tableWidgetId` attribute
+
+2. **Standalone Search** (Fallback Mode)
+   - Define a search directly in the widget configuration
+   - Independent from other widgets on the page
+   - Configured via `search` attribute
+   - Must target a single entity type (unique type required)
+
+### Data Processing
+
+The widget uses term frequency aggregation from the search index:
+- Queries the search index for the selected attribute's exact values
+- Counts occurrences of each distinct value (term frequencies/facets)
+- Sorts results by the attribute's sort value (alphabetically/naturally)
+- Handles missing values and permission restrictions gracefully
+
+### Visualization
+
+The chart is rendered using Highcharts with the following characteristics:
+- **Chart Type:** Vertical column chart (`type: 'column'`)
+- **Interactive:** Zoom enabled on Y-axis for detailed inspection
+- **Styling:** Each bar has a distinct color (colorByPoint enabled)
+- **Data Labels:** Shows the count value on each bar
+- **Tooltip:** Displays the value count on hover
+- **Axis:** X-axis shows attribute values, Y-axis shows counts (no decimals)
+- **Legend:** Disabled (since each bar is a unique category)
+- **Export:** Disabled
+
+## Configuration Concepts
+
+### Required Configuration
+
+1. **Attribute Name** (`attributeName`)
+   - The attribute to visualize (must be from the searched entity type)
+   - Only attributes with appropriate multiplicities are available
+   - Dynamically populated based on the connected table or search
+   - Constrained by `ConnectedBarChartAttributeEnumerationProvider`
+
+### Optional Configuration
+
+2. **Table Widget ID** (`tableWidgetId`)
+   - Reference to a table widget on the same page
+   - Optional: can use standalone search instead
+   - Provides dynamic list of available table widgets via `ConnectedTableWidgetsEnumerationProvider`
+
+3. **Search** (`search`)
+   - Alternative to table widget connection
+   - Allows configuring a search directly in the widget
+   - Must return entities of a single type
+   - Supports relative search filters
+
+4. **Localized Title** (`localizedTitle`)
+   - Custom title for the widget (supports multiple languages)
+   - Optional: defaults to "Bar Chart"
+   - Replaces deprecated `title` attribute
+
+5. **Height** (`height`)
+   - Custom height in pixels for the chart
+   - Optional: uses default height if not specified
+   - Allows charts to be sized appropriately for the dashboard
+
+### Configuration Validation
+
+The widget enforces the following validation rules:
+- At least one data source must be specified (table widget OR search)
+- If using standalone search, it must target a unique entity type
+- The selected attribute must exist in the entity type being searched
+
+### Configuration Display Logic
+
+The attribute name field has conditional visibility:
+- Only shown when either `tableWidgetId` or `search` is configured
+- Hidden until a data source is selected
+- This ensures users select a data source before choosing the attribute
+
+## Related Widgets
+
+The Connected Bar Chart is part of a family of "connected" chart widgets:
+
+1. **cf.platform.connectedPieChart** - Displays attribute distribution as a pie chart
+2. **cf.platform.connectedMatrix** - Shows two-dimensional attribute relationships
+3. **cf.platform.connectedSingleAttribute** - Displays a single attribute value from a selection
+4. **cf.platform.connectedNumberOfResults** - Shows the count of results from a table
+
+All these widgets share common patterns:
+- Can connect to table widgets or use standalone searches
+- Use the `ABSTRACT_CONNECTED_CHART` and `ABSTRACT_CONNECTED_TABLE_WIDGET` type definitions
+- Implement `ISearchProducer` interface
+- Support relative search filter resolution
+
+## Technical Architecture
+
+### Backend Components
+
+- **Definition Class:** `ConnectedBarChartWidgetDefinition`
+  - Extends `WidgetDefinition`
+  - Implements configuration validation and error handling
+  - Provides widget substitution for template rendering
+  - Icon: `fa-chart-bar` (Font Awesome bar chart icon)
+
+- **Data Handler:** `ConnectedBarChartDataHandler`
+  - Extends `ConnectedChartDataHandler` (abstract base class)
+  - Generates JSON array with [label, count] pairs
+  - Uses search index term frequencies for efficient aggregation
+  - Renders attribute values as HTML (without links, using separators)
+
+- **Configuration Provider:** `ConnectedBarChartAttributeEnumerationProvider`
+  - Extends `AbstractConnectedWidgetAttributeEnumerationProvider`
+  - Provides dynamic list of available attributes based on data source
+  - Resolves relative search filters
+
+### Frontend Components
+
+- **Directive:** `connectedBarChartWidget`
+  - AngularJS directive for widget integration
+  - Requires parent `cplaceWidget` directive
+  - Parses widget state from HTML attribute
+
+- **Controller:** `ConnectedBarChartWidgetController`
+  - Extends `AbstractConnectedChartWidgetController`
+  - Configures Highcharts with column chart settings
+  - Loads data from backend endpoint via AJAX
+  - Configuration includes zoom, tooltips, and styling
+
+### Data Flow
+
+1. Widget configuration specifies data source (table or search) and attribute
+2. Frontend controller initializes and requests data from backend
+3. Backend handler executes search and aggregates term frequencies
+4. Data is formatted as JSON array: `[["value1", count1], ["value2", count2], ...]`
+5. Frontend renders Highcharts column chart with the data
+6. User can interact with chart (zoom, hover for details)
+
+## Prerequisites and Dependencies
+
+### Prerequisites
+- The widget must be embedded in a page (not embeddable in other contexts)
+- For table widget connection: A table widget must exist on the same page
+- For standalone search: A valid search configuration targeting a single type
+
+### Dependencies
+- **Highcharts Library:** Used for chart rendering in the frontend
+- **Search Index:** Relies on search index term frequency capabilities
+- **Permission System:** Respects attribute-level permissions (handles `AttributeAccessForbiddenException`)
+
+## Configuration Patterns
+
+### Pattern 1: Connected to Table Widget
+The most common usage pattern:
+1. Add a table widget to the page
+2. Add the Connected Bar Chart widget
+3. Configure `tableWidgetId` to reference the table widget
+4. Select an `attributeName` to visualize
+5. Chart automatically reflects the table's current filters and search
+
+### Pattern 2: Standalone Search
+For independent visualizations:
+1. Add the Connected Bar Chart widget
+2. Configure a `search` that targets a specific entity type
+3. Select an `attributeName` to visualize
+4. Chart operates independently from other widgets
+
+### Pattern 3: Dashboard Integration
+For overview dashboards:
+1. Multiple chart widgets connected to the same table
+2. Table provides interactive filtering
+3. All connected charts update together
+4. Different attributes visualized in different chart types (bar, pie, matrix)
+
+## Migration Notes
+
+The widget supports migration from older configurations:
+- Deprecated `title` attribute is migrated to `localizedTitle`
+- Migration handled by `migrateUnlocalizedStringToLocalizedString` method
+- Old configurations continue to work but are automatically upgraded
+
+## Error Handling
+
+The widget displays errors for invalid configurations:
+
+1. **No Data Source Specified**
+   - Message: `noDataSourceSpecified`
+   - Occurs when neither `tableWidgetId` nor `search` is configured
+
+2. **Search for Unique Type Required**
+   - Message: `searchForUniqueTypeRequired`
+   - Occurs when standalone search returns multiple entity types
+   - Search must be constrained to a single type for attribute selection
+
+3. **Attribute Access Forbidden**
+   - Handled gracefully by returning empty results
+   - Respects permission system when users lack attribute read access
+
+4. **Data Generation Failure**
+   - Throws `IllegalStateException` with context
+   - Includes attribute name in error message for debugging
+
+## Best Practices
+
+### When to Use Connected Bar Chart
+- **Use when:**
+  - You want to show distribution across discrete categories
+  - You need to compare frequencies of different values
+  - The attribute has a reasonable number of distinct values (< 50)
+  - You want vertical/column representation
+
+- **Avoid when:**
+  - You have too many distinct values (chart becomes cluttered)
+  - You need continuous data visualization (use line charts instead)
+  - You want to show proportions/percentages (consider pie chart)
+  - You need multi-dimensional analysis (consider matrix widget)
+
+### Configuration Recommendations
+1. **Choose appropriate attributes:** Enumeration, reference, or text attributes with limited distinct values
+2. **Use meaningful titles:** Configure localized titles to clarify what the chart represents
+3. **Set appropriate height:** Adjust height based on number of categories and dashboard layout
+4. **Prefer table widget connection:** When working with interactive dashboards for synchronized filtering
+5. **Use standalone search:** When creating fixed visualizations or separate analysis views
+
+## Summary
+
+The Connected Bar Chart widget is a versatile visualization tool for displaying attribute value distributions. It excels at showing categorical data frequency and integrates seamlessly with table widgets for interactive dashboard experiences. The widget's flexible data source configuration and robust error handling make it suitable for various business intelligence and data analysis scenarios within the cplace platform.

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

@@ -0,0 +1,396 @@
+# Connected Matrix Widget Research
+
+**Widget ID:** `cf.platform.connectedMatrix`
+**Repository:** `main`
+**Definition Class:** `cf.cplace.platform/src/main/java/cf/cplace/platform/frontend/widgets/ConnectedMatrixWidgetDefinition.java`
+**Research Date:** 2026-01-16
+
+---
+
+## 1. Widget Description
+
+The Connected Matrix Widget displays search results in a two-dimensional matrix visualization, where pages are positioned based on two attributes (X and Y axes), creating an interactive grid that shows the distribution and relationships between items.
+
+---
+
+## 2. Purpose and Core Functionality
+
+### What This Widget Does
+
+The Connected Matrix Widget is a data visualization component that:
+
+1. **Creates a 2D Matrix Layout**: Organizes pages from a search result into a grid structure based on two configurable attributes
+2. **Displays Relationships**: Shows how items are distributed across two dimensions, making patterns and relationships visible at a glance
+3. **Connects to Table Widgets**: Integrates with existing table widgets to visualize their data in matrix form
+4. **Supports Interactive Navigation**: Each cell in the matrix contains clickable links to the pages it represents
+5. **Handles Multiple Value Types**: Works with enumeration, reference, date, and other attribute types
+
+### Technical Implementation
+
+The widget extends `AbstractConnectedTableHandler`, meaning it:
+- Connects to a table widget (`TABLE_WIDGET_ID` configuration)
+- Uses the table's search query and filters
+- Applies permissions from the connected table
+- Can be embedded on pages where the table widget resides
+
+The backend handler (`ConnectedMatrixHandler.java:48-364`) processes the data by:
+1. Executing the search query (up to `maxResults` items, default 500)
+2. Extracting X and Y attribute values from each page
+3. Grouping pages by their X/Y coordinate combinations
+4. Organizing the data into rows and columns
+5. Supporting special formatting for dates, enumerations, and user references
+
+---
+
+## 3. Use Cases
+
+### Primary Use Cases
+
+1. **Responsibility Assignment Matrix (RACI)**
+   - X-axis: Team members or roles
+   - Y-axis: Tasks or deliverables
+   - Shows who is responsible, accountable, consulted, or informed for each task
+   - Icon attributes can display status indicators or role types
+
+2. **Resource Allocation Matrix**
+   - X-axis: Time periods (weeks, months, quarters)
+   - Y-axis: Projects or teams
+   - Shows which resources are allocated where and when
+   - Profile images can represent team members
+
+3. **Risk Assessment Matrix**
+   - X-axis: Risk likelihood (Low, Medium, High)
+   - Y-axis: Risk impact (Low, Medium, High)
+   - Displays risks positioned by probability and severity
+   - Icons can show risk categories or status
+
+4. **Product Feature Comparison**
+   - X-axis: Products or product versions
+   - Y-axis: Features or requirements
+   - Shows which products have which features
+   - Icons can indicate implementation status
+
+5. **Stakeholder Analysis**
+   - X-axis: Interest level
+   - Y-axis: Influence/Power level
+   - Maps stakeholders by their engagement characteristics
+   - Profile images for person references
+
+6. **Cross-Functional Dependencies**
+   - X-axis: Departments or teams
+   - Y-axis: Projects or initiatives
+   - Visualizes cross-organizational dependencies
+   - Shows which teams are involved in which projects
+
+### When to Use This Widget
+
+Choose the Connected Matrix Widget when:
+- You need to visualize relationships between two categorical dimensions
+- You want to show distribution patterns across two attributes
+- You need to identify gaps or concentrations in a 2D space
+- Users need to quickly understand positioning or categorization
+- You want to make complex relationships more accessible visually
+
+### When NOT to Use This Widget
+
+Avoid this widget when:
+- You need detailed tabular data (use Table Widget instead)
+- You only have one dimension to visualize (use Bar/Pie Chart instead)
+- You need time-series visualization (use Line Chart or Gantt instead)
+- Attributes have too many unique values (matrix becomes too large)
+- You need hierarchical relationships (use Tree Table instead)
+
+---
+
+## 4. Configuration Concepts
+
+### Core Configuration Options
+
+#### Table Connection
+- **`TABLE_WIDGET_ID`** (Required): ID of the table widget to connect to
+  - The matrix uses the table's search query and applies the same permissions
+  - All table filters (including connected filters) affect the matrix data
+
+#### Axis Configuration
+
+**X-Axis (Horizontal)**:
+- **`ATTRIBUTE_X_NAME`** (Required): The attribute to use for columns
+  - Must be a custom attribute from the types in the search
+  - Supports: Enumerations, References (including Person), Dates, Strings, Numbers
+- **`LABEL_X`** (Optional): Custom label for the X-axis
+  - If not provided, uses the attribute's localized name
+- **`BOX_STYLE_X`** (Required, default: "plain"): Visual style for column headers
+  - `plain`: Simple text labels
+  - `label`: Styled label boxes
+  - `arrow`: Labels with arrow indicators
+  - `profile-line`: User profile images in a line layout (for Person references)
+  - `profile-column`: User profile images in a column layout (for Person references)
+- **`MIN_WIDTH`** (Optional): Minimum width for columns in pixels
+
+**Y-Axis (Vertical)**:
+- **`ATTRIBUTE_Y_NAME`** (Required): The attribute to use for rows
+  - Same type support as X-axis
+- **`LABEL_Y`** (Optional): Custom label for the Y-axis
+- **`BOX_STYLE_Y`** (Required, default: "plain"): Visual style for row headers
+  - Same options as X-axis
+- **`MAX_ROW_HEIGHT`** (Optional): Maximum height for rows in pixels
+
+#### Data Display
+- **`ICON_ATTRIBUTES`** (Optional, multiple): Additional attributes to display as icons in matrix cells
+  - Typically used for status indicators, categories, or visual markers
+  - Values are rendered as inline representations
+- **`MAX_RESULTS`** (Required, default: 500): Maximum number of pages to load from the search
+  - Prevents performance issues with large datasets
+  - Pages beyond this limit are not shown in the matrix
+
+#### Visual Settings
+- **`TITLE`** (Optional): Custom title for the widget
+  - If not provided, uses the widget's default name
+- **`HEIGHT`** (Optional): Fixed height for the widget in pixels
+
+### Configuration Behavior
+
+#### Enumeration Attributes
+When X or Y axis uses an enumeration attribute:
+- All enumeration values are pre-populated as lanes (columns/rows)
+- Empty cells are shown for values without matching pages
+- Order follows the enumeration's defined sort order
+
+#### Non-Enumeration Attributes
+For dates, references, or other types:
+- Only values present in the search results create lanes
+- Lanes are sorted by the value's sort value
+- Empty lanes are not shown
+
+#### Date Formatting
+Date attributes respect their DateConstraint configuration:
+- Formatted according to the attribute's date format settings
+- Grouped by formatted value (e.g., "Q1 2026", "January 2026")
+
+#### Person References with Profile Style
+When using `profile-line` or `profile-column` styles:
+- Extracts thumbnail URLs from Person entities
+- Displays profile pictures in the matrix headers
+- Falls back to text if thumbnail unavailable
+
+---
+
+## 5. Relationships to Other Widgets
+
+### Connected Widget Family
+
+The Connected Matrix Widget is part of a family of "connected" widgets that all integrate with table widgets:
+
+- **cf.platform.connectedBarChart**: Visualizes data distribution in bar chart form
+- **cf.platform.connectedPieChart**: Shows proportional distribution
+- **cf.platform.connectedSingleAttribute**: Displays a single attribute value from results
+- **cf.platform.connectedTableFilter**: Provides filtering controls for connected tables
+- **cf.platform.connectedAttributesGroup**: Groups and displays multiple attributes
+- **cf.cplace.platform.tableWidget**: The core table widget that others connect to
+
+All these widgets share the concept of connecting to a table widget to:
+- Share the same search query
+- Apply consistent permissions
+- Respond to table filters
+- Update when table data changes
+
+### Prerequisites and Dependencies
+
+**Required:**
+- A configured Table Widget (`cf.platform.tableWidget` or `cf.cplace.platform.tableWidget`)
+- Search results containing pages with the specified X and Y attributes
+- Attributes must be defined in the type(s) included in the search
+
+**Optional:**
+- Icon attributes for additional visual information
+- Custom localizations for axis labels
+
+**Compatible With:**
+- Connected Table Filter widgets (filters affect the matrix)
+- Other connected widgets (can share the same table widget)
+- Embedded Search widgets (as the source of the table)
+
+---
+
+## 6. Technical Details
+
+### Data Flow
+
+1. **Frontend Request**: Matrix widget sends request to `ConnectedMatrixHandler`
+2. **Data Extraction**: Handler receives:
+   - Component identifier (references the table widget)
+   - Search query with filters from the table
+   - Widget configuration (entity + widgetId)
+   - Embedding context
+3. **Search Execution**: Executes search with permissions from table specification
+4. **Matrix Population**:
+   - Extracts X and Y values from each page
+   - Creates lanes (rows/columns) for unique values
+   - Groups pages into cells based on coordinates
+   - Extracts icon attributes for display
+5. **JSON Response**: Returns `MatrixData` structure with:
+   - `typeLabel`: Name(s) of the types being displayed
+   - `xLabel`, `yLabel`: Axis labels
+   - `columns`: Array of X-axis lanes
+   - `rows`: Array of Y-axis lanes
+   - `data`: Nested map structure (y → x → list of entries)
+
+### Data Structures
+
+**MatrixData** (`MatrixData.java:15-26`):
+- Top-level container for the entire matrix
+- Contains labels, lanes, and the data grid
+
+**MatrixLane** (`MatrixLane.java:12-24`):
+- Represents a single row or column
+- Fields: `tagValue` (internal ID), `sortValue`, `label`, `imageUrl`
+
+**MatrixEntry** (`MatrixEntry.java:15-26`):
+- Represents a single page in a cell
+- Contains: `link` (URL to page), `icons` (rendered icon attributes)
+
+### Icon Attribute Rendering
+
+The widget supports flexible icon rendering (`ConnectedMatrixHandler.java:108-162`):
+- Enumerations: Shows the presentation value
+- Other types: Uses `ValuesAsHtmlRenderer` for appropriate formatting
+- Multiple icon attributes create a list of visual indicators per page
+
+### Special Handling
+
+**Person References with Profile Styles** (`ConnectedMatrixHandler.java:220-225`):
+- Detects when axis uses Person reference attribute
+- Checks if box style is `profile-line` or `profile-column`
+- Extracts thumbnail URL from Person entity
+- Adds image URL to MatrixLane for frontend rendering
+
+**Date Value Formatting** (`ConnectedMatrixHandler.java:267-284`):
+- Retrieves DateConstraint from attribute definition
+- Formats date according to constraint settings
+- Converts to StringValue for consistent display
+
+---
+
+## 7. Constraints and Limitations
+
+### Technical Constraints
+
+1. **Max Results Limit**: Default 500 pages, configurable
+   - Large datasets may not show all results
+   - No pagination within the matrix
+   - Consider refining search or using filters
+
+2. **Attribute Requirements**:
+   - Both X and Y attributes must exist on the types in the search
+   - Attributes must be custom attributes (not built-in properties)
+   - Pages without either attribute value are excluded from display
+
+3. **Matrix Size**:
+   - Large numbers of unique values create unwieldy matrices
+   - Best with 3-20 values per axis
+   - Too many cells can impact browser performance
+
+4. **Data Structure**:
+   - Matrix expects distinct categorical values
+   - Not designed for continuous numeric ranges
+   - Date attributes are grouped by formatted value (not continuous timeline)
+
+### UX Considerations
+
+1. **Empty Cells**:
+   - Enumeration attributes show all values (including empty)
+   - Other types only show values with data
+   - Empty cells are visible but not interactive
+
+2. **Multiple Pages per Cell**:
+   - Cells can contain multiple pages
+   - All pages are shown as links within the cell
+   - Very crowded cells may impact readability
+
+3. **No Drill-Down**:
+   - Matrix provides overview, not detail
+   - Users must click through to pages for full information
+   - Icon attributes provide limited context
+
+4. **Responsive Design**:
+   - Large matrices may not work well on small screens
+   - Minimum width and maximum row height help but don't fully solve this
+
+---
+
+## 8. Key Implementation Files
+
+### Backend (Java)
+
+- **Widget Definition**: `cf.cplace.platform/src/main/java/cf/cplace/platform/frontend/widgets/ConnectedMatrixWidgetDefinition.java` (lines 27-127)
+  - Defines widget metadata and configuration
+  - Icon: `fa-th` (grid/table icon)
+
+- **Request Handler**: `cf.cplace.platform/src/main/java/cf/cplace/platform/frontend/handler/widgets/matrix/ConnectedMatrixHandler.java` (lines 48-364)
+  - Processes requests and generates matrix data
+  - Handles attribute extraction and formatting
+
+- **Data Models**:
+  - `MatrixData.java` (lines 15-26): Container for matrix structure
+  - `MatrixLane.java` (lines 12-24): Row/column representation
+  - `MatrixEntry.java` (lines 15-26): Individual page entry
+
+- **Base Handler**: `cf.cplace.platform/src/main/java/cf/cplace/platform/frontend/handler/widgets/AbstractConnectedTableHandler.java` (lines 31-96)
+  - Shared logic for all connected widgets
+  - Handles table connection and search integration
+
+- **Configuration Type**: `cf.cplace.platform/src/main/java/cf/cplace/platform/frontend/templating/WidgetTypes.java` (lines 763-908)
+  - Defines all configuration attributes
+  - Sets defaults and constraints
+
+### Frontend
+
+Frontend files were not located in the platform repository during research, suggesting they may be:
+- In a separate frontend repository
+- Built as TypeScript/JavaScript components
+- Using a client-side framework to render the matrix from JSON data
+
+---
+
+## 9. Related Patterns and Best Practices
+
+### Naming Conventions
+
+- Widget ID follows pattern: `cf.platform.connected{Type}`
+- Connected widgets share `TABLE_WIDGET_ID` configuration
+- Handler classes follow: `Connected{Type}Handler`
+
+### Design Patterns
+
+1. **Template Method**: Base class defines flow, subclasses implement specifics
+2. **Strategy**: Different box styles change rendering behavior
+3. **Data Transfer Object**: Clean JSON serialization with Gsonable
+4. **Handler Pattern**: POST-only handlers for data retrieval
+
+### Best Practices Observed
+
+1. **Permission Delegation**: Matrix respects table widget permissions
+2. **Localization Support**: All labels support multiple languages
+3. **Null Safety**: Extensive use of `@Nullable` and null checks
+4. **Type Safety**: Strong typing with attribute definitions
+5. **Configurability**: Sensible defaults with override options
+6. **Performance**: Configurable max results to prevent overload
+
+---
+
+## 10. Questions for Further Research
+
+1. **Frontend Implementation**: Where is the client-side rendering code?
+2. **User Interactions**: Are cells clickable? Can users interact beyond navigation?
+3. **Real-time Updates**: Does the matrix refresh when table data changes?
+4. **Export Capabilities**: Can matrices be exported as images or documents?
+5. **Accessibility**: How does the widget handle screen readers and keyboard navigation?
+6. **Mobile Experience**: How does the responsive design work in practice?
+7. **Customization**: Can cell colors or styles be customized based on data?
+8. **Performance**: What are the practical limits for matrix size?
+
+---
+
+## Summary
+
+The Connected Matrix Widget is a powerful visualization tool for displaying two-dimensional relationships in data. It excels at showing distribution patterns, resource allocations, and categorical relationships. As part of the "connected widget" family, it integrates seamlessly with table widgets while providing a unique matrix-based perspective on search results. The widget is highly configurable, supporting various attribute types, visual styles, and display options, making it suitable for a wide range of business scenarios from RACI matrices to risk assessments.