@morscherlab/mint-sdk 1.1.4 → 1.1.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@morscherlab/mint-sdk",
-  "version": "1.1.4",
+  "version": "1.1.6",
   "description": "MINT Platform SDK — Vue 3 components, composables, and types for plugin development. MINT = Mass-spec INtegrated Toolkit.",
   "type": "module",
   "main": "./dist/index.js",

package/src/__tests__/components/ActionMenu.test.ts

@@ -0,0 +1,99 @@
+import { enableAutoUnmount, mount } from '@vue/test-utils'
+import { afterEach, describe, expect, it } from 'vitest'
+import ActionMenu from '../../components/ActionMenu.vue'
+
+const items = [
+  { id: 'edit', label: 'Edit' },
+  { id: 'delete', label: 'Delete', danger: true },
+]
+
+enableAutoUnmount(afterEach)
+
+describe('ActionMenu', () => {
+  it('should expose menu semantics on the square trigger', () => {
+    const wrapper = mount(ActionMenu, {
+      props: { label: 'More user actions', items },
+    })
+
+    expect(wrapper.get('button').attributes('aria-haspopup')).toBe('menu')
+  })
+
+  it('should teleport the menu to the document body when opened', async () => {
+    const wrapper = mount(ActionMenu, {
+      attachTo: document.body,
+      props: { label: 'More user actions', items },
+    })
+
+    await wrapper.get('button').trigger('click')
+
+    expect(document.body.querySelector('.mint-action-menu__panel')).not.toBeNull()
+  })
+
+  it('should emit the selected action item when an item is clicked', async () => {
+    const wrapper = mount(ActionMenu, {
+      attachTo: document.body,
+      props: { label: 'More user actions', items },
+    })
+    await wrapper.get('button').trigger('click')
+
+    const menuItems = document.body.querySelectorAll<HTMLButtonElement>('.mint-action-menu__item')
+    menuItems[0]?.click()
+    await wrapper.vm.$nextTick()
+
+    expect(wrapper.emitted('select')).toEqual([[items[0]]])
+  })
+
+  it('should render link items as semantic anchors', async () => {
+    const wrapper = mount(ActionMenu, {
+      attachTo: document.body,
+      props: {
+        label: 'More plugin actions',
+        items: [{ id: 'docs', label: 'Documentation', href: '/docs' }],
+      },
+    })
+    await wrapper.get('button').trigger('click')
+
+    expect(document.body.querySelector('.mint-action-menu__item')?.tagName).toBe('A')
+  })
+
+  it('should mark destructive items with the danger treatment', async () => {
+    const wrapper = mount(ActionMenu, {
+      attachTo: document.body,
+      props: { label: 'More user actions', items },
+    })
+    await wrapper.get('button').trigger('click')
+
+    const menuItems = document.body.querySelectorAll('.mint-action-menu__item')
+
+    expect(menuItems[1]?.classList.contains('mint-action-menu__item--danger')).toBe(true)
+  })
+
+  it('should close an open menu when its scroll context moves', async () => {
+    const wrapper = mount(ActionMenu, {
+      attachTo: document.body,
+      props: { label: 'More user actions', items },
+    })
+    await wrapper.get('button').trigger('click')
+
+    window.dispatchEvent(new Event('scroll'))
+    await wrapper.vm.$nextTick()
+
+    expect(document.body.querySelector('.mint-action-menu__panel')).toBeNull()
+  })
+
+  it('should return focus to the trigger when Escape closes the menu', async () => {
+    const wrapper = mount(ActionMenu, {
+      attachTo: document.body,
+      props: { label: 'More user actions', items },
+    })
+    const trigger = wrapper.get<HTMLButtonElement>('button')
+    await trigger.trigger('click')
+
+    document.body.querySelector<HTMLElement>('.mint-action-menu__item')?.dispatchEvent(
+      new KeyboardEvent('keydown', { key: 'Escape', bubbles: true }),
+    )
+    await wrapper.vm.$nextTick()
+
+    expect(document.activeElement).toBe(trigger.element)
+  })
+})

package/src/__tests__/components/BaseModal.test.ts

@@ -0,0 +1,133 @@
+import { mount } from '@vue/test-utils'
+import { describe, expect, it } from 'vitest'
+import BaseModal from '../../components/BaseModal.vue'
+import type { ModalTab } from '../../types'
+
+const stripTabs: ModalTab[] = [
+  { id: 'processing', label: 'Processing', meta: '6' },
+  { id: 'peaks', label: 'Peak detection' },
+  { id: 'correction', label: 'Correction', disabled: true },
+  { id: 'appearance', label: 'Appearance' },
+]
+
+const railTabs: ModalTab[] = [
+  { id: 'profile', label: 'Profile', icon: 'M20 21a8 8 0 0 0-16 0M12 11a4 4 0 1 0 0-8 4 4 0 0 0 0 8' },
+  { id: 'security', label: 'Security', meta: '2', description: 'Passkeys and institutional sign-in.' },
+  { id: 'appearance', label: 'Appearance' },
+]
+
+function mountModal(props: Record<string, unknown> = {}, slots: Record<string, string> = {}) {
+  return mount(BaseModal, {
+    props: {
+      modelValue: true,
+      title: 'Settings',
+      ...props,
+    },
+    slots: {
+      default: '<p class="body-content">Body</p>',
+      ...slots,
+    },
+    global: {
+      stubs: {
+        teleport: true,
+      },
+    },
+  })
+}
+
+describe('BaseModal', () => {
+  describe('plain layout', () => {
+    it('should not render a tab strip when layout is omitted', () => {
+      const wrapper = mountModal()
+      expect(wrapper.find('.mint-modal__tabs').exists()).toBe(false)
+    })
+  })
+
+  describe('tabs layout', () => {
+    it('should render a shell-level tablist when layout is tabs', () => {
+      const wrapper = mountModal({ layout: 'tabs', tabs: stripTabs, activeTab: 'processing' })
+      expect(wrapper.find('.mint-modal__tabs[role="tablist"]').exists()).toBe(true)
+    })
+
+    it('should mark the active tab with aria-selected when a tab is active', () => {
+      const wrapper = mountModal({ layout: 'tabs', tabs: stripTabs, activeTab: 'peaks' })
+      const active = wrapper.findAll('.mint-modal__tab')[1]
+      expect(active.attributes('aria-selected')).toBe('true')
+    })
+
+    it('should render the tab meta when a tab defines one', () => {
+      const wrapper = mountModal({ layout: 'tabs', tabs: stripTabs, activeTab: 'processing' })
+      expect(wrapper.find('.mint-modal__tab-meta').text()).toBe('6')
+    })
+
+    it('should emit update:activeTab when another tab is clicked', async () => {
+      const wrapper = mountModal({ layout: 'tabs', tabs: stripTabs, activeTab: 'processing' })
+      await wrapper.findAll('.mint-modal__tab')[1].trigger('click')
+      expect(wrapper.emitted('update:activeTab')?.at(-1)).toEqual(['peaks'])
+    })
+
+    it('should not emit update:activeTab when a disabled tab is clicked', async () => {
+      const wrapper = mountModal({ layout: 'tabs', tabs: stripTabs, activeTab: 'processing' })
+      await wrapper.findAll('.mint-modal__tab')[2].trigger('click')
+      expect(wrapper.emitted('update:activeTab')).toBeUndefined()
+    })
+
+    it('should skip disabled tabs when moving with ArrowRight', async () => {
+      const wrapper = mountModal({ layout: 'tabs', tabs: stripTabs, activeTab: 'peaks' })
+      await wrapper.findAll('.mint-modal__tab')[1].trigger('keydown.right')
+      expect(wrapper.emitted('update:activeTab')?.at(-1)).toEqual(['appearance'])
+    })
+
+    it('should apply the fixed-height body modifier when layout is tabs', () => {
+      const wrapper = mountModal({ layout: 'tabs', tabs: stripTabs, activeTab: 'processing' })
+      expect(wrapper.find('.mint-modal__body').classes()).toContain('mint-modal__body--tabbed')
+    })
+  })
+
+  describe('rail layout', () => {
+    it('should render a vertical tablist when layout is rail', () => {
+      const wrapper = mountModal({ layout: 'rail', tabs: railTabs, activeTab: 'profile' })
+      expect(wrapper.find('.mint-modal__rail[aria-orientation="vertical"]').exists()).toBe(true)
+    })
+
+    it('should show the active tab label as the pane title', () => {
+      const wrapper = mountModal({ layout: 'rail', tabs: railTabs, activeTab: 'security' })
+      expect(wrapper.find('.mint-modal__pane-title').text()).toBe('Security')
+    })
+
+    it('should show the active tab description as the pane subtitle', () => {
+      const wrapper = mountModal({ layout: 'rail', tabs: railTabs, activeTab: 'security' })
+      expect(wrapper.find('.mint-modal__pane-subtitle').text()).toBe('Passkeys and institutional sign-in.')
+    })
+
+    it('should emit update:activeTab when a rail item is clicked', async () => {
+      const wrapper = mountModal({ layout: 'rail', tabs: railTabs, activeTab: 'profile' })
+      await wrapper.findAll('.mint-modal__rail-item')[1].trigger('click')
+      expect(wrapper.emitted('update:activeTab')?.at(-1)).toEqual(['security'])
+    })
+
+    it('should move to the next tab when ArrowDown is pressed on a rail item', async () => {
+      const wrapper = mountModal({ layout: 'rail', tabs: railTabs, activeTab: 'profile' })
+      await wrapper.findAll('.mint-modal__rail-item')[0].trigger('keydown.down')
+      expect(wrapper.emitted('update:activeTab')?.at(-1)).toEqual(['security'])
+    })
+
+    it('should render the rail-footer slot inside the rail', () => {
+      const wrapper = mountModal(
+        { layout: 'rail', tabs: railTabs, activeTab: 'profile' },
+        { 'rail-footer': '<button class="rail-logout">Log out</button>' },
+      )
+      expect(wrapper.find('.mint-modal__rail .rail-logout').exists()).toBe(true)
+    })
+
+    it('should not render the plain body when layout is rail', () => {
+      const wrapper = mountModal({ layout: 'rail', tabs: railTabs, activeTab: 'profile' })
+      expect(wrapper.find('.mint-modal__body').exists()).toBe(false)
+    })
+
+    it('should render the default slot inside the pane body when layout is rail', () => {
+      const wrapper = mountModal({ layout: 'rail', tabs: railTabs, activeTab: 'profile' })
+      expect(wrapper.find('.mint-modal__pane-body .body-content').exists()).toBe(true)
+    })
+  })
+})

package/src/__tests__/components/SettingsModal.test.ts

@@ -32,14 +32,16 @@ describe('SettingsModal', () => {
       'tab-Advanced': '<div class="advanced-tab">Advanced Content</div>',
     })
 
-    const tabs = wrapper.findAll('.mint-settings-modal__tab')
+    const tabs = wrapper.findAll('.mint-modal__tab')
     expect(tabs.map(tab => tab.text())).toEqual(['General', 'Advanced'])
-    expect(tabs[0].classes()).toContain('mint-settings-modal__tab--active')
+    expect(tabs[0].classes()).toContain('mint-modal__tab--active')
     expect(wrapper.find('.general-tab').exists()).toBe(true)
 
     await tabs[1].trigger('click')
 
-    expect(tabs[1].classes()).toContain('mint-settings-modal__tab--active')
+    // Re-query: the teleport stub rebuilds the strip on re-render, so the
+    // pre-click wrappers point at detached nodes.
+    expect(wrapper.findAll('.mint-modal__tab')[1].classes()).toContain('mint-modal__tab--active')
   })
 
   it('syncs schema changes without remounting the modal', async () => {
@@ -78,7 +80,7 @@ describe('SettingsModal', () => {
     await wrapper.find('input').setValue('0.5')
     await wrapper.setProps({ schema: nextSchema })
 
-    const tabs = wrapper.findAll('.mint-settings-modal__tab')
+    const tabs = wrapper.findAll('.mint-modal__tab')
     expect(tabs.map(tab => tab.text())).toEqual(['General', 'Advanced'])
     expect((wrapper.find('input').element as HTMLInputElement).value).toBe('0.5')
 
@@ -177,7 +179,7 @@ describe('SettingsModal', () => {
 
     const wrapper = mountSettingsModal({ controls })
 
-    const tabs = wrapper.findAll('.mint-settings-modal__tab')
+    const tabs = wrapper.findAll('.mint-modal__tab')
     expect(tabs.map(tab => tab.text())).toEqual(['Parameters', 'Advanced'])
     expect((wrapper.find('input').element as HTMLInputElement).value).toBe('0.25')
 
@@ -355,7 +357,7 @@ describe('SettingsModal', () => {
 
     const adminWrapper = mountSettingsModal({ schema, userType: 'admin' })
 
-    expect(adminWrapper.findAll('.mint-settings-modal__tab').map(tab => tab.text())).toEqual([
+    expect(adminWrapper.findAll('.mint-modal__tab').map(tab => tab.text())).toEqual([
       'General',
       'Admin',
     ])
@@ -363,7 +365,7 @@ describe('SettingsModal', () => {
     expect(adminWrapper.text()).toContain('Admin Secret')
     expect(adminWrapper.text()).not.toContain('User Note')
 
-    await adminWrapper.findAll('.mint-settings-modal__tab')[1].trigger('click')
+    await adminWrapper.findAll('.mint-modal__tab')[1].trigger('click')
 
     expect(adminWrapper.text()).toContain('Admin Only')
   })

package/src/__tests__/docs/extractDocsComponents.test.ts

@@ -78,7 +78,14 @@ export { default as SpecialThing } from './SpecialThing.vue'
     mkdirSync(join(dir, 'src', 'components'), { recursive: true })
     writeFileSync(componentPath, `
 <script setup lang="ts">
-/** Fancy button docs. */
+/**
+ * Fancy button docs.
+ *
+ * @example Recommended
+ * \`\`\`vue
+ * <FancyButton label="Save" />
+ * \`\`\`
+ */
 interface Props {
   /** Visible label. */
   label: string
@@ -114,6 +121,13 @@ defineSlots<{
       group: 'base',
       source: 'packages/sdk-frontend/src/components/FancyButton.vue',
       description: 'Fancy button docs.',
+      examples: [
+        {
+          title: 'Recommended',
+          language: 'vue',
+          code: '<FancyButton label="Save" />',
+        },
+      ],
       props: [
         {
           name: 'label',

package/src/__tests__/docs/extractDocsParsing.test.ts

@@ -4,6 +4,7 @@ import {
   cleanJsdocSummary,
   extractBalancedBraces,
   extractBalancedParens,
+  extractJsdocExamples,
   extractTrailingJsdoc,
   findMatchingClose,
   splitTopLevel,
@@ -66,4 +67,25 @@ describe('extract docs parsing helpers', () => {
 
     expect(extractTrailingJsdoc(source, source.indexOf('export function'))).toContain('Selected.')
   })
+
+  it('extracts structured examples from JSDoc fenced blocks', () => {
+    const comment = `
+      /**
+       * Component summary.
+       *
+       * @example Recommended
+       * \`\`\`vue
+       * <ExperimentSelectorModal v-model="open" />
+       * \`\`\`
+       */
+    `
+
+    expect(extractJsdocExamples(comment)).toEqual([
+      {
+        title: 'Recommended',
+        language: 'vue',
+        code: '<ExperimentSelectorModal v-model="open" />',
+      },
+    ])
+  })
 })

package/src/__tests__/docs/frontendDocsCatalog.test.ts

@@ -3,6 +3,13 @@ import { existsSync, readFileSync } from 'node:fs'
 import { dirname, join, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { describe, expect, it } from 'vitest'
+import { compile } from 'vue'
+import {
+  DiagnosticCategory,
+  ModuleKind,
+  ScriptTarget,
+  transpileModule,
+} from 'typescript'
 
 interface FrontendManifest {
   categories: {
@@ -10,10 +17,13 @@ interface FrontendManifest {
       name: string
       deprecated?: boolean
       replacement?: string
+      examples?: Array<{ title: string; language: string; code: string }>
+      props?: Array<{ name: string }>
     }>
     composables: Array<{
       name: string
       members?: Array<{ name: string }>
+      examples?: Array<{ title: string; language: string; code: string }>
     }>
     templateExports: Array<{ name: string }>
     templatePacks: Array<{ name: string }>
@@ -23,6 +33,18 @@ interface FrontendManifest {
 
 const TEST_DIR = dirname(fileURLToPath(import.meta.url))
 const SDK_ROOT = resolve(TEST_DIR, '../../..')
+const CORE_USAGE_NAMES = [
+  'ArtifactSelectorModal',
+  'ControlWorkspaceView',
+  'ExperimentSelectorModal',
+  'GeneratedPluginView',
+  'GeneratedResultRenderer',
+  'JobsStatusTray',
+  'PluginWorkspaceView',
+  'useAnalysisArtifacts',
+  'useAppExperiment',
+  'usePluginJobs',
+]
 
 function extractFrontendManifest(): FrontendManifest {
   const output = execFileSync('bun', ['run', 'scripts/extract-docs.ts'], {
@@ -191,6 +213,64 @@ describe('frontend docs catalog coverage', () => {
     expect(missingFromManifest(documentedComponents, publicComponents)).toEqual([])
   })
 
+  it('keeps source-owned examples for the core frontend documentation contract', () => {
+    const manifest = extractFrontendManifest()
+    const documented = [
+      ...manifest.categories.components,
+      ...manifest.categories.composables,
+    ]
+    const byName = new Map(documented.map(item => [item.name, item]))
+    expect(CORE_USAGE_NAMES.filter(name => !byName.get(name)?.examples?.length)).toEqual([])
+  })
+
+  it('keeps core frontend examples syntactically valid', () => {
+    const manifest = extractFrontendManifest()
+    const documented = [
+      ...manifest.categories.components,
+      ...manifest.categories.composables,
+    ]
+    const byName = new Map(documented.map(item => [item.name, item]))
+    const invalid: string[] = []
+
+    for (const name of CORE_USAGE_NAMES) {
+      for (const example of byName.get(name)?.examples ?? []) {
+        if (example.language === 'vue') {
+          try {
+            compile(example.code)
+          } catch {
+            invalid.push(name)
+          }
+          continue
+        }
+        const result = transpileModule(example.code, {
+          compilerOptions: {
+            module: ModuleKind.ESNext,
+            target: ScriptTarget.ESNext,
+          },
+          reportDiagnostics: true,
+        })
+        if (result.diagnostics?.some(diagnostic => diagnostic.category === DiagnosticCategory.Error)) {
+          invalid.push(name)
+        }
+      }
+    }
+
+    expect(invalid).toEqual([])
+  })
+
+  it('documents required props for generated high-level components', () => {
+    const manifest = extractFrontendManifest()
+    const byName = new Map(manifest.categories.components.map(item => [item.name, item]))
+
+    expect({
+      GeneratedPluginView: byName.get('GeneratedPluginView')?.props?.map(prop => prop.name),
+      GeneratedResultRenderer: byName.get('GeneratedResultRenderer')?.props?.map(prop => prop.name),
+    }).toEqual({
+      GeneratedPluginView: ['baseUrl', 'showStandaloneLabel', 'transport'],
+      GeneratedResultRenderer: ['result'],
+    })
+  })
+
   it('re-exports every public component from the root SDK entrypoint', () => {
     const publicComponents = parseComponentExports()
     const rootComponents = parseRootComponentExports()

package/src/components/ActionMenu.story.vue

@@ -0,0 +1,26 @@
+<script setup lang="ts">
+import ActionMenu from './ActionMenu.vue'
+import type { ActionMenuItem } from '../types'
+
+const items: ActionMenuItem[] = [
+  { id: 'edit', label: 'Edit' },
+  { id: 'docs', label: 'Documentation ↗', href: 'https://example.com/docs', target: '_blank' },
+  { id: 'delete', label: 'Delete', danger: true },
+]
+</script>
+
+<template>
+  <Story title="Action/ActionMenu">
+    <Variant title="Default">
+      <div style="min-height: 14rem; display: flex; justify-content: center; padding: 2rem;">
+        <ActionMenu label="More actions" :items="items" />
+      </div>
+    </Variant>
+
+    <Variant title="Disabled">
+      <div style="display: flex; justify-content: center; padding: 2rem;">
+        <ActionMenu label="More actions" :items="items" disabled />
+      </div>
+    </Variant>
+  </Story>
+</template>