feat: ESDS 3.0 release based on Vue 3 and PrimeVue

[ericdouglaspratt]

🔗 Linked issue

• https://energysage.atlassian.net/browse/CED-1339

❓ Type of change

• 📖 Documentation (updates to the documentation or readme)
• 🐞 Bug fix (a non-breaking change that fixes an issue)
• 👌 Enhancement (improving an existing functionality like performance)
• ✨ New feature (a non-breaking change that adds functionality)
• ⚠️ Breaking change (fix or feature that would cause existing functionality to change)

📚 Description

• New es-ds-components package that is a Nuxt layer package and contains the PrimeVue config for downstream Nuxt 3 applications, as well as all related components
• New es-ds-docs folder that contains a Nuxt 3 app to power the new design system documentation site
• Local development and hot reloading are now much faster and simpler; the necessary linking and dev server initialization can be accomplished with a single command: make dev

🥼 Testing

• Tested on the new local docs site

🧐 Feedback Requested / Focus Areas

• Overall

📝 Checklist

• I have linked an issue or discussion.
• I have updated the documentation accordingly.
• I have documented testing approach

[ericdouglaspratt]

@tomleo The basic "hello world" foundation should be ready for a review now. Keep in mind, as per the ticket description, that the scope of this stage is:

1. create a feature branch
2. create the es-ds-components folder and package as a Nuxt layer
3. create the es-ds-docs folder, put a starter Nuxt 3 app in there, hook it up to es-bs-base and es-ds-components, and make sure hot reloading works for local development

I'm particularly interested in any feedback on the names of the makefile commands (make dev vs. make legacy-dev) and how we can best preserve the old packages' commands in case we need to do a hotfix (more worried about that in the Lerna case actually, which isn't set up yet for the new thing), while keeping it simple to run the new 3.0 design system locally and publish it.

And this PR will remain open for a while (so no need to fully approve it), as it represents the feature branch we'll work against. But worth reviewing what's there so far and any concerns. I've created or will create separate tickets for setting up the initial content in the docs site along with PrimeVue, Jest testing, linting, prettier, simultaneously publishing to NPM via Lerna, etc, as some of those can be done in parallel with developing PrimeVue components.

[mpleroux]

I get this error when running make dev after going through the usual build steps for es-ds. Is it looking for an npm package that doesn't exist yet?

mike@redtail es-ds % make dev   
npm --prefix es-bs-base link

up to date, audited 3 packages in 445ms

found 0 vulnerabilities
npm --prefix es-ds-components link

up to date, audited 3 packages in 275ms

found 0 vulnerabilities
cd es-ds-docs; npm link @energysage/es-bs-base @energysage/es-ds-components
npm ERR! code E404
npm ERR! 404 Not Found - GET https://registry.npmjs.org/@energysage%2fes-ds-components - Not found
npm ERR! 404 
npm ERR! 404  '@energysage/es-ds-components@*' is not in this registry.
npm ERR! 404 
npm ERR! 404 Note that you can also install from a
npm ERR! 404 tarball, folder, http url, or git url.

npm ERR! A complete log of this run can be found in: /Users/mike/.npm/_logs/2024-07-26T16_47_07_229Z-debug-0.log
make: *** [dev] Error 1

[hroth1994]

I get this error when running make dev after going through the usual build steps for es-ds. Is it looking for an npm package that doesn't exist yet?

mike@redtail es-ds % make dev   
npm --prefix es-bs-base link

up to date, audited 3 packages in 445ms

found 0 vulnerabilities
npm --prefix es-ds-components link

up to date, audited 3 packages in 275ms

found 0 vulnerabilities
cd es-ds-docs; npm link @energysage/es-bs-base @energysage/es-ds-components
npm ERR! code E404
npm ERR! 404 Not Found - GET https://registry.npmjs.org/@energysage%2fes-ds-components - Not found
npm ERR! 404 
npm ERR! 404  '@energysage/es-ds-components@*' is not in this registry.
npm ERR! 404 
npm ERR! 404 Note that you can also install from a
npm ERR! 404 tarball, folder, http url, or git url.

npm ERR! A complete log of this run can be found in: /Users/mike/.npm/_logs/2024-07-26T16_47_07_229Z-debug-0.log
make: *** [dev] Error 1

I got this error too.

[mpleroux]

After reviewing the contents of this PR more I now understand it's not meant to be run until the es-ds-components package exists. I familiarized myself with the files and I don't have any specific feedback right now.

[ericdouglaspratt]

Yeah I'm not entirely sure why that error happens - my first assumption was that it was because I hadn't given you an install command to run - I've now updated make install to run npm install on the newer folders - maybe that's necessary first.

If running make install and then make dev still doesn't work, maybe we can debug on Monday, because it works for me (originally, admittedly after manually running npm install in each folder separately, which make install should now be able to accomplish for you). And it's true the es-ds-components package doesn't exist on NPM, but if the local linking is working correctly, it shouldn't have to yet.

It could be because es-bs-base is listed first in the npm link command, so it tries to NPM install all the other packages including es-ds-components as part of that first step, and can't find it. I wonder if changing the order in the Makefile so that es-ds-components is first would help.

[ericdouglaspratt]

@mpleroux @hroth1994 I just published @energysage/es-ds-components to NPM and properly added it to the package.json of es-ds-docs - can you try again?

[hroth1994]

@mpleroux @hroth1994 I just published @energysage/es-ds-components to NPM and properly added it to the package.json of es-ds-docs - can you try again?

make install and make dev works now but I'm seeing a ton of these warnings:

[ericdouglaspratt]

Yeah I'm seeing those too; the newer version of SASS we're using is just saying some stuff is deprecated and should be cleaned up at some point. A full refactor of es-bs-base is a bit out of scope for this project, though I can make a ticket to have a look if we can clean it up because it makes it tougher to see other errors.

[mpleroux]

I have the same experience. I can run it locally and see the messages from App.vue and TestComponent.vue.

[mpleroux]

After reading the Sass page about those Mixed Declarations warnings it doesn't look like an easy fix. Declarations could be reordered within a single file, but conflicts between two files may require restructuring some of Bootstrap's SCSS:

   ┌──> ../../../.nodenv/versions/18.19.1/lib/node_modules/@energysage/es-bs-base/scss/_custom-forms.scss
501│       appearance: none;
   │       ^^^^^^^^^^^^^^^^ declaration
   ╵
   ┌──> ../../../.nodenv/versions/18.19.1/lib/node_modules/@energysage/es-bs-base/scss/mixins/_transition.scss
24 │ ┌       @media (prefers-reduced-motion: reduce) {
25 │ │         transition: none;
26 │ │       }
   │ └─── nested rule

I was wondering how Bootstrap themselves were handling it and their solution seems to be... downgrading Sass from 1.7.7.8 to 1.7.7.6? 🤦

[nathanielwarner]

Nice work on this! I'm glad you were even able to get the Prism source code viewing working.

Regarding the SASS deprecation warning, I don't know why we didn't encounter this before in the POCs. But in any case, I'm not sure it's that complex.. I left a comment on the ticket.

I also wonder whether we should be maintaining the old repos (es-vue-base and es-design-system) within this repo. es-vue-base would be broken if we remove styles from es-bs-base that are specific to the BootstrapVue implementation. It seems like we could keep the old design system as a branch instead.

[nathanielwarner]

Sort of a nit: I'm not sure we should encourage using PrimeVue components that are not part of the design system. We should at least warn people that they're gonna be unstyled

[nathanielwarner]

Noting that BootstrapVue's implementation for this and other layout components is a bit more complex, and supports other props including offset and order as specified in their docs. Do you think we should try to support those props as well? I think the approach you've followed is clearer and has less "magic" than how BootstrapVue does it.

[ericdouglaspratt]

For the final release, probably. I think we and others may be using those props in a few places, but worth a look at how complex it gets.

My main initial goal was to unblock the new design system docs site.

[nathanielwarner]

That makes sense yeah

[nathanielwarner]

Do you know what this is/why it's necessary? (ditto for analogous files) I tried deleting this file and referencing @energysage/es-bs-base/scss/variables/_blues.scss from es-ds-docs/pages/atoms/color.vue as was previously done, and that seemed to work fine

[ericdouglaspratt]

Interesting - when I initially tried it that way, it was coming in as a raw string rather than an object, so I searched around and found this discussion thread that offered some potential solutions.

I just tried switching the import path back to the old file locally and my dev server won't even load the Colors page now - it just hangs.

[nathanielwarner]

You restarted the dev server? And your node --version is 18.19.1?

[ericdouglaspratt]

I started it from scratch after making the change, yeah. I'm running node 18.12.0.

[nathanielwarner]

Maybe we can troubleshoot that together. Since the .node-version in this repo is 18.19.1, Nodenv should automatically put you on that when you're running node or npm from this directory. I'm guessing if you run which node, you see something other than /Users/yourname/.nodenv/shims/node

I don't know if that's the reason you're encountering this issue, but behavior does change between Node versions, especially the major releases.

[nathanielwarner]

Ohhh ok never mind. I'm actually getting the same error when I go specifically to http://localhost:8500/atoms/color. It's strange that it's only a client-side error.

[nathanielwarner]

Part of what Nuxt Layers allows is to specify this sort of thing in the design system package, rather than in downstream repos. Is there a reason you put the options other than extends here rather than in es-ds-components?

[nathanielwarner]

Also noting that the previous design system imported bootstrap.import rather than just bootstrap. I'm not sure if there's implications to that.

[ericdouglaspratt]

Fair! Having the es-bs-base include come for free with the es-ds-components Nuxt layer would be easier.

Not sure of the difference between bootstrap and bootstrap.import - I see a @forward directive in bootstrap.import, but not sure that's necessary as I don't think we need to make any variables or mixins available in any SCSS we write "after" the inclusion of bootstrap as there is none, it's passed straight to Nuxt to do a SASS build. In Vue components, I'd expect we still have to do the direct imports of breakpoints and variables as we did before.

[swarmia]

✅  Linked to Task ESDS-3 · es-bs-base@0.1.0 creation