@multiplatform.one/components 6.1.0 → 6.3.0

package/src/views/List.stories.tsx

@@ -1,3 +1,4 @@
+import { action } from "@multiplatform.one/storybook";
 import type { Meta } from "@storybook/react-native-web-vite";
 import { Text } from "tamagui";
 import { List } from "./List";
@@ -34,9 +35,60 @@ export const Default = {
   render: () => (
     <List<ListItemData>
       items={items}
-      getItemKey={(item) => item.id}
       renderItem={(item) => <Text fontSize="$3">{item.title}</Text>}
-      onItemPress={(item) => console.log("Pressed:", item.id)}
+      onItemClick={action("onItemClick")}
+      height={400}
+    />
+  ),
+};
+
+export const Loading = {
+  render: () => (
+    <List<ListItemData>
+      items={[]}
+      renderItem={(item) => <Text fontSize="$3">{item.title}</Text>}
+      isLoading
+      height={400}
+    />
+  ),
+};
+
+/** No items, no filters, no failure — the neutral empty state (Axiom 6: empty ≠ error). */
+export const Empty = {
+  render: () => (
+    <List<ListItemData>
+      items={[]}
+      renderItem={(item) => <Text fontSize="$3">{item.title}</Text>}
+      emptyMessage="No tasks yet"
+      height={400}
+    />
+  ),
+};
+
+/** Failed load wins over empty — error chrome with retry, never empty chrome (DG-ST-01). */
+export const Error = {
+  render: () => (
+    <List<ListItemData>
+      items={[]}
+      renderItem={(item) => <Text fontSize="$3">{item.title}</Text>}
+      error="The server did not respond."
+      onRetry={action("onRetry")}
+      height={400}
+    />
+  ),
+};
+
+/**
+ * Data exists upstream but the active search/filter matches nothing —
+ * no-results ≠ empty (Axiom 6 HONEST STATE). List carries no filter state of
+ * its own, so the consumer names the filter in `emptyMessage`.
+ */
+export const NoResults = {
+  render: () => (
+    <List<ListItemData>
+      items={[]}
+      renderItem={(item) => <Text fontSize="$3">{item.title}</Text>}
+      emptyMessage='No tasks match "deployment"'
       height={400}
     />
   ),

package/src/views/List.tsx

@@ -1,10 +1,13 @@
 import { componentColors } from "../componentColors";
+import { AsyncBoundary } from "../layouts/AsyncBoundary";
+import { Spinner } from "@multiplatform.one/forms";
 import { FlashList, type FlashListRef } from "@shopify/flash-list";
 import { useResolvedKnobs } from "@multiplatform.one/theme";
 import { useHotkey } from "@tanstack/react-hotkeys";
 import type { RegisterableHotkey } from "@tanstack/react-hotkeys";
-import React, { useCallback, useId, useRef, useState } from "react";
-import { ListItem, Spinner, Text, View, YStack, type YStackProps } from "tamagui";
+import React, { useCallback, useId, useRef, useState, type ReactNode } from "react";
+import { useTranslation } from "react-i18next";
+import { ListItem, View, YStack, type YStackProps } from "tamagui";
 
 /**
  * Configurable hotkey bindings for the List component.
@@ -44,6 +47,13 @@ export interface ListProps<T> extends Omit<YStackProps, "children"> {
   hasMore?: boolean;
   /** Whether data is loading */
   isLoading?: boolean;
+  /**
+   * Failed load (DG-ST-01 / W9). Wins over empty — never shows empty chrome.
+   * Pass a string, Error, custom node, or `true` for the default error UI.
+   */
+  error?: boolean | string | Error | ReactNode | null;
+  /** Retry handler for the default error UI. */
+  onRetry?: () => void;
   /** Estimated size of each item in pixels (default: 56) */
   estimateSize?: number;
   /** Number of items to render outside visible area (default: 5) */
@@ -85,18 +95,38 @@ export function List<T>({
   onLoadMore,
   hasMore = false,
   isLoading = false,
+  error = null,
+  onRetry,
   estimateSize: estimateSizeProp,
   overscan = 5,
-  emptyMessage = "No items found",
+  emptyMessage: emptyMessageProp,
   height: heightProp,
   "aria-label": ariaLabel,
   hotkeys: hotkeyOverrides,
   ...stackProps
 }: ListProps<T>) {
+  const { t } = useTranslation();
+  const emptyMessage = emptyMessageProp ?? t("No items found");
   const { knobProps } = useResolvedKnobs();
   const sz = knobProps.sizeToken;
   const estimateSize = estimateSizeProp ?? (sz === "$3" ? 44 : sz === "$5" ? 68 : 56);
-  const height = heightProp ?? (sz === "$3" ? 320 : sz === "$5" ? 480 : 400);
+  // No explicit height: hug content when the list is complete (page scrolls,
+  // no dead space / nested scrollbar); cap + scroll internally only while
+  // more pages can stream in (FlashList needs a bounded viewport to
+  // virtualize + fire onEndReached). The cap is a content-derived dial —
+  // ten estimated rows at the active size — not a raw pixel constant
+  // (LC-28 / DG-LAY-01).
+  const STREAMING_VIEWPORT_ROWS = 10;
+  const scrollCap = estimateSize * STREAMING_VIEWPORT_ROWS;
+  // The hug height tracks the MEASURED content size once FlashList reports
+  // it: an estimate-derived hug slices the last rows mid-row whenever rows
+  // render taller than the estimate (LC-10 FRAME-CONTAINMENT — measured
+  // overB 122/148 on FrappeList/FrappeListView). The estimate is only the
+  // pre-measure first paint.
+  const [measuredContentHeight, setMeasuredContentHeight] = useState<number | null>(null);
+  const height =
+    heightProp ??
+    (hasMore ? scrollCap : (measuredContentHeight ?? Math.max(items.length, 1) * estimateSize + 8));
   const listId = useId();
   const containerRef = useRef<HTMLDivElement>(null);
   const flashListRef = useRef<FlashListRef<T>>(null);
@@ -205,84 +235,94 @@ export function List<T>({
     }
   }, [onLoadMore, hasMore, isLoading]);
 
-  if (isLoading && items.length === 0) {
-    return (
-      <YStack {...knobProps.panelPadding} alignItems="center" {...stackProps}>
-        <Spinner size="large" />
-      </YStack>
-    );
-  }
+  // Clamp focused index if items shrunk
+  const effectiveFocused = focusedIndex >= items.length ? -1 : focusedIndex;
 
-  if (items.length === 0) {
-    return (
-      <YStack {...knobProps.panelPadding} alignItems="center" {...stackProps}>
-        <Text color={componentColors.text.muted}>{emptyMessage}</Text>
+  const listBody =
+    items.length === 0 ? null : (
+      <YStack {...knobProps.gap}>
+        <View
+          ref={containerRef as any}
+          role="list"
+          aria-label={ariaLabel}
+          aria-activedescendant={
+            effectiveFocused >= 0 ? `${listId}-item-${effectiveFocused}` : undefined
+          }
+          tabIndex={0}
+          outlineWidth={0}
+          style={{
+            height,
+          }}
+        >
+          <FlashList
+            ref={flashListRef}
+            data={items}
+            drawDistance={overscan * estimateSize}
+            onEndReached={handleEndReached}
+            onEndReachedThreshold={0.5}
+            onContentSizeChange={(_w, contentHeight) => {
+              if (contentHeight > 0) {
+                setMeasuredContentHeight((prev) => (prev === contentHeight ? prev : contentHeight));
+              }
+            }}
+            keyExtractor={(_, index) => `${listId}-item-${index}`}
+            renderItem={({ item, index }) => {
+              const isFocused = effectiveFocused === index;
+              return (
+                <ListItem
+                  id={`${listId}-item-${index}`}
+                  size={knobProps.sizeToken}
+                  // Item rows are R-SCALE (spec List rows): the hover/focus
+                  // row surface rounds with the radius knob — radius channel
+                  // only (Sidebar row precedent), rows never gain the
+                  // fragment's border width.
+                  borderRadius={knobProps.borderRadius.borderRadius}
+                  role="listitem"
+                  aria-selected={isFocused}
+                  {...(isFocused ? { "data-focused": true } : {})}
+                  backgroundColor={isFocused ? "$accentBackground" : "transparent"}
+                  hoverStyle={{ backgroundColor: componentColors.interactive.background }}
+                  pressStyle={{ backgroundColor: componentColors.interactive.hover }}
+                  cursor={onItemClick ? "pointer" : "default"}
+                  borderBottomWidth={1}
+                  borderBottomColor="$borderColor"
+                  onPress={
+                    onItemClick
+                      ? () => {
+                          setFocusedIndex(index);
+                          onItemClick(item);
+                        }
+                      : undefined
+                  }
+                >
+                  {renderItem(item, index)}
+                </ListItem>
+              );
+            }}
+            ListFooterComponent={
+              isLoading && items.length > 0 ? (
+                <YStack padding="$2" alignItems="center">
+                  <Spinner size="small" />
+                </YStack>
+              ) : null
+            }
+          />
+        </View>
       </YStack>
     );
-  }
-
-  // Clamp focused index if items shrunk
-  const effectiveFocused = focusedIndex >= items.length ? -1 : focusedIndex;
 
   return (
-    <YStack {...knobProps.gap} {...stackProps}>
-      <View
-        ref={containerRef as any}
-        role="list"
-        aria-label={ariaLabel}
-        aria-activedescendant={
-          effectiveFocused >= 0 ? `${listId}-item-${effectiveFocused}` : undefined
-        }
-        tabIndex={0}
-        outlineWidth={0}
-        style={{
-          height,
-        }}
-      >
-        <FlashList
-          ref={flashListRef}
-          data={items}
-          drawDistance={overscan * estimateSize}
-          onEndReached={handleEndReached}
-          onEndReachedThreshold={0.5}
-          keyExtractor={(_, index) => `${listId}-item-${index}`}
-          renderItem={({ item, index }) => {
-            const isFocused = effectiveFocused === index;
-            return (
-              <ListItem
-                id={`${listId}-item-${index}`}
-                size={knobProps.sizeToken}
-                role="listitem"
-                aria-selected={isFocused}
-                {...(isFocused ? { "data-focused": true } : {})}
-                backgroundColor={isFocused ? "$accentBackground" : "transparent"}
-                hoverStyle={{ backgroundColor: componentColors.interactive.background }}
-                pressStyle={{ backgroundColor: componentColors.interactive.hover }}
-                cursor={onItemClick ? "pointer" : "default"}
-                borderBottomWidth={1}
-                borderBottomColor="$borderColor"
-                onPress={
-                  onItemClick
-                    ? () => {
-                        setFocusedIndex(index);
-                        onItemClick(item);
-                      }
-                    : undefined
-                }
-              >
-                {renderItem(item, index)}
-              </ListItem>
-            );
-          }}
-          ListFooterComponent={
-            isLoading && items.length > 0 ? (
-              <YStack padding="$2" alignItems="center">
-                <Spinner size="small" />
-              </YStack>
-            ) : null
-          }
-        />
-      </View>
-    </YStack>
+    <AsyncBoundary
+      loading={!error && isLoading && items.length === 0}
+      empty={!error && items.length === 0}
+      error={error}
+      onRetry={onRetry}
+      layout="list"
+      compact
+      emptyTitle={emptyMessage}
+      {...stackProps}
+    >
+      {listBody}
+    </AsyncBoundary>
   );
 }

package/src/views/ReportBuilder.stories.tsx

@@ -1,3 +1,4 @@
+import { action } from "@multiplatform.one/storybook";
 import type { Meta } from "@storybook/react-native-web-vite";
 import { ReportBuilder, type ReportColumn } from "./ReportBuilder";
 
@@ -26,11 +27,46 @@ export default meta;
 
 export const Default = {
   name: "Main",
+  render: () => (
+    <ReportBuilder columns={columns} data={data} height={420} onExport={action("onExport")} />
+  ),
+};
+
+/**
+ * Zero rows — the inline "No data to display" empty state (Axiom 6: empty ≠ error).
+ * The report body is a flex/scroll region, so page-flow stories give it an
+ * explicit height (same pattern as the ImageGrid state stories).
+ */
+export const Empty = {
+  render: () => <ReportBuilder columns={columns} data={[]} height={420} />,
+};
+
+/** Rows still loading — table-shaped skeleton twin inside the report card (LC-20 / DG-ST-02). */
+export const Loading = {
+  render: () => <ReportBuilder columns={columns} data={[]} height={420} isLoading />,
+};
+
+/**
+ * Rows exist upstream but the active filters match nothing — "No results
+ * found" renders instead of the true-empty chrome (DG-TBL-06 / Axiom 6:
+ * empty ≠ no-results). The caller signals narrowing via `hasActiveFilters`.
+ */
+export const NoResults = {
+  render: () => <ReportBuilder columns={columns} data={[]} height={420} hasActiveFilters />,
+};
+
+/**
+ * Failed load wins over empty — error chrome with Retry replaces the report;
+ * the toolbar's column count and the table hide so they can't lie
+ * (DG-ST-01 / DG-ST-04).
+ */
+export const Error = {
   render: () => (
     <ReportBuilder
       columns={columns}
-      data={data}
-      onExport={(rows) => console.log("Export:", rows)}
+      data={[]}
+      error="The report rows could not be loaded."
+      onRetry={action("onRetry")}
     />
   ),
 };

package/src/views/ReportBuilder.tsx

@@ -1,6 +1,10 @@
+import { BarChart } from "../charts/BarChart";
 import { componentColors } from "../componentColors";
+import { AsyncBoundary, AsyncSkeleton, resolveAsyncStatus } from "../layouts/AsyncBoundary";
+import { EmptyState } from "../layouts/page";
 import { useResolvedKnobs } from "@multiplatform.one/theme";
 import React, { useState, useMemo, useCallback } from "react";
+import { useTranslation } from "react-i18next";
 import { Button, Card, ScrollView, Text, XStack, YStack, type YStackProps } from "tamagui";
 
 // ============================================================================
@@ -49,8 +53,26 @@ export interface ReportBuilderProps extends Omit<YStackProps, "children"> {
   onColumnsChange?: (enabledFieldnames: string[]) => void;
   /** Called for data export */
   onExport?: (data: Record<string, unknown>[]) => void;
+  /** Row press handler — rows become interactive when provided */
+  onRowPress?: (row: Record<string, unknown>, index: number) => void;
   /** Show a simple bar chart for grouped data (default: false) */
   showChart?: boolean;
+  /** Whether report rows are loading — renders a table-shaped skeleton (LC-20 / DG-ST-02) */
+  isLoading?: boolean;
+  /**
+   * Failed load (DG-ST-01 / Axiom 6). Wins over the empty chrome and hides
+   * the toolbar/chart so counts can't lie (DG-ST-04). Pass a string, Error,
+   * custom node, or `true` for the default error UI.
+   */
+  error?: boolean | string | Error | React.ReactNode | null;
+  /** Retry handler for the default error chrome */
+  onRetry?: () => void;
+  /**
+   * True when the caller has filters narrowing `data`. Zero rows then render
+   * as "no results" instead of the true-empty chrome (DG-TBL-06 / Axiom 6:
+   * empty ≠ no-results).
+   */
+  hasActiveFilters?: boolean;
 }
 
 // ============================================================================
@@ -59,6 +81,13 @@ export interface ReportBuilderProps extends Omit<YStackProps, "children"> {
 
 const numericFieldTypes = new Set(["Int", "Float", "Currency", "Percent", "Rating", "Duration"]);
 
+/** Dense report copy rides two steps below the size knob (medium keeps $2). */
+const reportTextSizeMap: Record<string, "$1" | "$2" | "$3"> = {
+  $3: "$1",
+  $4: "$2",
+  $5: "$3",
+};
+
 const aggregationLabels: Record<GroupByConfig["aggregation"], string> = {
   count: "Count",
   sum: "Sum",
@@ -67,17 +96,6 @@ const aggregationLabels: Record<GroupByConfig["aggregation"], string> = {
   max: "Max",
 };
 
-const defaultChartColors = [
-  "var(--accentBackground)",
-  "var(--color7)",
-  "var(--color8)",
-  "var(--color9)",
-  "var(--color10)",
-  "var(--color11)",
-  "var(--color6)",
-  "var(--color5)",
-];
-
 // ============================================================================
 // Helpers
 // ============================================================================
@@ -125,13 +143,13 @@ function SimpleBarChart({
   height?: number;
 }) {
   const { knobProps } = useResolvedKnobs();
-  const maxValue = useMemo(() => Math.max(...data.map((d) => d.value), 1), [data]);
   if (data.length === 0) return null;
 
-  const barWidth = 100 / Math.max(data.length, 1);
-  const padding = barWidth * 0.15;
-  const chartHeight = height - 30;
-
+  // One measure across group rows = a single series: the universal BarChart
+  // defaults every bar to the theme identity from the canonical chart
+  // palette (LC-27); per-bar hue variation would imply information the data
+  // doesn't carry. The chart is universal (d3 math + react-native-svg), so
+  // the report chart now renders on native too.
   return (
     <Card
       size={knobProps.sizeToken}
@@ -139,44 +157,7 @@ function SimpleBarChart({
       padding="$2"
       overflow="hidden"
     >
-      <YStack height={height} width="100%">
-        <svg
-          width="100%"
-          height="100%"
-          viewBox={`0 0 100 ${height}`}
-          preserveAspectRatio="none"
-          role="img"
-          aria-label="Bar chart"
-        >
-          {data.map((point, index) => {
-            const barHeight = (point.value / maxValue) * chartHeight;
-            const x = index * barWidth + padding;
-            const y = height - 30 - barHeight;
-            const color = defaultChartColors[index % defaultChartColors.length];
-            return (
-              <g key={`${point.label}-${index}`}>
-                <rect
-                  x={`${x}%`}
-                  y={y}
-                  width={`${barWidth - padding * 2}%`}
-                  height={barHeight}
-                  fill={color}
-                  rx="2"
-                />
-                <text
-                  x={`${x + (barWidth - padding * 2) / 2}%`}
-                  y={height - 8}
-                  textAnchor="middle"
-                  fontSize="7"
-                  fill="currentColor"
-                >
-                  {point.label.length > 10 ? `${point.label.slice(0, 10)}\u2026` : point.label}
-                </text>
-              </g>
-            );
-          })}
-        </svg>
-      </YStack>
+      <BarChart data={data} height={height} />
     </Card>
   );
 }
@@ -210,10 +191,22 @@ export function ReportBuilder({
   onGroupByChange,
   onColumnsChange,
   onExport,
+  onRowPress,
   showChart = false,
+  isLoading = false,
+  error = null,
+  onRetry,
+  hasActiveFilters = false,
   ...stackProps
 }: ReportBuilderProps) {
+  const { t } = useTranslation();
   const { knobProps } = useResolvedKnobs();
+  // Report chrome copy follows the size knob through the dense-table scale
+  // (LC-18 / SB-M-804); medium stays at the previous $2.
+  const reportFontSize = reportTextSizeMap[knobProps.sizeToken] ?? "$2";
+  // Error wins (DG-ST-01); initial load renders the table-shaped skeleton twin.
+  const hasError = resolveAsyncStatus({ error }) === "error";
+  const isInitialLoading = !hasError && isLoading && data.length === 0;
   // Column management
   const [enabledColumnSet, setEnabledColumnSet] = useState<Set<string>>(
     () => new Set(columns.filter((c) => c.enabled).map((c) => c.fieldname)),
@@ -361,7 +354,7 @@ export function ReportBuilder({
           key={col.fieldname}
           flex={1}
           fontWeight="600"
-          fontSize="$2"
+          fontSize={reportFontSize}
           color="$color"
           paddingHorizontal="$2"
           numberOfLines={1}
@@ -384,13 +377,14 @@ export function ReportBuilder({
           : { backgroundColor: componentColors.surface.background }.backgroundColor
       }
       hoverStyle={{ backgroundColor: componentColors.surface.background }}
-      {...(isGrouped ? { paddingLeft: knobProps.panelPadding.padding } : {})}
+      {...(isGrouped ? { paddingInlineStart: knobProps.panelPadding.padding } : {})}
+      {...(onRowPress ? { cursor: "pointer", onPress: () => onRowPress(row, index) } : {})}
     >
       {enabledColumns.map((col) => (
         <Text
           key={col.fieldname}
           flex={1}
-          fontSize="$2"
+          fontSize={reportFontSize}
           color="$color"
           paddingHorizontal="$2"
           numberOfLines={1}
@@ -435,15 +429,15 @@ export function ReportBuilder({
             onPress={() => toggleGroup(groupKey)}
             hoverStyle={{ backgroundColor: componentColors.interactive.hover }}
           >
-            <Text fontSize="$2">{isCollapsed ? "▶" : "▼"}</Text>
-            <Text fontWeight="600" fontSize="$2" color="$accentColor">
+            <Text fontSize={reportFontSize}>{isCollapsed ? "▶" : "▼"}</Text>
+            <Text fontWeight="600" fontSize={reportFontSize} color="$accentColor">
               {groupByCol?.label ?? groupBy.field}: {groupKey}
             </Text>
-            <Text fontSize="$2" color={componentColors.text.muted}>
+            <Text fontSize={reportFontSize} color={componentColors.text.muted}>
               ({group.rows.length} {group.rows.length === 1 ? "record" : "records"})
             </Text>
             <XStack flex={1} />
-            <Text fontWeight="500" fontSize="$2" color="$accentColor">
+            <Text fontWeight="500" fontSize={reportFontSize} color="$accentColor">
               {aggDisplay}
             </Text>
           </XStack>
@@ -454,6 +448,22 @@ export function ReportBuilder({
     });
   };
 
+  // Failed load: error chrome replaces the report; toolbar/chart/table hide
+  // so the column count and stale rows can't lie (DG-ST-01 / DG-ST-04).
+  if (hasError) {
+    return (
+      <AsyncBoundary
+        error={error}
+        onRetry={onRetry}
+        layout="table"
+        compact
+        errorTitle={t("Couldn't load report")}
+        {...knobProps.gap}
+        {...stackProps}
+      />
+    );
+  }
+
   return (
     <YStack {...knobProps.gap} {...stackProps}>
       {/* Toolbar */}
@@ -465,7 +475,7 @@ export function ReportBuilder({
       >
         <XStack {...knobProps.panelPadding} {...knobProps.gap} alignItems="center" flexWrap="wrap">
           {/* Column toggle info */}
-          <Text fontSize="$2" color={componentColors.text.muted}>
+          <Text fontSize={reportFontSize} color={componentColors.text.muted}>
             {enabledColumns.length} / {columns.length} columns
           </Text>
 
@@ -474,7 +484,7 @@ export function ReportBuilder({
           {/* Chart toggle */}
           {showChart && groupedData && (
             <Button
-              size="$2"
+              size={reportFontSize}
               onPress={() => setChartVisible((v) => !v)}
               theme={chartVisible ? "active" : undefined}
             >
@@ -484,7 +494,7 @@ export function ReportBuilder({
 
           {/* Export */}
           {onExport && (
-            <Button size="$2" onPress={handleExport}>
+            <Button size={reportFontSize} onPress={handleExport}>
               Export
             </Button>
           )}
@@ -506,22 +516,30 @@ export function ReportBuilder({
         borderColor="$borderColor"
         flex={1}
       >
-        <ScrollView flex={1}>
-          <YStack minWidth="100%">
-            {renderHeaderRow()}
-            {groupBy && groupedData
-              ? renderGroupedRows()
-              : data.map((row, index) => renderDataRow(row, index))}
-
-            {data.length === 0 && (
-              <YStack {...knobProps.panelPadding} alignItems="center" justifyContent="center">
-                <Text color={componentColors.text.muted} fontSize={knobProps.sizeToken}>
-                  No data to display
-                </Text>
-              </YStack>
-            )}
-          </YStack>
-        </ScrollView>
+        {isInitialLoading ? (
+          /* Skeleton twin inside the live table card (LC-20 / DG-ST-02) */
+          <AsyncSkeleton layout="table" padding="$2" />
+        ) : (
+          <ScrollView flex={1}>
+            <YStack minWidth="100%">
+              {renderHeaderRow()}
+              {groupBy && groupedData
+                ? renderGroupedRows()
+                : data.map((row, index) => renderDataRow(row, index))}
+
+              {/* Zero rows: distinguish "filters matched nothing" from a truly
+                  empty dataset (DG-TBL-06 / Axiom 6: empty ≠ no-results) */}
+              {data.length === 0 && (
+                <EmptyState
+                  compact
+                  aria-live="polite"
+                  data-async-state={hasActiveFilters ? "no-results" : "empty"}
+                  title={hasActiveFilters ? t("No results found") : t("No data to display")}
+                />
+              )}
+            </YStack>
+          </ScrollView>
+        )}
       </Card>
     </YStack>
   );