using System.Text.Json.Serialization;

namespace Elternbeirat.Contracts;

/// <summary>
///     A content page of the site, as stored in PocketBase.
/// </summary>
/// <remarks>
///     Pages also drive the site navigation: <see cref="Location"/> and
///     <see cref="Order"/> decide where and in which order a page appears in the
///     header or footer menu. <see cref="Embed"/> lists dynamic blocks rendered
///     below the page body.
/// </remarks>
public record Page
{
    /// <summary>
    ///     The slug of the home page, which is served at the site root <c>/</c> rather
    ///     than at <c>/home</c>. Reserved: no other page may use it.
    /// </summary>
    private const string HomeSlug = "home";

    /// <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 to visitors.
    /// </summary>
    /// <remarks>
    ///     Free text; may contain umlauts and spaces. For the URL, see <see cref="Slug"/>.
    ///     <see langword="required"/>: a page without a heading is incomplete, and the
    ///     field is required in PocketBase.
    /// </remarks>
    [JsonPropertyName("title")]
    public required string Title { get; init; }

    /// <summary>
    ///     Gets the page body as Markdown.
    /// </summary>
    [JsonPropertyName("body")]
    public string Body { get; init; } = string.Empty;

    /// <summary>
    ///     Gets the navigation menu the page appears in.
    /// </summary>
    /// <value>
    ///     Either <c>"header"</c> or <c>"footer"</c>.
    /// </value>
    /// <remarks>
    ///     <see langword="required"/>: the navigation is built from this, and the field
    ///     is required in PocketBase, so every page belongs to one of the two menus.
    /// </remarks>
    [JsonPropertyName("location")]
    public required string Location { get; init; }

    /// <summary>
    ///     Gets the sort order within the navigation menu given by <see cref="Location"/>.
    /// </summary>
    /// <value>
    ///     The sort key; pages with smaller values appear first.
    /// </value>
    [JsonPropertyName("order")]
    public double Order { get; init; }

    /// <summary>
    ///     Gets the URL slug of the page, e.g. <c>"board"</c> for <c>/board</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 in comparisons and generated URLs.
    /// </value>
    /// <remarks>
    ///     <see langword="required"/>: the slug is how a page is addressed, so a record
    ///     without one is broken. It is a required field in PocketBase, so deserializing
    ///     one that lacks it should fail loudly rather than yield a page with no URL.
    /// </remarks>
    [JsonPropertyName("slug")]
    public required string Slug { get; init; }

    /// <summary>
    ///     Gets the dynamic blocks rendered below the <see cref="Body"/>.
    /// </summary>
    /// <value>
    ///     Any of <c>"posts"</c> and <c>"events"</c>, or an empty list for a plain
    ///     text page.
    /// </value>
    [JsonPropertyName("embed")]
    public IReadOnlyList<string> Embed { get; init; } = [];

    /// <summary>
    ///     Tests whether a slug is the home page's. This is the single definition of
    ///     that comparison, so every caller identifies the home page the same way.
    /// </summary>
    /// <remarks>
    ///     An ordinal (case-sensitive) comparison is enough because slugs are always
    ///     lowercase: PocketBase enforces that with a field pattern (see
    ///     <see cref="Slug"/>), and this is only ever called with a stored slug.
    /// </remarks>
    /// <param name="slug">
    ///     The slug to test, e.g. from <see cref="Slug"/>.
    /// </param>
    /// <returns>
    ///     <see langword="true"/> if <paramref name="slug"/> is the home page's slug.
    /// </returns>
    public static bool IsHomeSlug(string slug) =>
        string.Equals(slug, HomeSlug, StringComparison.Ordinal);
}