@cplace/test-mcp-server 0.1.15 → 1.1.0

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

@@ -0,0 +1,332 @@
+# Widget Research: cf.cplace.ctts.main.widget
+
+## Widget Overview
+
+**Widget ID:** `cf.cplace.ctts.main.widget`
+**Repository:** cplace-ctts
+**Plugin:** cf.cplace.ctts.main
+**Definition Class:** `cf.cplace.ctts.main.script.MainWidgetDefinition`
+
+## Purpose
+
+The CTTS (cplace Time Tracking System) main widget is an interactive time tracking and booking interface that allows users to record, manage, and monitor their work hours across various projects and targets within specified time periods.
+
+**Short Description:**
+This widget provides a comprehensive time tracking grid interface where users can book hours to different targets (projects/activities), view time in different formats and time units (day/week/month), manage favorites, and submit time entries for approval through a monthly release workflow.
+
+## Core Functionality
+
+### 1. Time Booking Grid
+- **Interactive data grid** using Handsontable for recording time bookings
+- Users book time entries to various **targets** (projects, activities, or other entities defined in the system)
+- Each booking contains:
+  - Date
+  - Booked time (in seconds, supports negative values for corrections)
+  - Target reference (what the time was booked to)
+  - Optional description
+  - User reference
+
+### 2. Time Period Views
+The widget supports multiple time unit views:
+- **Day view**: Track time on a daily basis
+- **Week view** (default): See and edit an entire week at once
+- **Month view**: View and manage monthly time bookings
+- Optional "one value for month view" mode where a single total can be entered for the entire month
+
+### 3. Calendar Integration
+- **Calendar view** toggle for visual date selection
+- **Week picker** component for easy navigation between time periods
+- Weeks in the calendar can be made clickable (configurable)
+- "Today" button to quickly jump to the current date/week
+
+### 4. Time Format Options
+Users can toggle between different time format displays:
+- **Punctual time format**: Hours and minutes (e.g., "8:30")
+- **Decimal time format**: Decimal representation (e.g., "8.5" or "8,5" depending on locale)
+- Format preference is saved per user via UserConfig
+
+### 5. Target Management
+- **Add targets**: Users can add new booking targets through a dialog
+- **Favorites system**: Mark frequently-used targets as favorites for quick access
+- **Target filtering**: Configurable filters to control which targets users can select
+- **Distribution percentage**: Allocate time across targets by percentage
+- **Subsequent bookings**: Special mode for adding bookings to past months (with configurable limit)
+
+### 6. Representative/Delegate Booking
+- **Representative mode**: Authorized users can book time on behalf of other users
+- Configurable groups for:
+  - Representative time bookers (can only do representative bookings)
+  - Delegates (can be represented by others)
+- Visual indicator showing which user's time is being tracked
+
+### 7. Monthly Release Workflow
+- **Release month**: Submit time entries for a completed month
+- **Lock/unlock months**: Prevent changes to finalized time periods
+- **Revoke release**: Undo a month's release if needed
+- Privileged groups can edit locked cells
+- Admin override capabilities (configurable)
+
+### 8. Data Validation & Controls
+- **Maximum booking time per day**: Configurable limit (default: 10 hours)
+- **Overbook limit**: Warning threshold when exceeding daily limits
+- **Time fraction precision**: Configurable minimum time increment (1 sec, 1 min, 15 min, 30 min, 60 min)
+- **Negative bookings**: Optional support for negative time entries (corrections)
+- **Holiday/weekend handling**: Configurable whether holidays, Saturdays, and Sundays are bookable workdays
+- **Monthly negative bookings**: Control whether overall monthly total can be negative
+
+### 9. Data Display Options
+- **Sum line**: Shows totals, optionally with difference from target hours
+- **Sidebar**: Displays cell details and configurable attributes of selected targets
+- **Extended title text**: Larger header rows with more information
+- **Manual column resize**: Allow users to adjust column widths
+
+### 10. Data Actions
+- **Save**: Persist time booking changes
+- **Discard**: Revert unsaved changes
+- **Delete**: Remove booking entries for the current week
+- **Undo modal**: Confirmation dialog for destructive actions
+
+## Use Cases
+
+### Primary Use Cases
+
+1. **Individual Time Tracking**
+   - Employees track their daily/weekly work hours
+   - Book time to projects, tasks, or activities they work on
+   - View their time allocation across different targets
+   - Submit monthly timesheets for approval
+
+2. **Project Time Booking**
+   - Record time spent on specific projects or work packages
+   - Distribute time across multiple projects in a single day
+   - Track project-related hours for billing or resource planning
+
+3. **Administrative Time Management**
+   - Managers or assistants book time on behalf of team members
+   - HR or admin staff manage time entries for multiple users
+   - Corrections and adjustments to historical time data
+
+4. **Monthly Time Reporting**
+   - Users compile and submit their monthly working hours
+   - Managers review and approve released months
+   - Lock finalized periods to prevent further changes
+
+5. **Flexible Work Schedule Tracking**
+   - Support for part-time employees with varying hours
+   - Track overtime through overbook limits and warnings
+   - Handle irregular schedules (weekends, holidays)
+
+### Secondary Use Cases
+
+6. **Absence and Corrections**
+   - Use negative bookings to correct over-reported time
+   - Track non-working time on specific days
+
+7. **Multi-Workspace Operations**
+   - Users work across different organizational workspaces
+   - Filter targets by workspace
+   - Optionally restrict visibility to specific workspaces
+
+8. **Favorites and Quick Booking**
+   - Create favorite targets for frequently-used projects
+   - Quick time entry for routine activities
+   - Distribution percentages for regular allocations
+
+9. **Subsequent Booking (Retroactive Entries)**
+   - Add time entries to past months within a configurable limit
+   - Handle forgotten or delayed time reporting
+
+## Configuration Concepts
+
+### Widget-Level Configuration
+
+The widget can be configured with the following options:
+
+1. **Localized Title** (`LOCALIZED_TITLE`)
+   - Custom title for the widget instance
+
+2. **Height** (`HEIGHT`)
+   - Fixed height setting, or auto-height if not specified
+
+3. **Time Unit Per Page Mode** (`TIME_UNIT_PER_PAGE_MODE`)
+   - Options: Day, Week, Month
+   - Default: Month
+   - Controls the primary view granularity
+
+4. **Weeks in Calendar Are Clickable** (`WEEKS_IN_CALENDAR_ARE_CLICKABLE`)
+   - Boolean (default: true)
+   - Whether clicking weeks in calendar view changes the main grid
+
+5. **Default Time Format for Bookings** (`DEFAULT_TIME_FORMAT_FOR_BOOKINGS`)
+   - Options: Punctual (hours:minutes) or Decimal
+   - Default: Punctual
+   - Sets the initial time format for new users
+
+### App-Level Configuration
+
+The widget behavior is heavily influenced by app configuration settings in the workspace:
+
+#### Access Control
+- **Allowed Groups**: Groups with permission to use the widget
+- **Representative Time Booker Groups**: Users who can only do representative bookings
+- **Representative Type**: Groups that can act as delegates
+- **Privilege Groups**: Extended rights for editing locked/released entries
+
+#### Target Selection
+- **Visibility Type**: All targets vs. only permitted targets
+- **Select Workspaces**: Limit target selection to specific workspaces
+- **Select Type Names**: Define which entity types can be used as targets
+- **Select Type Attributes**: Attributes to display in the sidebar
+- **Target Filter Script**: Custom JavaScript filter for target selection
+- **Show Data From This Workspace Only**: Restrict displayed data by workspace
+
+#### Time Booking Rules
+- **Max Time Fraction**: Minimum bookable time increment (1 sec to 60 min)
+- **Default Maximum Working Hours Per Day**: Standard workday length
+- **Overbook Limit Per Day**: Warning threshold for excessive hours
+- **Allow Booking Only In Current Month**: Restrict historical entries
+- **Months Limit For Subsequent Booking**: How far back subsequent bookings are allowed
+- **Allow Negative Numbers For Bookings**: Enable correction entries
+- **Allow Overall Monthly Negative Bookings**: Allow negative monthly totals
+
+#### Workday Configuration
+- **Holidays Are Workdays**: Whether public holidays are bookable
+- **Saturdays Are Workdays**: Saturday booking enabled
+- **Sundays Are Workdays**: Sunday booking enabled
+
+#### Display & Behavior
+- **Targets As Favorites**: New targets default to favorites
+- **Show Difference In Sum Line**: Display variance from target hours
+- **Extended Title Text**: Larger header rows
+- **Manual Column Resize**: User-adjustable column widths
+- **One Value For Month View**: Accept single monthly total instead of daily breakdown
+- **Can Admins Edit Locked Cells**: Admin override for locked periods
+- **Allow Editing Of Non-Addable Targets**: Edit cells for targets no longer in selection
+
+#### Data Import
+- **Allowed Groups Import Aggregated Times**: Groups permitted to import time data files
+
+## Technical Architecture
+
+### Key Components
+
+1. **Definition Layer**
+   - `MainWidgetDefinition`: Widget registration and configuration type binding
+   - `MainWidgetConfiguration`: Widget-specific configuration type definition
+   - `MainAppConfiguration`: App-level configuration type definition
+
+2. **Data Layer**
+   - `TimeBookingData`: Individual time booking entries (date, time, user, description)
+   - `BookingRow`: Groups bookings by target
+   - `MonthFlag`: Tracks released/locked month status
+   - `TargetFlag`: Flags for booking targets
+   - `FavoriteTarget`: User's favorite target references
+   - `BookingRowMetaData`: Additional metadata for booking rows
+
+3. **Handler Layer** (Backend API endpoints)
+   - Grid data loading and saving
+   - Calendar view data
+   - Favorites management (save/delete)
+   - Target selection and filtering
+   - Release dialog and submission
+   - Representative selection and clearing
+   - Time format preferences
+   - Distribution percentage management
+   - Locked months checking
+
+4. **Frontend Layer**
+   - AngularJS-based UI components
+   - Handsontable integration for grid display
+   - Week picker component
+   - Calendar component
+   - Sidebar for cell details
+   - Various modal dialogs (undo, release, warnings)
+
+5. **Extension Points**
+   - `AdditionalHolidaysAppExtension`: Plugin-provided holiday calendars
+   - `TargetTimeManager`: Calculates target working hours per user/date
+   - `RepresentativeExtensionPointOnceADayTask`: Daily task for representative updates
+   - Custom filters for person and target selection
+
+### Data Handlers
+
+The widget communicates with the backend through multiple specialized handlers:
+
+- **GridDataLoadHandler**: Load booking data for display
+- **GridDataSaveHandler**: Persist time booking changes
+- **CalendarViewDataHandler**: Provide calendar-specific data
+- **FavoritesDataSaveHandler/DeleteHandler**: Manage favorite targets
+- **EditReleaseDialogHandler**: Open release dialog
+- **SubmitReleaseDialogHandler**: Process month release/revoke
+- **RepresentativeEditHandler/ClearHandler**: Manage representative mode
+- **DistributionPercentageWriteHandler**: Save distribution settings
+- **TimeFormatSaveHandler**: Persist user time format preference
+- **LockedMonthsCheckerHandler**: Validate month lock status
+
+## Relationships to Other Widgets
+
+The CTTS main widget is part of a larger time tracking solution that includes:
+
+1. **Employee Report Grid Widget** (`cf.cplace.ctts.main.employeeReportGrid`)
+   - Related reporting widget for employee-centric views
+
+2. **Employee Report Chart Widget** (`cf.cplace.ctts.main.employeeReportChart`)
+   - Visual/chart representation of employee time data
+
+3. **Project Manager Report Grid Widget** (`cf.cplace.ctts.main.projectmanagerReportGrid`)
+   - Project-focused reporting for managers
+
+4. **Project Manager Report Chart Widget** (`cf.cplace.ctts.main.projectmanagerReportChart`)
+   - Chart visualization for project manager reports
+
+The main widget focuses on **data entry and individual time tracking**, while the report widgets provide **aggregated analysis and visualization** from different perspectives (employee vs. project manager).
+
+## Prerequisites and Dependencies
+
+### Required
+- Access to a workspace where the CTTS app is configured
+- User must be in an allowed group (per app configuration)
+- At least one booking target type must be configured
+- Workspace selection must be configured
+
+### Optional
+- Calendar/holiday configuration for accurate workday detection
+- Target time configuration (via TargetTimeManager) for "should" hours display
+- Representative permissions for booking on behalf of others
+- Privilege group membership for editing locked periods
+- Import permissions for bulk time data loading
+
+## Key User Workflows
+
+### Basic Time Entry Workflow
+1. User opens widget → sees current week by default
+2. Clicks "Add target" (+ button)
+3. Selects project/activity from available targets
+4. Enters hours in grid cells for each day
+5. Clicks save (floppy disk icon) to persist entries
+6. Optionally marks favorite targets with star icon
+
+### Monthly Submission Workflow
+1. User completes all time entries for the month
+2. Reviews totals in sum line
+3. Clicks "Release month" button (share icon)
+4. Confirms release in dialog
+5. Month becomes read-only (locked) after release
+6. Privileged users or admins can revoke if needed
+
+### Representative Booking Workflow
+1. Authorized user clicks representative button
+2. Selects person to represent from filtered list
+3. Widget shows "Booking as: [Selected User]"
+4. Books time on behalf of that person
+5. Clears representative mode when done
+
+### Time Format Toggle
+1. User sees current format (e.g., "8:30")
+2. Toggles switch to decimal format
+3. Display updates to "8.5" (or "8,5" in German locale)
+4. Preference is saved automatically for future sessions
+
+## Summary
+
+The `cf.cplace.ctts.main.widget` is a feature-rich, enterprise-grade time tracking widget designed for comprehensive work hour management. It combines flexible data entry (supporting multiple time units, formats, and precision levels), robust workflow controls (release/lock mechanisms), administrative capabilities (representative booking, privilege overrides), and extensive configurability to adapt to various organizational time tracking requirements. The widget serves as the primary data entry point in the CTTS solution, complemented by separate reporting widgets for analysis and visualization.

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

@@ -0,0 +1,194 @@
+# Research: Widget `cf.cplace.demoWidgets.demoRichString`
+
+**Widget ID:** `cf.cplace.demoWidgets.demoRichString`
+**Widget Name:** Text without widget frame
+**Repository:** main
+**Definition Class:** `cf.cplace.platform/src/main/java/cf/cplace/platform/frontend/widgets/RichStringWithoutFrameWidgetDefinition.java`
+
+---
+
+## 1. Purpose
+
+The `cf.cplace.demoWidgets.demoRichString` widget is a specialized text widget that displays formatted rich text content without the standard widget frame/border, creating a seamless visual integration into the page layout.
+
+**Short Description:**
+A frameless widget for displaying formatted rich text with an optional title, editable only through the layout settings, designed for seamless content integration into page layouts.
+
+---
+
+## 2. Core Functionality
+
+### Key Characteristics
+
+1. **Frameless Display**
+   - The widget explicitly disables the standard widget frame by returning `false` in its `showFrame()` method (RichStringWithoutFrameWidgetSubstitution.java:102-104)
+   - This creates a borderless appearance that blends seamlessly into the page
+
+2. **Rich Text Rendering**
+   - Supports formatted text content including bold, italic, lists, links, and other rich text formatting
+   - Content is rendered using the platform's `richStringContent` function (RichStringWithoutFrameWidgetSubstitution.java:98)
+
+3. **Edit Restrictions**
+   - Content is **only editable through the layout/widget settings**, not through direct page editing
+   - This is explicitly mentioned in the widget description: "(Editable only in layout.)"
+
+4. **Localized Title Support**
+   - Supports multilingual titles through `LocalizedString` (RichStringWithoutFrameWidgetSubstitution.java:84-85)
+   - Titles are optional and can be configured per widget instance
+
+5. **Fulltext Searchability**
+   - Widget content is included in fulltext search results (RichStringWithoutFrameWidgetDefinition.java:43-45)
+
+---
+
+## 3. Use Cases
+
+### Primary Use Cases
+
+1. **Static Content Sections**
+   - Displaying informational text blocks that shouldn't look like widgets
+   - Adding explanatory content that blends naturally into the page
+   - Creating instructions or help text within a page layout
+
+2. **Visual Design & Layout**
+   - Creating clean, frame-free text sections for modern UI designs
+   - Building custom page layouts where widget borders would be visually distracting
+   - Designing landing pages or dashboards with seamless text integration
+
+3. **Content That Rarely Changes**
+   - Since editing requires accessing layout settings (not inline editing), this widget is ideal for content that:
+     - Is set up once during page design
+     - Changes infrequently
+     - Should not be easily editable by regular users
+
+4. **Structured Information Display**
+   - Displaying policy text, guidelines, or documentation
+   - Showing formatted announcements or notices
+   - Presenting structured content with headings, lists, and formatted text
+
+### When NOT to Use
+
+- **Frequently Updated Content:** The layout-only editing makes it inconvenient for content that changes often
+- **User-Generated Content:** Not suitable for content that users need to edit directly on the page
+- **Interactive Elements:** This is a display-only widget; use other widgets for interactive features
+
+---
+
+## 4. Configuration Concepts
+
+### Main Configuration Options
+
+The widget has three primary configuration attributes (defined in RichStringWithoutFrameWidgetSubstitution.java:26-66):
+
+1. **Title (Localized)**
+   - **Attribute:** `localizedWidgetTitle`
+   - **Type:** `LocalizedString`
+   - **Multiplicity:** At most one (optional)
+   - **Purpose:** Optional multilingual title displayed above the content
+   - **Note:** Replaces deprecated non-localized `widgetTitle` attribute
+
+2. **Content**
+   - **Attribute:** `content`
+   - **Type:** `RichString`
+   - **Multiplicity:** At most one (optional)
+   - **Purpose:** The main rich text content with formatting
+   - **Supports:** Bold, italic, lists, links, headings, and other rich text formatting
+
+3. **Height**
+   - **Attribute:** `height`
+   - **Type:** `Number`
+   - **Multiplicity:** At most one (optional)
+   - **Purpose:** Fixed height for the widget (in pixels or other units)
+   - **Use Case:** Useful for creating consistent layouts with fixed-height content areas
+
+### Customization Capabilities
+
+- **Formatting:** Full rich text formatting through the cplace rich text editor
+- **Multilingual Support:** Title can be localized for different languages
+- **Size Control:** Height can be explicitly set for layout consistency
+- **No Runtime Editing:** Content cannot be edited directly on the page, only through widget configuration
+
+---
+
+## 5. Context & Relationships
+
+### Related Widgets
+
+1. **`cf.platform.richString` (RichStringWidget)**
+   - The standard rich text widget **with a frame**
+   - Similar functionality but displays a widget border/frame
+   - Defined in RichStringWidgetDefinition.java:27
+   - Use when you want the standard widget appearance
+
+2. **Comparison with Standard RichString Widget**
+
+   | Aspect | demoRichString (Without Frame) | richString (Standard) |
+   |--------|-------------------------------|----------------------|
+   | Frame/Border | No (`showFrame()` returns false) | Yes (default widget frame) |
+   | Visual Integration | Seamless, blends into page | Distinct widget appearance |
+   | Title Requirement | Optional (maximalOne) | Required (exactlyOne) |
+   | Use Case | Clean layouts, static content | Standard widget usage |
+   | Widget ID | `cf.cplace.demoWidgets.demoRichString` | `cf.platform.richString` |
+
+3. **CustomRichStringAttributeWidget**
+   - Displays rich text attribute values from entities
+   - Different purpose: shows data from entity attributes rather than static configured content
+
+### Widget Family
+
+This widget belongs to the **text/content display widget family** within the cplace platform:
+- Shares configuration structure with standard RichStringWidget
+- Uses the same rendering mechanism (`richStringContent` function)
+- Part of the platform's core widget set (defined in `cf.cplace.platform`)
+
+### Technical Dependencies
+
+- **App:** Platform App (`PlatformPlugin.INSTANCE().platformApp`)
+- **Icon:** Font Awesome "fa-font" icon
+- **Rendering:** Uses `FunctionsHelper.proxy("richStringContent", ...)` for content rendering
+- **Entity Context:** Content rendering includes the entity UID for proper asset handling
+
+---
+
+## 6. Key Technical Details
+
+### Class Structure
+
+**Definition Class:** `RichStringWithoutFrameWidgetDefinition`
+- Location: cf.cplace.platform/src/main/java/cf/cplace/platform/frontend/widgets/RichStringWithoutFrameWidgetDefinition.java:23
+
+**Substitution Class:** `RichStringWithoutFrameWidgetSubstitution`
+- Location: cf.cplace.platform/src/main/java/cf/cplace/platform/frontend/widgets/RichStringWithoutFrameWidgetSubstitution.java:24
+- Handles content rendering and title display
+
+### Migration Support
+
+The widget includes migration logic for transitioning from the deprecated non-localized title to the localized version:
+- Old: `widgetTitle` (String)
+- New: `localizedWidgetTitle` (LocalizedString)
+- Migration method: `migrateUnlocalizedStringToLocalizedString()` (RichStringWithoutFrameWidgetDefinition.java:91)
+
+### Embedding Constraints
+
+- Can only be embedded as a widget (not in other contexts)
+- Checked via `checkIsEmbeddedAsWidget()` method (RichStringWithoutFrameWidgetDefinition.java:74)
+
+---
+
+## 7. Localization
+
+The widget supports full internationalization:
+
+**English:**
+- Name: "Text without widget frame"
+- Description: "A widget without frame to enter formatted text with a title. (Editable only in layout.)"
+
+**German:**
+- Name: "Text ohne Widget-Rahmen"
+- Description: "Ein Widget ohne Rahmen für die Eingabe von formatiertem Text. (Nur über die Einstellungen bearbeitbar.)"
+
+---
+
+## Summary
+
+The `cf.cplace.demoWidgets.demoRichString` widget is designed for displaying formatted text content that should visually blend into the page without the typical widget border. It's ideal for static or semi-static content that rarely changes, such as informational sections, guidelines, or design elements in custom page layouts. The key distinguishing feature is the absence of the widget frame, making it perfect for creating clean, modern UI designs where traditional widget borders would be visually disruptive.