@morscherlab/mint-sdk 1.2.0-beta.1 → 1.2.0-beta.10

package/src/components/SampleHierarchyTree.vue

@@ -3,6 +3,11 @@
 import { h, Transition, type VNode } from 'vue'
 import type { TreeNodeType, BadgeVariant, TreeNode } from '../types'
 import { useExpansionSet } from '../composables/useExpansionSet'
+import DataStateInternal from './internal/DataStateInternal.vue'
+
+/** Folder glyph kept from the pre-1.2 hand-rolled empty state. */
+const EMPTY_ICON_PATH
+  = 'M20 20a2 2 0 0 0 2-2V8a2 2 0 0 0-2-2h-7.9a2 2 0 0 1-1.69-.9L9.6 3.9A2 2 0 0 0 7.93 3H4a2 2 0 0 0-2 2v13a2 2 0 0 0 2 2Z'
 
 interface Props {
   nodes: TreeNode[]
@@ -12,6 +17,13 @@ interface Props {
   showCounts?: boolean
   maxDepth?: number
   size?: 'sm' | 'md' | 'lg'
+  /** Replace the tree with a loading placeholder. */
+  loading?: boolean
+  /**
+   * Error message. When set, the tree is replaced by an error state.
+   * `null`/`undefined` renders normally.
+   */
+  error?: string | null
 }
 
 const props = withDefaults(defineProps<Props>(), {
@@ -20,6 +32,8 @@ const props = withDefaults(defineProps<Props>(), {
   showIcons: true,
   showCounts: true,
   size: 'md',
+  loading: false,
+  error: null,
 })
 
 const emit = defineEmits<{
@@ -226,12 +240,25 @@ function renderTree(): VNode[] {
 
 <template>
   <div :class="['mint-sample-tree', `mint-sample-tree--${size}`]" role="tree">
+    <!-- Error state -->
+    <div v-if="error" class="mint-sample-tree__state">
+      <slot name="error" :error="error">
+        <DataStateInternal state="error" size="sm" :title="error" />
+      </slot>
+    </div>
+
+    <!-- Loading state -->
+    <div v-else-if="loading" class="mint-sample-tree__state">
+      <slot name="loading">
+        <DataStateInternal state="loading" size="sm" loading-label="Loading samples" />
+      </slot>
+    </div>
+
     <!-- Empty state -->
-    <div v-if="nodes.length === 0" class="mint-sample-tree__empty">
-      <svg class="mint-sample-tree__empty-icon" fill="none" stroke="currentColor" viewBox="0 0 24 24" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
-        <path d="M20 20a2 2 0 0 0 2-2V8a2 2 0 0 0-2-2h-7.9a2 2 0 0 1-1.69-.9L9.6 3.9A2 2 0 0 0 7.93 3H4a2 2 0 0 0-2 2v13a2 2 0 0 0 2 2Z" />
-      </svg>
-      <p class="mint-sample-tree__empty-text">No items</p>
+    <div v-else-if="nodes.length === 0" class="mint-sample-tree__state">
+      <slot name="empty">
+        <DataStateInternal state="empty" size="sm" title="No items" :icon-path="EMPTY_ICON_PATH" />
+      </slot>
     </div>
 
     <!-- Tree nodes rendered via render function -->
@@ -240,7 +267,3 @@ function renderTree(): VNode[] {
     </template>
   </div>
 </template>
-
-<style>
-@import '../styles/components/sample-hierarchy-tree.css';
-</style>

package/src/components/SampleLegend.vue

@@ -1,6 +1,7 @@
 <script setup lang="ts">
 /** Clickable color-swatch legend for plate sample types, supporting selection, count display, add/remove, and custom color assignment. */
 import type { SampleType } from '../types'
+import { SAMPLE_COLOR_SCALE } from '../utils/color'
 
 interface Props {
   modelValue?: string
@@ -17,10 +18,7 @@ const props = withDefaults(defineProps<Props>(), {
   samples: () => [],
   showCounts: true,
   editable: false,
-  colorPalette: () => [
-    '#3B82F6', '#10B981', '#EF4444', '#F59E0B', '#8B5CF6',
-    '#F97316', '#06B6D4', '#14B8A6', '#6B7280',
-  ],
+  colorPalette: () => [...SAMPLE_COLOR_SCALE],
   size: 'md',
   orientation: 'vertical',
 })
@@ -113,7 +111,3 @@ function handleAdd() {
     </button>
   </div>
 </template>
-
-<style>
-@import '../styles/components/sample-legend.css';
-</style>

package/src/components/SampleSelector.drag.ts

@@ -1,5 +1,7 @@
 import { ref } from 'vue'
 import type { SampleGroup } from '../types'
+import { useReorderAnnouncer } from '../composables/useListReorder'
+import { getSampleGroupMajorPrefix } from '../utils/sampleGroupPath'
 import {
   detectSampleGroupSeparator,
   getSampleGroupParentPath,
@@ -23,6 +25,7 @@ export function useSampleSelectorDrag(groups: MutableSampleGroups) {
   const draggingGroupKind = ref<GroupDragKind | null>(null)
   const reorderTarget = ref<string | null>(null)
   const reorderPosition = ref<GroupReorderPosition | null>(null)
+  const { announcement, announce, announcerStyle } = useReorderAnnouncer()
 
   function handleDragStart(sample: string, sourceGroup: string | null, event: DragEvent) {
     draggingSample.value = sample
@@ -143,7 +146,45 @@ export function useSampleSelectorDrag(groups: MutableSampleGroups) {
     handleGroupDragEnd()
   }
 
+  /**
+   * Keyboard alternative to the group reorder drag. The hierarchy constrains a
+   * move to the dragged node's siblings (a leaf may not cross a parent), so this
+   * is not a flat list reorder and does not use `useListReorder`: Alt+ArrowUp /
+   * Alt+ArrowDown swap the node with its previous / next sibling instead.
+   */
+  function handleGroupReorderKeydown(name: string, kind: GroupDragKind, event: KeyboardEvent) {
+    if (!event.altKey) return
+    const direction = event.key === 'ArrowUp' ? -1 : event.key === 'ArrowDown' ? 1 : 0
+    if (direction === 0) return
+
+    event.preventDefault()
+    const separator = detectSampleGroupSeparator(groups.value)
+    const siblings = kind === 'major'
+      ? uniqueMajorPrefixes(groups.value, separator)
+      : groups.value
+        .filter(group =>
+          getSampleGroupParentPath(group.name, separator) ===
+          getSampleGroupParentPath(name, separator))
+        .map(group => group.name)
+
+    const currentIndex = siblings.indexOf(name)
+    const target = siblings[currentIndex + direction]
+    if (currentIndex === -1 || target === undefined) return
+
+    const position: GroupReorderPosition = direction === -1 ? 'before' : 'after'
+    const nextGroups = kind === 'major'
+      ? reorderSampleMajorGroup(groups.value, name, target, position)
+      : reorderSampleGroup(groups.value, name, target, position)
+
+    if (nextGroups === groups.value) return
+    groups.value = nextGroups
+    announce(`${name} moved ${direction === -1 ? 'up' : 'down'} to position ${currentIndex + direction + 1} of ${siblings.length}.`)
+  }
+
   return {
+    announcement,
+    announcerStyle,
+    handleGroupReorderKeydown,
     draggingSample,
     dragOverGroup,
     draggingGroup,
@@ -162,3 +203,13 @@ export function useSampleSelectorDrag(groups: MutableSampleGroups) {
     handleGroupDrop,
   }
 }
+
+/** Major-group prefixes in tree order, de-duplicated. */
+function uniqueMajorPrefixes(groups: SampleGroup[], separator: string): string[] {
+  const seen: string[] = []
+  for (const group of groups) {
+    const prefix = getSampleGroupMajorPrefix(group.name, separator)
+    if (!seen.includes(prefix)) seen.push(prefix)
+  }
+  return seen
+}

package/src/components/SampleSelector.story.vue

@@ -72,6 +72,8 @@ const lcmsSamples = ['Liver', 'Kidney'].flatMap(tissue =>
 
 function initState() {
   return {
+    loading: false,
+    error: '',
     samples: mockSamples,
     selected: [] as string[],
     groups: [] as SampleGroup[],
@@ -100,6 +102,8 @@ function handleSmartGroup(result: AutoGroupResult, state: { groups: SampleGroup[
       <template #default="{ state }">
         <div style="padding: 2rem; max-width: 400px;">
           <SampleSelector
+            :loading="state.loading"
+            :error="state.error || null"
             v-model="state.selected"
             v-model:groups="state.groups"
             :samples="state.samples"
@@ -110,6 +114,8 @@ function handleSmartGroup(result: AutoGroupResult, state: { groups: SampleGroup[
         </div>
       </template>
       <template #controls="{ state }">
+        <HstCheckbox v-model="state.loading" title="Loading" />
+        <HstText v-model="state.error" title="Error Message" />
         <HstCheckbox v-model="state.enableGrouping" title="Enable Grouping" />
         <HstCheckbox v-model="state.enableSmartGroup" title="Enable Smart" />
       </template>

package/src/components/SampleSelector.tree.ts

@@ -34,6 +34,8 @@ export interface SampleGroupTreeContext {
   onGroupDragOver: (name: string, kind: GroupDragKind, event: DragEvent) => void
   onGroupDragLeave: (event: DragEvent) => void
   onGroupDrop: (name: string, kind: GroupDragKind, event: DragEvent) => void
+  /** Alt+ArrowUp / Alt+ArrowDown reorder a group among its siblings. */
+  onGroupReorderKeydown: (name: string, kind: GroupDragKind, event: KeyboardEvent) => void
 }
 
 /** Every concrete group name beneath a node, in tree order. */

package/src/components/SampleSelector.vue

@@ -25,6 +25,7 @@ import {
   removeSampleFromGroup as removeSampleFromSampleGroup,
   removeSampleGroups,
 } from './SampleSelector.groups'
+import DataStateInternal from './internal/DataStateInternal.vue'
 
 interface Props {
   samples?: string[]
@@ -35,6 +36,15 @@ interface Props {
   experimentId?: number
   designData?: Record<string, unknown>
   autoloadExperimentData?: boolean
+  /** Replace the selector body with a loading placeholder. */
+  loading?: boolean
+  /**
+   * Error message. When set, the selector body is replaced by an error state.
+   * `null`/`undefined` renders normally.
+   */
+  error?: string | null
+  /** Empty-state headline shown when there are no samples to select from. */
+  emptyMessage?: string
 }
 
 const props = withDefaults(defineProps<Props>(), {
@@ -45,6 +55,9 @@ const props = withDefaults(defineProps<Props>(), {
   experimentId: undefined,
   designData: undefined,
   autoloadExperimentData: true,
+  loading: false,
+  error: null,
+  emptyMessage: 'No samples available',
 })
 
 const emit = defineEmits<{
@@ -69,6 +82,8 @@ const internalGroups = computed({
 })
 
 const {
+  announcement: reorderAnnouncement,
+  announcerStyle,
   draggingSample,
   dragOverGroup,
   draggingGroup,
@@ -81,6 +96,7 @@ const {
   handleDragLeave,
   handleDrop,
   handleGroupDragStart,
+  handleGroupReorderKeydown,
   handleGroupDragEnd,
   handleGroupDragOver,
   handleGroupDragLeave,
@@ -227,6 +243,7 @@ const treeContext = computed<SampleGroupTreeContext>(() => ({
   onGroupDragOver: handleGroupDragOver,
   onGroupDragLeave: handleGroupDragLeave,
   onGroupDrop: handleGroupDrop,
+  onGroupReorderKeydown: handleGroupReorderKeydown,
 }))
 
 // New group
@@ -237,13 +254,36 @@ function addNewGroup() {
   newGroupName.value = ''
 }
 
+/** True while a loading, error or empty placeholder stands in for the body. */
+const isPlaceholderState = computed(() =>
+  props.loading || Boolean(props.error) || resolvedSamples.value.length === 0,
+)
+
 defineExpose({ handleSmartGroupApply })
 </script>
 
 <template>
   <div class="mint-sample-selector">
+    <div v-if="error" class="mint-sample-selector__state">
+      <slot name="error" :error="error">
+        <DataStateInternal state="error" size="sm" :title="error" />
+      </slot>
+    </div>
+
+    <div v-else-if="loading" class="mint-sample-selector__state">
+      <slot name="loading">
+        <DataStateInternal state="loading" size="sm" loading-label="Loading samples" />
+      </slot>
+    </div>
+
+    <div v-else-if="resolvedSamples.length === 0" class="mint-sample-selector__state">
+      <slot name="empty">
+        <DataStateInternal state="empty" size="sm" :title="emptyMessage" />
+      </slot>
+    </div>
+
     <!-- Select All Row -->
-    <label class="mint-sample-selector__select-all">
+    <label v-if="!isPlaceholderState" class="mint-sample-selector__select-all">
       <input
         type="checkbox"
         :checked="isAllSelected"
@@ -255,7 +295,7 @@ defineExpose({ handleSmartGroupApply })
     </label>
 
     <!-- Action Buttons Row -->
-    <div v-if="enableGrouping" class="mint-sample-selector__actions">
+    <div v-if="!isPlaceholderState && enableGrouping" class="mint-sample-selector__actions">
       <div class="mint-sample-selector__actions-row">
         <!-- Grouping Button -->
         <BaseButton
@@ -291,7 +331,7 @@ defineExpose({ handleSmartGroupApply })
     </div>
 
     <!-- Grouped View -->
-    <div v-if="groupingEnabled" class="mint-sample-selector__grouped">
+    <div v-if="!isPlaceholderState && groupingEnabled" class="mint-sample-selector__grouped">
       <!-- Groups Header -->
       <div class="mint-sample-selector__groups-header">
         <span class="mint-sample-selector__groups-title">Groups ({{ internalGroups.length }})</span>
@@ -320,7 +360,7 @@ defineExpose({ handleSmartGroupApply })
         />
 
         <!-- Empty state -->
-        <div v-if="internalGroups.length === 0" class="mint-sample-selector__empty">
+        <div v-if="internalGroups.length === 0" class="mint-sample-selector__hint">
           Click Smart to auto-group samples
         </div>
       </div>
@@ -394,7 +434,7 @@ defineExpose({ handleSmartGroupApply })
     </div>
 
     <!-- Flat View (when no groups) -->
-    <div v-if="!groupingEnabled" class="mint-sample-selector__flat">
+    <div v-if="!isPlaceholderState && !groupingEnabled" class="mint-sample-selector__flat">
       <!-- Search -->
       <div class="mint-sample-selector__search">
         <svg class="mint-sample-selector__search-icon" fill="none" stroke="currentColor" viewBox="0 0 24 24">
@@ -427,7 +467,7 @@ defineExpose({ handleSmartGroupApply })
           <span class="mint-sample-selector__flat-name">{{ sample }}</span>
         </div>
 
-        <div v-if="filteredSamples.length === 0 && searchQuery.trim()" class="mint-sample-selector__empty">
+        <div v-if="filteredSamples.length === 0 && searchQuery.trim()" class="mint-sample-selector__hint">
           No samples match "{{ searchQuery }}"
         </div>
       </div>
@@ -443,9 +483,8 @@ defineExpose({ handleSmartGroupApply })
       :design-data="resolvedDesignData"
       @apply="handleSmartGroupApply"
     />
+
+    <!-- Group reorder announcements for screen readers -->
+    <div role="status" aria-live="polite" :style="announcerStyle">{{ reorderAnnouncement }}</div>
   </div>
 </template>
-
-<style>
-@import '../styles/components/sample-selector.css';
-</style>

package/src/components/SampleSelectorGroupNode.vue

@@ -54,6 +54,18 @@ function onHeaderDrop(event: DragEvent) {
   if (dragKind.value === null) return
   props.ctx.onGroupDrop(dragName.value, dragKind.value, event)
 }
+
+/** Enter/Space expand the node; Alt+ArrowUp/Down reorder it among its siblings. */
+function onHeaderKeydown(event: KeyboardEvent) {
+  if (event.altKey) {
+    if (dragKind.value === null) return
+    props.ctx.onGroupReorderKeydown(dragName.value, dragKind.value, event)
+    return
+  }
+  if (event.key !== 'Enter' && event.key !== ' ') return
+  event.preventDefault()
+  props.ctx.toggleExpanded(props.node.key)
+}
 </script>
 
 <template>
@@ -81,7 +93,14 @@ function onHeaderDrop(event: DragEvent) {
         reorderEdge === 'after' ? 'mint-sample-selector__header--drag-over-after' : '',
       ]"
       :draggable="dragKind !== null"
+      role="button"
+      tabindex="0"
+      :aria-expanded="expanded"
+      :aria-label="dragKind !== null
+        ? `${node.label}. Press Alt with the up or down arrow keys to reorder.`
+        : node.label"
       @click="ctx.toggleExpanded(node.key)"
+      @keydown="onHeaderKeydown"
       @dragstart="onHeaderDragStart"
       @dragend="ctx.onGroupDragEnd"
       @dragover="onHeaderDragOver"

package/src/components/ScheduleCalendar.story.vue

@@ -86,6 +86,8 @@ const mockBlockedSlots: ScheduleBlockedSlot[] = [
 
 function initState() {
   return {
+    loading: false,
+    error: '',
     modelValue: today,
     view: 'week' as const,
     events: mockEvents,
@@ -106,6 +108,8 @@ function initState() {
       <template #default="{ state }">
         <div style="padding: 1rem; height: 700px;">
           <ScheduleCalendar
+            :loading="state.loading"
+            :error="state.error || null"
             v-model="state.modelValue"
             :view="state.view"
             :events="state.events"
@@ -123,6 +127,8 @@ function initState() {
         </div>
       </template>
       <template #controls="{ state }">
+        <HstCheckbox v-model="state.loading" title="Loading" />
+        <HstText v-model="state.error" title="Error Message" />
         <HstSelect
           v-model="state.view"
           title="View"

package/src/components/ScheduleCalendar.vue

@@ -7,11 +7,13 @@ import type {
   ScheduleBlockedSlot,
 } from '../types/components'
 import { useScheduleDrag } from '../composables/useScheduleDrag'
+import { useReorderAnnouncer } from '../composables/useListReorder'
 import {
   SCHEDULE_SLOT_HEIGHT,
   parseScheduleModelDate,
   useScheduleCalendarLayout,
 } from '../composables/useScheduleCalendarLayout'
+import DataStateInternal from './internal/DataStateInternal.vue'
 
 interface Props {
   modelValue?: Date | string
@@ -28,6 +30,19 @@ interface Props {
   showNavigation?: boolean
   statusColors?: Record<string, string>
   locale?: string
+  /** Replace the calendar grid with a loading placeholder. */
+  loading?: boolean
+  /**
+   * Error message. When set, the calendar grid is replaced by an error state.
+   * `null`/`undefined` renders normally.
+   */
+  error?: string | null
+  /**
+   * Opt-in empty-state headline. An empty grid is meaningful on a calendar, so
+   * the empty state only replaces it when this message is supplied and there
+   * are no events.
+   */
+  emptyMessage?: string
 }
 
 const props = withDefaults(defineProps<Props>(), {
@@ -43,6 +58,8 @@ const props = withDefaults(defineProps<Props>(), {
   showViewToggle: true,
   showNavigation: true,
   locale: 'en-US',
+  loading: false,
+  error: null,
 })
 
 const emit = defineEmits<{
@@ -57,6 +74,11 @@ const emit = defineEmits<{
 
 const SLOT_HEIGHT = SCHEDULE_SLOT_HEIGHT
 const currentView = ref<ScheduleView>(props.view)
+
+/** Empty state is opt-in: it needs an `emptyMessage` and an event-free range. */
+const showEmptyState = computed(() =>
+  Boolean(props.emptyMessage) && props.events.length === 0,
+)
 const currentDate = ref<Date>(parseScheduleModelDate(props.modelValue))
 const nowTimer = ref<ReturnType<typeof setInterval>>()
 const now = ref(new Date())
@@ -76,7 +98,9 @@ const weekStartsOnRef = computed(() => props.weekStartsOn)
 const localeRef = computed(() => props.locale)
 const showNowIndicatorRef = computed(() => props.showNowIndicator)
 
-const { isDragging, ghost, startCreate, startMove, startResize } = useScheduleDrag({
+const { announcement, announce, announcerStyle } = useReorderAnnouncer()
+
+const { isDragging, ghost, startCreate, startMove, startResize, nudgeEvent } = useScheduleDrag({
   slotDuration: slotDurationRef,
   dayStartHour: dayStartRef,
   dayEndHour: dayEndRef,
@@ -180,6 +204,35 @@ function onResizePointerDown(event: ScheduleEvent, edge: 'top' | 'bottom', dayIn
   startResize(event, edge, e.clientY, dayIndex)
 }
 
+/**
+ * Keyboard alternative to dragging an event: Alt+ArrowUp/Down move it by one
+ * slot, Shift+Alt+ArrowUp/Down shorten or lengthen it, Enter/Space open it.
+ */
+function onEventKeydown(event: ScheduleEvent, e: KeyboardEvent) {
+  if (e.key === 'Enter' || e.key === ' ') {
+    e.preventDefault()
+    emit('event-click', event)
+    return
+  }
+  if (!e.altKey) return
+  const direction = e.key === 'ArrowUp' ? -1 : e.key === 'ArrowDown' ? 1 : 0
+  if (direction === 0) return
+
+  e.preventDefault()
+  const mode = e.shiftKey ? 'resize' : 'move'
+  const applied = nudgeEvent(event, direction, mode)
+  announce(applied
+    ? `${event.title} ${mode === 'move' ? 'moved' : 'resized'} to ${formatEventTime(event)}.`
+    : `${event.title} cannot move further.`)
+}
+
+/** Instructions announced with each event. */
+function eventLabel(event: ScheduleEvent): string {
+  const base = `${event.title}, ${formatEventTime(event)}`
+  if (props.readonly || event.draggable === false) return base
+  return `${base}. Press Alt with the up or down arrow keys to reschedule it.`
+}
+
 function onMonthDayClick(date: Date) {
   currentDate.value = date
   emit('update:modelValue', date)
@@ -254,8 +307,27 @@ onUnmounted(() => {
       </div>
     </div>
 
+    <!-- Loading / error / empty placeholders replace the grid -->
+    <div v-if="error" class="mint-schedule__state">
+      <slot name="error" :error="error">
+        <DataStateInternal state="error" :title="error" />
+      </slot>
+    </div>
+
+    <div v-else-if="loading" class="mint-schedule__state">
+      <slot name="loading">
+        <DataStateInternal state="loading" loading-label="Loading schedule" />
+      </slot>
+    </div>
+
+    <div v-else-if="showEmptyState" class="mint-schedule__state">
+      <slot name="empty">
+        <DataStateInternal state="empty" :title="emptyMessage" />
+      </slot>
+    </div>
+
     <!-- Day / Week View -->
-    <template v-if="currentView === 'day' || currentView === 'week'">
+    <template v-else-if="currentView === 'day' || currentView === 'week'">
       <!-- Day headers -->
       <div v-if="currentView === 'week'" class="mint-schedule__day-headers">
         <div class="mint-schedule__day-header-gutter" />
@@ -312,7 +384,11 @@ onUnmounted(() => {
               :key="event.id"
               :class="['mint-schedule__event', getStatusClass(event.status)]"
               :style="getEventStyle(event, day) || undefined"
+              role="button"
+              tabindex="0"
+              :aria-label="eventLabel(event)"
               @click="onEventClick(event, $event)"
+              @keydown="onEventKeydown(event, $event)"
               @pointerdown="onEventPointerDown(event, dayIdx, $event)"
             >
               <slot name="event" :event="event">
@@ -364,7 +440,7 @@ onUnmounted(() => {
     </template>
 
     <!-- Month View -->
-    <template v-if="currentView === 'month'">
+    <template v-else-if="currentView === 'month'">
       <div class="mint-schedule__month-grid">
         <!-- Weekday headers -->
         <div
@@ -406,9 +482,8 @@ onUnmounted(() => {
         </div>
       </div>
     </template>
+
+    <!-- Reschedule announcements for screen readers -->
+    <div role="status" aria-live="polite" :style="announcerStyle">{{ announcement }}</div>
   </div>
 </template>
-
-<style>
-@import '../styles/components/schedule-calendar.css';
-</style>

package/src/components/ScientificNumber.vue

@@ -191,7 +191,3 @@ async function copyToClipboard() {
     </button>
   </span>
 </template>
-
-<style>
-@import '../styles/components/scientific-number.css';
-</style>

package/src/components/SecretInput.story.vue

@@ -0,0 +1,79 @@
+<script setup lang="ts">
+import { ref } from 'vue'
+import SecretInput from './SecretInput.vue'
+import type { PluginSecretRef } from '../utils/pluginSecrets'
+
+const sizes = ['sm', 'md', 'lg'] as const
+
+const storedRef: PluginSecretRef = { $secret: 'sec_0f2a4c6e8a0c2e4a6c8e0a2c4e6a8c0e', set: true }
+const lockedRef: PluginSecretRef = { $secret: null, locked: true }
+
+const stored = ref<PluginSecretRef | string | null>({ ...storedRef })
+const unset = ref<PluginSecretRef | string | null>(null)
+const locked = ref<PluginSecretRef | string | null>({ ...lockedRef })
+</script>
+
+<template>
+  <Story title="Base Inputs/SecretInput">
+    <Variant title="Playground">
+      <template #default="{ state }">
+        <div style="padding: 2rem; max-width: 600px;">
+          <SecretInput
+            v-model="state.value"
+            :placeholder="state.placeholder"
+            :disabled="state.disabled"
+            :error="state.error"
+            :size="state.size"
+          />
+          <p style="margin-top: 1rem; font-size: 0.875rem; color: var(--text-muted, #94a3b8);">
+            Submits: <code>{{ JSON.stringify(state.value) }}</code>
+          </p>
+        </div>
+      </template>
+
+      <template #controls="{ state }">
+        <HstText v-model="state.placeholder" title="Placeholder" />
+        <HstSelect
+          v-model="state.size"
+          title="Size"
+          :options="sizes.map(size => ({ label: size, value: size }))"
+        />
+        <HstCheckbox v-model="state.disabled" title="Disabled" />
+        <HstCheckbox v-model="state.error" title="Error" />
+      </template>
+
+      <template #initState>
+        {{ {
+          value: { $secret: 'sec_0f2a4c6e8a0c2e4a6c8e0a2c4e6a8c0e', set: true },
+          placeholder: 'Enter a new value',
+          disabled: false,
+          error: false,
+          size: 'md',
+        } }}
+      </template>
+    </Variant>
+
+    <Variant title="States">
+      <div style="padding: 2rem; max-width: 600px; display: flex; flex-direction: column; gap: 1.5rem;">
+        <div>
+          <p style="margin: 0 0 0.5rem; font-size: 0.75rem; color: var(--text-muted); text-transform: uppercase; letter-spacing: 0.05em;">
+            Stored
+          </p>
+          <SecretInput v-model="stored" />
+        </div>
+        <div>
+          <p style="margin: 0 0 0.5rem; font-size: 0.75rem; color: var(--text-muted); text-transform: uppercase; letter-spacing: 0.05em;">
+            Not set
+          </p>
+          <SecretInput v-model="unset" />
+        </div>
+        <div>
+          <p style="margin: 0 0 0.5rem; font-size: 0.75rem; color: var(--text-muted); text-transform: uppercase; letter-spacing: 0.05em;">
+            Provided by environment
+          </p>
+          <SecretInput v-model="locked" />
+        </div>
+      </div>
+    </Variant>
+  </Story>
+</template>