@multiplatform.one/components 7.4.0 → 7.5.0

package/src/SortableList/useSortableRows.ts

@@ -0,0 +1,433 @@
+import {
+  createContext,
+  createElement,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  type ReactNode,
+  type RefObject,
+} from "react";
+import {
+  AUTO_SCROLL_EDGE_PX,
+  AUTO_SCROLL_MAX_SPEED,
+  LIST_COLUMN_ID,
+  TOUCH_LONG_PRESS_MS,
+  applyReorder,
+  autoScrollVelocity,
+  describeCancel,
+  describeDragState,
+  formatListAnnouncement,
+  insertionIndexForY,
+  keyboardLift,
+  keyboardMove,
+  listBoardSnapshot,
+  resolveDrop,
+  siblingOffset,
+  type KanbanKeyboardDrag,
+} from "../views/kanbanDnd";
+
+export type SortableMode = "keyboard" | "pointer";
+
+export interface SortableSession {
+  mode: SortableMode;
+  sourceIndex: number;
+  targetIndex: number;
+  id: string;
+  label: string;
+  size: number;
+}
+
+export interface UseSortableRowsOptions<T> {
+  items: T[];
+  getId: (item: T, index: number) => string;
+  getLabel: (item: T, index: number) => string;
+  canReorder?: (item: T, index: number) => boolean;
+  onChange?: (next: T[]) => void;
+  enabled: boolean;
+  containerRef: RefObject<HTMLElement | null>;
+  rowSelector?: string;
+}
+
+const DEFAULT_ROW_SELECTOR = "[data-sortable-row], [data-child-row]";
+
+const SortableSessionContext = createContext<{ sourceId: string | null }>({
+  sourceId: null,
+});
+
+/** Lets a remount-prone cell (ChildTable handle) read lift state without recreating column defs. */
+export function SortableSessionProvider({
+  sourceId,
+  children,
+}: {
+  sourceId: string | null;
+  children: ReactNode;
+}) {
+  return createElement(SortableSessionContext.Provider, { value: { sourceId } }, children);
+}
+
+export function useSortableDragging(itemId: string, dragging?: boolean) {
+  const { sourceId } = useContext(SortableSessionContext);
+  return dragging ?? sourceId === itemId;
+}
+
+export function useSortableRows<T>({
+  items,
+  getId,
+  getLabel,
+  canReorder,
+  onChange,
+  enabled,
+  containerRef,
+  rowSelector = DEFAULT_ROW_SELECTOR,
+}: UseSortableRowsOptions<T>) {
+  const [session, setSession] = useState<SortableSession | null>(null);
+  const [announcement, setAnnouncement] = useState("");
+  const [focusedIndex, setFocusedIndex] = useState(0);
+  const sessionRef = useRef<SortableSession | null>(null);
+  sessionRef.current = session;
+  const itemsRef = useRef(items);
+  itemsRef.current = items;
+
+  const board = useMemo(() => listBoardSnapshot(items.length), [items.length]);
+
+  const ids = useMemo(() => items.map((item, i) => getId(item, i)), [items, getId]);
+  const labels = useMemo(() => items.map((item, i) => getLabel(item, i)), [items, getLabel]);
+
+  const rowEnabled = useCallback(
+    (index: number) => {
+      if (!enabled) return false;
+      if (index < 0 || index >= items.length) return false;
+      return canReorder ? canReorder(items[index], index) : true;
+    },
+    [canReorder, enabled, items],
+  );
+
+  const announce = useCallback(
+    (type: "lift" | "move" | "drop" | "cancel", drag: KanbanKeyboardDrag, label: string) => {
+      if (type === "cancel") {
+        setAnnouncement(
+          formatListAnnouncement(describeCancel(drag, board, label), {
+            sourcePosition: drag.sourceIndex + 1,
+          }),
+        );
+        return;
+      }
+      setAnnouncement(formatListAnnouncement(describeDragState(type, drag, board, label)));
+    },
+    [board],
+  );
+
+  const toDrag = useCallback(
+    (s: SortableSession): KanbanKeyboardDrag => ({
+      sourceColumnId: LIST_COLUMN_ID,
+      sourceIndex: s.sourceIndex,
+      target: { columnId: LIST_COLUMN_ID, index: s.targetIndex },
+    }),
+    [],
+  );
+
+  const focusRow = useCallback(
+    (id: string) => {
+      const root = containerRef.current;
+      if (!root) return;
+      const el = root.querySelector(`[data-sortable-row="${id}"], [data-child-row-id="${id}"]`);
+      (el as HTMLElement | null)?.focus?.();
+    },
+    [containerRef],
+  );
+
+  const liftAt = useCallback(
+    (index: number, mode: SortableMode) => {
+      if (!rowEnabled(index)) return false;
+      const kb = keyboardLift(board, LIST_COLUMN_ID, index);
+      if (!kb) return false;
+      const next: SortableSession = {
+        mode,
+        sourceIndex: index,
+        targetIndex: kb.target.index,
+        id: ids[index],
+        label: labels[index],
+        size: 44,
+      };
+      setSession(next);
+      sessionRef.current = next;
+      announce("lift", kb, next.label);
+      return true;
+    },
+    [announce, board, ids, labels, rowEnabled],
+  );
+
+  const moveSession = useCallback(
+    (direction: "up" | "down") => {
+      const current = sessionRef.current;
+      if (!current) return false;
+      const drag = toDrag(current);
+      const moved = keyboardMove(drag, board, direction);
+      if (moved === drag) return true;
+      const next = { ...current, targetIndex: moved.target.index };
+      setSession(next);
+      sessionRef.current = next;
+      announce("move", moved, current.label);
+      return true;
+    },
+    [announce, board, toDrag],
+  );
+
+  const dropSession = useCallback(() => {
+    const current = sessionRef.current;
+    if (!current) return false;
+    const drag = toDrag(current);
+    const result = resolveDrop(drag);
+    announce("drop", drag, current.label);
+    setSession(null);
+    sessionRef.current = null;
+    if (result.commit) {
+      onChange?.(applyReorder(itemsRef.current, result.from.index, result.to.index));
+    }
+    requestAnimationFrame(() => focusRow(current.id));
+    return true;
+  }, [announce, focusRow, onChange, toDrag]);
+
+  const cancelSession = useCallback(() => {
+    const current = sessionRef.current;
+    if (!current) return false;
+    announce("cancel", toDrag(current), current.label);
+    setSession(null);
+    sessionRef.current = null;
+    requestAnimationFrame(() => focusRow(current.id));
+    return true;
+  }, [announce, focusRow, toDrag]);
+
+  const onRowKeyDown = useCallback(
+    (index: number, e: { key: string; preventDefault: () => void }) => {
+      if (!enabled) return;
+      if (sessionRef.current) return;
+      if (e.key === " ") {
+        e.preventDefault();
+        liftAt(index, "keyboard");
+      }
+    },
+    [enabled, liftAt],
+  );
+
+  const onHandleKeyDown = useCallback(
+    (index: number, e: { key: string; preventDefault: () => void }) => {
+      if (!enabled) return;
+      if (sessionRef.current) return;
+      if (e.key === " " || e.key === "Enter") {
+        e.preventDefault();
+        liftAt(index, "keyboard");
+      }
+    },
+    [enabled, liftAt],
+  );
+
+  useEffect(() => {
+    if (!enabled || typeof window === "undefined") return;
+    const onKey = (e: KeyboardEvent) => {
+      const current = sessionRef.current;
+      if (current) {
+        if (e.key === "Escape") {
+          e.preventDefault();
+          e.stopPropagation();
+          cancelSession();
+          return;
+        }
+        if (e.key === "ArrowDown") {
+          e.preventDefault();
+          e.stopPropagation();
+          moveSession("down");
+          return;
+        }
+        if (e.key === "ArrowUp") {
+          e.preventDefault();
+          e.stopPropagation();
+          moveSession("up");
+          return;
+        }
+        if (e.key === " " || e.key === "Enter") {
+          e.preventDefault();
+          e.stopPropagation();
+          dropSession();
+        }
+        return;
+      }
+      if (e.key !== " " && e.key !== "Enter") return;
+      const handle = (e.target as HTMLElement | null)?.closest?.("[data-sortable-handle]");
+      if (!handle) return;
+      const id = handle.getAttribute("data-sortable-handle");
+      const index = ids.indexOf(id ?? "");
+      if (index < 0) return;
+      e.preventDefault();
+      liftAt(index, "keyboard");
+    };
+    window.addEventListener("keydown", onKey, true);
+    return () => window.removeEventListener("keydown", onKey, true);
+  }, [cancelSession, dropSession, enabled, ids, liftAt, moveSession]);
+
+  const measure = useCallback(() => {
+    const root = containerRef.current;
+    if (!root) return { items: [], size: 44 };
+    const els = [...root.querySelectorAll(rowSelector)];
+    const top = root.getBoundingClientRect().top;
+    const rows = els.map((el, index) => {
+      const r = el.getBoundingClientRect();
+      return {
+        index,
+        start: r.top - top + root.scrollTop,
+        size: r.height,
+      };
+    });
+    return { items: rows, size: rows[0]?.size ?? 44 };
+  }, [containerRef, rowSelector]);
+
+  const onHandlePointerDown = useCallback(
+    (
+      index: number,
+      e: { pointerType?: string; clientY: number; pointerId?: number; preventDefault?: () => void },
+    ) => {
+      if (!enabled || !rowEnabled(index)) return;
+      e.preventDefault?.();
+      const pointerType = e.pointerType ?? "mouse";
+      let lifted = false;
+      let hold: ReturnType<typeof setTimeout> | null = null;
+
+      const liftPointer = (clientY: number) => {
+        if (lifted) return;
+        lifted = true;
+        const { items: measured, size } = measure();
+        if (!liftAt(index, "pointer")) return;
+        const current = sessionRef.current;
+        if (current) {
+          const sized = { ...current, size };
+          setSession(sized);
+          sessionRef.current = sized;
+        }
+        const localY = (() => {
+          const root = containerRef.current;
+          if (!root) return 0;
+          return clientY - root.getBoundingClientRect().top + root.scrollTop;
+        })();
+        const target = insertionIndexForY({
+          localY,
+          items: measured,
+          sourceIndex: index,
+          count: itemsRef.current.length,
+          size,
+        });
+        const next = sessionRef.current;
+        if (next && target !== next.targetIndex) {
+          const moved = { ...next, targetIndex: target };
+          setSession(moved);
+          sessionRef.current = moved;
+          announce("move", toDrag(moved), moved.label);
+        }
+      };
+
+      const onMove = (ev: PointerEvent) => {
+        if (!lifted) return;
+        const root = containerRef.current;
+        if (!root) return;
+        const rect = root.getBoundingClientRect();
+        const vel = autoScrollVelocity({
+          pos: ev.clientY,
+          start: rect.top,
+          end: rect.bottom,
+          edge: AUTO_SCROLL_EDGE_PX,
+          maxSpeed: AUTO_SCROLL_MAX_SPEED,
+        });
+        if (vel) root.scrollTop += vel;
+        const { items: measured, size } = measure();
+        const localY = ev.clientY - rect.top + root.scrollTop;
+        const current = sessionRef.current;
+        if (!current) return;
+        const target = insertionIndexForY({
+          localY,
+          items: measured,
+          sourceIndex: current.sourceIndex,
+          count: itemsRef.current.length,
+          size,
+        });
+        if (target === current.targetIndex) return;
+        const moved = { ...current, targetIndex: target };
+        setSession(moved);
+        sessionRef.current = moved;
+        announce("move", toDrag(moved), moved.label);
+      };
+
+      const teardown = () => {
+        if (hold != null) clearTimeout(hold);
+        window.removeEventListener("pointermove", onMove);
+        window.removeEventListener("pointerup", onUp);
+        window.removeEventListener("pointercancel", onCancel);
+      };
+
+      const onUp = () => {
+        teardown();
+        if (lifted) dropSession();
+      };
+      const onCancel = () => {
+        teardown();
+        if (lifted) cancelSession();
+      };
+
+      window.addEventListener("pointermove", onMove);
+      window.addEventListener("pointerup", onUp);
+      window.addEventListener("pointercancel", onCancel);
+
+      if (pointerType === "mouse") {
+        liftPointer(e.clientY);
+      } else {
+        hold = setTimeout(() => liftPointer(e.clientY), TOUCH_LONG_PRESS_MS);
+      }
+    },
+    [
+      announce,
+      cancelSession,
+      containerRef,
+      dropSession,
+      enabled,
+      liftAt,
+      measure,
+      rowEnabled,
+      toDrag,
+    ],
+  );
+
+  const translateForIndex = useCallback(
+    (index: number) => {
+      const current = session;
+      if (!current) return 0;
+      return siblingOffset({
+        index,
+        sourceIndex: current.sourceIndex,
+        gapIndex: current.targetIndex,
+        size: current.size,
+      });
+    },
+    [session],
+  );
+
+  return {
+    session,
+    announcement,
+    focusedIndex,
+    setFocusedIndex,
+    rowEnabled,
+    ids,
+    labels,
+    liftAt,
+    onRowKeyDown,
+    onHandleKeyDown,
+    onHandlePointerDown,
+    translateForIndex,
+    liveProps: {
+      "aria-live": "polite" as const,
+      "aria-atomic": true,
+      "data-sortable-live": "true",
+    },
+  };
+}

package/src/Tabs/Tabs.lc50.spec.tsx

@@ -0,0 +1,41 @@
+/**
+ * LC-82 TEXT-RIDES-TEXT (catalog arm): Tabs labels ride TabLabel (Text).
+ * Array-of-string labels coalesce so `{label}{cond ? suffix : ""}` renders
+ * the concatenated name instead of tripping the native "Text strings must
+ * be rendered within a <Text> component" invariant.
+ */
+
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { screen } from "@testing-library/react";
+import { Text } from "tamagui";
+import { describe, expect, it } from "vitest";
+import { Tabs } from "./index";
+
+describe("Tabs LC-82 TEXT-RIDES-TEXT", () => {
+  it("renders array-of-strings labels as one concatenated tab name", () => {
+    const count: number = 3;
+    renderWithProviders(
+      <Tabs
+        items={[
+          {
+            value: "a",
+            label: ["Section one", count !== 0 ? ` (${count})` : ""],
+            content: <Text>Body</Text>,
+          },
+        ]}
+      />,
+    );
+    const tab = screen.getByRole("tab", { name: "Section one (3)" });
+    expect(tab).toBeInTheDocument();
+    const label = screen.getByText("Section one (3)");
+    expect(label.tagName).not.toBe("DIV");
+  });
+
+  it("renders a singleton string label on Text, not a layout DIV", () => {
+    renderWithProviders(
+      <Tabs items={[{ value: "a", label: "Only", content: <Text>Body</Text> }]} />,
+    );
+    const label = screen.getByText("Only");
+    expect(label.tagName).not.toBe("DIV");
+  });
+});

package/src/Tabs/Tabs.spec.tsx

@@ -1,8 +1,8 @@
 import { fireEvent, screen } from "@testing-library/react";
 import { Text } from "tamagui";
 import { renderWithProviders } from "@multiplatform.one/test-utils";
-import { describe, expect, it, vitest } from "vitest";
-import { Tabs, type TabsItem } from "./index";
+import { afterEach, describe, expect, it, vitest } from "vitest";
+import { Tabs, tabsOverflowFades, tabsScrollIntoViewX, type TabsItem } from "./index";
 
 const items: TabsItem[] = [
   { value: "one", label: "One", content: <Text>Panel one</Text> },
@@ -10,6 +10,13 @@ const items: TabsItem[] = [
   { value: "three", label: "Three", disabled: true, content: <Text>Panel three</Text> },
 ];
 
+const clearDirs = () => {
+  document.documentElement.removeAttribute("dir");
+  document.body.removeAttribute("dir");
+};
+
+afterEach(clearDirs);
+
 describe("Tabs", () => {
   it("renders a tablist with aria-selected on the active tab", () => {
     renderWithProviders(<Tabs items={items} />);
@@ -197,4 +204,75 @@ describe("Tabs", () => {
     expect(screen.queryByRole("tablist")).not.toBeInTheDocument();
     expect(container.querySelector("[data-tabs-variant]")).toBeNull();
   });
+
+  it("is a named compound export (List / Tab / Content)", () => {
+    expect(Tabs.List).toBeDefined();
+    expect(Tabs.Tab).toBeDefined();
+    expect(Tabs.Content).toBeDefined();
+  });
+
+  it("LC-49: exactly one tab is in the page tab order", () => {
+    renderWithProviders(<Tabs items={items} />);
+    const tabs = screen.getAllByRole("tab");
+    const stops = tabs.filter((el) => (el as HTMLElement).tabIndex === 0);
+    expect(stops).toHaveLength(1);
+    expect(stops[0]).toHaveAttribute("aria-selected", "true");
+    expect(screen.getByRole("tab", { name: "Three" }).tabIndex).toBe(-1);
+  });
+
+  it("ariaLabel overrides the default tablist name", () => {
+    renderWithProviders(<Tabs items={items} ariaLabel="Document sections" />);
+    expect(screen.getByRole("tablist")).toHaveAttribute("aria-label", "Document sections");
+  });
+
+  it("underline strip uses the G10 hairline (not a knob-driven border)", () => {
+    const { container } = renderWithProviders(<Tabs items={items} />);
+    expect(container.querySelector(".mp-hairline-b")).not.toBeNull();
+  });
+
+  it("contained variant does not paint the underline hairline", () => {
+    const { container } = renderWithProviders(
+      <Tabs items={items.slice(0, 3)} variant="contained" />,
+    );
+    expect(container.querySelector(".mp-hairline-b")).toBeNull();
+  });
+
+  it("declares writing direction on the root (useDirection)", () => {
+    document.documentElement.dir = "rtl";
+    const { container } = renderWithProviders(<Tabs items={items} />);
+    expect(container.querySelector("[data-tabs-dir]")?.getAttribute("data-tabs-dir")).toBe("rtl");
+  });
+});
+
+describe("tabsOverflowFades (rtl-audit U1)", () => {
+  it("LTR: rest state fades only the inline-end (right) edge", () => {
+    expect(tabsOverflowFades(0, 100, 400, "ltr")).toEqual({ left: false, right: true });
+    expect(tabsOverflowFades(50, 100, 400, "ltr")).toEqual({ left: true, right: true });
+    expect(tabsOverflowFades(300, 100, 400, "ltr")).toEqual({ left: true, right: false });
+  });
+
+  it("RTL: CSSOM scrollLeft is 0 → −range; rest (0) fades the physical left", () => {
+    expect(tabsOverflowFades(0, 100, 400, "rtl")).toEqual({ left: true, right: false });
+    expect(tabsOverflowFades(-150, 100, 400, "rtl")).toEqual({ left: true, right: true });
+    expect(tabsOverflowFades(-300, 100, 400, "rtl")).toEqual({ left: false, right: true });
+  });
+
+  it("no overflow → no fades in either direction", () => {
+    expect(tabsOverflowFades(0, 400, 400, "ltr")).toEqual({ left: false, right: false });
+    expect(tabsOverflowFades(0, 400, 400, "rtl")).toEqual({ left: false, right: false });
+  });
+});
+
+describe("tabsScrollIntoViewX", () => {
+  const layout = { x: 250, y: 0, width: 80, height: 32 };
+
+  it("LTR scrolls so a clipped tab lands inside the pad", () => {
+    expect(tabsScrollIntoViewX(layout, 0, 100, 400, "ltr")).toBe(250 + 80 - 100 + 32);
+  });
+
+  it("RTL converts the physical window back onto the negative scrollLeft range", () => {
+    const x = tabsScrollIntoViewX(layout, 0, 100, 400, "rtl");
+    expect(x).toBeLessThanOrEqual(0);
+    expect(x).toBeGreaterThanOrEqual(-300);
+  });
 });

package/src/Tabs/Tabs.stories.tsx

@@ -6,9 +6,10 @@ import {
   PaperclipIcon,
   UserIcon,
 } from "@phosphor-icons/react";
+import { Button, Input } from "@multiplatform.one/forms";
 import type { Meta, StoryObj } from "@storybook/react-native-web-vite";
 import React from "react";
-import { Button, Input, ScrollView, Text, XStack, YStack } from "tamagui";
+import { ScrollView, Text, XStack, YStack } from "tamagui";
 import { Chip } from "../Chip";
 import { Tabs, type TabsItem } from "./index";
 
@@ -38,6 +39,7 @@ const meta: Meta<typeof Tabs> = {
     loop: { control: "boolean" },
     disabled: { control: "boolean" },
     defaultValue: { control: "text" },
+    ariaLabel: { control: "text" },
   },
 };
 export default meta;
@@ -46,7 +48,7 @@ type Story = StoryObj<typeof Tabs>;
 
 const Panel = ({ title, body }: { title: string; body: string }) => (
   <YStack gap="$2">
-    <Text fontWeight="600">{title}</Text>
+    <Text fontWeight="700">{title}</Text>
     <Text color="$color11">{body}</Text>
   </YStack>
 );
@@ -215,7 +217,7 @@ export const LazyMountPanels: Story = {
         content: (
           <YStack gap="$2" maxWidth={320}>
             <Text color="$color11">Type here, switch away, and come back — state survives:</Text>
-            <Input placeholder="Kept alive across tab switches" />
+            <Input name="keptAlive" placeholder="Kept alive across tab switches" />
           </YStack>
         ),
       },