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

package/src/Select.recipe.ts

@@ -0,0 +1,211 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import { defineSlotRecipe } from "@pandacss/dev";
+
+// The common transition-property list, inlined (Panda has no
+// transitionProperty token category).
+// No box-shadow: nothing in this recipe uses one, and the focus ring's
+// layers must never fade in.
+const transitionCommon =
+  "background-color, border-color, color, fill, stroke, opacity, transform";
+
+/**
+ * Select slot recipe — the dropdown pair, shared by `Select` (a listbox behind
+ * a button) and `ComboBox` (a listbox behind a text input). One recipe because
+ * the two differ only in what the control is: keeping them together is what
+ * stops a searchable and a non-searchable picker drifting apart visually.
+ *
+ * `trigger` matches the `input` recipe's outline field so a select sits level
+ * with a TextField beside it; `content` matches the `menu` recipe's card so
+ * every dropdown surface in the family agrees.
+ *
+ * Apps restyle it through the `variant` group — classroom's `classroom`
+ * variant is the rounded pill its join form uses.
+ *
+ * The label is not a slot here: it comes from the `field` recipe, as every
+ * other labelled field's does. The only thing that costs is a per-`variant`
+ * label style — restyle the control and let the label match the family.
+ *
+ * Registered in the base preset (base-preset.ts).
+ */
+export const select = defineSlotRecipe({
+  className: "select",
+  slots: [
+    "root",
+    "trigger",
+    "value",
+    "indicator",
+    "content",
+    "list",
+    "option",
+    "optionIndicator",
+    "empty",
+  ],
+  base: {
+    // No layout here: the component wears the `field` recipe's root alongside
+    // this slot, and that recipe is the single owner of field-root layout
+    // (else `labelPosition` would fight this slot over `flexDirection`). The
+    // slot stays for apps and variants to target.
+    root: {},
+    trigger: {
+      display: "flex",
+      alignItems: "center",
+      justifyContent: "space-between",
+      gap: "2",
+      width: "100%",
+      minWidth: 0,
+      outline: "none",
+      appearance: "none",
+      font: "inherit",
+      textAlign: "start",
+      cursor: "pointer",
+      transitionProperty: transitionCommon,
+      transitionDuration: "normal",
+      border: "2px solid",
+      // As the input recipe (rationale there). The dropdown card below
+      // keeps gray.200 — a surface edge, not a form-control boundary.
+      borderColor: "gray.300",
+      bg: "white",
+      color: "inherit",
+      // As the input recipe, so mixed fields tint together on hover.
+      _hover: { borderColor: "gray.500" },
+      // `data-invalid` lands on the root — and, in a ComboBox, on the input —
+      // but never on the trigger: a RAC Button has no validity state, and our
+      // ComboBox control is a plain div. So it comes down from the parent.
+      // `> &` rather than a descendant selector, so an app's own invalid form
+      // wrapper cannot paint every control inside it red. Repeated `&`: the
+      // hover < focused < invalid specificity ladder, as the input recipe.
+      "&&:is([data-focused], :has(input:focus))": {
+        borderColor: "focusBorder",
+      },
+      // Border colour alone, as the input recipe.
+      "[data-invalid] > &&&": {
+        borderColor: "danger.500",
+      },
+      // Keyboard-only ring, two cases. Select's button: RAC's attribute.
+      // ComboBox: the input's RAC attributes are stripped by react-aria's
+      // synthetic blur during virtual focus, so its case combines the two
+      // signals that survive — native :focus plus the global-modality
+      // attribute the component renders (see ComboBox.tsx). No flicker
+      // during list navigation; can't match Select (no input).
+      "&&&[data-focus-visible], &&&[data-keyboard-modality]:has(input:focus)": {
+        focusRing: "outline",
+      },
+      "&[data-disabled]": { opacity: 0.4, cursor: "not-allowed" },
+    },
+    // Whatever shows the current value: Select's SelectValue, ComboBox's
+    // input. One slot for both, so an app restyling the placeholder (say)
+    // does not have to know which kind of control it is looking at.
+    value: {
+      flex: "1",
+      minWidth: 0,
+      overflow: "hidden",
+      textOverflow: "ellipsis",
+      whiteSpace: "nowrap",
+      outline: "none",
+      bg: "transparent",
+      color: "inherit",
+      font: "inherit",
+      // RAC sets data-placeholder on SelectValue when nothing is chosen; the
+      // ComboBox input uses the real placeholder attribute.
+      "&[data-placeholder]": { color: "gray.500" },
+      _placeholder: { color: "gray.500" },
+    },
+    indicator: {
+      display: "inline-flex",
+      flexShrink: 0,
+      alignItems: "center",
+      justifyContent: "center",
+      fontSize: "1.25em",
+      color: "inherit",
+      // No pointer-events:none here: in a ComboBox this slot is the button
+      // that opens the list. Select's is an aria-hidden span inside the
+      // trigger, so it needs no help being inert.
+      background: "transparent",
+      border: "none",
+      cursor: "pointer",
+      // No focus styling, deliberately: react-aria keeps a ComboBox's toggle
+      // button out of the tab order (the input owns the keyboard), so a ring
+      // here would only ever be reachable programmatically, and would suggest
+      // the chevron is a tab stop. The whole control shows focus instead.
+      outline: "none",
+    },
+    content: {
+      // Line the card up with the control, as a select should. `Select` gets
+      // this from RAC, whose trigger is the button it measures; `ComboBox`
+      // measures its own control and sets the width inline, because RAC's var
+      // is the *input's* width there.
+      minWidth: "var(--trigger-width)",
+      display: "flex",
+      flexDirection: "column",
+      bg: "white",
+      color: "inherit",
+      py: "2",
+      zIndex: "popover",
+      borderRadius: "md",
+      borderWidth: "1px",
+      borderColor: "gray.200",
+      boxShadow: "sm",
+      // Matches the menu recipe's fade/scale.
+      transformOrigin: "top",
+      opacity: 1,
+      transform: "scale(1)",
+      transition: "opacity 0.1s ease-out, transform 0.1s ease-out",
+      "&[data-entering]": { opacity: 0, transform: "scale(0.95)" },
+      "&[data-exiting]": { opacity: 0, transform: "scale(0.95)" },
+      _motionReduce: { transition: "none" },
+    },
+    list: {
+      outline: "none",
+      overflowY: "auto",
+    },
+    option: {
+      display: "flex",
+      alignItems: "center",
+      gap: "2",
+      py: "1.5",
+      px: "3",
+      cursor: "pointer",
+      color: "inherit",
+      outline: "none",
+      // As the menu recipe: the highlight is focus indication (no
+      // transition — it snaps with the ring, which keyboard nav adds;
+      // inset, the rows being full-bleed).
+      "&[data-focused]": { bg: "gray.100" },
+      "&[data-focus-visible]": { focusRing: "outlineInset" },
+      "&[data-pressed]": { bg: "gray.200" },
+      "&[data-disabled]": { opacity: 0.4, cursor: "not-allowed" },
+    },
+    optionIndicator: {
+      display: "inline-flex",
+      flexShrink: 0,
+      alignItems: "center",
+      justifyContent: "center",
+      marginStart: "auto",
+      fontSize: "0.8em",
+      opacity: 0,
+      "[data-selected] &": { opacity: 1 },
+    },
+    empty: {
+      px: "3",
+      py: "2",
+      color: "gray.600",
+    },
+  },
+  variants: {
+    // The `input` recipe's size ladder, step for step, so a Select sits level
+    // with a TextField beside it at every size. The indicator is em-sized and
+    // scales free; the dropdown card keeps one density across sizes.
+    size: {
+      lg: { trigger: { fontSize: "lg", px: "4", h: "12", borderRadius: "md" } },
+      md: { trigger: { fontSize: "md", px: "4", h: "10", borderRadius: "md" } },
+      sm: { trigger: { fontSize: "sm", px: "3", h: "8", borderRadius: "sm" } },
+    },
+  },
+  defaultVariants: {
+    size: "md",
+  },
+});

package/src/Select.tsx

@@ -0,0 +1,194 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import { createContext, ReactNode, useContext } from "react";
+import {
+  Button as RACButton,
+  ListBox as RACListBox,
+  ListBoxItem as RACListBoxItem,
+  ListBoxItemProps as RACListBoxItemProps,
+  Popover,
+  PopoverProps,
+  Select as RACSelect,
+  SelectProps as RACSelectProps,
+  SelectValue,
+} from "react-aria-components";
+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";
+
+export type SelectSlots = ReturnType<typeof select>;
+
+// Options are children, so they can't see the variant their Select was given.
+// The parent hands its resolved slots down, as Modal does for its own slots.
+const SlotContext = createContext<SelectSlots>(select({}));
+
+export const useSelectSlots = () => useContext(SlotContext);
+
+export const SelectSlotProvider = SlotContext.Provider;
+
+export interface SelectProps<T extends object>
+  extends Omit<
+      RACSelectProps<T>,
+      "className" | "children" | "style" | "placeholder"
+    >,
+    SelectVariantProps,
+    FieldSupportProps,
+    FieldLayoutProps {
+  /** Visible label. Use `aria-label` instead where the design has none. */
+  label?: ReactNode;
+  /** Label style overrides. */
+  labelCss?: SystemStyleObject;
+  /**
+   * Shown in the trigger while nothing is chosen. Defaults to a translated
+   * "Select an item".
+   */
+  placeholder?: string;
+  /** `SelectOption`s. */
+  children: ReactNode;
+  /**
+   * Replaces the chevron; `null` removes it. Rarely right on a Select — the
+   * chevron is the only thing marking its trigger as a dropdown rather than
+   * a label, where a ComboBox's text input speaks for itself (which is why
+   * classroom's chevron-less autocomplete is a ComboBox).
+   */
+  indicator?: ReactNode | null;
+  /** Placement of the dropdown relative to the trigger. */
+  placement?: PopoverProps["placement"];
+  /**
+   * Cap the dropdown's height. 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 button the value sits in). */
+  triggerCss?: SystemStyleObject;
+  /** Per-instance overrides for the dropdown card. */
+  contentCss?: SystemStyleObject;
+  className?: string;
+}
+
+/**
+ * Select — a listbox behind a button, for choosing one of a known set. Use
+ * ComboBox where the user should be able to type to filter.
+ */
+export const Select = <T extends object>({
+  label,
+  labelCss,
+  placeholder,
+  children,
+  indicator,
+  placement = "bottom start",
+  maxHeight,
+  helperText,
+  errorMessage,
+  helperTextCss,
+  labelPosition,
+  triggerCss,
+  contentCss,
+  className,
+  ...props
+}: SelectProps<T>) => {
+  // splitVariantProps, not a hand-picked list: an app preset can add variant
+  // groups to the recipe and they have to reach it.
+  const [variantProps, rest] = select.splitVariantProps(props);
+  const intl = useIntl();
+  const slots = select(variantProps);
+  const fieldSlots = field({ size: variantProps.size, labelPosition });
+  return (
+    <SelectSlotProvider value={slots}>
+      <RACSelect
+        {...(rest as RACSelectProps<T>)}
+        className={cx(fieldSlots.root, slots.root, className)}
+      >
+        {label != null && (
+          <FieldLabel
+            size={variantProps.size}
+            labelPosition={labelPosition}
+            isRequired={props.isRequired}
+            css={labelCss}
+          >
+            {label}
+          </FieldLabel>
+        )}
+        <RACButton
+          className={cx(
+            slots.trigger,
+            triggerCss ? css(triggerCss) : undefined,
+          )}
+        >
+          <SelectValue className={slots.value}>
+            {({ isPlaceholder, defaultChildren }) =>
+              isPlaceholder
+                ? placeholder ??
+                  intl.formatMessage(uiMessage("ui.select-placeholder"))
+                : defaultChildren
+            }
+          </SelectValue>
+          {indicator !== null && (
+            <span className={slots.indicator} aria-hidden>
+              {indicator ?? <Icon as={RiArrowDownSLine} />}
+            </span>
+          )}
+        </RACButton>
+        <Popover
+          placement={placement}
+          maxHeight={maxHeight}
+          className={cx(
+            slots.content,
+            contentCss ? css(contentCss) : undefined,
+          )}
+        >
+          <RACListBox className={slots.list}>{children}</RACListBox>
+        </Popover>
+        <FieldSupport
+          helperText={helperText}
+          errorMessage={errorMessage}
+          helperTextCss={helperTextCss}
+          labelPosition={labelPosition}
+        />
+      </RACSelect>
+    </SelectSlotProvider>
+  );
+};
+
+export interface SelectOptionProps
+  extends Omit<RACListBoxItemProps, "className" | "children" | "style"> {
+  children?: ReactNode;
+  css?: SystemStyleObject;
+  className?: string;
+}
+
+/** A row in a `Select` or `ComboBox` list. */
+export const SelectOption = ({
+  children,
+  css: cssProp,
+  className,
+  ...rest
+}: SelectOptionProps) => {
+  const slots = useSelectSlots();
+  return (
+    <RACListBoxItem
+      {...rest}
+      className={cx(
+        slots.option,
+        cssProp ? css(cssProp) : undefined,
+        className,
+      )}
+    >
+      {children}
+    </RACListBoxItem>
+  );
+};

package/src/SharedUIProvider.tsx

@@ -3,7 +3,17 @@
  *
  * SPDX-License-Identifier: MIT
  */
-import { createContext, ReactNode, useContext, useMemo } from "react";
+import {
+  createContext,
+  ReactNode,
+  useContext,
+  useEffect,
+  useMemo,
+} from "react";
+import { isRTL } from "react-aria";
+import { I18nProvider } from "react-aria-components";
+import { IntlContext } from "react-intl";
+import { racLocale } from "./rac-locale";
 
 /**
  * Registers the close function of the currently open dismissable overlay, or
@@ -21,27 +31,73 @@ const SharedUIContext = createContext<SharedUIContextValue | null>(null);
 
 export interface SharedUIProviderProps {
   overlayCloseRegistrar?: OverlayCloseRegistrar;
+  /**
+   * Locale for react-aria's own built-in strings. Defaults to the surrounding
+   * IntlProvider's locale, which is what apps want: pass this only where the
+   * two must differ.
+   */
+  locale?: string;
+  /**
+   * Keeps `<html lang>` and `<html dir>` in step with the locale, so assistive
+   * tech announces the page in the app's language and the layout runs the
+   * right way round. On by default; set false where the app doesn't own the
+   * document it's mounted in (an embedded widget), or when mounting more than
+   * one provider per page. The static `lang="en"` in index.html remains the
+   * pre-hydration default.
+   *
+   * Turning it off in an RTL locale means the app must set `dir` itself above
+   * the components, or the UI half-mirrors: react-aria mirrors from the locale
+   * in JS whatever the DOM says, while logical properties and `_rtl` rules
+   * read `dir` (see the README's RTL note).
+   *
+   * Correct only when the IntlProvider locale is the language the app
+   * actually renders in — an app falling back wholesale to its English
+   * catalog should claim `en` there, not the user's language setting (see
+   * the README's react-intl step).
+   */
+  setDocumentLang?: boolean;
   children: ReactNode;
 }
 
 /**
- * SharedUIProvider — the app-side installation point for optional shared-ui
- * integrations. Currently that is only the overlay-close registrar, so apps
- * without one can omit the provider entirely. Localized strings come from
- * react-intl: an IntlProvider must be mounted above shared-ui components
- * (see the package README for merging this package's message catalogs).
+ * SharedUIProvider — the app-side installation point for shared-ui
+ * integrations: the optional overlay-close registrar, and the locale for
+ * react-aria's built-in strings.
+ *
+ * This package's own strings come from react-intl, so an IntlProvider must be
+ * mounted above shared-ui components (see the package README). react-aria
+ * translates its built-in strings itself, from its own bundled catalogs, and
+ * without this provider it picks the locale from the browser rather than from
+ * the app's language setting — mount it inside the IntlProvider so the two
+ * agree.
  */
 export const SharedUIProvider = ({
   overlayCloseRegistrar,
+  locale,
+  setDocumentLang = true,
   children,
 }: SharedUIProviderProps) => {
+  // Read the context rather than calling useIntl(), which throws when there is
+  // no IntlProvider: react-aria falls back to the browser locale, as before.
+  const intlLocale = useContext(IntlContext)?.locale;
+  const appLocale = locale ?? intlLocale;
+  // The tag react-aria gets, so the document's direction and the components'
+  // cannot disagree; also the only form isRTL can be handed safely, as it
+  // throws on a malformed tag.
+  const sanitizedLocale = racLocale(appLocale);
+  useEffect(() => {
+    if (setDocumentLang && appLocale && sanitizedLocale) {
+      document.documentElement.lang = appLocale;
+      document.documentElement.dir = isRTL(sanitizedLocale) ? "rtl" : "ltr";
+    }
+  }, [setDocumentLang, appLocale, sanitizedLocale]);
   const value = useMemo(
     () => ({ overlayCloseRegistrar }),
     [overlayCloseRegistrar],
   );
   return (
     <SharedUIContext.Provider value={value}>
-      {children}
+      <I18nProvider locale={sanitizedLocale}>{children}</I18nProvider>
     </SharedUIContext.Provider>
   );
 };

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.
+ *
+ * The colours flow through a 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)",
+  // gray.350, the decorative-fill stop, as the Avatar default.
+  "--skeleton-end-color": "token(colors.gray.350)",
+  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",
+  // The content is hidden rather than unmounted, 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 (default 0.8). */
+  speed?: number;
+  children?: ReactNode;
+  /** Per-instance style overrides, merged after the base. */
+  css?: SystemStyleObject;
+  className?: string;
+}
+
+/**
+ * Skeleton — a loading placeholder: a block pulsing between two greys until
+ * its content is ready.
+ *
+ * Content simply appears when `isLoaded` turns true; wrap in `Fade` where a
+ * 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 (default 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.
+ */
+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,
+            // The last line is drawn at 80%, with no gap after it.
+            width: noOfLines > 1 && index === noOfLines - 1 ? "80%" : "100%",
+            marginBottom: index === noOfLines - 1 ? "0" : spacing,
+          }}
+        />
+      ))}
+    </div>
+  );
+};

package/src/Slide.tsx

@@ -17,8 +17,8 @@ export interface SlideProps {
 }
 
 /**
- * Slide — Chakra's Slide transition, bottom edge only (add other directions
- * when a use appears): a full-width panel pinned to the viewport bottom,
+ * Slide — a slide-in transition, bottom edge only (add other directions when
+ * a use appears): a full-width panel pinned to the viewport bottom,
  * translated offscreen when closed. Content stays mounted throughout, so
  * closing doesn't drop in-flight state and the exit animates.
  */