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

package/src/Field.tsx

@@ -0,0 +1,187 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import { HTMLAttributes, ReactNode } from "react";
+import {
+  FieldError,
+  Label as RACLabel,
+  LabelProps as RACLabelProps,
+  Text as RACText,
+} from "react-aria-components";
+import { css, cx } from "styled-system/css";
+import { field, FieldVariantProps } from "styled-system/recipes";
+import { SystemStyleObject } from "styled-system/types";
+
+/**
+ * The helper/error chrome every labelled form field shares — TextField,
+ * Select, ComboBox, NumberField, RadioGroup and CheckboxGroup carry the same
+ * props (data-microbit-org's forms attach helper and error text to all of
+ * these).
+ */
+export interface FieldSupportProps {
+  /** Help text below the field. */
+  helperText?: ReactNode;
+  /** Shown below the field when invalid. */
+  errorMessage?: ReactNode;
+  /** Per-instance style overrides for the helper text. */
+  helperTextCss?: SystemStyleObject;
+}
+
+/**
+ * `labelPosition` for the four single-control fields (TextField, NumberField,
+ * Select, ComboBox). Deliberately not on RadioGroup/CheckboxGroup: their roots
+ * carry no layout, and RAC's own `orientation` prop is a different axis there
+ * (it lays out the radios, not the label).
+ */
+export interface FieldLayoutProps {
+  /**
+   * `side` puts the label beside the control — the settings-row pattern. The
+   * label absorbs the free space; the control keeps its own width, so give it
+   * one (`groupCss`, `wrapperCss` or `triggerCss` depending on the field).
+   * Helper and error text drop to a full-width line below the pair.
+   */
+  labelPosition?: FieldVariantProps["labelPosition"];
+}
+
+/**
+ * Helper text and error message for a react-aria field container. Render
+ * inside any RAC component with field validation context (TextField, Select,
+ * ComboBox, NumberField, RadioGroup, CheckboxGroup) — react-aria wires the
+ * description to the input's aria-describedby, and the error renders only
+ * while the field is invalid. Also exported for app-side composites built on
+ * RAC containers.
+ */
+export const FieldSupport = ({
+  helperText,
+  errorMessage,
+  helperTextCss,
+  labelPosition,
+}: FieldSupportProps & FieldLayoutProps) => {
+  const slots = field({ labelPosition });
+  return (
+    <>
+      {helperText != null && (
+        <RACText
+          slot="description"
+          className={cx(
+            slots.helperText,
+            helperTextCss ? css(helperTextCss) : undefined,
+          )}
+        >
+          {helperText}
+        </RACText>
+      )}
+      <FieldError className={slots.errorMessage}>{errorMessage}</FieldError>
+    </>
+  );
+};
+
+interface FieldTextProps extends HTMLAttributes<HTMLDivElement> {
+  children: ReactNode;
+  /** The field's `labelPosition`, so the text lays out to match. */
+  labelPosition?: FieldVariantProps["labelPosition"];
+  /** Per-instance style overrides. */
+  css?: SystemStyleObject;
+}
+
+/**
+ * Context-free helper text for a control react-aria isn't wiring — a native
+ * select or a masked input. Inside a RAC field
+ * container use `FieldSupport`, which wires `aria-describedby` and validation
+ * for free; here the caller owns that wiring: give this an `id` and reference
+ * it from the control's `aria-describedby` (as `NativeSelectField` does).
+ */
+export const FieldHelperText = ({
+  children,
+  labelPosition,
+  css: cssProp,
+  ...rest
+}: FieldTextProps) => (
+  <div
+    {...rest}
+    className={cx(
+      field({ labelPosition }).helperText,
+      cssProp ? css(cssProp) : undefined,
+    )}
+  >
+    {children}
+  </div>
+);
+
+/**
+ * Context-free error message, the counterpart to `FieldHelperText` — see its
+ * note on the wiring the caller owns. RAC's
+ * `FieldError` renders only while its field is invalid; here that decision is
+ * the caller's too: render it conditionally.
+ */
+export const FieldErrorMessage = ({
+  children,
+  labelPosition,
+  css: cssProp,
+  ...rest
+}: FieldTextProps) => (
+  <div
+    {...rest}
+    className={cx(
+      field({ labelPosition }).errorMessage,
+      cssProp ? css(cssProp) : undefined,
+    )}
+  >
+    {children}
+  </div>
+);
+
+/**
+ * The required-field asterisk. Render inside the field's label when
+ * `isRequired`; aria-hidden because react-aria already announces requiredness
+ * from the input itself.
+ */
+export const FieldRequiredIndicator = () => (
+  <span aria-hidden className={field().requiredIndicator}>
+    *
+  </span>
+);
+
+export interface FieldLabelProps
+  extends Omit<RACLabelProps, "className" | "children" | "style"> {
+  children: ReactNode;
+  /** Adds the required asterisk; pass the field's `isRequired`. */
+  isRequired?: boolean;
+  /** The field's `size`, so the label scales with its control. */
+  size?: FieldVariantProps["size"];
+  /** The field's `labelPosition`, so the label lays out to match. */
+  labelPosition?: FieldVariantProps["labelPosition"];
+  /** Per-instance style overrides. */
+  css?: SystemStyleObject;
+}
+
+/**
+ * A field's visible label, asterisk included. Every labelled field in the
+ * library renders its label through this, so the `field` recipe is the single
+ * answer to what a label looks like.
+ *
+ * Also exported for app-side composites: inside a RAC field container the
+ * association is automatic, and outside one (a masked or native input) pass
+ * `id` and `htmlFor` yourself.
+ */
+export const FieldLabel = ({
+  children,
+  isRequired,
+  size,
+  labelPosition,
+  css: cssProp,
+  ...rest
+}: FieldLabelProps) => (
+  <RACLabel
+    {...rest}
+    className={cx(
+      field({ size, labelPosition }).label,
+      cssProp ? css(cssProp) : undefined,
+    )}
+  >
+    {children}
+    {isRequired ? <FieldRequiredIndicator /> : null}
+  </RACLabel>
+);

package/src/GridList.recipe.ts

@@ -0,0 +1,57 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import { defineSlotRecipe } from "@pandacss/dev";
+
+/**
+ * GridList slot recipe — a vertical list of selectable rows, each of which may
+ * hold its own interactive controls (which is what makes it a grid rather than
+ * a listbox: the roving tab index moves through rows, and the controls inside
+ * a row are reachable without leaving it).
+ *
+ * The greys here are the family's neutral list styling; an app with a strong
+ * selection colour restates them (classroom's roster does).
+ *
+ * Registered in the base preset (base-preset.ts), which also has the
+ * `staticCss` entry that keeps the runtime-prop variants generated.
+ */
+export const gridList = defineSlotRecipe({
+  className: "grid-list",
+  slots: ["root", "item"],
+  base: {
+    root: {
+      // The list takes the roving tab index, so it is focusable itself and
+      // would otherwise draw the platform ring around the whole list.
+      outline: "none",
+    },
+    item: {
+      display: "flex",
+      alignItems: "center",
+      position: "relative",
+      // A row is interactive by definition — it selects, or it acts.
+      cursor: "pointer",
+      outline: "none",
+      transitionProperty: "background",
+      transitionDuration: "ultra-fast",
+      transitionTimingFunction: "ease-in",
+      _hover: { bg: "gray.50" },
+      // A row holding an open menu (or any other popover) keeps the hover
+      // grey, so the row an open menu belongs to stays visible. Hover state
+      // cannot do this on its own: a Popover lays a fixed full-viewport
+      // underlay over the page while open, which takes the pointer off the
+      // row — `:hover` and RAC's own `data-hovered` both drop the moment the
+      // menu appears. A trigger carries `aria-expanded` (useOverlayTrigger),
+      // so the row can see its own open overlay.
+      "&:has([aria-expanded=true])": { bg: "gray.50" },
+      "&[data-selected]": {
+        bg: "gray.100",
+        _hover: { bg: "gray.100" },
+        "&:has([aria-expanded=true])": { bg: "gray.100" },
+      },
+      "&[data-focus-visible]": { focusRing: "outline" },
+      "&[data-disabled]": { opacity: 0.4, cursor: "not-allowed" },
+    },
+  },
+});

package/src/GridList.tsx

@@ -0,0 +1,81 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import { ReactNode } from "react";
+import {
+  GridList as RACGridList,
+  GridListItem as RACGridListItem,
+  GridListItemProps as RACGridListItemProps,
+  GridListProps as RACGridListProps,
+} from "react-aria-components";
+import { css, cx } from "styled-system/css";
+import { gridList } from "styled-system/recipes";
+import { SystemStyleObject } from "styled-system/types";
+
+export interface GridListProps<T extends object>
+  extends Omit<RACGridListProps<T>, "className" | "style" | "children"> {
+  /** `GridListItem`s, or a render function when `items` is given. */
+  children: RACGridListProps<T>["children"];
+  /** Per-instance style overrides for the list, merged after the recipe. */
+  css?: SystemStyleObject;
+  className?: string;
+}
+
+/**
+ * GridList — react-aria-components' <GridList>: a list of selectable rows,
+ * each of which may contain its own buttons and menus.
+ *
+ * Reach for it over a `ListBox` when the rows carry controls: a listbox option
+ * is a leaf, so a button inside one is unreachable by keyboard, where a grid
+ * row's contents are part of the grid's navigation.
+ */
+export const GridList = <T extends object>({
+  css: cssProp,
+  className,
+  children,
+  ...rest
+}: GridListProps<T>) => {
+  const slots = gridList();
+  return (
+    <RACGridList
+      {...rest}
+      className={cx(slots.root, cssProp ? css(cssProp) : undefined, className)}
+    >
+      {children}
+    </RACGridList>
+  );
+};
+
+export interface GridListItemProps<T extends object = object>
+  extends Omit<RACGridListItemProps<T>, "className" | "style" | "children"> {
+  children?: ReactNode;
+  /** Per-instance style overrides for the row, merged after the recipe. */
+  css?: SystemStyleObject;
+  className?: string;
+}
+
+/**
+ * A row in a `GridList`. Its children are laid out by the row itself — the
+ * gridcell react-aria puts between them is `display: contents`.
+ *
+ * Give every row a `textValue`: react-aria derives typeahead text from string
+ * children only, and a row is usually a composition rather than a string.
+ */
+export const GridListItem = <T extends object = object>({
+  css: cssProp,
+  className,
+  children,
+  ...rest
+}: GridListItemProps<T>) => {
+  const slots = gridList();
+  return (
+    <RACGridListItem
+      {...rest}
+      className={cx(slots.item, cssProp ? css(cssProp) : undefined, className)}
+    >
+      {children}
+    </RACGridListItem>
+  );
+};

package/src/Heading.recipe.ts

@@ -6,7 +6,7 @@
 import { defineRecipe } from "@pandacss/dev";
 
 /**
- * Heading recipe — Chakra's default Heading base + responsive sizes.
+ * Heading recipe — a bold heading-font base + responsive sizes.
  * A config recipe for the same reasons as `button` (see Button.recipe.ts);
  * the `marketing` variant is token-driven via the `display` font, so brands
  * only override tokens.
@@ -44,6 +44,25 @@ export const heading = defineRecipe({
     // GT Walsheim in the private preset.
     variant: {
       marketing: { fontFamily: "display" },
+      // Page-title chrome in the accent colour (`headingAccent` — see
+      // base-preset.ts). Converged from classroom and data-microbit-org,
+      // which carried these two byte-identically app-side.
+      //
+      // `fontSize` goes through a doubled selector because `size` sets it too,
+      // responsively. Source order can't settle that: Panda hoists media
+      // queries below the base rules and emits variant rules in the order it
+      // meets them, so which of the two wins would depend on the breakpoint
+      // and on what other call sites exist. Two classes beat one at every
+      // width instead.
+      label: {
+        "&&": { fontSize: "4xl" },
+        color: "headingAccent",
+      },
+      subtitle: {
+        "&&": { fontSize: "xl" },
+        fontWeight: "normal",
+        color: "headingAccent",
+      },
     },
   },
   defaultVariants: {

package/src/Heading.tsx

@@ -7,8 +7,8 @@ import { styled } from "styled-system/jsx";
 import { heading } from "styled-system/recipes";
 
 /**
- * Heading — Chakra's <Heading> equivalent, backed by the `heading` config
- * recipe (so the private preset can add brand variants). Defaults to an <h2>;
- * pass `as` to change the element and `size` to pick the type scale.
+ * Heading — a heading backed by the `heading` config recipe (so the private
+ * preset can add brand variants). Defaults to an <h2>; pass `as` to change
+ * the element and `size` to pick the type scale.
  */
 export const Heading = styled("h2", heading);

package/src/Icon.tsx

@@ -3,13 +3,26 @@
  *
  * SPDX-License-Identifier: MIT
  */
-import { IconType } from "react-icons/lib";
+import { ComponentType, SVGProps } from "react";
 import { css, cx } from "styled-system/css";
 import { SystemStyleObject } from "styled-system/types";
 
+/**
+ * Any component that renders an `<svg>` from svg props. Deliberately no
+ * narrower than the props `Icon` actually passes, so it accepts both
+ * react-icons' `IconType` and svgr components (`import X from "./x.svg?react"`,
+ * which the apps use for their custom-path icons).
+ */
+export type IconComponent = ComponentType<
+  Pick<
+    SVGProps<SVGSVGElement>,
+    "className" | "focusable" | "role" | "aria-label" | "aria-hidden"
+  >
+>;
+
 export interface IconProps {
-  /** The react-icons component to render. */
-  as: IconType;
+  /** The icon component to render: a react-icons glyph or an svgr import. */
+  as: IconComponent;
   /** Panda style overrides (size via fontSize/boxSize, colour, etc.). */
   css?: SystemStyleObject;
   className?: string;
@@ -18,10 +31,9 @@ export interface IconProps {
 }
 
 /**
- * Icon — renders a react-icons glyph inline at `1em`, matching Chakra's <Icon>
- * base styles. `fill: currentColor` means the glyph follows the surrounding
- * text colour (set `css={{ color: ... }}` to override), so it inherits colour
- * like Chakra's icons rather than defaulting to black.
+ * Icon — renders a react-icons glyph inline at `1em`. `fill: currentColor`
+ * means the glyph follows the surrounding text colour rather than defaulting
+ * to black (set `css={{ color: ... }}` to override).
  *
  * Unlabelled icons are treated as decorative and hidden from assistive tech;
  * a labelled icon gets `role="img"` (a bare svg aria-label is unreliably
@@ -43,6 +55,10 @@ export const Icon = ({
         lineHeight: "1em",
         flexShrink: 0,
         fill: "currentColor",
+        // Set on the element itself: an inline-block icon sits ~3px off
+        // without it. Don't rely on Panda's preflight happening to set it on
+        // every svg.
+        verticalAlign: "middle",
         ...cssProp,
       }),
       className,

package/src/IconButton.tsx

@@ -7,11 +7,9 @@ import { forwardRef } from "react";
 import { Button, ButtonProps } from "./Button";
 
 export interface IconButtonProps
-  extends Omit<ButtonProps, "leftIcon" | "rightIcon"> {
+  extends Omit<ButtonProps, "startIcon" | "endIcon"> {
   /** Icon-only buttons have no visible label, so this is required. */
   "aria-label": string;
-  /** Circular rather than the recipe's border-radius (Chakra's `isRound`). */
-  isRound?: boolean;
 }
 
 /**
@@ -19,19 +17,16 @@ export interface IconButtonProps
  * padding (its size variants add `px`, which would squeeze a single glyph in a
  * fixed-width button) and keeps the `minW` from the size so the box stays
  * square. Pass the icon as children.
+ *
+ * Circular at every size without asking: the 2rem `button` radius exceeds half
+ * the tallest size (3rem), so CSS clamps it to a full round. Override
+ * `borderRadius` per instance for anything else — an attached group or a
+ * button that sits in a card corner needs per-corner control, not a shape flag.
  */
 export const IconButton = forwardRef<HTMLButtonElement, IconButtonProps>(
-  function IconButton({ isRound, css: cssProp, children, ...rest }, ref) {
+  function IconButton({ css: cssProp, children, ...rest }, ref) {
     return (
-      <Button
-        ref={ref}
-        css={{
-          px: 0,
-          ...(isRound ? { borderRadius: "full" } : {}),
-          ...cssProp,
-        }}
-        {...rest}
-      >
+      <Button ref={ref} css={{ px: 0, ...cssProp }} {...rest}>
         {children}
       </Button>
     );

package/src/Image.tsx

@@ -5,7 +5,7 @@
  */
 import { styled } from "styled-system/jsx";
 
-/** Image — an <img> accepting Panda style props. Replaces Chakra's <Image>. */
+/** Image — an <img> accepting Panda style props. */
 export const Image = styled("img", {
   base: { maxWidth: "100%" },
 });

package/src/Input.recipe.ts

@@ -5,21 +5,22 @@
  */
 import { defineRecipe } from "@pandacss/dev";
 
-// Chakra's transition.property.common, inlined (Panda has no transitionProperty
-// token category).
+// The common transition-property list, inlined (Panda has no
+// transitionProperty token category).
 const transitionCommon =
-  "background-color, border-color, color, fill, stroke, opacity, box-shadow, transform";
+  "background-color, border-color, color, fill, stroke, opacity, transform";
 
 /**
- * Input recipe — Chakra's outline Input field at md size (light mode). Used by
+ * Input recipe — the outline text field with an sm/md/lg size scale. Used by
  * the shared-ui Input and NativeSelect, and by TextField's input slot.
  *
- * Focus matches both native `:focus-visible` (plain inputs; browsers treat any
- * focus in a text field as focus-visible) and react-aria's `data-focused`
- * (inputs inside RAC TextField). Focus is declared after invalid so a focused
- * invalid field shows the focus ring, as in Chakra.
+ * hover < focused < invalid is a specificity ladder (`&&`, `&&&`): Panda
+ * sorts state rules against its own pseudo-class table, not declaration
+ * order, so equal-specificity borderColor ties would leave hover winning.
+ * Variants still override freely (later cascade layer).
  *
- * Registered in the base preset (base-preset.ts).
+ * Registered in the base preset (base-preset.ts), which also has the
+ * `staticCss` entry that keeps the runtime-prop size variants generated.
  */
 export const input = defineRecipe({
   className: "input",
@@ -32,32 +33,44 @@ export const input = defineRecipe({
     font: "inherit",
     transitionProperty: transitionCommon,
     transitionDuration: "normal",
-    fontSize: "md",
-    px: "4",
-    h: "10",
-    borderRadius: "md",
-    border: "1px solid",
-    borderColor: "gray.200",
+    border: "2px solid",
+    // Deliberately below 3:1 — valid while something else visually
+    // identifies the field (label, or a ≥3:1 icon/placeholder).
+    // Checkbox/Radio keep gray.400: their box IS the identifier.
+    // Rationale: ui-private docs/a11y-positions.md.
+    borderColor: "gray.300",
     bg: "inherit",
     color: "inherit",
-    _hover: { borderColor: "gray.300" },
-    "&[data-invalid], &:user-invalid": {
+    _hover: { borderColor: "gray.500" },
+    // Any focus, pointer included; the keyboard ring composes on top.
+    // zIndex so the border — and the ring with it — paint over
+    // attached-group neighbours.
+    "&&:is(:focus, [data-focused])": { zIndex: 1, borderColor: "focusBorder" },
+    "&&&:is([data-invalid], :user-invalid)": {
       borderColor: "danger.500",
-      boxShadow: "0 0 0 1px token(colors.danger.500)",
-    },
-    "&:is(:focus-visible, [data-focused])": {
-      zIndex: 1,
-      borderColor: "focusBorder",
-      boxShadow: "0 0 0 1px token(colors.focusBorder)",
-      // Focus indicator for forced-colors modes, which strip the box-shadow
-      // and force the border colour (the focusShadow utility's technique; the
-      // ring here is the 1px border tint, not an outline* shadow token).
-      outline: "2px solid transparent",
-      outlineOffset: "2px",
     },
+    // Modality-tracked: RAC's attribute, or Input.tsx's. Native
+    // :focus-visible is the fallback for a bare element wearing the recipe,
+    // but not text-entry ones — browsers match it there on a pointer click,
+    // which is what the tracking exists to exclude.
+    "&&&:is([data-focus-visible], :focus-visible:not([data-rac], input, textarea))":
+      {
+        focusRing: "outline",
+      },
     "&:is(:disabled, [data-disabled])": {
       opacity: 0.4,
       cursor: "not-allowed",
     },
   },
+  variants: {
+    // The sm/md/lg size scale.
+    size: {
+      lg: { fontSize: "lg", px: "4", h: "12", borderRadius: "md" },
+      md: { fontSize: "md", px: "4", h: "10", borderRadius: "md" },
+      sm: { fontSize: "sm", px: "3", h: "8", borderRadius: "sm" },
+    },
+  },
+  defaultVariants: {
+    size: "md",
+  },
 });

package/src/Input.tsx

@@ -4,30 +4,46 @@
  * SPDX-License-Identifier: MIT
  */
 import { forwardRef, InputHTMLAttributes } from "react";
+import { mergeProps, useFocusRing } from "react-aria";
 import { css, cx } from "styled-system/css";
-import { input } from "styled-system/recipes";
+import { input, InputVariantProps } from "styled-system/recipes";
 import { SystemStyleObject } from "styled-system/types";
 
 export interface InputProps
-  extends Omit<InputHTMLAttributes<HTMLInputElement>, "className"> {
+  // `size` is the recipe's size scale; the native character-count attribute
+  // it shadows was unused.
+  extends Omit<InputHTMLAttributes<HTMLInputElement>, "className" | "size">,
+    InputVariantProps {
   /** Per-instance style overrides, merged after the recipe. */
   css?: SystemStyleObject;
   className?: string;
 }
 
 /**
- * Input — a native input styled like Chakra's outline Input (md). For a
- * labelled field with help/error text use TextField instead.
+ * Input — a native input in the outline field style. For a labelled field
+ * with help/error text use TextField instead.
  */
 export const Input = forwardRef<HTMLInputElement, InputProps>(function Input(
-  { css: cssProp, className, ...rest },
+  { css: cssProp, className, ...props },
   ref,
 ) {
+  // splitVariantProps, not a hand-picked `size`: an app preset can add variant
+  // groups to the recipe (classroom adds `variant`), and cherry-picking would
+  // silently drop them onto the DOM as unknown attributes instead.
+  const [variantProps, rest] = input.splitVariantProps(props);
+  // A native input never gets RAC's data-focus-visible, which the recipe's
+  // ring keys off — track modality ourselves, as TextField's input does.
+  const { isFocusVisible, focusProps } = useFocusRing({ isTextInput: true });
   return (
     <input
       ref={ref}
-      className={cx(input(), cssProp ? css(cssProp) : undefined, className)}
-      {...rest}
+      data-focus-visible={isFocusVisible || undefined}
+      className={cx(
+        input(variantProps),
+        cssProp ? css(cssProp) : undefined,
+        className,
+      )}
+      {...mergeProps(rest, focusProps)}
     />
   );
 });