@microbit/ui 0.1.0-alpha.8 → 0.1.0

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,82 +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,
+      labelCss,
       helperText,
       errorMessage,
       helperTextCss,
+      labelPosition,
       onFocus,
       autoCapitalize,
-      ...rest
+      ...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>
+        </FieldLabel>
         <RACInput
           ref={ref}
-          className={input()}
+          className={input(variantProps)}
           onFocus={onFocus}
           autoCapitalize={autoCapitalize}
         />
-        {helperText && (
-          <RACText
-            slot="description"
-            className={cx(
-              slots.helperText,
-              helperTextCss ? css(helperTextCss) : undefined,
-            )}
-          >
-            {helperText}
-          </RACText>
-        )}
-        <FieldError className={slots.errorMessage}>{errorMessage}</FieldError>
+        <FieldSupport
+          helperText={helperText}
+          errorMessage={errorMessage}
+          helperTextCss={helperTextCss}
+          labelPosition={labelPosition}
+        />
       </RACTextField>
     );
   },

package/src/Toast.recipe.ts

@@ -6,10 +6,9 @@
 import { defineSlotRecipe } from "@pandacss/dev";
 
 /**
- * Toast slot recipe — the Chakra-era solid Alert restyled as a toast (white
- * text, teal for every status except error). Status colours come from the
- * `toast*Bg` semantic tokens so brand presets can retune them without
- * touching the recipe.
+ * Toast slot recipe — a solid alert card with white text, teal for every
+ * status except error. Status colours come from the `toast*Bg` semantic
+ * tokens so brand presets can retune them without touching the recipe.
  *
  * Registered in the base preset (base-preset.ts). The status variant
  * is chosen at runtime from the toast content, so it needs the preset's
@@ -17,13 +16,36 @@ import { defineSlotRecipe } from "@pandacss/dev";
  */
 export const toast = defineSlotRecipe({
   className: "toast",
-  slots: ["region", "root", "icon", "title", "description", "closeButton"],
+  slots: [
+    "region",
+    "root",
+    "content",
+    "body",
+    "icon",
+    "title",
+    "description",
+    "closeButton",
+  ],
   base: {
     region: {
       position: "fixed",
       top: "4",
       left: "50%",
       transform: "translateX(-50%)",
+      // Percentage centring of a text-width region lands the toasts on a
+      // fractional pixel. Chrome floors ::view-transition-group's transform to
+      // a whole CSS pixel, so the snapshot the enter/exit animation displays
+      // sits up to 1px left of the element it stands in for, and every toast
+      // jumps right as the transition hands back to the real DOM (visible
+      // above 1x, where the two no longer round to the same device pixel).
+      // Rounding the region's own offsets keeps it on whole pixels so the two
+      // agree. round() postdates view transitions in Chrome (130 vs 111), so
+      // the guard keeps the plain centring for the versions in between rather
+      // than dropping the declarations and losing it altogether.
+      "@supports (left: round(50%, 1px))": {
+        left: "round(50%, 1px)",
+        transform: "translateX(round(-50%, 1px))",
+      },
       zIndex: "toast",
       display: "flex",
       flexDirection: "column",
@@ -34,18 +56,35 @@ export const toast = defineSlotRecipe({
       position: "relative",
       display: "flex",
       alignItems: "flex-start",
-      gap: "3",
       p: "4",
       // Leave room for the absolutely-positioned close button plus breathing
       // space so its hover area never overlaps the title text (24px button at
-      // 4px inset spans ~4-28px from the right; content stops at 40px for a
-      // ~12px gap).
-      paddingRight: "10",
+      // 4px inset spans ~4-28px from the end edge; content stops at 40px for
+      // a ~12px gap). Logical, like the button's own inset.
+      paddingEnd: "10",
       borderRadius: "md",
       boxShadow: "lg",
       color: "white",
       maxW: "sm",
       pointerEvents: "auto",
+      // The card is focusable (RAC gives it tabindex), so it takes the
+      // house ring rather than the UA default. Ink, because the ring is
+      // drawn on the page, not the card — Toast.tsx tags the close button.
+      outline: "none",
+      _focusVisible: { focusRing: "outline" },
+    },
+    // The icon has to be inside the alert region to be announced with the
+    // message, so this row — not the root — is what lays the two out.
+    content: {
+      display: "flex",
+      alignItems: "flex-start",
+      gap: "3",
+      // Let the text shrink below its content width so long words wrap
+      // instead of pushing past the toast's maxW.
+      minWidth: 0,
+    },
+    body: {
+      minWidth: 0,
     },
     icon: {
       fontSize: "1.25rem",
@@ -58,9 +97,8 @@ export const toast = defineSlotRecipe({
       mt: "1",
     },
     closeButton: {
-      // A sized box with the glyph centred (like Chakra's CloseButton size
-      // "sm": 24px box, 2xs glyph) gives padding around the X and a hover
-      // affordance.
+      // A sized box with the glyph centred (24px box, 2xs glyph) gives
+      // padding around the X and a hover affordance.
       position: "absolute",
       top: "1",
       insetEnd: "1",
@@ -79,11 +117,10 @@ export const toast = defineSlotRecipe({
       outline: "none",
       transitionProperty: "background-color, box-shadow",
       transitionDuration: "normal",
-      // Chakra's CloseButton hover is a subtle dark overlay (blackAlpha) in
-      // light mode, not a bright highlight.
+      // Hover is a subtle dark overlay (blackAlpha), not a bright highlight.
       _hover: { bg: "blackAlpha.100" },
       _active: { bg: "blackAlpha.200" },
-      _focusVisible: { focusShadow: "outline" },
+      _focusVisible: { focusRing: "outline" },
     },
   },
   variants: {