@multiplatform.one/forms 6.6.0 → 7.0.0

package/src/Label/Label.spec.tsx

@@ -0,0 +1,65 @@
+import { describe, expect, it } from "vitest";
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { Input as TamaguiInput } from "tamagui";
+import { Label } from "./index";
+
+describe("Label", () => {
+  it("associates with a control via htmlFor", () => {
+    const { container } = renderWithProviders(
+      <>
+        <Label htmlFor="email-field">Email address</Label>
+        <TamaguiInput id="email-field" />
+      </>,
+    );
+    const label = container.querySelector("label");
+    expect(label).not.toBeNull();
+    expect(label?.htmlFor).toBe("email-field");
+    expect(label?.textContent).toContain("Email address");
+  });
+
+  it("appends the required asterisk from house marking", () => {
+    const { container } = renderWithProviders(
+      <Label htmlFor="req" required>
+        Email address
+      </Label>,
+    );
+    expect(container.querySelector("label")?.textContent).toBe("Email address *");
+  });
+
+  it("appends (optional) when marking optional fields", () => {
+    const { container } = renderWithProviders(
+      <Label htmlFor="opt" required={false} requiredMarking="optional">
+        Nickname
+      </Label>,
+    );
+    expect(container.querySelector("label")?.textContent).toBe("Nickname (optional)");
+  });
+
+  it("keeps a hidden label in the tree and associated", () => {
+    const { container } = renderWithProviders(
+      <>
+        <Label htmlFor="search-field" hidden>
+          Search
+        </Label>
+        <TamaguiInput id="search-field" />
+      </>,
+    );
+    const label = container.querySelector("label");
+    expect(label?.htmlFor).toBe("search-field");
+    expect(label?.textContent).toContain("Search");
+    const style = label ? getComputedStyle(label) : null;
+    expect(style?.position === "absolute" || label?.style.position === "absolute").toBe(true);
+  });
+
+  it("wraps a page-heading label in h1", () => {
+    const { container } = renderWithProviders(
+      <Label htmlFor="event" asPageHeading>
+        Event name
+      </Label>,
+    );
+    const heading = container.querySelector("h1");
+    expect(heading).not.toBeNull();
+    expect(heading?.querySelector("label")?.htmlFor).toBe("event");
+    expect(heading?.textContent).toContain("Event name");
+  });
+});

package/src/Label/Label.stories.tsx

@@ -10,6 +10,11 @@ const meta: Meta<typeof Label> = {
     children: { control: "text" },
     size: { control: "select", options: ["$1", "$2", "$3", "$4", "$6", "$8"] },
     htmlFor: { control: "text" },
+    required: { control: "boolean" },
+    hidden: { control: "boolean" },
+    asPageHeading: { control: "boolean" },
+    error: { control: "boolean" },
+    disabled: { control: "boolean" },
   },
   args: {
     children: "Email address",
@@ -25,28 +30,93 @@ export const Basic: Story = {
 
 export const WithControl: Story = {
   render: () => (
-    <YStack gap="$2" maxWidth={320}>
-      <Label htmlFor="label-story-input">Email address</Label>
+    <YStack gap="$1.5" maxWidth={320}>
+      <Label htmlFor="label-story-input" required>
+        Email address
+      </Label>
       <TamaguiInput id="label-story-input" placeholder="you@example.com" />
     </YStack>
   ),
 };
 
+export const RequiredAndOptional: Story = {
+  render: () => (
+    <YStack gap="$4" maxWidth={320}>
+      <YStack gap="$1.5">
+        <Label htmlFor="label-required" required>
+          Email address
+        </Label>
+        <TamaguiInput id="label-required" />
+      </YStack>
+      <YStack gap="$1.5">
+        <Label htmlFor="label-optional" required={false} requiredMarking="optional">
+          Nickname
+        </Label>
+        <TamaguiInput id="label-optional" />
+      </YStack>
+    </YStack>
+  ),
+};
+
+export const ErrorState: Story = {
+  render: () => (
+    <YStack gap="$1.5" maxWidth={320}>
+      <Label htmlFor="label-error" required error>
+        Email address
+      </Label>
+      <TamaguiInput id="label-error" />
+    </YStack>
+  ),
+};
+
+export const Disabled: Story = {
+  render: () => (
+    <YStack gap="$1.5" maxWidth={320}>
+      <Label htmlFor="label-disabled" disabled>
+        Email address
+      </Label>
+      <TamaguiInput id="label-disabled" disabled />
+    </YStack>
+  ),
+};
+
+export const AsPageHeading: Story = {
+  render: () => (
+    <YStack gap="$2" maxWidth={400}>
+      <Label htmlFor="label-heading" asPageHeading>
+        Event name
+      </Label>
+      <TamaguiInput id="label-heading" />
+    </YStack>
+  ),
+};
+
+export const Hidden: Story = {
+  render: () => (
+    <YStack gap="$1.5" maxWidth={320}>
+      <Label htmlFor="label-hidden" hidden>
+        Search
+      </Label>
+      <TamaguiInput id="label-hidden" placeholder="Search" />
+    </YStack>
+  ),
+};
+
 export const EdgeCases: Story = {
   render: () => (
     <YStack gap="$4" maxWidth={360}>
-      <YStack gap="$2">
+      <YStack gap="$1.5">
         <Label htmlFor="label-empty">{""}</Label>
         <TamaguiInput id="label-empty" placeholder="empty label above" />
       </YStack>
-      <YStack gap="$2">
+      <YStack gap="$1.5">
         <Label htmlFor="label-long">
           This is an extremely long label that keeps going and going to check wrapping behaviour of
           label text over multiple lines without breaking the layout of the associated control
         </Label>
         <TamaguiInput id="label-long" placeholder="long label above" />
       </YStack>
-      <YStack gap="$2">
+      <YStack gap="$1.5">
         <Label htmlFor="label-rtl">تسمية باللغة العربية</Label>
         <TamaguiInput id="label-rtl" placeholder="rtl label above" />
       </YStack>

package/src/Label/index.tsx

@@ -1,12 +1,107 @@
+import { createElement } from "react";
 import { useResolvedKnobs } from "@multiplatform.one/theme";
-import type { LabelProps, SizeTokens } from "tamagui";
-import { Label as TamaguiLabel } from "tamagui";
+import type { FontSizeTokens, LabelProps as TamaguiLabelProps, SizeTokens } from "tamagui";
+import { isWeb, Label as TamaguiLabel, YStack } from "tamagui";
+import {
+  formatRequiredMarkSuffix,
+  mapHouseRequiredMarking,
+  useRequiredMarking,
+  type RequiredMarkMode,
+} from "../requiredMarking";
+import { formCommonColors } from "../shared/colorRamps";
 
-interface LabelPropsWithKnobs extends Omit<LabelProps, "size"> {
+export interface LabelProps extends Omit<TamaguiLabelProps, "size"> {
+  /** Type step. Do not pass a control-height `sizeToken` (LC-73). */
   size?: SizeTokens;
+  required?: boolean;
+  requiredMarking?: RequiredMarkMode;
+  /**
+   * Polaris `labelAccessibilityVisibility="exclusive"` / GOV.UK visually hidden:
+   * stays in the a11y tree and keeps `htmlFor`, takes no layout.
+   */
+  hidden?: boolean;
+  /** GOV.UK label-as-page-heading: type from the heading recipe, wrapped in `h1`. */
+  asPageHeading?: boolean;
+  error?: boolean;
+  disabled?: boolean;
 }
 
-export function Label({ size, ...props }: LabelPropsWithKnobs) {
-  const { knobProps } = useResolvedKnobs();
-  return <TamaguiLabel size={size ?? knobProps.sizeToken} {...knobProps.body} {...props} />;
+const visuallyHidden = {
+  position: "absolute" as const,
+  width: 1,
+  height: 1,
+  margin: -1,
+  padding: 0,
+  overflow: "hidden" as const,
+  ...(isWeb ? { whiteSpace: "nowrap" as const, borderWidth: 0 } : { opacity: 0 }),
+};
+
+export function Label({
+  size,
+  required,
+  requiredMarking: requiredMarkingProp,
+  hidden,
+  asPageHeading,
+  error,
+  disabled,
+  htmlFor,
+  children,
+  ...props
+}: LabelProps) {
+  const { knobProps, disabledState } = useResolvedKnobs();
+  const markingCtx = useRequiredMarking();
+  const markMode: RequiredMarkMode =
+    requiredMarkingProp ?? markingCtx?.mode ?? mapHouseRequiredMarking(knobProps.requiredMarking);
+  const suffix = formatRequiredMarkSuffix(required, markMode);
+  const keepLabelReadable = Boolean(disabled) && disabledState.style !== "dimWhole";
+  const typeSize = (size as FontSizeTokens | undefined) ?? knobProps.label.fontSize;
+  const color = error ? formCommonColors.error : knobProps.textAccentColor;
+  const type = asPageHeading
+    ? {
+        ...knobProps.heading,
+        fontSize: knobProps.pageTitle.size,
+        lineHeight: knobProps.pageTitle.size,
+      }
+    : { fontSize: typeSize, lineHeight: typeSize };
+
+  const node = (
+    <TamaguiLabel
+      htmlFor={htmlFor}
+      // T-LABEL: body metrics + label type fragment + textAccentColor.
+      // Never pass sizeToken as Tamagui `size` — that variant runs
+      // getButtonSized and inflates line-height to control height (LC-73).
+      {...knobProps.body}
+      {...knobProps.label}
+      {...type}
+      color={color}
+      cursor={disabled ? "not-allowed" : htmlFor ? "pointer" : "default"}
+      display="flex"
+      alignItems="flex-start"
+      flexWrap="wrap"
+      opacity={keepLabelReadable ? 1 : undefined}
+      {...(disabled && !keepLabelReadable ? disabledState.assemblyKnobProps : undefined)}
+      {...(hidden ? visuallyHidden : undefined)}
+      pressStyle={{ color }}
+      hoverStyle={{ color }}
+      focusStyle={{ color }}
+      {...props}
+    >
+      {children}
+      {suffix}
+    </TamaguiLabel>
+  );
+
+  if (asPageHeading && !hidden) {
+    // Real <h1> wherever a DOM exists (web + happy-dom). Tamagui `tag`
+    // leaks as an attribute on RN-web. Native uses header role.
+    if (typeof document !== "undefined") {
+      return createElement("h1", { style: { margin: 0, padding: 0 } }, node);
+    }
+    return (
+      <YStack accessibilityRole="header" margin={0} padding={0}>
+        {node}
+      </YStack>
+    );
+  }
+  return node;
 }

package/src/Skeleton/index.tsx

@@ -1,4 +1,4 @@
-import { radiusClassProps, useResolvedKnobs } from "@multiplatform.one/theme";
+import { radiusClassProps, sizeRecipeForToken, useResolvedKnobs } from "@multiplatform.one/theme";
 import type { GetProps } from "tamagui";
 import { View, styled, isWeb } from "tamagui";
 
@@ -46,9 +46,21 @@ const SkeletonFrame = styled(View, {
 });
 
 // Size-knob geometry (spec: Skeleton block/text/circle scale with
-// `sizeToken`); medium keeps the previous 16px line and 40px circle.
-const skeletonTextHeightMap: Record<string, number> = { $3: 14, $4: 16, $5: 20 };
-const skeletonCircleSizeMap: Record<string, number> = { $3: 32, $4: 40, $5: 48 };
+// `sizeToken`), DERIVED from the generated size recipe (LC-80): a text bone
+// is the token's recipe fontSize + 2px of line-box rounding (medium keeps
+// the previous 16px line), and a circle bone is the medallion one height
+// step above the control ramp (medium keeps the previous 40px circle).
+const SKELETON_SIZE_TOKENS = ["$3", "$4", "$5"] as const;
+const skeletonCircleTokenUp: Record<string, string> = { $3: "$4", $4: "$5", $5: "$6" };
+
+function skeletonTextHeight(sizeToken: string): number | undefined {
+  if (!(SKELETON_SIZE_TOKENS as readonly string[]).includes(sizeToken)) return undefined;
+  return sizeRecipeForToken(sizeToken).fontSize + 2;
+}
+
+function skeletonCircleSize(sizeToken: string): number {
+  return sizeRecipeForToken(skeletonCircleTokenUp[sizeToken] ?? "$5").height;
+}
 // SP-GAP: text-line gap follows the space knob; medium keeps $2.
 const skeletonGapMap: Record<string, string> = { small: "$1", medium: "$2", large: "$3" };
 
@@ -93,9 +105,7 @@ export function Skeleton({
       variant={variant}
       width={width}
       // Text lines follow the size knob; explicit height ejects.
-      height={
-        height ?? (variant === "text" ? skeletonTextHeightMap[knobProps.sizeToken] : undefined)
-      }
+      height={height ?? (variant === "text" ? skeletonTextHeight(knobProps.sizeToken) : undefined)}
       // Radius only — a skeleton is a flat blob, it never draws the knob's border.
       // Consumers that clamp (Checkbox/Radio/Switch) pass an explicit borderRadius
       // which wins via ...props below.
@@ -153,7 +163,7 @@ export function SkeletonText({
 
 export function SkeletonCircle({ size: sizeProp, ...props }: SkeletonProps & { size?: number }) {
   const { knobProps } = useResolvedKnobs();
-  const size = sizeProp ?? skeletonCircleSizeMap[knobProps.sizeToken] ?? 40;
+  const size = sizeProp ?? skeletonCircleSize(knobProps.sizeToken);
   return <Skeleton variant="circular" width={size} height={size} {...props} />;
 }
 

package/src/Spinner/Spinner.spec.tsx

@@ -0,0 +1,66 @@
+/**
+ * @vitest-environment jsdom
+ */
+
+import { cleanup } from "@testing-library/react";
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { Preset } from "@multiplatform.one/theme";
+import { afterEach, describe, expect, it } from "vitest";
+import { Spinner } from "./index";
+
+afterEach(cleanup);
+
+function status(container: HTMLElement): HTMLElement {
+  return container.querySelector("[role='status']") as HTMLElement;
+}
+
+describe("Spinner", () => {
+  it("announces as a polite status region and is not a progressbar", () => {
+    const { container } = renderWithProviders(<Spinner />);
+    const node = status(container);
+    expect(node).toBeTruthy();
+    expect(node.getAttribute("aria-label")).toBe("Loading");
+    expect(node.getAttribute("aria-live")).toBe("polite");
+    expect(container.querySelector("[role='progressbar']")).toBeNull();
+  });
+
+  it("stops spinning when the animation knob is none", () => {
+    const { container } = renderWithProviders(
+      <Preset overrides={{ animation: "none" }}>
+        <Spinner />
+      </Preset>,
+    );
+    expect(status(container).className).toContain("mp1-spinner-static");
+  });
+
+  it("keeps spinning with motion on", () => {
+    const { container } = renderWithProviders(<Spinner />);
+    const node = status(container);
+    expect(node.className).toContain("mp1-spinner");
+    expect(node.className).not.toContain("mp1-spinner-static");
+  });
+
+  it("maps explicit small/large onto the shared size-token scale", () => {
+    const small = renderWithProviders(<Spinner size="small" />);
+    expect(status(small.container).getAttribute("data-size")).toBe("$1");
+    cleanup();
+    const large = renderWithProviders(<Spinner size="large" />);
+    expect(status(large.container).getAttribute("data-size")).toBe("$3");
+  });
+
+  it("follows the size knob when size is omitted", () => {
+    const small = renderWithProviders(
+      <Preset overrides={{ size: "small" }}>
+        <Spinner />
+      </Preset>,
+    );
+    expect(status(small.container).getAttribute("data-size")).toBe("$3");
+    cleanup();
+    const large = renderWithProviders(
+      <Preset overrides={{ size: "large" }}>
+        <Spinner />
+      </Preset>,
+    );
+    expect(status(large.container).getAttribute("data-size")).toBe("$5");
+  });
+});

package/src/Spinner/Spinner.stories.tsx

@@ -1,5 +1,6 @@
 import type { Meta, StoryObj } from "@storybook/react-native-web-vite";
 import { useState } from "react";
+import { Preset } from "@multiplatform.one/theme";
 import { XStack, YStack, Paragraph } from "tamagui";
 import { Button } from "../Button";
 import { Spinner } from "./index";
@@ -23,20 +24,48 @@ export const Basic: Story = {
 
 export const Sizes: Story = {
   render: () => (
-    <XStack gap="$6" alignItems="center">
-      <YStack gap="$2" alignItems="center">
-        <Spinner size="small" />
-        <Paragraph size="$2">small</Paragraph>
-      </YStack>
-      <YStack gap="$2" alignItems="center">
-        <Spinner size="large" />
-        <Paragraph size="$2">large</Paragraph>
-      </YStack>
-      <YStack gap="$2" alignItems="center">
-        <Spinner size="small" color="#e5484d" />
-        <Paragraph size="$2">custom color</Paragraph>
-      </YStack>
-    </XStack>
+    <YStack gap="$6">
+      <XStack gap="$6" alignItems="center">
+        <YStack gap="$2" alignItems="center">
+          <Spinner size="small" />
+          <Paragraph size="$2">small</Paragraph>
+        </YStack>
+        <YStack gap="$2" alignItems="center">
+          <Spinner size="large" />
+          <Paragraph size="$2">large</Paragraph>
+        </YStack>
+        <YStack gap="$2" alignItems="center">
+          <Spinner size="small" color="$red10" />
+          <Paragraph size="$2">custom color</Paragraph>
+        </YStack>
+      </XStack>
+      <XStack gap="$6" alignItems="center">
+        <YStack gap="$2" alignItems="center">
+          <Preset overrides={{ size: "small" }}>
+            <Spinner />
+          </Preset>
+          <Paragraph size="$2">knob small</Paragraph>
+        </YStack>
+        <YStack gap="$2" alignItems="center">
+          <Preset overrides={{ size: "medium" }}>
+            <Spinner />
+          </Preset>
+          <Paragraph size="$2">knob medium</Paragraph>
+        </YStack>
+        <YStack gap="$2" alignItems="center">
+          <Preset overrides={{ size: "large" }}>
+            <Spinner />
+          </Preset>
+          <Paragraph size="$2">knob large</Paragraph>
+        </YStack>
+        <YStack gap="$2" alignItems="center">
+          <Preset overrides={{ animation: "none" }}>
+            <Spinner size="large" />
+          </Preset>
+          <Paragraph size="$2">motion off</Paragraph>
+        </YStack>
+      </XStack>
+    </YStack>
   ),
 };
 

package/src/Spinner/SpinnerGlyph.tsx

@@ -0,0 +1,38 @@
+import { getVariable, useTheme } from "tamagui";
+import { Circle, Svg } from "react-native-svg";
+
+const VB = 24;
+const CX = VB / 2;
+const R = 9;
+const STROKE = 2.5;
+const CIRCUMFERENCE = 2 * Math.PI * R;
+const ARC = CIRCUMFERENCE * 0.75;
+
+export function useSpinnerStroke(color?: string): string {
+  const theme = useTheme();
+  if (color && !color.startsWith("$")) return color;
+  const key = (color ?? "$color").replace(/^\$/, "");
+  const token = theme[key as keyof typeof theme];
+  if (!token) return color ?? "currentColor";
+  return String(getVariable((token as { get?: (p: string) => unknown }).get?.("web") ?? token));
+}
+
+/** Linear/Polaris arc: round-cap 270° head on a faint track. Scales with the box. */
+export function SpinnerGlyph({ color, size }: { color: string; size: number }) {
+  return (
+    <Svg width={size} height={size} viewBox={`0 0 ${VB} ${VB}`} pointerEvents="none">
+      <Circle cx={CX} cy={CX} r={R} fill="none" stroke={color} strokeWidth={STROKE} opacity={0.2} />
+      <Circle
+        cx={CX}
+        cy={CX}
+        r={R}
+        fill="none"
+        stroke={color}
+        strokeWidth={STROKE}
+        strokeLinecap="round"
+        strokeDasharray={`${ARC} ${CIRCUMFERENCE - ARC}`}
+        transform={`rotate(-90 ${CX} ${CX})`}
+      />
+    </Svg>
+  );
+}

package/src/Spinner/index.native.tsx

@@ -0,0 +1,64 @@
+import { useEffect, useRef } from "react";
+import { Animated, Easing } from "react-native";
+import { useResolvedKnobs } from "@multiplatform.one/theme";
+import { View } from "tamagui";
+import { t } from "../shared/t";
+import { SpinnerGlyph, useSpinnerStroke } from "./SpinnerGlyph";
+import { spinnerSizePx, spinnerSizeToken, type SpinnerProps } from "./spinnerSize";
+
+export type { SpinnerProps, SpinnerSize } from "./spinnerSize";
+
+const SPIN_MS = 700;
+
+/** Native Spinner. Size follows the shared size-token scale; spin gates on transition. */
+export function Spinner({ size, color, ...props }: SpinnerProps) {
+  const { knobProps } = useResolvedKnobs();
+  const token = spinnerSizeToken(size, knobProps.sizeToken);
+  const px = spinnerSizePx(token);
+  const stroke = useSpinnerStroke(color);
+  const spinning = Boolean(knobProps.transition);
+  const spin = useRef(new Animated.Value(0)).current;
+
+  useEffect(() => {
+    if (!spinning) {
+      spin.setValue(0);
+      return;
+    }
+    const loop = Animated.loop(
+      Animated.timing(spin, {
+        toValue: 1,
+        duration: SPIN_MS,
+        easing: Easing.linear,
+        useNativeDriver: true,
+      }),
+    );
+    loop.start();
+    return () => {
+      loop.stop();
+      spin.setValue(0);
+    };
+  }, [spinning, spin]);
+
+  const rotate = spin.interpolate({
+    inputRange: [0, 1],
+    outputRange: ["0deg", "360deg"],
+  });
+
+  return (
+    <View
+      width={px}
+      height={px}
+      role="status"
+      aria-label={t("Loading")}
+      aria-live="polite"
+      aria-busy
+      pointerEvents="none"
+      data-size={token}
+      {...props}
+    >
+      <Animated.View style={{ width: px, height: px, transform: [{ rotate }] }}>
+        <SpinnerGlyph color={stroke} size={px} />
+      </Animated.View>
+    </View>
+  );
+}