@multiplatform.one/components 6.1.0 → 6.4.0

package/src/views/ImageGrid.stories.tsx

@@ -1,3 +1,4 @@
+import { action } from "@multiplatform.one/storybook";
 import type { Meta } from "@storybook/react-native-web-vite";
 import { Text, View } from "tamagui";
 import { ImageGrid } from "./ImageGrid";
@@ -29,13 +30,14 @@ export const Default = {
     <ImageGrid<ImageItem>
       items={items}
       columns={3}
-      getItemKey={(item) => item.id}
       renderItem={(item) => (
+        // No tile-owned radius (G-15 story honesty): ImageGrid's card frame
+        // clips items at the knob radius — a pinned $3 held a 7px arc at
+        // borderRadius:none (UX-P06 "ImageGrid tiles br=7").
         <View
           width="100%"
           aspectRatio={1}
           backgroundColor="$color3"
-          borderRadius="$3"
           alignItems="center"
           justifyContent="center"
         >
@@ -46,3 +48,55 @@ export const Default = {
     />
   ),
 };
+
+/**
+ * Initial load with no items renders the grid-shaped skeleton twin — muted
+ * aspect-correct blocks in the live cell geometry, not a raw spinner
+ * (LC-20 / DG-ST-02).
+ */
+export const Loading = {
+  render: () => <ImageGrid<ImageItem> items={[]} columns={3} renderItem={() => null} isLoading />,
+};
+
+/** No images, no failure — neutral empty state (Axiom 6: empty ≠ error). */
+export const Empty = {
+  render: () => (
+    <ImageGrid<ImageItem>
+      items={[]}
+      columns={3}
+      renderItem={() => null}
+      emptyMessage="No images uploaded"
+      height={400}
+    />
+  ),
+};
+
+/**
+ * Images exist upstream but the active filter matches nothing — no-results ≠
+ * empty (Axiom 6 HONEST STATE). The consumer names the filter in
+ * `emptyMessage`.
+ */
+export const NoResults = {
+  render: () => (
+    <ImageGrid<ImageItem>
+      items={[]}
+      columns={3}
+      renderItem={() => null}
+      emptyMessage='No images match "screenshots"'
+      height={400}
+    />
+  ),
+};
+
+/** Failed load wins over empty — error chrome with retry, never empty chrome (DG-ST-01). */
+export const Error = {
+  render: () => (
+    <ImageGrid<ImageItem>
+      items={[]}
+      columns={3}
+      renderItem={() => null}
+      error="The image list could not be loaded."
+      onRetry={action("onRetry")}
+    />
+  ),
+};

package/src/views/ImageGrid.tsx

@@ -1,9 +1,26 @@
-import { componentColors } from "../componentColors";
-import { useResolvedKnobs } from "@multiplatform.one/theme";
+import { AsyncBoundary, resolveAsyncStatus } from "../layouts/AsyncBoundary";
+import { Skeleton } from "../Skeleton";
+import { Spinner } from "@multiplatform.one/forms";
+import {
+  getLayoutSizeClass,
+  type LayoutSizeClass,
+  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 { Spinner, Text, View, XStack, YStack, type YStackProps } from "tamagui";
+import React, { useCallback, useEffect, useId, useRef, useState } from "react";
+import { useTranslation } from "react-i18next";
+// useWindowDimensions from tamagui, NOT react-native: importing react-native
+// here pulls react-native-web's CJS inline-style-prefixer into the SSR module
+// graph, which the SSR runner evaluates as ESM ("exports is not defined").
+import {
+  View,
+  XStack,
+  YStack,
+  getTokenValue,
+  useWindowDimensions,
+  type YStackProps,
+} from "tamagui";
 
 /**
  * Configurable hotkey bindings for the ImageGrid component.
@@ -37,15 +54,25 @@ export interface ImageGridProps<T> extends Omit<YStackProps, "children"> {
   onLoadMore?: () => void;
   /** Whether more items are available */
   hasMore?: boolean;
-  /** Whether data is loading */
+  /** Whether data is loading — initial load renders a grid-shaped skeleton twin (LC-20 / DG-ST-02) */
   isLoading?: boolean;
-  /** Number of columns in the grid (default: 4) */
+  /**
+   * 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 | React.ReactNode | null;
+  /** Retry handler for the default error UI. */
+  onRetry?: () => void;
+  /** Number of columns in the grid (default: responsive to window width, 2-5) */
   columns?: number;
   /** Estimated height of each row in pixels (default: 240) */
   estimateSize?: number;
   /** Number of rows to render outside visible area (default: 3) */
   overscan?: number;
-  /** Height of the scrollable container in pixels (default: 600) */
+  /**
+   * Fixed height of the grid in pixels. When set, the grid scrolls within
+   * its own container; when omitted, the grid flows with the page scroll.
+   */
   height?: number;
   /** Message shown when items array is empty */
   emptyMessage?: string;
@@ -53,6 +80,38 @@ export interface ImageGridProps<T> extends Omit<YStackProps, "children"> {
   hotkeys?: ImageGridHotkeys;
 }
 
+/**
+ * Skeleton twin of the grid (LC-20 / DG-ST-02): aspect-correct muted blocks
+ * in the live cell geometry — same column count, same half-gutter cell
+ * padding, radius-knob rounding — so the layout doesn't jump when images
+ * land. Replaces the raw centered Spinner the grid used pre-W9.
+ */
+function ImageGridSkeleton({
+  columns,
+  cellPadding,
+  loadingLabel,
+}: {
+  columns: number;
+  cellPadding: number;
+  loadingLabel: string;
+}) {
+  return (
+    <XStack
+      flexWrap="wrap"
+      margin={-cellPadding}
+      data-async-skeleton="image-grid"
+      aria-busy
+      aria-label={loadingLabel}
+    >
+      {Array.from({ length: columns * 2 }).map((_, i) => (
+        <View key={i} width={`${100 / columns}%` as any} padding={cellPadding}>
+          <Skeleton variant="rounded" width="100%" aspectRatio={1} />
+        </View>
+      ))}
+    </XStack>
+  );
+}
+
 /**
  * Generic image grid component with keyboard navigation.
  *
@@ -81,21 +140,49 @@ export function ImageGrid<T>({
   onLoadMore,
   hasMore = false,
   isLoading = false,
-  columns = 4,
+  error = null,
+  onRetry,
+  columns: columnsProp,
   estimateSize: _estimateSize,
   overscan: _overscan,
   height: heightProp,
-  emptyMessage = "No items found",
+  emptyMessage: emptyMessageProp,
   hotkeys: hotkeyOverrides,
   ...stackProps
 }: ImageGridProps<T>) {
+  const { t } = useTranslation();
+  const emptyMessage = emptyMessageProp ?? t("No items found");
   const { knobProps } = useResolvedKnobs();
-  const sz = knobProps.sizeToken;
-  const height = heightProp ?? (sz === "$3" ? 480 : sz === "$5" ? 720 : 600);
+  // Responsive default: a fixed count that looks right on desktop renders
+  // skinny slivers on a phone. Explicit `columns` always wins. Column count
+  // is a structural layout decision, so it consumes the canonical layout
+  // size classes (LC-28 / DG-LAY-01) instead of a raw pixel ladder.
+  const { width: windowWidth } = useWindowDimensions();
+  const columnsBySizeClass: Record<LayoutSizeClass, number> = {
+    compact: 2,
+    medium: 3,
+    expanded: 4,
+    large: 5,
+    xl: 5,
+  };
+  const columns = columnsProp ?? columnsBySizeClass[getLayoutSizeClass(windowWidth)];
+  const height = heightProp;
   const gridId = useId();
   const containerRef = useRef<HTMLDivElement>(null);
+  const sentinelRef = useRef<HTMLDivElement>(null);
   const [focusedIndex, setFocusedIndex] = useState(-1);
 
+  // Flex `gap` on a single-child cell wrapper is a no-op, so gutters come
+  // from half-gutter padding on every cell (works on web and native — no
+  // CSS calc). The negative margin on the wrap container pulls the outer
+  // cells flush with the surrounding content.
+  const gapToken = knobProps.gap.gap;
+  const gutter =
+    typeof gapToken === "number"
+      ? gapToken
+      : ((getTokenValue(gapToken as Parameters<typeof getTokenValue>[0], "space") as number) ?? 16);
+  const cellPadding = gutter / 2;
+
   // Scroll to focused item using DOM scrollIntoView
   const scrollToIndex = useCallback(
     (index: number) => {
@@ -188,49 +275,55 @@ export function ImageGrid<T>({
     hotkeyOpts,
   );
 
-  if (isLoading && items.length === 0) {
-    return (
-      <YStack {...knobProps.panelPadding} alignItems="center" {...stackProps}>
-        <Spinner size="large" />
-      </YStack>
-    );
-  }
+  // Page-flow mode (no explicit height): fire infinite loads when the
+  // bottom sentinel enters the viewport. IntersectionObserver is web-only;
+  // native consumers needing infinite scroll pass an explicit `height` so
+  // the grid owns its own scroll container.
+  useEffect(() => {
+    if (height !== undefined || !onLoadMore || !hasMore || isLoading) return;
+    if (typeof IntersectionObserver === "undefined") return;
+    const el = sentinelRef.current;
+    if (!el) return;
+    const observer = new IntersectionObserver((entries) => {
+      if (entries.some((entry) => entry.isIntersecting)) onLoadMore();
+    });
+    observer.observe(el);
+    return () => observer.disconnect();
+  }, [height, onLoadMore, hasMore, isLoading]);
 
-  if (items.length === 0) {
-    return (
-      <YStack {...knobProps.panelPadding} alignItems="center" {...stackProps}>
-        <Text color={componentColors.text.muted}>{emptyMessage}</Text>
-      </YStack>
-    );
-  }
+  // Error wins over empty (DG-ST-01); initial load renders the grid twin.
+  const hasError = resolveAsyncStatus({ error }) === "error";
 
   // Clamp focused index if items shrunk
   const effectiveFocused = focusedIndex >= items.length ? -1 : focusedIndex;
 
-  return (
-    <YStack {...stackProps}>
+  const gridBody =
+    items.length === 0 ? null : (
       <View
         ref={containerRef as any}
         role="grid"
-        aria-label="Image grid"
+        aria-label={t("Image grid")}
         aria-activedescendant={
           effectiveFocused >= 0 ? `${gridId}-item-${effectiveFocused}` : undefined
         }
         tabIndex={0}
         outlineWidth={0}
-        style={{ height, overflowY: "auto" } as React.CSSProperties}
+        {...(height !== undefined
+          ? {
+              style: { height, overflowY: "auto" } as React.CSSProperties,
+              onScroll:
+                onLoadMore && hasMore && !isLoading
+                  ? () => {
+                      const el = containerRef.current;
+                      if (el && el.scrollTop + el.clientHeight >= el.scrollHeight - 50) {
+                        onLoadMore();
+                      }
+                    }
+                  : undefined,
+            }
+          : null)}
       >
-        <XStack
-          flexWrap="wrap"
-          onScroll={
-            onLoadMore && hasMore && !isLoading
-              ? () => {
-                  const el = containerRef.current;
-                  if (el && el.scrollTop + el.clientHeight >= el.scrollHeight - 50) onLoadMore();
-                }
-              : undefined
-          }
-        >
+        <XStack flexWrap="wrap" margin={-cellPadding}>
           {items.map((item, index) => {
             const isFocused = effectiveFocused === index;
             return (
@@ -239,9 +332,9 @@ export function ImageGrid<T>({
                 id={`${gridId}-item-${index}`}
                 data-focused={isFocused || undefined}
                 width={`${100 / columns}%` as any}
+                padding={cellPadding}
                 backgroundColor={isFocused ? "$accentBackground" : undefined}
                 borderRadius={isFocused ? knobProps.borderRadius.borderRadius : undefined}
-                {...knobProps.gap}
                 cursor={onItemClick ? "pointer" : undefined}
                 onPress={
                   onItemClick
@@ -252,7 +345,17 @@ export function ImageGrid<T>({
                     : undefined
                 }
               >
-                {renderItem(item)}
+                {/* Cards/media are R-SCALE (spec ImageGrid): the owned card
+                    frame rounds with the radius knob and clips the media. */}
+                <View
+                  borderRadius={knobProps.borderRadius.borderRadius}
+                  {...(knobProps.borderRadius.className
+                    ? { className: knobProps.borderRadius.className }
+                    : {})}
+                  overflow="hidden"
+                >
+                  {renderItem(item)}
+                </View>
               </View>
             );
           })}
@@ -262,7 +365,33 @@ export function ImageGrid<T>({
             <Spinner size="small" />
           </YStack>
         )}
+        <View ref={sentinelRef as any} height={1} />
       </View>
-    </YStack>
+    );
+
+  // Exactly one of: error → loading skeleton → empty → grid (W9 / DG-ST-01)
+  return (
+    <AsyncBoundary
+      compact
+      error={error}
+      onRetry={onRetry}
+      errorTitle={t("Couldn't load images")}
+      emptyTitle={emptyMessage}
+      loading={
+        !hasError && isLoading && items.length === 0 ? (
+          <ImageGridSkeleton
+            columns={columns}
+            cellPadding={cellPadding}
+            loadingLabel={t("Loading")}
+          />
+        ) : (
+          false
+        )
+      }
+      empty={!hasError && items.length === 0}
+      {...stackProps}
+    >
+      {gridBody}
+    </AsyncBoundary>
   );
 }