@dodona/papyros 0.1.954-darkmode → 0.2.1

package/README.md

@@ -13,7 +13,7 @@
 </p>
 
 Papyros is a programming scratchpad in the browser. It allows running code
-directly in your browser, no installation required. Right now, the focus in on providing a great experience for Python, while also supporting JavaScript.
+directly in your browser, no installation required. Right now, the focus is on providing a great experience for Python, while also supporting JavaScript.
 By taking away obstacles between students and coding, the learning experience becomes
 smoother and less error-prone.
 
@@ -38,22 +38,24 @@ 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.
+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.
 The following options are supported:
-- standAlone: Whether to operate in stand-alone or embedded mode as described above.
-- 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
+- `standAlone`: Whether to operate in stand-alone or embedded mode as described above.
+- `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.
+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
+
+- `code`: the CodeEditor.
+- `panel`: the StatusPanel in the CodeEditor
+- `input`: the field for the user input
+- `output`: the panel for output of the code
 
 ### User input
 

package/dist/Backend.d.ts

@@ -1,6 +1,7 @@
 import { CompletionContext, CompletionResult } from "@codemirror/autocomplete";
 import { BackendEvent } from "./BackendEvent";
 import { SyncExtras } from "comsync";
+import { BackendEventQueue } from "./BackendEventQueue";
 /**
  * Interface to represent the CodeMirror CompletionContext in a worker
  */
@@ -34,9 +35,16 @@ export interface WorkerAutocompleteContext {
         text: string;
     } | null;
 }
+export interface WorkerDiagnostic {
+    lineNr: number;
+    columnNr: number;
+    severity: "info" | "warning" | "error";
+    message: string;
+}
 export declare abstract class Backend<Extras extends SyncExtras = SyncExtras> {
     protected extras: Extras;
     protected onEvent: (e: BackendEvent) => any;
+    protected queue: BackendEventQueue;
     /**
      * Constructor is limited as it is meant to be used as a WebWorker
      * Proper initialization occurs in the launch method when the worker is started
@@ -74,4 +82,17 @@ export declare abstract class Backend<Extras extends SyncExtras = SyncExtras> {
      * @param {WorkerAutocompleteContext} context Context to autcomplete in
      */
     abstract autocomplete(context: WorkerAutocompleteContext): Promise<CompletionResult | null>;
+    /**
+     * Generate linting suggestions for the given code
+     * @param {string} code The code to lint
+     */
+    abstract lintCode(code: string): Promise<Array<WorkerDiagnostic>>;
+    /**
+     * @return {boolean} Whether too many output events were generated
+     */
+    hasOverflow(): boolean;
+    /**
+     * @return {Array<BackendEvent>} The events that happened after overflow
+     */
+    getOverflow(): Array<BackendEvent>;
 }

package/dist/BackendEventQueue.d.ts

@@ -0,0 +1,85 @@
+import { BackendEvent, BackendEventType } from "./BackendEvent";
+/**
+ * Queue to limit the amount of messages sent between threads
+ * This prevents communication issues which arise either in Comlink
+ * or in the WebWorker message passing code
+ */
+export declare class BackendEventQueue {
+    /**
+     * Function to process events in the queue
+     */
+    private callback;
+    /**
+     * The maximal amount of output events to send before overflowing
+     */
+    private limit;
+    /**
+     * The time in milliseconds before sending events through
+     */
+    private flushTime;
+    /**
+     * Queue storing the BackendEvents before flushing
+     */
+    private queue;
+    /**
+     * Queue storing Output-events after overflowing
+     */
+    private overflow;
+    /**
+     * Time in milliseconds when the last flush occurred
+     */
+    private lastFlushTime;
+    /**
+     * Amount of BackendEvents sent through this run
+     */
+    private sendCount;
+    /**
+     * Decoder to convert data to strings
+     */
+    private decoder;
+    /**
+     * @param {Function} callback Function to process events in the queue
+     * @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);
+    /**
+     * Add an element to the queue
+     * @param {BackendEventType} type The type of the event
+     * @param {string | BufferSource} text The data for the event
+     * @param {string | any} extra Extra data for the event
+     * If string, interpreted as the contentType
+     * If anything else, it should contain a contentType
+     * If the contentType is not textual, an error is thrown
+     */
+    put(type: BackendEventType, text: string | BufferSource, extra: string | any): void;
+    /**
+     * @return {boolean} Whether the queue contents should be flushed
+     */
+    protected shouldFlush(): boolean;
+    /**
+     * Reset the queue contents for a new run
+     */
+    reset(): void;
+    /**
+     * @param {BackendEvent} e The event put in the queue
+     * @return {number} The amount of lines of data in the event
+     */
+    private static lines;
+    /**
+     * Flush the queue contents using the callback
+     */
+    flush(): void;
+    /**
+     * @return {boolean} Whether too many output events were generated
+     */
+    hasOverflow(): boolean;
+    /**
+     * @return {Array<BackendEvent>} The events that happened after overflow
+     */
+    getOverflow(): Array<BackendEvent>;
+    /**
+     * @param {Function} callback The event-consuming callback
+     */
+    setCallback(callback: (e: BackendEvent) => void): void;
+}

package/dist/BackendManager.d.ts

@@ -25,7 +25,7 @@ export declare abstract class BackendManager {
      * Map an event type to interested subscribers
      * Uses an Array to maintain order of subscription
      */
-    static subscriberMap: Map<BackendEventType, Array<BackendEventListener>>;
+    private static subscriberMap;
     /**
      * The channel used to communicate with the SyncClients
      */
@@ -40,7 +40,13 @@ export declare abstract class BackendManager {
      * @param {ProgrammingLanguage} language The programming language supported by the backend
      * @return {SyncClient<Backend>} A SyncClient for the Backend
      */
-    static startBackend(language: ProgrammingLanguage): SyncClient<Backend>;
+    static getBackend(language: ProgrammingLanguage): SyncClient<Backend>;
+    /**
+     * Remove a backend for the given language
+     * @param {ProgrammingLanguage} language The programming language supported by the backend
+     * @return {boolean} Whether the remove operation had any effect
+     */
+    static removeBackend(language: ProgrammingLanguage): boolean;
     /**
      * Register a callback for when an event of a certain type is published
      * @param {BackendEventType} type The type of event to subscribe to

package/dist/CodeEditor.d.ts

@@ -1,9 +1,8 @@
-import { LanguageSupport } from "@codemirror/language";
-import { Compartment, Extension } from "@codemirror/state";
 import { ProgrammingLanguage } from "./ProgrammingLanguage";
-import { EditorView } from "@codemirror/view";
-import { CompletionSource } from "@codemirror/autocomplete";
 import { Renderable, RenderOptions } from "./util/Rendering";
+import { CompletionSource } from "@codemirror/autocomplete";
+import { EditorView } from "@codemirror/view";
+import { Diagnostic } from "@codemirror/lint";
 /**
  * Component that provides useful features to users writing code
  */
@@ -11,55 +10,49 @@ export declare class CodeEditor extends Renderable {
     /**
      * Reference to the user interface of the editor
      */
-    editorView: EditorView;
-    /**
-     * Compartment to change language at runtime
-     */
-    languageCompartment: Compartment;
-    /**
-     * Compartment to configure indentation level at runtime
-     */
-    indentCompartment: Compartment;
-    /**
-     * Compartment to configure the placeholder at runtime
-     */
-    placeholderCompartment: Compartment;
+    readonly editorView: EditorView;
     /**
-    * Compartment to configure the panel at runtime
+     * Mapping from CodeEditorOptions to a configurable compartment
      */
-    panelCompartment: Compartment;
-    /**
-     * Compartment to configure the autocompletion at runtime
-     */
-    autocompletionCompartment: Compartment;
-    /**
-     * Compartment to configure styling at runtime (e.g. switching to dark mode)
-     */
-    styleCompartent: Compartment;
+    private compartments;
     /**
      * Construct a new CodeEditor
      * @param {string} initialCode The initial code to display
      * @param {number} indentLength The length in spaces for the indent unit
      */
     constructor(initialCode?: string, indentLength?: number);
+    /**
+     * Helper method to dispatch configuration changes at runtime
+     * @param {Array<[Option, Extension]>} items Array of items to reconfigure
+     * The option indicates the relevant compartment
+     * The extension indicates the new configuration
+     */
+    private reconfigure;
+    /**
+     * Render the editor with the given options and panel
+     * @param {RenderOptions} options Options for rendering
+     * @param {HTMLElement} panel The panel to display at the bottom
+     * @return {HTMLElement} The rendered element
+     */
     protected _render(options: RenderOptions): void;
     /**
-     * Set the language that is currently used
      * @param {ProgrammingLanguage} language The language to use
      */
-    setLanguage(language: ProgrammingLanguage): void;
+    setProgrammingLanguage(language: ProgrammingLanguage): void;
     /**
      * @param {CompletionSource} completionSource Function to obtain autocomplete results
      */
     setCompletionSource(completionSource: CompletionSource): void;
     /**
-     * Set the length in spaces of the indentation unit
-     * @param {number} indentLength The number of spaces to use
+     * @param {LintSource} lintSource Function to obtain linting results
+     */
+    setLintingSource(lintSource: (view: EditorView) => readonly Diagnostic[] | Promise<readonly Diagnostic[]>): void;
+    /**
+     * @param {number} indentLength The number of spaces to use for indentation
      */
     setIndentLength(indentLength: number): void;
     /**
-     * Set the panel that is displayed at the bottom of the editor
-     * @param {HTMLElement} panel The panel to display
+     * @param {HTMLElement} panel The panel to display at the bottom of the editor
      */
     setPanel(panel: HTMLElement): void;
     /**
@@ -76,40 +69,38 @@ export declare class CodeEditor extends Renderable {
     focus(): void;
     /**
      * @param {number} indentLength The amount of spaces to use
-     * @return {string} The indentation unit to use
+     * @return {string} The indentation unit to be used by CodeMirror
      */
-    static getIndentUnit(indentLength: number): string;
+    private static getIndentUnit;
     /**
      * @param  {ProgrammingLanguage} language The language to support
      * @return {LanguageSupport} CodeMirror LanguageSupport for the language
      */
-    static getLanguageSupport(language: ProgrammingLanguage): LanguageSupport;
-    /**
-    *  - [syntax highlighting depending on the language](#getLanguageSupport)
-    *  - [line numbers](#gutter.lineNumbers)
-    *  - [special character highlighting](#view.highlightSpecialChars)
-    *  - [the undo history](#history.history)
-    *  - [a fold gutter](#fold.foldGutter)
-    *  - [custom selection drawing](#view.drawSelection)
-    *  - [multiple selections](#state.EditorState^allowMultipleSelections)
-    *  - [reindentation on input](#language.indentOnInput)
-    *  - [syntax highlighting with the default highlight style]
-    *   (#highlight.defaultHighlightStyle) (as fallback)
-    *  - [bracket matching](#matchbrackets.bracketMatching)
-    *  - [bracket closing](#closebrackets.closeBrackets)
-    *  - [autocompletion](#autocomplete.autocompletion)
-    *  - [rectangular selection](#rectangular-selection.rectangularSelection)
-    *  - [active line highlighting](#view.highlightActiveLine)
-    *  - [active line gutter highlighting](#gutter.highlightActiveLineGutter)
-    *  - [selection match highlighting](#search.highlightSelectionMatches)
+    private static getLanguageSupport;
+    /**
+    *  - line numbers
+    *  - special character highlighting
+    *  - the undo history
+    *  - a fold gutter
+    *  - gutter for linting
+    *  - custom selection drawing
+    *  - multiple selections
+    *  - reindentation on input
+    *  - bracket matching
+    *  - bracket closing
+    *  - autocompletion
+    *  - rectangular selection
+    *  - active line highlighting
+    *  - active line gutter highlighting
+    *  - selection match highlighting
     * Keymaps:
-    *  - [bracket closing](#commands.closeBracketsKeymap)
-    *  - [the default command bindings](#commands.defaultKeymap)
-    *  - [search](#search.searchKeymap)
-    *  - [commenting](#comment.commentKeymap)
-    *  - [linting](#lint.lintKeymap)
-    *  - [indenting with tab](#commands.indentWithTab)
+    *  - the default command bindings
+    *  - bracket closing
+    *  - searching
+    *  - linting
+    *  - completion
+    *  - indenting with tab
     *  @return {Array<Extension} Default extensions to use
     */
-    static getExtensions(): Array<Extension>;
+    private static getExtensions;
 }

package/dist/Constants.d.ts

@@ -1,6 +1,8 @@
 import { ProgrammingLanguage } from "./ProgrammingLanguage";
 export declare const MAIN_APP_ID: string;
-export declare const OUTPUT_TA_ID: string;
+export declare const OUTPUT_AREA_WRAPPER_ID: string;
+export declare const OUTPUT_AREA_ID: string;
+export declare const OUTPUT_OVERFLOW_ID: string;
 export declare const INPUT_AREA_WRAPPER_ID: string;
 export declare const INPUT_TA_ID: string;
 export declare const USER_INPUT_WRAPPER_ID: string;

package/dist/InputManager.d.ts

@@ -1,4 +1,3 @@
-import { BackendEvent } from "./BackendEvent";
 import { UserInputHandler } from "./input/UserInputHandler";
 import { Renderable, RenderOptions } from "./util/Rendering";
 export declare enum InputMode {
@@ -17,15 +16,16 @@ export declare class InputManager extends Renderable {
     getInputMode(): InputMode;
     setInputMode(inputMode: InputMode): void;
     get inputHandler(): UserInputHandler;
-    _render(options: RenderOptions): void;
-    waitWithPrompt(waiting: boolean, prompt?: string): void;
-    onUserInput(): Promise<void>;
+    isWaiting(): boolean;
+    protected _render(options: RenderOptions): void;
+    private waitWithPrompt;
+    private onUserInput;
     /**
      * Asynchronously handle an input request by prompting the user for input
      * @param {BackendEvent} e Event containing the input data
      * @return {Promise<void>} Promise of handling the request
      */
-    onInputRequest(e: BackendEvent): Promise<void>;
-    onRunStart(): void;
-    onRunEnd(): void;
+    private onInputRequest;
+    private onRunStart;
+    private onRunEnd;
 }