docs: add comprehensive Mix 2.0 generator pattern catalog #808
Conversation
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
Document all repetitive patterns identified in Spec, Styler, and MutableStyler classes for the new generator architecture: - Spec patterns: copyWith, lerp, debugFillProperties, props - Styler patterns: dual constructors, resolve, merge, mixins - MutableStyler patterns: utility initialization, convenience accessors - Mix type patterns: sealed classes, subclass structure Includes complete mapping tables: - Type → Lerp strategy (MixOps.lerp vs MixOps.lerpSnap) - Type → Prop wrapper (Prop.maybe vs Prop.maybeMix) - Type → Utility class - Type → DiagnosticsProperty Proposes new generator architecture with: - Metadata extraction layer - Type resolution utilities - Spec/Styler/MutableStyler builders Phase 1 of the mix_generator rewrite.
Transform the pattern catalog into a self-contained agent context document that can be provided to an AI agent to execute the generator rewrite. Includes: - Agent system prompt with capabilities and mindset - Detailed task description with goals and approach - Execution guidelines with phase-by-phase instructions - Acceptance criteria with checkboxes - Validation approach with golden file testing strategy - Key decision points for type resolution - Codebase navigation table - Important constraints The pattern catalog reference remains unchanged below the agent context. This document is now ready to hand off to an AI agent for implementation.
Address review findings that would cause generator implementation to fail: C1: Document @MixableField annotation capabilities and gaps C2: Add FlagProperty ifTrue resolution with curated map of all values C3: CORRECT list merge semantics (Prop<List<T>> uses merge, not mergeList) C4: Add explicit mixin mapping table for all 8 stylers C5: Add source order preservation strategy using nameOffset C6: Add reliable lerp strategy detection with explicit type lists C7: Document import/part emission rules for .g.dart files C8: Add typedef and static chain generation rules C9: Add curated utility accessor mapping for MutableStylers Answer all review questions with specific decisions. These corrections are critical for achieving exact-match generated output.
Address additional review feedback with 6 new clarifications:
C10: Utility callback pattern decision rule
- When to use specialized utility with Prop.mix vs MixUtility
- Complete type → pattern mapping table
C11: Edge cases consolidation
- All known edge cases in one place
- textDirectives, shadows vs boxShadow, nested specs, etc.
C12: Error handling strategy
- Fail-fast with actionable messages
- Fallback behaviors for unknown types
C13: Testing normalization rules
- dart format both sides
- Strip headers, normalize newlines
- Example test structure
C14: Phase dependencies (explicit)
- Visual dependency graph
- Clarified START HERE entry point
C15: code_builder vs string templates
- Allow string templates for simple patterns
- code_builder for complex class structures
Also:
- Updated constraint #4 to reflect flexible code emission approach
- Added Q6 confirming NO backward compatibility required
Major architectural additions based on code generation expert review: Phase 0: Emission Strategy Decision - Decided: generate entire classes into .g.dart parts - Hand-written files become golden references only - Stub + generated part structure defined Phase 1: Registries + Metadata Planning (REWRITTEN) - CRITICAL FIX: StylerPlan/MutablePlan are DERIVED from Spec - NOT extractors from existing Styler classes (circular dependency) - Added MixTypeRegistry and UtilityRegistry - Added FieldModel with computed effective values Pattern Additions: - Section 2.8: Styler debugFillProperties pattern - Always uses DiagnosticsProperty (not type-specific) - Uses $-prefixed field names - Base fields NOT included - Section 2.9: Styler props pattern New Corrections: - C16: isLerpable:false semantics clarified with fixture - C17: Compile-level integration test requirement - C14: Updated phase dependencies to include Phase 0 These changes address the "biggest gaps" identified in expert review: 1. How to legally generate class bodies in Dart 2. Where metadata comes from (Spec, not Styler) 3. Registry vs string heuristics for type mapping
Critical fixes based on expert feedback: Phase 0: Emission Strategy (COMPLETE REWRITE) - Replaced extension/augmentation approach with mixin-based Spec generation - Extensions cannot satisfy required overrides (copyWith, lerp, etc.) - Augmentations not shipped in Dart 3.10 - too risky for production - New approach: generate _$SpecMethods mixin into .g.dart - Added file topology & builder outputs subsection - Single .g.dart per Spec containing mixin + Styler + MutableStyler Consistency fixes: - Removed all stale StylerMetadata "extractor" references - All plans are now DERIVED from Spec + registries, not extracted - Updated START HERE section to reflect derived plan approach - Updated C14 phase dependencies for new architecture New corrections added: - C18: Field rename/alias handling (textDirectives → directives) - C19: Styler props base-fields rule (excludes $animation, etc.) - C20: Registry discovery + caching (curated maps recommended) - C21: Unknown type fallback behavior (explicit fallbacks + warnings) - C22: Composite spec generation rules (FlexBox/StackBox) - C23: Curated maps consolidation (single core/curated/ directory) Updated sections: - Section 1.1: Class structure shows stub + generated mixin pattern - Section 2.9: Explicit CONFIRMED RULE for props exclusions - Section 6.1: Directory structure with curated/ and plans/ directories - Section 6.2: Plan classes (FieldModel, StylerPlan, MutablePlan) - Section 6.4: Builder classes (SpecMixinBuilder, StylerBuilder) - Section 7: Implementation plan aligned with new architecture
Contributor
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
To view this pull requests documentation preview, visit the following URL: Documentation is deployed and generated using docs.page. |
Fixes based on expert agent review: 1. Constraints clarification (feedback #2): - Updated constraint #1 to explain hand-written files serve two roles - Current: golden references; Future: stubs with part/with boilerplate - Clarified "do not modify" means patterns/logic, not boilerplate 2. Directory structure consistency (feedback #3): - Phase 1 now shows plans/ directory (not metadata/) - Renamed section to "Registries + Derived Plans Layer" 3. UtilityCallbackKind enum (feedback #7): - Added enum with propMix, propDirect, methodTearOff - Updated UtilityRegistry to use (String, UtilityCallbackKind) tuples - Updated C10 with three distinct patterns - Updated C20 curated map example with enum values - ColorUtility explicitly marked as propDirect (not propMix) 4. Golden test examples (feedback #9): - Updated VALIDATION APPROACH section to use expected fixtures - Updated C13 test example to compare with .g.dart fixtures - All examples now use test/golden/expected/*.g.dart pattern 5. textDirectives fixture test (feedback #10): - Added comprehensive fixture test example to C11 - Shows stub input, expected behaviors, test assertions - Covers: raw List (no Prop), mergeList, pass-through resolve, alias
Addresses all remaining issues from expert review: A. Plan text fixes: - A1: Fixed C1 isLerpable to use MixOps.lerpSnap (matches C16) - A2: Replaced Key Decision Points with registry-based lookups - A3: Renamed Phase 3 to Spec Mixin Builder with correct file path - A4: Standardized mixin naming to _$XSpecMethods throughout - A5: Added migration notes for Styler/MutableStyler stubs B. Build_runner wiring: - B1-B2: Added complete build.yaml with SharedPartBuilder + generate_for - B3: Added stub validation warning for missing part directives C. Import management: - C1-C3: Added Import Closure section explaining stub import requirements D. FieldModel improvements: - D1: Added methodName to UtilityRegistry for methodTearOff pattern - D2: Clarified alias applies to copyWith, diagnostics, and setter names E. Lerp consistency: - E1: Added locked nested spec lerp rule (a?.lerp(b, t) ?? b) F. Mixin constraint: - F1: Added Diagnosticable to mixin on-clause G. Code style: - G1: Explicit decision that generated code has no doc comments H. Testing: - H1: Fixed compile test to create both stub and part files I. Generator pipeline: - I1: Added Generator Orchestration section with full MixGenerator example
Fixes remaining issues from expert verification: Blocker 1.3: ListMix mapping key strategy - Clarified listMixTypes uses element type as key (e.g., "Shadow" not "List<Shadow>") - Added list handling logic steps for detection and lookup Blocker 5.1: Deprecated 'on' utility - Explicitly de-scoped deprecated 'on' property in MutableStyler (YAGNI) - Added "Explicitly NOT generated" section to Phase 5 Setter generation rule: - Added explicit rule for Phase 4: generate setter for every public constructor field - Setter name uses aliased stylerPublicName - No exceptions for raw list fields Fail-fast validations: - Added comprehensive table of generator error checks - Covers: missing part directive, missing mixins, unknown types, missing aliases - Actionable error messages help developers fix issues at build time
Major corrections from detailed codebase verification: C19 FIX - Styler props base fields: - WRONG: Plan said base fields NOT included in props - CORRECT: BoxStyler.props DOES include $animation, $modifier, $variants - Updated Section 2.9, C19, and Phase 4 Task 8 C10 FIX - Utility callback patterns: - Added Pattern D: convenienceAccessor for delegated utilities - BoxMutableStyler.color is decoration.box.color, NOT direct ColorUtility - IconMutableStyler.color DOES use propDirect pattern correctly - Updated enum to include convenienceAccessor Composite Specs (C22): - CRITICAL: FlexBoxSpec fields are StyleSpec<BoxSpec>, NOT BoxSpec directly - Updated lerp pattern to show StyleSpec.lerp usage - Updated curated composite mapping with correct field types - Fixed E1 to show two patterns: StyleSpec<T> vs direct Spec IconStyler shadows pattern: - Added detailed example of Prop.mix(ShadowListMix(...)) pattern - Shows full constructor transformation for List<TMix> types New additions: - Phase 4 Task 9: call() method for widget-creating Stylers - Mixin generic parameter table with exact type params for each mixin - Extended diagnostic property table with 13 additional types - Clarified abstract getter semantics in generated mixins
github-actions
bot
added
documentation
Investigation of actual codebase reveals the simplification proposal is based on incorrect assumptions: DEPRECATED (confirmed): - `on` utility in MutableStylers → replaced by direct methods like $box.onHovered() - Legacy widget constructors → replaced by new constructors NOT DEPRECATED (must generate): - MutableStyler classes themselves → BoxStyler.chain returns BoxMutableStyler - MutableState classes → required for mutable state management - Utility patterns (propMix, propDirect, methodTearOff, convenienceAccessor) - StyleMutableBuilder base class - UtilityRegistry and all resolvers Evidence: - BoxStyler.chain (line 112) actively returns BoxMutableStyler - StyleMutableBuilder exists at core/spec_utility.dart:54 - All *_mutable_style.dart files are active (10+ references each) - Only the `on` utility has @deprecated annotation Added: - Deprecation Scope section to KEY DECISION POINTS - Clarification in Phase 5 about what IS vs ISN'T deprecated
- Update Deprecation Scope section with full list of deprecated items - Add commit reference for traceability - Update Section 3.4 with both .on and .wrap deprecation patterns - Add migration examples for deprecated patterns - Clarify generator impact: continue generating MutableStyler/Styler classes
github-actions
bot
removed
documentation
Addresses validated blockers from expert review: 1. build.yaml configuration (BLOCKER-2): - Updated to match actual codebase: PartBuilder with .g.dart - Fixed builder name, import path, and extensions - Added note about current vs future architecture 2. Generator orchestration section: - Changed from SharedPartBuilder to PartBuilder - Updated entry point path to mix_generator.dart - Added formatOutput with DartFormatter 3. Phase 4 Styler Builder tasks: - Added task 10: Generate static chain accessor - Added chain accessor pattern documentation - Added consistency note: StackStyler missing chain 4. Golden test fixtures: - Added setup instructions (mkdir command) - Added minimal fixture example for box_spec_input.dart - Clarified directory does not exist yet False positives resolved: - BLOCKER-1 (MutableStyler scope) - NOT a blocker, plan is correct - BLOCKER-4 (chain accessor) - NOT a blocker, works with MutableStyler
Updates the implementation plan to focus initial scope on: - Phase 1-4: Spec mixin + Styler generation - Phase 6: Testing infrastructure MutableStyler generation (Phase 5) is deferred: - MutableStyler classes remain hand-written for initial release - Styler.chain accessor remains hand-written - UtilityRegistry/UtilityResolver moved to Phase 5 - MutablePlan creation moved to Phase 5 Changes made: - Phase 4: Removed chain accessor task (depends on MutableStyler) - Phase 5: Marked as DEFERRED with clear rationale - Acceptance criteria: Marked MutableStyler criteria as deferred - Generator orchestration: Removed MutableStyler generation code - Phase dependency diagram: Updated to show deferred scope - Implementation plan summary: Clarified initial vs deferred scope
- Remove UtilityRegistry/MutablePlan from Phase 1 (deferred to Phase 5) - Note UtilityResolver deferral in Phase 2 - Fix E1 lerp pattern (remove ?? fallback to match FlexBoxSpec) - Fix build.yaml: .mix.dart → .g.dart extension - Narrow build.yaml generate_for to lib/src/specs/**/*.dart - Remove non-existent ColorMix from mixTypeMap
- Update mission statement to Spec + Styler only - Remove MutableStyler from generator objectives - Mark MutableStyler generation as DEFERRED to Phase 5 - Update file topology to show Styler-only generation - Add deferral notes to C9, C10, C22 sections - Mark UtilityRegistry, MutablePlan, UtilityResolver as Phase 5 - Update directory structure with deferral annotations - Clarify initial scope: Phases 1-4 + 6, not Phase 5 MutableStyler classes remain hand-written for initial release.
Complete removal of deferred MutableStyler content: Removed entirely: - Phase 5 (MutableStyler Builder) section - Section 3: MutableStyler Patterns (130+ lines) - C9 (Utility Accessor Mapping) and C10 (Utility Callback Patterns) - MutablePlan, UtilityRegistry, UtilityResolver, MutableStylerBuilder - MutableStyler Files Analyzed section - Static chain accessor pattern Cleaned up: - Renumbered C11-C23 to C9-C21 - Renumbered Section 4-8 to Section 3-7 - Renumbered Phase 6 to Phase 5 - Updated phase diagram - Removed deferred notes throughout - Cleaned directory structure - Updated FieldModel (removed mutableUtilityName, effectiveUtility, etc.) Generator now produces only: - _$XSpecMethods mixin - typedef alias - Full Styler class
Adds comprehensive reference documentation for future MutableStyler generation implementation: - A.1: What remains hand-written (file patterns, reference files) - A.2: MutableStyler class structure pattern - A.3: Utility patterns (propMix, propDirect, methodTearOff, convenienceAccessor) - A.4: Convenience accessor mapping table - A.5: Type → Utility mapping table - A.6: Removed architecture components (files, plan classes) - A.7: Static chain accessor pattern - A.8: Deprecated patterns (DO NOT generate) - A.9: Composite MutableStyler patterns (FlexBox, StackBox) This preserves all the MutableStyler patterns that were removed from the main plan, serving as a reference for future implementation.
Corrected C# references that pointed to old section numbers after MutableStyler content removal and renumbering: - C19 → C17 (props base-fields rule, 2 occurrences) - C15 → C13 (code_builder vs String Templates) - C18 → C16 (field rename/alias handling) - Phase 6 → Phase 5 (testing phase reference)
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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.
Document all repetitive patterns identified in Spec, Styler, and
MutableStyler classes for the new generator architecture:
Includes complete mapping tables:
Proposes new generator architecture with:
Phase 1 of the mix_generator rewrite.