@morscherlab/mint-sdk 1.0.0-beta.1 → 1.0.0-beta.3

package/src/components/SettingsModal.vue

@@ -1,16 +1,91 @@
 <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`, compact `controls`, or a
+ *      complete `defineControlModel()` result plus `v-model:values`. Each
+ *      group/section becomes a tab; fields auto-render via the SDK form field
+ *      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 FormFieldRendererInternal from './internal/FormFieldRendererInternal.vue'
+import { useFormBuilder } from '../composables/useFormBuilder'
+import {
+  controlsToSettingsSchema,
+  defineControlModel,
+  mergeControlWorkspaceOptions,
+  type ControlModel,
+  type ControlModelBinding,
+  type ControlSchema,
+  type ControlWorkspaceOptions,
+} from '../composables/useControlSchema'
 import { useSettingsStore, colorPalettes } from '../stores/settings'
-import type { ThemeMode, ColorPalette, TableDensity, SettingsTab } from '../types'
+import {
+  formSchemaFieldNames,
+  pickExistingRecordKeys,
+  pickRecordKeys,
+  recordValuesEqualForKeys,
+} from '../utils/formModelSync'
+import type {
+  ThemeMode,
+  ColorPalette,
+  TableDensity,
+  SettingsTab,
+  SettingsTabInput,
+  SettingsModalLayout,
+  SettingsModalSchema,
+  FormSchema,
+  FormSectionSchema,
+  FormEnhancements,
+} from '../types'
+import { normalizeItemInput } from '../utils/items'
+
+// 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
-  tabs?: SettingsTab[]
+  /** Manual tab descriptors. Ignored when `schema` is set (groups become tabs). */
+  tabs?: SettingsTabInput[]
   showAppearance?: boolean
   size?: 'md' | 'lg' | 'xl'
+  layout?: SettingsModalLayout
+  /** Declarative schema — fields auto-render via SDK form components. */
+  schema?: SettingsModalSchema
+  /** Model returned by defineControlModel(), or a raw nested ControlModel for one-step settings generation. */
+  model?: ControlModel | ControlModelBinding
+  /** Compact controls model — converted to `schema` when `schema` is not set. */
+  controls?: ControlSchema
+  /** Conversion options for `controls`, such as section labels, columns, and shared initialValues. */
+  controlOptions?: ControlWorkspaceOptions
+  /** Two-way bound values when `schema`, `model`, or `controls` 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 +93,144 @@ const props = withDefaults(defineProps<Props>(), {
   tabs: () => [],
   showAppearance: true,
   size: 'lg',
+  layout: 'horizontal',
+  model: undefined,
 })
 
 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' }]
-    : props.tabs
+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}`
+
+const resolvedModel = computed<ControlModelBinding | undefined>(() => {
+  if (props.model === undefined) return undefined
+  return isControlModelBinding(props.model) ? props.model : defineControlModel(props.model)
+})
+const resolvedControls = computed<ControlSchema | undefined>(() =>
+  props.controls ?? resolvedModel.value?.controls,
+)
+const resolvedControlOptions = computed<ControlWorkspaceOptions>(() =>
+  mergeControlWorkspaceOptions(resolvedModel.value?.controlOptions ?? {}, props.controlOptions)
+)
+const settingsSchema = computed<SettingsModalSchema | undefined>(() =>
+  props.schema ?? (
+    resolvedControls.value
+      ? controlsToSettingsSchema(resolvedControls.value, resolvedControlOptions.value)
+      : undefined
+  ),
+)
+const isSchemaDriven = computed(() => !!settingsSchema.value)
+const resolvedValues = computed<Record<string, unknown>>(() => ({
+  ...(resolvedControlOptions.value.initialValues ?? {}),
+  ...(props.values ?? {}),
+}))
+
+// Schema-driven mode keeps one form-builder instance and syncs schema changes
+// into it, so callers can swap groups/fields without remounting the modal.
+const builder = useFormBuilder(
+  settingsSchema.value ? buildFlatSchema(settingsSchema.value) : { sections: [] },
+  resolvedValues.value,
+  props.enhancements,
+)
+
+watch(
+  () => settingsSchema.value,
+  (schema) => {
+    if (!schema) {
+      builder.updateSchema({ sections: [] }, {})
+      return
+    }
+
+    const flatSchema = buildFlatSchema(schema)
+    const fieldNames = formSchemaFieldNames(flatSchema)
+    const sourceValues = props.values === undefined
+      ? {
+          ...resolvedValues.value,
+          ...(builder.form.data as Record<string, unknown>),
+        }
+      : resolvedValues.value
+
+    builder.updateSchema(flatSchema, pickExistingRecordKeys(sourceValues ?? {}, fieldNames))
+  },
+  { deep: true },
+)
+
+watch(
+  () => ({ ...resolvedValues.value }),
+  (data) => {
+    if (!settingsSchema.value) return
+    const fieldNames = builderFieldNames()
+    if (recordValuesEqualForKeys(data, builder.form.data as Record<string, unknown>, fieldNames)) return
+    builder.reset(pickRecordKeys(data, fieldNames))
+  },
+  { deep: true },
+)
+
+watch(
+  () => ({ ...builder.form.data }),
+  (data) => {
+    if (settingsSchema.value) 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(() =>
+  settingsSchema.value
+    ? settingsSchema.value.groups.filter((g) => builder.isSectionVisible(g.id))
+    : [],
 )
 
-const activeTab = ref(allTabs.value[0]?.id || 'appearance')
+const manualTabs = computed<SettingsTab[]>(() => props.tabs.map(normalizeItemInput))
+
+const allTabs = computed<SettingsTab[]>(() => {
+  const base: SettingsTab[] = settingsSchema.value
+    ? visibleSchemaGroups.value.map((g) => ({ id: g.id, label: g.label, icon: g.icon, description: g.description }))
+    : manualTabs.value
+  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 activeGroupVisibleFields = computed(() => {
+  if (!activeGroup.value) return []
+  return activeGroup.value.fields.filter((f) => builder.isFieldVisible(f.name))
+})
 
 const themeOptions: { value: ThemeMode; label: string }[] = [
   { value: 'light', label: 'Light' },
@@ -51,6 +248,14 @@ function handleClose() {
   emit('update:modelValue', false)
   emit('close')
 }
+
+function builderFieldNames(): string[] {
+  return builder.fields.map(field => field.name)
+}
+
+function isControlModelBinding(model: ControlModel | ControlModelBinding): model is ControlModelBinding {
+  return 'controls' in model && 'controlOptions' in model
+}
 </script>
 
 <template>
@@ -61,9 +266,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 +282,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="isSchemaDriven && 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)"
+                >
+                  <FormFieldRendererInternal
+                    :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="!isSchemaDriven">
+            <template v-for="tab in manualTabs" :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/TagsInput.vue

@@ -1,6 +1,8 @@
 <script setup lang="ts">
 /** Lets users type and add tags with autocomplete suggestions, categories, and a max-tag cap. */
 import { ref, computed } from 'vue'
+import { useSelectionLimit } from '../composables/useSelectionLimit'
+import { useDropdownState } from '../composables/useDropdownState'
 
 interface TagSuggestion {
   value: string
@@ -43,13 +45,23 @@ const emit = defineEmits<{
 
 const inputValue = ref('')
 const inputRef = ref<HTMLInputElement>()
-const dropdownOpen = ref(false)
 const highlightedIndex = ref(-1)
+const {
+  isOpen: dropdownOpen,
+  rootRef,
+  open: openDropdown,
+  close: closeDropdown,
+} = useDropdownState({
+  onClose: () => {
+    highlightedIndex.value = -1
+  },
+})
 
-const canAddMore = computed(() => {
-  if (props.maxTags === undefined) return true
-  return props.modelValue.length < props.maxTags
+const selectionLimit = useSelectionLimit({
+  count: () => props.modelValue.length,
+  max: () => props.maxTags,
 })
+const canAddMore = selectionLimit.canAddMore
 
 const normalizedSuggestions = computed<TagSuggestion[]>(() => {
   return props.suggestions.map(s => typeof s === 'string' ? { value: s } : s)
@@ -73,7 +85,7 @@ function categoryFor(tag: string): TagCategory | undefined {
 function addTag(value: string) {
   const trimmed = value.trim()
   if (!trimmed) return
-  if (!canAddMore.value) return
+  if (!selectionLimit.canAdd()) return
 
   // If a category is active and user didn't already type a prefix, prepend it
   let final = trimmed
@@ -85,8 +97,7 @@ function addTag(value: string) {
 
   emit('update:modelValue', [...props.modelValue, final])
   inputValue.value = ''
-  dropdownOpen.value = false
-  highlightedIndex.value = -1
+  closeDropdown()
 }
 
 function removeTag(index: number) {
@@ -100,7 +111,7 @@ function handleKeydown(event: KeyboardEvent) {
   if (event.key === 'ArrowDown' && filteredSuggestions.value.length) {
     event.preventDefault()
     highlightedIndex.value = Math.min(highlightedIndex.value + 1, filteredSuggestions.value.length - 1)
-    dropdownOpen.value = true
+    openDropdown()
     return
   }
   if (event.key === 'ArrowUp' && filteredSuggestions.value.length) {
@@ -118,8 +129,7 @@ function handleKeydown(event: KeyboardEvent) {
     return
   }
   if (event.key === 'Escape') {
-    dropdownOpen.value = false
-    highlightedIndex.value = -1
+    closeDropdown()
     return
   }
   if (event.key === 'Backspace' && !inputValue.value && props.modelValue.length > 0) {
@@ -128,13 +138,13 @@ function handleKeydown(event: KeyboardEvent) {
 }
 
 function handleFocus() {
-  if (filteredSuggestions.value.length) dropdownOpen.value = true
+  if (filteredSuggestions.value.length) openDropdown()
 }
 
 function handleBlur() {
   // Delay so a click on a suggestion fires first
   setTimeout(() => {
-    dropdownOpen.value = false
+    closeDropdown()
   }, 120)
 }
 
@@ -147,7 +157,7 @@ function handlePaste(event: ClipboardEvent) {
   const newTags = [...props.modelValue]
 
   for (const tag of tags) {
-    if (!canAddMore.value) break
+    if (!selectionLimit.canAdd(1, newTags.length)) break
     if (!props.allowDuplicates && newTags.includes(tag)) continue
     newTags.push(tag)
   }
@@ -164,13 +174,18 @@ function setCategory(prefix: string) {
 }
 
 function onInputEvent() {
-  dropdownOpen.value = filteredSuggestions.value.length > 0
+  if (filteredSuggestions.value.length > 0) {
+    openDropdown()
+  } else {
+    closeDropdown()
+  }
   highlightedIndex.value = -1
 }
 </script>
 
 <template>
   <div
+    ref="rootRef"
     :class="[
       'mint-tags-input',
       `mint-tags-input--${size}`,

package/src/components/ThemeToggle.vue

@@ -1,6 +1,7 @@
 <script setup lang="ts">
 /** Icon button that toggles between light and dark mode, swapping sun/moon icons to reflect the active theme. */
 import { useTheme } from '../composables/useTheme'
+import IconButton from './IconButton.vue'
 
 interface Props {
   size?: 'sm' | 'md' | 'lg'
@@ -14,16 +15,17 @@ const { isDark, toggleTheme } = useTheme()
 </script>
 
 <template>
-  <button
-    type="button"
-    :class="['mint-theme-toggle', `mint-theme-toggle--${size}`]"
-    :aria-label="isDark ? 'Switch to light mode' : 'Switch to dark mode'"
+  <IconButton
+    class="mint-theme-toggle"
+    variant="ghost"
+    :size="size"
+    :label="isDark ? 'Switch to light mode' : 'Switch to dark mode'"
     @click="toggleTheme"
   >
     <!-- Lucide sun -->
     <svg
       v-if="isDark"
-      :class="`mint-theme-toggle__icon--${size}`"
+      class="mint-theme-toggle__icon"
       viewBox="0 0 24 24"
       fill="none"
       stroke="currentColor"
@@ -36,7 +38,7 @@ const { isDark, toggleTheme } = useTheme()
     <!-- Lucide moon -->
     <svg
       v-else
-      :class="`mint-theme-toggle__icon--${size}`"
+      class="mint-theme-toggle__icon"
       viewBox="0 0 24 24"
       fill="none"
       stroke="currentColor"
@@ -46,7 +48,7 @@ const { isDark, toggleTheme } = useTheme()
     >
       <path d="M20.985 12.486a9 9 0 1 1-9.473-9.472c.405-.022.617.46.402.803a6 6 0 0 0 8.268 8.268c.344-.215.825-.004.803.401" />
     </svg>
-  </button>
+  </IconButton>
 </template>
 
 <style>