@kine-design/core 0.0.1-beta.1 → 0.0.1-beta.10

package/compositions/common/useResizeObserver.ts

@@ -0,0 +1,47 @@
+/**
+ * @description resizeObserver hook
+ * @author 阿怪
+ * @date 2023/6/24 16:08
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ *
+ * Learn from vueuse useResizeObserver
+ */
+
+import { onBeforeUnmount, Ref, watch } from 'vue';
+
+export function useResizeObserver(
+  target: Ref<HTMLElement | null>,
+  callback: ResizeObserverCallback,
+  options: ResizeObserverOptions = {},
+) {
+
+  let observer: ResizeObserver | undefined;
+
+  const cleanup = () => {
+    if (observer) {
+      observer.disconnect();
+      observer = undefined;
+    }
+  };
+
+  // vueuse used watch
+  const stopWatch = watch(target, () => {
+    if (target.value) {
+      cleanup();
+      observer = new ResizeObserver(callback);
+      observer.observe(target.value, options);
+    }
+  });
+
+  onBeforeUnmount(() => {
+    cleanup();
+    stopWatch();
+  });
+
+  return {
+    cleanup,
+  };
+
+}

package/compositions/common/useTeleport.ts

@@ -0,0 +1,24 @@
+/**
+ * @description teleport hook
+ * @author 阿怪
+ * @date 2023/5/5 10:40
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { h, Teleport, TeleportProps, VNode } from 'vue';
+import { MTeleportProps } from '../../types/common/common';
+
+export default function useTeleport(options: {
+  teleportProps?: MTeleportProps | true,
+  slot: VNode | VNode[]
+}) {
+  return h(Teleport, initTeleportOptions(options.teleportProps as TeleportProps), options.slot);
+}
+
+export const initTeleportOptions = (options: TeleportProps | true | undefined) => {
+  if (options === true || options === undefined) {
+    return { to: 'body' };
+  }
+  return options;
+};

package/compositions/contextMenu/index.ts

@@ -0,0 +1,10 @@
+/**
+ * @description context menu composables barrel export
+ * @author kine-design
+ * @date 2026/5/22
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+export { useContextMenu } from './useContextMenu';
+export type { MenuItem } from './types';

package/compositions/contextMenu/types.ts

@@ -0,0 +1,21 @@
+/**
+ * @description context menu types
+ * @author kine-design
+ * @date 2026/5/22
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import type { VNode } from 'vue';
+
+export interface MenuItem {
+  key: string;
+  label: string;
+  icon?: () => VNode;
+  action: () => void;
+  visible?: boolean;
+  disabled?: boolean;
+  danger?: boolean;
+  children?: MenuItem[];
+  separator?: boolean;
+}

package/compositions/contextMenu/useContextMenu.ts

@@ -0,0 +1,101 @@
+/**
+ * @description context menu composable — manages open/close state, positioning, and keyboard navigation
+ * @author kine-design
+ * @date 2026/5/22
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { ref, computed } from 'vue';
+import type { MenuItem } from './types';
+
+export function useContextMenu() {
+  const isOpen = ref(false);
+  const position = ref({ x: 0, y: 0 });
+  const items = ref<MenuItem[]>([]);
+  const activeIndex = ref(-1);
+
+  const visibleItems = computed(() =>
+    items.value.filter(item => item.visible !== false),
+  );
+
+  const open = (event: MouseEvent, menuItems: MenuItem[]) => {
+    event.preventDefault();
+    event.stopPropagation();
+
+    items.value = menuItems;
+    activeIndex.value = -1;
+
+    // Calculate position with viewport edge flipping
+    const x = event.clientX;
+    const y = event.clientY;
+
+    position.value = { x, y };
+    isOpen.value = true;
+  };
+
+  const close = () => {
+    isOpen.value = false;
+    activeIndex.value = -1;
+  };
+
+  const moveUp = () => {
+    const visible = visibleItems.value;
+    if (visible.length === 0) return;
+
+    let next = activeIndex.value - 1;
+    // Skip separators
+    while (next >= 0 && visible[next]?.separator) {
+      next--;
+    }
+    if (next < 0) {
+      // Wrap to last non-separator item
+      next = visible.length - 1;
+      while (next >= 0 && visible[next]?.separator) {
+        next--;
+      }
+    }
+    activeIndex.value = next;
+  };
+
+  const moveDown = () => {
+    const visible = visibleItems.value;
+    if (visible.length === 0) return;
+
+    let next = activeIndex.value + 1;
+    // Skip separators
+    while (next < visible.length && visible[next]?.separator) {
+      next++;
+    }
+    if (next >= visible.length) {
+      // Wrap to first non-separator item
+      next = 0;
+      while (next < visible.length && visible[next]?.separator) {
+        next++;
+      }
+    }
+    activeIndex.value = next;
+  };
+
+  const executeCurrent = () => {
+    const visible = visibleItems.value;
+    const item = visible[activeIndex.value];
+    if (item && !item.disabled && !item.separator) {
+      item.action();
+      close();
+    }
+  };
+
+  return {
+    isOpen,
+    position,
+    items,
+    activeIndex,
+    visibleItems,
+    open,
+    close,
+    moveUp,
+    moveDown,
+    executeCurrent,
+  };
+}

package/compositions/editor/index.ts

@@ -0,0 +1,18 @@
+/**
+ * @description Editor composition barrel export
+ * @author kine-design
+ * @date 2026/5/22
+ * @version v1.0.0
+ *
+ * Headless editor composable — provides logic, no rendering.
+ */
+export { useEditor } from './useEditor';
+export type {
+  UseEditorOptions,
+  EditorConfig,
+  EditorToolbarConfig,
+  EditorExtensionConfig,
+  EditorToolbarActions,
+  EditorActiveState,
+  UseEditorReturn,
+} from './types';

package/compositions/editor/types.ts

@@ -0,0 +1,147 @@
+/**
+ * @description Editor composition types
+ * @author kine-design
+ * @date 2026/5/22
+ * @version v1.0.0
+ *
+ * Type definitions for the rich text editor composable.
+ */
+import type { Editor } from '@tiptap/core';
+import type { ShallowRef, Ref, ComputedRef } from 'vue';
+
+/**
+ * Toolbar feature toggle. Each key controls visibility of a toolbar group.
+ * All default to true when omitted.
+ */
+export interface EditorToolbarConfig {
+  bold?: boolean;
+  italic?: boolean;
+  strike?: boolean;
+  code?: boolean;
+  heading?: boolean;
+  bulletList?: boolean;
+  orderedList?: boolean;
+  blockquote?: boolean;
+  codeBlock?: boolean;
+  link?: boolean;
+  image?: boolean;
+  textAlign?: boolean;
+  undo?: boolean;
+}
+
+/**
+ * Extension-level configuration that is forwarded to individual tiptap extensions.
+ */
+export interface EditorExtensionConfig {
+  link?: {
+    openOnClick?: boolean;
+    HTMLAttributes?: Record<string, string>;
+  };
+  image?: {
+    allowBase64?: boolean;
+    HTMLAttributes?: Record<string, string>;
+  };
+  placeholder?: {
+    text?: string;
+  };
+}
+
+/**
+ * Top-level editor configuration passed via props.
+ */
+export interface EditorConfig {
+  toolbar?: EditorToolbarConfig;
+  extensions?: EditorExtensionConfig;
+}
+
+/**
+ * Options accepted by the useEditor composable.
+ */
+export interface UseEditorOptions {
+  /** Initial HTML or plain-text content */
+  content?: string;
+  /** When true the editor is not editable */
+  readonly?: boolean;
+  /** Placeholder text shown when the editor is empty */
+  placeholder?: string;
+  /** Feature configuration */
+  config?: EditorConfig;
+  /** Callback fired when content changes (HTML string) */
+  onUpdate?: (html: string) => void;
+  /** Callback fired when the editor is ready */
+  onReady?: () => void;
+  /** Callback fired on focus */
+  onFocus?: () => void;
+  /** Callback fired on blur */
+  onBlur?: () => void;
+}
+
+/**
+ * Toolbar action functions returned by the composable.
+ */
+export interface EditorToolbarActions {
+  toggleBold: () => void;
+  toggleItalic: () => void;
+  toggleStrike: () => void;
+  toggleCode: () => void;
+  setParagraph: () => void;
+  setHeading: (level: 1 | 2 | 3) => void;
+  toggleBulletList: () => void;
+  toggleOrderedList: () => void;
+  toggleBlockquote: () => void;
+  toggleCodeBlock: () => void;
+  setLink: (href: string) => void;
+  unsetLink: () => void;
+  setImage: (src: string, alt?: string) => void;
+  setTextAlign: (alignment: 'left' | 'center' | 'right') => void;
+  undo: () => void;
+  redo: () => void;
+  focus: () => void;
+  blur: () => void;
+  clear: () => void;
+}
+
+/**
+ * Active-state flags for toolbar highlighting.
+ */
+export interface EditorActiveState {
+  bold: boolean;
+  italic: boolean;
+  strike: boolean;
+  code: boolean;
+  paragraph: boolean;
+  heading1: boolean;
+  heading2: boolean;
+  heading3: boolean;
+  bulletList: boolean;
+  orderedList: boolean;
+  blockquote: boolean;
+  codeBlock: boolean;
+  link: boolean;
+}
+
+/**
+ * Return type of the useEditor composable.
+ */
+export interface UseEditorReturn {
+  /** The raw tiptap Editor instance (may be null before creation) */
+  editor: ShallowRef<Editor | undefined>;
+  /** Whether the editor has been created and is ready */
+  isReady: Ref<boolean>;
+  /** Toolbar action methods */
+  actions: ComputedRef<EditorToolbarActions | null>;
+  /** Active formatting state */
+  activeState: ComputedRef<EditorActiveState>;
+  /** Update editor content programmatically */
+  setContent: (html: string) => void;
+  /** Toggle the editable state */
+  setEditable: (editable: boolean) => void;
+  /** Get current content as HTML */
+  getHTML: () => string;
+  /** Get current content as plain text */
+  getText: () => string;
+  /** Whether undo is available */
+  canUndo: ComputedRef<boolean>;
+  /** Whether redo is available */
+  canRedo: ComputedRef<boolean>;
+}

package/compositions/editor/useEditor.ts

@@ -0,0 +1,224 @@
+/**
+ * @description Headless editor composable built on tiptap
+ * @author kine-design
+ * @date 2026/5/22
+ * @version v1.0.0
+ *
+ * Provides editor state, toolbar actions, and active-state tracking
+ * without any rendering — the UI layer consumes this composable.
+ */
+import { ref, computed, onBeforeUnmount } from 'vue';
+import { useEditor as useTiptapEditor } from '@tiptap/vue-3';
+import StarterKit from '@tiptap/starter-kit';
+import Link from '@tiptap/extension-link';
+import Image from '@tiptap/extension-image';
+import Placeholder from '@tiptap/extension-placeholder';
+import TextAlign from '@tiptap/extension-text-align';
+import CodeBlockLowlight from '@tiptap/extension-code-block-lowlight';
+import { common, createLowlight } from 'lowlight';
+import type { UseEditorOptions, EditorToolbarActions, EditorActiveState } from './types';
+
+const lowlight = createLowlight(common);
+
+export function useEditor(options: UseEditorOptions = {}) {
+  const {
+    content = '',
+    readonly = false,
+    placeholder = 'Start typing...',
+    config = {},
+    onUpdate,
+    onReady,
+    onFocus,
+    onBlur,
+  } = options;
+
+  const isReady = ref(false);
+
+  // Build extension array based on config
+  const buildExtensions = () => {
+    const toolbar = config.toolbar ?? {};
+    const ext = config.extensions ?? {};
+
+    const extensions = [
+      StarterKit.configure({
+        heading: toolbar.heading !== false ? { levels: [1, 2, 3] } : false,
+        bold: toolbar.bold !== false ? {} : false,
+        italic: toolbar.italic !== false ? {} : false,
+        strike: toolbar.strike !== false ? {} : false,
+        code: toolbar.code !== false ? {} : false,
+        bulletList: toolbar.bulletList !== false ? {} : false,
+        orderedList: toolbar.orderedList !== false ? {} : false,
+        blockquote: toolbar.blockquote !== false ? {} : false,
+        // Disable the built-in code block — we use lowlight instead
+        codeBlock: false,
+      }),
+      Placeholder.configure({
+        placeholder: ext.placeholder?.text ?? placeholder,
+      }),
+    ];
+
+    // Code block with syntax highlighting
+    if (toolbar.codeBlock !== false) {
+      extensions.push(
+        CodeBlockLowlight.configure({
+          lowlight,
+          HTMLAttributes: {
+            class: 'k-editor-code-block',
+          },
+        }),
+      );
+    }
+
+    // Link extension
+    if (toolbar.link !== false) {
+      extensions.push(
+        Link.configure({
+          openOnClick: ext.link?.openOnClick ?? false,
+          HTMLAttributes: {
+            class: 'k-editor-link',
+            ...ext.link?.HTMLAttributes,
+          },
+        }),
+      );
+    }
+
+    // Image extension
+    if (toolbar.image !== false) {
+      extensions.push(
+        Image.configure({
+          inline: true,
+          allowBase64: ext.image?.allowBase64 ?? false,
+          HTMLAttributes: {
+            class: 'k-editor-image',
+            ...ext.image?.HTMLAttributes,
+          },
+        }),
+      );
+    }
+
+    // Text alignment
+    if (toolbar.textAlign !== false) {
+      extensions.push(
+        TextAlign.configure({
+          types: ['heading', 'paragraph'],
+        }),
+      );
+    }
+
+    return extensions;
+  };
+
+  // Create the tiptap editor
+  const editor = useTiptapEditor({
+    content,
+    editable: !readonly,
+    extensions: buildExtensions(),
+    onUpdate: ({ editor: e }) => {
+      onUpdate?.(e.getHTML());
+    },
+    onCreate: () => {
+      isReady.value = true;
+      onReady?.();
+    },
+    onFocus: () => {
+      onFocus?.();
+    },
+    onBlur: () => {
+      onBlur?.();
+    },
+  });
+
+  // Toolbar actions
+  const actions = computed<EditorToolbarActions | null>(() => {
+    const e = editor.value;
+    if (!e) return null;
+
+    return {
+      toggleBold: () => { e.chain().focus().toggleBold().run(); },
+      toggleItalic: () => { e.chain().focus().toggleItalic().run(); },
+      toggleStrike: () => { e.chain().focus().toggleStrike().run(); },
+      toggleCode: () => { e.chain().focus().toggleCode().run(); },
+      setParagraph: () => { e.chain().focus().setParagraph().run(); },
+      setHeading: (level: 1 | 2 | 3) => { e.chain().focus().toggleHeading({ level }).run(); },
+      toggleBulletList: () => { e.chain().focus().toggleBulletList().run(); },
+      toggleOrderedList: () => { e.chain().focus().toggleOrderedList().run(); },
+      toggleBlockquote: () => { e.chain().focus().toggleBlockquote().run(); },
+      toggleCodeBlock: () => { e.chain().focus().toggleCodeBlock().run(); },
+      setLink: (href: string) => { e.chain().focus().setLink({ href }).run(); },
+      unsetLink: () => { e.chain().focus().unsetLink().run(); },
+      setImage: (src: string, alt?: string) => { e.chain().focus().setImage({ src, alt }).run(); },
+      setTextAlign: (alignment: 'left' | 'center' | 'right') => {
+        e.chain().focus().setTextAlign(alignment).run();
+      },
+      undo: () => { e.chain().focus().undo().run(); },
+      redo: () => { e.chain().focus().redo().run(); },
+      focus: () => { e.chain().focus().run(); },
+      blur: () => { e.commands.blur(); },
+      clear: () => { e.chain().focus().clearContent().run(); },
+    };
+  });
+
+  // Active state tracking
+  const activeState = computed<EditorActiveState>(() => {
+    const e = editor.value;
+    if (!e) {
+      return {
+        bold: false, italic: false, strike: false, code: false,
+        paragraph: false, heading1: false, heading2: false, heading3: false,
+        bulletList: false, orderedList: false, blockquote: false,
+        codeBlock: false, link: false,
+      };
+    }
+    return {
+      bold: e.isActive('bold'),
+      italic: e.isActive('italic'),
+      strike: e.isActive('strike'),
+      code: e.isActive('code'),
+      paragraph: e.isActive('paragraph'),
+      heading1: e.isActive('heading', { level: 1 }),
+      heading2: e.isActive('heading', { level: 2 }),
+      heading3: e.isActive('heading', { level: 3 }),
+      bulletList: e.isActive('bulletList'),
+      orderedList: e.isActive('orderedList'),
+      blockquote: e.isActive('blockquote'),
+      codeBlock: e.isActive('codeBlock'),
+      link: e.isActive('link'),
+    };
+  });
+
+  const canUndo = computed(() => editor.value?.can().undo() ?? false);
+  const canRedo = computed(() => editor.value?.can().redo() ?? false);
+
+  // Content management
+  const setContent = (html: string) => {
+    if (!editor.value) return;
+    const current = editor.value.getHTML();
+    if (current === html) return;
+    editor.value.commands.setContent(html);
+  };
+
+  const setEditable = (editable: boolean) => {
+    editor.value?.setEditable(editable);
+  };
+
+  const getHTML = () => editor.value?.getHTML() ?? '';
+  const getText = () => editor.value?.getText() ?? '';
+
+  // Cleanup
+  onBeforeUnmount(() => {
+    editor.value?.destroy();
+  });
+
+  return {
+    editor,
+    isReady,
+    actions,
+    activeState,
+    setContent,
+    setEditable,
+    getHTML,
+    getText,
+    canUndo,
+    canRedo,
+  };
+}

package/compositions/index.ts

@@ -0,0 +1,15 @@
+/**
+ * @description compositions barrel export
+ * @author kine-design
+ * @date 2026/5/22 00:00
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+export * from './overlay';
+export * from './contextMenu';
+export * from './peekView';
+export * from './commandPalette';
+export * from './tooltip';
+export * from './editor';
+export * from './theme';

package/compositions/input/__tests__/useBooleanInput.test.ts

@@ -0,0 +1,73 @@
+/**
+ * @description initChecked / getNewModelValue 测试
+ * @author 阿怪
+ * @date 2026/3/23
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { describe, expect, it } from 'vitest';
+import { initChecked, getNewModelValue } from '../useBooleanInput';
+
+describe('initChecked', () => {
+  it('checked 为 true 时直接返回 true', () => {
+    expect(initChecked({ checked: true, modelValue: undefined, value: undefined })).toBe(true);
+  });
+
+  it('modelValue 为 boolean 时返回该值', () => {
+    expect(initChecked({ checked: undefined, modelValue: true, value: undefined })).toBe(true);
+    expect(initChecked({ checked: undefined, modelValue: false, value: undefined })).toBe(false);
+  });
+
+  it('modelValue 和 value 相等时返回 true', () => {
+    expect(initChecked({ checked: undefined, modelValue: 'a', value: 'a' })).toBe(true);
+  });
+
+  it('modelValue 和 value 不等时返回 false', () => {
+    expect(initChecked({ checked: undefined, modelValue: 'a', value: 'b' })).toBe(false);
+  });
+
+  it('modelValue 为数组时，检查 value 是否在数组中', () => {
+    expect(initChecked({ checked: undefined, modelValue: ['a', 'b'], value: 'a' })).toBe(true);
+    expect(initChecked({ checked: undefined, modelValue: ['a', 'b'], value: 'c' })).toBe(false);
+  });
+
+  it('所有值为空时返回 false', () => {
+    expect(initChecked({ checked: undefined, modelValue: undefined, value: undefined })).toBe(false);
+    expect(initChecked({ checked: null, modelValue: null, value: null })).toBe(false);
+  });
+});
+
+describe('getNewModelValue', () => {
+  // 有 value 且 modelValue 为数组
+  it('checked=true 且 modelValue 为数组时添加 value', () => {
+    expect(getNewModelValue({ value: 'c', modelValue: ['a', 'b'] }, true)).toEqual(['a', 'b', 'c']);
+  });
+
+  it('checked=false 且 modelValue 为数组时移除 value', () => {
+    expect(getNewModelValue({ value: 'b', modelValue: ['a', 'b'] }, false)).toEqual(['a']);
+  });
+
+  it('不重复添加已存在的 value', () => {
+    expect(getNewModelValue({ value: 'a', modelValue: ['a', 'b'] }, true)).toEqual(['a', 'b']);
+  });
+
+  it('移除不存在的 value 不报错', () => {
+    expect(getNewModelValue({ value: 'c', modelValue: ['a', 'b'] }, false)).toEqual(['a', 'b']);
+  });
+
+  // 有 value 且 modelValue 非数组
+  it('checked=true 返回 value', () => {
+    expect(getNewModelValue({ value: 'a', modelValue: undefined }, true)).toBe('a');
+  });
+
+  it('checked=false 返回 undefined', () => {
+    expect(getNewModelValue({ value: 'a', modelValue: undefined }, false)).toBeUndefined();
+  });
+
+  // 无 value
+  it('无 value 时直接返回 checked 布尔值', () => {
+    expect(getNewModelValue({ value: undefined, modelValue: undefined }, true)).toBe(true);
+    expect(getNewModelValue({ value: undefined, modelValue: undefined }, false)).toBe(false);
+  });
+});