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

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

package/compositions/theme/presets/compact.ts

@@ -0,0 +1,117 @@
+/**
+ * @description compact theme preset — denser layout with scaled-down spacing/font/radius
+ * @author kine-design
+ * @date 2026/5/22
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import type { ThemeDefinition } from '../types';
+
+/**
+ * Compact theme inherits light colors but scales spacing/radius/font down by ~0.75.
+ * Shadow and motion stay unchanged.
+ */
+export const compactTheme: ThemeDefinition = {
+  id: 'compact',
+  name: 'Compact',
+  description: 'Denser layout — smaller spacing, font sizes, and radius (0.75x scale)',
+  tokens: {
+    color: {
+      'bg-primary': '#f5f5f5',
+      'bg-secondary': '#ebebeb',
+      'bg-tertiary': '#e0e0e0',
+      'bg-hover': '#d4d4d4',
+      'bg-inset': '#dcdcdc',
+      'neutral-1': '#f0f0f0',
+      'neutral-2': '#e5e5e5',
+      'neutral-3': '#d4d4d4',
+      'neutral-4': '#c0c0c0',
+      'neutral-5': '#a0a0a0',
+      'neutral-6': '#787878',
+      'accent-light': '#e8f5ef',
+      'accent-default': '#1ab873',
+      'accent-hover': '#1ec87d',
+      'accent-active': '#158f5a',
+      'accent-alt': '#168f5a',
+      'semantic-success': '#1ab873',
+      'semantic-success-hover': '#1ec87d',
+      'semantic-success-light': '#e8f5ef',
+      'semantic-warning': '#d4820a',
+      'semantic-warning-hover': '#e08f10',
+      'semantic-warning-light': '#fdf4e6',
+      'semantic-error': '#b03020',
+      'semantic-error-hover': '#c03828',
+      'semantic-error-light': '#fce8e6',
+      'semantic-info': '#4a6a9e',
+      'semantic-info-hover': '#3a558a',
+      'semantic-info-light': '#e8eef5',
+      'text-primary': '#1a1a1a',
+      'text-secondary': '#4a4f4c',
+      'text-muted': '#8a8a8a',
+      'text-inverse': '#ffffff',
+      'border-default': '#c8c9c3',
+      'border-subtle': '#e0e0dc',
+      'border-strong': '#1ab873',
+    },
+    interaction: {
+      'hover-intensity': '15%',
+      'active-intensity': '22%',
+      'focus-glow': '30%',
+      'focus-ring-width': '1px',
+      'focus-ring-offset': '1px',
+      'text-glow': '50%',
+      'transition-duration': '100ms',
+    },
+    spacing: {
+      '1': '1px',
+      '2': '3px',
+      '3': '4px',
+      '4': '6px',
+      '5': '8px',
+      '6': '9px',
+      '7': '10px',
+      '8': '12px',
+      '10': '15px',
+      '12': '18px',
+      '14': '21px',
+      '16': '24px',
+      '20': '30px',
+      '24': '36px',
+    },
+    radius: {
+      'xs': '1px',
+      'sm': '4px',
+      'md': '6px',
+      'lg': '9px',
+    },
+    font: {
+      'family-mono': "ui-monospace, 'SF Mono', 'Cascadia Code', 'Fira Code', monospace",
+      'family-system': 'system-ui, -apple-system, sans-serif',
+      'size-xs': '7px',
+      'size-sm': '8px',
+      'size-md': '10px',
+      'size-lg': '11px',
+      'size-xl': '12px',
+      'size-2xl': '13px',
+      'size-3xl': '16px',
+      'size-4xl': '20px',
+      'weight-thin': '100',
+      'weight-regular': '400',
+      'weight-medium': '500',
+      'weight-semibold': '600',
+      'weight-bold': '700',
+    },
+    shadow: {
+      'glow-radius': '8px',
+      'sm': '0px 1px 2px rgba(0,0,0,0.05)',
+      'md': '0px 4px 8px rgba(0,0,0,0.08), 0px 2px 4px rgba(0,0,0,0.04)',
+      'lg': '0px 4px 8px rgba(0,0,0,0.12), 0px 6px 12px rgba(16,24,40,0.12), 0px 1px 16px rgba(16,24,40,0.12)',
+    },
+    motion: {
+      'duration-fast': '200ms',
+      'duration-normal': '400ms',
+      'easing-default': 'ease-in-out',
+    },
+  },
+};

package/compositions/theme/presets/dark.ts

@@ -0,0 +1,113 @@
+/**
+ * @description dark theme preset — Phosphor sci-fi terminal palette
+ * @author kine-design
+ * @date 2026/5/22
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import type { ThemeDefinition } from '../types';
+
+export const darkTheme: ThemeDefinition = {
+  id: 'dark',
+  name: 'Dark',
+  description: 'Dark mode — Phosphor terminal aesthetic, inverted colors',
+  tokens: {
+    color: {
+      'bg-primary': '#000000',
+      'bg-secondary': '#0a0a0a',
+      'bg-tertiary': '#141414',
+      'bg-hover': '#1a1a1a',
+      'bg-inset': '#1e1e1e',
+      'neutral-1': '#0f0f0f',
+      'neutral-2': '#1a1a1a',
+      'neutral-3': '#262626',
+      'neutral-4': '#333333',
+      'neutral-5': '#4a4a4a',
+      'neutral-6': '#666666',
+      'accent-light': '#0d2e1f',
+      'accent-default': '#2ad98d',
+      'accent-hover': '#3ae29a',
+      'accent-active': '#22b072',
+      'accent-alt': '#1fa86b',
+      'semantic-success': '#2ad98d',
+      'semantic-success-hover': '#3ae29a',
+      'semantic-success-light': '#0d2e1f',
+      'semantic-warning': '#fab03d',
+      'semantic-warning-hover': '#fabb55',
+      'semantic-warning-light': '#2e2210',
+      'semantic-error': '#cb523e',
+      'semantic-error-hover': '#de5f48',
+      'semantic-error-light': '#2e1210',
+      'semantic-info': '#8ba3c7',
+      'semantic-info-hover': '#5976ba',
+      'semantic-info-light': '#10182e',
+      'text-primary': '#e8e8e8',
+      'text-secondary': '#86908a',
+      'text-muted': '#555555',
+      'text-inverse': '#0a0a0a',
+      'border-default': '#31322c',
+      'border-subtle': '#252520',
+      'border-strong': '#2ad98d',
+    },
+    interaction: {
+      'hover-intensity': '18%',
+      'active-intensity': '28%',
+      'focus-glow': '35%',
+      'focus-ring-width': '2px',
+      'focus-ring-offset': '2px',
+      'text-glow': '55%',
+      'transition-duration': '150ms',
+    },
+    spacing: {
+      '1': '2px',
+      '2': '4px',
+      '3': '6px',
+      '4': '8px',
+      '5': '10px',
+      '6': '12px',
+      '7': '14px',
+      '8': '16px',
+      '10': '20px',
+      '12': '24px',
+      '14': '28px',
+      '16': '32px',
+      '20': '40px',
+      '24': '48px',
+    },
+    radius: {
+      'xs': '2px',
+      'sm': '6px',
+      'md': '8px',
+      'lg': '12px',
+    },
+    font: {
+      'family-mono': "ui-monospace, 'SF Mono', 'Cascadia Code', 'Fira Code', monospace",
+      'family-system': 'system-ui, -apple-system, sans-serif',
+      'size-xs': '9px',
+      'size-sm': '10px',
+      'size-md': '12px',
+      'size-lg': '13px',
+      'size-xl': '14px',
+      'size-2xl': '16px',
+      'size-3xl': '20px',
+      'size-4xl': '24px',
+      'weight-thin': '100',
+      'weight-regular': '400',
+      'weight-medium': '500',
+      'weight-semibold': '600',
+      'weight-bold': '700',
+    },
+    shadow: {
+      'glow-radius': '8px',
+      'sm': '0px 1px 2px rgba(0,0,0,0.15)',
+      'md': '0px 4px 8px rgba(0,0,0,0.25), 0px 2px 4px rgba(0,0,0,0.15)',
+      'lg': '0px 4px 8px rgba(0,0,0,0.35), 0px 6px 12px rgba(0,0,0,0.25), 0px 1px 16px rgba(0,0,0,0.2)',
+    },
+    motion: {
+      'duration-fast': '200ms',
+      'duration-normal': '400ms',
+      'easing-default': 'ease-in-out',
+    },
+  },
+};

package/compositions/theme/presets/index.ts

@@ -0,0 +1,11 @@
+/**
+ * @description built-in theme presets barrel export
+ * @author kine-design
+ * @date 2026/5/22
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+export { lightTheme } from './light';
+export { darkTheme } from './dark';
+export { compactTheme } from './compact';

package/compositions/theme/presets/light.ts

@@ -0,0 +1,113 @@
+/**
+ * @description light theme preset — extracted from base.css :root values
+ * @author kine-design
+ * @date 2026/5/22
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import type { ThemeDefinition } from '../types';
+
+export const lightTheme: ThemeDefinition = {
+  id: 'light',
+  name: 'Light',
+  description: 'Default light theme — neutral backgrounds, dark text, Phosphor accent',
+  tokens: {
+    color: {
+      'bg-primary': '#f5f5f5',
+      'bg-secondary': '#ebebeb',
+      'bg-tertiary': '#e0e0e0',
+      'bg-hover': '#d4d4d4',
+      'bg-inset': '#dcdcdc',
+      'neutral-1': '#f0f0f0',
+      'neutral-2': '#e5e5e5',
+      'neutral-3': '#d4d4d4',
+      'neutral-4': '#c0c0c0',
+      'neutral-5': '#a0a0a0',
+      'neutral-6': '#787878',
+      'accent-light': '#e8f5ef',
+      'accent-default': '#1ab873',
+      'accent-hover': '#1ec87d',
+      'accent-active': '#158f5a',
+      'accent-alt': '#168f5a',
+      'semantic-success': '#1ab873',
+      'semantic-success-hover': '#1ec87d',
+      'semantic-success-light': '#e8f5ef',
+      'semantic-warning': '#d4820a',
+      'semantic-warning-hover': '#e08f10',
+      'semantic-warning-light': '#fdf4e6',
+      'semantic-error': '#b03020',
+      'semantic-error-hover': '#c03828',
+      'semantic-error-light': '#fce8e6',
+      'semantic-info': '#4a6a9e',
+      'semantic-info-hover': '#3a558a',
+      'semantic-info-light': '#e8eef5',
+      'text-primary': '#1a1a1a',
+      'text-secondary': '#4a4f4c',
+      'text-muted': '#8a8a8a',
+      'text-inverse': '#ffffff',
+      'border-default': '#c8c9c3',
+      'border-subtle': '#e0e0dc',
+      'border-strong': '#1ab873',
+    },
+    interaction: {
+      'hover-intensity': '15%',
+      'active-intensity': '22%',
+      'focus-glow': '30%',
+      'focus-ring-width': '2px',
+      'focus-ring-offset': '2px',
+      'text-glow': '50%',
+      'transition-duration': '150ms',
+    },
+    spacing: {
+      '1': '2px',
+      '2': '4px',
+      '3': '6px',
+      '4': '8px',
+      '5': '10px',
+      '6': '12px',
+      '7': '14px',
+      '8': '16px',
+      '10': '20px',
+      '12': '24px',
+      '14': '28px',
+      '16': '32px',
+      '20': '40px',
+      '24': '48px',
+    },
+    radius: {
+      'xs': '2px',
+      'sm': '6px',
+      'md': '8px',
+      'lg': '12px',
+    },
+    font: {
+      'family-mono': "ui-monospace, 'SF Mono', 'Cascadia Code', 'Fira Code', monospace",
+      'family-system': 'system-ui, -apple-system, sans-serif',
+      'size-xs': '9px',
+      'size-sm': '10px',
+      'size-md': '12px',
+      'size-lg': '13px',
+      'size-xl': '14px',
+      'size-2xl': '16px',
+      'size-3xl': '20px',
+      'size-4xl': '24px',
+      'weight-thin': '100',
+      'weight-regular': '400',
+      'weight-medium': '500',
+      'weight-semibold': '600',
+      'weight-bold': '700',
+    },
+    shadow: {
+      'glow-radius': '8px',
+      'sm': '0px 1px 2px rgba(0,0,0,0.05)',
+      'md': '0px 4px 8px rgba(0,0,0,0.08), 0px 2px 4px rgba(0,0,0,0.04)',
+      'lg': '0px 4px 8px rgba(0,0,0,0.12), 0px 6px 12px rgba(16,24,40,0.12), 0px 1px 16px rgba(16,24,40,0.12)',
+    },
+    motion: {
+      'duration-fast': '200ms',
+      'duration-normal': '400ms',
+      'easing-default': 'ease-in-out',
+    },
+  },
+};

package/compositions/theme/types.ts

@@ -0,0 +1,46 @@
+/**
+ * @description theme system type definitions
+ * @author kine-design
+ * @date 2026/5/22
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+
+/** Token category map: flat key-value pairs per category */
+export interface ThemeTokens {
+  /** e.g. 'bg-primary': '#f5f5f5', 'neutral-3': '#d4d4d4', 'accent-light': '#e8f5ef' */
+  color: Record<string, string>
+  /** e.g. '1': '2px', '2': '4px' */
+  spacing: Record<string, string>
+  /** e.g. 'xs': '2px', 'sm': '6px' */
+  radius: Record<string, string>
+  /** e.g. 'size-sm': '12px', 'family-system': 'system-ui, ...' */
+  font: Record<string, string>
+  /** e.g. 'sm': '0px 1px 2px ...', 'glow-radius': '8px' */
+  shadow: Record<string, string>
+  /** e.g. 'duration-fast': '200ms', 'easing-default': 'ease-in-out' */
+  motion: Record<string, string>
+  /** e.g. 'hover-intensity': '15%', 'transition-duration': '150ms' */
+  interaction: Record<string, string>
+}
+
+/** All supported token category names */
+export type ThemeTokenCategory = keyof ThemeTokens
+
+/** A registered theme definition */
+export interface ThemeDefinition {
+  id: string
+  name: string
+  description?: string
+  tokens: Partial<ThemeTokens>
+}
+
+/** User-level per-token overrides (sparse) */
+export type ThemeOverrides = Partial<ThemeTokens>
+
+/** Serialized state persisted to localStorage */
+export interface PersistedThemeState {
+  currentTheme: string
+  overrides: ThemeOverrides
+}