Group FAQs by a topic relation, ordered; drop unused FAQ teaser

Elternbeirat.Contracts/Faq.cs

@@ -6,7 +6,9 @@ namespace Elternbeirat.Contracts;
 ///     A single question and answer of the FAQ, as stored in PocketBase.
 /// </summary>
 /// <remarks>
-///     On the FAQ page, entries are grouped by <see cref="Topic"/>.
+///     On the FAQ page, entries are grouped by their <see cref="Topic"/>. The topic is
+///     a PocketBase relation; <see cref="Topic"/> is the resolved topic record, present
+///     only when the query expanded the relation (see <see cref="FaqExpand"/>).
 /// </remarks>
 public record Faq
 {
@@ -42,17 +44,39 @@ public record Faq
     public required string Answer { get; init; }
 
     /// <summary>
-    ///     Gets the topic the question is grouped under, e.g.
-    ///     <c>"Mensa und Mittagessen"</c>.
+    ///     Gets the expanded relations returned by PocketBase, or <see langword="null"/>
+    ///     when the query did not expand any.
+    /// </summary>
+    [JsonPropertyName("expand")]
+    public FaqExpand? Expand { get; init; }
+
+    /// <summary>
+    ///     Gets the resolved topic this entry is grouped under, or <see langword="null"/>
+    ///     when the query did not expand the topic relation.
     /// </summary>
     /// <remarks>
-    ///     <see langword="required"/>: the FAQ page groups entries by topic, so an entry
-    ///     without one has no place. The field is required in PocketBase.
-    ///
-    ///     This is the heading shown on the page verbatim, not a slug: editors add a
-    ///     new group by typing its heading here, no code change. Entries with the same
-    ///     topic text land in one group.
+    ///     Convenience over <see cref="Expand"/>: the FAQ page reads the grouping
+    ///     heading from here. It is <see langword="null"/> unless the entry was loaded
+    ///     with the topic relation expanded.
     /// </remarks>
+    [JsonIgnore]
+    public FaqTopic? Topic => Expand?.Topic;
+}
+
+/// <summary>
+///     The relations of a <see cref="Faq"/> that PocketBase returns under
+///     <c>expand</c> when the query asks for them.
+/// </summary>
+/// <remarks>
+///     One property per expandable relation, named after its PocketBase field, so the
+///     JSON <c>expand</c> object maps straight onto it. <see cref="Faq.Topic"/> reads
+///     through this.
+/// </remarks>
+public record FaqExpand
+{
+    /// <summary>
+    ///     Gets the expanded topic of the <c>topic</c> relation, if it was expanded.
+    /// </summary>
     [JsonPropertyName("topic")]
-    public required string Topic { get; init; }
+    public FaqTopic? Topic { get; init; }
 }

Elternbeirat.Contracts/FaqTopic.cs

@@ -0,0 +1,73 @@
+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; }
+}

Elternbeirat.Contracts/Page.cs

@@ -90,8 +90,8 @@ public record Page
     ///     Gets the dynamic blocks rendered below the <see cref="Body"/>.
     /// </summary>
     /// <value>
-    ///     Any of <c>"posts"</c>, <c>"events"</c> and <c>"faqs"</c>, or an empty list
-    ///     for a plain text page.
+    ///     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; } = [];