Components

TIP

Before you start, be sure to read the Introduction.

The components package contains all Vue components supported by Codey.

Running the local development environment

Playground

A playground is created to provide a realistic environment where codey is setup as intended and components can be tested/developed as they would be used within a real vue application.

You can start the playground using the following command:

npm run dev:playground

The playground automatically loads all components created in the examples folder of your component.

Note

Currently you need to restart the playground when new examples were added as this part isn't within the watch scope.

Documentation

Adding new components requires them to be documented. To open the documentation simply run

npm run dev:docs

The showcases used within the documentation are the examples created and used by the playground. This way we eliminate duplicate code and have an external use for the already created examples during development.

A base to get component docs started can be found here: apps\documentation\src\docs\components\_template.md

Creating or Adopting a Component

Adding a new component or adopting one from an existing framework requires changes to the components package.

1. Folder and File Setup

The following folder structure is required when creating a new component. This will represent your component module and allows it to be tree shaken:

┣ packages
┃   ┣ components
┃   ┃   ┣ src
┃   ┃   ┃   ┣ new-component
┃   ┃   ┃   ┃   ┣ examples
┃   ┃   ┃   ┃   ┃   ┣ default-use-case.vue
┃   ┃   ┃   ┃   ┃   ┣ as-something.vue
┃   ┃   ┃   ┃   ┃   ┣ with-some-prop-enabled.vue
┃   ┃   ┃   ┃   ┣ new-component.test.ts (optional)
┃   ┃   ┃   ┃   ┣ new-component.vue
┃   ┃   ┃   ┃   ┣ new-component.types.ts (optional)
┃   ┃   ┃   ┃   ┣ index.ts

The index.ts exports everything that is publicly accessible:

export { default as XerNewComponent } from "./new-component.vue";
// depending on what type options you have
export type * from "./new-component.types";
export type * from "./new-component.vue";

Finally you need to add your component module to the root index.ts found at packages/components/src/index.ts:

// src/index.ts
export * from "./new-component";

File Naming Conventions

• We don't necessarily name components in 2 or more words. This would require the use of a prefix like xer- on all the files like e.g. button or card. As we are in the Xerius Codey Repo, everything would be named like that, loosing its value. We choose not to add this prefix clutter on our file naming.
• We don't follow the PascalCase naming rule for Vue components, instead everything is kebab-case so all files and folders are streamlined. This also prevents case issues with renames.

Examples

These represent different use cases and configuration options of the component. They can be used during development in the Playground, for visual testing and as showcase within the Documentation.

For inspiration on naming the examples, have a look at existing components.

Important

It is important to follow the kebab-case format for examples as they are dynamically read by the Playground and Documentation.

Visual Testing

For each component visual tests need to be created in the tests folder of the apps/playground application. The visual tests are based on the examples and can include functional tests as well to test the integration of different components.

The folder structure should look as following:

┣ apps
┃   ┣ playground
┃   ┃   ┣ tests
┃   ┃   ┃   ┣ new-component
┃   ┃   ┃   ┃   ┣ new-component.pw.ts

A screenshot folder will be added automatically when running the visual tests for the first time.

Unit Testing

When a component is adopted from an existing framework, unit test don't fall under our responsibility when no changes are made to the component. Visual tests will suffice to verify the theming and custom styling for Xerius.

For our own components, unit tests should be created to test internal logic and functionality that is changeable by the props (or public API) of the component. As visual tests are mandatory, unit tests should prevent creating an overlap in the test coverage.

Types

Note

In case of adopting a component from an existing framework, we don't re-export the types. They can be imported directly from the original package.

All components should have type definitions. Depending on the complexity and required data structures an option for type exports can be chosen:

• Types that are tightly coupled to a component should be exported from the vue file itself using an extra <script lang="ts"> tag on top of the file e.g. a Prop type.
• When having multiple components or specific data types like e.g. LanguageOptions a separate types file should be use for exporting the types.

2. Styling

The main driver for styling is tailwind. When creating or maintaining a custom component all styling needs to be set using tailwind. The codey-style will no longer be supported. In case class definition become to large, a <style scoped> block can be added to use the tailwind @apply function to support custom classes. Readability and maintainability is stil an important factor.

PrimeVue Presets

When adopting a component from PrimeVue a preset needs to be added at new-component/presets/preset-name.js. The required tailwind classes need to be set there to meet the design requirements.

When create a new preset, be sure to add it to packages/components/presets/preset-name/index.ts.

3. Add changeset

In order to have a correct representation in the changelog a changeset needs to be added running the following command:

npm run changeset:add

When asked, select that this is a change for @xerius/codey-components and for @xerius/codey-style when styles were added. Since this adds a new functionality, it needs to be marked as a minor change. As last step, give a descriptive message what component you added.

The last step is to open a PR for review