@microbit/ui 0.1.0-alpha.8 → 0.1.0

package/src/Button.tsx

@@ -4,6 +4,7 @@
  * SPDX-License-Identifier: MIT
  */
 import { forwardRef, ReactNode } from "react";
+import { useIntl } from "react-intl";
 import {
   Button as RACButton,
   ButtonProps as RACButtonProps,
@@ -12,6 +13,33 @@ import { css, cx } from "styled-system/css";
 import { button, ButtonVariantProps } from "styled-system/recipes";
 import { SystemStyleObject } from "styled-system/types";
 import { buttonIcon } from "./button-icon";
+import { uiMessage } from "./messages";
+import { Spinner } from "./Spinner";
+
+// A 1em spinner centred over the hidden label. Out of flow, so the label alone
+// sets the button's size; the recipe's base `position: relative` is what it
+// anchors to. Its own component so useIntl runs only while a button is
+// actually loading — a bare Button must keep working without an IntlProvider
+// (test renders commonly lack one).
+const ButtonSpinner = () => {
+  const intl = useIntl();
+  return (
+    <span
+      className={css({
+        position: "absolute",
+        inset: 0,
+        display: "flex",
+        alignItems: "center",
+        justifyContent: "center",
+      })}
+    >
+      <Spinner
+        aria-label={intl.formatMessage(uiMessage("ui.loading"))}
+        css={{ width: "1em", height: "1em" }}
+      />
+    </span>
+  );
+};
 
 export interface ButtonProps
   extends Omit<RACButtonProps, "className" | "children">,
@@ -19,10 +47,16 @@ export interface ButtonProps
   /** Per-instance style overrides, merged after the recipe. */
   css?: SystemStyleObject;
   className?: string;
-  /** Icon rendered before the label, matching Chakra's `leftIcon`. */
-  leftIcon?: ReactNode;
-  /** Icon rendered after the label, matching Chakra's `rightIcon`. */
-  rightIcon?: ReactNode;
+  /** Icon rendered before the label. */
+  startIcon?: ReactNode;
+  /** Icon rendered after the label. */
+  endIcon?: ReactNode;
+  /**
+   * Show a spinner in place of the label and disable interaction: the label
+   * stays in the layout but invisible, so the button keeps its size, and the
+   * dimmed disabled look applies.
+   */
+  isLoading?: boolean;
   children?: ReactNode;
 }
 
@@ -37,32 +71,51 @@ export const Button = forwardRef<HTMLButtonElement, ButtonProps>(
     {
       variant,
       size,
+      tone,
       css: cssProp,
       className,
-      leftIcon,
-      rightIcon,
+      startIcon,
+      endIcon,
+      isLoading,
       children,
       ...rest
     },
     ref,
   ) {
+    const label = (
+      <>
+        {startIcon ? (
+          <span className={buttonIcon({ side: "start" })}>{startIcon}</span>
+        ) : null}
+        {children}
+        {endIcon ? (
+          <span className={buttonIcon({ side: "end" })}>{endIcon}</span>
+        ) : null}
+      </>
+    );
     return (
       <RACButton
         ref={ref}
         className={cx(
-          button({ variant, size }),
+          button({ variant, size, tone }),
           cssProp ? css(cssProp) : undefined,
           className,
         )}
+        data-loading={isLoading ? "" : undefined}
         {...rest}
+        isDisabled={isLoading || rest.isDisabled}
       >
-        {leftIcon ? (
-          <span className={buttonIcon({ side: "left" })}>{leftIcon}</span>
-        ) : null}
-        {children}
-        {rightIcon ? (
-          <span className={buttonIcon({ side: "right" })}>{rightIcon}</span>
-        ) : null}
+        {isLoading ? (
+          <>
+            <ButtonSpinner />
+            {/* Hidden with opacity, not removed: it keeps the button the size
+                it is when idle, so a row of buttons doesn't reflow. Still in
+                the accessibility tree, so the button keeps its name. */}
+            <span className={css({ opacity: 0 })}>{label}</span>
+          </>
+        ) : (
+          label
+        )}
       </RACButton>
     );
   },

package/src/ButtonGroup.tsx

@@ -9,8 +9,8 @@ import { SystemStyleObject } from "styled-system/types";
 
 export interface ButtonGroupProps extends HTMLAttributes<HTMLDivElement> {
   /**
-   * Square the inner radii so adjacent buttons form one control (Chakra's
-   * `isAttached`). Otherwise buttons get a small gap.
+   * Square the inner radii so adjacent buttons form one control. Otherwise
+   * buttons get a small gap.
    */
   isAttached?: boolean;
   /** Per-instance style overrides. */
@@ -20,36 +20,58 @@ export interface ButtonGroupProps extends HTMLAttributes<HTMLDivElement> {
 
 /**
  * ButtonGroup — lays out related buttons in a row. Works with any button
- * elements (shared-ui or native). Replaces Chakra's ButtonGroup.
+ * elements (shared-ui or native).
+ *
+ * Attached, the buttons divide by a hairline and the group keeps whatever
+ * outline the variant draws round the outside, so a 2px `secondary` reads as
+ * one bordered control with cells inside it rather than three boxes. A
+ * variant with no border of its own (`primary`, `solid`, `neutral`) divides
+ * by a gap in the same place, the surface behind the group showing through —
+ * see the `[data-attached]` rule in base-preset.ts.
  */
 export const ButtonGroup = forwardRef<HTMLDivElement, ButtonGroupProps>(
   function ButtonGroup({ isAttached, css: cssProp, className, ...rest }, ref) {
     return (
       <div
         ref={ref}
+        data-attached={isAttached ? "" : undefined}
         className={cx(
           css({
             display: "inline-flex",
             alignItems: "center",
-            // Buttons are position: relative, so without this an attached
-            // sibling paints over the focused button's focus-ring shadow
-            // (Chakra's Button applied zIndex 1 on focus when grouped).
-            "& > *": { _focus: { zIndex: 1 } },
+            // Buttons are position: relative, so a sibling would paint over
+            // the focused button's ring. Only while it shows: a permanently
+            // raised child would own the seam it shares, so a hover on its
+            // neighbour would stop short of it.
+            "& > *": { _focusVisible: { zIndex: 1 } },
           }),
           isAttached
             ? css({
                 gap: 0,
-                // :first-child/:last-child, not :first-of-type: attached
-                // groups can mix element types (e.g. select + button), and
-                // -of-type matches per element type.
-                "& > *:first-child:not(:last-child)": {
+                // :first-child/:last-child, not -of-type: attached groups can
+                // mix element types (e.g. select + button).
+                //
+                // A hairline whatever the variant's border, which stays as the
+                // group's outline — matching it made a 2px seam read as a gap
+                // (microbit-foundation/ui#22). Both sides of a seam keep a
+                // border and overlap by its width so the two paint as one
+                // line; dropping one instead would move that button's border
+                // box off the cell you see, and `focusRing` is an outline, so
+                // the ring would land on the seam rather than outside it.
+                //
+                // padding-box so a fill doesn't paint under the transparent
+                // seam a borderless variant gets from the preset. Here rather
+                // than with that rule because `bg` is the `background`
+                // shorthand, which resets it from `recipes`.
+                "& > *": { backgroundClip: "padding-box" },
+                "& > *:not(:last-child)": {
                   borderEndRadius: 0,
+                  borderInlineEndWidth: "1px",
                 },
-                "& > *:not(:first-child):not(:last-child)": {
-                  borderRadius: 0,
-                },
-                "& > *:not(:first-child):last-child": {
+                "& > *:not(:first-child)": {
                   borderStartRadius: 0,
+                  borderInlineStartWidth: "1px",
+                  marginInlineStart: "-1px",
                 },
               })
             : css({ gap: 2 }),

package/src/Card.recipe.ts

@@ -6,8 +6,7 @@
 import { defineSlotRecipe } from "@pandacss/dev";
 
 /**
- * Card slot recipe — Chakra's Card at its default md size (light mode), with
- * the `elevated` (default) and `outline` variants this app uses.
+ * Card slot recipe, with `elevated` (default) and `outline` variants.
  *
  * Registered in the base preset (base-preset.ts); `variant` is
  * forwarded as a runtime prop so the variants are generated via `staticCss`.

package/src/Card.tsx

@@ -16,7 +16,8 @@ export interface CardProps
 }
 
 /**
- * Card — Chakra's <Card> equivalent (md size). Place a CardBody inside.
+ * Card — a container styled with the `card` config recipe (md size). Place a
+ * CardBody inside.
  */
 export const Card = forwardRef<HTMLDivElement, CardProps>(function Card(
   { variant, css: cssProp, className, ...rest },

package/src/Checkbox.recipe.ts

@@ -6,16 +6,15 @@
 import { defineSlotRecipe } from "@pandacss/dev";
 
 /**
- * Checkbox slot recipe — Chakra's md checkbox with the default blue
- * colorScheme (light mode). The control's `borderColor: inherit` picks up a
- * `borderColor` set on the root, matching Chakra's convention for tinting the
- * box from the call site.
+ * Checkbox slot recipe with an sm/md/lg size scale. The control's
+ * `borderColor: inherit` picks up a `borderColor` set on the root, so call
+ * sites can tint the box from there.
  *
  * State styling keys off data attributes stamped on the control by the
  * shared-ui Checkbox (react-aria provides the state via render props).
  *
- * Registered in the base preset (base-preset.ts). No variants, so it
- * needs no `staticCss` entry.
+ * Registered in the base preset (base-preset.ts), which also has the
+ * `staticCss` entry that keeps the runtime-prop size variants generated.
  */
 export const checkbox = defineSlotRecipe({
   className: "checkbox",
@@ -27,6 +26,11 @@ export const checkbox = defineSlotRecipe({
       verticalAlign: "top",
       cursor: "pointer",
       position: "relative",
+      // The accessible outline stop (WCAG 1.4.11), as the input recipe.
+      // Stated here rather than on the control — whose `borderColor:
+      // inherit` reads it — so a call site can still tint the whole control
+      // by setting borderColor on the root.
+      borderColor: "gray.400",
       "&[data-disabled]": { cursor: "not-allowed" },
     },
     control: {
@@ -34,11 +38,8 @@ export const checkbox = defineSlotRecipe({
       alignItems: "center",
       justifyContent: "center",
       flexShrink: 0,
-      width: "4",
-      height: "4",
-      transitionProperty: "box-shadow",
-      transitionDuration: "normal",
-      border: "2px solid",
+      borderWidth: "2px",
+      borderStyle: "solid",
       borderRadius: "sm",
       borderColor: "inherit",
       color: "white",
@@ -52,13 +53,23 @@ export const checkbox = defineSlotRecipe({
           borderColor: "controlCheckedHoverBg",
         },
       },
+      // Disabled greys; the selected block restates _hover so the widened
+      // native-:hover condition can't re-tint a disabled control.
+      "&[data-disabled]": {
+        bg: "gray.100",
+        borderColor: "gray.100",
+      },
+      "&[data-selected][data-disabled]": {
+        bg: "gray.200",
+        borderColor: "gray.200",
+        color: "gray.500",
+        _hover: { bg: "gray.200", borderColor: "gray.200" },
+      },
       "&[data-focus-visible]": {
-        focusShadow: "outline",
+        focusRing: "outline",
       },
     },
     icon: {
-      width: "0.75rem",
-      height: "0.75rem",
       transitionProperty: "transform",
       transitionDuration: "normal",
     },
@@ -68,4 +79,28 @@ export const checkbox = defineSlotRecipe({
       "&[data-disabled]": { opacity: 0.4 },
     },
   },
+  variants: {
+    // The icon dimensions are the 1.2em-wide check glyph at each size's icon
+    // fontSize (3xs/2xs/2xs), resolved to rem.
+    size: {
+      sm: {
+        control: { width: "3", height: "3" },
+        icon: { width: "0.54rem", height: "0.54rem" },
+        label: { fontSize: "sm" },
+      },
+      md: {
+        control: { width: "4", height: "4" },
+        icon: { width: "0.75rem", height: "0.75rem" },
+        label: { fontSize: "md" },
+      },
+      lg: {
+        control: { width: "5", height: "5" },
+        icon: { width: "0.75rem", height: "0.75rem" },
+        label: { fontSize: "lg" },
+      },
+    },
+  },
+  defaultVariants: {
+    size: "md",
+  },
 });

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

@@ -6,7 +6,7 @@
 import { styled } from "styled-system/jsx";
 
 /**
- * Code — inline code chip matching Chakra's <Code> (gray subtle, light mode).
+ * Code — an inline code chip (subtle grey, light mode).
  */
 export const Code = styled("code", {
   base: {