@karyl-chan/ui 0.1.0

package/src/composables/use-confirm.ts

@@ -0,0 +1,36 @@
+import { ref } from "vue";
+
+export interface ConfirmOptions {
+  title: string;
+  message: string;
+  confirmLabel?: string;
+  confirmVariant?: "primary" | "danger";
+  cancelLabel?: string;
+}
+
+interface PendingConfirm {
+  options: ConfirmOptions;
+  resolve: (confirmed: boolean) => void;
+}
+
+const pending = ref<PendingConfirm | null>(null);
+
+export function useConfirm() {
+  function confirm(opts: ConfirmOptions): Promise<boolean> {
+    return new Promise<boolean>((resolve) => {
+      pending.value = { options: opts, resolve };
+    });
+  }
+
+  function handleConfirm() {
+    pending.value?.resolve(true);
+    pending.value = null;
+  }
+
+  function handleClose() {
+    pending.value?.resolve(false);
+    pending.value = null;
+  }
+
+  return { pending, confirm, handleConfirm, handleClose };
+}

package/src/composables/use-drawer.css

@@ -0,0 +1,47 @@
+/*
+ * Drawer layout, backdrop, and slide-transition classes.
+ * Imported by: main.ts (global, once at app init)
+ * Discipline: per-instance chrome (padding, colour, border) stays in the
+ *   caller's scoped style; this file is only for shared structure and transitions.
+ */
+
+.drawer-backdrop {
+    position: fixed;
+    inset: 0;
+    background: rgba(0, 0, 0, 0.45);
+    z-index: 1000;
+}
+.drawer-panel {
+    position: fixed;
+    z-index: 1001;
+    display: flex;
+    flex-direction: column;
+    background: var(--bg-surface);
+    overflow: hidden;
+}
+.drawer-panel[data-placement="bottom"] { bottom: 0; left: 0; right: 0; }
+.drawer-panel[data-placement="top"] { top: 0; left: 0; right: 0; }
+.drawer-panel[data-placement="left"] { top: 0; bottom: 0; left: 0; }
+.drawer-panel[data-placement="right"] { top: 0; bottom: 0; right: 0; }
+
+.drawer-fade-enter-active,
+.drawer-fade-leave-active { transition: opacity 0.2s; }
+.drawer-fade-enter-from,
+.drawer-fade-leave-to { opacity: 0; }
+
+.drawer-slide-bottom-enter-active,
+.drawer-slide-bottom-leave-active,
+.drawer-slide-top-enter-active,
+.drawer-slide-top-leave-active,
+.drawer-slide-left-enter-active,
+.drawer-slide-left-leave-active,
+.drawer-slide-right-enter-active,
+.drawer-slide-right-leave-active { transition: transform 0.22s cubic-bezier(0.4, 0, 0.2, 1); }
+.drawer-slide-bottom-enter-from,
+.drawer-slide-bottom-leave-to { transform: translateY(100%); }
+.drawer-slide-top-enter-from,
+.drawer-slide-top-leave-to { transform: translateY(-100%); }
+.drawer-slide-left-enter-from,
+.drawer-slide-left-leave-to { transform: translateX(-100%); }
+.drawer-slide-right-enter-from,
+.drawer-slide-right-leave-to { transform: translateX(100%); }

package/src/composables/use-drawer.ts

@@ -0,0 +1,58 @@
+import { onBeforeUnmount, watch, type Ref } from "vue";
+import { useEscapeStack } from "./use-escape-stack";
+
+export type DrawerPlacement = "bottom" | "top" | "left" | "right";
+
+export interface UseDrawerOptions {
+  /** Reactive flag controlling the drawer's mounted/open state. */
+  visible: Ref<boolean>;
+  /** Edge the panel is anchored to and slides in from. Default: 'bottom'. */
+  placement?: DrawerPlacement;
+  /** Called when the user dismisses the drawer (backdrop click / Escape). */
+  onClose?: () => void;
+  /** Escape closes the drawer. Default: true. */
+  closeOnEscape?: boolean;
+}
+
+export interface UseDrawerReturn {
+  placement: DrawerPlacement;
+  backdropClass: string;
+  panelClass: string;
+  backdropTransition: string;
+  panelTransition: string;
+  close: () => void;
+}
+
+/**
+ * Generic drawer behavior: escape-stack registration, placement-driven
+ * transition class names, and shared backdrop/panel styles. The caller
+ * owns the Teleport + <Transition> + DOM, so drawers can live inline
+ * without a one-size-fits-all wrapper component.
+ */
+export function useDrawer(options: UseDrawerOptions): UseDrawerReturn {
+  const placement: DrawerPlacement = options.placement ?? "bottom";
+  const closeOnEscape = options.closeOnEscape !== false;
+  const { register, unregister } = useEscapeStack();
+
+  const close = () => options.onClose?.();
+
+  watch(
+    options.visible,
+    (v) => {
+      if (v) register(closeOnEscape ? close : null);
+      else unregister();
+    },
+    { immediate: true },
+  );
+
+  onBeforeUnmount(unregister);
+
+  return {
+    placement,
+    backdropClass: "drawer-backdrop",
+    panelClass: "drawer-panel",
+    backdropTransition: "drawer-fade",
+    panelTransition: `drawer-slide-${placement}`,
+    close,
+  };
+}

package/src/composables/use-escape-stack.ts

@@ -0,0 +1,80 @@
+import { nanoid } from 'nanoid'
+
+type EscapeCallback = () => void
+
+interface StackEntry {
+    id: string
+    callback: EscapeCallback | null
+}
+
+const stacks = new Map<string, StackEntry[]>()
+let listenerInstalled = false
+
+function ensureListener() {
+    if (listenerInstalled) return
+    listenerInstalled = true
+
+    document.addEventListener('keydown', (e) => {
+        if (e.key !== 'Escape') return
+
+        for (const [, entries] of stacks) {
+            // 從頂端往下找第一個有 callback 的
+            for (let i = entries.length - 1; i >= 0; i--) {
+                const entry = entries[i]
+                if (entry.callback) {
+                    e.stopPropagation()
+                    e.preventDefault()
+                    entry.callback()
+                    return
+                }
+            }
+        }
+    })
+}
+
+/**
+ * 統一的 overlay escape 管理
+ *
+ * 所有 overlay（usePopover、NuModal）共用同一個 escape stack，
+ * 按 Escape 時只有最頂層的 overlay 會被關閉。
+ *
+ * @param target - stack 分組 key（通常為 'overlay'）
+ */
+export const useEscapeStack = (target = 'overlay') => {
+    if (!stacks.has(target)) {
+        stacks.set(target, [])
+    }
+
+    const id = nanoid()
+    const stack = stacks.get(target)!
+
+    /**
+     * 註冊到 stack，提供 escape callback。
+     * 傳入 null 表示佔位但不響應 Escape（如 closeOnEscape: false 的 overlay）。
+     */
+    const register = (callback: EscapeCallback | null) => {
+        // 避免重複註冊
+        if (stack.some(e => e.id === id)) return
+        stack.push({ id, callback })
+        ensureListener()
+    }
+
+    /**
+     * 從 stack 移除
+     */
+    const unregister = () => {
+        const idx = stack.findIndex(e => e.id === id)
+        if (idx !== -1) stack.splice(idx, 1)
+    }
+
+    /**
+     * 取得目前 stack 中的註冊數量（用於判斷是否需要解鎖 body scroll 等）
+     */
+    const getStackSize = () => stack.length
+
+    return {
+        register,
+        unregister,
+        getStackSize,
+    }
+}

package/src/composables/use-file-drop.ts

@@ -0,0 +1,47 @@
+import { ref, type Ref } from 'vue'
+
+export interface FileDropHandlers {
+    isDragging: Ref<boolean>
+    onDragEnter: (event: DragEvent) => void
+    onDragOver: (event: DragEvent) => void
+    onDragLeave: () => void
+    onDrop: (event: DragEvent) => void
+}
+
+export function useFileDrop(onFiles: (files: File[]) => void): FileDropHandlers {
+    const isDragging = ref(false)
+    let counter = 0
+
+    function isFileDrag(event: DragEvent): boolean {
+        const types = event.dataTransfer?.types
+        if (!types) return false
+        for (let i = 0; i < types.length; i++) if (types[i] === 'Files') return true
+        return false
+    }
+
+    return {
+        isDragging,
+        onDragEnter(event) {
+            if (!isFileDrag(event)) return
+            event.preventDefault()
+            counter++
+            isDragging.value = true
+        },
+        onDragOver(event) {
+            if (!isFileDrag(event)) return
+            event.preventDefault()
+        },
+        onDragLeave() {
+            counter = Math.max(0, counter - 1)
+            if (counter === 0) isDragging.value = false
+        },
+        onDrop(event) {
+            event.preventDefault()
+            counter = 0
+            isDragging.value = false
+            const files = event.dataTransfer?.files
+            if (!files || files.length === 0) return
+            onFiles(Array.from(files))
+        }
+    }
+}

package/src/composables/use-long-press.ts

@@ -0,0 +1,62 @@
+import { onBeforeUnmount } from 'vue';
+
+export interface UseLongPressOptions {
+    /** Hold duration before the action fires. Default 450 ms — matches
+     *  the timer used by the chat conversation's message long-press. */
+    ms?: number;
+}
+
+export interface LongPressInfo {
+    /** Viewport-relative coordinates of the touch. Suitable for
+     *  positioning a context menu via clientX/clientY semantics. */
+    x: number;
+    y: number;
+    /** The element the touch started on. Captured at touchstart because
+     *  `event.currentTarget` is null by the time the timer fires. */
+    target: HTMLElement;
+}
+
+export interface LongPressBinding {
+    start: (event: TouchEvent, action: (info: LongPressInfo) => void) => void;
+    cancel: () => void;
+}
+
+/**
+ * Touch long-press helper. Returns `start` (call from `@touchstart`) and
+ * `cancel` (call from `@touchend` / `@touchmove` / `@touchcancel`).
+ * `start` snapshots the touch coordinates and `currentTarget` synchronously
+ * so the action closure can use them after the setTimeout — `event.currentTarget`
+ * is reset to null once event handling completes.
+ *
+ * `contextmenu` events fire reliably on right-click but not on touch
+ * (especially Safari on iOS). This helper supplies the missing path
+ * for any sidebar row / chip / button that wants to surface a context
+ * menu under both pointer and touch input.
+ */
+export function useLongPress(options: UseLongPressOptions = {}): LongPressBinding {
+    const ms = options.ms ?? 450;
+    let timer: ReturnType<typeof setTimeout> | null = null;
+
+    function start(event: TouchEvent, action: (info: LongPressInfo) => void) {
+        if (event.touches.length !== 1) return;
+        const touch = event.touches[0];
+        const target = event.currentTarget as HTMLElement | null;
+        if (!target) return;
+        const info: LongPressInfo = { x: touch.clientX, y: touch.clientY, target };
+        if (timer) clearTimeout(timer);
+        timer = setTimeout(() => {
+            timer = null;
+            action(info);
+        }, ms);
+    }
+    function cancel() {
+        if (timer) {
+            clearTimeout(timer);
+            timer = null;
+        }
+    }
+
+    onBeforeUnmount(cancel);
+
+    return { start, cancel };
+}

package/src/composables/use-popover.css

@@ -0,0 +1,32 @@
+/*
+ * Popover placement-entry animation keyframes and utility classes.
+ * Imported by: main.ts (global, once at app init)
+ * Discipline: per-instance chrome (padding, colour, border) stays in the
+ *   caller's scoped style; this file is only for shared animation primitives.
+ */
+
+[data-popover-entering] *{transition:none!important}
+@keyframes popoverSlideDownAndFade{
+    from{opacity:0;transform:translateY(-10px)}
+    to{opacity:1;transform:translateY(0)}
+}
+@keyframes popoverSlideUpAndFade{
+    from{opacity:0;transform:translateY(10px)}
+    to{opacity:1;transform:translateY(0)}
+}
+@keyframes popoverSlideLeftAndFade{
+    from{opacity:0;transform:translateX(10px)}
+    to{opacity:1;transform:translateY(0)}
+}
+@keyframes popoverSlideRightAndFade{
+    from{opacity:0;transform:translateX(-10px)}
+    to{opacity:1;transform:translateY(0)}
+}
+.popover-anim-down-normal{animation:popoverSlideDownAndFade .2s ease 0s 1 normal both}
+.popover-anim-down-reverse{animation:popoverSlideDownAndFade .2s ease 0s 1 reverse both}
+.popover-anim-up-normal{animation:popoverSlideUpAndFade .2s ease 0s 1 normal both}
+.popover-anim-up-reverse{animation:popoverSlideUpAndFade .2s ease 0s 1 reverse both}
+.popover-anim-left-normal{animation:popoverSlideLeftAndFade .2s ease 0s 1 normal both}
+.popover-anim-left-reverse{animation:popoverSlideLeftAndFade .2s ease 0s 1 reverse both}
+.popover-anim-right-normal{animation:popoverSlideRightAndFade .2s ease 0s 1 normal both}
+.popover-anim-right-reverse{animation:popoverSlideRightAndFade .2s ease 0s 1 reverse both}