Contribution Guide ​

I use pnpm for my OpenSource projects. I also use yarn & npm as well, just like you. So, I highly recommend using ni.

We will use ni's commands in the following code snippets. If you are not using it, you can do the conversion yourself: ni = pnpm install, nr = pnpm run.

To set the repository up:

nr dev

It will start development mode for Anu package. It will start the build process in watch mode.

nr docs:dev

It will start VitePress development server for documentation. Within few seconds you will get the link to run documentation. You can use this as playground.

nr clean

It will remove the node_modules directory from workspace root and all the packages.

VS Code is recommended editor for this project. There's nice configurations in .vscode along with other editor related config files which will setup your editor according to project.

Recommended Extensions ​

Install & enable recommended extensions by following this guide.

Comment Anchors ​

I heavily use comment anchors extension in all of my projects for quick navigation within file.

I highly recommend reading the README of this extension to get the idea of how to use it. This is great time saver and will take 2-3 minute reading.

Anchors ​

Below is list of anchors we can use in this project. You can get list of snippet for anchors by pressing ctrl+space and searching for cm-.

👉 (cm-hand-emoji) ​

I use this emoji to anchor a line. This is for highlighting some code block or navigating to regularly visited line.

I use this for dividing my file in small chunks and labeling code blocks.

ℹ️ (cm-info-emoji) ​

I use this emoji to remind/inform other contributors or myself about some specific code I have written so I don't get question like "Why the hack, I wrote this code?" later on.

I use it to comment intermediate or complex code.

❗ (cm-warning-emoji) ​

I use this emoji to warn other contributors or myself about some danger. I rarely use it. It is useful in letting others know to be careful here.

I use it to indicate be very careful with whatever you do with code next to it

No Prettier ​

Since ESLint is already configured to format the code, there is no need to duplicate the functionality with Prettier. To format the code, you can run na eslint --fix or referring the ESLint section for IDE Setup.

If you have Prettier installed in your editor, we recommend you disable it when working on the project to avoid conflict.

Required ​

• Anu provides preset named "Theme Default" where all appearance related classes should be written. Idea is someone can create his own preset to totally customize the look & feel of Anu.
• For structural & functional styles, you better write them in component itself.
• If you are creating new component please make sure to follow the pattern we used in other components. Additionally, Make sure to use as const for slots like below:

export const aTabsSlots = {
  default: (_: { name: any }) => null as any,
} as const

Optional ​

• For dummy text instead of Lorem ipsum, you can use cupcakeipsum which is pretty sweet 😋
• Try to follow Python Zen. Here's post with nice examples.

Design ​

At the moment, anu don't have any design system. Hence, we have full freedom to design the component we like. However anu's UI should follow some basic stuff:

• It should be minimal
• Alignment matters
• Prefer outline icons instead of solid icons
• transitions & animations are nice to have (Don't use fancy animations, it should look professional)

CSS vars ​

We follow naming convention for CSS color vars. As we have theme colors CSS vars that has just HSL value and not full color (e.g. --a-primary: 265, 97.7%, 66.3%) and some other colors that are full color (e.g. --a-switch-icon-color: hsla(0, 10%, 20%, 0.68)), it's confusing while using the CSS var to identify if it's full color or just HSL value.

Due to this reason we follow below convention when deciding the name of CSS var that is color:

• suffix -c => For just HSL value (--a-base-c: 0, 10%, 20%;)
• suffix -color => For full color (--a-switch-icon-color: hsla(0, 10%, 20%, 0.68))
• Don't suffix anything => For theme color (--a-primary: 265, 97.7%, 66.3%)

With above naming convention, we can clearly know if we should wrap the CSS var in hsl() or directly use it like a color value.

Template Refs ​

In Anu, we follow below convention for template refs:

• variable that holds template ref should be prefixed with ref. e.g. refInput, refMenu, etc.
• Try to assign type for template ref variable. e.g. refWrapper: Ref<HTMLDivElement | undefined> = ref()

Creating new component ​

First of all, it is advisable to discuss the design & features of the component by opening the new issue. E.g. New component: Menu

For creating new component,

1. Create new folder with the name of the component in packages/anu-vue/src/components
2. Create component with .vue extension (we'll only use .ts or .tsx in special cases)
3. Create meta.ts file and define props, slots & events for the component.
4. Create index.ts file like other components and export stuff like meta, component, etc. (You can check other component's index.ts file and update accordingly.)
5. Export newly created component in packages/anu-vue/src/components/index.ts file so it can be registered globally

Once you have this setup, create docs page for this component in packages/documentation/docs/guide/components

Add the newly created docs page to the sidebar of the docs in packages/documentation/docs/.vitepress/config.ts

For demo you need to create a new demo file in packages/documentation/docs/demos/<component-name>. Make sure to follow the naming convention (Demo<component-name><demo-name>) for creating demo so that it doesn't conflict with other demo file. This is because these files will be globally registered as components in VitePress so we can use them in markdown easily.

Now, we have component, its documentation page and single demo.

For creating a demo use card container (You can refer to other component docs).

::::card <demo-title> <!-- This is title of demo -->

:::code <demo-file> <!-- This will render the demo -->
<<< <path-to-demo-file> <!-- This will add code snippet for the demo -->
:::

Make sure you are add snippet of the same demo you rendered.

For better UX you can highlight the lines in demo snippet as we done in other components.

API ​

Make sure to write the API of the component correctly so it can be auto generated by vue-component-meta

Please refer to its README for details.

Discuss first ​

Before you start to work on a feature pull request, it's always better to open a feature request issue first to discuss with the maintainers whether the feature is desired and the design of those features. This would help save time for both the maintainers and the contributors and help features to be shipped faster.

For typo fixes, it's recommended to batch multiple typo fixes into one pull request to maintain a cleaner commit history.

Commit convention ​

We use Conventional Commits for commit messages, which allows the changelog to be auto-generated based on the commits. Please read the guide through if you aren't familiar with it already.

Only fix: and feat: will be presented in the changelog.

Note that fix: and feat: are for actual code changes (that might affect logic). For typo or document changes, use docs: or chore: instead:

• fix: typo -> docs: fix typo

Pull Request ​

If you don't know how to send a Pull Request, we recommend reading the guide.

When sending a pull request, make sure your PR's title also follows the Commit Convention.

If your PR fixes or resolves an existing issue, please add the following line in your PR description (replace 123 with a real issue number):

fix #123

This will let GitHub know the issues are linked, and automatically close them once the PR gets merged. Learn more at the guide.

It's ok to have multiple commits in a single PR, you don't need to rebase or force push for your changes as we will use Squash and Merge to squash the commits into one commit when merging.

Thanks for reading and your contribution 😇

Happy coding 🙌🏻