# 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.