@antelopejs/dms-database 0.0.1

package/frontend-vue/app/components/SchemaTableInspector.vue

@@ -0,0 +1,278 @@
+<script setup lang="ts">
+import type {
+	FieldDescriptor,
+	TableSummary,
+} from "../composables/useDatabaseSchemas";
+import { inferFieldTypeIcon, isPrimaryKey } from "../utils/databaseFieldTypeIcons";
+
+// Body panel for the shared dms drawer (useDrawer). The drawer owns the chrome
+// (themed surface, header with the table name + subtitle, close button); this
+// component only renders the inspector content: columns / indexes / preview
+// tabs and the footer. It is opened from schemas.vue via `useDrawer().open()`.
+
+// Descriptor kinds that admit null/undefined on their own: an explicit
+// null/undefined, or an untyped any/unknown.
+const NULLISH_KINDS = new Set<FieldDescriptor["kind"]>([
+	"null",
+	"undefined",
+	"any",
+	"unknown",
+]);
+
+// A field is nullable when its descriptor admits null/undefined — directly, as
+// an untyped any/unknown, or as a member of a union. Anything else is required.
+function isNullable(descriptor: FieldDescriptor): boolean {
+	if (NULLISH_KINDS.has(descriptor.kind)) return true;
+	if (descriptor.kind === "union") {
+		return descriptor.members.some(
+			(member) => member.kind === "null" || member.kind === "undefined",
+		);
+	}
+	return false;
+}
+
+interface Props {
+	schemaId: string | null;
+	table: TableSummary | null;
+	// Injected by the shared DynamicDrawer; unused here (read-only panel).
+	containerId?: string;
+}
+
+const props = defineProps<Props>();
+
+// The shared DynamicDrawer dismisses the drawer when the body emits `success`.
+const emit = defineEmits<{ success: [] }>();
+
+const { t } = useI18n();
+const router = useDmsRouter();
+const { $authFetch } = useAuthFetch();
+
+const DATA_PATH = "/modules/database/data";
+const BROWSE_LIST = "/api/database/browse/list";
+const FILTER_MODE_IS = "is";
+
+type Tab = "columns" | "indexes" | "preview";
+const tab = ref<Tab>("columns");
+
+const tabItems = computed(() => [
+	{ label: t("dms_database.schemas.inspector.columns"), value: "columns" as const, icon: "i-ph-layout" },
+	{ label: t("dms_database.schemas.inspector.indexes"), value: "indexes" as const, icon: "i-ph-key" },
+	{ label: t("dms_database.schemas.inspector.preview"), value: "preview" as const, icon: "i-ph-table" },
+]);
+
+const fieldEntries = computed(() =>
+	Object.entries(props.table?.fields ?? {}).map(([name, descriptor]) => {
+		const meta = inferFieldTypeIcon(descriptor, name);
+		const pk = isPrimaryKey(name, props.table?.indexes ?? {});
+		// Primary keys are never nullable; otherwise read it off the descriptor.
+		const nullable = pk ? false : isNullable(descriptor);
+		return { name, meta, pk, nullable };
+	}),
+);
+
+const indexEntries = computed(() =>
+	Object.entries(props.table?.indexes ?? {}).map(([name, def]) => ({
+		name,
+		fields: def.fields ?? [],
+		multi: Boolean(def.multi),
+	})),
+);
+
+// --- preview (single sample row) ---
+const previewRow = ref<Record<string, unknown> | null>(null);
+const previewLoading = ref(false);
+const previewError = ref(false);
+const previewLoadedFor = ref<string | null>(null);
+
+async function loadPreview() {
+	if (!props.schemaId || !props.table) return;
+	const key = `${props.schemaId}::${props.table.name}`;
+	if (previewLoadedFor.value === key) return;
+	previewLoading.value = true;
+	previewError.value = false;
+	try {
+		const res = await $authFetch<{ results: Record<string, unknown>[] }>(
+			BROWSE_LIST,
+			{
+				query: {
+					filter_schema: `${FILTER_MODE_IS}:${props.schemaId}`,
+					filter_table: `${FILTER_MODE_IS}:${props.table.name}`,
+					limit: 1,
+				},
+			},
+		);
+		previewRow.value = res.results?.[0] ?? null;
+		previewLoadedFor.value = key;
+	} catch {
+		previewError.value = true;
+		previewRow.value = null;
+	} finally {
+		previewLoading.value = false;
+	}
+}
+
+const previewJson = computed(() =>
+	previewRow.value ? JSON.stringify(previewRow.value, null, 2) : "",
+);
+
+// The panel is mounted only while the drawer is open, so the preview loads as
+// soon as its tab is selected (no `open` prop to gate on anymore).
+watch(
+	() => [tab.value, props.table?.name] as const,
+	() => {
+		if (tab.value === "preview") loadPreview();
+	},
+);
+
+const browseTo = computed(() => {
+	if (!props.schemaId || !props.table) return DATA_PATH;
+	return `${DATA_PATH}?schema=${encodeURIComponent(props.schemaId)}&table=${encodeURIComponent(props.table.name)}`;
+});
+
+// "Browse data" navigates to the data browser and closes the drawer so the user
+// lands on the table without the panel lingering over it.
+function browseData() {
+	router.push(browseTo.value);
+	emit("success");
+}
+</script>
+
+<template>
+	<!-- Fixed width so the right-side drawer keeps a stable, comfortable size
+	     instead of shrinking/growing with the active tab's content (the shared
+	     DynamicDrawer sizes a right drawer to its content and exposes no width). -->
+	<div class="flex h-full w-[36rem] max-w-[calc(100vw-3rem)] flex-col">
+		<!-- tabs -->
+		<div class="border-b border-default pb-3">
+			<DmsSegmented v-model="tab" :items="tabItems" />
+		</div>
+
+		<!-- body -->
+		<div class="flex-1 overflow-y-auto py-4">
+			<!-- columns -->
+			<table v-if="tab === 'columns'" class="w-full text-sm">
+				<thead>
+					<tr class="border-b border-default text-left">
+						<th class="text-dimmed py-2 pr-3 text-xs font-semibold">
+							{{ $t("dms_database.schemas.inspector.colName") }}
+						</th>
+						<th class="text-dimmed py-2 px-3 text-xs font-semibold">
+							{{ $t("dms_database.schemas.inspector.colType") }}
+						</th>
+						<th class="text-dimmed py-2 pl-3 text-xs font-semibold">
+							{{ $t("dms_database.schemas.inspector.colNullable") }}
+						</th>
+					</tr>
+				</thead>
+				<tbody>
+					<tr
+						v-for="field in fieldEntries"
+						:key="field.name"
+						class="border-b border-default/60 last:border-0"
+					>
+						<td class="py-2 pr-3">
+							<span class="flex items-center gap-2 font-mono text-toned">
+								<UIcon
+									:name="field.pk ? 'i-ph-key' : field.meta.icon"
+									class="size-3.5 shrink-0"
+									:class="field.pk ? 'text-warning' : field.meta.color"
+								/>
+								{{ field.name }}
+							</span>
+						</td>
+						<td class="py-2 px-3">
+							<span
+								class="font-mono text-[11px]"
+								:class="field.meta.color"
+							>
+								{{ field.pk ? "pk" : field.meta.label }}
+							</span>
+						</td>
+						<td class="py-2 pl-3 text-dimmed">
+							{{
+								field.nullable
+									? $t("dms_database.schemas.inspector.yes")
+									: $t("dms_database.schemas.inspector.no")
+							}}
+						</td>
+					</tr>
+				</tbody>
+			</table>
+
+			<!-- indexes -->
+			<div v-else-if="tab === 'indexes'" class="space-y-2.5">
+				<div
+					v-for="idx in indexEntries"
+					:key="idx.name"
+					class="flex items-center gap-3 rounded-md border border-default bg-default px-3 py-2.5"
+				>
+					<UBadge
+						:color="idx.multi ? 'info' : 'neutral'"
+						variant="soft"
+						size="sm"
+					>
+						{{
+							idx.multi
+								? $t("dms_database.schemas.inspector.multi")
+								: $t("dms_database.schemas.inspector.single")
+						}}
+					</UBadge>
+					<span class="font-mono text-[12.5px] text-toned">{{ idx.name }}</span>
+					<span
+						v-if="idx.fields.length"
+						class="font-mono text-[11px] text-dimmed ml-auto truncate"
+					>
+						{{ idx.fields.join(", ") }}
+					</span>
+				</div>
+				<p
+					v-if="indexEntries.length === 0"
+					class="text-dimmed text-sm py-6 text-center"
+				>
+					{{ $t("dms_database.schemas.inspector.noIndexes") }}
+				</p>
+			</div>
+
+			<!-- preview -->
+			<div v-else>
+				<div v-if="previewLoading" class="py-10 text-center">
+					<UProgress size="sm" />
+				</div>
+				<div
+					v-else-if="previewError"
+					class="text-dimmed text-sm py-10 text-center"
+				>
+					{{ $t("dms_database.schemas.inspector.previewError") }}
+				</div>
+				<div
+					v-else-if="!previewRow"
+					class="text-dimmed text-sm py-10 text-center"
+				>
+					{{ $t("dms_database.schemas.inspector.previewEmpty") }}
+				</div>
+				<pre
+					v-else
+					class="text-xs rounded-lg border border-default bg-default p-4 overflow-auto whitespace-pre text-toned"
+					>{{ previewJson }}</pre
+				>
+			</div>
+		</div>
+
+		<!-- footer -->
+		<div class="flex items-center gap-2 border-t border-default pt-4">
+			<span class="flex items-center gap-1.5 text-xs text-success">
+				<UIcon name="i-ph-check-circle" class="size-3.5" />
+				{{ $t("dms_database.schemas.inspector.healthy") }}
+			</span>
+			<UButton
+				color="neutral"
+				variant="outline"
+				size="sm"
+				icon="i-ph-rows"
+				:label="$t('dms_database.schemas.browseData')"
+				class="ml-auto"
+				@click="browseData"
+			/>
+		</div>
+	</div>
+</template>

package/frontend-vue/app/composables/useDataBrowserGrid.ts

@@ -0,0 +1,162 @@
+// Per-tab grid state (paging, sort, filters, column widths) and a data cache
+// so switching tabs restores instantly without a refetch. Keyed by
+// BrowserTab.id.
+
+export interface ColumnFilterState {
+	mode: "is" | "contains";
+	value: string;
+}
+
+export interface GridState {
+	page: number;
+	pageSize: number;
+	sortKey: string | null;
+	sortDirection: "asc" | "desc";
+	search: string;
+	filters: Record<string, ColumnFilterState>;
+	columnWidths: Record<string, number>;
+}
+
+export interface GridColumn {
+	name: string;
+	// Coarse runtime type sampled by the backend: string | number | boolean |
+	// object | array | null | undefined.
+	type: string;
+	isPrimaryKey: boolean;
+}
+
+export interface GridData {
+	columns: GridColumn[];
+	rows: Record<string, unknown>[];
+	total: number;
+	primaryKey: string | null;
+	// Serialised query parameters that produced this payload; lets the grid
+	// skip refetching when nothing changed.
+	paramsKey: string;
+}
+
+export const GRID_PAGE_SIZES = [25, 50, 100, 200];
+
+function defaultGridState(): GridState {
+	return {
+		page: 0,
+		pageSize: 25,
+		sortKey: null,
+		sortDirection: "asc",
+		search: "",
+		filters: {},
+		columnWidths: {},
+	};
+}
+
+export function useDataBrowserGrid() {
+	const states = useDmsState<Record<string, GridState>>(
+		"dms-database-grid-states",
+		() => ({}),
+	);
+	const cache = useDmsState<Record<string, GridData>>(
+		"dms-database-grid-cache",
+		() => ({}),
+	);
+
+	function getState(tabId: string): GridState {
+		if (!states.value[tabId]) states.value[tabId] = defaultGridState();
+		return states.value[tabId];
+	}
+
+	function getCache(tabId: string): GridData | null {
+		return cache.value[tabId] ?? null;
+	}
+
+	function setCache(tabId: string, data: GridData) {
+		cache.value[tabId] = data;
+	}
+
+	function invalidate(tabId: string) {
+		Reflect.deleteProperty(cache.value, tabId);
+	}
+
+	// Forget everything about a closed tab.
+	function drop(tabId: string) {
+		Reflect.deleteProperty(states.value, tabId);
+		Reflect.deleteProperty(cache.value, tabId);
+	}
+
+	return { getState, getCache, setCache, invalidate, drop };
+}
+
+// --- query helpers shared by the grid ---
+
+// Reserved by the wire protocol for table selection (the backend's
+// SELECTION_FILTER_KEYS): a data filter on a column literally named `schema`,
+// `table` or `instance` would clobber the selection parameters, so it is never
+// emitted and the filter UI is disabled for these columns.
+const RESERVED_FILTER_FIELDS = new Set(["schema", "table", "instance"]);
+
+export function isReservedFilterField(field: string): boolean {
+	return RESERVED_FILTER_FIELDS.has(field);
+}
+
+// Normalized (empty-pruned, reserved-pruned, name-sorted) filter entries: the
+// single source for both the wire query and the cache key, so key-insertion
+// order or an empty draft can't cause spurious cache misses.
+function activeFilterEntries(
+	state: GridState,
+): Array<[string, ColumnFilterState]> {
+	return Object.entries(state.filters)
+		.filter(([field, filter]) => filter.value && !isReservedFilterField(field))
+		.sort(([a], [b]) => a.localeCompare(b));
+}
+
+// Single encoder for the `<mode>:<value>` wire tokens parseFilter decodes
+// server-side (src/utils/query.ts) — the grammar is defined here once instead
+// of scattered string literals.
+export function filterToken(mode: "is" | "contains", value: string): string {
+	return `${mode}:${value}`;
+}
+
+export function isFilterToken(value: string): string {
+	return filterToken("is", value);
+}
+
+// Selection filters identifying the table, in the wire format the browse
+// backend decodes (see resolveSelection in src/routes/data.ts).
+export function browseSelectionQuery(tab: BrowserTab): Record<string, string> {
+	const query: Record<string, string> = {
+		filter_schema: isFilterToken(tab.schema),
+		filter_table: isFilterToken(tab.table),
+	};
+	if (tab.instance !== DEFAULT_INSTANCE_VALUE) {
+		query.filter_instance = isFilterToken(tab.instance);
+	}
+	return query;
+}
+
+export function browseListQuery(
+	state: GridState,
+): Record<string, string | number> {
+	const query: Record<string, string | number> = {
+		offset: state.page * state.pageSize,
+		limit: state.pageSize,
+		sortDirection: state.sortDirection,
+	};
+	if (state.sortKey) query.sortKey = state.sortKey;
+	if (state.search) query.search = state.search;
+	for (const [field, filter] of activeFilterEntries(state)) {
+		query[`filter_${field}`] = filterToken(filter.mode, filter.value);
+	}
+	return query;
+}
+
+// Everything that changes the server payload (column widths deliberately not).
+export function browseParamsKey(tab: BrowserTab, state: GridState): string {
+	return JSON.stringify([
+		tab.id,
+		state.page,
+		state.pageSize,
+		state.sortKey,
+		state.sortDirection,
+		state.search,
+		activeFilterEntries(state),
+	]);
+}

package/frontend-vue/app/composables/useDataBrowserTabs.ts

@@ -0,0 +1,255 @@
+// Shared state for the data-browser tabs: each tab pins a (schema, instance,
+// table) triplet. The active tab is mirrored to the URL query (deep-links) and
+// the whole tab set is persisted to sessionStorage (survives a page refresh,
+// stays per browser tab).
+
+export const DEFAULT_INSTANCE_VALUE = "__DEFAULT__";
+export const CROSS_INSTANCE_VALUE = "__CROSS_INSTANCE__";
+
+export interface BrowserTab {
+	id: string;
+	schema: string;
+	// DEFAULT_INSTANCE_VALUE, CROSS_INSTANCE_VALUE or a named instance id.
+	instance: string;
+	table: string;
+	// VS Code-style preview tab: the next openTab reuses it instead of adding
+	// a new tab. At most one per session; pinning (double-click, pin icon,
+	// drag-reorder, editing a cell) clears the flag.
+	preview?: boolean;
+}
+
+const STORAGE_KEY = "dms-database:data-browser:tabs";
+
+function browserTabId(
+	schema: string,
+	instance: string,
+	table: string,
+): string {
+	return `${schema}::${instance}::${table}`;
+}
+
+interface PersistedTabs {
+	tabs: BrowserTab[];
+	activeId: string | null;
+}
+
+function readPersisted(): PersistedTabs | null {
+	if (typeof window === "undefined") return null;
+	try {
+		const raw = window.sessionStorage.getItem(STORAGE_KEY);
+		if (!raw) return null;
+		const parsed = JSON.parse(raw) as PersistedTabs;
+		if (!Array.isArray(parsed.tabs)) return null;
+		const tabs = parsed.tabs
+			.filter(
+				(tab) =>
+					tab &&
+					typeof tab.schema === "string" &&
+					typeof tab.instance === "string" &&
+					typeof tab.table === "string",
+			)
+			.map((tab) => ({
+				...tab,
+				id: browserTabId(tab.schema, tab.instance, tab.table),
+				preview: tab.preview === true,
+			}))
+			// Recomputed ids can collide on a legacy/hand-edited payload; duplicate
+			// ids would break the tab bar's v-for keys and closeTab.
+			.filter(
+				(tab, index, all) => all.findIndex((t) => t.id === tab.id) === index,
+			);
+		// The preview slot is a singleton; a hand-edited payload could carry
+		// several — honour only the first.
+		const firstPreview = tabs.findIndex((tab) => tab.preview);
+		for (const [index, tab] of tabs.entries()) {
+			if (index !== firstPreview) tab.preview = false;
+		}
+		const activeId = tabs.some((tab) => tab.id === parsed.activeId)
+			? parsed.activeId
+			: (tabs[0]?.id ?? null);
+		return { tabs, activeId };
+	} catch {
+		return null;
+	}
+}
+
+export function useDataBrowserTabs() {
+	const tabs = useDmsState<BrowserTab[]>("dms-database-browser-tabs", () => []);
+	const activeId = useDmsState<string | null>(
+		"dms-database-browser-active",
+		() => null,
+	);
+	const route = useDmsRoute();
+	const router = useDmsRouter();
+	// Captured at setup so closeTab can drop the closed tab's
+	// grid state itself instead of relying on every caller to remember to.
+	const grid = useDataBrowserGrid();
+
+	const activeTab = computed(
+		() => tabs.value.find((tab) => tab.id === activeId.value) ?? null,
+	);
+	// When tabs span several schemas the tab bar disambiguates its labels.
+	const hasMultipleSchemas = computed(
+		() => new Set(tabs.value.map((tab) => tab.schema)).size > 1,
+	);
+
+	function persist() {
+		if (typeof window === "undefined") return;
+		try {
+			window.sessionStorage.setItem(
+				STORAGE_KEY,
+				JSON.stringify({ tabs: tabs.value, activeId: activeId.value }),
+			);
+		} catch {
+			// Quota/private-mode failures only cost tab restoration.
+		}
+	}
+
+	// The URL carries the ACTIVE tab only (deep-links); per-tab grid state
+	// deliberately stays out of it.
+	function syncUrl() {
+		const tab = activeTab.value;
+		const query = { ...route.query };
+		delete query.schema;
+		delete query.instance;
+		delete query.table;
+		if (tab) {
+			query.schema = tab.schema;
+			query.table = tab.table;
+			if (tab.instance !== DEFAULT_INSTANCE_VALUE) query.instance = tab.instance;
+		}
+		if (
+			Object.keys(query).length === Object.keys(route.query).length &&
+			Object.entries(query).every(([key, value]) => route.query[key] === value)
+		) return;
+		router.replace({ query });
+	}
+
+	function activateTab(id: string) {
+		if (!tabs.value.some((tab) => tab.id === id)) return;
+		activeId.value = id;
+		syncUrl();
+		persist();
+	}
+
+	// Promote a preview tab to a permanent one (double-click, pin icon, drag).
+	function pinTab(id: string) {
+		const tab = tabs.value.find((t) => t.id === id);
+		if (!tab?.preview) return;
+		tabs.value = tabs.value.map((t) =>
+			t.id === id ? { ...t, preview: false } : t,
+		);
+		persist();
+	}
+
+	// Opens as a preview by default (VS Code-style: single-click reuses the
+	// preview slot). Pass preview = false for an explicitly permanent open
+	// (sidebar double-click, deep-links) — it also pins the tab if already
+	// open as preview.
+	function openTab(
+		schema: string,
+		instance: string,
+		table: string,
+		preview = true,
+	) {
+		const id = browserTabId(schema, instance, table);
+		const existing = tabs.value.find((tab) => tab.id === id);
+		if (existing) {
+			if (!preview) pinTab(id);
+			activateTab(id);
+			return;
+		}
+		const tab: BrowserTab = { id, schema, instance, table, preview };
+		const previewIndex = tabs.value.findIndex((t) => t.preview);
+		if (preview && previewIndex >= 0) {
+			// Reuse the preview slot in place: swap its content, drop the replaced
+			// tab's grid state (its id dies with it).
+			const replaced = tabs.value[previewIndex]!;
+			const next = [...tabs.value];
+			next[previewIndex] = tab;
+			tabs.value = next;
+			grid.drop(replaced.id);
+		} else {
+			tabs.value = [...tabs.value, tab];
+		}
+		activateTab(id);
+	}
+
+	function closeTab(id: string) {
+		const index = tabs.value.findIndex((tab) => tab.id === id);
+		if (index < 0) return;
+		const next = tabs.value.filter((tab) => tab.id !== id);
+		tabs.value = next;
+		if (activeId.value === id) {
+			// Right neighbour first, then left — mirrors browser tab behaviour.
+			activeId.value = (next[index] ?? next[index - 1])?.id ?? null;
+		}
+		// The closed tab's grid state and cached rows go with it — otherwise they
+		// leak for the rest of the session.
+		grid.drop(id);
+		syncUrl();
+		persist();
+	}
+
+	// Reorder (drag & drop): move the dragged tab to the target tab's position.
+	// Pure reorder — pin-on-drag is a gesture policy and lives at the drop site
+	// (the tab bar's onDrop), not in this primitive.
+	function moveTab(draggedId: string, targetId: string) {
+		if (draggedId === targetId) return;
+		const next = [...tabs.value];
+		const from = next.findIndex((tab) => tab.id === draggedId);
+		const to = next.findIndex((tab) => tab.id === targetId);
+		if (from < 0 || to < 0) return;
+		const [moved] = next.splice(from, 1);
+		if (!moved) return;
+		next.splice(to, 0, moved);
+		tabs.value = next;
+		persist();
+	}
+
+	// Restore persisted tabs, then let the URL win for the active selection so
+	// existing deep-links keep working. Call exactly once, from the page's
+	// onMounted.
+	function restore() {
+		const persisted = readPersisted();
+		if (persisted) {
+			tabs.value = persisted.tabs;
+			activeId.value = persisted.activeId;
+		}
+		const schema = route.query.schema;
+		const table = route.query.table;
+		if (
+			typeof schema === "string" &&
+			schema &&
+			typeof table === "string" &&
+			table
+		) {
+			const instance =
+				typeof route.query.instance === "string" && route.query.instance
+					? route.query.instance
+					: DEFAULT_INSTANCE_VALUE;
+			// Deep-links carry explicit intent (overview row double-click, the
+			// inspector's "browse data" button, shared URLs): open permanently, the
+			// preview slot is for casual sidebar browsing only.
+			openTab(schema, instance, table, false);
+		} else if (!schema && activeTab.value) {
+			// Only reclaim the URL when it carries no selection at all: a
+			// schema-only deep-link (?schema=X) is the sidebar's to honour and
+			// must not be clobbered by the restored tab.
+			syncUrl();
+		}
+	}
+
+	return {
+		tabs,
+		activeId,
+		activeTab,
+		hasMultipleSchemas,
+		openTab,
+		closeTab,
+		activateTab,
+		pinTab,
+		moveTab,
+		restore,
+	};
+}