@microbit/ui 0.1.0-alpha.3

package/src/Menu.tsx

@@ -0,0 +1,172 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import { ReactNode, useCallback, useState } from "react";
+import {
+  Menu as RACMenu,
+  MenuItem as RACMenuItem,
+  MenuItemProps as RACMenuItemProps,
+  MenuTrigger as RACMenuTrigger,
+  Popover,
+  PopoverProps,
+  Separator,
+} from "react-aria-components";
+import { css, cx } from "styled-system/css";
+import { menu } from "styled-system/recipes";
+import { SystemStyleObject } from "styled-system/types";
+import { useOverlayCloseRegistrar } from "./SharedUIProvider";
+
+export interface MenuTriggerProps {
+  /** Called when the menu opens. */
+  onOpen?: () => void;
+  /** Called when the menu closes. */
+  onClose?: () => void;
+  /** The trigger element followed by a `MenuList` (react-aria pattern). */
+  children: ReactNode;
+}
+
+/**
+ * MenuTrigger — react-aria-components' <MenuTrigger>. Its first child is the
+ * trigger (e.g. a Button); the second is a `MenuList`. RAC returns focus to the
+ * trigger when the menu closes.
+ *
+ * When the app installs an overlay-close registrar (e.g. so the Android back
+ * button can close the menu), the trigger runs controlled and registers its
+ * close function while open. Otherwise it's an uncontrolled pass-through.
+ */
+export const MenuTrigger = ({
+  onOpen,
+  onClose,
+  children,
+}: MenuTriggerProps) => {
+  const registerClose = useOverlayCloseRegistrar();
+  const [isOpen, setIsOpen] = useState(false);
+
+  const handleOpenChange = useCallback(
+    (open: boolean) => {
+      setIsOpen(open);
+      if (open) {
+        registerClose?.(() => {
+          setIsOpen(false);
+          registerClose(null);
+        });
+        onOpen?.();
+      } else {
+        registerClose?.(null);
+        onClose?.();
+      }
+    },
+    [registerClose, onOpen, onClose],
+  );
+
+  if (!registerClose) {
+    return (
+      <RACMenuTrigger
+        onOpenChange={(open) => (open ? onOpen?.() : onClose?.())}
+      >
+        {children}
+      </RACMenuTrigger>
+    );
+  }
+
+  return (
+    <RACMenuTrigger isOpen={isOpen} onOpenChange={handleOpenChange}>
+      {children}
+    </RACMenuTrigger>
+  );
+};
+
+export interface MenuListProps {
+  children: ReactNode;
+  /** Placement of the dropdown relative to the trigger. */
+  placement?: PopoverProps["placement"];
+  /** Per-instance style overrides, merged after the recipe. */
+  css?: SystemStyleObject;
+  className?: string;
+}
+
+/**
+ * MenuList — the dropdown surface: RAC's <Popover> (positioned card) wrapping a
+ * RAC <Menu> (the list). Place `MenuItem`s inside.
+ */
+export const MenuList = ({
+  children,
+  // Matches Chakra Menu's default "bottom-start".
+  placement = "bottom start",
+  css: cssProp,
+  className,
+}: MenuListProps) => {
+  const slots = menu();
+  return (
+    <Popover
+      placement={placement}
+      className={cx(
+        slots.content,
+        cssProp ? css(cssProp) : undefined,
+        className,
+      )}
+    >
+      <RACMenu className={slots.list}>{children}</RACMenu>
+    </Popover>
+  );
+};
+
+export interface MenuItemProps
+  extends Omit<RACMenuItemProps, "className" | "children"> {
+  /** Icon rendered before the label, matching Chakra's MenuItem `icon`. */
+  icon?: ReactNode;
+  /** Per-instance style overrides, merged after the recipe. */
+  css?: SystemStyleObject;
+  className?: string;
+  children?: ReactNode;
+}
+
+/**
+ * MenuItem — a RAC <MenuItem> styled with the `menu` recipe's `item` slot.
+ * Use `onAction` for the click behaviour (RAC closes the menu automatically).
+ */
+export const MenuItem = ({
+  icon,
+  css: cssProp,
+  className,
+  children,
+  ...rest
+}: MenuItemProps) => {
+  const slots = menu();
+  return (
+    <RACMenuItem
+      className={cx(slots.item, cssProp ? css(cssProp) : undefined, className)}
+      {...rest}
+    >
+      {icon ? (
+        <>
+          <span className={slots.icon}>{icon}</span>
+          <span className={slots.label}>{children}</span>
+        </>
+      ) : (
+        children
+      )}
+    </RACMenuItem>
+  );
+};
+
+export interface MenuDividerProps {
+  css?: SystemStyleObject;
+  className?: string;
+}
+
+/** Horizontal rule separating groups of menu items. */
+export const MenuDivider = ({ css: cssProp, className }: MenuDividerProps) => {
+  const slots = menu();
+  return (
+    <Separator
+      className={cx(
+        slots.divider,
+        cssProp ? css(cssProp) : undefined,
+        className,
+      )}
+    />
+  );
+};

package/src/Modal.recipe.ts

@@ -0,0 +1,163 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+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.
+ *
+ * A config recipe (rather than an atomic `sva`) so the `size` variant accepts
+ * responsive values, e.g. `{ base: "full", md: "4xl" }`. Consumed by the
+ * shared-ui Modal, which maps the slots onto react-aria-components'
+ * ModalOverlay / Modal / Dialog.
+ *
+ * Registered in the base preset (base-preset.ts).
+ */
+// Appearance of a normal (non-full) modal box. Restated by every non-full size
+// variant so that, when `size` is responsive (e.g. { base: "full", md: "4xl" }),
+// the larger breakpoint fully overrides the `full` variant rather than leaking
+// its margin:0 / border-radius:0 / full-height / gradient into desktop. Panda
+// applies the base-breakpoint variant value unconditionally, so symmetric
+// property sets across size values are required.
+const dialogBox = {
+  my: "16",
+  mx: "2",
+  borderRadius: "md",
+  background: "white",
+  minHeight: "auto",
+  padding: "0",
+};
+
+// The `full` variant also styles these slots; same symmetry requirement.
+const dialogSlots = {
+  header: { pl: "6" },
+  body: { overflowY: "visible" },
+  closeTrigger: { top: "2" },
+};
+
+export const dialog = defineSlotRecipe({
+  className: "dialog",
+  slots: [
+    "overlay",
+    "content",
+    "inner",
+    "header",
+    "body",
+    "footer",
+    "closeTrigger",
+  ],
+  base: {
+    overlay: {
+      position: "fixed",
+      inset: 0,
+      w: "100%",
+      h: "100%",
+      bg: "blackAlpha.600",
+      zIndex: "modal",
+      display: "flex",
+      justifyContent: "center",
+      alignItems: "flex-start",
+      overflow: "auto",
+      overscrollBehaviorY: "none",
+      // Fade the backdrop in/out. RAC toggles data-entering/data-exiting and
+      // waits for the transition before unmounting.
+      opacity: 1,
+      transition: "opacity 0.2s ease-out",
+      "&[data-entering]": { opacity: 0 },
+      "&[data-exiting]": { opacity: 0 },
+      _motionReduce: { transition: "none" },
+    },
+    content: {
+      position: "relative",
+      color: "inherit",
+      boxShadow: "lg",
+      width: "100%",
+      display: "flex",
+      flexDirection: "column",
+      outline: "none",
+      // Approximate Chakra's fade + scale enter/exit.
+      opacity: 1,
+      transform: "scale(1)",
+      transition: "opacity 0.2s ease-out, transform 0.2s ease-out",
+      "&[data-entering]": { opacity: 0, transform: "scale(0.95)" },
+      "&[data-exiting]": { opacity: 0, transform: "scale(0.95)" },
+      _motionReduce: { transition: "none" },
+    },
+    inner: {
+      outline: "none",
+      display: "flex",
+      flexDirection: "column",
+      width: "100%",
+      flex: "1 1 auto",
+    },
+    header: {
+      px: "6",
+      py: "4",
+      fontSize: "xl",
+      fontWeight: "semibold",
+      flexShrink: 0,
+    },
+    body: { px: "6", py: "2", flex: "1" },
+    footer: {
+      px: "6",
+      py: "4",
+      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.
+      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.
+    centered: {
+      true: {
+        overlay: { alignItems: "center" },
+      },
+    },
+    size: {
+      xs: { ...dialogSlots, content: { ...dialogBox, maxWidth: "xs" } },
+      sm: { ...dialogSlots, content: { ...dialogBox, maxWidth: "sm" } },
+      md: { ...dialogSlots, content: { ...dialogBox, maxWidth: "md" } },
+      lg: { ...dialogSlots, content: { ...dialogBox, maxWidth: "lg" } },
+      xl: { ...dialogSlots, content: { ...dialogBox, maxWidth: "xl" } },
+      "2xl": { ...dialogSlots, content: { ...dialogBox, maxWidth: "2xl" } },
+      "3xl": { ...dialogSlots, content: { ...dialogBox, maxWidth: "3xl" } },
+      "4xl": { ...dialogSlots, content: { ...dialogBox, maxWidth: "4xl" } },
+      "5xl": { ...dialogSlots, content: { ...dialogBox, maxWidth: "5xl" } },
+      "6xl": { ...dialogSlots, content: { ...dialogBox, maxWidth: "6xl" } },
+      full: {
+        content: {
+          maxWidth: "100vw",
+          minHeight: "100dvh",
+          my: "0",
+          mx: "0",
+          borderRadius: "0",
+          paddingTop: "env(safe-area-inset-top)",
+          paddingBottom: "env(safe-area-inset-bottom)",
+          paddingLeft: "env(safe-area-inset-left)",
+          paddingRight: "env(safe-area-inset-right)",
+          // brand colour in the status-bar area, white below (matches ActionBar)
+          background:
+            "linear-gradient(to bottom, token(colors.statusBarBg) env(safe-area-inset-top), white env(safe-area-inset-top))",
+        },
+        header: {
+          pl: "calc(var(--window-controls-left, 0px) + token(spacing.6))",
+        },
+        body: { flex: "1", overflowY: "auto" },
+        closeTrigger: {
+          top: "calc(env(safe-area-inset-top) + token(spacing.2))",
+        },
+      },
+    },
+  },
+  defaultVariants: { size: "md" },
+});

package/src/Modal.tsx

@@ -0,0 +1,265 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import { createContext, ReactNode, RefObject, useContext } from "react";
+import {
+  Button as RACButton,
+  Dialog,
+  Heading as RACHeading,
+  Modal as RACModal,
+  ModalOverlay,
+} 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 { uiMessage } from "./messages";
+import { UnmountCallback } from "./UnmountCallback";
+
+type DialogSlots = ReturnType<typeof dialog>;
+
+const SlotContext = createContext<{ slots: DialogSlots; onClose: () => void }>({
+  slots: dialog({}),
+  onClose: () => undefined,
+});
+
+const useDialog = () => useContext(SlotContext);
+
+export type ModalSize = ConditionalValue<
+  | "xs"
+  | "sm"
+  | "md"
+  | "lg"
+  | "xl"
+  | "2xl"
+  | "3xl"
+  | "4xl"
+  | "5xl"
+  | "6xl"
+  | "full"
+>;
+
+export interface ModalProps {
+  isOpen: boolean;
+  onClose: () => void;
+  size?: ModalSize;
+  /** Allow closing by clicking the backdrop (default true; Escape always closes). */
+  isDismissable?: boolean;
+  /** Disable the enter/exit transitions (Chakra's motionPreset="none"). */
+  motionless?: boolean;
+  /** Prevent Escape closing the dialog (Chakra's closeOnEsc={false}). */
+  isKeyboardDismissDisabled?: boolean;
+  /** Style overrides for the dialog box (Chakra's ModalContent props). */
+  contentCss?: SystemStyleObject;
+  /**
+   * Style overrides for the backdrop (Chakra's ModalOverlay props), e.g. a
+   * transparent backdrop when something else provides the dimming.
+   */
+  overlayCss?: SystemStyleObject;
+  /**
+   * Use "alertdialog" for confirmations that interrupt the user (Chakra's
+   * AlertDialog).
+   */
+  role?: "dialog" | "alertdialog";
+  /** Vertically centre the dialog (Chakra's `isCentered`). */
+  isCentered?: boolean;
+  /**
+   * Called after the dialog has fully closed (exit transition done and the
+   * dialog removed). Matches Chakra's `onCloseComplete`.
+   */
+  onCloseComplete?: () => void;
+  /**
+   * Element to focus when the dialog closes, instead of the element that was
+   * focused when it opened. Matches Chakra's `finalFocusRef`.
+   */
+  finalFocusRef?: RefObject<HTMLElement>;
+  /**
+   * Accessible name for dialogs without a ModalHeader (which otherwise
+   * provides the label). One of the two is required — react-aria warns in
+   * dev builds when a dialog has neither. An explicit `aria-label` wins
+   * over a ModalHeader.
+   */
+  "aria-label"?: string;
+  children: ReactNode;
+}
+
+/**
+ * Modal — a focus-trapping dialog. Collapses Chakra's
+ * Modal/ModalOverlay/ModalContent into a single shell; place ModalHeader,
+ * ModalBody and ModalFooter inside.
+ */
+export const Modal = ({
+  isOpen,
+  onClose,
+  size,
+  isDismissable = true,
+  motionless,
+  isKeyboardDismissDisabled,
+  contentCss,
+  overlayCss,
+  role,
+  isCentered,
+  onCloseComplete,
+  finalFocusRef,
+  "aria-label": ariaLabel,
+  children,
+}: ModalProps) => {
+  const slots = dialog({ size, centered: isCentered });
+  const motionlessClass = motionless
+    ? css({
+        transition: "none",
+        "&[data-entering]": { opacity: 1, transform: "none" },
+        "&[data-exiting]": { opacity: 1, transform: "none" },
+      })
+    : undefined;
+  const handleUnmount = () => {
+    onCloseComplete?.();
+    const el = finalFocusRef?.current;
+    if (el) {
+      // After RAC's own focus restoration, which also runs on unmount.
+      requestAnimationFrame(() => el.focus());
+    }
+  };
+  return (
+    <ModalOverlay
+      isOpen={isOpen}
+      onOpenChange={(open) => {
+        if (!open) {
+          onClose();
+        }
+      }}
+      isDismissable={isDismissable}
+      isKeyboardDismissDisabled={isKeyboardDismissDisabled}
+      className={cx(
+        slots.overlay,
+        motionlessClass,
+        overlayCss ? css(overlayCss) : undefined,
+      )}
+    >
+      <UnmountCallback callback={handleUnmount} />
+      <RACModal
+        className={cx(
+          slots.content,
+          motionlessClass,
+          contentCss ? css(contentCss) : undefined,
+        )}
+      >
+        <Dialog role={role} aria-label={ariaLabel} className={slots.inner}>
+          <SlotContext.Provider value={{ slots, onClose }}>
+            {children}
+          </SlotContext.Provider>
+        </Dialog>
+      </RACModal>
+    </ModalOverlay>
+  );
+};
+
+interface SlotProps {
+  children?: ReactNode;
+  css?: SystemStyleObject;
+  className?: string;
+}
+
+/** Modal title. Rendered as RAC's labelling heading for the dialog. */
+export const ModalHeader = ({
+  children,
+  css: cssProp,
+  className,
+  level,
+}: SlotProps & {
+  /** Heading element level (default 3, like RAC). */ level?: number;
+}) => {
+  const { slots } = useDialog();
+  return (
+    <RACHeading
+      slot="title"
+      level={level}
+      className={cx(
+        slots.header,
+        cssProp ? css(cssProp) : undefined,
+        className,
+      )}
+    >
+      {children}
+    </RACHeading>
+  );
+};
+
+export const ModalBody = ({ children, css: cssProp, className }: SlotProps) => {
+  const { slots } = useDialog();
+  return (
+    <div
+      className={cx(slots.body, cssProp ? css(cssProp) : undefined, className)}
+    >
+      {children}
+    </div>
+  );
+};
+
+export const ModalFooter = ({
+  children,
+  css: cssProp,
+  className,
+}: SlotProps) => {
+  const { slots } = useDialog();
+  return (
+    <div
+      className={cx(
+        slots.footer,
+        cssProp ? css(cssProp) : undefined,
+        className,
+      )}
+    >
+      {children}
+    </div>
+  );
+};
+
+export interface ModalCloseButtonProps {
+  /** Accessible name; defaults to the localized close label. */
+  "aria-label"?: string;
+}
+
+/**
+ * ModalCloseButton — the X in the dialog's top corner (Chakra's
+ * ModalCloseButton at its default md size). Closes via the Modal's onClose.
+ */
+export const ModalCloseButton = ({
+  "aria-label": ariaLabel,
+}: ModalCloseButtonProps) => {
+  const intl = useIntl();
+  const { slots, onClose } = useDialog();
+  return (
+    <RACButton
+      aria-label={ariaLabel ?? intl.formatMessage(uiMessage("ui.close-action"))}
+      onPress={onClose}
+      className={cx(
+        slots.closeTrigger,
+        css({
+          display: "inline-flex",
+          alignItems: "center",
+          justifyContent: "center",
+          width: "8",
+          height: "8",
+          fontSize: "xs",
+          borderRadius: "md",
+          cursor: "pointer",
+          bg: "transparent",
+          border: "none",
+          color: "inherit",
+          outline: "none",
+          transitionProperty: "background-color, box-shadow",
+          transitionDuration: "normal",
+          _hover: { bg: "blackAlpha.100" },
+          _active: { bg: "blackAlpha.200" },
+          _focusVisible: { focusShadow: "outline" },
+        }),
+      )}
+    >
+      <CloseIcon />
+    </RACButton>
+  );
+};

package/src/NativeSelect.tsx

@@ -0,0 +1,76 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import { forwardRef, SelectHTMLAttributes } from "react";
+import { css, cx } from "styled-system/css";
+import { input } from "styled-system/recipes";
+import { SystemStyleObject } from "styled-system/types";
+
+export interface NativeSelectProps
+  extends Omit<SelectHTMLAttributes<HTMLSelectElement>, "className"> {
+  /**
+   * Suppress the dropdown chevron, e.g. when an adjacent control provides the
+   * affordance. Without the chevron a bare <select> element is rendered (no
+   * wrapper), so it can participate directly in e.g. an attached ButtonGroup.
+   */
+  hideChevron?: boolean;
+  /** Per-instance style overrides, merged after the recipe. */
+  css?: SystemStyleObject;
+  className?: string;
+}
+
+/**
+ * NativeSelect — a native select styled like Chakra's Select field (md,
+ * outline). The recipe's `appearance: none` removes the platform chevron, so
+ * one is drawn back in by default (Chakra Select's glyph, `currentColor`).
+ */
+export const NativeSelect = forwardRef<HTMLSelectElement, NativeSelectProps>(
+  function NativeSelect(
+    { hideChevron = false, css: cssProp, className, ...rest },
+    ref,
+  ) {
+    const select = (
+      <select
+        ref={ref}
+        className={cx(
+          input(),
+          css(
+            { cursor: "pointer" },
+            // Room for the chevron overlay.
+            hideChevron ? undefined : { paddingRight: "8" },
+            cssProp,
+          ),
+          className,
+        )}
+        {...rest}
+      />
+    );
+    if (hideChevron) {
+      return select;
+    }
+    return (
+      <span className={css({ position: "relative", display: "inline-flex" })}>
+        {select}
+        {/* Chakra Select's chevron. */}
+        <svg
+          viewBox="0 0 24 24"
+          aria-hidden
+          className={css({
+            position: "absolute",
+            right: "2",
+            top: "50%",
+            transform: "translateY(-50%)",
+            width: "5",
+            height: "5",
+            pointerEvents: "none",
+            fill: "currentColor",
+          })}
+        >
+          <path d="M16.59 8.59 12 13.17 7.41 8.59 6 10l6 6 6-6z" />
+        </svg>
+      </span>
+    );
+  },
+);