@microbit/ui 0.1.0-alpha.9 → 0.1.0

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.
  */

package/src/Slider.recipe.ts

@@ -6,14 +6,18 @@
 import { defineSlotRecipe } from "@pandacss/dev";
 
 /**
- * Slider slot recipe — Chakra's horizontal md slider (14px thumb, 4px
- * gray.200 track, blue filled track; light mode). Consumed by the shared-ui
- * Slider, which maps the slots onto react-aria-components'
- * Slider/SliderTrack/SliderThumb.
+ * Slider slot recipe — a horizontal slider (3.5-token thumb, 1-token gray.200
+ * track, blue filled track). Consumed by the shared-ui Slider, which maps the
+ * slots onto react-aria-components' Slider/SliderTrack/SliderThumb.
  *
- * The `mark` slot is hidden until the slider has focus (Chakra call sites did
- * this with `_focusWithin` + a class); the reveal lives here so call sites
- * only style the mark's look.
+ * Geometry: the root is thumb-height with NO horizontal padding, the track is
+ * absolutely centred inside it at full width, and the thumb overhangs the
+ * track ends at 0%/100%. Call sites position overlays (marks, value labels)
+ * against that root box. Sizes are tokens, not px, so apps with resized
+ * scales (e.g. python-editor's ×0.88) keep proportional geometry.
+ *
+ * The `mark` slot is hidden until the slider has focus; the reveal lives here
+ * so call sites only style the mark's look.
  *
  * Registered in the base preset (base-preset.ts). No variants, so it
  * needs no `staticCss` entry.
@@ -26,9 +30,9 @@ export const slider = defineSlotRecipe({
       position: "relative",
       display: "block",
       width: "100%",
+      // Thumb-height; the track centres inside.
+      height: "3.5",
       touchAction: "none",
-      // Half the thumb so it doesn't overflow the ends (Chakra container px).
-      px: "calc(14px / 2)",
       "&:focus-within [data-part='mark']": {
         display: "block",
       },
@@ -38,8 +42,12 @@ export const slider = defineSlotRecipe({
       },
     },
     track: {
-      position: "relative",
-      height: "4px",
+      position: "absolute",
+      top: "50%",
+      transform: "translateY(-50%)",
+      left: 0,
+      width: "100%",
+      height: "1",
       overflow: "hidden",
       borderRadius: "sm",
       bg: "gray.200",
@@ -52,15 +60,18 @@ export const slider = defineSlotRecipe({
     filledTrack: {
       position: "absolute",
       top: 0,
-      left: 0,
+      // Logical, unlike the thumb: the fill grows from the track's start, so
+      // in RTL it fills from the right and the two still meet.
+      insetStart: 0,
       height: "100%",
-      bg: "sliderFilledTrack",
+      // Fill colour is set per call site via `filledTrackCss`.
+      bg: "brand.500",
     },
     thumb: {
       position: "absolute",
       top: "50%",
-      width: "14px",
-      height: "14px",
+      width: "3.5",
+      height: "3.5",
       display: "flex",
       alignItems: "center",
       justifyContent: "center",
@@ -76,7 +87,7 @@ export const slider = defineSlotRecipe({
       },
       transform: "translate(-50%, -50%)",
       "&[data-focus-visible]": {
-        focusShadow: "outline",
+        focusRing: "outline",
       },
       "&[data-disabled]": {
         bg: "gray.300",

package/src/Slider.tsx

@@ -4,6 +4,7 @@
  * SPDX-License-Identifier: MIT
  */
 import { ReactNode } from "react";
+import { useLocale } from "react-aria";
 import {
   Slider as RACSlider,
   SliderThumb,
@@ -33,20 +34,24 @@ export interface SliderProps {
   thumbCss?: SystemStyleObject;
   /**
    * Positioned at the current value along the track and shown while the
-   * slider has focus (Chakra's SliderMark usage).
+   * slider has focus.
    */
   mark?: ReactNode;
   markCss?: SystemStyleObject;
   /**
    * Additional positioned overlays rendered inside the slider root
    * (always-visible value labels, threshold markers, ...). The root is
-   * position: relative; position children absolutely, typically with a
-   * percentage `left` for the track position.
+   * position: relative; position children absolutely.
+   *
+   * Anything sitting at a *value* along the track takes a percentage `left`,
+   * physical and mirrored by hand in RTL as the thumb is (see `offset`
+   * below), never `insetInlineStart`. Anything pinned to the track's *ends*
+   * — min/max labels and the like — is ordinary layout and should be
+   * logical, so `insetStart`/`insetEnd`.
    */
   children?: ReactNode;
   /**
-   * Tooltip-styled bubble anchored above the thumb (Chakra's
-   * Tooltip-around-SliderThumb pattern). Rendered only while
+   * Tooltip-styled bubble anchored above the thumb. Rendered only while
    * `isThumbTooltipOpen`; drive it from hover/focus, e.g. via
    * `onThumbFocusChange` and mouse handlers on an enclosing element.
    */
@@ -56,10 +61,7 @@ export interface SliderProps {
   onThumbFocusChange?: (isFocused: boolean) => void;
 }
 
-/**
- * Slider — react-aria-components <Slider> styled like Chakra's horizontal md
- * slider.
- */
+/** Slider — a styled horizontal react-aria-components <Slider>. */
 export const Slider = ({
   value,
   onChange,
@@ -80,7 +82,13 @@ export const Slider = ({
   onThumbFocusChange,
 }: SliderProps) => {
   const slots = slider();
+  const { direction } = useLocale();
   const percent = ((value - minValue) / (maxValue - minValue)) * 100;
+  // react-aria positions the thumb with a physical `left` that it mirrors
+  // itself in RTL (useSliderThumb), so anything tracking the thumb has to
+  // mirror the same way rather than going logical — `insetInlineStart` would
+  // put these on the opposite side of the track from the thumb.
+  const offset = direction === "rtl" ? 100 - percent : percent;
   return (
     <RACSlider
       value={value}
@@ -96,7 +104,7 @@ export const Slider = ({
         <div
           data-part="mark"
           className={cx(slots.mark, markCss ? css(markCss) : undefined)}
-          style={{ left: `${percent}%` }}
+          style={{ left: `${offset}%` }}
         >
           {mark}
         </div>
@@ -119,7 +127,7 @@ export const Slider = ({
           role="presentation"
           className={css({
             position: "absolute",
-            bottom: "calc(50% + 14px)",
+            bottom: "calc(50% + token(sizes.3.5))",
             transform: "translateX(-50%)",
             bg: "gray.700",
             color: "white",
@@ -148,7 +156,7 @@ export const Slider = ({
               borderTopColor: "gray.700",
             },
           })}
-          style={{ left: `${percent}%` }}
+          style={{ left: `${offset}%` }}
         >
           {thumbTooltip}
         </div>

package/src/Spinner.tsx

@@ -5,29 +5,29 @@
  */
 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 {
-  /** Chakra Spinner sizes: sm 1rem, md 1.5rem (default). */
+  /** sm is 1rem, md 1.5rem (default). */
   size?: "sm" | "md";
   /**
-   * Revolution time (Chakra's `speed`, default 0.45s). Under
-   * prefers-reduced-motion the spin is slowed to ~3x this value.
+   * Revolution time (default 0.45s). Under prefers-reduced-motion the spin is
+   * slowed to ~3x this value.
    */
   speed?: string;
   /** Per-instance style overrides, merged after the base. */
   css?: SystemStyleObject;
   className?: string;
-  /**
-   * Accessible name. Required: Chakra's Spinner announced a visually hidden
-   * "Loading..." by default, so a nameless spinner would regress on it.
-   */
+  /** Accessible name. Required: a spinner must announce what is loading. */
   "aria-label": string;
+  /** `data-*` attributes land on the spinner, for tests that wait on it. */
+  [key: `data-${string}`]: unknown;
 }
 
 /**
- * Spinner — Chakra's border-based spinner (currentColor with transparent
- * bottom/left quadrants).
+ * Spinner — a border-based spinner (currentColor with transparent bottom/left
+ * quadrants).
  */
 export const Spinner = ({
   size = "md",
@@ -35,8 +35,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/Svg.tsx

@@ -6,10 +6,9 @@
 import { styled } from "styled-system/jsx";
 
 /**
- * Svg — a Panda-styled svg element with Chakra Icon's base sizing (1em,
+ * Svg — a Panda-styled svg element with Icon's base sizing (1em,
  * inline-block). For custom-path icons; react-icons glyphs use `Icon`.
- * As a styled-factory component its call-site style props are extracted
- * (unlike style props forwarded through a plain wrapper — gotcha #9).
+ * As a styled-factory component its call-site style props are extracted.
  */
 export const Svg = styled("svg", {
   base: {