@microbit/ui 0.1.0-alpha.21 → 0.1.0-alpha.23

package/src/Toast.tsx

@@ -23,12 +23,11 @@ import { toast as toastRecipe } from "styled-system/recipes";
 import { CloseIcon } from "./CloseIcon";
 import { Icon } from "./Icon";
 import { uiMessage } from "./messages";
-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;
@@ -75,11 +74,20 @@ export const toastQueue = new RACToastQueue<ToastContent>({
   wrapUpdate,
 });
 
-// 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
-// don't reliably. The icon is decorative; the status is announced via the
-// visually hidden status text.
+// 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 (filled glyphs, coloured by the toast foreground = white
+// here). Warning is a triangle, error a circle — the glyph must distinguish
+// them because the colours alone don't reliably. The glyph is also what
+// carries the status for assistive tech, via its accessible name (see
+// ToastProvider).
 const statusIcon: Record<ToastStatus, IconType> = {
   info: RiInformationFill,
   success: RiCheckboxCircleFill,
@@ -122,21 +130,24 @@ export const ToastProvider = () => {
             // 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
-                  for assistive tech too. */}
-              <VisuallyHidden>
-                {intl.formatMessage(uiMessage(`ui.toast-status-${status}`))}{" "}
-              </VisuallyHidden>
-              {toast.content.title && (
-                <p className={slots.title}>{toast.content.title}</p>
-              )}
-              {toast.content.description && (
-                <div className={slots.description}>
-                  {toast.content.description}
-                </div>
-              )}
+            <RACToastContent className={slots.content}>
+              <Icon
+                as={statusIcon[status]}
+                className={slots.icon}
+                aria-label={intl.formatMessage(
+                  uiMessage(`ui.toast-status-${status}`),
+                )}
+              />
+              <div className={slots.body}>
+                {toast.content.title && (
+                  <p className={slots.title}>{toast.content.title}</p>
+                )}
+                {toast.content.description && (
+                  <div className={slots.description}>
+                    {toast.content.description}
+                  </div>
+                )}
+              </div>
             </RACToastContent>
             {toast.content.isClosable && (
               <RACButton
@@ -166,26 +177,28 @@ 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. The toast is re-added: 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. */
   closeAll(): void;
 }
 
 /**
- * useToast — imperative toast trigger in the shape of Chakra's `useToast()`
- * call sites: `toast({ title, description, status, duration })`. Unlike
- * Chakra there is no `duration: null`; use `persistent: true` instead.
+ * useToast — imperative toast trigger:
+ * `toast({ title, description, status, duration })`. There is no
+ * `duration: null`; use `persistent: true` instead.
  */
 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,
@@ -198,7 +211,7 @@ export const useToast = (): ToastFn =>
       if (id && isActive(id)) {
         return;
       }
-      toastQueue.add(
+      const key = toastQueue.add(
         {
           id,
           title,
@@ -206,21 +219,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.recipe.ts

@@ -6,17 +6,12 @@
 import { defineRecipe } from "@pandacss/dev";
 
 /**
- * Tooltip recipe — Chakra's dark tooltip.
+ * Tooltip recipe — the dark tooltip.
  *
  * A recipe rather than styles inside the component because tooltip typography
- * is the kind of thing an app sets once for all of them: classroom's Chakra
- * theme did exactly that (`fontSize: md`), and a `css` override at today's
- * call sites would quietly not apply to tomorrow's.
- *
- * The colour, vertical padding and radius are Chakra's exactly. They had
- * drifted (white, `py: 1`, `borderRadius: md`) while this lived inside the
- * component, which classroom's port measured: a 6px radius where Chakra drew
- * 2px. ml-trainer and python-editor pick the correction up too.
+ * is the kind of thing an app sets once for all of them (classroom does,
+ * `fontSize: md`), and a `css` override at today's call sites would quietly
+ * not apply to tomorrow's.
  *
  * Registered in the base preset (base-preset.ts).
  */

package/src/Tooltip.tsx

@@ -12,9 +12,9 @@ import { PopoverArrow } from "./PopoverArrow";
 
 export interface TooltipProps {
   /**
-   * Tooltip body (Chakra's `label`). Not named `content`: Panda extracts
-   * utility-named props with literal values from any JSX component, so a
-   * `content` prop taking a string would emit a broken CSS `content` rule.
+   * Tooltip body. Not named `content`: Panda extracts utility-named props
+   * with literal values from any JSX component, so a `content` prop taking a
+   * string would emit a broken CSS `content` rule.
    */
   label: ReactNode;
   /** A single focusable trigger element (e.g. a Button). */
@@ -40,16 +40,47 @@ 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. 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;
 }
 
 /**
- * Tooltip — react-aria-components TooltipTrigger + Tooltip, styled to match
- * Chakra's dark tooltip. The child must be a focusable element so the tooltip
- * is reachable by keyboard (RAC requirement), unless `triggerRef` provides
- * the anchor and the caller manages open state and keyboard access itself.
+ * Tooltip — react-aria-components TooltipTrigger + Tooltip in the dark
+ * tooltip style. The child must be a focusable element so the tooltip is
+ * reachable by keyboard (RAC requirement), unless `triggerRef` provides the
+ * anchor and the caller manages open state and keyboard access itself.
  */
 export const Tooltip = ({
   label,
@@ -58,10 +89,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,229 @@
+/**
+ * (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;
+ * prefer that direction over 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/UnmountCallback.tsx

@@ -7,8 +7,8 @@ import { useEffect, useRef } from "react";
 
 /**
  * Runs its callback when unmounted. RAC keeps an overlay tree mounted until
- * the exit transition finishes, so mounting this inside a Modal/Drawer gives
- * the equivalent of Chakra's `onCloseComplete`. Internal to shared-ui.
+ * the exit transition finishes, so mounting this inside the overlay
+ * implements Modal/Drawer's `onCloseComplete`. Internal to shared-ui.
  */
 export const UnmountCallback = ({ callback }: { callback?: () => void }) => {
   const ref = useRef(callback);

package/src/VisuallyHidden.tsx

@@ -7,7 +7,7 @@ import { styled } from "styled-system/jsx";
 
 /**
  * VisuallyHidden — screen-reader-only content (Panda's `srOnly` utility).
- * Renders a span like Chakra's; use `as="div"` for block children.
+ * Renders a span; use `as="div"` for block children.
  */
 export const VisuallyHidden = styled("span", {
   base: { srOnly: true },