@morscherlab/mint-sdk 1.2.0-beta.3 → 1.2.0-beta.5

package/src/components/PluginWorkspaceView.controls.ts

@@ -0,0 +1,182 @@
+import { computed, reactive, watch } from 'vue'
+import type { ComputedRef } from 'vue'
+import type { PillNavItem } from '../types'
+import type {
+  ControlComponentBinding,
+  ControlComponentBindingsById,
+  ControlComponentBindingsConfig,
+  ControlComponentPropsByIdMap,
+  ControlComponentPropsMap,
+  ControlModel,
+  ControlModelBinding,
+  ControlSchema,
+  ControlWorkspaceOptions,
+} from '../composables/useControlSchema'
+import {
+  controlValuesToComponentBindings,
+  controlValuesToComponentBindingsById,
+  controlValuesToComponentProps,
+  controlsToViewItems,
+  getControlDefaults,
+  getDefaultControlView,
+  mergeControlWorkspaceOptions,
+  resolveControlModel,
+} from '../composables/useControlSchema'
+
+export interface PluginWorkspaceControlsOptions {
+  model: () => ControlModel | ControlModelBinding | undefined
+  controls: () => ControlSchema | undefined
+  controlOptions: () => ControlWorkspaceOptions
+  modelValue: () => Record<string, unknown> | undefined
+  values: () => Record<string, unknown> | undefined
+  componentBindings: () => ControlComponentBindingsConfig | undefined
+  componentProps: () => ControlComponentPropsMap | undefined
+  componentPropsById: () => ControlComponentPropsByIdMap | undefined
+  emitValues: (values: Record<string, unknown>) => void
+}
+
+export interface PluginWorkspaceControls {
+  resolvedModel: ComputedRef<ControlModelBinding | undefined>
+  resolvedControls: ComputedRef<ControlSchema | undefined>
+  resolvedControlOptions: ComputedRef<ControlWorkspaceOptions>
+  generatedPillNav: ComputedRef<PillNavItem[]>
+  generatedDefaultView: ComputedRef<string>
+  internalControlValues: Record<string, unknown>
+  resolvedComponentBindings: ComputedRef<ControlComponentBinding[]>
+  resolvedComponentBindingsById: ComputedRef<ControlComponentBindingsById>
+  resolvedComponentProps: ComputedRef<Record<string, unknown>>
+  resolvedComponentPropsById: ComputedRef<Record<string, Record<string, unknown>>>
+  handleControlValuesUpdate: (values: Record<string, unknown>) => void
+}
+
+export function usePluginWorkspaceControls(
+  options: PluginWorkspaceControlsOptions,
+): PluginWorkspaceControls {
+  const resolvedModel = computed<ControlModelBinding | undefined>(() =>
+    resolveControlModel(options.model()),
+  )
+
+  const resolvedControls = computed<ControlSchema | undefined>(() =>
+    options.controls() ?? resolvedModel.value?.controls,
+  )
+
+  const resolvedControlOptions = computed<ControlWorkspaceOptions>(() =>
+    mergeControlWorkspaceOptions(resolvedModel.value?.controlOptions ?? {}, options.controlOptions()),
+  )
+
+  const externalControlValues = computed(() => options.modelValue() ?? options.values())
+  const internalControlValues = reactive<Record<string, unknown>>({})
+  let syncingControlValues = false
+
+  const generatedControlDefaults = computed<Record<string, unknown>>(() => {
+    if (!resolvedControls.value) return {}
+    return {
+      ...getControlDefaults(resolvedControls.value),
+      ...(resolvedControlOptions.value.initialValues ?? {}),
+    }
+  })
+
+  function replaceControlValues(values: Record<string, unknown>) {
+    for (const key of Object.keys(internalControlValues)) {
+      if (!(key in values)) {
+        delete internalControlValues[key]
+      }
+    }
+    Object.assign(internalControlValues, values)
+  }
+
+  function emitControlValues() {
+    options.emitValues({ ...internalControlValues })
+  }
+
+  function syncResolvedControlValues() {
+    syncingControlValues = true
+    replaceControlValues({
+      ...generatedControlDefaults.value,
+      ...(externalControlValues.value === undefined ? internalControlValues : externalControlValues.value),
+    })
+    syncingControlValues = false
+  }
+
+  function handleControlValuesUpdate(values: Record<string, unknown>) {
+    syncingControlValues = true
+    replaceControlValues({
+      ...generatedControlDefaults.value,
+      ...values,
+    })
+    syncingControlValues = false
+    emitControlValues()
+  }
+
+  const resolvedComponentBindings = computed(() =>
+    controlValuesToComponentBindings(
+      internalControlValues,
+      options.componentBindings() ?? resolvedModel.value?.componentBindings,
+    ),
+  )
+
+  const resolvedComponentBindingsById = computed(() =>
+    controlValuesToComponentBindingsById(
+      internalControlValues,
+      options.componentBindings() ?? resolvedModel.value?.componentBindings,
+    ),
+  )
+
+  const resolvedComponentProps = computed(() => {
+    const mapping = options.componentProps() ?? resolvedModel.value?.componentProps
+    return mapping === undefined ? {} : controlValuesToComponentProps(internalControlValues, mapping)
+  })
+
+  const resolvedComponentPropsById = computed(() => {
+    const mappings = options.componentPropsById() ?? resolvedModel.value?.componentPropsById
+    if (mappings === undefined) return {}
+
+    return Object.fromEntries(
+      Object.entries(mappings).map(([id, mapping]) => [
+        id,
+        controlValuesToComponentProps(internalControlValues, mapping),
+      ]),
+    )
+  })
+
+  const generatedPillNav = computed<PillNavItem[]>(() => {
+    if (!resolvedControls.value) return []
+    return controlsToViewItems(resolvedControls.value, resolvedControlOptions.value)
+  })
+
+  const generatedDefaultView = computed(() => {
+    if (!resolvedControls.value) return ''
+    return getDefaultControlView(resolvedControls.value, resolvedControlOptions.value)
+  })
+
+  syncResolvedControlValues()
+
+  watch(
+    [generatedControlDefaults, externalControlValues],
+    syncResolvedControlValues,
+    { deep: true },
+  )
+
+  watch(
+    internalControlValues,
+    () => {
+      if (syncingControlValues) return
+      emitControlValues()
+    },
+    { deep: true, flush: 'sync' },
+  )
+
+  return {
+    resolvedModel,
+    resolvedControls,
+    resolvedControlOptions,
+    generatedPillNav,
+    generatedDefaultView,
+    internalControlValues,
+    resolvedComponentBindings,
+    resolvedComponentBindingsById,
+    resolvedComponentProps,
+    resolvedComponentPropsById,
+    handleControlValuesUpdate,
+  }
+}

package/src/components/PluginWorkspaceView.navigation.ts

@@ -0,0 +1,106 @@
+import { computed, ref, type ComputedRef, type Ref, type WritableComputedRef } from 'vue'
+import type {
+  PageSelectorItem,
+  PageSelectorItemInput,
+  PillNavItem,
+  PillNavItemInput,
+} from '../types'
+
+type ReadableRef<T> = Readonly<Ref<T>>
+
+export interface PluginWorkspaceNavigationOptions {
+  activeView: () => string | undefined
+  defaultActiveView: () => string | undefined
+  currentPillId: () => string | undefined
+  currentPageSelectorId: () => string | undefined
+  pillNav: () => PillNavItemInput[] | undefined
+  pageSelector: () => PageSelectorItemInput[] | undefined
+  panelIds: () => string[]
+  generatedPillNav: ReadableRef<readonly PillNavItem[]>
+  generatedDefaultView: ReadableRef<string>
+  emitActiveView: (viewId: string) => void
+  emitPageSelectorSelect: (page: PageSelectorItem) => void
+  emitPillSelect: (item: PillNavItem) => void
+}
+
+export interface PluginWorkspaceNavigation {
+  resolvedPillNav: ComputedRef<PillNavItemInput[] | undefined>
+  firstConfiguredViewId: ComputedRef<string>
+  resolvedActiveView: WritableComputedRef<string>
+  resolvedCurrentPillId: ComputedRef<string>
+  resolvedCurrentPageSelectorId: ComputedRef<string>
+  setActiveView: (viewId: string) => void
+  handlePageSelectorSelect: (page: PageSelectorItem) => void
+  handlePillSelect: (item: PillNavItem) => void
+}
+
+export function usePluginWorkspaceNavigation(
+  options: PluginWorkspaceNavigationOptions,
+): PluginWorkspaceNavigation {
+  const internalActiveView = ref(options.defaultActiveView())
+
+  const resolvedPillNav = computed<PillNavItemInput[] | undefined>(() => {
+    if (options.pillNav() !== undefined) return options.pillNav()
+    return options.generatedPillNav.value.length > 0
+      ? [...options.generatedPillNav.value]
+      : undefined
+  })
+
+  const firstConfiguredViewId = computed(() =>
+    options.defaultActiveView()
+      ?? firstItemId(options.pillNav())
+      ?? options.generatedDefaultView.value
+      ?? firstItemId(options.pageSelector())
+      ?? options.panelIds()[0]
+      ?? '',
+  )
+
+  const resolvedActiveView = computed({
+    get: () =>
+      options.activeView()
+        ?? options.currentPillId()
+        ?? options.currentPageSelectorId()
+        ?? internalActiveView.value
+        ?? firstConfiguredViewId.value,
+    set: (value: string) => {
+      internalActiveView.value = value
+      options.emitActiveView(value)
+    },
+  })
+
+  const resolvedCurrentPillId = computed(() => options.currentPillId() ?? resolvedActiveView.value)
+  const resolvedCurrentPageSelectorId = computed(() =>
+    options.currentPageSelectorId() ?? resolvedActiveView.value,
+  )
+
+  function setActiveView(viewId: string) {
+    resolvedActiveView.value = viewId
+  }
+
+  function handlePageSelectorSelect(page: PageSelectorItem) {
+    setActiveView(page.id)
+    options.emitPageSelectorSelect(page)
+  }
+
+  function handlePillSelect(item: PillNavItem) {
+    setActiveView(item.id)
+    options.emitPillSelect(item)
+  }
+
+  return {
+    resolvedPillNav,
+    firstConfiguredViewId,
+    resolvedActiveView,
+    resolvedCurrentPillId,
+    resolvedCurrentPageSelectorId,
+    setActiveView,
+    handlePageSelectorSelect,
+    handlePillSelect,
+  }
+}
+
+function firstItemId(items?: readonly (string | { id: string })[]): string | undefined {
+  const item = items?.[0]
+  if (item === undefined) return undefined
+  return typeof item === 'string' ? item : item.id
+}

package/src/components/PluginWorkspaceView.props.ts

@@ -0,0 +1,207 @@
+import type {
+  AccountMenuItem,
+  ExperimentSummary,
+  PageSelectorItem,
+  PageSelectorItemInput,
+  PillNavItem,
+  PillNavItemInput,
+  PillNavOption,
+  PluginSwitcherInfo,
+  PluginSwitcherPlugin,
+  SidebarToolSection,
+  TopBarSettingsConfig,
+  TopBarVariant,
+} from '../types'
+import type { FormEnhancements, FormSchema } from '../types/form-builder'
+import type {
+  ControlComponentBinding,
+  ControlComponentBindingsById,
+  ControlComponentBindingsConfig,
+  ControlComponentPropsByIdMap,
+  ControlComponentPropsMap,
+  ControlModel,
+  ControlModelBinding,
+  ControlSchema,
+  ControlWorkspaceOptions,
+} from '../composables/useControlSchema'
+
+export type PluginWorkspaceSidebarVariant = 'default' | 'analysis'
+
+export interface PluginWorkspaceViewProps {
+  /** App or plugin title shown in the top bar. */
+  title?: string
+  /** Secondary copy shown under the title. */
+  subtitle?: string
+  /** Top bar visual treatment. */
+  topBarVariant?: TopBarVariant
+  /** Home link used by the top bar brand icon. */
+  homePath?: string
+  /** Show the default MINT logo when no icon/logo slot is provided. */
+  showLogo?: boolean
+  /** Preferred route-level page selector entries. Pass [] to suppress integrated platform fallback. */
+  pageSelector?: PageSelectorItemInput[]
+  /** Active page selector id. Defaults to activeView. */
+  currentPageSelectorId?: string
+  /** Optional plugin switcher shown in the left navigation position. */
+  pluginSwitcher?: PluginSwitcherInfo
+  /** Preferred centered navigation for local modes inside the current route. */
+  pillNav?: PillNavItemInput[]
+  /** Active centered pill id. Defaults to activeView. */
+  currentPillId?: string
+  /** Show the theme toggle button. */
+  showThemeToggle?: boolean
+  /** Show the settings button and modal. */
+  showSettings?: boolean
+  /** Built-in settings modal configuration. */
+  settingsConfig?: TopBarSettingsConfig
+  /** Show the standalone badge when not integrated into the platform. */
+  showStandaloneLabel?: boolean
+  /** Custom standalone badge label. */
+  standaloneLabel?: string
+  /** Account dropdown entries. */
+  accountMenu?: AccountMenuItem[]
+  /** Show the notifications icon button. */
+  showNotifications?: boolean
+  /** Draw a notification dot on the notifications icon. */
+  hasNotificationDot?: boolean
+  /** Show the admin shortcut. */
+  showAdmin?: boolean
+  /** Route used by the admin shortcut. */
+  adminPath?: string
+  /** Account display name. */
+  userName?: string
+  /** Explicit account avatar initial. */
+  userInitial?: string
+  /** Account email shown in the avatar menu. */
+  userEmail?: string
+  /** Enable the built-in AppTopBar experiment popover and selector flow. The current experiment comes from the shared experiment store, not from a prop. Keep this comment on one line — the docs extractor drops multi-line JSDoc. */
+  experimentShell?: boolean
+  /** Save handler used by the AppTopBar experiment chip. Return a message to flash success. */
+  experimentSave?: () => string | null | Promise<string | null>
+  /** Disable the experiment save action. */
+  experimentSaveDisabled?: boolean
+  /** Tooltip shown when the experiment save action is disabled. */
+  experimentSaveDisabledMessage?: string
+
+  /** Active workspace view used by top bar navigation and sidebar panels. */
+  activeView?: string
+  /** Initial active view when activeView is uncontrolled. */
+  defaultActiveView?: string
+  /** Map of view IDs to sidebar tool sections. */
+  panels?: Record<string, SidebarToolSection[]>
+  /** Optional FormBuilder schemas keyed by section ID. */
+  forms?: Record<string, FormSchema>
+  /** Sidebar chrome title. */
+  sidebarTitle?: string
+  /** Sidebar chrome subtitle. */
+  sidebarSubtitle?: string
+  /** Optional compact badge/count rendered in the sidebar header. */
+  sidebarBadge?: string | number
+  /** AppSidebar visual preset. `analysis` matches the LEAF-style MINT analysis sidebar language. */
+  sidebarVariant?: PluginWorkspaceSidebarVariant
+  /** Sidebar CSS width. Defaults to AppSidebar's variant width. */
+  sidebarWidth?: string
+  /** Sidebar position in AppLayout. */
+  sidebarPosition?: 'left' | 'right'
+  /** Convert the sidebar into an SDK-owned mobile overlay below the AppLayout breakpoint. */
+  responsiveSidebar?: boolean
+  /** Render the sidebar shell even when no panel matches the active view. */
+  showSidebarWhenEmpty?: boolean
+  /** Disable the built-in sidebar surface entirely. */
+  showSidebar?: boolean
+  /** DOM id for the AppSidebar scrollable content area. Use with route/tab-owned Teleport sidebars. */
+  sidebarContentId?: string
+  /** Compact AppSidebar density. */
+  dense?: boolean
+  /** Show a built-in collapse/expand button in the sidebar chrome. Defaults to AppSidebar's variant behavior. */
+  sidebarCollapsible?: boolean
+  /** Sidebar width when collapsed. */
+  sidebarCollapsedWidth?: string
+  /** Accessible label for the sidebar collapse action. */
+  sidebarCollapseButtonLabel?: string
+  /** Accessible label for the sidebar expand action. */
+  sidebarExpandButtonLabel?: string
+  /** Floating AppLayout style. */
+  floating?: boolean
+  /** Optional compact control model for generated sidebar forms. */
+  model?: ControlModel | ControlModelBinding
+  /** Compact control schema for generated sidebar forms. */
+  controls?: ControlSchema
+  /** Options passed to compact control schema generation. */
+  controlOptions?: ControlWorkspaceOptions
+  /** Optional SDK component bindings exposed to the default slot with resolved props. */
+  componentBindings?: ControlComponentBindingsConfig
+  /** Optional mapping from workspace values to component props exposed to the default slot. */
+  componentProps?: ControlComponentPropsMap
+  /** Optional named mappings from workspace values to component props exposed to the default slot. */
+  componentPropsById?: ControlComponentPropsByIdMap
+  /** Shared values for auto-rendered sidebar forms. Supports default v-model. */
+  modelValue?: Record<string, unknown>
+  /** Shared values for auto-rendered sidebar forms. */
+  values?: Record<string, unknown>
+  /** Runtime FormBuilder enhancements for auto-rendered sidebar forms. */
+  formEnhancements?: FormEnhancements<Record<string, unknown>>
+  /** Show submit/cancel actions inside auto-rendered sidebar forms. */
+  showFormActions?: boolean
+  /** Loading/saving state for auto-rendered sidebar forms. */
+  formLoading?: boolean
+  /** Disabled state for auto-rendered sidebar forms. */
+  formDisabled?: boolean
+  /** Readonly state for auto-rendered sidebar forms. */
+  formReadonly?: boolean
+  /** Size passed to auto-rendered sidebar forms. */
+  formSize?: 'sm' | 'md' | 'lg'
+  /** Controlled sidebar collapsed state. */
+  sidebarCollapsed?: boolean
+  /** Initial sidebar collapsed state when uncontrolled. */
+  defaultSidebarCollapsed?: boolean
+  /** Accessible label for the mobile sidebar toggle. */
+  sidebarToggleLabel?: string
+  /** Accessible label used when the mobile sidebar is open. */
+  sidebarCloseLabel?: string
+}
+
+/**
+ * Event map for PluginWorkspaceView, shared with the {@link usePluginWorkspace} composable
+ * so its internal pieces can emit through the exact same typed contract as the public component.
+ */
+export interface PluginWorkspaceViewEmits {
+  'update:activeView': [value: string]
+  'page-selector-select': [page: PageSelectorItem]
+  'pill-select': [item: PillNavItem]
+  'pill-option-select': [option: PillNavOption, item: PillNavItem]
+  'plugin-switcher-select': [plugin: PluginSwitcherPlugin]
+  'plugin-switcher-install': []
+  'account-menu-select': [item: AccountMenuItem]
+  'sign-out': []
+  'notifications-click': []
+  'settings-values-change': [data: Record<string, unknown>]
+  'admin-click': []
+  'experiment-select': [experiment: ExperimentSummary]
+  'experiment-detach': []
+  'update:modelValue': [values: Record<string, unknown>]
+  'update:values': [values: Record<string, unknown>]
+  'update:sidebarCollapsed': [value: boolean]
+  'update:toggle': [sectionId: string, value: boolean]
+  'section-action': [sectionId: string, actionId: string]
+  'form-submit': [sectionId: string, values: Record<string, unknown>]
+  'form-cancel': [sectionId: string]
+}
+
+/** Typed `emit` function shape produced by `defineEmits<PluginWorkspaceViewEmits>()`. */
+export type PluginWorkspaceViewEmit = <K extends keyof PluginWorkspaceViewEmits>(
+  event: K,
+  ...args: PluginWorkspaceViewEmits[K]
+) => void
+
+export interface PluginWorkspaceSlotProps {
+  activeView: string
+  setActiveView: (viewId: string) => void
+  values: Record<string, unknown>
+  componentBindings: ControlComponentBinding[]
+  componentBindingsById: ControlComponentBindingsById
+  componentProps: Record<string, unknown>
+  componentPropsById: Record<string, Record<string, unknown>>
+}
+
+export type PluginWorkspaceForwardedSlotProps = Record<string, unknown>

package/src/components/PluginWorkspaceView.shell.ts

@@ -0,0 +1,67 @@
+const topBarForwardedSlots = new Set([
+  'icon',
+  'logo',
+  'page-selector-icon',
+  'page-selector-item-icon',
+  'nav',
+  'center',
+  'actions',
+  'account-menu-items',
+  'account-menu-item-icon',
+  'settings-appearance',
+])
+
+const sidebarForwardedSlots = new Set([
+  'header',
+  'collapsed',
+  'collapsed-footer',
+  'footer',
+])
+
+type SlotKeyMap = Readonly<Record<string, unknown>>
+
+export interface PluginWorkspaceSidebarSurfaceOptions {
+  showSidebar: boolean
+  panels: Record<string, unknown>
+  forms: Record<string, unknown>
+  model: unknown
+  controls: unknown
+  showSidebarWhenEmpty: boolean
+  sidebarContentId?: string
+  sidebarTitle?: string
+  sidebarSubtitle?: string
+  sidebarBadge?: string | number
+  hasSidebarSlot: boolean
+  sidebarSlotCount: number
+}
+
+export function getPluginWorkspaceTopBarSlotNames(slots: SlotKeyMap): string[] {
+  return Object.keys(slots).filter(name =>
+    topBarForwardedSlots.has(name) || name.startsWith('settings-tab-'),
+  )
+}
+
+export function getPluginWorkspaceSidebarSlotNames(slots: SlotKeyMap): string[] {
+  return Object.keys(slots).filter(name =>
+    sidebarForwardedSlots.has(name) || name.startsWith('section-'),
+  )
+}
+
+export function hasPluginWorkspaceSidebarSurface(
+  options: PluginWorkspaceSidebarSurfaceOptions,
+): boolean {
+  if (!options.showSidebar) return false
+  return (
+    Object.keys(options.panels).length > 0
+    || Object.keys(options.forms).length > 0
+    || options.model !== undefined
+    || options.controls !== undefined
+    || options.showSidebarWhenEmpty
+    || options.sidebarContentId !== undefined
+    || options.sidebarTitle !== undefined
+    || options.sidebarSubtitle !== undefined
+    || options.sidebarBadge !== undefined
+    || options.hasSidebarSlot
+    || options.sidebarSlotCount > 0
+  )
+}