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

package/src/Toast.recipe.ts

@@ -6,10 +6,9 @@
 import { defineSlotRecipe } from "@pandacss/dev";
 
 /**
- * Toast slot recipe — the Chakra-era solid Alert restyled as a toast (white
- * text, teal for every status except error). Status colours come from the
- * `toast*Bg` semantic tokens so brand presets can retune them without
- * touching the recipe.
+ * Toast slot recipe — a solid alert card with white text, teal for every
+ * status except error. Status colours come from the `toast*Bg` semantic
+ * tokens so brand presets can retune them without touching the recipe.
  *
  * Registered in the base preset (base-preset.ts). The status variant
  * is chosen at runtime from the toast content, so it needs the preset's
@@ -17,13 +16,36 @@ import { defineSlotRecipe } from "@pandacss/dev";
  */
 export const toast = defineSlotRecipe({
   className: "toast",
-  slots: ["region", "root", "icon", "title", "description", "closeButton"],
+  slots: [
+    "region",
+    "root",
+    "content",
+    "body",
+    "icon",
+    "title",
+    "description",
+    "closeButton",
+  ],
   base: {
     region: {
       position: "fixed",
       top: "4",
       left: "50%",
       transform: "translateX(-50%)",
+      // Percentage centring of a text-width region lands the toasts on a
+      // fractional pixel. Chrome floors ::view-transition-group's transform to
+      // a whole CSS pixel, so the snapshot the enter/exit animation displays
+      // sits up to 1px left of the element it stands in for, and every toast
+      // jumps right as the transition hands back to the real DOM (visible
+      // above 1x, where the two no longer round to the same device pixel).
+      // Rounding the region's own offsets keeps it on whole pixels so the two
+      // agree. round() postdates view transitions in Chrome (130 vs 111), so
+      // the guard keeps the plain centring for the versions in between rather
+      // than dropping the declarations and losing it altogether.
+      "@supports (left: round(50%, 1px))": {
+        left: "round(50%, 1px)",
+        transform: "translateX(round(-50%, 1px))",
+      },
       zIndex: "toast",
       display: "flex",
       flexDirection: "column",
@@ -34,7 +56,6 @@ export const toast = defineSlotRecipe({
       position: "relative",
       display: "flex",
       alignItems: "flex-start",
-      gap: "3",
       p: "4",
       // Leave room for the absolutely-positioned close button plus breathing
       // space so its hover area never overlaps the title text (24px button at
@@ -46,6 +67,24 @@ export const toast = defineSlotRecipe({
       color: "white",
       maxW: "sm",
       pointerEvents: "auto",
+      // The card is focusable (RAC gives it tabindex), so it takes the
+      // house ring rather than the UA default. Ink, because the ring is
+      // drawn on the page, not the card — Toast.tsx tags the close button.
+      outline: "none",
+      _focusVisible: { focusRing: "outline" },
+    },
+    // The icon has to be inside the alert region to be announced with the
+    // message, so this row — not the root — is what lays the two out.
+    content: {
+      display: "flex",
+      alignItems: "flex-start",
+      gap: "3",
+      // Let the text shrink below its content width so long words wrap
+      // instead of pushing past the toast's maxW.
+      minWidth: 0,
+    },
+    body: {
+      minWidth: 0,
     },
     icon: {
       fontSize: "1.25rem",
@@ -58,9 +97,8 @@ export const toast = defineSlotRecipe({
       mt: "1",
     },
     closeButton: {
-      // A sized box with the glyph centred (like Chakra's CloseButton size
-      // "sm": 24px box, 2xs glyph) gives padding around the X and a hover
-      // affordance.
+      // A sized box with the glyph centred (24px box, 2xs glyph) gives
+      // padding around the X and a hover affordance.
       position: "absolute",
       top: "1",
       insetEnd: "1",
@@ -79,11 +117,10 @@ export const toast = defineSlotRecipe({
       outline: "none",
       transitionProperty: "background-color, box-shadow",
       transitionDuration: "normal",
-      // Chakra's CloseButton hover is a subtle dark overlay (blackAlpha) in
-      // light mode, not a bright highlight.
+      // Hover is a subtle dark overlay (blackAlpha), not a bright highlight.
       _hover: { bg: "blackAlpha.100" },
       _active: { bg: "blackAlpha.200" },
-      _focusVisible: { focusShadow: "outline" },
+      _focusVisible: { focusRing: "outline" },
     },
   },
   variants: {

package/src/Toast.tsx

@@ -3,7 +3,7 @@
  *
  * SPDX-License-Identifier: MIT
  */
-import { ReactNode, useMemo } from "react";
+import { ReactNode, useMemo, useSyncExternalStore } from "react";
 import {
   Button as RACButton,
   UNSTABLE_Toast as RACToast,
@@ -23,12 +23,12 @@ import { toast as toastRecipe } from "styled-system/recipes";
 import { CloseIcon } from "./CloseIcon";
 import { Icon } from "./Icon";
 import { uiMessage } from "./messages";
-import { VisuallyHidden } from "./VisuallyHidden";
+import { darkSurface } from "./system";
 
 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,18 +36,68 @@ 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);
+    // A transition is routinely skipped — another update starts one while
+    // this is still animating, or the tab is hidden — and the browser then
+    // rejects its promises with "AbortError: Transition was skipped". The
+    // DOM update has still run; only the animation is dropped. Settle on
+    // rejection too (`.finally()` would re-throw, surfacing routine skips
+    // as unhandled rejections in error reporting) and swallow `ready`,
+    // which some engines reject without marking handled.
+    transition.ready.catch(() => {});
+    const settle = () => {
+      if (--activeTransitions === 0) {
+        document.documentElement.classList.remove(TRANSITION_CLASS);
+      }
+    };
+    transition.finished.then(settle, settle);
+  } 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,
 });
 
-// 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,
@@ -55,6 +105,10 @@ const statusIcon: Record<ToastStatus, IconType> = {
   error: RiErrorWarningFill,
 };
 
+// Module scope so useSyncExternalStore doesn't resubscribe every render.
+const subscribeToQueue = (fn: () => void) => toastQueue.subscribe(fn);
+const getVisibleCount = () => toastQueue.visibleToasts.length;
+
 /**
  * Mount once near the app root, inside the IntlProvider (the close button's
  * label and the status announcements are react-intl messages).
@@ -63,32 +117,57 @@ const statusIcon: Record<ToastStatus, IconType> = {
 export const ToastProvider = () => {
   const intl = useIntl();
   const slots = toastRecipe();
+  // The region's landmark label counts the visible toasts, so it has to
+  // track the queue.
+  const count = useSyncExternalStore(
+    subscribeToQueue,
+    getVisibleCount,
+    getVisibleCount,
+  );
   return (
-    <RACToastRegion queue={toastQueue} className={slots.region}>
+    <RACToastRegion
+      queue={toastQueue}
+      aria-label={intl.formatMessage(uiMessage("ui.toast-region"), { count })}
+      className={slots.region}
+    >
       {({ toast }) => {
         const status = toast.content.status ?? "info";
         return (
-          <RACToast toast={toast} className={toastRecipe({ status }).root}>
-            <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>
-              )}
+          <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 }}
+          >
+            <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
                 slot="close"
                 aria-label={intl.formatMessage(uiMessage("ui.close-action"))}
+                // The card is dark at every status, and no app can tag a
+                // surface the package ships. Tagged here, not on the card:
+                // the tag covers the element it sits on, whose own ring is
+                // drawn outside it, on the page.
+                {...darkSurface}
                 className={slots.closeButton}
               >
                 <CloseIcon />
@@ -102,32 +181,39 @@ export const ToastProvider = () => {
 };
 
 export interface ToastOptions extends ToastContent {
+  /** Auto-dismiss after this many ms. Default 5000. Ignored when `persistent`. */
+  duration?: number;
   /**
-   * Auto-dismiss after ms; null means no auto-dismiss (Chakra's semantics).
-   * RAC enforces a 5000ms minimum for accessibility.
+   * Never auto-dismiss. The close button is forced on so the toast is not
+   * permanent and unremovable.
    */
-  duration?: number | null;
+  persistent?: boolean;
 }
 
 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 every toast, queued as well as displayed. */
+  closeAll(): void;
 }
 
 /**
- * useToast — imperative toast trigger matching the shape of Chakra's
- * `useToast()` call sites: `toast({ title, description, status, duration })`.
+ * 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,
@@ -135,31 +221,50 @@ export const useToast = (): ToastFn =>
       status,
       isClosable,
       duration,
+      persistent,
     }: ToastOptions) => {
       if (id && isActive(id)) {
         return;
       }
-      toastQueue.add(
+      const key = toastQueue.add(
         {
           id,
           title,
           description,
           status,
-          // A toast that never times out must be dismissable or it is
-          // permanent and unremovable; force the close button on.
-          isClosable: isClosable || duration == null,
+          isClosable: isClosable || persistent,
+        },
+        {
+          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,
         },
-        { timeout: duration ?? 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 });
     };
-    return Object.assign(add, { isActive, update });
+    // 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 = () => {
+      keysById.clear();
+      toastQueue.clear();
+    };
+    return Object.assign(add, { isActive, update, closeAll });
   }, []);

package/src/Tooltip.recipe.ts

@@ -0,0 +1,32 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import { defineRecipe } from "@pandacss/dev";
+
+/**
+ * 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 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).
+ */
+export const tooltip = defineRecipe({
+  className: "tooltip",
+  base: {
+    bg: "gray.700",
+    color: "whiteAlpha.900",
+    px: "2",
+    py: "0.5",
+    borderRadius: "sm",
+    fontSize: "sm",
+    fontWeight: "medium",
+    boxShadow: "md",
+    maxW: "xs",
+    zIndex: "tooltip",
+  },
+});

package/src/Tooltip.tsx

@@ -5,31 +5,16 @@
  */
 import { ReactElement, ReactNode, RefObject } from "react";
 import { Tooltip as RACTooltip, TooltipTrigger } from "react-aria-components";
-import { css } from "styled-system/css";
+import { css, cx } from "styled-system/css";
+import { tooltip } from "styled-system/recipes";
 import { SystemStyleObject } from "styled-system/types";
 import { PopoverArrow } from "./PopoverArrow";
 
-// Base as an object (not a precomputed class) so a caller's `css` override is
-// merged into a single css() call — Panda then dedupes conflicting utilities
-// (e.g. px/py) so overrides actually win.
-const tooltipBase: SystemStyleObject = {
-  bg: "gray.700",
-  color: "white",
-  px: "2",
-  py: "1",
-  borderRadius: "md",
-  fontSize: "sm",
-  fontWeight: "medium",
-  boxShadow: "md",
-  maxW: "xs",
-  zIndex: "tooltip",
-};
-
 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). */
@@ -55,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,
@@ -73,16 +89,23 @@ 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}
       placement={placement}
       offset={hasArrow ? 8 : 4}
-      className={css({ ...tooltipBase, ...cssProp })}
+      className={cx(tooltip(), cssProp ? css(cssProp) : undefined)}
     >
       {hasArrow && <PopoverArrow css={{ "& svg": { fill: "gray.700" } }} />}
       {label}