@cplace/test-mcp-server 1.0.0 → 1.1.0

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

@@ -0,0 +1,580 @@
+# Widget Research: cf.cplace.dragAndDropImageView.imageWithTextWidget
+
+## Widget Identity
+
+- **Widget ID**: `cf.cplace.dragAndDropImageView.imageWithTextWidget`
+- **Display Name**: Image with text
+- **Repository**: cplace-paw
+- **Plugin**: cf.cplace.dragAndDropImageView
+- **Definition Class**: `ImageWithTextWidgetDefinition.java`
+
+## 1. Purpose
+
+The Image with Text widget extends the basic drag-and-drop image viewer by adding configurable text overlay functionality, enabling users to display images with descriptive or contextual text positioned on top of the image with rich HTML formatting support.
+
+### Short Description
+
+Displays an image from a file reference attribute with customizable text overlay supporting rich HTML formatting and flexible positioning.
+
+## 2. Core Functionality
+
+### What It Does
+
+The widget provides all the functionality of the base Image widget plus text overlay capabilities:
+
+**Inherited from Base Image Widget:**
+1. **Image Display**: Shows the image referenced by a specified Page attribute
+2. **Upload Interface**: Provides drag-and-drop file upload capability with a file picker button
+3. **Image Selection**: Displays a table of available images on the Page for quick selection
+4. **Image Removal**: Allows users to remove the current image reference
+5. **Scaling Options**: Supports multiple image scaling modes (horizontal, vertical, fit)
+6. **Lightbox Integration**: Opens images in a lightbox view when clicked
+
+**Additional Text Overlay Functionality:**
+1. **Text Overlay**: Displays configurable text on top of the image
+2. **Rich HTML Support**: Text can include HTML formatting (bold, italic, colors, links, etc.)
+3. **Flexible Positioning**: Text can be positioned at various locations on the image
+4. **Dynamic Content**: Text can be pulled from Page attributes or static configuration
+
+### Technical Implementation
+
+The widget extends the base `DragAndDropImageViewWidgetDefinition` and adds:
+
+- **Text Rendering Layer**: Overlays HTML-formatted text on the displayed image
+- **Position Control**: CSS-based positioning system for text placement
+- **Attribute Binding**: Can display text from Page attributes dynamically
+- **Style Integration**: Supports inline styles and CSS classes for text appearance
+
+## 3. Use Cases
+
+### Primary Use Cases
+
+1. **Hero Banners with Captions**: Display promotional images with title text or call-to-action overlays
+   - Example: Project landing page with "Welcome to Project X" overlaid on banner image
+
+2. **Labeled Visual Content**: Add descriptive text to images for context
+   - Example: Process diagram with "Phase 1: Planning" overlaid on diagram section
+
+3. **Call-to-Action Images**: Combine visual appeal with actionable text
+   - Example: Feature image with "Learn More" or "Get Started" button text
+
+4. **Annotated Screenshots**: Add explanatory text to screenshots or documentation images
+   - Example: UI screenshot with "Click here to start" pointing to a specific area
+
+5. **Status Indicators**: Display dynamic status text over visual representations
+   - Example: Project status board with status text overlaid on project image
+
+6. **Marketing/Communication Pages**: Create visually rich communication with minimal effort
+   - Example: News article with headline overlaid on featured image
+
+7. **Dashboard Headers**: Combine visual branding with key metrics or titles
+   - Example: Department dashboard with department name overlaid on theme image
+
+### When to Use This Widget
+
+- You need to display a **single image with text** on a Page
+- The text should be **positioned on/over the image** (not beside it)
+- You want **rich text formatting** (colors, fonts, sizes, links)
+- The text content may need to be **dynamic** (from Page attributes)
+- Users need **easy upload and management** of the image
+- You want a **professional, modern appearance** with text overlays
+
+### When NOT to Use This Widget
+
+- Text should appear **beside or below** the image (consider using layout containers)
+- You need to display **multiple images** (consider image gallery widgets)
+- The text is very long (overlays work best with short, impactful text)
+- You need complex text layouts or multiple text blocks (consider separate text widgets)
+- Read-only image display without upload capability (consider simpler image display widgets)
+
+## 4. Configuration Concepts
+
+### Inherited Configuration from Base Widget
+
+**Reference Attribute** (`ATTRIBUTE_NAME`)
+- The Page attribute that stores the image reference
+- **Constraints**:
+  - Must be a reference attribute
+  - Multiplicity: "At most one Value" (maximalOne)
+  - Content type: Document (File)
+  - Must be editable by the user
+
+**Scaling** (`SCALING`)
+- Controls how the image fits within the widget area
+- Options: `horizontal`, `vertical`, `fit`
+
+**Fixed Height** (`FIXED_HEIGHT`)
+- Optional maximum height in pixels
+- Constrains the image display area
+
+**Show Frame** (`SHOW_FRAME`)
+- Boolean toggle for displaying the widget frame
+- Default: `true`
+
+**Localized Title** (`LOCALIZED_TITLE`)
+- Multi-language widget title
+
+### Text Overlay Configuration
+
+**Text Content** (Configuration attribute - name TBD)
+- The text to display over the image
+- Supports:
+  - **Static text**: Configured directly in widget settings
+  - **Dynamic text**: Pulled from a Page attribute
+  - **Rich HTML**: Full HTML formatting support (bold, italic, colors, sizes, links)
+
+**Text Position** (Configuration attribute - name TBD)
+- Controls where the text appears on the image
+- Likely options:
+  - Top-left, Top-center, Top-right
+  - Middle-left, Middle-center, Middle-right
+  - Bottom-left, Bottom-center, Bottom-right
+
+**Text Styling** (Configuration options - specifics TBD)
+- Font size, color, background
+- Text shadow or outline for readability
+- Padding/margins around text
+- Background overlay (semi-transparent box behind text)
+
+### Typical Configuration Patterns
+
+1. **Title Overlay Pattern**
+   - Position: Bottom-left or Center
+   - Style: Large, bold text with semi-transparent dark background
+   - Use case: Hero sections, feature highlights
+
+2. **Caption Pattern**
+   - Position: Bottom-left or Bottom-right
+   - Style: Smaller text, possibly italicized
+   - Use case: Photo credits, image descriptions
+
+3. **Call-to-Action Pattern**
+   - Position: Center or Bottom-center
+   - Style: Button-like appearance with contrasting colors
+   - Use case: Interactive elements, navigation prompts
+
+## 5. User Interaction Flow
+
+### Configuration Phase (Design/Admin)
+
+1. Add widget to Page layout
+2. Configure image attribute reference
+3. Set image scaling and display options
+4. Configure text content (static or attribute-based)
+5. Choose text position on image
+6. Style text appearance (color, size, background)
+7. Optionally configure frame and title settings
+
+### When No Image Is Set
+
+1. Widget displays **upload button** with file picker
+2. Below that, a **table of available images**
+3. **Text overlay not visible** until image is present
+4. User can:
+   - Click "Upload image" to browse and upload
+   - Drag and drop a file onto the widget
+   - Select an existing image from the table
+
+### During Upload
+
+1. Progress bar appears showing upload percentage
+2. When complete, the image displays automatically
+3. **Text overlay appears** positioned on the image
+4. The attribute reference is updated
+
+### When Image Is Set
+
+1. Image displays with configured scaling
+2. **Text overlay renders** on top of the image with configured positioning and styling
+3. **Remove button** (red X) appears in top-right corner
+4. Clicking the image opens it in a lightbox view (with or without text overlay)
+5. Clicking remove:
+   - Clears the attribute reference
+   - Returns to the "no image" state
+   - Text overlay disappears
+
+### Dynamic Text Updates
+
+If text is bound to a Page attribute:
+- Text updates automatically when the attribute value changes
+- No page reload required
+- Maintains consistent positioning and styling
+
+### Permission Handling
+
+Inherits permission model from base widget:
+- If user lacks **read permissions** on referenced Document: Shows "insufficient rights" message
+- If user lacks **edit permissions** on attribute: Upload/remove buttons hidden
+- If user lacks **create document permissions** on Page: Upload disabled
+- Text display respects read permissions on any bound attributes
+
+## 6. Related Context
+
+### Widget Family
+
+This widget is the middle tier in a three-widget family:
+
+1. **cf.cplace.dragAndDropImageView.widget** (Image)
+   - Base widget: Image display with upload
+   - No text overlay
+
+2. **cf.cplace.dragAndDropImageView.imageWithTextWidget** (Image with text) ← **THIS WIDGET**
+   - Extends base widget
+   - Adds text overlay with positioning and HTML formatting
+   - Single image focus
+
+3. **cf.cplace.dragAndDropImageView.imageWithTextAndListWidget** (Image with text and list)
+   - Extends image with text widget
+   - Adds search/list component below the image
+   - Combines image header with related entity list
+
+### When to Choose Which Widget
+
+| Requirement | Recommended Widget |
+|------------|-------------------|
+| Just need image display and upload | Base Image widget |
+| Need text overlaid on image | **Image with text widget** |
+| Need image + text + related entities list | Image with text and list widget |
+
+### Dependencies
+
+- **cplace Platform**: Core platform functionality
+- **Page Architecture**: Must be embedded in a Page entity
+- **Document Management**: Relies on Document entity type and file handling
+- **Permission System**: Respects read/edit permissions on attributes and entities
+- **HTML Rendering**: Requires support for HTML in text content
+- **CSS Styling**: Uses CSS for text positioning and appearance
+
+### Technical Prerequisites
+
+- Page must have a reference attribute configured with:
+  - Type: Reference to Document
+  - Multiplicity: At most one value
+- User must have appropriate permissions on:
+  - The Page (to edit)
+  - The attribute (to edit)
+  - Document creation (to upload)
+- If using dynamic text:
+  - Source attribute must exist and be readable by user
+
+## 7. Implementation Details
+
+### Frontend (TypeScript/AngularJS)
+
+**Extends**: `DragAndDropImageViewCtrl` (base widget controller)
+
+**Additional Controller Responsibilities**:
+- Manages text content (static or from attribute)
+- Handles text positioning and styling
+- Renders HTML content safely
+- Updates text when bound attributes change
+- Manages text overlay layer on image
+
+**Additional State Model** (extends `IDragAndDropImageViewState`):
+```typescript
+{
+  // Inherited from base
+  insertUrl: string;
+  removeUrl: string;
+  uploadUrl: string;
+  scaling: 'horizontal' | 'vertical' | 'fit';
+  maxHeight: number;
+  insufficientRights: boolean;
+  imageSrc: string;
+  availableImages: IImageDocument[];
+
+  // Text overlay additions (expected)
+  textContent: string;           // HTML-formatted text
+  textPosition: string;          // Position identifier
+  textStyle: {                   // Styling configuration
+    fontSize?: string;
+    color?: string;
+    backgroundColor?: string;
+    // ... other style properties
+  };
+  dynamicTextSource?: string;    // Attribute name if dynamic
+}
+```
+
+### Backend (Java)
+
+**Widget Definition**: `ImageWithTextWidgetDefinition`
+- Extends `DragAndDropImageViewWidgetDefinition`
+- Defines additional configuration attributes for text
+- Builds enhanced widget state JSON including text configuration
+- Handles dynamic text resolution from Page attributes
+- Validates text source attributes
+
+**Configuration Type**: Extends `DRAG_AND_DROP_IMAGE_WIDGET.TYPE`
+- Additional TypeDef attributes for:
+  - Text content source (static or attribute reference)
+  - Text positioning
+  - Text styling options
+  - HTML formatting options
+
+**Handlers**: Inherits from base widget
+- `UploadHandler`: No changes needed
+- `InsertHandler`: No changes needed
+- `RemoveHandler`: No changes needed
+- Text rendering is client-side
+
+### Styling
+
+Extends base widget CSS with additions for:
+- **Text overlay layer**: Absolute positioning over image
+- **Position classes**: `.text-top-left`, `.text-center`, `.text-bottom-right`, etc.
+- **Text container styling**: Background, padding, borders
+- **Readability enhancements**: Text shadows, contrast overlays
+- **Responsive text sizing**: Text scales appropriately on different screen sizes
+- **HTML content styling**: Styles for bold, italic, links, etc. within overlay
+
+## 8. Key Design Decisions
+
+### Why Overlay Text Instead of Separate Elements?
+
+Text overlay provides several advantages:
+- **Visual cohesion**: Text and image treated as single visual unit
+- **Space efficiency**: No additional vertical space needed
+- **Design flexibility**: Modern, magazine-style layouts
+- **Attention focus**: Text draws eye to specific parts of image
+- **Professional appearance**: Polished, contemporary look
+
+### HTML Support for Rich Formatting
+
+Supporting HTML in text overlays allows:
+- **Emphasis**: Bold, italic, underline for key words
+- **Colors**: Brand colors or semantic colors (red for warnings, etc.)
+- **Links**: Make text actionable with hyperlinks
+- **Lists**: Structured information in overlay
+- **Sizing**: Different font sizes for hierarchy
+- **Flexibility**: Future-proof for additional formatting needs
+
+### Positioning Options
+
+Multiple position choices enable:
+- **Compositional balance**: Place text where image has space
+- **Visual hierarchy**: Center for primary messages, corners for secondary
+- **Adaptability**: Different images have different "safe zones"
+- **Use case variety**: Headers, captions, labels all have natural positions
+
+### Inheritance from Base Widget
+
+Building on the base widget ensures:
+- **Code reuse**: No duplication of image management logic
+- **Consistency**: Same image handling across widget family
+- **Maintainability**: Fixes to base widget benefit all variants
+- **Learning curve**: Users familiar with base widget understand this one quickly
+
+## 9. Limitations and Constraints
+
+### Inherited Constraints from Base Widget
+
+- **Must** be a reference attribute to Document type
+- **Must** have "At most one value" multiplicity
+- Only embeddable in **Page** entities
+- Single image only
+- Relies on platform file upload restrictions
+
+### Text Overlay Constraints
+
+**Text Length**
+- Long text may not fit well on images
+- No automatic text wrapping controls (depends on CSS)
+- Readability decreases with longer content
+
+**HTML Complexity**
+- Complex HTML structures may not render well in overlay
+- Limited space constrains layout possibilities
+- May have HTML sanitization restrictions for security
+
+**Positioning Limitations**
+- Fixed position options (not pixel-perfect placement)
+- May not align perfectly with specific image features
+- Position behavior may vary with different image sizes
+
+**Readability Challenges**
+- Text may be hard to read on busy image backgrounds
+- Requires careful color/contrast choices
+- May need semi-transparent backgrounds for legibility
+
+**Dynamic Text Considerations**
+- Attribute-based text may change length unexpectedly
+- No validation that text fits in chosen position
+- Requires attribute read permissions
+
+## 10. Best Practices
+
+### Image Selection
+
+- Choose images with **clear areas** for text placement
+- Avoid overly busy backgrounds where text will appear
+- Consider **aspect ratio** when selecting scaling mode
+- Use high-quality images that scale well
+
+### Text Content
+
+- Keep text **short and impactful** (headlines, not paragraphs)
+- Use **clear, readable fonts** at appropriate sizes
+- Ensure **high contrast** between text and image background
+- Test readability at different screen sizes
+
+### Text Positioning
+
+- Position text in **visually quiet areas** of the image
+- Follow **compositional rules** (rule of thirds, etc.)
+- Consider **reading patterns** (left-to-right, top-to-bottom)
+- Avoid covering important image content
+
+### Styling for Readability
+
+- Use **semi-transparent backgrounds** behind text when needed
+- Apply **text shadows** or outlines for contrast
+- Choose **large enough font sizes** for easy reading
+- Test on **different devices** and screen sizes
+
+### Dynamic Text Usage
+
+- Validate that **attribute values are appropriate length**
+- Provide **default/fallback text** if attribute is empty
+- Consider **formatting rules** for attribute content
+- Document expected attribute content format
+
+## 11. Common Patterns and Examples
+
+### Pattern 1: Hero Section with Title
+
+**Configuration:**
+- Large image with brand/project visual
+- Text: Page title or headline (from attribute)
+- Position: Center or bottom-center
+- Style: Large, bold, white text with dark semi-transparent background
+
+**Use case:** Landing pages, project overviews, feature highlights
+
+### Pattern 2: Image Card with Caption
+
+**Configuration:**
+- Medium-sized image
+- Text: Short description or category label (static or attribute)
+- Position: Bottom-left
+- Style: Medium text, light background, subtle shadow
+
+**Use case:** Card layouts, gallery items, category browsing
+
+### Pattern 3: Call-to-Action Banner
+
+**Configuration:**
+- Wide banner image
+- Text: Action phrase with link (HTML with anchor tag)
+- Position: Center
+- Style: Button-like appearance, bold colors, large text
+
+**Use case:** Navigation prompts, feature announcements, promotional content
+
+### Pattern 4: Labeled Diagram
+
+**Configuration:**
+- Technical diagram or process flow
+- Text: Phase/stage label (static)
+- Position: Top-left or top-center
+- Style: Simple, clean text, minimal background
+
+**Use case:** Process documentation, phase indicators, workflow diagrams
+
+### Pattern 5: Status Dashboard Header
+
+**Configuration:**
+- Thematic/brand image
+- Text: Status or metric value (from attribute)
+- Position: Top-right or bottom-right
+- Style: Color-coded text (red/yellow/green), medium size
+
+**Use case:** Dashboards, status boards, monitoring pages
+
+## 12. Comparison with Alternatives
+
+### vs. Base Image Widget
+
+| Feature | Base Image | Image with Text |
+|---------|-----------|----------------|
+| Image display | ✓ | ✓ |
+| Upload/manage | ✓ | ✓ |
+| Text overlay | ✗ | ✓ |
+| HTML formatting | ✗ | ✓ |
+| Complexity | Lower | Moderate |
+| Configuration | Simpler | More options |
+
+**Choose Image with Text when:** You need text on the image, not beside it.
+
+### vs. Separate Image + Text Widgets
+
+| Feature | Image + Text Widgets | Image with Text |
+|---------|---------------------|----------------|
+| Visual cohesion | Separate elements | Single unit |
+| Space efficiency | Uses more vertical space | Compact |
+| Layout flexibility | More flexible placement | Fixed overlay |
+| Configuration | Two widgets to configure | Single configuration |
+| Text positioning | Beside/below image | On top of image |
+
+**Choose Image with Text when:** You want modern overlay style, space efficiency, visual cohesion.
+
+### vs. Image with Text and List Widget
+
+| Feature | Image with Text | Image with Text and List |
+|---------|----------------|------------------------|
+| Image + text | ✓ | ✓ |
+| Related entities list | ✗ | ✓ |
+| Use case | Visual focus | Visual + data |
+| Complexity | Moderate | Higher |
+| Vertical space | Less | More |
+
+**Choose Image with Text when:** You don't need a related entities list, just image with overlay.
+
+## 13. Search Keywords
+
+For finding this widget in codebase or documentation:
+
+- Image with text widget
+- Text overlay image widget
+- Image caption widget
+- Drag and drop image with text
+- HTML text overlay widget
+- Image banner with text
+- cplace image text widget
+- cf.cplace.dragAndDropImageView.imageWithTextWidget
+- ImageWithTextWidgetDefinition
+- Hero banner widget
+- Labeled image widget
+
+## 14. Additional Notes
+
+### Accessibility Considerations
+
+- Text overlays should have sufficient color contrast
+- Alt text for images should include overlay text content
+- Consider screen reader behavior with overlaid text
+- Test keyboard navigation if text includes links
+
+### Performance Considerations
+
+- HTML rendering adds minimal overhead
+- Dynamic text updates are efficient (attribute watching)
+- Image loading performance same as base widget
+- No additional backend calls for text rendering
+
+### Maintenance and Evolution
+
+This widget is part of a stable, mature widget family. Updates typically involve:
+- Enhanced text positioning options
+- Additional styling capabilities
+- Improved responsive behavior
+- Better accessibility features
+
+### Related Documentation
+
+For complete understanding of this widget, also review:
+- Base widget documentation: `cf.cplace.dragAndDropImageView.widget`
+- Extended widget documentation: `cf.cplace.dragAndDropImageView.imageWithTextAndListWidget`
+- cplace Page attribute documentation
+- Document management and file upload documentation
+- HTML sanitization and security guidelines