@microbit/ui 0.0.0-gray.ramp.90

package/lang/ui.zh-tw.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

@@ -0,0 +1,66 @@
+{
+  "name": "@microbit/ui",
+  "version": "0.0.0-gray.ramp.90",
+  "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",
+    "./base-tokens": "./src/base-tokens.ts",
+    "./dense-preset": "./src/dense-preset.ts",
+    "./messages": "./src/messages.ts",
+    "./postcss-legacy-safari": "./postcss-legacy-safari.cjs",
+    "./reset.css": "./reset.css",
+    "./lang/*": "./lang/*"
+  },
+  "files": [
+    "src",
+    "lang",
+    "postcss-legacy-safari.cjs",
+    "reset.css",
+    "README.md",
+    "LICENSE.md"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "panda": "panda codegen",
+    "typecheck": "npm run panda && tsc --noEmit",
+    "pretest": "npm run panda",
+    "test": "vitest run",
+    "prestorybook": "npm run panda",
+    "storybook": "storybook dev -p 6006 --no-open",
+    "prebuild-storybook": "npm run panda",
+    "build-storybook": "storybook build"
+  },
+  "peerDependencies": {
+    "@pandacss/dev": "^1.11.4",
+    "react": "^18.3.1",
+    "react-aria-components": "^1.19.0",
+    "react-icons": "^4.12.0 || ^5.0.0",
+    "react-intl": "^6.6.8 || ^7.0.0"
+  },
+  "devDependencies": {
+    "@pandacss/dev": "^1.11.4",
+    "@storybook/react-vite": "^10.5.2",
+    "@testing-library/react": "^16.3.2",
+    "@testing-library/user-event": "^14.6.1",
+    "@types/node": "^26.1.1",
+    "@types/react": "^18.3.3",
+    "@types/react-dom": "^18.3.0",
+    "@vitejs/plugin-react": "^4.5.2",
+    "jsdom": "^29.1.1",
+    "react": "^18.3.1",
+    "react-aria-components": "^1.19.0",
+    "react-dom": "^18.3.1",
+    "react-icons": "^4.12.0",
+    "react-intl": "^6.6.8",
+    "storybook": "^10.5.2",
+    "typescript": "^5.4.2",
+    "vite": "^6.3.5",
+    "vitest": "^4.1.10"
+  },
+  "publishConfig": {
+    "tag": "gray-ramp"
+  }
+}

package/postcss-legacy-safari.cjs

@@ -0,0 +1,96 @@
+/*
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ *
+ * TEMPORARY compatibility shim for consuming apps that still support Safari
+ * below 15. Delete this file (and the app-side wiring — see the README) once
+ * every consuming app has raised its support floor past the affected browsers.
+ *
+ * The bug: Safari 14.x silently drops logical *shorthands* whose value
+ * contains var() — `padding-inline: var(--spacing-2)` applies nothing, even
+ * though `padding-inline: 10px` (literal) and `padding-inline-start:
+ * var(--spacing-2)` (longhand) both work. Panda emits these shorthands for its
+ * px/py/mx/my utilities, so the bug removes most token-based spacing.
+ *
+ * The fix: rewrite the inline/block logical shorthands into their -start/-end
+ * longhands. Kept logical (not physical left/right) so RTL still flips.
+ *
+ * This is one of TWO legacy concerns for the same era of browsers; the other
+ * is @layer, which those browsers drop wholesale. Apps also run
+ * @csstools/postcss-cascade-layers (de-layering) and pin build.cssTarget — see
+ * the "Legacy browser support" section of the README. All of it is expected to
+ * be removed together when the floor rises.
+ *
+ * Exposed as a PostCSS plugin factory:
+ *   const { expandLogicalShorthands } = require("@microbit/ui/postcss-legacy-safari");
+ *   module.exports = { plugins: [expandLogicalShorthands(), ...] };
+ */
+
+// Logical shorthands whose value is `<start> <end>` (one value applies to
+// both). NOT included: border-inline / border-block — those are compound
+// (`width style color`) and duplicate the whole value to each side rather than
+// splitting, so they would need different handling. Add them explicitly if a
+// consuming app ever emits them.
+const LOGICAL_SHORTHANDS = {
+  "padding-inline": ["padding-inline-start", "padding-inline-end"],
+  "padding-block": ["padding-block-start", "padding-block-end"],
+  "margin-inline": ["margin-inline-start", "margin-inline-end"],
+  "margin-block": ["margin-block-start", "margin-block-end"],
+  "inset-inline": ["inset-inline-start", "inset-inline-end"],
+  "inset-block": ["inset-block-start", "inset-block-end"],
+  "scroll-margin-inline": [
+    "scroll-margin-inline-start",
+    "scroll-margin-inline-end",
+  ],
+  "scroll-margin-block": [
+    "scroll-margin-block-start",
+    "scroll-margin-block-end",
+  ],
+  "scroll-padding-inline": [
+    "scroll-padding-inline-start",
+    "scroll-padding-inline-end",
+  ],
+  "scroll-padding-block": [
+    "scroll-padding-block-start",
+    "scroll-padding-block-end",
+  ],
+};
+
+// Split a value on top-level whitespace, ignoring spaces inside parens so
+// var() fallbacks stay intact. One value applies to both sides; two map to
+// start then end (per the CSS shorthand rules).
+const splitTopLevel = (value) => {
+  const parts = [];
+  let depth = 0;
+  let current = "";
+  for (const ch of value) {
+    if (ch === "(") depth++;
+    else if (ch === ")") depth--;
+    if (depth === 0 && /\s/.test(ch)) {
+      if (current.trim()) parts.push(current.trim());
+      current = "";
+    } else {
+      current += ch;
+    }
+  }
+  if (current.trim()) parts.push(current.trim());
+  return parts;
+};
+
+const expandLogicalShorthands = () => ({
+  postcssPlugin: "microbit-ui-expand-logical-shorthands",
+  Declaration(decl) {
+    const longhands = LOGICAL_SHORTHANDS[decl.prop.toLowerCase()];
+    if (!longhands) return;
+    const parts = splitTopLevel(decl.value);
+    if (parts.length === 0) return;
+    const [start, end = start] = parts;
+    decl.cloneBefore({ prop: longhands[0], value: start });
+    decl.cloneBefore({ prop: longhands[1], value: end });
+    decl.remove();
+  },
+});
+expandLogicalShorthands.postcss = true;
+
+module.exports = { expandLogicalShorthands };

package/reset.css

@@ -0,0 +1,35 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ *
+ * Chakra-reset parity that must live in the `reset` cascade layer: import
+ * from the app's layers.css with
+ *
+ *   @import "@microbit/ui/reset.css" layer(reset);
+ *
+ * Deliberately not in the preset's globalCss: globalCss emits into the
+ * `base` layer, and the legacy-Safari cascade-layer flattening
+ * specificity-boosts base+ rules above CSS it can't see (runtime-injected
+ * styles such as CodeMirror themes, and other per-file-processed app CSS).
+ * A reset must stay at the bottom of the cascade in production exactly as
+ * it is in dev — see playbook gotcha #28.
+ */
+*,
+*::before,
+*::after {
+  border-color: var(--colors-gray-200);
+  word-wrap: break-word;
+}
+
+/*
+ * Panda's preflight (base layer) beats the rule above with
+ * `border-color: var(--global-color-border, currentcolor)`. The currentcolor
+ * fallback poisons `border-color: inherit` chains (inherit copies the
+ * currentcolor KEYWORD, which then resolves against the child's own `color`
+ * — e.g. white on the checkbox/radio control). Defining the hook keeps the
+ * default border colour a real colour, as Chakra's global reset did.
+ */
+:root {
+  --global-color-border: var(--colors-gray-200);
+}

package/src/Avatar.recipe.ts

@@ -0,0 +1,168 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import { defineSlotRecipe } from "@pandacss/dev";
+
+/**
+ * Avatar slot recipe — Chakra's avatar: 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 — exactly as Chakra did. 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]` outranks the call site's utility class on
+ * specificity wherever cascade layers aren't in play — which is every app
+ * still coexisting with Chakra (playbook gotcha #40).
+ *
+ * Sizes are Chakra's, with its `calc(size / 2.5)` font size resolved per size
+ * so an app preset can restate either independently (classroom's avatars are
+ * a grade larger than Chakra's).
+ *
+ * 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",
+      // Chakra's no-name defaults; the name-derived pair arrives inline.
+      background: "var(--avatar-bg, token(colors.gray.400))",
+      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",
+    },
+  },
+  variants: {
+    // Chakra's scale: the container size, and Chakra's `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, as Chakra's did
+    // (through one variable). 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. Chakra's placements, same offsets. */
+    placement: {
+      "top-start": {
+        badge: {
+          top: "0",
+          insetStart: "0",
+          transform: "translate(-25%, -25%)",
+        },
+      },
+      "top-end": {
+        badge: { top: "0", insetEnd: "0", transform: "translate(25%, -25%)" },
+      },
+      "bottom-start": {
+        badge: {
+          bottom: "0",
+          insetStart: "0",
+          transform: "translate(-25%, 25%)",
+        },
+      },
+      "bottom-end": {
+        badge: { bottom: "0", insetEnd: "0", transform: "translate(25%, 25%)" },
+      },
+    },
+  },
+  defaultVariants: {
+    size: "md",
+    placement: "bottom-end",
+  },
+});

package/src/Avatar.tsx

@@ -0,0 +1,276 @@
+/**
+ * (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";
+
+/**
+ * Chakra's `randomColor({ string })`, reproduced exactly: a djb2-style hash of
+ * the name, its low three bytes read as a colour. Not random despite the name
+ * — the same name is always the same colour, which is the point, and
+ * reproducing the hash means avatars keep the colours they had under Chakra.
+ */
+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;
+};
+
+/**
+ * Chakra's 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;
+};
+
+/**
+ * Chakra's `initials`: 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);
+};
+
+/**
+ * Chakra's generic person glyph, the fallback when there is no name. Chakra
+ * hardcoded it white; here it inherits `currentColor`, which is the same white
+ * on the no-name grey background and stays visible if a call site recolours.
+ */
+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";
+
+/**
+ * Chakra's `useImage`: 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 Chakra's person glyph. */
+  icon?: ReactNode;
+  /** Accessible name for the icon fallback. Chakra's default was " avatar". */
+  iconLabel?: string;
+  /** Override how a name becomes initials. */
+  getInitials?: (name: string) => string;
+  /** Chakra's `showBorder`: 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 — Chakra's <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, as Chakra's call sites did.
+ */
+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, matching Chakra's `:not([data-loaded])`.
+  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,
+              // Chakra's 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, as Chakra did:
+      // 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 — Chakra's
+   * didn't either, so 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>
+);