@octabits-io/nuxt-ui-kit 0.14.2 → 0.16.0

package/README.md

@@ -26,16 +26,17 @@ itself, so it has no Nuxt dependency, only `vue`.
 - **Route guard builder** — `createAuthGuard` returns a handler yielding a
   redirect target or `undefined`; per-app policy (org validation, role gates)
   goes in the `afterAuthenticated` hook
-- **Eden Treaty client factory** (`@elysiajs/eden` peer) —
-  `createTreatyClientFactory<App>` (lazy singleton, bearer injection,
-  `parseDate: false` by default to keep ISO-date strings string-typed on the
-  wire), plus `createAccessTokenProvider` and `resolveApiBaseUrl`
+- **API-client seams** (`./api`, transport-agnostic) —
+  `resolveApiBaseUrl` (configured URL → page origin in production → localhost
+  dev port) and `createAccessTokenProvider` (bearer from the OIDC session).
+  Build the client with Hono's `hc` and inject the token through its own async
+  `headers` thunk
 - **Org store core** — `createOrgStoreCore<TOrg>` (granted orgs, slug-keyed
   selection, persistence, lost-access revocation) for the app's own store
 - **API error → i18n** — `createApiErrorMessenger({ t, te })`: maps
   `{ key, message }` bodies and validation errors to user-facing strings via
   the `errors.*` / `validation.fields.*` / `validation.messages.*` key
-  convention; unwraps Eden `{ value }` envelopes
+  convention; unwraps `{ value }` error envelopes
 - **Confirm dialog** — promise-based `useConfirm()` + singleton state, with a
   `./components/ConfirmDialog.vue` renderer (`common.cancel`/`common.confirm`
   i18n defaults, `zIndexClass` prop for stacking above slideovers)
@@ -113,11 +114,17 @@ export default defineNuxtPlugin((nuxtApp) => {
   })
 })
 
-// app/composables/useApi.ts
-const getClient = createTreatyClientFactory<App>({
-  getBaseUrl: () => resolveApiBaseUrl({ configuredUrl, isProductionBuild: import.meta.env.PROD, devFallbackPort: 3002 }),
-  getAccessToken: createAccessTokenProvider(getUserManager),
-})
+// app/composables/useApi.ts — `hcWithType` is the API package's pre-compiled client type
+const getAccessToken = createAccessTokenProvider(getUserManager)
+const client = hcWithType(
+  resolveApiBaseUrl({ configuredUrl, isProductionBuild: import.meta.env.PROD, devFallbackPort: 3002 }),
+  {
+    headers: async () => {
+      const token = await getAccessToken()
+      return token ? { authorization: `Bearer ${token}` } : {}
+    },
+  },
+)
 
 // app/stores/auth.ts
 export const useAuthStore = defineStore('auth', () =>

package/dist/api/index.d.ts

@@ -1,8 +1,5 @@
 import { UserManager } from "oidc-client-ts";
-import { Treaty } from "@elysiajs/eden";
-import { Elysia } from "elysia";
 //#region src/api/client.d.ts
-type AnyElysia = Elysia<any, any, any, any, any, any, any>;
 interface ResolveApiBaseUrlOptions {
   /**
    * The explicitly configured URL, first-match-wins — e.g.
@@ -26,40 +23,5 @@ declare function resolveApiBaseUrl(options: ResolveApiBaseUrlOptions): string;
  * access token, or `null` when there is no non-expired session.
  */
 declare function createAccessTokenProvider(getUserManager: () => UserManager): () => Promise<string | null>;
-interface TreatyClientFactoryOptions {
-  /** Resolve (and memoize, if desired) the base URL at first client use. */
-  getBaseUrl: () => string;
-  /** Bearer token per request; `null` sends no Authorization header. */
-  getAccessToken: () => Promise<string | null>;
-  /**
-   * Eden Treaty's auto-Date parsing on responses. Default `false`: with the
-   * default `true`, any `YYYY-MM-DD` string in a response is silently
-   * converted to a `Date` object, which then JSON-serializes back as a full
-   * ISO datetime on the next request — breaking server-side "plain ISO date
-   * string" validation. Keep the wire contract string-typed unless the API
-   * genuinely round-trips Date objects.
-   */
-  parseDate?: boolean;
-  /**
-   * Additional header source(s), applied after the bearer injector — a later
-   * entry wins on key collision, so consumers can add or override headers
-   * without losing the Authorization injection.
-   */
-  headers?: Treaty.Config['headers'];
-  /** Extra Treaty config (fetcher, onRequest, …), applied last. */
-  treatyConfig?: Omit<Treaty.Config, 'headers' | 'parseDate'>;
-}
-/**
- * Lazily-created Eden Treaty client singleton with OIDC bearer injection.
- *
- * ```ts
- * const getClient = createTreatyClientFactory<App>({ getBaseUrl, getAccessToken })
- * export function useApi() {
- *   const client = getClient()
- *   return { api: client.api, client }
- * }
- * ```
- */
-declare function createTreatyClientFactory<App extends AnyElysia>(options: TreatyClientFactoryOptions): () => Treaty.Create<App>;
 //#endregion
-export { type ResolveApiBaseUrlOptions, type TreatyClientFactoryOptions, createAccessTokenProvider, createTreatyClientFactory, resolveApiBaseUrl };
+export { type ResolveApiBaseUrlOptions, createAccessTokenProvider, resolveApiBaseUrl };

package/dist/api/index.js

@@ -1,4 +1,3 @@
-import { treaty } from "@elysiajs/eden";
 //#region src/api/client.ts
 /**
 * Resolve the API base URL: configured value, else the page origin in
@@ -19,33 +18,5 @@ function createAccessTokenProvider(getUserManager) {
 		return user.access_token;
 	};
 }
-/**
-* Lazily-created Eden Treaty client singleton with OIDC bearer injection.
-*
-* ```ts
-* const getClient = createTreatyClientFactory<App>({ getBaseUrl, getAccessToken })
-* export function useApi() {
-*   const client = getClient()
-*   return { api: client.api, client }
-* }
-* ```
-*/
-function createTreatyClientFactory(options) {
-	let client = null;
-	return function getClient() {
-		if (client) return client;
-		const bearerInjector = async () => {
-			const token = await options.getAccessToken();
-			if (token) return { authorization: `Bearer ${token}` };
-		};
-		const extraHeaders = options.headers === void 0 ? [] : Array.isArray(options.headers) ? options.headers : [options.headers];
-		client = treaty(options.getBaseUrl(), {
-			parseDate: options.parseDate ?? false,
-			headers: [bearerInjector, ...extraHeaders],
-			...options.treatyConfig
-		});
-		return client;
-	};
-}
 //#endregion
-export { createAccessTokenProvider, createTreatyClientFactory, resolveApiBaseUrl };
+export { createAccessTokenProvider, resolveApiBaseUrl };

package/dist/events/index.js

@@ -43,7 +43,6 @@ function createSseFrameParser() {
 				if (Number.isInteger(parsed) && parsed >= 0) retry = parsed;
 				break;
 			}
-			default: break;
 		}
 	}
 	function push(chunk) {

package/dist/index.d.ts

@@ -2,7 +2,7 @@ import { Component, ComputedRef, InjectionKey, Ref } from "vue";
 import { RouteLocationRaw } from "vue-router";
 //#region src/org/orgStore.d.ts
 type OrgStorage = Pick<Storage, 'getItem' | 'setItem' | 'removeItem'>;
-/** Result seam for the org fetch — mirrors an Eden Treaty `{ data, error }`. */
+/** Result seam for the org fetch — a `{ data, error }` pair, whatever the client. */
 type FetchOrganizationsResult<TOrg> = {
   items: TOrg[];
   error?: undefined;
@@ -119,6 +119,33 @@ declare function createApiErrorMessenger(options: ApiErrorMessengerOptions): {
 };
 //#endregion
 //#region src/components/pageActions.d.ts
+/**
+ * A set of actions that are alternative ANSWERS to one question, collapsed
+ * into a single inline control.
+ *
+ * The distinction it draws is between a bar that asks one thing and a bar that
+ * asks several. Three buttons — "record yes", "record no", "record silence" —
+ * are not three operations; they are one operation with three outcomes, and
+ * rendered as peers they read as three independent things to do, indistinguish-
+ * able from the unrelated tools beside them. Grouped, the bar asks the question
+ * once and the answers live inside it.
+ *
+ * Use it ONLY for mutually exclusive outcomes. A pair like confirm/cancel that
+ * an operator may legitimately reach for at different moments is two buttons,
+ * not a group with two rows behind a chevron.
+ *
+ * Repeat the same descriptor object on every member (declare it once as a const
+ * and reference it); the first member's copy defines the trigger and fixes the
+ * group's position in the bar.
+ */
+interface PageActionsGroup {
+  /** Stable group identity. Doubles as the overflow-menu section id. */
+  id: string;
+  /** The question, as a verb phrase — "Record answer", "Close out". */
+  label: string;
+  /** Trigger icon. Falls back to the first member's. */
+  icon?: string;
+}
 /**
  * Declarative page-header action. One array describes every action of a page —
  * inline buttons and overflow-menu items alike — and `PageActions` decides
@@ -139,6 +166,20 @@ interface PageActionsItem {
   description?: string;
   /** Inline button tone. At most ONE 'primary' item should be visible per state. */
   tone?: 'primary' | 'neutral';
+  /**
+   * Collapse this item into a shared decision control with its group siblings.
+   *
+   * Inline, the group renders as ONE outline trigger labeled `group.label` with
+   * the members as rows — solid instead if any inline member carries
+   * `tone: 'primary'`, so the one-solid-primary rule still holds and a grouped
+   * beat still reads as the beat. A group with a single available member skips
+   * the dropdown and renders that member as an ordinary button; a chevron
+   * hiding one row is chrome pretending to be a choice.
+   *
+   * In the overflow menu the members are flat rows in a section of their own —
+   * a submenu would bury an answer two levels deep.
+   */
+  group?: PageActionsGroup;
   /**
    * Placement tier:
    * - 'always' — inline at every width (the state's main action)
@@ -151,7 +192,9 @@ interface PageActionsItem {
    * Menu group id for 'menu' items (default 'default'). Groups render as
    * separated menu sections in first-appearance order; collapsed 'auto' items
    * form the leading group and utility items the trailing one. Convention:
-   * put destructive rows in the last-declared section.
+   * put destructive rows in the last-declared section. Defaults to `group.id`
+   * when the item belongs to a decision group, so grouped answers stay together
+   * in the menu without restating the section.
    */
   section?: string;
   /** Menu-item color (e.g. 'error' for destructive rows). Inline tone wins inline. */
@@ -243,10 +286,16 @@ declare function useDirtyTracking<T extends Record<string, unknown>>(state: T):
  * Offset-based table pagination: `page`/`itemsPerPage`/`total` state with a
  * derived `offset` and ready-to-spread `queryParams { limit, offset }`.
  * `onPaginationChange` fires whenever page or page size changes (refetch hook).
+ * It may be async — the refetch it triggers almost always is — and the return
+ * value is deliberately ignored rather than awaited: the watcher is a
+ * fire-and-forget notification, not a lifecycle the caller can join. Typing it
+ * `() => void` instead made every async loader passed here a
+ * `no-misused-promises` finding at the call site (18 of them in reynt's
+ * console) for a shape that is correct by design.
  */
 declare function usePagination(options?: {
   defaultLimit?: number;
-  onPaginationChange?: () => void;
+  onPaginationChange?: () => void | Promise<void>;
 }): {
   page: import("vue").Ref<number, number>;
   itemsPerPage: import("vue").Ref<number, number>;
@@ -260,4 +309,4 @@ declare function usePagination(options?: {
   resetPagination: () => void;
 };
 //#endregion
-export { type ApiErrorLike, type ApiErrorMessengerOptions, type ConfirmOptions, type FetchOrganizationsResult, HELP_PANEL_KEY, type HelpPanel, type HelpPanelAction, type HelpPanelOptions, type HelpPanelRegistration, type OrgStoreCore, type OrgStoreCoreOptions, PAGE_ACTIONS_COLLAPSE_BELOW, PAGE_HEADER_WIDTH, type PageActionsItem, type ValidationApiErrorLike, createApiErrorMessenger, createOrgStoreCore, resolveRuntimeConfigValue, useConfirm, useConfirmState, useDirtyTracking, useHelpPanel, usePagination };
+export { type ApiErrorLike, type ApiErrorMessengerOptions, type ConfirmOptions, type FetchOrganizationsResult, HELP_PANEL_KEY, type HelpPanel, type HelpPanelAction, type HelpPanelOptions, type HelpPanelRegistration, type OrgStoreCore, type OrgStoreCoreOptions, PAGE_ACTIONS_COLLAPSE_BELOW, PAGE_HEADER_WIDTH, type PageActionsGroup, type PageActionsItem, type ValidationApiErrorLike, createApiErrorMessenger, createOrgStoreCore, resolveRuntimeConfigValue, useConfirm, useConfirmState, useDirtyTracking, useHelpPanel, usePagination };

package/dist/index.js

@@ -120,7 +120,10 @@ function useConfirmState() {
 *
 * Framework-free: pass `t`/`te` from your i18n instance (the app-side
 * composable is typically `const { t, te } = useI18n()` + this factory).
-* Eden Treaty error envelopes (`{ value }`) are unwrapped automatically.
+* Errors wrapped in a `{ value }` envelope are unwrapped automatically — Eden
+* Treaty's error shape originally, kept because it costs nothing and any
+* client that boxes the body the same way gets the same handling. Hono's `hc`
+* hands back the parsed body directly, so it takes the unwrapped path.
 */
 /** Lowercase + collapse every non-alphanumeric run to `_` (trimmed) — a flat, definable vue-i18n key segment. */
 function i18nSlug(value) {
@@ -246,6 +249,12 @@ function useDirtyTracking(state) {
 * Offset-based table pagination: `page`/`itemsPerPage`/`total` state with a
 * derived `offset` and ready-to-spread `queryParams { limit, offset }`.
 * `onPaginationChange` fires whenever page or page size changes (refetch hook).
+* It may be async — the refetch it triggers almost always is — and the return
+* value is deliberately ignored rather than awaited: the watcher is a
+* fire-and-forget notification, not a lifecycle the caller can join. Typing it
+* `() => void` instead made every async loader passed here a
+* `no-misused-promises` finding at the call site (18 of them in reynt's
+* console) for a shape that is correct by design.
 */
 function usePagination(options = {}) {
 	const { defaultLimit = 50, onPaginationChange } = options;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@octabits-io/nuxt-ui-kit",
-  "version": "0.14.2",
-  "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",
+  "version": "0.16.0",
+  "description": "Frontend kit for Nuxt/Vue admin SPAs: OIDC session harness (oidc-client-ts), API-client seams (base URL + OIDC bearer), 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",
   "exports": {
@@ -73,22 +73,18 @@
     "url": "https://github.com/octabits-io/platform/issues"
   },
   "devDependencies": {
-    "@elysiajs/eden": "^1.4.9",
     "date-fns": "^4.4.0",
-    "elysia": "^1.4.29",
     "oidc-client-ts": "^3.5.0",
-    "vitest": "^4.1.10",
+    "vitest": "^4.1.11",
     "vue": "^3.5.41",
     "zod": "^4.4.3",
-    "@octabits-io/framework": "^0.22.0"
+    "@octabits-io/framework": "^0.33.0"
   },
   "peerDependencies": {
-    "@elysiajs/eden": "^1.4.0",
     "@internationalized/date": "^3",
     "@nuxt/ui": "^4",
     "@octabits-io/framework": ">=0.4.0 <1",
     "date-fns": "^3 || ^4",
-    "elysia": ">=1.4 <3",
     "oidc-client-ts": "^3.3.0",
     "typescript": "^5 || ^6 || ^7",
     "vue": "^3.5.0",
@@ -97,9 +93,6 @@
     "zod": "^4"
   },
   "peerDependenciesMeta": {
-    "@elysiajs/eden": {
-      "optional": true
-    },
     "@octabits-io/framework": {
       "optional": true
     },
@@ -112,9 +105,6 @@
     "date-fns": {
       "optional": true
     },
-    "elysia": {
-      "optional": true
-    },
     "oidc-client-ts": {
       "optional": true
     },

package/src/components/PageActions.vue

@@ -14,7 +14,16 @@ import PageActionMenu from './PageActionMenu.vue';
 // Package-name import (not ../composables): only src/components is packed, and
 // the dist-barrel Symbol instance must match the consumer's HELP_PANEL_KEY provider.
 import { HELP_PANEL_KEY } from '@octabits-io/nuxt-ui-kit';
-import { PAGE_ACTIONS_COLLAPSE_BELOW, PAGE_HEADER_WIDTH, type PageActionsItem } from './pageActions.ts';
+import UButton from '@nuxt/ui/components/Button.vue';
+import {
+  PAGE_ACTIONS_COLLAPSE_BELOW,
+  PAGE_HEADER_WIDTH,
+  foldInlineActions,
+  groupIsPrimary,
+  isInlineBound as isItemInlineBound,
+  resolveCollapseStages,
+  type PageActionsItem,
+} from './pageActions.ts';
 
 /**
  * Width-aware page-header action cluster: one declarative list drives both the
@@ -23,6 +32,12 @@ import { PAGE_ACTIONS_COLLAPSE_BELOW, PAGE_HEADER_WIDTH, type PageActionsItem }
  * only 'always' items stay inline and everything else — 'auto' items, utility
  * items, and the Help trigger — moves into the ⋯ menu, keeping its label.
  *
+ * Items sharing a `group` fold into ONE inline control (see `PageActionsGroup`):
+ * mutually exclusive answers to a single question stop competing for the bar as
+ * peers. This is the only rank between "inline button" and "buried in ⋯" —
+ * without it every neutral inline action is the same ghost weight, and a bar of
+ * six says nothing about which one an operator reaches for.
+ *
  * The Help trigger is rendered automatically when a `HELP_PANEL_KEY` registry
  * with registered actions is provided (replaces `PageUtilityActions` on pages
  * using this component — pass `:utility="false"` to `PageHeader`).
@@ -35,6 +50,25 @@ const props = withDefaults(defineProps<{
   utilityItems?: PageActionsItem[]
   /** Header width (px) below which 'auto'/utility items collapse into the menu. */
   collapseBelow?: number
+  /**
+   * Header width (px) below which ONLY the utility region (utility items + the
+   * Help trigger) collapses into the menu, while every action stays inline.
+   *
+   * Exists because the fallback below `collapseBelow` is `flex-wrap`, and a bar
+   * that does not fit therefore WRAPS rather than collapsing — silently, into
+   * two or three rows, with the record's title stranded on a line of its own.
+   * Between `collapseBelow` and "actually fits" that was the only behaviour
+   * available, and it dropped nothing, so it chose the wrap point arbitrarily.
+   *
+   * A second threshold makes the loss ordered instead: utilities go first,
+   * because they are the only things in the bar that change nothing — then the
+   * 'auto' actions at `collapseBelow`, then the wrap. Set it per header from
+   * what that header's widest state actually needs.
+   *
+   * Defaults to `collapseBelow`, i.e. no separate stage and no change for any
+   * caller that does not ask for one.
+   */
+  utilityCollapseBelow?: 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. */
@@ -42,6 +76,7 @@ const props = withDefaults(defineProps<{
 }>(), {
   utilityItems: () => [],
   collapseBelow: PAGE_ACTIONS_COLLAPSE_BELOW,
+  utilityCollapseBelow: undefined,
   help: true,
 });
 
@@ -51,21 +86,24 @@ const headerWidth = inject(PAGE_HEADER_WIDTH, null);
 
 // null (no PageHeader provider / pre-measurement) counts as wide — the
 // flex-wrap fallback keeps an unexpectedly narrow first frame usable.
-const collapsed = computed(() => {
-  const width = headerWidth?.value;
-  return width != null && width < props.collapseBelow;
-});
+const stages = computed(() =>
+  resolveCollapseStages(headerWidth?.value ?? null, props.collapseBelow, props.utilityCollapseBelow),
+);
+const collapsed = computed(() => stages.value.collapsed);
+const utilitiesCollapsed = computed(() => stages.value.utilitiesCollapsed);
 
 const showHelp = computed(() => props.help && Boolean(helpPanel?.hasActions.value));
 
 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);
+const isInlineBound = (item: PageActionsItem) => isItemInlineBound(item, collapsed.value);
 
-const inlineItems = computed(() => actionItems.value.filter(isInlineBound));
+const inlineEntries = computed(() => foldInlineActions(actionItems.value, collapsed.value));
+
+function toGroupMenuItem(item: PageActionsItem): DropdownMenuItem {
+  return { ...toMenuItem(item), description: item.description };
+}
 
 // AI cluster: one inline item renders as its own verb-labeled AiButton; several
 // share a labeled "AI ∨" dropdown (icons + descriptions per row).
@@ -81,7 +119,7 @@ const aiDropdownItems = computed<DropdownMenuItem[]>(() =>
   })),
 );
 
-const inlineUtilityItems = computed(() => collapsed.value ? [] : props.utilityItems);
+const inlineUtilityItems = computed(() => utilitiesCollapsed.value ? [] : props.utilityItems);
 
 // Descriptions render only in the dedicated AI dropdown (which has wrap/width
 // styling) — the compact ⋯ overflow stays label-only.
@@ -107,7 +145,7 @@ const menuGroups = computed<DropdownMenuItem[][]>(() => {
   const sections = new Map<string, PageActionsItem[]>();
   for (const item of actionItems.value) {
     if ((item.visibility ?? 'auto') !== 'menu') continue;
-    const section = item.section ?? 'default';
+    const section = item.section ?? item.group?.id ?? 'default';
     if (!sections.has(section)) sections.set(section, []);
     sections.get(section)!.push(item);
   }
@@ -119,7 +157,7 @@ const menuGroups = computed<DropdownMenuItem[][]>(() => {
     || ((item.visibility ?? 'auto') === 'auto' && collapsed.value),
   );
 
-  const utilityGroup: DropdownMenuItem[] = collapsed.value
+  const utilityGroup: DropdownMenuItem[] = utilitiesCollapsed.value
     ? [
         ...props.utilityItems.map(toMenuItem),
         ...(showHelp.value && helpPanel
@@ -137,25 +175,49 @@ const menuGroups = computed<DropdownMenuItem[][]>(() => {
 });
 
 const hasUtilityRegion = computed(() =>
-  inlineUtilityItems.value.length > 0 || (showHelp.value && !collapsed.value),
+  inlineUtilityItems.value.length > 0 || (showHelp.value && !utilitiesCollapsed.value),
 );
 </script>
 
 <template>
-  <PageAction
-    v-for="item in inlineItems"
-    :key="item.key"
-    :icon="item.icon"
-    :label="item.label"
-    show-label
-    :tone="item.tone ?? 'neutral'"
-    :loading="item.loading"
-    :disabled="item.disabled"
-    :disabled-reason="item.disabledReason"
-    :to="item.to"
-    :target="item.target"
-    @click="item.onSelect?.()"
-  />
+  <template v-for="entry in inlineEntries" :key="entry.type === 'group' ? entry.group.id : entry.item.key">
+    <PageAction
+      v-if="entry.type === 'item'"
+      :icon="entry.item.icon"
+      :label="entry.item.label"
+      show-label
+      :tone="entry.item.tone ?? 'neutral'"
+      :loading="entry.item.loading"
+      :disabled="entry.item.disabled"
+      :disabled-reason="entry.item.disabledReason"
+      :to="entry.item.to"
+      :target="entry.item.target"
+      @click="entry.item.onSelect?.()"
+    />
+    <!-- A decision group: one question, its answers inside. Outline rather
+         than ghost — it is a decision, and the ghost tools beside it are not.
+         Solid when it carries the state's primary. -->
+    <UDropdownMenu
+      v-else
+      :items="[entry.items.map(toGroupMenuItem)]"
+      :content="{ align: 'end' }"
+      :ui="{
+        content: 'w-64',
+        item: 'gap-2.5 p-2',
+        itemLabel: 'font-medium text-highlighted',
+        itemDescription: 'mt-0.5 whitespace-normal text-xs/4',
+      }"
+    >
+      <UButton
+        :icon="entry.group.icon ?? entry.items[0]!.icon"
+        :label="entry.group.label"
+        size="md"
+        :color="groupIsPrimary(entry.items) ? 'primary' : 'neutral'"
+        :variant="groupIsPrimary(entry.items) ? 'solid' : 'outline'"
+        trailing-icon="i-lucide-chevron-down"
+      />
+    </UDropdownMenu>
+  </template>
   <!-- AI cluster: soft-primary sparkles = "AI acts on data". One item → its
        verb label; several → the shared labeled dropdown. `size="md"` matches
        PageAction — AiButton keeps its `sm` default for in-page triggers. -->
@@ -203,7 +265,7 @@ const hasUtilityRegion = computed(() =>
       @click="item.onSelect?.()"
     />
     <PageAction
-      v-if="showHelp && helpPanel"
+      v-if="showHelp && !utilitiesCollapsed && helpPanel"
       icon="i-lucide-circle-help"
       :label="t('pageChrome.help')"
       show-label

package/src/components/pageActions.test.ts

@@ -0,0 +1,158 @@
+import { describe, expect, it } from 'vitest';
+import {
+  foldInlineActions,
+  groupIsPrimary,
+  isInlineBound,
+  resolveCollapseStages,
+  type PageActionsGroup,
+  type PageActionsItem,
+} from './pageActions.ts';
+
+/**
+ * The rank between "inline button" and "buried in ⋯".
+ *
+ * Without a group the bar has exactly two inline weights — one solid primary
+ * and N identical ghosts — so a set of alternative outcomes is indistinguish-
+ * able from the unrelated tools beside it. These tests pin the folding, because
+ * every property that makes a group readable (its position, what it swallows,
+ * what it refuses to swallow) is silent when it breaks: the bar still renders,
+ * it just renders wrong.
+ */
+
+const ANSWER: PageActionsGroup = { id: 'answer', label: 'Record answer', icon: 'i-lucide-reply' };
+const CLOSEOUT: PageActionsGroup = { id: 'closeout', label: 'Close out' };
+
+const item = (over: Partial<PageActionsItem> & { key: string }): PageActionsItem => ({
+  icon: 'i-lucide-dot',
+  label: over.key,
+  ...over,
+});
+
+const keysOf = (entries: ReturnType<typeof foldInlineActions>) =>
+  entries.map((entry) => (entry.type === 'group' ? `${entry.group.id}[${entry.items.map((i) => i.key).join(',')}]` : entry.item.key));
+
+describe('isInlineBound', () => {
+  it("keeps 'always' inline at every width and drops 'menu' at every width", () => {
+    for (const collapsed of [false, true]) {
+      expect(isInlineBound(item({ key: 'a', visibility: 'always' }), collapsed)).toBe(true);
+      expect(isInlineBound(item({ key: 'm', visibility: 'menu' }), collapsed)).toBe(false);
+    }
+  });
+
+  it("collapses 'auto' — the default — only when narrow", () => {
+    expect(isInlineBound(item({ key: 'a' }), false)).toBe(true);
+    expect(isInlineBound(item({ key: 'a' }), true)).toBe(false);
+  });
+});
+
+describe('foldInlineActions', () => {
+  it('folds group members into one entry at the FIRST member position', () => {
+    // The group must not drift to the end of the bar: an operator reads the bar
+    // left to right, and the caller's declaration order is the reading order.
+    const entries = foldInlineActions([
+      item({ key: 'publish', visibility: 'always' }),
+      item({ key: 'yes', group: ANSWER, visibility: 'always' }),
+      item({ key: 'tool' }),
+      item({ key: 'no', group: ANSWER, visibility: 'always' }),
+      item({ key: 'silence', group: ANSWER, visibility: 'always' }),
+    ], false);
+
+    expect(keysOf(entries)).toEqual(['publish', 'answer[yes,no,silence]', 'tool']);
+  });
+
+  it('keeps separate groups separate', () => {
+    const entries = foldInlineActions([
+      item({ key: 'yes', group: ANSWER, visibility: 'always' }),
+      item({ key: 'departed', group: CLOSEOUT, visibility: 'always' }),
+      item({ key: 'no', group: ANSWER, visibility: 'always' }),
+      item({ key: 'no-show', group: CLOSEOUT, visibility: 'always' }),
+    ], false);
+
+    expect(keysOf(entries)).toEqual(['answer[yes,no]', 'closeout[departed,no-show]']);
+  });
+
+  it('unwraps a group left with one available member', () => {
+    // A chevron over a single row is chrome pretending to be a choice — and the
+    // unwrapped member must render as itself, keeping its own label and tone.
+    const entries = foldInlineActions([
+      item({ key: 'yes', group: ANSWER, visibility: 'always', tone: 'primary' }),
+      item({ key: 'no', group: ANSWER, visibility: 'menu' }),
+    ], false);
+
+    expect(entries).toHaveLength(1);
+    expect(entries[0]).toMatchObject({ type: 'item', item: { key: 'yes', tone: 'primary' } });
+  });
+
+  it('never offers a row the state disallows', () => {
+    // A member the caller sent to the menu is not an answer the operator may
+    // give — the trigger must not list it.
+    const entries = foldInlineActions([
+      item({ key: 'yes', group: ANSWER, visibility: 'always' }),
+      item({ key: 'no', group: ANSWER, visibility: 'always' }),
+      item({ key: 'silence', group: ANSWER, visibility: 'menu' }),
+    ], false);
+
+    expect(keysOf(entries)).toEqual(['answer[yes,no]']);
+  });
+
+  it("drops a whole group whose members are all 'auto' once collapsed", () => {
+    // They reappear as flat menu rows (menuGroups keys their section off
+    // group.id) rather than as a submenu — an answer two levels deep is buried.
+    const items = [
+      item({ key: 'yes', group: ANSWER }),
+      item({ key: 'no', group: ANSWER }),
+    ];
+    expect(keysOf(foldInlineActions(items, false))).toEqual(['answer[yes,no]']);
+    expect(foldInlineActions(items, true)).toEqual([]);
+  });
+
+  it('leaves ungrouped bars exactly as they were', () => {
+    const items = [
+      item({ key: 'confirm', tone: 'primary', visibility: 'always' }),
+      item({ key: 'cancel' }),
+      item({ key: 'archive', visibility: 'menu' }),
+    ];
+    expect(keysOf(foldInlineActions(items, false))).toEqual(['confirm', 'cancel']);
+    expect(keysOf(foldInlineActions(items, true))).toEqual(['confirm']);
+  });
+});
+
+describe('groupIsPrimary', () => {
+  it('is solid when the group carries the beat, outline otherwise', () => {
+    // Folding a beat into a group must not demote it — close-out IS what the
+    // rail asks for, and it has to keep reading as the one solid button.
+    expect(groupIsPrimary([item({ key: 'departed', tone: 'primary' }), item({ key: 'no-show' })])).toBe(true);
+    // Nothing is due while an offer waits on the guest, so nothing shouts.
+    expect(groupIsPrimary([item({ key: 'yes' }), item({ key: 'no' })])).toBe(false);
+  });
+});
+
+describe('resolveCollapseStages', () => {
+  const stages = (width: number | null) => resolveCollapseStages(width, 640, 880);
+
+  it('drops the utilities before it drops any action', () => {
+    // The band this exists for: wide enough that nothing used to collapse, too
+    // narrow to fit — where the header silently wrapped instead.
+    expect(stages(900)).toEqual({ collapsed: false, utilitiesCollapsed: false });
+    expect(stages(700)).toEqual({ collapsed: false, utilitiesCollapsed: true });
+    expect(stages(500)).toEqual({ collapsed: true, utilitiesCollapsed: true });
+  });
+
+  it('never leaves the utilities inline while the optional actions are gone', () => {
+    // A caller passing a utility threshold BELOW collapseBelow would otherwise
+    // produce exactly that bar. `collapsed` implies the utility stage.
+    expect(resolveCollapseStages(500, 640, 300)).toEqual({ collapsed: true, utilitiesCollapsed: true });
+  });
+
+  it('treats a pre-measurement width as wide', () => {
+    // Otherwise every mount flashes a collapsed bar before the observer fires.
+    expect(resolveCollapseStages(null, 640, 880)).toEqual({ collapsed: false, utilitiesCollapsed: false });
+  });
+
+  it('is a no-op stage when no utility threshold is given', () => {
+    for (const width of [500, 700, 900]) {
+      const s = resolveCollapseStages(width, 640);
+      expect(s.utilitiesCollapsed).toBe(s.collapsed);
+    }
+  });
+});

package/src/components/pageActions.ts

@@ -1,6 +1,34 @@
 import type { InjectionKey, Ref } from 'vue';
 import type { RouteLocationRaw } from 'vue-router';
 
+/**
+ * A set of actions that are alternative ANSWERS to one question, collapsed
+ * into a single inline control.
+ *
+ * The distinction it draws is between a bar that asks one thing and a bar that
+ * asks several. Three buttons — "record yes", "record no", "record silence" —
+ * are not three operations; they are one operation with three outcomes, and
+ * rendered as peers they read as three independent things to do, indistinguish-
+ * able from the unrelated tools beside them. Grouped, the bar asks the question
+ * once and the answers live inside it.
+ *
+ * Use it ONLY for mutually exclusive outcomes. A pair like confirm/cancel that
+ * an operator may legitimately reach for at different moments is two buttons,
+ * not a group with two rows behind a chevron.
+ *
+ * Repeat the same descriptor object on every member (declare it once as a const
+ * and reference it); the first member's copy defines the trigger and fixes the
+ * group's position in the bar.
+ */
+export interface PageActionsGroup {
+  /** Stable group identity. Doubles as the overflow-menu section id. */
+  id: string;
+  /** The question, as a verb phrase — "Record answer", "Close out". */
+  label: string;
+  /** Trigger icon. Falls back to the first member's. */
+  icon?: string;
+}
+
 /**
  * Declarative page-header action. One array describes every action of a page —
  * inline buttons and overflow-menu items alike — and `PageActions` decides
@@ -21,6 +49,20 @@ export interface PageActionsItem {
   description?: string;
   /** Inline button tone. At most ONE 'primary' item should be visible per state. */
   tone?: 'primary' | 'neutral';
+  /**
+   * Collapse this item into a shared decision control with its group siblings.
+   *
+   * Inline, the group renders as ONE outline trigger labeled `group.label` with
+   * the members as rows — solid instead if any inline member carries
+   * `tone: 'primary'`, so the one-solid-primary rule still holds and a grouped
+   * beat still reads as the beat. A group with a single available member skips
+   * the dropdown and renders that member as an ordinary button; a chevron
+   * hiding one row is chrome pretending to be a choice.
+   *
+   * In the overflow menu the members are flat rows in a section of their own —
+   * a submenu would bury an answer two levels deep.
+   */
+  group?: PageActionsGroup;
   /**
    * Placement tier:
    * - 'always' — inline at every width (the state's main action)
@@ -33,7 +75,9 @@ export interface PageActionsItem {
    * Menu group id for 'menu' items (default 'default'). Groups render as
    * separated menu sections in first-appearance order; collapsed 'auto' items
    * form the leading group and utility items the trailing one. Convention:
-   * put destructive rows in the last-declared section.
+   * put destructive rows in the last-declared section. Defaults to `group.id`
+   * when the item belongs to a decision group, so grouped answers stay together
+   * in the menu without restating the section.
    */
   section?: string;
   /** Menu-item color (e.g. 'error' for destructive rows). Inline tone wins inline. */
@@ -55,3 +99,97 @@ export const PAGE_HEADER_WIDTH: InjectionKey<Ref<number | null>> = Symbol('page-
 
 /** Below this header width (px), 'auto' actions and utilities collapse into the menu. */
 export const PAGE_ACTIONS_COLLAPSE_BELOW = 640;
+
+/** One slot in the inline bar: a lone action, or a folded decision group. */
+export type PageActionsInlineEntry =
+  | { type: 'item'; item: PageActionsItem }
+  | { type: 'group'; group: PageActionsGroup; items: PageActionsItem[] };
+
+/** Whether an item renders inline at the current width. */
+export function isInlineBound(item: PageActionsItem, collapsed: boolean): boolean {
+  const visibility = item.visibility ?? 'auto';
+  return visibility === 'always' || (visibility === 'auto' && !collapsed);
+}
+
+/**
+ * The inline bar, in declaration order, with decision groups folded.
+ *
+ * Folded in a single pass over the original array rather than by partitioning
+ * it, because a group's position in the bar is its FIRST member's — pulling
+ * groups out and appending them would reorder the bar behind the caller's back.
+ *
+ * A group whose members are split across visibility tiers keeps only the
+ * inline-bound ones, so a trigger never offers a row the state disallows; and a
+ * group left with one member unwraps to an ordinary button, because a chevron
+ * over a single row is chrome pretending to be a choice.
+ *
+ * Pure, and exported for its test — the SFC only renders what this returns.
+ */
+export function foldInlineActions(
+  items: PageActionsItem[],
+  collapsed: boolean,
+): PageActionsInlineEntry[] {
+  const entries: PageActionsInlineEntry[] = [];
+  const groupAt = new Map<string, number>();
+  for (const item of items) {
+    if (!isInlineBound(item, collapsed)) continue;
+    if (!item.group) {
+      entries.push({ type: 'item', item });
+      continue;
+    }
+    const at = groupAt.get(item.group.id);
+    if (at == null) {
+      groupAt.set(item.group.id, entries.length);
+      entries.push({ type: 'group', group: item.group, items: [item] });
+    } else {
+      (entries[at] as Extract<PageActionsInlineEntry, { type: 'group' }>).items.push(item);
+    }
+  }
+  return entries.map((entry) =>
+    entry.type === 'group' && entry.items.length === 1
+      ? { type: 'item' as const, item: entry.items[0]! }
+      : entry,
+  );
+}
+
+/**
+ * Solid only if the group carries the state's primary, so folding a beat into a
+ * group does not demote it and the one-solid-primary rule survives.
+ */
+export function groupIsPrimary(items: PageActionsItem[]): boolean {
+  return items.some((item) => item.tone === 'primary');
+}
+
+/** What the current header width leaves inline. */
+export interface PageActionsCollapseStages {
+  /** 'auto' actions, utility items and Help are all in the ⋯ menu. */
+  collapsed: boolean;
+  /** Utility items and Help are in the ⋯ menu; actions are still inline. */
+  utilitiesCollapsed: boolean;
+}
+
+/**
+ * The ordered stages of loss as a header narrows: utilities first, then the
+ * 'auto' actions, then (below everything) the header's own `flex-wrap`.
+ *
+ * `collapsed` implies `utilitiesCollapsed` by construction rather than by two
+ * comparisons agreeing — a caller passing a utility threshold BELOW
+ * `collapseBelow` would otherwise produce a bar that has dropped its optional
+ * actions while still rendering the optional utilities beside them.
+ *
+ * A null width is pre-measurement and counts as wide: the first frame renders
+ * everything and the ResizeObserver corrects it, rather than flashing a
+ * collapsed bar on every mount.
+ */
+export function resolveCollapseStages(
+  width: number | null,
+  collapseBelow: number,
+  utilityCollapseBelow?: number,
+): PageActionsCollapseStages {
+  if (width == null) return { collapsed: false, utilitiesCollapsed: false };
+  const collapsed = width < collapseBelow;
+  return {
+    collapsed,
+    utilitiesCollapsed: collapsed || width < (utilityCollapseBelow ?? collapseBelow),
+  };
+}