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

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,16 +34,34 @@ 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.
+   *
+   * 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. Rendered only while
+   * `isThumbTooltipOpen`; drive it from hover/focus, e.g. via
+   * `onThumbFocusChange` and mouse handlers on an enclosing element.
+   */
+  thumbTooltip?: ReactNode;
+  isThumbTooltipOpen?: boolean;
+  /** Thumb focus tracking (react-aria focus events). */
+  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,
@@ -57,9 +76,19 @@ export const Slider = ({
   thumbCss,
   mark,
   markCss,
+  children,
+  thumbTooltip,
+  isThumbTooltipOpen,
+  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}
@@ -75,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>
@@ -91,9 +120,52 @@ export const Slider = ({
           style={{ width: `${percent}%` }}
         />
       </SliderTrack>
+      {thumbTooltip && isThumbTooltipOpen && (
+        // Matches the shared Tooltip's look (tooltipBase) with a bottom
+        // arrow, anchored above the thumb.
+        <div
+          role="presentation"
+          className={css({
+            position: "absolute",
+            bottom: "calc(50% + token(sizes.3.5))",
+            transform: "translateX(-50%)",
+            bg: "gray.700",
+            color: "white",
+            px: "2",
+            py: "1",
+            borderRadius: "md",
+            fontSize: "sm",
+            fontWeight: "medium",
+            boxShadow: "md",
+            zIndex: "tooltip",
+            whiteSpace: "nowrap",
+            _after: {
+              content: '""',
+              position: "absolute",
+              // 1px into the box so subpixel edges can't antialias into a
+              // hairline seam (see PopoverArrow).
+              top: "calc(100% - 1px)",
+              left: "50%",
+              transform: "translateX(-50%)",
+              borderWidth: "4px",
+              borderStyle: "solid",
+              // Per-side: tokens don't resolve inside multi-value
+              // shorthands (they emit verbatim and the browser drops the
+              // invalid declaration).
+              borderColor: "transparent",
+              borderTopColor: "gray.700",
+            },
+          })}
+          style={{ left: `${offset}%` }}
+        >
+          {thumbTooltip}
+        </div>
+      )}
       <SliderThumb
+        onFocusChange={onThumbFocusChange}
         className={cx(slots.thumb, thumbCss ? css(thumbCss) : undefined)}
       />
+      {children}
     </RACSlider>
   );
 };

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: {

package/src/Switch.recipe.ts

@@ -6,15 +6,15 @@
 import { defineSlotRecipe } from "@pandacss/dev";
 
 /**
- * Switch slot recipe — Chakra's md switch with the default blue colorScheme
- * (light mode). Track is 1.875rem x 1rem with a 2px inset; the thumb slides by
- * the track/thumb width difference when selected.
+ * Switch slot recipe with an sm/md/lg size scale. The track has a 2px inset;
+ * the thumb matches the track height and slides by the track width/height
+ * difference when selected.
  *
  * State styling keys off data attributes stamped by the shared-ui Switch
  * (react-aria provides the state via render props).
  *
- * Registered in the base preset (base-preset.ts). No variants, so it
- * needs no `staticCss` entry.
+ * Registered in the base preset (base-preset.ts), which also has the
+ * `staticCss` entry that keeps the runtime-prop size variants generated.
  */
 export const switchRecipe = defineSlotRecipe({
   className: "switch",
@@ -35,8 +35,6 @@ export const switchRecipe = defineSlotRecipe({
       boxSizing: "content-box",
       borderRadius: "full",
       p: "0.5",
-      width: "1.875rem",
-      height: "4",
       transitionProperty: "background-color",
       transitionDuration: "fast",
       bg: "gray.300",
@@ -44,7 +42,7 @@ export const switchRecipe = defineSlotRecipe({
         bg: "controlCheckedBg",
       },
       "&[data-focus-visible]": {
-        focusShadow: "outline",
+        focusRing: "outline",
       },
       "&[data-disabled]": { opacity: 0.4 },
       // Forced-colors modes strip author backgrounds, flattening track and
@@ -61,10 +59,18 @@ export const switchRecipe = defineSlotRecipe({
       transitionProperty: "transform",
       transitionDuration: "normal",
       borderRadius: "inherit",
-      width: "4",
-      height: "4",
+      // The thumb rests at the track's start and slides to its end, so the
+      // travel has to reverse in RTL — a transform is physical however the
+      // rest of the switch is laid out. Distance is per size, below.
+      // Fallbacks carry a unit: `calc(-1 * 0)` is a number, which is invalid
+      // where a length is wanted, and would drop the RTL transform whole.
       "&[data-selected]": {
-        transform: "translateX(0.875rem)",
+        transform: "translateX(var(--switch-travel, 0px))",
+      },
+      _rtl: {
+        "&[data-selected]": {
+          transform: "translateX(calc(-1 * var(--switch-travel, 0px)))",
+        },
       },
       _forcedColors: {
         bg: "ButtonText",
@@ -77,4 +83,44 @@ export const switchRecipe = defineSlotRecipe({
       "&[data-disabled]": { opacity: 0.4 },
     },
   },
+  variants: {
+    // `start` puts the label first and the control at the row's end — the
+    // settings-row pattern (a preference name beside its switch), the toggle
+    // counterpart of the field recipe's `labelPosition="side"`. Values are
+    // start/end rather than top/side because the default label is already
+    // beside the control, after it. The label keeps an end margin so a long
+    // translation can't butt against the track (the SelectFormControl
+    // lesson — see the field-chrome roadmap bullet).
+    labelPosition: {
+      end: {},
+      start: {
+        root: {
+          flexDirection: "row-reverse",
+          justifyContent: "space-between",
+          width: "100%",
+        },
+        label: { marginStart: "0", marginEnd: "3" },
+      },
+    },
+    // Track width x height per size; the thumb's travel is the difference
+    // between them.
+    size: {
+      sm: {
+        track: { width: "1.375rem", height: "3" },
+        thumb: { width: "3", height: "3", "--switch-travel": "0.625rem" },
+      },
+      md: {
+        track: { width: "1.875rem", height: "4" },
+        thumb: { width: "4", height: "4", "--switch-travel": "0.875rem" },
+      },
+      lg: {
+        track: { width: "2.875rem", height: "6" },
+        thumb: { width: "6", height: "6", "--switch-travel": "1.375rem" },
+      },
+    },
+  },
+  defaultVariants: {
+    size: "md",
+    labelPosition: "end",
+  },
 });

package/src/Switch.tsx

@@ -3,38 +3,59 @@
  *
  * SPDX-License-Identifier: MIT
  */
-import { ReactNode } from "react";
+import { ReactNode, useId } from "react";
 import {
   Switch as RACSwitch,
   SwitchProps as RACSwitchProps,
 } from "react-aria-components";
 import { css, cx } from "styled-system/css";
-import { switchRecipe } from "styled-system/recipes";
+import { switchRecipe, SwitchRecipeVariantProps } from "styled-system/recipes";
 import { SystemStyleObject } from "styled-system/types";
+import { FieldHelperText } from "./Field";
 
 export interface SwitchProps
-  extends Omit<RACSwitchProps, "className" | "children" | "style"> {
+  extends Omit<RACSwitchProps, "className" | "children" | "style">,
+    SwitchRecipeVariantProps {
   /** Per-instance style overrides for the root, merged after the recipe. */
   css?: SystemStyleObject;
   className?: string;
   children?: ReactNode;
+  /**
+   * Help text below the switch, wired to its `aria-describedby` — the same
+   * chrome the labelled fields' `helperText` renders. With it the component
+   * gains a wrapping `<div>`, so the switch-plus-text moves as one block.
+   */
+  helperText?: ReactNode;
+  /** Per-instance style overrides for the helper text. */
+  helperTextCss?: SystemStyleObject;
 }
 
 /**
- * Switch — react-aria-components <Switch> styled like Chakra's md switch.
- * Children render as the label; pass `aria-label` for label-less switches.
+ * Switch — a styled react-aria-components <Switch>. Children render as the
+ * label; pass `aria-label` for label-less switches. `labelPosition="start"`
+ * is the settings-row layout: label first, switch at the row's end.
  */
 export const Switch = ({
+  size,
+  labelPosition,
   css: cssProp,
   className,
   children,
+  helperText,
+  helperTextCss,
   ...rest
 }: SwitchProps) => {
-  const slots = switchRecipe();
-  return (
+  const slots = switchRecipe({ size, labelPosition });
+  const helperId = useId();
+  const describedBy =
+    [rest["aria-describedby"], helperText != null ? helperId : undefined]
+      .filter(Boolean)
+      .join(" ") || undefined;
+  const switchElement = (
     <RACSwitch
       className={cx(slots.root, cssProp ? css(cssProp) : undefined, className)}
       {...rest}
+      aria-describedby={describedBy}
     >
       {({ isSelected, isFocusVisible, isDisabled }) => {
         const state = {
@@ -57,4 +78,15 @@ export const Switch = ({
       }}
     </RACSwitch>
   );
+  if (helperText == null) {
+    return switchElement;
+  }
+  return (
+    <div>
+      {switchElement}
+      <FieldHelperText id={helperId} css={helperTextCss}>
+        {helperText}
+      </FieldHelperText>
+    </div>
+  );
 };

package/src/Text.recipe.ts

@@ -0,0 +1,26 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import { defineRecipe } from "@pandacss/dev";
+
+/**
+ * Text recipe — sizes only, no default: with no `size`, Text inherits, which
+ * is what most family apps expect. A config recipe so an app preset can set
+ * an app-wide default size by extending `defaultVariants` (python-editor
+ * defaults to md, which its shrunken fontSize scale renders at 0.9rem).
+ *
+ * Registered in the base preset (base-preset.ts).
+ */
+export const text = defineRecipe({
+  className: "text",
+  jsx: ["Text"],
+  variants: {
+    size: {
+      sm: { fontSize: "sm" },
+      md: { fontSize: "md" },
+      lg: { fontSize: "lg" },
+    },
+  },
+});

package/src/Text.tsx

@@ -4,9 +4,13 @@
  * SPDX-License-Identifier: MIT
  */
 import { styled } from "styled-system/jsx";
+import { text } from "styled-system/recipes";
 
 /**
  * Text — a paragraph that accepts Panda style props. Use `as` to render a
- * different element (`span`, `div`, `h2`). Replaces Chakra's <Text>.
+ * different element (`span`, `div`, `h2`).
+ * Backed by the `text` config recipe: `size` picks a type-scale size, and an
+ * app preset can extend the recipe's `defaultVariants` to give all its Text
+ * a default size (see Text.recipe.ts).
  */
-export const Text = styled("p");
+export const Text = styled("p", text);

package/src/TextField.tsx

@@ -5,67 +5,81 @@
  */
 import { FocusEvent, forwardRef, ReactNode } from "react";
 import {
-  FieldError,
   Input as RACInput,
-  Label as RACLabel,
-  Text as RACText,
   TextField as RACTextField,
   TextFieldProps as RACTextFieldProps,
 } from "react-aria-components";
-import { css, cx } from "styled-system/css";
-import { field, input } from "styled-system/recipes";
+import { field, input, InputVariantProps } from "styled-system/recipes";
 import { SystemStyleObject } from "styled-system/types";
+import {
+  FieldLabel,
+  FieldLayoutProps,
+  FieldSupport,
+  FieldSupportProps,
+} from "./Field";
 
 export interface TextFieldProps
   extends Omit<
-    RACTextFieldProps,
-    "className" | "children" | "style" | "onFocus" | "onBlur"
-  > {
-  /** Visible label (Chakra's FormLabel; asterisk added when `isRequired`). */
+      RACTextFieldProps,
+      "className" | "children" | "style" | "onFocus" | "onBlur"
+    >,
+    InputVariantProps,
+    FieldSupportProps,
+    FieldLayoutProps {
+  /** Visible label (asterisk added when `isRequired`). */
   label: ReactNode;
-  /** Help text below the input (Chakra's FormHelperText). */
-  helperText?: ReactNode;
-  /** Shown below the input when `isInvalid` (Chakra's FormErrorMessage). */
-  errorMessage?: ReactNode;
-  /** Per-instance style overrides for the helper text. */
-  helperTextCss?: SystemStyleObject;
+  /** Label style overrides. */
+  labelCss?: SystemStyleObject;
   onFocus?: (e: FocusEvent<HTMLInputElement>) => void;
+  /** Input autocapitalize attribute (react-aria's TextField omits it). */
+  autoCapitalize?: "off" | "none" | "on" | "sentences" | "words" | "characters";
 }
 
 /**
- * TextField — a labelled single-line text input, collapsing Chakra's
- * FormControl/FormLabel/Input/FormHelperText/FormErrorMessage. The ref is
- * forwarded to the input element.
+ * TextField — a labelled single-line text input with optional help and error
+ * text. The ref is forwarded to the input element.
  */
 export const TextField = forwardRef<HTMLInputElement, TextFieldProps>(
   function TextField(
-    { label, helperText, errorMessage, helperTextCss, onFocus, ...rest },
+    {
+      label,
+      labelCss,
+      helperText,
+      errorMessage,
+      helperTextCss,
+      labelPosition,
+      onFocus,
+      autoCapitalize,
+      ...props
+    },
     ref,
   ) {
-    const slots = field();
+    // 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({ size: variantProps.size, labelPosition });
     return (
       <RACTextField {...rest} className={slots.root}>
-        <RACLabel className={slots.label}>
+        <FieldLabel
+          size={variantProps.size}
+          labelPosition={labelPosition}
+          isRequired={rest.isRequired}
+          css={labelCss}
+        >
           {label}
-          {rest.isRequired ? (
-            <span aria-hidden className={slots.requiredIndicator}>
-              *
-            </span>
-          ) : null}
-        </RACLabel>
-        <RACInput ref={ref} className={input()} onFocus={onFocus} />
-        {helperText && (
-          <RACText
-            slot="description"
-            className={cx(
-              slots.helperText,
-              helperTextCss ? css(helperTextCss) : undefined,
-            )}
-          >
-            {helperText}
-          </RACText>
-        )}
-        <FieldError className={slots.errorMessage}>{errorMessage}</FieldError>
+        </FieldLabel>
+        <RACInput
+          ref={ref}
+          className={input(variantProps)}
+          onFocus={onFocus}
+          autoCapitalize={autoCapitalize}
+        />
+        <FieldSupport
+          helperText={helperText}
+          errorMessage={errorMessage}
+          helperTextCss={helperTextCss}
+          labelPosition={labelPosition}
+        />
       </RACTextField>
     );
   },