@kine-design/core 0.0.1-beta.6 → 0.0.1-beta.7

package/compositions/common/testAnchor.ts

@@ -0,0 +1,211 @@
+/**
+ * @description Test anchor system: provide/inject keys, types, and kDefineComponent wrapper
+ * @author kine-design
+ * @date 2026/4/28
+ * @version v1.0.0
+ *
+ * Renders business-semantic `data-k` attributes on DOM elements when testAnchor is enabled,
+ * allowing E2E tests to target components by stable identifiers.
+ */
+import {
+  cloneVNode,
+  defineComponent,
+  inject,
+  type ComponentPropsOptions,
+  type EmitsOptions,
+  type InjectionKey,
+  type Ref,
+  type SetupContext,
+  type VNode,
+} from 'vue';
+
+// ---------------------------------------------------------------------------
+// Injection keys
+// ---------------------------------------------------------------------------
+
+/** Global switch provided by KConfigProvider to enable data-k rendering */
+export const K_TEST_ANCHOR_KEY: InjectionKey<Ref<boolean>> = Symbol('k-test-anchor');
+
+/** Field identity provided by KFormItem so child inputs inherit field name */
+export const K_FIELD_KEY: InjectionKey<Ref<string | undefined>> = Symbol('k-field');
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface KAnchorConfig {
+  /** Semantic type: 'field' | 'action' | 'table' | 'col' | 'dialog' | 'drawer' | 'tab' */
+  type: string;
+  /** Which prop to derive the identity from (e.g., 'prop' for KFormItem, 'title' for KDialog) */
+  prop?: string;
+  /** Derive identity from default slot text content (for KButton) */
+  slotText?: boolean;
+}
+
+interface KDefineComponentOptions {
+  name: string;
+  props?: ComponentPropsOptions;
+  emits?: EmitsOptions;
+  kAnchor?: KAnchorConfig;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Extract text content from a VNode tree (for slotText mode).
+ * Walks children recursively, concatenating string segments.
+ */
+function extractSlotText(nodes: VNode[] | undefined): string {
+  if (!nodes) return '';
+  let text = '';
+  for (const node of nodes) {
+    if (typeof node.children === 'string') {
+      text += node.children;
+    } else if (Array.isArray(node.children)) {
+      text += extractSlotText(node.children as VNode[]);
+    }
+  }
+  return text.trim();
+}
+
+/**
+ * Resolve the data-k value for a component instance.
+ * Returns undefined when testAnchor is off or no identity can be derived.
+ */
+function resolveDataK(
+  config: KAnchorConfig,
+  props: Record<string, unknown>,
+  attrs: Record<string, unknown>,
+  fieldFromParent: string | undefined,
+  slotNodes?: VNode[],
+): string | undefined {
+  // Developer override via k-{type} attr (e.g., k-action="approve")
+  const overrideKey = `k-${config.type}`;
+  const override = attrs[overrideKey];
+  if (typeof override === 'string' && override) {
+    return `${config.type}:${override}`;
+  }
+
+  // Derive from prop
+  if (config.prop) {
+    const val = props[config.prop];
+    if (typeof val === 'string' && val) {
+      return `${config.type}:${val}`;
+    }
+  }
+
+  // Derive from slot text (e.g., KButton default slot)
+  if (config.slotText && slotNodes) {
+    const text = extractSlotText(slotNodes);
+    if (text) {
+      return `${config.type}:${text}`;
+    }
+  }
+
+  // Fallback: check props.text (for KButton text prop)
+  if (config.slotText && typeof props.text === 'string' && props.text) {
+    return `${config.type}:${props.text}`;
+  }
+
+  // Inherit from parent KFormItem for input-type components
+  if (config.type === 'field' && !config.prop && fieldFromParent) {
+    return `${config.type}:${fieldFromParent}`;
+  }
+
+  return undefined;
+}
+
+/**
+ * Inject data-k attribute into a VNode.
+ * Uses cloneVNode to avoid mutating the original.
+ */
+function injectDataK(vnode: VNode, dataK: string): VNode {
+  return cloneVNode(vnode, { 'data-k': dataK });
+}
+
+// ---------------------------------------------------------------------------
+// kDefineComponent
+// ---------------------------------------------------------------------------
+
+/**
+ * Wrapper around Vue's defineComponent that automatically injects `data-k`
+ * test anchor attributes when testAnchor is enabled via KConfigProvider.
+ *
+ * Usage:
+ * ```tsx
+ * export default kDefineComponent((_props, ctx) => {
+ *   return () => <div class="k-form-item">...</div>;
+ * }, {
+ *   name: 'KFormItem',
+ *   props: FormCore.formItemProps,
+ *   kAnchor: { type: 'field', prop: 'prop' },
+ * });
+ * ```
+ */
+export function kDefineComponent<P extends Record<string, unknown>>(
+  setup: (props: P, ctx: SetupContext) => () => VNode | VNode[] | null | undefined,
+  options: KDefineComponentOptions,
+) {
+  const { kAnchor, ...defineOptions } = options;
+
+  return defineComponent((rawProps: P, ctx: SetupContext) => {
+    // Call the original setup to get the render function
+    const render = setup(rawProps, ctx);
+
+    // If no kAnchor config, skip entirely
+    if (!kAnchor) {
+      return render;
+    }
+
+    // Read the global testAnchor switch
+    const testAnchor = inject(K_TEST_ANCHOR_KEY, undefined);
+
+    // For field-type components without own prop, inject parent field identity
+    const parentField = (kAnchor.type === 'field' && !kAnchor.prop)
+      ? inject(K_FIELD_KEY, undefined)
+      : undefined;
+
+    return () => {
+      const vnode = render();
+
+      // When testAnchor is off (default), render as-is
+      if (!testAnchor?.value) {
+        return vnode;
+      }
+
+      // Resolve the data-k value
+      const props = rawProps as Record<string, unknown>;
+      const slotNodes = kAnchor.slotText ? (ctx.slots.default?.() ?? undefined) : undefined;
+      const dataK = resolveDataK(
+        kAnchor,
+        props,
+        ctx.attrs,
+        parentField?.value,
+        slotNodes,
+      );
+
+      if (!dataK) {
+        return vnode;
+      }
+
+      // Inject into root vnode
+      if (vnode === null || vnode === undefined) {
+        return vnode;
+      }
+
+      // Handle array of vnodes (Fragment) — inject into first element
+      if (Array.isArray(vnode)) {
+        if (vnode.length === 0) return vnode;
+        const first = vnode[0];
+        if (first && typeof first === 'object') {
+          return [injectDataK(first, dataK), ...vnode.slice(1)];
+        }
+        return vnode;
+      }
+
+      return injectDataK(vnode, dataK);
+    };
+  }, defineOptions as Parameters<typeof defineComponent>[1]);
+}

package/dist/compositions/common/testAnchor.d.ts

@@ -0,0 +1,40 @@
+import { ComponentPropsOptions, EmitsOptions, InjectionKey, Ref, SetupContext, VNode } from 'vue';
+/** Global switch provided by KConfigProvider to enable data-k rendering */
+export declare const K_TEST_ANCHOR_KEY: InjectionKey<Ref<boolean>>;
+/** Field identity provided by KFormItem so child inputs inherit field name */
+export declare const K_FIELD_KEY: InjectionKey<Ref<string | undefined>>;
+export interface KAnchorConfig {
+    /** Semantic type: 'field' | 'action' | 'table' | 'col' | 'dialog' | 'drawer' | 'tab' */
+    type: string;
+    /** Which prop to derive the identity from (e.g., 'prop' for KFormItem, 'title' for KDialog) */
+    prop?: string;
+    /** Derive identity from default slot text content (for KButton) */
+    slotText?: boolean;
+}
+interface KDefineComponentOptions {
+    name: string;
+    props?: ComponentPropsOptions;
+    emits?: EmitsOptions;
+    kAnchor?: KAnchorConfig;
+}
+/**
+ * Wrapper around Vue's defineComponent that automatically injects `data-k`
+ * test anchor attributes when testAnchor is enabled via KConfigProvider.
+ *
+ * Usage:
+ * ```tsx
+ * export default kDefineComponent((_props, ctx) => {
+ *   return () => <div class="k-form-item">...</div>;
+ * }, {
+ *   name: 'KFormItem',
+ *   props: FormCore.formItemProps,
+ *   kAnchor: { type: 'field', prop: 'prop' },
+ * });
+ * ```
+ */
+export declare function kDefineComponent<P extends Record<string, unknown>>(setup: (props: P, ctx: SetupContext) => () => VNode | VNode[] | null | undefined, options: KDefineComponentOptions): import('vue').DefineSetupFnComponent<P, EmitsOptions, {}, P & ({
+    [x: `on${Capitalize<string>}`]: ((...args: never) => any) | undefined;
+} | {
+    [x: `on${Capitalize<string>}`]: ((...args: any[]) => any) | undefined;
+}), import('vue').PublicProps>;
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kine-design/core",
-  "version": "0.0.1-beta.6",
+  "version": "0.0.1-beta.7",
   "description": "",
   "type": "module",
   "main": "./dist/core.js",