whiteport-design-studio 0.1.0

package/src/workflows/4-ux-design/COMPONENT-FILE-STRUCTURE.md

@@ -0,0 +1,742 @@
+# Component File Structure
+
+**Modular Organization for Complex Components**
+
+---
+
+## Problem Statement
+
+Complex components (calendars, calculators, graphs, interactive widgets) contain three distinct types of information that should be separated:
+
+1. **Page Context** - Where/how component appears on specific pages
+2. **Design System** - Visual design, states, Figma specifications
+3. **Feature Logic** - Interactive behavior, business rules, data flow
+
+**Current Issue:** All three are mixed in page specifications, making them hard to maintain and reuse.
+
+---
+
+## Proposed Structure
+
+### File Organization
+
+```
+project-root/
+├─ Pages/                          # Page-specific context
+│  ├─ 01-start-page.md
+│  ├─ 02-calendar-page.md
+│  └─ 03-profile-page.md
+│
+├─ Components/                     # Design System components
+│  ├─ navigation-bar.component.md
+│  ├─ feature-card.component.md
+│  ├─ calendar-widget.component.md
+│  └─ walk-scheduler.component.md
+│
+└─ Features/                       # Interactive logic & business rules
+   ├─ calendar-logic.feature.md
+   ├─ walk-assignment.feature.md
+   ├─ notification-system.feature.md
+   └─ user-permissions.feature.md
+```
+
+---
+
+## File Type Definitions
+
+### 1. Page Files (`Pages/*.md`)
+
+**Purpose:** Page-specific layout, component placement, and context
+
+**Contains:**
+
+- Page metadata (URL, scenario, purpose)
+- Layout structure (sections, grid)
+- Component instances with page-specific config
+- Content in all languages
+- Navigation flow (entry/exit points)
+
+**Does NOT contain:**
+
+- Component visual design (→ Components/)
+- Interactive logic (→ Features/)
+
+**Example:** `02-calendar-page.md`
+
+```markdown
+# 02-calendar-page
+
+**Scenario:** Manage Dog Care Schedule
+**URL:** `/calendar`
+
+## Layout Structure
+
+### Header Section
+
+- Component: `navigation-bar` (from Components/)
+- Position: Top, full-width
+
+### Main Content
+
+- Component: `calendar-widget` (from Components/)
+- Position: Center, 80% width
+- Configuration:
+  - View: Month
+  - Start Day: Monday
+  - Show: Walk assignments only
+- Feature: `calendar-logic` (from Features/)
+
+### Sidebar
+
+- Component: `walk-scheduler` (from Components/)
+- Position: Right, 20% width
+- Feature: `walk-assignment` (from Features/)
+
+## Content
+
+**Page Title:**
+
+- EN: "Family Dog Care Calendar"
+- SE: "Familjens Hundvårdskalender"
+```
+
+---
+
+### 2. Component Files (`Components/*.md`)
+
+**Purpose:** Visual design, states, variants, Figma specifications
+
+**Contains:**
+
+- Component name and purpose
+- Visual specifications (colors, spacing, typography)
+- States (default, hover, active, disabled, loading, error)
+- Variants (sizes, types, themes)
+- Figma component mapping
+- Responsive behavior
+- Accessibility requirements
+
+**Does NOT contain:**
+
+- Business logic (→ Features/)
+- Page-specific placement (→ Pages/)
+
+**Example:** `calendar-widget.component.md`
+
+```markdown
+# Calendar Widget Component
+
+**Type:** Complex Interactive Component
+**Design System ID:** `calendar-widget`
+**Figma Component:** `DS/Widgets/Calendar`
+
+## Purpose
+
+Displays a monthly calendar view with interactive date selection and event display.
+
+## Visual Specifications
+
+### Layout
+
+- Grid: 7 columns (days) × 5-6 rows (weeks)
+- Cell size: 48px × 48px (desktop), 40px × 40px (mobile)
+- Gap: 4px between cells
+- Padding: 16px container padding
+
+### Typography
+
+- Month/Year header: Large Heading (24px Bold)
+- Day labels: Caption (12px Medium)
+- Date numbers: Body Text (16px Regular)
+- Event indicators: Caption (10px Regular)
+
+### Colors
+
+- Background: `--color-surface`
+- Cell default: `--color-surface-elevated`
+- Cell hover: `--color-surface-hover`
+- Cell selected: `--color-primary`
+- Cell today: `--color-accent`
+- Cell disabled: `--color-surface-disabled`
+
+## States
+
+### Default State
+
+- All dates visible
+- Current month displayed
+- Today highlighted with accent color
+- No date selected
+
+### Date Selected
+
+- Selected date: Primary color background
+- Date number: White text
+- Border: 2px solid primary-dark
+
+### Date Hover
+
+- Background: Surface-hover color
+- Cursor: Pointer
+- Transition: 150ms ease
+
+### Date Disabled (Past dates)
+
+- Background: Surface-disabled
+- Text: Gray-400
+- Cursor: Not-allowed
+- No hover effect
+
+### Loading State
+
+- Skeleton animation on date cells
+- Month/year header visible
+- Navigation disabled
+
+### With Events
+
+- Small dot indicator below date number
+- Dot color: Event category color
+- Max 3 dots visible per cell
+
+## Variants
+
+### Size Variants
+
+- **Large:** 56px cells (desktop default)
+- **Medium:** 48px cells (tablet)
+- **Small:** 40px cells (mobile)
+
+### View Variants
+
+- **Month View:** Default, shows full month
+- **Week View:** Shows 7 days in row
+- **Day View:** Shows single day with hourly slots
+
+## Figma Specifications
+
+**Component Path:** `Design System > Widgets > Calendar`
+
+**Variants to Create:**
+
+- Size: Large / Medium / Small
+- View: Month / Week / Day
+- State: Default / Selected / Disabled / Loading
+
+**Auto-layout:** Enabled
+**Constraints:** Fill container width
+
+## Responsive Behavior
+
+### Mobile (< 768px)
+
+- Use Small variant (40px cells)
+- Stack month navigation vertically
+- Reduce padding to 12px
+
+### Tablet (768px - 1024px)
+
+- Use Medium variant (48px cells)
+- Horizontal month navigation
+- Standard padding (16px)
+
+### Desktop (> 1024px)
+
+- Use Large variant (56px cells)
+- Full navigation controls
+- Increased padding (20px)
+
+## Accessibility
+
+- **Keyboard Navigation:**
+  - Arrow keys: Navigate between dates
+  - Enter/Space: Select date
+  - Tab: Move to month navigation
+- **Screen Readers:**
+  - ARIA label: "Calendar, {Month} {Year}"
+  - Each date: "Select {Day}, {Date} {Month}"
+  - Selected date: "Selected, {Day}, {Date} {Month}"
+- **Focus Management:**
+  - Visible focus ring on keyboard navigation
+  - Focus trap within calendar when open
+
+## Dependencies
+
+- **Features:** Requires `calendar-logic.feature.md` for interaction behavior
+- **Data:** Expects events array from API
+```
+
+---
+
+### 3. Feature Files (`Features/*.md`)
+
+**Purpose:** Interactive logic, business rules, data flow, state management
+
+**Contains:**
+
+- Feature name and purpose
+- User interactions and system responses
+- Business rules and validation
+- State transitions
+- Data requirements (API endpoints, data models)
+- Edge cases and error handling
+
+**Does NOT contain:**
+
+- Visual design (→ Components/)
+- Page layout (→ Pages/)
+
+**Example:** `calendar-logic.feature.md`
+
+````markdown
+# Calendar Logic Feature
+
+**Feature ID:** `calendar-logic`
+**Type:** Interactive Widget Logic
+**Complexity:** High
+
+## Purpose
+
+Manages calendar interactions, date selection, event display, and navigation between months/weeks/days.
+
+## User Interactions
+
+### Interaction 1: Select Date
+
+**Trigger:** User clicks on a date cell
+
+**Flow:**
+
+1. User clicks date cell
+2. System validates date is not disabled
+3. System updates selected date state
+4. System triggers `onDateSelect` callback with date
+5. System highlights selected date
+6. System updates related components (e.g., event list for that date)
+
+**Business Rules:**
+
+- Cannot select dates in the past (configurable)
+- Cannot select dates beyond 1 year in future (configurable)
+- Can only select one date at a time (single-select mode)
+- Can select date range (range-select mode, if enabled)
+
+**Edge Cases:**
+
+- Clicking already selected date: Deselects it
+- Clicking disabled date: No action, show tooltip
+- Rapid clicking: Debounce to prevent multiple selections
+
+### Interaction 2: Navigate to Next Month
+
+**Trigger:** User clicks "Next Month" button
+
+**Flow:**
+
+1. User clicks next month button
+2. System increments month by 1
+3. System fetches events for new month (if needed)
+4. System re-renders calendar with new month
+5. System clears selected date (optional, configurable)
+6. System updates month/year header
+
+**Business Rules:**
+
+- Cannot navigate beyond max date (1 year from today)
+- Loading state shown while fetching events
+- Previous selections cleared on month change
+
+### Interaction 3: View Events for Date
+
+**Trigger:** User hovers over date with event indicators
+
+**Flow:**
+
+1. User hovers over date cell with events
+2. System shows tooltip with event summary
+3. Tooltip displays: Event count, first 2 event titles
+4. User can click to see full event list
+
+**Business Rules:**
+
+- Tooltip appears after 300ms hover
+- Max 2 events shown in tooltip
+- "And X more" shown if > 2 events
+
+## State Management
+
+### Component State
+
+```javascript
+{
+  currentMonth: Date,           // Currently displayed month
+  selectedDate: Date | null,    // User-selected date
+  viewMode: 'month' | 'week' | 'day',
+  events: Event[],              // Events for current view
+  loading: boolean,             // Loading state
+  error: string | null          // Error message
+}
+```
+````
+
+### State Transitions
+
+**Initial State:**
+
+- currentMonth: Current month
+- selectedDate: null
+- viewMode: 'month'
+- events: []
+- loading: false
+- error: null
+
+**On Date Select:**
+
+- selectedDate: clicked date
+- Trigger callback: onDateSelect(date)
+
+**On Month Change:**
+
+- currentMonth: new month
+- selectedDate: null (if clearOnMonthChange = true)
+- loading: true
+- Fetch events for new month
+- loading: false
+
+**On Error:**
+
+- error: error message
+- loading: false
+- Show error state in UI
+
+## Data Requirements
+
+### API Endpoints
+
+**Get Events for Month**
+
+- **Method:** GET
+- **Path:** `/api/calendar/events?month={YYYY-MM}`
+- **Purpose:** Fetch all events for specified month
+- **Response:**
+  ```json
+  {
+    "events": [
+      {
+        "id": "evt_123",
+        "date": "2024-12-15",
+        "title": "Morning Walk - Max",
+        "category": "walk",
+        "assignedTo": "user_456"
+      }
+    ]
+  }
+  ```
+
+**Create Event**
+
+- **Method:** POST
+- **Path:** `/api/calendar/events`
+- **Purpose:** Create new calendar event
+- **Request:**
+  ```json
+  {
+    "date": "2024-12-15",
+    "title": "Morning Walk",
+    "category": "walk",
+    "assignedTo": "user_456"
+  }
+  ```
+
+### Data Models
+
+**Event Model:**
+
+```typescript
+interface Event {
+  id: string;
+  date: string; // ISO date format
+  title: string;
+  category: 'walk' | 'feeding' | 'vet' | 'grooming';
+  assignedTo: string; // User ID
+  completed: boolean;
+  notes?: string;
+}
+```
+
+## Validation Rules
+
+| Rule         | Validation                                | Error Message                          |
+| ------------ | ----------------------------------------- | -------------------------------------- |
+| Date in past | `date < today`                            | "Cannot select past dates"             |
+| Date too far | `date > today + 365 days`                 | "Cannot select dates beyond 1 year"    |
+| Event title  | `title.length > 0 && title.length <= 100` | "Event title required (max 100 chars)" |
+
+## Error Handling
+
+### Network Error (Failed to fetch events)
+
+- **Trigger:** API request fails
+- **Action:** Show error state in calendar
+- **Message:** "Unable to load events. Please try again."
+- **Recovery:** Retry button
+
+### Invalid Date Selection
+
+- **Trigger:** User attempts to select disabled date
+- **Action:** Show tooltip
+- **Message:** "This date is not available"
+- **Recovery:** Select different date
+
+## Configuration Options
+
+```javascript
+{
+  minDate: Date | null,          // Earliest selectable date
+  maxDate: Date | null,          // Latest selectable date
+  disablePastDates: boolean,     // Disable dates before today
+  clearOnMonthChange: boolean,   // Clear selection on month change
+  selectionMode: 'single' | 'range',
+  showEventIndicators: boolean,  // Show dots for events
+  fetchEventsOnMount: boolean,   // Auto-fetch on load
+  onDateSelect: (date: Date) => void,
+  onMonthChange: (month: Date) => void,
+  onEventClick: (event: Event) => void
+}
+```
+
+## Dependencies
+
+- **Component:** `calendar-widget.component.md` (visual design)
+- **Feature:** `walk-assignment.feature.md` (for creating walk events)
+- **API:** Calendar Events API
+
+```
+
+---
+
+## Benefits of This Structure
+
+### 1. Separation of Concerns
+
+| Concern | File Type | Example |
+|---------|-----------|---------|
+| **Where** component appears | Page | `02-calendar-page.md` |
+| **How** component looks | Component | `calendar-widget.component.md` |
+| **What** component does | Feature | `calendar-logic.feature.md` |
+
+### 2. Reusability
+
+**Component used on multiple pages:**
+```
+
+Pages/02-calendar-page.md → Components/calendar-widget.component.md
+Pages/05-dashboard.md → Components/calendar-widget.component.md
+↓
+Features/calendar-logic.feature.md
+
+```
+
+**Same component, different configurations:**
+- Calendar Page: Month view, full-width
+- Dashboard: Week view, sidebar widget
+
+### 3. Team Collaboration
+
+| Role | Primary Files | Secondary Files |
+|------|---------------|-----------------|
+| **UX Designer** | Components/ | Pages/ (layout) |
+| **Developer** | Features/ | Components/ (implementation) |
+| **Content Writer** | Pages/ | - |
+| **Product Manager** | Features/ (rules) | Pages/ (flow) |
+
+### 4. Maintainability
+
+**Change visual design:**
+- Edit: `Components/calendar-widget.component.md`
+- Impact: All pages using calendar automatically updated
+
+**Change business logic:**
+- Edit: `Features/calendar-logic.feature.md`
+- Impact: All instances of calendar use new logic
+
+**Change page layout:**
+- Edit: `Pages/02-calendar-page.md`
+- Impact: Only that specific page
+
+---
+
+## File Naming Conventions
+
+### Pages
+```
+
+{number}-{page-name}.md
+
+Examples:
+01-start-page.md
+02-calendar-page.md
+03-profile-settings.md
+
+```
+
+### Components
+```
+
+{component-name}.component.md
+
+Examples:
+navigation-bar.component.md
+feature-card.component.md
+calendar-widget.component.md
+walk-scheduler.component.md
+
+```
+
+### Features
+```
+
+{feature-name}.feature.md
+
+Examples:
+calendar-logic.feature.md
+walk-assignment.feature.md
+user-authentication.feature.md
+notification-system.feature.md
+
+````
+
+---
+
+## Cross-Reference System
+
+### In Page Files
+
+Reference components and features:
+
+```markdown
+### Main Content Section
+
+**Component:** `calendar-widget` (→ Components/calendar-widget.component.md)
+**Feature:** `calendar-logic` (→ Features/calendar-logic.feature.md)
+**Configuration:**
+- View: Month
+- Disable past dates: true
+````
+
+### In Component Files
+
+Reference required features:
+
+```markdown
+## Dependencies
+
+- **Feature:** `calendar-logic.feature.md` (interaction behavior)
+- **Feature:** `walk-assignment.feature.md` (event creation)
+```
+
+### In Feature Files
+
+Reference related components:
+
+```markdown
+## Dependencies
+
+- **Component:** `calendar-widget.component.md` (visual implementation)
+- **API:** Calendar Events API
+```
+
+---
+
+## Migration Strategy
+
+### Phase 1: Create Structure
+
+1. Create `Components/` folder
+2. Create `Features/` folder
+3. Keep existing `Pages/` (or create if needed)
+
+### Phase 2: Extract Components
+
+1. Identify reusable components in page specs
+2. Create component files with visual design only
+3. Update page files to reference components
+
+### Phase 3: Extract Features
+
+1. Identify complex interactive logic
+2. Create feature files with business rules
+3. Update page and component files to reference features
+
+### Phase 4: Refactor Existing Pages
+
+1. Move visual specs → Components/
+2. Move logic → Features/
+3. Keep layout & content in Pages/
+
+---
+
+## Example: Dog Week Calendar
+
+### Before (Monolithic)
+
+```
+Pages/02-calendar-page.md (500 lines)
+├─ Page layout
+├─ Calendar visual design
+├─ Calendar interaction logic
+├─ Walk scheduler visual design
+├─ Walk assignment logic
+├─ Navigation bar design
+└─ All content in all languages
+```
+
+### After (Modular)
+
+```
+Pages/02-calendar-page.md (100 lines)
+├─ Page layout
+├─ Component references
+├─ Feature references
+└─ Content in all languages
+
+Components/calendar-widget.component.md (150 lines)
+├─ Visual specifications
+├─ States & variants
+└─ Figma mapping
+
+Components/walk-scheduler.component.md (100 lines)
+├─ Visual specifications
+└─ States & variants
+
+Features/calendar-logic.feature.md (200 lines)
+├─ Interaction flows
+├─ Business rules
+├─ Data requirements
+└─ Error handling
+
+Features/walk-assignment.feature.md (150 lines)
+├─ Assignment logic
+├─ Validation rules
+└─ API integration
+```
+
+**Result:** Easier to maintain, reuse, and collaborate!
+
+---
+
+## Summary
+
+**Three-tier architecture:**
+
+1. **Pages/** - Layout, placement, content (WHERE)
+2. **Components/** - Visual design, states, Figma (HOW IT LOOKS)
+3. **Features/** - Logic, rules, data (WHAT IT DOES)
+
+**Benefits:**
+
+- ✅ Clear separation of concerns
+- ✅ Reusable components across pages
+- ✅ Maintainable business logic
+- ✅ Better team collaboration
+- ✅ Aligns with BMad v6 modular philosophy