@cplace/test-mcp-server 0.1.15 → 1.1.0

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

@@ -0,0 +1,174 @@
+# Widget Research: cf.cplace.formsWizard.wizardActivation
+
+## Overview
+
+**Widget ID**: `cf.cplace.formsWizard.wizardActivation`
+**Repository**: `cplace-forms-wizard`
+**Definition Class**: `cf.cplace.formsWizard/src/main/java/cf/cplace/formsWizard/script/WizardActivationWidgetDefinition.java`
+
+## Purpose
+
+The Wizard Activation widget enables administrators to activate or deactivate Forms Wizards based on configuration validation. It provides a simple interface to control whether end users can start new wizards or continue existing wizard instances.
+
+## Core Functionality
+
+### What This Widget Does
+
+The widget displays an **Activate** or **Deactivate** button depending on the wizard's current state:
+
+- **When the wizard is inactive**: Shows an "Activate" button that allows administrators to make the wizard available to end users
+- **When the wizard is active**: Shows a "Deactivate" button that allows administrators to disable the wizard
+
+### Activation States
+
+The widget manages two states (defined in `ActivationState.enum`):
+- `ACTIVE`: The wizard is available for use by end users
+- `INACTIVE`: The wizard is disabled and cannot be started or continued
+
+### Validation and Safety
+
+The widget implements important safety checks:
+
+1. **Configuration Validation**: Before allowing activation, the widget verifies that the wizard configuration is complete and valid by consulting the `WizardAnalysisService`
+2. **Blocked Activation**: If the configuration is incomplete or invalid, the Activate button is disabled and a message is displayed explaining why the wizard cannot be activated
+3. **Confirmation Dialog**: When deactivating a wizard, a confirmation dialog appears warning that "users can neither start new wizards nor continue them" once deactivated
+4. **Permission Check**: The widget respects entity permissions and only allows state changes if the user has edit permissions on the wizard page
+
+## Use Cases
+
+### Primary Use Case: Wizard Lifecycle Management
+
+Administrators use this widget to control the availability of Forms Wizards throughout their lifecycle:
+
+1. **During Configuration**: Keep the wizard inactive while configuring steps, transitions, and localization
+2. **Pre-Activation Validation**: Use alongside the Wizard Analysis widget to verify all configuration is valid
+3. **Activation**: Once the wizard is fully configured and validated, activate it to make it available to end users
+4. **Maintenance**: Deactivate the wizard when changes are needed or to temporarily disable it
+5. **Retirement**: Deactivate wizards that are no longer needed
+
+### Typical Workflow
+
+1. Administrator creates a new Forms Wizard page (inactive by default)
+2. Administrator configures wizard steps, transitions, and settings using other widgets
+3. Administrator reviews the Wizard Analysis widget to check for configuration issues
+4. Once all validation checks pass, the Activate button becomes enabled
+5. Administrator clicks Activate to make the wizard available
+6. If changes are needed later, administrator clicks Deactivate (with confirmation) to modify the wizard safely
+
+## Integration with Other Widgets
+
+The Wizard Activation widget is typically used alongside these related widgets on a wizard configuration page:
+
+- **Wizard Analysis Widget** (`cf.cplace.formsWizard.wizardAnalysis`): Validates wizard configuration and determines whether activation is allowed
+- **Step Manager Widget** (`cf.cplace.formsWizard.stepManager`): Manages the list of wizard steps
+- **Wizard Localizations Widget** (`cf.cplace.formsWizard.wizardLocalizations`): Configures multi-language support
+- **Step Editor Widgets**: Configure individual step properties
+
+The widget listens for configuration change events and automatically refreshes the activation state when:
+- Step relationships are modified
+- Step configurations are updated
+
+## Configuration
+
+### Widget Configuration Options
+
+The widget has minimal configuration requirements:
+- **Height**: Inherited from `WidgetTypes.BASE_MIXIN.HEIGHT` (only configurable property)
+
+### Embedding Constraints
+
+The widget can **only** be embedded on pages of type `cf.cplace.formsWizard.wizard`. This is enforced by the `checkEmbeddableIn()` method in the widget definition (lines 95-98 of WizardActivationWidgetDefinition.java).
+
+### User Interface Elements
+
+The widget displays:
+1. **Activate Button**: Primary button shown when wizard is inactive
+   - Enabled when configuration is valid and user has edit permissions
+   - Disabled with explanation message when configuration is invalid
+2. **Deactivate Button**: Primary button shown when wizard is active
+   - Always enabled when wizard is active (requires confirmation)
+3. **Cannot Activate Message**: Informational text displayed when the Activate button is disabled
+   - Message: "The wizard cannot be activated because the configuration is incomplete. The Wizard Analysis widget gives more information about why the wizard cannot be activated."
+
+## Technical Implementation Details
+
+### Backend Architecture
+
+**Service Layer** (`WizardActivationService.java`):
+- `getWizardActivationData()`: Retrieves current activation state and whether state changes are allowed
+- `setState()`: Updates the wizard's activation state after validation
+- `canActivateWizard()`: Validates wizard configuration using `WizardAnalysisService` before allowing activation
+- `isStateTransitionValid()`: Ensures state transitions follow business rules
+
+**REST API** (`WizardActivationController.java`):
+- `GET /cplace-fe/cf.cplace.formsWizard/wizard/activation?wizardId={id}`: Retrieves activation data
+- `POST /cplace-fe/cf.cplace.formsWizard/wizard/activation?wizardId={id}`: Updates activation state
+
+### Frontend Architecture
+
+**Component** (`WizardActivation.component.ts`):
+- Manages UI state and button visibility
+- Listens for wizard configuration changes via Angular events
+- Broadcasts activation state changes to other components
+- Shows confirmation dialog before deactivation
+
+**Service** (`WizardActivation.service.ts`):
+- Communicates with REST API
+- Handles confirmation modal for deactivation
+- Manages error states
+
+### Data Flow
+
+1. Widget loads and fetches current activation state from backend
+2. Backend checks wizard configuration validity via `WizardAnalysisService`
+3. Frontend displays appropriate button (Activate/Deactivate) based on state
+4. User clicks button:
+   - **Activate**: Immediately sends request to backend after validation check
+   - **Deactivate**: Shows confirmation modal first, then sends request
+5. Backend updates the wizard's `ACTIVE_STATE` attribute
+6. Widget broadcasts state change event to refresh other widgets
+
+### Events
+
+**Listens to**:
+- `events.NOTIFY_AFTER_CONTROL_SUBMIT`: Refreshes when step relationships change
+- `STEP_CONFIG_UPDATED_EVENT`: Refreshes when step configuration is saved
+
+**Broadcasts**:
+- `AbstractFlexiCtrl.EVENT_REFRESH_COMPONENTS`: Triggers component refresh
+- `EVENT_RELOAD_ATTRIBUTES_GROUP_WIDGET`: Reloads attribute widgets
+- `ACTIVATION_STATE_CHANGED`: Notifies other widgets of state change
+
+## User-Facing Messages
+
+The widget uses these localized messages (from `messages_en.properties`):
+
+- `wizardActivationActivate`: "Activate"
+- `wizardActivationDeactivate`: "Deactivate"
+- `wizardActivationModalTitle`: "Wizard deactivation"
+- `wizardActivationConfirmationBodyMessage`: "Are you sure you want to deactivate this wizard? Once the wizard is deactivated, users can neither start new wizards nor continue them."
+- `wizardActivationModalCancel`: "Cancel"
+- `wizardActivationReasonCannotActivate`: "The wizard cannot be activated because the configuration is incomplete. The Wizard Analysis widget gives more information about why the wizard cannot be activated."
+- `wizardActivationErrorDialogTitle`: "Activation Error"
+- `wizardActivationErrorDialogMessage`: "There was a problem with activating/deactivating the wizard. Please reload the page and verify if the wizard configuration is valid."
+
+## Dependencies
+
+- **Forms Wizard App**: Part of the Forms Wizard application
+- **Forms Wizard Types**: Uses `FormsWizardAppTypes.WIZARD.TYPE` and `FormsWizardAppTypes.WIZARD.ACTIVE_STATE`
+- **Wizard Analysis Service**: Depends on `WizardAnalysisService` to validate wizard configuration before activation
+- **Generic Modal Service**: Uses `GenericModalService` for confirmation dialogs and error messages
+
+## Key Business Rules
+
+1. **Activation requires valid configuration**: A wizard can only be activated if all validation checks pass (no errors in Wizard Analysis)
+2. **Deactivation requires confirmation**: Deactivating a wizard shows a warning that users cannot start or continue wizard instances
+3. **Permission-based**: State changes only allowed if user has edit permissions on the wizard page
+4. **Single state at a time**: A wizard is either ACTIVE or INACTIVE (no intermediate states)
+5. **Automatic refresh**: The widget automatically updates when wizard configuration changes
+
+## Related Documentation
+
+See also:
+- Wizard Analysis Widget research: `/Users/thomasbuechner/dev/repos/cplace-ga-products/specs/2026-01-16/cf-cplace-formsWizard-wizardAnalysis/research.md`
+- Widget Definition Mapping: `/Users/thomasbuechner/dev/repos/cplace-ga-products/specs/2026-01-16/widget-definition-mapping.md`

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

@@ -0,0 +1,283 @@
+# Forms Wizard Analysis Widget Research
+
+## Widget Information
+- **Widget ID**: `cf.cplace.formsWizard.wizardAnalysis`
+- **Widget Name**: Forms Wizard Analysis
+- **Repository**: cplace-forms-wizard
+- **Definition Class**: `cf.cplace.formsWizard/src/main/java/cf/cplace/formsWizard/script/WizardAnalysisWidgetDefinition.java`
+
+## Description
+
+The Forms Wizard Analysis widget validates that a Forms Wizard has all the necessary configurations to be able to run properly. It performs comprehensive checks on wizard structure, step configuration, and navigation logic to identify potential issues before the wizard is activated and made available to end users.
+
+## Purpose
+
+This widget serves as a validation and quality assurance tool for Forms Wizard administrators. It automatically analyzes the wizard configuration and displays a list of validation results, highlighting both successful checks and potential problems that could prevent the wizard from functioning correctly. This helps administrators catch configuration errors early in the wizard design process.
+
+## Core Functionality
+
+### Validation Analysis
+
+The widget performs automated validation by running multiple analyzers that check different aspects of the wizard configuration:
+
+1. **Start Step Validation** (`HasStartStepAnalyzer`)
+   - Checks if a start step is configured
+   - Error message: "Start step is not available"
+   - Success message: "Start step is available"
+
+2. **Step Reachability** (`AreAllStepsReachableAnalyzer`)
+   - Verifies that all configured steps can be reached during wizard execution
+   - Identifies orphaned steps that are not connected to the wizard flow
+   - Error message: "Some steps are not reachable (not reachable steps: {identifiers})"
+   - Success message: "All steps are reachable"
+
+3. **Final Step Validation** (`HasAtLeastOneFinalStepAnalyzer`)
+   - Ensures at least one final step is configured
+   - Error message: "No final step found"
+   - Success message: "At least one final step available"
+
+4. **Leaf Node Validation** (`AreAllLeavesFinalStepsAnalyzer`)
+   - Checks that all steps without next steps are marked as final steps
+   - Error message: "Not all steps without next steps are final steps ({identifiers})"
+   - Success message: "All steps without next steps are final steps"
+
+5. **Final Step Integrity** (`FinalStepsHaveNoNextStepAnalyzer`)
+   - Verifies that final steps do not have next steps configured
+   - Error message: "Some final steps have next steps (final steps with next steps: {identifiers})"
+   - Success message: "All final steps have no next steps"
+
+6. **External Access Configuration** (`ExternalAccessAnalyzer`)
+   - Validates external access settings when the wizard is configured for external use
+   - Error message: "An external access user is needed when the wizard is configured to be external."
+   - Success message: "The wizard is not configured to be external which means no further validation has to be done."
+
+7. **Skip Configuration Validation** (`SkipConfigurationIsValidAnalyzer`)
+   - Validates "skip to" step configurations
+   - Error message: "Some steps have invalid 'skip to' configuration: {identifiers}"
+   - Success message: "Basic configuration is valid"
+
+### Real-Time Updates
+
+The widget automatically refreshes its analysis when:
+- Step relationships are modified (listens to `NOTIFY_AFTER_CONTROL_SUBMIT` events)
+- Step configurations are updated (listens to `STEP_CONFIG_UPDATED_EVENT` events)
+- The wizard configuration changes
+
+### Visual Feedback
+
+The widget displays results in a list format with visual indicators:
+- Valid checks are styled with the `valid` CSS class
+- Invalid checks are styled with the `invalid` CSS class
+- Each result shows a descriptive message explaining the validation outcome
+
+## Use Cases
+
+### 1. Wizard Configuration Validation
+**Scenario**: An administrator is configuring a new Forms Wizard to guide users through a multi-step process (e.g., employee onboarding, project approval, or data collection).
+
+**Usage**: The administrator places the Forms Wizard Analysis widget on the wizard's configuration page. As they configure steps and navigation, the widget continuously validates the setup and immediately highlights any structural issues, such as:
+- Missing start step
+- Disconnected steps that can't be reached
+- Final steps that incorrectly have next steps
+- Missing final step definitions
+
+### 2. Pre-Activation Quality Check
+**Scenario**: Before activating a wizard and making it available to end users, an administrator wants to ensure the configuration is valid and complete.
+
+**Usage**: The administrator reviews the Forms Wizard Analysis widget to verify all validation checks pass. This prevents activating a broken wizard that could:
+- Fail to start due to missing start step
+- Trap users in unreachable steps
+- Have incomplete navigation flows
+- Lack proper completion endpoints
+
+### 3. Troubleshooting Wizard Issues
+**Scenario**: A wizard is not working as expected, and the administrator needs to identify configuration problems.
+
+**Usage**: The administrator adds or reviews the Forms Wizard Analysis widget to diagnose structural issues. The widget's detailed error messages pinpoint exactly which steps or configurations are problematic, such as:
+- "Some steps are not reachable (not reachable steps: EmployeeReview, FinalApproval)"
+- "Some final steps have next steps (final steps with next steps: SubmissionComplete)"
+
+### 4. External Wizard Configuration
+**Scenario**: An administrator is setting up a wizard to be accessible by external users (non-authenticated users or users from external systems).
+
+**Usage**: The Forms Wizard Analysis widget validates that external access is properly configured, ensuring an external access user is set when required. This prevents runtime errors when external users attempt to execute the wizard.
+
+### 5. Complex Navigation Validation
+**Scenario**: A wizard has conditional branching, skip logic, or complex navigation paths between steps.
+
+**Usage**: The widget validates that all navigation configurations are valid, ensuring:
+- Skip configurations point to valid steps
+- All paths eventually lead to a final step
+- No circular references or infinite loops exist in the navigation
+
+### 6. Wizard Maintenance and Updates
+**Scenario**: An administrator is updating an existing wizard by adding new steps or modifying the navigation flow.
+
+**Usage**: The widget provides continuous validation feedback during modifications, helping the administrator maintain a valid configuration throughout the update process. This is especially valuable when reorganizing steps or changing the navigation structure.
+
+## Configuration
+
+### Widget Configuration Options
+
+The widget has minimal configuration requirements:
+
+- **Height**: Configurable widget height (inherited from `WidgetTypes.BASE_MIXIN.HEIGHT`)
+- **Embedded Entity**: Automatically receives the wizard page it is embedded in
+
+### Embedding Restrictions
+
+The widget can **only** be embedded on pages of type `cf.cplace.formsWizard.wizard` (the Forms Wizard configuration page). This restriction is enforced in the `checkEmbeddableIn` method.
+
+### Widget State
+
+The widget maintains a simple state containing:
+- `embeddedIn`: The asset ID of the wizard page being analyzed
+
+## Technical Architecture
+
+### Backend Components
+
+1. **Widget Definition** (`WizardAnalysisWidgetDefinition.java`)
+   - Defines widget metadata and embedding rules
+   - Manages widget state initialization
+   - Belongs to the Forms Wizard App
+
+2. **REST Controller** (`WizardAnalysisController.java`)
+   - Endpoint: `{plugin}/wizard/analysis?wizardId={id}`
+   - Returns validation results as JSON
+   - Coordinates analysis service calls
+
+3. **Analysis Service** (`WizardAnalysisService.java`)
+   - Orchestrates multiple analyzer components
+   - Runs wizard-level analyzers (7 core analyzers)
+   - Runs step-level analyzers for all wizard steps
+   - Aggregates results into a single response
+
+4. **Analyzer Components**
+   - Each analyzer implements the `WizardAnalyzer` interface
+   - Each produces a `WizardAnalysisResultDto` with a message and validity flag
+   - Analyzers are stateless and reusable
+
+### Frontend Components
+
+1. **Angular Component** (`WizardAnalysis.component.ts`)
+   - Controller: `cfCplaceFormsWizardWizardAnalysis`
+   - Bindings: `wizardId` (input)
+   - Manages component lifecycle and event subscriptions
+   - Triggers analysis updates on configuration changes
+
+2. **Service** (`WizardAnalysisService`)
+   - Makes HTTP requests to the analysis REST endpoint
+   - Parses and returns validation results
+
+3. **Template** (`wizardAnalysis.htm`)
+   - Displays validation results as an unordered list
+   - Applies CSS classes based on validation status
+   - Shows localized message for each validation result
+
+## Context and Relationships
+
+### Related Widgets in Forms Wizard Feature Set
+
+The Forms Wizard Analysis widget is part of a comprehensive widget ecosystem for configuring and managing Forms Wizards:
+
+1. **Wizard Activation Widget** (`cf.cplace.formsWizard.wizardActivation`)
+   - Controls wizard activation state
+   - Typically used alongside the Analysis widget
+   - Prevents activation when analysis shows invalid configuration
+
+2. **Wizard Localizations Widget** (`cf.cplace.formsWizard.wizardLocalizations`)
+   - Manages localized text for wizard UI elements
+   - Provides multi-language support for wizards
+
+3. **Step Manager Widget** (`cf.cplace.formsWizard.stepManager`)
+   - Manages the list of wizard steps
+   - Creates, edits, and orders steps in the wizard flow
+
+4. **Step Editor Widget** (`cf.cplace.formsWizard.stepEditorWidget`)
+   - Configures individual step properties and behavior
+   - Used on step configuration pages
+
+5. **Step Editor for Wizard Widget** (`cf.cplace.formsWizard.stepEditorForWizardWidget`)
+   - Alternative step editor embedded on wizard pages
+   - Provides inline step editing capabilities
+
+6. **Step Preview Widget** (`cf.cplace.formsWizard.stepPreview`)
+   - Shows a preview of how a step will appear to end users
+   - Helps administrators visualize the user experience
+
+7. **Start Wizard Widget** (`cf.cplace.formsWizard.startWizardWidget`)
+   - Provides the button/interface for end users to start a wizard
+   - Used on pages where wizards should be launched
+
+8. **Horizontal Divider Widget** (`cf.cplace.formsWizard.horizontalDivider`)
+   - Visual separator for wizard UI elements
+
+### Typical Page Layout
+
+On a Forms Wizard configuration page, you would typically find:
+- **Step Manager Widget**: To manage the list of steps
+- **Wizard Analysis Widget**: To validate the configuration
+- **Wizard Activation Widget**: To activate/deactivate the wizard
+- **Wizard Localizations Widget**: To configure multi-language support
+
+### Dependencies
+
+- **Forms Wizard App**: The widget belongs to the Forms Wizard application
+- **Forms Wizard Types**: Requires wizard and step type definitions from `FormsWizardAppTypes`
+- **Step Finder Utilities**: Uses `StepFinder` to locate and traverse wizard steps
+- **Wizard Path Finder**: Uses `WizardPathFinder` for reachability analysis
+
+### Integration Points
+
+1. **Wizard Execution**: The `WizardExecutor` checks wizard validity before allowing execution, using the same analysis logic
+2. **Activation Service**: The `WizardActivationService` may reference analysis results to determine if a wizard can be activated
+3. **Step Configuration**: Changes to step configuration trigger automatic re-analysis
+
+## Validation Workflow
+
+The typical validation workflow is:
+
+1. **Administrator configures wizard** → Widget automatically analyzes configuration
+2. **Configuration change detected** → Widget triggers re-analysis
+3. **Analysis service runs** → All analyzers execute in sequence
+4. **Results aggregated** → Both wizard-level and step-level results combined
+5. **UI updates** → Results displayed with visual indicators
+6. **Administrator reviews** → Addresses any validation errors
+7. **Wizard activation** → Only proceeds when all validations pass
+
+## Error Prevention
+
+The widget helps prevent common wizard configuration errors:
+
+- **Structural errors**: Missing start/end points, disconnected steps
+- **Navigation errors**: Invalid skip configurations, unreachable steps
+- **Logic errors**: Final steps with next steps, non-final leaf nodes
+- **Access errors**: Missing external access configuration
+
+## Best Practices
+
+1. **Always include on wizard configuration pages**: The widget should be standard on all wizard configuration pages to provide continuous validation feedback
+
+2. **Review before activation**: Always review the widget's output before activating a wizard for end users
+
+3. **Address all errors**: Even if some checks pass, address all validation errors before making the wizard available
+
+4. **Use with activation widget**: Combine with the Wizard Activation widget to create a complete configuration and activation workflow
+
+5. **Monitor after changes**: After modifying an existing wizard, review the analysis results to ensure the changes didn't introduce new issues
+
+## Localization
+
+All validation messages are localized through the message bundle system:
+- English messages: `messages_en.properties`
+- German messages: `messages_de.properties`
+- Messages include parameterized text to show specific problematic step identifiers
+
+## Key Technical Notes
+
+- **Stateless analyzers**: Each analyzer is stateless and can run independently
+- **Real-time updates**: The widget subscribes to platform events for automatic updates
+- **REST-based**: Analysis is performed server-side and results are fetched via REST API
+- **Extensible**: New analyzers can be added to the `WizardAnalysisService` to check additional conditions
+- **Type safety**: Only embeddable on wizard-type pages, enforced at the platform level

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

@@ -0,0 +1,193 @@
+# Widget Research: cf.cplace.formsWizard.wizardLocalizations
+
+## Overview
+
+**Widget ID:** `cf.cplace.formsWizard.wizardLocalizations`
+
+**Repository:** `cplace-forms-wizard` (cf.cplace.formsWizard)
+
+**Definition Class:** `cf.cplace.formsWizard/src/main/java/cf/cplace/formsWizard/script/WizardLocalizationsWidgetDefinition.java`
+
+## Purpose
+
+The Wizard Localizations widget provides an interface for managing multi-language text translations used throughout a wizard's user interface. It allows administrators to define localized labels, messages, and UI text for different language codes, ensuring wizards can be presented in multiple languages based on user preferences.
+
+## Core Functionality
+
+This widget:
+1. Displays and manages localization data stored on a wizard entity
+2. Provides an editing interface for adding/modifying translations across multiple languages
+3. Detects and warns about languages used in localizations that aren't configured as system languages
+4. Persists localization changes through a dedicated REST API endpoint
+5. Integrates with cplace's standard localization infrastructure
+
+## Use Cases
+
+### Primary Use Case: Multi-Language Wizard Support
+When building a wizard that needs to support users in different languages, this widget allows you to:
+- Define translations for wizard UI elements (labels, buttons, messages, etc.)
+- Manage all language variants in a centralized location
+- Ensure consistency across the wizard's interface
+
+**Example Scenario:** A company operates in Germany, France, and the UK. They create an onboarding wizard that needs to display in German, French, and English. Using this widget, they can define all text elements with translations for each language code (de, fr, en).
+
+### Secondary Use Case: Localization Quality Assurance
+The widget helps identify configuration issues:
+- Detects when localizations reference languages not enabled in the system
+- Provides warnings for "unsupported languages" that won't be accessible to users
+- Helps administrators audit and maintain localization completeness
+
+### Related Feature Context
+This widget is part of the Forms Wizard feature set, which enables low-code creation of multi-step forms and workflows. Localizations are essential for making these wizards accessible to international user bases.
+
+## Architecture & Implementation
+
+### Data Storage
+
+Localizations are stored as JSON in a read-only string attribute on the wizard entity:
+
+- **Attribute ID:** `cf.cplace.formsWizard.localizations`
+- **Type:** Single String (Long String)
+- **Default Value:** `{}`
+- **Access:** Read-only (modified only through the widget/API)
+
+### Data Structure
+
+**Localizations Object:**
+```
+{
+  "key1": {
+    "localizedLabels": {
+      "en": "English text",
+      "de": "German text",
+      "fr": "French text"
+    }
+  },
+  "key2": { ... }
+}
+```
+
+Each key maps to a `Localization` object containing `localizedLabels` (language code → translated text).
+
+### Frontend Components
+
+**Main Widget Directive:**
+- File: `cfCplaceFormsWizardWizardLocalizationsWidgetDirective.ts`
+- Provides help icon linking to documentation: https://docs.cplace.io/lowcode/features/forms-wizard/text-localization
+- Parses widget state and initializes the controller
+
+**Main Component:**
+- Component: `cfCplaceFormsWizardLocalizations`
+- Inputs: `localizationsDto` (GetLocalizationsDto), `wizardId` (string)
+- Features: Save button, loading indicator, unsupported language warnings
+- Embeds: `cf-cplace-forms-wizard-localized-enumeration` component for editing
+
+**Service:**
+- File: `WizardLocalizations.service.ts`
+- Method: `save(wizardId, localizations)` → POST to `/cplace-fe/cf.cplace.formsWizard/wizard/localizations`
+
+### Backend Components
+
+**Widget Definition:**
+- File: `WizardLocalizationsWidgetDefinition.java`
+- Retrieves localization data from wizard entity via `FormsWizardAppTypes.WIZARD.LOCALIZATIONS`
+- Renders via `WidgetTemplateSubstitution`
+
+**Service Layer:**
+- File: `WizardLocalizationsService.java`
+- Method: `saveLocalizations(wizardId, localizations)`
+- Validates wizard type and persists changes using `PersistentEntity.doOnWritableCopyAndPersistIfModified()`
+
+**REST Controller:**
+- File: `WizardLocalizationsController.java`
+- Endpoint: `POST /cplace-fe/cf.cplace.formsWizard/wizard/localizations`
+- Parameters: `wizardId` (request param), `SetLocalizationsDto` (request body)
+
+### Data Transfer Objects
+
+**GetLocalizationsDto:**
+- Used for reading/displaying localizations
+- Contains: `Localizations` object and `Set<UnsupportedLanguageDto>`
+- Identifies languages used in localizations that aren't configured system languages
+
+**SetLocalizationsDto:**
+- Used for saving localizations
+- Contains: `Localizations` object to be persisted
+
+**Localizations:**
+- Extends `HashMap<String, Localization>`
+- JSON serialization via `toJson()` / `fromJson()` methods
+- Default empty state: `{}`
+
+**Localization:**
+- Contains: `Map<String, String> localizedLabels` (language → translation)
+- Converts to/from cplace's `LocalizedString` format
+
+## Configuration Concepts
+
+### Main Configuration Options
+
+1. **Localization Keys:** String identifiers for each localizable element
+2. **Language Codes:** ISO language codes (e.g., "en", "de", "fr") for each translation
+3. **Localized Text:** The actual translated text for each key/language pair
+
+### Customization Capabilities
+
+- **Add/Remove Languages:** Support any number of language variants
+- **Add/Remove Keys:** Define localizations for any wizard UI element
+- **Edit Translations:** Modify text for specific language/key combinations
+- **Bulk Management:** Edit all localizations in a single interface
+
+### Validation & Warnings
+
+The widget automatically:
+- Detects unsupported languages (languages in localizations not enabled in cplace)
+- Displays warnings for configuration issues
+- Prevents saving invalid data structures
+
+## Dependencies & Prerequisites
+
+### Prerequisites
+1. A wizard entity of type `cf.cplace.formsWizard.wizard`
+2. System languages configured in cplace (for proper language support)
+3. Forms Wizard plugin installed and enabled
+
+### Related Components
+- **Forms Wizard Framework:** This widget is part of the broader Forms Wizard feature
+- **cplace Localization System:** Integrates with `LocalizedString` and `UserLanguage` utilities
+- **Wizard Types:** Defined in `FormsWizardAppTypes.WIZARD`
+
+### Integration Points
+- Widget reads from `FormsWizardAppTypes.WIZARD.LOCALIZATIONS` attribute
+- Service validates wizard type using `FormsWizardAppTypes.WIZARD.TYPE`
+- Frontend embeds `cf-cplace-forms-wizard-localized-enumeration` component
+
+## Documentation & Support
+
+**Official Documentation:** https://docs.cplace.io/lowcode/features/forms-wizard/text-localization
+
+**Test Coverage:**
+- File: `TestLocalizations.java`
+- Tests: Serialization, DTO construction, unsupported language detection, LocalizedString conversions
+
+## Key Technical Details
+
+### Widget Behavior
+- **Read-Only Attribute:** Localizations attribute is read-only to ensure all modifications go through the controlled API
+- **JSON Storage:** All localization data stored as JSON for flexibility and queryability
+- **Validation:** Backend validates wizard type before allowing modifications
+- **State Management:** Frontend manages dirty state and provides save confirmation
+
+### Performance Considerations
+- Localizations loaded once per widget rendering
+- Changes persisted via single REST call
+- JSON parsing/serialization happens at service boundaries
+
+### Security
+- Modifications require appropriate permissions on the wizard entity
+- REST endpoint validates wizard type before allowing changes
+- Service uses platform's standard persistence mechanism with access control
+
+## Summary
+
+The `cf.cplace.formsWizard.wizardLocalizations` widget is a specialized administrative tool for managing multi-language support in Forms Wizards. It provides a user-friendly interface for defining, editing, and maintaining translations across all wizard UI elements, with built-in validation to ensure localization quality and consistency. The widget integrates seamlessly with cplace's localization infrastructure and is essential for organizations deploying wizards in multi-language environments.