@microbit/ui 0.0.0-gray.ramp.90

package/src/ProgressBar.tsx

@@ -0,0 +1,61 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import { ProgressBar as RACProgressBar } from "react-aria-components";
+import { css } from "styled-system/css";
+import { SystemStyleObject } from "styled-system/types";
+
+export interface ProgressBarProps {
+  /** 0–100. */
+  value: number;
+  "aria-label": string;
+  /** Track overrides (size, radius, width), merged after the base. */
+  css?: SystemStyleObject;
+  /** Fill overrides (colour), merged after the base. */
+  barCss?: SystemStyleObject;
+}
+
+/**
+ * ProgressBar — react-aria-components <ProgressBar> styled like Chakra's md
+ * Progress (12px gray.100 track). Set the fill colour per call site via
+ * `barCss` (Chakra's colorScheme).
+ */
+export const ProgressBar = ({
+  value,
+  "aria-label": ariaLabel,
+  css: cssProp,
+  barCss,
+}: ProgressBarProps) => (
+  <RACProgressBar
+    value={value}
+    aria-label={ariaLabel}
+    // Single css() calls so caller overrides of base properties (radius, fill
+    // colour) are deduped at merge time rather than racing on stylesheet order.
+    className={css(
+      {
+        width: "100%",
+        height: 3,
+        bg: "gray.100",
+        overflow: "hidden",
+        borderRadius: "sm",
+      },
+      cssProp,
+    )}
+  >
+    {({ percentage }) => (
+      <div
+        className={css(
+          {
+            height: "100%",
+            bg: "progressFilledTrack",
+            transition: "width 0.2s",
+          },
+          barCss,
+        )}
+        style={{ width: `${percentage ?? 0}%` }}
+      />
+    )}
+  </RACProgressBar>
+);

package/src/Radio.recipe.ts

@@ -0,0 +1,112 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import { defineSlotRecipe } from "@pandacss/dev";
+
+/**
+ * Radio slot recipe — Chakra's radio with the default blue colorScheme
+ * (light mode) and its sm/md/lg size scale: the checkbox control rounded
+ * fully, with a 50% `currentColor` dot when selected instead of the check
+ * glyph. As with the checkbox, `borderColor: inherit` picks up a
+ * `borderColor` set on the root.
+ *
+ * State styling keys off data attributes stamped by the shared-ui Radio
+ * (react-aria provides the state via render props).
+ *
+ * Registered in the base preset (base-preset.ts), which also has the
+ * `staticCss` entry that keeps the runtime-prop size variants generated.
+ */
+export const radio = defineSlotRecipe({
+  className: "radio",
+  slots: ["root", "control", "label"],
+  base: {
+    root: {
+      display: "inline-flex",
+      alignItems: "center",
+      verticalAlign: "top",
+      cursor: "pointer",
+      position: "relative",
+      // As the checkbox: the control's `borderColor: inherit` reads this
+      // (call sites can still tint at the root); the reset's gray.200
+      // fallback was ~1.3:1. The accessible outline stop, as the input
+      // recipe (docs/gray-ramp.md).
+      borderColor: "gray.400",
+      "&[data-disabled]": { cursor: "not-allowed" },
+    },
+    control: {
+      display: "inline-flex",
+      alignItems: "center",
+      justifyContent: "center",
+      flexShrink: 0,
+      transitionProperty: "box-shadow",
+      transitionDuration: "normal",
+      borderWidth: "2px",
+      borderStyle: "solid",
+      borderRadius: "full",
+      borderColor: "inherit",
+      color: "white",
+      bg: "white",
+      "&[data-selected]": {
+        bg: "controlCheckedBg",
+        borderColor: "controlCheckedBg",
+        color: "white",
+        _hover: {
+          bg: "controlCheckedHoverBg",
+          borderColor: "controlCheckedHoverBg",
+        },
+        // Chakra's radio dot.
+        _before: {
+          content: '""',
+          display: "inline-block",
+          position: "relative",
+          width: "50%",
+          height: "50%",
+          borderRadius: "50%",
+          bg: "currentColor",
+        },
+      },
+      // Chakra's disabled greys; the selected block restates _hover so the
+      // widened native-:hover condition can't re-tint a disabled control.
+      "&[data-disabled]": {
+        bg: "gray.100",
+        borderColor: "gray.100",
+      },
+      "&[data-selected][data-disabled]": {
+        bg: "gray.200",
+        borderColor: "gray.200",
+        color: "gray.500",
+        _hover: { bg: "gray.200", borderColor: "gray.200" },
+      },
+      "&[data-focus-visible]": {
+        focusShadow: "outline",
+      },
+    },
+    label: {
+      userSelect: "none",
+      marginStart: "2",
+      "&[data-disabled]": { opacity: 0.4 },
+    },
+  },
+  variants: {
+    // Chakra's Radio size scale (the Checkbox control scale).
+    size: {
+      sm: {
+        control: { width: "3", height: "3" },
+        label: { fontSize: "sm" },
+      },
+      md: {
+        control: { width: "4", height: "4" },
+        label: { fontSize: "md" },
+      },
+      lg: {
+        control: { width: "5", height: "5" },
+        label: { fontSize: "lg" },
+      },
+    },
+  },
+  defaultVariants: {
+    size: "md",
+  },
+});

package/src/Radio.tsx

@@ -0,0 +1,89 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import { ReactNode } from "react";
+import {
+  Radio as RACRadio,
+  RadioProps as RACRadioProps,
+  RadioGroup as RACRadioGroup,
+  RadioGroupProps as RACRadioGroupProps,
+} from "react-aria-components";
+import { css, cx } from "styled-system/css";
+import { radio, RadioVariantProps } from "styled-system/recipes";
+import { SystemStyleObject } from "styled-system/types";
+
+export interface RadioGroupProps
+  extends Omit<RACRadioGroupProps, "className" | "style"> {
+  /** Per-instance style overrides, merged after the recipe. */
+  css?: SystemStyleObject;
+  className?: string;
+}
+
+/**
+ * RadioGroup — react-aria-components <RadioGroup> for a set of Radios. Carries
+ * no styling of its own: compose with Stack for layout, as Chakra call sites
+ * did.
+ */
+export const RadioGroup = ({
+  css: cssProp,
+  className,
+  ...rest
+}: RadioGroupProps) => {
+  return (
+    <RACRadioGroup
+      className={cx(cssProp ? css(cssProp) : undefined, className)}
+      {...rest}
+    />
+  );
+};
+
+export interface RadioProps
+  extends Omit<RACRadioProps, "className" | "children" | "style">,
+    RadioVariantProps {
+  /** Per-instance style overrides for the root, merged after the recipe. */
+  css?: SystemStyleObject;
+  className?: string;
+  children?: ReactNode;
+}
+
+/**
+ * Radio — react-aria-components <Radio> styled like Chakra's radio. Must be
+ * rendered inside a RadioGroup. Children render as the label.
+ */
+export const Radio = ({
+  size,
+  css: cssProp,
+  className,
+  children,
+  ...rest
+}: RadioProps) => {
+  const slots = radio({ size });
+  return (
+    <RACRadio
+      className={cx(slots.root, cssProp ? css(cssProp) : undefined, className)}
+      {...rest}
+    >
+      {({ isSelected, isFocusVisible, isDisabled }) => (
+        <>
+          <span
+            className={slots.control}
+            data-selected={isSelected || undefined}
+            data-focus-visible={isFocusVisible || undefined}
+            data-disabled={isDisabled || undefined}
+            aria-hidden
+          />
+          {children != null && (
+            <span
+              className={slots.label}
+              data-disabled={isDisabled || undefined}
+            >
+              {children}
+            </span>
+          )}
+        </>
+      )}
+    </RACRadio>
+  );
+};

package/src/Select.recipe.ts

@@ -0,0 +1,210 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import { defineSlotRecipe } from "@pandacss/dev";
+
+// Chakra's transition.property.common, inlined (Panda has no transitionProperty
+// token category).
+const transitionCommon =
+  "background-color, border-color, color, fill, stroke, opacity, box-shadow, transform";
+
+/**
+ * Select slot recipe — the dropdown pair, shared by `Select` (a listbox behind
+ * a button) and `ComboBox` (a listbox behind a text input). One recipe because
+ * the two differ only in what the control is: keeping them together is what
+ * stops a searchable and a non-searchable picker drifting apart visually.
+ *
+ * `trigger` is styled from the Chakra outline Input field so a select sits
+ * level with a TextField beside it; `content` matches the `menu` recipe's card
+ * so every dropdown surface in the family agrees.
+ *
+ * Apps restyle it through the `variant` group — classroom's `classroom`
+ * variant is the rounded pill its join form uses.
+ *
+ * Registered in the base preset (base-preset.ts).
+ */
+export const select = defineSlotRecipe({
+  className: "select",
+  slots: [
+    "root",
+    "label",
+    "trigger",
+    "value",
+    "indicator",
+    "content",
+    "list",
+    "option",
+    "optionIndicator",
+    "empty",
+  ],
+  base: {
+    root: {
+      display: "flex",
+      flexDirection: "column",
+      width: "100%",
+    },
+    label: {
+      fontSize: "md",
+      fontWeight: "medium",
+      marginEnd: "3",
+      mb: "2",
+    },
+    trigger: {
+      display: "flex",
+      alignItems: "center",
+      justifyContent: "space-between",
+      gap: "2",
+      width: "100%",
+      minWidth: 0,
+      outline: "none",
+      appearance: "none",
+      font: "inherit",
+      textAlign: "start",
+      cursor: "pointer",
+      transitionProperty: transitionCommon,
+      transitionDuration: "normal",
+      border: "1px solid",
+      // 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",
+      borderRadius: "md",
+      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.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.
+      // `> &` rather than a descendant selector, so an app's own invalid form
+      // wrapper cannot paint every control inside it red.
+      //
+      // Declared after hover and before focus so red beats a hover tint and
+      // the focus ring beats red, as in the input recipe.
+      "[data-invalid] > &": {
+        borderColor: "danger.500",
+        boxShadow: "0 0 0 1px token(colors.danger.500)",
+      },
+      // Two focus cases. `data-focus-visible` is Select's button on keyboard
+      // focus only (RAC leaves it unset for mouse, matching the react-aria
+      // docs' Select). The `:has()` arm is ComboBox: its control is a plain
+      // div wrapping an input, so it gets no RAC attributes itself, and as a
+      // text field it should show focus on any modality. That arm watches
+      // native `:focus` rather than the input's `data-focused`, because
+      // react-aria dispatches a synthetic blur at the input whenever virtual
+      // focus moves to an option (aria-activedescendant) — which strips RAC's
+      // attribute for as long as the list has an active option, real focus
+      // never having left. Select's trigger holds no input, so it can't match.
+      "&[data-focus-visible], &:has(input:focus)": {
+        boxShadow: "0 0 0 1px token(colors.focusBorder)",
+        borderColor: "focusBorder",
+        outline: "2px solid transparent",
+        outlineOffset: "2px",
+      },
+      "&[data-disabled]": { opacity: 0.4, cursor: "not-allowed" },
+    },
+    // Whatever shows the current value: Select's SelectValue, ComboBox's
+    // input. One slot for both, so an app restyling the placeholder (say)
+    // does not have to know which kind of control it is looking at.
+    value: {
+      flex: "1",
+      minWidth: 0,
+      overflow: "hidden",
+      textOverflow: "ellipsis",
+      whiteSpace: "nowrap",
+      outline: "none",
+      bg: "transparent",
+      color: "inherit",
+      font: "inherit",
+      // RAC sets data-placeholder on SelectValue when nothing is chosen; the
+      // ComboBox input uses the real placeholder attribute.
+      "&[data-placeholder]": { color: "gray.500" },
+      _placeholder: { color: "gray.500" },
+    },
+    indicator: {
+      display: "inline-flex",
+      flexShrink: 0,
+      alignItems: "center",
+      justifyContent: "center",
+      fontSize: "1.25em",
+      color: "inherit",
+      // No pointer-events:none here: in a ComboBox this slot is the button
+      // that opens the list. Select's is an aria-hidden span inside the
+      // trigger, so it needs no help being inert.
+      background: "transparent",
+      border: "none",
+      cursor: "pointer",
+      // No focus styling, deliberately: react-aria keeps a ComboBox's toggle
+      // button out of the tab order (the input owns the keyboard), so a ring
+      // here would only ever be reachable programmatically, and would suggest
+      // the chevron is a tab stop. The whole control shows focus instead.
+      outline: "none",
+    },
+    content: {
+      // Line the card up with the control, as a select should and as
+      // react-select did. `Select` gets this from RAC, whose trigger is the
+      // button it measures; `ComboBox` measures its own control and sets the
+      // width inline, because RAC's var is the *input's* width there.
+      minWidth: "var(--trigger-width)",
+      display: "flex",
+      flexDirection: "column",
+      bg: "white",
+      color: "inherit",
+      py: "2",
+      zIndex: "popover",
+      borderRadius: "md",
+      borderWidth: "1px",
+      borderColor: "gray.200",
+      boxShadow: "sm",
+      // Matches the menu recipe's fade/scale.
+      transformOrigin: "top",
+      opacity: 1,
+      transform: "scale(1)",
+      transition: "opacity 0.1s ease-out, transform 0.1s ease-out",
+      "&[data-entering]": { opacity: 0, transform: "scale(0.95)" },
+      "&[data-exiting]": { opacity: 0, transform: "scale(0.95)" },
+      _motionReduce: { transition: "none" },
+    },
+    list: {
+      outline: "none",
+      overflowY: "auto",
+    },
+    option: {
+      display: "flex",
+      alignItems: "center",
+      gap: "2",
+      py: "1.5",
+      px: "3",
+      cursor: "pointer",
+      color: "inherit",
+      outline: "none",
+      transitionProperty: "background",
+      transitionDuration: "ultra-fast",
+      transitionTimingFunction: "ease-in",
+      "&[data-focused]": { bg: "gray.100" },
+      "&[data-pressed]": { bg: "gray.200" },
+      "&[data-disabled]": { opacity: 0.4, cursor: "not-allowed" },
+    },
+    optionIndicator: {
+      display: "inline-flex",
+      flexShrink: 0,
+      alignItems: "center",
+      justifyContent: "center",
+      marginStart: "auto",
+      fontSize: "0.8em",
+      opacity: 0,
+      "[data-selected] &": { opacity: 1 },
+    },
+    empty: {
+      px: "3",
+      py: "2",
+      color: "gray.600",
+    },
+  },
+});

package/src/Select.tsx

@@ -0,0 +1,153 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import { createContext, ReactNode, useContext } from "react";
+import {
+  Button as RACButton,
+  Label as RACLabel,
+  ListBox as RACListBox,
+  ListBoxItem as RACListBoxItem,
+  ListBoxItemProps as RACListBoxItemProps,
+  Popover,
+  PopoverProps,
+  Select as RACSelect,
+  SelectProps as RACSelectProps,
+  SelectValue,
+} 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 { SystemStyleObject } from "styled-system/types";
+import { Icon } from "./Icon";
+
+export type SelectSlots = ReturnType<typeof select>;
+
+// Options are children, so they can't see the variant their Select was given.
+// The parent hands its resolved slots down, as Modal does for its own slots.
+const SlotContext = createContext<SelectSlots>(select({}));
+
+export const useSelectSlots = () => useContext(SlotContext);
+
+export const SelectSlotProvider = SlotContext.Provider;
+
+export interface SelectProps<T extends object>
+  extends Omit<
+      RACSelectProps<T>,
+      "className" | "children" | "style" | "placeholder"
+    >,
+    SelectVariantProps {
+  /** Visible label. Use `aria-label` instead where the design has none. */
+  label?: ReactNode;
+  /** Shown in the trigger while nothing is chosen (Chakra's placeholder). */
+  placeholder?: string;
+  /** `SelectOption`s. */
+  children: ReactNode;
+  /**
+   * Replaces the chevron; `null` removes it. Rarely right on a Select — the
+   * chevron is the only thing marking its trigger as a dropdown rather than
+   * a label, where a ComboBox's text input speaks for itself (which is why
+   * classroom's chevron-less autocomplete is a ComboBox).
+   */
+  indicator?: ReactNode | null;
+  /** Placement of the dropdown relative to the trigger. */
+  placement?: PopoverProps["placement"];
+  /**
+   * Cap the dropdown's height (react-select's `maxMenuHeight`). A prop rather
+   * than a `contentCss` rule because RAC writes its own max-height inline
+   * while positioning, which beats any class.
+   */
+  maxHeight?: number;
+  /** Per-instance overrides for the trigger. */
+  css?: SystemStyleObject;
+  /** Per-instance overrides for the dropdown card. */
+  contentCss?: SystemStyleObject;
+  className?: string;
+}
+
+/**
+ * Select — a listbox behind a button, for choosing one of a known set.
+ * Replaces Chakra-era react-select at non-searchable call sites; use ComboBox
+ * where the user should be able to type to filter.
+ */
+export const Select = <T extends object>({
+  label,
+  placeholder,
+  children,
+  indicator,
+  placement = "bottom start",
+  maxHeight,
+  css: cssProp,
+  contentCss,
+  className,
+  ...props
+}: SelectProps<T>) => {
+  // 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 slots = select(variantProps);
+  return (
+    <SelectSlotProvider value={slots}>
+      <RACSelect
+        {...(rest as RACSelectProps<T>)}
+        className={cx(slots.root, className)}
+      >
+        {label != null && <RACLabel className={slots.label}>{label}</RACLabel>}
+        <RACButton
+          className={cx(slots.trigger, cssProp ? css(cssProp) : undefined)}
+        >
+          <SelectValue className={slots.value}>
+            {({ isPlaceholder, defaultChildren }) =>
+              isPlaceholder ? placeholder ?? "" : defaultChildren
+            }
+          </SelectValue>
+          {indicator !== null && (
+            <span className={slots.indicator} aria-hidden>
+              {indicator ?? <Icon as={RiArrowDownSLine} />}
+            </span>
+          )}
+        </RACButton>
+        <Popover
+          placement={placement}
+          maxHeight={maxHeight}
+          className={cx(
+            slots.content,
+            contentCss ? css(contentCss) : undefined,
+          )}
+        >
+          <RACListBox className={slots.list}>{children}</RACListBox>
+        </Popover>
+      </RACSelect>
+    </SelectSlotProvider>
+  );
+};
+
+export interface SelectOptionProps
+  extends Omit<RACListBoxItemProps, "className" | "children" | "style"> {
+  children?: ReactNode;
+  css?: SystemStyleObject;
+  className?: string;
+}
+
+/** A row in a `Select` or `ComboBox` list. */
+export const SelectOption = ({
+  children,
+  css: cssProp,
+  className,
+  ...rest
+}: SelectOptionProps) => {
+  const slots = useSelectSlots();
+  return (
+    <RACListBoxItem
+      {...rest}
+      className={cx(
+        slots.option,
+        cssProp ? css(cssProp) : undefined,
+        className,
+      )}
+    >
+      {children}
+    </RACListBoxItem>
+  );
+};

package/src/SharedUIProvider.tsx

@@ -0,0 +1,55 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import { createContext, ReactNode, useContext, useMemo } from "react";
+
+/**
+ * Registers the close function of the currently open dismissable overlay, or
+ * clears it (null) when the overlay closes. Installed by apps that need to
+ * dismiss overlays from outside the component tree — e.g. the Android
+ * hardware back button. Only one overlay is open at a time.
+ */
+export type OverlayCloseRegistrar = (close: (() => void) | null) => void;
+
+interface SharedUIContextValue {
+  overlayCloseRegistrar?: OverlayCloseRegistrar;
+}
+
+const SharedUIContext = createContext<SharedUIContextValue | null>(null);
+
+export interface SharedUIProviderProps {
+  overlayCloseRegistrar?: OverlayCloseRegistrar;
+  children: ReactNode;
+}
+
+/**
+ * SharedUIProvider — the app-side installation point for optional shared-ui
+ * integrations. Currently that is only the overlay-close registrar, so apps
+ * without one can omit the provider entirely. Localized strings come from
+ * react-intl: an IntlProvider must be mounted above shared-ui components
+ * (see the package README for merging this package's message catalogs).
+ */
+export const SharedUIProvider = ({
+  overlayCloseRegistrar,
+  children,
+}: SharedUIProviderProps) => {
+  const value = useMemo(
+    () => ({ overlayCloseRegistrar }),
+    [overlayCloseRegistrar],
+  );
+  return (
+    <SharedUIContext.Provider value={value}>
+      {children}
+    </SharedUIContext.Provider>
+  );
+};
+
+/**
+ * The app-installed overlay-close registrar, if any. Overlay components run
+ * controlled and register their close function while open so the app can
+ * dismiss them; without a registrar they manage open state internally.
+ */
+export const useOverlayCloseRegistrar = (): OverlayCloseRegistrar | undefined =>
+  useContext(SharedUIContext)?.overlayCloseRegistrar;