@multiplatform.one/forms 6.4.2 → 6.6.0

package/src/fields/Slider/index.tsx

@@ -333,6 +333,10 @@ function SliderControl({
   const trackActive = (
     <TamaguiSlider.TrackActive
       backgroundColor={formControlColors.border}
+      // The fill rides the same radius as the track it sits in: without it
+      // tamagui's default left a pill fill inside a square track at
+      // `borderRadius:none` — an undeclared knob-immune shape (D-09 / LC-60).
+      borderRadius={borderRadius}
       transition={transitionProp}
     />
   );

package/src/fields/Stepper/Stepper.stories.tsx

@@ -1,4 +1,5 @@
 import { action } from "@multiplatform.one/storybook";
+import type { GuardrailSpecimenParameter } from "@multiplatform.one/theme";
 import type { Meta, StoryObj } from "@storybook/react-native-web-vite";
 import { useForm } from "@tanstack/react-form";
 import { useState } from "react";
@@ -94,6 +95,17 @@ export const Basic: Story = {
 };
 
 export const Disabled: Story = {
+  parameters: {
+    // LC-57 allowlist: this story IS the disabled-dial demo. Stepper has no
+    // disabledReason plumbing (component-contract change, tracked separately),
+    // so its +/- buttons bare-disable here by design. The warn still fires;
+    // the harvester tolerates exactly this code on this story.
+    guardrailSpecimen: {
+      warns: ["bare-disabled"],
+      reason:
+        "Disabled-dial specimen: the whole field rests disabled and Stepper has no disabledReason plumbing yet.",
+    } satisfies GuardrailSpecimenParameter,
+  },
   args: {
     label: "Disabled Field",
     disabled: true,

package/src/fields/Switch/Switch.spec.tsx

@@ -1,12 +1,35 @@
 import { useForm } from "@tanstack/react-form";
-import { act, fireEvent, waitFor } from "@testing-library/react";
-import { YStack } from "tamagui";
+import { act, fireEvent, render, waitFor } from "@testing-library/react";
+import { TamaguiProvider, YStack, createTamagui } from "tamagui";
 import { describe, expect, it, vi } from "vitest";
 import { renderWithProviders } from "@multiplatform.one/test-utils";
+import {
+  createThemesBuilder,
+  defaultAccentTheme,
+  defaultBaseTheme,
+  defaultBuilderOptions,
+} from "@multiplatform.one/theme";
+import { configWithoutAnimations } from "@tamagui/config";
+import { animationsCSS } from "@tamagui/config/v5-css";
 import { Button } from "../../Button";
 import { Form } from "../../Form";
 import { Switch } from "./index";
 
+// House builder themes for the LC-05 mark assertion — created at MODULE
+// scope: tamagui registers a config's theme variables globally at
+// createTamagui time, and a config created after the first render (inside a
+// test body) never resolves its tokens (Progress.spec pattern).
+const houseThemes = createThemesBuilder(
+  defaultBaseTheme,
+  defaultAccentTheme,
+  defaultBuilderOptions,
+).themes() as Record<string, Record<string, string>>;
+const houseConfig = createTamagui({
+  ...configWithoutAnimations,
+  animations: animationsCSS,
+  themes: houseThemes as any,
+});
+
 describe("Switch", () => {
   describe("without form context", () => {
     it("should render with label and helper text correctly", () => {
@@ -315,4 +338,29 @@ describe("Switch", () => {
       });
     });
   });
+
+  describe("checked track mark (LC-05 ONE-EMPHASIS / UX-002)", () => {
+    // The checked Switch track IS a selection mark, so it resolves the shared
+    // accent mark token; the unchecked track stays neutral chrome. Stock test
+    // themes carry no $accentBackground, so mount the house builder themes
+    // for real resolution.
+    it("paints the checked track with the accent mark and the unchecked track neutral", () => {
+      const { container } = render(
+        <TamaguiProvider config={houseConfig} defaultTheme="light" disableInjectCSS>
+          <YStack>
+            <Switch label="On" name="on" defaultValue={true} />
+            <Switch label="Off" name="off" defaultValue={false} />
+          </YStack>
+        </TamaguiProvider>,
+      );
+      const switches = Array.from(container.querySelectorAll("[role='switch']"));
+      expect(switches.length).toBe(2);
+      const on = switches.find((s) => s.getAttribute("aria-checked") === "true") as HTMLElement;
+      const off = switches.find((s) => s.getAttribute("aria-checked") === "false") as HTMLElement;
+      expect(on).toBeTruthy();
+      expect(off).toBeTruthy();
+      expect(on.className).toContain("_bg-accentBackg");
+      expect(off.className).not.toContain("_bg-accentBackg");
+    });
+  });
 });

package/src/fields/TextArea/TextArea.spec.tsx

@@ -182,6 +182,63 @@ describe("TextArea", () => {
     });
   });
 
+  describe("late-arriving value display (create-mode seeding)", () => {
+    // The DOM textarea itself adopts late `defaultValue` updates while
+    // pristine (React DOM keeps the value attribute synced), but `charCount`
+    // was mount-only state — a value applied AFTER first paint (create-mode
+    // engine seeding, setFieldValue) rendered a stale count. Adopting a
+    // programmatic value must not emit onChange (LC-14).
+    it("form-integrated: a field value set after mount displays with a live count, without onChange", async () => {
+      const onChange = vi.fn();
+      const onChangeText = vi.fn();
+      let formApi: { setFieldValue: (name: "notes", value: string) => void } | undefined;
+      const TestComponent = () => {
+        const form = useForm({ defaultValues: { notes: "" } });
+        formApi = form as unknown as typeof formApi;
+        return (
+          <Form form={form}>
+            <TextArea
+              label="Notes"
+              name="notes"
+              showCount
+              onChange={onChange}
+              onChangeText={onChangeText}
+            />
+          </Form>
+        );
+      };
+      const result = renderWithProviders(<TestComponent />);
+      expect(result.findTextElement("0 characters")).toBeDefined();
+
+      await act(async () => {
+        formApi?.setFieldValue("notes", "seeded text");
+      });
+      await waitFor(() => {
+        expect((result.getTextArea() as HTMLTextAreaElement)?.value).toBe("seeded text");
+        expect(result.findTextElement("11 characters")).toBeDefined();
+      });
+      expect(onChange).not.toHaveBeenCalled();
+      expect(onChangeText).not.toHaveBeenCalled();
+    });
+
+    it("standalone controlled: a value arriving after mount updates the count, without onChange", async () => {
+      const onChangeText = vi.fn();
+      const result = renderWithProviders(
+        <TextArea label="Notes" value="" showCount onChangeText={onChangeText} />,
+      );
+      expect(result.findTextElement("0 characters")).toBeDefined();
+
+      result.rerender(
+        <TextArea label="Notes" value="late value" showCount onChangeText={onChangeText} />,
+      );
+      await waitFor(() => {
+        expect((result.getTextArea() as HTMLTextAreaElement)?.value).toBe("late value");
+        expect(result.findTextElement("10 characters")).toBeDefined();
+      });
+      expect(onChangeText).not.toHaveBeenCalled();
+    });
+  });
+
   describe("with useForm hook directly", () => {
     it("should handle form submission with useForm", async () => {
       const onSubmitMock = vi.fn();

package/src/fields/TextArea/TextArea.stories.tsx

@@ -190,7 +190,26 @@ export const AutoResize: Story = {
   },
 };
 
+/**
+ * FOREIGN CONTRAST SPECIMEN (LC-56 STORY-HONESTY): the right column renders the
+ * RAW tamagui TextArea beside the house TextArea strictly so the difference
+ * stays visible. Raw primitives here are by design and labeled — knob/contrast
+ * probes skip this story via `parameters.foreignContrastSpecimen`.
+ */
 export const Comparison: Story = {
+  name: "Foreign contrast specimen (raw tamagui)",
+  parameters: {
+    // Machine-readable exemption for knob/contrast probes and the LC-56 linter arm.
+    foreignContrastSpecimen: true,
+    docs: {
+      description: {
+        story:
+          "FOREIGN CONTRAST SPECIMEN (LC-56 STORY-HONESTY). The right column is the raw " +
+          "tamagui TextArea, rendered for contrast only: it ignores house knobs and field " +
+          "recipes by design. Probes asserting house rendering must skip this story.",
+      },
+    },
+  },
   render: () => {
     const ComparisonExample = () => {
       const [customVal, setCustomVal] = useState("");

package/src/fields/TextArea/index.tsx

@@ -171,6 +171,14 @@ export function TextArea({
 
   const isControlled = value !== undefined;
 
+  // Count from the live value whenever an upstream source drives the field
+  // (controlled `value` prop or TanStack field state): the mount-only
+  // charCount state froze counts for values applied after first paint
+  // (create-mode seeding, setFieldValue). Uncontrolled standalone keeps the
+  // keystroke-fed local state (its defaultValue never changes underneath).
+  const countFrom = (textValue: string | undefined) =>
+    isControlled || !!(resolvedForm && name) ? (textValue ?? "").length : charCount;
+
   const renderTextArea = (
     textValue: string | undefined,
     handleChange?: (text: string) => void,
@@ -178,7 +186,7 @@ export function TextArea({
     hasError?: boolean,
   ) => (
     <>
-      {showCount && countPosition.startsWith("top") && renderCount(charCount)}
+      {showCount && countPosition.startsWith("top") && renderCount(countFrom(textValue))}
       <YStack position="relative">
         <InputParts.Box
           height="auto"
@@ -232,7 +240,7 @@ export function TextArea({
         </InputParts.Box>
         {renderOverlay?.()}
       </YStack>
-      {showCount && countPosition.startsWith("bottom") && renderCount(charCount)}
+      {showCount && countPosition.startsWith("bottom") && renderCount(countFrom(textValue))}
     </>
   );
 

package/src/fields/TimePicker/index.tsx

@@ -106,7 +106,7 @@ function AmPmColumn({
               backgroundColor={isSelected ? formInputColors.background.focus : "transparent"}
               hoverStyle={{ backgroundColor: formInputColors.background.focus }}
               onPress={() => onChange(period)}
-              {...(knobProps.transition ? { animation: knobProps.transition } : undefined)}
+              {...(knobProps.transition ? { transition: knobProps.transition } : undefined)}
             >
               <Text
                 fontSize="$3"

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

@@ -1,10 +1,52 @@
-import { fireEvent, screen } from "@testing-library/react";
+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 {
+  createThemesBuilder,
+  defaultAccentTheme,
+  defaultBaseTheme,
+  defaultBuilderOptions,
+} from "@multiplatform.one/theme";
+import { configWithoutAnimations } from "@tamagui/config";
+import { animationsCSS } from "@tamagui/config/v5-css";
+import type { ReactElement } from "react";
+import { TamaguiProvider, createTamagui } from "tamagui";
 import { __resetDevWarnSeen } from "../../shared/devWarn";
 import { Form } from "../../Form";
 import { ToggleGroup } from "./index";
 
+// The stock test themes carry no accent ramp, so token resolution for the
+// LC-05 selected mark is invisible under renderWithProviders. Mount the house
+// builder themes (the same ones apps run) to assert the real resolved fill —
+// the pattern Progress.spec.tsx established.
+const houseThemes = createThemesBuilder(
+  defaultBaseTheme,
+  defaultAccentTheme,
+  defaultBuilderOptions,
+).themes() as Record<string, Record<string, string>>;
+
+const houseConfig = createTamagui({
+  ...configWithoutAnimations,
+  animations: animationsCSS,
+  themes: houseThemes as any,
+});
+
+function renderWithHouseThemes(ui: ReactElement) {
+  return render(
+    <TamaguiProvider config={houseConfig} defaultTheme="light" disableInjectCSS>
+      {ui}
+    </TamaguiProvider>,
+  );
+}
+
+/**
+ * First three numeric groups (h, s, l) of an hsla() string — the digit prefix
+ * Tamagui embeds in the atomic class it generates for a concrete color value.
+ */
+function hslDigits(hsla: string): string {
+  return (hsla.match(/\d+/g) ?? []).slice(0, 3).join("");
+}
+
 const options = [
   { label: "Left", value: "left" },
   { label: "Center", value: "center" },
@@ -162,4 +204,25 @@ describe("ToggleGroup", () => {
       expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining("bare-disabled"));
     });
   });
+
+  describe("selected mark (LC-05 ONE-EMPHASIS / D-01)", () => {
+    it("fills the selected segment with the accent-tinted surface, never the neutral tier", () => {
+      const { container } = renderWithHouseThemes(
+        <ToggleGroup label="Alignment" options={options} defaultValue="left" />,
+      );
+      // Segmented-control selection strength is pinned at TINTED (D-01
+      // ViewSwitcher rider): the accent ramp's surface tier in a light scheme
+      // is its palest step (accent11) — the same channel ViewSwitcher takes.
+      const tint = houseThemes.light.accent11;
+      expect(tint).toBeTruthy();
+      const selected = container.querySelector('[data-state="on"]') as HTMLElement;
+      const idle = container.querySelector('[data-state="off"]') as HTMLElement;
+      expect(selected).toBeTruthy();
+      expect(idle).toBeTruthy();
+      expect(selected.className).toContain(`_bg-hsla${hslDigits(tint)}`);
+      expect(idle.className).not.toContain(`_bg-hsla${hslDigits(tint)}`);
+      // Ink marks selection nowhere: the old neutral $color8 fill is gone.
+      expect(selected.className).not.toContain("_bg-color8");
+    });
+  });
 });

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

@@ -252,7 +252,26 @@ const alignmentOptions = [
   { label: "Right", value: "right" },
 ];
 
+/**
+ * FOREIGN CONTRAST SPECIMEN (LC-56 STORY-HONESTY): the right column renders the
+ * RAW tamagui ToggleGroup beside the house ToggleGroup strictly so the
+ * difference stays visible. Raw primitives here are by design and labeled —
+ * knob/contrast probes skip this story via `parameters.foreignContrastSpecimen`.
+ */
 export const Comparison: Story = {
+  name: "Foreign contrast specimen (raw tamagui)",
+  parameters: {
+    // Machine-readable exemption for knob/contrast probes and the LC-56 linter arm.
+    foreignContrastSpecimen: true,
+    docs: {
+      description: {
+        story:
+          "FOREIGN CONTRAST SPECIMEN (LC-56 STORY-HONESTY). The right column is the raw " +
+          "tamagui ToggleGroup, rendered for contrast only: it ignores house knobs and " +
+          "control recipes by design. Probes asserting house rendering must skip this story.",
+      },
+    },
+  },
   render: () => {
     const ComparisonExample = () => {
       const [customVal, setCustomVal] = useState("left");

package/src/fields/ToggleGroup/index.tsx

@@ -4,6 +4,7 @@ import {
   ensureFocusVisibleRing,
   ensureKeyboardModalityTracking,
   keyboardFocusRingProps,
+  useAccentTintedSurface,
   useReadableTextOn,
   wasKeyboardFocus,
 } from "@multiplatform.one/theme";
@@ -30,6 +31,11 @@ import {
   useResolvedValidators,
 } from "../../shared/utils";
 
+// NOTE: no `active` variant here — the selected fill is runtime-resolved
+// (accent-tinted surface, LC-05/D-01), so it rides direct props re-applied
+// through hover/press. A static variant would expand at its key position and
+// paint its stale value OVER those direct props (the exact drift the LC-40
+// wash comment below records for the disabled tier).
 const ToggleItemFrame = styled(TamaguiToggleGroup.Item, {
   cursor: "pointer",
   userSelect: "none",
@@ -56,20 +62,6 @@ const ToggleItemFrame = styled(TamaguiToggleGroup.Item, {
         },
       },
     },
-    active: {
-      true: {
-        backgroundColor: formButtonColors.border.active,
-        borderColor: formButtonColors.border.active,
-        hoverStyle: {
-          backgroundColor: formButtonColors.border.active,
-          borderColor: formButtonColors.border.active,
-        },
-        pressStyle: {
-          backgroundColor: formButtonColors.border.active,
-          borderColor: formButtonColors.border.active,
-        },
-      },
-    },
   } as const,
 });
 
@@ -244,11 +236,19 @@ export function ToggleGroup({
     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");
+  // LC-05 / D-01: selection is ONE accent language across every choice-control
+  // family — this selected segment filled with the neutral `$color8` tier, the
+  // catalog's last ink/neutral-marked selection surface. Segmented-control
+  // STRENGTH is pinned at TINTED (the D-01 ViewSwitcher rider — not the solid
+  // an accent CTA takes), so the fill is the accent ramp's surface tier
+  // mirrored by scheme, the same channel ViewSwitcher resolves. When the
+  // accent ramp is absent (tint sub-themes) the neutral tier stays as the
+  // declared fallback so selection never goes invisible.
+  // UX-018 / Axiom 15 kept: the label is the paper/ink anchor luminance-picked
+  // for the ACTUAL fill, never an assumed scheme token.
+  const selectedTint = useAccentTintedSurface();
+  const selectedFill = selectedTint ?? formButtonColors.border.active;
+  const onSelectedLabel = useReadableTextOn(selectedFill);
   // 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).
@@ -344,9 +344,13 @@ export function ToggleGroup({
       const itemDisabled = Boolean(disabled || option.disabled);
       const itemDescribedBy = option.disabled ? itemReasonIdFor(option.disabledReason) : undefined;
       const isTabStop = index === tabStopIndex;
+      // The accent-tinted selected fill (border rides the fill, as the
+      // neutral chip's did) — re-applied through hover/press below so the
+      // neutral state layer never paints over the selection mark (the LC-05
+      // rule the checked Switch track and ViewSwitcher chip already follow).
       const activeColors = {
-        backgroundColor: formButtonColors.border.active,
-        borderColor: formButtonColors.border.active,
+        backgroundColor: selectedFill,
+        borderColor: selectedFill,
       };
 
       return (
@@ -365,18 +369,16 @@ export function ToggleGroup({
           paddingHorizontal="$2"
           borderWidth={knobProps.borderRadius.borderWidth}
           outlined={knobProps.outlined}
-          animation={knobProps.transition}
+          transition={knobProps.transition}
           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.
+          // text-bearing chrome — a disabled segment drops the live selected
+          // fill entirely, 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

package/src/shared/FloatingListScrollArrows.stories.tsx

@@ -15,7 +15,9 @@ const manyOptions = Array.from({ length: 60 }, (_, i) => ({
   label: `Option ${i + 1}`,
 }));
 
-const fewOptions = Array.from({ length: 3 }, (_, i) => ({
+// Six entries: short enough that the floating list never scrolls (the story's
+// point) while clearing the ≤5 `select-too-few-options` guardrail (DG-CTRL-01).
+const fewOptions = Array.from({ length: 6 }, (_, i) => ({
   value: `option-${i + 1}`,
   label: `Option ${i + 1}`,
 }));
@@ -45,7 +47,7 @@ export const ShortSelect: Story = {
     <YStack maxWidth={320}>
       <Select
         id="fls-short"
-        label="Three options"
+        label="Six options"
         options={fewOptions}
         helperText="No arrows expected"
       />

package/src/shared/TimeColumn.tsx

@@ -66,7 +66,7 @@ export function TimeColumn({
               justifyContent="center"
               backgroundColor={isSelected ? formInputColors.background.focus : "transparent"}
               hoverStyle={{ backgroundColor: formInputColors.background.focus }}
-              {...(knobProps.transition ? { animation: knobProps.transition } : undefined)}
+              {...(knobProps.transition ? { transition: knobProps.transition } : undefined)}
             >
               <Text
                 fontSize="$4"

package/src/shared/focusManagement.ts

@@ -66,6 +66,10 @@ function restoreLater(
   insideRef?: RefObject<HTMLElement | null>,
 ) {
   const restore = () => {
+    // Fires from the unmount path, so the document can be gone by now (a test
+    // environment torn down inside the retry window). `isConnected` stays
+    // stale-true on a detached node, so it does not cover this.
+    if (!canUseDom()) return;
     const target = prevRef.current;
     if (!target || !target.isConnected) return;
     if (focusIsDropped(insideRef?.current ?? null)) target.focus();
@@ -102,11 +106,17 @@ export function useSheetModalFocus(open: boolean, frameRef: RefObject<HTMLElemen
 
     // Focus moves in once the sheet has mounted its frame (spring start).
     const focusIn = () => {
+      if (!canUseDom()) return;
       if (frame.contains(document.activeElement)) return;
       const first = frame.querySelector<HTMLElement>(FOCUSABLE);
       (first ?? frame).focus({ preventScroll: true });
     };
-    const raf = requestAnimationFrame(() => requestAnimationFrame(focusIn));
+    // Both frames are tracked: cancelling only the outer one leaves the inner
+    // callback live once the outer has already run.
+    let innerRaf = 0;
+    const raf = requestAnimationFrame(() => {
+      innerRaf = requestAnimationFrame(focusIn);
+    });
 
     // Light Tab trap: cycle within the frame (modal sheet owns focus).
     const onKeyDown = (e: KeyboardEvent) => {
@@ -132,6 +142,7 @@ export function useSheetModalFocus(open: boolean, frameRef: RefObject<HTMLElemen
     frame.addEventListener("keydown", onKeyDown);
     return () => {
       cancelAnimationFrame(raf);
+      cancelAnimationFrame(innerRaf);
       frame.removeEventListener("keydown", onKeyDown);
       restoreLater(prevRef, frameRef);
     };

package/src/shared/t.spec.ts

@@ -0,0 +1,39 @@
+import { describe, expect, it } from "vitest";
+import { bidiIsolate, t } from "./t";
+
+describe("t (uninitialized-i18n fallback)", () => {
+  it("returns the key with {{var}} interpolation applied", () => {
+    expect(t("Delete row {{row}}", { row: 3 })).toBe("Delete row 3");
+  });
+
+  it("leaves unknown variables as-is", () => {
+    expect(t("Delete row {{row}}", { other: 1 })).toBe("Delete row {{row}}");
+  });
+});
+
+describe("bidiIsolate (LC-58 BIDI-ISOLATION)", () => {
+  it("wraps the run in FSI…PDI so RTL contexts cannot reorder it", () => {
+    expect(bidiIsolate("1–5 of 5")).toBe("\u20681–5 of 5\u2069");
+    expect(bidiIsolate("Search...")).toBe("\u2068Search...\u2069");
+  });
+
+  it("keeps LTR content byte-identical inside the isolates", () => {
+    // First-strong isolation adds only the invisible FSI/PDI frame — the
+    // visible run is unchanged, so LTR rendering is unaffected.
+    const isolated = bidiIsolate("Search...");
+    expect(isolated.slice(1, -1)).toBe("Search...");
+    expect(isolated.startsWith("\u2068")).toBe(true);
+    expect(isolated.endsWith("\u2069")).toBe(true);
+  });
+
+  it("preserves an RTL run's own base direction (first-strong semantics)", () => {
+    // An Arabic run keeps its first strong character (RTL) as the isolate's
+    // base direction — isolation never forces LTR on translated copy.
+    const rtl = "بحث…";
+    expect(bidiIsolate(rtl)).toBe(`\u2068${rtl}\u2069`);
+  });
+
+  it("leaves empty strings alone (nothing to isolate)", () => {
+    expect(bidiIsolate("")).toBe("");
+  });
+});

package/src/shared/t.ts

@@ -21,3 +21,23 @@ export function t(key: string, options?: TOptions): string {
   }
   return interpolate(key, options);
 }
+
+/**
+ * First-strong bidi isolation — FSI…PDI (`\u2068…\u2069`), the string form of
+ * `<bdi>` (LC-58 BIDI-ISOLATION). Same helper as `components/src/shared/t.ts`
+ * and `table/src/utils/withInterp.ts` (the interpolation-home duplication
+ * precedent) — the helper lives beside each package's `t()` interpolator.
+ * Formatted runs that mix directions inside an RTL paragraph reorder by the
+ * bidi algorithm's rules — "1–5 of 5" renders "of 5 5–1", a trailing
+ * "Search..." ellipsis flips to "…Search" — because each weak/latin segment
+ * resolves independently. Isolating the WHOLE run gives it its own base
+ * direction from its first strong character, so untranslated latin copy
+ * renders LTR as a unit while translated RTL copy still renders RTL. Apply
+ * at the interpolation site of visible strings; never per-string manual
+ * marks, never aria-labels (invisible to reorder; breaks exact-match label
+ * queries).
+ */
+export function bidiIsolate(text: string): string {
+  if (!text) return text;
+  return `\u2068${text}\u2069`;
+}

package/types/Button/index.d.ts

@@ -40,8 +40,16 @@ export interface ButtonProps extends Omit<TamaguiButtonProps, "form" | "icon" |
      * — bare `disabled` emits `bare-disabled`.
      */
     disabledReason?: string;
+    /**
+     * Where the visible reason renders relative to the control. `"below"`
+     * (default) stacks it under the button — right for forms and vertical
+     * layouts. `"inline"` puts it beside the button on the same line — for
+     * toolbar/control rows, where a stacked reason breaks the row's shared
+     * control height and wraps into cramped multi-line type.
+     */
+    disabledReasonPlacement?: "below" | "inline";
 }
-export declare function Button({ children, action, form: formProp, loading, accent, error, warning, success, skeleton, outlined, disabled, theme, onPress, onKeyDown, tabIndex, icon, iconAfter, compact, verb, noun, actionRole, disabledReason, ...props }: ButtonProps): import("react/jsx-runtime").JSX.Element;
+export declare function Button({ children, action, form: formProp, loading, accent, error, warning, success, skeleton, outlined, disabled, theme, onPress, onKeyDown, tabIndex, icon, iconAfter, compact, verb, noun, actionRole, disabledReason, disabledReasonPlacement, ...props }: ButtonProps): import("react/jsx-runtime").JSX.Element;
 export declare namespace Button {
     var Icon: (props: {
         children: React.ReactNode;

package/types/Button/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/Button/index.tsx"],"names":[],"mappings":"AAAA,OAAO,EAML,KAAK,aAAa,EAClB,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AAQf,OAAO,EAEL,KAAK,WAAW,IAAI,kBAAkB,EAQvC,MAAM,SAAS,CAAC;AAIjB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAI3C,OAAO,KAAK,EAAE,UAAU,EAAuB,MAAM,cAAc,CAAC;AAyBpE,0DAA0D;AAC1D,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,WAAW,GAAG,QAAQ,CAAC;AAElE,KAAK,QAAQ,GAAG,SAAS,GAAG,aAAa,CAAC;IAAE,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAgF7D,MAAM,WAAW,WAAY,SAAQ,IAAI,CAAC,kBAAkB,EAAE,MAAM,GAAG,MAAM,GAAG,WAAW,CAAC;IAC1F,MAAM,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC;IAC5B,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,IAAI,CAAC,EAAE,QAAQ,CAAC;IAChB,SAAS,CAAC,EAAE,QAAQ,CAAC;IACrB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,UAAU,CAAC,EAAE,gBAAgB,CAAC;IAC9B;;;;;;;OAOG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,wBAAgB,MAAM,CAAC,EACrB,QAAQ,EACR,MAAM,EACN,IAAI,EAAE,QAAQ,EACd,OAAO,EACP,MAAM,EACN,KAAK,EACL,OAAO,EACP,OAAO,EACP,QAAgB,EAChB,QAAQ,EACR,QAAQ,EACR,KAAK,EACL,OAAO,EACP,SAAS,EACT,QAAQ,EACR,IAAI,EACJ,SAAS,EACT,OAAO,EACP,IAAI,EACJ,IAAI,EACJ,UAAU,EACV,cAAc,EACd,GAAG,KAAK,EACT,EAAE,WAAW,2CAgSb;yBAxTe,MAAM;;;iBAsCP,CAAC;YACH,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/Button/index.tsx"],"names":[],"mappings":"AAAA,OAAO,EAML,KAAK,aAAa,EAClB,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AAQf,OAAO,EAEL,KAAK,WAAW,IAAI,kBAAkB,EASvC,MAAM,SAAS,CAAC;AAIjB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAI3C,OAAO,KAAK,EAAE,UAAU,EAAuB,MAAM,cAAc,CAAC;AAyBpE,0DAA0D;AAC1D,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,WAAW,GAAG,QAAQ,CAAC;AAElE,KAAK,QAAQ,GAAG,SAAS,GAAG,aAAa,CAAC;IAAE,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAgF7D,MAAM,WAAW,WAAY,SAAQ,IAAI,CAAC,kBAAkB,EAAE,MAAM,GAAG,MAAM,GAAG,WAAW,CAAC;IAC1F,MAAM,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC;IAC5B,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,IAAI,CAAC,EAAE,QAAQ,CAAC;IAChB,SAAS,CAAC,EAAE,QAAQ,CAAC;IACrB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,UAAU,CAAC,EAAE,gBAAgB,CAAC;IAC9B;;;;;;;OAOG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;;OAMG;IACH,uBAAuB,CAAC,EAAE,OAAO,GAAG,QAAQ,CAAC;CAC9C;AAED,wBAAgB,MAAM,CAAC,EACrB,QAAQ,EACR,MAAM,EACN,IAAI,EAAE,QAAQ,EACd,OAAO,EACP,MAAM,EACN,KAAK,EACL,OAAO,EACP,OAAO,EACP,QAAgB,EAChB,QAAQ,EACR,QAAQ,EACR,KAAK,EACL,OAAO,EACP,SAAS,EACT,QAAQ,EACR,IAAI,EACJ,SAAS,EACT,OAAO,EACP,IAAI,EACJ,IAAI,EACJ,UAAU,EACV,cAAc,EACd,uBAAiC,EACjC,GAAG,KAAK,EACT,EAAE,WAAW,2CAuTb;yBAhVe,MAAM;;;iBA0BS,CAAC;YAAsB,CAAC"}

package/types/FieldDisplay/formatters.d.ts

@@ -10,9 +10,15 @@ export declare const EMPTY = "\u2014";
 export declare function asText(v: any): string;
 export interface NumericFormatOptions {
     precision?: number;
-    /** ISO 4217 currency code, e.g. "USD". */
+    /** ISO 4217 currency code (or a symbol a code is known for), e.g. "USD". */
     currency?: string;
 }
+/**
+ * Read-only numeric cells speak the house number registers (LC-12 render
+ * channel): the same figure reads identically in a table cell, a KPI tile
+ * and a group aggregate. `precision` pins the fraction digits a Frappe field
+ * declares; the register owns everything else.
+ */
 export declare function formatNumericText(num: number, options?: NumericFormatOptions): string;
 export { ISO_DATE_ONLY } from "@multiplatform.one/theme";
 export interface DateFormatOptions {

package/types/FieldDisplay/formatters.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"formatters.d.ts","sourceRoot":"","sources":["../../src/FieldDisplay/formatters.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,eAAO,MAAM,KAAK,WAAM,CAAC;AAEzB,wBAAgB,MAAM,CAAC,CAAC,EAAE,GAAG,GAAG,MAAM,CAYrC;AAED,MAAM,WAAW,oBAAoB;IACnC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,0CAA0C;IAC1C,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,oBAAyB,GAAG,MAAM,CAczF;AAGD,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAEzD,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,GAAG,EAAE,OAAO,GAAE,iBAAsB,GAAG,MAAM,CAIlF"}
+{"version":3,"file":"formatters.d.ts","sourceRoot":"","sources":["../../src/FieldDisplay/formatters.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,eAAO,MAAM,KAAK,WAAM,CAAC;AAEzB,wBAAgB,MAAM,CAAC,CAAC,EAAE,GAAG,GAAG,MAAM,CAYrC;AAED,MAAM,WAAW,oBAAoB;IACnC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,4EAA4E;IAC5E,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,oBAAyB,GAAG,MAAM,CAIzF;AAGD,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAEzD,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,GAAG,EAAE,OAAO,GAAE,iBAAsB,GAAG,MAAM,CAIlF"}