Keep/docs/component-inventory.md

Component Inventory - keep-notes

Overview

Complete inventory of React components in the Memento web application. The application uses 20+ domain-specific components organized by functionality.

Total Components: 20+ UI Library: Radix UI Icons: Lucide React

---

Component Categories

1. Authentication Components

Component	File	Purpose	Props
LoginForm	login-form.tsx	User login form	email, password, handleSubmit
RegisterForm	register-form.tsx	User registration	name, email, password, confirmPassword

Usage: Used in (auth)/login and (auth)/register routes

---

2. Note Components

Component	File	Purpose	Props
NoteCard	note-card.tsx	Individual note display	note, onPin, onArchive, onUpdate, onDelete
NoteEditor	note-editor.tsx	Rich note editor	note, onChange, onSave
NoteInput	note-input.tsx	Quick note creation	onCreate, autoFocus
NoteActions	note-actions.tsx	Note action menu	note, onEdit, onPin, onArchive, onDelete
NoteChecklist	note-checklist.tsx	Checklist items	items, onChange, onToggle
NoteImages	note-images.tsx	Image gallery	images, onAdd, onRemove
EditorImages	editor-images.tsx	Image upload/edit	images, onChange

Features:

• Drag-and-drop support via @dnd-kit
• Color-coded backgrounds
• Markdown rendering support
• Checklist with checkbox items
• Image attachments (base64 or URL)
• Pin/unpin functionality
• Archive/unarchive

---

3. Label Components

Component	File	Purpose	Props
LabelBadge	label-badge.tsx	Label display badge	label, onRemove, color
LabelFilter	label-filter.tsx	Filter by labels	labels, selectedLabels, onChange
LabelSelector	label-selector.tsx	Select labels for note	availableLabels, selectedLabels, onChange
LabelManager	label-manager.tsx	Manage user labels	labels, onCreate, onUpdate, onDelete
LabelManagementDialog	label-management-dialog.tsx	Label management modal	isOpen, onClose, labels
GhostTags	ghost-tags.tsx	Floating tag display	tags, onTagClick

Color Options: red, orange, yellow, green, teal, blue, purple, pink, gray

---

4. Layout Components

Component	File	Purpose	Props
Header	header.tsx	Application header	title, user
HeaderWrapper	header-wrapper.tsx	Header container with logic	children, user
Sidebar	sidebar.tsx	Navigation sidebar	isOpen, onClose
MasonryGrid	masonry-grid.tsx	Masonry grid layout	items, renderItem

Layout Libraries:

• Muuri (masonry grid)
• react-grid-layout
• @dnd-kit (drag and drop)

---

5. Content Components

Component	File	Purpose	Props
MarkdownContent	markdown-content.tsx	Markdown renderer	content, className

Features:

• GitHub Flavored Markdown (GFM)
• Syntax highlighting (if configured)
• Safe rendering (sanitization)

---

6. User Components

Component	File	Purpose	Props
UserNav	user-nav.tsx (inferred)	User navigation menu	user, onLogout

Features:

• Profile settings access
• Logout functionality
• Theme toggle

---

7. Dialog/Modal Components

Component	File	Purpose	Props
ReminderDialog	reminder-dialog.tsx	Set note reminders	note, onSave, onClose

Features:

• Date/time picker
• Recurrence options
• Location-based reminders (future)

---

8. UI Primitives (Radix UI)

Located in components/ui/ - Auto-generated or minimal wrappers around Radix UI:

Component	Radix Primitive	Purpose
Avatar	@radix-ui/react-avatar	User avatar display
Checkbox	@radix-ui/react-checkbox	Checkbox input
Dialog	@radix-ui/react-dialog	Modal dialogs
Dropdown Menu	@radix-ui/react-dropdown-menu	Dropdown menus
Popover	@radix-ui/react-popover	Floating content
Separator	@radix-ui/react-separator	Visual separators
Slot	@radix-ui/react-slot	Component composition
Tooltip	@radix-ui/react-tooltip	Hover tooltips

Usage: Domain components compose these primitives

---

Component Hierarchy

Layout Components
├── Header → HeaderWrapper
│   └── UserNav
├── Sidebar
└── MasonryGrid
    └── NoteCard
        ├── NoteEditor
        │   ├── NoteChecklist
        │   ├── NoteImages
        │   └── EditorImages
        └── NoteActions

Label Management
├── LabelBadge
├── LabelFilter
├── LabelSelector
├── LabelManager → LabelManagementDialog
└── GhostTags

Authentication
├── LoginForm
└── RegisterForm

Content
└── MarkdownContent

---

Component Patterns

1. Compound Components

NoteEditor contains:

• NoteChecklist (if type=checklist)
• NoteImages
• EditorImages

HeaderWrapper wraps:

• Header
• UserNav

2. Controlled Components

Most components are controlled (parent state):

• NoteCard receives note object and callbacks
• LabelFilter receives selected labels and onChange
• NoteEditor manages local state, calls onSave

3. Modal Pattern

Dialogs use Radix Dialog:

• LabelManagementDialog
• ReminderDialog

Pattern:

{isOpen && (
  <Dialog open={isOpen} onOpenChange={onClose}>
    <DialogContent>{/* content */}</DialogContent>
  </Dialog>
)}

---

Component Communication

Props Drilling

• Components receive data via props
• Callbacks passed for mutations

Server Actions

• Note mutations via app/actions/notes.ts
• Label mutations via server actions
• Auth mutations via app/actions/register.ts

Context Providers

• User session context (from NextAuth)
• Theme context (light/dark mode)

---

Design System

Colors

Note Colors: default, red, orange, yellow, green, teal, blue, purple, pink, gray

Label Colors: Same palette as notes

Typography

• Font: System font stack (Tailwind default)
• Sizes: Based on Tailwind typography plugin

Spacing

• Gap: Tailwind spacing scale
• Padding: Consistent 4px/8px/16px/24px increments

---

Component State Management

Local State

• Form inputs (controlled components)
• Modal open/closed state
• Temporary editing state

Server State

• Notes list (fetched from API)
• User session (NextAuth)
• Labels (fetched from API)

State Updates

1. User action → Server action / API call
2. Database update (Prisma)
3. Revalidate / refetch
4. Component re-render

No Global State Library: Uses React Context + hooks instead of Redux/Zustand

---

Component Dependencies

UI Libraries

• Radix UI (primitives)
• Tailwind CSS (styling)
• Lucide React (icons)
• @dnd-kit (drag and drop)
• Muuri (masonry layout)
• react-grid-layout (grid system)
• react-markdown (markdown rendering)
• react-masonry-css (alternative masonry)

Custom Hooks

• Located in hooks/
• Used for:
  • Form validation
  • Local storage
  • Debouncing
  • Media queries

---

Component Performance

Optimizations

• React.memo (selective components)
• Lazy loading (dynamic imports)
• Image optimization (next/image)
• Code splitting (route-based)

Masonry Grid

• Muuri for performant drag-and-drop
• Virtualization for large note lists

---

Component Testing

E2E Coverage

• Playwright tests in tests/
• Coverage: Component interactions
• Test file: search-quality.spec.ts

Manual Testing

• Test UI in npm run test:headed
• Test reports: playwright-report/

---

Component Styling

CSS Strategy

• Framework: Tailwind CSS 4
• Approach: Utility-first
• Custom CSS: In globals.css
• Component Styles: Tailwind classes

Responsive Design

• Mobile-first approach
• Breakpoints: sm, md, lg, xl
• Grid adapts to screen size

Theme Support

• Light/dark mode via user preference
• Theme stored in User.theme
• CSS variables for theme colors

---

Accessibility

Radix UI Features

• Keyboard navigation
• ARIA attributes
• Focus management
• Screen reader support

Custom A11y

• Alt text for images
• Semantic HTML
• Form labels
• Error messages

---

Component Future Enhancements

Potential Improvements:

1. Add skeleton loaders
2. Implement error boundaries
3. Add undo/redo for note edits
4. Rich text editor (WYSIWYG)
5. Collaborative editing
6. Note templates
7. Color picker for custom colors
8. Drag-and-drop file upload
9. Voice input (Web Speech API)
10. Export/import notes

---

Component Maintenance

File Organization:

• Domain-driven (note-, label-, auth-*)
• Co-located with related components
• Clear naming conventions

Code Quality:

• TypeScript for type safety
• Consistent prop interfaces
• Reusable UI primitives
• Minimal prop drilling (use context where appropriate)

---

Component Usage Examples

NoteCard

<NoteCard
  note={note}
  onPin={() => handleTogglePin(note.id)}
  onArchive={() => handleToggleArchive(note.id)}
  onUpdate={(updates) => handleUpdateNote(note.id, updates)}
  onDelete={() => handleDeleteNote(note.id)}
/>

LabelSelector

<LabelSelector
  availableLabels={labels}
  selectedLabels={note.labels || []}
  onChange={(newLabels) => updateNoteLabels(note.id, newLabels)}
/>

MasonryGrid

<MasonryGrid
  items={notes}
  renderItem={(note) => <NoteCard key={note.id} note={note} />}
/>

---

Summary

The Memento application uses a well-organized component architecture with:

• 20+ domain components for notes, labels, auth, and layout
• Radix UI primitives for accessible, composable UI
• Controlled components with parent-managed state
• Server actions for mutations
• No global state library (Context + hooks instead)
• Drag-and-drop via @dnd-kit
• Masonry layout via Muuri
• Responsive design with Tailwind CSS