Merge branch 'main' into break-props

.github/workflows/analysis.yml

@@ -1,21 +1,24 @@
-on: [push, pull_request]
 name: Static Analysis
+on: [push, pull_request]
+permissions:
+  contents: read
+
 jobs:
-  test: 
+  static_analysis:
     runs-on: ubuntu-latest
     steps:
-    - name: Install Go
-      uses: actions/setup-go@v3
+    - uses: actions/checkout@v4
       with:
-        go-version: 1.19.x
+        persist-credentials: false
+    - uses: WillAbides/[email protected]
+      with:
+        go-version: '1.21.x'
+
+    - name: Install analysis tools
+      run: go install honnef.co/go/tools/cmd/[email protected]
 
-    - name: Checkout code
-      uses: actions/checkout@v2
-
     - name: Vet
       run: go vet ./...
 
     - name: Staticcheck
-      run: |
-        go install honnef.co/go/tools/cmd/[email protected]
-        staticcheck ./...
+      run: staticcheck ./...

.github/workflows/test.yml

@@ -1,26 +1,26 @@
-on: [push, pull_request]
 name: Test
+on: [push, pull_request]
+permissions:
+  contents: read
+
 jobs:
   test:
     strategy:
       matrix:
-        go-version: [1.14.x, 1.19.x, 1.20.x]
+        go-version: [1.17.x, 1.20.x, 1.21.x]
         os: [ubuntu-latest, windows-latest, macos-latest]
 
     runs-on: ${{ matrix.os }}
     steps:
-    - name: Install Go
-      uses: actions/setup-go@v3
+    - uses: actions/checkout@v4
+      with:
+        persist-credentials: false
+    - uses: WillAbides/[email protected]
       with:
         go-version: ${{ matrix.go-version }}
-
-    - name: Checkout code
-      uses: actions/checkout@v2
 
-    - name: Build without tests
-      run: go build ./...
-      if: ${{ matrix.go-version == '1.14.x' }}
-
     - name: Test
       run: go test ./...
-      if: ${{ matrix.go-version != '1.14.x' }}
+
+    - name: Build without tests
+      run: go build ./...

README.md

@@ -1,3 +1,35 @@
 # typesetting
 
 This library provides typesetting capabilities in pure Go. It is appropriate for use in GUI applications, and is shared by multiple Go UI toolkits including [Fyne](https://fyne.io) and [Gio](https://gioui.org).
+
+## Development cycle
+
+This project, although already used in production by UI toolkits, still evolves rapidly. As such, the library uses unstable versions v0.x.y : the required breaking changes will bump the minor version number (x); the bug fixes and performance improvements the patch number (y).
+
+## Review guidelines
+
+Go-text is a collaboration between many individuals and projects, it is important to us that
+designs and decisions are right for the broadest possible audience.
+As a result the project will always have 3 maintainers that represent different projects
+(currently Fyne.io, Gio and an independent developer).
+
+### API and Architectural decisions
+
+Changes to any core go-text repositories (not including utility or generator repos) will require
+sign-off from at least 2 of these 3 maintainers to be approved.
+"typesetting" and "render" are currently considered core.
+Upon approval the second thumbs up will typically merge the change into the repository.
+
+Decisions or API discussions are best carried out within the context of a GitHub issue or
+pull request for greatest visibility in the future.
+
+### Smaller changes and quality of life improvements
+
+For speed of acceptance on smaller issues it is not always required to have complete consensus.
+When a change is deemed to be of minor impact (for example documentation corrections, trivial
+bug fixes and straight forward refactoring of content) an expedited review is supported.
+In this situation the contribution only requires a single approval (not from the individual
+proposing the change).
+
+If in doubt please seek approval of two maintainers - and feel free to ask questions in the
+#go-text channel of gophers Slack server.

di/direction.go

@@ -1,5 +1,9 @@
 package di
 
+import (
+	"github.com/go-text/typesetting/harfbuzz"
+)
+
 // Direction indicates the layout direction of a piece of text.
 type Direction uint8
 
@@ -14,30 +18,52 @@ const (
 	DirectionBTT
 )
 
+const (
+	progression Direction = 1 << iota
+	// axisVertical is the bit for the axis, 0 for horizontal, 1 for vertical
+	axisVertical
+
+	// If this flag is set, the orientation is chosen
+	// using the [verticalSideways] flag.
+	// Otherwise, the segmenter will resolve the orientation based
+	// on unicode properties
+	verticalOrientationSet
+	// verticalSideways is set for 'sideways', unset for 'upright'
+	// It implies BVerticalOrientationSet is set
+	verticalSideways
+)
+
 // IsVertical returns whether d is laid out on a vertical
 // axis. If the return value is false, d is on the horizontal
 // axis.
-func (d Direction) IsVertical() bool {
-	return d == DirectionBTT || d == DirectionTTB
-}
+func (d Direction) IsVertical() bool { return d&axisVertical != 0 }
 
 // Axis returns the layout axis for d.
 func (d Direction) Axis() Axis {
-	switch d {
-	case DirectionBTT, DirectionTTB:
+	if d.IsVertical() {
 		return Vertical
-	default:
-		return Horizontal
 	}
+	return Horizontal
 }
 
+// SwitchAxis switches from horizontal to vertical (and vice versa), preserving
+// the progression.
+func (d Direction) SwitchAxis() Direction { return d ^ axisVertical }
+
 // Progression returns the text layout progression for d.
 func (d Direction) Progression() Progression {
-	switch d {
-	case DirectionTTB, DirectionLTR:
+	if d&progression == 0 {
 		return FromTopLeft
-	default:
-		return TowardTopLeft
+	}
+	return TowardTopLeft
+}
+
+// SetProgression sets the progression, preserving the others bits.
+func (d *Direction) SetProgression(p Progression) {
+	if p == FromTopLeft {
+		*d &= ^progression
+	} else {
+		*d |= progression
 	}
 }
 
@@ -65,3 +91,40 @@ const (
 	// of TowardTopLeft progression.
 	TowardTopLeft Progression = true
 )
+
+// HasVerticalOrientation returns true if the direction has set up
+// an orientation for vertical text (typically using [SetSideways] or [SetUpright])
+func (d Direction) HasVerticalOrientation() bool { return d&verticalOrientationSet != 0 }
+
+// IsSideways returns true if the direction is vertical with a 'sideways'
+// orientation.
+//
+// When shaping vertical text, 'sideways' means that the glyphs are rotated
+// by 90°, clock-wise. This flag should be used by renderers to properly
+// rotate the glyphs when drawing.
+func (d Direction) IsSideways() bool { return d.IsVertical() && d&verticalSideways != 0 }
+
+// SetSideways makes d vertical with 'sideways' or 'upright' orientation, preserving only the
+// progression.
+func (d *Direction) SetSideways(sideways bool) {
+	*d |= axisVertical | verticalOrientationSet
+	if sideways {
+		*d |= verticalSideways
+	} else {
+		*d &= ^verticalSideways
+	}
+}
+
+// Harfbuzz returns the equivalent direction used by harfbuzz.
+func (d Direction) Harfbuzz() harfbuzz.Direction {
+	switch d & (progression | axisVertical) {
+	case DirectionRTL:
+		return harfbuzz.RightToLeft
+	case DirectionBTT:
+		return harfbuzz.BottomToTop
+	case DirectionTTB:
+		return harfbuzz.TopToBottom
+	default:
+		return harfbuzz.LeftToRight
+	}
+}

di/direction_test.go

@@ -0,0 +1,65 @@
+package di
+
+import (
+	"testing"
+
+	"github.com/go-text/typesetting/harfbuzz"
+	tu "github.com/go-text/typesetting/opentype/testutils"
+)
+
+func TestDirection(t *testing.T) {
+	tu.Assert(t, DirectionLTR.Axis() == Horizontal)
+	tu.Assert(t, DirectionRTL.Axis() == Horizontal)
+	tu.Assert(t, DirectionTTB.Axis() == Vertical)
+	tu.Assert(t, DirectionBTT.Axis() == Vertical)
+	tu.Assert(t, !DirectionLTR.IsVertical())
+	tu.Assert(t, !DirectionRTL.IsVertical())
+	tu.Assert(t, DirectionTTB.IsVertical())
+	tu.Assert(t, DirectionBTT.IsVertical())
+
+	tu.Assert(t, DirectionLTR.Progression() == FromTopLeft)
+	tu.Assert(t, DirectionRTL.Progression() == TowardTopLeft)
+	tu.Assert(t, DirectionTTB.Progression() == FromTopLeft)
+	tu.Assert(t, DirectionBTT.Progression() == TowardTopLeft)
+
+	tu.Assert(t, !DirectionTTB.IsSideways())
+	tu.Assert(t, !DirectionBTT.IsSideways())
+
+	tu.Assert(t, DirectionLTR.SwitchAxis() == DirectionTTB)
+	tu.Assert(t, DirectionRTL.SwitchAxis() == DirectionBTT)
+	tu.Assert(t, DirectionTTB.SwitchAxis() == DirectionLTR)
+	tu.Assert(t, DirectionBTT.SwitchAxis() == DirectionRTL)
+
+	tu.Assert(t, DirectionLTR.Harfbuzz() == harfbuzz.LeftToRight)
+	tu.Assert(t, DirectionRTL.Harfbuzz() == harfbuzz.RightToLeft)
+	tu.Assert(t, DirectionTTB.Harfbuzz() == harfbuzz.TopToBottom)
+	tu.Assert(t, DirectionBTT.Harfbuzz() == harfbuzz.BottomToTop)
+
+	tu.Assert(t, !DirectionLTR.HasVerticalOrientation())
+	tu.Assert(t, !DirectionRTL.HasVerticalOrientation())
+	tu.Assert(t, !DirectionTTB.HasVerticalOrientation())
+	tu.Assert(t, !DirectionBTT.HasVerticalOrientation())
+
+	for _, test := range []struct {
+		sideways    bool
+		progression Progression
+		hb          harfbuzz.Direction
+	}{
+		{true, FromTopLeft, harfbuzz.TopToBottom},
+		{true, TowardTopLeft, harfbuzz.BottomToTop},
+		{false, FromTopLeft, harfbuzz.TopToBottom},
+		{false, TowardTopLeft, harfbuzz.BottomToTop},
+	} {
+		d := axisVertical
+		d.SetProgression(test.progression)
+
+		tu.Assert(t, !d.HasVerticalOrientation())
+		d.SetSideways(test.sideways)
+
+		tu.Assert(t, d.HasVerticalOrientation())
+		tu.Assert(t, d.IsSideways() == test.sideways)
+		tu.Assert(t, d.Axis() == Vertical)
+		tu.Assert(t, d.Progression() == test.progression)
+		tu.Assert(t, d.Harfbuzz() == test.hb)
+	}
+}