@quarto/jupyterlab-quarto 0.1.44 → 0.2.3

package/LICENSE

@@ -1,6 +1,6 @@
 BSD 3-Clause License
 
-Copyright (c) 2023, Posit, PBC
+Copyright (c) 2023, Charles Teague
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without

package/README.md

@@ -1,23 +1,34 @@
 # JupyterLab Quarto Extension
 
-[Quarto](https://www.quarto.org) is an open source project that combines Jupyter notebooks with flexible options to use a single source document to produce high-quality articles, reports, presentations, websites, and books in HTML, PDF, MS Word, ePub, and more. Quarto supports a wide variety of useful new features useful in technical documents, including support for LaTeX equations, citations, cross-references, figure panels, callouts, advanced page layout, and more. 
+[Quarto](https://www.quarto.org) is an open source project that combines Jupyter notebooks with flexible options to use a single source document to produce high-quality articles, reports, presentations, websites, and books in HTML, PDF, MS Word, ePub, and more. Quarto supports a wide variety of useful new features useful in technical documents, including support for LaTeX equations, citations, cross-references, figure panels, callouts, advanced page layout, and more.
 
 The JupyterLab Quarto extension allows JupyterLab to render notebooks which include Quarto markdown content.
 <br/><br/>
+
 <p align="center">
 <img src="https://user-images.githubusercontent.com/261654/230087634-d5027ebc-8508-43b4-81c9-c4b7d6cfa738.png" width="60%">
 </p>
 
+### Binder
+
+You can try an example of the extension in a notebook (though you can't actually render the notebook using Quarto) on Binder.
+
+[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/quarto-dev/jupyterlab-quarto/main?urlpath=lab)
+
+## Status
+
+[![Github Actions Status](https://github.com/quarto-dev/jupyterlab-quarto/workflows/Build/badge.svg)](https://github.com/quarto-dev/jupyterlab-quarto/actions/workflows/build.yml)
+
 ## Requirements
 
-- JupyterLab >= 3.0
+- JupyterLab >= 4.0.0
 
 ## Install
 
 To install the extension, execute:
 
 ```bash
-pip install jupyterlab-quarto
+pip install jupyterlab_quarto
 ```
 
 ## Uninstall
@@ -25,40 +36,42 @@ pip install jupyterlab-quarto
 To remove the extension, execute:
 
 ```bash
-pip uninstall jupyterlab-quarto
+pip uninstall jupyterlab_quarto
 ```
 
 ## Contributing
 
 ### Development install
 
+Note: You will need NodeJS to build the extension package.
+
+The `jlpm` command is JupyterLab's pinned version of
+[yarn](https://yarnpkg.com/) that is installed with JupyterLab. You may use
+`yarn` or `npm` in lieu of `jlpm` below.
+
 ```bash
-# From apps/jupyterlab
+# Clone the repo to your local environment
+# Change directory to the jupyterlab_quarto directory
 # Install package in development mode
 pip install -e "."
 # Link your development version of the extension with JupyterLab
 jupyter labextension develop . --overwrite
 # Rebuild extension Typescript source after making changes
-yarn build
+jlpm build
 ```
-Note: You will need NodeJS to build the extension package.
-
-Note: The `jlpm` command is JupyterLab's pinned version of
-[yarn](https://yarnpkg.com/) that is installed with JupyterLab. You may use
-`yarn` or `npm` in lieu of `jlpm` below.
 
 You can watch the source directory and run JupyterLab at the same time in different terminals to watch for changes in the extension's source and automatically rebuild the extension.
 
 ```bash
 # Watch the source directory in one terminal, automatically rebuilding when needed
-yarn watch
+jlpm watch
 # Run JupyterLab in another terminal
 jupyter lab
 ```
 
 With the watch command running, every saved change will immediately be built locally and available in your running JupyterLab. Refresh JupyterLab to load the change in your browser (you may need to wait several seconds for the extension to be rebuilt).
 
-By default, the `build` command generates the source maps for this extension to make it easier to debug using the browser dev tools. To also generate source maps for the JupyterLab core extensions, you can run the following command:
+By default, the `jlpm build` command generates the source maps for this extension to make it easier to debug using the browser dev tools. To also generate source maps for the JupyterLab core extensions, you can run the following command:
 
 ```bash
 jupyter lab build --minimize=False
@@ -67,12 +80,32 @@ jupyter lab build --minimize=False
 ### Development uninstall
 
 ```bash
-pip uninstall jupyterlab-quarto
+pip uninstall jupyterlab_quarto
 ```
 
 In development mode, you will also need to remove the symlink created by `jupyter labextension develop`
 command. To find its location, you can run `jupyter labextension list` to figure out where the `labextensions`
-folder is located. Then you can remove the symlink named `jupyterlab-quarto` within that folder.
+folder is located. Then you can remove the symlink named `@quarto/jupyterlab-quarto` within that folder.
+
+### Testing the extension
+
+#### Frontend tests
+
+This extension is using [Jest](https://jestjs.io/) for JavaScript code testing.
+
+To execute them, execute:
+
+```sh
+jlpm
+jlpm test
+```
+
+#### Integration tests
+
+This extension uses [Playwright](https://playwright.dev/) for the integration tests (aka user level tests).
+More precisely, the JupyterLab helper [Galata](https://github.com/jupyterlab/jupyterlab/tree/master/galata) is used to handle testing the extension in JupyterLab.
+
+More information are provided within the [ui-tests](./ui-tests/README.md) README.
 
 ### Packaging the extension
 

package/lib/__tests__/jupyterlab_quarto.spec.d.ts

@@ -0,0 +1,3 @@
+/**
+ * Example of [Jest](https://jestjs.io/docs/getting-started) unit tests
+ */

package/lib/__tests__/jupyterlab_quarto.spec.js

@@ -0,0 +1,9 @@
+"use strict";
+/**
+ * Example of [Jest](https://jestjs.io/docs/getting-started) unit tests
+ */
+describe('@quarto/jupyterlab-quarto', () => {
+    it('should be tested', () => {
+        expect(1 + 1).toEqual(2);
+    });
+});

package/lib/ast/ast.d.ts

@@ -0,0 +1,2 @@
+import type Token from 'markdown-it/lib/token';
+export declare const toAst: (toks: Token[]) => Token[];

package/lib/ast/ast.js

@@ -0,0 +1,40 @@
+export const toAst = (toks) => {
+    let pos = 0;
+    const inner = () => {
+        if (pos >= toks.length) {
+            return;
+        }
+        const tok = toks[pos];
+        if (tok.type.endsWith('_open')) {
+            ++pos;
+            const children = [];
+            while (toks[pos].type !== tok.type.replace('_open', '_close')) {
+                children.push(inner());
+            }
+            ++pos;
+            return {
+                ...tok,
+                type: tok.type.replace('_open', ''),
+                children: children
+            };
+        }
+        if (tok.type === 'inline' && tok.children) {
+            const children = toAst(tok.children);
+            ++pos;
+            return {
+                ...tok,
+                children
+            };
+        }
+        ++pos;
+        return tok;
+    };
+    const result = [];
+    while (pos < toks.length) {
+        const node = inner();
+        if (node) {
+            result.push(node);
+        }
+    }
+    return result;
+};

package/lib/const.d.ts

@@ -0,0 +1,4 @@
+import { Token } from '@lumino/coreutils';
+import { MarkdownItManager } from './types';
+export declare const kPackageNamespace = "jupyterlab-quarto";
+export declare const kMarkdownItMgr: Token<MarkdownItManager>;

package/lib/const.js

@@ -0,0 +1,11 @@
+/*
+ * const.ts
+ *
+ * Copyright (C) 2020-2023 Posit Software, PBC
+ *
+ */
+import { Token } from '@lumino/coreutils';
+// The namespace for this project
+export const kPackageNamespace = 'jupyterlab-quarto';
+// The MarkdownIt manager token.
+export const kMarkdownItMgr = new Token(kPackageNamespace);

package/lib/hooks/codemirror.d.ts

@@ -0,0 +1,5 @@
+import { Hook } from '../types';
+import { IEditorLanguageRegistry } from '@jupyterlab/codemirror';
+export declare function codeMirrorPreloadHook(registry: IEditorLanguageRegistry): Hook<string, string>;
+export declare const codeMirrorHighlighter: (languageRegistry: IEditorLanguageRegistry) => (str: string, lang: string, _attr: any) => string;
+export declare const codeMirrorHighlight: (str: string, lang: string, registry: IEditorLanguageRegistry) => string;

package/lib/hooks/codemirror.js

@@ -0,0 +1,77 @@
+/*
+ * hooks.ts
+ *
+ * Copyright (C) 2020-2023 Posit Software, PBC
+ *
+ */
+export function codeMirrorPreloadHook(registry) {
+    // TODO: Properly deal with {r}, {{r}} style expressions
+    const fenced = new RegExp(/^`{3}([^\s]+)/g);
+    return {
+        run: async (source) => {
+            const newModes = new Map();
+            let match;
+            while ((match = fenced.exec(source))) {
+                if (!newModes.has(match[1])) {
+                    newModes.set(match[1], registry.getLanguage(match[1]));
+                }
+            }
+            if (newModes.size) {
+                Promise.all(newModes.values()).catch(console.warn);
+            }
+            return source;
+        }
+    };
+}
+export const codeMirrorHighlighter = (languageRegistry) => {
+    return (str, lang, _attr) => {
+        if (!lang) {
+            return ''; // use external default escaping
+        }
+        try {
+            const spec = languageRegistry.findBest(lang);
+            if (!spec) {
+                console.warn(`No CodeMirror mode: ${lang}`);
+                return '';
+            }
+            const el = document.createElement('div');
+            try {
+                languageRegistry.highlight(str, spec, el);
+                return el.innerHTML;
+            }
+            catch (err) {
+                console.warn(`Failed to highlight ${lang} code`, err);
+            }
+        }
+        catch (err) {
+            console.warn(`No CodeMirror mode: ${lang}`);
+            console.warn(`Require CodeMirror mode error: ${err}`);
+        }
+        return '';
+    };
+};
+export const codeMirrorHighlight = (str, lang, registry) => {
+    if (!lang) {
+        return ''; // use external default escaping
+    }
+    try {
+        const spec = registry.findBest(lang);
+        if (!spec) {
+            console.warn(`No CodeMirror mode: ${lang}`);
+            return '';
+        }
+        const el = document.createElement('div');
+        try {
+            registry.highlight(str, spec, el);
+            return el.innerHTML;
+        }
+        catch (err) {
+            console.warn(`Failed to highlight ${lang} code`, err);
+        }
+    }
+    catch (err) {
+        console.warn(`No CodeMirror mode: ${lang}`);
+        console.warn(`Require CodeMirror mode error: ${err}`);
+    }
+    return '';
+};

package/lib/index.d.ts

@@ -0,0 +1,5 @@
+import { JupyterFrontEndPlugin } from '@jupyterlab/application';
+import { MarkdownItManager } from './types';
+import '../style/index.css';
+declare const _default: (JupyterFrontEndPlugin<void> | JupyterFrontEndPlugin<MarkdownItManager>)[];
+export default _default;

package/lib/index.js

@@ -0,0 +1,61 @@
+import { IEditorLanguageRegistry, IEditorThemeRegistry } from '@jupyterlab/codemirror';
+import { mermaid } from './providers/mermaid';
+import { kMarkdownItMgr, kPackageNamespace } from './const';
+import { footnotes } from './providers/footnotes';
+import '../style/index.css';
+import { markdownItManager } from './manager';
+import { divs } from './providers/divs';
+import { deflist } from './providers/deflist';
+import { gridtables } from './providers/gridtables';
+import { sub } from './providers/sub';
+import { sup } from './providers/sup';
+import { tasklists } from './providers/tasklists';
+import { cites } from './providers/cites';
+import { attrs } from './providers/attrs';
+import { callouts } from './providers/callouts';
+import { decorator } from './providers/decorator';
+import { yaml } from './providers/yaml';
+import { math } from './providers/math';
+import { figures } from './providers/figures';
+import { figureDivs } from './providers/figure-divs';
+import { tableCaptions } from './providers/table-captions';
+import { spans } from './providers/spans';
+import { shortcodes } from './providers/shortcodes';
+const plugin = {
+    id: `${kPackageNamespace}:plugin`,
+    autoStart: true,
+    provides: kMarkdownItMgr,
+    requires: [IEditorThemeRegistry, IEditorLanguageRegistry],
+    activate: (_app, themeRegistry, languageRegistry) => {
+        console.log('JupyterLab extension @quarto/jupyterlab-quarto is activated!');
+        // Create a markdown rendering manager
+        return markdownItManager(themeRegistry, languageRegistry);
+    }
+};
+// Markdown It Extensions which provide base Pandoc behavior
+const kPandocExtensions = [
+    footnotes,
+    spans,
+    attrs,
+    deflist,
+    figures,
+    gridtables,
+    sub,
+    sup,
+    tasklists,
+    divs,
+    math
+];
+// Markdown It Extensions which provide Quarto specific behavior
+const kQuartoExtensions = [
+    figureDivs,
+    tableCaptions,
+    cites,
+    mermaid,
+    callouts,
+    decorator,
+    yaml,
+    shortcodes
+];
+// The extensions that should be enabled for Jupyter
+export default [plugin, ...kPandocExtensions, ...kQuartoExtensions];

package/lib/manager.d.ts

@@ -0,0 +1,8 @@
+import { IEditorLanguageRegistry, IEditorThemeRegistry } from '@jupyterlab/codemirror';
+import { Options } from 'markdown-it';
+import { RenderedMarkdown } from './widgets';
+import { MarkdownItPluginProvider, Renderer } from './types';
+export declare function markdownItManager(themeRegistry: IEditorThemeRegistry, languageRegistry: IEditorLanguageRegistry): {
+    registerPlugin(provider: MarkdownItPluginProvider): void;
+    getRenderer(widget: RenderedMarkdown, options?: Options): Promise<Renderer>;
+};

package/lib/manager.js

@@ -0,0 +1,115 @@
+/*
+ * manager.ts
+ *
+ * Copyright (C) 2020-2023 Posit Software, PBC
+ *
+ */
+import { markdownRendererFactory } from '@jupyterlab/rendermime';
+import MarkdownIt from 'markdown-it';
+import { RenderedMarkdown } from './widgets';
+import { codeMirrorHighlighter, codeMirrorPreloadHook } from './hooks/codemirror';
+// Provides resolved MarkdownIt options using the passed in options, the plugin
+// options, and default options.
+const resolveOptions = (widget, options, providers, themeRegistry, languageRegistry) => {
+    // Build options table
+    let allOptions = {
+        html: true,
+        linkify: true,
+        typographer: true,
+        langPrefix: `cm-s-${themeRegistry.defaultTheme} language-`,
+        highlight: codeMirrorHighlighter(languageRegistry)
+    };
+    for (const plugin of providers) {
+        if (plugin.options) {
+            try {
+                // Add options for this plugin
+                allOptions = { ...allOptions, ...plugin.options(widget) };
+            }
+            catch (err) {
+                console.warn(`Failed to get options from markdown-it plugin ${plugin.id}`, err);
+            }
+        }
+    }
+    return {
+        ...allOptions,
+        ...options
+    };
+};
+export function markdownItManager(themeRegistry, languageRegistry) {
+    // The plugin providers
+    const pluginProviders = new Map();
+    //  The IMarkdownItManager
+    const manager = {
+        registerPlugin(provider) {
+            pluginProviders.set(provider.id, provider);
+        },
+        async getRenderer(widget, options = {}) {
+            var _a, _b, _c, _d;
+            // Fetch the list of providers
+            const providers = [...pluginProviders.values()];
+            providers.sort(sortRanked);
+            // Create MarkdownIt instance
+            const allOptions = resolveOptions(widget, options, providers, themeRegistry, languageRegistry);
+            let md = new MarkdownIt('default', allOptions);
+            // Lifecycle hooks
+            const preParseHooks = [];
+            const postRenderHooks = [];
+            // add mode pre-loading hook if using default highlighter
+            if (codeMirrorHighlighter(languageRegistry) === allOptions.highlight) {
+                preParseHooks.push(codeMirrorPreloadHook(languageRegistry));
+            }
+            // Build MarkdownIt and load lifecycle hooks
+            for (const provider of providers) {
+                try {
+                    // Load MarkdownIt plugin
+                    const [plugin, ...pluginOptions] = await provider.plugin();
+                    // Build MarkdownIt instance
+                    md = md.use(plugin, ...pluginOptions);
+                    // Build table of lifecycle hooks
+                    if (((_a = provider.hooks) === null || _a === void 0 ? void 0 : _a.preParse) !== undefined) {
+                        preParseHooks.push((_b = provider.hooks) === null || _b === void 0 ? void 0 : _b.preParse);
+                    }
+                    if (((_c = provider.hooks) === null || _c === void 0 ? void 0 : _c.postRender) !== undefined) {
+                        postRenderHooks.push((_d = provider.hooks) === null || _d === void 0 ? void 0 : _d.postRender);
+                    }
+                }
+                catch (err) {
+                    console.warn(`Failed to load/use markdown-it plugin ${provider.id}`, err);
+                }
+            }
+            // Sort hooks by rank
+            preParseHooks.sort(sortRanked);
+            postRenderHooks.sort(sortRanked);
+            return {
+                // Parse and render Markdown
+                render: content => {
+                    return md.render(content);
+                },
+                // Run hooks serially
+                preParse: async (content) => {
+                    for (const hook of preParseHooks) {
+                        content = await hook.run(content);
+                    }
+                    return content;
+                },
+                // Run hooks serially
+                postRender: async (node) => {
+                    for (const hook of postRenderHooks) {
+                        await hook.run(node);
+                    }
+                }
+            };
+        }
+    };
+    // Register the Renderer
+    markdownRendererFactory.createRenderer = (options) => {
+        return new RenderedMarkdown(options, manager);
+    };
+    return manager;
+}
+// Sorts by rank, using 100 if no default is provided.
+const kDefaultRank = 100;
+const sortRanked = (left, right) => {
+    var _a, _b;
+    return ((_a = left.rank) !== null && _a !== void 0 ? _a : kDefaultRank) - ((_b = right.rank) !== null && _b !== void 0 ? _b : kDefaultRank);
+};

package/lib/plugins/callouts.d.ts

@@ -0,0 +1,2 @@
+import type MarkdownIt from 'markdown-it/lib';
+export declare const calloutPlugin: (md: MarkdownIt) => void;