@multiplatform.one/forms 6.1.0 → 6.4.0

package/src/fields/ToggleGroup/index.tsx

@@ -1,10 +1,26 @@
 import type { ReactNode } from "react";
+import { useState } from "react";
+import {
+  ensureFocusVisibleRing,
+  ensureKeyboardModalityTracking,
+  keyboardFocusRingProps,
+  useReadableTextOn,
+  wasKeyboardFocus,
+} from "@multiplatform.one/theme";
 import type { AnyFormApi } from "../../types";
 import type { FontSizeTokens, LabelProps, SizeTokens } from "tamagui";
-import { SizableText, ToggleGroup as TamaguiToggleGroup, View, XStack, styled } from "tamagui";
+import {
+  SizableText,
+  ToggleGroup as TamaguiToggleGroup,
+  View,
+  XStack,
+  isWeb,
+  styled,
+} from "tamagui";
 import { Skeleton } from "../../Skeleton";
 import { Field, FieldLayout } from "../../fieldLayout";
-import { formButtonColors } from "../../shared/colorRamps";
+import { formButtonColors, formCommonColors } from "../../shared/colorRamps";
+import { warnBareDisabled } from "../../shared/devWarn";
 import {
   getElevationWrapperProps,
   getFieldError,
@@ -71,49 +87,52 @@ function getGroupedBorderRadius(
   const isFirst = index === 0;
   const isLast = index === count - 1;
   if (isFirst && isLast) return { borderRadius: radius };
+  // Logical (start/end) corners so RTL flips the rounding with the items —
+  // physical corners would land rounded edges on interior seams (mirrors
+  // the ControlGroup fix).
   if (orientation === "horizontal") {
     return isFirst
       ? {
-          borderTopLeftRadius: radius,
-          borderBottomLeftRadius: radius,
-          borderTopRightRadius: zero,
-          borderBottomRightRadius: zero,
+          borderStartStartRadius: radius,
+          borderEndStartRadius: radius,
+          borderStartEndRadius: zero,
+          borderEndEndRadius: zero,
         }
       : isLast
         ? {
-            borderTopRightRadius: radius,
-            borderBottomRightRadius: radius,
-            borderTopLeftRadius: zero,
-            borderBottomLeftRadius: zero,
+            borderStartEndRadius: radius,
+            borderEndEndRadius: radius,
+            borderStartStartRadius: zero,
+            borderEndStartRadius: zero,
           }
         : {
             borderRadius: zero,
-            borderTopLeftRadius: zero,
-            borderTopRightRadius: zero,
-            borderBottomLeftRadius: zero,
-            borderBottomRightRadius: zero,
+            borderStartStartRadius: zero,
+            borderStartEndRadius: zero,
+            borderEndStartRadius: zero,
+            borderEndEndRadius: zero,
           };
   }
   return isFirst
     ? {
-        borderTopLeftRadius: radius,
-        borderTopRightRadius: radius,
-        borderBottomLeftRadius: zero,
-        borderBottomRightRadius: zero,
+        borderStartStartRadius: radius,
+        borderStartEndRadius: radius,
+        borderEndStartRadius: zero,
+        borderEndEndRadius: zero,
       }
     : isLast
       ? {
-          borderBottomLeftRadius: radius,
-          borderBottomRightRadius: radius,
-          borderTopLeftRadius: zero,
-          borderTopRightRadius: zero,
+          borderEndStartRadius: radius,
+          borderEndEndRadius: radius,
+          borderStartStartRadius: zero,
+          borderStartEndRadius: zero,
         }
       : {
           borderRadius: zero,
-          borderTopLeftRadius: zero,
-          borderTopRightRadius: zero,
-          borderBottomLeftRadius: zero,
-          borderBottomRightRadius: zero,
+          borderStartStartRadius: zero,
+          borderStartEndRadius: zero,
+          borderEndStartRadius: zero,
+          borderEndEndRadius: zero,
         };
 }
 
@@ -136,6 +155,19 @@ function ToggleItemWithElevation({
   return <ToggleItemFrame {...props} {...groupedRadius} />;
 }
 
+export interface ToggleGroupOption {
+  label: string;
+  value: string;
+  icon?: ReactNode;
+  disabled?: boolean;
+  /**
+   * DG-ST-03 — explains why the item is disabled. Renders as a visible line
+   * under the group wired to the item via `aria-describedby`. A bare
+   * item-level `disabled` without it DEV-warns `bare-disabled`.
+   */
+  disabledReason?: string;
+}
+
 export interface ToggleGroupProps {
   name?: string;
   form?: AnyFormApi;
@@ -146,15 +178,27 @@ export interface ToggleGroupProps {
   error?: string | boolean;
   required?: boolean;
   disabled?: boolean;
+  /**
+   * DG-ST-03 — explains why the whole group is disabled. Takes the helper
+   * slot while disabled (mirrors error-replaces-helper). A bare `disabled`
+   * without it DEV-warns `bare-disabled`.
+   */
+  disabledReason?: string;
   readOnly?: boolean;
   size?: SizeTokens;
   id?: string;
   type?: "single" | "multiple";
   value?: string | string[];
   defaultValue?: string | string[];
+  /**
+   * Canonical change handler, consistent with the rest of the field family.
+   * Prefer this over `onValueChange`.
+   */
+  onChange?: (value: string | string[]) => void;
+  /** @deprecated Use `onChange` instead. Kept as an alias for the tamagui name. */
   onValueChange?: (value: string | string[]) => void;
   onBlur?: (...args: any[]) => void;
-  options?: Array<{ label: string; value: string; icon?: ReactNode }>;
+  options?: ToggleGroupOption[];
   orientation?: "horizontal" | "vertical";
   children?: ReactNode;
   /** When true, renders a skeleton placeholder instead of the toggle group */
@@ -173,12 +217,14 @@ export function ToggleGroup({
   error,
   required,
   disabled,
+  disabledReason,
   readOnly,
   size,
   id: idProp,
   type = "single",
   value,
   defaultValue,
+  onChange,
   onValueChange,
   onBlur,
   options,
@@ -187,14 +233,70 @@ export function ToggleGroup({
   skeleton,
   compact,
 }: ToggleGroupProps) {
-  const { resolvedForm, knobProps, control, text, elevation, id } = useFormField({
+  // Canonical `onChange` and the alias `onValueChange` both fire from the
+  // single emit site below (same reconciliation as Switch).
+  const handleValueChange = (val: string | string[]) => {
+    onChange?.(val);
+    onValueChange?.(val);
+  };
+  const { resolvedForm, knobProps, control, text, elevation, disabledState, id } = useFormField({
     form: formProp,
     id: idProp,
     compact,
   });
+  // UX-018 / Axiom 15: the selected segment fills with `$color8`
+  // (formButtonColors.border.active). Under a bright tint the label inherits
+  // the scheme `$color` (near-white in dark) → 1.24:1 on bright yellow. The
+  // readable label is the paper/ink anchor that reads on the actual fill.
+  const onSelectedLabel = useReadableTextOn("$color8");
+  // Chromium drops keyboard modality when tamagui's group redirects focus to
+  // an item, so :focus-visible/focusVisibleStyle can miss — paint the ring
+  // manually on keyboard-origin focus (see theme keyboardFocusRing).
+  const [kbFocusValue, setKbFocusValue] = useState<string | null>(null);
+  // Roving anchor: while a segment is focused it owns the group's single tab
+  // stop (Shift+Tab exits instead of hopping to the selected segment).
+  const [focusValue, setFocusValue] = useState<string | null>(null);
+  if (isWeb) ensureKeyboardModalityTracking();
   const resolvedValidators = useResolvedValidators(required, validators, label, name);
   const elevationWrapperProps = getElevationWrapperProps(knobProps, elevation);
 
+  // DG-ST-03: disabled groups/items explain themselves or DEV-warn.
+  warnBareDisabled({
+    component: "ToggleGroup",
+    id,
+    disabled: Boolean(disabled),
+    disabledReason,
+    skip: Boolean(skeleton),
+  });
+  for (const option of options ?? []) {
+    warnBareDisabled({
+      component: "ToggleGroup.Item",
+      id: option.value,
+      disabled: Boolean(option.disabled) && !disabled,
+      disabledReason: option.disabledReason ?? disabledReason,
+      skip: Boolean(skeleton),
+    });
+  }
+  // Group reason takes the helper slot while disabled (same one-slot rule as
+  // error-replaces-helper), riding FieldLayout's aria-describedby wiring.
+  const resolvedHelperText = disabled && disabledReason?.trim() ? disabledReason : helperText;
+  // Item reasons render once each under the group; items point at them via
+  // aria-describedby (visible without hover — DG-OVL-05 safe).
+  const uniqueItemReasons = [
+    ...new Set(
+      (options ?? [])
+        .filter((o) => o.disabled && o.disabledReason?.trim())
+        .map((o) => o.disabledReason!.trim()),
+    ),
+  ];
+  const itemReasonIdFor = (reason: string | undefined): string | undefined => {
+    if (!reason?.trim()) return undefined;
+    const index = uniqueItemReasons.indexOf(reason.trim());
+    return index >= 0 ? `${id}-item-reason-${index}` : undefined;
+  };
+  const optionDisabledByValue = (val: string) =>
+    Boolean(options?.find((o) => o.value === val)?.disabled);
+
   // Render skeleton placeholder
   if (skeleton) {
     const optionCount = options?.length ?? 3;
@@ -219,9 +321,29 @@ export function ToggleGroup({
         ? Array.isArray(resolvedValue) && resolvedValue.includes(val)
         : resolvedValue === val;
 
+    // Roving tabindex (single tab stop): tamagui's vendored roving-focus item
+    // hardcodes tabIndex=0 on every segment. Keep exactly one segment in the
+    // page tab order — the focused one while focus is inside the group, else
+    // the first enabled selected one, else the first enabled one; arrows move
+    // within the group.
+    const focusedIdx = focusValue
+      ? options.findIndex((o) => o.value === focusValue && !(disabled || o.disabled))
+      : -1;
+    const firstSelectedEnabled = options.findIndex(
+      (o) => isSelected(o.value) && !(disabled || o.disabled),
+    );
+    const tabStopIndex =
+      focusedIdx >= 0
+        ? focusedIdx
+        : firstSelectedEnabled >= 0
+          ? firstSelectedEnabled
+          : options.findIndex((o) => !(disabled || o.disabled));
     return options.map((option, index) => {
       const groupedRadius = getGroupedBorderRadius(index, count, orientation, radius);
       const selected = isSelected(option.value);
+      const itemDisabled = Boolean(disabled || option.disabled);
+      const itemDescribedBy = option.disabled ? itemReasonIdFor(option.disabledReason) : undefined;
+      const isTabStop = index === tabStopIndex;
       const activeColors = {
         backgroundColor: formButtonColors.border.active,
         borderColor: formButtonColors.border.active,
@@ -233,6 +355,7 @@ export function ToggleGroup({
           elevationWrapperProps={elevationWrapperProps}
           groupedRadius={groupedRadius}
           value={option.value}
+          {...(isWeb ? { tabIndex: isTabStop ? 0 : -1 } : undefined)}
           size={knobProps.sizeToken}
           width="auto"
           height="auto"
@@ -243,38 +366,67 @@ export function ToggleGroup({
           borderWidth={knobProps.borderRadius.borderWidth}
           outlined={knobProps.outlined}
           animation={knobProps.transition}
-          disabled={disabled}
-          {...(selected ? activeColors : undefined)}
-          {...(selected ? { active: true, activeStyle: activeColors } : undefined)}
+          disabled={itemDisabled}
+          {...(itemDescribedBy ? { "aria-describedby": itemDescribedBy } : undefined)}
+          // LC-40 DISABLED-VISIBLE (was DG-ST-03 hand-roll): segments are
+          // text-bearing chrome — a disabled segment drops the live active
+          // fill entirely (the `active` variant expands at its key position
+          // and would beat the wash), so the wash owns the chrome and the
+          // label pins to the lowest AA tier below. A SELECTED disabled
+          // segment takes the recipe's stronger selected tier so the chosen
+          // option stays visible (Axiom 6), not aria-only.
+          {...(selected && !itemDisabled ? activeColors : undefined)}
+          {...(selected && !itemDisabled ? { active: true, activeStyle: activeColors } : undefined)}
+          {...(itemDisabled
+            ? selected
+              ? disabledState.selectedSurfaceKnobProps
+              : disabledState.surfaceKnobProps
+            : undefined)}
           {...(readOnly ? { pointerEvents: "none" as const } : undefined)}
-          hoverStyle={{
-            ...stripRadiusFromStateProps(control.hoverKnobProps),
-            ...(selected
-              ? activeColors
-              : knobProps.outlined
-                ? {
-                    backgroundColor: "transparent",
-                    borderColor: formButtonColors.border.hover,
-                  }
-                : {
-                    backgroundColor: formButtonColors.background.hover,
-                    borderColor: formButtonColors.border.base,
-                  }),
-          }}
-          pressStyle={{
-            ...stripRadiusFromStateProps(control.pressKnobProps),
-            ...(selected
-              ? activeColors
-              : knobProps.outlined
-                ? {
-                    backgroundColor: "transparent",
-                    borderColor: formButtonColors.border.active,
-                  }
-                : {
-                    backgroundColor: formButtonColors.background.active,
-                    borderColor: formButtonColors.border.base,
-                  }),
-          }}
+          // LC-40: no hover/press feedback while disabled — the live styles
+          // repainted the active colors over the wash (dishonest
+          // pressability signal; hovered selected segments fell below AA).
+          // Pinning the wash beats the item's intrinsic hover theme too.
+          hoverStyle={
+            itemDisabled
+              ? selected
+                ? { ...disabledState.selectedSurfaceKnobProps }
+                : { ...disabledState.surfaceKnobProps }
+              : {
+                  ...stripRadiusFromStateProps(control.hoverKnobProps),
+                  ...(selected
+                    ? activeColors
+                    : knobProps.outlined
+                      ? {
+                          backgroundColor: "transparent",
+                          borderColor: formButtonColors.border.hover,
+                        }
+                      : {
+                          backgroundColor: formButtonColors.background.hover,
+                          borderColor: formButtonColors.border.base,
+                        }),
+                }
+          }
+          pressStyle={
+            itemDisabled
+              ? selected
+                ? { ...disabledState.selectedSurfaceKnobProps }
+                : { ...disabledState.surfaceKnobProps }
+              : {
+                  ...stripRadiusFromStateProps(control.pressKnobProps),
+                  ...(selected
+                    ? activeColors
+                    : knobProps.outlined
+                      ? {
+                          backgroundColor: "transparent",
+                          borderColor: formButtonColors.border.active,
+                        }
+                      : {
+                          backgroundColor: formButtonColors.background.active,
+                          borderColor: formButtonColors.border.base,
+                        }),
+                }
+          }
           {...(stripRadiusFromStateProps(control.focusKnobProps) && {
             focusStyle: {
               borderColor: formButtonColors.border.active,
@@ -287,12 +439,29 @@ export function ToggleGroup({
               ...stripRadiusFromStateProps(control.focusVisibleKnobProps),
             },
           })}
+          {...(isWeb
+            ? {
+                onFocus: () => {
+                  setFocusValue(option.value);
+                  if (wasKeyboardFocus()) setKbFocusValue(option.value);
+                },
+                onBlur: () => {
+                  setFocusValue((prev) => (prev === option.value ? null : prev));
+                  setKbFocusValue((prev) => (prev === option.value ? null : prev));
+                },
+              }
+            : undefined)}
+          {...(kbFocusValue === option.value ? keyboardFocusRingProps : undefined)}
         >
           {option.icon}
           <SizableText
             size={knobProps.sizeToken as FontSizeTokens}
             userSelect="none"
             {...knobProps.body}
+            {...(selected && !itemDisabled && onSelectedLabel
+              ? { color: onSelectedLabel }
+              : undefined)}
+            {...(itemDisabled ? disabledState.textKnobProps : undefined)}
             hoverStyle={text.hoverKnobProps}
             pressStyle={text.pressKnobProps}
             focusStyle={text.focusKnobProps}
@@ -314,7 +483,16 @@ 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,
       type,
       ...(type === "single" ? { disableDeactivation: true } : {}),
       ...(isControlled
@@ -322,8 +500,23 @@ export function ToggleGroup({
         : { defaultValue: resolvedValue ?? emptyValue }),
       onValueChange: (val: string | string[]) => {
         if (disabled || readOnly) return;
+        // DG-ST-03 guard: presses on disabled items never change the value
+        // (items stay mounted + explained instead of hiding).
+        if (options) {
+          if (type === "single") {
+            if (typeof val === "string" && optionDisabledByValue(val)) return;
+          } else {
+            const prevArr = Array.isArray(resolvedValue) ? resolvedValue : [];
+            const nextArr = Array.isArray(val) ? val : [];
+            const toggled = [
+              ...nextArr.filter((v) => !prevArr.includes(v)),
+              ...prevArr.filter((v) => !nextArr.includes(v)),
+            ];
+            if (toggled.length === 1 && optionDisabledByValue(toggled[0])) return;
+          }
+        }
         handleChange?.(val);
-        onValueChange?.(val);
+        handleValueChange(val);
       },
       id,
       disabled,
@@ -339,9 +532,22 @@ export function ToggleGroup({
     };
 
     return (
-      <TamaguiToggleGroup {...toggleProps}>
-        {renderContent(resolvedValue ?? emptyValue)}
-      </TamaguiToggleGroup>
+      <>
+        <TamaguiToggleGroup {...toggleProps}>
+          {renderContent(resolvedValue ?? emptyValue)}
+        </TamaguiToggleGroup>
+        {uniqueItemReasons.map((reason, index) => (
+          <SizableText
+            key={reason}
+            id={`${id}-item-reason-${index}`}
+            size="$1"
+            color={formCommonColors.muted}
+            data-mp-disabled-reason="true"
+          >
+            {reason}
+          </SizableText>
+        ))}
+      </>
     );
   };
 
@@ -353,9 +559,12 @@ export function ToggleGroup({
         labelProps={labelProps}
         error={error}
         required={required}
-        helperText={helperText}
+        helperText={resolvedHelperText}
         size={size}
         knobProps={knobProps}
+        // LC-40: FieldLayout owns the dimWhole assembly dim (keepLabel pins
+        // the sibling label/helper readable) — it needs the disabled state.
+        disabled={disabled}
       >
         {renderToggleGroup(value ?? defaultValue, value !== undefined, undefined, onBlur, !!error)}
       </FieldLayout>
@@ -378,9 +587,11 @@ export function ToggleGroup({
             labelProps={labelProps}
             error={resolvedError}
             required={required}
-            helperText={helperText}
+            helperText={resolvedHelperText}
             size={size}
             knobProps={knobProps}
+            // LC-40: see standalone branch — FieldLayout carries dimWhole.
+            disabled={disabled}
           >
             {renderToggleGroup(
               value !== undefined ? value : (field.state.value as string | string[]),

package/src/formSpacing.ts

@@ -0,0 +1,15 @@
+/**
+ * Form rhythm tokens (DG-FORM-06): section gap must exceed field gap.
+ *
+ * Mapped to Tamagui space tokens in this repo:
+ * - `$4` ≈ 18px — field-to-field
+ * - `$8` ≈ 46px — section-to-section (clearly larger)
+ *
+ * Fluent/Windows guidance is 24 / 48; our token ramp is the nearest encoding
+ * without inventing raw pixel knobs.
+ */
+export const formFieldGap = "$4" as const;
+export const formSectionGap = "$8" as const;
+
+/** Default readable form width (DG-FORM-08 ~480–600px). */
+export const formReadableMaxWidth = 560;

package/src/hooks/useFocusManagement.spec.tsx

@@ -6,6 +6,8 @@ import { act } from "@testing-library/react";
 import { beforeAll, describe, expect, it, vi } from "vitest";
 import { renderWithProviders } from "@multiplatform.one/test-utils";
 import {
+  focusFieldTarget,
+  focusFirstInvalid,
   useFocusManagement,
   useOTPFocusManagement,
   useSearchableDropdownFocus,
@@ -287,3 +289,36 @@ describe("useSearchableDropdownFocus", () => {
     renderWithProviders(<TestComponent />);
   });
 });
+
+describe("focusFirstInvalid / focusFieldTarget", () => {
+  it("focuses the first aria-invalid control", () => {
+    const form = document.createElement("form");
+    const ok = document.createElement("input");
+    ok.id = "ok";
+    const bad = document.createElement("input");
+    bad.id = "bad";
+    bad.setAttribute("aria-invalid", "true");
+    form.append(ok, bad);
+    document.body.appendChild(form);
+
+    const focused = focusFirstInvalid(form);
+    expect(focused?.id).toBe("bad");
+    expect(mockFocus).toHaveBeenCalled();
+    form.remove();
+  });
+
+  it("resolves by id then falls back to first invalid", () => {
+    const form = document.createElement("form");
+    const email = document.createElement("input");
+    email.id = "email";
+    const other = document.createElement("input");
+    other.id = "other";
+    other.setAttribute("aria-invalid", "true");
+    form.append(email, other);
+    document.body.appendChild(form);
+
+    expect(focusFieldTarget(form, { id: "email" })?.id).toBe("email");
+    expect(focusFieldTarget(form, { id: "missing", name: "nope" })?.id).toBe("other");
+    form.remove();
+  });
+});

package/src/hooks/useFocusManagement.ts

@@ -1,6 +1,70 @@
 import { type RefObject, useCallback, useEffect, useRef, useState } from "react";
 import { isWeb } from "tamagui";
 
+/**
+ * Focus the first invalid control inside a container (`aria-invalid="true"`).
+ * Used after failed submit / ErrorSummary jump links (DG-VAL-02).
+ */
+export function focusFirstInvalid(container: HTMLElement | null | undefined): HTMLElement | null {
+  if (!isWeb || !container || typeof container.querySelector !== "function") return null;
+  const el = container.querySelector(
+    '[aria-invalid="true"]:not([disabled]):not([aria-disabled="true"])',
+  ) as HTMLElement | null;
+  if (!el || typeof el.focus !== "function") return null;
+  el.focus();
+  el.scrollIntoView?.({ block: "nearest", behavior: "smooth" });
+  return el;
+}
+
+/**
+ * Resolve and focus a field by DOM id, then name attribute, then first invalid.
+ */
+export function focusFieldTarget(
+  container: HTMLElement | null | undefined,
+  target: { id?: string; name?: string },
+): HTMLElement | null {
+  if (!isWeb || !container) return null;
+
+  const tryFocus = (el: Element | null | undefined): HTMLElement | null => {
+    if (!el || !(el instanceof HTMLElement) || typeof el.focus !== "function") return null;
+    // Prefer a nested focusable control when the match is a wrapper.
+    const nested = el.matches?.(
+      "input, textarea, select, button, [tabindex]:not([tabindex='-1']), [contenteditable='true']",
+    )
+      ? el
+      : (el.querySelector?.(
+          "input:not([disabled]), textarea:not([disabled]), select:not([disabled]), [tabindex]:not([tabindex='-1'])",
+        ) as HTMLElement | null);
+    const focusable = nested ?? el;
+    focusable.focus();
+    focusable.scrollIntoView?.({ block: "nearest", behavior: "smooth" });
+    return focusable;
+  };
+
+  if (target.id) {
+    const byId =
+      (typeof document !== "undefined" ? document.getElementById(target.id) : null) ??
+      container.querySelector(`#${cssEscape(target.id)}`);
+    const focused = tryFocus(byId);
+    if (focused) return focused;
+  }
+
+  if (target.name) {
+    const byName = container.querySelector(`[name="${cssEscape(target.name)}"]`);
+    const focused = tryFocus(byName);
+    if (focused) return focused;
+  }
+
+  return focusFirstInvalid(container);
+}
+
+function cssEscape(value: string): string {
+  if (typeof CSS !== "undefined" && typeof CSS.escape === "function") {
+    return CSS.escape(value);
+  }
+  return value.replace(/[^a-zA-Z0-9_-]/g, "\\$&");
+}
+
 export interface FocusManagementOptions {
   /**
    * Whether to trap focus within the container