velt-area-best-practices

Files (8)

• AGENTS.full.md
• AGENTS.md
• SKILL.md
• metadata.json
• _sections.md · rules/shared/
• api-toggle-area-comments.md · rules/shared/api/
• types-area-annotation.md · rules/shared/types/
• wireframe-variables-area.md · rules/shared/wireframe-variables/

SKILL.md (first lines)

# Velt Area Comments Best Practices

Implementation guide for Velt Area Comments — the rectangle area-annotation feature where users draw a box on the page and attach a comment thread to that region. Area is built on top of the Comments feature: it's not a separate component, it's a mode of `<VeltComments>` that is enabled by default and toggled via a prop or runtime method.

## When to Apply

Reference these guidelines when:
- Toggling area comments on or off in your app (default is ON)
- Choosing between the declarative `areaComment` prop on `<VeltComments>` and the imperative `commentElement.enableAreaComment()` / `disableAreaComment()` API
- Building a custom area pin via the wireframe surface — only `<velt-area-pin-portal-wireframe>` registers; the tool and container do not yet
- Reading `componentConfig.areaPinAnnotation`, `componentConfig.selected`, `componentConfig.isResizing`, `componentConfig.hideAreaAnnotation`, or the geometry / resize-offset variables
- Typing against `AreaAnnotation`, `AreaProperty`, `AreaTargetAnnotation`, or `AreaMetadata`
- Understanding how an `AreaAnnotation` links back to the comment thread(s) it scopes via `targetAnnotations[]`

## Area is a Comments-feature mode

There is **no** standalone `<VeltArea>` component. Area annotations are produced by the Comments feature when the area mode is active. The relevant SDK handle is `client.getCommentElement()` (the comments handle), not a hypothetical `getAreaElement()`. The three Area-specific public elements (`<velt-area-pin-portal>`, `<velt-area-tool>`, `<velt-area-container>`) are rendered automatically by the comments runtime when area mode is enabled.

## Rule Categories by Priority

| Priority | Category | Impact | Prefix |
|----------|----------|--------|--------|
| 1 | API | HIGH | `api-` |
| 2 | Wireframe Variables | MEDIUM | `wireframe-variables-` |
| 3 | Types | MEDIUM | `types-` |

## Quick Reference

### API (HIGH)
- `api-toggle-area-comments` — `<VeltComments areaComment={false}>` prop and `commentElement.enableAreaComment()` / `disableAreaComment()` runtime methods; the three public Area primitives (tool / pin-portal / container); the "no standalone component" framing

### Wireframe Variables (MEDIUM)
- `wireframe-variables-area` — `<velt-area-pin-portal-wireframe>` (the only Area primitive with a wireframe registration today) and its `componentConfig.*` reference (areaPinAnnotation, selected, isResizing, hideAreaAnnotation, areaProperties, resizingOffset, offsetTop/Left, areaAnnotationColor, commentPinAnnotation link)

### Types (MEDIUM)
- `types-area-annotation` — `AreaAnnotation` shape with the comment-linkage field `targetAnnotations[]` (`AreaTargetAnnotation[]`); supporting `AreaProperty` (geometry) and `AreaMetadata` (open extras); how area pins attach to comment threads

## How to Use

Read individual rule files for detailed explanations and code examples:

```
rules/shared/api/api-toggle-area-comments.md
rules/shared/wireframe-variables/wireframe-variables-area.md
rules/shared/types/types-area-annotation.md
```

Each rule contains:
- Why it matters
- React / Next.js + Other Frameworks code samples
- Common pitfalls
- Verification checklist
- Source pointers to official docs

## Related skills

- **`velt-comments-best-practices`** — Area is a mode of the comments feature; the `commentElement` handle, comment-annotation shape, and most surrounding setup live in the comments skill. Cross-link rather than duplicate.

## Compiled Documents

- `AGENTS.md` — Compressed index of all rules with file paths (start here)
- `AGENTS.full.md` — Full verbose guide with all rules expanded inline

From velt-js/velt-plugin-cursor, MIT.