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

package/src/components/shared/roadmap/roadmap-grid-skeleton.tsx

@@ -1,60 +1,14 @@
+import { RoadmapCardSkeleton } from '../../chat/entity-cards/roadmap-card';
+import { LoadingRegion } from '../../loading/loading-region';
 /**
- * RoadmapGridSkeleton — loading state for the `/roadmap` grid view.
- *
- * Pure JSX (no hooks, no events) — `'use client'` not strictly required
- * here; tsup's client-entry banner injects it automatically when this
- * file is bundled into the client output. We match the playbook's
- * skeleton-file convention (no directive when no hooks).
- *
- * NOTE: lib's `chat/entity-cards/roadmap-card.tsx` also exports a
- * `RoadmapCardSkeleton` — that one is the COMPACT 56px chat-card
- * variant. This file's internal card-skeleton (340px grid card)
- * intentionally stays file-internal to avoid the naming collision;
- * only `RoadmapGridSkeleton` is exported.
+ * RoadmapGridSkeleton: loading state for the `/roadmap` grid view. The grid
+ * renders `RoadmapCard`, so each placeholder is that card's own loading box,
+ * `RoadmapCardSkeleton`.
  */
 
-function RoadmapCardSkeleton() {
-  return (
-    <div className="relative flex min-h-[340px] flex-col gap-[16px] rounded-[6px] border border-ods-border bg-ods-card p-[24px]">
-      {/* Status Badge Skeleton - Top Right */}
-      <div className="absolute right-[24px] top-[24px]">
-        <div className="h-[20px] w-[80px] animate-pulse rounded bg-ods-border"></div>
-      </div>
-
-      {/* Icon and title skeleton */}
-      <div className="flex items-center gap-[16px] pr-[120px]">
-        <div className="h-[80px] w-[80px] flex-shrink-0 animate-pulse rounded-lg bg-ods-border"></div>
-        <div className="flex min-w-0 flex-1 flex-col gap-1">
-          <div className="flex min-h-[48px] items-center">
-            <div className="h-[24px] w-full animate-pulse rounded bg-ods-border"></div>
-          </div>
-          <div className="flex min-h-[20px] items-center">
-            <div className="h-[14px] w-1/2 animate-pulse rounded bg-ods-border"></div>
-          </div>
-        </div>
-      </div>
-
-      {/* Description skeleton - exactly 3 lines */}
-      <div className="flex min-h-[72px] items-center">
-        <div className="w-full space-y-2">
-          <div className="h-[24px] animate-pulse rounded bg-ods-border"></div>
-          <div className="h-[24px] animate-pulse rounded bg-ods-border"></div>
-          <div className="h-[24px] w-4/5 animate-pulse rounded bg-ods-border"></div>
-        </div>
-      </div>
-
-      <div className="flex-1"></div>
-
-      {/* Bottom skeleton */}
-      <div className="flex items-center justify-between">
-        <div className="h-[48px] w-[120px] animate-pulse rounded bg-ods-border"></div>
-        <div className="h-[32px] w-[100px] animate-pulse rounded bg-ods-border"></div>
-      </div>
-    </div>
-  );
-}
-
 export interface RoadmapGridSkeletonProps {
+  /** The loading state announces itself (`LoadingRegion`). `false` inside another loading region. Default `true`. */
+  region?: boolean;
   /** Number of skeleton cards to show. Default 4. */
   count?: number;
   /** Show the desktop left margin (~120px) that aligns the grid with
@@ -63,12 +17,16 @@ export interface RoadmapGridSkeletonProps {
   showLeftMargin?: boolean;
 }
 
-export function RoadmapGridSkeleton({ count = 4, showLeftMargin = true }: RoadmapGridSkeletonProps) {
+export function RoadmapGridSkeleton({ region = true, count = 4, showLeftMargin = true }: RoadmapGridSkeletonProps) {
   return (
-    <div className={`grid grid-cols-1 gap-6 content-md:grid-cols-2 ${showLeftMargin ? 'content-md:ml-[120px]' : ''}`}>
+    <LoadingRegion
+      label="Loading the roadmap"
+      announce={region}
+      className={`grid grid-cols-1 gap-6 content-md:grid-cols-2 ${showLeftMargin ? 'content-md:ml-[120px]' : ''}`}
+    >
       {Array.from({ length: count }).map((_, i) => (
         <RoadmapCardSkeleton key={i} />
       ))}
-    </div>
+    </LoadingRegion>
   );
 }

package/src/components/tickets/help-center-create-form.tsx

@@ -27,6 +27,8 @@
 
 import { useState, type ChangeEvent } from 'react';
 import { ContactForm } from '../contact';
+import { LoadingRegion } from '../loading/loading-region';
+import { UnifiedSkeleton } from '../loading/unified-skeleton';
 import { Input, Label } from '../ui';
 import { RequiredMark } from '../ui/required-mark';
 import type { UseTicketActionsReturn } from './hooks/use-ticket-actions';
@@ -91,14 +93,23 @@ export interface HelpCenterCreateFormProps {
  * the spacing rule fires identically — without them the whole stack
  * shifts up 24px on every page load.
  */
-export function HelpCenterCreateFormSkeleton() {
+export function HelpCenterCreateFormSkeleton({
+  region = true,
+}: {
+  /** The loading state announces itself (`LoadingRegion`). `false` inside another loading region. Default `true`. */
+  region?: boolean;
+} = {}) {
   return (
-    <div className="flex h-full flex-col rounded-2xl border border-ods-border p-6 content-md:rounded-3xl content-md:p-8 content-lg:p-10">
+    <LoadingRegion
+      label="Loading the form"
+      announce={region}
+      className="flex h-full flex-col rounded-2xl border border-ods-border p-6 content-md:rounded-3xl content-md:p-8 content-lg:p-10"
+    >
       {/* Heading container — mirrors `mb-6 content-md:mb-8` + h2 with its own
           `mb-3 content-md:mb-4` and `text-h2` height (32px font, line-height
           ~1.25 → 40px). h-10 bar matches the rendered h2 height. */}
       <div className="mb-6 content-md:mb-8">
-        <div className="mb-3 h-10 w-72 animate-pulse rounded bg-ods-border content-md:mb-4" />
+        <UnifiedSkeleton className="mb-3 h-10 w-72 rounded content-md:mb-4" />
       </div>
 
       {/* Form body — same `space-y-4 content-md:space-y-6` gap stack.
@@ -124,8 +135,8 @@ export function HelpCenterCreateFormSkeleton() {
             height: 27 + 4 + 48 (h-12 input) = 79px, identical to
             real form. */}
         <div className="flex flex-col">
-          <div className="mb-1 h-[27px] w-20 animate-pulse rounded bg-ods-border" />
-          <div className="h-12 w-full animate-pulse rounded bg-ods-border" />
+          <UnifiedSkeleton className="mb-1 h-[27px] w-20 rounded" />
+          <UnifiedSkeleton className="h-12 w-full rounded" />
         </div>
 
         {/* Message section — `flex flex-col flex-grow` matches real
@@ -135,8 +146,8 @@ export function HelpCenterCreateFormSkeleton() {
             below it. Same `h-[27px]` + `mb-1` Label pattern as Subject:
             27 + 4 + 96 = 127px, identical to real form. */}
         <div className="flex flex-grow flex-col">
-          <div className="mb-1 h-[27px] w-32 animate-pulse rounded bg-ods-border" />
-          <div className="h-24 w-full flex-grow animate-pulse rounded bg-ods-border" />
+          <UnifiedSkeleton className="mb-1 h-[27px] w-32 rounded" />
+          <UnifiedSkeleton className="h-24 w-full flex-grow rounded" />
         </div>
 
         {/* Attachments row — mirrors the real `flex flex-col gap-2`
@@ -144,8 +155,8 @@ export function HelpCenterCreateFormSkeleton() {
             the h-7 add button + helper text. */}
         <div className="flex flex-col gap-2">
           <div className="flex items-center gap-2">
-            <div className="h-7 w-7 shrink-0 animate-pulse rounded bg-ods-border" />
-            <div className="h-4 w-40 animate-pulse rounded bg-ods-border" />
+            <UnifiedSkeleton className="h-7 w-7 shrink-0 rounded" />
+            <UnifiedSkeleton className="h-4 w-40 rounded" />
           </div>
         </div>
 
@@ -153,11 +164,11 @@ export function HelpCenterCreateFormSkeleton() {
             Button bar is h-12 to match the real `<Button>` height
             (48px). */}
         <div className="mt-auto flex w-full flex-col items-center justify-end gap-4 pt-2 content-md:flex-row content-md:gap-6">
-          <div className="h-4 w-72 animate-pulse rounded bg-ods-border" />
-          <div className="h-12 w-32 animate-pulse rounded bg-ods-border" />
+          <UnifiedSkeleton className="h-4 w-72 rounded" />
+          <UnifiedSkeleton className="h-12 w-32 rounded" />
         </div>
       </div>
-    </div>
+    </LoadingRegion>
   );
 }
 

package/src/components/tickets/ticket-center.tsx

@@ -23,9 +23,10 @@ import { formatRelativeTime } from '../../utils/date-utils';
 import { devSectionAnchorId } from '../../utils/dev-sections/dev-section-param-keys';
 import { useChatIdentity } from '../chat/hooks/use-chat-identity';
 import { EmptyState } from '../empty-state';
+import { LoadingRegion } from '../loading/loading-region';
+import { UnifiedSkeleton } from '../loading/unified-skeleton';
 import { Button } from '../ui/button';
 import { Card } from '../ui/card';
-import { Skeleton } from '../ui/skeleton';
 import { useTicketActions } from './hooks/use-ticket-actions';
 import { useTicketsList } from './hooks/use-tickets-list';
 import { TicketOpenForm } from './ticket-open-form';
@@ -178,16 +179,21 @@ function TicketCenterAuthed({
   );
 }
 
-function TicketCenterSkeleton() {
+function TicketCenterSkeleton({
+  region = true,
+}: {
+  /** The loading state announces itself (`LoadingRegion`). `false` inside another loading region. Default `true`. */
+  region?: boolean;
+} = {}) {
   return (
-    <div className="flex flex-col gap-6">
+    <LoadingRegion label="Loading tickets" announce={region} className="flex flex-col gap-6">
       <Card className="p-6">
-        <Skeleton className="mb-4 h-7 w-48" />
-        <Skeleton className="mb-3 h-10 w-full" />
-        <Skeleton className="h-24 w-full" />
+        <UnifiedSkeleton className="mb-4 h-7 w-48" />
+        <UnifiedSkeleton className="mb-3 h-10 w-full" />
+        <UnifiedSkeleton className="h-24 w-full" />
       </Card>
       <TicketListSkeleton />
-    </div>
+    </LoadingRegion>
   );
 }
 
@@ -197,11 +203,11 @@ function TicketListSkeleton() {
       {[0, 1, 2].map(i => (
         <div key={i} className="flex h-20 items-center gap-4 border-b border-ods-border px-4 last:border-b-0">
           <div className="flex flex-1 flex-col gap-2">
-            <Skeleton className="h-4 w-2/3" />
-            <Skeleton className="h-3 w-full" />
+            <UnifiedSkeleton className="h-4 w-2/3" />
+            <UnifiedSkeleton className="h-3 w-full" />
           </div>
-          <Skeleton className="h-8 w-20" />
-          <Skeleton className="h-8 w-16" />
+          <UnifiedSkeleton className="h-8 w-20" />
+          <UnifiedSkeleton className="h-8 w-16" />
         </div>
       ))}
     </Card>

package/src/components/tickets/ticket-detail-drawer.tsx

@@ -23,6 +23,7 @@
 
 import { useEffect, useRef } from 'react';
 import { useStickToBottom } from 'use-stick-to-bottom';
+import { LoadingRegion } from '../loading/loading-region';
 import { formatRelativeTime } from './../../utils/date-utils';
 import { ChatMessageRow, ChatMessageRowSkeleton } from './../chat/chat-message-row';
 import { useChatIdentity } from './../chat/hooks/use-chat-identity';
@@ -297,11 +298,11 @@ function TicketTimelinePanel({ ticket }: { ticket: AnyTicket }) {
     // the skeleton would snap-to-bottom on skeleton height, then again on content).
     return (
       <div className={`${TICKET_FEED_FRAME} ${TICKET_FEED_HEIGHT}`}>
-        <div className={TICKET_FEED_INNER}>
+        <LoadingRegion label="Loading messages" className={TICKET_FEED_INNER}>
           {Array.from({ length: TICKET_FEED_SKELETON_ROWS }, (_, i) => (
             <ChatMessageRowSkeleton key={i} />
           ))}
-        </div>
+        </LoadingRegion>
       </div>
     );
   }

package/src/components/ui/admin-form-drawer.tsx

@@ -2,10 +2,11 @@
 
 import { useId, useState, type ReactNode } from 'react';
 import { HUBSPOT_DO_NOT_COLLECT_FORM_PROPS } from '../../utils/hubspot-collected-forms';
+import { LoadingRegion } from '../loading/loading-region';
+import { UnifiedSkeleton } from '../loading/unified-skeleton';
 import { Button } from './button';
 import { Drawer, DrawerBody, DrawerContent, DrawerDescription, DrawerHeader, DrawerTitle } from './drawer';
 import { UnsavedChangesChip } from './modal-guarded-close';
-import { Skeleton } from './skeleton';
 
 const SKELETON_FIELD_WIDTHS = ['w-24', 'w-32', 'w-20', 'w-40', 'w-28', 'w-36'];
 
@@ -117,15 +118,14 @@ export function AdminFormDrawer({
             }}
           >
             {loading ? (
-              <div aria-busy="true" className="flex flex-col gap-[var(--spacing-system-lf)]">
-                <span className="sr-only">Loading</span>
+              <LoadingRegion label="Loading" className="flex flex-col gap-[var(--spacing-system-lf)]">
                 {SKELETON_FIELD_WIDTHS.map((labelWidth, i) => (
-                  <div key={i} className="space-y-[var(--spacing-system-xsf)]" aria-hidden="true">
-                    <Skeleton className={`h-4 ${labelWidth}`} />
-                    <Skeleton className="h-10 w-full" />
+                  <div key={i} className="space-y-[var(--spacing-system-xsf)]">
+                    <UnifiedSkeleton className={`h-4 ${labelWidth}`} />
+                    <UnifiedSkeleton className="h-10 w-full" />
                   </div>
                 ))}
-              </div>
+              </LoadingRegion>
             ) : (
               children
             )}

package/src/components/ui/admin-form-modal.tsx

@@ -2,6 +2,8 @@
 
 import { useId, type ReactNode } from 'react';
 import { HUBSPOT_DO_NOT_COLLECT_FORM_PROPS } from '../../utils/hubspot-collected-forms';
+import { LoadingRegion } from '../loading/loading-region';
+import { UnifiedSkeleton } from '../loading/unified-skeleton';
 import { Button } from './button';
 import { UnsavedChangesChip, useGuardedClose } from './modal-guarded-close';
 import {
@@ -13,7 +15,6 @@ import {
   ModalV2TwoColumn,
   type ModalV2Size,
 } from './modal-v2';
-import { Skeleton } from './skeleton';
 
 /**
  * Label widths for the loading placeholder. Uneven on purpose — a column of
@@ -174,10 +175,11 @@ export function AdminFormModal({
           // the modal doesn't visibly re-flow when the entity lands.
           <ModalV2Content>
             {loadingContent ? (
-              <div aria-busy="true">{loadingContent}</div>
+              // The one announcement: a `loadingContent` with a region of its own takes `region={false}`.
+              <LoadingRegion label="Loading">{loadingContent}</LoadingRegion>
             ) : (
-              <div
-                aria-busy="true"
+              <LoadingRegion
+                label="Loading"
                 className={
                   // Mirrors the PANEL WIDTH, not the slot API. `wide` covers the
                   // master-detail modals too (seo-redirect, managed-repo,
@@ -189,18 +191,17 @@ export function AdminFormModal({
                     : 'grid grid-cols-1 gap-[var(--spacing-system-xl)]'
                 }
               >
-                <span className="sr-only">Loading…</span>
                 {Array.from({ length: skeletonColumns }, (_, col) => (
                   <div key={col} className="space-y-[var(--spacing-system-lf)]" aria-hidden="true">
                     {SKELETON_FIELD_WIDTHS.map((labelWidth, i) => (
                       <div key={i} className="space-y-[var(--spacing-system-xsf)]">
-                        <Skeleton className={`h-4 ${labelWidth}`} />
-                        <Skeleton className="h-10 w-full" />
+                        <UnifiedSkeleton className={`h-4 ${labelWidth}`} />
+                        <UnifiedSkeleton className="h-10 w-full" />
                       </div>
                     ))}
                   </div>
                 ))}
-              </div>
+              </LoadingRegion>
             )}
           </ModalV2Content>
         ) : twoColumn ? (

package/src/components/ui/analyzing-state.tsx

@@ -1,6 +1,6 @@
 import { cn } from '../../utils/cn';
 import { ChatTypingIndicator } from '../chat/chat-typing-indicator';
-import { Skeleton } from './skeleton';
+import { UnifiedSkeleton } from '../loading/unified-skeleton';
 
 export interface AnalyzingStateProps {
   /** What is being worked on, as a sentence with no closing mark ("Mingo is analyzing your logs"). */
@@ -19,7 +19,7 @@ const ROW_STAGGER_MS = 200;
  * and the chat's own typing dots. It says an agent is at work, where a bare
  * sentence in an empty box reads as idle.
  *
- * Built from the shared pieces only: `Skeleton` for the rows and
+ * Built from the shared pieces only: `UnifiedSkeleton` for the rows and
  * `ChatTypingIndicator` for the dots. Still under reduced motion. It is
  * announced as a status; the rows and dots are decoration.
  */
@@ -37,12 +37,9 @@ export function AnalyzingState({ label, className }: AnalyzingStateProps) {
                 opacity,
               )}
             >
-              <Skeleton
-                className="h-2 w-2 shrink-0 rounded-full bg-ods-flamingo-cyan motion-reduce:animate-none"
-                style={delay}
-              />
-              <Skeleton className="h-2.5 min-w-0 flex-1 motion-reduce:animate-none" style={delay} />
-              <Skeleton className="h-2.5 w-12 shrink-0 motion-reduce:animate-none" style={delay} />
+              <UnifiedSkeleton className="h-2 w-2 shrink-0 rounded-full bg-ods-flamingo-cyan" style={delay} />
+              <UnifiedSkeleton className="h-2.5 min-w-0 flex-1" style={delay} />
+              <UnifiedSkeleton className="h-2.5 w-12 shrink-0" style={delay} />
             </div>
           );
         })}

package/src/components/ui/content-loader.tsx

@@ -1,6 +1,8 @@
 'use client';
 
 import { cn } from '../../utils/cn';
+import { LoadingRegion } from '../loading/loading-region';
+import { UnifiedSkeleton } from '../loading/unified-skeleton';
 
 export interface ContentLoaderProps {
   /**
@@ -23,6 +25,10 @@ export interface ContentLoaderProps {
    * Container CSS classes
    */
   containerClassName?: string;
+  /** What is loading, read once by a screen reader. Default "Loading". */
+  label?: string;
+  /** The loading state announces itself (`LoadingRegion`). `false` inside another loading region. Default `true`. */
+  region?: boolean;
 }
 
 /**
@@ -35,35 +41,37 @@ export function ContentLoader({
   showTitle = true,
   className,
   containerClassName,
+  label = 'Loading',
+  region = true,
 }: ContentLoaderProps) {
   const renderCardSkeleton = () => (
-    <div className="animate-pulse">
-      {showTitle && <div className="mb-6 h-8 w-64 rounded bg-ods-skeleton" />}
+    <div>
+      {showTitle && <UnifiedSkeleton className="mb-6 h-8 w-64 rounded" />}
       <div className="rounded-lg border border-ods-border bg-ods-card p-6">
         <div className="mb-6 grid grid-cols-1 gap-6 content-md:grid-cols-4">
           {Array.from({ length: items }).map((_, i) => (
             <div key={i}>
-              <div className="mb-2 h-4 w-20 rounded bg-ods-skeleton" />
-              <div className="h-6 w-32 rounded bg-ods-skeleton" />
+              <UnifiedSkeleton className="mb-2 h-4 w-20 rounded" />
+              <UnifiedSkeleton className="h-6 w-32 rounded" />
             </div>
           ))}
         </div>
         <div className="border-t border-ods-border pt-4">
-          <div className="h-4 w-64 rounded bg-ods-skeleton" />
+          <UnifiedSkeleton className="h-4 w-64 rounded" />
         </div>
       </div>
     </div>
   );
 
   const renderFormSkeleton = () => (
-    <div className="animate-pulse">
-      {showTitle && <div className="mb-6 h-8 w-64 rounded bg-ods-card" />}
+    <div>
+      {showTitle && <UnifiedSkeleton className="mb-6 h-8 w-64 rounded" />}
       <div className="rounded-lg bg-ods-card p-6">
         <div className="space-y-4">
           {Array.from({ length: items }).map((_, i) => (
             <div key={i}>
-              <div className="mb-2 h-4 w-32 rounded bg-ods-skeleton" />
-              <div className="h-10 rounded bg-ods-skeleton" />
+              <UnifiedSkeleton className="mb-2 h-4 w-32 rounded" />
+              <UnifiedSkeleton className="h-10 rounded" />
             </div>
           ))}
         </div>
@@ -72,23 +80,23 @@ export function ContentLoader({
   );
 
   const renderDetailSkeleton = () => (
-    <div className="animate-pulse">
-      {showTitle && <div className="mb-6 h-8 w-64 rounded bg-ods-skeleton" />}
+    <div>
+      {showTitle && <UnifiedSkeleton className="mb-6 h-8 w-64 rounded" />}
       <div className="rounded-lg border border-ods-border bg-ods-card p-6">
         <div className="grid grid-cols-1 gap-6 content-lg:grid-cols-3">
           <div className="content-lg:col-span-2">
-            <div className="mb-4 h-64 rounded bg-ods-skeleton" />
+            <UnifiedSkeleton className="mb-4 h-64 rounded" />
             <div className="space-y-2">
               {Array.from({ length: 3 }).map((_, i) => (
-                <div key={i} className="h-4 rounded bg-ods-skeleton" />
+                <UnifiedSkeleton key={i} className="h-4 rounded" />
               ))}
             </div>
           </div>
           <div>
-            <div className="mb-4 h-32 rounded bg-ods-skeleton" />
+            <UnifiedSkeleton className="mb-4 h-32 rounded" />
             <div className="space-y-2">
               {Array.from({ length: items }).map((_, i) => (
-                <div key={i} className="h-3 rounded bg-ods-skeleton" />
+                <UnifiedSkeleton key={i} className="h-3 rounded" />
               ))}
             </div>
           </div>
@@ -98,17 +106,17 @@ export function ContentLoader({
   );
 
   const renderListSkeleton = () => (
-    <div className="animate-pulse space-y-3">
-      {showTitle && <div className="mb-6 h-8 w-64 rounded bg-ods-skeleton" />}
+    <div className="space-y-3">
+      {showTitle && <UnifiedSkeleton className="mb-6 h-8 w-64 rounded" />}
       {Array.from({ length: items }).map((_, i) => (
         <div key={i} className="rounded-lg border border-ods-border bg-ods-card p-4">
           <div className="flex items-center gap-4">
-            <div className="h-12 w-12 rounded bg-ods-skeleton" />
+            <UnifiedSkeleton className="h-12 w-12 rounded" />
             <div className="flex-1">
-              <div className="mb-2 h-4 w-3/4 rounded bg-ods-skeleton" />
-              <div className="h-3 w-1/2 rounded bg-ods-skeleton" />
+              <UnifiedSkeleton className="mb-2 h-4 w-3/4 rounded" />
+              <UnifiedSkeleton className="h-3 w-1/2 rounded" />
             </div>
-            <div className="h-8 w-20 rounded bg-ods-skeleton" />
+            <UnifiedSkeleton className="h-8 w-20 rounded" />
           </div>
         </div>
       ))}
@@ -130,9 +138,9 @@ export function ContentLoader({
   };
 
   return (
-    <div className={cn('p-6', containerClassName)}>
+    <LoadingRegion label={label} announce={region} className={cn('p-6', containerClassName)}>
       <div className={cn(className)}>{renderSkeleton()}</div>
-    </div>
+    </LoadingRegion>
   );
 }