78 lines
5.5 KiB
Markdown
78 lines
5.5 KiB
Markdown
# Component Breakdown & Implementation Details
|
|
|
|
> This document is a granulated shard from the main "5-front-end-architecture.md" focusing on "Component Library, Reusable UI Components Guide, Atomic Design Elements, or Component Breakdown & Implementation Details".
|
|
|
|
This section outlines the conventions and templates for defining UI components. While a few globally shared or foundational components (e.g., main layout structures) might be specified here upfront to ensure consistency, the detailed specification for most feature-specific components will emerge as user stories are implemented. The key is for the development team (or AI agent) to follow the "Template for Component Specification" below whenever a new component is identified for development.
|
|
|
|
### Component Naming & Organization
|
|
|
|
- **Component File Naming:**
|
|
|
|
- React component files will use `PascalCase.tsx`. For example, `NewsletterCard.tsx`, `PodcastPlayer.tsx`.
|
|
- Next.js special files like `page.tsx`, `layout.tsx`, `loading.tsx`, `error.tsx`, `global-error.tsx`, and `not-found.tsx` will use their conventional lowercase or kebab-case names.
|
|
|
|
- **Component Organization (Reiteration from Directory Structure):**
|
|
|
|
- **Application-Specific Core Components:** Reusable components specific to BMad DiCaster (e.g., `NewsletterCard`, `PodcastPlayer`) will reside in `app/components/core/`.
|
|
- **Application-Specific Layout Components:** Components used for structuring page layouts (e.g., `PageWrapper.tsx`) will reside in `app/components/layout/`.
|
|
- **Shadcn UI Components:** Components added via the Shadcn UI CLI will reside in `components/ui/` (e.g., `Button.tsx`, `Card.tsx`).
|
|
- **Page-Specific Components:** If a component is complex but _only_ used on a single page, it can be co-located with that page's route file, for instance, in a `components` subfolder within that route's directory. However, the preference is to place reusable components in `app/components/core/` or `app/components/layout/`.
|
|
|
|
### Template for Component Specification
|
|
|
|
This template should be used to define and document each significant UI component identified from the UI/UX Specification (`docs/ui-ux-spec.txt`) and any subsequent design iterations. The goal is to provide sufficient detail for a developer or an AI agent to implement the component with minimal ambiguity. Most feature-specific components will be detailed emergently during development, following this template.
|
|
|
|
---
|
|
|
|
#### Component: `{ComponentName}` (e.g., `NewsletterCard`, `PodcastPlayerControls`)
|
|
|
|
- **Purpose:** {Briefly describe what this component does and its primary role in the user interface. What user need does it address?}
|
|
- **Source File(s):** {e.g., `app/components/core/NewsletterCard.tsx`}
|
|
- **Visual Reference:** {Link to specific Figma frame/component if available, or a detailed description/sketch if not. If based on a Shadcn UI component, note that and any key customizations.}
|
|
- **Props (Properties):**
|
|
{List each prop the component accepts. Specify its name, TypeScript type, whether it's required, any default value, and a clear description.}
|
|
| Prop Name | Type | Required? | Default Value | Description |
|
|
| :------------ | :------------------------------------ | :-------- | :------------ | :--------------------------------------------------- |
|
|
| `exampleProp` | `string` | Yes | N/A | Example string prop. |
|
|
| `items` | `Array<{id: string, name: string}>` | Yes | N/A | An array of item objects to display. |
|
|
| `variant` | `'primary' \| 'secondary'` | No | `'primary'` | Visual variant of the component. |
|
|
| `onClick` | `(event: React.MouseEvent) => void` | No | N/A | Optional click handler. |
|
|
- **Internal State (if any):**
|
|
{Describe any significant internal state the component manages using React hooks (e.g., `useState`).}
|
|
| State Variable | Type | Initial Value | Description |
|
|
| :---------------- | :-------- | :------------ | :------------------------------------------------ |
|
|
| `isLoading` | `boolean` | `false` | Tracks if data for the component is loading. |
|
|
| `selectedItem` | `string \| null` | `null` | Stores the ID of the currently selected item. |
|
|
- **Key UI Elements / Structure (Conceptual):**
|
|
{Describe the main visual parts of the component and their general layout. Reference Shadcn UI components if used as building blocks.}
|
|
```jsx
|
|
// Example for a Card component
|
|
<Card>
|
|
<CardHeader>
|
|
<CardTitle>{"{{titleProp}}"}</CardTitle>
|
|
<CardDescription>{"{{descriptionProp}}"}</CardDescription>
|
|
</CardHeader>
|
|
<CardContent>{/* {list of items or main content} */}</CardContent>
|
|
<CardFooter>{/* {action buttons or footer content} */}</CardFooter>
|
|
</Card>
|
|
```
|
|
- **Events Handled / Emitted:**
|
|
- **Handles:** {List significant DOM events the component handles directly.}
|
|
- **Emits (Callbacks):** {If the component uses props to emit events (callbacks) to its parent, list them here.}
|
|
- **Actions Triggered (Side Effects):**
|
|
- **State Management (Zustand):** {If the component interacts with a Zustand store, specify which store and actions.}
|
|
- **API Calls / Data Fetching:** {Specify how Client Components trigger mutations or re-fetches (e.g., Server Actions).}
|
|
- **Styling Notes:**
|
|
- {Reference to specific Shadcn UI components used.}
|
|
- {Key Tailwind CSS classes or custom styles for the "synthwave" theme.}
|
|
- {Specific responsiveness behavior.}
|
|
- **Accessibility (AX) Notes:**
|
|
- {Specific ARIA attributes needed.}
|
|
- {Keyboard navigation considerations.}
|
|
- {Focus management details.}
|
|
- {Notes on color contrast.}
|
|
|
|
---
|
|
|
|
_This template will be applied to each new significant component during the development process._
|