@alhena/components NPM

Gemini 2 Alhena Components (@alhena/components)

About the code name
Getting started
How to write components - rules and best practices
Local publishing for development
TL;DR: How to create this project

About the code name

The whole thing is called Gemini 2 (an official name). The frontend project has a codename Alhena /ælˈhiːnə/, which is one of the stars in the constellation Gemini (still wondering? see wiki). This project contains just some VUE components.

Getting started

This project contains VUE components for Gemini 2 Alhena frontend.

It was created as Quasar project by Quasar Cli, but we don't build a Quasar project (however the possibility is still here). We use Strorybook instead. Storybook is something like catalog of our components, as well as a test place.

Project can be published by standard npm commands (see bellow). We don't use any packer for publishing; the components are packed without any processing. It has one big advantage, we can use all Quasar SCSS variables. And one big disadvantage, we must only use these component in Quasar projects.

Scripts:

use yarn command for installation
yarn storybook opens storybook in reactive mode
yarn build-storybook compiles static build of storybook - great for a presentation.
There are some others scripts for linting and formatting. As I said before, you can run quasar dev, but no application is intended to be here.

How to write components - rules and best practices

Prerequisites

You know how Strorybook works - read the doc carefully.
You know how to publish this project in our local repository (see bellow).
...and, of course, some basic skills...

Structural rules

When you should place your component in this project?
- your component is to be used many times in a final project; create it even it is for example a small customization of a Quasar component
- your component is complex, and you need a playground for testing; even it is used just ones in one final project.
Keep your component as simple as possible. Components should contain just the visual logic. See Coding rules.
Organise components in directories; accordingly use title description in your *.stories.* files. Don't hesitate to reorganise the whole project if you find it messy.

Coding rules

use Composition API with script setup in all VUE files
styles:
- use scoped SCSS, i.e. <style lang="scss" scoped> in all VUE files
- you can use global SCSS variables and styles from src/css/app.scss and src/css/quasar.variables.scss files - in the final project will be used variables and styles of the final project instead
- please keep the above files in sync for your convenience.
Don't code any outer logic (stores, API) here! Components should contain just the visual logic. For all other logic (using stores, API calls etc.) use a wrapping component in the final application, like <template> <your-component /><template>. Use args in its *.stories.* file instead.
comments: please, for our sanity...:
- spend some time and your brainpower describing your file - what it is for, how it works, and why it is actually here
- use JSDoc for any function, whose meaning isn't clear at first glance
- inside functions: even though you're convinced that your magic code must be clear to everyone, make a comment for the rest of the world

Naming conventions

file names
- use prefix "Ac" for all components here (like Quasar uses "Q")
- use pascal case, like AcButton
styles
- use kebab case for styles, like last-warning
- if you place a style in global SCSS files (app.scss or quasar.variables.scss), use prefix "a-", like a-last-warning
variables
- use camel case, like arrayLength
- please, use descriptive variable names, without any crippling abbreviation - like countOfYellowJackets instead yelJacX; don't hesitate to rename the variable if you change the logic, and don't be scared of long names

Local publishing for development

TODO

TL;DR: How to create this project

You should only read this part if you are going to create this project again from the scratch.

Written with help of https://dev.to/allanjeremy/using-quasar-with-vue3-storybook-4dl8

I couldn't get it to work using Vite instead WebPack - there was probably conflict between Vite versions in Quasar CLI (v2) and in Storybook (v3). I gave up and used WebPack :-( however Vite would be better for many reasons.

Create a new Quasar project
```
yarn global add @quasar/cli
yarn create quasar
```
...and set these values:
- What would you like to build? » App with Quasar CLI, let's go!
- Project folder: ... alhena-components
- Target directory "alhena-components" is not empty. Remove existing files and continue? ... yes
- Pick Quasar version: » Quasar v2 (Vue 3 | latest and greatest)
- Pick script type: » Typescript
- Pick Quasar App CLI variant: » Quasar App CLI with WebPack
- Package name: ... alhena-components
- Project product name: (must start with letter if building mobile apps) ... Gemini 2 Alhena Components
- Project description: ... VUE components for Gemini 2 Alhena frontend
- Author: ... rp roman.plischke@aveco.com
- Pick a Vue component style: » Composition API with script setup
- Pick your CSS preprocessor: » Sass with SCSS syntax
- Check the features needed for your project: » ESLint, Vue-i18n
- Pick an ESLint preset: » Prettier
...and then Install project dependencies? (recommended) » Yes, use yarn
cd <your project directory> OR open it in IntelliJ
yarn set version stable for version 3.3.1 or greater
yarn (it sets yarn in a compatible mode using "node_modules" directory, see "nodeLinker: node-modules" in .yarnrc.yml)
Initialize Storybook:
- npx storybook init
- ...if ESLint selected, answer Yes to 'eslintPlugin' migration question (it installs eslint-plugin-storybook).

Update your Storybook settings, .storybook/preview.js file

import '@quasar/extras/roboto-font/roboto-font.css';
// These are optional
import '@quasar/extras/material-icons/material-icons.css';
import '@quasar/extras/animate/fadeInUp.css';
import '@quasar/extras/animate/fadeOutDown.css';
import '@quasar/extras/animate/fadeInRight.css';
import '@quasar/extras/animate/fadeOutRight.css';

// Loads the quasar styles and registers quasar functionality with storybook
import 'quasar/dist/quasar.css';
import { app } from '@storybook/vue3';
import { Quasar } from 'quasar';

// This is also where you would set things up such as pinia for storybook

app.use(Quasar, {});

export const parameters = {
  actions: { argTypesRegex: '^on[A-Z].*' },
  controls: {
    matchers: {
      color: /(background|color)$/i,
      date: /Date$/,
    },
  },
};