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

package/src/components/SettingsModal.vue

@@ -0,0 +1,399 @@
+<script setup lang="ts">
+/**
+ * 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).
+ *
+ * @example Recommended
+ * ```vue
+ * <SettingsModal v-model="open" v-model:values="values" :model="settingsModel" />
+ * ```
+ */
+import { ref, computed, watch } from 'vue'
+import BaseModal from './BaseModal.vue'
+import FormFieldRendererInternal from './internal/FormFieldRendererInternal.vue'
+import { useFormBuilder } from '../composables/useFormBuilder'
+import {
+  controlsToSettingsSchema,
+  mergeControlWorkspaceOptions,
+  resolveControlModel,
+  type ControlModel,
+  type ControlModelBinding,
+  type ControlSchema,
+  type ControlWorkspaceOptions,
+} from '../composables/useControlSchema'
+import { useSettingsStore, colorPalettes } from '../stores/settings'
+import { useAuthStore } from '../stores/auth'
+import { usePlatformContext } from '../composables/usePlatformContext'
+import { canAccessByPolicy } from '../permissions'
+import {
+  formSchemaFieldNames,
+  pickExistingRecordKeys,
+  pickRecordKeys,
+  recordValuesEqualForKeys,
+} from '../utils/formModelSync'
+import type {
+  ThemeMode,
+  ColorPalette,
+  TableDensity,
+  ModalLayout,
+  ModalTab,
+  SettingsTab,
+  SettingsTabInput,
+  SettingsModalLayout,
+  SettingsModalSchema,
+  SettingsUserType,
+  FormEnhancements,
+} from '../types'
+import type { AccessControlled, PermissionUser } from '../permissions'
+import {
+  APPEARANCE_TAB_ID,
+  buildFlatSettingsSchema,
+  buildSettingsTabs,
+  filterSettingsSchemaByAccess,
+  normalizeVisibleSettingsTabs,
+  settingsGroupToTab,
+} from './SettingsModal.schema'
+
+interface Props {
+  modelValue: boolean
+  title?: string
+  /** 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>>
+  /** Optional user type override for permission-filtered settings content. Defaults to SDK auth/platform context. */
+  userType?: SettingsUserType
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  title: 'Settings',
+  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 auth = useAuthStore()
+const { user: platformUser } = usePlatformContext()
+
+const isVertical = computed(() => props.layout === 'vertical')
+
+const resolvedModel = computed<ControlModelBinding | undefined>(() => {
+  return resolveControlModel(props.model)
+})
+const resolvedControls = computed<ControlSchema | undefined>(() =>
+  props.controls ?? resolvedModel.value?.controls,
+)
+const resolvedControlOptions = computed<ControlWorkspaceOptions>(() =>
+  mergeControlWorkspaceOptions(resolvedModel.value?.controlOptions ?? {}, props.controlOptions)
+)
+const sourceSettingsSchema = computed<SettingsModalSchema | undefined>(() =>
+  props.schema ?? (
+    resolvedControls.value
+      ? controlsToSettingsSchema(resolvedControls.value, resolvedControlOptions.value)
+      : undefined
+  ),
+)
+const currentAccessUser = computed<PermissionUser | null>(() => {
+  if (props.userType) {
+    return { role: props.userType === 'admin' ? 'admin' : 'user' }
+  }
+  return auth.userInfo ?? platformUser.value ?? null
+})
+const isAccessUserAuthenticated = computed(() =>
+  props.userType !== undefined || auth.isAuthenticated || !!platformUser.value,
+)
+const settingsSchema = computed<SettingsModalSchema | undefined>(() => {
+  if (!sourceSettingsSchema.value) return undefined
+  return filterSettingsSchemaByAccess(sourceSettingsSchema.value, canShowForCurrentUser)
+})
+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 ? buildFlatSettingsSchema(settingsSchema.value) : { sections: [] },
+  resolvedValues.value,
+  props.enhancements,
+)
+
+watch(
+  () => settingsSchema.value,
+  (schema) => {
+    if (!schema) {
+      builder.updateSchema({ sections: [] }, {})
+      return
+    }
+
+    const flatSchema = buildFlatSettingsSchema(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', {
+        ...resolvedValues.value,
+        ...data,
+      })
+    }
+  },
+  { 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 manualTabs = computed<SettingsTab[]>(() =>
+  normalizeVisibleSettingsTabs(props.tabs, canShowForCurrentUser)
+)
+
+const allTabs = computed<SettingsTab[]>(() => {
+  const base: SettingsTab[] = settingsSchema.value
+    ? visibleSchemaGroups.value.map(settingsGroupToTab)
+    : manualTabs.value
+  return buildSettingsTabs(base, props.showAppearance)
+})
+
+const activeTab = ref(allTabs.value[0]?.id || APPEARANCE_TAB_ID)
+
+// BaseModal owns the tab chrome: 'vertical' keeps its public name and maps to
+// the shell rail; horizontal maps to the shell strip (plain when single-tab).
+const baseLayout = computed<ModalLayout>(() => {
+  if (isVertical.value) return 'rail'
+  return allTabs.value.length > 1 ? 'tabs' : 'plain'
+})
+
+const modalTabs = computed<ModalTab[]>(() =>
+  allTabs.value.map((tab) => ({
+    id: tab.id,
+    label: tab.label,
+    icon: tab.icon,
+    description: tab.description,
+    meta: tab.meta,
+  })),
+)
+
+// 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' },
+  { value: 'dark', label: 'Dark' },
+  { value: 'system', label: 'System' },
+]
+
+const densityOptions: { value: TableDensity; label: string }[] = [
+  { value: 'compact', label: 'Compact' },
+  { value: 'normal', label: 'Normal' },
+  { value: 'comfortable', label: 'Comfortable' },
+]
+
+function handleClose() {
+  emit('update:modelValue', false)
+  emit('close')
+}
+
+function builderFieldNames(): string[] {
+  return builder.fields.map(field => field.name)
+}
+
+function canShowForCurrentUser(item: AccessControlled): boolean {
+  return canAccessByPolicy(
+    currentAccessUser.value,
+    item,
+    isAccessUserAuthenticated.value,
+  )
+}
+</script>
+
+<template>
+  <BaseModal
+    :model-value="modelValue"
+    :title="title"
+    :size="size"
+    :layout="baseLayout"
+    :tabs="modalTabs"
+    :active-tab="activeTab"
+    @update:active-tab="activeTab = $event"
+    @update:model-value="emit('update:modelValue', $event)"
+    @close="handleClose"
+  >
+    <!-- Body: the active pane only — tab strip / rail / footer are BaseModal's shell. -->
+    <div class="mint-settings-modal">
+      <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 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 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 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>
+
+        <slot name="appearance" />
+      </div>
+    </div>
+
+    <template v-if="$slots.footer" #footer>
+      <slot
+        name="footer"
+        :values="builder.form.data"
+        :close="handleClose"
+      />
+    </template>
+  </BaseModal>
+</template>
+
+<style>
+@import '../styles/components/settings-modal.css';
+</style>

package/src/components/Skeleton.story.vue

@@ -0,0 +1,141 @@
+<script setup lang="ts">
+import Skeleton from './Skeleton.vue'
+
+const variants: ('text' | 'circular' | 'rectangular' | 'rounded')[] = ['text', 'circular', 'rectangular', 'rounded']
+const animations: ('pulse' | 'wave' | 'none')[] = ['pulse', 'wave', 'none']
+</script>
+
+<template>
+  <Story title="Data Display/Skeleton">
+    <Variant title="Playground">
+      <template #default="{ state }">
+        <div style="padding: 2rem; max-width: 400px; margin: 0 auto;">
+          <Skeleton
+            :variant="state.variant"
+            :animation="state.animation"
+            :width="state.width || undefined"
+            :height="state.height || undefined"
+          />
+        </div>
+      </template>
+
+      <template #controls="{ state }">
+        <HstSelect
+          v-model="state.variant"
+          title="Variant"
+          :options="variants.map(v => ({ label: v, value: v }))"
+        />
+        <HstSelect
+          v-model="state.animation"
+          title="Animation"
+          :options="animations.map(a => ({ label: a, value: a }))"
+        />
+        <HstText v-model="state.width" title="Width (e.g. 200px, 50%)" />
+        <HstText v-model="state.height" title="Height (e.g. 40px)" />
+      </template>
+    </Variant>
+
+    <Variant title="All Variants">
+      <div style="padding: 2rem; max-width: 400px; margin: 0 auto; display: flex; flex-direction: column; gap: 1.5rem;">
+        <div v-for="variant in variants" :key="variant">
+          <p style="margin: 0 0 0.5rem; font-size: 0.75rem; color: var(--text-muted, #94a3b8); text-transform: uppercase; letter-spacing: 0.05em;">
+            {{ variant }}
+          </p>
+          <Skeleton :variant="variant" />
+        </div>
+      </div>
+    </Variant>
+
+    <Variant title="Animation Types">
+      <div style="padding: 2rem; max-width: 400px; margin: 0 auto; display: flex; flex-direction: column; gap: 1.5rem;">
+        <div v-for="animation in animations" :key="animation">
+          <p style="margin: 0 0 0.5rem; font-size: 0.75rem; color: var(--text-muted, #94a3b8); text-transform: uppercase; letter-spacing: 0.05em;">
+            {{ animation }}
+          </p>
+          <Skeleton variant="text" :animation="animation" />
+        </div>
+      </div>
+    </Variant>
+
+    <Variant title="Card Loading Pattern">
+      <div style="padding: 2rem; max-width: 400px; margin: 0 auto;">
+        <div style="border: 1px solid var(--border-color, #e2e8f0); border-radius: 0.5rem; padding: 1.5rem; display: flex; flex-direction: column; gap: 1rem;">
+          <div style="display: flex; align-items: center; gap: 0.75rem;">
+            <Skeleton variant="circular" width="48" height="48" />
+            <div style="flex: 1; display: flex; flex-direction: column; gap: 0.5rem;">
+              <Skeleton variant="text" width="60%" />
+              <Skeleton variant="text" width="40%" />
+            </div>
+          </div>
+          <Skeleton variant="rounded" height="160" />
+          <div style="display: flex; flex-direction: column; gap: 0.5rem;">
+            <Skeleton variant="text" />
+            <Skeleton variant="text" />
+            <Skeleton variant="text" width="75%" />
+          </div>
+        </div>
+      </div>
+    </Variant>
+
+    <Variant title="Table Loading Pattern">
+      <div style="padding: 2rem; max-width: 600px; margin: 0 auto;">
+        <div style="display: flex; flex-direction: column; gap: 0.75rem;">
+          <div style="display: flex; gap: 1rem; padding-bottom: 0.75rem; border-bottom: 1px solid var(--border-color, #e2e8f0);">
+            <Skeleton variant="text" width="60px" height="14" />
+            <Skeleton variant="text" width="120px" height="14" />
+            <Skeleton variant="text" width="80px" height="14" />
+            <Skeleton variant="text" width="100px" height="14" />
+          </div>
+          <div v-for="i in 5" :key="i" style="display: flex; gap: 1rem;">
+            <Skeleton variant="text" width="60px" />
+            <Skeleton variant="text" width="120px" />
+            <Skeleton variant="text" width="80px" />
+            <Skeleton variant="text" width="100px" />
+          </div>
+        </div>
+      </div>
+    </Variant>
+
+    <Variant title="Custom Sizes">
+      <div style="padding: 2rem; display: flex; gap: 1.5rem; align-items: flex-start; justify-content: center; flex-wrap: wrap;">
+        <div style="display: flex; flex-direction: column; align-items: center; gap: 0.5rem;">
+          <Skeleton variant="circular" width="32" height="32" />
+          <span style="font-size: 0.75rem; color: var(--text-muted, #94a3b8);">32px</span>
+        </div>
+        <div style="display: flex; flex-direction: column; align-items: center; gap: 0.5rem;">
+          <Skeleton variant="circular" width="48" height="48" />
+          <span style="font-size: 0.75rem; color: var(--text-muted, #94a3b8);">48px</span>
+        </div>
+        <div style="display: flex; flex-direction: column; align-items: center; gap: 0.5rem;">
+          <Skeleton variant="circular" width="64" height="64" />
+          <span style="font-size: 0.75rem; color: var(--text-muted, #94a3b8);">64px</span>
+        </div>
+        <div style="display: flex; flex-direction: column; align-items: center; gap: 0.5rem;">
+          <Skeleton variant="circular" width="96" height="96" />
+          <span style="font-size: 0.75rem; color: var(--text-muted, #94a3b8);">96px</span>
+        </div>
+      </div>
+    </Variant>
+    <Variant title="Atom classes — quick loading layouts">
+      <div style="padding: 2rem; max-width: 480px;">
+        <div style="display: flex; flex-direction: column; gap: 0.875rem; padding: 1rem; border: 1px solid var(--border-color); border-radius: var(--radius-md); background: var(--bg-card);">
+          <div style="display: flex; align-items: center; gap: 0.75rem;">
+            <div class="sk--avatar" />
+            <div style="flex: 1; display: flex; flex-direction: column; gap: 0.5rem;">
+              <div class="sk--title" />
+              <div class="sk--line-sm" style="width: 80%;" />
+            </div>
+          </div>
+          <div class="sk--line" />
+          <div class="sk--line" style="width: 90%;" />
+          <div class="sk--line" style="width: 70%;" />
+          <div style="display: flex; gap: 0.5rem; margin-top: 0.25rem;">
+            <div class="sk--pill" />
+            <div class="sk--pill" />
+            <div class="sk--btn" style="margin-left: auto;" />
+          </div>
+        </div>
+      </div>
+    </Variant>
+  </Story>
+</template>

package/src/components/Skeleton.vue

@@ -0,0 +1,74 @@
+<script setup lang="ts">
+/** Animated loading placeholder in text, circular, rectangular, or rounded variants with pulse or wave animation. */
+import { computed } from 'vue'
+
+interface Props {
+  variant?: 'text' | 'circular' | 'rectangular' | 'rounded'
+  width?: string | number
+  height?: string | number
+  animation?: 'pulse' | 'wave' | 'none'
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  variant: 'text',
+  animation: 'wave',
+})
+
+const style = computed(() => {
+  const s: Record<string, string> = {}
+
+  if (props.width) {
+    s.width = typeof props.width === 'number' ? `${props.width}px` : props.width
+  }
+
+  if (props.height) {
+    s.height = typeof props.height === 'number' ? `${props.height}px` : props.height
+  }
+
+  return s
+})
+
+const classes = computed(() => {
+  const base = ['bg-bg-hover']
+
+  switch (props.variant) {
+    case 'circular':
+      base.push('rounded-full')
+      if (!props.width && !props.height) {
+        base.push('w-10 h-10')
+      }
+      break
+    case 'rectangular':
+      base.push('rounded-none')
+      if (!props.height) base.push('h-24')
+      break
+    case 'rounded':
+      base.push('rounded-mint')
+      if (!props.height) base.push('h-24')
+      break
+    default:
+      base.push('rounded')
+      if (!props.height) base.push('h-4')
+      if (!props.width) base.push('w-full')
+  }
+
+  switch (props.animation) {
+    case 'pulse':
+      base.push('animate-pulse')
+      break
+    case 'wave':
+      base.push('skeleton-wave')
+      break
+  }
+
+  return base
+})
+</script>
+
+<template>
+  <div :class="classes" :style="style" />
+</template>
+
+<style>
+@import '../styles/components/skeleton.css';
+</style>