Add JSDoc to component type hierarchy

[UniquePixels]

Context

Audit ID: ARCH-4

The distinction between `AnyComponentInteraction`, `ComponentInteraction`, and `SelectMenuInteraction` requires reading the source to understand. Users may pick the wrong type.

Approach

Add JSDoc to each type alias explaining when to use it and how they relate to each other.

Files

• `src/core/sparks/component.ts`

[coderabbitai]

Coding Plan

Summary

• Enhance existing JSDoc comments with usage guidance and relationship explanations
• Add @example blocks following established codebase conventions
• Focus on helping users understand when to choose each type in the hierarchy
• Single file modification with no behavioral changes

Implementation Steps

Enhance Type Hierarchy Documentation

Update the JSDoc comments for the three component interaction type aliases to provide clear guidance on when to use each type, their relationships, and practical usage examples following the established codebase conventions.

Update JSDoc Comments for Component Interaction Types

Enhance the existing minimal JSDoc comments on SelectMenuInteraction, ComponentInteraction, and AnyComponentInteraction to guide users in selecting the appropriate type.

• Update SelectMenuInteraction JSDoc (lines 17-25) to explain it's for handlers that should only respond to select menu interactions, list the five constituent subtypes, and include an @example showing defineComponent<SelectMenuInteraction>({...})
• Update ComponentInteraction JSDoc (lines 27-30) to explain it covers buttons and select menus but excludes modals, clarify its relationship to SelectMenuInteraction, and include an @example for handlers that need both button and select menu support
• Update AnyComponentInteraction JSDoc (lines 32-37) to explain it's the widest type including modals, note it's the default constraint used internally, and clarify that most user-facing handlers should prefer the narrower types unless modal support is needed
• Maintain the existing single-sentence summary style at the start of each JSDoc block, adding the expanded guidance and @example blocks below
• Follow the codebase pattern of fenced TypeScript code blocks (```ts) in examples

🤖 Prompt for AI agents

Update the JSDoc comments on the three component interaction type aliases in
`src/core/sparks/component.ts`. The goal is to add clear usage guidance,
relationship context, and `@example` blocks to each type alias without making
any behavioral changes.

- **`SelectMenuInteraction` (lines 17-25):**
  - Keep the existing single-sentence summary as the first line
- Add explanation that this type is for handlers that should only respond to
select menu interactions
  - List the five constituent subtypes that form this union
- Add an `@example` block using a fenced ` ```ts ` code block demonstrating
`defineComponent<SelectMenuInteraction>({...})`

- **`ComponentInteraction` (lines 27-30):**
  - Keep the existing single-sentence summary as the first line
- Add explanation that this type covers both buttons and select menus but
excludes modals
- Clarify its relationship to `SelectMenuInteraction` (i.e., it is a superset
that adds `ButtonInteraction`)
- Add an `@example` block using a fenced ` ```ts ` code block for handlers that
need both button and select menu support

- **`AnyComponentInteraction` (lines 32-37):**
  - Keep the existing single-sentence summary as the first line
- Add explanation that this is the widest type, including modals
(`ModalSubmitInteraction`)
  - Note that it is the default constraint used internally
- Clarify that most user-facing handlers should prefer the narrower types unless
modal support is specifically needed
  - Add an `@example` block using a fenced ` ```ts ` code block

- All `@example` blocks must use fenced TypeScript code blocks (` ```ts `)
following the established codebase convention
- Do not change any type definitions, imports, or runtime code — this is
documentation only

Research

The project is a Discord.js framework with a spark-based architecture for defining command and component handlers. The component interaction type hierarchy is defined in src/core/sparks/component.ts with three layered union types: SelectMenuInteraction (narrowest, all five select menu subtypes), ComponentInteraction (adds ButtonInteraction), and AnyComponentInteraction (widest, adds ModalSubmitInteraction). The codebase follows consistent JSDoc conventions: single-sentence summaries for types, @example blocks with fenced TypeScript for usage guidance, and @param/@throws tags where applicable.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Update the JSDoc comments on the three component interaction type aliases in
`src/core/sparks/component.ts`. The goal is to add clear usage guidance,
relationship context, and `@example` blocks to each type alias without making
any behavioral changes.

- **`SelectMenuInteraction` (lines 17-25):**
  - Keep the existing single-sentence summary as the first line
- Add explanation that this type is for handlers that should only respond to
select menu interactions
  - List the five constituent subtypes that form this union
- Add an `@example` block using a fenced ` ```ts ` code block demonstrating
`defineComponent<SelectMenuInteraction>({...})`

- **`ComponentInteraction` (lines 27-30):**
  - Keep the existing single-sentence summary as the first line
- Add explanation that this type covers both buttons and select menus but
excludes modals
- Clarify its relationship to `SelectMenuInteraction` (i.e., it is a superset
that adds `ButtonInteraction`)
- Add an `@example` block using a fenced ` ```ts ` code block for handlers that
need both button and select menu support

- **`AnyComponentInteraction` (lines 32-37):**
  - Keep the existing single-sentence summary as the first line
- Add explanation that this is the widest type, including modals
(`ModalSubmitInteraction`)
  - Note that it is the default constraint used internally
- Clarify that most user-facing handlers should prefer the narrower types unless
modal support is specifically needed
  - Add an `@example` block using a fenced ` ```ts ` code block

- All `@example` blocks must use fenced TypeScript code blocks (` ```ts `)
following the established codebase convention
- Do not change any type definitions, imports, or runtime code — this is
documentation only

💡 Iterate on the plan with: @coderabbitai <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!