@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/

You can use Kotti as a vue plugin. This will make all of Kotti's components accessible globally

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

const app = createApp(/* ... */)

// Use Kotti as a plugin
app.use(KottiUI)

Alternatively, you can import single components into your vue files as needed

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"

# Set up bun to produce a human readable lock file. Learn more here: https://bun.com/docs/guides/install/git-diff-bun-lockfile
git config diff.lockb.textconv bun
git config diff.lockb.binary true

# install dependencies
bun install
bun run build

Develop

# auto-build/watch
bun run watch

or

# having to build should hopefully be resolved in a future update
bun workspace @3yourmind/yoco run build
bun workspace @3yourmind/vue-use-tippy run build
bun workspace @3yourmind/kotti-ui run build
# serve at http://localhost:3000
bun 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

• Have crowdin cli installed
  • MacOs:

    brew tap crowdin/crowdin
    brew install crowdin@3
    

  • Linux:
    • https://support.crowdin.com/cli-tool/#installation
• Have accesss to https://crowdin.com/project/3yourmind-kotti/en
• Have a crowdin token stored in a local env variable (https://crowdin.com/settings#api-key)

  export CROWDIN_V2_API_KEY=1234567890...
  

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)
bun run fix:eslint
# es-lint (without --fix)
bun run check:eslint

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

Testing

bun 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:

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

3. 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

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

5. 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:

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

3. 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

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

5. 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

bun 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
bun run tarball

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

# Can be combined with other commands
bun 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:

• https://docs.npmjs.com/cli/v6/commands/npm-pack
• https://classic.yarnpkg.com/en/docs/cli/add

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)
bun run debug:turbo