@microbit/ui 0.1.0-alpha.10

package/src/LinkButton.tsx

@@ -0,0 +1,80 @@
+/**
+ * (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, matching Chakra's `leftIcon`. */
+  leftIcon?: ReactNode;
+  /** Icon rendered after the label, matching Chakra's `rightIcon`. */
+  rightIcon?: 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 (Chakra's
+ * `Button as="a"`). 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,
+      css: cssProp,
+      className,
+      leftIcon,
+      rightIcon,
+      children,
+      ...rest
+    },
+    ref,
+  ) {
+    return (
+      <RACLink
+        ref={ref}
+        className={cx(
+          button({ variant, size }),
+          css(linkReset, cssProp),
+          className,
+        )}
+        {...rest}
+      >
+        {leftIcon ? (
+          <span className={buttonIcon({ side: "left" })}>{leftIcon}</span>
+        ) : null}
+        {children}
+        {rightIcon ? (
+          <span className={buttonIcon({ side: "right" })}>{rightIcon}</span>
+        ) : null}
+      </RACLink>
+    );
+  },
+);

package/src/List.tsx

@@ -0,0 +1,31 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+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).
+ */
+export const List = styled("ul", {
+  base: { listStyleType: "none" },
+});
+
+/** List item, matching Chakra's <ListItem>. */
+export const ListItem = styled("li", {
+  base: {},
+});
+
+/** Bulleted list matching Chakra's <UnorderedList>. */
+export const UnorderedList = styled("ul", {
+  base: { listStyleType: "disc", marginStart: "1em" },
+});
+
+/** Numbered list matching Chakra's <OrderedList>. */
+export const OrderedList = styled("ol", {
+  base: { listStyleType: "decimal", marginStart: "1em" },
+});

package/src/Menu.recipe.ts

@@ -0,0 +1,119 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+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.
+ *
+ * A config slot recipe (rather than an atomic `sva`) for consistency with
+ * `dialog` and so presets can override it later if brands diverge.
+ * No variants, so it needs no `staticCss` entry.
+ *
+ * Registered in the base preset (base-preset.ts).
+ */
+export const menu = defineSlotRecipe({
+  className: "menu",
+  slots: [
+    "content",
+    "list",
+    "item",
+    "icon",
+    "label",
+    "divider",
+    "group",
+    "groupTitle",
+    "itemIndicator",
+  ],
+  base: {
+    content: {
+      bg: "white",
+      color: "inherit",
+      minWidth: "3xs",
+      py: "2",
+      zIndex: "dropdown",
+      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.
+      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",
+    },
+    item: {
+      display: "flex",
+      alignItems: "center",
+      py: "1.5",
+      px: "3",
+      cursor: "pointer",
+      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]": { bg: "gray.100" },
+      "&[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.
+      flex: "1",
+    },
+    icon: {
+      display: "inline-flex",
+      alignItems: "center",
+      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.
+      fontSize: "0.8em",
+    },
+    divider: {
+      border: 0,
+      borderBottom: "1px solid",
+      borderColor: "gray.200",
+      my: "2",
+      opacity: 0.6,
+    },
+    group: {},
+    // Chakra's MenuGroup/MenuOptionGroup title.
+    groupTitle: {
+      display: "block",
+      mx: "4",
+      my: "2",
+      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).
+    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

@@ -0,0 +1,261 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+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 {
+  /** 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 MenuOptionGroupProps {
+  /** 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;
+}
+
+/**
+ * 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.
+ */
+export const MenuOptionGroup = ({
+  title,
+  value,
+  onChange,
+  children,
+  css: cssProp,
+  className,
+}: MenuOptionGroupProps) => {
+  const slots = menu();
+  return (
+    <RACMenuSection
+      className={cx(slots.group, cssProp ? css(cssProp) : undefined, className)}
+      selectionMode="single"
+      selectedKeys={value != null ? [value] : []}
+      onSelectionChange={(keys) => {
+        if (keys !== "all") {
+          const key = keys.values().next().value;
+          if (key != null) {
+            onChange?.(String(key));
+          }
+        }
+      }}
+    >
+      {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 (Chakra's MenuItemOption).
+ */
+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;
+}
+
+/** 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" },
+});