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

package/src/Field.tsx

@@ -0,0 +1,189 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import { HTMLAttributes, ReactNode } from "react";
+import {
+  FieldError,
+  Label as RACLabel,
+  LabelProps as RACLabelProps,
+  Text as RACText,
+} from "react-aria-components";
+import { css, cx } from "styled-system/css";
+import { field, FieldVariantProps } from "styled-system/recipes";
+import { SystemStyleObject } from "styled-system/types";
+
+/**
+ * The label/helper/error chrome every labelled form field shares — Chakra's
+ * FormControl parts, generalised out of TextField so Select, ComboBox,
+ * NumberField, RadioGroup and CheckboxGroup carry the same props
+ * (data-microbit-org's forms attach helper and error text to all of these).
+ */
+export interface FieldSupportProps {
+  /** Help text below the field (Chakra's FormHelperText). */
+  helperText?: ReactNode;
+  /** Shown below the field when invalid (Chakra's FormErrorMessage). */
+  errorMessage?: ReactNode;
+  /** Per-instance style overrides for the helper text. */
+  helperTextCss?: SystemStyleObject;
+}
+
+/**
+ * `labelPosition` for the four single-control fields (TextField, NumberField,
+ * Select, ComboBox). Deliberately not on RadioGroup/CheckboxGroup: their roots
+ * carry no layout, and RAC's own `orientation` prop is a different axis there
+ * (it lays out the radios, not the label).
+ */
+export interface FieldLayoutProps {
+  /**
+   * `side` puts the label beside the control — the settings-row pattern. The
+   * label absorbs the free space; the control keeps its own width, so give it
+   * one (`groupCss`, `wrapperCss` or `triggerCss` depending on the field).
+   * Helper and error text drop to a full-width line below the pair.
+   */
+  labelPosition?: FieldVariantProps["labelPosition"];
+}
+
+/**
+ * Helper text and error message for a react-aria field container. Render
+ * inside any RAC component with field validation context (TextField, Select,
+ * ComboBox, NumberField, RadioGroup, CheckboxGroup) — react-aria wires the
+ * description to the input's aria-describedby, and the error renders only
+ * while the field is invalid. Also exported for app-side composites built on
+ * RAC containers.
+ */
+export const FieldSupport = ({
+  helperText,
+  errorMessage,
+  helperTextCss,
+  labelPosition,
+}: FieldSupportProps & FieldLayoutProps) => {
+  const slots = field({ labelPosition });
+  return (
+    <>
+      {helperText != null && (
+        <RACText
+          slot="description"
+          className={cx(
+            slots.helperText,
+            helperTextCss ? css(helperTextCss) : undefined,
+          )}
+        >
+          {helperText}
+        </RACText>
+      )}
+      <FieldError className={slots.errorMessage}>{errorMessage}</FieldError>
+    </>
+  );
+};
+
+interface FieldTextProps extends HTMLAttributes<HTMLDivElement> {
+  children: ReactNode;
+  /** The field's `labelPosition`, so the text lays out to match. */
+  labelPosition?: FieldVariantProps["labelPosition"];
+  /** Per-instance style overrides. */
+  css?: SystemStyleObject;
+}
+
+/**
+ * Context-free helper text (Chakra's FormHelperText) for a control react-aria
+ * isn't wiring — a native select or a masked input. Inside a RAC field
+ * container use `FieldSupport`, which wires `aria-describedby` and validation
+ * for free; here the caller owns that wiring: give this an `id` and reference
+ * it from the control's `aria-describedby` (as `NativeSelectField` does).
+ */
+export const FieldHelperText = ({
+  children,
+  labelPosition,
+  css: cssProp,
+  ...rest
+}: FieldTextProps) => (
+  <div
+    {...rest}
+    className={cx(
+      field({ labelPosition }).helperText,
+      cssProp ? css(cssProp) : undefined,
+    )}
+  >
+    {children}
+  </div>
+);
+
+/**
+ * Context-free error message (Chakra's FormErrorMessage), the counterpart to
+ * `FieldHelperText` — see its note on the wiring the caller owns. RAC's
+ * `FieldError` renders only while its field is invalid; here that decision is
+ * the caller's too: render it conditionally.
+ */
+export const FieldErrorMessage = ({
+  children,
+  labelPosition,
+  css: cssProp,
+  ...rest
+}: FieldTextProps) => (
+  <div
+    {...rest}
+    className={cx(
+      field({ labelPosition }).errorMessage,
+      cssProp ? css(cssProp) : undefined,
+    )}
+  >
+    {children}
+  </div>
+);
+
+/**
+ * The required-field asterisk (Chakra's FormLabel indicator). Render inside
+ * the field's label when `isRequired`; aria-hidden because react-aria already
+ * announces requiredness from the input itself.
+ */
+export const FieldRequiredIndicator = () => (
+  <span aria-hidden className={field().requiredIndicator}>
+    *
+  </span>
+);
+
+export interface FieldLabelProps
+  extends Omit<RACLabelProps, "className" | "children" | "style"> {
+  children: ReactNode;
+  /** Adds the required asterisk; pass the field's `isRequired`. */
+  isRequired?: boolean;
+  /** The field's `size`, so the label scales with its control. */
+  size?: FieldVariantProps["size"];
+  /** The field's `labelPosition`, so the label lays out to match. */
+  labelPosition?: FieldVariantProps["labelPosition"];
+  /** Per-instance style overrides. */
+  css?: SystemStyleObject;
+}
+
+/**
+ * A field's visible label (Chakra's FormLabel), asterisk included. Every
+ * labelled field in the library renders its label through this, so the `field`
+ * recipe is the single answer to what a label looks like — Select and ComboBox
+ * previously carried a near-identical `label` slot on the `select` recipe,
+ * which is how the two drifted.
+ *
+ * Also exported for app-side composites: inside a RAC field container the
+ * association is automatic, and outside one (a masked or native input) pass
+ * `id` and `htmlFor` yourself.
+ */
+export const FieldLabel = ({
+  children,
+  isRequired,
+  size,
+  labelPosition,
+  css: cssProp,
+  ...rest
+}: FieldLabelProps) => (
+  <RACLabel
+    {...rest}
+    className={cx(
+      field({ size, labelPosition }).label,
+      cssProp ? css(cssProp) : undefined,
+    )}
+  >
+    {children}
+    {isRequired ? <FieldRequiredIndicator /> : null}
+  </RACLabel>
+);

package/src/Input.recipe.ts

@@ -44,10 +44,12 @@ export const input = defineRecipe({
     transitionProperty: transitionCommon,
     transitionDuration: "normal",
     border: "1px solid",
-    borderColor: "gray.200",
+    // The accessible outline stops: gray.400 is the ramp's 3:1-on-white
+    // boundary grey (WCAG 1.4.11), and hover steps darker, never lighter.
+    borderColor: "gray.400",
     bg: "inherit",
     color: "inherit",
-    _hover: { borderColor: "gray.300" },
+    _hover: { borderColor: "gray.500" },
     "&&:is([data-invalid], :user-invalid)": {
       borderColor: "danger.500",
       boxShadow: "0 0 0 1px token(colors.danger.500)",

package/src/NativeSelectField.tsx

@@ -0,0 +1,84 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import { forwardRef, ReactNode, useId } from "react";
+import { css, cx } from "styled-system/css";
+import { field } from "styled-system/recipes";
+import { SystemStyleObject } from "styled-system/types";
+import { FieldHelperText, FieldLabel, FieldLayoutProps } from "./Field";
+import { NativeSelect, NativeSelectProps } from "./NativeSelect";
+
+export interface NativeSelectFieldProps
+  extends NativeSelectProps,
+    FieldLayoutProps {
+  /** Visible label, associated with the select via `htmlFor`. */
+  label: ReactNode;
+  /** Label style overrides. */
+  labelCss?: SystemStyleObject;
+  /** Help text below the field, wired to the select's `aria-describedby`. */
+  helperText?: ReactNode;
+  /** Per-instance style overrides for the field root. */
+  rootCss?: SystemStyleObject;
+}
+
+/**
+ * NativeSelectField — a labelled `NativeSelect`, pairing the bare control with
+ * the field chrome the RAC fields get from react-aria, as `TextField` pairs
+ * with `Input`. The label association and `aria-describedby` are wired here,
+ * since there is no RAC context to do it; the label dims with the control
+ * exactly as the RAC fields' do. No `errorMessage` yet — no consumer needs
+ * one; render `FieldErrorMessage` beside it if yours does.
+ *
+ * With `labelPosition="side"` this is the settings row both
+ * `SelectFormControl`s hand-rolled: label beside a fixed-width select
+ * (`wrapperCss={{ width: "28ch" }}`), label absorbing the free space.
+ */
+export const NativeSelectField = forwardRef<
+  HTMLSelectElement,
+  NativeSelectFieldProps
+>(function NativeSelectField(
+  { label, labelCss, helperText, labelPosition, rootCss, id, ...rest },
+  ref,
+) {
+  const generatedId = useId();
+  const selectId = id ?? generatedId;
+  const helperId = useId();
+  const describedBy =
+    [rest["aria-describedby"], helperText != null ? helperId : undefined]
+      .filter(Boolean)
+      .join(" ") || undefined;
+  return (
+    <div
+      className={cx(
+        field({ size: rest.size, labelPosition }).root,
+        rootCss ? css(rootCss) : undefined,
+      )}
+      // The field recipe's label dims off the root's data-disabled, which RAC
+      // stamps for the other fields; here it is restated from the attribute.
+      data-disabled={rest.disabled || undefined}
+    >
+      <FieldLabel
+        htmlFor={selectId}
+        size={rest.size}
+        labelPosition={labelPosition}
+        isRequired={rest.required}
+        css={labelCss}
+      >
+        {label}
+      </FieldLabel>
+      <NativeSelect
+        ref={ref}
+        id={selectId}
+        {...rest}
+        aria-describedby={describedBy}
+      />
+      {helperText != null && (
+        <FieldHelperText id={helperId} labelPosition={labelPosition}>
+          {helperText}
+        </FieldHelperText>
+      )}
+    </div>
+  );
+});

package/src/NumberField.recipe.ts

@@ -11,18 +11,18 @@ import { defineSlotRecipe } from "@pandacss/dev";
  * two stacked buttons. Consumed by the shared-ui NumberField
  * (react-aria-components NumberField).
  *
- * Registered in the base preset (base-preset.ts). No variants, so it needs
- * no `staticCss` entry.
+ * Registered in the base preset (base-preset.ts), which also has the
+ * `staticCss` entry that keeps the runtime-prop size variants generated.
  */
 export const numberField = defineSlotRecipe({
   className: "numberField",
   slots: ["root", "group", "stepper", "stepperButton"],
   base: {
-    root: {
-      display: "flex",
-      flexDirection: "column",
-      alignItems: "stretch",
-    },
+    // 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: {},
     group: {
       position: "relative",
       zIndex: 0,
@@ -64,4 +64,22 @@ export const numberField = defineSlotRecipe({
       "&[data-disabled]": { opacity: 0.4, cursor: "not-allowed" },
     },
   },
+  variants: {
+    // Chakra's NumberInput: the stepper column stays 24px wide at every size
+    // (as does the input padding paired with it in NumberField.tsx); only the
+    // arrow glyphs scale, at 0.75 × the field's font size. The base's `xs` is
+    // exactly md × 0.75, so md adds nothing.
+    size: {
+      lg: {
+        stepperButton: { fontSize: "calc(token(fontSizes.lg) * 0.75)" },
+      },
+      md: {},
+      sm: {
+        stepperButton: { fontSize: "calc(token(fontSizes.sm) * 0.75)" },
+      },
+    },
+  },
+  defaultVariants: {
+    size: "md",
+  },
 });

package/src/NumberField.tsx

@@ -8,33 +8,43 @@ import {
   Button as RACButton,
   Group as RACGroup,
   Input as RACInput,
-  Label as RACLabel,
   NumberField as RACNumberField,
   NumberFieldProps as RACNumberFieldProps,
 } from "react-aria-components";
+import { useIntl } from "react-intl";
 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";
+import { uiMessage } from "./messages";
 
 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 +61,49 @@ 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 });
+    const intl = useIntl();
+    // Fold the field's name into the stepper labels as react-aria does; the
+    // trim eats the leftover space when there is no usable name.
+    const fieldLabel =
+      rest["aria-label"] ?? (typeof label === "string" ? label : "");
     return (
       <RACNumberField
+        incrementAriaLabel={intl
+          .formatMessage(uiMessage("ui.numberfield-increase"), { fieldLabel })
+          .trim()}
+        decrementAriaLabel={intl
+          .formatMessage(uiMessage("ui.numberfield-decrease"), { fieldLabel })
+          .trim()}
         {...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 +111,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 +130,7 @@ export const NumberField = forwardRef<HTMLInputElement, NumberFieldProps>(
           helperText={helperText}
           errorMessage={errorMessage}
           helperTextCss={helperTextCss}
+          labelPosition={labelPosition}
         />
       </RACNumberField>
     );

package/src/Radio.recipe.ts

@@ -28,6 +28,10 @@ export const radio = defineSlotRecipe({
       verticalAlign: "top",
       cursor: "pointer",
       position: "relative",
+      // As the checkbox: the accessible outline stop (WCAG 1.4.11), on the
+      // root so the control's `borderColor: inherit` reads it and call
+      // sites can still tint at the root.
+      borderColor: "gray.400",
       "&[data-disabled]": { cursor: "not-allowed" },
     },
     control: {

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,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>
+  );
+};