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

package/src/components/shared/product-release/product-release-card.tsx

@@ -11,8 +11,30 @@ import {
 } from '../../chat/entity-cards/content-card-frame';
 import { CardHoverPlay } from '../../features/video-center-badge';
 import { InteractiveCard } from '../../ui/interactive-card';
+import { useLoadingScope } from '../../ui/loading-scope';
 import { SquareAvatar } from '../../ui/square-avatar';
 import { StatusBadge } from '../../ui/status-badge';
+import {
+  RELEASE_CARD_CELL_CLASS,
+  RELEASE_CARD_CELL_DIVIDER_CLASS,
+  RELEASE_CARD_CELL_LABEL_CLASS,
+  RELEASE_CARD_CELL_LABELS,
+  RELEASE_CARD_CELL_STACK_CLASS,
+  RELEASE_CARD_CHANGELOG_CLASS,
+  RELEASE_CARD_COVER_BOX_CLASS,
+  RELEASE_CARD_COVER_COLUMN_CLASS,
+  RELEASE_CARD_GRID_CLASS,
+  RELEASE_CARD_HERO_CLASS,
+  RELEASE_CARD_LG_FRAME_CLASS,
+  RELEASE_CARD_SUMMARY_BOX_CLASS,
+  RELEASE_CARD_SUMMARY_CLASS,
+  RELEASE_CARD_TEXT_COLUMN_CLASS,
+  RELEASE_CARD_TITLE_BOX_CLASS,
+  RELEASE_CARD_TITLE_CLASS,
+  RELEASE_CARD_VERSION_CLASS,
+  RELEASE_CARD_VERSION_ROW_CLASS,
+} from './product-release-card-classes';
+import { ProductReleaseCardSkeleton } from './product-release-card-skeleton';
 
 /**
  * Card density. Two variants, both actively used across openframe + flamingo
@@ -86,6 +108,8 @@ export interface ProductReleaseCardProps {
   className?: string;
   /** Card density. Defaults to `'lg'` (the canonical large card). */
   size?: ProductReleaseCardSize;
+  /** The release is still being read: the card draws its own skeleton (also in a page's loading scope). */
+  loading?: boolean;
 
   // ─── Catalog-only props (ignored by `default` / `sm` branches) ─────────
   /** Cover image URL. Falls back to a neutral `Package`-icon placeholder. */
@@ -138,7 +162,10 @@ export function ProductReleaseCard({
   viewCount,
   author,
   changelogCounts,
+  loading = false,
 }: ProductReleaseCardProps) {
+  // One switch: while the release is read (a prop, or a page's loading scope) the card is its skeleton.
+  if (useLoadingScope() || loading) return <ProductReleaseCardSkeleton size={size} className={className} />;
   // ----- LG branch (rich /releases catalog row + related-content rail) -----
   // The card has THREE zones:
   //   1. Hero — cover image LEFT, version pill + title + summary RIGHT.
@@ -182,25 +209,25 @@ export function ProductReleaseCard({
       releaseType && releaseTypeBadgeColor
         ? {
             value: releaseType.toUpperCase(),
-            label: 'Type',
+            label: RELEASE_CARD_CELL_LABELS[0],
             uppercase: true,
             colorScheme: releaseTypeBadgeColor,
           }
-        : { value: '—', label: 'Type', uppercase: false },
+        : { value: '—', label: RELEASE_CARD_CELL_LABELS[0], uppercase: false },
       releaseStatus
         ? {
             value: releaseStatus.toUpperCase(),
-            label: 'Status',
+            label: RELEASE_CARD_CELL_LABELS[1],
             uppercase: true,
           }
-        : { value: '—', label: 'Status', uppercase: false },
+        : { value: '—', label: RELEASE_CARD_CELL_LABELS[1], uppercase: false },
       formattedDate
         ? {
             value: formattedDate,
-            label: 'Released',
+            label: RELEASE_CARD_CELL_LABELS[2],
             uppercase: false,
           }
-        : { value: '—', label: 'Released', uppercase: false },
+        : { value: '—', label: RELEASE_CARD_CELL_LABELS[2], uppercase: false },
     ];
     // EMPTY_AUTHOR_PLACEHOLDER shape — mirrors the hub's
     // EMPTY_AUTHOR_PLACEHOLDER constant exported from
@@ -212,15 +239,14 @@ export function ProductReleaseCard({
     // skeleton's shape matches the loaded card exactly. The earlier
     // dynamic `gridColsClass` ternary collapsed missing cells and
     // caused 28-56px reflow on resolve.
-    const gridColsClass = 'content-md:grid-cols-4';
-    const dividerClass = 'border-b content-md:border-b-0 content-md:border-r border-ods-border';
+    const dividerClass = RELEASE_CARD_CELL_DIVIDER_CLASS;
 
     // THE shared card frame: interactive (accent border on hover) when the card
     // links or clicks, the static frame when it does neither.
     const interactive = !!anchorProps || !!onClick;
     const frameClass = cn(
       interactive ? CONTENT_CARD_FRAME_CLASS : CONTENT_CARD_SKELETON_FRAME_CLASS,
-      'flex flex-col gap-4 p-6',
+      RELEASE_CARD_LG_FRAME_CLASS,
       'focus:outline-none focus-visible:ring-2 focus-visible:ring-ods-accent focus-visible:ring-offset-2 focus-visible:ring-offset-ods-bg',
       'no-underline',
       className,
@@ -229,9 +255,9 @@ export function ProductReleaseCard({
     const innerLayout = (
       <>
         {/* HERO ZONE — cover LEFT + version pill + title + summary RIGHT */}
-        <div className="flex flex-col gap-4 content-md:flex-row content-md:gap-6">
-          <div className="w-full flex-shrink-0 content-md:w-[256px]">
-            <div className="relative aspect-[1200/630] w-full overflow-hidden rounded-lg bg-ods-bg">
+        <div className={RELEASE_CARD_HERO_CLASS}>
+          <div className={RELEASE_CARD_COVER_COLUMN_CLASS}>
+            <div className={cn(RELEASE_CARD_COVER_BOX_CLASS, 'bg-ods-bg')}>
               {coverImage ? (
                 <Image
                   src={coverImage}
@@ -249,29 +275,24 @@ export function ProductReleaseCard({
               {hasVideoCover && coverImage && <CardHoverPlay size="md" />}
             </div>
           </div>
-          <div className="flex min-w-0 flex-1 flex-col">
-            <div className="mb-3 flex items-center gap-3">
-              <span className="truncate font-semibold text-ods-text-primary text-code">v{version}</span>
+          <div className={RELEASE_CARD_TEXT_COLUMN_CLASS}>
+            <div className={RELEASE_CARD_VERSION_ROW_CLASS}>
+              <span className={RELEASE_CARD_VERSION_CLASS}>v{version}</span>
             </div>
             {/* Title — reserve a fixed 2-line height so cards with
                 1-line titles don't shrink and the catalog skeleton-to-
                 content transition is shift-free. Mirrors the
                 onboarding-guide catalog card. */}
-            <div className="mb-3 flex min-h-[60px] items-start content-md:min-h-[72px]">
-              <h3 className="line-clamp-2 font-['Azeret_Mono'] text-xl font-semibold leading-tight text-ods-text-primary content-md:text-2xl">
-                {title}
-              </h3>
+            <div className={RELEASE_CARD_TITLE_BOX_CLASS}>
+              <h3 className={RELEASE_CARD_TITLE_CLASS}>{title}</h3>
             </div>
             {/* Summary — fixed 3-line height. `line-clamp-3` caps long
                 summaries at 3 lines; `min-h` reserves the same vertical
                 space when content is shorter, so the catalog grid stays
-                row-consistent regardless of per-card content length.
-                Heights derived from text-sm content-md:text-base × leading-relaxed
-                (1.625): 14×1.625×3 ≈ 68 px mobile, 16×1.625×3 ≈ 78 px desktop. */}
-            <div className="min-h-[68px] content-md:min-h-[78px]">
-              <p className="line-clamp-3 font-['DM_Sans'] text-sm leading-relaxed text-ods-text-secondary content-md:text-base">
-                {summary ?? ''}
-              </p>
+                row-consistent regardless of per-card content length
+                (three lines of the summary's `text-h4`). */}
+            <div className={RELEASE_CARD_SUMMARY_BOX_CLASS}>
+              <p className={RELEASE_CARD_SUMMARY_CLASS}>{summary ?? ''}</p>
             </div>
           </div>
         </div>
@@ -280,37 +301,40 @@ export function ProductReleaseCard({
             always-on changelog placeholder matches the loaded shape
             (zero reflow on resolve). When `totalChangelog === 0`, an
             empty-state line takes the same vertical space as the
-            populated row. */}
-        <div className="flex flex-wrap items-center gap-x-4 gap-y-1.5 border-t border-ods-border pt-3 text-ods-text-secondary text-h6">
+            populated row. Which counts show is read data, so each one is a
+            read list item (`data-loading-item`): the skeleton draws the first. */}
+        <div className={RELEASE_CARD_CHANGELOG_CLASS}>
           {totalChangelog > 0 && changelogCounts ? (
             <>
               {changelogCounts.features > 0 && (
-                <span className="inline-flex items-center gap-1.5">
+                <span data-loading-item className="inline-flex items-center gap-1.5">
                   <Sparkles className="h-3.5 w-3.5" />
                   {changelogCounts.features} {changelogCounts.features === 1 ? 'feature' : 'features'}
                 </span>
               )}
               {changelogCounts.fixes > 0 && (
-                <span className="inline-flex items-center gap-1.5">
+                <span data-loading-item className="inline-flex items-center gap-1.5">
                   <Wrench className="h-3.5 w-3.5" />
                   {changelogCounts.fixes} {changelogCounts.fixes === 1 ? 'fix' : 'fixes'}
                 </span>
               )}
               {changelogCounts.improvements > 0 && (
-                <span className="inline-flex items-center gap-1.5">
+                <span data-loading-item className="inline-flex items-center gap-1.5">
                   <TrendingUp className="h-3.5 w-3.5" />
                   {changelogCounts.improvements} {changelogCounts.improvements === 1 ? 'improvement' : 'improvements'}
                 </span>
               )}
               {changelogCounts.breaking > 0 && (
-                <span className="inline-flex items-center gap-1.5 text-ods-warning">
+                <span data-loading-item className="inline-flex items-center gap-1.5 text-ods-warning">
                   <AlertTriangle className="h-3.5 w-3.5" />
                   {changelogCounts.breaking} breaking
                 </span>
               )}
             </>
           ) : (
-            <span className="text-ods-text-secondary">No changelog entries yet</span>
+            <span data-loading-item className="text-ods-text-secondary">
+              No changelog entries yet
+            </span>
           )}
         </div>
 
@@ -320,23 +344,17 @@ export function ProductReleaseCard({
             text, no colored badge — em-dash badges read as broken next
             to populated ones); the Author cell falls back to the
             EMPTY_AUTHOR_PLACEHOLDER shape declared above. */}
-        <div
-          className={cn(
-            'grid grid-cols-1',
-            gridColsClass,
-            'w-full overflow-hidden rounded-md border border-ods-border',
-          )}
-        >
+        <div className={RELEASE_CARD_GRID_CLASS}>
           {valueCells.map((cell, i) => (
-            <div key={`${cell.label}-${i}`} className={cn('flex flex-col gap-3 p-4', dividerClass)}>
-              <div className="flex flex-col gap-0">
+            <div key={`${cell.label}-${i}`} className={cn(RELEASE_CARD_CELL_CLASS, dividerClass)}>
+              <div className={RELEASE_CARD_CELL_STACK_CLASS}>
                 {cell.colorScheme ? (
                   <StatusBadge
                     text={cell.value}
                     variant="card"
                     colorScheme={cell.colorScheme}
                     singleLine
-                    className="self-start"
+                    className="justify-self-start"
                   />
                 ) : (
                   <p
@@ -350,7 +368,7 @@ export function ProductReleaseCard({
                     {cell.uppercase ? cell.value.toLocaleUpperCase() : cell.value}
                   </p>
                 )}
-                <p className="text-ods-text-secondary text-h6">{cell.label}</p>
+                <p className={RELEASE_CARD_CELL_LABEL_CLASS}>{cell.label}</p>
               </div>
             </div>
           ))}

package/src/components/shared/product-release/product-releases-view.tsx

@@ -32,14 +32,18 @@ import { buildProductReleaseCardProps } from '../../chat/entity-cards/product-re
 import { useEntityCardLink } from '../../chat/entity-cards/use-entity-card-link';
 import { isModifierClick } from '../../chat/utils/chat-nav-resolution';
 import { executeNavigationImperative } from '../../chat/utils/execute-navigation';
+import { usePageDataSync } from '../../layout/page-data-sync';
 import { ListEmptyState } from '../../list-empty-state';
 import { LoadingRegion } from '../../loading/loading-region';
-import { PersistentPaginationWrapper } from '../../persistent-pagination';
 import { LoadError } from '../../ui/error-state';
+import { useLoadingScope } from '../../ui/loading-scope';
+import { UnifiedPagination } from '../../unified-pagination';
 import { ProductReleaseCard, type ProductReleaseCardProps } from './product-release-card';
-import { ProductReleaseCardSkeleton } from './product-release-card-skeleton';
 
 const DEFAULT_ENDPOINT = '/api/releases';
+/** The pager's row inside the list's bottom slot: no margin of its own (the slot spaces it), so the loaded pager is
+ *  the height of its skeleton. */
+const PAGER_ROW_CLASS = 'flex w-full justify-center';
 // Param keys sourced from the shared registry (see RoadmapView) — single source for the
 // chrome's written `?key=` and this view's read.
 const DEFAULT_SEARCH_PARAM_KEY = DEV_SECTION_PARAM_KEYS.search;
@@ -158,10 +162,19 @@ export function ProductReleasesView({
   const listParams = new URLSearchParams({ limit: String(itemsPerPage), offset: String(offset) });
   if (search) listParams.set(searchParamKey, search);
   if (status && status !== 'all') listParams.set(statusParamKey, status);
-  const { data, isLoading, error, reload } = useSelfFetch<ProductReleaseListResponse>(
-    `${endpoint}?${listParams.toString()}`,
-    { initialData },
-  );
+  // In a page's loading state the list is read: nothing is fetched and the view is its skeleton.
+  const inScope = useLoadingScope();
+  const {
+    data,
+    isLoading: fetching,
+    error,
+    reload,
+  } = useSelfFetch<ProductReleaseListResponse>(inScope ? null : `${endpoint}?${listParams.toString()}`, {
+    initialData,
+  });
+  const isLoading = inScope || fetching;
+  // The page's sync row (`PageDataSyncRow`) states what this list's endpoint answered.
+  usePageDataSync(data?.sync, isLoading && !data);
 
   const releases = data?.data ?? [];
   const totalCount = data?.count ?? 0;
@@ -219,33 +232,28 @@ export function ProductReleasesView({
                     key={release?.id ?? `slot-${i}`}
                     style={{ visibility: isLoading || hasData ? 'visible' : 'hidden' }}
                   >
-                    {isLoading ? (
-                      <ProductReleaseCardSkeleton size="lg" />
-                    ) : release ? (
+                    {!isLoading && release ? (
                       <ReleaseRow release={release} basePath={basePath} buildCardProps={buildCardProps} />
                     ) : (
-                      <ProductReleaseCardSkeleton size="lg" />
+                      // Read, or a hidden slot past the page's last release: the card draws its own skeleton.
+                      <ProductReleaseCard loading size="lg" title="" version="" formattedDate="" />
                     )}
                   </div>
                 );
               })}
             </LoadingRegion>
 
-            {/* Pagination — always present at the bottom for consistent spacing. */}
+            {/* Pagination: always present at the bottom, one row height in every state (its skeleton while the list
+                is read, the hidden real control for a single page), so the list above never moves. */}
             <div className="mt-6 flex justify-center content-md:mt-8">
-              {isLoading ? (
-                <div className="m-3 h-12 w-64" />
-              ) : releases.length > 0 && totalPages > 1 ? (
-                <PersistentPaginationWrapper
-                  isLoading={false}
-                  currentPage={currentPage}
-                  totalPages={totalPages}
-                  onPageChange={goToPage}
-                  variant="blog"
-                />
-              ) : (
-                <div className="m-3 h-12 w-64" style={{ visibility: 'hidden' }} />
-              )}
+              <UnifiedPagination
+                loading={isLoading}
+                currentPage={currentPage}
+                totalPages={releases.length > 0 ? totalPages : 0}
+                onPageChange={goToPage}
+                className={PAGER_ROW_CLASS}
+                reserveSpace
+              />
             </div>
           </>
         )}