@microbit/ui 0.1.0-alpha.16 → 0.1.0-alpha.18

package/src/RadioGroup.tsx

@@ -0,0 +1,64 @@
+/**
+ * (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;
+  /** 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,
+  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}>{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",
@@ -67,11 +64,8 @@ export const select = defineSlotRecipe({
       transitionDuration: "normal",
       border: "1px solid",
       borderColor: "gray.200",
-      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.)
@@ -82,9 +76,12 @@ export const select = defineSlotRecipe({
       // `> &` rather than a descendant selector, so an app's own invalid form
       // wrapper cannot paint every control inside it red.
       //
-      // Declared after hover and before focus so red beats a hover tint and
-      // the focus ring beats red, as in the input recipe.
-      "[data-invalid] > &": {
+      // Doubled `&` for the same reason as the input recipe: hover, invalid and
+      // focus all set `borderColor`, and Panda sorts state rules by its own
+      // pseudo-class table rather than declaration order, so hover would win
+      // these ties. The repeated `&` makes the hover < invalid < focus ladder a
+      // matter of specificity instead.
+      "[data-invalid] > &&": {
         borderColor: "danger.500",
         boxShadow: "0 0 0 1px token(colors.danger.500)",
       },
@@ -98,7 +95,7 @@ export const select = defineSlotRecipe({
       // focus moves to an option (aria-activedescendant) — which strips RAC's
       // attribute for as long as the list has an active option, real focus
       // never having left. Select's trigger holds no input, so it can't match.
-      "&[data-focus-visible], &:has(input:focus)": {
+      "&&&[data-focus-visible], &&&:has(input:focus)": {
         boxShadow: "0 0 0 1px token(colors.focusBorder)",
         borderColor: "focusBorder",
         outline: "2px solid transparent",
@@ -204,4 +201,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,7 +42,9 @@ 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;
   /** Shown in the trigger while nothing is chosen (Chakra's placeholder). */
@@ -59,8 +66,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;
@@ -78,7 +85,11 @@ export const Select = <T extends object>({
   indicator,
   placement = "bottom start",
   maxHeight,
-  css: cssProp,
+  helperText,
+  errorMessage,
+  helperTextCss,
+  labelPosition,
+  triggerCss,
   contentCss,
   className,
   ...props
@@ -87,15 +98,27 @@ 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}
+          >
+            {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 +141,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/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,28 @@
  */
 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;
   onFocus?: (e: FocusEvent<HTMLInputElement>) => void;
   /** Input autocapitalize attribute (react-aria's TextField omits it). */
   autoCapitalize?: "off" | "none" | "on" | "sentences" | "words" | "characters";
@@ -47,6 +44,7 @@ export const TextField = forwardRef<HTMLInputElement, TextFieldProps>(
       helperText,
       errorMessage,
       helperTextCss,
+      labelPosition,
       onFocus,
       autoCapitalize,
       ...props
@@ -56,35 +54,28 @@ 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}
+        >
           {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>
     );
   },

package/src/base-preset.ts

@@ -24,6 +24,7 @@ import {
 // Config recipes are colocated with the shared-ui components they style; this
 // preset registers them so Panda merges them at codegen time.
 import { avatar } from "./Avatar.recipe";
+import { breadcrumb } from "./Breadcrumb.recipe";
 import { button } from "./Button.recipe";
 import { card } from "./Card.recipe";
 import { checkbox } from "./Checkbox.recipe";
@@ -41,7 +42,7 @@ import { switchRecipe } from "./Switch.recipe";
 import { dialog } from "./Modal.recipe";
 import { text } from "./Text.recipe";
 import { tooltip } from "./Tooltip.recipe";
-import { field } from "./TextField.recipe";
+import { field } from "./Field.recipe";
 import { toast } from "./Toast.recipe";
 
 /**
@@ -175,6 +176,12 @@ export const basePreset = definePreset({
         // follows; OSS language buttons are brand blue.)
         languageText: { value: "{colors.brand.500}" },
         languageTextHover: { value: "{colors.brand.600}" },
+        // The `label`/`subtitle` heading variants' colour (page-title chrome).
+        // classroom and data-microbit-org carried byte-identical variants with
+        // a hardcoded #cd0365 — the brand deep pink, which is data's
+        // `pink.500`; both override this to it. The OSS default follows the
+        // languageText precedent: the primary interactive brand.
+        headingAccent: { value: "{colors.brand.500}" },
         // The `primary`/`secondary` button variants' colours. Two brand
         // idioms exist in the family: brand-coloured buttons (ml-trainer,
         // python-editor — the defaults below) and a black-on-white system
@@ -216,6 +223,7 @@ export const basePreset = definePreset({
     },
     slotRecipes: {
       avatar,
+      breadcrumb,
       card,
       checkbox,
       dialog,
@@ -296,9 +304,11 @@ export const basePreset = definePreset({
       // as a runtime prop, so generate the breakpoint-prefixed variants too.
       dialog: [{ size: ["*"], responsive: true }, { centered: ["*"] }],
       drawer: ["*"],
+      field: ["*"],
       gridList: ["*"],
       listBox: ["*"],
       input: ["*"],
+      numberField: ["*"],
       radio: ["*"],
       select: ["*"],
       switchRecipe: ["*"],

package/src/index.ts

@@ -10,20 +10,25 @@
  */
 export * from "./system";
 export * from "./Avatar";
+export * from "./Breadcrumb";
 export * from "./Button";
 export * from "./LinkButton";
 export * from "./ButtonGroup";
 export * from "./Card";
 export * from "./Checkbox";
+export * from "./CheckboxGroup";
+export * from "./Field";
 export * from "./IconButton";
 export * from "./Image";
 export * from "./Input";
 export * from "./InputGroup";
 export * from "./LinkBox";
 export * from "./NativeSelect";
+export * from "./NativeSelectField";
 export * from "./NumberField";
 export * from "./ProgressBar";
 export * from "./Radio";
+export * from "./RadioGroup";
 export * from "./Skeleton";
 export * from "./Slide";
 export * from "./Slider";

package/src/rac-locale.ts

@@ -0,0 +1,33 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+
+/**
+ * Sanitizes one of our locale ids for react-aria's I18nProvider.
+ *
+ * No mapping is needed to reach react-aria's own strings: its fallback chain
+ * runs exact tag, then the bare language, then any variant of that language,
+ * then en-US — so `fr` finds fr-FR, `ja` finds ja-JP, and the locales it has no
+ * strings for at all (ca, cy, ga-IE, and our `lol` pseudo-locale) land on
+ * English.
+ *
+ * What does need handling is a malformed tag: I18nProvider's explicit-locale
+ * path feeds it straight to `new Intl.Locale` with no guard of its own (unlike
+ * its browser-locale path), so a bad tag throws during render and takes out the
+ * tree. Only reachable through SharedUIProvider's `locale` prop in practice —
+ * react-intl rejects a malformed locale before we could read it from context.
+ */
+export const racLocale = (locale: string | undefined): string | undefined => {
+  if (locale === undefined) {
+    // Leave react-aria on its browser-locale default.
+    return undefined;
+  }
+  try {
+    Intl.DateTimeFormat.supportedLocalesOf([locale]);
+  } catch {
+    return "en-GB";
+  }
+  return locale;
+};