CSS engine: sync font-palette, @font-palette-values and palette-mix()

From PeachPDF v0.9.6 (upstream 2bd95e9).

- FontPaletteValuesRule / IFontPaletteValuesRule and their descriptor table
  (font-family / base-palette / override-colors, stored raw)
- The font-palette property and its value converter
- PaletteMixGrammar: the palette-mix() grammar, sharing colour-space and
  hue-direction classification with ColorInterpolationMethodGrammar so the two
  functions cannot disagree about which spaces are valid

Parse-only: there is no palette resolver, and the font backend has no concept
of a CPAL palette, so these declarations cascade and are then ignored.

The two records in PaletteMixGrammar become hand-written classes for C# 7.3.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: 2 people

Source/HtmlRenderer/Core/CssEngine/PaletteMixGrammar.cs

@@ -0,0 +1,184 @@
+using System.Collections.Generic;
+
+namespace TheArtOfDev.HtmlRenderer.Core.CssEngine
+{
+    /// <summary>One operand of a <c>palette-mix()</c>: a palette reference and an optional mixing percentage.</summary>
+    internal sealed class PaletteMixOperand
+    {
+        public PaletteMixOperand(string palette, double? percentage)
+        {
+            Palette = palette;
+            Percentage = percentage;
+        }
+
+        public string Palette { get; }
+        public double? Percentage { get; }
+    }
+
+    /// <summary>
+    /// A parsed <c>palette-mix()</c> value (CSS Fonts Module Level 4). The two operands are blended per CPAL
+    /// entry in <see cref="ColorSpace"/> (with an optional polar <see cref="HueMethod"/>), weighted by the
+    /// operand percentages.
+    /// </summary>
+    internal sealed class ParsedPaletteMix
+    {
+        public ParsedPaletteMix(string colorSpace, string hueMethod, PaletteMixOperand first, PaletteMixOperand second)
+        {
+            ColorSpace = colorSpace;
+            HueMethod = hueMethod;
+            First = first;
+            Second = second;
+        }
+
+        public string ColorSpace { get; }
+        public string HueMethod { get; }
+        public PaletteMixOperand First { get; }
+        public PaletteMixOperand Second { get; }
+    }
+
+    /// <summary>
+    /// The single, shared grammar for the CSS <c>palette-mix()</c> function
+    /// (<a href="https://www.w3.org/TR/css-fonts-4/#font-palette-values">CSS Fonts 4</a>):
+    /// <code>palette-mix( &lt;color-interpolation-method&gt; , [ [ normal | light | dark | &lt;palette-identifier&gt; ] &lt;percentage&gt;? ]#{2} )</code>.
+    /// Used by both Layer A (the <c>font-palette</c> value converter, which drops a malformed value at parse
+    /// time) and Layer B (<c>ActualFontPalette</c> resolution), so the two layers cannot disagree. Color-space
+    /// membership is owned by <see cref="ColorInterpolationMethodGrammar"/> (its predicates classify the space
+    /// and hue direction here), keeping a single source of truth for which spaces are valid.
+    /// </summary>
+    internal static class PaletteMixGrammar
+    {
+        private const string FunctionName = "palette-mix";
+        private const string In = "in";
+        private const string Hue = "hue";
+
+        public static ParsedPaletteMix TryParse(IReadOnlyList<Token> value)
+        {
+            var fn = SinglePaletteMixFunction(value);
+            if (fn == null)
+                return null;
+
+            var groups = SplitTopLevelComma(new List<Token>(fn.ArgumentTokens));
+            if (groups.Count != 3)
+                return null;
+
+            if (!TryParseMethod(groups[0], out var space, out var hue) ||
+                !TryParseOperand(groups[1], out var first) ||
+                !TryParseOperand(groups[2], out var second))
+                return null;
+
+            // Both percentages explicitly zero has no valid interpretation (mirrors color-mix()).
+            if (first.Percentage == 0 && second.Percentage == 0)
+                return null;
+
+            return new ParsedPaletteMix(space, hue, first, second);
+        }
+
+        private static FunctionToken SinglePaletteMixFunction(IReadOnlyList<Token> value)
+        {
+            FunctionToken found = null;
+            foreach (var token in value)
+            {
+                if (token.Type == TokenType.Whitespace)
+                    continue;
+                var fn = token as FunctionToken;
+                if (found != null || fn == null || !fn.Data.Isi(FunctionName))
+                    return null;
+                found = fn;
+            }
+
+            return found;
+        }
+
+        // in <color-space> [ <hue-interpolation-method> hue ]?  (the hue method only after a polar space)
+        private static bool TryParseMethod(List<Token> tokens, out string space, out string hue)
+        {
+            space = null;
+            hue = null;
+
+            int i = 0;
+
+            if (i >= tokens.Count || !IsIdent(tokens[i], out var inWord) || !inWord.Isi(In))
+                return false;
+            i++;
+
+            if (i >= tokens.Count || !IsIdent(tokens[i], out var spaceName) ||
+                !ColorInterpolationMethodGrammar.IsColorSpace(spaceName))
+                return false;
+            space = spaceName;
+            i++;
+
+            if (i < tokens.Count)
+            {
+                // A trailing "<dir> hue" is valid only for a polar color space.
+                if (!ColorInterpolationMethodGrammar.IsPolarColorSpace(spaceName))
+                    return false;
+                if (!IsIdent(tokens[i], out var dir) || !ColorInterpolationMethodGrammar.IsHueDirection(dir))
+                    return false;
+                i++;
+                if (i >= tokens.Count || !IsIdent(tokens[i], out var hueWord) || !hueWord.Isi(Hue))
+                    return false;
+                hue = dir;
+                i++;
+            }
+
+            return i == tokens.Count;
+        }
+
+        // [ normal | light | dark | <dashed-ident> ] <percentage>?
+        private static bool TryParseOperand(List<Token> tokens, out PaletteMixOperand operand)
+        {
+            operand = null;
+
+            if (tokens.Count == 0 || tokens.Count > 2)
+                return false;
+
+            if (!IsIdent(tokens[0], out var palette) || !IsPaletteIdentifier(palette))
+                return false;
+
+            double? percentage = null;
+            if (tokens.Count == 2)
+            {
+                var pct = tokens[1] as UnitToken;
+                if (pct == null || pct.Type != TokenType.Percentage)
+                    return false;
+                percentage = pct.Value;
+            }
+
+            operand = new PaletteMixOperand(palette, percentage);
+            return true;
+        }
+
+        private static bool IsPaletteIdentifier(string ident) =>
+            ident.Isi(Keywords.Normal) || ident.Isi("light") || ident.Isi("dark") ||
+            ident.StartsWith("--", System.StringComparison.Ordinal);
+
+        // Splits the argument tokens on top-level commas, dropping whitespace (insignificant in this grammar).
+        private static List<List<Token>> SplitTopLevelComma(List<Token> tokens)
+        {
+            var groups = new List<List<Token>> { new List<Token>() };
+            foreach (var token in tokens)
+            {
+                if (token.Type == TokenType.Whitespace)
+                    continue;
+                if (token.Type == TokenType.Comma)
+                    groups.Add(new List<Token>());
+                else
+                    groups[groups.Count - 1].Add(token);
+            }
+
+            return groups;
+        }
+
+        private static bool IsIdent(Token token, out string data)
+        {
+            if (token.Type == TokenType.Ident)
+            {
+                data = token.Data;
+                return true;
+            }
+
+            data = string.Empty;
+            return false;
+        }
+    }
+}

Source/HtmlRenderer/Core/CssEngine/Rules/FontPaletteValuesRule.cs

@@ -0,0 +1,56 @@
+using System.IO;
+using System.Linq;
+
+namespace TheArtOfDev.HtmlRenderer.Core.CssEngine
+{
+    /// <summary>
+    /// A <c>@font-palette-values</c> at-rule (CSS Fonts Module Level 4): associates a named palette override
+    /// (a dashed-ident such as <c>--my-palette</c>) with a font family, selecting a <c>base-palette</c> and
+    /// optionally overriding individual colors (<c>override-colors</c>). The descriptor block is stored like
+    /// <see cref="PropertyRule"/>; the name is captured from the prelude like <see cref="KeyframesRule.Name"/>.
+    /// </summary>
+    internal sealed class FontPaletteValuesRule : DeclarationRule, IFontPaletteValuesRule
+    {
+        internal FontPaletteValuesRule(StylesheetParser parser)
+            : base(RuleType.FontPaletteValues, RuleNames.FontPaletteValues, parser)
+        {
+        }
+
+        protected override Property CreateNewProperty(string name)
+        {
+            return PropertyFactory.Instance.CreateFontPaletteDescriptor(name);
+        }
+
+        protected override void ReplaceWith(IRule rule)
+        {
+            if (rule is FontPaletteValuesRule other) Name = other.Name;
+            base.ReplaceWith(rule);
+        }
+
+        public string Name { get; set; }
+
+        public string Family
+        {
+            get => GetValue(PropertyNames.FontFamily);
+            set => SetValue(PropertyNames.FontFamily, value);
+        }
+
+        public string BasePalette
+        {
+            get => GetValue(PropertyNames.BasePalette);
+            set => SetValue(PropertyNames.BasePalette, value);
+        }
+
+        public string OverrideColors
+        {
+            get => GetValue(PropertyNames.OverrideColors);
+            set => SetValue(PropertyNames.OverrideColors, value);
+        }
+
+        public override void ToCss(TextWriter writer, IStyleFormatter formatter)
+        {
+            var declarations = formatter.Declarations(Declarations.Where(d => d.HasValue).Select(d => d.ToCss(formatter)));
+            writer.Write(string.Concat("@font-palette-values ", Name, " { ", declarations, " }"));
+        }
+    }
+}

Source/HtmlRenderer/Core/CssEngine/Rules/IFontPaletteValuesRule.cs

@@ -0,0 +1,21 @@
+namespace TheArtOfDev.HtmlRenderer.Core.CssEngine
+{
+    /// <summary>
+    /// A palette override declared with a <c>@font-palette-values</c> at-rule (CSS Fonts Module Level 4).
+    /// Exposes the prelude name and the three descriptors.
+    /// </summary>
+    internal interface IFontPaletteValuesRule : IRule, IProperties
+    {
+        /// <summary>The palette name, a dashed-ident referenced by <c>font-palette: &lt;dashed-ident&gt;</c>, e.g. <c>--my-palette</c>.</summary>
+        string Name { get; set; }
+
+        /// <summary>The raw <c>font-family</c> descriptor value (the family this palette applies to).</summary>
+        string Family { get; set; }
+
+        /// <summary>The raw <c>base-palette</c> descriptor value (<c>&lt;integer&gt; | light | dark</c>).</summary>
+        string BasePalette { get; set; }
+
+        /// <summary>The raw <c>override-colors</c> descriptor value (a comma list of <c>&lt;index&gt; &lt;color&gt;</c> pairs).</summary>
+        string OverrideColors { get; set; }
+    }
+}

Source/HtmlRenderer/Core/CssEngine/StyleProperties/Font/FontPaletteProperty.cs

@@ -0,0 +1,20 @@
+namespace TheArtOfDev.HtmlRenderer.Core.CssEngine
+{
+    /// <summary>
+    /// The <c>font-palette</c> property (CSS Fonts Module Level 4): selects a color palette for a COLR/CPAL
+    /// color font. Inherited. The value grammar (<c>normal | light | dark | &lt;dashed-ident&gt; | palette-mix()</c>)
+    /// is validated by <see cref="FontPaletteValueConverter"/>; the authored text is preserved for the paint-time
+    /// resolver (<c>CssBoxProperties.ActualFontPalette</c>).
+    /// </summary>
+    internal sealed class FontPaletteProperty : Property
+    {
+        private static readonly IValueConverter StyleConverter = new FontPaletteValueConverter().OrDefault();
+
+        internal FontPaletteProperty()
+            : base(PropertyNames.FontPalette, PropertyFlags.Inherited)
+        {
+        }
+
+        internal override IValueConverter Converter => StyleConverter;
+    }
+}

Source/HtmlRenderer/Core/CssEngine/ValueConverters/FontPaletteValueConverter.cs

@@ -0,0 +1,49 @@
+using System.Collections.Generic;
+using System.Linq;
+
+namespace TheArtOfDev.HtmlRenderer.Core.CssEngine
+{
+    /// <summary>
+    /// Validates a <c>font-palette</c> value (CSS Fonts Module Level 4): the keywords <c>normal</c>/
+    /// <c>light</c>/<c>dark</c>, a <c>&lt;dashed-ident&gt;</c> naming an <c>@font-palette-values</c> rule, or a
+    /// <c>palette-mix()</c> function (validated through the shared <see cref="PaletteMixGrammar"/>). Anything
+    /// else is dropped at parse time. The authored value text is preserved verbatim (Layer B re-tokenizes and
+    /// resolves it in <c>ActualFontPalette</c>), mirroring <see cref="ClipPathValueConverter"/>.
+    /// </summary>
+    internal sealed class FontPaletteValueConverter : IValueConverter
+    {
+        public IPropertyValue Convert(IEnumerable<Token> value)
+        {
+            var tokens = value.Where(t => t.Type != TokenType.Whitespace).ToArray();
+
+            bool valid = tokens.Length == 1 && tokens[0].Type == TokenType.Ident
+                ? IsKeywordOrDashedIdent(tokens[0].Data)
+                : PaletteMixGrammar.TryParse(tokens) != null;
+
+            return valid ? new FontPaletteValue(value) : null;
+        }
+
+        public IPropertyValue Construct(Property[] properties)
+        {
+            return properties.Guard<FontPaletteValue>();
+        }
+
+        private static bool IsKeywordOrDashedIdent(string ident) =>
+            ident.Isi(Keywords.Normal) || ident.Isi("light") || ident.Isi("dark") ||
+            ident.StartsWith("--", System.StringComparison.Ordinal);
+
+        private sealed class FontPaletteValue : IPropertyValue
+        {
+            public FontPaletteValue(IEnumerable<Token> tokens)
+            {
+                Original = new TokenValue(tokens);
+            }
+
+            public string CssText => Original.Text;
+
+            public TokenValue Original { get; }
+
+            public TokenValue ExtractFor(string name) => Original;
+        }
+    }
+}