@morscherlab/mint-sdk 1.3.8 → 1.4.0-beta.1

package/src/components/StaleFormBanner.story.vue

@@ -0,0 +1,90 @@
+<script setup lang="ts">
+import { ref } from 'vue'
+import StaleFormBanner from './StaleFormBanner.vue'
+import BaseModal from './BaseModal.vue'
+import BaseButton from './BaseButton.vue'
+import BaseInput from './BaseInput.vue'
+
+const lastAction = ref('')
+const modalOpen = ref(true)
+const notes = ref('72 h exposure, n = 3 per dose. Plate 2 edge wells excluded.')
+const twelveSecondsAgo = () => new Date(Date.now() - 12_000).toISOString()
+
+function initPlayground() {
+  return {
+    actors: 'Alice Chen',
+    fields: 'Notes, Status',
+    reviewHref: '#',
+  }
+}
+
+function list(text: string): string[] {
+  return text.split(',').map(item => item.trim()).filter(Boolean)
+}
+</script>
+
+<template>
+  <Story title="Experiment/StaleFormBanner">
+    <Variant title="Playground" :init-state="initPlayground">
+      <template #default="{ state }">
+        <div style="padding: 2rem; max-width: 600px;">
+          <div style="border: 1px solid var(--border-color); border-radius: var(--radius-md); background: var(--bg-secondary); overflow: hidden;">
+            <StaleFormBanner
+              :change="{ actors: list(state.actors), fields: list(state.fields), at: twelveSecondsAgo() }"
+              :review-href="state.reviewHref"
+              entity-noun="this experiment"
+              @reload="lastAction = 'reload'"
+              @dismiss="lastAction = 'dismiss'"
+            />
+            <div style="padding: 1rem; font-size: 0.8125rem; color: var(--text-secondary);">Form fields</div>
+          </div>
+          <div v-if="lastAction" style="margin-top: 1rem; font-family: var(--font-mono); font-size: 0.75rem; color: var(--text-muted);">
+            Last event: <code>{{ lastAction }}</code>
+          </div>
+        </div>
+      </template>
+
+      <template #controls="{ state }">
+        <HstText v-model="state.actors" title="Writers (comma list)" />
+        <HstText v-model="state.fields" title="Changed fields (comma list)" />
+        <HstText v-model="state.reviewHref" title="Review link (empty: no Review)" />
+      </template>
+    </Variant>
+
+    <Variant title="In the Edit form" :init-state="() => ({})">
+      <div style="padding: 2rem; max-width: 600px;">
+        <BaseButton variant="secondary" @click="modalOpen = true">Edit experiment</BaseButton>
+        <BaseModal v-model:open="modalOpen" title="Edit experiment" size="lg">
+          <div style="margin: -1.125rem -1.25rem 1rem;">
+            <StaleFormBanner
+              :change="{ actors: ['Alice Chen'], fields: ['Notes', 'Status'], at: twelveSecondsAgo() }"
+              review-href="#"
+              @reload="modalOpen = false"
+              @dismiss="lastAction = 'dismiss'"
+            />
+          </div>
+          <label style="display: flex; flex-direction: column; gap: 0.3125rem; font-size: 0.75rem; color: var(--text-secondary);">
+            Notes
+            <BaseInput v-model="notes" type="textarea" :rows="3" />
+          </label>
+          <template #footer>
+            <BaseButton variant="secondary" size="sm" @click="modalOpen = false">Cancel</BaseButton>
+            <BaseButton variant="primary" size="sm">Save changes</BaseButton>
+          </template>
+        </BaseModal>
+      </div>
+    </Variant>
+  </Story>
+</template>
+
+<docs lang="md">
+## StaleFormBanner
+
+The strip at the top of a form when someone else saved the entity while the
+form holds unsaved edits (RFC #439). `useVersionedSave()` from
+`@morscherlab/mint-sdk/data` sets `stale` from the realtime stream; show the
+banner while it is set. Several writes merge into one banner. **Reload form**
+calls `reload()`, the close button calls `dismissStale()`, and **Review** opens
+`reviewHref` in a new tab. There is no Overwrite: a save on the older version
+gets `VersionConflictDialog`.
+</docs>

package/src/components/StaleFormBanner.vue

@@ -0,0 +1,83 @@
+<script setup lang="ts">
+/**
+ * The strip at the top of a form whose entity someone else changed while the
+ * form held unsaved edits (RFC #439). Show it while `useVersionedSave().stale`
+ * is set. It offers Reload and Review, not Overwrite: a save that would
+ * overwrite gets the 412 dialog.
+ */
+import { computed, onBeforeUnmount, ref } from 'vue'
+import { TriangleAlert, X } from 'lucide-vue-next'
+import type { StaleChange } from '../composables/useVersionedSave'
+
+interface Props {
+  change: StaleChange
+  /** The entity's page; Review opens it in a new tab. Without it, there is no Review. */
+  reviewHref?: string
+  /** What the form edits, for a write that names no fields. */
+  entityNoun?: string
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  reviewHref: '',
+  entityNoun: 'this record',
+})
+
+const emit = defineEmits<{
+  reload: []
+  dismiss: []
+}>()
+
+/** "A", "A and B", "A, B and C". */
+function list(items: readonly string[]): string {
+  if (items.length <= 1) return items[0] ?? ''
+  return `${items.slice(0, -1).join(', ')} and ${items[items.length - 1]}`
+}
+
+const summary = computed(() => {
+  const { actors, fields } = props.change
+  // Up to two named fields read as a list; more read as a count.
+  const what = fields.length === 0
+    ? props.entityNoun
+    : fields.length <= 2 ? list(fields) : `${fields.length} fields`
+  return `${list(actors)} changed ${what}`
+})
+
+const now = ref(Date.now())
+const timer = setInterval(() => { now.value = Date.now() }, 5_000)
+onBeforeUnmount(() => clearInterval(timer))
+
+const ago = computed(() => {
+  const seconds = Math.max(0, Math.round((now.value - Date.parse(props.change.at)) / 1000))
+  if (seconds < 60) return `${seconds} s ago`
+  const minutes = Math.round(seconds / 60)
+  if (minutes < 60) return `${minutes} min ago`
+  return `${Math.round(minutes / 60)} h ago`
+})
+</script>
+
+<template>
+  <div class="mint-stale-banner" role="status">
+    <TriangleAlert class="mint-stale-banner__icon" aria-hidden="true" />
+    <p class="mint-stale-banner__text">
+      <strong>{{ summary }}</strong>
+      {{ ' ' }}<time class="mint-stale-banner__time" :datetime="change.at">{{ ago }}</time>.
+      This form shows the older version.
+    </p>
+    <a
+      v-if="reviewHref"
+      class="mint-stale-banner__action"
+      :href="reviewHref"
+      target="_blank"
+      rel="noopener"
+    >Review</a>
+    <button type="button" class="mint-stale-banner__action" @click="emit('reload')">Reload form</button>
+    <button
+      type="button"
+      class="mint-stale-banner__dismiss"
+      aria-label="Dismiss until the next change"
+      @click="emit('dismiss')"
+    >
+      <X aria-hidden="true" />
+    </button>
+  </div>
+</template>

package/src/components/TagsInput.story.vue

@@ -27,7 +27,7 @@ function categorizedState() {
             v-model="state.tags"
             :placeholder="state.placeholder"
             :disabled="state.disabled"
-            :error="state.error"
+            :invalid="state.error"
             :size="state.size"
             :max-tags="state.useMaxTags ? state.maxTags : undefined"
             :allow-duplicates="state.allowDuplicates"
@@ -97,7 +97,7 @@ function categorizedState() {
       <div style="padding: 2rem; max-width: 500px; margin: 0 auto;">
         <TagsInput
           :model-value="['invalid-tag']"
-          error
+          invalid
           placeholder="Fix the tags..."
         />
       </div>
@@ -143,11 +143,11 @@ function categorizedState() {
             v-model:active-category="state.activeCategory"
             placeholder="Pick a category and type..."
             :categories="[
-              { name: 'role', prefix: 'role', color: 'primary' },
-              { name: 'status', prefix: 'status', color: 'success' },
-              { name: 'type', prefix: 'type', color: 'info' },
-              { name: 'qc', prefix: 'qc', color: 'warning' },
-              { name: 'ref', prefix: 'ref', color: 'neutral' },
+              { name: 'role', prefix: 'role', tone: 'primary' },
+              { name: 'status', prefix: 'status', tone: 'success' },
+              { name: 'type', prefix: 'type', tone: 'info' },
+              { name: 'qc', prefix: 'qc', tone: 'warning' },
+              { name: 'ref', prefix: 'ref', tone: 'neutral' },
             ]"
           />
           <p style="margin: 0; font-size: 0.75rem; color: var(--text-muted);">

package/src/components/TagsInput.vue

@@ -3,6 +3,7 @@
 import { ref, computed, useTemplateRef } from 'vue'
 import { useSelectionLimit } from '../composables/useSelectionLimit'
 import { useDropdownState } from '../composables/useDropdownState'
+import type { Tone } from '../types'
 
 interface TagSuggestion {
   value: string
@@ -12,14 +13,14 @@ interface TagSuggestion {
 interface TagCategory {
   name: string
   prefix: string
-  color?: 'primary' | 'success' | 'warning' | 'error' | 'info' | 'neutral'
+  tone?: Tone
 }
 
 interface Props {
   modelValue?: string[]
   placeholder?: string
   disabled?: boolean
-  error?: boolean
+  invalid?: boolean
   size?: 'sm' | 'md' | 'lg'
   maxTags?: number
   allowDuplicates?: boolean
@@ -31,7 +32,7 @@ interface Props {
 const props = withDefaults(defineProps<Props>(), {
   modelValue: () => [],
   disabled: false,
-  error: false,
+  invalid: false,
   size: 'md',
   allowDuplicates: false,
   suggestions: () => [],
@@ -201,7 +202,7 @@ function onInputEvent() {
     :class="[
       'mint-tags-input',
       `mint-tags-input--${size}`,
-      error ? 'mint-tags-input--error' : '',
+      invalid ? 'mint-tags-input--error' : '',
       disabled ? 'mint-tags-input--disabled' : '',
       categories.length ? 'mint-tags-input--categorized' : '',
     ]"
@@ -214,7 +215,7 @@ function onInputEvent() {
         type="button"
         :class="[
           'mint-tags-input__category',
-          `mint-tags-input__category--${cat.color ?? 'neutral'}`,
+          `mint-tags-input__category--${cat.tone ?? 'neutral'}`,
           activeCategory === cat.prefix ? 'mint-tags-input__category--active' : '',
         ]"
         :disabled="disabled"
@@ -232,7 +233,7 @@ function onInputEvent() {
         :class="[
           'mint-tags-input__tag',
           `mint-tags-input__tag--${size}`,
-          categoryFor(tag) ? `mint-tags-input__tag--${categoryFor(tag)?.color ?? 'neutral'}` : '',
+          categoryFor(tag) ? `mint-tags-input__tag--${categoryFor(tag)?.tone ?? 'neutral'}` : '',
         ]"
       >
         <span

package/src/components/ThemeToggle.vue

@@ -1,7 +1,8 @@
 <script setup lang="ts">
 /** Icon button that toggles between light and dark mode, swapping sun/moon icons to reflect the active theme. */
+import { Moon, Sun } from 'lucide-vue-next'
 import { useTheme } from '../composables/useTheme'
-import IconButton from './IconButton.vue'
+import BaseButton from './BaseButton.vue'
 
 interface Props {
   size?: 'sm' | 'md' | 'lg'
@@ -15,38 +16,12 @@ const { isDark, toggleTheme } = useTheme()
 </script>
 
 <template>
-  <IconButton
+  <BaseButton
     class="mint-theme-toggle"
     variant="ghost"
     :size="size"
+    :icon="isDark ? Sun : Moon"
     :label="isDark ? 'Switch to light mode' : 'Switch to dark mode'"
     @click="toggleTheme"
-  >
-    <!-- Lucide sun -->
-    <svg
-      v-if="isDark"
-      class="mint-theme-toggle__icon"
-      viewBox="0 0 24 24"
-      fill="none"
-      stroke="currentColor"
-      stroke-width="2"
-      stroke-linecap="round"
-      stroke-linejoin="round"
-    >
-      <circle cx="12" cy="12" r="4" /><path d="M12 2v2" /><path d="M12 20v2" /><path d="m4.93 4.93 1.41 1.41" /><path d="m17.66 17.66 1.41 1.41" /><path d="M2 12h2" /><path d="M20 12h2" /><path d="m6.34 17.66-1.41 1.41" /><path d="m19.07 4.93-1.41 1.41" />
-    </svg>
-    <!-- Lucide moon -->
-    <svg
-      v-else
-      class="mint-theme-toggle__icon"
-      viewBox="0 0 24 24"
-      fill="none"
-      stroke="currentColor"
-      stroke-width="2"
-      stroke-linecap="round"
-      stroke-linejoin="round"
-    >
-      <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>
-  </IconButton>
+  />
 </template>

package/src/components/TimeRangeInput.story.vue

@@ -42,7 +42,7 @@ function initState() {
           <TimeRangeInput
             v-model="state.modelValue"
             :disabled="state.disabled"
-            :error="state.error"
+            :invalid="state.error"
             :size="state.size"
             :step="state.step"
             :format="state.format"

package/src/components/TimeRangeInput.vue

@@ -2,13 +2,13 @@
 /** Paired start/end time pickers that validate range order (end must follow start) and display computed duration. */
 import { computed, watch } from 'vue'
 import type { TimeRange, TimeSlotDisabledFn } from '../types/components'
-import TimePicker from './TimePicker.vue'
-import { durationMinutes, compareTime } from '../composables/useTimeUtils'
+import DatePicker from './DatePicker.vue'
+import { durationMinutes, compareTime } from '../utils/time'
 
 interface Props {
   modelValue?: TimeRange
   disabled?: boolean
-  error?: boolean
+  invalid?: boolean
   size?: 'sm' | 'md' | 'lg'
   min?: string
   max?: string
@@ -22,7 +22,7 @@ interface Props {
 
 const props = withDefaults(defineProps<Props>(), {
   disabled: false,
-  error: false,
+  invalid: false,
   size: 'md',
   step: 15,
   format: '24h',
@@ -90,10 +90,11 @@ function onEndChange(value: string | undefined) {
 <template>
   <div class="mint-time-range">
     <div class="mint-time-range__start">
-      <TimePicker
+      <DatePicker
+        type="time"
         :model-value="startValue"
         :disabled="disabled"
-        :error="error || isInvalid"
+        :invalid="invalid || isInvalid"
         :size="size"
         :min="min"
         :max="max"
@@ -108,10 +109,11 @@ function onEndChange(value: string | undefined) {
     <span class="mint-time-range__separator" aria-hidden="true">–</span>
 
     <div class="mint-time-range__end">
-      <TimePicker
+      <DatePicker
+        type="time"
         :model-value="endValue"
         :disabled="disabled"
-        :error="error || isInvalid"
+        :invalid="invalid || isInvalid"
         :size="size"
         :min="endMin"
         :max="max"

package/src/components/VersionConflictDialog.story.vue

@@ -0,0 +1,60 @@
+<script setup lang="ts">
+import { ref } from 'vue'
+import VersionConflictDialog from './VersionConflictDialog.vue'
+import BaseButton from './BaseButton.vue'
+
+const lastAction = ref('')
+
+function initPlayground() {
+  return {
+    open: true,
+    entity: 'EXP-042 · Cisplatin dose response, HCT116',
+    changes: 'Notes, End date',
+    loading: false,
+  }
+}
+
+function changeList(text: string): string[] {
+  return text.split(',').map(item => item.trim()).filter(Boolean)
+}
+</script>
+
+<template>
+  <Story title="Experiment/VersionConflictDialog">
+    <Variant title="Playground" :init-state="initPlayground">
+      <template #default="{ state }">
+        <div style="padding: 2rem; max-width: 600px; display: flex; flex-direction: column; gap: 1rem;">
+          <BaseButton variant="secondary" @click="state.open = true">Save (412)</BaseButton>
+          <div v-if="lastAction" style="font-family: var(--font-mono); font-size: 0.75rem; color: var(--text-muted);">
+            Last event: <code>{{ lastAction }}</code>
+          </div>
+          <VersionConflictDialog
+            v-model:open="state.open"
+            :entity="state.entity"
+            :changes="changeList(state.changes)"
+            :loading="state.loading"
+            @reload="() => { state.open = false; lastAction = 'reload' }"
+            @overwrite="() => { state.open = false; lastAction = 'overwrite' }"
+          />
+        </div>
+      </template>
+
+      <template #controls="{ state }">
+        <HstCheckbox v-model="state.open" title="Open" />
+        <HstText v-model="state.entity" title="Entity line" />
+        <HstText v-model="state.changes" title="Changed fields (comma list)" />
+        <HstCheckbox v-model="state.loading" title="Overwrite saving" />
+      </template>
+    </Variant>
+  </Story>
+</template>
+
+<docs lang="md">
+## VersionConflictDialog
+
+The dialog for a save that the platform refused with `412 <entity>.version_conflict`
+(RFC #439). Pair it with `useVersionedSave()` from `@morscherlab/mint-sdk/data`:
+open it while `conflict` is set, call `reload()` on **Reload and discard mine**
+and `overwrite()` on **Overwrite**. Overwrite sends the form again with
+`If-Match` set to the version from the 412, so it replaces the newer version.
+</docs>

package/src/components/VersionConflictDialog.vue

@@ -0,0 +1,79 @@
+<script setup lang="ts">
+/**
+ * The dialog for a save refused with 412 `<entity>.version_conflict` (RFC #439).
+ * Show it while `useVersionedSave().conflict` is set: Reload discards the
+ * user's edits and refetches, Overwrite saves them on top of the newer version.
+ */
+import { computed } from 'vue'
+import { RefreshCw } from 'lucide-vue-next'
+import BaseModal from './BaseModal.vue'
+import BaseButton from './BaseButton.vue'
+
+interface Props {
+  open: boolean
+  /** The entity line under the title, such as `EXP-042 · Cisplatin dose response`. */
+  entity?: string
+  /** Labels of the fields the user changed and did not save. */
+  changes?: string[]
+  /** True while Overwrite saves. */
+  loading?: boolean
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  entity: '',
+  changes: () => [],
+  loading: false,
+})
+
+const emit = defineEmits<{
+  'update:open': [value: boolean]
+  reload: []
+  overwrite: []
+}>()
+
+const message = computed(() => {
+  const count = props.changes.length
+  if (count === 0) return 'Your changes are not saved. Pick what to keep.'
+  const [noun, verb] = count === 1 ? ['change', 'is'] : ['changes', 'are']
+  return `Your ${count} ${noun} (${props.changes.join(', ')}) ${verb} not saved. Pick what to keep.`
+})
+</script>
+
+<template>
+  <BaseModal
+    :open="open"
+    title="Changed by someone else"
+    :subtitle="entity || undefined"
+    size="md"
+    :closable="!loading"
+    :close-on-escape="!loading"
+    @update:open="emit('update:open', $event)"
+  >
+    <p class="mint-version-conflict__message">{{ message }}</p>
+
+    <template #footer>
+      <div class="mint-version-conflict__footer">
+        <BaseButton
+          type="button"
+          variant="secondary"
+          size="sm"
+          class="mint-version-conflict__overwrite"
+          :loading="loading"
+          @click="emit('overwrite')"
+        >
+          Overwrite
+        </BaseButton>
+        <BaseButton
+          type="button"
+          variant="primary"
+          size="sm"
+          :icon="RefreshCw"
+          :disabled="loading"
+          @click="emit('reload')"
+        >
+          Reload and discard mine
+        </BaseButton>
+      </div>
+    </template>
+  </BaseModal>
+</template>

package/src/components/WellPlate.geometry.ts

@@ -64,44 +64,6 @@ export function createPlateRowLabels(config: WellPlateConfig): string[] {
   return Array.from({ length: config.rows }, (_, index) => rowLabel(index))
 }
 
-function plateConfigOrThrow(format: number): WellPlateConfig {
-  const config = PLATE_CONFIGS[format as WellPlateFormat]
-  if (!config) throw new Error(`Unsupported plate format '${format}'.`)
-  return config
-}
-
-/** Every well id of a plate, row-major (A1, A2, … B1, …). */
-export function wellIdsForFormat(format: number): string[] {
-  const { rows, cols } = plateConfigOrThrow(format)
-  return Array.from({ length: rows }, (_, row) =>
-    Array.from({ length: cols }, (_col, col) => `${rowLabel(row)}${col + 1}`)
-  ).flat()
-}
-
-/** Throw unless `wellId` names a well that exists on a `format`-well plate. */
-export function assertWellInFormat(wellId: string, format: number): void {
-  const { rows, cols } = plateConfigOrThrow(format)
-  const match = /^([A-Z]+)([1-9][0-9]*)$/.exec(wellId.toUpperCase())
-  if (!match) {
-    throw new Error(`Invalid well id '${wellId}'.`)
-  }
-  const row = rowIndex(match[1])
-  const col = Number(match[2]) - 1
-  if (row < 0 || col < 0 || row >= rows || col >= cols) {
-    throw new Error(`Well '${wellId}' is outside a ${format}-well plate.`)
-  }
-}
-
-/** Coerce an unknown value to a supported plate format, else `fallback`. */
-export function readPlateFormat(value: unknown, fallback: WellPlateFormat): WellPlateFormat {
-  const parsed = typeof value === 'number'
-    ? value
-    : typeof value === 'string'
-      ? Number(value)
-      : Number.NaN
-  return parsed in PLATE_CONFIGS ? (parsed as WellPlateFormat) : fallback
-}
-
 export function createPlateColumnLabels(config: WellPlateConfig): number[] {
   return Array.from({ length: config.cols }, (_, index) => index + 1)
 }

package/src/components/WellPlate.rendering.ts

@@ -65,19 +65,6 @@ export function sampleTint(color: string): { backgroundColor: string; border: st
   }
 }
 
-let sampleTypeIndicatorWarned = false
-
-/** One dev-only warning per page for the no-op `showSampleTypeIndicator` prop. */
-export function warnSampleTypeIndicatorDeprecated(): void {
-  if (sampleTypeIndicatorWarned) return
-  if (typeof process !== 'undefined' && process.env?.NODE_ENV === 'production') return
-  sampleTypeIndicatorWarned = true
-  console.warn(
-    '[WellPlate] showSampleTypeIndicator is deprecated and renders nothing; it is removed in MINT 1.4. '
-    + 'The sample-type marker already shows shape per type and Q / i glyphs for QC / iQC.',
-  )
-}
-
 export function wellLabel(well: Well, showWellLabels: boolean): string | undefined {
   if (!showWellLabels) return undefined
   return well.metadata?.label as string | undefined