@morscherlab/mint-sdk 1.0.0-alpha.9 → 1.0.0-beta.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@morscherlab/mint-sdk",
-  "version": "1.0.0-alpha.9",
+  "version": "1.0.0-beta.2",
   "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/__tests__/components/AppTopBar.test.ts

@@ -621,10 +621,10 @@ describe('AppTopBar', () => {
 
       expect(wrapper.find('.mint-topbar__logo-text').exists()).toBe(true)
       expect(wrapper.find('.mint-topbar__logo-text').text()).toBe('M')
-      expect(wrapper.find('.mint-topbar__logo-svg').exists()).toBe(false)
+      expect(wrapper.findComponent({ name: 'PluginIcon' }).exists()).toBe(false)
     })
 
-    it('should render plugin metadata icon SVG when plugin has icon', () => {
+    it('should render PluginIcon when plugin metadata has an icon', () => {
       const iconPath = 'M13 10V3L4 14h7v7l9-11h-7z'
       mockPlatformCtx({
         isIntegrated: true,
@@ -633,13 +633,31 @@ describe('AppTopBar', () => {
 
       const wrapper = createWrapper({ title: 'Test App' })
 
-      const svg = wrapper.find('.mint-topbar__logo-svg')
-      expect(svg.exists()).toBe(true)
-      expect(svg.find('path').attributes('d')).toBe(iconPath)
+      const pluginIcon = wrapper.findComponent({ name: 'PluginIcon' })
+      expect(pluginIcon.exists()).toBe(true)
+      expect(pluginIcon.props('icon')).toBe(iconPath)
+      expect(pluginIcon.props('variant')).toBe('solid')
+      expect(pluginIcon.props('size')).toBe('md')
       expect(wrapper.find('.mint-topbar__logo-text').exists()).toBe(false)
     })
 
-    it('should not render plugin icon when #icon slot is provided', () => {
+    it('should pass plugin.color to PluginIcon as tone', () => {
+      const iconPath = 'M13 10V3L4 14h7v7l9-11h-7z'
+      mockPlatformCtx({
+        isIntegrated: true,
+        plugin: {
+          id: 'test', name: 'Test', version: '1.0',
+          icon: iconPath, color: '#22C55E',
+          route_prefix: '/test', api_prefix: '/api/test',
+        },
+      })
+
+      const wrapper = createWrapper({ title: 'Test App' })
+
+      expect(wrapper.findComponent({ name: 'PluginIcon' }).props('tone')).toBe('#22C55E')
+    })
+
+    it('should not render PluginIcon when #icon slot is provided', () => {
       const iconPath = 'M13 10V3L4 14h7v7l9-11h-7z'
       mockPlatformCtx({
         isIntegrated: true,
@@ -651,10 +669,10 @@ describe('AppTopBar', () => {
       })
 
       expect(wrapper.find('.custom-icon').exists()).toBe(true)
-      expect(wrapper.find('.mint-topbar__logo-svg').exists()).toBe(false)
+      expect(wrapper.findComponent({ name: 'PluginIcon' }).exists()).toBe(false)
     })
 
-    it('should not render plugin icon when icon does not start with M', () => {
+    it('should still render PluginIcon when icon does not start with M (PluginIcon shows fallback)', () => {
       mockPlatformCtx({
         isIntegrated: true,
         plugin: { id: 'test', name: 'Test', version: '1.0', icon: 'invalid-path', route_prefix: '/test', api_prefix: '/api/test' },
@@ -662,12 +680,12 @@ describe('AppTopBar', () => {
 
       const wrapper = createWrapper({ title: 'Test App' })
 
-      expect(wrapper.find('.mint-topbar__logo-svg').exists()).toBe(false)
-      expect(wrapper.find('.mint-topbar__logo-text').exists()).toBe(true)
-      expect(wrapper.find('.mint-topbar__logo-text').text()).toBe('M')
+      // Topbar passes any non-empty icon string to PluginIcon, which decides what to render.
+      expect(wrapper.findComponent({ name: 'PluginIcon' }).exists()).toBe(true)
+      expect(wrapper.find('.mint-topbar__logo-text').exists()).toBe(false)
     })
 
-    it('should not render plugin icon when icon is empty string', () => {
+    it('should not render PluginIcon when icon is empty string', () => {
       mockPlatformCtx({
         isIntegrated: true,
         plugin: { id: 'test', name: 'Test', version: '1.0', icon: '', route_prefix: '/test', api_prefix: '/api/test' },
@@ -675,7 +693,7 @@ describe('AppTopBar', () => {
 
       const wrapper = createWrapper({ title: 'Test App' })
 
-      expect(wrapper.find('.mint-topbar__logo-svg').exists()).toBe(false)
+      expect(wrapper.findComponent({ name: 'PluginIcon' }).exists()).toBe(false)
       expect(wrapper.find('.mint-topbar__logo-text').exists()).toBe(true)
       expect(wrapper.find('.mint-topbar__logo-text').text()).toBe('M')
     })

package/src/__tests__/components/PluginIcon.test.ts

@@ -0,0 +1,119 @@
+import { describe, it, expect } from 'vitest'
+import { mount } from '@vue/test-utils'
+import PluginIcon from '../../components/PluginIcon.vue'
+
+const SAMPLE_PATH = 'M13 10V3L4 14h7v7l9-11h-7z'
+const SAMPLE_HTTPS_URL = 'https://example.com/icon.png'
+
+describe('PluginIcon', () => {
+  describe('format detection', () => {
+    it('should render SVG path when icon starts with M followed by digit', () => {
+      const wrapper = mount(PluginIcon, { props: { icon: SAMPLE_PATH } })
+      const path = wrapper.find('svg path')
+      expect(path.exists()).toBe(true)
+      expect(path.attributes('d')).toBe(SAMPLE_PATH)
+      expect(wrapper.find('img').exists()).toBe(false)
+    })
+
+    it('should render SVG path when icon starts with lowercase m and a space', () => {
+      const wrapper = mount(PluginIcon, { props: { icon: 'm 5,5 l 10,10' } })
+      const path = wrapper.find('svg path')
+      expect(path.exists()).toBe(true)
+      expect(path.attributes('d')).toBe('m 5,5 l 10,10')
+    })
+
+    it('should render SVG path after stripping leading whitespace', () => {
+      const wrapper = mount(PluginIcon, { props: { icon: '   ' + SAMPLE_PATH } })
+      const path = wrapper.find('svg path')
+      expect(path.exists()).toBe(true)
+      expect(path.attributes('d')).toBe(SAMPLE_PATH)
+    })
+
+    it('should render SVG path after stripping leading BOM', () => {
+      const wrapper = mount(PluginIcon, { props: { icon: '' + SAMPLE_PATH } })
+      const path = wrapper.find('svg path')
+      expect(path.exists()).toBe(true)
+      expect(path.attributes('d')).toBe(SAMPLE_PATH)
+    })
+
+    it('should render <img> for raster data URLs (png, jpeg, gif, webp)', () => {
+      for (const mime of ['png', 'jpeg', 'jpg', 'gif', 'webp']) {
+        const url = `data:image/${mime};base64,iVBORw0KGgo=`
+        const wrapper = mount(PluginIcon, { props: { icon: url } })
+        expect(wrapper.find('img').attributes('src')).toBe(url)
+        expect(wrapper.find('svg path').exists()).toBe(false)
+      }
+    })
+
+    it('should reject data:image/svg+xml as fallback (security)', () => {
+      const svgDataUrl = 'data:image/svg+xml;base64,PHN2Zz48L3N2Zz4='
+      const wrapper = mount(PluginIcon, { props: { icon: svgDataUrl } })
+      expect(wrapper.find('img').exists()).toBe(false)
+      expect(wrapper.find('svg path').exists()).toBe(true)
+      expect(wrapper.find('svg path').attributes('d')).not.toBe(svgDataUrl)
+    })
+
+    it('should render <img> for https URLs with referrer/lazy attributes', () => {
+      const wrapper = mount(PluginIcon, { props: { icon: SAMPLE_HTTPS_URL } })
+      const img = wrapper.find('img')
+      expect(img.attributes('src')).toBe(SAMPLE_HTTPS_URL)
+      expect(img.attributes('referrerpolicy')).toBe('no-referrer')
+      expect(img.attributes('loading')).toBe('lazy')
+    })
+
+    it('should reject http URLs as fallback (mixed-content)', () => {
+      const wrapper = mount(PluginIcon, { props: { icon: 'http://example.com/icon.png' } })
+      expect(wrapper.find('img').exists()).toBe(false)
+      expect(wrapper.find('svg path').exists()).toBe(true)
+    })
+
+    it('should render fallback path when icon is empty', () => {
+      const wrapper = mount(PluginIcon, { props: { icon: '' } })
+      expect(wrapper.find('svg path').exists()).toBe(true)
+      expect(wrapper.find('img').exists()).toBe(false)
+    })
+
+    it('should render fallback when icon is unrecognized', () => {
+      const wrapper = mount(PluginIcon, { props: { icon: 'markdown:foo' } })
+      expect(wrapper.find('svg path').exists()).toBe(true)
+      expect(wrapper.find('img').exists()).toBe(false)
+    })
+  })
+
+  describe('size and variant classes', () => {
+    it('should apply size class', () => {
+      const wrapper = mount(PluginIcon, { props: { icon: SAMPLE_PATH, size: 'lg' } })
+      expect(wrapper.classes()).toContain('mint-plugin-icon--lg')
+    })
+
+    it('should default size to md', () => {
+      const wrapper = mount(PluginIcon, { props: { icon: SAMPLE_PATH } })
+      expect(wrapper.classes()).toContain('mint-plugin-icon--md')
+    })
+
+    it('should apply variant class', () => {
+      const wrapper = mount(PluginIcon, { props: { icon: SAMPLE_PATH, variant: 'tinted' } })
+      expect(wrapper.classes()).toContain('mint-plugin-icon--tinted')
+    })
+
+    it('should default variant to solid', () => {
+      const wrapper = mount(PluginIcon, { props: { icon: SAMPLE_PATH } })
+      expect(wrapper.classes()).toContain('mint-plugin-icon--solid')
+    })
+  })
+
+  describe('tone', () => {
+    it('should apply tone via inline custom property', () => {
+      const wrapper = mount(PluginIcon, { props: { icon: SAMPLE_PATH, tone: '#0EA5E9' } })
+      const style = wrapper.attributes('style') || ''
+      expect(style).toContain('--mint-plugin-icon-tone')
+      expect(style).toContain('#0EA5E9')
+    })
+
+    it('should not apply tone style when undefined', () => {
+      const wrapper = mount(PluginIcon, { props: { icon: SAMPLE_PATH } })
+      const style = wrapper.attributes('style') || ''
+      expect(style).not.toContain('--mint-plugin-icon-tone')
+    })
+  })
+})

package/src/components/AppTopBar.vue

@@ -21,11 +21,10 @@ import AppPageSelector from './AppPageSelector.vue'
 import AppPillNav from './AppPillNav.vue'
 import AppAvatarMenu from './AppAvatarMenu.vue'
 import AppPluginSwitcher from './AppPluginSwitcher.vue'
+import PluginIcon from './PluginIcon.vue'
 import { usePlatformContext } from '../composables/usePlatformContext'
 import { APP_EXPERIMENT_KEY } from '../composables/useAppExperiment'
 
-const SVG_PATH_PREFIX = 'M'
-
 interface Props {
   // Classic title & breadcrumb
   title?: string
@@ -96,6 +95,7 @@ const emit = defineEmits<{
   'account-menu-select': [item: AccountMenuItem]
   'sign-out': []
   'notifications-click': []
+  'settings-values-change': [data: Record<string, unknown>]
 }>()
 
 const settingsOpen = ref(false)
@@ -103,10 +103,7 @@ const { isIntegrated, plugin } = usePlatformContext()
 const isStandalone = computed(() => !isIntegrated.value)
 const appExperiment = inject(APP_EXPERIMENT_KEY, null)
 
-const pluginIcon = computed(() => {
-  const icon = plugin.value?.icon
-  return icon && icon.startsWith(SVG_PATH_PREFIX) ? icon : null
-})
+const hasPluginIcon = computed(() => !!plugin.value?.icon)
 
 const profileInitial = computed(() => {
   if (props.userInitial) return props.userInitial
@@ -224,13 +221,14 @@ onUnmounted(() => {
           class="mint-topbar-home-link"
         >
           <slot name="icon">
-            <div v-if="pluginIcon" class="mint-topbar__logo">
-              <div class="mint-topbar__logo-icon">
-                <svg class="mint-topbar__logo-svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
-                  <path :d="pluginIcon" />
-                </svg>
-              </div>
-            </div>
+            <PluginIcon
+              v-if="hasPluginIcon"
+              class="mint-topbar__plugin-icon"
+              :icon="plugin!.icon"
+              :tone="plugin!.color"
+              size="md"
+              variant="solid"
+            />
             <slot v-else name="logo">
               <div v-if="showLogo" class="mint-topbar__logo">
                 <div class="mint-topbar__logo-icon">
@@ -246,13 +244,14 @@ onUnmounted(() => {
           class="mint-topbar-home-link"
         >
           <slot name="icon">
-            <div v-if="pluginIcon" class="mint-topbar__logo">
-              <div class="mint-topbar__logo-icon">
-                <svg class="mint-topbar__logo-svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
-                  <path :d="pluginIcon" />
-                </svg>
-              </div>
-            </div>
+            <PluginIcon
+              v-if="hasPluginIcon"
+              class="mint-topbar__plugin-icon"
+              :icon="plugin!.icon"
+              :tone="plugin!.color"
+              size="md"
+              variant="solid"
+            />
             <slot v-else name="logo">
               <div v-if="showLogo" class="mint-topbar__logo">
                 <div class="mint-topbar__logo-icon">
@@ -264,13 +263,14 @@ onUnmounted(() => {
         </router-link>
         <template v-else>
           <slot name="icon">
-            <div v-if="pluginIcon" class="mint-topbar__logo">
-              <div class="mint-topbar__logo-icon">
-                <svg class="mint-topbar__logo-svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
-                  <path :d="pluginIcon" />
-                </svg>
-              </div>
-            </div>
+            <PluginIcon
+              v-if="hasPluginIcon"
+              class="mint-topbar__plugin-icon"
+              :icon="plugin!.icon"
+              :tone="plugin!.color"
+              size="md"
+              variant="solid"
+            />
             <slot v-else name="logo">
               <div v-if="showLogo" class="mint-topbar__logo">
                 <div class="mint-topbar__logo-icon">
@@ -637,6 +637,11 @@ onUnmounted(() => {
     :tabs="settingsConfig?.tabs"
     :show-appearance="settingsConfig?.showAppearance ?? true"
     :size="settingsConfig?.size"
+    :layout="settingsConfig?.layout"
+    :schema="settingsConfig?.schema"
+    :values="settingsConfig?.values"
+    :enhancements="settingsConfig?.enhancements"
+    @update:values="emit('settings-values-change', $event)"
   >
     <template v-for="tab in (settingsConfig?.tabs ?? [])" :key="tab.id" #[`tab-${tab.id}`]>
       <slot :name="`settings-tab-${tab.id}`" />

package/src/components/PluginIcon.story.vue

@@ -0,0 +1,71 @@
+<script setup lang="ts">
+import { reactive } from 'vue'
+import PluginIcon from './PluginIcon.vue'
+
+const SAMPLE_PATH = 'M13 10V3L4 14h7v7l9-11h-7z'
+// Tiny 1x1 transparent PNG.
+const SAMPLE_PNG = 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkAAIAAAoAAv/lxKUAAAAASUVORK5CYII='
+const SAMPLE_HTTPS = 'https://upload.wikimedia.org/wikipedia/commons/thumb/4/4f/Vue.js_Logo_2.svg/64px-Vue.js_Logo_2.svg.png'
+
+function initState() {
+  return reactive({
+    icon: SAMPLE_PATH,
+    size: 'md' as 'sm' | 'md' | 'lg',
+    variant: 'solid' as 'solid' | 'tinted',
+    tone: '',
+  })
+}
+</script>
+
+<template>
+  <Story title="Brand/PluginIcon" :layout="{ type: 'grid', width: 320 }">
+    <Variant title="Playground" :init-state="initState">
+      <template #default="{ state }">
+        <div style="padding: 2rem; max-width: 600px;">
+          <PluginIcon :icon="state.icon" :size="state.size" :variant="state.variant" :tone="state.tone || undefined" />
+        </div>
+      </template>
+      <template #controls="{ state }">
+        <HstText v-model="state.icon" title="icon" />
+        <HstSelect v-model="state.size" title="size" :options="['sm', 'md', 'lg']" />
+        <HstSelect v-model="state.variant" title="variant" :options="['solid', 'tinted']" />
+        <HstText v-model="state.tone" title="tone (hex)" />
+      </template>
+    </Variant>
+
+    <Variant title="Sizes">
+      <div style="padding: 2rem; display: flex; gap: 1rem; align-items: center;">
+        <PluginIcon :icon="SAMPLE_PATH" size="sm" />
+        <PluginIcon :icon="SAMPLE_PATH" size="md" />
+        <PluginIcon :icon="SAMPLE_PATH" size="lg" />
+      </div>
+    </Variant>
+
+    <Variant title="Variants">
+      <div style="padding: 2rem; display: flex; gap: 1rem; align-items: center;">
+        <PluginIcon :icon="SAMPLE_PATH" variant="solid" />
+        <PluginIcon :icon="SAMPLE_PATH" variant="tinted" />
+      </div>
+    </Variant>
+
+    <Variant title="Format showcase">
+      <div style="padding: 2rem; display: flex; gap: 1rem; align-items: center;">
+        <PluginIcon :icon="SAMPLE_PATH" size="lg" variant="tinted" />
+        <PluginIcon :icon="SAMPLE_PNG" size="lg" variant="tinted" />
+        <PluginIcon :icon="SAMPLE_HTTPS" size="lg" variant="tinted" />
+        <PluginIcon icon="" size="lg" variant="tinted" />
+      </div>
+      <p style="padding: 0 2rem; color: var(--text-muted); font-size: 0.875rem;">
+        SVG path · data URL (PNG) · https URL · empty (fallback)
+      </p>
+    </Variant>
+
+    <Variant title="Tone overrides">
+      <div style="padding: 2rem; display: flex; gap: 1rem; align-items: center;">
+        <PluginIcon :icon="SAMPLE_PATH" size="lg" variant="solid" tone="#0EA5E9" />
+        <PluginIcon :icon="SAMPLE_PATH" size="lg" variant="solid" tone="#F97316" />
+        <PluginIcon :icon="SAMPLE_PATH" size="lg" variant="solid" tone="#22C55E" />
+      </div>
+    </Variant>
+  </Story>
+</template>

package/src/components/PluginIcon.vue

@@ -0,0 +1,88 @@
+<script setup lang="ts">
+/** Renders a plugin's icon as a sized chip. Auto-detects format:
+ *  - SVG path data (e.g. "M13 10V3...") → inline <svg><path>
+ *  - Raster data URL (data:image/png|jpeg|jpg|gif|webp;...) → <img>
+ *  - https:// URL → <img> with no-referrer + lazy loading
+ *  - Anything else → MINT canonical plugin placeholder path
+ *
+ *  http:// URLs and data:image/svg+xml URLs are deliberately rejected
+ *  (mixed-content + XSS, see spec 2026-05-04-plugin-icon-component-design.md). */
+import { computed } from 'vue'
+
+defineOptions({ name: 'PluginIcon' })
+
+interface Props {
+  icon?: string
+  size?: 'sm' | 'md' | 'lg'
+  variant?: 'solid' | 'tinted'
+  tone?: string
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  size: 'md',
+  variant: 'solid',
+})
+
+// MINT canonical plugin placeholder — page-with-corner-fold glyph.
+const FALLBACK_PATH = 'M14 7v4a1 1 0 0 0 1 1h4M5 3h9l5 5v11a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2z'
+
+const PATH_REGEX = /^[Mm][\s,\d\-.]/
+const RASTER_DATA_URL_REGEX = /^data:image\/(png|jpeg|jpg|gif|webp);/
+
+type Format = 'path' | 'data-url' | 'https-url' | 'fallback'
+
+interface Detected {
+  format: Format
+  value: string
+}
+
+const detected = computed<Detected>(() => {
+  // Strip leading whitespace and BOM before pattern checks.
+  const raw = (props.icon ?? '').replace(/^[\s]+/, '')
+  if (!raw) return { format: 'fallback', value: FALLBACK_PATH }
+  if (PATH_REGEX.test(raw)) return { format: 'path', value: raw }
+  if (RASTER_DATA_URL_REGEX.test(raw)) return { format: 'data-url', value: raw }
+  if (raw.startsWith('https://')) return { format: 'https-url', value: raw }
+  return { format: 'fallback', value: FALLBACK_PATH }
+})
+
+const rootClasses = computed(() => [
+  'mint-plugin-icon',
+  `mint-plugin-icon--${props.size}`,
+  `mint-plugin-icon--${props.variant}`,
+])
+
+const rootStyle = computed(() =>
+  props.tone ? { '--mint-plugin-icon-tone': props.tone } : undefined,
+)
+</script>
+
+<template>
+  <span :class="rootClasses" :style="rootStyle">
+    <svg
+      v-if="detected.format === 'path' || detected.format === 'fallback'"
+      class="mint-plugin-icon__svg"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      stroke-width="2"
+      stroke-linecap="round"
+      stroke-linejoin="round"
+      aria-hidden="true"
+    >
+      <path :d="detected.value" />
+    </svg>
+    <img
+      v-else
+      class="mint-plugin-icon__img"
+      :src="detected.value"
+      alt=""
+      referrerpolicy="no-referrer"
+      loading="lazy"
+    />
+  </span>
+</template>
+
+<style>
+@import '../styles/components/plugin-icon.css';
+</style>