@microbit/ui 0.1.0-alpha.10

package/src/Switch.recipe.ts

@@ -0,0 +1,107 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import { defineSlotRecipe } from "@pandacss/dev";
+
+/**
+ * Switch slot recipe — Chakra's switch with the default blue colorScheme
+ * (light mode) and its sm/md/lg size scale. The track has a 2px inset; the
+ * thumb matches the track height and slides by the track width/height
+ * difference when selected.
+ *
+ * State styling keys off data attributes stamped by the shared-ui Switch
+ * (react-aria provides the state via render props).
+ *
+ * Registered in the base preset (base-preset.ts), which also has the
+ * `staticCss` entry that keeps the runtime-prop size variants generated.
+ */
+export const switchRecipe = defineSlotRecipe({
+  className: "switch",
+  slots: ["root", "track", "thumb", "label"],
+  base: {
+    root: {
+      display: "inline-flex",
+      alignItems: "center",
+      verticalAlign: "top",
+      cursor: "pointer",
+      position: "relative",
+      "&[data-disabled]": { cursor: "not-allowed" },
+    },
+    track: {
+      display: "inline-flex",
+      flexShrink: 0,
+      justifyContent: "flex-start",
+      boxSizing: "content-box",
+      borderRadius: "full",
+      p: "0.5",
+      transitionProperty: "background-color",
+      transitionDuration: "fast",
+      bg: "gray.300",
+      "&[data-selected]": {
+        bg: "controlCheckedBg",
+      },
+      "&[data-focus-visible]": {
+        focusShadow: "outline",
+      },
+      "&[data-disabled]": { opacity: 0.4 },
+      // Forced-colors modes strip author backgrounds, flattening track and
+      // thumb to the same colour; a border keeps the track visible and the
+      // system SelectedItem pair conveys on/off.
+      _forcedColors: {
+        borderWidth: "1px",
+        borderStyle: "solid",
+        "&[data-selected]": { bg: "SelectedItem" },
+      },
+    },
+    thumb: {
+      bg: "white",
+      transitionProperty: "transform",
+      transitionDuration: "normal",
+      borderRadius: "inherit",
+      _forcedColors: {
+        bg: "ButtonText",
+        "&[data-selected]": { bg: "SelectedItemText" },
+      },
+    },
+    label: {
+      userSelect: "none",
+      marginStart: "2",
+      "&[data-disabled]": { opacity: 0.4 },
+    },
+  },
+  variants: {
+    // Chakra's Switch size scale (track width x height; the selected-thumb
+    // translate is the difference between them).
+    size: {
+      sm: {
+        track: { width: "1.375rem", height: "3" },
+        thumb: {
+          width: "3",
+          height: "3",
+          "&[data-selected]": { transform: "translateX(0.625rem)" },
+        },
+      },
+      md: {
+        track: { width: "1.875rem", height: "4" },
+        thumb: {
+          width: "4",
+          height: "4",
+          "&[data-selected]": { transform: "translateX(0.875rem)" },
+        },
+      },
+      lg: {
+        track: { width: "2.875rem", height: "6" },
+        thumb: {
+          width: "6",
+          height: "6",
+          "&[data-selected]": { transform: "translateX(1.375rem)" },
+        },
+      },
+    },
+  },
+  defaultVariants: {
+    size: "md",
+  },
+});

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,89 @@
+/**
+ * (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,
+      size,
+      ...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({ size })}
+          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,171 @@
+/**
+ * (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;
+  /** Dismiss all visible toasts (Chakra's toast.closeAll). */
+  closeAll(): 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 });
+    };
+    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 });
+  }, []);