Contributing

Branching

The repository for @studiometa/ui follows a trunk-based workflow with main as the single principal branch:

• feature/... for new features
• fix/... for bug fixes

Every merge should be first approved by opening a pull-request against the main branch.

Local development

Clone the project and install the required dependencies. The back-end can be run with ddev which is preconfigured.

git clone https://github.com:studiometa/ui.git
cd ui/

# Install NPM dependencies
npm install
ddev start

# Launch the dev environment
npm run docs:dev

You will then be able to open the documentation development URL localhost:5173/-/ in your browser.

The TypeScript files from the @studiometa/ui packages can be imported in the playground by using a ESM import statement:

import { Figure } from '@studiometa/ui';

While in dev mode, the source TypeScript files will be automatically rebuild on change and made available to the playground at localhost:5173/-/play/index.html.

You can also open the repository in GitPod and start the dev environment there.

Remote development with Gitpod

The repository is also configured to easily run in Gitpod. Just click on the following button to get started:

Adding a component

A component can either be a single TypeScript file, a single Twig template or for more complex features, a combination of both.

💡 Pro tip

Take inspiration from existing components for new implementations.

TypeScript

The default template for a TypeScript component is as follow:

import { Base } from '@studiometa/js-toolkit';
import type { BaseConfig, BaseProps } from '@studiometa/js-toolkit';

export interface NameProps extends BaseProps {}

/**
 * Name class.
 */
export default class Name extends Base<NameProps> {
  static config: BaseConfig = {
    name: 'Name',
  };
}

Once your component is ready, add an export of all its content to the index.ts file of its category. For example, if it is a molecule, edit the packages/ui/index.ts file:

 export * from './Modal/index.js';
+export * from './MyComponent/index.js';
 export * from './Panel/index.js';

Twig

All Twig templates should at least expose an attr variable that can be used to configure the attributes of the HTML root element of the template. To facilitate this pattern, we use functions added by our studiometa/twig-toolkit.

{% set default_attributes = { class: 'block' } %}
{% set required_attributes = { data_component: 'MyComponent' } %}

{% set attributes = merge_html_attributes(
  attr ?? null,
  default_attributes,
  required_attributes,
) %}

<div {{ html_attributes(attribute) }}>
  ...
</div>

Publishing a new version

To publish a new version, create a release branch from main:

git checkout main
git pull origin main
git checkout -b release/0.2.41

In this release branch, update the version number of all packages with the following command:

npm version 0.2.41 -ws --include-workspace-root

Edit the CHANGELOG.md file to add the version number and the date of the release:

 ## [Unreleased]

+## [v0.2.41](https://github.com/studiometa/ui/compare/0.2.40..0.2.41) (2024-02-13)
+

Open a pull-request against main to validate the changes and make sure all tests are passing. Once the PR is approved, merge it and tag the release:

git checkout main
git pull origin main
git tag 0.2.41 --message 'v0.2.41'
git push origin main
git push origin --tags

GitHub actions will create a release on GitHub and publish the @studiometa/ui packages to NPM. The Packagist package will be updated with the latest tag as well.