summercms-initial-research/.planning/phases/03-component-system/03-CONTEXT.md

Phase 3: Component System - Context

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

## 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.

## 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

## 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

## Deferred Ideas

None — discussion stayed within phase scope

---

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