JARLE

Write code and see the result as you type.

Overview

<h3>Hello World!</h3>

<h3>Hello World!</h3>

JARLE only looks at the last thing you return, so write whatever you need in front of it.

const DEFAULT = 'World'; function Greet({ subject = DEFAULT }) { return <div>Hello {subject}</div>; } class ClassyGreet extends React.Component { render() { const { subject } = this.props; return <em>Hello {subject}</em>; } } <> <Greet /> <Greet subject="Planet" /> <ClassyGreet subject="Universe" /> </>;

const DEFAULT = 'World';
function Greet({ subject = DEFAULT }) {
  return <div>Hello {subject}</div>;
}
class ClassyGreet extends React.Component {
  render() {
    const { subject } = this.props;
    return <em>Hello {subject}</em>;
  }
}
<>
  <Greet />
  <Greet subject="Planet" />
  <ClassyGreet subject="Universe" />
</>;

If the last expression is a valid React element type it'll render that as well:

const DEFAULT = 'World'; function Greet() { return <div>Hello world</div>; }

const DEFAULT = 'World';
function Greet() {
  return <div>Hello world</div>;
}

Or with class components

class ClassyGreet extends React.Component { render() { return <em>Hello world</em>; } }

class ClassyGreet extends React.Component {
  render() {
    return <em>Hello world</em>;
  }
}

If you want to be explicit you can also export a value directly (only the default export is used).

export default React.forwardRef(() => { return <strong>I'm unique!</strong>; });

export default React.forwardRef(() => {
  return <strong>I'm unique!</strong>;
});

For punchy terse demostrations of component render logic, use renderAsComponent to have JARLE use your code as the body of a React function component.

const [seconds, setSeconds] = useState(0); useEffect(() => { let interval = setInterval(() => { setSeconds((prev) => prev + 1); }, 1000); return () => clearInterval(interval); }, []); return <div>Seconds past: {seconds}</div>;

const [seconds, setSeconds] = useState(0);
useEffect(() => {
  let interval = setInterval(() => {
    setSeconds((prev) => prev + 1);
  }, 1000);
  return () => clearInterval(interval);
}, []);
return <div>Seconds past: {seconds}</div>;

If you do need more control over what get's rendered, or need to render asynchronously, a render function is always in scope:

setTimeout(() => { render(<div>I'm late!</div>); }, 1000);

setTimeout(() => {
  render(<div>I'm late!</div>);
}, 1000);

Scope

You can control which values, clases, components, etc are provided automatically to the example code when it's run by adjusting the scope. The scope is an object map of identifiers and their values. The React namespace is provided as well as all of the built-in hooks (useState, useRef, etc) automatically along with a render() function for finely tuning the returned element.

You can also add our own values:

import lodash from 'lodash';

<Provider scope={{ _: lodash }} />;

Importing modules in examples

Import can be used in code blocks (as long as the browser supports dynamic imports).

import confetti from 'https://cdn.skypack.dev/canvas-confetti'; <button onClick={() => confetti()}>Confetti</button>;

import confetti from 'https://cdn.skypack.dev/canvas-confetti';
<button onClick={() => confetti()}>Confetti</button>;

Import statements are extracted from the example code and the requests are passed to a function responsible for resolving them into modules.

The default behavior uses import(), relying on the browsers module support. You can however, customize the importer to suit your needs. The resolver may return an object map of possible requests to their module, useful when you only want to expose a few local values to examples (see also scope).

<Provider

resolveImports={() => ({

lodash: lodash,

'my-component': { default: () => <strong>Hey</strong> },

})}

/>

For dynamic resolution the resolve is also passed a list of requests to be mapped to their modules. Here is the default implementation

<Provider

resolveImports={(requests) =>

promise.all(requests.map((request) => import(request)))

}

/>

You can also mix together some of your own static analysis and tooling to build really neat integrations where imports are resolved a head of time, using webpack or other bundlers.

Usage

A full example of how to use JARLE via another JARLE editor!

import theme from 'https://cdn.skypack.dev/prism-react-renderer/themes/oceanicNext'; const { Provider, Editor, Error, Preview } = Jarle; const code = ` <strong>Here's an editor inside an editor</strong> `; <div> <h4 align="center">Yo Dawg I heard you liked editors</h4> <Provider code={code} theme={theme} language="jsx"> <Editor style={{ padding: 20 }} infoSrOnly /> <Preview style={{ padding: 20, textAlign: 'center' }} /> <Error /> </Provider> </div>;

import theme from 'https://cdn.skypack.dev/prism-react-renderer/themes/oceanicNext';
const { Provider, Editor, Error, Preview } = Jarle;
const code = `
  <strong>Here's an editor inside an editor</strong>
`;
<div>
  <h4 align="center">Yo Dawg I heard you liked editors</h4>
  <Provider code={code} theme={theme} language="jsx">
    <Editor style={{ padding: 20 }} infoSrOnly />
    <Preview style={{ padding: 20, textAlign: 'center' }} />
    <Error />
  </Provider>
</div>;

Render into an iframe

Previews are all rendered into the same document as the editor so they share stuff like global CSS. If want to sandbox the result from the parent document, render your preview into an <iframe> useing a "portal".

const { Provider, Editor, Error, Preview } = Jarle; function IFrameEditor(props) { const [contentRef, setContentRef] = useState(null); const mountNode = contentRef && contentRef.contentWindow.document.body; return ( <Provider {...props}> <Editor style={{ padding: 20 }} infoSrOnly /> <iframe ref={setContentRef} style={{ width: '100%' }} /> {mountNode && ReactDOM.createPortal( <Preview style={{ padding: 20, textAlign: 'center' }} />, mountNode )} <Error /> </Provider> ); } const code = ` <strong>Here's an editor inside an editor inside an iframe</strong> `; <IFrameEditor code={code} theme={theme} language="jsx" />;

const { Provider, Editor, Error, Preview } = Jarle;
function IFrameEditor(props) {
  const [contentRef, setContentRef] = useState(null);
  const mountNode = contentRef && contentRef.contentWindow.document.body;
  return (
    <Provider {...props}>
      <Editor style={{ padding: 20 }} infoSrOnly />
      <iframe ref={setContentRef} style={{ width: '100%' }} />
      {mountNode &&
        ReactDOM.createPortal(
          <Preview style={{ padding: 20, textAlign: 'center' }} />,
          mountNode
        )}
      <Error />
    </Provider>
  );
}
const code = `
  <strong>Here's an editor inside an editor inside an iframe</strong>
`;
<IFrameEditor code={code} theme={theme} language="jsx" />;

Syntax Highlighting

Like React Live, JARLE uses Prism via prism-react-renderer for syntax highlighting. To get up and running quickly JARLE also reexports all the packages themes from prism-react-renderer, under jarle/themes so you don't have to explicitly add prism-react-renderer to your package.json.

To use a theme import and pass it to the Provider:

import theme from 'jarle/themes/oceanicNext';

<Provider

theme={theme}

...

/>

You can also use normal Prism themes by leaving off the theme prop and adding the appropriate class and global CSS.

Line Numbers

Add the lineNumbers prop to the Editor to show line numbers. They can be styled with CSS targeting the line-number class or add a lineNumber key to your prism theme.

1

2

3

4

5

6

7

const DEFAULT = 'World'; function Greet({ subject = DEFAULT }) { return <div>Hello {subject}</div>; } <Greet />;

const DEFAULT = 'World';
function Greet({ subject = DEFAULT }) {
  return <div>Hello {subject}</div>;
}
<Greet />;

Accessiblity

Rich text editors like JARLE tend to break an important aspect of keyboard navigation on the web. Namely they break tab behavior by indenting instead of moving focus to the next item on the page. This really helpful for text editing but can trap keyboard users in the editor.

To address this JARLE doesn't automatically trap focus when the user tabs into the editor. Pressing enter or typing printable characters activates the tap trap, so the hitting tab indents instead of moving focus. Hitting esc disables tab trapping allowing a user to tab away from the editor.

This behavior is communicated to users via Info text (which should also be read out to a Screen Reader). The visual message is enabled by default because not all keyboard users are screen reader users. If you want to make the messages "screen ready only", pass infoSrOnly to the Editor.

API

<Provider>

The Provider supplies the context to the other components as well as handling jsx transpilation and import resolution.

children

Render subcomponents

type: ReactNode

coderequired

A string of code to render

type: string

language

A Prism language string for selecting a grammar for syntax highlighting

type: string

renderAsComponent

Creates a react component using the code text as it's body. This allows using top level hooks in your example without having to create and return your own component. Cannot be used with render() in the example.

import Button from './Button'

const [active, setActive] = useState()

<Button active={active} onClick={() => setActive(true)}/>

type: boolean

default:false

resolveImports

A function that maps an array of import requests to modules, may return a promise.

const resolveImports = (requests) =>

Promise.all(requests.map(req => import(req)))

Or an object hash of import requests to the result

const resolveImports = () => ({

'./foo': Foo

})

type: (requests: string[]) => Promise<Record<string, any>any[]>

default:function defaultResolveImports(sources) { return Promise.all(sources.map((s) => import(/* webpackIgnore: true */ s))); }

scope

A context object of values automatically available for use in editor code

type: TScope

showImports

Whether the import statements in the initial code text are shown to the user or not.

type: boolean

default:true

theme

A Prism theme object, leave empty to not use a theme or use a traditional CSS theme.

type: PrismTheme

<Editor>

The Editor is the code text editor component, some props can be supplied directly or take from the Provider context if available.

className

type: string

infoComponent

The component used to render A11y messages about keyboard navigation, override to customize the styling

type: ReactComponentType<any>

default:<InfoMessage>

infoSrOnly

Styles the info component so that it is not visible but still accessible by screen readers.

type: boolean

default:false

lineNumbers

Render line numbers

type: boolean

style

type: any

theme

A Prism theme object, can also be specified on the Provider

type: PrismTheme

<Preview>

The component that renders the user's code.

className

type: string

holderTheme

An optional holder.js theme

type: any

<Error>

Displays an sytax or runtime error that occured when rendering the code