// Licensed to the .NET Foundation under one or more agreements.
// The .NET Foundation licenses this file to you under the MIT license.

namespace Microsoft.AspNetCore.Html
{
    /// <summary>
    /// A builder for HTML content.
    /// </summary>
    public interface IHtmlContentBuilder : IHtmlContentContainer
    {
        /// <summary>
        /// Appends an <see cref="IHtmlContent"/> instance.
        /// </summary>
        /// <param name="content">The <see cref="IHtmlContent"/> to append.</param>
        /// <returns>The <see cref="IHtmlContentBuilder"/>.</returns>
        IHtmlContentBuilder AppendHtml(IHtmlContent content);

        /// <summary>
        /// Appends a <see cref="string"/> value. The value is treated as unencoded as-provided, and will be HTML
        /// encoded before writing to output.
        /// </summary>
        /// <param name="unencoded">The <see cref="string"/> to append.</param>
        /// <returns>The <see cref="IHtmlContentBuilder"/>.</returns>
        IHtmlContentBuilder Append(string unencoded);

        /// <summary>
        /// Appends an HTML encoded <see cref="string"/> value. The value is treated as HTML encoded as-provided, and
        /// no further encoding will be performed.
        /// </summary>
        /// <param name="encoded">The HTML encoded <see cref="string"/> to append.</param>
        /// <returns>The <see cref="IHtmlContentBuilder"/>.</returns>
        IHtmlContentBuilder AppendHtml(string encoded);

        /// <summary>
        /// Clears the content.
        /// </summary>
        /// <returns>The <see cref="IHtmlContentBuilder"/>.</returns>
        IHtmlContentBuilder Clear();
    }
}
