@microbit/ui 0.0.0-gray.ramp.92 → 0.0.0-gray.ramp.v2.106

package/README.md

@@ -84,10 +84,13 @@ node_modules/@microbit/ui/lang/ui.fr.json --ast --out-file ...` (multiple
    input files merge; ids are `ui.`-namespaced so they can't collide). This
    keeps the strings in the app's lazily loaded locale chunks rather than
    an eagerly bundled catalog-of-all-locales.
-6. **`ToastProvider`** once near the root, inside the `IntlProvider`.
-7. Optionally **`SharedUIProvider`** with an overlay-close registrar so the
-   app can dismiss open menus from outside the tree (e.g. the Android
-   hardware back button). Apps without one can omit the provider.
+6. **`SharedUIProvider`** inside the `IntlProvider`, wrapping the app. It
+   passes the locale on to react-aria, which translates its own built-in
+   strings (see [Strings](#strings)); without it those follow the browser
+   rather than the app's language setting. Also takes an optional
+   overlay-close registrar, so the app can dismiss open menus from outside
+   the tree (e.g. the Android hardware back button).
+7. **`ToastProvider`** once near the root, inside the two providers above.
 
 ## Legacy browser support (Safari < 15) — temporary
 
@@ -168,6 +171,19 @@ Semantic tokens (`languageText`, `statusBarBg`, `danger.*`, `toast*Bg`,
 brand presets override; they resolve through var indirection, so overrides
 apply wherever the token is consumed.
 
+### The grey rule
+
+The default `gray` ramp is **neutral and complete** (see
+[docs/gray-ramp.md](../../docs/gray-ramp.md) for the grading and its
+contrast guarantees). App/brand presets may override its _values_ — never
+its names, and never partially in a way that lets a stop fall through to
+a different grey system. Light stops (10–300) are free: byte-pin an app's
+existing surfaces or tint them. Dark-half values (350–900) may only be
+overridden luminance-matched to the family grading — each stop's contrast
+figure is the contract (400 ≥ 3:1 outlines, 500 ≥ 4.5:1 text), hue is
+free. Which stops an app tints is a per-app design decision, not a
+pattern to copy. New apps: take the default and ship.
+
 ## Runtime token lookups
 
 For values that feed _computation_ rather than stylesheets (canvas painting,
@@ -179,7 +195,7 @@ runtime lookup:
 import { token } from "@microbit/ui"; // re-exports styled-system/tokens
 
 token("colors.brand.500"); // "#007dbc" — raw value, safe for colour math
-token("colors.statusBarBg"); // "var(--colors-gray-500)" — CSS contexts only
+token("colors.statusBarBg"); // "var(--colors-brand2-500)" — CSS contexts only
 ```
 
 Base tokens resolve to raw values; **semantic tokens resolve to `var()`
@@ -207,6 +223,20 @@ Crowdin ZIP>` (config-driven over packages in
 `bin/update-translations.cjs`), after which you run `npm run i18n:tidy`
 from the root.
 
+### react-aria's own strings
+
+Separately from all of the above, react-aria has built-in strings of its own —
+stepper button labels, the toast region's landmark label, hidden dismiss
+buttons, listbox and selection announcements — and translates them from
+catalogs it bundles, nothing to do with react-intl. `SharedUIProvider` hands it
+the app's locale so the two agree.
+
+It covers 32 locales. Of ours, ca, cy and ga-IE (and the `lol` pseudo-locale)
+are not among them and fall back to English; the rest resolve, including where
+our id is less specific than react-aria's (`fr` finds its fr-FR). There is no
+supported way to supply translations for the locales it misses, so where one of
+its strings matters we pass our own text in as a label instead.
+
 ## Chakra UI heritage and license
 
 This package's design language began as a faithful port of

package/lang/ui.en.json

@@ -1,8 +1,16 @@
 {
+  "ui.breadcrumb": {
+    "defaultMessage": "Breadcrumb",
+    "description": "Accessible label for the breadcrumb navigation trail (the WAI-ARIA APG's conventional name)"
+  },
   "ui.close-action": {
     "defaultMessage": "Close",
     "description": "Close button text or label"
   },
+  "ui.loading": {
+    "defaultMessage": "Loading",
+    "description": "Announced by screen readers for a button showing a loading spinner"
+  },
   "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.0.0-gray.ramp.92",
+  "version": "0.0.0-gray.ramp.v2.106",
   "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",
@@ -61,6 +61,6 @@
     "vitest": "^4.1.10"
   },
   "publishConfig": {
-    "tag": "gray-ramp"
+    "tag": "gray-ramp-v2"
   }
 }

package/src/Avatar.recipe.ts

@@ -44,7 +44,10 @@ 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))",
+      // 350, not 400: a decorative fill written against Chakra's 2.26:1
+      // mid-grey, which the outline re-grade made an ink stop — 350 keeps
+      // the disc's weight (docs/gray-ramp.md).
+      background: "var(--avatar-bg, token(colors.gray.350))",
       color: "var(--avatar-color, token(colors.white))",
       borderColor: "white",
     },

package/src/Breadcrumb.recipe.ts

@@ -0,0 +1,43 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import { defineSlotRecipe } from "@pandacss/dev";
+
+/**
+ * Breadcrumb slot recipe — Chakra's Breadcrumb layout: a flex list with a
+ * separator between items. The links themselves are the shared `Link`
+ * (Chakra's BreadcrumbLink base was identical to its Link base), so there is
+ * no link slot; the current page renders as a plain span.
+ *
+ * Registered in the base preset (base-preset.ts). No variants, so it needs
+ * no `staticCss` entry.
+ */
+export const breadcrumb = defineSlotRecipe({
+  className: "breadcrumb",
+  slots: ["root", "list", "item", "separator"],
+  base: {
+    root: {},
+    list: {
+      display: "flex",
+      alignItems: "center",
+      listStyle: "none",
+      margin: 0,
+      padding: 0,
+    },
+    item: {
+      display: "inline-flex",
+      alignItems: "center",
+      // The separator renders inside every item (no children introspection);
+      // the last item's simply doesn't show.
+      "&:last-of-type [data-separator]": { display: "none" },
+    },
+    separator: {
+      // Chakra's default `spacing` was a literal 0.5rem; the token follows
+      // the library's existing lean (the button icon gap made the same
+      // call — see the playbook's open token-vs-literal spacing decision).
+      mx: "2",
+    },
+  },
+});

package/src/Breadcrumb.tsx

@@ -0,0 +1,116 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import { createContext, ReactNode, useContext } from "react";
+import { useIntl } from "react-intl";
+import { css, cx } from "styled-system/css";
+import { styled, type HTMLStyledProps } from "styled-system/jsx";
+import { breadcrumb } from "styled-system/recipes";
+import { SystemStyleObject } from "styled-system/types";
+import { Link } from "./Link";
+import { uiMessage } from "./messages";
+
+// The separator is declared once on the Breadcrumb and rendered by every
+// item; the current-page flag hops from BreadcrumbItem to the BreadcrumbLink
+// inside it (Chakra did both with cloneElement).
+const SeparatorContext = createContext<ReactNode>("/");
+const CurrentPageContext = createContext(false);
+
+export interface BreadcrumbProps {
+  /** Between items; an element or string. Chakra's default "/". */
+  separator?: ReactNode;
+  /** Per-instance style overrides for the nav (e.g. fontSize). */
+  css?: SystemStyleObject;
+  className?: string;
+  /** BreadcrumbItems. */
+  children: ReactNode;
+}
+
+/**
+ * Breadcrumb — navigation trail matching Chakra's: nav > ol > li with a
+ * separator between items and the current page as plain text with
+ * `aria-current="page"`.
+ */
+export const Breadcrumb = ({
+  separator = "/",
+  css: cssProp,
+  className,
+  children,
+}: BreadcrumbProps) => {
+  const intl = useIntl();
+  const slots = breadcrumb();
+  return (
+    <nav
+      aria-label={intl.formatMessage(uiMessage("ui.breadcrumb"))}
+      className={cx(slots.root, cssProp ? css(cssProp) : undefined, className)}
+    >
+      <SeparatorContext.Provider value={separator}>
+        <ol className={slots.list}>{children}</ol>
+      </SeparatorContext.Provider>
+    </nav>
+  );
+};
+
+export interface BreadcrumbItemProps {
+  /**
+   * Marks this item as the current page: its BreadcrumbLink renders as a
+   * plain span with `aria-current="page"` rather than a link.
+   */
+  isCurrentPage?: boolean;
+  css?: SystemStyleObject;
+  className?: string;
+  children: ReactNode;
+}
+
+export const BreadcrumbItem = ({
+  isCurrentPage = false,
+  css: cssProp,
+  className,
+  children,
+}: BreadcrumbItemProps) => {
+  const separator = useContext(SeparatorContext);
+  const slots = breadcrumb();
+  return (
+    <li
+      className={cx(slots.item, cssProp ? css(cssProp) : undefined, className)}
+    >
+      <CurrentPageContext.Provider value={isCurrentPage}>
+        {children}
+      </CurrentPageContext.Provider>
+      <span
+        data-separator
+        role="presentation"
+        aria-hidden
+        className={slots.separator}
+      >
+        {separator}
+      </span>
+    </li>
+  );
+};
+
+export type BreadcrumbLinkProps = HTMLStyledProps<"a">;
+
+// The current page's text: same element shape as the link (so call-site
+// style props keep working) minus the interactivity.
+const CurrentPageText = styled("span");
+
+/**
+ * The trail's link: the shared `Link` (Chakra's BreadcrumbLink base was its
+ * Link base), or a plain span with `aria-current="page"` inside an item
+ * marked `isCurrentPage`.
+ */
+export const BreadcrumbLink = (props: BreadcrumbLinkProps) => {
+  const isCurrentPage = useContext(CurrentPageContext);
+  if (isCurrentPage) {
+    const { href: _href, children, ...rest } = props;
+    return (
+      <CurrentPageText aria-current="page" {...rest}>
+        {children}
+      </CurrentPageText>
+    );
+  }
+  return <Link {...props} />;
+};

package/src/Button.recipe.ts

@@ -178,9 +178,6 @@ export const button = defineRecipe({
         borderWidth: "2px",
         borderColor: "gray.200",
         color: "languageText",
-        // The hover wash reads as a highlight because the app's gray ramp
-        // carries its brand undertone (per-app tinted ramps) — an
-        // achromatic gray.100 here goes drab, a tinted one doesn't.
         _hover: { color: "languageTextHover", bg: "gray.100" },
       },
     },

package/src/Button.tsx

@@ -4,6 +4,7 @@
  * SPDX-License-Identifier: MIT
  */
 import { forwardRef, ReactNode } from "react";
+import { useIntl } from "react-intl";
 import {
   Button as RACButton,
   ButtonProps as RACButtonProps,
@@ -12,6 +13,33 @@ import { css, cx } from "styled-system/css";
 import { button, ButtonVariantProps } from "styled-system/recipes";
 import { SystemStyleObject } from "styled-system/types";
 import { buttonIcon } from "./button-icon";
+import { uiMessage } from "./messages";
+import { Spinner } from "./Spinner";
+
+// Chakra's ButtonSpinner: a 1em spinner centred over the hidden label. Out of
+// flow, so the label alone sets the button's size; the recipe's base
+// `position: relative` is what it anchors to. Its own component so useIntl runs
+// only while a button is actually loading — a bare Button must keep working
+// without an IntlProvider (test renders commonly lack one).
+const ButtonSpinner = () => {
+  const intl = useIntl();
+  return (
+    <span
+      className={css({
+        position: "absolute",
+        inset: 0,
+        display: "flex",
+        alignItems: "center",
+        justifyContent: "center",
+      })}
+    >
+      <Spinner
+        aria-label={intl.formatMessage(uiMessage("ui.loading"))}
+        css={{ width: "1em", height: "1em" }}
+      />
+    </span>
+  );
+};
 
 export interface ButtonProps
   extends Omit<RACButtonProps, "className" | "children">,
@@ -23,6 +51,14 @@ export interface ButtonProps
   leftIcon?: ReactNode;
   /** Icon rendered after the label, matching Chakra's `rightIcon`. */
   rightIcon?: ReactNode;
+  /**
+   * Show a spinner in place of the label and disable interaction, matching
+   * Chakra's `isLoading`: the label stays in the layout but invisible, so the
+   * button keeps its size, and the dimmed disabled look applies. Chakra's
+   * `loadingText`/`spinnerPlacement` (a visible label beside the spinner) are
+   * unported — no app in the family used them.
+   */
+  isLoading?: boolean;
   children?: ReactNode;
 }
 
@@ -41,11 +77,23 @@ export const Button = forwardRef<HTMLButtonElement, ButtonProps>(
       className,
       leftIcon,
       rightIcon,
+      isLoading,
       children,
       ...rest
     },
     ref,
   ) {
+    const label = (
+      <>
+        {leftIcon ? (
+          <span className={buttonIcon({ side: "left" })}>{leftIcon}</span>
+        ) : null}
+        {children}
+        {rightIcon ? (
+          <span className={buttonIcon({ side: "right" })}>{rightIcon}</span>
+        ) : null}
+      </>
+    );
     return (
       <RACButton
         ref={ref}
@@ -54,15 +102,21 @@ export const Button = forwardRef<HTMLButtonElement, ButtonProps>(
           cssProp ? css(cssProp) : undefined,
           className,
         )}
+        data-loading={isLoading ? "" : undefined}
         {...rest}
+        isDisabled={isLoading || rest.isDisabled}
       >
-        {leftIcon ? (
-          <span className={buttonIcon({ side: "left" })}>{leftIcon}</span>
-        ) : null}
-        {children}
-        {rightIcon ? (
-          <span className={buttonIcon({ side: "right" })}>{rightIcon}</span>
-        ) : null}
+        {isLoading ? (
+          <>
+            <ButtonSpinner />
+            {/* Hidden with opacity, not removed: it keeps the button the size
+                it is when idle, so a row of buttons doesn't reflow. Still in
+                the accessibility tree, so the button keeps its name. */}
+            <span className={css({ opacity: 0 })}>{label}</span>
+          </>
+        ) : (
+          label
+        )}
       </RACButton>
     );
   },

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

@@ -0,0 +1,72 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import { ReactNode } from "react";
+import {
+  CheckboxGroup as RACCheckboxGroup,
+  CheckboxGroupProps as RACCheckboxGroupProps,
+} 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 CheckboxGroupProps
+  extends Omit<RACCheckboxGroupProps, "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. */
+  css?: SystemStyleObject;
+  className?: string;
+}
+
+/**
+ * CheckboxGroup — react-aria-components <CheckboxGroup> for a set of
+ * Checkboxes sharing one value array (each Checkbox's `value` marks its
+ * entry). 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 RadioGroup does. Chakra's CheckboxGroup was a bare
+ * context provider, so ported call sites gain the chrome rather than
+ * restating it around the group.
+ */
+export const CheckboxGroup = ({
+  label,
+  labelCss,
+  helperText,
+  errorMessage,
+  helperTextCss,
+  css: cssProp,
+  className,
+  children,
+  ...rest
+}: CheckboxGroupProps) => {
+  return (
+    <RACCheckboxGroup
+      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}
+          />
+        </>
+      )}
+    </RACCheckboxGroup>
+  );
+};

package/src/ComboBox.tsx

@@ -16,23 +16,32 @@ 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 {
+  FieldLabel,
+  FieldLayoutProps,
+  FieldSupport,
+  FieldSupportProps,
+} from "./Field";
 import { Icon } from "./Icon";
 import { SelectSlotProvider } from "./Select";
 
 export interface ComboBoxProps<T extends object>
   extends Omit<RACComboBoxProps<T>, "className" | "children" | "style">,
-    SelectVariantProps {
+    SelectVariantProps,
+    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
@@ -41,8 +50,15 @@ export interface ComboBoxProps<T extends object>
    * that (react-select did it with a custom `SingleValue`).
    */
   startContent?: ReactNode;
-  /** `SelectOption`s. */
-  children: ReactNode;
+  /**
+   * `SelectOption`s, or a render function over the `items` prop for a
+   * dynamic collection — which is how an async lookup works: drive `items`
+   * from loaded results (e.g. react-stately's useAsyncList) and filter
+   * server-side; react-aria skips its own text filtering when `items` is
+   * controlled. Pair with `emptyState` (swap its content while loading) and
+   * `isPopoverHidden` for a minimum query length.
+   */
+  children: ReactNode | ((item: T) => ReactNode);
   /**
    * Replaces the chevron; pass `null` for none, which is what a plain
    * autocomplete wants (react-select's `dropdownIndicator: display none`).
@@ -68,11 +84,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;
@@ -90,6 +107,7 @@ export interface ComboBoxProps<T extends object>
 const ComboBoxInner = <T extends object>(
   {
     label,
+    labelCss,
     placeholder,
     startContent,
     children,
@@ -98,7 +116,11 @@ const ComboBoxInner = <T extends object>(
     isPopoverHidden,
     placement = "bottom start",
     maxHeight,
-    css: cssProp,
+    helperText,
+    errorMessage,
+    helperTextCss,
+    labelPosition,
+    triggerCss,
     contentCss,
     className,
     ...props
@@ -108,6 +130,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);
@@ -136,12 +159,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}>{label}</RACLabel>}
+        {label != null && (
+          <FieldLabel
+            size={variantProps.size}
+            labelPosition={labelPosition}
+            isRequired={props.isRequired}
+            css={labelCss}
+          >
+            {label}
+          </FieldLabel>
+        )}
         <div
           ref={triggerRef}
-          className={cx(slots.trigger, cssProp ? css(cssProp) : undefined)}
+          className={cx(
+            slots.trigger,
+            triggerCss ? css(triggerCss) : undefined,
+          )}
         >
           {startContent}
           <RACInput
@@ -178,6 +213,12 @@ const ComboBoxInner = <T extends object>(
             </RACListBox>
           </Popover>
         )}
+        <FieldSupport
+          helperText={helperText}
+          errorMessage={errorMessage}
+          helperTextCss={helperTextCss}
+          labelPosition={labelPosition}
+        />
       </RACComboBox>
     </SelectSlotProvider>
   );