nuxt-ui-basekit 0.1.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +93 -79
  2. package/app/composables/useBaseKit.ts +40 -35
  3. package/package.json +3 -3
package/README.md CHANGED
@@ -1,14 +1,16 @@
1
1
  # nuxt-ui-basekit
2
2
 
3
- Basis-Komponenten für Nuxt 4 auf [Nuxt UI](https://ui.nuxt.com) — als Nuxt-Layer.
4
- Tabellen, Reiter, Diagramme, Auswahl-Dialoge, Leerzustände: die Bausteine, die
5
- in jedem Verwaltungs-Frontend wieder anfallen und die Nuxt UI nicht mitbringt.
3
+ Base components for Nuxt 4 on top of [Nuxt UI](https://ui.nuxt.com) — as a Nuxt
4
+ layer. Tables, tabs, charts, pickers, empty states: the parts that come up again
5
+ in every admin frontend and that Nuxt UI does not ship.
6
6
 
7
- Das Paket kennt keine Anwendung. Es hat keine Stores außer einem für die
8
- Rückfrage, keine Endpunkte, keine Übersetzungsschlüssel und keine Farben, die
9
- zu einer Marke gehören. Was es anzeigt, bekommt es hereingereicht.
7
+ The package knows nothing about your application. It has no stores beyond the
8
+ one behind the confirmation dialog, no endpoints, no translation keys and no
9
+ colours that belong to a brand. Whatever it displays is handed in.
10
10
 
11
- ## Einbinden
11
+ **[→ Every component with a screenshot](https://github.com/McGo/nuxt-ui-basekit/blob/main/COMPONENTS.md)**
12
+
13
+ ## Install
12
14
 
13
15
  ```bash
14
16
  npm i -D nuxt-ui-basekit
@@ -21,30 +23,39 @@ export default defineNuxtConfig({
21
23
  })
22
24
  ```
23
25
 
24
- `@nuxt/ui`, `nuxt` und `pinia` sind Peers, sie stehen im Konsumenten und
25
- werden nicht mitgeliefert. Die Komponenten sind danach global verfügbar, ohne
26
- Import.
26
+ `@nuxt/ui`, `nuxt` and `pinia` are peers — they live in the consumer and are not
27
+ bundled along. The components are globally available afterwards, no import.
28
+
29
+ Nuxt UI itself still needs its stylesheet, the same as in any project that uses
30
+ it:
31
+
32
+ ```css
33
+ /* app/assets/css/main.css, referenced from nuxt.config.ts */
34
+ @import "tailwindcss";
35
+ @import "@nuxt/ui";
36
+ ```
27
37
 
28
- ## Was drin ist
38
+ ## What is in it
29
39
 
30
- | Gruppe | Komponenten |
40
+ | Group | Components |
31
41
  |---|---|
32
- | Struktur | `BaseKitTabs` · `BaseKitSettingRow` · `BaseKitEmptyState` · `BaseKitChoiceCard` · `BaseKitPending` |
33
- | Listen | `BaseKitDataTable` · `BaseKitStatTile` |
34
- | Auswahl | `BaseKitRecordPicker` · `BaseKitIconPicker` · `BaseKitFileUpload` |
35
- | Wege | `BaseKitBackLink` · `BaseKitViewLink` |
36
- | Rückfrage | `BaseKitConfirmModal` + `useConfirm()` |
42
+ | Structure | `BaseKitTabs` · `BaseKitSettingRow` · `BaseKitEmptyState` · `BaseKitChoiceCard` · `BaseKitPending` |
43
+ | Lists | `BaseKitDataTable` · `BaseKitStatTile` |
44
+ | Pickers | `BaseKitRecordPicker` · `BaseKitIconPicker` · `BaseKitFileUpload` |
45
+ | Navigation | `BaseKitBackLink` · `BaseKitViewLink` |
46
+ | Confirmation | `BaseKitConfirmModal` + `useConfirm()` |
37
47
  | Text | `BaseKitMarkdownEditor` |
38
- | Diagramme | `BaseKitChartBars` · `-Columns` · `-Donut` · `-Meter` · `-Figure` |
48
+ | Charts | `BaseKitChartBars` · `-Columns` · `-Donut` · `-Meter` · `-Figure` |
39
49
 
40
- Jede Komponente trägt ihre Erklärung im Kopf der Datei — was sie tut, wann sie
41
- die richtige Wahl ist und wann nicht.
50
+ Each component carries its reasoning in the file header — what it does, when it
51
+ is the right choice and when it is not. [COMPONENTS.md](https://github.com/McGo/nuxt-ui-basekit/blob/main/COMPONENTS.md) has the
52
+ short version of each, with a screenshot.
42
53
 
43
- ## Beschriftungen und Sprache
54
+ ## Labels and language
44
55
 
45
- Die Komponenten rufen kein `vue-i18n` auf und kennen keine
46
- Übersetzungsschlüssel. Ohne Zutun rendern sie deutsche Voreinstellungen; wer
47
- eigene Texte oder mehrere Sprachen führt, reicht sie über ein Plugin herein:
56
+ The components never call `vue-i18n` and know no translation keys. Left alone
57
+ they render English defaults; anyone with their own wording or several
58
+ languages hands them in through a plugin:
48
59
 
49
60
  ```ts
50
61
  // plugins/basekit.ts
@@ -65,95 +76,98 @@ export default defineNuxtPlugin((nuxtApp) => {
65
76
  })
66
77
  ```
67
78
 
68
- Zwei Dinge, die dabei Zeit kosten können:
79
+ `locale` is a BCP-47 tag and drives `Intl` — thousands separators, percentages
80
+ and date formats in the charts follow it.
81
+
82
+ Two things that can cost an afternoon:
69
83
 
70
- - **`useI18n()` gehört nicht ins Plugin.** Es verlangt einen
71
- Komponenten-Setup-Kontext und wirft dort `MUST_BE_CALL_SETUP_TOP`
72
- (Fehlercode 26). Beim serverseitigen Rendern heißt das: 500 auf jeder Seite.
73
- Die Instanz kommt über `nuxtApp.$i18n`, und zwar erst beim Lesen des
74
- `computed` — dann ist auch die Plugin-Reihenfolge gleichgültig.
75
- - **Einzelne Beschriftungen** bleiben als Prop überschreibbar. Die Tabelle
76
- trägt nur, was ohne Angabe herauskommt.
84
+ - **`useI18n()` does not belong in the plugin.** It requires a component setup
85
+ context and throws `MUST_BE_CALL_SETUP_TOP` (error 26) there. Under server-side
86
+ rendering that means a 500 on every page. Take the instance from
87
+ `nuxtApp.$i18n`, and only when the `computed` is read — then plugin order
88
+ stops mattering too.
89
+ - **Individual labels stay overridable as props.** The table above only decides
90
+ what comes out when nothing is passed.
77
91
 
78
- ## Farben
92
+ ## Colours
79
93
 
80
- Die Komponenten greifen ausschließlich auf `--basekit-*` zu. Die
81
- Voreinstellungen stehen in `app/assets/css/basekit.css` und werden vom Layer
82
- geladen. Ein Projekt mit eigenem Theme legt sie in seinem eigenen Stylesheet
83
- darauf:
94
+ The components only ever reach for `--basekit-*`. The defaults live in
95
+ `app/assets/css/basekit.css` and are loaded by the layer. A project with its own
96
+ theme puts its values on top, in its own stylesheet:
84
97
 
85
98
  ```css
86
99
  :root {
87
- --basekit-accent: var(--meine-markenfarbe, #2563eb);
88
- --basekit-surface: var(--meine-kartenflaeche, #ffffff);
100
+ --basekit-accent: var(--my-brand-colour, #2563eb);
101
+ --basekit-surface: var(--my-card-surface, #ffffff);
89
102
  }
90
103
  ```
91
104
 
92
- Die fünf Diagrammfarben sind als Satz geprüft — Lichtheitsband, Chroma und
93
- Abstand zwischen Nachbarn, auch unter Farbfehlsichtigkeit. Wer sie
94
- überschreibt, sollte das als Satz tun und nicht einzeln; wer mehr als fünf
95
- Reihen hat, fasst zusammen, statt eine sechste Farbe zu erfinden.
105
+ The five chart colours are validated as a set — lightness band, chroma and the
106
+ distance between neighbours, colour vision deficiency included. Override them as
107
+ a set rather than one at a time; if you have more than five series, group them
108
+ instead of inventing a sixth colour.
96
109
 
97
- ## Entwickeln
110
+ ## Development
98
111
 
99
112
  ```bash
100
113
  npm install
101
- npx nuxi prepare # erzeugt .nuxt/tsconfig.json, sonst laufen die Tests nicht
114
+ npx nuxi prepare # writes .nuxt/tsconfig.json, without it the tests fail
102
115
  npm test
103
116
  npm run lint # nuxi typecheck
104
117
  ```
105
118
 
106
- `tests/grenze.test.ts` hält fest, was das Paket nicht darf: keine Importe
107
- außerhalb des Pakets, keine Abhängigkeit, die nicht in der `package.json`
108
- steht, kein `vue-i18n`, keine Übersetzungsschlüssel, keine fremden
109
- CSS-Variablen. Der Test ist der Grund, warum sich das Paket überhaupt
110
- herausschneiden ließ — ohne ihn wäre die Trennung nach dem dritten Feature
111
- wieder zu.
119
+ `tests/grenze.test.ts` pins down what the package is not allowed to do: no
120
+ imports from outside the package, no dependency that is missing from
121
+ `package.json`, no `vue-i18n`, no translation keys, no foreign CSS variables.
122
+ That test is the reason the package could be carved out at all — without it the
123
+ separation would have closed up again by the third feature.
124
+
125
+ `playground/` is a small Nuxt app that pulls the layer in the way a consumer
126
+ would. It is the place to look at a component, and the source of the
127
+ screenshots in [COMPONENTS.md](https://github.com/McGo/nuxt-ui-basekit/blob/main/COMPONENTS.md):
128
+
129
+ ```bash
130
+ cd playground && npm install && npm run dev
131
+ ```
112
132
 
113
133
  ### Lockfile
114
134
 
115
- Wer auf macOS oder Windows eine Abhängigkeit hinzufügt, muss das Lockfile
116
- anschließend einmal unter Linux/x64 nachziehen — sonst fehlen die
117
- plattformspezifischen Optional-Pakete (`@emnapi/*` und Verwandtschaft), und
118
- `npm ci` im Workflow bricht ab:
135
+ Adding a dependency on macOS or Windows means pulling the lockfile through
136
+ Linux/x64 afterwards — otherwise the platform-specific optional packages
137
+ (`@emnapi/*` and relatives) are missing and `npm ci` fails in the workflow:
119
138
 
120
139
  ```bash
121
140
  docker run --rm --platform linux/amd64 -v "$PWD:/app" -w /app \
122
141
  node:24 npm install --package-lock-only
123
142
  ```
124
143
 
125
- Die Architektur ist nicht gleichgültig: auf Apple Silicon läuft der Container
126
- ohne `--platform` als arm64, und dann fehlen genau die x64-Varianten, die der
127
- Runner braucht. Danach lokal einmal `npm ci`, das holt die eigenen Binaries
128
- zurück.
129
-
130
- ## Veröffentlichen
144
+ The architecture matters: on Apple Silicon the container runs as arm64 without
145
+ `--platform`, and then exactly the x64 variants the runner needs are still
146
+ missing. Run `npm ci` locally afterwards to get your own binaries back.
131
147
 
132
- Zwei Workflows unter `.github/workflows`. `pruefen` läuft auf `main` und in
133
- jedem Pull Request und führt `nuxi prepare`, `nuxi typecheck` und die Tests
134
- aus. `veroeffentlichen` hängt an einem Tag `vX.Y.Z`, prüft noch einmal und
135
- schiebt das Paket dann nach npmjs.com. Ein Build-Schritt fehlt, weil der Layer
136
- als Rohquelle ausgeliefert wird und Nuxt ihn im Konsumenten übersetzt.
148
+ ## Releasing
137
149
 
138
- Eine neue Fassung:
150
+ Two workflows under `.github/workflows`. `pruefen` runs on `main` and on every
151
+ pull request and does `nuxi prepare`, `nuxi typecheck` and the tests.
152
+ `veroeffentlichen` hangs off a `vX.Y.Z` tag, checks again and publishes to
153
+ npmjs.com. There is no build step: the layer ships as raw source and Nuxt
154
+ compiles it in the consumer.
139
155
 
140
156
  ```bash
141
- npm version patch # hebt die package.json und setzt den Tag
157
+ npm version patch # bumps package.json and sets the tag
142
158
  git push --follow-tags
143
159
  ```
144
160
 
145
- Der Job vergleicht den Tag mit der Zahl in der `package.json` und bricht ab,
146
- wenn die beiden auseinanderlaufen. Veröffentlicht wird mit `--provenance`:
147
- auf npmjs steht dann nachprüfbar, aus welchem Commit das Paket stammt.
148
-
149
- Dafür braucht das Repo ein Secret `NPM_TOKEN` — ein Automation-Token aus dem
150
- npm-Konto, einzutragen unter *Settings → Secrets and variables → Actions*.
161
+ The job compares the tag against the number in `package.json` and stops if they
162
+ disagree. Publishing runs over OIDC through npm's trusted publishing — no token
163
+ in the repository — and with `--provenance`, so npmjs records which commit the
164
+ package was built from.
151
165
 
152
- ## Herkunft
166
+ ## Origin
153
167
 
154
- Entstanden in einem Verwaltungs-Frontend und dort über Monate in Gebrauch,
155
- bevor es hier ein eigenes Paket wurde.
168
+ Grown inside an admin frontend and in use there for months before it became a
169
+ package of its own.
156
170
 
157
- ## Lizenz
171
+ ## License
158
172
 
159
- MIT — siehe [LICENSE](LICENSE).
173
+ MIT — see [LICENSE](LICENSE).
package/app/composables/useBaseKit.ts CHANGED
@@ -16,11 +16,15 @@ import { computed, inject, type ComputedRef, type InjectionKey } from 'vue'
16
16
  * export default defineNuxtPlugin((nuxtApp) => {
17
17
  * const config = computed(() => ({
18
18
  * locale: 'de-DE',
19
- * labels: { ...BASEKIT_DEFAULTS.labels, search: 'Suchen' },
19
+ * labels: { ...BASEKIT_DEFAULTS.labels, search: 'Suchen', cancel: 'Abbrechen' },
20
20
  * }))
21
21
  * nuxtApp.vueApp.provide(baseKitKey, config)
22
22
  * })
23
23
  *
24
+ * Wer eine andere Sprache fährt, überschreibt die Tabelle vollständig — die
25
+ * Voreinstellung unten ist englisch und deckt nur den Fall ab, dass niemand
26
+ * etwas bereitstellt.
27
+ *
24
28
  * Wer nichts bereitstellt, bekommt die Voreinstellungen unten. Wichtig, wenn
25
29
  * die Werte aus einer i18n-Bibliothek kommen: `useI18n()` verlangt einen
26
30
  * Komponenten-Setup-Kontext und wirft im Plugin. Die Instanz gehört über
@@ -93,45 +97,46 @@ export interface BaseKitConfig {
93
97
  }
94
98
 
95
99
  /**
96
- * Voreinstellung: deutsch. Alle Projekte im Haus sind es, und eine Anwendung
97
- * mit mehreren Sprachen überschreibt die Tabelle ohnehin komplett.
100
+ * Voreinstellung: englisch. Das Paket weiß nicht, in welcher Sprache die
101
+ * Anwendung läuft, und Englisch ist die Sprache, die am wenigsten Leser
102
+ * ausschließt. Wer deutsch fährt, reicht `BASEKIT_DEFAULTS_DE` herein.
98
103
  */
99
104
  export const BASEKIT_DEFAULTS: BaseKitConfig = {
100
- locale: 'de-DE',
105
+ locale: 'en-US',
101
106
  labels: {
102
- search: 'Suchen',
103
- all: 'Alle',
104
- select: 'Auswählen',
105
- change: 'Ändern',
106
- edit: 'Bearbeiten',
107
- cancel: 'Abbrechen',
108
- confirm: 'Bestätigen',
109
- confirmTitle: 'Sind Sie sicher?',
110
- confirmBody: 'Diese Aktion lässt sich nicht rückgängig machen.',
111
- empty: 'Noch nichts vorhanden',
112
- noResults: 'Keine Treffer',
113
- noResultsHint: 'Andere Schreibweise oder weniger Filter probieren.',
114
- back: 'Zurück zur Übersicht',
115
- view: 'Ansehen',
116
- upload: 'Datei wählen',
117
- perPage: 'pro Seite',
118
- iconChoose: 'Symbol wählen',
119
- iconEmpty: 'Kein Symbol gefunden',
120
- iconClear: 'Kein Symbol',
121
- chartAsTable: 'Als Tabelle',
122
- chartAsChart: 'Als Diagramm',
123
- paginationRange: ({ from, to, total }) => `${from}–${to} von ${total}`,
107
+ search: 'Search',
108
+ all: 'All',
109
+ select: 'Select',
110
+ change: 'Change',
111
+ edit: 'Edit',
112
+ cancel: 'Cancel',
113
+ confirm: 'Confirm',
114
+ confirmTitle: 'Are you sure?',
115
+ confirmBody: 'This action cannot be undone.',
116
+ empty: 'Nothing here yet',
117
+ noResults: 'No matches',
118
+ noResultsHint: 'Try a different spelling or fewer filters.',
119
+ back: 'Back to overview',
120
+ view: 'View',
121
+ upload: 'Choose file',
122
+ perPage: 'per page',
123
+ iconChoose: 'Choose icon',
124
+ iconEmpty: 'No icon found',
125
+ iconClear: 'No icon',
126
+ chartAsTable: 'As table',
127
+ chartAsChart: 'As chart',
128
+ paginationRange: ({ from, to, total }) => `${from}–${to} of ${total}`,
124
129
  markdown: {
125
- bold: 'Fett',
126
- italic: 'Kursiv',
127
- h2: 'Überschrift 2',
128
- h3: 'Überschrift 3',
129
- bullet: 'Liste',
130
- ordered: 'Nummerierte Liste',
131
- quote: 'Zitat',
130
+ bold: 'Bold',
131
+ italic: 'Italic',
132
+ h2: 'Heading 2',
133
+ h3: 'Heading 3',
134
+ bullet: 'Bullet list',
135
+ ordered: 'Numbered list',
136
+ quote: 'Quote',
132
137
  code: 'Code',
133
138
  link: 'Link',
134
- linkPrompt: 'Link-URL',
139
+ linkPrompt: 'Link URL',
135
140
  },
136
141
  },
137
142
  }
@@ -140,7 +145,7 @@ export const baseKitKey: InjectionKey<ComputedRef<BaseKitConfig>> = Symbol('base
140
145
 
141
146
  /**
142
147
  * Konfiguration für eine BaseKit-Komponente. Ohne bereitgestellten Wert
143
- * greifen die Voreinstellungen — die Komponente rendert dann auf Deutsch,
148
+ * greifen die Voreinstellungen — die Komponente rendert dann auf Englisch,
144
149
  * statt leere Beschriftungen zu zeigen.
145
150
  */
146
151
  export function useBaseKit(): ComputedRef<BaseKitConfig> {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "nuxt-ui-basekit",
3
- "version": "0.1.0",
3
+ "version": "0.2.0",
4
4
  "description": "Markenfreie Basis-Komponenten für Nuxt 4 auf Nuxt UI — Tabellen, Reiter, Diagramme, Auswahl und Leerzustände als Nuxt-Layer.",
5
5
  "keywords": [
6
6
  "nuxt",
@@ -42,7 +42,7 @@
42
42
  "peerDependencies": {
43
43
  "@nuxt/ui": "^4.0.0",
44
44
  "nuxt": "^4.0.0",
45
- "pinia": "^2.2.0 || ^3.0.0"
45
+ "pinia": "^2.2.0 || ^3.0.0 || ^4.0.0"
46
46
  },
47
47
  "dependencies": {
48
48
  "@tiptap/extension-link": "^3.27.0",
@@ -60,7 +60,7 @@
60
60
  "@vue/test-utils": "^2.4.10",
61
61
  "happy-dom": "^20.9.0",
62
62
  "nuxt": "^4.0.0",
63
- "pinia": "^2.2.4",
63
+ "pinia": "^4.0.0",
64
64
  "typescript": "^5.5.0",
65
65
  "vitest": "^4.1.6",
66
66
  "vue-tsc": "^2.1.0"