LT-22638: Show OpenType feature names and multi-valued variants

Docs/opentype-font-features.md

@@ -4,6 +4,22 @@ FieldWorks stores font options as renderer-neutral feature strings such as `smcp
 
 In the current WinForms UI, use the Font Options button in font controls to choose the configurable features exposed by the selected font. Graphite remains available for now, but the Font Options UI is no longer limited to Graphite fonts.
 
+## Feature names and values
+
+Feature labels are resolved in order: the name the font supplies for a stylistic set (`ssXX`) or character variant (`cvXX`) via its GSUB `featureParams` and `name` table; a localized name from `FwCoreDlgControls.resx`; the English name from the registered-feature catalog; and finally a `Stylistic Set N` / `Character Variant N` / `Feature #<tag>` fallback. Labels show the name only, matching the Graphite presentation; four-character tags appear only in the last-resort fallback. `OpenTypeFontFeatureInfoReader` in `FwUtils` reads this information from GSUB and GPOS through a table-source delegate (GDI `GetFontData` in the app, font-file bytes in tests) and degrades to a tag-only record if a table is malformed.
+
+A character variant that names its options is presented as a multi-valued submenu — `None` plus each named option — and stored as `cv43=2`, where the value is the 1-based option index. Character variants and stylistic sets without font-supplied strings fall back to an on/off toggle.
+
+`OpenTypeFeatureCatalog` in `FwUtils` classifies registered features. Features it marks hidden (shaping-required features such as `mark`, `ccmp`, `init`; and glyph-palette features such as `aalt`) are discovered but not shown as toggles. Features it marks default-on (`liga`, `clig`, `calt`, `kern`) display as enabled when the stored feature string does not mention them; the string gains an explicit `tag=0` only when the user turns such a feature off. Unset features are never written.
+
+`IsDefaultOn` is the one place the OpenType provider is not equivalent to the Graphite one, and the difference matters before changing the set. `GraphiteFontFeatureProvider` gets `defaultValue` from the font: `IRenderingFeatures.GetFeatureValues` reads the font's own feature table, where the designer declared a default per feature, and that same table drives the Graphite shaper. The checkbox and the renderer cannot disagree. OpenType has nowhere to record this. A GSUB/GPOS `FeatureRecord` has no default-value field, and only `cvNN`/`ssNN` carry `featureParams`, which hold labels rather than defaults. `OpenTypeFontFeatureProvider` therefore fills the same out-parameter from `OpenTypeFeatureCatalog.IsDefaultOn`, a static table. That makes it an assertion about what Uniscribe does, not a fact read from the font, and the two providers share a signature that hides the difference.
+
+Marking a tag default-on only sets the initial checkbox state for a feature the writing system does not mention; nothing reaches the renderer either way. Being wrong is not symmetric. A tag wrongly marked on displays as enabled while the text is unaffected, and the user's first click writes `tag=0`, so the gesture meant to enable it explicitly disables it. A tag wrongly marked off displays as disabled while the text is affected, and the first click writes `tag=1`, a no-op that matches reality, with `tag=0` one click further. Under uncertainty, off is the recoverable error.
+
+That is why the set is narrower than the OpenType registry suggests. The registry recommends `cpsp` and `rand` be on by default, and `chws` and `halt` for horizontal CJK layout in applications that do not implement CLREQ/JLREQ/KLREQ. Those are instructions to an application to *apply* a feature, which here would mean writing `tag=1`; marking such a tag default-on does the opposite, leaving the string silent so the feature is never requested. `chws` and `halt` could not both be default-on regardless, since each is mutually exclusive with the other and with every other horizontal glyph-width feature, and the catalog carries no per-script state. LT-22774 measures what Uniscribe actually applies, which is the only thing that can close this loop the way the Graphite font table closes it.
+
+Feature discovery is script-blind, which is a known limitation rather than an oversight. `OpenTypeFontFeatureInfoReader` walks the feature list flat and deduplicates by tag, so a font that gave the same tag different labels or options under different scripts would show one script's strings to another. No font does: of 178 installed fonts, 173 `cv`/`ss` tags appear more than once and every duplicate carries identical metadata, and the SIL fonts covering Latin, Cyrillic and Greek together register each feature once under every script. Making it script-aware requires passing the writing system's script into the reader; do that when a font appears that needs it.
+
 Graphite feature IDs are still converted only at the Graphite renderer boundary. OpenType feature tags stay as four-character tags and are passed to the Uniscribe OpenType path when Graphite is not enabled.
 
 For export, CSS output maps these values to `font-feature-settings`, and Notebook export preserves writing-system default font features in `DefaultFontFeatures`.

Src/Common/FwUtils/FwUtilsTests/FwUtilsTests.csproj

@@ -46,4 +46,19 @@
     <ProjectReference Include="../../ViewsInterfaces/ViewsInterfaces.csproj" />
     <ProjectReference Include="../FwUtils.csproj" />
   </ItemGroup>
+
+  <!-- Charis SIL test font: downloaded (not committed) by Build/PackageRestore.targets into
+       Downloads/CharisSIL; copied beside the test assembly so OpenTypeFontFeatureInfoReader tests
+       can slice its tables privately. Keep CharisSilTestFontVersion in sync with CharisSilVersion
+       in Build/PackageRestore.targets (see also Src/views/Test/TestViews.vcxproj). LT-22638. -->
+  <PropertyGroup>
+    <CharisSilTestFontVersion>6.200</CharisSilTestFontVersion>
+    <CharisSilTestFontPath>$(FwRoot)\Downloads\CharisSIL\CharisSIL-$(CharisSilTestFontVersion)\CharisSIL-Regular.ttf</CharisSilTestFontPath>
+  </PropertyGroup>
+  <Target Name="CopyCharisSilTestFont" AfterTargets="Build">
+    <Copy SourceFiles="$(CharisSilTestFontPath)"
+          DestinationFolder="$(OutDir)TestData\Fonts\CharisSIL"
+          SkipUnchangedFiles="true"
+          Condition="Exists('$(CharisSilTestFontPath)')" />
+  </Target>
 </Project>

Src/Common/FwUtils/FwUtilsTests/OpenTypeFeatureCatalogTests.cs

@@ -0,0 +1,97 @@
+// Copyright (c) 2026 SIL International
+// This software is licensed under the LGPL, version 2.1 or later
+// (http://www.gnu.org/licenses/lgpl-2.1.html)
+
+using System;
+using System.Linq;
+using NUnit.Framework;
+
+namespace SIL.FieldWorks.Common.FwUtils
+{
+	[TestFixture]
+	public class OpenTypeFeatureCatalogTests
+	{
+		// The exact set the pre-LT-22638 FontFeaturesButton hid via its s_nonUserConfigurableTags
+		// blocklist. Every one must stay hidden so the catalog does not un-hide shaping features.
+		private static readonly string[] LegacyBlocklist =
+		{
+			"abvf", "abvm", "abvs", "akhn", "blwf", "blwm", "blws", "ccmp",
+			"cjct", "curs", "dist", "fina", "haln", "half", "init", "isol",
+			"ljmo", "locl", "mark", "medi", "mkmk", "nukt", "pref", "pres",
+			"pstf", "psts", "rclt", "rkrf", "rlig", "tjmo", "vjmo"
+		};
+
+		[Test]
+		public void LegacyBlocklistTags_AreAllHidden()
+		{
+			foreach (var tag in LegacyBlocklist)
+			{
+				Assert.That(OpenTypeFeatureCatalog.IsKnown(tag), Is.True, $"'{tag}' should be catalogued");
+				Assert.That(OpenTypeFeatureCatalog.IsHidden(tag), Is.True, $"'{tag}' should remain hidden");
+			}
+		}
+
+		[Test]
+		public void DiscretionaryLigatures_AreUserVisible()
+		{
+			// Audit correction: Paratext hides dlig, but it is the canonical user-facing ligature feature.
+			Assert.That(OpenTypeFeatureCatalog.IsHidden("dlig"), Is.False);
+		}
+
+		[Test]
+		public void AccessAllAlternates_IsHidden()
+		{
+			// Audit correction: aalt is a glyph palette, not a meaningful on/off toggle.
+			Assert.That(OpenTypeFeatureCatalog.IsHidden("aalt"), Is.True);
+		}
+
+		[TestCase("liga")]
+		[TestCase("clig")]
+		[TestCase("calt")]
+		[TestCase("kern")]
+		public void CommonlyDefaultOnFeatures_AreDefaultOn(string tag)
+		{
+			Assert.That(OpenTypeFeatureCatalog.IsHidden(tag), Is.False);
+			Assert.That(OpenTypeFeatureCatalog.IsDefaultOn(tag), Is.True);
+		}
+
+		[Test]
+		public void DefaultOnFeatures_AreOnlyTheDocumentedFour()
+		{
+			// A default-on feature is applied to text the user never opted into, and is written to
+			// the writing system only when they turn it off, so the set is a policy decision rather
+			// than a per-tag judgement. Docs/opentype-font-features.md names these four; asserting
+			// membership one tag at a time cannot catch a fifth being added, which is how "rand",
+			// "chws", "cpsp", "halt" and "size" got in. LT-22638.
+			//
+			// The set deliberately diverges from the OpenType registry, which suggests cpsp, rand,
+			// chws and halt be on by default. Unlike the Graphite provider, which reads defaultValue
+			// out of the font, this one asserts it from a static table, because OpenType has no
+			// per-feature default to read; a wrong assertion here inverts the user's first click.
+			// Docs/opentype-font-features.md has the full reasoning, and LT-22774 measures what
+			// Uniscribe actually applies. Do not widen this set without that measurement.
+			var defaultOn = OpenTypeFeatureCatalog.AllTags
+				.Where(OpenTypeFeatureCatalog.IsDefaultOn)
+				.OrderBy(tag => tag, StringComparer.Ordinal)
+				.ToArray();
+
+			Assert.That(defaultOn, Is.EqualTo(new[] { "calt", "clig", "kern", "liga" }));
+		}
+
+		[Test]
+		public void UnknownTag_IsNeitherKnownNorHidden()
+		{
+			Assert.That(OpenTypeFeatureCatalog.IsKnown("zzzz"), Is.False);
+			Assert.That(OpenTypeFeatureCatalog.IsHidden("zzzz"), Is.False);
+			Assert.That(OpenTypeFeatureCatalog.GetEnglishName("zzzz"), Is.Null);
+		}
+
+		[Test]
+		public void VisibleFeatures_HaveEnglishNames()
+		{
+			foreach (var tag in OpenTypeFeatureCatalog.AllTags.Where(t => !OpenTypeFeatureCatalog.IsHidden(t)))
+				Assert.That(OpenTypeFeatureCatalog.GetEnglishName(tag), Is.Not.Null.And.Not.Empty,
+					$"visible feature '{tag}' needs a friendly name");
+		}
+	}
+}