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

package/src/components/ui/product-screen-frame.tsx

@@ -93,8 +93,16 @@ export function ProductScreenFrame({
     return () => observer.disconnect();
   }, [designWidth, scaleFrom]);
 
-  const screenStyle: CSSProperties =
-    mode === 'scaled'
+  // Before the frame is measured (the server's HTML, until hydration) the stylesheet lays the screen out the way the
+  // measure will (`styles/product-screen-frame.css`): at the design width, scaled to the frame. So the loading form a
+  // first paint shows is the loaded screen's own layout, never the narrow one.
+  const pending = mode === 'pending';
+  const screenStyle: CSSProperties = pending
+    ? ({
+        '--product-screen-design-width': `${designWidth}px`,
+        '--product-screen-scale-from': `${scaleFrom}px`,
+      } as CSSProperties)
+    : mode === 'scaled'
       ? {
           width: designWidth,
           // The crop is in frame pixels, so the unscaled box is taller by the same factor.
@@ -112,23 +120,25 @@ export function ProductScreenFrame({
       role="img"
       aria-label={label}
       data-app-type={appType}
-      className={cn('relative overflow-hidden', className)}
+      className={cn('product-screen-frame relative overflow-hidden', className)}
       style={{ height }}
     >
       <PortalContainerContext.Provider value={portalHost}>
         <CollisionBoundaryContext.Provider value={frame}>
-          <div inert aria-hidden className="ods-content-area" style={screenStyle}>
+          <div
+            inert
+            aria-hidden
+            className={cn('ods-content-area', pending && 'product-screen-pending')}
+            style={screenStyle}
+          >
             <div className="ods-content-scope">
               {/* Until measured (the server's HTML, a page without scripts) the screen is its own loading state: every
                   component in it draws its skeleton, so the window shows the screen's shape instead of nothing, and
                   the unscaled real screen is never painted. */}
-              {mode === 'pending' ? (
-                <LoadingScope bare>
-                  <PagePicture>{children}</PagePicture>
-                </LoadingScope>
-              ) : (
+              {/* One tree whether measured or not: only the scope turns off, so nothing inside is mounted twice. */}
+              <LoadingScope bare active={pending}>
                 <PagePicture>{children}</PagePicture>
-              )}
+              </LoadingScope>
             </div>
             <div ref={setPortalHost} style={{ display: 'contents' }} />
           </div>

package/src/components/ui/progress-bar.tsx

@@ -5,6 +5,7 @@ import { useEffect, useRef, useState } from 'react';
 import { useContentMdUp } from '../../hooks/ui/use-content-breakpoint';
 import { cn } from '../../utils/cn';
 import { UnifiedSkeleton } from '../loading/unified-skeleton';
+import { useLoadingScope } from './loading-scope';
 
 /** The bar's height in px: below the content `md` step, and from it (the bar switches on the content's width). */
 export const PROGRESS_BAR_HEIGHT = { mobile: 8, desktop: 24 } as const;
@@ -12,7 +13,7 @@ export const PROGRESS_BAR_HEIGHT = { mobile: 8, desktop: 24 } as const;
 const PROGRESS_BAR_HEIGHT_CLASS = 'h-2 content-md:h-6';
 
 /** The bar while its value is read: one box at the bar's own height, switched at the bar's own step. */
-export function ProgressBarSkeleton({ className }: { className?: string }) {
+function ProgressBarSkeleton({ className }: { className?: string }) {
   return <UnifiedSkeleton className={cn(PROGRESS_BAR_HEIGHT_CLASS, 'w-full rounded', className)} />;
 }
 
@@ -26,6 +27,9 @@ type ProgressBarProps = {
   height?: number; // desktop height (px)
   mobileHeight?: number; // mobile height (px)
   inverted?: boolean; // if true, high values are good (green), low values are bad (red)
+  /** The value is still being read: the bar draws its `ProgressBarSkeleton` at its own height. A loading scope does
+   *  the same. */
+  loading?: boolean;
 };
 
 export const ProgressBar: React.FC<ProgressBarProps> = ({
@@ -38,7 +42,10 @@ export const ProgressBar: React.FC<ProgressBarProps> = ({
   height = PROGRESS_BAR_HEIGHT.desktop,
   mobileHeight = PROGRESS_BAR_HEIGHT.mobile,
   inverted = false,
+  loading: loadingProp,
 }) => {
+  // ONE switch: in a page's loading state (or while the host reads the value) the bar is its skeleton.
+  const loading = useLoadingScope() || !!loadingProp;
   const isMdUp = useContentMdUp() ?? true;
   const effectiveSegmentWidth = isMdUp ? segmentWidth : mobileSegmentWidth;
   const effectiveHeight = isMdUp ? height : mobileHeight;
@@ -62,7 +69,10 @@ export const ProgressBar: React.FC<ProgressBarProps> = ({
     resizeObserver.observe(containerRef.current);
 
     return () => resizeObserver.disconnect();
-  }, [effectiveSegmentWidth, segmentGap]);
+    // `loading`: the box is mounted when the value arrives, so its segments are counted then.
+  }, [effectiveSegmentWidth, segmentGap, loading]);
+
+  if (loading) return <ProgressBarSkeleton />;
 
   // Pick color based on thresholds using ODS design tokens
   const getColor = () => {

package/src/components/ui/query-report-table/index.ts

@@ -1,13 +1,11 @@
 export { QueryReportTable } from './query-report-table';
 export { QueryReportTableHeader } from './query-report-table-header';
 export { QueryReportTableRow } from './query-report-table-row';
-export { QueryReportTableSkeleton } from './query-report-table-skeleton';
 export { deriveColumns, exportToCSV } from './utils';
 
 export type {
   QueryReportTableProps,
   QueryReportTableHeaderProps,
   QueryReportTableRowProps,
-  QueryReportTableSkeletonProps,
   QueryResultRow,
 } from './types';

package/src/components/ui/query-report-table/query-report-table-header.tsx

@@ -3,6 +3,7 @@
 import { useRef, useState, useCallback } from 'react';
 import { cn } from '../../../utils/cn';
 import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from '../tooltip';
+import { QUERY_REPORT_HEADER_CELL_CLASS, queryReportHeaderClass } from './query-report-table-row';
 import type { QueryReportTableHeaderProps } from './types';
 
 export function QueryReportTableHeader({
@@ -14,7 +15,7 @@ export function QueryReportTableHeader({
   const isCompact = variant === 'compact';
 
   return (
-    <div className={cn('flex items-center gap-4 px-4', isCompact ? 'border-b border-ods-border py-2' : '', className)}>
+    <div className={cn(queryReportHeaderClass(isCompact), className)}>
       {columns.map(column => (
         <TruncatedHeaderCell key={column} value={column} width={columnWidth} />
       ))}
@@ -37,7 +38,7 @@ function TruncatedHeaderCell({ value, width }: { value: string; width: number })
     <TooltipProvider delayDuration={300}>
       <Tooltip open={isTruncated ? undefined : false}>
         <TooltipTrigger asChild onMouseEnter={checkTruncation}>
-          <div className="flex shrink-0 items-center" style={{ width, height: 48 }}>
+          <div className={QUERY_REPORT_HEADER_CELL_CLASS} style={{ width }}>
             <div ref={textRef} className="truncate text-ods-text-secondary text-h5">
               {value}
             </div>

package/src/components/ui/query-report-table/query-report-table-row.tsx

@@ -2,37 +2,56 @@
 
 import { useRef, useState, useCallback } from 'react';
 import { cn } from '../../../utils/cn';
+import {
+  DATA_TABLE_ROW_FRAME_CLASS,
+  ROW_HEIGHT_DESKTOP,
+  ROW_SHELL_CLASSES,
+} from '../data-table/data-table-row-classes';
+import { loadingItemProps } from '../loading-scope';
 import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from '../tooltip';
 import type { QueryReportTableRowProps } from './types';
 
+/**
+ * The report's row boxes, loaded and loading, from the data table's row class set (`data-table-row-classes`): the
+ * default row is the data table's card, shell and height; a compact row a divided 56px line in the same shell.
+ */
+export const queryReportRowFrameClass = (compact: boolean) =>
+  compact ? 'border-b border-ods-border' : cn('relative', DATA_TABLE_ROW_FRAME_CLASS);
+export const queryReportRowCellsClass = (compact: boolean) =>
+  cn('flex', ROW_SHELL_CLASSES, compact ? 'h-[56px]' : ROW_HEIGHT_DESKTOP);
+/** The header's row: the rows' shell, so each header cell sits over its column. */
+export const queryReportHeaderClass = (compact: boolean) =>
+  cn('flex', ROW_SHELL_CLASSES, compact && 'border-b border-ods-border py-2');
+/** One header cell's box (48px high), loaded and loading. */
+export const QUERY_REPORT_HEADER_CELL_CLASS = 'flex h-12 shrink-0 items-center';
+/** The rows' stack and the gap between rows, loaded and loading. */
+export const queryReportRowsClass = (compact: boolean) =>
+  cn('flex flex-col', compact ? 'gap-0' : 'gap-[var(--spacing-system-xs)]');
+/** One cell's box, loaded and loading. */
+export const QUERY_REPORT_CELL_CLASS = 'flex shrink-0 flex-col justify-center overflow-hidden';
+
 export function QueryReportTableRow({
   row,
   columns,
   columnWidth,
   variant = 'default',
   className,
+  ...props
 }: QueryReportTableRowProps) {
   const isCompact = variant === 'compact';
 
   return (
     <div
-      className={cn(
-        isCompact
-          ? 'border-b border-ods-border'
-          : 'relative overflow-hidden rounded-[6px] border border-ods-border bg-ods-card',
-        className,
-      )}
+      // A list's markers (`data-loading-item`) ride on the row, as on its loading form's rows.
+      {...loadingItemProps(props)}
+      className={cn(queryReportRowFrameClass(isCompact), className)}
     >
-      <div className={cn('flex items-center gap-4 px-4', isCompact ? 'h-[56px]' : 'h-[80px]')}>
+      <div className={queryReportRowCellsClass(isCompact)}>
         {columns.map(column => {
           const value = row[column];
           const displayValue = value === null || value === undefined ? '-' : String(value);
           return (
-            <div
-              key={column}
-              className="flex shrink-0 flex-col justify-center overflow-hidden"
-              style={{ width: columnWidth }}
-            >
+            <div key={column} className={QUERY_REPORT_CELL_CLASS} style={{ width: columnWidth }}>
               <TruncatedCell
                 className={cn('text-ods-text-primary', isCompact ? 'text-h6' : 'text-h4')}
                 value={displayValue}

package/src/components/ui/query-report-table/query-report-table-skeleton.tsx

@@ -2,7 +2,16 @@
 
 import { cn } from '../../../utils/cn';
 import { LoadingRegion } from '../../loading/loading-region';
-import { UnifiedSkeleton } from '../../loading/unified-skeleton';
+import { TextLineSkeleton } from '../../loading/unified-skeleton';
+import { LoadingItems } from '../loading-scope';
+import {
+  QUERY_REPORT_CELL_CLASS,
+  QUERY_REPORT_HEADER_CELL_CLASS,
+  queryReportHeaderClass,
+  queryReportRowCellsClass,
+  queryReportRowFrameClass,
+  queryReportRowsClass,
+} from './query-report-table-row';
 import type { QueryReportTableSkeletonProps } from './types';
 
 export function QueryReportTableSkeleton({
@@ -16,42 +25,40 @@ export function QueryReportTableSkeleton({
   const isCompact = variant === 'compact';
 
   return (
-    <LoadingRegion
-      label="Loading results"
-      announce={region}
-      className={cn('flex flex-col', isCompact ? 'gap-0' : 'gap-[var(--spacing-system-xs)]', className)}
-    >
-      {/* Skeleton header */}
-      <div className={cn('flex items-center gap-4 px-4', isCompact ? 'border-b border-ods-border py-2' : '')}>
-        {Array.from({ length: columns }).map((_, i) => (
-          <div key={`header-${i}`} className="flex shrink-0 items-center" style={{ width: columnWidth, height: 48 }}>
-            <UnifiedSkeleton className="h-4 w-3/4 rounded" />
-          </div>
-        ))}
+    <LoadingRegion label="Loading results" announce={region} className={cn('flex flex-col', className)}>
+      {/* Skeleton header: the columns are the result's, drawn as `columns` bars (cells of one header row). It sits on
+          the rows, as the loaded header does. */}
+      <div className={queryReportHeaderClass(isCompact)}>
+        <LoadingItems count={columns}>
+          {() => (
+            <div className={QUERY_REPORT_HEADER_CELL_CLASS} style={{ width: columnWidth }}>
+              <TextLineSkeleton type="h5" className="w-3/4" />
+            </div>
+          )}
+        </LoadingItems>
       </div>
 
-      {/* Skeleton rows */}
-      {Array.from({ length: rows }).map((_, rowIndex) => (
-        <div
-          key={`row-${rowIndex}`}
-          className={cn(
-            isCompact
-              ? 'border-b border-ods-border'
-              : 'relative overflow-hidden rounded-[6px] border border-ods-border bg-ods-card',
-          )}
-        >
-          <div className={cn('flex items-center gap-4 px-4', isCompact ? 'h-[56px]' : 'h-[80px]')}>
-            {Array.from({ length: columns }).map((_cell, colIndex) => (
-              <div key={`cell-${rowIndex}-${colIndex}`} className="shrink-0" style={{ width: columnWidth }}>
-                <UnifiedSkeleton
-                  className={cn('rounded', isCompact ? 'h-4' : 'h-5')}
-                  width={`${55 + ((rowIndex * colIndex * 7) % 35)}%`}
-                />
+      {/* Skeleton rows: the result's rows (marked like the loaded rows), each `columns` cells. */}
+      <div className={queryReportRowsClass(isCompact)}>
+        <LoadingItems count={rows}>
+          {rowIndex => (
+            <div data-loading-item className={queryReportRowFrameClass(isCompact)}>
+              <div className={queryReportRowCellsClass(isCompact)}>
+                <LoadingItems count={columns}>
+                  {colIndex => (
+                    <div className={QUERY_REPORT_CELL_CLASS} style={{ width: columnWidth }}>
+                      <TextLineSkeleton
+                        type={isCompact ? 'h6' : 'h4'}
+                        width={`${55 + ((rowIndex * colIndex * 7) % 35)}%`}
+                      />
+                    </div>
+                  )}
+                </LoadingItems>
               </div>
-            ))}
-          </div>
-        </div>
-      ))}
+            </div>
+          )}
+        </LoadingItems>
+      </div>
     </LoadingRegion>
   );
 }

package/src/components/ui/query-report-table/query-report-table.tsx

@@ -5,21 +5,28 @@ import { useHorizontalScrollbar } from '../../../hooks/ui/use-horizontal-scrollb
 import { cn } from '../../../utils/cn';
 import { Download02Icon } from '../../icons-v2-generated/interface/download-02-icon';
 import { Button } from '../button';
-import { TableEmptyState } from '../table/table-empty-state';
+import { DataTableEmpty } from '../data-table/data-table-empty';
+import { InertWhileLoading, useLoadingScope } from '../loading-scope';
 import { QueryReportTableHeader } from './query-report-table-header';
-import { QueryReportTableRow } from './query-report-table-row';
+import { QueryReportTableRow, queryReportRowsClass } from './query-report-table-row';
 import { QueryReportTableSkeleton } from './query-report-table-skeleton';
 import type { QueryReportTableProps } from './types';
 import { deriveColumns, exportToCSV } from './utils';
 
+/** The rows a loading report draws when the host states none: a typical report, since a report has no page size. */
+const QUERY_REPORT_TABLE_SKELETON_ROWS = 8;
+/** The columns a loading report draws when the host states none: a typical result (the columns are the data's). */
+const QUERY_REPORT_TABLE_SKELETON_COLUMNS = 6;
+
 export function QueryReportTable({
   title,
   data,
-  loading = false,
+  loading: loadingProp = false,
   loadingRegion = true,
-  skeletonRows = 8,
-  skeletonColumns = 6,
+  skeletonRows = QUERY_REPORT_TABLE_SKELETON_ROWS,
+  skeletonColumns = QUERY_REPORT_TABLE_SKELETON_COLUMNS,
   emptyMessage,
+  emptyState,
   columnWidth = 160,
   columnOrder,
   showExport = true,
@@ -30,7 +37,9 @@ export function QueryReportTable({
   className,
   tableClassName,
 }: QueryReportTableProps) {
+  const loading = useLoadingScope() || loadingProp;
   const isCompact = variant === 'compact';
+  const showExportButton = showExport && (loading || data.length > 0);
   const columns = useMemo(() => deriveColumns(data, columnOrder), [data, columnOrder]);
 
   const handleExport = () => {
@@ -58,28 +67,32 @@ export function QueryReportTable({
 
   return (
     <div className={cn('flex w-full flex-col', isCompact ? 'gap-0' : 'gap-[var(--spacing-system-l)]', className)}>
-      {/* Title bar — hidden in compact mode and when empty */}
-      {!isCompact && (title || headerActions || (showExport && data.length > 0)) && (
+      {/* Title bar — hidden in compact mode and when there is nothing to show in it. Export is drawn while the rows
+          are read too (real and inert: they will hold data), so the bar does not appear when they land. */}
+      {!isCompact && (title || headerActions || showExportButton) && (
         <div className="flex items-end justify-between pt-[var(--spacing-system-l)]">
           <h2 className="text-ods-text-primary text-h2">{title}</h2>
           <div className="flex items-center gap-[var(--spacing-system-s)]">
             {headerActions}
-            {showExport && data.length > 0 && (
-              <Button
-                className="bg-ods-card content-max-md:hidden"
-                variant="outline"
-                leftIcon={<Download02Icon size={18} className="text-ods-text-secondary" />}
-                onClick={handleExport}
-              >
-                Export CSV
-              </Button>
+            {showExportButton && (
+              <InertWhileLoading loading={loading} className="inline-flex shrink-0 content-max-md:hidden">
+                <Button
+                  className="bg-ods-card"
+                  variant="outline"
+                  leftIcon={<Download02Icon size={18} className="text-ods-text-secondary" />}
+                  onClick={handleExport}
+                >
+                  Export CSV
+                </Button>
+              </InertWhileLoading>
             )}
           </div>
         </div>
       )}
 
-      {/* Loading state */}
-      {loading && (
+      {/* One slot, three forms: loading (the rows' skeleton), empty (the same mapping `DataTable.Body` makes:
+          `emptyState` wins; `emptyMessage` is its title), and the table. */}
+      {loading ? (
         <QueryReportTableSkeleton
           rows={skeletonRows}
           columns={skeletonColumns}
@@ -87,13 +100,15 @@ export function QueryReportTable({
           variant={variant}
           region={loadingRegion}
         />
-      )}
-
-      {/* Empty state */}
-      {!loading && data.length === 0 && <TableEmptyState message={emptyMessage} />}
-
-      {/* Table content */}
-      {!loading && data.length > 0 && (
+      ) : data.length === 0 ? (
+        emptyState ? (
+          <DataTableEmpty {...emptyState} />
+        ) : emptyMessage != null ? (
+          <DataTableEmpty title={emptyMessage} description={undefined} />
+        ) : (
+          <DataTableEmpty />
+        )
+      ) : (
         <div className="flex flex-col">
           {/* Custom scrollbar track — hidden in compact mode */}
           {!isCompact && thumbRatio > 0 && (
@@ -124,10 +139,11 @@ export function QueryReportTable({
             <div ref={scrollRef} className={cn('overflow-x-auto', tableClassName)} onScroll={onScroll}>
               <div style={{ minWidth: tableMinWidth }}>
                 <QueryReportTableHeader columns={columns} columnWidth={columnWidth} variant={variant} />
-                <div className={cn('flex flex-col', isCompact ? 'gap-0' : 'gap-[var(--spacing-system-xs)]')}>
+                <div className={queryReportRowsClass(isCompact)}>
                   {data.map((row, index) => (
                     <QueryReportTableRow
                       key={index}
+                      data-loading-item
                       row={row}
                       columns={columns}
                       columnWidth={columnWidth}

package/src/components/ui/query-report-table/types.ts

@@ -1,4 +1,5 @@
 import type { ReactNode } from 'react';
+import type { NoDataProps } from '../no-data';
 
 export type QueryResultRow = Record<string, string | number | null>;
 
@@ -17,8 +18,11 @@ export interface QueryReportTableProps {
   skeletonRows?: number;
   /** Number of skeleton columns to display (default: 6) */
   skeletonColumns?: number;
-  /** Message shown when data is empty */
+  /** @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, as `DataTable.Body` takes them. Overrides
+   *  `emptyMessage`. */
+  emptyState?: NoDataProps;
   /** Fixed width for each column in pixels (default: 160) */
   columnWidth?: number;
   /** Explicit column ordering — keys not listed are appended at the end */