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

package/src/components/shared/legal-document/legal-document-page.tsx

@@ -20,11 +20,13 @@
 import type { ComponentType } from 'react';
 import Link from '../../../embed-shims/next-link';
 import { useRouter } from '../../../embed-shims/next-navigation';
+import { cn } from '../../../utils/cn';
 import { FaqSection, pageFaqProps, type PageFaqSlot } from '../../faq/faq-section';
-import { UnifiedSkeleton } from '../../loading/unified-skeleton';
+import { LoadingRegion } from '../../loading/loading-region';
 import { PageShell, PageLayout } from '../../ui';
 import { DataSyncLine } from '../../ui/data-attribution';
-import { RichMarkdownRenderer } from '../../ui/markdown';
+import { useLoadingScope } from '../../ui/loading-scope';
+import { RichMarkdownRenderer, RichMarkdownRendererSkeleton } from '../../ui/markdown';
 import { useLegalDocs, type LegalDocument } from './use-legal-docs';
 import { useLegalDocuments } from './use-legal-documents';
 
@@ -98,6 +100,26 @@ export function legalDocumentStampLabel(
   return parts.length > 0 ? parts.join(' \u00b7 ') : null;
 }
 
+/**
+ * Sections a legal document's skeleton draws: its first fold. One section at the rendered `article` type is about
+ * 290px (a 32px heading with its rule and margins, then a three-line and a two-line paragraph at 20px / 1.6) from
+ * desktop and about 260px on a phone, so three fill the screen under the page title at 1440 and at 390; a long
+ * document is drawn no further.
+ */
+export const LEGAL_DOCUMENT_SKELETON_SECTIONS = 3;
+
+/**
+ * A legal document's body while it is read: the rich renderer's own skeleton (`RichMarkdownRendererSkeleton`, the
+ * `article` type the page renders with), opening with the document's own title row, then its first fold of sections.
+ */
+export function LegalDocumentSkeleton({ sections = LEGAL_DOCUMENT_SKELETON_SECTIONS }: { sections?: number }) {
+  return (
+    <LoadingRegion label="Loading the document" className="w-full">
+      <RichMarkdownRendererSkeleton title sections={sections} />
+    </LoadingRegion>
+  );
+}
+
 export function LegalDocumentPage({
   docType,
   title: titleProp,
@@ -115,7 +137,9 @@ export function LegalDocumentPage({
   shell = true,
 }: LegalDocumentPageProps) {
   const router = useRouter();
-  const { data, isLoading, error } = useLegalDocs(docType, { initialData, apiEndpoint });
+  const { data, isLoading: fetching, error } = useLegalDocs(docType, { initialData, apiEndpoint });
+  // In a page's loading state the document is read: the page draws its skeleton (and fetches nothing).
+  const isLoading = useLoadingScope() || fetching;
 
   // Back-button config — mirrors DevSectionPage's `{ label: 'Back to home',
   // onClick: () => router.push('/') }`. Hide entirely when caller passes
@@ -141,31 +165,27 @@ export function LegalDocumentPage({
   // states its own version and effective date shows those (they are what a
   // reader agreed to), else the fallback description. When it was last read from
   // its repository is the shared sync line under the title.
-  const subtitle = legalDocumentStampLabel(data) ?? fallbackDescription;
+  // While it is read the stamp is unknown: its line is held (never the fallback description).
+  const subtitle = isLoading ? undefined : (legalDocumentStampLabel(data) ?? fallbackDescription);
 
   const inner = (
-    <PageLayout title={title} subtitle={subtitle} backButton={backCfg} titleSize="h1" titleWrap>
-      <DataSyncLine sync={data ? { source: 'github', syncedAt: data.lastSynced } : null} loading={isLoading && !data} />
+    <PageLayout
+      title={title}
+      subtitle={subtitle}
+      subtitleRow={isLoading ? 'always' : undefined}
+      backButton={backCfg}
+      titleSize="h1"
+      titleWrap
+    >
+      <DataSyncLine sync={data ? { source: 'github', syncedAt: data.lastSynced } : null} loading={isLoading} />
 
       <div className="flex flex-1 flex-col items-start gap-6 lg:flex-row lg:gap-10">
-        <div className="flex-1">
+        {/* While loading the column has no text to size it (the row is `items-start` on a phone): it takes the row's width. */}
+        <div className={cn('flex-1', isLoading && 'w-full')}>
           <div className="w-full">
             <article className="space-y-2">
               {isLoading ? (
-                // Loading skeleton matching Knowledge Hub pattern
-                <div className="space-y-6">
-                  <UnifiedSkeleton className="h-10 w-3/4 rounded-lg" />
-                  <div className="space-y-4">
-                    <UnifiedSkeleton className="h-4 w-full rounded" />
-                    <UnifiedSkeleton className="h-4 w-full rounded" />
-                    <UnifiedSkeleton className="h-4 w-5/6 rounded" />
-                  </div>
-                  <UnifiedSkeleton className="h-32 rounded-lg border border-ods-border" />
-                  <div className="space-y-4">
-                    <UnifiedSkeleton className="h-4 w-full rounded" />
-                    <UnifiedSkeleton className="h-4 w-4/5 rounded" />
-                  </div>
-                </div>
+                <LegalDocumentSkeleton />
               ) : error ? (
                 <div className="space-y-4 text-center">
                   <div className="rounded-lg border border-ods-error bg-ods-error-secondary p-6">

package/src/components/shared/legal-document/use-legal-docs.ts

@@ -15,6 +15,7 @@
 
 import { useState, useEffect, useRef } from 'react';
 import { contentFetch } from '../../../utils/embed-content-fetch';
+import { useLoadingScope } from '../../ui/loading-scope';
 
 export interface LegalDocument {
   title: string;
@@ -179,7 +180,10 @@ export function useLegalDocs(docType: string, options: UseLegalDocsOptions = {})
 
   // Fetch on mount (only if we don't already have server-provided initialData),
   // and on every explicit `refetch()`.
+  // In a loading scope nothing is fetched: the page draws what it was given.
+  const held = useLoadingScope();
   useEffect(() => {
+    if (held) return;
     if (initialData && reloadCount === 0) return;
 
     const requestId = ++requestIdRef.current;
@@ -228,7 +232,7 @@ export function useLegalDocs(docType: string, options: UseLegalDocsOptions = {})
 
     // Never rejects — settles every failure into `error` state.
     void fetchDocument();
-  }, [docType, effectiveEndpoint, initialData, reloadCount]);
+  }, [docType, effectiveEndpoint, initialData, reloadCount, held]);
 
   const refetch = () => {
     // An explicit retry starts from a settled (usually errored) state, so it

package/src/components/shared/legal-document/use-legal-documents.ts

@@ -14,6 +14,7 @@
 
 import { useEffect, useState } from 'react';
 import { contentFetch } from '../../../utils/embed-content-fetch';
+import { useLoadingScope } from '../../ui/loading-scope';
 
 export interface LegalDocumentSummary {
   /** The identifier `useLegalDocs` and `<LegalDocumentPage>` take. */
@@ -81,7 +82,9 @@ export function toLegalDocumentSummaries(payload: unknown): LegalDocumentSummary
 
 export function useLegalDocuments(options: UseLegalDocumentsOptions = {}): UseLegalDocumentsReturn {
   const endpoint = options.apiEndpoint ?? '/api/legal';
-  const enabled = options.enabled ?? true;
+  // In a loading scope nothing is fetched.
+  const held = useLoadingScope();
+  const enabled = (options.enabled ?? true) && !held;
   const [state, setState] = useState<UseLegalDocumentsReturn>({ documents: [], isLoading: enabled, error: null });
 
   useEffect(() => {

package/src/components/shared/media-gallery-strip.tsx

@@ -2,8 +2,11 @@
 
 import { useState } from 'react';
 import Image from '../../embed-shims/next-image';
+import { cn } from '../../utils/cn';
 import { Video } from '../features/video';
+import { UnifiedSkeleton } from '../loading/unified-skeleton';
 import { ImageGalleryModal } from '../ui/image-gallery-modal';
+import { useLoadingScope } from '../ui/loading-scope';
 
 export interface MediaGalleryStripItem {
   media_type: string;
@@ -18,6 +21,13 @@ function isGalleryImage(mediaType: string): boolean {
   return mediaType !== 'video' && mediaType !== 'demo';
 }
 
+/** The strip's layout, read by the strip and by its skeleton, so the skeleton is the strip's size. */
+const STRIP_CLASS = 'flex w-full gap-6 overflow-x-auto';
+const TILE_SIZE_CLASS = 'shrink-0 w-[240px] h-[200px] rounded-md';
+const TILE_CLASS = `${TILE_SIZE_CLASS} overflow-hidden border border-ods-border bg-ods-bg transition-opacity`;
+/** Tiles a skeleton draws when not told how many (a strip's first fold on a wide screen). */
+export const MEDIA_GALLERY_STRIP_SKELETON_COUNT = 4;
+
 export interface MediaGalleryStripProps {
   items: MediaGalleryStripItem[];
   className?: string;
@@ -37,16 +47,20 @@ export function MediaGalleryStrip({ items, className }: MediaGalleryStripProps)
   const [galleryOpen, setGalleryOpen] = useState(false);
   const [galleryIndex, setGalleryIndex] = useState(0);
 
+  // ONE switch: in a loading scope with no items yet (they are read) the strip is its skeleton; items it is given
+  // there are the page's own and are drawn as they are. A record's media is optional: a page whose loading layout
+  // leaves the strip out wraps the loaded one in `data-loading-optional`.
+  if (useLoadingScope() && !items?.length) return <MediaGalleryStripSkeleton className={className} />;
+
   if (!items || items.length === 0) return null;
 
   const galleryImages = items.filter(m => isGalleryImage(m.media_type)).map(m => m.media_url);
 
-  const tileClass =
-    'shrink-0 w-[240px] h-[200px] rounded-md overflow-hidden border border-ods-border bg-black transition-opacity';
+  const tileClass = TILE_CLASS;
 
   return (
     <>
-      <div className={`flex w-full gap-6 overflow-x-auto ${className ?? ''}`}>
+      <div className={`${STRIP_CLASS} ${className ?? ''}`}>
         {items.map((mediaItem, index) => {
           // Image tiles open the lightbox, so they're real <button>s — keyboard
           // focusable + Enter/Space activatable. Clips render in <Video>, which
@@ -94,3 +108,21 @@ export function MediaGalleryStrip({ items, className }: MediaGalleryStripProps)
     </>
   );
 }
+
+/** The media strip while it is read: `count` tiles of the strip's own 240×200 size. */
+export function MediaGalleryStripSkeleton({
+  count = MEDIA_GALLERY_STRIP_SKELETON_COUNT,
+  className,
+}: {
+  count?: number;
+  className?: string;
+}) {
+  return (
+    <div className={cn(STRIP_CLASS, 'overflow-hidden', className)} aria-hidden>
+      {Array.from({ length: count }, (_, i) => (
+        // biome-ignore lint/suspicious/noArrayIndexKey: skeleton tiles never reorder
+        <UnifiedSkeleton key={i} className={TILE_SIZE_CLASS} />
+      ))}
+    </div>
+  );
+}

package/src/components/shared/onboarding/index.ts

@@ -2,8 +2,5 @@
 
 export { OnboardingWalkthrough, type OnboardingWalkthroughProps } from './onboarding-walkthrough';
 export { OnboardingStepCard, type OnboardingStepCardProps } from './onboarding-step-card';
-export {
-  useOnboardingState,
-  type OnboardingState,
-  type OnboardingStepConfig,
-} from '../../../hooks/ui/use-onboarding-state';
+export { useOnboardingState, type OnboardingStepConfig } from '../../../hooks/ui/use-onboarding-state';
+export { type OnboardingState } from '../../../utils/onboarding-storage';

package/src/components/shared/product-release/index.ts

@@ -12,8 +12,8 @@ export {
   type ReleaseDetailPageProps,
   type VideoDisplaySectionProps,
   type MarkdownRendererProps,
-  type RoadmapItem,
 } from './release-detail-page';
+export { type RoadmapItem } from '../../chat/types/entities/roadmap-item';
 // NOTE: `RoadmapSectionProps` / `DeliverySectionProps` (the injectable-
 // component slot types for ReleaseDetailPage) are intentionally NOT
 // re-exported from this barrel — they collide with the prop types of

package/src/components/shared/product-release/product-release-card-classes.ts

@@ -0,0 +1,28 @@
+import { MEDIA_ASPECT } from '../../../styles/component-sizes';
+/**
+ * The large product-release card's layout, ONE copy read by `ProductReleaseCard` and `ProductReleaseCardSkeleton`,
+ * so the skeleton is the card's size at every width.
+ */
+export const RELEASE_CARD_LG_FRAME_CLASS = 'flex flex-col gap-4 p-6';
+export const RELEASE_CARD_HERO_CLASS = 'flex flex-col gap-4 content-md:flex-row content-md:gap-6';
+export const RELEASE_CARD_COVER_COLUMN_CLASS = 'w-full flex-shrink-0 content-md:w-[256px]';
+export const RELEASE_CARD_COVER_BOX_CLASS = `relative ${MEDIA_ASPECT.og} w-full overflow-hidden rounded-lg`;
+export const RELEASE_CARD_TEXT_COLUMN_CLASS = 'flex min-w-0 flex-1 flex-col';
+export const RELEASE_CARD_VERSION_ROW_CLASS = 'mb-3 flex items-center gap-3';
+export const RELEASE_CARD_VERSION_CLASS = 'truncate font-semibold text-ods-text-primary text-code';
+/** The title's box reserves two lines of the title's own type (`2lh`), the summary's three. */
+export const RELEASE_CARD_TITLE_BOX_CLASS = 'mb-3 flex min-h-[2lh] items-start text-h2';
+export const RELEASE_CARD_TITLE_CLASS = 'line-clamp-2 text-h2 text-ods-text-primary';
+export const RELEASE_CARD_SUMMARY_BOX_CLASS = 'min-h-[3lh] text-h4';
+export const RELEASE_CARD_SUMMARY_CLASS = 'line-clamp-3 text-h4 text-ods-text-secondary';
+export const RELEASE_CARD_CHANGELOG_CLASS =
+  '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';
+export const RELEASE_CARD_GRID_CLASS =
+  'grid grid-cols-1 content-md:grid-cols-4 w-full overflow-hidden rounded-md border border-ods-border';
+export const RELEASE_CARD_CELL_DIVIDER_CLASS = 'border-b content-md:border-b-0 content-md:border-r border-ods-border';
+export const RELEASE_CARD_CELL_CLASS = 'flex flex-col gap-3 p-4';
+/** The value over its label: only stacks, so a one-column grid, not a second column flexbox (WEBVIEW-001). */
+export const RELEASE_CARD_CELL_STACK_CLASS = 'grid grid-cols-1 gap-0';
+export const RELEASE_CARD_CELL_LABEL_CLASS = 'text-ods-text-secondary text-h6';
+/** The grid's three value cells' labels (static copy). */
+export const RELEASE_CARD_CELL_LABELS = ['Type', 'Status', 'Released'] as const;

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

@@ -2,7 +2,29 @@
 
 import { cn } from '../../../utils/cn';
 import { CONTENT_CARD_SKELETON_FRAME_CLASS } from '../../chat/entity-cards/content-card-frame';
-import { UnifiedSkeleton } from '../../loading/unified-skeleton';
+import { EntityMetadataAuthorCellSkeleton } from '../../chat/entity-cards/entity-author-card';
+import { TextLineSkeleton, UnifiedSkeleton } from '../../loading/unified-skeleton';
+import { StatusBadgeSkeleton } 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';
 
 export interface ProductReleaseCardSkeletonProps {
   /** Additional CSS classes */
@@ -23,71 +45,55 @@ export function ProductReleaseCardSkeleton({ className, size = 'lg' }: ProductRe
   // grid (with em-dash placeholders for missing values), so this
   // skeleton's shape matches exactly with zero load-to-resolve reflow.
   if (size === 'lg') {
+    // The card's own classes (`product-release-card-classes`): each read text is a bar of its own line box inside
+    // the loaded element, the grid's labels are real, the author cell is the shared metadata author skeleton.
     return (
-      <div className={cn(CONTENT_CARD_SKELETON_FRAME_CLASS, 'flex flex-col gap-4 p-6', className)}>
-        {/* HERO: placeholders are `UnifiedSkeleton` bars on the page background.
-
-            CRITICAL: title + summary use the SAME min-h containers as
-            the loaded card so total card height is byte-identical
-            between skeleton state and loaded state. Without this,
-            individual placeholder heights underrun the loaded card's
-            min-h reservations and the page jumps on resolve. */}
-        <div className="flex flex-col gap-4 content-md:flex-row content-md:gap-6">
-          <UnifiedSkeleton className="aspect-[1200/630] w-full flex-shrink-0 rounded-lg content-md:w-[256px]" />
-          <div className="flex min-w-0 flex-1 flex-col">
-            {/* Version pill — mirrors `flex items-center gap-3 mb-3` in
-                the loaded card. The loaded `<span text-lg>` renders at
-                line-height 28 px (Tailwind text-lg = 18 px / 28 px LH);
-                placeholder uses `h-7` (28 px) to match exactly. */}
-            <div className="mb-3 flex items-center gap-3">
-              <UnifiedSkeleton className="h-7 w-20 rounded" />
+      <div className={cn(CONTENT_CARD_SKELETON_FRAME_CLASS, RELEASE_CARD_LG_FRAME_CLASS, className)} aria-hidden>
+        <div className={RELEASE_CARD_HERO_CLASS}>
+          <div className={RELEASE_CARD_COVER_COLUMN_CLASS}>
+            <UnifiedSkeleton className={RELEASE_CARD_COVER_BOX_CLASS} />
+          </div>
+          <div className={RELEASE_CARD_TEXT_COLUMN_CLASS}>
+            <div className={RELEASE_CARD_VERSION_ROW_CLASS}>
+              <span className={RELEASE_CARD_VERSION_CLASS}>
+                <TextLineSkeleton type="inherit" as="span" className="w-16" />
+              </span>
             </div>
-            {/* Title container — SAME min-h as the loaded card so the
-                card height contributed by this region matches exactly. */}
-            <div className="mb-3 flex min-h-[60px] flex-col justify-start gap-1.5 content-md:min-h-[72px]">
-              <UnifiedSkeleton className="h-[25px] w-3/4 rounded content-md:h-[30px]" />
-              <UnifiedSkeleton className="h-[25px] w-1/2 rounded content-md:h-[30px]" />
+            <div className={RELEASE_CARD_TITLE_BOX_CLASS}>
+              <h3 className={cn(RELEASE_CARD_TITLE_CLASS, 'w-full')}>
+                <TextLineSkeleton type="inherit" as="span" lines={2} className="w-3/4" />
+              </h3>
             </div>
-            {/* Summary container — SAME min-h as the loaded card. The
-                3 placeholder lines mirror the rendered 3-line clamp. */}
-            <div className="flex min-h-[68px] flex-col justify-start gap-2 content-md:min-h-[78px]">
-              <UnifiedSkeleton className="h-3 w-full rounded" />
-              <UnifiedSkeleton className="h-3 w-11/12 rounded" />
-              <UnifiedSkeleton className="h-3 w-5/6 rounded" />
+            <div className={RELEASE_CARD_SUMMARY_BOX_CLASS}>
+              <p className={RELEASE_CARD_SUMMARY_CLASS}>
+                <TextLineSkeleton type="inherit" as="span" lines={3} className="w-full" />
+              </p>
             </div>
           </div>
         </div>
-
-        {/* CHANGELOG strip placeholder — always rendered. Inner
-            placeholder `h-5` mirrors the loaded strip's `text-sm`
-            line-height (20 px) so total height is consistent with the
-            loaded `border-t pt-3 + text content` (~32-33 px). */}
-        <div className="border-t border-ods-border pt-3">
-          <UnifiedSkeleton className="h-5 w-2/3 rounded" />
+        {/* The changelog's counts are read list items (which ones show is read data): one row's first item. */}
+        <div className={RELEASE_CARD_CHANGELOG_CLASS}>
+          <span data-loading-item className="inline-flex">
+            <TextLineSkeleton type="inherit" as="span" className="w-24" />
+          </span>
         </div>
-
-        {/* METADATA GRID: 4-cell placeholder, the loaded cells' own boxes (no surface of
-            their own; bars on the page background). Inner heights mirror the loaded cells. */}
-        <div className="grid w-full grid-cols-1 overflow-hidden rounded-md border border-ods-border content-md:grid-cols-4">
-          {[0, 1, 2].map(i => (
-            <div
-              key={`cell-${i}`}
-              className="flex flex-col gap-3 border-b border-ods-border p-4 content-md:border-b-0 content-md:border-r"
-            >
-              <div className="flex flex-col gap-2">
-                <UnifiedSkeleton className="h-7 w-24 rounded" />
-                <UnifiedSkeleton className="h-4 w-16 rounded" />
+        <div className={RELEASE_CARD_GRID_CLASS}>
+          {RELEASE_CARD_CELL_LABELS.map((label, i) => (
+            <div key={label} className={cn(RELEASE_CARD_CELL_CLASS, RELEASE_CARD_CELL_DIVIDER_CLASS)}>
+              <div className={RELEASE_CARD_CELL_STACK_CLASS}>
+                {/* The Type value is a card StatusBadge loaded; the others are a text-h4 line. */}
+                {i === 0 ? (
+                  <StatusBadgeSkeleton variant="card" className="justify-self-start" />
+                ) : (
+                  <p className="text-h4">
+                    <TextLineSkeleton type="inherit" as="span" className="w-24" />
+                  </p>
+                )}
+                <p className={RELEASE_CARD_CELL_LABEL_CLASS}>{label}</p>
               </div>
             </div>
           ))}
-          {/* Author cell */}
-          <div className="flex items-center gap-3 p-4">
-            <UnifiedSkeleton className="h-10 w-10 shrink-0 rounded-full" />
-            <div className="flex min-w-0 flex-1 flex-col gap-2">
-              <UnifiedSkeleton className="h-5 w-3/4 rounded" />
-              <UnifiedSkeleton className="h-4 w-1/2 rounded" />
-            </div>
-          </div>
+          <EntityMetadataAuthorCellSkeleton />
         </div>
       </div>
     );