Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/3yourmind/kotti
💅 3YOURMIND’s Vue UI Framework & Design System
https://github.com/3yourmind/kotti
design-system ui-framework vue
Last synced: 4 days ago
JSON representation
💅 3YOURMIND’s Vue UI Framework & Design System
- Host: GitHub
- URL: https://github.com/3yourmind/kotti
- Owner: 3YOURMIND
- License: mit
- Created: 2017-12-11T17:20:08.000Z (almost 7 years ago)
- Default Branch: master
- Last Pushed: 2024-10-25T08:32:05.000Z (19 days ago)
- Last Synced: 2024-10-25T08:44:54.105Z (18 days ago)
- Topics: design-system, ui-framework, vue
- Language: TypeScript
- Homepage: https://3yourmind.github.io/kotti/
- Size: 62.5 MB
- Stars: 78
- Watchers: 6
- Forks: 8
- Open Issues: 80
-
Metadata Files:
- Readme: README.md
- License: license.md
Awesome Lists containing this project
README
@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**:
```typescript
// 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`](/packages/kotti-ui) | [](https://npmjs.com/package/@3yourmind/kotti-ui) |  |  |  |
| [`@3yourmind/yoco`](/packages/yoco) | [](https://npmjs.com/package/@3yourmind/yoco) |  |  |  |
| [`@3yourmind/vue-use-tippy`](/packages/vue-use-tippy) | [](https://npmjs.com/package/@3yourmind/vue-use-tippy) |  |  |  |
## Dependencies
Some features of `KtFieldFileUpload` rely on [`WebRTC`](https://webrtc.org/). 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`](https://www.npmjs.com/package/webrtc-adapter) package.
## Development Workflow
### Initial Setup
Remember to use [your GitHub email](https://github.com/settings/emails) for this repo
```bash
git clone [email protected]:3yourmind/kotti
cd kotti
# configure github email for this repository
git config user.email "[email protected]"
# install dependencies
yarn config set workspaces-experimental true
yarn install
yarn run lerna bootstrap
```
### Develop
```bash
# auto-build/watch
yarn run watch
```
or
```bash
# 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
- 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
```bash
# 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
```bash
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](internals/scripts/source/publish.ts)
- 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](https://github.com/3YOURMIND/kotti/releases/new)
a. Tag format: `versions/kotti-ui/1.2.3` (select `Create new tag: versions/kotti-ui/1.2.3 on publish`)
b. Title format: `[email protected]: 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:
```bash
yarn run watch # or if already merged to master, go to
```
3. Create a pull request that bumps the version:
a. Update the version in `packages/kotti-ui/package.json`
b. Commit message format: `version([email protected]): tldr of what's happening`
4. Merge the pull request and publish the release draft from `step 1` [here](https://github.com/3YOURMIND/kotti/releases)
5. Announce the new version in the `#kotti` slack channel
#### Yoco
1. Prepare a new release draft [here](https://github.com/3YOURMIND/kotti/releases/new)
a. Tag format: `versions/yoco/1.2.3` (select `Create new tag: versions/yoco/1.2.3 on publish`)
b. Title format: `[email protected]: 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:
```bash
yarn run watch # or if already merged to master, go to
```
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([email protected]): tldr of what's happening`
4. Merge the pull request and publish the release draft from `step 1` [here](https://github.com/3YOURMIND/kotti/releases)
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](internals/scripts/source/publish.ts) and the [github workflow definition](.github/workflows/publish.yml) that drive this action
### Build
```bash
yarn run build
```
## Debugging
### Creating tarballs
For all packages that are published you can also create a tarball by running
```bash
# 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:
- 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](https://turbo.build/repo/docs) 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`](https://turbo.build/repo/docs/reference/command-line-reference/run#--graph)
```sh
# generate a graph of turbo run build (needs graphviz)
yarn run debug:turbo
```