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

package/src/ComboBox.tsx

@@ -0,0 +1,246 @@
+/**
+ * (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,
+  ListBox as RACListBox,
+  Popover,
+  PopoverProps,
+} from "react-aria-components";
+import { useFocusVisible } from "react-aria";
+import { useIntl } from "react-intl";
+import { RiArrowDownSLine } from "react-icons/ri";
+import { css, cx } from "styled-system/css";
+import { field, select, SelectVariantProps } from "styled-system/recipes";
+import { SystemStyleObject } from "styled-system/types";
+import {
+  FieldLabel,
+  FieldLayoutProps,
+  FieldSupport,
+  FieldSupportProps,
+} from "./Field";
+import { Icon } from "./Icon";
+import { uiMessage } from "./messages";
+import { SelectSlotProvider } from "./Select";
+
+export interface ComboBoxProps<T extends object>
+  extends Omit<RACComboBoxProps<T>, "className" | "children" | "style">,
+    SelectVariantProps,
+    FieldSupportProps,
+    FieldLayoutProps {
+  /** Visible label. Use `aria-label` instead where the design has none. */
+  label?: ReactNode;
+  /** Label style overrides. */
+  labelCss?: SystemStyleObject;
+  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, or a render function over the `items` prop for a
+   * dynamic collection — which is how an async lookup works: drive `items`
+   * from loaded results (e.g. react-stately's useAsyncList) and filter
+   * server-side; react-aria skips its own text filtering when `items` is
+   * controlled. Pair with `emptyState` (swap its content while loading) and
+   * `isPopoverHidden` for a minimum query length.
+   */
+  children: ReactNode | ((item: T) => 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 trigger — the box around the input, its
+   * `startContent` and its indicator, the same slot `Select`'s `triggerCss`
+   * styles. Reach the input itself through the `select` recipe's `value`
+   * slot.
+   */
+  triggerCss?: 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,
+    labelCss,
+    placeholder,
+    startContent,
+    children,
+    indicator,
+    emptyState,
+    isPopoverHidden,
+    placement = "bottom start",
+    maxHeight,
+    helperText,
+    errorMessage,
+    helperTextCss,
+    labelPosition,
+    triggerCss,
+    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 intl = useIntl();
+  const slots = select(variantProps);
+  const fieldSlots = field({ size: variantProps.size, labelPosition });
+  // 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.
+  // Global modality (text-input key filter): unlike the input's own RAC
+  // attributes, it survives react-aria's synthetic blur during virtual
+  // focus — the select recipe's ring rule pairs it with :has(input:focus).
+  const { isFocusVisible } = useFocusVisible({ isTextInput: true });
+  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(fieldSlots.root, slots.root, className)}
+      >
+        {label != null && (
+          <FieldLabel
+            size={variantProps.size}
+            labelPosition={labelPosition}
+            isRequired={props.isRequired}
+            css={labelCss}
+          >
+            {label}
+          </FieldLabel>
+        )}
+        <div
+          ref={triggerRef}
+          data-keyboard-modality={isFocusVisible || undefined}
+          className={cx(
+            slots.trigger,
+            triggerCss ? css(triggerCss) : undefined,
+          )}
+        >
+          {startContent}
+          <RACInput
+            ref={ref}
+            placeholder={placeholder}
+            className={slots.value}
+          />
+          {indicator !== null && (
+            <RACButton
+              aria-label={intl.formatMessage(uiMessage("ui.combobox-trigger"))}
+              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
+              aria-label={intl.formatMessage(uiMessage("ui.combobox-listbox"))}
+              className={slots.list}
+              renderEmptyState={
+                emptyState
+                  ? () => <div className={slots.empty}>{emptyState}</div>
+                  : undefined
+              }
+            >
+              {children}
+            </RACListBox>
+          </Popover>
+        )}
+        <FieldSupport
+          helperText={helperText}
+          errorMessage={errorMessage}
+          helperTextCss={helperTextCss}
+          labelPosition={labelPosition}
+        />
+      </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

@@ -3,19 +3,83 @@
  *
  * SPDX-License-Identifier: MIT
  */
+import { ComponentProps, forwardRef } from "react";
 import { styled } from "styled-system/jsx";
 
-/**
- * Divider — a horizontal rule matching Chakra's <Divider> (hairline at 60%
- * opacity; set `borderColor` to tint). Horizontal only.
- */
-export const Divider = styled("hr", {
+const StyledDivider = styled("hr", {
   base: {
     border: 0,
-    borderBottomWidth: "1px",
-    borderBottomStyle: "solid",
     borderColor: "gray.200",
     opacity: 0.6,
-    width: "100%",
   },
+  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 (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.
+ *
+ * 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

@@ -6,12 +6,11 @@
 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.
+ * Drawer slot recipe — a 20rem (`xs`) side 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
+ * The enter transition is a decelerating tween; the exit a 0.15s ease-in-out
  * tween.
  *
  * Registered in the base preset (base-preset.ts); `placement` is

package/src/Drawer.tsx

@@ -24,7 +24,7 @@ export interface DrawerProps extends DrawerVariantProps {
   onClose: () => void;
   /**
    * Called after the drawer has fully closed (exit transition done and the
-   * drawer removed). Matches Chakra's `onCloseComplete`.
+   * drawer removed).
    */
   onCloseComplete?: () => void;
   /** Allow closing by clicking the backdrop / pressing Escape (default true). */
@@ -39,9 +39,8 @@ export interface DrawerProps extends DrawerVariantProps {
 }
 
 /**
- * Drawer — a focus-trapping panel that slides in from the side. Collapses
- * Chakra's Drawer/DrawerOverlay/DrawerContent into a single shell; place
- * DrawerHeader and DrawerBody inside.
+ * Drawer — a focus-trapping panel that slides in from the side, in a single
+ * shell; place DrawerHeader and DrawerBody inside.
  */
 export const Drawer = ({
   isOpen,

package/src/ExternalLink.tsx

@@ -0,0 +1,43 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import { ComponentProps } from "react";
+import { RiExternalLinkLine } from "react-icons/ri";
+import { FormattedMessage } from "react-intl";
+import { Icon } from "./Icon";
+import { Link } from "./Link";
+import { uiMessage } from "./messages";
+import { VisuallyHidden } from "./VisuallyHidden";
+
+export type ExternalLinkProps = Omit<
+  ComponentProps<typeof Link>,
+  "target" | "rel"
+>;
+
+/**
+ * ExternalLink — a Link that opens in a new tab and says so both ways: a
+ * trailing external-link glyph for sighted users, and a visually hidden,
+ * translated "opens in a new tab" for assistive tech. Use this rather than
+ * restating `target="_blank"` + icon so the announcement can't be forgotten.
+ *
+ * For app chrome, where a new tab protects the user's session-only state.
+ * Content surfaces should prefer same-tab links, or a visible
+ * "(opens in new tab)" suffix and no icon.
+ *
+ * Inline-safe: the icon is 1em and follows the text colour, so the link can
+ * sit in prose as well as stand alone.
+ */
+export const ExternalLink = ({ children, ...props }: ExternalLinkProps) => (
+  <Link {...props} target="_blank" rel="noopener">
+    {children}
+    <VisuallyHidden>
+      {/* The comma separates the suffix in the accessible name: inline nodes
+          concatenate without a space, and leading whitespace is trimmed. */}
+      {", "}
+      <FormattedMessage {...uiMessage("ui.new-tab-notice")} />
+    </VisuallyHidden>
+    <Icon as={RiExternalLinkLine} aria-hidden css={{ ml: 1 }} />
+  </Link>
+);

package/src/Fade.tsx

@@ -0,0 +1,62 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import { CSSProperties, ReactNode } from "react";
+import { css, cx } from "styled-system/css";
+import { SystemStyleObject } from "styled-system/types";
+
+export interface FadeProps {
+  /** Visible when true; faded out (but mounted) when false. */
+  isOpen: boolean;
+  /** Fade-in time in seconds. Default 0.2. */
+  enterDuration?: number;
+  /** Fade-out time in seconds. Default 0.2. */
+  exitDuration?: number;
+  css?: SystemStyleObject;
+  className?: string;
+  children: ReactNode;
+}
+
+/**
+ * Fade — a CSS opacity transition (see Slide for the pattern). Content stays
+ * mounted throughout.
+ */
+export const Fade = ({
+  isOpen,
+  enterDuration = 0.2,
+  exitDuration = 0.2,
+  css: cssProp,
+  className,
+  children,
+}: FadeProps) => (
+  <div
+    data-open={isOpen ? "" : undefined}
+    // Runtime values, so an inline custom property rather than the css()
+    // object. The var switches in the same commit as the opacity, so the
+    // transition picks up the direction's own duration.
+    style={
+      {
+        "--fade-duration": `${isOpen ? enterDuration : exitDuration}s`,
+      } as CSSProperties
+    }
+    className={cx(
+      css(
+        {
+          opacity: 0,
+          pointerEvents: "none",
+          "&[data-open]": { opacity: 1, pointerEvents: "auto" },
+          transitionProperty: "opacity",
+          transitionDuration: "var(--fade-duration)",
+          transitionTimingFunction: "ease-out",
+          _motionReduce: { transition: "none" },
+        },
+        cssProp,
+      ),
+      className,
+    )}
+  >
+    {children}
+  </div>
+);

package/src/Field.recipe.ts

@@ -0,0 +1,114 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import { defineSlotRecipe } from "@pandacss/dev";
+
+/**
+ * Field slot recipe — the label/helper/error chrome, mapped onto
+ * react-aria-components' Label/Text/FieldError by `FieldLabel` and
+ * `FieldSupport`. Every labelled
+ * field in the library draws its chrome from here, including Select and
+ * ComboBox, whose own recipe styles only the dropdown pair; the input itself is
+ * styled by the `input` recipe (Input.recipe.ts).
+ *
+ * `root` is also the single owner of field-root *layout*: Select, ComboBox and
+ * NumberField wear it alongside their own recipe's root slot, which carries no
+ * layout of its own — two recipes fighting over `flexDirection` would leave
+ * `labelPosition` at the mercy of emission order. RadioGroup and CheckboxGroup
+ * deliberately don't wear it (their roots carry no layout at all).
+ *
+ * Registered in the base preset (base-preset.ts), which also has the
+ * `staticCss` entry that keeps the runtime-prop size variants generated.
+ */
+export const field = defineSlotRecipe({
+  className: "field",
+  slots: ["root", "label", "requiredIndicator", "helperText", "errorMessage"],
+  base: {
+    root: {
+      display: "flex",
+      flexDirection: "column",
+      alignItems: "stretch",
+      width: "100%",
+    },
+    label: {
+      display: "block",
+      fontSize: "md",
+      // Deliberately `normal`, not `medium`: no font in the family's stack
+      // has a 500 face (the two render identically on macOS and Windows),
+      // and the call sites that cared (settings rows) want `normal`.
+      fontWeight: "normal",
+      marginEnd: "3",
+      mb: "2",
+      transitionProperty: "opacity",
+      transitionDuration: "normal",
+      // RAC stamps `data-disabled` on the field root and on the control, never
+      // on the label, so an `&[data-disabled]` rule here matches nothing — it
+      // has to come down from the root. Direct child rather than a
+      // descendant selector, as the select recipe's invalid rule: an app's own
+      // disabled form wrapper must not be able to dim every label inside it.
+      "[data-disabled] > &": { opacity: 0.4 },
+    },
+    requiredIndicator: {
+      marginStart: "1",
+      color: "danger.500",
+    },
+    helperText: {
+      // RAC's Text renders a span, and RadioGroup/CheckboxGroup roots are not
+      // flex containers to blockify it, where an inline box would drop the
+      // margin below.
+      display: "block",
+      mt: "2",
+      fontSize: "sm",
+      lineHeight: "normal",
+      color: "gray.600",
+    },
+    errorMessage: {
+      display: "flex",
+      alignItems: "center",
+      mt: "2",
+      fontSize: "sm",
+      lineHeight: "normal",
+      color: "danger.500",
+    },
+  },
+  variants: {
+    // The label follows its control's size (the control itself is sized by
+    // the `input`/`select` recipes), so one `size` prop scales the whole row.
+    // Helper and error text stay `sm` at every size.
+    size: {
+      lg: { label: { fontSize: "lg" } },
+      md: { label: { fontSize: "md" } },
+      sm: { label: { fontSize: "sm" } },
+    },
+    // `side` puts the label beside its control — the settings-row pattern,
+    // where the label is a preference name and absorbs the free space. The
+    // control keeps its own width; give it one at the call site. Named after
+    // React Spectrum's `labelPosition`, not `orientation`, which RAC's
+    // RadioGroup already uses for the radios' own layout.
+    labelPosition: {
+      top: {},
+      side: {
+        root: {
+          flexDirection: "row",
+          alignItems: "center",
+          // Helper and error text are full-width items, so they wrap to
+          // their own line below the label/control pair.
+          flexWrap: "wrap",
+        },
+        // Basis 0, not auto: the wrap container breaks lines on hypothetical
+        // sizes, and an auto basis is the label's max-content — a long
+        // translated label would push the control onto its own line instead
+        // of wrapping its text beside it.
+        label: { mb: "0", flex: "1 1 0" },
+        helperText: { width: "100%" },
+        errorMessage: { width: "100%" },
+      },
+    },
+  },
+  defaultVariants: {
+    size: "md",
+    labelPosition: "top",
+  },
+});