@microbit/ui 0.1.0-alpha.3 → 0.1.0-alpha.31

package/src/Avatar.recipe.ts

@@ -0,0 +1,191 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import { defineSlotRecipe } from "@pandacss/dev";
+
+/**
+ * Avatar slot recipe — a circle showing an image, the initials of a name, or
+ * a generic person glyph, optionally with a badge pinned to one corner.
+ *
+ * The background and text colour come from `var(--avatar-bg)` and
+ * `var(--avatar-color)` rather than being flat values, because the component
+ * derives them from the name (see Avatar.tsx) and writes them as inline custom
+ * properties. Two reasons, both about letting a call site win with a plain
+ * `css={{ bg: …, color: … }}`: an inline *property* would beat any class,
+ * where an inline *variable* only feeds this declaration; and both must stay
+ * single-class selectors, since a state selector like `&[data-light-bg]`
+ * would outrank the call site's utility class on specificity.
+ *
+ * The `calc(size / 2.5)` font size is resolved per size so an app preset can
+ * restate either independently (classroom's avatars are a grade larger).
+ *
+ * Registered in the base preset (base-preset.ts), which also has the
+ * `staticCss` entry that keeps the runtime-prop variants generated.
+ */
+export const avatar = defineSlotRecipe({
+  className: "avatar",
+  slots: ["root", "label", "image", "badge"],
+  base: {
+    root: {
+      display: "inline-flex",
+      alignItems: "center",
+      justifyContent: "center",
+      flexShrink: 0,
+      position: "relative",
+      verticalAlign: "top",
+      textAlign: "center",
+      textTransform: "uppercase",
+      fontWeight: "medium",
+      borderRadius: "full",
+      // The no-name defaults; the name-derived pair arrives inline.
+      // gray.350 is the decorative-fill stop — 400+ are reserved for
+      // accessible outlines and text (see the ramp in base-preset.ts).
+      background: "var(--avatar-bg, token(colors.gray.350))",
+      color: "var(--avatar-color, token(colors.white))",
+      borderColor: "white",
+    },
+    label: {
+      lineHeight: "1",
+    },
+    image: {
+      width: "100%",
+      height: "100%",
+      objectFit: "cover",
+      borderRadius: "inherit",
+    },
+    badge: {
+      position: "absolute",
+      display: "flex",
+      alignItems: "center",
+      justifyContent: "center",
+      borderRadius: "full",
+      // em-relative, so a badge keeps its proportions at every avatar size.
+      borderWidth: "0.2em",
+      borderStyle: "solid",
+      borderColor: "white",
+      // The corner variants pin the badge with logical insets but nudge it
+      // out over the edge with a transform, which is physical — so the
+      // outward direction is a variable the RTL rule negates. Without it a
+      // `start` badge would sit at the right corner and nudge left, i.e.
+      // inwards over the avatar.
+      // 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.
+      transform:
+        "translate(var(--avatar-badge-x, 0px), var(--avatar-badge-y, 0px))",
+      _rtl: {
+        transform:
+          "translate(calc(-1 * var(--avatar-badge-x, 0px)), var(--avatar-badge-y, 0px))",
+      },
+    },
+  },
+  variants: {
+    // The container size, and the `calc(size / 2.5)` font size kept as a
+    // calc over the same token so both track a preset that rescales `sizes`
+    // (the dense preset does, by 0.88).
+    //
+    // The font size lands on the root *and* the label. They are separate
+    // declarations so an app can
+    // move one without the other: the root's is the em basis for a badge,
+    // the label's is how big the initials are, and the two are not always
+    // the same wish.
+    size: {
+      "2xs": {
+        root: {
+          width: "4",
+          height: "4",
+          fontSize: "calc(token(sizes.4) / 2.5)",
+        },
+        label: { fontSize: "calc(token(sizes.4) / 2.5)" },
+      },
+      xs: {
+        root: {
+          width: "6",
+          height: "6",
+          fontSize: "calc(token(sizes.6) / 2.5)",
+        },
+        label: { fontSize: "calc(token(sizes.6) / 2.5)" },
+      },
+      sm: {
+        root: {
+          width: "8",
+          height: "8",
+          fontSize: "calc(token(sizes.8) / 2.5)",
+        },
+        label: { fontSize: "calc(token(sizes.8) / 2.5)" },
+      },
+      md: {
+        root: {
+          width: "12",
+          height: "12",
+          fontSize: "calc(token(sizes.12) / 2.5)",
+        },
+        label: { fontSize: "calc(token(sizes.12) / 2.5)" },
+      },
+      lg: {
+        root: {
+          width: "16",
+          height: "16",
+          fontSize: "calc(token(sizes.16) / 2.5)",
+        },
+        label: { fontSize: "calc(token(sizes.16) / 2.5)" },
+      },
+      xl: {
+        root: {
+          width: "24",
+          height: "24",
+          fontSize: "calc(token(sizes.24) / 2.5)",
+        },
+        label: { fontSize: "calc(token(sizes.24) / 2.5)" },
+      },
+      "2xl": {
+        root: {
+          width: "32",
+          height: "32",
+          fontSize: "calc(token(sizes.32) / 2.5)",
+        },
+        label: { fontSize: "calc(token(sizes.32) / 2.5)" },
+      },
+    },
+    /** Which corner the badge sits in. */
+    placement: {
+      "top-start": {
+        badge: {
+          top: "0",
+          insetStart: "0",
+          "--avatar-badge-x": "-25%",
+          "--avatar-badge-y": "-25%",
+        },
+      },
+      "top-end": {
+        badge: {
+          top: "0",
+          insetEnd: "0",
+          "--avatar-badge-x": "25%",
+          "--avatar-badge-y": "-25%",
+        },
+      },
+      "bottom-start": {
+        badge: {
+          bottom: "0",
+          insetStart: "0",
+          "--avatar-badge-x": "-25%",
+          "--avatar-badge-y": "25%",
+        },
+      },
+      "bottom-end": {
+        badge: {
+          bottom: "0",
+          insetEnd: "0",
+          "--avatar-badge-x": "25%",
+          "--avatar-badge-y": "25%",
+        },
+      },
+    },
+  },
+  defaultVariants: {
+    size: "md",
+    placement: "bottom-end",
+  },
+});

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} />;
+};