@dodona/papyros 0.1.7-rc → 0.1.8

package/README.md

@@ -12,29 +12,22 @@
   </a>
 </p>
 
-Papyros is a programming scratchpad in the browser. It allows running arbitrary
-in various programming languages directly in your browser, no installation required.
+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.
 By taking away obstacles between students and coding, the learning experience becomes
-smoother and less error-prone. 
-
-Papyros aims to be:
-
-- **Easy to use** by having minimal installation instructions and an intuitive user interface
-- **Flexible** to support many programming languages
+smoother and less error-prone.
 
 Currently, Papyros provides support for the following programming languages:
 - Python, powered by [Pyodide](https://pyodide.org/en/stable/)
 - JavaScript, powered by your browser
 
-## Installation
+## Using Papyros in your own project
 
 You can install Papyros on your system using npm:
 ```shell
 npm install -g @dodona/papyros
 ```
 
-## Usage
-
 Papyros currently supports two modes of operation: stand-alone and embedded.
 
 In stand-alone mode, Papyros runs as a full application in the browser. 
@@ -51,6 +44,38 @@ 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
+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
+
+### 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
+
+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'
+```
+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 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 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.
 
 ## Documentation
 
@@ -78,4 +103,4 @@ You can view the results in your browser by visting http://localhost:8080.
 
 ## Try it online
 
-Start coding immediately in your [browser](https://docs.dodona.be/papyros/).
+Start coding immediately in your [browser](https://papyros.dodona.be/).

package/dist/Backend.d.ts

@@ -1,4 +1,5 @@
 import { PapyrosEvent } from "./PapyrosEvent";
+import { Channel } from "sync-message";
 export declare abstract class Backend {
     onEvent: (e: PapyrosEvent) => any;
     runId: number;
@@ -6,11 +7,10 @@ export declare abstract class Backend {
     /**
      * Initialize the backend, setting up any globals required
      * @param {function(PapyrosEvent):void} onEvent Callback for when events occur
-     * @param {Uint8Array} inputTextArray Optional shared buffer for input
-     * @param {Int32Array} inputMetaData Optional shared buffer for metadata about input
+     * @param {Channel} channel for communication with the main thread
      * @return {Promise<void>} Promise of launching
      */
-    launch(onEvent: (e: PapyrosEvent) => void, inputTextArray?: Uint8Array, inputMetaData?: Int32Array): Promise<void>;
+    launch(onEvent: (e: PapyrosEvent) => void, channel: Channel): Promise<void>;
     abstract _runCodeInternal(code: string): Promise<any>;
     /**
      * Validate and run arbitrary code

package/dist/CodeEditor.d.ts

@@ -1,12 +1,23 @@
-import { Compartment } from "@codemirror/state";
+import { LanguageSupport } from "@codemirror/language";
+import { Compartment, Extension } from "@codemirror/state";
 import { ProgrammingLanguage } from "./ProgrammingLanguage";
 import { EditorView } from "@codemirror/view";
+import { RenderOptions } from "./util/Util";
 export declare class CodeEditor {
     editorView: EditorView;
     languageCompartment: Compartment;
     indentCompartment: Compartment;
-    constructor(element: HTMLElement, language: ProgrammingLanguage, initialCode?: string, indentLength?: number);
-    setLanguage(language: ProgrammingLanguage): void;
+    placeholderCompartment: Compartment;
+    panelCompartment: Compartment;
+    constructor(language: ProgrammingLanguage, editorPlaceHolder: string, initialCode?: string, indentLength?: number);
+    render(options: RenderOptions, panel?: HTMLElement): HTMLElement;
+    setLanguage(language: ProgrammingLanguage, editorPlaceHolder: string): void;
     setIndentLength(indentLength: number): void;
+    setPanel(panel: HTMLElement): void;
     getCode(): string;
+    setCode(code: string): void;
+    focus(): void;
+    static getIndentUnit(indentLength: number): string;
+    static getLanguageSupport(language: ProgrammingLanguage): LanguageSupport;
+    static getExtensions(): Array<Extension>;
 }

package/dist/Constants.d.ts

@@ -1,15 +1,19 @@
 import { ProgrammingLanguage } from "./ProgrammingLanguage";
 export declare const MAIN_APP_ID = "papyros";
 export declare const OUTPUT_TA_ID = "code-output-area";
+export declare const INPUT_AREA_WRAPPER_ID = "code-input-area-wrapper";
 export declare const INPUT_TA_ID = "code-input-area";
 export declare const EDITOR_WRAPPER_ID = "code-area";
+export declare const PANEL_WRAPPER_ID = "code-status-panel";
 export declare const STATE_SPINNER_ID = "state-spinner";
 export declare const APPLICATION_STATE_TEXT_ID = "application-state-text";
 export declare const RUN_BTN_ID = "run-code-btn";
-export declare const TERMINATE_BTN_ID = "terminate-btn";
+export declare const STOP_BTN_ID = "stop-btn";
+export declare const SEND_INPUT_BTN_ID = "send-input-btn";
+export declare const SWITCH_INPUT_MODE_A_ID = "switch-input-mode";
 export declare const PROGRAMMING_LANGUAGE_SELECT_ID = "programming-language-select";
 export declare const DEFAULT_PROGRAMMING_LANGUAGE = ProgrammingLanguage.Python;
+export declare const EXAMPLE_SELECT_ID = "example-select";
 export declare const LOCALE_SELECT_ID = "locale-select";
 export declare const DEFAULT_LOCALE = "nl";
-export declare const INPUT_RELATIVE_URL = "/__papyros_input";
-export declare const SERVICE_WORKER_PATH = "./inputServiceWorker.js";
+export declare const DEFAULT_SERVICE_WORKER = "inputServiceWorker.js";

package/dist/InputManager.d.ts

@@ -0,0 +1,32 @@
+import { PapyrosEvent } from "./PapyrosEvent";
+import { RenderOptions } from "./util/Util";
+import { Channel } from "sync-message";
+export declare enum InputMode {
+    Interactive = "interactive",
+    Batch = "batch"
+}
+export declare const INPUT_MODES: InputMode[];
+interface InputSession {
+    lineNr: number;
+}
+export declare class InputManager {
+    renderOptions: RenderOptions;
+    inputMode: InputMode;
+    waiting: boolean;
+    batchInput: string;
+    onSend: () => void;
+    session: InputSession;
+    channel: Channel;
+    messageId: string;
+    constructor(onSend: () => void, inputMode: InputMode);
+    get enterButton(): HTMLButtonElement;
+    get inputArea(): HTMLInputElement;
+    render(options?: RenderOptions): void;
+    setInputMode(inputMode: InputMode): void;
+    setWaiting(waiting: boolean, prompt?: string): void;
+    sendLine(): Promise<boolean>;
+    onInput(e?: PapyrosEvent): Promise<void>;
+    onRunStart(): void;
+    onRunEnd(): void;
+}
+export {};

package/dist/InputServiceWorker.d.ts

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

package/dist/OutputManager.d.ts

@@ -0,0 +1,23 @@
+import { PapyrosEvent } from "./PapyrosEvent";
+import { RenderOptions } from "./util/Util";
+export interface FriendlyError {
+    name: string;
+    traceback?: string;
+    info?: string;
+    why?: string;
+    what?: string;
+    where?: string;
+}
+export declare class OutputManager {
+    outputAreaId: string;
+    options: RenderOptions;
+    get outputArea(): HTMLElement;
+    renderNextElement(html: string): void;
+    spanify(text: string, ignoreEmpty?: boolean): string;
+    showOutput(output: PapyrosEvent): void;
+    showError(error: FriendlyError | string): void;
+    render(options: RenderOptions): HTMLElement;
+    reset(): void;
+    onRunStart(): void;
+    onRunEnd(): void;
+}

package/dist/Papyros.d.ts

@@ -2,57 +2,69 @@ import "./Papyros.css";
 import { Remote } from "comlink";
 import { Backend } from "./Backend";
 import { CodeEditor } from "./CodeEditor";
+import { InputManager, InputMode } from "./InputManager";
 import { PapyrosEvent } from "./PapyrosEvent";
 import { ProgrammingLanguage } from "./ProgrammingLanguage";
+import { RenderOptions, ButtonOptions } from "./util/Util";
+import { StatusPanel } from "./StatusPanel";
+import { OutputManager } from "./OutputManager";
 declare enum PapyrosState {
     Loading = "loading",
     Running = "running",
     AwaitingInput = "awaiting_input",
-    Terminating = "terminating",
+    Stopping = "stopping",
     Ready = "ready"
 }
 declare class PapyrosStateManager {
     state: PapyrosState;
-    stateSpinner: HTMLElement;
-    stateText: HTMLElement;
-    runButton: HTMLButtonElement;
-    terminateButton: HTMLButtonElement;
-    constructor();
+    statusPanel: StatusPanel;
+    get runButton(): HTMLButtonElement;
+    get stopButton(): HTMLButtonElement;
+    constructor(statusPanel: StatusPanel, onRunClicked: () => void, onStopClicked: () => void);
     setState(state: PapyrosState, message?: string): void;
+    render(options: RenderOptions): HTMLElement;
 }
 interface PapyrosCodeState {
     programmingLanguage: ProgrammingLanguage;
     editor: CodeEditor;
     backend: Remote<Backend>;
     runId: number;
-    outputArea: HTMLInputElement;
-}
-interface PapyrosInputState {
-    lineNr: number;
-    textEncoder: TextEncoder;
-    inputArea: HTMLInputElement;
-    inputTextArray?: Uint8Array;
-    inputMetaData?: Int32Array;
 }
 interface PapyrosConfig {
     standAlone: boolean;
-    locale: string;
     programmingLanguage: ProgrammingLanguage;
+    locale: string;
+    inputMode: InputMode;
+}
+interface PapyrosRenderOptions {
+    papyros?: RenderOptions;
+    code?: RenderOptions;
+    panel?: RenderOptions;
+    input?: RenderOptions;
+    output?: RenderOptions;
 }
 export declare class Papyros {
+    config: PapyrosConfig;
     stateManager: PapyrosStateManager;
     codeState: PapyrosCodeState;
-    inputState: PapyrosInputState;
-    constructor(programmingLanguage: ProgrammingLanguage, inputTextArray?: Uint8Array, inputMetaData?: Int32Array);
+    inputManager: InputManager;
+    outputManager: OutputManager;
+    constructor(config: PapyrosConfig);
+    get state(): PapyrosState;
     launch(): Promise<Papyros>;
     setProgrammingLanguage(programmingLanguage: ProgrammingLanguage): Promise<void>;
+    setCode(code: string): void;
+    getCode(): string;
     startBackend(): Promise<void>;
-    static fromElement(parent: HTMLElement, config: PapyrosConfig): Promise<Papyros>;
+    configureInput(allowReload: boolean, serviceWorkerRoot?: string, serviceWorkerName?: string): Promise<boolean>;
     onError(e: PapyrosEvent): void;
-    sendInput(): Promise<boolean>;
     onInput(e: PapyrosEvent): Promise<void>;
     onMessage(e: PapyrosEvent): void;
     runCode(): Promise<void>;
-    terminate(): Promise<void>;
+    stop(): Promise<void>;
+    render(renderOptions: PapyrosRenderOptions): void;
+    addButton(options: ButtonOptions, onClick: () => void): void;
+    static supportsProgrammingLanguage(language: string): boolean;
+    static toProgrammingLanguage(language: string): ProgrammingLanguage | undefined;
 }
 export {};

package/dist/PapyrosEvent.d.ts

@@ -2,4 +2,5 @@ export interface PapyrosEvent {
     type: "input" | "output" | "script" | "success" | "error";
     data: string;
     runId: number;
+    content?: string;
 }

package/dist/ProgrammingLanguage.d.ts

@@ -2,5 +2,3 @@ export declare enum ProgrammingLanguage {
     Python = "Python",
     JavaScript = "JavaScript"
 }
-export declare const PROGRAMMING_LANGUAGES: ProgrammingLanguage[];
-export declare function plFromString(language: string): ProgrammingLanguage;

package/dist/StatusPanel.d.ts

@@ -0,0 +1,17 @@
+import { ButtonOptions, RenderOptions } from "./util/Util";
+interface DynamicButton {
+    id: string;
+    buttonHTML: string;
+    onClick: () => void;
+}
+export declare class StatusPanel {
+    buttons: Array<DynamicButton>;
+    constructor();
+    addButton(options: ButtonOptions, onClick: () => void): void;
+    get statusSpinner(): HTMLElement;
+    get statusText(): HTMLElement;
+    showSpinner(show: boolean): void;
+    setStatus(status: string): void;
+    render(options: RenderOptions): HTMLElement;
+}
+export {};

package/dist/examples/Examples.d.ts

@@ -0,0 +1,6 @@
+import { ProgrammingLanguage } from "../ProgrammingLanguage";
+export declare function getExamples(language: ProgrammingLanguage): {
+    [key: string]: string;
+};
+export declare function getExampleNames(language: ProgrammingLanguage): Array<string>;
+export declare function getCodeForExample(language: ProgrammingLanguage, name: string): string;

package/dist/examples/JavaScriptExamples.d.ts

@@ -0,0 +1,5 @@
+export declare const JAVASCRIPT_EXAMPLES: {
+    "Hello world!": string;
+    Input: string;
+    Fibonacci: string;
+};

package/dist/examples/PythonExamples.d.ts

@@ -0,0 +1,11 @@
+export declare const PYTHON_EXAMPLES: {
+    "Hello, World!": string;
+    Input: string;
+    Fibonacci: string;
+    Doctests: string;
+    Async: string;
+    Erroneous: string;
+    Unicode: string;
+    Files: string;
+    Matplotlib: string;
+};