@dodona/papyros 0.3.4 → 0.3.7-scoped

package/README.md

@@ -23,9 +23,14 @@ Currently, Papyros provides support for the following programming languages:
 
 ## Using Papyros in your own project
 
-You can install Papyros on your system using npm:
+You can add Papyros to your project as follows:
+- npm:
 ```shell
-npm install -g @dodona/papyros
+npm install @dodona/papyros
+```
+- yarn:
+```shell
+yarn add @dodona/papyros
 ```
 
 Papyros currently supports two modes of operation: stand-alone and embedded.
@@ -38,50 +43,61 @@ as the user knows for what purpose Papyros is being used. For example, when used
 scope of a Python exercise in Dodona, there is no need to support other programming languages.
 The locale should also match that of the actual application.
 
-The easiest way to initialize Papyros is by using the static method `Papyros.fromElement`.
-This method expects a parent element that wraps the scratchpad and a `PapyrosConfig` object.
+Using Papyros in your project is done by following a few steps. First, you create a new
+Papyros instance with a `PapyrosConfig` object.
 The following options are supported:
 
 - `standAlone`: Whether to operate in stand-alone or embedded mode as described above.
+- `programmingLanguage`: The [programming language](/src/ProgrammingLanguage.ts) to use in the CodeEditor and Backend.
 - `locale`: The locale to use, currently English and Dutch translations are provided.
-- `programmingLanguage`: The language to use in the CodeEditor and Backend
 - `inputMode`: How the users can provide input, according to the [InputMode enum](/src/InputManager.ts)
-
-Furthermore, you can provide fine-grained configuration in embedded mode by providing `RenderOptions`
-to each main component in the application. You minimally need to specify the ID of the parent element.
-You can also specify attributes, such as `style` or `data`, or `classNames` to be used.
-The main components are the following:
-
-- `code`: the CodeEditor.
-- `panel`: the StatusPanel in the CodeEditor
-- `input`: the field for the user input
-- `output`: the panel for output of the code
+- `example`: Optional name of the selected example, only appliccable in standAlone-mode
+- `channelOptions`: Optional options to provide to the [sync-message](https://github.com/alexmojaki/sync-message) channel. Extra is the serviceWorkerName, which is the relative pathname to the service worker script
+
+Furthermore, you can provide fine-grained configuration by providing `RenderOptions` to each main component in the application when rendering Papyros. You minimally need to specify the ID of the parent element.
+You can also specify attributes, such as `style`, `data`-attributes or `classNames` to be used.
+The components you can style like this are the following:
+- `standAloneOptions`: for the global application in standAlone mode
+- `codeEditorOptions`: for the CodeEditor.
+- `statusPanelOptions`: for the StatusPanel in the CodeEditor
+- `inputOptions`: for the field that handles the user input
+- `outputOptions`: for the panel that displays the output of the code
 
 ### User input
 
 Important to note is that handling asynchronous input in a synchronous way is not straightforward.
-This requires advanced features which are not available by default in your browser. We support two options
+This requires advanced features which are not available by default in your browser. We support two options based on [sync-message](https://github.com/alexmojaki/sync-message).
 
 The most efficient and practical way is using SharedArrayBuffers, which requires the presence of certain HTTP headers.
 The following headers must be set on resources using Papyros.
-```json
-'Cross-Origin-Opener-Policy': 'same-origin',
-'Cross-Origin-Embedder-Policy': 'require-corp'
+```yaml
+{
+  "Cross-Origin-Opener-Policy": "same-origin",
+  "Cross-Origin-Embedder-Policy": "require-corp"
+}
 ```
-If you are also embedding other components (such as iframes) in those pages, you will also need to set
-'Cross-Origin-Resource-Policy' to 'cross-origin' to make them work correctly. In order to limit the effect of this
-change, it is advised to restrict access using the 'Access-Control-Allow-Origin'-header to prevent abuse of including code.
+If you are also embedding other components (such as iframes, videos or images) in those pages, you will also need to set the `Cross-Origin-Resource-Policy`-header to `cross-origin` to make them work correctly. If these elements come from external URLs, it will likely not be possible to keep using them. An alternative is described below.
 
 If you would like to use this project without enabling these HTTP headers, we provide a solution using a service worker.
-If your application does not use a service worker yet, a default service worker is pre-built and included in the package.
-Simply copy the file located [here](dist/inputServiceWorker.js) to a location of choice in your application where it can be served.
-Then, before launching your instance of Papyros, make a call to configureInput with the location of the folder and the name of the file.
+If your application does not use a service worker yet, you can create one based on the [service worker used in stand-alone mode](src/InputServiceWorker.ts)).
+If you already use a service worker, simply include our [InputWorker](src/workers/input/InputWorker.ts) in your existing service worker using imports (you can import it separately from /dist/workers/input/InputWorker). An example of how to use it can be found in our described service worker. Afterwards, inform Papyros of the location using the channelOptions described earlier.
+
+### Code editor
+
+The editor used in Papyros is powered by [CodeMirror 6](https://codemirror.net/6/). It is accessible in code via an instance of Papyros and by default allows configuring many options:
+- the [programming language](/src/ProgrammingLanguage.ts) of the contents (for e.g. syntax higlighting)
+- the displayed placeholder
+- the indentation unit
+- the shown panel
+- the autocompletion source
+- the linting source
+- the theme used to style the editor
 
-If you already use a service worker, simply include our functionality in your existing worker using imports. An example can be found [here](src/InputServiceWorker.ts). Afterwards, inform Papyros of this using configureInput as above.
+If you need more specific functionality, this can be added in your own code by accessing the internal CodeMirror editorView.
 
 ## Documentation
 
-Visit our web page at <https://docs.dodona.be/papyros/>.
+Visit our documentation page at <https://docs.dodona.be/papyros/>.
 
 ## Building and developing
 

package/dist/Backend.d.ts

@@ -36,14 +36,45 @@ export interface WorkerAutocompleteContext {
     } | null;
 }
 export interface WorkerDiagnostic {
+    /**
+     * 1-based index of the starting line containing the issue
+     */
     lineNr: number;
+    /**
+     * 0-based index of the column in the starting line
+     */
     columnNr: number;
+    /**
+     * 1-based index of the ending line containing the issue
+     * Can be the same as lineNr
+     */
+    endLineNr: number;
+    /**
+     * 0-based index of the column in the ending line
+     */
+    endColumnNr: number;
+    /**
+     * Severity of the issue
+     */
     severity: "info" | "warning" | "error";
+    /**
+     * Message describing the issue
+     */
     message: string;
 }
 export declare abstract class Backend<Extras extends SyncExtras = SyncExtras> {
+    /**
+     * SyncExtras object that grants access to helpful methods
+     * for synchronous operations
+     */
     protected extras: Extras;
+    /**
+     * Callback to handle events published by this Backend
+     */
     protected onEvent: (e: BackendEvent) => any;
+    /**
+     * Queue to handle published events without overloading the thread
+     */
     protected queue: BackendEventQueue;
     /**
      * Constructor is limited as it is meant to be used as a WebWorker
@@ -58,9 +89,10 @@ export declare abstract class Backend<Extras extends SyncExtras = SyncExtras> {
     /**
      * Initialize the backend by doing all setup-related work
      * @param {function(BackendEvent):void} onEvent Callback for when events occur
+     * @param {function():void} onOverflow Callback for when overflow occurs
      * @return {Promise<void>} Promise of launching
      */
-    launch(onEvent: (e: BackendEvent) => void): Promise<void>;
+    launch(onEvent: (e: BackendEvent) => void, onOverflow: () => void): Promise<void>;
     /**
      * Executes the given code
      * @param {Extras} extras Helper properties to run code

package/dist/BackendEvent.d.ts

@@ -8,7 +8,8 @@ export declare enum BackendEventType {
     Output = "output",
     Sleep = "sleep",
     Error = "error",
-    Interrupt = "interrupt"
+    Interrupt = "interrupt",
+    Loading = "loading"
 }
 /**
  * All possible types for ease of iteration

package/dist/BackendEventQueue.d.ts

@@ -25,6 +25,14 @@ export declare class BackendEventQueue {
      * Queue storing Output-events after overflowing
      */
     private overflow;
+    /**
+     * Callback for when overflow occurs
+     */
+    private onOverflow;
+    /**
+     * Keep track whether the queue reached its limit this run
+     */
+    private overflown;
     /**
      * Time in milliseconds when the last flush occurred
      */
@@ -38,11 +46,12 @@ export declare class BackendEventQueue {
      */
     private decoder;
     /**
-     * @param {Function} callback Function to process events in the queue
+     * @param {function(BackendEvent):void} callback Function to process events in the queue
+     * @param {function():void} onOverflow Callback for when overflow occurs
      * @param {number} limit The maximal amount of output lines to send before overflowing
      * @param {number} flushTime The time in milliseconds before sending events through
      */
-    constructor(callback: (e: BackendEvent) => void, limit?: number, flushTime?: number);
+    constructor(callback: (e: BackendEvent) => void, onOverflow: () => void, limit?: number, flushTime?: number);
     /**
      * Add an element to the queue
      * @param {BackendEventType} type The type of the event

package/dist/BackendManager.d.ts

@@ -26,6 +26,10 @@ export declare abstract class BackendManager {
      * Uses an Array to maintain order of subscription
      */
     private static subscriberMap;
+    /**
+     * Whether the BackendManager is publishing events
+     */
+    private static halted;
     /**
      * The channel used to communicate with the SyncClients
      */
@@ -59,5 +63,6 @@ export declare abstract class BackendManager {
      * @param {BackendEventType} e The event to publish
      */
     static publish(e: BackendEvent): void;
+    private static halt;
 }
 export {};

package/dist/CodeEditor.d.ts

@@ -17,10 +17,11 @@ export declare class CodeEditor extends Renderable {
     private compartments;
     /**
      * Construct a new CodeEditor
+     * @param {Function} onRunRequest Callback for when the user wants to run the code
      * @param {string} initialCode The initial code to display
      * @param {number} indentLength The length in spaces for the indent unit
      */
-    constructor(initialCode?: string, indentLength?: number);
+    constructor(onRunRequest: () => void, initialCode?: string, indentLength?: number);
     /**
      * Helper method to dispatch configuration changes at runtime
      * @param {Array<[Option, Extension]>} items Array of items to reconfigure
@@ -51,6 +52,10 @@ export declare class CodeEditor extends Renderable {
      * @param {number} indentLength The number of spaces to use for indentation
      */
     setIndentLength(indentLength: number): void;
+    /**
+     * @param {Function} onChange Listener that performs actions on the new contents
+     */
+    onChange(onChange: ((newContent: string) => void)): void;
     /**
      * @param {HTMLElement} panel The panel to display at the bottom of the editor
      */
@@ -82,7 +87,6 @@ export declare class CodeEditor extends Renderable {
     *  - special character highlighting
     *  - the undo history
     *  - a fold gutter
-    *  - gutter for linting
     *  - custom selection drawing
     *  - multiple selections
     *  - reindentation on input

package/dist/CodeRunner.d.ts

@@ -2,6 +2,7 @@ import { CodeEditor } from "./CodeEditor";
 import { InputManager } from "./InputManager";
 import { ProgrammingLanguage } from "./ProgrammingLanguage";
 import { RenderOptions, ButtonOptions, Renderable } from "./util/Rendering";
+import { OutputManager } from "./OutputManager";
 interface CodeRunnerRenderOptions {
     /**
      * Options for rendering the panel
@@ -15,6 +16,10 @@ interface CodeRunnerRenderOptions {
      * Options for rendering the editor
      */
     codeEditorOptions: RenderOptions;
+    /**
+     * RenderOptions for the output field
+     */
+    outputOptions: RenderOptions;
 }
 /**
  * Enum representing the possible states while processing code
@@ -26,6 +31,19 @@ export declare enum RunState {
     Stopping = "stopping",
     Ready = "ready"
 }
+/**
+ * Interface to represent information required when handling loading events
+ */
+export interface LoadingData {
+    /**
+     * List of module names that are being loaded
+     */
+    modules: Array<string>;
+    /**
+     * Whether the modules are being loaded or have been loaded
+     */
+    loading: boolean;
+}
 /**
  * Helper component to manage and visualize the current RunState
  */
@@ -42,6 +60,10 @@ export declare class CodeRunner extends Renderable<CodeRunnerRenderOptions> {
      * Component to request and handle input from the user
      */
     readonly inputManager: InputManager;
+    /**
+     * Component to handle output generated by the user's code
+     */
+    readonly outputManager: OutputManager;
     /**
      * The backend that executes the code asynchronously
      */
@@ -54,6 +76,14 @@ export declare class CodeRunner extends Renderable<CodeRunnerRenderOptions> {
      * Buttons managed by this component
      */
     private buttons;
+    /**
+     * Array of packages that are being installed
+     */
+    private loadingPackages;
+    /**
+     * Previous state to restore when loading is done
+     */
+    private previousState;
     /**
      * Construct a new RunStateManager with the given listeners
      * @param {ProgrammingLanguage} programmingLanguage The language to use
@@ -86,7 +116,7 @@ export declare class CodeRunner extends Renderable<CodeRunnerRenderOptions> {
      * Show or hide the spinning circle, representing a running animation
      * @param {boolean} show Whether to show the spinner
      */
-    showSpinner(show: boolean): void;
+    private showSpinner;
     /**
      * Show the current state of the program to the user
      * @param {RunState} state The current state of the run
@@ -102,9 +132,14 @@ export declare class CodeRunner extends Renderable<CodeRunnerRenderOptions> {
     addButton(options: ButtonOptions, onClick: () => void): void;
     protected _render(options: CodeRunnerRenderOptions): HTMLElement;
     /**
-     * Run the code that is currently present in the editor
+     * @param {string} code The code to run
      * @return {Promise<void>} Promise of running the code
      */
-    runCode(): Promise<void>;
+    runCode(code: string): Promise<void>;
+    /**
+     * Callback to handle loading events
+     * @param {BackendEvent} e The loading event
+     */
+    private onLoad;
 }
 export {};

package/dist/Constants.d.ts

@@ -1,4 +1,10 @@
 import { ProgrammingLanguage } from "./ProgrammingLanguage";
+/**
+ * Add a prefix to a string, ensuring uniqueness in the page
+ * @param {string} s The value to add a prefix to
+ * @return {string} The value with an almost certainly unused prefix
+ */
+export declare function addPapyrosPrefix(s: string): string;
 export declare const MAIN_APP_ID: string;
 export declare const OUTPUT_AREA_WRAPPER_ID: string;
 export declare const OUTPUT_AREA_ID: string;

package/dist/InputManager.d.ts

@@ -1,4 +1,3 @@
-import { UserInputHandler } from "./input/UserInputHandler";
 import { Renderable, RenderOptions } from "./util/Rendering";
 export declare enum InputMode {
     Interactive = "interactive",
@@ -15,7 +14,7 @@ export declare class InputManager extends Renderable {
     private buildInputHandlerMap;
     getInputMode(): InputMode;
     setInputMode(inputMode: InputMode): void;
-    get inputHandler(): UserInputHandler;
+    private get inputHandler();
     isWaiting(): boolean;
     protected _render(options: RenderOptions): void;
     private waitWithPrompt;

package/dist/Library.d.ts

@@ -1,9 +1,12 @@
 import { BackendEvent } from "./BackendEvent";
 import { CodeEditor } from "./CodeEditor";
 import { InputManager, InputMode } from "./InputManager";
-import { OutputManager } from "./OutputManager";
-import { Papyros } from "./Papyros";
+import { FriendlyError, OutputManager } from "./OutputManager";
+import { Papyros, PapyrosConfig, PapyrosRenderOptions } from "./Papyros";
 import { CodeRunner, RunState } from "./CodeRunner";
-export * from "./ProgrammingLanguage";
-export type { BackendEvent };
-export { Papyros, CodeEditor, RunState, CodeRunner, InputManager, InputMode, OutputManager, };
+import { BackendManager } from "./BackendManager";
+import { ProgrammingLanguage } from "./ProgrammingLanguage";
+import { WorkerAutocompleteContext, WorkerDiagnostic } from "./Backend";
+import { ButtonOptions, RenderOptions } from "./util/Rendering";
+export type { BackendEvent, FriendlyError, WorkerAutocompleteContext, WorkerDiagnostic, PapyrosConfig, PapyrosRenderOptions, RenderOptions, ButtonOptions };
+export { Papyros, ProgrammingLanguage, BackendManager, CodeEditor, CodeRunner, RunState, InputManager, InputMode, OutputManager };