Component Organization Patterns

Guidelines for structuring React components in the Shadow Master codebase.

Component Directory Overview

/components/                    # 130+ components total
├── index.ts                    # Root exports (DiceRoller only)
├── *.tsx                       # 6 standalone utility components
├── action-resolution/          # 3 components - dice pool building
├── auth/                       # 1 component - email verification
├── character/                  # 12 components - character sheet display
├── combat/                     # 4 components - combat tracking UI
├── creation/                   # 83 components - character creation
│   ├── *.tsx                   # 14 top-level cards
│   ├── shared/                 # 14 reusable utilities
│   └── {feature}/              # 17 feature subfolders
├── cyberlimbs/                 # 6 components - augmentation UI
├── sync/                       # 2 components - ruleset sync status
└── ui/                         # 2 components - BaseModal, Tooltip

Decision Flowchart

Does the component have modals?
├─ Yes → Create subfolder, extract modals
└─ No → Does it have reusable Row/ListItem components?
        ├─ Yes, used elsewhere → Create subfolder
        └─ No → Keep as single file with internal helpers

When to Use a Subfolder

Create a subfolder with index.ts when:

• Component has one or more modals (selection dialogs, forms, etc.)
• Component has reusable row/list item components used in multiple places
• Component exceeds ~600 lines with clear separable concerns
• Component has distinct UI pieces that could be tested independently

Subfolder structure:

/components/{area}/{feature}/
├── FeatureCard.tsx           # Main component
├── FeatureModal.tsx          # Selection/edit modal
├── FeatureRow.tsx            # Optional: if row is complex/reusable
├── constants.ts              # Optional: magic values, options arrays
├── types.ts                  # Optional: feature-specific types
├── utils.ts                  # Optional: feature-specific helpers
├── index.ts                  # Re-exports public API

Index file pattern:

// index.ts - export only public API
export { FeatureCard } from "./FeatureCard";
export { FeatureModal } from "./FeatureModal"; // Only if used externally

When to Keep as Single File

Keep as a single file when:

• Component is self-contained with only internal helper components
• Internal components are tightly coupled and only make sense within the parent
• Component is under ~400 lines with straightforward structure
• No modals or independently reusable pieces

Component Areas

Root-Level Components (6 files)

Standalone utility components that don't fit a specific feature area:

/components/ui/ - Shared UI Primitives

Low-level accessible components used across the app. Built on React Aria.

When to add here: Generic UI primitives with no business logic.

/components/auth/ - Authentication Components

/components/action-resolution/ - Dice Pool Building

Components for building and displaying action resolution dice pools.

Note: No index.ts - import directly from files.

/components/character/ - Character Sheet Display

Components for viewing active characters (not creation). No index file - import directly.

/components/combat/ - Combat Tracking

Components for running combat encounters. Has index.ts and co-located tests.

/components/cyberlimbs/ - Cyberlimb Management

Components for cyberlimb augmentation display and modification.

/components/sync/ - Ruleset Synchronization

Components for displaying ruleset sync status and migration.

/components/creation/ - Character Creation

The largest component area (83 components). Organized by feature with shared utilities.

Top-Level Cards (14 files)

Single-file cards without complex modals:

Feature Subfolders (17 directories)

Shared Utilities (/creation/shared/)

Adding Components by Area

Adding a Creation Card

1. Determine structure using the decision flowchart
2. Create in /components/creation/ or /components/creation/{feature}/
3. Use CreationCard wrapper from /components/creation/shared/
4. Add to SheetCreationLayout.tsx in appropriate column
5. Update CreationState type in /lib/types/creation.ts if needed
6. Export from /components/creation/index.ts

Adding a Combat Component

1. Create in /components/combat/
2. Export from /components/combat/index.ts
3. Add co-located test in /components/combat/__tests__/

Adding a Character Sheet Component

1. Create in /components/character/
2. Import directly from file (no index.ts)
3. Add to relevant page in /app/characters/[id]/

Adding a Cyberlimb Component

1. Create in /components/cyberlimbs/
2. Export from /components/cyberlimbs/index.ts
3. Export types if needed for external use

Adding a UI Primitive

1. Create in /components/ui/
2. Build on React Aria for accessibility
3. Export from /components/ui/index.ts
4. No business logic - pure presentation

Adding a New API Endpoint

1. Create /app/api/{path}/route.ts
2. Export HTTP method handlers (GET, POST, PUT, DELETE)
3. Follow authentication pattern (getSession → validate user)
4. Call storage layer functions
5. Return JSON responses

Adding a New Ruleset Module

1. Define module type in /lib/types/edition.ts
2. Add module to book payload in /data/editions/{editionCode}/
3. Update merge logic in /lib/rules/merge.ts if special handling needed
4. Create hook in RulesetContext.tsx for easy access

Key Reference Files

• components/ui/BaseModal.tsx - Accessible modal foundation
• components/creation/shared/CreationCard.tsx - Card wrapper pattern
• components/creation/SkillsCard.tsx - Modal-based editing example
• components/combat/CombatTracker.tsx - Combat component with tests
• components/cyberlimbs/index.ts - Feature folder export pattern
• app/characters/create/sheet/components/SheetCreationLayout.tsx - Three-column layout

Component Diagram Generation

Mermaid diagrams are auto-generated from the component structure.

Commands

# Preview all areas to stdout
pnpm generate-diagrams

# Generate specific area
pnpm generate-diagrams --area=combat
pnpm generate-diagrams --area=creation

# Update documentation files
pnpm generate-diagrams --output=files

# Verbose mode with component counts
pnpm generate-diagrams --verbose

Output Locations

Diagram Color Key

When to Regenerate

Run pnpm generate-diagrams --output=files after:

• Adding a new component folder
• Adding/removing modals or cards
• Reorganizing component structure
• Before major documentation updates

Validation

# Validate creation docs structure (doesn't regenerate)
pnpm validate-creation-docs --verbose

Documentation Structure

Hand-Written (detailed)

/docs/architecture/creation-components/ - Detailed creation component docs with:

• Component descriptions
• Props documentation
• Usage patterns
• Context dependencies

Auto-Generated (overview)

/docs/architecture/components/ - Generated hierarchy diagrams:

• Mermaid component trees
• Summary tables
• Color-coded by type

Index File Conventions