@multiplatform.one/forms 7.76.0 → 7.77.0

package/src/DescriptionList/index.tsx

@@ -69,6 +69,24 @@ export interface DescriptionListItem {
    * middle so both ends stay legible, with a copy action (LC-169).
    */
   identifier?: boolean;
+  /**
+   * An icon-only fact (LC-169): no visible label. The term becomes the
+   * glyph's accessible name and its tooltip, and the value leads after the
+   * glyph. Only for a glyph that is unambiguous in context (a realm's shield
+   * beside "master", a link beside a URL).
+   */
+  labelHidden?: boolean;
+  /**
+   * Replaces an identifier row's copy button, e.g. a menu that also copies
+   * values derived from this one.
+   */
+  copyAction?: ReactNode;
+  /**
+   * Trailing content that belongs to this fact, on its line (iOS's detail
+   * accessory): a realm's checks as a glyph cluster beside the realm, so a
+   * card needs no row of its own for them (LC-169).
+   */
+  accessory?: ReactNode;
   /** Optional per-row Change action. */
   onChange?: () => void;
   changeLabel?: string;
@@ -219,6 +237,29 @@ function TermLead({ row, inline = false }: { row: DescriptionListItem; inline?:
   );
 }
 
+function termText(term: ReactNode): string | undefined {
+  return typeof term === "string" || typeof term === "number" ? String(term) : undefined;
+}
+
+/** The glyph of an icon-only fact: it carries the term as its name and tooltip. */
+function FactGlyph({ row }: { row: DescriptionListItem }) {
+  const ink = useGlyphColor("$textMuted");
+  const name = termText(row.term);
+  return (
+    <View
+      data-mpo-description-list-glyph=""
+      role="img"
+      aria-label={name}
+      flexShrink={0}
+      {...(isWeb
+        ? ({ title: name, style: ink ? { color: ink } : undefined } as Record<string, unknown>)
+        : { accessible: true })}
+    >
+      <IconSlot icon={row.icon} color={ink} size={16} />
+    </View>
+  );
+}
+
 function ChangeAction({ onChange, label }: { onChange: () => void; label?: string }) {
   return (
     <View data-mpo-description-list-action="" alignItems="flex-start" justifyContent="flex-end">
@@ -254,7 +295,7 @@ export function middleSplit(text: string): [string, string] {
  */
 const CopyResultContext = createContext<((ok: boolean) => void) | undefined>(undefined);
 
-function IdentifierValue({ text }: { text: string }) {
+function IdentifierValue({ text, action }: { text: string; action?: ReactNode }) {
   const onCopyResult = useContext(CopyResultContext);
   const { knobProps } = useResolvedKnobs();
   const [head, tail] = middleSplit(text);
@@ -287,14 +328,16 @@ function IdentifierValue({ text }: { text: string }) {
           {text}
         </Text>
       )}
-      <Button
-        nested
-        chromeless
-        flexShrink={0}
-        icon={<CopyIcon />}
-        aria-label={t("Copy to clipboard")}
-        onPress={() => void copy()}
-      />
+      {action ?? (
+        <Button
+          nested
+          chromeless
+          flexShrink={0}
+          icon={<CopyIcon />}
+          aria-label={t("Copy to clipboard")}
+          onPress={() => void copy()}
+        />
+      )}
     </XStack>
   );
 }
@@ -311,7 +354,7 @@ function ValueSlot({ row, trailing = false }: { row: DescriptionListItem; traili
           row.children
         )
       ) : row.identifier && row.value != null && row.value !== "" ? (
-        <IdentifierValue text={String(row.value)} />
+        <IdentifierValue text={String(row.value)} action={row.copyAction} />
       ) : (
         // FieldDisplay grows on flex 1 from a zero basis; in a column with no
         // height of its own that collapsed it to 0 and the next rule ran
@@ -355,7 +398,8 @@ function DescriptionListRowView({
     <View data-mpo-description-list-action="" />
   ) : null;
 
-  const oneLine = inline && !row.identifier;
+  const iconOnly = row.labelHidden === true;
+  const oneLine = (inline && !row.identifier) || iconOnly;
   const rowStyle: CSSProperties | undefined = oneLine
     ? undefined
     : isWeb
@@ -389,7 +433,29 @@ function DescriptionListRowView({
       : { justifySelf: "end" }
     : undefined;
 
-  const body = oneLine ? (
+  const body = iconOnly ? (
+    <XStack
+      data-mpo-description-list-icon-only=""
+      {...(row.icon == null && termText(row.term)
+        ? { role: "group" as const, "aria-label": termText(row.term) }
+        : null)}
+      alignItems="center"
+      width="100%"
+      minWidth={0}
+      gap={rhythm.columnGap as never}
+    >
+      {row.icon != null ? <FactGlyph row={row} /> : null}
+      <View flex={1} minWidth={0}>
+        <ValueSlot row={row} />
+      </View>
+      {row.accessory != null ? (
+        <View data-mpo-description-list-accessory="" flexShrink={0} maxWidth="70%">
+          {row.accessory}
+        </View>
+      ) : null}
+      {action}
+    </XStack>
+  ) : oneLine ? (
     <XStack alignItems="center" width="100%" minWidth={0} gap={rhythm.columnGap as never}>
       <View flexShrink={0} maxWidth="60%" minWidth={0}>
         <TermLead row={row} inline />

package/src/InputParts/index.tsx

@@ -61,6 +61,7 @@ import { formButtonColors, formCommonColors, formInputColors } from "../shared/c
 import { useControlGroupVertical, useControlGrouped } from "../shared/groupContext";
 import { nativeAutoFocus } from "../shared/nativeAutoFocus";
 import { pressSlopProps } from "../shared/pressSlopProps";
+import { useFieldRow } from "../shared/fieldRowContext";
 import { useIsInTableCell } from "../shared/tableCellContext";
 import { useInPanelEcho, usePanelTriggerRadiusReporter } from "../FloatingPanel/echoContext";
 import { useFieldA11y, useFieldDescribedBy } from "../fieldLayout";
@@ -387,8 +388,9 @@ const InputGroupImpl = InputGroupFrame.styleable<{
   const hydrationTouch = useTouchSurface();
   const { knobProps, control, disabledState } = useResolvedKnobs();
   const grouped = useControlGrouped();
+  const inFieldRow = useFieldRow();
   const groupedVertical = useControlGroupVertical();
-  const inTableCell = useIsInTableCell();
+  const inTableCell = useIsInTableCell() || inFieldRow;
   // Native Pressable owns onPress; do not also pass it to XGroup (double-fire).
   const framePressProps = isWeb ? { onPress, disabled } : { disabled };
   // Standalone Box clips children to radius. Grouped / in-cell frames leave
@@ -471,16 +473,16 @@ const InputGroupImpl = InputGroupFrame.styleable<{
   // LC-84: text-field inset, not the button ladder padX. Multiline Box
   // (height="auto") leaves padX to ThemedTextArea so padX === padY.
   const fieldInset = heightProp === "auto" ? 0 : textFieldInset(familyRecipe);
+  const trailingOverlay = useContext(FieldTrailingOverlayContext);
   const insetPadProps =
     sizeRecipeEscaped ||
     (typeof paddingHorizontalProp !== "number" && paddingHorizontalProp != null)
       ? undefined
-      : { paddingHorizontal: fieldInset };
+      : { paddingHorizontal: inFieldRow && !trailingOverlay ? 0 : fieldInset };
   // LC-149: an action overlaid from outside the Box (a picker's native clear,
   // which must sit outside the trigger's press capture) still lands in the
   // trailing slot. The Box reserves the end cap and drops its end inset so
   // the overlay reads as part of the field.
-  const trailingOverlay = useContext(FieldTrailingOverlayContext);
   const trailingSlot = trailingOverlay ? (
     <View
       aria-hidden

package/src/Label/index.tsx

@@ -8,6 +8,7 @@ import {
   useRequiredMarking,
   type RequiredMarkMode,
 } from "../requiredMarking";
+import { useFieldRow } from "../shared/fieldRowContext";
 import { formCommonColors } from "../shared/colorRamps";
 
 export interface LabelProps extends Omit<TamaguiLabelProps, "size"> {
@@ -56,15 +57,19 @@ export function Label({
   const keepLabelReadable = Boolean(disabled) && disabledState.style !== "dimWhole";
   // LC-152 label role: 13/500 web, 15/500 native at the default size token.
   const role = knobProps.textRole.label;
-  const typeSize = (size as FontSizeTokens | undefined) ?? role.fontSize;
-  const color = error ? formCommonColors.error : role.color;
+  const inRow = useFieldRow();
+  // A field row's label is the row's title: body size and weight, primary ink.
+  const typeSize = (size as FontSizeTokens | undefined) ?? (inRow ? undefined : role.fontSize);
+  const color = error ? formCommonColors.error : inRow ? "$color" : role.color;
   const type = asPageHeading
     ? {
         ...knobProps.heading,
         fontSize: knobProps.pageTitle.size,
         lineHeight: knobProps.pageTitle.size,
       }
-    : { fontSize: typeSize, lineHeight: typeSize, fontWeight: role.fontWeight };
+    : inRow && typeSize === undefined
+      ? {}
+      : { fontSize: typeSize, lineHeight: typeSize, fontWeight: role.fontWeight };
 
   const node = (
     <TamaguiLabel
@@ -78,7 +83,7 @@ export function Label({
       color={color}
       cursor={disabled ? "not-allowed" : htmlFor ? "pointer" : "default"}
       display="flex"
-      alignItems="flex-start"
+      alignItems={inRow ? "center" : "flex-start"}
       flexWrap="wrap"
       opacity={keepLabelReadable ? 1 : undefined}
       {...(disabled && !keepLabelReadable ? disabledState.assemblyKnobProps : undefined)}

package/src/fieldLayout.tsx

@@ -1,12 +1,17 @@
 import type { FieldApi } from "@tanstack/form-core";
 import { Field as TanstackField } from "@tanstack/react-form";
-import { useResolvedKnobs } from "@multiplatform.one/theme";
+import {
+  MIN_PRESS_TARGET,
+  hairline,
+  useGroupPosition,
+  useResolvedKnobs,
+} from "@multiplatform.one/theme";
 import type { KnobProps } from "@multiplatform.one/theme";
 import type { ReactNode } from "react";
 import { createContext, useContext, useEffect, useMemo } from "react";
 import { AccessibilityInfo } from "react-native";
 import type { FontSizeTokens, LabelProps, SizeTokens, YStackProps } from "tamagui";
-import { isWeb, Paragraph, XStack, YStack } from "tamagui";
+import { isWeb, Paragraph, View, XStack, YStack } from "tamagui";
 import { fieldWidthStyle } from "./fieldDefaults";
 import { Label } from "./Label";
 import {
@@ -16,6 +21,7 @@ import {
   useRequiredMarking,
 } from "./requiredMarking";
 import { formCommonColors } from "./shared/colorRamps";
+import { useFieldRow } from "./shared/fieldRowContext";
 import { warnBannedErrorWords, warnPlaceholderAsLabel } from "./shared/devWarn";
 import type { AnyFormApi, SimpleFieldApi } from "./types";
 
@@ -203,7 +209,14 @@ export function FieldLayout({
   const dimWhole = Boolean(_disabled) && disabledStyle === "dimWhole";
   const keepLabelReadable = Boolean(_disabled) && disabledStyle !== "dimWhole";
   const labelPlacement = knobProps.fieldLabelPlacement ?? "top";
-  const sideLabel = labelPlacement === "side" && Boolean(label);
+  const inRow = useFieldRow();
+  // In an inset group the row carries the group's inset and the hairline
+  // above it, as a ListGroupItem does: the separator runs the group's full
+  // width (FZ-8003) and the row keeps the 44pt height.
+  const groupPosition = useGroupPosition();
+  const inGroup = groupPosition != null;
+  const ruledAbove = inGroup && groupPosition !== "first" && groupPosition !== "only";
+  const sideLabel = !inRow && labelPlacement === "side" && Boolean(label);
 
   warnPlaceholderAsLabel({
     placeholder,
@@ -272,7 +285,8 @@ export function FieldLayout({
       required={required}
       requiredMarking={requiredMarkingProp}
       error={hasErrorState}
-      flexShrink={sideLabel ? 0 : undefined}
+      flexShrink={sideLabel || inRow ? 0 : undefined}
+      {...(inRow ? { maxWidth: "50%" } : null)}
       {...labelProps}
     >
       {label}
@@ -328,11 +342,37 @@ export function FieldLayout({
           onBlur={onBlur}
           data-disabled-style={disabledStyle}
           data-disabled-dimmed={dimWhole ? "true" : "false"}
-          data-label-placement={sideLabel ? "side" : "top"}
+          data-label-placement={inRow ? "row" : sideLabel ? "side" : "top"}
           data-label-gap={String(gapProps.gap)}
           data-field-hug={hug ? "true" : undefined}
         >
-          {sideLabel ? (
+          {inRow ? (
+            <>
+              <YStack width="100%">
+                {ruledAbove ? (
+                  <View
+                    aria-hidden
+                    {...hairline.line}
+                    {...({ "data-list-hairline": "full" } as Record<string, unknown>)}
+                  />
+                ) : null}
+                <XStack
+                  alignItems="center"
+                  minHeight={MIN_PRESS_TARGET}
+                  width="100%"
+                  {...knobProps.gap}
+                  {...(inGroup ? { paddingHorizontal: knobProps.panelPadding.padding } : null)}
+                  data-field-row=""
+                >
+                  {labelNode}
+                  <XStack flex={1} minWidth={0} justifyContent="flex-end" alignItems="center">
+                    {children}
+                  </XStack>
+                </XStack>
+              </YStack>
+              {errorNode ?? helperNode}
+            </>
+          ) : sideLabel ? (
             <XStack
               alignItems="flex-start"
               {...knobProps.gap}

package/src/fieldRows.spec.tsx

@@ -0,0 +1,150 @@
+/**
+ * @vitest-environment jsdom
+ *
+ * LC-169 field rows: the iOS inset-grouped form. Inside `FieldRows` a field is
+ * one row: label leading at the body size, the control trailing without its
+ * own box, at least 44pt tall.
+ */
+
+import { createDefaultThemeConfig, GroupPositionContext } from "@multiplatform.one/theme";
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { describe, expect, it } from "vitest";
+import { Input } from "./fields/Input";
+import { Select } from "./fields/Select";
+import { Switch } from "./fields/Switch";
+import { FieldRows } from "./shared/fieldRowContext";
+
+// `$textMuted` is a key only MPO's themes define; under the stock test themes
+// tamagui drops it to `$color`, so this file renders under MPO's own config.
+createDefaultThemeConfig({});
+
+const classes = (el: Element | null) => String(el?.className ?? "");
+
+describe("FieldRows (LC-169)", () => {
+  it("a text field is a row: label leading, value trailing and editable in place", () => {
+    const result = renderWithProviders(
+      <FieldRows>
+        <Input id="name" label="Display name" value="Ada Lovelace" onChange={() => {}} />
+      </FieldRows>,
+    );
+    const layout = result.container.querySelector("[data-label-placement]") as HTMLElement;
+    expect(layout.getAttribute("data-label-placement")).toBe("row");
+    const row = result.container.querySelector("[data-field-row]") as HTMLElement;
+    expect(classes(row)).toMatch(/_fd-row/);
+    expect(classes(row)).toMatch(/_mih-44px/);
+    const input = result.container.querySelector("input") as HTMLInputElement;
+    expect(row.contains(input)).toBe(true);
+    expect(row.textContent).toContain("Display name");
+    expect(classes(input)).toMatch(/_ta-right/);
+    expect(input.readOnly).toBe(false);
+  });
+
+  it("the row's label is the body title in the primary ink, not the footnote label role", () => {
+    const outside = renderWithProviders(
+      <Input id="a" label="Email" value="" onChange={() => {}} />,
+    );
+    const inside = renderWithProviders(
+      <FieldRows>
+        <Input id="b" label="Email" value="" onChange={() => {}} />
+      </FieldRows>,
+    );
+    const label = (r: typeof outside) => r.container.querySelector("label") as HTMLElement;
+    expect(classes(label(inside))).toMatch(/_col-color(\s|$)/);
+    expect(classes(label(inside))).not.toEqual(classes(label(outside)));
+  });
+
+  it("a picker is a value row: the value in the secondary ink, no box", () => {
+    const result = renderWithProviders(
+      <FieldRows>
+        <Select
+          id="tz"
+          label="Timezone"
+          options={[{ value: "chi", label: "America/Chicago" }]}
+          value="chi"
+          onChange={() => {}}
+        />
+      </FieldRows>,
+    );
+    const trigger = result.getByTestId("select-trigger");
+    expect(classes(trigger)).not.toMatch(/_bw-1px/);
+    const value = result.getByText("America/Chicago");
+    expect(classes(value)).toMatch(/_col-textMuted/);
+  });
+
+  it("a switch row leads with its label by default", () => {
+    const result = renderWithProviders(
+      <FieldRows>
+        <Switch id="push" label="Push notifications" />
+      </FieldRows>,
+    );
+    const row = result.getByText("Push notifications").parentElement as HTMLElement;
+    expect(classes(row)).toMatch(/_fd-row-reverse/);
+  });
+
+  it("in an inset group the row carries the group's inset, outside it none", () => {
+    const loose = renderWithProviders(
+      <FieldRows>
+        <Input id="loose" label="Display name" value="Ada" onChange={() => {}} />
+      </FieldRows>,
+    );
+    const looseRow = loose.container.querySelector("[data-field-row]");
+    expect(classes(looseRow)).not.toMatch(/_pl-/);
+    const grouped = renderWithProviders(
+      <GroupPositionContext.Provider value="first">
+        <FieldRows>
+          <Input id="grouped" label="Display name" value="Ada" onChange={() => {}} />
+        </FieldRows>
+      </GroupPositionContext.Provider>,
+    );
+    const groupedRow = grouped.container.querySelector("[data-field-row]");
+    expect(classes(groupedRow)).toMatch(/_pl-/);
+    expect(classes(groupedRow)).toMatch(/_pr-/);
+  });
+
+  it("a value and a picker's chevron end on the row's trailing inset, as a switch does", () => {
+    const result = renderWithProviders(
+      <FieldRows>
+        <Input id="name" label="Display name" value="Ada Lovelace" onChange={() => {}} />
+        <Select
+          id="tz"
+          label="Timezone"
+          options={[{ value: "chi", label: "America/Chicago" }]}
+          value="chi"
+          onChange={() => {}}
+        />
+      </FieldRows>,
+    );
+    const endPads = (from: Element) => {
+      const pads: string[] = [];
+      let node: Element | null = from;
+      while (node && !node.hasAttribute("data-field-row")) {
+        pads.push(...(classes(node).match(/_pr-\S+/g) ?? []));
+        node = node.parentElement;
+      }
+      return pads;
+    };
+    const input = result.container.querySelector("input") as HTMLInputElement;
+    const trigger = result.getByTestId("select-trigger");
+    for (const pad of [...endPads(input), ...endPads(trigger)]) expect(pad).toBe("_pr-0px");
+  });
+
+  it("in an inset group every row but the first draws the group's full-width hairline (FZ-8003)", () => {
+    const result = renderWithProviders(
+      <FieldRows>
+        <GroupPositionContext.Provider value="first">
+          <Input id="first" label="Display name" value="" onChange={() => {}} />
+        </GroupPositionContext.Provider>
+        <GroupPositionContext.Provider value="last">
+          <Input id="last" label="Email" value="" onChange={() => {}} />
+        </GroupPositionContext.Provider>
+      </FieldRows>,
+    );
+    const layouts = result.container.querySelectorAll("[data-label-placement='row']");
+    expect(layouts).toHaveLength(2);
+    expect(layouts[0]!.querySelector("[data-list-hairline]")).toBeNull();
+    const rule = layouts[1]!.querySelector("[data-list-hairline]");
+    expect(rule?.getAttribute("data-list-hairline")).toBe("full");
+    const row = layouts[1]!.querySelector("[data-field-row]")!;
+    expect(rule!.compareDocumentPosition(row) & Node.DOCUMENT_POSITION_FOLLOWING).toBeTruthy();
+  });
+});

package/src/fields/Input/index.tsx

@@ -29,6 +29,7 @@ import type { AnyFormApi, LinkResolver } from "../../types";
 import { LinkCell } from "../../utils/LinkCell";
 import { getFormSubmission } from "../../Form/submissionController";
 import { useKeyboardChain } from "../../keyboard";
+import { useFieldRow } from "../../shared/fieldRowContext";
 
 type InputAreaProps = ComponentProps<typeof InputParts.Area>;
 
@@ -173,6 +174,8 @@ export function Input({
   const submitForm = useCallback(() => {
     if (resolvedForm && name) void getFormSubmission(resolvedForm).submit();
   }, [resolvedForm, name]);
+  // A field row (LC-169) edits the value in place at the row's trailing edge.
+  const rowAlign = useFieldRow() ? ({ textAlign: "right" } as const) : undefined;
   const keyboard = useKeyboardChain({
     inputRef,
     enabled: !disabled && !readOnly && !skeleton && !children,
@@ -341,6 +344,7 @@ export function Input({
               aria-invalid={hasError || undefined}
               {...identifierProps}
               {...areaName}
+              {...rowAlign}
             />
           )
         ) : (
@@ -375,6 +379,7 @@ export function Input({
             aria-required={required || undefined}
             aria-invalid={hasError || undefined}
             {...areaName}
+            {...rowAlign}
             onChange={onChange}
             onChangeText={(text) => {
               if (disabled) return;

package/src/fields/Select/Select.spec.tsx

@@ -9,6 +9,7 @@ import { sizeRecipeForToken } from "@multiplatform.one/theme";
 import { Button } from "../../Button";
 import { Form } from "../../Form";
 import { __resetDevWarnSeen } from "../../shared/devWarn";
+import { FieldRows } from "../../shared/fieldRowContext";
 import { Select, type SelectOption } from "./index";
 
 /** Web panels portal out to the page (MPO-335, LC-90), so panel text is read from the page. */
@@ -281,6 +282,15 @@ describe("Select Components", () => {
       expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining("select-too-few-options"));
     });
 
+    it("does not warn in a field row, where a short list is the pop-up row (LC-169)", () => {
+      renderWithProviders(
+        <FieldRows>
+          <Select options={mockOptions} id="row" label="Digest frequency" />
+        </FieldRows>,
+      );
+      expect(warnSpy).not.toHaveBeenCalledWith(expect.stringContaining("select-too-few-options"));
+    });
+
     it("does not warn when options.length > 5", () => {
       const many: SelectOption[] = Array.from({ length: 6 }, (_, i) => ({
         value: `v${i}`,