Skip to content

Commit 246acb7

Browse files
deleoniodeleonio
committed
chore: fix first steps
1 parent cae0eae commit 246acb7

File tree

17 files changed

+463
-131
lines changed

17 files changed

+463
-131
lines changed

‎dev/docs/10-get-started/1-first-steps.mdx

Lines changed: 256 additions & 58 deletions
Original file line numberDiff line numberDiff line change
@@ -24,27 +24,13 @@ npm init kolibri@latest my-kolibri-app
2424
alt="Zeigt wie man mit create-kolibri eine neue App anlegen kann."
2525
/>
2626

27-
## Integration in vorhandene Projekte
27+
## Einbinden in ein bestehendes Projekt
2828

29-
### 1. Installation der Pakete
29+
### Einbinden von Schriftarten
3030

31-
Um die Komponenten nutzen zu können, müssen die benötigten npm-Pakete installiert werden. Je nach verwendeten Paket-Manager können diese mit einem der folgenden Befehle dem Projekt hinzugefügt werden.
31+
Schriftarten werden von Natur aus losgelöst vom CSS geladen und müssen je nach **KoliBri**-Theme in die projektspezifische Rahmenseite (`index.html`) eingebunden werden.
3232

33-
NPM `npm i @public-ui/components @public-ui/themes` oder
34-
35-
PNPM `pnpm i @public-ui/components @public-ui/themes` oder
36-
37-
YARN `yarn add @public-ui/components @public-ui/themes`
38-
39-
### 2. Einbinden von Schriftarten
40-
41-
Schriftarten, sogenannte Fonts, werden von Natur aus losgelöst vom CSS geladen und müssen je nach KoliBri-Theme (Styleguide) in die Rahmenseite (HTML-Datei) eingebunden werden.
42-
43-
Hierzu können die in der Bibliothek mitgelieferten Schriftarten in die eigenen Assets kopiert werden.
44-
45-
`cp -r node_modules/@public-ui/themes/assets public/assets`
46-
47-
Anschließend können die relevanten CSS-Dateien mit den Schriftart-Definitionen im `<head>` der HTML-Datei eingebunden werden.
33+
Hierzu können die in der Bibliothek mitgelieferten Schriftarten in die eigenen Assets kopiert werden: `node_modules/@public-ui/themes/assets`, oder eigene verwendet werden.
4834

4935
```html
5036
<!DOCTYPE html>
@@ -61,8 +47,8 @@ Anschließend können die relevanten CSS-Dateien mit den Schriftart-Definitionen
6147
<link rel="stylesheet" href="assets/codicons/codicon.css" />
6248
<link rel="stylesheet" href="assets/fontawesome-free/css/all.min.css" />
6349
<link rel="stylesheet" href="assets/icofont/icofont.min.css" />
64-
<link rel="stylesheet" href="assets/noto-sans/noto-sans.css" />
6550
<link rel="stylesheet" href="assets/kreon/style.css" />
51+
<link rel="stylesheet" href="assets/noto-sans/noto-sans.css" />
6652
<link rel="stylesheet" href="assets/material-icons/iconfont/material-icons.css" />
6753
<link rel="stylesheet" href="assets/material-symbols/index.css" />
6854
<link rel="stylesheet" href="assets/roboto/roboto.css" />
@@ -71,50 +57,225 @@ Anschließend können die relevanten CSS-Dateien mit den Schriftart-Definitionen
7157
</html>
7258
```
7359

74-
### 3. Registrieren des Komponenten-Loaders
60+
### I Vite + React
7561

76-
Nachdem die Vorbereitungen abgeschlossen sind, muss nur noch der Komponenten-Loader registriert werden.
77-
Er sorgt dafür, dass die Web Components asynchron (lazy) nachgeladen werden, sobald sie in der Webseite verwendet werden.
62+
#### 1. Installieren der KoliBri-Bibliotheken
7863

79-
| Methode | Erläuterung |
80-
| -------------------- | ------------------------------------------------------- |
81-
| register | Setzt ein Theme und registriert anschließend den Loader |
82-
| BMF | Registriert den Loader für z.B. das BMF-Theme |
83-
| defineCustomElements | Registriert den Loader für die Web Components |
64+
<kol-tabs _headers="['npm', 'pnpm', 'yarn']" _tabs='[{"_label":"NPM"},{"_label":"PNPM"},{"_label":"YARN"}]'>
65+
<div>`npm i @public-ui/components @public-ui/themes @public-ui/react`</div>
66+
<div>`pnpm i @public-ui/components @public-ui/themes @public-ui/react`</div>
67+
<div>`yarn add @public-ui/components @public-ui/themes @public-ui/react`</div>
68+
</kol-tabs>
8469

85-
#### Variante A: Statisches Projekt
70+
#### 2. Integration
8671

87-
```html
88-
<head>
89-
<script type="module">
90-
import { register } from 'https://esm.sh/@public-ui/components@1.4.0-rc.6';
91-
import { defineCustomElements } from 'https://esm.sh/@public-ui/components@1.4.0-rc.6/dist/loader';
92-
import { BMF } from 'https://esm.sh/@public-ui/themes@1.4.0-rc.6';
93-
register([BMF], defineCustomElements)
94-
.then(() => {})
72+
main.tsx
73+
74+
```diff
75+
import React from "react";
76+
import ReactDOM from "react-dom/client";
77+
import App from "./App.tsx";
78+
import "./index.css";
79+
80+
+import { register } from "@public-ui/components";
81+
+import { defineCustomElements } from "@public-ui/components/dist/loader";
82+
+import { DE } from "@public-ui/themes";
83+
84+
+register(DE, defineCustomElements)
85+
+ .then(() => {
86+
ReactDOM.createRoot(document.getElementById("root") as HTMLElement).render(
87+
<React.StrictMode>
88+
<App />
89+
</React.StrictMode>
90+
);
91+
+ })
92+
+ .catch(console.warn);
93+
```
94+
95+
#### 3. module einbinden
96+
97+
index.html
98+
99+
```diff
100+
<!DOCTYPE html>
101+
<html lang="en">
102+
<head>
103+
<meta charset="UTF-8" />
104+
<link rel="icon" type="image/svg+xml" href="/vite.svg" />
105+
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
106+
<title>Vite + React + TS</title>
107+
+ <script
108+
+ type="module"
109+
+ src="/node_modules/@public-ui/components/dist/kolibri/kolibri.esm.js"
110+
+ ></script>
111+
</head>
112+
<body>
113+
<div id="root"></div>
114+
<script type="module" src="/src/main.tsx"></script>
115+
</body>
116+
</html>
117+
```
118+
119+
#### 4. Beispiel
120+
121+
```tsx
122+
import React from 'react';
123+
import { KolSpin } from '@public-ui/react';
124+
125+
export const AppComponent = () => {
126+
return (
127+
<div>
128+
<KolSpin _show />
129+
</div>
130+
);
131+
};
132+
```
133+
134+
### II Vite + Vue
135+
136+
#### 1. Installieren der KoliBri-Bibliotheken
137+
138+
<kol-tabs _headers="['npm', 'pnpm', 'yarn']" _tabs='[{"_label":"NPM"},{"_label":"PNPM"},{"_label":"YARN"}]'>
139+
<div>`npm i @public-ui/components @public-ui/themes @public-ui/vue`</div>
140+
<div>`pnpm i @public-ui/components @public-ui/themes @public-ui/vue`</div>
141+
<div>`yarn add @public-ui/components @public-ui/themes @public-ui/vue`</div>
142+
</kol-tabs>
143+
144+
#### 2. Plugin
145+
146+
kolibri.plugin.ts
147+
148+
```js
149+
import type { Plugin } from 'vue';
150+
import { defineCustomElements } from '@public-ui/components/dist/loader';
151+
import { register } from '@public-ui/components';
152+
import { ITZBund } from '@public-ui/themes';
153+
export const ComponentLibrary: Plugin = {
154+
install() {
155+
register(ITZBund, defineCustomElements)
156+
.then(() => console.log('Components registered'))
95157
.catch(console.warn);
96-
</script>
97-
</head>
98-
<body>
99-
<kol-spin _show>
100-
</body>
158+
},
159+
};
160+
```
161+
162+
main.ts:
163+
164+
```diff
165+
import { createApp } from 'vue'
166+
import App from './App.vue'
167+
import './assets/main.css'
168+
+ import { ComponentLibrary } from './vue.plugin'
169+
170+
const app = createApp(App)
171+
172+
+ app.use(ComponentLibrary)
173+
174+
app.mount('#app')
175+
```
176+
177+
#### 3. module einbinden
178+
179+
index.html
180+
181+
```diff
182+
<!DOCTYPE html>
183+
<html lang="en">
184+
<head>
185+
<meta charset="UTF-8" />
186+
<link rel="icon" href="/favicon.ico" />
187+
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
188+
+ <script
189+
+ type="module"
190+
+ src="/node_modules/@public-ui/components/dist/kolibri/kolibri.esm.js"
191+
+ ></script>
192+
<title>Vite App</title>
193+
</head>
194+
<body>
195+
<div id="app"></div>
196+
<script type="module" src="/src/main.ts"></script>
197+
</body>
198+
</html>
199+
```
200+
201+
#### 4. Komponenten als custom components registrieren
202+
203+
vite.config.ts
204+
205+
```diff
206+
import { fileURLToPath, URL } from 'node:url'
207+
208+
import { defineConfig } from 'vite'
209+
import vue from '@vitejs/plugin-vue'
210+
211+
// https://vitejs.dev/config/
212+
export default defineConfig({
213+
- plugins: [],
214+
+ plugins: [
215+
+ vue({
216+
+ template: {
217+
+ compilerOptions: {
218+
+ // treat all tags with a dash as custom elements
219+
+ isCustomElement: (tag) => tag.includes('-')
220+
+ }
221+
+ }
222+
+ })
223+
+ ],
224+
resolve: {
225+
alias: {
226+
'@': fileURLToPath(new URL('./src', import.meta.url))
227+
}
228+
}
229+
})
101230
```
102231

103-
#### Variante B: React-Projekt
232+
#### 5. Beispiel
233+
234+
```html
235+
<kol-input-text :_value="text" :_on="{ onChange: (e: unknown, v: string) => (text = v) }"></kol-input-text>
236+
<kol-button _label="Text löschen" :_on="{ onClick: () => (text = '') }"></kol-button>
237+
```
238+
239+
Hinweis: KoliBri-Inputs übergeben in der Regel das Ursprungsevent als ersten Parameter und den Wert des Feldes als Zweiten.
240+
241+
### III React
242+
243+
#### 1. Installieren der KoliBri-Bibliotheken
244+
245+
`npm i @public-ui/components @public-ui/react @public-ui/themes`
246+
247+
oder
248+
249+
`pnpm i @public-ui/components @public-ui/react @public-ui/themes`
250+
251+
oder
252+
253+
`yarn add @public-ui/components @public-ui/react @public-ui/themes`
104254

105-
##### Integration
255+
#### 2. Registrieren des KoliBri-Loaders
256+
257+
Nachdem die Vorbereitungen abgeschlossen sind, muss nur noch der KoliBri-Loader registriert werden.
258+
Er sorgt dafür, dass die Web Components asynchron (lazy) nachgeladen werden, sobald sie in der Webseite verwendet werden.
259+
260+
| Methode | Erläuterung |
261+
| -------------------- | ------------------------------------------------------- |
262+
| register | Setzt ein Theme und registriert anschließend den Loader |
263+
| DEFAULT | Registriert den Loader für z.B. das DEFAULT-Theme |
264+
| defineCustomElements | Registriert den Loader für die Web Components |
265+
266+
#### 3. Integration
106267

107268
```tsx
108269
import React from 'react';
109270
import ReactDOM from 'react-dom';
110271

111272
import { AppComponent } from './components/app/component';
112273

113-
import { register } from '@public-ui/components';
274+
import { register } from '@public-ui/core';
114275
import { defineCustomElements } from '@public-ui/components/dist/loader';
115-
import { BMF } from '@public-ui/themes';
276+
import { DEFAULT } from '@public-ui/themes';
116277

117-
register(BMF, defineCustomElements)
278+
register(DEFAULT, defineCustomElements)
118279
.then(() => {
119280
const htmlDivElement: HTMLDivElement | null = document.querySelector<HTMLDivElement>('div#app');
120281
if (htmlDivElement instanceof HTMLDivElement) {
@@ -125,27 +286,64 @@ register(BMF, defineCustomElements)
125286
.catch(console.warn);
126287
```
127288

128-
##### Adapter installieren
289+
#### 4. Beispiel
129290

130-
Für React steht ein Adapter zur Verfügung, der die nahtlose und typisierte Verwendung in TSX ermöglicht.
291+
```tsx
292+
import React from 'react';
293+
import { KolSpin } from '@public-ui/react';
294+
295+
export const AppComponent = () => {
296+
return (
297+
<div>
298+
<KolSpin _show />
299+
</div>
300+
);
301+
};
302+
```
131303

132-
NPM `npm i @public-ui/react` oder
304+
### IV ohne Framework
133305

134-
PNPM `pnpm i @public-ui/react` oder
306+
`pnpm i @public-ui/components @public-ui/themes`
307+
`npm i @public-ui/components @public-ui/themes`
308+
`yarn add @public-ui/components @public-ui/themes`
309+
310+
```diff
311+
<!DOCTYPE html>
312+
<html lang="en">
313+
<head>
314+
<meta charset="UTF-8" />
315+
<link rel="icon" type="image/svg+xml" href="/vite.svg" />
316+
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
317+
<title>Title</title>
318+
+ <script
319+
+ type="module"
320+
+ src="/node_modules/@public-ui/components/dist/kolibri/kolibri.esm.js"
321+
+ ></script>
322+
</head>
323+
<body>
324+
<div id="app"></div>
325+
<script type="module" src="/src/main.ts"></script>
326+
</body>
327+
</html>
328+
```
135329

136-
YARN `yarn add @public-ui/react`
330+
Hierbei ist die Web-Component Schreibweise (kebab-case) zu verwenden. (z.B.: `<kol-heading>`)
137331

138-
##### Komponente verwenden
332+
### V statische Webseite
139333

140-
```tsx
141-
import React, { FunctionComponent } from 'react';
142-
import { KolSpin } from '@public-ui/react';
334+
Um KoliBri in eine statische Webseite einzubauen muss lediglich das folgende Script-Tag eingebunden werden.
335+
Sofern Schriftarten und/oder Icons verwendet werden, müssen diese, wie oben beschrieben, eingebunden werden.
143336

144-
export const App: FunctionComponent = () => <KolSpin _show />;
337+
```html
338+
<script type="module">
339+
import { register } from 'https://esm.sh/@public-ui/components';
340+
import { defineCustomElements } from 'https://esm.sh/@public-ui/components/dist/loader';
341+
import { ITZBund } from 'https://esm.sh/@public-ui/themes';
342+
register(ITZBund, defineCustomElements).catch(console.warn);
343+
</script>
145344
```
146345

147-
<hr />
148-
<hr />
346+
Hierbei ist die Web-Component Schreibweise (kebab-case) zu verwenden. (z.B.: `<kol-heading>`)
149347

150348
## Spezial Features
151349

0 commit comments

Comments
 (0)