# Phase 3: Component System - Context

**Gathered:** 2026-02-04
**Status:** Ready for planning

<domain>
## Phase Boundary

Enable reusable UI components that respond to HTMX interactions. Developers define components with YAML properties, components render via templates, and HTMX handlers respond to client-side triggers. This phase delivers the component infrastructure — CMS page editing UI that uses components is Phase 9.

</domain>

<decisions>
## Implementation Decisions

### Component definition
- YAML with explicit types: `name: {type: string, default: 'Default', required: true}`
- Full widget set for property types: string, number, boolean, dropdown, model binding, repeater, file picker, color picker, code editor
- Validation rules in YAML for simple cases (required, min, max, pattern), complex validation delegates to Scala functions
- Components registered per-plugin similar to WinterCMS (`registerComponents` → component bound to default alias usable in theme)
- Support inheritance — components can extend base component and override lifecycle methods
- Missing required properties = compile-time error (page won't render)
- No component versioning — breaking changes are plugin version bumps

### Rendering & output
- Template files, not ScalaTags DSL
- Twig-compatible template language (similar syntax to WinterCMS for easier migration)
- Every component requires `default.htm` — CLI scaffolding auto-generates it
- Theme context access: template helpers (`{{ asset('img/logo.png') }}`) AND ThemeService injection for Scala code

### HTMX behavior
- Handler naming convention: methods starting with `on` become handlers (`onRefresh`, `onLoadMore`)
- Handlers return `ZIO[Env, Error, Html]` for async operations
- CSRF protection always required on all HTMX requests
- Error presentation: both HTML fragment swap AND toast/notification via HX-Trigger, configurable per component or globally
- Loading states via standard HTMX indicators (`htmx-indicator` class, theme provides CSS)
- SSE support for real-time updates — components can push updates via Server-Sent Events

### Inspector/preview
- No dedicated component preview/playground
- CLI command for documentation: `summer docs:components` generates markdown from YAML
- Full property inspector in CMS page editor (click component to edit properties in sidebar) — UI built in Phase 9
- Basic metadata like WinterCMS: name, description, icon in YAML

### Claude's Discretion
- Dependency injection approach — pick pattern that fits ZIO idioms best, document clearly
- HTMX response headers (retarget, trigger) — pick idiomatic ZIO approach
- Handler routing URL structure — integrate well with ZIO HTTP

</decisions>

<specifics>
## Specific Ideas

- Component registration pattern from WinterCMS: `registerComponents` method in plugin returns map of component class → default alias
- Twig-compatible templating eases migration from WinterCMS themes
- Similar metadata structure to OctoberCMS/WinterCMS components

</specifics>

<deferred>
## Deferred Ideas

None — discussion stayed within phase scope

</deferred>

---

*Phase: 03-component-system*
*Context gathered: 2026-02-04*