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

package/compositions/input/useBooleanInput.ts

@@ -0,0 +1,52 @@
+/**
+ * @description boolean input like checkbox/radio... hooks
+ * @author 阿怪
+ * @date 2023/4/23 15:22
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { isBoolean, notEmpty } from '../../tools';
+
+export const initChecked = (props: {
+  checked: boolean | null | undefined,
+  modelValue: any,
+  value: any
+}) => {
+  if (props.checked) {
+    return props.checked;
+  }
+
+  if (notEmpty(props.modelValue)) {
+    if (notEmpty(props.value)) {
+      if (Array.isArray(props.modelValue)) {
+        return props.modelValue.includes(props.value);
+      }
+      return props.value === props.modelValue;
+    }
+
+    if (isBoolean(props.modelValue)) {
+      return props.modelValue;
+    }
+  }
+
+  return false;
+};
+
+
+export const getNewModelValue = (props: { value: any, modelValue?: any }, checked: boolean) => {
+  if (props.value) {
+    if (Array.isArray(props.modelValue)) {
+      const arr = [...props.modelValue];
+      if (checked) {
+        if (!arr.includes(props.value)) arr.push(props.value);
+      } else {
+        const idx = arr.indexOf(props.value);
+        if (idx !== -1) arr.splice(idx, 1);
+      }
+      return arr;
+    }
+    return checked ? props.value : undefined;
+  }
+  return checked;
+};

package/compositions/modal/__tests__/useModal.test.ts

@@ -0,0 +1,110 @@
+/**
+ * @description useModal 测试
+ * @author 阿怪
+ * @date 2026/3/23
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { describe, expect, it, vi } from 'vitest';
+import { nextTick, reactive } from 'vue';
+import { useModal } from '../useModal';
+
+describe('useModal', () => {
+  it('初始 visible 默认为 false', () => {
+    const emit = vi.fn();
+    const { visible } = useModal({}, emit);
+    expect(visible.value).toBe(false);
+  });
+
+  it('初始 visible 跟随 props', () => {
+    const emit = vi.fn();
+    const { visible } = useModal({ visible: true }, emit);
+    expect(visible.value).toBe(true);
+  });
+
+  it('open 设置 visible 为 true 并触发 emit', () => {
+    const emit = vi.fn();
+    const { visible, open } = useModal({}, emit);
+
+    open();
+    expect(visible.value).toBe(true);
+    expect(emit).toHaveBeenCalledWith('update:visible', true);
+  });
+
+  it('close 设置 visible 为 false 并触发 emit', () => {
+    const emit = vi.fn();
+    const { visible, close } = useModal({ visible: true }, emit);
+
+    close();
+    expect(visible.value).toBe(false);
+    expect(emit).toHaveBeenCalledWith('update:visible', false);
+  });
+
+  it('toggle 切换 visible 状态', () => {
+    const emit = vi.fn();
+    const { visible, toggle } = useModal({}, emit);
+
+    toggle(); // false → true
+    expect(visible.value).toBe(true);
+
+    toggle(); // true → false
+    expect(visible.value).toBe(false);
+  });
+
+  it('onMaskClick 默认关闭', () => {
+    const emit = vi.fn();
+    const { visible, open, onMaskClick } = useModal({}, emit);
+
+    open();
+    onMaskClick();
+    expect(visible.value).toBe(false);
+  });
+
+  it('onMaskClick 当 mask.clickClose=false 时不关闭', () => {
+    const emit = vi.fn();
+    const { visible, open, onMaskClick } = useModal({ mask: { clickClose: false } }, emit);
+
+    open();
+    onMaskClick();
+    expect(visible.value).toBe(true);
+  });
+
+  it('showMask 默认返回 true', () => {
+    const emit = vi.fn();
+    const { showMask } = useModal({}, emit);
+    expect(showMask()).toBe(true);
+  });
+
+  it('showMask 当 mask.show=false 时返回 false', () => {
+    const emit = vi.fn();
+    const { showMask } = useModal({ mask: { show: false } }, emit);
+    expect(showMask()).toBe(false);
+  });
+
+  it('onContentClick 阻止冒泡', () => {
+    const emit = vi.fn();
+    const { onContentClick } = useModal({}, emit);
+    const event = { stopPropagation: vi.fn() } as unknown as MouseEvent;
+
+    onContentClick(event);
+    expect(event.stopPropagation).toHaveBeenCalled();
+  });
+
+  it('外部 props.visible 变化时 watcher 同步内部 visible', async () => {
+    const emit = vi.fn();
+    const props = reactive({ visible: false });
+    const { visible } = useModal(props, emit);
+
+    expect(visible.value).toBe(false);
+
+    // 外部修改 props.visible → watcher 同步 visible.value
+    props.visible = true;
+    await nextTick();
+    expect(visible.value).toBe(true);
+
+    props.visible = false;
+    await nextTick();
+    expect(visible.value).toBe(false);
+  });
+});

package/compositions/modal/useModal.ts

@@ -0,0 +1,72 @@
+/**
+ * @description 模态框公共 composable（dialog / drawer / confirm 共用）
+ * @author 阿怪
+ * @date 2026/2/25 16:00
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ *
+ * 处理 visible 状态、遮罩层点击关闭、emit 同步
+ */
+import { ref, watch } from 'vue';
+import { type HookContext } from '../../components/types/hook';
+import { ModelMask } from '../../types/common/model';
+
+export interface UseModalProps {
+  visible?: boolean;
+  mask?: ModelMask;
+}
+
+export function useModal(props: UseModalProps, emit: HookContext['emit']) {
+  const visible = ref(props.visible ?? false);
+
+  watch(() => props.visible, (val) => {
+    visible.value = val ?? false;
+  });
+
+  /** 打开 */
+  const open = () => {
+    visible.value = true;
+    emit('update:visible', true);
+  };
+
+  /** 关闭 */
+  const close = () => {
+    visible.value = false;
+    emit('update:visible', false);
+  };
+
+  /** 切换 */
+  const toggle = () => {
+    if (visible.value) { close(); } else { open(); }
+  };
+
+  /** 遮罩层点击 */
+  const onMaskClick = () => {
+    const mask = props.mask;
+    const clickClose = mask?.clickClose ?? true;
+    if (clickClose) {
+      close();
+    }
+  };
+
+  /** 是否显示遮罩 */
+  const showMask = () => {
+    return props.mask?.show ?? true;
+  };
+
+  /** 阻止内容区域点击冒泡到遮罩 */
+  const onContentClick = (e: MouseEvent) => {
+    e.stopPropagation();
+  };
+
+  return {
+    visible,
+    open,
+    close,
+    toggle,
+    onMaskClick,
+    showMask,
+    onContentClick,
+  };
+}

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';

package/compositions/overlay/useOverlayStack.ts

@@ -0,0 +1,146 @@
+/**
+ * @description overlay stack manager — unified z-index and ESC handling for all popups
+ * @author kine-design
+ * @date 2026/5/22 00:00
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { defineStore } from 'pinia';
+import { computed, ref, onMounted, onBeforeUnmount } from 'vue';
+
+export type OverlayType = 'popover' | 'alert-dialog' | 'context-menu' | 'command-palette';
+
+export interface OverlayItem {
+  id: string;
+  type: OverlayType;
+  close: () => void;
+  zIndex: number;
+}
+
+const Z_INDEX_BASE = 100;
+
+let idCounter = 0;
+const generateId = (type: OverlayType) => `overlay-${type}-${++idCounter}`;
+
+export const useOverlayStackStore = defineStore('overlayStack', () => {
+  const overlayStack = ref<OverlayItem[]>([]);
+
+  const isEmpty = computed(() => overlayStack.value.length === 0);
+  const topItem = computed(() =>
+    overlayStack.value.length > 0
+      ? overlayStack.value[overlayStack.value.length - 1]
+      : undefined,
+  );
+
+  const push = (item: Omit<OverlayItem, 'zIndex'>) => {
+    const zIndex = overlayStack.value.length + Z_INDEX_BASE;
+    const entry: OverlayItem = { ...item, zIndex };
+    overlayStack.value.push(entry);
+    return entry;
+  };
+
+  const pop = () => {
+    const item = overlayStack.value.pop();
+    if (item) {
+      item.close();
+    }
+    return item;
+  };
+
+  const remove = (id: string) => {
+    const index = overlayStack.value.findIndex(item => item.id === id);
+    if (index !== -1) {
+      overlayStack.value.splice(index, 1);
+      recalculateZIndices();
+    }
+  };
+
+  const recalculateZIndices = () => {
+    overlayStack.value.forEach((item, index) => {
+      item.zIndex = index + Z_INDEX_BASE;
+    });
+  };
+
+  const handleEsc = (e: KeyboardEvent) => {
+    if (e.key === 'Escape' && !isEmpty.value) {
+      pop();
+    }
+  };
+
+  let listenerAttached = false;
+
+  const attachEscListener = () => {
+    if (!listenerAttached) {
+      document.addEventListener('keydown', handleEsc);
+      listenerAttached = true;
+    }
+  };
+
+  const detachEscListener = () => {
+    if (listenerAttached) {
+      document.removeEventListener('keydown', handleEsc);
+      listenerAttached = false;
+    }
+  };
+
+  return {
+    overlayStack,
+    isEmpty,
+    topItem,
+    push,
+    pop,
+    remove,
+    attachEscListener,
+    detachEscListener,
+  };
+});
+
+export function useOverlayStack() {
+  const store = useOverlayStackStore();
+
+  onMounted(() => {
+    store.attachEscListener();
+  });
+
+  onBeforeUnmount(() => {
+    store.detachEscListener();
+  });
+
+  return store;
+}
+
+export function useOverlayItem(type: OverlayType) {
+  const store = useOverlayStackStore();
+  let itemId: string | undefined;
+
+  const register = (closeFn: () => void) => {
+    const id = generateId(type);
+    const entry = store.push({ id, type, close: closeFn });
+    itemId = entry.id;
+    return entry;
+  };
+
+  const unregister = () => {
+    if (itemId) {
+      store.remove(itemId);
+      itemId = undefined;
+    }
+  };
+
+  const currentZIndex = computed(() => {
+    if (!itemId) return undefined;
+    const item = store.overlayStack.find((i: OverlayItem) => i.id === itemId);
+    return item?.zIndex;
+  });
+
+  onBeforeUnmount(() => {
+    unregister();
+  });
+
+  return {
+    register,
+    unregister,
+    currentZIndex,
+  };
+}

package/compositions/peekView/index.ts

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

package/compositions/peekView/usePeekView.ts

@@ -0,0 +1,99 @@
+/**
+ * @description PeekView composable — state management for non-modal peek panels
+ * @author kine-design
+ * @date 2026/5/22
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { ref, onMounted } from 'vue';
+import { useOverlayStackStore } from '../overlay/useOverlayStack';
+
+export type PeekViewMode = 'side' | 'modal' | 'full';
+
+export interface UsePeekViewOptions {
+  /** Default mode when opening without explicit mode */
+  defaultMode?: PeekViewMode;
+  /** Enable URL query param sync (?peek=<id>) */
+  urlSync?: boolean;
+}
+
+export function usePeekView(options: UsePeekViewOptions = {}) {
+  const { defaultMode = 'side', urlSync = false } = options;
+
+  const isOpen = ref(false);
+  const mode = ref<PeekViewMode>(defaultMode);
+  const peekId = ref<string | undefined>(undefined);
+
+  // URL sync helpers
+  const readPeekFromUrl = (): string | undefined => {
+    if (typeof window === 'undefined') return undefined;
+    const params = new URLSearchParams(window.location.search);
+    return params.get('peek') || undefined;
+  };
+
+  const writePeekToUrl = (id: string | undefined) => {
+    if (typeof window === 'undefined') return;
+    const url = new URL(window.location.href);
+    if (id) {
+      url.searchParams.set('peek', id);
+    } else {
+      url.searchParams.delete('peek');
+    }
+    window.history.replaceState(window.history.state, '', url.toString());
+  };
+
+  const open = (id: string, openMode?: PeekViewMode) => {
+    peekId.value = id;
+    mode.value = openMode ?? defaultMode;
+    isOpen.value = true;
+    if (urlSync) {
+      writePeekToUrl(id);
+    }
+  };
+
+  const close = () => {
+    isOpen.value = false;
+    peekId.value = undefined;
+    if (urlSync) {
+      writePeekToUrl(undefined);
+    }
+  };
+
+  const setMode = (newMode: PeekViewMode) => {
+    mode.value = newMode;
+  };
+
+  // Outside click handler: close only if overlay stack is empty
+  const handleOutsideClick = (event: MouseEvent, panelEl: HTMLElement | null) => {
+    if (!isOpen.value || !panelEl) return;
+
+    const overlayStore = useOverlayStackStore();
+    if (!overlayStore.isEmpty) return;
+
+    const target = event.target as Node;
+    if (!panelEl.contains(target)) {
+      close();
+    }
+  };
+
+  // Initialize from URL on mount (if urlSync is enabled)
+  onMounted(() => {
+    if (urlSync) {
+      const urlPeekId = readPeekFromUrl();
+      if (urlPeekId) {
+        open(urlPeekId);
+      }
+    }
+  });
+
+  return {
+    isOpen,
+    mode,
+    peekId,
+    open,
+    close,
+    setMode,
+    handleOutsideClick,
+  };
+}

package/compositions/popper/useClickAway.ts

@@ -0,0 +1,41 @@
+/**
+ * @description click away hook
+ * @author 阿怪
+ * @date 2023/5/12 01:02
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import useEventListener from '../common/useEventListener';
+
+
+const event = 'pointerdown';
+export default function useClickAway(options: {
+  target: EventTarget | (() => EventTarget | null | undefined),
+  handler: (event: PointerEvent) => void
+}) {
+  if (typeof window === 'undefined' || !window) {
+    return;
+  }
+
+  const listener = (event: Event) => {
+    const el = typeof options.target === 'function' ? options.target() : options.target;
+    if (!el) {
+      return;
+    }
+
+    if (el === event.target || event.composedPath().includes(el)) {
+      return;
+    }
+
+    options.handler(event as PointerEvent);
+  };
+
+  return useEventListener({
+    target: window,
+    event,
+    handler: listener,
+  });
+
+
+}

package/compositions/popper/usePopper.ts

@@ -0,0 +1,63 @@
+/**
+ * @description popper hook
+ * @author 阿怪
+ * @date 2023/1/29 10:21
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { arrow, autoUpdate, computePosition, ComputePositionConfig } from '@floating-ui/dom';
+
+export type Placement =
+  | 'top' | 'top-start' | 'top-end'
+  | 'right' | 'right-start' | 'right-end'
+  | 'bottom' | 'bottom-start' | 'bottom-end'
+  | 'left' | 'left-start' | 'left-end';
+export type PopperConfig = Partial<ComputePositionConfig>;
+
+type DomStyle = { left: string; top: string; display: string; position: string };
+export type PositionStyle = { style: DomStyle; arrowStyle: DomStyle, placement: Placement };
+
+export const usePopper = (
+  triggerNode: HTMLElement,
+  popperNode: HTMLElement,
+  update: (data: PositionStyle) => void,
+  arrowNode?: HTMLElement,
+  config?: PopperConfig,
+) => {
+
+  const getPositionStyle = async () => {
+    if (arrowNode && config?.middleware) {
+      config.middleware.push(arrow({ element: arrowNode }));
+    }
+
+
+    const { x, y, placement, middlewareData } = await computePosition(triggerNode, popperNode, config);
+    const res: PositionStyle = {
+      style: {
+        left: `${x}px`,
+        top: `${y}px`,
+        display: 'block',
+        position: 'absolute',
+      },
+      arrowStyle: {
+        left: `${middlewareData.arrow?.x ?? 0}px`,
+        top: `${middlewareData.arrow?.y ?? 0}px`,
+        display: 'block',
+        position: 'absolute',
+      },
+      placement,
+    };
+    update(res);
+
+    return res;
+  };
+
+  const clear = autoUpdate(triggerNode, popperNode, getPositionStyle);
+
+
+  return {
+    getPositionStyle,
+    clear,
+  };
+};

package/compositions/theme/index.ts

@@ -0,0 +1,17 @@
+/**
+ * @description theme composables barrel export
+ * @author kine-design
+ * @date 2026/5/22
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+export { useThemeStore } from './useTheme';
+export type {
+  ThemeDefinition,
+  ThemeTokens,
+  ThemeTokenCategory,
+  ThemeOverrides,
+  PersistedThemeState,
+} from './types';
+export { lightTheme, darkTheme, compactTheme } from './presets';