Added initial Angular content

[alterx]

This PR accompanies chromaui/learnstorybook-code#4 and addreses #2

What's inside:

• English version

What's missing:

• Spanish version
• Update commit SHAs for all the pages after that PR gets merged
• Proofread the whole thing (I could use some help with this one 😄)
• 🚀

[domyen]

I proofread the English version. There are a few minor copy changes but it all looks great! 👍

[domyen]

Typo: Double "in" here

[domyen]

Change to "a list of TaskComponents"

[domyen]

iimport --> import

[domyen]

Task --> TaskComponent

[domyen]

"...dispatch and action" ---> "...dispatch an action"

[domyen]

/react ---> /angular

[domyen]

Can you add link to the Angular English and Spanish editions in these locations:

• components/Header.js
• pages/index.js

[icarlossz]

I can help with the spanish translation.

[alterx]

@icarlossz, well, I've already started with that one. As soon as I get a first draft I'll submit it and you can proofread it. Does that work? 😄

[icarlossz]

@alterx It sounds great to me!

[alterx]

@icarlossz I've added the Spanish version
@domyen I've addressed your change requests (and a couple more I found)

[domyen]

This one should remain .css. The user is not actually running less, rather they're including the pre-compiled .css file included in the repo.

[alterx]

Well, I changed that in both the code and in the tutorial. I've configured the cli to use LESS. It didn't really make sense to use gulp and compile less when the @angular/cli + webpack can allow use of .less files.

You can see the commit here: chromaui/learnstorybook-code@c15b751

[domyen]

sgtm thanks for the explanation 👍

[icarlossz]

Reviewed, the spanish translation is good.

[tmeasday]

This is so great! Can't wait to get it out!!

Two things:

1. We can add syntax highlighting for typescript and json by changing Highlight.js to include loadLanguages(['bash', 'typescript', 'json']);. Looks nice!

2. I wonder why you decided not to do the PureTaskList and demonstrate the pattern of splitting the presentational part of a container out for its stories?

Is this difficult to do in angular? I feel like it is a useful trick, and without it the data chapter feels a bit weird, like there is no lesson in it, it is just setting up the next chapter.

[tmeasday]

Can we remove -o .storybook-static -- I just made this change to master

[alterx]

Hey @tmeasday, regarding the PureTaskList thing, I'm not really sure it makes sense for Angular. Let me try to rationalize it:

In React, when we use connect we compose a new higher order component that will provide the "selected" data to the underlying "presentational" component. Both components exist on their own and connect just enhances what the presentational component can do.

In Angular, in order to create a "connected" component we just inject the store and then we can select the data inside. It felt a bit unnecessary to add that part since we already have a presentational component (TaskList) and we'll build a "container" (InboxScreenComponent). So, if I had included that PureTaskList the TaskList would've basically been the same thing as the InboxScreenComponent and we weren't going to be able to just import "the presentational part" of the component.

In other words, there's no similar way to have the PureTaskList and TaskList in the same file and connect one while leaving the other one as a pure component like React allows. The only way would be to have two different component definitions: one for the dummy PureTaskList and one for the "connected" TaskList that would basically include a PureTaskList and a reference to the store, which is exactly how the relation between InboxScreenComponent and TaskList looks like.

Because of that, it felt weird to add it. It's basically replicating the same thing twice. I don't know if this is clear enough, tho. Let me know if you get what I'm trying to say.

I do agree that the data section feels a bit out of place on its own, and I actually thought about unifying both parts but didn't want to make a change that big to the structure of the lessons.

[tmeasday]

@alterx -- thanks for the write up, that makes perfect sense to me.

I feel like the issue involved here is simply that it isn't convenient to define two components in the one file in Angular as it is in React. Otherwise everything you've said above applies to React as well, and I struggled as well with the fact that InboxScreen doesn't really do much above the containerised TaskList.

Here's what I was thinking and I'll let you decide if it is worth the awkwardness of defining another component:

• It is a common pattern to include container components deep in the hierarchy of your application (as opposed to only at the top-level, e.g. InboxScreen).
• A useful pattern to allow you easily write stories for container components is to export/split out the presentational component inside and target the stories at that. (This is the lesson that we are trying to impart in the data chapter).
• This works great at the level of that container, but you cannot apply that technique to any components higher up the tree because they include the container.
• A useful pattern to deal with writing stories for "container-containing" components is to mock out the data source. (This is the lesson that we are trying to impart in the screens chapter).

Although in this example app it really doesn't make a lot of sense to have the container not at the top-level, in order to try and demonstrate both of the above I made things a bit convoluted and showed errors at the screen level, but fetch the data at the TaskList level.

I realise you wouldn't write an app like this in reality but things are typically way more complex and you are often tempted to embed containers deep in the hierarchy. So these techniques are good to know!

(As we mention in the screen chapter it is possible to avoid embedded containers completely in your app and not ever do the data-mocking technique, but that's not a good fit for a lot of (esp. redux) apps).

---

I wonder: if splitting the presentational part from the data access in a container is unnatural in Angular, is there a way to do the first technique in some other way? I feel like it's a good idea for people to know about!

[alterx]

Exactly!, I was struggling to see the need for the two components even in the React app but now that you explain why I get it and it makes sense. The main difference is that, in Angular, that separation of components isn't as "convenient" and felt even more awkward without knowing the context.

The way of doing this in Angular is actually creating both components. I think I could add that and clarify a bit the message 😄

[tmeasday]

Awesome!

I think maybe I need to work on the text a bit to make the above reasoning a bit more obvious so people aren't thinking "this is weird why would I ever do this" ;)

[icarlossz]

Great!

[alterx]

@tmeasday

So, after a bit of thinking, I'm still not sure this part is really useful in the Angular app. In Angular, as in React, we do have connected components all over the component tree (not only at the top level) but the component definition mechanism and the separation between dumb-smart components works a bit different and the way components are bootstrapped removes some of the issues this section tries to solve.

Here's what I was thinking and I'll let you decide if it is worth the awkwardness of defining another component:

• It is a common pattern to include container components deep in the hierarchy of your application (as opposed to only at the top-level, e.g. InboxScreen).
• A useful pattern to allow you easily write stories for container components is to export/split out the presentational component inside and target the stories at that. (This is the lesson that we are trying to impart in the data chapter).
• This works great at the level of that container, but you cannot apply that technique to any components higher up the tree because they include the container.
• A useful pattern to deal with writing stories for "container-containing" components is to mock out the data source. (This is the lesson that we are trying to impart in the screens chapter).

1. is also true in Angular.
2. this is the one I have more issues with since it doesn't work/feel the same way in Angular. When we talk about "presentational components" in Angular we just have a plain old component that only has @Input() and @Output() fields. It doesn't perform any other tasks outside of processing the inputs, rendering and, if necessary, sending out events. A connected component just gets a store via dependency injection and does it's thing, that's the main difference. So, splitting the presentational component out basically means leaving the TaskListComponent as is and create a new "connected" component that renders TaskListComponent and provides it with the task list.
3. with Angular that isn't a problem: as long as you've injected the right thing via the providers array and the component is included in the ngModule you'll be able to render all the things, I've created an example in a separate branch: alterx/learnstorybook-code@74df8a2
   As you can see, other than the error related code, there's not much difference between the InboxScreenComponent and the ConnectedTaskListComponent (and their .stories.ts files) and rendering the stories for InboxScreenComponent even though it includes the ConnectedTaskListComponent is trivial as long as the rightproviders and components are available.
4. In this case we "mock" it by injecting the real thing and it "Just Works™" (again, this is due to Angular's DI system).

After this explanation and reviewing the code I've added to that branch do you feel like it makes sense to add it to this PR? I just can't shake the feeling that we'd just be repeating ourselves here

[tmeasday]

Hey @alterx thanks again for bearing with me and explaining things to me, I appreciate it.

I'm still not sure things are so different between Angular and React--notice that we could also achieve an equivalent thing to your ConnectedTaskListComponent's story in React/Redux with something like (linked):

  // This Angular:
  .addDecorator(
     moduleMetadata({
       declarations: [],
       imports: [TaskModule, NgxsModule.forRoot([TasksState])],
       providers: [Store],
     }),
   )

  // Is equivalent to this React:
  import { Provider } from 'react-redux';
  import store from '../lib/redux';

  .addDecorator((story) => (
     <Provider store={store}>{story()}</Provider>
  );

(I think anyway, apologies if I am getting this wrong).

So, again, I'm not sure things are all that different, I think I still just haven't explained why I did it this way well enough ;). Let me have another try:

1. Note that we don't write a story for the connected component in learn storybook, so in some ways the awkwardness of ConnectedTaskList and InboxScreen being the same is not so apparent 😊

2. Not that in the code snippet above, we are just letting the default state of the store render. I'm not sure that makes a good story -- really we should be providing starting state as part of the story so it is clearer what's going on. I'm sure that's possible but it's a little added complexity for the "injecting/context" approach.

3. In the case of more complex tools (or real redux stores), it may be a lot more complex. For instance, I am used to Apollo/GraphQL, where again it is possible to mock the results of a query for a Query component, but it is much more brittle than providing the props directly and definitely a order of magnitude more complex than the "split into connected/presentational, write stories for presentational" approach.

For this reason, I really think it's good to show people that technique, definitely for React where the splitting is pretty easy and natural and probably advisable for other reasons too. For Angular, where it is awkward, I get why you aren't keen to do it.

I'm not sure. I still think the technique may be useful for Angular people, and I would suggest we show it to them even if it doesn't really make sense for this particular app. But I am by no means an Angular expert (or even user) so I will completely defer to your instincts on this. Let me know what you want to do!

[alterx]

Yeah, I think my main issue is that we're basically creating two components that are fundamentally the same thing (TaskListComponent becomes PureTaskListComponent, then we create a new ConnectedTaskListComponent then, in the next chapter, we create an InboxScreenComponent that is almost identical to the ConnectedTaskListComponent. It feels like duplicating things for the sake of showing a complex pattern that may not be apparent to a person that's new to the framework and/or Storybook. So it boils down to the example being so contrived and my mind feeling like these components are just too much haha, but then again, I know that we should intentionally keep things simple.

I'll add the new components.

[alterx]

@tmeasday , I've added the new text in english, please take a look and tell me what you think.

I had to change the "We see that although the error story works just fine, we have an issue in the default story, because the TaskList has no Redux store to connect to. (You also would encounter similar problems when trying to test the PureInboxScreen with a unit test)." part in screen.md because in Angular the fact that the PureInboxScreenComponent includes the TaskListComponent requires all the dependencies of the latter to also be included. In other words, PureInboxScreenComponent is not really pure so even if I submit the error prop I also need to submit all the other properties and providers (the store, for example).

This is one of the things I thought wouldn't make a lot of sense to add (the PureInboxScreenComponent) but I added it for the sake of completeness when comparing this to its React counterpart but there's no difference between having the PureInboxScreenCompoment along with the InboxScreenComponent and only having the latter. Either way we still need to inject all the dependencies to make the stories work.

Please let me know if the text makes sense and conveys what you wanted to convey in the React text so I can translate the missing parts to spanish.

[alterx]

I think this last commit solves the whole thing while showing an alternate way of defining stories :)

[tmeasday]

I think this is great @alterx! Let's get this merged!

[tmeasday]

We probably still need to fix up the commit links .. I can do in the morning..