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

package/src/NumberField.tsx

@@ -8,33 +8,41 @@ import {
   Button as RACButton,
   Group as RACGroup,
   Input as RACInput,
-  Label as RACLabel,
   NumberField as RACNumberField,
   NumberFieldProps as RACNumberFieldProps,
 } from "react-aria-components";
 import { RiArrowDownSFill, RiArrowUpSFill } from "react-icons/ri";
 import { css, cx } from "styled-system/css";
-import { field, input, numberField } from "styled-system/recipes";
+import {
+  field,
+  input,
+  InputVariantProps,
+  numberField,
+} from "styled-system/recipes";
 import { SystemStyleObject } from "styled-system/types";
 import {
-  FieldRequiredIndicator,
+  FieldLabel,
+  FieldLayoutProps,
   FieldSupport,
   FieldSupportProps,
-} from "./FieldSupport";
+} from "./Field";
 import { Icon } from "./Icon";
 
 export interface NumberFieldProps
   extends Omit<RACNumberFieldProps, "className" | "children" | "style">,
-    FieldSupportProps {
+    InputVariantProps,
+    FieldSupportProps,
+    FieldLayoutProps {
   /** Visible label (optional; otherwise pass `aria-label`). */
   label?: ReactNode;
-  /** Root style overrides (e.g. row layout for label-beside-field forms). */
-  css?: SystemStyleObject;
+  /** Root style overrides (for a label-beside-field row, prefer
+   * `labelPosition="side"`). */
+  rootCss?: SystemStyleObject;
   /** Label style overrides. */
   labelCss?: SystemStyleObject;
   /** Group (input + steppers) style overrides — set `width` here. */
   groupCss?: SystemStyleObject;
-  /** Input style overrides (e.g. a smaller size than the recipe's md). */
+  /** Input style overrides (for sizing, prefer the `size` prop). */
   inputCss?: SystemStyleObject;
 }
 
@@ -51,31 +59,38 @@ export const NumberField = forwardRef<HTMLInputElement, NumberFieldProps>(
       helperText,
       errorMessage,
       helperTextCss,
-      css: cssProp,
+      rootCss,
       labelCss,
       groupCss,
       inputCss,
-      ...rest
+      labelPosition,
+      ...props
     },
     ref,
   ) {
-    const slots = numberField();
-    const fieldSlots = field();
+    // 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 = numberField({ size: variantProps.size });
+    const fieldSlots = field({ size: variantProps.size, labelPosition });
     return (
       <RACNumberField
         {...rest}
-        className={cx(slots.root, cssProp ? css(cssProp) : undefined)}
+        className={cx(
+          fieldSlots.root,
+          slots.root,
+          rootCss ? css(rootCss) : undefined,
+        )}
       >
         {label != null && (
-          <RACLabel
-            className={cx(
-              fieldSlots.label,
-              labelCss ? css(labelCss) : undefined,
-            )}
+          <FieldLabel
+            size={variantProps.size}
+            labelPosition={labelPosition}
+            isRequired={rest.isRequired}
+            css={labelCss}
           >
             {label}
-            {rest.isRequired ? <FieldRequiredIndicator /> : null}
-          </RACLabel>
+          </FieldLabel>
         )}
         <RACGroup
           className={cx(slots.group, groupCss ? css(groupCss) : undefined)}
@@ -83,8 +98,9 @@ export const NumberField = forwardRef<HTMLInputElement, NumberFieldProps>(
           <RACInput
             ref={ref}
             className={cx(
-              input(),
-              // Room for the stepper column.
+              input(variantProps),
+              // Room for the stepper column (constant across sizes, as the
+              // stepper's width is).
               css({ paddingEnd: "6" }, inputCss),
             )}
           />
@@ -101,6 +117,7 @@ export const NumberField = forwardRef<HTMLInputElement, NumberFieldProps>(
           helperText={helperText}
           errorMessage={errorMessage}
           helperTextCss={helperTextCss}
+          labelPosition={labelPosition}
         />
       </RACNumberField>
     );

package/src/Radio.tsx

@@ -5,74 +5,12 @@
  */
 import { ReactNode } from "react";
 import {
-  Label as RACLabel,
   Radio as RACRadio,
   RadioProps as RACRadioProps,
-  RadioGroup as RACRadioGroup,
-  RadioGroupProps as RACRadioGroupProps,
 } from "react-aria-components";
 import { css, cx } from "styled-system/css";
-import { field, radio, RadioVariantProps } from "styled-system/recipes";
+import { radio, RadioVariantProps } from "styled-system/recipes";
 import { SystemStyleObject } from "styled-system/types";
-import {
-  FieldRequiredIndicator,
-  FieldSupport,
-  FieldSupportProps,
-} from "./FieldSupport";
-
-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 && (
-            <RACLabel className={field().label}>
-              {label}
-              {rest.isRequired ? <FieldRequiredIndicator /> : null}
-            </RACLabel>
-          )}
-          {typeof children === "function" ? children(renderProps) : children}
-          <FieldSupport
-            helperText={helperText}
-            errorMessage={errorMessage}
-            helperTextCss={helperTextCss}
-          />
-        </>
-      )}
-    </RACRadioGroup>
-  );
-};
 
 export interface RadioProps
   extends Omit<RACRadioProps, "className" | "children" | "style">,

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.)
@@ -207,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,13 +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 {
-  FieldRequiredIndicator,
+  FieldLabel,
+  FieldLayoutProps,
   FieldSupport,
   FieldSupportProps,
-} from "./FieldSupport";
+} from "./Field";
 import { Icon } from "./Icon";
 
 export type SelectSlots = ReturnType<typeof select>;
@@ -43,7 +43,8 @@ export interface SelectProps<T extends object>
       "className" | "children" | "style" | "placeholder"
     >,
     SelectVariantProps,
-    FieldSupportProps {
+    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). */
@@ -65,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;
@@ -87,7 +88,8 @@ export const Select = <T extends object>({
   helperText,
   errorMessage,
   helperTextCss,
-  css: cssProp,
+  labelPosition,
+  triggerCss,
   contentCss,
   className,
   ...props
@@ -96,20 +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}>
+          <FieldLabel
+            size={variantProps.size}
+            labelPosition={labelPosition}
+            isRequired={props.isRequired}
+          >
             {label}
-            {props.isRequired ? <FieldRequiredIndicator /> : null}
-          </RACLabel>
+          </FieldLabel>
         )}
         <RACButton
-          className={cx(slots.trigger, cssProp ? css(cssProp) : undefined)}
+          className={cx(
+            slots.trigger,
+            triggerCss ? css(triggerCss) : undefined,
+          )}
         >
           <SelectValue className={slots.value}>
             {({ isPlaceholder, defaultChildren }) =>
@@ -136,6 +145,7 @@ export const Select = <T extends object>({
           helperText={helperText}
           errorMessage={errorMessage}
           helperTextCss={helperTextCss}
+          labelPosition={labelPosition}
         />
       </RACSelect>
     </SelectSlotProvider>

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

@@ -6,16 +6,16 @@
 import { FocusEvent, forwardRef, ReactNode } from "react";
 import {
   Input as RACInput,
-  Label as RACLabel,
   TextField as RACTextField,
   TextFieldProps as RACTextFieldProps,
 } from "react-aria-components";
 import { field, input, InputVariantProps } from "styled-system/recipes";
 import {
-  FieldRequiredIndicator,
+  FieldLabel,
+  FieldLayoutProps,
   FieldSupport,
   FieldSupportProps,
-} from "./FieldSupport";
+} from "./Field";
 
 export interface TextFieldProps
   extends Omit<
@@ -23,7 +23,8 @@ export interface TextFieldProps
       "className" | "children" | "style" | "onFocus" | "onBlur"
     >,
     InputVariantProps,
-    FieldSupportProps {
+    FieldSupportProps,
+    FieldLayoutProps {
   /** Visible label (Chakra's FormLabel; asterisk added when `isRequired`). */
   label: ReactNode;
   onFocus?: (e: FocusEvent<HTMLInputElement>) => void;
@@ -43,6 +44,7 @@ export const TextField = forwardRef<HTMLInputElement, TextFieldProps>(
       helperText,
       errorMessage,
       helperTextCss,
+      labelPosition,
       onFocus,
       autoCapitalize,
       ...props
@@ -52,13 +54,16 @@ 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 ? <FieldRequiredIndicator /> : null}
-        </RACLabel>
+        </FieldLabel>
         <RACInput
           ref={ref}
           className={input(variantProps)}
@@ -69,6 +74,7 @@ export const TextField = forwardRef<HTMLInputElement, TextFieldProps>(
           helperText={helperText}
           errorMessage={errorMessage}
           helperTextCss={helperTextCss}
+          labelPosition={labelPosition}
         />
       </RACTextField>
     );

package/src/base-preset.ts

@@ -42,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";
 
 /**
@@ -304,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

@@ -17,16 +17,18 @@ export * from "./ButtonGroup";
 export * from "./Card";
 export * from "./Checkbox";
 export * from "./CheckboxGroup";
-export * from "./FieldSupport";
+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";