@microbit/ui 0.1.0-alpha.3

package/src/TextField.recipe.ts

@@ -0,0 +1,54 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import { defineSlotRecipe } from "@pandacss/dev";
+
+/**
+ * Field slot recipe — Chakra's FormControl parts (FormLabel/FormHelperText/
+ * FormErrorMessage, light mode). Consumed by the shared-ui TextField, which
+ * maps the slots onto react-aria-components' TextField/Label/Text/FieldError;
+ * the input itself is styled by the `input` recipe (Input.recipe.ts).
+ *
+ * Registered in the base preset (base-preset.ts). No variants, so it
+ * needs no `staticCss` entry.
+ */
+export const field = defineSlotRecipe({
+  className: "field",
+  slots: ["root", "label", "requiredIndicator", "helperText", "errorMessage"],
+  base: {
+    root: {
+      display: "flex",
+      flexDirection: "column",
+      alignItems: "stretch",
+      width: "100%",
+    },
+    label: {
+      display: "block",
+      fontSize: "md",
+      fontWeight: "medium",
+      marginEnd: "3",
+      mb: "2",
+      "&[data-disabled]": { opacity: 0.4 },
+    },
+    requiredIndicator: {
+      marginStart: "1",
+      color: "danger.500",
+    },
+    helperText: {
+      mt: "2",
+      fontSize: "sm",
+      lineHeight: "normal",
+      color: "gray.600",
+    },
+    errorMessage: {
+      display: "flex",
+      alignItems: "center",
+      mt: "2",
+      fontSize: "sm",
+      lineHeight: "normal",
+      color: "danger.500",
+    },
+  },
+});

package/src/TextField.tsx

@@ -0,0 +1,72 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import { FocusEvent, forwardRef, ReactNode } from "react";
+import {
+  FieldError,
+  Input as RACInput,
+  Label as RACLabel,
+  Text as RACText,
+  TextField as RACTextField,
+  TextFieldProps as RACTextFieldProps,
+} from "react-aria-components";
+import { css, cx } from "styled-system/css";
+import { field, input } from "styled-system/recipes";
+import { SystemStyleObject } from "styled-system/types";
+
+export interface TextFieldProps
+  extends Omit<
+    RACTextFieldProps,
+    "className" | "children" | "style" | "onFocus" | "onBlur"
+  > {
+  /** Visible label (Chakra's FormLabel; asterisk added when `isRequired`). */
+  label: ReactNode;
+  /** Help text below the input (Chakra's FormHelperText). */
+  helperText?: ReactNode;
+  /** Shown below the input when `isInvalid` (Chakra's FormErrorMessage). */
+  errorMessage?: ReactNode;
+  /** Per-instance style overrides for the helper text. */
+  helperTextCss?: SystemStyleObject;
+  onFocus?: (e: FocusEvent<HTMLInputElement>) => void;
+}
+
+/**
+ * TextField — a labelled single-line text input, collapsing Chakra's
+ * FormControl/FormLabel/Input/FormHelperText/FormErrorMessage. The ref is
+ * forwarded to the input element.
+ */
+export const TextField = forwardRef<HTMLInputElement, TextFieldProps>(
+  function TextField(
+    { label, helperText, errorMessage, helperTextCss, onFocus, ...rest },
+    ref,
+  ) {
+    const slots = field();
+    return (
+      <RACTextField {...rest} className={slots.root}>
+        <RACLabel className={slots.label}>
+          {label}
+          {rest.isRequired ? (
+            <span aria-hidden className={slots.requiredIndicator}>
+              *
+            </span>
+          ) : null}
+        </RACLabel>
+        <RACInput ref={ref} className={input()} onFocus={onFocus} />
+        {helperText && (
+          <RACText
+            slot="description"
+            className={cx(
+              slots.helperText,
+              helperTextCss ? css(helperTextCss) : undefined,
+            )}
+          >
+            {helperText}
+          </RACText>
+        )}
+        <FieldError className={slots.errorMessage}>{errorMessage}</FieldError>
+      </RACTextField>
+    );
+  },
+);

package/src/Toast.recipe.ts

@@ -0,0 +1,98 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+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.
+ *
+ * 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
+ * `staticCss` entry.
+ */
+export const toast = defineSlotRecipe({
+  className: "toast",
+  slots: ["region", "root", "icon", "title", "description", "closeButton"],
+  base: {
+    region: {
+      position: "fixed",
+      top: "4",
+      left: "50%",
+      transform: "translateX(-50%)",
+      zIndex: "toast",
+      display: "flex",
+      flexDirection: "column",
+      gap: "2",
+      pointerEvents: "none",
+    },
+    root: {
+      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
+      // 4px inset spans ~4-28px from the right; content stops at 40px for a
+      // ~12px gap).
+      paddingRight: "10",
+      borderRadius: "md",
+      boxShadow: "lg",
+      color: "white",
+      maxW: "sm",
+      pointerEvents: "auto",
+    },
+    icon: {
+      fontSize: "1.25rem",
+      flexShrink: 0,
+    },
+    title: {
+      fontWeight: "bold",
+    },
+    description: {
+      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.
+      position: "absolute",
+      top: "1",
+      insetEnd: "1",
+      color: "white",
+      display: "inline-flex",
+      alignItems: "center",
+      justifyContent: "center",
+      width: "6",
+      height: "6",
+      padding: "0",
+      fontSize: "2xs",
+      borderRadius: "md",
+      cursor: "pointer",
+      bg: "transparent",
+      border: "none",
+      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: { bg: "blackAlpha.100" },
+      _active: { bg: "blackAlpha.200" },
+      _focusVisible: { focusShadow: "outline" },
+    },
+  },
+  variants: {
+    status: {
+      info: { root: { bg: "toastInfoBg" } },
+      success: { root: { bg: "toastSuccessBg" } },
+      warning: { root: { bg: "toastWarningBg" } },
+      error: { root: { bg: "toastErrorBg" } },
+    },
+  },
+  defaultVariants: { status: "info" },
+});

package/src/Toast.tsx

@@ -0,0 +1,165 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import { ReactNode, useMemo } from "react";
+import {
+  Button as RACButton,
+  UNSTABLE_Toast as RACToast,
+  UNSTABLE_ToastContent as RACToastContent,
+  UNSTABLE_ToastQueue as RACToastQueue,
+  UNSTABLE_ToastRegion as RACToastRegion,
+} from "react-aria-components";
+import { useIntl } from "react-intl";
+import { IconType } from "react-icons/lib";
+import {
+  RiAlertFill,
+  RiCheckboxCircleFill,
+  RiErrorWarningFill,
+  RiInformationFill,
+} from "react-icons/ri";
+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. */
+  id?: string;
+  title?: ReactNode;
+  description?: ReactNode;
+  status?: ToastStatus;
+  isClosable?: boolean;
+}
+
+// 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,
+});
+
+// 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.
+const statusIcon: Record<ToastStatus, IconType> = {
+  info: RiInformationFill,
+  success: RiCheckboxCircleFill,
+  warning: RiAlertFill,
+  error: RiErrorWarningFill,
+};
+
+/**
+ * Mount once near the app root, inside the IntlProvider (the close button's
+ * label and the status announcements are react-intl messages).
+ * Renders the live region that announces and displays queued toasts.
+ */
+export const ToastProvider = () => {
+  const intl = useIntl();
+  const slots = toastRecipe();
+  return (
+    <RACToastRegion queue={toastQueue} 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>
+              )}
+            </RACToastContent>
+            {toast.content.isClosable && (
+              <RACButton
+                slot="close"
+                aria-label={intl.formatMessage(uiMessage("ui.close-action"))}
+                className={slots.closeButton}
+              >
+                <CloseIcon />
+              </RACButton>
+            )}
+          </RACToast>
+        );
+      }}
+    </RACToastRegion>
+  );
+};
+
+export interface ToastOptions extends ToastContent {
+  /**
+   * Auto-dismiss after ms; null means no auto-dismiss (Chakra's semantics).
+   * RAC enforces a 5000ms minimum for accessibility.
+   */
+  duration?: number | null;
+}
+
+export interface ToastFn {
+  (options: ToastOptions): void;
+  /** Whether a toast with this id is currently visible. */
+  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.
+   */
+  update(id: string, options: ToastOptions): void;
+}
+
+/**
+ * useToast — imperative toast trigger matching the shape of Chakra's
+ * `useToast()` call sites: `toast({ title, description, status, duration })`.
+ */
+export const useToast = (): ToastFn =>
+  useMemo(() => {
+    const isActive = (id: string) =>
+      toastQueue.visibleToasts.some((t) => t.content.id === id);
+    const add = ({
+      id,
+      title,
+      description,
+      status,
+      isClosable,
+      duration,
+    }: ToastOptions) => {
+      if (id && isActive(id)) {
+        return;
+      }
+      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,
+        },
+        { timeout: duration ?? undefined },
+      );
+    };
+    const update = (id: string, options: ToastOptions) => {
+      const existing = toastQueue.visibleToasts.find(
+        (t) => t.content.id === id,
+      );
+      if (existing) {
+        toastQueue.close(existing.key);
+      }
+      add({ ...options, id });
+    };
+    return Object.assign(add, { isActive, update });
+  }, []);

package/src/Tooltip.tsx

@@ -0,0 +1,91 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import { ReactElement, ReactNode, RefObject } from "react";
+import { Tooltip as RACTooltip, TooltipTrigger } from "react-aria-components";
+import { css } from "styled-system/css";
+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.
+   */
+  label: ReactNode;
+  /** A single focusable trigger element (e.g. a Button). */
+  children: ReactElement;
+  placement?:
+    | "top"
+    | "bottom"
+    | "left"
+    | "right"
+    | "top start"
+    | "top end"
+    | "bottom start"
+    | "bottom end"
+    | "left top"
+    | "left bottom"
+    | "right top"
+    | "right bottom";
+  hasArrow?: boolean;
+  /** Controlled open state (otherwise hover/focus driven). */
+  isOpen?: boolean;
+  /**
+   * Anchor element for positioning, when the child cannot register itself as
+   * 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). */
+  delay?: number;
+  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.
+ */
+export const Tooltip = ({
+  label,
+  children,
+  placement = "top",
+  hasArrow,
+  isOpen,
+  triggerRef,
+  delay = 0,
+  css: cssProp,
+}: TooltipProps) => (
+  <TooltipTrigger isOpen={isOpen} delay={delay} closeDelay={0}>
+    {children}
+    <RACTooltip
+      triggerRef={triggerRef}
+      placement={placement}
+      offset={hasArrow ? 8 : 4}
+      className={css({ ...tooltipBase, ...cssProp })}
+    >
+      {hasArrow && <PopoverArrow css={{ "& svg": { fill: "gray.700" } }} />}
+      {label}
+    </RACTooltip>
+  </TooltipTrigger>
+);

package/src/UnmountCallback.tsx

@@ -0,0 +1,18 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+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.
+ */
+export const UnmountCallback = ({ callback }: { callback?: () => void }) => {
+  const ref = useRef(callback);
+  ref.current = callback;
+  useEffect(() => () => ref.current?.(), []);
+  return null;
+};

package/src/VisuallyHidden.tsx

@@ -0,0 +1,14 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+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.
+ */
+export const VisuallyHidden = styled("span", {
+  base: { srOnly: true },
+});