@microbit/ui 0.2.2 → 0.3.1

package/README.md

@@ -228,6 +228,38 @@ on-dark flip below. Keep the shape:
 focusBorder: { value: { base: "{colors.brand.700}", _onDark: "{colors.white}" } };
 ```
 
+### Runtime inset variables
+
+Recipes also read a few custom properties that are set at runtime rather
+than emitted by Panda. Their names are API in the same way:
+
+- `--safe-area-nav-left` / `--safe-area-nav-right` — the horizontal
+  safe-area insets content must stay clear of, as distinct from a camera
+  cutout content may flow under. Set by `SharedUIProvider` from an
+  app-supplied `safeAreaNavSource`: a native shell with real inset
+  metadata (e.g. Android's WindowInsets API via a Capacitor plugin, as in
+  ml-trainer), which can tell the navigation bar from a display cutout.
+  Consumers read them with the raw `env(safe-area-inset-*)` value as the
+  fallback, so contexts without a source — the web included — degrade to
+  padding for every inset: conservative, never occluded. Exactly one
+  source owns the variables, and the provider is always the writer.
+
+  Don't spell those `var(…, env(…))` expressions out: the spacing tokens
+  `safeAreaTop`, `safeAreaBottom`, `safeAreaNavLeft` and `safeAreaNavRight`
+  define them once, fallbacks included — `paddingLeft: "safeAreaNavLeft"`,
+  or `token(spacing.safeAreaNavLeft)` inside `calc()`/`max()` expressions.
+  The raw variable names remain API for styling outside Panda.
+
+- `--window-controls-left` — the width of a shell's window-controls region
+  overlapping the top-left of the page (today: iPadOS 26's corner
+  adaptation, injected by ml-trainer's native shell). Read with a `0px`
+  fallback.
+
+All of these are deliberately physical: they describe screen positions, so
+they must not flip with the reading direction. Rules that consume them per
+reading-order side mirror them explicitly under `dir=rtl` (see the drawer
+recipe's placement variants).
+
 ## Dark surfaces
 
 Focus indicators are surface-aware through one tag. The default focus ring

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@microbit/ui",
-  "version": "0.2.2",
+  "version": "0.3.1",
   "description": "micro:bit design-system primitives: react-aria-components + Panda CSS with a design language ported from Chakra UI v2. Ships as source; see README for the consumption setup.",
   "license": "MIT",
   "type": "module",
@@ -57,4 +57,4 @@
     "vite": "^7.3.6",
     "vitest": "^4.1.10"
   }
-}
+}

package/src/Avatar.tsx

@@ -103,6 +103,9 @@ const useImageStatus = (src?: string, srcSet?: string): ImageStatus => {
   );
   useEffect(() => {
     if (!src) {
+      // Resets for a removed src; a render-time reset is a behaviour change
+      // to review.
+      // eslint-disable-next-line react-hooks/set-state-in-effect
       setStatus("pending");
       return;
     }
@@ -233,6 +236,7 @@ export const Avatar = ({
       // directly in the flex container it is a flex item and centres
       // exactly.
       isValidElement(icon) ? (
+        // eslint-disable-next-line @eslint-react/no-clone-element -- labelling in place is the point, as above.
         cloneElement(icon as ReactElement<Record<string, unknown>>, {
           role: "img",
           "aria-label": iconLabel,

package/src/Collapse.tsx

@@ -73,6 +73,8 @@ export const Collapse = ({
     if (isOpen) {
       // Opening: mount (collapsed) first, then flip on the next frame so
       // the browser has a computed collapsed state to transition from.
+      // The mount-then-flip sequencing above depends on the effect timing.
+      // eslint-disable-next-line react-hooks/set-state-in-effect
       setPresent(true);
       const raf = requestAnimationFrame(() => {
         setAnimating(true);

package/src/ComboBox.tsx

@@ -166,7 +166,7 @@ const ComboBoxInner = <T extends object>(
     <SelectSlotProvider value={slots}>
       <RACComboBox
         allowsEmptyCollection={emptyState != null}
-        {...(rest as RACComboBoxProps<T>)}
+        {...rest}
         className={cx(fieldSlots.root, slots.root, className)}
       >
         {label != null && (

package/src/Drawer.recipe.ts

@@ -10,6 +10,13 @@ import { defineSlotRecipe } from "@pandacss/dev";
  * Drawer, which maps the slots onto react-aria-components' ModalOverlay /
  * Modal / Dialog.
  *
+ * The panel spans the full viewport height, so like the full-size dialog it
+ * pads by the safe-area insets and paints the status-bar strip with the
+ * brand `statusBarBg` gradient. The inline inset is applied per placement,
+ * since only the screen edge the drawer touches needs it, and uses the
+ * nav-side safe-area tokens (README: CSS-variable contract) so content can
+ * flow under a camera cutout.
+ *
  * The enter transition is a decelerating tween; the exit a 0.15s ease-in-out
  * tween.
  *
@@ -41,7 +48,12 @@ export const drawer = defineSlotRecipe({
       maxWidth: "xs",
       maxH: "100dvh",
       color: "inherit",
-      bg: "white",
+      // brand colour in the status-bar area, white below (matches the
+      // full-size dialog)
+      background:
+        "linear-gradient(to bottom, token(colors.statusBarBg) token(spacing.safeAreaTop), white token(spacing.safeAreaTop))",
+      paddingTop: "safeAreaTop",
+      paddingBottom: "safeAreaBottom",
       boxShadow: "lg",
       display: "flex",
       flexDirection: "column",
@@ -78,15 +90,18 @@ export const drawer = defineSlotRecipe({
   variants: {
     // Reading-order sides, so a drawer keeps its relationship to the content
     // in an RTL locale rather than its screen position. The slide-out
-    // transforms are physical, so each needs mirroring under `dir=rtl` to
-    // travel towards its own edge.
+    // transforms and the safe-area inline padding are physical, so each
+    // needs mirroring under `dir=rtl` to track its own screen edge.
     placement: {
       start: {
         content: {
           insetStart: 0,
+          paddingLeft: "safeAreaNavLeft",
           "&[data-entering]": { transform: "translateX(-100%)" },
           "&[data-exiting]": { transform: "translateX(-100%)" },
           _rtl: {
+            paddingLeft: "0px",
+            paddingRight: "safeAreaNavRight",
             "&[data-entering]": { transform: "translateX(100%)" },
             "&[data-exiting]": { transform: "translateX(100%)" },
           },
@@ -95,9 +110,12 @@ export const drawer = defineSlotRecipe({
       end: {
         content: {
           insetEnd: 0,
+          paddingRight: "safeAreaNavRight",
           "&[data-entering]": { transform: "translateX(100%)" },
           "&[data-exiting]": { transform: "translateX(100%)" },
           _rtl: {
+            paddingRight: "0px",
+            paddingLeft: "safeAreaNavLeft",
             "&[data-entering]": { transform: "translateX(-100%)" },
             "&[data-exiting]": { transform: "translateX(-100%)" },
           },

package/src/Input.recipe.ts

@@ -49,11 +49,11 @@ export const input = defineRecipe({
     "&&&:is([data-invalid], :user-invalid)": {
       borderColor: "danger.500",
     },
-    // Modality-tracked: RAC's attribute, or Input.tsx's. Native
+    // Modality-tracked: RAC's attribute, or Input/NativeSelect's. Native
     // :focus-visible is the fallback for a bare element wearing the recipe,
-    // but not text-entry ones — browsers match it there on a pointer click,
-    // which is what the tracking exists to exclude.
-    "&&&:is([data-focus-visible], :focus-visible:not([data-rac], input, textarea))":
+    // but not form controls — browsers match it there on a pointer click
+    // (Chrome includes select), which is what the tracking exists to exclude.
+    "&&&:is([data-focus-visible], :focus-visible:not([data-rac], input, textarea, select))":
       {
         focusRing: "outline",
       },

package/src/Modal.recipe.ts

@@ -149,20 +149,22 @@ export const dialog = defineSlotRecipe({
           my: "0",
           mx: "0",
           borderRadius: "0",
-          paddingTop: "env(safe-area-inset-top)",
-          paddingBottom: "env(safe-area-inset-bottom)",
-          paddingLeft: "env(safe-area-inset-left)",
-          paddingRight: "env(safe-area-inset-right)",
+          paddingTop: "safeAreaTop",
+          paddingBottom: "safeAreaBottom",
+          // The nav-side tokens (README: CSS-variable contract), so content
+          // can flow under a camera cutout.
+          paddingLeft: "safeAreaNavLeft",
+          paddingRight: "safeAreaNavRight",
           // brand colour in the status-bar area, white below (matches ActionBar)
           background:
-            "linear-gradient(to bottom, token(colors.statusBarBg) env(safe-area-inset-top), white env(safe-area-inset-top))",
+            "linear-gradient(to bottom, token(colors.statusBarBg) token(spacing.safeAreaTop), white token(spacing.safeAreaTop))",
         },
         header: {
           pl: "calc(var(--window-controls-left, 0px) + token(spacing.6))",
         },
         body: { flex: "1", overflowY: "auto" },
         closeTrigger: {
-          top: "calc(env(safe-area-inset-top) + token(spacing.2))",
+          top: "calc(token(spacing.safeAreaTop) + token(spacing.2))",
         },
       },
     },

package/src/NativeSelect.tsx

@@ -4,6 +4,7 @@
  * SPDX-License-Identifier: MIT
  */
 import { forwardRef, SelectHTMLAttributes } from "react";
+import { mergeProps, useFocusRing } from "react-aria";
 import { css, cx } from "styled-system/css";
 import { input, InputVariantProps } from "styled-system/recipes";
 import { SystemStyleObject } from "styled-system/types";
@@ -40,9 +41,14 @@ export const NativeSelect = forwardRef<HTMLSelectElement, NativeSelectProps>(
     { hideChevron = false, size, css: cssProp, wrapperCss, className, ...rest },
     ref,
   ) {
+    // Modality tracked here rather than via the recipe's native
+    // :focus-visible fallback: Chrome matches that on a clicked select (as it
+    // does on text inputs), and this ring is keyboard-only.
+    const { isFocusVisible, focusProps } = useFocusRing();
     const select = (
       <select
         ref={ref}
+        data-focus-visible={isFocusVisible || undefined}
         className={cx(
           input({ size }),
           css(
@@ -59,7 +65,7 @@ export const NativeSelect = forwardRef<HTMLSelectElement, NativeSelectProps>(
           ),
           className,
         )}
-        {...rest}
+        {...mergeProps(rest, focusProps)}
       />
     );
     if (hideChevron) {

package/src/Select.tsx

@@ -110,7 +110,7 @@ export const Select = <T extends object>({
   return (
     <SelectSlotProvider value={slots}>
       <RACSelect
-        {...(rest as RACSelectProps<T>)}
+        {...rest}
         className={cx(fieldSlots.root, slots.root, className)}
       >
         {label != null && (

package/src/SharedUIProvider.tsx

@@ -13,6 +13,7 @@ import {
 import { isRTL } from "react-aria";
 import { I18nProvider } from "react-aria-components";
 import { IntlContext } from "react-intl";
+import { SafeAreaNavSource, useSafeAreaNav } from "./hooks/useSafeAreaNav";
 import { racLocale } from "./rac-locale";
 
 /**
@@ -56,13 +57,22 @@ export interface SharedUIProviderProps {
    * the README's react-intl step).
    */
   setDocumentLang?: boolean;
+  /**
+   * The source for the `--safe-area-nav-*` variables (see the README's
+   * CSS-variable contract): a native shell with real inset metadata (e.g.
+   * Android's WindowInsets API via a Capacitor plugin). Pass it only in the
+   * app shell that provides it; without a source the variables stay unset
+   * and consumers fall back to the raw `env()` insets. Keep its identity
+   * stable.
+   */
+  safeAreaNavSource?: SafeAreaNavSource;
   children: ReactNode;
 }
 
 /**
  * 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.
+ * integrations: the optional overlay-close registrar, the locale for
+ * react-aria's built-in strings, and the safe-area nav variables.
  *
  * 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
@@ -75,8 +85,10 @@ export const SharedUIProvider = ({
   overlayCloseRegistrar,
   locale,
   setDocumentLang = true,
+  safeAreaNavSource,
   children,
 }: SharedUIProviderProps) => {
+  useSafeAreaNav(safeAreaNavSource);
   // 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;

package/src/Slider.tsx

@@ -100,7 +100,7 @@ export const Slider = ({
       formatOptions={formatOptions}
       className={cx(slots.root, cssProp ? css(cssProp) : undefined)}
     >
-      {mark && (
+      {mark ? (
         <div
           data-part="mark"
           className={cx(slots.mark, markCss ? css(markCss) : undefined)}
@@ -108,7 +108,7 @@ export const Slider = ({
         >
           {mark}
         </div>
-      )}
+      ) : null}
       <SliderTrack
         className={cx(slots.track, trackCss ? css(trackCss) : undefined)}
       >
@@ -120,7 +120,7 @@ export const Slider = ({
           style={{ width: `${percent}%` }}
         />
       </SliderTrack>
-      {thumbTooltip && isThumbTooltipOpen && (
+      {thumbTooltip && isThumbTooltipOpen ? (
         // Matches the shared Tooltip's look (tooltipBase) with a bottom
         // arrow, anchored above the thumb.
         <div
@@ -160,7 +160,7 @@ export const Slider = ({
         >
           {thumbTooltip}
         </div>
-      )}
+      ) : null}
       <SliderThumb
         onFocusChange={onThumbFocusChange}
         className={cx(slots.thumb, thumbCss ? css(thumbCss) : undefined)}

package/src/Toast.tsx

@@ -149,14 +149,14 @@ export const ToastProvider = () => {
                 )}
               />
               <div className={slots.body}>
-                {toast.content.title && (
+                {toast.content.title ? (
                   <p className={slots.title}>{toast.content.title}</p>
-                )}
-                {toast.content.description && (
+                ) : null}
+                {toast.content.description ? (
                   <div className={slots.description}>
                     {toast.content.description}
                   </div>
-                )}
+                ) : null}
               </div>
             </RACToastContent>
             {toast.content.isClosable && (

package/src/UnmountCallback.tsx

@@ -12,6 +12,9 @@ import { useEffect, useRef } from "react";
  */
 export const UnmountCallback = ({ callback }: { callback?: () => void }) => {
   const ref = useRef(callback);
+  // Latest-ref pattern: the unmount effect calls the current callback
+  // without re-subscribing.
+  // eslint-disable-next-line react-hooks/refs
   ref.current = callback;
   useEffect(() => () => ref.current?.(), []);
   return null;

package/src/base-preset.ts

@@ -171,7 +171,22 @@ export const basePreset = definePreset({
         brand: colors.blue,
         brand2: colors.gray,
       },
-      spacing,
+      spacing: {
+        ...spacing,
+        // The safe-area inset expressions, defined once (README: CSS-variable
+        // contract). The nav sides read the runtime `--safe-area-nav-*`
+        // variables with the raw env() insets as the fallback, so contexts
+        // without a SharedUIProvider safeAreaNavSource degrade to padding
+        // for every inset.
+        safeAreaTop: { value: "env(safe-area-inset-top)" },
+        safeAreaBottom: { value: "env(safe-area-inset-bottom)" },
+        safeAreaNavLeft: {
+          value: "var(--safe-area-nav-left, env(safe-area-inset-left))",
+        },
+        safeAreaNavRight: {
+          value: "var(--safe-area-nav-right, env(safe-area-inset-right))",
+        },
+      },
       sizes,
       fontSizes,
       fontWeights,

package/src/hooks/usePrevious.ts

@@ -11,5 +11,8 @@ export function usePrevious<T>(value: T): T | undefined {
   useEffect(() => {
     ref.current = value;
   });
+  // Reading the previous render's value during render is the point of this
+  // hook.
+  // eslint-disable-next-line react-hooks/refs
   return ref.current;
 }

package/src/hooks/useSafeAreaNav.ts

@@ -0,0 +1,51 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import { useLayoutEffect } from "react";
+
+/**
+ * The horizontal insets content must stay clear of, in CSS pixels.
+ */
+export interface SafeAreaNavInsets {
+  left: number;
+  right: number;
+}
+
+/**
+ * A source for the `--safe-area-nav-left`/`--safe-area-nav-right` variables
+ * (see the README's CSS-variable contract): a native shell with real inset
+ * metadata (e.g. Android's WindowInsets API via a Capacitor plugin), which
+ * can tell the navigation bar from a display cutout. Called with a callback
+ * to invoke with the current insets immediately and again on every change;
+ * returns an unsubscribe function. Keep the source's identity stable — a
+ * new function each render resubscribes.
+ */
+export type SafeAreaNavSource = (
+  onChange: (insets: SafeAreaNavInsets) => void,
+) => () => void;
+
+/**
+ * Keeps `--safe-area-nav-left`/`--safe-area-nav-right` on the document
+ * element in step with `source`; without one the variables stay unset and
+ * consumers fall back to the raw env() insets. Installed by
+ * SharedUIProvider; not exported from the package.
+ */
+export const useSafeAreaNav = (source?: SafeAreaNavSource) => {
+  useLayoutEffect(() => {
+    if (!source) {
+      return;
+    }
+    const root = document.documentElement;
+    const unsubscribe = source(({ left, right }) => {
+      root.style.setProperty("--safe-area-nav-left", `${left}px`);
+      root.style.setProperty("--safe-area-nav-right", `${right}px`);
+    });
+    return () => {
+      unsubscribe();
+      root.style.removeProperty("--safe-area-nav-left");
+      root.style.removeProperty("--safe-area-nav-right");
+    };
+  }, [source]);
+};

package/src/index.ts

@@ -63,6 +63,10 @@ export * from "./Tooltip";
 export * from "./TooltipButton";
 export * from "./Toast";
 export * from "./VisuallyHidden";
+export type {
+  SafeAreaNavInsets,
+  SafeAreaNavSource,
+} from "./hooks/useSafeAreaNav";
 export { useBreakpointValue } from "./hooks/useBreakpointValue";
 export { useClipboard } from "./hooks/useClipboard";
 export { useDisclosure } from "./hooks/useDisclosure";