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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@microbit/ui",
-  "version": "0.1.0-alpha.17",
+  "version": "0.1.0-alpha.18",
   "description": "micro:bit design-system primitives: react-aria-components + Panda CSS with a design language ported from Chakra UI v2. Ships as source; see README for the consumption setup.",
   "license": "MIT",
   "type": "module",

package/src/Checkbox.tsx

@@ -3,7 +3,7 @@
  *
  * SPDX-License-Identifier: MIT
  */
-import { ReactNode } from "react";
+import { ReactNode, useId } from "react";
 import {
   Checkbox as RACCheckbox,
   CheckboxProps as RACCheckboxProps,
@@ -11,6 +11,7 @@ import {
 import { css, cx } from "styled-system/css";
 import { checkbox, CheckboxVariantProps } from "styled-system/recipes";
 import { SystemStyleObject } from "styled-system/types";
+import { FieldHelperText } from "./Field";
 
 /** What a render-prop child is told about the checkbox. */
 export interface CheckboxState {
@@ -39,6 +40,14 @@ export interface CheckboxProps
    * @default true
    */
   control?: boolean;
+  /**
+   * Help text below the checkbox, wired to its `aria-describedby` — the same
+   * chrome the labelled fields' `helperText` renders. With it the component
+   * gains a wrapping `<div>`, so the checkbox-plus-text moves as one block.
+   */
+  helperText?: ReactNode;
+  /** Per-instance style overrides for the helper text. */
+  helperTextCss?: SystemStyleObject;
 }
 
 /**
@@ -52,13 +61,21 @@ export const Checkbox = ({
   className,
   children,
   control,
+  helperText,
+  helperTextCss,
   ...rest
 }: CheckboxProps) => {
   const slots = checkbox({ size });
-  return (
+  const helperId = useId();
+  const describedBy =
+    [rest["aria-describedby"], helperText != null ? helperId : undefined]
+      .filter(Boolean)
+      .join(" ") || undefined;
+  const checkboxElement = (
     <RACCheckbox
       className={cx(slots.root, cssProp ? css(cssProp) : undefined, className)}
       {...rest}
+      aria-describedby={describedBy}
     >
       {({ isSelected, isFocusVisible, isDisabled }) => {
         const content =
@@ -103,4 +120,15 @@ export const Checkbox = ({
       }}
     </RACCheckbox>
   );
+  if (helperText == null) {
+    return checkboxElement;
+  }
+  return (
+    <div>
+      {checkboxElement}
+      <FieldHelperText id={helperId} css={helperTextCss}>
+        {helperText}
+      </FieldHelperText>
+    </div>
+  );
 };

package/src/CheckboxGroup.tsx

@@ -7,16 +7,10 @@ import { ReactNode } from "react";
 import {
   CheckboxGroup as RACCheckboxGroup,
   CheckboxGroupProps as RACCheckboxGroupProps,
-  Label as RACLabel,
 } from "react-aria-components";
 import { css, cx } from "styled-system/css";
-import { field } from "styled-system/recipes";
 import { SystemStyleObject } from "styled-system/types";
-import {
-  FieldRequiredIndicator,
-  FieldSupport,
-  FieldSupportProps,
-} from "./FieldSupport";
+import { FieldLabel, FieldSupport, FieldSupportProps } from "./Field";
 
 export interface CheckboxGroupProps
   extends Omit<RACCheckboxGroupProps, "className" | "style">,
@@ -58,10 +52,7 @@ export const CheckboxGroup = ({
       {(renderProps) => (
         <>
           {label != null && (
-            <RACLabel className={field().label}>
-              {label}
-              {rest.isRequired ? <FieldRequiredIndicator /> : null}
-            </RACLabel>
+            <FieldLabel isRequired={rest.isRequired}>{label}</FieldLabel>
           )}
           {typeof children === "function" ? children(renderProps) : children}
           <FieldSupport

package/src/ComboBox.tsx

@@ -16,27 +16,28 @@ import {
   ComboBox as RACComboBox,
   ComboBoxProps as RACComboBoxProps,
   Input as RACInput,
-  Label as RACLabel,
   ListBox as RACListBox,
   Popover,
   PopoverProps,
 } 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";
 import { SelectSlotProvider } from "./Select";
 
 export interface ComboBoxProps<T extends object>
   extends Omit<RACComboBoxProps<T>, "className" | "children" | "style">,
     SelectVariantProps,
-    FieldSupportProps {
+    FieldSupportProps,
+    FieldLayoutProps {
   /** Visible label. Use `aria-label` instead where the design has none. */
   label?: ReactNode;
   placeholder?: string;
@@ -81,11 +82,12 @@ export interface ComboBoxProps<T extends object>
    */
   maxHeight?: number;
   /**
-   * Per-instance overrides for the control — the box around the input, its
-   * `startContent` and its indicator, which is what `Select`'s `css` styles
-   * too. Reach the input itself through the `select` recipe's `value` slot.
+   * Per-instance overrides for the trigger — the box around the input, its
+   * `startContent` and its indicator, the same slot `Select`'s `triggerCss`
+   * styles. Reach the input itself through the `select` recipe's `value`
+   * slot.
    */
-  css?: SystemStyleObject;
+  triggerCss?: SystemStyleObject;
   /** Per-instance overrides for the dropdown card. */
   contentCss?: SystemStyleObject;
   className?: string;
@@ -114,7 +116,8 @@ const ComboBoxInner = <T extends object>(
     helperText,
     errorMessage,
     helperTextCss,
-    css: cssProp,
+    labelPosition,
+    triggerCss,
     contentCss,
     className,
     ...props
@@ -124,6 +127,7 @@ const ComboBoxInner = <T extends object>(
   // As Select: forward whatever variant groups the merged recipe has.
   const [variantProps, rest] = select.splitVariantProps(props);
   const slots = select(variantProps);
+  const fieldSlots = field({ size: variantProps.size, labelPosition });
   // Anchor the card to the whole control, not to the bare input inside it —
   // otherwise it hangs off the text baseline and is as narrow as the input.
   const triggerRef = useRef<HTMLDivElement>(null);
@@ -152,17 +156,23 @@ const ComboBoxInner = <T extends object>(
       <RACComboBox
         allowsEmptyCollection={emptyState != null}
         {...(rest as RACComboBoxProps<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>
         )}
         <div
           ref={triggerRef}
-          className={cx(slots.trigger, cssProp ? css(cssProp) : undefined)}
+          className={cx(
+            slots.trigger,
+            triggerCss ? css(triggerCss) : undefined,
+          )}
         >
           {startContent}
           <RACInput
@@ -203,6 +213,7 @@ const ComboBoxInner = <T extends object>(
           helperText={helperText}
           errorMessage={errorMessage}
           helperTextCss={helperTextCss}
+          labelPosition={labelPosition}
         />
       </RACComboBox>
     </SelectSlotProvider>

package/src/Field.recipe.ts

@@ -0,0 +1,113 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import { defineSlotRecipe } from "@pandacss/dev";
+
+/**
+ * Field slot recipe — Chakra's FormControl parts (FormLabel/FormHelperText/
+ * FormErrorMessage, light mode), mapped onto react-aria-components'
+ * Label/Text/FieldError by `FieldLabel` and `FieldSupport`. Every labelled
+ * field in the library draws its chrome from here, including Select and
+ * ComboBox, whose own recipe styles only the dropdown pair; the input itself is
+ * styled by the `input` recipe (Input.recipe.ts).
+ *
+ * `root` is also the single owner of field-root *layout*: Select, ComboBox and
+ * NumberField wear it alongside their own recipe's root slot, which carries no
+ * layout of its own — two recipes fighting over `flexDirection` would leave
+ * `labelPosition` at the mercy of emission order. RadioGroup and CheckboxGroup
+ * deliberately don't wear it (their roots carry no layout at all).
+ *
+ * Registered in the base preset (base-preset.ts), which also has the
+ * `staticCss` entry that keeps the runtime-prop size variants generated.
+ */
+export const field = defineSlotRecipe({
+  className: "field",
+  slots: ["root", "label", "requiredIndicator", "helperText", "errorMessage"],
+  base: {
+    root: {
+      display: "flex",
+      flexDirection: "column",
+      alignItems: "stretch",
+      width: "100%",
+    },
+    label: {
+      display: "block",
+      fontSize: "md",
+      // Deliberately not Chakra FormLabel's `medium`: no font in the family's
+      // stack has a 500 face, so the two were pixel-identical on macOS and
+      // Windows, and the only call sites that cared overrode to `normal`
+      // (settings rows). See the playbook's expected behavioural deltas.
+      fontWeight: "normal",
+      marginEnd: "3",
+      mb: "2",
+      transitionProperty: "opacity",
+      transitionDuration: "normal",
+      // RAC stamps `data-disabled` on the field root and on the control, never
+      // on the label, so an `&[data-disabled]` rule here matches nothing — it
+      // has to come down from the root (gotcha #45). Direct child rather than a
+      // descendant selector, as the select recipe's invalid rule: an app's own
+      // disabled form wrapper must not be able to dim every label inside it.
+      "[data-disabled] > &": { opacity: 0.4 },
+    },
+    requiredIndicator: {
+      marginStart: "1",
+      color: "danger.500",
+    },
+    helperText: {
+      // RAC's Text renders a span, and RadioGroup/CheckboxGroup roots are not
+      // flex containers to blockify it, where an inline box would drop the
+      // margin below (gotcha #44).
+      display: "block",
+      mt: "2",
+      fontSize: "sm",
+      lineHeight: "normal",
+      color: "gray.600",
+    },
+    errorMessage: {
+      display: "flex",
+      alignItems: "center",
+      mt: "2",
+      fontSize: "sm",
+      lineHeight: "normal",
+      color: "danger.500",
+    },
+  },
+  variants: {
+    // The label follows its control's size (the control itself is sized by
+    // the `input`/`select` recipes), so one `size` prop scales the whole row.
+    // Chakra's FormLabel never scaled — a deliberate delta; see the playbook's
+    // field-chrome notes. Helper and error text stay `sm` at every size, as
+    // Chakra's did.
+    size: {
+      lg: { label: { fontSize: "lg" } },
+      md: { label: { fontSize: "md" } },
+      sm: { label: { fontSize: "sm" } },
+    },
+    // `side` puts the label beside its control — the settings-row pattern,
+    // where the label is a preference name and absorbs the free space. The
+    // control keeps its own width; give it one at the call site. Named after
+    // React Spectrum's `labelPosition`, not `orientation`, which RAC's
+    // RadioGroup already uses for the radios' own layout.
+    labelPosition: {
+      top: {},
+      side: {
+        root: {
+          flexDirection: "row",
+          alignItems: "center",
+          // Helper and error text are full-width items, so they wrap to
+          // their own line below the label/control pair.
+          flexWrap: "wrap",
+        },
+        label: { mb: "0", flex: "1 1 auto" },
+        helperText: { width: "100%" },
+        errorMessage: { width: "100%" },
+      },
+    },
+  },
+  defaultVariants: {
+    size: "md",
+    labelPosition: "top",
+  },
+});

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/NativeSelectField.tsx

@@ -0,0 +1,81 @@
+/**
+ * (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;
+  /** 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, 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}
+      >
+        {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",
+  },
 });