openyida 2026.9.2 → 2026.9.3

package/README.md

@@ -153,7 +153,7 @@ openyida/
 │   ├── core/                   # Environment detection, i18n, diagnostics, data commands
 │   ├── process/                # Process form creation, configuration, preview
 │   ├── report/                 # Yida report and chart generation
-│   └── samples/                # Sample skeletons emitted by openyida sample
+│   └── samples/                # Reusable code templates emitted by openyida sample
 ├── project/                    # Default workspace template for generated Yida projects
 ├── yida-skills/                # Source skill docs and Yida API references
 └── scripts/                    # CI, packaging, and installation helpers
@@ -167,13 +167,14 @@ For a user-facing list of supported features and matching CLI commands, see [Ope
 
 ```bash
 openyida create-app "CRM"
-openyida create-app --name "CRM" --desc "Customer management" --theme-file ./app-theme.css --nav-theme light --logo-source appIcon --layout l_shape
+openyida sample yida-design app-theme --output .cache/openyida/crm/app-theme.css
+openyida create-app --name "CRM" --desc "Customer management" --theme-file .cache/openyida/crm/app-theme.css --nav-theme light --logo-source appIcon --layout l_shape
 openyida app-list --size 20
 openyida corp-efficiency
 openyida create-form create APP_XXX "Customer" .cache/openyida/forms/customer-fields.json
 openyida create-form update APP_XXX FORM_XXX .cache/openyida/forms/customer-changes.json
-openyida sample openyida-scaffold form-fields --output .cache/openyida/forms/customer-fields.json
-openyida sample openyida-scaffold canvas-form-drawer --output project/pages/src/customer-entry.canvas.jsx --var APP_TYPE=APP_XXX --var FORM_UUID=FORM_XXX
+openyida sample openyida-page-template form-fields --output .cache/openyida/forms/customer-fields.json
+openyida sample openyida-page-template canvas-form-drawer --output project/pages/src/customer-entry.canvas.jsx --var APP_TYPE=APP_XXX --var FORM_UUID=FORM_XXX
 openyida get-schema APP_XXX FORM_XXX
 openyida get-schema APP_XXX FORM_XXX --compact --resolve-fields "Customer Name,Status"
 openyida get-schema APP_XXX --all --output-dir .cache/schemas
@@ -403,7 +404,8 @@ Run `openyida --help` or `openyida <command> --help` for detailed usage.
 
 | Command | Description |
 |---------|-------------|
-| `openyida create-form create <appType> "<formTitle>" <fieldsJsonFile> [--locale zh_CN\|en_US\|ja_JP] [--open\|--no-open]` | Create a form page |
+| `openyida create-form create <appType> "<formTitle>" <fieldsJsonFile> [--icon auto\|<iconName>] [--locale zh_CN\|en_US\|ja_JP] [--open\|--no-open]` | Create a form page |
+| `openyida create-form icons [--json]` | List available form navigation icons |
 | `openyida create-form validate-fields <fieldsJsonOrFile> [--json]` | Validate form field JSON locally |
 | `openyida create-form update <appType> ... [--locale zh_CN\|en_US\|ja_JP] [--open\|--no-open]` | Update a form page |
 | `openyida create-form patch <appType> <formUuid> <patchJsonOrFile> [--open\|--no-open]` | Update a form page |
@@ -518,7 +520,7 @@ Run `openyida --help` or `openyida <command> --help` for detailed usage.
 | `openyida batch <file>\|--commands "cmd1 ; cmd2" [--stop-on-error] [--json]` | Run OpenYida commands in batch |
 | `openyida flash-to-prd --file <path> --name "<project>"` | Convert flash notes or meeting notes to a PRD prompt |
 | `openyida ai <text\|image> [options]` | Call Yida AI text and image recognition APIs |
-| `openyida asset <status\|verify-url\|resolve\|generate> [options]` | Detect asset capability / verify image URLs / resolve materials |
+| `openyida asset <status\|resolve\|generate> [options]` | Detect asset capability / resolve materials |
 | `openyida cdn-config [options]` | Configure CDN / OSS upload |
 | `openyida cdn-upload <image-path>` | Upload image to CDN |
 | `openyida cdn-refresh [options]` | Refresh CDN cache |
@@ -549,7 +551,7 @@ The runner rejects public generic echo services such as httpbin and example.com.
 
 The opt-in `node scripts/e2e-real/connector/action-update-runner.js` regression uses the owner-confirmed login-free `www.aliwork.com` fixture and a single owned NONE-auth connector containing a target action plus one preservation sentinel. Enable it with `OPENYIDA_E2E=1 OPENYIDA_E2E_CONNECTOR_ACTION_UPDATE=1`. It verifies isolated `currentPage`, `pageSize`, `userLanguage`, `searchFieldJson`, and dynamic `_stamp` edits, restores each field and the final baseline, and persists only response structure, data count, and SHA-256. It never stores response row values or auth/profile/corp identifiers, never retries unknown writes, and intentionally leaves the owned connector as a `cleanup_blocked` residual because no proven delete API exists.
 
-`openyida asset resolve --hero <path-or-url> --product <path-or-url> --require-hero --upload-assets --json` is the preferred preflight for homepage visuals. It verifies public image URLs, uploads local images when CDN is configured, mirrors verified external images to CDN when `--upload-assets` is passed, and returns `materialStatus: final|draft|none` so agents do not claim an unfinished visual page is final.
+`openyida asset resolve --hero <path-or-url> --product <path-or-url> --require-hero --upload-assets --json` is the preferred preflight for homepage visuals. It handles local files and external image references in one flow, uploads or mirrors them when CDN is configured, and returns `materialStatus: final|draft|none` so agents do not claim an unfinished visual page is final.
 
 #### Environment and Localization
 

package/lib/app/create-form/api-path.js

@@ -11,6 +11,8 @@
  * @param {string} [options.prefix]        额外的路径前缀（会以 / 拼接）
  * @param {string} [options.namespace]     命名空间，默认 dingtalk
  * @param {'formdesign'|'formnav'} [options.queryModule] 查询模块，默认 formdesign
+ * @param {string} [options.api]            页面请求标识，例如 Nav.update
+ * @param {boolean} [options.mock]          是否使用 mock 接口
  * @param {boolean} [options.addTimestamp] 是否追加 _stamp 时间戳查询参数
  * @returns {string} 拼接完成的 API 请求路径
  */
@@ -19,14 +21,26 @@ function buildApiPath(appType, apiName, options = {}) {
     prefix = '',
     namespace = 'dingtalk',
     queryModule = 'formdesign',
+    api,
+    mock,
     addTimestamp = false,
   } = options;
   if (queryModule !== 'formdesign' && queryModule !== 'formnav') {
     throw new Error(`Unsupported query module: ${queryModule}`);
   }
   const prefixPath = prefix ? `/${prefix}` : '';
-  const timestamp = addTimestamp ? `?_stamp=${Date.now()}` : '';
-  return `/${namespace}/web/${appType}${prefixPath}/query/${queryModule}/${apiName}.json${timestamp}`;
+  const queryParams = [];
+  if (api) {
+    queryParams.push(`_api=${encodeURIComponent(api)}`);
+  }
+  if (mock !== undefined) {
+    queryParams.push(`_mock=${String(Boolean(mock))}`);
+  }
+  if (addTimestamp) {
+    queryParams.push(`_stamp=${Date.now()}`);
+  }
+  const query = queryParams.length > 0 ? `?${queryParams.join('&')}` : '';
+  return `/${namespace}/web/${appType}${prefixPath}/query/${queryModule}/${apiName}.json${query}`;
 }
 
 module.exports = {

package/lib/app/create-form/args.js

@@ -85,6 +85,7 @@ function createParseArgs(dependencies) {
       layout: 'single',
       theme: 'default',
       labelAlign: 'top',
+      icon: 'auto',
       contentLocale: null,
       browserOpenMode: openOption.mode,
     };
@@ -104,6 +105,12 @@ function createParseArgs(dependencies) {
         options.labelAlign = args[i + 1];
         args.splice(i, 2);
         i--;
+      } else if (args[i] === '--icon' && i + 1 < args.length) {
+        options.icon = args[i + 1];
+        args.splice(i, 2);
+        i--;
+      } else if (args[i] === '--icon') {
+        throwCreateFormError('--icon requires a value', 'CREATE_FORM_INVALID_ARGUMENTS');
       } else if ((args[i] === '--locale' || args[i] === '--content-locale' || args[i] === '--lang') && i + 1 < args.length) {
         options.contentLocale = args[i + 1];
         if (!normalizeYidaLocale(options.contentLocale)) {
@@ -138,6 +145,13 @@ function createParseArgs(dependencies) {
 
     const mode = args[0];
 
+    if (mode === 'icons' || mode === 'list-icons') {
+      return {
+        mode: 'icons',
+        ...options
+      };
+    }
+
     if (mode === 'validate-fields') {
       if (args.length === 2) {
         return {

package/lib/app/create-form/nav-icon-service.js

@@ -0,0 +1,202 @@
+'use strict';
+
+const FORM_NAVIGATION_UPDATE_KEYS = [
+  'gmtModified',
+  'parentNavUuid',
+  'hidden',
+  'mobileHidden',
+  'i18nTitle',
+  'isNewReport',
+  'id',
+  'isNewForm',
+  'slug',
+  'formType',
+  'formUuid',
+  'navUuid',
+  'navType',
+  'isNew',
+  'gmtCreate',
+  'parentId',
+  'url',
+  'topicId',
+  'displayType',
+  'relateFormUuid',
+  'processCode',
+  'listOrder',
+  'formStatus',
+  'relateFormType',
+];
+
+function buildFormNavigationIconUpdatePayload(navigationNode, icon) {
+  const updatePayload = {
+    _locale_time_zone_offset: 28800000,
+  };
+  FORM_NAVIGATION_UPDATE_KEYS.forEach(function (key) {
+    if (navigationNode[key] !== undefined) {
+      updatePayload[key] = key === 'i18nTitle' && navigationNode[key] !== null && typeof navigationNode[key] === 'object'
+        ? String(navigationNode[key])
+        : navigationNode[key];
+    }
+  });
+
+  const navigationTitle = navigationNode.title || navigationNode.i18nTitle || {};
+  updatePayload.title = typeof navigationTitle === 'string'
+    ? navigationTitle
+    : JSON.stringify(navigationTitle);
+  updatePayload.formUuid = navigationNode.formUuid || 'NAV-SYSTEM-FROM-ME-UUID';
+  updatePayload.icon = icon;
+  return updatePayload;
+}
+
+function createFormNavIconService(dependencies) {
+  const {
+    buildApiPath,
+    requestWithAutoLogin,
+    sendGetRequest,
+    sendPostRequest,
+    throwCreateFormError,
+    sanitizeFailureResult,
+    candidateLimit = 8,
+  } = dependencies;
+
+  function flattenNavigationNodes(nodes, output) {
+    const resultNodes = output || [];
+    (nodes || []).forEach(function (node) {
+      resultNodes.push(node);
+      if (Array.isArray(node.children)) {
+        flattenNavigationNodes(node.children, resultNodes);
+      }
+    });
+    return resultNodes;
+  }
+
+  async function fetchFormNavigationList(authRef, appType) {
+    const navigationResult = await requestWithAutoLogin(function (auth) {
+      return sendGetRequest(
+        auth.baseUrl,
+        buildApiPath(appType, 'getFormNavigationListByOrder', {
+          queryModule: 'formnav',
+          addTimestamp: true,
+        }),
+        {
+          _api: 'Nav.queryList',
+          _mock: false,
+          _locale_time_zone_offset: 28800000,
+        }
+      );
+    }, authRef);
+
+    if (!navigationResult || navigationResult.success === false || !Array.isArray(navigationResult.content)) {
+      const message = navigationResult
+        ? navigationResult.errorMsg || navigationResult.message || 'Failed to fetch form navigation list'
+        : 'Failed to fetch form navigation list';
+      throwCreateFormError(message, 'CREATE_FORM_NAV_ICON_LIST_FAILED', {
+        appType,
+        result: sanitizeFailureResult(navigationResult),
+      });
+    }
+
+    return flattenNavigationNodes(navigationResult.content);
+  }
+
+  function resolveFormNavigationNode(nodes, formUuid) {
+    const exactMatches = (nodes || []).filter(function (node) {
+      return node && (node.formUuid === formUuid || node.navUuid === formUuid);
+    });
+    const relatedMatches = (nodes || []).filter(function (node) {
+      return node && node.relateFormUuid === formUuid;
+    });
+    const matches = exactMatches.length > 0 ? exactMatches : relatedMatches;
+    if (matches.length !== 1) {
+      return null;
+    }
+    return matches[0];
+  }
+
+  async function updateCreatedFormNavigationIcon(authRef, appType, formUuid, icon) {
+    const navigationNodes = await fetchFormNavigationList(authRef, appType);
+    const navigationNode = resolveFormNavigationNode(navigationNodes, formUuid);
+    if (!navigationNode) {
+      throwCreateFormError('Created form navigation node could not be resolved uniquely.', 'CREATE_FORM_NAV_ICON_NODE_NOT_FOUND', {
+        appType,
+        formUuid,
+        candidates: navigationNodes.filter(function (node) {
+          return node && node.navType !== 'SYSTEM';
+        }).slice(0, candidateLimit).map(function (node) {
+          return {
+            id: node.id,
+            navUuid: node.navUuid,
+            formUuid: node.formUuid,
+            relateFormUuid: node.relateFormUuid,
+            formType: node.formType,
+          };
+        }),
+      });
+    }
+
+    const updatePayload = buildFormNavigationIconUpdatePayload(navigationNode, icon);
+
+    const updateResult = await requestWithAutoLogin(function (auth) {
+      return sendPostRequest(
+        auth.baseUrl,
+        buildApiPath(appType, 'updateFormNavigation', {
+          queryModule: 'formnav',
+          api: 'Nav.update',
+          mock: false,
+          addTimestamp: true,
+        }),
+        updatePayload,
+        formUuid,
+        auth,
+        {
+          appType,
+          referer: `${auth.baseUrl}/${appType}/admin/${formUuid}`,
+        }
+      );
+    }, authRef);
+
+    if (!updateResult || updateResult.success === false) {
+      const message = updateResult
+        ? updateResult.errorMsg || updateResult.message || 'Failed to update form navigation icon'
+        : 'Failed to update form navigation icon';
+      throwCreateFormError(message, 'CREATE_FORM_NAV_ICON_UPDATE_FAILED', {
+        appType,
+        formUuid,
+        navUuid: navigationNode.navUuid,
+        icon,
+        result: sanitizeFailureResult(updateResult),
+      });
+    }
+
+    const updatedNavigationNodes = await fetchFormNavigationList(authRef, appType);
+    const updatedNavigationNode = resolveFormNavigationNode(updatedNavigationNodes, formUuid);
+    if (!updatedNavigationNode || updatedNavigationNode.icon !== icon) {
+      throwCreateFormError('Form navigation icon readback did not match the requested icon.', 'CREATE_FORM_NAV_ICON_READBACK_MISMATCH', {
+        appType,
+        formUuid,
+        navUuid: navigationNode.navUuid,
+        expectedIcon: icon,
+        actualIcon: updatedNavigationNode && updatedNavigationNode.icon,
+      });
+    }
+
+    return {
+      id: updatedNavigationNode.id,
+      navUuid: updatedNavigationNode.navUuid,
+      icon: updatedNavigationNode.icon,
+    };
+  }
+
+  return {
+    fetchFormNavigationList,
+    flattenNavigationNodes,
+    resolveFormNavigationNode,
+    updateCreatedFormNavigationIcon,
+  };
+}
+
+module.exports = {
+  FORM_NAVIGATION_UPDATE_KEYS,
+  buildFormNavigationIconUpdatePayload,
+  createFormNavIconService,
+};

package/lib/app/create-form/nav-icon.js

@@ -0,0 +1,267 @@
+'use strict';
+
+// Keep this catalog aligned with yida-next's page navigation icon picker:
+// src/components/AppSubNav/SortMenuTree/Theme/nav-icon-config.json.
+const FORM_NAV_ICON_GROUPS = [
+  {
+    key: 'defaultIcons',
+    label: '常用图标',
+    items: [
+      ['zhuye', '首页'],
+      ['clock', '时钟'],
+      ['CalendarSeventeen', '日历'],
+      ['set', '设置'],
+      ['account-settings', '账号设置'],
+      ['account', '人'],
+      ['lock', '锁'],
+      ['Addresslist', '通讯录'],
+      ['App', '应用'],
+      ['application', '应用2'],
+      ['dashboard', '看板'],
+      ['biaodan', '表单'],
+      ['baobiao', '报表'],
+      ['juhebiao', '聚合表'],
+      ['liucheng', '流程'],
+      ['biaoge', '表格'],
+      ['list', '列表'],
+      ['gerenwendang', '文档'],
+      ['Project', '项目'],
+      ['Filemanage', '文件管理'],
+      ['add-doc', '添加文件'],
+      ['bumen', '部门'],
+      ['gongzuo', '工作'],
+      ['book', '书'],
+      ['bonus', '礼物'],
+      ['briefcase', '公文包'],
+      ['building', '建筑'],
+      ['dingdingka', '钉钉卡'],
+      ['desktop', '电脑'],
+      ['document', '文件'],
+      ['folder', '文件夹'],
+    ],
+  },
+  {
+    key: 'systemIcons',
+    label: '更多图标',
+    items: [
+      ['smile', '笑脸'],
+      ['rengongfuwu', '人工服务'],
+      ['shop', '商城'],
+      ['calendar', '日历'],
+      ['Documents', '文件包'],
+      ['DingDrive', '云'],
+      ['appointment', '职务'],
+      ['Mail', '邮件'],
+      ['Product_management', '产品管理'],
+      ['Todo', '任务'],
+      ['admin', '账号'],
+      ['airplane', '飞机'],
+      ['bianqian', '标签'],
+      ['bus', '汽车'],
+      ['caidan1', '菜单'],
+      ['calendar-span', '日历'],
+      ['cascade', '连接'],
+      ['certificate-type', '印章管理'],
+      ['chengyuan', '成员'],
+      ['chuangjiantuandui', '创建团队'],
+      ['command', '快捷键'],
+      ['custom-column', '列表'],
+      ['data-settings', '数据设置'],
+      ['dagangshu', '大纲树'],
+      ['diannao', '电脑'],
+      ['diqu', '地区'],
+      ['dizhi', '地址'],
+      ['fulishe', '福利社'],
+      ['keshihuadaping', '可视化大屏'],
+      ['employee-add', '新增成员'],
+      ['fujian', '附件'],
+      ['fuwushichang', '市场'],
+      ['gouwudai', '购物袋'],
+      ['guanlianzuzhi', '关联组织'],
+      ['huangguan', '皇冠'],
+      ['huiyishi', '会议室'],
+      ['huiyuan', '会员'],
+      ['image', '图片'],
+      ['list-container', '列表2'],
+      ['name-card', '名片'],
+      ['printer', '打印机'],
+      ['renwu', '任务2'],
+      ['riqiziduan', '日期'],
+      ['scan', '扫码'],
+      ['shezhi', '设置'],
+      ['shoucang', '收藏'],
+      ['wenjian', '文件2'],
+      ['shujuguanliye1', '数据管理页'],
+      ['shujuyuanshezhi', '数据源'],
+      ['suo', '锁'],
+      ['tianjia', '添加'],
+      ['tongxunlu', '通讯录'],
+      ['wode', '我的'],
+      ['zhuguanliyuan', '主管理员'],
+      ['ziguanliyuan', '子管理员'],
+    ],
+  },
+];
+
+const FORM_NAV_ICONS = FORM_NAV_ICON_GROUPS.flatMap(function (group) {
+  return group.items.map(function (item) {
+    return {
+      name: item[0],
+      label: item[1],
+      group: group.key,
+    };
+  });
+});
+
+const ICON_BY_LOWER_NAME = new Map(FORM_NAV_ICONS.map(function (icon) {
+  return [icon.name.toLowerCase(), icon.name];
+}));
+
+const SEMANTIC_ICON_RULES = [
+  { icon: 'clock', keywords: ['考勤', '打卡', '工时', '时钟', 'attendance', 'timesheet'] },
+  { icon: 'huiyishi', keywords: ['会议室', '会议预约', '会议', 'meeting'] },
+  { icon: 'CalendarSeventeen', keywords: ['日程', '日历', '排期', '计划', '预约', 'calendar', 'schedule'] },
+  { icon: 'Project', keywords: ['项目', 'project'] },
+  { icon: 'Todo', keywords: ['任务', '待办', '工单', 'task', 'todo', 'ticket'] },
+  { icon: 'name-card', keywords: ['客户', '联系人', '访客', '名片', 'crm', 'customer', 'contact', 'visitor'] },
+  { icon: 'chengyuan', keywords: ['员工', '人员', '成员', '人才', '招聘', 'employee', 'member', 'recruit'] },
+  { icon: 'bumen', keywords: ['部门', '组织', '团队', 'department', 'organization', 'team'] },
+  { icon: 'Product_management', keywords: ['产品', '需求', 'product', 'requirement'] },
+  { icon: 'shop', keywords: ['商品', '商城', '店铺', 'product catalog', 'store', 'shop'] },
+  { icon: 'gouwudai', keywords: ['订单', '采购', '销售', '购物', 'order', 'purchase', 'sales'] },
+  { icon: 'dingdingka', keywords: ['财务', '报销', '费用', '付款', '收款', '预算', '发票', 'finance', 'expense', 'payment', 'invoice'] },
+  { icon: 'document', keywords: ['合同', '协议', '公文', '文书', 'contract', 'agreement'] },
+  { icon: 'Filemanage', keywords: ['文件', '档案', '资料', 'file', 'archive'] },
+  { icon: 'book', keywords: ['知识', '图书', '课程', '培训', 'knowledge', 'book', 'course', 'training'] },
+  { icon: 'baobiao', keywords: ['报表', '统计', '分析', 'report', 'analytics'] },
+  { icon: 'dashboard', keywords: ['看板', '指标', '驾驶舱', 'dashboard', 'metric'] },
+  { icon: 'liucheng', keywords: ['审批', '流程', 'approval', 'workflow'] },
+  { icon: 'dizhi', keywords: ['地址', '地点', '场地', 'address', 'location'] },
+  { icon: 'building', keywords: ['仓库', '库房', '楼宇', '场馆', 'warehouse', 'building'] },
+  { icon: 'desktop', keywords: ['设备', '电脑', '终端', 'device', 'computer'] },
+  { icon: 'fuwushichang', keywords: ['市场', '营销', '活动', '推广', 'marketing', 'campaign'] },
+  { icon: 'bonus', keywords: ['礼品', '奖励', '福利', 'gift', 'reward', 'benefit'] },
+  { icon: 'rengongfuwu', keywords: ['客服', '服务', '咨询', 'service', 'support'] },
+  { icon: 'Mail', keywords: ['邮件', '消息', '通知', 'mail', 'message', 'notification'] },
+  { icon: 'image', keywords: ['图片', '照片', '素材', 'image', 'photo', 'media'] },
+  { icon: 'fujian', keywords: ['附件', 'attachment'] },
+  { icon: 'certificate-type', keywords: ['印章', '用印', '证书', 'seal', 'certificate'] },
+  { icon: 'admin', keywords: ['账号', '管理员', 'account', 'admin'] },
+  { icon: 'lock', keywords: ['权限', '安全', '密码', 'permission', 'security', 'password'] },
+  { icon: 'bus', keywords: ['车辆', '用车', '交通', 'vehicle', 'car', 'transport'] },
+  { icon: 'airplane', keywords: ['差旅', '航班', '机票', 'travel', 'flight'] },
+  { icon: 'diqu', keywords: ['地区', '区域', 'region', 'area'] },
+  { icon: 'scan', keywords: ['扫码', '二维码', '条码', 'scan', 'qrcode', 'barcode'] },
+  { icon: 'shezhi', keywords: ['配置', '设置', 'config', 'setting'] },
+  { icon: 'biaoge', keywords: ['台账', '清单', '表格', '明细', 'ledger', 'table', 'list'] },
+  { icon: 'liucheng', keywords: ['申请', 'request'] },
+];
+
+const GENERIC_FORM_ICONS = ['biaodan', 'list', 'document', 'briefcase', 'gongzuo'];
+
+function normalizeText(value) {
+  if (value === undefined || value === null) {
+    return '';
+  }
+  if (typeof value === 'string' || typeof value === 'number') {
+    return String(value).toLowerCase();
+  }
+  if (Array.isArray(value)) {
+    return value.map(normalizeText).filter(Boolean).join(' ');
+  }
+  if (typeof value === 'object') {
+    return Object.values(value).map(normalizeText).filter(Boolean).join(' ');
+  }
+  return '';
+}
+
+function collectFieldSemanticText(fields) {
+  const values = [];
+  const visit = function (fieldList) {
+    (fieldList || []).forEach(function (field) {
+      if (!field || typeof field !== 'object') {
+        return;
+      }
+      values.push(field.label, field.title, field.name, field.key);
+      if (field.props && typeof field.props === 'object') {
+        values.push(field.props.label, field.props.title, field.props.name);
+      }
+      if (Array.isArray(field.children)) {
+        field.children.forEach(function (children) {
+          visit(Array.isArray(children) ? children : [children]);
+        });
+      }
+    });
+  };
+  visit(fields);
+  return normalizeText(values);
+}
+
+function findSemanticIcon(text) {
+  return SEMANTIC_ICON_RULES.find(function (rule) {
+    return rule.keywords.some(function (keyword) {
+      return text.includes(keyword.toLowerCase());
+    });
+  });
+}
+
+function stableGenericIcon(text) {
+  let hash = 0;
+  for (let index = 0; index < text.length; index++) {
+    hash = ((hash * 31) + text.charCodeAt(index)) >>> 0;
+  }
+  return GENERIC_FORM_ICONS[hash % GENERIC_FORM_ICONS.length];
+}
+
+function inferFormNavIcon(formTitle, fields) {
+  const titleText = normalizeText(formTitle);
+  const titleMatch = findSemanticIcon(titleText);
+  if (titleMatch) {
+    return titleMatch.icon;
+  }
+
+  const fieldText = collectFieldSemanticText(fields);
+  const fieldMatch = findSemanticIcon(fieldText);
+  if (fieldMatch) {
+    return fieldMatch.icon;
+  }
+
+  return stableGenericIcon(titleText || fieldText || 'form');
+}
+
+function normalizeFormNavIcon(value) {
+  const raw = String(value || '').trim();
+  if (!raw || raw.toLowerCase() === 'auto') {
+    return null;
+  }
+  return ICON_BY_LOWER_NAME.get(raw.toLowerCase()) || '';
+}
+
+function resolveFormNavIcon(value, formTitle, fields) {
+  const normalized = normalizeFormNavIcon(value);
+  if (normalized) {
+    return {
+      icon: normalized,
+      source: 'explicit',
+    };
+  }
+  if (String(value || '').trim() && String(value).trim().toLowerCase() !== 'auto') {
+    return {
+      icon: '',
+      source: 'invalid',
+    };
+  }
+  return {
+    icon: inferFormNavIcon(formTitle, fields),
+    source: 'auto',
+  };
+}
+
+module.exports = {
+  FORM_NAV_ICON_GROUPS,
+  FORM_NAV_ICONS,
+  collectFieldSemanticText,
+  inferFormNavIcon,
+  normalizeFormNavIcon,
+  resolveFormNavIcon,
+};