npm package: @alhena/components
Description: VUE components for Gemini 2 Alhena frontend
Author: Roman Plischke
Latest version: 1.0.9
Deprecated: Package no longer supported. Contact Support at https://www.npmjs.com/support for more info.

# Gemini 2 Alhena Components (@alhena/components)
<!-- TOC -->
  * [About the code name](#about-the-code-name)
  * [Getting started](#getting-started)
  * [How to write components - rules and best practices](#how-to-write-components---rules-and-best-practices)
    * [Prerequisites](#prerequisites)
    * [Structural rules](#structural-rules)
    * [Coding rules](#coding-rules)
    * [Naming conventions](#naming-conventions)
  * [Local publishing for development](#local-publishing-for-development)
  * [TL;DR: How to create this project](#tldr--how-to-create-this-project)
<!-- TOC -->
## 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](https://en.wikipedia.org/wiki/Gamma_Geminorum)). 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](https://quasar.dev/start/quasar-cli), but we don't build a Quasar project (however the possibility is still here). We use [Strorybook](https://storybook.js.org/) 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](https://storybook.js.org/) 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](https://vuejs.org/guide/extras/composition-api-faq.html#what-is-composition-api) in all VUE files
- **styles:**
  - use scoped [SCSS](https://sass-lang.com/documentation/syntax#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](https://storybook.js.org/docs/vue/writing-stories/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](https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html) 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

  ```bash
  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

  ```javascript
  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$/,
      },
    },
  };
  ```

- add two properties in `package.json`:
  - "main": "path/to/index.ts",
  - "module": "path/to/index.ts",

- now storybook should work, run `yarn storybook`