|
| 1 | +# ADR 0004: Cask Component Architecture |
| 2 | + |
| 3 | +## Status |
| 4 | +Accepted |
| 5 | + |
| 6 | +## Context |
| 7 | +The project requires a foundational design system component that can serve as a generic container, replacing the need for multiple basic HTML elements while maintaining type safety and flexibility. |
| 8 | + |
| 9 | +## Decision |
| 10 | +We will implement the **Cask component** as a polymorphic React component with the following architecture: |
| 11 | + |
| 12 | +### Core Design: |
| 13 | +- **Polymorphic typing**: Component can render as any HTML element via the `as` prop |
| 14 | +- **Default element**: Renders as `div` when no `as` prop is provided |
| 15 | +- **Props forwarding**: All HTML attributes are properly forwarded to the underlying element |
| 16 | +- **Named export**: Component is exported as named export (not default) for better tree-shaking |
| 17 | + |
| 18 | +## Rationale |
| 19 | + |
| 20 | +### Design Principles: |
| 21 | +1. **Flexibility**: Single component can replace multiple basic HTML containers |
| 22 | +2. **Type Safety**: TypeScript ensures element-specific props are correctly typed |
| 23 | +3. **Developer Experience**: Intuitive API similar to styled-components polymorphic pattern |
| 24 | +4. **Performance**: Minimal runtime overhead with compile-time type checking |
| 25 | + |
| 26 | +### Technical Implementation: |
| 27 | +- **TypeScript generics**: `Cask<T extends ElementType = 'div'>` for polymorphic typing |
| 28 | +- **Props intersection**: Combines component props with element-specific props via `ComponentProps<T>` |
| 29 | +- **Runtime element selection**: `const Component = as || 'div'` for dynamic rendering |
| 30 | +- **Clean API**: Simple prop spreading pattern for attribute forwarding |
| 31 | + |
| 32 | +### File Structure: |
| 33 | +``` |
| 34 | +src/cask/ |
| 35 | +├── index.ts # Named export barrel |
| 36 | +├── Cask.tsx # Component implementation |
| 37 | +└── Cask.test.tsx # Comprehensive unit tests |
| 38 | +``` |
| 39 | + |
| 40 | +### Usage Examples: |
| 41 | +```tsx |
| 42 | +// Default div rendering |
| 43 | +<Cask>Content</Cask> |
| 44 | + |
| 45 | +// Semantic HTML elements |
| 46 | +<Cask as="section">Section content</Cask> |
| 47 | +<Cask as="header">Header content</Cask> |
| 48 | + |
| 49 | +// Interactive elements with proper typing |
| 50 | +<Cask as="button" onClick={handler}>Click me</Cask> |
| 51 | +<Cask as="a" href="https://example.com">Link</Cask> |
| 52 | +``` |
| 53 | + |
| 54 | +### Import Pattern: |
| 55 | +```tsx |
| 56 | +import { Cask } from '@/src/cask' |
| 57 | +``` |
| 58 | + |
| 59 | +## Consequences |
| 60 | + |
| 61 | +### Positive: |
| 62 | +- **Reduced component proliferation**: Single component handles multiple container use cases |
| 63 | +- **Consistent API**: Uniform interface across different HTML elements |
| 64 | +- **Type safety**: Compile-time verification of element-specific attributes |
| 65 | +- **Tree-shaking friendly**: Named exports support better bundling optimization |
| 66 | +- **Testable**: Clear interface enables comprehensive unit testing |
| 67 | + |
| 68 | +### Negative: |
| 69 | +- **Learning curve**: Team needs to understand polymorphic component patterns |
| 70 | +- **Type complexity**: Generic types may be challenging for junior developers |
| 71 | +- **Runtime cost**: Minimal overhead from dynamic element selection |
| 72 | + |
| 73 | +### Design System Impact: |
| 74 | +- **Foundation layer**: Establishes pattern for future polymorphic components |
| 75 | +- **Styling integration**: Ready for future Next Yak styling system integration |
| 76 | +- **Extensibility**: Architecture supports future enhancements (themes, variants) |
| 77 | + |
| 78 | +### Testing Strategy: |
| 79 | +- **Unit tests**: Cover default behavior, polymorphic rendering, props forwarding |
| 80 | +- **Type tests**: Verify TypeScript type safety in various scenarios |
| 81 | +- **Integration tests**: Ensure compatibility with Next.js build process |
0 commit comments