@microbit/ui 0.1.0-alpha.4 → 0.1.0-alpha.6

package/LICENSE.md

@@ -19,3 +19,35 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
+
+---
+
+## Third-party notices
+
+This package includes design tokens and component styling derived from
+[Chakra UI](https://github.com/chakra-ui/chakra-ui) v2: the token scales in
+`src/base-tokens.ts` were snapshotted from `@chakra-ui/theme`'s default
+values, and the component recipes were ported from Chakra's component styles.
+Chakra UI is used under the MIT License:
+
+> MIT License
+>
+> Copyright (c) 2019 Segun Adebayo
+>
+> Permission is hereby granted, free of charge, to any person obtaining a copy
+> of this software and associated documentation files (the "Software"), to deal
+> in the Software without restriction, including without limitation the rights
+> to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+> copies of the Software, and to permit persons to whom the Software is
+> furnished to do so, subject to the following conditions:
+>
+> The above copyright notice and this permission notice shall be included in all
+> copies or substantial portions of the Software.
+>
+> THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+> IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+> FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+> AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+> LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+> OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+> SOFTWARE.

package/README.md

@@ -1,7 +1,9 @@
 # @microbit/ui
 
 react-aria-components + Panda CSS primitives with a design language ported from
-the Micro:bit Educational Foundation apps' original Chakra UI v2 themes.
+the Micro:bit Educational Foundation apps' original
+[Chakra UI](https://chakra-ui.com/) v2 themes (see
+[Chakra UI heritage](#chakra-ui-heritage-and-license)).
 
 The package **ships as source**: components import `styled-system/*`, which
 each consumer generates with its own Panda preset stack. There is no build
@@ -154,8 +156,9 @@ the token is consumed.
 ## Runtime token lookups
 
 For values that feed _computation_ rather than stylesheets (canvas painting,
-colour math, inline `style` for data-driven values — see gotcha #9 in
-RAC-MIGRATION.md), import the runtime lookup:
+colour math, inline `style` for data-driven values — see gotcha #9 in the
+repo's [migration playbook](../../docs/migration-playbook.md)), import the
+runtime lookup:
 
 ```ts
 import { token } from "@microbit/ui"; // re-exports styled-system/tokens
@@ -188,3 +191,17 @@ Crowdin via the repo-root `npm run update-translations -- <path to extracted
 Crowdin ZIP>` (config-driven over packages in
 `bin/update-translations.cjs`), after which you run `npm run i18n:tidy`
 from the root.
+
+## Chakra UI heritage and license
+
+This package's design language began as a faithful port of
+[Chakra UI](https://chakra-ui.com/) v2's, done so the apps it serves could
+leave Chakra without a redesign: `src/base-tokens.ts` was snapshotted from
+`@chakra-ui/theme`'s default token scales, and the `*.recipe.ts` files were
+ported from Chakra's component styles onto Panda config recipes.
+However far it evolves from that starting point, it owes its foundations to
+Chakra. Thanks to Segun Adebayo and the Chakra UI contributors.
+
+The package is [MIT](LICENSE.md) © Micro:bit Educational Foundation and
+contributors; Chakra UI is MIT © Segun Adebayo, and its notice is carried
+in [LICENSE.md](LICENSE.md).

package/lang/ui.de.json

@@ -0,0 +1,22 @@
+{
+  "ui.close-action": {
+    "defaultMessage": "Schließen",
+    "description": "Close button text or label"
+  },
+  "ui.toast-status-error": {
+    "defaultMessage": "Error",
+    "description": "Announced by screen readers before an error notification"
+  },
+  "ui.toast-status-info": {
+    "defaultMessage": "Information",
+    "description": "Announced by screen readers before an informational notification"
+  },
+  "ui.toast-status-success": {
+    "defaultMessage": "Success",
+    "description": "Announced by screen readers before a success notification"
+  },
+  "ui.toast-status-warning": {
+    "defaultMessage": "Warning",
+    "description": "Announced by screen readers before a warning notification"
+  }
+}

package/lang/ui.ga-ie.json

@@ -0,0 +1,22 @@
+{
+  "ui.close-action": {
+    "defaultMessage": "Dún",
+    "description": "Close button text or label"
+  },
+  "ui.toast-status-error": {
+    "defaultMessage": "Error",
+    "description": "Announced by screen readers before an error notification"
+  },
+  "ui.toast-status-info": {
+    "defaultMessage": "Information",
+    "description": "Announced by screen readers before an informational notification"
+  },
+  "ui.toast-status-success": {
+    "defaultMessage": "Success",
+    "description": "Announced by screen readers before a success notification"
+  },
+  "ui.toast-status-warning": {
+    "defaultMessage": "Warning",
+    "description": "Announced by screen readers before a warning notification"
+  }
+}

package/lang/ui.zh-cn.json

@@ -0,0 +1,22 @@
+{
+  "ui.close-action": {
+    "defaultMessage": "关闭",
+    "description": "Close button text or label"
+  },
+  "ui.toast-status-error": {
+    "defaultMessage": "Error",
+    "description": "Announced by screen readers before an error notification"
+  },
+  "ui.toast-status-info": {
+    "defaultMessage": "Information",
+    "description": "Announced by screen readers before an informational notification"
+  },
+  "ui.toast-status-success": {
+    "defaultMessage": "Success",
+    "description": "Announced by screen readers before a success notification"
+  },
+  "ui.toast-status-warning": {
+    "defaultMessage": "Warning",
+    "description": "Announced by screen readers before a warning notification"
+  }
+}

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@microbit/ui",
-  "version": "0.1.0-alpha.4",
-  "description": "micro:bit design-system primitives: react-aria-components + Panda CSS with a Chakra v2 design language. Ships as source; see README for the consumption setup.",
+  "version": "0.1.0-alpha.6",
+  "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",
   "exports": {
     ".": "./src/index.ts",
     "./base-preset": "./src/base-preset.ts",
-    "./chakra-tokens": "./src/chakra-tokens.ts",
+    "./base-tokens": "./src/base-tokens.ts",
     "./messages": "./src/messages.ts",
     "./postcss-legacy-safari": "./postcss-legacy-safari.cjs",
     "./lang/*": "./lang/*"

package/src/Button.tsx

@@ -8,25 +8,10 @@ import {
   Button as RACButton,
   ButtonProps as RACButtonProps,
 } from "react-aria-components";
-import { css, cva, cx } from "styled-system/css";
+import { css, cx } from "styled-system/css";
 import { button, ButtonVariantProps } from "styled-system/recipes";
 import { SystemStyleObject } from "styled-system/types";
-
-// Chakra's ButtonIcon: keeps the glyph centred and spaced from the label
-// (iconSpacing 0.5rem).
-const buttonIcon = cva({
-  base: {
-    display: "inline-flex",
-    alignSelf: "center",
-    flexShrink: 0,
-  },
-  variants: {
-    side: {
-      left: { marginEnd: "2" },
-      right: { marginStart: "2" },
-    },
-  },
-});
+import { buttonIcon } from "./button-icon";
 
 export interface ButtonProps
   extends Omit<RACButtonProps, "className" | "children">,

package/src/Code.tsx

@@ -0,0 +1,20 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import { styled } from "styled-system/jsx";
+
+/**
+ * Code — inline code chip matching Chakra's <Code> (gray subtle, light mode).
+ */
+export const Code = styled("code", {
+  base: {
+    fontFamily: "mono",
+    fontSize: "sm",
+    px: "0.2em",
+    borderRadius: "sm",
+    bg: "gray.100",
+    color: "gray.800",
+  },
+});

package/src/Collapse.tsx

@@ -0,0 +1,168 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import {
+  CSSProperties,
+  ReactNode,
+  useEffect,
+  useLayoutEffect,
+  useRef,
+  useState,
+} from "react";
+import { css, cx } from "styled-system/css";
+import { SystemStyleObject } from "styled-system/types";
+
+export interface CollapseProps {
+  /** Expanded when true (Chakra's `in`). */
+  isOpen: boolean;
+  /** Height when collapsed (Chakra's `startingHeight`). */
+  startingHeight?: number | string;
+  /**
+   * Height when expanded (Chakra's `endingHeight`; defaults to the measured
+   * content height, tracked with a ResizeObserver so nested expansion works).
+   */
+  endingHeight?: number | string;
+  /** Remove the content from the DOM once the exit transition finishes. */
+  unmountOnExit?: boolean;
+  css?: SystemStyleObject;
+  className?: string;
+  style?: CSSProperties;
+  children: ReactNode;
+}
+
+const toCssSize = (v: number | string) =>
+  typeof v === "number" ? `${v}px` : v;
+
+/**
+ * Collapse — Chakra's Collapse transition without framer-motion: the content
+ * is measured and the wrapper's height (and opacity, when collapsing to zero)
+ * transitions between the collapsed and expanded sizes. Content stays mounted
+ * unless `unmountOnExit` is set.
+ *
+ * As with framer-motion, only `isOpen` changes animate: initial mounts render
+ * at rest, and height corrections (late measurement, content growth) snap —
+ * otherwise a collapse mounted inside an entering view morphs during the
+ * outer animation.
+ */
+export const Collapse = ({
+  isOpen,
+  startingHeight = 0,
+  endingHeight,
+  unmountOnExit = false,
+  css: cssProp,
+  className,
+  style,
+  children,
+}: CollapseProps) => {
+  const contentRef = useRef<HTMLDivElement>(null);
+  const [measuredHeight, setMeasuredHeight] = useState<number>();
+  // For unmountOnExit: stay in the DOM until the exit transition ends.
+  const [present, setPresent] = useState(isOpen);
+  // The state the DOM shows. It follows isOpen from a layout effect so the
+  // transition-enable and the height flip land in the same commit (a
+  // render-time flip detector is unreliable: React can discard renders,
+  // losing the state update while keeping ref mutations).
+  const [displayOpen, setDisplayOpen] = useState(isOpen);
+  const [animating, setAnimating] = useState(false);
+
+  useLayoutEffect(() => {
+    if (isOpen === displayOpen) {
+      return;
+    }
+    if (isOpen) {
+      // Opening: mount (collapsed) first, then flip on the next frame so
+      // the browser has a computed collapsed state to transition from.
+      setPresent(true);
+      const raf = requestAnimationFrame(() => {
+        setAnimating(true);
+        setDisplayOpen(true);
+      });
+      return () => cancelAnimationFrame(raf);
+    }
+    // Closing: enable the transition and flip together, pre-paint.
+    setAnimating(true);
+    setDisplayOpen(false);
+  }, [isOpen, displayOpen]);
+
+  useLayoutEffect(() => {
+    const el = contentRef.current;
+    if (!el || endingHeight !== undefined) {
+      return;
+    }
+    setMeasuredHeight(el.scrollHeight);
+    const observer = new ResizeObserver(() =>
+      setMeasuredHeight(el.scrollHeight),
+    );
+    observer.observe(el);
+    return () => observer.disconnect();
+  }, [endingHeight, present]);
+
+  // Fallback for browsers/edge cases where transitionend doesn't fire.
+  useEffect(() => {
+    if (animating) {
+      const timeout = setTimeout(() => {
+        setAnimating(false);
+        if (!isOpen && unmountOnExit) {
+          setPresent(false);
+        }
+      }, 400);
+      return () => clearTimeout(timeout);
+    }
+  }, [animating, isOpen, unmountOnExit]);
+
+  if (unmountOnExit && !present) {
+    return null;
+  }
+
+  const expanded =
+    endingHeight !== undefined
+      ? toCssSize(endingHeight)
+      : measuredHeight !== undefined
+        ? `${measuredHeight}px`
+        : "auto";
+  const collapsed = toCssSize(startingHeight);
+  const hideWhenCollapsed = collapsed === "0px" || collapsed === "0";
+
+  return (
+    <div
+      onTransitionEnd={(e) => {
+        if (e.propertyName === "height" && e.target === e.currentTarget) {
+          setAnimating(false);
+          if (!isOpen && unmountOnExit) {
+            setPresent(false);
+          }
+        }
+      }}
+      className={cx(
+        css(
+          {
+            overflow: "hidden",
+            display: "block",
+            transitionDuration: "0.25s",
+            transitionTimingFunction: "cubic-bezier(0.4, 0, 0.2, 1)",
+            _motionReduce: { transition: "none" },
+          },
+          cssProp,
+        ),
+        className,
+      )}
+      // Runtime-measured/caller-supplied heights; transitions enabled only
+      // while an isOpen change is in flight.
+      style={{
+        transitionProperty: animating ? "height, opacity" : "none",
+        height: displayOpen ? expanded : collapsed,
+        opacity: displayOpen || !hideWhenCollapsed ? 1 : 0,
+        // At rest fully-collapsed, remove the content from the a11y tree
+        // and tab order, as Chakra did (kept visible while animating so
+        // the exit transition shows).
+        visibility:
+          displayOpen || animating || !hideWhenCollapsed ? undefined : "hidden",
+        ...style,
+      }}
+    >
+      <div ref={contentRef}>{children}</div>
+    </div>
+  );
+};

package/src/Divider.tsx

@@ -3,19 +3,50 @@
  *
  * SPDX-License-Identifier: MIT
  */
+import { ComponentProps, forwardRef } from "react";
 import { styled } from "styled-system/jsx";
 
-/**
- * Divider — a horizontal rule matching Chakra's <Divider> (hairline at 60%
- * opacity; set `borderColor` to tint). Horizontal only.
- */
-export const Divider = styled("hr", {
+const StyledDivider = styled("hr", {
   base: {
     border: 0,
-    borderBottomWidth: "1px",
-    borderBottomStyle: "solid",
     borderColor: "gray.200",
     opacity: 0.6,
-    width: "100%",
   },
+  variants: {
+    orientation: {
+      horizontal: {
+        borderBottomWidth: "1px",
+        borderBottomStyle: "solid",
+        width: "100%",
+      },
+      vertical: {
+        borderLeftWidth: "1px",
+        borderLeftStyle: "solid",
+        height: "100%",
+      },
+    },
+  },
+  defaultVariants: { orientation: "horizontal" },
 });
+
+export interface DividerProps extends ComponentProps<typeof StyledDivider> {}
+
+/**
+ * Divider — a hairline rule matching Chakra's <Divider> (60% opacity; set
+ * `borderColor` to tint). `orientation="vertical"` needs a height from the
+ * layout, e.g. a stretched flex row (Chakra's vertical divider likewise
+ * relied on `height: 100%`).
+ */
+export const Divider = forwardRef<HTMLHRElement, DividerProps>(
+  function Divider(props, ref) {
+    return (
+      <StyledDivider
+        ref={ref}
+        aria-orientation={
+          props.orientation === "vertical" ? "vertical" : "horizontal"
+        }
+        {...props}
+      />
+    );
+  },
+);

package/src/Fade.tsx

@@ -0,0 +1,48 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import { ReactNode } from "react";
+import { css, cx } from "styled-system/css";
+import { SystemStyleObject } from "styled-system/types";
+
+export interface FadeProps {
+  /** Visible when true; faded out (but mounted) when false. */
+  isOpen: boolean;
+  css?: SystemStyleObject;
+  className?: string;
+  children: ReactNode;
+}
+
+/**
+ * Fade — Chakra's Fade transition as a CSS opacity transition (see Slide for
+ * the pattern). Content stays mounted throughout.
+ */
+export const Fade = ({
+  isOpen,
+  css: cssProp,
+  className,
+  children,
+}: FadeProps) => (
+  <div
+    data-open={isOpen ? "" : undefined}
+    className={cx(
+      css(
+        {
+          opacity: 0,
+          pointerEvents: "none",
+          "&[data-open]": { opacity: 1, pointerEvents: "auto" },
+          transitionProperty: "opacity",
+          transitionDuration: "0.2s",
+          transitionTimingFunction: "ease-out",
+          _motionReduce: { transition: "none" },
+        },
+        cssProp,
+      ),
+      className,
+    )}
+  >
+    {children}
+  </div>
+);

package/src/IconButton.tsx

@@ -10,7 +10,12 @@ export interface IconButtonProps
   extends Omit<ButtonProps, "leftIcon" | "rightIcon"> {
   /** Icon-only buttons have no visible label, so this is required. */
   "aria-label": string;
-  /** Circular rather than the recipe's border-radius (Chakra's `isRound`). */
+  /**
+   * Circular rather than the recipe's border-radius (Chakra's `isRound`).
+   * Usually a visual no-op here: the 2rem `button` radius already renders
+   * square icon buttons as circles. Kept for ported call sites and for
+   * variants/overrides with a smaller radius (e.g. `unstyled`).
+   */
   isRound?: boolean;
 }
 

package/src/Kbd.tsx

@@ -0,0 +1,26 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import { styled } from "styled-system/jsx";
+
+/**
+ * Kbd — keyboard-key chip matching Chakra's <Kbd> (light mode).
+ */
+export const Kbd = styled("kbd", {
+  base: {
+    bg: "gray.100",
+    borderRadius: "md",
+    borderWidth: "1px",
+    borderStyle: "solid",
+    borderColor: "gray.200",
+    borderBottomWidth: "3px",
+    fontFamily: "mono",
+    fontSize: "0.8em",
+    fontWeight: "bold",
+    lineHeight: "normal",
+    px: "0.4em",
+    whiteSpace: "nowrap",
+  },
+});

package/src/LinkButton.tsx

@@ -0,0 +1,80 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import { forwardRef, ReactNode } from "react";
+import {
+  Link as RACLink,
+  LinkProps as RACLinkProps,
+} from "react-aria-components";
+import { css, cx } from "styled-system/css";
+import { button, ButtonVariantProps } from "styled-system/recipes";
+import { SystemStyleObject } from "styled-system/types";
+import { buttonIcon } from "./button-icon";
+
+export interface LinkButtonProps
+  extends Omit<RACLinkProps, "className" | "children">,
+    ButtonVariantProps {
+  /** Per-instance style overrides, merged after the recipe. */
+  css?: SystemStyleObject;
+  className?: string;
+  /** Icon rendered before the label, matching Chakra's `leftIcon`. */
+  leftIcon?: ReactNode;
+  /** Icon rendered after the label, matching Chakra's `rightIcon`. */
+  rightIcon?: ReactNode;
+  children?: ReactNode;
+}
+
+// Anchors pick up underline styling that buttons never have.
+const linkReset = css.raw({
+  textDecoration: "none",
+  _hover: { textDecoration: "none" },
+});
+
+/**
+ * LinkButton — a navigation link that looks like a Button (Chakra's
+ * `Button as="a"`). react-aria-components <Link> renders a real anchor
+ * (`href`, `target`, new-tab/middle-click semantics preserved) with the same
+ * interaction data attributes as Button, so the `button` recipe's
+ * hover/press/focus/disabled states apply unchanged.
+ *
+ * Use for navigation that should read as a call to action (e.g. an external
+ * help page presented as a dialog's primary action); use Button for
+ * in-page actions.
+ */
+export const LinkButton = forwardRef<HTMLAnchorElement, LinkButtonProps>(
+  function LinkButton(
+    {
+      variant,
+      size,
+      css: cssProp,
+      className,
+      leftIcon,
+      rightIcon,
+      children,
+      ...rest
+    },
+    ref,
+  ) {
+    return (
+      <RACLink
+        ref={ref}
+        className={cx(
+          button({ variant, size }),
+          css(linkReset, cssProp),
+          className,
+        )}
+        {...rest}
+      >
+        {leftIcon ? (
+          <span className={buttonIcon({ side: "left" })}>{leftIcon}</span>
+        ) : null}
+        {children}
+        {rightIcon ? (
+          <span className={buttonIcon({ side: "right" })}>{rightIcon}</span>
+        ) : null}
+      </RACLink>
+    );
+  },
+);

package/src/List.tsx

@@ -6,10 +6,14 @@
 import { styled } from "styled-system/jsx";
 
 /**
- * Unstyled list, matching Chakra's <List> (Panda's preflight already zeroes
- * margins/padding and removes list markers).
+ * Unstyled list, matching Chakra's <List>. The marker removal is explicit —
+ * Chakra's List set listStyleType itself, and coexisting apps run without
+ * Panda's preflight (margins/padding are zeroed by whichever reset is
+ * active).
  */
-export const List = styled("ul");
+export const List = styled("ul", {
+  base: { listStyleType: "none" },
+});
 
 /** List item, matching Chakra's <ListItem>. */
 export const ListItem = styled("li", {

package/src/Menu.recipe.ts

@@ -18,7 +18,17 @@ import { defineSlotRecipe } from "@pandacss/dev";
  */
 export const menu = defineSlotRecipe({
   className: "menu",
-  slots: ["content", "list", "item", "icon", "label", "divider"],
+  slots: [
+    "content",
+    "list",
+    "item",
+    "icon",
+    "label",
+    "divider",
+    "group",
+    "groupTitle",
+    "itemIndicator",
+  ],
   base: {
     content: {
       bg: "white",
@@ -84,5 +94,26 @@ export const menu = defineSlotRecipe({
       my: "2",
       opacity: 0.6,
     },
+    group: {},
+    // Chakra's MenuGroup/MenuOptionGroup title.
+    groupTitle: {
+      display: "block",
+      mx: "4",
+      my: "2",
+      fontWeight: "semibold",
+      fontSize: "sm",
+    },
+    // Check glyph slot for MenuItemOption: space always reserved (as Chakra
+    // does), visible only on the selected item (RAC sets data-selected on it).
+    itemIndicator: {
+      display: "inline-flex",
+      alignItems: "center",
+      justifyContent: "center",
+      flexShrink: 0,
+      marginEnd: "0.75rem",
+      fontSize: "0.8em",
+      opacity: 0,
+      "[data-selected] &": { opacity: 1 },
+    },
   },
 });