feat: New Border Title API

.gitignore

@@ -0,0 +1 @@
+**/.idea/

borders.go

@@ -246,11 +246,39 @@ func (s Style) applyBorder(str string) string {
 	border.BottomLeft = getFirstRuneAsString(border.BottomLeft)
 
 	var out strings.Builder
+	const sideCount = 2
 
 	// Render top
 	if hasTop {
-		top := renderHorizontalEdge(border.TopLeft, border.Top, border.TopRight, width)
-		top = styleBorder(top, topFG, topBG)
+		top := ""
+		title := s.GetBorderTitle()
+		if len(strings.TrimSpace(title)) > 0 {
+			if len(title) > width {
+				// the truncation algorithm can be provided through the API in the future
+				title = title[0 : width-1]
+			}
+
+			topBeforeTitle := border.TopLeft
+			topAfterTitle := border.TopRight
+			switch s.GetBorderTitleAlignment() {
+			case Right:
+				topBeforeTitle = border.TopLeft + strings.Repeat(border.Top, width-1-len(title))
+			case Center:
+				noTitleLen := width - 1 - len(title)
+				noTitleLen2 := noTitleLen / sideCount
+				topBeforeTitle = border.TopLeft + strings.Repeat(border.Top, noTitleLen2)
+				topAfterTitle = strings.Repeat(border.Top, noTitleLen-noTitleLen2) + border.TopRight
+			case Left:
+				topAfterTitle = strings.Repeat(border.Top, width-1-len(title)) + border.TopRight
+			}
+
+			top = styleBorder(topBeforeTitle, topFG, topBG) +
+				styleBorder(title, s.GetBorderTitleForeground(), s.GetBorderTitleBackground()) +
+				styleBorder(topAfterTitle, topFG, topBG)
+		} else {
+			top = renderHorizontalEdge(border.TopLeft, border.Top, border.TopRight, width)
+			top = styleBorder(top, topFG, topBG)
+		}
 		out.WriteString(top)
 		out.WriteRune('\n')
 	}
@@ -314,6 +342,7 @@ func renderHorizontalEdge(left, middle, right string, width int) string {
 
 	out := strings.Builder{}
 	out.WriteString(left)
+
 	for i := leftWidth + rightWidth; i < width+rightWidth; {
 		out.WriteRune(runes[j])
 		j++

example/main.go

@@ -95,6 +95,8 @@ var (
 	dialogBoxStyle = lipgloss.NewStyle().
 			Border(lipgloss.RoundedBorder()).
 			BorderForeground(lipgloss.Color("#874BFD")).
+			BorderTitleForeground(lipgloss.Color("#FFFFFF")).
+			BorderTitleAlignment(lipgloss.Center).
 			Padding(1, 0).
 			BorderTop(true).
 			BorderLeft(true).
@@ -239,7 +241,7 @@ func main() {
 
 		dialog := lipgloss.Place(width, 9,
 			lipgloss.Center, lipgloss.Center,
-			dialogBoxStyle.Render(ui),
+			dialogBoxStyle.Copy().BorderTitle(" Question ").Render(ui),
 			lipgloss.WithWhitespaceChars("猫咪"),
 			lipgloss.WithWhitespaceForeground(subtle),
 		)

get.go

@@ -434,6 +434,15 @@ func (s Style) getAsInt(k propKey) int {
 	return 0
 }
 
+func (s Style) getAsString(k propKey) string {
+	if v, ok := s.rules[k]; ok {
+		if s, ok := v.(string); ok {
+			return s
+		}
+	}
+	return ""
+}
+
 func (s Style) getAsPosition(k propKey) Position {
 	v, ok := s.rules[k]
 	if !ok {
@@ -456,7 +465,27 @@ func (s Style) getBorderStyle() Border {
 	return noBorder
 }
 
-// Split a string into lines, additionally returning the size of the widest
+// GetBorderTitle returns border title if set, otherwise returns empty string.
+func (s Style) GetBorderTitle() string {
+	return s.getAsString(borderTitleKey)
+}
+
+// GetBorderTitleAlignment returns border title  alignment.
+func (s Style) GetBorderTitleAlignment() Position {
+	return s.getAsPosition(borderTitleAlignmentKey)
+}
+
+// GetBorderTitleBackground returns border title background  color.
+func (s Style) GetBorderTitleBackground() TerminalColor {
+	return s.getAsColor(borderTitleBackgroundKey)
+}
+
+// GetBorderTitleForeground returns border title foreground  color.
+func (s Style) GetBorderTitleForeground() TerminalColor {
+	return s.getAsColor(borderTitleForegroundKey)
+}
+
+// Split a string into lines, additionally returning the size of the widest.
 // line.
 func getLines(s string) (lines []string, widest int) {
 	lines = strings.Split(s, "\n")

set.go

@@ -454,6 +454,30 @@ func (s Style) BorderLeftBackground(c TerminalColor) Style {
 	return s
 }
 
+// BorderTitle set border title, which is displayed as part of the top border.
+func (s Style) BorderTitle(title string) Style {
+	s.set(borderTitleKey, title)
+	return s
+}
+
+// BorderTitleAlignment set border title alignment.
+func (s Style) BorderTitleAlignment(alignment Position) Style {
+	s.set(borderTitleAlignmentKey, alignment)
+	return s
+}
+
+// BorderTitleBackground set border title background color.
+func (s Style) BorderTitleBackground(color TerminalColor) Style {
+	s.set(borderTitleBackgroundKey, color)
+	return s
+}
+
+// BorderTitleForeground set border title background color.
+func (s Style) BorderTitleForeground(color TerminalColor) Style {
+	s.set(borderTitleForegroundKey, color)
+	return s
+}
+
 // Inline makes rendering output one line and disables the rendering of
 // margins, padding and borders. This is useful when you need a style to apply
 // only to font rendering and don't want it to change any physical dimensions.

style.go

@@ -65,6 +65,12 @@ const (
 	borderBottomBackgroundKey
 	borderLeftBackgroundKey
 
+	// Border title.
+	borderTitleKey
+	borderTitleAlignmentKey
+	borderTitleBackgroundKey
+	borderTitleForegroundKey
+
 	inlineKey
 	maxWidthKey
 	maxHeightKey