@multiplatform.one/forms 6.1.0 → 6.3.0

package/src/FloatingPanel/index.tsx

@@ -1,10 +1,11 @@
 import type { ReactNode, UIEvent } from "react";
 import { useCallback, useEffect, useLayoutEffect, useRef, useState } from "react";
-import { useResolvedKnobs } from "@multiplatform.one/theme";
+import { OVERLAY_BREAKPOINT, useResolvedKnobs } from "@multiplatform.one/theme";
 import { isWeb, Sheet, useMedia, View, YStack } from "tamagui";
 import { useClick, useDismiss, useInteractions } from "@floating-ui/react";
 import { ScrollArrow } from "../shared/floatingList";
-import { formInputColors } from "../shared/colorRamps";
+import { useReturnFocusOnClose, useSheetModalFocus } from "../shared/focusManagement";
+import { useSheetEscapeDismiss } from "../shared/useSheetEscapeDismiss";
 import { useFloatingPanel, panelTransition, panelViewportPadding } from "./useFloatingPanel";
 import { zIndex } from "../shared/zIndex";
 
@@ -24,6 +25,13 @@ export interface FloatingPanelProps {
   open: boolean;
   onOpenChange: (open: boolean) => void;
   trigger: ReactNode;
+  /**
+   * Optional control rendered beside the trigger but OUTSIDE the native press
+   * capture (e.g. DatePicker/ColorPicker clear). On native the trigger subtree
+   * uses pointerEvents="none" so XGroup cannot steal the open gesture; anything
+   * that must keep its own onPress belongs here.
+   */
+  triggerEnd?: ReactNode;
   children: ReactNode;
   scrollable?: boolean;
   disabled?: boolean;
@@ -62,15 +70,32 @@ export interface FloatingPanelProps {
    * Only applies in sheet mode.
    */
   header?: ReactNode;
+  /**
+   * Native sheet mode: open the sheet at its full height (85% of the window)
+   * with the scroll area filling it, instead of content-driven height.
+   * For search-driven panels whose result list streams in as the user types
+   * (Awesomebar, Link fields) a content-fit sheet opens as a sliver showing
+   * only the search input. Web small-viewport sheets get the tall treatment
+   * from `scrollable` (percent snap points) instead.
+   */
+  sheetFill?: boolean;
   /**
    * Props passed to Sheet.ScrollView when scrollable. Use for onScroll (e.g. infinite load).
    */
   scrollViewProps?: Record<string, unknown>;
+  /**
+   * Native-only (iOS/Android): explicit VoiceOver/TalkBack name, value, and
+   * hint for the sheet trigger Pressable. On native the trigger subtree is
+   * pointerEvents="none", so its aria wiring never reaches the screen reader —
+   * the strings must live on the Pressable itself. Web ignores this.
+   */
+  triggerA11y?: { label?: string; value?: string; hint?: string };
 }
 
 // ── FloatingPanel ─────────────────────────────────────────────
 
-const gtSmBreakpoint = 860;
+// Canonical float↔sheet pivot (theme `layoutBreakpoints.expanded`, DG-LAY-01).
+const gtSmBreakpoint = OVERLAY_BREAKPOINT;
 
 /** Viewport-based gtSm that updates on resize (useMedia may not re-render on resize). */
 export function useViewportGtSm() {
@@ -104,32 +129,51 @@ function FloatingPanelSheet({
   open,
   onOpenChange,
   trigger,
+  triggerEnd,
   children,
   scrollable,
   disabled,
   contentPadding = "default",
-  transition = "medium",
+  transition: transitionProp,
   header,
   scrollViewProps,
 }: FloatingPanelProps) {
   const { knobProps } = useResolvedKnobs();
+  // LC-24 / A-ENTEREXIT: honor animation=none (undefined) — do not hardcode "medium".
+  const transition = transitionProp ?? knobProps.transition;
   const [position, setPosition] = useState(0);
 
   const handleOpenChange = (next: boolean) => {
-    if (!disabled) onOpenChange(next);
+    if (disabled) return;
+    // Every open starts at the top snap point — not wherever the previous
+    // drag left the sheet (a stale low snap reintroduces the sliver-open).
+    if (next) setPosition(0);
+    onOpenChange(next);
   };
+  // Tamagui Sheet has no key handling (unlike the web floating mode, which
+  // dismisses on Escape) — wire the dismissal intent here too.
+  useSheetEscapeDismiss(open, () => handleOpenChange(false));
+  // DG-A11Y-04 / Axiom 7: Sheet has no focus scope — move focus into the
+  // frame on open, trap Tab while open, return focus to the trigger on close.
+  const sheetFrameRef = useRef<HTMLElement | null>(null);
+  useSheetModalFocus(open, sheetFrameRef);
 
   const framePadding = contentPadding === "none" ? "$0" : knobProps.panelPadding.padding;
   const frameGap = contentPadding === "none" ? undefined : knobProps.gapLg.gap;
 
   return (
     <>
-      <View
-        onPress={() => handleOpenChange(!open)}
-        cursor={disabled ? "not-allowed" : "pointer"}
-        opacity={disabled ? 0.5 : 1}
-      >
-        {trigger}
+      <View flexDirection="row" alignItems="center" width="100%">
+        <View
+          flex={1}
+          minWidth={0}
+          onPress={() => handleOpenChange(!open)}
+          cursor={disabled ? "not-allowed" : "pointer"}
+          opacity={disabled ? 0.5 : 1}
+        >
+          {trigger}
+        </View>
+        {triggerEnd}
       </View>
       <Sheet
         modal
@@ -144,13 +188,20 @@ function FloatingPanelSheet({
         transition={transition}
       >
         <Sheet.Overlay
-          {...({ transition } as any)}
-          bg="$shadow6"
+          transition={transition}
+          backgroundColor="$shadow6"
           enterStyle={{ opacity: 0 }}
           exitStyle={{ opacity: 0 }}
         />
         <Sheet.Handle />
-        <Sheet.Frame padding={framePadding} gap={frameGap}>
+        <Sheet.Frame
+          // Sheet.Frame forwards its ref at runtime; the styled prop type
+          // just omits `ref`, hence the cast. tabIndex -1 makes the frame a
+          // programmatic focus target without joining the tab order.
+          {...({ ref: sheetFrameRef, tabIndex: -1 } as Record<string, unknown>)}
+          padding={framePadding}
+          gap={frameGap}
+        >
           {header}
           {scrollable ? (
             <Sheet.ScrollView flex={header ? 1 : undefined} {...scrollViewProps}>
@@ -206,6 +257,12 @@ function FloatingPanelWeb({
     },
   });
 
+  // DG-A11Y-04 / Axiom 7: floating-ui useDismiss has no focus manager — when
+  // Escape (or outside click on empty space) closes the panel while focus is
+  // inside it, focus falls to <body>. Return it to the pre-open element
+  // (the trigger's focusable). Deliberate focus moves elsewhere are kept.
+  useReturnFocusOnClose(open);
+
   const repositionOverlay = useCallback(() => {
     const dropdownElement = panel.refs.floating.current;
     const trig = panel.triggerRef.current;
@@ -226,6 +283,7 @@ function FloatingPanelWeb({
     const totalBorderWidth = borderTopWidth + borderBottomWidth;
     const scrollContentHeight = dropdownElement.scrollHeight;
     const totalContentHeight = scrollContentHeight + totalBorderWidth;
+    const liveTransition = panel.knobProps.transition ? panelTransition : "none";
 
     const isDropup = panel.placement.startsWith("top");
 
@@ -248,7 +306,7 @@ function FloatingPanelWeb({
 
       panel.initializingRef.current = false;
       void dropdownElement.offsetHeight;
-      if (isInitial) dropdownElement.style.transition = panelTransition;
+      if (isInitial) dropdownElement.style.transition = liveTransition;
       requestAnimationFrame(() => {
         if (dropdownElement) {
           panel.updateArrows(dropdownElement);
@@ -320,7 +378,7 @@ function FloatingPanelWeb({
 
     panel.initializingRef.current = false;
     void dropdownElement.offsetHeight;
-    if (isInitial) dropdownElement.style.transition = panelTransition;
+    if (isInitial) dropdownElement.style.transition = liveTransition;
     requestAnimationFrame(() => {
       if (dropdownElement) {
         panel.updateArrows(dropdownElement);
@@ -329,7 +387,14 @@ function FloatingPanelWeb({
         });
       }
     });
-  }, [isFill, panel.placement, panel.refs, panel.triggerRef, panel.updateArrows]);
+  }, [
+    isFill,
+    panel.placement,
+    panel.refs,
+    panel.triggerRef,
+    panel.updateArrows,
+    panel.knobProps.transition,
+  ]);
 
   repositionFnRef.current = repositionOverlay;
 
@@ -380,6 +445,9 @@ function FloatingPanelWeb({
     [isFill, panel.updateArrows],
   );
 
+  // animation=none → no CSS tween (same contract as knobProps.transition === undefined)
+  const webTransition = panel.knobProps.transition ? panelTransition : "none";
+
   return (
     <>
       <View
@@ -403,10 +471,9 @@ function FloatingPanelWeb({
               overflow: "auto",
               ...panel.floatingStyleRef.current,
               ...(overlayStyleRef.current ? { maxHeight: overlayStyleRef.current.maxHeight } : {}),
-              boxShadow: "0px 8px 28px rgba(0,0,0,0.12), 0px 2px 6px rgba(0,0,0,0.04)",
               opacity: panel.visible ? 1 : 0,
               transform: panel.visible ? "scale(1)" : "scale(0.96)",
-              transition: panelTransition,
+              transition: webTransition,
               transformOrigin: panel.placement.startsWith("top") ? "bottom left" : "top left",
             },
             onScroll: handleScroll,
@@ -414,10 +481,13 @@ function FloatingPanelWeb({
           data-testid="floating-panel-viewport"
           outlineWidth={0}
           pointerEvents={panel.visible ? "auto" : "none"}
-          backgroundColor="$background"
+          {...panel.knobProps.elevatedSurface}
+          // Complete elevatedSurface fragment above is the ONLY surface source
+          // (SF-OVERLAY "including border and elevation", Round 2 docket).
+          // The one layered exception is anatomy, not surface: the dropdown
+          // radius clamp (same shape as Card's containerRadius over
+          // elevatedSurface) keeps list rows unclipped at large radius knobs.
           borderRadius={panel.dropdownRadius}
-          borderWidth={panel.hasBorder ? panel.knobProps.borderRadius.borderWidth : 0}
-          borderColor={panel.hasBorder ? formInputColors.border.focus : "transparent"}
           paddingVertical={0}
         >
           <ScrollArrow

package/src/FloatingPanel/useFloatingPanel.ts

@@ -1,5 +1,5 @@
 import type { Middleware, Placement } from "@floating-ui/react";
-import { autoUpdate, offset, size, useFloating } from "@floating-ui/react";
+import { autoUpdate, offset, shift, size, useFloating } from "@floating-ui/react";
 import { useResolvedKnobs } from "@multiplatform.one/theme";
 import {
   type Dispatch,
@@ -13,6 +13,11 @@ import {
 } from "react";
 import { clampDropdownRadius, scrollArrowThreshold } from "../shared/floatingList";
 
+// React Native defines a `window` global without DOM event methods, so a bare
+// `typeof window` check is not enough — the floating cores mount this hook on
+// native (unused there, but it must not crash).
+const canUseDom = typeof window !== "undefined" && typeof window.addEventListener === "function";
+
 export const panelAnimationDuration = 180;
 export const panelGrowDuration = 200;
 export const panelViewportPadding = 10;
@@ -183,6 +188,10 @@ export function useFloatingPanel({
 
   const defaultMiddleware: Middleware[] = [
     offset({ mainAxis: 4 }),
+    // Horizontal collision handling: panels anchored near the right viewport
+    // edge (e.g. a ColorPicker in the last table column) shift back into view
+    // instead of clipping. Vertical placement is handled by computePlacement.
+    shift({ padding: panelViewportPadding }),
     ...(fitContent
       ? []
       : [
@@ -233,7 +242,7 @@ export function useFloatingPanel({
   // ── Page scroll lock ──────────────────────────────────────
 
   useLayoutEffect(() => {
-    if (!open || !mounted || typeof window === "undefined") return;
+    if (!open || !mounted || !canUseDom) return;
     const scrollY = window.scrollY;
     const floatingEl = refs.floating.current;
     if (!floatingEl) return;
@@ -282,7 +291,7 @@ export function useFloatingPanel({
   // ── Close on offscreen + reposition on scroll / resize ────
 
   useEffect(() => {
-    if (!open) return;
+    if (!open || !canUseDom) return;
     let rafId = 0;
     const throttled = () => {
       if (rafId) return;
@@ -311,7 +320,7 @@ export function useFloatingPanel({
   // ── Resize sync ───────────────────────────────────────────
 
   useLayoutEffect(() => {
-    if (typeof window === "undefined") return;
+    if (!canUseDom) return;
     window.addEventListener("resize", update);
     if (open) update();
     return () => window.removeEventListener("resize", update);

package/src/Form/Form.stories.tsx

@@ -28,7 +28,6 @@ import {
   MonthPicker,
   MultiDatePicker,
 } from "../fields/DatePicker";
-import { RichTextEditor } from "@multiplatform.one/rich-text";
 import { Duration } from "../fields/Duration";
 import { FileUpload } from "../fields/FileUpload";
 import { Geolocation } from "../fields/Geolocation";
@@ -47,6 +46,7 @@ import { Switch } from "../fields/Switch";
 import { TextArea } from "../fields/TextArea";
 import { TimePicker } from "../fields/TimePicker";
 import { ToggleGroup } from "../fields/ToggleGroup";
+import { formatFieldError } from "../ErrorSummary";
 import type { AnyFormApi } from "../types";
 import { Form } from "./index";
 
@@ -132,6 +132,79 @@ export const WithValidation = () => (
   </Form>
 );
 
+/**
+ * DG-VAL-02: submit with empty required fields → ErrorSummary above the form,
+ * role=alert, auto-focused, with links that jump to each invalid control.
+ * Pass `id={name}` on fields so summary anchors resolve.
+ *
+ * Copy uses formatFieldError({ problem, action }) so inline + summary stay in
+ * sync (FieldLayout still stringifies raw objects; prefer formatted strings
+ * until fieldLayout understands structured errors).
+ */
+export const WithErrorSummary = () => (
+  <Form
+    formOptions={{
+      defaultValues: {
+        fullName: "",
+        email: "",
+      },
+    }}
+    onSubmit={(values) => action("onSubmit")(values)}
+    errorSummaryTitle="There is a problem"
+  >
+    <YStack gap="$4" maxWidth={480}>
+      <Input
+        id="fullName"
+        name="fullName"
+        label="Full name"
+        required
+        validators={{
+          onSubmit: ({ value }) =>
+            !String(value || "").trim()
+              ? formatFieldError({
+                  problem: "Full name is empty.",
+                  action: "Enter your first and last name.",
+                })
+              : undefined,
+        }}
+      />
+      <Input
+        id="email"
+        name="email"
+        label="Email"
+        required
+        validators={{
+          onSubmit: ({ value }) => {
+            const v = String(value || "");
+            if (!v.trim()) {
+              return formatFieldError({
+                problem: "Email is empty.",
+                action: "Enter an email address.",
+              });
+            }
+            if (!v.includes("@")) {
+              return formatFieldError({
+                problem: "Email is incomplete.",
+                action: "Include an @ and a domain.",
+              });
+            }
+            return undefined;
+          },
+        }}
+      />
+      <Button action="submit">Save contact</Button>
+    </YStack>
+  </Form>
+);
+WithErrorSummary.parameters = {
+  docs: {
+    description: {
+      story:
+        'On failed submit, Form renders ErrorSummary (role=alert) above the fields, moves focus to it, and lists the same messages as inline errors. Each link focuses the matching control (`id` should match the field `name`). Default `validateOn="submit"` remaps field validators to blur-then-change after the first submit attempt so errors clear live.',
+    },
+  },
+};
+
 export const DynamicFields = () => {
   const form = useForm({
     defaultValues: {
@@ -775,11 +848,13 @@ export const AllFields = () => {
         <Separator marginTop="$4" />
         <H3>Full-width Fields</H3>
         <YStack gap="$4">
-          <RichTextEditor
+          {/* Rich-text form integration is covered by the rich-text package's
+              own stories — importing it here would cycle forms → rich-text. */}
+          <TextArea
             label="Rich Content"
             name="richContent"
-            helperText="Toggle between Raw and Formatted views"
-            minHeight={150}
+            helperText="Long-form text (rich editor demoed in rich-text stories)"
+            numberOfLines={6}
           />
           <Select
             label="Countries (Multi)"

package/src/Form/form.spec.tsx

@@ -279,6 +279,30 @@ describe("Form", () => {
       expect(onSubmit).not.toHaveBeenCalled();
     });
 
+    it("renders ErrorSummary with field errors after failed submit", async () => {
+      const onSubmit = vi.fn();
+      const result = renderWithProviders(
+        <Form formOptions={{ defaultValues: { name: "" } }} onSubmit={onSubmit}>
+          <Input id="name" name="name" label="Name" required />
+          <Button action="submit" testID="submit-button">
+            Submit
+          </Button>
+        </Form>,
+      );
+
+      const button = result.container.querySelector('[data-testid="submit-button"]');
+      await act(async () => {
+        if (button) fireEvent.click(button);
+      });
+
+      await waitFor(() => {
+        const summary = result.container.querySelector('[data-testid="error-summary"]');
+        expect(summary?.getAttribute("role")).toBe("alert");
+        expect(summary?.textContent).toMatch(/required/i);
+      });
+      expect(onSubmit).not.toHaveBeenCalled();
+    });
+
     it("should submit when validation passes", async () => {
       const onSubmit = vi.fn();
       const formOptions = {

package/src/Form/form.validateOn.spec.tsx

@@ -0,0 +1,65 @@
+import { act, fireEvent, waitFor } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { Button } from "../Button";
+import { Input } from "../fields/Input";
+import { Form, useEffectiveValidateOn } from "./index";
+
+describe("Form validateOn remapping (DG-VAL-01 / W2)", () => {
+  it("stays on submit before the first attempt", () => {
+    let effective: string | undefined;
+    function Probe() {
+      effective = useEffectiveValidateOn();
+      return null;
+    }
+    renderWithProviders(
+      <Form validateOn="submit" onSubmit={vi.fn()}>
+        <Probe />
+      </Form>,
+    );
+    expect(effective).toBe("submit");
+  });
+
+  it("upgrades to blur-then-change after a failed submit", async () => {
+    let effective = "submit";
+    function Probe() {
+      effective = useEffectiveValidateOn();
+      return null;
+    }
+    const result = renderWithProviders(
+      <Form formOptions={{ defaultValues: { name: "" } }} onSubmit={vi.fn()} validateOn="submit">
+        <Probe />
+        <Input id="name" name="name" label="Name" required />
+        <Button action="submit" testID="submit-button">
+          Submit
+        </Button>
+      </Form>,
+    );
+
+    expect(effective).toBe("submit");
+
+    const button = result.container.querySelector('[data-testid="submit-button"]');
+    await act(async () => {
+      if (button) fireEvent.click(button);
+    });
+
+    await waitFor(() => {
+      expect(result.container.querySelector('[data-testid="error-summary"]')).toBeTruthy();
+      expect(effective).toBe("blur-then-change");
+    });
+  });
+
+  it("honors explicit validateOn=blur without waiting for submit", () => {
+    let effective: string | undefined;
+    function Probe() {
+      effective = useEffectiveValidateOn();
+      return null;
+    }
+    renderWithProviders(
+      <Form validateOn="blur" onSubmit={vi.fn()}>
+        <Probe />
+      </Form>,
+    );
+    expect(effective).toBe("blur");
+  });
+});