Component Organization Patterns

Guidelines for structuring React components in the Shadow Master codebase.

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/creation/qualities/
├── QualitiesCard.tsx        # Main card component
├── QualityModal.tsx         # Selection/edit modal
├── QualityRow.tsx           # Optional: if row is complex/reusable
├── index.ts                 # Re-exports public components

Index file pattern:

// index.ts - export only public API
export { QualitiesCard } from "./QualitiesCard";
export { QualityModal } from "./QualityModal"; // 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

---

Creation Component Subfolders

Current organization (15 directories, 89 total components):

Folder	Components	Pattern
/armor	4	Panel + Row + PurchaseModal + ModModal
/augmentations	4	4 specialized modals
/contacts	2	Card + Modal + support files
/foci	2	Card + Modal
/gear	4	Panel + Row + 2 Modals
/identities	6	Card + 3 modal types
/knowledge-languages	5	Card + 2 Row types + 2 Modals
/magic-path	2	Card + Modal + utilities
/matrix-gear	3	Card + 2 specialized modals
/metatype	2	Card + Modal + support files
/qualities	3	Card + SelectionModal + DetailCard
/shared	10	Reusable utilities and hooks
/skills	5	5 specialized modals
/vehicles	4	4 specialized modals
/weapons	4	Row + 3 Modals

---

Adding a New Character Creation Card

1. Determine if card needs subfolder (see decision flowchart above)

   • Has modals? → Create subfolder with index.ts
   • Simple with internal helpers? → Single file is fine

2. Create card component in /components/creation/ or /components/creation/{feature}/

3. Follow the CreationCard wrapper pattern from /components/creation/shared/

4. Add to SheetCreationLayout.tsx in the appropriate column

5. Update CreationState type in /lib/types/creation.ts if needed

6. Export from /components/creation/index.ts

---

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/creation/shared/CreationCard.tsx - Card wrapper pattern
• components/creation/SkillsCard.tsx - Modal-based editing example
• components/creation/AugmentationsCard.tsx - Category tabs + list
• app/characters/create/sheet/components/SheetCreationLayout.tsx - Three-column layout