npm - @microbit/ui - Versions diffs - 0.1.0-alpha.23 → 0.1.0-alpha.25 - Mend

@microbit/ui 0.1.0-alpha.23 → 0.1.0-alpha.25

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (27) hide show

package/README.md CHANGED Viewed

@@ -13,9 +13,8 @@ PostCSS plugin for the CSS).
 ## App-side installation
-This package's own Storybook (`.storybook/` + `panda.config.ts`) is a
-worked example of the setup below, minus the app/brand presets. Everything
-an app must do:
+The repo's Storybook harness (`apps/storybook`) is a worked example of the
+setup below, minus the app/brand presets. Everything an app must do:
 1. **Panda preset stack** (`panda.config.ts`): `@pandacss/preset-base`, then
    the **base preset** (`@microbit/ui/base-preset` — the complete micro:bit
@@ -42,7 +41,7 @@ an app must do:
 3. **Resolve `styled-system/*` onto the generated output** for all
    importers, this package's source included — a `styled-system` alias in
    both `tsconfig.json` `paths` and the bundler config (see the
-   `viteFinal` in `.storybook/main.ts`).
+   `viteFinal` in `apps/storybook`'s `.storybook/main.ts`).
 4. **Generate and load the CSS** with Panda's PostCSS plugin. Keep Vite's
    default transformer — do **not** set `css.transformer: "lightningcss"`,
    which disables PostCSS. Add a `postcss.config.cjs`:
@@ -72,8 +71,9 @@ an app must do:
    width but no colour render `currentColor` borders.
    The `vendor` layer is for third-party stylesheets: import any vendor CSS
    with `@import "..." layer(vendor)` so it beats the preflight reset but
-   loses to app styling. See `.storybook/{layers.css,preview.tsx,main.ts}` +
-   `postcss.config.cjs` for the worked example.
+   loses to app styling. See `apps/storybook`'s
+   `.storybook/{layers.css,preview.tsx,main.ts}` + `postcss.config.cjs` for
+   the worked example.
 5. **react-intl**: an `IntlProvider` above any shared-ui usage. English
    works with no setup (components carry inline `defaultMessage`); for
@@ -87,11 +87,25 @@ node_modules/@microbit/ui/lang/ui.fr.json --ast --out-file ...` (multiple
 6. **`SharedUIProvider`** inside the `IntlProvider`, wrapping the app. It
    passes the locale on to react-aria, which translates its own built-in
    strings (see [Strings](#strings)); without it those follow the browser
-   rather than the app's language setting. Also takes an optional
+   rather than the app's language setting. It also keeps `<html lang>` in
+   step with the locale so assistive tech announces the page in the app's
+   language — pass `setDocumentLang={false}` where the app doesn't own the
+   document it's mounted in (an embedded widget). Also takes an optional
    overlay-close registrar, so the app can dismiss open menus from outside
    the tree (e.g. the Android hardware back button).
 7. **`ToastProvider`** once near the root, inside the two providers above.
+## Upgrading in an app
+After bumping the `@microbit/ui` version:
+1. `npm install` — the apps' postinstall runs `panda codegen`, but incremental
+   codegen does not detect external preset changes, so regenerate clean:
+   `rm -rf styled-system && npm run panda`.
+2. `npm run i18n:compile` — recompiles the app's per-locale catalogs so new
+   and retranslated `ui.*` strings ship (otherwise they fall back to English,
+   or stay missing).
 ## Legacy browser support (Safari < 15) — temporary
 Panda's output uses two things Safari below 15 mishandles. If an app must

package/lang/ui.ca.json CHANGED Viewed

@@ -19,6 +19,10 @@
     "defaultMessage": "S'està carregant",
     "description": "Announced by screen readers for a button showing a loading spinner"
   },
+  "ui.new-tab-notice": {
+    "defaultMessage": "opens in a new tab",
+    "description": "Visually hidden suffix on links that open a new tab, announced by screen readers"
+  },
   "ui.numberfield-decrease": {
     "defaultMessage": "Decrementa {fieldLabel}",
     "description": "Accessible label for a number field's decrement stepper; fieldLabel is the field's label and may be empty"

package/lang/ui.cy.json CHANGED Viewed

@@ -19,6 +19,10 @@
     "defaultMessage": "Wrthi'n Llwytho",
     "description": "Announced by screen readers for a button showing a loading spinner"
   },
+  "ui.new-tab-notice": {
+    "defaultMessage": "opens in a new tab",
+    "description": "Visually hidden suffix on links that open a new tab, announced by screen readers"
+  },
   "ui.numberfield-decrease": {
     "defaultMessage": "Decrease {fieldLabel}",
     "description": "Accessible label for a number field's decrement stepper; fieldLabel is the field's label and may be empty"

package/lang/ui.de.json CHANGED Viewed

@@ -19,6 +19,10 @@
     "defaultMessage": "Laden",
     "description": "Announced by screen readers for a button showing a loading spinner"
   },
+  "ui.new-tab-notice": {
+    "defaultMessage": "opens in a new tab",
+    "description": "Visually hidden suffix on links that open a new tab, announced by screen readers"
+  },
   "ui.numberfield-decrease": {
     "defaultMessage": "{fieldLabel} verringern",
     "description": "Accessible label for a number field's decrement stepper; fieldLabel is the field's label and may be empty"

package/lang/ui.en-us.json CHANGED Viewed

@@ -19,6 +19,10 @@
     "defaultMessage": "Loading",
     "description": "Announced by screen readers for a button showing a loading spinner"
   },
+  "ui.new-tab-notice": {
+    "defaultMessage": "opens in a new tab",
+    "description": "Visually hidden suffix on links that open a new tab, announced by screen readers"
+  },
   "ui.numberfield-decrease": {
     "defaultMessage": "Decrease {fieldLabel}",
     "description": "Accessible label for a number field's decrement stepper; fieldLabel is the field's label and may be empty"

package/lang/ui.en.json CHANGED Viewed

@@ -19,6 +19,10 @@
     "defaultMessage": "Loading",
     "description": "Announced by screen readers for a button showing a loading spinner"
   },
+  "ui.new-tab-notice": {
+    "defaultMessage": "opens in a new tab",
+    "description": "Visually hidden suffix on links that open a new tab, announced by screen readers"
+  },
   "ui.numberfield-decrease": {
     "defaultMessage": "Decrease {fieldLabel}",
     "description": "Accessible label for a number field's decrement stepper; fieldLabel is the field's label and may be empty"

package/lang/ui.es-es.json CHANGED Viewed

@@ -19,6 +19,10 @@
     "defaultMessage": "Cargando",
     "description": "Announced by screen readers for a button showing a loading spinner"
   },
+  "ui.new-tab-notice": {
+    "defaultMessage": "opens in a new tab",
+    "description": "Visually hidden suffix on links that open a new tab, announced by screen readers"
+  },
   "ui.numberfield-decrease": {
     "defaultMessage": "Reducir {fieldLabel}",
     "description": "Accessible label for a number field's decrement stepper; fieldLabel is the field's label and may be empty"

package/lang/ui.fr.json CHANGED Viewed

@@ -19,6 +19,10 @@
     "defaultMessage": "Chargement",
     "description": "Announced by screen readers for a button showing a loading spinner"
   },
+  "ui.new-tab-notice": {
+    "defaultMessage": "opens in a new tab",
+    "description": "Visually hidden suffix on links that open a new tab, announced by screen readers"
+  },
   "ui.numberfield-decrease": {
     "defaultMessage": "Diminuer {fieldLabel}",
     "description": "Accessible label for a number field's decrement stepper; fieldLabel is the field's label and may be empty"

package/lang/ui.ga-ie.json CHANGED Viewed

@@ -19,6 +19,10 @@
     "defaultMessage": "Ag lódáil",
     "description": "Announced by screen readers for a button showing a loading spinner"
   },
+  "ui.new-tab-notice": {
+    "defaultMessage": "opens in a new tab",
+    "description": "Visually hidden suffix on links that open a new tab, announced by screen readers"
+  },
   "ui.numberfield-decrease": {
     "defaultMessage": "Decrease {fieldLabel}",
     "description": "Accessible label for a number field's decrement stepper; fieldLabel is the field's label and may be empty"

package/lang/ui.it.json CHANGED Viewed

@@ -19,6 +19,10 @@
     "defaultMessage": "Caricamento",
     "description": "Announced by screen readers for a button showing a loading spinner"
   },
+  "ui.new-tab-notice": {
+    "defaultMessage": "opens in a new tab",
+    "description": "Visually hidden suffix on links that open a new tab, announced by screen readers"
+  },
   "ui.numberfield-decrease": {
     "defaultMessage": "Riduci {fieldLabel}",
     "description": "Accessible label for a number field's decrement stepper; fieldLabel is the field's label and may be empty"

package/lang/ui.ja.json CHANGED Viewed

@@ -19,6 +19,10 @@
     "defaultMessage": "読み込み中",
     "description": "Announced by screen readers for a button showing a loading spinner"
   },
+  "ui.new-tab-notice": {
+    "defaultMessage": "opens in a new tab",
+    "description": "Visually hidden suffix on links that open a new tab, announced by screen readers"
+  },
   "ui.numberfield-decrease": {
     "defaultMessage": "{fieldLabel}を縮小",
     "description": "Accessible label for a number field's decrement stepper; fieldLabel is the field's label and may be empty"

package/lang/ui.ko.json CHANGED Viewed

@@ -19,6 +19,10 @@
     "defaultMessage": "불러오는 중...",
     "description": "Announced by screen readers for a button showing a loading spinner"
   },
+  "ui.new-tab-notice": {
+    "defaultMessage": "opens in a new tab",
+    "description": "Visually hidden suffix on links that open a new tab, announced by screen readers"
+  },
   "ui.numberfield-decrease": {
     "defaultMessage": "{fieldLabel} 감소",
     "description": "Accessible label for a number field's decrement stepper; fieldLabel is the field's label and may be empty"

package/lang/ui.lo.json CHANGED Viewed

@@ -19,6 +19,10 @@
     "defaultMessage": "ກຳລັງໂຫຼດ",
     "description": "Announced by screen readers for a button showing a loading spinner"
   },
+  "ui.new-tab-notice": {
+    "defaultMessage": "opens in a new tab",
+    "description": "Visually hidden suffix on links that open a new tab, announced by screen readers"
+  },
   "ui.numberfield-decrease": {
     "defaultMessage": "Decrease {fieldLabel}",
     "description": "Accessible label for a number field's decrement stepper; fieldLabel is the field's label and may be empty"

package/lang/ui.lol.json CHANGED Viewed

@@ -19,6 +19,10 @@
     "defaultMessage": "Loading",
     "description": "Announced by screen readers for a button showing a loading spinner"
   },
+  "ui.new-tab-notice": {
+    "defaultMessage": "opens in a new tab",
+    "description": "Visually hidden suffix on links that open a new tab, announced by screen readers"
+  },
   "ui.numberfield-decrease": {
     "defaultMessage": "Decrease {fieldLabel}",
     "description": "Accessible label for a number field's decrement stepper; fieldLabel is the field's label and may be empty"

package/lang/ui.nl.json CHANGED Viewed

@@ -19,6 +19,10 @@
     "defaultMessage": "Laden",
     "description": "Announced by screen readers for a button showing a loading spinner"
   },
+  "ui.new-tab-notice": {
+    "defaultMessage": "opens in a new tab",
+    "description": "Visually hidden suffix on links that open a new tab, announced by screen readers"
+  },
   "ui.numberfield-decrease": {
     "defaultMessage": "Verlaag {fieldLabel}",
     "description": "Accessible label for a number field's decrement stepper; fieldLabel is the field's label and may be empty"

package/lang/ui.pl.json CHANGED Viewed

@@ -19,6 +19,10 @@
     "defaultMessage": "Ładowanie",
     "description": "Announced by screen readers for a button showing a loading spinner"
   },
+  "ui.new-tab-notice": {
+    "defaultMessage": "opens in a new tab",
+    "description": "Visually hidden suffix on links that open a new tab, announced by screen readers"
+  },
   "ui.numberfield-decrease": {
     "defaultMessage": "Zmniejsz {fieldLabel}",
     "description": "Accessible label for a number field's decrement stepper; fieldLabel is the field's label and may be empty"

package/lang/ui.pt-br.json CHANGED Viewed

@@ -19,6 +19,10 @@
     "defaultMessage": "Carregando",
     "description": "Announced by screen readers for a button showing a loading spinner"
   },
+  "ui.new-tab-notice": {
+    "defaultMessage": "opens in a new tab",
+    "description": "Visually hidden suffix on links that open a new tab, announced by screen readers"
+  },
   "ui.numberfield-decrease": {
     "defaultMessage": "Diminuir {fieldLabel}",
     "description": "Accessible label for a number field's decrement stepper; fieldLabel is the field's label and may be empty"

package/lang/ui.vi.json CHANGED Viewed

@@ -19,6 +19,10 @@
     "defaultMessage": "Đang tải",
     "description": "Announced by screen readers for a button showing a loading spinner"
   },
+  "ui.new-tab-notice": {
+    "defaultMessage": "opens in a new tab",
+    "description": "Visually hidden suffix on links that open a new tab, announced by screen readers"
+  },
   "ui.numberfield-decrease": {
     "defaultMessage": "Giảm {fieldLabel}",
     "description": "Accessible label for a number field's decrement stepper; fieldLabel is the field's label and may be empty"

package/lang/ui.zh-cn.json CHANGED Viewed

@@ -19,6 +19,10 @@
     "defaultMessage": "正在加载",
     "description": "Announced by screen readers for a button showing a loading spinner"
   },
+  "ui.new-tab-notice": {
+    "defaultMessage": "opens in a new tab",
+    "description": "Visually hidden suffix on links that open a new tab, announced by screen readers"
+  },
   "ui.numberfield-decrease": {
     "defaultMessage": "降低 {fieldLabel}",
     "description": "Accessible label for a number field's decrement stepper; fieldLabel is the field's label and may be empty"

package/lang/ui.zh-tw.json CHANGED Viewed

@@ -19,6 +19,10 @@
     "defaultMessage": "正在載入",
     "description": "Announced by screen readers for a button showing a loading spinner"
   },
+  "ui.new-tab-notice": {
+    "defaultMessage": "opens in a new tab",
+    "description": "Visually hidden suffix on links that open a new tab, announced by screen readers"
+  },
   "ui.numberfield-decrease": {
     "defaultMessage": "縮小 {fieldLabel}",
     "description": "Accessible label for a number field's decrement stepper; fieldLabel is the field's label and may be empty"

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@microbit/ui",
-  "version": "0.1.0-alpha.23",
+  "version": "0.1.0-alpha.25",
   "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",
@@ -27,11 +27,7 @@
     "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"
+    "test": "vitest run"
   },
   "peerDependencies": {
     "@pandacss/dev": "^1.11.4",
@@ -55,7 +51,6 @@
     "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"

package/src/Button.recipe.ts CHANGED Viewed

@@ -154,8 +154,7 @@ export const button = defineRecipe({
         _hover: { bg: "danger.600", _disabled: { bg: "danger.500" } },
         _active: { bg: "danger.700" },
       },
-      // Family-wide variants (every censused app has language- and
-      // toolbar-class buttons).
+      // Family-wide variant (every censused app has toolbar-class buttons).
       toolbar: {
         color: "black",
         bg: "white",
@@ -163,12 +162,6 @@ export const button = defineRecipe({
         _active: { bg: "whiteAlpha.800" },
         _focusVisible: { focusShadow: "outlineDark" },
       },
-      language: {
-        borderWidth: "2px",
-        borderColor: "gray.200",
-        color: "languageText",
-        _hover: { color: "languageTextHover", bg: "gray.100" },
-      },
     },
   },
   defaultVariants: {

package/src/ExternalLink.tsx ADDED Viewed

@@ -0,0 +1,47 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import { ComponentProps } from "react";
+import { RiExternalLinkLine } from "react-icons/ri";
+import { FormattedMessage } from "react-intl";
+import { Icon } from "./Icon";
+import { Link } from "./Link";
+import { uiMessage } from "./messages";
+import { VisuallyHidden } from "./VisuallyHidden";
+export type ExternalLinkProps = Omit<
+  ComponentProps<typeof Link>,
+  "target" | "rel"
+>;
+/**
+ * ExternalLink — a Link that opens in a new tab and says so both ways: a
+ * trailing external-link glyph for sighted users, and a visually hidden,
+ * translated "opens in a new tab" for assistive tech. Use this rather than
+ * restating `target="_blank"` + icon so the announcement can't be forgotten.
+ *
+ * For app chrome, where a new tab protects the user's session-only state.
+ * Content surfaces should prefer same-tab links, or a visible
+ * "(opens in new tab)" suffix and no icon.
+ *
+ * Inline-safe: the icon is 1em and follows the text colour, so the link can
+ * sit in prose as well as stand alone.
+ */
+export const ExternalLink = ({ children, ...props }: ExternalLinkProps) => (
+  <Link {...props} target="_blank" rel="noopener">
+    {children}
+    <VisuallyHidden>
+      {/* The comma separates the suffix in the accessible name: inline nodes
+          concatenate without a space, and leading whitespace is trimmed. */}
+      {", "}
+      <FormattedMessage {...uiMessage("ui.new-tab-notice")} />
+    </VisuallyHidden>
+    <Icon
+      as={RiExternalLinkLine}
+      aria-hidden
+      css={{ verticalAlign: "text-bottom", ml: 1 }}
+    />
+  </Link>
+);

package/src/SharedUIProvider.tsx CHANGED Viewed

@@ -3,7 +3,13 @@
  *
  * SPDX-License-Identifier: MIT
  */
-import { createContext, ReactNode, useContext, useMemo } from "react";
+import {
+  createContext,
+  ReactNode,
+  useContext,
+  useEffect,
+  useMemo,
+} from "react";
 import { I18nProvider } from "react-aria-components";
 import { IntlContext } from "react-intl";
 import { racLocale } from "./rac-locale";
@@ -30,6 +36,14 @@ export interface SharedUIProviderProps {
    * two must differ.
    */
   locale?: string;
+  /**
+   * Keeps `<html lang>` in step with the locale, so assistive tech announces
+   * the page in the app's language. On by default; set false where the app
+   * doesn't own the document it's mounted in (an embedded widget), or when
+   * mounting more than one provider per page. The static `lang="en"` in
+   * index.html remains the pre-hydration default.
+   */
+  setDocumentLang?: boolean;
   children: ReactNode;
 }
@@ -48,20 +62,25 @@ export interface SharedUIProviderProps {
 export const SharedUIProvider = ({
   overlayCloseRegistrar,
   locale,
+  setDocumentLang = true,
   children,
 }: SharedUIProviderProps) => {
   // 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;
+  const appLocale = locale ?? intlLocale;
+  useEffect(() => {
+    if (setDocumentLang && appLocale) {
+      document.documentElement.lang = appLocale;
+    }
+  }, [setDocumentLang, appLocale]);
   const value = useMemo(
     () => ({ overlayCloseRegistrar }),
     [overlayCloseRegistrar],
   );
   return (
     <SharedUIContext.Provider value={value}>
-      <I18nProvider locale={racLocale(locale ?? intlLocale)}>
-        {children}
-      </I18nProvider>
+      <I18nProvider locale={racLocale(appLocale)}>{children}</I18nProvider>
     </SharedUIContext.Provider>
   );
 };

package/src/Toast.tsx CHANGED Viewed

@@ -56,11 +56,20 @@ const wrapUpdate = (fn: () => void) => {
     activeTransitions++;
     document.documentElement.classList.add(TRANSITION_CLASS);
     const transition = document.startViewTransition(fn);
-    transition.finished.finally(() => {
+    // A transition is routinely skipped — another update starts one while
+    // this is still animating, or the tab is hidden — and the browser then
+    // rejects its promises with "AbortError: Transition was skipped". The
+    // DOM update has still run; only the animation is dropped. Settle on
+    // rejection too (`.finally()` would re-throw, surfacing routine skips
+    // as unhandled rejections in error reporting) and swallow `ready`,
+    // which some engines reject without marking handled.
+    transition.ready.catch(() => {});
+    const settle = () => {
       if (--activeTransitions === 0) {
         document.documentElement.classList.remove(TRANSITION_CLASS);
       }
-    });
+    };
+    transition.finished.then(settle, settle);
   } else {
     fn();
   }

package/src/base-preset.ts CHANGED Viewed

@@ -86,7 +86,7 @@ const gray = {
  * The base preset: the complete, working micro:bit design system. The base
  * token scales (base-tokens.ts), the micro:bit house style
  * (pill `radii.button`, `outline*` focus shadows, Helvetica fonts, the
- * `language`/`toolbar` button variants in Button.recipe.ts, the
+ * `toolbar` button variant in Button.recipe.ts, the
  * `languageText`/`toast*Bg`/`statusBarBg` semantic tokens), the shared-ui
  * component recipes, the react-aria condition widening, the `globalCss`
  * defaults, and the `staticCss` that keeps runtime-prop recipe
@@ -207,11 +207,12 @@ export const basePreset = definePreset({
           600: { value: "{colors.red.600}" },
           700: { value: "{colors.red.700}" },
         },
-        // The `language` button variant's text colour follows the primary
-        // interactive brand: every consumer resolves it to its `brand` ramp
-        // (CreateAI privately to brand.600 with no hover change,
-        // python-editor to brand.500/600 — the default). Semantic tokens so
-        // the recipe stays shared and a brand preset overrides only values.
+        // The language-dialog cards' text colour (@microbit/ui-patterns'
+        // LanguageDialog) follows the primary interactive brand: every
+        // consumer resolves it to its `brand` ramp (CreateAI privately to
+        // brand.600 with no hover change, python-editor to brand.500/600 —
+        // the default; data-microbit-org to black). Semantic tokens so the
+        // pattern stays shared and a brand preset overrides only values.
         languageText: { value: "{colors.brand.500}" },
         languageTextHover: { value: "{colors.brand.600}" },
         // The `label`/`subtitle` heading variants' colour (page-title chrome).
@@ -288,7 +289,8 @@ export const basePreset = definePreset({
       touchAction: "manipulation",
     },
     body: {
-      position: "relative",
+      // No `position: relative` (Chakra had it): it breaks react-aria's
+      // overlay positioning — see Tooltip's "In a scrolling page" story.
       minHeight: "100%",
       fontFeatureSettings: '"kern"',
       fontFamily: "body",

package/src/index.ts CHANGED Viewed

@@ -40,6 +40,7 @@ export * from "./Text";
 export * from "./TextField";
 export * from "./Heading";
 export * from "./Link";
+export * from "./ExternalLink";
 export * from "./Icon";
 export * from "./CloseButton";
 export * from "./CloseIcon";