gwchq-textjam 0.1.7 → 0.1.9

package/README.md

@@ -1,256 +1,253 @@
-# Getting Started
-
-This project provides a React component containing the Raspberry Pi Code Editor for embedding inside other applications. Although originally bootstrapped with [Create React App](https://github.com/facebook/create-react-app), the application has been ejected so all the build scripts etc. are now in the repo. Legacy web-component assets are still published for backwards compatibility, but the primary integration surface is the `TextJamEditor` React component.
-
-# Local development
-
-The app test page at `http://localhost:3011` can be used to develop the React component in isolation if needed.
-
-## Install dependencies
-
-This repository uses Yarn 3 (see `package.json` → `packageManager`). Please install dependencies with Yarn:
-
-```
-yarn install
-```
-
-Using `npm install` can fail due to strict peer-dependency resolution in npm for some legacy packages in this project.
-
-## Available Scripts
-
-In the project directory, you can run:
-
-### `yarn start`
-
-Runs the app in the development mode.\
-Open [http://localhost:3011](http://localhost:3011) to view the web component test page in the browser.
-
-The page will reload if you make edits.\
-You will also see any lint errors in the console.
-
-### `yarn test`
-
-Launches the test runner in interactive watch mode.\
-See the section about [running tests](https://facebook.github.io/create-react-app/docs/running-tests) for more information.
-
-### `yarn build:lib`
-
-Builds the lib for production to the `dist` folder.\
-It bundles React in production mode and optimizes the build for the best performance.
-
-The build is minified and the filenames include the hashes.\
-Your app is ready to be deployed!
-
-See the section about [deployment](https://facebook.github.io/create-react-app/docs/deployment) for more information.
-
-## Styling
-
-The dev playground (`webpack.config.js`) keeps styles in JavaScript via `style-loader` for the fastest live reload experience. The library build (`webpack.lib.config.js`) extracts all CSS/SCSS into `dist/style.css` using `MiniCssExtractPlugin` so consumers can import a single stylesheet while still benefitting from CSS Modules (`*.module.(css|scss)`) for scoped styles.
-
-### Styling Best Practices for Developers
-
-**Focus on CSS Modules**: When adding or modifying styles, prioritize CSS Modules over global styles. Use the `.module.css` or `.module.scss` naming convention to ensure styles are scoped to components and avoid style conflicts.
-
-**Refactor Global Styles**: When working on existing code, identify global styles and refactor them into CSS Modules when possible. This improves maintainability, reduces style conflicts, and makes components more self-contained.
-
-**CSS Modules Structure**:
-- Component-specific styles should live in `ComponentName/styles.module.scss` alongside the component
-- Import styles as: `import classes from './styles.module.scss'`
-- Use class names from the imported styles object: `className={classes.container}`
-- Webpack automatically generates scoped class names like `ComponentName__container--abc123`
-
-**When Global Styles Are Acceptable**:
-- Design system tokens and variables (e.g., color palettes, spacing scales)
-- Third-party library overrides that cannot be modularized
-- Base resets or typography that must apply globally
-
-**Example - Preferred CSS Modules Approach**:
-```jsx
-// ComponentName/ComponentName.jsx
-import classes from './styles.module.scss';
-
-export function ComponentName() {
-  return <div className={classes.container}>Content</div>;
-}
-```
-
-```scss
-// ComponentName/styles.module.scss
-.container {
-  padding: 1rem;
-  background: var(--color-background);
-}
-```
-
-## Testing
-
-Automated unit tests can be run via the `yarn test` command. These unit tests are written using the JavaScript testing framework `Jest` and make use of the tools provided by the [React Testing Library](https://testing-library.com/docs/). Automated accessibility testing for components is available via the `jest-axe` library. This can be achieved using the `haveNoViolations` matcher provided by `jest-axe`, although this does not guarantee that the tested components have no accessibility issues.
-
-## Publishing to npm
-
-### Prerequisites
-
-1. Ensure you're logged into npm:
-   ```bash
-   npm login
-   ```
-
-2. Verify you have publish access to the `gwchq-textjam` package.
-
-3. Make sure all changes are committed and the working directory is clean.
-
-### Publishing Steps
-
-1. **Update the version** in `package.json` following [semantic versioning](https://semver.org/):
-   - Patch: `0.1.2` → `0.1.3` (bug fixes)
-   - Minor: `0.1.2` → `0.2.0` (new features, backwards compatible)
-   - Major: `0.1.2` → `1.0.0` (breaking changes)
-   
-2. **Build the library** (automatically runs via `prepublishOnly` hook):
-   ```bash
-   yarn build:lib
-   ```
-   This creates the `dist` folder with:
-   - `index.js` - The main ESM module
-   - `style.css` - Extracted stylesheet
-   - `assets/` - Static assets (icons, fonts, etc.)
-
-3. **Verify the build output**:
-   - Check that `dist/index.js` exists and is properly built
-   - Verify `dist/style.css` contains all styles
-   - Ensure all required assets are in `dist/assets/`
-
-4. **Publish to npm**:
-   ```bash
-   npm publish
-   ```
-   The `prepublishOnly` script will automatically run `yarn build:lib` before publishing.
-
-5. **Verify publication**:
-   ```bash
-   npm view gwchq-textjam version
-   ```
-
-### What Gets Published
-
-The following files are included in the npm package (as defined in `package.json` → `files`):
-- `dist/` - Built library files
-- `README.md` - This file
-- `LICENSE` - License file
-
-### Package Exports
-
-Consumers can import:
-- Main component: `import { TextJamEditor } from "gwchq-textjam"`
-- Stylesheet: `import "gwchq-textjam/style.css"`
-
-# Using the editor as a React component
-
-The editor can be imported and rendered directly inside another React application. The package exports the `TextJamEditor` component and `styles.css`:
-
-```tsx
-import { TextJamEditor } from "gwchq-textjam";
-import "gwchq-textjam/style.css"
-
-export function EditorWrapper() {
-  return (
-    <TextJamEditor
-      project={{ project_type: "python", identifier: "my-py-app" }}
-    />
-  );
-}
-```
-
-The consumer's webpack config should include the following setups
-```
-{
-  ...,
-  modules: {
-    rules: [
-      ...,
-      {
-        test: /\.map$/,
-        type: "asset/resource",
-      },
-      {
-        test: /\.whl$/,
-        type: "asset/resource",
-      },
-      {
-        test: /\.glb$/,
-        type: "asset/resource",
-      },
-    ]
-  },
-  plugins: [
-    new CopyWebpackPlugin({
-      patterns: [
-        ...,
-        {
-          from: "node_modules/gwchq-textjam/dist/assets",
-          to: "assets",
-        },
-      ],
-    }),
-  ],
-  resolve: {
-    extensions: ['.js', '.jsx'],
-    alias: {
-      'react': path.resolve(__dirname, 'node_modules/react'),
-      'react-dom': path.resolve(__dirname, 'node_modules/react-dom'),
-      'react-redux': path.resolve(__dirname, 'node_modules/react-redux'),
-    },
-    fallback: {
-      stream: require.resolve('stream-browserify'),
-      path: require.resolve('path-browserify'),
-      util: require.resolve('util/'),
-      assert: require.resolve("assert"),
-    },
-  },
-}
-```
-
-### Component props
-
-`TextJamEditor` accepts the following props (previously exposed as web-component attributes):
-
-- `project`: an object with the project data. Contains the following props:
-  - `project_type`: Possible values `web` | `python`. Default project files will be created according to this value
-  - `identifier`: A string that represents the project id. If provided, cached project with same id will be loaded
-
-// TODO: review old options below
-- `code`: A preset blob of code to show in the editor pane (overrides content of `main.py`/`index.html`)
-- `embedded`: Enable embedded mode which hides some functionality (defaults to `false`)
-- `loadCache`: Load latest version of project code from local storage (defaults to `true`)
-- `locale`: Locale for UI elements and to determine the language of projects loaded from the API (defaults to `en`)
-- `outputOnly`: Only display the output panel (defaults to `false`)
-- `outputPanels`: Array of output panel names to display (defaults to `['text', 'visual']`)
-- `outputSplitView`: Start with split view in output panel (defaults to `false`, i.e. tabbed view)
-- `projectNameEditable`: Allow the user to edit the project name in the project bar (defaults to `false`)
-- `readOnly`: Display the editor in read-only mode (defaults to `false`)
-- `showSavePrompt`: Prompt the user to save their work (defaults to `false`)
-- `sidebarOptions`: Array of strings specifying the panels to be displayed in the sidebar. Options include `"projects"`, `"file"`, `"download"`, `"settings"`.
-- `sidebarPlugins`: Array of plugin definitions to render inside the sidebar (defaults to `[]`)
-- `theme`: Force editor into `"dark"` or `"light"` mode; browser/system preferences are used when omitted
-- `withProjectbar`: Show the project bar containing project name and save status (defaults to `false`)
-- `withSidebar`: Show the sidebar (defaults to `false`)
-
-When no props are supplied the component falls back to parsing the current page’s query string so the local development experience (`yarn start`) continues to work unchanged. You can override this by explicitly passing `queryString` or the equivalent props.
-
-### Events and callbacks
-
-For backwards compatibility the editor continues to dispatch the following `document` events. You can listen for them from your host application if you rely on the legacy integration layer:
-
-- `editor-codeChanged`
-- `editor-navigateToProjectsPage`
-- `editor-projectOwnerLoaded`
-- `editor-runCompleted`
-- `editor-runStarted`
-- `editor-stepChanged`
-- `editor-logIn`
-- `editor-signUp`
-- `editor-quizReady`
-- `editor-themeUpdated`
-
-These events make it possible for the host page to react to code execution, project changes, authentication requests, and theme updates.
-
+# Getting Started
+
+This project provides a React component containing the Raspberry Pi Code Editor for embedding inside other applications. Although originally bootstrapped with [Create React App](https://github.com/facebook/create-react-app), the application has been ejected so all the build scripts etc. are now in the repo. Legacy web-component assets are still published for backwards compatibility, but the primary integration surface is the `TextJamEditor` React component.
+
+# Local development
+
+The app test page at `http://localhost:3011` can be used to develop the React component in isolation if needed.
+
+## Install dependencies
+
+This repository uses Yarn 3 (see `package.json` → `packageManager`). Please install dependencies with Yarn:
+
+```
+yarn install
+```
+
+Using `npm install` can fail due to strict peer-dependency resolution in npm for some legacy packages in this project.
+
+## Available Scripts
+
+In the project directory, you can run:
+
+### `yarn start`
+
+Runs the app in the development mode.\
+Open [http://localhost:3011](http://localhost:3011) to view the web component test page in the browser.
+
+The page will reload if you make edits.\
+You will also see any lint errors in the console.
+
+### `yarn test`
+
+Launches the test runner in interactive watch mode.\
+See the section about [running tests](https://facebook.github.io/create-react-app/docs/running-tests) for more information.
+
+### `yarn build:lib`
+
+Builds the lib for production to the `dist` folder.\
+It bundles React in production mode and optimizes the build for the best performance.
+
+The build is minified and the filenames include the hashes.\
+Your app is ready to be deployed!
+
+See the section about [deployment](https://facebook.github.io/create-react-app/docs/deployment) for more information.
+
+## Styling
+
+The dev playground (`webpack.config.js`) keeps styles in JavaScript via `style-loader` for the fastest live reload experience. The library build (`webpack.lib.config.js`) extracts all CSS/SCSS into `dist/style.css` using `MiniCssExtractPlugin` so consumers can import a single stylesheet while still benefitting from CSS Modules (`*.module.(css|scss)`) for scoped styles.
+
+### Styling Best Practices for Developers
+
+**Focus on CSS Modules**: When adding or modifying styles, prioritize CSS Modules over global styles. Use the `.module.css` or `.module.scss` naming convention to ensure styles are scoped to components and avoid style conflicts.
+
+**Refactor Global Styles**: When working on existing code, identify global styles and refactor them into CSS Modules when possible. This improves maintainability, reduces style conflicts, and makes components more self-contained.
+
+**CSS Modules Structure**:
+- Component-specific styles should live in `ComponentName/styles.module.scss` alongside the component
+- Import styles as: `import classes from './styles.module.scss'`
+- Use class names from the imported styles object: `className={classes.container}`
+- Webpack automatically generates scoped class names like `ComponentName__container--abc123`
+
+**When Global Styles Are Acceptable**:
+- Design system tokens and variables (e.g., color palettes, spacing scales)
+- Third-party library overrides that cannot be modularized
+- Base resets or typography that must apply globally
+
+**Example - Preferred CSS Modules Approach**:
+```jsx
+// ComponentName/ComponentName.jsx
+import classes from './styles.module.scss';
+
+export function ComponentName() {
+  return <div className={classes.container}>Content</div>;
+}
+```
+
+```scss
+// ComponentName/styles.module.scss
+.container {
+  padding: 1rem;
+  background: var(--color-background);
+}
+```
+
+## Testing
+
+Automated unit tests can be run via the `yarn test` command. These unit tests are written using the JavaScript testing framework `Jest` and make use of the tools provided by the [React Testing Library](https://testing-library.com/docs/). Automated accessibility testing for components is available via the `jest-axe` library. This can be achieved using the `haveNoViolations` matcher provided by `jest-axe`, although this does not guarantee that the tested components have no accessibility issues.
+
+## Publishing to npm
+
+### Prerequisites
+
+1. Ensure you're logged into npm:
+   ```bash
+   npm login
+   ```
+
+2. Verify you have publish access to the `gwchq-textjam` package.
+
+3. Make sure all changes are committed and the working directory is clean.
+
+### Publishing Steps
+
+1. **Update the version** in `package.json` following [semantic versioning](https://semver.org/):
+   - Patch: `0.1.2` → `0.1.3` (bug fixes)
+   - Minor: `0.1.2` → `0.2.0` (new features, backwards compatible)
+   - Major: `0.1.2` → `1.0.0` (breaking changes)
+   
+2. **Build the library** (automatically runs via `prepublishOnly` hook):
+   ```bash
+   yarn build:lib
+   ```
+   This creates the `dist` folder with:
+   - `index.js` - The main ESM module
+   - `style.css` - Extracted stylesheet
+   - `assets/` - Static assets (icons, fonts, etc.)
+
+3. **Verify the build output**:
+   - Check that `dist/index.js` exists and is properly built
+   - Verify `dist/style.css` contains all styles
+   - Ensure all required assets are in `dist/assets/`
+
+4. **Publish to npm**:
+   ```bash
+   npm publish
+   ```
+   The `prepublishOnly` script will automatically run `yarn build:lib` before publishing.
+
+5. **Verify publication**:
+   ```bash
+   npm view gwchq-textjam version
+   ```
+
+### What Gets Published
+
+The following files are included in the npm package (as defined in `package.json` → `files`):
+- `dist/` - Built library files
+- `README.md` - This file
+- `LICENSE` - License file
+
+### Package Exports
+
+Consumers can import:
+- Main component: `import { TextJamEditor } from "gwchq-textjam"`
+- Stylesheet: `import "gwchq-textjam/style.css"`
+
+# Using the editor as a React component
+
+The editor can be imported and rendered directly inside another React application. The package exports the `TextJamEditor` component and `styles.css`:
+
+```tsx
+import { TextJamEditor } from "gwchq-textjam";
+import "gwchq-textjam/style.css"
+
+export function EditorWrapper() {
+  return (
+    <TextJamEditor
+      project={{ project_type: "python", identifier: "my-py-app" }}
+    />
+  );
+}
+```
+
+The consumer's webpack config should include the following setups
+```
+{
+  ...,
+  modules: {
+    rules: [
+      ...,
+      {
+        test: /\.map$/,
+        type: "asset/resource",
+      },
+      {
+        test: /\.whl$/,
+        type: "asset/resource",
+      },
+      {
+        test: /\.glb$/,
+        type: "asset/resource",
+      },
+    ]
+  },
+  plugins: [
+    new CopyWebpackPlugin({
+      patterns: [
+        ...,
+        {
+          from: "node_modules/gwchq-textjam/dist/assets",
+          to: "assets",
+        },
+      ],
+    }),
+  ],
+  resolve: {
+    extensions: ['.js', '.jsx'],
+    alias: {
+      'react': path.resolve(__dirname, 'node_modules/react'),
+      'react-dom': path.resolve(__dirname, 'node_modules/react-dom'),
+      'react-redux': path.resolve(__dirname, 'node_modules/react-redux'),
+    },
+    fallback: {
+      stream: require.resolve('stream-browserify'),
+      path: require.resolve('path-browserify'),
+      util: require.resolve('util/'),
+      assert: require.resolve("assert"),
+    },
+  },
+}
+```
+
+### Component props
+
+`TextJamEditor` accepts the following props (previously exposed as web-component attributes):
+
+- `project`: an object with the project data. Contains the following props:
+  - `project_type`: Possible values `web` | `python`. Default project files will be created according to this value
+  - `identifier`: A string that represents the project id. If provided, cached project with same id will be loaded
+
+// TODO: review old options below
+- `code`: A preset blob of code to show in the editor pane (overrides content of `main.py`/`index.html`)
+- `embedded`: Enable embedded mode which hides some functionality (defaults to `false`)
+- `loadCache`: Load latest version of project code from local storage (defaults to `true`)
+- `locale`: Locale for UI elements and to determine the language of projects loaded from the API (defaults to `en`)
+- `outputOnly`: Only display the output panel (defaults to `false`)
+- `outputPanels`: Array of output panel names to display (defaults to `['text', 'visual']`)
+- `outputSplitView`: Start with split view in output panel (defaults to `false`, i.e. tabbed view)
+- `projectNameEditable`: Allow the user to edit the project name in the project bar (defaults to `false`)
+- `readOnly`: Display the editor in read-only mode (defaults to `false`)
+- `showSavePrompt`: Prompt the user to save their work (defaults to `false`)
+- `sidebarOptions`: Array of strings specifying the panels to be displayed in the sidebar. Options include `"projects"`, `"file"`, `"download"`, `"settings"`.
+- `theme`: Force editor into `"dark"` or `"light"` mode; browser/system preferences are used when omitted
+
+When no props are supplied the component falls back to parsing the current page’s query string so the local development experience (`yarn start`) continues to work unchanged. You can override this by explicitly passing `queryString` or the equivalent props.
+
+### Events and callbacks
+
+For backwards compatibility the editor continues to dispatch the following `document` events. You can listen for them from your host application if you rely on the legacy integration layer:
+
+- `editor-codeChanged`
+- `editor-navigateToProjectsPage`
+- `editor-projectOwnerLoaded`
+- `editor-runCompleted`
+- `editor-runStarted`
+- `editor-stepChanged`
+- `editor-logIn`
+- `editor-signUp`
+- `editor-quizReady`
+- `editor-themeUpdated`
+
+These events make it possible for the host page to react to code execution, project changes, authentication requests, and theme updates.
+