04-code-organization/01-components.md

Components

Components are reusable UI units.

In Vroq apps, a component should usually focus on presentation, local UI behavior, and composition. A component may use local state, but it should usually avoid owning feature-wide store behavior.

When to create a component

Create a component when:

the logic is mostly UI composition
the unit can reasonably be reused
props are enough to describe the behavior
local state is sufficient
the code would otherwise duplicate presentation logic

Examples:

card renderer
toolbar
input wrapper
status badge
small collapsible panel with local open state

What a component should do

A good component should usually:

receive data through props
receive callbacks through props
use local state only for local UI concerns
stay usable in more than one place when practical
make its UI purpose obvious from its name

What a component should usually avoid

A component should usually avoid:

direct knowledge of feature store shape
dispatching app actions unless clearly justified
raw API calls
mixing presentation and feature orchestration

If store orchestration is central to the code, it is usually a section, not a component.

Naming

Component names should describe their UI role.

Examples:

FileCard
EditorToolbar
StatusBadge

Final rule

Use a component when the code is primarily reusable UI with props and local state, not feature-owned store behavior.