@morscherlab/mint-sdk 1.0.0-beta.2 → 1.0.0-beta.3

package/src/composables/useControlSchema.ts

@@ -0,0 +1,1274 @@
+import { computed, reactive, ref, watch, type ComputedRef, type Ref } from 'vue'
+import type {
+  PillNavItem,
+  SidebarToolSection,
+  SelectOption,
+  SettingsModalSchema,
+  TopBarSettingsConfig,
+  TopBarTab,
+} from '../types'
+import type {
+  FieldCondition,
+  FieldValidation,
+  FormFieldSchema,
+  FormFieldType,
+  FormSchema,
+  FormSectionSchema,
+} from '../types/form-builder'
+import { getTypeDefault } from './formBuilderRegistry'
+import type { WellConcentration } from './useDoseCalculator'
+
+export type ControlOptionValue = string | number | boolean
+export type ControlOption = ControlOptionValue | SelectOption<unknown>
+export type ControlPrimitive = string | number | boolean
+export type ControlShorthand = ControlPrimitive | readonly ControlOption[]
+export type ControlInput = ControlDefinition | ControlShorthand
+
+export interface ControlSectionConfig {
+  id?: string
+  label?: string
+  title?: string
+  description?: string
+  subtitle?: string
+  icon?: string | string[]
+  iconColor?: string
+  iconBg?: string
+  columns?: 1 | 2 | 3
+  condition?: FieldCondition
+  defaultOpen?: boolean
+  showToggle?: boolean
+}
+
+export interface ControlViewConfig {
+  label?: string
+  icon?: string
+  to?: string
+  href?: string
+  disabled?: boolean
+  children?: TopBarTab['children']
+}
+
+export interface ControlSidebarConfig extends Omit<ControlSectionConfig, 'id' | 'title' | 'description' | 'columns'> {
+  enabled?: boolean
+}
+
+export interface ControlDefinition {
+  type?: FormFieldType
+  label?: string
+  default?: unknown
+  defaultValue?: unknown
+  placeholder?: string
+  hint?: string
+  size?: 'sm' | 'md' | 'lg'
+  disabled?: boolean
+  readonly?: boolean
+  required?: boolean | string
+  min?: number | { value: number; message: string }
+  max?: number | { value: number; message: string }
+  minLength?: number | { value: number; message: string }
+  maxLength?: number | { value: number; message: string }
+  email?: boolean | string
+  pattern?: string | { value: string; message: string }
+  validation?: FieldValidation
+  condition?: FieldCondition
+  options?: readonly ControlOption[]
+  section?: string
+  sectionLabel?: string
+  sectionDescription?: string
+  sectionSubtitle?: string
+  view?: string
+  order?: number
+  colSpan?: number
+  props?: Record<string, unknown>
+  sidebar?: boolean | ControlSidebarConfig
+}
+
+export type ControlSchema = Record<string, ControlInput>
+export type ControlFormSchema = Extract<FormSchema, { sections: FormSectionSchema[] }>
+
+export interface ControlSchemaOptions {
+  view?: string
+  views?: Record<string, ControlViewConfig>
+  section?: string
+  sectionLabel?: string
+  sections?: Record<string, ControlSectionConfig>
+  columns?: 1 | 2 | 3
+  submitLabel?: string
+  cancelLabel?: string
+  showCancel?: boolean
+}
+
+export interface ControlWorkspaceOptions extends ControlSchemaOptions {
+  initialValues?: Record<string, unknown>
+  topBarSettings?: Omit<TopBarSettingsConfig, 'schema' | 'controls' | 'controlOptions' | 'values'>
+}
+
+export interface ControlModelSectionConfig extends ControlSectionConfig {
+  controls: ControlSchema
+  sidebar?: boolean | ControlSidebarConfig
+}
+
+export interface ControlModelViewConfig extends ControlViewConfig {
+  controls?: ControlSchema
+  section?: string
+  sectionLabel?: string
+  sectionDescription?: string
+  sections?: Record<string, ControlModelSectionConfig>
+}
+
+export interface ControlModel extends Omit<ControlWorkspaceOptions, 'sections' | 'views'> {
+  controls?: ControlSchema
+  sections?: Record<string, ControlModelSectionConfig>
+  views?: Record<string, ControlModelViewConfig>
+  /** Optional ControlWorkspaceView componentProps mapping returned with the generated controls/options. */
+  componentProps?: ControlComponentPropsMap
+  /** Optional named componentProps mappings returned for multiple SDK components. */
+  componentPropsById?: ControlComponentPropsByIdMap
+}
+
+export interface ControlModelBinding {
+  controls: ControlSchema
+  controlOptions: ControlWorkspaceOptions
+  componentProps?: ControlComponentPropsMap
+  componentPropsById?: ControlComponentPropsByIdMap
+}
+
+export interface ControlSidebarBinding {
+  panels: Record<string, SidebarToolSection[]>
+  forms: Record<string, ControlFormSchema>
+  viewIds: string[]
+  viewItems: PillNavItem[]
+  defaultView: string
+}
+
+export interface ControlFormBinding {
+  schema: ControlFormSchema
+}
+
+export interface ControlSettingsBinding {
+  schema: SettingsModalSchema
+}
+
+export interface ControlTopBarSettingsBinding {
+  showSettings: true
+  settingsConfig: TopBarSettingsConfig
+}
+
+export interface ControlWorkspaceFormBinding extends ControlFormBinding {
+  modelValue: Record<string, unknown>
+  'onUpdate:modelValue': (values: Record<string, unknown>) => void
+}
+
+export interface ControlWorkspaceSidebarBinding extends ControlSidebarBinding {
+  activeView: string
+  modelValue: Record<string, unknown>
+  'onUpdate:modelValue': (values: Record<string, unknown>) => void
+  values: Record<string, unknown>
+  'onUpdate:values': (values: Record<string, unknown>) => void
+}
+
+export interface ControlWorkspaceTopBarSettingsBinding extends ControlTopBarSettingsBinding {
+  onSettingsValuesChange: (values: Record<string, unknown>) => void
+}
+
+export interface ControlWorkspaceTopBarBinding {
+  tabs: TopBarTab[]
+  currentTabId: string
+  onTabSelect: (tab: TopBarTab) => void
+}
+
+export interface ControlWorkspacePillNavBinding {
+  items: PillNavItem[]
+  currentItemId: string
+  onSelect: (item: PillNavItem) => void
+}
+
+export interface ControlWorkspaceAppTopBarPillBinding extends ControlWorkspaceTopBarSettingsBinding {
+  pillNav: PillNavItem[]
+  currentPillId: string
+  onPillSelect: (item: PillNavItem) => void
+}
+
+export interface ControlWorkspaceAppTopBarTabsBinding extends ControlWorkspaceTopBarSettingsBinding {
+  tabs: TopBarTab[]
+  currentTabId: string
+  onTabSelect: (tab: TopBarTab) => void
+}
+
+export interface ControlWorkspaceComponentBindings {
+  form: ControlWorkspaceFormBinding
+  sidebar: ControlWorkspaceSidebarBinding
+  topBar: ComputedRef<ControlWorkspaceAppTopBarPillBinding>
+  topBarTabs: ComputedRef<ControlWorkspaceAppTopBarTabsBinding>
+  topBarSettings: ControlWorkspaceTopBarSettingsBinding
+  pillNav: ControlWorkspacePillNavBinding
+  componentProps: ComputedRef<Record<string, unknown>>
+  componentPropsById: ComputedRef<Record<string, Record<string, unknown>>>
+}
+
+export type ControlComponentPropSource<TValues extends Record<string, unknown> = Record<string, unknown>> =
+  | (keyof TValues & string)
+  | ((values: TValues) => unknown)
+
+export type ControlComponentPropsMap<TValues extends Record<string, unknown> = Record<string, unknown>> =
+  | readonly (keyof TValues & string)[]
+  | Record<string, ControlComponentPropSource<TValues>>
+
+export type ControlComponentPropsByIdMap<TValues extends Record<string, unknown> = Record<string, unknown>> =
+  Record<string, ControlComponentPropsMap<TValues>>
+
+export interface WellPlateControlPropsOptions<TValues extends Record<string, unknown> = Record<string, unknown>> {
+  selectedWells?: ControlComponentPropSource<TValues>
+  format?: ControlComponentPropSource<TValues>
+  wells?: ControlComponentPropSource<TValues>
+  disabled?: ControlComponentPropSource<TValues>
+  readonly?: ControlComponentPropSource<TValues>
+  showLegend?: ControlComponentPropSource<TValues>
+  showSampleTypeIndicator?: ControlComponentPropSource<TValues>
+  /** Listener for WellPlate v-model updates. Set false to keep generated props one-way. */
+  onUpdateModelValue?: ((values: TValues) => (wellIds: string[]) => void) | false
+}
+
+export interface DoseCalculatorControlPropsOptions<TValues extends Record<string, unknown> = Record<string, unknown>> {
+  mode?: ControlComponentPropSource<TValues>
+  targetWells?: ControlComponentPropSource<TValues>
+  /** Control value key used by the default apply-to-wells handler. */
+  wells?: ControlComponentPropSource<TValues>
+  disabled?: ControlComponentPropSource<TValues>
+  molecularWeight?: ControlComponentPropSource<TValues>
+  /** Listener for DoseCalculator apply-to-wells. Set false to keep generated props one-way. */
+  onApplyToWells?: ((values: TValues) => (results: WellConcentration[]) => void) | false
+}
+
+export interface WellPlateDoseControlPropsOptions<TValues extends Record<string, unknown> = Record<string, unknown>> {
+  plateId?: string
+  doseId?: string
+  plate?: WellPlateControlPropsOptions<TValues>
+  dose?: DoseCalculatorControlPropsOptions<TValues>
+}
+
+export interface DoseDesignControlModelOptions {
+  viewId?: string
+  viewLabel?: string
+  sectionId?: string
+  sectionLabel?: string
+  sectionDescription?: string
+  selectedWells?: readonly string[]
+  plateFormat?: number
+  plateFormats?: readonly number[]
+  doseMode?: 'serial' | 'dilution' | 'conversion'
+  doseModes?: readonly ('serial' | 'dilution' | 'conversion')[]
+  disabled?: boolean
+  includeMolecularWeight?: boolean
+  molecularWeight?: number
+  componentProps?: WellPlateDoseControlPropsOptions
+}
+
+export interface UseControlSchemaReturn<TControls extends ControlSchema> {
+  controls: TControls
+  fields: FormFieldSchema[]
+  formSchema: ControlFormSchema
+  form: ControlFormBinding
+  settingsSchema: SettingsModalSchema
+  settings: ControlSettingsBinding
+  topBarSettingsConfig: TopBarSettingsConfig
+  topBarSettings: ControlTopBarSettingsBinding
+  sidebarPanels: Record<string, SidebarToolSection[]>
+  viewIds: string[]
+  viewItems: PillNavItem[]
+  topBarTabs: TopBarTab[]
+  defaultView: string
+  sectionSchemas: Record<string, ControlFormSchema>
+  sidebar: ControlSidebarBinding
+  initialValues: ControlValues<TControls>
+  sectionSchema: (sectionId: string) => ControlFormSchema
+}
+
+export interface UseControlWorkspaceReturn<TControls extends ControlSchema>
+  extends Omit<UseControlSchemaReturn<TControls>, 'form' | 'sidebar' | 'topBarSettings'> {
+  schema: UseControlSchemaReturn<TControls>
+  values: ControlValues<TControls> & Record<string, unknown>
+  activeView: Ref<string>
+  form: ControlWorkspaceFormBinding
+  sidebar: ControlWorkspaceSidebarBinding
+  topBar: ControlWorkspaceTopBarBinding
+  pillNav: ControlWorkspacePillNavBinding
+  topBarSettings: ControlWorkspaceTopBarSettingsBinding
+  bindings: ControlWorkspaceComponentBindings
+  componentProps: ComputedRef<Record<string, unknown>>
+  componentPropsById: ComputedRef<Record<string, Record<string, unknown>>>
+  setActiveView: (viewId: string) => void
+  setValues: (values: Record<string, unknown>) => void
+  resetValues: (values?: Record<string, unknown>) => void
+  getComponentProps: (
+    mapping?: ControlComponentPropsMap<ControlValues<TControls> & Record<string, unknown>>
+  ) => Record<string, unknown>
+  getComponentPropsById: (
+    mappings?: ControlComponentPropsByIdMap<ControlValues<TControls> & Record<string, unknown>>
+  ) => Record<string, Record<string, unknown>>
+}
+
+export type ControlValues<TControls extends ControlSchema> = {
+  [K in keyof TControls]: ControlValue<TControls[K]>
+}
+
+type ControlValue<TControl> =
+  TControl extends { default: infer TDefault }
+    ? TDefault
+    : TControl extends { defaultValue: infer TDefaultValue }
+      ? TDefaultValue
+      : TControl extends readonly [infer First, ...unknown[]]
+        ? OptionValue<First>
+        : TControl extends ControlPrimitive
+          ? TControl
+          : unknown
+
+type OptionValue<TOption> = TOption extends SelectOption<infer TValue> ? TValue : TOption
+
+interface NormalizedControl {
+  name: string
+  definition: ControlDefinition
+  type: FormFieldType
+  sectionId: string
+  viewId: string
+  order: number
+}
+
+/** Preserve literal control keys while marking an object as a MINT control schema. */
+export function defineControls<TControls extends ControlSchema>(controls: TControls): TControls {
+  return controls
+}
+
+/** Flatten a simple view/section control data model into ControlWorkspaceView props for generated forms and sidebars. */
+export function defineControlModel(model: ControlModel): ControlModelBinding {
+  const {
+    controls: rootControls,
+    sections: rootSections,
+    views: modelViews,
+    componentProps,
+    componentPropsById,
+    ...baseOptions
+  } = model
+  const controls: ControlSchema = {}
+  const views: Record<string, ControlViewConfig> = {}
+  const sections: Record<string, ControlSectionConfig> = {}
+
+  const defaultViewId = model.view ?? 'default'
+  const defaultSectionId = model.section ?? 'controls'
+
+  if (rootControls) {
+    registerSectionOptions(sections, defaultSectionId, {
+      id: defaultSectionId,
+      label: model.sectionLabel,
+      title: model.sectionLabel,
+      columns: model.columns,
+    })
+    appendModelControls(controls, rootControls, defaultViewId, defaultSectionId)
+  }
+
+  for (const [sectionId, section] of Object.entries(rootSections ?? {})) {
+    registerSectionOptions(sections, sectionId, controlModelSectionOptions(section))
+    appendModelControls(controls, section.controls, defaultViewId, sectionId, section.sidebar)
+  }
+
+  for (const [viewId, view] of Object.entries(modelViews ?? {})) {
+    const {
+      controls: viewControls,
+      sections: viewSections,
+      section,
+      sectionLabel,
+      sectionDescription,
+      ...viewConfig
+    } = view
+
+    views[viewId] = omitUndefined(viewConfig)
+
+    if (viewControls) {
+      const sectionId = section ?? `${viewId}-controls`
+      const label = sectionLabel ?? view.label
+      registerSectionOptions(sections, sectionId, {
+        id: sectionId,
+        label,
+        title: label,
+        description: sectionDescription,
+        columns: model.columns,
+      })
+      appendModelControls(controls, viewControls, viewId, sectionId)
+    }
+
+    for (const [sectionKey, sectionConfig] of Object.entries(viewSections ?? {})) {
+      const sectionId = sectionConfig.id ?? `${viewId}-${sectionKey}`
+      registerSectionOptions(sections, sectionId, controlModelSectionOptions(sectionConfig))
+      appendModelControls(controls, sectionConfig.controls, viewId, sectionId, sectionConfig.sidebar)
+    }
+  }
+
+  const controlOptions: ControlWorkspaceOptions = {
+    ...baseOptions,
+  }
+
+  if (Object.keys(views).length > 0) {
+    controlOptions.views = views
+  }
+
+  if (Object.keys(sections).length > 0) {
+    controlOptions.sections = sections
+  }
+
+  return {
+    controls,
+    controlOptions,
+    ...(componentProps === undefined ? {} : { componentProps }),
+    ...(componentPropsById === undefined ? {} : { componentPropsById }),
+  }
+}
+
+/** Build default values for a control schema, matching FormBuilder field defaults. */
+export function getControlDefaults<TControls extends ControlSchema>(
+  controls: TControls,
+): ControlValues<TControls> {
+  const values: Record<string, unknown> = {}
+  for (const control of normalizeControls(controls)) {
+    values[control.name] = defaultValueForControl(control.definition, control.type)
+  }
+  return values as ControlValues<TControls>
+}
+
+/** Map control workspace values into component props for direct `v-bind` usage. */
+export function controlValuesToComponentProps<TValues extends Record<string, unknown>>(
+  values: TValues,
+  mapping?: ControlComponentPropsMap<TValues>,
+): Record<string, unknown> {
+  if (mapping === undefined) return { ...values }
+
+  if (Array.isArray(mapping)) {
+    const props: Record<string, unknown> = {}
+    for (const key of mapping) {
+      props[key] = values[key]
+    }
+    return props
+  }
+
+  const props: Record<string, unknown> = {}
+  for (const [prop, source] of Object.entries(mapping) as Array<[string, ControlComponentPropSource<TValues>]>) {
+    props[prop] = typeof source === 'function' ? source(values) : values[source]
+  }
+  return props
+}
+
+/** Return a default WellPlate prop mapping for generated control workspaces. */
+export function defineWellPlateControlProps<TValues extends Record<string, unknown> = Record<string, unknown>>(
+  options: WellPlateControlPropsOptions<TValues> = {},
+): ControlComponentPropsMap<TValues> {
+  const selectedWells = options.selectedWells ?? sourceKey<TValues>('selectedWells')
+  const onUpdateModelValue = options.onUpdateModelValue === false
+    ? undefined
+    : options.onUpdateModelValue ?? updateControlValueSource(selectedWells)
+
+  return compactComponentPropsMap<TValues>({
+    modelValue: selectedWells,
+    'onUpdate:modelValue': onUpdateModelValue,
+    format: options.format ?? sourceKey<TValues>('plateFormat'),
+    wells: options.wells ?? sourceKey<TValues>('wells'),
+    disabled: options.disabled ?? sourceKey<TValues>('disabled'),
+    readonly: options.readonly ?? sourceKey<TValues>('readonly'),
+    showLegend: options.showLegend,
+    showSampleTypeIndicator: options.showSampleTypeIndicator,
+  })
+}
+
+/** Return a default DoseCalculator prop mapping for generated control workspaces. */
+export function defineDoseCalculatorControlProps<TValues extends Record<string, unknown> = Record<string, unknown>>(
+  options: DoseCalculatorControlPropsOptions<TValues> = {},
+): ControlComponentPropsMap<TValues> {
+  const targetWells = options.targetWells ?? sourceKey<TValues>('selectedWells')
+  const wells = options.wells ?? sourceKey<TValues>('wells')
+  const onApplyToWells = options.onApplyToWells === false
+    ? undefined
+    : options.onApplyToWells ?? defaultDoseApplyHandler(wells, targetWells)
+
+  return compactComponentPropsMap<TValues>({
+    mode: options.mode ?? sourceKey<TValues>('doseMode'),
+    targetWells,
+    disabled: options.disabled ?? sourceKey<TValues>('disabled'),
+    molecularWeight: options.molecularWeight,
+    onApplyToWells,
+  })
+}
+
+/** Return named WellPlate + DoseCalculator prop mappings for one dose-design control model. */
+export function defineWellPlateDoseControlProps<TValues extends Record<string, unknown> = Record<string, unknown>>(
+  options: WellPlateDoseControlPropsOptions<TValues> = {},
+): ControlComponentPropsByIdMap<TValues> {
+  return {
+    [options.plateId ?? 'plate']: defineWellPlateControlProps(options.plate),
+    [options.doseId ?? 'dose']: defineDoseCalculatorControlProps(options.dose),
+  }
+}
+
+/** Return a complete ControlWorkspaceView model for WellPlate + DoseCalculator dose design. */
+export function defineDoseDesignControlModel(
+  options: DoseDesignControlModelOptions = {},
+): ControlModelBinding {
+  const viewId = options.viewId ?? 'design'
+  const sectionId = options.sectionId ?? 'dose'
+  const doseControls: ControlSchema = {
+    selectedWells: {
+      type: 'tags',
+      label: 'Selected wells',
+      default: [...(options.selectedWells ?? ['A1', 'A2'])],
+    },
+    plateFormat: {
+      label: 'Plate format',
+      default: options.plateFormat ?? 96,
+      options: options.plateFormats ?? [96, 384],
+    },
+    doseMode: {
+      label: 'Dose mode',
+      default: options.doseMode ?? 'serial',
+      options: options.doseModes ?? ['serial', 'dilution', 'conversion'],
+    },
+    disabled: {
+      label: 'Disable tools',
+      default: options.disabled ?? false,
+    },
+  }
+
+  if (options.includeMolecularWeight) {
+    doseControls.molecularWeight = {
+      type: 'number',
+      label: 'Molecular weight',
+      default: options.molecularWeight ?? 300,
+      min: 0,
+    }
+  }
+
+  return defineControlModel({
+    componentPropsById: defineWellPlateDoseControlProps({
+      ...options.componentProps,
+      dose: {
+        ...(options.componentProps?.dose ?? {}),
+        ...(options.includeMolecularWeight && options.componentProps?.dose?.molecularWeight === undefined
+          ? { molecularWeight: 'molecularWeight' }
+          : {}),
+      },
+    }),
+    views: {
+      [viewId]: {
+        label: options.viewLabel ?? 'Design',
+        sections: {
+          [sectionId]: {
+            label: options.sectionLabel ?? 'Dose design',
+            description: options.sectionDescription ?? 'Well selection and dose calculator controls',
+            controls: doseControls,
+          },
+        },
+      },
+    },
+  })
+}
+
+function isControlModelBindingInput<TControls extends ControlSchema>(
+  value: TControls | (ControlModelBinding & { controls: TControls }),
+): value is ControlModelBinding & { controls: TControls } {
+  return (
+    typeof value === 'object'
+    && value !== null
+    && 'controls' in value
+    && 'controlOptions' in value
+  )
+}
+
+export function mergeControlWorkspaceOptions(
+  base?: ControlWorkspaceOptions,
+  override?: ControlWorkspaceOptions,
+): ControlWorkspaceOptions {
+  return {
+    ...(base ?? {}),
+    ...(override ?? {}),
+    initialValues: {
+      ...(base?.initialValues ?? {}),
+      ...(override?.initialValues ?? {}),
+    },
+    topBarSettings: {
+      ...(base?.topBarSettings ?? {}),
+      ...(override?.topBarSettings ?? {}),
+    },
+  }
+}
+
+/** Convert a compact control schema into a FormBuilder schema. */
+export function controlsToFormSchema(
+  controls: ControlSchema,
+  options: ControlSchemaOptions = {},
+): ControlFormSchema {
+  const normalized = normalizeControls(controls, options)
+  const sectionIds = orderedUnique(normalized.map(control => control.sectionId))
+  const sections = sectionIds.map((sectionId): FormSectionSchema => {
+    const sectionControls = normalized.filter(control => control.sectionId === sectionId)
+    const config = sectionConfig(sectionId, sectionControls, options)
+    return {
+      id: sectionId,
+      title: config.title ?? config.label ?? humanize(sectionId),
+      description: config.description,
+      columns: config.columns ?? options.columns ?? 1,
+      defaultOpen: config.defaultOpen,
+      condition: config.condition,
+      fields: sectionControls.map(controlToFormField),
+    }
+  })
+
+  return {
+    sections,
+    submitLabel: options.submitLabel,
+    cancelLabel: options.cancelLabel,
+    showCancel: options.showCancel,
+  }
+}
+
+/** Convert controls into AppSidebar panels grouped by view and section. */
+export function controlsToSidebarPanels(
+  controls: ControlSchema,
+  options: ControlSchemaOptions = {},
+): Record<string, SidebarToolSection[]> {
+  const normalized = normalizeControls(controls, options)
+    .filter(control => isSidebarEnabled(control.definition.sidebar))
+  const viewIds = orderedUnique(normalized.map(control => control.viewId))
+  const panels: Record<string, SidebarToolSection[]> = {}
+
+  for (const viewId of viewIds) {
+    const viewControls = normalized.filter(control => control.viewId === viewId)
+    const sectionIds = orderedUnique(viewControls.map(control => control.sectionId))
+    panels[viewId] = sectionIds.map((sectionId): SidebarToolSection => {
+      const sectionControls = viewControls.filter(control => control.sectionId === sectionId)
+      const config = sectionConfig(sectionId, sectionControls, options)
+      const sidebarConfig = firstSidebarConfig(sectionControls)
+      return {
+        id: sectionId,
+        label: sidebarConfig?.label ?? config.label ?? config.title ?? humanize(sectionId),
+        subtitle: sidebarConfig?.subtitle ?? config.subtitle,
+        icon: sidebarConfig?.icon ?? config.icon,
+        iconColor: sidebarConfig?.iconColor ?? config.iconColor,
+        iconBg: sidebarConfig?.iconBg ?? config.iconBg,
+        defaultOpen: sidebarConfig?.defaultOpen ?? config.defaultOpen,
+        showToggle: sidebarConfig?.showToggle ?? config.showToggle,
+      }
+    })
+  }
+
+  return panels
+}
+
+/** Convert controls into a SettingsModal schema grouped by the same sections. */
+export function controlsToSettingsSchema(
+  controls: ControlSchema,
+  options: ControlSchemaOptions = {},
+): SettingsModalSchema {
+  const normalized = normalizeControls(controls, options)
+  const sectionIds = orderedUnique(normalized.map(control => control.sectionId))
+
+  return {
+    groups: sectionIds.map((sectionId) => {
+      const sectionControls = normalized.filter(control => control.sectionId === sectionId)
+      const config = sectionConfig(sectionId, sectionControls, options)
+      return {
+        id: sectionId,
+        label: config.label ?? config.title ?? humanize(sectionId),
+        description: config.description ?? config.subtitle,
+        icon: typeof config.icon === 'string' ? config.icon : undefined,
+        fields: sectionControls.map(controlToFormField),
+        columns: config.columns ?? options.columns ?? 1,
+        condition: config.condition,
+      }
+    }),
+  }
+}
+
+/** Convert controls into an AppTopBar settingsConfig object that passes compact controls through to SettingsModal. */
+export function controlsToTopBarSettingsConfig(
+  controls: ControlSchema,
+  options: ControlSchemaOptions = {},
+  config: Omit<TopBarSettingsConfig, 'schema' | 'controls' | 'controlOptions'> = {},
+): TopBarSettingsConfig {
+  return {
+    ...config,
+    controls,
+    controlOptions: options,
+  }
+}
+
+/** Return generated control view IDs that have at least one sidebar panel. */
+export function controlsToViewIds(
+  controls: ControlSchema,
+  options: ControlSchemaOptions = {},
+): string[] {
+  return controlsToViewItems(controls, options).map(item => item.id)
+}
+
+/** Return AppPillNav-compatible view items for switching generated control sidebars. */
+export function controlsToViewItems(
+  controls: ControlSchema,
+  options: ControlSchemaOptions = {},
+): PillNavItem[] {
+  return Object.entries(controlsToSidebarPanels(controls, options))
+    .filter(([, sections]) => sections.length > 0)
+    .map(([id]) => controlViewItem(id, options))
+}
+
+/** Return AppTopBar-compatible tabs for the same views that drive generated AppSidebar panels. */
+export function controlsToTopBarTabs(
+  controls: ControlSchema,
+  options: ControlSchemaOptions = {},
+): TopBarTab[] {
+  return Object.entries(controlsToSidebarPanels(controls, options))
+    .filter(([, sections]) => sections.length > 0)
+    .map(([id]) => controlTopBarTab(id, options))
+}
+
+/** Return the first generated sidebar view ID, or an empty string when controls render no sidebar panels. */
+export function getDefaultControlView(
+  controls: ControlSchema,
+  options: ControlSchemaOptions = {},
+): string {
+  return controlsToViewIds(controls, options)[0] ?? ''
+}
+
+/** Return a headerless single-section FormBuilder schema for rendering inside an AppSidebar section slot. */
+export function controlsToSectionFormSchema(
+  controls: ControlSchema,
+  sectionId: string,
+  options: ControlSchemaOptions = {},
+): ControlFormSchema {
+  const schema = controlsToFormSchema(controls, options)
+  return {
+    sections: schema.sections
+      .filter(section => section.id === sectionId)
+      .map(section => ({ ...section, title: '', description: undefined })),
+    submitLabel: schema.submitLabel,
+    cancelLabel: schema.cancelLabel,
+    showCancel: schema.showCancel,
+  }
+}
+
+/** Return headerless FormBuilder schemas keyed by section ID for AppSidebar auto-rendering. */
+export function controlsToSectionFormSchemas(
+  controls: ControlSchema,
+  options: ControlSchemaOptions = {},
+): Record<string, ControlFormSchema> {
+  const schema = controlsToFormSchema(controls, options)
+  const schemas: Record<string, ControlFormSchema> = {}
+  for (const section of schema.sections) {
+    schemas[section.id] = {
+      sections: [{ ...section, title: '', description: undefined }],
+      submitLabel: schema.submitLabel,
+      cancelLabel: schema.cancelLabel,
+      showCancel: schema.showCancel,
+    }
+  }
+  return schemas
+}
+
+/** Prepare FormBuilder, SettingsModal, AppTopBar settings, AppSidebar, and initial values from one compact control model. */
+export function useControlSchema<TControls extends ControlSchema>(
+  controls: TControls,
+  options: ControlSchemaOptions = {},
+): UseControlSchemaReturn<TControls> {
+  const formSchema = controlsToFormSchema(controls, options)
+  const settingsSchema = controlsToSettingsSchema(controls, options)
+  const topBarSettingsConfig = controlsToTopBarSettingsConfig(controls, options)
+  const sidebarPanels = controlsToSidebarPanels(controls, options)
+  const viewItems = controlsToViewItems(controls, options)
+  const viewIds = viewItems.map(item => item.id)
+  const topBarTabs = controlsToTopBarTabs(controls, options)
+  const defaultView = viewIds[0] ?? ''
+  const sectionSchemas = controlsToSectionFormSchemas(controls, options)
+
+  return {
+    controls,
+    fields: normalizeControls(controls, options).map(controlToFormField),
+    formSchema,
+    form: {
+      schema: formSchema,
+    },
+    settingsSchema,
+    settings: {
+      schema: settingsSchema,
+    },
+    topBarSettingsConfig,
+    topBarSettings: {
+      showSettings: true,
+      settingsConfig: topBarSettingsConfig,
+    },
+    sidebarPanels,
+    viewIds,
+    viewItems,
+    topBarTabs,
+    defaultView,
+    sectionSchemas,
+    sidebar: {
+      panels: sidebarPanels,
+      forms: sectionSchemas,
+      viewIds,
+      viewItems,
+      defaultView,
+    },
+    initialValues: getControlDefaults(controls),
+    sectionSchema: (sectionId: string) => controlsToSectionFormSchema(controls, sectionId, options),
+  }
+}
+
+/** Prepare shared reactive values plus AppTopBar/AppSidebar/FormBuilder bindings from one simple controls data model. */
+export function useControlWorkspace<TControls extends ControlSchema>(
+  controlsOrModel: TControls | (ControlModelBinding & { controls: TControls }),
+  options: ControlWorkspaceOptions = {},
+): UseControlWorkspaceReturn<TControls> {
+  const model = isControlModelBindingInput<TControls>(controlsOrModel) ? controlsOrModel : undefined
+  const controls: TControls = model ? model.controls : controlsOrModel as TControls
+  const workspaceOptions = model
+    ? mergeControlWorkspaceOptions(model.controlOptions, options)
+    : options
+  const { initialValues, topBarSettings, ...schemaOptions } = workspaceOptions
+  const schema = useControlSchema(controls, schemaOptions)
+  const activeView = ref(schema.defaultView)
+  const values = reactive({
+    ...schema.initialValues,
+    ...(initialValues ?? {}),
+  }) as ControlValues<TControls> & Record<string, unknown>
+
+  function setActiveView(viewId: string) {
+    syncActiveView(viewId)
+  }
+
+  function syncActiveView(viewId: string) {
+    if (!schema.viewIds.includes(viewId)) return
+    if (activeView.value !== viewId) activeView.value = viewId
+    if (sidebar.activeView !== viewId) sidebar.activeView = viewId
+    if (topBar.currentTabId !== viewId) topBar.currentTabId = viewId
+    if (pillNav.currentItemId !== viewId) pillNav.currentItemId = viewId
+  }
+
+  function setValues(nextValues: Record<string, unknown>) {
+    Object.assign(values, nextValues)
+  }
+
+  function resetValues(nextValues: Record<string, unknown> = {}) {
+    replaceRecord(values, {
+      ...schema.initialValues,
+      ...nextValues,
+    })
+  }
+
+  function getComponentProps(
+    mapping?: ControlComponentPropsMap<ControlValues<TControls> & Record<string, unknown>>,
+  ): Record<string, unknown> {
+    return controlValuesToComponentProps(values, mapping)
+  }
+
+  function getComponentPropsById(
+    mappings?: ControlComponentPropsByIdMap<ControlValues<TControls> & Record<string, unknown>>,
+  ): Record<string, Record<string, unknown>> {
+    if (mappings === undefined) return {}
+
+    return Object.fromEntries(
+      Object.entries(mappings).map(([id, mapping]) => [
+        id,
+        controlValuesToComponentProps(values, mapping),
+      ]),
+    )
+  }
+  const componentProps = computed(() => (
+    model?.componentProps === undefined ? {} : getComponentProps(model.componentProps)
+  ))
+  const componentPropsById = computed(() => getComponentPropsById(model?.componentPropsById))
+  const form = {
+    ...schema.form,
+    modelValue: values,
+    'onUpdate:modelValue': setValues,
+  } as ControlWorkspaceFormBinding
+
+  const topBarSettingsConfig: TopBarSettingsConfig = {
+    ...schema.topBarSettingsConfig,
+    ...(topBarSettings ?? {}),
+    values,
+  }
+  const sidebar = reactive({
+    ...schema.sidebar,
+    activeView: activeView.value,
+    modelValue: values,
+    'onUpdate:modelValue': setValues,
+    values,
+    'onUpdate:values': setValues,
+  }) as ControlWorkspaceSidebarBinding
+  const topBar = reactive({
+    tabs: schema.topBarTabs,
+    currentTabId: activeView.value,
+    onTabSelect: (tab: TopBarTab) => setActiveView(tab.id),
+  }) as ControlWorkspaceTopBarBinding
+  const pillNav = reactive({
+    items: schema.viewItems,
+    currentItemId: activeView.value,
+    onSelect: (item: PillNavItem) => setActiveView(item.id),
+  }) as ControlWorkspacePillNavBinding
+  const topBarSettingsBinding = {
+    showSettings: true,
+    settingsConfig: topBarSettingsConfig,
+    onSettingsValuesChange: setValues,
+  } as ControlWorkspaceTopBarSettingsBinding
+  const topBarProps = computed<ControlWorkspaceAppTopBarPillBinding>(() => ({
+    pillNav: pillNav.items,
+    currentPillId: pillNav.currentItemId,
+    onPillSelect: pillNav.onSelect,
+    ...topBarSettingsBinding,
+  }))
+  const topBarTabsProps = computed<ControlWorkspaceAppTopBarTabsBinding>(() => ({
+    tabs: topBar.tabs,
+    currentTabId: topBar.currentTabId,
+    onTabSelect: topBar.onTabSelect,
+    ...topBarSettingsBinding,
+  }))
+  const bindings: ControlWorkspaceComponentBindings = {
+    form,
+    sidebar,
+    topBar: topBarProps,
+    topBarTabs: topBarTabsProps,
+    topBarSettings: topBarSettingsBinding,
+    pillNav,
+    componentProps,
+    componentPropsById,
+  }
+
+  watch(activeView, syncActiveView, { flush: 'sync' })
+  watch(() => sidebar.activeView, syncActiveView, { flush: 'sync' })
+  watch(() => topBar.currentTabId, syncActiveView, { flush: 'sync' })
+  watch(() => pillNav.currentItemId, syncActiveView, { flush: 'sync' })
+
+  return {
+    ...schema,
+    schema,
+    values,
+    activeView,
+    topBarSettingsConfig,
+    form,
+    sidebar,
+    topBar,
+    pillNav,
+    topBarSettings: topBarSettingsBinding,
+    bindings,
+    componentProps,
+    componentPropsById,
+    setActiveView,
+    setValues,
+    resetValues,
+    getComponentProps,
+    getComponentPropsById,
+  }
+}
+
+function normalizeControls(
+  controls: ControlSchema,
+  options: ControlSchemaOptions = {},
+): NormalizedControl[] {
+  return Object.entries(controls)
+    .map(([name, input], index): NormalizedControl => {
+      const definition = normalizeControlDefinition(input)
+      const type = definition.type ?? inferControlType(definition)
+      return {
+        name,
+        definition,
+        type,
+        sectionId: definition.section ?? options.section ?? 'controls',
+        viewId: definition.view ?? options.view ?? 'default',
+        order: definition.order ?? index,
+      }
+    })
+    .sort((a, b) => a.order - b.order)
+}
+
+function normalizeControlDefinition(input: ControlInput): ControlDefinition {
+  if (isControlOptionArray(input)) {
+    if (input.length === 0) return { type: 'tags', default: [] }
+    return {
+      default: optionValue(input[0]),
+      options: input,
+    }
+  }
+
+  if (typeof input === 'string' || typeof input === 'number' || typeof input === 'boolean') {
+    return { default: input }
+  }
+
+  return input
+}
+
+function appendModelControls(
+  target: ControlSchema,
+  source: ControlSchema,
+  viewId: string,
+  sectionId: string,
+  sidebar?: boolean | ControlSidebarConfig,
+): void {
+  for (const [name, input] of Object.entries(source)) {
+    if (Object.prototype.hasOwnProperty.call(target, name)) {
+      throw new Error(
+        `Duplicate control "${name}" in defineControlModel(). Control names must be unique across views and sections.`,
+      )
+    }
+
+    const definition = normalizeControlDefinition(input)
+    target[name] = omitUndefined({
+      ...definition,
+      view: definition.view ?? viewId,
+      section: definition.section ?? sectionId,
+      sidebar: definition.sidebar ?? sidebar,
+    })
+  }
+}
+
+function controlModelSectionOptions(section: ControlModelSectionConfig): ControlSectionConfig {
+  const { controls: _controls, sidebar: _sidebar, ...options } = section
+  return omitUndefined(options)
+}
+
+function registerSectionOptions(
+  target: Record<string, ControlSectionConfig>,
+  sectionId: string,
+  options: ControlSectionConfig,
+): void {
+  target[sectionId] = omitUndefined({
+    ...(target[sectionId] ?? {}),
+    ...options,
+    id: sectionId,
+  })
+}
+
+function isControlOptionArray(input: ControlInput): input is readonly ControlOption[] {
+  return Array.isArray(input)
+}
+
+function inferControlType(definition: ControlDefinition): FormFieldType {
+  const value = definition.default ?? definition.defaultValue
+  if (definition.options?.length) return Array.isArray(value) ? 'multiselect' : 'select'
+  if (typeof value === 'boolean') return 'toggle'
+  if (typeof value === 'number') return 'number'
+  if (Array.isArray(value)) return 'tags'
+  return 'text'
+}
+
+function defaultValueForControl(definition: ControlDefinition, type: FormFieldType): unknown {
+  if (definition.default !== undefined) return definition.default
+  if (definition.defaultValue !== undefined) return definition.defaultValue
+  return getTypeDefault(type)
+}
+
+function controlToFormField(control: NormalizedControl): FormFieldSchema {
+  const { name, definition, type } = control
+  const props = fieldProps(definition)
+  return {
+    name,
+    label: definition.label ?? humanize(name),
+    type,
+    defaultValue: defaultValueForControl(definition, type),
+    placeholder: definition.placeholder,
+    hint: definition.hint,
+    size: definition.size,
+    disabled: definition.disabled,
+    readonly: definition.readonly,
+    validation: validationForControl(definition),
+    condition: definition.condition,
+    colSpan: definition.colSpan,
+    props,
+  }
+}
+
+function fieldProps(definition: ControlDefinition): Record<string, unknown> {
+  const props: Record<string, unknown> = {}
+  if (definition.min !== undefined) props.min = numericValue(definition.min)
+  if (definition.max !== undefined) props.max = numericValue(definition.max)
+  if (definition.options) props.options = definition.options.map(normalizeOption)
+  return { ...props, ...(definition.props ?? {}) }
+}
+
+function validationForControl(definition: ControlDefinition): FieldValidation | undefined {
+  const validation: FieldValidation = { ...(definition.validation ?? {}) }
+  if (definition.required !== undefined) validation.required = definition.required
+  if (definition.min !== undefined) validation.min = definition.min
+  if (definition.max !== undefined) validation.max = definition.max
+  if (definition.minLength !== undefined) validation.minLength = definition.minLength
+  if (definition.maxLength !== undefined) validation.maxLength = definition.maxLength
+  if (definition.email !== undefined) validation.email = definition.email
+  if (definition.pattern !== undefined) validation.pattern = definition.pattern
+  return Object.keys(validation).length > 0 ? validation : undefined
+}
+
+function sectionConfig(
+  sectionId: string,
+  controls: NormalizedControl[],
+  options: ControlSchemaOptions,
+): ControlSectionConfig {
+  const configured = options.sections?.[sectionId]
+  const first = controls[0]?.definition
+  return {
+    ...configured,
+    id: sectionId,
+    label: configured?.label ?? first?.sectionLabel,
+    title: configured?.title ?? first?.sectionLabel,
+    description: configured?.description ?? first?.sectionDescription,
+    subtitle: configured?.subtitle ?? first?.sectionSubtitle,
+  }
+}
+
+function firstSidebarConfig(controls: NormalizedControl[]): ControlSidebarConfig | undefined {
+  for (const control of controls) {
+    const sidebar = control.definition.sidebar
+    if (sidebar && typeof sidebar === 'object' && sidebar.enabled !== false) return sidebar
+  }
+  return undefined
+}
+
+function isSidebarEnabled(sidebar: ControlDefinition['sidebar']): boolean {
+  if (sidebar === false) return false
+  if (sidebar && typeof sidebar === 'object') return sidebar.enabled !== false
+  return true
+}
+
+function normalizeOption(option: ControlOption): SelectOption<unknown> {
+  if (typeof option === 'object' && option !== null && 'label' in option) {
+    return option
+  }
+  return {
+    value: option,
+    label: humanize(String(option)),
+  }
+}
+
+function optionValue(option: ControlOption): ControlOptionValue | unknown {
+  if (typeof option === 'object' && option !== null && 'value' in option) {
+    return option.value
+  }
+  return option
+}
+
+function compactComponentPropsMap<TValues extends Record<string, unknown>>(
+  mapping: Record<string, ControlComponentPropSource<TValues> | undefined>,
+): ControlComponentPropsMap<TValues> {
+  return Object.fromEntries(
+    Object.entries(mapping).filter((entry): entry is [string, ControlComponentPropSource<TValues>] =>
+      entry[1] !== undefined
+    ),
+  )
+}
+
+function sourceKey<TValues extends Record<string, unknown>>(key: string): keyof TValues & string {
+  return key as keyof TValues & string
+}
+
+function updateControlValueSource<TValues extends Record<string, unknown>>(
+  source: ControlComponentPropSource<TValues>,
+): ((values: TValues) => (value: string[]) => void) | undefined {
+  if (typeof source !== 'string') return undefined
+  return values => (value: string[]) => {
+    const writableValues = values as Record<string, unknown>
+    writableValues[source] = value
+  }
+}
+
+function defaultDoseApplyHandler<TValues extends Record<string, unknown>>(
+  wells: ControlComponentPropSource<TValues>,
+  targetWells: ControlComponentPropSource<TValues>,
+): ((values: TValues) => (results: WellConcentration[]) => void) | undefined {
+  if (wells === targetWells) return undefined
+  return updateWellsFromDoseResults(wells)
+}
+
+function updateWellsFromDoseResults<TValues extends Record<string, unknown>>(
+  source: ControlComponentPropSource<TValues>,
+): ((values: TValues) => (results: WellConcentration[]) => void) | undefined {
+  if (typeof source !== 'string') return undefined
+  return values => (results: WellConcentration[]) => {
+    const writableValues = values as Record<string, unknown>
+    const currentWells = recordValue(writableValues[source])
+    const nextWells: Record<string, Record<string, unknown>> = {}
+    for (const [wellId, well] of Object.entries(currentWells)) {
+      nextWells[wellId] = recordValue(well)
+    }
+
+    for (const result of results) {
+      const existing = recordValue(nextWells[result.wellId])
+      const metadata = recordValue(existing.metadata)
+      nextWells[result.wellId] = {
+        ...existing,
+        state: 'filled',
+        value: result.concentration.value,
+        metadata: {
+          ...metadata,
+          concentration: result.concentration,
+          ...(result.volume === undefined ? {} : { volume: result.volume }),
+        },
+      }
+    }
+
+    writableValues[source] = nextWells
+  }
+}
+
+function recordValue(value: unknown): Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : {}
+}
+
+function numericValue(value: number | { value: number; message: string }): number {
+  return typeof value === 'number' ? value : value.value
+}
+
+function orderedUnique(values: string[]): string[] {
+  return [...new Set(values)]
+}
+
+function controlViewItem(viewId: string, options: ControlSchemaOptions): PillNavItem {
+  const config = options.views?.[viewId]
+  return {
+    id: viewId,
+    label: config?.label ?? humanize(viewId),
+    ...(config?.icon !== undefined ? { icon: config.icon } : {}),
+    ...(config?.to !== undefined ? { to: config.to } : {}),
+    ...(config?.href !== undefined ? { href: config.href } : {}),
+    ...(config?.disabled !== undefined ? { disabled: config.disabled } : {}),
+  }
+}
+
+function controlTopBarTab(viewId: string, options: ControlSchemaOptions): TopBarTab {
+  const config = options.views?.[viewId]
+  return {
+    id: viewId,
+    label: config?.label ?? humanize(viewId),
+    ...(config?.to !== undefined ? { to: config.to } : {}),
+    ...(config?.href !== undefined ? { href: config.href } : {}),
+    ...(config?.icon !== undefined ? { icon: config.icon } : {}),
+    ...(config?.disabled !== undefined ? { disabled: config.disabled } : {}),
+    ...(config?.children !== undefined ? { children: config.children } : {}),
+  }
+}
+
+function replaceRecord(target: Record<string, unknown>, values: Record<string, unknown>) {
+  for (const key of Object.keys(target)) {
+    delete target[key]
+  }
+  Object.assign(target, values)
+}
+
+function omitUndefined<T extends object>(record: T): T {
+  const next: Record<string, unknown> = {}
+  for (const [key, value] of Object.entries(record as Record<string, unknown>)) {
+    if (value !== undefined) next[key] = value
+  }
+  return next as T
+}
+
+function humanize(value: string): string {
+  return value
+    .replace(/[_-]+/g, ' ')
+    .replace(/([a-z])([A-Z])/g, '$1 $2')
+    .trim()
+    .replace(/\w\S*/g, word => word.charAt(0).toUpperCase() + word.slice(1))
+}