Enhance UI customization options for components

[coderabbitai]

Background

This issue follows up on the discussion in PR #272 about improving customization options for UI components, specifically regarding the OAResponse component and OAMarkdown styling.

Current Situation

Currently, UI components have limited customization options. The discussion started around removing text-lg class from OAResponse descriptions to maintain consistency with other OAMarkdown usages.

Proposed Solutions

1. CSS Class-based Targeting

Add specific CSS classes to components for easier targeting:

.OAResponses oa-doc {
  @apply text-xl
}

2. Vue Slot-based Customization

Implement nested slots for granular control over UI components:

<OAOperation :operationId="operationId">
  <template #oa-response-description="slotProps">
    <OAMarkdown
      :content="slotProps.response.description"
      class="text-lg"
    />
  </template>
</OAOperation>

Goals

• Provide consistent customization approach across all components
• Allow users to customize any part of the UI without recreating large chunks
• Maintain backward compatibility during implementation
• Consider both CSS and prop-based customization methods

Related

• PR: fix: Render "Responses" descriptions with OAMarkdown component #272
• Comment: fix: Render "Responses" descriptions with OAMarkdown component #272 (comment)
• Requested by: @enzonotario

[enzonotario]

@coderabbitai generate an Imeplementation Plan for point 2

[coderabbitai]

Implementation Plan

Approach

Implement Vue slot-based customization for OAResponse component elements, allowing users to customize response descriptions, content-type selectors, and schema tabs at the OAOperation level without recreating entire components. The implementation will follow the established slot forwarding patterns in the codebase, using generic contextual slots that pass response-specific data through scoped props.

Observations

This is a VitePress-based OpenAPI documentation generator built with Vue 3 and TypeScript. The component hierarchy follows: OAOperation → OAOperationContent → OAResponses → OAResponse → OAMarkdown. The codebase already uses sophisticated slot forwarding patterns with defineSlots<Record<string, SlotType>>() and dynamic slot mapping via v-for. Components consistently use kebab-case naming for slots and pass contextual data through scoped slot bindings. The existing slot infrastructure in OAOperation, OAPath, and related components demonstrates mature patterns that can be extended for response-level customization.

Assumptions

Assumption 1: Slot Naming Strategy for Response Customization

Options Considered:

• Per-response-code slots with embedded codes (e.g., response-200-description, response-404-description)
• Generic contextual slots with response code passed via slot props (e.g., response-description receiving { responseCode: '200', response, operationId })
• Hybrid approach supporting both general and specific slot names

Chosen Option: Generic contextual slots with response code in slot props

Rationale: This approach aligns perfectly with existing codebase patterns where slots use semantic names (header, description, responses) and pass rich contextual data through scoped bindings. It provides the same flexibility as per-code slots while maintaining clean, scalable slot names. Developers can conditionally customize based on response code within their slot implementation, matching the established pattern of passing operation, method, and other context through slot props throughout the codebase.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Plan

Phase 1: Add Slot Definitions to OAResponse Component

Enable granular customization within individual response rendering by introducing slots for each major UI element.

Task 1: Define Slots in OAResponse Component

Add slot definitions for the three customizable UI sections within response rendering.

• Add defineSlots() call in src/components/Response/OAResponse.vue with slots: description, content-type-selector, schema-tabs
• Each slot should receive scoped props including responseCode, response object, and operationId
• Maintain existing default rendering by wrapping current implementation in conditional checks (render slot if provided, otherwise render default content)

Task 2: Implement Conditional Slot Rendering

Preserve backward compatibility by rendering default content when slots aren't provided.

• Replace existing OAMarkdown description rendering with slot-aware conditional: check for description slot, render slot with bound props if exists, otherwise render existing OAMarkdown component
• Apply same pattern to content-type selector and schema tabs sections
• Use v-if="$slots.description" pattern (or equivalent hasSlot helper) to check slot existence before rendering default components

🤖 Prompt for AI agents

Add slot customization to the OAResponse component for description, content-type
selector, and schema tabs.

In src/components/Response/OAResponse.vue:
- Add `defineSlots()` with three slots: `description`, `content-type-selector`,
`schema-tabs`
- Each slot should receive scoped props: `responseCode`, `response`,
`operationId`
- Wrap existing OAMarkdown description rendering in a conditional check: if
`description` slot exists, render it with bound props; otherwise render
OAMarkdown
- Apply the same conditional pattern to content-type selector and schema tabs
sections
- Use `v-if="$slots.slotName"` to check slot existence before falling back to
default rendering

Phase 2: Forward Response Slots Through OAResponses Container

Enable slot forwarding from parent components down to individual OAResponse instances.

Task 1: Add Slot Forwarding to OAResponses Component

Implement the established slot forwarding pattern used throughout the codebase.

• Add defineSlots<Record<string, any>>() in src/components/Response/OAResponses.vue
• Add template block using v-for="(_, name) in slots" with #[name]="slotProps" to dynamically forward all incoming slots
• Wrap existing OAResponse component rendering with the forwarding template
• Ensure slot props are passed through using v-bind="slotProps || {}" pattern

Task 2: Pass Response Context to Forwarded Slots

Augment slot props with response-specific context when forwarding to OAResponse.

• When forwarding slots to OAResponse, bind additional context: responseCode (from the current loop iteration), response data, and operationId
• Follow the established pattern of merging slot props with component-specific data (similar to how operation, method, path are passed in OAPath slots)
• Ensure the slot prop structure matches what OAResponse slots expect

🤖 Prompt for AI agents

Implement slot forwarding in OAResponses to pass slots down to OAResponse
components.

In src/components/Response/OAResponses.vue:
- Add `defineSlots<Record<string, any>>()`
- Add a template block with `v-for="(_, name) in slots"` and
`#[name]="slotProps"` to dynamically forward all slots
- Wrap existing OAResponse rendering within the forwarding template
- When rendering OAResponse, bind slot props augmented with response context:
merge `slotProps` with `responseCode`, `response` data, and `operationId`
- Use `v-bind` to pass the merged props structure

Phase 3: Integrate Response Slots into Operation Component Hierarchy

Connect the new response customization slots to the top-level OAOperation component API.

Task 1: Forward Response Slots Through OAOperationContent

Extend the existing slot forwarding in the operation content layer.

• Update src/components/Feature/OAOperationContent.vue to forward response-specific slots alongside existing slots (header, tags, description, etc.)
• The component already uses the v-for slot forwarding pattern - verify it captures and forwards the new response slots
• Ensure slot props flow through the existing forwarding mechanism without modification

Task 2: Update OAOperation Slot Types

Extend TypeScript type definitions to include the new response customization slots.

• Update the OperationSlot type in src/types.ts to include: 'description', 'content-type-selector', 'schema-tabs'
• Ensure src/components/Feature/OAOperation.vue references the updated slot type in its defineSlots<Record<string, OperationSlot>>() call
• Verify existing slot forwarding template in OAOperation captures and forwards the new slot names

🤖 Prompt for AI agents

Connect response slots to the top-level OAOperation component.

In src/components/Feature/OAOperationContent.vue:
- Verify existing `v-for` slot forwarding pattern captures and forwards the new
response slots
- Ensure slot props flow through without modification

In src/types.ts:
- Update OperationSlot type to include: `'description'`,
`'content-type-selector'`, `'schema-tabs'`

In src/components/Feature/OAOperation.vue:
- Verify `defineSlots<Record<string, OperationSlot>>()` references the updated
type
- Confirm existing slot forwarding template captures and forwards the new slot
names

Phase 4: Document Slot Props Interface

Provide TypeScript type safety and documentation for the new slot customization API.

Task 1: Define Response Slot Props Types

Create type definitions for the props available in response customization slots.

• Add new interface in src/types.ts (e.g., ResponseSlotProps) defining the structure: responseCode: string, response: OpenAPIV3.ResponseObject | OpenAPIV3_1.ResponseObject, operationId: string
• Include additional properties like content (ParsedContent) and description string where applicable for specific slots
• Use this type in slot prop bindings throughout the response component chain

Task 2: Update Slot Type Documentation

Enhance the OperationSlot type definition with inline documentation.

• Add JSDoc comments to the new slot names in the OperationSlot type explaining their purpose and available props
• Include usage examples in comments showing how to access responseCode, response, and other context
• Follow existing documentation patterns seen in other slot-related type definitions in the codebase

🤖 Prompt for AI agents

Add TypeScript types and documentation for response slot props.

In src/types.ts:
- Create a new interface `ResponseSlotProps` with properties: `responseCode:
string`, `response: OpenAPIV3.ResponseObject | OpenAPIV3_1.ResponseObject`,
`operationId: string`
- Include additional properties like `content` (ParsedContent) and `description`
string for specific slots
- Add JSDoc comments to the new slot names in OperationSlot type explaining
their purpose and available props
- Include usage examples showing how to access `responseCode`, `response`, and
other context

Update response component chain to use ResponseSlotProps in slot prop bindings

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Add slot customization to the OAResponse component for description, content-type
selector, and schema tabs.

In src/components/Response/OAResponse.vue:
- Add `defineSlots()` with three slots: `description`, `content-type-selector`,
`schema-tabs`
- Each slot should receive scoped props: `responseCode`, `response`,
`operationId`
- Wrap existing OAMarkdown description rendering in a conditional check: if
`description` slot exists, render it with bound props; otherwise render
OAMarkdown
- Apply the same conditional pattern to content-type selector and schema tabs
sections
- Use `v-if="$slots.slotName"` to check slot existence before falling back to
default rendering
===============================================================================

Task: 2

Implement slot forwarding in OAResponses to pass slots down to OAResponse
components.

In src/components/Response/OAResponses.vue:
- Add `defineSlots<Record<string, any>>()`
- Add a template block with `v-for="(_, name) in slots"` and
`#[name]="slotProps"` to dynamically forward all slots
- Wrap existing OAResponse rendering within the forwarding template
- When rendering OAResponse, bind slot props augmented with response context:
merge `slotProps` with `responseCode`, `response` data, and `operationId`
- Use `v-bind` to pass the merged props structure
===============================================================================

Task: 3

Connect response slots to the top-level OAOperation component.

In src/components/Feature/OAOperationContent.vue:
- Verify existing `v-for` slot forwarding pattern captures and forwards the new
response slots
- Ensure slot props flow through without modification

In src/types.ts:
- Update OperationSlot type to include: `'description'`,
`'content-type-selector'`, `'schema-tabs'`

In src/components/Feature/OAOperation.vue:
- Verify `defineSlots<Record<string, OperationSlot>>()` references the updated
type
- Confirm existing slot forwarding template captures and forwards the new slot
names
===============================================================================

Task: 4

Add TypeScript types and documentation for response slot props.

In src/types.ts:
- Create a new interface `ResponseSlotProps` with properties: `responseCode:
string`, `response: OpenAPIV3.ResponseObject | OpenAPIV3_1.ResponseObject`,
`operationId: string`
- Include additional properties like `content` (ParsedContent) and `description`
string for specific slots
- Add JSDoc comments to the new slot names in OperationSlot type explaining
their purpose and available props
- Include usage examples showing how to access `responseCode`, `response`, and
other context

Update response component chain to use ResponseSlotProps in slot prop bindings

💡 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 assumption 1 go ahead with option 3 and replan.