@microbit/ui 0.0.0-gray.ramp.90

package/src/CloseButton.tsx

@@ -0,0 +1,87 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import { ButtonHTMLAttributes, forwardRef } from "react";
+import { css, cx } from "styled-system/css";
+import { SystemStyleObject } from "styled-system/types";
+import { CloseIcon } from "./CloseIcon";
+
+export interface CloseButtonProps
+  extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, "className"> {
+  /** Chakra CloseButton sizes: sm 24px box, md 32px (default). */
+  size?: "sm" | "md";
+  /**
+   * Grow the touch target 8px beyond the visible button on every side via an
+   * ::after overlay.
+   */
+  expandHitArea?: boolean;
+  "aria-label": string;
+  /** Per-instance style overrides, merged after the base. */
+  css?: SystemStyleObject;
+  className?: string;
+}
+
+/**
+ * CloseButton — Chakra's standalone X button. A plain button (not react-aria)
+ * so call sites can extend the hit area with pseudo-elements, which
+ * react-aria's press bounding-rect check would defeat.
+ */
+export const CloseButton = forwardRef<HTMLButtonElement, CloseButtonProps>(
+  function CloseButton(
+    { size = "md", expandHitArea = false, css: cssProp, className, ...rest },
+    ref,
+  ) {
+    return (
+      <button
+        ref={ref}
+        type="button"
+        className={cx(
+          // A single css() call so per-instance overrides of base properties
+          // (e.g. borderRadius) merge rather than racing on stylesheet order.
+          css(
+            {
+              display: "inline-flex",
+              alignItems: "center",
+              justifyContent: "center",
+              flexShrink: 0,
+              position: "relative",
+              cursor: "pointer",
+              bg: "transparent",
+              border: "none",
+              color: "inherit",
+              outline: "none",
+              borderRadius: "md",
+              transitionProperty: "background-color, box-shadow",
+              transitionDuration: "normal",
+              _hover: { bg: "blackAlpha.100" },
+              _active: { bg: "blackAlpha.200" },
+              _focusVisible: { focusShadow: "outline" },
+            },
+            size === "sm"
+              ? { width: "6", height: "6", fontSize: "2xs" }
+              : { width: "8", height: "8", fontSize: "xs" },
+            expandHitArea
+              ? {
+                  _after: {
+                    position: "absolute",
+                    top: -2,
+                    right: -2,
+                    bottom: -2,
+                    left: -2,
+                    content: '""',
+                  },
+                }
+              : undefined,
+            cssProp,
+          ),
+          className,
+        )}
+        {...rest}
+      >
+        <CloseIcon />
+      </button>
+    );
+  },
+);

package/src/CloseIcon.tsx

@@ -0,0 +1,40 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import { css, cx } from "styled-system/css";
+import { SystemStyleObject } from "styled-system/types";
+
+export interface CloseIconProps {
+  css?: SystemStyleObject;
+  className?: string;
+}
+
+/**
+ * CloseIcon — the "✕" glyph used on close buttons (dialogs, toasts). This is
+ * Chakra's exact CloseButton path so the visual matches; sized to `1em` and
+ * `fill: currentColor` like the other icons. Reused wherever a close control
+ * is needed.
+ */
+export const CloseIcon = ({ css: cssProp, className }: CloseIconProps) => (
+  <svg
+    viewBox="0 0 24 24"
+    focusable="false"
+    aria-hidden="true"
+    className={cx(
+      css({
+        width: "1em",
+        height: "1em",
+        display: "inline-block",
+        lineHeight: "1em",
+        flexShrink: 0,
+        fill: "currentColor",
+        ...cssProp,
+      }),
+      className,
+    )}
+  >
+    <path d="M.439,21.44a1.5,1.5,0,0,0,2.122,2.121L11.823,14.3a.25.25,0,0,1,.354,0l9.262,9.263a1.5,1.5,0,1,0,2.122-2.121L14.3,12.177a.25.25,0,0,1,0-.354l9.263-9.262A1.5,1.5,0,0,0,21.439.44L12.177,9.7a.25.25,0,0,1-.354,0L2.561.44A1.5,1.5,0,0,0,.439,2.561L9.7,11.823a.25.25,0,0,1,0,.354Z" />
+  </svg>
+);

package/src/Code.tsx

@@ -0,0 +1,20 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import { styled } from "styled-system/jsx";
+
+/**
+ * Code — inline code chip matching Chakra's <Code> (gray subtle, light mode).
+ */
+export const Code = styled("code", {
+  base: {
+    fontFamily: "mono",
+    fontSize: "sm",
+    px: "0.2em",
+    borderRadius: "sm",
+    bg: "gray.100",
+    color: "gray.800",
+  },
+});

package/src/Collapse.tsx

@@ -0,0 +1,180 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import {
+  CSSProperties,
+  ReactNode,
+  useEffect,
+  useLayoutEffect,
+  useRef,
+  useState,
+} from "react";
+import { css, cx } from "styled-system/css";
+import { SystemStyleObject } from "styled-system/types";
+
+export interface CollapseProps {
+  /** Expanded when true (Chakra's `in`). */
+  isOpen: boolean;
+  /** Height when collapsed (Chakra's `startingHeight`). */
+  startingHeight?: number | string;
+  /**
+   * Height when expanded (Chakra's `endingHeight`; defaults to the measured
+   * content height, tracked with a ResizeObserver so nested expansion works).
+   */
+  endingHeight?: number | string;
+  /** Remove the content from the DOM once the exit transition finishes. */
+  unmountOnExit?: boolean;
+  css?: SystemStyleObject;
+  className?: string;
+  style?: CSSProperties;
+  children: ReactNode;
+}
+
+const toCssSize = (v: number | string) =>
+  typeof v === "number" ? `${v}px` : v;
+
+/**
+ * Collapse — Chakra's Collapse transition without framer-motion: the content
+ * is measured and the wrapper's height (and opacity, when collapsing to zero)
+ * transitions between the collapsed and expanded sizes. Content stays mounted
+ * unless `unmountOnExit` is set.
+ *
+ * As with framer-motion, only `isOpen` changes animate: initial mounts render
+ * at rest, and height corrections (late measurement, content growth) snap —
+ * otherwise a collapse mounted inside an entering view morphs during the
+ * outer animation.
+ */
+export const Collapse = ({
+  isOpen,
+  startingHeight = 0,
+  endingHeight,
+  unmountOnExit = false,
+  css: cssProp,
+  className,
+  style,
+  children,
+}: CollapseProps) => {
+  const contentRef = useRef<HTMLDivElement>(null);
+  const [measuredHeight, setMeasuredHeight] = useState<number>();
+  // For unmountOnExit: stay in the DOM until the exit transition ends.
+  const [present, setPresent] = useState(isOpen);
+  // The state the DOM shows. It follows isOpen from a layout effect so the
+  // transition-enable and the height flip land in the same commit (a
+  // render-time flip detector is unreliable: React can discard renders,
+  // losing the state update while keeping ref mutations).
+  const [displayOpen, setDisplayOpen] = useState(isOpen);
+  const [animating, setAnimating] = useState(false);
+
+  useLayoutEffect(() => {
+    if (isOpen === displayOpen) {
+      return;
+    }
+    if (isOpen) {
+      // Opening: mount (collapsed) first, then flip on the next frame so
+      // the browser has a computed collapsed state to transition from.
+      setPresent(true);
+      const raf = requestAnimationFrame(() => {
+        setAnimating(true);
+        setDisplayOpen(true);
+      });
+      return () => cancelAnimationFrame(raf);
+    }
+    // Closing: enable the transition and flip together, pre-paint.
+    setAnimating(true);
+    setDisplayOpen(false);
+  }, [isOpen, displayOpen]);
+
+  useLayoutEffect(() => {
+    const el = contentRef.current;
+    if (!el || endingHeight !== undefined) {
+      return;
+    }
+    setMeasuredHeight(el.scrollHeight);
+    const observer = new ResizeObserver(() =>
+      setMeasuredHeight(el.scrollHeight),
+    );
+    observer.observe(el);
+    return () => observer.disconnect();
+  }, [endingHeight, present]);
+
+  // Fallback for browsers/edge cases where transitionend doesn't fire.
+  useEffect(() => {
+    if (animating) {
+      const timeout = setTimeout(() => {
+        setAnimating(false);
+        if (!isOpen && unmountOnExit) {
+          setPresent(false);
+        }
+      }, 400);
+      return () => clearTimeout(timeout);
+    }
+  }, [animating, isOpen, unmountOnExit]);
+
+  if (unmountOnExit && !present) {
+    return null;
+  }
+
+  const expanded =
+    endingHeight !== undefined
+      ? toCssSize(endingHeight)
+      : measuredHeight !== undefined
+        ? `${measuredHeight}px`
+        : "auto";
+  const collapsed = toCssSize(startingHeight);
+  const hideWhenCollapsed = collapsed === "0px" || collapsed === "0";
+
+  return (
+    <div
+      onTransitionEnd={(e) => {
+        if (e.propertyName === "height" && e.target === e.currentTarget) {
+          setAnimating(false);
+          if (!isOpen && unmountOnExit) {
+            setPresent(false);
+          }
+        }
+      }}
+      className={cx(
+        css(
+          {
+            overflow: "hidden",
+            display: "block",
+            transitionDuration: "0.25s",
+            transitionTimingFunction: "cubic-bezier(0.4, 0, 0.2, 1)",
+            _motionReduce: { transition: "none" },
+          },
+          cssProp,
+        ),
+        className,
+      )}
+      // Runtime-measured/caller-supplied heights; transitions enabled only
+      // while an isOpen change is in flight.
+      style={{
+        transitionProperty: animating ? "height, opacity" : "none",
+        height: displayOpen ? expanded : collapsed,
+        opacity: displayOpen || !hideWhenCollapsed ? 1 : 0,
+        // At rest fully-collapsed, remove the content from the a11y tree
+        // and tab order, as Chakra did (kept visible while animating so
+        // the exit transition shows).
+        visibility:
+          displayOpen || animating || !hideWhenCollapsed ? undefined : "hidden",
+        ...style,
+      }}
+    >
+      <div
+        ref={contentRef}
+        // flow-root: the measured element must be a block formatting
+        // context, or children's margins collapse through it and
+        // scrollHeight under-measures — the outer (overflow: hidden)
+        // wrapper IS a BFC and needs the full height, so the mismatch
+        // clips the last line of margined content (python-editor's API
+        // docs). Rendering is unchanged: the margins always displayed
+        // inside the outer BFC.
+        className={css({ display: "flow-root" })}
+      >
+        {children}
+      </div>
+    </div>
+  );
+};

package/src/ComboBox.tsx

@@ -0,0 +1,192 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import {
+  ForwardedRef,
+  forwardRef,
+  ReactNode,
+  useLayoutEffect,
+  useRef,
+  useState,
+} from "react";
+import {
+  Button as RACButton,
+  ComboBox as RACComboBox,
+  ComboBoxProps as RACComboBoxProps,
+  Input as RACInput,
+  Label as RACLabel,
+  ListBox as RACListBox,
+  Popover,
+  PopoverProps,
+} from "react-aria-components";
+import { RiArrowDownSLine } from "react-icons/ri";
+import { css, cx } from "styled-system/css";
+import { select, SelectVariantProps } from "styled-system/recipes";
+import { SystemStyleObject } from "styled-system/types";
+import { Icon } from "./Icon";
+import { SelectSlotProvider } from "./Select";
+
+export interface ComboBoxProps<T extends object>
+  extends Omit<RACComboBoxProps<T>, "className" | "children" | "style">,
+    SelectVariantProps {
+  /** Visible label. Use `aria-label` instead where the design has none. */
+  label?: ReactNode;
+  placeholder?: string;
+  /**
+   * Rendered inside the control, before the input — an icon for the current
+   * value, say. A ComboBox's control is a text input, so unlike a Select it
+   * cannot show anything but text for what is chosen; this is the way round
+   * that (react-select did it with a custom `SingleValue`).
+   */
+  startContent?: ReactNode;
+  /** `SelectOption`s. */
+  children: ReactNode;
+  /**
+   * Replaces the chevron; pass `null` for none, which is what a plain
+   * autocomplete wants (react-select's `dropdownIndicator: display none`).
+   */
+  indicator?: ReactNode | null;
+  /**
+   * Shown in place of the list when nothing matches (react-select's
+   * `noOptionsMessage`). Implies `allowsEmptyCollection`, since RAC otherwise
+   * closes the popover the moment the collection empties.
+   */
+  emptyState?: ReactNode;
+  /**
+   * Keep the dropdown shut until this prop is true. For gating on a minimum
+   * query length — react-aria has no `minLength`, and rendering an empty list
+   * still opens an empty card.
+   */
+  isPopoverHidden?: boolean;
+  placement?: PopoverProps["placement"];
+  /**
+   * Cap the dropdown's height (react-select's `maxMenuHeight`). A prop rather
+   * than a `contentCss` rule because RAC writes its own max-height inline
+   * while positioning, which beats any class.
+   */
+  maxHeight?: number;
+  /**
+   * Per-instance overrides for the control — the box around the input, its
+   * `startContent` and its indicator, which is what `Select`'s `css` styles
+   * too. Reach the input itself through the `select` recipe's `value` slot.
+   */
+  css?: SystemStyleObject;
+  /** Per-instance overrides for the dropdown card. */
+  contentCss?: SystemStyleObject;
+  className?: string;
+}
+
+/**
+ * ComboBox — a text input that filters a listbox, for choosing one of a known
+ * set where typing to narrow it down is the point. Use Select where the list
+ * is short enough to just pick from.
+ *
+ * Note the react-select difference this replaces: react-select filtered on
+ * `label` and kept the menu open on selection unless told otherwise, whereas
+ * react-aria filters on each item's `textValue` and closes on selection.
+ */
+const ComboBoxInner = <T extends object>(
+  {
+    label,
+    placeholder,
+    startContent,
+    children,
+    indicator,
+    emptyState,
+    isPopoverHidden,
+    placement = "bottom start",
+    maxHeight,
+    css: cssProp,
+    contentCss,
+    className,
+    ...props
+  }: ComboBoxProps<T>,
+  ref: ForwardedRef<HTMLInputElement>,
+) => {
+  // As Select: forward whatever variant groups the merged recipe has.
+  const [variantProps, rest] = select.splitVariantProps(props);
+  const slots = select(variantProps);
+  // Anchor the card to the whole control, not to the bare input inside it —
+  // otherwise it hangs off the text baseline and is as narrow as the input.
+  const triggerRef = useRef<HTMLDivElement>(null);
+  // RAC's --trigger-width measures the input it anchors a ComboBox to, which
+  // is the control's content box — so a card sized from it is narrower than
+  // the field by the padding and border. Measure the control instead. State
+  // rather than reading the ref at render time: the popover is mounted from
+  // the first render, before the ref is set, and nothing would re-render it.
+  const [triggerWidth, setTriggerWidth] = useState<number>();
+  useLayoutEffect(() => {
+    const el = triggerRef.current;
+    if (!el) {
+      return;
+    }
+    const update = () => setTriggerWidth(el.offsetWidth);
+    update();
+    if (typeof ResizeObserver === "undefined") {
+      return;
+    }
+    const observer = new ResizeObserver(update);
+    observer.observe(el);
+    return () => observer.disconnect();
+  }, []);
+  return (
+    <SelectSlotProvider value={slots}>
+      <RACComboBox
+        allowsEmptyCollection={emptyState != null}
+        {...(rest as RACComboBoxProps<T>)}
+        className={cx(slots.root, className)}
+      >
+        {label != null && <RACLabel className={slots.label}>{label}</RACLabel>}
+        <div
+          ref={triggerRef}
+          className={cx(slots.trigger, cssProp ? css(cssProp) : undefined)}
+        >
+          {startContent}
+          <RACInput
+            ref={ref}
+            placeholder={placeholder}
+            className={slots.value}
+          />
+          {indicator !== null && (
+            <RACButton className={slots.indicator}>
+              {indicator ?? <Icon as={RiArrowDownSLine} />}
+            </RACButton>
+          )}
+        </div>
+        {!isPopoverHidden && (
+          <Popover
+            triggerRef={triggerRef}
+            placement={placement}
+            maxHeight={maxHeight}
+            style={triggerWidth ? { width: triggerWidth } : undefined}
+            className={cx(
+              slots.content,
+              contentCss ? css(contentCss) : undefined,
+            )}
+          >
+            <RACListBox
+              className={slots.list}
+              renderEmptyState={
+                emptyState
+                  ? () => <div className={slots.empty}>{emptyState}</div>
+                  : undefined
+              }
+            >
+              {children}
+            </RACListBox>
+          </Popover>
+        )}
+      </RACComboBox>
+    </SelectSlotProvider>
+  );
+};
+
+/**
+ * forwardRef with generics needs the cast (React's types cannot express it),
+ * so the ref lands on the input — call sites focus it for validation.
+ */
+export const ComboBox = forwardRef(ComboBoxInner) as <T extends object>(
+  props: ComboBoxProps<T> & { ref?: ForwardedRef<HTMLInputElement> },
+) => ReturnType<typeof ComboBoxInner>;

package/src/Divider.tsx

@@ -0,0 +1,85 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import { ComponentProps, forwardRef } from "react";
+import { styled } from "styled-system/jsx";
+
+const StyledDivider = styled("hr", {
+  base: {
+    border: 0,
+    borderColor: "gray.200",
+    opacity: 0.6,
+  },
+  variants: {
+    orientation: {
+      horizontal: {
+        borderBottomStyle: "solid",
+        width: "100%",
+      },
+      vertical: {
+        borderLeftStyle: "solid",
+        height: "100%",
+      },
+    },
+    // Rule weight, on the orientation's drawn edge (see compoundVariants).
+    // Semantic rather than a raw border width so call sites don't need to
+    // know which edge an orientation draws with.
+    thickness: {
+      thin: {},
+      thick: {},
+    },
+  },
+  compoundVariants: [
+    {
+      orientation: "horizontal",
+      thickness: "thin",
+      css: { borderBottomWidth: "1px" },
+    },
+    {
+      orientation: "horizontal",
+      thickness: "thick",
+      css: { borderBottomWidth: "2px" },
+    },
+    {
+      orientation: "vertical",
+      thickness: "thin",
+      css: { borderLeftWidth: "1px" },
+    },
+    {
+      orientation: "vertical",
+      thickness: "thick",
+      css: { borderLeftWidth: "2px" },
+    },
+  ],
+  defaultVariants: { orientation: "horizontal", thickness: "thin" },
+});
+
+export interface DividerProps extends ComponentProps<typeof StyledDivider> {}
+
+/**
+ * Divider — a hairline rule matching Chakra's <Divider> (60% opacity; set
+ * `borderColor` to tint, `thickness="thick"` for a 2px rule).
+ * `orientation="vertical"` needs a height from the layout, e.g. a stretched
+ * flex row (Chakra's vertical divider likewise relied on `height: 100%`).
+ *
+ * Decorative by default: hidden from assistive tech, since a visual rule
+ * between sections is noise as an announced separator (and every call site
+ * was opting out by hand). Pass `aria-hidden={false}` for a divider that
+ * should be exposed as a semantic separator.
+ */
+export const Divider = forwardRef<HTMLHRElement, DividerProps>(
+  function Divider(props, ref) {
+    return (
+      <StyledDivider
+        ref={ref}
+        aria-hidden
+        aria-orientation={
+          props.orientation === "vertical" ? "vertical" : "horizontal"
+        }
+        {...props}
+      />
+    );
+  },
+);

package/src/Drawer.recipe.ts

@@ -0,0 +1,98 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import { defineSlotRecipe } from "@pandacss/dev";
+
+/**
+ * Drawer slot recipe — Chakra's default Drawer parts (light mode) at its
+ * default `xs` size (20rem panel). Consumed by the shared-ui Drawer, which maps
+ * the slots onto react-aria-components' ModalOverlay / Modal / Dialog.
+ *
+ * The enter transition approximates Chakra's slide spring (damping 25,
+ * stiffness 180) with a decelerating tween; exit matches its 0.15s ease-in-out
+ * tween.
+ *
+ * Registered in the base preset (base-preset.ts); `placement` is
+ * forwarded as a runtime prop so the variants are generated via `staticCss`.
+ */
+export const drawer = defineSlotRecipe({
+  className: "drawer",
+  slots: ["overlay", "content", "inner", "header", "body"],
+  base: {
+    overlay: {
+      position: "fixed",
+      inset: 0,
+      w: "100%",
+      h: "100%",
+      bg: "blackAlpha.600",
+      zIndex: "modal",
+      opacity: 1,
+      transition: "opacity 0.2s ease-out",
+      "&[data-entering]": { opacity: 0 },
+      "&[data-exiting]": { opacity: 0 },
+      _motionReduce: { transition: "none" },
+    },
+    content: {
+      position: "fixed",
+      top: 0,
+      bottom: 0,
+      width: "100%",
+      maxWidth: "xs",
+      maxH: "100dvh",
+      color: "inherit",
+      bg: "white",
+      boxShadow: "lg",
+      display: "flex",
+      flexDirection: "column",
+      outline: "none",
+      zIndex: "modal",
+      transform: "translateX(0)",
+      transition: "transform 0.3s cubic-bezier(0, 0, 0.2, 1)",
+      "&[data-exiting]": {
+        transition: "transform 0.15s cubic-bezier(0.4, 0, 0.2, 1)",
+      },
+      _motionReduce: { transition: "none" },
+    },
+    inner: {
+      outline: "none",
+      display: "flex",
+      flexDirection: "column",
+      width: "100%",
+      height: "100%",
+    },
+    header: {
+      px: "6",
+      py: "4",
+      fontSize: "xl",
+      fontWeight: "semibold",
+      flexShrink: 0,
+    },
+    body: {
+      px: "6",
+      py: "2",
+      flex: "1",
+      overflow: "auto",
+    },
+  },
+  variants: {
+    placement: {
+      left: {
+        content: {
+          left: 0,
+          "&[data-entering]": { transform: "translateX(-100%)" },
+          "&[data-exiting]": { transform: "translateX(-100%)" },
+        },
+      },
+      right: {
+        content: {
+          right: 0,
+          "&[data-entering]": { transform: "translateX(100%)" },
+          "&[data-exiting]": { transform: "translateX(100%)" },
+        },
+      },
+    },
+  },
+  defaultVariants: { placement: "left" },
+});