Extensions API

[okonet]

We might want to take a look at https://github.com/camwest/react-slot-fill for allowing extensions for SG.

[sapegin]

We were talking about Storybook like plugins that would add tabs under examples. But this also can be useful.

[okonet]

Yeah, I actually don't like how storybook does it since it's very restrictive. This one should theoretically allow writing custom visualizers for the components and create custom controlled components (like knobs?). We should try it out and see if it works well for us.

[sapegin]

I think for knobs Storybook-style is quite good and enough. Why do you think it won’t work well?

[okonet]

My concern is more UI-wise: storybook only allow you to extend by creating tabs around the content there we are interested in creating extension inside of the content.

[sapegin]

Could you make some mockup of your ideas? That would really help ;-)

[okonet]

I could when I get some more time :(

[sapegin]

Have watched a ReactConf talk about it and this is amazing! But looks like it only works with Fiber. Not sure they will / can support React 15.

[sapegin]

What do we want to extend by the way?

1. Tabs under the component playground (Storybook like) seems useful: non-editable code, snapshots, knobs…
2. Access to style guide config.

What else?

[MicheleBertoli]

+1 for tabs, it seems a great starting point to me.

[cef62]

I agree with @okonet, I would love have both possibilities:

• add isolated features/plugins in tabs (around content)
• extend/augment rendered content (inside content)

While working on snapguidist I had some idea on that. Now that I've closed a very important deadline at work I can finally work on it. Next days I will share more about this with you!

[sapegin]

@cef62 Ping ;-) Do you have some time now?

[cef62]

I've started digging through the new 5.x implementation. I really like the new AST based parsing, great job @sapegin!
At the moment the part bugging me the most is that there's no effective way to assign a unique ID to every parsed snippet. This is something very important to support a plugin API in my opinion, in snapguidist for example we could use it to avoid unnecessary execution of unchanged snippets.

At the moment the most viable solution I can think of, but I'm not fond of it, is to support a sort of front matter where the user can expose data to the plugins and configure them.

What I think could be a interesting way to expose a plugin API is to wrap the RSG component, we want expose as customizable parts, with an HoC connected to styleguidist configuration and access the registered plugin. Every plugin register itself and the final user control the registering order. That approach would allow a single plugin to customize any required aspect of the UI.

I want to share a more complete idea as soon as possible. Next two weeks I'll be participating to Jsconfit and Codemotion Amsterdam, then I'll be finally able to give my full attention to the plugin API and snapguidist.

Meanwhile what do you think of the idea of using HoCs to connect plugins to styleguidist? And, do you have any better idea on how to assign a unique ID to every snippet of code?

[sapegin]

I think unique ID generation should be part of the core but I don’t know how to do expect use just indexes like Jest does itself.

About HOCs: sounds like a good idea, do you know how we could easily implement that? I also think that we should start from predefined extension points (toolbars and tabs) like I describe in #426 — it should be easier to implement and would be enough for many plugins, for Snapguidist as well if I’m not missing something ;-)

[cef62]

I think unique ID generation should be part of the core but I don’t know how to do expect use just indexes like Jest does itself

Jest use the assertion title as unique ID but we don't have it. This is why I'm thinking of a front matter approach. That approach would also open up snippet-level configuration of plugins.

About HOCs: sounds like a good idea, do you know how we could easily implement that?

I've a couple of ideas and it's what I hope to share in more detail asap.

I also think that we should start from predefined extension points (toolbars and tabs) like I describe in #426

I definitely agree with you!

[sapegin]

Front matter is a nice idea but I’m afraid we can’t require users to write it for each example just to be able to use Snapguidist. We could use the text in a paragraph in front of the example. It’s not perfect but probably better than indexes.

[cef62]

but I’m afraid we can’t require users to write it for each example

Yep, this is my exact feeling about it. But could/should be optional. I mean the plugin author could support an explicit title/ID/whatever to support specific features, if the user doen't care about those features (like test execution optimization) can simply skip the front matter.

We could use the text in a paragraph in front of the example.

That is a nice idea to avoid unnecessary repetitions on every snippet.

[sapegin]

So, yeah, we could generate these IDs in the core and pass them to your plugin’s tab component or whatever ;-)

[cef62]

So, yeah, we could generate these IDs in the core and pass them to your plugin’s tab component or whatever ;-)

Yes and no. We can just recognize snippet positional index and their content. If the user change the snippet order and the content we don't have any way to be sure of which snippet whas assigned to which ID.

[sapegin]

If we use text than most likely the text will be moved with the snippet and we don’t have a better idea anyway ;-)

[MicheleBertoli]

We can't assume there's always going to be a text above the snippet, right?

Jest is using a combination of name + index, and we are doing the same at the moment.
I can't see why we can't keep on doing it.

Afaik we don't have evidence of any performance issue, therefore I wouldn't worry about it.

Thanks @sapegin @cef62.

[cef62]

We can't assume there's always going to be a text above the snippet, right?

No we can't

Afaik we don't have evidence of any performance issue, therefore I wouldn't worry about it.

I was thinking not only about snapguidist but also to possibly more heavy integration that could benefit from more optimization.

Anyway I agree with you that is not fundamental, but a nice addition to have anyway.

[sapegin]

To start working on the API something very simple: adding buttons to component toolbar. What do you like more 1 or 2?

// styleguide.config.js
module.exports = {
	// ...
	plugins: [
		require('styleguidist-plugin-foo')({ some: 'options' })
	]
}

// Plugin that adds a button to each component toolbar
import React from 'react';
import ToolbarButton from 'react-styleguidist/lib/rsg-components/ToolbarButton');
import MdScreenShare from 'react-icons/lib/md/screen-share');
export default /* plugin options */ options => /* style guide config */ config => {
	return {
		// Buttons that should be added to a component toolbar
		// 1.
		getComponentToolbarButtons({ name, urlAnchor, urlIsolated, urlNoChrome }) {
			return [
				<ToolbarButton to={`http://sizzy.co/?url=${encodeURIComponent(urlNoChrome)}`} title="Open in Sizzy" blank><MdScreenShare /></ToolbarButton>
			];
		},
		// 2.
		toolbarButtons: [
			({ name, urlAnchor, urlIsolated, urlNoChrome }) =>
				<ToolbarButton to={`http://sizzy.co/?url=${encodeURIComponent(urlNoChrome)}`} title="Open in Sizzy" blank><MdScreenShare /></ToolbarButton>
		];
	};
};

[okonet]

IMO always go with functions since it's much more flexible in a long-term.

[sapegin]

@okonet Both are functions. The difference is only in an array placement: inside the function or outside. I like the second one more because it‘s just a component.

[cef62]

I also like the 2nd variant.
If I understand correctly any plugin it will produce an object containing several configuration hooks (toolbarButtons is the only one at the moment). react-styleguidist will chain all configurations from all registered plugins in the given order. Is that right? I like the approach!

[sapegin]

@cef62 Yeah, that’s the idea for simple things like toolbar buttons. And after that we can think what else we need.

[cef62]

I agree! Do you have a working branch or is just an idea? I'd love to help on this ;)
I'm finally done with conferences for a little while and I'll finally be able to contribute to snapguidist and styleguidist.

[sapegin]

@cef62 There’s the ui branch, right now I’m working on a component / section toolbar. I hope I could finish it on the weekend and commit. So far there’s not much to see ;-)

[cef62]

Ok thanks! I'll look at it and I'll see how I can contribute to move toward the API you proposed!

[sapegin]

@cef62 I think I need to implement the first version of the API with only component toolbar extension and then you could help with things we’ll need for Snapguidist.

[stepancar]

i like 1st variant

[sapegin]

@stepancar Any particular reason why?

[stepancar]

@sapegin, because in function we can implement any logic to select which buttons should be plased to example. For example, we want to add theme switcher button for several components which support theme switching using context.

[sapegin]

@stepancar In the second you could return null ;-) Maybe you have some other ideas?

[sapegin]

What if we make it more explicit like this?

// Plugin that adds a button to each component toolbar
import React from 'react';
import ToolbarButton from 'react-styleguidist/lib/rsg-components/ToolbarButton');
import MdScreenShare from 'react-icons/lib/md/screen-share');
export default /* plugin options */ options => /* style guide config */ config => {
	return {
		// Similar: onSection, onExample, etc.
		onComponent({ addToolbarButton }, { name, urlAnchor, urlIsolated, urlNoChrome }) {
		   addToolbarButton(
			<ToolbarButton to={`http://sizzy.co/?url=${encodeURIComponent(urlNoChrome)}`} title="Open in Sizzy" blank><MdScreenShare /></ToolbarButton>
			);
		},
	};
};

[okonet]

@sapegin I like this ↑

How will it be defined there the extension is happening? Is this pre-defiend by RSG?

[sapegin]

I’ve created a PR with some experiments: #505.

[mehrad77]

Is there any update on this feature?