Choose the minimum useful reading surface
For the illustrative hiking app, a card should help a reader decide whether to open a historical reference. Start with available text, source context, date and a usable link. The API returns flat records, not a ready-made card model, and it does not guarantee that every chosen field is present. Build a small adapter between those records and your screen.
Treat source identity separately from display text. A record id can help your app track an item when present, but a title or snippet is not a reliable replacement for identity. Do not merge different records because they discuss the same phrase. Keep the original data available to your adapter without exposing service credentials or debugging internals in the card.
Do not guess a missing kind or title
Use a valid kind value when one is available: post and comment support different labels. If the kind is absent or unrecognized, use a neutral Archived record label. Do not default every unknown record to a comment or imply that an isolated comment represents its entire parent discussion.
Consider a proposed fixture with kind=comment, readable text, no title and no usable source link. Its card can say Comment and Source link unavailable, followed by the text. It does not need a generated headline or a fabricated URL. Another fixture might have a long post title; allow it to wrap, or provide a clear way to expand it. These are testing examples, not records claimed to exist in the archive.
Render prose as untrusted content
Render untrusted prose with safe escaping before inserting it into the interface. Preserve meaningful paragraph breaks, but do not treat arbitrary record content as HTML instructions. If you later add Markdown support, choose and test a restricted rendering policy. Plain-text rendering is a valid first version and avoids promising a formatting feature you have not implemented.
Validate a source link before making it actionable, and handle a missing or unusable value as missing. Clearly label where an external link leads. Keep a readable text label for actions, keyboard access and a sensible focus order. A tooltip alone is not enough to explain an unavailable date or link to every reader.
Keep dates and conversation context honest
If a usable creation timestamp is present, show its meaning and formatting consistently. Otherwise state Date unavailable. Do not copy the parent post’s timestamp onto a comment: the two pieces of content need not have been created together. A retrieval date recorded by your app describes fetching, not the original discussion’s age.
When parent_id or link_id is present, local grouping may connect records already in your result set. Their presence does not recover absent ancestors, establish a complete thread or provide a new query filter. The current API exposes no parent_id or link_id filter. A card can acknowledge missing context without constructing a pretend conversation.
Keep list controls outside the card adapter
List-level pagination should read pagination.has_more and respect the page cap. Do not enable or disable Show more solely because pagination.relation is eq or gte: that relation describes the total, not the continuation control. A lower-bound or unknown total is also not proof that the visible records themselves are invalid.
A successful empty data array belongs to the list’s empty state, not an error card; it still costs one retrieval credit. In the proposed fixture review, include a long title, missing text, missing date, unusable link and unknown kind, then inspect how the layout behaves on a narrow screen. These are checks for your future implementation, not tests performed by this guide. Return to /en/#field-notes for source-age and state-design notes.
