@microbit/ui 0.1.0-alpha.3

package/src/PopoverArrow.tsx

@@ -0,0 +1,52 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import { OverlayArrow } from "react-aria-components";
+import { css, cx } from "styled-system/css";
+import { SystemStyleObject } from "styled-system/types";
+
+// react-aria positions the arrow and stamps the resolved side on the wrapper
+// as data-placement, but leaves orienting the glyph to us. The svg is square
+// with the triangle in the half nearest the overlay (tip at centre), so
+// rotating about the centre keeps it flush against the overlay on every side
+// — no translate fix-ups, whose signs depend on rotation direction and are
+// easy to get wrong (they detached the tooltip arrow from its box).
+const arrowBase = css({
+  "& svg": { display: "block" },
+  "&[data-placement='bottom'] svg": { transform: "rotate(180deg)" },
+  "&[data-placement='right'] svg": { transform: "rotate(90deg)" },
+  "&[data-placement='left'] svg": { transform: "rotate(-90deg)" },
+});
+
+export interface PopoverArrowProps {
+  /**
+   * Base width of the visible triangle in px; it protrudes half this into
+   * the gap. Defaults to Chakra's tooltip arrow proportions (an 8px square
+   * rotated 45°).
+   */
+  size?: number;
+  /** Styles merged after the base, e.g. `{ "& svg": { fill: "white" } }`. */
+  css?: SystemStyleObject;
+  className?: string;
+}
+
+/**
+ * PopoverArrow — the notch pointing from a popover or tooltip at its
+ * trigger, oriented automatically for react-aria's resolved placement.
+ * Render inside a RAC Popover/Tooltip; set the fill via the css prop.
+ */
+export const PopoverArrow = ({
+  size = 11.314,
+  css: cssProp,
+  className,
+}: PopoverArrowProps) => (
+  <OverlayArrow
+    className={cx(arrowBase, cssProp ? css(cssProp) : undefined, className)}
+  >
+    <svg width={size} height={size} viewBox="0 0 12 12">
+      <path d="M0 0 L6 6 L12 0" />
+    </svg>
+  </OverlayArrow>
+);

package/src/ProgressBar.tsx

@@ -0,0 +1,61 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import { ProgressBar as RACProgressBar } from "react-aria-components";
+import { css } from "styled-system/css";
+import { SystemStyleObject } from "styled-system/types";
+
+export interface ProgressBarProps {
+  /** 0–100. */
+  value: number;
+  "aria-label": string;
+  /** Track overrides (size, radius, width), merged after the base. */
+  css?: SystemStyleObject;
+  /** Fill overrides (colour), merged after the base. */
+  barCss?: SystemStyleObject;
+}
+
+/**
+ * ProgressBar — react-aria-components <ProgressBar> styled like Chakra's md
+ * Progress (12px gray.100 track). Set the fill colour per call site via
+ * `barCss` (Chakra's colorScheme).
+ */
+export const ProgressBar = ({
+  value,
+  "aria-label": ariaLabel,
+  css: cssProp,
+  barCss,
+}: ProgressBarProps) => (
+  <RACProgressBar
+    value={value}
+    aria-label={ariaLabel}
+    // Single css() calls so caller overrides of base properties (radius, fill
+    // colour) are deduped at merge time rather than racing on stylesheet order.
+    className={css(
+      {
+        width: "100%",
+        height: 3,
+        bg: "gray.100",
+        overflow: "hidden",
+        borderRadius: "sm",
+      },
+      cssProp,
+    )}
+  >
+    {({ percentage }) => (
+      <div
+        className={css(
+          {
+            height: "100%",
+            bg: "progressFilledTrack",
+            transition: "width 0.2s",
+          },
+          barCss,
+        )}
+        style={{ width: `${percentage ?? 0}%` }}
+      />
+    )}
+  </RACProgressBar>
+);

package/src/SharedUIProvider.tsx

@@ -0,0 +1,55 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import { createContext, ReactNode, useContext, useMemo } from "react";
+
+/**
+ * Registers the close function of the currently open dismissable overlay, or
+ * clears it (null) when the overlay closes. Installed by apps that need to
+ * dismiss overlays from outside the component tree — e.g. the Android
+ * hardware back button. Only one overlay is open at a time.
+ */
+export type OverlayCloseRegistrar = (close: (() => void) | null) => void;
+
+interface SharedUIContextValue {
+  overlayCloseRegistrar?: OverlayCloseRegistrar;
+}
+
+const SharedUIContext = createContext<SharedUIContextValue | null>(null);
+
+export interface SharedUIProviderProps {
+  overlayCloseRegistrar?: OverlayCloseRegistrar;
+  children: ReactNode;
+}
+
+/**
+ * SharedUIProvider — the app-side installation point for optional shared-ui
+ * integrations. Currently that is only the overlay-close registrar, so apps
+ * without one can omit the provider entirely. Localized strings come from
+ * react-intl: an IntlProvider must be mounted above shared-ui components
+ * (see the package README for merging this package's message catalogs).
+ */
+export const SharedUIProvider = ({
+  overlayCloseRegistrar,
+  children,
+}: SharedUIProviderProps) => {
+  const value = useMemo(
+    () => ({ overlayCloseRegistrar }),
+    [overlayCloseRegistrar],
+  );
+  return (
+    <SharedUIContext.Provider value={value}>
+      {children}
+    </SharedUIContext.Provider>
+  );
+};
+
+/**
+ * The app-installed overlay-close registrar, if any. Overlay components run
+ * controlled and register their close function while open so the app can
+ * dismiss them; without a registrar they manage open state internally.
+ */
+export const useOverlayCloseRegistrar = (): OverlayCloseRegistrar | undefined =>
+  useContext(SharedUIContext)?.overlayCloseRegistrar;

package/src/Slide.tsx

@@ -0,0 +1,54 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import { ReactNode } from "react";
+import { css, cx } from "styled-system/css";
+import { SystemStyleObject } from "styled-system/types";
+
+export interface SlideProps {
+  /** Slides in when true; sits translated offscreen when false. */
+  isOpen: boolean;
+  /** Per-instance style overrides (e.g. zIndex), merged after the base. */
+  css?: SystemStyleObject;
+  className?: string;
+  children: ReactNode;
+}
+
+/**
+ * Slide — Chakra's Slide transition, bottom edge only (add other directions
+ * when a use appears): a full-width panel pinned to the viewport bottom,
+ * translated offscreen when closed. Content stays mounted throughout, so
+ * closing doesn't drop in-flight state and the exit animates.
+ */
+export const Slide = ({
+  isOpen,
+  css: cssProp,
+  className,
+  children,
+}: SlideProps) => (
+  <div
+    data-open={isOpen ? "" : undefined}
+    className={cx(
+      css(
+        {
+          position: "fixed",
+          left: 0,
+          right: 0,
+          bottom: 0,
+          transform: "translateY(100%)",
+          "&[data-open]": { transform: "translateY(0)" },
+          transitionProperty: "transform",
+          transitionDuration: "0.25s",
+          transitionTimingFunction: "cubic-bezier(0, 0, 0.2, 1)",
+          _motionReduce: { transition: "none" },
+        },
+        cssProp,
+      ),
+      className,
+    )}
+  >
+    {children}
+  </div>
+);

package/src/Slider.recipe.ts

@@ -0,0 +1,91 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import { defineSlotRecipe } from "@pandacss/dev";
+
+/**
+ * Slider slot recipe — Chakra's horizontal md slider (14px thumb, 4px
+ * gray.200 track, blue filled track; light mode). Consumed by the shared-ui
+ * Slider, which maps the slots onto react-aria-components'
+ * Slider/SliderTrack/SliderThumb.
+ *
+ * The `mark` slot is hidden until the slider has focus (Chakra call sites did
+ * this with `_focusWithin` + a class); the reveal lives here so call sites
+ * only style the mark's look.
+ *
+ * Registered in the base preset (base-preset.ts). No variants, so it
+ * needs no `staticCss` entry.
+ */
+export const slider = defineSlotRecipe({
+  className: "slider",
+  slots: ["root", "track", "filledTrack", "thumb", "mark"],
+  base: {
+    root: {
+      position: "relative",
+      display: "block",
+      width: "100%",
+      touchAction: "none",
+      // Half the thumb so it doesn't overflow the ends (Chakra container px).
+      px: "calc(14px / 2)",
+      "&:focus-within [data-part='mark']": {
+        display: "block",
+      },
+      "&[data-disabled]": {
+        opacity: 0.4,
+        cursor: "not-allowed",
+      },
+    },
+    track: {
+      position: "relative",
+      height: "4px",
+      overflow: "hidden",
+      borderRadius: "sm",
+      bg: "gray.200",
+      cursor: "pointer",
+      "[data-disabled] &": {
+        bg: "gray.300",
+        cursor: "default",
+      },
+    },
+    filledTrack: {
+      position: "absolute",
+      top: 0,
+      left: 0,
+      height: "100%",
+      bg: "sliderFilledTrack",
+    },
+    thumb: {
+      position: "absolute",
+      top: "50%",
+      width: "14px",
+      height: "14px",
+      display: "flex",
+      alignItems: "center",
+      justifyContent: "center",
+      outline: "none",
+      zIndex: 1,
+      borderRadius: "full",
+      bg: "white",
+      boxShadow: "base",
+      transitionProperty: "transform",
+      transitionDuration: "normal",
+      "&[data-dragging]": {
+        transform: "translate(-50%, -50%) scale(1.15)",
+      },
+      transform: "translate(-50%, -50%)",
+      "&[data-focus-visible]": {
+        focusShadow: "outline",
+      },
+      "&[data-disabled]": {
+        bg: "gray.300",
+      },
+    },
+    mark: {
+      display: "none",
+      position: "absolute",
+      whiteSpace: "nowrap",
+    },
+  },
+});

package/src/Slider.tsx

@@ -0,0 +1,99 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import { ReactNode } from "react";
+import {
+  Slider as RACSlider,
+  SliderThumb,
+  SliderTrack,
+} from "react-aria-components";
+import { css, cx } from "styled-system/css";
+import { slider } from "styled-system/recipes";
+import { SystemStyleObject } from "styled-system/types";
+
+export interface SliderProps {
+  value: number;
+  onChange: (value: number) => void;
+  minValue?: number;
+  maxValue?: number;
+  "aria-label": string;
+  isDisabled?: boolean;
+  /**
+   * Number format for the value announced to assistive tech (e.g.
+   * `{ style: "unit", unit: "percent" }` so units are heard, not bare
+   * numbers).
+   */
+  formatOptions?: Intl.NumberFormatOptions;
+  /** Per-instance style overrides, merged after the recipe. */
+  css?: SystemStyleObject;
+  trackCss?: SystemStyleObject;
+  filledTrackCss?: SystemStyleObject;
+  thumbCss?: SystemStyleObject;
+  /**
+   * Positioned at the current value along the track and shown while the
+   * slider has focus (Chakra's SliderMark usage).
+   */
+  mark?: ReactNode;
+  markCss?: SystemStyleObject;
+}
+
+/**
+ * Slider — react-aria-components <Slider> styled like Chakra's horizontal md
+ * slider.
+ */
+export const Slider = ({
+  value,
+  onChange,
+  minValue = 0,
+  maxValue = 100,
+  "aria-label": ariaLabel,
+  isDisabled,
+  formatOptions,
+  css: cssProp,
+  trackCss,
+  filledTrackCss,
+  thumbCss,
+  mark,
+  markCss,
+}: SliderProps) => {
+  const slots = slider();
+  const percent = ((value - minValue) / (maxValue - minValue)) * 100;
+  return (
+    <RACSlider
+      value={value}
+      onChange={onChange}
+      minValue={minValue}
+      maxValue={maxValue}
+      aria-label={ariaLabel}
+      isDisabled={isDisabled}
+      formatOptions={formatOptions}
+      className={cx(slots.root, cssProp ? css(cssProp) : undefined)}
+    >
+      {mark && (
+        <div
+          data-part="mark"
+          className={cx(slots.mark, markCss ? css(markCss) : undefined)}
+          style={{ left: `${percent}%` }}
+        >
+          {mark}
+        </div>
+      )}
+      <SliderTrack
+        className={cx(slots.track, trackCss ? css(trackCss) : undefined)}
+      >
+        <div
+          className={cx(
+            slots.filledTrack,
+            filledTrackCss ? css(filledTrackCss) : undefined,
+          )}
+          style={{ width: `${percent}%` }}
+        />
+      </SliderTrack>
+      <SliderThumb
+        className={cx(slots.thumb, thumbCss ? css(thumbCss) : undefined)}
+      />
+    </RACSlider>
+  );
+};

package/src/Spinner.tsx

@@ -0,0 +1,69 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import { CSSProperties } from "react";
+import { css, cx } from "styled-system/css";
+import { SystemStyleObject } from "styled-system/types";
+
+export interface SpinnerProps {
+  /** Chakra Spinner sizes: sm 1rem, md 1.5rem (default). */
+  size?: "sm" | "md";
+  /**
+   * Revolution time (Chakra's `speed`, default 0.45s). Under
+   * prefers-reduced-motion the spin is slowed to ~3x this value.
+   */
+  speed?: string;
+  /** Per-instance style overrides, merged after the base. */
+  css?: SystemStyleObject;
+  className?: string;
+  /**
+   * Accessible name. Required: Chakra's Spinner announced a visually hidden
+   * "Loading..." by default, so a nameless spinner would regress on it.
+   */
+  "aria-label": string;
+}
+
+/**
+ * Spinner — Chakra's border-based spinner (currentColor with transparent
+ * bottom/left quadrants).
+ */
+export const Spinner = ({
+  size = "md",
+  speed,
+  css: cssProp,
+  className,
+  "aria-label": ariaLabel,
+}: SpinnerProps) => (
+  <span
+    role="status"
+    aria-label={ariaLabel}
+    style={speed ? ({ "--spinner-speed": speed } as CSSProperties) : undefined}
+    className={cx(
+      // Single css() call so caller overrides of base properties (e.g. width)
+      // are deduped at merge time rather than racing on stylesheet order.
+      css(
+        {
+          display: "inline-block",
+          borderWidth: "2px",
+          borderStyle: "solid",
+          borderColor: "currentColor",
+          borderBottomColor: "transparent",
+          borderLeftColor: "transparent",
+          borderRadius: "full",
+          // The duration rides a variable so the reduced-motion slow-down
+          // scales with a per-instance `speed` rather than fighting it.
+          animation: "spin var(--spinner-speed, 0.45s) linear infinite",
+          _motionReduce: {
+            animationDuration: "calc(var(--spinner-speed, 0.45s) * 3.33)",
+          },
+          width: size === "sm" ? "1rem" : "1.5rem",
+          height: size === "sm" ? "1rem" : "1.5rem",
+        },
+        cssProp,
+      ),
+      className,
+    )}
+  />
+);

package/src/Svg.tsx

@@ -0,0 +1,23 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import { styled } from "styled-system/jsx";
+
+/**
+ * Svg — a Panda-styled svg element with Chakra Icon's base sizing (1em,
+ * inline-block). For custom-path icons; react-icons glyphs use `Icon`.
+ * As a styled-factory component its call-site style props are extracted
+ * (unlike style props forwarded through a plain wrapper — gotcha #9).
+ */
+export const Svg = styled("svg", {
+  base: {
+    width: "1em",
+    height: "1em",
+    display: "inline-block",
+    lineHeight: "1em",
+    flexShrink: 0,
+    verticalAlign: "middle",
+  },
+});

package/src/Switch.recipe.ts

@@ -0,0 +1,80 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import { defineSlotRecipe } from "@pandacss/dev";
+
+/**
+ * Switch slot recipe — Chakra's md switch with the default blue colorScheme
+ * (light mode). Track is 1.875rem x 1rem with a 2px inset; the thumb slides by
+ * the track/thumb width 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). No variants, so it
+ * needs no `staticCss` entry.
+ */
+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",
+      width: "1.875rem",
+      height: "4",
+      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",
+      width: "4",
+      height: "4",
+      "&[data-selected]": {
+        transform: "translateX(0.875rem)",
+      },
+      _forcedColors: {
+        bg: "ButtonText",
+        "&[data-selected]": { bg: "SelectedItemText" },
+      },
+    },
+    label: {
+      userSelect: "none",
+      marginStart: "2",
+      "&[data-disabled]": { opacity: 0.4 },
+    },
+  },
+});

package/src/Switch.tsx

@@ -0,0 +1,60 @@
+/**
+ * (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 } from "styled-system/recipes";
+import { SystemStyleObject } from "styled-system/types";
+
+export interface SwitchProps
+  extends Omit<RACSwitchProps, "className" | "children" | "style"> {
+  /** 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 md switch.
+ * Children render as the label; pass `aria-label` for label-less switches.
+ */
+export const Switch = ({
+  css: cssProp,
+  className,
+  children,
+  ...rest
+}: SwitchProps) => {
+  const slots = switchRecipe();
+  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.tsx

@@ -0,0 +1,12 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import { styled } from "styled-system/jsx";
+
+/**
+ * Text — a paragraph that accepts Panda style props. Use `as` to render a
+ * different element (`span`, `div`, `h2`). Replaces Chakra's <Text>.
+ */
+export const Text = styled("p");