@morscherlab/mint-sdk 1.2.0-beta.2 → 1.2.0-beta.20

package/src/__tests__/docs/frontendDocsCatalog.test.ts

@@ -22,7 +22,7 @@ interface FrontendManifest {
     }>
     composables: Array<{
       name: string
-      members?: Array<{ name: string }>
+      members?: Array<{ name: string; type?: string }>
       examples?: Array<{ title: string; language: string; code: string }>
     }>
     templateExports: Array<{ name: string }>
@@ -271,11 +271,14 @@ describe('frontend docs catalog coverage', () => {
     })
   })
 
-  it('documents only the source-driven JobsStatusTray props', () => {
+  it('documents the source and MINT 1.1 JobsStatusTray props', () => {
     const manifest = extractFrontendManifest()
     const jobsStatusTray = manifest.categories.components.find(item => item.name === 'JobsStatusTray')
 
     expect(jobsStatusTray?.props?.map(prop => prop.name).sort()).toEqual([
+      'adapter',
+      'eventStream',
+      'jobs',
       'loadOnMount',
       'source',
       'teleportTo',
@@ -319,6 +322,18 @@ describe('frontend docs catalog coverage', () => {
       'AppPillNav',
       'usePluginApi',
       'UsePluginApiOptions',
+    ]
+
+    for (const name of retiredNames) {
+      expect(rootIndex).not.toMatch(new RegExp(`\\b${name}\\b`))
+      expect(componentsIndex).not.toMatch(new RegExp(`\\b${name}\\b`))
+      expect(composableExports).not.toMatch(new RegExp(`\\b${name}\\b`))
+    }
+  })
+
+  it('keeps the MINT 1.1 composable compatibility exports', () => {
+    const composablesIndex = readFileSync(join(SDK_ROOT, 'src', 'composables', 'index.ts'), 'utf8')
+    const expected = [
       'useJobsStatusTray',
       'UseJobsStatusTrayOptions',
       'UseJobsStatusTrayReturn',
@@ -329,11 +344,7 @@ describe('frontend docs catalog coverage', () => {
       'usePluginClient',
     ]
 
-    for (const name of retiredNames) {
-      expect(rootIndex).not.toMatch(new RegExp(`\\b${name}\\b`))
-      expect(componentsIndex).not.toMatch(new RegExp(`\\b${name}\\b`))
-      expect(composableExports).not.toMatch(new RegExp(`\\b${name}\\b`))
-    }
+    expect(expected.filter(name => !new RegExp(`\\b${name}\\b`).test(composablesIndex))).toEqual([])
   })
 
   it('documents every public composable/helper export used by docs and doctor', () => {
@@ -422,4 +433,25 @@ describe('frontend docs catalog coverage', () => {
 
     expect(useFormBuilder?.members?.map(member => member.name)).toContain('updateSchema')
   })
+
+  it('extracts inherited return interface members', () => {
+    const manifest = extractFrontendManifest()
+    const workspace = manifest.categories.composables.find(item => item.name === 'useBioTemplateWorkspace')
+
+    expect(workspace?.members?.map(member => member.name)).toContain('componentUsage')
+  })
+
+  it('ignores generic constraints when extracting inherited return members', () => {
+    const manifest = extractFrontendManifest()
+    const history = manifest.categories.composables.find(item => item.name === 'useCommandHistory')
+
+    expect(history?.members?.map(member => member.name)).not.toContain('description')
+  })
+
+  it('extracts exact array return member types while resolving inheritance', () => {
+    const manifest = extractFrontendManifest()
+    const bindings = manifest.categories.composables.find(item => item.name === 'controlValuesToComponentBindings')
+
+    expect(bindings?.members?.find(member => member.name === 'props')?.type).toBe('Record<string, unknown>')
+  })
 })

package/src/__tests__/stores/settings.test.ts

@@ -1,6 +1,12 @@
 import { beforeEach, describe, expect, it, vi } from 'vitest'
 import { createPinia, setActivePinia } from 'pinia'
-import { useSettingsStore } from '../../stores/settings'
+import { nextTick } from 'vue'
+import {
+  paletteCssVariables,
+  tableDensityToSize,
+  tryUseSettingsStore,
+  useSettingsStore,
+} from '../../stores/settings'
 
 function mockMatchMedia(matches = false) {
   Object.defineProperty(window, 'matchMedia', {
@@ -46,6 +52,8 @@ describe('useSettingsStore', () => {
     setActivePinia(createPinia())
     installLocalStorage()
     document.documentElement.classList.remove('dark')
+    document.documentElement.removeAttribute('style')
+    delete document.documentElement.dataset.density
     mockMatchMedia(false)
   })
 
@@ -75,4 +83,66 @@ describe('useSettingsStore', () => {
       tableDensity: 'compact',
     }))
   })
+
+  describe('palette and density DOM sync', () => {
+    it('writes no palette overrides for the default palette', () => {
+      const settings = useSettingsStore()
+      settings.initialize()
+
+      expect(paletteCssVariables('default')).toEqual({})
+      expect(document.documentElement.style.getPropertyValue('--color-primary')).toBe('')
+    })
+
+    it('applies the stored palette hues to html on initialize', () => {
+      localStorage.setItem('mint-settings', JSON.stringify({ colorPalette: 'viridis' }))
+
+      const settings = useSettingsStore()
+      settings.initialize()
+
+      const style = document.documentElement.style
+      expect(style.getPropertyValue('--color-primary')).toBe('hsl(280 84% 67%)')
+      expect(style.getPropertyValue('--color-primary-hover')).toBe('hsl(280 75% 59%)')
+      expect(style.getPropertyValue('--color-cta')).toBe('hsl(80 95% 53%)')
+    })
+
+    it('re-applies the overrides when the palette changes and clears them on default', async () => {
+      const settings = useSettingsStore()
+      settings.initialize()
+
+      settings.colorPalette = 'pastel'
+      await nextTick()
+      expect(document.documentElement.style.getPropertyValue('--color-primary')).toBe('hsl(200 84% 67%)')
+
+      settings.colorPalette = 'default'
+      await nextTick()
+      expect(document.documentElement.style.getPropertyValue('--color-primary')).toBe('')
+      expect(document.documentElement.style.getPropertyValue('--color-primary-soft')).toBe('')
+    })
+
+    it('mirrors the table density onto html[data-density]', async () => {
+      const settings = useSettingsStore()
+      settings.initialize()
+      expect(document.documentElement.dataset.density).toBe('normal')
+
+      settings.tableDensity = 'compact'
+      await nextTick()
+      expect(document.documentElement.dataset.density).toBe('compact')
+    })
+
+    it('maps each density onto a table size', () => {
+      const settings = useSettingsStore()
+      settings.initialize()
+
+      expect(tableDensityToSize('compact')).toBe('sm')
+      expect(tableDensityToSize('normal')).toBe('md')
+      expect(tableDensityToSize('comfortable')).toBe('lg')
+
+      settings.tableDensity = 'comfortable'
+      expect(settings.getTableSize()).toBe('lg')
+    })
+  })
+
+  it('exposes the store through tryUseSettingsStore when Pinia is active', () => {
+    expect(tryUseSettingsStore()).not.toBeNull()
+  })
 })

package/src/__tests__/styles/cssTokens.test.ts

@@ -0,0 +1,131 @@
+import { readdirSync, readFileSync, statSync } from 'node:fs'
+import { dirname, join, relative, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { describe, expect, it } from 'vitest'
+
+const here = dirname(fileURLToPath(import.meta.url))
+const srcRoot = resolve(here, '../..')
+const stylesDir = join(srcRoot, 'styles')
+const variablesCss = readFileSync(join(stylesDir, 'variables.css'), 'utf-8')
+
+/**
+ * Custom properties that are legitimately *not* declared in variables.css:
+ * they are set at runtime (inline `:style` bindings, JS-built names) or are
+ * component-local knobs declared in the same stylesheet that consumes them.
+ * Anything else must be a canonical token from variables.css.
+ */
+const RUNTIME_PROPERTY_ALLOWLIST = new Set<string>([
+  // Names assembled in JS (`--grp-${i}`) — the literal prefix is what the
+  // scanner sees in a template string.
+  '--grp-',
+])
+
+const SOURCE_EXTENSIONS = ['.vue', '.css', '.ts']
+const IGNORED_DIRS = new Set(['__tests__', 'generated-ui', 'node_modules'])
+
+function walk(dir: string, out: string[] = []): string[] {
+  for (const entry of readdirSync(dir)) {
+    const full = join(dir, entry)
+    if (statSync(full).isDirectory()) {
+      if (!IGNORED_DIRS.has(entry)) walk(full, out)
+    } else if (SOURCE_EXTENSIONS.some((ext) => entry.endsWith(ext))) {
+      out.push(full)
+    }
+  }
+  return out
+}
+
+const sourceFiles = walk(srcRoot)
+
+function declaredIn(text: string): Set<string> {
+  const names = new Set<string>()
+  // `--foo: value` declarations, in CSS blocks and in JS style objects.
+  for (const m of text.matchAll(/(--[A-Za-z0-9_-]+)\s*:/g)) names.add(m[1])
+  // setProperty('--foo', …) / `'--foo'` keys in style bindings.
+  for (const m of text.matchAll(/['"`](--[A-Za-z0-9_-]+)['"`]/g)) names.add(m[1])
+  return names
+}
+
+const canonicalTokens = declaredIn(variablesCss)
+
+// Component-local custom properties: declared in a stylesheet or set from an
+// inline `:style` binding in the SFC that owns it. They are legitimate, they
+// just are not part of the global token set.
+const componentLocalProperties = new Set<string>()
+for (const file of sourceFiles) {
+  for (const name of declaredIn(readFileSync(file, 'utf-8'))) {
+    componentLocalProperties.add(name)
+  }
+}
+
+interface Usage {
+  file: string
+  token: string
+}
+
+const usages: Usage[] = []
+for (const file of sourceFiles) {
+  const text = readFileSync(file, 'utf-8')
+  for (const m of text.matchAll(/var\(\s*(--[A-Za-z0-9_-]+)/g)) {
+    usages.push({ file, token: m[1] })
+  }
+}
+
+describe('CSS custom properties', () => {
+  it('scans a meaningful number of var() references', () => {
+    expect(usages.length).toBeGreaterThan(500)
+    expect(canonicalTokens.size).toBeGreaterThan(70)
+  })
+
+  it('only references custom properties that are actually defined', () => {
+    const undefinedUsages = usages.filter(({ token }) => {
+      if (canonicalTokens.has(token)) return false
+      if (RUNTIME_PROPERTY_ALLOWLIST.has(token)) return false
+      return !componentLocalProperties.has(token)
+    })
+
+    const report = [
+      ...new Set(
+        undefinedUsages.map(
+          ({ file, token }) => `${token} (${relative(srcRoot, file)})`,
+        ),
+      ),
+    ].sort()
+
+    expect(report).toEqual([])
+  })
+
+  it('does not use the platform-only --color-bg-*/--color-text-*/--color-border aliases', () => {
+    const platformOnly = /^--color-(bg|text)-|^--color-border$/
+    const offenders = [
+      ...new Set(
+        usages
+          .filter(({ token }) => platformOnly.test(token))
+          .map(({ file, token }) => `${token} (${relative(srcRoot, file)})`),
+      ),
+    ].sort()
+
+    expect(offenders).toEqual([])
+  })
+
+  it('aggregates every component stylesheet in styles/index.css', () => {
+    const index = readFileSync(join(stylesDir, 'index.css'), 'utf-8')
+    const imported = new Set(
+      [...index.matchAll(/@import\s+'\.\/components\/([^']+)'/g)].map((m) => m[1]),
+    )
+    const onDisk = readdirSync(join(stylesDir, 'components')).filter((f) =>
+      f.endsWith('.css'),
+    )
+    expect([...onDisk].filter((f) => !imported.has(f)).sort()).toEqual([])
+  })
+
+  it('does not re-import aggregated stylesheets from SFC <style> blocks', () => {
+    const offenders = sourceFiles
+      .filter((f) => f.endsWith('.vue'))
+      .filter((f) => /@import\s+['"][^'"]*styles\/components\//.test(readFileSync(f, 'utf-8')))
+      .map((f) => relative(srcRoot, f))
+      .sort()
+
+    expect(offenders).toEqual([])
+  })
+})

package/src/__tests__/utils/permissions.test.ts

@@ -7,6 +7,7 @@ import {
   hasAllPermissions,
   hasAnyPermission,
   isAdminUser,
+  normalizeAccessPolicy,
 } from '../../permissions'
 
 describe('permission helpers', () => {
@@ -60,3 +61,70 @@ describe('permission helpers', () => {
     expect(canAccessByPolicy(member, { plugin: 'reports' })).toBe(false)
   })
 })
+
+describe('normalizeAccessPolicy precedence', () => {
+  it('returns an empty policy for an absent rule', () => {
+    expect(normalizeAccessPolicy(undefined)).toEqual({})
+  })
+
+  it('reads a flat-only rule as-is', () => {
+    expect(normalizeAccessPolicy({
+      visibleFor: 'admin',
+      requiresAdmin: true,
+      permissions: ['users.manage'],
+      anyPermissions: ['plugins.install'],
+    })).toEqual({
+      visibleFor: 'admin',
+      requiresAdmin: true,
+      permissions: ['users.manage'],
+      anyPermissions: ['plugins.install'],
+    })
+  })
+
+  it('lifts a nested-only policy to the top level', () => {
+    expect(normalizeAccessPolicy({
+      access: { requiresAuth: true, plugin: 'reports', visibleFor: 'admin' },
+    })).toEqual({
+      requiresAuth: true,
+      plugin: 'reports',
+      visibleFor: 'admin',
+    })
+  })
+
+  it('lets the nested policy win over the deprecated flat duplicates', () => {
+    expect(normalizeAccessPolicy({
+      access: {
+        visibleFor: 'admin',
+        requiresAdmin: true,
+        permissions: ['users.manage'],
+        anyPermissions: ['plugins.install'],
+      },
+      visibleFor: 'user',
+      requiresAdmin: false,
+      permissions: ['experiments.view'],
+      anyPermissions: ['experiments.edit'],
+    })).toEqual({
+      visibleFor: 'admin',
+      requiresAdmin: true,
+      permissions: ['users.manage'],
+      anyPermissions: ['plugins.install'],
+    })
+  })
+
+  it('treats an undefined nested field as unset instead of masking the flat one', () => {
+    expect(normalizeAccessPolicy({
+      access: { visibleFor: undefined, requiresAdmin: true },
+      visibleFor: 'user',
+    })).toEqual({
+      visibleFor: 'user',
+      requiresAdmin: true,
+    })
+  })
+
+  it('feeds canAccessByPolicy from the nested policy', () => {
+    const member = { role: 'member', permissions: ['experiments.view'] }
+
+    expect(canAccessByPolicy(member, { access: { requiresAdmin: true }, requiresAdmin: false })).toBe(false)
+    expect(canAccessByPolicy(member, { access: { visibleFor: 'user' }, visibleFor: 'admin' })).toBe(true)
+  })
+})

package/src/apiErrors.ts

@@ -0,0 +1,85 @@
+export interface MintApiErrorEnvelope {
+  code: string
+  message: string
+  status: number
+  request_id: string | null
+  details: unknown
+  detail?: unknown
+}
+
+const STATUS_MESSAGES: Readonly<Record<number, string>> = {
+  400: 'Bad request',
+  401: 'Authentication required',
+  403: 'Permission denied',
+  404: 'Resource not found',
+  405: 'Method not allowed',
+  409: 'Conflict',
+  413: 'Payload too large',
+  415: 'Unsupported media type',
+  422: 'Validation error',
+  429: 'Rate limit exceeded',
+  500: 'Internal server error',
+  502: 'Bad gateway',
+  503: 'Service unavailable',
+}
+
+function asRecord(value: unknown): Record<string, unknown> | null {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null
+  return value as Record<string, unknown>
+}
+
+/** Public error thrown by typed MINT SDK requests. */
+export class MintApiError extends Error {
+  override readonly name: string = 'MintApiError'
+
+  constructor(
+    message: string,
+    readonly code: string,
+    readonly status: number,
+    readonly requestId: string | null,
+    readonly details: unknown,
+    readonly detail: unknown,
+    readonly body: unknown,
+    readonly cause?: unknown,
+  ) {
+    super(message)
+  }
+}
+
+export interface MintApiErrorOptions {
+  requestId?: string | null
+  cause?: unknown
+}
+
+/** Normalize current typed envelopes and the previous FastAPI detail shape. */
+export function mintApiErrorFromResponse(
+  status: number,
+  payload: unknown,
+  options: MintApiErrorOptions = {},
+): MintApiError {
+  const body = asRecord(payload)
+  const legacyDetail = body?.detail
+  const inner = asRecord(legacyDetail) ?? body
+  const text = (value: unknown): string | undefined =>
+    typeof value === 'string' && value ? value : undefined
+  // Complete envelopes own the public code; older wrappers defer to the plugin payload.
+  const canonical = typeof body?.status === 'number' && text(body.code) && text(body.message)
+  const code = (canonical ? text(body.code) : text(inner?.error) ?? text(inner?.code))
+    ?? text(body?.code) ?? 'unknown'
+  const message = (canonical ? text(body.message) : text(inner?.message))
+    ?? text(body?.message) ?? text(legacyDetail)
+    ?? STATUS_MESSAGES[status] ?? `HTTP ${status}`
+  const details = body?.details ?? inner?.details ?? null
+  const requestId = text(body?.request_id) ?? text(inner?.request_id) ?? options.requestId ?? null
+
+  return new MintApiError(
+    message,
+    code,
+    status,
+    requestId,
+    details,
+    legacyDetail,
+    payload,
+    options.cause,
+  )
+}

package/src/components/ActionMenu.vue

@@ -2,7 +2,9 @@
 /** Compact overflow actions with an IconButton trigger and a viewport-safe teleported menu. */
 import { computePosition, flip, offset, shift } from '@floating-ui/dom'
 import { Ellipsis } from 'lucide-vue-next'
-import { nextTick, onBeforeUnmount, ref } from 'vue'
+import { nextTick, onMounted, ref, watch } from 'vue'
+import { useDropdownState } from '../composables/useDropdownState'
+import { useMenuKeyboard } from '../composables/useMenuKeyboard'
 import type { ActionMenuItem } from '../types/components'
 import IconButton from './IconButton.vue'
 
@@ -22,14 +24,26 @@ const emit = defineEmits<{
   close: []
 }>()
 
-const isOpen = ref(false)
-const triggerRootRef = ref<HTMLElement | null>(null)
 const panelRef = ref<HTMLElement | null>(null)
 const panelStyle = ref<Record<string, string>>({ visibility: 'hidden' })
 
-function triggerElement(): HTMLButtonElement | null {
-  return triggerRootRef.value?.querySelector('button') ?? null
-}
+// Disclosure state (outside-click, Escape, scroll/resize closing, focus return)
+// comes from the shared composable; only floating-ui placement stays local.
+const { isOpen, rootRef, triggerRef, open, close } = useDropdownState({
+  closeOnScroll: true,
+  insideRefs: [panelRef],
+  onOpen: () => {
+    panelStyle.value = { visibility: 'hidden' }
+    emit('open')
+  },
+  onClose: () => emit('close'),
+})
+
+// IconButton owns the actual <button>, so the trigger element is resolved from
+// the wrapper once mounted rather than bound with a template ref.
+onMounted(() => {
+  triggerRef.value = rootRef.value?.querySelector('button') ?? null
+})
 
 function menuItems(): HTMLElement[] {
   if (!panelRef.value) return []
@@ -39,7 +53,7 @@ function menuItems(): HTMLElement[] {
 }
 
 async function positionPanel() {
-  const trigger = triggerElement()
+  const trigger = triggerRef.value
   const panel = panelRef.value
   if (!trigger || !panel) return
 
@@ -59,97 +73,43 @@ async function positionPanel() {
   }
 }
 
-function addGlobalListeners() {
-  document.addEventListener('pointerdown', handleDocumentPointerDown, true)
-  window.addEventListener('resize', handleViewportChange)
-  window.addEventListener('scroll', handleViewportChange, true)
-}
-
-function removeGlobalListeners() {
-  document.removeEventListener('pointerdown', handleDocumentPointerDown, true)
-  window.removeEventListener('resize', handleViewportChange)
-  window.removeEventListener('scroll', handleViewportChange, true)
-}
-
-async function openMenu() {
+/** `focusFirst` is false when the keyboard composable owns the initial focus. */
+function openMenu(focusFirst = true) {
   if (props.disabled || isOpen.value) return
-  panelStyle.value = { visibility: 'hidden' }
-  isOpen.value = true
-  emit('open')
-  addGlobalListeners()
-  await nextTick()
-  await positionPanel()
-  menuItems()[0]?.focus()
-}
-
-function closeMenu(returnFocus = false) {
-  if (!isOpen.value) return
-  isOpen.value = false
-  removeGlobalListeners()
-  emit('close')
-  if (returnFocus) {
-    nextTick(() => triggerElement()?.focus())
+  open()
+  if (focusFirst) {
+    void nextTick(() => menuItems()[0]?.focus())
   }
 }
 
 function toggleMenu() {
-  if (isOpen.value) closeMenu()
-  else void openMenu()
+  if (props.disabled) return
+  if (isOpen.value) close()
+  else openMenu()
 }
 
+const { handleTriggerKeydown, handlePanelKeydown } = useMenuKeyboard({
+  items: menuItems,
+  isOpen: () => isOpen.value,
+  open: () => openMenu(false),
+  close,
+})
+
 function handleSelect(item: ActionMenuItem) {
   if (item.disabled) return
   emit('select', item)
-  closeMenu()
-}
-
-function handleDocumentPointerDown(event: PointerEvent) {
-  const target = event.target
-  if (!(target instanceof Node)) return
-  if (triggerRootRef.value?.contains(target) || panelRef.value?.contains(target)) return
-  closeMenu()
-}
-
-function handleViewportChange() {
-  closeMenu()
+  close()
 }
 
-function handleMenuKeydown(event: KeyboardEvent) {
-  const items = menuItems()
-  const currentIndex = items.indexOf(document.activeElement as HTMLElement)
-
-  if (event.key === 'Escape') {
-    event.preventDefault()
-    closeMenu(true)
-    return
-  }
-  if (event.key === 'Tab') {
-    closeMenu()
-    return
-  }
-  if (event.key === 'Home') {
-    event.preventDefault()
-    items[0]?.focus()
-    return
-  }
-  if (event.key === 'End') {
-    event.preventDefault()
-    items[items.length - 1]?.focus()
-    return
-  }
-  if (event.key !== 'ArrowDown' && event.key !== 'ArrowUp') return
-
-  event.preventDefault()
-  const direction = event.key === 'ArrowDown' ? 1 : -1
-  const nextIndex = (Math.max(currentIndex, 0) + direction + items.length) % items.length
-  items[nextIndex]?.focus()
-}
-
-onBeforeUnmount(removeGlobalListeners)
+watch(isOpen, async (opened) => {
+  if (!opened) return
+  await nextTick()
+  await positionPanel()
+})
 </script>
 
 <template>
-  <span ref="triggerRootRef" class="mint-action-menu">
+  <span ref="rootRef" class="mint-action-menu">
     <IconButton
       variant="secondary"
       size="sm"
@@ -158,6 +118,7 @@ onBeforeUnmount(removeGlobalListeners)
       aria-haspopup="menu"
       :aria-expanded="isOpen"
       @click="toggleMenu"
+      @keydown="handleTriggerKeydown"
     >
       <Ellipsis
         class="mint-action-menu__trigger-icon"
@@ -175,7 +136,7 @@ onBeforeUnmount(removeGlobalListeners)
       class="mint-action-menu__panel"
       :style="panelStyle"
       role="menu"
-      @keydown="handleMenuKeydown"
+      @keydown="handlePanelKeydown"
     >
       <template v-for="item in items" :key="item.id">
         <a
@@ -203,7 +164,3 @@ onBeforeUnmount(removeGlobalListeners)
     </div>
   </Teleport>
 </template>
-
-<style>
-@import '../styles/components/action-menu.css';
-</style>

package/src/components/AlertBox.vue

@@ -82,7 +82,3 @@ const hasActions = () => !!props.actionLabel || !!slots.actions
     </button>
   </div>
 </template>
-
-<style>
-@import '../styles/components/alert-box.css';
-</style>