nuxt-ui-basekit 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mirko Haaser
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,159 @@
+# nuxt-ui-basekit
+
+Basis-Komponenten für Nuxt 4 auf [Nuxt UI](https://ui.nuxt.com) — als Nuxt-Layer.
+Tabellen, Reiter, Diagramme, Auswahl-Dialoge, Leerzustände: die Bausteine, die
+in jedem Verwaltungs-Frontend wieder anfallen und die Nuxt UI nicht mitbringt.
+
+Das Paket kennt keine Anwendung. Es hat keine Stores außer einem für die
+Rückfrage, keine Endpunkte, keine Übersetzungsschlüssel und keine Farben, die
+zu einer Marke gehören. Was es anzeigt, bekommt es hereingereicht.
+
+## Einbinden
+
+```bash
+npm i -D nuxt-ui-basekit
+```
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  extends: ['nuxt-ui-basekit'],
+})
+```
+
+`@nuxt/ui`, `nuxt` und `pinia` sind Peers, sie stehen im Konsumenten und
+werden nicht mitgeliefert. Die Komponenten sind danach global verfügbar, ohne
+Import.
+
+## Was drin ist
+
+| Gruppe | Komponenten |
+|---|---|
+| Struktur | `BaseKitTabs` · `BaseKitSettingRow` · `BaseKitEmptyState` · `BaseKitChoiceCard` · `BaseKitPending` |
+| Listen | `BaseKitDataTable` · `BaseKitStatTile` |
+| Auswahl | `BaseKitRecordPicker` · `BaseKitIconPicker` · `BaseKitFileUpload` |
+| Wege | `BaseKitBackLink` · `BaseKitViewLink` |
+| Rückfrage | `BaseKitConfirmModal` + `useConfirm()` |
+| Text | `BaseKitMarkdownEditor` |
+| Diagramme | `BaseKitChartBars` · `-Columns` · `-Donut` · `-Meter` · `-Figure` |
+
+Jede Komponente trägt ihre Erklärung im Kopf der Datei — was sie tut, wann sie
+die richtige Wahl ist und wann nicht.
+
+## Beschriftungen und Sprache
+
+Die Komponenten rufen kein `vue-i18n` auf und kennen keine
+Übersetzungsschlüssel. Ohne Zutun rendern sie deutsche Voreinstellungen; wer
+eigene Texte oder mehrere Sprachen führt, reicht sie über ein Plugin herein:
+
+```ts
+// plugins/basekit.ts
+import { computed } from 'vue'
+import { baseKitKey, BASEKIT_DEFAULTS } from 'nuxt-ui-basekit/labels'
+
+export default defineNuxtPlugin((nuxtApp) => {
+  const config = computed(() => {
+    const { t, locale } = nuxtApp.$i18n as Composer
+
+    return {
+      locale: locale.value,
+      labels: { ...BASEKIT_DEFAULTS.labels, search: t('common.search') },
+    }
+  })
+
+  nuxtApp.vueApp.provide(baseKitKey, config)
+})
+```
+
+Zwei Dinge, die dabei Zeit kosten können:
+
+- **`useI18n()` gehört nicht ins Plugin.** Es verlangt einen
+  Komponenten-Setup-Kontext und wirft dort `MUST_BE_CALL_SETUP_TOP`
+  (Fehlercode 26). Beim serverseitigen Rendern heißt das: 500 auf jeder Seite.
+  Die Instanz kommt über `nuxtApp.$i18n`, und zwar erst beim Lesen des
+  `computed` — dann ist auch die Plugin-Reihenfolge gleichgültig.
+- **Einzelne Beschriftungen** bleiben als Prop überschreibbar. Die Tabelle
+  trägt nur, was ohne Angabe herauskommt.
+
+## Farben
+
+Die Komponenten greifen ausschließlich auf `--basekit-*` zu. Die
+Voreinstellungen stehen in `app/assets/css/basekit.css` und werden vom Layer
+geladen. Ein Projekt mit eigenem Theme legt sie in seinem eigenen Stylesheet
+darauf:
+
+```css
+:root {
+  --basekit-accent: var(--meine-markenfarbe, #2563eb);
+  --basekit-surface: var(--meine-kartenflaeche, #ffffff);
+}
+```
+
+Die fünf Diagrammfarben sind als Satz geprüft — Lichtheitsband, Chroma und
+Abstand zwischen Nachbarn, auch unter Farbfehlsichtigkeit. Wer sie
+überschreibt, sollte das als Satz tun und nicht einzeln; wer mehr als fünf
+Reihen hat, fasst zusammen, statt eine sechste Farbe zu erfinden.
+
+## Entwickeln
+
+```bash
+npm install
+npx nuxi prepare     # erzeugt .nuxt/tsconfig.json, sonst laufen die Tests nicht
+npm test
+npm run lint         # nuxi typecheck
+```
+
+`tests/grenze.test.ts` hält fest, was das Paket nicht darf: keine Importe
+außerhalb des Pakets, keine Abhängigkeit, die nicht in der `package.json`
+steht, kein `vue-i18n`, keine Übersetzungsschlüssel, keine fremden
+CSS-Variablen. Der Test ist der Grund, warum sich das Paket überhaupt
+herausschneiden ließ — ohne ihn wäre die Trennung nach dem dritten Feature
+wieder zu.
+
+### Lockfile
+
+Wer auf macOS oder Windows eine Abhängigkeit hinzufügt, muss das Lockfile
+anschließend einmal unter Linux/x64 nachziehen — sonst fehlen die
+plattformspezifischen Optional-Pakete (`@emnapi/*` und Verwandtschaft), und
+`npm ci` im Workflow bricht ab:
+
+```bash
+docker run --rm --platform linux/amd64 -v "$PWD:/app" -w /app \
+  node:24 npm install --package-lock-only
+```
+
+Die Architektur ist nicht gleichgültig: auf Apple Silicon läuft der Container
+ohne `--platform` als arm64, und dann fehlen genau die x64-Varianten, die der
+Runner braucht. Danach lokal einmal `npm ci`, das holt die eigenen Binaries
+zurück.
+
+## Veröffentlichen
+
+Zwei Workflows unter `.github/workflows`. `pruefen` läuft auf `main` und in
+jedem Pull Request und führt `nuxi prepare`, `nuxi typecheck` und die Tests
+aus. `veroeffentlichen` hängt an einem Tag `vX.Y.Z`, prüft noch einmal und
+schiebt das Paket dann nach npmjs.com. Ein Build-Schritt fehlt, weil der Layer
+als Rohquelle ausgeliefert wird und Nuxt ihn im Konsumenten übersetzt.
+
+Eine neue Fassung:
+
+```bash
+npm version patch        # hebt die package.json und setzt den Tag
+git push --follow-tags
+```
+
+Der Job vergleicht den Tag mit der Zahl in der `package.json` und bricht ab,
+wenn die beiden auseinanderlaufen. Veröffentlicht wird mit `--provenance`:
+auf npmjs steht dann nachprüfbar, aus welchem Commit das Paket stammt.
+
+Dafür braucht das Repo ein Secret `NPM_TOKEN` — ein Automation-Token aus dem
+npm-Konto, einzutragen unter *Settings → Secrets and variables → Actions*.
+
+## Herkunft
+
+Entstanden in einem Verwaltungs-Frontend und dort über Monate in Gebrauch,
+bevor es hier ein eigenes Paket wurde.
+
+## Lizenz
+
+MIT — siehe [LICENSE](LICENSE).

package/app/assets/css/basekit.css

@@ -0,0 +1,86 @@
+/* ==========================================================================
+ * BaseKit — Gestaltungs-Token
+ *
+ * Die Komponenten greifen ausschließlich auf `--basekit-*` zu und nie auf
+ * Variablen einer bestimmten Anwendung. Hier stehen die Voreinstellungen.
+ *
+ * Eine Anwendung mit eigenem Theme legt die Token an einer Stelle auf ihre
+ * eigenen Variablen — ein Block in ihrem Stylesheet, geladen nach diesem:
+ *
+ *   :root {
+ *     --basekit-accent: var(--meine-markenfarbe, #2563eb);
+ *     --basekit-surface: var(--meine-kartenflaeche, #ffffff);
+ *   }
+ *
+ * Fällt der Block weg, rendern die Komponenten in den Werten von hier weiter.
+ * ========================================================================== */
+
+:root {
+  --basekit-surface: #ffffff;
+  --basekit-surface-muted: #f4f6fa;
+  --basekit-border: #e5e8ee;
+  --basekit-border-strong: #d6dbe4;
+  --basekit-text: #101828;
+  --basekit-text-muted: #667085;
+  --basekit-accent: #2563eb;
+  --basekit-accent-text: #ffffff;
+  --basekit-chrome: #0b2239;
+  --basekit-chrome-text: rgb(255 255 255 / 82%);
+}
+
+.dark {
+  --basekit-surface: #101828;
+  --basekit-surface-muted: #0b1220;
+  --basekit-border: #1f2937;
+  --basekit-border-strong: #374151;
+  --basekit-text: #e5e7eb;
+  --basekit-text-muted: #9ca3af;
+}
+
+/* --------------------------------------------------------------------------
+ * Diagramm-Farben (BaseKitChart*)
+ *
+ * Bewusst **nicht** aus der Markenfarbe abgeleitet. Ein Theme darf jede
+ * Akzentfarbe tragen — vier davon nebeneinander in einer gestapelten Fläche
+ * ergäben Reihen, die man nicht mehr auseinanderhält, und bei einer
+ * Rot-Grün-Schwäche gar nichts mehr. Die fünf Reihenfarben stehen deshalb
+ * fest und sind gegen die Kartenfläche geprüft (Lichtheitsband, Chroma,
+ * CVD-Abstand ΔE ≥ 8 zwischen Nachbarn, Normalsicht ΔE ≥ 15).
+ *
+ * Reihenfolge ist Teil der Prüfung: wer sie umsortiert oder eine sechste
+ * Farbe dazustellt, muss neu messen. Über fünf Reihen fasst die Übersicht
+ * zusammen, statt eine Farbe zu erfinden.
+ *
+ * Ein Kundenprojekt darf die Werte überschreiben — dann aber bitte als
+ * geprüften Satz und nicht einzeln.
+ * ------------------------------------------------------------------------ */
+:root {
+  --basekit-chart-1: #2a78d6;
+  --basekit-chart-2: #eb6834;
+  --basekit-chart-3: #1baf7a;
+  --basekit-chart-4: #eda100;
+  --basekit-chart-5: #e87ba4;
+
+  /* Die Fläche, in der ein Diagramm sitzt. Trägt die 2-px-Lücke zwischen
+   * gestapelten Segmenten und den Ring um Punkte — deshalb muss sie der
+   * Kartenfarbe entsprechen und nicht „irgendwie weiß" sein. */
+  --basekit-chart-surface: var(--ui-bg, #ffffff);
+  --basekit-chart-grid: rgb(0 0 0 / 8%);
+  --basekit-chart-axis: rgb(0 0 0 / 18%);
+  /* Zurückgenommene Reihe: Kontext, nicht Aussage. */
+  --basekit-chart-muted: rgb(0 0 0 / 22%);
+}
+
+.dark {
+  --basekit-chart-1: #3987e5;
+  --basekit-chart-2: #d95926;
+  --basekit-chart-3: #199e70;
+  --basekit-chart-4: #c98500;
+  --basekit-chart-5: #d55181;
+
+  --basekit-chart-surface: var(--ui-bg, #1e293b);
+  --basekit-chart-grid: rgb(255 255 255 / 10%);
+  --basekit-chart-axis: rgb(255 255 255 / 22%);
+  --basekit-chart-muted: rgb(255 255 255 / 28%);
+}
+

package/app/components/BaseKitBackLink.vue

@@ -0,0 +1,41 @@
+<script setup lang="ts">
+/**
+ * Rücksprung von einer Detailseite zur zugehörigen Liste.
+ *
+ * Steht immer an derselben Stelle: oben rechts im Seitenkopf. Vorher hatte
+ * das jede Seite anders gelöst — mal ein Knopf über der Überschrift, mal ein
+ * kleiner Link darüber, mal ein Knopf rechts im Kopf, und beschriftet war er
+ * mal mit dem Namen der Liste („Rubriken"), mal mit „Zurück". Wer zwischen
+ * zwei Bereichen wechselt, sucht den Weg zurück dann jedes Mal neu.
+ *
+ * Die Beschriftung ist deshalb fest und nennt nicht das Ziel, sondern die
+ * Richtung. `label` überschreibt sie für die Fälle, in denen es nicht zu
+ * einer Liste zurückgeht, sondern zum übergeordneten Datensatz.
+ */
+import { computed } from 'vue'
+import { useBaseKitLabels } from '../composables/useBaseKit'
+
+const props = withDefaults(defineProps<{
+  to: string
+  label?: string
+}>(), {
+  label: undefined,
+})
+
+const labels = useBaseKitLabels()
+
+const text = computed(() => props.label ?? labels.value.back)
+</script>
+
+<template>
+  <UButton
+    :to="props.to"
+    icon="i-lucide-arrow-left"
+    size="sm"
+    color="neutral"
+    variant="ghost"
+    class="shrink-0"
+  >
+    {{ text }}
+  </UButton>
+</template>

package/app/components/BaseKitChoiceCard.vue

@@ -0,0 +1,107 @@
+<script setup lang="ts">
+/**
+ * Auswahl-Karte — Pattern für „aus einer Handvoll Varianten eine wählen“,
+ * wenn die Varianten sich zeigen lassen (Themes, Layouts, Vorlagen).
+ * Ein Dropdown zeigt nur Namen; hier steht die Vorschau daneben.
+ *
+ *  ┌──────────────────────────┐
+ *  │                          │  ← Slot `preview` (stilisierte Vorschau)
+ *  │        Vorschau          │
+ *  ├──────────────────────────┤
+ *  │ Titel          [ Aktiv ] │  ← aktiv: Badge, sonst Knopf „Übernehmen“
+ *  │ Beschreibung             │
+ *  └──────────────────────────┘
+ *
+ * Verwendung (Karten in einem Grid, eine pro Variante):
+ *
+ *   <div class="grid gap-4 sm:grid-cols-2 xl:grid-cols-3">
+ *     <BaseKitChoiceCard
+ *       v-for="o in options"
+ *       :key="o.id"
+ *       :title="o.label"
+ *       :active="o.id === activeId"
+ *       :active-label="t('common.active')"
+ *       :apply-label="t('common.apply')"
+ *       :pending="pending"
+ *       @apply="apply(o.id)"
+ *     >
+ *       <template #preview><MeineVorschau :id="o.id" /></template>
+ *     </BaseKitChoiceCard>
+ *   </div>
+ *
+ * Die Karte selbst löst nichts aus — gewählt wird über den Knopf. Bei einer
+ * Auswahl, die sofort für alle gilt, ist ein Klick daneben sonst schnell
+ * passiert.
+ */
+withDefaults(defineProps<{
+  /** Name der Variante. */
+  title: string
+  /** Kurze Erläuterung unter dem Titel. */
+  description?: string
+  /** Diese Variante ist die aktive. */
+  active?: boolean
+  /** Läuft gerade ein Speichervorgang (sperrt den Knopf). */
+  pending?: boolean
+  /** Beschriftung des Knopfes für „diese Variante übernehmen“. */
+  applyLabel?: string
+  /** Beschriftung des Aktiv-Kennzeichens. */
+  activeLabel?: string
+  /** Seitenverhältnis der Vorschaufläche. */
+  ratio?: string
+}>(), {
+  description: undefined,
+  active: false,
+  pending: false,
+  applyLabel: 'Übernehmen',
+  activeLabel: 'Aktiv',
+  ratio: 'aspect-[16/10]',
+})
+
+defineEmits<{ apply: [] }>()
+</script>
+
+<template>
+  <div
+    class="basekit-choice-card overflow-hidden rounded-lg border bg-white transition-colors dark:bg-neutral-900"
+    :class="active
+      ? 'border-primary-500 ring-1 ring-primary-500'
+      : 'border-neutral-200 dark:border-neutral-800'"
+    :aria-current="active ? 'true' : undefined"
+  >
+    <div :class="['overflow-hidden border-b border-neutral-200 dark:border-neutral-800', ratio]">
+      <slot name="preview" />
+    </div>
+
+    <div class="flex items-start justify-between gap-3 p-3">
+      <div class="min-w-0">
+        <h3 class="truncate text-sm font-medium">
+          {{ title }}
+        </h3>
+        <p v-if="description" class="mt-0.5 text-xs text-neutral-500">
+          {{ description }}
+        </p>
+      </div>
+
+      <UBadge
+        v-if="active"
+        color="primary"
+        variant="subtle"
+        icon="i-lucide-check"
+        class="shrink-0"
+      >
+        {{ activeLabel }}
+      </UBadge>
+      <UButton
+        v-else
+        size="xs"
+        color="neutral"
+        variant="subtle"
+        class="shrink-0"
+        :loading="pending"
+        @click="$emit('apply')"
+      >
+        {{ applyLabel }}
+      </UButton>
+    </div>
+  </div>
+</template>

package/app/components/BaseKitConfirmModal.vue

@@ -0,0 +1,55 @@
+<script setup lang="ts">
+/**
+ * Global gemountetes Bestätigungs-Modal — wird vom `basekit:confirm`-Store
+ * gesteuert (siehe `useConfirm()`). Genau eine Instanz pro Layout genügt,
+ * sie beantwortet alle Abfragen.
+ *
+ * Ersetzt native `window.confirm`-Dialoge: gethemt, dark-mode-fähig,
+ * destruktive Aktionen als roter Bestätigen-Button. Schließen ohne Klick
+ * (Escape/Backdrop) zählt als Abbruch.
+ */
+import { computed } from 'vue'
+import { useBaseKitLabels } from '../composables/useBaseKit'
+import { useConfirmStore } from '../stores/confirm'
+
+const store = useConfirmStore()
+const labels = useBaseKitLabels()
+
+const opts = computed(() => store.options)
+
+const open = computed({
+  get: () => store.open,
+  set: (value: boolean) => {
+    // Backdrop-/Escape-Schließen ohne Bestätigung → Abbruch.
+    if (!value) store.settle(false)
+  },
+})
+</script>
+
+<template>
+  <UModal
+    :open="open"
+    :title="opts.title ?? labels.confirmTitle"
+    :ui="{ content: 'max-w-md' }"
+    @update:open="open = $event"
+  >
+    <template #body>
+      <p class="text-sm text-muted">
+        {{ opts.description ?? labels.confirmBody }}
+      </p>
+      <div class="mt-6 flex justify-end gap-2">
+        <UButton type="button" color="neutral" variant="ghost" @click="store.settle(false)">
+          {{ opts.cancelLabel ?? labels.cancel }}
+        </UButton>
+        <UButton
+          type="button"
+          :color="opts.color ?? 'primary'"
+          :icon="opts.icon"
+          @click="store.settle(true)"
+        >
+          {{ opts.confirmLabel ?? labels.confirm }}
+        </UButton>
+      </div>
+    </template>
+  </UModal>
+</template>