@morscherlab/mint-sdk 1.2.0-beta.4 → 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.4",
+  "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",

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

@@ -35,4 +35,127 @@ describe('AppAvatarMenu', () => {
     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()
+    })
+  })
 })

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

@@ -37,4 +37,71 @@ describe('BaseTabs', () => {
     expect(wrapper.findAll('svg.mint-tab__icon--svg')).toHaveLength(2)
     expect(wrapper.findAll('path')).toHaveLength(3)
   })
+
+  describe('keyboard navigation (WAI-ARIA tabs pattern)', () => {
+    const tabs = ['Run', 'Results', { id: 'settings', label: 'Settings', disabled: true }, 'Logs']
+
+    it('puts tabindex="0" only on the active tab', () => {
+      const wrapper = mount(BaseTabs, { props: { modelValue: 'Results', tabs } })
+      const buttons = wrapper.findAll('.mint-tab')
+
+      expect(buttons.map(b => b.attributes('tabindex'))).toEqual(['-1', '0', '-1', '-1'])
+    })
+
+    it('moves to and activates the next enabled tab on ArrowRight, skipping disabled tabs', async () => {
+      const wrapper = mount(BaseTabs, { props: { modelValue: 'Results', tabs } })
+
+      await wrapper.findAll('.mint-tab')[1].trigger('keydown', { key: 'ArrowRight' })
+
+      expect(wrapper.emitted('update:modelValue')?.at(-1)).toEqual(['Logs'])
+    })
+
+    it('moves to the previous enabled tab on ArrowLeft, wrapping past the start', async () => {
+      const wrapper = mount(BaseTabs, { props: { modelValue: 'Run', tabs } })
+
+      await wrapper.findAll('.mint-tab')[0].trigger('keydown', { key: 'ArrowLeft' })
+
+      expect(wrapper.emitted('update:modelValue')?.at(-1)).toEqual(['Logs'])
+    })
+
+    it('wraps past the end on ArrowRight', async () => {
+      const wrapper = mount(BaseTabs, { props: { modelValue: 'Logs', tabs } })
+
+      await wrapper.findAll('.mint-tab')[3].trigger('keydown', { key: 'ArrowRight' })
+
+      expect(wrapper.emitted('update:modelValue')?.at(-1)).toEqual(['Run'])
+    })
+
+    it('jumps to the first tab on Home and the last on End', async () => {
+      const wrapper = mount(BaseTabs, { props: { modelValue: 'Results', tabs } })
+
+      await wrapper.findAll('.mint-tab')[1].trigger('keydown', { key: 'End' })
+      expect(wrapper.emitted('update:modelValue')?.at(-1)).toEqual(['Logs'])
+
+      await wrapper.findAll('.mint-tab')[1].trigger('keydown', { key: 'Home' })
+      expect(wrapper.emitted('update:modelValue')?.at(-1)).toEqual(['Run'])
+    })
+
+    it('moves DOM focus onto the newly-activated tab', async () => {
+      const wrapper = mount(BaseTabs, {
+        props: { modelValue: 'Run', tabs },
+        attachTo: document.body,
+      })
+
+      await wrapper.findAll('.mint-tab')[0].trigger('keydown', { key: 'ArrowRight' })
+      await wrapper.setProps({ modelValue: 'Results' })
+      await wrapper.vm.$nextTick()
+
+      expect(document.activeElement).toBe(wrapper.findAll('.mint-tab')[1].element)
+      wrapper.unmount()
+    })
+
+    it('keeps aria-selected and aria-controls consistent with the active tab', () => {
+      const wrapper = mount(BaseTabs, { props: { modelValue: 'Results', tabs } })
+      const active = wrapper.findAll('.mint-tab')[1]
+
+      expect(active.attributes('aria-selected')).toBe('true')
+      expect(active.attributes('id')).toBe(active.attributes('aria-controls')?.replace('tabpanel', 'tab'))
+    })
+  })
 })

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

@@ -458,6 +458,140 @@ describe('DropdownButton', () => {
     })
   })
 
+  describe('listbox keyboard handling', () => {
+    it('opens and focuses the first enabled option on ArrowDown', async () => {
+      const wrapper = mount(DropdownButton, {
+        props: { options: mockOptions },
+        attachTo: document.body,
+      })
+
+      await wrapper.get('.mint-dropdown-button__trigger').trigger('keydown', { key: 'ArrowDown' })
+      await wrapper.vm.$nextTick()
+
+      expect(wrapper.find('.mint-dropdown-button__menu').exists()).toBe(true)
+      expect(document.activeElement).toBe(wrapper.findAll('.mint-dropdown-button__option')[0].element)
+
+      wrapper.unmount()
+    })
+
+    it('opens and focuses the last option on ArrowUp', async () => {
+      const wrapper = mount(DropdownButton, {
+        props: { options: mockOptions },
+        attachTo: document.body,
+      })
+
+      await wrapper.get('.mint-dropdown-button__trigger').trigger('keydown', { key: 'ArrowUp' })
+      await wrapper.vm.$nextTick()
+
+      // Option C is disabled and excluded from the navigable set, so the last
+      // navigable option is Option B even though it renders second-to-last.
+      const options = wrapper.findAll('.mint-dropdown-button__option')
+      expect(document.activeElement).toBe(options[1].element)
+
+      wrapper.unmount()
+    })
+
+    it('cycles option focus with ArrowDown/ArrowUp, skipping disabled options, wrapping at the ends', async () => {
+      const wrapper = mount(DropdownButton, {
+        props: { options: mockOptions },
+        attachTo: document.body,
+      })
+
+      await wrapper.get('.mint-dropdown-button__trigger').trigger('keydown', { key: 'ArrowDown' })
+      await wrapper.vm.$nextTick()
+
+      const options = wrapper.findAll('.mint-dropdown-button__option')
+      const menu = wrapper.get('.mint-dropdown-button__menu')
+
+      expect(document.activeElement).toBe(options[0].element)
+
+      // Option C is disabled and excluded from the navigable set entirely.
+      await menu.trigger('keydown', { key: 'ArrowDown' })
+      expect(document.activeElement).toBe(options[1].element)
+
+      await menu.trigger('keydown', { key: 'ArrowDown' })
+      expect(document.activeElement).toBe(options[0].element)
+
+      await menu.trigger('keydown', { key: 'ArrowUp' })
+      expect(document.activeElement).toBe(options[1].element)
+
+      wrapper.unmount()
+    })
+
+    it('jumps to the first option on Home and the last on End', async () => {
+      const wrapper = mount(DropdownButton, {
+        props: { options: mockOptions },
+        attachTo: document.body,
+      })
+
+      await wrapper.get('.mint-dropdown-button__trigger').trigger('keydown', { key: 'ArrowDown' })
+      await wrapper.vm.$nextTick()
+
+      const options = wrapper.findAll('.mint-dropdown-button__option')
+      const menu = wrapper.get('.mint-dropdown-button__menu')
+
+      await menu.trigger('keydown', { key: 'End' })
+      expect(document.activeElement).toBe(options[1].element)
+
+      await menu.trigger('keydown', { key: 'Home' })
+      expect(document.activeElement).toBe(options[0].element)
+
+      wrapper.unmount()
+    })
+
+    it('selects the focused option on Enter', async () => {
+      const wrapper = mount(DropdownButton, {
+        props: { options: mockOptions },
+        attachTo: document.body,
+      })
+
+      await wrapper.get('.mint-dropdown-button__trigger').trigger('keydown', { key: 'ArrowDown' })
+      await wrapper.vm.$nextTick()
+      await wrapper.get('.mint-dropdown-button__option').trigger('keydown', { key: 'Enter' })
+
+      expect(wrapper.emitted('update:modelValue')?.[0]).toEqual(['a'])
+      expect(wrapper.find('.mint-dropdown-button__menu').exists()).toBe(false)
+
+      wrapper.unmount()
+    })
+
+    it('closes on Escape and returns focus to the trigger', async () => {
+      const wrapper = mount(DropdownButton, {
+        props: { options: mockOptions },
+        attachTo: document.body,
+      })
+
+      const trigger = wrapper.get('.mint-dropdown-button__trigger')
+      await trigger.trigger('keydown', { key: 'ArrowDown' })
+      await wrapper.vm.$nextTick()
+
+      await wrapper.get('.mint-dropdown-button__menu').trigger('keydown', { key: 'Escape' })
+      await wrapper.vm.$nextTick()
+
+      expect(wrapper.find('.mint-dropdown-button__menu').exists()).toBe(false)
+      expect(document.activeElement).toBe(trigger.element)
+
+      wrapper.unmount()
+    })
+
+    it('closes on Tab without forcing focus', async () => {
+      const wrapper = mount(DropdownButton, {
+        props: { options: mockOptions },
+        attachTo: document.body,
+      })
+
+      await wrapper.get('.mint-dropdown-button__trigger').trigger('keydown', { key: 'ArrowDown' })
+      await wrapper.vm.$nextTick()
+
+      await wrapper.get('.mint-dropdown-button__menu').trigger('keydown', { key: 'Tab' })
+      await wrapper.vm.$nextTick()
+
+      expect(wrapper.find('.mint-dropdown-button__menu').exists()).toBe(false)
+
+      wrapper.unmount()
+    })
+  })
+
   describe('edge cases', () => {
     it('should handle empty options array', () => {
       const wrapper = mount(DropdownButton, {

package/src/__tests__/components/PluginWorkspaceView.internal.test.ts

@@ -0,0 +1,230 @@
+import { mount } from '@vue/test-utils'
+import { computed, h, nextTick } from 'vue'
+import { createPinia } from 'pinia'
+import { describe, expect, it, vi } from 'vitest'
+import AppLayout from '../../components/AppLayout.vue'
+import AppSidebar from '../../components/AppSidebar.vue'
+import AppTopBar from '../../components/AppTopBar.vue'
+import PluginWorkspaceView from '../../components/PluginWorkspaceView.vue'
+import WorkspaceControlsInternal from '../../components/internal/WorkspaceControlsInternal.vue'
+import WorkspaceShellInternal from '../../components/internal/WorkspaceShellInternal.vue'
+import WorkspaceSidebarInternal from '../../components/internal/WorkspaceSidebarInternal.vue'
+import type { PillNavItem, SidebarToolSection } from '../../types'
+
+vi.mock('../../composables/usePlatformContext', () => ({
+  usePlatformContext: vi.fn(() => ({
+    isIntegrated: computed(() => false),
+    context: { value: { isIntegrated: false, theme: 'system' } },
+    plugin: computed(() => undefined),
+    user: computed(() => undefined),
+    theme: computed(() => 'system' as const),
+    features: computed(() => undefined),
+    navigate: vi.fn(),
+    notify: vi.fn(),
+    sendToPlatform: vi.fn(),
+  })),
+}))
+
+vi.mock('../../composables/useTheme', () => ({
+  useTheme: vi.fn(() => ({
+    isDark: computed(() => false),
+    theme: computed(() => 'light'),
+    toggleTheme: vi.fn(),
+  })),
+}))
+
+const pillNav: PillNavItem[] = [
+  { id: 'data', label: 'Data' },
+  { id: 'results', label: 'Results' },
+]
+
+const panels: Record<string, SidebarToolSection[]> = {
+  data: [
+    { id: 'import', label: 'Import', defaultOpen: true },
+  ],
+  results: [
+    { id: 'display', label: 'Display', defaultOpen: true },
+  ],
+}
+
+interface WorkspaceSlotProps {
+  activeView: string
+  setActiveView: (viewId: string) => void
+}
+
+const globalOptions = {
+  plugins: [createPinia()],
+  stubs: {
+    'router-link': {
+      props: ['to', 'custom'],
+      template: `
+        <slot
+          v-if="custom"
+          :href="typeof to === 'string' ? to : '#'"
+          :navigate="() => {}"
+        />
+        <a v-else :href="typeof to === 'string' ? to : '#'"><slot /></a>
+      `,
+    },
+    BaseModal: {
+      template: '<div><slot /></div>',
+    },
+  },
+}
+
+describe('PluginWorkspaceView internal split', () => {
+  it('renders through WorkspaceShellInternal, WorkspaceSidebarInternal and WorkspaceControlsInternal', () => {
+    const wrapper = mount(PluginWorkspaceView, {
+      props: {
+        title: 'MS Uploader',
+        subtitle: 'Import and visualize',
+        pillNav,
+        panels,
+        sidebarTitle: 'Tools',
+        sidebarSubtitle: 'Current file',
+      },
+      slots: {
+        actions: () => h('button', { 'data-test': 'topbar-action' }, 'Run'),
+        'section-import': () => h('button', { 'data-test': 'import-action' }, 'Upload'),
+        default: ({ activeView }: WorkspaceSlotProps) => h('main', { 'data-test': 'content' }, activeView),
+      },
+      global: globalOptions,
+    })
+
+    // The public adapter renders its three internal pieces...
+    expect(wrapper.findComponent(WorkspaceShellInternal).exists()).toBe(true)
+    expect(wrapper.findComponent(WorkspaceSidebarInternal).exists()).toBe(true)
+    expect(wrapper.findComponent(WorkspaceControlsInternal).exists()).toBe(true)
+
+    // ...each of which wraps the same underlying SDK components with the same DOM output
+    // the pre-split component produced.
+    expect(wrapper.findComponent(AppLayout).props()).toMatchObject({
+      floating: true,
+      responsiveSidebar: true,
+      sidebarPosition: 'left',
+    })
+    expect(wrapper.findComponent(AppTopBar).props()).toMatchObject({
+      title: 'MS Uploader',
+      subtitle: 'Import and visualize',
+      pillNav,
+      currentPillId: 'data',
+    })
+    expect(wrapper.findComponent(AppSidebar).props()).toMatchObject({
+      panels,
+      activeView: 'data',
+      title: 'Tools',
+      subtitle: 'Current file',
+      variant: 'analysis',
+      floating: false,
+      dense: true,
+    })
+    expect(wrapper.get('[data-test="topbar-action"]').text()).toBe('Run')
+    expect(wrapper.get('[data-test="import-action"]').text()).toBe('Upload')
+    expect(wrapper.get('[data-test="content"]').text()).toBe('data')
+
+    // WorkspaceControlsInternal receives exactly the scoped-slot payload the default slot sees.
+    expect(wrapper.findComponent(WorkspaceControlsInternal).props('controls')).toMatchObject({
+      activeView: 'data',
+      values: {},
+    })
+  })
+
+  it('keeps topbar navigation and sidebar panels synchronized through the internal split', async () => {
+    const wrapper = mount(PluginWorkspaceView, {
+      props: {
+        title: 'Analysis',
+        pillNav,
+        panels,
+      },
+      slots: {
+        default: ({ activeView }: WorkspaceSlotProps) => h('main', { 'data-test': 'content' }, activeView),
+      },
+      global: globalOptions,
+    })
+
+    wrapper.findComponent(AppTopBar).vm.$emit('pill-select', { id: 'results', label: 'Results' })
+    await nextTick()
+
+    expect(wrapper.findComponent(AppTopBar).props('currentPillId')).toBe('results')
+    expect(wrapper.findComponent(AppSidebar).props('activeView')).toBe('results')
+    expect(wrapper.findComponent(WorkspaceSidebarInternal).props('sidebar')).toMatchObject({ activeView: 'results' })
+    expect(wrapper.get('[data-test="content"]').text()).toBe('results')
+    expect(wrapper.emitted('update:activeView')).toEqual([['results']])
+    expect(wrapper.emitted('pill-select')).toEqual([[{ id: 'results', label: 'Results' }]])
+  })
+
+  it('relays sidebar collapse, toggle, and form events unchanged through WorkspaceSidebarInternal', async () => {
+    const wrapper = mount(PluginWorkspaceView, {
+      props: {
+        title: 'Analysis',
+        panels,
+        forms: {
+          data: { sections: [] },
+        },
+      },
+      global: globalOptions,
+    })
+
+    const sidebar = wrapper.findComponent(AppSidebar)
+    sidebar.vm.$emit('update:collapsed', true)
+    sidebar.vm.$emit('update:toggle', 'import', false)
+    sidebar.vm.$emit('section-action', 'import', 'refresh')
+    sidebar.vm.$emit('form-submit', 'data', { value: 1 })
+    sidebar.vm.$emit('form-cancel', 'data')
+    await nextTick()
+
+    expect(wrapper.emitted('update:sidebarCollapsed')).toEqual([[true]])
+    expect(wrapper.emitted('update:toggle')).toEqual([['import', false]])
+    expect(wrapper.emitted('section-action')).toEqual([['import', 'refresh']])
+    expect(wrapper.emitted('form-submit')).toEqual([['data', { value: 1 }]])
+    expect(wrapper.emitted('form-cancel')).toEqual([['data']])
+  })
+
+  it('can render without a sidebar surface, omitting WorkspaceSidebarInternal entirely', () => {
+    const wrapper = mount(PluginWorkspaceView, {
+      props: {
+        title: 'Simple Plugin',
+        showSidebar: false,
+      },
+      slots: {
+        default: () => h('main', { 'data-test': 'content' }, 'Ready'),
+      },
+      global: globalOptions,
+    })
+
+    expect(wrapper.findComponent(WorkspaceSidebarInternal).exists()).toBe(false)
+    expect(wrapper.findComponent(AppSidebar).exists()).toBe(false)
+    expect(wrapper.findComponent(AppTopBar).props('title')).toBe('Simple Plugin')
+    expect(wrapper.get('[data-test="content"]').text()).toBe('Ready')
+  })
+
+  it('lets a consumer-supplied sidebar slot override WorkspaceSidebarInternal', () => {
+    const wrapper = mount(PluginWorkspaceView, {
+      props: {
+        title: 'Custom Sidebar',
+        panels,
+      },
+      slots: {
+        sidebar: () => h('aside', { 'data-test': 'custom-sidebar' }, 'Custom'),
+      },
+      global: globalOptions,
+    })
+
+    expect(wrapper.findComponent(WorkspaceSidebarInternal).exists()).toBe(false)
+    expect(wrapper.findComponent(AppSidebar).exists()).toBe(false)
+    expect(wrapper.get('[data-test="custom-sidebar"]').text()).toBe('Custom')
+  })
+
+  it('lets a consumer-supplied topbar slot override WorkspaceShellInternal default AppTopBar rendering', () => {
+    const wrapper = mount(PluginWorkspaceView, {
+      props: { title: 'Custom Top Bar' },
+      slots: {
+        topbar: () => h('header', { 'data-test': 'custom-topbar' }, 'Custom'),
+      },
+      global: globalOptions,
+    })
+
+    expect(wrapper.findComponent(AppTopBar).exists()).toBe(false)
+    expect(wrapper.get('[data-test="custom-topbar"]').text()).toBe('Custom')
+  })
+})