@multiplatform.one/components 6.6.0 → 7.0.0

package/src/views/List.tsx

@@ -2,12 +2,30 @@ 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 {
+  MIN_PRESS_TARGET,
+  ensureKeyboardModalityTracking,
+  getGroupPosition,
+  hairline,
+  keyboardFocusRingProps,
+  stackRadiusProps,
+  useReadableTextOn,
+  useResolvedKnobs,
+  wasKeyboardFocus,
+} from "@multiplatform.one/theme";
 import { useHotkey } from "@tanstack/react-hotkeys";
 import type { RegisterableHotkey } from "@tanstack/react-hotkeys";
-import React, { useCallback, useId, useRef, useState, type ReactNode } from "react";
-import { useTranslation } from "react-i18next";
-import { ListItem, View, YStack, type YStackProps } from "tamagui";
+import React, {
+  createContext,
+  useCallback,
+  useContext,
+  useId,
+  useRef,
+  useState,
+  type ReactNode,
+} from "react";
+import { useTranslation } from "../shared/i18n";
+import { Text, View, XStack, YStack, type YStackProps } from "tamagui";
 
 /**
  * Configurable hotkey bindings for the List component.
@@ -29,6 +47,148 @@ export interface ListHotkeys {
   pageUp?: RegisterableHotkey;
 }
 
+/** Per-row interaction state passed to `renderItem` and `ListRow`. */
+export interface ListItemState {
+  selected: boolean;
+  focused: boolean;
+  /** Readable ink when the row paints `$accentBackground` (LC-71 fill). */
+  onAccent?: string;
+}
+
+const ListItemStateContext = createContext<ListItemState>({
+  selected: false,
+  focused: false,
+});
+
+/** Read the current row's selection/focus. Defaults to idle outside a List. */
+export function useListItemState(): ListItemState {
+  return useContext(ListItemStateContext);
+}
+
+/**
+ * Subject-led document row (Desk list / Linear / Finder): leading glyph,
+ * title (+ optional subtitle), trailing muted meta. Sits inside List's
+ * stacked-group chrome — does not paint its own radius, fill, or ring.
+ */
+export interface ListRowProps {
+  /** Leading media slot — fixed box so titles share one x (LC-08). */
+  icon?: ReactNode;
+  title: ReactNode;
+  subtitle?: ReactNode;
+  /** Trailing Finder/Desk columns (dates, size, kind, status). */
+  meta?: ReactNode;
+}
+
+function RowText({
+  children,
+  ...props
+}: { children: ReactNode } & React.ComponentProps<typeof Text>) {
+  if (children == null || children === false) return null;
+  if (typeof children === "string" || typeof children === "number") {
+    return <Text {...props}>{children}</Text>;
+  }
+  return <>{children}</>;
+}
+
+/** Trailing Finder/Desk column. Inherits selected fill ink (LC-71). */
+export function ListRowMeta({
+  children,
+  width,
+  color,
+}: {
+  children: ReactNode;
+  width?: number;
+  color?: string;
+}) {
+  const { knobProps } = useResolvedKnobs();
+  const { selected, onAccent } = useListItemState();
+  const resolved = selected && onAccent ? onAccent : (color ?? componentColors.text.muted);
+  return (
+    <Text
+      {...knobProps.body}
+      fontSize="$2"
+      lineHeight="$2"
+      color={resolved}
+      numberOfLines={1}
+      minWidth={width}
+      textAlign="right"
+      userSelect="none"
+    >
+      {children}
+    </Text>
+  );
+}
+
+export function ListRow({ icon, title, subtitle, meta }: ListRowProps) {
+  const { knobProps } = useResolvedKnobs();
+  const { selected, onAccent } = useListItemState();
+  const ink = selected && onAccent ? onAccent : componentColors.text.primary;
+  const muted = selected && onAccent ? onAccent : componentColors.text.muted;
+  const iconSize = knobProps.sizeToken === "$3" ? 16 : knobProps.sizeToken === "$5" ? 22 : 18;
+  const leading = React.isValidElement(icon)
+    ? React.cloneElement(icon as React.ReactElement<{ size?: number; color?: string }>, {
+        size: iconSize,
+        color: "currentColor",
+      })
+    : icon;
+
+  return (
+    <XStack alignItems="center" gap="$3" flex={1} minWidth={0} width="100%">
+      {leading ? (
+        <View
+          width={iconSize}
+          height={iconSize}
+          flexShrink={0}
+          alignItems="center"
+          justifyContent="center"
+          color={muted}
+          {...({ "data-list-slot": "icon" } as any)}
+        >
+          {leading}
+        </View>
+      ) : null}
+      <YStack flex={1} minWidth={0} gap="$1" {...({ "data-list-slot": "title" } as any)}>
+        <RowText
+          {...knobProps.body}
+          color={ink}
+          fontWeight="500"
+          numberOfLines={1}
+          userSelect="none"
+        >
+          {title}
+        </RowText>
+        {subtitle != null && subtitle !== false ? (
+          <RowText
+            {...knobProps.body}
+            fontSize="$2"
+            lineHeight="$2"
+            color={muted}
+            opacity={selected ? 0.85 : 1}
+            numberOfLines={1}
+            userSelect="none"
+          >
+            {subtitle}
+          </RowText>
+        ) : null}
+      </YStack>
+      {meta != null && meta !== false ? (
+        <XStack
+          alignItems="center"
+          gap="$4"
+          flexShrink={0}
+          {...({ "data-list-slot": "meta" } as any)}
+        >
+          {typeof meta === "string" || typeof meta === "number" ? (
+            <ListRowMeta>{meta}</ListRowMeta>
+          ) : (
+            meta
+          )}
+        </XStack>
+      ) : null}
+    </XStack>
+  );
+}
+
 /**
  * Props for the generic List component.
  *
@@ -38,7 +198,7 @@ export interface ListProps<T> extends Omit<YStackProps, "children"> {
   /** Array of items to render */
   items: T[];
   /** Render function for each item */
-  renderItem: (item: T, index: number) => React.ReactNode;
+  renderItem: (item: T, index: number, state?: ListItemState) => React.ReactNode;
   /** Called when an item is clicked */
   onItemClick?: (item: T) => void;
   /** Called when user scrolls near the bottom (infinite scroll) */
@@ -62,6 +222,15 @@ export interface ListProps<T> extends Omit<YStackProps, "children"> {
   emptyMessage?: string;
   /** Height of the scrollable container in pixels (default: 400) */
   height?: number;
+  /**
+   * Filled row (LC-71). Finder/Linear list: arrows move this with keyboard
+   * focus. Controlled when passed; otherwise internal.
+   */
+  selectedIndex?: number;
+  /** Uncontrolled initial filled row. */
+  defaultSelectedIndex?: number;
+  /** Fires when the filled row changes (click or arrow keys). */
+  onSelectionChange?: (index: number, item: T) => void;
   /** Accessible label for the list */
   "aria-label"?: string;
   /** Configurable keyboard shortcut overrides */
@@ -72,9 +241,10 @@ export interface ListProps<T> extends Omit<YStackProps, "children"> {
  * Generic virtualized list component with keyboard navigation.
  *
  * Uses `@shopify/flash-list` for cross-platform virtualization and
- * `@tanstack/react-hotkeys` for keyboard navigation. Each row is rendered
- * as a Tamagui `ListItem` with native hover/press animations. Accepts data
- * purely through props — no data fetching logic included.
+ * `@tanstack/react-hotkeys` for keyboard navigation. Rows form one stacked
+ * group (LC-72): outer corners follow the radius knob, interiors stay square,
+ * hairlines sit only BETWEEN rows. Selected = accent fill; keyboard focus =
+ * inset ring on that same row (LC-71). Accepts data purely through props.
  *
  * @typeParam T - The item type rendered in the list
  *
@@ -82,7 +252,7 @@ export interface ListProps<T> extends Omit<YStackProps, "children"> {
  * ```tsx
  * <List
  *   items={items}
- *   renderItem={(item) => <Text>{item.name}</Text>}
+ *   renderItem={(item) => <ListRow title={item.name} meta={item.modified} />}
  *   onItemClick={(item) => console.log(item)}
  *   estimateSize={56}
  * />
@@ -101,6 +271,9 @@ export function List<T>({
   overscan = 5,
   emptyMessage: emptyMessageProp,
   height: heightProp,
+  selectedIndex: selectedIndexProp,
+  defaultSelectedIndex,
+  onSelectionChange,
   "aria-label": ariaLabel,
   hotkeys: hotkeyOverrides,
   ...stackProps
@@ -109,7 +282,10 @@ export function List<T>({
   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 estimateSize = estimateSizeProp ?? (sz === "$3" ? 48 : sz === "$5" ? 68 : 56);
+  const rowPad = knobProps.panelPadding.padding;
+  const onAccent = useReadableTextOn("$accentBackground");
+  const cornersRadius = knobProps.borderRadius.borderRadius;
   // 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
@@ -130,7 +306,32 @@ export function List<T>({
   const listId = useId();
   const containerRef = useRef<HTMLDivElement>(null);
   const flashListRef = useRef<FlashListRef<T>>(null);
-  const [focusedIndex, setFocusedIndex] = useState(-1);
+  const isControlled = selectedIndexProp !== undefined;
+  const [uncontrolledSelected, setUncontrolledSelected] = useState(defaultSelectedIndex ?? -1);
+  const selectedIndex = isControlled ? selectedIndexProp : uncontrolledSelected;
+  const selectedRef = useRef(selectedIndex);
+  selectedRef.current = selectedIndex;
+  const [containerKeyboardFocused, setContainerKeyboardFocused] = useState(false);
+  if (typeof document !== "undefined") ensureKeyboardModalityTracking();
+
+  const commitSelection = useCallback(
+    (index: number) => {
+      if (index < 0 || index >= items.length) return;
+      if (!isControlled) setUncontrolledSelected(index);
+      onSelectionChange?.(index, items[index]);
+    },
+    [isControlled, items, onSelectionChange],
+  );
+
+  const handleContainerFocus = useCallback(() => {
+    if (!wasKeyboardFocus()) return;
+    setContainerKeyboardFocused(true);
+    if (selectedRef.current < 0 && items.length > 0) commitSelection(0);
+  }, [commitSelection, items.length]);
+
+  const handleContainerBlur = useCallback(() => {
+    setContainerKeyboardFocused(false);
+  }, []);
 
   // Scroll to focused item when focusedIndex changes
   const scrollToIndex = useCallback(
@@ -142,6 +343,16 @@ export function List<T>({
     [items.length],
   );
 
+  const moveSelection = useCallback(
+    (next: number) => {
+      const clamped = Math.max(0, Math.min(next, items.length - 1));
+      commitSelection(clamped);
+      scrollToIndex(clamped);
+      return clamped;
+    },
+    [commitSelection, items.length, scrollToIndex],
+  );
+
   // Keyboard navigation via @tanstack/react-hotkeys
   const hotkeyOpts = {
     target: containerRef as React.RefObject<HTMLElement | null>,
@@ -150,11 +361,8 @@ export function List<T>({
   useHotkey(
     hotkeyOverrides?.next ?? "ArrowDown",
     () => {
-      setFocusedIndex((prev) => {
-        const next = prev < 0 ? 0 : Math.min(prev + 1, items.length - 1);
-        scrollToIndex(next);
-        return next;
-      });
+      const current = selectedRef.current;
+      moveSelection(current < 0 ? 0 : current + 1);
     },
     hotkeyOpts,
   );
@@ -162,11 +370,8 @@ export function List<T>({
   useHotkey(
     hotkeyOverrides?.prev ?? "ArrowUp",
     () => {
-      setFocusedIndex((prev) => {
-        const next = prev < 0 ? items.length - 1 : Math.max(prev - 1, 0);
-        scrollToIndex(next);
-        return next;
-      });
+      const current = selectedRef.current;
+      moveSelection(current < 0 ? items.length - 1 : current - 1);
     },
     hotkeyOpts,
   );
@@ -174,8 +379,9 @@ export function List<T>({
   useHotkey(
     hotkeyOverrides?.select ?? "Enter",
     () => {
-      if (focusedIndex >= 0 && focusedIndex < items.length) {
-        onItemClick?.(items[focusedIndex]);
+      const current = selectedRef.current;
+      if (current >= 0 && current < items.length) {
+        onItemClick?.(items[current]);
       }
     },
     hotkeyOpts,
@@ -184,10 +390,7 @@ export function List<T>({
   useHotkey(
     hotkeyOverrides?.first ?? "Home",
     () => {
-      if (items.length > 0) {
-        setFocusedIndex(0);
-        scrollToIndex(0);
-      }
+      if (items.length > 0) moveSelection(0);
     },
     hotkeyOpts,
   );
@@ -195,11 +398,7 @@ export function List<T>({
   useHotkey(
     hotkeyOverrides?.last ?? "End",
     () => {
-      if (items.length > 0) {
-        const lastIndex = items.length - 1;
-        setFocusedIndex(lastIndex);
-        scrollToIndex(lastIndex);
-      }
+      if (items.length > 0) moveSelection(items.length - 1);
     },
     hotkeyOpts,
   );
@@ -207,11 +406,8 @@ export function List<T>({
   useHotkey(
     hotkeyOverrides?.pageDown ?? "PageDown",
     () => {
-      setFocusedIndex((prev) => {
-        const next = Math.min((prev < 0 ? 0 : prev) + 10, items.length - 1);
-        scrollToIndex(next);
-        return next;
-      });
+      const current = selectedRef.current < 0 ? 0 : selectedRef.current;
+      moveSelection(current + 10);
     },
     hotkeyOpts,
   );
@@ -219,11 +415,8 @@ export function List<T>({
   useHotkey(
     hotkeyOverrides?.pageUp ?? "PageUp",
     () => {
-      setFocusedIndex((prev) => {
-        const next = Math.max((prev < 0 ? 0 : prev) - 10, 0);
-        scrollToIndex(next);
-        return next;
-      });
+      const current = selectedRef.current < 0 ? 0 : selectedRef.current;
+      moveSelection(current - 10);
     },
     hotkeyOpts,
   );
@@ -235,80 +428,113 @@ export function List<T>({
     }
   }, [onLoadMore, hasMore, isLoading]);
 
-  // Clamp focused index if items shrunk
-  const effectiveFocused = focusedIndex >= items.length ? -1 : focusedIndex;
+  // Clamp selected index if items shrunk
+  const effectiveSelected = selectedIndex >= items.length ? -1 : selectedIndex;
+  const showKeyboardRing = containerKeyboardFocused && wasKeyboardFocus();
 
   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,
+      <View
+        ref={containerRef as any}
+        role="list"
+        aria-label={ariaLabel}
+        aria-activedescendant={
+          effectiveSelected >= 0 ? `${listId}-item-${effectiveSelected}` : undefined
+        }
+        tabIndex={0}
+        outlineWidth={0}
+        onFocus={handleContainerFocus}
+        onBlur={handleContainerBlur}
+        style={{
+          height,
+        }}
+      >
+        <FlashList
+          ref={flashListRef}
+          data={items}
+          extraData={{ selected: effectiveSelected, ring: showKeyboardRing }}
+          drawDistance={overscan * estimateSize}
+          onEndReached={handleEndReached}
+          onEndReachedThreshold={0.5}
+          onContentSizeChange={(_w, contentHeight) => {
+            if (contentHeight > 0) {
+              setMeasuredContentHeight((prev) => (prev === contentHeight ? prev : contentHeight));
+            }
           }}
-        >
-          <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
+          keyExtractor={(_, index) => `${listId}-item-${index}`}
+          renderItem={({ item, index }) => {
+            const isSelected = effectiveSelected === index;
+            const position = getGroupPosition(index, items.length);
+            const corners = stackRadiusProps(position, cornersRadius);
+            const state: ListItemState = {
+              selected: isSelected,
+              focused: isSelected && showKeyboardRing,
+              onAccent,
+            };
+            return (
+              <YStack>
+                {index > 0 ? <View {...hairline.line} /> : null}
+                <XStack
                   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}
+                  {...({
+                    "data-list-row": true,
+                    ...(isSelected ? { "data-selected": true } : {}),
+                  } as any)}
+                  minHeight={MIN_PRESS_TARGET}
+                  paddingHorizontal={rowPad}
+                  paddingVertical="$2"
+                  alignItems="center"
+                  overflow="hidden"
+                  // Rows form ONE stacked group: the hover/focus/selection
+                  // surface rounds with the radius knob only at the group's
+                  // outer corners; interiors stay square (LC-72). Hairlines
+                  // sit BETWEEN rows only — never after the last.
+                  {...corners}
                   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
-                  }
+                  aria-selected={isSelected}
+                  backgroundColor={isSelected ? "$accentBackground" : "transparent"}
+                  {...(isSelected && onAccent ? { color: onAccent } : {})}
+                  {...(isSelected && showKeyboardRing
+                    ? {
+                        ...keyboardFocusRingProps,
+                        ...(onAccent ? { outlineColor: onAccent } : {}),
+                      }
+                    : { outlineWidth: 0 })}
+                  hoverStyle={{
+                    backgroundColor: isSelected
+                      ? "$accentBackground"
+                      : componentColors.interactive.background,
+                    ...corners,
+                  }}
+                  pressStyle={{
+                    backgroundColor: isSelected
+                      ? "$accentBackground"
+                      : componentColors.interactive.hover,
+                    ...corners,
+                  }}
+                  cursor="pointer"
+                  {...(knobProps.transition ? { transition: knobProps.transition } : {})}
+                  onPress={() => {
+                    commitSelection(index);
+                    onItemClick?.(item);
+                  }}
                 >
-                  {renderItem(item, index)}
-                </ListItem>
-              );
-            }}
-            ListFooterComponent={
-              isLoading && items.length > 0 ? (
-                <YStack padding="$2" alignItems="center">
-                  <Spinner size="small" />
-                </YStack>
-              ) : null
-            }
-          />
-        </View>
-      </YStack>
+                  <ListItemStateContext.Provider value={state}>
+                    {renderItem(item, index, state)}
+                  </ListItemStateContext.Provider>
+                </XStack>
+              </YStack>
+            );
+          }}
+          ListFooterComponent={
+            isLoading && items.length > 0 ? (
+              <YStack padding="$2" alignItems="center">
+                <Spinner size="small" />
+              </YStack>
+            ) : null
+          }
+        />
+      </View>
     );
 
   return (

package/src/views/ReportBuilder.stories.tsx

@@ -28,7 +28,34 @@ export default meta;
 export const Default = {
   name: "Main",
   render: () => (
-    <ReportBuilder columns={columns} data={data} height={420} onExport={action("onExport")} />
+    <ReportBuilder
+      columns={columns}
+      data={data}
+      height={420}
+      onExport={action("onExport")}
+      onColumnsChange={action("onColumnsChange")}
+      onGroupByChange={action("onGroupByChange")}
+      onRowPress={action("onRowPress")}
+    />
+  ),
+};
+
+/**
+ * Frappe Report View grouping: collapse/expand sections, aggregation, chart.
+ */
+export const Grouped = {
+  render: () => (
+    <ReportBuilder
+      columns={columns}
+      data={data}
+      height={520}
+      groupBy={{ field: "status", aggregation: "sum", aggregationField: "amount" }}
+      showChart
+      onExport={action("onExport")}
+      onColumnsChange={action("onColumnsChange")}
+      onGroupByChange={action("onGroupByChange")}
+      onRowPress={action("onRowPress")}
+    />
   ),
 };