@vibesdotdev/kit 0.0.0-stage → 1.0.0-rc.4

package/dist/lib/datatable/DataTable.svelte.d.ts

@@ -0,0 +1,25 @@
+import { type DataTableProps } from './types';
+declare function $$render<T>(): {
+    props: DataTableProps<T>;
+    exports: {};
+    bindings: "";
+    slots: {};
+    events: {};
+};
+declare class __sveltets_Render<T> {
+    props(): ReturnType<typeof $$render<T>>['props'];
+    events(): ReturnType<typeof $$render<T>>['events'];
+    slots(): ReturnType<typeof $$render<T>>['slots'];
+    bindings(): "";
+    exports(): {};
+}
+interface $$IsomorphicComponent {
+    new <T>(options: import('svelte').ComponentConstructorOptions<ReturnType<__sveltets_Render<T>['props']>>): import('svelte').SvelteComponent<ReturnType<__sveltets_Render<T>['props']>, ReturnType<__sveltets_Render<T>['events']>, ReturnType<__sveltets_Render<T>['slots']>> & {
+        $$bindings?: ReturnType<__sveltets_Render<T>['bindings']>;
+    } & ReturnType<__sveltets_Render<T>['exports']>;
+    <T>(internal: unknown, props: ReturnType<__sveltets_Render<T>['props']> & {}): ReturnType<__sveltets_Render<T>['exports']>;
+    z_$$bindings?: ReturnType<__sveltets_Render<any>['bindings']>;
+}
+declare const DataTable: $$IsomorphicComponent;
+type DataTable<T> = InstanceType<typeof DataTable<T>>;
+export default DataTable;

package/dist/lib/datatable/DataView.svelte

@@ -0,0 +1,254 @@
+<!--
+	DataView - drop-in list/table/cards + search + pagination.
+
+	Wraps a host-supplied `DatatableNavigation` and `PaginatedDataTable` so
+	the common case is a single component call instead of ~40 lines of store
+	wiring. Pages that need bespoke behavior keep using `PaginatedDataTable`
+	directly with their own store.
+
+	Server contract: pass the return of `toDataViewServerData(result)` from
+	`@vibesdotdev/kit/datatable/server` as `data`. That ensures filters are
+	flattened (Maps don't survive SvelteKit serialization).
+-->
+<script lang="ts" generics="T">import { Card, CardHeader, CardTitle, CardDescription, CardContent, CardFooter } from "../components/ui/card";
+import { Input } from "../components/ui/input";
+import { Icon } from "../components/icon";
+import EmptyState from "../components/layout/EmptyState.svelte";
+import PaginatedDataTable from "./PaginatedDataTable.svelte";
+import { Pagination, PaginationContent, PaginationItem, PaginationLink, PaginationPrevious, PaginationNext, PaginationEllipsis } from "../components/ui/pagination";
+import { cn } from "../utils.js";
+import { onDestroy, untrack } from "svelte";
+import { decodeFilters } from "./url-filters";
+import { settle } from "../attempt";
+import { kitLogger } from "../kit-logger";
+const logger = kitLogger("DataView");
+let { data, navigation, invalidateKey, renderMode = "table", columns, card, cardGridClass = "grid grid-cols-1 gap-4 sm:grid-cols-2 lg:grid-cols-3", getRowKey, searchable = false, searchPlaceholder = "Search...", searchDebounceMs = 300, enableSorting = true, showTopPagination = false, showBottomPagination = true, itemsPerPageOptions = [
+	5,
+	10,
+	25,
+	50,
+	100
+], title, description, useCardChrome = true, headerActions, filtersSnippet, afterContent, onRowClick, emptyMessage = "No items found.", emptyFilteredMessage = "No items match your filters.", emptyState, loading = false, class: className } = $props();
+$effect(() => {
+	if (renderMode === "table" && !columns) {
+		logger.warn("renderMode=\"table\" requires `columns`.");
+	}
+	if (renderMode === "cards" && !card) {
+		logger.warn("renderMode=\"cards\" requires a `card` snippet.");
+	}
+});
+// Reactive accessors derived from `data` so the store always reflects the
+// latest server response (SvelteKit reuses the component across navigations).
+const records = $derived.by(() => data.records ?? []);
+const pagination = $derived.by(() => data.pagination ?? {
+	page: 1,
+	perPage: 20,
+	total: 0,
+	totalPages: 0
+});
+const serverSort = $derived.by(() => data.sort ?? null);
+const initialPagination = untrack(() => pagination);
+const initialSort = untrack(() => serverSort);
+const paginationDefaults = untrack(() => data.paginationDefaults ?? {
+	page: 1,
+	perPage: 20,
+	sort: null
+});
+const initialInvalidateKey = untrack(() => invalidateKey);
+const store = untrack(() => navigation.createPaginatedStore({
+	data: () => records,
+	pagination: initialPagination,
+	sort: initialSort,
+	invalidateKey: initialInvalidateKey,
+	defaults: paginationDefaults
+}));
+$effect(() => {
+	store.updateFromServer(records, pagination, serverSort);
+});
+const activeFilters = $derived(data.filters ?? []);
+const hasActiveFilters = $derived(activeFilters.length > 0 || Boolean(data.search));
+// Search input - local state mirrors the server-confirmed search term but
+// drifts during typing; we debounce a `navigateDatatable` call.
+let searchTerm = $state(untrack(() => data.search ?? ""));
+let lastServerSearch = $state(untrack(() => data.search ?? null));
+$effect(() => {
+	const incoming = data.search ?? null;
+	if (incoming !== lastServerSearch) {
+		lastServerSearch = incoming;
+		searchTerm = incoming ?? "";
+	}
+});
+// Fixed message for a failed search navigation; the host error goes to the
+// logger as the error argument, never into the message.
+const SEARCH_NAVIGATION_FAILED = "Search navigation failed; showing the previous results.";
+async function commitSearch(value) {
+	const existing = decodeFilters(new URL(navigation.destination(), "https://vibes.invalid").searchParams.get("filters"));
+	const next = Object.fromEntries(Object.entries(existing).filter(([key]) => key !== "search"));
+	await navigation.navigate({
+		filters: next,
+		search: value.length > 0 ? value : null,
+		replace: true,
+		invalidateKey,
+		defaults: paginationDefaults
+	});
+}
+let searchTimer = null;
+function onSearchInput(value) {
+	searchTerm = value;
+	if (searchTimer) clearTimeout(searchTimer);
+	searchTimer = setTimeout(() => {
+		searchTimer = null;
+		void settle(() => commitSearch(value)).then((outcome) => {
+			if (!outcome.ok) logger.error(SEARCH_NAVIGATION_FAILED, outcome.error);
+		});
+	}, searchDebounceMs);
+}
+onDestroy(() => {
+	if (searchTimer) clearTimeout(searchTimer);
+});
+function isCardEmpty() {
+	return records.length === 0;
+}
+</script>
+
+{#snippet defaultEmpty()}
+	{#if emptyState}
+		{@render emptyState()}
+	{:else}
+		<EmptyState
+			icon="lucide:inbox"
+			title={hasActiveFilters ? emptyFilteredMessage : emptyMessage}
+			size="md"
+		/>
+	{/if}
+{/snippet}
+
+{#snippet searchRow()}
+	{#if searchable || filtersSnippet}
+		<div class="flex flex-col gap-2 px-6 pb-3 sm:flex-row sm:items-center sm:justify-between">
+			{#if searchable}
+				<div class="relative w-full sm:max-w-sm">
+					<Icon
+						icon="lucide:search"
+						class="pointer-events-none absolute top-1/2 left-2 h-4 w-4 -translate-y-1/2 text-muted-foreground"
+					/>
+					<Input
+						type="search"
+						value={searchTerm}
+						placeholder={searchPlaceholder}
+						class="pl-8"
+						oninput={(e) => onSearchInput((e.currentTarget as HTMLInputElement).value)}
+					/>
+				</div>
+			{/if}
+			{#if filtersSnippet}
+				<div class="flex flex-wrap items-center gap-2">{@render filtersSnippet()}</div>
+			{/if}
+		</div>
+	{/if}
+{/snippet}
+
+{#snippet cardModeBody()}
+	{#if isCardEmpty()}
+		{@render defaultEmpty()}
+	{:else}
+		<div class={cn('px-6 pb-6', cardGridClass)}>
+			{#each records as row, index (getRowKey ? getRowKey(row, index) : index)}
+				{#if card}
+					{@render card({ row, index })}
+				{/if}
+			{/each}
+		</div>
+		{#if afterContent}
+			<div class="px-6 pb-2">{@render afterContent()}</div>
+		{/if}
+		{#if showBottomPagination}
+			<CardFooter class="border-t !pt-3 !pb-3">
+				<Pagination
+					page={store.currentPage}
+					count={store.totalItems}
+					perPage={store.itemsPerPage}
+					onPageChange={(p) => store.changePage(p)}
+					class="mx-0 w-full justify-end whitespace-nowrap"
+				>
+					{#snippet children({ pages, currentPage })}
+						<PaginationContent>
+							<PaginationItem><PaginationPrevious /></PaginationItem>
+							{#each pages as p (p.key)}
+								{#if p.type === 'ellipsis'}
+									<PaginationItem><PaginationEllipsis /></PaginationItem>
+								{:else}
+									<PaginationItem>
+										<PaginationLink page={p} isActive={currentPage === p.value}>
+											{p.value}
+										</PaginationLink>
+									</PaginationItem>
+								{/if}
+							{/each}
+							<PaginationItem><PaginationNext /></PaginationItem>
+						</PaginationContent>
+					{/snippet}
+				</Pagination>
+			</CardFooter>
+		{/if}
+	{/if}
+{/snippet}
+
+{#snippet header()}
+	{#if title || description || headerActions}
+		<CardHeader class="pt-4">
+			<div class="flex items-center justify-between gap-3">
+				<div class="space-y-1">
+					{#if title}<CardTitle>{title}</CardTitle>{/if}
+					{#if description}<CardDescription>{description}</CardDescription>{/if}
+				</div>
+				{#if headerActions}
+					<div class="flex items-center gap-2">{@render headerActions()}</div>
+				{/if}
+			</div>
+		</CardHeader>
+	{/if}
+{/snippet}
+
+{#if renderMode === 'cards'}
+	{#if useCardChrome}
+		<Card class={cn('gap-0 overflow-hidden py-0', className)}>
+			{@render header()}
+			{@render searchRow()}
+			{@render cardModeBody()}
+		</Card>
+	{:else}
+		<div class={className}>
+			{@render header()}
+			{@render searchRow()}
+			{@render cardModeBody()}
+		</div>
+	{/if}
+{:else}
+	<!-- Table mode delegates almost everything to PaginatedDataTable. -->
+	<PaginatedDataTable
+		{store}
+		columns={columns ?? []}
+		{title}
+		{description}
+		{headerActions}
+		{enableSorting}
+		{showTopPagination}
+		{showBottomPagination}
+		{itemsPerPageOptions}
+		{onRowClick}
+		{emptyMessage}
+		{loading}
+		cardClassName={cn(useCardChrome ? '' : 'border-0 shadow-none', className)}
+	>
+		{#snippet beforeTable()}
+			{@render searchRow()}
+			{#if filtersSnippet}
+				<!-- already rendered in searchRow when filtersSnippet provided -->
+			{/if}
+		{/snippet}
+		{#snippet afterTable()}
+			{#if afterContent}{@render afterContent()}{/if}
+		{/snippet}
+	</PaginatedDataTable>
+{/if}

package/dist/lib/datatable/DataView.svelte.d.ts

@@ -0,0 +1,77 @@
+import type { Snippet } from 'svelte';
+import type { Column } from './types';
+import type { DataViewServerData } from './data-view-server';
+import type { DatatableNavigation } from './navigation';
+export interface DataViewCardContext<T> {
+    row: T;
+    index: number;
+}
+interface DataViewProps<T> {
+    /** Server load output (see `toDataViewServerData`). */
+    data: DataViewServerData<T>;
+    /** Host-owned route location, navigation, and invalidation adapter. */
+    navigation: DatatableNavigation;
+    /** SvelteKit invalidation key, e.g. 'app:knowledge-domains'. */
+    invalidateKey: string;
+    /** Rendering mode. @default 'table' */
+    renderMode?: 'table' | 'cards';
+    /** Required when renderMode='table'. */
+    columns?: Column<T>[];
+    /** Required when renderMode='cards'. */
+    card?: Snippet<[DataViewCardContext<T>]>;
+    /** Grid classes for card mode. */
+    cardGridClass?: string;
+    /**
+     * Stable row key for card-mode `{#each}` reconciliation. Falls back to
+     * `index` if omitted, which is correct only when row order never changes
+     * (no server-side sort/filter/search). Pass `(row) => row.id` whenever
+     * the row has a stable identifier.
+     */
+    getRowKey?: (row: T, index: number) => string | number;
+    /** Show a built-in search input. @default false */
+    searchable?: boolean;
+    searchPlaceholder?: string;
+    searchDebounceMs?: number;
+    enableSorting?: boolean;
+    showTopPagination?: boolean;
+    showBottomPagination?: boolean;
+    itemsPerPageOptions?: number[];
+    title?: string;
+    description?: string;
+    useCardChrome?: boolean;
+    headerActions?: Snippet;
+    /** Custom slot rendered above the table/cards, after the search row. */
+    filtersSnippet?: Snippet;
+    /** Slot rendered between the data and the bottom pagination. */
+    afterContent?: Snippet;
+    onRowClick?: (row: T) => void;
+    emptyMessage?: string;
+    emptyFilteredMessage?: string;
+    emptyState?: Snippet;
+    loading?: boolean;
+    class?: string;
+}
+declare function $$render<T>(): {
+    props: DataViewProps<T>;
+    exports: {};
+    bindings: "";
+    slots: {};
+    events: {};
+};
+declare class __sveltets_Render<T> {
+    props(): ReturnType<typeof $$render<T>>['props'];
+    events(): ReturnType<typeof $$render<T>>['events'];
+    slots(): ReturnType<typeof $$render<T>>['slots'];
+    bindings(): "";
+    exports(): {};
+}
+interface $$IsomorphicComponent {
+    new <T>(options: import('svelte').ComponentConstructorOptions<ReturnType<__sveltets_Render<T>['props']>>): import('svelte').SvelteComponent<ReturnType<__sveltets_Render<T>['props']>, ReturnType<__sveltets_Render<T>['events']>, ReturnType<__sveltets_Render<T>['slots']>> & {
+        $$bindings?: ReturnType<__sveltets_Render<T>['bindings']>;
+    } & ReturnType<__sveltets_Render<T>['exports']>;
+    <T>(internal: unknown, props: ReturnType<__sveltets_Render<T>['props']> & {}): ReturnType<__sveltets_Render<T>['exports']>;
+    z_$$bindings?: ReturnType<__sveltets_Render<any>['bindings']>;
+}
+declare const DataView: $$IsomorphicComponent;
+type DataView<T> = InstanceType<typeof DataView<T>>;
+export default DataView;

package/dist/lib/datatable/DatatableCell.svelte

@@ -0,0 +1,136 @@
+<!--
+	DataTable Cell Component
+	
+	Provides both snippet exports and component wrapper for table cells.
+	Following component rules: Complexity in markup, no business logic.
+-->
+<script module lang="ts">// Export cell snippets for direct use
+// Note: Snippets defined in template are automatically available to consumers
+export { textCell, dateCell, dateTimeCell, currencyCell, percentCell, badgeCell, linkCell, customCell };
+</script>
+
+<script lang="ts">import { Badge } from "../components/ui/badge";
+import { Button } from "../components/ui/button";
+import { formatDate, formatDateTime, formatCurrency, formatPercent } from "../utils/format";
+const BUTTON_VARIANTS = [
+	"default",
+	"destructive",
+	"outline",
+	"secondary",
+	"ghost",
+	"link",
+	"glass"
+];
+function buttonVariant(value) {
+	return BUTTON_VARIANTS.find((variant) => variant === value) ?? "outline";
+}
+let { variant = "text", value, row, href, actions = [], customSnippet, badgeVariant = "default", trueLabel = "Yes", falseLabel = "No", currency = "USD", decimals = 2 } = $props();
+</script>
+
+<!-- Text Cell (default) -->
+{#snippet textCell(value: unknown)}
+	<span class="truncate">{value ?? ''}</span>
+{/snippet}
+
+<!-- Date Cell -->
+{#snippet dateCell(value: unknown)}
+	<span class="tabular-nums">
+		{value && value instanceof Date ? formatDate(value) : value ? formatDate(String(value)) : '-'}
+	</span>
+{/snippet}
+
+<!-- DateTime Cell -->
+{#snippet dateTimeCell(value: unknown)}
+	<span class="text-sm tabular-nums">
+		{value && value instanceof Date
+			? formatDateTime(value)
+			: value
+				? formatDateTime(String(value))
+				: '-'}
+	</span>
+{/snippet}
+
+<!-- Currency Cell -->
+{#snippet currencyCell(value: unknown, currency = 'USD')}
+	<span class="font-medium tabular-nums">
+		{value !== null && value !== undefined ? formatCurrency(Number(value), currency) : '-'}
+	</span>
+{/snippet}
+
+<!-- Percent Cell -->
+{#snippet percentCell(value: unknown, decimals = 2)}
+	<span class="tabular-nums">
+		{value !== null && value !== undefined ? formatPercent(Number(value), decimals) : '-'}
+	</span>
+{/snippet}
+
+<!-- Boolean Cell -->
+{#snippet booleanCell(value: unknown, trueLabel = 'Yes', falseLabel = 'No')}
+	<Badge variant={value ? 'default' : 'outline'}>
+		{value ? trueLabel : falseLabel}
+	</Badge>
+{/snippet}
+
+<!-- Badge Cell -->
+{#snippet badgeCell(
+	value: unknown,
+	variant: 'default' | 'secondary' | 'destructive' | 'outline' = 'default'
+)}
+	{#if value}
+		<Badge {variant}>
+			{value}
+		</Badge>
+	{/if}
+{/snippet}
+
+<!-- Link Cell -->
+{#snippet linkCell(value: unknown, href: string)}
+	<a {href} class="text-primary underline-offset-4 hover:underline">
+		{value}
+	</a>
+{/snippet}
+
+<!-- Actions Cell -->
+{#snippet actionsCell(actions: Array<{ label: string; onclick: () => void; variant?: string }>)}
+	<div class="flex items-center gap-2">
+		{#each actions as action, i (i)}
+			<Button size="sm" variant={buttonVariant(action.variant)} onclick={action.onclick}>
+				{action.label}
+			</Button>
+		{/each}
+	</div>
+{/snippet}
+
+<!-- Custom Cell -->
+{#snippet customCell(
+	snippet: SnippetType<[{ value: unknown; row: DatatableRow }]>,
+	value: unknown,
+	row: DatatableRow
+)}
+	{@render snippet({ value, row })}
+{/snippet}
+
+<!-- Component Wrapper -->
+{#if variant === 'text'}
+	{@render textCell(value)}
+{:else if variant === 'date'}
+	{@render dateCell(value)}
+{:else if variant === 'datetime'}
+	{@render dateTimeCell(value)}
+{:else if variant === 'currency'}
+	{@render currencyCell(value, currency)}
+{:else if variant === 'percent'}
+	{@render percentCell(value, decimals)}
+{:else if variant === 'boolean'}
+	{@render booleanCell(value, trueLabel, falseLabel)}
+{:else if variant === 'badge'}
+	{@render badgeCell(value, badgeVariant)}
+{:else if variant === 'link'}
+	{@render linkCell(value, href || '#')}
+{:else if variant === 'actions'}
+	{@render actionsCell(actions)}
+{:else if variant === 'custom' && customSnippet}
+	{@render customCell(customSnippet, value, row || {})}
+{:else}
+	{@render textCell(value)}
+{/if}

package/dist/lib/datatable/DatatableCell.svelte.d.ts

@@ -0,0 +1,37 @@
+export { textCell, dateCell, dateTimeCell, currencyCell, percentCell, badgeCell, linkCell, customCell };
+import type { Snippet as SnippetType } from 'svelte';
+import type { DatatableRow } from './types';
+interface Props {
+    variant?: 'text' | 'date' | 'datetime' | 'currency' | 'percent' | 'boolean' | 'badge' | 'link' | 'actions' | 'custom';
+    value?: unknown;
+    row?: DatatableRow;
+    href?: string;
+    actions?: Array<{
+        label: string;
+        onclick: () => void;
+        variant?: string;
+    }>;
+    customSnippet?: SnippetType<[{
+        value: unknown;
+        row: DatatableRow;
+    }]>;
+    badgeVariant?: 'default' | 'secondary' | 'destructive' | 'outline';
+    trueLabel?: string;
+    falseLabel?: string;
+    currency?: string;
+    decimals?: number;
+}
+declare const textCell: (value: unknown) => ReturnType<import("svelte").Snippet>;
+declare const dateCell: (value: unknown) => ReturnType<import("svelte").Snippet>;
+declare const dateTimeCell: (value: unknown) => ReturnType<import("svelte").Snippet>;
+declare const currencyCell: (value: unknown, currency?: string) => ReturnType<import("svelte").Snippet>;
+declare const percentCell: (value: unknown, decimals?: number) => ReturnType<import("svelte").Snippet>;
+declare const badgeCell: (value: unknown, variant?: "default" | "secondary" | "destructive" | "outline") => ReturnType<import("svelte").Snippet>;
+declare const linkCell: (value: unknown, href: string) => ReturnType<import("svelte").Snippet>;
+declare const customCell: (snippet: SnippetType<[{
+    value: unknown;
+    row: DatatableRow;
+}]>, value: unknown, row: DatatableRow) => ReturnType<import("svelte").Snippet>;
+declare const DatatableCell: import("svelte").Component<Props, {}, "">;
+type DatatableCell = ReturnType<typeof DatatableCell>;
+export default DatatableCell;