@simplysm/solid 13.0.0-beta.6

package/src/components/layout/topbar/TopbarUser.tsx

@@ -0,0 +1,96 @@
+import { createSignal, For, type JSX, type ParentComponent, Show, splitProps } from "solid-js";
+import { IconChevronDown } from "@tabler/icons-solidjs";
+import clsx from "clsx";
+import { Icon } from "../../display/Icon";
+import { twMerge } from "tailwind-merge";
+import { Button } from "../../form-control/Button";
+import { Dropdown } from "../../disclosure/Dropdown";
+import { List } from "../../data/list/List";
+import { ListItem } from "../../data/list/ListItem";
+
+const wrapperBaseClass = clsx("flex items-center");
+const buttonContentClass = clsx("flex items-center", "gap-1");
+
+export interface TopbarUserMenu {
+  title: string;
+  onClick: () => void;
+}
+
+export interface TopbarUserProps extends Omit<JSX.HTMLAttributes<HTMLDivElement>, "onClick"> {
+  /**
+   * 드롭다운 메뉴 (있을 때만 드롭다운 표시)
+   */
+  menus?: TopbarUserMenu[];
+
+  /**
+   * 사용자 정보 영역 (커스터마이징)
+   */
+  children: JSX.Element;
+}
+
+/**
+ * Topbar 사용자 정보 컴포넌트
+ *
+ * @remarks
+ * - children으로 사용자 정보 표시 커스터마이징
+ * - menus가 있을 때 클릭 시 Dropdown으로 메뉴 표시
+ * - Button의 ghost 스타일 사용
+ *
+ * @example
+ * ```tsx
+ * <TopbarUser menus={[
+ *   { title: "프로필", onClick: () => navigate("/profile") },
+ *   { title: "로그아웃", onClick: handleLogout },
+ * ]}>
+ *   <span>사용자명</span>
+ * </TopbarUser>
+ * ```
+ */
+export const TopbarUser: ParentComponent<TopbarUserProps> = (props) => {
+  const [local, rest] = splitProps(props, ["children", "class", "menus"]);
+
+  const [open, setOpen] = createSignal(false);
+  let buttonRef: HTMLButtonElement | undefined;
+
+  const hasMenus = () => local.menus !== undefined && local.menus.length > 0;
+
+  const handleClick = () => {
+    if (hasMenus()) {
+      setOpen((v) => !v);
+    }
+  };
+
+  const handleMenuClick = (menu: TopbarUserMenu) => {
+    setOpen(false);
+    menu.onClick();
+  };
+
+  const getClassName = () => twMerge(wrapperBaseClass, local.class);
+
+  return (
+    <div {...rest} data-topbar-user class={getClassName()}>
+      <Button
+        ref={buttonRef}
+        variant="ghost"
+        onClick={handleClick}
+        class={buttonContentClass}
+        aria-haspopup={hasMenus() ? "menu" : undefined}
+        aria-expanded={hasMenus() ? open() : undefined}
+      >
+        {local.children}
+        <Show when={hasMenus()}>
+          <Icon icon={IconChevronDown} size="1em" class={clsx("transition-transform", open() && "rotate-180")} />
+        </Show>
+      </Button>
+      <Show when={hasMenus()}>
+        <Dropdown triggerRef={() => buttonRef} open={open()} onOpenChange={setOpen}>
+          <List inset>
+            <For each={local.menus}>
+              {(menu) => <ListItem onClick={() => handleMenuClick(menu)}>{menu.title}</ListItem>}
+            </For>
+          </List>
+        </Dropdown>
+      </Show>
+    </div>
+  );
+};

package/src/directives/ripple.ts

@@ -0,0 +1,151 @@
+import type { Accessor } from "solid-js";
+import { onCleanup } from "solid-js";
+
+declare module "solid-js" {
+  namespace JSX {
+    interface Directives {
+      ripple: boolean;
+    }
+  }
+}
+
+/**
+ * 인터랙티브 요소에 ripple 효과를 추가하는 directive.
+ *
+ * @remarks
+ * - 내부에 ripple-container div를 생성하여 overflow: hidden 적용 (부모 요소 영향 없음)
+ * - 요소의 position이 `static`일 때만 `relative`로 변경 (cleanup 시 원래 값 복원)
+ * - 단일 ripple 모드: 새 클릭 시 이전 ripple 제거
+ * - `prefers-reduced-motion: reduce` 설정 시 ripple 비활성화
+ *
+ * @example
+ * ```tsx
+ * <button use:ripple={!props.disabled}>Click me</button>
+ * ```
+ */
+export function ripple(el: HTMLElement, accessor: Accessor<boolean>): void {
+  let containerEl: HTMLDivElement | undefined;
+  let indicatorEl: HTMLDivElement | undefined;
+  let rafId: number | undefined;
+  let originalPosition: string | undefined;
+  let positionApplied = false;
+
+  const prefersReducedMotion = window.matchMedia("(prefers-reduced-motion: reduce)");
+
+  // ripple container 생성 (내부에서 overflow: hidden 처리)
+  const ensureContainer = () => {
+    if (containerEl) return containerEl;
+
+    containerEl = document.createElement("div");
+    containerEl.style.cssText =
+      "position: absolute; top: 0; left: 0; right: 0; bottom: 0; overflow: hidden; pointer-events: none; border-radius: inherit;";
+    el.appendChild(containerEl);
+
+    return containerEl;
+  };
+
+  const onPointerDown = (event: PointerEvent) => {
+    if (!accessor()) return;
+    if (prefersReducedMotion.matches) return;
+
+    // position 확인 및 적용 (container 배치를 위해 필요)
+    if (getComputedStyle(el).position === "static") {
+      if (!positionApplied) originalPosition = el.style.position;
+      el.style.position = "relative";
+      positionApplied = true;
+    }
+
+    const container = ensureContainer();
+
+    if (indicatorEl) {
+      indicatorEl.remove();
+      indicatorEl = undefined;
+    }
+
+    const rect = el.getBoundingClientRect();
+    const x = event.clientX - rect.left;
+    const y = event.clientY - rect.top;
+
+    // 클릭 위치에서 가장 먼 모서리까지의 거리를 반지름으로 사용
+    const maxDist = Math.max(
+      Math.hypot(x, y),
+      Math.hypot(rect.width - x, y),
+      Math.hypot(x, rect.height - y),
+      Math.hypot(rect.width - x, rect.height - y),
+    );
+    const size = maxDist * 2;
+
+    indicatorEl = document.createElement("div");
+    indicatorEl.classList.add(
+      "absolute",
+      "pointer-events-none",
+      "rounded-full",
+      "bg-black/20",
+      "dark:bg-white/20",
+      "transition-[transform,opacity]",
+      "duration-500",
+      "ease-in-out",
+    );
+    Object.assign(indicatorEl.style, {
+      width: `${size}px`,
+      height: `${size}px`,
+      top: `${y - size / 2}px`,
+      left: `${x - size / 2}px`,
+      transform: "scale(0)",
+      opacity: "1",
+    });
+
+    indicatorEl.addEventListener("transitionend", (e) => {
+      if (e.propertyName === "opacity" && indicatorEl && indicatorEl.style.opacity === "0") {
+        indicatorEl.remove();
+        indicatorEl = undefined;
+      }
+    });
+
+    container.appendChild(indicatorEl);
+
+    rafId = requestAnimationFrame(() => {
+      rafId = undefined;
+      if (indicatorEl) {
+        indicatorEl.style.transform = "scale(1)";
+      }
+    });
+  };
+
+  const onPointerUp = () => {
+    if (indicatorEl) {
+      indicatorEl.style.opacity = "0";
+    }
+  };
+
+  el.addEventListener("pointerdown", onPointerDown);
+  el.addEventListener("pointerup", onPointerUp);
+  el.addEventListener("pointercancel", onPointerUp);
+  el.addEventListener("pointerleave", onPointerUp);
+
+  onCleanup(() => {
+    el.removeEventListener("pointerdown", onPointerDown);
+    el.removeEventListener("pointerup", onPointerUp);
+    el.removeEventListener("pointercancel", onPointerUp);
+    el.removeEventListener("pointerleave", onPointerUp);
+
+    if (rafId !== undefined) {
+      cancelAnimationFrame(rafId);
+      rafId = undefined;
+    }
+
+    if (indicatorEl) {
+      indicatorEl.remove();
+      indicatorEl = undefined;
+    }
+
+    if (containerEl) {
+      containerEl.remove();
+      containerEl = undefined;
+    }
+
+    if (positionApplied && originalPosition !== undefined) {
+      el.style.position = originalPosition;
+    }
+  });
+}

package/src/helpers/createAppStructure.ts

@@ -0,0 +1,183 @@
+import { type Accessor, createMemo } from "solid-js";
+import type { Component } from "solid-js";
+import type { IconProps } from "@tabler/icons-solidjs";
+import type { SidebarMenuItem } from "../components/layout/sidebar/SidebarMenu";
+
+// ── 입력 타입 ──
+
+export interface AppStructureGroupItem<TModule> {
+  code: string;
+  title: string;
+  icon?: Component<IconProps>;
+  modules?: TModule[];
+  requiredModules?: TModule[];
+  children: AppStructureItem<TModule>[];
+}
+
+export interface AppStructureLeafItem<TModule> {
+  code: string;
+  title: string;
+  icon?: Component<IconProps>;
+  modules?: TModule[];
+  requiredModules?: TModule[];
+  component?: Component;
+  perms?: ("use" | "edit")[];
+  subPerms?: AppStructureSubPerm<TModule>[];
+  isNotMenu?: boolean;
+}
+
+export type AppStructureItem<TModule> = AppStructureGroupItem<TModule> | AppStructureLeafItem<TModule>;
+
+export interface AppStructureSubPerm<TModule> {
+  code: string;
+  title: string;
+  modules?: TModule[];
+  requiredModules?: TModule[];
+  perms: ("use" | "edit")[];
+}
+
+// ── 출력 타입 ──
+
+export interface AppRoute {
+  path: string;
+  component: Component;
+}
+
+export interface AppFlatMenu {
+  titleChain: string[];
+  href: string;
+}
+
+export interface AppStructure<TModule> {
+  items: AppStructureItem<TModule>[];
+  routes: AppRoute[];
+  usableMenus: Accessor<SidebarMenuItem[]>;
+  usableFlatMenus: Accessor<AppFlatMenu[]>;
+  permRecord: Accessor<Record<string, boolean>>;
+}
+
+// ── 내부 헬퍼 ──
+
+function isGroupItem<TModule>(item: AppStructureItem<TModule>): item is AppStructureGroupItem<TModule> {
+  return "children" in item;
+}
+
+function checkModules<TModule>(
+  modules: TModule[] | undefined,
+  requiredModules: TModule[] | undefined,
+  usableModules: TModule[] | undefined,
+): boolean {
+  if (usableModules === undefined) return true;
+
+  if (modules !== undefined && modules.length > 0) {
+    if (!modules.some((m) => usableModules.includes(m))) return false;
+  }
+
+  if (requiredModules !== undefined && requiredModules.length > 0) {
+    if (!requiredModules.every((m) => usableModules.includes(m))) return false;
+  }
+
+  return true;
+}
+
+function collectRoutes<TModule>(items: AppStructureItem<TModule>[], parentCodes: string[], routes: AppRoute[]): void {
+  for (const item of items) {
+    const codes = [...parentCodes, item.code];
+
+    if (isGroupItem(item)) {
+      collectRoutes(item.children, codes, routes);
+    } else if (item.component !== undefined) {
+      routes.push({
+        path: "/" + codes.join("/"),
+        component: item.component,
+      });
+    }
+  }
+}
+
+function extractRoutes<TModule>(items: AppStructureItem<TModule>[]): AppRoute[] {
+  const routes: AppRoute[] = [];
+  for (const top of items) {
+    if (isGroupItem(top)) {
+      collectRoutes(top.children, [], routes);
+    }
+  }
+  return routes;
+}
+
+function buildMenus<TModule>(
+  items: AppStructureItem<TModule>[],
+  basePath: string,
+  usableModules: TModule[] | undefined,
+  permRecord: Record<string, boolean>,
+): SidebarMenuItem[] {
+  const result: SidebarMenuItem[] = [];
+
+  for (const item of items) {
+    if (!checkModules(item.modules, item.requiredModules, usableModules)) continue;
+
+    const href = basePath + "/" + item.code;
+
+    if (isGroupItem(item)) {
+      const children = buildMenus(item.children, href, usableModules, permRecord);
+      if (children.length > 0) {
+        result.push({ title: item.title, icon: item.icon, children });
+      }
+    } else {
+      if (item.isNotMenu) continue;
+      if (item.perms?.includes("use") && !permRecord[href + "/use"]) continue;
+
+      result.push({ title: item.title, href, icon: item.icon });
+    }
+  }
+
+  return result;
+}
+
+function flattenMenus(menus: SidebarMenuItem[], titleChain: string[] = []): AppFlatMenu[] {
+  const result: AppFlatMenu[] = [];
+
+  for (const menu of menus) {
+    const chain = [...titleChain, menu.title];
+
+    if (menu.children !== undefined) {
+      result.push(...flattenMenus(menu.children, chain));
+    } else if (menu.href !== undefined) {
+      result.push({ titleChain: chain, href: menu.href });
+    }
+  }
+
+  return result;
+}
+
+// ── 메인 함수 ──
+
+export function createAppStructure<TModule>(opts: {
+  items: AppStructureItem<TModule>[];
+  usableModules?: Accessor<TModule[] | undefined>;
+  permRecord?: Accessor<Record<string, boolean>>;
+}): AppStructure<TModule> {
+  const permRecord = () => opts.permRecord?.() ?? {};
+
+  const routes = extractRoutes(opts.items);
+
+  const usableMenus = createMemo(() => {
+    const menus: SidebarMenuItem[] = [];
+    for (const top of opts.items) {
+      if (isGroupItem(top)) {
+        menus.push(...buildMenus(top.children, "/" + top.code, opts.usableModules?.(), permRecord()));
+      }
+    }
+    return menus;
+  });
+
+  const usableFlatMenus = createMemo(() => flattenMenus(usableMenus()));
+
+  return {
+    items: opts.items,
+    routes,
+    usableMenus,
+    usableFlatMenus,
+    permRecord,
+  };
+}

package/src/helpers/mergeStyles.ts

@@ -0,0 +1,55 @@
+import { type JSX } from "solid-js";
+
+/**
+ * CSS 스타일을 병합하는 유틸리티 함수
+ *
+ * @remarks
+ * - string과 object 형태의 스타일을 모두 지원
+ * - object 형태는 하나의 객체로 병합 (나중 값이 우선)
+ * - string은 파싱하여 병합
+ * - undefined는 무시
+ *
+ * @example
+ * ```tsx
+ * // Object 병합
+ * mergeStyles({ color: "red" }, { background: "blue" })
+ * // => { color: "red", background: "blue" }
+ *
+ * // String 병합
+ * mergeStyles("color: red;", "background: blue;")
+ * // => { color: "red", background: "blue" }
+ *
+ * // Mixed 병합
+ * mergeStyles({ color: "red" }, "background: blue;")
+ * // => { color: "red", background: "blue" }
+ * ```
+ */
+export function mergeStyles(...styles: (JSX.CSSProperties | string | undefined)[]): JSX.CSSProperties {
+  const result: Record<string, string> = {};
+
+  for (const style of styles) {
+    if (style === undefined) continue;
+
+    if (typeof style === "string") {
+      // CSS string 파싱
+      const declarations = style.split(";").filter((s) => s.trim());
+      for (const declaration of declarations) {
+        const colonIndex = declaration.indexOf(":");
+        if (colonIndex === -1) continue;
+
+        const property = declaration.slice(0, colonIndex).trim();
+        const value = declaration.slice(colonIndex + 1).trim();
+        if (property && value) {
+          // kebab-case를 camelCase로 변환
+          const camelProperty = property.replace(/-([a-z])/g, (_, letter: string) => letter.toUpperCase());
+          result[camelProperty] = value;
+        }
+      }
+    } else {
+      // Object 스타일 병합
+      Object.assign(result, style);
+    }
+  }
+
+  return result as JSX.CSSProperties;
+}

package/src/helpers/splitSlots.ts

@@ -0,0 +1,48 @@
+import "@simplysm/core-common";
+import { type Accessor, createMemo } from "solid-js";
+import type { JSX } from "solid-js/jsx-runtime";
+
+/**
+ * children을 slot 키 기준으로 분리하여 반환합니다.
+ * SolidJS의 splitProps와 유사한 패턴으로 동작합니다.
+ *
+ * @param resolved - children(() => props.children)으로 생성된 resolved children
+ * @param keys - 분리할 slot 키 배열 (camelCase, data 속성과 매칭)
+ * @returns [slots, content] - slots는 각 키별 HTMLElement[], content는 나머지 JSX.Element[]
+ *
+ * @example
+ * ```tsx
+ * const resolved = children(() => props.children);
+ * const [slots, content] = splitSlots(resolved, ["selectHeader", "selectAction"] as const);
+ *
+ * // JSX에서 사용
+ * <div>{slots().selectHeader.single()}</div>
+ * <div>{content()}</div>
+ * ```
+ */
+export function splitSlots<K extends string>(
+  resolved: { toArray: () => unknown[] },
+  keys: readonly K[],
+): [Accessor<Record<K, HTMLElement[]>>, Accessor<JSX.Element[]>] {
+  const memo = createMemo(() => {
+    const arr = resolved.toArray();
+    const result = Object.fromEntries(keys.map((k) => [k, []])) as unknown as Record<K, HTMLElement[]>;
+    const content: JSX.Element[] = [];
+
+    for (const c of arr) {
+      if (c instanceof HTMLElement) {
+        const matchedKey = keys.find((k) => k in c.dataset);
+        if (matchedKey !== undefined) {
+          result[matchedKey].push(c);
+          continue;
+        }
+      }
+      content.push(c as JSX.Element);
+    }
+
+    return { result, content };
+  });
+
+  // eslint-disable-next-line solid/reactivity -- 반환된 accessor는 JSX나 tracked scope에서 호출됨
+  return [() => memo().result, () => memo().content];
+}

package/src/hooks/createControllableSignal.ts

@@ -0,0 +1,63 @@
+import { createSignal, createEffect } from "solid-js";
+
+/**
+ * 함수 타입을 제한하는 유틸리티 타입
+ * 함수 타입이 전달되면 never로 변환되어 컴파일 타임 에러 발생
+ *
+ * @remarks
+ * 함수를 저장해야 할 경우 객체로 감싸기: `createControllableSignal<{ fn: () => void }>(...)`
+ */
+type NotFunction<T> = T extends (...args: unknown[]) => unknown ? never : T;
+
+/**
+ * Controlled/Uncontrolled 패턴을 지원하는 signal hook
+ *
+ * @remarks
+ * - `onChange`가 제공되면 controlled 모드: 외부에서 값 관리
+ * - `onChange`가 없으면 uncontrolled 모드: 내부 상태 사용
+ * - 함수형 setter 지원: `setValue(prev => !prev)`
+ *
+ * @example
+ * ```tsx
+ * // Controlled 모드 (onOpenChange 제공)
+ * const [open, setOpen] = createControllableSignal({
+ *   value: () => props.open ?? false,
+ *   onChange: () => props.onOpenChange,
+ * });
+ *
+ * // Uncontrolled 모드 (onOpenChange 미제공)
+ * const [open, setOpen] = createControllableSignal({
+ *   value: () => props.open ?? false,
+ *   onChange: () => undefined,
+ * });
+ *
+ * // 함수형 setter
+ * setOpen(prev => !prev);
+ * ```
+ */
+export function createControllableSignal<T>(options: {
+  value: () => T & NotFunction<T>;
+  onChange: () => ((value: T) => void) | undefined;
+}) {
+  const [internalValue, setInternalValue] = createSignal<T>(options.value());
+
+  // props 변경 시 내부 상태 동기화 (props 우선)
+  createEffect(() => {
+    const propValue = options.value();
+    setInternalValue(() => propValue);
+  });
+
+  const isControlled = () => options.onChange() !== undefined;
+  const value = () => (isControlled() ? options.value() : internalValue());
+  const setValue = (newValue: T | ((prev: T) => T)) => {
+    const resolved = typeof newValue === "function" ? (newValue as (prev: T) => T)(value()) : newValue;
+
+    if (isControlled()) {
+      options.onChange()?.(resolved);
+    } else {
+      setInternalValue(() => resolved);
+    }
+  };
+
+  return [value, setValue] as const;
+}

package/src/hooks/createIMEHandler.ts

@@ -0,0 +1,65 @@
+import { createSignal, onCleanup } from "solid-js";
+
+/**
+ * IME 조합 처리 훅
+ *
+ * @remarks
+ * 한글 등 IME 조합 중 onValueChange를 지연하여 DOM 재생성(조합 끊김)을 방지합니다.
+ * - 조합 중: composingValue만 업데이트 (content div 표시용)
+ * - 조합 완료(compositionEnd): setTimeout(0)으로 지연 후 setValue 호출
+ * - cleanup: flushComposition으로 미커밋 값 즉시 커밋
+ *
+ * @param setValue - 값 커밋 함수
+ * @returns IME 핸들러 객체
+ */
+export function createIMEHandler(setValue: (value: string) => void) {
+  const [composingValue, setComposingValue] = createSignal<string | null>(null);
+  let compositionFlushTimer: ReturnType<typeof setTimeout> | undefined;
+
+  function flushComposition(): void {
+    if (compositionFlushTimer != null) {
+      clearTimeout(compositionFlushTimer);
+      compositionFlushTimer = undefined;
+    }
+    const pending = composingValue();
+    if (pending != null) {
+      setComposingValue(null);
+      setValue(pending);
+    }
+  }
+
+  function handleCompositionStart(): void {
+    if (compositionFlushTimer != null) {
+      clearTimeout(compositionFlushTimer);
+      compositionFlushTimer = undefined;
+    }
+  }
+
+  function handleInput(value: string, isComposing: boolean): void {
+    if (isComposing || compositionFlushTimer != null) {
+      setComposingValue(value);
+      return;
+    }
+    setComposingValue(null);
+    setValue(value);
+  }
+
+  function handleCompositionEnd(value: string): void {
+    setComposingValue(value);
+    compositionFlushTimer = setTimeout(() => {
+      compositionFlushTimer = undefined;
+      setComposingValue(null);
+      setValue(value);
+    }, 0);
+  }
+
+  onCleanup(() => flushComposition());
+
+  return {
+    composingValue,
+    handleCompositionStart,
+    handleInput,
+    handleCompositionEnd,
+    flushComposition,
+  };
+}