feat: finalize multi-section support

Author: mmonterroca

builder.go

@@ -54,6 +54,133 @@ type DocumentBuilder struct {
 	errors []error
 }
 
+// SectionBuilder provides a fluent API for configuring document sections.
+type SectionBuilder struct {
+	section domain.Section
+	parent  *DocumentBuilder
+	err     error
+}
+
+func (sb *SectionBuilder) recordError(err error) {
+	if err == nil {
+		return
+	}
+	if sb.err == nil {
+		sb.err = err
+	}
+	if sb.parent != nil {
+		sb.parent.errors = append(sb.parent.errors, err)
+	}
+}
+
+func (sb *SectionBuilder) ensureSection(op string) bool {
+	if sb == nil {
+		return false
+	}
+	if sb.err != nil {
+		return false
+	}
+	if sb.section == nil {
+		sb.recordError(errors.InvalidState(op, "section is nil"))
+		return false
+	}
+	return true
+}
+
+// PageSize sets the page size for the section.
+
+func (sb *SectionBuilder) PageSize(size domain.PageSize) *SectionBuilder {
+	if !sb.ensureSection("SectionBuilder.PageSize") {
+		return sb
+	}
+
+	if err := sb.section.SetPageSize(size); err != nil {
+		sb.recordError(err)
+	}
+	return sb
+}
+
+// Orientation sets the page orientation for the section.
+func (sb *SectionBuilder) Orientation(orient domain.Orientation) *SectionBuilder {
+	if !sb.ensureSection("SectionBuilder.Orientation") {
+		return sb
+	}
+	if err := sb.section.SetOrientation(orient); err != nil {
+		sb.recordError(err)
+	}
+	return sb
+}
+
+// Margins sets the page margins for the section.
+func (sb *SectionBuilder) Margins(margins domain.Margins) *SectionBuilder {
+	if !sb.ensureSection("SectionBuilder.Margins") {
+		return sb
+	}
+	if err := sb.section.SetMargins(margins); err != nil {
+		sb.recordError(err)
+	}
+	return sb
+}
+
+// Columns sets the column layout for the section.
+func (sb *SectionBuilder) Columns(count int) *SectionBuilder {
+	if !sb.ensureSection("SectionBuilder.Columns") {
+		return sb
+	}
+	if err := sb.section.SetColumns(count); err != nil {
+		sb.recordError(err)
+	}
+	return sb
+}
+
+// Header returns the requested header for direct manipulation.
+func (sb *SectionBuilder) Header(headerType domain.HeaderType) (domain.Header, error) {
+	if sb == nil {
+		return nil, errors.InvalidState("SectionBuilder.Header", "section is nil")
+	}
+	if !sb.ensureSection("SectionBuilder.Header") {
+		return nil, sb.err
+	}
+	head, err := sb.section.Header(headerType)
+	if err != nil {
+		sb.recordError(err)
+		return nil, err
+	}
+	return head, nil
+}
+
+// Footer returns the requested footer for direct manipulation.
+func (sb *SectionBuilder) Footer(footerType domain.FooterType) (domain.Footer, error) {
+	if sb == nil {
+		return nil, errors.InvalidState("SectionBuilder.Footer", "section is nil")
+	}
+	if !sb.ensureSection("SectionBuilder.Footer") {
+		return nil, sb.err
+	}
+	foot, err := sb.section.Footer(footerType)
+	if err != nil {
+		sb.recordError(err)
+		return nil, err
+	}
+	return foot, nil
+}
+
+// Section exposes the underlying domain.Section for advanced scenarios.
+func (sb *SectionBuilder) Section() domain.Section {
+	if sb == nil {
+		return nil
+	}
+	return sb.section
+}
+
+// End returns control to the DocumentBuilder.
+func (sb *SectionBuilder) End() *DocumentBuilder {
+	if sb == nil {
+		return nil
+	}
+	return sb.parent
+}
+
 // NewDocumentBuilder creates a new document builder with optional configuration.
 //
 // Example:
@@ -131,6 +258,39 @@ func (b *DocumentBuilder) AddTable(rows, cols int) *TableBuilder {
 	}
 }
 
+// DefaultSection returns a SectionBuilder for configuring the document's default section.
+// Errors are accumulated and surfaced during Build().
+func (b *DocumentBuilder) DefaultSection() *SectionBuilder {
+	section, err := b.doc.DefaultSection()
+	sb := &SectionBuilder{
+		section: section,
+		parent:  b,
+	}
+	if err != nil {
+		sb.recordError(err)
+	}
+	return sb
+}
+
+// AddSection inserts a new section with the specified break type (default NextPage).
+// Returns a SectionBuilder for configuring the new section.
+func (b *DocumentBuilder) AddSection(breakType ...domain.SectionBreakType) *SectionBuilder {
+	bt := domain.SectionBreakTypeNextPage
+	if len(breakType) > 0 {
+		bt = breakType[0]
+	}
+
+	section, err := b.doc.AddSectionWithBreak(bt)
+	sb := &SectionBuilder{
+		section: section,
+		parent:  b,
+	}
+	if err != nil {
+		sb.recordError(err)
+	}
+	return sb
+}
+
 // SetMetadata sets the document metadata.
 func (b *DocumentBuilder) SetMetadata(meta *domain.Metadata) *DocumentBuilder {
 	if err := b.doc.SetMetadata(meta); err != nil {

builder_test.go

@@ -51,6 +51,129 @@ func TestDocumentBuilder_Build(t *testing.T) {
 	})
 }
 
+func TestDocumentBuilder_Sections(t *testing.T) {
+	t.Run("configures default section", func(t *testing.T) {
+		builder := NewDocumentBuilder()
+		builder.DefaultSection().
+			PageSize(domain.PageSizeA4).
+			Orientation(domain.OrientationLandscape).
+			Margins(domain.Margins{Top: 720, Right: 1440, Bottom: 720, Left: 1440, Header: 360, Footer: 360}).
+			Columns(2).
+			End()
+		builder.AddParagraph().Text("section content").End()
+
+		doc, err := builder.Build()
+		if err != nil {
+			t.Fatalf("expected no error, got %v", err)
+		}
+
+		sections := doc.Sections()
+		if len(sections) != 1 {
+			t.Fatalf("expected 1 section, got %d", len(sections))
+		}
+
+		sec := sections[0]
+		if sec.PageSize() != domain.PageSizeA4 {
+			t.Errorf("expected A4 page size, got %+v", sec.PageSize())
+		}
+		if sec.Orientation() != domain.OrientationLandscape {
+			t.Errorf("expected landscape orientation, got %v", sec.Orientation())
+		}
+		if sec.Columns() != 2 {
+			t.Errorf("expected 2 columns, got %d", sec.Columns())
+		}
+		m := sec.Margins()
+		if m.Top != 720 || m.Bottom != 720 || m.Header != 360 || m.Footer != 360 {
+			t.Errorf("unexpected margins %+v", m)
+		}
+	})
+
+	t.Run("adds additional section with break", func(t *testing.T) {
+		builder := NewDocumentBuilder()
+		builder.AddParagraph().Text("Before section break").End()
+
+		builder.AddSection(domain.SectionBreakTypeEvenPage).
+			Columns(3).
+			Orientation(domain.OrientationPortrait).
+			End()
+
+		builder.AddParagraph().Text("After section break").End()
+
+		doc, err := builder.Build()
+		if err != nil {
+			t.Fatalf("expected no error, got %v", err)
+		}
+
+		sections := doc.Sections()
+		if len(sections) != 2 {
+			t.Fatalf("expected 2 sections, got %d", len(sections))
+		}
+		if sections[1].Columns() != 3 {
+			t.Errorf("expected 3 columns on second section, got %d", sections[1].Columns())
+		}
+
+		blocks := doc.Blocks()
+		foundBreak := false
+		for _, block := range blocks {
+			if block.SectionBreak != nil {
+				foundBreak = true
+				if block.SectionBreak.Type != domain.SectionBreakTypeEvenPage {
+					t.Errorf("expected even page break, got %v", block.SectionBreak.Type)
+				}
+			}
+		}
+		if !foundBreak {
+			t.Fatalf("expected section break block in document")
+		}
+	})
+
+	t.Run("records errors when section configuration fails", func(t *testing.T) {
+		builder := NewDocumentBuilder()
+		builder.DefaultSection().Columns(0).End()
+
+		if _, err := builder.Build(); err == nil {
+			t.Fatal("expected error due to invalid column count, got nil")
+		}
+	})
+
+	t.Run("configures header via section builder", func(t *testing.T) {
+		builder := NewDocumentBuilder()
+		secBuilder := builder.DefaultSection()
+		header, err := secBuilder.Header(domain.HeaderDefault)
+		if err != nil {
+			t.Fatalf("expected header, got error %v", err)
+		}
+
+		para, err := header.AddParagraph()
+		if err != nil {
+			t.Fatalf("expected paragraph in header, got %v", err)
+		}
+		run, err := para.AddRun()
+		if err != nil {
+			t.Fatalf("expected run in header paragraph, got %v", err)
+		}
+		if err := run.SetText("Header text"); err != nil {
+			t.Fatalf("expected to set header text, got %v", err)
+		}
+
+		secBuilder.End()
+		builder.AddParagraph().Text("body content").End()
+		doc, err := builder.Build()
+		if err != nil {
+			t.Fatalf("expected no error, got %v", err)
+		}
+
+		section := doc.Sections()[0]
+		storedHeader, err := section.Header(domain.HeaderDefault)
+		if err != nil {
+			t.Fatalf("expected header from section, got %v", err)
+		}
+		if len(storedHeader.Paragraphs()) == 0 {
+			t.Fatal("expected header to contain paragraphs")
+		}
+	})
+}
+
 func TestParagraphBuilder_Text(t *testing.T) {
 	t.Run("adds single text run", func(t *testing.T) {
 		builder := NewDocumentBuilder()