@microbit/ui 0.1.0-alpha.9 → 0.1.0

package/src/Avatar.tsx

@@ -0,0 +1,278 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import {
+  cloneElement,
+  CSSProperties,
+  HTMLAttributes,
+  isValidElement,
+  ReactElement,
+  ReactNode,
+  SVGProps,
+  useEffect,
+  useState,
+} from "react";
+import { css, cx } from "styled-system/css";
+import { avatar, AvatarVariantProps } from "styled-system/recipes";
+import { token } from "styled-system/tokens";
+import { SystemStyleObject } from "styled-system/types";
+
+/**
+ * A djb2-style hash of the name, its low three bytes read as a colour. The
+ * same name is always the same colour, and the exact hash is a compatibility
+ * contract: apps' existing avatar rosters keep the colours they have always
+ * had, so don't change it.
+ */
+const colorFromName = (name: string): string => {
+  let hash = 0;
+  for (let i = 0; i < name.length; i += 1) {
+    hash = name.charCodeAt(i) + ((hash << 5) - hash);
+    hash = hash & hash;
+  }
+  let color = "#";
+  for (let j = 0; j < 3; j += 1) {
+    const value = (hash >> (j * 8)) & 255;
+    color += `00${value.toString(16)}`.slice(-2);
+  }
+  return color;
+};
+
+/**
+ * Contrast rule for the generated background: perceived brightness (the
+ * classic 299/587/114 weighting) below 128 counts as dark, and dark
+ * backgrounds take white text.
+ */
+const isLight = (hex: string): boolean => {
+  const r = parseInt(hex.slice(1, 3), 16);
+  const g = parseInt(hex.slice(3, 5), 16);
+  const b = parseInt(hex.slice(5, 7), 16);
+  return (r * 299 + g * 587 + b * 114) / 1000 >= 128;
+};
+
+/**
+ * First letter of the first and last words. Prefixed because it is exported
+ * from the package root, where a bare `initials` would be a broad name to
+ * claim.
+ */
+export const avatarInitials = (name: string): string => {
+  const names = name.trim().split(" ");
+  const firstName = names[0] ?? "";
+  const lastName = names.length > 1 ? names[names.length - 1] : "";
+  return firstName && lastName
+    ? `${firstName.charAt(0)}${lastName.charAt(0)}`
+    : firstName.charAt(0);
+};
+
+/**
+ * The generic person glyph, the fallback when there is no name. It inherits
+ * `currentColor` — white on the no-name grey background — so it stays visible
+ * if a call site recolours.
+ *
+ * The paths are Chakra UI's avatar glyph, inlined for visual parity with the
+ * apps' original look (see the notice in LICENSE.md).
+ */
+export const GenericAvatarIcon = (props: SVGProps<SVGSVGElement>) => (
+  <svg viewBox="0 0 128 128" width="100%" height="100%" {...props}>
+    <path
+      fill="currentColor"
+      d="M103,102.1388 C93.094,111.92 79.3504,118 64.1638,118 C48.8056,118 34.9294,111.768 25,101.7892 L25,95.2 C25,86.8096 31.981,80 40.6,80 L87.4,80 C96.019,80 103,86.8096 103,95.2 L103,102.1388 Z"
+    />
+    <path
+      fill="currentColor"
+      d="M63.9961647,24 C51.2938136,24 41,34.2938136 41,46.9961647 C41,59.7061864 51.2938136,70 63.9961647,70 C76.6985159,70 87,59.7061864 87,46.9961647 C87,34.2938136 76.6985159,24 63.9961647,24"
+    />
+  </svg>
+);
+
+type ImageStatus = "pending" | "loading" | "loaded" | "failed";
+
+/**
+ * Load the photo out of band and report how it went, so the avatar can show
+ * the initials or the icon meanwhile and keep showing them if it never
+ * arrives.
+ *
+ * The <img> element is only mounted once this says "loaded", which is what
+ * keeps a broken URL from leaving the browser's broken-image glyph inside the
+ * circle — the failure mode a fallback exists to prevent.
+ */
+const useImageStatus = (src?: string, srcSet?: string): ImageStatus => {
+  const [status, setStatus] = useState<ImageStatus>(
+    src ? "loading" : "pending",
+  );
+  useEffect(() => {
+    if (!src) {
+      setStatus("pending");
+      return;
+    }
+    // A new src starts again: without this the avatar would keep showing the
+    // previous person's photo, or stay stuck on a fallback it has outgrown.
+    setStatus("loading");
+    const img = new Image();
+    let current = true;
+    img.onload = () => {
+      if (current) {
+        setStatus("loaded");
+      }
+    };
+    img.onerror = () => {
+      if (current) {
+        setStatus("failed");
+      }
+    };
+    // srcSet before src, so the browser has the candidates to choose from
+    // when the load starts.
+    if (srcSet) {
+      img.srcset = srcSet;
+    }
+    img.src = src;
+    return () => {
+      current = false;
+      img.onload = null;
+      img.onerror = null;
+    };
+  }, [src, srcSet]);
+  return status;
+};
+
+export interface AvatarProps
+  extends Omit<HTMLAttributes<HTMLSpanElement>, "color" | "children">,
+    Pick<AvatarVariantProps, "size"> {
+  /**
+   * The person. Shown as initials, and hashed into the background colour, so
+   * two people are unlikely to share one.
+   */
+  name?: string;
+  /**
+   * Photo. The initials (or the icon) show until it has loaded, and go on
+   * showing if it fails — the avatar never renders a broken image.
+   */
+  src?: string;
+  srcSet?: string;
+  /** Shown when there is no name. Defaults to the generic person glyph. */
+  icon?: ReactNode;
+  /** Accessible name for the icon fallback. Defaults to " avatar". */
+  iconLabel?: string;
+  /** Override how a name becomes initials. */
+  getInitials?: (name: string) => string;
+  /** A 2px ring in the avatar's border colour. */
+  showBorder?: boolean;
+  /** An `AvatarBadge`. */
+  children?: ReactNode;
+  /** Per-instance style overrides, merged after the recipe. */
+  css?: SystemStyleObject;
+  className?: string;
+}
+
+/**
+ * Avatar — a circular identity marker showing a photo, the initials of a
+ * name, or a generic glyph, in a colour derived from the name.
+ *
+ * Decorative in most designs — pass `aria-hidden` where the name is already
+ * beside it.
+ */
+export const Avatar = ({
+  name,
+  src,
+  srcSet,
+  icon,
+  iconLabel = " avatar",
+  getInitials = avatarInitials,
+  showBorder,
+  size,
+  children,
+  css: cssProp,
+  className,
+  style,
+  ...rest
+}: AvatarProps) => {
+  const status = useImageStatus(src, srcSet);
+  const isLoaded = status === "loaded";
+  const slots = avatar({ size });
+  // Only while the image isn't showing.
+  const bg = name && !isLoaded ? colorFromName(name) : undefined;
+  return (
+    <span
+      {...rest}
+      data-loaded={isLoaded || undefined}
+      className={cx(
+        slots.root,
+        showBorder ? css({ borderWidth: "2px" }) : undefined,
+        cssProp ? css(cssProp) : undefined,
+        className,
+      )}
+      style={
+        bg
+          ? ({
+              ...style,
+              "--avatar-bg": bg,
+              // The contrast rule, as a variable rather than a state
+              // selector so a call site's `css` colour still wins (see the
+              // recipe).
+              "--avatar-color": isLight(bg)
+                ? token("colors.gray.800")
+                : token("colors.white"),
+            } as CSSProperties)
+          : style
+      }
+    >
+      {isLoaded ? (
+        <img
+          src={src}
+          srcSet={srcSet}
+          alt={name ?? iconLabel}
+          className={slots.image}
+        />
+      ) : name ? (
+        <span role="img" aria-label={name} className={slots.label}>
+          {getInitials(name)}
+        </span>
+      ) : // The icon is labelled in place rather than wrapped: a wrapper
+      // would make it an inline child with a line box of its own, where
+      // directly in the flex container it is a flex item and centres
+      // exactly.
+      isValidElement(icon) ? (
+        cloneElement(icon as ReactElement<Record<string, unknown>>, {
+          role: "img",
+          "aria-label": iconLabel,
+        })
+      ) : (
+        icon ?? <GenericAvatarIcon role="img" aria-label={iconLabel} />
+      )}
+      {children}
+    </span>
+  );
+};
+
+export interface AvatarBadgeProps
+  extends Omit<HTMLAttributes<HTMLDivElement>, "color">,
+    Pick<AvatarVariantProps, "placement"> {
+  children?: ReactNode;
+  /**
+   * Per-instance style overrides. The badge has no size of its own — call
+   * sites set one (`boxSize: "1.5em"` scales with the avatar).
+   */
+  css?: SystemStyleObject;
+  className?: string;
+}
+
+/** AvatarBadge — a status dot pinned to a corner of its `Avatar`. */
+export const AvatarBadge = ({
+  placement,
+  children,
+  css: cssProp,
+  className,
+  ...rest
+}: AvatarBadgeProps) => (
+  <div
+    {...rest}
+    className={cx(
+      avatar({ placement }).badge,
+      cssProp ? css(cssProp) : undefined,
+      className,
+    )}
+  >
+    {children}
+  </div>
+);

package/src/Breadcrumb.recipe.ts

@@ -0,0 +1,45 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import { defineSlotRecipe } from "@pandacss/dev";
+
+/**
+ * Breadcrumb slot recipe — a flex list with a separator between items. The
+ * links themselves are the shared `Link`, so there is no link slot; the
+ * current page renders as a plain span.
+ *
+ * Registered in the base preset (base-preset.ts). No variants, so it needs
+ * no `staticCss` entry.
+ */
+export const breadcrumb = defineSlotRecipe({
+  className: "breadcrumb",
+  slots: ["root", "list", "item", "separator"],
+  base: {
+    root: {},
+    list: {
+      display: "flex",
+      alignItems: "center",
+      listStyle: "none",
+      margin: 0,
+      padding: 0,
+    },
+    item: {
+      display: "inline-flex",
+      alignItems: "center",
+      // The separator renders inside every item (no children introspection);
+      // the last item's simply doesn't show.
+      "&:last-of-type [data-separator]": { display: "none" },
+    },
+    separator: {
+      mx: "2",
+      // A chevron separator points along the trail, so it has to turn round
+      // in RTL. Scoped to an svg because the default separator is the text
+      // "/", which would become "\": a caller passing a glyph owns its
+      // direction, one passing an icon gets it handled. Override via the
+      // separator slot's css for an icon that shouldn't turn.
+      _rtl: { "& svg": { transform: "scaleX(-1)" } },
+    },
+  },
+});

package/src/Breadcrumb.tsx

@@ -0,0 +1,114 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import { createContext, ReactNode, useContext } from "react";
+import { useIntl } from "react-intl";
+import { css, cx } from "styled-system/css";
+import { styled, type HTMLStyledProps } from "styled-system/jsx";
+import { breadcrumb } from "styled-system/recipes";
+import { SystemStyleObject } from "styled-system/types";
+import { Link } from "./Link";
+import { uiMessage } from "./messages";
+
+// The separator is declared once on the Breadcrumb and rendered by every
+// item; the current-page flag hops from BreadcrumbItem to the BreadcrumbLink
+// inside it.
+const SeparatorContext = createContext<ReactNode>("/");
+const CurrentPageContext = createContext(false);
+
+export interface BreadcrumbProps {
+  /** Between items; an element or string. Default "/". */
+  separator?: ReactNode;
+  /** Per-instance style overrides for the nav (e.g. fontSize). */
+  css?: SystemStyleObject;
+  className?: string;
+  /** BreadcrumbItems. */
+  children: ReactNode;
+}
+
+/**
+ * Breadcrumb — a navigation trail: nav > ol > li with a separator between
+ * items and the current page as plain text with `aria-current="page"`.
+ */
+export const Breadcrumb = ({
+  separator = "/",
+  css: cssProp,
+  className,
+  children,
+}: BreadcrumbProps) => {
+  const intl = useIntl();
+  const slots = breadcrumb();
+  return (
+    <nav
+      aria-label={intl.formatMessage(uiMessage("ui.breadcrumb"))}
+      className={cx(slots.root, cssProp ? css(cssProp) : undefined, className)}
+    >
+      <SeparatorContext.Provider value={separator}>
+        <ol className={slots.list}>{children}</ol>
+      </SeparatorContext.Provider>
+    </nav>
+  );
+};
+
+export interface BreadcrumbItemProps {
+  /**
+   * Marks this item as the current page: its BreadcrumbLink renders as a
+   * plain span with `aria-current="page"` rather than a link.
+   */
+  isCurrentPage?: boolean;
+  css?: SystemStyleObject;
+  className?: string;
+  children: ReactNode;
+}
+
+export const BreadcrumbItem = ({
+  isCurrentPage = false,
+  css: cssProp,
+  className,
+  children,
+}: BreadcrumbItemProps) => {
+  const separator = useContext(SeparatorContext);
+  const slots = breadcrumb();
+  return (
+    <li
+      className={cx(slots.item, cssProp ? css(cssProp) : undefined, className)}
+    >
+      <CurrentPageContext.Provider value={isCurrentPage}>
+        {children}
+      </CurrentPageContext.Provider>
+      <span
+        data-separator
+        role="presentation"
+        aria-hidden
+        className={slots.separator}
+      >
+        {separator}
+      </span>
+    </li>
+  );
+};
+
+export type BreadcrumbLinkProps = HTMLStyledProps<"a">;
+
+// The current page's text: same element shape as the link (so call-site
+// style props keep working) minus the interactivity.
+const CurrentPageText = styled("span");
+
+/**
+ * The trail's link: the shared `Link`, or a plain span with
+ * `aria-current="page"` inside an item marked `isCurrentPage`.
+ */
+export const BreadcrumbLink = (props: BreadcrumbLinkProps) => {
+  const isCurrentPage = useContext(CurrentPageContext);
+  if (isCurrentPage) {
+    const { href: _href, children, ...rest } = props;
+    return (
+      <CurrentPageText aria-current="page" {...rest}>
+        {children}
+      </CurrentPageText>
+    );
+  }
+  return <Link {...props} />;
+};

package/src/Button.recipe.ts

@@ -5,26 +5,24 @@
  */
 import { defineRecipe } from "@pandacss/dev";
 
-// Chakra's transition.property.common, inlined (Panda has no transitionProperty
-// token category). Matches Chakra's Button base transition.
+// The common transition-property list, inlined (Panda has no
+// transitionProperty token category). No box-shadow: focus indication
+// must never fade in.
 const transitionCommon =
-  "background-color, border-color, color, fill, stroke, opacity, box-shadow, transform";
+  "background-color, border-color, color, fill, stroke, opacity, transform";
 
 /**
- * Button recipe — Chakra's default Button base + sizes, with this app's
- * borderRadius (`button` = 2rem) and variant set ported from
- * `components/button.ts`. Interaction conditions (`_hover`/`_active`/
+ * Button recipe — the family button base + sizes, with the house
+ * borderRadius (`button` = 2rem). Interaction conditions (`_hover`/`_active`/
  * `_disabled`/`_focusVisible`) are widened in the preset to also match
- * react-aria-components' data attributes, so these Chakra-shaped variant
- * objects work unchanged on RAC's <Button>.
+ * react-aria-components' data attributes, so these variant objects work
+ * unchanged on RAC's <Button>.
  *
  * A config recipe (not a component cva): styles land in the `recipes` layer so
  * call sites can override with plain style props, and presets extend the
- * variants. This file holds the brand-independent variant set — the core
- * Chakra variants plus the family-wide `language`/`toolbar` variants; a
- * consuming app's preset extends it with app vocabulary (e.g. ml-trainer's
- * `led`/`record*`/`secondary-disabled`). Brand divergence within a variant is
- * token-driven (see the `languageText` semantic tokens).
+ * variants. Colour reaches a variant either through the `button.*` semantic
+ * tokens (the app's button idiom) or through `tone`, never through a per-app
+ * fork of a shape.
  *
  * Registered in the base preset (base-preset.ts).
  */
@@ -47,7 +45,7 @@ export const button = defineRecipe({
     verticalAlign: "middle",
     outline: "none",
     _focusVisible: {
-      focusShadow: "outline",
+      focusRing: "outline",
     },
     _disabled: {
       opacity: 0.4,
@@ -68,7 +66,7 @@ export const button = defineRecipe({
       xs: { h: "6", minW: "6", fontSize: "xs", px: "2" },
     },
     variant: {
-      // Chakra's unstyled reset + this app's border-radius removal.
+      // A full reset: the button renders as plain inline content.
       unstyled: {
         bg: "none",
         color: "inherit",
@@ -78,7 +76,7 @@ export const button = defineRecipe({
         p: "0",
         borderRadius: "unset",
       },
-      // Chakra's link layout (no padding/height) + this app's colours.
+      // Link-shaped button: no padding/height, underline on hover.
       link: {
         padding: 0,
         height: "auto",
@@ -92,13 +90,22 @@ export const button = defineRecipe({
           textDecoration: "underline",
         },
       },
+      // Colours come from the `button.*` semantic tokens so the family's two
+      // button idioms (brand-coloured vs black-on-white) share this recipe —
+      // see the token block in base-preset.ts.
       secondary: {
         borderWidth: "2px",
-        borderColor: "brand.500",
-        color: "brand.700",
+        borderColor: "button.secondaryBorder",
+        color: "button.secondaryText",
         bg: "transparent",
-        _hover: { borderColor: "brand.600" },
-        _active: { bg: "brand.50", borderColor: "brand.700" },
+        _hover: {
+          borderColor: "button.secondaryHoverBorder",
+          bg: "button.secondaryHoverBg",
+        },
+        _active: {
+          bg: "button.secondaryActiveBg",
+          borderColor: "button.secondaryActiveBorder",
+        },
       },
       ghost: {
         color: "black",
@@ -106,57 +113,88 @@ export const button = defineRecipe({
         _hover: { bg: "blackAlpha.50" },
         _active: { bg: "blackAlpha.100" },
       },
-      // Chakra had no `plain` variant, so `variant="plain"` fell through to
-      // base-only styling: a transparent, colour-inheriting button. Used for the
-      // action-bar icon-button menu triggers (settings/help), which supply their
-      // own colour and shape via instance styles.
+      // Base-only styling: a transparent, colour-inheriting button. Used for
+      // the action-bar icon-button menu triggers (settings/help), which supply
+      // their own colour and shape via instance styles.
       plain: {
         bg: "transparent",
         color: "inherit",
       },
       primary: {
         color: "white",
-        bg: "brand.500",
-        _hover: { bg: "brand.600", _disabled: { bg: "brand.500" } },
-        _active: { bg: "brand.700" },
+        bg: "button.primaryBg",
+        _hover: {
+          bg: "button.primaryHoverBg",
+          _disabled: { bg: "button.primaryBg" },
+        },
+        _active: { bg: "button.primaryActiveBg" },
       },
-      warning: {
+      // `solid`/`outline` are coloured by `tone`, and reference only the
+      // stops it guarantees (50/500/600/700). They are not `primary`/
+      // `secondary` in another colour: those follow the app's button idiom,
+      // which is black-on-white in half the family and so can't be a palette.
+      solid: {
+        color: "white",
+        bg: "colorPalette.500",
+        _hover: {
+          bg: "colorPalette.600",
+          _disabled: { bg: "colorPalette.500" },
+        },
+        _active: { bg: "colorPalette.700" },
+      },
+      // Border at 500 (a boundary needs only 3:1) so a `solid`/`outline`
+      // toggle pair shows the same edge either way; the label needs 600.
+      //
+      // Classroom restates two other outlines per call site — a neutral 1px
+      // grey one and a white-on-colour one. Promote either if a second
+      // consumer appears.
+      outline: {
         borderWidth: "2px",
-        borderColor: "danger.500",
-        color: "danger.500",
+        borderColor: "colorPalette.500",
+        color: "colorPalette.600",
         bg: "transparent",
-        _hover: { borderColor: "danger.600" },
-        _active: { bg: "danger.50", borderColor: "danger.500" },
+        _hover: { borderColor: "colorPalette.600", color: "colorPalette.700" },
+        _active: { bg: "colorPalette.50" },
       },
-      // Chakra's built-in solid + red colorScheme (destructive confirm
-      // buttons). Same values as `record` today, but a separate variant so
-      // recording UI and destructive actions can diverge - hence danger
-      // tokens here, red.* literals there.
-      warningSolid: {
-        color: "white",
-        bg: "danger.500",
-        _hover: { bg: "danger.600", _disabled: { bg: "danger.500" } },
-        _active: { bg: "danger.700" },
+      // Not a palette shape: a light fill under dark text is a different
+      // button from `solid`, and 350 exists in no other ramp.
+      neutral: {
+        color: "gray.800",
+        bg: "gray.100",
+        _hover: { bg: "gray.300", _disabled: { bg: "gray.100" } },
+        _active: { bg: "gray.350" },
       },
-      // Family-wide variants (every censused app has language- and
-      // toolbar-class buttons).
+      // Family-wide variant (every censused app has toolbar-class buttons).
+      // No ring override: the bar decides, and a dark one must spread
+      // `darkSurface` — an app adopting this variant needs the tag with it.
       toolbar: {
         color: "black",
         bg: "white",
         _hover: { bg: "whiteAlpha.900", _disabled: { bg: "white" } },
         _active: { bg: "whiteAlpha.800" },
-        _focusVisible: { focusShadow: "outlineDark" },
-      },
-      language: {
-        borderWidth: "2px",
-        borderColor: "gray.200",
-        color: "languageText",
-        _hover: { color: "languageTextHover", bg: "gray.100" },
       },
     },
+    /**
+     * The palette behind `solid`/`outline`. An allowlist rather than Panda's
+     * open `colorPalette` prop: if a shape reads a stop the palette doesn't
+     * define, the button renders as nothing at all, with no error anywhere
+     * (docs/hints.md). This is where a palette is vetted, and a tone should
+     * alias a whole ramp so it has nowhere to fall through. Apps may add
+     * their own.
+     */
+    tone: {
+      brand: { colorPalette: "brand" },
+      // The destructive role, which a brand preset can re-point.
+      danger: { colorPalette: "danger" },
+      // Conventional red that isn't destructive (record buttons), so
+      // deliberately not following a brand's error colour.
+      red: { colorPalette: "red" },
+    },
   },
   defaultVariants: {
     variant: "secondary",
     size: "md",
+    // Never absent: a shape with no palette renders nothing.
+    tone: "brand",
   },
 });