@microbit/ui 0.1.0-alpha.3

package/src/Drawer.tsx

@@ -0,0 +1,138 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import { createContext, ReactNode, useContext } from "react";
+import {
+  Dialog,
+  Heading as RACHeading,
+  Modal as RACModal,
+  ModalOverlay,
+} from "react-aria-components";
+import { css, cx } from "styled-system/css";
+import { drawer, DrawerVariantProps } from "styled-system/recipes";
+import { SystemStyleObject } from "styled-system/types";
+import { UnmountCallback } from "./UnmountCallback";
+
+type DrawerSlots = ReturnType<typeof drawer>;
+
+const SlotContext = createContext<DrawerSlots>(drawer({}));
+
+export interface DrawerProps extends DrawerVariantProps {
+  isOpen: boolean;
+  onClose: () => void;
+  /**
+   * Called after the drawer has fully closed (exit transition done and the
+   * drawer removed). Matches Chakra's `onCloseComplete`.
+   */
+  onCloseComplete?: () => void;
+  /** Allow closing by clicking the backdrop / pressing Escape (default true). */
+  isDismissable?: boolean;
+  /**
+   * Accessible name for the dialog. Required unless the drawer contains a
+   * `DrawerTitle`, which then labels it (react-aria warns in dev builds when
+   * neither is present). An explicit `aria-label` wins over a `DrawerTitle`.
+   */
+  "aria-label"?: string;
+  children: ReactNode;
+}
+
+/**
+ * Drawer — a focus-trapping panel that slides in from the side. Collapses
+ * Chakra's Drawer/DrawerOverlay/DrawerContent into a single shell; place
+ * DrawerHeader and DrawerBody inside.
+ */
+export const Drawer = ({
+  isOpen,
+  onClose,
+  onCloseComplete,
+  placement,
+  isDismissable = true,
+  "aria-label": ariaLabel,
+  children,
+}: DrawerProps) => {
+  const slots = drawer({ placement });
+  return (
+    <ModalOverlay
+      isOpen={isOpen}
+      onOpenChange={(open) => {
+        if (!open) {
+          onClose();
+        }
+      }}
+      isDismissable={isDismissable}
+      className={slots.overlay}
+    >
+      <UnmountCallback callback={onCloseComplete} />
+      <RACModal className={slots.content}>
+        <Dialog aria-label={ariaLabel} className={slots.inner}>
+          <SlotContext.Provider value={slots}>{children}</SlotContext.Provider>
+        </Dialog>
+      </RACModal>
+    </ModalOverlay>
+  );
+};
+
+interface SlotProps {
+  children: ReactNode;
+  css?: SystemStyleObject;
+  className?: string;
+}
+
+export const DrawerHeader = ({
+  children,
+  css: cssProp,
+  className,
+}: SlotProps) => {
+  const slots = useContext(SlotContext);
+  return (
+    <div
+      className={cx(
+        slots.header,
+        cssProp ? css(cssProp) : undefined,
+        className,
+      )}
+    >
+      {children}
+    </div>
+  );
+};
+
+/**
+ * DrawerTitle — a heading that labels the drawer dialog (react-aria's title
+ * slot). Use inside DrawerHeader when the drawer has a visible text title;
+ * DrawerHeader itself stays a layout element so it can hold non-heading
+ * content (logos, close buttons).
+ */
+export const DrawerTitle = ({
+  children,
+  css: cssProp,
+  className,
+  level,
+}: SlotProps & {
+  /** Heading element level (default 2, like react-aria). */ level?: number;
+}) => (
+  <RACHeading
+    slot="title"
+    level={level}
+    className={cssProp || className ? cx(css(cssProp), className) : undefined}
+  >
+    {children}
+  </RACHeading>
+);
+
+export const DrawerBody = ({
+  children,
+  css: cssProp,
+  className,
+}: SlotProps) => {
+  const slots = useContext(SlotContext);
+  return (
+    <div
+      className={cx(slots.body, cssProp ? css(cssProp) : undefined, className)}
+    >
+      {children}
+    </div>
+  );
+};

package/src/Heading.recipe.ts

@@ -0,0 +1,52 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import { defineRecipe } from "@pandacss/dev";
+
+/**
+ * Heading recipe — Chakra's default Heading base + responsive sizes.
+ * A config recipe for the same reasons as `button` (see Button.recipe.ts);
+ * the `marketing` variant is token-driven via the `display` font, so brands
+ * only override tokens.
+ *
+ * Registered in the base preset (base-preset.ts).
+ */
+export const heading = defineRecipe({
+  className: "heading",
+  jsx: ["Heading"],
+  base: {
+    fontFamily: "heading",
+    fontWeight: "bold",
+  },
+  variants: {
+    size: {
+      "4xl": { fontSize: { base: "6xl", md: "7xl" }, lineHeight: 1 },
+      "3xl": { fontSize: { base: "5xl", md: "6xl" }, lineHeight: 1 },
+      "2xl": {
+        fontSize: { base: "4xl", md: "5xl" },
+        lineHeight: { base: 1.2, md: 1 },
+      },
+      xl: {
+        fontSize: { base: "3xl", md: "4xl" },
+        lineHeight: { base: 1.33, md: 1.2 },
+      },
+      lg: {
+        fontSize: { base: "2xl", md: "3xl" },
+        lineHeight: { base: 1.33, md: 1.2 },
+      },
+      md: { fontSize: "xl", lineHeight: 1.2 },
+      sm: { fontSize: "md", lineHeight: 1.2 },
+      xs: { fontSize: "sm", lineHeight: 1.2 },
+    },
+    // Brand marketing headings. The `display` font token is Helvetica in OSS and
+    // GT Walsheim in the private preset.
+    variant: {
+      marketing: { fontFamily: "display" },
+    },
+  },
+  defaultVariants: {
+    size: "xl",
+  },
+});

package/src/Heading.tsx

@@ -0,0 +1,14 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import { styled } from "styled-system/jsx";
+import { heading } from "styled-system/recipes";
+
+/**
+ * Heading — Chakra's <Heading> equivalent, backed by the `heading` config
+ * recipe (so the private preset can add brand variants). Defaults to an <h2>;
+ * pass `as` to change the element and `size` to pick the type scale.
+ */
+export const Heading = styled("h2", heading);

package/src/Icon.tsx

@@ -0,0 +1,55 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import { IconType } from "react-icons/lib";
+import { css, cx } from "styled-system/css";
+import { SystemStyleObject } from "styled-system/types";
+
+export interface IconProps {
+  /** The react-icons component to render. */
+  as: IconType;
+  /** Panda style overrides (size via fontSize/boxSize, colour, etc.). */
+  css?: SystemStyleObject;
+  className?: string;
+  "aria-label"?: string;
+  "aria-hidden"?: boolean;
+}
+
+/**
+ * Icon — renders a react-icons glyph inline at `1em`, matching Chakra's <Icon>
+ * base styles. `fill: currentColor` means the glyph follows the surrounding
+ * text colour (set `css={{ color: ... }}` to override), so it inherits colour
+ * like Chakra's icons rather than defaulting to black.
+ *
+ * Unlabelled icons are treated as decorative and hidden from assistive tech;
+ * a labelled icon gets `role="img"` (a bare svg aria-label is unreliably
+ * announced without it).
+ */
+export const Icon = ({
+  as: As,
+  css: cssProp,
+  className,
+  "aria-label": ariaLabel,
+  "aria-hidden": ariaHidden,
+}: IconProps) => (
+  <As
+    className={cx(
+      css({
+        width: "1em",
+        height: "1em",
+        display: "inline-block",
+        lineHeight: "1em",
+        flexShrink: 0,
+        fill: "currentColor",
+        ...cssProp,
+      }),
+      className,
+    )}
+    focusable="false"
+    aria-label={ariaLabel}
+    aria-hidden={ariaHidden ?? (ariaLabel ? undefined : true)}
+    role={ariaLabel ? "img" : undefined}
+  />
+);

package/src/IconButton.tsx

@@ -0,0 +1,39 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import { forwardRef } from "react";
+import { Button, ButtonProps } from "./Button";
+
+export interface IconButtonProps
+  extends Omit<ButtonProps, "leftIcon" | "rightIcon"> {
+  /** Icon-only buttons have no visible label, so this is required. */
+  "aria-label": string;
+  /** Circular rather than the recipe's border-radius (Chakra's `isRound`). */
+  isRound?: boolean;
+}
+
+/**
+ * IconButton — a square, icon-only Button. Zeroes the recipe's horizontal
+ * padding (its size variants add `px`, which would squeeze a single glyph in a
+ * fixed-width button) and keeps the `minW` from the size so the box stays
+ * square. Pass the icon as children.
+ */
+export const IconButton = forwardRef<HTMLButtonElement, IconButtonProps>(
+  function IconButton({ isRound, css: cssProp, children, ...rest }, ref) {
+    return (
+      <Button
+        ref={ref}
+        css={{
+          px: 0,
+          ...(isRound ? { borderRadius: "full" } : {}),
+          ...cssProp,
+        }}
+        {...rest}
+      >
+        {children}
+      </Button>
+    );
+  },
+);

package/src/Image.tsx

@@ -0,0 +1,11 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import { styled } from "styled-system/jsx";
+
+/** Image — an <img> accepting Panda style props. Replaces Chakra's <Image>. */
+export const Image = styled("img", {
+  base: { maxWidth: "100%" },
+});

package/src/Input.recipe.ts

@@ -0,0 +1,63 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import { defineRecipe } from "@pandacss/dev";
+
+// Chakra's transition.property.common, inlined (Panda has no transitionProperty
+// token category).
+const transitionCommon =
+  "background-color, border-color, color, fill, stroke, opacity, box-shadow, transform";
+
+/**
+ * Input recipe — Chakra's outline Input field at md size (light mode). Used by
+ * the shared-ui Input and NativeSelect, and by TextField's input slot.
+ *
+ * Focus matches both native `:focus-visible` (plain inputs; browsers treat any
+ * focus in a text field as focus-visible) and react-aria's `data-focused`
+ * (inputs inside RAC TextField). Focus is declared after invalid so a focused
+ * invalid field shows the focus ring, as in Chakra.
+ *
+ * Registered in the base preset (base-preset.ts).
+ */
+export const input = defineRecipe({
+  className: "input",
+  base: {
+    width: "100%",
+    minWidth: 0,
+    outline: "none",
+    position: "relative",
+    appearance: "none",
+    font: "inherit",
+    transitionProperty: transitionCommon,
+    transitionDuration: "normal",
+    fontSize: "md",
+    px: "4",
+    h: "10",
+    borderRadius: "md",
+    border: "1px solid",
+    borderColor: "gray.200",
+    bg: "inherit",
+    color: "inherit",
+    _hover: { borderColor: "gray.300" },
+    "&[data-invalid], &:user-invalid": {
+      borderColor: "danger.500",
+      boxShadow: "0 0 0 1px token(colors.danger.500)",
+    },
+    "&:is(:focus-visible, [data-focused])": {
+      zIndex: 1,
+      borderColor: "focusBorder",
+      boxShadow: "0 0 0 1px token(colors.focusBorder)",
+      // Focus indicator for forced-colors modes, which strip the box-shadow
+      // and force the border colour (the focusShadow utility's technique; the
+      // ring here is the 1px border tint, not an outline* shadow token).
+      outline: "2px solid transparent",
+      outlineOffset: "2px",
+    },
+    "&:is(:disabled, [data-disabled])": {
+      opacity: 0.4,
+      cursor: "not-allowed",
+    },
+  },
+});

package/src/Input.tsx

@@ -0,0 +1,33 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import { forwardRef, InputHTMLAttributes } from "react";
+import { css, cx } from "styled-system/css";
+import { input } from "styled-system/recipes";
+import { SystemStyleObject } from "styled-system/types";
+
+export interface InputProps
+  extends Omit<InputHTMLAttributes<HTMLInputElement>, "className"> {
+  /** Per-instance style overrides, merged after the recipe. */
+  css?: SystemStyleObject;
+  className?: string;
+}
+
+/**
+ * Input — a native input styled like Chakra's outline Input (md). For a
+ * labelled field with help/error text use TextField instead.
+ */
+export const Input = forwardRef<HTMLInputElement, InputProps>(function Input(
+  { css: cssProp, className, ...rest },
+  ref,
+) {
+  return (
+    <input
+      ref={ref}
+      className={cx(input(), cssProp ? css(cssProp) : undefined, className)}
+      {...rest}
+    />
+  );
+});

package/src/InputGroup.tsx

@@ -0,0 +1,48 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+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.
+ */
+export const InputGroup = styled("div", {
+  base: { position: "relative", width: "100%", display: "flex" },
+});
+
+// The element styles are written out twice rather than shared via a spread:
+// Panda's extractor only reliably evaluates inline literals.
+
+/** Element overlaying the start of an InputGroup (Chakra InputLeftElement). */
+export const InputLeftElement = styled("div", {
+  base: {
+    position: "absolute",
+    top: 0,
+    left: 0,
+    width: "10",
+    height: "10",
+    display: "flex",
+    alignItems: "center",
+    justifyContent: "center",
+    zIndex: 2,
+  },
+});
+
+/** Element overlaying the end of an InputGroup (Chakra InputRightElement). */
+export const InputRightElement = styled("div", {
+  base: {
+    position: "absolute",
+    top: 0,
+    right: 0,
+    width: "10",
+    height: "10",
+    display: "flex",
+    alignItems: "center",
+    justifyContent: "center",
+    zIndex: 2,
+  },
+});

package/src/Link.tsx

@@ -0,0 +1,23 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+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.
+ */
+export const Link = styled("a", {
+  base: {
+    cursor: "pointer",
+    textDecoration: "none",
+    outline: "none",
+    transitionProperty:
+      "background-color, border-color, color, fill, stroke, opacity, box-shadow, transform",
+    transitionDuration: "normal",
+    _hover: { textDecoration: "underline" },
+    _focusVisible: { focusShadow: "outline" },
+  },
+});

package/src/LinkBox.tsx

@@ -0,0 +1,88 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import { ButtonHTMLAttributes, forwardRef } from "react";
+import { css, cx } from "styled-system/css";
+import { styled } from "styled-system/jsx";
+import { button } from "styled-system/recipes";
+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>.
+ */
+export const LinkBox = styled("div", {
+  base: { position: "relative" },
+});
+
+/**
+ * LinkOverlay — an anchor whose `::before` stretches over the nearest
+ * LinkBox, making the whole box its hit area. For button-driven overlays,
+ * apply the same `_before` inset style to a Button instead.
+ */
+export const LinkOverlay = styled("a", {
+  base: {
+    position: "static",
+    _before: {
+      content: '""',
+      cursor: "inherit",
+      display: "block",
+      position: "absolute",
+      top: 0,
+      left: 0,
+      zIndex: 0,
+      width: "100%",
+      height: "100%",
+    },
+  },
+});
+
+export interface LinkOverlayButtonProps
+  extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, "className"> {
+  /** Per-instance style overrides, merged after the base. */
+  css?: SystemStyleObject;
+  className?: string;
+}
+
+/**
+ * LinkOverlayButton — the button flavour of LinkOverlay: its `::before`
+ * stretches over the nearest LinkBox so the whole box is clickable.
+ *
+ * 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).
+ */
+export const LinkOverlayButton = forwardRef<
+  HTMLButtonElement,
+  LinkOverlayButtonProps
+>(function LinkOverlayButton({ css: cssProp, className, ...rest }, ref) {
+  return (
+    <button
+      ref={ref}
+      type="button"
+      className={cx(
+        button({ variant: "unstyled" }),
+        css({
+          cursor: "pointer",
+          position: "static",
+          _before: {
+            content: '""',
+            cursor: "pointer",
+            display: "block",
+            position: "absolute",
+            inset: 0,
+            zIndex: 0,
+          },
+        }),
+        cssProp ? css(cssProp) : undefined,
+        className,
+      )}
+      {...rest}
+    />
+  );
+});

package/src/List.tsx

@@ -0,0 +1,27 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import { styled } from "styled-system/jsx";
+
+/**
+ * Unstyled list, matching Chakra's <List> (Panda's preflight already zeroes
+ * margins/padding and removes list markers).
+ */
+export const List = styled("ul");
+
+/** 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,88 @@
+/**
+ * (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"],
+  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,
+    },
+  },
+});