@microbit/ui 0.0.0-gray.ramp.90

package/src/Modal.tsx

@@ -0,0 +1,377 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+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";
+
+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 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"). */
+  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;
+  /**
+   * 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.
+   */
+  contentStyle?: CSSProperties;
+  /**
+   * 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;
+  /**
+   * `data-*` attributes land on the dialog box (where Chakra's went, on
+   * ModalContent), 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;
+}
+
+/**
+ * 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. Collapses Chakra's
+ * Modal/ModalOverlay/ModalContent into a single shell; place ModalHeader,
+ * ModalBody and ModalFooter inside.
+ *
+ * Two ways to drive it:
+ *
+ * - **Controlled** (`isOpen` + `onClose`), which is what a Chakra app ports
+ *   to, and 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,
+  onClose,
+  size,
+  isDismissable = true,
+  motionless,
+  isKeyboardDismissDisabled,
+  contentCss,
+  contentStyle,
+  overlayCss,
+  role,
+  isCentered,
+  onCloseComplete,
+  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({
+        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) {
+          close();
+        }
+      }}
+      isDismissable={isDismissable}
+      isKeyboardDismissDisabled={isKeyboardDismissDisabled}
+      className={cx(
+        slots.overlay,
+        motionlessClass,
+        overlayCss ? css(overlayCss) : undefined,
+      )}
+    >
+      <UnmountCallback callback={handleUnmount} />
+      <RACModal
+        {...dataProps}
+        style={contentStyle}
+        className={cx(
+          slots.content,
+          motionlessClass,
+          contentCss ? css(contentCss) : undefined,
+        )}
+      >
+        <Dialog role={role} aria-label={ariaLabel} className={slots.inner}>
+          <SlotContext.Provider value={{ slots, onClose: close }}>
+            {children}
+          </SlotContext.Provider>
+        </Dialog>
+      </RACModal>
+    </ModalOverlay>
+  );
+};
+
+/**
+ * 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, as they did on Chakra's. */
+  [key: `data-${string}`]: unknown;
+}
+
+/** Modal title. Rendered as RAC's labelling heading for the dialog. */
+export const ModalHeader = ({
+  children,
+  css: cssProp,
+  className,
+  level,
+  ...rest
+}: SlotProps & {
+  /**
+   * 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(
+        slots.header,
+        cssProp ? css(cssProp) : undefined,
+        className,
+      )}
+    >
+      {children}
+    </RACHeading>
+  );
+};
+
+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}
+    </div>
+  );
+};
+
+export const ModalFooter = ({
+  children,
+  css: cssProp,
+  className,
+  ...rest
+}: SlotProps) => {
+  const { slots } = useDialog();
+  return (
+    <div
+      {...dataAttrs(rest)}
+      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;
+  /** `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.
+ */
+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(
+        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,94 @@
+/**
+ * (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, 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.
+  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 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). Chakra's Select worked the same way: layout
+   * props were split onto `.chakra-select__wrapper`, `width: 100%` otherwise.
+   * 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`).
+ */
+export const NativeSelect = forwardRef<HTMLSelectElement, NativeSelectProps>(
+  function NativeSelect(
+    { hideChevron = false, size, css: cssProp, wrapperCss, className, ...rest },
+    ref,
+  ) {
+    const select = (
+      <select
+        ref={ref}
+        className={cx(
+          input({ size }),
+          css(
+            { cursor: "pointer" },
+            // Room for the chevron overlay (Chakra Select's icon spacing,
+            // constant across sizes).
+            hideChevron ? undefined : { paddingRight: "8" },
+            cssProp,
+          ),
+          className,
+        )}
+        {...rest}
+      />
+    );
+    if (hideChevron) {
+      return select;
+    }
+    return (
+      <span
+        className={css(
+          // Full-width like every other field (and Chakra's select wrapper);
+          // 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. */}
+        <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>
+    );
+  },
+);

package/src/NumberField.recipe.ts

@@ -0,0 +1,67 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+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).
+ *
+ * Registered in the base preset (base-preset.ts). No variants, so it needs
+ * no `staticCss` entry.
+ */
+export const numberField = defineSlotRecipe({
+  className: "numberField",
+  slots: ["root", "group", "stepper", "stepperButton"],
+  base: {
+    root: {
+      display: "flex",
+      flexDirection: "column",
+      alignItems: "stretch",
+    },
+    group: {
+      position: "relative",
+      zIndex: 0,
+    },
+    // Chakra's NumberInputStepper: 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",
+      width: "6",
+      zIndex: 1,
+    },
+    stepperButton: {
+      display: "flex",
+      alignItems: "center",
+      justifyContent: "center",
+      flex: 1,
+      cursor: "pointer",
+      lineHeight: "normal",
+      fontSize: "xs",
+      color: "inherit",
+      bg: "transparent",
+      borderStart: "1px solid",
+      borderColor: "gray.200",
+      transitionProperty: "background",
+      transitionDuration: "ultra-fast",
+      "&:last-child": {
+        borderTop: "1px solid",
+        borderTopColor: "gray.200",
+        marginTop: "-1px",
+      },
+      "&[data-hovered]": { bg: "gray.100" },
+      "&[data-pressed]": { bg: "gray.200" },
+      "&[data-disabled]": { opacity: 0.4, cursor: "not-allowed" },
+    },
+  },
+});

package/src/NumberField.tsx

@@ -0,0 +1,86 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import { forwardRef, ReactNode } from "react";
+import {
+  Button as RACButton,
+  Group as RACGroup,
+  Input as RACInput,
+  Label as RACLabel,
+  NumberField as RACNumberField,
+  NumberFieldProps as RACNumberFieldProps,
+} from "react-aria-components";
+import { RiArrowDownSFill, RiArrowUpSFill } from "react-icons/ri";
+import { css, cx } from "styled-system/css";
+import { field, input, numberField } from "styled-system/recipes";
+import { SystemStyleObject } from "styled-system/types";
+import { Icon } from "./Icon";
+
+export interface NumberFieldProps
+  extends Omit<RACNumberFieldProps, "className" | "children" | "style"> {
+  /** Visible label (optional; otherwise pass `aria-label`). */
+  label?: ReactNode;
+  /** Root style overrides (e.g. row layout for label-beside-field forms). */
+  css?: SystemStyleObject;
+  /** Label style overrides. */
+  labelCss?: SystemStyleObject;
+  /** Group (input + steppers) style overrides — set `width` here. */
+  groupCss?: SystemStyleObject;
+  /** Input style overrides (e.g. a smaller size than the recipe's md). */
+  inputCss?: SystemStyleObject;
+}
+
+/**
+ * NumberField — react-aria-components <NumberField> styled like Chakra's
+ * NumberInput (outline input + right-hand stepper column). The ref is
+ * forwarded to the input element. Value clamping to min/maxValue is
+ * handled by react-aria; onChange receives NaN when the field is emptied.
+ */
+export const NumberField = forwardRef<HTMLInputElement, NumberFieldProps>(
+  function NumberField(
+    { label, css: cssProp, labelCss, groupCss, inputCss, ...rest },
+    ref,
+  ) {
+    const slots = numberField();
+    const fieldSlots = field();
+    return (
+      <RACNumberField
+        {...rest}
+        className={cx(slots.root, cssProp ? css(cssProp) : undefined)}
+      >
+        {label != null && (
+          <RACLabel
+            className={cx(
+              fieldSlots.label,
+              labelCss ? css(labelCss) : undefined,
+            )}
+          >
+            {label}
+          </RACLabel>
+        )}
+        <RACGroup
+          className={cx(slots.group, groupCss ? css(groupCss) : undefined)}
+        >
+          <RACInput
+            ref={ref}
+            className={cx(
+              input(),
+              // Room for the stepper column.
+              css({ paddingEnd: "6" }, inputCss),
+            )}
+          />
+          <div className={slots.stepper}>
+            <RACButton slot="increment" className={slots.stepperButton}>
+              <Icon as={RiArrowUpSFill} />
+            </RACButton>
+            <RACButton slot="decrement" className={slots.stepperButton}>
+              <Icon as={RiArrowDownSFill} />
+            </RACButton>
+          </div>
+        </RACGroup>
+      </RACNumberField>
+    );
+  },
+);

package/src/PopoverArrow.tsx

@@ -0,0 +1,67 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import { OverlayArrow } from "react-aria-components";
+import { css, cx } from "styled-system/css";
+import { SystemStyleObject } from "styled-system/types";
+
+// react-aria positions the arrow and stamps the resolved side on the wrapper
+// as data-placement, but leaves orienting the glyph to us. The svg is square
+// with the triangle in the half nearest the overlay (tip at centre), so
+// rotating about the centre keeps it flush against the overlay on every side
+// — no translate fix-ups, whose signs depend on rotation direction and are
+// easy to get wrong (they detached the tooltip arrow from its box).
+//
+// "Flush" still antialiases to a hairline seam when the overlay's edge lands
+// on a subpixel boundary, so each placement also pulls the svg 1px into the
+// overlay with a negative margin on the overlay-facing side (margins move the
+// box before the rotate, so the bleed direction is unaffected by it).
+const arrowBase = css({
+  "& svg": { display: "block" },
+  "&[data-placement='top'] svg": { marginTop: "-1px" },
+  "&[data-placement='bottom'] svg": {
+    transform: "rotate(180deg)",
+    marginBottom: "-1px",
+  },
+  "&[data-placement='right'] svg": {
+    transform: "rotate(90deg)",
+    marginRight: "-1px",
+  },
+  "&[data-placement='left'] svg": {
+    transform: "rotate(-90deg)",
+    marginLeft: "-1px",
+  },
+});
+
+export interface PopoverArrowProps {
+  /**
+   * Base width of the visible triangle in px; it protrudes half this into
+   * the gap. Defaults to Chakra's tooltip arrow proportions (an 8px square
+   * rotated 45°).
+   */
+  size?: number;
+  /** Styles merged after the base, e.g. `{ "& svg": { fill: "white" } }`. */
+  css?: SystemStyleObject;
+  className?: string;
+}
+
+/**
+ * PopoverArrow — the notch pointing from a popover or tooltip at its
+ * trigger, oriented automatically for react-aria's resolved placement.
+ * Render inside a RAC Popover/Tooltip; set the fill via the css prop.
+ */
+export const PopoverArrow = ({
+  size = 11.314,
+  css: cssProp,
+  className,
+}: PopoverArrowProps) => (
+  <OverlayArrow
+    className={cx(arrowBase, cssProp ? css(cssProp) : undefined, className)}
+  >
+    <svg width={size} height={size} viewBox="0 0 12 12">
+      <path d="M0 0 L6 6 L12 0" />
+    </svg>
+  </OverlayArrow>
+);