nuxt-ui-basekit 0.1.0

package/app/composables/useBaseKit.ts

@@ -0,0 +1,155 @@
+import { computed, inject, type ComputedRef, type InjectionKey } from 'vue'
+
+/**
+ * Der einzige Draht zwischen den BaseKit-Komponenten und der Anwendung,
+ * die sie einsetzt.
+ *
+ * Die Komponenten sollen in jedem Nuxt-Projekt laufen. Sie dürfen deshalb
+ * weder `vue-i18n` aufrufen noch Übersetzungsschlüssel kennen: `t('common.search')`
+ * gibt es nur in der einen Anwendung, die diesen Schlüssel führt, und ein
+ * Paket, das solche Schlüssel voraussetzt, ist keins.
+ *
+ * Stattdessen reicht die Anwendung Sprache und Beschriftungen einmal herein —
+ * in einem Plugin, das die Werte aus ihrer eigenen Quelle zieht:
+ *
+ *   // plugins/basekit.ts
+ *   export default defineNuxtPlugin((nuxtApp) => {
+ *     const config = computed(() => ({
+ *       locale: 'de-DE',
+ *       labels: { ...BASEKIT_DEFAULTS.labels, search: 'Suchen' },
+ *     }))
+ *     nuxtApp.vueApp.provide(baseKitKey, config)
+ *   })
+ *
+ * Wer nichts bereitstellt, bekommt die Voreinstellungen unten. Wichtig, wenn
+ * die Werte aus einer i18n-Bibliothek kommen: `useI18n()` verlangt einen
+ * Komponenten-Setup-Kontext und wirft im Plugin. Die Instanz gehört über
+ * `nuxtApp.$i18n` geholt, und zwar erst beim Lesen des `computed`.
+ *
+ * Über `provide`/`inject`, nicht über `useNuxtApp()`: so laufen die
+ * Komponenten auch in einem Vitest-Mount ohne Nuxt-Kontext, und unter SSR
+ * teilen sich zwei Anfragen nichts.
+ *
+ * Einzelne Beschriftungen bleiben weiterhin als Prop überschreibbar — hier
+ * steht nur, was ohne Zutun herauskommt.
+ */
+export interface BaseKitLabels {
+  /** Suchfeld über Listen und Auswahl-Dialogen. */
+  search: string
+  /** Filter-Eintrag „ohne Einschränkung". */
+  all: string
+  select: string
+  change: string
+  edit: string
+  cancel: string
+  confirm: string
+  /** Überschrift der Rückfrage, wenn der Aufrufer keine mitgibt. */
+  confirmTitle: string
+  /** Text der Rückfrage, wenn der Aufrufer keinen mitgibt. */
+  confirmBody: string
+  /** Leere Liste — es gibt noch nichts. */
+  empty: string
+  /** Leere Liste — die Suche greift, findet aber nichts. */
+  noResults: string
+  noResultsHint: string
+  back: string
+  view: string
+  upload: string
+  perPage: string
+  iconChoose: string
+  iconEmpty: string
+  /** Auswahl aufheben — im Symbolwähler die leere Wahl. */
+  iconClear: string
+  chartAsTable: string
+  chartAsChart: string
+  /** „1–25 von 300" — als Funktion, weil die Zahlen mitten im Satz stehen. */
+  paginationRange: (range: { from: number, to: number, total: number }) => string
+  /**
+   * Werkzeugleiste des Markdown-Editors. Eigene Gruppe, weil die Begriffe nur
+   * dort vorkommen und die obere Ebene sonst zur Hälfte aus ihnen bestünde.
+   */
+  markdown: {
+    bold: string
+    italic: string
+    h2: string
+    h3: string
+    bullet: string
+    ordered: string
+    quote: string
+    code: string
+    link: string
+    /** Abfrage beim Setzen eines Links. */
+    linkPrompt: string
+  }
+}
+
+export interface BaseKitConfig {
+  /**
+   * BCP-47-Kennung für `Intl` — steuert Tausendertrennung, Prozent- und
+   * Datumsformate in den Diagrammen.
+   */
+  locale: string
+  labels: BaseKitLabels
+}
+
+/**
+ * Voreinstellung: deutsch. Alle Projekte im Haus sind es, und eine Anwendung
+ * mit mehreren Sprachen überschreibt die Tabelle ohnehin komplett.
+ */
+export const BASEKIT_DEFAULTS: BaseKitConfig = {
+  locale: 'de-DE',
+  labels: {
+    search: 'Suchen',
+    all: 'Alle',
+    select: 'Auswählen',
+    change: 'Ändern',
+    edit: 'Bearbeiten',
+    cancel: 'Abbrechen',
+    confirm: 'Bestätigen',
+    confirmTitle: 'Sind Sie sicher?',
+    confirmBody: 'Diese Aktion lässt sich nicht rückgängig machen.',
+    empty: 'Noch nichts vorhanden',
+    noResults: 'Keine Treffer',
+    noResultsHint: 'Andere Schreibweise oder weniger Filter probieren.',
+    back: 'Zurück zur Übersicht',
+    view: 'Ansehen',
+    upload: 'Datei wählen',
+    perPage: 'pro Seite',
+    iconChoose: 'Symbol wählen',
+    iconEmpty: 'Kein Symbol gefunden',
+    iconClear: 'Kein Symbol',
+    chartAsTable: 'Als Tabelle',
+    chartAsChart: 'Als Diagramm',
+    paginationRange: ({ from, to, total }) => `${from}–${to} von ${total}`,
+    markdown: {
+      bold: 'Fett',
+      italic: 'Kursiv',
+      h2: 'Überschrift 2',
+      h3: 'Überschrift 3',
+      bullet: 'Liste',
+      ordered: 'Nummerierte Liste',
+      quote: 'Zitat',
+      code: 'Code',
+      link: 'Link',
+      linkPrompt: 'Link-URL',
+    },
+  },
+}
+
+export const baseKitKey: InjectionKey<ComputedRef<BaseKitConfig>> = Symbol('basekit')
+
+/**
+ * Konfiguration für eine BaseKit-Komponente. Ohne bereitgestellten Wert
+ * greifen die Voreinstellungen — die Komponente rendert dann auf Deutsch,
+ * statt leere Beschriftungen zu zeigen.
+ */
+export function useBaseKit(): ComputedRef<BaseKitConfig> {
+  const provided = inject(baseKitKey, null)
+  return provided ?? computed(() => BASEKIT_DEFAULTS)
+}
+
+/** Kurzform für den häufigen Fall, dass nur die Beschriftungen gebraucht werden. */
+export function useBaseKitLabels(): ComputedRef<BaseKitLabels> {
+  const config = useBaseKit()
+  return computed(() => config.value.labels)
+}

package/app/composables/useChartPalette.ts

@@ -0,0 +1,89 @@
+import { computed } from 'vue'
+import { useBaseKit } from './useBaseKit'
+
+/**
+ * Reihenfarben und Zahlenformate für die `BaseKitChart*`-Komponenten.
+ *
+ * Die Farben stehen als CSS-Variablen in `main.css` und sind als **Satz**
+ * geprüft — Reihenfolge inklusive. Deshalb gibt es hier nur einen Zugriff per
+ * Index und keine Erzeugung: eine sechste Farbe wäre unter einer
+ * Farbfehlsichtigkeit von einer der fünf nicht mehr zu unterscheiden.
+ * Wer mehr Reihen hat, fasst zusammen.
+ */
+export const BASEKIT_CHART_SLOTS = 5
+
+/** Farbe für Reihe `index` (0-basiert). Ab Slot 6 die zurückgenommene Graustufe. */
+export function baseKitChartColor(index: number): string {
+  return index < BASEKIT_CHART_SLOTS
+    ? `var(--basekit-chart-${index + 1})`
+    : 'var(--basekit-chart-muted)'
+}
+
+export function useChartFormat(): {
+  number: (value: number) => string
+  compact: (value: number) => string
+  percent: (value: number, total: number) => string
+  bytes: (value: number) => string
+  duration: (seconds: number) => string
+} {
+  const config = useBaseKit()
+  const locale = computed(() => config.value.locale)
+
+  function number(value: number): string {
+    return new Intl.NumberFormat(locale.value).format(value)
+  }
+
+  /** Für Werte an Marken und in Kacheln: 12.400 → 12,4 Tsd. */
+  function compact(value: number): string {
+    return value < 10000
+      ? number(value)
+      : new Intl.NumberFormat(locale.value, { notation: 'compact', maximumFractionDigits: 1 }).format(value)
+  }
+
+  /**
+   * Anteil in Prozent. Abgerundet, solange nicht alles erreicht ist — sonst
+   * würde 9.999 von 10.000 als „100 %" durchgehen und die eine fehlende
+   * Übersetzung wäre weggerundet.
+   */
+  function percent(value: number, total: number): string {
+    if (total <= 0) return '—'
+    if (value >= total) {
+      return new Intl.NumberFormat(locale.value, { style: 'percent', maximumFractionDigits: 0 })
+        .format(1)
+    }
+
+    const exact = (value / total) * 100
+    const floored = Math.floor(exact * 10) / 10
+    return new Intl.NumberFormat(locale.value, {
+      style: 'percent',
+      maximumFractionDigits: 1,
+    }).format(floored / 100)
+  }
+
+  /**
+   * Dezimalpräfixe (kB, MB, GB) — nicht KiB/MiB. Speicheranbieter rechnen so
+   * ab, und die Zahl soll zu der auf der Rechnung passen.
+   */
+  function bytes(value: number): string {
+    const units = ['B', 'kB', 'MB', 'GB', 'TB']
+    let size = Math.max(0, value)
+    let unit = 0
+    while (size >= 1000 && unit < units.length - 1) {
+      size /= 1000
+      unit++
+    }
+    const digits = unit === 0 ? 0 : (size < 10 ? 1 : 0)
+    return `${new Intl.NumberFormat(locale.value, { maximumFractionDigits: digits }).format(size)} ${units[unit]}`
+  }
+
+  /** Laufzeit als „14 h 20 min", unter einer Stunde nur Minuten. */
+  function duration(seconds: number): string {
+    const total = Math.max(0, Math.round(seconds / 60))
+    const hours = Math.floor(total / 60)
+    const minutes = total % 60
+    if (hours === 0) return `${number(minutes)} min`
+    return minutes === 0 ? `${number(hours)} h` : `${number(hours)} h ${number(minutes)} min`
+  }
+
+  return { number, compact, percent, bytes, duration }
+}

package/app/composables/useChartWidth.ts

@@ -0,0 +1,41 @@
+import { onBeforeUnmount, onMounted, ref, type Ref } from 'vue'
+
+/**
+ * Misst die Breite eines Containers, damit ein SVG in echten Pixeln zeichnen
+ * kann statt über eine skalierte `viewBox`.
+ *
+ * Der Unterschied ist die Schrift: eine `viewBox`, die auf Containerbreite
+ * hochgerechnet wird, zieht Achsenbeschriftung und Werte mit hoch — auf einer
+ * breiten Karte steht dann 15-px-Text, wo 11 gemeint waren. Mit gemessener
+ * Breite bleibt Text Text und nur die Geometrie wächst.
+ *
+ * Vor dem Mounten (SSR, erster Frame) gilt `fallback`. Das Diagramm ist damit
+ * sofort da und rückt einmal zurecht, statt zu flackern.
+ */
+export function useChartWidth(fallback = 640): {
+  el: Ref<HTMLElement | null>
+  width: Ref<number>
+} {
+  const el = ref<HTMLElement | null>(null)
+  const width = ref(fallback)
+  let observer: ResizeObserver | null = null
+
+  onMounted(() => {
+    if (!el.value || typeof ResizeObserver === 'undefined') return
+
+    observer = new ResizeObserver((entries) => {
+      const measured = entries[0]?.contentRect.width ?? 0
+      // Unter 240 px wird die Geometrie unbrauchbar; dann lieber schmal
+      // zeichnen und den Container scrollen lassen.
+      if (measured > 0) width.value = Math.max(240, Math.round(measured))
+    })
+    observer.observe(el.value)
+  })
+
+  onBeforeUnmount(() => {
+    observer?.disconnect()
+    observer = null
+  })
+
+  return { el, width }
+}

package/app/composables/useConfirm.ts

@@ -0,0 +1,16 @@
+import { useConfirmStore } from '../stores/confirm'
+import type { BaseKitConfirmOptions } from '../stores/confirm'
+
+/**
+ * Bestätigungsabfrage als Ersatz für natives `window.confirm`.
+ *
+ * Öffnet das global gemountete `BaseKitConfirmModal` und liefert ein Promise,
+ * das mit `true`/`false` auflöst.
+ *
+ *   const confirm = useConfirm()
+ *   if (!(await confirm({ description: t('…'), color: 'error', confirmLabel: t('common.delete') }))) return
+ */
+export function useConfirm(): (opts?: BaseKitConfirmOptions) => Promise<boolean> {
+  const store = useConfirmStore()
+  return (opts?: BaseKitConfirmOptions) => store.ask(opts)
+}

package/app/stores/confirm.ts

@@ -0,0 +1,56 @@
+import { defineStore } from 'pinia'
+import { ref } from 'vue'
+
+/** Optionen für eine Bestätigungsabfrage. */
+export interface BaseKitConfirmOptions {
+  /** Titel des Dialogs (Default: `common.confirm.title`). */
+  title?: string
+  /** Erklärtext / Konsequenz — bei Destruktivem ausformulieren. */
+  description?: string
+  /** Beschriftung des Bestätigen-Buttons (Default: `common.confirm.confirm`). */
+  confirmLabel?: string
+  /** Beschriftung des Abbrechen-Buttons (Default: `common.cancel`). */
+  cancelLabel?: string
+  /** Farbe des Bestätigen-Buttons — `error` für destruktive Aktionen. */
+  color?: 'error' | 'primary'
+  /** Optionales Icon am Bestätigen-Button. */
+  icon?: string
+}
+
+/**
+ * Zentraler Bestätigungs-Store — ersetzt native `window.confirm`-Dialoge durch
+ * eine gethemte, dark-mode-fähige Abfrage.
+ *
+ * `ask()` öffnet das global gemountete `BaseKitConfirmModal` und liefert ein
+ * Promise, das mit `true` (bestätigt) oder `false` (abgebrochen/geschlossen)
+ * auflöst. Der Resolver lebt außerhalb der Reaktivität, damit genau eine
+ * Antwort pro Abfrage zurückgeht.
+ *
+ * Genutzt über das Composable `useConfirm()`:
+ *   const confirm = useConfirm()
+ *   if (!(await confirm({ description: t('…'), color: 'error' }))) return
+ */
+export const useConfirmStore = defineStore('basekit:confirm', () => {
+  const open = ref(false)
+  const options = ref<BaseKitConfirmOptions>({})
+  let resolver: ((value: boolean) => void) | null = null
+
+  function ask(opts: BaseKitConfirmOptions = {}): Promise<boolean> {
+    // Läuft noch eine Abfrage, wird sie als abgebrochen aufgelöst.
+    resolver?.(false)
+    options.value = opts
+    open.value = true
+    return new Promise<boolean>((resolve) => {
+      resolver = resolve
+    })
+  }
+
+  /** Abfrage beantworten und Dialog schließen. */
+  function settle(value: boolean): void {
+    open.value = false
+    resolver?.(value)
+    resolver = null
+  }
+
+  return { open, options, ask, settle }
+})

package/app/utils/html-to-markdown.ts

@@ -0,0 +1,47 @@
+/**
+ * HTML → Markdown (turndown). Zwei Einsätze, beide nur im Admin/Editor — daher
+ * bewusst getrennt von `markdown.ts` (das im öffentlichen Widget-Bundle steckt
+ * und turndown nicht mitziehen soll):
+ *   - Tiptap speichert HTML → hier nach Markdown serialisieren.
+ *   - Legacy-Text-Blöcke mit rohem `config.html` einmalig nach Markdown wandeln.
+ *
+ * **turndown wird bewusst erst beim ersten Aufruf geladen.** Das Paket ist
+ * CommonJS; ein Import auf Modulebene landet im Server-Bundle und wirft dort
+ * beim Rendern „require is not defined in ES module scope". Der Editor läuft
+ * ohnehin nur im Browser — auf dem Server wird die Funktion nie aufgerufen.
+ */
+type Turndown = { turndown: (html: string) => string }
+
+let instance: Turndown | null = null
+
+function service(): Turndown | null {
+  if (instance) return instance
+  if (import.meta.server) return null
+
+  // Synchroner Zugriff auf ein bereits geladenes Modul: der Editor ruft
+  // `prepare()` beim Einhängen auf, bevor gespeichert werden kann.
+  return instance
+}
+
+/**
+ * Lädt turndown im Browser vor. Die Editor-Komponenten rufen das beim
+ * Einhängen auf, damit {@link htmlToMarkdown} danach synchron bleiben kann.
+ */
+export async function prepareHtmlToMarkdown(): Promise<void> {
+  if (instance || import.meta.server) return
+  const { default: TurndownService } = await import('turndown')
+  instance = new TurndownService({
+    headingStyle: 'atx',
+    codeBlockStyle: 'fenced',
+    bulletListMarker: '-',
+  }) as Turndown
+}
+
+export function htmlToMarkdown(html?: string | null): string {
+  if (!html) return ''
+  const td = service()
+  // Ohne geladenes turndown (Server, oder prepare() vergessen) lieber das
+  // Original zurückgeben als eine Ausnahme zu werfen — der Text ginge sonst
+  // beim Speichern verloren.
+  return td ? td.turndown(String(html)).trim() : String(html)
+}

package/app/utils/markdown.ts

@@ -0,0 +1,24 @@
+import MarkdownIt from 'markdown-it'
+
+/**
+ * Markdown → HTML für den Text-Block (`richtext`-Widget, jetzt Markdown).
+ *
+ * Bewusst `html: false`: roher HTML im Markdown wird NICHT durchgereicht — das
+ * schließt die wichtigste XSS-Lücke ohne separaten Sanitizer (markdown-it
+ * blockt zudem `javascript:`-Links per Default-`validateLink`). `linkify` macht
+ * nackte URLs klickbar, `typographer` glättet Anführungszeichen/Bindestriche.
+ *
+ * Geteilt zwischen Anzeige und Editor-Vorschau, damit
+ * Bearbeiten und Ausgabe identisch aussehen.
+ */
+const md: MarkdownIt = new MarkdownIt({
+  html: false,
+  linkify: true,
+  typographer: true,
+  breaks: false,
+})
+
+export function renderMarkdown(source?: string | null): string {
+  if (!source) return ''
+  return md.render(String(source))
+}

package/nuxt.config.ts

@@ -0,0 +1,43 @@
+import { fileURLToPath } from 'node:url'
+
+/**
+ * BaseKit als Nuxt-Layer.
+ *
+ * Der Layer registriert die Komponenten global und meldet die Composables und
+ * den Store für die Auto-Imports an. Er bringt bewusst **kein** UI-Modul mit:
+ * `@nuxt/ui` und `pinia` sind Peers, weil sie im Konsumenten ohnehin stehen
+ * und zwei Instanzen desselben Moduls sich in die Quere kommen.
+ *
+ * Die CSS-Datei trägt die Voreinstellungen der `--basekit-*`-Token. Wer eigene
+ * Farben führt, überschreibt sie in seinem eigenen Stylesheet — das nach
+ * diesem geladen wird.
+ */
+export default defineNuxtConfig({
+  $meta: {
+    name: 'nuxt-ui-basekit',
+  },
+
+  css: ['nuxt-ui-basekit/app/assets/css/basekit.css'],
+
+  // Ohne Pfad-Präfix registrieren: `app/components/charts/BaseKitChartDonut.vue`
+  // wird zu `<BaseKitChartDonut>`, nicht `<ChartsBaseKitChartDonut>`.
+  // Absoluter Pfad, weil `~/components` im Konsumenten auf dessen Ordner
+  // zeigen würde.
+  components: [
+    {
+      path: fileURLToPath(new URL('./app/components', import.meta.url)),
+      pathPrefix: false,
+    },
+  ],
+
+  imports: {
+    dirs: [
+      fileURLToPath(new URL('./app/composables', import.meta.url)),
+      fileURLToPath(new URL('./app/stores', import.meta.url)),
+    ],
+  },
+
+  alias: {
+    'nuxt-ui-basekit': fileURLToPath(new URL('./', import.meta.url)),
+  },
+})

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "nuxt-ui-basekit",
+  "version": "0.1.0",
+  "description": "Markenfreie Basis-Komponenten für Nuxt 4 auf Nuxt UI — Tabellen, Reiter, Diagramme, Auswahl und Leerzustände als Nuxt-Layer.",
+  "keywords": [
+    "nuxt",
+    "nuxt-layer",
+    "nuxt-ui",
+    "vue",
+    "components",
+    "charts",
+    "data-table"
+  ],
+  "type": "module",
+  "engines": {
+    "node": ">=24"
+  },
+  "main": "./nuxt.config.ts",
+  "files": [
+    "app",
+    "nuxt.config.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./nuxt.config.ts",
+      "import": "./nuxt.config.ts"
+    },
+    "./labels": "./app/composables/useBaseKit.ts",
+    "./app/*.vue": "./app/*.vue",
+    "./app/*.css": "./app/*.css",
+    "./app/*": "./app/*.ts",
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "dev:prepare": "nuxi prepare",
+    "lint": "nuxi typecheck",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "peerDependencies": {
+    "@nuxt/ui": "^4.0.0",
+    "nuxt": "^4.0.0",
+    "pinia": "^2.2.0 || ^3.0.0"
+  },
+  "dependencies": {
+    "@tiptap/extension-link": "^3.27.0",
+    "@tiptap/pm": "^3.27.0",
+    "@tiptap/starter-kit": "^3.27.0",
+    "@tiptap/vue-3": "^3.27.0",
+    "markdown-it": "^14.2.0",
+    "turndown": "^7.2.4"
+  },
+  "devDependencies": {
+    "@nuxt/ui": "^4.7.1",
+    "@types/markdown-it": "^14.1.2",
+    "@types/turndown": "^5.0.6",
+    "@vitejs/plugin-vue": "^6.0.6",
+    "@vue/test-utils": "^2.4.10",
+    "happy-dom": "^20.9.0",
+    "nuxt": "^4.0.0",
+    "pinia": "^2.2.4",
+    "typescript": "^5.5.0",
+    "vitest": "^4.1.6",
+    "vue-tsc": "^2.1.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/McGo/nuxt-ui-basekit.git"
+  },
+  "homepage": "https://github.com/McGo/nuxt-ui-basekit#readme",
+  "bugs": {
+    "url": "https://github.com/McGo/nuxt-ui-basekit/issues"
+  },
+  "author": "Mirko Haaser <kontakt@mirko-haaser.de>",
+  "license": "MIT"
+}