@manohub/app-kit 0.2.1 → 0.2.4

package/dist/index.d.ts

@@ -24,6 +24,7 @@ export { AppTable, type AppTableColumn, type AppTableProps, type AppTableSelecti
 export { AppPagination } from './components/app-pagination';
 export { AppBadge, type AppBadgeTone, type AppBadgeShape, type AppBadgeSize, type AppBadgeDot } from './components/app-badge';
 export { AppDialog } from './components/app-dialog';
+export { AppDrawer } from './components/app-drawer';
 export { AppTabs, type AppTabItem } from './components/app-tabs';
 export { AppForm, type AppFormProps, type AppFormItemProps, type AppFormLabelAlign, type AppFormCompound, } from './components/app-form';
 export { AppSection, type AppSectionProps } from './components/app-section';

package/dist/index.js

@@ -18,6 +18,7 @@ import { AppTable } from "./components/app-table.js";
 import { AppPagination } from "./components/app-pagination.js";
 import { AppBadge } from "./components/app-badge.js";
 import { AppDialog } from "./components/app-dialog.js";
+import { AppDrawer } from "./components/app-drawer.js";
 import { AppTabs } from "./components/app-tabs.js";
 import { AppForm } from "./components/app-form.js";
 import { AppSection } from "./components/app-section.js";
@@ -34,6 +35,7 @@ export {
   AppButton,
   AppCheckbox,
   AppDialog,
+  AppDrawer,
   AppFilter,
   AppForm,
   AppIconButton,

package/dist/styles/farris-bridge.css

@@ -110,6 +110,14 @@ body > .fv-tooltip.tooltip {
   min-height: 0;
 }
 
+/* AppDrawer：抽屉被 Teleport 进 `.app-container`（拿令牌与应用侧样式）后，上游会给根节点加
+ * `f-drawer-inline` 把它从 `position: fixed` 改成 `absolute` —— 而微前端里绝对定位的包含块
+ * 不可控（`.app-container` 自身未定位，宿主层级随门户而变），抽屉与遮罩会错位。
+ * 这里把包含块语义压回视口，覆盖范围与改造前 `host: "body"` 时完全一致。 */
+.app-container .f-drawer.f-drawer-inline {
+  position: fixed;
+}
+
 /* ===== AppSteps 只读档（clickable=false）的光标 =====
  * 上游 FStep 的 `clickable` prop 在 1.8.4 里**完全没被使用**，`li.clickable` 只由单个 step 的
  * `disabled` 决定 ⇒ 整条只读时上游仍给非禁用项手型光标。拦截已由 AppSteps 的门控承担，

package/lint/__tests__/guardrails.spec.mjs

@@ -41,6 +41,28 @@ function runAudit(script, cwd) {
   return { code: res.status, out: (res.stdout ?? '') + (res.stderr ?? '') }
 }
 
+/** 同上，但可追加参数（如 --strict / --json） */
+function runAuditWith(script, cwd, extraArgs = []) {
+  const res = spawnSync(process.execPath, [join(LINT, script), '--cwd=' + cwd, ...extraArgs], {
+    encoding: 'utf8',
+  })
+  return { code: res.status, out: (res.stdout ?? '') + (res.stderr ?? '') }
+}
+
+/** 改写临时消费仓的护栏配置（其余字段保持默认） */
+function writeConfig(root, apps, extra = {}) {
+  writeFileSync(
+    join(root, 'appkit-guardrails.config.json'),
+    JSON.stringify({
+      apps,
+      srcGlobs: ['src/**/*.ts', 'src/**/*.tsx'],
+      styleGlobs: ['src/**/*.css'],
+      ignore: ['node_modules', 'dist'],
+      ...extra,
+    }),
+  )
+}
+
 test('glob：嵌套路径必须匹配（防「只扫顶层文件」的静默漏扫）', async () => {
   const { globToRegExp } = await import('../shared.mjs')
   const src = globToRegExp('src/**/*.tsx')
@@ -52,6 +74,33 @@ test('glob：嵌套路径必须匹配（防「只扫顶层文件」的静默漏
   assert.ok(css.test('src/features/x/y.css'), '深层 css 应匹配')
 })
 
+test('changedFiles：未暂存的新增文件必须纳入（否则「新增文件必须归零」会假绿）', async () => {
+  const { changedFiles } = await import('../shared.mjs')
+  const root = mkdtempSync(join(tmpdir(), 'appkit-changed-'))
+  const git = (...args) => spawnSync('git', args, { cwd: root, encoding: 'utf8' })
+  try {
+    if (git('init', '-q', '.').status !== 0) return // 无 git：跳过（本机的护栏自测仍覆盖其余规则）
+    git('config', 'user.email', 'guardrails@test')
+    git('config', 'user.name', 'guardrails')
+    writeFileSync(join(root, 'tracked.ts'), 'export const a = 1\n')
+    assert.equal(git('add', 'tracked.ts').status, 0)
+    if (git('commit', '-qm', 'init').status !== 0) return // 提交失败（无身份/无 hooks 环境）：跳过
+
+    writeFileSync(join(root, 'untracked-new.ts'), 'export const b = 2\n')
+    const changed = changedFiles(root)
+    assert.ok(changed, '仓库内应返回改动集合（null 表示非 git 环境）')
+    assert.ok(
+      changed.has('untracked-new.ts'),
+      `未 git add 的新增文件必须进集合，实际：${[...changed].join(', ')}`,
+    )
+
+    writeFileSync(join(root, 'tracked.ts'), 'export const a = 2\n')
+    assert.ok(changedFiles(root).has('tracked.ts'), '已跟踪文件的改动仍须进集合')
+  } finally {
+    rmSync(root, { recursive: true, force: true })
+  }
+})
+
 test('违规样本：三条护栏都必须报错，且每条违规都带 correction', () => {
   const root = makeConsumer('violations-src')
   try {
@@ -133,6 +182,111 @@ test('pending 应用：照常报告但不计入退出码', () => {
   }
 })
 
+test('规则级豁免：只迁骨架（Shell-only）时，结构类纳入门禁、组件与样式类登记豁免', () => {
+  const root = makeConsumer('violations-src')
+  try {
+    // 只迁骨架：结构类立刻要合规（本 fixture 结构违规很多 → 必须仍拦断），
+    // 组件直连与样式类先登记豁免。
+    writeConfig(root, [
+      {
+        dir: 'app',
+        name: 'fixture-app',
+        prefixes: ['other-'],
+        pending: false,
+        waivedRules: [
+          { rule: 'api/*', reason: 'Shell-only：组件替换在下一批次', since: '2026-09-18' },
+          { rule: 'style/*', reason: '同上：样式收口等骨架稳定后', since: '2026-09-18' },
+        ],
+      },
+    ])
+
+    // component-audit：违规只剩豁免项 → 退出码 0，但**照常报告**（技术债必须可见）
+    const component = runAudit('component-audit.mjs', root)
+    assert.equal(component.code, 0, '豁免后不应拦断')
+    assert.ok(component.out.includes('api/farris-import'), '豁免项仍必须出现在报告里')
+    assert.ok(component.out.includes('豁免：已登记'), '豁免项要标明「已登记」')
+    assert.ok(component.out.includes('条属已登记豁免'), '汇总行要给出豁免条数')
+
+    // style-audit：同理（样式类整类豁免）
+    const style = runAudit('style-audit.mjs', root)
+    assert.equal(style.code, 0)
+    assert.ok(style.out.includes('style/visual'))
+
+    // structure-audit：没有豁免 → 结构类违规仍拦断（这才是「只迁骨架」的门禁）
+    const structure = runAudit('structure-audit.mjs', root)
+    assert.equal(structure.code, 1, '结构类规则未豁免，必须仍然拦断')
+    assert.ok(structure.out.includes('structure/no-shell'))
+  } finally {
+    rmSync(root, { recursive: true, force: true })
+  }
+})
+
+test('规则级豁免：--strict 时豁免一律失效（收口验收口径）', () => {
+  const root = makeConsumer('violations-src')
+  try {
+    writeConfig(root, [
+      {
+        dir: 'app',
+        name: 'fixture-app',
+        prefixes: ['other-'],
+        pending: true,
+        waivedRules: [{ rule: 'style/*', reason: '分阶段迁移', since: '2026-09-18' }],
+      },
+    ])
+    assert.equal(runAudit('style-audit.mjs', root).code, 0, '平时：豁免 + 挂起 → 不拦断')
+    assert.equal(runAuditWith('style-audit.mjs', root, ['--strict']).code, 1, '--strict：豁免与挂起都失效')
+  } finally {
+    rmSync(root, { recursive: true, force: true })
+  }
+})
+
+test('规则级豁免：0 条命中时提示可撤销（豁免只该在「还没迁到那层」期间存在）', () => {
+  const root = makeConsumer('clean-src')
+  try {
+    writeConfig(root, [
+      {
+        dir: 'app',
+        name: 'fixture-app',
+        prefixes: ['other-'],
+        pending: false,
+        waivedRules: [{ rule: 'api/*', reason: '上一批次留下的', since: '2026-09-01' }],
+      },
+    ])
+    const { code, out } = runAudit('component-audit.mjs', root)
+    assert.equal(code, 0)
+    assert.ok(out.includes('可以撤销'), `0 条命中应提示撤销，实际输出：${out}`)
+    assert.ok(out.includes('api/*'))
+  } finally {
+    rmSync(root, { recursive: true, force: true })
+  }
+})
+
+test('规则级豁免：配置缺 reason 时直接报错（不留静音键）', () => {
+  const root = makeConsumer('clean-src')
+  try {
+    writeConfig(root, [
+      { dir: 'app', name: 'fixture-app', prefixes: ['other-'], waivedRules: [{ rule: 'api/*' }] },
+    ])
+    const { code, out } = runAudit('component-audit.mjs', root)
+    assert.equal(code, 2, '配置错误应走「环境问题」退出码，而不是静默通过')
+    assert.ok(out.includes('缺少 reason'))
+  } finally {
+    rmSync(root, { recursive: true, force: true })
+  }
+})
+
+test('matchRule：精确名与整类通配各按各的匹配，不做中间通配', async () => {
+  const { matchRule } = await import('../shared.mjs')
+  assert.equal(matchRule('api/farris-import', 'api/farris-import'), true)
+  assert.equal(matchRule('api/*', 'api/legacy-prop'), true)
+  assert.equal(matchRule('api/*', 'style/visual'), false)
+  assert.equal(matchRule('structure/*', 'structure/no-shell'), true)
+  // 中间通配不实现：写出来会让人以为能精确匹配
+  assert.equal(matchRule('style/*-element', 'style/bare-element'), false)
+  assert.equal(matchRule('', 'api/legacy-prop'), false)
+  assert.equal(matchRule(undefined, 'api/legacy-prop'), false)
+})
+
 test('--changed：非 git 环境下不裁剪（宁可多检查）', () => {
   const root = makeConsumer('violations-src')
   try {

package/lint/component-audit.mjs

@@ -13,7 +13,7 @@
  *     `selection={{…}}` 是 app-kit 自己的结构化契约，**合法**；
  *     而 `rowOption` / `columnOption` / `enableSelectRow` / `enabelSelectRow` 等属于底层，一律禁止。
  *
- * 用法：node node_modules/@manohub/app-kit/lint/component-audit.mjs [--json] [--changed]
+ * 用法：pnpm exec appkit lint:component [--json] [--changed]
  */
 import { readFileSync } from 'node:fs'
 import { join } from 'node:path'

package/lint/guardrails.config.schema.json

@@ -30,6 +30,34 @@
             "type": "boolean",
             "default": false,
             "description": "存量挂起：为 true 时该应用仅产出基线报告，不计入退出码（迁移完成后置 false 即自动纳入门禁）。"
+          },
+          "waivedRules": {
+            "type": "array",
+            "description": "规则级豁免（**分阶段迁移**用，典型是「只迁骨架 / Shell-only」）：登记的规则照常报告但不计入退出码。要收口时跑 `--strict` 验证，并在撤销豁免后纳入门禁。规则名支持 `域/*` 整类通配（如 structure/*）；每条必须写 reason。",
+            "items": {
+              "oneOf": [
+                { "type": "string", "description": "简写形式（不推荐：没有理由，无法审计）" },
+                {
+                  "type": "object",
+                  "required": ["rule", "reason"],
+                  "properties": {
+                    "rule": {
+                      "type": "string",
+                      "description": "规则名（如 api/farris-import）或整类通配（如 style/*）。"
+                    },
+                    "reason": {
+                      "type": "string",
+                      "description": "为什么暂时不查 + 什么时候收口（如「只迁骨架，组件替换在下一批次」）。必填。"
+                    },
+                    "since": {
+                      "type": "string",
+                      "description": "登记日期（ISO 8601，如 2026-09-18）。"
+                    }
+                  },
+                  "additionalProperties": false
+                }
+              ]
+            }
           }
         }
       }
@@ -69,6 +97,20 @@
       "exemptionRegistry": "docs/appkit-exemptions.md",
       "contractDoc": "node_modules/@manohub/app-kit/CONTRACT.md",
       "ignore": ["node_modules", "dist"]
+    },
+    {
+      "apps": [
+        {
+          "dir": ".",
+          "name": "shell-only-app",
+          "prefixes": ["so-"],
+          "pending": false,
+          "waivedRules": [
+            { "rule": "api/*", "reason": "只迁骨架（Shell-only）：组件替换在下一批次", "since": "2026-09-18" },
+            { "rule": "style/*", "reason": "同上：样式收口等骨架稳定后再做", "since": "2026-09-18" }
+          ]
+        }
+      ]
     }
   ]
 }

package/lint/pre-commit.sample

@@ -1,26 +1,38 @@
-#!/bin/sh
-# app-kit 护栏 pre-commit 钩子样本：只检查**已改动文件**，目标 < 3 秒（否则人会在本机把它关掉）。
-#
-# 启用（不需要改 git 配置，默认 hooks 目录即可）：
-#   cp node_modules/@manohub/app-kit/lint/pre-commit.sample .git/hooks/pre-commit
-#   chmod +x .git/hooks/pre-commit
-#
-# 应用包不是仓库根时（monorepo，如 apps/sub-app），用环境变量指出包目录：
-#   APPKIT_APP_DIR=apps/sub-app   （可在 .git/hooks/pre-commit 里写死，或提交前 export）
-#
-# 说明：护栏以「应用包根」为 cwd 读取 appkit-guardrails.config.json；仓库根不存在该配置时
-# 必须给 APPKIT_APP_DIR，否则会以「未找到配置」失败（这是刻意为之：宁可报错，也不要静默跳过检查）。
-set -e
-
-AUDIT="node_modules/@manohub/app-kit/lint/run-all.mjs"
-
-if [ ! -f "$AUDIT" ]; then
-  echo "[guardrails] 未安装 @manohub/app-kit（找不到 $AUDIT），跳过检查"
-  exit 0
-fi
-
-if [ -n "$APPKIT_APP_DIR" ]; then
-  exec node "$AUDIT" --changed --cwd="$APPKIT_APP_DIR"
-fi
-
-exec node "$AUDIT" --changed
+#!/bin/sh
+# app-kit 护栏 pre-commit 钩子样本：只检查**已改动文件**（含新增但未提交的文件），目标 < 3 秒
+# （否则人会在本机把它关掉）。
+#
+# 启用（不需要改 git 配置，默认 hooks 目录即可）：
+#   cp node_modules/@manohub/app-kit/lint/pre-commit.sample .git/hooks/pre-commit
+#   chmod +x .git/hooks/pre-commit
+#
+# 应用包不是仓库根时（monorepo，如 apps/sub-app）：**必须**用环境变量指出包目录，
+# 因为钩子的 cwd 恒为仓库根，而本包通常只装在应用包自己的 node_modules 下：
+#   APPKIT_APP_DIR=apps/sub-app       （推荐在钩子文件里写死一行，或提交前 export）
+#
+# 说明：护栏以「应用包根」为 cwd 读取 appkit-guardrails.config.json；找不到脚本或配置时
+# 会明确告知并**跳过**本次检查（不阻塞提交）—— 静默通过的假绿比报错更危险。
+set -e
+
+# 应用包目录（缺省仓库根）
+APP_DIR="${APPKIT_APP_DIR:-.}"
+
+# 护栏脚本按「应用包自己的 node_modules → 仓库根 node_modules」依次找
+if [ -f "$APP_DIR/node_modules/@manohub/app-kit/lint/run-all.mjs" ]; then
+  AUDIT="$APP_DIR/node_modules/@manohub/app-kit/lint/run-all.mjs"
+elif [ -f "node_modules/@manohub/app-kit/lint/run-all.mjs" ]; then
+  AUDIT="node_modules/@manohub/app-kit/lint/run-all.mjs"
+else
+  echo "[guardrails] 未找到护栏脚本（已查 $APP_DIR/node_modules 与 node_modules）。"
+  echo "[guardrails] monorepo 请在钩子里设置 APPKIT_APP_DIR=<应用包目录>（如 apps/sub-app），"
+  echo "[guardrails] 否则本次提交不检查（不阻塞，但请尽快修好这条路径）。"
+  exit 0
+fi
+
+if [ ! -f "$APP_DIR/appkit-guardrails.config.json" ]; then
+  echo "[guardrails] $APP_DIR 下缺少 appkit-guardrails.config.json，无法确定被审计的应用。"
+  echo "[guardrails] 配置片段见 node_modules/@manohub/app-kit/CONTRACT.md §8。"
+  exit 0
+fi
+
+exec node "$AUDIT" --changed --cwd="$APP_DIR"

package/lint/run-all.mjs

@@ -1,59 +1,63 @@
-#!/usr/bin/env node
-/**
- * run-all —— 三条护栏的统一入口（接入方只挂这一条，见 CONTRACT.md §8）。
- *
- * 并发跑 style / component / structure，汇总输出与退出码；支持 `--changed`（只跑改动文件，供 pre-commit）。
- * 任一脚本报 error 即整体失败；`--json` 时输出聚合结果。
- *
- * 用法（接入方的 `package.json` 只挂前两条，另两条是排查单条时才用的）：
- *   node node_modules/@manohub/app-kit/lint/run-all.mjs            # 全量（挂成 "lint"）
- *   node node_modules/@manohub/app-kit/lint/run-all.mjs --changed   # 只跑改动文件（挂成 "lint:changed"）
- *   node node_modules/@manohub/app-kit/lint/style-audit.mjs         # 单条排查：style / component / structure
- *   node node_modules/@manohub/app-kit/lint/run-all.mjs --json
- */
-import { spawn } from 'node:child_process'
-import { fileURLToPath } from 'node:url'
-import { dirname, join } from 'node:path'
-import { parseArgs } from './shared.mjs'
-
-const HERE = dirname(fileURLToPath(import.meta.url))
-const AUDITS = ['style-audit.mjs', 'component-audit.mjs', 'structure-audit.mjs']
-
-const args = parseArgs()
-const passthrough = process.argv.slice(2).filter((a) => a.startsWith('--app=') || a.startsWith('--cwd='))
-if (args.changed) passthrough.push('--changed')
-if (args.json) passthrough.push('--json')
-
-const runOne = (script) =>
-  new Promise((resolve) => {
-    const child = spawn(process.execPath, [join(HERE, script), ...passthrough], {
-      cwd: args.cwd,
-      stdio: ['ignore', 'pipe', 'pipe'],
-    })
-    let stdout = ''
-    let stderr = ''
-    child.stdout.on('data', (d) => (stdout += d))
-    child.stderr.on('data', (d) => (stderr += d))
-    child.on('close', (code) => resolve({ script, code, stdout, stderr }))
-  })
-
-const started = Date.now()
-const results = await Promise.all(AUDITS.map(runOne))
-const elapsed = ((Date.now() - started) / 1000).toFixed(2)
-
-if (args.json) {
-  process.stdout.write(JSON.stringify({ audits: results.map((r) => ({ script: r.script, code: r.code })), elapsed }, null, 2) + '\n')
-} else {
-  for (const r of results) {
-    if (r.stdout) process.stdout.write(r.stdout)
-    if (r.stderr) process.stderr.write(r.stderr)
-  }
-  const failed = results.filter((r) => r.code !== 0)
-  process.stdout.write(
-    failed.length === 0
-      ? `✓ 护栏（三条）：全绿（${elapsed}s）\n`
-      : `✗ 护栏（三条）：${failed.map((f) => f.script).join(' / ')} 未通过（${elapsed}s）\n`,
-  )
-}
-
-process.exit(results.some((r) => r.code !== 0) ? 1 : 0)
+#!/usr/bin/env node
+/**
+ * run-all —— 三条护栏的统一入口（接入方只挂这一条，见 CONTRACT.md §8）。
+ *
+ * 并发跑 style / component / structure，汇总输出与退出码；支持 `--changed`（只跑改动文件，供 pre-commit）。
+ * 任一脚本报 error 即整体失败；`--json` 时输出聚合结果。
+ *
+ * 用法（经包的命令入口；接入方的 `package.json` 只挂前两条，其余是排查时才用的）：
+ *   pnpm exec appkit lint             # 全量（挂成 "lint"）
+ *   pnpm exec appkit lint --changed   # 只跑改动文件（挂成 "lint:changed"）
+ *   pnpm exec appkit lint --strict    # 收口验收：存量挂起与规则豁免一律失效
+ *   pnpm exec appkit lint:style       # 单条排查：style / component / structure
+ *   pnpm exec appkit lint --json
+ *
+ * 直接跑本脚本（`node node_modules/@manohub/app-kit/lint/run-all.mjs`）与上面完全等价 ——
+ * CLI 只是薄壳，已有钩子/脚本不必改。
+ */
+import { spawn } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+import { dirname, join } from 'node:path'
+import { parseArgs } from './shared.mjs'
+
+const HERE = dirname(fileURLToPath(import.meta.url))
+const AUDITS = ['style-audit.mjs', 'component-audit.mjs', 'structure-audit.mjs']
+
+const args = parseArgs()
+const passthrough = process.argv.slice(2).filter((a) => a.startsWith('--app=') || a.startsWith('--cwd='))
+if (args.changed) passthrough.push('--changed')
+if (args.json) passthrough.push('--json')
+
+const runOne = (script) =>
+  new Promise((resolve) => {
+    const child = spawn(process.execPath, [join(HERE, script), ...passthrough], {
+      cwd: args.cwd,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    })
+    let stdout = ''
+    let stderr = ''
+    child.stdout.on('data', (d) => (stdout += d))
+    child.stderr.on('data', (d) => (stderr += d))
+    child.on('close', (code) => resolve({ script, code, stdout, stderr }))
+  })
+
+const started = Date.now()
+const results = await Promise.all(AUDITS.map(runOne))
+const elapsed = ((Date.now() - started) / 1000).toFixed(2)
+
+if (args.json) {
+  process.stdout.write(JSON.stringify({ audits: results.map((r) => ({ script: r.script, code: r.code })), elapsed }, null, 2) + '\n')
+} else {
+  for (const r of results) {
+    if (r.stdout) process.stdout.write(r.stdout)
+    if (r.stderr) process.stderr.write(r.stderr)
+  }
+  const failed = results.filter((r) => r.code !== 0)
+  process.stdout.write(
+    failed.length === 0
+      ? `✓ 护栏（三条）：全绿（${elapsed}s）\n`
+      : `✗ 护栏（三条）：${failed.map((f) => f.script).join(' / ')} 未通过（${elapsed}s）\n`,
+  )
+}
+
+process.exit(results.some((r) => r.code !== 0) ? 1 : 0)