@3yourmind/kotti-ui

Complete. The most commonly-needed components are implemented in Kotti. More components will be implemented when there is a specific need for them. TypeScript Support. Kotti is transitioning to a fully TypeScript-based code-base. While Vue doesn’t support all TS features, we believe that it’s still benefitial in the supported cases. Modern. Kotti aims to be a modern UI framework, regularly iterating over the existing design and adjusting it with newer UX improvements.
Consistent. The goal is to provide consistent, intuitive, and easy-to-use Vue components that users can immediately understand. Similar components shouldn’t defy expectations. Fail-fast. We believe that it’s better to error early than to have hard-to-catch bugs due to API misuse. Our components provide prop validation to catch common mistakes and throw errors in unexpected situations. Open-Source. Kotti is licensed under the MIT License — one of the most-permissible software licenses out there. Feel free to fork, modify, and use it. For any project you want.

Installation

yarn add @3yourmind/kotti-ui

or

npm install --save @3yourmind/kotti-ui

Documentation & Usage

Documentation: https://3yourmind.github.io/kotti/

// in main.ts / entrypoint
import Vue from 'vue'
import KottiUI from '@3yourmind/kotti-ui'
import '@3yourmind/kotti-ui/dist/style.css'

// (optional) register all KtComponents globally
Vue.use(KottiUI)

// Alternatively, import the components you need
import { KtForm } from '@3yourmind/kotti-ui'

const CustomVueComponent = {
	// ...
	components: {
		//...
		KtForm,
	},
}

Packages

Name NPM Downloads (Month) Downloads (Total) Size
@3yourmind/kotti-ui
@3yourmind/yoco
@3yourmind/vue-use-tippy

Dependencies

Some features of KtFieldFileUpload rely on WebRTC. This technology should be available on all modern browsers as well as on native clients for all major platforms.

If you have issues accessing the device's camera, include the webrtc-adapter package.

Development Workflow

Initial Setup

Remember to use your GitHub email for this repo

git clone git@github.com:3yourmind/kotti

cd kotti

# configure github email for this repository
git config user.email "123456+githubusername@users.noreply.github.com"

# install dependencies
yarn config set workspaces-experimental true
yarn install
yarn run lerna bootstrap

Develop

# auto-build/watch
yarn run watch

or

# having to build should hopefully be resolved in a future update
yarn workspace @3yourmind/sass-node-modules-importer run build
yarn workspace @3yourmind/yoco run build
yarn workspace @3yourmind/vue-use-tippy run build
yarn workspace @3yourmind/kotti-ui run build
# serve at http://localhost:3000
yarn workspace @3yourmind/documentation run serve

Handling Rebases

There are two workflows to help with rebasing pull requests:

  1. Rebase
    Commenting /rebase on any pull request will trigger a GitHub Action that rebases the PR.
    This is best used when attempting to rebase a PR without auto-rebase before merging.
  2. Auto-Rebase
    Adding the autorebase:opt-in label to any pull request will automatically rebase the PR as soon as it’s out-of-date.
    This should preferrably be used by the author, as it requires them to be aware of having to use git pull --rebase

Translations

Translations are currently handled by Kotti's internal implementation. However, there is a Crowdin project to make sure that all translations are correct.

Pre-requisites

Push translations

Whenever new translations are added, edited or removed

  1. Update the Crowdin source file packages/kotti-ui/source/locales/input.json with latest translations from the Kotti language file packages/kotti-ui/source/kotti-i18n/locales/en-US.ts
  2. Push the source file to crowdin
    crowdin push

Pull translations

  1. Check if translations are ready. It should display 100% next to the target language.
    crowdin status
  2. Pull latest translations
    crowdin pull
  3. Copy latest translations from the Crowdin language .json file to the corresponding Kotti language file. E.g.:
    • From packages/kotti-ui/source/locales/de.json
    • To packages/kotti-ui/source/kotti-i18n/locales/de-DE.ts

Linting

# es-lint (with --fix)
yarn run fix:eslint
# es-lint (without --fix)
yarn run check:eslint

# stylelint (with --fix)
yarn run fix:stylelint
# stylelint (without --fix)
yarn run check:stylelint

Testing

yarn run test

Publishing

This monorepo supports a semi-automatic release workflow. To trigger an automatic release:

  • make sure that the package that should be auto-released is mentioned in packagesToConsider of this file
  • bump the package's version in the relevant package.json
  • merge this change to master. This will trigger the repo's publish workflow which publishes any new versions it finds.

Kotti

  1. Prepare a new release draft here

    a. Tag format: versions/kotti-ui/1.2.3 (select Create new tag: versions/kotti-ui/1.2.3 on publish)

    b. Title format: kotti-ui@1.2.3: tldr of what's happening

    c. Release notes: Follow guidelines of previous releases

    d. Click on Save draft

  2. Optional: If you haven't already, make sure to functionally test:

yarn run watch # or if already merged to master, go to <https://3yourmind.github.io/kotti/>

  1. Create a pull request that bumps the version:
    a. Update the version in packages/kotti-ui/package.json
    b. Commit message format: version(kotti-ui@1.2.3): tldr of what's happening

  2. Merge the pull request and publish the release draft from step 1 here

  3. Announce the new version in the #kotti slack channel

Yoco

  1. Prepare a new release draft here

    a. Tag format: versions/yoco/1.2.3 (select Create new tag: versions/yoco/1.2.3 on publish)

    b. Title format: yoco@1.2.3: tldr of what's happening

    c. Release notes: Follow guidelines of previous releases

    d. Click on Save draft

  2. Optional: If you haven't already, make sure to functionally test:

yarn run watch # or if already merged to master, go to <https://3yourmind.github.io/kotti/>

  1. Create a pull request that bumps the version:
    a. Update the version in packages/yoco/package.json
    b. Update the yoco version in packages/kotti-ui/package.json (consider bumping kotti-ui, if the changes need to be used there as well)
    c. Commit message format: version(yoco@1.2.3): tldr of what's happening

  2. Merge the pull request and publish the release draft from step 1 here

  3. Announce the new version in the #kotti slack channel

Debugging

In case this does not work as expected, you want to check out the publish script and the github workflow definition that drive this action

Build

yarn run build

Debugging

Creating tarballs

For all packages that are published you can also create a tarball by running

# Create tarballs for all relevant packages
yarn run tarball

# Create tarball for a specific package
yarn run tarball --filter @3yourmind/yoco

# Can be combined with other commands
yarn run build tarball

# How the created tarballs can be installed in another project (yarn@1)
yarn cache clean && yarn remove @3yourmind/yoco && yarn add ../path/to/kotti/packages/yoco/package.tar.gz

See more:

Internals

Important Folders

Path Purpose
packages/documentation Nuxt-managed documentation

Turborepo Tooling

Debugging

The best starting point for debugging turbo is:

  1. Figure out what turbo command gets run (e.g. by checking package.json)
  2. Check the relevant tasks in turbo.json and packages/*/turbo.json

The Turborepo Documentation is an excellent resource, also make sure you have the @recommended Vercel.turbo-vsc extension installed as it provides autocomplete and linting for turbo.json.

It is also possible to visualize the graph used by turbo run

# generate a graph of turbo run build (needs graphviz)
yarn run debug:turbo