@kine-design/core 0.0.1-beta.11 → 0.0.1-beta.13

package/compositions/commandPalette/useCommandPalette.ts

@@ -0,0 +1,135 @@
+/**
+ * @description CommandPalette composable — global search + command execution
+ * @author kine-design
+ * @date 2026/5/22
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ *
+ * Manages open/close state, command registration, query filtering, and execution.
+ * Does NOT participate in overlayStack — fixed z-index 9500.
+ */
+import { ref, computed, type Ref, type ComputedRef } from 'vue';
+import type { Command } from './types';
+
+export interface UseCommandPaletteReturn {
+  /** Whether the palette is open */
+  isOpen: Ref<boolean>;
+  /** Current search query */
+  query: Ref<string>;
+  /** Index of the currently highlighted item */
+  activeIndex: Ref<number>;
+  /** All registered commands */
+  commands: Ref<Command[]>;
+  /** Filtered commands based on query */
+  filtered: ComputedRef<Command[]>;
+  /** Open the palette */
+  open: () => void;
+  /** Close the palette */
+  close: () => void;
+  /** Toggle open/close */
+  toggle: () => void;
+  /** Register a command */
+  registerCommand: (cmd: Command) => void;
+  /** Unregister a command by id */
+  unregisterCommand: (id: string) => void;
+  /** Execute the command at a given index in the filtered list, then close */
+  execute: (index: number) => void;
+}
+
+/**
+ * CommandPalette composable
+ *
+ * Provides reactive state for opening, searching, and executing commands.
+ */
+export function useCommandPalette(): UseCommandPaletteReturn {
+  const isOpen = ref(false);
+  const query = ref('');
+  const activeIndex = ref(0);
+  const commands = ref<Command[]>([]);
+
+  /** element that had focus before the palette opened */
+  let previousActiveElement: Element | null = null;
+
+  const open = () => {
+    previousActiveElement = document.activeElement;
+    isOpen.value = true;
+    query.value = '';
+    activeIndex.value = 0;
+  };
+
+  const close = () => {
+    isOpen.value = false;
+    query.value = '';
+    activeIndex.value = 0;
+    // restore focus to the previously focused element
+    if (previousActiveElement && previousActiveElement instanceof HTMLElement) {
+      previousActiveElement.focus();
+    }
+    previousActiveElement = null;
+  };
+
+  const toggle = () => {
+    if (isOpen.value) {
+      close();
+    } else {
+      open();
+    }
+  };
+
+  const registerCommand = (cmd: Command) => {
+    // prevent duplicates
+    const exists = commands.value.some(c => c.id === cmd.id);
+    if (!exists) {
+      commands.value.push(cmd);
+    }
+  };
+
+  const unregisterCommand = (id: string) => {
+    const idx = commands.value.findIndex(c => c.id === id);
+    if (idx !== -1) {
+      commands.value.splice(idx, 1);
+    }
+  };
+
+  /**
+   * Simple case-insensitive substring match on label + keywords.
+   */
+  const filtered = computed<Command[]>(() => {
+    const q = query.value.trim().toLowerCase();
+    if (!q) {
+      return commands.value;
+    }
+    return commands.value.filter(cmd => {
+      if (cmd.label.toLowerCase().includes(q)) {
+        return true;
+      }
+      if (cmd.keywords) {
+        return cmd.keywords.some(kw => kw.toLowerCase().includes(q));
+      }
+      return false;
+    });
+  });
+
+  const execute = (index: number) => {
+    const cmd = filtered.value[index];
+    if (cmd) {
+      close();
+      cmd.action();
+    }
+  };
+
+  return {
+    isOpen,
+    query,
+    activeIndex,
+    commands,
+    filtered,
+    open,
+    close,
+    toggle,
+    registerCommand,
+    unregisterCommand,
+    execute,
+  };
+}

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/overlay/index.ts

@@ -0,0 +1,14 @@
+/**
+ * @description overlay composables barrel export
+ * @author kine-design
+ * @date 2026/5/22 00:00
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+export {
+  useOverlayStackStore,
+  useOverlayStack,
+  useOverlayItem,
+} from './useOverlayStack';
+export type { OverlayItem, OverlayType } from './useOverlayStack';