@wishbone-media/spark 0.14.0 → 0.15.0

package/src/components/SparkTable.vue

@@ -0,0 +1,368 @@
+<template>
+  <div class="spark-table">
+    <!-- Header Toolbar: All plugins flow left to right -->
+    <spark-table-toolbar v-if="sparkTable.computed.ready" position="header">
+      <component
+        v-for="plugin in headerPlugins"
+        :key="plugin.name"
+        :is="pluginComponentsByType[plugin.config.type]"
+        :class="plugin.config.align ? `self-${plugin.config.align}` : ''"
+        :spark-table="sparkTable"
+        :config="plugin.config"
+      />
+      <slot name="header" :spark-table="sparkTable" :loading="loading" :error="error"></slot>
+    </spark-table-toolbar>
+
+    <!-- Table Grid -->
+    <HotTable theme-name="ht-theme-classic" ref="table" :settings="sparkTable.tableSettings" />
+
+    <!-- Footer Toolbar: Pagination always on the right -->
+    <spark-table-toolbar v-if="sparkTable.computed.ready" position="footer">
+      <spark-table-pagination-details
+        :spark-table="sparkTable"
+      />
+      <div class="flex items-center gap-x-3">
+        <spark-table-pagination-paging
+          :spark-table="sparkTable"
+          @paginate="sparkTable.methods.applyParams"
+        />
+        <spark-table-pagination-per-page
+          :spark-table="sparkTable"
+          @paginate="sparkTable.methods.applyParams"
+        />
+        <slot name="footer" :spark-table="sparkTable" :loading="loading" :error="error"></slot>
+      </div>
+    </spark-table-toolbar>
+  </div>
+</template>
+
+<script>
+const defaultOptions = {
+  perPages: [100, 200, 500],
+  limit: 100,
+}
+
+const defaultParams = {
+  page: 1,
+  limit: defaultOptions.limit,
+}
+
+const defaultTableSettings = {
+  colHeaders: true,
+  filters: false,
+  stretchH: 'all',
+  colWidths: 50,
+  renderAllRows: true,
+  readOnly: true,
+  tableClassName: 'spark-table-table',
+  readOnlyCellClassName: 'read-only',
+  licenseKey: 'non-commercial-and-evaluation',
+}
+</script>
+<script setup>
+import { computed, onMounted, ref, reactive, inject } from 'vue'
+import nprogress from 'nprogress'
+import { has, get, find } from 'lodash'
+import { HotTable } from '@handsontable/vue3'
+import 'handsontable/styles/handsontable.css'
+import 'handsontable/styles/ht-theme-classic.css'
+import {
+  registerPlugin,
+  AutoColumnSize,
+  CopyPaste,
+  StretchColumns,
+  NestedHeaders,
+} from 'handsontable/plugins'
+import { registerAllCellTypes } from 'handsontable/cellTypes'
+import { watchDebounced } from '@vueuse/core'
+import { customiseHeader } from '@/utils/sparkTable/header.js'
+import { registerSparkRenderers } from '@/utils/sparkTable/renderers'
+import { updateRow } from '@/utils/sparkTable/update-row.js'
+import SparkTablePaginationDetails from './SparkTablePaginationDetails.vue'
+import SparkTablePaginationPaging from './SparkTablePaginationPaging.vue'
+import SparkTablePaginationPerPage from './SparkTablePaginationPerPage.vue'
+import SparkTableToolbar from './SparkTableToolbar.vue'
+import { SparkTableSearch, SparkTableFilterSelect, SparkTableFilterButtons, SparkTableDatePicker, SparkTableReset } from './plugins'
+
+const props = defineProps({
+  url: {
+    type: String,
+  },
+
+  dataProvider: {
+    type: Function,
+  },
+
+  dataTransformer: {
+    type: Function,
+
+    default: (data, props) => {
+      const hasNestedHeaders = get(props.settings, 'nestedHeaders')
+
+      return {
+        data: hasNestedHeaders
+          ? data.data.data.map((row) => {
+              const columnKeys = props.settings.columnKeys || []
+              return columnKeys.map((key) => row[key])
+            })
+          : data.data.data,
+        meta: {
+          last_page: data.data.last_page,
+          from: data.data.from,
+          to: data.data.to,
+          total: data.data.total,
+        },
+      }
+    },
+  },
+
+  params: {
+    type: Object,
+    default() {
+      return defaultParams
+    },
+  },
+
+  options: {
+    type: Object,
+    default() {
+      return defaultOptions
+    },
+  },
+
+  settings: {
+    type: Object,
+    default() {
+      return defaultTableSettings
+    },
+  },
+
+  plugins: {
+    type: Object,
+    default: () => ({}),
+  },
+})
+
+registerAllCellTypes()
+registerPlugin(AutoColumnSize)
+registerPlugin(CopyPaste)
+registerPlugin(StretchColumns)
+if (get(props, 'settings.nestedHeaders')) {
+  registerPlugin(NestedHeaders)
+}
+
+const emit = defineEmits([
+  'viewRow',
+  'editRow',
+  'deleteRow',
+  'ready',
+  'loading',
+  'load',
+  'error',
+  'page-change',
+])
+
+// Inject configured axios instance
+const axios = inject('axios')
+
+const table = ref(null)
+const loading = ref(false)
+const error = ref(null)
+
+// Plugin component mapping by type
+const pluginComponentsByType = {
+  search: SparkTableSearch,
+  filterSelect: SparkTableFilterSelect,
+  filterButtons: SparkTableFilterButtons,
+  datePicker: SparkTableDatePicker,
+  reset: SparkTableReset,
+}
+
+// Header plugins: all enabled plugins flow left to right
+const headerPlugins = computed(() => {
+  return Object.entries(props.plugins)
+    .filter(([_, config]) => config && config.enabled)
+    .map(([name, config]) => ({ name, config }))
+})
+
+const sparkTable = reactive({
+  hotInstance: null,
+  url: props.url,
+  plugins: props.plugins,
+  response: {},
+  params: {
+    page: 1,
+    limit: props.options.limit,
+  },
+  methods: {
+    applyParams: (payload) => {
+      if (payload) {
+        sparkTable.params = {
+          ...sparkTable.params,
+          ...payload,
+        }
+        emit('page-change', sparkTable.params)
+      }
+    },
+
+    removeParam: async (prop) => {
+      if (sparkTable.params[prop]) {
+        delete sparkTable.params[prop]
+        await sparkTable.methods.loadTable()
+      }
+    },
+
+    loadTable: async (callback) => {
+      if (!table.value || !table.value.hotInstance) {
+        return
+      }
+
+      loading.value = true
+      error.value = null
+      emit('loading', true)
+
+      nprogress.start()
+
+      sparkTable.hotInstance = table.value.hotInstance
+
+      try {
+        if (props.dataProvider) {
+          const response = await props.dataProvider(sparkTable.computed.params)
+          sparkTable.response = props.dataTransformer(response, props)
+        } else if (props.url) {
+          const response = await axios.get(props.url, {
+            params: sparkTable.computed.params,
+          })
+          sparkTable.response = props.dataTransformer(response, props)
+        } else {
+          console.error('No data provider or URL provided')
+          loading.value = false
+          emit('loading', false)
+          nprogress.done()
+          return
+        }
+
+        sparkTable.hotInstance.updateData(sparkTable.response.data)
+
+        if (sparkTable.options.callback && typeof sparkTable.options.callback === 'function') {
+          await sparkTable.options.callback()
+        }
+
+        // @see: https://forum.handsontable.com/t/table-not-maintaning-width/3116/11
+        const autoColumnSize = sparkTable.hotInstance.getPlugin('autoColumnSize')
+        autoColumnSize.recalculateAllColumnsWidth()
+
+        emit('load', {
+          data: sparkTable.response.data,
+          meta: sparkTable.response.meta,
+        })
+
+        if (callback && typeof callback === 'function') {
+          callback()
+        }
+      } catch (e) {
+        error.value = e
+        emit('error', e)
+        console.error('Error loading table data:', e)
+      } finally {
+        loading.value = false
+        emit('loading', false)
+        nprogress.done()
+      }
+    },
+
+    // can't use sparkTable.hotInstance here because the ref isn't ready
+    colToProp: (col) => table.value.hotInstance.colToProp(col),
+
+    fireEvent: (type, payload) => {
+      emit(type, payload)
+    },
+
+    getSettingsForProp: (prop) => find(get(sparkTable.tableSettings, `columns`), { data: prop }),
+
+    // Helper methods for easier param access
+    getParams: () => sparkTable.computed.params,
+    getParam: (key) => sparkTable.computed.params[key],
+    setParam: (key, value) => {
+      sparkTable.methods.applyParams({ [key]: value })
+    },
+    clearParam: (key) => sparkTable.methods.removeParam(key),
+    clearParams: (keys) => {
+      // Clear multiple params at once without triggering multiple reloads
+      const keysArray = Array.isArray(keys) ? keys : [keys]
+      keysArray.forEach(key => {
+        if (sparkTable.params[key] !== undefined) {
+          delete sparkTable.params[key]
+        }
+      })
+      // Trigger a single reload
+      sparkTable.methods.applyParams({ page: 1 })
+    },
+  },
+
+  computed: {
+    params: computed(() => ({
+      ...props.params,
+      ...sparkTable.params,
+    })),
+
+    ready: computed(() => has(sparkTable, 'response.meta.last_page')),
+  },
+
+  options: computed(() => ({
+    ...defaultOptions,
+    ...props.options,
+  })),
+
+  tableSettings: computed(() => ({
+    ...defaultTableSettings,
+    ...{
+      ...{
+        nestedHeaders: get(props.settings, 'nestedHeaders', []),
+      },
+      ...(!get(props.settings, 'nestedHeaders') && {
+        afterGetColHeader: (col, th) => customiseHeader(col, th, sparkTable),
+      }),
+      afterChange: (changes, source) => updateRow(changes, source, sparkTable),
+    },
+    ...props.settings,
+  })),
+})
+
+watchDebounced(
+  () => props.params,
+  async () => {
+    sparkTable.params.page = 1
+    await sparkTable.methods.loadTable()
+  },
+  { debounce: 50, maxWait: 1000 },
+)
+watchDebounced(
+  () => sparkTable.params,
+  async () => {
+    await sparkTable.methods.loadTable()
+  },
+  { debounce: 50, maxWait: 1000 },
+)
+
+onMounted(async () => {
+  await sparkTable.methods.loadTable()
+  emit('ready')
+})
+
+registerSparkRenderers(sparkTable)
+
+defineExpose({
+  refresh: () => sparkTable.methods.loadTable(),
+  getParams: () => sparkTable.methods.getParams(),
+  getParam: (key) => sparkTable.methods.getParam(key),
+  setParam: (key, value) => sparkTable.methods.setParam(key, value),
+  clearParam: (key) => sparkTable.methods.clearParam(key),
+  clearParams: (keys) => sparkTable.methods.clearParams(keys),
+  applyParams: (params) => sparkTable.methods.applyParams(params),
+  loading,
+  error,
+  sparkTable,
+  table,
+})
+</script>

package/src/components/SparkTablePaginationDetails.vue

@@ -0,0 +1,26 @@
+<template>
+  <div>
+    <div class="flex items-center gap-4 px-4 py-3">
+      <div class="shrink-0">
+        <div class="text-sm text-gray-700">
+          Showing
+          <span class="font-medium">{{ props.sparkTable.response.meta.from }}</span>
+          to
+          <span class="font-medium">{{ props.sparkTable.response.meta.to }}</span>
+          of
+          <span class="font-medium">{{ props.sparkTable.response.meta.total }}</span>
+          results
+        </div>
+      </div>
+    </div>
+  </div>
+</template>
+
+<script setup>
+const props = defineProps({
+  sparkTable: {
+    type: Object,
+    required: true,
+  },
+})
+</script>

package/src/components/SparkTablePaginationPaging.vue

@@ -0,0 +1,102 @@
+<template>
+  <div>
+    <div class="flex items-center gap-4 px-4 py-3">
+      <div class="shrink-0 ml-auto" v-if="pageRange.length > 1">
+        <div>
+          <nav
+            class="isolate inline-flex -space-x-px rounded-md shadow-xs bg-white"
+            aria-label="Pagination"
+          >
+            <a
+              :class="canPrev ? '' : 'disabled'"
+              href="#"
+              class="relative inline-flex items-center rounded-l-md px-2 py-[9px] text-gray-400 ring-1 ring-gray-300 ring-inset hover:bg-gray-50 focus:z-20 focus:outline-offset-0"
+              @click.prevent="pageChanged(-1)"
+            >
+              <font-awesome-icon :icon="Icons.farChevronLeft" class="size-5" />
+            </a>
+
+            <a
+              v-for="page in pageRange"
+              :key="`page-${page}`"
+              href="#"
+              class="relative inline-flex items-center px-4 py-[9px] text-sm font-semibold ring-1 ring-inset"
+              :class="
+                sparkTable.params.page === page
+                  ? 'z-10 text-white bg-primary-600 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-primary-600 hover:bg-primary-600'
+                  : 'text-gray-900 hover:bg-gray-50 ring-gray-300 focus:z-20 focus:outline-offset-0'
+              "
+              @click="gotoPage(page)"
+            >
+              {{ page }}
+            </a>
+
+            <a
+              :class="canNext ? '' : 'disabled'"
+              @click.prevent="pageChanged(1)"
+              href="#"
+              class="relative inline-flex items-center rounded-r-md px-2 py-[9px] text-gray-400 ring-1 ring-gray-300 ring-inset hover:bg-gray-50 focus:z-20 focus:outline-offset-0"
+            >
+              <font-awesome-icon :icon="Icons.farChevronRight" class="size-5" />
+            </a>
+          </nav>
+        </div>
+      </div>
+    </div>
+  </div>
+</template>
+
+<script setup>
+import { computed } from 'vue'
+import { get, range } from 'lodash'
+import { Icons } from '@/plugins/fontawesome.js'
+
+const props = defineProps({
+  sparkTable: {
+    type: Object,
+    required: true,
+  },
+})
+
+const emit = defineEmits(['paginate'])
+
+const pageChanged = (change) => {
+  gotoPage(props.sparkTable.params.page + change)
+}
+const gotoPage = (targetPage) => {
+  if (targetPage < 1 || targetPage > props.sparkTable.response.meta.last_page) {
+    return
+  }
+
+  emit('paginate', {
+    page: targetPage,
+  })
+}
+
+// Range
+const lastPage = computed(() => {
+  if (!props.sparkTable.params.page) {
+    return 1
+  }
+
+  return Math.ceil(props.sparkTable.params.page / 10) * 10
+})
+const pageRange = computed(() => {
+  if (!props.sparkTable.computed.ready) {
+    return []
+  }
+
+  return range(
+    Math.floor((lastPage.value - 1) / 10) * 10 + 1,
+    lastPage.value > props.sparkTable.response.meta.last_page
+      ? props.sparkTable.response.meta.last_page + 1
+      : lastPage.value + 1,
+  )
+})
+
+// Status
+const canNext = computed(
+  () => props.sparkTable.params.page < get(props.sparkTable.response.meta, 'last_page', 1),
+)
+const canPrev = computed(() => props.sparkTable.params.page > 1)
+</script>

package/src/components/SparkTablePaginationPerPage.vue

@@ -0,0 +1,47 @@
+<template>
+  <div class="spark-table-pagination-per-page">
+    <FormKit
+      :model-value="sparkTable.params.limit"
+      type="select"
+      :options="perPageOptions"
+      outer-class="!mb-0"
+      wrapper-class="!mb-0"
+      input-class="!py-2"
+      @input="limitChanged"
+    />
+  </div>
+</template>
+
+<script setup>
+import { computed } from 'vue'
+
+const props = defineProps({
+  sparkTable: {
+    type: Object,
+    required: true,
+  },
+})
+
+const emit = defineEmits(['paginate'])
+
+// Format options for FormKit select
+const perPageOptions = computed(() => {
+  return props.sparkTable.options.perPages.map((option) => ({
+    label: String(option),
+    value: option,
+  }))
+})
+
+const limitChanged = (value) => {
+  emit('paginate', {
+    page: 1,
+    limit: parseInt(value),
+  })
+}
+</script>
+
+<style scoped>
+.spark-table-pagination-per-page {
+  @apply flex items-center;
+}
+</style>

package/src/components/SparkTableToolbar.vue

@@ -0,0 +1,33 @@
+<template>
+  <div v-if="hasContent" :class="toolbarClass">
+    <slot></slot>
+  </div>
+</template>
+
+<script setup>
+import { computed, useSlots } from 'vue'
+
+const props = defineProps({
+  position: {
+    type: String,
+    required: true,
+    validator: (value) => ['header', 'footer'].includes(value),
+  },
+})
+
+const slots = useSlots()
+
+const hasContent = computed(() => !!slots.default)
+
+const toolbarClass = computed(() => {
+  const baseClasses = 'spark-table-toolbar flex flex-wrap items-center gap-x-5 px-5 w-full'
+
+  // Footer has pagination details on left, controls on right
+  if (props.position === 'footer') {
+    return `${baseClasses} spark-table-toolbar-footer justify-between`
+  }
+
+  // Header flows left to right
+  return `${baseClasses} spark-table-toolbar-header gap-y-5 py-5`
+})
+</script>

package/src/components/index.js

@@ -7,3 +7,10 @@ export { default as SparkCard } from './SparkCard.vue'
 export { default as SparkModalContainer } from './SparkModalContainer.vue'
 export { default as SparkModalDialog } from './SparkModalDialog.vue'
 export { default as SparkOverlay } from './SparkOverlay.vue'
+export { default as SparkTable } from './SparkTable.vue'
+export { default as SparkTablePaginationPaging } from './SparkTablePaginationPaging.vue'
+export { default as SparkTablePaginationPerPage } from './SparkTablePaginationPerPage.vue'
+export { default as SparkTableToolbar } from './SparkTableToolbar.vue'
+
+// Table plugins
+export * from './plugins'

package/src/components/plugins/SparkTableDatePicker.vue

@@ -0,0 +1,122 @@
+<template>
+  <div class="spark-table-date-picker">
+    <FormKit
+      v-model="selectedDate"
+      type="datepicker"
+      :label="label"
+      :placeholder="config.placeholder || 'Select date'"
+      :overlay="true"
+      value-format="YYYY-MM-DD"
+      format="YYYY-MM-DD"
+      outer-class="!mb-0"
+      wrapper-class="!mb-0"
+      v-bind="config.formkitProps || {}"
+    />
+  </div>
+</template>
+
+<script setup>
+/**
+ * SparkTableDatePicker Plugin Component
+ *
+ * Provides a single date picker that applies date filter parameters to the SparkTable.
+ * For date ranges, use two separate datePicker plugin instances (startDate and endDate).
+ *
+ * @component
+ * @example
+ * // Single date filter
+ * const plugins = {
+ *   createdDate: {
+ *     type: 'datePicker',
+ *     enabled: true,
+ *     key: 'created_at',
+ *     label: 'Created Date',
+ *     placeholder: 'Select date',
+ *     position: 'header-right',
+ *   },
+ * }
+ *
+ * @example
+ * // Date range using two pickers
+ * const plugins = {
+ *   startDate: {
+ *     type: 'datePicker',
+ *     enabled: true,
+ *     key: 'created_at_start',
+ *     label: 'Start Date',
+ *     position: 'header-right',
+ *   },
+ *   endDate: {
+ *     type: 'datePicker',
+ *     enabled: true,
+ *     key: 'created_at_end',
+ *     label: 'End Date',
+ *     position: 'header-right',
+ *   },
+ * }
+ */
+import { ref, watch } from 'vue'
+
+/**
+ * @typedef {Object} SparkTableDatePickerConfig
+ * @property {string} type - Plugin type: 'datePicker'
+ * @property {boolean} enabled - Enable the plugin
+ * @property {string} key - Date filter key (used in query params)
+ * @property {string} [label] - Label displayed above the date picker
+ * @property {string} [placeholder='Select date'] - Placeholder text
+ * @property {string} [param] - Custom query param (defaults to filter[key])
+ * @property {string} [position='header-left'] - Toolbar position
+ * @property {Object} [formkitProps] - Additional FormKit props to pass through
+ */
+
+const props = defineProps({
+  /** SparkTable instance object */
+  sparkTable: {
+    type: Object,
+    required: true,
+  },
+  /** Date picker plugin configuration */
+  config: {
+    type: Object,
+    required: true,
+    validator: (config) => {
+      return config.key
+    },
+  },
+})
+
+const selectedDate = ref(null)
+const label = props.config.label || null
+const param = props.config.param || `filter[${props.config.key}]`
+
+// Initialize from existing params
+selectedDate.value = props.sparkTable.params[param] || null
+
+// Watch for date changes
+watch(selectedDate, (newValue) => {
+  if (newValue) {
+    props.sparkTable.methods.applyParams({
+      page: 1,
+      [param]: newValue,
+    })
+  } else {
+    props.sparkTable.methods.removeParam(param)
+  }
+})
+
+// Watch for external param changes
+watch(
+  () => props.sparkTable.params[param],
+  (newValue) => {
+    if (!newValue && selectedDate.value) {
+      selectedDate.value = null
+    }
+  },
+)
+</script>
+
+<style scoped>
+.spark-table-date-picker {
+  @apply flex items-center gap-2;
+}
+</style>