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

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.1",
+  "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>

package/src/components/PageAction.vue

@@ -0,0 +1,88 @@
+<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.
+import { computed, useSlots } from 'vue'
+import type { RouteLocationRaw } from 'vue-router'
+import UTooltip from '@nuxt/ui/components/Tooltip.vue'
+import UButton from '@nuxt/ui/components/Button.vue'
+import type { ButtonProps } from '@nuxt/ui'
+
+type Tone = 'primary' | 'neutral' | 'destructive'
+
+/**
+ * Normalized page-header action button: icon-only renders with a tooltip and
+ * aria-label from the required `label`; a default slot or `showLabel` renders
+ * the label text inline. `destructive` is only valid inside `PageActionMenu`.
+ */
+const props = withDefaults(defineProps<{
+  /** Icon name (required). */
+  icon: string
+  /** Required. Used as tooltip text for icon-only buttons and aria-label otherwise. */
+  label: string
+  /** Visual tone. `destructive` is only valid inside PageActionMenu. */
+  tone?: Tone
+  loading?: boolean
+  disabled?: boolean
+  to?: RouteLocationRaw
+  /** Link target, e.g. '_blank' for external links (only meaningful with `to`). */
+  target?: string
+  /** Force the button to render label text. If absent, a default slot determines it. */
+  showLabel?: boolean
+  /** Whether the tooltip should respect global disabled state. */
+  tooltipDisabled?: boolean
+}>(), {
+  tone: 'neutral',
+  loading: false,
+  disabled: false,
+  showLabel: false,
+  tooltipDisabled: false,
+})
+
+const slots = useSlots()
+
+const hasLabelSlot = computed(() => Boolean(slots.default))
+const isIconOnly = computed(() => !hasLabelSlot.value && !props.showLabel)
+
+const buttonProps = computed<Partial<ButtonProps>>(() => {
+  const base: Partial<ButtonProps> = {
+    icon: props.icon,
+    size: 'sm',
+    loading: props.loading,
+    disabled: props.disabled || props.loading,
+    to: props.to,
+    target: props.target,
+  }
+  switch (props.tone) {
+    case 'primary':
+      return { ...base, color: 'primary', variant: 'solid' }
+    case 'destructive':
+      if (import.meta.dev) {
+        console.warn('[PageAction] tone="destructive" should be used inside PageActionMenu, not inline.')
+      }
+      return { ...base, color: 'error', variant: 'ghost' }
+    case 'neutral':
+    default:
+      return { ...base, color: 'neutral', variant: 'ghost' }
+  }
+})
+
+if (import.meta.dev && !props.label) {
+  console.warn('[PageAction] `label` is required (used as tooltip text for icon-only buttons).')
+}
+</script>
+
+<template>
+  <UTooltip v-if="isIconOnly" :text="label" :disabled="tooltipDisabled">
+    <UButton
+      v-bind="buttonProps"
+      :aria-label="label"
+    />
+  </UTooltip>
+  <UButton
+    v-else
+    v-bind="buttonProps"
+    :label="showLabel ? label : undefined"
+  >
+    <slot />
+  </UButton>
+</template>

package/src/components/PageActionMenu.vue

@@ -0,0 +1,34 @@
+<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: pageChrome.moreActions.
+import { useI18n } from 'vue-i18n'
+import UDropdownMenu from '@nuxt/ui/components/DropdownMenu.vue'
+import type { DropdownMenuItem } from '@nuxt/ui'
+import PageAction from './PageAction.vue'
+
+/**
+ * Overflow/dropdown menu trigger that matches PageAction sizing. Accepts the
+ * grouped `DropdownMenuItem[][]` shape. Destructive actions should set
+ * `color: 'error'` on the item.
+ */
+withDefaults(defineProps<{
+  items: DropdownMenuItem[][]
+  icon?: string
+  label?: string
+}>(), {
+  icon: 'i-lucide-ellipsis-vertical',
+  label: undefined,
+})
+
+const { t } = useI18n()
+</script>
+
+<template>
+  <UDropdownMenu v-if="items.length" :items="items">
+    <PageAction
+      :icon="icon"
+      :label="label ?? t('pageChrome.moreActions')"
+    />
+  </UDropdownMenu>
+</template>