@microbit/ui-code-view 0.0.0-stage → 0.1.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Micro:bit Educational Foundation and contributors
+
+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,3 +1,145 @@
-# Temporary Holding Version
+# @microbit/ui-code-view
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Read-only, syntax-highlighted code views for micro:bit web apps, styled to
+match the editors the code comes from. Successor to
+`@microbit-foundation/react-code-view`.
+
+## What's here
+
+- **`PythonEditorCodeView`** — Python, styled like the micro:bit Python
+  Editor.
+- **`MakeCodeJavaScriptCodeView`** — MakeCode JavaScript, styled like
+  MakeCode's JavaScript view.
+
+Both take a `code` prop and show line numbers. An optional `className` goes on
+the outermost element, for example to make the background transparent. The
+stylesheet's rules for that element (background, colour, font, padding) have
+zero specificity, so any class wins over them whatever the stylesheet order.
+Highlighting is done by [highlight.js](https://highlightjs.org/), which is a
+regular dependency.
+
+The view is always left to right (`dir="ltr"`), whatever the page direction,
+and marked `translate="no"` so browser translation leaves the code alone.
+While the code is too wide for the view, it is a focusable group named
+"Python code" or "JavaScript code", so keyboard users can scroll it; code
+that fits adds no tab stop. Line numbers are hidden from screen readers.
+
+## Consumption
+
+Unlike the other packages in this repo, this one **ships built** (ES modules
+plus type declarations) and is styled by a **plain stylesheet**, so it works
+in apps with or without Panda CSS. It supports React 17, 18 and 19, and
+needs `react-intl` (6 or 7), a peer dependency, for its accessible names.
+
+1. Install the package, and `react-intl` if the app doesn't already have it.
+2. Import the stylesheet once.
+
+   In an app set up as the [`@microbit/ui` README](../ui/README.md)
+   describes, import it into the `vendor` cascade layer of your entry
+   stylesheet, so it beats Panda's preflight but loses to your own styling:
+
+   ```css
+   @layer reset, vendor, base, tokens, recipes, utilities;
+
+   @import "@microbit/ui/reset.css" layer(reset);
+   @import "@microbit/ui-code-view/style.css" layer(vendor);
+   ```
+
+   Elsewhere, import it as you would any other stylesheet:
+
+   ```ts
+   import "@microbit/ui-code-view/style.css";
+   ```
+
+3. Render the components:
+
+   ```tsx
+   import { PythonEditorCodeView } from "@microbit/ui-code-view";
+
+   <PythonEditorCodeView code={"from microbit import *\n"} />;
+   ```
+
+   They must be inside an `IntlProvider`.
+
+4. **Strings**: the components carry no inline English, so compile this
+   package's catalogs into your per-locale catalogs alongside your own,
+   **English included** (message ids are namespaced `ui-code-view.`). With
+   [`@microbit/i18n-tools`](../i18n-tools), list the package in your catalog
+   config and `microbit-i18n compile` merges it, backfilling English for
+   locales without a translation:
+
+   ```js
+   catalogs: [
+     {
+       source: "lang/ui.en.json",
+       out: "app/messages/ui.{lang}.json",
+       packages: ["@microbit/ui-code-view"],
+     },
+   ],
+   ```
+
+   Without the catalog, the accessible names render as message ids.
+
+The stylesheet loads Source Code Pro from `fonts.microbit.org` for the Python
+view. Its class names (`mb-code-view…` and highlight.js's `hljs-…`) are part
+of this package's API.
+
+## Colours
+
+The Python view's syntax colours are CSS variables shared with the Python
+Editor's CodeMirror theme:
+
+| Variable                    | Used for                         | OSS default            |
+| --------------------------- | -------------------------------- | ---------------------- |
+| `--colors-code-default`     | Plain text                       | `black`                |
+| `--colors-code-keyword`     | Keywords                         | `darkblue`             |
+| `--colors-code-string`      | Strings                          | `green`                |
+| `--colors-code-comment`     | Comments                         | `gray`                 |
+| `--colors-code-literal`     | `True`, `False`, `None`, numbers | `darkgreen`            |
+| `--colors-code-line-number` | Line numbers                     | `#b4b4b4` (`gray.350`) |
+
+In a Panda app they come from the `code.*` tokens in `@microbit/ui`'s base
+preset, so a brand preset that sets those tokens restyles this view and the
+editor together. Without Panda, the stylesheet falls back to the OSS defaults;
+set the variables in your own CSS (for example on `:root`) to change them.
+
+The MakeCode view's colours are fixed: they copy MakeCode's own look.
+
+## Migrating from `@microbit-foundation/react-code-view`
+
+- `PythonCodeRendering` is now `PythonEditorCodeView`, and
+  `MakeCodeJavaScriptRendering` is now `MakeCodeJavaScriptCodeView`.
+- The stylesheet is `@microbit/ui-code-view/style.css`.
+- The components now need an `IntlProvider` and this package's compiled
+  catalogs (see [Consumption](#consumption)).
+- Style the view through `className` rather than by targeting its inner
+  elements. The old package rendered a single `<pre>`; the new markup is
+  different, so selectors such as `& pre` no longer reach the background.
+- The Python view's colours are now the OSS defaults unless the app sets
+  them (see [Colours](#colours)). To keep the micro:bit palette, set the
+  `code.*` tokens in your brand preset or the variables in your CSS.
+- Line numbers stay in place when long lines scroll sideways.
+- The view has no outer margin. The old one rendered a bare `<pre>`, so it
+  picked up the browser's default margin unless the app reset it.
+
+## Development
+
+Stories live in `stories/` here but are rendered by the repo's Storybook
+harness, [`apps/storybook`](../../apps/storybook). Run it from the repo root:
+
+```bash
+npm run storybook
+```
+
+`npm run build -w @microbit/ui-code-view` compiles to `dist/`; it also runs on
+`npm install` and before packing.
+
+## Releases
+
+Publish a GitHub release with a tag of the form `ui-code-view-vX.Y.Z`. The
+build workflow routes the release to this package by the tag prefix and
+publishes it. This package is versioned independently of `@microbit/ui`.
+
+## License
+
+[MIT](LICENSE.md) © Micro:bit Educational Foundation and contributors.

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+export interface CodeViewProps {
+    code: string;
+    /**
+     * Added to the outermost element, e.g. to change the background. Any class
+     * wins over the stylesheet's rules for that element, which are
+     * zero-specificity, so stylesheet order and cascade layers don't matter.
+     */
+    className?: string;
+}
+/** Python, styled like the micro:bit Python Editor. */
+export declare const PythonEditorCodeView: (props: CodeViewProps) => import("react").JSX.Element;
+/** MakeCode's JavaScript (a TypeScript subset), styled like its code view. */
+export declare const MakeCodeJavaScriptCodeView: (props: CodeViewProps) => import("react").JSX.Element;

package/dist/index.js

@@ -0,0 +1,83 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+/**
+ * ui-code-view — read-only, syntax-highlighted code in the style of the
+ * micro:bit editors. Styled by the package's plain stylesheet
+ * (`@microbit/ui-code-view/style.css`), not Panda.
+ */
+import hljs from "highlight.js/lib/core";
+import python from "highlight.js/lib/languages/python";
+import typescript from "highlight.js/lib/languages/typescript";
+import { useEffect, useMemo, useRef, useState } from "react";
+import { useIntl } from "react-intl";
+// A private instance so an app's own highlight.js configuration (e.g. a
+// classPrefix, which would break style.css) can't reach these components.
+const highlighter = hljs.newInstance();
+highlighter.registerLanguage("python", python);
+highlighter.registerLanguage("typescript", typescript);
+/**
+ * Whether the element currently scrolls sideways. Safari doesn't make scroll
+ * containers keyboard-focusable, so a scrolling view needs a tabIndex to be
+ * reachable without a mouse; one that fits stays out of the tab order.
+ */
+const useScrollsHorizontally = (ref, content) => {
+    const [scrolls, setScrolls] = useState(false);
+    useEffect(() => {
+        const element = ref.current;
+        if (!element) {
+            return;
+        }
+        const update = () => setScrolls(element.scrollWidth > element.clientWidth);
+        update();
+        const observer = new ResizeObserver(update);
+        observer.observe(element);
+        // A web font arriving changes the content's width but not the element's.
+        let active = true;
+        void document.fonts?.ready.then(() => active && update());
+        return () => {
+            active = false;
+            observer.disconnect();
+        };
+    }, [ref, content]);
+    return scrolls;
+};
+const CodeView = ({ code: source, className, language, variant, label, }) => {
+    const intl = useIntl();
+    // The HTML parser turns a lone \r into a line break, so counting only \n
+    // would number fewer lines than the code shows.
+    const code = source.replace(/\r\n?/g, "\n");
+    // A trailing newline ends the last line rather than starting another.
+    const lineNumbers = code
+        .replace(/\n$/, "")
+        .split("\n")
+        .map((_, i) => i + 1)
+        .join("\n");
+    // highlight.js escapes the source; its output contains only its own spans.
+    const html = useMemo(() => highlighter.highlight(code, { language, ignoreIllegals: true }).value, [code, language]);
+    const codeRef = useRef(null);
+    const scrolls = useScrollsHorizontally(codeRef, html);
+    // Browsers drop focus from an element that stops being focusable, so a
+    // resize or zoom that ends the scrolling mustn't take the tabIndex away
+    // until focus moves on.
+    const [focused, setFocused] = useState(false);
+    const focusable = scrolls || focused;
+    // Line numbers are a separate column rather than a prefix on each line so
+    // highlight.js's output never needs splitting: its spans for multi-line
+    // strings and comments cross line breaks.
+    return (
+    // Code reads left to right whatever the page direction, and browser
+    // translation would rewrite identifiers and comments.
+    _jsxs("div", { className: `mb-code-view mb-code-view--${variant}${className ? ` ${className}` : ""}`, dir: "ltr", translate: "no", children: [_jsx("pre", { className: "mb-code-view__gutter", "aria-hidden": "true", children: lineNumbers }), _jsx("pre", { ref: codeRef, className: "mb-code-view__code", onFocus: () => setFocused(true), onBlur: () => setFocused(false), ...(focusable && {
+                    tabIndex: 0,
+                    role: "group",
+                    "aria-label": intl.formatMessage({ id: label }),
+                }), children: _jsx("code", { dangerouslySetInnerHTML: { __html: html } }) })] }));
+};
+/** Python, styled like the micro:bit Python Editor. */
+export const PythonEditorCodeView = (props) => (_jsx(CodeView, { ...props, language: "python", variant: "python-editor", label: "ui-code-view.python-label" }));
+/** MakeCode's JavaScript (a TypeScript subset), styled like its code view. */
+export const MakeCodeJavaScriptCodeView = (props) => (_jsx(CodeView, { ...props, language: "typescript", variant: "makecode-javascript", label: "ui-code-view.makecode-javascript-label" }));

package/lang/ui.en-US.json

@@ -0,0 +1 @@
+{}

package/lang/ui.en.json

@@ -0,0 +1,10 @@
+{
+  "ui-code-view.makecode-javascript-label": {
+    "defaultMessage": "JavaScript code",
+    "description": "Accessible name for a scrollable, read-only view of a MakeCode project's JavaScript"
+  },
+  "ui-code-view.python-label": {
+    "defaultMessage": "Python code",
+    "description": "Accessible name for a scrollable, read-only view of Python code"
+  }
+}

package/package.json

@@ -1,6 +1,59 @@
 {
   "name": "@microbit/ui-code-view",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Read-only, syntax-highlighted code views styled like the micro:bit Python Editor and MakeCode's JavaScript view. Plain CSS, no Panda setup needed; see README.",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/microbit-foundation/ui.git",
+    "directory": "packages/ui-code-view"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./style.css": "./style.css",
+    "./lang/*": "./lang/*"
+  },
+  "files": [
+    "dist",
+    "lang",
+    "style.css",
+    "README.md",
+    "LICENSE.md"
+  ],
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "prepare": "npm run build",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "highlight.js": "^11.12.0"
+  },
+  "peerDependencies": {
+    "react": "^17.0.0 || ^18.0.0 || ^19.0.0",
+    "react-intl": "^6.6.8 || ^7.0.0"
+  },
+  "devDependencies": {
+    "@storybook/react-vite": "^10.5.2",
+    "@testing-library/react": "^16.3.2",
+    "@types/react": "^18.3.3",
+    "@types/react-dom": "^18.3.0",
+    "@vitejs/plugin-react": "^5.2.0",
+    "jsdom": "^29.1.1",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "react-intl": "^6.6.8",
+    "typescript": "^5.4.2",
+    "vitest": "^4.1.10"
+  }
+}

package/style.css

@@ -0,0 +1,127 @@
+/*
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ *
+ * Plain CSS so apps without Panda can use the package. Panda apps import it
+ * into their `vendor` cascade layer, where it beats the preflight's pre/code
+ * rules but loses to app styling.
+ */
+@font-face {
+  font-family: "Source Code Pro";
+  font-style: normal;
+  font-weight: 500;
+  src: url("https://fonts.microbit.org/source-code-pro/v14/source-code-pro-v14-latin-500.woff2")
+    format("woff2");
+}
+
+/* Rules on the outer element are zero-specificity so a consumer's className
+   beats them in apps without cascade layers too, whatever the stylesheet
+   order. The resets below keep their specificity: they must still beat
+   app-wide pre/code rules. */
+:where(.mb-code-view) {
+  display: grid;
+  grid-template-columns: auto minmax(0, 1fr);
+  margin: 0;
+  padding: 20px 10px;
+}
+
+/* Resets so app-wide pre/code styling can't throw the two columns out of
+   line with each other. */
+.mb-code-view__gutter,
+.mb-code-view__code,
+.mb-code-view__code code {
+  margin: 0;
+  padding: 0;
+  border: none;
+  background: none;
+  color: inherit;
+  font: inherit;
+}
+
+.mb-code-view__gutter {
+  /* Explicit because Panda's preflight makes everything border-box. */
+  box-sizing: content-box;
+  min-width: 2em;
+  text-align: right;
+  -webkit-user-select: none;
+  user-select: none;
+}
+
+.mb-code-view__code {
+  overflow-x: auto;
+}
+
+/* The @microbit/ui focus ring. The view's padding leaves room for it. */
+.mb-code-view__code:focus-visible {
+  outline: 2px solid var(--colors-focus-ring, #1a1a1a);
+  outline-offset: 2px;
+}
+
+/* Colours come from the `code.*` tokens in @microbit/ui's base preset, so a
+   brand preset restyles this view and the Python Editor together. The
+   fallbacks repeat the base preset's OSS defaults for apps without Panda. */
+:where(.mb-code-view--python-editor) {
+  background: #fcfcfc;
+  color: var(--colors-code-default, black);
+  font-family: "Source Code Pro", monospace;
+  font-size: 1.2rem;
+  line-height: 1.4;
+}
+
+.mb-code-view--python-editor .mb-code-view__gutter {
+  padding-right: 1em;
+  color: var(--colors-code-line-number, #b4b4b4);
+}
+
+.mb-code-view--python-editor .hljs-keyword {
+  color: var(--colors-code-keyword, darkblue);
+}
+
+.mb-code-view--python-editor .hljs-string {
+  color: var(--colors-code-string, green);
+}
+
+.mb-code-view--python-editor .hljs-comment {
+  color: var(--colors-code-comment, gray);
+}
+
+/* The editor has no number colour: CodeMirror's Python grammar treats numbers
+   as literals. */
+.mb-code-view--python-editor .hljs-literal,
+.mb-code-view--python-editor .hljs-number {
+  color: var(--colors-code-literal, darkgreen);
+}
+
+:where(.mb-code-view--makecode-javascript) {
+  background: #ecf0f1;
+  color: #000000;
+  font-family: Monaco, Menlo, "Ubuntu Mono", Consolas, source-code-pro,
+    monospace;
+  /* 19px/26px at the default root size, scaling with the user's setting. */
+  font-size: 1.1875rem;
+  line-height: calc(26 / 19);
+}
+
+.mb-code-view--makecode-javascript .mb-code-view__gutter {
+  padding-right: 1.6em;
+  color: #2c3e50;
+}
+
+.mb-code-view--makecode-javascript .hljs-keyword,
+.mb-code-view--makecode-javascript .hljs-built_in,
+.mb-code-view--makecode-javascript .hljs-literal {
+  color: #0000ff;
+}
+
+.mb-code-view--makecode-javascript .hljs-string {
+  color: #a31515;
+}
+
+.mb-code-view--makecode-javascript .hljs-comment {
+  color: #008000;
+}
+
+.mb-code-view--makecode-javascript .hljs-number {
+  color: #008080;
+}