Duit Maintainer

Quick Start

When implementing a new Flutter widget for the Duit library, follow this workflow:

1. Create attributes structure in pkg/duit_attributes/
2. Add widget type to pkg/duit_core/element_type.go
3. Add widget function in pkg/duit_widget/
4. Run code generation: make gogen
5. Write tests if required

Widget Implementation Workflow

Step 1: Create Attributes Structure

Create a new file in pkg/duit_attributes/ named {widget_name}_attributes.go:

go
1package duit_attributes
2
3import (
4    "errors"
5    "github.com/Duit-Foundation/duit_go/v4/pkg/duit_utils"
6)
7
8// WidgetNameAttributes defines attributes for WidgetName widget.
9// See: https://api.flutter.dev/flutter/widgets/WidgetName-class.html
10type WidgetNameAttributes struct {
11    *ValueReferenceHolder `gen:"wrap"`
12    *ThemeConsumer        `gen:"wrap"`
13    Property1             duit_utils.Tristate[bool] `json:"property1,omitempty"`
14    Property2             string                     `json:"property2,omitempty"`
15}
16
17// NewWidgetNameAttributes creates a new WidgetNameAttributes instance.
18func NewWidgetNameAttributes() *WidgetNameAttributes {
19    return &WidgetNameAttributes{}
20}
21
22// SetProperty1 sets the property1 and returns WidgetNameAttributes for method chaining.
23func (r *WidgetNameAttributes) SetProperty1(property1 bool) *WidgetNameAttributes {
24    r.Property1 = duit_utils.BoolValue(property1)
25    return r
26}
27
28// SetProperty2 sets the property2 and returns WidgetNameAttributes for method chaining.
29func (r *WidgetNameAttributes) SetProperty2(property2 string) *WidgetNameAttributes {
30    r.Property2 = property2
31    return r
32}
33
34//bindgen:exclude
35func (r *WidgetNameAttributes) Validate() error {
36    if err := r.ValueReferenceHolder.Validate(); err != nil {
37        return err
38    }
39
40    if err := r.ThemeConsumer.Validate(); err != nil {
41        return err
42    }
43
44    if r.Property1 == nil {
45        return errors.New("property1 is required")
46    }
47
48    return nil
49}

Rules:

• Use *ValueReferenceHolder with gen:"wrap" tag
• Use *ThemeConsumer with gen:"wrap" tag
• Use duit_utils.Tristate[T] for optional boolean properties
• Add json:"propertyName,omitempty" tag for all fields
• Method receiver must be named r
• Add //bindgen:exclude comment to Validate() method
• Documentation must be in English

Step 2: Add Widget Type

Add a constant to pkg/duit_core/element_type.go:

go
1const (
2    // ... existing types
3    WidgetName DuitElementType = "WidgetName"
4)

Follow naming convention: Use PascalCase with no spaces or underscores.

Step 3: Add Widget Function

Create a new file in pkg/duit_widget/ named {widget_name}.go:

go
1package duit_widget
2
3import (
4    "github.com/Duit-Foundation/duit_go/v4/pkg/duit_attributes"
5    "github.com/Duit-Foundation/duit_go/v4/pkg/duit_core"
6)
7
8/*
9Example:
10    WidgetName(
11        duit_attributes.NewWidgetNameAttributes().
12            SetProperty1(true).
13            SetProperty2("value"),
14        "id",
15        false,
16        nil,
17    )
18*/
19func WidgetName(attributes *duit_attributes.WidgetNameAttributes, id string, controlled bool, child *duit_core.DuitElementModel) *duit_core.DuitElementModel {
20    checkAttributes(attributes)
21    return new(duit_core.DuitElementModel).CreateElement(duit_core.WidgetName, id, "", attributes, nil, controlled, 1, nil, child)
22}

Function signature patterns:

• Single child: func WidgetName(attributes *Attrs, id string, controlled bool, child *DuitElementModel) *DuitElementModel
• Multiple children: func WidgetName(attributes *Attrs, id string, controlled bool, children []*DuitElementModel) *DuitElementModel
• Optional child: func WidgetName(attributes *Attrs, id string, child *DuitElementModel) *DuitElementModel

CreateElement parameters:

1. Widget type constant
2. ID string
3. Tag string (empty for most widgets)
4. Attributes
5. Commands (nil for most widgets)
6. Controlled boolean
7. Children count (use 2 for widgets with optional child like Visibility)
8. Nil (reserved)
9. Children (variadic)

Rules:

• Always call checkAttributes(attributes) to validate
• Use new(DuitElementModel).CreateElement(...)
• Add example usage in comment

Step 4: Run Code Generation

bash
1make gogen

This generates embedded struct delegates and other boilerplate code.

Step 5: Write Tests

Only write tests when explicitly required. When required, create {widget_name}_attributes_test.go in pkg/duit_attributes/:

go
1package duit_attributes_test
2
3import (
4    "testing"
5
6    "github.com/Duit-Foundation/duit_go/v4/pkg/duit_attributes"
7)
8
9func TestWidgetNameAttributes_Validate_ValidAttributes(t *testing.T) {
10    attrs := &duit_attributes.WidgetNameAttributes{
11        Property1: duit_utils.BoolValue(true),
12    }
13
14    err := attrs.Validate()
15    if err != nil {
16        t.Fatal("expected no error for valid attributes, got:", err)
17    }
18}
19
20func TestWidgetNameAttributes_Validate_MissingRequiredProperty(t *testing.T) {
21    attrs := &duit_attributes.WidgetNameAttributes{
22        Property1: nil, // missing required property
23    }
24
25    err := attrs.Validate()
26    if err == nil {
27        t.Fatal("expected error for missing required property")
28    }
29}
30
31func TestWidgetNameAttributes_SetProperty1(t *testing.T) {
32    attrs := duit_attributes.NewWidgetNameAttributes()
33    property1 := true
34
35    result := attrs.SetProperty1(property1)
36
37    if *attrs.Property1 != property1 {
38        t.Fatalf("expected Property1 to be %v, got: %v", property1, attrs.Property1)
39    }
40
41    if result != attrs {
42        t.Fatal("expected SetProperty1 to return same instance for method chaining")
43    }
44}

Testing rules:

• Test filename: {target_file}_test.go
• Only test properties explicitly used in structure's methods
• Always test Tristate[T] properties for JSON serialization
• Never check error text, only check if error exists
• Never cover embedded fields or embedded structs
• Test setter methods return same instance for chaining

Code Review Checklist

When reviewing widget implementations, check:

• Receiver name is r for all structure methods
• Documentation is in English
• Method chaining returns same instance (return r)
• Required properties validated in Validate() method
• Validate() has //bindgen:exclude comment
• checkAttributes() called in widget function
• Widget type follows naming convention (PascalCase)
• Attributes use appropriate types (Tristate[T] for optionals)
• JSON tags use omitempty suffix
• Example usage comment present in widget file
• Nil checks for potentially nil receivers before method calls

Coding Conventions

Style Rules

From pkg/.cursor/rules/style.mdc:

1. Method receiver name must always be "r"
2. Documentation must be in English
3. Explicit nil checks for potentially nil receivers

Testing Rules

From pkg/.cursor/rules/testing.mdc:

1. Never cover embedded fields or embedded structs with tests
2. Always add tests for Tristate[T] properties (JSON serialization)
3. Test filename: {target_file}_test.go
4. Only test properties explicitly used in structure's methods
5. Never check error text, only check if error exists

Flutter Documentation Reference

Always reference official Flutter documentation in attributes structure:

go
1// See: https://api.flutter.dev/flutter/widgets/WidgetName-class.html

Common Patterns

Required Properties

go
1if r.RequiredProperty == nil {
2    return errors.New("requiredProperty is required")
3}

Optional Properties (Tristate)

go
1type WidgetAttributes struct {
2    OptionalProperty duit_utils.Tristate[bool] `json:"optionalProperty,omitempty"`
3}
4
5// SetOptionalProperty sets the optional property.
6func (r *WidgetAttributes) SetOptionalProperty(optional bool) *WidgetAttributes {
7    r.OptionalProperty = duit_utils.BoolValue(optional)
8    return r
9}

String Properties

go
1type WidgetAttributes struct {
2    TextProperty string `json:"textProperty,omitempty"`
3}
4
5// SetTextProperty sets the text property.
6func (r *WidgetAttributes) SetTextProperty(text string) *WidgetAttributes {
7    r.TextProperty = text
8    return r
9}

Nil-Safe Method Calls

go
1func SomeFunction(widget *DuitElementModel) {
2    if widget == nil {
3        return
4    }
5    widget.SomeMethod()
6}

Makefile Commands

bash
1# Generate code
2make gogen
3
4# Run tests
5make test
6
7# Run vet
8make vet

Always run make gogen after adding new widgets.

Troubleshooting

Code generation fails

• Check that gen:"wrap" tags are present for embedded structs
• Verify attribute struct has no syntax errors
• Ensure all referenced types are imported

Tests fail

• Check that required properties are set in test
• Verify Tristate properties are tested for JSON serialization
• Ensure error checks don't compare error text

Widget not recognized

• Verify type is added to element_type.go
• Check type name matches exactly in widget function
• Run make gogen to regenerate delegates