@multiplatform.one/components 7.28.1 → 7.29.1

package/src/layouts/EmptyState.tsx

@@ -62,6 +62,12 @@ export function EmptyState({
   // Polaris/Primer: icon | copy | actions are three bands; title+description
   // sit tighter than the bands. Compact (table/column) stays on the stepped gap.
   const frameGap = compact ? knobProps.gap : knobProps.gapLg;
+  // One paragraph per line: a web paragraph folds a newline into a space, and
+  // a multi-line server reason (LC-96) then reads as one run-on sentence.
+  const descriptionLines = (description ?? "")
+    .split("\n")
+    .map((line) => line.trim())
+    .filter(Boolean);
 
   if (isError) {
     warnBannedErrorWords(title, { component: "EmptyState" });
@@ -145,8 +151,9 @@ export function EmptyState({
       {well && isError ? <Intent name="error">{well}</Intent> : well}
       <YStack alignItems="center" gap="$1" {...readingWidthStyle()}>
         {titleNode}
-        {description ? (
+        {descriptionLines.map((line, index) => (
           <Paragraph
+            key={`${index}:${line}`}
             {...knobProps.body}
             color={knobProps.textAccentColor as any}
             fontSize={knobProps.label.fontSize}
@@ -154,9 +161,9 @@ export function EmptyState({
             margin={0}
             width="100%"
           >
-            {description}
+            {line}
           </Paragraph>
-        ) : null}
+        ))}
       </YStack>
       {action ? (
         <XStack

package/src/layouts/Screen.keyboardTaps.spec.tsx

@@ -0,0 +1,57 @@
+/**
+ * MPO-457: a native sheet is an RN Modal, so the Screen's ScrollView is a
+ * React ancestor of every row in it. At RN's default keyboardShouldPersistTaps
+ * ("never") that ScrollView claims the first tap in the sheet while the
+ * keyboard is up and spends it on dismissing the keyboard. The house
+ * ScrollView carries "handled" on native (ScrollView.native.spec.tsx), so
+ * Screen must scroll through it.
+ */
+import { cleanup } from "@testing-library/react";
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { afterEach, expect, it, vi } from "vitest";
+import { Screen } from "./page";
+
+const houseScrollViews = vi.hoisted(() => [] as Array<Record<string, unknown>>);
+
+vi.mock("../ScrollView", async (importOriginal) => {
+  const { forwardRef, createElement } = await import("react");
+  const { ScrollView } = await importOriginal<typeof import("../ScrollView")>();
+  return {
+    ScrollView: forwardRef<unknown, Record<string, unknown>>(function HouseScrollProbe(props, ref) {
+      houseScrollViews.push(props);
+      return createElement(ScrollView as never, { ...props, ref });
+    }),
+  };
+});
+
+afterEach(() => {
+  cleanup();
+  houseScrollViews.length = 0;
+});
+
+it("scrolls through the house ScrollView, which defaults keyboard taps to handled on native", () => {
+  renderWithProviders(
+    <Screen>
+      <span>Page body</span>
+    </Screen>,
+  );
+  expect(houseScrollViews.length).toBeGreaterThan(0);
+});
+
+it("still hands scrollViewProps to that ScrollView, so a screen can opt back out", () => {
+  renderWithProviders(
+    <Screen scrollViewProps={{ keyboardShouldPersistTaps: "never" }}>
+      <span>Page body</span>
+    </Screen>,
+  );
+  expect(houseScrollViews.at(-1)?.keyboardShouldPersistTaps).toBe("never");
+});
+
+it("renders no ScrollView when scroll is off", () => {
+  renderWithProviders(
+    <Screen scroll={false}>
+      <span>Page body</span>
+    </Screen>,
+  );
+  expect(houseScrollViews).toEqual([]);
+});

package/src/layouts/Screen.stories.tsx

@@ -1,7 +1,9 @@
 import type { Meta, StoryObj } from "@storybook/react-native-web-vite";
 // Catalog Button (G-15 story honesty / LC-18, UX-P06).
-import { Button } from "@multiplatform.one/forms";
-import { Paragraph, YStack } from "tamagui";
+import { Button, Input } from "@multiplatform.one/forms";
+import { useState } from "react";
+import { Paragraph, SizableText, YStack } from "tamagui";
+import { SheetModal } from "../SheetModal";
 import { CONTENT_MAX_WIDTH, EmptyState, PageHeader, PageSection, Screen } from "./page";
 
 const meta: Meta<typeof Screen> = {
@@ -106,3 +108,54 @@ export const NestedScreens: Story = {
     </Screen>
   ),
 };
+
+const PROJECTS = ["Alpha", "Beta", "Gamma", "Delta"] as const;
+
+function SheetOverKeyboardHarness(args: Story["args"]) {
+  const [open, setOpen] = useState(false);
+  const [picks, setPicks] = useState<string[]>([]);
+  const readout = `Picks: ${picks.length}${picks.length ? `, last ${picks[picks.length - 1]}` : ""}`;
+  return (
+    <Screen {...args}>
+      <PageHeader
+        title="Sheet over the keyboard"
+        subtitle="The Screen scrolls at its defaults and the sheet opens over it"
+      />
+      <Paragraph testID="screen-plain-text">
+        With a field focused, a tap on this text dismisses the keyboard.
+      </Paragraph>
+      <Input label="Screen field" placeholder="Focus to raise the keyboard" />
+      <Button onPress={() => setOpen(true)}>Open sheet</Button>
+      <Paragraph testID="screen-picks">{readout}</Paragraph>
+      <SheetModal
+        open={open}
+        onOpenChange={setOpen}
+        header={<SizableText fontWeight="600">Pick a project</SizableText>}
+      >
+        <YStack gap="$2">
+          <Input label="Search" placeholder="Focus to raise the keyboard" />
+          <Paragraph testID="sheet-picks">{readout}</Paragraph>
+          {PROJECTS.map((name) => (
+            <Button key={name} onPress={() => setPicks((previous) => [...previous, name])}>
+              {name}
+            </Button>
+          ))}
+        </YStack>
+      </SheetModal>
+    </Screen>
+  );
+}
+
+export const SheetOverKeyboard: Story = {
+  name: "Sheet over the keyboard",
+  parameters: {
+    nativeGallery: { scroll: false },
+    docs: {
+      description: {
+        story:
+          "MPO-457: the sheet is an RN Modal, so the Screen's ScrollView is a React ancestor of every row in it. Focus Search, then tap a project: the first tap picks it while the keyboard stays up.",
+      },
+    },
+  },
+  render: (args) => <SheetOverKeyboardHarness {...args} />,
+};

package/src/layouts/page.tsx

@@ -28,21 +28,9 @@ import {
 } from "@multiplatform.one/theme";
 import type { ReactNode } from "react";
 import type { ScrollViewProps as TamaguiScrollViewProps, XStackProps, YStackProps } from "tamagui";
-import {
-  H1,
-  H2,
-  H3,
-  H4,
-  H5,
-  H6,
-  Paragraph,
-  ScrollView,
-  Separator,
-  XStack,
-  YStack,
-  isWeb,
-} from "tamagui";
+import { H1, H2, H3, H4, H5, H6, Paragraph, Separator, XStack, YStack, isWeb } from "tamagui";
 import { componentColors, sectionHeading } from "../componentColors";
+import { ScrollView } from "../ScrollView";
 import {
   PageHeadingScope,
   usePageChromeInset,

package/src/layouts/sidebar.tsx

@@ -12,7 +12,8 @@ import {
 } from "@multiplatform.one/theme";
 import type React from "react";
 import { Fragment, useId, useState } from "react";
-import { Label, ScrollView, Separator, Text, XStack, YStack, isWeb } from "tamagui";
+import { Label, Separator, Text, XStack, YStack, isWeb } from "tamagui";
+import { ScrollView } from "../ScrollView";
 import { componentColors } from "../componentColors";
 
 export interface SidebarSection {

package/src/layouts/tags.tsx

@@ -14,7 +14,6 @@ import {
   Input,
   Label,
   Popover,
-  ScrollView,
   Text,
   View,
   XStack,
@@ -24,6 +23,7 @@ import {
   type InputProps,
   type YStackProps,
 } from "tamagui";
+import { ScrollView } from "../ScrollView";
 import {
   Chip,
   ChipFrame,

package/src/layouts/toolbar.tsx

@@ -10,7 +10,8 @@ import {
 import type React from "react";
 import { useTranslation } from "../shared/i18n";
 import { Button } from "@multiplatform.one/forms";
-import { Group, ScrollView, Separator, Text, XStack, isWeb } from "tamagui";
+import { Group, Separator, Text, XStack, isWeb } from "tamagui";
+import { ScrollView } from "../ScrollView";
 
 export interface ToolbarAction {
   label: string;

package/src/shared/useReturnFocusOnClose.spec.tsx

@@ -0,0 +1,39 @@
+import { act, cleanup, renderHook } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { useReturnFocusOnClose } from "./useReturnFocusOnClose";
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+  cleanup();
+  vi.useRealTimers();
+  document.body.replaceChildren();
+});
+
+describe("useReturnFocusOnClose", () => {
+  function setup() {
+    vi.useFakeTimers();
+    const trigger = document.createElement("button");
+    document.body.append(trigger);
+    trigger.focus();
+    const hook = renderHook(({ open }) => useReturnFocusOnClose(open), {
+      initialProps: { open: true },
+    });
+    return { ...hook, trigger };
+  }
+
+  it("restores dropped focus after the close animation", async () => {
+    const h = setup();
+    h.trigger.blur();
+    h.rerender({ open: false });
+    await act(() => vi.advanceTimersByTimeAsync(400));
+    expect(document.activeElement).toBe(h.trigger);
+  });
+
+  it("leaves the delayed restore inert once the document is gone", () => {
+    const h = setup();
+    h.trigger.blur();
+    h.rerender({ open: false });
+    vi.stubGlobal("document", undefined);
+    expect(() => vi.advanceTimersByTime(400)).not.toThrow();
+  });
+});

package/src/shared/useReturnFocusOnClose.ts

@@ -39,6 +39,10 @@ export function useReturnFocusOnClose(open: boolean) {
     if (!canUseDom() || !open) return;
     return () => {
       const restore = () => {
+        // Nothing cancels this after unmount, so the document can be gone by
+        // now (a test environment torn down inside the retry window), and
+        // `isConnected` stays true on the detached node.
+        if (!canUseDom()) return;
         const target = prevRef.current;
         if (!target || !target.isConnected) return;
         if (focusIsDropped()) {

package/src/surfaces.spec.tsx

@@ -1,7 +1,7 @@
-import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { modelFirstFocusableShow, renderWithProviders } from "@multiplatform.one/test-utils";
 import { Preset, type Knobs } from "@multiplatform.one/theme";
 import { defaultConfig } from "@tamagui/config/v5";
-import { cleanup, render } from "@testing-library/react";
+import { cleanup, fireEvent, render, screen, waitFor } from "@testing-library/react";
 import { readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -14,7 +14,8 @@ import {
   Sheet,
   TamaguiProvider,
 } from "tamagui";
-import { afterEach, describe, expect, it } from "vitest";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { Input } from "@multiplatform.one/forms";
 import { Button } from "./Button";
 import * as pkg from "./index";
 import {
@@ -22,6 +23,7 @@ import {
   CardFooter,
   CardHeader,
   DialogContent,
+  DialogShowFocus,
   AlertDialogContent,
   AlertDialogOverlay,
   KnobCard,
@@ -280,3 +282,270 @@ describe("overlay containers take the Axiom 1 child-clip cap (MPO-150)", () => {
     }
   }
 });
+
+// MPO-452: tamagui's FocusScope checks "focus already inside?" before an idle
+// wait of up to 200 ms, then focuses the first tabbable that does not hold
+// focus. A click into the name field during that wait had focus moved on to
+// the Save button, so every keystroke after it missed the field.
+describe("PopoverContent open focus (MPO-452)", () => {
+  function SaveAsPopover() {
+    return (
+      <Popover>
+        <Popover.Trigger asChild>
+          <button type="button">Save As</button>
+        </Popover.Trigger>
+        <PopoverContent>
+          <input aria-label="Report name" />
+          <button type="button">Save</button>
+        </PopoverContent>
+      </Popover>
+    );
+  }
+
+  it("keeps focus on a field focused right after open", async () => {
+    renderWithProviders(<SaveAsPopover />);
+    fireEvent.click(screen.getByRole("button", { name: "Save As" }));
+    const field = await waitFor(() => screen.getByLabelText("Report name"));
+    field.focus();
+    expect(document.activeElement).toBe(field);
+    await new Promise((resolve) => setTimeout(resolve, 300));
+    expect(document.activeElement).toBe(field);
+  });
+
+  it("focuses the first tabbable on open", async () => {
+    renderWithProviders(<SaveAsPopover />);
+    fireEvent.click(screen.getByRole("button", { name: "Save As" }));
+    const field = await waitFor(() => screen.getByLabelText("Report name"));
+    await waitFor(() => expect(document.activeElement).toBe(field));
+  });
+});
+
+// MPO-466: DialogContent mounts the same FocusScope. In browsers its native
+// <dialog>.show() focuses inside first; jsdom has no show(), so the deferred
+// pass ran and moved focus off a field focused right after open.
+describe("DialogContent open focus (MPO-466)", () => {
+  function RenameDialog({ onOpenAutoFocus }: { onOpenAutoFocus?: (event: Event) => void }) {
+    return (
+      <Dialog modal>
+        <Dialog.Trigger asChild>
+          <button type="button">Rename</button>
+        </Dialog.Trigger>
+        <Dialog.Portal>
+          <DialogContent onOpenAutoFocus={onOpenAutoFocus}>
+            <input aria-label="Name" />
+            <input aria-label="Notes" />
+            <button type="button">Save</button>
+          </DialogContent>
+        </Dialog.Portal>
+      </Dialog>
+    );
+  }
+
+  const settle = () => new Promise((resolve) => setTimeout(resolve, 300));
+
+  it.each(["Name", "Notes"])(
+    "keeps focus on the %s field focused right after open",
+    async (label) => {
+      renderWithProviders(<RenameDialog />);
+      fireEvent.click(screen.getByRole("button", { name: "Rename" }));
+      const field = await waitFor(() => screen.getByLabelText(label));
+      field.focus();
+      expect(document.activeElement).toBe(field);
+      await settle();
+      expect(document.activeElement).toBe(field);
+    },
+  );
+
+  it("focuses the first tabbable on open", async () => {
+    renderWithProviders(<RenameDialog />);
+    fireEvent.click(screen.getByRole("button", { name: "Rename" }));
+    const field = await waitFor(() => screen.getByLabelText("Name"));
+    await waitFor(() => expect(document.activeElement).toBe(field));
+  });
+
+  it("runs the caller's onOpenAutoFocus first and lets it opt out", async () => {
+    const seen: boolean[] = [];
+    renderWithProviders(
+      <RenameDialog
+        onOpenAutoFocus={(event) => {
+          seen.push(event.defaultPrevented);
+          event.preventDefault();
+        }}
+      />,
+    );
+    const trigger = screen.getByRole("button", { name: "Rename" });
+    trigger.focus();
+    fireEvent.click(trigger);
+    await waitFor(() => screen.getByLabelText("Name"));
+    await settle();
+    expect(seen).toEqual([false]);
+    expect(document.activeElement).toBe(trigger);
+  });
+});
+
+// AlertDialogContent needs no house handler: tamagui's AlertDialog.Content
+// prevents the FocusScope open pass and focuses its Cancel action in the same
+// step, so there is no deferred focus to race.
+describe("AlertDialogContent open focus (MPO-466)", () => {
+  function RenameAlertDialog() {
+    return (
+      <AlertDialog>
+        <AlertDialog.Trigger asChild>
+          <button type="button">Rename</button>
+        </AlertDialog.Trigger>
+        <AlertDialog.Portal>
+          <AlertDialogContent>
+            <input aria-label="Name" />
+            <AlertDialog.Cancel asChild>
+              <button type="button">Cancel</button>
+            </AlertDialog.Cancel>
+            <button type="button">Save</button>
+          </AlertDialogContent>
+        </AlertDialog.Portal>
+      </AlertDialog>
+    );
+  }
+
+  it("focuses its Cancel action on open", async () => {
+    renderWithProviders(<RenameAlertDialog />);
+    fireEvent.click(screen.getByRole("button", { name: "Rename" }));
+    const cancel = await waitFor(() => screen.getByText("Cancel"));
+    await waitFor(() => expect(document.activeElement).toBe(cancel));
+  });
+
+  it("keeps focus on a field focused right after open", async () => {
+    renderWithProviders(<RenameAlertDialog />);
+    fireEvent.click(screen.getByRole("button", { name: "Rename" }));
+    const field = await waitFor(() => screen.getByLabelText("Name"));
+    field.focus();
+    await new Promise((resolve) => setTimeout(resolve, 300));
+    expect(document.activeElement).toBe(field);
+  });
+});
+
+// MPO-470: in Chromium and WebKit, <dialog>.show() focuses the first focusable
+// descendant, a tabindex=-1 frame included, where Firefox and the HTML spec
+// take the first tab stop. The house Input's group frame is tabindex=-1, so it
+// took focus, FocusScope then saw focus inside and never ran the open focus,
+// and typing went nowhere. jsdom has no show(), so modelFirstFocusableShow
+// stands in for Chromium's.
+
+describe("DialogContent open focus behind <dialog>.show() (MPO-470)", () => {
+  let restoreShow = () => {};
+  beforeEach(() => {
+    restoreShow = modelFirstFocusableShow();
+  });
+  afterEach(() => restoreShow());
+
+  function NameDialog({
+    helpFirst,
+    onOpenAutoFocus,
+  }: {
+    helpFirst?: boolean;
+    onOpenAutoFocus?: (event: Event) => void;
+  }) {
+    return (
+      <Dialog modal>
+        <Dialog.Trigger asChild>
+          <button type="button">Rename</button>
+        </Dialog.Trigger>
+        <Dialog.Portal>
+          <DialogContent onOpenAutoFocus={onOpenAutoFocus}>
+            {helpFirst ? <button type="button">Help</button> : null}
+            <Input inputProps={{ "aria-label": "Name" }} />
+            <button type="button">Save</button>
+          </DialogContent>
+        </Dialog.Portal>
+      </Dialog>
+    );
+  }
+
+  it("moves focus off the house Input's group frame onto its field", async () => {
+    renderWithProviders(<NameDialog />);
+    fireEvent.click(screen.getByRole("button", { name: "Rename" }));
+    const field = await waitFor(() => screen.getByLabelText("Name"));
+    expect(field.closest("[tabindex='-1']")).not.toBeNull();
+    await waitFor(() => expect(document.activeElement).toBe(field));
+  });
+
+  it("runs the caller's onOpenAutoFocus, which can pick another target", async () => {
+    renderWithProviders(
+      <NameDialog
+        onOpenAutoFocus={(event) => {
+          event.preventDefault();
+          screen.getByRole("button", { name: "Save" }).focus();
+        }}
+      />,
+    );
+    fireEvent.click(screen.getByRole("button", { name: "Rename" }));
+    const save = await waitFor(() => screen.getByRole("button", { name: "Save" }));
+    await waitFor(() => expect(document.activeElement).toBe(save));
+  });
+
+  it("leaves focus on a tab stop the browser picked", async () => {
+    renderWithProviders(<NameDialog helpFirst />);
+    fireEvent.click(screen.getByRole("button", { name: "Rename" }));
+    const help = await waitFor(() => screen.getByRole("button", { name: "Help" }));
+    await new Promise((resolve) => setTimeout(resolve, 300));
+    expect(document.activeElement).toBe(help);
+  });
+});
+
+describe("AlertDialogContent open focus behind <dialog>.show() (MPO-470)", () => {
+  let restoreShow = () => {};
+  beforeEach(() => {
+    restoreShow = modelFirstFocusableShow();
+  });
+  afterEach(() => restoreShow());
+
+  it("moves focus off the house Input's group frame onto its field", async () => {
+    renderWithProviders(
+      <AlertDialog>
+        <AlertDialog.Trigger asChild>
+          <button type="button">Rename</button>
+        </AlertDialog.Trigger>
+        <AlertDialog.Portal>
+          <AlertDialogContent>
+            <Input inputProps={{ "aria-label": "Name" }} />
+            <AlertDialog.Cancel asChild>
+              <button type="button">Cancel</button>
+            </AlertDialog.Cancel>
+          </AlertDialogContent>
+        </AlertDialog.Portal>
+      </AlertDialog>,
+    );
+    fireEvent.click(screen.getByRole("button", { name: "Rename" }));
+    const field = await waitFor(() => screen.getByLabelText("Name"));
+    expect(field.closest("[tabindex='-1']")).not.toBeNull();
+    await waitFor(() => expect(document.activeElement).toBe(field));
+  });
+});
+
+describe("DialogShowFocus in a raw Dialog.Content (MPO-470)", () => {
+  let restoreShow = () => {};
+  beforeEach(() => {
+    restoreShow = modelFirstFocusableShow();
+  });
+  afterEach(() => restoreShow());
+
+  it("moves focus off the house Input's group frame onto its field", async () => {
+    renderWithProviders(
+      <Dialog modal>
+        <Dialog.Trigger asChild>
+          <button type="button">Save Filter</button>
+        </Dialog.Trigger>
+        <Dialog.Portal>
+          <Dialog.Content>
+            <Input inputProps={{ "aria-label": "Filter Name" }} />
+            <button type="button">Save</button>
+            <DialogShowFocus />
+          </Dialog.Content>
+        </Dialog.Portal>
+      </Dialog>,
+    );
+    fireEvent.click(screen.getByRole("button", { name: "Save Filter" }));
+    const field = await waitFor(() => screen.getByLabelText("Filter Name"));
+    expect(field.closest("[tabindex='-1']")).not.toBeNull();
+    await waitFor(() => expect(document.activeElement).toBe(field));
+  });
+});