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

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",
@@ -66,16 +63,16 @@ export const select = defineSlotRecipe({
       transitionProperty: transitionCommon,
       transitionDuration: "normal",
       border: "1px solid",
-      borderColor: "gray.200",
-      borderRadius: "md",
+      // As the input recipe: the ramp's accessible outline stop, with hover
+      // stepping darker. The dropdown card below keeps the light gray.200 —
+      // it's a surface edge, not a form-control boundary.
+      borderColor: "gray.400",
       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.)
-      _hover: { borderColor: "gray.300" },
+      _hover: { borderColor: "gray.500" },
       // `data-invalid` lands on the root — and, in a ComboBox, on the input —
       // but never on the trigger: a RAC Button has no validity state, and our
       // ComboBox control is a plain div. So it comes down from the parent.
@@ -207,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,
@@ -16,16 +15,19 @@ import {
   SelectProps as RACSelectProps,
   SelectValue,
 } from "react-aria-components";
+import { useIntl } from "react-intl";
 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";
+import { uiMessage } from "./messages";
 
 export type SelectSlots = ReturnType<typeof select>;
 
@@ -43,10 +45,16 @@ 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). */
+  /** Label style overrides. */
+  labelCss?: SystemStyleObject;
+  /**
+   * Shown in the trigger while nothing is chosen (Chakra's placeholder).
+   * Defaults to a translated "Select an item".
+   */
   placeholder?: string;
   /** `SelectOption`s. */
   children: ReactNode;
@@ -65,8 +73,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;
@@ -79,6 +87,7 @@ export interface SelectProps<T extends object>
  */
 export const Select = <T extends object>({
   label,
+  labelCss,
   placeholder,
   children,
   indicator,
@@ -87,7 +96,8 @@ export const Select = <T extends object>({
   helperText,
   errorMessage,
   helperTextCss,
-  css: cssProp,
+  labelPosition,
+  triggerCss,
   contentCss,
   className,
   ...props
@@ -95,25 +105,37 @@ export const Select = <T extends object>({
   // splitVariantProps, not a hand-picked list: an app preset can add variant
   // groups to the recipe and they have to reach it (playbook gotcha #37).
   const [variantProps, rest] = select.splitVariantProps(props);
+  const intl = useIntl();
   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}
+            css={labelCss}
+          >
             {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 }) =>
-              isPlaceholder ? placeholder ?? "" : defaultChildren
+              isPlaceholder
+                ? placeholder ??
+                  intl.formatMessage(uiMessage("ui.select-placeholder"))
+                : defaultChildren
             }
           </SelectValue>
           {indicator !== null && (
@@ -136,6 +158,7 @@ export const Select = <T extends object>({
           helperText={helperText}
           errorMessage={errorMessage}
           helperTextCss={helperTextCss}
+          labelPosition={labelPosition}
         />
       </RACSelect>
     </SelectSlotProvider>

package/src/Skeleton.tsx

@@ -12,12 +12,14 @@ import { SystemStyleObject } from "styled-system/types";
  * caller's `css` is merged into one `css()` call and its overrides win
  * (playbook gotcha #8).
  *
- * The colours are Chakra's, through the same pair of custom properties, so a
- * call site can retint one skeleton without knowing how the animation works.
+ * The colours flow through the same pair of custom properties Chakra used,
+ * so a call site can retint one skeleton without knowing how the animation
+ * works.
  */
 const skeletonBase: SystemStyleObject = {
   "--skeleton-start-color": "token(colors.gray.100)",
-  "--skeleton-end-color": "token(colors.gray.400)",
+  // gray.350, the decorative-fill stop, as the Avatar default.
+  "--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

@@ -6,16 +6,17 @@
 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 { SystemStyleObject } from "styled-system/types";
 import {
-  FieldRequiredIndicator,
+  FieldLabel,
+  FieldLayoutProps,
   FieldSupport,
   FieldSupportProps,
-} from "./FieldSupport";
+} from "./Field";
 
 export interface TextFieldProps
   extends Omit<
@@ -23,9 +24,12 @@ export interface TextFieldProps
       "className" | "children" | "style" | "onFocus" | "onBlur"
     >,
     InputVariantProps,
-    FieldSupportProps {
+    FieldSupportProps,
+    FieldLayoutProps {
   /** Visible label (Chakra's FormLabel; asterisk added when `isRequired`). */
   label: ReactNode;
+  /** 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";
@@ -40,9 +44,11 @@ export const TextField = forwardRef<HTMLInputElement, TextFieldProps>(
   function TextField(
     {
       label,
+      labelCss,
       helperText,
       errorMessage,
       helperTextCss,
+      labelPosition,
       onFocus,
       autoCapitalize,
       ...props
@@ -52,13 +58,17 @@ 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 ? <FieldRequiredIndicator /> : null}
-        </RACLabel>
+        </FieldLabel>
         <RACInput
           ref={ref}
           className={input(variantProps)}
@@ -69,6 +79,7 @@ export const TextField = forwardRef<HTMLInputElement, TextFieldProps>(
           helperText={helperText}
           errorMessage={errorMessage}
           helperTextCss={helperTextCss}
+          labelPosition={labelPosition}
         />
       </RACTextField>
     );

package/src/Toast.tsx

@@ -3,7 +3,7 @@
  *
  * SPDX-License-Identifier: MIT
  */
-import { ReactNode, useMemo } from "react";
+import { ReactNode, useMemo, useSyncExternalStore } from "react";
 import {
   Button as RACButton,
   UNSTABLE_Toast as RACToast,
@@ -55,6 +55,10 @@ const statusIcon: Record<ToastStatus, IconType> = {
   error: RiErrorWarningFill,
 };
 
+// Module scope so useSyncExternalStore doesn't resubscribe every render.
+const subscribeToQueue = (fn: () => void) => toastQueue.subscribe(fn);
+const getVisibleCount = () => toastQueue.visibleToasts.length;
+
 /**
  * Mount once near the app root, inside the IntlProvider (the close button's
  * label and the status announcements are react-intl messages).
@@ -63,8 +67,19 @@ const statusIcon: Record<ToastStatus, IconType> = {
 export const ToastProvider = () => {
   const intl = useIntl();
   const slots = toastRecipe();
+  // The region's landmark label counts the visible toasts, so it has to
+  // track the queue.
+  const count = useSyncExternalStore(
+    subscribeToQueue,
+    getVisibleCount,
+    getVisibleCount,
+  );
   return (
-    <RACToastRegion queue={toastQueue} className={slots.region}>
+    <RACToastRegion
+      queue={toastQueue}
+      aria-label={intl.formatMessage(uiMessage("ui.toast-region"), { count })}
+      className={slots.region}
+    >
       {({ toast }) => {
         const status = toast.content.status ?? "info";
         return (

package/src/base-preset.ts

@@ -42,9 +42,46 @@ 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";
 
+// The family gray ramp: pure neutrals as the library default. The two
+// halves have different jobs and different override rules:
+//
+// - 10–300 are surface stops (panels, page backdrops, hairlines, subtle
+//   fills). Presets may freely override these values — pinning an app's
+//   existing surfaces or applying a brand tint — because a few bits of
+//   lightness here reads across a whole viewport.
+// - 350 is the decorative/state fill stop (~2.1:1): avatar discs, skeleton
+//   pulse, pressed fills. Never text or boundaries.
+// - 400–900 are ink stops (outlines, placeholders, text) with a contrast
+//   contract on white: 400 ≥ 3:1, the accessible form-outline stop
+//   (WCAG 1.4.11); 500 ≥ 4.5:1, text-safe secondary (placeholders, muted
+//   icons). Presets may re-tint these only luminance-matched — the
+//   contrast figures are the contract, hue is free.
+//
+// Override values, never names: raw var(--colors-gray-*) references and
+// paired private presets depend on the names, so a rename is a breaking
+// change to both and needs every app and paired preset moved in lockstep
+// (as was done when Chakra's misnamed darker-than-50 stop `25` became
+// `75`). And never override partially in a way that lets a stop fall
+// through to a different grey system.
+const gray = {
+  10: { value: "#fcfcfc" },
+  50: { value: "#f9f9f9" },
+  75: { value: "#f5f5f5" },
+  100: { value: "#f1f1f1" },
+  200: { value: "#e7e7e7" },
+  300: { value: "#d4d4d4" },
+  350: { value: "#b4b4b4" }, // ~2.1:1 — decorative fills only
+  400: { value: "#949494" }, // 3.05:1 — accessible outline stop
+  500: { value: "#767676" }, // 4.54:1 — text-safe secondary
+  600: { value: "#575757" },
+  700: { value: "#404040" },
+  800: { value: "#262626" },
+  900: { value: "#1a1a1a" },
+};
+
 /**
  * The base preset: the complete, working micro:bit design system. The base
  * token scales (base-tokens.ts), the micro:bit house style
@@ -92,16 +129,12 @@ export const basePreset = definePreset({
     tokens: {
       colors: {
         ...colors,
-        gray: {
-          ...colors.gray,
-          // Very light grays the family's designs use below Chakra's 50.
-          10: { value: "#fcfcfc" },
-          25: { value: "#f5f5f5" },
-        },
+        gray,
         // OSS default brand ramps (see the brand contract above). `brand`
-        // aliases Chakra blue; `brand2` Chakra's *unmodified* gray (not the
-        // `gray` above, whose 10/25 additions are lighter — getting this
-        // wrong once made card text near-invisible).
+        // aliases Chakra blue; `brand2` stays Chakra's slate gray — a frozen
+        // legacy alias, deliberately decoupled from the neutral `gray` above
+        // so ml-trainer's OSS look and `statusBarBg`'s default don't move.
+        // Removing the slot is a follow-up needing an ml-trainer lockstep.
         brand: colors.blue,
         brand2: colors.gray,
       },
@@ -304,9 +337,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";

package/src/FieldSupport.tsx

@@ -1,68 +0,0 @@
-/**
- * (c) 2026, Micro:bit Educational Foundation and contributors
- *
- * SPDX-License-Identifier: MIT
- */
-import { ReactNode } from "react";
-import { FieldError, Text as RACText } from "react-aria-components";
-import { css, cx } from "styled-system/css";
-import { field } 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;
-}
-
-/**
- * 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,
-}: FieldSupportProps) => {
-  const slots = field();
-  return (
-    <>
-      {helperText != null && (
-        <RACText
-          slot="description"
-          className={cx(
-            slots.helperText,
-            helperTextCss ? css(helperTextCss) : undefined,
-          )}
-        >
-          {helperText}
-        </RACText>
-      )}
-      <FieldError className={slots.errorMessage}>{errorMessage}</FieldError>
-    </>
-  );
-};
-
-/**
- * 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>
-);