@flamingo-stack/openframe-frontend-core 0.0.748 → 0.0.749

package/src/components/content-loading-container.tsx

@@ -2,6 +2,7 @@
 
 import type { ReactNode } from 'react';
 import { cn } from '../utils/cn';
+import { LoadingRegion } from './loading/loading-region';
 
 interface ContentLoadingContainerProps {
   /**
@@ -50,7 +51,7 @@ interface ContentLoadingContainerProps {
  * ```tsx
  * <ContentLoadingContainer
  *   isLoading={isLoadingVendors}
- *   skeletonComponent={<CardSkeletonGrid variant="vendor" count={12} />}
+ *   skeletonComponent={<CardSkeletonGrid variant="vendor" count={12} region={false} />}
  *   minHeight="min-h-[800px]"
  * >
  *   <VendorGrid vendors={vendors} />
@@ -72,23 +73,21 @@ export function ContentLoadingContainer({
       style={{
         transitionDuration: `${transitionDuration}ms`,
       }}
-      role="region"
-      aria-label={isLoading ? 'Loading content' : 'Content loaded'}
-      aria-live="polite"
     >
       {/* Loading Skeleton Overlay */}
       {isLoading && (
-        <div
+        // The one announcement for this content: a `skeletonComponent` that has a region of its own
+        // takes `region={false}`.
+        <LoadingRegion
+          label="Loading content"
           className="absolute inset-0 z-10 bg-ods-bg"
           style={{
             opacity: loadingOpacity,
             transition: `opacity ${transitionDuration}ms ease-in-out`,
           }}
-          role="status"
-          aria-label="Loading content"
         >
           {skeletonComponent}
-        </div>
+        </LoadingRegion>
       )}
 
       {/* Actual Content */}

package/src/components/docs/doc-viewer.tsx

@@ -8,6 +8,7 @@ import { findDocNodeByPath } from '../../utils/doc-tree-nav';
 import { PageShell } from '../layout/article-detail-layout';
 import { PageLayout } from '../layout/page-layout';
 import { CategorySidebarSkeleton } from '../loading/page-layout-skeleton';
+import { UnifiedSkeleton } from '../loading/unified-skeleton';
 import { MultiLevelNavigation, MobileNavigationDropdown } from '../navigation/multi-level-navigation';
 import { StickySectionNav } from '../navigation/sticky-section-nav';
 import { PersistentSidebar, PersistentMobileDropdown } from '../persistent-filter-controls';
@@ -368,7 +369,7 @@ function DocViewerContent({
                   {isMarkdownContent && (isLoadingContent || isLoadingStructure) && (
                     <div className="hidden content-lg:block">
                       <div className="sticky top-24">
-                        <div className="mb-5 h-[14px] w-28 animate-pulse rounded bg-ods-border" />
+                        <UnifiedSkeleton className="mb-5 h-[14px] w-28 rounded" />
                         <div className="space-y-0">
                           {[130, 170, 190, 220, 110, 200, 80, 100, 120, 140, 90].map((w, i) => (
                             <div
@@ -377,7 +378,7 @@ function DocViewerContent({
                                 i === 0 ? 'border-ods-accent' : 'border-transparent'
                               }`}
                             >
-                              <div className="h-[13px] animate-pulse rounded bg-ods-border" style={{ width: w }} />
+                              <UnifiedSkeleton className="h-[13px] rounded" width={w} />
                             </div>
                           ))}
                         </div>

package/src/components/docs/skeletons.tsx

@@ -1,59 +1,67 @@
+import { EmbedLoadingSkeleton } from '../embeds/embed-iframe';
+import { LoadingRegion } from '../loading/loading-region';
+import { UnifiedSkeleton } from '../loading/unified-skeleton';
 /**
  * Text-style skeleton — matches a rendered markdown article layout.
  * Used by `<DocsHubPage>` as the default for `markdown` (and unknown
  * document types). Embedders can override via `renderSkeleton`.
  */
-export function MarkdownSkeleton() {
+export function MarkdownSkeleton({
+  region = true,
+}: {
+  /** The loading state announces itself (`LoadingRegion`). `false` inside another loading region. Default `true`. */
+  region?: boolean;
+} = {}) {
   return (
-    <div className="mt-6 space-y-7">
+    <LoadingRegion label="Loading the document" announce={region} className="mt-6 space-y-7">
       <div className="space-y-[14px]">
-        <div className="h-[16px] w-full animate-pulse rounded bg-ods-border" />
-        <div className="h-[16px] w-full animate-pulse rounded bg-ods-border" />
-        <div className="h-[16px] w-full animate-pulse rounded bg-ods-border" />
-        <div className="h-[16px] w-3/4 animate-pulse rounded bg-ods-border" />
+        <UnifiedSkeleton className="h-[16px] w-full rounded" />
+        <UnifiedSkeleton className="h-[16px] w-full rounded" />
+        <UnifiedSkeleton className="h-[16px] w-full rounded" />
+        <UnifiedSkeleton className="h-[16px] w-3/4 rounded" />
       </div>
       <div className="space-y-[14px]">
-        <div className="h-[16px] w-full animate-pulse rounded bg-ods-border" />
-        <div className="h-[16px] w-full animate-pulse rounded bg-ods-border" />
-        <div className="h-[16px] w-full animate-pulse rounded bg-ods-border" />
-        <div className="h-[16px] w-5/6 animate-pulse rounded bg-ods-border" />
+        <UnifiedSkeleton className="h-[16px] w-full rounded" />
+        <UnifiedSkeleton className="h-[16px] w-full rounded" />
+        <UnifiedSkeleton className="h-[16px] w-full rounded" />
+        <UnifiedSkeleton className="h-[16px] w-5/6 rounded" />
       </div>
       <div className="space-y-[14px]">
-        <div className="h-[16px] w-full animate-pulse rounded bg-ods-border" />
-        <div className="h-[16px] w-full animate-pulse rounded bg-ods-border" />
-        <div className="h-[16px] w-full animate-pulse rounded bg-ods-border" />
-        <div className="h-[16px] w-full animate-pulse rounded bg-ods-border" />
-        <div className="h-[16px] w-2/3 animate-pulse rounded bg-ods-border" />
+        <UnifiedSkeleton className="h-[16px] w-full rounded" />
+        <UnifiedSkeleton className="h-[16px] w-full rounded" />
+        <UnifiedSkeleton className="h-[16px] w-full rounded" />
+        <UnifiedSkeleton className="h-[16px] w-full rounded" />
+        <UnifiedSkeleton className="h-[16px] w-2/3 rounded" />
       </div>
-      <div className="h-[88px] animate-pulse rounded-lg border border-ods-border bg-ods-card" />
-      <div className="h-7 w-1/3 animate-pulse rounded bg-ods-border" />
+      <UnifiedSkeleton className="h-[88px] rounded-lg border border-ods-border" />
+      <UnifiedSkeleton className="h-7 w-1/3 rounded" />
       <div className="space-y-[14px]">
-        <div className="h-[16px] w-full animate-pulse rounded bg-ods-border" />
-        <div className="h-[16px] w-full animate-pulse rounded bg-ods-border" />
-        <div className="h-[16px] w-full animate-pulse rounded bg-ods-border" />
-        <div className="h-[16px] w-[72%] animate-pulse rounded bg-ods-border" />
+        <UnifiedSkeleton className="h-[16px] w-full rounded" />
+        <UnifiedSkeleton className="h-[16px] w-full rounded" />
+        <UnifiedSkeleton className="h-[16px] w-full rounded" />
+        <UnifiedSkeleton className="h-[16px] w-[72%] rounded" />
       </div>
       <div className="space-y-[14px]">
-        <div className="h-[16px] w-full animate-pulse rounded bg-ods-border" />
-        <div className="h-[16px] w-full animate-pulse rounded bg-ods-border" />
-        <div className="h-[16px] w-full animate-pulse rounded bg-ods-border" />
-        <div className="h-[16px] w-full animate-pulse rounded bg-ods-border" />
-        <div className="h-[16px] w-[58%] animate-pulse rounded bg-ods-border" />
+        <UnifiedSkeleton className="h-[16px] w-full rounded" />
+        <UnifiedSkeleton className="h-[16px] w-full rounded" />
+        <UnifiedSkeleton className="h-[16px] w-full rounded" />
+        <UnifiedSkeleton className="h-[16px] w-full rounded" />
+        <UnifiedSkeleton className="h-[16px] w-[58%] rounded" />
       </div>
-      <div className="h-7 w-2/5 animate-pulse rounded bg-ods-border" />
+      <UnifiedSkeleton className="h-7 w-2/5 rounded" />
       <div className="space-y-[14px]">
-        <div className="h-[16px] w-full animate-pulse rounded bg-ods-border" />
-        <div className="h-[16px] w-full animate-pulse rounded bg-ods-border" />
-        <div className="h-[16px] w-[90%] animate-pulse rounded bg-ods-border" />
+        <UnifiedSkeleton className="h-[16px] w-full rounded" />
+        <UnifiedSkeleton className="h-[16px] w-full rounded" />
+        <UnifiedSkeleton className="h-[16px] w-[90%] rounded" />
       </div>
       <div className="space-y-[14px]">
-        <div className="h-[16px] w-full animate-pulse rounded bg-ods-border" />
-        <div className="h-[16px] w-full animate-pulse rounded bg-ods-border" />
-        <div className="h-[16px] w-full animate-pulse rounded bg-ods-border" />
-        <div className="h-[16px] w-[70%] animate-pulse rounded bg-ods-border" />
+        <UnifiedSkeleton className="h-[16px] w-full rounded" />
+        <UnifiedSkeleton className="h-[16px] w-full rounded" />
+        <UnifiedSkeleton className="h-[16px] w-full rounded" />
+        <UnifiedSkeleton className="h-[16px] w-[70%] rounded" />
       </div>
-      <div className="h-[88px] animate-pulse rounded-lg border border-ods-border bg-ods-card" />
-    </div>
+      <UnifiedSkeleton className="h-[88px] rounded-lg border border-ods-border" />
+    </LoadingRegion>
   );
 }
 
@@ -68,35 +76,35 @@ export function MarkdownSkeleton() {
  *   - `google_sheet`/`figma` → header with title + ONE button/toggle
  *   - `file`                 → centered FileDownloadCard-style box
  *   - undefined / others     → generic (1-button header)
- *
- * IMPORTANT: bars use `bg-ods-border` (NOT `bg-ods-skeleton`). The
- * `--ods-skeleton` token resolves to TRANSPARENT in this build, leaving
- * the skeleton box visually empty — the embed skeleton was the loudest
- * surface affected (a full-height iframe area showing nothing). Same fix
- * the chat-message-row skeleton already documents in its inline comment.
  */
 export interface EmbedSkeletonProps {
   /** When provided, the header layout matches the eventual viewer's
    *  button count + arrangement, so the layout doesn't shift on load. */
   documentType?: 'pdf' | 'google_sheet' | 'figma' | 'file' | string;
+  /** The loading state announces itself (`LoadingRegion`). `false` inside another loading region. Default `true`. */
+  region?: boolean;
 }
 
-export function EmbedSkeleton({ documentType }: EmbedSkeletonProps = {}) {
+export function EmbedSkeleton({ documentType, region = true }: EmbedSkeletonProps = {}) {
   // Centered card shape for the `file` documentType — matches
   // `<FileDownloadCard>`'s `flex flex-col items-center justify-center py-16`
   // + bordered card with icon, name, type/size row, Download button.
   if (documentType === 'file') {
     return (
-      <div className="flex flex-col items-center justify-center py-16">
+      <LoadingRegion
+        label="Loading the document"
+        announce={region}
+        className="flex flex-col items-center justify-center py-16"
+      >
         <div className="w-full max-w-md space-y-4 rounded-xl border border-ods-border bg-ods-card p-8 text-center">
-          <div className="mx-auto h-16 w-16 animate-pulse rounded bg-ods-border" />
+          <UnifiedSkeleton className="mx-auto h-16 w-16 rounded" />
           <div className="space-y-2">
-            <div className="mx-auto h-5 w-2/3 animate-pulse rounded bg-ods-border" />
-            <div className="mx-auto h-4 w-1/2 animate-pulse rounded bg-ods-border" />
+            <UnifiedSkeleton className="mx-auto h-5 w-2/3 rounded" />
+            <UnifiedSkeleton className="mx-auto h-4 w-1/2 rounded" />
           </div>
-          <div className="h-10 w-full animate-pulse rounded bg-ods-border" />
+          <UnifiedSkeleton className="h-10 w-full rounded" />
         </div>
-      </div>
+      </LoadingRegion>
     );
   }
 
@@ -105,32 +113,25 @@ export function EmbedSkeleton({ documentType }: EmbedSkeletonProps = {}) {
   const buttonCount = documentType === 'pdf' ? 2 : 1;
 
   return (
-    <div className="space-y-4">
+    <LoadingRegion label="Loading the document" announce={region} className="space-y-4">
       {/* Header — matches the actual viewer's
        *  `flex flex-col gap-3 content-sm:flex-row content-sm:items-center content-sm:justify-between`
        *  (mobile-stacked, desktop-row). */}
       <div className="flex flex-col gap-3 content-sm:flex-row content-sm:items-center content-sm:justify-between">
         {/* Left: icon + title */}
         <div className="flex min-w-0 flex-1 items-center gap-2">
-          <div className="h-5 w-5 shrink-0 animate-pulse rounded bg-ods-border" />
-          <div className="h-6 w-2/3 animate-pulse rounded bg-ods-border" />
+          <UnifiedSkeleton className="h-5 w-5 shrink-0 rounded" />
+          <UnifiedSkeleton className="h-6 w-2/3 rounded" />
         </div>
         {/* Right: 1 or 2 buttons. Mobile = full-width; desktop = auto. */}
         <div className="flex w-full items-center gap-2 content-sm:w-auto">
           {Array.from({ length: buttonCount }).map((_, i) => (
-            <div
-              key={i}
-              className="h-10 w-full flex-1 animate-pulse rounded bg-ods-border content-sm:w-32 content-sm:flex-initial"
-            />
+            <UnifiedSkeleton key={i} className="h-10 w-full flex-1 rounded content-sm:w-32 content-sm:flex-initial" />
           ))}
         </div>
       </div>
-      {/* Body — clean iframe-sized rectangle, no fake inner placeholder
-       *  cruft. Matches the viewer's default `calc(100vh - 250px)` height. */}
-      <div
-        className="w-full animate-pulse rounded-lg border border-ods-border bg-ods-card"
-        style={{ height: 'calc(100vh - 250px)' }}
-      />
-    </div>
+      {/* Body: the iframe viewer's own loading box (its default `calc(100vh - 250px)` height). */}
+      <EmbedLoadingSkeleton region={false} />
+    </LoadingRegion>
   );
 }

package/src/components/embeds/embed-iframe.tsx

@@ -2,22 +2,29 @@
 
 import type React from 'react';
 import { useState, useCallback, useRef, useEffect } from 'react';
+import { UnifiedSkeleton } from '../loading/unified-skeleton';
 
-/** Loading skeleton for iframe embeds — clean iframe-sized rectangle.
- *  Uses `bg-ods-card` (visible token) rather than `bg-ods-skeleton`
- *  which resolves to transparent in this build (the same gotcha
- *  documented in `chat-message-row.tsx`'s skeleton). No fake inner
- *  placeholder cruft — a real loading iframe shows a blank rectangle.
+/** Loading skeleton for iframe embeds: a clean iframe-sized `UnifiedSkeleton`
+ *  rectangle. No fake inner placeholder cruft: a real loading iframe shows a
+ *  blank rectangle.
  *
  *  Exported so a viewer that is still RESOLVING where its frame points
  *  (ClaudeEmbed probing for a self-hosted mirror, before it has a `src`)
  *  can render the IDENTICAL skeleton through `EmbedViewerFrame`, keeping
  *  every embed's loading state 1:1 with the Figma/Sheets/PDF viewers. */
-export function EmbedLoadingSkeleton({ height }: { height?: string }) {
+export function EmbedLoadingSkeleton({
+  height,
+  region = true,
+}: {
+  height?: string;
+  /** The box announces itself (one named status). `false` inside another loading region. Default `true`. */
+  region?: boolean;
+}) {
   return (
-    <div
-      className="w-full animate-pulse overflow-hidden rounded-lg border border-ods-border bg-ods-card"
-      style={{ height: height || 'calc(100vh - 250px)' }}
+    <UnifiedSkeleton
+      className="w-full overflow-hidden rounded-lg border border-ods-border"
+      height={height || 'calc(100vh - 250px)'}
+      aria-label={region ? 'Loading the embed' : undefined}
     />
   );
 }

package/src/components/embeds/index.ts

@@ -14,8 +14,8 @@ export type { FigmaEmbedProps } from './figma-embed';
 export { ClaudeEmbed } from './claude-embed';
 export type { ClaudeEmbedProps, ClaudeEmbedKind } from './claude-embed';
 
-export { OGLinkPreview, OGLinkErrorBoundary } from './og-link-preview';
-export type { OGLinkPreviewProps, OGData, BuildPlaceholderUrl } from './og-link-preview';
+export { OGLinkPreview, OGLinkErrorBoundary, OGLinkTileSkeleton } from './og-link-preview';
+export type { OGLinkPreviewProps, OGData } from './og-link-preview';
 
 export { FileDownloadCard } from './file-download-card';
 export type { FileDownloadCardProps } from './file-download-card';

package/src/components/embeds/linkedin-embed-client.tsx

@@ -4,6 +4,7 @@ import { ExternalLink } from 'lucide-react';
 import { useMemo, useState } from 'react';
 import Link from '../../embed-shims/next-link';
 import { LinkedinIcon } from '../icons-v2-generated/brand-logos/linkedin-icon';
+import { UnifiedSkeleton } from '../loading/unified-skeleton';
 import { LinkedInContainer } from './embed-container';
 
 /**
@@ -61,17 +62,17 @@ export function LinkedInEmbedClient({ url, height = 600 }: LinkedInEmbedProps) {
     <LinkedInContainer>
       <div className="relative w-full" style={{ height }}>
         {!loaded && (
-          <div className="absolute inset-0 animate-pulse p-6">
+          <div className="absolute inset-0 p-6">
             <div className="mb-4 flex items-center space-x-3">
-              <div className="h-12 w-12 rounded-full bg-ods-border" />
+              <UnifiedSkeleton className="h-12 w-12 rounded-full" />
               <div>
-                <div className="mb-2 h-4 w-32 rounded bg-ods-border" />
-                <div className="h-3 w-24 rounded bg-ods-border" />
+                <UnifiedSkeleton className="mb-2 h-4 w-32 rounded" />
+                <UnifiedSkeleton className="h-3 w-24 rounded" />
               </div>
             </div>
             <div className="space-y-2">
-              <div className="h-4 w-full rounded bg-ods-border" />
-              <div className="h-4 w-3/4 rounded bg-ods-border" />
+              <UnifiedSkeleton className="h-4 w-full rounded" />
+              <UnifiedSkeleton className="h-4 w-3/4 rounded" />
             </div>
           </div>
         )}

package/src/components/embeds/markdown-image.tsx

@@ -2,6 +2,7 @@
 
 import { useEffect, useState } from 'react';
 import Image from '../../embed-shims/next-image';
+import { UnifiedSkeleton } from '../loading/unified-skeleton';
 import { useRichMarkdownRuntime } from './rich-markdown-runtime';
 
 /**
@@ -63,9 +64,10 @@ export function MarkdownImage({ src, alt }: { src: string; alt?: string }) {
   // Reserve a neutral box while probing so the layout doesn't jump when the image appears.
   if (!ratio) {
     return (
-      <span
-        className="mx-auto my-2 block w-full max-w-full animate-pulse rounded-lg bg-ods-card"
-        style={{ aspectRatio: '3 / 2', maxHeight: `${MAX_H_REM}rem` }}
+      <UnifiedSkeleton
+        as="span"
+        className="mx-auto my-2 block aspect-[3/2] w-full max-w-full rounded-lg"
+        style={{ maxHeight: `${MAX_H_REM}rem` }}
         aria-hidden
       />
     );