@flamingo-stack/openframe-frontend-core 0.0.777 → 0.0.781

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

@@ -3,6 +3,10 @@
 import { cn } from '../../utils/cn';
 import { LoadingRegion } from '../loading/loading-region';
 import { UnifiedSkeleton } from '../loading/unified-skeleton';
+import { LoadingItems } from './loading-scope';
+
+/** Body lines the detail placeholder draws: a typical paragraph. */
+const CONTENT_LOADER_SKELETON_LINES = 3;
 
 export interface ContentLoaderProps {
   /**
@@ -31,13 +35,16 @@ export interface ContentLoaderProps {
   region?: boolean;
 }
 
+/** Items the loader draws when its host states none: a typical list. */
+const CONTENT_LOADER_SKELETON_ITEMS = 4;
+
 /**
  * Unified content loader component that replaces duplicate loading patterns
  * Uses ODS design tokens for consistent theming
  */
 export function ContentLoader({
   variant = 'card',
-  items = 4,
+  items = CONTENT_LOADER_SKELETON_ITEMS,
   showTitle = true,
   className,
   containerClassName,
@@ -49,12 +56,14 @@ export function ContentLoader({
       {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}>
-              <UnifiedSkeleton className="mb-2 h-4 w-20 rounded" />
-              <UnifiedSkeleton className="h-6 w-32 rounded" />
-            </div>
-          ))}
+          <LoadingItems count={items}>
+            {() => (
+              <div data-loading-item>
+                <UnifiedSkeleton className="mb-2 h-4 w-20 rounded" />
+                <UnifiedSkeleton className="h-6 w-32 rounded" />
+              </div>
+            )}
+          </LoadingItems>
         </div>
         <div className="border-t border-ods-border pt-4">
           <UnifiedSkeleton className="h-4 w-64 rounded" />
@@ -68,12 +77,14 @@ export function ContentLoader({
       {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}>
-              <UnifiedSkeleton className="mb-2 h-4 w-32 rounded" />
-              <UnifiedSkeleton className="h-10 rounded" />
-            </div>
-          ))}
+          <LoadingItems count={items}>
+            {() => (
+              <div data-loading-item>
+                <UnifiedSkeleton className="mb-2 h-4 w-32 rounded" />
+                <UnifiedSkeleton className="h-10 rounded" />
+              </div>
+            )}
+          </LoadingItems>
         </div>
       </div>
     </div>
@@ -87,17 +98,17 @@ export function ContentLoader({
           <div className="content-lg:col-span-2">
             <UnifiedSkeleton className="mb-4 h-64 rounded" />
             <div className="space-y-2">
-              {Array.from({ length: 3 }).map((_, i) => (
-                <UnifiedSkeleton key={i} className="h-4 rounded" />
-              ))}
+              <LoadingItems count={CONTENT_LOADER_SKELETON_LINES}>
+                {() => <UnifiedSkeleton className="h-4 rounded" />}
+              </LoadingItems>
             </div>
           </div>
           <div>
             <UnifiedSkeleton className="mb-4 h-32 rounded" />
             <div className="space-y-2">
-              {Array.from({ length: items }).map((_, i) => (
-                <UnifiedSkeleton key={i} className="h-3 rounded" />
-              ))}
+              <LoadingItems count={items}>
+                {() => <UnifiedSkeleton className="h-3 rounded" data-loading-item />}
+              </LoadingItems>
             </div>
           </div>
         </div>
@@ -108,18 +119,20 @@ export function ContentLoader({
   const renderListSkeleton = () => (
     <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">
-            <UnifiedSkeleton className="h-12 w-12 rounded" />
-            <div className="flex-1">
-              <UnifiedSkeleton className="mb-2 h-4 w-3/4 rounded" />
-              <UnifiedSkeleton className="h-3 w-1/2 rounded" />
+      <LoadingItems count={items}>
+        {() => (
+          <div className="rounded-lg border border-ods-border bg-ods-card p-4" data-loading-item>
+            <div className="flex items-center gap-4">
+              <UnifiedSkeleton className="h-12 w-12 rounded" />
+              <div className="flex-1">
+                <UnifiedSkeleton className="mb-2 h-4 w-3/4 rounded" />
+                <UnifiedSkeleton className="h-3 w-1/2 rounded" />
+              </div>
+              <UnifiedSkeleton className="h-8 w-20 rounded" />
             </div>
-            <UnifiedSkeleton className="h-8 w-20 rounded" />
           </div>
-        </div>
-      ))}
+        )}
+      </LoadingItems>
     </div>
   );
 

package/src/components/ui/cursor-pagination.tsx

@@ -4,6 +4,7 @@ import { ChevronLeft, ChevronRight, RotateCcw, Home } from 'lucide-react';
 import { cn } from '../../utils/cn';
 import { TextLineSkeleton } from '../loading/unified-skeleton';
 import { Button } from './button';
+import { useLoadingScope } from './loading-scope';
 
 export interface CursorPaginationProps {
   hasNextPage: boolean;
@@ -16,6 +17,10 @@ export interface CursorPaginationProps {
   totalCount?: number | null;
   itemName?: string;
 
+  /**
+   * The pager's page is being read: every button is disabled. Before the first count is known (no `currentCount`), and
+   * inside a loading scope, the pager draws its skeleton: the count line a bar, its own buttons real and inert.
+   */
   loading?: boolean;
 
   onNext?: (cursor: string) => void;
@@ -27,8 +32,6 @@ export interface CursorPaginationProps {
   compact?: boolean;
   resetButtonLabel?: string;
   resetButtonIcon?: 'home' | 'rotate';
-  /** @internal The skeleton's state: the count line a bar, the buttons drawn but inert. */
-  skeleton?: boolean;
 }
 
 export function CursorPagination({
@@ -40,7 +43,7 @@ export function CursorPagination({
   currentCount,
   totalCount,
   itemName = 'items',
-  loading = false,
+  loading: loadingProp = false,
   onNext,
   onPrevious,
   onReset,
@@ -49,8 +52,11 @@ export function CursorPagination({
   compact = false,
   resetButtonLabel = 'First',
   resetButtonIcon = 'home',
-  skeleton = false,
 }: CursorPaginationProps) {
+  const loading = useLoadingScope() || loadingProp;
+  // Its data is the count: until the first one is known, the pager draws its skeleton (a page read with a count shown
+  // keeps the count and only disables the buttons).
+  const skeleton = loading && !currentCount;
   const handleNext = () => {
     if (hasNextPage && endCursor && onNext) {
       onNext(endCursor);
@@ -145,26 +151,6 @@ export function CursorPagination({
   );
 }
 
-/**
- * The pager while its page is read: the same row, the count line as a bar, and the pager's own buttons (their labels
- * are the pager's words) drawn inert. Takes the pager's configuration; its cursors and counts are not known yet.
- */
-export function CursorPaginationSkeleton(
-  props: Pick<
-    CursorPaginationProps,
-    | 'hasPreviousPage'
-    | 'onPrevious'
-    | 'onReset'
-    | 'className'
-    | 'showInfo'
-    | 'compact'
-    | 'resetButtonLabel'
-    | 'resetButtonIcon'
-  >,
-) {
-  return <CursorPagination {...props} hasNextPage={false} skeleton />;
-}
-
 export function CursorPaginationSimple({
   hasNextPage,
   hasPreviousPage,

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

@@ -98,7 +98,8 @@ export interface DashboardInfoCardProps {
   /**
    * While `loading`: hold the percentage's box (plain "(NN%)" text, or a `Tag` when
    * `percentageDisplay` / `progressVariant` would draw one), because the loaded card will show
-   * a percentage. Default `false`.
+   * a percentage. Default: `showProgress` or a percentage drawn as a tag (`percentageDisplay="tag"`, or a
+   * `warning`/`error` `progressVariant`), the cards that show one.
    */
   loadingShowsPercentage?: boolean;
   /**
@@ -106,8 +107,21 @@ export interface DashboardInfoCardProps {
    * whose loaded state will carry one. Default `false`.
    */
   loadingShowsSubValue?: boolean;
+  /**
+   * While `loading`: the title is read too, so its line is a bar even when a `title` is passed (an empty `title`
+   * already draws the bar). `titleSlot` and `titleTag` are left as given. Default `false`.
+   */
+  titleLoading?: boolean;
+  /**
+   * While `loading`: the icon is read too (it depends on the figure), so the icon slot is a skeleton of the slot's
+   * own box, whether or not an `icon` is passed. Default `false`.
+   */
+  iconLoading?: boolean;
 }
 
+/** The icon slot's box (Figma "icon" variant): 32px on mobile, 56px from `md` up. Read by the slot and its skeleton. */
+const DASHBOARD_INFO_CARD_ICON_BOX_CLASS = 'size-8 shrink-0 rounded-sm content-md:size-14';
+
 export function DashboardInfoCard({
   title,
   titleSlot,
@@ -127,8 +141,10 @@ export function DashboardInfoCard({
   subValue,
   caption,
   loading: loadingProp = false,
-  loadingShowsPercentage = false,
+  loadingShowsPercentage: loadingShowsPercentageProp,
   loadingShowsSubValue = false,
+  titleLoading = false,
+  iconLoading = false,
 }: DashboardInfoCardProps) {
   // In a page's loading state the figure is read: the card is its skeleton (`loading`).
   const inScope = useLoadingScope();
@@ -140,13 +156,15 @@ export function DashboardInfoCard({
   const percentageAsTag =
     percentageDisplay === 'tag' ||
     (percentageDisplay === 'auto' && (progressVariant === 'warning' || progressVariant === 'error'));
+  // A card that draws a progress ring or a percentage tag shows a percentage once loaded: its box is held by default.
+  const loadingShowsPercentage = loadingShowsPercentageProp ?? (showProgress || percentageAsTag);
 
   const renderPercentage = () => {
     if (loading) {
       if (!loadingShowsPercentage) return null;
       // The box the loaded percentage takes: a `Tag` (h-8) or one `text-h4` line.
       return percentageAsTag ? (
-        <UnifiedSkeleton className="h-8 w-12 shrink-0 rounded-md" />
+        <Tag loading label="" className="w-12" />
       ) : (
         <p className="text-h4">
           <TextLineSkeleton type="inherit" as="span" className="w-12" />
@@ -246,10 +264,19 @@ export function DashboardInfoCard({
     <>
       {/* Icon slot (Figma "icon" variant): 32px box / 16px content on mobile,
           56px box / 24px content from `md` up. */}
-      {icon && (
-        <div className="flex size-8 shrink-0 items-center justify-center rounded-sm border border-ods-border bg-ods-bg p-[var(--spacing-system-xxs)] text-ods-text-primary content-md:size-14">
-          <span className="flex size-4 items-center justify-center content-md:size-6 [&>*]:size-full">{icon}</span>
-        </div>
+      {loading && iconLoading ? (
+        <UnifiedSkeleton className={DASHBOARD_INFO_CARD_ICON_BOX_CLASS} />
+      ) : (
+        icon && (
+          <div
+            className={cn(
+              DASHBOARD_INFO_CARD_ICON_BOX_CLASS,
+              'flex items-center justify-center border border-ods-border bg-ods-bg p-[var(--spacing-system-xxs)] text-ods-text-primary',
+            )}
+          >
+            <span className="flex size-4 items-center justify-center content-md:size-6 [&>*]:size-full">{icon}</span>
+          </div>
+        )
       )}
 
       {/* Content section */}
@@ -258,7 +285,7 @@ export function DashboardInfoCard({
         <div className="flex items-center gap-[var(--spacing-system-xxs)]">
           {titleSlot ??
             // A title still being read (empty while loading) is a bar of its line, like no title.
-            (title !== undefined && !(loading && !title) ? (
+            (title !== undefined && !(loading && (!title || titleLoading)) ? (
               <p className="truncate text-ods-text-secondary text-h5">{title}</p>
             ) : (
               loading && (
@@ -342,11 +369,3 @@ export function DashboardInfoCard({
     </div>
   );
 }
-
-/**
- * A DashboardInfoCard while its figure is read: the same card with `loading` set, so it is the loaded card's box.
- * The title, title slot, tag and icon it is given are the page's own and draw as they are.
- */
-export function DashboardInfoCardSkeleton(props: Omit<DashboardInfoCardProps, 'value' | 'loading'>) {
-  return <DashboardInfoCard {...props} value="" loading />;
-}

package/src/components/ui/data-attribution.tsx

@@ -64,7 +64,7 @@ export function DataAttribution({ icon, source, lastUpdated, action }: DataAttri
  * words drawn for real, the source and the date bars of the line's height, so the line does not move when it
  * fills in. The source's mark is the one given (a brand glyph is static), else a box of its size.
  */
-export function DataAttributionSkeleton({ icon, action }: Pick<DataAttributionProps, 'icon' | 'action'> = {}) {
+function DataAttributionSkeleton({ icon, action }: Pick<DataAttributionProps, 'icon' | 'action'> = {}) {
   return (
     <div className={LINE_CLASS} aria-hidden="true">
       <div className={ITEM_CLASS}>

package/src/components/ui/data-table/data-table-body.tsx

@@ -3,19 +3,27 @@
 import { useSyncExternalStore, type ReactNode } from 'react';
 import { useIsomorphicLayoutEffect } from '../../../hooks/ui/use-isomorphic-layout-effect';
 import { cn } from '../../../utils/cn';
+import { LoadingFallback } from '../../loading/loading-fallback';
 import { LoadingRegion } from '../../loading/loading-region';
-import { useLoadingScope } from '../loading-scope';
+import { LoadingItems, useLoadingScope } from '../loading-scope';
 import type { NoDataProps } from '../no-data';
 import { useDataTableContext } from './data-table';
 import { DataTableEmpty } from './data-table-empty';
 import { useDataTableLoadMoreStore } from './data-table-load-more';
+import { PlaceholderRows, ReservedEmptyState } from './data-table-reserved-rows';
 import { DataTableRow } from './data-table-row';
-import { DataTableSkeleton, PlaceholderRows, ReservedEmptyState, ROW_STACK_CLASSES } from './data-table-skeleton';
+import { ROW_STACK_CLASSES } from './data-table-row-classes';
 import { DATA_TABLE_SKELETON_ROWS, dataTablePageSize } from './utils';
 
 export interface DataTableBodyProps<T = unknown> {
   /** Show skeleton rows while `loading` is true and data is empty. */
   loading?: boolean;
+  /**
+   * While loading, the table holds placeholder rows (the host gives `useDataTable` one full page of them) and the body
+   * draws them with their REAL cells in a loading scope: every part of a cell draws its own loading form, so the
+   * loading row is the loaded row's own layout. Without it a loading row is one bar per column.
+   */
+  loadingCells?: boolean;
   /** @deprecated Use `emptyState` instead. Legacy single-line message; mapped to the empty state's title. */
   emptyMessage?: string;
   /** Props for the empty state (NoData) shown when there are no rows. Overrides `emptyMessage`. */
@@ -103,6 +111,7 @@ const getNoRows = () => 0;
  */
 export function DataTableBody<T = unknown>({
   loading: loadingProp,
+  loadingCells = false,
   emptyMessage,
   emptyState,
   skeletonRows: skeletonRowsProp,
@@ -131,11 +140,34 @@ export function DataTableBody<T = unknown>({
   // has rows to continue takes them over; an empty or loading one leaves the
   // footer drawing its own, as before.
   const loadMore = useDataTableLoadMoreStore();
-  const loadMoreRows = useSyncExternalStore(loadMore.subscribe, loadMore.getSkeletonRows, getNoRows);
+  // The next page the footer is reading: its page size, drawn as that many loading rows.
+  const loadMorePageSize = useSyncExternalStore(loadMore.subscribe, loadMore.getSkeletonRows, getNoRows);
   useIsomorphicLayoutEffect(() => (hasRows ? loadMore.registerRowsBody() : undefined), [loadMore, hasRows]);
 
   const skeletonRowClassName = typeof rowClassName === 'string' ? rowClassName : undefined;
 
+  if (loading && loadingCells && hasRows) {
+    return (
+      <LoadingFallback
+        label="Loading results"
+        status={loadingRegion && !inScope}
+        className={cn(ROW_STACK_CLASSES, className)}
+      >
+        {rows.map((row, index) => (
+          <DataTableRow<T>
+            key={row.id}
+            row={row}
+            drawsCells
+            compact={compact}
+            rowHeightClassName={rowHeightClassName}
+            className={typeof rowClassName === 'function' ? rowClassName(row.original, index) : rowClassName}
+            data-loading-item
+          />
+        ))}
+      </LoadingFallback>
+    );
+  }
+
   if (loading && !hasRows) {
     return (
       <LoadingRegion
@@ -144,11 +176,18 @@ export function DataTableBody<T = unknown>({
         announce={loadingRegion && !inScope}
         className={cn(ROW_STACK_CLASSES, className)}
       >
-        <DataTableSkeleton
-          rows={skeletonRows}
-          className={skeletonRowClassName}
-          rowHeightClassName={rowHeightClassName}
-        />
+        <LoadingItems count={skeletonRows}>
+          {index => (
+            <DataTableRow
+              row={null}
+              loadingIndex={index}
+              compact={compact}
+              className={skeletonRowClassName}
+              rowHeightClassName={rowHeightClassName}
+              data-loading-item
+            />
+          )}
+        </LoadingItems>
       </LoadingRegion>
     );
   }
@@ -182,7 +221,7 @@ export function DataTableBody<T = unknown>({
   }
 
   // Load-more rows are row slots too, so they count against `minRows`.
-  const padCount = minRows ? Math.max(0, minRows - rows.length - loadMoreRows) : 0;
+  const padCount = minRows ? Math.max(0, minRows - rows.length - loadMorePageSize) : 0;
 
   return (
     <div className={cn(ROW_STACK_CLASSES, className)}>
@@ -200,15 +239,23 @@ export function DataTableBody<T = unknown>({
             rowHeightClassName={rowHeightClassName}
             className={cls}
             subRow={renderSubRow?.(item)}
+            data-loading-item
           />
         );
       })}
-      {loadMoreRows > 0 && (
-        <DataTableSkeleton
-          rows={loadMoreRows}
-          className={skeletonRowClassName}
-          rowHeightClassName={rowHeightClassName}
-        />
+      {loadMorePageSize > 0 && (
+        <LoadingItems count={loadMorePageSize}>
+          {index => (
+            <DataTableRow
+              row={null}
+              loadingIndex={index}
+              compact={compact}
+              className={skeletonRowClassName}
+              rowHeightClassName={rowHeightClassName}
+              data-loading-item
+            />
+          )}
+        </LoadingItems>
       )}
       {padCount > 0 && <PlaceholderRows count={padCount} rowHeightClassName={rowHeightClassName} />}
     </div>

package/src/components/ui/data-table/data-table-cursor-footer.tsx

@@ -14,7 +14,7 @@ export interface DataTableCursorFooterProps extends Omit<CursorPaginationProps,
 
 /**
  * Cursor-based prev/next footer for a `DataTable`. Place after `<DataTable.Body>`.
- * Thin wrapper around `<CursorPagination>` with a border-top separator to match the legacy `Table` look.
+ * Thin wrapper around `<CursorPagination>` with a border-top separator above it.
  */
 export function DataTableCursorFooter({ className, currentCount, showInfo, ...rest }: DataTableCursorFooterProps) {
   const table = useDataTableContext();

package/src/components/ui/data-table/data-table-header.tsx

@@ -4,6 +4,7 @@ import { flexRender, type Header } from '@tanstack/react-table';
 import type { ReactNode } from 'react';
 import { cn } from '../../../utils/cn';
 import { Arrow01DownIcon, Arrow01UpIcon, SwitchVrIcon } from '../../icons-v2-generated';
+import { TextLineSkeleton } from '../../loading/unified-skeleton';
 import { InfoHint } from '../info-hint';
 import { useDataTableContext } from './data-table';
 import { DataTableColumnFilter } from './data-table-column-filter';
@@ -198,7 +199,7 @@ function getCellVisibilityClasses(
  * non-filterable cell returned `null`, and the survivors rendered with no width and
  * no alignment. One frame later the real values arrived, so the header visibly
  * filled in and the columns snapped into place — while `DataTableRow` and
- * `DataTableSkeleton`, which have always used plain `hideAt` classes, were correct
+ * its loading rows, which have always used plain `hideAt` classes, were correct
  * from the start. Header and body therefore disagreed about which columns exist and
  * how wide they are for exactly one frame, which is the flicker-and-jump on every
  * table's load.
@@ -321,8 +322,19 @@ function HeaderCell({ header, sort, onSortChange }: HeaderCellProps) {
 export const DATA_TABLE_HEADER_LABEL_CLASS =
   'min-w-0 text-balance uppercase text-ods-text-secondary transition-colors duration-200 text-h5 group-hover:text-ods-text-primary';
 
+/** A header label's bar while its text is read (`meta.headerLoading`). */
+const DATA_TABLE_HEADER_LABEL_BAR_CLASS = 'w-40 max-w-full';
+
 function HeaderLabel({ header }: { header: AnyHeader }) {
   const headerDef = header.column.columnDef.header;
+  // The label is read data (whose list the table is): its bar in the label's own box and type step.
+  if (header.column.columnDef.meta?.headerLoading) {
+    return (
+      <span className={DATA_TABLE_HEADER_LABEL_CLASS}>
+        <TextLineSkeleton type="inherit" as="span" className={DATA_TABLE_HEADER_LABEL_BAR_CLASS} />
+      </span>
+    );
+  }
   if (headerDef === undefined) return null;
   if (typeof headerDef === 'string') {
     return <span className={DATA_TABLE_HEADER_LABEL_CLASS}>{headerDef}</span>;

package/src/components/ui/data-table/data-table-infinite-footer.tsx

@@ -4,10 +4,12 @@ import { useEffect, useRef, useState, useSyncExternalStore } from 'react';
 import { useIsomorphicLayoutEffect } from '../../../hooks/ui/use-isomorphic-layout-effect';
 import { LoadingRegion } from '../../loading/loading-region';
 import { Button } from '../button';
+import { LoadingItems } from '../loading-scope';
 import { useOptionalDataTableContext } from './data-table';
 import { useDataTableLoadMoreStore } from './data-table-load-more';
-import { DataTableSkeleton, ROW_STACK_CLASSES } from './data-table-skeleton';
-import { dataTablePageSize } from './utils';
+import { DataTableRow } from './data-table-row';
+import { ROW_STACK_CLASSES } from './data-table-row-classes';
+import { DATA_TABLE_NEXT_PAGE_SKELETON_ROWS, dataTablePageSize } from './utils';
 
 export interface DataTableInfiniteFooterProps {
   hasNextPage: boolean;
@@ -111,11 +113,12 @@ export function DataTableInfiniteFooter({
   });
 
   const table = useOptionalDataTableContext();
-  const skeletonRows = skeletonRowsProp ?? (table ? dataTablePageSize(table) : undefined) ?? 3;
+  const pageSize =
+    skeletonRowsProp ?? (table ? dataTablePageSize(table) : undefined) ?? DATA_TABLE_NEXT_PAGE_SKELETON_ROWS;
 
   const loadMore = useDataTableLoadMoreStore();
   const bodyDrawsRows = useSyncExternalStore(loadMore.subscribe, loadMore.getHasRowsBody, getNoBody);
-  const requestedRows = isFetchingNextPage ? skeletonRows : 0;
+  const requestedRows = isFetchingNextPage ? pageSize : 0;
   // A layout effect, so the body's re-render lands before paint: no frame
   // between "fetching" and the rows appearing.
   useIsomorphicLayoutEffect(() => {
@@ -173,7 +176,9 @@ export function DataTableInfiniteFooter({
       {isFetchingNextPage && !bodyDrawsRows && (
         // Busy, without a second status: the footer's own one below says "Loading more results".
         <LoadingRegion status={false} className={ROW_STACK_CLASSES}>
-          <DataTableSkeleton rows={skeletonRows} />
+          <LoadingItems count={pageSize}>
+            {index => <DataTableRow row={null} loadingIndex={index} data-loading-item />}
+          </LoadingItems>
         </LoadingRegion>
       )}
       {isStalled && (

package/src/components/ui/data-table/data-table-reserved-rows.tsx

@@ -0,0 +1,111 @@
+'use client';
+
+import type { ReactNode } from 'react';
+import { cn } from '../../../utils/cn';
+import { LoadingItems } from '../loading-scope';
+import {
+  DATA_TABLE_PAD_ROW_FRAME_CLASS,
+  ROW_DESKTOP_SHELL_CLASS,
+  ROW_HEIGHT_DESKTOP,
+  ROW_HEIGHT_MOBILE,
+  ROW_MOBILE_SHELL_CLASS,
+  ROW_SHELL_CLASSES,
+} from './data-table-row-classes';
+
+/**
+ * The empty state, floating centred over a full page's worth of reserved row
+ * slots. `DataTable.Body` renders this — an empty table is exactly when a
+ * collapsing one is most visible (the pagination and everything under it jump
+ * the moment a filter matches nothing), so the body reserves the page's slots.
+ */
+export function ReservedEmptyState({
+  count,
+  gapClassName,
+  rowHeightClassName,
+  children,
+}: {
+  count: number;
+  gapClassName: string;
+  rowHeightClassName?: string;
+  children: ReactNode;
+}) {
+  // ONE grid cell holds both layers, so the box is as tall as the TALLER of
+  // the two: a short reservation (three compact rows) never clips the empty
+  // state, and a tall one still reserves its slots. The former absolute
+  // overlay took no height of its own, so a message taller than the slots
+  // spilled out of the host's horizontal scroller and grew it a vertical
+  // scrollbar — the header scrolled away inside a section.
+  return (
+    <div className="grid w-full">
+      <div className={cn('flex w-full flex-col [grid-area:1/1]', gapClassName)}>
+        <PlaceholderRows count={count} rowHeightClassName={rowHeightClassName} />
+      </div>
+      {/* `sticky left-0` + `w-screen max-w-full`: hosts wrap tables in a
+          horizontal scroller with a forced min-width, and an overlay centred on
+          that CANVAS puts the message off-screen on a phone. This centres it on
+          the visible area instead, and collapses to plain centring when the
+          table is not wider than its container. */}
+      <div className="flex items-center [grid-area:1/1]">
+        <div className="sticky left-0 flex w-screen max-w-full justify-center">{children}</div>
+      </div>
+    </div>
+  );
+}
+
+/**
+ * Invisible rows that occupy exactly one row slot each.
+ *
+ * THE height reservation for a table whose page is short or empty — every call
+ * site uses it (`DataTable.Body`'s pad and empty branches), so
+ * a padded page and an empty one are the same height by construction rather
+ * than by matching guesses in each component.
+ */
+export function PlaceholderRows({
+  count,
+  rowHeightClassName,
+}: {
+  count: number;
+  /** Height on the CARD, as `DataTableRow` carries it. */
+  rowHeightClassName?: string;
+}) {
+  return (
+    // loading-standard-ok(ITEM_MARK): pad slots that reserve a short page's height in the LOADED table, not items
+    <LoadingItems count={count}>
+      {() => (
+        <div
+          // `border-transparent`, not no border: a real row card draws a 1px
+          // border on each side, so its outer block is the inner height PLUS 2.
+          // A pad row without one is 2px shorter than the row it stands in for
+          // — invisible per row, 54px over a 27-row remainder, which is the
+          // same shift `minRows` exists to prevent.
+          className={cn(
+            DATA_TABLE_PAD_ROW_FRAME_CLASS,
+            // The stated slot height belongs on the CARD, exactly as a real
+            // row carries it — a real row with a sub-row is taller than its
+            // cells, so reserving the cells' height here left every pad row
+            // short by the sub-row.
+            rowHeightClassName,
+          )}
+          aria-hidden="true"
+        >
+          <div
+            className={cn(
+              ROW_DESKTOP_SHELL_CLASS,
+              'py-0',
+              ROW_SHELL_CLASSES,
+              rowHeightClassName ? 'h-full' : ROW_HEIGHT_DESKTOP,
+            )}
+          />
+          <div
+            className={cn(
+              ROW_MOBILE_SHELL_CLASS,
+              'py-0',
+              ROW_SHELL_CLASSES,
+              rowHeightClassName ? 'h-full' : ROW_HEIGHT_MOBILE,
+            )}
+          />
+        </div>
+      )}
+    </LoadingItems>
+  );
+}