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

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" },

package/src/Modal.tsx

@@ -3,19 +3,28 @@
  *
  * SPDX-License-Identifier: MIT
  */
-import { createContext, ReactNode, RefObject, useContext } from "react";
+import {
+  createContext,
+  CSSProperties,
+  ReactNode,
+  RefObject,
+  useContext,
+} from "react";
 import {
   Button as RACButton,
   Dialog,
+  DialogTrigger as RACDialogTrigger,
   Heading as RACHeading,
   Modal as RACModal,
   ModalOverlay,
+  OverlayTriggerStateContext,
 } 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 { dataAttrs } from "./data-attrs";
 import { uiMessage } from "./messages";
 import { UnmountCallback } from "./UnmountCallback";
 
@@ -42,38 +51,39 @@ export type ModalSize = ConditionalValue<
   | "full"
 >;
 
-export interface ModalProps {
-  isOpen: boolean;
-  onClose: () => void;
+export interface ModalOwnProps {
   size?: ModalSize;
   /** Allow closing by clicking the backdrop (default true; Escape always closes). */
   isDismissable?: boolean;
-  /** Disable the enter/exit transitions (Chakra's motionPreset="none"). */
+  /** Disable the enter/exit transitions. */
   motionless?: boolean;
-  /** Prevent Escape closing the dialog (Chakra's closeOnEsc={false}). */
+  /** Prevent Escape closing the dialog. */
   isKeyboardDismissDisabled?: boolean;
-  /** Style overrides for the dialog box (Chakra's ModalContent props). */
+  /** Style overrides for the dialog box. */
   contentCss?: SystemStyleObject;
   /**
-   * Style overrides for the backdrop (Chakra's ModalOverlay props), e.g. a
-   * transparent backdrop when something else provides the dimming.
+   * Inline styles for the dialog box, for runtime-computed positioning that
+   * Panda can't statically extract (e.g. a dialog aligned to a measured
+   * element). Prefer `contentCss` for static styles.
    */
-  overlayCss?: SystemStyleObject;
+  contentStyle?: CSSProperties;
   /**
-   * Use "alertdialog" for confirmations that interrupt the user (Chakra's
-   * AlertDialog).
+   * Style overrides for the backdrop, e.g. a transparent backdrop when
+   * something else provides the dimming.
    */
+  overlayCss?: SystemStyleObject;
+  /** Use "alertdialog" for confirmations that interrupt the user. */
   role?: "dialog" | "alertdialog";
-  /** Vertically centre the dialog (Chakra's `isCentered`). */
+  /** Vertically centre the dialog. */
   isCentered?: boolean;
   /**
    * Called after the dialog has fully closed (exit transition done and the
-   * dialog removed). Matches Chakra's `onCloseComplete`.
+   * dialog removed).
    */
   onCloseComplete?: () => void;
   /**
    * Element to focus when the dialog closes, instead of the element that was
-   * focused when it opened. Matches Chakra's `finalFocusRef`.
+   * focused when it opened.
    */
   finalFocusRef?: RefObject<HTMLElement>;
   /**
@@ -84,12 +94,51 @@ export interface ModalProps {
    */
   "aria-label"?: string;
   children: ReactNode;
+  /**
+   * `data-*` attributes land on the dialog box, so end-to-end tests can
+   * address a dialog. Shells that forward their caller's data attributes can
+   * spread them straight in.
+   */
+  [key: `data-${string}`]: unknown;
 }
 
 /**
- * Modal — a focus-trapping dialog. Collapses Chakra's
- * Modal/ModalOverlay/ModalContent into a single shell; place ModalHeader,
+ * A Modal you drive yourself. Also the type for a component that *forwards*
+ * modal props — `Omit<ControlledModalProps, "children">` — because a spread
+ * cannot be matched against the union `ModalProps` is: TypeScript has no way
+ * to know which half of it an object with `isOpen?: boolean` satisfies.
+ */
+export type ControlledModalProps = ModalOwnProps & {
+  /** Whether the dialog is showing. */
+  isOpen: boolean;
+  /** Called when the dialog asks to close. */
+  onClose: () => void;
+};
+
+/**
+ * The props of a `Modal`: its own, plus an open state that is either entirely
+ * yours or entirely a `DialogTrigger`'s. Never half of each — `isOpen`
+ * without `onClose` leaves the close button and Escape with nothing to call,
+ * so the pair is enforced rather than merely documented.
+ */
+export type ModalProps =
+  | ControlledModalProps
+  | (ModalOwnProps & { isOpen?: never; onClose?: never });
+
+/**
+ * Modal — a focus-trapping dialog in a single shell; place ModalHeader,
  * ModalBody and ModalFooter inside.
+ *
+ * Two ways to drive it:
+ *
+ * - **Controlled** (`isOpen` + `onClose`), which is what any dialog with more
+ *   than one opener needs — a menu item and a toolbar button opening the same
+ *   dialog, or one opened from a handler after an async result.
+ * - **Inside a `DialogTrigger`**, with neither prop: react-aria holds the
+ *   open state, the trigger opens it, and `ModalCloseButton` and the footer's
+ *   `useDialogClose()` still close it. Prefer this where a dialog has exactly
+ *   one trigger sitting next to it — there is no state to hold, and none to
+ *   get out of step.
  */
 export const Modal = ({
   isOpen,
@@ -99,6 +148,7 @@ export const Modal = ({
   motionless,
   isKeyboardDismissDisabled,
   contentCss,
+  contentStyle,
   overlayCss,
   role,
   isCentered,
@@ -106,7 +156,14 @@ export const Modal = ({
   finalFocusRef,
   "aria-label": ariaLabel,
   children,
+  ...rest
 }: ModalProps) => {
+  // Set by a DialogTrigger (or any react-aria overlay trigger) above us. When
+  // `isOpen` is given it is ignored: RAC's ModalOverlay prefers an explicit
+  // prop over the context, and so do we for the close function.
+  const triggerState = useContext(OverlayTriggerStateContext);
+  const close = onClose ?? (() => triggerState?.close());
+  const dataProps = dataAttrs(rest);
   const slots = dialog({ size, centered: isCentered });
   const motionlessClass = motionless
     ? css({
@@ -128,11 +185,17 @@ export const Modal = ({
       isOpen={isOpen}
       onOpenChange={(open) => {
         if (!open) {
-          onClose();
+          close();
         }
       }}
       isDismissable={isDismissable}
       isKeyboardDismissDisabled={isKeyboardDismissDisabled}
+      // Marker for the html:has() rule in base-preset.ts that releases the
+      // scroll lock's reserved scrollbar gutter while a full-size dialog is
+      // open: the reserved strip is a hit-testing dead zone (clicks fall
+      // through to the root and read as outside-dismissal), and the page
+      // reflowing behind an opaque full-screen dialog is invisible.
+      data-fullsize={size === "full" || undefined}
       className={cx(
         slots.overlay,
         motionlessClass,
@@ -141,6 +204,8 @@ export const Modal = ({
     >
       <UnmountCallback callback={handleUnmount} />
       <RACModal
+        {...dataProps}
+        style={contentStyle}
         className={cx(
           slots.content,
           motionlessClass,
@@ -148,7 +213,7 @@ export const Modal = ({
         )}
       >
         <Dialog role={role} aria-label={ariaLabel} className={slots.inner}>
-          <SlotContext.Provider value={{ slots, onClose }}>
+          <SlotContext.Provider value={{ slots, onClose: close }}>
             {children}
           </SlotContext.Provider>
         </Dialog>
@@ -157,10 +222,40 @@ export const Modal = ({
   );
 };
 
+/**
+ * DialogTrigger — react-aria-components' <DialogTrigger>: wrap a trigger
+ * element and a `Modal`, and the open state is theirs rather than yours.
+ *
+ * ```tsx
+ * <DialogTrigger>
+ *   <Button>Settings</Button>
+ *   <Modal size="lg">
+ *     <ModalHeader>Settings</ModalHeader>
+ *     …
+ *   </Modal>
+ * </DialogTrigger>
+ * ```
+ *
+ * Only for a dialog with a single trigger beside it. A dialog opened from
+ * more than one place, from a menu item (which cannot hold a dialog — a
+ * non-collection child truncates the menu), or from a handler, wants the
+ * controlled `Modal` instead.
+ */
+export const DialogTrigger = RACDialogTrigger;
+
+/**
+ * The current dialog's close function — the same one `ModalCloseButton` uses,
+ * for a footer's own Cancel/Done buttons. Works in both modes, so a dialog's
+ * content need not know which is driving it.
+ */
+export const useDialogClose = () => useDialog().onClose;
+
 interface SlotProps {
   children?: ReactNode;
   css?: SystemStyleObject;
   className?: string;
+  /** `data-*` attributes land on the slot element. */
+  [key: `data-${string}`]: unknown;
 }
 
 /** Modal title. Rendered as RAC's labelling heading for the dialog. */
@@ -169,12 +264,18 @@ export const ModalHeader = ({
   css: cssProp,
   className,
   level,
+  ...rest
 }: SlotProps & {
-  /** Heading element level (default 3, like RAC). */ level?: number;
+  /**
+   * Heading element level. Defaults to 2: RAC's Dialog supplies that through
+   * HeadingContext for the `title` slot, not the bare Heading default of 3.
+   */
+  level?: number;
 }) => {
   const { slots } = useDialog();
   return (
     <RACHeading
+      {...dataAttrs(rest)}
       slot="title"
       level={level}
       className={cx(
@@ -188,10 +289,16 @@ export const ModalHeader = ({
   );
 };
 
-export const ModalBody = ({ children, css: cssProp, className }: SlotProps) => {
+export const ModalBody = ({
+  children,
+  css: cssProp,
+  className,
+  ...rest
+}: SlotProps) => {
   const { slots } = useDialog();
   return (
     <div
+      {...dataAttrs(rest)}
       className={cx(slots.body, cssProp ? css(cssProp) : undefined, className)}
     >
       {children}
@@ -203,10 +310,12 @@ export const ModalFooter = ({
   children,
   css: cssProp,
   className,
+  ...rest
 }: SlotProps) => {
   const { slots } = useDialog();
   return (
     <div
+      {...dataAttrs(rest)}
       className={cx(
         slots.footer,
         cssProp ? css(cssProp) : undefined,
@@ -221,19 +330,23 @@ export const ModalFooter = ({
 export interface ModalCloseButtonProps {
   /** Accessible name; defaults to the localized close label. */
   "aria-label"?: string;
+  /** `data-*` attributes land on the button. */
+  [key: `data-${string}`]: unknown;
 }
 
 /**
- * ModalCloseButton — the X in the dialog's top corner (Chakra's
- * ModalCloseButton at its default md size). Closes via the Modal's onClose.
+ * ModalCloseButton — the X in the dialog's top corner. Closes via the Modal's
+ * onClose.
  */
 export const ModalCloseButton = ({
   "aria-label": ariaLabel,
+  ...rest
 }: ModalCloseButtonProps) => {
   const intl = useIntl();
   const { slots, onClose } = useDialog();
   return (
     <RACButton
+      {...dataAttrs(rest)}
       aria-label={ariaLabel ?? intl.formatMessage(uiMessage("ui.close-action"))}
       onPress={onClose}
       className={cx(
@@ -255,7 +368,7 @@ export const ModalCloseButton = ({
           transitionDuration: "normal",
           _hover: { bg: "blackAlpha.100" },
           _active: { bg: "blackAlpha.200" },
-          _focusVisible: { focusShadow: "outline" },
+          _focusVisible: { focusRing: "outline" },
         }),
       )}
     >

package/src/MoreMenuButton.tsx

@@ -0,0 +1,63 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import { forwardRef } from "react";
+import { MdMoreVert } from "react-icons/md";
+import { Icon } from "./Icon";
+import { IconButton, IconButtonProps } from "./IconButton";
+
+export interface MoreMenuButtonProps
+  extends Omit<IconButtonProps, "children"> {}
+
+/**
+ * MoreMenuButton — the "more options" half of a split button. Use as the
+ * trigger inside a MenuTrigger, alongside the main action, both in an
+ * attached ButtonGroup:
+ *
+ * ```tsx
+ * <ButtonGroup isAttached>
+ *   <Button variant="primary" onPress={send}>Send</Button>
+ *   <MenuTrigger>
+ *     <MoreMenuButton variant="primary" aria-label="More send options" />
+ *     <MenuList>…</MenuList>
+ *   </MenuTrigger>
+ * </ButtonGroup>
+ * ```
+ *
+ * Give it the main action's `variant`, `tone` and `size`: the two halves are
+ * one control. The seam between them is ButtonGroup's job.
+ */
+export const MoreMenuButton = forwardRef<
+  HTMLButtonElement,
+  MoreMenuButtonProps
+>(function MoreMenuButton({ css: cssProp, ...props }, ref) {
+  return (
+    <IconButton ref={ref} css={cssProp} {...props}>
+      <Icon
+        as={MdMoreVert}
+        css={{
+          // Optical centring: an attached end button is a rectangle plus a
+          // semicircle, whose area sits 4.7% of the width towards the flat
+          // edge. A share of the width rather than a length because that is a
+          // property of the shape, not the size — the button stays square and
+          // the radius always clamps to half its height (see IconButton), so
+          // one percentage holds everywhere. Leading is the mirror image; a
+          // middle or lone button is symmetric and needs nothing.
+          //
+          // Position rather than margin so the nudge can't feed back into the
+          // width the percentage resolves against.
+          "[data-attached] > *:not(:first-child):last-child &": {
+            position: "relative",
+            insetInlineStart: "-4.7%",
+          },
+          "[data-attached] > *:first-child:not(:last-child) &": {
+            position: "relative",
+            insetInlineStart: "4.7%",
+          },
+        }}
+      />
+    </IconButton>
+  );
+});

package/src/NativeSelect.tsx

@@ -5,41 +5,56 @@
  */
 import { forwardRef, SelectHTMLAttributes } from "react";
 import { css, cx } from "styled-system/css";
-import { input } from "styled-system/recipes";
+import { input, InputVariantProps } from "styled-system/recipes";
 import { SystemStyleObject } from "styled-system/types";
 
 export interface NativeSelectProps
-  extends Omit<SelectHTMLAttributes<HTMLSelectElement>, "className"> {
+  // `size` is the recipe's size scale; the native visible-rows attribute it
+  // shadows was unused.
+  extends Omit<SelectHTMLAttributes<HTMLSelectElement>, "className" | "size">,
+    InputVariantProps {
   /**
    * 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. */
+  /** Per-instance style overrides for the select, merged after the recipe. */
   css?: SystemStyleObject;
+  /**
+   * Style overrides for the chevron wrapper, which is where width constraints
+   * belong (the select fills it). No wrapper is rendered with `hideChevron`;
+   * constrain the select directly.
+   */
+  wrapperCss?: 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`).
+ * NativeSelect — a native select styled like the outline Input. The recipe's
+ * `appearance: none` removes the platform chevron, so one is drawn back in by
+ * default (`currentColor`).
  */
 export const NativeSelect = forwardRef<HTMLSelectElement, NativeSelectProps>(
   function NativeSelect(
-    { hideChevron = false, css: cssProp, className, ...rest },
+    { hideChevron = false, size, css: cssProp, wrapperCss, className, ...rest },
     ref,
   ) {
     const select = (
       <select
         ref={ref}
         className={cx(
-          input(),
+          input({ size }),
           css(
-            { cursor: "pointer" },
-            // Room for the chevron overlay.
-            hideChevron ? undefined : { paddingRight: "8" },
+            // Option text sits a hair higher than input text; the 1px bottom
+            // padding compensates.
+            {
+              cursor: "pointer",
+              paddingBottom: "1px",
+              _disabled: { cursor: "not-allowed" },
+            },
+            // Room for the chevron overlay (constant across sizes).
+            hideChevron ? undefined : { paddingEnd: "8" },
             cssProp,
           ),
           className,
@@ -51,21 +66,33 @@ export const NativeSelect = forwardRef<HTMLSelectElement, NativeSelectProps>(
       return select;
     }
     return (
-      <span className={css({ position: "relative", display: "inline-flex" })}>
+      <span
+        className={css(
+          // Full-width like every other field; the select's own recipe width
+          // fills it. Constrain via wrapperCss.
+          { position: "relative", display: "inline-flex", width: "100%" },
+          wrapperCss,
+        )}
+      >
         {select}
-        {/* Chakra Select's chevron. */}
+        {/* The chevron, fixed-size across field sizes. The path is Chakra
+            UI's Select chevron, inlined for visual parity with the apps'
+            original look (see the notice in LICENSE.md). */}
         <svg
           viewBox="0 0 24 24"
           aria-hidden
           className={css({
             position: "absolute",
-            right: "2",
+            insetEnd: "2",
             top: "50%",
             transform: "translateY(-50%)",
             width: "5",
             height: "5",
             pointerEvents: "none",
             fill: "currentColor",
+            // The chevron sits outside the select so it doesn't inherit its
+            // disabled dimming; dim it explicitly to match.
+            "select:disabled + &": { opacity: 0.5 },
           })}
         >
           <path d="M16.59 8.59 12 13.17 7.41 8.59 6 10l6 6 6-6z" />

package/src/NativeSelectField.tsx

@@ -0,0 +1,84 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import { forwardRef, ReactNode, useId } from "react";
+import { css, cx } from "styled-system/css";
+import { field } from "styled-system/recipes";
+import { SystemStyleObject } from "styled-system/types";
+import { FieldHelperText, FieldLabel, FieldLayoutProps } from "./Field";
+import { NativeSelect, NativeSelectProps } from "./NativeSelect";
+
+export interface NativeSelectFieldProps
+  extends NativeSelectProps,
+    FieldLayoutProps {
+  /** Visible label, associated with the select via `htmlFor`. */
+  label: ReactNode;
+  /** Label style overrides. */
+  labelCss?: SystemStyleObject;
+  /** Help text below the field, wired to the select's `aria-describedby`. */
+  helperText?: ReactNode;
+  /** Per-instance style overrides for the field root. */
+  rootCss?: SystemStyleObject;
+}
+
+/**
+ * NativeSelectField — a labelled `NativeSelect`, pairing the bare control with
+ * the field chrome the RAC fields get from react-aria, as `TextField` pairs
+ * with `Input`. The label association and `aria-describedby` are wired here,
+ * since there is no RAC context to do it; the label dims with the control
+ * exactly as the RAC fields' do. No `errorMessage` yet — no consumer needs
+ * one; render `FieldErrorMessage` beside it if yours does.
+ *
+ * With `labelPosition="side"` this is the settings row both
+ * `SelectFormControl`s hand-rolled: label beside a fixed-width select
+ * (`wrapperCss={{ width: "28ch" }}`), label absorbing the free space.
+ */
+export const NativeSelectField = forwardRef<
+  HTMLSelectElement,
+  NativeSelectFieldProps
+>(function NativeSelectField(
+  { label, labelCss, helperText, labelPosition, rootCss, id, ...rest },
+  ref,
+) {
+  const generatedId = useId();
+  const selectId = id ?? generatedId;
+  const helperId = useId();
+  const describedBy =
+    [rest["aria-describedby"], helperText != null ? helperId : undefined]
+      .filter(Boolean)
+      .join(" ") || undefined;
+  return (
+    <div
+      className={cx(
+        field({ size: rest.size, labelPosition }).root,
+        rootCss ? css(rootCss) : undefined,
+      )}
+      // The field recipe's label dims off the root's data-disabled, which RAC
+      // stamps for the other fields; here it is restated from the attribute.
+      data-disabled={rest.disabled || undefined}
+    >
+      <FieldLabel
+        htmlFor={selectId}
+        size={rest.size}
+        labelPosition={labelPosition}
+        isRequired={rest.required}
+        css={labelCss}
+      >
+        {label}
+      </FieldLabel>
+      <NativeSelect
+        ref={ref}
+        id={selectId}
+        {...rest}
+        aria-describedby={describedBy}
+      />
+      {helperText != null && (
+        <FieldHelperText id={helperId} labelPosition={labelPosition}>
+          {helperText}
+        </FieldHelperText>
+      )}
+    </div>
+  );
+});