Add ability to show and execute code, but avoid story wrapper UI

[bashmish]

Use case

Often I need to show the setup code to the users, because it's important for the demos underneath.
This setup code doesn't contain demos, just some JS or CSS which needs to be executed, without any direct visuals, so I want to avoid rendering it in a story wrapper.

I also reason about this in the following manner:

• execute code
  • show demo
    • show code (js preview-story)
    • do not show code (js story)
  • do not show demo
    • show code (this feature request)
    • do not show code (js script)
• do not execute code
  • show demo
    • show code (makes no sense)
    • do not show code (makes no sense)
  • do not show demo
    • show code (js, just standard Markdown)
    • do not show code (makes no sense)

Examples

1. Show and execute setup JS code, e.g. how to register custom elements in preparation for the demos below with code.

   Live: https://backlight.dev/edit/xS11aQmjMLIvr5PU5Mru/flipper/doc/flipper.md?p=doc
   I have to duplicate the setup code in js script and in the js code block.

2. Show and render setup CSS code, e.g. classes which I then use in the demos underneath, so users need to read this CSS code first to understand the follow-up demos code.

   Live: https://backlight.dev/edit/4BeMe20hqOWTkdUL2NuJ/box/doc/box.md?branch=feature-request-show-setup-code%4044v7XI9EE5hzBwU7oxi8dbGjKz03&p=doc
   I use a workaround here not to duplicate the code, but I had to add a paragraph to invite to read it, although I want to just show the code block immediately without this fancy wrapper around it and not hide it behind a button-click.

Proposals

All proposal are also applicable to html code blocks, but I'm using js smth for readability.

1. js preview-script
   Given js preview-story differs from js story in the fact that it does show the code.
   We can make js preview-script to differ from js script in the same way.
   Important remark: such block can return smth to render (not really a story though) or can just be some JS to execute.

Pros:

• In our project we use the semantics of MDJS stories to automatically show them in the storybook, which makes me like this proposal, because it doesn't mark this setup code as a story which is semantically correct.

Cons:

• html preview-script reads weird, because it's not really a script 🤷
• js script is not designed for rendering, while this feature assumes rendering is needed (not always, but if the store is returned), just without extra UI wrapper

Example 1 with this proposal:

js preview-script

import { provideDesignSystem, getFlipper } from '@divriots/starter-furious';

provideDesignSystem().register(getFlipper());

Example 2 with this proposal:

html preview-script

<style>
  .boxStory {
    width: 8rem;
    height: 8rem;
    box-shadow: 0 25px 50px -12px rgba(0, 0, 0, 0.25);
  }
</style>

2. js story no-ui, js story no-ui no-render

Not a big fan of this, but just sharing for completeness.
The idea is to control if the story UI wrapper is shown and if the code needs to be rendered in the DOM.

Cons:

• this makes it semantically a story always, which is not true
• we need sometimes to just execute the code without rendering, which js story is not designed for

3. Rename js script to js setup, add new js preview-setup for executable JS blocks and js/html preview-render-setup for rendered blocks

This combines best of previous two and takes into account their limitations.
js script can be left for backwards compatibility, but I think it's good to rename it given it's kinda the same thing semantically.
But you can also argue it's unrelated, and that makes it just a few new ones.

Example 1 with this proposal:

js preview-setup

import { provideDesignSystem, getFlipper } from '@divriots/starter-furious';

provideDesignSystem().register(getFlipper());

Example 2 with this proposal (given version with both js and html for clarity)

js preview-render-setup

export const setupStyles = () => `
  <style>
    .boxStory {
      width: 8rem;
      height: 8rem;
      box-shadow: 0 25px 50px -12px rgba(0, 0, 0, 0.25);
    }
  </style>
`;

html preview-render-setup

<style>
  .boxStory {
    width: 8rem;
    height: 8rem;
    box-shadow: 0 25px 50px -12px rgba(0, 0, 0, 0.25);
  }
</style>

Glad to discuss other proposals, certainly there is space for better API ideas.

[daKmoR]

to clarify your goal is to write something that executes the code AND displays it as a "standard" markdown code block...

e.g.

```js [some-id]
const foo = 'bar';
```

should result in something like this (simplified)

<script type="module">
  const foo = 'bar';
</script>

<code><pre>
   const foo = 'bar';
</pre></code>

[daKmoR]

how about render-code or render+code 🤔

```html render-code
<style>
  .boxStory {
    width: 8rem;
    height: 8rem;
    box-shadow: 0 25px 50px -12px rgba(0, 0, 0, 0.25);
  }
</style>
```

the full list would be

• render (currently story)
  • render/execute the code here
  • will only bevisible if the code returns something visible
• render-code
  • render/execute the code here
  • put the code snippet here
• render-frame (currently preview-story)
  • render/execute the code here
  • put the code snippet here
  • wrap it within a frame

[bashmish]

render-smth makes it confusing to me, because I imagine rendering smth different, while in each case I think we render the story, so the second word shouldn't be different

but I like the direction where it's going, maybe it just needs to be a configuration rather than a unique name?
e.g. story with-frame with-code where with-frame wraps it in a frame, with-code displays the code

another related idea: I was thinking about the possibility to control the initial code dropdown state open/closed for the preview-story code, so could be another configuration, e.g. open-code (with closed remaining the default)

but isn't it all a bit too much of a major change? or are you considering now releasing a new major?

[daKmoR]

yeah I need to do a new major at some point anyways as unified/remark moved to esm only with v10... so updating to the lastest version would be a breaking change anyways...

we can include something in the current release via some different methodology...

but ultimately in the next major, it needs to have some "config"... as besides story/render/inject or however it will be called I also need the destination between server and client execution...

e.g. it becomes quite a lot 😅

here is a worst-case scenario 🙈

```js server story with-frame with-code opened

maybe it needs some sort of syntax (using inject in this example for lack of a better word... but could be render, story, execute, ...)

```js client
console.log('just execute');
```

```js server inject
export const foo = () => html`<p>render the p</p>`;
```

```js client inject({ withCode: true })
export const bar = () => html`<p>render the p AND the highlighted code block</p>`;
```

```js client inject-frame({ openCode: true })
export const baz = () => html`<p>render the p AND the highlighted code block OPENED within a FRAME</p>`;
```

[bashmish]

is there an issue where you collect all use case and requests to support? I can contribute my use-cases there instead of having another thread here?

[daKmoR]

it sort of outlined here
#315