MetaJson.cs

using System.Text.Json;
using System.Text.Json.Serialization;

namespace ShellDocs.Core;

public class MetaJson
{
    [JsonPropertyName("title")]
    public string? Title { get; set; }

    [JsonPropertyName("pages")]
    public List<MetaJsonEntry> Pages { get; set; } = new();

    // Slugs of pages or subfolders that should route (URLs resolve) but not
    // appear in the sidebar tree. Useful for landing pages reached only via
    // the package selector, private drafts, or archived content.
    [JsonPropertyName("hidden")]
    public List<string> Hidden { get; set; } = new();

    private static readonly JsonSerializerOptions Options = new()
    {
        PropertyNameCaseInsensitive = true,
        ReadCommentHandling = JsonCommentHandling.Skip,
        AllowTrailingCommas = true,
        Converters = { new MetaJsonEntryConverter() }
    };

    public static MetaJson? Parse(string json)
    {
        if (string.IsNullOrWhiteSpace(json)) return null;
        return JsonSerializer.Deserialize<MetaJson>(json, Options);
    }
}

public abstract class MetaJsonEntry { }
public class MetaJsonPageRef : MetaJsonEntry { public required string Slug { get; init; } }
public class MetaJsonDivider : MetaJsonEntry { }
public class MetaJsonSubsection : MetaJsonEntry
{
    public required string Title { get; init; }
    public List<MetaJsonEntry> Pages { get; init; } = new();
}

/*
    Each entry in meta.json's "pages" array can be:
      - a string slug ("button")
      - the literal "---" for a section divider
      - an object { "title": "Data Display", "pages": [...] } for a subsection
    Custom converter dispatches on the JSON token type.
*/
internal class MetaJsonEntryConverter : JsonConverter<MetaJsonEntry>
{
    public override MetaJsonEntry? Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
    {
        if (reader.TokenType == JsonTokenType.String)
        {
            var value = reader.GetString() ?? "";
            return value == "---" ? new MetaJsonDivider() : new MetaJsonPageRef { Slug = value };
        }

        if (reader.TokenType == JsonTokenType.StartObject)
        {
            using var doc = JsonDocument.ParseValue(ref reader);
            var root = doc.RootElement;
            var title = root.TryGetProperty("title", out var t) ? t.GetString() ?? "" : "";
            var pages = new List<MetaJsonEntry>();
            if (root.TryGetProperty("pages", out var p) && p.ValueKind == JsonValueKind.Array)
            {
                foreach (var el in p.EnumerateArray())
                {
                    var elJson = el.GetRawText();
                    var childReader = new Utf8JsonReader(System.Text.Encoding.UTF8.GetBytes(elJson));
                    childReader.Read();
                    var child = Read(ref childReader, typeof(MetaJsonEntry), options);
                    if (child is not null) pages.Add(child);
                }
            }
            return new MetaJsonSubsection { Title = title, Pages = pages };
        }

        throw new JsonException($"Unexpected token {reader.TokenType} in meta.json entry.");
    }

    public override void Write(Utf8JsonWriter writer, MetaJsonEntry value, JsonSerializerOptions options)
        => throw new NotSupportedException("Writing meta.json entries not supported.");
}