@octabits-io/nuxt-ui-kit 0.11.0 → 0.13.0

package/README.md

@@ -50,6 +50,15 @@ itself, so it has no Nuxt dependency, only `vue`.
   an app-side `useDateFormat`), plus source-shipped `./components/DateInput.vue`,
   `DateRangeInput.vue` (travel/booking end-date semantics, blocked dates via
   props, injected `availabilityCheck`), and `PeriodDisplay.vue`
+- **`./events`** — the browser side of `@octabits-io/framework/events`:
+  `createEventStreamClient`, a fetch-based SSE reader (the stream is
+  authenticated with an `Authorization` header, which native `EventSource`
+  cannot set — so reconnect, `Last-Event-ID` replay, and full-jitter backoff
+  live here), with a durable-only watermark, bounded seen-id dedupe, a
+  `degraded` state for honest fallback-polling UX, and a content-type guard
+  (a 200 `text/html` SPA fallback is a failure, not a stream);
+  `createSseFrameParser`; `useEventStream` (reactive connection state +
+  scope-bound lifecycle)
 - **`./ai`** — frontend AI-workflow engine: `useAiWorkflow` /
   `useAiWorkflowGuard` (poll-driven state over injected transport),
   `createAiProgressCore` (cross-page tracking + completion/applied signals —

package/dist/events/index.d.ts

@@ -0,0 +1,101 @@
+import { Ref } from "vue";
+//#region src/events/sseParser.d.ts
+/**
+ * Incremental SSE frame parser — pure logic, no I/O, exhaustively unit
+ * tested. Feed it decoded text chunks as they arrive; it returns completed
+ * frames (an empty line terminates a frame, per the SSE spec).
+ *
+ * Only the fields the event stream uses are surfaced (`id`, `event`, `data`,
+ * `retry`); comment lines (`: hb` heartbeats) and unknown fields are
+ * discarded. CRLF and bare-CR line endings are normalized.
+ */
+interface SseFrame {
+  /** The `id:` field — present only on durable events (the watermark rule). */
+  id?: string;
+  /** The `event:` field (the envelope type, informational). */
+  event?: string;
+  /** The `data:` field(s), newline-joined. */
+  data: string;
+  /** A `retry:` field, parsed to ms. */
+  retry?: number;
+}
+interface SseFrameParser {
+  /** Consume a chunk; returns every frame completed by it. */
+  push(chunk: string): SseFrame[];
+  /** Discard any partial frame state (call on reconnect). */
+  reset(): void;
+}
+declare function createSseFrameParser(): SseFrameParser;
+//#endregion
+//#region src/events/client.d.ts
+/**
+ * Structural duplicate of the framework's `EventEnvelope` — the kit has no
+ * dependency on `@octabits-io/framework`, and the wire format is the
+ * contract, not the type.
+ */
+interface StreamedEvent<T = unknown> {
+  id: string;
+  seq?: number;
+  type: string;
+  scopeKey: string;
+  at: string;
+  lane: 'durable' | 'ephemeral';
+  data: T;
+  actor?: {
+    type: string;
+    id?: string;
+    name?: string;
+  };
+  resources?: string[];
+}
+type EventStreamState = 'idle' | 'connecting' | 'connected' | 'reconnecting' | 'degraded' | 'stopped';
+interface EventStreamRequest {
+  url: string;
+  /** Extra headers — put your `Authorization` here, fresh per attempt. */
+  headers?: Record<string, string>;
+}
+interface EventStreamClientOptions {
+  /**
+   * Build the request for each (re)connect attempt. Called every attempt so
+   * the auth token is always fresh. May be async (token refresh).
+   */
+  buildRequest: () => EventStreamRequest | Promise<EventStreamRequest>;
+  /** Deduped envelope delivery, both lanes. */
+  onEvent: (event: StreamedEvent) => void;
+  onStateChange?: (state: EventStreamState) => void;
+  /** Injected fetch (default `globalThis.fetch`). */
+  fetchImpl?: typeof fetch;
+  /** Base reconnect delay, overridden by the server's `retry:` hint (default 3 000 ms). */
+  retryMs?: number;
+  /** Reconnect delay ceiling under sustained failure (default 30 000 ms). */
+  maxRetryMs?: number;
+  /** Continuous failure duration before state turns `degraded` (default 60 000 ms). */
+  degradedAfterMs?: number;
+  /** Seen-id dedupe set bound (default 2 000). */
+  maxSeenIds?: number;
+  /** Resume watermark persisted from a previous session, if any. */
+  initialLastEventId?: string | null;
+}
+interface EventStreamClient {
+  start(): void;
+  stop(): void;
+  state(): EventStreamState;
+  /** The current watermark (last durable SSE id seen). */
+  lastEventId(): string | null;
+}
+declare function createEventStreamClient(options: EventStreamClientOptions): EventStreamClient;
+//#endregion
+//#region src/events/useEventStream.d.ts
+interface UseEventStreamReturn {
+  /** Reactive connection state — drive fallback-polling and UI hints off this. */
+  state: Readonly<Ref<EventStreamState>>;
+  /** Reactive count of events delivered (deduped) this session. */
+  received: Readonly<Ref<number>>;
+  start(): void;
+  stop(): void;
+  /** Current watermark (persist it to resume replay across page loads). */
+  lastEventId(): string | null;
+}
+declare function useEventStream(options: EventStreamClientOptions): UseEventStreamReturn;
+//#endregion
+export { type EventStreamClient, type EventStreamClientOptions, type EventStreamRequest, type EventStreamState, type SseFrame, type SseFrameParser, type StreamedEvent, type UseEventStreamReturn, createEventStreamClient, createSseFrameParser, useEventStream };

package/dist/events/index.js

@@ -0,0 +1,245 @@
+import { onScopeDispose, readonly, ref } from "vue";
+//#region src/events/sseParser.ts
+function createSseFrameParser() {
+	let buffer = "";
+	let id;
+	let event;
+	let retry;
+	let dataLines = [];
+	function resetFrame() {
+		id = void 0;
+		event = void 0;
+		retry = void 0;
+		dataLines = [];
+	}
+	function processLine(line, frames) {
+		if (line === "") {
+			if (dataLines.length > 0 || id !== void 0 || event !== void 0 || retry !== void 0) frames.push({
+				...id !== void 0 ? { id } : {},
+				...event !== void 0 ? { event } : {},
+				...retry !== void 0 ? { retry } : {},
+				data: dataLines.join("\n")
+			});
+			resetFrame();
+			return;
+		}
+		if (line.startsWith(":")) return;
+		const colon = line.indexOf(":");
+		const field = colon === -1 ? line : line.slice(0, colon);
+		let value = colon === -1 ? "" : line.slice(colon + 1);
+		if (value.startsWith(" ")) value = value.slice(1);
+		switch (field) {
+			case "id":
+				if (!value.includes("\0")) id = value;
+				break;
+			case "event":
+				event = value;
+				break;
+			case "data":
+				dataLines.push(value);
+				break;
+			case "retry": {
+				const parsed = Number.parseInt(value, 10);
+				if (Number.isInteger(parsed) && parsed >= 0) retry = parsed;
+				break;
+			}
+			default: break;
+		}
+	}
+	function push(chunk) {
+		buffer += chunk.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+		const frames = [];
+		let newline = buffer.indexOf("\n");
+		while (newline !== -1) {
+			const line = buffer.slice(0, newline);
+			buffer = buffer.slice(newline + 1);
+			processLine(line, frames);
+			newline = buffer.indexOf("\n");
+		}
+		return frames;
+	}
+	function reset() {
+		buffer = "";
+		resetFrame();
+	}
+	return {
+		push,
+		reset
+	};
+}
+//#endregion
+//#region src/events/client.ts
+/**
+* The fetch-based SSE event-stream client. A hand-rolled reader rather than
+* native `EventSource` because the stream is authenticated with an
+* `Authorization` header, which `new EventSource(url)` cannot set — so
+* reconnect, `Last-Event-ID`, and backoff are implemented here, once.
+*
+* Semantics baked in (mirroring the server contract in
+* `@octabits-io/framework/events`):
+*
+* - **Watermark**: only frames carrying an SSE `id:` advance the persisted
+*   watermark (the server sets `id:` on durable events only) — sent back as
+*   the `Last-Event-ID` header on every reconnect for replay.
+* - **Dedupe**: replay overlaps and at-least-once delivery mean duplicates
+*   are normal; a bounded seen-id set (envelope `id`, not `seq`) filters
+*   them before `onEvent`.
+* - **Reconnect is routine, not an error**: the server caps connection age
+*   (~5 min) so auth is re-evaluated; a server-side close re-connects after
+*   the server's `retry:` hint with **full jitter**. Only sustained failure
+*   moves the state to `degraded` (UI hint to resume fallback polling).
+*/
+function createEventStreamClient(options) {
+	const { buildRequest, onEvent, onStateChange, fetchImpl = globalThis.fetch.bind(globalThis), retryMs = 3e3, maxRetryMs = 3e4, degradedAfterMs = 6e4, maxSeenIds = 2e3, initialLastEventId = null } = options;
+	let state = "idle";
+	let lastEventId = initialLastEventId;
+	let serverRetryMs = null;
+	let abort = null;
+	let running = false;
+	let attempt = 0;
+	let failingSince = null;
+	let retryTimer;
+	const seen = /* @__PURE__ */ new Set();
+	const seenOrder = [];
+	function setState(next) {
+		if (state === next) return;
+		state = next;
+		onStateChange?.(next);
+	}
+	function markSeen(id) {
+		if (seen.has(id)) return false;
+		seen.add(id);
+		seenOrder.push(id);
+		if (seenOrder.length > maxSeenIds) {
+			const evicted = seenOrder.shift();
+			if (evicted !== void 0) seen.delete(evicted);
+		}
+		return true;
+	}
+	function scheduleReconnect() {
+		if (!running) return;
+		attempt += 1;
+		if (failingSince === null) failingSince = Date.now();
+		setState(Date.now() - failingSince >= degradedAfterMs ? "degraded" : "reconnecting");
+		const cap = Math.min(maxRetryMs, (serverRetryMs ?? retryMs) * 2 ** Math.min(attempt - 1, 8));
+		const delay = Math.random() * cap;
+		retryTimer = setTimeout(() => void connect(), delay);
+	}
+	function handleFrame(frame) {
+		if (frame.retry !== void 0) serverRetryMs = frame.retry;
+		if (frame.id !== void 0 && frame.id !== "") lastEventId = frame.id;
+		if (frame.data === "") return;
+		let envelope;
+		try {
+			envelope = JSON.parse(frame.data);
+		} catch {
+			return;
+		}
+		if (typeof envelope !== "object" || envelope === null || typeof envelope.id !== "string") return;
+		if (!markSeen(envelope.id)) return;
+		onEvent(envelope);
+	}
+	async function connect() {
+		if (!running) return;
+		if (state === "idle" || state === "stopped") setState("connecting");
+		abort = new AbortController();
+		const parser = createSseFrameParser();
+		try {
+			const request = await buildRequest();
+			const response = await fetchImpl(request.url, {
+				headers: {
+					accept: "text/event-stream",
+					...lastEventId !== null ? { "last-event-id": lastEventId } : {},
+					...request.headers
+				},
+				signal: abort.signal
+			});
+			const contentType = response.headers.get("content-type") ?? "";
+			if (!response.ok || !response.body || !contentType.includes("text/event-stream")) {
+				scheduleReconnect();
+				return;
+			}
+			setState("connected");
+			attempt = 0;
+			failingSince = null;
+			const reader = response.body.getReader();
+			const decoder = new TextDecoder();
+			for (;;) {
+				const { value, done } = await reader.read();
+				if (done) break;
+				for (const frame of parser.push(decoder.decode(value, { stream: true }))) handleFrame(frame);
+			}
+			if (running) {
+				setState("reconnecting");
+				retryTimer = setTimeout(() => void connect(), Math.random() * (serverRetryMs ?? retryMs));
+			}
+		} catch (error) {
+			if (!running || error instanceof DOMException && error.name === "AbortError") return;
+			scheduleReconnect();
+		}
+	}
+	function start() {
+		if (running) return;
+		running = true;
+		connect();
+	}
+	function stop() {
+		running = false;
+		if (retryTimer) clearTimeout(retryTimer);
+		abort?.abort();
+		abort = null;
+		setState("stopped");
+	}
+	return {
+		start,
+		stop,
+		state: () => state,
+		lastEventId: () => lastEventId
+	};
+}
+//#endregion
+//#region src/events/useEventStream.ts
+/**
+* Vue composable over {@link createEventStreamClient}: reactive connection
+* state, scope-bound lifecycle, and a typed per-event-type handler registry.
+*
+* The app owns *what to do* with events (invalidation registry, toasts, …);
+* this composable owns the connection. Typical wiring, once, in the app
+* shell:
+*
+* ```ts
+* const stream = useEventStream({
+*   buildRequest: () => ({
+*     url: `${apiBase}/events`,
+*     headers: { authorization: `Bearer ${auth.accessToken}` },
+*   }),
+*   onEvent: (event) => invalidation.dispatch(event),
+* });
+* watch(tenantReady, (ready) => (ready ? stream.start() : stream.stop()));
+* ```
+*/
+function useEventStream(options) {
+	const state = ref("idle");
+	const received = ref(0);
+	const client = createEventStreamClient({
+		...options,
+		onEvent: (event) => {
+			received.value += 1;
+			options.onEvent(event);
+		},
+		onStateChange: (next) => {
+			state.value = next;
+			options.onStateChange?.(next);
+		}
+	});
+	onScopeDispose(() => client.stop());
+	return {
+		state: readonly(state),
+		received: readonly(received),
+		start: client.start,
+		stop: client.stop,
+		lastEventId: client.lastEventId
+	};
+}
+//#endregion
+export { createEventStreamClient, createSseFrameParser, useEventStream };

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.11.0",
+  "version": "0.13.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",
@@ -45,6 +45,11 @@
       "import": "./dist/ai/index.js",
       "default": "./dist/ai/index.js"
     },
+    "./events": {
+      "types": "./dist/events/index.d.ts",
+      "import": "./dist/events/index.js",
+      "default": "./dist/events/index.js"
+    },
     "./styles.css": "./src/styles.css",
     "./components/*": "./src/components/*"
   },
@@ -75,7 +80,7 @@
     "vitest": "^4.1.10",
     "vue": "^3.5.40",
     "zod": "^4.4.3",
-    "@octabits-io/framework": "^0.7.0"
+    "@octabits-io/framework": "^0.8.0"
   },
   "peerDependencies": {
     "@elysiajs/eden": "^1.4.0",

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
@@ -55,13 +58,33 @@ const collapsed = computed(() => {
 
 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,
@@ -77,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),
@@ -101,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);
 });
@@ -125,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';
   /**