@microbit/ui 0.1.0-alpha.3 → 0.1.0-alpha.31

package/src/Checkbox.tsx

@@ -3,64 +3,143 @@
  *
  * SPDX-License-Identifier: MIT
  */
-import { ReactNode } from "react";
+import { ReactNode, useId } from "react";
 import {
   Checkbox as RACCheckbox,
   CheckboxProps as RACCheckboxProps,
 } from "react-aria-components";
+import { useIntl } from "react-intl";
 import { css, cx } from "styled-system/css";
-import { checkbox } from "styled-system/recipes";
+import { checkbox, CheckboxVariantProps } from "styled-system/recipes";
 import { SystemStyleObject } from "styled-system/types";
+import { FieldHelperText } from "./Field";
+import { uiMessage } from "./messages";
+
+/** What a render-prop child is told about the checkbox. */
+export interface CheckboxState {
+  isSelected: boolean;
+  isFocusVisible: boolean;
+  isDisabled: boolean;
+}
 
 export interface CheckboxProps
-  extends Omit<RACCheckboxProps, "className" | "children" | "style"> {
+  extends Omit<RACCheckboxProps, "className" | "children" | "style">,
+    CheckboxVariantProps {
   /** Per-instance style overrides for the root, merged after the recipe. */
   css?: SystemStyleObject;
   className?: string;
-  children?: ReactNode;
+  /**
+   * The label. A function receives the checkbox's state, for a label that
+   * changes with it.
+   */
+  children?: ReactNode | ((state: CheckboxState) => ReactNode);
+  /**
+   * Whether to draw the box. `false` is for a checkbox whose children draw
+   * the selected state themselves — a selectable tile, or an avatar that
+   * grows a tick. The label wrapper goes with it, so the children own the
+   * whole row, including the focus ring the box would otherwise carry.
+   *
+   * @default true
+   */
+  control?: boolean;
+  /**
+   * Help text below the checkbox, wired to its `aria-describedby` — the same
+   * chrome the labelled fields' `helperText` renders. With it the component
+   * gains a wrapping `<div>`, so the checkbox-plus-text moves as one block.
+   */
+  helperText?: ReactNode;
+  /** Per-instance style overrides for the helper text. */
+  helperTextCss?: SystemStyleObject;
 }
 
 /**
- * Checkbox — react-aria-components <Checkbox> styled like Chakra's md
- * checkbox. Children render as the label; wrap them in a visually-hidden
- * span for icon-less checkboxes.
+ * Checkbox — a styled react-aria-components <Checkbox>. Children render as
+ * the label; wrap them in a visually-hidden span for icon-less checkboxes.
  */
 export const Checkbox = ({
+  size,
   css: cssProp,
   className,
   children,
+  control,
+  helperText,
+  helperTextCss,
   ...rest
 }: CheckboxProps) => {
-  const slots = checkbox();
-  return (
+  const slots = checkbox({ size });
+  const helperId = useId();
+  const intl = useIntl();
+  const describedBy =
+    [rest["aria-describedby"], helperText != null ? helperId : undefined]
+      .filter(Boolean)
+      .join(" ") || undefined;
+  // Default name for a row-selection checkbox (a GridList row's). A future
+  // Table's select-all header checkbox shares the slot name and will need a
+  // different label.
+  const ariaLabel =
+    rest["aria-label"] ??
+    (rest.slot === "selection"
+      ? intl.formatMessage(uiMessage("ui.select-row-action"))
+      : undefined);
+  const checkboxElement = (
     <RACCheckbox
       className={cx(slots.root, cssProp ? css(cssProp) : undefined, className)}
       {...rest}
+      aria-label={ariaLabel}
+      aria-describedby={describedBy}
     >
-      {({ isSelected, isFocusVisible }) => (
-        <>
-          <span
-            className={slots.control}
-            data-selected={isSelected || undefined}
-            data-focus-visible={isFocusVisible || undefined}
-            aria-hidden
-          >
-            {isSelected && (
-              <svg viewBox="0 0 12 10" className={slots.icon} aria-hidden>
-                <polyline
-                  points="1.5 6 4.5 9 10.5 1"
-                  fill="none"
-                  stroke="currentColor"
-                  strokeWidth="2"
-                  strokeLinecap="round"
-                  strokeLinejoin="round"
-                />
-              </svg>
+      {({ isSelected, isFocusVisible, isDisabled }) => {
+        const content =
+          typeof children === "function"
+            ? children({ isSelected, isFocusVisible, isDisabled })
+            : children;
+        if (control === false) {
+          return content;
+        }
+        return (
+          <>
+            <span
+              className={slots.control}
+              data-selected={isSelected || undefined}
+              data-focus-visible={isFocusVisible || undefined}
+              data-disabled={isDisabled || undefined}
+              aria-hidden
+            >
+              {isSelected && (
+                <svg viewBox="0 0 12 10" className={slots.icon} aria-hidden>
+                  <polyline
+                    points="1.5 6 4.5 9 10.5 1"
+                    fill="none"
+                    stroke="currentColor"
+                    strokeWidth="2"
+                    strokeLinecap="round"
+                    strokeLinejoin="round"
+                  />
+                </svg>
+              )}
+            </span>
+            {content != null && (
+              <span
+                className={slots.label}
+                data-disabled={isDisabled || undefined}
+              >
+                {content}
+              </span>
             )}
-          </span>
-          {children != null && <span className={slots.label}>{children}</span>}
-        </>
-      )}
+          </>
+        );
+      }}
     </RACCheckbox>
   );
+  if (helperText == null) {
+    return checkboxElement;
+  }
+  return (
+    <div>
+      {checkboxElement}
+      <FieldHelperText id={helperId} css={helperTextCss}>
+        {helperText}
+      </FieldHelperText>
+    </div>
+  );
 };

package/src/CheckboxGroup.tsx

@@ -0,0 +1,70 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import { ReactNode } from "react";
+import {
+  CheckboxGroup as RACCheckboxGroup,
+  CheckboxGroupProps as RACCheckboxGroupProps,
+} from "react-aria-components";
+import { css, cx } from "styled-system/css";
+import { SystemStyleObject } from "styled-system/types";
+import { FieldLabel, FieldSupport, FieldSupportProps } from "./Field";
+
+export interface CheckboxGroupProps
+  extends Omit<RACCheckboxGroupProps, "className" | "style">,
+    FieldSupportProps {
+  /**
+   * Visible label for the group. Use `aria-label` instead where the design
+   * has none.
+   */
+  label?: ReactNode;
+  /** Label style overrides. */
+  labelCss?: SystemStyleObject;
+  /** Per-instance style overrides. */
+  css?: SystemStyleObject;
+  className?: string;
+}
+
+/**
+ * CheckboxGroup — react-aria-components <CheckboxGroup> for a set of
+ * Checkboxes sharing one value array (each Checkbox's `value` marks its
+ * entry). Beyond the optional field chrome (label/helperText/errorMessage)
+ * it carries no styling of its own: compose with Stack for layout, as
+ * RadioGroup does.
+ */
+export const CheckboxGroup = ({
+  label,
+  labelCss,
+  helperText,
+  errorMessage,
+  helperTextCss,
+  css: cssProp,
+  className,
+  children,
+  ...rest
+}: CheckboxGroupProps) => {
+  return (
+    <RACCheckboxGroup
+      className={cx(cssProp ? css(cssProp) : undefined, className)}
+      {...rest}
+    >
+      {(renderProps) => (
+        <>
+          {label != null && (
+            <FieldLabel isRequired={rest.isRequired} css={labelCss}>
+              {label}
+            </FieldLabel>
+          )}
+          {typeof children === "function" ? children(renderProps) : children}
+          <FieldSupport
+            helperText={helperText}
+            errorMessage={errorMessage}
+            helperTextCss={helperTextCss}
+          />
+        </>
+      )}
+    </RACCheckboxGroup>
+  );
+};

package/src/CloseButton.tsx

@@ -10,7 +10,7 @@ import { CloseIcon } from "./CloseIcon";
 
 export interface CloseButtonProps
   extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, "className"> {
-  /** Chakra CloseButton sizes: sm 24px box, md 32px (default). */
+  /** sm is a 24px box, md 32px (default). */
   size?: "sm" | "md";
   /**
    * Grow the touch target 8px beyond the visible button on every side via an
@@ -24,7 +24,7 @@ export interface CloseButtonProps
 }
 
 /**
- * CloseButton — Chakra's standalone X button. A plain button (not react-aria)
+ * CloseButton — a 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.
  */
@@ -57,7 +57,7 @@ export const CloseButton = forwardRef<HTMLButtonElement, CloseButtonProps>(
               transitionDuration: "normal",
               _hover: { bg: "blackAlpha.100" },
               _active: { bg: "blackAlpha.200" },
-              _focusVisible: { focusShadow: "outline" },
+              _focusVisible: { focusRing: "outline" },
             },
             size === "sm"
               ? { width: "6", height: "6", fontSize: "2xs" }

package/src/CloseIcon.tsx

@@ -12,10 +12,12 @@ export interface CloseIconProps {
 }
 
 /**
- * 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.
+ * CloseIcon — the "✕" glyph used on close buttons (dialogs, toasts). Sized to
+ * `1em` and `fill: currentColor` like the other icons. Reused wherever a
+ * close control is needed.
+ *
+ * The path is Chakra UI's CloseButton icon, inlined for visual parity with
+ * the apps' original look (see the notice in LICENSE.md).
  */
 export const CloseIcon = ({ css: cssProp, className }: CloseIconProps) => (
   <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 — an inline code chip (subtle grey, 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,179 @@
+/**
+ * (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. */
+  isOpen: boolean;
+  /** Height when collapsed. */
+  startingHeight?: number | string;
+  /**
+   * Height when expanded (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 — an expand/collapse transition: 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.
+ *
+ * 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 (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>
+  );
+};