Investigate the use of custom tag names for React Components

[tomalec]

It's quite a high-level idea, for DevX improvement. Probably, could be discussed with a broader audience.

Problems

Currently, all our React components are returning a <div> as a top-level element. To style it the component we use a class, like <div class="woocommerce-dashboard-section">.

That introduces several problems:

1. We end up with a meaningless div-soup
   • makes the resulting tree harder to read, debug and maintain
2. It's not clear whether the given CSS rule is meant to style all instances of the component being defined or a group/class of elements.

3. To style the child/sub-components our component uses, we need to know the child component implementation details or sprout more class names everywhere. Consider following example. Woo's ProfileWizard uses external component TabPanel from @wordpress/components, and wants to set some styles for the TabPanel element. To achieve that it either

   • needs to know and hard-code the implementaiton detail of TabPanel: the .components-tab-panel__tabs used there
   • put a class name on <TabPanel>

   What's even more confusing, in this particular case it does both :confused: Why?

Proposal

I think we can improve it by using a component's name in HTML as well. So we will have a more 1:1 relationship between the JS and HTML code. The code we write and the code that is executed in a browser and we the A8C developers, HEs, and our users debug.

We can simply render an element with a custom name, like <woocommerce-profile-wizard>.

:warning: Please note, that we do not have to define any custom elements.

Its behavior is defined as HTMLUnknownElement and HTMLElement. and it works well even in IE9. You can check how it works in your browser here https://jsbin.com/wupinok/edit?html,output.

Benefits:

• HTML code is more readable and informative. (addresses Problem 1.)

  • the reader is not hypnotized with 100s of divs

  • close tags give information about what component is closed. (See an example from YouTube)

  • class attribute is less bloated

  • HTML and CSS code now have a semantic distinction between a name that describes a component kind and a name that describes a group/class of elements.

  • lower risk of class name conflicts

• We are using and supporting the native open web feature, rather than relying on a specific framework
• We are getting closer to use modern web platform features like custom elements. (Probably, one day React will keep up with WebComponents, and eventually will sue custom elements anyway, as no code is always faster than any code)

• We could use it to style child elements of a component. Consider, we are creating a "WOO FAQ List" component, that would use "WP FAQ Question" component. With native HTML and CSS, we could write:

  <style>
    :host {
      display: flex;
      flex-direction: column;
    }
    /** as a `woo-faq-list` author, I know that I'm using `wp-faq-question`, so I'll use its name */
    :host > wp-faq-question { 
      border-bottom: 1px solid black;
    }
    :host > wp-faq-question:last-child {
      border-bottom: none;
    }
  </style>
  <wp-faq-question>A?</wp-faq-question>
  <wp-faq-question>B?</wp-faq-question>
  <wp-faq-question>C?</wp-faq-question>

  see working example https://jsbin.com/zohewew/edit?html,js,output

  With React we could do the following:

  import WPFAQQuestion from '@wordpress/components';
  
  export class WooFAQList extends React.Component{
      static tagName = 'woo-faq-list';
      //...
      render(){
          return 
              <WooFAQList.tagName>
                  <WPFAQQuestion>A?</WPFAQQuestion>
                  <WPFAQQuestion>B?</WPFAQQuestion>
                  <WPFAQQuestion>C?</WPFAQQuestion>
              </WooFAQList.tagName>
      }
  }

  then the WooFAQList.css would be simply use woo-faq-list > wp-faq-question or ${ WooFAQList.tagName } > ${ WPFAQQuestion.tagName } if we would use any CSS-in-JS solution to effectively avoid any name conflicts in HTML and CSS.

Potential problems and solutions:

• React throws warnings when encounters non-native <customname>. We can stick to <custom-name> to keep it happy.
• Tag names may collide between plugins/projects/teams. We already have that problem with classes, right? There is nothing new introduced here. However, it should be easy to solve that problem here, see the point below.
• If we will use <custom-name> and some third-party code register a custom element with the same name, we could get unexpected behavior. We can use <customname> and workaround React warning. However, I'd say the chances somebody else would register a woocommerce-admin-faq-list element are pretty low. For sure lower than somebody creates CSS styles for .woocommerce-admin-faq-list. Also, if somebody is registering a woocommerce-admin-* custom element, they are asking for problems anyway. Luckily we generate those names in JS anyway, so if we would like to be safe for those cases, we could simply add some tiny utility or a feature of the base Component class, so the tagName getter would return something like <woocommerce-admin-faq-list-dg23j6>.

Risks, to be checked and evaluated:

• [ ] Performance hit for rendering HTMLUnknownElement or HTMLElement vs DivElement. I guess it's minimal, as browser engines written in C should pretty early and inexpensively cut any custom-element lifecycle for those elements.
• [ ] Legacy browsers, like IE < 8
• [ ] React may have some difficulty with attribute vs. property distinction for non-native elements.

[ecgan]

@tomalec , hey this looks really cool! First thing that came to my mind is some time ago I read that react and custom elements do not work well together, I'm not sure how true it is today though. Also, I think that there is a way to put namespace for custom elements like <woocommerce:faq-list>, right? This might help to avoid collision.

Lastly, do you know if there is prior art or discussion on this within a8c? That would help to determine whether this is a go or no-go.

---

see working example https://jsbin.com/zohewew/edit?html,js,output

Btw, there is no output in this jsbin.

[jconroy]

Thanks for posting @tomalec this is a great overview of your thoughts!

For now, let's follow suit with the current approach (acknowledging there is room to improve) and revisit once we have less time constraints.

[tomalec]

@ecgan

I read that react and custom elements do not work well together

AFAIK, that's the thing with React and any new ES or HTML feature ;) Seems to be the price of any big framework that creates its own platform. I hope it's better now, given, the Web Components are around for ~8years, and for ~3yrs supported in major browsers.

I think that there is a way to put namespace for custom elements like , right? This might help to avoid collision.

<namespace:*> is XML/XHTML thing, and is a separate topic. I think it never got traction and is not very popular. The common and advertised approach to namespace custom elements was the convention to call them, like <ventor-element>, that's one of the reasons why the dash (-) is required for a custom element name. That also guarantees the lac of collision with new native elements that may come in the future, which will be always without dash. (yeah, yeah standard bodies regred, that there are some legacy native elements with dash, (but the Web have to be backward compatible.)

do you know if there is prior art or discussion on this within a8c?

I did some brief research and didn't find anything, If I get more dime, I could dig deeper. I asked @alshakero who is in A8C longer than me and he is very experienced with Web Components as well.

Btw, there is no output in this jsbin.

:( JSBin still have some problems with saving revisions. Is it better now? if not you may try https://jsbin.com/zohewew/4/edit?html,output

[ecgan]

Btw, there is no output in this jsbin.

:( JSBin still have some problems with saving revisions. Is it better now? if not you may try https://jsbin.com/zohewew/4/edit?html,output

Yup, both links are working now! 🙂 👍