393 cbyrd vue component guidance

[chrabyrd]

brief description of changes

issues addressed

further comments

---

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

[jacobtylerwalls]

This is really helpful, Christopher. I know other developers will appreciate having this walkthrough.

I don't have any concerns, just some follow-up questions to take this even further.

[jacobtylerwalls]

I'd love to get a .prettierrc in place as soon as possible so we can standardize on:

• single vs. double quotes
• 2 vs. 4 spaces
• line-length

And have a github action step fail PRs that haven't been formatted. Then we can socialize the knowledge about how to configure "format on save" in VS Code so that you never have to hand-format again. (Separately, I'll suggest doing the same thing with the python backend because we seem to get lots of PRs with unrelated formatting changes on a regular basis...)

I don't have a strong preference about quote or indentation width myself.

[jacobtylerwalls]

archesproject/arches#10575

[jacobtylerwalls]

This example is perfect. There's nothing else that makes sense.

In a more contrived example, you end up with more options about where to shove things. If there are a lot of arrow functions, you can group them all together, or you can keep the setter right next to where the state is declared. (Kind of like const [count, setCount] = useState(0); in React.)

In other words, a more contrived example might look like (knowing full well that the worse this gets the more it signals some decomposition is called for 😉 ):

<script setup lang="ts">
import { ref } from 'vue';  // third-party import
...

import { FancyButton } from 'primevue'; // will be a handful of these
...

import "MyComponent" from "@...";  // first-party import
...

import type { ApiResponse } from "@types/...'; // types
...

const LIMIT = 42; // constants

const [prop1, prop2]: {prop1: number, prop2: string} = defineProps(["prop1", "prop2"]);  // props
const toast = useToast(); // hooks
const count = ref(0);  // state
const otherReactiveState = ref([]);  // even more state
...

const formattedValue = computed(() => { // this is a lot like state...
...
});

const increment = () => { // begin arrow functions....
...

const onClick = () => {
...

const onReorder = () => {
...

const fetchData = async () => {
...

await fetchData();  // initialization code

Again, this is testing the edges of too-much-in-one-file, but I think it's not far from realistic (a couple of pieces of reactive state, a couple of callbacks, data fetching, and a toast for error handling)

These are all debatable, but what do you think about:

• Imports at top, whitespace between 3rd party and 1st party, optionally around primevue imports
• Import types last
• static constants, then props, then reactive state, then computed/watch, etc.
• functions mutating state declared right after state
• otherwise arrow functions toward the bottom
• any calls to those functions at the very end

[ryan86]

Should each category also be alphabetized? Static consts A-Z, props A-Z, functions A-Z, etc?

[ryan86]

Also, maybe additional category for vue lifecycle hooks unless we want to include them with arrow functions?

[jacobtylerwalls]

@ryan86 👋

alpha'ing constants and callbacks seems like overkill to me in my experience. 🤷‍♂️

[jacobtylerwalls]

Nice example. Foo!

[Off topic] By the way, do you happen to know what procedure compiles strings for translators? Do they get de-duped between the frontend and backend the way they do now? E.g.:

arches/location1.py
arches/location2.py
arches/app/media/js/blah.js
arches/app/src/components/BarReport/BarReportHeader.vue
arches_for_science/plugins/whatever.py
===
BAR!

[chrabyrd]

👋 @jacobtylerwalls

As far as the vue3-gettext implementation is concerned, it's on a per-filetree/project basis. Essentially the path value in gettext.config.js can only accept a single directory. I've not dug in enough to know if there's de-duplication at the filetree/project level but that will be interesting to explore

[ryan86]

If Header, Bio, and Actions are all imported into UserProfile.vue what goes in UserProfileView.vue?

[chrabyrd]

👋 @ryan86

UserProfileView.vue is a higher-order component. It's purpose is to bring together the lower-order components and maybe some window dressing around them. eg

<script setup>
import { ref } from 'vue';
import UserProfileHeader from './UserProfileHeader.vue';
import UserProfileBio from './UserProfileBio.vue';
import UserProfileActions from './UserProfileActions.vue';

const user = ref({
  name: 'John Doe',
  email: '[email protected]',
  bio: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit.'
});
</script>

<template>
  <div>
    <UserProfileHeader :name="user.name" :email="user.email" />
    <UserProfileBio :bio="user.bio" />
    <UserProfileActions />
  </div>
</template>

[jacobtylerwalls]

Noticed we'll have to silence the vue warnings for this:

[Vue warn]: Property 'items' was accessed via 'this'. Avoid using 'this' in templates. 

And it's too bad that JS variables in <script setup> now show as unused in VS Code. Maybe the tooling will catch up.

In vue 3.4+ (once the tooling catches up, b/c I don't seem to be able to use it now), we might be able to prefer:

:items

instead of:

:items="this.items"

Thoughts?

[chrabyrd]

I'll definitely look into this, it might be preferable to amend the current documentation to prefer the shorthand -- I'm not against the notion 👍