@morscherlab/mint-sdk 1.1.5 → 1.1.7

package/src/components/ExperimentSelectorModal.vue

@@ -1,5 +1,12 @@
 <script setup lang="ts">
-/** Modal for searching and selecting an experiment from the platform list with filters and keyboard nav. */
+/**
+ * Modal for searching and selecting an experiment from the platform list with filters and keyboard nav.
+ *
+ * @example Recommended
+ * ```vue
+ * <ExperimentSelectorModal v-model="open" :allowed-experiment-types="['mass-spectrometry']" />
+ * ```
+ */
 import { ref, reactive, computed, watch, nextTick } from 'vue'
 import type { ModalSize, ExperimentSummary, ExperimentFilters } from '../types'
 import { useExperimentSelector } from '../composables/useExperimentSelector'

package/src/components/FormBuilder.vue

@@ -21,6 +21,11 @@
  * - `section:<id>` — replace an entire section body
  * - `section:<id>:after` — inject content after a section
  * - `actions` — replace the default FormActions bar when `showActions` is true
+ *
+ * @example Recommended
+ * ```vue
+ * <FormBuilder v-model="values" :model="formModel" />
+ * ```
  */
 import { ref, computed, watch } from 'vue'
 import type { FormSchema, FormEnhancements, UseFormBuilderReturn } from '../types/form-builder'

package/src/components/GeneratedPluginView.vue

@@ -1,4 +1,12 @@
 <script setup lang="ts">
+/**
+ * Standard generated workspace for a plugin that exposes an SDK job manifest.
+ *
+ * @example Recommended
+ * ```vue
+ * <GeneratedPluginView base-url="/api/peak-qc" />
+ * ```
+ */
 import { computed, onMounted, reactive, ref, watch } from 'vue'
 
 import { generatedJobDefaults, generatedJobFormSchema, normalizeGeneratedJobInput } from '../generated/schema'
@@ -20,11 +28,13 @@ import JobsStatusTray from './JobsStatusTray.vue'
 import LoadingSpinner from './LoadingSpinner.vue'
 import PluginWorkspaceView from './PluginWorkspaceView.vue'
 
-const props = withDefaults(defineProps<{
+interface Props {
   baseUrl: string
   showStandaloneLabel?: boolean
   transport?: GeneratedAnalysisTransport
-}>(), {
+}
+
+const props = withDefaults(defineProps<Props>(), {
   showStandaloneLabel: false,
 })
 

package/src/components/GeneratedResultRenderer.vue

@@ -1,4 +1,12 @@
 <script setup lang="ts">
+/**
+ * Render standardized text, table, image, Plotly, JSON, and artifact job results.
+ *
+ * @example Recommended
+ * ```vue
+ * <GeneratedResultRenderer :result="result" />
+ * ```
+ */
 import { computed } from 'vue'
 
 import type { DataFrameColumn } from '../types'
@@ -7,9 +15,11 @@ import ChartContainer from './ChartContainer.vue'
 import DataFrame from './DataFrame.vue'
 import GeneratedPlotlyResult from './GeneratedPlotlyResult.vue'
 
-const props = defineProps<{
+interface Props {
   result: GeneratedAnalysisResult
-}>()
+}
+
+const props = defineProps<Props>()
 
 const tableColumns = computed<DataFrameColumn[]>(() => {
   if (props.result.kind !== 'table') return []

package/src/components/JobsStatusTray.vue

@@ -1,5 +1,12 @@
 <script setup lang="ts">
-/** Floating, source-driven job status tray for plugin and platform workflows. */
+/**
+ * Floating, source-driven job status tray for plugin and platform workflows.
+ *
+ * @example Recommended
+ * ```vue
+ * <JobsStatusTray :source="jobs" />
+ * ```
+ */
 import { computed, nextTick, ref, toRef, useId } from 'vue'
 
 import {

package/src/components/PluginWorkspaceView.vue

@@ -1,5 +1,14 @@
 <script setup lang="ts">
-/** Standard plugin workspace shell that combines AppLayout, AppTopBar, and AppSidebar with LEAF-style defaults. */
+/**
+ * Standard plugin workspace shell that combines AppLayout, AppTopBar, and AppSidebar with LEAF-style defaults.
+ *
+ * @example Recommended
+ * ```vue
+ * <PluginWorkspaceView title="Analysis" experiment-shell>
+ *   <router-view />
+ * </PluginWorkspaceView>
+ * ```
+ */
 import { computed, useSlots } from 'vue'
 import type {
   AccountMenuItem,

package/src/components/SettingsModal.vue

@@ -17,6 +17,11 @@
  *
  * Layout: `horizontal` (underline tabs, default) or `vertical` (sidebar rail
  * with optional icons + descriptions, recommended for 5+ groups).
+ *
+ * @example Recommended
+ * ```vue
+ * <SettingsModal v-model="open" v-model:values="values" :model="settingsModel" />
+ * ```
  */
 import { ref, computed, watch } from 'vue'
 import BaseModal from './BaseModal.vue'
@@ -45,6 +50,8 @@ import type {
   ThemeMode,
   ColorPalette,
   TableDensity,
+  ModalLayout,
+  ModalTab,
   SettingsTab,
   SettingsTabInput,
   SettingsModalLayout,
@@ -107,11 +114,6 @@ const { user: platformUser } = usePlatformContext()
 
 const isVertical = computed(() => props.layout === 'vertical')
 
-// Per-instance prefix for ARIA tab/tabpanel id wiring. Stable across renders.
-const uid = `mint-settings-${Math.random().toString(36).slice(2, 9)}`
-const tabId = (id: string) => `${uid}-tab-${id}`
-const panelId = (id: string) => `${uid}-panel-${id}`
-
 const resolvedModel = computed<ControlModelBinding | undefined>(() => {
   return resolveControlModel(props.model)
 })
@@ -223,8 +225,21 @@ const allTabs = computed<SettingsTab[]>(() => {
 
 const activeTab = ref(allTabs.value[0]?.id || APPEARANCE_TAB_ID)
 
-const activeTabMeta = computed<SettingsTab | undefined>(() =>
-  allTabs.value.find((t) => t.id === activeTab.value),
+// BaseModal owns the tab chrome: 'vertical' keeps its public name and maps to
+// the shell rail; horizontal maps to the shell strip (plain when single-tab).
+const baseLayout = computed<ModalLayout>(() => {
+  if (isVertical.value) return 'rail'
+  return allTabs.value.length > 1 ? 'tabs' : 'plain'
+})
+
+const modalTabs = computed<ModalTab[]>(() =>
+  allTabs.value.map((tab) => ({
+    id: tab.id,
+    label: tab.label,
+    icon: tab.icon,
+    description: tab.description,
+    meta: tab.meta,
+  })),
 )
 
 // If the active tab vanishes (group hidden by condition), drop back to the first available.
@@ -278,166 +293,104 @@ function canShowForCurrentUser(item: AccessControlled): boolean {
     :model-value="modelValue"
     :title="title"
     :size="size"
+    :layout="baseLayout"
+    :tabs="modalTabs"
+    :active-tab="activeTab"
+    @update:active-tab="activeTab = $event"
     @update:model-value="emit('update:modelValue', $event)"
     @close="handleClose"
   >
-    <div :class="['mint-settings-modal', `mint-settings-modal--${layout}`]">
+    <!-- Body: the active pane only — tab strip / rail / footer are BaseModal's shell. -->
+    <div class="mint-settings-modal">
       <div
-        v-if="!isVertical && allTabs.length > 1"
-        class="mint-settings-modal__tabs"
+        v-if="isSchemaDriven && activeGroup"
+        class="mint-settings-modal__group-grid"
+        :style="{ '--mint-settings-cols': activeGroup.columns ?? 1 }"
       >
-        <button
-          v-for="tab in allTabs"
-          :key="tab.id"
-          type="button"
-          :class="['mint-settings-modal__tab', { 'mint-settings-modal__tab--active': activeTab === tab.id }]"
-          @click="activeTab = tab.id"
-        >
-          {{ tab.label }}
-        </button>
+        <template v-for="field in activeGroupVisibleFields" :key="field.name">
+          <div :style="field.colSpan ? { gridColumn: `span ${field.colSpan}` } : undefined">
+            <slot
+              :name="`field:${field.name}`"
+              :field="field"
+              :form="builder.form"
+              :field-props="builder.form.getFieldProps(field.name)"
+            >
+              <FormFieldRendererInternal
+                :field="field"
+                :resolved-props="builder.getResolvedFieldProps(field)"
+                :form="builder.form"
+              />
+            </slot>
+          </div>
+        </template>
       </div>
 
-      <div
-        v-else-if="isVertical"
-        class="mint-settings-modal__rail"
-        role="tablist"
-        aria-orientation="vertical"
-        aria-label="Settings sections"
-      >
-        <button
-          v-for="tab in allTabs"
-          :id="tabId(tab.id)"
-          :key="tab.id"
-          type="button"
-          role="tab"
-          :class="['mint-settings-modal__rail-item', { 'mint-settings-modal__rail-item--active': activeTab === tab.id }]"
-          :aria-selected="activeTab === tab.id"
-          :aria-controls="panelId(tab.id)"
-          :tabindex="activeTab === tab.id ? 0 : -1"
-          @click="activeTab = tab.id"
-        >
-          <span class="mint-settings-modal__rail-item-icon" aria-hidden="true">
-            <span v-if="tab.icon" v-html="tab.icon" />
-          </span>
-          <span class="mint-settings-modal__rail-item-text">
-            <span class="mint-settings-modal__rail-item-label">{{ tab.label }}</span>
-            <span v-if="tab.description" class="mint-settings-modal__rail-item-description">
-              {{ tab.description }}
-            </span>
-          </span>
-        </button>
-      </div>
+      <template v-else-if="!isSchemaDriven">
+        <template v-for="tab in manualTabs" :key="tab.id">
+          <div v-show="activeTab === tab.id">
+            <slot :name="`tab-${tab.id}`" />
+          </div>
+        </template>
+      </template>
+
+      <div v-if="showAppearance" v-show="activeTab === APPEARANCE_TAB_ID">
+        <div class="mint-settings-modal__section">
+          <div class="mint-settings-modal__section-label">Theme</div>
+          <div class="mint-settings-modal__option-group">
+            <button
+              v-for="opt in themeOptions"
+              :key="opt.value"
+              type="button"
+              :class="['mint-settings-modal__option-btn', { 'mint-settings-modal__option-btn--active': settings.theme === opt.value }]"
+              @click="settings.theme = opt.value"
+            >
+              {{ opt.label }}
+            </button>
+          </div>
+        </div>
 
-      <!-- Vertical mode wraps content in a tabpanel <section> with a header bar; horizontal mode stays a plain <div>. -->
-      <component
-        :is="isVertical ? 'section' : 'div'"
-        :class="isVertical ? 'mint-settings-modal__pane' : 'mint-settings-modal__content'"
-        :id="isVertical && activeTabMeta ? panelId(activeTabMeta.id) : undefined"
-        :role="isVertical ? 'tabpanel' : undefined"
-        :aria-labelledby="isVertical && activeTabMeta ? tabId(activeTabMeta.id) : undefined"
-        :tabindex="isVertical ? 0 : undefined"
-      >
-        <header
-          v-if="isVertical && activeTabMeta?.label"
-          class="mint-settings-modal__pane-header"
-        >
-          <h4 class="mint-settings-modal__pane-title">{{ activeTabMeta.label }}</h4>
-          <p v-if="activeTabMeta.description" class="mint-settings-modal__pane-subtitle">
-            {{ activeTabMeta.description }}
-          </p>
-        </header>
-
-        <div :class="isVertical ? 'mint-settings-modal__pane-body' : null">
-          <div
-            v-if="isSchemaDriven && activeGroup"
-            class="mint-settings-modal__group-grid"
-            :style="{ '--mint-settings-cols': activeGroup.columns ?? 1 }"
-          >
-            <template v-for="field in activeGroupVisibleFields" :key="field.name">
-              <div :style="field.colSpan ? { gridColumn: `span ${field.colSpan}` } : undefined">
-                <slot
-                  :name="`field:${field.name}`"
-                  :field="field"
-                  :form="builder.form"
-                  :field-props="builder.form.getFieldProps(field.name)"
-                >
-                  <FormFieldRendererInternal
-                    :field="field"
-                    :resolved-props="builder.getResolvedFieldProps(field)"
-                    :form="builder.form"
-                  />
-                </slot>
-              </div>
-            </template>
+        <div class="mint-settings-modal__section">
+          <div class="mint-settings-modal__section-label">Color Palette</div>
+          <div class="mint-settings-modal__option-group">
+            <button
+              v-for="(palette, key) in colorPalettes"
+              :key="key"
+              type="button"
+              :class="['mint-settings-modal__option-btn', { 'mint-settings-modal__option-btn--active': settings.colorPalette === key }]"
+              @click="settings.colorPalette = key as ColorPalette"
+            >
+              {{ palette.name }}
+            </button>
           </div>
+        </div>
 
-          <template v-else-if="!isSchemaDriven">
-            <template v-for="tab in manualTabs" :key="tab.id">
-              <div v-show="activeTab === tab.id">
-                <slot :name="`tab-${tab.id}`" />
-              </div>
-            </template>
-          </template>
-
-          <div v-if="showAppearance" v-show="activeTab === APPEARANCE_TAB_ID">
-            <div class="mint-settings-modal__section">
-              <div class="mint-settings-modal__section-label">Theme</div>
-              <div class="mint-settings-modal__option-group">
-                <button
-                  v-for="opt in themeOptions"
-                  :key="opt.value"
-                  type="button"
-                  :class="['mint-settings-modal__option-btn', { 'mint-settings-modal__option-btn--active': settings.theme === opt.value }]"
-                  @click="settings.theme = opt.value"
-                >
-                  {{ opt.label }}
-                </button>
-              </div>
-            </div>
-
-            <div class="mint-settings-modal__section">
-              <div class="mint-settings-modal__section-label">Color Palette</div>
-              <div class="mint-settings-modal__option-group">
-                <button
-                  v-for="(palette, key) in colorPalettes"
-                  :key="key"
-                  type="button"
-                  :class="['mint-settings-modal__option-btn', { 'mint-settings-modal__option-btn--active': settings.colorPalette === key }]"
-                  @click="settings.colorPalette = key as ColorPalette"
-                >
-                  {{ palette.name }}
-                </button>
-              </div>
-            </div>
-
-            <div class="mint-settings-modal__section">
-              <div class="mint-settings-modal__section-label">Table Density</div>
-              <div class="mint-settings-modal__option-group">
-                <button
-                  v-for="opt in densityOptions"
-                  :key="opt.value"
-                  type="button"
-                  :class="['mint-settings-modal__option-btn', { 'mint-settings-modal__option-btn--active': settings.tableDensity === opt.value }]"
-                  @click="settings.tableDensity = opt.value"
-                >
-                  {{ opt.label }}
-                </button>
-              </div>
-              <p class="mint-settings-modal__note">Adjusts row height in data tables.</p>
-            </div>
-
-            <slot name="appearance" />
+        <div class="mint-settings-modal__section">
+          <div class="mint-settings-modal__section-label">Table Density</div>
+          <div class="mint-settings-modal__option-group">
+            <button
+              v-for="opt in densityOptions"
+              :key="opt.value"
+              type="button"
+              :class="['mint-settings-modal__option-btn', { 'mint-settings-modal__option-btn--active': settings.tableDensity === opt.value }]"
+              @click="settings.tableDensity = opt.value"
+            >
+              {{ opt.label }}
+            </button>
           </div>
+          <p class="mint-settings-modal__note">Adjusts row height in data tables.</p>
         </div>
-      </component>
+
+        <slot name="appearance" />
+      </div>
     </div>
-    <div v-if="$slots.footer" class="mint-settings-modal__footer">
+
+    <template v-if="$slots.footer" #footer>
       <slot
         name="footer"
         :values="builder.form.data"
         :close="handleClose"
       />
-    </div>
+    </template>
   </BaseModal>
 </template>
 

package/src/components/index.ts

@@ -30,6 +30,7 @@ export { default as AlertBox } from './AlertBox.vue'
 export { default as AppToastContainer } from './AppToastContainer.vue'
 
 // Action components
+export { default as ActionMenu } from './ActionMenu.vue'
 export { default as IconButton } from './IconButton.vue'
 export { default as ThemeToggle } from './ThemeToggle.vue'
 

package/src/composables/controlSchemaDoseDesign.ts

@@ -86,7 +86,14 @@ export function defineWellPlateDoseComponentBindings<TValues extends Record<stri
   ]
 }
 
-/** Return a complete ControlWorkspaceView model for WellPlate + DoseCalculator dose design. */
+/**
+ * Return a complete ControlWorkspaceView model for WellPlate + DoseCalculator dose design.
+ *
+ * @example Recommended
+ * ```ts
+ * const workspaceModel = defineDoseDesignControlModel({ selectedWells: ['A1', 'A2'] })
+ * ```
+ */
 export function defineDoseDesignControlModel(
   options: DoseDesignControlModelOptions = {},
 ): ControlModelBinding {

package/src/composables/controlSchemaModel.ts

@@ -33,7 +33,16 @@ export function resolveControlModel(
   return isControlModelBinding(model) ? model : defineControlModel(model)
 }
 
-/** Create a complete workspace component binding from a simple controls data model for ControlWorkspaceView, generated forms, and sidebars. */
+/**
+ * Create a complete workspace component binding from a simple controls data model for ControlWorkspaceView, generated forms, and sidebars.
+ *
+ * @example Recommended
+ * ```ts
+ * const workspaceModel = defineControlModel({
+ *   controls: { threshold: { type: 'number', default: 0.05 } },
+ * })
+ * ```
+ */
 export function defineControlModel(model: ControlModel): ControlModelBinding {
   const {
     controls: rootControls,

package/src/composables/useAnalysisArtifacts.ts

@@ -85,7 +85,15 @@ export interface UseAnalysisArtifactsReturn {
   clear: () => void
 }
 
-/** Lists and manages analysis artifacts through the user-facing platform API. */
+/**
+ * Lists and manages analysis artifacts through the user-facing platform API.
+ *
+ * @example Recommended
+ * ```ts
+ * const artifacts = useAnalysisArtifacts({ pluginId: 'LEAF' })
+ * await artifacts.list()
+ * ```
+ */
 export function useAnalysisArtifacts(
   options: UseAnalysisArtifactsOptions = {},
 ): UseAnalysisArtifactsReturn {

package/src/composables/useAppExperiment.ts

@@ -93,6 +93,13 @@ export const APP_EXPERIMENT_KEY: InjectionKey<AppExperimentState> = Symbol('app-
  * The composable never writes a selection of its own. `ExperimentSelectorModal`
  * commits to the store and this reads back, so a displayed name can only ever
  * have come from the platform.
+ *
+ * @example Recommended
+ * ```ts
+ * const appExperiment = useAppExperiment({
+ *   onSelect: experiment => loadExperiment(experiment.id),
+ * })
+ * ```
  */
 export function useAppExperiment(options: UseAppExperimentOptions = {}): UseAppExperimentReturn {
   const store = useExperimentStore()

package/src/composables/useBioTemplatePackWorkspace.ts

@@ -79,7 +79,15 @@ export interface UseBioTemplatePackWorkspaceReturn {
   requireCurrentExperimentId: UseTemplateCollectionReturn['requireCurrentExperimentId']
 }
 
-/** Create a complete workspace for a curated biology template pack from a single pack id. */
+/**
+ * Create a complete workspace for a curated biology template pack from a single pack id.
+ *
+ * @example Recommended
+ * ```ts
+ * const pack = useBioTemplatePackWorkspace('cell-culture-screen')
+ * await pack.loadCurrent()
+ * ```
+ */
 export function useBioTemplatePackWorkspace(
   packId: TemplatePackId | string,
   options: UseBioTemplatePackWorkspaceOptions = {},

package/src/composables/useControlWorkspace.ts

@@ -44,7 +44,15 @@ import type {
   UseControlWorkspaceReturn,
 } from './controlSchemaTypes'
 
-/** Prepare shared reactive values plus AppTopBar/AppSidebar/FormBuilder bindings from one simple controls data model. */
+/**
+ * Prepare shared reactive values plus AppTopBar/AppSidebar/FormBuilder bindings from one simple controls data model.
+ *
+ * @example Recommended
+ * ```ts
+ * const workspace = useControlWorkspace(workspaceModel)
+ * const { form, sidebar, topBar } = workspace.bindings
+ * ```
+ */
 export function useControlWorkspace<TControls extends ControlSchema>(
   controlsOrModel: TControls | (ControlModelBinding & { controls: TControls }),
   options: ControlWorkspaceOptions = {},

package/src/composables/useGeneratedAnalysis.ts

@@ -161,6 +161,15 @@ export function useGeneratedAnalysis(
   return createPluginJobs(options, '/generated/manifest')
 }
 
+/**
+ * Connect a custom plugin frontend to the SDK-owned job lifecycle.
+ *
+ * @example Recommended
+ * ```ts
+ * const jobs = usePluginJobs({ baseUrl: '/api/leaf/jobs' })
+ * await jobs.initialize()
+ * ```
+ */
 export function usePluginJobs(
   options: UsePluginJobsOptions,
 ): UsePluginJobsReturn {

package/src/styles/components/action-menu.css

@@ -0,0 +1,59 @@
+/* ActionMenu — compact square trigger with a teleported, viewport-safe menu. */
+
+.mint-action-menu {
+  display: inline-flex;
+  flex-shrink: 0;
+}
+
+.mint-action-menu__trigger-icon {
+  width: 1rem;
+  height: 1rem;
+}
+
+.mint-action-menu__panel {
+  position: fixed;
+  z-index: 1000;
+  display: flex;
+  min-width: 10rem;
+  max-width: min(18rem, calc(100vw - 1rem));
+  flex-direction: column;
+  padding: 0.25rem;
+  border: 1px solid var(--border-color);
+  border-radius: var(--radius-md);
+  background: var(--bg-secondary);
+  box-shadow: var(--shadow-md);
+}
+
+.mint-action-menu__item {
+  display: flex;
+  width: 100%;
+  align-items: center;
+  padding: 0.4375rem 0.625rem;
+  border: 0;
+  border-radius: 0.375rem;
+  background: transparent;
+  color: var(--text-primary);
+  font-family: inherit;
+  font-size: 0.78125rem;
+  line-height: 1.25;
+  text-align: left;
+  text-decoration: none;
+  cursor: pointer;
+  transition: background-color var(--mint-transition);
+}
+
+.mint-action-menu__item:hover:not(:disabled),
+.mint-action-menu__item:focus-visible {
+  outline: none;
+  background: var(--bg-hover);
+}
+
+.mint-action-menu__item--danger {
+  color: var(--mint-error);
+}
+
+.mint-action-menu__item:disabled {
+  color: var(--text-muted);
+  cursor: not-allowed;
+  opacity: var(--mint-disabled-opacity);
+}

package/src/styles/components/icon-button.css

@@ -2,6 +2,7 @@
 
 .mint-icon-button {
   display: inline-flex;
+  flex-shrink: 0;
   align-items: center;
   justify-content: center;
   border-radius: var(--radius-md);
@@ -126,18 +127,21 @@
 
 /* Sizes */
 .mint-icon-button--sm {
+  width: var(--form-height-sm);
+  height: var(--form-height-sm);
   padding: 0.375rem;
-  min-height: var(--form-height-sm);
 }
 
 .mint-icon-button--md {
+  width: var(--form-height-md);
+  height: var(--form-height-md);
   padding: 0.5rem;
-  min-height: var(--form-height-md);
 }
 
 .mint-icon-button--lg {
+  width: var(--form-height-lg);
+  height: var(--form-height-lg);
   padding: 0.75rem;
-  min-height: var(--form-height-lg);
 }
 
 .mint-icon-button__icon--sm,