@microbit/ui 0.1.0-alpha.3 → 0.1.0-alpha.31

package/src/InputGroup.tsx

@@ -7,8 +7,8 @@ import { styled } from "styled-system/jsx";
 
 /**
  * InputGroup — relative wrapper for an Input with addon elements. Pad the
- * input (`pl`/`pr`) to make room for the elements. Replaces Chakra's
- * InputGroup.
+ * input (`ps`/`pe`) to make room for the elements; the elements sit on the
+ * reading-order sides, so physical padding lands opposite them in RTL.
  */
 export const InputGroup = styled("div", {
   base: { position: "relative", width: "100%", display: "flex" },
@@ -16,33 +16,47 @@ export const InputGroup = styled("div", {
 
 // The element styles are written out twice rather than shared via a spread:
 // Panda's extractor only reliably evaluates inline literals.
+// The size variants are square boxes matching the input recipe's height per
+// size; pass the same `size` as the grouped Input.
 
-/** Element overlaying the start of an InputGroup (Chakra InputLeftElement). */
-export const InputLeftElement = styled("div", {
+/** Element overlaying the start of an InputGroup. */
+export const InputStartElement = styled("div", {
   base: {
     position: "absolute",
     top: 0,
-    left: 0,
-    width: "10",
-    height: "10",
+    insetStart: 0,
     display: "flex",
     alignItems: "center",
     justifyContent: "center",
     zIndex: 2,
   },
+  variants: {
+    size: {
+      lg: { width: "12", height: "12" },
+      md: { width: "10", height: "10" },
+      sm: { width: "8", height: "8" },
+    },
+  },
+  defaultVariants: { size: "md" },
 });
 
-/** Element overlaying the end of an InputGroup (Chakra InputRightElement). */
-export const InputRightElement = styled("div", {
+/** Element overlaying the end of an InputGroup. */
+export const InputEndElement = styled("div", {
   base: {
     position: "absolute",
     top: 0,
-    right: 0,
-    width: "10",
-    height: "10",
+    insetEnd: 0,
     display: "flex",
     alignItems: "center",
     justifyContent: "center",
     zIndex: 2,
   },
+  variants: {
+    size: {
+      lg: { width: "12", height: "12" },
+      md: { width: "10", height: "10" },
+      sm: { width: "8", height: "8" },
+    },
+  },
+  defaultVariants: { size: "md" },
 });

package/src/Kbd.tsx

@@ -0,0 +1,26 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import { styled } from "styled-system/jsx";
+
+/**
+ * Kbd — a keyboard-key chip (light mode).
+ */
+export const Kbd = styled("kbd", {
+  base: {
+    bg: "gray.100",
+    borderRadius: "md",
+    borderWidth: "1px",
+    borderStyle: "solid",
+    borderColor: "gray.200",
+    borderBottomWidth: "3px",
+    fontFamily: "mono",
+    fontSize: "0.8em",
+    fontWeight: "bold",
+    lineHeight: "normal",
+    px: "0.4em",
+    whiteSpace: "nowrap",
+  },
+});

package/src/Link.tsx

@@ -6,8 +6,8 @@
 import { styled } from "styled-system/jsx";
 
 /**
- * Link — anchor styled to match Chakra's <Link> base (no underline until hover,
- * focus ring on keyboard focus). Accepts Panda style props for colour etc.
+ * Link — a styled anchor (no underline until hover, focus ring on keyboard
+ * focus). Accepts Panda style props for colour etc.
  */
 export const Link = styled("a", {
   base: {
@@ -18,6 +18,6 @@ export const Link = styled("a", {
       "background-color, border-color, color, fill, stroke, opacity, box-shadow, transform",
     transitionDuration: "normal",
     _hover: { textDecoration: "underline" },
-    _focusVisible: { focusShadow: "outline" },
+    _focusVisible: { focusRing: "outline" },
   },
 });

package/src/LinkBox.tsx

@@ -12,7 +12,7 @@ import { SystemStyleObject } from "styled-system/types";
 /**
  * LinkBox — makes a whole box clickable via a nested LinkOverlay (or any
  * element with an inset `_before` overlay). Other interactive children must
- * be raised with `zIndex: 1`. Replaces Chakra's <LinkBox>.
+ * be raised with `zIndex: 1`.
  */
 export const LinkBox = styled("div", {
   base: { position: "relative" },
@@ -54,8 +54,7 @@ export interface LinkOverlayButtonProps
  * Deliberately a plain button, not a react-aria one: react-aria's usePress
  * cancels presses that land outside the button's bounding rect, which defeats
  * the overlay. `position: static` overrides the button recipe's base so the
- * overlay anchors to the LinkBox (Chakra's LinkOverlay did the same over its
- * Button).
+ * overlay anchors to the LinkBox.
  */
 export const LinkOverlayButton = forwardRef<
   HTMLButtonElement,

package/src/LinkButton.tsx

@@ -0,0 +1,81 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import { forwardRef, ReactNode } from "react";
+import {
+  Link as RACLink,
+  LinkProps as RACLinkProps,
+} from "react-aria-components";
+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";
+
+export interface LinkButtonProps
+  extends Omit<RACLinkProps, "className" | "children">,
+    ButtonVariantProps {
+  /** Per-instance style overrides, merged after the recipe. */
+  css?: SystemStyleObject;
+  className?: string;
+  /** Icon rendered before the label. */
+  startIcon?: ReactNode;
+  /** Icon rendered after the label. */
+  endIcon?: ReactNode;
+  children?: ReactNode;
+}
+
+// Anchors pick up underline styling that buttons never have.
+const linkReset = css.raw({
+  textDecoration: "none",
+  _hover: { textDecoration: "none" },
+});
+
+/**
+ * LinkButton — a navigation link that looks like a Button.
+ * react-aria-components <Link> renders a real anchor
+ * (`href`, `target`, new-tab/middle-click semantics preserved) with the same
+ * interaction data attributes as Button, so the `button` recipe's
+ * hover/press/focus/disabled states apply unchanged.
+ *
+ * Use for navigation that should read as a call to action (e.g. an external
+ * help page presented as a dialog's primary action); use Button for
+ * in-page actions.
+ */
+export const LinkButton = forwardRef<HTMLAnchorElement, LinkButtonProps>(
+  function LinkButton(
+    {
+      variant,
+      size,
+      tone,
+      css: cssProp,
+      className,
+      startIcon,
+      endIcon,
+      children,
+      ...rest
+    },
+    ref,
+  ) {
+    return (
+      <RACLink
+        ref={ref}
+        className={cx(
+          button({ variant, size, tone }),
+          css(linkReset, cssProp),
+          className,
+        )}
+        {...rest}
+      >
+        {startIcon ? (
+          <span className={buttonIcon({ side: "start" })}>{startIcon}</span>
+        ) : null}
+        {children}
+        {endIcon ? (
+          <span className={buttonIcon({ side: "end" })}>{endIcon}</span>
+        ) : null}
+      </RACLink>
+    );
+  },
+);

package/src/List.tsx

@@ -6,22 +6,24 @@
 import { styled } from "styled-system/jsx";
 
 /**
- * Unstyled list, matching Chakra's <List> (Panda's preflight already zeroes
- * margins/padding and removes list markers).
+ * Unstyled list. The marker removal is explicit rather than relying on a
+ * reset.
  */
-export const List = styled("ul");
+export const List = styled("ul", {
+  base: { listStyleType: "none" },
+});
 
-/** List item, matching Chakra's <ListItem>. */
+/** List item. */
 export const ListItem = styled("li", {
   base: {},
 });
 
-/** Bulleted list matching Chakra's <UnorderedList>. */
+/** Bulleted list. */
 export const UnorderedList = styled("ul", {
   base: { listStyleType: "disc", marginStart: "1em" },
 });
 
-/** Numbered list matching Chakra's <OrderedList>. */
+/** Numbered list. */
 export const OrderedList = styled("ol", {
   base: { listStyleType: "decimal", marginStart: "1em" },
 });

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]": { focusRing: "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

@@ -6,9 +6,9 @@
 import { defineSlotRecipe } from "@pandacss/dev";
 
 /**
- * Menu slot recipe — Chakra's default Menu parts (light mode). `content` is the
- * dropdown card (react-aria-components' Popover), `list` the RAC Menu, `item` a
- * MenuItem, `icon` the leading-icon wrapper.
+ * Menu slot recipe. `content` is the dropdown card (react-aria-components'
+ * Popover), `list` the RAC Menu, `item` a MenuItem, `icon` the leading-icon
+ * wrapper.
  *
  * A config slot recipe (rather than an atomic `sva`) for consistency with
  * `dialog` and so presets can override it later if brands diverge.
@@ -18,20 +18,34 @@ import { defineSlotRecipe } from "@pandacss/dev";
  */
 export const menu = defineSlotRecipe({
   className: "menu",
-  slots: ["content", "list", "item", "icon", "label", "divider"],
+  slots: [
+    "content",
+    "list",
+    "item",
+    "icon",
+    "label",
+    "divider",
+    "group",
+    "groupTitle",
+    "itemIndicator",
+  ],
   base: {
     content: {
       bg: "white",
       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.
+      // Nothing else lives between 1400 and the toast/tooltip layer.
+      zIndex: "popover",
       borderRadius: "md",
       borderWidth: "1px",
       borderColor: "gray.200",
       boxShadow: "sm",
-      // Approximate Chakra's menu fade/scale. RAC toggles data-entering/
-      // data-exiting on the Popover and waits for the transition before unmount.
+      // Fade/scale enter/exit. RAC toggles data-entering/data-exiting on the
+      // Popover and waits for the transition before unmount.
       transformOrigin: "top",
       opacity: 1,
       transform: "scale(1)",
@@ -52,19 +66,18 @@ export const menu = defineSlotRecipe({
       color: "inherit",
       textDecoration: "none",
       outline: "none",
-      transitionProperty: "background",
-      transitionDuration: "ultra-fast",
-      transitionTimingFunction: "ease-in",
-      // RAC highlights the active item (keyboard or pointer) with data-focused;
-      // data-pressed is the pressed state — mirrors Chakra's _focus/_active.
+      // data-focused is RAC's active item, either modality. The highlight
+      // is focus indication: no transition (it snaps with the ring, which
+      // keyboard nav adds; inset, the rows being full-bleed).
       "&[data-focused]": { bg: "gray.100" },
+      "&[data-focus-visible]": { focusRing: "outlineInset" },
       "&[data-pressed]": { bg: "gray.200" },
       "&[data-disabled]": { opacity: 0.4, cursor: "not-allowed" },
     },
     label: {
-      // Chakra wraps an icon-item's children in a flex:1 span, so block
-      // children (e.g. two stacked <Text>s) lay out vertically rather than as
-      // flex-row siblings of the icon.
+      // A flex:1 wrapper around an icon-item's children, so block children
+      // (e.g. two stacked <Text>s) lay out vertically rather than as flex-row
+      // siblings of the icon.
       flex: "1",
     },
     icon: {
@@ -73,8 +86,8 @@ export const menu = defineSlotRecipe({
       justifyContent: "center",
       flexShrink: 0,
       marginEnd: "0.75rem",
-      // Chakra's MenuIcon shrinks glyphs to 0.8em; items passing an explicitly
-      // sized icon (e.g. h/w) override this.
+      // Glyphs shrink to 0.8em; items passing an explicitly sized icon
+      // (e.g. h/w) override this.
       fontSize: "0.8em",
     },
     divider: {
@@ -84,5 +97,26 @@ export const menu = defineSlotRecipe({
       my: "2",
       opacity: 0.6,
     },
+    group: {},
+    // Title for a menu group or option group.
+    groupTitle: {
+      display: "block",
+      mx: "4",
+      my: "2",
+      fontWeight: "semibold",
+      fontSize: "sm",
+    },
+    // Check glyph slot for MenuItemOption: space always reserved, visible
+    // only on the selected item (RAC sets data-selected on it).
+    itemIndicator: {
+      display: "inline-flex",
+      alignItems: "center",
+      justifyContent: "center",
+      flexShrink: 0,
+      marginEnd: "0.75rem",
+      fontSize: "0.8em",
+      opacity: 0,
+      "[data-selected] &": { opacity: 1 },
+    },
   },
 });

package/src/Menu.tsx

@@ -5,17 +5,21 @@
  */
 import { ReactNode, useCallback, useState } from "react";
 import {
+  Header as RACHeader,
   Menu as RACMenu,
   MenuItem as RACMenuItem,
   MenuItemProps as RACMenuItemProps,
+  MenuSection as RACMenuSection,
   MenuTrigger as RACMenuTrigger,
   Popover,
   PopoverProps,
   Separator,
 } from "react-aria-components";
+import { RiCheckLine } from "react-icons/ri";
 import { css, cx } from "styled-system/css";
 import { menu } from "styled-system/recipes";
 import { SystemStyleObject } from "styled-system/types";
+import { Icon } from "./Icon";
 import { useOverlayCloseRegistrar } from "./SharedUIProvider";
 
 export interface MenuTriggerProps {
@@ -93,7 +97,6 @@ export interface MenuListProps {
  */
 export const MenuList = ({
   children,
-  // Matches Chakra Menu's default "bottom-start".
   placement = "bottom start",
   css: cssProp,
   className,
@@ -115,7 +118,7 @@ export const MenuList = ({
 
 export interface MenuItemProps
   extends Omit<RACMenuItemProps, "className" | "children"> {
-  /** Icon rendered before the label, matching Chakra's MenuItem `icon`. */
+  /** Icon rendered before the label. */
   icon?: ReactNode;
   /** Per-instance style overrides, merged after the recipe. */
   css?: SystemStyleObject;
@@ -152,6 +155,118 @@ export const MenuItem = ({
   );
 };
 
+interface MenuOptionGroupBaseProps {
+  /** Group heading shown above the options. */
+  title?: ReactNode;
+  /** `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 group of checkable `MenuItemOption`s within a menu.
+ * `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).
+ */
+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={props.type === "checkbox" ? "multiple" : "single"}
+      selectedKeys={selectedKeys}
+      onSelectionChange={(keys) => {
+        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.
+          props.onChange?.(values[0]);
+        }
+      }}
+    >
+      {title != null && (
+        <RACHeader className={slots.groupTitle}>{title}</RACHeader>
+      )}
+      {children}
+    </RACMenuSection>
+  );
+};
+
+export interface MenuItemOptionProps
+  extends Omit<RACMenuItemProps, "className" | "children" | "id" | "value"> {
+  /** This option's value within its `MenuOptionGroup`. */
+  value: string;
+  css?: SystemStyleObject;
+  className?: string;
+  children?: ReactNode;
+}
+
+/**
+ * MenuItemOption — a selectable option inside a `MenuOptionGroup`, with a
+ * check indicator on the selected item.
+ */
+export const MenuItemOption = ({
+  value,
+  css: cssProp,
+  className,
+  children,
+  ...rest
+}: MenuItemOptionProps) => {
+  const slots = menu();
+  return (
+    <RACMenuItem
+      id={value}
+      className={cx(slots.item, cssProp ? css(cssProp) : undefined, className)}
+      {...rest}
+    >
+      <span className={slots.itemIndicator} aria-hidden>
+        <Icon as={RiCheckLine} />
+      </span>
+      <span className={slots.label}>{children}</span>
+    </RACMenuItem>
+  );
+};
+
 export interface MenuDividerProps {
   css?: SystemStyleObject;
   className?: string;