@morscherlab/mint-sdk 1.2.0-beta.4 → 1.2.0-beta.7

package/src/composables/usePluginWorkspace.ts

@@ -0,0 +1,208 @@
+import { computed } from 'vue'
+import type { ComputedRef } from 'vue'
+import type { PageSelectorItem, PillNavItem } from '../types'
+import type {
+  PluginWorkspaceViewEmit,
+  PluginWorkspaceViewProps,
+} from '../components/PluginWorkspaceView.props'
+import { usePluginWorkspaceControls } from '../components/PluginWorkspaceView.controls'
+import { usePluginWorkspaceNavigation } from '../components/PluginWorkspaceView.navigation'
+import {
+  getPluginWorkspaceSidebarSlotNames,
+  getPluginWorkspaceTopBarSlotNames,
+  hasPluginWorkspaceSidebarSurface,
+} from '../components/PluginWorkspaceView.shell'
+import type {
+  PluginWorkspaceControlsModel,
+  PluginWorkspaceShellModel,
+  PluginWorkspaceSidebarModel,
+} from './pluginWorkspaceModel'
+
+/**
+ * Loosely-typed view of a component's `useSlots()` result: only slot presence and names are
+ * read here, so this accepts any `defineSlots()` shape without fighting Vue's `Slot` render
+ * function type. Mirrors the `SlotKeyMap` helper type in PluginWorkspaceView.shell.ts.
+ */
+export type PluginWorkspaceSlotsLike = Readonly<Record<string, unknown>>
+
+export interface UsePluginWorkspaceOptions {
+  /** PluginWorkspaceView's own reactive props object (from `defineProps`). */
+  props: PluginWorkspaceViewProps
+  /** PluginWorkspaceView's own slots (from `useSlots()`), used to detect provided passthrough slots. */
+  slots: PluginWorkspaceSlotsLike
+  /** PluginWorkspaceView's own typed `emit` function (from `defineEmits<PluginWorkspaceViewEmits>()`). */
+  emit: PluginWorkspaceViewEmit
+}
+
+export interface UsePluginWorkspaceReturn {
+  /** Model consumed by WorkspaceShellInternal's `shell` prop. */
+  shell: ComputedRef<PluginWorkspaceShellModel>
+  /** Model consumed by WorkspaceSidebarInternal's `sidebar` prop. */
+  sidebar: ComputedRef<PluginWorkspaceSidebarModel>
+  /** Model consumed by WorkspaceControlsInternal's `controls` prop, and by the raw `default` slot. */
+  controls: ComputedRef<PluginWorkspaceControlsModel>
+  /** Whether AppLayout should render a sidebar surface at all. */
+  hasSidebarSurface: ComputedRef<boolean>
+  /** Applies an AppSidebar `update:model-value` payload to the shared control values and emits `update:modelValue`/`update:values`. */
+  handleControlValuesUpdate: (values: Record<string, unknown>) => void
+  /** Resolves an AppTopBar `page-selector-select` payload into the active view and emits `page-selector-select`. */
+  handlePageSelectorSelect: (page: PageSelectorItem) => void
+  /** Resolves an AppTopBar `pill-select` payload into the active view and emits `pill-select`. */
+  handlePillSelect: (item: PillNavItem) => void
+}
+
+/**
+ * Maps PluginWorkspaceView's flat 72-prop surface into the three typed model objects
+ * (`shell`, `sidebar`, `controls`) rendered by its internal pieces
+ * (WorkspaceShellInternal, WorkspaceSidebarInternal, WorkspaceControlsInternal). Reuses the
+ * existing `usePluginWorkspaceControls` / `usePluginWorkspaceNavigation` composables and the
+ * PluginWorkspaceView.shell slot-detection helpers, so it changes only how that state is
+ * assembled and exposed, not the underlying behavior.
+ *
+ * @example Recommended
+ * ```ts
+ * const props = withDefaults(defineProps<PluginWorkspaceViewProps>(), { ... })
+ * const emit = defineEmits<PluginWorkspaceViewEmits>()
+ * const slots = useSlots()
+ * const { shell, sidebar, controls } = usePluginWorkspace({ props, slots, emit })
+ * ```
+ */
+export function usePluginWorkspace(options: UsePluginWorkspaceOptions): UsePluginWorkspaceReturn {
+  const { props, slots, emit } = options
+
+  const controlsState = usePluginWorkspaceControls({
+    model: () => props.model,
+    controls: () => props.controls,
+    controlOptions: () => props.controlOptions ?? {},
+    modelValue: () => props.modelValue,
+    values: () => props.values,
+    componentBindings: () => props.componentBindings,
+    componentProps: () => props.componentProps,
+    componentPropsById: () => props.componentPropsById,
+    emitValues: (values) => {
+      emit('update:modelValue', values)
+      emit('update:values', values)
+    },
+  })
+
+  const navigationState = usePluginWorkspaceNavigation({
+    activeView: () => props.activeView,
+    defaultActiveView: () => props.defaultActiveView,
+    currentPillId: () => props.currentPillId,
+    currentPageSelectorId: () => props.currentPageSelectorId,
+    pillNav: () => props.pillNav,
+    pageSelector: () => props.pageSelector,
+    panelIds: () => Object.keys(props.panels ?? {}),
+    generatedPillNav: controlsState.generatedPillNav,
+    generatedDefaultView: controlsState.generatedDefaultView,
+    emitActiveView: viewId => emit('update:activeView', viewId),
+    emitPageSelectorSelect: page => emit('page-selector-select', page),
+    emitPillSelect: item => emit('pill-select', item),
+  })
+
+  const topBarSlotNames = computed<string[]>(() => getPluginWorkspaceTopBarSlotNames(slots))
+  const sidebarSlotNames = computed<string[]>(() => getPluginWorkspaceSidebarSlotNames(slots))
+
+  const hasSidebarSurface = computed(() => hasPluginWorkspaceSidebarSurface({
+    showSidebar: props.showSidebar ?? true,
+    panels: props.panels ?? {},
+    forms: props.forms ?? {},
+    model: props.model,
+    controls: props.controls,
+    showSidebarWhenEmpty: props.showSidebarWhenEmpty ?? false,
+    sidebarContentId: props.sidebarContentId,
+    sidebarTitle: props.sidebarTitle,
+    sidebarSubtitle: props.sidebarSubtitle,
+    sidebarBadge: props.sidebarBadge,
+    hasSidebarSlot: Boolean(slots.sidebar),
+    sidebarSlotCount: sidebarSlotNames.value.length,
+  }))
+
+  const controls = computed<PluginWorkspaceControlsModel>(() => ({
+    activeView: navigationState.resolvedActiveView.value,
+    setActiveView: navigationState.setActiveView,
+    values: controlsState.internalControlValues,
+    componentBindings: controlsState.resolvedComponentBindings.value,
+    componentBindingsById: controlsState.resolvedComponentBindingsById.value,
+    componentProps: controlsState.resolvedComponentProps.value,
+    componentPropsById: controlsState.resolvedComponentPropsById.value,
+  }))
+
+  const shell = computed<PluginWorkspaceShellModel>(() => ({
+    sidebarPosition: props.sidebarPosition ?? 'left',
+    sidebarWidth: props.sidebarWidth,
+    floating: props.floating ?? true,
+    responsiveSidebar: props.responsiveSidebar ?? true,
+    sidebarToggleLabel: props.sidebarToggleLabel ?? 'Open workspace sidebar',
+    sidebarCloseLabel: props.sidebarCloseLabel ?? 'Close workspace sidebar',
+    hasSidebarSurface: hasSidebarSurface.value,
+    title: props.title ?? 'Workspace',
+    subtitle: props.subtitle,
+    topBarVariant: props.topBarVariant ?? 'card',
+    homePath: props.homePath ?? '/',
+    showLogo: props.showLogo ?? true,
+    pageSelector: props.pageSelector,
+    currentPageSelectorId: navigationState.resolvedCurrentPageSelectorId.value,
+    pluginSwitcher: props.pluginSwitcher,
+    pillNav: navigationState.resolvedPillNav.value,
+    currentPillId: navigationState.resolvedCurrentPillId.value,
+    showThemeToggle: props.showThemeToggle ?? true,
+    showSettings: props.showSettings ?? true,
+    settingsConfig: props.settingsConfig,
+    showStandaloneLabel: props.showStandaloneLabel ?? false,
+    standaloneLabel: props.standaloneLabel ?? 'Standalone',
+    accountMenu: props.accountMenu,
+    showNotifications: props.showNotifications ?? false,
+    hasNotificationDot: props.hasNotificationDot ?? false,
+    showAdmin: props.showAdmin ?? false,
+    adminPath: props.adminPath ?? '/admin',
+    userName: props.userName,
+    userInitial: props.userInitial,
+    userEmail: props.userEmail,
+    topBarSlotNames: topBarSlotNames.value,
+    controls: controls.value,
+  }))
+
+  const sidebar = computed<PluginWorkspaceSidebarModel>(() => ({
+    title: props.sidebarTitle,
+    subtitle: props.sidebarSubtitle,
+    badge: props.sidebarBadge,
+    variant: props.sidebarVariant ?? 'analysis',
+    panels: props.panels ?? {},
+    activeView: navigationState.resolvedActiveView.value,
+    floating: false,
+    dense: props.dense ?? true,
+    width: props.sidebarWidth,
+    side: props.sidebarPosition ?? 'left',
+    forms: props.forms ?? {},
+    contentId: props.sidebarContentId,
+    showWhenEmpty: (props.showSidebarWhenEmpty ?? false) || props.sidebarContentId !== undefined,
+    model: props.model,
+    controlSchema: props.controls,
+    controlOptions: props.controlOptions ?? {},
+    values: controlsState.internalControlValues,
+    formEnhancements: props.formEnhancements,
+    showFormActions: props.showFormActions ?? false,
+    formLoading: props.formLoading ?? false,
+    formDisabled: props.formDisabled ?? false,
+    formReadonly: props.formReadonly ?? false,
+    formSize: props.formSize ?? 'sm',
+    collapsible: props.sidebarCollapsible,
+    collapsed: props.sidebarCollapsed,
+    defaultCollapsed: props.defaultSidebarCollapsed ?? false,
+    collapsedWidth: props.sidebarCollapsedWidth ?? '3rem',
+    collapseButtonLabel: props.sidebarCollapseButtonLabel ?? 'Collapse sidebar',
+    expandButtonLabel: props.sidebarExpandButtonLabel ?? 'Expand sidebar',
+    slotNames: sidebarSlotNames.value,
+  }))
+
+  return {
+    shell,
+    sidebar,
+    controls,
+    hasSidebarSurface,
+    handleControlValuesUpdate: controlsState.handleControlValuesUpdate,
+    handlePageSelectorSelect: navigationState.handlePageSelectorSelect,
+    handlePillSelect: navigationState.handlePillSelect,
+  }
+}

package/src/composables/useResourceCrud.ts

@@ -38,7 +38,11 @@ export interface UseResourceCrudReturn<TItem, TCreate, TUpdate, TKey extends Res
   clearError: () => void
 }
 
-/** Common list/create/update/delete state wrapper for generated plugin clients. */
+/**
+ * Common list/create/update/delete state wrapper for generated plugin clients.
+ *
+ * @deprecated Unused by the MINT platform and scheduled for removal in MINT 1.3; use `useGeneratedPluginClient()` instead.
+ */
 export function useResourceCrud<
   TItem,
   TCreate = Partial<TItem>,

package/src/composables/useRovingFocus.ts

@@ -0,0 +1,66 @@
+import { nextTick } from 'vue'
+
+export interface UseRovingFocusOptions {
+  /** Selectable item ids, in DOM order. Already excludes items skipped entirely (e.g. disabled tabs). */
+  ids: () => string[]
+  /** The id that is currently active/selected. */
+  activeId: () => string | undefined
+  /** Activates an id (e.g. emit `update:modelValue`). The composable focuses the matching element afterward. */
+  activate: (id: string) => void
+  /** Returns the focusable element for an id, queried lazily so it reflects the post-activation DOM. */
+  getElement: (id: string) => HTMLElement | null | undefined
+  /** Arrow-key axis: `'horizontal'` (Left/Right, default) or `'vertical'` (Up/Down). */
+  orientation?: 'horizontal' | 'vertical'
+}
+
+export interface UseRovingFocusReturn {
+  /** Bind to each item's `@keydown`. */
+  handleKeydown: (event: KeyboardEvent) => void
+}
+
+/**
+ * WAI-ARIA roving-tabindex navigation with automatic activation (the tabs pattern):
+ * Left/Right (or Up/Down when `orientation` is `'vertical'`) move to the adjacent item
+ * and activate it immediately, wrapping past the ends; Home/End jump to the first/last
+ * item. Only the active item should carry `tabindex="0"`; give every other item
+ * `tabindex="-1"`. Used by BaseTabs.
+ */
+export function useRovingFocus(options: UseRovingFocusOptions): UseRovingFocusReturn {
+  const orientation = options.orientation ?? 'horizontal'
+  const prevKey = orientation === 'vertical' ? 'ArrowUp' : 'ArrowLeft'
+  const nextKey = orientation === 'vertical' ? 'ArrowDown' : 'ArrowRight'
+
+  function moveTo(id: string | undefined) {
+    if (id === undefined) return
+    options.activate(id)
+    void nextTick(() => options.getElement(id)?.focus())
+  }
+
+  function handleKeydown(event: KeyboardEvent) {
+    const ids = options.ids()
+    if (ids.length === 0) return
+    const currentIndex = ids.indexOf(options.activeId() ?? '')
+
+    if (event.key === 'Home') {
+      event.preventDefault()
+      moveTo(ids[0])
+      return
+    }
+    if (event.key === 'End') {
+      event.preventDefault()
+      moveTo(ids[ids.length - 1])
+      return
+    }
+    if (event.key === prevKey) {
+      event.preventDefault()
+      moveTo(ids[currentIndex <= 0 ? ids.length - 1 : currentIndex - 1])
+      return
+    }
+    if (event.key === nextKey) {
+      event.preventDefault()
+      moveTo(ids[currentIndex === -1 || currentIndex >= ids.length - 1 ? 0 : currentIndex + 1])
+    }
+  }
+
+  return { handleKeydown }
+}

package/src/composables/useWellPainting.ts

@@ -46,7 +46,11 @@ const PLATE_DIMENSIONS: Record<WellPlateFormat, { rows: number; cols: number }>
   384: { rows: 16, cols: 24 },
 }
 
-/** Pointer painting/rectangle selection state for WellPlate-based editors. */
+/**
+ * Pointer painting/rectangle selection state for WellPlate-based editors.
+ *
+ * @deprecated Unused by the MINT platform and scheduled for removal in MINT 1.3; use `useWellPlateEditor()` instead.
+ */
 export function useWellPainting<TMode extends string = string, TPayload = unknown>(
   options: UseWellPaintingOptions<TMode, TPayload>,
 ): UseWellPaintingReturn<TMode, TPayload> {

package/src/composables/useWellPlateAdapter.ts

@@ -28,7 +28,11 @@ export interface UseWellPlateAdapterReturn {
   wells: ComputedRef<Record<string, Partial<Well>>>
 }
 
-/** Convert domain rows into WellPlate's wells prop without hand-written adapters. */
+/**
+ * Convert domain rows into WellPlate's wells prop without hand-written adapters.
+ *
+ * @deprecated Unused by the MINT platform and scheduled for removal in MINT 1.3; use `useWellPlateEditor()` instead.
+ */
 export function useWellPlateAdapter<TEntry>(
   options: WellPlateAdapterOptions<TEntry>,
 ): UseWellPlateAdapterReturn {

package/src/composables/useWellPlateValidation.ts

@@ -33,7 +33,11 @@ export interface UseWellPlateValidationReturn<TType extends string = string> {
   errorCount: ComputedRef<number>
 }
 
-/** Rule-driven validation state for WellPlate layout/design screens. */
+/**
+ * Rule-driven validation state for WellPlate layout/design screens.
+ *
+ * @deprecated Unused by the MINT platform and scheduled for removal in MINT 1.3; use `useWellPlateEditor()` instead.
+ */
 export function useWellPlateValidation<TContext, TType extends string = string>(
   options: UseWellPlateValidationOptions<TContext, TType>,
 ): UseWellPlateValidationReturn<TType> {

package/src/composables/workspaceRecipes.ts

@@ -0,0 +1,267 @@
+import type { TopBarVariant } from '../types'
+import type { FormEnhancements } from '../types/form-builder'
+import type {
+  ControlModel,
+  ControlModelBinding,
+  ControlSchema,
+  ControlWorkspaceOptions,
+  UseControlWorkspaceReturn,
+} from './useControlSchema'
+import { mergeControlWorkspaceOptions, resolveControlModel } from './useControlSchema'
+
+/**
+ * Merges `initialValues`/external `modelValue`/`values` on top of a base
+ * `ControlWorkspaceOptions.initialValues`, matching the layering FormBuilder expects: base
+ * defaults, then caller-supplied initial values, then live external values win last. Shared by
+ * {@link controlWorkspaceProps} and {@link bioTemplatePresetWorkspaceProps} so both "generate a
+ * workspace from options, initialValues, and v-model" views merge options identically.
+ */
+export function resolveControlOptionsWithExternalValues<TOptions extends ControlWorkspaceOptions>(
+  base: TOptions,
+  initialValues: Record<string, unknown> | undefined,
+  externalValues: Record<string, unknown> | undefined,
+): TOptions {
+  if (initialValues === undefined && externalValues === undefined) return base
+
+  return {
+    ...base,
+    initialValues: {
+      ...(base.initialValues ?? {}),
+      ...(initialValues ?? {}),
+      ...(externalValues ?? {}),
+    },
+  }
+}
+
+export interface ControlWorkspaceModelProps {
+  model?: ControlModel | ControlModelBinding
+  controls?: ControlSchema
+  controlOptions?: ControlWorkspaceOptions
+  initialValues?: Record<string, unknown>
+  modelValue?: Record<string, unknown>
+  values?: Record<string, unknown>
+}
+
+export interface ResolvedControlWorkspaceModel {
+  /** `modelValue` if provided, else `values` — the single external v-model source of truth. */
+  externalValues: Record<string, unknown> | undefined
+  /** `model` resolved through `resolveControlModel()`, or undefined for a raw `controls` schema. */
+  resolvedModel: ControlModelBinding | undefined
+  /** `controls` if provided, else the resolved model's controls, else `{}`. */
+  resolvedControls: ControlSchema
+  /** `controlOptions` merged over the resolved model's own options, with initialValues/external values layered on top. */
+  resolvedControlOptions: ControlWorkspaceOptions
+}
+
+/**
+ * Resolves ControlWorkspaceView's `model`/`controls`/`controlOptions`/`initialValues`/
+ * `modelValue`/`values` props into the schema + options pair `useControlWorkspace()` needs.
+ * Pure and framework-free so callers wrap each field in their own `computed()`.
+ *
+ * @example Recommended
+ * ```ts
+ * const resolved = computed(() => controlWorkspaceProps(props))
+ * const resolvedControls = computed(() => resolved.value.resolvedControls)
+ * ```
+ */
+export function controlWorkspaceProps(props: ControlWorkspaceModelProps): ResolvedControlWorkspaceModel {
+  const externalValues = props.modelValue ?? props.values
+  const resolvedModel = resolveControlModel(props.model)
+  const resolvedControls: ControlSchema = props.controls ?? resolvedModel?.controls ?? {}
+  const baseControlOptions = mergeControlWorkspaceOptions(resolvedModel?.controlOptions, props.controlOptions)
+  const resolvedControlOptions = resolveControlOptionsWithExternalValues(
+    baseControlOptions,
+    props.initialValues,
+    externalValues,
+  )
+
+  return { externalValues, resolvedModel, resolvedControls, resolvedControlOptions }
+}
+
+export interface DoseDesignWorkspacePassthroughProps {
+  workspace?: UseControlWorkspaceReturn<ControlSchema>
+  controlOptions?: ControlWorkspaceOptions
+  initialValues?: Record<string, unknown>
+  modelValue?: Record<string, unknown>
+  values?: Record<string, unknown>
+  title?: string
+  subtitle?: string
+  topBarVariant?: TopBarVariant
+  sidebarWidth?: string
+  sidebarVariant?: 'default' | 'analysis'
+  responsiveSidebar?: boolean
+  sidebarPosition?: 'left' | 'right'
+  sidebarTitle?: string
+  sidebarSubtitle?: string
+  sidebarBadge?: string | number
+  floating?: boolean
+  dense?: boolean
+  showSettings?: boolean
+  showFormActions?: boolean
+  formEnhancements?: FormEnhancements<Record<string, unknown>>
+  formLoading?: boolean
+  formDisabled?: boolean
+  formReadonly?: boolean
+  formSize?: 'sm' | 'md' | 'lg'
+}
+
+/**
+ * Maps DoseDesignWorkspaceView's props straight through to the identically-named
+ * ControlWorkspaceView props it wraps — the ~25-key pass-through list that used to be spelled
+ * out attribute-by-attribute in the template. `model` is the caller's already-resolved dose
+ * design model, not the raw (possibly absent) `props.model`.
+ *
+ * @example Recommended
+ * ```vue
+ * <ControlWorkspaceView v-bind="doseDesignWorkspaceProps(props, resolvedModel)" />
+ * ```
+ */
+export function doseDesignWorkspaceProps(
+  props: DoseDesignWorkspacePassthroughProps,
+  model: ControlModel | ControlModelBinding,
+) {
+  return {
+    model,
+    workspace: props.workspace,
+    controlOptions: props.controlOptions,
+    initialValues: props.initialValues,
+    modelValue: props.modelValue,
+    values: props.values,
+    title: props.title,
+    subtitle: props.subtitle,
+    topBarVariant: props.topBarVariant,
+    sidebarWidth: props.sidebarWidth,
+    sidebarVariant: props.sidebarVariant,
+    responsiveSidebar: props.responsiveSidebar,
+    sidebarPosition: props.sidebarPosition,
+    sidebarTitle: props.sidebarTitle,
+    sidebarSubtitle: props.sidebarSubtitle,
+    sidebarBadge: props.sidebarBadge,
+    floating: props.floating,
+    dense: props.dense,
+    showSettings: props.showSettings,
+    showFormActions: props.showFormActions,
+    formEnhancements: props.formEnhancements,
+    formLoading: props.formLoading,
+    formDisabled: props.formDisabled,
+    formReadonly: props.formReadonly,
+    formSize: props.formSize,
+  }
+}
+
+export interface BioTemplateExperimentWorkspaceStatusProps {
+  status?: {
+    loading?: boolean
+    saving?: boolean
+    error?: string | null
+    hasExperiment?: boolean
+    currentExperimentId?: number
+    lastLoadedAt?: Date | null
+    lastSavedAt?: Date | null
+  }
+  loading?: boolean
+  error?: string | null
+  hasExperiment?: boolean
+  currentExperimentId?: number
+  lastLoadedAt?: Date | null
+  lastSavedAt?: Date | null
+}
+
+export interface ResolvedBioTemplateExperimentStatus {
+  loading: boolean
+  error: string | null | undefined
+  hasExperiment: boolean
+  currentExperimentId: number | undefined
+  lastLoadedAt: Date | null | undefined
+  lastSavedAt: Date | null | undefined
+}
+
+/**
+ * Merges BioTemplateExperimentWorkspaceView's grouped `status` prop over its individual
+ * `loading`/`error`/`hasExperiment`/... props: `status` wins whenever the corresponding field
+ * on it is set, otherwise the flat prop (or its default) is used. Centralizes the six
+ * independent fallback rules generated plugin pages rely on when they pass a request/experiment
+ * `status` object instead of wiring each field by hand.
+ */
+export function bioTemplateExperimentWorkspaceProps(
+  props: BioTemplateExperimentWorkspaceStatusProps,
+): ResolvedBioTemplateExperimentStatus {
+  const status = props.status
+  return {
+    loading: status?.loading !== undefined || status?.saving !== undefined
+      ? Boolean(status?.loading) || Boolean(status?.saving)
+      : Boolean(props.loading),
+    error: status?.error !== undefined ? status.error : props.error,
+    hasExperiment: status?.hasExperiment ?? props.hasExperiment ?? false,
+    currentExperimentId: status?.currentExperimentId ?? props.currentExperimentId,
+    lastLoadedAt: status?.lastLoadedAt !== undefined ? status.lastLoadedAt : props.lastLoadedAt,
+    lastSavedAt: status?.lastSavedAt !== undefined ? status.lastSavedAt : props.lastSavedAt,
+  }
+}
+
+export interface BioTemplatePackWorkspacePassthroughProps {
+  message?: string
+  dense?: boolean
+  readonly?: boolean
+  showStatus?: boolean
+  showTemplateSummary?: boolean
+  loadLabel?: string
+  resetLabel?: string
+  saveLabel?: string
+}
+
+/**
+ * Assembles the prop object BioTemplatePackWorkspaceView binds onto the
+ * BioTemplateExperimentWorkspaceView it wraps: its own display props passed straight through,
+ * plus the pack-derived `target`/`label`/`status`/`actions` computed by the caller.
+ */
+export function bioTemplatePackWorkspaceProps<TTarget, TStatus, TActions>(
+  props: BioTemplatePackWorkspacePassthroughProps,
+  derived: {
+    target: TTarget
+    label: string
+    status: TStatus
+    actions: TActions
+  },
+) {
+  return {
+    target: derived.target,
+    kind: 'collection' as const,
+    label: derived.label,
+    message: props.message,
+    status: derived.status,
+    actions: derived.actions,
+    dense: props.dense,
+    readonly: props.readonly,
+    showStatus: props.showStatus,
+    showTemplateSummary: props.showTemplateSummary,
+    loadLabel: props.loadLabel,
+    resetLabel: props.resetLabel,
+    saveLabel: props.saveLabel,
+  }
+}
+
+export interface BioTemplatePresetWorkspaceOptionsProps<TOptions extends ControlWorkspaceOptions> {
+  workspaceOptions?: TOptions
+  initialValues?: Record<string, unknown>
+  modelValue?: Record<string, unknown>
+  values?: Record<string, unknown>
+}
+
+/**
+ * Resolves BioTemplatePresetWorkspaceView's `workspaceOptions`/`initialValues`/`modelValue`/
+ * `values` props into the single options object `useBioTemplatePresetWorkspace()` needs,
+ * reusing the same base/initialValues/external-values layering as {@link controlWorkspaceProps}.
+ */
+export function bioTemplatePresetWorkspaceProps<TOptions extends ControlWorkspaceOptions>(
+  props: BioTemplatePresetWorkspaceOptionsProps<TOptions>,
+): { externalValues: Record<string, unknown> | undefined; resolvedWorkspaceOptions: TOptions } {
+  const externalValues = props.modelValue ?? props.values
+  const resolvedWorkspaceOptions = resolveControlOptionsWithExternalValues(
+    (props.workspaceOptions ?? {}) as TOptions,
+    props.initialValues,
+    externalValues,
+  )
+
+  return { externalValues, resolvedWorkspaceOptions }
+}

package/src/index.ts

@@ -41,6 +41,22 @@ export {
   deriveShade,
   type Hsl,
 } from './utils/color'
+export {
+  PLUGIN_SECRET_FORMAT_KEY,
+  PLUGIN_SECRET_FORMAT_REF,
+  PLUGIN_SECRET_REF_KEY,
+  clearPluginSecret,
+  isPluginSecretLocked,
+  isPluginSecretRef,
+  keepPluginSecret,
+  pluginSecretId,
+  pluginSecretLabel,
+  pluginSecretState,
+  setPluginSecret,
+  usesPluginSecretReferences,
+  type PluginSecretRef,
+  type PluginSecretState,
+} from './utils/pluginSecrets'
 export {
   LCMS_DEFAULT_CONTROL_POSITIONS,
   createLcmsControlWellEditData,

package/src/styles/components/secret-input.css

@@ -0,0 +1,60 @@
+/* SecretInput — plugin secret settings field with a set / not set / environment badge. */
+
+.mint-secret-input {
+  display: flex;
+  flex-direction: column;
+  gap: 0.5rem;
+}
+
+.mint-secret-input__status {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  flex-wrap: wrap;
+}
+
+.mint-secret-input__badge {
+  display: inline-flex;
+  align-items: center;
+  border-radius: 999px;
+  padding: 0.125rem 0.5rem;
+  font-size: 0.75rem;
+  font-weight: 500;
+  line-height: 1.4;
+  border: 1px solid transparent;
+  background-color: var(--bg-tertiary);
+  color: var(--text-secondary);
+}
+
+.mint-secret-input__badge--set {
+  background-color: color-mix(in srgb, var(--mint-success) 12%, transparent);
+  border-color: color-mix(in srgb, var(--mint-success) 35%, transparent);
+  color: var(--mint-success);
+}
+
+.mint-secret-input__badge--environment {
+  background-color: color-mix(in srgb, var(--mint-info) 12%, transparent);
+  border-color: color-mix(in srgb, var(--mint-info) 35%, transparent);
+  color: var(--mint-info);
+}
+
+.mint-secret-input__badge--pending {
+  background-color: color-mix(in srgb, var(--mint-warning) 12%, transparent);
+  border-color: color-mix(in srgb, var(--mint-warning) 35%, transparent);
+  color: var(--mint-warning);
+}
+
+.mint-secret-input__hint {
+  font-size: 0.75rem;
+  color: var(--text-muted);
+}
+
+.mint-secret-input__actions {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+}
+
+.mint-secret-input--error .mint-secret-input__badge {
+  border-color: color-mix(in srgb, var(--mint-error) 45%, transparent);
+}

package/src/styles/index.css

@@ -30,6 +30,7 @@
 @import './components/radio-group.css';
 @import './components/sample-legend.css';
 @import './components/section-card.css';
+@import './components/secret-input.css';
 @import './components/select.css';
 @import './components/skeleton.css';
 @import './components/slider.css';