nuxt-ui-basekit 0.2.0 → 0.2.1

package/app/components/charts/BaseKitChartFigure.vue

@@ -1,13 +1,13 @@
 <script setup lang="ts">
 /**
- * Rahmen für ein Diagramm: Karte, Titel, Legende und der Umschalter auf die
- * Tabellenansicht.
+ * The frame around a chart: card, title, legend, and the switch to the table
+ * view.
  *
- * Der Umschalter ist keine Zugabe. Ein Diagramm codiert Werte über Farbe und
- * Länge; wer davon nichts hat — Farbfehlsichtigkeit, Screenreader, Ausdruck —
- * braucht dieselben Zahlen in lesbarer Form. Deshalb bringt jede Karte hier
- * ihre Tabelle mit, und deshalb ist der Umschalter sichtbar und nicht in einem
- * Menü versteckt.
+ * That switch is not a nicety. A chart encodes values through colour and
+ * length; anyone who gets nothing out of that — a colour vision deficiency, a
+ * screen reader, a printout — needs the same numbers in readable form. Which
+ * is why every card here brings its table along, and why the switch is visible
+ * rather than buried in a menu.
  */
 import { computed, ref } from 'vue'
 import { useBaseKitLabels } from '../../composables/useBaseKit'
@@ -15,11 +15,11 @@ import { useBaseKitLabels } from '../../composables/useBaseKit'
 const props = withDefaults(defineProps<{
   title: string
   subtitle?: string
-  /** Wohin die Karte führt. Ohne Ziel bleibt der Titel ein Titel. */
+  /** Where the card leads. Without a target the title stays a title. */
   href?: string
-  /** Diagramm ausgrauen, während im Hintergrund nachgeladen wird. */
+  /** Grey the chart out while something reloads in the background. */
   stale?: boolean
-  /** Ohne Tabellen-Slot entfällt der Umschalter. */
+  /** Without a table slot the switch disappears. */
   tableAvailable?: boolean
 }>(), {
   subtitle: undefined,

package/app/components/charts/BaseKitChartMeter.vue

@@ -1,10 +1,10 @@
 <script setup lang="ts">
 /**
- * Ein Verhältnis gegen eine bekannte Grenze — „so viele von so vielen".
+ * A ratio against a known limit — this many of that many.
  *
- * Ein Meter setzt voraus, dass es ein Ganzes gibt. Wo keins existiert (Bytes
- * ohne Kontingent, Anzahl ohne Obergrenze), gehört die Zahl in eine Kachel und
- * nicht hierher; ein voller Balken behauptete sonst eine erreichte Grenze.
+ * A meter presupposes that a whole exists. Where none does — bytes without a
+ * quota, a count without a ceiling — the number belongs in a tile and not
+ * here; a full bar would otherwise claim a limit had been reached.
  */
 import { computed } from 'vue'
 import { baseKitChartColor, useChartFormat } from '../../composables/useChartPalette'

package/app/composables/useBaseKit.ts

@@ -1,16 +1,15 @@
 import { computed, inject, type ComputedRef, type InjectionKey } from 'vue'
 
 /**
- * Der einzige Draht zwischen den BaseKit-Komponenten und der Anwendung,
- * die sie einsetzt.
+ * The only wire between the BaseKit components and the application using them.
  *
- * 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.
+ * The components are meant to run in any Nuxt project. That rules out calling
+ * `vue-i18n` and it rules out knowing translation keys: `t('common.search')`
+ * exists only in the one application that carries that key, and a package
+ * which presupposes such keys is not a package.
  *
- * Stattdessen reicht die Anwendung Sprache und Beschriftungen einmal herein —
- * in einem Plugin, das die Werte aus ihrer eigenen Quelle zieht:
+ * Instead the application hands language and labels in once, from a plugin
+ * that pulls the values out of its own source:
  *
  *   // plugins/basekit.ts
  *   export default defineNuxtPlugin((nuxtApp) => {
@@ -21,39 +20,35 @@ import { computed, inject, type ComputedRef, type InjectionKey } from 'vue'
  *     nuxtApp.vueApp.provide(baseKitKey, config)
  *   })
  *
- * Wer eine andere Sprache fährt, überschreibt die Tabelle vollständig — die
- * Voreinstellung unten ist englisch und deckt nur den Fall ab, dass niemand
- * etwas bereitstellt.
+ * Provide nothing and the defaults below apply. One thing worth knowing when
+ * the values come from an i18n library: `useI18n()` requires a component setup
+ * context and throws inside a plugin. Take the instance from `nuxtApp.$i18n`,
+ * and only when the `computed` is read.
  *
- * 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`.
+ * Over `provide`/`inject` rather than `useNuxtApp()`: that way the components
+ * also run in a Vitest mount without a Nuxt context, and two requests share
+ * nothing under SSR.
  *
- * Ü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.
+ * Individual labels stay overridable as props — what follows only decides what
+ * comes out when nothing is passed.
  */
 export interface BaseKitLabels {
-  /** Suchfeld über Listen und Auswahl-Dialogen. */
+  /** Search field above lists and pickers. */
   search: string
-  /** Filter-Eintrag „ohne Einschränkung". */
+  /** Filter entry for "no restriction". */
   all: string
   select: string
   change: string
   edit: string
   cancel: string
   confirm: string
-  /** Überschrift der Rückfrage, wenn der Aufrufer keine mitgibt. */
+  /** Heading of the confirmation when the caller passes none. */
   confirmTitle: string
-  /** Text der Rückfrage, wenn der Aufrufer keinen mitgibt. */
+  /** Body of the confirmation when the caller passes none. */
   confirmBody: string
-  /** Leere Liste — es gibt noch nichts. */
+  /** Empty list — nothing exists yet. */
   empty: string
-  /** Leere Liste — die Suche greift, findet aber nichts. */
+  /** Empty list — the search ran and found nothing. */
   noResults: string
   noResultsHint: string
   back: string
@@ -62,15 +57,15 @@ export interface BaseKitLabels {
   perPage: string
   iconChoose: string
   iconEmpty: string
-  /** Auswahl aufheben — im Symbolwähler die leere Wahl. */
+  /** Clearing the choice — the empty option in the icon picker. */
   iconClear: string
   chartAsTable: string
   chartAsChart: string
-  /** „1–25 von 300" — als Funktion, weil die Zahlen mitten im Satz stehen. */
+  /** "1–25 of 300" — a function, because the numbers sit inside the sentence. */
   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.
+   * Toolbar of the Markdown editor. Its own group, because the terms occur
+   * nowhere else and the top level would otherwise be half made of them.
    */
   markdown: {
     bold: string
@@ -82,24 +77,24 @@ export interface BaseKitLabels {
     quote: string
     code: string
     link: string
-    /** Abfrage beim Setzen eines Links. */
+    /** Prompt shown when setting a link. */
     linkPrompt: string
   }
 }
 
 export interface BaseKitConfig {
   /**
-   * BCP-47-Kennung für `Intl` — steuert Tausendertrennung, Prozent- und
-   * Datumsformate in den Diagrammen.
+   * BCP-47 tag for `Intl` — drives thousands separators, percentages and date
+   * formats in the charts.
    */
   locale: string
   labels: BaseKitLabels
 }
 
 /**
- * Voreinstellung: englisch. Das Paket weiß nicht, in welcher Sprache die
- * Anwendung läuft, und Englisch ist die Sprache, die am wenigsten Leser
- * ausschließt. Wer deutsch fährt, reicht `BASEKIT_DEFAULTS_DE` herein.
+ * Defaults: English. The package cannot know what language the application
+ * runs in, and English is the one that shuts out the fewest readers. Anything
+ * else is handed in through the plugin above.
  */
 export const BASEKIT_DEFAULTS: BaseKitConfig = {
   locale: 'en-US',
@@ -144,16 +139,16 @@ export const BASEKIT_DEFAULTS: BaseKitConfig = {
 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 Englisch,
- * statt leere Beschriftungen zu zeigen.
+ * Configuration for a BaseKit component. With nothing provided the defaults
+ * apply — the component then renders in English instead of showing empty
+ * labels.
  */
 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. */
+/** Short form for the common case of only needing the labels. */
 export function useBaseKitLabels(): ComputedRef<BaseKitLabels> {
   const config = useBaseKit()
   return computed(() => config.value.labels)

package/app/composables/useChartPalette.ts

@@ -2,17 +2,17 @@ import { computed } from 'vue'
 import { useBaseKit } from './useBaseKit'
 
 /**
- * Reihenfarben und Zahlenformate für die `BaseKitChart*`-Komponenten.
+ * Series colours and number formats for the `BaseKitChart*` components.
  *
- * 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.
+ * The colours live as CSS variables in `app/assets/css/basekit.css` and are
+ * validated as a **set**, order included. That is why there is lookup by index
+ * here and no generation: a sixth colour would be indistinguishable from one
+ * of the five under a colour vision deficiency. More series than that means
+ * grouping them.
  */
 export const BASEKIT_CHART_SLOTS = 5
 
-/** Farbe für Reihe `index` (0-basiert). Ab Slot 6 die zurückgenommene Graustufe. */
+/** Colour for series `index`, zero-based. From slot 6 on, the muted grey. */
 export function baseKitChartColor(index: number): string {
   return index < BASEKIT_CHART_SLOTS
     ? `var(--basekit-chart-${index + 1})`
@@ -33,7 +33,7 @@ export function useChartFormat(): {
     return new Intl.NumberFormat(locale.value).format(value)
   }
 
-  /** Für Werte an Marken und in Kacheln: 12.400 → 12,4 Tsd. */
+  /** For values on ticks and in tiles: 12,400 becomes 12.4K. */
   function compact(value: number): string {
     return value < 10000
       ? number(value)
@@ -41,9 +41,9 @@ export function useChartFormat(): {
   }
 
   /**
-   * 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.
+   * A share in percent, rounded down as long as the whole has not been
+   * reached — otherwise 9,999 out of 10,000 would pass as "100%" and the one
+   * missing item would be rounded out of sight.
    */
   function percent(value: number, total: number): string {
     if (total <= 0) return '—'
@@ -61,8 +61,8 @@ export function useChartFormat(): {
   }
 
   /**
-   * Dezimalpräfixe (kB, MB, GB) — nicht KiB/MiB. Speicheranbieter rechnen so
-   * ab, und die Zahl soll zu der auf der Rechnung passen.
+   * Decimal prefixes (kB, MB, GB), not KiB/MiB. Storage is billed that way,
+   * and the number here should match the one on the invoice.
    */
   function bytes(value: number): string {
     const units = ['B', 'kB', 'MB', 'GB', 'TB']
@@ -76,7 +76,7 @@ export function useChartFormat(): {
     return `${new Intl.NumberFormat(locale.value, { maximumFractionDigits: digits }).format(size)} ${units[unit]}`
   }
 
-  /** Laufzeit als „14 h 20 min", unter einer Stunde nur Minuten. */
+  /** Runtime as "14 h 20 min"; below an hour, minutes only. */
   function duration(seconds: number): string {
     const total = Math.max(0, Math.round(seconds / 60))
     const hours = Math.floor(total / 60)

package/app/composables/useChartWidth.ts

@@ -1,16 +1,16 @@
 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`.
+ * Measures a container so an SVG can draw in real pixels instead of going
+ * through a scaled `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.
+ * The difference is the type: a `viewBox` scaled up to container width drags
+ * axis labels and values up with it — a wide card then shows 15px text where
+ * 11 was meant. With a measured width, text stays text and only the geometry
+ * grows.
  *
- * Vor dem Mounten (SSR, erster Frame) gilt `fallback`. Das Diagramm ist damit
- * sofort da und rückt einmal zurecht, statt zu flackern.
+ * Before mount (SSR, first frame) `fallback` applies. The chart is therefore
+ * there straight away and settles once, rather than flickering.
  */
 export function useChartWidth(fallback = 640): {
   el: Ref<HTMLElement | null>
@@ -25,8 +25,8 @@ export function useChartWidth(fallback = 640): {
 
     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.
+      // Below 240px the geometry becomes useless; draw narrow and let the
+      // container scroll instead.
       if (measured > 0) width.value = Math.max(240, Math.round(measured))
     })
     observer.observe(el.value)

package/app/composables/useConfirm.ts

@@ -2,10 +2,10 @@ import { useConfirmStore } from '../stores/confirm'
 import type { BaseKitConfirmOptions } from '../stores/confirm'
 
 /**
- * Bestätigungsabfrage als Ersatz für natives `window.confirm`.
+ * A confirmation prompt in place of the native `window.confirm`.
  *
- * Öffnet das global gemountete `BaseKitConfirmModal` und liefert ein Promise,
- * das mit `true`/`false` auflöst.
+ * Opens the globally mounted `BaseKitConfirmModal` and returns a promise that
+ * resolves to `true` or `false`.
  *
  *   const confirm = useConfirm()
  *   if (!(await confirm({ description: t('…'), color: 'error', confirmLabel: t('common.delete') }))) return

package/app/stores/confirm.ts

@@ -1,32 +1,32 @@
 import { defineStore } from 'pinia'
 import { ref } from 'vue'
 
-/** Optionen für eine Bestätigungsabfrage. */
+/** Options for one confirmation prompt. */
 export interface BaseKitConfirmOptions {
-  /** Titel des Dialogs (Default: `common.confirm.title`). */
+  /** Dialog title. Falls back to the `confirmTitle` label. */
   title?: string
-  /** Erklärtext / Konsequenz — bei Destruktivem ausformulieren. */
+  /** Explanation or consequence — spell it out for anything destructive. */
   description?: string
-  /** Beschriftung des Bestätigen-Buttons (Default: `common.confirm.confirm`). */
+  /** Label of the confirm button. Falls back to the `confirm` label. */
   confirmLabel?: string
-  /** Beschriftung des Abbrechen-Buttons (Default: `common.cancel`). */
+  /** Label of the cancel button. Falls back to the `cancel` label. */
   cancelLabel?: string
-  /** Farbe des Bestätigen-Buttons — `error` für destruktive Aktionen. */
+  /** Colour of the confirm button — `error` for destructive actions. */
   color?: 'error' | 'primary'
-  /** Optionales Icon am Bestätigen-Button. */
+  /** Optional icon on the confirm button. */
   icon?: string
 }
 
 /**
- * Zentraler Bestätigungs-Store — ersetzt native `window.confirm`-Dialoge durch
- * eine gethemte, dark-mode-fähige Abfrage.
+ * The confirmation store — replaces native `window.confirm` dialogs with a
+ * themed, dark-mode-capable prompt.
  *
- * `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.
+ * `ask()` opens the globally mounted `BaseKitConfirmModal` and returns a
+ * promise resolving to `true` (confirmed) or `false` (cancelled or closed).
+ * The resolver lives outside reactivity so exactly one answer goes back per
+ * prompt.
  *
- * Genutzt über das Composable `useConfirm()`:
+ * Used through the `useConfirm()` composable:
  *   const confirm = useConfirm()
  *   if (!(await confirm({ description: t('…'), color: 'error' }))) return
  */
@@ -36,7 +36,7 @@ export const useConfirmStore = defineStore('basekit:confirm', () => {
   let resolver: ((value: boolean) => void) | null = null
 
   function ask(opts: BaseKitConfirmOptions = {}): Promise<boolean> {
-    // Läuft noch eine Abfrage, wird sie als abgebrochen aufgelöst.
+    // A prompt still running is resolved as cancelled.
     resolver?.(false)
     options.value = opts
     open.value = true
@@ -45,7 +45,7 @@ export const useConfirmStore = defineStore('basekit:confirm', () => {
     })
   }
 
-  /** Abfrage beantworten und Dialog schließen. */
+  /** Answer the prompt and close the dialog. */
   function settle(value: boolean): void {
     open.value = false
     resolver?.(value)

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

@@ -1,14 +1,12 @@
 /**
- * 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.
+ * HTML to Markdown, through turndown. Kept apart from `markdown.ts` on
+ * purpose: that one may end up in a public bundle and should not drag turndown
+ * along, while this one is only ever needed where something is edited.
  *
- * **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.
+ * **turndown is loaded lazily, and that is deliberate.** The package is
+ * CommonJS; an import at module level lands in the server bundle and throws
+ * "require is not defined in ES module scope" while rendering. The editor runs
+ * in the browser anyway — on the server this function is never called.
  */
 type Turndown = { turndown: (html: string) => string }
 
@@ -18,14 +16,14 @@ 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.
+  // Synchronous access to an already loaded module: the editor calls
+  // `prepare()` on mount, well before anything can be saved.
   return instance
 }
 
 /**
- * Lädt turndown im Browser vor. Die Editor-Komponenten rufen das beim
- * Einhängen auf, damit {@link htmlToMarkdown} danach synchron bleiben kann.
+ * Preloads turndown in the browser. The editor components call this on mount
+ * so {@link htmlToMarkdown} can stay synchronous afterwards.
  */
 export async function prepareHtmlToMarkdown(): Promise<void> {
   if (instance || import.meta.server) return
@@ -40,8 +38,8 @@ export async function prepareHtmlToMarkdown(): Promise<void> {
 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.
+  // Without turndown loaded — on the server, or when prepare() was forgotten
+  // — return the original rather than throwing: the text would otherwise be
+  // lost on save.
   return td ? td.turndown(String(html)).trim() : String(html)
 }

package/app/utils/markdown.ts

@@ -1,15 +1,16 @@
 import MarkdownIt from 'markdown-it'
 
 /**
- * Markdown → HTML für den Text-Block (`richtext`-Widget, jetzt Markdown).
+ * Markdown to HTML.
  *
- * 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.
+ * `html: false` on purpose: raw HTML inside the Markdown is NOT passed
+ * through. That closes the biggest XSS hole without a separate sanitizer —
+ * markdown-it also blocks `javascript:` links through its default
+ * `validateLink`. `linkify` makes bare URLs clickable, `typographer` smooths
+ * quotes and dashes.
  *
- * Geteilt zwischen Anzeige und Editor-Vorschau, damit
- * Bearbeiten und Ausgabe identisch aussehen.
+ * Shared between display and editor preview, so that editing and output look
+ * the same.
  */
 const md: MarkdownIt = new MarkdownIt({
   html: false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nuxt-ui-basekit",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Markenfreie Basis-Komponenten für Nuxt 4 auf Nuxt UI — Tabellen, Reiter, Diagramme, Auswahl und Leerzustände als Nuxt-Layer.",
   "keywords": [
     "nuxt",