Preview

You can showcase live running code by annotating a code block with js preview-story.

Features

Shows components inside the page as they are
You can enable “Simulation Mode” to break them out
Simulation mode renders in an iframe to supporting media queries and isolated Simulation settings
Simulation Settings
- Style (windows, mac, android, iOS)
- Size (small, medium, large, Galaxy S5, iPhone X, iPad …)
- Automatic Height
- Theme (light, dark)
- Language (en, nl, …)
Settings are ”global” for all Simulators (e.g. changing one will change all)
Settings can be remembered for other pages / return visits

JavaScript Story

```js client
import { html } from '@mdjs/mdjs-preview';
import './assets/demo-element.js';
```

```js preview-story
export const foo = () => html``;
```

will result in

export const foo = () => html` <demo-element></demo-element> `;

// not defined for android

// not defined for ios

Story Code

If your preview is followed by a code blocks marked as story-code then those will be shown when switching between multiple platforms

```js preview-story
// will be visible when platform web is selected
export const JsPreviewStory = () => html`  `;
```

```xml story-code


```

```swift story-code
// will be visible when platform ios is selected
import Demo.Element

let card = DemoElement()
```

See it in action by opening up the code block and switching platforms

// will be visible when platform web is selected
export const JsPreviewStory = () => html` <demo-element></demo-element> `;

<!-- will be visible when platform android is selected -->
<Button
    android:id="@+id/demoElement"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:text="Android Code"
    style="@style/Widget.Demo.Element"
/>

// will be visible when platform ios is selected
import Demo.Element

let card = DemoElement()

HTML Story

```html preview-story

```

will result in

<demo-element></demo-element>

Setup Simulation Mode

For simulation mode we need a dedicated html file that will be used as an iframe target while loading stories.

The fastest way to create such a file is to use the layout-simulator layout.

Create a file docs/simulator.md with the following content.

---
layout: layout-simulator
eleventyExcludeFromCollections: true
excludeFromSearch: true
---

Once you have that you need to configure it for the story renderer by setting it in your config/rocket.config.js.

/** @type {import('rocket/cli').RocketCliConfig} */
export default ({
  setupUnifiedPlugins: [
    adjustPluginOptions('mdjsSetupCode', {
      simulationSettings: { simulatorUrl: '/simulator/' },
    }),
  ],
});

You can freely choose the path for the "simulator" by creating the md file in a different folder and adjusting the path in the config.

Simulator states

To simulate these stats that usually come from the device itself we put those infos on the document tag.

We can simulate the following settings

platform Adopting styles and behavior depending on which device platform you are.

<html platform="web"></html>
<html platform="android"></html>
<html platform="ios"></html>
<!-- potentially later -->
<html platform="web-windows"></html>
<html platform="web-mac"></html>

theme Adjust your styles based on a theme - light/dark are the default but you can add as many as you want.
```
<html theme="light"></html>
<html theme="dark"></html>
```
language Best to relay on data-lang as lang often gets changes by translations services which may interfere with your translation loading system.
```
<html lang="en-US" data-lang="en-US"></html>
<html lang="de-DE" data-lang="de-DE"></html>
```

If you want to react to such document changes you can use an MutationObserver.

For a vanilla web component it could look something like this:

class DemoElement extends HTMLElement {
  constructor() {
    super();
    this.attachShadow({ mode: 'open' });

    this.platform = 'the web';
    this.language = 'en-US';
    this.theme = 'light';

    this.observer = new MutationObserver(this.updateData);
  }

  updateData = () => {
    this.platform = document.documentElement.getAttribute('platform') || 'the web';
    this.language = document.documentElement.getAttribute('data-lang') || 'en-US';
    this.theme = document.documentElement.getAttribute('theme') || 'light';
    this.requestUpdate();
  };

  connectedCallback() {
    this.updateData();

    this.observer.observe(document.documentElement, { attributes: true });
  }

  requestUpdate() {
    this.shadowRoot.innerHTML = this.render();
  }

  render() {
    return `
      ...
    `;
  }
}

customElements.define('demo-element', DemoElement);

Extending mdjs-preview

It is possible to define a custom version of mdjs-preview in order to add functionality, change its appearance of make it run in 'hybrid mode' (accepting both lit1 and -2 TemplateResults). The example below shows how the latter can be achieved by providing a custom render function. Note that we define mdjs-preview as the custom element name. We need to make sure that this file is executed before the original mdjs-preview definition file is executed.

import { MdJsPreview } from '@mdjs/mdjs-preview';
import { render as render2 } from 'lit';
import { isTemplateResult as isTemplateResult2 } from 'lit/directive-helpers.js';
import { render as render1  } from 'lit-html';

export class HybridLitMdjsPreview extends MdJsPreview {
  renderStory(html, container, options) {
    if (isTemplateResult2(html)) {
      render2(html, container, options);
    } else {
      render1(html, container, options);
    }
  }
customElements.define('mdjs-preview', HybridLitMdjsPreview);

Caught a mistake or want to contribute to the documentation? Edit this page on GitHub!