@morscherlab/mint-sdk 1.0.0-alpha.2

package/src/components/Calendar.vue

@@ -0,0 +1,363 @@
+<script setup lang="ts">
+/** Month calendar for single date, multi-date, or range selection with markers and navigation. */
+import { ref, computed, watch } from 'vue'
+import type { CalendarSelectionMode, CalendarMarker, CalendarDayContext } from '../types'
+
+/**
+ * Calendar - Month calendar with date selection, range selection, and custom markers.
+ *
+ * @example
+ * ```vue
+ * <!-- Single date selection -->
+ * <Calendar v-model="selectedDate" />
+ *
+ * <!-- Range selection -->
+ * <Calendar v-model="dateRange" selection-mode="range" />
+ *
+ * <!-- With markers -->
+ * <Calendar :markers="[{ date: '2024-01-15', color: '#ff0000', label: 'Event' }]" />
+ * ```
+ */
+interface Props {
+  /** Selected date(s) - type depends on selectionMode */
+  modelValue?: Date | Date[] | { start: Date; end: Date } | null
+  /** Selection behavior mode */
+  selectionMode?: CalendarSelectionMode
+  /** Display month (0-11) */
+  month?: number
+  /** Display year */
+  year?: number
+  /** Always show 6 weeks (42 days) */
+  fixedWeeks?: boolean
+  /** First day of week (0=Sunday, 1=Monday, etc.) */
+  weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6
+  /** Show days from adjacent months */
+  showOutsideDays?: boolean
+  /** Show month navigation buttons */
+  showNavigation?: boolean
+  /** Visual markers on specific dates */
+  markers?: CalendarMarker[]
+  /** Earliest selectable date */
+  minDate?: Date | string
+  /** Latest selectable date */
+  maxDate?: Date | string
+  /** Explicitly disabled dates */
+  disabledDates?: Array<Date | string>
+  /** Custom disabled date logic */
+  isDateDisabled?: (date: Date) => boolean
+  /** Locale for date formatting */
+  locale?: string
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  selectionMode: 'single',
+  fixedWeeks: true,
+  weekStartsOn: 1,
+  showOutsideDays: true,
+  showNavigation: true,
+  markers: () => [],
+  disabledDates: () => [],
+  locale: 'en-US',
+})
+
+/**
+ * @event update:modelValue - Emitted when date selection changes (v-model support)
+ * @event update:month - Emitted when displayed month changes
+ * @event update:year - Emitted when displayed year changes
+ * @event day-click - Emitted when a day is clicked, includes day context
+ * @event navigate - Emitted when month navigation occurs
+ */
+const emit = defineEmits<{
+  'update:modelValue': [value: Date | Date[] | { start: Date; end: Date } | null]
+  'update:month': [month: number]
+  'update:year': [year: number]
+  'day-click': [context: CalendarDayContext]
+  navigate: [direction: 'prev' | 'next', month: number, year: number]
+}>()
+
+const today = new Date()
+today.setHours(0, 0, 0, 0)
+
+const currentMonth = ref(props.month ?? today.getMonth())
+const currentYear = ref(props.year ?? today.getFullYear())
+
+// Range hover tracking
+const hoveredDate = ref<Date | null>(null)
+
+watch(() => props.month, (val) => { if (val !== undefined) currentMonth.value = val })
+watch(() => props.year, (val) => { if (val !== undefined) currentYear.value = val })
+
+const monthLabel = computed(() => {
+  const date = new Date(currentYear.value, currentMonth.value, 1)
+  return date.toLocaleDateString(props.locale, { month: 'long', year: 'numeric' })
+})
+
+const weekDayLabels = computed(() => {
+  const labels: string[] = []
+  // Use Jan 7, 2024 (Sunday) as reference, then offset by weekStartsOn
+  const base = new Date(2024, 0, 7 + props.weekStartsOn)
+  for (let i = 0; i < 7; i++) {
+    const d = new Date(base)
+    d.setDate(d.getDate() + i)
+    labels.push(d.toLocaleDateString(props.locale, { weekday: 'short' }))
+  }
+  return labels
+})
+
+function toDateKey(d: Date): string {
+  return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}-${String(d.getDate()).padStart(2, '0')}`
+}
+
+function parseDate(val: Date | string): Date {
+  if (val instanceof Date) return val
+  const d = new Date(val + 'T00:00:00')
+  return d
+}
+
+function isSameDay(a: Date, b: Date): boolean {
+  return a.getFullYear() === b.getFullYear() &&
+    a.getMonth() === b.getMonth() &&
+    a.getDate() === b.getDate()
+}
+
+const disabledDateSet = computed(() => {
+  const set = new Set<string>()
+  for (const d of props.disabledDates) {
+    const parsed = parseDate(d)
+    set.add(toDateKey(parsed))
+  }
+  return set
+})
+
+const markerMap = computed(() => {
+  const map = new Map<string, CalendarMarker[]>()
+  for (const marker of props.markers) {
+    const date = parseDate(marker.date)
+    const key = toDateKey(date)
+    if (!map.has(key)) map.set(key, [])
+    map.get(key)!.push(marker)
+  }
+  return map
+})
+
+function isDateSelected(date: Date): boolean {
+  const val = props.modelValue
+  if (!val) return false
+  if (val instanceof Date) return isSameDay(date, val)
+  if (Array.isArray(val)) return val.some(d => isSameDay(date, d))
+  if ('start' in val && 'end' in val) {
+    return isSameDay(date, val.start) || isSameDay(date, val.end)
+  }
+  return false
+}
+
+function isInRange(date: Date): boolean {
+  if (props.selectionMode !== 'range') return false
+  const val = props.modelValue
+  if (!val || !('start' in (val as object))) return false
+  const range = val as { start: Date; end: Date }
+
+  const t = date.getTime()
+  const start = range.start?.getTime()
+  if (!start) return false
+
+  // If hovering during selection (before end is set)
+  if (!range.end && hoveredDate.value) {
+    const hov = hoveredDate.value.getTime()
+    const [lo, hi] = start <= hov ? [start, hov] : [hov, start]
+    return t > lo && t < hi
+  }
+
+  // Complete range
+  if (range.end) {
+    const end = range.end.getTime()
+    return t > start && t < end
+  }
+
+  return false
+}
+
+function isDisabled(date: Date): boolean {
+  if (disabledDateSet.value.has(toDateKey(date))) return true
+  if (props.isDateDisabled?.(date)) return true
+  if (props.minDate) {
+    const min = parseDate(props.minDate)
+    if (date < min) return true
+  }
+  if (props.maxDate) {
+    const max = parseDate(props.maxDate)
+    if (date > max) return true
+  }
+  return false
+}
+
+const calendarDays = computed<CalendarDayContext[]>(() => {
+  const first = new Date(currentYear.value, currentMonth.value, 1)
+  const startDow = first.getDay()
+  const offset = (startDow - props.weekStartsOn + 7) % 7
+
+  const totalCells = props.fixedWeeks ? 42 : (() => {
+    const daysInMonth = new Date(currentYear.value, currentMonth.value + 1, 0).getDate()
+    const needed = offset + daysInMonth
+    return Math.ceil(needed / 7) * 7
+  })()
+
+  const days: CalendarDayContext[] = []
+  for (let i = 0; i < totalCells; i++) {
+    const date = new Date(currentYear.value, currentMonth.value, 1 - offset + i)
+    date.setHours(0, 0, 0, 0)
+    const key = toDateKey(date)
+    days.push({
+      date,
+      dayOfMonth: date.getDate(),
+      isToday: isSameDay(date, today),
+      isSelected: isDateSelected(date),
+      isInRange: isInRange(date),
+      isDisabled: isDisabled(date),
+      isOutsideMonth: date.getMonth() !== currentMonth.value,
+      markers: markerMap.value.get(key) ?? [],
+    })
+  }
+  return days
+})
+
+// Range selection state
+const rangeStart = ref<Date | null>(null)
+
+function handleDayClick(day: CalendarDayContext) {
+  if (day.isDisabled) return
+  if (!props.showOutsideDays && day.isOutsideMonth) return
+
+  emit('day-click', day)
+
+  if (props.selectionMode === 'none') return
+
+  if (props.selectionMode === 'single') {
+    emit('update:modelValue', day.date)
+  } else if (props.selectionMode === 'multiple') {
+    const current = (props.modelValue as Date[] | undefined) ?? []
+    const idx = current.findIndex(d => isSameDay(d, day.date))
+    if (idx >= 0) {
+      const next = [...current]
+      next.splice(idx, 1)
+      emit('update:modelValue', next)
+    } else {
+      emit('update:modelValue', [...current, day.date])
+    }
+  } else if (props.selectionMode === 'range') {
+    if (!rangeStart.value) {
+      rangeStart.value = day.date
+    } else {
+      const start = rangeStart.value
+      const end = day.date
+      rangeStart.value = null
+      const ordered = start.getTime() <= end.getTime()
+        ? { start, end }
+        : { start: end, end: start }
+      emit('update:modelValue', ordered)
+    }
+  }
+}
+
+function handleDayHover(day: CalendarDayContext) {
+  if (props.selectionMode === 'range' && rangeStart.value) {
+    hoveredDate.value = day.date
+  }
+}
+
+function prevMonth() {
+  if (currentMonth.value === 0) {
+    currentMonth.value = 11
+    currentYear.value--
+    emit('update:year', currentYear.value)
+  } else {
+    currentMonth.value--
+  }
+  emit('update:month', currentMonth.value)
+  emit('navigate', 'prev', currentMonth.value, currentYear.value)
+}
+
+function nextMonth() {
+  if (currentMonth.value === 11) {
+    currentMonth.value = 0
+    currentYear.value++
+    emit('update:year', currentYear.value)
+  } else {
+    currentMonth.value++
+  }
+  emit('update:month', currentMonth.value)
+  emit('navigate', 'next', currentMonth.value, currentYear.value)
+}
+</script>
+
+<template>
+  <div class="mld-calendar">
+    <div v-if="showNavigation" class="mld-calendar__header">
+      <button type="button" class="mld-calendar__nav-btn" aria-label="Previous month" @click="prevMonth">
+        <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+          <path d="m15 18-6-6 6-6" />
+        </svg>
+      </button>
+      <slot name="header" :month="currentMonth" :year="currentYear" :prev-month="prevMonth" :next-month="nextMonth">
+        <span class="mld-calendar__title">{{ monthLabel }}</span>
+      </slot>
+      <button type="button" class="mld-calendar__nav-btn" aria-label="Next month" @click="nextMonth">
+        <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+          <path d="m9 18 6-6-6-6" />
+        </svg>
+      </button>
+    </div>
+
+    <div class="mld-calendar__weekdays">
+      <span
+        v-for="(label, i) in weekDayLabels"
+        :key="i"
+        class="mld-calendar__weekday"
+      >
+        <slot name="week-day" :day-name="label" :index="i">{{ label }}</slot>
+      </span>
+    </div>
+
+    <div class="mld-calendar__grid">
+      <button
+        v-for="(day, i) in calendarDays"
+        :key="i"
+        type="button"
+        :disabled="day.isDisabled"
+        :class="[
+          'mld-calendar__day',
+          {
+            'mld-calendar__day--today': day.isToday,
+            'mld-calendar__day--selected': day.isSelected,
+            'mld-calendar__day--in-range': day.isInRange,
+            'mld-calendar__day--disabled': day.isDisabled,
+            'mld-calendar__day--outside': day.isOutsideMonth,
+            'mld-calendar__day--interactive': selectionMode !== 'none' && !day.isDisabled,
+          },
+        ]"
+        @click="handleDayClick(day)"
+        @mouseenter="handleDayHover(day)"
+      >
+        <slot name="day-content" :day="day">
+          <span class="mld-calendar__day-number">{{ day.dayOfMonth }}</span>
+          <div v-if="day.markers.length > 0" class="mld-calendar__markers">
+            <span
+              v-for="(marker, mi) in day.markers.slice(0, 3)"
+              :key="mi"
+              :class="[
+                'mld-calendar__marker',
+                `mld-calendar__marker--${marker.type ?? 'dot'}`,
+              ]"
+              :style="marker.color ? { '--marker-color': marker.color } : {}"
+              :title="marker.label"
+            />
+          </div>
+        </slot>
+      </button>
+    </div>
+  </div>
+</template>
+
+<style>
+@import '../styles/components/calendar.css';
+</style>

package/src/components/ChartContainer.story.vue

@@ -0,0 +1,113 @@
+<script setup lang="ts">
+import ChartContainer from './ChartContainer.vue'
+</script>
+
+<template>
+  <Story title="Data Display/ChartContainer">
+    <Variant title="Playground">
+      <template #default="{ state }">
+        <div style="padding: 2rem; max-width: 700px; margin: 0 auto;">
+          <ChartContainer
+            :title="state.showTitle ? state.title : undefined"
+            :description="state.showDescription ? state.description : undefined"
+            :loading="state.loading"
+            :empty="state.empty"
+            :empty-message="state.emptyMessage"
+          >
+            <div style="height: 300px; display: flex; align-items: center; justify-content: center; color: var(--text-muted, #94a3b8); font-style: italic; border: 2px dashed var(--border-color, #e2e8f0); border-radius: 0.5rem;">
+              Chart content goes here (e.g. Chart.js, D3, etc.)
+            </div>
+          </ChartContainer>
+        </div>
+      </template>
+
+      <template #controls="{ state }">
+        <HstCheckbox v-model="state.showTitle" title="Show Title" />
+        <HstText v-model="state.title" title="Title" />
+        <HstCheckbox v-model="state.showDescription" title="Show Description" />
+        <HstText v-model="state.description" title="Description" />
+        <HstCheckbox v-model="state.loading" title="Loading" />
+        <HstCheckbox v-model="state.empty" title="Empty" />
+        <HstText v-model="state.emptyMessage" title="Empty Message" />
+      </template>
+    </Variant>
+
+    <Variant title="With Title and Description">
+      <div style="padding: 2rem; max-width: 700px; margin: 0 auto;">
+        <ChartContainer
+          title="Dose-Response Curve"
+          description="IC50 analysis for compound MINT-2847 across 8-point dilution series"
+        >
+          <div style="height: 300px; display: flex; align-items: center; justify-content: center; color: var(--text-muted, #94a3b8); font-style: italic; border: 2px dashed var(--border-color, #e2e8f0); border-radius: 0.5rem;">
+            Sigmoidal dose-response chart placeholder
+          </div>
+        </ChartContainer>
+      </div>
+    </Variant>
+
+    <Variant title="Loading State">
+      <div style="padding: 2rem; max-width: 700px; margin: 0 auto;">
+        <ChartContainer
+          title="Cell Viability Heatmap"
+          description="Processing 96-well plate data..."
+          loading
+        >
+          <div style="height: 300px;" />
+        </ChartContainer>
+      </div>
+    </Variant>
+
+    <Variant title="Empty State">
+      <div style="padding: 2rem; max-width: 700px; margin: 0 auto;">
+        <ChartContainer
+          title="Experiment Results"
+          empty
+          empty-message="No results found. Run an analysis to see data here."
+        />
+      </div>
+    </Variant>
+
+    <Variant title="With Toolbar Slot">
+      <div style="padding: 2rem; max-width: 700px; margin: 0 auto;">
+        <ChartContainer title="Proliferation Assay">
+          <template #toolbar>
+            <div style="display: flex; gap: 0.5rem;">
+              <button type="button" style="padding: 0.25rem 0.75rem; font-size: 0.8125rem; border: 1px solid var(--border-color, #e2e8f0); border-radius: 0.375rem; background: var(--bg-card, #fff); color: var(--text-primary, #1e293b); cursor: pointer;">
+                Linear
+              </button>
+              <button type="button" style="padding: 0.25rem 0.75rem; font-size: 0.8125rem; border: 1px solid var(--mint-primary, #3B82F6); border-radius: 0.375rem; background: var(--mint-primary, #3B82F6); color: #fff; cursor: pointer;">
+                Log
+              </button>
+            </div>
+          </template>
+          <div style="height: 300px; display: flex; align-items: center; justify-content: center; color: var(--text-muted, #94a3b8); font-style: italic; border: 2px dashed var(--border-color, #e2e8f0); border-radius: 0.5rem;">
+            Chart with toolbar controls
+          </div>
+        </ChartContainer>
+      </div>
+    </Variant>
+
+    <Variant title="With Legend Slot">
+      <div style="padding: 2rem; max-width: 700px; margin: 0 auto;">
+        <ChartContainer title="Multi-Compound Comparison">
+          <div style="height: 250px; display: flex; align-items: center; justify-content: center; color: var(--text-muted, #94a3b8); font-style: italic; border: 2px dashed var(--border-color, #e2e8f0); border-radius: 0.5rem;">
+            Overlay chart placeholder
+          </div>
+          <template #legend>
+            <div style="display: flex; gap: 1.5rem; justify-content: center; font-size: 0.8125rem; color: var(--text-primary, #1e293b);">
+              <span style="display: flex; align-items: center; gap: 0.375rem;">
+                <span style="width: 12px; height: 12px; border-radius: 50%; background: #3B82F6;" /> MINT-2847
+              </span>
+              <span style="display: flex; align-items: center; gap: 0.375rem;">
+                <span style="width: 12px; height: 12px; border-radius: 50%; background: #EC4899;" /> MINT-3192
+              </span>
+              <span style="display: flex; align-items: center; gap: 0.375rem;">
+                <span style="width: 12px; height: 12px; border-radius: 50%; background: #10B981;" /> Vehicle
+              </span>
+            </div>
+          </template>
+        </ChartContainer>
+      </div>
+    </Variant>
+  </Story>
+</template>

package/src/components/ChartContainer.vue

@@ -0,0 +1,64 @@
+<script setup lang="ts">
+/** Wraps a chart with header, toolbar slot, loading overlay, empty state, and legend slot. */
+import LoadingSpinner from './LoadingSpinner.vue'
+import EmptyState from './EmptyState.vue'
+
+interface Props {
+  title?: string
+  description?: string
+  loading?: boolean
+  empty?: boolean
+  emptyMessage?: string
+}
+
+withDefaults(defineProps<Props>(), {
+  loading: false,
+  empty: false,
+  emptyMessage: 'No data available',
+})
+</script>
+
+<template>
+  <div class="mld-chart">
+    <div v-if="title || description || $slots.toolbar" class="mld-chart__header">
+      <div v-if="title || description" class="mld-chart__header-text">
+        <h3 v-if="title" class="mld-chart__title">{{ title }}</h3>
+        <p v-if="description" class="mld-chart__description">{{ description }}</p>
+      </div>
+      <div v-if="$slots.toolbar" class="mld-chart__toolbar">
+        <slot name="toolbar" />
+      </div>
+    </div>
+
+    <div class="mld-chart__body">
+      <!-- Loading overlay -->
+      <div v-if="loading" class="mld-chart__loading-overlay">
+        <LoadingSpinner size="lg" />
+      </div>
+
+      <!-- Empty state -->
+      <template v-else-if="empty">
+        <slot name="empty">
+          <EmptyState
+            :title="emptyMessage"
+            size="sm"
+            icon-path="M3 13.125C3 12.504 3.504 12 4.125 12h2.25c.621 0 1.125.504 1.125 1.125v6.75C7.5 20.496 6.996 21 6.375 21h-2.25A1.125 1.125 0 013 19.875v-6.75zM9.75 8.625c0-.621.504-1.125 1.125-1.125h2.25c.621 0 1.125.504 1.125 1.125v11.25c0 .621-.504 1.125-1.125 1.125h-2.25a1.125 1.125 0 01-1.125-1.125V8.625zM16.5 4.125c0-.621.504-1.125 1.125-1.125h2.25C20.496 3 21 3.504 21 4.125v15.75c0 .621-.504 1.125-1.125 1.125h-2.25a1.125 1.125 0 01-1.125-1.125V4.125z"
+          />
+        </slot>
+      </template>
+
+      <!-- Chart content -->
+      <template v-else>
+        <slot />
+      </template>
+    </div>
+
+    <div v-if="$slots.legend" class="mld-chart__legend">
+      <slot name="legend" />
+    </div>
+  </div>
+</template>
+
+<style>
+@import '../styles/components/chart-container.css';
+</style>

package/src/components/ChemicalFormula.story.vue

@@ -0,0 +1,102 @@
+<script setup lang="ts">
+import ChemicalFormula from './ChemicalFormula.vue'
+
+const formulas = [
+  { formula: 'H2O', name: 'Water' },
+  { formula: 'NaCl', name: 'Sodium Chloride' },
+  { formula: 'C6H12O6', name: 'Glucose' },
+  { formula: 'Ca(OH)2', name: 'Calcium Hydroxide' },
+  { formula: 'H2SO4', name: 'Sulfuric Acid' },
+  { formula: 'CH3COOH', name: 'Acetic Acid' },
+  { formula: 'C2H5OH', name: 'Ethanol' },
+  { formula: 'NH3', name: 'Ammonia' },
+  { formula: 'CuSO4.5H2O', name: 'Copper Sulfate Pentahydrate' },
+  { formula: 'Fe2O3', name: 'Iron(III) Oxide' },
+]
+</script>
+
+<template>
+  <Story title="Data Display/ChemicalFormula">
+    <Variant title="Playground">
+      <template #default="{ state }">
+        <div style="padding: 2rem; display: flex; align-items: center; justify-content: center; font-size: 1.5rem;">
+          <ChemicalFormula :formula="state.formula" :inline="state.inline" />
+        </div>
+      </template>
+
+      <template #controls="{ state }">
+        <HstText v-model="state.formula" title="Formula" />
+        <HstCheckbox v-model="state.inline" title="Inline" />
+      </template>
+    </Variant>
+
+    <Variant title="Common Formulas">
+      <div style="padding: 2rem; max-width: 500px; margin: 0 auto;">
+        <table style="width: 100%; border-collapse: collapse; font-size: 1rem;">
+          <thead>
+            <tr>
+              <th style="text-align: left; padding: 0.75rem 0.5rem; border-bottom: 2px solid var(--border-color, #e2e8f0); color: var(--text-muted, #94a3b8); font-weight: 600;">Name</th>
+              <th style="text-align: left; padding: 0.75rem 0.5rem; border-bottom: 2px solid var(--border-color, #e2e8f0); color: var(--text-muted, #94a3b8); font-weight: 600;">Formula</th>
+              <th style="text-align: left; padding: 0.75rem 0.5rem; border-bottom: 2px solid var(--border-color, #e2e8f0); color: var(--text-muted, #94a3b8); font-weight: 600;">Rendered</th>
+            </tr>
+          </thead>
+          <tbody>
+            <tr v-for="item in formulas" :key="item.formula">
+              <td style="padding: 0.5rem; border-bottom: 1px solid var(--border-color, #e2e8f0); color: var(--text-primary, #1e293b);">{{ item.name }}</td>
+              <td style="padding: 0.5rem; border-bottom: 1px solid var(--border-color, #e2e8f0); font-family: monospace; color: var(--text-muted, #94a3b8);">{{ item.formula }}</td>
+              <td style="padding: 0.5rem; border-bottom: 1px solid var(--border-color, #e2e8f0); color: var(--text-primary, #1e293b); font-size: 1.125rem;">
+                <ChemicalFormula :formula="item.formula" />
+              </td>
+            </tr>
+          </tbody>
+        </table>
+      </div>
+    </Variant>
+
+    <Variant title="Inline in Text">
+      <div style="padding: 2rem; max-width: 600px; margin: 0 auto; line-height: 1.8; color: var(--text-primary, #1e293b);">
+        <p style="margin: 0 0 1rem;">
+          The reaction of <ChemicalFormula formula="NaOH" /> with <ChemicalFormula formula="HCl" /> produces
+          <ChemicalFormula formula="NaCl" /> and <ChemicalFormula formula="H2O" />.
+        </p>
+        <p style="margin: 0 0 1rem;">
+          Photosynthesis converts <ChemicalFormula formula="CO2" /> and <ChemicalFormula formula="H2O" />
+          into <ChemicalFormula formula="C6H12O6" /> and <ChemicalFormula formula="O2" />.
+        </p>
+        <p style="margin: 0;">
+          The drug compound was dissolved in <ChemicalFormula formula="(CH3)2SO" /> (DMSO) at a stock
+          concentration of 10 mM.
+        </p>
+      </div>
+    </Variant>
+
+    <Variant title="Block Display">
+      <div style="padding: 2rem; display: flex; flex-direction: column; gap: 1rem; align-items: center; font-size: 1.5rem;">
+        <ChemicalFormula formula="C6H12O6" :inline="false" />
+        <ChemicalFormula formula="Ca(OH)2" :inline="false" />
+        <ChemicalFormula formula="CuSO4.5H2O" :inline="false" />
+      </div>
+    </Variant>
+
+    <Variant title="Complex Formulas">
+      <div style="padding: 2rem; display: flex; flex-direction: column; gap: 1.25rem; align-items: center; font-size: 1.25rem;">
+        <div style="display: flex; gap: 0.75rem; align-items: baseline;">
+          <span style="min-width: 180px; text-align: right; color: var(--text-muted, #94a3b8); font-size: 0.875rem;">Aspirin:</span>
+          <ChemicalFormula formula="C9H8O4" />
+        </div>
+        <div style="display: flex; gap: 0.75rem; align-items: baseline;">
+          <span style="min-width: 180px; text-align: right; color: var(--text-muted, #94a3b8); font-size: 0.875rem;">Caffeine:</span>
+          <ChemicalFormula formula="C8H10N4O2" />
+        </div>
+        <div style="display: flex; gap: 0.75rem; align-items: baseline;">
+          <span style="min-width: 180px; text-align: right; color: var(--text-muted, #94a3b8); font-size: 0.875rem;">ATP:</span>
+          <ChemicalFormula formula="C10H16N5O13P3" />
+        </div>
+        <div style="display: flex; gap: 0.75rem; align-items: baseline;">
+          <span style="min-width: 180px; text-align: right; color: var(--text-muted, #94a3b8); font-size: 0.875rem;">Hemoglobin subunit:</span>
+          <ChemicalFormula formula="C738H1166N812O203S2Fe" />
+        </div>
+      </div>
+    </Variant>
+  </Story>
+</template>

package/src/components/ChemicalFormula.vue

@@ -0,0 +1,39 @@
+<script setup lang="ts">
+/** Renders a chemical formula string (H₂O, C₆H₁₂O₆, Ca(OH)₂) with typographically correct subscripts and superscripts for charges. */
+import { useChemicalFormula, type FormulaPart } from '../composables/useChemicalFormula'
+
+interface Props {
+  formula: string
+  inline?: boolean
+}
+
+withDefaults(defineProps<Props>(), {
+  inline: true,
+})
+
+const { renderFormulaParts } = useChemicalFormula()
+
+function getParts(f: string): FormulaPart[] {
+  return renderFormulaParts(f)
+}
+</script>
+
+<template>
+  <component
+    :is="inline ? 'span' : 'div'"
+    :class="['mld-chem-formula', !inline ? 'mld-chem-formula--block' : '']"
+  >
+    <template v-for="(part, i) in getParts(formula)" :key="i">
+      <span v-if="part.type === 'element'" class="mld-chem-formula__element">{{ part.text }}</span>
+      <span v-else-if="part.type === 'subscript'" class="mld-chem-formula__subscript">{{ part.text }}</span>
+      <span v-else-if="part.type === 'superscript'" class="mld-chem-formula__superscript">{{ part.text }}</span>
+      <span v-else-if="part.type === 'paren'" class="mld-chem-formula__paren">{{ part.text }}</span>
+      <span v-else-if="part.type === 'dot'" class="mld-chem-formula__dot">{{ part.text }}</span>
+      <span v-else-if="part.type === 'charge'" class="mld-chem-formula__charge">{{ part.text }}</span>
+    </template>
+  </component>
+</template>
+
+<style>
+@import '../styles/components/chemical-formula.css';
+</style>