@12-apps/ui 6.17.0 → 6.18.0

package/src/components/form/Button/Button.native.tsx

@@ -0,0 +1,339 @@
+import * as React from 'react';
+import {
+  ActivityIndicator,
+  Animated,
+  Easing,
+  Platform,
+  Pressable,
+  StyleSheet,
+  Text as RNText,
+  View,
+  type GestureResponderEvent,
+  type PressableStateCallbackType,
+  type StyleProp,
+  type TextStyle,
+  type ViewStyle,
+} from 'react-native';
+
+import { resolveButtonProps } from './Button.helpers';
+import {
+  BUTTON_FONT_WEIGHT,
+  BUTTON_ICON_GAP_UNITS,
+  BUTTON_LINE_HEIGHT,
+  BUTTON_RADIUS_UNITS,
+  BUTTON_SIZES,
+  BUTTON_SPINNER_SIZE,
+  BUTTON_WASH_ALPHA,
+  GLASS_BACKGROUND_ALPHA,
+  GLASS_BACKGROUND_ALPHA_PRESSED,
+  GLASS_BORDER_ALPHA,
+  GLOW_INNER_ALPHA,
+  GLOW_RADIUS,
+  ICON_ONLY_PADDING,
+  PULSE_ALPHA,
+  PULSE_DURATION_MS,
+  PULSE_SPREAD,
+  buttonPalette,
+  gradientStops,
+  quietInk,
+} from './Button.metrics';
+import type { ButtonProps, ButtonVariant } from './Button.types.native';
+import { childTestId, resolveTestId, withoutTestIdProps } from '../../../platform/test-id';
+import { useUiTheme } from '../../../provider/use-ui-theme.native';
+import { alpha } from '../../../tokens/color';
+import type { ColorValue, SizeValue } from '../../../tokens/vocabulary';
+import type { UiPaletteColor, UiTheme } from '../../../tokens/theme';
+
+/** MUI's `min-width` for a button that carries a label. */
+const MIN_WIDTH = 64;
+
+interface Paint {
+  container: ViewStyle;
+  pressed: ViewStyle;
+  label: TextStyle;
+}
+
+/**
+ * What the web's `VARIANT_STYLES` paint, as three React Native styles: at rest,
+ * while pressed (the web's `:hover`, which touch has no equivalent of), and the
+ * label. Same palette arithmetic, same alphas.
+ *
+ * `gradient` is the one honest gap: React Native core has no gradient fill, so
+ * it paints the gradient's first stop. A host wanting the real thing adds a
+ * gradient library; the parity ledger records this.
+ */
+function paintFor(
+  theme: UiTheme,
+  variant: ButtonVariant,
+  color: ColorValue,
+  palette: UiPaletteColor,
+  active: boolean,
+): Paint {
+  const wash = alpha(palette.main, BUTTON_WASH_ALPHA);
+  switch (variant) {
+    case 'outline':
+      return {
+        container: { backgroundColor: 'transparent', borderWidth: 1, borderColor: palette.main },
+        pressed: { backgroundColor: wash, borderColor: palette.dark },
+        label: { color: palette.main },
+      };
+    case 'ghost':
+      return {
+        container: { backgroundColor: 'transparent' },
+        pressed: { backgroundColor: wash },
+        label: { color: quietInk(theme, palette) },
+      };
+    case 'text':
+      return {
+        container: { backgroundColor: active ? wash : 'transparent' },
+        pressed: { backgroundColor: wash },
+        label: { color: quietInk(theme, palette) },
+      };
+    case 'glass':
+      return {
+        container: {
+          backgroundColor: alpha(theme.palette.background.paper, GLASS_BACKGROUND_ALPHA),
+          borderWidth: 1,
+          borderColor: alpha(theme.palette.divider, GLASS_BORDER_ALPHA),
+        },
+        pressed: { backgroundColor: alpha(theme.palette.background.paper, GLASS_BACKGROUND_ALPHA_PRESSED) },
+        label: { color: palette.main },
+      };
+    case 'gradient': {
+      const [from, to] = gradientStops(theme, color, palette);
+      return {
+        container: { backgroundColor: from },
+        pressed: { backgroundColor: to },
+        label: { color: '#fff' },
+      };
+    }
+    default:
+      return {
+        container: { backgroundColor: palette.main },
+        pressed: { backgroundColor: palette.dark },
+        label: { color: palette.contrastText || '#fff' },
+      };
+  }
+}
+
+/** MUI's disabled treatment per variant family, so a disabled button reads as one on both sides. */
+function disabledPaint(theme: UiTheme, variant: ButtonVariant): Paint {
+  const filled = variant === 'solid' || variant === 'gradient' || variant === 'glass';
+  return {
+    container: filled
+      ? { backgroundColor: theme.palette.action.disabledBackground, borderWidth: 0 }
+      : variant === 'outline'
+        ? { backgroundColor: 'transparent', borderWidth: 1, borderColor: theme.palette.action.disabledBackground }
+        : { backgroundColor: 'transparent' },
+    pressed: {},
+    label: { color: theme.palette.action.disabled },
+  };
+}
+
+function sizeStyle(theme: UiTheme, size: SizeValue, iconOnly: boolean, hasIcon: boolean): ViewStyle {
+  const metrics = BUTTON_SIZES[size];
+  if (iconOnly) {
+    return { padding: ICON_ONLY_PADDING[size], minWidth: 0 };
+  }
+  return {
+    paddingVertical: metrics.paddingVertical,
+    paddingHorizontal: metrics.paddingHorizontal,
+    minWidth: MIN_WIDTH,
+    gap: hasIcon ? theme.spacing(BUTTON_ICON_GAP_UNITS) : undefined,
+  };
+}
+
+function glowStyle(palette: UiPaletteColor): ViewStyle {
+  return Platform.select<ViewStyle>({
+    android: { elevation: 8 },
+    default: {
+      shadowColor: palette.main,
+      shadowOpacity: GLOW_INNER_ALPHA,
+      shadowRadius: GLOW_RADIUS,
+      shadowOffset: { width: 0, height: 0 },
+    },
+  });
+}
+
+/** The web's `::after` pulse ring: a looped scale-and-fade behind the button. */
+function Pulse({ color, radius, testID }: { color: string; radius: number; testID: string }): React.JSX.Element {
+  const progress = React.useRef(new Animated.Value(0)).current;
+
+  React.useEffect(() => {
+    const loop = Animated.loop(
+      Animated.timing(progress, {
+        toValue: 1,
+        duration: PULSE_DURATION_MS,
+        easing: Easing.out(Easing.ease),
+        useNativeDriver: Platform.OS !== 'web',
+      }),
+    );
+    loop.start();
+    return () => loop.stop();
+  }, [progress]);
+
+  return (
+    <Animated.View
+      testID={testID}
+      aria-hidden
+      style={[
+        StyleSheet.absoluteFill,
+        {
+          pointerEvents: 'none',
+          borderRadius: radius,
+          backgroundColor: color,
+          opacity: progress.interpolate({ inputRange: [0, 0.7, 1], outputRange: [PULSE_ALPHA, 0, 0] }),
+          transform: [
+            { scale: progress.interpolate({ inputRange: [0, 0.7, 1], outputRange: [1, 1 + PULSE_SPREAD / 40, 1] }) },
+          ],
+        },
+      ]}
+    />
+  );
+}
+
+/**
+ * A string or number child is the label and gets the label style; anything
+ * else is rendered as given. No test id of its own: the web puts none on the
+ * label, and a shared story that counts `/perf-button-/` must count buttons.
+ */
+function renderChildren(children: React.ReactNode, label: TextStyle): React.ReactNode {
+  return React.Children.map(children, (child) =>
+    typeof child === 'string' || typeof child === 'number' ? (
+      <RNText style={label} numberOfLines={1}>
+        {child}
+      </RNText>
+    ) : (
+      child
+    ),
+  );
+}
+
+type ResolvedProps = ReturnType<typeof resolveButtonProps<ButtonProps>>;
+
+interface ButtonLook {
+  inactive: boolean;
+  palette: UiPaletteColor;
+  radius: number;
+  label: TextStyle;
+  container: (state: PressableStateCallbackType) => StyleProp<ViewStyle>;
+}
+
+/**
+ * Everything the button paints, decided once per render from the resolved
+ * props and the theme. Kept out of the component so the component reads as
+ * structure — what renders where — and this reads as arithmetic.
+ */
+function buttonLook(theme: UiTheme, props: ResolvedProps): ButtonLook {
+  const { variant, color, size, loading, icon, children, glow, pulse, active, disabled, style } = props;
+  const palette = buttonPalette(theme, color);
+  const iconOnly = !loading && icon != null && children == null;
+  const inactive = Boolean(disabled) || loading;
+  const paint = inactive ? disabledPaint(theme, variant) : paintFor(theme, variant, color, palette, active);
+  const radius = theme.spacing(BUTTON_RADIUS_UNITS);
+  const metrics = BUTTON_SIZES[size];
+  // The web button is `overflow: hidden` (its ripple needs it) unless the pulse
+  // ring turns it visible; on native the glow's shadow needs it visible too,
+  // because a view's own shadow is clipped by its own overflow there.
+  const overflow: ViewStyle['overflow'] = pulse || glow ? 'visible' : 'hidden';
+  const sized = sizeStyle(theme, size, iconOnly, icon != null && !loading);
+  const glowing = glow && !inactive ? glowStyle(palette) : null;
+
+  return {
+    inactive,
+    palette,
+    radius,
+    label: {
+      fontFamily: theme.typography.fontFamily,
+      fontSize: metrics.fontSize,
+      lineHeight: metrics.fontSize * BUTTON_LINE_HEIGHT,
+      fontWeight: String(BUTTON_FONT_WEIGHT) as TextStyle['fontWeight'],
+      textAlign: 'center',
+      ...paint.label,
+    },
+    container: (state) => [
+      styles.base,
+      { borderRadius: radius, overflow },
+      sized,
+      paint.container,
+      state.pressed && !inactive ? paint.pressed : null,
+      glowing,
+      style,
+    ],
+  };
+}
+
+/** The spinner that replaces the label while loading; `role` comes from react-native's ActivityIndicator. */
+function Spinner({ color, testID }: { color: string; testID: string }): React.JSX.Element {
+  return (
+    <ActivityIndicator
+      size={Platform.OS === 'ios' ? 'small' : BUTTON_SPINNER_SIZE}
+      color={color}
+      testID={testID}
+      accessibilityLabel="loading"
+    />
+  );
+}
+
+export const Button = React.forwardRef<View, ButtonProps>((rawProps, ref) => {
+  const resolved = resolveButtonProps(rawProps);
+  const { loading, icon, iconPosition, pulse, ripple, children, onClick, onPress, ...others } = resolved;
+  const theme = useUiTheme();
+  const look = buttonLook(theme, resolved);
+
+  // The shared stories pass `'data-testid'` as a plain prop; honour it here and
+  // keep all three spellings off the element (react-native-web would drop them).
+  const testId = resolveTestId(others, 'button');
+  const idFor = (suffix: string) => childTestId(others, suffix, 'button');
+  const rest = withoutTestIdProps(others);
+  // `buttonLook` consumed these; they are not Pressable props.
+  const { variant: _v, color: _c, size: _s, glow: _g, active: _a, disabled: _d, style: _st, ...pressable } = rest;
+
+  const handlePress = (event: GestureResponderEvent): void => {
+    onClick?.(event);
+    onPress?.(event);
+  };
+
+  const iconNode =
+    !loading && icon ? (
+      <View style={styles.icon} testID={idFor('icon')}>
+        {icon}
+      </View>
+    ) : null;
+
+  return (
+    <Pressable
+      ref={ref}
+      role="button"
+      aria-disabled={look.inactive}
+      aria-busy={loading}
+      disabled={look.inactive}
+      onPress={handlePress}
+      android_ripple={ripple && !look.inactive ? { color: alpha(look.palette.main, 0.2), borderless: false } : undefined}
+      style={look.container}
+      testID={testId}
+      {...pressable}
+    >
+      {pulse && !look.inactive ? <Pulse color={look.palette.main} radius={look.radius} testID={idFor('pulse')} /> : null}
+      {iconPosition === 'left' ? iconNode : null}
+      {loading ? <Spinner color={look.label.color as string} testID={idFor('loading')} /> : renderChildren(children, look.label)}
+      {iconPosition === 'right' ? iconNode : null}
+    </Pressable>
+  );
+});
+
+Button.displayName = 'Button';
+
+const styles = StyleSheet.create({
+  base: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    justifyContent: 'center',
+    alignSelf: 'flex-start',
+    position: 'relative',
+  },
+  icon: {
+    alignItems: 'center',
+    justifyContent: 'center',
+  },
+});

package/src/components/form/Button/Button.styles.ts

@@ -1,6 +1,9 @@
 import { alpha, darken, keyframes, lighten } from '@mui/material/styles/index.js';
 import type { CSSObject, Theme } from '@mui/material/styles/index.js';
 
+import { BUTTON_SIZES, ICON_ONLY_PADDING as ICON_ONLY_PADDING_PX } from './Button.metrics';
+import { px } from '../../../tokens/theme';
+
 // Define pulse animation globally
 const pulseAnimation = keyframes`
   0% {
@@ -62,16 +65,17 @@ export const getColorFromTheme = (theme: Theme, color: string): ColorPalette =>
   };
 };
 
-/** What an unrecognised size falls back to, named so indexing can never be undefined. */
-const DEFAULT_SIZE: CSSObject = { padding: '8px 16px', fontSize: '1rem' };
+// Derived from `Button.metrics.ts`, which the native `Button` reads too — one
+// table, so a size cannot differ between the renderers.
+const SIZE_MAP: Record<string, CSSObject> = Object.fromEntries(
+  Object.entries(BUTTON_SIZES).map(([size, m]) => [
+    size,
+    { padding: `${m.paddingVertical}px ${m.paddingHorizontal}px`, fontSize: px(m.fontSize) },
+  ]),
+);
 
-const SIZE_MAP: Record<string, CSSObject> = {
-  xs: { padding: '2px 8px', fontSize: '0.75rem' },
-  sm: { padding: '6px 12px', fontSize: '0.875rem' },
-  md: DEFAULT_SIZE,
-  lg: { padding: '10px 20px', fontSize: '1.125rem' },
-  xl: { padding: '12px 24px', fontSize: '1.25rem' },
-};
+/** What an unrecognised size falls back to, named so indexing can never be undefined. */
+const DEFAULT_SIZE: CSSObject = SIZE_MAP.md as CSSObject;
 
 /**
  * A BUTTON THAT IS ONLY AN ICON IS SQUARE.
@@ -86,13 +90,9 @@ const SIZE_MAP: Record<string, CSSObject> = {
  * Derived, not declared: a button with an `icon` and no children can only be an
  * icon button, so no consumer has to opt in and none can forget to.
  */
-const ICON_ONLY_PADDING: Record<string, string> = {
-  xs: '2px',
-  sm: '5px',
-  md: '7px',
-  lg: '9px',
-  xl: '11px',
-};
+const ICON_ONLY_PADDING: Record<string, string> = Object.fromEntries(
+  Object.entries(ICON_ONLY_PADDING_PX).map(([size, padding]) => [size, `${padding}px`]),
+);
 
 const iconOnlySize = (size: string): CSSObject => ({
   minWidth: 0,

package/src/components/form/Button/Button.tsx

@@ -4,6 +4,7 @@ import { styled } from '@mui/material/styles/index.js';
 import * as React from 'react';
 
 import { resolveButtonProps } from './Button.helpers';
+import { childTestId, resolveTestId, withoutTestIdProps } from '../../../platform/test-id';
 import {
   buttonEmphasisStyles,
   buttonVariantStyles,
@@ -88,11 +89,13 @@ export const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
       onClick,
       onFocus,
       onBlur,
-      dataTestId,
-      ...props
+      ...others
     } = resolveButtonProps(rawProps);
-    const testId = (suffix: string) =>
-      dataTestId ? `${dataTestId}-${suffix}` : `button-${suffix}`;
+    // Every spelling of the test id the shared contract allows, mapped to the
+    // one the DOM reads; the native Button does the same in reverse.
+    const ownTestId = resolveTestId(others, 'button');
+    const testId = (suffix: string) => childTestId(others, suffix, 'button');
+    const props = withoutTestIdProps(others);
 
     // Wrap icon with testId if provided
     const iconWithTestId =
@@ -122,7 +125,7 @@ export const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
         onFocus={onFocus}
         onBlur={onBlur}
         sx={buttonSize(size, iconOnly)}
-        data-testid={dataTestId || 'button'}
+        data-testid={ownTestId}
         {...props}
         className={mergedClassName}
       >

package/src/components/form/Button/Button.types.native.ts

@@ -0,0 +1,27 @@
+import type {
+  GestureResponderEvent,
+  NativeSyntheticEvent,
+  PressableProps,
+  StyleProp,
+  TargetedEvent,
+  ViewStyle,
+} from 'react-native';
+
+import type { ButtonBaseProps } from './Button.base';
+
+export type { ButtonBaseProps, ButtonVariant } from './Button.base';
+
+/**
+ * The native `Button`. `onClick` keeps its web name — the 179 call sites in
+ * the origin apps spell it that way and a shared screen should not have to
+ * know which renderer it is on — and `onPress` is accepted too, because that is
+ * what a React Native developer will reach for. Both fire.
+ */
+export type ButtonProps = ButtonBaseProps &
+  Omit<PressableProps, keyof ButtonBaseProps | 'style' | 'onPress' | 'onFocus' | 'onBlur'> & {
+    onClick?: (event: GestureResponderEvent) => void;
+    onPress?: (event: GestureResponderEvent) => void;
+    onFocus?: (event: NativeSyntheticEvent<TargetedEvent>) => void;
+    onBlur?: (event: NativeSyntheticEvent<TargetedEvent>) => void;
+    style?: StyleProp<ViewStyle>;
+  };

package/src/components/form/Button/Button.types.ts

@@ -1,75 +1,25 @@
-import type { ColorValue, SizeValue } from '../../../tokens/scales';
 import type { ButtonProps as MuiButtonProps } from '@mui/material/Button/index.js';
 import type * as React from 'react';
 
-export interface ButtonProps extends Omit<MuiButtonProps, 'variant' | 'color' | 'size'> {
-  /**
-   * The variant of the button
-   */
-  variant?: 'solid' | 'outline' | 'ghost' | 'text' | 'glass' | 'gradient';
+import type { ButtonBaseProps } from './Button.base';
 
-  /**
-   * The color of the button
-   */
-  color?: ColorValue;
-  
-  /**
-   * The size of the button
-   */
-  size?: SizeValue;
-  
-  /**
-   * Whether the button is in loading state
-   */
-  loading?: boolean;
-  
-  /**
-   * Icon to display in the button
-   */
-  icon?: React.ReactNode;
-  
-  /**
-   * Position of the icon
-   */
-  iconPosition?: 'left' | 'right';
-
-  /**
-   * Whether the button should have a glow effect
-   */
-  glow?: boolean;
-  
-  /**
-   * Whether the button should have a pulse animation
-   */
-  pulse?: boolean;
-  
-  /**
-   * Whether to show ripple effect on click
-   */
-  ripple?: boolean;
-
-  /**
-   * Whether the button is in active state
-   */
-  active?: boolean;
+export type { ButtonBaseProps, ButtonVariant } from './Button.base';
 
+export interface ButtonProps
+  extends ButtonBaseProps,
+    Omit<MuiButtonProps, 'variant' | 'color' | 'size' | keyof ButtonBaseProps> {
   /**
    * Click handler
    */
   onClick?: React.MouseEventHandler<HTMLButtonElement>;
-  
+
   /**
    * Focus handler
    */
   onFocus?: React.FocusEventHandler<HTMLButtonElement>;
-  
+
   /**
    * Blur handler
    */
   onBlur?: React.FocusEventHandler<HTMLButtonElement>;
-
-  /**
-   * Test ID for testing purposes
-   */
-  dataTestId?: string;
-}
+}

package/src/components/form/Button/index.native.ts

@@ -0,0 +1,2 @@
+export { Button } from './Button.native';
+export type { ButtonBaseProps, ButtonProps, ButtonVariant } from './Button.types.native';

package/src/components/form/Button/index.ts

@@ -1,2 +1,2 @@
 export { Button } from './Button';
-export type { ButtonProps } from './Button.types';
+export type { ButtonBaseProps, ButtonProps, ButtonVariant } from './Button.types';

package/src/components/form/Form/Form.md

@@ -85,7 +85,7 @@ Default layout with fields stacked vertically:
 ```
 
 ### Horizontal Layout
-Labels positioned horizontally beside inputs:
+Intended to put labels beside their inputs:
 ```tsx
 <Form variant="horizontal">
   <FormField name="field1" label="Field 1">
@@ -94,6 +94,13 @@ Labels positioned horizontally beside inputs:
 </Form>
 ```
 
+> **Not wired up yet.** `Form` accepts the variant, but nothing carries it down
+> to `FormField` — `FormFieldProps` has no `variant` — so a horizontal form
+> currently draws ordinary vertical rows. The field's styled wrapper still
+> keeps the horizontal branch, scoped to the column axis (see
+> [Row spacing](#row-spacing)), so wiring it up later is a wiring job rather
+> than a re-derivation of the spacing.
+
 ### Inline Layout
 All elements in a single row:
 ```tsx
@@ -103,6 +110,44 @@ All elements in a single row:
 </Form>
 ```
 
+## Row spacing
+
+A label sits **4px** above its control, and exactly one thing puts it there:
+`FormLabel`'s own `marginBottom` (`theme.spacing(0.5)`). `FormMessage` mirrors it
+with the same 4px `marginTop` below the control, so a row reads 4 / control / 4.
+
+`FormField` deliberately adds **nothing** to that. It used to: the wrapper was a
+flex column with `gap: theme.spacing(1)`, and in a column a gap and a margin add
+up — 8 + 4 = 12px, three times what every other user of `FormLabel` draws.
+`CepField`, `CategorySelect`, `CreatableSelect`, the `total-form` fields and
+`@12-apps/discounts`' builders all put a bare `FormLabel` straight inside a
+`FormControl`, which has no gap of its own, so the label's margin is the whole
+of their spacing at 4px. `FormField` was the only one of them that disagreed.
+
+That is a claim about `FormLabel`'s callers, not about every labelled control in
+the package: `Textarea` labels itself through MUI's `InputLabel` at
+`theme.spacing(1)` and draws 8px. It shares no code with `FormLabel`, so it is a
+separate inconsistency — worth settling one day, and no argument for keeping a
+second spacing mechanism here.
+
+Eight pixels a row is invisible on one field and decisive on six. Measured in
+Chromium at 320x568 — the smallest supported viewport — a six-field address form
+put its submit button 41px below the fold.
+
+**There is no `spacing` prop, and that is the answer rather than an omission.**
+A knob here would be a second place to state a decision that already has one, and
+its default would have to be the 4px every other `FormLabel` row draws — so the
+only thing it would buy is the ability to disagree with them. A row that
+genuinely needs more air gets it from the container: `Form`'s own `spacing` sets
+the distance *between* fields, and a caller composing `FormControl` +
+`FormLabel` by hand can space them however it likes.
+
+`variant="horizontal"` keeps a `columnGap` rather than a `gap`. That branch is
+unreachable today (see [Horizontal Layout](#horizontal-layout)), and the axis is
+the reason it is kept rather than deleted: with the label beside the control a
+horizontal gap and a vertical margin are orthogonal, where a `gap` shorthand
+would put the 8px straight back on the row axis as soon as a field wrapped.
+
 ## Validation
 
 Display validation errors and helper text:

package/src/components/form/Form/Form.tsx

@@ -54,6 +54,45 @@ export const Form = React.forwardRef<HTMLFormElement, FormProps>(
 
 Form.displayName = 'Form';
 
+/**
+ * NO ROW GAP HERE, and that is the fix rather than an omission.
+ *
+ * `FormLabel` already carries `marginBottom: theme.spacing(0.5)` — 4px — and it
+ * carries it because it has to: every OTHER user of it (`CepField`,
+ * `CategorySelect`, `CreatableSelect`, the three `total-form` fields, five of
+ * `@12-apps/discounts`' builders and the host's own `currency-field`) puts a
+ * bare `FormLabel` straight inside a `FormControl`, which is a plain block box
+ * with no gap of its own. There, the label's own margin is the ONLY thing
+ * between the label and the control.
+ *
+ * A `gap: theme.spacing(1)` here was a second mechanism for that one job, and in
+ * a column the two ADD: 8px + 4px put `FormField` at 12px where every one of
+ * those siblings sits at 4px. Measured in Chromium at 320x568 on a consuming
+ * app's six-field delivery address form, the 8px a row it added pushed the
+ * submit button from 561px to 609px — 41px below the fold of the smallest
+ * supported phone, i.e. a checkout whose primary action is off-screen.
+ *
+ * That claim is about `FormLabel`'s own callers, not about the whole package:
+ * `Textarea` labels its control through MUI's `InputLabel` at
+ * `theme.spacing(1)` and still draws 8px. It composes nothing out of
+ * `FormLabel`, so it is a separate inconsistency rather than a reason to keep
+ * a second spacing here.
+ *
+ * ## The `columnGap` is scaffolding, and currently unreachable
+ *
+ * `FormFieldProps` has no `variant` and `FormField` passes none, so `variant`
+ * is ALWAYS undefined and every branch below resolves to the vertical shape.
+ * `Form` accepts `variant="horizontal"` and `Form.md` documents it as "labels
+ * beside inputs", but nothing carries that variant down to the field — so a
+ * horizontal form draws vertical rows today. That gap is older than this
+ * change and fixing it is a feature, not a spacing fix.
+ *
+ * The branch is kept, scoped to the COLUMN axis, so that whoever does wire it
+ * up inherits the right answer: with the label beside the control, a horizontal
+ * gap and a vertical margin are orthogonal and nothing double-counts. A `gap`
+ * shorthand there would put the 8px back on the row axis the moment a field
+ * wrapped.
+ */
 const StyledFormField = styled(Box, {
   shouldForwardProp: (prop) => prop !== 'variant',
 })<{ variant?: 'vertical' | 'horizontal' }>(
@@ -61,7 +100,7 @@ const StyledFormField = styled(Box, {
     display: variant === 'horizontal' ? 'grid' : 'flex',
     flexDirection: variant === 'horizontal' ? undefined : 'column',
     gridTemplateColumns: variant === 'horizontal' ? '200px 1fr' : undefined,
-    gap: theme.spacing(1),
+    columnGap: variant === 'horizontal' ? theme.spacing(1) : undefined,
     alignItems: variant === 'horizontal' ? 'center' : undefined,
   }),
 );