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

package/src/components/DataFrame.vue

@@ -1,7 +1,7 @@
 <script setup lang="ts">
 /** Data table with sortable columns, search, pagination, and optional row selection. */
 import { ref, computed, onBeforeUnmount } from 'vue'
-import type { DataFrameColumn, SortState, PaginationState } from '../types'
+import type { DataFrameColumn, DataFrameSpec, SortState } from '../types'
 import { useSortedItems } from '../composables/useSortedItems'
 import { useTextSearch } from '../composables/useTextSearch'
 import { useListSelection } from '../composables/useListSelection'
@@ -9,6 +9,7 @@ import BaseCheckbox from './BaseCheckbox.vue'
 import DataStateInternal from './internal/DataStateInternal.vue'
 import LoadingSpinner from './LoadingSpinner.vue'
 import { tableDensityToSize, tryUseSettingsStore } from '../stores/settings'
+import { applySpecDefaults } from '../composables/componentSpecs'
 
 /** Inbox glyph kept from the pre-1.2 hand-rolled empty state. */
 const EMPTY_ICON_PATH
@@ -18,119 +19,96 @@ const EMPTY_ICON_PATH
 /**
  * DataFrame - Data table with sorting, searching, pagination, and row selection.
  *
+ * The structure (columns, paging, search, selection) is one `:spec` built with
+ * `defineDataFrame()`. Rows, loading and error are plain props; sort,
+ * selection, page and column widths are `v-model`s.
+ *
  * @example
+ * ```ts
+ * const table = defineDataFrame({
+ *   columns: [{ key: 'name', label: 'Name', sortable: true }, { key: 'age', label: 'Age', type: 'number' }],
+ *   rowKey: 'id',
+ *   searchable: true,
+ *   pagination: { pageSize: 10 },
+ * })
+ * ```
  * ```vue
- * <DataFrame
- *   :data="rows"
- *   :columns="[
- *     { key: 'name', label: 'Name', sortable: true },
- *     { key: 'age', label: 'Age', align: 'right' }
- *   ]"
- *   sortable
- *   searchable
- *   :pagination="{ page: 1, pageSize: 10, total: 100 }"
- * />
+ * <DataFrame :spec="table" :data="rows" v-model:selected="selected" />
  * ```
  */
 interface Props {
+  /** Structure built with defineDataFrame(). Optional: every option has a default. */
+  spec?: DataFrameSpec
   /** Array of data objects */
   data: Record<string, unknown>[]
-  /** Column definitions */
-  columns: DataFrameColumn[]
-  /** Unique key for each row (property name or function) */
-  rowKey?: string | ((row: Record<string, unknown>) => string | number)
-  /** Alternate row background colors */
-  striped?: boolean
-  /** Show table borders */
-  bordered?: boolean
-  /**
-   * Table size. Left unset, it follows the platform's `tableDensity` setting
-   * (compact → `sm`, normal → `md`, comfortable → `lg`) and falls back to
-   * `md` when no settings store is installed.
-   */
-  size?: 'sm' | 'md' | 'lg'
-  /** Make header sticky on scroll */
-  stickyHeader?: boolean
-  /** Maximum table height (enables vertical scroll) */
-  maxHeight?: string | number
   /** Show loading overlay */
   loading?: boolean
-  /**
-   * Error message. When set, the table body is replaced by an error state
-   * instead of the empty state. `null`/`undefined` renders normally.
-   */
+  /** Error message. When set, the table body is replaced by an error state. */
   error?: string | null
   /** Empty state message */
   emptyText?: string
-  /** Enable column sorting */
-  sortable?: boolean
-  /** Current sort state (controlled mode) */
+  /** Current sort state. Bind with `v-model:sort`; unbound, the table keeps its own. */
   sort?: SortState | null
-  /** Pagination state or false to disable */
-  pagination?: PaginationState | false
-  /** Enable search input */
-  searchable?: boolean
-  /** Search input placeholder */
-  searchPlaceholder?: string
-  /** Column keys to search (defaults to all) */
-  searchKeys?: string[]
-  /** Enable row selection with checkboxes */
-  selectable?: boolean
-  /** Currently selected row keys */
-  selectedKeys?: (string | number)[]
-  /** Make each body row act as a click/keyboard target. */
-  clickableRows?: boolean
-  /** Show a trailing action column with a per-row delete button. */
-  deletable?: boolean
-  /** Tooltip / aria-label for the row delete button. */
-  deleteLabel?: string
-  /** Allow dragging a column's right edge to resize it. */
-  resizable?: boolean
-  /** Controlled column widths in px, keyed by column key (omit for uncontrolled). */
+  /** Selected row keys. Bind with `v-model:selected`. */
+  selected?: (string | number)[]
+  /** Current page (1-indexed) when `spec.pagination` is set. Bind with `v-model:page`; unbound, the table keeps its own. */
+  page?: number
+  /** Column widths in px keyed by column key. Bind with `v-model:column-widths`; unbound, the table keeps its own. */
   columnWidths?: Record<string, number>
 }
 
 const props = withDefaults(defineProps<Props>(), {
-  striped: true,
-  bordered: true,
-  stickyHeader: false,
+  spec: () => ({}),
   loading: false,
   error: null,
   emptyText: 'No data',
-  sortable: false,
-  pagination: false,
-  searchable: false,
-  searchPlaceholder: 'Search...',
-  selectable: false,
-  selectedKeys: () => [],
-  clickableRows: false,
-  deletable: false,
-  deleteLabel: 'Delete row',
-  resizable: false,
+  sort: undefined,
+  selected: () => [],
+  page: undefined,
+  columnWidths: undefined,
 })
 
 /**
  * @event update:sort - Emitted when sort state changes
- * @event update:pagination - Emitted when page changes
- * @event update:selectedKeys - Emitted when row selection changes
+ * @event update:page - Emitted when the page changes
+ * @event update:selected - Emitted when row selection changes
  * @event row-click - Emitted when a row is clicked
  * @event cell-click - Emitted when a cell is clicked
  */
 const emit = defineEmits<{
   'update:sort': [sort: SortState | null]
-  'update:pagination': [pagination: PaginationState]
-  'update:selectedKeys': [keys: (string | number)[]]
+  'update:page': [page: number]
+  'update:selected': [keys: (string | number)[]]
   'update:columnWidths': [widths: Record<string, number>]
   'row-click': [row: Record<string, unknown>, index: number]
   'cell-click': [value: unknown, column: DataFrameColumn, row: Record<string, unknown>]
   'delete-row': [row: Record<string, unknown>, index: number]
 }>()
 
+const config = computed(() => applySpecDefaults({
+  striped: true,
+  bordered: true,
+  stickyHeader: false,
+  sortable: false,
+  pagination: false as const,
+  searchable: false,
+  searchPlaceholder: 'Search...',
+  selectable: false,
+  clickableRows: false,
+  deletable: false,
+  deleteLabel: 'Delete row',
+  resizable: false,
+}, props.spec))
+
+const columns = computed<DataFrameColumn[]>(() =>
+  config.value.columns ?? Object.keys(props.data[0] ?? {}).map(key => ({ key, label: key })),
+)
+
 const settings = tryUseSettingsStore()
 
 /** Explicit `size` wins; otherwise the user's table density, else `md`. */
 const size = computed<'sm' | 'md' | 'lg'>(() =>
-  props.size ?? (settings ? tableDensityToSize(settings.tableDensity) : 'md'),
+  config.value.size ?? (settings ? tableDensityToSize(settings.tableDensity) : 'md'),
 )
 
 const searchQuery = ref('')
@@ -139,9 +117,10 @@ const internalSort = ref<SortState | null>(null)
 const activeSort = computed(() => props.sort !== undefined ? props.sort : internalSort.value)
 
 function getRowKey(row: Record<string, unknown>, index: number): string | number {
-  if (!props.rowKey) return index
-  if (typeof props.rowKey === 'function') return props.rowKey(row)
-  return row[props.rowKey] as string | number
+  const { rowKey } = config.value
+  if (!rowKey) return index
+  if (typeof rowKey === 'function') return rowKey(row)
+  return row[rowKey] as string | number
 }
 
 function getCellValue(row: Record<string, unknown>, key: string): unknown {
@@ -167,9 +146,9 @@ function columnAlign(col: DataFrameColumn): 'left' | 'center' | 'right' {
 const textSearch = useTextSearch({
   items: () => props.data,
   query: searchQuery,
-  enabled: () => props.searchable,
+  enabled: () => config.value.searchable,
   getText: (row) => {
-    const keys = props.searchKeys ?? props.columns.map(c => c.key)
+    const keys = config.value.searchKeys ?? columns.value.map(c => c.key)
     return keys.map(key => getCellValue(row, key))
   },
 })
@@ -180,27 +159,32 @@ const tableSort = useSortedItems({
   sort: activeSort,
   enabled: () => {
     const sort = activeSort.value
-    return Boolean(sort?.direction && props.columns.some(c => c.key === sort.key))
+    return Boolean(sort?.direction && columns.value.some(c => c.key === sort.key))
   },
   getValue: (row, key) => getCellValue(row, key),
 })
 const sortedData = tableSort.sortedItems
 
-// Pagination
-const paginatedData = computed(() => {
-  if (!props.pagination) return sortedData.value
-  const { page, pageSize } = props.pagination
-  const start = (page - 1) * pageSize
-  return sortedData.value.slice(start, start + pageSize)
-})
+// Pagination: a bound `page` wins; unbound, the table keeps its own.
+const internalPage = ref(1)
+const pageSize = computed(() => config.value.pagination ? config.value.pagination.pageSize : 0)
 
 const totalPages = computed(() => {
-  if (!props.pagination) return 1
-  return Math.max(1, Math.ceil(sortedData.value.length / props.pagination.pageSize))
+  if (!pageSize.value) return 1
+  return Math.max(1, Math.ceil(sortedData.value.length / pageSize.value))
+})
+
+// Kept inside `totalPages`, so a search or shorter `data` never leaves an empty page.
+const currentPage = computed(() => Math.min(props.page ?? internalPage.value, totalPages.value))
+
+const paginatedData = computed(() => {
+  if (!pageSize.value) return sortedData.value
+  const start = (currentPage.value - 1) * pageSize.value
+  return sortedData.value.slice(start, start + pageSize.value)
 })
 
 function handleSort(col: DataFrameColumn) {
-  if (!col.sortable && !props.sortable) return
+  if (!col.sortable && !config.value.sortable) return
 
   const current = activeSort.value
   let next: SortState | null
@@ -224,8 +208,8 @@ function handleSort(col: DataFrameColumn) {
 }
 
 function handlePageChange(page: number) {
-  if (!props.pagination) return
-  emit('update:pagination', { ...props.pagination, page })
+  internalPage.value = page
+  emit('update:page', page)
 }
 
 function handleRowClick(row: Record<string, unknown>, index: number) {
@@ -233,7 +217,7 @@ function handleRowClick(row: Record<string, unknown>, index: number) {
 }
 
 function handleRowKeydown(event: KeyboardEvent, row: Record<string, unknown>, index: number) {
-  if (!props.clickableRows) return
+  if (!config.value.clickableRows) return
   if (event.key !== 'Enter' && event.key !== ' ') return
   event.preventDefault()
   handleRowClick(row, index)
@@ -241,13 +225,13 @@ function handleRowKeydown(event: KeyboardEvent, row: Record<string, unknown>, in
 
 function handleCellClick(row: Record<string, unknown>, col: DataFrameColumn, index: number) {
   emit('cell-click', getCellValue(row, col.key), col, row)
-  if (props.clickableRows) {
+  if (config.value.clickableRows) {
     handleRowClick(row, index)
   }
 }
 
 function isColumnSortable(col: DataFrameColumn): boolean {
-  return col.sortable === true || (props.sortable && col.sortable !== false)
+  return col.sortable === true || (config.value.sortable && col.sortable !== false)
 }
 
 /** `aria-sort` for the header cell, omitted on columns that cannot be sorted. */
@@ -270,27 +254,27 @@ const pageRowKeys = computed(() =>
   paginatedData.value.map((row, i) => getRowKey(row, i))
 )
 const rowSelection = useListSelection({
-  selected: () => props.selectedKeys,
+  selected: () => props.selected,
   items: pageRowKeys,
 })
 const allSelected = computed(() => {
-  return props.selectable && rowSelection.isAllSelected.value
+  return config.value.selectable && rowSelection.isAllSelected.value
 })
 
 const selectIndeterminate = computed(() => {
-  return props.selectedKeys.length > 0 && !allSelected.value
+  return props.selected.length > 0 && !allSelected.value
 })
 
 function toggleSelectAll() {
   if (allSelected.value) {
-    emit('update:selectedKeys', [])
+    emit('update:selected', [])
   } else {
-    emit('update:selectedKeys', rowSelection.itemValues.value)
+    emit('update:selected', rowSelection.itemValues.value)
   }
 }
 
 function toggleRowSelect(key: string | number) {
-  emit('update:selectedKeys', rowSelection.toggleValue(key))
+  emit('update:selected', rowSelection.toggleValue(key))
 }
 
 // Column resizing — uncontrolled by default; pass `columnWidths` to control it.
@@ -371,9 +355,9 @@ function handleDeleteRow(row: Record<string, unknown>, index: number) {
 }
 
 const wrapperStyle = computed(() => {
-  if (!props.maxHeight) return undefined
-  const maxHeight = typeof props.maxHeight === 'number' ? `${props.maxHeight}px` : props.maxHeight
-  return { maxHeight, overflowY: 'auto' as const }
+  const { maxHeight } = config.value
+  if (!maxHeight) return undefined
+  return { maxHeight: toCssSize(maxHeight), overflowY: 'auto' as const }
 })
 </script>
 
@@ -381,11 +365,11 @@ const wrapperStyle = computed(() => {
   <div
     :class="[
       'mint-dataframe',
-      { 'mint-dataframe--bordered': bordered },
+      { 'mint-dataframe--bordered': config.bordered },
     ]"
   >
     <!-- Search header -->
-    <div v-if="searchable" class="mint-dataframe__header">
+    <div v-if="config.searchable" class="mint-dataframe__header">
       <div class="mint-dataframe__search-wrapper">
         <svg class="mint-dataframe__search-icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
           <circle cx="11" cy="11" r="8" /><path d="m21 21-4.34-4.34" />
@@ -394,7 +378,7 @@ const wrapperStyle = computed(() => {
           v-model="searchQuery"
           type="text"
           class="mint-dataframe__search"
-          :placeholder="searchPlaceholder"
+          :placeholder="config.searchPlaceholder"
         />
       </div>
     </div>
@@ -402,9 +386,9 @@ const wrapperStyle = computed(() => {
     <!-- Table wrapper -->
     <div class="mint-dataframe__table-wrapper" :style="wrapperStyle">
       <table class="mint-dataframe__table">
-        <thead :class="['mint-dataframe__thead', { 'mint-dataframe__thead--sticky': stickyHeader }]">
+        <thead :class="['mint-dataframe__thead', { 'mint-dataframe__thead--sticky': config.stickyHeader }]">
           <tr>
-            <th v-if="selectable" class="mint-dataframe__th mint-dataframe__th--checkbox">
+            <th v-if="config.selectable" class="mint-dataframe__th mint-dataframe__th--checkbox">
               <BaseCheckbox
                 :model-value="allSelected"
                 :indeterminate="selectIndeterminate"
@@ -424,7 +408,7 @@ const wrapperStyle = computed(() => {
                 {
                   'mint-dataframe__th--sortable': isColumnSortable(col),
                   'mint-dataframe__th--sorted': activeSort?.key === col.key && activeSort?.direction,
-                  'mint-dataframe__th--resizable': resizable,
+                  'mint-dataframe__th--resizable': config.resizable,
                 },
               ]"
               :style="columnStyle(col)"
@@ -465,7 +449,7 @@ const wrapperStyle = computed(() => {
               </slot>
               </component>
               <span
-                v-if="resizable"
+                v-if="config.resizable"
                 class="mint-dataframe__resize-handle"
                 role="slider"
                 tabindex="0"
@@ -479,7 +463,7 @@ const wrapperStyle = computed(() => {
               />
             </th>
             <th
-              v-if="deletable"
+              v-if="config.deletable"
               :class="['mint-dataframe__th', `mint-dataframe__th--${size}`, 'mint-dataframe__th--actions']"
               aria-label="Actions"
             />
@@ -493,17 +477,17 @@ const wrapperStyle = computed(() => {
             :class="[
               'mint-dataframe__row',
               {
-                'mint-dataframe__row--striped': striped && rowIndex % 2 === 1,
+                'mint-dataframe__row--striped': config.striped && rowIndex % 2 === 1,
                 'mint-dataframe__row--selected': rowSelection.isSelected(getRowKey(row, rowIndex)),
-                'mint-dataframe__row--clickable': clickableRows,
+                'mint-dataframe__row--clickable': config.clickableRows,
               },
             ]"
-            :tabindex="clickableRows ? 0 : undefined"
-            :role="clickableRows ? 'button' : undefined"
+            :tabindex="config.clickableRows ? 0 : undefined"
+            :role="config.clickableRows ? 'button' : undefined"
             @click="handleRowClick(row, rowIndex)"
             @keydown="handleRowKeydown($event, row, rowIndex)"
           >
-            <td v-if="selectable" class="mint-dataframe__td mint-dataframe__td--checkbox">
+            <td v-if="config.selectable" class="mint-dataframe__td mint-dataframe__td--checkbox">
               <BaseCheckbox
                 :model-value="rowSelection.isSelected(getRowKey(row, rowIndex))"
                 size="sm"
@@ -532,14 +516,14 @@ const wrapperStyle = computed(() => {
               </slot>
             </td>
             <td
-              v-if="deletable"
+              v-if="config.deletable"
               :class="['mint-dataframe__td', `mint-dataframe__td--${size}`, 'mint-dataframe__td--actions']"
             >
               <button
                 type="button"
                 class="mint-dataframe__delete-btn"
-                :aria-label="deleteLabel"
-                :title="deleteLabel"
+                :aria-label="config.deleteLabel"
+                :title="config.deleteLabel"
                 @click.stop="handleDeleteRow(row, rowIndex)"
               >
                 <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
@@ -574,29 +558,29 @@ const wrapperStyle = computed(() => {
     </div>
 
     <!-- Footer / Pagination -->
-    <div v-if="pagination" class="mint-dataframe__footer">
+    <div v-if="pageSize" class="mint-dataframe__footer">
       <slot name="footer">
         <span class="mint-dataframe__page-info">
-          {{ (pagination.page - 1) * pagination.pageSize + 1 }}&ndash;{{ Math.min(pagination.page * pagination.pageSize, sortedData.length) }}
+          {{ (currentPage - 1) * pageSize + 1 }}&ndash;{{ Math.min(currentPage * pageSize, sortedData.length) }}
           of {{ sortedData.length }}
         </span>
         <div class="mint-dataframe__page-controls">
           <button
             type="button"
             class="mint-dataframe__page-btn"
-            :disabled="pagination.page <= 1"
-            @click="handlePageChange(pagination.page - 1)"
+            :disabled="currentPage <= 1"
+            @click="handlePageChange(currentPage - 1)"
           >
             <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>
-          <span class="mint-dataframe__page-number">{{ pagination.page }} / {{ totalPages }}</span>
+          <span class="mint-dataframe__page-number">{{ currentPage }} / {{ totalPages }}</span>
           <button
             type="button"
             class="mint-dataframe__page-btn"
-            :disabled="pagination.page >= totalPages"
-            @click="handlePageChange(pagination.page + 1)"
+            :disabled="currentPage >= totalPages"
+            @click="handlePageChange(currentPage + 1)"
           >
             <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" />

package/src/components/{DateTimePicker.story.vue → DatePicker.datetime.story.vue}

@@ -1,5 +1,5 @@
 <script setup lang="ts">
-import DateTimePicker from './DateTimePicker.vue'
+import DatePicker from './DatePicker.vue'
 
 const now = new Date()
 const today = `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, '0')}-${String(now.getDate()).padStart(2, '0')}T09:00`
@@ -13,7 +13,7 @@ function initState() {
     modelValue: today as string | undefined,
     placeholder: 'Select date & time',
     disabled: false,
-    error: false,
+    invalid: false,
     size: 'md' as const,
     timeStep: 15,
     timeFormat: '24h' as const,
@@ -23,18 +23,19 @@ function initState() {
 </script>
 
 <template>
-  <Story title="Scheduling/DateTimePicker">
+  <Story title="Scheduling/DatePicker · datetime">
     <Variant title="Playground" :init-state="initState">
       <template #default="{ state }">
         <div style="padding: 2rem; max-width: 400px; min-height: 36rem;">
-          <DateTimePicker
+          <DatePicker
+            type="datetime"
             v-model="state.modelValue"
             :placeholder="state.placeholder"
             :disabled="state.disabled"
-            :error="state.error"
+            :invalid="state.invalid"
             :size="state.size"
-            :time-step="state.timeStep"
-            :time-format="state.timeFormat"
+            :step="state.timeStep"
+            :format="state.timeFormat"
             :clearable="state.clearable"
           />
         </div>
@@ -43,7 +44,7 @@ function initState() {
         <HstText v-model="state.modelValue" title="Value (ISO)" />
         <HstText v-model="state.placeholder" title="Placeholder" />
         <HstCheckbox v-model="state.disabled" title="Disabled" />
-        <HstCheckbox v-model="state.error" title="Error" />
+        <HstCheckbox v-model="state.invalid" title="Invalid" />
         <HstSelect
           v-model="state.size"
           title="Size"
@@ -68,16 +69,18 @@ function initState() {
 
     <Variant title="12-Hour Format">
       <div style="padding: 2rem; max-width: 400px;">
-        <DateTimePicker
+        <DatePicker
+          type="datetime"
           :model-value="today"
-          time-format="12h"
+          format="12h"
         />
       </div>
     </Variant>
 
     <Variant title="With Min/Max Range">
       <div style="padding: 2rem; max-width: 400px;">
-        <DateTimePicker
+        <DatePicker
+          type="datetime"
           :model-value="today"
           :min="today"
           :max="nextWeekStr"
@@ -87,7 +90,8 @@ function initState() {
 
     <Variant title="Clearable">
       <div style="padding: 2rem; max-width: 400px;">
-        <DateTimePicker
+        <DatePicker
+          type="datetime"
           :model-value="today"
           clearable
         />
@@ -96,13 +100,14 @@ function initState() {
 
     <Variant title="No Value">
       <div style="padding: 2rem; max-width: 400px;">
-        <DateTimePicker placeholder="Pick a date and time" />
+        <DatePicker type="datetime" placeholder="Pick a date and time" />
       </div>
     </Variant>
 
     <Variant title="Disabled">
       <div style="padding: 2rem; max-width: 400px;">
-        <DateTimePicker
+        <DatePicker
+          type="datetime"
           :model-value="today"
           disabled
         />

package/src/components/DatePicker.story.vue

@@ -33,7 +33,7 @@ function initPlayground() {
             v-model="state.value"
             :placeholder="state.placeholder"
             :disabled="state.disabled"
-            :error="state.error"
+            :invalid="state.error"
             :size="state.size"
             :clearable="state.clearable"
             :min="state.useMin ? state.min : undefined"
@@ -97,7 +97,7 @@ function initPlayground() {
       <div style="padding: 2rem; max-width: 400px; margin: 0 auto;">
         <DatePicker
           model-value="2026-01-01"
-          error
+          invalid
           placeholder="Invalid date"
         />
       </div>