@cplace/test-mcp-server 0.1.15 → 1.1.0

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

@@ -0,0 +1,332 @@
+# Widget Research: cf.platform.tags
+
+**Date:** 2026-01-16
+**Widget ID:** `cf.platform.tags`
+**Repository:** main
+**Definition Class:** `cf.cplace.platform/src/main/java/cf/cplace/platform/frontend/widgets/TagsWidgetDefinition.java`
+
+---
+
+## Overview
+
+### Purpose
+
+The Tags widget displays all tags assigned to a page and provides an interface for users to add, edit, and remove tags directly within the page view.
+
+### Short Description
+
+The Tags widget shows all tags of a page and allows users to edit them, enabling flexible categorization and classification of pages for better organization and searchability.
+
+---
+
+## Core Functionality
+
+### What is Tagging?
+
+Tags are a core feature of the cplace platform that enable flexible, user-defined categorization of pages. Unlike fixed hierarchies or predefined categories, tags provide a lightweight way to:
+
+- Add metadata to pages without changing the data model
+- Create ad-hoc classifications and groupings
+- Enable cross-cutting categorization (a page can have multiple tags)
+- Facilitate search and filtering operations
+
+### Tag Characteristics
+
+Based on the analysis of the `Taggable` mixin and `Tag` class:
+
+**Tag Properties:**
+- Tags consist of a simple name (string value)
+- Tags are normalized to lowercase for consistency (`Taggable.java:49`)
+- Tags are stored as a JSON array internally (`Taggable.java:197-207`)
+- Tags are trimmed of whitespace (`Tag.java:20`)
+- Previous versions supported tag namespaces, but this feature was removed (`Tag.java:11`)
+
+**Data Model:**
+- Tags are stored in a serialized format in the `_serializedTags` attribute
+- The `TagDummyAttribute` provides a UI-friendly representation for editing
+- Tags are searchable via the search index (`SearchIndexFields.FIELD_STANDARD_TAGS`)
+- Tags support change tracking through `TagsChange` events
+
+---
+
+## Use Cases
+
+### Primary Use Cases
+
+1. **Content Categorization**
+   - Organize pages with flexible, user-defined labels
+   - Apply multiple categories to a single page (e.g., "important", "draft", "q1-2024")
+   - Create cross-cutting classifications that don't fit hierarchical structures
+
+2. **Search and Filtering**
+   - Find all pages with specific tags using `TagFilter` or `TagPrefixFilter`
+   - Build tag clouds to visualize frequently used tags
+   - Enable faceted search experiences based on tag frequency
+
+3. **Workflow and Status Tracking**
+   - Mark pages with workflow states (e.g., "review", "approved", "archived")
+   - Flag items for follow-up or special attention
+   - Track project phases or milestones
+
+4. **Team Collaboration**
+   - Share informal classifications across team members
+   - Create temporary groupings without modifying the data model
+   - Enable different teams to apply their own categorization schemes
+
+5. **Ad-hoc Organization**
+   - Quick categorization without creating formal attributes or types
+   - Experiment with different organizational schemes
+   - Support evolving classification needs
+
+### When to Use This Widget
+
+Users should choose the Tags widget when they need to:
+
+- Display and manage tags on a page in the page view
+- Allow users to quickly add or remove tags inline
+- Show tag metadata alongside other page content
+- Enable visual identification of tagged content
+
+### Typical Scenarios
+
+- **Project Pages:** Tag pages with project phases, priorities, or team names
+- **Documentation:** Categorize documents by topic, audience, or status
+- **Task Management:** Label tasks with context, priority, or assignment
+- **Knowledge Base:** Tag articles with topics, difficulty levels, or relevance
+
+---
+
+## Configuration & Customization
+
+### Widget Embedding
+
+**Embedding Rules:**
+- Can be embedded in pages (checked via `checkIsEmbeddedAsWidget`)
+- Must be on `Page` entities or type definitions that apply to pages
+- Only one instance should exist per page (checked via `checkIsNotAlreadyEmbedded`)
+
+**Code Reference:** `TagsWidgetDefinition.java:48-56`
+
+### Display Characteristics
+
+The widget has specific display properties configured in the `getContentSubstitution` method:
+
+**Frame and Padding:**
+- **No Frame:** The widget renders without a surrounding frame (`showFrame() = false`)
+- **No Padding:** Content has no internal padding (`isNoPadding() = true`)
+
+These settings create a clean, integrated appearance that blends seamlessly into the page layout.
+
+**Code Reference:** `TagsWidgetDefinition.java:59-71`
+
+### Icon
+
+The widget uses the Font Awesome `fa-hashtag` icon (📎), which is a universal symbol for tags and metadata.
+
+**Code Reference:** `TagsWidgetDefinition.java:43-45`
+
+### Configuration Options
+
+**Minimal Configuration:**
+The Tags widget has minimal configuration requirements:
+- No complex configuration parameters
+- Works with the page's existing `Taggable` mixin
+- Automatically scoped to the page's space via `spaceId` parameter
+
+**Frontend Control State:**
+The widget passes the following to the frontend (`TagDummyAttribute.java:82-89`):
+- `type`: "builtin/tags" - identifies the control type
+- `value.tags`: Array of current tag names
+- `spaceId`: The space context for tag suggestions
+- `noLabel`: Optional parameter to hide the label
+
+---
+
+## Technical Architecture
+
+### Backend Components
+
+**Core Classes:**
+
+1. **`TagsWidgetDefinition`** - Widget definition class
+   - Defines widget kind, name, description
+   - Controls embedding rules and display properties
+   - Location: `cf.cplace.platform/src/main/java/cf/cplace/platform/frontend/widgets/TagsWidgetDefinition.java`
+
+2. **`Taggable`** - Mixin that provides tag functionality
+   - Methods: `getTags()`, `setTags()`, `assignTag()`, `unassignTag()`, `hasTag()`
+   - Tag normalization and serialization
+   - Location: `cf.cplace.platform/src/main/java/cf/cplace/platform/core/datamodel/builtin/assets/taggable/Taggable.java`
+
+3. **`TagDummyAttribute`** - UI bridge for tag editing
+   - Provides editable control state for frontend
+   - Handles form submission via `applyAngularParameter()`
+   - Location: `cf.cplace.platform/src/main/java/cf/cplace/platform/core/datamodel/builtin/TagDummyAttribute.java`
+
+4. **`Tag`** - Value object representing a single tag
+   - Simple string-based name
+   - Immutable after creation
+   - Location: `cf.cplace.platform/src/main/java/cf/cplace/platform/core/datamodel/builtin/assets/taggable/Tag.java`
+
+**Search Integration:**
+- **`TagFilter`** - Filter pages by exact tag match
+- **`TagPrefixFilter`** - Filter pages by tag prefix (for autocomplete)
+- **`TagUtilities`** - Helper methods for tag ordering and sorting
+- **Tag Cloud Support** - Frequency-based tag visualization
+
+### Data Flow
+
+1. **Display:** Widget reads tags from `Taggable` mixin via `_serializedTags()` attribute
+2. **Edit:** User modifies tags in frontend control
+3. **Submit:** `TagDummyAttribute.applyAngularParameter()` processes form submission
+4. **Update:** Tags are assigned/unassigned via `Taggable` methods
+5. **Persist:** Changes trigger `TagsChange` events and update search index
+6. **Reload:** Updated tags appear in widget on next page load
+
+---
+
+## Relationships to Other Features
+
+### Entity Model Integration
+
+**Taggable Mixin:**
+The `Page` class includes the `Taggable` mixin, which provides tag functionality to all pages:
+
+```java
+// From Page.java:408
+new Taggable() {},
+```
+
+This means every page in the system can have tags, regardless of its type definition.
+
+### Search Integration
+
+Tags are deeply integrated with the search system:
+
+**Autocomplete:**
+- Tags support prefix-based autocomplete via `Taggable.getTagsForPrefix()`
+- Returns most frequently used tags matching a prefix
+- Useful for suggesting existing tags to users
+
+**Filtering:**
+- `TagFilter` enables exact tag matching in searches
+- `TagPrefixFilter` supports partial matches
+- Term frequency analysis via `Search.termFrequencies()`
+
+**Tag Cloud:**
+- `TagCloud` class provides frequency-based visualization
+- Orders tags by usage count
+- Supports blacklisting certain tags
+
+### Versioning and Change Tracking
+
+Tags participate in the versioning system:
+
+**Change Events:**
+- `TagsChange` records before/after state of tags
+- Watchable attribute triggers notifications on changes
+- Changes appear in version history
+
+**Code Reference:** `Taggable.java:246-253`
+
+### Related Widgets
+
+The Tags widget is part of a family of page metadata widgets:
+
+- **`cf.platform.attributes`** - Display page attributes
+- **`cf.platform.modificationInfo`** - Show creation/modification metadata
+- **`cf.platform.incomingReferences`** - Display references to this page
+- **`cf.platform.comments`** - Show page comments
+
+These widgets often appear together on page views to provide comprehensive metadata visualization.
+
+---
+
+## API Usage
+
+### Programmatic Tag Management
+
+**Common Operations:**
+
+```java
+// Get tags
+Taggable taggable = page.adapt(Taggable.class);
+Set<Tag> tags = taggable.getTags();
+SortedSet<String> tagNames = taggable.getTagNames();
+
+// Check for tag
+boolean hasTag = taggable.hasTag("important");
+
+// Assign tags
+taggable.assignTag("new-tag");
+taggable.assignTags(Arrays.asList("tag1", "tag2"));
+
+// Remove tags
+taggable.unassignTag("old-tag");
+taggable.unassignTags(Arrays.asList("tag1", "tag2"));
+
+// Clear all tags
+taggable.clear();
+```
+
+**Helper Method:**
+```java
+// Create tags widget via WidgetHelper
+WidgetWithContent tagsWidget = WidgetHelper.getTagsWidget();
+```
+
+---
+
+## Key Insights
+
+### Design Philosophy
+
+1. **Lightweight:** Tags provide metadata without schema changes
+2. **User-Driven:** No predefined tag taxonomy - users create as needed
+3. **Searchable:** First-class search integration via indexing
+4. **Normalized:** Case-insensitive, trimmed for consistency
+5. **Versioned:** Tag changes tracked like attribute changes
+
+### Technical Considerations
+
+**Performance:**
+- Tags serialized as JSON array (compact storage)
+- Indexed for search (fast filtering)
+- Prefix-based autocomplete (efficient suggestions)
+
+**Data Integrity:**
+- Tags normalized to prevent duplicates
+- Empty/null tags filtered out
+- Changes tracked for audit trail
+
+**User Experience:**
+- No frame/padding for clean integration
+- Space-scoped suggestions for relevance
+- Hashtag icon for instant recognition
+
+### Evolution
+
+**Historical Context:**
+- Previous versions supported tag namespaces (removed)
+- Original package: `cf.cplace.platform.script.widgets` (refactored to `frontend.widgets`)
+
+**Code Reference:** Mapping rules in `messages_en.properties:4326-4327`
+
+---
+
+## Summary
+
+The Tags widget (`cf.platform.tags`) is a fundamental metadata widget that displays and manages tags on pages. It provides a lightweight, flexible categorization system that complements formal data model attributes. The widget integrates deeply with the platform's search capabilities, enabling tag-based filtering, autocomplete, and tag cloud visualizations.
+
+**Key Benefits:**
+- Zero configuration required - works out of the box
+- Supports ad-hoc, user-driven classification
+- Fully integrated with search and versioning
+- Clean, minimal visual design
+- Programmatic API for scripting scenarios
+
+**Ideal For:**
+- Content organization and categorization
+- Search enhancement and faceted navigation
+- Workflow state tracking
+- Team collaboration and informal classification

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

@@ -0,0 +1,258 @@
+# Widget Research: cf.platform.wiki
+
+## Overview
+
+**Widget ID:** `cf.platform.wiki`
+**Repository:** main
+**Definition Class:** `cf.cplace.platform/src/main/java/cf/cplace/platform/frontend/widgets/WikiWidgetDefinition.java`
+**Icon:** `fa-wikipedia-w` (Wikipedia icon)
+
+## Summary Description
+
+The Wiki widget provides an editable rich-text content area for pages, documents, and principals (persons/groups). It displays and allows editing of the built-in content field of the entity it's embedded in.
+
+## Purpose
+
+The Wiki widget serves as a primary content editor and viewer for entities that have rich-text content capabilities. It provides a Wikipedia-style editing experience where users can create and maintain formatted text content with support for:
+
+- Rich text formatting (HTML-based)
+- Internal and external links
+- Images
+- Embedded widgets within the content
+- Wiki-style collaborative content editing
+
+The widget acts as a bridge between the entity's underlying `RichStringAttribute` content field and the user interface, providing an in-place editing experience.
+
+## Core Functionality
+
+### Content Source
+
+The Wiki widget retrieves its content from different attributes depending on the entity type:
+
+1. **Pages** (`Page`): Uses the `_content()` attribute
+2. **Documents** (`Document`): Uses the `_content()` attribute
+3. **Persons** (`Person`): Uses the `_description()` attribute
+4. **Groups** (`Group`): Uses the `_description()` attribute
+5. **Type Definitions** (`TypeDefinition`): Uses the `_description()` attribute
+
+### Rich String Content
+
+All content displayed by the Wiki widget is stored as a `RichStringAttribute`, which:
+
+- Is HTML-safe
+- Supports medium-length text (up to `Store.MEDIUM_TEXT`)
+- Tracks changes through `RichStringChange` events
+- Can contain internal links, external links, images, and embedded widgets
+- Automatically validates and updates links to other entities
+
+### Embedding Rules
+
+The Wiki widget can be embedded in:
+
+- **Pages**: Any page entity
+- **Documents**: File/document entities
+- **Persons**: User profile entities
+- **Groups**: Group/team entities
+- **Type Definitions**: Custom type definition pages
+
+It enforces that:
+- It must be embedded as a widget (not as other embedding types)
+- Only one instance should be embedded per entity (checked via `checkIsNotAlreadyEmbedded`)
+
+## Use Cases
+
+### 1. **Page Content Management**
+
+The most common use case is for text pages (e.g., `default.page` type) where users need to:
+
+- Create documentation pages
+- Build knowledge bases
+- Write project descriptions
+- Create meeting notes
+- Maintain wiki-style collaborative content
+
+**Example Context:**
+A project workspace with multiple documentation pages where team members collaboratively edit and maintain project information.
+
+### 2. **Document Descriptions**
+
+For document entities, the Wiki widget allows users to:
+
+- Add contextual descriptions to uploaded files
+- Provide metadata and explanations for documents
+- Create document summaries
+
+**Example Context:**
+A requirements document uploaded to the system needs a detailed description explaining its purpose, version history, and related information.
+
+### 3. **User Profiles and Group Descriptions**
+
+For persons and groups, the Wiki widget enables:
+
+- Creating rich user bio/profile information
+- Adding team descriptions and charters
+- Documenting roles and responsibilities
+- Linking to related projects or expertise areas
+
+**Example Context:**
+A team lead wants to create a comprehensive group page describing the team's mission, members, ongoing projects, and contact information.
+
+### 4. **Type Definition Documentation**
+
+For custom types, the Wiki widget supports:
+
+- Documenting what a custom type represents
+- Providing usage guidelines for the type
+- Adding examples and best practices
+
+**Example Context:**
+A system administrator creates a custom type for "Risk Items" and uses the Wiki widget to document when and how this type should be used.
+
+## Configuration
+
+### No Configuration Options
+
+Unlike many other widgets (e.g., `CustomRichStringAttributeWidgetDefinition` which has `SHOW_FRAME` and `ATTRIBUTE_NAME` options), the Wiki widget has **no configurable attributes**.
+
+The widget definition shows:
+```java
+<attributes/>
+```
+
+This means:
+- No widget-specific settings to configure
+- Behavior is entirely determined by the entity type it's embedded in
+- Content automatically maps to the appropriate field based on entity type
+
+### Template
+
+The widget uses a minimal template (`wikiWidgetDefinition.htm`):
+```
+$this.show(editViaWidget,noLabel,modalEditing="false")$
+```
+
+This template indicates:
+- **editViaWidget**: Enables in-line editing directly in the widget
+- **noLabel**: Doesn't display a label/title for the content field
+- **modalEditing="false"**: Editing happens in-place rather than in a modal dialog
+
+## Relationship to Other Widgets
+
+### Comparison with Custom Rich String Attribute Widget
+
+The **Custom Rich String Attribute Widget** (`cf.platform.customRichStringAttribute`) is a more flexible alternative that:
+
+- Can display any custom rich-text attribute (not just the built-in content field)
+- Has configuration options (show frame, attribute name selection)
+- Provides a title based on the attribute definition
+- Works only with custom entities and custom attributes
+
+In contrast, the **Wiki Widget**:
+
+- Is specifically designed for built-in content/description fields
+- Works with core entity types (Pages, Documents, Principals)
+- Has no configuration options
+- Provides a standardized content editing experience
+
+### Part of Core Content Editing
+
+The Wiki widget is part of the platform's core content management capabilities, alongside:
+
+- **Attributes Widget**: Displays all entity attributes
+- **Comments Widget**: Handles discussion threads
+- **Files Widget**: Manages attachments
+
+Together, these widgets form the foundation for collaborative content creation and management in the cplace platform.
+
+## Technical Details
+
+### Java Class Structure
+
+**File:** `/Users/thomasbuechner/dev/repos/main/cf.cplace.platform/src/main/java/cf/cplace/platform/frontend/widgets/WikiWidgetDefinition.java`
+
+Key implementation details:
+
+```java
+public class WikiWidgetDefinition extends WidgetDefinition {
+    public static final String KIND = "cf.platform.wiki";
+
+    @Override
+    public void checkEmbeddableIn(PersistentEntity entity, WidgetEmbedding embedding) {
+        checkIsEmbeddedAsWidget(entity, embedding);
+        checkEntityKindAndAllowTypeDefinitionsWhichApplyToIt(
+            entity, embedding,
+            Page.class, Document.class, Person.class, Group.class
+        );
+    }
+
+    @Override
+    public WidgetTemplateSubstitution getContentSubstitution(...) {
+        return new ContentWidgetTemplateSubstitution(this, params) {
+            @Override
+            public Object getScopeObject() {
+                // Returns appropriate content field based on entity type
+                if (entity instanceof Page) return ((Page) entity)._content();
+                else if (entity instanceof Document) return ((Document) entity)._content();
+                else if (entity instanceof Principal) return ((Principal) entity)._description();
+                else if (entity instanceof TypeDefinition) return ((TypeDefinition) entity)._description();
+                else return null;
+            }
+        };
+    }
+}
+```
+
+### Internationalization
+
+Messages are defined in `cf.cplace.platform/src/main/resources/cf/cplace/platform/messages_en.properties`:
+
+```properties
+frontend.widgets.WikiWidgetDefinition.name=Wiki
+frontend.widgets.WikiWidgetDefinition.description=Adds a wiki to the page.
+```
+
+## Key Characteristics
+
+1. **Zero Configuration**: The widget requires no setup or configuration - it automatically adapts to the entity type.
+
+2. **Built-in Field Focus**: Specifically designed for built-in content/description fields, not custom attributes.
+
+3. **Collaborative Editing**: Provides in-place, modal-free editing for wiki-style collaborative content.
+
+4. **Multi-Entity Support**: Works across different entity types with appropriate field mapping.
+
+5. **Rich Content**: Leverages `RichStringAttribute` capabilities including formatting, links, images, and embedded widgets.
+
+6. **Single Instance Design**: Enforces that only one Wiki widget should be embedded per entity, as there's only one content/description field per entity.
+
+## Dependencies
+
+- **App**: Part of the core platform app (`PlatformPlugin.INSTANCE().platformApp`)
+- **Entity Types**: Depends on Page, Document, Person, Group, and TypeDefinition classes
+- **Rich String Infrastructure**: Relies on `RichStringAttribute` and related change tracking
+- **Widget Container**: Integrates with the widget embedding system
+
+## Common Patterns
+
+### Typical Page Layout
+
+A typical text page layout includes:
+
+1. **Page Header**: Entity name and navigation
+2. **Wiki Widget**: Main content area (this widget)
+3. **Comments Widget**: Discussion section
+4. **Files Widget**: Attachments section
+5. **Attributes Widget**: Additional metadata
+
+### Content Flow
+
+1. User navigates to a page/document/profile
+2. Wiki widget renders the current content from the appropriate field
+3. User clicks to edit (in-place)
+4. Changes are saved to the `RichStringAttribute`
+5. Change listeners update dependent widgets and links
+6. Version history tracks content evolution
+
+## Summary
+
+The Wiki widget is a fundamental, zero-configuration widget that provides rich-text editing capabilities for the core content fields of pages, documents, and principal entities. It emphasizes simplicity and convention over configuration, automatically adapting its behavior based on the entity type while providing a consistent Wikipedia-style editing experience across the platform.