[RFC] Re-export html helper from WC frameworks

[shilman]

Summary

Re-export Lit’s html template tag from @storybook/web-components to improve adoption among non-Lit WC users, who mistakenly think that Storybook WC is Lit-specific.

Problem Statement

@storybook/web-components uses Lit for custom render functions:

import { html } from 'lit';

export default { component: 'my-component' };
export const WithProp = {
  render: () => html`<my-component prop="value" />`,
};

Thanks to its peer dependency on lit and the import in the story file, there is a preconception that Storybook WC is somehow Lit-specific.

As a result of this misunderstanding, users of other WC frameworks such as FAST often use @storybook/html, and forego benefits of @storybook/web-components like automatic control generation.

Non-goals

Different WC folks have proposed making it possible to to provide custom render function handlers so that users can create their own. This is already possible, but we have not documented it because we don't want to increase the surface area and fragment the space.

Implementation

To solve this problem, we propose re-exporting html from @storybook/web-components renderer and the frameworks @storybook/web-components-vite / @storybook/web-components-webpack5. The lit peer dependency would become a lit-html dependency, and the story import would change as well:

import { html } from '@storybook/web-components-vite'; // or -webpack5

export default { component: 'my-component' };
export const WithProp = {
  render: () => html`<my-component prop="value" />`,
};

NOTE: Render function can also return a plain HTML string as its output.

Prior Art

???

Deliverables

1. Update library. Update the dependency to lit-html and re-export html from the renderer (@storybook/web-components) and frameworks (@storybook/web-components-vite , @storybook/web-components-webpack5).
2. Documentation. Update docs snippets to use the new framework import per above. Also to better emphasize in both the @storybook/html and @storybook/web-components docs that @storybook/web-components is the recommendation for all WC projects.
3. Automigration. This would be backwards compatible with existing code, but better to get existing WC users onto the latest patterns.

Risks

1. Updating the dependency causes hoisting issues in some projects, or is handled worse/differently than a peer dependency.
2. Users are using more stuff from lit in their stories than just html, and we need to add a full lit dependency instead and export more utilities (lit depends on lit-html).

Unresolved Questions

No response

Alternatives considered / Abandoned Ideas

No response

[dgibson666]

like automatic control generation.

Are the advantages and differences documented somewhere? I did not know the web components version could do this and it seems mostly the same as the html version that I used in the past with stencil (per an older tutorial).

[iamallyniam]

I've been using the Document.parseHTMLUnsafe() to return the html, for use with declarative shadow dom.

[radium-v]

Hi, I'm a maintainer of FAST as well as Fluent Web Components where we're using @storybook/html (we also have a few other projects that use @storybook/web-components but our approach is the same).

As a result of this misunderstanding, users of other WC frameworks such as FAST often use @storybook/html, and forego benefits of @storybook/web-components like automatic control generation.

We have a renderComponent helper function that allows us to use FAST Element's html function directly. We don't do this to specifically avoid using Lit, but rather to avoid the confusion of having two html functions in use, each with slightly different ergonomics and return signatures.

I think a bigger issue is that the automatic control generation handled by @storybook/web-components relies on web-components-analyzer, which doesn't support FASTElement components. This is a separate issue, and the way we write fast components has shifted since 2020 when that issue was created (there are multiple ways to define an element with FAST, and last I checked most CEM tools don't completely capture everything yet).

[JamesIves]

Throwing our use case into the ring here. My team uses @storybook/web-components with Lit, instead of using the out of the box control generation we leverage this addon alongside this analyzer, I've documented our process here.

To be fair I've never thought that the web-components exporter purely relied on Lit, but even if I wasn't using Lit I'm not sure that that'd have stopped me if it's used purely as a convenience to render HTML in a story. While I appreciate I can render things directly, using my own framework of choice, writing other framework code within the context of Storybook is not unfamiliar, for example we have to write React components already for Storybook doc blocks.