SDK contracts and attributes

namespace McBasic.ComponentSdk;

/// <summary>Declares a public C# control that can be packaged for McBasic.</summary>
[AttributeUsage(AttributeTargets.Class, AllowMultiple = false, Inherited = false)]
public sealed class McComponentAttribute : Attribute
{
    /// <summary>Declares stable component, BASIC and display identities.</summary>
    public McComponentAttribute(string id, string basicName, string displayName)
    {
        Id = id;
        BasicName = basicName;
        DisplayName = displayName;
    }

    /// <summary>Gets the globally qualified stable component identifier.</summary>
    public string Id { get; }
    /// <summary>Gets the type name exposed to BASIC.</summary>
    public string BasicName { get; }
    /// <summary>Gets the user-facing component name.</summary>
    public string DisplayName { get; }
    /// <summary>Gets or sets the Toolbox category.</summary>
    public string Category { get; set; } = "Custom Controls";
    /// <summary>The McBasic Component SDK contract version, not the package version.</summary>
    public string ApiVersion { get; set; } = McComponentSdkContract.CurrentApiVersion;
    /// <summary>Gets or sets whether the component has no visual surface.</summary>
    public bool NonVisual { get; set; }
    /// <summary>Gets or sets whether the component accepts McBasic visual children.</summary>
    public bool Container { get; set; }
    /// <summary>Gets or sets the help summary.</summary>
    public string Description { get; set; } = "";
    /// <summary>Optional package-relative icon path used by the metadata-only Toolbox.</summary>
    public string? Icon { get; set; }
    /// <summary>Optional package-relative documentation path used by help and signature UI.</summary>
    public string? Documentation { get; set; }
    /// <summary>Gets or sets the default design width in device-independent pixels.</summary>
    public double DefaultWidth { get; set; } = 160;
    /// <summary>Gets or sets the default design height in device-independent pixels.</summary>
    public double DefaultHeight { get; set; } = 32;
    /// <summary>Gets or sets whether the designer permits interactive resizing.</summary>
    public bool Resizable { get; set; } = true;
}

/// <summary>Exports a public C# property to the McBasic inspector.</summary>
[AttributeUsage(AttributeTargets.Property, AllowMultiple = false, Inherited = true)]
public sealed class McPropertyAttribute : Attribute
{
    /// <summary>Exports the CLR property using its CLR name.</summary>
    public McPropertyAttribute() { }
    /// <summary>Exports the CLR property using the specified BASIC name.</summary>
    public McPropertyAttribute(string name) => Name = name;
    /// <summary>Gets the optional BASIC name override.</summary>
    public string? Name { get; }
    /// <summary>Gets or sets the Inspector and Object Browser help text.</summary>
    public string Description { get; set; } = "";
    /// <summary>Gets or sets whether authored assignment is forbidden.</summary>
    public bool ReadOnly { get; set; }
    /// <summary>Gets or sets the default value encoded as JSON.</summary>
    public string? DefaultValueJson { get; set; }
    /// <summary>Gets or sets the reset value encoded as JSON.</summary>
    public string? ResetValueJson { get; set; }
    /// <summary>Gets or sets a registered SDK property-editor identifier.</summary>
    public string? Editor { get; set; }
}

/// <summary>Exports a public C# method to McBasic signature help.</summary>
[AttributeUsage(AttributeTargets.Method, AllowMultiple = false, Inherited = true)]
public sealed class McMethodAttribute : Attribute
{
    /// <summary>Exports the CLR method using its CLR name.</summary>
    public McMethodAttribute() { }
    /// <summary>Exports the CLR method using the specified BASIC name.</summary>
    public McMethodAttribute(string name) => Name = name;
    /// <summary>Gets the optional BASIC name override.</summary>
    public string? Name { get; }
    /// <summary>Gets or sets signature-help and Object Browser text.</summary>
    public string Description { get; set; } = "";
    /// <summary>Gets or sets whether the method uses the SDK async contract.</summary>
    public bool Async { get; set; }
}

/// <summary>Exports a public C# event to the McBasic event list.</summary>
[AttributeUsage(AttributeTargets.Event, AllowMultiple = false, Inherited = true)]
public sealed class McEventAttribute : Attribute
{
    /// <summary>Exports the CLR event using its CLR name.</summary>
    public McEventAttribute() { }
    /// <summary>Exports the CLR event using the specified BASIC name.</summary>
    public McEventAttribute(string name) => Name = name;
    /// <summary>Gets the optional BASIC name override.</summary>
    public string? Name { get; }
    /// <summary>Gets or sets event-editor and Object Browser text.</summary>
    public string Description { get; set; } = "";
}