@fbkworks/adapter-core 0.2.0 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -29,7 +29,8 @@ createApp(App).use(createBusinessKit({ adapter: elementPlusAdapter, theme: 'ligh
29
29
  ## 契约
30
30
 
31
31
  - `UiAdapter`:`meta` / `capabilities` / `primitives` / `RootProvider` / `theme`
32
- - `UiPrimitives`:Button、Input、Select、Checkbox、Form、FormItem、DataGrid、Pagination、Dialog、Tag、Empty、Spin
32
+ - `UiPrimitives`:Button、Input、Select、Checkbox、DatePicker、Radio、Form、FormItem、DataGrid、Pagination、Dialog、Tag、Spin
33
+ - `Drawer`:**可选**原语。缺了不影响启动校验,只有 `FbkDetailDrawer` 会由 `requirePrimitive` 抛错并指向 `FbkDetailPage`
33
34
  - `Capabilities`:能力声明,业务组件据此降级而不是判断适配器名字
34
35
  - `ADAPTER_API_VERSION`:启动时校验,防止 core 与适配器版本错配
35
36
  - 注入键使用 `Symbol.for('fbk.adapter.context')`,多份 core 副本也不会断
package/dist/index.d.mts CHANGED
@@ -88,10 +88,15 @@ interface FeedbackApi {
88
88
  * 三者都是**必填**,旧适配器缺少它们会在启动时被 assertAdapterCompatible
89
89
  * 拦下,因此属于破坏性变更 —— 版本号必须提升。
90
90
  *
91
- * 版本 3:新增 Drawer 原语(详情抽屉)。它同样是**必填**,旧适配器缺少它会在
92
- * 启动时被 assertAdapterCompatible 拦下,因此属于破坏性变更 —— 版本号必须提升。
93
- * 设为可选的代价更大:可选意味着 FbkDetailDrawer 必须准备降级路径,
94
- * 而每一种降级都是「用户以为能用、实际表现不同」(见设计稿 §二之一)。
91
+ * 版本 3:新增 Drawer 原语(详情抽屉)。
92
+ *
93
+ * Drawer 随后被改为**可选**(见 docs/design/2026-10-28-optional-primitive-layer.md),
94
+ * 版本号**没有**因此提升 —— 把必填改为可选是更宽松的约束:已有的 v3 适配器仍然通过,
95
+ * 之前不被允许的(无 Drawer)现在通过。没有任何适配器因这次改动而失败。
96
+ *
97
+ * 由此确立的判据:
98
+ * 新增原语会破版(旧适配器缺成员 → 启动即失败),减少约束不会。
99
+ * 所以「新增」应走可选层,「移除」不需要动版本号。
95
100
  */
96
101
  declare const ADAPTER_API_VERSION = 3;
97
102
  interface AdapterMeta {
@@ -140,7 +145,6 @@ interface Capabilities {
140
145
  };
141
146
  theme: {
142
147
  darkMode: boolean;
143
- cssVariables: boolean;
144
148
  provider: boolean;
145
149
  };
146
150
  /** 细粒度可选能力,业务组件按 key 探测 */
@@ -177,9 +181,12 @@ interface UiPrimitives {
177
181
  * 抽屉。与 Dialog 分开:它是「从一侧滑出、承载详情内容」的容器,
178
182
  * 不是打断当前操作的模态框。缺了它,详情只能挤进 Dialog 或退回普通页。
179
183
  */
180
- Drawer: Component;
184
+ /**
185
+ * 可选原语。缺了只影响 FbkDetailDrawer,库的其余部分完全正常。
186
+ * 缺失时 FbkDetailDrawer 在 mount 阶段抛错并指向 FbkDetailPage —— 见 requirePrimitive。
187
+ */
188
+ Drawer?: Component;
181
189
  Tag: Component;
182
- Empty: Component;
183
190
  Spin: Component;
184
191
  }
185
192
  interface UiAdapter {
@@ -195,6 +202,13 @@ interface UiAdapter {
195
202
  RootProvider: Component;
196
203
  theme: ThemeBridge;
197
204
  }
205
+ /**
206
+ * 取一个**可选**原语;缺失时抛出带替代方案的错误。
207
+ *
208
+ * 为什么不是降级:降级是「看起来能用、行为不同」,报错是「明确告诉你用不了、并给你出路」。
209
+ * 项目原则是显式失败优于静默降级。
210
+ */
211
+ declare function requirePrimitive<K extends keyof UiPrimitives>(adapter: UiAdapter, key: K, alternative: string): NonNullable<UiPrimitives[K]>;
198
212
  declare function assertAdapterCompatible(adapter: UiAdapter): void;
199
213
 
200
214
  /**
@@ -273,9 +287,6 @@ interface CheckboxEmits {
273
287
  'update:modelValue': [value: boolean];
274
288
  change: [value: boolean];
275
289
  }
276
- interface EmptyProps {
277
- description?: string;
278
- }
279
290
  /**
280
291
  * 日期/时间选择。
281
292
  *
@@ -753,5 +764,5 @@ declare function getCellValue<T>(column: DataGridColumn<T>, row: T): unknown;
753
764
  */
754
765
  declare function renderCell<T>(column: DataGridColumn<T>, row: T, index: number): unknown;
755
766
 
756
- export { ADAPTER_API_VERSION, ADAPTER_CONTEXT, FbkProvider, NOOP_REPORTER, PERMISSION_CONTEXT, THEME_IS_DARK, assertAdapterCompatible, createAdapterContext, createBusinessKit, createPermissionDirective, createReporter, getCellValue, hasPermission, renderCell, safeContext, toErrorEvent, useAdapter, useAdapterCapabilities, useAdapterContext, useFbkTheme, usePermission, useReporter };
757
- export type { AdapterContext, AdapterMeta, BusinessKitOptions, ButtonProps, ButtonVariant, Capabilities, CellRenderContext, CheckboxEmits, CheckboxProps, ConfirmApi, ConfirmOptions, DataGridColumn, DataGridEmits, DataGridPresentation, DataGridProps, DatePickerProps, DatePickerType, DialogProps, DrawerProps, EmptyProps, FbkErrorEvent, FbkErrorSource, FbkReporter, FbkReporterOptions, FbkRule, FbkTelemetryEvent, FbkTelemetryType, FeedbackApi, FormExpose, FormItemProps, FormProps, FormRules, InputProps, MessageApi, MessageOptions, MessageType, PaginationProps, PermissionContext, PermissionResolver, RadioOption, RadioProps, SelectOption, SelectProps, Size, SortOrder, SortState, SpinProps, Status, TagProps, ThemeBridge, ThemeMode, UiAdapter, UiPrimitives };
767
+ export { ADAPTER_API_VERSION, ADAPTER_CONTEXT, FbkProvider, NOOP_REPORTER, PERMISSION_CONTEXT, THEME_IS_DARK, assertAdapterCompatible, createAdapterContext, createBusinessKit, createPermissionDirective, createReporter, getCellValue, hasPermission, renderCell, requirePrimitive, safeContext, toErrorEvent, useAdapter, useAdapterCapabilities, useAdapterContext, useFbkTheme, usePermission, useReporter };
768
+ export type { AdapterContext, AdapterMeta, BusinessKitOptions, ButtonProps, ButtonVariant, Capabilities, CellRenderContext, CheckboxEmits, CheckboxProps, ConfirmApi, ConfirmOptions, DataGridColumn, DataGridEmits, DataGridPresentation, DataGridProps, DatePickerProps, DatePickerType, DialogProps, DrawerProps, FbkErrorEvent, FbkErrorSource, FbkReporter, FbkReporterOptions, FbkRule, FbkTelemetryEvent, FbkTelemetryType, FeedbackApi, FormExpose, FormItemProps, FormProps, FormRules, InputProps, MessageApi, MessageOptions, MessageType, PaginationProps, PermissionContext, PermissionResolver, RadioOption, RadioProps, SelectOption, SelectProps, Size, SortOrder, SortState, SpinProps, Status, TagProps, ThemeBridge, ThemeMode, UiAdapter, UiPrimitives };
package/dist/index.d.ts CHANGED
@@ -88,10 +88,15 @@ interface FeedbackApi {
88
88
  * 三者都是**必填**,旧适配器缺少它们会在启动时被 assertAdapterCompatible
89
89
  * 拦下,因此属于破坏性变更 —— 版本号必须提升。
90
90
  *
91
- * 版本 3:新增 Drawer 原语(详情抽屉)。它同样是**必填**,旧适配器缺少它会在
92
- * 启动时被 assertAdapterCompatible 拦下,因此属于破坏性变更 —— 版本号必须提升。
93
- * 设为可选的代价更大:可选意味着 FbkDetailDrawer 必须准备降级路径,
94
- * 而每一种降级都是「用户以为能用、实际表现不同」(见设计稿 §二之一)。
91
+ * 版本 3:新增 Drawer 原语(详情抽屉)。
92
+ *
93
+ * Drawer 随后被改为**可选**(见 docs/design/2026-10-28-optional-primitive-layer.md),
94
+ * 版本号**没有**因此提升 —— 把必填改为可选是更宽松的约束:已有的 v3 适配器仍然通过,
95
+ * 之前不被允许的(无 Drawer)现在通过。没有任何适配器因这次改动而失败。
96
+ *
97
+ * 由此确立的判据:
98
+ * 新增原语会破版(旧适配器缺成员 → 启动即失败),减少约束不会。
99
+ * 所以「新增」应走可选层,「移除」不需要动版本号。
95
100
  */
96
101
  declare const ADAPTER_API_VERSION = 3;
97
102
  interface AdapterMeta {
@@ -140,7 +145,6 @@ interface Capabilities {
140
145
  };
141
146
  theme: {
142
147
  darkMode: boolean;
143
- cssVariables: boolean;
144
148
  provider: boolean;
145
149
  };
146
150
  /** 细粒度可选能力,业务组件按 key 探测 */
@@ -177,9 +181,12 @@ interface UiPrimitives {
177
181
  * 抽屉。与 Dialog 分开:它是「从一侧滑出、承载详情内容」的容器,
178
182
  * 不是打断当前操作的模态框。缺了它,详情只能挤进 Dialog 或退回普通页。
179
183
  */
180
- Drawer: Component;
184
+ /**
185
+ * 可选原语。缺了只影响 FbkDetailDrawer,库的其余部分完全正常。
186
+ * 缺失时 FbkDetailDrawer 在 mount 阶段抛错并指向 FbkDetailPage —— 见 requirePrimitive。
187
+ */
188
+ Drawer?: Component;
181
189
  Tag: Component;
182
- Empty: Component;
183
190
  Spin: Component;
184
191
  }
185
192
  interface UiAdapter {
@@ -195,6 +202,13 @@ interface UiAdapter {
195
202
  RootProvider: Component;
196
203
  theme: ThemeBridge;
197
204
  }
205
+ /**
206
+ * 取一个**可选**原语;缺失时抛出带替代方案的错误。
207
+ *
208
+ * 为什么不是降级:降级是「看起来能用、行为不同」,报错是「明确告诉你用不了、并给你出路」。
209
+ * 项目原则是显式失败优于静默降级。
210
+ */
211
+ declare function requirePrimitive<K extends keyof UiPrimitives>(adapter: UiAdapter, key: K, alternative: string): NonNullable<UiPrimitives[K]>;
198
212
  declare function assertAdapterCompatible(adapter: UiAdapter): void;
199
213
 
200
214
  /**
@@ -273,9 +287,6 @@ interface CheckboxEmits {
273
287
  'update:modelValue': [value: boolean];
274
288
  change: [value: boolean];
275
289
  }
276
- interface EmptyProps {
277
- description?: string;
278
- }
279
290
  /**
280
291
  * 日期/时间选择。
281
292
  *
@@ -753,5 +764,5 @@ declare function getCellValue<T>(column: DataGridColumn<T>, row: T): unknown;
753
764
  */
754
765
  declare function renderCell<T>(column: DataGridColumn<T>, row: T, index: number): unknown;
755
766
 
756
- export { ADAPTER_API_VERSION, ADAPTER_CONTEXT, FbkProvider, NOOP_REPORTER, PERMISSION_CONTEXT, THEME_IS_DARK, assertAdapterCompatible, createAdapterContext, createBusinessKit, createPermissionDirective, createReporter, getCellValue, hasPermission, renderCell, safeContext, toErrorEvent, useAdapter, useAdapterCapabilities, useAdapterContext, useFbkTheme, usePermission, useReporter };
757
- export type { AdapterContext, AdapterMeta, BusinessKitOptions, ButtonProps, ButtonVariant, Capabilities, CellRenderContext, CheckboxEmits, CheckboxProps, ConfirmApi, ConfirmOptions, DataGridColumn, DataGridEmits, DataGridPresentation, DataGridProps, DatePickerProps, DatePickerType, DialogProps, DrawerProps, EmptyProps, FbkErrorEvent, FbkErrorSource, FbkReporter, FbkReporterOptions, FbkRule, FbkTelemetryEvent, FbkTelemetryType, FeedbackApi, FormExpose, FormItemProps, FormProps, FormRules, InputProps, MessageApi, MessageOptions, MessageType, PaginationProps, PermissionContext, PermissionResolver, RadioOption, RadioProps, SelectOption, SelectProps, Size, SortOrder, SortState, SpinProps, Status, TagProps, ThemeBridge, ThemeMode, UiAdapter, UiPrimitives };
767
+ export { ADAPTER_API_VERSION, ADAPTER_CONTEXT, FbkProvider, NOOP_REPORTER, PERMISSION_CONTEXT, THEME_IS_DARK, assertAdapterCompatible, createAdapterContext, createBusinessKit, createPermissionDirective, createReporter, getCellValue, hasPermission, renderCell, requirePrimitive, safeContext, toErrorEvent, useAdapter, useAdapterCapabilities, useAdapterContext, useFbkTheme, usePermission, useReporter };
768
+ export type { AdapterContext, AdapterMeta, BusinessKitOptions, ButtonProps, ButtonVariant, Capabilities, CellRenderContext, CheckboxEmits, CheckboxProps, ConfirmApi, ConfirmOptions, DataGridColumn, DataGridEmits, DataGridPresentation, DataGridProps, DatePickerProps, DatePickerType, DialogProps, DrawerProps, FbkErrorEvent, FbkErrorSource, FbkReporter, FbkReporterOptions, FbkRule, FbkTelemetryEvent, FbkTelemetryType, FeedbackApi, FormExpose, FormItemProps, FormProps, FormRules, InputProps, MessageApi, MessageOptions, MessageType, PaginationProps, PermissionContext, PermissionResolver, RadioOption, RadioProps, SelectOption, SelectProps, Size, SortOrder, SortState, SpinProps, Status, TagProps, ThemeBridge, ThemeMode, UiAdapter, UiPrimitives };
package/dist/index.mjs CHANGED
@@ -3,6 +3,15 @@ import { warnOnce } from '@fbkworks/shared';
3
3
  import { defaultTokens, toCssText } from '@fbkworks/tokens';
4
4
 
5
5
  const ADAPTER_API_VERSION = 3;
6
+ function requirePrimitive(adapter, key, alternative) {
7
+ const primitive = adapter.primitives?.[key];
8
+ if (!primitive) {
9
+ throw new Error(
10
+ `[fbk] \u9002\u914D\u5668\u300C${adapter.meta?.name ?? "unknown"}\u300D\u6CA1\u6709\u63D0\u4F9B ${String(key)} \u539F\u8BED\uFF0C\u8BE5\u7EC4\u4EF6\u4E0D\u53EF\u7528\u3002` + alternative
11
+ );
12
+ }
13
+ return primitive;
14
+ }
6
15
  function assertAdapterCompatible(adapter) {
7
16
  if (!adapter || typeof adapter !== "object") {
8
17
  throw new Error("[fbk] adapter \u5FC5\u987B\u662F UiAdapter \u5BF9\u8C61\u3002");
@@ -24,9 +33,7 @@ function assertAdapterCompatible(adapter) {
24
33
  "DataGrid",
25
34
  "Pagination",
26
35
  "Dialog",
27
- "Drawer",
28
36
  "Tag",
29
- "Empty",
30
37
  "Spin"
31
38
  ];
32
39
  const missing = required.filter((key) => !adapter.primitives?.[key]);
@@ -441,4 +448,4 @@ function renderCell(column, row, index) {
441
448
  return String(value);
442
449
  }
443
450
 
444
- export { ADAPTER_API_VERSION, ADAPTER_CONTEXT, FbkProvider, NOOP_REPORTER, PERMISSION_CONTEXT, THEME_IS_DARK, assertAdapterCompatible, createAdapterContext, createBusinessKit, createPermissionDirective, createReporter, getCellValue, hasPermission, renderCell, safeContext, toErrorEvent, useAdapter, useAdapterCapabilities, useAdapterContext, useFbkTheme, usePermission, useReporter };
451
+ export { ADAPTER_API_VERSION, ADAPTER_CONTEXT, FbkProvider, NOOP_REPORTER, PERMISSION_CONTEXT, THEME_IS_DARK, assertAdapterCompatible, createAdapterContext, createBusinessKit, createPermissionDirective, createReporter, getCellValue, hasPermission, renderCell, requirePrimitive, safeContext, toErrorEvent, useAdapter, useAdapterCapabilities, useAdapterContext, useFbkTheme, usePermission, useReporter };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@fbkworks/adapter-core",
3
- "version": "0.2.0",
3
+ "version": "0.4.0",
4
4
  "type": "module",
5
5
  "sideEffects": false,
6
6
  "files": [
@@ -17,8 +17,8 @@
17
17
  "./package.json": "./package.json"
18
18
  },
19
19
  "dependencies": {
20
- "@fbkworks/shared": "^0.2.0",
21
- "@fbkworks/tokens": "^0.2.0"
20
+ "@fbkworks/shared": "^0.3.0",
21
+ "@fbkworks/tokens": "^0.3.0"
22
22
  },
23
23
  "peerDependencies": {
24
24
  "vue": "^3.5.0"
@@ -35,15 +35,15 @@
35
35
  "component-library"
36
36
  ],
37
37
  "license": "MIT",
38
- "author": "54356",
39
- "homepage": "https://github.com/54356/frontend-business-kit#readme",
38
+ "author": "socalledPF",
39
+ "homepage": "https://github.com/socalledPF/fbkworks#readme",
40
40
  "repository": {
41
41
  "type": "git",
42
- "url": "git+https://github.com/54356/frontend-business-kit.git",
42
+ "url": "git+https://github.com/socalledPF/fbkworks.git",
43
43
  "directory": "packages/adapter-core"
44
44
  },
45
45
  "bugs": {
46
- "url": "https://github.com/54356/frontend-business-kit/issues"
46
+ "url": "https://github.com/socalledPF/fbkworks/issues"
47
47
  },
48
48
  "engines": {
49
49
  "node": ">=20.11.0"