Documents Carousel — Feed & Adapter Requirements

Updated: 2026-08-26 09:55 ET · Feature: AB#2580 "Document Module" (Epic AB#1821 UI Refresh / dynamic-feed AB#2133) · Prepared: 2026-08-25 · Prepared by: Claude Code, with Jose Castro

TLDR

• Decided direction (2026-08-25): the target is a new carousel section inside the existing MEC/LEC DocumentsHub — not the ALPA/"ALP MAG" carousel that already exists on the separate /home surface, which stays untouched.
• No new "Document Component" module needed. DocumentsHub.razor already is the orchestrator (it composes multiple <DocumentsBrowser> sections today); DocumentsBrowser already is the adapter/loader (it fetches, filters, sorts, and maps DocumentItem per section). Adding a carousel section is a new DocumentsBrowserPresentation value plus one new composition call in the hub — see §5.
• The Carousel UI itself is already built and does not need touching: CarouselViewModel → Carousel.razor, and the per-item adapter (DocumentItem → CardHeroViewModel) already exists as DocumentHeroFactory, just not yet called from DocumentsBrowser.
• The live feed has real data-quality gaps that affect MEC/LEC scopes directly: zero images across every sampled document (confirmed twice, six weeks apart) and duplicate MEC/LEC scope nodes that BUG-1995 was once thought to silently drop. Both are resolved as of 2026-08-26 — no backend fix required for either. Image gap: CardHero is being refactored to auto-hide its image area on a missing/failed image, matching the pattern CardText/CardSmall/PromoBanner already use (§2.5). Scope-dedup: live-reconfirmed on a real production account that the composite-key fix (AB#2208, shipped 2026-07-06) already preserves every category/document under duplicate-named scope nodes — the 2026-08-25 "ALPA empty" finding does not reproduce and was most likely a transient backend 503, not a dedup regression (§4, §6 #3).

1. Context — AB#2580

AB#2580 "Document Module" (Task, State: New, assigned Alejandro Acevedo) reads:

"The attached payload will be loaded in the background to cache the data. Then, using this data structure from the cache, the Document Module will implement data helping UI to be rendered. What is the endpoint this JSON payload will be retrieved from? Is the endpoint live or must it be mocked for now?"

All three parts of the description are already answered by the existing codebase — the two explicit questions, and the background-caching behavior the paragraph opens with:

AB#2580's attached sample (samplegetdocs.txt) is a raw capture of that live response: a JSON array of 20 scope nodes, 759 documents. Structure below.

2. What already exists (reuse, don't rebuild)

2.1 The MEC/LEC hub stack — where this work actually lands

Routing stays as-is (2026-08-25, Jose): DocumentsListPage remains a standalone, directly-routable page — reached via /documents?scope=MEC (etc.) from a menu-item route, the same pattern the legacy native app used (a Shell route bound to a menu item, not a page nested inside another page). This carousel work adds a section inside the hub the page already renders; it does not restructure routing or collapse the page/hub/browser layering into one component.

The production mechanism for that menu-item route already exists: TopNav's member-facing drawer rows are driven by backend MenuItem records whose SpecialCode is exactly "blazor-hybrid", with MenuItem.Link pointing at a Blazor route. A production MEC-documents menu item would set that link to /documents?scope=MEC and appear as a normal (non-Dev-tagged) row. The two topnav.drawerDocHubMec9 / topnav.drawerDocHubAlpa10 buttons currently in the drawer (TopNav.razor:159-172, tagged Dev, comment: "TEMPORARY DEMO AID... delete this button to revert") are a stand-in for that real menu-item route, not the intended long-term entry point — worth retiring once a real MenuItem record covers it.

2.2 The ALPA/"ALP MAG" carousel — a different surface, not touched by this work

What this means for AB#2580: the Carousel UI is done, the per-item adapter (DocumentHeroFactory) is done. The work is wiring a new DocumentsBrowserPresentation.Carousel arm into the existing MEC/LEC hub stack — not generalizing MockHomePreviewFeedService, and not touching the dynamic-feed PageDto/ContainerDto/ItemDto contract at all.

2.3 A third, unrelated system solves an adjacent problem — mobile-content-api's template field (not used here)

A third content-API doc set exists in this repo — docs/mobile-content-api/ (Sites → Pages → Containers → Items) — separate from both the MEC/LEC hub stack (§2.1) and the dynamic-feed PageDto/ContainerDto/ItemDto system (§2.2). It documents a free-form template field that solves a conceptually adjacent problem — binding a UI slot to filtered DocumentItem content — with a completely different mechanism:

A real captured instance (Carousel container → List item, UAL Communications feed) shows the shape a caller puts inside that unschema'd string — this specific inner shape is not documented anywhere in this repo; it's one observed instance, not a contract:

{
  "renderType": "CardText",
  "variant": null,
  "contentType": "DocumentItem",
  "parentFilterType": "MEC",
  "parentFilterValue": "ual",
  "filterType": "Category",
  "filterValue": "Communications",
  "scope": null,
  "category": null,
  "grouping": null,
  "searchFilter": "by:date-direction:desc-top:3",
  "action": null
}

A repo-wide grep for renderType, filterType, filterValue, and searchFilter as literal JSON keys returns hits only against this one captured payload — no DAL or FDX equivalent exists anywhere in docs or source, and neither does a full page-level response combining multiple such items. None of this generalizes to AB#2580: the MEC/LEC hub carousel this document specifies is built directly against IScaffoldDocumentsQueries/DocumentItem (§2.1), never through an ItemDto.template string.

2.4 The background caching AB#2580 asks about is already built — and it is not the PrefetchCount download cache

2.5 Decision (2026-08-26, Jose) — CardHero refactors to auto-hide on no image; three of the RCL's four image-bearing components already do this

Decision: CardHero moves to the CardText/CardSmall/PromoBanner pattern — no image in the payload, or a real URL that 404s/auth-blocks, hides .alpa-cardlg-media entirely rather than substituting placeholder art. This directly answers Open Questions #1 and #2 (§6): no backend fix is required for the image gap, and the client's standing answer to "no image" is auto-hide, not CardHero's current placeholder or DocumentsBrowserLogic.ResolveIcon's icon treatment (§6 #2's other two options).

What the refactor actually touches:

• Not just an @@if in the Razor. Unlike CardText/PromoBanner, .alpa-cardlg bakes the image slot's dimensions into the card's own layout: .alpa-cardlg sets a fixed min-height: 343px (alpa-components.css:304-317, documented as 200px media + 143px content per the card-lg spec) and .alpa-cardlg-media a fixed height: 200px (:319-327). Collapsing the slot needs a CardSmall-style modifier class (e.g. alpa-cardlg--noimg) that overrides both, not a bare conditional around the <img> — otherwise the card keeps its full height with an empty 200px block where the image used to be, the same "looks broken, not absent" failure CardSmall's fix was written to avoid.
• No DocumentHeroFactory change needed. DocumentHeroFactory.Create (§2.1) already passes Image = document.Image straight through, including when it's null — the hide-vs-placeholder decision lives entirely inside CardHero, so the adapter in §5 step 2 is unaffected by this refactor.
• Blast radius is wider than this carousel. CardHero is also the ALP MAG carousel's card (MockHomePreviewFeedService, §2.2, out of scope for this document) and FavoritesViewModel's hero rows (§5) — both currently show the placeholder photos and will start showing no-image cards instead once this ships. Worth a screenshot check on both surfaces, not just the new MEC/LEC carousel, before merging.
• Spec doc goes stale otherwise. docs/component-specifications/card-hero/card-hero-property-mapping.html:138,192 documents today's placeholder fallback as CardHero's contract — needs updating alongside the code change or it misdescribes retired behavior.

3. Sample payload structure (AB#2580 attachment, samplegetdocs.txt)

Three-level array, matching the live getdocuments response shape:

[
  {
    "scope": "ALPA",
    "categories": [
      {
        "category": "Canada Limits",
        "description": "Canada Limits",
        "documents": [
          {
            "title": "Canadian Limits: 2026 & 2025",
            "docType": "pdf",
            "path": "~/media/968EF181A0EB47F99A27F49ACCB5A1CE.ashx?modified=...",
            "image": null,
            "featuredImage": null,
            "featuredImageLink": null,
            "featured": false,
            "description": null,
            "publishDate": "2026-03-18T13:15:00-04:00",
            "source": "sitecore",
            "fileID": "{968EF181-A0EB-47F9-9A27-F49ACCB5A1CE}",
            "portalID": -1
          }
        ]
      }
    ]
  }
]

Sample composition: 20 scope nodes / 759 documents total. docType ∈ {pdf, html, htm, webpage}; source ∈ {DNN, sitecore}. Maps onto the existing domain model 1:1 — ScopeItem → CategoryItem → DocumentItem (ALPAMobile.Application/Abstractions/Documents, ALPAMobile.Domain/Data/Models/CategoryItem.cs) — via the standard IDocumentsQueries deserialization path already in place; no new raw-DTO mapping is needed at this level.

4. Known data-quality gaps in the live feed

These were first captured 2026-07-10 in backend-api-mapping-report.html Part 3 ("GetDocuments metadata alignment", sampled 383 documents / 20 scope / 20 category nodes). I re-checked every one against the AB#2580 sample (759 documents, captured 2026-08-24) and against a live logged-in account (UAL test member, 2026-08-25) — all are still present, six weeks later. A recommended target shape for the gap that actually blocks this work is in §8 — as of the 2026-08-26 decision in §2.5/§6, only the duplicate-scope-nodes gap still does; the image gap is resolved client-side.

5. Adapter requirements — the MEC/LEC hub carousel

Decided direction (2026-08-25): extend the existing DocumentsHub/DocumentsBrowser stack rather than add a new orchestrating component. Concretely, five changes, all localized to the files already in §2.1. The plan below was reviewed against the current code on 2026-08-25 and three of the five steps needed correction — flagged inline as Verified / Gap found — corrected below so the corrections aren't mistaken for the original framing.

1. New presentation value. Verified DocumentsBrowserTypes.cs:21-31 — add Carousel to DocumentsBrowserPresentation. DocumentsBrowserLogic.cs:17-21's Allowed dictionary currently reads [DocumentsBrowserMode.DocumentList] = [DatedRows, Tiles] — needs Carousel added to that array (the Defaults dictionary at :24-28 stays DatedRows as the default; Carousel is opt-in via the Presentation parameter, matching how Tiles already works). Without this, ResolvePresentation throws by design (:36-39) — confirmed this is the actual current guard, not a hypothetical one.
2. Map through DocumentHeroFactory, not a new mapper — but fix a missing field first. Gap found — corrected below DocumentsBrowser.razor.cs's LoadDocumentsAsync() (:144-164) already produces the exact List<DocumentItem> a carousel needs — fetched, filtered, sorted, capped to MaxItems, the same pipeline DatedRows uses. The new branch maps that same ordered list through DocumentHeroFactory.Create(doc, doc.FileID) into a sibling field (e.g. _heroCards), with DocumentHeroFactory injected alongside the existing CardIconFactory/CategoryCardFactory/DocumentRowFactory (:68-72).
   
   The gap: DocumentHeroFactory.Create (DocumentHeroFactory.cs:35-42) does not set ComponentViewModel.Id — confirmed by reading it directly: it sets FavoriteItemTypeId, Title, Description, Image, Link, and nothing else. Its only current caller, FavoritesViewModel.HydrateAsync (FavoritesViewModel.cs:113), never needs .Id either, because Favorites rows use their own remove affordance, not the generic heart toggle. But DocumentsBrowser's other two per-document factories both set it explicitly — DocumentRowFactory.Create sets Id = document.FileID (DocumentRowFactory.cs) and CardIconFactory.Create sets Id = CategoryCardFactory.RawId(...) — because ComponentView.CanFavorite (ComponentView.razor.cs:40-45) requires !string.IsNullOrEmpty(vm.Id) before a heart renders at all. Left as-is, every hero card in the new carousel would silently show no favorite heart — not a crash, not a visible error, just a missing affordance a tester would have to notice by its absence.
   
   Fix: set Id = fileId inside DocumentHeroFactory.Create itself (it already receives fileId as a parameter) rather than patching it in at each call site — a one-line, backward-compatible addition that also closes the gap for FavoritesViewModel's existing call, and matches the sibling factories' convention.
3. IsEmpty gets a new arm. Verified DocumentsBrowser.razor.cs:86-91's switch needs DocumentsBrowserPresentation.Carousel => _heroCards.Count == 0 — confirmed the existing switch's default arm (_ => _documentRows.Count == 0) would otherwise silently catch an unhandled Carousel value and check the wrong (always-empty) collection.
4. Render by wrapping into CarouselViewModel — but DocumentsBrowser's own header/empty-state need a guard, or the section double-renders. Gap found — corrected below The recommended approach (§6 #4) is still to build new CarouselViewModel { Title = ..., Items = [.. _heroCards] } and render <Carousel Vm="..." /> inside the new switch case, reusing Carousel.razor unchanged.
   
   The gap: read against the current file, DocumentsBrowser.razor renders its own section header from SectionTitle/ViewAllLink (:22-32, alpa-docbrowser-head) and its own empty-state gate (:34-37, generic <EmptyState>) before the presentation switch even runs (:40) — neither is presentation-aware today. Carousel.razor unconditionally renders its own header (.alpa-feed-header, no guard around the outer <div> — only the "View All" anchor inside it is conditional). Adding Carousel as a plain new case in the switch, as originally drafted, would render two headers stacked on top of each other showing the same title and View All link — DocumentsBrowser's alpa-docbrowser-head and Carousel.razor's alpa-feed-header — and would also mean Carousel.razor's own "Off the Radar" empty treatment is unreachable, since DocumentsBrowser's generic <EmptyState> gate (:34-37) always wins first.
   
   Fix: two small, localized changes — (a) guard DocumentsBrowser.razor:22's header condition with && _presentation != DocumentsBrowserPresentation.Carousel, so Carousel.razor is the sole header owner for that presentation; (b) pass SuppressEmptyState="true" on the new hub composition call (matching the hub's existing convention for its other three sections, §5 step 5) so an empty carousel section collapses entirely via the existing :12-17 gate, rather than needing to resolve which of the two components' empty-state treatments should win. This sidesteps needing Carousel.razor's "Off the Radar" card at all for this specific use — it stays reachable in principle but isn't exercised via DocumentsHub.
5. One new composition call in the hub. Verified DocumentsHub.razor gets a fourth <DocumentsBrowser Mode="DocumentsBrowserMode.DocumentList" Presentation="DocumentsBrowserPresentation.Carousel" SuppressEmptyState="true" .../>, same shape as its existing "Latest Documents" call (:33-39), with SuppressEmptyState="true" added per the fix above. Placement in the hub's section order (top, alongside "Latest Documents", or replacing it) and whether it needs its own Category/Grouping filter are still open — see §6 #5/#6.

Confirmed working with no changes needed: favorite-heart wiring (as opposed to the .Id gap above) — ComponentView's cascading parameter is typed FavoriteToggleContext? (ComponentView.razor.cs:26), the identical type DocumentsHub.razor already supplies via <CascadingValue Value="_favoriteContext"> wrapping all its <DocumentsBrowser> children. Neither Carousel.razor nor ComponentView redeclare that cascading type, so the same context reaches hero cards inside a nested <Carousel> automatically — once the .Id gap above is fixed, no additional favorite plumbing is needed. Also unchanged: the fetch/filter/sort pipeline, SourceUnavailable/FilterDescription semantics, and the mandatory /document-open link policy (already inside DocumentHeroFactory).

Test impact: UnitTest/DocumentsBrowserLogicTests.cs exercises Allowed/Defaults/ResolvePresentation today and will need a new case asserting Carousel is valid for DocumentList (and invalid for CategoryGrid, matching the existing throw-on-invalid-pair test shape). Not independently checked for a DocumentsBrowser.razor.cs-level render test that might assert exhaustively on _presentation — worth a quick grep before implementation.

6. Open questions

7. Out of scope (this document)

• The /home ALP MAG carousel (MockHomePreviewFeedService) — a separate, already-working surface. It is explicitly a mock standing in for the real dynamic-feed endpoint and is expected to eventually be re-pointed at a live PageDto from the AB#2133 backend once that endpoint exists (§2.2), not to be generalized or merged with the MEC/LEC hub work in this document.
• The dynamic-feed endpoint itself (AB#2133) — contract §9 lists its route/auth as still open. The MEC/LEC hub carousel in this document does not depend on it and never routes through PageDto/ContainerDto/ItemDto.
• Rebuilding Carousel.razor, CarouselViewModel, or the HeroCard presentation — all already implemented and reused as-is (§5).
• The document-open/download pipeline (DocumentOpenPage, docType routing) — only referenced here where it shares a data-quality gap with the carousel.

8. Recommended feed shape — a guide for the backend contract

8.1 Which gaps actually block the carousel

As of 2026-08-26, none of §4's gaps need a backend fix for this specific work — the two that once did (image, dedup) are resolved client-side (§2.5, §4/§6 #3). What's left is pre-existing hygiene, split by whether it's still worth a backend ask:

8.2 Recommended shape — annotated example

Current shape (from the AB#2580 sample, six duplicate ALPA nodes shown collapsed to two for brevity) versus the recommended shape below — both changes are now nice-to-have hygiene proposals rather than required fixes, per the 2026-08-26 findings in §2.5 and §4/§6 #3.

// CURRENT — as captured 2026-08-24, six separate "ALPA" nodes (this doc's own §4 finding)
[
  { "scope": "ALPA", "categories": [ { "category": "Canada Limits", "documents": [ ... ] } ] },
  { "scope": "ALPA", "categories": [ { "category": "ALP MAG", "description": "ALPA Magazine.",
      "documents": [ { "title": "ALP MAG", "image": null, ... } ] } ] },
  // ...4 more "ALPA" nodes, each with a different category array
]

// RECOMMENDED — one node per logical scope, categories merged under it
[
  {
    "scope": "ALPA",
    "categories": [
      { "category": "Canada Limits", "categoryTitle": "Canada Limits", "documents": [ ... ] },
      {
        "category": "ALP MAG",
        // NEW — always populated, distinct from description; description keeps its
        // existing free-text role instead of doubling as the only source of a friendly name.
        "categoryTitle": "ALP Magazine",
        "description": "ALPA Magazine.",
        "documents": [
          {
            "title": "Air Line Pilot — July/August 2026",
            // NEW — real cover art where it exists; absent (null) is still a valid,
            // client-handled state (§2.1) for document types with no cover art (e.g. Canada
            // Limits, a policy PDF) — this is additive, not a required-on-every-document field.
            "image": "https://.../covers/alp-mag-2026-07.jpg",
            "docType": "pdf",
            "publishDate": "2026-07-01T00:00:00-04:00",
            "source": "sitecore",
            "fileID": "{...}",
            "portalID": -1
          }
        ]
      }
      // ...every other real ALPA category, all under this one node
    ]
  }
]

Nothing else in the existing shape (§3) changes — fileID, docType, source, publishDate, portalID, and the rest are unaffected and already sufficient for this work.

8.3 Rollout note

Both proposed fixes are additive/structural, not breaking, whichever priority they end up shipping at: a client that doesn't yet know about categoryTitle ignores it (it already falls back to CategoryItem.DisplayTitle's existing "API title-if-distinct, else description" logic — §4 row 4); a client reading the deduplicated scope array sees strictly more correct data than today's silently-dropped duplicates, not a different shape to parse. Neither fix requires a client-side version gate.

References

• AB#2580 "Document Module" (Azure Boards) — attached samplegetdocs.txt
• ALPAMobile/Services/RestService.cs:1581-1586, ALPAMobile/Services/ScaffoldDataSourceRouters.cs:208-300
• ALPAMobile/Services/DataManager.cs:1136-1260, ALPAMobile/Services/CacheContentService.cs:203 — the background metadata-cache mechanism (§1, §2.4)
• ALPAMobile/Services/DataManager.cs:1298-1354 — the composite-key dedup logic (CategoryItem/DocumentItem.CompositeId), fixed by commit 34a7a7af "process children of repeated scope names" (AB#2208, 2026-07-06); live-reconfirmed 2026-08-26 (§4, §6 #3)
• Document Cache — Design Gap (AB#2578) — the separate PrefetchCount download cache, not used by this work (§2.4)
• ALPAMobile.Presentation/Components/Library/DocumentsHub.razor, DocumentsBrowser.razor(.cs), ALPAMobile.Presentation/Components/DocumentsBrowserTypes.cs, DocumentsBrowserLogic.cs
• ALPAMobile.Presentation/Components/DocumentHeroFactory.cs
• ALPAMobile.Presentation/ViewModels/CarouselViewModel.cs, ALPAMobile.Presentation/Components/Library/Carousel.razor, CardHero.razor(.cs)
• CardText.razor, CardSmall.razor(.cs), PromoBanner.razor, wwwroot/css/alpa-components.css:304-327,7916 — the auto-hide-on-no-image precedent and the .alpa-cardlg CSS mechanics (§2.5)
• CardHero — Data Source Analysis — documents today's placeholder fallback as the contract; needs updating per §2.5's decision
• ALPAMobile/Services/MockHomePreviewFeedService.cs — the ALP MAG surface, out of scope (§2.2/§7)
• ALPAMobile.Application/ApiModels/PageDto.cs, ItemDto.cs; ALPAMobile.Presentation/Components/ContainerFactory.cs, ItemComponentFactory.cs — dynamic-feed shape, not used by the MEC/LEC hub carousel
• Dynamic Feed API Contract §3.3, §4, §5, §9
• Backend API Mapping Report — Part 3, "GetDocuments metadata alignment" (2026-07-10)
• Dynamic UI Architecture
• MEC Customization Mock Guide — CLE172 "Roster" MenuItem-vs-DocumentItem finding (§2.1 note)
• Mobile Content API — Dynamic Feed, Admin Portal — template field (§2.3, not used by this work)