Créer un nouveau composant

Orion fournit une simple interface de ligne de commande pour améliorer l'expérience développeur au moment de contribuer au projet.
Ce cli va se charger de construire un nouveau composant en créant les fichier nécessaires dans les bons dossiers.

Ne vous inquiétez pas, nous utilisons une architecture assez courante avec seulement un léger changement dans le script que nous allons expliquer juste après.

Notre philosophie de conception de packages

Le design est assez basique et suis le schéma ci dessous.

Garder le code clair

Le code est divisé en 3 fichiers.

Améliorer l'expérience développeur

Comme dit plusieurs fois, nous tenons à l'expérience développeur. C'est pour l'une de ces raisons que nous avons choisi de mettre toute la partie script dans une class typescript dédiée pour chaque composant.

Ce modèle de conception rend l'utilisation de class et d'héritage beaucoup plus simple. Cela contribue également à maintenir un code propre, même à l'intérieur d'un template.

Vous vous demandez comment c'est possible ?

Il suffit juste d'utiliser des attributs private ou protected dans votre classe SetupService pour les empêcher d'être accessibles depuis le template.
Par exemple si vous utilisez VSCode, vous aurez un Intellisense plus propre. Cela permet de réduire le nombre d'erreurs et la complexité du code lors du développement de votre application.
Mais regardons un exemple plus concret.

Le processus de création de composant

Nous ne voulons pas ennuyer les développeur avec une convention de nommage et une structure de fichier. C'est pourquoi nous avons créé un petit cli pour rendre ce processus plus simple.

# À la racine d'Orion
node cli.cjs

Choisissez l'option package.

┌  
🥨 --> Welcome to Orion CLI
│
◆  Select what you want to do
│  ○ Volar Intellisense
│  ● New package (Scaffold a new package)
│  ○ Create packages index
│  ○ Create services index
│  ○ Create sandbox routes
│  ○ Build lib
│  ○ Create doc's data files
└

Entrez ensuite le nom de votre paquet.

┌  
🥨 --> Welcome to Orion CLI
│
◇  Select what you want to do
│  New package
│
◆  What's the name of your package?
│  Package name
└

┌  
🥨 --> Welcome to Orion CLI
│
◇  Select what you want to do
│  New package
│
◇  What's the name of your package?
│  draft
│
◆  🥨 --> Orion created /packages/Draft/index.ts
│
◆  🥨 --> Orion created /packages/Draft/src/OrionDraft.vue
│
◆  🥨 --> Orion created /packages/Draft/src/OrionDraft.less
│
◆  🥨 --> Orion created /packages/Draft/src/OrionDraftSetupService.ts
│
◆  🥨 --> Orion created /docs/components/OrionDraft.md
│
◆  🥨 --> Orion created /packages/index.ts
│
◆  🥨 --> Orion created /lib/packages.d.ts
│
◆  Enter the prefix for Orion components?
│  o_
└

La commande volar est exécutée automatiquement pour récréer le fichier orion-volar.d.ts avec votre nouveau composant (plus d'info sur la commande volar).

Fichiers packages

La structure des dossiers suivante sera générée avec la commande package.

<template>
	<pre>OrionDraft</pre>
</template>

<script setup lang="ts">
import './OrionDraft.less';
import OrionDraftSetupService from './OrionDraftSetupService';
const props = defineProps(OrionDraftSetupService.props);
const setup = new OrionDraftSetupService(props);
defineExpose(setup.publicInstance);
</script>

import SharedSetupService from '../../Shared/SharedSetupService';
import SharedProps from '../../Shared/SharedProps';

type Props = SetupProps<typeof OrionDraftSetupService.props>;

export default class OrionDraftSetupService extends SharedSetupService<Props> {
	static props = {};

	constructor(props: Props) {
		super(props);
	}
}

@import '../../Shared/styles/variables.less';
@import '../../Shared/styles/mixins.less';

.orion-draft {
}

Structure des paquets

Documentation

Une fois que vous avez créé votre nouveau composant, n'oubliez pas d'ajouter une documentation.

La commande package a également créé le fichier suivant : /docs/components/OrionDraft.md

Il est difficile d'écrire une documentation, mais faites de votre mieux en expliquant simplement comment fonctionne le composant, quand il peut être utilisé, et quelles situations spécifiques il peut gérer.

Démos

Comme vous l'avez probablement remarqué, chaque paquet comprend un dossier docs. Il contiendra les fichiers .vue pour chaque démo ou playground que vous voulez voir apparaître dans la documentation.

Nous avons créé un plugin Vuepress/Markdown pour intégrer facilement ces démos dans les fichiers markdown.

À la suite de votre code, il est possible d'ajouter une description concernant la démo. Pour cela, utilisez le marqueur @lang: suivi d'une des langues supportées dans la documentation (en pour l'anglais est nécéssaire).

Prenons par exemple la documentation d'OrionButton, vous y trouverez ces lignes:

::: demo:Button
ButtonColors
ButtonIcons
ButtonPlayground
:::

La première ligne correspond au marqueur qui va indiquer au bundler d'intégrer les démos à ce niveau.
Lors du parsing des fichiers sources, la regex cherchera l'expression suivante : ::: demo:
Si nous prenons l'exemple de notre composant Draft :

::: demo:Draft

Ensuite il suffit de spécifier quelle démo vous souhaitez insérez (en écrivant le nom du fichier) :

::: demo:Draft
DraftDemo1
DraftDemo2
DraftDemo3
::: <!-- ne pas oublier de fermer le marqueur de démo avec ::: -->

Puis dans le fichier .vue la description prendra cette forme à la fin du fichier

@lang:en
### Titre de votre démo

La description de votre composant
@lang

Ajouter votre documentation dans le menu

La dernière étape consiste à ajouter un lien de la page de documentation au niveau de la sidebar.
Ajoutez le chemin correspondant à votre fichier dans l'une des parties children dans le fichierdocs/.vuepress/configs/sidebar/index.ts. La bonne position dépendra de la catégorie de votre composant.