@morscherlab/mint-sdk 1.0.0-beta.1 → 1.0.0-beta.3

package/src/components/AppTopBar.vue

@@ -1,18 +1,27 @@
 <script setup lang="ts">
 /** Full application top bar with brand logo, page selector or plugin switcher, centered pill nav, experiment popover, and avatar menu. */
-import { ref, computed, inject, onMounted, onUnmounted } from 'vue'
+import { ref, computed, inject } from 'vue'
 import type {
   TopBarPage,
+  TopBarPageInput,
   TopBarTab,
+  TopBarTabInput,
   TopBarTabOption,
+  TopBarTabOptionInput,
   TopBarSettingsConfig,
   TopBarVariant,
   PillNavItem,
+  PillNavItemInput,
   PageSelectorItem,
+  PageSelectorItemInput,
   PluginSwitcherInfo,
   PluginSwitcherPlugin,
   AccountMenuItem,
+  SettingsTab,
 } from '../types/components'
+import type { PluginNavItem } from '../types/platform'
+import { normalizeItemInput } from '../utils/items'
+import { isPluginIconFormat } from '../utils/pluginIcon'
 import ThemeToggle from './ThemeToggle.vue'
 import SettingsModal from './SettingsModal.vue'
 import ExperimentPopover from './ExperimentPopover.vue'
@@ -21,49 +30,75 @@ import AppPageSelector from './AppPageSelector.vue'
 import AppPillNav from './AppPillNav.vue'
 import AppAvatarMenu from './AppAvatarMenu.vue'
 import AppPluginSwitcher from './AppPluginSwitcher.vue'
+import PluginIcon from './PluginIcon.vue'
 import { usePlatformContext } from '../composables/usePlatformContext'
 import { APP_EXPERIMENT_KEY } from '../composables/useAppExperiment'
-
-const SVG_PATH_PREFIX = 'M'
+import { useEventListener } from '../composables/useEventListener'
+import { useDropdownState } from '../composables/useDropdownState'
 
 interface Props {
-  // Classic title & breadcrumb
+  /** App or plugin title shown in the left title group when no page selector is present. */
   title?: string
+  /** Secondary title copy shown under the title in title-group layouts. */
   subtitle?: string
+  /** Show the default MINT logo when the icon/logo slot is not provided. */
   showLogo?: boolean
+  /** Top bar visual treatment. */
   variant?: TopBarVariant
-  pluginName?: string
-  pages?: TopBarPage[]
-  currentPageId?: string
-  tabs?: TopBarTab[]
-  currentTabId?: string
+  /** Home link used by classic breadcrumb layouts. */
   homePath?: string
 
-  // New layout — left page selector / plugin switcher
-  pageSelector?: PageSelectorItem[]
+  /** Preferred route-level page switch entries for plugin and platform pages. */
+  pageSelector?: PageSelectorItemInput[]
+  /** Active id for the preferred page selector. */
   currentPageSelectorId?: string
+  /** Optional plugin switcher shown in the left navigation position instead of pageSelector. */
   pluginSwitcher?: PluginSwitcherInfo
 
-  // New layout — centered pill nav
-  pillNav?: PillNavItem[]
+  /** Preferred centered navigation for local modes inside the current route. */
+  pillNav?: PillNavItemInput[]
+  /** Active id for the preferred centered pill navigation. */
   currentPillId?: string
 
-  // New right cluster — avatar menu + optional notifications
+  /** Account dropdown entries. Takes precedence over the classic profile button. */
   accountMenu?: AccountMenuItem[]
+  /** Show the notifications icon button. */
   showNotifications?: boolean
+  /** Draw a notification dot on the notifications icon. */
   hasNotificationDot?: boolean
 
-  // Classic right cluster (still works; AvatarMenu takes precedence over Profile)
+  /** Compatibility breadcrumb plugin name. Prefer pageSelector for route-level pages. */
+  pluginName?: string
+  /** Compatibility page dropdown items. Prefer pageSelector for new route-level navigation. */
+  pages?: TopBarPageInput[]
+  /** Active id for the compatibility page dropdown. */
+  currentPageId?: string
+  /** Compatibility center tabs. Prefer pillNav for new in-page modes. */
+  tabs?: TopBarTabInput[]
+  /** Active id for compatibility center tabs. */
+  currentTabId?: string
+
+  /** Show the theme toggle button. */
   showThemeToggle?: boolean
+  /** Show the settings button and modal. */
   showSettings?: boolean
+  /** Built-in SettingsModal configuration. */
   settingsConfig?: TopBarSettingsConfig
+  /** Show the standalone badge when the plugin is not integrated into the platform. */
   showStandaloneLabel?: boolean
+  /** Custom standalone badge label. */
   standaloneLabel?: string
+  /** Show the classic admin shortcut. */
   showAdmin?: boolean
+  /** Route used by the classic admin shortcut. */
   adminPath?: string
+  /** Show the classic profile button when accountMenu is not provided. */
   showProfile?: boolean
+  /** Classic profile display name. */
   userName?: string
+  /** Explicit classic profile initial. */
   userInitial?: string
+  /** Classic profile email, used by avatar/account layouts. */
   userEmail?: string
 }
 
@@ -96,6 +131,7 @@ const emit = defineEmits<{
   'account-menu-select': [item: AccountMenuItem]
   'sign-out': []
   'notifications-click': []
+  'settings-values-change': [data: Record<string, unknown>]
 }>()
 
 const settingsOpen = ref(false)
@@ -103,10 +139,7 @@ const { isIntegrated, plugin } = usePlatformContext()
 const isStandalone = computed(() => !isIntegrated.value)
 const appExperiment = inject(APP_EXPERIMENT_KEY, null)
 
-const pluginIcon = computed(() => {
-  const icon = plugin.value?.icon
-  return icon && icon.startsWith(SVG_PATH_PREFIX) ? icon : null
-})
+const hasPluginIcon = computed(() => !!plugin.value?.icon)
 
 const profileInitial = computed(() => {
   if (props.userInitial) return props.userInitial
@@ -114,21 +147,22 @@ const profileInitial = computed(() => {
   return 'U'
 })
 
+const hasPlatformPages = computed(() => props.pages === undefined && !!plugin.value?.nav_items?.length)
+const effectivePluginName = computed(() => props.pluginName ?? (hasPlatformPages.value ? plugin.value?.name : '') ?? '')
 const hasPageSelector = computed(() => !!props.pageSelector?.length)
 const hasPluginSwitcher = computed(() => !!props.pluginSwitcher)
 const hasPillNav = computed(() => !!props.pillNav?.length)
 const hasAccountMenu = computed(() => !!props.accountMenu?.length)
 const hasLegacyBreadcrumb = computed(
-  () => !hasPageSelector.value && !hasPluginSwitcher.value && (!!props.pluginName || !!props.pages?.length),
+  () => !hasPageSelector.value && !hasPluginSwitcher.value && (!!effectivePluginName.value || normalizedPages.value.length > 0),
 )
 const hasTitleGroup = computed(
   () =>
     !hasPageSelector.value &&
     !hasPluginSwitcher.value &&
+    !hasLegacyBreadcrumb.value &&
     !!props.title &&
-    !!props.subtitle &&
-    !props.pluginName &&
-    !props.pages?.length,
+    !!props.subtitle
 )
 const hasTitleOnly = computed(
   () =>
@@ -138,25 +172,104 @@ const hasTitleOnly = computed(
     !hasLegacyBreadcrumb.value &&
     !!props.title,
 )
+const normalizedPages = computed<TopBarPage[]>(() =>
+  props.pages !== undefined
+    ? props.pages.map(normalizeItemInput)
+    : plugin.value?.nav_items?.map(pluginNavItemToPage) ?? [],
+)
+const normalizedTabs = computed<TopBarTab[]>(() => props.tabs?.map(normalizeTopBarTabInput) ?? [])
+const normalizedPageSelector = computed<PageSelectorItem[]>(() => props.pageSelector?.map(normalizeItemInput) ?? [])
+const normalizedPillNav = computed<PillNavItem[]>(() => props.pillNav?.map(normalizeItemInput) ?? [])
+const normalizedSettingsTabs = computed<SettingsTab[]>(() =>
+  props.settingsConfig?.tabs?.map(normalizeItemInput) ?? [],
+)
+const effectiveCurrentPageId = computed(() =>
+  props.currentPageId
+    ?? (hasPlatformPages.value ? currentPageIdFromLocation(normalizedPages.value) : undefined)
+    ?? (hasPlatformPages.value ? normalizedPages.value[0]?.id : undefined),
+)
+const currentLegacyPage = computed(() =>
+  normalizedPages.value.find((page) => page.id === effectiveCurrentPageId.value),
+)
+const effectiveTitle = computed(() =>
+  props.title ?? (hasPlatformPages.value ? currentLegacyPage.value?.label : undefined),
+)
 
-const showPagesDropdown = ref(false)
-const dropdownRef = ref<HTMLElement | null>(null)
+const {
+  isOpen: showPagesDropdown,
+  rootRef: dropdownRef,
+  close: closePagesDropdown,
+  toggle: togglePagesDropdownBase,
+} = useDropdownState()
 const openTabDropdown = ref<string | null>(null)
 const tabDropdownRefs = ref<Map<string, HTMLElement>>(new Map())
 
 function togglePagesDropdown() {
-  showPagesDropdown.value = !showPagesDropdown.value
+  togglePagesDropdownBase()
   openTabDropdown.value = null
 }
 
+function normalizeTopBarTabInput(tab: TopBarTabInput): TopBarTab {
+  const normalized = normalizeItemInput<Omit<TopBarTab, 'children'> & { children?: TopBarTabOptionInput[] }>(tab)
+  return {
+    ...normalized,
+    children: normalized.children?.map(normalizeItemInput),
+  }
+}
+
+function isSvgTabIcon(icon?: string): icon is string {
+  return !!icon && (icon.startsWith('M') || icon.startsWith('m'))
+}
+
+function normalizeNavPath(path?: string): string {
+  const raw = path?.trim() || '/'
+  const prefixed = raw.startsWith('/') ? raw : `/${raw}`
+  return prefixed.replace(/\/+$/, '') || '/'
+}
+
+function pageIdFromPath(path: string, fallback: string): string {
+  const normalized = normalizeNavPath(path)
+  if (normalized === '/') return 'dashboard'
+  return normalized.replace(/^\/+/, '').replace(/\/+/g, '-') || fallback
+}
+
+function pluginNavItemToPage(item: PluginNavItem, index: number): TopBarPage {
+  const path = normalizeNavPath(item.path)
+  return {
+    id: item.id || pageIdFromPath(path, `page-${index + 1}`),
+    label: item.label,
+    to: path,
+    icon: item.icon || plugin.value?.icon,
+    description: item.description,
+  }
+}
+
+function currentPagePath(): string | undefined {
+  if (typeof window === 'undefined') return undefined
+  const pathname = normalizeNavPath(window.location.pathname)
+  const routePrefix = normalizeNavPath(plugin.value?.route_prefix)
+
+  if (pathname === routePrefix) return '/'
+  if (routePrefix !== '/' && pathname.startsWith(`${routePrefix}/`)) {
+    return normalizeNavPath(pathname.slice(routePrefix.length))
+  }
+  return pathname
+}
+
+function currentPageIdFromLocation(pages: TopBarPage[]): string | undefined {
+  const path = currentPagePath()
+  if (!path) return undefined
+  return pages.find((page) => normalizeNavPath(page.to || page.href) === path)?.id
+}
+
 function handlePageClick(page: TopBarPage) {
   if (page.disabled) return
   emit('page-select', page)
-  showPagesDropdown.value = false
+  closePagesDropdown()
 }
 
 function toggleTabDropdown(tabId: string) {
-  showPagesDropdown.value = false
+  closePagesDropdown()
   openTabDropdown.value = openTabDropdown.value === tabId ? null : tabId
 }
 
@@ -187,10 +300,6 @@ function setTabDropdownRef(el: HTMLElement | null, tabId: string) {
 function handleClickOutside(event: MouseEvent) {
   const target = event.target as Node
 
-  if (showPagesDropdown.value && dropdownRef.value && !dropdownRef.value.contains(target)) {
-    showPagesDropdown.value = false
-  }
-
   if (openTabDropdown.value !== null) {
     const clickedInside = Array.from(tabDropdownRefs.value.values()).some((el) => el.contains(target))
     if (!clickedInside) {
@@ -199,13 +308,7 @@ function handleClickOutside(event: MouseEvent) {
   }
 }
 
-onMounted(() => {
-  document.addEventListener('click', handleClickOutside)
-})
-
-onUnmounted(() => {
-  document.removeEventListener('click', handleClickOutside)
-})
+useEventListener(() => document, 'click', handleClickOutside)
 </script>
 
 <template>
@@ -224,13 +327,14 @@ onUnmounted(() => {
           class="mint-topbar-home-link"
         >
           <slot name="icon">
-            <div v-if="pluginIcon" class="mint-topbar__logo">
-              <div class="mint-topbar__logo-icon">
-                <svg class="mint-topbar__logo-svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
-                  <path :d="pluginIcon" />
-                </svg>
-              </div>
-            </div>
+            <PluginIcon
+              v-if="hasPluginIcon"
+              class="mint-topbar__plugin-icon"
+              :icon="plugin!.icon"
+              :tone="plugin!.color"
+              size="md"
+              variant="solid"
+            />
             <slot v-else name="logo">
               <div v-if="showLogo" class="mint-topbar__logo">
                 <div class="mint-topbar__logo-icon">
@@ -246,13 +350,14 @@ onUnmounted(() => {
           class="mint-topbar-home-link"
         >
           <slot name="icon">
-            <div v-if="pluginIcon" class="mint-topbar__logo">
-              <div class="mint-topbar__logo-icon">
-                <svg class="mint-topbar__logo-svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
-                  <path :d="pluginIcon" />
-                </svg>
-              </div>
-            </div>
+            <PluginIcon
+              v-if="hasPluginIcon"
+              class="mint-topbar__plugin-icon"
+              :icon="plugin!.icon"
+              :tone="plugin!.color"
+              size="md"
+              variant="solid"
+            />
             <slot v-else name="logo">
               <div v-if="showLogo" class="mint-topbar__logo">
                 <div class="mint-topbar__logo-icon">
@@ -264,13 +369,14 @@ onUnmounted(() => {
         </router-link>
         <template v-else>
           <slot name="icon">
-            <div v-if="pluginIcon" class="mint-topbar__logo">
-              <div class="mint-topbar__logo-icon">
-                <svg class="mint-topbar__logo-svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
-                  <path :d="pluginIcon" />
-                </svg>
-              </div>
-            </div>
+            <PluginIcon
+              v-if="hasPluginIcon"
+              class="mint-topbar__plugin-icon"
+              :icon="plugin!.icon"
+              :tone="plugin!.color"
+              size="md"
+              variant="solid"
+            />
             <slot v-else name="logo">
               <div v-if="showLogo" class="mint-topbar__logo">
                 <div class="mint-topbar__logo-icon">
@@ -293,8 +399,8 @@ onUnmounted(() => {
         @install-click="emit('plugin-switcher-install')"
       />
       <AppPageSelector
-        v-else-if="hasPageSelector && pageSelector"
-        :pages="pageSelector"
+        v-else-if="hasPageSelector"
+        :pages="normalizedPageSelector"
         :current-page-id="currentPageSelectorId"
         @select="emit('page-selector-select', $event)"
       >
@@ -314,12 +420,12 @@ onUnmounted(() => {
 
       <div v-else-if="hasLegacyBreadcrumb" ref="dropdownRef" class="mint-topbar-breadcrumb">
         <button
-          v-if="pages?.length"
+          v-if="normalizedPages.length"
           type="button"
           class="mint-topbar-plugin-name"
           @click.stop="togglePagesDropdown"
         >
-          {{ pluginName }}
+          {{ effectivePluginName }}
           <svg
             class="mint-topbar-chevron"
             :class="{ 'mint-topbar-chevron--open': showPagesDropdown }"
@@ -335,10 +441,10 @@ onUnmounted(() => {
             <path d="m6 9 6 6 6-6" />
           </svg>
         </button>
-        <span v-else class="mint-topbar-plugin-name--static">{{ pluginName }}</span>
+        <span v-else class="mint-topbar-plugin-name--static">{{ effectivePluginName }}</span>
 
         <svg
-          v-if="title"
+          v-if="effectiveTitle"
           class="mint-topbar-separator"
           width="16"
           height="16"
@@ -351,36 +457,69 @@ onUnmounted(() => {
         >
           <path d="m9 18 6-6-6-6" />
         </svg>
-        <span v-if="title" class="mint-topbar-current-page">{{ title }}</span>
+        <span v-if="effectiveTitle" class="mint-topbar-current-page">{{ effectiveTitle }}</span>
 
         <div v-show="showPagesDropdown" class="mint-topbar-dropdown">
-          <template v-for="page in pages" :key="page.id">
+          <template v-for="page in normalizedPages" :key="page.id">
             <a
               v-if="page.href"
               :href="page.href"
-              :class="['mint-topbar-dropdown-item', { 'mint-topbar-dropdown-item--active': page.id === currentPageId, 'mint-topbar-dropdown-item--disabled': page.disabled }]"
-              @click="showPagesDropdown = false"
+              :class="['mint-topbar-dropdown-item', { 'mint-topbar-dropdown-item--active': page.id === effectiveCurrentPageId, 'mint-topbar-dropdown-item--disabled': page.disabled }]"
+              @click="closePagesDropdown"
             >
-              <span class="mint-topbar-dropdown-item__label">{{ page.label }}</span>
-              <span v-if="page.description" class="mint-topbar-dropdown-item__description">{{ page.description }}</span>
+              <span class="mint-topbar-dropdown-item__page">
+                <PluginIcon
+                  v-if="isPluginIconFormat(page.icon)"
+                  class="mint-topbar-dropdown-item__icon"
+                  :icon="page.icon"
+                  size="sm"
+                  variant="tinted"
+                />
+                <span class="mint-topbar-dropdown-item__copy">
+                  <span class="mint-topbar-dropdown-item__label">{{ page.label }}</span>
+                  <span v-if="page.description" class="mint-topbar-dropdown-item__description">{{ page.description }}</span>
+                </span>
+              </span>
             </a>
             <router-link
               v-else-if="page.to"
               :to="page.to"
-              :class="['mint-topbar-dropdown-item', { 'mint-topbar-dropdown-item--active': page.id === currentPageId, 'mint-topbar-dropdown-item--disabled': page.disabled }]"
-              @click="showPagesDropdown = false"
+              :class="['mint-topbar-dropdown-item', { 'mint-topbar-dropdown-item--active': page.id === effectiveCurrentPageId, 'mint-topbar-dropdown-item--disabled': page.disabled }]"
+              @click="closePagesDropdown"
             >
-              <span class="mint-topbar-dropdown-item__label">{{ page.label }}</span>
-              <span v-if="page.description" class="mint-topbar-dropdown-item__description">{{ page.description }}</span>
+              <span class="mint-topbar-dropdown-item__page">
+                <PluginIcon
+                  v-if="isPluginIconFormat(page.icon)"
+                  class="mint-topbar-dropdown-item__icon"
+                  :icon="page.icon"
+                  size="sm"
+                  variant="tinted"
+                />
+                <span class="mint-topbar-dropdown-item__copy">
+                  <span class="mint-topbar-dropdown-item__label">{{ page.label }}</span>
+                  <span v-if="page.description" class="mint-topbar-dropdown-item__description">{{ page.description }}</span>
+                </span>
+              </span>
             </router-link>
             <button
               v-else
               type="button"
-              :class="['mint-topbar-dropdown-item', { 'mint-topbar-dropdown-item--active': page.id === currentPageId, 'mint-topbar-dropdown-item--disabled': page.disabled }]"
+              :class="['mint-topbar-dropdown-item', { 'mint-topbar-dropdown-item--active': page.id === effectiveCurrentPageId, 'mint-topbar-dropdown-item--disabled': page.disabled }]"
               @click="handlePageClick(page)"
             >
-              <span class="mint-topbar-dropdown-item__label">{{ page.label }}</span>
-              <span v-if="page.description" class="mint-topbar-dropdown-item__description">{{ page.description }}</span>
+              <span class="mint-topbar-dropdown-item__page">
+                <PluginIcon
+                  v-if="isPluginIconFormat(page.icon)"
+                  class="mint-topbar-dropdown-item__icon"
+                  :icon="page.icon"
+                  size="sm"
+                  variant="tinted"
+                />
+                <span class="mint-topbar-dropdown-item__copy">
+                  <span class="mint-topbar-dropdown-item__label">{{ page.label }}</span>
+                  <span v-if="page.description" class="mint-topbar-dropdown-item__description">{{ page.description }}</span>
+                </span>
+              </span>
             </button>
           </template>
         </div>
@@ -396,7 +535,7 @@ onUnmounted(() => {
         <slot name="center">
           <AppPillNav
             v-if="hasPillNav && pillNav"
-            :items="pillNav"
+            :items="normalizedPillNav"
             :current-item-id="currentPillId"
             @select="emit('pill-select', $event)"
           />
@@ -406,9 +545,9 @@ onUnmounted(() => {
       <!-- Center: classic tabs (when no pillNav) — wrapped in the same centered
            container as AppPillNav so classic :tabs consumers get centered pill
            layout without migrating to :pill-nav. -->
-      <div v-if="!hasPillNav && tabs?.length" class="mint-topbar__center">
+      <div v-if="!hasPillNav && normalizedTabs.length" class="mint-topbar__center">
         <div class="mint-topbar__tabs">
-          <template v-for="tab in tabs" :key="tab.id">
+          <template v-for="tab in normalizedTabs" :key="tab.id">
           <div
             :ref="(el) => tab.children?.length ? setTabDropdownRef(el as HTMLElement, tab.id) : null"
             class="mint-topbar-tab-wrapper"
@@ -423,6 +562,19 @@ onUnmounted(() => {
               ]"
               @click.stop="handleTabClick(tab)"
             >
+              <svg
+                v-if="isSvgTabIcon(tab.icon)"
+                class="mint-topbar-tab-icon"
+                viewBox="0 0 24 24"
+                fill="none"
+                stroke="currentColor"
+                stroke-width="2"
+                stroke-linecap="round"
+                stroke-linejoin="round"
+                aria-hidden="true"
+              >
+                <path :d="tab.icon" />
+              </svg>
               {{ tab.label }}
               <svg
                 class="mint-topbar-tab-chevron"
@@ -449,6 +601,19 @@ onUnmounted(() => {
                 { 'mint-topbar-tab--disabled': tab.disabled }
               ]"
             >
+              <svg
+                v-if="isSvgTabIcon(tab.icon)"
+                class="mint-topbar-tab-icon"
+                viewBox="0 0 24 24"
+                fill="none"
+                stroke="currentColor"
+                stroke-width="2"
+                stroke-linecap="round"
+                stroke-linejoin="round"
+                aria-hidden="true"
+              >
+                <path :d="tab.icon" />
+              </svg>
               {{ tab.label }}
             </a>
             <router-link
@@ -460,6 +625,19 @@ onUnmounted(() => {
                 { 'mint-topbar-tab--disabled': tab.disabled }
               ]"
             >
+              <svg
+                v-if="isSvgTabIcon(tab.icon)"
+                class="mint-topbar-tab-icon"
+                viewBox="0 0 24 24"
+                fill="none"
+                stroke="currentColor"
+                stroke-width="2"
+                stroke-linecap="round"
+                stroke-linejoin="round"
+                aria-hidden="true"
+              >
+                <path :d="tab.icon" />
+              </svg>
               {{ tab.label }}
             </router-link>
             <button
@@ -472,6 +650,19 @@ onUnmounted(() => {
               ]"
               @click="handleTabClick(tab)"
             >
+              <svg
+                v-if="isSvgTabIcon(tab.icon)"
+                class="mint-topbar-tab-icon"
+                viewBox="0 0 24 24"
+                fill="none"
+                stroke="currentColor"
+                stroke-width="2"
+                stroke-linecap="round"
+                stroke-linejoin="round"
+                aria-hidden="true"
+              >
+                <path :d="tab.icon" />
+              </svg>
               {{ tab.label }}
             </button>
 
@@ -634,11 +825,19 @@ onUnmounted(() => {
     v-if="showSettings"
     v-model="settingsOpen"
     :title="settingsConfig?.title"
-    :tabs="settingsConfig?.tabs"
+    :tabs="normalizedSettingsTabs"
     :show-appearance="settingsConfig?.showAppearance ?? true"
     :size="settingsConfig?.size"
+    :layout="settingsConfig?.layout"
+    :schema="settingsConfig?.schema"
+    :model="settingsConfig?.model"
+    :controls="settingsConfig?.controls"
+    :control-options="settingsConfig?.controlOptions"
+    :values="settingsConfig?.values"
+    :enhancements="settingsConfig?.enhancements"
+    @update:values="emit('settings-values-change', $event)"
   >
-    <template v-for="tab in (settingsConfig?.tabs ?? [])" :key="tab.id" #[`tab-${tab.id}`]>
+    <template v-for="tab in normalizedSettingsTabs" :key="tab.id" #[`tab-${tab.id}`]>
       <slot :name="`settings-tab-${tab.id}`" />
     </template>
     <template #appearance>

package/src/components/BaseModal.vue

@@ -1,7 +1,8 @@
 <script setup lang="ts">
 /** Modal dialog with backdrop, focus trap, Escape-to-close, and configurable size/variant. */
-import { ref, watch, nextTick, onMounted, onUnmounted } from 'vue'
+import { ref, watch, nextTick, onUnmounted } from 'vue'
 import type { ModalSize, ModalVariant } from '../types'
+import { useEventListener } from '../composables/useEventListener'
 
 interface Props {
   modelValue: boolean
@@ -101,12 +102,9 @@ watch(() => props.modelValue, async (isOpen) => {
   }
 })
 
-onMounted(() => {
-  document.addEventListener('keydown', handleKeydown)
-})
+useEventListener(() => document, 'keydown', handleKeydown)
 
 onUnmounted(() => {
-  document.removeEventListener('keydown', handleKeydown)
   document.body.style.overflow = ''
 })
 </script>

package/src/components/BaseRadioGroup.vue

@@ -1,10 +1,12 @@
 <script setup lang="ts">
 /** Renders a group of radio buttons in list or tile layout, horizontal or vertical. */
-import type { RadioOption } from '../types'
+import { computed } from 'vue'
+import type { RadioOption, RadioOptionInput } from '../types'
+import { normalizeOptionInput } from '../utils/options'
 
 interface Props {
   modelValue?: string | number
-  options: RadioOption[]
+  options: RadioOptionInput[]
   name: string
   disabled?: boolean
   direction?: 'horizontal' | 'vertical'
@@ -23,6 +25,8 @@ const emit = defineEmits<{
   'update:modelValue': [value: string | number]
 }>()
 
+const normalizedOptions = computed<RadioOption[]>(() => props.options.map(normalizeOptionInput))
+
 function handleChange(value: string | number) {
   emit('update:modelValue', value)
 }
@@ -34,7 +38,7 @@ function handleChange(value: string | number) {
     role="radiogroup"
   >
     <label
-      v-for="option in props.options"
+      v-for="option in normalizedOptions"
       :key="String(option.value)"
       :class="[
         'mint-radio-option',