@microbit/ui 0.1.0-alpha.13 → 0.1.0-alpha.15

package/src/Menu.tsx

@@ -156,45 +156,75 @@ export const MenuItem = ({
   );
 };
 
-export interface MenuOptionGroupProps {
+interface MenuOptionGroupBaseProps {
   /** Group heading shown above the options (Chakra's `title`). */
   title?: ReactNode;
-  /** The selected `MenuItemOption`'s value (radio semantics). */
-  value?: string;
-  /** Called with the newly selected option's value. */
-  onChange?: (value: string) => void;
   /** `MenuItemOption` children. */
   children: ReactNode;
   css?: SystemStyleObject;
   className?: string;
 }
 
+export interface MenuOptionGroupRadioProps extends MenuOptionGroupBaseProps {
+  type?: "radio";
+  /** The selected `MenuItemOption`'s value. */
+  value?: string;
+  /** Called with the newly selected option's value. */
+  onChange?: (value: string) => void;
+}
+
+export interface MenuOptionGroupCheckboxProps extends MenuOptionGroupBaseProps {
+  type: "checkbox";
+  /** The checked `MenuItemOption`s' values. */
+  value?: string[];
+  /** Called with the full set of checked values after a toggle. */
+  onChange?: (value: string[]) => void;
+}
+
+export type MenuOptionGroupProps =
+  | MenuOptionGroupRadioProps
+  | MenuOptionGroupCheckboxProps;
+
 /**
- * MenuOptionGroup — a single-select (radio) group of `MenuItemOption`s within
- * a menu, replacing Chakra's `MenuOptionGroup type="radio"`. Selection is
- * section-scoped (RAC MenuSection), so a menu can mix action items and option
- * groups.
+ * MenuOptionGroup — a group of checkable `MenuItemOption`s within a menu,
+ * replacing Chakra's `MenuOptionGroup`. `type="radio"` (the default) is
+ * single-select and renders `menuitemradio`; `type="checkbox"` is multi-select
+ * and renders `menuitemcheckbox`, each option toggling independently.
+ *
+ * Selection is section-scoped (RAC MenuSection), so a menu can mix action items
+ * and option groups. An option's own `onAction` still fires on every press,
+ * including the press that deselects it — so a lone toggle can be driven either
+ * by the group's `onChange` or by the item's `onAction`.
+ *
+ * Choosing an option leaves the menu open (a plain `MenuItem` closes it), which
+ * is what Chakra's checkbox groups did. Chakra's *radio* groups closed on
+ * select, so a ported radio group is a deliberate behaviour change.
  */
-export const MenuOptionGroup = ({
-  title,
-  value,
-  onChange,
-  children,
-  css: cssProp,
-  className,
-}: MenuOptionGroupProps) => {
+export const MenuOptionGroup = (props: MenuOptionGroupProps) => {
+  const { title, children, css: cssProp, className } = props;
   const slots = menu();
+  const selectedKeys =
+    props.type === "checkbox"
+      ? props.value ?? []
+      : props.value != null
+        ? [props.value]
+        : [];
   return (
     <RACMenuSection
       className={cx(slots.group, cssProp ? css(cssProp) : undefined, className)}
-      selectionMode="single"
-      selectedKeys={value != null ? [value] : []}
+      selectionMode={props.type === "checkbox" ? "multiple" : "single"}
+      selectedKeys={selectedKeys}
       onSelectionChange={(keys) => {
-        if (keys !== "all") {
-          const key = keys.values().next().value;
-          if (key != null) {
-            onChange?.(String(key));
-          }
+        if (keys === "all") {
+          return;
+        }
+        const values = [...keys].map(String);
+        if (props.type === "checkbox") {
+          props.onChange?.(values);
+        } else if (values.length > 0) {
+          // Radio: a press that clears the selection reports nothing, matching
+          // Chakra, which had no way to express an empty radio group.
+          props.onChange?.(values[0]);
         }
       }}
     >

package/src/Modal.tsx

@@ -13,15 +13,18 @@ import {
 import {
   Button as RACButton,
   Dialog,
+  DialogTrigger as RACDialogTrigger,
   Heading as RACHeading,
   Modal as RACModal,
   ModalOverlay,
+  OverlayTriggerStateContext,
 } from "react-aria-components";
 import { css, cx } from "styled-system/css";
 import { dialog } from "styled-system/recipes";
 import { ConditionalValue, SystemStyleObject } from "styled-system/types";
 import { useIntl } from "react-intl";
 import { CloseIcon } from "./CloseIcon";
+import { dataAttrs } from "./data-attrs";
 import { uiMessage } from "./messages";
 import { UnmountCallback } from "./UnmountCallback";
 
@@ -48,9 +51,7 @@ export type ModalSize = ConditionalValue<
   | "full"
 >;
 
-export interface ModalProps {
-  isOpen: boolean;
-  onClose: () => void;
+export interface ModalOwnProps {
   size?: ModalSize;
   /** Allow closing by clicking the backdrop (default true; Escape always closes). */
   isDismissable?: boolean;
@@ -96,12 +97,53 @@ export interface ModalProps {
    */
   "aria-label"?: string;
   children: ReactNode;
+  /**
+   * `data-*` attributes land on the dialog box (where Chakra's went, on
+   * ModalContent), so end-to-end tests can address a dialog. Shells that
+   * forward their caller's data attributes can spread them straight in.
+   */
+  [key: `data-${string}`]: unknown;
 }
 
+/**
+ * A Modal you drive yourself. Also the type for a component that *forwards*
+ * modal props — `Omit<ControlledModalProps, "children">` — because a spread
+ * cannot be matched against the union `ModalProps` is: TypeScript has no way
+ * to know which half of it an object with `isOpen?: boolean` satisfies.
+ */
+export type ControlledModalProps = ModalOwnProps & {
+  /** Whether the dialog is showing. */
+  isOpen: boolean;
+  /** Called when the dialog asks to close. */
+  onClose: () => void;
+};
+
+/**
+ * The props of a `Modal`: its own, plus an open state that is either entirely
+ * yours or entirely a `DialogTrigger`'s. Never half of each — `isOpen`
+ * without `onClose` leaves the close button and Escape with nothing to call,
+ * so the pair is enforced rather than merely documented.
+ */
+export type ModalProps =
+  | ControlledModalProps
+  | (ModalOwnProps & { isOpen?: never; onClose?: never });
+
 /**
  * Modal — a focus-trapping dialog. Collapses Chakra's
  * Modal/ModalOverlay/ModalContent into a single shell; place ModalHeader,
  * ModalBody and ModalFooter inside.
+ *
+ * Two ways to drive it:
+ *
+ * - **Controlled** (`isOpen` + `onClose`), which is what a Chakra app ports
+ *   to, and what any dialog with more than one opener needs — a menu item and
+ *   a toolbar button opening the same dialog, or one opened from a handler
+ *   after an async result.
+ * - **Inside a `DialogTrigger`**, with neither prop: react-aria holds the
+ *   open state, the trigger opens it, and `ModalCloseButton` and the footer's
+ *   `useDialogClose()` still close it. Prefer this where a dialog has exactly
+ *   one trigger sitting next to it — there is no state to hold, and none to
+ *   get out of step.
  */
 export const Modal = ({
   isOpen,
@@ -119,7 +161,14 @@ export const Modal = ({
   finalFocusRef,
   "aria-label": ariaLabel,
   children,
+  ...rest
 }: ModalProps) => {
+  // Set by a DialogTrigger (or any react-aria overlay trigger) above us. When
+  // `isOpen` is given it is ignored: RAC's ModalOverlay prefers an explicit
+  // prop over the context, and so do we for the close function.
+  const triggerState = useContext(OverlayTriggerStateContext);
+  const close = onClose ?? (() => triggerState?.close());
+  const dataProps = dataAttrs(rest);
   const slots = dialog({ size, centered: isCentered });
   const motionlessClass = motionless
     ? css({
@@ -141,7 +190,7 @@ export const Modal = ({
       isOpen={isOpen}
       onOpenChange={(open) => {
         if (!open) {
-          onClose();
+          close();
         }
       }}
       isDismissable={isDismissable}
@@ -154,6 +203,7 @@ export const Modal = ({
     >
       <UnmountCallback callback={handleUnmount} />
       <RACModal
+        {...dataProps}
         style={contentStyle}
         className={cx(
           slots.content,
@@ -162,7 +212,7 @@ export const Modal = ({
         )}
       >
         <Dialog role={role} aria-label={ariaLabel} className={slots.inner}>
-          <SlotContext.Provider value={{ slots, onClose }}>
+          <SlotContext.Provider value={{ slots, onClose: close }}>
             {children}
           </SlotContext.Provider>
         </Dialog>
@@ -171,10 +221,40 @@ export const Modal = ({
   );
 };
 
+/**
+ * DialogTrigger — react-aria-components' <DialogTrigger>: wrap a trigger
+ * element and a `Modal`, and the open state is theirs rather than yours.
+ *
+ * ```tsx
+ * <DialogTrigger>
+ *   <Button>Settings</Button>
+ *   <Modal size="lg">
+ *     <ModalHeader>Settings</ModalHeader>
+ *     …
+ *   </Modal>
+ * </DialogTrigger>
+ * ```
+ *
+ * Only for a dialog with a single trigger beside it. A dialog opened from
+ * more than one place, from a menu item (which cannot hold a dialog — a
+ * non-collection child truncates the menu), or from a handler, wants the
+ * controlled `Modal` instead.
+ */
+export const DialogTrigger = RACDialogTrigger;
+
+/**
+ * The current dialog's close function — the same one `ModalCloseButton` uses,
+ * for a footer's own Cancel/Done buttons. Works in both modes, so a dialog's
+ * content need not know which is driving it.
+ */
+export const useDialogClose = () => useDialog().onClose;
+
 interface SlotProps {
   children?: ReactNode;
   css?: SystemStyleObject;
   className?: string;
+  /** `data-*` attributes land on the slot element, as they did on Chakra's. */
+  [key: `data-${string}`]: unknown;
 }
 
 /** Modal title. Rendered as RAC's labelling heading for the dialog. */
@@ -183,12 +263,18 @@ export const ModalHeader = ({
   css: cssProp,
   className,
   level,
+  ...rest
 }: SlotProps & {
-  /** Heading element level (default 3, like RAC). */ level?: number;
+  /**
+   * Heading element level. Defaults to 2: RAC's Dialog supplies that through
+   * HeadingContext for the `title` slot, not the bare Heading default of 3.
+   */
+  level?: number;
 }) => {
   const { slots } = useDialog();
   return (
     <RACHeading
+      {...dataAttrs(rest)}
       slot="title"
       level={level}
       className={cx(
@@ -202,10 +288,16 @@ export const ModalHeader = ({
   );
 };
 
-export const ModalBody = ({ children, css: cssProp, className }: SlotProps) => {
+export const ModalBody = ({
+  children,
+  css: cssProp,
+  className,
+  ...rest
+}: SlotProps) => {
   const { slots } = useDialog();
   return (
     <div
+      {...dataAttrs(rest)}
       className={cx(slots.body, cssProp ? css(cssProp) : undefined, className)}
     >
       {children}
@@ -217,10 +309,12 @@ export const ModalFooter = ({
   children,
   css: cssProp,
   className,
+  ...rest
 }: SlotProps) => {
   const { slots } = useDialog();
   return (
     <div
+      {...dataAttrs(rest)}
       className={cx(
         slots.footer,
         cssProp ? css(cssProp) : undefined,
@@ -235,6 +329,8 @@ export const ModalFooter = ({
 export interface ModalCloseButtonProps {
   /** Accessible name; defaults to the localized close label. */
   "aria-label"?: string;
+  /** `data-*` attributes land on the button. */
+  [key: `data-${string}`]: unknown;
 }
 
 /**
@@ -243,11 +339,13 @@ export interface ModalCloseButtonProps {
  */
 export const ModalCloseButton = ({
   "aria-label": ariaLabel,
+  ...rest
 }: ModalCloseButtonProps) => {
   const intl = useIntl();
   const { slots, onClose } = useDialog();
   return (
     <RACButton
+      {...dataAttrs(rest)}
       aria-label={ariaLabel ?? intl.formatMessage(uiMessage("ui.close-action"))}
       onPress={onClose}
       className={cx(

package/src/Select.recipe.ts

@@ -0,0 +1,179 @@
+/**
+ * (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",
+      borderColor: "gray.200",
+      borderRadius: "md",
+      bg: "white",
+      color: "inherit",
+      h: "10",
+      px: "4",
+      _hover: { borderColor: "gray.300" },
+      "&[data-focus-visible]": {
+        focusShadow: "outline",
+        borderColor: "focusBorder",
+      },
+      // A ComboBox's control is an input, which is focused whenever it is open.
+      "&[data-focused]": { focusShadow: "outline", borderColor: "focusBorder" },
+      "&[data-invalid]": { borderColor: "danger.500" },
+      "&[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",
+      outline: "none",
+      "&[data-focus-visible]": { focusShadow: "outline" },
+    },
+    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)",
+      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",
+      maxHeight: "inherit",
+      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>
+  );
+};