@morscherlab/mint-sdk 1.2.0-beta.4 → 1.2.0-beta.5

package/src/composables/formBuilderRegistry.ts

@@ -2,6 +2,7 @@ import type { Component } from 'vue'
 import type { FormFieldType } from '../types/form-builder'
 
 import BaseInput from '../components/BaseInput.vue'
+import SecretInput from '../components/SecretInput.vue'
 import BaseTextarea from '../components/BaseTextarea.vue'
 import BaseSelect from '../components/BaseSelect.vue'
 import MultiSelect from '../components/MultiSelect.vue'
@@ -34,6 +35,7 @@ const registry: Record<FormFieldType, RegistryEntry> = {
   text: { component: BaseInput, defaults: { type: 'text' }, vModel: true },
   email: { component: BaseInput, defaults: { type: 'email' }, vModel: true },
   password: { component: BaseInput, defaults: { type: 'password' }, vModel: true },
+  secret: { component: SecretInput, defaults: {}, vModel: true },
   tel: { component: BaseInput, defaults: { type: 'tel' }, vModel: true },
   url: { component: BaseInput, defaults: { type: 'url' }, vModel: true },
   search: { component: BaseInput, defaults: { type: 'search' }, vModel: true },
@@ -75,6 +77,9 @@ export function getTypeDefault(type: FormFieldType): unknown {
     case 'multiselect':
     case 'tags':
       return []
+    case 'secret':
+      // A secret field has no empty string state: `null` means "not stored".
+      return null
     default:
       return ''
   }

package/src/composables/index.ts

@@ -528,3 +528,29 @@ export {
   type UsePluginJobCenterOptions,
   type UsePluginJobCenterReturn,
 } from './useJobsStatusTray'
+export {
+  usePluginWorkspace,
+  type PluginWorkspaceSlotsLike,
+  type UsePluginWorkspaceOptions,
+  type UsePluginWorkspaceReturn,
+} from './usePluginWorkspace'
+export {
+  type PluginWorkspaceControlsModel,
+  type PluginWorkspaceShellModel,
+  type PluginWorkspaceSidebarModel,
+} from './pluginWorkspaceModel'
+export {
+  useFocusTrap,
+  type UseFocusTrapOptions,
+  type UseFocusTrapReturn,
+} from './useFocusTrap'
+export {
+  useRovingFocus,
+  type UseRovingFocusOptions,
+  type UseRovingFocusReturn,
+} from './useRovingFocus'
+export {
+  useMenuKeyboard,
+  type UseMenuKeyboardOptions,
+  type UseMenuKeyboardReturn,
+} from './useMenuKeyboard'

package/src/composables/pluginWorkspaceModel.ts

@@ -0,0 +1,182 @@
+import type {
+  AccountMenuItem,
+  PageSelectorItemInput,
+  PillNavItemInput,
+  PluginSwitcherInfo,
+  SidebarToolSection,
+  TopBarSettingsConfig,
+  TopBarVariant,
+} from '../types'
+import type { FormEnhancements, FormSchema } from '../types/form-builder'
+import type {
+  ControlComponentBinding,
+  ControlComponentBindingsById,
+  ControlModel,
+  ControlModelBinding,
+  ControlSchema,
+  ControlWorkspaceOptions,
+} from './useControlSchema'
+import type { PluginWorkspaceSidebarVariant } from '../components/PluginWorkspaceView.props'
+
+/**
+ * Scoped-slot payload shared by PluginWorkspaceView's `default`, `topbar`, and `sidebar`
+ * slots: the resolved active view plus the values and component bindings/props derived
+ * from the compact control schema. WorkspaceControlsInternal renders a component's default
+ * slot bound to exactly this shape.
+ */
+export interface PluginWorkspaceControlsModel {
+  /** Currently resolved workspace view id. */
+  activeView: string
+  /** Sets the active view, updating any uncontrolled state and emitting `update:activeView`. */
+  setActiveView: (viewId: string) => void
+  /** Current control values, shared between the auto-rendered sidebar form and the default slot. */
+  values: Record<string, unknown>
+  /** Ordered SDK component bindings resolved from the current control values. */
+  componentBindings: ControlComponentBinding[]
+  /** SDK component bindings resolved from the current control values, keyed by binding id. */
+  componentBindingsById: ControlComponentBindingsById
+  /** Flat component props resolved from the current control values. */
+  componentProps: Record<string, unknown>
+  /** Named component prop mappings resolved from the current control values. */
+  componentPropsById: Record<string, Record<string, unknown>>
+}
+
+/**
+ * Resolved AppLayout + AppTopBar configuration consumed by WorkspaceShellInternal: top bar
+ * chrome and navigation, plus the AppLayout layout/collapse props that own the responsive
+ * mobile sidebar toggle.
+ */
+export interface PluginWorkspaceShellModel {
+  /** AppLayout sidebar position. */
+  sidebarPosition: 'left' | 'right'
+  /** AppLayout sidebar width, forwarded so the layout can reserve space before AppSidebar mounts. */
+  sidebarWidth?: string
+  /** AppLayout floating style. */
+  floating: boolean
+  /** Convert the sidebar into an SDK-owned mobile overlay below the AppLayout breakpoint. */
+  responsiveSidebar: boolean
+  /** Accessible label for the mobile sidebar toggle. */
+  sidebarToggleLabel: string
+  /** Accessible label used when the mobile sidebar is open. */
+  sidebarCloseLabel: string
+  /** Whether AppLayout should render a `#sidebar` template at all. */
+  hasSidebarSurface: boolean
+  /** App or plugin title shown in the top bar. */
+  title: string
+  /** Secondary copy shown under the title. */
+  subtitle?: string
+  /** Top bar visual treatment. */
+  topBarVariant: TopBarVariant
+  /** Home link used by the top bar brand icon. */
+  homePath: string
+  /** Show the default MINT logo when no icon/logo slot is provided. */
+  showLogo: boolean
+  /** Preferred route-level page selector entries. */
+  pageSelector?: PageSelectorItemInput[]
+  /** Resolved active page selector id. */
+  currentPageSelectorId: string
+  /** Optional plugin switcher shown in the left navigation position. */
+  pluginSwitcher?: PluginSwitcherInfo
+  /** Resolved centered pill navigation, generated from the control schema when omitted. */
+  pillNav?: PillNavItemInput[]
+  /** Resolved active centered pill id. */
+  currentPillId: string
+  /** Show the theme toggle button. */
+  showThemeToggle: boolean
+  /** Show the settings button and modal. */
+  showSettings: boolean
+  /** Built-in settings modal configuration. */
+  settingsConfig?: TopBarSettingsConfig
+  /** Show the standalone badge when not integrated into the platform. */
+  showStandaloneLabel: boolean
+  /** Custom standalone badge label. */
+  standaloneLabel: string
+  /** Account dropdown entries. */
+  accountMenu?: AccountMenuItem[]
+  /** Show the notifications icon button. */
+  showNotifications: boolean
+  /** Draw a notification dot on the notifications icon. */
+  hasNotificationDot: boolean
+  /** Show the admin shortcut. */
+  showAdmin: boolean
+  /** Route used by the admin shortcut. */
+  adminPath: string
+  /** Account display name. */
+  userName?: string
+  /** Explicit account avatar initial. */
+  userInitial?: string
+  /** Account email shown in the avatar menu. */
+  userEmail?: string
+  /** Names of AppTopBar passthrough slots the caller actually provided. */
+  topBarSlotNames: string[]
+  /** Scoped-slot payload exposed to the `topbar` override slot. */
+  controls: PluginWorkspaceControlsModel
+}
+
+/**
+ * Resolved AppSidebar configuration consumed by WorkspaceSidebarInternal: sidebar chrome,
+ * panels/forms, collapse behavior, and the compact control-schema props that drive
+ * AppSidebar's auto-generated form.
+ */
+export interface PluginWorkspaceSidebarModel {
+  /** Sidebar chrome title. */
+  title?: string
+  /** Sidebar chrome subtitle. */
+  subtitle?: string
+  /** Optional compact badge/count rendered in the sidebar header. */
+  badge?: string | number
+  /** AppSidebar visual preset. */
+  variant: PluginWorkspaceSidebarVariant
+  /** Map of view IDs to sidebar tool sections. */
+  panels: Record<string, SidebarToolSection[]>
+  /** Resolved active view, used to pick which panels/forms render. */
+  activeView: string
+  /** AppSidebar floating style (always false: PluginWorkspaceView docks the sidebar inside AppLayout). */
+  floating: boolean
+  /** Compact AppSidebar density. */
+  dense: boolean
+  /** Sidebar CSS width. */
+  width?: string
+  /** Sidebar position, mirrors the shell's `sidebarPosition`. */
+  side: 'left' | 'right'
+  /** Optional FormBuilder schemas keyed by section ID. */
+  forms: Record<string, FormSchema>
+  /** DOM id for the AppSidebar scrollable content area. */
+  contentId?: string
+  /** Render the sidebar shell even when no panel matches the active view. */
+  showWhenEmpty: boolean
+  /** Optional compact control model for the generated sidebar form. */
+  model?: ControlModel | ControlModelBinding
+  /** Compact control schema for the generated sidebar form. */
+  controlSchema?: ControlSchema
+  /** Options passed to compact control schema generation. */
+  controlOptions: ControlWorkspaceOptions
+  /** Shared values for the auto-rendered sidebar form. */
+  values: Record<string, unknown>
+  /** Runtime FormBuilder enhancements for the auto-rendered sidebar form. */
+  formEnhancements?: FormEnhancements<Record<string, unknown>>
+  /** Show submit/cancel actions inside the auto-rendered sidebar form. */
+  showFormActions: boolean
+  /** Loading/saving state for the auto-rendered sidebar form. */
+  formLoading: boolean
+  /** Disabled state for the auto-rendered sidebar form. */
+  formDisabled: boolean
+  /** Readonly state for the auto-rendered sidebar form. */
+  formReadonly: boolean
+  /** Size passed to the auto-rendered sidebar form. */
+  formSize: 'sm' | 'md' | 'lg'
+  /** Show a built-in collapse/expand button in the sidebar chrome. */
+  collapsible?: boolean
+  /** Controlled sidebar collapsed state. */
+  collapsed?: boolean
+  /** Initial sidebar collapsed state when uncontrolled. */
+  defaultCollapsed: boolean
+  /** Sidebar width when collapsed. */
+  collapsedWidth: string
+  /** Accessible label for the sidebar collapse action. */
+  collapseButtonLabel: string
+  /** Accessible label for the sidebar expand action. */
+  expandButtonLabel: string
+  /** Names of AppSidebar passthrough slots the caller actually provided. */
+  slotNames: string[]
+}

package/src/composables/useAsync.ts

@@ -165,7 +165,11 @@ function defaultTransformError(error: unknown): AsyncError {
  * const handleSubmit = () => submit(new FormData(formRef.value))
  * ```
  */
-/** Wraps an async function with reactive loading, error, and success state plus optional auto-execute. */
+/**
+ * Wraps an async function with reactive loading, error, and success state plus optional auto-execute.
+ *
+ * @deprecated Unused by the MINT platform and scheduled for removal in MINT 1.3; use `useRequestSyncState()` instead.
+ */
 export function useAsync<T>(
   asyncFn: (...args: unknown[]) => Promise<T>,
   options: UseAsyncOptions<T> = {}

package/src/composables/useBioTemplatePackWorkspace.ts

@@ -27,6 +27,9 @@ import {
   type BioTemplateWorkspaceBindings,
   type UseBioTemplateWorkspaceReturn,
 } from './useBioTemplateWorkspace'
+import {
+  liftWorkspaceComponentBindings,
+} from './flattenWorkspaceBindings'
 import type {
   BioTemplateComponentBinding,
   BioTemplateComponentBindingsById,
@@ -120,14 +123,17 @@ export function useBioTemplatePackWorkspace(
   const pillNav = computed(() => workspace.value.pillNav)
   const topBarSettings = computed(() => workspace.value.topBarSettings)
   const bindings = computed(() => workspace.value.bindings)
-  const componentBindings = computed(() => workspace.value.componentBindings)
-  const componentBindingsById = computed(() => workspace.value.componentBindingsById)
-  const componentImports = computed(() => workspace.value.componentImports)
-  const componentProps = computed(() => workspace.value.componentProps)
-  const componentPropsById = computed(() => workspace.value.componentPropsById)
-  const componentPropsByComponent = computed(() => workspace.value.componentPropsByComponent)
-  const componentSnippets = computed(() => workspace.value.componentSnippets)
-  const componentUsage = computed(() => workspace.value.componentUsage)
+  const {
+    componentBindings,
+    componentBindingsById,
+    componentImports,
+    componentProps,
+    componentPropsById,
+    componentPropsByComponent,
+    componentSnippets,
+    componentUsage,
+    getComponentProps: getWorkspaceComponentProps,
+  } = liftWorkspaceComponentBindings(workspace)
 
   watch(collection, value => {
     workspaceRef.value = createWorkspace(value)
@@ -181,7 +187,7 @@ export function useBioTemplatePackWorkspace(
     componentPropsByComponent,
     componentSnippets,
     componentUsage,
-    getComponentProps: (component, options) => workspace.value.getComponentProps(component, options),
+    getComponentProps: getWorkspaceComponentProps,
     applyCollection,
     resetToDefaultCollection,
     save: templateCollection.save,

package/src/composables/useBioTemplatePresetWorkspace.ts

@@ -34,6 +34,9 @@ import {
   type BioTemplateRendererBinding,
   type UseBioTemplateWorkspaceReturn,
 } from './useBioTemplateWorkspace'
+import {
+  liftWorkspaceComponentBindings,
+} from './flattenWorkspaceBindings'
 import type {
   BioTemplateComponentBinding,
   BioTemplateComponentBindingsById,
@@ -138,14 +141,17 @@ export function useBioTemplatePresetWorkspace(
   const collection = templateCollection.templateCollection
   const workspace = computed(() => useBioTemplateWorkspace(collection.value, resolvedControlOptions))
   const renderer = computed<BioTemplateRendererBinding>(() => ({ target: collection.value }))
-  const componentBindings = computed(() => workspace.value.componentBindings)
-  const componentBindingsById = computed(() => workspace.value.componentBindingsById)
-  const componentImports = computed(() => workspace.value.componentImports)
-  const componentProps = computed(() => workspace.value.componentProps)
-  const componentPropsById = computed(() => workspace.value.componentPropsById)
-  const componentPropsByComponent = computed(() => workspace.value.componentPropsByComponent)
-  const componentSnippets = computed(() => workspace.value.componentSnippets)
-  const componentUsage = computed(() => workspace.value.componentUsage)
+  const {
+    componentBindings,
+    componentBindingsById,
+    componentImports,
+    componentProps,
+    componentPropsById,
+    componentPropsByComponent,
+    componentSnippets,
+    componentUsage,
+    getComponentProps,
+  } = liftWorkspaceComponentBindings(workspace)
   const form = reactive({
     ...controls.form,
     modelValue: controlValues.value,
@@ -179,13 +185,6 @@ export function useBioTemplatePresetWorkspace(
     ...topBarSettings,
   }))
 
-  function getComponentProps(
-    component: string,
-    options?: Parameters<UseBioTemplateWorkspaceReturn['getComponentProps']>[1],
-  ) {
-    return workspace.value.getComponentProps(component, options)
-  }
-
   const bindings: BioTemplatePresetWorkspaceBindings = {
     renderer,
     form,

package/src/composables/useBioTemplateWorkspace.ts

@@ -21,16 +21,12 @@ import {
 } from './useBioTemplateControls'
 import {
   useBioTemplateComponents,
-  type BioTemplateComponentBinding,
-  type BioTemplateComponentBindingsById,
-  type BioTemplateComponentImport,
-  type BioTemplateComponentPropsByComponent,
-  type BioTemplateComponentPropsBinding,
-  type BioTemplateComponentPropsById,
-  type BioTemplateComponentSnippet,
-  type BioTemplateComponentUsage,
   type UseBioTemplateComponentsReturn,
 } from './useBioTemplateComponents'
+import {
+  flattenWorkspaceComponentBindings,
+  type BioTemplateWorkspaceComponentBindings,
+} from './flattenWorkspaceBindings'
 
 export type BioTemplateWorkspaceTarget = BioTemplateControlTarget
 
@@ -38,24 +34,16 @@ export interface BioTemplateRendererBinding {
   target: BioTemplateEnvelope<unknown> | TemplateCollectionEnvelope
 }
 
-export interface BioTemplateWorkspaceBindings {
+export interface BioTemplateWorkspaceBindings extends BioTemplateWorkspaceComponentBindings {
   renderer: BioTemplateRendererBinding | null
   form: ControlWorkspaceFormBinding
   sidebar: ControlWorkspaceSidebarBinding
   topBar: UseControlWorkspaceReturn<BioTemplateControlSchema>['bindings']['topBar']
   topBarSettings: ControlWorkspaceTopBarSettingsBinding
   pillNav: ControlWorkspacePillNavBinding
-  componentBindings: BioTemplateComponentBinding[]
-  componentBindingsById: BioTemplateComponentBindingsById
-  componentProps: BioTemplateComponentPropsBinding[]
-  componentPropsById: BioTemplateComponentPropsById
-  componentPropsByComponent: BioTemplateComponentPropsByComponent
-  componentSnippets: BioTemplateComponentSnippet[]
-  componentUsage: BioTemplateComponentUsage | null
-  getComponentProps: UseBioTemplateComponentsReturn['getComponentProps']
 }
 
-export interface UseBioTemplateWorkspaceReturn {
+export interface UseBioTemplateWorkspaceReturn extends BioTemplateWorkspaceComponentBindings {
   target: BioTemplateWorkspaceTarget
   controls: UseControlSchemaReturn<BioTemplateControlSchema>
   workspace: UseControlWorkspaceReturn<BioTemplateControlSchema>
@@ -70,15 +58,6 @@ export interface UseBioTemplateWorkspaceReturn {
   topBarSettings: ControlWorkspaceTopBarSettingsBinding
   bindings: BioTemplateWorkspaceBindings
   renderer: BioTemplateRendererBinding | null
-  componentBindings: BioTemplateComponentBinding[]
-  componentBindingsById: BioTemplateComponentBindingsById
-  componentImports: BioTemplateComponentImport[]
-  componentProps: BioTemplateComponentPropsBinding[]
-  componentPropsById: BioTemplateComponentPropsById
-  componentPropsByComponent: BioTemplateComponentPropsByComponent
-  componentSnippets: BioTemplateComponentSnippet[]
-  componentUsage: BioTemplateComponentUsage | null
-  getComponentProps: UseBioTemplateComponentsReturn['getComponentProps']
 }
 
 /** One-stop wiring for BioTemplateRenderer, FormBuilder, AppSidebar, and template-aware SDK components. */
@@ -90,21 +69,25 @@ export function useBioTemplateWorkspace(
   const workspace = useControlWorkspace(controls.controls, options)
   const components = useBioTemplateComponents(target)
   const renderer = isTemplateObjectTarget(target) ? { target } : null
-  const bindings: BioTemplateWorkspaceBindings = {
-    renderer,
-    form: workspace.bindings.form,
-    sidebar: workspace.bindings.sidebar,
-    topBar: workspace.bindings.topBar,
-    topBarSettings: workspace.bindings.topBarSettings,
-    pillNav: workspace.bindings.pillNav,
+  const componentBindings = flattenWorkspaceComponentBindings({
     componentBindings: components.bindings,
     componentBindingsById: components.componentBindingsById,
+    componentImports: components.imports,
     componentProps: components.componentProps,
     componentPropsById: components.componentPropsById,
     componentPropsByComponent: components.componentPropsByComponent,
     componentSnippets: components.snippets,
     componentUsage: components.usage,
     getComponentProps: components.getComponentProps,
+  })
+  const bindings: BioTemplateWorkspaceBindings = {
+    renderer,
+    form: workspace.bindings.form,
+    sidebar: workspace.bindings.sidebar,
+    topBar: workspace.bindings.topBar,
+    topBarSettings: workspace.bindings.topBarSettings,
+    pillNav: workspace.bindings.pillNav,
+    ...componentBindings,
   }
 
   return {
@@ -122,15 +105,7 @@ export function useBioTemplateWorkspace(
     topBarSettings: workspace.topBarSettings,
     bindings,
     renderer,
-    componentBindings: components.bindings,
-    componentBindingsById: components.componentBindingsById,
-    componentImports: components.imports,
-    componentProps: components.componentProps,
-    componentPropsById: components.componentPropsById,
-    componentPropsByComponent: components.componentPropsByComponent,
-    componentSnippets: components.snippets,
-    componentUsage: components.usage,
-    getComponentProps: components.getComponentProps,
+    ...componentBindings,
   }
 }
 

package/src/composables/useCommandHistory.ts

@@ -31,7 +31,11 @@ export interface UseCommandHistoryReturn<TCommand extends CommandHistoryCommand
   clear: () => void
 }
 
-/** Generic command-stack state for plugin editors with undo/redo controls. */
+/**
+ * Generic command-stack state for plugin editors with undo/redo controls.
+ *
+ * @deprecated Unused by the MINT platform and scheduled for removal in MINT 1.3; keep command stacks plugin-local.
+ */
 export function useCommandHistory<TCommand extends CommandHistoryCommand = CommandHistoryCommand>(
   options: UseCommandHistoryOptions = {},
 ): UseCommandHistoryReturn<TCommand> {

package/src/composables/useFocusTrap.ts

@@ -0,0 +1,91 @@
+import { nextTick, watch, type Ref } from 'vue'
+import { useEventListener } from './useEventListener'
+
+export interface UseFocusTrapOptions {
+  /** Ref to the trap's container element. Focusable elements are queried within it. */
+  containerRef: Ref<HTMLElement | null>
+  /** Reactive flag — the trap activates when this becomes `true` and releases when it becomes `false`. */
+  active: Ref<boolean>
+  /** Restore focus to the element that was focused before activation, when the trap releases. Default `true`. */
+  restoreFocus?: boolean
+}
+
+export interface UseFocusTrapReturn {
+  /** Focusable descendants of the container, in DOM order, excluding roving-tabindex (`tabindex="-1"`) elements. */
+  getFocusableElements: () => HTMLElement[]
+}
+
+const FOCUSABLE_SELECTOR = [
+  'a[href]',
+  'button:not([disabled])',
+  'input:not([disabled])',
+  'select:not([disabled])',
+  'textarea:not([disabled])',
+  '[tabindex]:not([tabindex="-1"])',
+].join(', ')
+
+/**
+ * Traps Tab focus within a container while `active` is true: Tab wraps from the last
+ * focusable element back to the first (and Shift+Tab from the first to the last), the
+ * first focusable element (or the container itself, if none) receives focus when the
+ * trap activates, and focus returns to whatever was focused beforehand when it releases.
+ * Used by BaseModal and WellEditPopupInternal.
+ */
+export function useFocusTrap(options: UseFocusTrapOptions): UseFocusTrapReturn {
+  const { containerRef, active } = options
+  const restoreFocus = options.restoreFocus ?? true
+  let previouslyFocused: HTMLElement | null = null
+
+  function getFocusableElements(): HTMLElement[] {
+    if (!containerRef.value) return []
+    // Roving tabindex (inactive tabs/rail items) stays out of the Tab cycle. Checking
+    // the attribute directly (rather than the `.tabIndex` IDL property) avoids relying
+    // on a browser/engine's default-tabindex computation for freshly-patched elements.
+    return Array.from(containerRef.value.querySelectorAll<HTMLElement>(FOCUSABLE_SELECTOR))
+      .filter((el) => el.getAttribute('tabindex') !== '-1')
+  }
+
+  function handleKeydown(event: KeyboardEvent) {
+    if (event.key !== 'Tab' || !active.value || !containerRef.value) return
+
+    const focusable = getFocusableElements()
+    if (focusable.length === 0) {
+      event.preventDefault()
+      return
+    }
+
+    const first = focusable[0]
+    const last = focusable[focusable.length - 1]
+
+    if (event.shiftKey && document.activeElement === first) {
+      event.preventDefault()
+      last.focus()
+    } else if (!event.shiftKey && document.activeElement === last) {
+      event.preventDefault()
+      first.focus()
+    }
+  }
+
+  // `flush: 'sync'` so releasing the trap from `onBeforeUnmount` restores focus
+  // before the component's reactive scope is torn down — a batched (default
+  // 'pre') watcher would be scheduled but never flushed once that scope stops.
+  watch(active, async (isActive) => {
+    if (isActive) {
+      previouslyFocused = document.activeElement as HTMLElement | null
+      await nextTick()
+      const focusable = getFocusableElements()
+      if (focusable.length > 0) {
+        focusable[0].focus()
+      } else {
+        containerRef.value?.focus()
+      }
+    } else {
+      if (restoreFocus) previouslyFocused?.focus()
+      previouslyFocused = null
+    }
+  }, { flush: 'sync' })
+
+  useEventListener(() => document, 'keydown', handleKeydown)
+
+  return { getFocusableElements }
+}

package/src/composables/useMenuKeyboard.ts

@@ -0,0 +1,90 @@
+import { nextTick } from 'vue'
+
+export interface UseMenuKeyboardOptions {
+  /** Returns the currently navigable items inside the open panel, in DOM order. */
+  items: () => HTMLElement[]
+  /** True while the panel is open. */
+  isOpen: () => boolean
+  /** Opens the panel. */
+  open: () => void
+  /** Closes the panel. When `returnFocus` is true, focus should return to the trigger. */
+  close: (returnFocus?: boolean) => void
+}
+
+export interface UseMenuKeyboardReturn {
+  /**
+   * Bind to the trigger's `@keydown`. ArrowDown/Enter/Space open the panel (when
+   * closed) and focus its first item; ArrowUp opens it focused on the last item.
+   */
+  handleTriggerKeydown: (event: KeyboardEvent) => void
+  /**
+   * Bind to the open panel's `@keydown`. ArrowUp/ArrowDown cycle focus with
+   * wraparound, Home/End jump to the first/last item, Escape closes and returns
+   * focus to the trigger, and Tab closes without moving focus.
+   */
+  handlePanelKeydown: (event: KeyboardEvent) => void
+}
+
+/**
+ * Shared keyboard contract for menu- and listbox-style disclosure panels (the
+ * WAI-ARIA menu button pattern). Used by AppAvatarMenu and DropdownButton; ActionMenu
+ * implements the same contract inline.
+ */
+export function useMenuKeyboard(options: UseMenuKeyboardOptions): UseMenuKeyboardReturn {
+  function focusItem(position: 'first' | 'last') {
+    void nextTick(() => {
+      const items = options.items()
+      const target = position === 'first' ? items[0] : items[items.length - 1]
+      target?.focus()
+    })
+  }
+
+  function handleTriggerKeydown(event: KeyboardEvent) {
+    if (options.isOpen()) return
+
+    if (event.key === 'ArrowDown' || event.key === 'Enter' || event.key === ' ') {
+      event.preventDefault()
+      options.open()
+      focusItem('first')
+      return
+    }
+    if (event.key === 'ArrowUp') {
+      event.preventDefault()
+      options.open()
+      focusItem('last')
+    }
+  }
+
+  function handlePanelKeydown(event: KeyboardEvent) {
+    const items = options.items()
+    const currentIndex = items.indexOf(document.activeElement as HTMLElement)
+
+    if (event.key === 'Escape') {
+      event.preventDefault()
+      options.close(true)
+      return
+    }
+    if (event.key === 'Tab') {
+      options.close()
+      return
+    }
+    if (event.key === 'Home') {
+      event.preventDefault()
+      items[0]?.focus()
+      return
+    }
+    if (event.key === 'End') {
+      event.preventDefault()
+      items[items.length - 1]?.focus()
+      return
+    }
+    if (event.key !== 'ArrowDown' && event.key !== 'ArrowUp') return
+
+    event.preventDefault()
+    const direction = event.key === 'ArrowDown' ? 1 : -1
+    const nextIndex = (Math.max(currentIndex, 0) + direction + items.length) % items.length
+    items[nextIndex]?.focus()
+  }
+
+  return { handleTriggerKeydown, handlePanelKeydown }
+}

package/src/composables/useOptimisticMutation.ts

@@ -32,7 +32,11 @@ export interface UseOptimisticMutationReturn<TVariables, TData, TSnapshot = unkn
   reset: () => void
 }
 
-/** Run async mutations with optional optimistic local updates and rollback. */
+/**
+ * Run async mutations with optional optimistic local updates and rollback.
+ *
+ * @deprecated Unused by the MINT platform and scheduled for removal in MINT 1.3; use `useRequestSyncState()` instead.
+ */
 export function useOptimisticMutation<TVariables, TData, TSnapshot = unknown>(
   options: UseOptimisticMutationOptions<TVariables, TData, TSnapshot>,
 ): UseOptimisticMutationReturn<TVariables, TData, TSnapshot> {