@octabits-io/nuxt-ui-kit 0.10.0 → 0.12.0

package/dist/i18n/index.d.ts

@@ -41,6 +41,7 @@ interface KitMessages {
     back: string;
     moreActions: string;
     help: string;
+    ai: string;
   };
 }
 declare const kitMessagesEn: KitMessages;

package/dist/i18n/index.js

@@ -29,7 +29,8 @@ const kitMessagesEn = {
 	pageChrome: {
 		back: "Back",
 		moreActions: "More actions",
-		help: "Help"
+		help: "Help",
+		ai: "AI"
 	}
 };
 //#endregion

package/dist/index.d.ts

@@ -129,6 +129,14 @@ interface PageActionsItem {
   key: string;
   icon: string;
   label: string;
+  /**
+   * 'ai' renders the item in the AI cluster: sparkles + primary-soft (AiButton
+   * styling). One inline AI item → verb-labeled button; several → a labeled
+   * "AI ∨" dropdown. Collapsed AI items form their own menu group.
+   */
+  kind?: 'action' | 'ai';
+  /** Menu-only helper text (shown in the AI dropdown / overflow rows). */
+  description?: string;
   /** Inline button tone. At most ONE 'primary' item should be visible per state. */
   tone?: 'primary' | 'neutral';
   /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@octabits-io/nuxt-ui-kit",
-  "version": "0.10.0",
+  "version": "0.12.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",

package/src/components/AiButton.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.
+import UButton from '@nuxt/ui/components/Button.vue';
+
+/**
+ * THE visual token for AI triggers: sparkles + primary-soft + verb label.
+ * Every button that launches AI work (workflow, generation, suggestion) renders
+ * through this primitive so "AI will do something" always looks the same.
+ * Convention: `i-lucide-sparkles` is reserved exclusively for AI triggers;
+ * soft/solid primary = AI acts on data, ghost = AI conversation.
+ */
+withDefaults(defineProps<{
+  label: string
+  /** Leading icon. Keep the sparkles default unless a workflow icon is clearer. */
+  icon?: string
+  /** e.g. 'i-lucide-chevron-down' for dropdown triggers. */
+  trailingIcon?: string
+  size?: 'xs' | 'sm' | 'md'
+  variant?: 'soft' | 'solid' | 'subtle' | 'outline' | 'ghost'
+  loading?: boolean
+  disabled?: boolean
+}>(), {
+  icon: 'i-lucide-sparkles',
+  trailingIcon: undefined,
+  size: 'sm',
+  variant: 'soft',
+  loading: false,
+  disabled: false,
+});
+</script>
+
+<template>
+  <UButton
+    :label="label"
+    :icon="icon"
+    :trailing-icon="trailingIcon"
+    color="primary"
+    :variant="variant"
+    :size="size"
+    :loading="loading"
+    :disabled="disabled"
+  />
+</template>

package/src/components/PageActions.vue

@@ -1,11 +1,14 @@
 <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.help (+ PageActionMenu's pageChrome.moreActions).
+// i18n key contract: pageChrome.help, pageChrome.ai (+ PageActionMenu's pageChrome.moreActions).
 import { computed, inject } from 'vue';
 import { useI18n } from 'vue-i18n';
 import USeparator from '@nuxt/ui/components/Separator.vue';
+import UDropdownMenu from '@nuxt/ui/components/DropdownMenu.vue';
+import UIcon from '@nuxt/ui/components/Icon.vue';
 import type { DropdownMenuItem } from '@nuxt/ui';
+import AiButton from './AiButton.vue';
 import PageAction from './PageAction.vue';
 import PageActionMenu from './PageActionMenu.vue';
 // Package-name import (not ../composables): only src/components is packed, and
@@ -32,9 +35,14 @@ const props = withDefaults(defineProps<{
   utilityItems?: PageActionsItem[]
   /** Header width (px) below which 'auto'/utility items collapse into the menu. */
   collapseBelow?: number
+  /** Render the built-in Help trigger (when a help registry with actions is
+   *  provided). Disable in nested/panel headers where the page-level header
+   *  already owns Help. */
+  help?: boolean
 }>(), {
   utilityItems: () => [],
   collapseBelow: PAGE_ACTIONS_COLLAPSE_BELOW,
+  help: true,
 });
 
 const { t } = useI18n();
@@ -48,15 +56,35 @@ const collapsed = computed(() => {
   return width != null && width < props.collapseBelow;
 });
 
-const showHelp = computed(() => Boolean(helpPanel?.hasActions.value));
+const showHelp = computed(() => props.help && Boolean(helpPanel?.hasActions.value));
 
-const inlineItems = computed(() => props.items.filter(item =>
+const actionItems = computed(() => props.items.filter(item => (item.kind ?? 'action') !== 'ai'));
+const aiItems = computed(() => props.items.filter(item => item.kind === 'ai'));
+
+const isInlineBound = (item: PageActionsItem) =>
   (item.visibility ?? 'auto') === 'always'
-  || ((item.visibility ?? 'auto') === 'auto' && !collapsed.value),
-));
+  || ((item.visibility ?? 'auto') === 'auto' && !collapsed.value);
+
+const inlineItems = computed(() => actionItems.value.filter(isInlineBound));
+
+// AI cluster: one inline item renders as its own verb-labeled AiButton; several
+// share a labeled "AI ∨" dropdown (icons + descriptions per row).
+const inlineAiItems = computed(() => aiItems.value.filter(isInlineBound));
+const aiDropdownItems = computed<DropdownMenuItem[]>(() =>
+  inlineAiItems.value.map(item => ({
+    label: item.label,
+    description: item.description,
+    icon: item.icon,
+    disabled: item.disabled || Boolean(item.disabledReason),
+    loading: item.loading,
+    onSelect: item.onSelect,
+  })),
+);
 
 const inlineUtilityItems = computed(() => collapsed.value ? [] : props.utilityItems);
 
+// Descriptions render only in the dedicated AI dropdown (which has wrap/width
+// styling) — the compact ⋯ overflow stays label-only.
 function toMenuItem(item: PageActionsItem): DropdownMenuItem {
   return {
     label: item.label,
@@ -72,18 +100,25 @@ function toMenuItem(item: PageActionsItem): DropdownMenuItem {
 
 const menuGroups = computed<DropdownMenuItem[][]>(() => {
   const collapsedAutos = collapsed.value
-    ? props.items.filter(item => (item.visibility ?? 'auto') === 'auto')
+    ? actionItems.value.filter(item => (item.visibility ?? 'auto') === 'auto')
     : [];
 
   // Menu-only items grouped by section, in first-appearance order.
   const sections = new Map<string, PageActionsItem[]>();
-  for (const item of props.items) {
+  for (const item of actionItems.value) {
     if ((item.visibility ?? 'auto') !== 'menu') continue;
     const section = item.section ?? 'default';
     if (!sections.has(section)) sections.set(section, []);
     sections.get(section)!.push(item);
   }
 
+  // AI items bound to the menu (explicit 'menu', or 'auto' while collapsed)
+  // form their own group between the action sections and the utilities.
+  const aiGroup = aiItems.value.filter(item =>
+    (item.visibility ?? 'auto') === 'menu'
+    || ((item.visibility ?? 'auto') === 'auto' && collapsed.value),
+  );
+
   const utilityGroup: DropdownMenuItem[] = collapsed.value
     ? [
         ...props.utilityItems.map(toMenuItem),
@@ -96,6 +131,7 @@ const menuGroups = computed<DropdownMenuItem[][]>(() => {
   return [
     collapsedAutos.map(toMenuItem),
     ...[...sections.values()].map(group => group.map(toMenuItem)),
+    aiGroup.map(toMenuItem),
     utilityGroup,
   ].filter(group => group.length > 0);
 });
@@ -120,6 +156,35 @@ const hasUtilityRegion = computed(() =>
     :target="item.target"
     @click="item.onSelect?.()"
   />
+  <!-- AI cluster: soft-primary sparkles = "AI acts on data". One item → its
+       verb label; several → the shared labeled dropdown. -->
+  <AiButton
+    v-if="inlineAiItems.length === 1"
+    :label="inlineAiItems[0]!.label"
+    :loading="inlineAiItems[0]!.loading"
+    :disabled="inlineAiItems[0]!.disabled || Boolean(inlineAiItems[0]!.disabledReason)"
+    @click="inlineAiItems[0]!.onSelect?.()"
+  />
+  <UDropdownMenu
+    v-else-if="inlineAiItems.length > 1"
+    :items="aiDropdownItems"
+    :content="{ align: 'end' }"
+    :ui="{
+      content: 'w-72',
+      item: 'gap-2.5 p-2',
+      itemLabel: 'font-medium text-highlighted',
+      itemDescription: 'mt-0.5 whitespace-normal text-xs/4',
+    }"
+  >
+    <AiButton :label="t('pageChrome.ai')" trailing-icon="i-lucide-chevron-down" />
+    <template #item-leading="{ item }">
+      <span
+        class="flex size-8 shrink-0 items-center justify-center rounded-lg bg-gradient-to-br from-primary/20 to-primary/5 text-primary ring-1 ring-primary/20 ring-inset"
+      >
+        <UIcon :name="(item.icon as string) ?? 'i-lucide-sparkles'" class="size-4" />
+      </span>
+    </template>
+  </UDropdownMenu>
   <PageActionMenu :items="menuGroups" />
   <template v-if="hasUtilityRegion">
     <USeparator orientation="vertical" class="h-5 mx-1" />

package/src/components/pageActions.ts

@@ -11,6 +11,14 @@ export interface PageActionsItem {
   key: string;
   icon: string;
   label: string;
+  /**
+   * 'ai' renders the item in the AI cluster: sparkles + primary-soft (AiButton
+   * styling). One inline AI item → verb-labeled button; several → a labeled
+   * "AI ∨" dropdown. Collapsed AI items form their own menu group.
+   */
+  kind?: 'action' | 'ai';
+  /** Menu-only helper text (shown in the AI dropdown / overflow rows). */
+  description?: string;
   /** Inline button tone. At most ONE 'primary' item should be visible per state. */
   tone?: 'primary' | 'neutral';
   /**