gwchq-textjam 0.5.16 → 0.5.18

package/README.md

@@ -30,8 +30,7 @@ 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.
+Runs the Jest test suite once and exits. Pass `--watch` (e.g. `yarn test --watch`) for interactive watch mode, or `--coverage` to generate a coverage report.
 
 ### `yarn build:lib`
 
@@ -39,9 +38,7 @@ 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.
+The library is ready to be published — see [Publishing to npm](#publishing-to-npm) below.
 
 ## Styling
 
@@ -87,7 +84,7 @@ export function ComponentName() {
 
 ## 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.
+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 `toHaveNoViolations` matcher provided by `jest-axe`, although this does not guarantee that the tested components have no accessibility issues.
 
 ## Publishing to npm
 
@@ -127,11 +124,12 @@ The following files are included in the npm package (as defined in `package.json
 Consumers can import:
 
 - Main component: `import { TextJamEditor } from "gwchq-textjam"`
+- `CurriculumDisplayMode` enum and `useCurriculumDisplayMode` hook: `import { CurriculumDisplayMode, useCurriculumDisplayMode } 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`:
+The editor can be imported and rendered directly inside another React application:
 
 ```tsx
 import { TextJamEditor } from "gwchq-textjam";
@@ -140,7 +138,23 @@ import "gwchq-textjam/style.css";
 export function EditorWrapper() {
   return (
     <TextJamEditor
-      project={{ project_type: "python", identifier: "my-py-app" }}
+      project={{
+        project_type: "python",
+        identifier: "my-py-app",
+        name: "My Python App",
+        rootDirId: "root",
+        components: [],
+        commits: [],
+      }}
+      isLoading={false}
+      user={{
+        userId: 1,
+        firstName: "Ada",
+        lastName: "Lovelace",
+        initials: "AL",
+        isFacilitator: false,
+        avatarSrc: "",
+      }}
     />
   );
 }
@@ -209,43 +223,42 @@ The consumer's webpack config should include the following setups
 
 ### Component props
 
-`TextJamEditor` accepts the following props (previously exposed as web-component attributes):
+`TextJamEditor` accepts the following props (see `TextJamEditorProps` in `src/App.tsx` for the source of truth):
 
-- `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
-  - `author`: an object with owner user data (firstName, lastName, id)
-  - `components`: an array of project components (files and folders)
-- `packageApiUrl`: A string with url to download pyodide packages. If not provided - default value is pyodide CDN.
-- `isSharedProject`: a boolean to show a shared project interface instead the regular editor if `true` (`false` by default)
-- `isCodeVisible`: a boolean to show or hide the code panel (`true` by default)
+**Required**
+
+- `project` (`IncomingProjectData`): the project data. Contains `project_type` (`"web"` | `"python"`), `identifier`, `name`, `rootDirId`, `components` (files and folders), `commits`, and optionally `author`, `commitId`, `savedAt`, `extension`, etc.
+- `isLoading`: a boolean indicating whether the project is still loading.
+- `user` (`AuthorizedUser`): the authenticated user — `userId`, `firstName`, `lastName`, `initials`, `isFacilitator`, `avatarSrc`.
 
-// TODO: review old options below
+**Optional**
+
+- `packageApiUrl`: A string with url to download pyodide packages. If not provided, the default value is the pyodide CDN.
+- `isSharedProject`: a boolean to show a shared project interface instead of the regular editor if `true` (`false` by default)
+- `isCodeVisible`: a boolean to show or hide the code panel (`true` by default)
+- `template`: a `Project` used as the starter/template content.
+- `curriculum`: a `Curriculum` object (`{ curriculumDisplayMode, curriculumContent }`) controlling the embedded curriculum panel. `curriculumDisplayMode` is one of `CurriculumDisplayMode.HIDDEN | NORMAL | EXPANDED`.
+- `saveProject`: `(options: { project, commitBlob?, hasContentChanges?, hasNameChanges?, skipRedirect? }) => void | Promise<void>` — called by the editor when a save is triggered.
+- `isSaving`: a boolean reflecting whether a save is in progress.
+- `loadProjectContent`: a `LoadProjectContentFunction` used to fetch project content on demand.
+- `projectContent`: pre-loaded project content (a zip `Blob`) to inflate instead of fetching it.
+- `starterCodeContent`: a `Blob | null` with starter code content.
+- `shareLinks`: `{ showCode, hideCode } | null` — links for sharing the project.
+- `isContentLoaded` / `isSaveSuccess`: `boolean | null` flags surfaced by the host app's load/save flow.
+- `loadTemplateProjectData`: callback to trigger loading of template project data.
+- `isTemplateDataLoaded`: a boolean indicating whether template data has finished loading.
+- `navigationGuardCoordinator`: a `NavigationGuardCoordinator` (`{ register(guard, shouldBlock?) }`) the host app can use to intercept navigation while there are unsaved changes.
+- `onLogoutClick` / `onViewProfileClick` / `onHomeClick`: callbacks fired from the editor's auth/nav menu.
 
-- `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`)
-- `sidebarOptions`: Array of strings specifying the panels to be displayed in the sidebar. Options include `"projects"`, `"file"`, `"download"`, `"settings"`.
+`sidebarOptions` (`string[]`, defaults to `["files", "home", "user"]`) is also accepted at runtime and forwarded down to the sidebar
 
-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.
+### Client-side storage
 
-### Events and callbacks
+**IndexedDB** is the editor's actual project cache. It opens a `textjam-store` database (`src/utils/IndexedDb.ts`) with three object stores — `files` (file blobs), `projects` (project metadata, keyed by project key, stamped with `savedAt`), and `project_files` (the list of file ids belonging to a project). The `useProjectCache` hook reads/writes this cache so a project's latest content survives a reload without a round trip to the host app.
 
-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:
+**`localStorage`** is used only for a small cross-tab notification, not for storing project content:
 
-- `editor-codeChanged`
-- `editor-navigateToProjectsPage`
-- `editor-projectOwnerLoaded`
-- `editor-runCompleted`
-- `editor-runStarted`
-- `editor-stepChanged`
-- `editor-logIn`
-- `editor-signUp`
-- `editor-quizReady`
-- `editor-themeUpdated`
+- `src/utils/projectTabSync.ts` writes a `project-updated` key (`{ key, timestamp, source }`) whenever the active project changes.
+- Other open tabs pick this up via the `storage` event (`listenProjectUpdates`) and, through the `useProjectTabSync` hook, show a "made changes in another tab, refresh to see your updates" toast. Preview tabs and the tab that made the change are excluded.
 
-These events make it possible for the host page to react to code execution, project changes, authentication requests, and theme updates.
+Inside the sandboxed iframe used to run HTML/JS projects, the editor also overrides `window.localStorage` (`src/components/Editor/Runners/HtmlRunner/helpers/scripts.ts`) to block reads/writes/removal of `authKey` and any `oidc.*` key, and disables `clear()` entirely — this prevents user-authored preview code from reading or tampering with the host app's auth tokens.

package/dist/index.js

@@ -51743,7 +51743,8 @@ var useResizableSeparator = _ref => {
     applyPixels(nextPx, metrics);
   };
   var separatorProps = {
-    role: "separator",
+    // Not "separator": NVDA stays in browse mode on a splitter and eats arrows.
+    role: "slider",
     tabIndex: 0,
     "aria-label": separatorLabel !== null && separatorLabel !== void 0 ? separatorLabel : "Resize panels",
     "aria-orientation": isVerticalHandle ? "vertical" : "horizontal",
@@ -82852,9 +82853,10 @@ const useFileTree = ({ projectFiles, onRename, onDrop, onOpenFile, rootId, readO
         tree.rebuildTree();
     }, [projectFiles, tree]);
     // A leftover dnd state disables every hotkey; `dragend` never comes when the
-    // dragged row unmounts. Capture + microtask: their handler runs between them.
+    // dragged row unmounts. Capture + task, not microtask: a native dispatch runs
+    // microtasks between listeners, i.e. before their drop handler reads it.
     (0, react_2.useEffect)(() => {
-        const clearDndState = () => queueMicrotask(() => tree.applySubStateUpdate("dnd", null));
+        const clearDndState = () => setTimeout(() => tree.applySubStateUpdate("dnd", null));
         document.addEventListener("drop", clearDndState, true);
         return () => document.removeEventListener("drop", clearDndState, true);
     }, [tree]);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "gwchq-textjam",
   "description": "Embeddable React editor used in Raspberry Pi text-based projects.",
-  "version": "0.5.16",
+  "version": "0.5.18",
   "license": "Apache-2.0",
   "homepage": "https://github.com/GirlsFirst/gwchq-textjam",
   "author": "Girls Who Code HQ",