@microbit/ui 0.0.0-gray.ramp.90

package/src/Switch.tsx

@@ -0,0 +1,62 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import { ReactNode } from "react";
+import {
+  Switch as RACSwitch,
+  SwitchProps as RACSwitchProps,
+} from "react-aria-components";
+import { css, cx } from "styled-system/css";
+import { switchRecipe, SwitchRecipeVariantProps } from "styled-system/recipes";
+import { SystemStyleObject } from "styled-system/types";
+
+export interface SwitchProps
+  extends Omit<RACSwitchProps, "className" | "children" | "style">,
+    SwitchRecipeVariantProps {
+  /** Per-instance style overrides for the root, merged after the recipe. */
+  css?: SystemStyleObject;
+  className?: string;
+  children?: ReactNode;
+}
+
+/**
+ * Switch — react-aria-components <Switch> styled like Chakra's switch.
+ * Children render as the label; pass `aria-label` for label-less switches.
+ */
+export const Switch = ({
+  size,
+  css: cssProp,
+  className,
+  children,
+  ...rest
+}: SwitchProps) => {
+  const slots = switchRecipe({ size });
+  return (
+    <RACSwitch
+      className={cx(slots.root, cssProp ? css(cssProp) : undefined, className)}
+      {...rest}
+    >
+      {({ isSelected, isFocusVisible, isDisabled }) => {
+        const state = {
+          "data-selected": isSelected || undefined,
+          "data-focus-visible": isFocusVisible || undefined,
+          "data-disabled": isDisabled || undefined,
+        };
+        return (
+          <>
+            <span className={slots.track} {...state} aria-hidden>
+              <span className={slots.thumb} {...state} />
+            </span>
+            {children != null && (
+              <span className={slots.label} {...state}>
+                {children}
+              </span>
+            )}
+          </>
+        );
+      }}
+    </RACSwitch>
+  );
+};

package/src/Text.recipe.ts

@@ -0,0 +1,29 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import { defineRecipe } from "@pandacss/dev";
+
+/**
+ * Text recipe — Chakra's <Text> had no styles of its own, but an app theme
+ * could give it sizes and a default size via `components.Text`
+ * (python-editor's did: sm/md with a default of md, which its shrunken
+ * fontSize scale renders at 0.9rem). A config recipe so an app preset can
+ * restore that: extend `defaultVariants` to set an app-wide default size.
+ * No default here — with no `size`, Text inherits like Chakra's default,
+ * which is what the other family apps expect.
+ *
+ * Registered in the base preset (base-preset.ts).
+ */
+export const text = defineRecipe({
+  className: "text",
+  jsx: ["Text"],
+  variants: {
+    size: {
+      sm: { fontSize: "sm" },
+      md: { fontSize: "md" },
+      lg: { fontSize: "lg" },
+    },
+  },
+});

package/src/Text.tsx

@@ -0,0 +1,16 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import { styled } from "styled-system/jsx";
+import { text } from "styled-system/recipes";
+
+/**
+ * Text — a paragraph that accepts Panda style props. Use `as` to render a
+ * different element (`span`, `div`, `h2`). Replaces Chakra's <Text>.
+ * Backed by the `text` config recipe: `size` picks a type-scale size, and an
+ * app preset can extend the recipe's `defaultVariants` to give all its Text
+ * a default size (Chakra `components.Text` parity — see Text.recipe.ts).
+ */
+export const Text = styled("p", text);

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,91 @@
+/**
+ * (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, InputVariantProps } from "styled-system/recipes";
+import { SystemStyleObject } from "styled-system/types";
+
+export interface TextFieldProps
+  extends Omit<
+      RACTextFieldProps,
+      "className" | "children" | "style" | "onFocus" | "onBlur"
+    >,
+    InputVariantProps {
+  /** 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;
+  /** Input autocapitalize attribute (react-aria's TextField omits it). */
+  autoCapitalize?: "off" | "none" | "on" | "sentences" | "words" | "characters";
+}
+
+/**
+ * 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,
+      autoCapitalize,
+      ...props
+    },
+    ref,
+  ) {
+    // As Input: forward every recipe variant group, not just `size`, so a
+    // preset that adds one keeps working.
+    const [variantProps, rest] = input.splitVariantProps(props);
+    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(variantProps)}
+          onFocus={onFocus}
+          autoCapitalize={autoCapitalize}
+        />
+        {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,173 @@
+/**
+ * (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 this many ms. Default 5000. Ignored when `persistent`. */
+  duration?: number;
+  /**
+   * Never auto-dismiss. The close button is forced on so the toast is not
+   * permanent and unremovable.
+   */
+  persistent?: boolean;
+}
+
+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;
+  /** Dismiss all visible toasts (Chakra's toast.closeAll). */
+  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.
+ */
+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,
+      persistent,
+    }: ToastOptions) => {
+      if (id && isActive(id)) {
+        return;
+      }
+      toastQueue.add(
+        {
+          id,
+          title,
+          description,
+          status,
+          isClosable: isClosable || persistent,
+        },
+        { timeout: persistent ? undefined : duration ?? 5000 },
+      );
+    };
+    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 });
+    };
+    const closeAll = () => {
+      // Copy first: closing mutates visibleToasts as we iterate.
+      [...toastQueue.visibleToasts].forEach((t) => toastQueue.close(t.key));
+    };
+    return Object.assign(add, { isActive, update, closeAll });
+  }, []);

package/src/Tooltip.recipe.ts

@@ -0,0 +1,37 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import { defineRecipe } from "@pandacss/dev";
+
+/**
+ * Tooltip recipe — Chakra's 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.
+ *
+ * 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

@@ -0,0 +1,76 @@
+/**
+ * (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, cx } from "styled-system/css";
+import { tooltip } from "styled-system/recipes";
+import { SystemStyleObject } from "styled-system/types";
+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.
+   */
+  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={cx(tooltip(), cssProp ? css(cssProp) : undefined)}
+    >
+      {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 },
+});