@simplysm/solid 13.0.0-beta.6

package/src/hooks/createMountTransition.ts

@@ -0,0 +1,45 @@
+import { createSignal, createEffect, onCleanup } from "solid-js";
+
+/**
+ * 열림/닫힘 애니메이션을 위한 mount transition 훅
+ *
+ * @remarks
+ * - `open`이 true가 되면 즉시 `mounted=true`, double rAF 후 `animating=true`
+ * - `open`이 false가 되면 즉시 `animating=false`, transitionend 또는 fallback 타이머(200ms) 후 `mounted=false`
+ * - CSS transition과 함께 사용: `mounted()`로 DOM 렌더링, `animating()`으로 CSS 클래스 전환
+ */
+export function createMountTransition(open: () => boolean): {
+  mounted: () => boolean;
+  animating: () => boolean;
+  unmount: () => void;
+} {
+  const [mounted, setMounted] = createSignal(false);
+  const [animating, setAnimating] = createSignal(false);
+
+  createEffect(() => {
+    if (open()) {
+      setMounted(true);
+      let rafId1: number;
+      let rafId2: number;
+      rafId1 = requestAnimationFrame(() => {
+        rafId2 = requestAnimationFrame(() => {
+          setAnimating(true);
+        });
+      });
+      onCleanup(() => {
+        cancelAnimationFrame(rafId1);
+        cancelAnimationFrame(rafId2);
+      });
+    } else if (mounted()) {
+      setAnimating(false);
+      const fallbackTimer = setTimeout(() => {
+        if (!open()) setMounted(false);
+      }, 200);
+      onCleanup(() => clearTimeout(fallbackTimer));
+    }
+  });
+
+  const unmount = () => setMounted(false);
+
+  return { mounted, animating, unmount };
+}

package/src/hooks/useClipboardValueCopy.ts

@@ -0,0 +1,177 @@
+import { onCleanup, onMount } from "solid-js";
+
+/**
+ * 폼 컨트롤의 value를 클립보드 복사에 포함시키는 초기화 훅
+ *
+ * @remarks
+ * 브라우저 기본 동작에서는 드래그 선택 후 복사 시 `<input>`, `<textarea>`, `<select>`의
+ * 값이 포함되지 않는 문제를 해결한다.
+ *
+ * - `<input type="text|number|...">` → `.value`
+ * - `<textarea>` → `.value`
+ * - `<select>` → 선택된 옵션 텍스트
+ * - `<input type="checkbox|radio">` → `.checked` ? "Y" : ""
+ * - 테이블 내에서는 셀 간 탭(`\t`), 행 간 개행(`\n`) 구분 (Excel 호환)
+ */
+export function useClipboardValueCopy(): void {
+  onMount(() => {
+    const handler = (e: ClipboardEvent) => {
+      const sel = window.getSelection();
+      if (!sel || sel.isCollapsed || sel.rangeCount === 0) return;
+
+      const range = sel.getRangeAt(0);
+      const text = extractTextFromRange(range);
+      if (text == null) return;
+
+      e.clipboardData!.setData("text/plain", text);
+      e.preventDefault();
+    };
+
+    document.addEventListener("copy", handler);
+    onCleanup(() => document.removeEventListener("copy", handler));
+  });
+}
+
+/**
+ * Selection Range 내의 텍스트를 추출한다.
+ * 폼 컨트롤은 value로 치환하고, 테이블 구조는 TSV 형식으로 변환한다.
+ *
+ * @returns 추출된 텍스트. 폼 컨트롤이 없으면 `null` (브라우저 기본 동작 유지)
+ */
+function extractTextFromRange(range: Range): string | null {
+  const root =
+    range.commonAncestorContainer instanceof Element
+      ? range.commonAncestorContainer
+      : range.commonAncestorContainer.parentElement;
+  if (!root) return null;
+
+  // 선택 범위에 폼 컨트롤이 없으면 브라우저 기본 동작 사용
+  const formSelector = 'input:not([type=hidden]), textarea, select, [role="checkbox"], [role="radio"]';
+  const hasFormElements = [...root.querySelectorAll(formSelector)].some((el) => range.intersectsNode(el));
+  if (!hasFormElements) return null;
+
+  const parts: string[] = [];
+
+  const walk = (node: Node) => {
+    if (!range.intersectsNode(node)) return;
+
+    // ARIA checkbox/radio: role="checkbox" 또는 role="radio" 요소
+    if (node instanceof Element) {
+      const role = node.getAttribute("role");
+      if (role === "checkbox" || role === "radio") {
+        parts.push(node.getAttribute("aria-checked") === "true" ? "Y" : "");
+        return;
+      }
+    }
+
+    // 폼 컨트롤: value 추출
+    if (node instanceof HTMLInputElement) {
+      if (node.type === "hidden") return;
+      if (node.type === "checkbox" || node.type === "radio") {
+        parts.push(node.checked ? "Y" : "");
+      } else {
+        parts.push(formatInputValue(node));
+      }
+      return;
+    }
+    if (node instanceof HTMLTextAreaElement) {
+      const v = node.value;
+      // 개행 포함 시 큰따옴표로 감싸서 Excel 셀 내 줄바꿈 유지
+      parts.push(v.includes("\n") ? `"${v.replace(/"/g, '""')}"` : v);
+      return;
+    }
+    if (node instanceof HTMLSelectElement) {
+      if (node.selectedOptions.length > 0) {
+        parts.push(node.selectedOptions[0].textContent?.trim() ?? "");
+      }
+      return;
+    }
+
+    // 텍스트 노드
+    if (node.nodeType === Node.TEXT_NODE) {
+      // 숨겨진 텍스트 건너뛰기 (dual-element overlay 패턴 등)
+      const parent = node.parentElement;
+      if (parent) {
+        const style = getComputedStyle(parent);
+        if (style.visibility === "hidden" || style.display === "none") {
+          return;
+        }
+      }
+
+      let text = node.textContent ?? "";
+      if (node === range.startContainer && node === range.endContainer) {
+        text = text.slice(range.startOffset, range.endOffset);
+      } else if (node === range.startContainer) {
+        text = text.slice(range.startOffset);
+      } else if (node === range.endContainer) {
+        text = text.slice(0, range.endOffset);
+      }
+      parts.push(text);
+      return;
+    }
+
+    // Element가 아닌 노드
+    if (!(node instanceof Element)) {
+      for (const child of node.childNodes) walk(child);
+      return;
+    }
+
+    // <br>
+    if (node.tagName === "BR") {
+      parts.push("\n");
+      return;
+    }
+
+    // 테이블 행: 셀 간 탭 구분, 행 끝 개행
+    if (node.tagName === "TR") {
+      let firstCell = true;
+      for (const child of node.childNodes) {
+        if (!range.intersectsNode(child)) continue;
+        if (child instanceof HTMLTableCellElement) {
+          if (!firstCell) parts.push("\t");
+          firstCell = false;
+        }
+        walk(child);
+      }
+      parts.push("\n");
+      return;
+    }
+
+    // 기본: 자식 순회
+    for (const child of node.childNodes) {
+      walk(child);
+    }
+  };
+
+  walk(range.commonAncestorContainer);
+
+  return parts.join("").replace(/\n+$/, "");
+}
+
+/**
+ * input value를 로캘 형식으로 변환한다.
+ * - `date` → `toLocaleDateString()`
+ * - `time` → `toLocaleTimeString()`
+ * - `datetime-local` → `toLocaleString()`
+ * - 그 외 → 원래 값 그대로
+ */
+function formatInputValue(input: HTMLInputElement): string {
+  const { type, value } = input;
+  if (!value) return "";
+
+  if (type === "date" || type === "datetime-local") {
+    const date = new Date(value);
+    if (!isNaN(date.getTime())) {
+      return type === "date" ? date.toLocaleDateString() : date.toLocaleString();
+    }
+  }
+
+  if (type === "time") {
+    const date = new Date(`1970-01-01T${value}`);
+    if (!isNaN(date.getTime())) {
+      return date.toLocaleTimeString();
+    }
+  }
+
+  return value;
+}

package/src/hooks/usePersisted.ts

@@ -0,0 +1,51 @@
+import { createSignal, type Accessor, type Setter } from "solid-js";
+import { makePersisted, type AsyncStorage, type SyncStorage } from "@solid-primitives/storage";
+import { jsonStringify, jsonParse } from "@simplysm/core-common";
+import { useConfig } from "../providers/ConfigContext";
+
+/**
+ * clientName prefix가 적용된 영속 저장소 훅
+ *
+ * @remarks
+ * - ConfigContext.Provider 내부에서만 사용 가능
+ * - 키는 자동으로 `{clientName}.{key}` 형태로 저장됨
+ * - 반응형 동기화 지원 (Signal 변경 시 자동 저장)
+ * - DateTime, DateOnly, Time, Uuid 등 커스텀 타입 직렬화 지원
+ * - 비동기 저장소 사용 시 세 번째 반환값 `loading`으로 초기 로드 상태 확인 가능
+ *
+ * @example
+ * ```tsx
+ * // 기본 사용 (localStorage)
+ * const [theme, setTheme, loading] = usePersisted("theme", "light");
+ *
+ * // loading 무시 (기존 호환)
+ * const [theme, setTheme] = usePersisted("theme", "light");
+ * ```
+ *
+ * @param key - 저장소 키 (clientName prefix가 자동 적용됨)
+ * @param initialValue - 초기값 (저장된 값이 없을 때 사용)
+ * @returns [getter, setter, loading] 튜플
+ */
+export function usePersisted<T>(key: string, initialValue: T): [Accessor<T>, Setter<T>, Accessor<boolean>] {
+  const config = useConfig();
+  const prefixedKey = `${config.clientName}.${key}`;
+  const storage = config.storage ?? localStorage;
+
+  // eslint-disable-next-line solid/reactivity -- makePersisted는 signal 튜플을 직접 받도록 설계됨
+  const [value, setValue, init] = makePersisted(createSignal<T>(initialValue), {
+    name: prefixedKey,
+    storage: storage as SyncStorage | AsyncStorage,
+    serialize: (v) => jsonStringify(v),
+    deserialize: (v) => jsonParse<T>(v),
+  });
+
+  // init이 Promise이면 비동기 저장소 → loading 추적
+  const isAsync = init instanceof Promise;
+  const [loading, setLoading] = createSignal(isAsync);
+
+  if (isAsync) {
+    void init.then(() => setLoading(false));
+  }
+
+  return [value, setValue, loading];
+}

package/src/hooks/usePrint.ts

@@ -0,0 +1,277 @@
+import type { JSX } from "solid-js";
+import { render } from "solid-js/web";
+import { jsPDF } from "jspdf";
+import * as htmlToImage from "html-to-image";
+import { useLoading } from "../components/feedback/loading/LoadingContext";
+import { PrintInstanceContext, type PrintInstance } from "../components/feedback/print/PrintInstanceContext";
+
+// --- Types ---
+
+export interface PrintOptions {
+  size?: string;
+  margin?: string;
+}
+
+export interface UsePrintReturn {
+  toPrinter: (factory: () => JSX.Element, options?: PrintOptions) => Promise<void>;
+  toPdf: (factory: () => JSX.Element, options?: PrintOptions) => Promise<Uint8Array>;
+}
+
+// --- Paper size constants (pt) ---
+
+const PAPER_SIZES: Partial<Record<string, [number, number]>> = {
+  a3: [841.89, 1190.55],
+  a4: [595.28, 841.89],
+  a5: [419.53, 595.28],
+  letter: [612, 792],
+  legal: [612, 1008],
+};
+
+// --- Internal helpers ---
+
+function parseDimension(dim: string): number {
+  const num = parseFloat(dim);
+  if (dim.endsWith("mm")) return num * 2.83465;
+  if (dim.endsWith("cm")) return num * 28.3465;
+  if (dim.endsWith("in")) return num * 72;
+  return num; // pt
+}
+
+function parseSize(size?: string): { width: number; height: number; orientation: "p" | "l" } {
+  const s = (size ?? "A4").toLowerCase().trim();
+  const landscape = s.includes("landscape");
+  const cleanSize = s.replace(/\s*(landscape|portrait)\s*/g, "").trim();
+
+  const paperSize = PAPER_SIZES[cleanSize];
+  if (paperSize) {
+    const [w, h] = paperSize;
+    if (landscape) return { width: h, height: w, orientation: "l" };
+    return { width: w, height: h, orientation: "p" };
+  }
+
+  // 커스텀 크기: "210mm 297mm"
+  const parts = cleanSize.split(/\s+/);
+  if (parts.length === 2) {
+    const w = parseDimension(parts[0]);
+    const h = parseDimension(parts[1]);
+    return { width: w, height: h, orientation: w > h ? "l" : "p" };
+  }
+
+  return { width: 595.28, height: 841.89, orientation: "p" };
+}
+
+function waitForImages(container: HTMLElement): Promise<void> {
+  const imgs = Array.from(container.querySelectorAll("img"));
+  return Promise.all(
+    imgs.map((img) =>
+      img.complete
+        ? Promise.resolve()
+        : new Promise<void>((resolve) => {
+            img.addEventListener("load", () => resolve(), { once: true });
+            img.addEventListener("error", () => resolve(), { once: true });
+          }),
+    ),
+  ).then(() => undefined);
+}
+
+async function renderAndWait(factory: () => JSX.Element): Promise<{ container: HTMLElement; dispose: () => void }> {
+  const container = document.createElement("div");
+  container.style.position = "fixed";
+  container.style.left = "-9999px";
+  container.style.top = "0";
+  document.body.appendChild(container);
+
+  let resolveReady: (() => void) | undefined;
+  const state = { readyCalled: false };
+
+  const readyPromise = new Promise<void>((resolve) => {
+    resolveReady = resolve;
+  });
+
+  const instance: PrintInstance = {
+    ready: () => {
+      state.readyCalled = true;
+      resolveReady?.();
+    },
+  };
+
+  const dispose = render(
+    () =>
+      PrintInstanceContext.Provider({
+        value: instance,
+        get children() {
+          return factory();
+        },
+      }),
+    container,
+  );
+
+  // SolidJS 컴포넌트는 동기적으로 마운트됨.
+  // 동기적으로 ready()가 호출되었으면 이미 state.readyCalled=true.
+  // 비동기 ready (onMount 내 async 등)를 위해 rAF 대기 후 확인.
+  await Promise.resolve();
+
+  if (!state.readyCalled) {
+    await new Promise<void>((resolve) => {
+      requestAnimationFrame(() => resolve());
+    });
+  }
+
+  if (state.readyCalled) {
+    await readyPromise;
+  }
+
+  await waitForImages(container);
+
+  return { container, dispose };
+}
+
+// --- Hook ---
+
+export function usePrint(): UsePrintReturn {
+  const busy = useLoading();
+
+  const toPrinter = async (factory: () => JSX.Element, options?: PrintOptions): Promise<void> => {
+    busy.show();
+    let container: HTMLElement | undefined;
+    let dispose: (() => void) | undefined;
+    let styleEl: HTMLStyleElement | undefined;
+
+    try {
+      const result = await renderAndWait(factory);
+      container = result.container;
+      dispose = result.dispose;
+
+      // 인쇄 대상을 visible로 전환
+      container.style.position = "static";
+      container.style.left = "auto";
+      container.classList.add("_sd-print-target");
+
+      // @media print 스타일 주입
+      styleEl = document.createElement("style");
+      styleEl.textContent = `
+        @page {
+          size: ${options?.size ?? "A4"};
+          margin: ${options?.margin ?? "0"};
+        }
+        body > ._sd-print-target { display: none; }
+        @media print {
+          html, body { -webkit-print-color-adjust: exact; background: white; }
+          body > * { display: none !important; }
+          body > ._sd-print-target { display: block !important; }
+        }
+      `;
+      document.head.appendChild(styleEl);
+
+      await new Promise<void>((resolve) => {
+        requestAnimationFrame(() => {
+          window.print();
+          resolve();
+        });
+      });
+    } finally {
+      styleEl?.remove();
+      dispose?.();
+      container?.remove();
+      busy.hide();
+    }
+  };
+
+  const toPdf = async (factory: () => JSX.Element, options?: PrintOptions): Promise<Uint8Array> => {
+    busy.show();
+    let container: HTMLElement | undefined;
+    let dispose: (() => void) | undefined;
+
+    try {
+      const result = await renderAndWait(factory);
+      container = result.container;
+      dispose = result.dispose;
+
+      const { width: pageWidth, height: pageHeight, orientation } = parseSize(options?.size);
+
+      const doc = new jsPDF(orientation, "pt", [pageWidth, pageHeight]);
+      doc.deletePage(1);
+
+      const pages = Array.from(container.querySelectorAll<HTMLElement>("[data-print-page]"));
+
+      if (pages.length > 0) {
+        // 명시적 페이지 분할
+        for (const pageEl of pages) {
+          pageEl.style.width = pageWidth + "pt";
+
+          const canvas = await htmlToImage.toCanvas(pageEl, {
+            backgroundColor: "white",
+            pixelRatio: 4,
+          });
+
+          const imgWidth = pageWidth;
+          const imgHeight = canvas.height * (pageWidth / canvas.width);
+
+          doc.addPage([pageWidth, pageHeight], orientation);
+          doc.addImage({
+            imageData: canvas,
+            x: 0,
+            y: 0,
+            width: imgWidth,
+            height: imgHeight,
+          });
+        }
+      } else {
+        // 자동 분할: 전체 콘텐츠를 페이지 높이 기준으로 슬라이스
+        // container 자체는 off-screen 스타일(position/left)을 가지므로
+        // html-to-image가 클론 시 동일 스타일을 복제하여 빈 캔버스가 생길 수 있음.
+        // 따라서 실제 콘텐츠 요소를 target으로 사용.
+        const target = (container.firstElementChild as HTMLElement | null) ?? container;
+        target.style.width = pageWidth + "pt";
+
+        const canvas = await htmlToImage.toCanvas(target, {
+          backgroundColor: "white",
+          pixelRatio: 4,
+        });
+
+        const scaleFactor = pageWidth / canvas.width;
+        const pageHeightPx = pageHeight / scaleFactor;
+        const totalPages = Math.ceil(canvas.height / pageHeightPx);
+
+        for (let i = 0; i < totalPages; i++) {
+          const sliceCanvas = document.createElement("canvas");
+          sliceCanvas.width = canvas.width;
+          sliceCanvas.height = Math.min(pageHeightPx, canvas.height - i * pageHeightPx);
+
+          const ctx = sliceCanvas.getContext("2d")!;
+          ctx.drawImage(
+            canvas,
+            0,
+            i * pageHeightPx,
+            canvas.width,
+            sliceCanvas.height,
+            0,
+            0,
+            canvas.width,
+            sliceCanvas.height,
+          );
+
+          const imgHeight = sliceCanvas.height * scaleFactor;
+
+          doc.addPage([pageWidth, pageHeight], orientation);
+          doc.addImage({
+            imageData: sliceCanvas,
+            x: 0,
+            y: 0,
+            width: pageWidth,
+            height: imgHeight,
+          });
+        }
+      }
+
+      const arrayBuffer = doc.output("arraybuffer");
+      return new Uint8Array(arrayBuffer);
+    } finally {
+      dispose?.();
+      container?.remove();
+      busy.hide();
+    }
+  };
+
+  return { toPrinter, toPdf };
+}

package/src/hooks/useRouterLink.ts

@@ -0,0 +1,64 @@
+import { useNavigate } from "@solidjs/router";
+
+export interface RouterLinkOptions {
+  /** 이동할 경로 (완성된 URL, 예: "/home/dashboard?tab=1") */
+  href: string;
+
+  /** 페이지 이동 시 전달할 데이터 (URL에 노출되지 않음) */
+  state?: Record<string, unknown>;
+
+  /** Shift+클릭 시 새 창 크기 */
+  window?: {
+    width?: number; // 기본값: 800
+    height?: number; // 기본값: 800
+  };
+}
+
+/**
+ * 라우터 네비게이션을 처리하는 hook
+ *
+ * @remarks
+ * - 일반 클릭: SPA 라우팅 (useNavigate)
+ * - Ctrl/Alt + 클릭: 새 탭
+ * - Shift + 클릭: 새 창 (window 옵션 크기 적용)
+ *
+ * @example
+ * ```tsx
+ * const navigate = useRouterLink();
+ *
+ * <ListItem onClick={navigate({ href: "/home/dashboard" })}>
+ *   대시보드
+ * </ListItem>
+ *
+ * // state 전달
+ * <ListItem onClick={navigate({
+ *   href: "/users/123",
+ *   state: { from: "list" }
+ * })}>
+ *   사용자
+ * </ListItem>
+ * ```
+ */
+export function useRouterLink(): (options: RouterLinkOptions) => (e: MouseEvent | KeyboardEvent) => void {
+  const navigate = useNavigate();
+
+  return (options: RouterLinkOptions) => {
+    return (e: MouseEvent | KeyboardEvent) => {
+      e.preventDefault();
+      e.stopPropagation();
+
+      if (e.ctrlKey || e.metaKey || e.altKey) {
+        // Ctrl/Cmd/Alt + 클릭: 새 탭
+        window.open(options.href, "_blank");
+      } else if (e.shiftKey) {
+        // Shift + 클릭: 새 창
+        const width = options.window?.width ?? 800;
+        const height = options.window?.height ?? 800;
+        window.open(options.href, "", `width=${width},height=${height}`);
+      } else {
+        // 일반 클릭: SPA 라우팅
+        navigate(options.href, options.state ? { state: options.state } : undefined);
+      }
+    };
+  };
+}