@microbit/ui 0.1.0-alpha.9 → 0.1.0

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,34 +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 all visible toasts (Chakra's toast.closeAll). */
+  /** 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,
@@ -137,35 +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 });
     };
+    // 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

@@ -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,44 +5,46 @@
  */
 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). */
   children: ReactElement;
+  /**
+   * Which side of the trigger the tooltip prefers. A preference, not a
+   * promise: react-aria flips it at runtime when the tooltip would leave the
+   * viewport, so pick the side that reads right rather than one that dodges
+   * an edge.
+   *
+   * `top`/`bottom` are direction-neutral and suit most tooltips.
+   * `start`/`end` follow reading order and mirror in RTL. `left`/`right` are
+   * screen sides and never mirror — reach for them only when the trigger is
+   * pinned to a physical edge.
+   */
   placement?:
     | "top"
     | "bottom"
+    | "start"
+    | "end"
     | "left"
     | "right"
     | "top start"
     | "top end"
     | "bottom start"
     | "bottom end"
+    | "start top"
+    | "start bottom"
+    | "end top"
+    | "end bottom"
     | "left top"
     | "left bottom"
     | "right top"
@@ -55,16 +57,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 +106,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}