@stonecrop/atable 0.24.0 → 0.26.0

package/src/components/ATable.vue

@@ -14,7 +14,7 @@
 			<tbody>
 				<slot name="body" :data="store">
 					<ARow
-						v-for="(row, filteredIndex) in store.filteredRows"
+						v-for="(row, filteredIndex) in visibleRows"
 						:key="`${row.originalIndex}-${filteredIndex}`"
 						:row="row"
 						:row-index="row.originalIndex"
@@ -57,7 +57,20 @@
 				</slot>
 			</tbody>
 
-			<slot name="footer" :data="store" />
+			<slot name="footer" :data="store" :page="pagination">
+				<ATablePaginationFooter
+					:column-count="footerColumnCount"
+					:show-footer="showFooter"
+					:has-more="hasMore"
+					:has-prev="hasPrev"
+					:has-next="hasNext"
+					:has-local-next="hasLocalNext"
+					:has-ever-had-more="hasEverHadMore"
+					:loaded-count="loadedCount"
+					:loading="paginationLoading"
+					:next="paginationNext"
+					:prev="paginationPrev" />
+			</slot>
 
 			<!-- Modal overlay -->
 			<slot name="modal" :data="store">
@@ -92,8 +105,10 @@ import AGanttConnection from './AGanttConnection.vue'
 import ARow from './ARow.vue'
 import ATableHeader from './ATableHeader.vue'
 import ATableModal from './ATableModal.vue'
+import ATablePaginationFooter from './ATablePaginationFooter.vue'
+import { useTablePagination } from '../composables/table-pagination'
 import { createTableStore } from '../stores/table'
-import type { ColumnSchema } from '@stonecrop/schema'
+import type { ColumnSchema, GetRecordsOptions, GetRecordsResult } from '@stonecrop/schema'
 
 import { schemaToColumns } from '../schemaToColumns'
 import type {
@@ -123,11 +138,15 @@ const {
 	config = new Object(),
 	schema = [],
 	linkResolver = undefined,
+	getRecords = undefined,
+	sourceKey = undefined,
 } = defineProps<{
 	id?: string
 	config?: TableConfig
 	schema?: ColumnSchema[]
 	linkResolver?: LinkResolverFn
+	getRecords?: (options?: GetRecordsOptions) => Promise<GetRecordsResult>
+	sourceKey?: string
 }>()
 
 const emit = defineEmits<{
@@ -156,6 +175,29 @@ const store = createTableStore({
 	linkResolver: linkResolver ?? injectedLinkResolver,
 })
 
+const pagination = useTablePagination({
+	rows: () => store.filteredRows,
+	pageSize: () => store.config.pageSize,
+	getRecords,
+	sourceKey: () => sourceKey,
+})
+
+const {
+	visibleRows,
+	showFooter,
+	hasMore,
+	hasPrev,
+	hasNext,
+	hasLocalNext,
+	hasEverHadMore,
+	loadedCount,
+	loading: paginationLoading,
+	next: paginationNext,
+	prev: paginationPrev,
+} = pagination
+
+const footerColumnCount = computed(() => store.columns.length + (store.zeroColumn ? 1 : 0))
+
 store.$onAction(({ name, store: storeInstance, args, after }) => {
 	if (name === 'setCellData' || name === 'setCellText') {
 		const [colIndex, rowIndex, newValue] = args
@@ -398,6 +440,7 @@ const handleRowAction = (actionType: RowActionType, rowIndex: number, event?: Mo
 
 defineExpose({
 	store,
+	pagination,
 	createConnection: store.createConnection,
 	deleteConnection: store.deleteConnection,
 	getConnectionsForBar: store.getConnectionsForBar,

package/src/components/ATableColumnFilter.vue

@@ -66,26 +66,11 @@
 
 <script setup lang="ts">
 import { ref, reactive, computed } from 'vue'
-import { componentCategory, type ComponentCategory } from '@stonecrop/schema'
 
 import { createTableStore } from '../stores/table'
+import { resolveFilterType } from '../resolveFilterType'
 import type { TableColumn } from '../types'
 
-// The filter widget is chosen by the component's semantic category.
-const CATEGORY_FILTER: Record<ComponentCategory, 'text' | 'select' | 'number' | 'date' | 'dateRange' | 'checkbox'> = {
-	text: 'text',
-	number: 'number',
-	boolean: 'checkbox',
-	date: 'date',
-	datetime: 'dateRange',
-	select: 'select',
-	code: 'text',
-	link: 'text',
-	attach: 'text',
-	quantity: 'number',
-	currency: 'number',
-}
-
 const { column, colIndex, store } = defineProps<{
 	column: TableColumn
 	colIndex: number
@@ -98,13 +83,7 @@ const dateFilter = reactive({
 	endValue: '',
 })
 
-const resolvedFilterType = computed(() => {
-	if (column.filterType) return column.filterType
-	const category = componentCategory(column.component)
-	if (category) return CATEGORY_FILTER[category]
-	// An unknown (custom) component gets the widget that can filter anything.
-	return 'text'
-})
+const resolvedFilterType = computed(() => resolveFilterType(column))
 
 const getSelectOptions = (col: TableColumn): any[] => {
 	if (col.filterOptions) return col.filterOptions

package/src/components/ATablePaginationFooter.vue

@@ -0,0 +1,100 @@
+<template>
+	<tfoot v-if="showFooter" class="atable-pagination">
+		<tr>
+			<td :colspan="columnCount">
+				<p v-if="hasMore" class="truncation-note">This is a partial list — more records exist on the server.</p>
+				<p v-else-if="showCompleteNote" class="completion-note">All {{ loadedCount }} records loaded.</p>
+				<div v-if="showControls" class="atable-pagination-controls">
+					<button type="button" class="atable-pagination-btn" :disabled="!hasPrev || loading" @click="prev">
+						Previous
+					</button>
+					<button type="button" class="atable-pagination-btn" :disabled="!hasNext || loading" @click="onNext">
+						{{ hasMore && !hasLocalNext ? 'Load more' : 'Next' }}
+					</button>
+				</div>
+			</td>
+		</tr>
+	</tfoot>
+</template>
+
+<script setup lang="ts">
+import { computed } from 'vue'
+
+const props = defineProps<{
+	columnCount: number
+	showFooter: boolean
+	hasMore: boolean
+	hasPrev: boolean
+	hasNext: boolean
+	hasLocalNext: boolean
+	hasEverHadMore: boolean
+	loadedCount: number
+	loading: boolean
+	next: () => Promise<void>
+	prev: () => void
+}>()
+
+const showCompleteNote = computed(() => !props.hasMore && props.hasEverHadMore)
+const showControls = computed(() => props.hasMore || props.hasPrev)
+
+const onNext = () => {
+	void props.next()
+}
+</script>
+
+<style scoped>
+.atable-pagination td {
+	padding: 0.75rem 0.5ch;
+	border-top: 1px solid var(--sc-row-border-color, #e0e0e0);
+}
+
+.truncation-note,
+.completion-note {
+	margin: 0 0 0.5rem;
+	font-size: var(--sc-table-font-size, 0.875rem);
+	color: var(--sc-gray-60, #666);
+}
+
+.completion-note {
+	margin-bottom: 0;
+}
+
+.atable-pagination-controls {
+	display: flex;
+	gap: 0.5rem;
+}
+
+.atable-pagination-btn {
+	appearance: none;
+	-webkit-appearance: none;
+	box-sizing: border-box;
+	padding: 0.5rem 1rem;
+	background: var(--sc-btn-color, #fafafa);
+	color: var(--sc-btn-label-color, #333333);
+	border: 1px solid var(--sc-btn-border, #cccccc);
+	border-radius: var(--sc-border-radius, 0);
+	cursor: pointer;
+	font-family: var(--sc-font-family, Arial, sans-serif);
+	font-size: var(--sc-table-font-size, 0.875rem);
+	font-weight: 400;
+	line-height: 1.2;
+	transition: background-color 0.15s ease;
+}
+
+.atable-pagination-btn:hover:not(:disabled) {
+	background: var(--sc-btn-hover, #f2f2f2);
+}
+
+.atable-pagination-btn:focus-visible {
+	outline: 2px solid var(--sc-input-active-border-color, #333333);
+	outline-offset: 1px;
+}
+
+.atable-pagination-btn:disabled {
+	cursor: not-allowed;
+	background: var(--sc-gray-5, #f2f2f2);
+	color: var(--sc-gray-50, #808080);
+	border-color: var(--sc-gray-20, #cccccc);
+	opacity: 1;
+}
+</style>

package/src/composables/table-pagination.ts

@@ -0,0 +1,172 @@
+import type { GetRecordsOptions, GetRecordsResult } from '@stonecrop/schema'
+import { computed, nextTick, ref, toValue, watch, type MaybeRefOrGetter, type Ref } from 'vue'
+
+import type { TableRow } from '../types'
+
+/**
+ * A table row after filter/sort, with its index in the held row list.
+ * @public
+ */
+export type FilteredTableRow = TableRow & { originalIndex: number }
+
+/**
+ * Options for {@link useTablePagination}.
+ * @public
+ */
+export interface UseTablePaginationOptions {
+	/** Rows after filter and sort — pagination is a window over this list, not part of filtering. */
+	rows: MaybeRefOrGetter<FilteredTableRow[]>
+	/** When set, slice the held rows into windows of this size. Omit to show the whole held list. */
+	pageSize?: MaybeRefOrGetter<number | undefined>
+	/** Fetch the next server page. Typed from schema so ATable need not import Stonecrop. */
+	getRecords?: (options?: GetRecordsOptions) => Promise<GetRecordsResult>
+	/** When this changes, refetch from offset 0. */
+	sourceKey?: MaybeRefOrGetter<string | undefined>
+}
+
+/**
+ * Pagination state and controls returned by {@link useTablePagination}.
+ * @public
+ */
+export interface TablePagination {
+	visibleRows: Ref<FilteredTableRow[]>
+	hasPrev: Ref<boolean>
+	hasNext: Ref<boolean>
+	/** Whether the server reported more records beyond what has been fetched. */
+	hasMore: Ref<boolean>
+	loading: Ref<boolean>
+	next: () => Promise<void>
+	prev: () => void
+	/** Whether footer chrome should render. */
+	showFooter: Ref<boolean>
+	/** Whether another in-memory window exists before asking the server. */
+	hasLocalNext: Ref<boolean>
+	/** Rows currently held after filter/sort — useful for a completion summary. */
+	loadedCount: Ref<number>
+	/** True once the server reported a further page existed (multi-page fetch). */
+	hasEverHadMore: Ref<boolean>
+}
+
+/**
+ * Window rows after filter/sort, and optionally walk {@link @stonecrop/schema#GetRecordsOptions} for the next page.
+ * Pagination is not a filter — pass already-filtered rows.
+ * @public
+ */
+export function useTablePagination(options: UseTablePaginationOptions): TablePagination {
+	const heldRows = computed(() => toValue(options.rows))
+	const pageSize = computed(() => toValue(options.pageSize))
+	const sourceKey = computed(() => toValue(options.sourceKey))
+
+	const windowIndex = ref(0)
+	const loading = ref(false)
+	const serverHasMore = ref(false)
+	const hasEverHadMore = ref(false)
+	const lastFetchOffset = ref(0)
+	const lastPageLength = ref(0)
+	const loadedCount = computed(() => heldRows.value.length)
+
+	const effectivePageSize = computed(() => {
+		const size = pageSize.value
+		if (size != null && size > 0) {
+			return size
+		}
+		// No pageSize: one window over everything held (server list or full child table).
+		const count = heldRows.value.length
+		return count > 0 ? count : 1
+	})
+
+	const windowCount = computed(() => Math.max(1, Math.ceil(heldRows.value.length / effectivePageSize.value)))
+
+	const visibleRows = computed(() => {
+		const start = windowIndex.value * effectivePageSize.value
+		return heldRows.value.slice(start, start + effectivePageSize.value)
+	})
+
+	const hasLocalNext = computed(() => windowIndex.value < windowCount.value - 1)
+	const hasPrev = computed(() => windowIndex.value > 0)
+	const hasNext = computed(() => hasLocalNext.value || (Boolean(options.getRecords) && serverHasMore.value))
+	const hasMore = computed(() => serverHasMore.value)
+
+	const showFooter = computed(() => {
+		if (options.getRecords) {
+			// Keep the footer after the last "Load more" so completion is visible, not silent.
+			return serverHasMore.value || hasPrev.value || loading.value || (hasEverHadMore.value && !serverHasMore.value)
+		}
+		const size = pageSize.value
+		return size != null && size > 0 && heldRows.value.length > size
+	})
+
+	const resetWindow = () => {
+		windowIndex.value = 0
+		hasEverHadMore.value = false
+	}
+
+	const fetchFromServer = async (fetchOptions?: GetRecordsOptions) => {
+		if (!options.getRecords) {
+			return
+		}
+		loading.value = true
+		try {
+			const result = await options.getRecords(fetchOptions)
+			serverHasMore.value = result.hasMore
+			if (result.hasMore) {
+				hasEverHadMore.value = true
+			}
+			lastFetchOffset.value = fetchOptions?.offset ?? 0
+			lastPageLength.value = result.data.length
+		} finally {
+			loading.value = false
+		}
+	}
+
+	watch(
+		() => sourceKey.value,
+		() => {
+			resetWindow()
+			if (options.getRecords) {
+				void fetchFromServer()
+			}
+		},
+		{ immediate: true }
+	)
+
+	watch(heldRows, () => {
+		// Shrinking the held set can leave the window past the end.
+		if (windowIndex.value >= windowCount.value) {
+			windowIndex.value = Math.max(0, windowCount.value - 1)
+		}
+	})
+
+	const next = async () => {
+		if (hasLocalNext.value) {
+			windowIndex.value += 1
+			return
+		}
+		if (options.getRecords && serverHasMore.value) {
+			await fetchFromServer({ offset: lastFetchOffset.value + lastPageLength.value })
+			await nextTick()
+			// Parent/HST grows rows; show the newly appended tail.
+			windowIndex.value = Math.max(0, windowCount.value - 1)
+		}
+	}
+
+	const prev = () => {
+		if (windowIndex.value > 0) {
+			windowIndex.value -= 1
+		}
+	}
+
+	return {
+		visibleRows,
+		hasPrev,
+		hasNext,
+		hasMore,
+		loading,
+		next,
+		prev,
+		showFooter,
+		hasLocalNext,
+		loadedCount,
+		hasEverHadMore,
+	}
+}

package/src/index.ts

@@ -9,7 +9,10 @@ import ATableHeader from './components/ATableHeader.vue'
 import ATableLoading from './components/ATableLoading.vue'
 import ATableLoadingBar from './components/ATableLoadingBar.vue'
 import ATableModal from './components/ATableModal.vue'
+import ATablePaginationFooter from './components/ATablePaginationFooter.vue'
 export { createTableStore } from './stores/table'
+export { useTablePagination } from './composables/table-pagination'
+export type { FilteredTableRow, TablePagination, UseTablePaginationOptions } from './composables/table-pagination'
 export type { FilterState, FilterStateRecord } from './stores/table'
 export type * from './types'
 export { schemaToColumns } from './schemaToColumns'
@@ -41,6 +44,7 @@ function install(app: App /* options */) {
 	app.component('ATableLoading', ATableLoading)
 	app.component('ATableLoadingBar', ATableLoadingBar)
 	app.component('ATableModal', ATableModal)
+	app.component('ATablePaginationFooter', ATablePaginationFooter)
 }
 
 export {
@@ -53,5 +57,6 @@ export {
 	ATableLoading,
 	ATableLoadingBar,
 	ATableModal,
+	ATablePaginationFooter,
 	install,
 }

package/src/linkSearchableText.ts

@@ -0,0 +1,42 @@
+/**
+ * Normalize a scalar cell value to a non-empty string, or nothing.
+ *
+ * Rejecting objects is what the haystack wants: a nested value has no single textual form, and
+ * `String()` on one contributes `[object Object]`, which matches a search for "object" and nothing
+ * a user would actually type.
+ */
+function scalarText(value: unknown): string | undefined {
+	if (value == null || typeof value === 'object') return undefined
+	if (typeof value === 'string') return value === '' ? undefined : value
+	if (typeof value === 'number' || typeof value === 'boolean' || typeof value === 'bigint') {
+		return String(value)
+	}
+	return undefined
+}
+
+/**
+ * Build the substring-search haystack for a link column cell.
+ * Server middleware enriches inline FKs to `{ id, displayText }`; search both.
+ * @public
+ */
+export function linkSearchableText(cellValue: unknown): string {
+	if (cellValue == null || cellValue === '') return ''
+
+	// `in` rather than an assertion to `Record<string, unknown>`: the assertion claims the value has
+	// string keys of unknown type, which is narrower than `object` and so is a claim this function
+	// cannot make about a cell it did not build.
+	if (typeof cellValue === 'object') {
+		const parts: string[] = []
+		if ('id' in cellValue) {
+			const id = scalarText(cellValue.id)
+			if (id !== undefined) parts.push(id)
+		}
+		if ('displayText' in cellValue) {
+			const displayText = scalarText(cellValue.displayText)
+			if (displayText !== undefined) parts.push(displayText)
+		}
+		return parts.join(' ')
+	}
+
+	return scalarText(cellValue) ?? ''
+}

package/src/resolveFilterType.ts

@@ -0,0 +1,32 @@
+import { componentCategory, type ComponentCategory } from '@stonecrop/schema'
+
+import type { TableColumn } from './types'
+
+/** Filter widget type derived from a component's semantic category. */
+export type ResolvedFilterType = 'text' | 'select' | 'number' | 'date' | 'dateRange' | 'checkbox' | 'component'
+
+const CATEGORY_FILTER: Record<ComponentCategory, Exclude<ResolvedFilterType, 'component'>> = {
+	text: 'text',
+	number: 'number',
+	boolean: 'checkbox',
+	date: 'date',
+	datetime: 'dateRange',
+	select: 'select',
+	code: 'text',
+	link: 'text',
+	attach: 'text',
+	quantity: 'number',
+	currency: 'number',
+}
+
+/**
+ * Resolve the filter widget and filter logic type for a column.
+ * Explicit `filterType` wins; otherwise derive from the component category.
+ * @public
+ */
+export function resolveFilterType(column: Pick<TableColumn, 'filterType' | 'component'>): ResolvedFilterType {
+	if (column.filterType) return column.filterType
+	const category = componentCategory(column.component)
+	if (category) return CATEGORY_FILTER[category]
+	return 'text'
+}

package/src/stores/table.ts

@@ -3,6 +3,7 @@ import { componentCategory } from '@stonecrop/schema'
 import type { BadgeDescriptor } from '@stonecrop/schema'
 import { type CSSProperties, computed, ref } from 'vue'
 
+import { linkSearchableText } from '../linkSearchableText'
 import type {
 	CellContext,
 	ConnectionHandle,
@@ -15,6 +16,7 @@ import type {
 	TableModal,
 	TableRow,
 } from '../types'
+import { resolveFilterType } from '../resolveFilterType'
 import { formatCurrency, formatQuantity, generateHash } from '../utils'
 
 /**
@@ -77,15 +79,16 @@ function isNodeOpen(rowIndex: number, treeDisplay: TableDisplay[]): boolean {
 }
 
 function applyFilter(cellValue: any, filter: FilterState, column: TableColumn): boolean {
-	const filterType = column.filterType || 'text'
+	const filterType = resolveFilterType(column)
 	const value = filter.value
 
 	if (!value && filterType !== 'dateRange' && filterType !== 'checkbox') return true
 
 	switch (filterType) {
 		case 'text': {
-			const searchableText =
-				typeof cellValue === 'object' && cellValue !== null
+			const searchableText = column.linkDoctype
+				? linkSearchableText(cellValue)
+				: typeof cellValue === 'object' && cellValue !== null
 					? Object.values(cellValue).join(' ')
 					: String(cellValue || '')
 			return searchableText.toLowerCase().includes(String(value).toLowerCase())
@@ -360,7 +363,7 @@ export const createTableStore = (initData: {
 					filter.value ||
 					filter.startValue ||
 					filter.endValue ||
-					(column.filterType === 'checkbox' && filter.value !== undefined)
+					(resolveFilterType(column) === 'checkbox' && filter.value !== undefined)
 
 				if (!hasFilterValue) return
 

package/src/types/index.ts

@@ -205,6 +205,12 @@ export interface BaseTableConfig {
 	 * Configuration for row-level actions (add, delete, duplicate, etc.).
 	 */
 	rowActions?: RowActionsConfig
+
+	/**
+	 * When set, slice the held rows into in-memory windows of this size.
+	 * Omit to show the whole held list as one window (server paging uses the backend cap).
+	 */
+	pageSize?: number
 }
 
 /**