Code.Movie

Animations

Function animateHTML(frames, options)

Turns keyframe objects into a giant string of HTML and CSS that renders the animation. Example usage:

import { animateHTML, defaultTheme } from "@codemovie/code-movie";
import { json } from "@codemovie/code-movie/language/json";

const sceneData = animateHTML(frames, {
  language: json(), // ... or any other language
  tabSize: 2, // required, whole number
  minCols: 5, // optional, defaults to 0
  rootClassSeed: 0, // optional, don't set this unless you know you have to
  theme: defaultTheme, // optional
  debugOverride: false, // optional
  wrapCSS: (id, content) => `.${id}{${content}}`, // optional
});

import { animateHTML, defaultTheme } from "@codemovie/code-movie";
import { json } from "@codemovie/code-movie/language/json";

const sceneData = animateHTML(frames, {
  language: json(), // ... or any other language
  tabSize: 2, // required, whole number
  minCols: 5, // optional, defaults to 0
  rootClassSeed: 0, // optional, don't set this unless you know you have to
  theme: defaultTheme, // optional
  debugOverride: false, // optional
  wrapCSS: (id, content) => `.${id}{${content}}`, // optional
});

Parameter frames

An array of objects conforming to the following TypeScript type:

type InputFrame = {
  code: string;
  ranges?: InputRange[];
  decorations?: InputDecoration[];
};

type InputFrame = {
  code: string;
  ranges?: InputRange[];
  decorations?: InputDecoration[];
};

Each object represents one keyframe in the resulting animation.

• code: String, required. Source code for the current frame
• ranges: Array, optional. Defaults to an empty array. Work in Progress; Ignore this for now.
• decorations: Array, optional. Defaults to an empty array. Contains decorations.

Parameter options

An object conforming to the following TypeScript type:

type InputOptions = {
  language: LanguageDefinition;
  tabSize: number;
  minCols?: number;
  rootClassSeed?: number;
  debugOverride?: boolean;
  theme?: Theme | ThemeWithCondition[];
};

type InputOptions = {
  language: LanguageDefinition;
  tabSize: number;
  minCols?: number;
  rootClassSeed?: number;
  debugOverride?: boolean;
  theme?: Theme | ThemeWithCondition[];
};

The details of the different options are explained below.

Return value

A string of HTML containing the animation, expressed as a <div> and a <style> element.

You can jump between keyframes by switching between the classes frame0, frame1, frameN etc. on the element with the class cm-animation or use the Code.Movie runtime element to get a more high-level API and UI.

Function fromStringsToScene(frames, inputOptions)

Turns keyframe objects into an intermediate SceneData object that contains the animation information. Only useful if you want to read or modify the resulting SceneData object before turning it into HTML and CSS. Example usage:

import { fromStringsToScene, defaultTheme } from "@codemovie/code-movie";
import { json } from "@codemovie/code-movie/language/json";

const sceneData = fromStringsToScene(frames, {
  language: json(), // ... or any other language
  tabSize: 2, // required, whole number
});

import { fromStringsToScene, defaultTheme } from "@codemovie/code-movie";
import { json } from "@codemovie/code-movie/language/json";

const sceneData = fromStringsToScene(frames, {
  language: json(), // ... or any other language
  tabSize: 2, // required, whole number
});

Parameter frames

Same as the fist parameter to animateHTML(frames, options).

Parameter inputOptions

An object conforming to the following TypeScript type:

type InputOptions = {
  language: LanguageDefinition;
  tabSize: number;
  minCols?: number;
};

type InputOptions = {
  language: LanguageDefinition;
  tabSize: number;
  minCols?: number;
};

The details of the different options are explained below.

Return value

A SceneData object. Contains the language definition, animation information and some metadata. Usually passed straight to toAnimationHTML(). The exact object interface may change at any time. Use with caution.

Function toAnimationHTML(sceneData, animationOptions)

Turns an intermediate SceneData object and animation options into a giant string of HTML and CSS that renders the animation. Only useful when you use fromStringsToScene() instead of the more convenient animateHTML(). Example usage:

import { toAnimationHTML, defaultTheme } from "@codemovie/code-movie";

const html = toAnimationHTML(sceneData, {
  rootClassSeed: 0, // optional, don't set this unless you know you have to
  theme: defaultTheme, // optional
  debugOverride: false, // optional
  wrapCSS: (id, content) => `.${id}{${content}}`, // optional
});

import { toAnimationHTML, defaultTheme } from "@codemovie/code-movie";

const html = toAnimationHTML(sceneData, {
  rootClassSeed: 0, // optional, don't set this unless you know you have to
  theme: defaultTheme, // optional
  debugOverride: false, // optional
  wrapCSS: (id, content) => `.${id}{${content}}`, // optional
});

Parameter sceneData

The animation information object generated by fromStringsToScene().

Parameter animationOptions

An object conforming to the following TypeScript type:

type AnimationOptions = {
  rootClassSeed?: number;
  debugOverride?: boolean;
  theme?: Theme | ThemeWithCondition[];
};

type AnimationOptions = {
  rootClassSeed?: number;
  debugOverride?: boolean;
  theme?: Theme | ThemeWithCondition[];
};

The details of the different options are explained below.

Return value

Same as animateHTML(inputFrames, options) (a huge string of HTML and CSS containing the finished animation).

Options

language (required)

The programming language to use for parsing the input. LanguageDefinition objects are obtained by calling one of the functions from one of the language modules. Required.

tabSize (required)

Sets the number of spaces that tab characters should be converted to when computing animations. Required, must be a whole number.

minCols (optional)

Sets the minimum number of columns for the output. Defaults to 0, meaning that the minimum width of the animation entirely depends on the input code.

theme (optional)

Either a theme object or an array of themes with conditions. Themes with conditions conform to the following TypeScript type:

type ThemeWithCondition = {
  theme: Theme;
  condition: string;
};

type ThemeWithCondition = {
  theme: Theme;
  condition: string;
};

Themes with conditions can generate CSS that depends on some CSS condition, like a parent class or a media query. This is useful for supporting dark and light mode. Each can be a selector or the "header" of any relevant block at-rule, such as @media and @supports:

import {
  toAnimationHTML,
  monokaiLight,
  monokaiDark,
} from "@codemovie/code-movie";

// Example: use dark or light theme dependent on a media query
const html1 = toAnimationHTML(sceneData, {
  theme: [
    { theme: monokaiLight, condition: "@media (prefers-color-scheme: light)" },
    { theme: monokaiDark, condition: "@media (prefers-color-scheme: dark)" },
  ],
});

// Example: use dark or light theme dependent on a parent class
const html2 = toAnimationHTML(sceneData, {
  theme: [
    { theme: monokaiLight, condition: ":root.isLight" },
    { theme: monokaiDark, condition: ":root.isDark" },
  ],
});

import {
  toAnimationHTML,
  monokaiLight,
  monokaiDark,
} from "@codemovie/code-movie";

// Example: use dark or light theme dependent on a media query
const html1 = toAnimationHTML(sceneData, {
  theme: [
    { theme: monokaiLight, condition: "@media (prefers-color-scheme: light)" },
    { theme: monokaiDark, condition: "@media (prefers-color-scheme: dark)" },
  ],
});

// Example: use dark or light theme dependent on a parent class
const html2 = toAnimationHTML(sceneData, {
  theme: [
    { theme: monokaiLight, condition: ":root.isLight" },
    { theme: monokaiDark, condition: ":root.isDark" },
  ],
});

To pass a theme that is not subject to any conditions, set condition to the empty string.

The theme option is optional and defaults to the default theme (without conditions).

rootClassSeed (optional)

A seed value used to generate a unique ID for the animation, which is used to namespace the CSS so that multiple animations can co-exist on one web page. This is optional and defaults to an automatically-incrementing number starting from a random value. If you need the animation IDs to be deterministic, you can set this value to some reasonably unique-ish whole number, like an automatically incrementing ID or Date.now().

debugOverride (optional)

When true, turns off class name minification/obfuscation and spams the console with debug information. Optional, defaults to false.

wrapCSS (optional)

Function that defines how the CSS that the animation generates should be wrapped in order to provide a useful amount of style isolation. It takes the animation's ID and the CSS content and returns a string of valid CSS. Its default implementation uses the animation ID as a scoping CSS class:

const defaultWrapCSS: (id: string, content: string) => string = (
  id: string,
  content: string,
) => `.${id}{${content}}`;

const defaultWrapCSS: (id: string, content: string) => string = (
  id: string,
  content: string,
) => `.${id}{${content}}`;

To buff CSS isolation provide a custom function that, for example uses the animation's id as an actual ID, thereby increasing the nested rule's selector specificity.