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

package/src/components/ui/index.ts

@@ -65,6 +65,9 @@ export * from './badge';
 export * from './ai-generated-badge';
 export * from './fade-preview';
 export * from './layout-hold';
+export * from './skeleton-surface';
+export * from './input-styles';
+export * from './loading-scope';
 export * from './progress';
 export * from './release-changelog-section';
 export * from './stacked-rows-panel';
@@ -127,6 +130,8 @@ export * from './avatar-stack';
 export * from './people-cell';
 export * from './deleted-user-avatar';
 export * from './square-avatar';
+// THE sizes of the library's components (avatars, icons, tiles, media, text rows).
+export * from '../../styles/component-sizes';
 export * from './tab-selector';
 export * from './tag';
 export * from './title-content-block';
@@ -181,7 +186,7 @@ export type {
 } from './query-report-table';
 
 // Pagination components
-export { CursorPagination, CursorPaginationSimple } from './cursor-pagination';
+export { CursorPagination, CursorPaginationSimple, CursorPaginationSkeleton } from './cursor-pagination';
 export type { CursorPaginationProps } from './cursor-pagination';
 
 // DataTable (headless, TanStack Table-based) — replacement for legacy `Table`.
@@ -253,3 +258,18 @@ export * from './super-user-banner-view';
 export { RequiredMark } from './required-mark';
 export { IconTile } from './icon-tile';
 export { PolicyLink } from './policy-link';
+export type { DateRange } from 'react-day-picker';
+export { TitleBlock, TITLE_BLOCK_MIN_HEIGHT } from '../layout/title-block';
+export type { TitleBlockProps, TitleSkeletonLines } from '../layout/title-block';
+export type { SortableColumn, SortConfig, SortDirection } from './sort-column-item';
+export {
+  ORGANIZATION_CARD_RADIUS_CLASS,
+  ORGANIZATION_CARD_LAYOUT_CLASS,
+  ORGANIZATION_CARD_SURFACE_CLASS,
+  ORGANIZATION_CARD_HEADER_CLASS,
+  ORGANIZATION_CARD_TEXT_CLASS,
+  ORGANIZATION_CARD_DESCRIPTION_CLASS,
+  ORGANIZATION_CARD_FOOTER_CLASS,
+  ORGANIZATION_CARD_STATS_CLASS,
+  ORGANIZATION_CARD_STAT_CLASS,
+} from '../loading/organization-card-skeleton';

package/src/components/ui/info-card-row.tsx

@@ -1,5 +1,9 @@
+'use client';
+
 import type { ReactNode } from 'react';
 import { cn } from '../../utils/cn';
+import { TextLineSkeleton, UnifiedSkeleton } from '../loading/unified-skeleton';
+import { useLoadingScope } from './loading-scope';
 
 export interface InfoCardRowSection {
   title: string;
@@ -16,11 +20,23 @@ export interface InfoCardRowProps {
 const CELL =
   'flex items-center gap-[var(--spacing-system-s)] min-w-0 p-[var(--spacing-system-xsf)] content-md:p-[var(--spacing-system-m)] min-h-[60px] content-md:min-h-[76px]';
 
+/** The row's frame, lead and stat cells, read by the row and by its skeleton. */
+const FRAME_CLASS =
+  'flex shrink-0 flex-col overflow-hidden rounded-md border border-ods-border bg-ods-card content-md:flex-row';
+const LEAD_CELL_CLASS = 'border-b border-ods-border content-md:flex-1 content-md:border-b-0 content-md:border-r';
+const LEAD_ICON_CLASS =
+  'flex size-10 shrink-0 items-center justify-center overflow-hidden rounded-sm border border-ods-border [&>*]:size-full [&_img]:object-cover';
+const LEAD_TEXT_CLASS = 'flex min-w-0 flex-1 flex-col justify-center';
+const STATS_CLASS = 'flex content-md:flex-1';
+const STAT_DIVIDER_CLASS = 'border-r border-ods-border';
+const STAT_TEXT_CLASS = 'flex min-w-0 flex-1 flex-col';
+const STAT_TITLE_CLASS = 'truncate uppercase text-ods-text-secondary text-h5';
+
 function StatCell({ section, className }: { section: InfoCardRowSection; className?: string }) {
   return (
     <div className={cn(CELL, 'flex-1', className)}>
-      <div className="flex min-w-0 flex-1 flex-col">
-        <p className="truncate uppercase text-ods-text-secondary text-h5">{section.title}</p>
+      <div className={STAT_TEXT_CLASS}>
+        <p className={STAT_TITLE_CLASS}>{section.title}</p>
         <div className="flex min-w-0 items-center gap-[var(--spacing-system-s)]">
           <p className="min-w-0 flex-1 truncate text-ods-text-primary text-h3">{section.caption}</p>
           {section.icon && (
@@ -36,31 +52,70 @@ function StatCell({ section, className }: { section: InfoCardRowSection; classNa
 }
 
 export function InfoCardRow({ lead, stats, className }: InfoCardRowProps) {
+  // In a page's loading state the row's figures are read (its lead title is empty): the row is its skeleton.
+  const inScope = useLoadingScope();
+  if (inScope && !lead.title) {
+    return (
+      <InfoCardRowSkeleton
+        leadIcon={Boolean(lead.icon)}
+        statTitles={[stats[0].title, stats[1].title]}
+        className={className}
+      />
+    );
+  }
   return (
-    <div
-      className={cn(
-        'flex shrink-0 flex-col overflow-hidden rounded-md border border-ods-border bg-ods-card content-md:flex-row',
-        className,
-      )}
-    >
-      <div
-        className={cn(CELL, 'border-b border-ods-border content-md:flex-1 content-md:border-b-0 content-md:border-r')}
-      >
-        {lead.icon && (
-          <div className="flex size-10 shrink-0 items-center justify-center overflow-hidden rounded-sm border border-ods-border [&>*]:size-full [&_img]:object-cover">
-            {lead.icon}
-          </div>
-        )}
-        <div className="flex min-w-0 flex-1 flex-col justify-center">
+    <div className={cn(FRAME_CLASS, className)}>
+      <div className={cn(CELL, LEAD_CELL_CLASS)}>
+        {lead.icon && <div className={LEAD_ICON_CLASS}>{lead.icon}</div>}
+        <div className={LEAD_TEXT_CLASS}>
           <p className="truncate text-ods-text-primary text-h3">{lead.title}</p>
           <p className="truncate text-ods-text-secondary text-h6">{lead.caption}</p>
         </div>
       </div>
 
-      <div className="flex content-md:flex-1">
-        <StatCell section={stats[0]} className="border-r border-ods-border" />
+      <div className={STATS_CLASS}>
+        <StatCell section={stats[0]} className={STAT_DIVIDER_CLASS} />
         <StatCell section={stats[1]} />
       </div>
     </div>
   );
 }
+
+/**
+ * An InfoCardRow while its figures are read: the same frame and cells, the lead's picture a box and its two
+ * lines bars, each stat's caption a `text-h3` bar under its title (the page's own label, drawn for real when it
+ * is given, else a bar).
+ */
+export function InfoCardRowSkeleton({
+  leadIcon = true,
+  statTitles = ['', ''],
+  className,
+}: {
+  /** The loaded row leads with a picture. Default `true`. */
+  leadIcon?: boolean;
+  /** The stats' own titles (static labels). Empty ones are bars. */
+  statTitles?: [string, string];
+  className?: string;
+}) {
+  return (
+    <div className={cn(FRAME_CLASS, className)} aria-hidden>
+      <div className={cn(CELL, LEAD_CELL_CLASS)}>
+        {leadIcon && <UnifiedSkeleton className={LEAD_ICON_CLASS} />}
+        <div className={LEAD_TEXT_CLASS}>
+          <TextLineSkeleton type="h3" className="w-1/2" />
+          <TextLineSkeleton type="h6" className="w-1/3" />
+        </div>
+      </div>
+      <div className={STATS_CLASS}>
+        {statTitles.map((title, index) => (
+          <div key={index} className={cn(CELL, 'flex-1', index === 0 && STAT_DIVIDER_CLASS)}>
+            <div className={STAT_TEXT_CLASS}>
+              {title ? <p className={STAT_TITLE_CLASS}>{title}</p> : <TextLineSkeleton type="h5" className="w-16" />}
+              <TextLineSkeleton type="h3" className="w-20" />
+            </div>
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+}

package/src/components/ui/info-card.tsx

@@ -6,7 +6,9 @@ import { useCopyToClipboard } from '../../hooks';
 import { cn } from '../../utils/cn';
 import { CheckIcon } from '../icons-v2-generated';
 import { Copy01Icon } from '../icons-v2-generated/documents';
-import { ProgressBar } from './progress-bar';
+import { TextLineSkeleton } from '../loading/unified-skeleton';
+import { useLoadingScope } from './loading-scope';
+import { ProgressBar, ProgressBarSkeleton } from './progress-bar';
 
 export interface InfoCardFooterData {
   /** Leading icon next to the text, expected at 24x24 (e.g. <ShieldCheckIcon size={24} />) */
@@ -46,21 +48,49 @@ export interface InfoCardData {
 interface InfoCardProps {
   data: InfoCardData;
   className?: string;
+  /** The shape drawn while the data is read (a page's loading state, where `data.items` is empty). */
+  skeleton?: InfoCardSkeletonShape;
 }
 
-export function InfoCard({ data, className = '' }: InfoCardProps) {
+/** What a loading InfoCard draws: its rows, and whether it carries a head, a progress bar and a footer. */
+export interface InfoCardSkeletonShape {
+  /** Value rows drawn. Default {@link INFO_CARD_SKELETON_ROWS}. */
+  rows?: number;
+  /** A title line. Default `true`. */
+  title?: boolean;
+  /** A subtitle line. */
+  subtitle?: boolean;
+  progress?: boolean;
+  footer?: boolean;
+}
+
+/** Rows a loading card draws when its caller names no count. */
+export const INFO_CARD_SKELETON_ROWS = 3;
+
+/** The card's frame and groups, read by the card and by its skeleton. */
+const FRAME_CLASS = 'flex w-full flex-col overflow-hidden rounded-md border border-ods-border bg-ods-card';
+const CONTENT_CLASS = 'flex w-full flex-col items-start gap-[var(--spacing-system-l)] p-[var(--spacing-system-m)]';
+const HEAD_CLASS = 'flex w-full flex-col items-start self-stretch';
+const HEAD_LINE_CLASS = 'flex items-center gap-[var(--spacing-system-xsf)] self-stretch';
+const ROWS_CLASS = 'flex w-full flex-col items-start gap-[var(--spacing-system-xs)] self-stretch';
+const VALUE_ROW_CLASS = 'flex h-6 w-full items-center gap-[var(--spacing-system-xs)] self-stretch';
+const DIVIDER_CLASS = 'h-px flex-1 bg-ods-divider';
+const FOOTER_CLASS = 'mt-auto flex w-full flex-col border-t border-ods-border p-[var(--spacing-system-m)]';
+
+export function InfoCard({ data, className = '', skeleton }: InfoCardProps) {
+  // In a page's loading state with no rows yet (they are read) the card is its skeleton.
+  const inScope = useLoadingScope();
+  if (inScope && data.items.length === 0) return <InfoCardSkeleton {...skeleton} className={className} />;
   return (
-    <div
-      className={cn('flex w-full flex-col overflow-hidden rounded-md border border-ods-border bg-ods-card', className)}
-    >
+    <div className={cn(FRAME_CLASS, className)}>
       {/* Header (title + subtitle) and body (rows + progress) are two groups separated by
           `gap-l`; the title/subtitle stack tightly and the rows use `gap-xs` — matching the ODS
           "Info-card" design. With no title/subtitle, the body is the only group. */}
-      <div className="flex w-full flex-col items-start gap-[var(--spacing-system-l)] p-[var(--spacing-system-m)]">
+      <div className={CONTENT_CLASS}>
         {(data.title || data.subtitle) && (
-          <div className="flex w-full flex-col items-start self-stretch">
+          <div className={HEAD_CLASS}>
             {data.title && (
-              <div className="flex items-center gap-[var(--spacing-system-xsf)] self-stretch">
+              <div className={HEAD_LINE_CLASS}>
                 <span className="min-w-0 truncate text-ods-text-primary text-h4" title={data.title}>
                   {data.title}
                 </span>
@@ -68,7 +98,7 @@ export function InfoCard({ data, className = '' }: InfoCardProps) {
               </div>
             )}
             {data.subtitle && (
-              <div className="flex items-center gap-[var(--spacing-system-xsf)] self-stretch">
+              <div className={HEAD_LINE_CLASS}>
                 <span className="min-w-0 truncate text-ods-text-secondary text-h4" title={data.subtitle}>
                   {data.subtitle}
                 </span>
@@ -81,7 +111,7 @@ export function InfoCard({ data, className = '' }: InfoCardProps) {
         )}
 
         {(data.items.length > 0 || data.progress) && (
-          <div className="flex w-full flex-col items-start gap-[var(--spacing-system-xs)] self-stretch">
+          <div className={ROWS_CLASS}>
             {/* Info items */}
             {data.items.map((item, index) => {
               const values = Array.isArray(item.value) ? item.value : [item.value];
@@ -124,7 +154,7 @@ export function InfoCard({ data, className = '' }: InfoCardProps) {
 
 function InfoCardFooter({ footer }: { footer: InfoCardFooterData }) {
   return (
-    <div className="mt-auto flex w-full flex-col border-t border-ods-border p-[var(--spacing-system-m)]">
+    <div className={FOOTER_CLASS}>
       <div className="flex w-full items-center justify-between gap-1">
         <div className="flex items-center gap-1">
           {footer.icon}
@@ -159,9 +189,9 @@ function InfoCardValueRow({ label, value, showLabel, copyable, icon, copyAriaLab
   const { copy, copied } = useCopyToClipboard();
 
   return (
-    <div className="flex h-6 w-full items-center gap-[var(--spacing-system-xs)] self-stretch">
+    <div className={VALUE_ROW_CLASS}>
       <span className="whitespace-nowrap text-ods-text-primary text-h4">{showLabel ? label : ''}</span>
-      <div className="h-px flex-1 bg-ods-divider" />
+      <div className={DIVIDER_CLASS} />
       <div className="flex max-w-[60%] items-center gap-[var(--spacing-system-xsf)]">
         <span className="select-text truncate text-ods-text-primary text-h4" title={value}>
           {value}
@@ -184,3 +214,47 @@ function InfoCardValueRow({ label, value, showLabel, copyable, icon, copyAriaLab
     </div>
   );
 }
+
+/**
+ * An InfoCard while its data is read: the same frame and groups, the title and subtitle `text-h4` bars, each row
+ * its label and value bars either side of the row's divider, the progress bar and the footer line boxes of their
+ * own height.
+ */
+export function InfoCardSkeleton({
+  rows = INFO_CARD_SKELETON_ROWS,
+  title = true,
+  subtitle = false,
+  progress = false,
+  footer = false,
+  className = '',
+}: InfoCardSkeletonShape & { className?: string }) {
+  return (
+    <div className={cn(FRAME_CLASS, className)} aria-hidden>
+      <div className={CONTENT_CLASS}>
+        {(title || subtitle) && (
+          <div className={HEAD_CLASS}>
+            {title && <TextLineSkeleton type="h4" className="w-1/2" />}
+            {subtitle && <TextLineSkeleton type="h4" className="w-1/3" />}
+          </div>
+        )}
+        {(rows > 0 || progress) && (
+          <div className={ROWS_CLASS}>
+            {Array.from({ length: rows }, (_, index) => (
+              <div key={index} className={VALUE_ROW_CLASS}>
+                <TextLineSkeleton type="h4" className="w-20" />
+                <div className={DIVIDER_CLASS} />
+                <TextLineSkeleton type="h4" className="w-24" />
+              </div>
+            ))}
+            {progress && <ProgressBarSkeleton />}
+          </div>
+        )}
+      </div>
+      {footer && (
+        <div className={FOOTER_CLASS}>
+          <TextLineSkeleton type="h4" className="w-1/2" />
+        </div>
+      )}
+    </div>
+  );
+}

package/src/components/ui/input-styles.ts

@@ -0,0 +1,6 @@
+/**
+ * The text field's box: its height per breakpoint and its radius. A plain module (no client directive), read by
+ * `Input` and by `InteractiveSkeleton.Input`, so a field's skeleton is the field's box.
+ */
+export const INPUT_HEIGHT_CLASS = 'h-11 md:h-12';
+export const INPUT_RADIUS_CLASS = 'rounded-[6px]';

package/src/components/ui/input.tsx

@@ -4,6 +4,7 @@ import { Loader2 } from 'lucide-react';
 import { type InputHTMLAttributes, type ReactNode, forwardRef } from 'react';
 import { cn } from '../../utils/cn';
 import { FieldWrapper } from './field-wrapper';
+import { INPUT_HEIGHT_CLASS, INPUT_RADIUS_CLASS } from './input-styles';
 
 export interface InputProps extends InputHTMLAttributes<HTMLInputElement> {
   /** When true, renders error border & ring */
@@ -96,7 +97,9 @@ const Input = forwardRef<HTMLInputElement, InputProps>((allProps, ref) => {
       data-invalid={isInvalid || undefined}
       className={cn(
         // Layout & spacing
-        'flex h-11 w-full cursor-text items-center gap-2 rounded-[6px] border px-3 md:h-12',
+        'flex w-full cursor-text items-center gap-2 border px-3',
+        INPUT_HEIGHT_CLASS,
+        INPUT_RADIUS_CLASS,
         // Focus-within states
         'has-[:focus-visible]:outline-none',
         'group',

package/src/components/ui/layout-hold.tsx

@@ -3,24 +3,21 @@ import { cn } from '../../utils/cn';
 import { SKELETON_SURFACE_CLASS } from './skeleton-surface';
 
 /**
- * Holding a layout while its content is read, the two ways that are right at
- * EVERY width. A placeholder of a guessed size (a `w-40` bar, a `h-[120px]`
+ * Holding text while its layout is read, the way that is right at EVERY width. A placeholder of a guessed size (a `w-40` bar, a `h-[120px]`
  * box) is only right at the widths it was tuned at: text wraps where the words
  * make it wrap, so the placeholder has to be made of the words, or of the real
  * layout, to wrap where the content will.
  *
- * - `TextHold`: an inline stand-in exactly as wide as the words it is given
+ * - `TextHold`: an inline bar exactly as wide as the words it is given (the page's own words, never invented)
  *   (same font, same letter spacing, because it IS those words, not shown).
  *   `bar` draws one skeleton bar per line the words take, each as wide as
  *   its line, in plain CSS (no measuring, so it is in the server's HTML);
  *   `blank` only keeps their space.
- * - `LayoutHold`: a block as tall as the real layout rendered inside it, kept
- *   invisible and inert: the layout's own height, at any width.
  *
- * Neither is shown or read out; both are removed for assistive technology.
+ * It is not shown or read out; it is removed for assistive technology.
  */
 export interface TextHoldProps {
-  /** The words whose width is held (the content's own, or a stand-in of its length). */
+  /** The words whose width is held: the page's own static words, never invented ones. */
   children: ReactNode;
   /** `bar`: one skeleton bar per line the words take. `blank`: the space only. */
   variant?: 'bar' | 'blank';
@@ -66,6 +63,11 @@ export interface LayoutHoldProps {
   className?: string;
 }
 
+/**
+ * @deprecated Render the layout itself inside a `LoadingScope`: each part draws its own skeleton. Kept so hosts on an
+ * older release keep compiling; nothing in the lib uses it. A block as tall as the layout rendered inside it, kept
+ * invisible and inert.
+ */
 export function LayoutHold({ children, className }: LayoutHoldProps) {
   return (
     <div aria-hidden inert className={cn('invisible', className)}>

package/src/components/ui/leader-row.tsx

@@ -1,5 +1,7 @@
 import type { ReactNode } from 'react';
 import { cn } from '../../utils/cn';
+import { TextLineSkeleton, UnifiedSkeleton } from '../loading/unified-skeleton';
+import { useLoadingScope } from './loading-scope';
 
 export interface LeaderRowProps {
   label: ReactNode;
@@ -11,18 +13,70 @@ export interface LeaderRowProps {
   className?: string;
 }
 
+/** The row's layout, read by the row and by its skeleton, so the skeleton is the row's size. */
+const LEADER_ROW_CLASS = 'flex min-w-0 items-center gap-[var(--spacing-system-xsf)] text-h4';
+const LEADER_LABEL_CLASS = 'shrink-0 whitespace-nowrap text-ods-text-secondary';
+const LEADER_LINE_CLASS = 'h-px min-w-4 flex-1 bg-ods-border';
+const STATUS_BOX_CLASS = 'flex shrink-0 items-center';
+
 /**
  * A label and its value joined by a leader line (Figma `info-card` row): the
  * quiet label, a hairline that takes the free space, the value, and a status
  * mark at the end. One line, always: a long value clips.
  */
+/** Whether a slot holds something to draw: a read value that is not here yet is empty. */
+const isGiven = (node: ReactNode) => node !== null && node !== undefined && node !== false && node !== '';
+
 export function LeaderRow({ label, value, status, as: Row = 'div', className }: LeaderRowProps) {
+  // In a loading scope a row whose value is not here yet (empty) is its skeleton; a row the page states in full
+  // (config copy, values already known) is drawn as it is.
+  if (useLoadingScope() && !isGiven(value)) {
+    return (
+      <LeaderRowSkeleton status={!!status} label={isGiven(label) ? label : undefined} as={Row} className={className} />
+    );
+  }
   return (
-    <Row className={cn('flex min-w-0 items-center gap-[var(--spacing-system-xsf)] text-h4', className)}>
-      <span className="shrink-0 whitespace-nowrap text-ods-text-secondary">{label}</span>
-      <span className="h-px min-w-4 flex-1 bg-ods-border" aria-hidden />
+    <Row className={cn(LEADER_ROW_CLASS, className)}>
+      <span className={LEADER_LABEL_CLASS}>{label}</span>
+      <span className={LEADER_LINE_CLASS} aria-hidden />
       <span className="min-w-0 truncate text-ods-text-primary">{value}</span>
-      {status && <span className="flex shrink-0 items-center">{status}</span>}
+      {status && <span className={STATUS_BOX_CLASS}>{status}</span>}
+    </Row>
+  );
+}
+
+
+/**
+ * A row while it is read: the label (drawn as it is when the page states it, else a bar), the hairline drawn for
+ * real, a bar for the value, a status box. Every bar is one line of the ROW's type step, so a row sized with
+ * `className="text-h6"` keeps its height.
+ */
+export function LeaderRowSkeleton({
+  status = false,
+  label,
+  as: Row = 'div',
+  className,
+}: {
+  status?: boolean;
+  /** The row's label, when the page states it. */
+  label?: ReactNode;
+  as?: 'div' | 'li';
+  className?: string;
+}) {
+  return (
+    <Row className={cn(LEADER_ROW_CLASS, className)} aria-hidden>
+      {label !== undefined ? (
+        <span className={LEADER_LABEL_CLASS}>{label}</span>
+      ) : (
+        <TextLineSkeleton as="span" type="inherit" className="inline-block w-24 shrink-0" />
+      )}
+      <span className={LEADER_LINE_CLASS} />
+      <TextLineSkeleton as="span" type="inherit" className="inline-block w-16 shrink-0" />
+      {status && (
+        <span className={STATUS_BOX_CLASS}>
+          <UnifiedSkeleton className="size-4" />
+        </span>
+      )}
     </Row>
   );
 }

package/src/components/ui/loading-scope.tsx

@@ -0,0 +1,54 @@
+'use client';
+
+/**
+ * A page's loading state, drawn by its own components. THE RULE: every component that shows read data has its own
+ * `<Name>Skeleton` (the same layout, sharing the component's class constants, its static copy drawn for real and
+ * every read part a skeleton shape), and decides in ONE place when it is loading:
+ *
+ *   if (useLoadingScope() || <its own data is not here yet>) return <NameSkeleton … />;
+ *
+ * Inside `LoadingScope` (which a page wraps around its loading state) every component is therefore its skeleton,
+ * and the same skeleton shows while it fetches on the client. Nothing in a scope fetches, writes, or draws invented
+ * words.
+ */
+import { createContext, useContext, type ReactNode } from 'react';
+import { cn } from '../../utils/cn';
+
+const LoadingScopeContext = createContext(false);
+
+/** Draws its children as their own loading state. Inert and hidden from assistive technology: the page's loading
+ *  region announces it once. `bare` draws no element of its own (the scope only): for a component's own `loading`
+ *  mode, whose markup must not change and whose container already says it is loading. `active` (default true) turns
+ *  the scope on and off without changing the tree, so a component that finishes loading is not remounted; a false
+ *  never cancels an outer scope. */
+export function LoadingScope({
+  children,
+  className,
+  bare = false,
+  active,
+}: {
+  children: ReactNode;
+  className?: string;
+  bare?: boolean;
+  active?: boolean;
+}) {
+  const outer = useContext(LoadingScopeContext);
+  const on = outer || (active ?? true);
+  if (bare) return <LoadingScopeContext.Provider value={on}>{children}</LoadingScopeContext.Provider>;
+  return (
+    <LoadingScopeContext.Provider value={on}>
+      <div
+        aria-hidden={on || undefined}
+        inert={on || undefined}
+        className={cn(on && 'pointer-events-none select-none', className)}
+      >
+        {children}
+      </div>
+    </LoadingScopeContext.Provider>
+  );
+}
+
+/** Whether the component draws as its own loading state (its `<Name>Skeleton`). */
+export function useLoadingScope(): boolean {
+  return useContext(LoadingScopeContext);
+}

package/src/components/ui/markdown/base-components.tsx

@@ -16,6 +16,7 @@ import { cn } from '../../../utils/cn';
 import { slugifyHeadingText } from '../../../utils/markdown-heading-id';
 import { renderedLinkRel } from '../../../utils/markdown-link';
 import { getHashTargetElement, navigateSamePageHash, HUB_HEADER_OFFSET_PX } from '../../../utils/same-page-hash-nav';
+import { useLoadingScope } from '../loading-scope';
 import { extractText, resolveFallbackHeadingId, useAssignedHeadingIds, useHeadingId } from './heading-ids';
 import { MermaidDiagram } from './mermaid-diagram';
 import type { TextSizeElement } from './text-size';
@@ -64,8 +65,21 @@ export interface StandardLeafRenderers {
  * the engine's cap: 400x400 intrinsic, `w-auto h-auto max-h-[400px]` drives
  * the actual rendered box; click-to-expand surfaces provide full resolution.
  */
+/**
+ * The page title, a section heading and a paragraph of rendered markdown (before the text size): read by the
+ * renderer and by every skeleton that stands in for a markdown body.
+ */
+export const MARKDOWN_H1_CLASS = 'mb-4 mt-8 font-sans font-bold text-ods-text-primary first:mt-0';
+export const MARKDOWN_H2_CLASS =
+  'mb-4 mt-8 border-b border-ods-border pb-2 font-sans font-semibold text-ods-text-primary';
+export const MARKDOWN_PARAGRAPH_CLASS = 'mb-4 leading-relaxed text-ods-text-primary first:mt-0 last:mb-0';
+
 const MarkdownContentImage: React.FC<{ src: string; alt?: string }> = ({ src, alt }) => {
-  const resolvedSrc = useAuthedImageSrc(src);
+  // In a loading scope the image is a box and nothing is fetched: the authed fetch is skipped, and the `Image` shim
+  // draws its skeleton box (`HeldImage`) without reading `src`. `src` is passed only so the box is drawn at all.
+  const inScope = useLoadingScope();
+  const authedSrc = useAuthedImageSrc(inScope ? undefined : src);
+  const resolvedSrc = inScope ? src : authedSrc;
   if (!resolvedSrc) return null;
   return (
     <Image
@@ -235,20 +249,15 @@ export function buildBaseComponents({
     ...buildStandardLeafRenderers({ textSizes }),
 
     // --- headings ---
-    h1: makeHeading('h1', cn('mb-4 mt-8 font-sans font-bold text-ods-text-primary first:mt-0', textSizes.h1)),
-    h2: makeHeading(
-      'h2',
-      cn('mb-4 mt-8 border-b border-ods-border pb-2 font-sans font-semibold text-ods-text-primary', textSizes.h2),
-    ),
+    h1: makeHeading('h1', cn(MARKDOWN_H1_CLASS, textSizes.h1)),
+    h2: makeHeading('h2', cn(MARKDOWN_H2_CLASS, textSizes.h2)),
     h3: makeHeading('h3', cn('mb-3 mt-6 font-sans font-semibold text-ods-text-primary', textSizes.h3)),
     h4: makeHeading('h4', cn('mb-2 mt-4 font-sans font-semibold text-ods-text-primary', textSizes.h4)),
     h5: makeHeading('h5', cn('mb-2 mt-3 font-sans font-semibold text-ods-text-primary', textSizes.h5)),
     h6: makeHeading('h6', cn('mb-1 mt-3 font-sans font-semibold text-ods-text-primary', textSizes.h6)),
 
     // --- paragraph ---
-    p: ({ children }: MdRenderProps<'p'>) => (
-      <p className={cn('mb-4 leading-relaxed text-ods-text-primary first:mt-0 last:mb-0', textSizes.p)}>{children}</p>
-    ),
+    p: ({ children }: MdRenderProps<'p'>) => <p className={cn(MARKDOWN_PARAGRAPH_CLASS, textSizes.p)}>{children}</p>,
 
     // --- links ---
     a: ({ href, children, className: linkClassName, rel: authoredRel }: MdRenderProps<'a'>) => {