@solidxai/core-ui 0.1.12-beta.0 → 0.1.12-beta.1

package/dist/routes/pages/admin/core/DatasourceIntrospectionPage.tsx

@@ -0,0 +1,1719 @@
+import {
+  Cog,
+  Database,
+  ExternalLink,
+  RefreshCw,
+  Save,
+  Search,
+  ShieldAlert,
+  Sparkles,
+} from "lucide-react";
+import { camelCase, startCase } from "lodash";
+import { useEffect, useMemo, useRef, useState } from "react";
+import { useDispatch } from "react-redux";
+import { useParams } from "react-router-dom";
+import { showToast } from "../../../../redux/features/toastSlice";
+import { SolidJsonEditor } from "../../../../components/core/json/SolidJsonEditor";
+import { Column, SolidDataTable } from "../../../../components/core/list/SolidDataTable";
+import {
+  SolidButton,
+  SolidCheckbox,
+  SolidDialog,
+  SolidDialogBody,
+  SolidDialogClose,
+  SolidDialogDescription,
+  SolidDialogFooter,
+  SolidDialogHeader,
+  SolidDialogSeparator,
+  SolidDialogTitle,
+  SolidInput,
+  SolidSelect,
+  SolidSpinner,
+  SolidSwitch,
+  SolidTabGroup,
+  SolidTextarea,
+} from "../../../../components/shad-cn-ui";
+import {
+  type DatasourceIntrospectionTableDetail,
+  type DatasourceIntrospectionMappingPreview,
+  type DatasourceIntrospectionMappingRequest,
+  type DatasourceIntrospectionTableRecord,
+  useApplyDatasourceIntrospectionMappingMutation,
+  useGetDatasourceIntrospectionBootstrapQuery,
+  useGetDatasourceIntrospectionTableDetailQuery,
+  useGetDatasourceIntrospectionTablesQuery,
+  usePreviewDatasourceIntrospectionMappingMutation,
+} from "../../../../redux/api/datasourceIntrospectionApi";
+import { useGetmodelByIdQuery } from "../../../../redux/api/modelApi";
+import "./DatasourceIntrospectionPage.css";
+
+type SessionSettings = {
+  relationInferenceEnabled: boolean;
+  prioritizeUnmappedTables: boolean;
+};
+
+type DrawerColumnDraft = {
+  columnName: string;
+  fieldName: string;
+  dataType: string;
+  solidFieldType: string;
+  ormType: string;
+  nullable: boolean;
+  defaultValue: string | null;
+  characterMaximumLength: number | null;
+  numericPrecision: number | null;
+  numericScale: number | null;
+  ordinalPosition: number | null;
+  isAutoGenerated: boolean;
+  handledBySuperclass: boolean;
+  superclassFieldName: string | null;
+  fieldId: number | null;
+  include: boolean;
+  matched: boolean;
+  isPrimaryKey: boolean;
+};
+
+type DrawerDraft = {
+  mapped: boolean;
+  modelId: number | null;
+  mappedModuleLabel: string | null;
+  singularName: string;
+  pluralName: string;
+  displayName: string;
+  description: string;
+  tableName: string;
+  schema: string | null;
+  dataSource: string;
+  dataSourceType: string;
+  legacyTableType: "none" | "existing_id" | "generated_id";
+  baseClassName: string;
+  userKeyField: string;
+  enableAuditTracking: boolean;
+  enableSoftDelete: boolean;
+  draftPublishWorkflow: boolean;
+  internationalisation: boolean;
+  columns: DrawerColumnDraft[];
+  preservedFields: any[];
+};
+
+function providerLabel(type: string) {
+  if (type === "postgres") return "PostgreSQL";
+  if (type === "mysql") return "MySQL";
+  if (type === "mssql") return "MS SQL Server";
+  return type;
+}
+
+const scalarFieldTypeOptions = [
+  { value: "shortText", label: "Short Text" },
+  { value: "longText", label: "Long Text" },
+  { value: "richText", label: "Rich Text" },
+  { value: "boolean", label: "Boolean" },
+  { value: "int", label: "Integer" },
+  { value: "bigint", label: "Big Integer" },
+  { value: "decimal", label: "Decimal" },
+  { value: "date", label: "Date" },
+  { value: "datetime", label: "Date Time" },
+  { value: "time", label: "Time" },
+  { value: "json", label: "JSON" },
+  { value: "uuid", label: "UUID" },
+  { value: "email", label: "Email" },
+  { value: "password", label: "Password" },
+];
+
+const scalarFieldTypeValueSet = new Set(scalarFieldTypeOptions.map((option) => option.value));
+
+function getDefaultOrmTypeForSolidFieldType(dataSourceType: string, solidFieldType: string) {
+  const normalizedDatasourceType = dataSourceType.toLowerCase();
+
+  const ormTypesByDatasource: Record<string, Record<string, string>> = {
+    mssql: {
+      shortText: "varchar",
+      longText: "nvarchar",
+      richText: "nvarchar",
+      boolean: "bit",
+      int: "int",
+      bigint: "bigint",
+      decimal: "numeric",
+      date: "date",
+      datetime: "datetime",
+      time: "time",
+      json: "simple-json",
+      uuid: "uniqueidentifier",
+      email: "nvarchar",
+      password: "nvarchar",
+    },
+    mysql: {
+      shortText: "varchar",
+      longText: "longtext",
+      richText: "longtext",
+      boolean: "boolean",
+      int: "int",
+      bigint: "int",
+      decimal: "decimal",
+      date: "date",
+      datetime: "datetime",
+      time: "time",
+      json: "json",
+      uuid: "varchar",
+      email: "varchar",
+      password: "varchar",
+    },
+    postgres: {
+      shortText: "varchar",
+      longText: "text",
+      richText: "text",
+      boolean: "boolean",
+      int: "integer",
+      bigint: "bigint",
+      decimal: "decimal",
+      date: "date",
+      datetime: "timestamp",
+      time: "time",
+      json: "json",
+      uuid: "varchar",
+      email: "varchar",
+      password: "varchar",
+    },
+  };
+
+  return ormTypesByDatasource[normalizedDatasourceType]?.[solidFieldType] ?? "varchar";
+}
+
+function legacyTypeLabel(value: string) {
+  if (value === "generated_id") return "Legacy generated id";
+  if (value === "existing_id") return "Legacy existing id";
+  return "Legacy generated id";
+}
+
+function statusLabel(record: DatasourceIntrospectionTableRecord) {
+  return record.mapped ? "Mapped" : "Ready to map";
+}
+
+function readQueryError(error: any) {
+  return (
+    error?.data?.message
+    || error?.error
+    || error?.message
+    || "Something went wrong."
+  );
+}
+
+function normalizeName(value: string) {
+  return value.trim().toLowerCase();
+}
+
+function findMatchingModelField(column: DatasourceIntrospectionTableDetail["columns"][number], modelFields: any[]) {
+  return modelFields.find((field) => {
+    if (field?.isSystem) return false;
+
+    const sameColumnName = normalizeName(field?.columnName ?? "") === normalizeName(column.columnName);
+    if (sameColumnName) return true;
+
+    return Boolean(column.isAutoGenerated && column.fieldName === "id" && field?.name === "id");
+  }) ?? null;
+}
+
+function sanitizeExistingFieldPayload(field: any) {
+  const {
+    createdAt,
+    updatedAt,
+    deletedAt,
+    model,
+    mediaStorageProvider,
+    identifier,
+    ...rest
+  } = field ?? {};
+
+  if (mediaStorageProvider?.id && !rest.mediaStorageProviderId) {
+    rest.mediaStorageProviderId = mediaStorageProvider.id;
+  }
+
+  return rest;
+}
+
+function buildDrawerDraft(
+  tableDetail: DatasourceIntrospectionTableDetail,
+  selectedTable: DatasourceIntrospectionTableRecord,
+  mappedModelData?: any,
+): DrawerDraft {
+  const modelData = selectedTable.mapped ? (mappedModelData?.data ?? null) : null;
+  const modelFields = modelData?.fields ?? [];
+  const preservedFields = modelFields.map((field: any) => sanitizeExistingFieldPayload(field));
+  const modelUserKeyField =
+    modelData?.userKeyField?.name
+    || modelFields.find((field: any) => field?.isUserKey)?.name
+    || "";
+
+  const columns: DrawerColumnDraft[] = tableDetail.columns.map((column) => {
+    const matchingField = findMatchingModelField(column, modelFields);
+    return {
+      columnName: column.columnName,
+      fieldName: matchingField?.name ?? column.fieldName,
+      dataType: column.dataType,
+      solidFieldType: matchingField?.type ?? column.solidFieldType,
+      ormType: matchingField?.ormType ?? column.ormType,
+      nullable: column.nullable,
+      defaultValue: matchingField?.defaultValue ?? column.defaultValue,
+      characterMaximumLength: column.characterMaximumLength,
+      numericPrecision: column.numericPrecision,
+      numericScale: column.numericScale,
+      ordinalPosition: column.ordinalPosition,
+      isAutoGenerated: column.isAutoGenerated,
+      handledBySuperclass: column.handledBySuperclass,
+      superclassFieldName: column.superclassFieldName,
+      fieldId: matchingField?.id ?? null,
+      include: column.handledBySuperclass ? false : Boolean(matchingField) || !selectedTable.mapped,
+      matched: Boolean(matchingField),
+      isPrimaryKey: Boolean(matchingField?.isPrimaryKey) || (column.isAutoGenerated && column.fieldName === "id"),
+    };
+  });
+
+  const draftUserKeyField = modelUserKeyField || tableDetail.suggestedMetadata.userKeyField;
+
+  return {
+    mapped: selectedTable.mapped,
+    modelId: selectedTable.mappedModelId,
+    mappedModuleLabel: selectedTable.mappedModuleDisplayName || selectedTable.mappedModuleName || null,
+    singularName: modelData?.singularName ?? tableDetail.suggestedMetadata.singularName,
+    pluralName: modelData?.pluralName ?? tableDetail.suggestedMetadata.pluralName,
+    displayName: modelData?.displayName ?? tableDetail.suggestedMetadata.displayName,
+    description: modelData?.description ?? tableDetail.suggestedMetadata.displayName,
+    tableName: modelData?.tableName ?? tableDetail.suggestedMetadata.tableName,
+    schema: tableDetail.suggestedMetadata.schema,
+    dataSource: modelData?.dataSource ?? tableDetail.suggestedMetadata.dataSource,
+    dataSourceType: modelData?.dataSourceType ?? tableDetail.suggestedMetadata.dataSourceType,
+    legacyTableType: modelData?.legacyTableType ?? tableDetail.suggestedMetadata.legacyTableType,
+    baseClassName: tableDetail.suggestedMetadata.baseClassName,
+    userKeyField: draftUserKeyField,
+    enableAuditTracking: modelData?.enableAuditTracking ?? true,
+    enableSoftDelete: modelData?.enableSoftDelete ?? false,
+    draftPublishWorkflow: modelData?.draftPublishWorkflow ?? false,
+    internationalisation: modelData?.internationalisation ?? false,
+    columns,
+    preservedFields,
+  };
+}
+
+function getDrawerValidationErrors(draft: DrawerDraft) {
+  const errors: string[] = [];
+  const includedColumns = draft.columns.filter((column) => !column.handledBySuperclass && column.include);
+  const seenFieldNames = new Set<string>();
+
+  if (!draft.singularName.trim()) {
+    errors.push("Singular name is required.");
+  }
+  if (!draft.pluralName.trim()) {
+    errors.push("Plural name is required.");
+  }
+  if (!draft.displayName.trim()) {
+    errors.push("Display name is required.");
+  }
+  if (!includedColumns.length) {
+    errors.push("Select at least one physical column to include in the mapping.");
+  }
+
+  for (const column of includedColumns) {
+    const normalizedFieldName = column.fieldName.trim();
+    if (!normalizedFieldName) {
+      errors.push(`Field name is required for column "${column.columnName}".`);
+      continue;
+    }
+
+    if (!scalarFieldTypeValueSet.has(column.solidFieldType)) {
+      errors.push(`SolidX type "${column.solidFieldType}" is not allowed in step 1 for column "${column.columnName}".`);
+      continue;
+    }
+
+    if (seenFieldNames.has(normalizedFieldName.toLowerCase())) {
+      errors.push(`Field name "${normalizedFieldName}" is duplicated in the mapping draft.`);
+      continue;
+    }
+
+    seenFieldNames.add(normalizedFieldName.toLowerCase());
+  }
+
+  if (!draft.userKeyField.trim()) {
+    errors.push("Choose a user key field before saving the mapping.");
+  } else {
+    const userKeyExists = includedColumns.some((column) => column.fieldName === draft.userKeyField);
+    if (!userKeyExists) {
+      errors.push("The chosen user key field must remain part of the mapped columns.");
+    }
+  }
+
+  if (draft.legacyTableType === "existing_id") {
+    const hasPrimaryKey = includedColumns.some((column) => column.isPrimaryKey);
+    if (!hasPrimaryKey) {
+      errors.push("Legacy existing-id mappings must keep the generated id column mapped to field name \"id\".");
+    }
+  }
+
+  return errors;
+}
+
+function buildMappingRequest(
+  draft: DrawerDraft,
+  plannedMigrationTimestamp?: number | null,
+): DatasourceIntrospectionMappingRequest {
+  return {
+    mapped: draft.mapped,
+    modelId: draft.modelId,
+    singularName: draft.singularName.trim(),
+    pluralName: draft.pluralName.trim(),
+    displayName: draft.displayName.trim(),
+    description: draft.description.trim() || draft.displayName.trim(),
+    tableName: draft.tableName,
+    schema: draft.schema ?? null,
+    dataSource: draft.dataSource,
+    dataSourceType: draft.dataSourceType,
+    legacyTableType: draft.legacyTableType,
+    baseClassName: draft.baseClassName,
+    userKeyField: draft.userKeyField,
+    enableAuditTracking: draft.enableAuditTracking,
+    enableSoftDelete: draft.enableSoftDelete,
+    draftPublishWorkflow: draft.draftPublishWorkflow,
+    internationalisation: draft.internationalisation,
+    plannedMigrationTimestamp: plannedMigrationTimestamp ?? null,
+    columns: draft.columns.map((column) => ({
+      columnName: column.columnName,
+      fieldName: column.fieldName,
+      dataType: column.dataType,
+      solidFieldType: column.solidFieldType,
+      ormType: column.ormType,
+      nullable: column.nullable,
+      defaultValue: column.defaultValue,
+      characterMaximumLength: column.characterMaximumLength,
+      numericPrecision: column.numericPrecision,
+      numericScale: column.numericScale,
+      ordinalPosition: column.ordinalPosition,
+      isAutoGenerated: column.isAutoGenerated,
+      handledBySuperclass: column.handledBySuperclass,
+      superclassFieldName: column.superclassFieldName,
+      fieldId: column.fieldId,
+      include: column.include,
+      matched: column.matched,
+      isPrimaryKey: column.isPrimaryKey,
+    })),
+  };
+}
+
+function parseAndValidateReviewedModelJson(
+  metadataJsonText: string,
+  draft: DrawerDraft,
+) {
+  let parsed: any;
+
+  try {
+    parsed = JSON.parse(metadataJsonText);
+  } catch (error: any) {
+    return {
+      error: `Metadata JSON is not valid JSON: ${error?.message ?? "Unknown parse error."}`,
+      parsed: null,
+    };
+  }
+
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    return {
+      error: "Metadata JSON must be an object.",
+      parsed: null,
+    };
+  }
+
+  const requiredStringKeys = [
+    "singularName",
+    "pluralName",
+    "displayName",
+    "description",
+    "dataSource",
+    "dataSourceType",
+    "tableName",
+    "userKeyFieldUserKey",
+  ];
+
+  for (const key of requiredStringKeys) {
+    if (typeof parsed[key] !== "string" || !parsed[key].trim()) {
+      return {
+        error: `Metadata JSON must include a non-empty "${key}" string.`,
+        parsed: null,
+      };
+    }
+  }
+
+  const immutableChecks: Array<{ key: string; expected: string }> = [
+    { key: "dataSource", expected: draft.dataSource },
+    { key: "dataSourceType", expected: draft.dataSourceType },
+    { key: "tableName", expected: draft.tableName },
+    { key: "legacyTableType", expected: draft.legacyTableType },
+  ];
+
+  for (const check of immutableChecks) {
+    if (`${parsed[check.key] ?? ""}` !== `${check.expected}`) {
+      return {
+        error: `Metadata JSON cannot change immutable binding key "${check.key}".`,
+        parsed: null,
+      };
+    }
+  }
+
+  const requiredBooleanKeys = [
+    "enableAuditTracking",
+    "enableSoftDelete",
+    "draftPublishWorkflow",
+    "internationalisation",
+  ];
+
+  for (const key of requiredBooleanKeys) {
+    if (typeof parsed[key] !== "boolean") {
+      return {
+        error: `Metadata JSON must include a boolean "${key}" value.`,
+        parsed: null,
+      };
+    }
+  }
+
+  if (!Array.isArray(parsed.fields)) {
+    return {
+      error: "Metadata JSON must include a fields array.",
+      parsed: null,
+    };
+  }
+
+  const seenFieldNames = new Set<string>();
+  for (const [index, field] of parsed.fields.entries()) {
+    if (!field || typeof field !== "object" || Array.isArray(field)) {
+      return {
+        error: `Field at index ${index} is not a valid object.`,
+        parsed: null,
+      };
+    }
+
+    if (typeof field.name !== "string" || !field.name.trim()) {
+      return {
+        error: `Field at index ${index} must include a non-empty "name".`,
+        parsed: null,
+      };
+    }
+
+    if (typeof field.type !== "string" || !field.type.trim()) {
+      return {
+        error: `Field "${field.name}" must include a non-empty "type".`,
+        parsed: null,
+      };
+    }
+
+    if (typeof field.ormType !== "string" || !field.ormType.trim()) {
+      return {
+        error: `Field "${field.name}" must include a non-empty "ormType".`,
+        parsed: null,
+      };
+    }
+
+    if (typeof field.columnName !== "string" || !field.columnName.trim()) {
+      return {
+        error: `Field "${field.name}" must include a non-empty "columnName".`,
+        parsed: null,
+      };
+    }
+
+    const normalizedFieldName = field.name.trim().toLowerCase();
+    if (seenFieldNames.has(normalizedFieldName)) {
+      return {
+        error: `Field name "${field.name}" is duplicated in metadata JSON.`,
+        parsed: null,
+      };
+    }
+
+    seenFieldNames.add(normalizedFieldName);
+  }
+
+  if (!parsed.fields.some((field: any) => field?.name === parsed.userKeyFieldUserKey && !field?.isMarkedForRemoval)) {
+    return {
+      error: "Metadata JSON must keep userKeyFieldUserKey present in the fields array.",
+      parsed: null,
+    };
+  }
+
+  return {
+    error: null,
+    parsed,
+  };
+}
+
+export function DatasourceIntrospectionPage() {
+  const params = useParams();
+  const dispatch = useDispatch();
+  const moduleId = Number(params.moduleId ?? 0);
+  const isValidModuleId = Number.isFinite(moduleId) && moduleId > 0;
+
+  const {
+    data: bootstrap,
+    isLoading: isBootstrapLoading,
+    isFetching: isBootstrapFetching,
+    error: bootstrapError,
+    refetch: refetchBootstrap,
+  } = useGetDatasourceIntrospectionBootstrapQuery(moduleId, {
+    skip: !isValidModuleId,
+  });
+
+  const [selectedDatasource, setSelectedDatasource] = useState("");
+  const [selectedTableKey, setSelectedTableKey] = useState("");
+  const [tableSearch, setTableSearch] = useState("");
+  const [settingsOpen, setSettingsOpen] = useState(false);
+  const [settingsTab, setSettingsTab] = useState("datasource-info");
+  const [drawerOpen, setDrawerOpen] = useState(false);
+  const [drawerDraft, setDrawerDraft] = useState<DrawerDraft | null>(null);
+  const [drawerTab, setDrawerTab] = useState("general-info");
+  const [drawerStep, setDrawerStep] = useState<"edit" | "review">("edit");
+  const [reviewTab, setReviewTab] = useState("metadata-json");
+  const [mappingPreview, setMappingPreview] = useState<DatasourceIntrospectionMappingPreview | null>(null);
+  const [reviewedMetadataJsonValue, setReviewedMetadataJsonValue] = useState<any>(null);
+  const [metadataJsonText, setMetadataJsonText] = useState("");
+  const [metadataJsonValidationError, setMetadataJsonValidationError] = useState<string | null>(null);
+  const [metadataJsonResetToken, setMetadataJsonResetToken] = useState("initial");
+  const [drawerBootstrapping, setDrawerBootstrapping] = useState(false);
+  const [sessionSettings, setSessionSettings] = useState<SessionSettings>({
+    relationInferenceEnabled: false,
+    prioritizeUnmappedTables: true,
+  });
+  const [draftSessionSettings, setDraftSessionSettings] = useState<SessionSettings>(sessionSettings);
+  const drawerBootstrapTimerRef = useRef<number | null>(null);
+
+  const scrollDrawerBodyToTop = () => {
+    if (typeof document === "undefined") return;
+
+    window.requestAnimationFrame(() => {
+      const drawerBody = document.querySelector<HTMLDivElement>(".sdix-drawer-body");
+      drawerBody?.scrollTo({ top: 0, left: 0 });
+    });
+  };
+
+  const [
+    previewMapping,
+    { isLoading: isPreviewMappingLoading },
+  ] = usePreviewDatasourceIntrospectionMappingMutation();
+
+  const [
+    applyMapping,
+    { isLoading: isApplyMappingLoading },
+  ] = useApplyDatasourceIntrospectionMappingMutation();
+
+  const isSavingMapping = isApplyMappingLoading;
+
+  useEffect(() => {
+    if (!bootstrap) return;
+    if (selectedDatasource) return;
+    if (bootstrap.recommendedDatasourceName) {
+      setSelectedDatasource(bootstrap.recommendedDatasourceName);
+    }
+  }, [bootstrap, selectedDatasource]);
+
+  useEffect(() => {
+    setSelectedTableKey("");
+    setDrawerDraft(null);
+    setDrawerOpen(false);
+    setTableSearch("");
+    setDrawerStep("edit");
+    setReviewTab("metadata-json");
+    setMappingPreview(null);
+    setReviewedMetadataJsonValue(null);
+    setMetadataJsonText("");
+    setMetadataJsonValidationError(null);
+    setMetadataJsonResetToken(`datasource-${Date.now()}`);
+  }, [selectedDatasource]);
+
+  useEffect(() => () => {
+    if (drawerBootstrapTimerRef.current) {
+      window.clearTimeout(drawerBootstrapTimerRef.current);
+    }
+  }, []);
+
+  useEffect(() => {
+    if (!drawerOpen) return;
+    scrollDrawerBodyToTop();
+  }, [drawerOpen, drawerStep, drawerTab, reviewTab, selectedTableKey]);
+
+  const datasourceOptions = useMemo(
+    () => (bootstrap?.datasources ?? []).map((datasource) => ({
+      label: `${datasource.displayName} (${providerLabel(datasource.type)})`,
+      value: datasource.name,
+    })),
+    [bootstrap],
+  );
+
+  const {
+    data: tablesResponse,
+    isLoading: isTablesLoading,
+    isFetching: isTablesFetching,
+    error: tablesError,
+    refetch: refetchTables,
+  } = useGetDatasourceIntrospectionTablesQuery(
+    { moduleId, datasource: selectedDatasource },
+    {
+      skip: !isValidModuleId || !selectedDatasource,
+    },
+  );
+
+  const selectedTable = useMemo(
+    () => tablesResponse?.records?.find((record) => `${record.schema ?? ""}::${record.tableName}` === selectedTableKey) ?? null,
+    [tablesResponse, selectedTableKey],
+  );
+
+  const {
+    data: tableDetail,
+    isLoading: isTableDetailLoading,
+    isFetching: isTableDetailFetching,
+    error: tableDetailError,
+    refetch: refetchTableDetail,
+  } = useGetDatasourceIntrospectionTableDetailQuery(
+    {
+      moduleId,
+      datasource: selectedDatasource,
+      table: selectedTable?.tableName ?? "",
+      schema: selectedTable?.schema ?? undefined,
+    },
+    {
+      skip: !drawerOpen || !isValidModuleId || !selectedDatasource || !selectedTable || !!tablesResponse?.synchronizeBlocked,
+    },
+  );
+
+  const {
+    data: mappedModelResponse,
+    isLoading: isMappedModelLoading,
+    isFetching: isMappedModelFetching,
+    error: mappedModelError,
+  } = useGetmodelByIdQuery(selectedTable?.mappedModelId ?? 0, {
+    skip: !drawerOpen || !selectedTable?.mapped || !selectedTable?.mappedModelId,
+  });
+
+  const mappedModelData = mappedModelResponse?.data;
+  const selectedDatasourceRecord = bootstrap?.datasources?.find((datasource) => datasource.name === selectedDatasource) ?? null;
+  const drawerLoadingError = selectedTable?.mapped ? (tableDetailError || mappedModelError) : tableDetailError;
+  const isDrawerBlockingLoading = Boolean(
+    selectedTable
+    && (
+      drawerBootstrapping
+      || !drawerDraft
+      || isTableDetailLoading
+      || isTableDetailFetching
+      || (selectedTable.mapped && (isMappedModelLoading || isMappedModelFetching))
+    ),
+  );
+
+  useEffect(() => {
+    if (!drawerOpen || !selectedTable || !tableDetail) return;
+    if (selectedTable.mapped && (!mappedModelData || mappedModelData.id !== selectedTable.mappedModelId)) return;
+
+    if (drawerBootstrapTimerRef.current) {
+      window.clearTimeout(drawerBootstrapTimerRef.current);
+    }
+
+    setDrawerDraft(buildDrawerDraft(
+      tableDetail,
+      selectedTable,
+      selectedTable.mapped ? mappedModelResponse : undefined,
+    ));
+    drawerBootstrapTimerRef.current = window.setTimeout(() => {
+      setDrawerBootstrapping(false);
+    }, 150);
+  }, [drawerOpen, selectedTable, tableDetail, mappedModelData, mappedModelResponse]);
+
+  const filteredRecords = useMemo(() => {
+    const records = [...(tablesResponse?.records ?? [])];
+    const searchNeedle = tableSearch.trim().toLowerCase();
+
+    const filtered = searchNeedle
+      ? records.filter((record) => {
+        const haystack = `${record.tableName} ${record.schema ?? ""} ${record.mappedModelSingularName ?? ""} ${record.mappedModelDisplayName ?? ""}`.toLowerCase();
+        return haystack.includes(searchNeedle);
+      })
+      : records;
+
+    if (sessionSettings.prioritizeUnmappedTables) {
+      filtered.sort((left, right) => {
+        if (left.mapped !== right.mapped) {
+          return left.mapped ? 1 : -1;
+        }
+
+        const leftLabel = `${left.schema ?? ""}.${left.tableName}`.toLowerCase();
+        const rightLabel = `${right.schema ?? ""}.${right.tableName}`.toLowerCase();
+        return leftLabel.localeCompare(rightLabel);
+      });
+    }
+
+    return filtered;
+  }, [sessionSettings.prioritizeUnmappedTables, tableSearch, tablesResponse?.records]);
+
+  const drawerUserKeyOptions = useMemo(() => {
+    const options = new Map<string, { label: string; value: string }>();
+
+    tableDetail?.userKeyCandidates?.forEach((candidate) => {
+      options.set(candidate.name, {
+        label: `${candidate.label} · ${candidate.reason}`,
+        value: candidate.name,
+      });
+    });
+
+    drawerDraft?.columns
+      .filter((column) => !column.handledBySuperclass && column.include)
+      .forEach((column) => {
+        if (!options.has(column.fieldName)) {
+          options.set(column.fieldName, {
+            label: `${column.fieldName} · mapped from ${column.columnName}`,
+            value: column.fieldName,
+          });
+        }
+      });
+
+    return Array.from(options.values());
+  }, [drawerDraft?.columns, tableDetail?.userKeyCandidates]);
+
+  const settingsTabs = [
+    {
+      value: "datasource-info",
+      label: "Datasource Info",
+      content: (
+        <div className="sdix-settings-grid">
+          <div className="sdix-settings-static">
+            <span>Target module</span>
+            <strong>{bootstrap?.module?.displayName}</strong>
+          </div>
+          <div className="sdix-settings-static">
+            <span>Default datasource</span>
+            <strong>{bootstrap?.module?.defaultDataSource || "Not set"}</strong>
+          </div>
+          <div className="sdix-settings-static">
+            <span>Datasource name</span>
+            <strong>{selectedDatasourceRecord?.displayName || "Not selected"}</strong>
+          </div>
+          <div className="sdix-settings-static">
+            <span>Datasource type</span>
+            <strong>{selectedDatasourceRecord ? providerLabel(selectedDatasourceRecord.type) : "-"}</strong>
+          </div>
+          <div className="sdix-settings-static">
+            <span>Host</span>
+            <strong>{selectedDatasourceRecord?.host || "-"}</strong>
+          </div>
+          <div className="sdix-settings-static">
+            <span>Port</span>
+            <strong>{selectedDatasourceRecord?.port ?? "-"}</strong>
+          </div>
+          <div className="sdix-settings-static">
+            <span>Database</span>
+            <strong>{selectedDatasourceRecord?.database || "-"}</strong>
+          </div>
+          <div className="sdix-settings-static">
+            <span>Env Prefix</span>
+            <strong>{selectedDatasourceRecord?.envPrefix || "-"}</strong>
+          </div>
+          <div className="sdix-settings-static">
+            <span>Synchronize</span>
+            <strong>{selectedDatasourceRecord ? (selectedDatasourceRecord.synchronize === true ? "true" : "false") : "-"}</strong>
+          </div>
+        </div>
+      ),
+    },
+    {
+      value: "session-settings",
+      label: "Session Settings",
+      content: (
+        <div className="sdix-settings-grid">
+          <div className="sdix-settings-row">
+            <div>
+              <label>Relation inference</label>
+              <p>Keep this off until we deliberately introduce relation discovery across engines.</p>
+            </div>
+            <SolidSwitch
+              checked={draftSessionSettings.relationInferenceEnabled}
+              onChange={(checked) => setDraftSessionSettings((current) => ({ ...current, relationInferenceEnabled: checked }))}
+            />
+          </div>
+
+          <div className="sdix-settings-row">
+            <div>
+              <label>Prioritize unmapped tables</label>
+              <p>Bubble unmapped tables to the top of the inventory so the first pass stays focused.</p>
+            </div>
+            <SolidSwitch
+              checked={draftSessionSettings.prioritizeUnmappedTables}
+              onChange={(checked) => setDraftSessionSettings((current) => ({ ...current, prioritizeUnmappedTables: checked }))}
+            />
+          </div>
+        </div>
+      ),
+    },
+  ];
+
+  const handleRefresh = async () => {
+    await refetchBootstrap();
+    if (selectedDatasource) {
+      await refetchTables();
+    }
+    if (selectedTable) {
+      await refetchTableDetail();
+    }
+  };
+
+  const openTableDrawer = (record: DatasourceIntrospectionTableRecord) => {
+    if (drawerBootstrapTimerRef.current) {
+      window.clearTimeout(drawerBootstrapTimerRef.current);
+    }
+
+    setSelectedTableKey(`${record.schema ?? ""}::${record.tableName}`);
+    setDrawerDraft(null);
+    setDrawerTab("general-info");
+    setDrawerStep("edit");
+    setReviewTab("metadata-json");
+    setMappingPreview(null);
+    setReviewedMetadataJsonValue(null);
+    setMetadataJsonText("");
+    setMetadataJsonValidationError(null);
+    setMetadataJsonResetToken(`table-${record.schema ?? "default"}-${record.tableName}-${Date.now()}`);
+    setDrawerBootstrapping(true);
+    setDrawerOpen(true);
+  };
+
+  const applyDraftSettings = () => {
+    setSessionSettings(draftSessionSettings);
+    setSettingsOpen(false);
+  };
+
+  const updateDrawerDraft = (updater: (current: DrawerDraft) => DrawerDraft) => {
+    setMappingPreview(null);
+    setDrawerDraft((current) => (current ? updater(current) : current));
+  };
+
+  const updateGeneralField = (field: keyof DrawerDraft, value: any) => {
+    updateDrawerDraft((current) => ({ ...current, [field]: value }));
+  };
+
+  const updateColumnFieldName = (columnName: string, nextFieldName: string) => {
+    updateDrawerDraft((current) => ({
+      ...current,
+      columns: current.columns.map((column) => {
+        if (column.columnName !== columnName) return column;
+        return { ...column, fieldName: camelCase(nextFieldName) };
+      }),
+      userKeyField: current.userKeyField === current.columns.find((column) => column.columnName === columnName)?.fieldName
+        ? camelCase(nextFieldName)
+        : current.userKeyField,
+    }));
+  };
+
+  const updateColumnSolidFieldType = (columnName: string, nextSolidFieldType: string) => {
+    updateDrawerDraft((current) => ({
+      ...current,
+      columns: current.columns.map((column) => {
+        if (column.columnName !== columnName) return column;
+        if (column.handledBySuperclass) return column;
+
+        return {
+          ...column,
+          solidFieldType: nextSolidFieldType,
+          ormType: getDefaultOrmTypeForSolidFieldType(current.dataSourceType, nextSolidFieldType),
+        };
+      }),
+    }));
+  };
+
+  const setColumnIncluded = (columnName: string, include: boolean) => {
+    updateDrawerDraft((current) => ({
+      ...current,
+      columns: current.columns.map((column) => {
+        if (column.columnName !== columnName) return column;
+        if (column.handledBySuperclass || column.isPrimaryKey) return column;
+        return { ...column, include };
+      }),
+    }));
+  };
+
+  const changeUserKeyField = (fieldName: string) => {
+    updateDrawerDraft((current) => ({
+      ...current,
+      userKeyField: fieldName,
+      columns: current.columns.map((column) => (
+        column.fieldName === fieldName
+          ? { ...column, include: column.handledBySuperclass ? false : true }
+          : column
+      )),
+    }));
+  };
+
+  const setUnmappedColumnsIncluded = (include: boolean) => {
+    updateDrawerDraft((current) => ({
+      ...current,
+      columns: current.columns.map((column) => {
+        if (column.handledBySuperclass || column.matched || column.isPrimaryKey) {
+          return column;
+        }
+        return { ...column, include };
+      }),
+    }));
+  };
+
+  const openMappedModelForm = () => {
+    const targetModelId = drawerDraft?.modelId ?? selectedTable?.mappedModelId;
+    if (!targetModelId) return;
+    window.open(`/admin/core/solid-core/model-metadata/form/${targetModelId}`, "_blank", "noopener,noreferrer");
+  };
+
+  const viewChanges = async () => {
+    if (!drawerDraft || !bootstrap?.module?.id) return;
+
+    const validationErrors = getDrawerValidationErrors(drawerDraft);
+    if (validationErrors.length) {
+      validationErrors.forEach((detail) => {
+        dispatch(showToast({ severity: "error", summary: "Validation", detail }));
+      });
+      return;
+    }
+
+    try {
+      const preview = await previewMapping({
+        moduleId: bootstrap.module.id,
+        payload: buildMappingRequest(drawerDraft),
+      }).unwrap();
+
+      setMappingPreview(preview);
+      setReviewedMetadataJsonValue(preview.metadataJson.model);
+      setMetadataJsonText(JSON.stringify(preview.metadataJson.model, null, 2));
+      setMetadataJsonValidationError(null);
+      setMetadataJsonResetToken(`preview-${preview.metadataJson.filePath}-${Date.now()}`);
+      setReviewTab("metadata-json");
+      setDrawerStep("review");
+    } catch (error: any) {
+      dispatch(showToast({
+        severity: "error",
+        summary: "Preview failed",
+        detail: readQueryError(error),
+      }));
+    }
+  };
+
+  const saveMapping = async () => {
+    if (!drawerDraft || !bootstrap?.module?.id) return;
+
+    const validationErrors = getDrawerValidationErrors(drawerDraft);
+    if (validationErrors.length) {
+      validationErrors.forEach((detail) => {
+        dispatch(showToast({ severity: "error", summary: "Validation", detail }));
+      });
+      setDrawerStep("edit");
+      return;
+    }
+
+    const reviewedModelValidation = parseAndValidateReviewedModelJson(metadataJsonText, drawerDraft);
+    if (reviewedModelValidation.error || !reviewedModelValidation.parsed) {
+      setMetadataJsonValidationError(reviewedModelValidation.error ?? "Metadata JSON is invalid.");
+      setReviewTab("metadata-json");
+      setDrawerStep("review");
+      dispatch(showToast({
+        severity: "error",
+        summary: "Validation",
+        detail: reviewedModelValidation.error ?? "Metadata JSON is invalid.",
+      }));
+      return;
+    }
+
+    setMetadataJsonValidationError(null);
+
+    try {
+      const response = await applyMapping({
+        moduleId: bootstrap.module.id,
+        payload: {
+          ...buildMappingRequest(drawerDraft, mappingPreview?.migration.timestamp ?? null),
+          reviewedModel: reviewedModelValidation.parsed,
+        },
+      }).unwrap();
+
+      dispatch(showToast({
+        severity: "success",
+        summary: "Saved",
+        detail: response.migration.written
+          ? "The mapping, metadata JSON, and migration template were written successfully."
+          : drawerDraft.mapped
+            ? "The model mapping was updated and written back to metadata JSON."
+            : "The model mapping was created and written to metadata JSON.",
+      }));
+
+      setDrawerOpen(false);
+      setDrawerDraft(null);
+      setMappingPreview(null);
+      setReviewedMetadataJsonValue(null);
+      setMetadataJsonText("");
+      setMetadataJsonValidationError(null);
+      setMetadataJsonResetToken(`saved-${Date.now()}`);
+      setDrawerStep("edit");
+      await refetchTables();
+      await refetchBootstrap();
+    } catch (error: any) {
+      dispatch(showToast({
+        severity: "error",
+        summary: "Save failed",
+        detail: readQueryError(error),
+      }));
+    }
+  };
+
+  if (!isValidModuleId) {
+    return (
+      <div className="sdix-page">
+        <div className="sdix-empty-state">
+          <ShieldAlert size={24} />
+          <h2>Module not found</h2>
+          <p>Open datasource introspection from a saved module so SolidX knows which module should receive the mapped models.</p>
+        </div>
+      </div>
+    );
+  }
+
+  const selectableUnmappedColumns = drawerDraft?.columns.filter(
+    (column) => !column.handledBySuperclass && !column.matched && !column.isPrimaryKey,
+  ) ?? [];
+  const allSelectableUnmappedIncluded = selectableUnmappedColumns.length > 0
+    && selectableUnmappedColumns.every((column) => column.include);
+  const drawerRawDdl = tableDetail?.rawDdl ?? null;
+  const drawerTabs = drawerDraft ? [
+    {
+      value: "general-info",
+      label: "General Info",
+      content: (
+        <div className="sdix-drawer-form">
+          <section className="sdix-form-section">
+            <h4 className="solid-form-layout-label">Model Info</h4>
+            <div className="sdix-form-grid">
+              <div className="sdix-form-field">
+                <label htmlFor="sdix-singular-name">Singular Name</label>
+                <SolidInput
+                  id="sdix-singular-name"
+                  value={drawerDraft.singularName}
+                  onChange={(event) => updateGeneralField("singularName", event.target.value)}
+                />
+              </div>
+              <div className="sdix-form-field">
+                <label htmlFor="sdix-plural-name">Plural Name</label>
+                <SolidInput
+                  id="sdix-plural-name"
+                  value={drawerDraft.pluralName}
+                  onChange={(event) => updateGeneralField("pluralName", event.target.value)}
+                />
+              </div>
+              <div className="sdix-form-field">
+                <label htmlFor="sdix-display-name">Display Name</label>
+                <SolidInput
+                  id="sdix-display-name"
+                  value={drawerDraft.displayName}
+                  onChange={(event) => updateGeneralField("displayName", event.target.value)}
+                />
+              </div>
+              <div className="sdix-form-field">
+                <label htmlFor="sdix-user-key-field">User Key Field</label>
+                <SolidSelect
+                  id="sdix-user-key-field"
+                  value={drawerDraft.userKeyField}
+                  options={drawerUserKeyOptions}
+                  placeholder="Select user key field"
+                  onChange={(event) => changeUserKeyField(event.value)}
+                />
+              </div>
+              <div className="sdix-form-field sdix-form-field--full">
+                <label htmlFor="sdix-description">Description</label>
+                <SolidTextarea
+                  id="sdix-description"
+                  rows={3}
+                  value={drawerDraft.description}
+                  onChange={(event) => updateGeneralField("description", event.target.value)}
+                />
+              </div>
+            </div>
+          </section>
+
+          <section className="sdix-form-section">
+            <h4 className="solid-form-layout-label">Datasource Binding</h4>
+            <div className="sdix-form-grid">
+              <div className="sdix-form-field">
+                <label htmlFor="sdix-table-name">Table Name</label>
+                <SolidInput
+                  id="sdix-table-name"
+                  value={drawerDraft.tableName}
+                  onChange={(event) => updateGeneralField("tableName", event.target.value)}
+                />
+              </div>
+              <div className="sdix-form-field">
+                <label htmlFor="sdix-schema-name">Schema</label>
+                <SolidInput
+                  id="sdix-schema-name"
+                  value={drawerDraft.schema ?? "default"}
+                  disabled
+                />
+              </div>
+              <div className="sdix-form-field">
+                <label htmlFor="sdix-datasource-name">Datasource</label>
+                <SolidInput
+                  id="sdix-datasource-name"
+                  value={drawerDraft.dataSource}
+                  disabled
+                />
+              </div>
+              <div className="sdix-form-field">
+                <label htmlFor="sdix-datasource-type">Provider</label>
+                <SolidInput
+                  id="sdix-datasource-type"
+                  value={providerLabel(drawerDraft.dataSourceType)}
+                  disabled
+                />
+              </div>
+              <div className="sdix-form-field">
+                <label htmlFor="sdix-legacy-type">Legacy Strategy</label>
+                <SolidInput
+                  id="sdix-legacy-type"
+                  value={legacyTypeLabel(drawerDraft.legacyTableType)}
+                  disabled
+                />
+              </div>
+              <div className="sdix-form-field">
+                <label htmlFor="sdix-base-class">Superclass</label>
+                <SolidInput
+                  id="sdix-base-class"
+                  value={drawerDraft.baseClassName}
+                  disabled
+                />
+              </div>
+            </div>
+          </section>
+        </div>
+      ),
+    },
+    {
+      value: "columns-mapping",
+      label: "Columns Mapping",
+      content: (
+        <div className="sdix-columns">
+          <div className="sdix-columns__toolbar">
+            <div className="sdix-columns__legend" aria-label="Column legend">
+              <span className="sdix-status-badge is-superclass">System column</span>
+              <span className="sdix-status-badge is-muted">Application column</span>
+            </div>
+          </div>
+          <div className="sdix-column-table">
+            <div className="sdix-column-row sdix-column-row--head sdix-column-row--mapping">
+              <span>Column</span>
+              <span>Field</span>
+              <span>Database</span>
+              <span>SolidX</span>
+              <span className="sdix-column-select-header">
+                {selectableUnmappedColumns.length ? (
+                  <SolidCheckbox
+                    checked={allSelectableUnmappedIncluded}
+                    onChange={(event) => setUnmappedColumnsIncluded(event.target.checked)}
+                    aria-label={allSelectableUnmappedIncluded ? "Deselect all unmapped columns" : "Select all unmapped columns"}
+                  />
+                ) : (
+                  "Include"
+                )}
+              </span>
+              <span>Status</span>
+              <span>Action</span>
+            </div>
+            {drawerDraft.columns.map((column) => {
+              const isUserKey = drawerDraft.userKeyField === column.fieldName;
+              const statusClassName = column.handledBySuperclass
+                ? "is-superclass"
+                : column.include
+                  ? column.matched
+                    ? "is-mapped"
+                    : "is-unmapped"
+                  : "is-muted";
+
+              const statusText = column.handledBySuperclass
+                ? "System"
+                : column.include
+                  ? column.matched
+                    ? "Mapped"
+                    : "Queued for save"
+                  : column.matched
+                    ? "Currently omitted"
+                    : "Skipped for now";
+
+              return (
+                <div key={column.columnName} className="sdix-column-row sdix-column-row--mapping">
+                  <span className="sdix-column-meta">
+                    <strong>{column.columnName}</strong>
+                    {column.isAutoGenerated ? <small>Generated id column</small> : null}
+                  </span>
+                  <span>
+                    <SolidInput
+                      value={column.fieldName}
+                      disabled={column.handledBySuperclass}
+                      onChange={(event) => updateColumnFieldName(column.columnName, event.target.value)}
+                    />
+                    {isUserKey ? <small className="sdix-inline-note">User key</small> : null}
+                  </span>
+                  <span className="sdix-column-meta">
+                    <strong>{column.dataType}</strong>
+                  </span>
+                  <span>
+                    {column.handledBySuperclass ? (
+                      <span>{column.solidFieldType}</span>
+                    ) : (
+                      <SolidSelect
+                        value={column.solidFieldType}
+                        options={scalarFieldTypeOptions}
+                        onChange={(event) => updateColumnSolidFieldType(column.columnName, event.value)}
+                      />
+                    )}
+                  </span>
+                  <span className="sdix-column-include">
+                    {column.handledBySuperclass ? (
+                      <span className="sdix-column-placeholder">-</span>
+                    ) : column.matched ? (
+                      <span className="sdix-column-placeholder">-</span>
+                    ) : column.isPrimaryKey ? (
+                      <SolidCheckbox checked disabled label="Required" />
+                    ) : (
+                      <SolidCheckbox
+                        checked={column.include}
+                        onChange={(event) => setColumnIncluded(column.columnName, event.target.checked)}
+                      />
+                    )}
+                  </span>
+                  <span>
+                    <span className={`sdix-status-badge ${statusClassName}`}>{statusText}</span>
+                  </span>
+                  <span className="sdix-column-action">
+                    {column.handledBySuperclass ? (
+                      <SolidButton size="small" variant="outline" disabled>
+                        Managed
+                      </SolidButton>
+                    ) : column.isPrimaryKey ? (
+                      <SolidButton size="small" variant="outline" disabled>
+                        Required
+                      </SolidButton>
+                    ) : column.matched ? (
+                      <SolidButton size="small" variant="outline" onClick={() => setColumnIncluded(column.columnName, false)}>
+                        Remove mapping
+                      </SolidButton>
+                    ) : (
+                      <span className="sdix-column-placeholder">-</span>
+                    )}
+                  </span>
+                </div>
+              );
+            })}
+          </div>
+        </div>
+      ),
+    },
+    {
+      value: "raw-ddl",
+      label: "Raw DDL",
+      content: (
+        <div className="sdix-ddl-tab">
+          {drawerRawDdl?.available && drawerRawDdl.statement ? (
+            <pre className="sdix-ddl-code"><code>{drawerRawDdl.statement}</code></pre>
+          ) : (
+            <div className="sdix-empty-state is-inline sdix-ddl-empty">
+              <Database size={18} />
+              <p>{drawerRawDdl?.note || "DDL preview is not available for this table."}</p>
+            </div>
+          )}
+        </div>
+      ),
+    },
+  ] : [];
+
+  const reviewTabs = mappingPreview ? [
+    {
+      value: "metadata-json",
+      label: "Metadata JSON",
+      content: (
+        <div className="sdix-review-panel sdix-review-panel--metadata">
+          <div className="sdix-review-meta sdix-review-meta--compact">
+            <span>Target file</span>
+            <strong>{mappingPreview.metadataJson.filePath}</strong>
+          </div>
+          <SolidJsonEditor
+            className="sdix-json-editor"
+            value={reviewedMetadataJsonValue ?? mappingPreview.metadataJson.model}
+            resetToken={metadataJsonResetToken}
+            onValueChange={(nextValue) => {
+              setReviewedMetadataJsonValue(nextValue);
+              if (metadataJsonValidationError) {
+                setMetadataJsonValidationError(null);
+              }
+            }}
+            onTextChange={(nextText) => {
+              setMetadataJsonText(nextText);
+            }}
+            onErrorChange={setMetadataJsonValidationError}
+          />
+          {metadataJsonValidationError ? (
+            <div className="sdix-json-validation-error">
+              <span>{metadataJsonValidationError}</span>
+            </div>
+          ) : null}
+        </div>
+      ),
+    },
+    {
+      value: "migration",
+      label: "Migration",
+      content: (
+        <div className="sdix-review-panel sdix-review-panel--migration">
+          {mappingPreview.migration.willGenerate && mappingPreview.migration.filePath ? (
+            <>
+              <div className="sdix-review-meta sdix-review-meta--compact">
+                <span>Target file</span>
+                <strong>{mappingPreview.migration.filePath}</strong>
+              </div>
+              <p className="sdix-review-note">
+                This migration preview is generated from the current mapping and is read-only here. Saving the mapping will write a new template migration file to the target location.
+              </p>
+              {mappingPreview.migration.content ? (
+                <pre className="sdix-ddl-code sdix-ddl-code--fill"><code>{mappingPreview.migration.content}</code></pre>
+              ) : null}
+            </>
+          ) : (
+            <div className="sdix-empty-state is-inline sdix-ddl-empty">
+              <Database size={18} />
+              <p>{mappingPreview.migration.note}</p>
+            </div>
+          )}
+        </div>
+      ),
+    },
+  ] : [];
+
+  return (
+    <div className="sdix-page">
+      <div className="sdix-toolbar">
+        <div className="sdix-toolbar__left">
+          <div className="sdix-toolbar-search">
+            <Search size={15} />
+            <SolidInput
+              value={tableSearch}
+              onChange={(event) => setTableSearch(event.target.value)}
+              placeholder="Search tables"
+              disabled={!selectedDatasource}
+            />
+          </div>
+        </div>
+
+        <div className="sdix-toolbar__actions">
+          {isBootstrapFetching || isTablesFetching || isTableDetailFetching || isMappedModelFetching ? (
+            <div className="sdix-inline-status">
+              <SolidSpinner size={16} />
+              <span>Refreshing</span>
+            </div>
+          ) : null}
+          <SolidSelect
+            value={selectedDatasource}
+            options={datasourceOptions}
+            placeholder="Datasource"
+            className="sdix-toolbar-select sdix-toolbar-select--compact"
+            onChange={(event) => setSelectedDatasource(event.value)}
+          />
+          <SolidButton
+            size="small"
+            className="sdix-icon-button"
+            leftIcon={<RefreshCw size={16} />}
+            onClick={() => void handleRefresh()}
+            tooltip="Refresh"
+            aria-label="Refresh"
+          />
+          <SolidButton
+            size="small"
+            className="sdix-icon-button"
+            leftIcon={<Cog size={16} />}
+            onClick={() => {
+              setDraftSessionSettings(sessionSettings);
+              setSettingsTab("datasource-info");
+              setSettingsOpen(true);
+            }}
+            tooltip="Session settings"
+            aria-label="Session settings"
+          />
+        </div>
+      </div>
+
+      {isBootstrapLoading ? (
+        <div className="sdix-loading">
+          <SolidSpinner size={28} />
+          <p>Loading introspection workspace...</p>
+        </div>
+      ) : bootstrapError ? (
+        <div className="sdix-error">
+          <span>{readQueryError(bootstrapError)}</span>
+          <SolidButton size="small" variant="outline" onClick={() => void refetchBootstrap()}>
+            Retry
+          </SolidButton>
+        </div>
+      ) : (
+        <>
+          {selectedDatasource && tablesResponse?.synchronizeBlocked ? (
+            <div className="sdix-blocker">
+              <ShieldAlert size={20} />
+              <div>
+                <h3>Synchronize must be disabled before introspection</h3>
+                <p>{tablesResponse.synchronizeMessage}</p>
+              </div>
+            </div>
+          ) : null}
+
+          <div className="sdix-workbench">
+            <div className="sdix-table-shell">
+            {!selectedDatasource ? (
+              <div className="sdix-empty-state is-inline">
+                <Database size={22} />
+                <p>Select a datasource to load its tables.</p>
+              </div>
+            ) : isTablesLoading ? (
+              <div className="sdix-loading is-inline">
+                <SolidSpinner size={24} />
+                <p>Inspecting datasource tables...</p>
+              </div>
+            ) : tablesError ? (
+              <div className="sdix-error is-inline">
+                <span>{readQueryError(tablesError)}</span>
+                <SolidButton size="small" variant="outline" onClick={() => void refetchTables()}>
+                  Retry
+                </SolidButton>
+              </div>
+            ) : !filteredRecords.length ? (
+              <div className="sdix-empty-state is-inline">
+                <Database size={22} />
+                <p>{tableSearch ? "No tables match the current quick filter." : "No database tables were discovered for this datasource."}</p>
+              </div>
+            ) : (
+              <div className="sdix-table-area">
+                <SolidDataTable
+                  value={filteredRecords}
+                  dataKey="tableName"
+                  viewportHeight="calc(100vh - 162px)"
+                  size="small"
+                  onRowClick={({ data }) => openTableDrawer(data)}
+                  rowClassName={(rowData) => `${rowData.schema ?? ""}::${rowData.tableName}` === selectedTableKey && drawerOpen ? "sdix-table-row-selected" : ""}
+                  emptyMessage="No datasource tables found"
+                >
+                  <Column
+                    field="tableName"
+                    header="Table"
+                    body={(rowData: DatasourceIntrospectionTableRecord) => (
+                      <div className="sdix-table-primary-cell">
+                        <strong>{rowData.tableName}</strong>
+                      </div>
+                    )}
+                    style={{ minWidth: 240 }}
+                  />
+                  <Column field="schema" header="Schema" body={(rowData: DatasourceIntrospectionTableRecord) => rowData.schema || "dbo/default"} style={{ minWidth: 120 }} />
+                  <Column
+                    header="Status"
+                    body={(rowData: DatasourceIntrospectionTableRecord) => (
+                      <span
+                        className={`sdix-status-badge ${rowData.mapped ? "is-mapped" : "is-unmapped"}`}
+                      >
+                        {statusLabel(rowData)}
+                      </span>
+                    )}
+                    style={{ minWidth: 150 }}
+                  />
+                  <Column
+                    header="Superclass"
+                    body={(rowData: DatasourceIntrospectionTableRecord) => rowData.suggestedBaseClassName}
+                    style={{ minWidth: 220 }}
+                  />
+                  <Column field="suggestedUserKeyField" header="User Key" style={{ minWidth: 160 }} />
+                  <Column
+                    header="Mapped Model"
+                    body={(rowData: DatasourceIntrospectionTableRecord) => (
+                      rowData.mapped
+                        ? (rowData.mappedModelDisplayName || rowData.mappedModelSingularName || "-")
+                        : <span className="sdix-muted-cell">Not mapped</span>
+                    )}
+                    style={{ minWidth: 200 }}
+                  />
+                  <Column
+                    header="System Columns"
+                    body={(rowData: DatasourceIntrospectionTableRecord) => Math.max(rowData.columnCount - rowData.physicalColumnCount, 0)}
+                    style={{ minWidth: 130 }}
+                  />
+                  <Column
+                    header="Columns"
+                    body={(rowData: DatasourceIntrospectionTableRecord) => rowData.physicalColumnCount}
+                    style={{ minWidth: 110 }}
+                  />
+                </SolidDataTable>
+              </div>
+            )}
+            </div>
+          </div>
+
+          <SolidDialog
+            open={settingsOpen}
+            onOpenChange={setSettingsOpen}
+            style={{ width: "min(560px, calc(100vw - 32px))" }}
+          >
+            <SolidDialogHeader>
+              <div>
+                <SolidDialogTitle>Session settings</SolidDialogTitle>
+                <SolidDialogDescription>
+                  Review the selected datasource and adjust the session-specific introspection flags.
+                </SolidDialogDescription>
+              </div>
+              <SolidDialogClose />
+            </SolidDialogHeader>
+            <SolidDialogSeparator />
+            <SolidDialogBody>
+              <SolidTabGroup
+                tabs={settingsTabs}
+                value={settingsTab}
+                onValueChange={setSettingsTab}
+                className="sdix-settings-tabs"
+                panelClassName="sdix-settings-tab-panel"
+              />
+            </SolidDialogBody>
+            <SolidDialogFooter>
+              <SolidButton variant="outline" onClick={() => setSettingsOpen(false)}>
+                Cancel
+              </SolidButton>
+              <SolidButton onClick={applyDraftSettings}>
+                Apply
+              </SolidButton>
+            </SolidDialogFooter>
+          </SolidDialog>
+
+          <SolidDialog
+            open={drawerOpen}
+            onOpenChange={setDrawerOpen}
+            className="sdix-drawer"
+            overlayClassName="sdix-drawer-overlay"
+            dismissible
+          >
+            <SolidDialogHeader className="sdix-drawer-header">
+              <div className="sdix-drawer-header__identity">
+                <SolidDialogTitle>{selectedTable?.tableName || "Table details"}</SolidDialogTitle>
+                <SolidDialogDescription className="sdix-drawer-header__meta">
+                  {selectedTable
+                    ? `${selectedTable.schema || "default"} · ${selectedDatasourceRecord?.database || selectedDatasourceRecord?.displayName || "Datasource"}${selectedDatasourceRecord ? ` · ${providerLabel(selectedDatasourceRecord.type)}` : ""}`
+                    : "Review mapping details"}
+                </SolidDialogDescription>
+              </div>
+              <SolidDialogClose />
+            </SolidDialogHeader>
+            <SolidDialogSeparator />
+            <SolidDialogBody className="sdix-drawer-body">
+              {!selectedTable ? (
+                <div className="sdix-empty-state is-inline">
+                  <Sparkles size={22} />
+                  <p>Select a table row to review its structure.</p>
+                </div>
+              ) : drawerLoadingError ? (
+                <div className="sdix-error is-inline">
+                  <span>{readQueryError(drawerLoadingError)}</span>
+                  <SolidButton size="small" variant="outline" onClick={() => void refetchTableDetail()}>
+                    Retry
+                  </SolidButton>
+                </div>
+              ) : isDrawerBlockingLoading ? (
+                <div className="sdix-loading is-inline">
+                  <SolidSpinner size={24} />
+                  <p>Preparing column mapping preview...</p>
+                </div>
+              ) : (
+                <div className="sdix-drawer-stack">
+                  {drawerDraft && !drawerDraft.mapped && drawerStep === "edit" ? (
+                    <div className="sdix-detail-callout sdix-system-fields-callout">
+                      <h3>SolidX system fields are added later</h3>
+                      <p>
+                        This preview only lists the legacy table columns that already exist today.
+                        {" "}
+                        Framework system fields from the selected superclass, including the namespaced
+                        {" "}
+                        <code>ss_*</code>
+                        {" "}
+                        columns, are introduced when you save the mapping and then generate/apply the follow-up migrations.
+                      </p>
+                    </div>
+                  ) : null}
+                  {drawerStep === "edit" ? (
+                    <SolidTabGroup
+                      tabs={drawerTabs}
+                      value={drawerTab}
+                      onValueChange={setDrawerTab}
+                      className="sdix-drawer-tabs"
+                      panelClassName="sdix-drawer-tab-panel"
+                    />
+                  ) : (
+                    <SolidTabGroup
+                      tabs={reviewTabs}
+                      value={reviewTab}
+                      onValueChange={setReviewTab}
+                      className="sdix-drawer-tabs"
+                      panelClassName="sdix-drawer-tab-panel"
+                    />
+                  )}
+                </div>
+              )}
+            </SolidDialogBody>
+            {drawerDraft && !isDrawerBlockingLoading ? (
+              <>
+                <SolidDialogSeparator />
+                <SolidDialogFooter className="sdix-drawer-footer">
+                  <div className="sdix-drawer-footer__meta">
+                    {drawerStep === "review" && mappingPreview ? (
+                      <span>
+                        Review the metadata update first, then save to apply
+                        {" "}
+                        <strong>{mappingPreview.summary.includedColumnNames.length}</strong>
+                        {" "}
+                        mapped columns
+                        {mappingPreview.summary.generatedSystemColumnCount
+                          ? ` and ${mappingPreview.summary.generatedSystemColumnCount} SolidX system column migration changes`
+                          : ""}
+                        .
+                      </span>
+                    ) : drawerDraft.mapped ? (
+                      <span>
+                        Editing mapped model
+                        {" "}
+                        <strong>{selectedTable?.mappedModelDisplayName || selectedTable?.mappedModelSingularName}</strong>
+                        {drawerDraft.mappedModuleLabel ? ` in ${drawerDraft.mappedModuleLabel}` : ""}
+                      </span>
+                    ) : (
+                      <span>Saving will create the model metadata and write it to the module JSON.</span>
+                    )}
+                  </div>
+                  <div className="sdix-drawer-footer__actions">
+                    {drawerDraft.mapped && drawerDraft.modelId ? (
+                      <SolidButton size="small" variant="outline" leftIcon={<ExternalLink size={14} />} onClick={openMappedModelForm}>
+                        Open model form
+                      </SolidButton>
+                    ) : null}
+                    {drawerStep === "review" ? (
+                      <>
+                        <SolidButton size="small" variant="outline" onClick={() => setDrawerStep("edit")}>
+                          Back to editing
+                        </SolidButton>
+                        <SolidButton size="small" leftIcon={<Save size={14} />} loading={isSavingMapping} onClick={() => void saveMapping()}>
+                          Save mapping
+                        </SolidButton>
+                      </>
+                    ) : (
+                      <SolidButton
+                        size="small"
+                        leftIcon={<Save size={14} />}
+                        loading={isPreviewMappingLoading}
+                        onClick={() => void viewChanges()}
+                      >
+                        View Changes
+                      </SolidButton>
+                    )}
+                  </div>
+                </SolidDialogFooter>
+              </>
+            ) : null}
+          </SolidDialog>
+        </>
+      )}
+    </div>
+  );
+}