From 63e334d92b5442775d152d9dfe640ea5b90744e0 Mon Sep 17 00:00:00 2001
From: Jakub Zych <jakub@keios.eu>
Date: Wed, 4 Feb 2026 15:38:45 +0100
Subject: [PATCH] docs(03): capture phase context

Phase 03: Component System
- Implementation decisions documented
- Phase boundary established
---
 .../phases/03-component-system/03-CONTEXT.md  | 71 +++++++++++++++++++
 1 file changed, 71 insertions(+)
 create mode 100644 .planning/phases/03-component-system/03-CONTEXT.md

diff --git a/.planning/phases/03-component-system/03-CONTEXT.md b/.planning/phases/03-component-system/03-CONTEXT.md
new file mode 100644
index 0000000..6b676fd
--- /dev/null
+++ b/.planning/phases/03-component-system/03-CONTEXT.md
@@ -0,0 +1,71 @@
+# 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*