Adds Vue Styleguide #481

[chrabyrd]

brief description of changes

Adds Vue Style Guide, majorly changes Vue Integration Guide.

issues addressed

#481

---

This box must be checked

• the PR branch was originally made from the base branch

This box should be checked

• after these changes the docs build locally without error

This box should only be checked you intend to follow through on it (we can do it on our end too)

• I will cherry-pick all commits in this PR into other branches that should have them after this PR is merged

[chiatt]

This looks really great @chrabyrd. Just a couple of minor comments.

[ekansa]

This is awesome! I just noted a few places where it would be helpful to have a little explanation about why a given good practice should be followed. Otherwise, this looks looks great and it'll be a key help for the community!

[jacobtylerwalls]

Thank you!!

I'll do my best to start following this :-)

[jacobtylerwalls]

On the projects you and I are working on right now, we have the luxury of writing as-svelte-as-we-can endpoints to deliver just-what's-needed. But I think not everyone will have that luxury.

Should we (briefly) advise to not go too far in the other direction, e.g. have a dozen children all fetching an identical response?

[chrabyrd]

Hmm this is a tough one. We do expect to have dozens of children hitting endpoints with identical responses. Eg widget config fetching, section data fetching, etc.

[jacobtylerwalls]

Given that design, it's probably a sign we need to make sure we're sending appropriate cache headers. I think downstream caches will assume GET's are safe to cache, and if we have a bunch of perms-filtering logic, we need to clarify that with the correct headers.

[jacobtylerwalls]

I think there usability/accessibility reasons we wouldn't want horizontal space and borders to scale with the font size, as argued here.

Whatever we land on, would be nice to get it enforced with stylelint or similar pre-commit hook, happy 2 help with this one 👍

[apeters]

I've read that same article and I think it makes some salient points about how "rem" everywhere might not make sense especially considering accessibility.

[chrabyrd]

Let's table this for the moment, and loop back around after everything else settles. There is definitely discussion to be had here.

[apeters]

How about then/except?

Suggested change

	- Wrap all async operations in `try/catch`, and surface or display errors appropriately.
	- Wrap all async operations in `try/catch` or `then/except`, and surface or display errors appropriately.

[chrabyrd]

where are you seeing a working JS pattern that uses except?

[jacobtylerwalls]

I think Alexei meant catch(), which means he thought you meant try/except, which means he didn't catch (ha) that you were intending to refer to both try and .then().catch() -- I take his point we could reword slightly to avoid this potential confusion

[apeters]

where are you seeing a working JS pattern that uses except?

Thanks @jacobtylerwalls , yeah, I did mean catch (python confusion there...) I think what I was pointing out was that .then().catch() can be used as an alternative way to provide error handling for async functions.

Maybe what that really means is that this rule should emphasize the requirement to always handle for errors rather than be prescriptive about how you do it.

[apeters]

I would prefer that 9 and 10 are reversed. Lifecycle hooks trigger/use all of the above. Those things tend to be the thing I know is the last part in the script tag. Even though I "get" function hoisting, I still naturally think about functions as being declared above the things that call them.

This also aligns with most code examples I've seen in the Vue docs themselves.

[chrabyrd]

This is something I feel pretty strongly about. The reason for this ordering is to support the 'big picture' flow of components. If I'm attempting to understand a new component, knowing when it does things is more important important information than how. Also we already have components that have hundreds of lines of functions, which I don't want to scroll through to get to the hooks. And conversely, would you expect defineExpose, defineEmits, watch-ers, and computeds to be declared below functions as well? As they can also use declared functions.

[jacobtylerwalls]

I find @chrabyrd's argument convincing, and @apeters I wonder if this fades into the background a little bit given the potential we might be using onMounted less for fetching, see here

[apeters]

Examples in the Vue docs have lifecycle hooks as the last items in the script tag, and we, ourselves, tend to do that as well when I review what we've done in the past. I was really expressing a preference. But then this is what this whole exercise is about.

[apeters]

All in all, this looks great @chrabyrd ! Thanks for putting in so much thought, care, and hard work into this! Even though I have a couple of nits, I'm so grateful that you put this out there 🙏

[chrabyrd]

note -- this add vue-lexer as a requirement. It'll need to be installed

[jacobtylerwalls]

Thanks for adding, I'm digging this now 👍

[ekansa]

Agreed! This is super helpful!

[jacobtylerwalls]

Seems to not follow 8-10 below which do 3rd party, 2nd party (arches apps), 1st party

[ekansa]

@chrabyrd @jacobtylerwalls @apeters How are we feeling about this PR? Should we wait until you all catch your breath after the v8 release? I'm happy to look at it again, but I don't want to distract you all right now.

[ekansa]

@chrabyrd just checking in about this. How are things going with this update? Is there anything I can review, or otherwise help with?

[chrabyrd]

👋 @ekansa

Good question! Just been busy of late. Lemme give this a once-over and get back to you 👍