@multiplatform.one/components 6.7.0 → 7.0.0

package/src/views/ImageGrid.stories.tsx

@@ -1,18 +1,58 @@
 import { action } from "@multiplatform.one/storybook";
+import { resolveChartPalette } from "@multiplatform.one/theme";
 import type { Meta } from "@storybook/react-native-web-vite";
-import { Text, View } from "tamagui";
+import { Image, Text, YStack } from "tamagui";
 import { ImageGrid } from "./ImageGrid";
 
 interface ImageItem {
   id: string;
   src: string;
   alt: string;
+  title: string;
+  filename: string;
 }
 
-const items: ImageItem[] = Array.from({ length: 12 }, (_, i) => ({
+const TITLES = [
+  "Harbor morning",
+  "Cedar ridge",
+  "Studio north",
+  "Meadow late",
+  "Night folio",
+  "Grain loft",
+  "Atlas quay",
+  "Copper dune",
+  "Glass marsh",
+  "Ember hall",
+  "North jetty",
+  "Vellum field",
+] as const;
+
+/**
+ * Self-contained plate (no network): a horizon + sun on a categorical solid.
+ * Embedded SVG pixels, not UI chrome — same honesty rule as ImageView sprites.
+ */
+function plateSrc(color: string, seed: number): string {
+  const sunX = 248 + (seed % 5) * 22;
+  const sunY = 58 + (seed % 4) * 16;
+  const sunR = 34 + (seed % 3) * 8;
+  const horizon = 214 + (seed % 5) * 16;
+  return `data:image/svg+xml;utf8,${encodeURIComponent(
+    `<svg xmlns="http://www.w3.org/2000/svg" width="400" height="400" viewBox="0 0 400 400">
+      <rect width="400" height="400" fill="${color}"/>
+      <circle cx="${sunX}" cy="${sunY}" r="${sunR}" fill="white" fill-opacity="0.28"/>
+      <rect y="${horizon}" width="400" height="${400 - horizon}" fill="black" fill-opacity="0.2"/>
+    </svg>`,
+  )}`;
+}
+
+const palette = resolveChartPalette({ scheme: "light" }).categorical;
+
+const items: ImageItem[] = TITLES.map((title, i) => ({
   id: `img-${i + 1}`,
-  src: `https://picsum.photos/seed/${i + 1}/200/200`,
-  alt: `Sample image ${i + 1}`,
+  src: plateSrc(palette[i % palette.length] ?? palette[0], i),
+  alt: title,
+  title,
+  filename: `IMG_${1042 + i * 7}.jpg`,
 }));
 
 const meta: Meta = {
@@ -24,27 +64,51 @@ const meta: Meta = {
 
 export default meta;
 
+function PhotoPlate({ item }: { item: ImageItem }) {
+  // 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").
+  return <Image src={item.src} alt={item.alt} width="100%" aspectRatio={1} objectFit="cover" />;
+}
+
 export const Default = {
   name: "Main",
   render: () => (
     <ImageGrid<ImageItem>
       items={items}
       columns={3}
+      onItemClick={action("onItemClick")}
+      renderItem={(item) => <PhotoPlate item={item} />}
+      height={400}
+    />
+  ),
+};
+
+/**
+ * Polar MediaCard anatomy: square media, title + muted filename under the
+ * plate. The grid rings the whole card (image + caption), not the photo
+ * alone — the perceived control is the card.
+ */
+export const WithCaptions = {
+  render: () => (
+    <ImageGrid<ImageItem>
+      items={items.slice(0, 6)}
+      columns={3}
+      onItemClick={action("onItemClick")}
       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"
-          alignItems="center"
-          justifyContent="center"
-        >
-          <Text fontSize="$2">{item.alt}</Text>
-        </View>
+        <YStack>
+          <PhotoPlate item={item} />
+          <YStack padding="$2" gap="$1">
+            <Text fontSize="$3" color="$color12" numberOfLines={1}>
+              {item.title}
+            </Text>
+            <Text fontSize="$2" color="$color11" numberOfLines={1}>
+              {item.filename}
+            </Text>
+          </YStack>
+        </YStack>
       )}
-      height={400}
+      height={480}
     />
   ),
 };

package/src/views/ImageGrid.tsx

@@ -1,15 +1,19 @@
 import { AsyncBoundary, resolveAsyncStatus } from "../layouts/AsyncBoundary";
 import { Skeleton } from "../Skeleton";
+import { useDirection } from "../hooks/useDirection";
 import { Spinner } from "@multiplatform.one/forms";
 import {
   getLayoutSizeClass,
+  keyboardFocusRingProps,
   type LayoutSizeClass,
+  ensureKeyboardModalityTracking,
   useResolvedKnobs,
+  wasKeyboardFocus,
 } from "@multiplatform.one/theme";
 import { useHotkey } from "@tanstack/react-hotkeys";
 import type { RegisterableHotkey } from "@tanstack/react-hotkeys";
 import React, { useCallback, useEffect, useId, useRef, useState } from "react";
-import { useTranslation } from "react-i18next";
+import { useTranslation } from "../shared/i18n";
 // 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").
@@ -36,6 +40,10 @@ export interface ImageGridHotkeys {
   right?: RegisterableHotkey;
   /** Select the focused item (default: Enter) */
   select?: RegisterableHotkey;
+  /** Move focus to the first item (default: Home) */
+  first?: RegisterableHotkey;
+  /** Move focus to the last item (default: End) */
+  last?: RegisterableHotkey;
 }
 
 /**
@@ -112,6 +120,84 @@ function ImageGridSkeleton({
   );
 }
 
+/**
+ * One Photos/Polar tile: the rounded media frame is the perceived control.
+ * LC-71 ring rides this node (inset — overflow clips children to radius),
+ * never the padded cell and never the grid. Hover veil is pointer-only;
+ * keyboard focus is ring-only (no fill wash over the image).
+ */
+function ImageGridTile({
+  id,
+  isFocused,
+  showRing,
+  clickable,
+  cellPadding,
+  columns,
+  colIndex,
+  rowIndex,
+  radius,
+  radiusClassName,
+  onPress,
+  children,
+}: {
+  id: string;
+  isFocused: boolean;
+  showRing: boolean;
+  clickable: boolean;
+  cellPadding: number;
+  columns: number;
+  colIndex: number;
+  rowIndex: number;
+  radius: string | number;
+  radiusClassName?: string;
+  onPress?: () => void;
+  children: React.ReactNode;
+}) {
+  const [hovered, setHovered] = useState(false);
+  return (
+    <View width={`${100 / columns}%` as any} padding={cellPadding} role="presentation">
+      <View
+        id={id}
+        // "gridcell" is a valid ARIA role but outside RN's `Role` union;
+        // forwarded to the DOM node on web (house Record cast).
+        {...({ role: "gridcell" } as Record<string, unknown>)}
+        aria-colindex={colIndex}
+        aria-rowindex={rowIndex}
+        aria-selected={isFocused}
+        data-focused={isFocused || undefined}
+        position="relative"
+        borderRadius={radius}
+        {...(radiusClassName ? { className: radiusClassName } : {})}
+        cursor={clickable ? "pointer" : undefined}
+        {...(showRing ? keyboardFocusRingProps : { outlineWidth: 0 })}
+        // Tamagui forwards onHoverIn/onHoverOut at runtime; the RN-flavored
+        // View prop type omits them (house Record cast).
+        {...({
+          onHoverIn: () => setHovered(true),
+          onHoverOut: () => setHovered(false),
+        } as Record<string, unknown>)}
+        onPress={onPress}
+      >
+        {/* Clip media to the radius; keep overflow off the ring node so
+            LC-71 outline is not severed (same split as Input.Box). */}
+        <View borderRadius={radius} overflow="hidden">
+          {children}
+        </View>
+        {hovered && !showRing ? (
+          <View
+            position="absolute"
+            inset={0}
+            pointerEvents="none"
+            backgroundColor="$color12"
+            opacity={0.08}
+            borderRadius={radius}
+          />
+        ) : null}
+      </View>
+    </View>
+  );
+}
+
 /**
  * Generic image grid component with keyboard navigation.
  *
@@ -153,6 +239,7 @@ export function ImageGrid<T>({
   const { t } = useTranslation();
   const emptyMessage = emptyMessageProp ?? t("No items found");
   const { knobProps } = useResolvedKnobs();
+  const isRTL = useDirection() === "rtl";
   // 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
@@ -171,6 +258,11 @@ export function ImageGrid<T>({
   const containerRef = useRef<HTMLDivElement>(null);
   const sentinelRef = useRef<HTMLDivElement>(null);
   const [focusedIndex, setFocusedIndex] = useState(-1);
+  if (typeof document !== "undefined") ensureKeyboardModalityTracking();
+  const handleContainerFocus = useCallback(() => {
+    if (!wasKeyboardFocus()) return;
+    setFocusedIndex((prev) => (prev < 0 ? 0 : prev));
+  }, []);
 
   // 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
@@ -193,84 +285,61 @@ export function ImageGrid<T>({
     [gridId, items.length],
   );
 
-  // Keyboard navigation via @tanstack/react-hotkeys
-  const hotkeyOpts = {
-    target: containerRef as React.RefObject<HTMLElement | null>,
-  };
-
-  useHotkey(
-    hotkeyOverrides?.right ?? "ArrowRight",
-    () => {
+  const moveFocus = useCallback(
+    (delta: number) => {
       setFocusedIndex((prev) => {
-        if (prev < 0) return 0;
-        const col = prev % columns;
-        // Don't wrap to next row, stop at end of row or end of items
-        if (col < columns - 1 && prev + 1 < items.length) {
-          const next = prev + 1;
-          scrollToIndex(next);
-          return next;
+        if (items.length === 0) return prev;
+        if (prev < 0) {
+          scrollToIndex(0);
+          return 0;
         }
-        return prev;
+        const next = Math.max(0, Math.min(items.length - 1, prev + delta));
+        scrollToIndex(next);
+        return next;
       });
     },
-    hotkeyOpts,
+    [items.length, scrollToIndex],
   );
 
-  useHotkey(
-    hotkeyOverrides?.left ?? "ArrowLeft",
-    () => {
-      setFocusedIndex((prev) => {
-        if (prev < 0) return 0;
-        const col = prev % columns;
-        if (col > 0) {
-          const next = prev - 1;
-          scrollToIndex(next);
-          return next;
-        }
-        return prev;
-      });
-    },
-    hotkeyOpts,
-  );
+  // Keyboard navigation via @tanstack/react-hotkeys.
+  // Photos: Left/Right walk reading order (wrap to the next row); Up/Down
+  // jump a row. Physical arrows flip on RTL so visual direction holds.
+  const hotkeyOpts = {
+    target: containerRef as React.RefObject<HTMLElement | null>,
+  };
 
-  useHotkey(
-    hotkeyOverrides?.down ?? "ArrowDown",
-    () => {
-      setFocusedIndex((prev) => {
-        if (prev < 0) return 0;
-        const next = prev + columns;
-        if (next < items.length) {
-          scrollToIndex(next);
-          return next;
-        }
-        return prev;
-      });
-    },
-    hotkeyOpts,
-  );
+  useHotkey(hotkeyOverrides?.right ?? "ArrowRight", () => moveFocus(isRTL ? -1 : 1), hotkeyOpts);
+  useHotkey(hotkeyOverrides?.left ?? "ArrowLeft", () => moveFocus(isRTL ? 1 : -1), hotkeyOpts);
+  useHotkey(hotkeyOverrides?.down ?? "ArrowDown", () => moveFocus(columns), hotkeyOpts);
+  useHotkey(hotkeyOverrides?.up ?? "ArrowUp", () => moveFocus(-columns), hotkeyOpts);
+
+  const activateFocused = useCallback(() => {
+    if (focusedIndex >= 0 && focusedIndex < items.length) {
+      onItemClick?.(items[focusedIndex]);
+    }
+  }, [focusedIndex, items, onItemClick]);
+
+  useHotkey(hotkeyOverrides?.select ?? "Enter", activateFocused, hotkeyOpts);
+  // Photos opens the focused thumbnail with Space as well as Return.
+  useHotkey("Space", activateFocused, hotkeyOpts);
 
   useHotkey(
-    hotkeyOverrides?.up ?? "ArrowUp",
+    hotkeyOverrides?.first ?? "Home",
     () => {
-      setFocusedIndex((prev) => {
-        if (prev < 0) return 0;
-        const next = prev - columns;
-        if (next >= 0) {
-          scrollToIndex(next);
-          return next;
-        }
-        return prev;
-      });
+      if (items.length === 0) return;
+      setFocusedIndex(0);
+      scrollToIndex(0);
     },
     hotkeyOpts,
   );
 
   useHotkey(
-    hotkeyOverrides?.select ?? "Enter",
+    hotkeyOverrides?.last ?? "End",
     () => {
-      if (focusedIndex >= 0 && focusedIndex < items.length) {
-        onItemClick?.(items[focusedIndex]);
-      }
+      if (items.length === 0) return;
+      const last = items.length - 1;
+      setFocusedIndex(last);
+      scrollToIndex(last);
     },
     hotkeyOpts,
   );
@@ -296,6 +365,10 @@ export function ImageGrid<T>({
 
   // Clamp focused index if items shrunk
   const effectiveFocused = focusedIndex >= items.length ? -1 : focusedIndex;
+  const showKeyboardRing = effectiveFocused >= 0 && wasKeyboardFocus();
+  const rowCount = Math.ceil(items.length / columns);
+  const radius = knobProps.borderRadius.borderRadius;
+  const radiusClassName = knobProps.borderRadius.className;
 
   const gridBody =
     items.length === 0 ? null : (
@@ -303,11 +376,16 @@ export function ImageGrid<T>({
         ref={containerRef as any}
         role="grid"
         aria-label={t("Image grid")}
+        aria-colcount={columns}
+        aria-rowcount={rowCount}
         aria-activedescendant={
           effectiveFocused >= 0 ? `${gridId}-item-${effectiveFocused}` : undefined
         }
         tabIndex={0}
         outlineWidth={0}
+        focusStyle={{ outlineWidth: 0 }}
+        focusVisibleStyle={{ outlineWidth: 0 }}
+        onFocus={handleContainerFocus}
         {...(height !== undefined
           ? {
               style: { height, overflowY: "auto" } as React.CSSProperties,
@@ -323,43 +401,45 @@ export function ImageGrid<T>({
             }
           : null)}
       >
-        <XStack flexWrap="wrap" margin={-cellPadding}>
-          {items.map((item, index) => {
-            const isFocused = effectiveFocused === index;
+        <YStack margin={-cellPadding}>
+          {Array.from({ length: rowCount }, (_, row) => {
+            const start = row * columns;
+            const rowItems = items.slice(start, start + columns);
             return (
-              <View
-                key={`${gridId}-item-${index}`}
-                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}
-                cursor={onItemClick ? "pointer" : undefined}
-                onPress={
-                  onItemClick
-                    ? () => {
-                        setFocusedIndex(index);
-                        onItemClick(item);
+              <XStack key={`${gridId}-row-${row}`} role="row">
+                {rowItems.map((item, col) => {
+                  const index = start + col;
+                  const isFocused = effectiveFocused === index;
+                  return (
+                    <ImageGridTile
+                      key={`${gridId}-item-${index}`}
+                      id={`${gridId}-item-${index}`}
+                      isFocused={isFocused}
+                      showRing={isFocused && showKeyboardRing}
+                      clickable={Boolean(onItemClick)}
+                      cellPadding={cellPadding}
+                      columns={columns}
+                      colIndex={col + 1}
+                      rowIndex={row + 1}
+                      radius={radius}
+                      radiusClassName={radiusClassName}
+                      onPress={
+                        onItemClick
+                          ? () => {
+                              setFocusedIndex(index);
+                              onItemClick(item);
+                            }
+                          : undefined
                       }
-                    : undefined
-                }
-              >
-                {/* 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>
+                    >
+                      {renderItem(item)}
+                    </ImageGridTile>
+                  );
+                })}
+              </XStack>
             );
           })}
-        </XStack>
+        </YStack>
         {isLoading && items.length > 0 && (
           <YStack padding="$2" alignItems="center">
             <Spinner size="small" />