@flamingo-stack/openframe-frontend-core 0.0.765 → 0.0.766

package/src/components/onboarding-guides/onboarding-guide-detail-view.tsx

@@ -13,6 +13,12 @@
  * (markdown, video warmup, captions, related-card hrefs via
  * `runtime.composeContentUrl`). Optional `MarkdownRenderer` lets hosts swap a
  * renderer with extra plugins.
+ *
+ * LOADING: the view is its own loading state. While the guide is read (or in a host's loading scope) it renders the
+ * SAME page over an empty guide (`EMPTY_ONBOARDING_GUIDE`, or the host's empty placeholder) inside a `LoadingScope`:
+ * the title block, the tags, the metadata grid, the body, the byline and the related guides each draw their own
+ * skeleton; the back button and the static labels are real. Parts a guide may not have (its video, its bites) are left
+ * out while loading and carry `data-loading-optional` once loaded.
  */
 
 import { Fragment, type ComponentType, type ReactNode } from 'react';
@@ -37,9 +43,11 @@ import { VideoBitesStrip } from '../features/video-bites-strip';
 // the detail block visibly narrower than the rail.
 import { PageShell } from '../layout/article-detail-layout';
 import { PageLayout } from '../layout/page-layout';
+import { LoadingRegion } from '../loading/loading-region';
+import { TextLineSkeleton } from '../loading/unified-skeleton';
 import { ArticleAuthorByline } from '../shared/article-author-byline';
-import { DetailPageSkeleton } from '../shared/detail-page-skeleton';
 import { LoadError } from '../ui/error-state';
+import { LoadingScope, useLoadingScope } from '../ui/loading-scope';
 import { RichMarkdownRenderer } from '../ui/markdown';
 
 export interface OnboardingGuideDetailViewProps {
@@ -84,6 +92,95 @@ export interface OnboardingGuideDetailViewProps {
   shell?: boolean;
 }
 
+/** The view's layout, read by the view and by its skeleton, so the skeleton is the view's size. */
+const RELATED_BLOCK_CLASS = 'space-y-4 border-t border-ods-border pt-8';
+const RELATED_HEADING_CLASS = 'tracking-[-0.36px] text-ods-text-primary text-h3';
+const RELATED_LIST_CLASS = 'flex flex-col gap-3';
+const BODY_CLASS = 'space-y-4';
+/** The metadata grid's extra cell label (static copy). */
+const SECTION_CELL_LABEL = 'Section';
+/** Related guide cards the related block's skeleton draws (a guide's first fold). */
+export const ONBOARDING_GUIDE_RELATED_SKELETON_COUNT = 3;
+
+/** The guide the view renders while it is read: every field empty, so each part draws its own skeleton. */
+const EMPTY_ONBOARDING_GUIDE: OnboardingGuide = {
+  id: '',
+  title: '',
+  slug: '',
+  section: '',
+  step_order: 0,
+  section_order: 0,
+  content: '',
+  video_summary: null,
+  transcript: null,
+  transcript_words_data: null,
+  srt_content: null,
+  ai_transcript_formatted: null,
+  main_video_url: null,
+  main_video_thumbnail: null,
+  youtube_url: null,
+  highlight_video_url: null,
+  highlight_video_thumbnail: null,
+  highlight_video_duration_ms: null,
+  highlight_video_source: null,
+  video_bites: [],
+  featured_image: null,
+  og_image_url: null,
+  seo_title: null,
+  seo_description: null,
+  seo_keywords: null,
+  status: 'published',
+  published_at: null,
+  author_id: null,
+  custom_instructions: null,
+  config: null,
+  ai_effort_score: null,
+  onboarding_guide_tags: [],
+  created_at: '',
+  updated_at: '',
+  created_by: null,
+  updated_by: null,
+};
+
+/**
+ * The same-section guides under the article: "More in <section>" over their cards, each a read list item. While the
+ * guide is read (`useLoadingScope()`) it renders a fold of empty guides, whose cards draw their own skeletons, under
+ * the heading's real words with the section as a bar.
+ */
+function RelatedGuides({
+  section,
+  related,
+  renderCard,
+}: {
+  section: string;
+  related: OnboardingGuide[];
+  renderCard: (guide: OnboardingGuide) => ReactNode;
+}) {
+  const loading = useLoadingScope();
+  const guides = loading
+    ? Array.from({ length: ONBOARDING_GUIDE_RELATED_SKELETON_COUNT }, (_, i) => ({
+        ...EMPTY_ONBOARDING_GUIDE,
+        id: `skeleton-${i}`,
+      }))
+    : related;
+  if (guides.length === 0) return null;
+  return (
+    <div className={RELATED_BLOCK_CLASS}>
+      <h2 className={RELATED_HEADING_CLASS}>
+        More in{' '}
+        {loading ? <TextLineSkeleton type="inherit" as="span" className="inline-block w-32 align-middle" /> : section}
+      </h2>
+      <ul className={RELATED_LIST_CLASS}>
+        {guides.map(guide => (
+          <li key={guide.id} data-loading-item>
+            {renderCard(guide)}
+          </li>
+        ))}
+      </ul>
+    </div>
+  );
+}
+
 export function OnboardingGuideDetailView({
   authorHref,
   authorBio,
@@ -111,7 +208,16 @@ export function OnboardingGuideDetailView({
 
   // Controlled (hub SSR `initialData`) OR self-fetch by slug (config-only embed).
   const url = initialData ? null : slug && guideEndpoint ? guideEndpoint(slug) : null;
-  const { data: guide, isLoading, error, reload } = useSelfFetch<OnboardingGuide>(url, { initialData });
+  // In a page's loading state the guide is read (the host passes an empty record): nothing is fetched.
+  const scoped = useLoadingScope();
+  const {
+    data: guide,
+    isLoading,
+    error,
+    reload,
+  } = useSelfFetch<OnboardingGuide>(scoped ? null : url, {
+    initialData,
+  });
 
   // Hooks must run unconditionally — feed them optional-chained values so they
   // no-op while the guide is still loading.
@@ -120,34 +226,25 @@ export function OnboardingGuideDetailView({
     supabaseStorageOrigin: runtime?.endpoints.supabaseStorageOrigin,
   });
 
-  if (error || (!guide && !isLoading)) {
+  const backCfg = { label: backLabel, onClick: () => router.push(resolvedBackHref) };
+  const loading = scoped || (!guide && isLoading);
+  if (!loading && (error || !guide)) {
     return renderShell(<LoadError message="Guide not found." onRetry={reload} />);
   }
-  if (!guide) {
-    // Skeleton (not a bare "Loading…") for parity with every other shared view —
-    // catalog, roadmap, releases all render a skeleton on first load, so the detail
-    // page shouldn't flash text then content. `bare` + `PageShell` so the loading
-    // state matches the loaded page's full width / padding / min-height.
-    return renderShell(
-      // Match the loaded page's top offset (TitleBlock's
-      // `pt-[var(--spacing-system-l)]`) so content doesn't jump on load.
-      <div className="pt-[var(--spacing-system-l)]">
-        <DetailPageSkeleton bare showImageGallery={false} />
-      </div>,
-    );
-  }
+  // While loading: the host's empty placeholder (in its scope) or the view's own empty guide.
+  const view = guide ?? EMPTY_ONBOARDING_GUIDE;
 
   // Track URLs via the ONE captions configurer (`useCaptions`); same-origin
   // hosts get the relative `/api/captions/...` default. Zero per-page wiring.
-  const { captionsUrl, highlightCaptionsUrl } = captions.forEntity('onboarding_guide', guide);
+  const { captionsUrl, highlightCaptionsUrl } = captions.forEntity('onboarding_guide', view);
 
   const videoPoster =
-    guide.main_video_thumbnail ||
-    guide.featured_image ||
-    guide.og_image_url ||
+    view.main_video_thumbnail ||
+    view.featured_image ||
+    view.og_image_url ||
     // `buildOgPlaceholderUrl` always returns a usable string (relative route at
     // worst), so it's the terminal fallback — no trailing `|| undefined` needed.
-    buildOgPlaceholderUrl(runtime?.endpoints, guide.title, { aspect: 'wide' });
+    buildOgPlaceholderUrl(runtime?.endpoints, view.title, { aspect: 'wide' });
 
   const defaultRenderRelatedCard = (g: OnboardingGuide) => {
     const cta = resolveContentHref(runtime?.composeContentUrl, {
@@ -160,25 +257,20 @@ export function OnboardingGuideDetailView({
   };
   const renderRelatedCardFn = renderRelatedCard ?? defaultRenderRelatedCard;
 
-  return renderShell(
-    <PageLayout
-      title={guide.title}
-      titleSize="h1"
-      titleWrap
-      backButton={{ label: backLabel, onClick: () => router.push(resolvedBackHref) }}
-    >
+  const page = (
+    <PageLayout title={view.title} loading={loading} titleSize="h1" titleWrap backButton={backCfg}>
       {/* Tags — flat onboarding_guide_tags[] from entity_tags. */}
-      <EntityTagBadges tags={guide.onboarding_guide_tags} />
+      <EntityTagBadges tags={view.onboarding_guide_tags} />
 
       {/* Metadata grid — Section · Step | Published | Author. */}
       <EntityAuthorCard
-        author={guide.author}
+        author={view.author}
         authorHref={authorHref}
-        publishedAt={guide.published_at}
+        publishedAt={view.published_at}
         extraCells={[
           {
-            value: `${guide.section} · Step ${guide.step_order}`,
-            label: 'Section',
+            value: `${view.section} · Step ${view.step_order}`,
+            label: SECTION_CELL_LABEL,
             uppercase: false,
           },
         ]}
@@ -186,17 +278,18 @@ export function OnboardingGuideDetailView({
 
       {/* Video. `main_video_url` (Mux/MP4) and `youtube_url` are independent
             columns — either populated renders the player. */}
-      {(guide.main_video_url || guide.youtube_url) && (
-        <div ref={videoWarmupRef}>
+      {!loading && (view.main_video_url || view.youtube_url) && (
+        // A guide's video is optional: the loading state leaves it out.
+        <div ref={videoWarmupRef} data-loading-optional="">
           <EntityVideoSection
-            mainVideoUrl={guide.main_video_url}
-            youtubeUrl={guide.youtube_url || undefined}
-            highlightVideoUrl={guide.highlight_video_url}
+            mainVideoUrl={view.main_video_url}
+            youtubeUrl={view.youtube_url || undefined}
+            highlightVideoUrl={view.highlight_video_url}
             mainVideoPoster={videoPoster}
-            highlightVideoThumbnail={guide.highlight_video_thumbnail || undefined}
+            highlightVideoThumbnail={view.highlight_video_thumbnail || undefined}
             videoSummary={undefined}
             videoBites={undefined}
-            title={guide.title}
+            title={view.title}
             captionsUrl={captionsUrl}
             highlightCaptionsUrl={highlightCaptionsUrl}
             MarkdownRenderer={MarkdownRenderer}
@@ -204,45 +297,41 @@ export function OnboardingGuideDetailView({
         </div>
       )}
 
-      {/* Markdown body */}
-      {guide.content && (
-        <div className="space-y-4">
-          <MarkdownRenderer content={guide.content} />
+      {/* Markdown body (in the loading scope, the renderer's own skeleton) */}
+      {(loading || view.content) && (
+        <div className={BODY_CLASS}>
+          <MarkdownRenderer content={view.content ?? ''} />
         </div>
       )}
 
-      {/* Video Bites — unified strip; renders nothing when no published bites. */}
-      <VideoBitesStrip
-        bites={(guide.video_bites as VideoTeaser[] | null) ?? []}
-        filterPublished={true}
-        showTitle={false}
-        profile={toStripProfile(guide.author)}
-        href={`/onboarding-guides/${guide.slug}`}
-      />
+      {/* Video Bites — unified strip; renders nothing when no published bites. Optional per guide: the loading state
+          leaves it out (no box of its own: `contents`). */}
+      {loading ? null : (
+        <div className="contents" data-loading-optional="">
+          <VideoBitesStrip
+            bites={(view.video_bites as VideoTeaser[] | null) ?? []}
+            filterPublished={true}
+            showTitle={false}
+            profile={toStripProfile(view.author)}
+            href={`/onboarding-guides/${view.slug}`}
+          />
+        </div>
+      )}
 
       {/* End-of-article author byline (avatar + linked name + bio) — the
             author DESCRIPTION block every article-shaped detail page renders.
             Hidden when the guide has no author (the byline returns null). */}
       <ArticleAuthorByline
-        author={guide.author?.full_name ?? null}
-        avatar={guide.author?.avatar_url}
-        jobTitle={guide.author?.job_title}
-        bio={authorBio ?? guide.author?.about}
+        author={view.author?.full_name ?? null}
+        avatar={view.author?.avatar_url}
+        jobTitle={view.author?.job_title}
+        bio={authorBio ?? view.author?.about}
         href={authorHref}
         fallbackBio={fallbackBio}
       />
 
       {/* Related — same-section, ordered by step. */}
-      {related.length > 0 && (
-        <div className="space-y-4 border-t border-ods-border pt-8">
-          <h2 className="tracking-[-0.36px] text-ods-text-primary text-h3">More in {guide.section}</h2>
-          <ul className="flex flex-col gap-3">
-            {related.map(r => (
-              <li key={r.id}>{renderRelatedCardFn(r)}</li>
-            ))}
-          </ul>
-        </div>
-      )}
+      <RelatedGuides section={view.section} related={related} renderCard={renderRelatedCardFn} />
 
       {/*
        * Host slot — cross-type related-content / FAQ rail.
@@ -264,6 +353,16 @@ export function OnboardingGuideDetailView({
        * all of them, and that file carries an explicit FROZEN contract.
        */}
       <Fragment key="related-content">{relatedContent}</Fragment>
-    </PageLayout>,
+    </PageLayout>
+  );
+  // The loading state is the page itself in a scope, announced once unless a host's scope already did.
+  return renderShell(
+    loading ? (
+      <LoadingRegion label="Loading the guide" announce={!scoped}>
+        <LoadingScope>{page}</LoadingScope>
+      </LoadingRegion>
+    ) : (
+      page
+    ),
   );
 }

package/src/components/onboarding-guides/onboarding-guides-catalog-skeleton.tsx

@@ -1,61 +1,48 @@
 'use client';
 
 import { OnboardingGuideCardSkeleton } from '../chat/entity-cards/onboarding-guide-card';
-import { LoadingRegion } from '../loading/loading-region';
-import { UnifiedSkeleton } from '../loading/unified-skeleton';
+import { TextLineSkeleton } from '../loading/unified-skeleton';
 
+/** The catalog's layout, read by the loaded view and by its sections' skeleton, so the skeleton is the view's size. */
+export const CATALOG_VIEW_CLASS = 'flex w-full flex-col gap-10';
+export const CATALOG_CONTROLS_CLASS = 'space-y-4';
+export const CATALOG_SECTIONS_CLASS = 'space-y-10';
+export const CATALOG_SECTION_CLASS = 'space-y-4';
+export const CATALOG_SECTION_HEADING_CLASS = 'flex items-center gap-2 text-ods-text-primary text-h3';
+export const CATALOG_SECTION_COUNT_CLASS =
+  'inline-flex items-center justify-center rounded-full bg-ods-text-secondary/20 px-2 py-0.5 text-ods-text-secondary text-h6';
+export const CATALOG_LIST_CLASS = 'flex flex-col gap-4';
+
+/**
+ * Catalog cards one screen shows under the search and the section pills (a 1440x900 desktop and a 390x844 phone
+ * both fit three of the `catalog` card's height before the fold). The section count is the data's: the skeleton
+ * draws ONE section of this fold, and every loaded section is a `data-loading-item`.
+ */
+export const ONBOARDING_CATALOG_CARD_FOLD = 3;
 /**
- * Loading skeleton for `/onboarding-guides` — CHROME-LESS, exactly like the
- * loaded `<OnboardingGuidesCatalogView>`. The HOST page owns the
- * `<DevSectionPage sectionKey="onboarding">` shell (hero + back button);
- * this component renders only what replaces the view: the search/pill
- * placeholder block and the section card lists.
- *
- * HISTORY: this used to mount its own `<DevSectionPage>` — nested inside the
- * page's shell that double-rendered the hero + back button during loading
- * (the view was made chrome-less in the page restructure; the skeleton was
- * missed). Keep BOTH chrome-less.
- *
- * Wrapper mirrors the loaded view's `w-full flex flex-col gap-10`; per-card
- * height matches the loaded catalog card so resolve shifts are zero.
+ * The catalog's sections while the guides are read: ONE section of `ONBOARDING_CATALOG_CARD_FOLD` cards in the view's
+ * own classes (its heading and count bars). The view draws it itself (`useLoadingScope() || loading`): its search bar
+ * is real and its section pills draw their own skeleton.
  */
-export function OnboardingGuidesCatalogSkeleton({
-  region = true,
-}: {
-  /** The loading state announces itself (`LoadingRegion`). `false` inside another loading region. Default `true`. */
-  region?: boolean;
-} = {}) {
+export function OnboardingCatalogSectionsSkeleton() {
   return (
-    <LoadingRegion label="Loading onboarding guides" announce={region} className="flex w-full flex-col gap-10">
-      {/* Search input placeholder — matches `<SearchInput>` h-12 — plus the
-          section pill row (~74 px incl. padding), same as the loaded
-          preControls block. */}
-      <div className="space-y-4">
-        <UnifiedSkeleton className="h-12 w-full rounded-md" />
-        <div className="flex flex-wrap items-center gap-3 rounded-lg border border-ods-border bg-ods-card p-4">
-          <UnifiedSkeleton className="h-4 w-14 rounded" />
-          {[0, 1, 2, 3].map(i => (
-            <UnifiedSkeleton key={i} className="h-10 w-24 rounded-md" />
+    <div className={CATALOG_SECTIONS_CLASS}>
+      <section className={CATALOG_SECTION_CLASS} data-loading-item>
+        <h2 className={CATALOG_SECTION_HEADING_CLASS}>
+          <TextLineSkeleton type="inherit" as="span" className="w-40" />
+          <span className={CATALOG_SECTION_COUNT_CLASS}>
+            <TextLineSkeleton type="inherit" as="span" className="w-3" />
+          </span>
+        </h2>
+        <ul className={CATALOG_LIST_CLASS}>
+          {Array.from({ length: ONBOARDING_CATALOG_CARD_FOLD }, (_, i) => (
+            // biome-ignore lint/suspicious/noArrayIndexKey: skeleton cards never reorder
+            <li key={i}>
+              <OnboardingGuideCardSkeleton size="catalog" />
+            </li>
           ))}
-        </div>
-      </div>
-      <div className="space-y-10">
-        {[4, 3, 3].map((cardCount, sectionIdx) => (
-          <section key={sectionIdx} className="space-y-4">
-            <div className="flex items-center gap-2 tracking-[-0.36px] text-ods-text-primary text-h3">
-              <UnifiedSkeleton className="h-6 w-40 rounded" />
-              <UnifiedSkeleton className="h-5 w-8 rounded-full" />
-            </div>
-            <ul className="flex flex-col gap-4">
-              {Array.from({ length: cardCount }).map((_, cardIdx) => (
-                <li key={cardIdx}>
-                  <OnboardingGuideCardSkeleton size="catalog" />
-                </li>
-              ))}
-            </ul>
-          </section>
-        ))}
-      </div>
-    </LoadingRegion>
+        </ul>
+      </section>
+    </div>
   );
 }

package/src/components/onboarding-guides/onboarding-guides-catalog-view.tsx

@@ -26,13 +26,25 @@ import { useMemo, useTransition, type ReactNode } from 'react';
 import { useChatRuntime } from '../../contexts/chat-runtime-context';
 import { useRouter, useSearchParams } from '../../embed-shims';
 import { useSelfFetch } from '../../hooks/use-self-fetch';
+import { cn } from '../../utils/cn';
 import { resolveContentHref } from '../../utils/content-href';
 import { OnboardingGuideCard } from '../chat/entity-cards/onboarding-guide-card';
 import type { OnboardingGuide } from '../chat/types/entities/onboarding-guide';
+import { LoadingRegion } from '../loading/loading-region';
 import { DocSearchBar, useDocSearch } from '../shared/doc-search';
 import { LoadError } from '../ui/error-state';
 import { FilterPillRow } from '../ui/filter-pill-row';
-import { OnboardingGuidesCatalogSkeleton } from './onboarding-guides-catalog-skeleton';
+import { LoadingScope, useLoadingScope } from '../ui/loading-scope';
+import {
+  CATALOG_CONTROLS_CLASS,
+  CATALOG_LIST_CLASS,
+  CATALOG_SECTION_CLASS,
+  CATALOG_SECTION_COUNT_CLASS,
+  CATALOG_SECTION_HEADING_CLASS,
+  CATALOG_SECTIONS_CLASS,
+  CATALOG_VIEW_CLASS,
+  OnboardingCatalogSectionsSkeleton,
+} from './onboarding-guides-catalog-skeleton';
 
 type SectionSummary = { section: string; section_order: number; count: number };
 
@@ -67,8 +79,11 @@ export function OnboardingGuidesCatalogView({
   const [isPending, startTransition] = useTransition();
   const runtime = useChatRuntime();
 
+  // In a page's loading state the catalog is read: it renders its own view in the scope (every part its own
+  // skeleton) and fetches nothing.
+  const scoped = useLoadingScope();
   // Self-fetch only when the host supplied NO data but DID give an endpoint.
-  const selfFetch = initialGuides === undefined && guidesEndpoint !== undefined;
+  const selfFetch = !scoped && initialGuides === undefined && guidesEndpoint !== undefined;
   // Active section: from the URL when self-fetching, from the prop (host RSC
   // already read the URL server-side) when controlled.
   const sectionValue = selfFetch ? (searchParams.get('section') ?? '') : initialSection;
@@ -96,6 +111,8 @@ export function OnboardingGuidesCatalogView({
     [initialSections, sectionsRes.data],
   );
   const isLoading = selfFetch ? guidesRes.isLoading : false;
+  // The catalog's first read (no guides yet), or a host's loading scope: the view renders in a loading scope.
+  const loading = scoped || (selfFetch && guidesRes.data == null && isLoading);
 
   // Section grouping. Data arrives already filtered (server-side `?section=`
   // for the host, or our `?section=` fetch); this just buckets visible rows.
@@ -163,7 +180,7 @@ export function OnboardingGuidesCatalogView({
   const renderCardFn = renderCard ?? defaultRenderCard;
 
   const preControls = (
-    <div className="space-y-4">
+    <div className={CATALOG_CONTROLS_CLASS}>
       <DocSearchBar
         placeholder="Search onboarding guides, releases, case studies…"
         query={docSearch.query}
@@ -173,12 +190,14 @@ export function OnboardingGuidesCatalogView({
         onResultSelect={docSearch.handleResultSelect}
         showDropdown={docSearch.keepDropdownOpen}
       />
-      {sections.length > 0 && (
+      {(loading || sections.length > 0) && (
         <FilterPillRow
           label="Section"
           selectedValue={activeSection}
           onValueChange={setSection}
-          options={sectionFilterOptions}
+          // While loading the options (their counts) are read: the row draws its own skeleton.
+          options={loading ? [] : sectionFilterOptions}
+          loading={loading}
         />
       )}
     </div>
@@ -186,50 +205,77 @@ export function OnboardingGuidesCatalogView({
 
   // A failed guides fetch → a RETRYABLE error (not the indistinguishable-from-
   // empty "no guides found" state) — parity with the sibling self-fetch views.
-  if (selfFetch && guidesRes.error) {
+  if (!loading && selfFetch && guidesRes.error) {
     return <LoadError message="Failed to load onboarding guides." onRetry={guidesRes.reload} />;
   }
-  // Full-page skeleton ONLY on the very first load (no data has loaded yet) — a
-  // later section toggle that legitimately returns ZERO guides keeps the page
-  // chrome (search + section pills) and dims the grid via the className below.
-  if (selfFetch && guidesRes.data == null && isLoading) {
-    return <OnboardingGuidesCatalogSkeleton />;
-  }
 
-  return (
-    <div className="flex w-full flex-col gap-10">
+  const view = (
+    <div className={CATALOG_VIEW_CLASS}>
       {preControls}
-      {guides.length === 0 ? (
-        <div className="py-16 text-center">
-          <GraduationCap className="mx-auto mb-4 h-12 w-12 text-ods-text-secondary" />
-          <h2 className="mb-2 text-ods-text-primary text-h3">No onboarding guides found</h2>
-          <p className="text-ods-text-secondary text-h6">
-            {activeSection !== 'all'
-              ? 'No guides in this section yet.'
-              : "We're working on the onboarding library. Check back soon."}
-          </p>
-        </div>
-      ) : (
-        <div className={isPending || isLoading ? 'space-y-10 opacity-60 transition-opacity' : 'space-y-10'}>
-          {grouped.map(sec => (
-            <section key={sec.section} className="space-y-4">
-              <h2 className="flex items-center gap-2 text-ods-text-primary text-h3">
-                {sec.section}
-                <span className="inline-flex items-center justify-center rounded-full bg-ods-text-secondary/20 px-2 py-0.5 text-ods-text-secondary text-h6">
-                  {sec.guides.length}
-                </span>
-              </h2>
-              {/* HORIZONTAL catalog list — single column so consecutive steps
-                  read top-to-bottom; a grid would visually reorder them. */}
-              <ul className="flex flex-col gap-4">
-                {sec.guides.map(guide => (
-                  <li key={guide.id}>{renderCardFn(guide)}</li>
-                ))}
-              </ul>
-            </section>
-          ))}
-        </div>
-      )}
+      <OnboardingCatalogSections
+        grouped={grouped}
+        loading={loading}
+        dimmed={isPending || isLoading}
+        allSections={activeSection === 'all'}
+        renderCard={renderCardFn}
+      />
+    </div>
+  );
+  // The first read (no data yet): the SAME view in a loading scope. A later section toggle that returns ZERO guides
+  // keeps the page's controls and dims the grid (`dimmed`).
+  if (!loading) return view;
+  return (
+    <LoadingRegion label="Loading onboarding guides" announce={!scoped}>
+      <LoadingScope>{view}</LoadingScope>
+    </LoadingRegion>
+  );
+}
+
+/** The catalog's sections: their own skeleton while the guides are read (`useLoadingScope() || loading`). */
+function OnboardingCatalogSections({
+  grouped,
+  loading,
+  dimmed,
+  allSections,
+  renderCard,
+}: {
+  grouped: Array<{ section: string; guides: OnboardingGuide[] }>;
+  loading: boolean;
+  dimmed: boolean;
+  /** No section is selected (the empty state's wording). */
+  allSections: boolean;
+  renderCard: (guide: OnboardingGuide) => ReactNode;
+}) {
+  if (useLoadingScope() || loading) return <OnboardingCatalogSectionsSkeleton />;
+  if (grouped.length === 0) {
+    return (
+      <div className="py-16 text-center">
+        <GraduationCap className="mx-auto mb-4 h-12 w-12 text-ods-text-secondary" />
+        <h2 className="mb-2 text-ods-text-primary text-h3">No onboarding guides found</h2>
+        <p className="text-ods-text-secondary text-h6">
+          {allSections ? "We're working on the onboarding library. Check back soon." : 'No guides in this section yet.'}
+        </p>
+      </div>
+    );
+  }
+  return (
+    <div className={cn(CATALOG_SECTIONS_CLASS, dimmed && 'opacity-60 transition-opacity')}>
+      {grouped.map(sec => (
+        // A section is the data's group: how many there are is the record's (`data-loading-item`).
+        <section key={sec.section} className={CATALOG_SECTION_CLASS} data-loading-item>
+          <h2 className={CATALOG_SECTION_HEADING_CLASS}>
+            {sec.section}
+            <span className={CATALOG_SECTION_COUNT_CLASS}>{sec.guides.length}</span>
+          </h2>
+          {/* HORIZONTAL catalog list — single column so consecutive steps
+              read top-to-bottom; a grid would visually reorder them. */}
+          <ul className={CATALOG_LIST_CLASS}>
+            {sec.guides.map(guide => (
+              <li key={guide.id}>{renderCard(guide)}</li>
+            ))}
+          </ul>
+        </section>
+      ))}
     </div>
   );
 }