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

package/dist/utils/pluginSecrets.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Stable references for plugin secret settings.
+ *
+ * A settings response never carries a secret's value. Every secret leaf is a
+ * marker instead:
+ *
+ * - `{ "$secret": "sec_…", "set": true }` — a stored secret, referenced by a
+ *   stable opaque id. Send the marker back unchanged to keep the stored value.
+ * - `null` — nothing stored at that position.
+ * - `{ "$secret": null, "locked": true }` — the effective value comes from the
+ *   environment and is never written back.
+ *
+ * On save each secret leaf accepts the reference, a plain string (a new value),
+ * or `null` (clear). Payloads carry `secret_format: "ref"` so a `null` reads as
+ * a deliberate clear rather than the deprecated "unchanged" placeholder.
+ */
+/** Reserved marker key that references a stored secret. */
+export declare const PLUGIN_SECRET_REF_KEY = "$secret";
+/** Reserved payload key declaring which secret wire format a client speaks. */
+export declare const PLUGIN_SECRET_FORMAT_KEY = "secret_format";
+/** Wire format published and understood by this SDK. */
+export declare const PLUGIN_SECRET_FORMAT_REF = "ref";
+/** One `$secret` marker as published by a settings response. */
+export interface PluginSecretRef {
+    $secret: string | null;
+    set?: boolean;
+    locked?: boolean;
+}
+/** What a settings form should tell the user about one secret field. */
+export type PluginSecretState = 'set' | 'unset' | 'environment';
+/** Return whether one settings value is a `$secret` reference marker. */
+export declare function isPluginSecretRef(value: unknown): value is PluginSecretRef;
+/** Return the stored secret id behind a marker, or `null` when nothing is stored. */
+export declare function pluginSecretId(value: unknown): string | null;
+/** Classify one secret field for display: stored, unset, or environment-provided. */
+export declare function pluginSecretState(value: unknown): PluginSecretState;
+/** Human label for one secret field's state. */
+export declare function pluginSecretLabel(value: unknown): string;
+/** Whether a secret field is read-only because the environment supplies it. */
+export declare function isPluginSecretLocked(value: unknown): boolean;
+/**
+ * Value to submit for an untouched secret field: the reference, unchanged.
+ *
+ * A locked marker round-trips too, which is how the platform keeps a stored
+ * value that an environment variable currently hides.
+ */
+export declare function keepPluginSecret(current: unknown): PluginSecretRef | null;
+/** Value to submit when the user typed a new secret. */
+export declare function setPluginSecret(value: string): string;
+/** Value to submit when the user cleared a secret. */
+export declare function clearPluginSecret(): null;
+/** Whether a settings response declares the `$secret` reference wire format. */
+export declare function usesPluginSecretReferences(response: unknown): boolean;

package/dist/utils/records.d.ts

@@ -0,0 +1,4 @@
+/** Narrow an unknown value to a plain object (arrays and null excluded). */
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+/** Narrow an unknown value to any non-null object, arrays included. */
+export declare function isObjectLike(value: unknown): value is Record<string, unknown>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@morscherlab/mint-sdk",
-  "version": "1.2.0-beta.3",
+  "version": "1.2.0-beta.5",
   "description": "MINT Platform SDK — Vue 3 components, composables, and types for plugin development. MINT = Mass-spec INtegrated Toolkit.",
   "type": "module",
   "main": "./dist/index.js",
@@ -15,6 +15,10 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
+    "./install": {
+      "types": "./dist/install.d.ts",
+      "import": "./dist/install.js"
+    },
     "./components": {
       "types": "./dist/components/index.d.ts",
       "import": "./dist/components/index.js"
@@ -46,7 +50,8 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "src"
   ],
   "scripts": {
     "build": "vue-tsc --noEmit && bun run build:library && bun run build:generated-ui && node scripts/check-package-exports.mjs",
@@ -85,6 +90,7 @@
   "devDependencies": {
     "@histoire/plugin-vue": "1.0.0-beta.1",
     "@simplewebauthn/browser": "10.0.0",
+    "@simplewebauthn/types": "10.0.0",
     "@types/node": "22.19.13",
     "@types/plotly.js": "^3.0.10",
     "@vitejs/plugin-vue": "6.0.5",

package/src/__stories__/experiment-helpers.ts

@@ -0,0 +1,86 @@
+/**
+ * Shared helpers for story files that need experiment selector integration.
+ * Provides mock data, API interceptors, and a provider wrapper component.
+ */
+import { defineComponent, onUnmounted } from 'vue'
+import { useAppExperiment } from '../composables/useAppExperiment'
+import { useApi } from '../composables/useApi'
+import { useExperimentStore } from '../stores/experiment'
+import type { ExperimentSummary } from '../types'
+
+export const mockExperiments: ExperimentSummary[] = [
+  { id: 1, experiment_code: 'DR-HeLa-DOX-001', name: 'Doxorubicin dose-response in HeLa cells', status: 'completed', experiment_type: 'dose_response', project: 'Oncology Screen Q1', project_name: 'Oncology Screen Q1', created_at: '2026-02-28T14:30:00Z', updated_at: '2026-03-01T09:15:00Z', has_design_data: true },
+  { id: 2, experiment_code: 'CV-MCF7-24H-002', name: 'MCF-7 cell viability 24h time course', status: 'completed', experiment_type: 'cell_viability', project: 'Oncology Screen Q1', project_name: 'Oncology Screen Q1', created_at: '2026-02-25T10:00:00Z', updated_at: '2026-02-26T16:45:00Z', has_design_data: true },
+  { id: 3, experiment_code: 'DR-PANC1-GEM-003', name: 'Gemcitabine IC50 in PANC-1', status: 'ongoing', experiment_type: 'dose_response', project: 'Pancreatic Cancer', project_name: 'Pancreatic Cancer', created_at: '2026-03-01T08:00:00Z', updated_at: '2026-03-02T11:30:00Z', has_design_data: true },
+  { id: 4, experiment_code: 'CV-A549-CIS-004', name: 'Cisplatin cytotoxicity A549 lung', status: 'ongoing', experiment_type: 'cell_viability', project: 'Lung Cancer Panel', project_name: 'Lung Cancer Panel', created_at: '2026-03-01T13:00:00Z', updated_at: '2026-03-02T08:00:00Z', has_design_data: false },
+  { id: 5, experiment_code: 'DR-HEK293-CTRL-005', name: 'HEK-293T control viability baseline', status: 'completed', experiment_type: 'dose_response', project: 'Toxicity Controls', project_name: 'Toxicity Controls', created_at: '2026-02-20T09:00:00Z', updated_at: '2026-02-22T17:00:00Z', has_design_data: true },
+]
+
+const mockExperimentTypes = [
+  { name: 'dose_response', color: '#3b82f6' },
+  { name: 'cell_viability', color: '#10b981' },
+]
+
+const mockProjects = [
+  { id: 1, name: 'Oncology Screen Q1' },
+  { id: 2, name: 'Pancreatic Cancer' },
+  { id: 3, name: 'Lung Cancer Panel' },
+  { id: 4, name: 'Toxicity Controls' },
+]
+
+export function installMockInterceptor() {
+  const { client } = useApi()
+  client.interceptors.request.use((config) => {
+    const url = config.url ?? ''
+    if (url.includes('/experiments/experiment-types')) {
+      config.adapter = () => Promise.resolve({ data: mockExperimentTypes, status: 200, statusText: 'OK', headers: {}, config })
+      return config
+    }
+    if (url.includes('/projects')) {
+      config.adapter = () => Promise.resolve({ data: mockProjects, status: 200, statusText: 'OK', headers: {}, config })
+      return config
+    }
+    if (url.startsWith('/api/experiments')) {
+      const params = new URLSearchParams(url.split('?')[1] ?? '')
+      const skip = Number(params.get('skip') ?? 0)
+      const limit = Number(params.get('limit') ?? 100)
+      let filtered = [...mockExperiments]
+      const status = params.get('status')
+      const search = params.get('search')?.toLowerCase()
+      if (status) filtered = filtered.filter(e => e.status === status)
+      if (search) filtered = filtered.filter(e => e.name.toLowerCase().includes(search) || e.experiment_code?.toLowerCase().includes(search))
+      config.adapter = () => Promise.resolve({ data: { experiments: filtered.slice(skip, skip + limit), total: filtered.length }, status: 200, statusText: 'OK', headers: {}, config })
+    }
+    return config
+  })
+}
+
+/**
+ * Wrapper component that fakes integrated mode and provides useAppExperiment context.
+ * Use in story files to demonstrate experiment selector integration.
+ *
+ * The preselected experiment is committed to the shared store as a full
+ * platform record — the same path the selector modal uses at runtime.
+ *
+ * Props:
+ *   preselect (boolean, default true) - pre-select the first mock experiment
+ */
+export const ExperimentProvider = defineComponent({
+  props: { preselect: { type: Boolean, default: true } },
+  setup(props, { slots }) {
+    ;(window as any).__MINT_PLATFORM__ = { isIntegrated: true, theme: 'system' }
+    installMockInterceptor()
+    const experimentStore = useExperimentStore()
+    useAppExperiment({
+      onSave: async () => 'Saved!',
+    })
+    if (props.preselect && mockExperiments[0]) {
+      experimentStore.select(mockExperiments[0])
+    }
+    onUnmounted(() => {
+      experimentStore.clear()
+      delete (window as any).__MINT_PLATFORM__
+    })
+    return () => slots.default?.()
+  },
+})

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

@@ -0,0 +1,99 @@
+import { mount } from '@vue/test-utils'
+import { defineComponent, h } from 'vue'
+import { describe, expect, it, vi } from 'vitest'
+import ActionItemInternal from '../../components/internal/ActionItemInternal.vue'
+
+function createRouterLinkStub(navigate = vi.fn()) {
+  return defineComponent({
+    name: 'RouterLinkStub',
+    props: {
+      to: [String, Object],
+      custom: Boolean,
+    },
+    setup(props, { slots }) {
+      return () => props.custom
+        ? slots.default?.({ href: props.to, navigate })
+        : h('a', { href: props.to, onClick: navigate }, slots.default?.())
+    },
+  })
+}
+
+describe('ActionItemInternal', () => {
+  it('renders a normal button action and emits clicks', async () => {
+    const wrapper = mount(ActionItemInternal, {
+      slots: { default: 'Run' },
+    })
+
+    const button = wrapper.get('button')
+    expect(button.attributes('type')).toBe('button')
+
+    await button.trigger('click')
+
+    expect(wrapper.emitted('click')).toHaveLength(1)
+  })
+
+  it('renders disabled href actions without navigating or emitting', async () => {
+    const wrapper = mount(ActionItemInternal, {
+      props: {
+        href: '/disabled',
+        disabled: true,
+      },
+      slots: { default: 'Disabled' },
+    })
+
+    const link = wrapper.get('a')
+    expect(link.attributes('href')).toBeUndefined()
+    expect(link.attributes('aria-disabled')).toBe('true')
+
+    await link.trigger('click')
+
+    expect(wrapper.emitted('click')).toBeUndefined()
+  })
+
+  it('renders router actions through router-link and navigates after emitting', async () => {
+    const navigate = vi.fn()
+    const wrapper = mount(ActionItemInternal, {
+      props: { to: '/settings' },
+      slots: { default: 'Settings' },
+      global: {
+        stubs: {
+          'router-link': createRouterLinkStub(navigate),
+        },
+      },
+    })
+
+    const link = wrapper.get('a')
+    expect(link.attributes('href')).toBe('/settings')
+
+    await link.trigger('click')
+
+    expect(wrapper.emitted('click')).toHaveLength(1)
+    expect(navigate).toHaveBeenCalledTimes(1)
+  })
+
+  it('renders disabled router actions without href, navigation, or emitted clicks', async () => {
+    const navigate = vi.fn()
+    const wrapper = mount(ActionItemInternal, {
+      props: {
+        to: '/settings',
+        disabled: true,
+      },
+      slots: { default: 'Settings' },
+      global: {
+        stubs: {
+          'router-link': createRouterLinkStub(navigate),
+        },
+      },
+    })
+
+    const link = wrapper.get('a')
+    expect(link.attributes('href')).toBeUndefined()
+    expect(link.attributes('aria-disabled')).toBe('true')
+    expect(link.attributes('tabindex')).toBe('-1')
+
+    await link.trigger('click')
+
+    expect(wrapper.emitted('click')).toBeUndefined()
+    expect(navigate).not.toHaveBeenCalled()
+  })
+})

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

@@ -0,0 +1,120 @@
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+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 render the default trigger with the Lucide ellipsis icon', () => {
+    const wrapper = mount(ActionMenu, {
+      props: { label: 'More user actions', items },
+    })
+
+    expect(wrapper.find('svg.lucide-ellipsis').exists()).toBe(true)
+  })
+
+  it('should keep the default trigger icon at 16 pixels', () => {
+    const styles = readFileSync(
+      resolve(process.cwd(), 'src/styles/components/action-menu.css'),
+      'utf8',
+    )
+
+    expect(styles).toMatch(
+      /\.mint-action-menu__trigger-icon\s*\{[^}]*width:\s*1rem;[^}]*height:\s*1rem;/s,
+    )
+  })
+
+  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/AppAvatarMenu.test.ts

@@ -0,0 +1,161 @@
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { mount } from '@vue/test-utils'
+import { describe, expect, it } from 'vitest'
+import AppAvatarMenu from '../../components/AppAvatarMenu.vue'
+
+describe('AppAvatarMenu', () => {
+  it('should vertically center avatar initials with a compact line box', () => {
+    const styles = readFileSync(
+      resolve(process.cwd(), 'src/styles/components/app-avatar-menu.css'),
+      'utf8',
+    )
+
+    expect(styles).toMatch(/\.mint-avatar-menu__avatar\s*\{[^}]*line-height:\s*1;/s)
+  })
+
+  it('renders mixed menu actions and emits selected items', async () => {
+    const docs = { id: 'docs', label: 'Docs', href: '/docs' }
+    const profile = { id: 'profile', label: 'Profile' }
+    const wrapper = mount(AppAvatarMenu, {
+      props: {
+        userName: 'Ada Lovelace',
+        items: [profile, { id: 'divider', label: '', divider: true }, docs],
+        showSignOut: false,
+      },
+    })
+
+    await wrapper.get('.mint-avatar-menu__trigger').trigger('click')
+
+    const items = wrapper.findAll('.mint-avatar-menu__item')
+    expect(items[1].element.tagName.toLowerCase()).toBe('a')
+
+    await items[1].trigger('click')
+
+    expect(wrapper.emitted('select')).toEqual([[docs]])
+    expect(wrapper.find('.mint-avatar-menu__panel').exists()).toBe(false)
+  })
+
+  describe('keyboard handling (menu button pattern)', () => {
+    const items = [{ id: 'profile', label: 'Profile' }, { id: 'settings', label: 'Settings' }]
+
+    function mountMenu() {
+      return mount(AppAvatarMenu, {
+        props: { userName: 'Ada Lovelace', items, showSignOut: true },
+        attachTo: document.body,
+      })
+    }
+
+    it('sets aria-expanded on the trigger and toggles it open/closed', async () => {
+      const wrapper = mountMenu()
+      const trigger = wrapper.get('.mint-avatar-menu__trigger')
+      expect(trigger.attributes('aria-expanded')).toBe('false')
+
+      await trigger.trigger('click')
+      expect(trigger.attributes('aria-expanded')).toBe('true')
+
+      wrapper.unmount()
+    })
+
+    it('opens and focuses the first item on ArrowDown', async () => {
+      const wrapper = mountMenu()
+      await wrapper.get('.mint-avatar-menu__trigger').trigger('keydown', { key: 'ArrowDown' })
+      await wrapper.vm.$nextTick()
+
+      expect(wrapper.find('.mint-avatar-menu__panel').exists()).toBe(true)
+      expect(document.activeElement).toBe(wrapper.findAll('[role="menuitem"]')[0].element)
+
+      wrapper.unmount()
+    })
+
+    it('opens and focuses the last item on ArrowUp', async () => {
+      const wrapper = mountMenu()
+      await wrapper.get('.mint-avatar-menu__trigger').trigger('keydown', { key: 'ArrowUp' })
+      await wrapper.vm.$nextTick()
+
+      const menuItems = wrapper.findAll('[role="menuitem"]')
+      expect(document.activeElement).toBe(menuItems[menuItems.length - 1].element)
+
+      wrapper.unmount()
+    })
+
+    it('opens and focuses the first item on Enter and Space', async () => {
+      for (const key of ['Enter', ' ']) {
+        const wrapper = mountMenu()
+        await wrapper.get('.mint-avatar-menu__trigger').trigger('keydown', { key })
+        await wrapper.vm.$nextTick()
+
+        expect(document.activeElement).toBe(wrapper.findAll('[role="menuitem"]')[0].element)
+        wrapper.unmount()
+      }
+    })
+
+    it('cycles item focus with ArrowDown/ArrowUp, wrapping at the ends', async () => {
+      const wrapper = mountMenu()
+      await wrapper.get('.mint-avatar-menu__trigger').trigger('keydown', { key: 'ArrowDown' })
+      await wrapper.vm.$nextTick()
+
+      const menuItems = wrapper.findAll('[role="menuitem"]')
+      const panel = wrapper.get('.mint-avatar-menu__panel')
+
+      await panel.trigger('keydown', { key: 'ArrowDown' })
+      expect(document.activeElement).toBe(menuItems[1].element)
+
+      await panel.trigger('keydown', { key: 'ArrowDown' })
+      expect(document.activeElement).toBe(menuItems[menuItems.length - 1].element)
+
+      await panel.trigger('keydown', { key: 'ArrowDown' })
+      expect(document.activeElement).toBe(menuItems[0].element)
+
+      await panel.trigger('keydown', { key: 'ArrowUp' })
+      expect(document.activeElement).toBe(menuItems[menuItems.length - 1].element)
+
+      wrapper.unmount()
+    })
+
+    it('jumps to the first item on Home and the last on End', async () => {
+      const wrapper = mountMenu()
+      await wrapper.get('.mint-avatar-menu__trigger').trigger('keydown', { key: 'ArrowDown' })
+      await wrapper.vm.$nextTick()
+
+      const menuItems = wrapper.findAll('[role="menuitem"]')
+      const panel = wrapper.get('.mint-avatar-menu__panel')
+
+      await panel.trigger('keydown', { key: 'End' })
+      expect(document.activeElement).toBe(menuItems[menuItems.length - 1].element)
+
+      await panel.trigger('keydown', { key: 'Home' })
+      expect(document.activeElement).toBe(menuItems[0].element)
+
+      wrapper.unmount()
+    })
+
+    it('closes on Escape and returns focus to the trigger', async () => {
+      const wrapper = mountMenu()
+      const trigger = wrapper.get('.mint-avatar-menu__trigger')
+      await trigger.trigger('keydown', { key: 'ArrowDown' })
+      await wrapper.vm.$nextTick()
+
+      await wrapper.get('.mint-avatar-menu__panel').trigger('keydown', { key: 'Escape' })
+      await wrapper.vm.$nextTick()
+
+      expect(wrapper.find('.mint-avatar-menu__panel').exists()).toBe(false)
+      expect(document.activeElement).toBe(trigger.element)
+
+      wrapper.unmount()
+    })
+
+    it('closes on Tab without forcing focus', async () => {
+      const wrapper = mountMenu()
+      await wrapper.get('.mint-avatar-menu__trigger').trigger('keydown', { key: 'ArrowDown' })
+      await wrapper.vm.$nextTick()
+
+      await wrapper.get('.mint-avatar-menu__panel').trigger('keydown', { key: 'Tab' })
+      await wrapper.vm.$nextTick()
+
+      expect(wrapper.find('.mint-avatar-menu__panel').exists()).toBe(false)
+
+      wrapper.unmount()
+    })
+  })
+})