using System.Text.Json.Serialization;

namespace Elternbeirat.Contracts;

/// <summary>
///     A topic the FAQ entries are grouped under, as stored in PocketBase.
/// </summary>
/// <remarks>
///     A <see cref="Faq"/> points at its topic through a relation, so the FAQ page
///     groups the questions by topic and shows the groups in <see cref="Order"/>.
///     Making the topic its own record (rather than a free-text field on each
///     question) means the heading, its order and its optional <see cref="Intro"/>
///     are edited in one place and shared by every question in the group.
/// </remarks>
public record FaqTopic
{
    /// <summary>
    ///     Gets the PocketBase record id.
    /// </summary>
    /// <remarks>
    ///     <see langword="required"/>: every stored record has an id. Modeling it as
    ///     required states which fields a record must carry, independent of the store,
    ///     so a future data source has to supply them too.
    /// </remarks>
    [JsonPropertyName("id")]
    public required string Id { get; init; }

    /// <summary>
    ///     Gets the heading shown above the group of questions, e.g.
    ///     <c>"Mensa und Mittagessen"</c>.
    /// </summary>
    /// <remarks>
    ///     Free text; may contain umlauts and spaces. For the URL, see <see cref="Slug"/>.
    ///     <see langword="required"/>: a topic without a heading has nothing to show, and
    ///     the field is required in PocketBase.
    /// </remarks>
    [JsonPropertyName("title")]
    public required string Title { get; init; }

    /// <summary>
    ///     Gets the URL slug of the topic, e.g. <c>"mensa"</c>.
    /// </summary>
    /// <value>
    ///     A URL path segment: lowercase letters, digits and single hyphens as
    ///     separators, no umlauts. PocketBase enforces this on save via a field
    ///     pattern (<c>^[a-z0-9]+(-[a-z0-9]+)*$</c>), so every stored slug is already
    ///     canonical and the app can use it verbatim.
    /// </value>
    /// <remarks>
    ///     <see langword="required"/>: the slug is required in PocketBase and is the
    ///     stable identifier of a topic, independent of its display title.
    /// </remarks>
    [JsonPropertyName("slug")]
    public required string Slug { get; init; }

    /// <summary>
    ///     Gets the optional introduction shown below the topic heading, as Markdown.
    /// </summary>
    /// <value>
    ///     The intro Markdown, or an empty string when the topic has none.
    /// </value>
    [JsonPropertyName("intro")]
    public string Intro { get; init; } = string.Empty;

    /// <summary>
    ///     Gets the sort order of the topic among the FAQ groups.
    /// </summary>
    /// <value>
    ///     The sort key; topics with smaller values appear first.
    /// </value>
    [JsonPropertyName("order")]
    public double Order { get; init; }
}