advanced-calculator/docs/migration-plan.md

Advanced Calculator Migration Plan

Migration target: .NET 4.7 WPF (src.4.7) → Avalonia on .NET 8 (src) with Desktop, Android, and Browser heads.

Objectives

• Preserve existing features and UX while adopting MVVM and cross‑platform patterns.
• Encapsulate the expression engine behind a service to isolate API differences.
• Maintain a single shared UI project for all heads; avoid platform‑specific code.

Repo Overview

• New solution (src):
  • AdvancedCalculator (shared UI, Avalonia 11, net8.0)
  • Heads: AdvancedCalculator.Desktop (net8.0), AdvancedCalculator.Android (net8.0-android), AdvancedCalculator.Browser (net8.0-browser)
  • Uses CommunityToolkit.Mvvm and already references CSMic.StandardLibrary.
• Old project (src.4.7):
  • WPF MainWindow with variables, function definitions panel, history, and input with Enter submit.
  • Icons via Material Design Icons TTF + IconFont.cs glyph map.
  • Models: HistoryItem, VariableItem, FunctionDefinitonItem.
  • Interpreter: csmic.InputInterpreter in code-behind.

High-Level Approach

1. Port models and static data to the shared project.
2. Wrap the interpreter in a service (ICalculatorService) that maintains state and exposes async APIs.
3. Move UI logic from code-behind to MainViewModel using commands and observable collections.
4. Recreate the WPF layout in Avalonia XAML (MainView.axaml), preserving behavior and styling.
5. Migrate icons/assets and wire up font usage across platforms.
6. Polish interactions (auto-scroll, focus, virtualization) and verify cross‑platform.

Mapping WPF → Avalonia

• Events → Commands:
  • txtInput_KeyDown (Enter) → SubmitCommand with KeyBinding on the input TextBox.
  • btnFx_Click → ToggleFunctionsCommand.
• Collections:
  • List<T> → ObservableCollection<T> for History and Variables.
• Visibility:
  • WPF Visibility → bool properties (IsExpression, IsFunctionsPanelOpen) bound to IsVisible or via a simple BoolToGridLength/BoolToVisibility converter.
• Icons:
  • Keep IconFont glyphs and ship the TTF in Assets/Fonts, or reduce to the required subset.
• Scrolling:
  • Use ListBox/ListView and set selected index to last; optionally call ScrollIntoView from code-behind or via behavior.

Phased Plan

Phase 1: Models and Service

• Add Models in src/AdvancedCalculator:
  • HistoryItem.cs (copy shape from WPF)
  • VariableItem.cs (replace Visibility with bool IsExpression and string? ExpressionComputation)
  • FunctionDefinitionItem.cs (rename to fix spelling; copy DefinedFunctions static enumeration)
• Add Services:
  • ICalculatorService with methods like:
    • Task<InterpretResult> InterpretAsync(string input)
  • CalculatorService that holds a persistent interpreter instance from CSMic.StandardLibrary and returns:
    • Computed Output
    • Current variables (name, value, type)
    • For equation variables: compute and store ExpressionComputation

Notes:

• The service isolates any API delta between WPF’s csmic.InputInterpreter and the current CSMic.StandardLibrary.

Phase 2: ViewModel

• Expand MainViewModel:
  • Properties: InputText, IsFunctionsPanelOpen, ObservableCollection<HistoryItem> History, ObservableCollection<VariableItem> Variables.
  • Commands: SubmitCommand, ToggleFunctionsCommand using RelayCommand/AsyncRelayCommand.
  • On submit: call CalculatorService.InterpretAsync(InputText), append to History, rebuild Variables, clear InputText, and request UI scroll to last.

Phase 3: UI Layout

• Update Views/MainView.axaml to mirror WPF layout:
  • Grid with two columns; left hosts Variables (row 0) + Functions panel (row 1, height toggled), right hosts History (row 0) + input row (row 1).
  • Add GridSplitter between columns.
  • Bind ItemsSource for lists and set DataTemplates for item visuals (icon column + text stacks as in WPF XAML).
  • Input row: toggle Button bound to ToggleFunctionsCommand; TextBox bound to InputText with KeyBinding Enter → SubmitCommand.

Phase 4: Icons and Assets

• Copy materialdesignicons-webfont.ttf to src/AdvancedCalculator/Assets/Fonts.
• Update AdvancedCalculator.csproj to include the font as an AvaloniaResource.
• Reference the font in XAML via FontFamily="avares://AdvancedCalculator/Assets/Fonts#Material Design Icons".
• Optionally copy a slimmed IconFont.cs (only used glyphs) and bind TextBlock to those glyph strings.

Phase 5: Interaction Polish

• Auto-scroll History on submit (select last item or call ScrollIntoView in code-behind for MainView).
• Ensure lists use virtualization (default templates are virtualized; confirm template choice preserves it).
• Focus management: focus input TextBox after submit.

Phase 6: Cross-Platform Verification

• Desktop: smoke test.
• Browser: ensure font loads correctly as an Avalonia resource; verify icons render and inputs submit with Enter.
• Android: verify IME enter (Done/Go) triggers submit; confirm font packaged and renders.

Phase 7: Cleanup and Docs

• Remove placeholder greeting and unused templates.
• Update README.md with build/run instructions per target, plus basic usage.
• (Optional) Add a few unit tests for CalculatorService if practical without heavy harness.

File-Level Checklist

• Add:
  • src/AdvancedCalculator/Models/HistoryItem.cs
  • src/AdvancedCalculator/Models/VariableItem.cs
  • src/AdvancedCalculator/Models/FunctionDefinitionItem.cs
  • src/AdvancedCalculator/Services/ICalculatorService.cs
  • src/AdvancedCalculator/Services/CalculatorService.cs
  • src/AdvancedCalculator/Assets/Fonts/materialdesignicons-webfont.ttf
• Update:
  • src/AdvancedCalculator/AdvancedCalculator.csproj (Avalonia resources for Fonts)
  • src/AdvancedCalculator/ViewModels/MainViewModel.cs (properties + commands)
  • src/AdvancedCalculator/Views/MainView.axaml (+ optional code-behind for scroll/focus)

Risks & Mitigations

• Interpreter API changes: contained by CalculatorService; adjust adapter logic without touching UI.
• Font payload size (Browser, Android): if large, switch to a reduced subset or alternate icon source.
• Visibility semantics: prefer bool bindings to IsVisible to avoid platform enums.
• WebAssembly resource loading: verify avares:// URIs and that the font is included as a resource.

Acceptance Criteria

• Entering an expression appends to History and updates Variables.
• Variables defined as equations show computed ExpressionComputation and a distinct icon.
• Function definitions panel toggles and displays static help list.
• Icons render on Desktop and Browser; Android renders acceptable icons.
• Solution builds and runs across Desktop, Browser, and Android heads.

Timeline Estimate

• Phase 1–2 (Models, Service, VM): 0.5–1 day
• Phase 3 (UI layout and bindings): 1–1.5 days
• Phase 4–5 (Assets, polish): 0.5 day
• Phase 6 (Cross‑platform checks): 0.5–1 day
• Total: ~2.5–4 days including docs and smoke tests

Next Actions

1. Create Models and Services scaffolding in AdvancedCalculator and wire MainViewModel.
2. Port the XAML layout and data templates into MainView.axaml.
3. Add icon font resources and verify rendering on Desktop.
4. Smoke test on Browser and Android heads; adjust assets if needed.