@cplace/test-mcp-server 1.0.0 → 1.1.0

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

@@ -0,0 +1,419 @@
+# Step Manager Widget Research
+
+## Widget Information
+- **Widget ID**: `cf.cplace.formsWizard.stepManager`
+- **Widget Name**: Step Manager
+- **Repository**: cplace-forms-wizard
+- **Definition Class**: `cf.cplace.formsWizard/src/main/java/cf/cplace/formsWizard/script/WizardStepManagerWidgetDefinition.java`
+
+## Description
+
+The Step Manager widget provides a comprehensive overview table of all Forms Wizard steps configured for a specific wizard. It displays step metadata, configuration status, and provides actions to create new steps or delete existing ones.
+
+## Purpose
+
+This widget serves as the central management interface for Forms Wizard administrators to view, organize, and manage the complete list of steps that make up a wizard. It provides a sortable, actionable table view that shows key information about each step, helping administrators understand the wizard's structure at a glance and perform step lifecycle operations.
+
+## Core Functionality
+
+### Step Overview Table
+
+The widget displays a sortable table with the following columns for each step:
+
+1. **Name**: Step display name (clickable link to the step configuration page)
+2. **Identifier**: Unique identifier for the step (used for programmatic references)
+3. **Type**: Step type (e.g., Form, Script, Info, Summary, Table)
+4. **Configuration Complete**: Visual indicator showing whether the step is fully configured
+   - Check icon (✓) for complete configuration
+   - X icon (✗) for incomplete configuration
+   - Tooltip: "More information can be found in the 'Wizard Analysis' widget"
+5. **Created At**: Creation timestamp of the step
+6. **Order in Wizard**: Position/sequence number in the wizard flow (only works if a start step is set)
+
+### Real-Time Updates
+
+The widget automatically refreshes the step list when:
+- Step relationship attributes are changed (listens to `NOTIFY_AFTER_CONTROL_SUBMIT` events)
+- The wizard activation state changes (listens to `ACTIVATION_STATE_CHANGED` events)
+- The wizard configuration is modified
+
+This ensures the table always reflects the current state of the wizard's steps.
+
+### Table Actions and Buttons
+
+#### Create Step Button
+- **Label**: "Create Step"
+- **Icon**: Plus icon (fa-plus)
+- **Functionality**: Opens a modal dialog to create a new step
+- **Permissions**: Only shown if the user can edit the wizard
+- **Behavior**:
+  - Pre-fills the new step with the current wizard reference
+  - Opens in the same workspace as the wizard
+  - Automatically links the new step to the wizard
+
+#### Delete Step Action
+- **Label**: "Delete step"
+- **Icon**: Trash icon (fa-trash)
+- **Availability**: Shown when exactly one step is selected in the table
+- **Permissions**: Only available if the user can edit the wizard
+- **Functionality**: Opens a modal dialog to confirm and delete the selected step
+
+### Configuration Completeness Indicator
+
+The widget shows at a glance whether each step is fully configured:
+- **Complete**: Green check icon indicates all required step configuration is present
+- **Incomplete**: Red X icon indicates missing or invalid configuration
+- The completeness check is performed by the `StepAnalysisService`, which validates step-level configuration requirements
+
+This indicator helps administrators quickly identify steps that need attention before the wizard can be activated.
+
+### Step Ordering
+
+The "Order in Wizard" column shows the position of each step in the wizard's execution flow:
+- Position is calculated based on the shortest path from the start step to each step
+- Only works when a start step is configured
+- Steps with no path from the start step receive a default high position value
+- Helps visualize the wizard's navigation flow and identify potential unreachable steps
+
+## Use Cases
+
+### 1. Step Inventory and Organization
+**Scenario**: An administrator needs to understand what steps exist in a wizard and how they're organized.
+
+**Usage**: The Step Manager widget provides a complete inventory of all steps in the wizard, showing their names, types, and order. The administrator can quickly scan the list to understand the wizard's structure and identify any missing or extra steps.
+
+### 2. Step Configuration Monitoring
+**Scenario**: Before activating a wizard, an administrator needs to ensure all steps are properly configured.
+
+**Usage**: The "Configuration Complete" column shows which steps have incomplete configurations. The administrator can click on steps marked as incomplete (red X icon) to navigate to those step pages and complete the configuration. This works in conjunction with the Wizard Analysis widget for detailed validation messages.
+
+### 3. Creating New Wizard Steps
+**Scenario**: An administrator is building a wizard and needs to add a new step to the flow.
+
+**Usage**: The administrator clicks the "Create Step" button, which opens a modal dialog to create a new step. The new step is automatically:
+- Associated with the current wizard
+- Created in the same workspace
+- Added to the step list in the table
+- Ready for configuration
+
+This streamlines the step creation process by pre-filling wizard context.
+
+### 4. Removing Obsolete Steps
+**Scenario**: An administrator needs to remove a step that's no longer needed in the wizard.
+
+**Usage**: The administrator selects the step in the table and clicks the "Delete step" action. This opens a confirmation modal to delete the step. This helps maintain a clean wizard structure by removing unused or deprecated steps.
+
+### 5. Understanding Wizard Flow Sequence
+**Scenario**: An administrator wants to understand the execution order of steps in the wizard.
+
+**Usage**: The "Order in Wizard" column shows the position of each step in the execution sequence, starting from the start step. Steps with position 1 are directly after the start step, position 2 are second in line, and so on. This helps visualize the navigation flow and identify:
+- Steps that are early vs. late in the process
+- Potential unreachable steps (high position numbers when they should be reachable)
+- The shortest path length from start to each step
+
+### 6. Quick Navigation to Step Configuration
+**Scenario**: An administrator needs to quickly access a specific step's configuration page.
+
+**Usage**: The step names in the table are clickable links that navigate directly to the step's configuration page. This provides quick access to edit step properties, configure forms, set up navigation rules, or modify step-specific settings.
+
+### 7. Step Type Overview
+**Scenario**: An administrator wants to understand what types of steps are used in the wizard (Form, Script, Info, etc.).
+
+**Usage**: The "Type" column shows each step's type, providing a quick overview of the mix of step types in the wizard. This helps assess the wizard's structure:
+- Are there appropriate Info steps to guide users?
+- Are there Form steps for data collection?
+- Are there Script steps for processing?
+- Is there a Summary step at the end?
+
+### 8. Tracking Step Creation
+**Scenario**: An administrator needs to know when steps were created, useful for auditing or troubleshooting.
+
+**Usage**: The "Created At" column shows the creation timestamp for each step, which can help:
+- Identify recently added steps
+- Understand the development timeline
+- Track changes and modifications
+- Correlate step creation with issues or changes
+
+### 9. Wizard Development Workflow
+**Scenario**: A team is collaboratively building a complex wizard with multiple steps.
+
+**Usage**: The Step Manager widget serves as the central hub during wizard development:
+1. Create initial steps using the "Create Step" button
+2. Monitor configuration completeness as steps are configured
+3. Verify step ordering aligns with the intended flow
+4. Remove test or prototype steps that are no longer needed
+5. Ensure all steps are complete before handing off for review
+
+## 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, ensuring the widget always has access to a wizard context.
+
+### Widget State
+
+The widget maintains a simple state containing:
+- `embeddedIn`: The asset ID of the wizard page being managed
+
+This state is automatically initialized when the widget is embedded and is used to:
+- Fetch the correct steps for the wizard
+- Generate URLs for the create step button
+- Validate permissions for actions
+
+### Table Configuration
+
+The widget uses a static table component with the following configuration:
+- **6 sortable columns** (all columns can be sorted)
+- **Hidden column**: The "Order in Wizard" column is hidden by default but available
+- **Default sort**: Sorted by Name (column 0) in ascending order
+- **Row selection**: Enabled to support delete actions
+- **Dynamic buttons**: Button URL includes the wizard ID parameter
+- **Dynamic actions**: Action URL includes both wizard ID and selected step IDs
+
+## Technical Architecture
+
+### Backend Components
+
+1. **Widget Definition** (`WizardStepManagerWidgetDefinition.java`)
+   - Defines widget metadata and embedding rules
+   - Manages widget state initialization
+   - Belongs to the Forms Wizard App
+   - Provides height configuration option
+
+2. **REST Service** (`StepManagerService.java`)
+   - **Get Steps Endpoint**: Returns list of all steps for a wizard
+     - URL: `{plugin}/wizard/stepmanager?wizardId={id}`
+     - Returns: `WizardStepsDto` containing step information
+   - **Table Buttons Endpoint**: Returns available table buttons (Create Step)
+     - URL: `{plugin}/wizard/stepmanager/tableButtons?wizardId={id}`
+     - Returns: `TableButtonsDto`
+   - **Table Actions Endpoint**: Returns available actions for selected steps (Delete)
+     - URL: `{plugin}/wizard/stepmanager/tableActions?wizardId={id}&selectedIds={ids}`
+     - Returns: `TableActionsDto`
+
+3. **Data Processing**
+   - Uses `StepFinder.getStepsForWizard()` to retrieve all steps associated with a wizard
+   - Uses `WizardPathFinder` to calculate the shortest path from start step to each step
+   - Uses `StepAnalysisService` to determine configuration completeness
+   - Uses `StepTypeExtension` to get localized step type names
+   - Validates permissions using `WizardPermissionsHelper.canEditWizard()`
+
+4. **Step Information DTO** (`StepInfoDto`)
+   Contains:
+   - `id`: Unique step identifier
+   - `name`: Display name of the step
+   - `identifier`: Step identifier string
+   - `type`: Localized step type name
+   - `configurationComplete`: Boolean flag for completeness
+   - `createdAt`: ISO 8601 formatted creation timestamp
+   - `positionInWizard`: Integer position in execution order
+   - `stepUrl`: Direct URL to the step's configuration page
+
+### Frontend Components
+
+1. **Angular Component** (`StepManager.component.ts`)
+   - Controller: `cfCplaceFormsWizardStepManager`
+   - Bindings: `wizardId` (input from widget state)
+   - Manages component lifecycle and event subscriptions
+   - Triggers data refresh on configuration changes
+   - Emits `WIZARD_RENDER_STATIC_TABLE` event to render the table
+
+2. **Service** (`StepManagerService`)
+   - Makes HTTP GET requests to the step manager REST endpoint
+   - Parses and returns step data as `WizardSteps` model
+   - Manages promise-based asynchronous data loading
+
+3. **Data Service** (`StepManagerDataService`)
+   - Initializes data from wizard ID
+   - Handles data caching and refresh logic
+   - Provides data to the component controller
+
+4. **Template** (`stepManager.htm`)
+   - Displays a loading indicator while data is fetching
+   - Renders a sortable table using the `forms-wizard-static-table` directive
+   - Displays step information with proper formatting
+   - Shows configuration completeness icon with tooltip
+   - Links step names to their configuration pages
+
+5. **Static Table Directive** (`formsWizardStaticTable`)
+   - Provides table sorting functionality
+   - Manages row selection for actions
+   - Loads and displays buttons and actions dynamically
+   - Handles table rendering and updates
+
+### Event-Driven Architecture
+
+The widget subscribes to platform events to maintain real-time accuracy:
+
+1. **Control Submit Event** (`events.NOTIFY_AFTER_CONTROL_SUBMIT`)
+   - Triggered when any form control is submitted
+   - Filtered to only act on step relationship attribute changes
+   - Refreshes the step list to reflect navigation changes
+
+2. **Activation State Changed Event** (`ACTIVATION_STATE_CHANGED`)
+   - Triggered when wizard activation state changes
+   - Refreshes the step list to reflect any activation-related updates
+
+This event-driven approach ensures the widget always shows current data without manual refresh.
+
+## Context and Relationships
+
+### Related Widgets in Forms Wizard Feature Set
+
+The Step Manager widget is part of a comprehensive widget ecosystem for configuring and managing Forms Wizards:
+
+1. **Wizard Analysis Widget** (`cf.cplace.formsWizard.wizardAnalysis`)
+   - Complements Step Manager by providing detailed validation
+   - The "Configuration Complete" indicator in Step Manager references the Analysis widget for details
+   - Used together to ensure all steps are properly configured
+
+2. **Wizard Activation Widget** (`cf.cplace.formsWizard.wizardActivation`)
+   - Controls wizard activation state
+   - Works with Step Manager to ensure steps are configured before activation
+
+3. **Wizard Localizations Widget** (`cf.cplace.formsWizard.wizardLocalizations`)
+   - Manages localized text for wizard UI elements
+   - Separate from step configuration managed by Step Manager
+
+4. **Step Editor Widget** (`cf.cplace.formsWizard.stepEditorWidget`)
+   - Configures individual step properties
+   - Step Manager links to step pages where this widget is used
+   - Step Manager provides the overview, Step Editor provides the details
+
+5. **Step Editor for Wizard Widget** (`cf.cplace.formsWizard.stepEditorForWizardWidget`)
+   - Alternative step editor embedded on wizard pages
+   - May be used alongside Step Manager on wizard configuration pages
+
+6. **Step Preview Widget** (`cf.cplace.formsWizard.stepPreview`)
+   - Shows a preview of how a step will appear to end users
+   - Complements Step Manager by providing visual feedback
+
+7. **Start Wizard Widget** (`cf.cplace.formsWizard.startWizardWidget`)
+   - End-user interface to launch configured wizards
+   - Executes the wizards that Step Manager helps configure
+
+8. **Horizontal Divider Widget** (`cf.cplace.formsWizard.horizontalDivider`)
+   - Visual separator for organizing wizard configuration UI
+
+### Typical Page Layout
+
+On a Forms Wizard configuration page, you would typically find:
+- **Step Manager Widget**: Central table showing all steps
+- **Wizard Analysis Widget**: Validation results and error messages
+- **Wizard Activation Widget**: Activate/deactivate controls
+- **Wizard Localizations Widget**: Multi-language configuration
+- **Step Editor for Wizard Widget**: Optional inline step editing
+
+This layout provides a complete wizard configuration experience on a single page.
+
+### 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**: Uses `StepFinder` utility to retrieve all steps for a wizard
+- **Wizard Path Finder**: Uses `WizardPathFinder` to calculate step positions
+- **Step Analysis Service**: Uses `StepAnalysisService` to determine configuration completeness
+- **Step Type Extension**: Uses `StepTypeExtension` to retrieve step type metadata
+- **Wizard Permissions Helper**: Uses `WizardPermissionsHelper` to validate edit permissions
+
+### Integration Points
+
+1. **Step Creation**: Creates new steps via `EditNewFirstStepHandler` with wizard context pre-filled
+2. **Step Deletion**: Deletes steps via `DeleteHandler` with confirmation modal
+3. **Step Navigation**: Links directly to step configuration pages using step URLs
+4. **Configuration Validation**: Integrates with step analyzers to show completeness status
+5. **Wizard Analysis**: The configuration complete indicator references the Wizard Analysis widget for detailed validation messages
+
+## Workflow Integration
+
+### Typical Wizard Development Workflow
+
+1. **Create Wizard** → Administrator creates a new wizard page
+2. **Add Steps** → Administrator uses Step Manager widget to create steps
+3. **Configure Steps** → Administrator clicks step names to configure each step
+4. **Monitor Completeness** → Step Manager shows configuration status
+5. **Validate Structure** → Wizard Analysis widget provides detailed validation
+6. **Activate Wizard** → Wizard Activation widget enables the wizard for use
+
+The Step Manager widget is central to steps 2-4 in this workflow.
+
+### Step Management Lifecycle
+
+1. **Creation**: Use "Create Step" button in Step Manager
+2. **Configuration**: Click step name to navigate to configuration
+3. **Monitoring**: View configuration completeness in Step Manager
+4. **Validation**: Check Wizard Analysis for detailed issues
+5. **Deletion**: Select step and use "Delete step" action
+6. **Ordering**: View step sequence in "Order in Wizard" column
+
+## Key Technical Notes
+
+- **Wizard Scoped**: Only shows steps associated with the embedding wizard
+- **Permission Aware**: Buttons and actions only appear for users with edit permissions
+- **Real-Time**: Automatically refreshes on configuration changes
+- **REST-Based**: All data fetched via REST API for clean separation of concerns
+- **Sortable**: All columns are sortable for flexible data organization
+- **Type Safety**: Only embeddable on wizard-type pages, enforced at platform level
+- **Path Calculation**: Uses graph algorithms to calculate shortest paths from start step
+- **Extensible**: Step types are provided via extension points, supporting custom step types
+
+## Localization
+
+All UI text is localized through the message bundle system:
+
+**English** (`messages_en.properties`):
+- Widget name: "Step Manager"
+- Description: "Overview widget of all existing Forms Wizard steps"
+- Table columns: "Name", "Identifier", "Type", "Configuration complete", "Created at", "Order in the wizard"
+- Actions: "Create Step", "Delete step"
+- Tooltip: "More information can be found in the 'Wizard Analysis' widget"
+
+**German** (`messages_de.properties`):
+- Widget name: "Schritt-Manager"
+- Description: "Übersichts-Widget über alle vorhandenen Forms-Wizard-Schritte"
+- Table columns: "Name", "Bezeichner", "Typ", "Konfiguration vollständig", "Erstellt am", "Reihenfolge im Wizard"
+- Actions: "Schritt anlegen", "Schritt löschen"
+- Tooltip: "Mehr Informationen können im Widget 'Wizard Analyse' gefunden werden"
+
+## Best Practices
+
+1. **Place on Wizard Configuration Pages**: The widget should be standard on all wizard configuration pages to provide easy step management
+
+2. **Combine with Analysis Widget**: Use alongside the Wizard Analysis widget for comprehensive wizard configuration feedback
+
+3. **Monitor Configuration Status**: Regularly check the "Configuration Complete" column to ensure all steps are properly configured
+
+4. **Use Step Ordering**: Review the "Order in Wizard" column to verify the intended flow sequence
+
+5. **Clean Up Unused Steps**: Regularly review and delete steps that are no longer part of the wizard flow
+
+6. **Link to Step Pages**: Use the clickable step names for quick navigation to step configuration
+
+7. **Check Before Activation**: Ensure all steps show complete configuration before activating the wizard
+
+## Performance Considerations
+
+- **Lazy Loading**: The table displays a loading indicator while fetching data
+- **Event Filtering**: Only refreshes on relevant events (step relation changes, activation changes)
+- **Efficient Path Finding**: Shortest path calculation is optimized using `WizardPathFinder`
+- **Server-Side Sorting**: All data processing happens on the backend for performance
+- **Minimal State**: Widget maintains minimal state to reduce memory footprint
+
+## Security and Permissions
+
+- **Edit Permissions**: Only users with wizard edit permissions can see buttons and actions
+- **Workspace Boundaries**: Steps are scoped to the wizard's workspace
+- **Access Control**: Button and action visibility is controlled server-side
+- **Safe Deletion**: Delete action requires explicit selection and confirmation
+- **Type Validation**: Embedding restrictions prevent misuse on non-wizard pages
+
+## Summary
+
+The Step Manager widget is an essential administrative tool for Forms Wizard configuration. It provides a comprehensive, sortable table view of all wizard steps with key metadata, configuration status indicators, and lifecycle management actions. The widget serves as the central hub for step management, enabling administrators to create, view, and delete steps while monitoring their configuration completeness and execution order. Its tight integration with other Forms Wizard widgets (particularly the Wizard Analysis widget) creates a complete configuration experience that ensures wizards are properly set up before activation.

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

@@ -0,0 +1,256 @@
+# Step Preview Widget Research
+
+**Widget ID:** `cf.cplace.formsWizard.stepPreview`
+**Repository:** `cplace-forms-wizard`
+**Definition Class:** `cf.cplace.formsWizard/src/main/java/cf/cplace/formsWizard/script/StepPreviewWidgetDefinition.java`
+
+---
+
+## 1. Widget Description
+
+The **Step Preview Widget** is a real-time visual preview widget that displays how a Forms Wizard step will appear to end users during wizard execution while it is being configured by an administrator.
+
+---
+
+## 2. Purpose and Core Functionality
+
+### What It Does
+
+The Step Preview Widget provides a **live, dynamic preview** of individual wizard steps during the configuration phase. It:
+
+1. **Fetches step data** from the backend via REST API (`/steps/preview` endpoint)
+2. **Renders the appropriate step view** based on the step type (Form, Info, Decision, Table, Script)
+3. **Auto-updates** when step configuration changes, listening to `STEP_CONFIG_UPDATED_EVENT`
+4. **Dynamically compiles** the correct Angular directive for each step type
+5. **Handles non-previewable steps** by showing a "This step does not have a view" message
+
+### Technical Architecture
+
+**Backend (Java):**
+- **Controller:** `StepPreviewController` exposes a GET endpoint at `/cplace-fe/cf.cplace.formsWizard/steps/preview`
+- **Service:** `StepPreviewCreatorService` generates preview data by:
+  - Finding the step entity by ID
+  - Determining the step type
+  - Checking if the step requires user interaction (`requiresUserInteraction()`)
+  - Creating a preview view using the step type's layouter
+
+**Frontend (TypeScript/Angular):**
+- **Component:** `StepPreviewController` manages the preview lifecycle
+- **Service:** `StepPreviewService` handles API calls to fetch preview data
+- **Dynamic Rendering:** Uses Angular's `$compile` service to dynamically create and inject the appropriate step preview directive
+- **Directive Mapping:** `StepTypeToDirectiveService` converts step type names (e.g., `cf.cplace.formsWizard.form`) to Angular directive names (e.g., `cf-cplace-forms-wizard-form`)
+
+### Key Implementation Details
+
+**From `StepPreviewWidgetDefinition.java:66-69`:**
+```java
+public void checkEmbeddableIn(PersistentEntity entity, WidgetEmbedding embedding) {
+    checkIsEmbeddedAsWidget(entity, embedding);
+    checkIsOneOfTheseTypes(entity, embedding, FormsWizardAppTypes.STEP.TYPE);
+}
+```
+- The widget can **only be embedded on Step pages** (type: `cf.cplace.formsWizard.step`)
+
+**From `StepPreviewComponent.ts:50-71`:**
+```typescript
+updatePreview() {
+    this.stepPreviewService.getPreview(this.stepId).then((result) => {
+        if (this.stepData && this.stepData.stepType === result.type) {
+            this.stepData = result;  // Same type: just update data
+        } else {
+            this.stepData = result;
+            // Different type: destroy old directive and create new one
+            this.$element.empty();
+            const elmName = this.stepTypeToDirectiveService.getDirectiveForPreview(result.type);
+            const stepViewElm = document.createElement(elmName);
+            const stepViewDirective = this.$compile(stepViewElm)(this.$scope.$new());
+            this.$element.append(stepViewDirective);
+        }
+    });
+}
+```
+- **Smart update logic:** If the step type hasn't changed, it updates data without re-rendering
+- **Full re-render:** If the step type changes, it destroys the old directive and creates a new one
+
+---
+
+## 3. Use Cases
+
+### Primary Use Case: Step Configuration Preview
+**Who:** Forms Wizard administrators/configurators
+**When:** While configuring individual steps of a Forms Wizard
+**Why:** To see how the step will appear to end users before activating the wizard
+
+**Scenario:**
+1. Administrator opens a Step page in the Forms Wizard
+2. The Step Preview Widget (typically placed in the bottom-left section of the page layout) shows a live preview
+3. Administrator edits step configuration using the Step Editor Widget (top-left section)
+4. The preview automatically updates to reflect changes
+5. Administrator can verify layout, attribute placement, and appearance before saving
+
+### Use Case 2: Multi-Step Type Support
+**Step Types Supported:**
+- **Form Steps:** Preview shows form fields, layout (single/multi-column), and UI elements (text, dividers)
+- **Info Steps:** Preview shows informational text and dynamically generated content
+- **Decision Steps:** Preview shows decision options and button labels
+- **Table Steps:** Preview shows table configuration
+- **Script Steps:** Shows "no preview available" (no user interaction)
+
+### Use Case 3: Configuration Validation
+**Who:** Forms Wizard administrators
+**Why:** To catch configuration issues early
+
+**Example:**
+- Form step with no attributes configured → Preview shows the issue visually
+- Duplicate attributes → Preview reflects the merged state
+- Invalid attribute selections → Preview shows errors or incomplete state
+
+---
+
+## 4. Configuration Concepts
+
+### Widget Embedding
+- **Automatically embedded** on Step pages via the default type layout defined in `FormsWizardAppTypes.STEP.WIDGET_CONTAINER_DEF`
+- Located in the **second row, first column** (6-column width) of the default Step page layout
+- Positioned **below the Step Editor Widget** for easy side-by-side configuration
+
+### Widget State
+**From `cfCplaceFormsWizardStepPreviewWidgetDirective.ts:3-5`:**
+```typescript
+export interface StepPreviewState {
+  embeddedIn: string;  // The ID of the Step page this widget is embedded in
+}
+```
+- Minimal configuration required
+- Widget automatically determines which step to preview based on the embedding page
+
+### Configuration Options
+The widget itself has **minimal configuration** (height can be set, as seen in the type definition: `"height": "500.0"`). The preview content is entirely driven by:
+1. The step being edited
+2. The step's type
+3. The step's configuration data
+
+### Non-Previewable Steps
+**From `StepPreviewCreatorService.java:34-36`:**
+```java
+if (!stepType.requiresUserInteraction()) {
+    return new StepDto(DUMMY_STEP_NAME, null);
+}
+```
+- Steps that don't require user interaction (e.g., Script steps) return a dummy step name
+- Frontend displays: **"This step does not have a view"** (message key: `stepPreviewNotApplicable`)
+
+---
+
+## 5. Context and Dependencies
+
+### Relationship to Other Widgets
+The Step Preview Widget is part of a **cohesive step configuration experience**:
+
+1. **Step Editor Widget** (`cf.cplace.formsWizard.stepEditor`)
+   - Placed in the top-left section of Step pages
+   - Provides the configuration UI
+   - Triggers `STEP_CONFIG_UPDATED_EVENT` when configuration changes
+   - The preview listens to this event and updates automatically
+
+2. **Step Editor for Wizard Widget** (`cf.cplace.formsWizard.stepEditorForWizard`)
+   - Quick editor embedded on Wizard pages
+   - Also works with the preview widget in the same way
+
+3. **Step Manager Widget** (`cf.cplace.formsWizard.stepManager`)
+   - Lists all steps in a wizard
+   - Users navigate from here to individual Step pages where the preview is shown
+
+### Forms Wizard Architecture
+The widget is part of the larger **Forms Wizard** feature set:
+
+- **Forms Wizard App:** Enables creation of multi-step input wizards
+- **Wizard Execution:** End users navigate through steps in runtime
+- **Step Types:** Extensible architecture supporting different step types (Form, Info, Decision, Table, Script)
+- **Step Configuration:** Administrators configure steps using editors and preview the result
+
+### Prerequisites
+- **Embedding Context:** Must be embedded on a page of type `cf.cplace.formsWizard.step`
+- **Step Type Registration:** The step type being previewed must be registered via the `StepType` extension point
+- **Step Type Directive:** Each previewable step type must provide an Angular directive for rendering the preview
+
+### Extension Points
+The widget leverages the **StepType extension point architecture**:
+- Each `StepType` implementation provides a `StepLayouter`
+- The layouter's `createPreview()` method generates preview data
+- Frontend dynamically loads the appropriate preview directive
+
+---
+
+## 6. Key Messages and Localization
+
+**Widget Name and Description:**
+- `script.StepPreviewWidgetDefinition.widgetName=Step Preview`
+- `script.StepPreviewWidgetDefinition.description=Preview widget that shows the step that is currently being configured`
+
+**User-Facing Messages:**
+- `formsWizardPlugin.javascriptMessages.stepPreviewNotApplicable=This step does not have a view`
+
+---
+
+## 7. Technical Implementation Notes
+
+### Dynamic Directive Compilation
+The widget uses Angular's `$compile` service to dynamically create step-type-specific preview directives:
+- **Step Type:** `cf.cplace.formsWizard.form`
+- **Becomes Directive:** `cf-cplace-forms-wizard-form`
+
+**Transformation Logic (`StepTypeToDirectiveService`):**
+1. Convert camelCase to snake-case with dashes
+2. Replace all dots with dashes
+3. Example: `cf.cplace.formsWizard.form` → `cf-cplace-forms-wizard-form`
+
+### Event-Driven Updates
+The widget listens to the `STEP_CONFIG_UPDATED_EVENT` on Angular's `$rootScope`:
+```typescript
+this.$rootScope.$on(STEP_CONFIG_UPDATED_EVENT, (event, args) => {
+    this.updatePreview();
+});
+```
+This ensures the preview stays in sync with configuration changes in real-time.
+
+### REST API
+**Endpoint:** `GET /cplace-fe/cf.cplace.formsWizard/steps/preview?stepId={stepId}`
+**Response:** `StepDto` containing:
+- `type`: The step type name (e.g., `cf.cplace.formsWizard.form`)
+- `data`: Step-specific view data (layout, attributes, configuration)
+
+---
+
+## 8. Default Page Layout Integration
+
+The Step Preview Widget is **pre-configured** in the default layout for Step pages:
+
+**From `FormsWizardAppTypes.java:171-384`:**
+```java
+Row.fromColumns(
+    new Column(9, StepEditorWidget),      // Left: 9-column editor
+    new Column(3, AttributesWidget)        // Right: 3-column attributes
+),
+Row.fromColumns(
+    new Column(6, StepPreviewWidget),      // Left: 6-column preview
+    new Column(6)                          // Right: empty
+)
+```
+
+This layout creates a **two-row configuration interface**:
+- **Top row:** Editor (9 cols) + Attributes panel (3 cols)
+- **Bottom row:** Preview (6 cols) + Empty space (6 cols)
+
+---
+
+## 9. Summary
+
+The **Step Preview Widget** is a specialized configuration tool that provides real-time visual feedback during Forms Wizard step configuration. It bridges the gap between configuration and execution by showing administrators exactly how their step will appear to end users. The widget is tightly integrated with the Step Editor Widget and the broader Forms Wizard architecture, leveraging Angular's dynamic compilation capabilities to support multiple step types through a pluggable directive system.
+
+**Key Strengths:**
+- Real-time preview during configuration
+- Support for multiple step types via dynamic directives
+- Automatic updates via event-driven architecture
+- Minimal configuration required (embedded by default)
+- Graceful handling of non-previewable steps