Export system for Zeal

[yash-deepsource]

CSS

• We aren't going to ship normalize.css anymore, since @tailwind base takes care of normalization for us.

  Refer: Preflight - Tailwind CSS

• The rationale for adding CSS styling should be as follows:
  • Prefer using @layer w/ components for writing component classes. These styles are directly written inside a component, e.g.:

    <style lang="postcss">
    @tailwind components;
    
    @layer components {
      .z-tag {
        column-gap: theme('gap.2');
      }
    }
    </style>

  • Prefer using @layer w/ utilities for writing custom utilities (a.k.a. tailwind classes).
  • Prefer using arbitary values for one-off things.
  • Only use pure custom CSS, in index.css if none of these use-cases match yours.
• Colors and various base utilities will be configured via exports from Supernova. Ref: Theming in Zeal #4

Vue Files

• Vue files live in the /src/components directory.
• Each component has its own folder that consists of the component file itself and its accompanying child components/building blocks.
• Each directory has an index.ts file that is responsible for exporting all the contents of the directory.

Transpile vs Bundle/Compile

• Currently, we build Zeal completely and serve distribution files to users of the package; along with the tailwind.config.js file.
• This leads to unnecessary confusion when a user imports Zeal to their project; since if they want to take benefit of utilities not used anywhere in the core Zeal package, they have to import the tailwind config. Add it to their own. And, then ensure that their own CSS file also imports our custom CSS file for the PostCSS build to cleanup. Otherwise, it will lead to missing styles in the final builds; as evident in Bifrost.
• Users of Zeal who want customization will usually have their own build pipelines hooked up for their own web apps. Why not let them, import our raw components and let their build system handle compiling and optimizing its contents?
• We can perform a minified build and have a dist version side-by-side if there are users who would prefer to add Zeal over a CDN, for metrics on bundlephobia, etc.
• Let's go for a Transpile + Compile'd build, where power users can import files as-is and can manage their own builds independently.
• mkdist for transpiling and vite for builds.

mkdist also provides some great points in favor of transpiling libraries!

Types

• We will use vue-tsc (Volar's type checker) for type exports.
• It takes tsconfig.json and exports types for your .vue and .ts files automatically.

---

Feedback

I would love to hear feedback on specifics around:

• Although Tailwind specifically suggests against adding CSS on a per-component basis, the approach with PostCSS as a preprocessor for the style block seems to get around the problems mentioned within the article. Does the proposed approach raise any concerns regarding build outputs or code style in your mind?
• As a web app author, do you feel okay with adding a library that leaves bundling up to you and provides you with transpiled source code of the components?
• Any other specifics that you would like to be discussed around exports of Zeal that have been missed or concerns with the current plan?

Let's discuss anything regarding this here. Feel free to create Issues around this and tag the discussion within if required.

[shivam-deepsource]

Does the proposed approach raise any concerns regarding build outputs or code style in your mind?

The only concern here would be maintaining sanity. In the original way, the markup and style always stay together, keeping context switch minimal. The proposed way does not disrupt this in a large way, but is a slippery slope.

For instance, a button tag can have padding, font and color properties. In this example, nothing stops developers from building the classes as btn btn-sm btn-primary, this can quickly get complex for large components with multiple nested dom elements that need to be styled. Reaching this point actually means the only benefit we're getting from tailwind is standardized tokens. This is also not guaranteed, since the logical next convenience will be writing custom styles in those tags for small adjustments like spacing. The broken window theory holds well here

However, the benefits we get from actually writing styles per component basis is worth it IMO, but *we'll have to enforce the rules set out in the CSS section, maybe write macros to enforce it or a custom script that does that. @yash-deepsource what do you think?

As a web app author, do you feel okay with adding a library that leaves bundling up to you and provides you with transpiled source code of the components?

In any other case, say Shifty or Charts, I'd always expect a transpiled and bundled output, ready to be used in the browser as is. But for a component system exclusively meant for the Vue ecosystem, we need not do that. Anyone using Zeal components will bundle their app anyway, adding that step for us is just redundant.

[yash-deepsource]

However, the benefits we get from actually writing styles per component basis is worth it IMO, but *we'll have to enforce the rules set out in the CSS section, maybe write macros to enforce it or a custom script that does that. @yash-deepsource what do you think?

Agreed, we should ensure a few things I think:

• Complex components, with multiple parts, should be built depending on whether the nested doms need to be customizable or not.
  • Even though Vue 3 allows multiple elements as root elements, it still requires defining which single component will inherit the classes, etc. passed to it by its parent. In this case, as well, we only need to use the component layer for the customizable element. The rest of the elements can stay true to atomic CSS principles and keep things inline.
  • In the case of the respective nested DOM elements requiring their own customization, we should build them in a way where they aren't a single component but peer/child components that work together to create a fully functioning component. E.g. <Accordion/> and <AccordionItem/>.

These things should largely prevent such an issue from occurring, but we should definitely work on a Macro or a StyleLint rules that automate this process for us. What do you think?