@multiplatform.one/forms 7.4.1 → 7.5.0

package/src/fields/ToggleGroup/ToggleGroup.spec.tsx

@@ -2,10 +2,12 @@ import { fireEvent, render, screen } from "@testing-library/react";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { renderWithProviders } from "@multiplatform.one/test-utils";
 import {
+  MIN_PRESS_TARGET,
   createThemesBuilder,
   defaultAccentTheme,
   defaultBaseTheme,
   defaultBuilderOptions,
+  sizeRecipeForToken,
 } from "@multiplatform.one/theme";
 import { configWithoutAnimations } from "@tamagui/config";
 import { animationsCSS } from "@tamagui/config/v5-css";
@@ -231,7 +233,7 @@ describe("ToggleGroup", () => {
       const { container } = renderWithHouseThemes(
         <ToggleGroup label="Alignment" options={options} defaultValue="left" />,
       );
-      const segments = [...container.querySelectorAll('[data-state]')] as HTMLElement[];
+      const segments = [...container.querySelectorAll("[data-state]")] as HTMLElement[];
       expect(segments).toHaveLength(3);
       for (const segment of segments) {
         expect(segment.className).toMatch(/_bw-0\b|_borderw-0\b|bw-0/);
@@ -243,7 +245,7 @@ describe("ToggleGroup", () => {
       const { container } = renderWithHouseThemes(
         <ToggleGroup label="Alignment" options={options} defaultValue="center" />,
       );
-      const segments = [...container.querySelectorAll('[data-state]')] as HTMLElement[];
+      const segments = [...container.querySelectorAll("[data-state]")] as HTMLElement[];
       expect(segments).toHaveLength(3);
       const [first, middle, last] = segments;
       // Tamagui emits per-corner radius classes from stackRadiusProps.
@@ -251,5 +253,119 @@ describe("ToggleGroup", () => {
       expect(first.className).not.toEqual(middle.className);
       expect(last.className).not.toEqual(middle.className);
     });
+
+    it("rings the focused segment, never the group frame (LC-71)", () => {
+      const { container } = renderWithHouseThemes(
+        <ToggleGroup label="Alignment" options={options} defaultValue="left" />,
+      );
+      const group = container.querySelector('[role="group"]') as HTMLElement;
+      expect(group).toBeTruthy();
+      // Ring on the container is the known-bad segmented pattern: square
+      // outline over a rounded frame, and it paints on mouse via :focus-within.
+      expect(group.className).not.toMatch(/outlineWidth-2px|outlinew-2px|_ow-2px/);
+    });
+
+    it("paints segment height from the size recipe; press floor is hitSlop not minHeight (LC-75 / LC-77)", () => {
+      const { container } = renderWithHouseThemes(
+        <ToggleGroup label="Alignment" options={options} defaultValue="left" />,
+      );
+      const segments = [...container.querySelectorAll("[data-state]")] as HTMLElement[];
+      expect(segments.length).toBeGreaterThan(0);
+      const recipe = sizeRecipeForToken("$4");
+      for (const segment of segments) {
+        expect(segment.className).toContain(`_h-${recipe.height}px`);
+        // LC-77: the 44px floor is hitSlop, never a painted minHeight.
+        expect(segment.className).not.toMatch(/_mih-44px|_minh-44px|minHeight-44px/);
+        expect(MIN_PRESS_TARGET).toBe(44);
+      }
+    });
+
+    it("applies the animation knob as transition on each segment (SB-M-221)", () => {
+      const { container } = renderWithHouseThemes(
+        <ToggleGroup label="Alignment" options={options} defaultValue="left" />,
+      );
+      const segments = [...container.querySelectorAll("[data-state]")] as HTMLElement[];
+      expect(segments.length).toBeGreaterThan(0);
+      for (const segment of segments) {
+        expect(segment.className).toMatch(/transition|tns-|trs-/i);
+        expect(segment.style.transitionDuration).toMatch(/\d+ms/);
+        expect(segment.style.transitionDuration).not.toMatch(/^0m?s$/);
+      }
+    });
+  });
+
+  describe("one tab stop (LC-49 / SB-M-217)", () => {
+    it("exposes exactly one tab stop among the segments", () => {
+      const { container } = renderWithHouseThemes(
+        <ToggleGroup label="Alignment" options={options} defaultValue="center" />,
+      );
+      const segments = [...container.querySelectorAll("[data-state]")] as HTMLElement[];
+      expect(segments).toHaveLength(3);
+      expect(segments.map((el) => el.getAttribute("tabindex"))).toEqual(["-1", "0", "-1"]);
+    });
+  });
+
+  describe("edge cases", () => {
+    it("keeps duplicate option values as distinct segments (SB-M-220)", () => {
+      const { container } = renderWithHouseThemes(
+        <ToggleGroup
+          label="Dup"
+          options={[
+            { label: "One", value: "same" },
+            { label: "Two", value: "same" },
+          ]}
+        />,
+      );
+      const segments = [...container.querySelectorAll("[data-state]")] as HTMLElement[];
+      expect(segments).toHaveLength(2);
+      expect(segments.map((el) => el.id).filter(Boolean)).toHaveLength(2);
+      expect(new Set(segments.map((el) => el.id)).size).toBe(2);
+    });
+
+    it("places interior seams on logical inline edges so RTL does not invert rounding", () => {
+      const { container } = renderWithHouseThemes(
+        <ToggleGroup label="Alignment" options={options} defaultValue="left" />,
+      );
+      const seams = [...container.querySelectorAll("[data-mp-toggle-seam]")] as HTMLElement[];
+      expect(seams.length).toBeGreaterThan(0);
+      for (const seam of seams) {
+        expect(seam.className + JSON.stringify(seam.style.cssText)).toMatch(
+          /insetInlineEnd|inset-inline-end/i,
+        );
+        expect(seam.getAttribute("style") ?? "").not.toMatch(/(?:^|;)\s*right\s*:/);
+      }
+    });
+
+    it("blocks change when readOnly (SB-M-218)", () => {
+      const onChange = vi.fn();
+      const result = renderWithProviders(
+        <ToggleGroup
+          label="Alignment"
+          options={options}
+          defaultValue="left"
+          readOnly
+          onChange={onChange}
+        />,
+      );
+      const center = result.findTextElement("Center");
+      expect(center).toBeDefined();
+      if (center) fireEvent.click(center);
+      expect(onChange).not.toHaveBeenCalled();
+    });
+
+    it("sizes skeleton segments from the control recipe, never a 60px literal (LC-20)", () => {
+      const recipe = sizeRecipeForToken("$4");
+      const { container } = renderWithHouseThemes(
+        <ToggleGroup label="Loading" options={options} skeleton />,
+      );
+      const skels = [...container.querySelectorAll("[data-mp-toggle-skeleton]")] as HTMLElement[];
+      expect(skels).toHaveLength(options.length);
+      const expectedWidth = recipe.paddingHorizontal * 2 + 40;
+      for (const skel of skels) {
+        expect(skel.className).toContain(`_h-${recipe.height}px`);
+        expect(skel.className).toContain(`_w-${expectedWidth}px`);
+        expect(skel.className).not.toContain("_w-60px");
+      }
+    });
   });
 });

package/src/fields/ToggleGroup/ToggleGroup.stories.tsx

@@ -49,6 +49,23 @@ const meta: Meta<typeof ToggleGroup> = {
       options: ["single", "multiple"],
       description: "Whether single or multiple items can be selected",
     },
+    readOnly: {
+      control: "boolean",
+      description: "Whether the toggle group is read-only",
+    },
+    compact: {
+      control: "boolean",
+      description: "Density override (space only — LC-76)",
+    },
+    skeleton: {
+      control: "boolean",
+      description: "Render the LC-20 skeleton that mirrors the segment row",
+    },
+    orientation: {
+      control: "select",
+      options: ["horizontal", "vertical"],
+      description: "Segment stack direction",
+    },
   },
 };
 
@@ -167,6 +184,20 @@ export const ItemDisabledReason: Story = {
   },
 };
 
+export const ReadOnly: Story = {
+  args: {
+    label: "Read-only Toggle Group",
+    readOnly: true,
+    type: "single",
+    defaultValue: "left",
+    options: [
+      { label: "Left", value: "left" },
+      { label: "Center", value: "center" },
+      { label: "Right", value: "right" },
+    ],
+  },
+};
+
 export const WithError: Story = {
   args: {
     label: "Toggle Group with Error",
@@ -338,3 +369,13 @@ export const Comparison: Story = {
 export const SkeletonState: Story = {
   args: { label: "Alignment", type: "single", options: alignmentOptions, skeleton: true },
 };
+
+export const Compact: Story = {
+  args: {
+    label: "Alignment",
+    compact: true,
+    type: "single",
+    defaultValue: "center",
+    options: alignmentOptions,
+  },
+};

package/src/fields/ToggleGroup/index.tsx

@@ -1,8 +1,6 @@
 import type { ReactNode } from "react";
 import { useState } from "react";
 import {
-  MIN_PRESS_TARGET,
-  ensureFocusVisibleRing,
   ensureKeyboardModalityTracking,
   getGroupPosition,
   hairline,
@@ -15,15 +13,8 @@ import {
   wasKeyboardFocus,
 } from "@multiplatform.one/theme";
 import type { AnyFormApi } from "../../types";
-import type { FontSizeTokens, LabelProps, SizeTokens } from "tamagui";
-import {
-  SizableText,
-  ToggleGroup as TamaguiToggleGroup,
-  View,
-  XStack,
-  isWeb,
-  styled,
-} from "tamagui";
+import type { LabelProps, SizeTokens } from "tamagui";
+import { SizableText, ToggleGroup as TamaguiToggleGroup, View, isWeb, styled } from "tamagui";
 import { Skeleton } from "../../Skeleton";
 import { Field, FieldLayout } from "../../fieldLayout";
 import { formButtonColors, formCommonColors, formInputColors } from "../../shared/colorRamps";
@@ -31,9 +22,7 @@ import { warnBareDisabled } from "../../shared/devWarn";
 import {
   getElevationWrapperProps,
   getFieldError,
-  getFieldHeight,
   mergeFieldHandler,
-  stripRadiusFromStateProps,
   useFormField,
   useResolvedValidators,
 } from "../../shared/utils";
@@ -58,14 +47,20 @@ const ToggleItemFrame = styled(TamaguiToggleGroup.Item, {
   position: "relative",
   focusStyle: { outlineWidth: 0, backgroundColor: "transparent" },
   focusVisibleStyle: { outlineWidth: 0 },
-  hoverStyle: {
-    backgroundColor: formButtonColors.background.hover,
-  },
-  pressStyle: {
-    backgroundColor: formButtonColors.background.active,
-  },
 });
 
+/** Theme animationConfig durations — unstyled ToggleFrame drops Tamagui's transition class. */
+const SEGMENT_MOTION_MS: Record<string, number> = {
+  bouncy: 200,
+  lazy: 600,
+  slow: 500,
+  medium: 250,
+  quick: 100,
+  tooltip: 400,
+  snappy: 80,
+  gentle: 450,
+};
+
 /** State recipes may carry border/outline; segments accept FILL only (LC-71). */
 function segmentFillState(
   props: { backgroundColor?: unknown } | undefined,
@@ -198,10 +193,24 @@ export function ToggleGroup({
   if (isWeb) ensureKeyboardModalityTracking();
   const resolvedValidators = useResolvedValidators(required, validators, label, name);
   const elevationWrapperProps = getElevationWrapperProps(knobProps, elevation);
-  const sz = knobProps.sizeToken;
-  const padH = sz === "$3" ? ("$2" as const) : sz === "$5" ? ("$4" as const) : ("$3" as const);
-  const padV = sz === "$3" ? ("$1" as const) : sz === "$5" ? ("$2" as const) : ("$1.5" as const);
-  const segmentHitSlop = pressTargetHitSlop(getFieldHeight(sz));
+  // LC-75: height / pad / gap come from the coordinated size recipe. LC-77:
+  // the 44px floor is hitSlop, never a painted minHeight.
+  const segmentHitSlop = pressTargetHitSlop(knobProps.control.height);
+  // SB-M-221 / LC-68: tween fill on the unstyled item via CSS (Tamagui's
+  // `transition` token does not emit a class here). animation=none → snap.
+  const motionMs =
+    typeof knobProps.transition === "string" ? SEGMENT_MOTION_MS[knobProps.transition] : undefined;
+  const segmentMotionStyle =
+    isWeb && motionMs != null
+      ? {
+          className: "mp-toggle-transition",
+          style: {
+            transitionProperty: "background-color, color, border-color, outline-color",
+            transitionDuration: `${motionMs}ms`,
+            transitionTimingFunction: "ease",
+          },
+        }
+      : undefined;
 
   // DG-ST-03: disabled groups/items explain themselves or DEV-warn.
   warnBareDisabled({
@@ -243,8 +252,8 @@ export function ToggleGroup({
   // Render skeleton placeholder — fused R-OUTER row, square interiors (LC-20 / LC-72).
   if (skeleton) {
     const optionCount = options?.length ?? 3;
-    const segmentH = getFieldHeight(knobProps.sizeToken);
-    const segmentW = Math.round(segmentH * 1.5);
+    const segmentH = knobProps.control.height;
+    const segmentW = knobProps.control.paddingHorizontal * 2 + 40;
     return (
       <FieldLayout id={id} label={label} size={size} knobProps={knobProps}>
         <View
@@ -255,7 +264,13 @@ export function ToggleGroup({
           {...knobProps.inputSurface}
         >
           {Array.from({ length: optionCount }, (_, i) => (
-            <Skeleton key={i} variant="rectangular" width={segmentW} height={segmentH} />
+            <Skeleton
+              key={i}
+              variant="rectangular"
+              width={segmentW}
+              height={segmentH}
+              data-mp-toggle-skeleton
+            />
           ))}
         </View>
       </FieldLayout>
@@ -309,26 +324,26 @@ export function ToggleGroup({
 
       return (
         <ToggleItemWithElevation
-          key={option.value}
+          key={`${index}-${option.value}`}
           elevationWrapperProps={elevationWrapperProps}
           groupedRadius={groupedRadius}
           value={option.value}
+          id={`${id}-${index}-${option.value}`}
           unstyled
           {...(isWeb ? { tabIndex: isTabStop ? 0 : -1 } : undefined)}
-          size={knobProps.sizeToken}
           width="auto"
-          height="auto"
-          minHeight={MIN_PRESS_TARGET}
+          height={knobProps.control.height}
           hitSlop={segmentHitSlop}
           flexShrink={0}
           flexGrow={1}
           flexBasis={isWeb ? 0 : undefined}
-          paddingHorizontal={padH}
-          paddingVertical={padV}
-          gap="$1.5"
+          paddingHorizontal={knobProps.control.paddingHorizontal}
+          gap={knobProps.control.gap}
+          {...segmentMotionStyle}
           borderWidth={0}
           borderColor="transparent"
           margin={0}
+          outlineWidth={0}
           transition={knobProps.transition}
           disabled={itemDisabled}
           {...(itemDescribedBy ? { "aria-describedby": itemDescribedBy } : undefined)}
@@ -368,23 +383,16 @@ export function ToggleGroup({
                       })),
                 }
           }
-          // Focus re-asserts the selected fill (the LC-05 rule hover/press
-          // above already follow, and the exact ViewSwitcher recipe):
-          // selecting a segment focuses it, and ToggleFrame's intrinsic
-          // active recipe carries a neutral `$backgroundActive` focus fill
-          // that would otherwise grey out the chip the moment it is chosen.
+          // LC-71: ring rides the keyboard-focused item (inset, clipped
+          // group). Never a selection border. ToggleFrame's focus fill is
+          // re-asserted so the accent chip does not grey out on choose.
           focusStyle={{
-            outlineWidth: 0,
-            borderColor: formButtonColors.border.active,
-            ...stripRadiusFromStateProps(control.focusKnobProps),
-            ...(selected && !itemDisabled ? activeColors : undefined),
-          }}
-          focusVisibleStyle={{
-            outlineWidth: 0,
-            borderColor: formButtonColors.border.active,
-            ...stripRadiusFromStateProps(control.focusVisibleKnobProps),
             ...(selected && !itemDisabled ? activeColors : undefined),
+            ...(kbFocusValue === option.value ? keyboardFocusRingProps : { outlineWidth: 0 }),
           }}
+          focusVisibleStyle={
+            kbFocusValue === option.value ? keyboardFocusRingProps : { outlineWidth: 0 }
+          }
           {...(isWeb
             ? {
                 onFocus: () => {
@@ -401,8 +409,8 @@ export function ToggleGroup({
         >
           {option.icon}
           <SizableText
-            size={knobProps.sizeToken as FontSizeTokens}
             userSelect="none"
+            {...knobProps.controlType}
             {...knobProps.body}
             {...(selected && !itemDisabled && onSelectedLabel
               ? { color: onSelectedLabel }
@@ -419,18 +427,19 @@ export function ToggleGroup({
               pointerEvents="none"
               position="absolute"
               zIndex={1}
+              data-mp-toggle-seam
               {...(orientation === "horizontal"
                 ? {
                     ...hairline.vline,
                     top: 8,
                     bottom: 8,
-                    right: 0,
+                    insetInlineEnd: 0,
                     flexBasis: hairlineWidth,
                   }
                 : {
                     ...hairline.line,
-                    left: 8,
-                    right: 8,
+                    insetInlineStart: 8,
+                    insetInlineEnd: 8,
                     bottom: 0,
                     flexBasis: hairlineWidth,
                   })}
@@ -450,23 +459,17 @@ export function ToggleGroup({
   ) => {
     const emptyValue = type === "multiple" ? [] : "";
 
-    // DG-A11Y-01: the role=group container is a focusable tab entry point
-    // that redirects focus to an item — paint the ring synchronously while
-    // focus is WITHIN (CellWrapper focusWithin pattern), and on the
-    // container's own :focus for the redirect gap.
-    const groupRing = ensureFocusVisibleRing({ ...control.focusVisibleKnobProps });
-
     const toggleProps: any = {
-      focusStyle: groupRing,
-      focusVisibleStyle: groupRing,
-      focusWithinStyle: groupRing,
-      // R-OUTER (LC-18, the ViewSwitcher recipe): the group frame owns the
-      // radius so its focus ring and the clipped segment fills follow the
-      // rounded container — without it the group ring paints a square around
-      // the rounded first/last segments. Clip so square interior seams stay
-      // inside the frame at high radius (DF-09); segment rings are inset
-      // (outlineOffset −2) so they survive the clip. Elevation is the one
-      // exception: per-segment shadow wrappers would be cut by the clip.
+      // LC-71: the ring rides the focused segment, never the group. A
+      // container ring is square over the rounded frame and paints on mouse
+      // via :focus-within. Segment rings are inset so they survive the clip.
+      outlineWidth: 0,
+      focusStyle: { outlineWidth: 0 },
+      focusVisibleStyle: { outlineWidth: 0 },
+      // R-OUTER (LC-18 / LC-72 CONTAINER-CLIP): the group frame owns the
+      // radius; clip so square interior seams stay inside the rounded
+      // frame (DF-09). Elevation is the one exception: per-segment shadow
+      // wrappers would be cut by the clip.
       borderRadius: knobProps.borderRadius.borderRadius,
       ...(elevationWrapperProps.elevation ? undefined : { overflow: "hidden" as const }),
       type,

package/src/fields/selectedOrder.spec.ts

@@ -0,0 +1,29 @@
+import { describe, expect, it } from "vitest";
+import { orderOptionsBySelected } from "./selectedOrder";
+
+const options = [
+  { value: "apple", label: "Apple" },
+  { value: "banana", label: "Banana" },
+  { value: "cherry", label: "Cherry" },
+];
+
+describe("orderOptionsBySelected", () => {
+  it("selected-first pins chosen rows to the top, alphabetically among themselves", () => {
+    const ordered = orderOptionsBySelected(options, ["cherry", "apple"], "selected-first");
+    expect(ordered.map((o) => o.value)).toEqual(["apple", "cherry", "banana"]);
+  });
+
+  it("stable leaves options in the given order", () => {
+    const ordered = orderOptionsBySelected(options, ["cherry"], "stable");
+    expect(ordered.map((o) => o.value)).toEqual(["apple", "banana", "cherry"]);
+  });
+
+  it("defaults to selected-first", () => {
+    const ordered = orderOptionsBySelected(options, ["banana"]);
+    expect(ordered.map((o) => o.value)).toEqual(["banana", "apple", "cherry"]);
+  });
+
+  it("does not pin when nothing is selected", () => {
+    expect(orderOptionsBySelected(options, [], "selected-first")).toEqual(options);
+  });
+});

package/src/fields/selectedOrder.ts

@@ -0,0 +1,26 @@
+export type SelectedOrder = "selected-first" | "stable";
+
+type OptionLike = { value: string; label: string };
+
+/**
+ * Order a multi-select option list.
+ *
+ * `selected-first` (default) pins chosen rows to the top, sorted alphabetically
+ * among themselves; unselected rows keep their original relative order.
+ * `stable` never rearranges.
+ */
+export function orderOptionsBySelected<T extends OptionLike>(
+  options: readonly T[],
+  selected: readonly string[],
+  selectedOrder: SelectedOrder = "selected-first",
+): T[] {
+  if (selectedOrder === "stable" || selected.length === 0) {
+    return options as T[];
+  }
+  const selectedSet = new Set(selected);
+  const first = options
+    .filter((o) => selectedSet.has(o.value))
+    .sort((a, b) => a.label.localeCompare(b.label));
+  const rest = options.filter((o) => !selectedSet.has(o.value));
+  return [...first, ...rest];
+}