livecodes
Version:
A Code Playground That Just Works!
992 lines • 74.6 kB
TypeScript
declare module 'livecodes' {
/**
* LiveCodes SDK - A Code Playground That Just Works!
*
* This module is the main entry point for the LiveCodes SDK.
* It provides the core `createPlayground` and `getPlaygroundUrl` functions.
*
* @module livecodes
*/
import type { Code, Config, EmbedOptions, Language, Playground } from 'livecodes/models';
export type { Code, Config, EmbedOptions, Language, Playground };
/**
* Creates a LiveCodes playground.
*
* @param {string | HTMLElement} container - `HTMLElement` or a string representing a CSS selector. This is the container where the playground is rendered.
If not found, an error is thrown (except in [headless mode](https://livecodes.io/docs/sdk/headless), in which this parameter is optional and can be omitted).
* @param {EmbedOptions} options - The [embed options](https://livecodes.io/docs/sdk/js-ts#embed-options) for the playground (optional).
* @return {Promise<Playground>} A promise that resolves to a [`Playground`](https://livecodes.io/docs/api/interfaces/Playground/) object which exposes many [SDK methods](https://livecodes.io/docs/sdk/js-ts/#sdk-methods) that can be used to interact with the playground.
*/
export function createPlayground(container: string | HTMLElement, options?: EmbedOptions): Promise<Playground>;
export function createPlayground(options: EmbedOptions & {
view: 'headless';
}): Promise<Playground>;
/**
* Gets the URL to a LiveCodes playground (as a string) from the provided [options](https://livecodes.io/docs/sdk/js-ts#embed-options).
* This can be useful for providing links to run code in playgrounds.
*
* @param {EmbedOptions} options - The [options](https://livecodes.io/docs/sdk/js-ts#embed-options) for the playground.
* @return {string} The URL of the playground (as a string).
*
* large objects like config and params are store in the url hash params while the rest are in the search params
* unless config is a string in which case it is stored in searchParams
*/
export function getPlaygroundUrl(options?: EmbedOptions): string;
/**
* A utility function that allows compressing the stringified config object (e.g. for sharing in URL hash)
* It encodes it in base64 with a few tweaks to make it URI safe.
*
* This is the `compressToEncodedURIComponent` function re-exported from `lz-string` for convenience.
*
* @param {string} uncompressed - The string to be compressed (e.g. stringified config object)
* @return {string} The compressed string
*
* @example
* ```ts
* const compressed = compress(JSON.stringify(config));
* ```
*/
export const compress: (uncompressed: string) => string;
/**
* A utility function that allows decompressing the config object (compressed by {@link compress}).
* It decodes it to a string that should be JSON.parsed.
*
* This is the `decompressFromEncodedURIComponent` function re-exported from `lz-string` for convenience.
*
* @param {string} compressed - The string to be decompressed
* @return {string | null} The decompressed string or `null` if it fails
*
* @example
* ```ts
* const decompressed = decompress(str);
* if (decompressed) {
* try {
* const config = JSON.parse(decompressed);
* } catch {
*
* }
* }
* ```
*/
export const decompress: (compressed: string) => string | null;
}
declare module 'livecodes/models' {
/**
* Converts a union type to an intersection type.
* @typeParam U - The union type to convert
*/
export type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
/**
* Makes nested object types more readable by flattening intersecting types.
* @typeParam T - The type to prettify
*/
export type Prettify<T> = {
[K in keyof T]: T[K] extends object ? Prettify<T[K]> : T[K];
} & {};
/**
* Language name, alias or extension.
*/
export type Language = 'html' | 'htm' | 'markdown' | 'md' | 'mdown' | 'mkdn' | 'mdx' | 'astro' | 'pug' | 'jade' | 'haml' | 'asciidoc' | 'adoc' | 'asc' | 'mustache' | 'handlebars' | 'hbs' | 'ejs' | 'eta' | 'nunjucks' | 'njk' | 'liquid' | 'liquidjs' | 'dot' | 'twig' | 'vento' | 'vto' | 'art-template' | 'art' | 'jinja' | 'bbcode' | 'bb' | 'mjml' | 'diagrams' | 'diagram' | 'graph' | 'plt' | 'richtext' | 'rte' | 'rich' | 'rte.html' | 'css' | 'scss' | 'sass' | 'less' | 'stylus' | 'styl' | 'stylis' | 'postcss' | 'javascript' | 'js' | 'mjs' | 'json' | 'babel' | 'es' | 'sucrase' | 'typescript' | 'flow' | 'ts' | 'mts' | 'jsx' | 'tsx' | 'react' | 'react-jsx' | 'react.jsx' | 'react-tsx' | 'react.tsx' | 'react-native' | 'react-native.jsx' | 'react-native-tsx' | 'react-native.tsx' | 'vue' | 'vue3' | 'vue2' | 'vue-app' | 'app.vue' | 'svelte' | 'svelte-app' | 'app.svelte' | 'stencil' | 'stencil.tsx' | 'solid' | 'solid.jsx' | 'solid.tsx' | 'riot' | 'riotjs' | 'malina' | 'malinajs' | 'ripple' | 'ripplejs' | 'xht' | 'coffeescript' | 'coffee' | 'livescript' | 'ls' | 'civet' | 'clio' | 'imba' | 'assemblyscript' | 'as' | 'python' | 'py' | 'pyodide' | 'python-wasm' | 'py-wasm' | 'pythonwasm' | 'pywasm' | 'py3' | 'wasm.py' | 'r' | 'rlang' | 'rstats' | 'r-wasm' | 'ruby' | 'rb' | 'ruby-wasm' | 'wasm.rb' | 'rubywasm' | 'go' | 'golang' | 'go-wasm' | 'wasm.go' | 'gowasm' | 'php' | 'php-wasm' | 'phpwasm' | 'wasm.php' | 'cpp' | 'c' | 'C' | 'cp' | 'cxx' | 'c++' | 'cppm' | 'ixx' | 'ii' | 'hpp' | 'h' | 'cpp-wasm' | 'cppwasm' | 'cwasm' | 'wasm.cpp' | 'clang' | 'clang.cpp' | 'java' | 'csharp' | 'csharp-wasm' | 'cs' | 'cs-wasm' | 'wasm.cs' | 'perl' | 'pl' | 'pm' | 'lua' | 'lua-wasm' | 'luawasm' | 'wasm.lua' | 'teal' | 'tl' | 'fennel' | 'fnl' | 'julia' | 'jl' | 'scheme' | 'scm' | 'commonlisp' | 'common-lisp' | 'lisp' | 'clojurescript' | 'clojure' | 'cljs' | 'clj' | 'cljc' | 'edn' | 'gleam' | 'swift' | 'rescript' | 'res' | 'resi' | 'reason' | 're' | 'rei' | 'ocaml' | 'ml' | 'mli' | 'tcl' | 'wat' | 'wast' | 'webassembly' | 'wasm' | 'Binary' | 'sql' | 'sqlite' | 'sqlite3' | 'pg.sql' | 'pgsql.sql' | 'pgsql' | 'pg' | 'pglite' | 'pglite.sql' | 'postgresql' | 'postgres' | 'postgre.sql' | 'postgresql.sql' | 'prolog.pl' | 'prolog' | 'minizinc' | 'mzn' | 'dzn' | 'blockly' | 'blockly.xml' | 'xml' | 'pintora';
/**
* The identifier for each code editor pane in the playground.
*/
export type EditorId = 'markup' | 'style' | 'script';
/**
* Represents a position in a code editor,
* with 1-based line number and (optional) 1-based column number.
*/
export interface EditorPosition {
/** 1-based line number */
lineNumber: number;
/** 1-based column number (optional) */
column?: number;
}
/**
* The app theme mode.
*/
export type Theme = 'light' | 'dark';
/**
* CSS preprocessors and PostCSS plugins.
*/
export type Processor = 'postcss' | 'postcssImportUrl' | 'tailwindcss' | 'windicss' | 'unocss' | 'tokencss' | 'lightningcss' | 'autoprefixer' | 'postcssPresetEnv' | 'cssmodules' | 'purgecss' | 'cssnano';
/**
* CSS presets.
*/
export type CssPresetId = '' | 'normalize.css' | 'reset-css';
/**
* CDN providers for external resources.
*/
export type CDN = 'jspm' | 'skypack' | 'jsdelivr' | 'fastly.jsdelivr' | 'gcore.jsdelivr' | 'testingcf.jsdelivr' | 'jsdelivr.b-cdn' | 'jsdelivr.gh' | 'fastly.jsdelivr.gh' | 'gcore.jsdelivr.gh' | 'testingcf.jsdelivr.gh' | 'jsdelivr.b-cdn.gh' | 'jsdelivr.esm' | 'fastly.jsdelivr.esm' | 'gcore.jsdelivr.esm' | 'testingcf.jsdelivr.esm' | 'jsdelivr.b-cdn.esm' | 'esm.run' | 'esm.sh' | 'esbuild' | 'bundle.run' | 'unpkg' | 'npmcdn' | 'statically';
/**
* Supported UI/app languages for localization.
*/
export type AppLanguage = 'auto' | 'ar' | 'bn' | 'de' | 'en' | 'es' | 'fa' | 'fr' | 'hi' | 'id' | 'it' | 'ja' | 'nl' | 'pt' | 'tr' | 'ru' | 'ur' | 'zh-CN';
/**
* Starter template names.
*/
export type TemplateName = 'blank' | 'javascript' | 'typescript' | 'react' | 'react-native' | 'vue2' | 'vue' | 'angular' | 'preact' | 'svelte' | 'solid' | 'lit' | 'stencil' | 'mdx' | 'astro' | 'riot' | 'malina' | 'jquery' | 'backbone' | 'knockout' | 'jest' | 'jest-react' | 'bootstrap' | 'tailwindcss' | 'shadcn-ui' | 'daisyui' | 'd3' | 'phaser' | 'coffeescript' | 'livescript' | 'civet' | 'clio' | 'imba' | 'rescript' | 'reason' | 'ocaml' | 'python' | 'python-wasm' | 'r' | 'ruby' | 'ruby-wasm' | 'go' | 'go-wasm' | 'php' | 'php-wasm' | 'cpp' | 'cpp-wasm' | 'java' | 'csharp-wasm' | 'perl' | 'lua' | 'lua-wasm' | 'teal' | 'fennel' | 'julia' | 'scheme' | 'commonlisp' | 'clojurescript' | 'gleam' | 'tcl' | 'markdown' | 'assemblyscript' | 'wat' | 'sql' | 'postgresql' | 'prolog' | 'minizinc' | 'blockly' | 'diagrams';
/**
* Tools in the tools pane.
*/
export type ToolName = 'console' | 'compiled' | 'tests';
/**
* Status of the tools pane.
*/
export type ToolsPaneStatus = 'closed' | 'open' | 'full' | 'none' | '';
/**
* API commands for the SDK.
*/
export type APICommands = 'setBroadcastToken' | 'showVersion';
/**
* Screen names in the app.
*/
export type ScreenName = 'login' | 'info' | 'new' | 'open' | 'assets' | 'add-asset' | 'snippets' | 'add-snippet' | 'import' | 'resources' | 'share' | 'embed' | 'deploy' | 'sync' | 'backup' | 'broadcast' | 'welcome' | 'about' | 'custom-settings' | 'editor-settings' | 'code-to-image' | 'test-editor' | 'keyboard-shortcuts';
/**
* Themes for the Monaco editor.
*/
export type MonacoTheme = 'active4d' | 'all-hallows-eve' | 'amy' | 'birds-of-paradise' | 'blackboard' | 'brilliance-black' | 'brilliance-dull' | 'catppuccin-latte' | 'catppuccin-frappe' | 'catppuccin-macchiato' | 'catppuccin-mocha' | 'chrome-devtools' | 'clouds-midnight' | 'clouds' | 'cobalt' | 'cobalt2' | 'custom-vs-light' | 'custom-vs-dark' | 'dawn' | 'dracula' | 'dreamweaver' | 'eiffel' | 'espresso-libre' | 'github' | 'github-dark' | 'github-light' | 'hc-black' | 'hc-light' | 'idle' | 'idlefingers' | 'iplastic' | 'katzenmilch' | 'krtheme' | 'kuroir' | 'lazy' | 'magicwb-amiga' | 'merbivore-soft' | 'merbivore' | 'monochrome' | 'monochrome-dark' | 'monokai' | 'monokai-bright' | 'monoindustrial' | 'night-owl' | 'nord' | 'oceanic-next' | 'pastels-on-dark' | 'slush-and-poppies' | 'solarized-dark' | 'solarized-light' | 'spacecadet' | 'sunburst' | 'textmate-mac-classic' | 'tomorrow' | 'tomorrow-night' | 'tomorrow-night-blue' | 'tomorrow-night-bright' | 'tomorrow-night-eighties' | 'twilight' | 'upstream-sunburst' | 'vibrant-ink' | 'vs' | 'vs-dark' | 'xcode-default' | 'zenburnesque';
/**
* Themes for the CodeMirror editor.
*/
export type CodemirrorTheme = 'amy' | 'aura' | 'ayu-light' | 'barf' | 'basic-light' | 'basic-dark' | 'bespin' | 'birds-of-paradise' | 'boys-and-girls' | 'catppuccin-latte' | 'catppuccin-frappe' | 'catppuccin-macchiato' | 'catppuccin-mocha' | 'clouds' | 'cm-light' | 'cobalt' | 'cool-glow' | 'dracula' | 'espresso' | 'github-dark' | 'github-light' | 'gruvbox-dark' | 'gruvbox-light' | 'material-dark' | 'material-light' | 'monochrome' | 'monochrome-dark' | 'noctis-lilac' | 'nord' | 'one-dark' | 'rose-pine-dawn' | 'smoothy' | 'solarized-light' | 'solarized-dark' | 'tokyo-night' | 'tokyo-night-day' | 'tokyo-night-storm' | 'tomorrow';
/**
* Themes for the CodeJar editor.
*/
export type CodejarTheme = 'a11y-dark' | 'atom-dark' | 'base16-ateliersulphurpool-light' | 'catppuccin-latte' | 'catppuccin-frappe' | 'catppuccin-macchiato' | 'catppuccin-mocha' | 'cb' | 'coldark-cold' | 'coldark-dark' | 'coy' | 'coy-without-shadows' | 'darcula' | 'dark' | 'dracula' | 'duotone-dark' | 'duotone-earth' | 'duotone-forest' | 'duotone-light' | 'duotone-sea' | 'duotone-space' | 'funky' | 'ghcolors' | 'gruvbox-dark' | 'gruvbox-light' | 'holi-theme' | 'hopscotch' | 'laserwave' | 'lucario' | 'material-dark' | 'material-light' | 'material-oceanic' | 'monochrome' | 'monochrome-dark' | 'night-owl' | 'nord' | 'nord-2' | 'okaidia' | 'one-dark' | 'one-light' | 'pojoaque' | 'shades-of-purple' | 'solarized-dark-atom' | 'solarized-light' | 'synthwave84' | 'tomorrow' | 'twilight' | 'vs' | 'vsc-dark-plus' | 'xonokai' | 'z-touchs';
/**
* Editor theme that can be a Monaco, CodeMirror, or CodeJar theme,
* optionally with editor prefix and/or a theme suffix (light/dark).
* See [docs](https://livecodes.io/docs/configuration/configuration-object#editortheme) for details.
*/
export type EditorTheme = MonacoTheme | CodemirrorTheme | CodejarTheme | `${MonacoTheme}@${Theme}` | `${CodemirrorTheme}@${Theme}` | `${CodejarTheme}@${Theme}` | `monaco:${MonacoTheme}` | `codemirror:${CodemirrorTheme}` | `codejar:${CodejarTheme}` | `monaco:${MonacoTheme}@${Theme}` | `codemirror:${CodemirrorTheme}@${Theme}` | `codejar:${CodejarTheme}@${Theme}`;
/**
* Represents the result of a single test.
*/
export interface TestResult {
/** Time taken to run the test in milliseconds. */
duration: number;
/** Array of error messages if the test failed. */
errors: string[];
/** The status of the test. */
status: 'pass' | 'fail' | 'skip';
/** The path to the test in the test suite. */
testPath: string[];
}
/**
* Custom type declarations for module imports.
*/
export interface Types {
/** The module name and its type declaration URL */
[key: string]: string | {
url: string;
declareAsModule?: boolean;
declareAsGlobal?: boolean;
autoload?: boolean;
};
}
/**
* Configuration for each code editor pane in the playground.
*/
export interface Editor {
/**
* A language name, extension or alias (as defined in [language documentations](https://livecodes.io/docs/languages/)).
*
* For the list of supported values, see [Language](https://livecodes.io/docs/api/type-aliases/Language)
*/
language: Language;
/**
* The initial content of the code editor.
* @default ""
*/
content?: string;
/**
* A URL to load `content` from. It has to be a valid URL that is CORS-enabled.
*
* The URL is only fetched if `content` property had no value.
*/
contentUrl?: string;
/**
* Hidden content that gets evaluated without being visible in the code editor.
*
* This can be useful in embedded playgrounds (e.g. for adding helper functions, utilities or tests)
*/
hiddenContent?: string;
/**
* A URL to load `hiddenContent` from. It has to be a valid URL that is CORS-enabled.
*
* The URL is only fetched if `hiddenContent` property had no value.
*/
hiddenContentUrl?: string;
/**
* Lines that get folded when the editor loads.
*
* This can be used for less relevant content.
* @example [{ from: 5, to: 8 }, { from: 15, to: 20 }]
*/
foldedLines?: Array<{
from: number;
to: number;
}>;
/**
* If set, this is used as the title of the editor in the UI,
* overriding the default title set to the language name
* (e.g. `"Python"` can be used instead of `"Py (Wasm)"`).
*/
title?: string;
/**
* If `true`, the title of the code editor is hidden, however its code is still evaluated.
*
* This can be useful in embedded playgrounds (e.g. for hiding unnecessary code).
*/
hideTitle?: boolean;
/**
* The order of the editor in the UI.
* @default 0
*/
order?: number;
/**
* A CSS selector to load content from [DOM import](https://livecodes.io/docs/features/import#import-code-from-dom).
*/
selector?: string;
/**
* The initial position of the cursor in the code editor.
* @example {lineNumber: 5, column: 10}
*/
position?: EditorPosition;
}
/**
* Custom settings for the playground.
*/
export type CustomSettings = Partial<{
[key in Language | Processor]: any;
} & {
template: {
data?: any;
prerender?: boolean;
};
scriptType: 'module' | 'application/javascript' | 'application/ecmascript' | 'text/javascript' | 'text/ecmascript' | '' | 'text/liquid' | 'text/python' | 'text/r' | 'text/ruby-wasm' | 'text/x-uniter-php' | 'text/php-wasm' | 'text/cpp' | 'text/java' | 'text/csharp-wasm' | 'text/perl' | 'text/julia' | 'text/biwascheme' | 'text/commonlisp' | 'text/tcl' | 'text/prolog' | 'text/minizinc' | 'text/go-wasm' | 'application/json' | 'application/lua' | 'text/fennel' | 'application/wasm-uint8';
mapImports: boolean;
imports: Record<string, string>;
convertCommonjs: boolean;
defaultCDN: CDN;
types: Types;
}>;
/**
* Configuration for code formatting options.
*/
export interface FormatterConfig {
/**
* If `true`, lines are indented with tabs instead of spaces.
* @default false
*/
useTabs: boolean;
/**
* The number of spaces per indentation-level.
* @default 2
*/
tabSize: number;
/**
* Configures Prettier [code formatter](https://livecodes.io/docs/features/code-format) to use semi-colons.
* @default true
*/
semicolons: boolean;
/**
* Configures Prettier [code formatter](https://livecodes.io/docs/features/code-format) to use single quotes instead of double quotes.
* @default false
*/
singleQuote: boolean;
/**
* Configures Prettier [code formatter](https://livecodes.io/docs/features/code-format) to use [trailing commas](https://prettier.io/docs/en/options.html#trailing-commas).
* @default true
*/
trailingComma: boolean;
}
/**
* Configuration for code editor settings.
*/
export interface EditorConfig {
/**
* Selects the [code editor](https://livecodes.io/docs/features/editor-settings#code-editor) to use.
*
* If `undefined` (the default), Monaco editor is used on desktop,
* CodeMirror is used on mobile and in `simple` mode,
* while CodeJar is used in `codeblock` mode, in `lite` mode and in `readonly` playgrounds.
*
* If set to `auto`, Monaco editor is used on desktop and CodeMirror is used on mobile regardless of other settings.
*
* @default undefined
*/
editor: 'monaco' | 'codemirror' | 'codejar' | 'auto' | undefined;
/**
* Sets the app [theme](https://livecodes.io/docs/features/themes) to light/dark mode.
* @default "dark"
*/
theme: Theme;
/**
* Sets the app theme color.
* If `undefined`, it is set to `"hsl(214, 40%, 50%)"`.
* @default undefined
*/
themeColor: string | undefined;
/**
* Sets the [code editor](https://livecodes.io/docs/features/editor-settings) themes.
*
* See docs for [editor themes](https://livecodes.io/docs/configuration/configuration-object#editortheme) for details.
*
* @example "vs"
* @example "monaco:twilight, codemirror:one-dark"
* @example ["vs@light"]
* @example ["vs@light", "vs-dark@dark"]
* @example ["monaco:vs@light", "codemirror:github-light@light", "dracula@dark"]
*/
editorTheme: EditorTheme[] | string | undefined;
/**
* Sets the [code editor](https://livecodes.io/docs/features/editor-settings) font family.
*/
fontFamily: string | undefined;
/**
* Sets the font size.
*
* If `undefined` (the default), the font size is set to 14 for the full app and 12 for [embeds](https://livecodes.io/docs/features/embeds).
* @default undefined
*/
fontSize: number | undefined;
/**
* If `true`, lines are indented with tabs instead of spaces.
*
* Also used in [code formatting](https://livecodes.io/docs/features/code-format).
* @default false
*/
useTabs: boolean;
/**
* The number of spaces per indentation-level.
*
* Also used in [code formatting](https://livecodes.io/docs/features/code-format).
* @default 2
*/
tabSize: number;
/**
* Show line numbers in [code editor](https://livecodes.io/docs/features/editor-settings).
* @default true
*/
lineNumbers: boolean | 'relative';
/**
* Enables word-wrap for long lines.
* @default false
*/
wordWrap: boolean;
/**
* When set to `true`, regions marked by `#region` and `#endregion` comments are folded when the project is loaded.
* @default false
*/
foldRegions: boolean;
/**
* Use auto-complete to close brackets and quotes.
* @default true
*/
closeBrackets: boolean;
/**
* Enables minimap in code editor.
* @default false
*/
minimap: boolean;
/**
* Enables [Emmet](https://livecodes.io/docs/features/editor-settings#emmet).
* @default true
*/
emmet: boolean;
/**
* Sets [editor mode](https://livecodes.io/docs/features/editor-settings#editor-modes).
*/
editorMode: 'vim' | 'emacs' | undefined;
}
/**
* User preferences and settings for the playground.
*/
export interface UserConfig extends EditorConfig, FormatterConfig {
/**
* If `true`, the result page is automatically updated on code change,
* after time [delay](https://livecodes.io/docs/configuration/configuration-object#delay).
* @default true
*/
autoupdate: boolean;
/**
* If `true`, the project is automatically saved on code change,
* after time [delay](https://livecodes.io/docs/configuration/configuration-object#delay).
* @default false
*/
autosave: boolean;
/**
* If `true`, the project is watched for code changes which trigger tests to auto-run.
* @default false
*/
autotest: boolean;
/**
* Time delay (in milliseconds) following code change,
* after which the result page is updated (if [`autoupdate`](https://livecodes.io/docs/configuration/configuration-object#autoupdate) is `true`)
* and/or the project is saved (if [`autosave`](https://livecodes.io/docs/configuration/configuration-object#autosave) is `true`).
* @default 1500
*/
delay: number;
/**
* If `true`, the code is automatically [formatted](https://livecodes.io/docs/features/code-format) on saving the project.
* @default false
*/
formatOnsave: boolean;
/**
* Sets the app layout to horizontal or vertical.
* If set to `"responsive"` (the default) or `undefined`,
* the layout is vertical in small screens when the playground height is larger than its width,
* otherwise horizontal.
* @default "responsive"
*/
layout: 'responsive' | 'horizontal' | 'vertical' | undefined;
/**
* Enables [recovering last unsaved project](https://livecodes.io/docs/features/recover) when the app is reopened.
* @default true
*/
recoverUnsaved: boolean;
/**
* Enables [showing element spacing](https://livecodes.io/docs/features/result#show-spacings) in the result page.
* @default false
*/
showSpacing: boolean;
/**
* If `true`, the [welcome screen](https://livecodes.io/docs/features/welcome) is displayed when the app loads.
*/
welcome: boolean;
/**
* Sets the app UI language used.
*/
appLanguage: AppLanguage | undefined;
}
/**
* These are properties that define how the app behaves.
*/
export interface AppConfig {
/**
* If `true`, editors are loaded in read-only mode, where the user is not allowed to change the code.
*
* By default, when readonly is set to true, the light-weight code editor [CodeJar](https://livecodes.io/docs/features/editor-settings#code-editor) is used.
* If you wish to use another editor, set the [editor](https://livecodes.io/docs/configuration/configuration-object#editor) property.
* @default false
*/
readonly: boolean;
/**
* If `false`, the UI will not show the menu that allows changing editor language.
* @default true
*/
allowLangChange: boolean;
/**
* Sets the [default view](https://livecodes.io/docs/features/default-view) for the playground.
* @default "split"
*/
view?: 'split' | 'editor' | 'result';
/**
* Sets the [display mode](https://livecodes.io/docs/features/display-modes).
* @default "full"
*/
mode: 'full' | 'focus' | 'lite' | 'simple' | 'editor' | 'codeblock' | 'result';
/**
* Sets enabled and active tools and status of [tools pane](https://livecodes.io/docs/features/tools-pane).
* @default { enabled: "all", active: "", status: "" }
* @example
* ```js
* {
* "tools": {
* "enabled": ["console", "compiled"],
* "active": "console",
* "status": "open"
* }
* }
* ```
*/
tools: Partial<{
enabled: ToolName[] | 'all';
active: ToolName | '';
status: ToolsPaneStatus;
}>;
/**
* Sets result page [zoom level](https://livecodes.io/docs/features/result#result-page-zoom).
*/
zoom: 1 | 0.5 | 0.25;
}
/**
* The properties that define the content of the current [project](https://livecodes.io/docs/features/projects).
*/
export interface ContentConfig {
/**
* Project title.
* This is used as [result page](https://livecodes.io/docs/features/result) title and title meta tag.
* Also used in project search.
* @default "Untitled Project"
*/
title: string;
/**
* Project description. Used in [project](https://livecodes.io/docs/features/projects) search
* and [result page](https://livecodes.io/docs/features/result) description meta tag.
* @default ""
*/
description: string;
/**
* Content added to the [result page](https://livecodes.io/docs/features/result) `<head>` element.
* @default '<meta charset="UTF-8" />\n<meta name="viewport" content="width=device-width, initial-scale=1.0" />'
*/
head: string;
/**
* Attributes added to the [result page](https://livecodes.io/docs/features/result) `<html>` element.
* It can be an object or a string.
* @example <caption>Both of these become `<html lang="en" class="dark">`</caption>
* { lang: "en", class: "dark" }
* 'lang="en" class="dark"'
*/
htmlAttrs: Record<string, string> | string;
/**
* Project tags.
* Used in [project](https://livecodes.io/docs/features/projects) filter and search.
* @default []
*/
tags: string[];
/**
* Selects the active editor to show.
*
* Defaults to the last used editor for user, otherwise `"markup"`
* @type {`"markup"` | `"style"` | `"script"` | `undefined`}
*/
activeEditor: EditorId | undefined;
/**
* List of enabled languages.
*
* Defaults to all supported languages in full app and only current editor languages in [embeds](https://livecodes.io/docs/features/embeds).
*/
languages: Array<Language | Processor> | undefined;
/**
* An object that configures the language and content of the markup editor.
*
* See [docs](https://livecodes.io/docs/configuration/configuration-object/#markup) for details.
* @default { language: "html", content: "" }
*/
markup: Prettify<Editor>;
/**
* An object that configures the language and content of the style editor.
*
* See [docs](https://livecodes.io/docs/configuration/configuration-object/#markup) for details.
* @default { language: "css", content: "" }
*/
style: Prettify<Editor>;
/**
* An object that configures the language and content of the script editor.
*
* See [docs](https://livecodes.io/docs/configuration/configuration-object/#markup) for details.
* @default { language: "javascript", content: "" }
*/
script: Prettify<Editor>;
/**
* List of URLs for [external stylesheets](https://livecodes.io/docs/features/external-resources) to add to the [result page](https://livecodes.io/docs/features/result).
*/
stylesheets: string[];
/**
* List of URLs for [external scripts](https://livecodes.io/docs/features/external-resources) to add to the [result page](https://livecodes.io/docs/features/result).
*/
scripts: string[];
/**
* [CSS Preset](https://livecodes.io/docs/features/external-resources#css-presets) to use.
* @type {"" | "normalize.css" | "reset-css"}
*/
cssPreset: CssPresetId;
/**
* List of enabled [CSS processors](https://livecodes.io/docs/features/css/#css-processors).
*
* For the list of available processors, see [Processor](https://livecodes.io/docs/api/internal/type-aliases/Processor)
*/
processors: Processor[];
/**
* Defines [custom settings](https://livecodes.io/docs/advanced/custom-settings) for the current project.
*/
customSettings: Prettify<CustomSettings>;
/**
* Allows specifying custom [import maps](https://github.com/WICG/import-maps) for [module imports](https://livecodes.io/docs/features/module-resolution#custom-module-resolution).
*
* **Example**
*
* Setting `imports` like this:
* ```js
* "imports": {
* "moment": "https://cdn.jsdelivr.net/npm/moment@2.29.4/dist/moment.js"
* }
* ```
* results in the following import map:
* ```html
* <script type="importmap">
* {
* "imports": {
* "moment": "https://cdn.jsdelivr.net/npm/moment@2.29.4/dist/moment.js"
* }
* }
* </script>
* ```
* See docs for [Imports](https://livecodes.io/docs/configuration/configuration-object#imports)
* and [Custom Module Resolution](https://livecodes.io/docs/features/module-resolution/#custom-module-resolution)
*/
imports: {
[key: string]: string;
};
/**
* Allows providing custom TypeScript type declarations for better [editor intellisense](https://livecodes.io/docs/features/intellisense).
*
* It is an object where each key represents module name and value represents the types.
*
* See docs for [Types](https://livecodes.io/docs/configuration/configuration-object#types)
* and [Custom Types](https://livecodes.io/docs/features/intellisense#custom-types)
*
* @example
* ```js
* {
* "types": {
* "my-demo-lib": "https://my-custom-domain/my-type-declarations.d.ts"
* }
* }
* ```
* @example
* ```
* {
* "types": {
* "my-demo-lib": {
* "url": "https://my-custom-domain/types.d.ts",
* "autoload": true,
* "declareAsModule": true
* }
* }
* ```
*/
types: Prettify<Types>;
/**
* Configures the [language](https://livecodes.io/docs/features/tests#supported-languages)
* and content of [tests](https://livecodes.io/docs/features/tests).
*/
tests: Prettify<Partial<Editor>> | undefined;
/**
* This is a read-only property which specifies the current LiveCodes version.
*
* Version specified in [exported](https://livecodes.io/docs/features/export) projects allows automatically upgrading the project configuration when imported by an app with a newer version.
*/
readonly version: string;
}
/**
* The playground configuration interface combining content, app, and user settings.
*/
export interface Config extends ContentConfig, AppConfig, UserConfig {
}
/**
* An object that contains the language, content and compiled code for each of the 3 [code editors](https://livecodes.io/docs/features/projects)
* and the [result page](https://livecodes.io/docs/features/result) HTML.
*
* See [docs](https://livecodes.io/docs/api/interfaces/Code) for details.
*/
export interface Code {
/** Markup editor code. */
markup: {
/** The language of the code. */
language: Language;
/** The source code. */
content: string;
/** The compiled code. */
compiled: string;
};
/** Style editor code. */
style: {
/** The language of the code. */
language: Language;
/** The source code. */
content: string;
/** The compiled code. */
compiled: string;
};
/** Script editor code. */
script: {
/** The language of the code. */
language: Language;
/** The source code. */
content: string;
/** The compiled code. */
compiled: string;
};
/** The HTML content of the result page. */
result: string;
}
/**
* Union of all watch function types for playground events.
*/
export type WatchFns = WatchLoad | WatchReady | WatchCode | WatchConsole | WatchTests | WatchDestroy;
/**
* Called when the playground first loads.
*/
export type WatchLoad = (event: 'load', fn: () => void) => {
remove: () => void;
};
/**
* Called when a new project is loaded (including when [imported](https://livecodes.io/docs/features/import)) and the playground is ready to run.
*/
export type WatchReady = (event: 'ready', fn: (data: {
config: Config;
}) => void) => {
remove: () => void;
};
/**
* Watch function type for code changes in the playground.
*/
export type WatchCode = (event: 'code', fn: (data: {
code: Code;
config: Config;
}) => void) => {
remove: () => void;
};
/**
* Called when console methods are called in the result page.
*/
export type WatchConsole = (event: 'console', fn: (data: {
method: string;
args: any[];
}) => void) => {
remove: () => void;
};
/**
* Called when test results are available.
*/
export type WatchTests = (event: 'tests', fn: (data: {
results: TestResult[];
error?: string;
}) => void) => {
remove: () => void;
};
/**
* Called when the playground is destroyed.
*/
export type WatchDestroy = (event: 'destroy', fn: () => void) => {
remove: () => void;
};
/**
* The event name type for SDK watch functions.
*/
export type SDKEvent = Parameters<WatchFns>[0];
/**
* The event handler type for SDK watch functions.
*/
export type SDKEventHandler = Parameters<WatchFns>[1];
/**
* The combined watch function type that handles all events.
*/
export type WatchFn = UnionToIntersection<WatchFns>;
/**
* The SDK API interface for playground interaction.
*/
export interface API {
/**
* Runs the [result page](https://livecodes.io/docs/features/result) (after any required compilation for code).
* @example
* ```ts
* import { createPlayground } from "livecodes";
*
* createPlayground("#container").then(async (playground) => {
* await playground.run();
*
* });
* ```
*/
run: () => Promise<void>;
/**
* Formats the code.
*
* By default, the code in all editors (markup, style and script) is formatted.
* To format only the active editor, the value `false` should be passed as an argument.
* @example
* ```ts
* import { createPlayground } from "livecodes";
*
* createPlayground("#container").then(async (playground) => {
* await playground.format();
*
* });
* ```
*/
format: (allEditors?: boolean) => Promise<void>;
/**
* Gets a [share url](https://livecodes.io/docs/features/share) for the current project.
*
* By default, the url has a long query string representing the compressed encoded config object.
* If the argument `shortUrl` was set to `true`, a short url is generated.
* @example
* ```ts
* import { createPlayground } from "livecodes";
*
* createPlayground("#container").then(async (playground) => {
* const longUrl = await playground.getShareUrl();
* const shortUrl = await playground.getShareUrl(true);
* });
* ```
*/
getShareUrl: (shortUrl?: boolean) => Promise<string>;
/**
* Gets a [configuration object](https://livecodes.io/docs/configuration/configuration-object) representing the playground state.
*
* This can be used to restore state if passed as an [EmbedOptions](https://livecodes.io/docs/sdk/js-ts#embed-options) property when [creating playgrounds](https://livecodes.io/docs/sdk/js-ts/#createplayground),
* or can be manipulated and loaded in run-time using [`setConfig`](https://livecodes.io/docs/sdk/js-ts#setconfig) method.
* @example
* ```ts
* import { createPlayground } from "livecodes";
*
* createPlayground("#container").then(async (playground) => {
* const config = await playground.getConfig();
* });
* ```
*/
getConfig: (contentOnly?: boolean) => Promise<Config>;
/**
* Loads a new project using the passed configuration object.
* If the config is a string, it is assumed to be a URL to a JSON file that contains the configuration object.
*
* @throws It throws an error if the config object (or URL) is invalid.
*
* @example
* ```ts
* import { createPlayground } from "livecodes";
*
* createPlayground("#container").then(async (playground) => {
* const config = {
* markup: {
* language: "html",
* content: "Hello World!",
* },
* };
* const newConfig = await playground.setConfig(config);
*
* });
* ```
*/
setConfig: (config: Partial<Config> | string) => Promise<Config>;
/**
* Gets the playground code (including source code, source language and compiled code) for each editor (markup, style, script), in addition to result page HTML.
*
* See [Code](https://livecodes.io/docs/api/interfaces/Code) for the structure of the returned object.
* @example
* ```ts
* import { createPlayground } from "livecodes";
*
* createPlayground("#container").then(async (playground) => {
* const code = await playground.getCode();
*
*
* const { content, language, compiled } = code.script;
*
*
* const result = code.result;
* });
* ```
*/
getCode: () => Promise<Code>;
/**
* Shows the selected panel.
*
* See [docs](https://livecodes.io/docs/sdk/js-ts#show) for details.
* @example
* await playground.show("style");
* await playground.show("toggle-result");
* await playground.show("result", { full: true });
* await playground.show("script");
* await playground.show("result", { zoom: 0.5 });
* await playground.show("console", { full: true });
*/
show: (panel: EditorId | 'editor' | 'result' | 'toggle-result' | ToolName, options?: {
full?: boolean;
line?: number;
column?: number;
zoom?: Config['zoom'];
}) => Promise<void>;
/**
* Runs project [tests](https://livecodes.io/docs/features/tests) (if present) and gets test results.
* @example
* ```ts
* import { createPlayground } from "livecodes";
*
* createPlayground("#container").then(async (playground) => {
* const { results } = await playground.runTests();
* });
* ```
*/
runTests: () => Promise<{
results: TestResult[];
}>;
/**
* Runs a callback function when code changes.
*
* @deprecated Use [`watch`](https://livecodes.io/docs/sdk/js-ts#watch) method instead.
*/
onChange: (fn: (data: {
code: Code;
config: Config;
}) => void) => {
remove: () => void;
};
/**
* Allows to watch for various playground events.
* It takes 2 arguments: event name and a callback function that will be called on every event.
*
* event name can be one of: `"load" | "ready" | "code" | "console" | "tests" | "destroy"`
*
* In some events, the callback function will be called with an object that supplies relevant data to the callback function (e.g. code, console output, test results).
*
* The watch method returns an object with a single method (`remove`), which when called will remove the callback from watching further events.
*
* See [docs](https://livecodes.io/docs/sdk/js-ts#watch) for details.
* @example
* ```ts
* import { createPlayground } from "livecodes";
*
* createPlayground("#container").then((playground) => {
* const codeWatcher = playground.watch("code", ({ code, config }) => {
*
* console.log("code:", code);
* console.log("config:", config);
* });
*
* const consoleWatcher = playground.watch("console", ({ method, args }) => {
*
* console[method](...args);
* });
*
* const testsWatcher = playground.watch("tests", ({ results }) => {
*
* results.forEach((testResult) => {
* console.log("status:", testResult.status);
* console.log(testResult.errors);
* });
* });
*
*
* codeWatcher.remove();
* consoleWatcher.remove();
* testsWatcher.remove();
*
* });
* ```
*/
watch: WatchFn;
/**
* Executes custom commands, including: `"setBroadcastToken"` and `"showVersion"`.
*
* See [docs](https://livecodes.io/docs/sdk/js-ts#exec) for details.
*/
exec: (command: APICommands, ...args: any[]) => Promise<{
output: any;
} | {
error: string;
}>;
/**
* Destroys the playground instance, and removes event listeners.
*
* Further call to any SDK methods throws an error.
* @example
* ```ts
* import { createPlayground } from "livecodes";
*
* createPlayground("#container").