@microbit/ui 0.1.0-alpha.20 → 0.1.0-alpha.22

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@microbit/ui",
-  "version": "0.1.0-alpha.20",
+  "version": "0.1.0-alpha.22",
   "description": "micro:bit design-system primitives: react-aria-components + Panda CSS with a design language ported from Chakra UI v2. Ships as source; see README for the consumption setup.",
   "license": "MIT",
   "type": "module",

package/src/Modal.recipe.ts

@@ -54,7 +54,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",

package/src/Modal.tsx

@@ -195,6 +195,12 @@ export const Modal = ({
       }}
       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,

package/src/NumberField.recipe.ts

@@ -54,10 +54,18 @@ export const numberField = defineSlotRecipe({
       borderColor: "gray.200",
       transitionProperty: "background",
       transitionDuration: "ultra-fast",
+      // Follow the input's corners, less the 1px 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) - 1px)",
+      },
       "&:last-child": {
         borderTop: "1px solid",
         borderTopColor: "gray.200",
         marginTop: "-1px",
+        borderEndEndRadius: "calc(token(radii.md) - 1px)",
       },
       "&[data-hovered]": { bg: "gray.100" },
       "&[data-pressed]": { bg: "gray.200" },
@@ -75,7 +83,15 @@ export const numberField = defineSlotRecipe({
       },
       md: {},
       sm: {
-        stepperButton: { fontSize: "calc(token(fontSizes.sm) * 0.75)" },
+        stepperButton: {
+          fontSize: "calc(token(fontSizes.sm) * 0.75)",
+          "&:first-child": {
+            borderStartEndRadius: "calc(token(radii.sm) - 1px)",
+          },
+          "&:last-child": {
+            borderEndEndRadius: "calc(token(radii.sm) - 1px)",
+          },
+        },
       },
     },
   },

package/src/ProgressBar.tsx

@@ -50,7 +50,6 @@ export const ProgressBar = ({
           {
             height: "100%",
             bg: "brand.500",
-            transition: "width 0.2s",
           },
           barCss,
         )}

package/src/Toast.tsx

@@ -28,7 +28,7 @@ import { VisuallyHidden } from "./VisuallyHidden";
 export type ToastStatus = "info" | "success" | "warning" | "error";
 
 export interface ToastContent {
-  /** Dedup key: adding a toast whose id is already visible is a no-op. */
+  /** Dedup key: adding a toast whose id is already queued is a no-op. */
   id?: string;
   title?: ReactNode;
   description?: ReactNode;
@@ -36,13 +36,54 @@ export interface ToastContent {
   isClosable?: boolean;
 }
 
+// Enter/exit/reflow animation: queue updates run inside a view transition
+// (react-aria's supported mechanism — toasts unmount synchronously, so CSS
+// transitions on the element can't animate the exit). The keyframes and the
+// ::view-transition rules live in base-preset.ts, scoped by this class,
+// which marks the transition as toast-initiated while it runs: the rules
+// select entering/exiting groups with `(*)`, avoiding view-transition-class
+// (needs Safari 18.2/Chrome 125 vs 18.0/111 for the API itself), and the
+// scoping keeps them — and the pointer-events override — away from any view
+// transitions the app runs. Browsers without the API and reduced-motion
+// users get the bare update.
+const TRANSITION_CLASS = "microbit-ui-toast-transition";
+let activeTransitions = 0;
+const wrapUpdate = (fn: () => void) => {
+  if (
+    typeof document !== "undefined" &&
+    document.startViewTransition &&
+    !window.matchMedia("(prefers-reduced-motion: reduce)").matches
+  ) {
+    activeTransitions++;
+    document.documentElement.classList.add(TRANSITION_CLASS);
+    const transition = document.startViewTransition(fn);
+    transition.finished.finally(() => {
+      if (--activeTransitions === 0) {
+        document.documentElement.classList.remove(TRANSITION_CLASS);
+      }
+    });
+  } else {
+    fn();
+  }
+};
+
 // Module-level queue shared by useToast() and the <ToastProvider/> region.
 // (RAC's Toast API is still flagged UNSTABLE_*; the surface is small and behind
 // this module, so a swap to a custom queue later is contained.)
 export const toastQueue = new RACToastQueue<ToastContent>({
   maxVisibleToasts: 5,
+  wrapUpdate,
 });
 
+// Index of our ids to the queue's own keys. The queue only exposes its
+// visible slice — the newest `maxVisibleToasts` — so ids can't be resolved by
+// scanning it: once newer toasts arrive an older one is still queued but out
+// of sight, and dedup would let a second copy through while update() added
+// rather than replaced. react-aria's per-toast `onClose` keeps this honest
+// however a toast goes (timeout, close button, or update). clear() doesn't
+// call onClose, so closeAll empties both.
+const keysById = new Map<string, string>();
+
 // Status icon matching Chakra's AlertIcon (filled glyphs, coloured by the
 // toast foreground = white here). Warning is a triangle, error a circle, as
 // in Chakra — the glyph must distinguish them because the colours alone
@@ -83,7 +124,13 @@ export const ToastProvider = () => {
       {({ toast }) => {
         const status = toast.content.status ?? "info";
         return (
-          <RACToast toast={toast} className={toastRecipe({ status }).root}>
+          <RACToast
+            toast={toast}
+            className={toastRecipe({ status }).root}
+            // A unique view-transition-name per toast creates its snapshot
+            // group and lets old/new pair up across the transition.
+            style={{ viewTransitionName: toast.key }}
+          >
             <Icon as={statusIcon[status]} className={slots.icon} aria-hidden />
             <RACToastContent>
               {/* Colour and icon are the only visible status signals; say it
@@ -128,14 +175,18 @@ export interface ToastOptions extends ToastContent {
 
 export interface ToastFn {
   (options: ToastOptions): void;
-  /** Whether a toast with this id is currently visible. */
+  /**
+   * Whether a toast with this id is still queued — displayed, or waiting
+   * behind newer toasts for its turn.
+   */
   isActive(id: string): boolean;
   /**
-   * Replace a visible toast's content (Chakra's toast.update). The toast is
-   * re-added, so unlike Chakra it re-animates and restarts any timeout.
+   * Replace a queued toast's content (Chakra's toast.update). The toast is
+   * re-added, so unlike Chakra it re-animates, restarts any timeout, and
+   * takes its place at the front of the queue.
    */
   update(id: string, options: ToastOptions): void;
-  /** Dismiss all visible toasts (Chakra's toast.closeAll). */
+  /** Dismiss every toast, queued as well as displayed (Chakra's toast.closeAll). */
   closeAll(): void;
 }
 
@@ -146,8 +197,7 @@ export interface ToastFn {
  */
 export const useToast = (): ToastFn =>
   useMemo(() => {
-    const isActive = (id: string) =>
-      toastQueue.visibleToasts.some((t) => t.content.id === id);
+    const isActive = (id: string) => keysById.has(id);
     const add = ({
       id,
       title,
@@ -160,7 +210,7 @@ export const useToast = (): ToastFn =>
       if (id && isActive(id)) {
         return;
       }
-      toastQueue.add(
+      const key = toastQueue.add(
         {
           id,
           title,
@@ -168,21 +218,37 @@ export const useToast = (): ToastFn =>
           status,
           isClosable: isClosable || persistent,
         },
-        { timeout: persistent ? undefined : duration ?? 5000 },
+        {
+          timeout: persistent ? undefined : duration ?? 5000,
+          onClose: id
+            ? // Only our own entry is ours to drop: an id reused after this
+              // toast closed belongs to the later add.
+              () => {
+                if (keysById.get(id) === key) {
+                  keysById.delete(id);
+                }
+              }
+            : undefined,
+        },
       );
+      if (id) {
+        keysById.set(id, key);
+      }
     };
     const update = (id: string, options: ToastOptions) => {
-      const existing = toastQueue.visibleToasts.find(
-        (t) => t.content.id === id,
-      );
-      if (existing) {
-        toastQueue.close(existing.key);
+      const key = keysById.get(id);
+      if (key !== undefined) {
+        toastQueue.close(key);
       }
       add({ ...options, id });
     };
+    // clear() empties the whole queue, including the toasts held back by
+    // maxVisibleToasts. Closing the visible ones one by one would only
+    // promote the queued ones into view. It's also a single update, so the
+    // whole set exits in one view transition.
     const closeAll = () => {
-      // Copy first: closing mutates visibleToasts as we iterate.
-      [...toastQueue.visibleToasts].forEach((t) => toastQueue.close(t.key));
+      keysById.clear();
+      toastQueue.clear();
     };
     return Object.assign(add, { isActive, update, closeAll });
   }, []);

package/src/Tooltip.tsx

@@ -40,8 +40,41 @@ export interface TooltipProps {
    * the trigger (i.e. it is not a RAC component or `Focusable`).
    */
   triggerRef?: RefObject<HTMLElement | null>;
-  /** Hover open delay in ms (RAC default ~1500; pass 0 for instant). */
+  /**
+   * Hover open delay in ms, defaulting to react-aria's 1500.
+   *
+   * The delay is per bout of interest, not per control: react-aria keeps a
+   * global "warm" flag, so the first tooltip waits and every one after it opens
+   * instantly until half a second or so after the last one closes. That is what
+   * keeps a row of buttons from firing tooltips at a pointer merely crossing
+   * them.
+   *
+   * **Pass 0 where the tooltip is the label** — an icon-only button, where the
+   * text is the only explanation of the glyph and waiting for it reads as
+   * broken. Leave it alone where the control already says what it is and the
+   * tooltip adds detail.
+   */
   delay?: number;
+  /**
+   * Close delay in ms, defaulting to react-aria's 500.
+   *
+   * This is what makes a tooltip hoverable, as WCAG 1.4.13 asks: react-aria
+   * puts hover handlers on the tooltip that re-open it, but with an immediate
+   * close it has unmounted before the pointer can cross the gap. Chakra closed
+   * on mouse-out and we matched that at first; a tooltip that vanishes as you
+   * reach for it is not worth the parity. Pass 0 where the delay is wrong for a
+   * particular control.
+   */
+  closeDelay?: number;
+  /**
+   * Whether pressing the trigger closes the tooltip (RAC default true).
+   *
+   * react-aria binds this to keydown as well as pointerdown, so with the
+   * default *any* key press dismisses the tooltip and only hover or focus
+   * brings it back. Pass false where the tooltip's text is the point of the
+   * control rather than a hint about an action.
+   */
+  shouldCloseOnPress?: boolean;
   css?: SystemStyleObject;
 }
 
@@ -58,10 +91,17 @@ export const Tooltip = ({
   hasArrow,
   isOpen,
   triggerRef,
-  delay = 0,
+  delay,
+  closeDelay,
+  shouldCloseOnPress,
   css: cssProp,
 }: TooltipProps) => (
-  <TooltipTrigger isOpen={isOpen} delay={delay} closeDelay={0}>
+  <TooltipTrigger
+    isOpen={isOpen}
+    delay={delay}
+    closeDelay={closeDelay}
+    shouldCloseOnPress={shouldCloseOnPress}
+  >
     {children}
     <RACTooltip
       triggerRef={triggerRef}

package/src/TooltipButton.tsx

@@ -0,0 +1,230 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import {
+  ReactNode,
+  useCallback,
+  useContext,
+  useEffect,
+  useId,
+  useRef,
+} from "react";
+import { TooltipTriggerStateContext } from "react-aria-components";
+import { css } from "styled-system/css";
+import { SystemStyleObject } from "styled-system/types";
+import { Button } from "./Button";
+import { Tooltip, TooltipProps } from "./Tooltip";
+import { VisuallyHidden } from "./VisuallyHidden";
+
+// A tooltip whose text *is* the point of the control — an information affordance
+// beside a heading, say — rather than a hint about what a button does. That
+// difference drives everything here, because react-aria's tooltips are built for
+// the second case:
+//
+// - They never open on press, since a tooltip isn't a touch pattern. Sighted
+//   touch users would have no way in, so this toggles on press.
+// - Their text is associated with the trigger only while open, so touch screen
+//   readers (iPadOS VoiceOver, TalkBack) never reach it. The same text is
+//   therefore always present on a visually hidden node, named or described from
+//   the button. The visible tooltip is aria-hidden to avoid double announcement.
+// - Any key press dismisses them (see Tooltip's shouldCloseOnPress), which for
+//   this pattern means a keyboard user can dismiss but never re-open.
+//
+// Everything else is left to react-aria: it opens on hover and on keyboard
+// focus, closes on Escape without disturbing a surrounding dialog, and keeps
+// only one tooltip open at a time across the whole document. Hovering the
+// tooltip to keep it open relies on Tooltip's non-zero close delay, so don't
+// pass `closeDelay={0}` through to it.
+
+// How far outside the tooltip the pointer still counts as on it, covering the
+// trigger/tooltip gap and the arrow.
+const pointerMarginPx = 12;
+
+const triggerStyle: SystemStyleObject = {
+  // The button recipe's size variants set a height and horizontal padding for
+  // text buttons; shrink to the glyph so the focus ring is an even circle
+  // around it and the control doesn't stretch its row.
+  display: "inline-flex",
+  alignItems: "center",
+  justifyContent: "center",
+  height: "auto",
+  minHeight: "0",
+  minWidth: "0",
+  padding: "0",
+  lineHeight: "1",
+  cursor: "pointer",
+  borderRadius: "50%",
+  _focusVisible: { focusShadow: "outline" },
+};
+
+export interface TooltipButtonProps {
+  /**
+   * Tooltip body. Also the button's accessible name, or its description when
+   * `aria-label` is given.
+   */
+  label: ReactNode;
+  /** Button content, typically an `Icon`. */
+  children: ReactNode;
+  /**
+   * Short accessible name for the button, e.g. "Live graph". Recommended when
+   * `label` runs to more than a few words: without it the whole body becomes
+   * the button's name, which a screen reader reads out in full.
+   */
+  "aria-label"?: string;
+  placement?: TooltipProps["placement"];
+  hasArrow?: boolean;
+  /** Style overrides for the tooltip, e.g. padding for a multi-line body. */
+  css?: SystemStyleObject;
+  /** Style overrides for the button. */
+  triggerCss?: SystemStyleObject;
+}
+
+/**
+ * TooltipButton — a small button, usually an icon, whose tooltip carries
+ * information the user needs rather than a hint about an action.
+ *
+ * Unlike a bare `Tooltip` it works by pointer, keyboard and touch, and its text
+ * reaches screen readers on every platform. Use it for an information icon
+ * beside a heading or a "partially supported" marker; use `Tooltip` for a hint
+ * on a button that does something else.
+ *
+ * Open question: react-spectrum makes this pattern a popover
+ * (`ContextualHelp`), not a tooltip, which would remove the hidden copy of the
+ * body and the pointer-geometry keep-alive below rather than work around them.
+ * Tracked as microbit-foundation/ui#63, which would deprecate this component;
+ * see "Open across the completed migrations" in docs/migration-playbook.md
+ * before extending it.
+ */
+export const TooltipButton = ({
+  label,
+  children,
+  "aria-label": ariaLabel,
+  placement,
+  hasArrow,
+  css: cssProp,
+  triggerCss,
+}: TooltipButtonProps) => {
+  const textId = useId();
+  const tooltipBodyId = useId();
+  return (
+    <Tooltip
+      label={
+        <div id={tooltipBodyId} aria-hidden={true}>
+          {label}
+        </div>
+      }
+      placement={placement}
+      hasArrow={hasArrow}
+      css={cssProp}
+      // The tooltip is this button's whole explanation — an icon with a 1.5s
+      // wait before anything appears reads as broken — so opt out of the warmup
+      // the labelled controls want.
+      delay={0}
+      shouldCloseOnPress={false}
+    >
+      <span className={css({ display: "flex" })}>
+        <TooltipButtonTrigger
+          aria-label={ariaLabel}
+          textId={textId}
+          tooltipBodyId={tooltipBodyId}
+          css={triggerCss}
+        >
+          {children}
+        </TooltipButtonTrigger>
+        <VisuallyHidden as="div" id={textId} aria-hidden={true}>
+          {label}
+        </VisuallyHidden>
+      </span>
+    </Tooltip>
+  );
+};
+
+interface TooltipButtonTriggerProps {
+  children: ReactNode;
+  "aria-label"?: string;
+  /** Visually hidden copy of the body, naming or describing the button. */
+  textId: string;
+  /** The body inside the visible tooltip, used to find it in the document. */
+  tooltipBodyId: string;
+  css?: SystemStyleObject;
+}
+
+/**
+ * The button itself, split out so it can read the tooltip's state from context.
+ * Being a RAC component it registers itself as the tooltip's trigger — hover,
+ * focus and positioning all follow from that, even nested inside the span.
+ */
+const TooltipButtonTrigger = ({
+  children,
+  "aria-label": ariaLabel,
+  textId,
+  tooltipBodyId,
+  css: cssProp,
+}: TooltipButtonTriggerProps) => {
+  const state = useContext(TooltipTriggerStateContext);
+  const ref = useRef<HTMLButtonElement>(null);
+  const handlePress = useCallback(() => {
+    if (state?.isOpen) {
+      state.close(true);
+    } else {
+      state?.open(true);
+    }
+  }, [state]);
+  // Hovering the tooltip keeps it open, so it can be read at magnification
+  // (WCAG 1.4.13). react-aria does that by re-opening on hover, which fails
+  // when the tooltip is portalled into a container a modal has marked inert:
+  // it is painted but can never be the target of a mouse event. Pointer
+  // geometry works either way — open() clears the pending close.
+  //
+  // Leaving the tooltip has to close it here too. The trigger's own hover-end
+  // fired long ago, when the pointer set off across the gap, so nothing else
+  // will. Not while the trigger is hovered or focused, though: those are
+  // react-aria's own reasons to be open, and it will close on its own terms.
+  const isOpen = state?.isOpen;
+  useEffect(() => {
+    if (!isOpen) {
+      return;
+    }
+    const listener = (e: MouseEvent) => {
+      const rect = document
+        .getElementById(tooltipBodyId)
+        ?.closest('[role="tooltip"]')
+        ?.getBoundingClientRect();
+      const onTooltip =
+        !!rect &&
+        e.clientX >= rect.left - pointerMarginPx &&
+        e.clientX <= rect.right + pointerMarginPx &&
+        e.clientY >= rect.top - pointerMarginPx &&
+        e.clientY <= rect.bottom + pointerMarginPx;
+      if (onTooltip) {
+        state?.open(true);
+      } else if (
+        ref.current !== document.activeElement &&
+        !ref.current?.matches(":hover")
+      ) {
+        state?.close();
+      }
+    };
+    document.addEventListener("mousemove", listener);
+    return () => document.removeEventListener("mousemove", listener);
+  }, [isOpen, state, tooltipBodyId]);
+  return (
+    <Button
+      ref={ref}
+      variant="unstyled"
+      aria-label={ariaLabel}
+      // Without a short name the body is the name; with one it is the
+      // description. react-aria overwrites aria-describedby with the visible
+      // tooltip's id while open, and that copy is aria-hidden so announces
+      // nothing; closed — the state a touch screen reader is in — this applies.
+      aria-labelledby={ariaLabel ? undefined : textId}
+      aria-describedby={ariaLabel ? textId : undefined}
+      onPress={handlePress}
+      css={{ ...triggerStyle, ...cssProp }}
+    >
+      {children}
+    </Button>
+  );
+};

package/src/base-preset.ts

@@ -125,6 +125,15 @@ export const basePreset = definePreset({
           background: "var(--skeleton-end-color)",
         },
       },
+      // Toast enter/exit, played on the view-transition snapshots (see the
+      // ::view-transition rules in globalCss). Chakra-ballpark timings: fade
+      // + short slide in, quicker fade + shrink out.
+      toastSlideIn: {
+        from: { opacity: 0, transform: "translateY(-24px)" },
+      },
+      toastSlideOut: {
+        to: { opacity: 0, transform: "scale(0.85)" },
+      },
     },
     tokens: {
       colors: {
@@ -314,6 +323,40 @@ export const basePreset = definePreset({
     "h1, h2, h3, h4, h5, h6": {
       textWrap: "wrap",
     },
+    // While a full-size dialog is open (the Modal stamps data-fullsize on
+    // its overlay), release the scrollbar gutter that react-aria's scroll
+    // lock reserves on the root. The reserved strip is scrollbar chrome to
+    // hit-testing — elementFromPoint returns null there, so clicks fall
+    // through to the root and dismiss the dialog, and controls near the
+    // right edge lose part of their target. With the page fully covered,
+    // the reflow this causes is invisible. !important: react-aria sets the
+    // reservation as a non-important inline style.
+    "html:has([data-fullsize])": {
+      scrollbarGutter: "auto !important",
+    },
+    // Toast enter/exit (the ToastQueue wraps updates in
+    // document.startViewTransition — see Toast.tsx, which also stamps the
+    // scoping class on <html> while its transitions run). Timings sit in
+    // Chakra's ballpark: 0.4s fade+slide in, 0.2s fade+shrink out; the
+    // stack reflow comes from the default group animation. `(*)` +
+    // `:only-child` matches exactly the entering/exiting toast groups: the
+    // root snapshot always has both old and new children, and toasts are
+    // the only named groups during a toast transition. The snapshot
+    // overlay must not eat clicks while a toast animates, hence
+    // pointer-events, scoped likewise.
+    "html.microbit-ui-toast-transition::view-transition": {
+      pointerEvents: "none",
+    },
+    // `both` fill: the snapshots must hold the keyframes' end states for
+    // however long the rest of the transition (e.g. the 0.25s default group
+    // animation) outlives them, or they snap back to full size/opacity for
+    // the remainder.
+    "html.microbit-ui-toast-transition::view-transition-new(*):only-child": {
+      animation: "toastSlideIn 0.4s cubic-bezier(0.4, 0, 0.2, 1) both",
+    },
+    "html.microbit-ui-toast-transition::view-transition-old(*):only-child": {
+      animation: "toastSlideOut 0.2s cubic-bezier(0.4, 0, 1, 1) both",
+    },
   },
   // shared-ui components forward `variant`/`size`/etc. as runtime props to
   // the recipe functions, so Panda's static analysis can't see which variants

package/src/index.ts

@@ -58,6 +58,7 @@ export * from "./Modal";
 export * from "./PopoverArrow";
 export * from "./SharedUIProvider";
 export * from "./Tooltip";
+export * from "./TooltipButton";
 export * from "./Toast";
 export * from "./VisuallyHidden";
 export { useBreakpointValue } from "./hooks/useBreakpointValue";