@microbit/ui 0.1.0-alpha.9 → 0.1.0

package/src/Kbd.tsx

@@ -6,7 +6,7 @@
 import { styled } from "styled-system/jsx";
 
 /**
- * Kbd — keyboard-key chip matching Chakra's <Kbd> (light mode).
+ * Kbd — a keyboard-key chip (light mode).
  */
 export const Kbd = styled("kbd", {
   base: {

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

@@ -19,10 +19,10 @@ export interface LinkButtonProps
   /** Per-instance style overrides, merged after the recipe. */
   css?: SystemStyleObject;
   className?: string;
-  /** Icon rendered before the label, matching Chakra's `leftIcon`. */
-  leftIcon?: ReactNode;
-  /** Icon rendered after the label, matching Chakra's `rightIcon`. */
-  rightIcon?: ReactNode;
+  /** Icon rendered before the label. */
+  startIcon?: ReactNode;
+  /** Icon rendered after the label. */
+  endIcon?: ReactNode;
   children?: ReactNode;
 }
 
@@ -33,8 +33,8 @@ const linkReset = css.raw({
 });
 
 /**
- * LinkButton — a navigation link that looks like a Button (Chakra's
- * `Button as="a"`). react-aria-components <Link> renders a real anchor
+ * 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.
@@ -48,10 +48,11 @@ export const LinkButton = forwardRef<HTMLAnchorElement, LinkButtonProps>(
     {
       variant,
       size,
+      tone,
       css: cssProp,
       className,
-      leftIcon,
-      rightIcon,
+      startIcon,
+      endIcon,
       children,
       ...rest
     },
@@ -61,18 +62,18 @@ export const LinkButton = forwardRef<HTMLAnchorElement, LinkButtonProps>(
       <RACLink
         ref={ref}
         className={cx(
-          button({ variant, size }),
+          button({ variant, size, tone }),
           css(linkReset, cssProp),
           className,
         )}
         {...rest}
       >
-        {leftIcon ? (
-          <span className={buttonIcon({ side: "left" })}>{leftIcon}</span>
+        {startIcon ? (
+          <span className={buttonIcon({ side: "start" })}>{startIcon}</span>
         ) : null}
         {children}
-        {rightIcon ? (
-          <span className={buttonIcon({ side: "right" })}>{rightIcon}</span>
+        {endIcon ? (
+          <span className={buttonIcon({ side: "end" })}>{endIcon}</span>
         ) : null}
       </RACLink>
     );

package/src/List.tsx

@@ -6,26 +6,24 @@
 import { styled } from "styled-system/jsx";
 
 /**
- * Unstyled list, matching Chakra's <List>. The marker removal is explicit —
- * Chakra's List set listStyleType itself, and coexisting apps run without
- * Panda's preflight (margins/padding are zeroed by whichever reset is
- * active).
+ * Unstyled list. The marker removal is explicit rather than relying on a
+ * reset.
  */
 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.
@@ -35,13 +35,17 @@ 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.
+      // 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)",
@@ -62,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: {
@@ -83,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: {
@@ -95,7 +98,7 @@ export const menu = defineSlotRecipe({
       opacity: 0.6,
     },
     group: {},
-    // Chakra's MenuGroup/MenuOptionGroup title.
+    // Title for a menu group or option group.
     groupTitle: {
       display: "block",
       mx: "4",
@@ -103,8 +106,8 @@ export const menu = defineSlotRecipe({
       fontWeight: "semibold",
       fontSize: "sm",
     },
-    // Check glyph slot for MenuItemOption: space always reserved (as Chakra
-    // does), visible only on the selected item (RAC sets data-selected on it).
+    // 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",

package/src/Menu.tsx

@@ -97,7 +97,6 @@ export interface MenuListProps {
  */
 export const MenuList = ({
   children,
-  // Matches Chakra Menu's default "bottom-start".
   placement = "bottom start",
   css: cssProp,
   className,
@@ -119,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;
@@ -156,45 +155,72 @@ export const MenuItem = ({
   );
 };
 
-export interface MenuOptionGroupProps {
-  /** Group heading shown above the options (Chakra's `title`). */
+interface MenuOptionGroupBaseProps {
+  /** Group heading shown above the options. */
   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.
+ * `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 = ({
-  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.
+          props.onChange?.(values[0]);
         }
       }}
     >
@@ -217,7 +243,7 @@ export interface MenuItemOptionProps
 
 /**
  * MenuItemOption — a selectable option inside a `MenuOptionGroup`, with a
- * check indicator on the selected item (Chakra's MenuItemOption).
+ * check indicator on the selected item.
  */
 export const MenuItemOption = ({
   value,

package/src/Modal.recipe.ts

@@ -6,9 +6,9 @@
 import { defineSlotRecipe } from "@pandacss/dev";
 
 /**
- * Dialog slot recipe — Chakra's default Modal parts (light mode), plus this
- * app's overrides: a full-viewport overlay (the iOS WKWebView 100% fix) and a
- * `full` size with safe-area insets and the brand status-bar gradient.
+ * Dialog slot recipe. The overlay spans the full viewport (the iOS WKWebView
+ * 100% fix) and the `full` size adds safe-area insets and the brand
+ * status-bar gradient.
  *
  * A config recipe (rather than an atomic `sva`) so the `size` variant accepts
  * responsive values, e.g. `{ base: "full", md: "4xl" }`. Consumed by the
@@ -33,6 +33,9 @@ const dialogBox = {
 };
 
 // The `full` variant also styles these slots; same symmetry requirement.
+// The header's padding stays physical to pair with that variant's
+// window-controls inset, which is a screen position rather than a
+// reading-order one; the base `px` covers the start side either way.
 const dialogSlots = {
   header: { pl: "6" },
   body: { overflowY: "visible" },
@@ -54,7 +57,13 @@ export const dialog = defineSlotRecipe({
     overlay: {
       position: "fixed",
       inset: 0,
-      w: "100%",
+      // 100vw, not 100%: react-aria's scroll lock reserves the root
+      // scrollbar gutter (scrollbar-gutter: stable), which narrows the
+      // containing block for fixed elements — 100% leaves an uncovered
+      // strip where the page scrollbar was. Viewport units span the
+      // reserved gutter, so the backdrop (and a full-size dialog) reach
+      // the real viewport edge.
+      w: "100vw",
       h: "100%",
       bg: "blackAlpha.600",
       zIndex: "modal",
@@ -79,7 +88,7 @@ export const dialog = defineSlotRecipe({
       display: "flex",
       flexDirection: "column",
       outline: "none",
-      // Approximate Chakra's fade + scale enter/exit.
+      // Fade + scale enter/exit.
       opacity: 1,
       transform: "scale(1)",
       transition: "opacity 0.2s ease-out, transform 0.2s ease-out",
@@ -108,16 +117,15 @@ export const dialog = defineSlotRecipe({
       display: "flex",
       alignItems: "center",
       justifyContent: "flex-end",
-      // Chakra had no footer gap (call sites wrapped buttons in HStacks);
-      // baked in as the house style. Override via css for tighter layouts.
+      // The gap is house style; override via css for tighter layouts.
       gap: "5",
       flexShrink: 0,
     },
     closeTrigger: { position: "absolute", top: "2", insetEnd: "3" },
   },
   variants: {
-    // Chakra's `isCentered`: vertically centre the dialog in the viewport
-    // rather than the default top alignment.
+    // Vertically centre the dialog in the viewport rather than the default
+    // top alignment.
     centered: {
       true: {
         overlay: { alignItems: "center" },