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

package/src/components/SettingsModal.vue

@@ -1,16 +1,67 @@
 <script setup lang="ts">
-/** Tabbed settings modal with a built-in appearance tab (theme, color palette, table density) and extensible custom tabs. */
-import { ref, computed } from 'vue'
+/**
+ * Tabbed settings modal with three usage modes:
+ *
+ *   1. Schema-driven (recommended) — pass `schema` + `v-model:values`. Each
+ *      group becomes a tab; fields auto-render via the SDK's FormFieldRenderer
+ *      registry (text, select, number, toggle, molecule, concentration, …).
+ *      Conditional visibility, validation, and dynamic options come for free.
+ *
+ *   2. Manual tabs + slots — pass `tabs` and a `<template #tab-{id}>` slot
+ *      per tab. Use this when you need bespoke widgets the form-builder
+ *      registry doesn't cover (or for legacy plugins).
+ *
+ *   3. Appearance only — `showAppearance` (default true) renders the built-in
+ *      theme / palette / table-density tab. Works alongside both modes above.
+ *
+ * Layout: `horizontal` (underline tabs, default) or `vertical` (sidebar rail
+ * with optional icons + descriptions, recommended for 5+ groups).
+ */
+import { ref, computed, watch } from 'vue'
 import BaseModal from './BaseModal.vue'
+import FormFieldRenderer from './FormFieldRenderer.vue'
+import { useFormBuilder } from '../composables/useFormBuilder'
 import { useSettingsStore, colorPalettes } from '../stores/settings'
-import type { ThemeMode, ColorPalette, TableDensity, SettingsTab } from '../types'
+import type {
+  ThemeMode,
+  ColorPalette,
+  TableDensity,
+  SettingsTab,
+  SettingsModalLayout,
+  SettingsModalSchema,
+  FormSchema,
+  FormSectionSchema,
+  FormEnhancements,
+} from '../types'
+
+// Map our settings groups onto the form-builder's flat-section shape.
+// `title: ''` because the rail/pane header already shows the group name.
+function buildFlatSchema(schema: SettingsModalSchema): FormSchema {
+  return {
+    sections: schema.groups.map<FormSectionSchema>((g) => ({
+      id: g.id,
+      title: '',
+      fields: g.fields,
+      columns: g.columns,
+      condition: g.condition,
+    })),
+  }
+}
 
 interface Props {
   modelValue: boolean
   title?: string
+  /** Manual tab descriptors. Ignored when `schema` is set (groups become tabs). */
   tabs?: SettingsTab[]
   showAppearance?: boolean
   size?: 'md' | 'lg' | 'xl'
+  layout?: SettingsModalLayout
+  /** Declarative schema — fields auto-render via SDK form components. */
+  schema?: SettingsModalSchema
+  /** Two-way bound values when `schema` is set. */
+  values?: Record<string, unknown>
+  /** Optional dynamic enhancements (validators, dynamic options, callbacks). */
+  enhancements?: FormEnhancements<Record<string, unknown>>
 }
 
 const props = withDefaults(defineProps<Props>(), {
@@ -18,22 +69,85 @@ const props = withDefaults(defineProps<Props>(), {
   tabs: () => [],
   showAppearance: true,
   size: 'lg',
+  layout: 'horizontal',
 })
 
 const emit = defineEmits<{
   'update:modelValue': [value: boolean]
+  'update:values': [data: Record<string, unknown>]
   close: []
 }>()
 
 const settings = useSettingsStore()
 
-const allTabs = computed<SettingsTab[]>(() =>
-  props.showAppearance
-    ? [...props.tabs, { id: 'appearance', label: 'Appearance' }]
+const APPEARANCE_TAB_ID = 'appearance'
+
+const APPEARANCE_TAB: SettingsTab = {
+  id: APPEARANCE_TAB_ID,
+  label: 'Appearance',
+  description: 'Theme, color palette, and table density',
+}
+
+const isVertical = computed(() => props.layout === 'vertical')
+
+// Per-instance prefix for ARIA tab/tabpanel id wiring. Stable across renders.
+const uid = `mint-settings-${Math.random().toString(36).slice(2, 9)}`
+const tabId = (id: string) => `${uid}-tab-${id}`
+const panelId = (id: string) => `${uid}-panel-${id}`
+
+// `props.schema` is read once at setup. Pass a stable schema object (declare it
+// at module scope, not inside a render function) — the form-builder is not
+// re-initialized when the prop changes. To swap schemas, key the modal:
+// `<SettingsModal :key="schemaId" :schema="schemaA" />`.
+const builder = props.schema
+  ? useFormBuilder(buildFlatSchema(props.schema), props.values, props.enhancements)
+  : null
+
+if (builder) {
+  watch(
+    () => ({ ...builder.form.data }),
+    (data) => emit('update:values', data as Record<string, unknown>),
+    { deep: true },
+  )
+}
+
+// Schema groups whose `condition` evaluates false against the current data are
+// dropped from the rail entirely — same semantics as section visibility in
+// FormBuilder. Manual `tabs` have no condition mechanism, so they pass through.
+const visibleSchemaGroups = computed(() =>
+  builder && props.schema
+    ? props.schema.groups.filter((g) => builder.isSectionVisible(g.id))
+    : [],
+)
+
+const allTabs = computed<SettingsTab[]>(() => {
+  const base: SettingsTab[] = props.schema
+    ? visibleSchemaGroups.value.map((g) => ({ id: g.id, label: g.label, icon: g.icon, description: g.description }))
     : props.tabs
+  return props.showAppearance ? [...base, APPEARANCE_TAB] : base
+})
+
+const activeTab = ref(allTabs.value[0]?.id || APPEARANCE_TAB_ID)
+
+const activeTabMeta = computed<SettingsTab | undefined>(() =>
+  allTabs.value.find((t) => t.id === activeTab.value),
+)
+
+// If the active tab vanishes (group hidden by condition), drop back to the first available.
+watch(allTabs, (tabs) => {
+  if (!tabs.some((t) => t.id === activeTab.value)) {
+    activeTab.value = tabs[0]?.id ?? APPEARANCE_TAB_ID
+  }
+})
+
+const activeGroup = computed(() =>
+  visibleSchemaGroups.value.find((g) => g.id === activeTab.value),
 )
 
-const activeTab = ref(allTabs.value[0]?.id || 'appearance')
+const activeGroupVisibleFields = computed(() => {
+  if (!activeGroup.value || !builder) return []
+  return activeGroup.value.fields.filter((f) => builder.isFieldVisible(f.name))
+})
 
 const themeOptions: { value: ThemeMode; label: string }[] = [
   { value: 'light', label: 'Light' },
@@ -61,9 +175,11 @@ function handleClose() {
     @update:model-value="emit('update:modelValue', $event)"
     @close="handleClose"
   >
-    <div class="mint-settings-modal">
-      <!-- Tabs -->
-      <div v-if="allTabs.length > 1" class="mint-settings-modal__tabs">
+    <div :class="['mint-settings-modal', `mint-settings-modal--${layout}`]">
+      <div
+        v-if="!isVertical && allTabs.length > 1"
+        class="mint-settings-modal__tabs"
+      >
         <button
           v-for="tab in allTabs"
           :key="tab.id"
@@ -75,68 +191,139 @@ function handleClose() {
         </button>
       </div>
 
-      <!-- Custom tab content -->
-      <div class="mint-settings-modal__content">
-        <template v-for="tab in tabs" :key="tab.id">
-          <div v-show="activeTab === tab.id">
-            <slot :name="`tab-${tab.id}`" />
+      <div
+        v-else-if="isVertical"
+        class="mint-settings-modal__rail"
+        role="tablist"
+        aria-orientation="vertical"
+        aria-label="Settings sections"
+      >
+        <button
+          v-for="tab in allTabs"
+          :id="tabId(tab.id)"
+          :key="tab.id"
+          type="button"
+          role="tab"
+          :class="['mint-settings-modal__rail-item', { 'mint-settings-modal__rail-item--active': activeTab === tab.id }]"
+          :aria-selected="activeTab === tab.id"
+          :aria-controls="panelId(tab.id)"
+          :tabindex="activeTab === tab.id ? 0 : -1"
+          @click="activeTab = tab.id"
+        >
+          <span class="mint-settings-modal__rail-item-icon" aria-hidden="true">
+            <span v-if="tab.icon" v-html="tab.icon" />
+          </span>
+          <span class="mint-settings-modal__rail-item-text">
+            <span class="mint-settings-modal__rail-item-label">{{ tab.label }}</span>
+            <span v-if="tab.description" class="mint-settings-modal__rail-item-description">
+              {{ tab.description }}
+            </span>
+          </span>
+        </button>
+      </div>
+
+      <!-- Vertical mode wraps content in a tabpanel <section> with a header bar; horizontal mode stays a plain <div>. -->
+      <component
+        :is="isVertical ? 'section' : 'div'"
+        :class="isVertical ? 'mint-settings-modal__pane' : 'mint-settings-modal__content'"
+        :id="isVertical && activeTabMeta ? panelId(activeTabMeta.id) : undefined"
+        :role="isVertical ? 'tabpanel' : undefined"
+        :aria-labelledby="isVertical && activeTabMeta ? tabId(activeTabMeta.id) : undefined"
+        :tabindex="isVertical ? 0 : undefined"
+      >
+        <header
+          v-if="isVertical && activeTabMeta?.label"
+          class="mint-settings-modal__pane-header"
+        >
+          <h4 class="mint-settings-modal__pane-title">{{ activeTabMeta.label }}</h4>
+          <p v-if="activeTabMeta.description" class="mint-settings-modal__pane-subtitle">
+            {{ activeTabMeta.description }}
+          </p>
+        </header>
+
+        <div :class="isVertical ? 'mint-settings-modal__pane-body' : null">
+          <div
+            v-if="schema && builder && activeGroup"
+            class="mint-settings-modal__group-grid"
+            :style="{ '--mint-settings-cols': activeGroup.columns ?? 1 }"
+          >
+            <template v-for="field in activeGroupVisibleFields" :key="field.name">
+              <div :style="field.colSpan ? { gridColumn: `span ${field.colSpan}` } : undefined">
+                <slot
+                  :name="`field:${field.name}`"
+                  :field="field"
+                  :form="builder.form"
+                  :field-props="builder.form.getFieldProps(field.name)"
+                >
+                  <FormFieldRenderer
+                    :field="field"
+                    :resolved-props="builder.getResolvedFieldProps(field)"
+                    :form="builder.form"
+                  />
+                </slot>
+              </div>
+            </template>
           </div>
-        </template>
-
-        <!-- Built-in appearance tab -->
-        <div v-if="showAppearance" v-show="activeTab === 'appearance'">
-          <!-- Theme -->
-          <div class="mint-settings-modal__section">
-            <div class="mint-settings-modal__section-label">Theme</div>
-            <div class="mint-settings-modal__option-group">
-              <button
-                v-for="opt in themeOptions"
-                :key="opt.value"
-                type="button"
-                :class="['mint-settings-modal__option-btn', { 'mint-settings-modal__option-btn--active': settings.theme === opt.value }]"
-                @click="settings.theme = opt.value"
-              >
-                {{ opt.label }}
-              </button>
+
+          <template v-else-if="!builder">
+            <template v-for="tab in tabs" :key="tab.id">
+              <div v-show="activeTab === tab.id">
+                <slot :name="`tab-${tab.id}`" />
+              </div>
+            </template>
+          </template>
+
+          <div v-if="showAppearance" v-show="activeTab === APPEARANCE_TAB_ID">
+            <div class="mint-settings-modal__section">
+              <div class="mint-settings-modal__section-label">Theme</div>
+              <div class="mint-settings-modal__option-group">
+                <button
+                  v-for="opt in themeOptions"
+                  :key="opt.value"
+                  type="button"
+                  :class="['mint-settings-modal__option-btn', { 'mint-settings-modal__option-btn--active': settings.theme === opt.value }]"
+                  @click="settings.theme = opt.value"
+                >
+                  {{ opt.label }}
+                </button>
+              </div>
             </div>
-          </div>
 
-          <!-- Color palette -->
-          <div class="mint-settings-modal__section">
-            <div class="mint-settings-modal__section-label">Color Palette</div>
-            <div class="mint-settings-modal__option-group">
-              <button
-                v-for="(palette, key) in colorPalettes"
-                :key="key"
-                type="button"
-                :class="['mint-settings-modal__option-btn', { 'mint-settings-modal__option-btn--active': settings.colorPalette === key }]"
-                @click="settings.colorPalette = key as ColorPalette"
-              >
-                {{ palette.name }}
-              </button>
+            <div class="mint-settings-modal__section">
+              <div class="mint-settings-modal__section-label">Color Palette</div>
+              <div class="mint-settings-modal__option-group">
+                <button
+                  v-for="(palette, key) in colorPalettes"
+                  :key="key"
+                  type="button"
+                  :class="['mint-settings-modal__option-btn', { 'mint-settings-modal__option-btn--active': settings.colorPalette === key }]"
+                  @click="settings.colorPalette = key as ColorPalette"
+                >
+                  {{ palette.name }}
+                </button>
+              </div>
             </div>
-          </div>
 
-          <!-- Table density -->
-          <div class="mint-settings-modal__section">
-            <div class="mint-settings-modal__section-label">Table Density</div>
-            <div class="mint-settings-modal__option-group">
-              <button
-                v-for="opt in densityOptions"
-                :key="opt.value"
-                type="button"
-                :class="['mint-settings-modal__option-btn', { 'mint-settings-modal__option-btn--active': settings.tableDensity === opt.value }]"
-                @click="settings.tableDensity = opt.value"
-              >
-                {{ opt.label }}
-              </button>
+            <div class="mint-settings-modal__section">
+              <div class="mint-settings-modal__section-label">Table Density</div>
+              <div class="mint-settings-modal__option-group">
+                <button
+                  v-for="opt in densityOptions"
+                  :key="opt.value"
+                  type="button"
+                  :class="['mint-settings-modal__option-btn', { 'mint-settings-modal__option-btn--active': settings.tableDensity === opt.value }]"
+                  @click="settings.tableDensity = opt.value"
+                >
+                  {{ opt.label }}
+                </button>
+              </div>
+              <p class="mint-settings-modal__note">Adjusts row height in data tables.</p>
             </div>
-            <p class="mint-settings-modal__note">Adjusts row height in data tables.</p>
-          </div>
 
-          <slot name="appearance" />
+            <slot name="appearance" />
+          </div>
         </div>
-      </div>
+      </component>
     </div>
   </BaseModal>
 </template>

package/src/components/index.ts

@@ -45,6 +45,7 @@ export { default as AppPluginSwitcher } from './AppPluginSwitcher.vue'
 export { default as AppSidebar } from './AppSidebar.vue'
 export { default as AppLayout } from './AppLayout.vue'
 export { default as AppContainer } from './AppContainer.vue'
+export { default as PluginIcon } from './PluginIcon.vue'
 
 // Utility components
 export { default as Skeleton } from './Skeleton.vue'

package/src/index.ts

@@ -38,6 +38,7 @@ export {
   AppSidebar,
   AppLayout,
   AppContainer,
+  PluginIcon,
   Skeleton,
   // Biological experiment components
   WellPlate,
@@ -301,6 +302,9 @@ export type {
   ConfirmVariant,
   // SettingsModal types
   SettingsTab,
+  SettingsModalLayout,
+  SettingsGroup,
+  SettingsModalSchema,
   // ScientificNumber types
   NumberNotation,
   // TimePicker types

package/src/styles/components/app-pill-nav.css

@@ -13,8 +13,7 @@
   display: inline-flex;
   align-items: center;
   border: 0;
-  /* 1px optical centering offset for 13px text. See CLAUDE.md § Optical Centering. */
-  padding: 0.3125rem 0.875rem 0.4375rem;
+  padding: 0.375rem 0.875rem;
   border-radius: 9999px;
   font-size: 0.8125rem;
   font-weight: 500;

package/src/styles/components/app-top-bar.css

@@ -278,8 +278,7 @@
   display: inline-flex;
   align-items: center;
   gap: 0.25rem;
-  /* Asymmetric top/bottom padding — Fira Sans optical centering. */
-  padding: 0.3125rem 0.875rem 0.4375rem;
+  padding: 0.375rem 0.875rem;
   border: 0;
   background: transparent;
   border-radius: 9999px;

package/src/styles/components/button.css

@@ -133,24 +133,20 @@
 }
 
 /* Sizes */
-/* Optical centering: Fira Sans' cap-letter midpoint sits above the em-box center.
-   Old rule (pre-0.16) compensated with a 2px upward shift; user testing showed
-   that read as "too high" across sizes. New rule: 1px upward shift universally.
-   See CLAUDE.md § Optical Centering. */
 .mint-button--sm {
-  padding: 0.3125rem 0.75rem 0.4375rem;
+  padding: 0.375rem 0.75rem;
   font-size: 0.875rem;
   min-height: var(--form-height-sm);
 }
 
 .mint-button--md {
-  padding: 0.4375rem 1rem 0.5625rem;
+  padding: 0.5rem 1rem;
   font-size: 0.875rem;
   min-height: var(--form-height-md);
 }
 
 .mint-button--lg {
-  padding: 0.6875rem 1.5rem 0.8125rem;
+  padding: 0.75rem 1.5rem;
   font-size: 1rem;
   min-height: var(--form-height-lg);
 }

package/src/styles/components/dropdown-button.css

@@ -125,21 +125,21 @@
   background-color: var(--bg-tertiary);
 }
 
-/* Trigger sizes — 1px optical padding shift (0.16+). See CLAUDE.md § Optical Centering. */
+/* Trigger sizes */
 .mint-dropdown-button__trigger--sm {
-  padding: 0.3125rem 0.75rem 0.4375rem;
+  padding: 0.375rem 0.75rem;
   font-size: 0.875rem;
   min-height: var(--form-height-sm);
 }
 
 .mint-dropdown-button__trigger--md {
-  padding: 0.4375rem 1rem 0.5625rem;
+  padding: 0.5rem 1rem;
   font-size: 0.875rem;
   min-height: var(--form-height-md);
 }
 
 .mint-dropdown-button__trigger--lg {
-  padding: 0.6875rem 1.5rem 0.8125rem;
+  padding: 0.75rem 1.5rem;
   font-size: 1rem;
   min-height: var(--form-height-lg);
 }

package/src/styles/components/input.css

@@ -45,22 +45,21 @@
   cursor: not-allowed;
 }
 
-/* Size variants — 1px optical padding shift (0.16+).
-   See CLAUDE.md § Optical Centering. */
+/* Size variants */
 .mint-input--sm {
-  padding: 0.3125rem 0.625rem 0.4375rem;
+  padding: 0.375rem 0.625rem;
   font-size: 0.8125rem;
   min-height: var(--form-height-sm);
 }
 
 .mint-input--md {
-  padding: 0.4375rem 0.75rem 0.5625rem;
+  padding: 0.5rem 0.75rem;
   font-size: 0.875rem;
   min-height: var(--form-height-md);
 }
 
 .mint-input--lg {
-  padding: 0.6875rem 1rem 0.8125rem;
+  padding: 0.75rem 1rem;
   font-size: 1rem;
   min-height: var(--form-height-lg);
 }

package/src/styles/components/number-input.css

@@ -72,9 +72,9 @@
 
 /* Horizontal padding matches BaseInput canonical scale (10/12/16) so FormField's
    12px label indent aligns with the numeric text across all input types. */
-.mint-number-input__input--sm { padding: 0.3125rem 0.625rem 0.4375rem; font-size: 0.875rem; }
-.mint-number-input__input--md { padding: 0.4375rem 0.75rem 0.5625rem;  font-size: 0.875rem; }
-.mint-number-input__input--lg { padding: 0.6875rem 1rem 0.8125rem;     font-size: 1rem; }
+.mint-number-input__input--sm { padding: 0.375rem 0.625rem; font-size: 0.875rem; }
+.mint-number-input__input--md { padding: 0.5rem 0.75rem;    font-size: 0.875rem; }
+.mint-number-input__input--lg { padding: 0.75rem 1rem;      font-size: 1rem; }
 
 /* ---------- Unit suffix ---------- */
 

package/src/styles/components/plugin-icon.css

@@ -0,0 +1,38 @@
+/* PluginIcon — BEM. Renders a plugin's icon inside a sized chip with two
+   visual variants. Tintable via `--mint-plugin-icon-tone` custom property. */
+
+.mint-plugin-icon {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+  border-radius: var(--radius-md, 0.5rem);
+  overflow: hidden;
+}
+
+/* Sizes */
+.mint-plugin-icon--sm { width: 1.5rem; height: 1.5rem; }
+.mint-plugin-icon--md { width: 2rem;   height: 2rem;   }
+.mint-plugin-icon--lg { width: 3rem;   height: 3rem; border-radius: 0.75rem; }
+
+/* Variants — `--mint-plugin-icon-tone` falls back to --color-primary */
+.mint-plugin-icon--solid {
+  background-color: var(--mint-plugin-icon-tone, var(--color-primary));
+  color: white;
+}
+.mint-plugin-icon--tinted {
+  background-color: color-mix(in srgb, var(--mint-plugin-icon-tone, var(--color-primary)) 12%, transparent);
+  color: var(--mint-plugin-icon-tone, var(--color-primary));
+}
+
+/* Inner svg/img — sized to ~62% of chip */
+.mint-plugin-icon--sm .mint-plugin-icon__svg,
+.mint-plugin-icon--sm .mint-plugin-icon__img { width: 0.9375rem; height: 0.9375rem; }
+.mint-plugin-icon--md .mint-plugin-icon__svg,
+.mint-plugin-icon--md .mint-plugin-icon__img { width: 1.125rem;  height: 1.125rem;  }
+.mint-plugin-icon--lg .mint-plugin-icon__svg,
+.mint-plugin-icon--lg .mint-plugin-icon__img { width: 1.5rem;    height: 1.5rem;    }
+
+.mint-plugin-icon__img {
+  object-fit: contain;
+}

package/src/styles/components/segmented-control.css

@@ -114,24 +114,21 @@
   box-shadow: 0 1px 2px rgba(0, 0, 0, 0.1);
 }
 
-/* Size variants - simple — 1px optical padding shift universally (0.16+).
-   See CLAUDE.md § Optical Centering. */
+/* Size variants - simple */
 .mint-segmented-control__option--simple.mint-segmented-control__option--sm {
-  padding: 0.3125rem 0.75rem 0.4375rem;
+  padding: 0.375rem 0.75rem;
   font-size: 0.75rem;
   min-height: var(--form-height-sm);
 }
 
 .mint-segmented-control__option--simple.mint-segmented-control__option--md {
-  padding: 0.4375rem 1rem 0.5625rem;
+  padding: 0.5rem 1rem;
   font-size: 0.875rem;
   min-height: var(--form-height-md);
 }
 
 .mint-segmented-control__option--simple.mint-segmented-control__option--lg {
-  /* 9/11 (not 11/13 like BaseButton lg) — SegmentedControl uses a smaller
-     em-box at 1rem font + 1.25 line-height, so the 1px shift lands here. */
-  padding: 0.5625rem 1.25rem 0.6875rem;
+  padding: 0.625rem 1.25rem;
   font-size: 1rem;
   min-height: var(--form-height-lg);
 }