Table of contents

• Trace component
  • Usage
  • CSS variables
• Contributing
  • Setup
  • Build
  • Dev Server

Trace component

Trace component is a modern webcomponent that visualizes the trace of a program. It is reimplementation of pythontutor. All credits for the original idea go to Philip Guo.

Usage

To use the webcomponent, import the js and simply use the component in your html:

<tc-trace .trace=${trace} .translations="translations"></tc-trace>

This trace is preferably generated by our json tracer. But you can write your own trace generator as long as it follows the format specified in our types. This component should also be compatible with the pythontutor trace format for now, but this might change in the future.

translations is an optional object that can be used to translate the information card shown at the first frame. It should be of type HelpCardTranslations as defined in HelpCard.ts.

You can listen to frame-change events to get the current frame of the trace for example to indicate the current line of code.

You can also add your trace frame by frame using the addFrame method. This method takes a Frame as defined in types.

const traceComponent = document.querySelector('tc-trace');
traceComponent.addFrame({...});

CSS variables

To adjust the look of the trace, you can adjust the css variables defined in the styles file.

Contributing

Setup

Install dependencies:

yarn install

Build

To build the JavaScript version of your component:

yarn build

To watch files and rebuild when the files are modified, run the following command in a separate shell:

yarn build:watch

Dev Server

This project uses modern-web.dev's @web/dev-server for previewing the project without additional build steps. Web Dev Server handles resolving Node-style "bare" import specifiers, which aren't supported in browsers. It also automatically transpiles JavaScript and adds polyfills to support older browsers. See modern-web.dev's Web Dev Server documentation for more information.

To run the dev server and open the project in a new browser tab:

yarn serve

There is a development HTML file located at /dev/index.html that you can view at http://localhost:8000/dev/index.html. Note that this command will serve your code using Lit's development mode (with more verbose errors). To serve your code against Lit's production mode, use yarn serve:prod.