@morscherlab/mint-sdk 1.0.0-rc.2 → 1.0.0-rc.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@morscherlab/mint-sdk",
-  "version": "1.0.0-rc.2",
+  "version": "1.0.0-rc.4",
   "description": "MINT Platform SDK — Vue 3 components, composables, and types for plugin development. MINT = Mass-spec INtegrated Toolkit.",
   "type": "module",
   "main": "./dist/index.js",

package/src/composables/controlComponentBindings.ts

@@ -0,0 +1,80 @@
+import type {
+  ControlComponentBinding,
+  ControlComponentBindingConfig,
+  ControlComponentBindingRecordConfig,
+  ControlComponentBindingsById,
+  ControlComponentBindingsConfig,
+  ControlComponentPropsMap,
+  ControlComponentPropSource,
+} from './useControlSchema'
+
+/** 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
+}
+
+/** Map control workspace values into named SDK component bindings for direct slot rendering. */
+export function controlValuesToComponentBindings<TValues extends Record<string, unknown>>(
+  values: TValues,
+  bindings?: ControlComponentBindingsConfig<TValues>,
+): ControlComponentBinding[] {
+  if (bindings === undefined) return []
+
+  return normalizeControlComponentBindingConfigs(bindings).map(binding => ({
+    id: binding.id,
+    component: binding.component,
+    props: controlValuesToComponentProps(values, binding.props),
+  }))
+}
+
+/** Map control workspace values into SDK component bindings keyed by binding id. */
+export function controlValuesToComponentBindingsById<TValues extends Record<string, unknown>>(
+  values: TValues,
+  bindings?: ControlComponentBindingsConfig<TValues>,
+): ControlComponentBindingsById {
+  return Object.fromEntries(
+    controlValuesToComponentBindings(values, bindings).map(binding => [binding.id, binding]),
+  )
+}
+
+function normalizeControlComponentBindingConfigs<TValues extends Record<string, unknown>>(
+  bindings: ControlComponentBindingsConfig<TValues>,
+): Array<Required<Pick<ControlComponentBindingConfig<TValues>, 'id' | 'component'>> & Pick<ControlComponentBindingConfig<TValues>, 'props'>> {
+  if (Array.isArray(bindings)) {
+    const usedIds = new Map<string, number>()
+    return bindings.map(binding => ({
+      id: uniqueComponentBindingId(binding.id ?? binding.component, usedIds),
+      component: binding.component,
+      props: binding.props,
+    }))
+  }
+
+  return Object.entries(bindings).map(([id, binding]: [string, ControlComponentBindingRecordConfig<TValues>]) => ({
+    id,
+    component: binding.component,
+    props: binding.props,
+  }))
+}
+
+function uniqueComponentBindingId(id: string, usedIds: Map<string, number>): string {
+  const count = usedIds.get(id) ?? 0
+  usedIds.set(id, count + 1)
+  return count === 0 ? id : `${id}-${count + 1}`
+}

package/src/composables/controlSchemaAdapters.ts

@@ -0,0 +1,196 @@
+import type {
+  PillNavItem,
+  SidebarToolSection,
+  SettingsModalSchema,
+  TopBarSettingsConfig,
+} from '../types'
+import type {
+  FormSectionSchema,
+} from '../types/form-builder'
+import {
+  controlToFormField,
+} from './controlSchemaFormFields'
+import {
+  controlViewItem,
+  firstSidebarConfig,
+  isSidebarEnabled,
+  sectionConfig,
+} from './controlSchemaLayout'
+import {
+  normalizeControls,
+} from './controlSchemaNormalize'
+import {
+  humanize,
+  orderedUnique,
+} from './controlSchemaUtils'
+import type {
+  ControlFormSchema,
+  ControlSchema,
+  ControlSchemaOptions,
+} from './useControlSchema'
+
+/** 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,
+        access: config.access,
+        visibleFor: config.visibleFor,
+        requiresAdmin: config.requiresAdmin,
+        permissions: config.permissions,
+        anyPermissions: config.anyPermissions,
+      }
+    }),
+  }
+}
+
+/** 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 AppTopBar pillNav-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 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
+}

package/src/composables/controlSchemaFormFields.ts

@@ -0,0 +1,61 @@
+import type {
+  FieldValidation,
+  FormFieldSchema,
+} from '../types/form-builder'
+import {
+  defaultValueForControl,
+  normalizeOption,
+  type NormalizedControl,
+} from './controlSchemaNormalize'
+import {
+  humanize,
+  numericValue,
+} from './controlSchemaUtils'
+import type {
+  ControlDefinition,
+} from './useControlSchema'
+
+export 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,
+    access: definition.access,
+    visibleFor: definition.visibleFor,
+    requiresAdmin: definition.requiresAdmin,
+    permissions: definition.permissions,
+    anyPermissions: definition.anyPermissions,
+    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
+}

package/src/composables/controlSchemaLayout.ts

@@ -0,0 +1,59 @@
+import type {
+  PillNavItem,
+} from '../types'
+import type {
+  NormalizedControl,
+} from './controlSchemaNormalize'
+import {
+  humanize,
+} from './controlSchemaUtils'
+import type {
+  ControlDefinition,
+  ControlSchemaOptions,
+  ControlSectionConfig,
+  ControlSidebarConfig,
+} from './useControlSchema'
+
+export 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,
+  }
+}
+
+export 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
+}
+
+export function isSidebarEnabled(sidebar: ControlDefinition['sidebar']): boolean {
+  if (sidebar === false) return false
+  if (sidebar && typeof sidebar === 'object') return sidebar.enabled !== false
+  return true
+}
+
+export 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 } : {}),
+    ...(config?.children !== undefined ? { children: config.children } : {}),
+  }
+}

package/src/composables/controlSchemaNormalize.ts

@@ -0,0 +1,101 @@
+import type {
+  SelectOption,
+} from '../types'
+import type {
+  FormFieldType,
+} from '../types/form-builder'
+import {
+  getTypeDefault,
+} from './formBuilderRegistry'
+import {
+  humanize,
+} from './controlSchemaUtils'
+import type {
+  ControlDefinition,
+  ControlInput,
+  ControlOption,
+  ControlOptionValue,
+  ControlSchema,
+  ControlSchemaOptions,
+} from './useControlSchema'
+
+export interface NormalizedControl {
+  name: string
+  definition: ControlDefinition
+  type: FormFieldType
+  sectionId: string
+  viewId: string
+  order: number
+}
+
+export 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)
+}
+
+export 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
+}
+
+export function defaultValueForControl(definition: ControlDefinition, type: FormFieldType): unknown {
+  if (definition.default !== undefined) return definition.default
+  if (definition.defaultValue !== undefined) return definition.defaultValue
+  return getTypeDefault(type)
+}
+
+export 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 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 optionValue(option: ControlOption): ControlOptionValue | unknown {
+  if (typeof option === 'object' && option !== null && 'value' in option) {
+    return option.value
+  }
+  return option
+}

package/src/composables/controlSchemaUtils.ts

@@ -0,0 +1,36 @@
+export function recordValue(value: unknown): Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : {}
+}
+
+export function numericValue(value: number | { value: number; message: string }): number {
+  return typeof value === 'number' ? value : value.value
+}
+
+export function orderedUnique(values: string[]): string[] {
+  return [...new Set(values)]
+}
+
+export function replaceRecord(target: Record<string, unknown>, values: Record<string, unknown>) {
+  for (const key of Object.keys(target)) {
+    delete target[key]
+  }
+  Object.assign(target, values)
+}
+
+export 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
+}
+
+export 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))
+}

package/src/composables/controlWorkspaceOptions.ts

@@ -0,0 +1,21 @@
+import type {
+  ControlWorkspaceOptions,
+} from './useControlSchema'
+
+export function mergeControlWorkspaceOptions(
+  base?: ControlWorkspaceOptions,
+  override?: ControlWorkspaceOptions,
+): ControlWorkspaceOptions {
+  return {
+    ...(base ?? {}),
+    ...(override ?? {}),
+    initialValues: {
+      ...(base?.initialValues ?? {}),
+      ...(override?.initialValues ?? {}),
+    },
+    topBarSettings: {
+      ...(base?.topBarSettings ?? {}),
+      ...(override?.topBarSettings ?? {}),
+    },
+  }
+}