@microbit/ui 0.1.0-alpha.14 → 0.1.0-alpha.16

package/src/Skeleton.tsx

@@ -0,0 +1,146 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import { HTMLAttributes, ReactNode } from "react";
+import { css, cx } from "styled-system/css";
+import { SystemStyleObject } from "styled-system/types";
+
+/**
+ * The placeholder block, as an object rather than a precomputed class so a
+ * caller's `css` is merged into one `css()` call and its overrides win
+ * (playbook gotcha #8).
+ *
+ * The colours are Chakra's, through the same pair of custom properties, so a
+ * call site can retint one skeleton without knowing how the animation works.
+ */
+const skeletonBase: SystemStyleObject = {
+  "--skeleton-start-color": "token(colors.gray.100)",
+  "--skeleton-end-color": "token(colors.gray.400)",
+  background: "var(--skeleton-start-color)",
+  borderColor: "var(--skeleton-end-color)",
+  opacity: 0.7,
+  borderRadius: "sm",
+  boxShadow: "none",
+  backgroundClip: "padding-box",
+  cursor: "default",
+  color: "transparent",
+  pointerEvents: "none",
+  userSelect: "none",
+  // Chakra hid the content rather than unmounting it, so a skeleton sized
+  // from real children keeps their dimensions.
+  "&::before, &::after, *": { visibility: "hidden" },
+  animation:
+    "skeletonFade var(--skeleton-speed, 0.8s) linear infinite alternate",
+  _motionReduce: { animation: "none" },
+};
+
+export interface SkeletonProps
+  extends Omit<HTMLAttributes<HTMLDivElement>, "color"> {
+  /** Show the children instead of the placeholder. */
+  isLoaded?: boolean;
+  /** Seconds per pulse (Chakra's `speed`, default 0.8). */
+  speed?: number;
+  children?: ReactNode;
+  /** Per-instance style overrides, merged after the base. */
+  css?: SystemStyleObject;
+  className?: string;
+}
+
+/**
+ * Skeleton — Chakra's loading placeholder: a block pulsing between two greys
+ * until its content is ready.
+ *
+ * Chakra faded the real content in over 0.4s when `isLoaded` turned true;
+ * here it simply appears. Wrap in `Fade` where that transition matters.
+ */
+export const Skeleton = ({
+  isLoaded,
+  speed,
+  children,
+  css: cssProp,
+  className,
+  style,
+  ...rest
+}: SkeletonProps) => {
+  if (isLoaded) {
+    return (
+      <div
+        {...rest}
+        style={style}
+        className={cx(cssProp ? css(cssProp) : undefined, className)}
+      >
+        {children}
+      </div>
+    );
+  }
+  return (
+    <div
+      {...rest}
+      style={
+        speed === undefined
+          ? style
+          : ({ ...style, "--skeleton-speed": `${speed}s` } as typeof style)
+      }
+      className={cx(css({ ...skeletonBase, ...cssProp }), className)}
+    >
+      {children}
+    </div>
+  );
+};
+
+export interface SkeletonTextProps extends SkeletonProps {
+  /** How many lines to draw (Chakra's default is 3). */
+  noOfLines?: number;
+  /** Gap between the lines. Any CSS length. */
+  spacing?: string;
+  /** Height of each line. Any CSS length. */
+  skeletonHeight?: string;
+}
+
+/**
+ * SkeletonText — a paragraph-shaped `Skeleton`: evenly spaced lines, the last
+ * one short, as Chakra drew them.
+ */
+export const SkeletonText = ({
+  noOfLines = 3,
+  spacing = "0.5rem",
+  skeletonHeight = "0.5rem",
+  isLoaded,
+  speed,
+  children,
+  css: cssProp,
+  className,
+  ...rest
+}: SkeletonTextProps) => {
+  if (isLoaded) {
+    return (
+      <div
+        {...rest}
+        className={cx(cssProp ? css(cssProp) : undefined, className)}
+      >
+        {children}
+      </div>
+    );
+  }
+  return (
+    <div
+      {...rest}
+      className={cx(cssProp ? css(cssProp) : undefined, className)}
+    >
+      {Array.from({ length: noOfLines }, (_, index) => (
+        <Skeleton
+          key={index}
+          speed={speed}
+          style={{
+            height: skeletonHeight,
+            // Chakra's shape: a last line at 80%, and no gap after it.
+            width: noOfLines > 1 && index === noOfLines - 1 ? "80%" : "100%",
+            marginBottom: index === noOfLines - 1 ? "0" : spacing,
+          }}
+        />
+      ))}
+    </div>
+  );
+};

package/src/Spinner.tsx

@@ -5,6 +5,7 @@
  */
 import { CSSProperties } from "react";
 import { css, cx } from "styled-system/css";
+import { dataAttrs } from "./data-attrs";
 import { SystemStyleObject } from "styled-system/types";
 
 export interface SpinnerProps {
@@ -23,6 +24,8 @@ export interface SpinnerProps {
    * "Loading..." by default, so a nameless spinner would regress on it.
    */
   "aria-label": string;
+  /** `data-*` attributes land on the spinner, for tests that wait on it. */
+  [key: `data-${string}`]: unknown;
 }
 
 /**
@@ -35,8 +38,10 @@ export const Spinner = ({
   css: cssProp,
   className,
   "aria-label": ariaLabel,
+  ...rest
 }: SpinnerProps) => (
   <span
+    {...dataAttrs(rest)}
     role="status"
     aria-label={ariaLabel}
     style={speed ? ({ "--spinner-speed": speed } as CSSProperties) : undefined}

package/src/TextField.tsx

@@ -49,11 +49,13 @@ export const TextField = forwardRef<HTMLInputElement, TextFieldProps>(
       helperTextCss,
       onFocus,
       autoCapitalize,
-      size,
-      ...rest
+      ...props
     },
     ref,
   ) {
+    // As Input: forward every recipe variant group, not just `size`, so a
+    // preset that adds one keeps working.
+    const [variantProps, rest] = input.splitVariantProps(props);
     const slots = field();
     return (
       <RACTextField {...rest} className={slots.root}>
@@ -67,7 +69,7 @@ export const TextField = forwardRef<HTMLInputElement, TextFieldProps>(
         </RACLabel>
         <RACInput
           ref={ref}
-          className={input({ size })}
+          className={input(variantProps)}
           onFocus={onFocus}
           autoCapitalize={autoCapitalize}
         />

package/src/Tooltip.recipe.ts

@@ -0,0 +1,37 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import { defineRecipe } from "@pandacss/dev";
+
+/**
+ * Tooltip recipe — Chakra's dark tooltip.
+ *
+ * A recipe rather than styles inside the component because tooltip typography
+ * is the kind of thing an app sets once for all of them: classroom's Chakra
+ * theme did exactly that (`fontSize: md`), and a `css` override at today's
+ * call sites would quietly not apply to tomorrow's.
+ *
+ * The colour, vertical padding and radius are Chakra's exactly. They had
+ * drifted (white, `py: 1`, `borderRadius: md`) while this lived inside the
+ * component, which classroom's port measured: a 6px radius where Chakra drew
+ * 2px. ml-trainer and python-editor pick the correction up too.
+ *
+ * Registered in the base preset (base-preset.ts).
+ */
+export const tooltip = defineRecipe({
+  className: "tooltip",
+  base: {
+    bg: "gray.700",
+    color: "whiteAlpha.900",
+    px: "2",
+    py: "0.5",
+    borderRadius: "sm",
+    fontSize: "sm",
+    fontWeight: "medium",
+    boxShadow: "md",
+    maxW: "xs",
+    zIndex: "tooltip",
+  },
+});

package/src/Tooltip.tsx

@@ -5,26 +5,11 @@
  */
 import { ReactElement, ReactNode, RefObject } from "react";
 import { Tooltip as RACTooltip, TooltipTrigger } from "react-aria-components";
-import { css } from "styled-system/css";
+import { css, cx } from "styled-system/css";
+import { tooltip } from "styled-system/recipes";
 import { SystemStyleObject } from "styled-system/types";
 import { PopoverArrow } from "./PopoverArrow";
 
-// Base as an object (not a precomputed class) so a caller's `css` override is
-// merged into a single css() call — Panda then dedupes conflicting utilities
-// (e.g. px/py) so overrides actually win.
-const tooltipBase: SystemStyleObject = {
-  bg: "gray.700",
-  color: "white",
-  px: "2",
-  py: "1",
-  borderRadius: "md",
-  fontSize: "sm",
-  fontWeight: "medium",
-  boxShadow: "md",
-  maxW: "xs",
-  zIndex: "tooltip",
-};
-
 export interface TooltipProps {
   /**
    * Tooltip body (Chakra's `label`). Not named `content`: Panda extracts
@@ -82,7 +67,7 @@ export const Tooltip = ({
       triggerRef={triggerRef}
       placement={placement}
       offset={hasArrow ? 8 : 4}
-      className={css({ ...tooltipBase, ...cssProp })}
+      className={cx(tooltip(), cssProp ? css(cssProp) : undefined)}
     >
       {hasArrow && <PopoverArrow css={{ "& svg": { fill: "gray.700" } }} />}
       {label}

package/src/base-preset.ts

@@ -23,19 +23,24 @@ import {
 } from "./base-tokens";
 // Config recipes are colocated with the shared-ui components they style; this
 // preset registers them so Panda merges them at codegen time.
+import { avatar } from "./Avatar.recipe";
 import { button } from "./Button.recipe";
 import { card } from "./Card.recipe";
 import { checkbox } from "./Checkbox.recipe";
 import { radio } from "./Radio.recipe";
 import { drawer } from "./Drawer.recipe";
+import { gridList } from "./GridList.recipe";
 import { heading } from "./Heading.recipe";
 import { input } from "./Input.recipe";
+import { listBox } from "./ListBox.recipe";
 import { numberField } from "./NumberField.recipe";
 import { menu } from "./Menu.recipe";
+import { select } from "./Select.recipe";
 import { slider } from "./Slider.recipe";
 import { switchRecipe } from "./Switch.recipe";
 import { dialog } from "./Modal.recipe";
 import { text } from "./Text.recipe";
+import { tooltip } from "./Tooltip.recipe";
 import { field } from "./TextField.recipe";
 import { toast } from "./Toast.recipe";
 
@@ -65,11 +70,23 @@ export const basePreset = definePreset({
   theme: {
     breakpoints,
     keyframes: {
-      // Spinner's revolution (the only keyframe a shared-ui component uses).
+      // Spinner's revolution.
       spin: {
         "0%": { transform: "rotate(0deg)" },
         "100%": { transform: "rotate(360deg)" },
       },
+      // Skeleton's pulse, over the pair of custom properties the component
+      // sets, so a retinted skeleton animates between its own colours.
+      skeletonFade: {
+        from: {
+          borderColor: "var(--skeleton-start-color)",
+          background: "var(--skeleton-start-color)",
+        },
+        to: {
+          borderColor: "var(--skeleton-end-color)",
+          background: "var(--skeleton-end-color)",
+        },
+      },
     },
     tokens: {
       colors: {
@@ -158,6 +175,27 @@ export const basePreset = definePreset({
         // follows; OSS language buttons are brand blue.)
         languageText: { value: "{colors.brand.500}" },
         languageTextHover: { value: "{colors.brand.600}" },
+        // The `primary`/`secondary` button variants' colours. Two brand
+        // idioms exist in the family: brand-coloured buttons (ml-trainer,
+        // python-editor — the defaults below) and a black-on-white system
+        // (classroom, data-microbit-org: black solid, black outline, no
+        // border colour change on hover but a blackAlpha wash instead).
+        // Tokens rather than per-app recipe overrides so both idioms share
+        // one recipe — a `variant` fork would be duplicated by every app on
+        // the far side of it. `primary`'s text colour stays a literal
+        // `white`: every app in the family puts white on a dark solid.
+        // `ghost` needs no tokens (black + blackAlpha in all four apps).
+        button: {
+          primaryBg: { value: "{colors.brand.500}" },
+          primaryHoverBg: { value: "{colors.brand.600}" },
+          primaryActiveBg: { value: "{colors.brand.700}" },
+          secondaryText: { value: "{colors.brand.700}" },
+          secondaryBorder: { value: "{colors.brand.500}" },
+          secondaryHoverBorder: { value: "{colors.brand.600}" },
+          secondaryHoverBg: { value: "transparent" },
+          secondaryActiveBorder: { value: "{colors.brand.700}" },
+          secondaryActiveBg: { value: "{colors.brand.50}" },
+        },
         // Toast status colours: the Chakra-era toast Alert restyle (teal for
         // every status except error) shared across the app family.
         toastInfoBg: { value: "{colors.teal.800}" },
@@ -174,16 +212,21 @@ export const basePreset = definePreset({
       heading,
       input,
       text,
+      tooltip,
     },
     slotRecipes: {
+      avatar,
       card,
       checkbox,
       dialog,
       drawer,
       field,
+      gridList,
+      listBox,
       menu,
       numberField,
       radio,
+      select,
       slider,
       switchRecipe,
       toast,
@@ -240,7 +283,12 @@ export const basePreset = definePreset({
   // can silently lose runtime-prop variants.
   staticCss: {
     recipes: {
-      button: ["*"],
+      // Size is passed responsively at call sites ported from Chakra's
+      // `size={["md", "lg"]}`, so generate the breakpoint-prefixed variants
+      // too — otherwise the class lands on the element with no rule behind it
+      // and the button silently falls back to the base size.
+      avatar: ["*"],
+      button: [{ size: ["*"], responsive: true }, { variant: ["*"] }],
       checkbox: ["*"],
       heading: ["*"],
       card: ["*"],
@@ -248,10 +296,14 @@ export const basePreset = definePreset({
       // as a runtime prop, so generate the breakpoint-prefixed variants too.
       dialog: [{ size: ["*"], responsive: true }, { centered: ["*"] }],
       drawer: ["*"],
+      gridList: ["*"],
+      listBox: ["*"],
       input: ["*"],
       radio: ["*"],
+      select: ["*"],
       switchRecipe: ["*"],
       text: ["*"],
+      tooltip: ["*"],
       // Toast status is chosen at runtime from the toast content.
       toast: ["*"],
     },

package/src/data-attrs.ts

@@ -0,0 +1,16 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+
+/**
+ * The `data-*` entries of a props object, for components that let a caller
+ * put test hooks on an inner element rather than the one their props land on.
+ *
+ * Internal: not exported from the package.
+ */
+export const dataAttrs = (props: object): Record<string, unknown> =>
+  Object.fromEntries(
+    Object.entries(props).filter(([key]) => key.startsWith("data-")),
+  );

package/src/dense-preset.ts

@@ -0,0 +1,108 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import { definePreset } from "@pandacss/dev";
+
+const toTokens = (values: Record<string, string>) =>
+  Object.fromEntries(
+    Object.entries(values).map(([k, value]) => [k, { value }]),
+  ) as Record<string, { value: string }>;
+
+/**
+ * The numeric spacing/size grid, Chakra's 0.25rem step × 0.88.
+ *
+ * Only the numeric scale is touched: the named `sizes` (`xs`…`8xl`, `max`,
+ * `full`, `container.*`) stay at their base-preset values, as they did in
+ * both apps' Chakra themes.
+ */
+const scale = toTokens({
+  px: "1px",
+  0.5: "0.11rem",
+  1: "0.22rem",
+  1.5: "0.33rem",
+  2: "0.44rem",
+  2.5: "0.55rem",
+  3: "0.66rem",
+  3.5: "0.77rem",
+  4: "0.88rem",
+  5: "1.1rem",
+  6: "1.32rem",
+  7: "1.54rem",
+  8: "1.76rem",
+  9: "1.98rem",
+  10: "2.2rem",
+  12: "2.64rem",
+  14: "3.08rem",
+  16: "3.52rem",
+  20: "4.4rem",
+  24: "5.28rem",
+  28: "6.16rem",
+  32: "7.04rem",
+  36: "7.92rem",
+  40: "8.8rem",
+  44: "9.68rem",
+  48: "10.56rem",
+  52: "11.44rem",
+  56: "12.32rem",
+  60: "13.2rem",
+  64: "14.08rem",
+  72: "15.84rem",
+  80: "17.6rem",
+  96: "21.12rem",
+});
+
+/**
+ * Font sizes from `md` up, × 0.9. `xs`/`sm` keep their full size so small
+ * text never gets too small, and `3xs`/`2xs` (which neither app's theme
+ * listed) stay at their base-preset values.
+ */
+const denseFontSizes = toTokens({
+  md: "0.9rem",
+  lg: "1.012rem",
+  xl: "1.125rem",
+  "2xl": "1.35rem",
+  "3xl": "1.687rem",
+  "4xl": "2.025rem",
+  "5xl": "2.7rem",
+  "6xl": "3.375rem",
+  "7xl": "4.05rem",
+  "8xl": "5.4rem",
+  "9xl": "7.2rem",
+});
+
+/**
+ * The dense preset — an optional density override for the information-dense
+ * apps in the family. Stacks between the base preset and the app preset:
+ *
+ * ```ts
+ * presets: ["@pandacss/preset-base", basePreset, densePreset, appPreset]
+ * ```
+ *
+ * Both python-editor and classroom shipped the same "make everything
+ * smaller" Chakra theme change (2022): the numeric spacing/sizes grid at
+ * × 0.88 and `fontSizes` from `md` up at × 0.9. The two themes' values were
+ * byte-identical, so the scale lives here rather than being replicated in
+ * each app preset (migration-playbook gotcha #25 — a global scale override
+ * hides from every safeguard, so it needs to be explicit and shared).
+ *
+ * Whether this density stays or the family aligns on one scale is an open
+ * design question; when it is answered, this preset is the single place the
+ * answer lands (deleting it from an app's stack un-shrinks that app).
+ * ml-trainer and data-microbit-org do not use it.
+ */
+export const densePreset = definePreset({
+  name: "microbit-ui-dense",
+  theme: {
+    extend: {
+      tokens: {
+        spacing: scale,
+        sizes: scale,
+        fontSizes: denseFontSizes,
+      },
+    },
+  },
+});
+
+export default densePreset;

package/src/hooks/useDisclosure.ts

@@ -0,0 +1,32 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import { useCallback, useMemo, useState } from "react";
+
+export interface Disclosure {
+  isOpen: boolean;
+  onOpen: () => void;
+  onClose: () => void;
+  onToggle: () => void;
+}
+
+/**
+ * useDisclosure — Chakra's hook of the same name: the open/closed state of a
+ * dialog, menu or drawer, and the three functions that change it.
+ *
+ * A thin `useState` wrapper, kept because it is the shape a Chakra app's
+ * dialog call sites are written in, and because a stable object means a
+ * disclosure can be passed to a memoised child without re-rendering it.
+ */
+export const useDisclosure = (defaultIsOpen = false): Disclosure => {
+  const [isOpen, setIsOpen] = useState(defaultIsOpen);
+  const onOpen = useCallback(() => setIsOpen(true), []);
+  const onClose = useCallback(() => setIsOpen(false), []);
+  const onToggle = useCallback(() => setIsOpen((open) => !open), []);
+  return useMemo(
+    () => ({ isOpen, onOpen, onClose, onToggle }),
+    [isOpen, onOpen, onClose, onToggle],
+  );
+};

package/src/index.ts

@@ -9,6 +9,7 @@
  * match the Chakra theme; behaviour follows react-aria patterns.
  */
 export * from "./system";
+export * from "./Avatar";
 export * from "./Button";
 export * from "./LinkButton";
 export * from "./ButtonGroup";
@@ -23,8 +24,10 @@ export * from "./NativeSelect";
 export * from "./NumberField";
 export * from "./ProgressBar";
 export * from "./Radio";
+export * from "./Skeleton";
 export * from "./Slide";
 export * from "./Slider";
+export * from "./Select";
 export * from "./Spinner";
 export * from "./Svg";
 export * from "./Switch";
@@ -40,8 +43,11 @@ export * from "./Collapse";
 export * from "./Fade";
 export * from "./Kbd";
 export * from "./Divider";
+export * from "./GridList";
 export * from "./Drawer";
 export * from "./List";
+export * from "./ListBox";
+export * from "./ComboBox";
 export * from "./Menu";
 export * from "./Modal";
 export * from "./PopoverArrow";
@@ -51,5 +57,7 @@ export * from "./Toast";
 export * from "./VisuallyHidden";
 export { useBreakpointValue } from "./hooks/useBreakpointValue";
 export { useClipboard } from "./hooks/useClipboard";
+export { useDisclosure } from "./hooks/useDisclosure";
+export type { Disclosure } from "./hooks/useDisclosure";
 export { useMediaQuery } from "./hooks/useMediaQuery";
 export { usePrevious } from "./hooks/usePrevious";

package/src/system.ts

@@ -11,6 +11,8 @@
 export { css, cva, sva, cx } from "styled-system/css";
 export { token } from "styled-system/tokens";
 export type { SystemStyleObject } from "styled-system/types";
+// react-aria collection types call sites need for selection handlers.
+export type { Key, Selection } from "react-aria-components";
 export type {
   BoxProps,
   FlexProps,
@@ -21,9 +23,16 @@ export type {
 } from "styled-system/jsx";
 
 // Layout patterns — the Panda-native equivalents of Chakra's Box/Flex/Stack/etc.
+//
+// `styled` is re-exported for the `styled(Component)` form, which works from
+// anywhere. The `styled.tag` JSX form does NOT: Panda recognises the factory by
+// the module it was imported from, so `<styled.table css={…}>` on a `styled`
+// imported from here silently produces no CSS. Import it from
+// "styled-system/jsx" for that (playbook gotcha #41).
 export {
   AspectRatio,
   Box,
+  Container,
   Flex,
   Stack,
   HStack,