@microbit/ui 0.2.1 → 0.3.0

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.1",
+  "version": "0.3.0",
   "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/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/Modal.tsx

@@ -9,6 +9,8 @@ import {
   ReactNode,
   RefObject,
   useContext,
+  useEffect,
+  useRef,
 } from "react";
 import {
   Button as RACButton,
@@ -28,6 +30,92 @@ import { dataAttrs } from "./data-attrs";
 import { uiMessage } from "./messages";
 import { UnmountCallback } from "./UnmountCallback";
 
+// react-aria's tabbable selector, which it doesn't export. It special-cases
+// radio groups (only the checked radio is tabbable) where this doesn't — an
+// acceptable divergence for the shim below, whose worst case on a miss is
+// standing aside and leaving the keystroke to FocusScope, as without it.
+const TABBABLE_SELECTOR = [
+  "input:not([disabled]):not([type=hidden])",
+  "select:not([disabled])",
+  "textarea:not([disabled])",
+  "button:not([disabled])",
+  "a[href]",
+  "area[href]",
+  "summary",
+  "iframe",
+  "object",
+  "embed",
+  "audio[controls]",
+  "video[controls]",
+  "[contenteditable]:not([contenteditable^='false'])",
+  "[tabindex]:not([disabled])",
+]
+  .map((s) => `${s}:not([hidden]):not([tabindex='-1'])`)
+  .join(",");
+
+const isTabbable = (element: Element) =>
+  !element.closest("[inert]") &&
+  (element.checkVisibility?.({ visibilityProperty: true }) ?? true);
+
+/**
+ * Tab handling for iframes in the dialog, which react-aria's focus
+ * containment gets wrong in Firefox: FocusScope re-implements Tab as a
+ * synchronous programmatic focus of the next tabbable element, and Firefox
+ * silently drops a synchronous focus() of a cross-origin iframe made during
+ * key event dispatch — the keystroke appears to do nothing. The same call
+ * deferred to the next frame works, so this capture-phase listener (which
+ * runs before FocusScope's bubble-phase one) claims the keystroke whenever
+ * the element Tab would move to is an iframe, and performs the move
+ * deferred. Every other Tab is left to FocusScope. Remove if react-aria
+ * defers iframe focus itself.
+ */
+const IframeTabShim = ({
+  containerRef,
+}: {
+  containerRef: RefObject<HTMLElement | null>;
+}) => {
+  useEffect(() => {
+    const onKeyDown = (e: KeyboardEvent) => {
+      if (
+        e.key !== "Tab" ||
+        e.altKey ||
+        e.ctrlKey ||
+        e.metaKey ||
+        e.isComposing
+      ) {
+        return;
+      }
+      const container = containerRef.current;
+      const active = container?.ownerDocument.activeElement;
+      if (!container || !active || !container.contains(active)) {
+        return;
+      }
+      const tabbables = Array.from(
+        container.querySelectorAll<HTMLElement>(TABBABLE_SELECTOR),
+      ).filter(isTabbable);
+      const index = tabbables.indexOf(active as HTMLElement);
+      if (index === -1) {
+        return;
+      }
+      const target =
+        tabbables[
+          (index + (e.shiftKey ? -1 : 1) + tabbables.length) % tabbables.length
+        ];
+      if (!(target instanceof HTMLIFrameElement)) {
+        return;
+      }
+      e.preventDefault();
+      // Keep FocusScope's own document-level handler from also acting.
+      e.stopImmediatePropagation();
+      requestAnimationFrame(() => target.focus());
+    };
+    const doc = containerRef.current?.ownerDocument ?? document;
+    doc.addEventListener("keydown", onKeyDown, true);
+    return () => doc.removeEventListener("keydown", onKeyDown, true);
+  }, [containerRef]);
+  return null;
+};
+
 type DialogSlots = ReturnType<typeof dialog>;
 
 const SlotContext = createContext<{ slots: DialogSlots; onClose: () => void }>({
@@ -163,6 +251,7 @@ export const Modal = ({
   // prop over the context, and so do we for the close function.
   const triggerState = useContext(OverlayTriggerStateContext);
   const close = onClose ?? (() => triggerState?.close());
+  const contentRef = useRef<HTMLDivElement>(null);
   const dataProps = dataAttrs(rest);
   const slots = dialog({ size, centered: isCentered });
   const motionlessClass = motionless
@@ -205,6 +294,7 @@ export const Modal = ({
       <UnmountCallback callback={handleUnmount} />
       <RACModal
         {...dataProps}
+        ref={contentRef}
         style={contentStyle}
         className={cx(
           slots.content,
@@ -213,6 +303,7 @@ export const Modal = ({
         )}
       >
         <Dialog role={role} aria-label={ariaLabel} className={slots.inner}>
+          <IframeTabShim containerRef={contentRef} />
           <SlotContext.Provider value={{ slots, onClose: close }}>
             {children}
           </SlotContext.Provider>

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";