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

package/lang/ui.pl.json

@@ -1,8 +1,44 @@
 {
+  "ui.breadcrumb": {
+    "defaultMessage": "Breadcrumb",
+    "description": "Accessible label for the breadcrumb navigation trail (the WAI-ARIA APG's conventional name)"
+  },
   "ui.close-action": {
     "defaultMessage": "Zamknij",
     "description": "Close button text or label"
   },
+  "ui.combobox-listbox": {
+    "defaultMessage": "Sugestie",
+    "description": "Accessible label for a ComboBox's dropdown list of suggestions"
+  },
+  "ui.combobox-trigger": {
+    "defaultMessage": "Wyświetlaj sugestie",
+    "description": "Accessible label for the button that opens a ComboBox's suggestions dropdown"
+  },
+  "ui.loading": {
+    "defaultMessage": "Loading",
+    "description": "Announced by screen readers for a button showing a loading spinner"
+  },
+  "ui.numberfield-decrease": {
+    "defaultMessage": "Zmniejsz {fieldLabel}",
+    "description": "Accessible label for a number field's decrement stepper; fieldLabel is the field's label and may be empty"
+  },
+  "ui.numberfield-increase": {
+    "defaultMessage": "Zwiększ {fieldLabel}",
+    "description": "Accessible label for a number field's increment stepper; fieldLabel is the field's label and may be empty"
+  },
+  "ui.select-placeholder": {
+    "defaultMessage": "Wybierz element",
+    "description": "Shown in a Select's trigger while nothing is chosen and the app supplies no placeholder"
+  },
+  "ui.select-row-action": {
+    "defaultMessage": "Zaznacz",
+    "description": "Accessible label for a row-selection checkbox in a list or table; screen readers read it together with the row's content"
+  },
+  "ui.toast-region": {
+    "defaultMessage": "{count, plural, one {# powiadomienie} few {# powiadomienia} many {# powiadomień} other {# powiadomienia}}.",
+    "description": "Accessible label for the notifications area; count is the number of notifications showing"
+  },
   "ui.toast-status-error": {
     "defaultMessage": "Error",
     "description": "Announced by screen readers before an error notification"

package/lang/ui.pt-br.json

@@ -1,8 +1,44 @@
 {
+  "ui.breadcrumb": {
+    "defaultMessage": "Breadcrumb",
+    "description": "Accessible label for the breadcrumb navigation trail (the WAI-ARIA APG's conventional name)"
+  },
   "ui.close-action": {
     "defaultMessage": "Fechar",
     "description": "Close button text or label"
   },
+  "ui.combobox-listbox": {
+    "defaultMessage": "Sugestões",
+    "description": "Accessible label for a ComboBox's dropdown list of suggestions"
+  },
+  "ui.combobox-trigger": {
+    "defaultMessage": "Mostrar sugestões",
+    "description": "Accessible label for the button that opens a ComboBox's suggestions dropdown"
+  },
+  "ui.loading": {
+    "defaultMessage": "Loading",
+    "description": "Announced by screen readers for a button showing a loading spinner"
+  },
+  "ui.numberfield-decrease": {
+    "defaultMessage": "Diminuir {fieldLabel}",
+    "description": "Accessible label for a number field's decrement stepper; fieldLabel is the field's label and may be empty"
+  },
+  "ui.numberfield-increase": {
+    "defaultMessage": "Aumentar {fieldLabel}",
+    "description": "Accessible label for a number field's increment stepper; fieldLabel is the field's label and may be empty"
+  },
+  "ui.select-placeholder": {
+    "defaultMessage": "Selecione um item",
+    "description": "Shown in a Select's trigger while nothing is chosen and the app supplies no placeholder"
+  },
+  "ui.select-row-action": {
+    "defaultMessage": "Selecionar",
+    "description": "Accessible label for a row-selection checkbox in a list or table; screen readers read it together with the row's content"
+  },
+  "ui.toast-region": {
+    "defaultMessage": "{count, plural, one {# notificação} other {# notificações}}.",
+    "description": "Accessible label for the notifications area; count is the number of notifications showing"
+  },
   "ui.toast-status-error": {
     "defaultMessage": "Error",
     "description": "Announced by screen readers before an error notification"

package/lang/ui.zh-cn.json

@@ -1,8 +1,44 @@
 {
+  "ui.breadcrumb": {
+    "defaultMessage": "Breadcrumb",
+    "description": "Accessible label for the breadcrumb navigation trail (the WAI-ARIA APG's conventional name)"
+  },
   "ui.close-action": {
     "defaultMessage": "关闭",
     "description": "Close button text or label"
   },
+  "ui.combobox-listbox": {
+    "defaultMessage": "建议",
+    "description": "Accessible label for a ComboBox's dropdown list of suggestions"
+  },
+  "ui.combobox-trigger": {
+    "defaultMessage": "显示建议",
+    "description": "Accessible label for the button that opens a ComboBox's suggestions dropdown"
+  },
+  "ui.loading": {
+    "defaultMessage": "Loading",
+    "description": "Announced by screen readers for a button showing a loading spinner"
+  },
+  "ui.numberfield-decrease": {
+    "defaultMessage": "降低 {fieldLabel}",
+    "description": "Accessible label for a number field's decrement stepper; fieldLabel is the field's label and may be empty"
+  },
+  "ui.numberfield-increase": {
+    "defaultMessage": "提高 {fieldLabel}",
+    "description": "Accessible label for a number field's increment stepper; fieldLabel is the field's label and may be empty"
+  },
+  "ui.select-placeholder": {
+    "defaultMessage": "选择一个项目",
+    "description": "Shown in a Select's trigger while nothing is chosen and the app supplies no placeholder"
+  },
+  "ui.select-row-action": {
+    "defaultMessage": "选择",
+    "description": "Accessible label for a row-selection checkbox in a list or table; screen readers read it together with the row's content"
+  },
+  "ui.toast-region": {
+    "defaultMessage": "{count, plural, one {# 个通知} other {# 个通知}}。",
+    "description": "Accessible label for the notifications area; count is the number of notifications showing"
+  },
   "ui.toast-status-error": {
     "defaultMessage": "Error",
     "description": "Announced by screen readers before an error notification"

package/lang/ui.zh-tw.json

@@ -1,8 +1,44 @@
 {
+  "ui.breadcrumb": {
+    "defaultMessage": "Breadcrumb",
+    "description": "Accessible label for the breadcrumb navigation trail (the WAI-ARIA APG's conventional name)"
+  },
   "ui.close-action": {
     "defaultMessage": "關閉",
     "description": "Close button text or label"
   },
+  "ui.combobox-listbox": {
+    "defaultMessage": "建議",
+    "description": "Accessible label for a ComboBox's dropdown list of suggestions"
+  },
+  "ui.combobox-trigger": {
+    "defaultMessage": "顯示建議",
+    "description": "Accessible label for the button that opens a ComboBox's suggestions dropdown"
+  },
+  "ui.loading": {
+    "defaultMessage": "Loading",
+    "description": "Announced by screen readers for a button showing a loading spinner"
+  },
+  "ui.numberfield-decrease": {
+    "defaultMessage": "縮小 {fieldLabel}",
+    "description": "Accessible label for a number field's decrement stepper; fieldLabel is the field's label and may be empty"
+  },
+  "ui.numberfield-increase": {
+    "defaultMessage": "放大 {fieldLabel}",
+    "description": "Accessible label for a number field's increment stepper; fieldLabel is the field's label and may be empty"
+  },
+  "ui.select-placeholder": {
+    "defaultMessage": "選取項目",
+    "description": "Shown in a Select's trigger while nothing is chosen and the app supplies no placeholder"
+  },
+  "ui.select-row-action": {
+    "defaultMessage": "選取",
+    "description": "Accessible label for a row-selection checkbox in a list or table; screen readers read it together with the row's content"
+  },
+  "ui.toast-region": {
+    "defaultMessage": "{count, plural, one {# 個通知} other {# 個通知}}。",
+    "description": "Accessible label for the notifications area; count is the number of notifications showing"
+  },
   "ui.toast-status-error": {
     "defaultMessage": "Error",
     "description": "Announced by screen readers before an error notification"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@microbit/ui",
-  "version": "0.1.0-alpha.17",
+  "version": "0.1.0-alpha.19",
   "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/Avatar.recipe.ts

@@ -44,7 +44,9 @@ export const avatar = defineSlotRecipe({
       fontWeight: "medium",
       borderRadius: "full",
       // Chakra's no-name defaults; the name-derived pair arrives inline.
-      background: "var(--avatar-bg, token(colors.gray.400))",
+      // gray.350 is the decorative-fill stop — 400+ are reserved for
+      // accessible outlines and text (see the ramp in base-preset.ts).
+      background: "var(--avatar-bg, token(colors.gray.350))",
       color: "var(--avatar-color, token(colors.white))",
       borderColor: "white",
     },

package/src/Checkbox.recipe.ts

@@ -27,6 +27,11 @@ export const checkbox = defineSlotRecipe({
       verticalAlign: "top",
       cursor: "pointer",
       position: "relative",
+      // The accessible outline stop (WCAG 1.4.11), as the input recipe.
+      // Stated here rather than on the control — whose `borderColor:
+      // inherit` reads it — so a call site can still tint the whole control
+      // by setting borderColor on the root.
+      borderColor: "gray.400",
       "&[data-disabled]": { cursor: "not-allowed" },
     },
     control: {

package/src/Checkbox.tsx

@@ -3,14 +3,17 @@
  *
  * SPDX-License-Identifier: MIT
  */
-import { ReactNode } from "react";
+import { ReactNode, useId } from "react";
 import {
   Checkbox as RACCheckbox,
   CheckboxProps as RACCheckboxProps,
 } from "react-aria-components";
+import { useIntl } from "react-intl";
 import { css, cx } from "styled-system/css";
 import { checkbox, CheckboxVariantProps } from "styled-system/recipes";
 import { SystemStyleObject } from "styled-system/types";
+import { FieldHelperText } from "./Field";
+import { uiMessage } from "./messages";
 
 /** What a render-prop child is told about the checkbox. */
 export interface CheckboxState {
@@ -39,6 +42,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 +63,31 @@ export const Checkbox = ({
   className,
   children,
   control,
+  helperText,
+  helperTextCss,
   ...rest
 }: CheckboxProps) => {
   const slots = checkbox({ size });
-  return (
+  const helperId = useId();
+  const intl = useIntl();
+  const describedBy =
+    [rest["aria-describedby"], helperText != null ? helperId : undefined]
+      .filter(Boolean)
+      .join(" ") || undefined;
+  // Default name for a row-selection checkbox (a GridList row's). A future
+  // Table's select-all header checkbox shares the slot name and will need a
+  // different label.
+  const ariaLabel =
+    rest["aria-label"] ??
+    (rest.slot === "selection"
+      ? intl.formatMessage(uiMessage("ui.select-row-action"))
+      : undefined);
+  const checkboxElement = (
     <RACCheckbox
       className={cx(slots.root, cssProp ? css(cssProp) : undefined, className)}
       {...rest}
+      aria-label={ariaLabel}
+      aria-describedby={describedBy}
     >
       {({ isSelected, isFocusVisible, isDisabled }) => {
         const content =
@@ -103,4 +132,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">,
@@ -26,6 +20,8 @@ export interface CheckboxGroupProps
    * `aria-label` instead where the design has none.
    */
   label?: ReactNode;
+  /** Label style overrides. */
+  labelCss?: SystemStyleObject;
   /** Per-instance style overrides. */
   css?: SystemStyleObject;
   className?: string;
@@ -42,6 +38,7 @@ export interface CheckboxGroupProps
  */
 export const CheckboxGroup = ({
   label,
+  labelCss,
   helperText,
   errorMessage,
   helperTextCss,
@@ -58,10 +55,9 @@ export const CheckboxGroup = ({
       {(renderProps) => (
         <>
           {label != null && (
-            <RACLabel className={field().label}>
+            <FieldLabel isRequired={rest.isRequired} css={labelCss}>
               {label}
-              {rest.isRequired ? <FieldRequiredIndicator /> : null}
-            </RACLabel>
+            </FieldLabel>
           )}
           {typeof children === "function" ? children(renderProps) : children}
           <FieldSupport

package/src/ComboBox.tsx

@@ -16,29 +16,34 @@ import {
   ComboBox as RACComboBox,
   ComboBoxProps as RACComboBoxProps,
   Input as RACInput,
-  Label as RACLabel,
   ListBox as RACListBox,
   Popover,
   PopoverProps,
 } 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";
 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;
+  /** Label style overrides. */
+  labelCss?: SystemStyleObject;
   placeholder?: string;
   /**
    * Rendered inside the control, before the input — an icon for the current
@@ -81,11 +86,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;
@@ -103,6 +109,7 @@ export interface ComboBoxProps<T extends object>
 const ComboBoxInner = <T extends object>(
   {
     label,
+    labelCss,
     placeholder,
     startContent,
     children,
@@ -114,7 +121,8 @@ const ComboBoxInner = <T extends object>(
     helperText,
     errorMessage,
     helperTextCss,
-    css: cssProp,
+    labelPosition,
+    triggerCss,
     contentCss,
     className,
     ...props
@@ -123,7 +131,9 @@ const ComboBoxInner = <T extends object>(
 ) => {
   // As Select: forward whatever variant groups the merged recipe has.
   const [variantProps, rest] = select.splitVariantProps(props);
+  const intl = useIntl();
   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 +162,24 @@ 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}
+            css={labelCss}
+          >
             {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
@@ -171,7 +188,10 @@ const ComboBoxInner = <T extends object>(
             className={slots.value}
           />
           {indicator !== null && (
-            <RACButton className={slots.indicator}>
+            <RACButton
+              aria-label={intl.formatMessage(uiMessage("ui.combobox-trigger"))}
+              className={slots.indicator}
+            >
               {indicator ?? <Icon as={RiArrowDownSLine} />}
             </RACButton>
           )}
@@ -188,6 +208,7 @@ const ComboBoxInner = <T extends object>(
             )}
           >
             <RACListBox
+              aria-label={intl.formatMessage(uiMessage("ui.combobox-listbox"))}
               className={slots.list}
               renderEmptyState={
                 emptyState
@@ -203,6 +224,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",
+  },
+});