@stonecrop/atable 0.4.12 → 0.4.13

package/src/components/ATable.vue

@@ -18,7 +18,10 @@
 							v-if="column.isGantt"
 							:is="column.ganttComponent || 'AGanttCell'"
 							:store="store"
-							:color="row.gantt_color"
+							:columnsCount="store.columns.length - pinnedColumnCount"
+							:color="row.gantt?.color"
+							:start="row.gantt?.startIndex"
+							:end="row.gantt?.endIndex"
 							:colspan="column.colspan"
 							:pinned="column.pinned"
 							:rowIndex="rowIndex"
@@ -66,13 +69,13 @@
 <script setup lang="ts">
 import { vOnClickOutside } from '@vueuse/components'
 import { useMutationObserver } from '@vueuse/core'
-import { nextTick, watch, onMounted, useTemplateRef } from 'vue'
+import { nextTick, watch, onMounted, useTemplateRef, computed } from 'vue'
 
 import ARow from './ARow.vue'
 import ATableHeader from './ATableHeader.vue'
 import ATableModal from './ATableModal.vue'
 import { createTableStore } from '../stores/table'
-import type { TableColumn, TableConfig, TableRow } from '../types'
+import type { GanttDragEvent, TableColumn, TableConfig, TableRow } from '../types'
 
 const {
 	id,
@@ -91,6 +94,7 @@ const {
 const emit = defineEmits<{
 	'update:modelValue': [value: TableRow[]]
 	cellUpdate: [{ colIndex: number; rowIndex: number; newValue: any; oldValue: any }]
+	'gantt:drag': [event: GanttDragEvent]
 }>()
 
 const tableRef = useTemplateRef<HTMLTableElement>('table')
@@ -101,10 +105,31 @@ store.$onAction(({ name, store, args, after }) => {
 	if (name === 'setCellData' || name === 'setCellText') {
 		const [colIndex, rowIndex, newValue] = args
 		const oldValue = store.getCellData(colIndex, rowIndex)
-
 		after(() => {
 			emit('cellUpdate', { colIndex, rowIndex, newValue, oldValue })
 		})
+	} else if (name === 'updateGanttBar') {
+		const [event] = args
+		const ganttBar = store.rows[event.rowIndex]?.gantt
+		if (ganttBar) {
+			// only emit if the bar was actually resized or moved; check before the mutation
+			let emitDrag = false
+			if (event.type === 'resize') {
+				if (event.edge === 'start') {
+					emitDrag = ganttBar.startIndex !== event.value
+				} else if (event.edge === 'end') {
+					emitDrag = ganttBar.endIndex !== event.value
+				}
+			} else if (event.type === 'bar') {
+				emitDrag = ganttBar.startIndex !== event.start || ganttBar.endIndex !== event.end
+			}
+
+			if (emitDrag) {
+				after(() => {
+					emit('gantt:drag', event)
+				})
+			}
+		}
 	}
 })
 
@@ -127,6 +152,10 @@ onMounted(() => {
 	}
 })
 
+const pinnedColumnCount = computed(() => {
+	return store.columns.filter(column => column.pinned).length
+})
+
 const assignStickyCellWidths = () => {
 	const table = tableRef.value
 
@@ -180,25 +209,24 @@ window.addEventListener('keydown', (event: KeyboardEvent) => {
 
 const getProcessedColumnsForRow = (row: TableRow) => {
 	const isGanttRow = row.indent === 0
-	const pinnedColumnCount = store.columns.filter(column => column.pinned).length
-	if (!isGanttRow || pinnedColumnCount === 0) {
+	if (!isGanttRow || pinnedColumnCount.value === 0) {
 		return store.columns
 	}
 
 	// For Gantt views, first add the pinned columns
 	const result: TableColumn[] = []
-	for (let i = 0; i < pinnedColumnCount; i++) {
+	for (let i = 0; i < pinnedColumnCount.value; i++) {
 		const column = { ...store.columns[i] }
 		column.originalIndex = i // Preserve original index
 		result.push(column)
 	}
 
-	// Finally, add the Gantt bar column with a full-width colspan
+	// Finally, add the Gantt bar column with either a provided colspan or default to full-width colspan
 	result.push({
-		...store.columns[pinnedColumnCount],
+		...store.columns[pinnedColumnCount.value],
 		isGantt: true,
-		colspan: store.columns.length - pinnedColumnCount,
-		originalIndex: pinnedColumnCount,
+		colspan: row.gantt?.colspan || store.columns.length - pinnedColumnCount.value,
+		originalIndex: pinnedColumnCount.value,
 		width: 'auto', // TODO: refactor to API that can detect when data exists in a cell. Might have be custom and not generalizable
 	})
 

package/src/index.ts

@@ -12,6 +12,8 @@ import ATableModal from './components/ATableModal.vue'
 export { createTableStore } from './stores/table'
 export type {
 	CellContext,
+	GanttDragEvent,
+	GanttOptions,
 	TableColumn,
 	TableConfig,
 	TableDisplay,

package/src/stores/table.ts

@@ -1,7 +1,15 @@
 import { defineStore } from 'pinia'
 import { type CSSProperties, computed, ref } from 'vue'
 
-import type { CellContext, TableColumn, TableConfig, TableDisplay, TableModal, TableRow } from '../types'
+import type {
+	CellContext,
+	GanttDragEvent,
+	TableColumn,
+	TableConfig,
+	TableDisplay,
+	TableModal,
+	TableRow,
+} from '../types'
 import { generateHash } from '../utils'
 
 /**
@@ -121,7 +129,6 @@ export const createTableStore = (initData: {
 
 		const isRowGantt = (rowIndex: number) => {
 			const row = rows.value[rowIndex]
-			console.log(config.value.view, row.indent)
 			return config.value.view === 'gantt' && row.indent === 0
 		}
 
@@ -201,6 +208,23 @@ export const createTableStore = (initData: {
 			}
 		}
 
+		const updateGanttBar = (event: GanttDragEvent) => {
+			// update the local gantt bar cache
+			const ganttBar = rows.value[event.rowIndex]?.gantt
+			if (ganttBar) {
+				if (event.type === 'resize') {
+					if (event.edge === 'start') {
+						ganttBar.startIndex = event.value
+					} else if (event.edge === 'end') {
+						ganttBar.endIndex = event.value
+					}
+				} else if (event.type === 'bar') {
+					ganttBar.startIndex = event.start
+					ganttBar.endIndex = event.end
+				}
+			}
+		}
+
 		return {
 			// state
 			columns,
@@ -229,6 +253,7 @@ export const createTableStore = (initData: {
 			setCellData,
 			setCellText,
 			toggleRowExpand,
+			updateGanttBar,
 		}
 	})
 

package/src/types/index.ts

@@ -6,24 +6,77 @@ import { createTableStore } from '../stores/table'
  * Table column definition.
  * @public
  */
-export type TableColumn = {
+export interface TableColumn {
+	/**
+	 * The key of the column. This is used to identify the column in the table.
+	 */
 	name: string
 
+	/**
+	 * The alignment of the column. Possible values:
+	 * - `left` - left aligned
+	 * - `center` - center aligned
+	 * - `right` - right aligned
+	 * - `start` - aligned to the start of the column
+	 * - `end` - aligned to the end of the column
+	 *
+	 * @defaultValue 'center'
+	 */
 	align?: CanvasTextAlign
+
+	/**
+	 * Control whether cells for the column is editable.
+	 *
+	 * @defaultValue false
+	 */
 	edit?: boolean
+
+	/**
+	 * The label of the column. This is displayed in the table header.
+	 *
+	 * @defaultValue If no label is provided, a character will be assigned alphabetically,
+	 * starting from 'A' for the first column, 'B' for the second column, and so on.
+	 */
 	label?: string
+
+	/**
+	 * The data-type of the column. Possible values:
+	 * - `Data` - the column contains text data
+	 * - `Select` - the column contains a select input
+	 * - `Date` - the column contains a date input
+	 * - `component` - the column contains a custom component
+	 *
+	 * @beta
+	 */
 	type?: string
+
+	/**
+	 * The width of the column. This can be a number (in pixels) or a string (in CSS units).
+	 *
+	 * @defaultValue '40ch'
+	 */
 	width?: string
-	pinned?: boolean
 
-	// Gantt-specific fields
-	colspan?: number
-	ganttComponent?: string
-	isGantt?: boolean
-	originalIndex?: number
+	/**
+	 * Control whether the column should be pinned to the table.
+	 *
+	 * @defaultValue false
+	 */
+	pinned?: boolean
 
+	/**
+	 * The component to use to render the cell for the column. If not provided, the table will
+	 * render the default `<td>` element.
+	 */
 	cellComponent?: string
+
+	/**
+	 * Additional properties to pass to the table's cell component.
+	 *
+	 * Only applicable if the `cellComponent` property is set for the column.
+	 */
 	cellComponentProps?: Record<string, any>
+
 	/**
 	 * The component to use for the modal. If a function is provided, it will be called with the cell context.
 	 * The following properties are available on the cell context:
@@ -38,20 +91,85 @@ export type TableColumn = {
 	 * - `rowIndex` - the row index of the current cell
 	 * - `store` - the table data store
 	 */
+
 	modalComponent?: string | ((context: CellContext) => string)
+
+	/**
+	 * Additional properties to pass to the modal component.
+	 *
+	 * Only applicable if the `modalComponent` property is set for the column.
+	 */
 	modalComponentExtraProps?: Record<string, any>
 
+	/**
+	 * The format function to use to format the value of the cell. This can either be a normal or stringified
+	 * function that takes the value and the cell context and returns a string.
+	 */
 	format?: string | ((value: any, context: CellContext) => string)
+
+	/**
+	 * The masking function to use to apply an input mask to the cell. This will accept an input value and
+	 * return the masked value.
+	 */
 	mask?: (value: any) => any
+
+	/**
+	 * Whether the column is a Gantt column.
+	 *
+	 * Only applicable for Gantt tables.
+	 *
+	 * @defaultValue false
+	 */
+	isGantt?: boolean
+
+	/**
+	 * The component to use to render the Gantt bar for the column.
+	 *
+	 * Only applicable for Gantt tables.
+	 *
+	 * @defaultValue 'AGanttCell'
+	 */
+	ganttComponent?: string
+
+	/**
+	 * The colspan of the Gantt-bar for the column. This is used to determine how many columns
+	 * the Gantt-bar should span.
+	 *
+	 * Only applicable for Gantt tables.
+	 *
+	 * @defaultValue The number of columns in the table, excluding any pinned columns.
+	 */
+	colspan?: number
+
+	/**
+	 * The starting column index for the Gantt-bar, excluding any pinned columns. This is
+	 * evaluated automatically while rendering the table.
+	 *
+	 * Only applicable for Gantt tables.
+	 *
+	 * @defaultValue 0
+	 */
+	originalIndex?: number
 }
 
 /**
  * Table cell context definition.
  * @public
  */
-export type CellContext = {
+export interface CellContext {
+	/**
+	 * The row object for the current cell.
+	 */
 	row: TableRow
+
+	/**
+	 * The column object for the current cell.
+	 */
 	column: TableColumn
+
+	/**
+	 * The table object for the current cell.
+	 */
 	table: { [key: string]: any }
 }
 
@@ -59,7 +177,7 @@ export type CellContext = {
  * Table configuration definition.
  * @public
  */
-export type TableConfig = {
+export interface TableConfig {
 	/**
 	 * The type of view to display the table in. Possible values:
 	 * - `uncounted` - row numbers are not displayed in the table
@@ -68,6 +186,12 @@ export type TableConfig = {
 	 * - `tree` - carets are displayed in the number column that expand/collapse grouped rows
 	 */
 	view?: 'uncounted' | 'list' | 'list-expansion' | 'tree' | 'gantt'
+
+	/**
+	 * Control whether the table should be allowed to use the full width of its container.
+	 *
+	 * @defaultValue false
+	 */
 	fullWidth?: boolean
 }
 
@@ -75,14 +199,72 @@ export type TableConfig = {
  * Table display definition.
  * @public
  */
-export type TableDisplay = {
-	childrenOpen?: boolean
+export interface TableDisplay {
+	/**
+	 * Indicates whether a row node is expanded or collapsed.
+	 *
+	 * Only applicable for list-expansion views.
+	 *
+	 * @defaultValue false
+	 */
 	expanded?: boolean
-	indent?: number
+
+	/**
+	 * Indicates whether a row node's child nodes are open or closed.
+	 *
+	 * Only applicable for tree views.
+	 *
+	 * @defaultValue false
+	 */
+	childrenOpen?: boolean
+
+	/**
+	 * Indicates whether a row node is a parent node. This is evaluated automatically
+	 * while rendering the table.
+	 *
+	 * Only applicable for tree views.
+	 */
 	isParent?: boolean
+
+	/**
+	 * Indicates whether a row node is a root node. This is evaluated automatically
+	 * while rendering the table.
+	 *
+	 * Only applicable for tree views.
+	 */
 	isRoot?: boolean
+
+	/**
+	 * Indicates whether a row node is visible. This is evaluated automatically
+	 * while rendering the table.
+	 *
+	 * Only applicable for tree views.
+	 */
 	open?: boolean
+
+	/**
+	 * The indentation level of the row node.
+	 *
+	 * Only applicable for tree and gantt views.
+	 *
+	 * @defaultValue 0
+	 */
+	indent?: number
+
+	/**
+	 * The HTML parent element for the row node. This is evaluated automatically while rendering
+	 * the table.
+	 *
+	 * Only applicable for tree and gantt views.
+	 */
 	parent?: number
+
+	/**
+	 * Indicates whether a row node has been modified. This is evaluated automatically when a cell
+	 * is edited.
+	 *
+	 * @defaultValue false
+	 */
 	rowModified?: boolean
 }
 
@@ -90,44 +272,168 @@ export type TableDisplay = {
  * Table row definition.
  * @public
  */
-export type TableRow = {
+export interface TableRow {
+	/**
+	 * Additional arbitrary properties that can be passed to the row object.
+	 */
 	[key: string]: any
+
+	/**
+	 * The indentation level of the row node.
+	 *
+	 * Only applicable for tree and gantt views.
+	 *
+	 * @defaultValue 0
+	 */
 	indent?: number
+
+	/**
+	 * The HTML parent element for the row node. This is evaluated automatically while rendering
+	 * the table.
+	 *
+	 * Only applicable for tree and gantt views.
+	 */
 	parent?: number
 
 	/**
-	 * When a table is being viewed as a Gantt chart, this colour would be applied to the row's gantt bar, if one exists.
+	 * The options to use when rendering the row as a Gantt table.
+	 */
+	gantt?: GanttOptions
+}
+
+/**
+ * This interface defines the options for a row when it is being viewed as a Gantt chart.
+ * @public
+ */
+export interface GanttOptions {
+	/**
+	 * The colour to be applied to the row's gantt bar.
+	 */
+	color?: string
+
+	/**
+	 * The starting column index for the gantt bar.
+	 */
+	startIndex?: number
+
+	/**
+	 * The ending column index for the gantt bar. If the endIndex and colspan are not provided,
+	 * the bar will stretch to the end of the table.
+	 */
+	endIndex?: number
+
+	/**
+	 * The length of the gantt bar. Useful when only the start index is provided. If the
+	 * colspan and endIndex are not provided, the bar will stretch to the end of the table.
 	 */
-	gantt_color?: string
+	colspan?: number
 }
 
+/**
+ * Gantt table drag event definition.
+ * @public
+ */
+export type GanttDragEvent =
+	| { rowIndex: number; colIndex: number; type: 'bar'; start: number; end: number }
+	| { rowIndex: number; colIndex: number; type: 'resize'; edge: 'start' | 'end'; value: number }
+
 /**
  * Table modal definition.
  * @public
  */
-export type TableModal = {
-	bottom?: ReturnType<typeof useElementBounding>['bottom']
+export interface TableModal {
+	/**
+	 * Indicates whether the table modal is currently visible.
+	 *
+	 * @defaultValue false
+	 */
+	visible?: boolean
+
+	/**
+	 * The HTML cell element that the modal is currently being displayed for. The field is unset
+	 * when the modal is not being displayed.
+	 */
 	cell?: HTMLTableCellElement | null
-	colIndex?: number
-	event?: string
-	height?: ReturnType<typeof useElementBounding>['height']
-	left?: ReturnType<typeof useElementBounding>['left']
+
+	/**
+	 * The HTML parent element that the modal is currently being displayed for. The field is unset
+	 * when the modal is not being displayed.
+	 */
 	parent?: HTMLElement
+
+	/**
+	 * The index of the column that the modal is currently being displayed for. The field is
+	 * unset when the modal is not being displayed.
+	 */
+	colIndex?: number
+
+	/**
+	 * The index of the row that the modal is currently being displayed for. The field is
+	 * unset when the modal is not being displayed.
+	 */
 	rowIndex?: number
-	visible?: boolean
-	width?: ReturnType<typeof useElementBounding>['width']
 
+	/**
+	 * The component to use to render the modal. If not provided, the table will
+	 * try to use the column's `modalComponent` property, if set. If that is not set,
+	 * the table will not display a modal.
+	 *
+	 * @see {@link TableColumn.modalComponent}
+	 */
 	component?: string
+
+	/**
+	 * Additional properties to pass to the table's modal component.
+	 */
 	componentProps?: Record<string, any>
+
+	/**
+	 * Reactive bottom value for the modal's bounding box. The field is unset when the modal
+	 * is not being displayed.
+	 */
+	bottom?: ReturnType<typeof useElementBounding>['bottom']
+
+	/**
+	 * Reactive height value for the modal's bounding box. The field is unset when the modal
+	 * is not being displayed.
+	 */
+	height?: ReturnType<typeof useElementBounding>['height']
+
+	/**
+	 * Reactive left value for the modal's bounding box. The field is unset when the modal
+	 * is not being displayed.
+	 */
+	left?: ReturnType<typeof useElementBounding>['left']
+
+	/**
+	 * Reactive width value for the modal's bounding box. The field is unset when the modal
+	 * is not being displayed.
+	 */
+	width?: ReturnType<typeof useElementBounding>['width']
 }
 
 /**
  * Table modal component props definition.
  * @public
  */
-export type TableModalProps = {
+export interface TableModalProps {
+	/**
+	 * Additional arbitrary properties that can be passed to the modal component.
+	 */
 	[key: string]: any
+
+	/**
+	 * The index of the column that the modal is currently being displayed for.
+	 */
 	colIndex: number
+
+	/**
+	 * The index of the row that the modal is currently being displayed for.
+	 */
 	rowIndex: number
+
+	/**
+	 * The store for managing the current table's state.
+	 */
 	store: ReturnType<typeof createTableStore>
 }