@morscherlab/mint-sdk 1.1.5 → 1.1.7

package/src/components/ActionMenu.vue

@@ -0,0 +1,209 @@
+<script setup lang="ts">
+/** Compact overflow actions with an IconButton trigger and a viewport-safe teleported menu. */
+import { computePosition, flip, offset, shift } from '@floating-ui/dom'
+import { Ellipsis } from 'lucide-vue-next'
+import { nextTick, onBeforeUnmount, ref } from 'vue'
+import type { ActionMenuItem } from '../types/components'
+import IconButton from './IconButton.vue'
+
+interface Props {
+  label: string
+  items: ActionMenuItem[]
+  disabled?: boolean
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  disabled: false,
+})
+
+const emit = defineEmits<{
+  select: [item: ActionMenuItem]
+  open: []
+  close: []
+}>()
+
+const isOpen = ref(false)
+const triggerRootRef = ref<HTMLElement | null>(null)
+const panelRef = ref<HTMLElement | null>(null)
+const panelStyle = ref<Record<string, string>>({ visibility: 'hidden' })
+
+function triggerElement(): HTMLButtonElement | null {
+  return triggerRootRef.value?.querySelector('button') ?? null
+}
+
+function menuItems(): HTMLElement[] {
+  if (!panelRef.value) return []
+  return Array.from(
+    panelRef.value.querySelectorAll<HTMLElement>('.mint-action-menu__item:not(:disabled)'),
+  )
+}
+
+async function positionPanel() {
+  const trigger = triggerElement()
+  const panel = panelRef.value
+  if (!trigger || !panel) return
+
+  const position = await computePosition(trigger, panel, {
+    placement: 'bottom-end',
+    strategy: 'fixed',
+    middleware: [
+      offset(4),
+      flip(),
+      shift({ padding: 8 }),
+    ],
+  })
+  panelStyle.value = {
+    left: `${position.x}px`,
+    top: `${position.y}px`,
+    visibility: 'visible',
+  }
+}
+
+function addGlobalListeners() {
+  document.addEventListener('pointerdown', handleDocumentPointerDown, true)
+  window.addEventListener('resize', handleViewportChange)
+  window.addEventListener('scroll', handleViewportChange, true)
+}
+
+function removeGlobalListeners() {
+  document.removeEventListener('pointerdown', handleDocumentPointerDown, true)
+  window.removeEventListener('resize', handleViewportChange)
+  window.removeEventListener('scroll', handleViewportChange, true)
+}
+
+async function openMenu() {
+  if (props.disabled || isOpen.value) return
+  panelStyle.value = { visibility: 'hidden' }
+  isOpen.value = true
+  emit('open')
+  addGlobalListeners()
+  await nextTick()
+  await positionPanel()
+  menuItems()[0]?.focus()
+}
+
+function closeMenu(returnFocus = false) {
+  if (!isOpen.value) return
+  isOpen.value = false
+  removeGlobalListeners()
+  emit('close')
+  if (returnFocus) {
+    nextTick(() => triggerElement()?.focus())
+  }
+}
+
+function toggleMenu() {
+  if (isOpen.value) closeMenu()
+  else void openMenu()
+}
+
+function handleSelect(item: ActionMenuItem) {
+  if (item.disabled) return
+  emit('select', item)
+  closeMenu()
+}
+
+function handleDocumentPointerDown(event: PointerEvent) {
+  const target = event.target
+  if (!(target instanceof Node)) return
+  if (triggerRootRef.value?.contains(target) || panelRef.value?.contains(target)) return
+  closeMenu()
+}
+
+function handleViewportChange() {
+  closeMenu()
+}
+
+function handleMenuKeydown(event: KeyboardEvent) {
+  const items = menuItems()
+  const currentIndex = items.indexOf(document.activeElement as HTMLElement)
+
+  if (event.key === 'Escape') {
+    event.preventDefault()
+    closeMenu(true)
+    return
+  }
+  if (event.key === 'Tab') {
+    closeMenu()
+    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()
+}
+
+onBeforeUnmount(removeGlobalListeners)
+</script>
+
+<template>
+  <span ref="triggerRootRef" class="mint-action-menu">
+    <IconButton
+      variant="secondary"
+      size="sm"
+      :label="label"
+      :disabled="disabled"
+      aria-haspopup="menu"
+      :aria-expanded="isOpen"
+      @click="toggleMenu"
+    >
+      <Ellipsis
+        class="mint-action-menu__trigger-icon"
+        :size="16"
+        :stroke-width="2"
+        aria-hidden="true"
+      />
+    </IconButton>
+  </span>
+
+  <Teleport to="body">
+    <div
+      v-if="isOpen"
+      ref="panelRef"
+      class="mint-action-menu__panel"
+      :style="panelStyle"
+      role="menu"
+      @keydown="handleMenuKeydown"
+    >
+      <template v-for="item in items" :key="item.id">
+        <a
+          v-if="item.href !== undefined && !item.disabled"
+          :href="item.href"
+          :target="item.target"
+          :rel="item.target === '_blank' ? 'noopener noreferrer' : undefined"
+          :class="['mint-action-menu__item', { 'mint-action-menu__item--danger': item.danger }]"
+          role="menuitem"
+          @click="handleSelect(item)"
+        >
+          {{ item.label }}
+        </a>
+        <button
+          v-else
+          type="button"
+          :class="['mint-action-menu__item', { 'mint-action-menu__item--danger': item.danger }]"
+          role="menuitem"
+          :disabled="item.disabled"
+          @click="handleSelect(item)"
+        >
+          {{ item.label }}
+        </button>
+      </template>
+    </div>
+  </Teleport>
+</template>
+
+<style>
+@import '../styles/components/action-menu.css';
+</style>

package/src/components/AppSidebar.vue

@@ -9,20 +9,9 @@
  * When activeView is omitted, the first non-empty panel view is selected.
  * When no view has matching panels, the sidebar hides entirely.
  *
- * @example
+ * @example Recommended
  * ```vue
- * <AppSidebar :panels="toolPanels" :active-view="activeTab">
- *   <template #section-parameters>
- *     <BaseSlider v-model="threshold" label="Threshold" />
- *   </template>
- *   <template #section-display>
- *     <BaseToggle v-model="showOutliers" label="Show outliers" />
- *   </template>
- *   <template #header>Plugin Tools</template>
- * </AppSidebar>
- *
- * <!-- Direct schema-driven controls -->
- * <AppSidebar :controls="controls" :active-view="activeTab" v-model="values" />
+ * <AppSidebar v-model="values" :model="sidebarModel" />
  * ```
  */
 import { computed, ref, useSlots, type Slots } from 'vue'

package/src/components/ArtifactSelectorModal.vue

@@ -1,5 +1,12 @@
 <script setup lang="ts">
-/** Modal for browsing and selecting an analysis artifact of an experiment, with filters and keyboard nav. */
+/**
+ * Modal for browsing and selecting an analysis artifact of an experiment, with filters and keyboard nav.
+ *
+ * @example Recommended
+ * ```vue
+ * <ArtifactSelectorModal v-model="open" :experiment-id="experimentId" @select="selectArtifact" />
+ * ```
+ */
 import { computed, ref, watch, nextTick } from 'vue'
 import type { ModalSize } from '../types'
 import type {

package/src/components/BaseModal.story.vue

@@ -2,7 +2,7 @@
 import { ref } from 'vue'
 import BaseModal from './BaseModal.vue'
 import BaseButton from './BaseButton.vue'
-import type { ModalSize } from '../types'
+import type { ModalSize, ModalTab } from '../types'
 
 const modalSizes: ModalSize[] = ['sm', 'md', 'lg', 'xl', 'full']
 const galleryOpen = ref<Record<string, boolean>>({
@@ -19,6 +19,28 @@ const refreshOpen = ref(false)
 const subtitleOpen = ref(false)
 const drawerOpen = ref(false)
 const sheetOpen = ref(false)
+
+// ---- layout="tabs": shell-level tab strip (2–4 sections) ----
+const tabsOpen = ref(false)
+const tabsActive = ref('processing')
+const stripTabs: ModalTab[] = [
+  { id: 'processing', label: 'Processing', meta: '6' },
+  { id: 'peaks', label: 'Peak detection', meta: '9' },
+  { id: 'correction', label: 'Correction', meta: '4' },
+  { id: 'appearance', label: 'Appearance' },
+]
+
+// ---- layout="rail": shell-level rail (5+ sections) ----
+const railOpen = ref(false)
+const railActive = ref('security')
+const railTabs: ModalTab[] = [
+  { id: 'profile', label: 'Profile', description: 'Name, display name, and email', icon: 'M20 21a8 8 0 0 0-16 0M12 11a4 4 0 1 0 0-8 4 4 0 0 0 0 8' },
+  { id: 'password', label: 'Password', description: 'Change your sign-in password', icon: 'M6 11h12v10H6zM9 11V7a3 3 0 0 1 6 0v4' },
+  { id: 'security', label: 'Security', meta: '2', description: 'Passkeys and institutional sign-in', icon: 'm12 3 8 4.5v9L12 21l-8-4.5v-9L12 3Z' },
+  { id: 'notifications', label: 'Notifications', description: 'Email and in-app alerts', icon: 'M18 8a6 6 0 1 0-12 0c0 7-3 8-3 8h18s-3-1-3-8M13.7 21a2 2 0 0 1-3.4 0' },
+  { id: 'tokens', label: 'API tokens', meta: '3', description: 'Programmatic access keys', icon: 'M15 7h3a4 4 0 0 1 0 8h-3M9 15H6a4 4 0 0 1 0-8h3M8 11h8' },
+  { id: 'appearance', label: 'Appearance', description: 'Theme and density', icon: 'M12 3a9 9 0 1 0 0 18 3 3 0 0 0 0-6 3 3 0 0 1 0-6 3 3 0 0 0 0-6M7 10h.01M12 7h.01M17 10h.01' },
+]
 </script>
 
 <template>
@@ -225,5 +247,89 @@ const sheetOpen = ref(false)
         </template>
       </BaseModal>
     </Variant>
+
+    <Variant title="Tabs layout — shell-level strip">
+      <div style="padding: 2rem;">
+        <BaseButton variant="primary" @click="tabsOpen = true">
+          Open tabbed modal
+        </BaseButton>
+        <p style="margin: 1rem 0 0; font-size: 0.8125rem; color: var(--text-muted);">
+          The strip is a shell region between header and body: flush with the modal edges,
+          it never scrolls with the content, and the body keeps one fixed height across tabs.
+          Arrow keys move between tabs. For 2–4 sections; use the rail beyond that.
+        </p>
+      </div>
+
+      <BaseModal
+        v-model="tabsOpen"
+        v-model:active-tab="tabsActive"
+        layout="tabs"
+        :tabs="stripTabs"
+        size="lg"
+        title="Isotope Tracer Analysis — settings"
+        subtitle="Plugin 2.4 · applies to this workspace"
+      >
+        <div style="display: flex; flex-direction: column; gap: 0.875rem;">
+          <p style="margin: 0; font-size: 0.8125rem; color: var(--text-secondary);">
+            Active tab: <strong style="color: var(--text-primary);">{{ tabsActive }}</strong> —
+            pane content swaps here while the card height stays put.
+          </p>
+          <div v-for="n in 4" :key="n" style="display: flex; align-items: center; gap: 0.875rem; padding: 0.6875rem 0; border-bottom: 1px solid var(--border-light);">
+            <span style="width: 9.5rem; flex-shrink: 0; font-size: 0.6875rem; font-weight: 600; letter-spacing: 0.05em; text-transform: uppercase; color: var(--text-muted);">Setting {{ n }}</span>
+            <span style="flex: 1; padding: 0.375rem 0.625rem; border: 1px solid var(--border-color); border-radius: 0.4375rem; background: var(--bg-secondary); font-family: var(--font-mono); font-size: 0.8125rem;">value {{ n }}</span>
+          </div>
+        </div>
+        <template #footer>
+          <BaseButton variant="secondary" @click="tabsOpen = false">Cancel</BaseButton>
+          <BaseButton variant="primary" @click="tabsOpen = false">Save settings</BaseButton>
+        </template>
+      </BaseModal>
+    </Variant>
+
+    <Variant title="Rail layout — shell-level sidebar">
+      <div style="padding: 2rem;">
+        <BaseButton variant="primary" @click="railOpen = true">
+          Open rail modal
+        </BaseButton>
+        <p style="margin: 1rem 0 0; font-size: 0.8125rem; color: var(--text-muted);">
+          For 5+ sections, or sections needing descriptions/counts. The rail is a real shell
+          column (no negative-margin bleed), scrolls independently of the pane, and the pane
+          names the active section in its own header. Collapses to the strip under 640px.
+        </p>
+      </div>
+
+      <BaseModal
+        v-model="railOpen"
+        v-model:active-tab="railActive"
+        layout="rail"
+        :tabs="railTabs"
+        size="lg"
+        title="Your account"
+        subtitle="R. Keller · rkeller · Admin"
+        close-on-overlay
+      >
+        <template #rail-footer>
+          <button
+            type="button"
+            style="display: flex; align-items: center; gap: 0.5rem; margin-top: auto; padding: 0.4375rem 0.625rem; border: none; border-radius: 0.4375rem; background: transparent; color: var(--mint-error); font-family: inherit; font-size: 0.78125rem; font-weight: 500; text-align: left; cursor: pointer;"
+            @click="railOpen = false"
+          >
+            Log out
+          </button>
+        </template>
+
+        <div style="display: flex; flex-direction: column;">
+          <div v-for="n in 3" :key="n" style="display: flex; align-items: center; gap: 0.6875rem; padding: 0.5625rem 0; border-bottom: 1px solid var(--border-light);">
+            <span style="flex: 1; font-size: 0.8125rem; color: var(--text-primary);">{{ railActive }} row {{ n }}</span>
+            <span style="font-size: 0.71875rem; color: var(--text-muted);">detail</span>
+          </div>
+        </div>
+        <template #footer>
+          <span style="font-size: 0.75rem; color: var(--text-muted);">Changes apply immediately</span>
+          <div style="flex: 1;" />
+          <BaseButton variant="secondary" @click="railOpen = false">Close</BaseButton>
+        </template>
+      </BaseModal>
+    </Variant>
   </Story>
 </template>

package/src/components/BaseModal.vue

@@ -1,7 +1,7 @@
 <script setup lang="ts">
-/** Modal dialog with backdrop, focus trap, Escape-to-close, and configurable size/variant. */
-import { ref, watch, nextTick, onUnmounted } from 'vue'
-import type { ModalSize, ModalVariant } from '../types'
+/** Modal dialog with backdrop, focus trap, Escape-to-close, and configurable size/variant/layout. */
+import { computed, ref, watch, nextTick, onUnmounted, type ComponentPublicInstance } from 'vue'
+import type { ModalLayout, ModalSize, ModalTab, ModalVariant } from '../types'
 import { useEventListener } from '../composables/useEventListener'
 
 interface Props {
@@ -13,6 +13,16 @@ interface Props {
   closable?: boolean
   closeOnOverlay?: boolean
   closeOnEscape?: boolean
+  /**
+   * Shell layout. 'tabs' renders a tab strip between header and body;
+   * 'rail' renders a sidebar rail + pane as the shell's middle row.
+   * Both are shell regions — never part of the scrolling body content.
+   */
+  layout?: ModalLayout
+  /** Sections for the tab strip / rail. The strip renders only with 2+ tabs. */
+  tabs?: ModalTab[]
+  /** Id of the selected tab. Two-way bindable via update:activeTab. */
+  activeTab?: string
 }
 
 const props = withDefaults(defineProps<Props>(), {
@@ -21,13 +31,49 @@ const props = withDefaults(defineProps<Props>(), {
   closable: true,
   closeOnOverlay: false,
   closeOnEscape: true,
+  layout: 'plain',
+  tabs: () => [],
 })
 
 const emit = defineEmits<{
   'update:modelValue': [value: boolean]
+  'update:activeTab': [id: string]
   close: []
 }>()
 
+const activeTabMeta = computed(() => props.tabs.find((tab) => tab.id === props.activeTab))
+
+const tabButtonRefs = new Map<string, HTMLElement>()
+
+function setTabButtonRef(id: string, el: Element | ComponentPublicInstance | null) {
+  if (el instanceof HTMLElement) {
+    tabButtonRefs.set(id, el)
+  } else {
+    tabButtonRefs.delete(id)
+  }
+}
+
+function selectTab(tab: ModalTab) {
+  if (tab.disabled || tab.id === props.activeTab) return
+  emit('update:activeTab', tab.id)
+}
+
+/** ARIA tablist keyboard contract: arrows move selection to the next non-disabled tab, wrapping. */
+function focusTab(delta: number) {
+  const enabled = props.tabs.filter((tab) => !tab.disabled)
+  if (enabled.length === 0) return
+  const currentIndex = enabled.findIndex((tab) => tab.id === props.activeTab)
+  const next = enabled[(currentIndex + delta + enabled.length) % enabled.length]
+  if (!next || next.id === props.activeTab) return
+  emit('update:activeTab', next.id)
+  tabButtonRefs.get(next.id)?.focus()
+}
+
+function isPathIcon(icon: ModalTab['icon']): icon is string | string[] {
+  if (!icon) return false
+  return Array.isArray(icon) || icon.trim().startsWith('M') || icon.trim().startsWith('m')
+}
+
 const containerRef = ref<HTMLElement | null>(null)
 let previouslyFocused: HTMLElement | null = null
 
@@ -43,6 +89,8 @@ const FOCUSABLE_SELECTOR = [
 function getFocusableElements(): HTMLElement[] {
   if (!containerRef.value) return []
   return Array.from(containerRef.value.querySelectorAll<HTMLElement>(FOCUSABLE_SELECTOR))
+    // Roving tabindex (inactive tabs/rail items) stays out of the Tab cycle.
+    .filter((el) => el.tabIndex !== -1)
 }
 
 function handleKeydown(event: KeyboardEvent) {
@@ -127,6 +175,7 @@ onUnmounted(() => {
             'mint-modal__container',
             `mint-modal__container--${size}`,
             `mint-modal__container--${variant}`,
+            `mint-modal__container--${layout}`,
           ]"
           role="dialog"
           aria-modal="true"
@@ -160,8 +209,107 @@ onUnmounted(() => {
             </button>
           </div>
 
+          <!-- Tab strip — a shell region between header and body, flush with the modal edges -->
+          <div
+            v-if="layout === 'tabs' && tabs.length > 1"
+            class="mint-modal__tabs"
+            role="tablist"
+          >
+            <button
+              v-for="tab in tabs"
+              :key="tab.id"
+              :ref="(el) => setTabButtonRef(tab.id, el)"
+              type="button"
+              role="tab"
+              :aria-selected="activeTab === tab.id"
+              :aria-disabled="tab.disabled || undefined"
+              :tabindex="activeTab === tab.id ? 0 : -1"
+              :class="['mint-modal__tab', {
+                'mint-modal__tab--active': activeTab === tab.id,
+                'mint-modal__tab--disabled': tab.disabled,
+              }]"
+              @click="selectTab(tab)"
+              @keydown.left.prevent="focusTab(-1)"
+              @keydown.right.prevent="focusTab(1)"
+            >
+              {{ tab.label }}
+              <span v-if="tab.meta" class="mint-modal__tab-meta">{{ tab.meta }}</span>
+            </button>
+          </div>
+
+          <!-- Rail layout: rail column + pane are the shell's middle row -->
+          <div v-if="layout === 'rail'" class="mint-modal__split">
+            <div class="mint-modal__rail" role="tablist" aria-orientation="vertical">
+              <div class="mint-modal__rail-items">
+                <button
+                  v-for="tab in tabs"
+                  :key="tab.id"
+                  :ref="(el) => setTabButtonRef(tab.id, el)"
+                  type="button"
+                  role="tab"
+                  :aria-selected="activeTab === tab.id"
+                  :aria-disabled="tab.disabled || undefined"
+                  :tabindex="activeTab === tab.id ? 0 : -1"
+                  :class="['mint-modal__rail-item', {
+                    'mint-modal__rail-item--active': activeTab === tab.id,
+                    'mint-modal__rail-item--disabled': tab.disabled,
+                  }]"
+                  @click="selectTab(tab)"
+                  @keydown.up.prevent="focusTab(-1)"
+                  @keydown.down.prevent="focusTab(1)"
+                >
+                  <span v-if="tab.icon" class="mint-modal__rail-item-icon" aria-hidden="true">
+                    <svg
+                      v-if="isPathIcon(tab.icon)"
+                      viewBox="0 0 24 24"
+                      fill="none"
+                      stroke="currentColor"
+                      stroke-width="1.8"
+                      stroke-linecap="round"
+                      stroke-linejoin="round"
+                    >
+                      <template v-if="Array.isArray(tab.icon)">
+                        <path v-for="(d, index) in tab.icon" :key="index" :d="d" />
+                      </template>
+                      <path v-else :d="tab.icon" />
+                    </svg>
+                    <!-- Trusted, author-controlled markup only — same contract as SettingsTab.icon. -->
+                    <span v-else v-html="tab.icon" />
+                  </span>
+                  <span class="mint-modal__rail-item-text">
+                    <span class="mint-modal__rail-item-label">{{ tab.label }}</span>
+                    <span v-if="tab.description" class="mint-modal__rail-item-description">{{ tab.description }}</span>
+                  </span>
+                  <span v-if="tab.meta" class="mint-modal__rail-item-meta">{{ tab.meta }}</span>
+                </button>
+              </div>
+              <!-- Quiet rail-bottom action (e.g. Log out) -->
+              <slot name="rail-footer" />
+            </div>
+
+            <section
+              class="mint-modal__pane"
+              role="tabpanel"
+              :aria-label="activeTabMeta?.label"
+              tabindex="0"
+            >
+              <header v-if="activeTabMeta?.label" class="mint-modal__pane-header">
+                <h4 class="mint-modal__pane-title">{{ activeTabMeta.label }}</h4>
+                <p v-if="activeTabMeta.description" class="mint-modal__pane-subtitle">
+                  {{ activeTabMeta.description }}
+                </p>
+              </header>
+              <div class="mint-modal__pane-body">
+                <slot />
+              </div>
+            </section>
+          </div>
+
           <!-- Body -->
-          <div class="mint-modal__body">
+          <div
+            v-else
+            :class="['mint-modal__body', layout === 'tabs' ? 'mint-modal__body--tabbed' : null]"
+          >
             <slot />
           </div>
 

package/src/components/BioTemplateExperimentWorkspaceView.vue

@@ -1,5 +1,12 @@
 <script setup lang="ts">
-/** Current-experiment template workspace with load/save/reset controls and WellPlate/DataFrame/DoseCalculator previews. */
+/**
+ * Current-experiment template workspace with load/save/reset controls and WellPlate/DataFrame/DoseCalculator previews.
+ *
+ * @example Recommended
+ * ```vue
+ * <BioTemplateExperimentWorkspaceView :target="collection" label="Assay" kind="collection" />
+ * ```
+ */
 import { computed } from 'vue'
 import {
   extractTemplateCollection,

package/src/components/BioTemplatePackWorkspaceView.vue

@@ -1,5 +1,12 @@
 <script setup lang="ts">
-/** Complete current-experiment workspace for a curated biology template pack with save/load controls and component-prop slots. */
+/**
+ * Complete current-experiment workspace for a curated biology template pack with save/load controls and component-prop slots.
+ *
+ * @example Recommended
+ * ```vue
+ * <BioTemplatePackWorkspaceView pack="cell-culture-screen" />
+ * ```
+ */
 import { computed, effectScope, onScopeDispose, shallowRef, unref, useSlots, watch, type EffectScope } from 'vue'
 import type { BioTemplateEnvelope, TemplateCollectionEnvelope, TemplatePackId } from '../templates'
 import type {

package/src/components/BioTemplatePresetWorkspaceView.vue

@@ -1,5 +1,12 @@
 <script setup lang="ts">
-/** Complete editable biology template preset workspace for WellPlate/DoseCalculator, LC-MS, qPCR, generated controls, preview components, and current-experiment save wiring. */
+/**
+ * Complete editable biology template preset workspace for WellPlate/DoseCalculator, LC-MS, qPCR, generated controls, preview components, and current-experiment save wiring.
+ *
+ * @example Recommended
+ * ```vue
+ * <BioTemplatePresetWorkspaceView v-model="values" preset="wellplate-screen" />
+ * ```
+ */
 import { computed, effectScope, onScopeDispose, shallowRef, toRaw, unref, watch, type EffectScope } from 'vue'
 import type { BioTemplateControlValues, TemplatePresetId } from '../templates'
 import type {

package/src/components/BioTemplateRenderer.vue

@@ -1,5 +1,12 @@
 <script setup lang="ts">
-/** Render biology template envelopes with matching SDK components such as WellPlate, DoseCalculator, and DataFrame. */
+/**
+ * Render biology template envelopes with matching SDK components such as WellPlate, DoseCalculator, and DataFrame.
+ *
+ * @example Recommended
+ * ```vue
+ * <BioTemplateRenderer :target="collection" />
+ * ```
+ */
 import { computed } from 'vue'
 import {
   toBioTemplateComponentBindings,

package/src/components/ComponentBindingRenderer.vue

@@ -1,5 +1,12 @@
 <script setup lang="ts">
-/** Render generated SDK component bindings such as WellPlate, DoseCalculator, DataFrame, and PlateMapEditor. */
+/**
+ * Render generated SDK component bindings such as WellPlate, DoseCalculator, DataFrame, and PlateMapEditor.
+ *
+ * @example Recommended
+ * ```vue
+ * <ComponentBindingRenderer :bindings="workspace.componentBindings.value" />
+ * ```
+ */
 import { computed, type Component } from 'vue'
 import DataFrame from './DataFrame.vue'
 import DoseCalculator from './DoseCalculator.vue'

package/src/components/ControlWorkspaceView.vue

@@ -1,5 +1,12 @@
 <script setup lang="ts">
-/** Complete control workspace component that turns a simple controls data model into AppTopBar, AppSidebar, and FormBuilder forms. */
+/**
+ * Complete control workspace component that turns a simple controls data model into AppTopBar, AppSidebar, and FormBuilder forms.
+ *
+ * @example Recommended
+ * ```vue
+ * <ControlWorkspaceView v-model="values" :model="workspaceModel" title="Analysis" />
+ * ```
+ */
 import { computed, effectScope, onScopeDispose, shallowRef, toRaw, watch, type EffectScope } from 'vue'
 import type { TopBarVariant } from '../types'
 import type { FormEnhancements } from '../types/form-builder'

package/src/components/DoseDesignWorkspaceView.vue

@@ -1,5 +1,12 @@
 <script setup lang="ts">
-/** Complete ControlWorkspaceView page shell for WellPlate + DoseCalculator dose design. */
+/**
+ * Complete ControlWorkspaceView page shell for WellPlate + DoseCalculator dose design.
+ *
+ * @example Recommended
+ * ```vue
+ * <DoseDesignWorkspaceView v-model="values" title="Dose Design" />
+ * ```
+ */
 import { computed } from 'vue'
 import type { TopBarVariant } from '../types'
 import type { FormEnhancements } from '../types/form-builder'