@multiplatform.one/forms 6.1.0 → 6.4.0

package/src/fields/RadioGroup/index.tsx

@@ -1,6 +1,7 @@
 import type { ReactNode } from "react";
+import { useCallback, useRef, useState } from "react";
 import type { AnyFormApi } from "../../types";
-import type { FontSizeTokens, LabelProps, SizeTokens } from "tamagui";
+import type { FontSizeTokens, LabelProps, SizeTokens, TamaguiElement } from "tamagui";
 import {
   Label,
   type RadioGroupProps as TamaguiRadioGroupProps,
@@ -8,8 +9,11 @@ import {
   View,
   XStack,
   YStack,
+  getVariableValue,
+  isWeb,
   styled,
 } from "tamagui";
+import { getSize } from "@tamagui/get-token";
 import { Skeleton } from "../../Skeleton";
 import { Field, FieldLayout } from "../../fieldLayout";
 import { formControlColors } from "../../shared/colorRamps";
@@ -21,59 +25,86 @@ import {
   useFormField,
   useResolvedValidators,
 } from "../../shared/utils";
+import {
+  CheckboxCardContent,
+  CheckboxCardDescription,
+  CheckboxCardFrame,
+  CheckboxCardLabel,
+  getCardDescriptionSize,
+  getCheckboxCardLayout,
+} from "../Checkbox/CheckboxCard";
+
+/** Minimum pressable target for an individual radio control (WCAG 2.5.5 / SP-FIXED). */
+const radioTargetSize = 44;
 
+// The pressable/focusable role=radio element is a 44px transparent target;
+// the visible circle is the inner RadioGlyph. Sizing the target (not the
+// glyph) keeps visual density while flooring the touch target.
 const RadioItemFrame = styled(TamaguiRadioGroup.Item, {
+  width: radioTargetSize,
+  height: radioTargetSize,
+  minWidth: radioTargetSize,
+  minHeight: radioTargetSize,
+  padding: 0,
+  borderWidth: 0,
   borderRadius: 1000,
-  backgroundColor: formControlColors.background,
-  borderColor: formControlColors.border,
-  hoverStyle: {
-    backgroundColor: formControlColors.background,
-    borderColor: formControlColors.border,
-  },
-  pressStyle: {
-    backgroundColor: formControlColors.background,
-    borderColor: formControlColors.border,
-  },
-  focusStyle: {
-    backgroundColor: formControlColors.background,
-    borderColor: formControlColors.border,
-  },
-  focusVisibleStyle: {
-    backgroundColor: formControlColors.background,
-    borderColor: formControlColors.border,
-  },
+  backgroundColor: "transparent",
+  alignItems: "center",
+  justifyContent: "center",
+  hoverStyle: { backgroundColor: "transparent" },
+  pressStyle: { backgroundColor: "transparent" },
+  focusStyle: { backgroundColor: "transparent" },
+  focusVisibleStyle: { backgroundColor: "transparent" },
+});
+
+// Visual radio circle, sized like tamagui's radio item (size token * 0.5).
+// DF-06 / WCAG 1.4.11: classic empty-ring anatomy — transparent fill with a
+// ≥3:1 boundary ring. The old filled disc ($color5 fill + $color7 border)
+// measured 1.26:1 vs the page and 1.20:1 border-vs-disc: three identical
+// gray blobs under a squint. The control's shape now comes from its ring.
+const RadioGlyph = styled(View, {
+  borderRadius: 1000,
+  backgroundColor: "transparent",
+  borderColor: formControlColors.boundary,
+  alignItems: "center",
+  justifyContent: "center",
   variants: {
-    outlined: {
-      true: {
-        backgroundColor: "transparent",
-        hoverStyle: { backgroundColor: "transparent", borderColor: formControlColors.border },
-        pressStyle: { backgroundColor: "transparent", borderColor: formControlColors.border },
-        focusStyle: { backgroundColor: "transparent", borderColor: formControlColors.border },
+    size: {
+      "...size": (val: SizeTokens) => {
+        const glyphSize = Math.floor(getVariableValue(getSize(val)) * 0.5);
+        return { width: glyphSize, height: glyphSize };
       },
     },
+    outlined: {
+      true: { backgroundColor: "transparent" },
+    },
   } as const,
 });
 
+/**
+ * Ring width floor: a 1px hairline at the boundary tier still under-signals a
+ * 22px control (platform radios sit at ~2px); knob borderWidth applies above
+ * the floor. Purely the glyph ring — knob-driven seams elsewhere unchanged.
+ */
+const radioRingWidth = (knobBorderWidth: number | undefined) => Math.max(knobBorderWidth ?? 1, 2);
+
 const RadioIndicatorFrame = styled(TamaguiRadioGroup.Indicator, {
   borderRadius: 1000,
+  // DF-06 optics rider (Axiom 15): the selected dot fills ~half the OUTER
+  // disc — the platform-convention 0.45–0.55 band. Percentage sizes resolve
+  // against the glyph's content box (disc minus the 2px ring), so 60% of
+  // content ≈ 0.49 of the disc at the 22px default. The previous 33%
+  // (6.6px in a 22px disc, 0.30) under-signaled the checked state.
+  width: "60%",
+  height: "60%",
 });
 
-function RadioItemWithElevation({
-  elevationWrapperProps,
-  itemRadius = 1000,
-  ...props
-}: { elevationWrapperProps: Record<string, any>; itemRadius?: number; value: string } & Record<
-  string,
-  any
->) {
-  if (elevationWrapperProps.elevation) {
-    return (
-      <View {...elevationWrapperProps} borderRadius={itemRadius}>
-        <RadioItemFrame {...props} />
-      </View>
-    );
-  }
-  return <RadioItemFrame {...props} />;
+export interface RadioGroupOption {
+  label: string;
+  value: string;
+  disabled?: boolean;
+  /** Muted secondary line under the label; rendered in `card` mode. */
+  description?: string;
 }
 
 export interface RadioGroupProps {
@@ -91,9 +122,15 @@ export interface RadioGroupProps {
   id?: string;
   value?: string;
   defaultValue?: string;
+  /**
+   * Canonical change handler, consistent with the rest of the field family.
+   * Prefer this over `onValueChange`.
+   */
+  onChange?: (value: string) => void;
+  /** @deprecated Use `onChange` instead. Kept as an alias for the tamagui/Radix name. */
   onValueChange?: (value: string) => void;
   onBlur?: (...args: any[]) => void;
-  options?: Array<{ label: string; value: string }>;
+  options?: RadioGroupOption[];
   orientation?: "horizontal" | "vertical";
   radioGroupProps?: Omit<
     TamaguiRadioGroupProps,
@@ -106,6 +143,13 @@ export interface RadioGroupProps {
   skeleton?: boolean;
   /** When true, uses compact sizing */
   compact?: boolean;
+  /**
+   * When true, renders each option as a selection card (LC-22): radio in a
+   * leading slot, bold label to its right, muted `option.description` under
+   * the label; the whole card selects. Consumes the shared CheckboxCard
+   * primitives (same anatomy as `CheckboxGroup card`).
+   */
+  card?: boolean;
 }
 
 export function RadioGroup({
@@ -123,6 +167,7 @@ export function RadioGroup({
   id: idProp,
   value,
   defaultValue,
+  onChange,
   onValueChange,
   onBlur,
   options,
@@ -132,8 +177,15 @@ export function RadioGroup({
   pointy,
   skeleton,
   compact,
+  card,
 }: RadioGroupProps) {
-  const { resolvedForm, knobProps, control, text, elevation, id } = useFormField({
+  // Canonical `onChange` and the alias `onValueChange` both fire from the
+  // single emit site below (same reconciliation as Switch).
+  const handleValueChange = (val: string) => {
+    onChange?.(val);
+    onValueChange?.(val);
+  };
+  const { resolvedForm, knobProps, control, text, elevation, disabledState, id } = useFormField({
     form: formProp,
     id: idProp,
     compact,
@@ -143,81 +195,249 @@ export function RadioGroup({
   const resolvedPointy = pointy ?? knobProps.pointy;
   const itemRadius = resolvedPointy ? 0 : 1000;
   const indicatorRadius = resolvedPointy ? 0 : 1000;
+  // Uncontrolled state for card-mode whole-card press (and standalone use) —
+  // without this, card body presses only fire parent handlers while Tamagui's
+  // defaultValue-driven group stays stale.
+  const [internalValue, setInternalValue] = useState<string | undefined>(defaultValue);
+
+  // Tamagui's RadioGroup renders its RovingFocusGroup as a separate View
+  // AROUND the role=radiogroup frame (Radix merges both onto one element via
+  // asChild; the tamagui port does not), leaving a focusable outer div with
+  // no role/name in the tab order (voiceover pass, SchemaForm radiogroup).
+  // Neutralize that wrapper's tabindex on web so only the radiogroup's
+  // radios participate in tab order. The roving group re-applies tabIndex=0
+  // whenever its focusable-item count or tab-back state re-renders, so a
+  // one-shot strip does not hold — an attribute observer keeps it out.
+  const wrapperTabIndexObserver = useRef<MutationObserver | null>(null);
+  const frameRef = useCallback((node: TamaguiElement | null) => {
+    wrapperTabIndexObserver.current?.disconnect();
+    wrapperTabIndexObserver.current = null;
+    if (!isWeb || !node) return;
+    const wrapper = (node as unknown as HTMLElement).parentElement;
+    // The roving wrapper is role-less and carries data-orientation; anything
+    // else means the structure changed and we must not touch it.
+    if (!wrapper || wrapper.getAttribute("role") || !wrapper.hasAttribute("data-orientation")) {
+      return;
+    }
+    const strip = () => {
+      if (wrapper.getAttribute("tabindex") === "0") wrapper.setAttribute("tabindex", "-1");
+    };
+    strip();
+    const observer = new MutationObserver(strip);
+    observer.observe(wrapper, { attributes: true, attributeFilter: ["tabindex"] });
+    wrapperTabIndexObserver.current = observer;
+  }, []);
 
   // Render skeleton placeholder
   if (skeleton) {
+    // Mirror the real anatomy (LC-20 SKELETON-MIRRORS-ANATOMY): each row is a
+    // 20px control at the same radius the real radio uses (pill / pointy-0),
+    // then a label bar separated by the real control↔label gap. Label widths
+    // are DETERMINISTIC per index (never %, never random): a percentage width
+    // inside an auto-width horizontal row resolves against a width computed
+    // without it, so the bar paints past the row's edge and fuses with the
+    // next item's control.
     const optionCount = options?.length ?? 3;
+    const Container = orientation === "horizontal" ? XStack : YStack;
+    const labelWidths = [88, 64, 76];
     return (
       <FieldLayout id={id} label={label} size={size} knobProps={knobProps}>
-        <YStack gap="$2">
+        <Container gap="$2">
           {Array.from({ length: optionCount }, (_, i) => (
             <XStack key={i} gap="$2" alignItems="center">
-              <Skeleton variant="circular" width={20} height={20} />
-              <Skeleton variant="text" width="50%" height={14} />
+              {/* Mirror the 44px pressable target box around the 20px glyph */}
+              <View
+                width={radioTargetSize}
+                height={radioTargetSize}
+                alignItems="center"
+                justifyContent="center"
+              >
+                <Skeleton
+                  variant={itemRadius === 0 ? "rounded" : "circular"}
+                  width={20}
+                  height={20}
+                  borderRadius={itemRadius}
+                />
+              </View>
+              <Skeleton variant="text" width={labelWidths[i % labelWidths.length]} height={14} />
             </XStack>
           ))}
-        </YStack>
+        </Container>
       </FieldLayout>
     );
   }
 
-  const renderItems = () => {
+  const renderRadioItem = (
+    option: RadioGroupOption,
+    itemId: string,
+    a11y?: { "aria-labelledby"?: string; "aria-describedby"?: string },
+    selected?: boolean,
+    isTabStop?: boolean,
+  ) => {
+    const glyph = (
+      <RadioGlyph
+        size={knobProps.sizeToken}
+        borderWidth={radioRingWidth(knobProps.borderRadius.borderWidth)}
+        borderRadius={itemRadius}
+        outlined={knobProps.outlined}
+        {...(knobProps.transition ? { animation: knobProps.transition } : undefined)}
+      >
+        <RadioIndicatorFrame
+          borderRadius={indicatorRadius}
+          backgroundColor={knobProps.textAccentColor}
+          {...(knobProps.transition ? { animation: knobProps.transition } : undefined)}
+        />
+      </RadioGlyph>
+    );
+    return (
+      <RadioItemFrame
+        value={option.value}
+        id={itemId}
+        // Roving tabindex (single tab stop): tamagui's vendored roving-focus
+        // item leaves tabIndex=0 on every radio, so a 3-option group was 3
+        // tab stops. Only the checked radio (or the first enabled one when
+        // none is checked) stays in the page tab order; arrows move + select.
+        {...(isWeb && isTabStop !== undefined ? { tabIndex: isTabStop ? 0 : -1 } : undefined)}
+        borderRadius={itemRadius === 0 ? 0 : 1000}
+        transition={knobProps.transition}
+        disabled={disabled || option.disabled}
+        // LC-40 DISABLED-VISIBLE: ring is text-free chrome — dim it while the
+        // sibling label stays readable (read-only never dims).
+        {...(disabled || option.disabled ? disabledState.chromeKnobProps : undefined)}
+        pointerEvents={readOnly ? "none" : undefined}
+        {...a11y}
+        // RN only exposes the radio to the a11y tree when `accessible` is set;
+        // web keeps Tamagui's role=radio + label association untouched.
+        {...(!isWeb
+          ? {
+              accessible: true,
+              "aria-label": typeof option.label === "string" ? option.label : String(option.value),
+              "aria-checked": selected ?? false,
+            }
+          : {})}
+        {...(stripRadiusFromStateProps(control.hoverKnobProps) && {
+          hoverStyle: {
+            backgroundColor: "transparent",
+            ...stripRadiusFromStateProps(control.hoverKnobProps),
+          },
+        })}
+        {...(stripRadiusFromStateProps(control.pressKnobProps) && {
+          pressStyle: {
+            backgroundColor: "transparent",
+            ...stripRadiusFromStateProps(control.pressKnobProps),
+          },
+        })}
+        {...(stripRadiusFromStateProps(control.focusKnobProps) && {
+          focusStyle: {
+            backgroundColor: "transparent",
+            ...stripRadiusFromStateProps(control.focusKnobProps),
+          },
+        })}
+        {...(stripRadiusFromStateProps(control.focusVisibleKnobProps) && {
+          focusVisibleStyle: {
+            backgroundColor: "transparent",
+            ...stripRadiusFromStateProps(control.focusVisibleKnobProps),
+          },
+        })}
+      >
+        {elevationWrapperProps.elevation ? (
+          <View {...elevationWrapperProps} borderRadius={itemRadius}>
+            {glyph}
+          </View>
+        ) : (
+          glyph
+        )}
+      </RadioItemFrame>
+    );
+  };
+
+  const renderItems = (currentValue: string | undefined, emit: (val: string) => void) => {
     if (children) return children;
     if (!options) return null;
     const Container = orientation === "horizontal" ? XStack : YStack;
+    // Exactly one radio stays tabbable: the checked enabled one, else the
+    // first enabled one (WAI-ARIA radio-group pattern).
+    const checkedEnabled = options.findIndex(
+      (o) => o.value === currentValue && !(disabled || o.disabled),
+    );
+    const tabStopIndex =
+      checkedEnabled >= 0 ? checkedEnabled : options.findIndex((o) => !(disabled || o.disabled));
+
+    if (card) {
+      const layout = getCheckboxCardLayout(knobProps.space);
+      const descriptionSize = getCardDescriptionSize(size || knobProps.sizeToken);
+      return (
+        <Container gap="$2">
+          {options.map((option, index) => {
+            // Include the index so duplicate option values don't produce
+            // duplicate React keys / DOM ids.
+            const itemId = `${id}-${index}-${option.value}`;
+            const labelId = `${itemId}-label`;
+            const descriptionId = option.description ? `${itemId}-description` : undefined;
+            const isSelected = currentValue === option.value;
+            const isDisabled = disabled || option.disabled;
+            return (
+              <CheckboxCardFrame
+                key={`${index}-${option.value}`}
+                active={isSelected}
+                {...layout}
+                borderRadius={knobProps.borderRadius.borderRadius}
+                // LC-40: selection cards dim as chrome (label rides the card).
+                {...(isDisabled ? disabledState.chromeKnobProps : undefined)}
+                // Whole card selects. Clicking the radio itself may also fire
+                // this; both emit the same value, so the double emit is
+                // idempotent (same pattern as CheckboxGroup card).
+                onPress={() => {
+                  if (isDisabled || readOnly) return;
+                  emit(option.value);
+                }}
+              >
+                {renderRadioItem(
+                  option,
+                  itemId,
+                  {
+                    "aria-labelledby": labelId,
+                    ...(descriptionId && { "aria-describedby": descriptionId }),
+                  },
+                  isSelected,
+                  index === tabStopIndex,
+                )}
+                <CheckboxCardContent>
+                  {/* fontWeight after size: the size variant's font weight
+                      would otherwise override the styled bold default */}
+                  <CheckboxCardLabel
+                    id={labelId}
+                    size={(size || knobProps.sizeToken) as FontSizeTokens}
+                    fontWeight="600"
+                  >
+                    {option.label}
+                  </CheckboxCardLabel>
+                  {option.description ? (
+                    <CheckboxCardDescription id={descriptionId} size={descriptionSize}>
+                      {option.description}
+                    </CheckboxCardDescription>
+                  ) : null}
+                </CheckboxCardContent>
+              </CheckboxCardFrame>
+            );
+          })}
+        </Container>
+      );
+    }
+
     return (
       <Container gap="$2">
-        {options.map((option) => {
-          const itemId = `${id}-${option.value}`;
+        {options.map((option, index) => {
+          const itemId = `${id}-${index}-${option.value}`;
           return (
-            <XStack key={option.value} gap="$2" alignItems="center">
-              <RadioItemWithElevation
-                elevationWrapperProps={elevationWrapperProps}
-                itemRadius={itemRadius}
-                value={option.value}
-                id={itemId}
-                size={knobProps.sizeToken}
-                borderWidth={knobProps.borderRadius.borderWidth}
-                borderRadius={itemRadius}
-                outlined={knobProps.outlined}
-                transition={knobProps.transition}
-                disabled={disabled}
-                pointerEvents={readOnly ? "none" : undefined}
-                {...(stripRadiusFromStateProps(control.hoverKnobProps) && {
-                  hoverStyle: {
-                    backgroundColor: formControlColors.background,
-                    borderColor: formControlColors.border,
-                    ...stripRadiusFromStateProps(control.hoverKnobProps),
-                  },
-                })}
-                {...(stripRadiusFromStateProps(control.pressKnobProps) && {
-                  pressStyle: {
-                    backgroundColor: formControlColors.background,
-                    borderColor: formControlColors.border,
-                    ...stripRadiusFromStateProps(control.pressKnobProps),
-                  },
-                })}
-                {...(stripRadiusFromStateProps(control.focusKnobProps) && {
-                  focusStyle: {
-                    backgroundColor: formControlColors.background,
-                    borderColor: formControlColors.border,
-                    ...stripRadiusFromStateProps(control.focusKnobProps),
-                  },
-                })}
-                {...(stripRadiusFromStateProps(control.focusVisibleKnobProps) && {
-                  focusVisibleStyle: {
-                    backgroundColor: formControlColors.background,
-                    borderColor: formControlColors.border,
-                    ...stripRadiusFromStateProps(control.focusVisibleKnobProps),
-                  },
-                })}
-              >
-                <RadioIndicatorFrame
-                  borderRadius={indicatorRadius}
-                  backgroundColor={knobProps.textAccentColor}
-                  {...(knobProps.transition ? { animation: knobProps.transition } : undefined)}
-                />
-              </RadioItemWithElevation>
+            <XStack key={`${index}-${option.value}`} gap="$2" alignItems="center">
+              {renderRadioItem(
+                option,
+                itemId,
+                undefined,
+                currentValue === option.value,
+                index === tabStopIndex,
+              )}
               <Label
                 htmlFor={itemId}
                 size={(size || knobProps.sizeToken) as FontSizeTokens}
@@ -245,26 +465,58 @@ export function RadioGroup({
     handleChange?: (val: string) => void,
     handleBlur?: (...args: any[]) => void,
     hasError?: boolean,
-  ) => (
-    <TamaguiRadioGroup
-      {...radioGroupProps}
-      id={id}
-      defaultValue={radioValue}
-      onValueChange={(val) => {
-        if (disabled || readOnly) return;
-        handleChange?.(val);
-        onValueChange?.(val);
-      }}
-      {...(handleBlur ? { onBlur: handleBlur } : undefined)}
-      aria-required={required || undefined}
-      aria-invalid={hasError || undefined}
-      aria-readonly={readOnly || undefined}
-    >
-      {renderItems()}
-    </TamaguiRadioGroup>
-  );
+  ) => {
+    const emit = (val: string) => {
+      if (disabled || readOnly) return;
+      setInternalValue(val);
+      handleChange?.(val);
+      handleValueChange(val);
+    };
+    // Card mode must be controlled so whole-card press updates the selected
+    // indicator; plain mode keeps defaultValue for existing uncontrolled use.
+    const valueProps = card ? { value: radioValue } : { defaultValue: radioValue };
+
+    // WAI-ARIA radio group: arrow keys move focus AND select the newly
+    // focused radio (Tab entry alone never selects). Tamagui's roving group
+    // moves focus on this same keydown via a deferred focus call, so read
+    // document.activeElement one tick later and activate it — a real click
+    // flows through Tamagui's value machinery (controlled AND uncontrolled).
+    const handleArrowSelect = (e: { key?: string }) => {
+      if (!options || disabled || readOnly) return;
+      const key = e.key;
+      if (key !== "ArrowDown" && key !== "ArrowUp" && key !== "ArrowLeft" && key !== "ArrowRight")
+        return;
+      setTimeout(() => {
+        const active = document.activeElement as HTMLElement | null;
+        if (!active?.id || !active.id.startsWith(`${id}-`)) return;
+        if (active.getAttribute("role") !== "radio") return;
+        if (active.getAttribute("aria-checked") === "true") return;
+        active.click();
+      }, 0);
+    };
+
+    return (
+      <TamaguiRadioGroup
+        {...radioGroupProps}
+        ref={frameRef}
+        id={id}
+        {...valueProps}
+        onValueChange={emit}
+        {...(handleBlur ? { onBlur: handleBlur } : undefined)}
+        {...(isWeb && options && !children
+          ? { onKeyDown: handleArrowSelect as unknown as () => void }
+          : undefined)}
+        aria-required={required || undefined}
+        aria-invalid={hasError || undefined}
+        aria-readonly={readOnly || undefined}
+      >
+        {renderItems(radioValue, emit)}
+      </TamaguiRadioGroup>
+    );
+  };
 
   if (!resolvedForm || !name) {
+    const currentValue = value !== undefined ? value : internalValue;
     return (
       <FieldLayout
         id={id}
@@ -275,8 +527,11 @@ export function RadioGroup({
         helperText={helperText}
         size={size}
         knobProps={knobProps}
+        // LC-40: FieldLayout owns the dimWhole assembly dim (keepLabel pins
+        // the sibling label/helper readable) — it needs the disabled state.
+        disabled={disabled}
       >
-        {renderRadioGroup(value ?? defaultValue, undefined, onBlur, !!error)}
+        {renderRadioGroup(currentValue, undefined, onBlur, !!error)}
       </FieldLayout>
     );
   }
@@ -290,6 +545,8 @@ export function RadioGroup({
     >
       {(field) => {
         const resolvedError = getFieldError(field, error);
+        const fieldValue = field.state.value as string | undefined;
+        const currentValue = value !== undefined ? value : fieldValue;
         return (
           <FieldLayout
             id={id}
@@ -300,9 +557,11 @@ export function RadioGroup({
             helperText={helperText}
             size={size}
             knobProps={knobProps}
+            // LC-40: see standalone branch — FieldLayout carries dimWhole.
+            disabled={disabled}
           >
             {renderRadioGroup(
-              value !== undefined ? value : (field.state.value as string),
+              currentValue,
               (val) => field.handleChange(val as any),
               mergeFieldHandler(field, "handleBlur", onBlur),
               !!resolvedError,

package/src/fields/Rating/Rating.spec.tsx

@@ -1,4 +1,5 @@
 import { describe, expect, it, vi } from "vitest";
+import { fireEvent } from "@testing-library/react";
 import { renderWithProviders } from "@multiplatform.one/test-utils";
 import { Form } from "../../Form";
 import { Rating } from "./index";
@@ -53,6 +54,49 @@ describe("Rating", () => {
       );
       expect(result.findTextElement("Disabled")).toBeDefined();
     });
+
+    // UX-009 / Axiom 13 ONE BODY: the contract must be usable bare.
+    it("renders bare without starIcon — package default star, no crash", () => {
+      const result = renderWithProviders(<Rating label="Bare" value={0.6} />);
+      const stars = result.container.querySelectorAll("[data-rating-star]");
+      expect(stars.length).toBe(5);
+      // Default Phosphor star renders an svg glyph inside every star slot
+      expect(result.container.querySelectorAll("[data-rating-star] svg").length).toBe(5);
+    });
+
+    // UX-009 / DG-A11Y: stars are keyboard-focusable and operable.
+    it("stars form one roving tab stop and activate with Enter/Space", () => {
+      const onChange = vi.fn();
+      const result = renderWithProviders(<Rating label="Kbd" value={0.4} onChange={onChange} />);
+      const stars = Array.from(result.container.querySelectorAll("[data-rating-star]"));
+      expect(stars.length).toBe(5);
+      const tabStops = stars.filter((s) => s.getAttribute("tabindex") === "0");
+      // Exactly one tab stop (roving) — the committed value star (2 of 5)
+      expect(tabStops.length).toBe(1);
+      expect(tabStops[0]?.getAttribute("data-rating-index")).toBe("2");
+      // Every other star stays reachable by arrows (tabindex -1, not absent)
+      for (const star of stars) {
+        expect(star.getAttribute("tabindex")).toMatch(/^(0|-1)$/);
+      }
+      // Enter on star 4 commits 4/5
+      const star4 = result.container.querySelector("[data-rating-index='4']") as HTMLElement;
+      fireEvent.keyDown(star4, { key: "Enter" });
+      expect(onChange).toHaveBeenCalledWith(0.8);
+      // Space on the current star (2) toggles the rating off
+      const star2 = result.container.querySelector("[data-rating-index='2']") as HTMLElement;
+      fireEvent.keyDown(star2, { key: " " });
+      expect(onChange).toHaveBeenCalledWith(0);
+    });
+
+    it("disabled stars drop out of the tab order", () => {
+      const result = renderWithProviders(<Rating label="Disabled" value={0.4} disabled />);
+      const stars = Array.from(result.container.querySelectorAll("[data-rating-star]"));
+      expect(stars.length).toBe(5);
+      for (const star of stars) {
+        expect(star.getAttribute("tabindex")).toBeNull();
+        expect(star.getAttribute("aria-disabled")).toBe("true");
+      }
+    });
   });
 
   describe("with form context", () => {