@cplace/test-mcp-server 0.1.15 → 1.1.0

package/dist/widget-specifications/CLAUDE.md

@@ -0,0 +1,288 @@
+# Widget Specifications Guidelines
+
+This directory contains supplementary documentation for widgets that help AI correctly discover, understand, and configure widgets. These specifications follow a two-level progressive disclosure architecture.
+
+## Two-Level Architecture
+
+Each level serves a distinct purpose in the AI-assisted workflow:
+
+| Level | Purpose | Question Answered | Files |
+|-------|---------|-------------------|-------|
+| **1** | Discovery | "What widgets exist?" | `_meta.json`, `_summary.md` |
+| **2** | Definition | "How does this widget work and how do I configure it?" | `_summary.md`, `_overview.md`, `_implementation.md`, `{attribute}.md` |
+
+Level 2 (`cplace_get_widget_definition`) provides configurable depth via boolean flags:
+- **Baseline** (always): `summary` from `_summary.md`
+- **With `includeOverview: true`**: Adds `overview` from `_overview.md`
+- **With `includeDetails: true`**: Adds `implementation` from `_implementation.md` and attribute specifications
+
+**Information should not be duplicated across levels.**
+
+## File Structure
+
+```
+widget-specifications/{widgetKind}/
+├── _meta.json           → Level 1: Tag metadata
+├── _summary.md          → Level 1: Brief description
+├── _overview.md         → Level 2: Conceptual documentation
+├── _implementation.md   → With includeDetails: Widget-level implementation hints
+└── {attribute}.md       → With includeDetails: Attribute-specific configuration
+```
+
+- Directory name = exact widget kind (e.g., `cf.platform.embeddedSearchAsTable`)
+- Attribute file name = attribute short name (e.g., `search.md`, not the full attribute name)
+
+## Tool Response Mapping
+
+| Tool | Level | Returns |
+|------|-------|---------|
+| `cplace_list_widget_definitions` | 1 | API metadata + `summary` from `_summary.md`, filtered by `tags` |
+| `cplace_get_widget_definition` | 2 | Configurable via flags - see below |
+
+### `cplace_get_widget_definition` Response Depth
+
+| Flags | Returns |
+|-------|---------|
+| (none) | `widgetKind`, `localizedName`, `summary` |
+| `includeOverview: true` | Above + `overview` |
+| `includeDetails: true` | Above + `implementation`, `attributesCount`, `attributes` with per-attribute `specification` |
+| Both flags | All fields |
+
+---
+
+## Level 1: Discovery Files
+
+### `_meta.json`
+
+Tag metadata and app dependency information used for filtering widgets during discovery.
+
+```json
+{
+  "tags": ["table", "searchable", "filterable", "sortable", "selectable", "navigation"],
+  "requiredApp": "cf.cplace.cboard.main"
+}
+```
+
+**Fields:**
+- `tags`: Array of tags for categorization (see `tag-registry.json`)
+- `requiredApp`: App required for this widget to be available:
+  - `null`: Platform widget, always available
+  - `"cf.cplace.appName"`: Requires specific app to be installed
+  - Missing/undefined: Not yet documented
+
+Tags are organized by dimension (data type, display format, interaction, purpose, technical). See `tag-registry.json` for the complete list.
+
+### `_summary.md`
+
+Brief description for scanning during widget discovery. **Maximum 1-2 sentences.**
+
+**Content guidelines**:
+- What the widget displays/does (one sentence)
+- Primary use case (optional, one sentence)
+
+**Example**:
+```markdown
+Displays pages matching a search query in a sortable, filterable table format. Use for listing collections of data with support for master-detail interactions.
+```
+
+**Do NOT include**:
+- Configuration details
+- Attribute descriptions
+- Implementation workflows
+
+---
+
+## Level 2: Understanding Files
+
+### `_overview.md`
+
+Rich conceptual documentation for understanding the widget's purpose, patterns, and design considerations.
+
+**Content guidelines**:
+- When to use this widget (use cases)
+- Operating modes and their purposes
+- Design considerations and trade-offs
+- Connection patterns with other widgets
+- Common pitfalls to avoid
+- Alternative widgets to consider
+- Related patterns
+
+**Example structure**:
+```markdown
+# Widget Name
+
+**Technical ID**: `cf.platform.widgetKind`
+
+## Overview
+What this widget does and when to use it...
+
+## Operating Modes
+### Standalone Mode
+Description...
+
+### Master Mode
+Description...
+
+## Design Considerations
+### When to Use This Pattern
+Guidance...
+
+## Common Pitfalls
+- Pitfall 1...
+- Pitfall 2...
+
+## Related Patterns
+- Pattern name - brief description
+```
+
+**Do NOT include**:
+- Attribute configuration details
+- JSON format specifications
+- Step-by-step configuration workflows
+
+---
+
+## Implementation Files (with includeDetails)
+
+### `_implementation.md`
+
+Widget-level implementation hints and configuration guidance.
+
+**Content guidelines**:
+- Configuration modes and which attributes they activate
+- Attribute dependencies and conditional requirements
+- Typical configuration workflow/order
+- Technical gotchas
+
+**Example**:
+```markdown
+**Configuration Modes**:
+- `search`: Query pages via embedded search (most common)
+  - Requires: `search` attribute with cplaceJson from `cplace_search_pages`
+- `connectedTable`: Display data from another table widget
+  - Requires: `connectedTableWidgetId` pointing to the source widget
+
+**Typical Configuration Workflow**:
+1. Configure either `search` or `connectedTableWidgetId`
+2. Define visible columns via `columns` attribute
+3. Optionally configure sorting, filtering, and grouping
+```
+
+**Do NOT include**:
+- Conceptual explanations (belongs in `_overview.md`)
+- Use case descriptions (belongs in `_overview.md`)
+- Detailed attribute schemas (returned by API)
+
+### `{attribute}.md`
+
+Attribute-specific configuration documentation. Only create when the attribute requires information not available from the API response.
+
+---
+
+## Core Principle: Don't Duplicate
+
+The `cplace_get_widget_definition` MCP tool already provides:
+- Attribute names and localized names
+- Constraint types (boolean, string, textEnumeration, dynamicEnumeration, search, etc.)
+- Required/optional status
+- Enumeration values (for textEnumeration constraints)
+- Multiplicity (single/multiple)
+
+**Widget specifications should ONLY document information that the MCP tool CANNOT provide.**
+
+## When to Create Attribute Specifications
+
+Create a specification file for an attribute when:
+
+1. **Complex Value Construction** - The value requires a specific workflow to construct correctly
+   - Example: `search` attribute needs JSON from `cplace_search_pages` response
+
+2. **Non-Obvious Valid Values** - The constraint type doesn't reveal what values are actually valid
+   - Example: `dataSource` is a string but only accepts `search`, `connectedTable`, `selection`
+
+3. **Conditional Requirements** - Other attributes become required based on this attribute's value
+   - Example: When `dataSource=search`, the `search` attribute becomes required
+
+4. **JSON Format Documentation** - The attribute accepts structured JSON but the schema isn't obvious
+   - Example: `columns`, `multiSortColumns`, `filters` all need JSON format examples
+
+5. **Common Mistakes** - Users/AI frequently misuse this attribute
+   - Example: Manually constructing search JSON instead of using cplaceJson
+
+6. **Semantic Clarification** - The attribute name is misleading
+   - Example: `dataSource` sounds like it expects a type reference, but it's a mode selector
+
+## When NOT to Create Attribute Specifications
+
+Do NOT create specifications for:
+
+- Simple boolean flags with obvious semantics (e.g., `showTableHeader`, `hideNames`)
+- Attributes where the constraint fully describes valid values (e.g., `textEnumeration` with all values listed)
+- Basic string/number attributes with obvious purpose (e.g., `title`, `height`)
+- Attributes where the localized name makes the purpose clear
+
+## Attribute Specification Format
+
+Keep specifications **brief and actionable**:
+
+```markdown
+**Warning**: [One-line warning about common mistakes, if applicable]
+
+**Valid Values**: [If constraint doesn't reveal valid values]
+- `value1`: Description
+- `value2`: Description
+
+**Correct Usage**: [Brief description of correct workflow]
+
+**Workflow**: [If complex multi-step process required]
+1. Step one
+2. Step two
+3. Step three
+
+**JSON Format**: [If attribute accepts structured JSON]
+```json
+{
+  "example": "structure"
+}
+```
+
+**Note**: [Additional context, relationships to other attributes]
+```
+
+Not all sections are required. Only include what's necessary for the specific attribute.
+
+---
+
+## Examples
+
+### Good Attribute Specification (search.md)
+```markdown
+**Warning**: Do not manually construct search JSON!
+
+**Correct Usage**: Use the cplaceJson field from cplace_search_pages response
+
+**Workflow**:
+1. Call cplace_search_pages with your desired filter
+2. Take the cplaceJson field from the response
+3. Use that value for the search configuration
+```
+
+### Good Attribute Specification (dataSource.md)
+```markdown
+**Warning**: This is a mode selector, NOT a type reference!
+
+**Valid Values**:
+- `search`: Widget queries data via embedded search (use search attribute)
+- `connectedTable`: Widget uses data from a connected table widget (use tableWidgetId)
+- `selection`: Widget uses explicitly selected pages (use selection attribute)
+
+**Note**: The "required" constraints on tableWidgetId and selection are conditional - only the attribute matching your dataSource choice is actually required.
+```
+
+### Bad Specification (don't create this)
+```markdown
+**Type**: Boolean
+**Required**: Yes
+**Description**: Controls whether the table header is shown.
+```
+This duplicates information already in the MCP tool response.