What is Clay in relation to DXP

[bryceosterhaus]

This conversation keeps rearing its head in various threads(https://github.com/liferay/clay/pull/3034, https://github.com/liferay/clay/issues/2421, https://github.com/liferay/clay/pull/3204).

There seems to be a root problem of not knowing where clay ends and dxp begins.

We define Clay as "A Web Implementation of Lexicon Experience Language". Which really actually isn't that helpful since Clay is multi-faceted in the fact that we have @clayui/css and then additionally the react components. I believe that definition was initially created when it was just a css library. But now we have react components that are an implementation of @clayui/css.

Then on the DXP side, we have clay:* taglibs that are a jsp implementation of clay. Clay being all of clay, both css and react.

Now I think we probably need better definitions for Clay, and specifically separate definitions for @clayui/css and the react components. This is my primary goal for this issue, determine a helpful definition that will alleviate endless back and forth discussions of how we relate to DXP.

So we sort of have this sliding scale of how specific to DXP should our API be.

I think the question is where do our taglibs, @clayui/css, and react components fall on this scale.

Currently, I think we have been sort of being treating it like...

Is the desired goal to be something more like this?

IMO, I think for v2.x, there was no clear separation and thus it resulted in many highly-specific components for single use cases. Which is probably why my personal thought has been to make a clear separation between Clay and DXP by making Clay agnostic.

Personally, I think it should be something more like this.

css and react packages are inline with one another in terms of API and naming. And then the taglibs are DXP specific implementations.

So what about all of you, where do you think Clay ends and DXP begins? Should they be the same thing? What sort of definitions do you think would help @clayui/css and @clayui/* react packages?

[wincent]

I think it's about achieving a practical, pragmatic balance between two things that both sound desirable in the abstract (ie. the two ends of the axis in your diagram: flexibility/generality vs specific/concrete).

"Balance" here doesn't mean that we have to shoot to be exactly in the middle; it just means that we need to be aware of the trade-offs involved, recognize that the optimal answer is seldom to be found at the very extremes, and to take an intentional stance about it all.

I'd add two other properties that are valuable to bear in mind:

• Consistency: Given that we have multiple pieces involved, it's desirable to have some shared conceptual language and usage patterns. The more we allow terminology and API "shape" to diverge, the harder it is for people to learn multiple parts of the system.
• Simplicity: "Simple" is not always easy to deliver, but when you can pull it off, it makes everything better — for example, simpler (more restrictive) components are easier to use, which favors adoption, reduces the possibility of human error etc; a simpler definition of what Clay is (eg. "an implementation of Lexicon") makes it easier to explain, cheaper to document etc.

I'd agree with your description of what we've done so far: Clay (this repo) has tended towards the general and the taglibs have obviously tended towards the concrete/specific. Personally, I think doing it this way in Clay has been a mistake. It's made Clay harder to use than necessary for teams working in liferay-portal, and led us to invest an excessive amount of energy running this project as though it were a broadly used community-driven and community-supported project, with all the overhead that that entails — the reality is that any use outside of Liferay is marginal. (Not a mistake that is unique to Clay: I think we've done it with a number of other open source projects too.)

I don't think the answer lies at the opposite extreme either (that's too strict) or smack-bang in the middle (that's too simplistic, and not opinionated enough). I think we should go with the simplest definition of Clay that we can ("an implementation of Lexicon"), and then strive for consistency across layers — without taking it to extremes, but making a best effort — in recognition of the fact that Liferay's usage of Clay is its whole reason for existing. As engineers, it's tempting to make things beautiful and abstract, but we are operating within the reality of an economic framework, and our prime responsibility is to create value for Liferay, the company. That obviously means serving customers as well, but the main way we serve them is by making our products better; the focus has to be on Liferay and its produts.

That doesn't mean that we totally turn our back on making low-level components or APIs that have "escape hatches" that enable customization beyond what's narrowly defined in Lexicon (having low-level, flexible components is how we ensure that the system is actually possible to evolve over time without everything being change-resistant, rigid and locked down). It means that we optimize for Liferay teams, and we weight that optimization towards where it is going to have the biggest impact. In other words, core DXP is the most important use case, but other teams working within Liferay matter too. I don't view this as a static problem space, but one which evolves over time as Liferay itself changes, its product line-up develops, market forces shape what customers expect and do etc etc. If we get this right, Lexicon, Clay and Liferay all evolve together, slowly becoming more robust, more powerful, more valuable etc.

[jbalsas]

I pretty much share @wincent's sentiment and that's what I've been trying to convey through different conversations.

I think we all mostly agree on principle on where we want Clay to stand and we just have some misalignment at times on where to draw the line or what that means in terms of implementation.

I'd like to hear from more people before being more vocal so everyone feels free to share.

Please:

• @carloslancha, could you offer your view on this adding your past experience with Clay v2?.
• @matuzalemsteles, @diegonvs, @brunobasto, would you mind sharing your opinion and enrich it with your interactions with the Brazilian teams consuming Clay?
• @pat270, @marcoscv-work, @eduardoallegrini, from a purely design language / CSS point of view... what do you think the library is and where should it stand?
• @kresimir-coko, @mateomustapic, @markocikos, @julien from what you're seeing Clay evolve and your experience developing DXP apps... how do you see the library being most useful?
• @izaera, I know you probably don't care, but just in case 😂

[brunobasto]

I think @wincent pretty much summarised it well. The hard thing to do is to find where the balance point is. Like Greg also pointed out, the balance point is not static.

From my previous experiences, I would try to avoid being on the extreme right side (too thighed to DXP) because the reality is that we don't know what DXP will look like in the near future. I don't think designers see Lexicon as a constrained set of rules (and they probably shouldn't) so for every new feature, there will always be slight modifications to what Lexicon initially predicted.

With high level components, at any given point in time we might have an API that attends the predicted use cases well, but as soon as one designer comes up with a little twist on some use case, then the API might become a limiting factor for developers.

On v3 I liked the idea of having both high level and low level components because that enabled the use of clay in cases not predicted by Lexicon without having to implement the hole thing from scratch (using only clay/css) just because one little detail din't quite fit the actual use case.

Having that said, we should also keep in mind who is using our APIs. High level components (and also TagLibs) are very useful for those that are not very comfortable with React (or JavaScript).

[matuzalemsteles]

Hey guys, I'm still a little confused about this conversation, it seems that we have returned to the definitions of low-level and high-level... I don't understand why both would not solve these problems but I see that it may be a speech more aligned to Clay than the components in React but in the end, it always comes back to him.

In my view, we should always stick to what the Lexicon predicts and not directly to the DXP use cases... it's a long-standing product with a mix of different frameworks and standards in each project. I think trying to bring what's in DXP here seems a little wrong because we're trying to go back and just cover the legacy with something modern instead of rethinking the standards and defining the new cases based on our current tool, React, our current library. As everyone said we have to have a balance, I think we are getting there, we will not necessarily get a clear definition on this because we do not have a library of tools for the DXP but a library of components for a Design System, things are different here and we need to understand that.

Although DXP is the main consumer of Clay and Lexicon, we shouldn't push all use cases for both, the definition of the Design system is exactly that, predicting common and primitive cases and not all cases that appear with each release, Clay it should be enough to support teams to allow them to continue using Clay as a base, like the definitions we created for low-level and high-level, which tries to fill the different cases between each team.

A vision that we seem to have is that we mix things up, we try to make Clay the DXP tool library and at the same time a Design System. The Design System offers the fundamentals and the base is what we are trying to do with Clay now and at the same time trying to fill this need to be an internal library for DXP and to cover whatever case two or three teams are having.

At the time of Clay v2, we went a long way to faithfully following the Lexicon cases and creating giant APIs, it seems that it was an error when people couldn't use it properly and had many problems. But on a good look, maybe the problem was not the rigid APIs and maybe what we wanted was to make the components more primitive, simple, less complex and just a basis for creating new things. It seems clearer when it comes to Design System but if we wanted to make Clay at the time a library for DXP, the rigid and large APIs and large components would not be the problems...

As a final point, I would say that clay:taglibs should be very limited and the components should at least have the consistency of some APIs but we should not reflect the limitations of taglibs in the components. Now the question, is clay:taglibs part of the Clay package? if so we should approach the definitions of a Design System and not try to mix into being a library for the DXP if we want that we should just disconnect the Clay name maybe?

[jbalsas]

Just a quick intermission while the rest of the comments keep coming:

[...] stick to what the Lexicon predicts and not directly to the DXP use cases... it's a long-standing product with a mix of different frameworks and standards in each project. I think trying to bring what's in DXP [...]

When we say that this is being used in DXP... we don't mean an old version of DXP. We mean an updated version (current) updated to faithfully recreate and implement Lexicon patterns in the web. That is, teams in DXP are implementing Lexicon pieces for real. Not legacy versions of it, but current actual versions. That's one place where we see how the recommendations of the Experience Language is implemented in real life.

Now the question, is clay:taglibs part of the Clay package?

This is a very interesting question... I'll let everyone mull it over 😁

[pat270]

Clay CSS stands closer to the DXP side of the scale. Most of the components were created because it was needed in DXP. This isn't bad. DXP's requirements are common across many apps. There was a real need for fluid containers that maxed out at a specific width so Bootstrap added container-sm, container-md, container-lg, etc in 4.4. We had already added something similar early on (container-fluid container-fluid-max-xl). This is a common trend with Bootstrap 4 updates. We already have them because DXP needed it.

Clay CSS is using a similar pattern to the low level high level components in Clay React. The markup is ugly, but you can drop stuff in to get a UI you can use. I agree with everyone the low level high level pattern is the right direction and allows us to adapt to changing needs.

We can still make a library that is low on the scale have high API Specificity. What matters is implementation. Utility classes are as low as you can get on the scale. We create specific components using utilities with no flexibility. We now have high API Specificity with an Agnostic 3rd party framework.

[kresimir-coko]

From what you're seeing Clay evolve and your experience developing DXP apps... how do you see the library being most useful?

Since the goal with Clay isn't to make a widely popular and used library we should focus on it's primary purpose, implementing Lexicon to be used by Liferay's products. If any new app starts getting built by Liferay, we should aim that Clay has enough to get them far enough so that Lexicon + Clay can develop new components that they request. Do we have people asking teams what they need from Clay, or is it expected from them to open issues on Github? We seem to be not getting requests for new components at all, is it because teams don't know they can ask us?

Documentation & Consistency

I believe that these two things can make or break Clay. Sure, DXP will use Clay (almost) no matter what, but what about other Liferay apps, like Commerce for example? Those projects need Clay to be well documented and consistent. When those two things are combined users develop intuition on Clay, because after some time of using Clay I already know that some components are gonna have a displayType prop, that's awesome. I think that, with as big of a project as it is, Clay is very consistent in it's implementations, whereas Clay's user-facing content (clayui.com and storybook) can be improved. Having a clear, simple and consistent documentation on clayui.com and storybook can give us a lot of "easy" points in these categories.

Storybook

When I first landed on Clay's Storybook a while back I closed it thinking it was something for Clay developers to use, like a troubleshooting tool that I stumbled upon. Now I use it every day, which leads me to believe we can use Storybook to reduce friction that a component library might introduce when using it in a big project, like we have them in Liferay. Perhaps it's with descriptive naming in the navigation, or by having a docs page explaining what Storybook is and how to best use it.

Developer Tools

I have no experience on the subject, but is something like a VSC extension possible for Clay? Something to only display related props when using a component, instead of everything available, sorted alphabetically like it is now

[bryceosterhaus]

@wincent It's made Clay harder to use than necessary for teams working in liferay-portal

Any particular areas that have been hard about it? I really haven't heard much feedback from teams or other users other than a few one off bugs.

This actually makes me think, after reading through all these comments, one thing I've realized is that I don't actually have a ton of evidence to know whats working well for users and what isn't working well. This sort of comes across as the biggest red flag for myself in that I don't entirely know what users are experiencing or pitfalls they have encountered. I've talked with a few teams and devs but nothing comes up other than small one off issues.

Now the question, is clay:taglibs part of the Clay package?

This is a good question and probably gets at the root of some of the back and forth confusion as how in-line the tag vs component APIs should be. IMO I think if we have taglibs called clay, they should be an implementation of Clay and not the other way around. And if we define clay as an implementation of Lexicon, it seems to me that Clay would be generic to DXP, specific to Lexicon, and then the taglibs would be specific to DXP.

[jbalsas]

Hey @bryceosterhaus, nice points there!

[...] the biggest red flag for myself in that I don't entirely know what users are experiencing or pitfalls they have encountered [...]

This is what I've been trying to convey... DXP is the main user of Clay... and DXP is more than just the new React Apps and components. It's all of them. One clear pitfall is that Clay is not easily usable from JSPs (which make up for a sizeable portion of the products). So, the lack of Clay footprint is a proof itself of its shortcomings.

[...] IMO I think if we have taglibs called clay, they should be an implementation of Clay [...]

Spoiler alert... they are.

In its purest V2 form, all we do is pass down data to the soy templates. V2 tags are but a simple data passthrough wrapper to our components.

pageWriter.writeln(
    SoyTemplateRenderer.renderTemplate("ClayDrodopwon.render", data)
);

pageWriter.writeln("
    <script type="text/javascript>
        new ClayDropdown(data).render("#foo"));
    </script>
");

For v3, the way this more or less should look like (raw, it doesn't exactly look like this, but so you get the idea) would be:

<div id="foo">
    // Render basic markup only
    <button class="btn btn-secondary>Dropdown</button>

    <script type="text/javascript">
        ReactDOM.render(<ClayDropdown... >, document.getElementById("foo"));
    </script>
</div>

Basic SSR rendering with pure Clay hidration.

[...] and not the other way around [...]

They aren't. This is important to understand... tags in DXP are simply a wrapper around Clay.

Since we do have an additional layer, we're also able to "correct" some of the missing ergonomics coming from Clay. The better defaults we offer in Clay for the real usages, the less we need to tweak in DXP.

It's not that Clay needs to bend to DXP, it's that DXP is the biggest and real set of data points we have about Clay usage (or lack thereof). Failing to acknowledge that will inevitably result in lack of data to make accurate decisions.

[wincent]

@wincent It's made Clay harder to use than necessary for teams working in liferay-portal

Any particular areas that have been hard about it? I really haven't heard much feedback from teams or other users other than a few one off bugs.

I may be at risk of extrapolating from my own experience, and from the experience of those nearby me in the office (back when we used to actually be together in an office) that have made remarks about Clay, when talking about "teams working in liferay-portal". So reframing it in terms of personal exprience, I personally have found Clay to be difficult and painful to use:

• It feels verbose and boilerplately, with a large array of attributes. As the number of attributes increases, the likelihood that we'll come up with intuitive/obvious/transparent names for them decreases, which leads to the next point...
• The documentation and storybook examples are (or were) thin, so I very quickly learned that any time I wanted to use a Clay component, I had to look at the source code to figure out what options it had and what they do. I'm sure they've improved over time, but once burned, I am probably going to continue to stick with git grep and vim, because the source code is the one thing that by definition cannot lie about or fall out-of-date with what the implementation actually does.
• On several occasions, even though we had a low-level component (because of course we couldn't use a high-level component to express some bespoke corner case in liferay-portal), the low-level component wasn't flexible enough to permit the required behavior. And because I am lazy, rather than go through a lengthy process of debating feature requirements here, waiting for an implementation, waiting for a release etc... or fighting with various parties to try and get them to align on a different design though would be expressible using the existing tools.... I have tended to just drop down to primitives — React components that render divs and spans and that have the desired behavior. The list of things to do is just too long, and you could argue that by rolling my own things I am just adding to the mountain of technical debt, but getting everything done "the right way" via Clay/Lexicon etc feels like a Sisyphean struggle that just pulls me away from other, much more impactful tasks I could be completing.
• Finally, I think we've overmodularized this, and as a result instead of having a single version number of "Clay" in liferay-portal, we have an array of independent releases with different version numbers, changelogs etc which contributes to the whole thing not feeling cohesive, consistent and dependable.

Now, please don't take all this as a critique of Clay (I know, too late... 😬). Whatever has been negative or lacking about my experience with it could just as easily be attributed to my own lack of ability or familiarity with it — I have also heard people say that they love working with the new Clay React components. I don't know what life used to be like at Liferay, but it sure seems like what we have now is a big improvement.

[kresimir-coko]

The documentation and storybook examples are (or were) thin, so I very quickly learned that any time I wanted to use a Clay component, I had to look at the source code to figure out what options it had and what they do.

I get this so much, which is why I'm putting all of my time right now and in the near future to bring documentation up to a respectable point. IDK who worked on Clay before I joined the team, but if it was the same people as now, sans me, I can understand why the docs were so thin.

At the end of the day what's the point in having a component library if it has so much friction in order to use it that you're better off writing your own component.

[diegonvs]

The documentation and storybook examples are (or were) thin, so I very quickly learned that any time I wanted to use a Clay component, I had to look at the source code to figure out what options it had and what they do.

When we're creating these docs, We were thinking about first deliver the components(due to some delays in milestones) and then creating a simpler documentation for people(our Clay team and DXP product people) enhance it. I think we're on the right way, improving our docs day-by-day and turning clay docs more mature.

About the low-level/high-level balance:

I consider Clay low level components a good foundation for creating another components. Designers don't follow strictly Lexicon rules, We needed to provide a good way to stick with that and I think We got it. However, these components may not be too productive for teams and I think We can invest more time analysing patterns on DXP e.g SearchContainer and create these components on frontend-js-react-web.

I don't think Clay is mature enough, I think we are evolving day after day given the complexity of the product, communication with designers and team development

[brunobasto]

On several occasions, even though we had a low-level component (because of course we couldn't use a high-level component to express some bespoke corner case in liferay-portal), the low-level component wasn't flexible enough to permit the required behavior. And because I am lazy, rather than go through a lengthy process of debating feature requirements here, waiting for an implementation, waiting for a release etc... or fighting with various parties to try and get them to align on a different design though would be expressible using the existing tools.... I have tended to just drop down to primitives — React components that render divs and spans and that have the desired behavior. The list of things to do is just too long, and you could argue that by rolling my own things I am just adding to the mountain of technical debt, but getting everything done "the right way" via Clay/Lexicon etc feels like a Sisyphean struggle that just pulls me away from other, much more impactful tasks I could be completing.

I can relate to that

[matuzalemsteles]

I think that in the face of all this it seems that we have something that came up and that I am very surprised, I think that before going ahead with Clay's future plans we should start to reflect on what would be the way forward, and first of all, to reap the feedbacks from people who use Clay to know if there is this same feeling shared among people I have the same view as Bryce I still haven't seen people complain that Clay is not working for the most of the time but I hear that some components are not yet well aligned or some APIs still need to be rethought I think this is natural and is part of the evolution process of any API...

Before moving on, some of the things we need to keep in mind about the past and not try to fall into the same problem. Clay actually has many components, perhaps not so many compared to other libraries, but it was necessary to meet the expectations of many people... Important points to keep in mind:

• Having components fully aligned with the Lexicon did not work... we did it in v2, we know what the problems were, that was the dream but it is not the reality, the train moving and new visual changes appearing and new cases appearing. Even if we try to be future proof with flexible components there will always be new cases or edge cases.
• Only flexible components could be the ideal solution to be proof of the future or just allow Clay to be the foundation, but what is the point of flexibility? I think that was the biggest discourse we had on other issues of trying to reach the breakeven point, I would say it is difficult and that is where we are trying to get.
• Some DXP products people just wanted to use Clay according to what Lexicon specified just by doing a copy & paste, but the big point is, how would I balance this if it didn't work in v2, it wasn't the reality.
• The development of V3 was considered to support not only DXP but to help teams like Analytics Cloud, Commerce, and an internal Liferay Cloud product that it started using recently to develop quickly... Given that the components were made in different ways in each product, so we had to work on more generic components... which goes back to the subject of what we think Clay was developed for.

One question that remains that I want to ask about in the face of all this and the expectation of what I am seeing is: Do we really want to support these teams? Should we put aside the idea of ​​the Design System and continue with nested components only for DXP and its cases?

[jbalsas]

Do we really want to support these teams?

Yes.

• Commerce is built on top of DXP and heavily relies on most of its bundled applications. Supporting DXP supports Commerce.
• Insurance Portal (or other solution) is built on top of DXP and 100% relies on it. Supporting DXP supports this product too.
• Analytics Cloud would be a good testbed for our React components... but I don't see Clay gaining much traction there, and they seem comfortable with what they have. I'd love to serve them, but they might just not want us... 🤷
• Liferay Cloud can move to Clay. We're ready to support them when that happens. It hasn't yet. Optimizing for a case that might or might not happen is pretty dangerous as we might end up supporting nothing. We want to support them... but we can't support them if they're not using Clay.

Should we put aside the idea of ​​the Design System and continue with nested components only for DXP and its cases?

No.

Please, re-read https://github.com/liferay/clay/issues/3214#issuecomment-627530925 and https://github.com/liferay/clay/issues/3214#issuecomment-628437396.

Most designs in DXP are faithful to Lexicon. When they diverge, they either check with Lexicon to make them converge or we tell them to implement it on their own. This case is a minority. 90% of the interfaces in DXP are standard Lexicon. And many of them aren't easily implementable with Clay (lack of JSPs or flexibility or APIs are you mention...)

Whenever there's a gap in Clay, teams in DXP implement Lexicon or their components in any way they can. When the gap is directly on the Lexicon side and not in a new custom crazy component, Clay should fill that up. We never bring DXP-specific components to Clay. At least this hasn't happened to the best of my knowledge and no one is saying it has to.

We already cleared that up. If it's not in Lexicon, it's not in Clay. If you want something in Clay, you go through Lexicon first. The thing is... there's a lot of Lexicon in DXP implemented in raw HTML or components because Clay is not offering those facilities (JSP tags or React components).

[matuzalemsteles]

Most designs in DXP are faith to Lexicon. When they diverge, they either check with Lexicon to make them converge or we tell them to implement it on their own. This case is a minority. 90% of the interfaces in DXP are standard Lexicon. And many of them aren't easily implementable with Clay (lack of JSPs or flexibility or APIs are you mention...)

😱I'm surprised to hear that, but how much are our Clay APIs not covering the cases, are they specific APIs? Specific components? It’s interesting because we don’t see many reports about it in issues, there are usually some exceptions to some APIs that we’ll work on and improve but that way it looks like it’s all components, and Clay doesn’t work for people 😞

We already cleared that up. If it's not in Lexicon, it's not in Clay. If you want something in Clay, you go through Lexicon first. [...]

I think that would be the perfect world but apparently it doesn’t flow very well in Brazil, people don’t want to pay for this time to go through Lexicon and arrive at an implementation in Clay, even if they’ve done it before they wouldn’t go back to put Clay there. The funniest thing I see is that this is very common because when they always start a new story or new resources there are always unforeseen cases and they always come back to us in Brazil frustrated because they are not able to use Clay most of the time what is a feather 🥺...

The thing is... there's a lot of Lexicon in DXP implemented in raw HTML or components because Clay is not offering those facilities (JSP tags or React components).

I think the next thing would be to take these cases and document and review why Clay didn't work for them, since they follow the Lexicon!

[jbalsas]

[...] and they always come back to us in Brazil frustrated because they are not able to use Clay most of the time what is a feather

So this is important feedback and in line with what we're seeing. We need to double down on this, go back to the teams and work with them. Figure out what's preventing bigger adoption of Clay, bring that back and work on fixing it.

I also want to make echo of @wincent's comment:

I have also heard people say that they love working with the new Clay React components. I don't know what life used to be like at Liferay, but it sure seems like what we have now is a big improvement.

I think this is also true and not at odds with still needing to work on it. Clay's development experience, specially with the new react flavour, is a great improvement and developers are enjoying working with it. We need to keep figuring out ways to serve them, but I feel we're on the right track!

I think the next thing would be to take these cases and document and review why Clay didn't work for them, since they follow the Lexicon!

The most standard, stable cases of Lexicon are written in JSPs and JSP tags ☺️

[bryceosterhaus]

One clear pitfall is that Clay is not easily usable from JSPs (which make up for a sizeable portion of the products). ... The most standard, stable cases of Lexicon are written in JSPs and JSP tags

So it sounds like the key point in this is JSP + Components. Which is more fundamentally a React+JSP issue and not a clay issue. I vaguely remember from our initial conversations of Clay+React pre v3.x, we kept pushing the react+JSP issue down the line saying it would just need to be a technical issue we work out and it wouldn't be an issue, which was probably a mistake for us to not figure that out first.

So perhaps, instead of this being a Clay specific issue, we focus on React+JSP instead?

[diegonvs]

So this is important feedback and in line with what we're seeing. We need to double down on this, go back to the teams and work with them. Figure out what's preventing bigger adoption of Clay, bring that back and work on fixing it.

For Brazilian teams, these low-level components are very important for using Clay(verbosely, may not too productive) and not block them. We encourage them to make questions to design people about the usages but sometimes is not too easy. They'll be blocked and will not use Clay components just using markup.

[bryceosterhaus]

Analytics Cloud would be a good testbed for our React components... but I don't see Clay gaining much traction there, and they seem comfortable with what they have. I'd love to serve them, but they might just not want us... 🤷

For what its worth, I think they already had a large set of base reusable components they were using before v3.x was even a thought. In order for them to go back and replace these components with clay, it just requires time that they don't have since their team recently got smaller.

[jbalsas]

So perhaps, instead of this being a Clay specific issue, we focus on React+JSP instead?

No, I don't think so... at least it's not an issue, it's just what it is, and something we need to take on slowly.

To me, the key points from this conversation are:

• We should focus on building a highly composable library that speeds up building Lexicon-based UIs
• We should follow modern best practices and try to limit the impact legacy code has on our decisions while we push for a React approach
• We need to properly identify real cases to help us drive our decisions, which components to build and which defaults to apply.

That last point is the one that I think is really our key misalignment. To me, the problem is not that we still don't have the JSP tags, but that we make decisions that make implementing them a bit harder because we identify those as something specific alien to Lexicon. This is the what I'd like to correct.

It's not that we have to build for DXP just for the sake of it being DXP, but because that's our biggest and better test lab to know how Lexicon is evolving and what the big majority of developers in our company need. And one last time, with this, it doesn't mean we want to look the other side when it comes to other teams, just that we can't prioritize decisions to serve customers we don't have over customers we actually have.

For what its worth, I think they already had a large set of base reusable components they were using before v3.x was even a thought. In order for them to go back and replace these components with clay, it just requires time that they don't have since their team recently got smaller.

Yeah, that's what I meant. Depending on the conditions of the team, they might never reallly need to move to Clay and that might be totally fine. If we identified AC using Clay as strategic, we'd likely have to work with them to get it done. Same with DXP Cloud. Until then... DXP and Commerce are our main consumers.

[bryceosterhaus]

Okay, so I think we all agree that DXP is our primary target and end user, and so we need to primarily build with that in mind. So no need to hash out that more.

As for my original question of "What is Clay in relation to DXP?", I think @jbalsas's points summarize this well of

• We should focus on building a highly composable library that speeds up building Lexicon-based UIs
• We should follow modern best practices and try to limit the impact legacy code has on our decisions while we push for a React approach
• We need to properly identify real cases to help us drive our decisions, which components to build and which defaults to apply.

I think points 1 & 2 we have already been doing pretty well. Clay is very composable and also follows modern practices. And for point 3, I actually think we have done well at this because we have been identifying use cases from Lexicon and teams and providing components and examples for those.

However, from this thread, I get a sentiment from a handful of these comments that "clay isn't helping DXP". One pitfall I see is our docs, and I think we can push to improve these. However, other than that, what are the exact areas of trouble? And specifically I am curious why Clay is causing trouble and it not being a React+JSP issue(@jbalsas: " it's not an issue").

I gather this general sentiment from comments like...

@jbalsas Whenever there's a gap in Clay, teams in DXP implement Lexicon or their components in any way they can. When the gap is directly on the Lexicon side and not in a new custom crazy component, Clay should fill that up.

@matuzalemsteles they always come back to us in Brazil frustrated because they are not able to use Clay most of the time

@wincent & @brunobasto the low-level component wasn't flexible enough to permit the required behavior

@jbalsas 90% of the interfaces in DXP are standard Lexicon. And many of them aren't easily implementable with Clay

Some specific issues brought up were:

verbose and boilerplately,

I don't know if there is any way around this since jsx is naturally boilerplatey and our end user, DXP, has so many various use cases that naturally we have to provide APIs to adapt for those cases.

we've overmodularized this

I'd be happy to combine all in a single package or version if we actually think it would solve our main problem in being helpful for DXP. However, I'm not quite sure this is that big of an issue for users. Happy to be wrong though.

Final thoughts... What are the gaps and real use cases that Clay is not filling? What specific cases are not "easily implementable with Clay"? Are there any examples(issues, teams, people, etc) we can look at so that we can fill these gaps? Otherwise, it sort of feels like Clay is up against an unknown standard of that "its just not helpful for DXP", but no clear reasons why it isn't. The only two I am aware of are Tables and Layout, both which we are waiting on to gather more requirements.

My overall goal here is determining steps forward in making Clay valuable to DXP and Liferay. If there are use cases and teams we aren't providing value for, what is the pain point or pitfall? How can clay move forward and provide more value?

[brunobasto]

@wincent & @brunobasto the low-level component wasn't flexible enough to permit the required behavior

Actually, this was more like the case for me when using high level components. With low level components I feel they provide greater flexibility with the only drawback of being harder to understand (or to know they exist) sometimes.

What are the gaps and real use cases that Clay is not filling? What specific cases are not "easily implementable with Clay"? Are there any examples(issues, teams, people, etc) we can look at so that we can fill these gaps? Otherwise, it sort of feels like Clay is up against an unknown standard of that "its just not helpful for DXP", but no clear reasons why it isn't. The only two I am aware of are Tables and Layout, both which we are waiting on to gather more requirements.

Maybe @interaminense @brunofarache @alinedoleron @albinojunior (to mention a few) can provide some feedback about what they've experienced so far?

[brunofarache]

Maybe @interaminense @brunofarache @alinedoleron @albinojunior (to mention a few) can provide some feedback about what they've experienced so far?

Those are the most common high level components that I’ve been copying and pasting over some modules (App Builder, Forms Report, Workflow Metrics, Data Layout Builder):

• TableWithPagination, or even more complete, a TableWithPaginationAndManagementToolbar, which is basically a SearchContainer taglib clone, connected to a Rest API endpoint.

• EmptyState

• Loading (loading spinner), I guess Clay already has this spinner, but had to create a HOC for Table.

• PermissionsModal is being used in app builder only but I can foresee it being used in other places because permission management is now available through Rest API too.

• useRequest or something better that makes it easier consume our Rest APIs (response parsing and error handling are done the same way for all APIs, it’s a repetitive task)

• SearchInput, used to filter a list as you type, and shows an empty state if everything is filtered out.

Not sure if that’s what you are asking for though, @brunobasto. This thread is huge and I haven’t read the whole thing.

[jbalsas]

Thanks @brunofarache! I think some of those usages are legit, and from some we could gather some inspiration if see repeated usage across DXP.

I want to make sure we answer this:

Now the question, is clay:taglibs part of the Clay package?

YES

As I think it must be clear by now, JSP tags are just a wrapper around the React components and our ClayCSS generated markup.

The reason why they live in liferay-portal is mainly technical. All the infrastructure to compile JSPs is available there. The clay taglib is mostly a library for DXP (we don't really know about any external pure JSP consumers...), keeping it there reduces friction for both DXP and ourselves as maintainers.

I've always been reluctant to add this information to http://clayui.com specially because of the complex relation and DXP-coupling. However, it seems this is both confusing ourselves and making this information harder to find. In lieu of this, I'm going to propose adding the JSP Tags information usage to our site as part of What kind of information is contained on component pages?

[matuzalemsteles]

Closing this issue, related to comment on https://github.com/liferay/clay/issues/3849#issuecomment-1635083207.