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

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 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 }`. */
@@ -117,6 +118,52 @@ declare function createApiErrorMessenger(options: ApiErrorMessengerOptions): {
   isValidationError: (error: unknown) => error is ValidationApiErrorLike;
 };
 //#endregion
+//#region src/components/pageActions.d.ts
+/**
+ * Declarative page-header action. One array describes every action of a page —
+ * inline buttons and overflow-menu items alike — and `PageActions` decides
+ * placement from `visibility` and the available header width.
+ */
+interface PageActionsItem {
+  /** Stable identity (also the Vue key). */
+  key: string;
+  icon: string;
+  label: string;
+  /** Inline button tone. At most ONE 'primary' item should be visible per state. */
+  tone?: 'primary' | 'neutral';
+  /**
+   * Placement tier:
+   * - 'always' — inline at every width (the state's main action)
+   * - 'auto'   — inline when the header is wide enough, else moved into the
+   *              overflow menu (default)
+   * - 'menu'   — overflow-menu only
+   */
+  visibility?: 'always' | 'auto' | 'menu';
+  /**
+   * 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.
+   */
+  section?: string;
+  /** Menu-item color (e.g. 'error' for destructive rows). Inline tone wins inline. */
+  color?: 'error' | 'warning';
+  loading?: boolean;
+  disabled?: boolean;
+  /** Blocked-with-reason: renders disabled; inline buttons tooltip "label — reason". */
+  disabledReason?: string | null;
+  to?: RouteLocationRaw;
+  target?: string;
+  onSelect?: () => void;
+}
+/**
+ * Current PageHeader content width in px, provided by `PageHeader` via a
+ * ResizeObserver. `null` until first measurement (treated as wide).
+ */
+declare const PAGE_HEADER_WIDTH: InjectionKey<Ref<number | null>>;
+/** Below this header width (px), 'auto' actions and utilities collapse into the menu. */
+declare const PAGE_ACTIONS_COLLAPSE_BELOW = 640;
+//#endregion
 //#region src/composables/useHelpPanel.d.ts
 interface HelpPanelAction {
   /** Unique key for this action within the tab */
@@ -205,4 +252,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, 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 PageActionsItem, type ValidationApiErrorLike, createApiErrorMessenger, createOrgStoreCore, resolveRuntimeConfigValue, useConfirm, useConfirmState, useDirtyTracking, useHelpPanel, usePagination };

package/dist/index.js

@@ -156,6 +156,15 @@ function createApiErrorMessenger(options) {
 	};
 }
 //#endregion
+//#region src/components/pageActions.ts
+/**
+* Current PageHeader content width in px, provided by `PageHeader` via a
+* ResizeObserver. `null` until first measurement (treated as wide).
+*/
+const PAGE_HEADER_WIDTH = Symbol("page-header-width");
+/** Below this header width (px), 'auto' actions and utilities collapse into the menu. */
+const PAGE_ACTIONS_COLLAPSE_BELOW = 640;
+//#endregion
 //#region src/composables/useHelpPanel.ts
 const HELP_PANEL_KEY = Symbol("help-panel");
 /**
@@ -268,4 +277,4 @@ function usePagination(options = {}) {
 	};
 }
 //#endregion
-export { HELP_PANEL_KEY, createApiErrorMessenger, createOrgStoreCore, resolveRuntimeConfigValue, useConfirm, useConfirmState, useDirtyTracking, useHelpPanel, usePagination };
+export { HELP_PANEL_KEY, PAGE_ACTIONS_COLLAPSE_BELOW, PAGE_HEADER_WIDTH, createApiErrorMessenger, createOrgStoreCore, resolveRuntimeConfigValue, useConfirm, useConfirmState, useDirtyTracking, useHelpPanel, usePagination };

package/package.json

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

@@ -0,0 +1,151 @@
+<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).
+import { computed, inject } from 'vue';
+import { useI18n } from 'vue-i18n';
+import USeparator from '@nuxt/ui/components/Separator.vue';
+import type { DropdownMenuItem } from '@nuxt/ui';
+import PageAction from './PageAction.vue';
+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';
+
+/**
+ * Width-aware page-header action cluster: one declarative list drives both the
+ * inline buttons and the overflow menu. Wide headers render 'always' + 'auto'
+ * items inline (all labeled, one solid primary max); below `collapseBelow`
+ * only 'always' items stay inline and everything else — 'auto' items, utility
+ * items, and the Help trigger — moves into the ⋯ menu, keeping its label.
+ *
+ * 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`).
+ */
+const props = withDefaults(defineProps<{
+  /** Entity actions (inline and/or menu, per `visibility`). */
+  items: PageActionsItem[]
+  /** Page-level utility triggers (e.g. "Ask about this booking"). Inline right
+   *  of a separator when wide; bottom menu group when collapsed. */
+  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();
+const helpPanel = inject(HELP_PANEL_KEY, null);
+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 showHelp = computed(() => props.help && Boolean(helpPanel?.hasActions.value));
+
+const inlineItems = computed(() => props.items.filter(item =>
+  (item.visibility ?? 'auto') === 'always'
+  || ((item.visibility ?? 'auto') === 'auto' && !collapsed.value),
+));
+
+const inlineUtilityItems = computed(() => collapsed.value ? [] : props.utilityItems);
+
+function toMenuItem(item: PageActionsItem): DropdownMenuItem {
+  return {
+    label: item.label,
+    icon: item.icon,
+    color: item.color,
+    disabled: item.disabled || Boolean(item.disabledReason),
+    loading: item.loading,
+    to: item.to,
+    target: item.target,
+    onSelect: item.onSelect,
+  };
+}
+
+const menuGroups = computed<DropdownMenuItem[][]>(() => {
+  const collapsedAutos = collapsed.value
+    ? props.items.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) {
+    if ((item.visibility ?? 'auto') !== 'menu') continue;
+    const section = item.section ?? 'default';
+    if (!sections.has(section)) sections.set(section, []);
+    sections.get(section)!.push(item);
+  }
+
+  const utilityGroup: DropdownMenuItem[] = collapsed.value
+    ? [
+        ...props.utilityItems.map(toMenuItem),
+        ...(showHelp.value && helpPanel
+          ? [{ label: t('pageChrome.help'), icon: 'i-lucide-circle-help', onSelect: () => helpPanel.toggle() }]
+          : []),
+      ]
+    : [];
+
+  return [
+    collapsedAutos.map(toMenuItem),
+    ...[...sections.values()].map(group => group.map(toMenuItem)),
+    utilityGroup,
+  ].filter(group => group.length > 0);
+});
+
+const hasUtilityRegion = computed(() =>
+  inlineUtilityItems.value.length > 0 || (showHelp.value && !collapsed.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?.()"
+  />
+  <PageActionMenu :items="menuGroups" />
+  <template v-if="hasUtilityRegion">
+    <USeparator orientation="vertical" class="h-5 mx-1" />
+    <PageAction
+      v-for="item in inlineUtilityItems"
+      :key="item.key"
+      :icon="item.icon"
+      :label="item.label"
+      show-label
+      :loading="item.loading"
+      :disabled="item.disabled"
+      :to="item.to"
+      :target="item.target"
+      @click="item.onSelect?.()"
+    />
+    <PageAction
+      v-if="showHelp && helpPanel"
+      icon="i-lucide-circle-help"
+      :label="t('pageChrome.help')"
+      show-label
+      @click="helpPanel.toggle()"
+    />
+  </template>
+</template>

package/src/components/PageHeader.vue

@@ -2,7 +2,7 @@
 // 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.back (+ PageActionMenu/PageUtilityActions keys).
-import { computed } from 'vue'
+import { computed, onBeforeUnmount, onMounted, provide, ref } from 'vue'
 import { useI18n } from 'vue-i18n'
 import { useRouter, type RouteLocationRaw } from 'vue-router'
 import UButton from '@nuxt/ui/components/Button.vue'
@@ -10,6 +10,7 @@ import USkeleton from '@nuxt/ui/components/Skeleton.vue'
 import type { DropdownMenuItem } from '@nuxt/ui'
 import PageActionMenu from './PageActionMenu.vue'
 import PageUtilityActions from './PageUtilityActions.vue'
+import { PAGE_HEADER_WIDTH } from './pageActions.ts'
 
 /**
  * Standard page header.
@@ -27,6 +28,11 @@ import PageUtilityActions from './PageUtilityActions.vue'
  * - Header height, spacing, and tooltip behavior are normalized via `PageAction`.
  * - Utility triggers (Help, AI history, …) live in `#utility` (default =
  *   `PageUtilityActions`) and render as LABELED buttons, not icon-only.
+ *
+ * Prefer driving all of the above declaratively with `PageActions` (place it
+ * in `#actions`, pass `:utility="false"`): it enforces the conventions and
+ * collapses 'auto'/utility items into the ⋯ menu on narrow headers using the
+ * width this component provides via `PAGE_HEADER_WIDTH`.
  */
 const props = withDefaults(defineProps<{
   title?: string
@@ -56,6 +62,22 @@ const props = withDefaults(defineProps<{
 const { t } = useI18n()
 const router = useRouter()
 
+// Measured content width for PageActions' collapse decision. null until the
+// first observation (treated as wide — the flex-wrap fallback covers it).
+const wrapperEl = ref<HTMLElement | null>(null)
+const headerWidth = ref<number | null>(null)
+provide(PAGE_HEADER_WIDTH, headerWidth)
+
+let observer: ResizeObserver | null = null
+onMounted(() => {
+  if (!wrapperEl.value || typeof ResizeObserver === 'undefined') return
+  observer = new ResizeObserver((entries) => {
+    headerWidth.value = entries[0]?.contentRect.width ?? null
+  })
+  observer.observe(wrapperEl.value)
+})
+onBeforeUnmount(() => observer?.disconnect())
+
 function onBack() {
   if (typeof props.back === 'object' && props.back && 'to' in props.back) {
     router.push(props.back.to)
@@ -80,7 +102,7 @@ const titleClass = computed(() => props.density === 'compact' ? 'font-display te
 </script>
 
 <template>
-  <div :class="wrapperClass">
+  <div ref="wrapperEl" :class="wrapperClass">
     <UButton
       v-if="back"
       icon="i-lucide-arrow-left"

package/src/components/pageActions.ts

@@ -0,0 +1,49 @@
+import type { InjectionKey, Ref } from 'vue';
+import type { RouteLocationRaw } from 'vue-router';
+
+/**
+ * Declarative page-header action. One array describes every action of a page —
+ * inline buttons and overflow-menu items alike — and `PageActions` decides
+ * placement from `visibility` and the available header width.
+ */
+export interface PageActionsItem {
+  /** Stable identity (also the Vue key). */
+  key: string;
+  icon: string;
+  label: string;
+  /** Inline button tone. At most ONE 'primary' item should be visible per state. */
+  tone?: 'primary' | 'neutral';
+  /**
+   * Placement tier:
+   * - 'always' — inline at every width (the state's main action)
+   * - 'auto'   — inline when the header is wide enough, else moved into the
+   *              overflow menu (default)
+   * - 'menu'   — overflow-menu only
+   */
+  visibility?: 'always' | 'auto' | 'menu';
+  /**
+   * 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.
+   */
+  section?: string;
+  /** Menu-item color (e.g. 'error' for destructive rows). Inline tone wins inline. */
+  color?: 'error' | 'warning';
+  loading?: boolean;
+  disabled?: boolean;
+  /** Blocked-with-reason: renders disabled; inline buttons tooltip "label — reason". */
+  disabledReason?: string | null;
+  to?: RouteLocationRaw;
+  target?: string;
+  onSelect?: () => void;
+}
+
+/**
+ * Current PageHeader content width in px, provided by `PageHeader` via a
+ * ResizeObserver. `null` until first measurement (treated as wide).
+ */
+export const PAGE_HEADER_WIDTH: InjectionKey<Ref<number | null>> = Symbol('page-header-width');
+
+/** Below this header width (px), 'auto' actions and utilities collapse into the menu. */
+export const PAGE_ACTIONS_COLLAPSE_BELOW = 640;