/// <summary>
///     Builder for defining bit sub-fields within a <see cref = "FieldType.BitField"/>.
/// </summary>
public sealed class BitFieldBuilder
{
#region Fields
    private readonly List<BitFieldDefinition> _bits = [];
#endregion
#region Methods
    /// <summary>Adds a single-bit flag.</summary>
    public BitFieldBuilder Flag(string name, int bitPosition)
    {
        _bits.Add(new BitFieldDefinition(name, bitPosition, 1));
        return this;
    }

    /// <summary>Adds a multi-bit field.</summary>
    public BitFieldBuilder Bits(string name, int startBit, int bitCount)
    {
        _bits.Add(new BitFieldDefinition(name, startBit, bitCount));
        return this;
    }

    /// <summary>Adds a multi-bit field with enum value mappings.</summary>
    public BitFieldBuilder Bits(string name, int startBit, int bitCount, params (int Value, string Label)[] values)
    {
        var enumValues = ImmutableDictionary.CreateRange(values.Select(v => KeyValuePair.Create(v.Value, v.Label)));
        _bits.Add(new BitFieldDefinition(name, startBit, bitCount, enumValues));
        return this;
    }

    /// <summary>Builds the immutable array of bit field definitions.</summary>
    internal ImmutableArray<BitFieldDefinition> Build() => [.._bits];
#endregion
}