@octabits-io/nuxt-ui-kit 0.2.0 → 0.3.0

package/dist/locale/index.js

@@ -0,0 +1,140 @@
+import { computed, inject, provide, ref, toValue, watchEffect } from "vue";
+import { baseLocaleOf, resolveLocale } from "@octabits-io/framework/utils";
+//#region src/locale/pruneLocaleMap.ts
+/**
+* Drop empty-string leaves from a `LocaleMap<string>` so cleared tabs fall
+* back to the default locale instead of shadowing it with `''`. Returns a new
+* map; use `Object.keys(result).length` to decide between map and `null` when
+* the API expects `null` for "unset".
+*/
+function pruneLocaleMap(map) {
+	return Object.fromEntries(Object.entries(map ?? {}).filter(([, v]) => !!v));
+}
+//#endregion
+//#region src/locale/index.ts
+const LOCALE_FIELD_CONTEXT = Symbol("nuxt-ui-kit:locale-field-context");
+/** Provide the locale-field context (call once, near the app root). */
+function provideLocaleFieldContext(context) {
+	provide(LOCALE_FIELD_CONTEXT, context);
+}
+/** Resolve the locale-field context inside a component (throws when absent). */
+function useLocaleFieldContext() {
+	const context = inject(LOCALE_FIELD_CONTEXT, null);
+	if (!context) throw new Error("[nuxt-ui-kit] LocaleInput/LocaleTextarea need provideLocaleFieldContext() near the app root.");
+	return context;
+}
+/**
+* Tab plumbing shared by every per-locale field editor: one tab per content
+* locale, an active-tab ref, and the completeness indicator. Value access
+* stays with the caller — pass `hasValue` so the indicator works for any
+* value type (strings, rich-text documents, …).
+*
+* **Register variants** (e.g. `de-formal`, whose base `de` is also supported)
+* are a tone/overlay axis, not a real language: a label like "Hotel" is
+* identical in both. So variant tabs are **hidden by default** and only shown
+* when `registerOverride` is true (reader-addressing prose — descriptions,
+* body copy). When shown, a blank variant value *inherits* its base locale
+* (neutral hint, not a "missing" warning), and clearing the field should
+* **delete the key** so the resolver falls through to the base
+* (`de-formal → de`).
+*/
+function useLocaleTabs(hasValue, source, registerOverride = false) {
+	const supportedLocales = computed(() => toValue(source.locales));
+	const defaultLocale = computed(() => toValue(source.defaultLocale));
+	/** A locale whose base language is itself also supported (e.g. `de-formal` ⊂ `de`). */
+	const isVariant = (loc) => baseLocaleOf(loc) !== loc && supportedLocales.value.includes(baseLocaleOf(loc));
+	const visibleLocales = computed(() => {
+		const filtered = toValue(registerOverride) ? supportedLocales.value : supportedLocales.value.filter((loc) => !isVariant(loc));
+		return filtered.includes(defaultLocale.value) ? filtered : [...filtered, defaultLocale.value];
+	});
+	const active = ref("");
+	watchEffect(() => {
+		if (!visibleLocales.value.includes(active.value)) active.value = visibleLocales.value.includes(defaultLocale.value) ? defaultLocale.value : visibleLocales.value[0] ?? "";
+	});
+	/**
+	* A register variant carries a lowercase BCP-47 *variant* subtag (e.g.
+	* `de-formal`) — as opposed to a region (`de-AT`) or script (`zh-Hans`).
+	* Formality is a tenant-wide choice, so the tab reads as the plain language
+	* ("DE"), not the internal `DE-FORMAL` token.
+	*/
+	const REGISTER_VARIANT = /-[a-z]{4,8}$/;
+	const tabLabel = (loc) => (REGISTER_VARIANT.test(loc) ? baseLocaleOf(loc) : loc).toUpperCase();
+	const items = computed(() => visibleLocales.value.map((loc) => ({
+		label: tabLabel(loc),
+		value: loc
+	})));
+	const indicatorOf = (loc) => {
+		if (hasValue(loc)) return null;
+		if (isVariant(loc)) return { kind: "inherits" };
+		return loc === defaultLocale.value ? { kind: "error" } : { kind: "warning" };
+	};
+	/**
+	* Source locale for quick translate: the active tab when it has a value, so
+	* freshly edited text wins; otherwise the default locale, otherwise the
+	* first filled visible locale. `null` when every tab is empty. The fallback
+	* matters because the operator typically sits on the tab they want FILLED —
+	* translate must not go dead just because the active tab is the empty one.
+	*/
+	const translateSource = computed(() => {
+		if (hasValue(active.value)) return active.value;
+		if (hasValue(defaultLocale.value)) return defaultLocale.value;
+		return visibleLocales.value.find(hasValue) ?? null;
+	});
+	return {
+		items,
+		active,
+		indicatorOf,
+		isVariant,
+		defaultLocale,
+		visibleLocales,
+		translateSource,
+		translateTargets: computed(() => visibleLocales.value.filter((loc) => loc !== translateSource.value && !hasValue(loc) && (!isVariant(loc) || loc === defaultLocale.value)))
+	};
+}
+/**
+* String-valued locale field over a single `LocaleMap<string>` model — the
+* composable behind `LocaleInput` / `LocaleTextarea`. See
+* {@link useLocaleTabs} for the tab/indicator semantics.
+*/
+function useLocaleField(model, source, registerOverride = false) {
+	const hasValue = (loc) => {
+		const v = model.value?.[loc];
+		return typeof v === "string" && v.length > 0;
+	};
+	const { items, active, indicatorOf, isVariant, defaultLocale, translateSource, translateTargets } = useLocaleTabs(hasValue, source, registerOverride);
+	return {
+		items,
+		active,
+		activeValue: computed({
+			get: () => model.value?.[active.value] ?? "",
+			set: (val) => {
+				const next = { ...model.value ?? {} };
+				if (val === "" && isVariant(active.value)) delete next[active.value];
+				else next[active.value] = val;
+				model.value = next;
+			}
+		}),
+		indicatorOf,
+		defaultLocale,
+		translateSource,
+		translateTargets
+	};
+}
+/**
+* Resolve a `LocaleMap<string>` to a single display string for list / detail
+* surfaces, using the **default content locale** — deliberately decoupled
+* from the app's own UI language, which is unrelated chrome and would
+* otherwise select content arbitrarily. Lists therefore always show the
+* canonical value, consistently for every user; the per-locale values stay
+* fully editable via `LocaleInput` / `LocaleTextarea`.
+*/
+function createLocaleDisplay(source) {
+	/** Resolve a LocaleMap to its default-locale string, falling back when empty. */
+	function display(map, fallback = "") {
+		const defaultLocale = toValue(source.defaultLocale);
+		return resolveLocale(map, defaultLocale, defaultLocale) ?? fallback;
+	}
+	return { display };
+}
+//#endregion
+export { LOCALE_FIELD_CONTEXT, createLocaleDisplay, provideLocaleFieldContext, pruneLocaleMap, useLocaleField, useLocaleFieldContext, useLocaleTabs };

package/dist/zod/index.d.ts

@@ -1,3 +1,4 @@
+import { Ref } from "vue";
 import * as z from "zod";
 //#region src/zod/index.d.ts
 type ZodLocaleFactory = () => Parameters<typeof z.config>[0];
@@ -20,5 +21,26 @@ interface ZodLocaleSyncOptions {
  * change. Call once from an app plugin.
  */
 declare function setupZodLocaleSync(options: ZodLocaleSyncOptions): void;
+interface UseWizardStepValidationOptions<TState> {
+  form: Ref<any>;
+  stepper: Ref<any>;
+  activeStep: Ref<number>;
+  state: TState;
+  schema: z.ZodObject<z.ZodRawShape> | Ref<z.ZodObject<z.ZodRawShape>>;
+  stepFields: Partial<Record<number, readonly (keyof TState)[]>>;
+}
+/**
+ * Gates a stepper + form multi-step wizard by validating only the current
+ * step's fields via `schema.pick(...)`: `currentStepValid` drives the Next
+ * button's enabled state reactively, `goNext` runs the form-level validation
+ * for the step's fields (surfacing messages) before advancing, `goPrev` just
+ * steps back. Works with any form/stepper exposing the structural `validate`
+ * / `next` / `prev` surface (e.g. Nuxt UI's UForm + UStepper).
+ */
+declare function useWizardStepValidation<TState extends object>(options: UseWizardStepValidationOptions<TState>): {
+  currentStepValid: import("vue").ComputedRef<boolean>;
+  goNext: () => Promise<void>;
+  goPrev: () => void;
+};
 //#endregion
-export { ZodLocaleSyncOptions, setupZodLocaleSync };
+export { UseWizardStepValidationOptions, ZodLocaleSyncOptions, setupZodLocaleSync, useWizardStepValidation };

package/dist/zod/index.js

@@ -1,3 +1,4 @@
+import { computed, isRef } from "vue";
 import * as z from "zod";
 //#region src/zod/index.ts
 /**
@@ -13,5 +14,47 @@ function setupZodLocaleSync(options) {
 	apply(options.getLocale());
 	options.onLocaleChange(apply);
 }
+/**
+* Gates a stepper + form multi-step wizard by validating only the current
+* step's fields via `schema.pick(...)`: `currentStepValid` drives the Next
+* button's enabled state reactively, `goNext` runs the form-level validation
+* for the step's fields (surfacing messages) before advancing, `goPrev` just
+* steps back. Works with any form/stepper exposing the structural `validate`
+* / `next` / `prev` surface (e.g. Nuxt UI's UForm + UStepper).
+*/
+function useWizardStepValidation(options) {
+	const { form, stepper, activeStep, state, schema, stepFields } = options;
+	function getSchema() {
+		return isRef(schema) ? schema.value : schema;
+	}
+	const currentStepValid = computed(() => {
+		const fields = stepFields[activeStep.value];
+		if (!fields || fields.length === 0) return true;
+		const partial = {};
+		const pickShape = {};
+		for (const f of fields) {
+			partial[f] = state[f];
+			pickShape[f] = true;
+		}
+		return getSchema().pick(pickShape).safeParse(partial).success;
+	});
+	async function goNext() {
+		const fields = stepFields[activeStep.value];
+		if (fields && fields.length > 0) try {
+			await form.value?.validate({ name: fields.map(String) });
+		} catch {
+			return;
+		}
+		stepper.value?.next();
+	}
+	function goPrev() {
+		stepper.value?.prev();
+	}
+	return {
+		currentStepValid,
+		goNext,
+		goPrev
+	};
+}
 //#endregion
-export { setupZodLocaleSync };
+export { setupZodLocaleSync, useWizardStepValidation };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@octabits-io/nuxt-ui-kit",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Frontend kit for Nuxt/Vue admin SPAs: OIDC session harness (oidc-client-ts), Eden Treaty client factory, auth/org store cores, and a route-guard builder — factory-style seams the app wires into its own plugins, stores, and middleware",
   "license": "MIT",
   "type": "module",
@@ -10,6 +10,26 @@
       "import": "./dist/index.js",
       "default": "./dist/index.js"
     },
+    "./auth": {
+      "types": "./dist/auth/index.d.ts",
+      "import": "./dist/auth/index.js",
+      "default": "./dist/auth/index.js"
+    },
+    "./api": {
+      "types": "./dist/api/index.d.ts",
+      "import": "./dist/api/index.js",
+      "default": "./dist/api/index.js"
+    },
+    "./i18n": {
+      "types": "./dist/i18n/index.d.ts",
+      "import": "./dist/i18n/index.js",
+      "default": "./dist/i18n/index.js"
+    },
+    "./locale": {
+      "types": "./dist/locale/index.d.ts",
+      "import": "./dist/locale/index.js",
+      "default": "./dist/locale/index.js"
+    },
     "./zod": {
       "types": "./dist/zod/index.d.ts",
       "import": "./dist/zod/index.js",
@@ -52,10 +72,12 @@
     "oidc-client-ts": "^3.5.0",
     "vitest": "^4.1.10",
     "vue": "^3.5.39",
-    "zod": "^4.4.3"
+    "zod": "^4.4.3",
+    "@octabits-io/framework": "^0.3.0"
   },
   "peerDependencies": {
     "@elysiajs/eden": "^1.4.0",
+    "@octabits-io/framework": "^0.3.0",
     "@internationalized/date": "^3",
     "@nuxt/ui": "^4",
     "date-fns": "^3 || ^4",
@@ -68,6 +90,12 @@
     "zod": "^4"
   },
   "peerDependenciesMeta": {
+    "@elysiajs/eden": {
+      "optional": true
+    },
+    "@octabits-io/framework": {
+      "optional": true
+    },
     "@internationalized/date": {
       "optional": true
     },
@@ -80,6 +108,9 @@
     "elysia": {
       "optional": true
     },
+    "oidc-client-ts": {
+      "optional": true
+    },
     "typescript": {
       "optional": true
     },

package/src/components/LocaleInput.vue

@@ -0,0 +1,132 @@
+<script setup lang="ts">
+// Shipped as source: the consumer's Vite compiles this SFC. All imports are
+// explicit — no reliance on the consumer's auto-import configuration.
+// i18n key contract: localeField.translate (+ LocaleTab's key).
+// Requires provideLocaleFieldContext() near the app root.
+import { computed } from 'vue'
+import { useI18n } from 'vue-i18n'
+import type { LocaleMap } from '@octabits-io/framework/utils'
+import UFormField from '@nuxt/ui/components/FormField.vue'
+import UTabs from '@nuxt/ui/components/Tabs.vue'
+import UInput from '@nuxt/ui/components/Input.vue'
+import UTooltip from '@nuxt/ui/components/Tooltip.vue'
+import UButton from '@nuxt/ui/components/Button.vue'
+import {
+  useLocaleField,
+  useLocaleFieldContext,
+  type LocaleFieldTranslateScope,
+} from '@octabits-io/nuxt-ui-kit/locale'
+import LocaleTab from './LocaleTab.vue'
+
+/**
+ * Edits a `LocaleMap<string>` field (one value per content locale) as a single
+ * input with a per-locale tab bar. The tab for a locale missing a value shows a
+ * dot — orange for a normal locale, red for the default locale (which should
+ * always be filled). The full map is the single source of truth, so switching
+ * tabs never loses an in-progress edit.
+ *
+ * Register-variant locales (e.g. `de-formal`) are hidden by default — a label is
+ * register-invariant ("Hotel" is the same formal or informal). Set
+ * `register-override` for reader-addressing prose where formal/informal differs;
+ * see `LocaleTextarea`, which is the usual home for that.
+ */
+const model = defineModel<LocaleMap<string>>({ default: () => ({}) })
+
+const props = defineProps<{
+  label?: string
+  description?: string
+  help?: string
+  placeholder?: string
+  /** Form field path — wires validation errors to this field. */
+  name?: string
+  /** Marks the default-locale value as required (visual only). */
+  required?: boolean
+  maxlength?: number
+  /** Surface register-variant locales (e.g. `de-formal`) as optional override tabs. */
+  registerOverride?: boolean
+  /** AI-translate context describing what the field holds. Defaults to `label`. */
+  translateContext?: string
+  /** Hide the AI-translate button (slugs, codes — values that must not be translated). */
+  noTranslate?: boolean
+}>()
+
+defineSlots<{
+  /**
+   * Replaces the default AI-translate button with custom field-level AI
+   * actions (e.g. a menu merging generate + translate). The scope carries the
+   * field's translate machinery so the override can still offer it.
+   */
+  ai?: (scope: LocaleFieldTranslateScope) => unknown
+}>()
+
+const { t } = useI18n()
+const { useSource, useTranslate } = useLocaleFieldContext()
+
+const { items, active, activeValue, indicatorOf, translateSource, translateTargets } = useLocaleField(
+  model,
+  useSource(),
+  () => props.registerOverride ?? false,
+)
+
+// The translate provider is optional app wiring — without it the sparkle
+// button never renders and the #ai slot scope reports unavailable.
+const translator = useTranslate?.({
+  model,
+  context: () => props.translateContext ?? props.label,
+  source: translateSource,
+  targetLocales: translateTargets,
+})
+
+const aiScope = computed<LocaleFieldTranslateScope>(() => ({
+  available: !!translator && items.value.length > 1 && !props.noTranslate,
+  canTranslate: translator?.canTranslate.value ?? false,
+  translating: translator?.translating.value ?? false,
+  translate: () => translator?.translate(),
+}))
+</script>
+
+<template>
+  <UFormField :label="label" :description="description" :help="help" :name="name" :required="required">
+    <div class="flex flex-col gap-2">
+      <!-- A single effective locale needs no tab chrome — degrade to a plain input
+           (the row still renders when a page slots in field-level AI actions). -->
+      <div v-if="items.length > 1 || !!$slots.ai" class="flex items-center justify-between gap-2">
+        <UTabs
+          v-if="items.length > 1"
+          v-model="active"
+          :items="items"
+          :content="false"
+          size="sm"
+          color="neutral"
+          variant="link"
+          :ui="{ list: 'gap-2' }"
+        >
+          <template #default="{ item }">
+            <LocaleTab :label="item.label as string" :indicator="indicatorOf(item.value as string)" />
+          </template>
+        </UTabs>
+        <span v-else />
+        <slot name="ai" v-bind="aiScope">
+          <UTooltip v-if="aiScope.available" :text="t('localeField.translate')">
+            <UButton
+              icon="i-lucide-languages"
+              size="xs"
+              variant="ghost"
+              color="primary"
+              :loading="aiScope.translating"
+              :disabled="!aiScope.canTranslate"
+              :aria-label="t('localeField.translate')"
+              @click.prevent="aiScope.translate()"
+            />
+          </UTooltip>
+        </slot>
+      </div>
+      <UInput
+        v-model="activeValue"
+        :placeholder="placeholder"
+        :maxlength="maxlength"
+        class="w-full"
+      />
+    </div>
+  </UFormField>
+</template>

package/src/components/LocaleTab.vue

@@ -0,0 +1,44 @@
+<script setup lang="ts">
+// Shipped as source: the consumer's Vite compiles this SFC. All imports are
+// explicit — no reliance on the consumer's auto-import configuration.
+// i18n key contract: localeField.inheritsBaseLocale.
+import { computed } from 'vue'
+import { useI18n } from 'vue-i18n'
+import type { LocaleTabIndicator } from '@octabits-io/nuxt-ui-kit/locale'
+
+/**
+ * Renders a locale tab label with its completeness indicator:
+ * red dot = default locale empty, orange = a normal locale empty,
+ * neutral dot = a register-variant override empty (inherits its base locale).
+ */
+const props = defineProps<{
+  label: string
+  indicator: LocaleTabIndicator
+}>()
+
+const { t } = useI18n()
+
+const dotClass = computed(() => {
+  switch (props.indicator?.kind) {
+    case 'error':
+      return 'bg-error'
+    case 'warning':
+      return 'bg-warning'
+    case 'inherits':
+      return 'bg-muted'
+    default:
+      return null
+  }
+})
+
+const title = computed(() =>
+  props.indicator?.kind === 'inherits' ? t('localeField.inheritsBaseLocale') : undefined,
+)
+</script>
+
+<template>
+  <span class="flex items-center gap-1.5" :title="title">
+    {{ label }}
+    <span v-if="dotClass" class="size-1.5 shrink-0 rounded-full" :class="dotClass" />
+  </span>
+</template>

package/src/components/LocaleTextarea.vue

@@ -0,0 +1,131 @@
+<script setup lang="ts">
+// Shipped as source: the consumer's Vite compiles this SFC. All imports are
+// explicit — no reliance on the consumer's auto-import configuration.
+// i18n key contract: localeField.translate (+ LocaleTab's key).
+// Requires provideLocaleFieldContext() near the app root.
+import { computed } from 'vue'
+import { useI18n } from 'vue-i18n'
+import type { LocaleMap } from '@octabits-io/framework/utils'
+import UFormField from '@nuxt/ui/components/FormField.vue'
+import UTabs from '@nuxt/ui/components/Tabs.vue'
+import UTextarea from '@nuxt/ui/components/Textarea.vue'
+import UTooltip from '@nuxt/ui/components/Tooltip.vue'
+import UButton from '@nuxt/ui/components/Button.vue'
+import {
+  useLocaleField,
+  useLocaleFieldContext,
+  type LocaleFieldTranslateScope,
+} from '@octabits-io/nuxt-ui-kit/locale'
+import LocaleTab from './LocaleTab.vue'
+
+/**
+ * Multi-line variant of `LocaleInput` — edits a `LocaleMap<string>` field
+ * (descriptions, body copy, …) with a per-locale tab bar. See `LocaleInput`
+ * for the completeness-dot semantics.
+ *
+ * Reader-addressing prose is where formal/informal registers actually differ, so
+ * set `register-override` here to expose e.g. `de-formal` as an optional override
+ * tab (blank = inherits `de`). Leave it off for register-invariant copy.
+ */
+const model = defineModel<LocaleMap<string>>({ default: () => ({}) })
+
+const props = defineProps<{
+  label?: string
+  description?: string
+  help?: string
+  placeholder?: string
+  /** Form field path — wires validation errors to this field. */
+  name?: string
+  required?: boolean
+  maxlength?: number
+  rows?: number
+  /** Surface register-variant locales (e.g. `de-formal`) as optional override tabs. */
+  registerOverride?: boolean
+  /** AI-translate context describing what the field holds. Defaults to `label`. */
+  translateContext?: string
+  /** Hide the AI-translate button (slugs, codes — values that must not be translated). */
+  noTranslate?: boolean
+}>()
+
+defineSlots<{
+  /**
+   * Replaces the default AI-translate button with custom field-level AI
+   * actions (e.g. a menu merging generate + translate). The scope carries the
+   * field's translate machinery so the override can still offer it.
+   */
+  ai?: (scope: LocaleFieldTranslateScope) => unknown
+}>()
+
+const { t } = useI18n()
+const { useSource, useTranslate } = useLocaleFieldContext()
+
+const { items, active, activeValue, indicatorOf, translateSource, translateTargets } = useLocaleField(
+  model,
+  useSource(),
+  () => props.registerOverride ?? false,
+)
+
+// The translate provider is optional app wiring — without it the sparkle
+// button never renders and the #ai slot scope reports unavailable.
+const translator = useTranslate?.({
+  model,
+  context: () => props.translateContext ?? props.label,
+  source: translateSource,
+  targetLocales: translateTargets,
+})
+
+const aiScope = computed<LocaleFieldTranslateScope>(() => ({
+  available: !!translator && items.value.length > 1 && !props.noTranslate,
+  canTranslate: translator?.canTranslate.value ?? false,
+  translating: translator?.translating.value ?? false,
+  translate: () => translator?.translate(),
+}))
+</script>
+
+<template>
+  <UFormField :label="label" :description="description" :help="help" :name="name" :required="required">
+    <div class="flex flex-col gap-2">
+      <!-- A single effective locale needs no tab chrome — degrade to a plain textarea
+           (the row still renders when a page slots in field-level AI actions). -->
+      <div v-if="items.length > 1 || !!$slots.ai" class="flex items-center justify-between gap-2">
+        <UTabs
+          v-if="items.length > 1"
+          v-model="active"
+          :items="items"
+          :content="false"
+          size="sm"
+          color="neutral"
+          variant="link"
+          :ui="{ list: 'gap-2' }"
+        >
+          <template #default="{ item }">
+            <LocaleTab :label="item.label as string" :indicator="indicatorOf(item.value as string)" />
+          </template>
+        </UTabs>
+        <span v-else />
+        <slot name="ai" v-bind="aiScope">
+          <UTooltip v-if="aiScope.available" :text="t('localeField.translate')">
+            <UButton
+              icon="i-lucide-languages"
+              size="xs"
+              variant="ghost"
+              color="primary"
+              :loading="aiScope.translating"
+              :disabled="!aiScope.canTranslate"
+              :aria-label="t('localeField.translate')"
+              @click.prevent="aiScope.translate()"
+            />
+          </UTooltip>
+        </slot>
+      </div>
+      <UTextarea
+        v-model="activeValue"
+        :placeholder="placeholder"
+        :maxlength="maxlength"
+        :rows="rows ?? 4"
+        autoresize
+        class="w-full"
+      />
+    </div>
+  </UFormField>
+</template>