@done-coding/admin-core 0.26.1 → 0.27.0

package/es/index.mjs

@@ -14,74 +14,76 @@ import { default as default15 } from "./components/form/FormSubmitBtn.vue.mjs";
 import { default as default16 } from "./components/form/FormTree.vue.mjs";
 import { default as default17 } from "./components/form/FormVerifyCode.vue.mjs";
 import { default as default18 } from "./components/display/HeightProvider.vue.mjs";
-import { default as default19 } from "./components/modal/ImagePreviewTrigger.vue.mjs";
-import { default as default20 } from "./components/menu/MenuItemSub.vue.mjs";
-import { default as default21 } from "./components/menu/MenuTree.vue.mjs";
-import { default as default22 } from "./components/modal/ModalImagePreview.vue.mjs";
-import { default as default23 } from "./components/modal/ModalPorter.vue.mjs";
-import { default as default24 } from "./components/modal/ModalShelf.vue.mjs";
-import { default as default25 } from "./components/panel/PanelItemNestPanel.vue.mjs";
-import { default as default26 } from "./components/misc/SelectModule.vue.mjs";
-import { default as default27 } from "./components/display/ShadowClone.vue.mjs";
-import { default as default28 } from "./components/slot-layout/SlotLayoutTemplate.vue.mjs";
-import { default as default29 } from "./components/table/TableEmpty.vue.mjs";
-import { default as default30 } from "./components/display/TabsMain.vue.mjs";
-import { default as default31 } from "./components/misc/TriggerAutoImport.vue.mjs";
-import { default as default32 } from "./components/display/WatchSize.vue.mjs";
+import { default as default19 } from "./components/icon/IconHammer.vue.mjs";
+import { default as default20 } from "./components/modal/ImagePreviewTrigger.vue.mjs";
+import { default as default21 } from "./components/menu/MenuItemSub.vue.mjs";
+import { default as default22 } from "./components/menu/MenuTree.vue.mjs";
+import { default as default23 } from "./components/modal/ModalImagePreview.vue.mjs";
+import { default as default24 } from "./components/modal/ModalPorter.vue.mjs";
+import { default as default25 } from "./components/modal/ModalShelf.vue.mjs";
+import { default as default26 } from "./components/panel/PanelItemNestPanel.vue.mjs";
+import { default as default27 } from "./components/misc/SelectModule.vue.mjs";
+import { default as default28 } from "./components/display/ShadowClone.vue.mjs";
+import { default as default29 } from "./components/slot-layout/SlotLayoutTemplate.vue.mjs";
+import { default as default30 } from "./components/table/TableEmpty.vue.mjs";
+import { default as default31 } from "./components/display/TabsMain.vue.mjs";
+import { default as default32 } from "./components/misc/TriggerAutoImport.vue.mjs";
+import { default as default33 } from "./components/display/WatchSize.vue.mjs";
 import { APP_API_LIST_MODEL_KEY_CONFIG } from "./config/list-model.mjs";
 import { APP_GLOBAL_IMAGE_PREVIEW_KEY, APP_GLOBAL_VIDEO_PREVIEW_KEY, GLOBAL_MODAL_REMOTE_KEY } from "./components/modal/modal-global-keys.mjs";
 import { APP_LAYOUT_APP_STORE_KEY, APP_LAYOUT_BRIDGE_KEY, APP_LAYOUT_USER_STORE_KEY, APP_PAGE_CONTENT_INSET, APP_PAGE_LIST_DETAIL_CONTEXT, BODY_CONTENT_VIEWPORT_HEIGHT, BODY_CONTENT_VIEWPORT_INSET, BODY_CONTENT_VIEWPORT_RECT, CORE_BRIDGE_KEY, FORM_NEST_REGISTRY_KEY, NEST_LAYOUT_SCALE_KEY, SCOPE_VIEWPORT_MAX_HEIGHT, TABS_MAIN_VISUAL_LEVEL, getModalShelfInjectionKey } from "./inject/key.mjs";
 import { APP_PAGE_SLOT_Z_INDEX, computeAppPageContentInset, computeAppPageReducedViewportHeight, computeAppPageReducedViewportWidth, computeAppPageSlotShimStyles, computeAppPageSlotStyles } from "./components/app-layout/app-page-geometry.mjs";
-import { default as default33 } from "./components/display/ActionConfirm.vue.mjs";
-import { default as default34 } from "./components/app-layout/AppAside.vue.mjs";
-import { default as default35 } from "./components/app-layout/AppBody.vue.mjs";
-import { default as default36 } from "./components/app-layout/AppBreadcrumb.vue.mjs";
-import { default as default37 } from "./components/app-layout/AppFooter.vue.mjs";
-import { default as default38 } from "./components/app-layout/AppHeader.vue.mjs";
-import { default as default39 } from "./components/app-layout/AppLayout.vue.mjs";
-import { default as default40 } from "./components/app-layout/AppPage.vue.mjs";
-import { default as default41 } from "./components/page-layout/AppPageDetail.vue.mjs";
-import { default as default42 } from "./components/app-layout/AppSidebar.vue.mjs";
-import { default as default43 } from "./components/app-layout/AppTheme.vue.mjs";
-import { default as default44 } from "./components/misc/AutoRefresh.vue.mjs";
-import { default as default45 } from "./components/misc/AutoRefreshGroup.vue.mjs";
-import { default as default46 } from "./components/display/BadgeMark.vue.mjs";
+import { default as default34 } from "./components/display/ActionConfirm.vue.mjs";
+import { default as default35 } from "./components/app-layout/AppAside.vue.mjs";
+import { default as default36 } from "./components/app-layout/AppBody.vue.mjs";
+import { default as default37 } from "./components/app-layout/AppBreadcrumb.vue.mjs";
+import { default as default38 } from "./components/app-layout/AppFooter.vue.mjs";
+import { default as default39 } from "./components/app-layout/AppHeader.vue.mjs";
+import { default as default40 } from "./components/app-layout/AppLayout.vue.mjs";
+import { default as default41 } from "./components/app-layout/AppPage.vue.mjs";
+import { default as default42 } from "./components/page-layout/AppPageDetail.vue.mjs";
+import { default as default43 } from "./components/app-layout/AppSidebar.vue.mjs";
+import { default as default44 } from "./components/app-layout/AppTheme.vue.mjs";
+import { default as default45 } from "./components/misc/AutoRefresh.vue.mjs";
+import { default as default46 } from "./components/misc/AutoRefreshGroup.vue.mjs";
+import { BADGE_MASK_KINDS } from "./bridge/badge.mjs";
+import { default as default47 } from "./components/display/BadgeMark.vue.mjs";
 import { CORE_VIEWPORT_DECOR_ZINDEX_ABOVE, CORE_VIEWPORT_DECOR_ZINDEX_BELOW } from "./components/app-layout/viewport.mjs";
-import { default as default47, default as default48 } from "./components/modal/ModalConfirm.vue.mjs";
+import { default as default48, default as default49 } from "./components/modal/ModalConfirm.vue.mjs";
 import { DC_SLOT_ATTR, SlotRegion, parseSlotRegion } from "./config/slot-region.mjs";
-import { default as default49 } from "./components/data-view/DataGridView.vue.mjs";
+import { default as default50 } from "./components/data-view/DataGridView.vue.mjs";
 import { EXPORT_MAX_LIMIT, OPERATE_COLUMN_PROP, exportCSV, pickExportColumns } from "./utils/export.mjs";
 import { FORM_CONFIG_SELECT_ALL_VALUE, getConfirmPasswordRule, passwordRule, setFormComponentType } from "./helpers/form.mjs";
 import { FORM_ITEM_CHANGE_LOADING, NEST_LAYOUT_TIERS, ceilToTier, generateFormData, getBlurSubmit, getChangeSubmit, getDatePickerShortcuts, getEnterSubmit, getPlaceholder, getVModelSugar, parseFormData, resolveFormLayout, resolveLayoutSpan, setInputComponent, setSelectComponent, stringifyFormData, swiftFormItemConfig } from "./components/form/utils.mjs";
-import { default as default50 } from "./components/form/FormActiveFilter.vue.mjs";
-import { default as default51 } from "./components/form/FormItemNestForm.vue.mjs";
-import { default as default52 } from "./components/form/FormItemNestFormList.vue.mjs";
-import { default as default53 } from "./components/form/FormMain.vue.mjs";
-import { default as default54 } from "./components/form/FormSearch.vue.mjs";
-import { default as default55 } from "./components/form/FormShadowCloneDispatch.vue.mjs";
-import { default as default56 } from "./components/form/FormSortSwitch.vue.mjs";
-import { default as default57 } from "./components/form/FormSortSwitchGroup.vue.mjs";
-import { default as default58 } from "./components/form/FormSubmitPanel.vue.mjs";
-import { default as default59 } from "./components/form/FormUpload.vue.mjs";
-import { default as default60 } from "./components/form/FormUploadAudio.vue.mjs";
-import { default as default61 } from "./components/form/FormUploadImage.vue.mjs";
-import { default as default62 } from "./components/form/FormUploadVideo.vue.mjs";
-import { default as default63 } from "./components/form/FormVerifyImage.vue.mjs";
-import { default as default64 } from "./components/data-view/InfiniteListView.vue.mjs";
-import { default as default65, default as default66 } from "./components/list-layout/ListLayout.vue.mjs";
-import { default as default67 } from "./components/modal/ModalVideoPreview.vue.mjs";
-import { default as default68 } from "./components/panel/PanelEditSwitch.vue.mjs";
-import { default as default69 } from "./components/panel/PanelItem.vue.mjs";
-import { default as default70 } from "./components/panel/PanelItemNestForm.vue.mjs";
-import { default as default71 } from "./components/panel/PanelMain.vue.mjs";
+import { default as default51 } from "./components/form/FormActiveFilter.vue.mjs";
+import { default as default52 } from "./components/form/FormItemNestForm.vue.mjs";
+import { default as default53 } from "./components/form/FormItemNestFormList.vue.mjs";
+import { default as default54 } from "./components/form/FormMain.vue.mjs";
+import { default as default55 } from "./components/form/FormSearch.vue.mjs";
+import { default as default56 } from "./components/form/FormShadowCloneDispatch.vue.mjs";
+import { default as default57 } from "./components/form/FormSortSwitch.vue.mjs";
+import { default as default58 } from "./components/form/FormSortSwitchGroup.vue.mjs";
+import { default as default59 } from "./components/form/FormSubmitPanel.vue.mjs";
+import { default as default60 } from "./components/form/FormUpload.vue.mjs";
+import { default as default61 } from "./components/form/FormUploadAudio.vue.mjs";
+import { default as default62 } from "./components/form/FormUploadImage.vue.mjs";
+import { default as default63 } from "./components/form/FormUploadVideo.vue.mjs";
+import { default as default64 } from "./components/form/FormVerifyImage.vue.mjs";
+import { default as default65 } from "./components/data-view/InfiniteListView.vue.mjs";
+import { default as default66, default as default67 } from "./components/list-layout/ListLayout.vue.mjs";
+import { default as default68 } from "./components/modal/ModalVideoPreview.vue.mjs";
+import { default as default69 } from "./components/panel/PanelEditSwitch.vue.mjs";
+import { default as default70 } from "./components/panel/PanelItem.vue.mjs";
+import { default as default71 } from "./components/panel/PanelItemNestForm.vue.mjs";
+import { default as default72 } from "./components/panel/PanelMain.vue.mjs";
 import { ROUTE_MODULE_LEVEL, TabsMainReplaceQueryKey } from "./config/route.mjs";
-import { default as default72 } from "./components/slot-layout/SlotLayoutFlowAside.vue.mjs";
+import { default as default73 } from "./components/slot-layout/SlotLayoutFlowAside.vue.mjs";
 import { TABLE_COLUMN_KEY_OPERATE, TABLE_COLUMN_KEY_SELECTION } from "./components/table/constants.mjs";
-import { default as default73 } from "./components/table/TableMain.vue.mjs";
-import { default as default74 } from "./components/table/TableSkeleton.vue.mjs";
-import { default as default75 } from "./components/table/TableToolbar.vue.mjs";
-import { default as default76 } from "./components/modal/VideoPreviewTrigger.vue.mjs";
-import { default as default77 } from "./components/view-layout/ViewLayout.vue.mjs";
+import { default as default74 } from "./components/table/TableMain.vue.mjs";
+import { default as default75 } from "./components/table/TableSkeleton.vue.mjs";
+import { default as default76 } from "./components/table/TableToolbar.vue.mjs";
+import { default as default77 } from "./components/modal/VideoPreviewTrigger.vue.mjs";
+import { default as default78 } from "./components/view-layout/ViewLayout.vue.mjs";
 import { buildRhythmCss, useCoreThemeApply } from "./hooks/use-theme-apply.mjs";
 import { checkLogin } from "./router/guard/login.mjs";
 import { checkPermission } from "./router/guard/permission.mjs";
@@ -128,102 +130,104 @@ export {
   APP_PAGE_SLOT_Z_INDEX,
   default2 as ActionBtn,
   default3 as ActionBtnGroup,
-  default33 as ActionConfirm,
-  default34 as AppAside,
-  default35 as AppBody,
-  default36 as AppBreadcrumb,
-  default37 as AppFooter,
-  default38 as AppHeader,
-  default39 as AppLayout,
-  default40 as AppPage,
-  default41 as AppPageDetail,
+  default34 as ActionConfirm,
+  default35 as AppAside,
+  default36 as AppBody,
+  default37 as AppBreadcrumb,
+  default38 as AppFooter,
+  default39 as AppHeader,
+  default40 as AppLayout,
+  default41 as AppPage,
+  default42 as AppPageDetail,
   default4 as AppPageListDetailLayout,
-  default42 as AppSidebar,
-  default43 as AppTheme,
-  default44 as AutoRefresh,
-  default45 as AutoRefreshGroup,
+  default43 as AppSidebar,
+  default44 as AppTheme,
+  default45 as AutoRefresh,
+  default46 as AutoRefreshGroup,
+  BADGE_MASK_KINDS,
   BODY_CONTENT_VIEWPORT_HEIGHT,
   BODY_CONTENT_VIEWPORT_INSET,
   BODY_CONTENT_VIEWPORT_RECT,
-  default46 as BadgeMark,
+  default47 as BadgeMark,
   default5 as BooleanTag,
   CORE_BRIDGE_KEY,
   CORE_VIEWPORT_DECOR_ZINDEX_ABOVE,
   CORE_VIEWPORT_DECOR_ZINDEX_BELOW,
-  default47 as ConfirmModal,
+  default48 as ConfirmModal,
   DC_SLOT_ATTR,
-  default49 as DataGridView,
+  default50 as DataGridView,
   default6 as DetailModal,
   EXPORT_MAX_LIMIT,
   FORM_CONFIG_SELECT_ALL_VALUE,
   FORM_ITEM_CHANGE_LOADING,
   FORM_NEST_REGISTRY_KEY,
-  default50 as FormActiveFilter,
+  default51 as FormActiveFilter,
   default8 as FormInput,
   default9 as FormInputShadowClone,
-  default51 as FormItemNestForm,
-  default52 as FormItemNestFormList,
-  default53 as FormMain,
+  default52 as FormItemNestForm,
+  default53 as FormItemNestFormList,
+  default54 as FormMain,
   default10 as FormModal,
   default12 as FormRadioGroup,
-  default54 as FormSearch,
+  default55 as FormSearch,
   default13 as FormSelect,
   default14 as FormSelectShadowClone,
-  default55 as FormShadowCloneDispatch,
-  default56 as FormSortSwitch,
-  default57 as FormSortSwitchGroup,
+  default56 as FormShadowCloneDispatch,
+  default57 as FormSortSwitch,
+  default58 as FormSortSwitchGroup,
   default15 as FormSubmitBtn,
-  default58 as FormSubmitPanel,
+  default59 as FormSubmitPanel,
   default16 as FormTree,
-  default59 as FormUpload,
-  default60 as FormUploadAudio,
-  default61 as FormUploadImage,
-  default62 as FormUploadVideo,
+  default60 as FormUpload,
+  default61 as FormUploadAudio,
+  default62 as FormUploadImage,
+  default63 as FormUploadVideo,
   default17 as FormVerifyCode,
-  default63 as FormVerifyImage,
+  default64 as FormVerifyImage,
   GLOBAL_MODAL_REMOTE_KEY,
   default18 as HeightProvider,
-  default19 as ImagePreviewTrigger,
-  default64 as InfiniteListView,
-  default65 as ListLayout,
-  default66 as ListPage,
-  default20 as MenuItemSub,
-  default21 as MenuTree,
-  default48 as ModalConfirm,
+  default19 as IconHammer,
+  default20 as ImagePreviewTrigger,
+  default65 as InfiniteListView,
+  default66 as ListLayout,
+  default67 as ListPage,
+  default21 as MenuItemSub,
+  default22 as MenuTree,
+  default49 as ModalConfirm,
   default7 as ModalDetail,
   default11 as ModalForm,
-  default22 as ModalImagePreview,
-  default23 as ModalPorter,
-  default24 as ModalShelf,
-  default67 as ModalVideoPreview,
+  default23 as ModalImagePreview,
+  default24 as ModalPorter,
+  default25 as ModalShelf,
+  default68 as ModalVideoPreview,
   NEST_LAYOUT_SCALE_KEY,
   NEST_LAYOUT_TIERS,
   OPERATE_COLUMN_PROP,
-  default68 as PanelEditSwitch,
-  default69 as PanelItem,
-  default70 as PanelItemNestForm,
-  default25 as PanelItemNestPanel,
-  default71 as PanelMain,
+  default69 as PanelEditSwitch,
+  default70 as PanelItem,
+  default71 as PanelItemNestForm,
+  default26 as PanelItemNestPanel,
+  default72 as PanelMain,
   ROUTE_MODULE_LEVEL,
   SCOPE_VIEWPORT_MAX_HEIGHT,
-  default26 as SelectModule,
-  default27 as ShadowClone,
-  default72 as SlotLayoutFlowAside,
-  default28 as SlotLayoutTemplate,
+  default27 as SelectModule,
+  default28 as ShadowClone,
+  default73 as SlotLayoutFlowAside,
+  default29 as SlotLayoutTemplate,
   SlotRegion,
   TABLE_COLUMN_KEY_OPERATE,
   TABLE_COLUMN_KEY_SELECTION,
   TABS_MAIN_VISUAL_LEVEL,
-  default29 as TableEmpty,
-  default73 as TableMain,
-  default74 as TableSkeleton,
-  default75 as TableToolbar,
-  default30 as TabsMain,
+  default30 as TableEmpty,
+  default74 as TableMain,
+  default75 as TableSkeleton,
+  default76 as TableToolbar,
+  default31 as TabsMain,
   TabsMainReplaceQueryKey,
-  default31 as TriggerAutoImport,
-  default76 as VideoPreviewTrigger,
-  default77 as ViewLayout,
-  default32 as WatchSize,
+  default32 as TriggerAutoImport,
+  default77 as VideoPreviewTrigger,
+  default78 as ViewLayout,
+  default33 as WatchSize,
   buildRhythmCss,
   ceilToTier,
   checkLogin,

package/es/style.css

@@ -66,13 +66,18 @@
   justify-content: flex-end;
   gap: 8px;
 }
-.badge-mark[data-v-12868883] .el-badge__content.is-fixed {
+.badge-mark[data-v-4116ac36] .el-badge__content.is-fixed {
   right: 0;
   transform: translateY(-50%) translateX(calc(100% + 2px));
 }
-.badge-mark_middle[data-v-12868883] .el-badge__content.is-fixed {
+.badge-mark_middle[data-v-4116ac36] .el-badge__content.is-fixed {
   top: 50%;
 }
+.badge-mark[data-v-4116ac36] .badge-mark__icon {
+  display: block;
+  font-size: 1em;
+  line-height: 1;
+}
 .app-page[data-v-3ef165a7] {
   --dc-page-content-viewport-top: var(--v6b53f4c2);
   --dc-page-content-viewport-bottom: var(--v1c770cbe);
@@ -415,23 +420,23 @@ to {
   color: var(--dc-core-primary-color);
   font-weight: 600;
 }
-.dc-tabs-tile--nav-absolute[data-v-acb4bb13],
-.dc-tabs-tile--nav-fixed[data-v-acb4bb13] {
+.dc-tabs-tile--nav-absolute[data-v-9b8e85b8],
+.dc-tabs-tile--nav-fixed[data-v-9b8e85b8] {
   position: relative;
 }
-.dc-tabs-tile--nav-sticky[data-v-acb4bb13] {
+.dc-tabs-tile--nav-sticky[data-v-9b8e85b8] {
   display: flex;
   flex-direction: column;
 }
-.dc-tabs-tile__scroll[data-v-acb4bb13] {
+.dc-tabs-tile__scroll[data-v-9b8e85b8] {
   display: flex;
   flex-direction: column;
   gap: 12px;
 }
-.dc-tabs-tile__card[data-v-acb4bb13] {
+.dc-tabs-tile__card[data-v-9b8e85b8] {
   width: 100%;
 }
-.dc-tabs-tile__nav[data-v-acb4bb13] {
+.dc-tabs-tile__nav[data-v-9b8e85b8] {
   z-index: 2;
   max-height: 60%;
   overflow: auto;
@@ -536,7 +541,7 @@ to {
   height: 100%;
   padding: 0 20px;
 }
-.app-header[data-v-40b13903] {
+.app-header[data-v-d887bc4c] {
   transition-duration: 0.3s;
   transition-property: height;
   transition-timing-function: linear;
@@ -544,13 +549,13 @@ to {
   box-shadow: var(--dc-core-shadow, var(--el-box-shadow));
   z-index: 1;
 }
-.app-header-module[data-v-40b13903] {
+.app-header-module[data-v-d887bc4c] {
   display: flex;
   flex: 1;
   height: 100%;
   overflow-x: auto;
 }
-.app-header-module-item[data-v-40b13903] {
+.app-header-module-item[data-v-d887bc4c] {
   display: flex;
   justify-content: center;
   align-items: center;
@@ -558,24 +563,24 @@ to {
   white-space: nowrap;
   height: 100%;
 }
-.app-header-module-item[data-v-40b13903]:hover,
-.app-header-module-item_active[data-v-40b13903] {
-  color: var(--v05959ac0);
+.app-header-module-item[data-v-d887bc4c]:hover,
+.app-header-module-item_active[data-v-d887bc4c] {
+  color: var(--v7733782f);
 }
-.app-header-module-item_active[data-v-40b13903] {
+.app-header-module-item_active[data-v-d887bc4c] {
   position: relative;
 }
-.app-header-module-item_active[data-v-40b13903]::before {
+.app-header-module-item_active[data-v-d887bc4c]::before {
   content: "";
   position: absolute;
   left: 50%;
   top: 0;
   width: 100%;
   height: 3px;
-  background-color: var(--v05959ac0);
+  background-color: var(--v7733782f);
   transform: translateX(-50%);
 }
-.app-header-shim[data-v-40b13903] {
+.app-header-shim[data-v-d887bc4c] {
   width: 100%;
   height: 100%;
   display: flex;
@@ -585,10 +590,10 @@ to {
   font-size: 18px;
   font-weight: bold;
 }
-.app-header-module-item__icon[data-v-40b13903] {
+.app-header-module-item__icon[data-v-d887bc4c] {
   margin-right: 8px;
 }
-.app-header-right[data-v-40b13903] {
+.app-header-right[data-v-d887bc4c] {
   padding-left: 80px;
   display: flex;
   align-items: center;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@done-coding/admin-core",
-  "version": "0.26.1",
+  "version": "0.27.0",
   "description": "内部前端库",
   "private": false,
   "main": "es/index.mjs",
@@ -83,5 +83,5 @@
   "dependencies": {
     "@tanstack/vue-virtual": "^3.13.35"
   },
-  "gitHead": "413474bbb4f32f343d3cfa990815985518729ef1"
+  "gitHead": "2c445676329b49413fcb729f224638ecec4c0e06"
 }

package/src/bridge/docs/README.md

@@ -50,6 +50,28 @@ appCoreBridge.theme.setStyle("studio-stage");
 appCoreBridge.theme.setDark(true);
 ```
 
+### 明暗覆盖（`theme.setDarkOverride`）
+
+明暗有两层：`theme.setMode` / `setDark` 改的是**用户偏好**（写缓存、下次启动恢复）；
+`theme.setDarkOverride` 改的是**当前会话的临时覆盖**——压过 mode 派生，但 [MUST NOT]
+触达 storage、[MUST NOT] 改 `themeMode`。
+
+```ts
+appCoreBridge.theme.setDarkOverride(true);   // 临时暗色（不写缓存）
+appCoreBridge.theme.setDarkOverride();       // 无参清除覆盖，回落用户偏好
+```
+
+典型场景：本应用被宿主以 iframe 嵌入（如 SSO 登录页），明暗须跟随宿主临时接管，
+而该应用**独立打开时仍按自己缓存的偏好**。
+
+覆盖期间 `themeIsDark` / `themeColors` / `<html>.dark` 全部跟随覆盖值（无「视觉暗、
+状态亮」的脱钩）；明暗切换控件仍显示 `themeMode`，即用户自己的偏好——语义上就该如此：
+偏好没变，只是当前被宿主接管。
+
+[MUST NOT] 用 `setDark` 模拟临时覆盖：`persist()` 写的是 `themeStyle + themeMode` 整条
+payload，覆盖值一旦进了 `themeMode`，后续任何一次 `setStyle`（含插件风格异步注册时
+`add` 内自动触发的那次）都会把它顺手写进缓存、污染独立打开时的偏好。
+
 ## 徽标注册表（`bridge.badge`）
 
 一张扁平的 `key → 标记` 表；菜单项与 `ActionBtn` 按 key 查表渲染**绝对定位角标**（跟在文案右侧，**不压字**，且[MUST] 不改变宿主尺寸）。

package/src/components/icon/README.md

@@ -0,0 +1,38 @@
+# components/icon — 图标族
+
+core 自带的图标组件族。**只收 element-plus 图标集缺失、且语义上非它不可的那几个**——
+[MUST NOT] 把 EP 已有的图标在这里再画一遍（那是纯重复，且两套观感会打架）。
+
+## 准入判据
+
+新增一个图标前 [MUST] 先答这两问：
+
+1. **EP 图标集里真的没有吗？** 全量清单见 `@element-plus/icons-vue`。有就直接用 EP 的。
+2. **换一个近似的 EP 图标真的不行吗？** 「近似但会被读错」才算不行（如 `Tools` 被读成设置），
+   「不够好看」不算。
+
+## 优先取开源图标集的形，[MUST NOT] 手画
+
+小尺寸图标的辨识度高度依赖剪影，手画的几何形在 12px 下几乎必然糊（实测：手画的轴对齐
+T 形锤被甲方判「太丑」，换成斜置羊角锤即可读）。故 [MUST] 先从成熟开源集（Bootstrap Icons /
+Lucide / Material Symbols 等，许可证需 MIT / ISC / Apache-2.0 一类）取被大量验证过的形，
+**只抄单条 path、[MUST NOT] 引整包依赖**（我们一次只要一个图标）。
+
+[MUST] 在组件注释里写明**来源 + 许可证 + 版权行**。风格上优先取 **fill 实心**版本——
+EP 图标是实心的，描边版（如 Lucide）在 12px 下偏细、与 EP 混排会打架。
+
+## 写作约定
+
+- **颜色 [MUST] 用 `fill="currentColor"`**：继承父级 `color`，天然随主题风格 / 亮暗 / 语义色档走。
+  [MUST NOT] 写死色值、[MUST NOT] 自造 CSS 变量（规则 14）。
+- **尺寸 [MUST] 用 `width/height="1em"`**：外面套 `ElIcon` 调 `font-size` 即可缩放，
+  [MUST NOT] 写死 px。`viewBox` **随图标源**，不强求与 EP 的 1024 一致——渲染尺寸由 1em 决定，
+  换算坐标只会徒增手抄出错的风险。
+- **根元素 [MUST] 带 `dc-<组件名-kebab>` 类**（规则 17），与内部裸类并存。
+- `aria-hidden="true"` + `focusable="false"`：图标是装饰，语义由宿主（或悬浮气泡）承担。
+
+## 清单
+
+| 组件 | 用途 | 为什么不用 EP 的 |
+|---|---|---|
+| `IconHammer` | 施工 / 开发中（`bridge.badge` 的 `wip` 档） | EP 无锤子；最接近的 `Tools` 是扳手+齿轮，被读成「设置」。取自 Bootstrap Icons `hammer`（MIT） |

package/types/bridge/badge.d.ts

@@ -50,6 +50,28 @@ export type BadgeEntry = {
      * @example "批量导出订单为 Excel。适合按月对账；单次超 10 万行会超时，内测期不建议用于生产对账。"
      */
     description?: string;
+    /**
+     * 被遮挡的标被触发时的回调（点宿主 / 点角标都算触发）。
+     *
+     * **[MUST] 只有 `wip` / `locked` 两档会调用它**——只有这两档会遮挡宿主交互，
+     * 其余 kind 是纯展示、宿主照常可点，没有"被拦下的那次点击"可供回调。
+     * 字段放在共享段（而非收窄进那两个 kind）是甲方口径：所有 kind 都可配、非必传。
+     *
+     * 缺省时由 core 出默认提示（`locked` →「请联系平台开通功能」/ `wip` →
+     * 「功能正在加紧开发中」）。要改文案就自己配本回调去弹，core [MUST NOT] 再开覆盖字段。
+     */
+    onTrigger?: (entry: BadgeEntry) => void;
+    /**
+     * 业务自定义标识——**core 不消费、纯透传**，供业务方自己按它找东西
+     * （查文档 / 查开通链接 / 埋点归因等）。
+     *
+     * 命名带 `biz` 前缀是刻意的：注册表本身的 map key 已经占了"key"这个词
+     * （菜单侧是路由 path），entry 里再来个裸 `key` 会当场混淆。
+     *
+     * [MUST NOT] 由 core 据它组装 / 注册 `key → 回调` 的映射——core 是基座层不是应用层，
+     * 聚合与数据来源全在 app（同本文件开头的分工）。
+     */
+    bizKey?: string;
 } & ({
     /** 数字角标 */
     kind: "count";
@@ -65,6 +87,10 @@ export type BadgeEntry = {
     kind: "beta";
 } | {
     kind: "wip";
+} | {
+    kind: "deprecated";
+} | {
+    kind: "locked";
 } | {
     /** 自定义标：内置五档不够用时才用 */
     kind: "custom";
@@ -77,7 +103,9 @@ export type BadgeEntry = {
     type?: BadgeProps["type"];
 });
 /** 内置标（非 count / custom）的 kind 联合——文案与语义色由 core 统一定，保证跨 app 一致 */
-export type BadgeBuiltinKind = "new" | "updated" | "beta" | "wip";
+export type BadgeBuiltinKind = "new" | "updated" | "beta" | "wip" | "deprecated" | "locked";
+/** 会遮挡宿主交互的 kind——[MUST] 与 `use-badge-mask` 的判据同源，[MUST NOT] 两处各写一份 */
+export declare const BADGE_MASK_KINDS: readonly ["wip", "locked"];
 /** bridge 徽标 hook 工厂入参 */
 export interface BridgeBadgeInit {
     /** 初始标记表（如随版本发布的静态 NEW 标）；缺省空表 */

package/types/bridge/index.d.ts

@@ -13,6 +13,7 @@ export { createStorageWithNamespace } from './storage';
 export type { CoreThemeEntry, CoreThemeLifecycleContext, CoreThemeLifecycleHooks, CoreConfigDescription, CoreThemeModule, CoreThemeMode, CoreThemeDensity, CoreThemeMotion, ElSize, CoreThemeComponentDefaults, CoreThemePresetLayout, BridgeThemeLayoutState, BridgeThemeLayoutBaseline, BridgeThemeHook, } from './theme';
 export type { CoreLayoutModule, BridgeLayoutHook, BridgeLayoutInit, LayoutCollapsePersistShape, } from './layout';
 export type { BadgeEntry, BadgeMarkMap, BadgeBuiltinKind, CoreBadgeModule, BridgeBadgeHook, BridgeBadgeInit, } from './badge';
+export { BADGE_MASK_KINDS } from './badge';
 /**
  * 认证桥接无状态纯工厂。
  *

package/types/bridge/theme/types.d.ts

@@ -226,6 +226,17 @@ export interface CoreThemeModule {
      * 新代码 [SHOULD] 用 {@link CoreThemeModule.setMode}（支持 `system` 第三态）。
      */
     setDark: (isDark: boolean) => void;
+    /**
+     * 覆盖明暗（**仅内存，不持久化**）：`true`/`false` 压过 {@link CoreThemeModule.setMode}
+     * 的派生结果，**无参调用** `setDarkOverride()` 清除覆盖、回落 mode。
+     *
+     * 场景：应用被宿主以 iframe 嵌入（如 SSO 登录页），明暗须跟随宿主临时接管，但该应用
+     * 独立打开时仍按自己缓存的偏好——故覆盖 [MUST NOT] 触达 storage、[MUST NOT] 改
+     * `themeMode`（用户真实偏好原样保留，明暗切换控件仍显示它）。
+     * 覆盖期间 `themeIsDark` / `themeColors` / `<html>.dark` 全部跟随覆盖值，不存在
+     * 「视觉暗、状态亮」的脱钩。
+     */
+    setDarkOverride: (isDark?: boolean) => void;
     /**
      * 直接设密度档（独立于风格切换；供 UI 偏好 / demo 切换器）。
      * 注：`setStyle` 会按目标 preset 的 density 复位，故风格切换后手设的密度会被覆盖（同 layout 语义）。