@microbit/ui 0.1.0-alpha.14 → 0.1.0-alpha.16

package/src/Checkbox.tsx

@@ -12,13 +12,33 @@ import { css, cx } from "styled-system/css";
 import { checkbox, CheckboxVariantProps } from "styled-system/recipes";
 import { SystemStyleObject } from "styled-system/types";
 
+/** What a render-prop child is told about the checkbox. */
+export interface CheckboxState {
+  isSelected: boolean;
+  isFocusVisible: boolean;
+  isDisabled: boolean;
+}
+
 export interface CheckboxProps
   extends Omit<RACCheckboxProps, "className" | "children" | "style">,
     CheckboxVariantProps {
   /** Per-instance style overrides for the root, merged after the recipe. */
   css?: SystemStyleObject;
   className?: string;
-  children?: ReactNode;
+  /**
+   * The label. A function receives the checkbox's state, for a label that
+   * changes with it.
+   */
+  children?: ReactNode | ((state: CheckboxState) => ReactNode);
+  /**
+   * Whether to draw the box. `false` is for a checkbox whose children draw
+   * the selected state themselves — a selectable tile, or an avatar that
+   * grows a tick. The label wrapper goes with it, so the children own the
+   * whole row, including the focus ring the box would otherwise carry.
+   *
+   * @default true
+   */
+  control?: boolean;
 }
 
 /**
@@ -31,6 +51,7 @@ export const Checkbox = ({
   css: cssProp,
   className,
   children,
+  control,
   ...rest
 }: CheckboxProps) => {
   const slots = checkbox({ size });
@@ -39,38 +60,47 @@ export const Checkbox = ({
       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
-          >
-            {isSelected && (
-              <svg viewBox="0 0 12 10" className={slots.icon} aria-hidden>
-                <polyline
-                  points="1.5 6 4.5 9 10.5 1"
-                  fill="none"
-                  stroke="currentColor"
-                  strokeWidth="2"
-                  strokeLinecap="round"
-                  strokeLinejoin="round"
-                />
-              </svg>
-            )}
-          </span>
-          {children != null && (
+      {({ isSelected, isFocusVisible, isDisabled }) => {
+        const content =
+          typeof children === "function"
+            ? children({ isSelected, isFocusVisible, isDisabled })
+            : children;
+        if (control === false) {
+          return content;
+        }
+        return (
+          <>
             <span
-              className={slots.label}
+              className={slots.control}
+              data-selected={isSelected || undefined}
+              data-focus-visible={isFocusVisible || undefined}
               data-disabled={isDisabled || undefined}
+              aria-hidden
             >
-              {children}
+              {isSelected && (
+                <svg viewBox="0 0 12 10" className={slots.icon} aria-hidden>
+                  <polyline
+                    points="1.5 6 4.5 9 10.5 1"
+                    fill="none"
+                    stroke="currentColor"
+                    strokeWidth="2"
+                    strokeLinecap="round"
+                    strokeLinejoin="round"
+                  />
+                </svg>
+              )}
             </span>
-          )}
-        </>
-      )}
+            {content != null && (
+              <span
+                className={slots.label}
+                data-disabled={isDisabled || undefined}
+              >
+                {content}
+              </span>
+            )}
+          </>
+        );
+      }}
     </RACCheckbox>
   );
 };

package/src/ComboBox.tsx

@@ -0,0 +1,192 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import {
+  ForwardedRef,
+  forwardRef,
+  ReactNode,
+  useLayoutEffect,
+  useRef,
+  useState,
+} from "react";
+import {
+  Button as RACButton,
+  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 { SystemStyleObject } from "styled-system/types";
+import { Icon } from "./Icon";
+import { SelectSlotProvider } from "./Select";
+
+export interface ComboBoxProps<T extends object>
+  extends Omit<RACComboBoxProps<T>, "className" | "children" | "style">,
+    SelectVariantProps {
+  /** Visible label. Use `aria-label` instead where the design has none. */
+  label?: ReactNode;
+  placeholder?: string;
+  /**
+   * Rendered inside the control, before the input — an icon for the current
+   * value, say. A ComboBox's control is a text input, so unlike a Select it
+   * cannot show anything but text for what is chosen; this is the way round
+   * that (react-select did it with a custom `SingleValue`).
+   */
+  startContent?: ReactNode;
+  /** `SelectOption`s. */
+  children: ReactNode;
+  /**
+   * Replaces the chevron; pass `null` for none, which is what a plain
+   * autocomplete wants (react-select's `dropdownIndicator: display none`).
+   */
+  indicator?: ReactNode | null;
+  /**
+   * Shown in place of the list when nothing matches (react-select's
+   * `noOptionsMessage`). Implies `allowsEmptyCollection`, since RAC otherwise
+   * closes the popover the moment the collection empties.
+   */
+  emptyState?: ReactNode;
+  /**
+   * Keep the dropdown shut until this prop is true. For gating on a minimum
+   * query length — react-aria has no `minLength`, and rendering an empty list
+   * still opens an empty card.
+   */
+  isPopoverHidden?: boolean;
+  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 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.
+   */
+  css?: SystemStyleObject;
+  /** Per-instance overrides for the dropdown card. */
+  contentCss?: SystemStyleObject;
+  className?: string;
+}
+
+/**
+ * ComboBox — a text input that filters a listbox, for choosing one of a known
+ * set where typing to narrow it down is the point. Use Select where the list
+ * is short enough to just pick from.
+ *
+ * Note the react-select difference this replaces: react-select filtered on
+ * `label` and kept the menu open on selection unless told otherwise, whereas
+ * react-aria filters on each item's `textValue` and closes on selection.
+ */
+const ComboBoxInner = <T extends object>(
+  {
+    label,
+    placeholder,
+    startContent,
+    children,
+    indicator,
+    emptyState,
+    isPopoverHidden,
+    placement = "bottom start",
+    maxHeight,
+    css: cssProp,
+    contentCss,
+    className,
+    ...props
+  }: ComboBoxProps<T>,
+  ref: ForwardedRef<HTMLInputElement>,
+) => {
+  // As Select: forward whatever variant groups the merged recipe has.
+  const [variantProps, rest] = select.splitVariantProps(props);
+  const slots = select(variantProps);
+  // 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);
+  // RAC's --trigger-width measures the input it anchors a ComboBox to, which
+  // is the control's content box — so a card sized from it is narrower than
+  // the field by the padding and border. Measure the control instead. State
+  // rather than reading the ref at render time: the popover is mounted from
+  // the first render, before the ref is set, and nothing would re-render it.
+  const [triggerWidth, setTriggerWidth] = useState<number>();
+  useLayoutEffect(() => {
+    const el = triggerRef.current;
+    if (!el) {
+      return;
+    }
+    const update = () => setTriggerWidth(el.offsetWidth);
+    update();
+    if (typeof ResizeObserver === "undefined") {
+      return;
+    }
+    const observer = new ResizeObserver(update);
+    observer.observe(el);
+    return () => observer.disconnect();
+  }, []);
+  return (
+    <SelectSlotProvider value={slots}>
+      <RACComboBox
+        allowsEmptyCollection={emptyState != null}
+        {...(rest as RACComboBoxProps<T>)}
+        className={cx(slots.root, className)}
+      >
+        {label != null && <RACLabel className={slots.label}>{label}</RACLabel>}
+        <div
+          ref={triggerRef}
+          className={cx(slots.trigger, cssProp ? css(cssProp) : undefined)}
+        >
+          {startContent}
+          <RACInput
+            ref={ref}
+            placeholder={placeholder}
+            className={slots.value}
+          />
+          {indicator !== null && (
+            <RACButton className={slots.indicator}>
+              {indicator ?? <Icon as={RiArrowDownSLine} />}
+            </RACButton>
+          )}
+        </div>
+        {!isPopoverHidden && (
+          <Popover
+            triggerRef={triggerRef}
+            placement={placement}
+            maxHeight={maxHeight}
+            style={triggerWidth ? { width: triggerWidth } : undefined}
+            className={cx(
+              slots.content,
+              contentCss ? css(contentCss) : undefined,
+            )}
+          >
+            <RACListBox
+              className={slots.list}
+              renderEmptyState={
+                emptyState
+                  ? () => <div className={slots.empty}>{emptyState}</div>
+                  : undefined
+              }
+            >
+              {children}
+            </RACListBox>
+          </Popover>
+        )}
+      </RACComboBox>
+    </SelectSlotProvider>
+  );
+};
+
+/**
+ * forwardRef with generics needs the cast (React's types cannot express it),
+ * so the ref lands on the input — call sites focus it for validation.
+ */
+export const ComboBox = forwardRef(ComboBoxInner) as <T extends object>(
+  props: ComboBoxProps<T> & { ref?: ForwardedRef<HTMLInputElement> },
+) => ReturnType<typeof ComboBoxInner>;

package/src/GridList.recipe.ts

@@ -0,0 +1,58 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import { defineSlotRecipe } from "@pandacss/dev";
+
+/**
+ * GridList slot recipe — a vertical list of selectable rows, each of which may
+ * hold its own interactive controls (which is what makes it a grid rather than
+ * a listbox: the roving tab index moves through rows, and the controls inside
+ * a row are reachable without leaving it).
+ *
+ * Chakra had no equivalent, so there is no Chakra look to match: the greys
+ * here are the family's neutral list styling, and an app with a strong
+ * selection colour restates them (classroom's roster does).
+ *
+ * Registered in the base preset (base-preset.ts), which also has the
+ * `staticCss` entry that keeps the runtime-prop variants generated.
+ */
+export const gridList = defineSlotRecipe({
+  className: "grid-list",
+  slots: ["root", "item"],
+  base: {
+    root: {
+      // The list takes the roving tab index, so it is focusable itself and
+      // would otherwise draw the platform ring around the whole list.
+      outline: "none",
+    },
+    item: {
+      display: "flex",
+      alignItems: "center",
+      position: "relative",
+      // A row is interactive by definition — it selects, or it acts.
+      cursor: "pointer",
+      outline: "none",
+      transitionProperty: "background",
+      transitionDuration: "ultra-fast",
+      transitionTimingFunction: "ease-in",
+      _hover: { bg: "gray.50" },
+      // A row holding an open menu (or any other popover) keeps the hover
+      // grey, so the row an open menu belongs to stays visible. Hover state
+      // cannot do this on its own: a Popover lays a fixed full-viewport
+      // underlay over the page while open, which takes the pointer off the
+      // row — `:hover` and RAC's own `data-hovered` both drop the moment the
+      // menu appears. A trigger carries `aria-expanded` (useOverlayTrigger),
+      // so the row can see its own open overlay.
+      "&:has([aria-expanded=true])": { bg: "gray.50" },
+      "&[data-selected]": {
+        bg: "gray.100",
+        _hover: { bg: "gray.100" },
+        "&:has([aria-expanded=true])": { bg: "gray.100" },
+      },
+      "&[data-focus-visible]": { focusShadow: "outline" },
+      "&[data-disabled]": { opacity: 0.4, cursor: "not-allowed" },
+    },
+  },
+});

package/src/GridList.tsx

@@ -0,0 +1,81 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import { ReactNode } from "react";
+import {
+  GridList as RACGridList,
+  GridListItem as RACGridListItem,
+  GridListItemProps as RACGridListItemProps,
+  GridListProps as RACGridListProps,
+} from "react-aria-components";
+import { css, cx } from "styled-system/css";
+import { gridList } from "styled-system/recipes";
+import { SystemStyleObject } from "styled-system/types";
+
+export interface GridListProps<T extends object>
+  extends Omit<RACGridListProps<T>, "className" | "style" | "children"> {
+  /** `GridListItem`s, or a render function when `items` is given. */
+  children: RACGridListProps<T>["children"];
+  /** Per-instance style overrides for the list, merged after the recipe. */
+  css?: SystemStyleObject;
+  className?: string;
+}
+
+/**
+ * GridList — react-aria-components' <GridList>: a list of selectable rows,
+ * each of which may contain its own buttons and menus.
+ *
+ * Reach for it over a `ListBox` when the rows carry controls: a listbox option
+ * is a leaf, so a button inside one is unreachable by keyboard, where a grid
+ * row's contents are part of the grid's navigation.
+ */
+export const GridList = <T extends object>({
+  css: cssProp,
+  className,
+  children,
+  ...rest
+}: GridListProps<T>) => {
+  const slots = gridList();
+  return (
+    <RACGridList
+      {...rest}
+      className={cx(slots.root, cssProp ? css(cssProp) : undefined, className)}
+    >
+      {children}
+    </RACGridList>
+  );
+};
+
+export interface GridListItemProps<T extends object = object>
+  extends Omit<RACGridListItemProps<T>, "className" | "style" | "children"> {
+  children?: ReactNode;
+  /** Per-instance style overrides for the row, merged after the recipe. */
+  css?: SystemStyleObject;
+  className?: string;
+}
+
+/**
+ * A row in a `GridList`. Its children are laid out by the row itself — the
+ * gridcell react-aria puts between them is `display: contents`.
+ *
+ * Give every row a `textValue`: react-aria derives typeahead text from string
+ * children only, and a row is usually a composition rather than a string.
+ */
+export const GridListItem = <T extends object = object>({
+  css: cssProp,
+  className,
+  children,
+  ...rest
+}: GridListItemProps<T>) => {
+  const slots = gridList();
+  return (
+    <RACGridListItem
+      {...rest}
+      className={cx(slots.item, cssProp ? css(cssProp) : undefined, className)}
+    >
+      {children}
+    </RACGridListItem>
+  );
+};

package/src/Icon.tsx

@@ -3,13 +3,27 @@
  *
  * SPDX-License-Identifier: MIT
  */
-import { IconType } from "react-icons/lib";
+import { ComponentType, SVGProps } from "react";
 import { css, cx } from "styled-system/css";
 import { SystemStyleObject } from "styled-system/types";
 
+/**
+ * Any component that renders an `<svg>` from svg props. Deliberately no
+ * narrower than the props `Icon` actually passes, so it accepts both
+ * react-icons' `IconType` and svgr components (`import X from "./x.svg?react"`,
+ * which the apps use for their custom-path icons — Chakra's `<Icon as={…}>`
+ * took either).
+ */
+export type IconComponent = ComponentType<
+  Pick<
+    SVGProps<SVGSVGElement>,
+    "className" | "focusable" | "role" | "aria-label" | "aria-hidden"
+  >
+>;
+
 export interface IconProps {
-  /** The react-icons component to render. */
-  as: IconType;
+  /** The icon component to render: a react-icons glyph or an svgr import. */
+  as: IconComponent;
   /** Panda style overrides (size via fontSize/boxSize, colour, etc.). */
   css?: SystemStyleObject;
   className?: string;
@@ -43,6 +57,12 @@ export const Icon = ({
         lineHeight: "1em",
         flexShrink: 0,
         fill: "currentColor",
+        // Chakra's Icon set this on the element itself, and an inline-block
+        // icon sits ~3px off without it. Panda's preflight happens to set it
+        // on every svg, which hid the omission in apps that had already
+        // flipped — classroom measured the difference at its kill-switch,
+        // where the preflight arrived and moved every icon back.
+        verticalAlign: "middle",
         ...cssProp,
       }),
       className,

package/src/Input.tsx

@@ -23,14 +23,18 @@ export interface InputProps
  * labelled field with help/error text use TextField instead.
  */
 export const Input = forwardRef<HTMLInputElement, InputProps>(function Input(
-  { size, css: cssProp, className, ...rest },
+  { css: cssProp, className, ...props },
   ref,
 ) {
+  // splitVariantProps, not a hand-picked `size`: an app preset can add variant
+  // groups to the recipe (classroom adds `variant`), and cherry-picking would
+  // silently drop them onto the DOM as unknown attributes instead.
+  const [variantProps, rest] = input.splitVariantProps(props);
   return (
     <input
       ref={ref}
       className={cx(
-        input({ size }),
+        input(variantProps),
         cssProp ? css(cssProp) : undefined,
         className,
       )}

package/src/ListBox.recipe.ts

@@ -0,0 +1,43 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import { defineSlotRecipe } from "@pandacss/dev";
+
+/**
+ * ListBox slot recipe — a standalone list of choosable options, single or
+ * multiple. Distinct from the `select` recipe's `list`/`option` slots, which
+ * style the same react-aria primitive inside a dropdown card: this one sits
+ * inline on the page, so it carries no surface of its own.
+ *
+ * An option is a leaf — if the rows need their own buttons or menus, they
+ * want `GridList` instead.
+ *
+ * Registered in the base preset (base-preset.ts), which also has the
+ * `staticCss` entry that keeps the runtime-prop variants generated.
+ */
+export const listBox = defineSlotRecipe({
+  className: "list-box",
+  slots: ["root", "option"],
+  base: {
+    root: {
+      // The listbox holds the roving tab index, so it is focusable itself and
+      // would otherwise draw the platform ring around the whole list.
+      outline: "none",
+    },
+    option: {
+      display: "flex",
+      alignItems: "center",
+      cursor: "pointer",
+      outline: "none",
+      transitionProperty: "background",
+      transitionDuration: "ultra-fast",
+      transitionTimingFunction: "ease-in",
+      _hover: { bg: "gray.50" },
+      "&[data-selected]": { bg: "gray.100", _hover: { bg: "gray.100" } },
+      "&[data-focus-visible]": { focusShadow: "outline" },
+      "&[data-disabled]": { opacity: 0.4, cursor: "not-allowed" },
+    },
+  },
+});

package/src/ListBox.tsx

@@ -0,0 +1,88 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import {
+  ListBox as RACListBox,
+  ListBoxItem as RACListBoxItem,
+  ListBoxItemProps as RACListBoxItemProps,
+  ListBoxProps as RACListBoxProps,
+} from "react-aria-components";
+import { css, cx } from "styled-system/css";
+import { listBox } from "styled-system/recipes";
+import { SystemStyleObject } from "styled-system/types";
+
+export interface ListBoxProps<T extends object>
+  extends Omit<RACListBoxProps<T>, "className" | "style" | "children"> {
+  /** `ListBoxOption`s, or a render function when `items` is given. */
+  children: RACListBoxProps<T>["children"];
+  /** Per-instance style overrides for the list, merged after the recipe. */
+  css?: SystemStyleObject;
+  className?: string;
+}
+
+/**
+ * ListBox — react-aria-components' <ListBox>, standing on the page rather
+ * than inside a dropdown (that is `Select`/`ComboBox`, which share their own
+ * recipe).
+ *
+ * Options are leaves: a button inside one is unreachable by keyboard, so rows
+ * carrying their own controls want `GridList`.
+ */
+export const ListBox = <T extends object>({
+  css: cssProp,
+  className,
+  children,
+  ...rest
+}: ListBoxProps<T>) => {
+  const slots = listBox();
+  return (
+    <RACListBox
+      {...rest}
+      className={cx(slots.root, cssProp ? css(cssProp) : undefined, className)}
+    >
+      {children}
+    </RACListBox>
+  );
+};
+
+export interface ListBoxOptionProps<T extends object = object>
+  extends Omit<RACListBoxItemProps<T>, "className" | "style" | "children"> {
+  /**
+   * The option's content. A function receives the option's state, for a row
+   * that draws its own selected marker rather than taking the recipe's
+   * background.
+   */
+  children?: RACListBoxItemProps<T>["children"];
+  /** Per-instance style overrides for the option, merged after the recipe. */
+  css?: SystemStyleObject;
+  className?: string;
+}
+
+/**
+ * An option in a `ListBox`.
+ *
+ * Give it a `textValue` where its children aren't a plain string: react-aria
+ * derives typeahead text from string children only.
+ */
+export const ListBoxOption = <T extends object = object>({
+  css: cssProp,
+  className,
+  children,
+  ...rest
+}: ListBoxOptionProps<T>) => {
+  const slots = listBox();
+  return (
+    <RACListBoxItem
+      {...rest}
+      className={cx(
+        slots.option,
+        cssProp ? css(cssProp) : undefined,
+        className,
+      )}
+    >
+      {children}
+    </RACListBoxItem>
+  );
+};

package/src/Menu.recipe.ts

@@ -35,7 +35,12 @@ export const menu = defineSlotRecipe({
       color: "inherit",
       minWidth: "3xs",
       py: "2",
-      zIndex: "dropdown",
+      // `popover` (1500), not `dropdown` (1000): a RAC Popover always portals
+      // to the body, so a menu opened from inside a Modal (zIndex `modal`,
+      // 1400) escapes the modal's stacking context and would paint behind it.
+      // Chakra never hit this — its MenuList rendered inline unless explicitly
+      // portalled. Nothing else lives between 1400 and the toast/tooltip layer.
+      zIndex: "popover",
       borderRadius: "md",
       borderWidth: "1px",
       borderColor: "gray.200",