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

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> {

package/src/composables/usePluginClient.ts

@@ -15,6 +15,7 @@ import {
 import { usePlatformContext } from './usePlatformContext'
 import { useRequestSyncState } from './useRequestSyncState'
 import { useAuthStore } from '../stores/auth'
+import { PLUGIN_SECRET_FORMAT_KEY } from '../utils/pluginSecrets'
 import {
   currentExperimentFromContext,
   getInjectedPlatformContext,
@@ -545,6 +546,26 @@ export function usePluginClient<TClient>(client: TClient): TClient {
 
 const PLATFORM_OWNED_SETTINGS_KEY = 'allowed_experiment_types'
 
+/**
+ * Secret settings travel as `{ "$secret": "<id>" }` references, so an untouched
+ * secret round-trips without ever exposing its value. Declaring the format on
+ * every write keeps a `null` unambiguous: it clears the stored secret instead of
+ * meaning "unchanged", which is what the deprecated placeholder form meant.
+ */
+function withSecretFormat(
+  payload: Record<string, unknown>,
+  secretFormat: string | null,
+): Record<string, unknown> {
+  if (!secretFormat) return payload
+  return { ...payload, [PLUGIN_SECRET_FORMAT_KEY]: secretFormat }
+}
+
+function responseSecretFormat(response: unknown): string | null {
+  if (!response || typeof response !== 'object') return null
+  const format = (response as Record<string, unknown>)[PLUGIN_SECRET_FORMAT_KEY]
+  return typeof format === 'string' && format ? format : null
+}
+
 function cloneRecord(value: Record<string, unknown>): Record<string, unknown> {
   return JSON.parse(JSON.stringify(value)) as Record<string, unknown>
 }
@@ -618,6 +639,7 @@ export function usePluginSettings<TSettings = Record<string, unknown>>(
   const values = ref({}) as Ref<PluginSettingsValues<TSettings>>
   const savedValues = shallowRef<Record<string, unknown>>({})
   const revision = ref<string | null>(null)
+  const secretFormat = ref<string | null>(null)
   const request = useRequestSyncState('Plugin settings request failed.')
   const isLoading = ref(false)
   const isSaving = ref(false)
@@ -650,11 +672,16 @@ export function usePluginSettings<TSettings = Record<string, unknown>>(
     values.value = cloneRecord(nextValues) as PluginSettingsValues<TSettings>
   }
 
-  function applyLoaded(nextValues: Record<string, unknown>, nextRevision: string | null): void {
+  function applyLoaded(
+    nextValues: Record<string, unknown>,
+    nextRevision: string | null,
+    nextSecretFormat: string | null = secretFormat.value,
+  ): void {
     const cloned = cloneRecord(nextValues)
     values.value = cloned as PluginSettingsValues<TSettings>
     savedValues.value = cloneRecord(cloned)
     revision.value = nextRevision
+    secretFormat.value = nextSecretFormat
   }
 
   async function load(): Promise<void> {
@@ -674,6 +701,7 @@ export function usePluginSettings<TSettings = Record<string, unknown>>(
       applyLoaded(
         responseSettingsPayload(response),
         responseSettingsRevision(response),
+        responseSecretFormat(response),
       )
     } catch {
       // Error state is handled by request.run().
@@ -707,7 +735,12 @@ export function usePluginSettings<TSettings = Record<string, unknown>>(
               revision?: string
             }>(
               `/plugins/${encodeURIComponent(resolvedPluginName.value)}/config`,
-              { config: topLevelSettingsPatch(payload, typedKeys) },
+              {
+                config: withSecretFormat(
+                  topLevelSettingsPatch(payload, typedKeys),
+                  secretFormat.value,
+                ),
+              },
             ),
             { success: 'save', errorMessage: 'Failed to save plugin settings' },
           )
@@ -730,7 +763,11 @@ export function usePluginSettings<TSettings = Record<string, unknown>>(
         }
 
         if (!response) return true
-        applyLoaded(responseSettingsPayload(response), nextRevision)
+        applyLoaded(
+          responseSettingsPayload(response),
+          nextRevision,
+          responseSecretFormat(response) ?? secretFormat.value,
+        )
         return true
       } else {
         const ifMatch = revision.value
@@ -741,13 +778,14 @@ export function usePluginSettings<TSettings = Record<string, unknown>>(
             settings: Record<string, unknown>
             mode?: string
             revision?: string
-          }>('/settings', payload, ifMatch),
+          }>('/settings', withSecretFormat(payload, secretFormat.value), ifMatch),
           { success: 'save', errorMessage: 'Failed to save plugin settings' },
         )
       }
       applyLoaded(
         responseSettingsPayload(response),
         responseSettingsRevision(response) ?? revision.value,
+        responseSecretFormat(response) ?? secretFormat.value,
       )
       return true
     } catch {