@microbit/ui 0.1.0-alpha.9 → 0.1.0

package/src/Modal.tsx

@@ -13,15 +13,18 @@ import {
 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";
 
@@ -48,17 +51,15 @@ 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;
   /**
    * Inline styles for the dialog box, for runtime-computed positioning that
@@ -67,25 +68,22 @@ export interface ModalProps {
    */
   contentStyle?: CSSProperties;
   /**
-   * Style overrides for the backdrop (Chakra's ModalOverlay props), e.g. a
-   * transparent backdrop when something else provides the dimming.
+   * 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 (Chakra's
-   * AlertDialog).
-   */
+  /** 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>;
   /**
@@ -96,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,
@@ -119,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({
@@ -141,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,
@@ -154,6 +204,7 @@ export const Modal = ({
     >
       <UnmountCallback callback={handleUnmount} />
       <RACModal
+        {...dataProps}
         style={contentStyle}
         className={cx(
           slots.content,
@@ -162,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>
@@ -171,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. */
@@ -183,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(
@@ -202,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}
@@ -217,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,
@@ -235,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(
@@ -269,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

@@ -9,8 +9,8 @@ import { input, InputVariantProps } from "styled-system/recipes";
 import { SystemStyleObject } from "styled-system/types";
 
 export interface NativeSelectProps
-  // `size` is the recipe's size scale, as in Chakra; the native visible-rows
-  // attribute it shadows was unused.
+  // `size` is the recipe's size scale; the native visible-rows attribute it
+  // shadows was unused.
   extends Omit<SelectHTMLAttributes<HTMLSelectElement>, "className" | "size">,
     InputVariantProps {
   /**
@@ -19,19 +19,25 @@ export interface NativeSelectProps
    * 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 (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, size, css: cssProp, className, ...rest },
+    { hideChevron = false, size, css: cssProp, wrapperCss, className, ...rest },
     ref,
   ) {
     const select = (
@@ -40,10 +46,15 @@ export const NativeSelect = forwardRef<HTMLSelectElement, NativeSelectProps>(
         className={cx(
           input({ size }),
           css(
-            { cursor: "pointer" },
-            // Room for the chevron overlay (Chakra Select's icon spacing,
-            // constant across sizes).
-            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,
@@ -55,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, fixed-size across field sizes. */}
+        {/* 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>
+  );
+});

package/src/NumberField.recipe.ts

@@ -6,37 +6,44 @@
 import { defineSlotRecipe } from "@pandacss/dev";
 
 /**
- * NumberField slot recipe — Chakra's NumberInput look: an outline input (the
- * `input` recipe styles the input itself) with a right-hand stepper column of
- * two stacked buttons. Consumed by the shared-ui NumberField
- * (react-aria-components NumberField).
+ * NumberField slot recipe — an outline input (the `input` recipe styles the
+ * input itself) with a right-hand stepper column of two stacked buttons.
+ * Consumed by the shared-ui NumberField (react-aria-components NumberField).
  *
- * Registered in the base preset (base-preset.ts). No variants, so it needs
- * no `staticCss` entry.
+ * Registered in the base preset (base-preset.ts), which also has the
+ * `staticCss` entry that keeps the runtime-prop size variants generated.
  */
 export const numberField = defineSlotRecipe({
   className: "numberField",
   slots: ["root", "group", "stepper", "stepperButton"],
   base: {
-    root: {
-      display: "flex",
-      flexDirection: "column",
-      alignItems: "stretch",
-    },
+    // No layout here: the component wears the `field` recipe's root alongside
+    // this slot, and that recipe is the single owner of field-root layout
+    // (else `labelPosition` would fight this slot over `flexDirection`). The
+    // slot stays for apps and variants to target.
+    root: {},
     group: {
       position: "relative",
       zIndex: 0,
+      // The stepper overlays the input as a sibling, so the input's own
+      // :hover misses it — the group carries the hover tint. The :not()
+      // list is required: slot recipes layer above plain recipes
+      // (recipes.slots), so this would otherwise override focused/invalid
+      // (see docs/hints.md). :user-invalid takes its own :not(): :not() is
+      // not forgiving, so one list would drop the whole selector on a
+      // browser that doesn't know the pseudo-class (Safari < 16.5).
+      "&:hover input:not(:focus, [data-focused], [data-invalid]):not(:user-invalid)":
+        { borderColor: "gray.500" },
     },
-    // Chakra's NumberInputStepper: a column overlaying the input's right
-    // edge, inset by the input border.
+    // A column overlaying the input's right edge, inset by the input border.
     stepper: {
       display: "flex",
       flexDirection: "column",
       position: "absolute",
       insetEnd: "0",
       top: "0",
-      height: "calc(100% - 2px)",
-      margin: "1px",
+      height: "calc(100% - 4px)",
+      margin: "2px",
       width: "6",
       zIndex: 1,
     },
@@ -54,14 +61,48 @@ export const numberField = defineSlotRecipe({
       borderColor: "gray.200",
       transitionProperty: "background",
       transitionDuration: "ultra-fast",
+      // Follow the input's corners, less the 2px border the stepper is inset
+      // by, so the hover and pressed fills curve away with the border instead
+      // of squaring off over its arc. Radii track the input recipe's size
+      // scale, so the `sm` variant restates them.
+      "&:first-child": {
+        borderStartEndRadius: "calc(token(radii.md) - 2px)",
+      },
       "&:last-child": {
         borderTop: "1px solid",
         borderTopColor: "gray.200",
         marginTop: "-1px",
+        borderEndEndRadius: "calc(token(radii.md) - 2px)",
       },
       "&[data-hovered]": { bg: "gray.100" },
       "&[data-pressed]": { bg: "gray.200" },
       "&[data-disabled]": { opacity: 0.4, cursor: "not-allowed" },
     },
   },
+  variants: {
+    // The stepper column stays 24px wide at every size (as does the input
+    // padding paired with it in NumberField.tsx); only the arrow glyphs
+    // scale, at 0.75 × the field's font size. The base's `xs` is exactly
+    // md × 0.75, so md adds nothing.
+    size: {
+      lg: {
+        stepperButton: { fontSize: "calc(token(fontSizes.lg) * 0.75)" },
+      },
+      md: {},
+      sm: {
+        stepperButton: {
+          fontSize: "calc(token(fontSizes.sm) * 0.75)",
+          "&:first-child": {
+            borderStartEndRadius: "calc(token(radii.sm) - 2px)",
+          },
+          "&:last-child": {
+            borderEndEndRadius: "calc(token(radii.sm) - 2px)",
+          },
+        },
+      },
+    },
+  },
+  defaultVariants: {
+    size: "md",
+  },
 });