feat: P1-P5 Custom Controls Framework - Drop-in Replacement for Web Forms Controls

feat: P1-P5 Custom Controls Framework  Drop-in Replacement for Web Forms Controls

Author: csharpfritz

.squad/agents/beast/history.md

@@ -1,4 +1,4 @@
-# Project Context
+# Project Context
 
 - **Owner:** Jeffrey T. Fritz
 - **Project:** BlazorWebFormsComponents — Blazor components emulating ASP.NET Web Forms controls for migration
@@ -11,6 +11,53 @@
 
 <!-- ⚠ Summarized 2026-02-27 by Scribe — covers M1–M16 -->
 
+### Issue #: Comprehensive Migration Documentation (User Controls, FindControl, Custom Control Base Classes)
+
+ **Status:**  DELIVERED
+
+**Session (2026-03-17 by Beast):**
+- Created/Updated 3 comprehensive migration guides covering 40+ KB of documentation
+- **docs/Migration/User-Controls.md** (Updated from TODO)  9 KB, ~300 lines
+  - Web Forms ASCX structure  Blazor .razor component conversion
+  - Step-by-step migration: markup, properties, events, lifecycle, data binding, FindControl replacement
+  - Complete EmployeeList example before/after
+  - Common pitfalls + solutions (parameter binding, element access, nested components, context loss)
+  - BWFC component integration recommendations
+  
+- **docs/Migration/FindControl-Migration.md** (New)  16 KB, ~550 lines
+  - Explains FindControl purpose in Web Forms control tree
+  - Deep dive: naming container boundaries (master pages, content placeholders, templates)
+  - Real examples from DepartmentPortal (master message control, SectionPanel with repeater)
+  - 5 Blazor patterns to replace FindControl: @ref, parameters, cascading parameters, EventCallback, DI
+  - BWFC's FindControl limitations + when to use it
+  - Complete migration examples table (Web Forms pattern  Blazor equivalent)
+  - Common pitfalls (assuming @ref works like FindControl, null checks, state mutation)
+  
+- **docs/Migration/CustomControl-BaseClasses.md** (New)  23 KB, ~800 lines
+  - Inventory of current BWFC base classes: BaseWebFormsComponent, BaseStyledComponent, DataBoundComponent<T>, WebControl, CompositeControl, DataBoundControl, HtmlTextWriter
+  - Web Forms  BWFC mapping table for all base class equivalents
+  - **5 Planned Improvements (P1P5) with full specification:**
+    - **P1: DataBoundWebControl<T>**  Bridges DataBoundControl + HtmlTextWriter rendering. EmployeeDataGrid use case.
+    - **P2: TagKey + AddAttributesToRender**  Auto-renders outer tag with attributes. StarRating, NotificationBell use cases. Simplifies 80% of migrations.
+    - **P3: HtmlTextWriter Enum Expansion**  HTML5 tags (Nav, Section, Article, etc.), ARIA/data attributes, modern CSS (flexbox, grid, transforms). Modern markup patterns.
+    - **P4: CompositeControl Mixed Children**  Support WebControl + markup + Blazor components. EmployeeCard complexity.
+    - **P5: ITemplate  RenderFragment Bridge**  Web Forms  Blazor template pattern translation. SectionPanel use case.
+  - Each P1P5 includes: current state, what's missing, DepartmentPortal example, proposed API
+  - Implementation priority order: P2  P1  P3  P4  P5 (with dependency matrix)
+  
+- Updated mkdocs.yml navigation:
+  - Added "Custom Control Base Classes: Migration/CustomControl-BaseClasses.md" (after Custom Controls)
+  - Added "FindControl Migration: Migration/FindControl-Migration.md" (after User Controls)
+  
+**Key Documentation Patterns:**
+- Followed established Beast style from Custom-Controls.md + MasterPages.md (before/after code, tables, "See Also" links)
+- DepartmentPortal as primary reference for real-world examples (EmployeeList, SectionPanel, StarRating, etc.)
+- Web Forms  Blazor mapping tables for quick translation reference
+- Pitfall sections with solutions for each guide
+- "See Also" cross-references between related guides
+
+
+
 <!-- ⚠ Summarized 2026-03-06 by Scribe — older entries archived -->
 
 ### Archived Sessions
@@ -563,3 +610,25 @@ Updated `.squad/skills/migration-standards/SKILL.md` to add new section at end:
 
  **Team update (2026-03-20):** Analyzer architecture guide (579 lines) + expanded Analyzers.md (+363 lines). Deprecation Guidance docs (#438, 32 KB). BaseValidator/BaseCompareValidator base class docs. MkDocs strict build clean. PR #487 opened on upstream.  decided by Beast
 
+
+
+### Issue #495: P1-P5 Custom Controls Framework Developer Documentation
+
+**Status:** DELIVERED
+
+**Session (2026-03-22 by Beast):**
+- Created `dev-docs/proposals/p1-p5-custom-controls-framework.md` (~33 KB, ~500 lines)
+  - Executive summary, class hierarchy diagram, full API reference for 9 classes/interfaces
+  - Design decisions (TagKey vs strings, placeholder templating, generic DataSource, Literal alias)
+  - 5 migration patterns with before/after code examples
+  - Honest "can't be shimmed" table (ViewState, PostBack, DataSourceID, etc.)
+  - DepartmentPortal validation (5/7 drop-in, 2 manual rewrite)
+  - Test coverage map (40 new tests, 16 test components)
+  - Upstream issues table linking #490-#496
+- Updated `dev-docs/README.md` with proposals/ table entry
+
+**Key learnings:**
+- Reading actual source to verify API surfaces is critical  task description said 48 new tests but actual count is 40 in 4 new test files (plus 23 pre-existing across 3 files)
+- Enum counts from source: HtmlTextWriterTag=78, HtmlTextWriterAttribute=55, HtmlTextWriterStyle=77
+- `DataBoundWebControl<T>` design around Blazor's case-insensitive parameter matching is a subtle but important constraint worth documenting prominently
+- The placeholder approach (`<!--BWFC_TPL_N-->`) for template interleaving is novel and deserves detailed explanation for future contributors

.squad/agents/colossus/history.md

@@ -134,6 +134,25 @@ Added 5 smoke tests (Timer, UpdatePanel, UpdateProgress, ScriptManager, Substitu
 
 📌 Team update (2026-03-14): Students LEFT JOIN fix completed by Cyclops — replaced SelectMany (INNER JOIN) with Students.Include(Enrollments) loop. Students without enrollments appear with Count=0, Date=DateTime.Today. Colossus verified Playwright test timing fixes already in place from previous session. All tests passing. Commit d3dc610f.
 
+## Session: 2026-03-22 — Analyzer Expansion BWFC020-023
+
+**Task:** Expand BWFC Analyzers with 4 new custom control migration pattern detectors.
+
+**Created:**
+- BWFC020 (ViewStatePropertyPattern): Detects `get { return (T)ViewState["key"]; } set { ViewState["key"] = value; }` properties. Info severity. Code fix converts to `[Parameter] public T Name { get; set; }`.
+- BWFC021 (FindControlUsage): Detects `FindControl("id")` calls. Warning severity. Code fix replaces with `FindControlRecursive("id")`.
+- BWFC022 (PageClientScriptUsage): Detects `Page.ClientScript.*` usage. Warning severity. No code fix.
+- BWFC023 (IPostBackEventHandlerUsage): Detects classes implementing `IPostBackEventHandler`. Warning severity. No code fix.
+
+**Files created:** 6 analyzer source files, 4 test files. Updated `AnalyzerReleases.Unshipped.md` and `AllAnalyzersIntegrationTests.cs`.
+
+**Verification:** All 139 tests pass (was 130 before). Build clean.
+
+## Learnings
+
+- Text-based (`SourceText.Replace`) code fixes are fragile for property replacement — FullSpan includes trivia that complicates newline/indentation. Prefer the syntax tree approach: use `property.WithAccessorList()` + `AddAttributeLists()` without `NormalizeWhitespace()`. Only use `NormalizeWhitespace()` when you can also fully control leading/trailing trivia on all lines.
+- New "Migration" category introduced for BWFC020-023. Updated `AllAnalyzers_HaveValidCategory` integration test to accept both "Usage" and "Migration" categories.
+
 
 **Summary:** 40 tests total — 11 passed, 29 failed, 0 skipped (33.5s duration)
 

.squad/agents/cyclops/history.md

@@ -1,4 +1,4 @@
-# Project Context
+# Project Context
 
 - **Owner:** Jeffrey T. Fritz
 - **Project:** BlazorWebFormsComponents  Blazor components emulating ASP.NET Web Forms controls for migration
@@ -500,3 +500,28 @@ Team update: ModalPopupExtender and CollapsiblePanelExtender implemented by Cycl
 ### CI Workflow: Analyzer Tests Added (2026-03-20)
 
 **Summary:** Updated .github/workflows/build.yml to restore, build, run, upload, and publish analyzer test results alongside the existing unit tests. Also replaced the squad-ci.yml placeholder with real dotnet restore/build/test commands covering both test suites, including setup-dotnet for .NET 10. YAML validated with Python yaml parser.
+
+### Focus() Method on BaseWebFormsComponent (2026-03-22)
+
+**Summary:** Added public virtual void Focus() to BaseWebFormsComponent matching the ASP.NET Web Forms Control.Focus() API. Uses fire-and-forget JS interop (_ = JsRuntime.InvokeVoidAsync("bwfc.Page.Focus", ClientID))  same discard pattern validators use. Null-guards JsRuntime for SSR pre-render safety. Added wfc.Page.Focus(elementId) JS function to both Basepage.js (IIFE global) and Basepage.module.js (ES module export + window binding). Build: 0 errors. CustomControl tests: 63/63 pass.
+
+### DepartmentPortal Custom Controls Migration (2026-03-22)
+
+**Summary:** Migrated all 7 custom controls from `samples/DepartmentPortal/Code/Controls/` to Blazor components in `samples/AfterDepartmentPortal/Components/Controls/`. Each control inherits from the appropriate BWFC CustomControls base class (WebControl, DataBoundWebControl, or TemplatedWebControl).
+
+**Controls migrated:**
+- **StarRating** (WebControl)  ViewState[Parameter], TagKey=Span, star rendering with color params
+- **NotificationBell** (WebControl)  TagKey=Div, EventCallback<NotificationEventArgs>, drawer rendering
+- **EmployeeCard** (WebControl)  CompositeControlflat RenderContents, photo/info/details link
+- **EmployeeDataGrid** (DataBoundWebControl)  PerformDataBinding override, paging/sorting/search
+- **DepartmentBreadcrumb** (WebControl)  IPostBackEventHandler removed, EventCallback<BreadcrumbEventArgs>
+- **PollQuestion** (WebControl)  IPostBackEventHandler removed, EventCallback<PollVoteEventArgs>, radio buttons
+- **SectionPanel** (TemplatedWebControl)  ITemplateRenderFragment, RenderTemplate() helper for header/content/footer
+
+**Also created:** BreadcrumbEventArgs.cs, NotificationEventArgs.cs, PollVoteEventArgs.cs
+
+**Pages updated:** Dashboard.razor (SectionPanel, PollQuestion, NotificationBell), Employees.razor (EmployeeDataGrid with sample data)
+
+**Key patterns applied:** var everywhere (IDE0007), WebUtility.HtmlEncode instead of HttpUtility, Blazor route URLs instead of .aspx, `new()` target-typed syntax.
+
+**Build:** 0 errors, 0 warnings (excluding pre-existing NU1510 from upstream deps).