Equation editor for Avalonia: MathEditBox, MathView, and their packages

.github/workflows/ci.yml

@@ -5,8 +5,6 @@ on:
     branches:
       - main
   pull_request:
-    branches:
-      - main
   workflow_dispatch:
 
 permissions:
@@ -23,8 +21,14 @@ env:
   DOTNET_SKIP_FIRST_TIME_EXPERIENCE: 'true'
   NUGET_PACKAGES: ${{ github.workspace }}/.nuget/packages
   SOLUTION: SharpEquations.slnx
-  LIBRARY_PROJECT: src/SharpEquations/SharpEquations.csproj
+  # the packages, all with the version of BuildVersion.props: the converter, and the equation editor on top of it
+  LIBRARY_PROJECTS: >-
+    src/SharpEquations/SharpEquations.csproj
+    src/SharpEquations.Editing/SharpEquations.Editing.csproj
+    src/SharpEquations.Rendering/SharpEquations.Rendering.csproj
+    src/SharpEquations.Avalonia/SharpEquations.Avalonia.csproj
   TEST_PROJECT: tests/SharpEquations.Tests/SharpEquations.Tests.csproj
+  EDITOR_TEST_PROJECT: tests/SharpEquations.Avalonia.Tests/SharpEquations.Avalonia.Tests.csproj
   FEED_URL: https://nuget.pkg.github.com/${{ github.repository_owner }}/index.json
 
 # Stages: Resolve Version -> Test (Linux, Windows, macOS) -> Pack NuGet
@@ -105,18 +109,21 @@ jobs:
             label: Linux x64
             os: ubuntu-latest
             tfms: net10.0 net8.0
+            editor_tfms: net10.0 net8.0
             dotnet: |
               8.0.x
               10.0.x
           - rid: win-x64
             label: Windows x64
             os: windows-latest
             tfms: net10.0 net481
+            editor_tfms: net10.0
             dotnet: 10.0.x
           - rid: osx-arm64
             label: macOS arm64
             os: macos-latest
             tfms: net10.0
+            editor_tfms: net10.0
             dotnet: 10.0.x
 
     steps:
@@ -152,6 +159,19 @@ jobs:
             echo "::endgroup::"
           done
 
+      # the equation editor (Avalonia 12 has no .NET Framework build: net10.0, and net8.0 where it is installed)
+      - name: Run editor tests
+        shell: bash
+        run: |
+          set -e
+          for TFM in ${{ matrix.editor_tfms }}; do
+            echo "::group::editor $TFM"
+            dotnet run --project "$EDITOR_TEST_PROJECT" -c Release -f "$TFM" --no-build -- \
+              --report-trx --report-trx-filename "${{ matrix.rid }}.editor.$TFM.trx" \
+              --results-directory "$GITHUB_WORKSPACE/TestResults"
+            echo "::endgroup::"
+          done
+
       - name: Upload test results
         if: always()
         uses: actions/upload-artifact@v7
@@ -201,11 +221,13 @@ jobs:
       # The .snupkg symbol package is written next to the .nupkg.
       - name: Pack
         run: |
-          dotnet pack "$LIBRARY_PROJECT" \
-            -c Release \
-            -o artifacts \
-            -p:VersionSuffix="$VERSION_SUFFIX" \
-            -p:ContinuousIntegrationBuild=true
+          for PROJECT in $LIBRARY_PROJECTS; do
+            dotnet pack "$PROJECT" \
+              -c Release \
+              -o artifacts \
+              -p:VersionSuffix="$VERSION_SUFFIX" \
+              -p:ContinuousIntegrationBuild=true
+          done
           ls -lh artifacts
 
       # nuget.org shows the README of the package: fail if it is missing or not declared.

.github/workflows/codeql.yml

@@ -8,8 +8,6 @@ on:
     branches:
       - main
   pull_request:
-    branches:
-      - main
   schedule:
     - cron: '27 4 * * 3'
   workflow_dispatch:

.github/workflows/demo.yml

@@ -0,0 +1,69 @@
+name: Web demo
+
+# The equation editor on WebAssembly (samples/SharpEquations.Avalonia.Browser.Demo): built on every pull request,
+# published to GitHub Pages from main, or from any branch when the workflow is run by hand (Settings → Pages → Source:
+# GitHub Actions; a branch other than main must be allowed in Settings → Environments → github-pages).
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: demo-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  DOTNET_NOLOGO: 'true'
+  DOTNET_CLI_TELEMETRY_OPTOUT: 'true'
+  DOTNET_SKIP_FIRST_TIME_EXPERIENCE: 'true'
+  PROJECT: samples/SharpEquations.Avalonia.Browser.Demo/SharpEquations.Avalonia.Browser.Demo.csproj
+
+jobs:
+  build:
+    name: Build the web demo
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+
+      - name: Setup .NET
+        uses: actions/setup-dotnet@v6
+        with:
+          dotnet-version: '10.0.x'
+
+      - name: Install the WebAssembly workload
+        run: dotnet workload install wasm-tools
+
+      - name: Publish
+        run: dotnet publish "$PROJECT" -c Release -o publish
+
+      # GitHub Pages serves the site from a folder: no Jekyll, and the index for any path that is not a file
+      - name: Prepare the site
+        run: |
+          touch publish/wwwroot/.nojekyll
+          cp publish/wwwroot/index.html publish/wwwroot/404.html
+
+      - uses: actions/upload-pages-artifact@v4
+        with:
+          path: publish/wwwroot
+
+  deploy:
+    name: Deploy to GitHub Pages
+    if: github.event_name == 'workflow_dispatch' || github.event_name == 'push' && github.ref == 'refs/heads/main'
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v5

.github/workflows/prerelease-cleanup.yml

@@ -5,8 +5,6 @@ name: PR Pre-release Cleanup
 on:
   pull_request:
     types: [closed]
-    branches:
-      - main
 
 permissions:
   contents: read

AGENTS.md

@@ -14,8 +14,14 @@ generated parser, on netstandard2.0): keep it so, and keep containers and other
 | `src/SharpEquations/` | The library: `Public/` (the public API), `Internal/` (one folder per format), `Resources/` (XSLT stylesheets) |
 | `src/SharpEquations.RegexPolyfill/` | Build time only: the `[GeneratedRegex]` source generator of the netstandard2.0 build |
 | `src/SharpEquations.XsltGenerator/` | Build time only: the source generator that compiles the XSLT stylesheets of `Resources/` to C# |
+| `src/SharpEquations.Editing/` | The equation editor's model, no user interface: `MathNode` tree, caret, selection, undo, build up and build down |
+| `src/SharpEquations.Rendering/` | The layout of MathML Core over the OpenType MATH table, no user interface: `MathLayoutEngine`, `MathLayout` |
+| `src/SharpEquations.Avalonia/` | The controls for Avalonia: `MathEditBox` (the editor), `MathView`; embeds Libertinus Math |
+| `samples/SharpEquations.Avalonia.Demo/` | A window with the editor (`DemoView`, shared with the web demo) |
+| `samples/SharpEquations.Avalonia.Browser.Demo/` | The same demo on WebAssembly (needs the `wasm-tools` workload, so not in the solution; `.github/workflows/demo.yml` publishes it to GitHub Pages) |
 | `benchmarks/SharpEquations.Benchmarks/` | BenchmarkDotNet benchmarks of reading, writing and converting the corpora |
 | `tests/SharpEquations.Tests/` | TUnit tests, in folders by subject (PublicApi, MathML, Omml, Mtef, UnicodeMath, LaTeX, Property, Regression) |
+| `tests/SharpEquations.Avalonia.Tests/` | TUnit tests of the editor (Editing, Rendering, and the controls in a headless Avalonia session with Skia) |
 | `tests/data/` | Test data and its provenance (`tests/data/README.md`) |
 
 ## Code Style
@@ -57,7 +63,8 @@ init-only record: `Display`, `Strict`, `PreserveFormatting`, `LaTeXFlavor` stand
   `menclose notation="bottom"`. The default intents (`:fenced`, `:function`, `absolute-value`,
   `binomial-coefficient`, the matrices...) are not kept, since they would make an equation differ by how it was
   written (`\binom`, `⒞`, `(¦)`); `DefaultIntents.Restore` infers them again from the structure for the LaTeX and
-  UnicodeMath writers.
+  UnicodeMath writers. Content MathML of the source (`apply`, `ci`, `cn`..., outside the annotations) is first rewritten
+  as presentation MathML by `ctop.xsl` (David Carlisle's, see `NOTICE`), keeping the presentation MathML around it.
 - `Internal/Omml/`: OMML ↔ MathML with the XSLT 1.0 stylesheets of `Resources/` (from the TEI Stylesheets, see
   `NOTICE`). OMML is written as Word writes it (plain letters with `m:sty`/`m:scr`,
   underbars as `m:bar`), and an upright word of OMML (`max`) is read as one identifier.
@@ -81,6 +88,27 @@ init-only record: `Display`, `Strict`, `PreserveFormatting`, `LaTeXFlavor` stand
   UnicodeMath: a slash is a slash, not a fraction, and a bar without its pair is a bar, not an absolute value), and
   written as standard LaTeX or as the LaTeX Word writes (`LaTeXSerializer`).
 
+## The equation editor
+
+`docs/EDITOR.md` is its design. The core does not depend on it: the editor is built on the public API of the core only,
+and Avalonia is a dependency of `SharpEquations.Avalonia` alone (Editing and Rendering target netstandard2.0 and
+net10.0 with no package, as the core).
+
+- `Editing`: an equation being edited is a tree of `MathNode`s (the normalized MathML with a row, `mrow`, in every
+  slot) whose only text not built up is in runs. A run builds up with the nodes before it in its row: tokens are written
+  back as they were typed, structures as placeholders (Yi syllables, which the parsers read as identifiers) put back in
+  the result; this works because UnicodeMath round-trips exactly. Positions are paths of child indexes; offsets in runs
+  are code points.
+- `Rendering`: `Layout/Engine.cs` lays out after MathML Core with the constants of the MATH table; the ink boxes of the
+  glyphs come from the outlines of the font (`OpenType/GlyphOutlines.cs`: `glyf`, or the CFF charstrings), never from
+  the rasterizer, and the tables from a copy of the font file (`OpenType/FontFile.cs`).
+- `Avalonia`: `AvaloniaMathFont` reads the font file once with `TryGetStream` and asks Avalonia for its glyph typeface
+  only to draw, each time (`MathFonts.Register` registers the embedded font again with a new font manager: a headless
+  test session gives each test one, and a glyph typeface of the old one is released); the tests that use the headless
+  session are `[NotInParallel("headless")]`, since showing a window or typing runs the jobs of the dispatcher.
+- The core's `EquationCommands` (public) lists the control words of UnicodeMath and the commands of LaTeX with their
+  symbols, for the completion of the editor; `PublicApi/EquationCommandsTests` checks that the parsers read them.
+
 ## Building and Testing
 
 ```bash
@@ -93,12 +121,17 @@ net481 (Windows, where the test project targets net10.0 and net481). The 738 exa
 `tests/data/unicodemath/` test the UnicodeMath port, and `Property/RoundTripPropertyTests` checks, for all of them and
 for the equations of Word documents (`tests/data/omml/`), that an equation written in its own format (UnicodeMath,
 OMML) reads back to the same equation, and that one written in another format (standard LaTeX, Word's LaTeX, OMML)
-loses only the first time what that format cannot hold. Keep these at 100%.
+loses only the first time what that format cannot hold. Keep these at 100%. For the editor, an equation of the corpus
+loaded in the editor, or built down to linear text and up again, is the same equation (100%); typed one character at a
+time it is the equation of the whole text for 93% of the corpus (`Editing/CorpusTests`) and for 90% of the LaTeX of
+latex2mathml (`Editing/RepositoryCorporaTests`), which a change must not lower. The public API of the editor's
+packages is tracked in their `PublicAPI.*.txt`, as that of the core.
 
 ## Releases
 
 `.github/workflows/ci.yml`, the same pipeline as SharpMediaInfo and Letra200bSharp: it tests on Linux (net10.0, net8.0),
-Windows (net10.0, net481) and macOS (net10.0), packs, publishes a `pr-<N>-…` pre-release for each pull request (deleted on close by
+Windows (net10.0, net481) and macOS (net10.0), packs the four packages (`SharpEquations` and the editor's `SharpEquations.Editing`, `.Rendering`, `.Avalonia`, with
+one version), publishes a `pr-<N>-…` pre-release for each pull request (deleted on close by
 `prerelease-cleanup.yml`) and, on `main`, tags `v<VersionPrefix>` of `BuildVersion.props`, creates the GitHub release
 and pushes the package to GitHub Packages and nuget.org (Trusted Publishing, repository variable `NUGET_USER`). A change
 that should release bumps `VersionPrefix`; one that should not says `[no-new-version]` in its commit message.

Directory.Packages.props

@@ -4,6 +4,13 @@
     <CentralPackageTransitivePinningEnabled>true</CentralPackageTransitivePinningEnabled>
   </PropertyGroup>
   <ItemGroup>
+    <PackageVersion Include="Avalonia" Version="12.1.4" />
+    <PackageVersion Include="Avalonia.Browser" Version="12.1.4" />
+    <PackageVersion Include="Avalonia.Desktop" Version="12.1.4" />
+    <PackageVersion Include="Avalonia.Fonts.Inter" Version="12.1.4" />
+    <PackageVersion Include="Avalonia.Headless" Version="12.1.4" />
+    <PackageVersion Include="Avalonia.Skia" Version="12.1.4" />
+    <PackageVersion Include="Avalonia.Themes.Fluent" Version="12.1.4" />
     <PackageVersion Include="BenchmarkDotNet" Version="0.15.8" />
     <PackageVersion Include="Microsoft.SourceLink.GitHub" Version="10.0.401" PrivateAssets="All" />
     <PackageVersion Include="Microsoft.CodeAnalysis.CSharp" Version="4.8.0" />

NOTICE

@@ -182,3 +182,130 @@ SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
 CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
 OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+----------------------------------------------------------------------------
+src/SharpEquations/Resources/ctop.xsl
+tests/data/contentmathml/ctop-*.mml
+
+From https://github.com/davidcarlisle/web-xslt (ctop/ctop.xsl), the XSLT 1.0
+stylesheet of Content MathML to presentation MathML, and its test equations
+(ctop/tests/ctopxslt.html). The web-xslt collection is distributed under the MIT
+licence; ctop.xsl also under the W3C Software Notice and License, Apache 2,
+MPL 1.1 or MPL 2.0. SharpEquations uses them under the MIT licence, the stylesheet
+modified as described in its header:
+
+Copyright David Carlisle 2001, 2002, 2008, 2009, 2013.
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+----------------------------------------------------------------------------
+tests/data/latex/latex2mathml-*.json
+
+Test cases from https://github.com/roniemartinez/latex2mathml:
+
+MIT License
+
+Copyright (c) 2016 Ronie Martinez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+----------------------------------------------------------------------------
+tests/data/mathml/mml2tex.json
+
+Test cases from https://github.com/transpect/mml2tex:
+
+Copyright (c) 2015, transpect.io
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+----------------------------------------------------------------------------
+src/SharpEquations/Internal/LaTeX/Mhchem.cs
+tests/data/latex/treeblood-mhchem.json
+
+The rules of mhchem's \ce in Mhchem.cs follow mhchem.go of https://github.com/Wyatt915/treeblood,
+rewritten in C# to write LaTeX rather than MathML; the test cases are those of its test/TESTCASES.yaml:
+
+MIT License
+
+Copyright (c) 2024 Wyatt Sheffield
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+----------------------------------------------------------------------------
+src/SharpEquations.Avalonia/Assets/Fonts/LibertinusMath-Regular.otf
+
+Libertinus Math 7.040, from the Libertinus fonts, https://github.com/alerque/libertinus,
+the math font that SharpEquations.Avalonia embeds for the systems without Cambria Math.
+Copyright © 2012-2021 The Libertinus Project Authors, with Reserved Font Name
+"Linux Libertine", "Biolinum", "STIX Fonts". Licensed under the SIL Open Font License,
+Version 1.1: src/SharpEquations.Avalonia/Assets/Fonts/OFL.txt (LibertinusMath-OFL.txt in
+the package).