cdp-material-sdk 0.1.0 → 0.1.2

package/dist/index.js

@@ -1,43 +1,47 @@
-import { C as e, a as t, b as n, c as i, D as o, E, I as T, d as _, L as O, e as N, f as R, N as r, g as A, O as C, h as l, R as S, S as u, i as D, j as d, k as m, l as I, m as P, n as p, o as Y, p as M, q as g, u as c, r as L, v as G, s as v } from "./validateManifest-Cn6KPHou.js";
-import { D as K, a as h, b as x, P as V, r as y, s as F, u as b, c as k, d as z } from "./useFieldRegistry-CwjlA-ja.js";
+import { C as e, a as t, b as n, c as E, D as i, d as T, e as _, f as o, g as O, E as N, F as R, I as A, h as D, L as r, i as I, j as C, N as L, k as l, O as S, l as u, S as d, m as P, n as Y, o as m, p, q as M, r as g, s as c, t as G, u as v, v as K, w as F, x as f, y as x } from "./validateManifest-DspYuz81.js";
+import { D as y, a as h, b, P as k, r as z, s as H, u as J, c as U, d as j } from "./useFieldRegistry-CwjlA-ja.js";
 export {
   e as CATEGORY_LABELS,
   t as COMPONENT_CATEGORY,
   n as COMPONENT_STATE_KEY,
-  i as COMPONENT_TRAIT,
-  o as DYNAMIC_ENUM_KEY,
-  K as DataContainerRuntimeContext,
+  E as COMPONENT_TRAIT,
+  i as DATA_FIELD_ROLE,
+  T as DRILL_ACTION,
+  _ as DRILL_EVENT,
+  o as DRILL_STATE,
+  O as DYNAMIC_ENUM_KEY,
+  y as DataContainerRuntimeContext,
   h as DataScope,
-  x as DataScopeContext,
-  E as ENGINE_EVENT_TYPE,
-  T as INJECT_PATH_ROOT,
-  _ as INJECT_PATH_SLOT_PROPS,
-  O as LOADING_PROP_NAME,
-  N as LOADING_STRATEGY,
-  R as LOADING_WRAPPER_TYPE,
-  r as NOTIFY_ERROR_STRATEGY,
-  A as NOTIFY_TIMING,
-  C as OptionItemSchema,
-  l as OptionsSchema,
-  V as PageContext,
-  S as RemoteOptionConfigSchema,
-  u as SLOT_KEY,
-  D as STANDARD_EVENT_KEYS,
-  d as diagnoseMissingActionImpls,
+  b as DataScopeContext,
+  N as ENGINE_EVENT_TYPE,
+  R as FIELD_ROLE_KEY,
+  A as INJECT_PATH_ROOT,
+  D as INJECT_PATH_SLOT_PROPS,
+  r as LOADING_PROP_NAME,
+  I as LOADING_STRATEGY,
+  C as LOADING_WRAPPER_TYPE,
+  L as NOTIFY_ERROR_STRATEGY,
+  l as NOTIFY_TIMING,
+  S as OptionItemSchema,
+  u as OptionsSchema,
+  k as PageContext,
+  d as SLOT_KEY,
+  P as STANDARD_EVENT_KEYS,
+  Y as diagnoseMissingActionImpls,
   m as diagnoseMissingStateKeys,
-  I as isCustomEventKey,
-  P as isStandardEventKey,
-  p as normalizeAdapterEvents,
-  Y as normalizeManifestEvents,
-  M as printSingleValidationResult,
-  g as printValidationResult,
-  y as resolveDataContainerRuntimeValue,
-  F as shouldUseDataContainerRuntimeFallback,
-  c as useConcurrentLoading,
-  b as useDataContainer,
-  k as useDataContainerApi,
-  L as useDualLoading,
-  z as useFieldRegistry,
-  G as validateManifest,
-  v as validateManifests
+  p as isCustomEventKey,
+  M as isStandardEventKey,
+  g as normalizeAdapterEvents,
+  c as normalizeManifestEvents,
+  G as printSingleValidationResult,
+  v as printValidationResult,
+  z as resolveDataContainerRuntimeValue,
+  H as shouldUseDataContainerRuntimeFallback,
+  K as useConcurrentLoading,
+  J as useDataContainer,
+  U as useDataContainerApi,
+  F as useDualLoading,
+  j as useFieldRegistry,
+  f as validateManifest,
+  x as validateManifests
 };

package/dist/portable.d.ts

@@ -7,6 +7,7 @@ export * from './hooks/useConcurrentLoading';
 export * from './hooks/useDualLoading';
 export * from './protocol/adapter';
 export * from './protocol/common-schemas';
+export * from './protocol/drill';
 export * from './protocol/events';
 export * from './protocol/manifest';
 export * from './protocol/manifest-types';

package/dist/portable.js

@@ -1,33 +1,37 @@
-import { C as e, a as E, b as i, c as n, D as t, E as T, I as _, d as O, L as N, e as o, f as A, N as R, g as S, O as I, h as P, R as Y, S as d, i as l, j as C, k as M, l as m, m as r, n as L, o as g, p, q as G, u, r as D, v, s as K } from "./validateManifest-Cn6KPHou.js";
+import { C as E, a as T, b as _, c as e, D as i, d as n, e as t, f as O, g as N, E as A, F as I, I as R, h as L, L as o, i as S, j as D, N as Y, k as P, O as d, l, S as C, m as M, n as r, o as m, p as G, q as g, r as p, s as u, t as K, u as v, v as c, w as f, x as F, y as V } from "./validateManifest-DspYuz81.js";
 export {
-  e as CATEGORY_LABELS,
-  E as COMPONENT_CATEGORY,
-  i as COMPONENT_STATE_KEY,
-  n as COMPONENT_TRAIT,
-  t as DYNAMIC_ENUM_KEY,
-  T as ENGINE_EVENT_TYPE,
-  _ as INJECT_PATH_ROOT,
-  O as INJECT_PATH_SLOT_PROPS,
-  N as LOADING_PROP_NAME,
-  o as LOADING_STRATEGY,
-  A as LOADING_WRAPPER_TYPE,
-  R as NOTIFY_ERROR_STRATEGY,
-  S as NOTIFY_TIMING,
-  I as OptionItemSchema,
-  P as OptionsSchema,
-  Y as RemoteOptionConfigSchema,
-  d as SLOT_KEY,
-  l as STANDARD_EVENT_KEYS,
-  C as diagnoseMissingActionImpls,
-  M as diagnoseMissingStateKeys,
-  m as isCustomEventKey,
-  r as isStandardEventKey,
-  L as normalizeAdapterEvents,
-  g as normalizeManifestEvents,
-  p as printSingleValidationResult,
-  G as printValidationResult,
-  u as useConcurrentLoading,
-  D as useDualLoading,
-  v as validateManifest,
-  K as validateManifests
+  E as CATEGORY_LABELS,
+  T as COMPONENT_CATEGORY,
+  _ as COMPONENT_STATE_KEY,
+  e as COMPONENT_TRAIT,
+  i as DATA_FIELD_ROLE,
+  n as DRILL_ACTION,
+  t as DRILL_EVENT,
+  O as DRILL_STATE,
+  N as DYNAMIC_ENUM_KEY,
+  A as ENGINE_EVENT_TYPE,
+  I as FIELD_ROLE_KEY,
+  R as INJECT_PATH_ROOT,
+  L as INJECT_PATH_SLOT_PROPS,
+  o as LOADING_PROP_NAME,
+  S as LOADING_STRATEGY,
+  D as LOADING_WRAPPER_TYPE,
+  Y as NOTIFY_ERROR_STRATEGY,
+  P as NOTIFY_TIMING,
+  d as OptionItemSchema,
+  l as OptionsSchema,
+  C as SLOT_KEY,
+  M as STANDARD_EVENT_KEYS,
+  r as diagnoseMissingActionImpls,
+  m as diagnoseMissingStateKeys,
+  G as isCustomEventKey,
+  g as isStandardEventKey,
+  p as normalizeAdapterEvents,
+  u as normalizeManifestEvents,
+  K as printSingleValidationResult,
+  v as printValidationResult,
+  c as useConcurrentLoading,
+  f as useDualLoading,
+  F as validateManifest,
+  V as validateManifests
 };

package/dist/protocol/common-schemas.d.ts

@@ -37,36 +37,5 @@ export declare const OptionsSchema: {
         };
     };
 };
-export declare const RemoteOptionConfigSchema: {
-    readonly type: "object";
-    readonly title: "远程选项配置";
-    readonly properties: {
-        readonly panelCode: {
-            readonly type: "string";
-            readonly title: "面板代码";
-        };
-        readonly fieldName: {
-            readonly type: "string";
-            readonly title: "字段名称";
-        };
-        readonly extraFieldNames: {
-            readonly type: "array";
-            readonly title: "额外字段";
-            readonly description: "额外随每个选项返回的字段名（如 code、status 等），用于自定义显示格式或后续业务取用。";
-            readonly items: {
-                readonly type: "string";
-            };
-        };
-        readonly condition: {
-            readonly type: "object";
-            readonly title: "查询条件";
-            readonly description: "声明式查询条件，支持表达式绑定。";
-            readonly additionalProperties: {
-                readonly type: "string";
-            };
-        };
-    };
-};
 export type OptionItem = FromSchema<typeof OptionItemSchema>;
 export type Options = FromSchema<typeof OptionsSchema>;
-export type RemoteOptionConfig = FromSchema<typeof RemoteOptionConfigSchema>;

package/dist/protocol/drill.d.ts

@@ -0,0 +1,32 @@
+export declare const DRILL_ACTION: {
+    readonly PUSH: "drillPush";
+    readonly POP_TO: "drillPopTo";
+    readonly RESET: "drillReset";
+};
+export declare const DRILL_STATE: {
+    readonly PATH: "drillPath";
+};
+export declare const DRILL_EVENT: {
+    readonly NAVIGATE_REQUEST: "drill:navigateRequest";
+    readonly RESET_REQUEST: "drill:resetRequest";
+};
+export interface DrillFrame {
+    level: string;
+    key: string | number;
+    label: string;
+    record?: unknown;
+}
+export interface DrillNavigateRequest {
+    index: number;
+}
+export interface DrillPushParams {
+    frame: DrillFrame;
+}
+export interface DrillPopToParams {
+    index: number;
+}
+export interface DrillRuntimeProps {
+    drillPath?: readonly DrillFrame[];
+    onDrillNavigateRequest?: (request: DrillNavigateRequest) => void;
+    onDrillResetRequest?: () => void;
+}

package/dist/protocol/manifest.d.ts

@@ -8,6 +8,14 @@ export declare const SLOT_KEY = "x-slot";
 export declare const INJECT_PATH_ROOT = "$root";
 /** useImperativeHandle 中用于暴露组件运行时状态的保留 key */
 export declare const COMPONENT_STATE_KEY: "__state";
+export declare const FIELD_ROLE_KEY = "x-fieldRole";
+export declare const DATA_FIELD_ROLE: {
+    readonly ATTRIBUTE: "attribute";
+    readonly DIMENSION: "dimension";
+    readonly MEASURE: "measure";
+};
+export type DataFieldRole = typeof DATA_FIELD_ROLE[keyof typeof DATA_FIELD_ROLE];
+export type DataSourceFieldRoleFilter = typeof DATA_FIELD_ROLE.DIMENSION | typeof DATA_FIELD_ROLE.MEASURE;
 export interface DynamicEnumConfig {
     source: string;
     valueKey: string;
@@ -22,6 +30,7 @@ export interface ExtendedJSONSchema7 extends JSONSchema7 {
         label: string;
     }>;
     placeholder?: string;
+    [FIELD_ROLE_KEY]?: DataSourceFieldRoleFilter;
 }
 export interface StandardEventDeclaration {
     title?: string;

package/dist/protocol/traits.d.ts

@@ -3,5 +3,6 @@ export declare const COMPONENT_TRAIT: {
     readonly DATA_CONTAINER: "Data.Container";
     readonly LAYOUT_CONTAINER: "Layout.Container";
     readonly INTERACTION_CLICKABLE: "Interaction.Clickable";
+    readonly INTERACTION_DRILLABLE: "Interaction.Drillable";
 };
 export type ComponentTrait = typeof COMPONENT_TRAIT[keyof typeof COMPONENT_TRAIT];

package/dist/{validateManifest-Cn6KPHou.js → validateManifest-DspYuz81.js}

@@ -1,24 +1,24 @@
-import { useState as m, useRef as A, useEffect as h, useCallback as u, useMemo as g } from "react";
-const O = () => {
-  const [t, e] = m(0), [o, n] = m(void 0), c = A(0);
-  h(() => {
+import { useState as T, useRef as g, useEffect as L, useCallback as u, useMemo as m } from "react";
+const S = () => {
+  const [t, e] = T(0), [o, n] = T(void 0), c = g(0);
+  L(() => {
     c.current = t;
   }, [t]);
-  const a = u(() => c.current > 0, []), s = u((l) => (e((y) => y + 1), l && n(l), a()), [a]), p = u(() => (e((l) => {
-    const y = Math.max(0, l - 1);
-    return y === 0 && n(void 0), y;
+  const a = u(() => c.current > 0, []), s = u((p) => (e((E) => E + 1), p && n(p), a()), [a]), l = u(() => (e((p) => {
+    const E = Math.max(0, p - 1);
+    return E === 0 && n(void 0), E;
   }), a()), [a]), r = u(() => {
     e(0), n(void 0);
   }, []);
-  return g(() => ({
+  return m(() => ({
     isLoading: t > 0,
     loadingText: o,
     startLoading: s,
-    stopLoading: p,
+    stopLoading: l,
     getLoading: a,
     resetLoading: r
-  }), [a, t, o, r, s, p]);
-}, x = () => {
+  }), [a, t, o, r, s, l]);
+}, V = () => {
   const {
     isLoading: t,
     loadingText: e,
@@ -26,10 +26,10 @@ const O = () => {
     stopLoading: n,
     getLoading: c,
     resetLoading: a
-  } = O(), [s, p] = m(!1), r = g(() => t || s, [t, s]), l = A(!1);
-  return h(() => {
-    l.current = r;
-  }, [r]), g(() => ({
+  } = S(), [s, l] = T(!1), r = m(() => t || s, [t, s]), p = g(!1);
+  return L(() => {
+    p.current = r;
+  }, [r]), m(() => ({
     actionLoading: t,
     actionLoadingText: e,
     startActionLoading: o,
@@ -37,9 +37,9 @@ const O = () => {
     getActionLoading: c,
     resetActionLoading: a,
     dataLoading: s,
-    setDataLoading: p,
+    setDataLoading: l,
     isLoading: r,
-    isLoadingRef: l
+    isLoadingRef: p
   }), [
     t,
     e,
@@ -51,7 +51,7 @@ const O = () => {
     n
   ]);
 };
-function S(t) {
+function N(t) {
   if (!t)
     return [];
   const e = [];
@@ -62,7 +62,7 @@ function S(t) {
     });
   return e;
 }
-function _(t) {
+function O(t) {
   if (!t)
     return [];
   const e = [];
@@ -73,8 +73,8 @@ function _(t) {
     });
   return e;
 }
-function v(t) {
-  const e = S(t?.events), o = _(t?.customEvents);
+function I(t) {
+  const e = N(t?.events), o = O(t?.customEvents);
   return {
     standard: e,
     custom: o,
@@ -82,44 +82,34 @@ function v(t) {
     allKeys: [...e.map((n) => n.type), ...o.map((n) => n.type)]
   };
 }
-const $ = {
+const v = {
   type: "object",
   properties: {
     label: { type: "string", title: "显示名称" },
     value: { type: "string", title: "选项值" },
     disabled: { type: "boolean", title: "是否禁用" }
   }
-}, V = {
+}, x = {
   type: "array",
   title: "选项列表",
-  items: $
+  items: v
 }, J = {
-  type: "object",
-  title: "远程选项配置",
-  properties: {
-    panelCode: { type: "string", title: "面板代码" },
-    fieldName: { type: "string", title: "字段名称" },
-    extraFieldNames: {
-      type: "array",
-      title: "额外字段",
-      description: "额外随每个选项返回的字段名（如 code、status 等），用于自定义显示格式或后续业务取用。",
-      items: { type: "string" }
-    },
-    condition: {
-      type: "object",
-      title: "查询条件",
-      description: "声明式查询条件，支持表达式绑定。",
-      additionalProperties: { type: "string" }
-    }
-  }
+  PUSH: "drillPush",
+  POP_TO: "drillPopTo",
+  RESET: "drillReset"
 }, W = {
+  PATH: "drillPath"
+}, q = {
+  NAVIGATE_REQUEST: "drill:navigateRequest",
+  RESET_REQUEST: "drill:resetRequest"
+}, Q = {
   BEFORE: "before",
   AFTER: "after",
   BOTH: "both"
-}, q = {
+}, X = {
   IGNORE: "ignore",
   STOP: "stop"
-}, C = {
+}, R = {
   MOUNT: "mount",
   UNMOUNT: "unmount",
   CLICK: "click",
@@ -132,15 +122,19 @@ const $ = {
   ITEM_LONG_PRESS: "itemLongPress",
   DATA_FETCH: "dataFetch",
   OPTIONS_FETCH: "optionsFetch"
-}, I = Object.values(C), L = new Set(I), P = /^[^:\s]+:[^:\s]+$/;
-function f(t) {
-  return L.has(t);
+}, $ = Object.values(R), h = new Set($), C = /^[^:\s]+:[^:\s]+$/;
+function y(t) {
+  return h.has(t);
 }
-function E(t) {
-  return P.test(t) && !L.has(t);
+function f(t) {
+  return C.test(t) && !h.has(t);
 }
-const Q = "x-dynamic-enum", X = "x-slot", R = "$root", Z = "__state";
-function D(t) {
+const Z = "x-dynamic-enum", tt = "x-slot", D = "$root", et = "__state", nt = "x-fieldRole", ot = {
+  ATTRIBUTE: "attribute",
+  DIMENSION: "dimension",
+  MEASURE: "measure"
+};
+function P(t) {
   if (!t)
     return [];
   const e = [];
@@ -163,7 +157,7 @@ function M(t) {
   return e;
 }
 function w(t) {
-  const e = D(t?.events), o = M(t?.customEvents);
+  const e = P(t?.events), o = M(t?.customEvents);
   return {
     standard: e,
     custom: o,
@@ -171,19 +165,20 @@ function w(t) {
     allKeys: [...e.map((n) => n.type), ...o.map((n) => n.type)]
   };
 }
-const tt = {
+const at = {
   NATIVE: "native",
   WRAPPER: "wrapper",
   NONE: "none"
-}, et = {
+}, st = {
   SPIN: "spin",
   SKELETON: "skeleton",
   WAVE: "wave"
-}, nt = "loading", T = {
+}, rt = "loading", A = {
   DATA_FIELD: "Data.Field",
   DATA_CONTAINER: "Data.Container",
   LAYOUT_CONTAINER: "Layout.Container",
-  INTERACTION_CLICKABLE: "Interaction.Clickable"
+  INTERACTION_CLICKABLE: "Interaction.Clickable",
+  INTERACTION_DRILLABLE: "Interaction.Drillable"
 }, d = {
   GENERAL: "General",
   FLOAT: "Float",
@@ -196,7 +191,7 @@ const tt = {
   PAGE: "Page",
   DEV: "Dev",
   HTML_TEMPLATE: "HtmlTemplate"
-}, ot = {
+}, it = {
   [d.GENERAL]: "通用",
   [d.FLOAT]: "悬浮",
   [d.LAYOUT]: "布局",
@@ -208,17 +203,17 @@ const tt = {
   [d.PAGE]: "页面",
   [d.DEV]: "调试",
   [d.HTML_TEMPLATE]: "HTML 模板"
-}, b = "slotProps.root", Y = [T.DATA_FIELD, T.DATA_CONTAINER], j = [R, b], N = ["string", "number", "boolean", "array", "object", "integer", "null"];
+}, b = "slotProps.root", Y = [A.DATA_FIELD, A.DATA_CONTAINER], K = [D, b], _ = ["string", "number", "boolean", "array", "object", "integer", "null"];
 function i(t, e, o, n, c) {
   t.push({ type: e, field: o, message: n, severity: c });
 }
-function K(t, e, o) {
+function U(t, e, o) {
   const n = t.type;
   if (!t.meta)
     return i(e, n, "meta", "meta 字段是必填的", "error"), !1;
   if (t.meta.title || i(e, n, "meta.title", "title 是必填的", "error"), t.meta.category ? Object.values(d).includes(t.meta.category) || i(e, n, "meta.category", `无效的 category: ${t.meta.category}`, "error") : i(e, n, "meta.category", "category 是必填的", "error"), t.meta.valueSchema) {
     const a = t.meta.valueSchema.type;
-    a && typeof a == "string" && !N.includes(a) && i(e, n, "meta.valueSchema.type", `无效的 valueSchema type: ${a}`, "error");
+    a && typeof a == "string" && !_.includes(a) && i(e, n, "meta.valueSchema.type", `无效的 valueSchema type: ${a}`, "error");
   }
   return t.traits?.some((a) => Y.includes(a)) && !t.meta.valueSchema && i(
     o,
@@ -228,30 +223,30 @@ function K(t, e, o) {
     "warning"
   ), !0;
 }
-function G(t, e, o) {
-  const n = t.type, c = w(t), a = new Set(c.standard.map((p) => p.type)), s = new Set(c.custom.map((p) => p.type));
-  if (c.all.length > 0 && (c.standard.forEach((p, r) => {
-    p.type || i(e, n, `events[${r}].type`, "事件类型不能为空", "error"), p.type && !f(p.type) && i(e, n, `events[${r}].type`, `标准事件类型必须属于 EngineEventProtocol: ${p.type}`, "error");
-  }), c.custom.forEach((p) => {
-    p.type || i(e, n, "customEvents.type", "自定义事件类型不能为空", "error"), p.type && !E(p.type) && i(e, n, `customEvents.${p.type}`, `自定义事件类型必须是 namespaced 形态: ${p.type}`, "error"), p.payloadSchema || i(e, n, `customEvents.${p.type}.payloadSchema`, "自定义事件必须声明 payloadSchema", "error");
+function H(t, e, o) {
+  const n = t.type, c = w(t), a = new Set(c.standard.map((l) => l.type)), s = new Set(c.custom.map((l) => l.type));
+  if (c.all.length > 0 && (c.standard.forEach((l, r) => {
+    l.type || i(e, n, `events[${r}].type`, "事件类型不能为空", "error"), l.type && !y(l.type) && i(e, n, `events[${r}].type`, `标准事件类型必须属于 EngineEventProtocol: ${l.type}`, "error");
+  }), c.custom.forEach((l) => {
+    l.type || i(e, n, "customEvents.type", "自定义事件类型不能为空", "error"), l.type && !f(l.type) && i(e, n, `customEvents.${l.type}`, `自定义事件类型必须是 namespaced 形态: ${l.type}`, "error"), l.payloadSchema || i(e, n, `customEvents.${l.type}.payloadSchema`, "自定义事件必须声明 payloadSchema", "error");
   })), t.adapter) {
-    const p = v(t.adapter);
-    p.standard.forEach((r, l) => {
-      r.type || i(e, n, `adapter.events[${l}].type`, "Adapter 事件类型不能为空", "error"), r.type && !f(r.type) && i(e, n, `adapter.events[${l}].type`, `Adapter 标准事件类型必须属于 EngineEventProtocol: ${r.type}`, "error"), r.type && f(r.type) && !a.has(r.type) && i(e, n, `adapter.events[${l}].type`, `Adapter 标准事件必须先在 manifest.events 中声明: ${r.type}`, "error"), r.propName || i(e, n, `adapter.events[${l}].propName`, "Adapter propName 不能为空", "error");
-    }), p.custom.forEach((r) => {
-      r.type || i(e, n, "adapter.customEvents.type", "Adapter 自定义事件类型不能为空", "error"), r.type && !E(r.type) && i(e, n, `adapter.customEvents.${r.type}`, `Adapter 自定义事件类型必须是 namespaced 形态: ${r.type}`, "error"), r.type && E(r.type) && !s.has(r.type) && i(e, n, `adapter.customEvents.${r.type}`, `Adapter 自定义事件必须先在 manifest.customEvents 中声明: ${r.type}`, "error"), r.propName || i(e, n, `adapter.customEvents.${r.type}.propName`, "Adapter customEvents propName 不能为空", "error");
+    const l = I(t.adapter);
+    l.standard.forEach((r, p) => {
+      r.type || i(e, n, `adapter.events[${p}].type`, "Adapter 事件类型不能为空", "error"), r.type && !y(r.type) && i(e, n, `adapter.events[${p}].type`, `Adapter 标准事件类型必须属于 EngineEventProtocol: ${r.type}`, "error"), r.type && y(r.type) && !a.has(r.type) && i(e, n, `adapter.events[${p}].type`, `Adapter 标准事件必须先在 manifest.events 中声明: ${r.type}`, "error"), r.propName || i(e, n, `adapter.events[${p}].propName`, "Adapter propName 不能为空", "error");
+    }), l.custom.forEach((r) => {
+      r.type || i(e, n, "adapter.customEvents.type", "Adapter 自定义事件类型不能为空", "error"), r.type && !f(r.type) && i(e, n, `adapter.customEvents.${r.type}`, `Adapter 自定义事件类型必须是 namespaced 形态: ${r.type}`, "error"), r.type && f(r.type) && !s.has(r.type) && i(e, n, `adapter.customEvents.${r.type}`, `Adapter 自定义事件必须先在 manifest.customEvents 中声明: ${r.type}`, "error"), r.propName || i(e, n, `adapter.customEvents.${r.type}.propName`, "Adapter customEvents propName 不能为空", "error");
     });
   }
 }
-function H(t, e, o) {
+function F(t, e, o) {
   const n = t.type, c = t.actions;
   if (c)
     for (const [a, s] of Object.entries(c))
       s && (s.title || i(e, n, `actions.${a}.title`, `动作 "${a}" 缺少 title`, "error"), s.returns || i(o, n, `actions.${a}.returns`, `动作 "${a}" 未声明 returns schema，建议补充`, "warning"), s.params && s.params.type !== "object" && i(e, n, `actions.${a}.params.type`, '动作参数 schema 的 type 必须为 "object"', "error"));
 }
-function F(t, e, o) {
+function G(t, e, o) {
   const n = t.type, c = t.engine?.render?.injection?.rootPath;
-  c ? typeof c == "string" && !j.includes(c) && i(
+  c ? typeof c == "string" && !K.includes(c) && i(
     o,
     n,
     "engine.render.injection.rootPath",
@@ -265,7 +260,7 @@ function F(t, e, o) {
     "warning"
   );
 }
-function U(t, e, o) {
+function j(t, e, o) {
   const n = t.type, c = t.slots;
   if (c)
     for (const [a, s] of Object.entries(c))
@@ -281,17 +276,17 @@ function k(t, e, o) {
   const n = t.type, c = t.state;
   if (c)
     for (const [a, s] of Object.entries(c))
-      s && (s.title || i(e, n, `state.${a}.title`, `状态 "${a}" 缺少 title`, "error"), s.schema ? s.schema.type && typeof s.schema.type == "string" && !N.includes(s.schema.type) && i(e, n, `state.${a}.schema.type`, `状态 "${a}" 的 schema.type 无效: ${s.schema.type}`, "error") : i(e, n, `state.${a}.schema`, `状态 "${a}" 缺少 schema`, "error"));
+      s && (s.title || i(e, n, `state.${a}.title`, `状态 "${a}" 缺少 title`, "error"), s.schema ? s.schema.type && typeof s.schema.type == "string" && !_.includes(s.schema.type) && i(e, n, `state.${a}.schema.type`, `状态 "${a}" 的 schema.type 无效: ${s.schema.type}`, "error") : i(e, n, `state.${a}.schema`, `状态 "${a}" 缺少 schema`, "error"));
 }
 function z(t) {
   const e = [], o = [];
-  return t.type || i(e, t.type || "Unknown", "type", "type 字段是必填的", "error"), K(t, e, o) ? (G(t, e), H(t, e, o), k(t, e), U(t, e, o), F(t, e, o), {
+  return t.type || i(e, t.type || "Unknown", "type", "type 字段是必填的", "error"), U(t, e, o) ? (H(t, e), F(t, e, o), k(t, e), j(t, e, o), G(t, e, o), {
     valid: e.length === 0,
     errors: e,
     warnings: o
   }) : { valid: !1, errors: e, warnings: o };
 }
-function at(t) {
+function ct(t) {
   const e = [], o = [];
   for (const n of t) {
     const c = z(n);
@@ -303,13 +298,13 @@ function at(t) {
     warnings: o
   };
 }
-function st(t, e) {
+function lt(t, e) {
   return !t || !e ? [] : t.filter((o) => typeof e[o] != "function");
 }
-function rt(t, e) {
+function pt(t, e) {
   return !t?.state || !e ? [] : Object.keys(t.state).filter((o) => !(o in e));
 }
-function it(t) {
+function dt(t) {
   t.valid ? console.log("✅ 所有 Manifest 验证通过") : console.error(`❌ 发现 ${t.errors.length} 个错误`), t.errors.length > 0 && (console.error(`
 错误列表:`), t.errors.forEach((e) => {
     console.error(`  ❌ [${e.type}] ${e.field}: ${e.message}`);
@@ -318,7 +313,7 @@ function it(t) {
     console.warn(`  ⚠️  [${e.type}] ${e.field}: ${e.message}`);
   }));
 }
-function ct(t, e = "[Registry]") {
+function Et(t, e = "[Registry]") {
   if (!t.valid && t.errors.length > 0) {
     const o = t.errors[0]?.type || "Unknown";
     console.error(`${e} ❌ Manifest validation failed for '${o}':`), t.errors.forEach((n) => console.error(`  - ${n.field}: ${n.message}`));
@@ -329,34 +324,38 @@ function ct(t, e = "[Registry]") {
   }
 }
 export {
-  ot as C,
-  Q as D,
-  C as E,
-  R as I,
-  nt as L,
-  q as N,
-  $ as O,
-  J as R,
-  X as S,
+  it as C,
+  ot as D,
+  R as E,
+  nt as F,
+  D as I,
+  rt as L,
+  X as N,
+  v as O,
+  tt as S,
   d as a,
-  Z as b,
-  T as c,
-  b as d,
-  tt as e,
-  et as f,
-  W as g,
-  V as h,
-  I as i,
+  et as b,
+  A as c,
+  J as d,
+  q as e,
+  W as f,
+  Z as g,
+  b as h,
+  at as i,
   st as j,
-  rt as k,
-  E as l,
-  f as m,
-  v as n,
-  w as o,
-  ct as p,
-  it as q,
-  x as r,
-  at as s,
-  O as u,
-  z as v
+  Q as k,
+  x as l,
+  $ as m,
+  lt as n,
+  pt as o,
+  f as p,
+  y as q,
+  I as r,
+  w as s,
+  Et as t,
+  dt as u,
+  S as v,
+  V as w,
+  z as x,
+  ct as y
 };

package/docs/component-development/README.md

@@ -83,6 +83,13 @@
 - [声明事件](./recipes/声明事件.md)
 - [Events 模型](./reference/Events模型.md)
 
+### 我要让组件支持层级下钻
+
+阅读：
+
+- [声明层级下钻能力](./recipes/声明层级下钻能力.md)
+- [层级下钻能力模型](./reference/层级下钻能力模型.md)
+
 ### 我要让流程或 AI 调用组件方法
 
 阅读：

package/docs/component-development/recipes//345/243/260/346/230/216/345/261/202/347/272/247/344/270/213/351/222/273/350/203/275/345/212/233.md

@@ -0,0 +1,34 @@
+---
+type: recipe
+capability: drill
+related:
+  - reference/层级下钻能力模型.md
+  - recipes/声明事件.md
+  - recipes/声明动作与状态.md
+---
+
+# 声明层级下钻能力
+
+## 适用场景
+
+组件需要展示宿主维护的层级路径，并请求返回历史层或根层时使用。普通详情跳转不属于层级下钻。
+
+## 步骤
+
+1. 在 manifest 的 `traits` 中加入 `COMPONENT_TRAIT.INTERACTION_DRILLABLE`。
+2. 组件接收 `DrillRuntimeProps`，受控渲染 `drillPath`。
+3. 点击历史节点时调用 `onDrillNavigateRequest({ index })`；返回根层时调用 `onDrillResetRequest()`。
+4. 在组件库内共享路径视图，不在每个 Chart、Table 或 CardList 重复实现。
+5. 用 `validateManifest()` 检查 manifest。
+
+不要在组件内保存第二份路径，也不要重复声明 trait 自动提供的 actions、state 和 events。数据查询、参数加工与更新成功后的 `drillPush` / `drillPopTo` / `drillReset` 由宿主事件编排完成。
+
+## 自检
+
+- 空路径不产生额外 DOM 或高度。
+- 路径点击只发请求，不立即修改状态。
+- 查询成功后再调用对应下钻 action。
+
+## 关联文档
+
+- [层级下钻能力模型](../reference/层级下钻能力模型.md)

package/docs/component-development/reference/Traits/350/203/275/345/212/233/346/250/241/345/236/213.md

@@ -24,6 +24,7 @@ Traits 之间不互斥，一个组件可以同时声明多个 trait。例如 For
 | `Data.Container` | `COMPONENT_TRAIT.DATA_CONTAINER` | Form、Table、List、CardList | 组件管理一组数据作用域 |
 | `Layout.Container` | `COMPONENT_TRAIT.LAYOUT_CONTAINER` | 通用容器：Card、Grid、Section；强组合关系：Tabs、Steps、Form（带 `nesting` 类型约束） | 组件具备**默认 children 区域**（与 `manifest.slots` 是两条独立机制） |
 | `Interaction.Clickable` | `COMPONENT_TRAIT.INTERACTION_CLICKABLE` | Button、Link、ClickableCard | 组件具备点击交互语义 |
+| `Interaction.Drillable` | `COMPONENT_TRAIT.INTERACTION_DRILLABLE` | Chart、Table、CardList | 宿主为组件实例提供受控下钻路径、动作和导航请求事件 |
 
 ---
 
@@ -154,6 +155,23 @@ Traits 之间不互斥，一个组件可以同时声明多个 trait。例如 For
 
 ---
 
+## INTERACTION_DRILLABLE
+
+### 什么时候声明
+
+组件能够沿数据层级进入下一层并返回历史层，例如图表维度下钻、表格或卡片列表的下一级记录。
+
+### 作者要做什么
+
+- 声明 `COMPONENT_TRAIT.INTERACTION_DRILLABLE`。
+- 接收宿主注入的 `drillPath`，并以适合自身布局的方式展示路径。
+- 用户选择历史层时调用 `onDrillNavigateRequest({ index })`。
+- 不在组件内部维护第二份路径状态，也不在 manifest 重复声明 trait 自动提供的 props、event、actions 和 state。
+
+完整契约与编排边界见 [层级下钻能力模型](./层级下钻能力模型.md)。
+
+---
+
 ## Traits 与 valueSchema
 
 声明 `DATA_FIELD` 或 `DATA_CONTAINER` 时，建议同时声明 `meta.valueSchema`。
@@ -194,6 +212,7 @@ meta: {
 | `DATA_CONTAINER` | 用于管理子字段数据作用域；必须在子组件渲染区域提供 `DataScope`。与 `LAYOUT_CONTAINER` 不互斥，Form 这类容器应同时声明 |
 | `LAYOUT_CONTAINER` | 控制**默认 children 区域**开关，仅影响 `schema.children` 是否被宿主递归渲染。具名子区域走 `manifest.slots`，与本 trait 互不依赖 |
 | `INTERACTION_CLICKABLE` | 表示具备点击语义；需要编排响应时再声明 click event |
+| `INTERACTION_DRILLABLE` | 表示具备层级下钻语义；宿主维护路径状态，组件只做受控展示与导航请求 |
 
 数据 trait 与 `meta.valueSchema` 的校验级别见 [validateManifest 校验规则](./validateManifest校验规则.md)。
 

package/docs/component-development/reference//345/261/202/347/272/247/344/270/213/351/222/273/350/203/275/345/212/233/346/250/241/345/236/213.md

@@ -0,0 +1,80 @@
+---
+type: reference
+capability: drill
+related:
+  - recipes/声明层级下钻能力.md
+  - reference/Traits能力模型.md
+  - reference/Events模型.md
+  - reference/ActionsState模型.md
+---
+
+# 层级下钻能力模型
+
+`INTERACTION_DRILLABLE` 声明组件能够沿数据层级进入、返回和复位。它只定义跨包契约：宿主维护路径状态并执行编排，组件通过受控 props 展示路径并发出导航请求。当 `drillPath` 为空时表示根层，当前层由末帧派生，不单独保存。
+
+## 组件作者接入
+
+```tsx
+import type { DrillRuntimeProps } from 'cdp-material-sdk/portable';
+import { COMPONENT_TRAIT } from 'cdp-material-sdk/portable';
+
+export const manifest = {
+  // ...
+  traits: [COMPONENT_TRAIT.INTERACTION_DRILLABLE],
+};
+
+export function Chart({
+  drillPath = [],
+  onDrillNavigateRequest,
+  onDrillResetRequest,
+}: DrillRuntimeProps) {
+  return (
+    <DrillPathView
+      items={drillPath}
+      onNavigate={(index) => onDrillNavigateRequest?.({ index })}
+      onReset={() => onDrillResetRequest?.()}
+    />
+  );
+}
+```
+
+组件负责路径 UI 的位置与样式，但不自行保存第二份路径状态。一个组件库内的 Chart、Table、CardList 应复用库内共享的纯展示组件。
+
+## 宿主自动提供的契约
+
+| 类别 | 名称 | 语义 |
+|---|---|---|
+| Prop | `drillPath` | 当前组件实例的受控路径，类型为 `DrillFrame[]` |
+| Prop | `onDrillNavigateRequest` | 用户点击历史路径节点时调用，参数为 `{ index }` |
+| Prop | `onDrillResetRequest` | 用户请求返回根层时调用 |
+| Event | `drill:navigateRequest` | 将返回请求交给事件编排 |
+| Event | `drill:resetRequest` | 将返回根层请求交给事件编排 |
+| Action | `drillPush({ frame })` | 成功取得下一层数据后追加路径 |
+| Action | `drillPopTo({ index })` | 成功取得历史层数据后截断路径 |
+| Action | `drillReset()` | 返回根层 |
+| State | `drillPath` | 供表达式读取的当前路径快照 |
+
+以上字段由 trait 对应的宿主 Feature 自动注入，组件 manifest 不要重复声明 props、event、actions 或 state。
+
+## 编排边界
+
+下钻状态不负责查询。推荐顺序是：
+
+```text
+itemClick
+  → 参数加工 / 条件判断
+  → 查询并更新组件数据
+  → component.invoke(drillPush, { frame })
+```
+
+返回历史层同理：先查询并更新数据，成功后再调用 `drillPopTo`。查询失败时路径保持不变。
+
+## 公共导出
+
+以下内容均从 `cdp-material-sdk/portable` 导入：
+
+- `COMPONENT_TRAIT.INTERACTION_DRILLABLE`
+- `DRILL_ACTION`、`DRILL_STATE`、`DRILL_EVENT`
+- `DrillFrame`、`DrillNavigateRequest`、`DrillPushParams`、`DrillPopToParams`、`DrillRuntimeProps`
+
+SDK 不提供下钻 Hook、HOC 或面包屑 UI；这些分别属于宿主 Feature 和外置 UI 库。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cdp-material-sdk",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "license": "MIT",
   "publishConfig": {
     "access": "public",