basicwidget/internal: represent font attributes as variations and features

Replace font.Attributes' ad-hoc Weight, Liga, and Tnum members with
general OpenType variation and feature settings. The settings are
stored as taggedValues, a canonical string encoding sorted by tag, so
Attributes remains comparable and keeps working as the face cache key
and in change checks. Attributes values are built with WithVariation
and WithFeature, and resolveFace applies the settings generically
instead of special-casing individual tags.

Move the Feature and Variation types from textstyle to font so the
OpenType tag/value concepts live in the leaf package; textstyle's
Style now exposes them as font.Feature and font.Variation.

A zero Attributes no longer forces the wght axis to 0 on resolved
faces; unset axes now leave the font's defaults untouched.

Updates #131

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

Author: hajimehoshi

basicwidget/internal/font/font.go

@@ -7,6 +7,9 @@ import (
 	"bytes"
 	"compress/gzip"
 	_ "embed"
+	"encoding/binary"
+	"iter"
+	"math"
 	"slices"
 	"sync/atomic"
 
@@ -41,26 +44,90 @@ func init() {
 	theDefaultFaceSource = e
 }
 
-var (
-	tagWght = text.MustParseTag("wght")
-	tagLiga = text.MustParseTag("liga")
-	tagTnum = text.MustParseTag("tnum")
-)
+// Feature is an OpenType feature setting.
+type Feature struct {
+	// Tag identifies the feature, like 'liga'.
+	Tag text.Tag
+
+	// Value is the feature value handed to the font. For typical on/off
+	// features, 0 disables and 1 enables the feature.
+	Value uint32
+}
+
+// Variation is an OpenType variation axis setting.
+type Variation struct {
+	// Tag identifies the axis, like 'wght'.
+	Tag text.Tag
+
+	// Value is the axis value.
+	Value float32
+}
+
+// taggedValues is a canonical, comparable encoding of OpenType (tag, value)
+// settings: 8 bytes per entry, a big-endian uint32 tag followed by a
+// big-endian uint32 value, sorted by tag with at most one entry per tag.
+type taggedValues string
+
+// uint32At returns the big-endian uint32 at byte offset i.
+func (t taggedValues) uint32At(i int) uint32 {
+	return uint32(t[i])<<24 | uint32(t[i+1])<<16 | uint32(t[i+2])<<8 | uint32(t[i+3])
+}
+
+// with returns t with tag set to value, keeping the canonical order.
+func (t taggedValues) with(tag text.Tag, value uint32) taggedValues {
+	var buf [8]byte
+	binary.BigEndian.PutUint32(buf[:4], uint32(tag))
+	binary.BigEndian.PutUint32(buf[4:], value)
+	entry := taggedValues(buf[:])
+	for i := 0; i < len(t); i += 8 {
+		switch existing := text.Tag(t.uint32At(i)); {
+		case existing < tag:
+			continue
+		case existing == tag:
+			return t[:i] + entry + t[i+8:]
+		default:
+			return t[:i] + entry + t[i:]
+		}
+	}
+	return t + entry
+}
 
-// Attributes is a comparable set of text rendering attributes: size, weight,
-// ligatures, tabular numerals, and language. A face is resolved from
-// Attributes together with a [Family]; the attributes alone do not identify a
-// font.
-//
-// TODO: Weight, Liga, and Tnum are ad-hoc special cases. Represent them as
-// general OpenType variations (wght) and features (liga, tnum) while keeping
-// Attributes comparable (#131).
+// all iterates the settings in tag order.
+func (t taggedValues) all() iter.Seq2[text.Tag, uint32] {
+	return func(yield func(text.Tag, uint32) bool) {
+		for i := 0; i < len(t); i += 8 {
+			if !yield(text.Tag(t.uint32At(i)), t.uint32At(i+4)) {
+				return
+			}
+		}
+	}
+}
+
+// Attributes is a comparable set of text rendering attributes: size,
+// language, and OpenType variation and feature settings. A face is resolved
+// from Attributes together with a [Family]; the attributes alone do not
+// identify a font.
 type Attributes struct {
-	Size   float64
-	Weight text.Weight
-	Liga   bool
-	Tnum   bool
-	Lang   language.Tag
+	Size float64
+	Lang language.Tag
+
+	// variations is the canonical encoding of the variation axis settings.
+	variations taggedValues
+
+	// features is the canonical encoding of the feature settings.
+	features taggedValues
+}
+
+// WithVariation returns a with the OpenType variation axis tag set to value.
+func (a Attributes) WithVariation(tag text.Tag, value float32) Attributes {
+	a.variations = a.variations.with(tag, math.Float32bits(value))
+	return a
+}
+
+// WithFeature returns a with the OpenType feature tag set to value.
+func (a Attributes) WithFeature(tag text.Tag, value uint32) Attributes {
+	a.features = a.features.with(tag, value)
+	return a
 }
 
 // Face is a resolved text face.
@@ -238,16 +305,11 @@ func resolveFace(context *guigui.Context, fnt *Family, attributes Attributes) (t
 			Size:     attributes.Size,
 			Language: attributes.Lang,
 		}
-		gtf.SetVariation(tagWght, float32(attributes.Weight))
-		if attributes.Liga {
-			gtf.SetFeature(tagLiga, 1)
-		} else {
-			gtf.SetFeature(tagLiga, 0)
+		for tag, value := range attributes.variations.all() {
+			gtf.SetVariation(tag, math.Float32frombits(value))
 		}
-		if attributes.Tnum {
-			gtf.SetFeature(tagTnum, 1)
-		} else {
-			gtf.SetFeature(tagTnum, 0)
+		for tag, value := range attributes.features.all() {
+			gtf.SetFeature(tag, value)
 		}
 
 		var f text.Face

basicwidget/internal/font/font_test.go

@@ -6,10 +6,38 @@ package font_test
 import (
 	"testing"
 
+	"github.com/hajimehoshi/ebiten/v2/text/v2"
+
 	"github.com/guigui-gui/guigui"
 	"github.com/guigui-gui/guigui/basicwidget/internal/font"
 )
 
+func TestAttributesCanonical(t *testing.T) {
+	tagWght := text.MustParseTag("wght")
+	tagLiga := text.MustParseTag("liga")
+	tagTnum := text.MustParseTag("tnum")
+
+	// The setting order does not affect equality.
+	a1 := font.Attributes{Size: 16}.WithVariation(tagWght, 700).WithFeature(tagLiga, 1).WithFeature(tagTnum, 0)
+	a2 := font.Attributes{Size: 16}.WithFeature(tagTnum, 0).WithFeature(tagLiga, 1).WithVariation(tagWght, 700)
+	if a1 != a2 {
+		t.Errorf("attributes with the same settings should be equal: %v != %v", a1, a2)
+	}
+
+	// Setting a tag again overwrites the previous value.
+	a3 := font.Attributes{Size: 16}.WithVariation(tagWght, 400).WithVariation(tagWght, 700)
+	a4 := font.Attributes{Size: 16}.WithVariation(tagWght, 700)
+	if a3 != a4 {
+		t.Errorf("overwriting a tag should be equal to setting it once: %v != %v", a3, a4)
+	}
+
+	// Different values are not equal.
+	a5 := font.Attributes{Size: 16}.WithVariation(tagWght, 400)
+	if a4 == a5 {
+		t.Errorf("attributes with different settings should not be equal: %v == %v", a4, a5)
+	}
+}
+
 func TestFaceIDStableForSameRecipe(t *testing.T) {
 	var context guigui.Context
 

basicwidget/internal/textstyle/export_test.go

@@ -55,14 +55,14 @@ func (s Style) WithLang(lang language.Tag) Style {
 }
 
 func (s Style) WithFeature(tag text.Tag, value uint32) Style {
-	s.features = mergeTagged(s.features, []Feature{{Tag: tag, Value: value}}, func(f Feature) text.Tag {
+	s.features = mergeTagged(s.features, []font.Feature{{Tag: tag, Value: value}}, func(f font.Feature) text.Tag {
 		return f.Tag
 	})
 	return s
 }
 
 func (s Style) WithVariation(tag text.Tag, value float32) Style {
-	s.variations = mergeTagged(s.variations, []Variation{{Tag: tag, Value: value}}, func(v Variation) text.Tag {
+	s.variations = mergeTagged(s.variations, []font.Variation{{Tag: tag, Value: value}}, func(v font.Variation) text.Tag {
 		return v.Tag
 	})
 	return s

basicwidget/internal/textstyle/runs.go

@@ -124,7 +124,7 @@ func (r *Runs) UnsetLang(start, end int) {
 
 // SetFeature overrides the OpenType feature tag in [start, end) with value.
 func (r *Runs) SetFeature(start, end int, tag text.Tag, value uint32) {
-	r.apply(start, end, Style{features: []Feature{{Tag: tag, Value: value}}})
+	r.apply(start, end, Style{features: []font.Feature{{Tag: tag, Value: value}}})
 }
 
 // UnsetFeature removes the override of the OpenType feature tag in
@@ -136,7 +136,7 @@ func (r *Runs) UnsetFeature(start, end int, tag text.Tag) {
 // SetVariation overrides the OpenType variation axis tag in [start, end)
 // with value.
 func (r *Runs) SetVariation(start, end int, tag text.Tag, value float32) {
-	r.apply(start, end, Style{variations: []Variation{{Tag: tag, Value: value}}})
+	r.apply(start, end, Style{variations: []font.Variation{{Tag: tag, Value: value}}})
 }
 
 // UnsetVariation removes the override of the OpenType variation axis tag in

basicwidget/internal/textstyle/runs_test.go

@@ -12,6 +12,7 @@ import (
 	"github.com/hajimehoshi/ebiten/v2/text/v2"
 	"golang.org/x/text/language"
 
+	"github.com/guigui-gui/guigui/basicwidget/internal/font"
 	"github.com/guigui-gui/guigui/basicwidget/internal/textstyle"
 )
 
@@ -427,7 +428,7 @@ func TestRunsStyleGetters(t *testing.T) {
 	if _, ok := style.Underline(); ok {
 		t.Errorf("Underline(): got set, want unset")
 	}
-	if got, want := style.Features(), []textstyle.Feature{{Tag: tagTnum, Value: 1}}; !slices.Equal(got, want) {
+	if got, want := style.Features(), []font.Feature{{Tag: tagTnum, Value: 1}}; !slices.Equal(got, want) {
 		t.Errorf("Features(): got: %+v, want: %+v", got, want)
 	}
 	if got := style.Variations(); got != nil {

basicwidget/internal/textstyle/style.go

@@ -36,25 +36,6 @@ func (o optional[T]) Value() (T, bool) {
 	return o.value, o.set
 }
 
-// Feature is an OpenType feature setting.
-type Feature struct {
-	// Tag identifies the feature, like 'liga'.
-	Tag text.Tag
-
-	// Value is the feature value handed to the font. For typical on/off
-	// features, 0 disables and 1 enables the feature.
-	Value uint32
-}
-
-// Variation is an OpenType variation axis setting.
-type Variation struct {
-	// Tag identifies the axis, like 'wght'.
-	Tag text.Tag
-
-	// Value is the axis value.
-	Value float32
-}
-
 // Style is a set of style overrides for a byte range of a text value. The
 // zero value overrides nothing. Styles are produced by [Runs]; an unset
 // property does not override anything.
@@ -73,8 +54,8 @@ type Style struct {
 
 	// features and variations are sorted by tag with at most one entry per
 	// tag.
-	features   []Feature
-	variations []Variation
+	features   []font.Feature
+	variations []font.Variation
 }
 
 // Family returns the font family override and whether it is set.
@@ -120,12 +101,12 @@ func (s Style) Lang() (language.Tag, bool) {
 }
 
 // Features returns the OpenType feature overrides, sorted by tag.
-func (s Style) Features() []Feature {
+func (s Style) Features() []font.Feature {
 	return s.features
 }
 
 // Variations returns the OpenType variation axis overrides, sorted by tag.
-func (s Style) Variations() []Variation {
+func (s Style) Variations() []font.Variation {
 	return s.variations
 }
 
@@ -184,10 +165,10 @@ func (s Style) merge(other Style) Style {
 	if other.lang.set {
 		s.lang = other.lang
 	}
-	s.features = mergeTagged(s.features, other.features, func(f Feature) text.Tag {
+	s.features = mergeTagged(s.features, other.features, func(f font.Feature) text.Tag {
 		return f.Tag
 	})
-	s.variations = mergeTagged(s.variations, other.variations, func(v Variation) text.Tag {
+	s.variations = mergeTagged(s.variations, other.variations, func(v font.Variation) text.Tag {
 		return v.Tag
 	})
 	return s
@@ -247,10 +228,10 @@ func (s Style) remove(mask styleMask) Style {
 	if mask.lang {
 		s.lang = optional[language.Tag]{}
 	}
-	s.features = removeTagged(s.features, mask.featureTags, func(f Feature) text.Tag {
+	s.features = removeTagged(s.features, mask.featureTags, func(f font.Feature) text.Tag {
 		return f.Tag
 	})
-	s.variations = removeTagged(s.variations, mask.variationTags, func(v Variation) text.Tag {
+	s.variations = removeTagged(s.variations, mask.variationTags, func(v font.Variation) text.Tag {
 		return v.Tag
 	})
 	return s
@@ -279,10 +260,10 @@ func removeTagged[T any](entries []T, tags []text.Tag, tag func(T) text.Tag) []T
 // canonicalized returns s with features and variations sorted by tag and
 // deduplicated, keeping the last entry for each tag.
 func (s Style) canonicalized() Style {
-	s.features = canonicalTagged(s.features, func(f Feature) text.Tag {
+	s.features = canonicalTagged(s.features, func(f font.Feature) text.Tag {
 		return f.Tag
 	})
-	s.variations = canonicalTagged(s.variations, func(v Variation) text.Tag {
+	s.variations = canonicalTagged(s.variations, func(v font.Variation) text.Tag {
 		return v.Tag
 	})
 	return s

basicwidget/internal/textwidget/style.go

@@ -95,20 +95,33 @@ func (s *textStyle) fontFamilyID() uint64 {
 // faceAttributes returns the font attributes to shape the value with. liga
 // sets whether ligatures are enabled.
 func (s *textStyle) faceAttributes(forceBold bool, liga bool) font.Attributes {
-	size := s.baseFontSize * s.scale()
 	weight := text.WeightMedium
 	if s.bold || forceBold {
 		weight = text.WeightBold
 	}
-	return font.Attributes{
-		Size:   size,
-		Weight: weight,
-		Liga:   liga,
-		Tnum:   s.tabular,
-		Lang:   s.lang,
+	a := font.Attributes{
+		Size: s.baseFontSize * s.scale(),
+		Lang: s.lang,
 	}
+	a = a.WithVariation(tagWght, float32(weight))
+	a = a.WithFeature(tagLiga, boolToFeatureValue(liga))
+	a = a.WithFeature(tagTnum, boolToFeatureValue(s.tabular))
+	return a
 }
 
+func boolToFeatureValue(b bool) uint32 {
+	if b {
+		return 1
+	}
+	return 0
+}
+
+var (
+	tagWght = text.MustParseTag("wght")
+	tagLiga = text.MustParseTag("liga")
+	tagTnum = text.MustParseTag("tnum")
+)
+
 // ensureStyleRuns clears the ranged style overrides if the store's
 // renderable content has been mutated since they were applied, and returns
 // the runs.

basicwidget/internal/textwidget/text.go

@@ -754,7 +754,7 @@ func (t *Text) faceAttributes(forceBold bool) font.Attributes {
 func (t *Text) face(context *guigui.Context, forceBold bool) font.Face {
 	attrs := t.lastFaceAttributes
 	if forceBold {
-		attrs.Weight = text.WeightBold
+		attrs = attrs.WithVariation(tagWght, float32(text.WeightBold))
 	}
 	return font.NewFace(context, t.style.fontFamily, attrs)
 }