From 48e695a2c89edad6e4880e7decfdb36d524f8279 Mon Sep 17 00:00:00 2001
From: Kyle Kelley <rgbkrk@gmail.com>
Date: Thu, 12 Oct 2023 15:32:38 -0700
Subject: feat(unstable): add Deno.jupyter.display API (#20819)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

This brings in [`display`](https://github.com/rgbkrk/display.js) as part
of the `Deno.jupyter` namespace.

Additionally these APIs were added:
- "Deno.jupyter.md"
- "Deno.jupyter.html"
- "Deno.jupyter.svg"
- "Deno.jupyter.format"

These APIs greatly extend capabilities of rendering output in Jupyter
notebooks.

---------

Co-authored-by: Bartek Iwańczuk <biwanczuk@gmail.com>
---
 cli/tsc/dts/lib.deno.unstable.d.ts | 124 +++++++++++++++++++++++++++++++++++++
 1 file changed, 124 insertions(+)

(limited to 'cli/tsc/dts/lib.deno.unstable.d.ts')

diff --git a/cli/tsc/dts/lib.deno.unstable.d.ts b/cli/tsc/dts/lib.deno.unstable.d.ts
index 26bb78757..76e8ef49b 100644
--- a/cli/tsc/dts/lib.deno.unstable.d.ts
+++ b/cli/tsc/dts/lib.deno.unstable.d.ts
@@ -2076,6 +2076,130 @@ declare namespace Deno {
    *
    * @category Jupyter */
   export namespace jupyter {
+    export interface DisplayOptions {
+      raw?: boolean;
+      update?: boolean;
+      display_id?: string;
+    }
+
+    type VegaObject = {
+      $schema: string;
+      [key: string]: unknown;
+    };
+
+    /**
+     * A collection of supported media types and data for Jupyter frontends.
+     */
+    export type MediaBundle = {
+      "text/plain"?: string;
+      "text/html"?: string;
+      "image/svg+xml"?: string;
+      "text/markdown"?: string;
+      "application/javascript"?: string;
+
+      // Images (per Jupyter spec) must be base64 encoded. We could _allow_
+      // accepting Uint8Array or ArrayBuffer within `display` calls, however we still
+      // must encode them for jupyter.
+      "image/png"?: string; // WISH: Uint8Array | ArrayBuffer
+      "image/jpeg"?: string; // WISH: Uint8Array | ArrayBuffer
+      "image/gif"?: string; // WISH: Uint8Array | ArrayBuffer
+      "application/pdf"?: string; // WISH: Uint8Array | ArrayBuffer
+
+      // NOTE: all JSON types must be objects at the top level (no arrays, strings, or other primitives)
+      "application/json"?: object;
+      "application/geo+json"?: object;
+      "application/vdom.v1+json"?: object;
+      "application/vnd.plotly.v1+json"?: object;
+      "application/vnd.vega.v5+json"?: VegaObject;
+      "application/vnd.vegalite.v4+json"?: VegaObject;
+      "application/vnd.vegalite.v5+json"?: VegaObject;
+
+      // Must support a catch all for custom media types / mimetypes
+      [key: string]: string | object | undefined;
+    };
+
+    export const $display: unique symbol;
+
+    export type Displayable = {
+      [$display]: () => MediaBundle | Promise<MediaBundle>;
+    };
+
+    /**
+     * Display function for Jupyter Deno Kernel.
+     * Mimics the behavior of IPython's `display(obj, raw=True)` function to allow
+     * asynchronous displaying of objects in Jupyter.
+     *
+     * @param obj - The object to be displayed
+     * @param options - Display options with a default { raw: true }
+     */
+    export function display(obj: unknown, options?: DisplayOptions): void;
+
+    /**
+     * Show Markdown in Jupyter frontends with a tagged template function.
+     *
+     * Takes a template string and returns a displayable object for Jupyter frontends.
+     *
+     * @example
+     * Create a Markdown view.
+     *
+     * ```typescript
+     * const { md } = Deno.jupyter;
+     * md`# Notebooks in TypeScript via Deno ![Deno logo](https://github.com/denoland.png?size=32)
+     *
+     * * TypeScript ${Deno.version.typescript}
+     * * V8 ${Deno.version.v8}
+     * * Deno ${Deno.version.deno}
+     *
+     * Interactive compute with Jupyter _built into Deno_!
+     * `
+     * ```
+     */
+    export function md(
+      strings: TemplateStringsArray,
+      ...values: unknown[]
+    ): Displayable;
+
+    /**
+     * Show HTML in Jupyter frontends with a tagged template function.
+     *
+     * Takes a template string and returns a displayable object for Jupyter frontends.
+     *
+     * @example
+     * Create an HTML view.
+     * ```typescript
+     * const { html } = Deno.jupyter;
+     * html`<h1>Hello, world!</h1>`
+     * ```
+     */
+    export function html(
+      strings: TemplateStringsArray,
+      ...values: unknown[]
+    ): Displayable;
+
+    /**
+     * SVG Tagged Template Function.
+     *
+     * Takes a template string and returns a displayable object for Jupyter frontends.
+     *
+     * Example usage:
+     *
+     * svg`<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100">
+     *      <circle cx="50" cy="50" r="40" stroke="green" stroke-width="4" fill="yellow" />
+     *    </svg>`
+     */
+    export function svg(
+      strings: TemplateStringsArray,
+      ...values: unknown[]
+    ): Displayable;
+
+    /**
+     * Format an object for displaying in Deno
+     *
+     * @param obj - The object to be displayed
+     * @returns MediaBundle
+     */
+    export function format(obj: unknown): MediaBundle;
+
     /**
      * Broadcast a message on IO pub channel.
      *
-- 
cgit v1.2.3