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

package/compositions/toast/useToast.ts

@@ -0,0 +1,176 @@
+/**
+ * @description toast 队列 composable — Promise-based 通知系统
+ * @author 阿怪
+ * @date 2026/5/22
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { ref } from 'vue';
+
+/**
+ * Toast 类型
+ */
+export type ToastType = 'success' | 'error' | 'warning' | 'info' | 'loading';
+
+/**
+ * Toast 队列中每一条 toast 的内部结构
+ */
+export interface ToastItem {
+  id: number;
+  type: ToastType;
+  title: string;
+  message?: string;
+  duration: number;
+  createdAt: number;
+}
+
+/**
+ * 创建 toast 时的配置参数
+ */
+export interface ToastShowOptions {
+  type?: ToastType;
+  title: string;
+  message?: string;
+  duration?: number;
+}
+
+/**
+ * promise() 方法的三阶段配置
+ */
+export interface ToastPromiseOptions<T> {
+  loading: string | { title: string; message?: string };
+  success: string | { title: string; message?: string } | ((data: T) => string | { title: string; message?: string });
+  error: string | { title: string; message?: string } | ((err: unknown) => string | { title: string; message?: string });
+}
+
+/** 各类型默认自动关闭时间（毫秒） */
+const DEFAULT_DURATIONS: Record<ToastType, number> = {
+  success: 3000,
+  error: 5000,
+  warning: 4000,
+  info: 3000,
+  loading: 0, // loading never auto-dismiss
+};
+
+/** 最大可见 toast 数量 */
+const MAX_VISIBLE = 3;
+
+let nextId = 0;
+
+/**
+ * Toast 队列 composable
+ * 管理 toast 的增删、自动关闭定时器与 Promise 模式
+ */
+export function useToast() {
+  const toasts = ref<ToastItem[]>([]);
+  const timers = new Map<number, ReturnType<typeof setTimeout>>();
+
+  /**
+   * 展示一条 toast，返回 id
+   */
+  const show = (options: ToastShowOptions): number => {
+    const id = nextId++;
+    const type = options.type ?? 'info';
+    const duration = options.duration ?? DEFAULT_DURATIONS[type];
+
+    const item: ToastItem = {
+      id,
+      type,
+      title: options.title,
+      message: options.message,
+      duration,
+      createdAt: Date.now(),
+    };
+
+    toasts.value.push(item);
+
+    // enforce max visible — remove oldest (non-loading) if exceeding limit
+    while (toasts.value.length > MAX_VISIBLE) {
+      const oldest = toasts.value.find(t => t.type !== 'loading');
+      if (oldest) {
+        dismiss(oldest.id);
+      } else {
+        // all are loading, remove the very first
+        dismiss(toasts.value[0].id);
+      }
+    }
+
+    if (duration > 0) {
+      const timer = setTimeout(() => dismiss(id), duration);
+      timers.set(id, timer);
+    }
+
+    return id;
+  };
+
+  /**
+   * 按 id 移除一条 toast
+   */
+  const dismiss = (id: number): void => {
+    const idx = toasts.value.findIndex(t => t.id === id);
+    if (idx !== -1) {
+      toasts.value.splice(idx, 1);
+    }
+    const timer = timers.get(id);
+    if (timer) {
+      clearTimeout(timer);
+      timers.delete(id);
+    }
+  };
+
+  /**
+   * 将 stage 配置标准化为 { title, message }
+   */
+  function normalizeStage(stage: string | { title: string; message?: string }): { title: string; message?: string } {
+    if (typeof stage === 'string') {
+      return { title: stage };
+    }
+    return stage;
+  }
+
+  /**
+   * Promise toast pattern:
+   *   - 立即展示 loading toast
+   *   - resolve → 替换为 success toast
+   *   - reject → 替换为 error toast
+   */
+  const promise = <T>(
+    p: Promise<T>,
+    options: ToastPromiseOptions<T>,
+  ): Promise<T> => {
+    const loadingStage = normalizeStage(options.loading);
+    const loadingId = show({
+      type: 'loading',
+      title: loadingStage.title,
+      message: loadingStage.message,
+    });
+
+    return p.then(
+      (data) => {
+        dismiss(loadingId);
+        const raw = typeof options.success === 'function' ? options.success(data) : options.success;
+        const successStage = normalizeStage(raw);
+        show({
+          type: 'success',
+          title: successStage.title,
+          message: successStage.message,
+        });
+        return data;
+      },
+      (err: unknown) => {
+        dismiss(loadingId);
+        const raw = typeof options.error === 'function' ? options.error(err) : options.error;
+        const errorStage = normalizeStage(raw);
+        show({
+          type: 'error',
+          title: errorStage.title,
+          message: errorStage.message,
+        });
+        throw err;
+      },
+    );
+  };
+
+  return { toasts, show, dismiss, promise };
+}

package/compositions/tooltip/index.ts

@@ -0,0 +1,9 @@
+/**
+ * @description tooltip compositions barrel export
+ * @author 阿怪
+ * @date 2026/5/22
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+export { useTooltip, type TooltipPlacement, type TooltipPositionData } from './useTooltip';

package/compositions/tooltip/useTooltip.ts

@@ -0,0 +1,10 @@
+/**
+ * @description tooltip composable re-export from component layer
+ * @author 阿怪
+ * @date 2026/5/22
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+export { useTooltip } from '../../components/base/tooltip/useTooltip';
+export type { TooltipPlacement, TooltipPositionData } from '../../components/base/tooltip/useTooltip';

package/dist/components/base/tooltip/index.d.ts

@@ -4,3 +4,4 @@ export declare const TooltipCore: {
     useTooltip: typeof useTooltip;
 };
 export type { TooltipProps } from './props';
+export type { TooltipPlacement, TooltipPositionData } from './useTooltip';

package/dist/components/base/tooltip/useTooltip.d.ts

@@ -1,25 +1,28 @@
+import { Placement } from '../../../compositions/popper/usePopper';
 import { TooltipProps } from './props';
-export type TooltipStyle = {
-    position: string;
-    left: string;
-    top: string;
-    zIndex: string;
+export type TooltipPlacement = Placement;
+export type TooltipPositionData = {
+    style: Record<string, string>;
+    arrowStyle: Record<string, string>;
+    placement: Placement;
 };
 export declare function useTooltip(props: Required<TooltipProps>): {
     visible: import('vue').Ref<boolean, boolean>;
-    tooltipStyle: import('vue').Ref<Record<string, never> | {
-        position: string;
-        left: string;
-        top: string;
-        zIndex: string;
-    }, TooltipStyle | Record<string, never> | {
-        position: string;
-        left: string;
-        top: string;
-        zIndex: string;
-    }>;
+    positionData: import('vue').Ref<{
+        style: Record<string, string>;
+        arrowStyle: Record<string, string>;
+        placement: Placement;
+    } | null, TooltipPositionData | {
+        style: Record<string, string>;
+        arrowStyle: Record<string, string>;
+        placement: Placement;
+    } | null>;
     triggerRef: import('vue').Ref<HTMLElement | null, HTMLElement | null>;
     tooltipRef: import('vue').Ref<HTMLElement | null, HTMLElement | null>;
-    show: () => Promise<void>;
+    arrowRef: import('vue').Ref<HTMLElement | null, HTMLElement | null>;
+    tooltipId: string;
+    show: () => void;
     hide: () => void;
+    hideImmediate: () => void;
+    initPopper: () => void;
 };

package/dist/compositions/commandPalette/index.d.ts

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

package/dist/compositions/commandPalette/types.d.ts

@@ -0,0 +1,20 @@
+import { VNode } from 'vue';
+/**
+ * A single command registered in the palette.
+ */
+export interface Command {
+    /** Unique identifier */
+    id: string;
+    /** Display label (also used for search) */
+    label: string;
+    /** Optional icon render function */
+    icon?: () => VNode;
+    /** Additional search terms beyond the label */
+    keywords?: string[];
+    /** Grouping category (e.g. "Navigation", "Actions") */
+    group?: string;
+    /** Shortcut hint text displayed on the right side of the item */
+    shortcut?: string;
+    /** Callback executed when the command is selected */
+    action: () => void;
+}

package/dist/compositions/commandPalette/useCommandPalette.d.ts

@@ -0,0 +1,32 @@
+import { Ref, ComputedRef } from 'vue';
+import { 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 declare function useCommandPalette(): UseCommandPaletteReturn;

package/dist/compositions/contextMenu/index.d.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/dist/compositions/contextMenu/types.d.ts

@@ -0,0 +1,12 @@
+import { 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/dist/compositions/contextMenu/useContextMenu.d.ts

@@ -0,0 +1,52 @@
+import { MenuItem } from './types';
+export declare function useContextMenu(): {
+    isOpen: import('vue').Ref<boolean, boolean>;
+    position: import('vue').Ref<{
+        x: number;
+        y: number;
+    }, {
+        x: number;
+        y: number;
+    } | {
+        x: number;
+        y: number;
+    }>;
+    items: import('vue').Ref<{
+        key: string;
+        label: string;
+        icon?: (() => import('vue').VNode) | undefined;
+        action: () => void;
+        visible?: boolean | undefined;
+        disabled?: boolean | undefined;
+        danger?: boolean | undefined;
+        children?: /*elided*/ any[] | undefined;
+        separator?: boolean | undefined;
+    }[], MenuItem[] | {
+        key: string;
+        label: string;
+        icon?: (() => import('vue').VNode) | undefined;
+        action: () => void;
+        visible?: boolean | undefined;
+        disabled?: boolean | undefined;
+        danger?: boolean | undefined;
+        children?: /*elided*/ any[] | undefined;
+        separator?: boolean | undefined;
+    }[]>;
+    activeIndex: import('vue').Ref<number, number>;
+    visibleItems: import('vue').ComputedRef<{
+        key: string;
+        label: string;
+        icon?: (() => import('vue').VNode) | undefined;
+        action: () => void;
+        visible?: boolean | undefined;
+        disabled?: boolean | undefined;
+        danger?: boolean | undefined;
+        children?: /*elided*/ any[] | undefined;
+        separator?: boolean | undefined;
+    }[]>;
+    open: (event: MouseEvent, menuItems: MenuItem[]) => void;
+    close: () => void;
+    moveUp: () => void;
+    moveDown: () => void;
+    executeCurrent: () => void;
+};

package/dist/compositions/editor/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @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/dist/compositions/editor/types.d.ts

@@ -0,0 +1,132 @@
+import { Editor } from '@tiptap/core';
+import { 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/dist/compositions/editor/useEditor.d.ts

@@ -0,0 +1,13 @@
+import { UseEditorOptions, EditorToolbarActions, EditorActiveState } from './types';
+export declare function useEditor(options?: UseEditorOptions): {
+    editor: import('vue').ShallowRef<import('@tiptap/vue-3').Editor | undefined, import('@tiptap/vue-3').Editor | undefined>;
+    isReady: import('vue').Ref<boolean, boolean>;
+    actions: import('vue').ComputedRef<EditorToolbarActions | null>;
+    activeState: import('vue').ComputedRef<EditorActiveState>;
+    setContent: (html: string) => void;
+    setEditable: (editable: boolean) => void;
+    getHTML: () => string;
+    getText: () => string;
+    canUndo: import('vue').ComputedRef<boolean>;
+    canRedo: import('vue').ComputedRef<boolean>;
+};

package/dist/compositions/index.d.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/dist/compositions/overlay/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @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';