docs: Add comprehensive fragment rendering specification#36
Open
docs: Add comprehensive fragment rendering specification#36
Conversation
Add detailed specification for implementing fragment rendering feature, which enables multiple ViewContext implementations per ViewComponent with type-based conditional rendering in templates. Key features: - Multiple ViewContext types in single ViewComponent - Type-safe fragment selection via view:context attribute - Support for Thymeleaf, JTE, and KTE template engines - Backward compatible with existing code Includes: - Full technical specification (fragment-rendering-spec.md) - Example implementations (ButtonComponent, AlertComponent) - Usage examples and controller integration - Migration guide and best practices - Implementation roadmap This addresses the need for reduced code duplication when creating component variants (e.g., primary/secondary/danger buttons) while maintaining compile-time type safety.
Major updates based on design discussions: **Core Changes:** - Remove view:context-root requirement (unnecessary boilerplate) - Introduce presence-based rendering (no attribute = always render) - Add MultiViewContext pattern for flexible composition - Same-component requirement for ViewContexts in MultiViewContext - Runtime validation only (no template scanning/compile-time) **Two Complementary Patterns:** 1. Type-Based Variants - One ViewContext, one fragment renders (e.g., ButtonComponent with Primary/Secondary/Danger variants) 2. MultiViewContext Composition - Multiple ViewContexts, multiple fragments (e.g., PageComponent with optional Header/Content/Footer sections) **Key Features:** - Framework-provided MultiViewContext class (zero boilerplate) - Automatic null filtering for conditional composition - Sealed interfaces pattern for shared properties - thymeVar comment conventions for IDE autocomplete - Clear error messages with actionable guidance - Works with all template engines (Thymeleaf, JTE, KTE) **Technical Design:** - Updated ViewContextMethodReturnValueHandler for MultiViewContext - New ThymeleafViewContextFragmentProcessor for view:context attribute - Fragment rendering rules (presence-based, multiple fragments) - Performance considerations and validation strategy **Examples Added:** - Button variants (type-based selection) - Page layouts with optional sections (MultiViewContext) - Alert component with sealed interfaces - Dashboard with conditional sections - Layout variants (admin/user/guest) **Implementation Plan:** - Phase 1: Core Infrastructure (v0.10.0) - Phase 2: Documentation & Examples (v0.10.0) - Phase 3: IDE Tooling (v0.11.0+) **Alternatives Documented:** - view:context-root (rejected - unnecessary) - String-based selection (rejected - no type safety) - Cross-component ViewContexts (rejected - use nested components) - Compile-time validation (deferred - complexity not justified) - Template scanning (rejected - runtime validation sufficient) This version reflects the consensus on keeping the implementation simple while maximizing developer experience and type safety.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Add detailed specification for implementing fragment rendering feature,
which enables multiple ViewContext implementations per ViewComponent with
type-based conditional rendering in templates.
Key features:
Includes:
This addresses the need for reduced code duplication when creating
component variants (e.g., primary/secondary/danger buttons) while
maintaining compile-time type safety.