@htlkg/components 0.0.2 → 0.0.4

package/src/data/columnHelpers.ts

@@ -0,0 +1,503 @@
+/**
+ * Column Definition Helpers
+ *
+ * Pre-built column definitions for common patterns, reducing boilerplate
+ * when defining DataTable columns.
+ */
+
+import type { DataTableColumn } from "./DataTable.vue";
+
+/**
+ * Date formatting options
+ */
+export interface DateFormatOptions {
+	format?: "short" | "medium" | "long" | "full";
+	locale?: string;
+}
+
+/**
+ * Tag color function type
+ */
+export type TagColorFn<T> = (item: T) => string;
+
+/**
+ * Pre-built column helpers
+ */
+export const columns = {
+	/**
+	 * Simple text column
+	 *
+	 * @example
+	 * columns.text('name', 'Name')
+	 */
+	text: <T = any>(key: string, label: string, options?: { sortable?: boolean; width?: string }): DataTableColumn<T> => ({
+		key,
+		label,
+		type: "text",
+		sortable: options?.sortable ?? true,
+		width: options?.width,
+	}),
+
+	/**
+	 * Number column with locale formatting
+	 *
+	 * @example
+	 * columns.number('amount', 'Amount')
+	 * columns.number('price', 'Price', { prefix: '$', decimals: 2 })
+	 */
+	number: <T = any>(
+		key: string,
+		label: string,
+		options?: { prefix?: string; suffix?: string; decimals?: number; sortable?: boolean }
+	): DataTableColumn<T> => ({
+		key,
+		label,
+		type: "number",
+		sortable: options?.sortable ?? true,
+		render: (item: any) => {
+			const value = item[key];
+			if (value === null || value === undefined) return "";
+
+			const formatted =
+				options?.decimals !== undefined
+					? Number(value).toLocaleString(undefined, {
+							minimumFractionDigits: options.decimals,
+							maximumFractionDigits: options.decimals,
+						})
+					: Number(value).toLocaleString();
+
+			return `${options?.prefix ?? ""}${formatted}${options?.suffix ?? ""}`;
+		},
+	}),
+
+	/**
+	 * Date column with formatting
+	 *
+	 * @example
+	 * columns.date('createdAt', 'Created')
+	 * columns.date('updatedAt', 'Updated', { format: 'long' })
+	 */
+	date: <T = any>(key: string, label: string, options?: DateFormatOptions & { sortable?: boolean }): DataTableColumn<T> => ({
+		key,
+		label,
+		type: "date",
+		sortable: options?.sortable ?? true,
+		render: (item: any) => {
+			const value = item[key];
+			if (!value) return "";
+
+			const date = value instanceof Date ? value : new Date(value);
+			if (Number.isNaN(date.getTime())) return "";
+
+			const formatOptions: Intl.DateTimeFormatOptions = {
+				short: { dateStyle: "short" },
+				medium: { dateStyle: "medium" },
+				long: { dateStyle: "long" },
+				full: { dateStyle: "full" },
+			}[options?.format ?? "medium"] as Intl.DateTimeFormatOptions;
+
+			return date.toLocaleDateString(options?.locale, formatOptions);
+		},
+	}),
+
+	/**
+	 * DateTime column with formatting
+	 *
+	 * @example
+	 * columns.dateTime('createdAt', 'Created At')
+	 */
+	dateTime: <T = any>(key: string, label: string, options?: { sortable?: boolean; locale?: string }): DataTableColumn<T> => ({
+		key,
+		label,
+		type: "date",
+		sortable: options?.sortable ?? true,
+		render: (item: any) => {
+			const value = item[key];
+			if (!value) return "";
+
+			const date = value instanceof Date ? value : new Date(value);
+			if (Number.isNaN(date.getTime())) return "";
+
+			return date.toLocaleString(options?.locale, {
+				dateStyle: "medium",
+				timeStyle: "short",
+			});
+		},
+	}),
+
+	/**
+	 * Tag column with optional color function
+	 *
+	 * @example
+	 * columns.tag('status', 'Status')
+	 * columns.tag('status', 'Status', (item) => item.active ? 'green' : 'red')
+	 */
+	tag: <T = any>(key: string, label: string, colorFn?: TagColorFn<T>, options?: { sortable?: boolean }): DataTableColumn<T> => ({
+		key,
+		label,
+		type: "tag",
+		sortable: options?.sortable ?? true,
+		render: (item: T) => {
+			const value = (item as any)[key];
+			return {
+				content: value,
+				color: colorFn?.(item) ?? "gray",
+				type: "tag",
+			};
+		},
+	}),
+
+	/**
+	 * Badge column (numeric badge style)
+	 *
+	 * @example
+	 * columns.badge('count', 'Count')
+	 * columns.badge('brandCount', 'Brands')
+	 */
+	badge: <T = any>(key: string, label: string, options?: { sortable?: boolean }): DataTableColumn<T> => ({
+		key,
+		label,
+		type: "badge",
+		sortable: options?.sortable ?? true,
+		render: (item: any) => ({
+			content: item[key],
+			type: "badge",
+		}),
+	}),
+
+	/**
+	 * Boolean column rendered as tag
+	 *
+	 * @example
+	 * columns.boolean('active', 'Active')
+	 * columns.boolean('verified', 'Verified', { trueLabel: 'Yes', falseLabel: 'No' })
+	 */
+	boolean: <T = any>(
+		key: string,
+		label: string,
+		options?: { trueLabel?: string; falseLabel?: string; trueColor?: string; falseColor?: string; sortable?: boolean }
+	): DataTableColumn<T> => ({
+		key,
+		label,
+		type: "tag",
+		sortable: options?.sortable ?? true,
+		render: (item: any) => {
+			const value = Boolean(item[key]);
+			return {
+				content: value ? (options?.trueLabel ?? "Yes") : (options?.falseLabel ?? "No"),
+				color: value ? (options?.trueColor ?? "green") : (options?.falseColor ?? "red"),
+				type: "tag",
+			};
+		},
+	}),
+
+	/**
+	 * Email column (renders as link)
+	 *
+	 * @example
+	 * columns.email('email', 'Email')
+	 */
+	email: <T = any>(key: string, label: string, options?: { sortable?: boolean }): DataTableColumn<T> => ({
+		key,
+		label,
+		type: "text",
+		sortable: options?.sortable ?? true,
+		render: (item: any) => ({
+			content: item[key],
+			type: "link",
+			href: `mailto:${item[key]}`,
+		}),
+	}),
+
+	/**
+	 * Actions column (row actions)
+	 *
+	 * @example
+	 * columns.actions(['view', 'edit', 'delete'])
+	 */
+	actions: <T = any>(actions: string[]): DataTableColumn<T> => ({
+		key: "_actions",
+		label: "",
+		sortable: false,
+		render: () => actions,
+	}),
+
+	/**
+	 * Custom render column
+	 *
+	 * @example
+	 * columns.custom('fullName', 'Name', (item) => `${item.firstName} ${item.lastName}`)
+	 */
+	custom: <T = any>(
+		key: string,
+		label: string,
+		render: (item: T, index: number) => any,
+		options?: { sortable?: boolean; width?: string }
+	): DataTableColumn<T> => ({
+		key,
+		label,
+		sortable: options?.sortable ?? false,
+		width: options?.width,
+		render,
+	}),
+
+	/**
+	 * Truncated text column
+	 *
+	 * @example
+	 * columns.truncate('description', 'Description', 50)
+	 */
+	truncate: <T = any>(key: string, label: string, maxLength: number, options?: { sortable?: boolean }): DataTableColumn<T> => ({
+		key,
+		label,
+		type: "text",
+		sortable: options?.sortable ?? true,
+		render: (item: any) => {
+			const value = String(item[key] ?? "");
+			if (value.length <= maxLength) return value;
+			return `${value.substring(0, maxLength)}...`;
+		},
+	}),
+
+	/**
+	 * Image column
+	 *
+	 * @example
+	 * columns.image('avatar', 'Avatar', { size: 32 })
+	 */
+	image: <T = any>(key: string, label: string, options?: { size?: number; fallback?: string }): DataTableColumn<T> => ({
+		key,
+		label,
+		sortable: false,
+		render: (item: any) => ({
+			content: item[key] || options?.fallback,
+			type: "image",
+			size: options?.size ?? 32,
+		}),
+	}),
+
+	/**
+	 * Progress column
+	 *
+	 * @example
+	 * columns.progress('completion', 'Progress')
+	 */
+	progress: <T = any>(key: string, label: string, options?: { max?: number; sortable?: boolean }): DataTableColumn<T> => ({
+		key,
+		label,
+		type: "number",
+		sortable: options?.sortable ?? true,
+		render: (item: any) => ({
+			content: item[key],
+			type: "progress",
+			max: options?.max ?? 100,
+		}),
+	}),
+
+	/**
+	 * Clickable link column that emits an action
+	 *
+	 * @example
+	 * // Simple link with action
+	 * columns.link('name', 'Campaign Name', (item) => ({
+	 *   action: 'view',
+	 *   data: { id: item.id }
+	 * }))
+	 *
+	 * // Link with custom emit handler in parent
+	 * columns.link('title', 'Title', (item) => ({
+	 *   action: 'openDetails',
+	 *   data: item
+	 * }))
+	 */
+	link: <T = any>(
+		key: string,
+		label: string,
+		emitConfig: (item: T) => { action: string; data: any },
+		options?: { sortable?: boolean; width?: string }
+	): DataTableColumn<T> => ({
+		key,
+		label,
+		sortable: options?.sortable ?? true,
+		width: options?.width,
+		render: (item: T) => ({
+			content: (item as any)[key],
+			type: "link",
+			emits: emitConfig(item),
+		}),
+	}),
+
+	/**
+	 * Link to external URL
+	 *
+	 * @example
+	 * columns.externalLink('website', 'Website')
+	 * columns.externalLink('url', 'URL', { newTab: true })
+	 */
+	externalLink: <T = any>(
+		key: string,
+		label: string,
+		options?: { sortable?: boolean; newTab?: boolean; displayKey?: string }
+	): DataTableColumn<T> => ({
+		key,
+		label,
+		sortable: options?.sortable ?? true,
+		render: (item: any) => {
+			const url = item[key];
+			const display = options?.displayKey ? item[options.displayKey] : url;
+			return {
+				content: display,
+				type: "link",
+				href: url,
+				target: options?.newTab ? "_blank" : undefined,
+			};
+		},
+	}),
+
+	/**
+	 * Relative time column (e.g., "2 hours ago")
+	 *
+	 * @example
+	 * columns.relativeTime('updatedAt', 'Last Updated')
+	 */
+	relativeTime: <T = any>(key: string, label: string, options?: { sortable?: boolean; locale?: string }): DataTableColumn<T> => ({
+		key,
+		label,
+		type: "date",
+		sortable: options?.sortable ?? true,
+		render: (item: any) => {
+			const value = item[key];
+			if (!value) return "";
+
+			const date = value instanceof Date ? value : new Date(value);
+			if (Number.isNaN(date.getTime())) return "";
+
+			const now = new Date();
+			const diffMs = now.getTime() - date.getTime();
+			const diffSecs = Math.floor(diffMs / 1000);
+			const diffMins = Math.floor(diffSecs / 60);
+			const diffHours = Math.floor(diffMins / 60);
+			const diffDays = Math.floor(diffHours / 24);
+
+			if (diffSecs < 60) return "Just now";
+			if (diffMins < 60) return `${diffMins}m ago`;
+			if (diffHours < 24) return `${diffHours}h ago`;
+			if (diffDays < 7) return `${diffDays}d ago`;
+
+			return date.toLocaleDateString(options?.locale);
+		},
+	}),
+
+	/**
+	 * User/Avatar column with name and optional subtitle
+	 *
+	 * @example
+	 * columns.user('assignee', 'Assigned To', { avatarKey: 'avatar', subtitleKey: 'email' })
+	 */
+	user: <T = any>(
+		key: string,
+		label: string,
+		options?: { avatarKey?: string; subtitleKey?: string; sortable?: boolean }
+	): DataTableColumn<T> => ({
+		key,
+		label,
+		sortable: options?.sortable ?? true,
+		render: (item: any) => ({
+			content: item[key],
+			type: "guest",
+			avatar: options?.avatarKey ? item[options.avatarKey] : undefined,
+			subtitle: options?.subtitleKey ? item[options.subtitleKey] : undefined,
+		}),
+	}),
+
+	/**
+	 * Currency column with formatting
+	 *
+	 * @example
+	 * columns.currency('amount', 'Total', { currency: 'EUR' })
+	 * columns.currency('price', 'Price', { currency: 'USD', locale: 'en-US' })
+	 */
+	currency: <T = any>(
+		key: string,
+		label: string,
+		options?: { currency?: string; locale?: string; sortable?: boolean }
+	): DataTableColumn<T> => ({
+		key,
+		label,
+		type: "number",
+		sortable: options?.sortable ?? true,
+		render: (item: any) => {
+			const value = item[key];
+			if (value === null || value === undefined) return "";
+
+			return new Intl.NumberFormat(options?.locale ?? "en-US", {
+				style: "currency",
+				currency: options?.currency ?? "EUR",
+			}).format(Number(value));
+		},
+	}),
+
+	/**
+	 * Percentage column
+	 *
+	 * @example
+	 * columns.percentage('openRate', 'Open Rate')
+	 * columns.percentage('completion', 'Progress', { decimals: 0 })
+	 */
+	percentage: <T = any>(
+		key: string,
+		label: string,
+		options?: { decimals?: number; sortable?: boolean; multiply?: boolean }
+	): DataTableColumn<T> => ({
+		key,
+		label,
+		type: "number",
+		sortable: options?.sortable ?? true,
+		render: (item: any) => {
+			const value = item[key];
+			if (value === null || value === undefined) return "";
+
+			// If multiply is true, assume value is 0-1 and needs *100
+			const numValue = options?.multiply ? Number(value) * 100 : Number(value);
+			return `${numValue.toFixed(options?.decimals ?? 1)}%`;
+		},
+	}),
+};
+
+/**
+ * Status color mappings for common status values
+ */
+export const statusColors: Record<string, string> = {
+	active: "green",
+	inactive: "gray",
+	pending: "yellow",
+	approved: "green",
+	rejected: "red",
+	draft: "gray",
+	published: "green",
+	archived: "gray",
+	error: "red",
+	success: "green",
+	warning: "yellow",
+	info: "blue",
+};
+
+/**
+ * Get color for a status value
+ *
+ * @example
+ * columns.tag('status', 'Status', (item) => getStatusColor(item.status))
+ */
+export function getStatusColor(status: string): string {
+	return statusColors[status?.toLowerCase()] ?? "gray";
+}
+
+/**
+ * Create a status color function for a specific key
+ *
+ * @example
+ * columns.tag('status', 'Status', createStatusColorFn('status'))
+ */
+export function createStatusColorFn<T>(key: keyof T): TagColorFn<T> {
+	return (item: T) => getStatusColor(String(item[key]));
+}

package/src/data/data.md

@@ -0,0 +1,106 @@
+# Data Module
+
+Components for displaying and managing data.
+
+## Components
+
+### Table
+
+Comprehensive data table with pagination, sorting, and filtering.
+
+```vue
+<script setup>
+import { ref } from 'vue';
+import { Table } from '@htlkg/components/data';
+
+const currentPage = ref(1);
+const columns = [
+  { name: 'Name', value: 'name', sortable: true },
+  { name: 'Email', value: 'email' },
+  { name: 'Status', value: 'status' },
+];
+</script>
+
+<template>
+  <Table 
+    v-model:currentPage="currentPage"
+    :items="users"
+    :columns="columns"
+    :loading="loading"
+    selectable
+    @row-click="handleRowClick"
+    @selection-change="handleSelection"
+  />
+</template>
+```
+
+### DataList
+
+Simple list component for displaying collections.
+
+```vue
+<script setup>
+import { DataList } from '@htlkg/components/data';
+</script>
+
+<template>
+  <DataList :items="items" :loading="loading">
+    <template #item="{ item }">
+      <div>{{ item.name }}</div>
+    </template>
+    <template #empty>
+      <p>No items found</p>
+    </template>
+  </DataList>
+</template>
+```
+
+### SearchableSelect
+
+Searchable dropdown with single/multiple selection.
+
+```vue
+<script setup>
+import { ref } from 'vue';
+import { SearchableSelect } from '@htlkg/components/data';
+
+const selected = ref(null);
+const options = [
+  { value: '1', label: 'Option 1' },
+  { value: '2', label: 'Option 2' },
+];
+</script>
+
+<template>
+  <SearchableSelect 
+    v-model="selected"
+    :options="options"
+    placeholder="Select..."
+    searchable
+    clearable
+  />
+</template>
+```
+
+### Chart
+
+Data visualization with multiple chart types.
+
+```vue
+<script setup>
+import { Chart } from '@htlkg/components/data';
+
+const data = {
+  labels: ['Jan', 'Feb', 'Mar'],
+  datasets: [{ data: [10, 20, 30] }],
+};
+</script>
+
+<template>
+  <Chart 
+    type="line"
+    :data="data"
+    :options="{ responsive: true }"
+  />
+</template>
+```