Package | Components architecture (VanillaJS/HTML)

[jeffchew]

Jeff-Chew created the following on May 23:

Overview

This is the creation of the package architecture for the Components (VanillaJS/HTML flavor). This will include all IBM.com related components.

Additional Information

• Should look into the current carbon-components to see what architecture can be lifted from there

Acceptance criteria

• Components should reference the styles package for CSS styling
• Storybook HTML as an output, as it will serve as the living documentation for this package
• Appropriate lint/unit testing functionality
• Pre-commit/pre-push hooks
• Publish scripts to generate modular output
• README on setup and usage

Original issue: https://github.ibm.com/webstandards/digital-design/issues/860

[jeffchew]

On Jun 25, Jeff-Chew commented:
@vladislav-saling @kenny-lam @james-dow I added in a story to look into Storybook for vanilla JS (https://github.ibm.com/webstandards/digital-design/issues/1120), which I think I'd prefer if it weren't for the Drupal team's ask for twig/json files. But we would also need a way to test the twig/json files themselves, which currently only see that support in pattern lab.

[jeffchew]

On Jun 25, james-dow commented:
@Jeff-Chew what type of testing are you expecting? Does it go beyond unit testing, or are you looking for interaction/behavior basic QA testing?

[jeffchew]

On Jun 25, Jeff-Chew commented:
@james-dow The latter. Testing meaning to make sure that the templates render properly. From what I can tell, storybook won't work with twig templates, but pure HTML as part of the stories. It only seems like pattern lab with the twig php engine would be able to render twig templates as part of the output, but I don't want to get tied down to using pattern lab because I honestly prefer Storybook. I'm torn because this is a must have request coming from the Drupal team.

cc: @kenny-lam @vladislav-saling @hahnrob @linda-carotenuto @Wonil-Suh1

[jeffchew]

On Jun 25, james-dow commented:
Correct me if I'm wrong, but we're talking about two separate issues, right?

1. There is the QA testing process, and then...
2. Drupal's oddly specific requirements.

In relation to Drupal, I haven't been a part of those discussions so I'm not totally looped into the requirements. But I am curious why Drupal wouldn't just use the given component/pattern's documentation page on the website? I'm a little confused why they would be special enough to warrant their own documentation site like Storybook.

Looping in @chsanche too.

[jeffchew]

On Jun 25, Jeff-Chew commented:
@james-dow they are somewhat related. Note, I talked about this in depth in yesterday's engineering huddle in the second agenda item, but will give the td;dr for non-engineers here (as well as @vladislav-saling who wasn't able to attend the huddle yesterday):

• Drupal today has the team manually copying and pasting HTML templates into their drupal themes
• Data mapping to templates is currently a manual process
• Drupal team is looking to use a combination of twig templates with corresponding JSON data file to add automation to their data mapping within Drupal
• They wish to reference the twig templates directly from our components/patterns packages, and will automate data mapping based on the template JSON structure

They don't want pattern lab, per se, but the underlying twig/json templates which they can reference directly in our packages. So theoretically, we wouldn't have to do this in pattern lab but whatever automated template documentation we wish to use (storybook, fractal, pattern lab, etc). However, we wouldn't have a way for us to visually test if we are creating twig templates, unless we have something like pattern lab's twig php engine. Which is the problem I described above.

I'd love to find a way to use something more modern like Storybook. It gives us niceties like knobs, storyshots, etc. But I'm struggling with the Drupal request.

cc: @hahnrob @Wonil-Suh1 @kenny-lam @linda-carotenuto

[jeffchew]

On Jun 26, Jeff-Chew commented:
FYI, moving this out of the sprint for now. Want to have some conversations with Drupal team, as well as package approach internally before we move forward.
cc: @kenny-lam @james-dow @vladislav-saling @hahnrob

[jeffchew]

On Jun 26, james-dow commented:
Right, I remember talking about it shortly in the huddle, but it didn't feel like we went super in depth. I did raise a similar concern in that meeting though.

This part here I understand and get. I'm not trying to say I don't see value in something like a Storybook for testing and live documentation purposes. I do wonder if we could make the website live documentation, but that's probably a little larger effort.

However, we wouldn't have a way for us to visually test if we are creating twig templates unless we have something like pattern lab's twig php engine.

What I don't understand is the following. I don't understand how storybook or even pattern lab solves these problems/requirements that they have.

• Drupal today has the team manually copying and pasting HTML templates into their Drupal themes
• Data mapping to templates is currently a manual process
• Drupal team is looking to use a combination of twig templates with corresponding JSON data file to add automation to their data mapping within Drupal
• They wish to reference the twig templates directly from our components/patterns packages, and will automate data mapping based on the template JSON structure

Couldn't we just push a twig template library to Packagist using Composer with a twig template and its corresponding JSON data file? (I'm really curious learning more about this data file requirement, and how it works). Then Drupal could just use the documentation on the joined gatsby website we build. I'm struggling with why they (Drupal team) would need patterns lab or storybook. Maybe I don't fully understand storybook, and pattern lab's full capabilities, but I thought they just kind of automated creating that live documentation you were talking about, and creates a nice environment to manually test the components.

I feel like there is a disconnect with me personally here. I'm not sure if I'm missing some piece of the requirement that ties the two together, or if I'm missing some sort of limitation whether with our site, Storybook/Patternlab, or PHP in general.

[jeffchew]

On Jun 26, Jeff-Chew commented:
I set up a meeting with our tech team and theirs in a couple of weeks. Hopefully we can hash this out. But the bottom line is that from an implementation standpoint, they don't need pattern lab.

What they asked for and need is a place to directly reference twig templates, where they would want us to provide those and they reference directly from our packages (and not from pattern lab, storybook, fractal, or any other automated templating tool).

Before the meeting with their team, I already added a topic in our morning huddle to talk more about this.

[jeffchew]

On Jun 26, vladislav-saling commented:
If I remember correctly, some of the talks about Drupal friendly implementation happened before stronger alignment on the website solution (joined gatsby thing). Is it possible to review Drupal requirements in light of that? Considering possible engineering overhead I'd lean towards a bit more minimalistic solution (twig template lib?). Maybe we could start outlining an MVP that would satify Drupal needs.

IIRC @kenny-lam was the closes to Drupal team earlier this year so he might have some extra insight.

[jeffchew]

On Jul 09, Jeff-Chew commented:
@hahnrob I dropped the priority of this story and moving it out for the v1.1 release for now. We will be focusing more on #224 .

[jeffchew]

On Jul 17, Jeff-Chew commented:
@hahnrob after discussion with the tech team, we're pushing out vanilla support for now, so I removed the milestone and release.

[jeffchew]

On Oct 03, Jeff-Chew commented:
@hahnrob @linda-carotenuto I'm thinking of pushing this out to a future sprint since this isn't needed until v1.2.

[jeffchew]

On Oct 03, linda-carotenuto commented:
ok, agree