#pragma once

// FormKit —— 表单渲染的「单一真相」层。
//
// 历史问题：每个表单/对话框各自手搭布局（裸 QFormLayout + 裸 QLabel、各写边距/标签列宽），
// 规范文档（§6.4/§7.0）只是文字约束、无法强制，于是同类控件在不同位置长得不一样。
// 本模块把「只读键值详情」与「可编辑表单」的视觉度量收敛到唯一实现，所有表单必须经此产出，
// 一致性由「代码复用」强制，而非「人工遵守文档」。

#include <QFrame>  // editLabel/formCard 返回 QLabel*/QFrame*；调用方常把结果直接传给
#include <QLabel>  // addRow/addWidget(QWidget*)，需在调用点见到完整类型（QLabel/QFrame 派生自 QWidget）。
#include <QList>
#include <QString>

#include "repo/RepoTypes.hpp"

class QBoxLayout;
class QComboBox;
class QDialog;
class QDialogButtonBox;
class QFormLayout;
class QVBoxLayout;
class QWidget;

namespace geopro::app::formkit {

// ── 下拉框：全局建下拉的标准入口（返回空态感知下拉 EmptyAwareComboBox）──────────────
// placeholder 非空时设占位文案 + currentIndex=-1（未选显灰字占位，对齐 Arco ASelect）；
// placeholder 为空时保持 QComboBox 默认行为（addItem 后自动选首项），不强加占位。
// 无真实可选项时点开弹窗会显示一条灰色「暂无数据」（实现于 EmptyAwareComboBox）。
QComboBox* comboBox(const QString& placeholder = QString(), QWidget* parent = nullptr);

// ── 只读详情：唯一键值模型构建器 ─────────────────────────────────────────────
// 链式 group()/row() 产出 data::DynamicForm，喂给唯一的 §6.4 渲染器 DynamicFormView。
// 三维体/切片/异常等「数据详情」对话框共用，杜绝裸 QFormLayout 漂移。
class DetailForm {
public:
    DetailForm& group(const QString& name);          // 开新分组
    DetailForm& row(const QString& key, const QString& value);  // 向当前组追加键值行
    const geopro::data::DynamicForm& build() const { return form_; }

private:
    geopro::data::DynamicForm form_;
};

// 给只读详情对话框铺设标准骨架：DynamicFormView（§6.4 卡片）+ 底部 Close + 统一边距。
// extras 追加在卡片下方、按钮上方（异常详情的顶点坐标/备注走此口），与主键值表共享节奏。
void buildDetailDialog(QDialog* dlg, const geopro::data::DynamicForm& form,
                       const QList<QWidget*>& extras = {});

// ── 对话框外壳：统一所有对话框的边距/卡片/按钮栏（编辑态与只读态共用 → 外观一致）──────
// 标准根布局：统一外边距 space/lg + 行距 space/md。
QVBoxLayout* dialogRoot(QDialog* dlg);
// 标准表单卡片：bg/panel-subtle + 1px 边框 + 中圆角 + 统一内距。把表单/分组/键值包成
// 与「数据详情 / 属性面板」同款的卡片面。返回 QFrame；其 layout() 即 QVBoxLayout，向内 addSection/addLayout。
QFrame* formCard(QWidget* parent);
QVBoxLayout* cardBody(QFrame* card);  // 取 formCard 的内层 QVBoxLayout（便捷器）
// 标准底部按钮栏：QDialogButtonBox(Ok|Cancel)，已接 accept/reject；okText/cancelText 可定制文案。
QDialogButtonBox* addDialogButtons(QVBoxLayout* root, QDialog* dlg, const QString& okText = QString(),
                                   const QString& cancelText = QString());

// ── 可编辑表单：§7.0 统一度量（DynamicFormEditor 与各参数对话框共用，单一真相）──────
QFormLayout* makeEditForm();  // 右对齐标签 + 标准行距/列距
QLabel* editLabel(const QString& text, QWidget* parent = nullptr,
                  bool richText = false);  // 定宽右标签列（kFormLabelCol）
void capField(QWidget* field);             // 字段最大宽上限（kFormFieldMax）
// 分组标题（heading 字号 + 半粗 + 次级色）+ 标题下 1px divider；topGap=true 时上方留 space/lg。
void addSection(QBoxLayout* into, const QString& title, QWidget* parent, bool topGap);

}  // namespace geopro::app::formkit