@wishbone-media/spark 0.21.0 → 0.23.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wishbone-media/spark",
-  "version": "0.21.0",
+  "version": "0.23.0",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",

package/src/assets/css/spark-table.css

@@ -9,6 +9,19 @@
   --ht-header-highlighted-background-color: transparent;
 }
 
+.spark-table .handsontable td.current {
+  @apply relative;
+
+  &::before {
+    @apply absolute opacity-[0.14] content-[''] inset-0 bg-[var(--ht-cell-selection-background-color,#1a42e8)];
+  }
+}
+
+.spark-table .handsontable tr.ht__row_odd:hover td,
+.spark-table .handsontable tr.ht__row_even:hover td {
+  @apply !bg-gray-100;
+}
+
 .spark-table .ht_master .wtBorder {
   @apply !hidden;
 }

package/src/components/SparkTable.vue

@@ -355,6 +355,29 @@ const sparkTable = reactive({
         }
         return stretchedWidth
       },
+      /**
+       * Copy displayed cell content instead of raw data values
+       * This ensures custom renderers copy their visual output, not the underlying data
+       */
+      beforeCopy: (data, coords) => {
+        const hot = table.value?.hotInstance
+        if (!hot) return
+
+        coords.forEach((range) => {
+          for (let row = range.startRow; row <= range.endRow; row++) {
+            for (let col = range.startCol; col <= range.endCol; col++) {
+              const td = hot.getCell(row, col)
+              if (td) {
+                const dataRow = row - coords[0].startRow
+                const dataCol = col - coords[0].startCol
+                // Prefer data-copy-value (for renderers like boolean with icons)
+                // Fall back to textContent for standard rendered content
+                data[dataRow][dataCol] = td.dataset.copyValue ?? td.textContent ?? ''
+              }
+            }
+          }
+        })
+      },
     },
     ...props.settings,
   })),

package/src/utils/formatTemporal.js

@@ -0,0 +1,335 @@
+/**
+ * Format Temporal objects using Day.js-compatible format strings
+ *
+ * Uses native Temporal API and Intl.DateTimeFormat under the hood.
+ * Zero external dependencies.
+ *
+ * @see https://day.js.org/docs/en/display/format for format token reference
+ *
+ * Supported tokens:
+ * | Token | Output        | Description                     |
+ * |-------|---------------|---------------------------------|
+ * | YYYY  | 2018          | Four-digit year                 |
+ * | YY    | 18            | Two-digit year                  |
+ * | MMMM  | January       | Full month name                 |
+ * | MMM   | Jan           | Abbreviated month name          |
+ * | MM    | 01-12         | Month, 2-digits                 |
+ * | M     | 1-12          | Month                           |
+ * | DD    | 01-31         | Day of month, 2-digits          |
+ * | D     | 1-31          | Day of month                    |
+ * | Do    | 1st, 2nd, 3rd | Day of month with ordinal       |
+ * | dddd  | Sunday        | Full weekday name               |
+ * | ddd   | Sun           | Abbreviated weekday name        |
+ * | dd    | Su            | Min weekday name (2 chars)      |
+ * | d     | 0-6           | Day of week (0 = Sunday)        |
+ * | HH    | 00-23         | Hour (24-hour), 2-digits        |
+ * | H     | 0-23          | Hour (24-hour)                  |
+ * | hh    | 01-12         | Hour (12-hour), 2-digits        |
+ * | h     | 1-12          | Hour (12-hour)                  |
+ * | kk    | 01-24         | Hour (1-24), 2-digits           |
+ * | k     | 1-24          | Hour (1-24)                     |
+ * | mm    | 00-59         | Minute, 2-digits                |
+ * | m     | 0-59          | Minute                          |
+ * | ss    | 00-59         | Second, 2-digits                |
+ * | s     | 0-59          | Second                          |
+ * | SSS   | 000-999       | Milliseconds, 3-digits          |
+ * | A     | AM/PM         | Meridiem uppercase              |
+ * | a     | am/pm         | Meridiem lowercase              |
+ * | Z     | +05:00        | UTC offset with colon           |
+ * | ZZ    | +0500         | UTC offset without colon        |
+ * | Q     | 1-4           | Quarter                         |
+ * | X     | 1360013296    | Unix timestamp (seconds)        |
+ * | x     | 1360013296123 | Unix timestamp (milliseconds)   |
+ *
+ * Escape characters by wrapping in square brackets: [MM] outputs "MM"
+ *
+ * @example
+ * formatTemporal(temporal, 'YYYY-MM-DD')           // "2025-12-03"
+ * formatTemporal(temporal, 'DD MMM YYYY, HH:mm')   // "03 Dec 2025, 11:36"
+ * formatTemporal(temporal, 'dddd, MMMM Do YYYY')   // "Wednesday, December 3rd 2025"
+ * formatTemporal(temporal, '[Today is] dddd')      // "Today is Wednesday"
+ */
+
+/**
+ * Get ordinal suffix for a number (1st, 2nd, 3rd, 4th, etc.)
+ * @param {number} n
+ * @returns {string}
+ */
+const getOrdinal = (n) => {
+  const s = ['th', 'st', 'nd', 'rd']
+  const v = n % 100
+  return n + (s[(v - 20) % 10] || s[v] || s[0])
+}
+
+/**
+ * Pad a number with leading zeros
+ * @param {number} n
+ * @param {number} length
+ * @returns {string}
+ */
+const pad = (n, length = 2) => String(n).padStart(length, '0')
+
+/**
+ * Create a cached Intl.DateTimeFormat formatter
+ * @param {string} locale
+ * @param {Intl.DateTimeFormatOptions} options
+ * @returns {Intl.DateTimeFormat}
+ */
+const formatterCache = new Map()
+const getFormatter = (locale, options) => {
+  const key = `${locale}:${JSON.stringify(options)}`
+  if (!formatterCache.has(key)) {
+    formatterCache.set(key, new Intl.DateTimeFormat(locale, options))
+  }
+  return formatterCache.get(key)
+}
+
+/**
+ * Get formatted part from Intl.DateTimeFormat
+ * @param {Date} date
+ * @param {string} locale
+ * @param {Intl.DateTimeFormatOptions} options
+ * @param {string} type - The part type to extract
+ * @returns {string}
+ */
+const getFormattedPart = (date, locale, options, type) => {
+  const formatter = getFormatter(locale, options)
+  const parts = formatter.formatToParts(date)
+  const part = parts.find(p => p.type === type)
+  return part ? part.value : ''
+}
+
+/**
+ * Convert Temporal object to Date for Intl formatting
+ * @param {Temporal.PlainDateTime|Temporal.ZonedDateTime|Temporal.Instant} temporal
+ * @returns {Date}
+ */
+const temporalToDate = (temporal) => {
+  if (temporal.epochMilliseconds !== undefined) {
+    // ZonedDateTime or Instant
+    return new Date(temporal.epochMilliseconds)
+  }
+  // PlainDateTime - treat as local time
+  return new Date(
+    temporal.year,
+    temporal.month - 1,
+    temporal.day,
+    temporal.hour || 0,
+    temporal.minute || 0,
+    temporal.second || 0,
+    temporal.millisecond || 0
+  )
+}
+
+/**
+ * Extract time components from a Temporal object
+ * @param {Temporal.PlainDateTime|Temporal.ZonedDateTime} temporal
+ * @returns {Object}
+ */
+const getTemporalComponents = (temporal) => {
+  const hour24 = temporal.hour || 0
+  const hour12 = hour24 % 12 || 12
+  const isPM = hour24 >= 12
+
+  return {
+    year: temporal.year,
+    month: temporal.month,
+    day: temporal.day,
+    hour24,
+    hour12,
+    hourFrom1: hour24 === 0 ? 24 : hour24, // k format (1-24)
+    minute: temporal.minute || 0,
+    second: temporal.second || 0,
+    millisecond: temporal.millisecond || 0,
+    dayOfWeek: temporal.dayOfWeek, // 1=Monday, 7=Sunday in Temporal
+    isPM,
+    quarter: Math.ceil(temporal.month / 3),
+  }
+}
+
+/**
+ * Get timezone offset string
+ * @param {Temporal.ZonedDateTime} temporal
+ * @param {boolean} withColon
+ * @returns {string}
+ */
+const getTimezoneOffset = (temporal, withColon = true) => {
+  if (!temporal.offsetNanoseconds && temporal.offsetNanoseconds !== 0) {
+    return ''
+  }
+
+  const offsetMinutes = Math.round(temporal.offsetNanoseconds / 60_000_000_000)
+  const sign = offsetMinutes >= 0 ? '+' : '-'
+  const absMinutes = Math.abs(offsetMinutes)
+  const hours = Math.floor(absMinutes / 60)
+  const minutes = absMinutes % 60
+
+  if (withColon) {
+    return `${sign}${pad(hours)}:${pad(minutes)}`
+  }
+  return `${sign}${pad(hours)}${pad(minutes)}`
+}
+
+/**
+ * Token definitions with their replacement functions
+ * Order matters - longer tokens must be matched first
+ */
+const createTokens = (temporal, locale) => {
+  const comp = getTemporalComponents(temporal)
+  const date = temporalToDate(temporal)
+
+  // Convert Temporal dayOfWeek (1=Mon, 7=Sun) to JS dayOfWeek (0=Sun, 6=Sat)
+  const jsDayOfWeek = comp.dayOfWeek === 7 ? 0 : comp.dayOfWeek
+
+  return [
+    // Year
+    ['YYYY', () => String(comp.year)],
+    ['YY', () => String(comp.year).slice(-2)],
+
+    // Month
+    ['MMMM', () => getFormattedPart(date, locale, { month: 'long' }, 'month')],
+    ['MMM', () => getFormattedPart(date, locale, { month: 'short' }, 'month')],
+    ['MM', () => pad(comp.month)],
+    ['M', () => String(comp.month)],
+
+    // Day of month
+    ['DD', () => pad(comp.day)],
+    ['Do', () => getOrdinal(comp.day)],
+    ['D', () => String(comp.day)],
+
+    // Day of week
+    ['dddd', () => getFormattedPart(date, locale, { weekday: 'long' }, 'weekday')],
+    ['ddd', () => getFormattedPart(date, locale, { weekday: 'short' }, 'weekday')],
+    ['dd', () => getFormattedPart(date, locale, { weekday: 'short' }, 'weekday').slice(0, 2)],
+    ['d', () => String(jsDayOfWeek)],
+
+    // Hour
+    ['HH', () => pad(comp.hour24)],
+    ['H', () => String(comp.hour24)],
+    ['hh', () => pad(comp.hour12)],
+    ['h', () => String(comp.hour12)],
+    ['kk', () => pad(comp.hourFrom1)],
+    ['k', () => String(comp.hourFrom1)],
+
+    // Minute
+    ['mm', () => pad(comp.minute)],
+    ['m', () => String(comp.minute)],
+
+    // Second
+    ['ss', () => pad(comp.second)],
+    ['s', () => String(comp.second)],
+
+    // Millisecond
+    ['SSS', () => pad(comp.millisecond, 3)],
+
+    // AM/PM
+    ['A', () => comp.isPM ? 'PM' : 'AM'],
+    ['a', () => comp.isPM ? 'pm' : 'am'],
+
+    // Timezone offset
+    ['ZZ', () => getTimezoneOffset(temporal, false)],
+    ['Z', () => getTimezoneOffset(temporal, true)],
+
+    // Quarter
+    ['Q', () => String(comp.quarter)],
+
+    // Unix timestamp
+    ['x', () => String(temporal.epochMilliseconds ?? date.getTime())],
+    ['X', () => String(Math.floor((temporal.epochMilliseconds ?? date.getTime()) / 1000))],
+  ]
+}
+
+/**
+ * Format a Temporal object using a Day.js-compatible format string
+ *
+ * @param {Temporal.PlainDateTime|Temporal.ZonedDateTime|Temporal.Instant|string} input - Temporal object or ISO string
+ * @param {string} formatStr - Day.js-compatible format string
+ * @param {Object} [options={}] - Options
+ * @param {string} [options.locale='en-US'] - Locale for month/weekday names
+ * @returns {string} Formatted date string
+ */
+export const formatTemporal = (input, formatStr, options = {}) => {
+  const { locale = 'en-US' } = options
+
+  if (!input) {
+    return ''
+  }
+
+  // Handle string input - parse as PlainDateTime
+  let temporal = input
+  if (typeof input === 'string') {
+    try {
+      // Try parsing as ZonedDateTime first, then PlainDateTime
+      if (input.includes('[') || input.includes('Z') || /[+-]\d{2}:\d{2}$/.test(input)) {
+        temporal = Temporal.ZonedDateTime.from(input)
+      } else {
+        // Handle "YYYY-MM-DD HH:mm:ss" format (common from APIs)
+        const normalized = input.replace(' ', 'T')
+        temporal = Temporal.PlainDateTime.from(normalized)
+      }
+    } catch (e) {
+      console.error('Failed to parse date string:', input, e)
+      return input
+    }
+  }
+
+  const tokens = createTokens(temporal, locale)
+
+  // Build regex pattern for all tokens, including escaped sequences
+  // Escaped sequences: [anything] should be preserved literally
+  const tokenPattern = tokens.map(([token]) => token).join('|')
+  const regex = new RegExp(`\\[([^\\]]+)\\]|(${tokenPattern})`, 'g')
+
+  return formatStr.replace(regex, (match, escaped, token) => {
+    // If it's an escaped sequence, return the content without brackets
+    if (escaped !== undefined) {
+      return escaped
+    }
+
+    // Find and execute the token replacement
+    const tokenDef = tokens.find(([t]) => t === token)
+    if (tokenDef) {
+      return tokenDef[1]()
+    }
+
+    return match
+  })
+}
+
+/**
+ * Parse a datetime string (e.g., from Laravel API) and optionally convert timezone
+ *
+ * @param {string} dateString - Date string like "2025-12-03 11:36:27"
+ * @param {Object} [options={}] - Options
+ * @param {string} [options.fromTimezone] - Source timezone (e.g., 'UTC')
+ * @param {string} [options.toTimezone] - Target timezone (e.g., 'Australia/Sydney')
+ * @returns {Temporal.PlainDateTime|Temporal.ZonedDateTime} Temporal object
+ */
+export const parseDatetime = (dateString, options = {}) => {
+  const { fromTimezone, toTimezone } = options
+
+  if (!dateString) {
+    return null
+  }
+
+  // Normalize "YYYY-MM-DD HH:mm:ss" to "YYYY-MM-DDTHH:mm:ss"
+  const normalized = dateString.replace(' ', 'T')
+
+  // If timezone conversion is requested
+  if (fromTimezone && toTimezone) {
+    // Parse as ZonedDateTime in the source timezone
+    const zoned = Temporal.PlainDateTime.from(normalized).toZonedDateTime(fromTimezone)
+    // Convert to target timezone
+    return zoned.withTimeZone(toTimezone)
+  }
+
+  if (fromTimezone) {
+    // Just attach the source timezone
+    return Temporal.PlainDateTime.from(normalized).toZonedDateTime(fromTimezone)
+  }
+
+  // Return as PlainDateTime (no timezone info)
+  return Temporal.PlainDateTime.from(normalized)
+}
+
+export default formatTemporal

package/src/utils/index.js

@@ -2,3 +2,4 @@ export * from './cookies.js'
 export { customiseHeader } from './sparkTable/header.js'
 export { renderHeaderTitle } from './sparkTable/header-title.js'
 export { updateRow } from './sparkTable/update-row.js'
+export { formatTemporal, parseDatetime } from './formatTemporal.js'

package/src/utils/sparkTable/renderers/boolean.js

@@ -70,6 +70,9 @@ export const booleanRenderer = (sparkTable) => {
 
     const colors = colorClasses[colorName] || colorClasses.gray
 
+    // Store the boolean value for copy/paste (since icon has no text content)
+    td.dataset.copyValue = truthy ? 'true' : 'false'
+
     // Create circular container
     const container = document.createElement('div')
     container.classList.add(

package/src/utils/sparkTable/renderers/currency.js

@@ -0,0 +1,71 @@
+/**
+ * Spark Currency Renderer
+ *
+ * Formats numbers as Australian currency with dollar sign and comma separators.
+ *
+ * Usage:
+ * {
+ *   data: 'total',
+ *   renderer: 'spark.currency',
+ *   rendererConfig: {
+ *     decimals: 2,          // Decimal places (default: 2)
+ *     emptyText: '-',       // Text for null/empty values (default: '')
+ *   }
+ * }
+ *
+ * Examples:
+ * - 1234.5    → "$1,234.50"
+ * - 1000000   → "$1,000,000.00"
+ * - -500      → "-$500.00"
+ * - null      → ""
+ */
+
+/**
+ * Format a number as Australian currency
+ * @param {number} value
+ * @param {number} decimals
+ * @returns {string}
+ */
+const formatCurrency = (value, decimals = 2) => {
+  const num = Number(value)
+  if (isNaN(num)) return null
+
+  const isNegative = num < 0
+  const absValue = Math.abs(num)
+
+  // Format with commas and decimals
+  const formatted = absValue.toLocaleString('en-AU', {
+    minimumFractionDigits: decimals,
+    maximumFractionDigits: decimals,
+  })
+
+  // Add dollar sign (after negative sign if negative)
+  return isNegative ? `-$${formatted}` : `$${formatted}`
+}
+
+export const currencyRenderer = (sparkTable) => {
+  return (instance, td, row, col, prop, value, cellProperties) => {
+    td.innerHTML = ''
+    td.classList.add('spark-table-cell-currency')
+
+    const config = cellProperties.rendererConfig || {}
+    const { decimals = 2, emptyText = '' } = config
+
+    // Handle null/empty values
+    if (value === null || value === undefined || value === '') {
+      td.textContent = emptyText
+      return
+    }
+
+    const formatted = formatCurrency(value, decimals)
+
+    if (formatted === null) {
+      td.textContent = emptyText
+      return
+    }
+
+    const span = document.createElement('span')
+    span.textContent = formatted
+    td.appendChild(span)
+  }
+}

package/src/utils/sparkTable/renderers/datetime.js

@@ -0,0 +1,106 @@
+import { formatTemporal, parseDatetime } from '@/utils/formatTemporal.js'
+
+/**
+ * Spark DateTime Renderer
+ *
+ * Renders datetime values with customizable formatting and timezone conversion.
+ * Uses native Temporal API with Day.js-compatible format strings.
+ *
+ * Input format: "2025-12-03 11:36:27" (typical Laravel API datetime) or null
+ *
+ * Usage:
+ * {
+ *   data: 'created_at',
+ *   renderer: 'spark.datetime',
+ *   rendererConfig: {
+ *     format: 'DD MMM YYYY, HH:mm',     // Day.js-compatible format string
+ *     fromTimezone: 'UTC',               // Source timezone (optional)
+ *     toTimezone: 'Australia/Sydney',    // Target timezone (optional)
+ *     locale: 'en-AU',                   // Locale for month/weekday names (optional)
+ *     emptyText: '-',                    // Text to show for null/empty values (optional)
+ *   }
+ * }
+ *
+ * Format tokens (Day.js-compatible):
+ * | Token | Output        | Description                     |
+ * |-------|---------------|---------------------------------|
+ * | YYYY  | 2018          | Four-digit year                 |
+ * | YY    | 18            | Two-digit year                  |
+ * | MMMM  | January       | Full month name                 |
+ * | MMM   | Jan           | Abbreviated month name          |
+ * | MM    | 01-12         | Month, 2-digits                 |
+ * | M     | 1-12          | Month                           |
+ * | DD    | 01-31         | Day of month, 2-digits          |
+ * | D     | 1-31          | Day of month                    |
+ * | Do    | 1st, 2nd      | Day of month with ordinal       |
+ * | dddd  | Sunday        | Full weekday name               |
+ * | ddd   | Sun           | Abbreviated weekday name        |
+ * | dd    | Su            | Min weekday name (2 chars)      |
+ * | d     | 0-6           | Day of week (0 = Sunday)        |
+ * | HH    | 00-23         | Hour (24-hour), 2-digits        |
+ * | H     | 0-23          | Hour (24-hour)                  |
+ * | hh    | 01-12         | Hour (12-hour), 2-digits        |
+ * | h     | 1-12          | Hour (12-hour)                  |
+ * | mm    | 00-59         | Minute, 2-digits                |
+ * | m     | 0-59          | Minute                          |
+ * | ss    | 00-59         | Second, 2-digits                |
+ * | s     | 0-59          | Second                          |
+ * | SSS   | 000-999       | Milliseconds, 3-digits          |
+ * | A     | AM/PM         | Meridiem uppercase              |
+ * | a     | am/pm         | Meridiem lowercase              |
+ * | Z     | +05:00        | UTC offset with colon           |
+ * | ZZ    | +0500         | UTC offset without colon        |
+ *
+ * Escape characters by wrapping in square brackets: [at] outputs "at"
+ *
+ * Examples:
+ * - 'DD MMM YYYY, HH:mm'     → "03 Dec 2025, 11:36"
+ * - 'YYYY-MM-DD'             → "2025-12-03"
+ * - 'dddd, MMMM Do YYYY'     → "Wednesday, December 3rd 2025"
+ * - 'h:mm A'                 → "11:36 AM"
+ * - 'DD/MM/YY [at] h:mma'    → "03/12/25 at 11:36am"
+ */
+
+export const datetimeRenderer = (sparkTable) => {
+  return (instance, td, row, col, prop, value, cellProperties) => {
+    // Clear cell
+    td.innerHTML = ''
+    td.classList.add('spark-table-cell-datetime')
+
+    const config = cellProperties.rendererConfig || {}
+    const {
+      format = 'DD MMM YYYY, HH:mm',
+      fromTimezone,
+      toTimezone,
+      locale = 'en-US',
+      emptyText = '',
+    } = config
+
+    // Handle null/empty values
+    if (!value) {
+      td.textContent = emptyText
+      return
+    }
+
+    try {
+      // Parse the datetime string and optionally convert timezone
+      const temporal = parseDatetime(value, { fromTimezone, toTimezone })
+
+      if (!temporal) {
+        td.textContent = emptyText
+        return
+      }
+
+      // Format using Day.js-compatible format string
+      const formatted = formatTemporal(temporal, format, { locale })
+
+      const span = document.createElement('span')
+      span.textContent = formatted
+      td.appendChild(span)
+    } catch (error) {
+      console.error('Error formatting datetime:', error, { value, format })
+      // Fall back to showing the raw value
+      td.textContent = value
+    }
+  }
+}

package/src/utils/sparkTable/renderers/index.js

@@ -2,9 +2,11 @@ import { baseRenderer, registerRenderer } from 'handsontable/renderers'
 import { actionsRenderer } from './actions.js'
 import { badgeRenderer } from './badge.js'
 import { booleanRenderer } from './boolean.js'
+import { currencyRenderer } from './currency.js'
 import { linkRenderer } from './link.js'
 import { imageRenderer } from './image.js'
 import { dateRenderer } from './date.js'
+import { datetimeRenderer } from './datetime.js'
 
 /**
  * Renderer Registry for SparkTable
@@ -52,9 +54,11 @@ export const getRenderer = (key) => {
  * - spark.actions: Inline action buttons
  * - spark.badge: Colored status badges
  * - spark.boolean: Boolean indicators with check/times icons
+ * - spark.currency: Australian currency formatting
  * - spark.link: Clickable links (email, phone, custom)
  * - spark.image: Image thumbnails
  * - spark.date: Formatted dates
+ * - spark.datetime: Advanced datetime formatting with timezone support
  * - style.capitalize: Legacy renderer for text capitalization
  *
  * @param {Object} sparkTable - SparkTable instance
@@ -64,9 +68,11 @@ export const registerSparkRenderers = (sparkTable) => {
   register('spark.actions', actionsRenderer(sparkTable))
   register('spark.badge', badgeRenderer(sparkTable))
   register('spark.boolean', booleanRenderer(sparkTable))
+  register('spark.currency', currencyRenderer(sparkTable))
   register('spark.link', linkRenderer(sparkTable))
   register('spark.image', imageRenderer(sparkTable))
   register('spark.date', dateRenderer(sparkTable))
+  register('spark.datetime', datetimeRenderer(sparkTable))
 
   // Legacy renderer for backward compatibility
   register('style.capitalize', (instance, td, row, col, prop, value) => {