@microbit/ui 0.0.0-gray.ramp.92 → 0.0.0-gray.ramp.v2.106

package/src/Radio.tsx

@@ -7,38 +7,11 @@ import { ReactNode } from "react";
 import {
   Radio as RACRadio,
   RadioProps as RACRadioProps,
-  RadioGroup as RACRadioGroup,
-  RadioGroupProps as RACRadioGroupProps,
 } from "react-aria-components";
 import { css, cx } from "styled-system/css";
 import { radio, RadioVariantProps } from "styled-system/recipes";
 import { SystemStyleObject } from "styled-system/types";
 
-export interface RadioGroupProps
-  extends Omit<RACRadioGroupProps, "className" | "style"> {
-  /** Per-instance style overrides, merged after the recipe. */
-  css?: SystemStyleObject;
-  className?: string;
-}
-
-/**
- * RadioGroup — react-aria-components <RadioGroup> for a set of Radios. Carries
- * no styling of its own: compose with Stack for layout, as Chakra call sites
- * did.
- */
-export const RadioGroup = ({
-  css: cssProp,
-  className,
-  ...rest
-}: RadioGroupProps) => {
-  return (
-    <RACRadioGroup
-      className={cx(cssProp ? css(cssProp) : undefined, className)}
-      {...rest}
-    />
-  );
-};
-
 export interface RadioProps
   extends Omit<RACRadioProps, "className" | "children" | "style">,
     RadioVariantProps {

package/src/RadioGroup.tsx

@@ -0,0 +1,69 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import { ReactNode } from "react";
+import {
+  RadioGroup as RACRadioGroup,
+  RadioGroupProps as RACRadioGroupProps,
+} from "react-aria-components";
+import { css, cx } from "styled-system/css";
+import { SystemStyleObject } from "styled-system/types";
+import { FieldLabel, FieldSupport, FieldSupportProps } from "./Field";
+
+export interface RadioGroupProps
+  extends Omit<RACRadioGroupProps, "className" | "style">,
+    FieldSupportProps {
+  /**
+   * Visible label for the group (Chakra's FormLabel above it). Use
+   * `aria-label` instead where the design has none.
+   */
+  label?: ReactNode;
+  /** Label style overrides. */
+  labelCss?: SystemStyleObject;
+  /** Per-instance style overrides, merged after the recipe. */
+  css?: SystemStyleObject;
+  className?: string;
+}
+
+/**
+ * RadioGroup — react-aria-components <RadioGroup> for a set of Radios. Beyond
+ * the optional field chrome (label/helperText/errorMessage — Chakra's
+ * FormControl parts) it carries no styling of its own: compose with Stack for
+ * layout, as Chakra call sites did.
+ */
+export const RadioGroup = ({
+  label,
+  labelCss,
+  helperText,
+  errorMessage,
+  helperTextCss,
+  css: cssProp,
+  className,
+  children,
+  ...rest
+}: RadioGroupProps) => {
+  return (
+    <RACRadioGroup
+      className={cx(cssProp ? css(cssProp) : undefined, className)}
+      {...rest}
+    >
+      {(renderProps) => (
+        <>
+          {label != null && (
+            <FieldLabel isRequired={rest.isRequired} css={labelCss}>
+              {label}
+            </FieldLabel>
+          )}
+          {typeof children === "function" ? children(renderProps) : children}
+          <FieldSupport
+            helperText={helperText}
+            errorMessage={errorMessage}
+            helperTextCss={helperTextCss}
+          />
+        </>
+      )}
+    </RACRadioGroup>
+  );
+};

package/src/Select.recipe.ts

@@ -23,13 +23,16 @@ const transitionCommon =
  * Apps restyle it through the `variant` group — classroom's `classroom`
  * variant is the rounded pill its join form uses.
  *
+ * The label is not a slot here: it comes from the `field` recipe, as every
+ * other labelled field's does. The only thing that costs is a per-`variant`
+ * label style — restyle the control and let the label match the family.
+ *
  * Registered in the base preset (base-preset.ts).
  */
 export const select = defineSlotRecipe({
   className: "select",
   slots: [
     "root",
-    "label",
     "trigger",
     "value",
     "indicator",
@@ -40,17 +43,11 @@ export const select = defineSlotRecipe({
     "empty",
   ],
   base: {
-    root: {
-      display: "flex",
-      flexDirection: "column",
-      width: "100%",
-    },
-    label: {
-      fontSize: "md",
-      fontWeight: "medium",
-      marginEnd: "3",
-      mb: "2",
-    },
+    // No layout here: the component wears the `field` recipe's root alongside
+    // this slot, and that recipe is the single owner of field-root layout
+    // (else `labelPosition` would fight this slot over `flexDirection`). The
+    // slot stays for apps and variants to target.
+    root: {},
     trigger: {
       display: "flex",
       alignItems: "center",
@@ -70,11 +67,8 @@ export const select = defineSlotRecipe({
       // stepping darker. The dropdown card below keeps the light gray.200 —
       // it's a surface edge, not a form-control boundary.
       borderColor: "gray.400",
-      borderRadius: "md",
       bg: "white",
       color: "inherit",
-      h: "10",
-      px: "4",
       // As the input recipe, so a Select, a NativeSelect and a TextField in one
       // form all tint together on hover. (react-aria's TextField has no hover
       // effect, but matching the family beats matching their docs.)
@@ -210,4 +204,17 @@ export const select = defineSlotRecipe({
       color: "gray.600",
     },
   },
+  variants: {
+    // The `input` recipe's size ladder, step for step, so a Select sits level
+    // with a TextField beside it at every size. The indicator is em-sized and
+    // scales free; the dropdown card keeps one density across sizes.
+    size: {
+      lg: { trigger: { fontSize: "lg", px: "4", h: "12", borderRadius: "md" } },
+      md: { trigger: { fontSize: "md", px: "4", h: "10", borderRadius: "md" } },
+      sm: { trigger: { fontSize: "sm", px: "3", h: "8", borderRadius: "sm" } },
+    },
+  },
+  defaultVariants: {
+    size: "md",
+  },
 });

package/src/Select.tsx

@@ -6,7 +6,6 @@
 import { createContext, ReactNode, useContext } from "react";
 import {
   Button as RACButton,
-  Label as RACLabel,
   ListBox as RACListBox,
   ListBoxItem as RACListBoxItem,
   ListBoxItemProps as RACListBoxItemProps,
@@ -18,8 +17,14 @@ import {
 } from "react-aria-components";
 import { RiArrowDownSLine } from "react-icons/ri";
 import { css, cx } from "styled-system/css";
-import { select, SelectVariantProps } from "styled-system/recipes";
+import { field, select, SelectVariantProps } from "styled-system/recipes";
 import { SystemStyleObject } from "styled-system/types";
+import {
+  FieldLabel,
+  FieldLayoutProps,
+  FieldSupport,
+  FieldSupportProps,
+} from "./Field";
 import { Icon } from "./Icon";
 
 export type SelectSlots = ReturnType<typeof select>;
@@ -37,9 +42,13 @@ export interface SelectProps<T extends object>
       RACSelectProps<T>,
       "className" | "children" | "style" | "placeholder"
     >,
-    SelectVariantProps {
+    SelectVariantProps,
+    FieldSupportProps,
+    FieldLayoutProps {
   /** Visible label. Use `aria-label` instead where the design has none. */
   label?: ReactNode;
+  /** Label style overrides. */
+  labelCss?: SystemStyleObject;
   /** Shown in the trigger while nothing is chosen (Chakra's placeholder). */
   placeholder?: string;
   /** `SelectOption`s. */
@@ -59,8 +68,8 @@ export interface SelectProps<T extends object>
    * while positioning, which beats any class.
    */
   maxHeight?: number;
-  /** Per-instance overrides for the trigger. */
-  css?: SystemStyleObject;
+  /** Per-instance overrides for the trigger (the button the value sits in). */
+  triggerCss?: SystemStyleObject;
   /** Per-instance overrides for the dropdown card. */
   contentCss?: SystemStyleObject;
   className?: string;
@@ -73,12 +82,17 @@ export interface SelectProps<T extends object>
  */
 export const Select = <T extends object>({
   label,
+  labelCss,
   placeholder,
   children,
   indicator,
   placement = "bottom start",
   maxHeight,
-  css: cssProp,
+  helperText,
+  errorMessage,
+  helperTextCss,
+  labelPosition,
+  triggerCss,
   contentCss,
   className,
   ...props
@@ -87,15 +101,28 @@ export const Select = <T extends object>({
   // groups to the recipe and they have to reach it (playbook gotcha #37).
   const [variantProps, rest] = select.splitVariantProps(props);
   const slots = select(variantProps);
+  const fieldSlots = field({ size: variantProps.size, labelPosition });
   return (
     <SelectSlotProvider value={slots}>
       <RACSelect
         {...(rest as RACSelectProps<T>)}
-        className={cx(slots.root, className)}
+        className={cx(fieldSlots.root, slots.root, className)}
       >
-        {label != null && <RACLabel className={slots.label}>{label}</RACLabel>}
+        {label != null && (
+          <FieldLabel
+            size={variantProps.size}
+            labelPosition={labelPosition}
+            isRequired={props.isRequired}
+            css={labelCss}
+          >
+            {label}
+          </FieldLabel>
+        )}
         <RACButton
-          className={cx(slots.trigger, cssProp ? css(cssProp) : undefined)}
+          className={cx(
+            slots.trigger,
+            triggerCss ? css(triggerCss) : undefined,
+          )}
         >
           <SelectValue className={slots.value}>
             {({ isPlaceholder, defaultChildren }) =>
@@ -118,6 +145,12 @@ export const Select = <T extends object>({
         >
           <RACListBox className={slots.list}>{children}</RACListBox>
         </Popover>
+        <FieldSupport
+          helperText={helperText}
+          errorMessage={errorMessage}
+          helperTextCss={helperTextCss}
+          labelPosition={labelPosition}
+        />
       </RACSelect>
     </SelectSlotProvider>
   );

package/src/SharedUIProvider.tsx

@@ -4,6 +4,9 @@
  * SPDX-License-Identifier: MIT
  */
 import { createContext, ReactNode, useContext, useMemo } from "react";
+import { I18nProvider } from "react-aria-components";
+import { IntlContext } from "react-intl";
+import { racLocale } from "./rac-locale";
 
 /**
  * Registers the close function of the currently open dismissable overlay, or
@@ -21,27 +24,44 @@ const SharedUIContext = createContext<SharedUIContextValue | null>(null);
 
 export interface SharedUIProviderProps {
   overlayCloseRegistrar?: OverlayCloseRegistrar;
+  /**
+   * Locale for react-aria's own built-in strings. Defaults to the surrounding
+   * IntlProvider's locale, which is what apps want: pass this only where the
+   * two must differ.
+   */
+  locale?: string;
   children: ReactNode;
 }
 
 /**
- * SharedUIProvider — the app-side installation point for optional shared-ui
- * integrations. Currently that is only the overlay-close registrar, so apps
- * without one can omit the provider entirely. Localized strings come from
- * react-intl: an IntlProvider must be mounted above shared-ui components
- * (see the package README for merging this package's message catalogs).
+ * SharedUIProvider — the app-side installation point for shared-ui
+ * integrations: the optional overlay-close registrar, and the locale for
+ * react-aria's built-in strings.
+ *
+ * This package's own strings come from react-intl, so an IntlProvider must be
+ * mounted above shared-ui components (see the package README). react-aria
+ * translates its built-in strings itself, from its own bundled catalogs, and
+ * without this provider it picks the locale from the browser rather than from
+ * the app's language setting — mount it inside the IntlProvider so the two
+ * agree.
  */
 export const SharedUIProvider = ({
   overlayCloseRegistrar,
+  locale,
   children,
 }: SharedUIProviderProps) => {
+  // Read the context rather than calling useIntl(), which throws when there is
+  // no IntlProvider: react-aria falls back to the browser locale, as before.
+  const intlLocale = useContext(IntlContext)?.locale;
   const value = useMemo(
     () => ({ overlayCloseRegistrar }),
     [overlayCloseRegistrar],
   );
   return (
     <SharedUIContext.Provider value={value}>
-      {children}
+      <I18nProvider locale={racLocale(locale ?? intlLocale)}>
+        {children}
+      </I18nProvider>
     </SharedUIContext.Provider>
   );
 };

package/src/Skeleton.tsx

@@ -17,7 +17,9 @@ import { SystemStyleObject } from "styled-system/types";
  */
 const skeletonBase: SystemStyleObject = {
   "--skeleton-start-color": "token(colors.gray.100)",
-  "--skeleton-end-color": "token(colors.gray.400)",
+  // 350, not 400: decorative fill weight, as the Avatar default
+  // (docs/gray-ramp.md).
+  "--skeleton-end-color": "token(colors.gray.350)",
   background: "var(--skeleton-start-color)",
   borderColor: "var(--skeleton-end-color)",
   opacity: 0.7,

package/src/Switch.recipe.ts

@@ -72,6 +72,24 @@ export const switchRecipe = defineSlotRecipe({
     },
   },
   variants: {
+    // `start` puts the label first and the control at the row's end — the
+    // settings-row pattern (a preference name beside its switch), the toggle
+    // counterpart of the field recipe's `labelPosition="side"`. Values are
+    // start/end rather than top/side because the default label is already
+    // beside the control, after it. The label keeps an end margin so a long
+    // translation can't butt against the track (the SelectFormControl
+    // lesson — see the field-chrome roadmap bullet).
+    labelPosition: {
+      end: {},
+      start: {
+        root: {
+          flexDirection: "row-reverse",
+          justifyContent: "space-between",
+          width: "100%",
+        },
+        label: { marginStart: "0", marginEnd: "3" },
+      },
+    },
     // Chakra's Switch size scale (track width x height; the selected-thumb
     // translate is the difference between them).
     size: {
@@ -103,5 +121,6 @@ export const switchRecipe = defineSlotRecipe({
   },
   defaultVariants: {
     size: "md",
+    labelPosition: "end",
   },
 });

package/src/Switch.tsx

@@ -3,7 +3,7 @@
  *
  * SPDX-License-Identifier: MIT
  */
-import { ReactNode } from "react";
+import { ReactNode, useId } from "react";
 import {
   Switch as RACSwitch,
   SwitchProps as RACSwitchProps,
@@ -11,6 +11,7 @@ import {
 import { css, cx } from "styled-system/css";
 import { switchRecipe, SwitchRecipeVariantProps } from "styled-system/recipes";
 import { SystemStyleObject } from "styled-system/types";
+import { FieldHelperText } from "./Field";
 
 export interface SwitchProps
   extends Omit<RACSwitchProps, "className" | "children" | "style">,
@@ -19,24 +20,43 @@ export interface SwitchProps
   css?: SystemStyleObject;
   className?: string;
   children?: ReactNode;
+  /**
+   * Help text below the switch, wired to its `aria-describedby` — the same
+   * chrome the labelled fields' `helperText` renders. With it the component
+   * gains a wrapping `<div>`, so the switch-plus-text moves as one block.
+   */
+  helperText?: ReactNode;
+  /** Per-instance style overrides for the helper text. */
+  helperTextCss?: SystemStyleObject;
 }
 
 /**
  * Switch — react-aria-components <Switch> styled like Chakra's switch.
  * Children render as the label; pass `aria-label` for label-less switches.
+ * `labelPosition="start"` is the settings-row layout: label first, switch at
+ * the row's end.
  */
 export const Switch = ({
   size,
+  labelPosition,
   css: cssProp,
   className,
   children,
+  helperText,
+  helperTextCss,
   ...rest
 }: SwitchProps) => {
-  const slots = switchRecipe({ size });
-  return (
+  const slots = switchRecipe({ size, labelPosition });
+  const helperId = useId();
+  const describedBy =
+    [rest["aria-describedby"], helperText != null ? helperId : undefined]
+      .filter(Boolean)
+      .join(" ") || undefined;
+  const switchElement = (
     <RACSwitch
       className={cx(slots.root, cssProp ? css(cssProp) : undefined, className)}
       {...rest}
+      aria-describedby={describedBy}
     >
       {({ isSelected, isFocusVisible, isDisabled }) => {
         const state = {
@@ -59,4 +79,15 @@ export const Switch = ({
       }}
     </RACSwitch>
   );
+  if (helperText == null) {
+    return switchElement;
+  }
+  return (
+    <div>
+      {switchElement}
+      <FieldHelperText id={helperId} css={helperTextCss}>
+        {helperText}
+      </FieldHelperText>
+    </div>
+  );
 };

package/src/TextField.tsx

@@ -5,31 +5,31 @@
  */
 import { FocusEvent, forwardRef, ReactNode } from "react";
 import {
-  FieldError,
   Input as RACInput,
-  Label as RACLabel,
-  Text as RACText,
   TextField as RACTextField,
   TextFieldProps as RACTextFieldProps,
 } from "react-aria-components";
-import { css, cx } from "styled-system/css";
 import { field, input, InputVariantProps } from "styled-system/recipes";
 import { SystemStyleObject } from "styled-system/types";
+import {
+  FieldLabel,
+  FieldLayoutProps,
+  FieldSupport,
+  FieldSupportProps,
+} from "./Field";
 
 export interface TextFieldProps
   extends Omit<
       RACTextFieldProps,
       "className" | "children" | "style" | "onFocus" | "onBlur"
     >,
-    InputVariantProps {
+    InputVariantProps,
+    FieldSupportProps,
+    FieldLayoutProps {
   /** Visible label (Chakra's FormLabel; asterisk added when `isRequired`). */
   label: ReactNode;
-  /** Help text below the input (Chakra's FormHelperText). */
-  helperText?: ReactNode;
-  /** Shown below the input when `isInvalid` (Chakra's FormErrorMessage). */
-  errorMessage?: ReactNode;
-  /** Per-instance style overrides for the helper text. */
-  helperTextCss?: SystemStyleObject;
+  /** Label style overrides. */
+  labelCss?: SystemStyleObject;
   onFocus?: (e: FocusEvent<HTMLInputElement>) => void;
   /** Input autocapitalize attribute (react-aria's TextField omits it). */
   autoCapitalize?: "off" | "none" | "on" | "sentences" | "words" | "characters";
@@ -44,9 +44,11 @@ export const TextField = forwardRef<HTMLInputElement, TextFieldProps>(
   function TextField(
     {
       label,
+      labelCss,
       helperText,
       errorMessage,
       helperTextCss,
+      labelPosition,
       onFocus,
       autoCapitalize,
       ...props
@@ -56,35 +58,29 @@ export const TextField = forwardRef<HTMLInputElement, TextFieldProps>(
     // As Input: forward every recipe variant group, not just `size`, so a
     // preset that adds one keeps working.
     const [variantProps, rest] = input.splitVariantProps(props);
-    const slots = field();
+    const slots = field({ size: variantProps.size, labelPosition });
     return (
       <RACTextField {...rest} className={slots.root}>
-        <RACLabel className={slots.label}>
+        <FieldLabel
+          size={variantProps.size}
+          labelPosition={labelPosition}
+          isRequired={rest.isRequired}
+          css={labelCss}
+        >
           {label}
-          {rest.isRequired ? (
-            <span aria-hidden className={slots.requiredIndicator}>
-              *
-            </span>
-          ) : null}
-        </RACLabel>
+        </FieldLabel>
         <RACInput
           ref={ref}
           className={input(variantProps)}
           onFocus={onFocus}
           autoCapitalize={autoCapitalize}
         />
-        {helperText && (
-          <RACText
-            slot="description"
-            className={cx(
-              slots.helperText,
-              helperTextCss ? css(helperTextCss) : undefined,
-            )}
-          >
-            {helperText}
-          </RACText>
-        )}
-        <FieldError className={slots.errorMessage}>{errorMessage}</FieldError>
+        <FieldSupport
+          helperText={helperText}
+          errorMessage={errorMessage}
+          helperTextCss={helperTextCss}
+          labelPosition={labelPosition}
+        />
       </RACTextField>
     );
   },