@simplysm/solid 13.0.0-beta.6

package/src/index.ts

@@ -0,0 +1,117 @@
+// form-control
+export * from "./components/form-control/Button";
+export * from "./components/form-control/select/Select";
+export * from "./components/form-control/select/SelectContext";
+export * from "./components/form-control/combobox/Combobox";
+export * from "./components/form-control/combobox/ComboboxContext";
+export * from "./components/form-control/field/TextInput";
+export * from "./components/form-control/field/NumberInput";
+export * from "./components/form-control/field/DatePicker";
+export * from "./components/form-control/field/DateTimePicker";
+export * from "./components/form-control/field/TimePicker";
+export * from "./components/form-control/field/Textarea";
+export * from "./components/form-control/field/Field.styles";
+export * from "./components/form-control/checkbox/Checkbox";
+export * from "./components/form-control/checkbox/Checkbox.styles";
+export * from "./components/form-control/checkbox/Radio";
+export * from "./components/form-control/checkbox/CheckboxGroup";
+export * from "./components/form-control/checkbox/RadioGroup";
+export * from "./components/form-control/color-picker/ColorPicker";
+export * from "./components/form-control/date-range-picker/DateRangePicker";
+export * from "./components/form-control/editor/RichTextEditor";
+export * from "./components/form-control/numpad/Numpad";
+export * from "./components/form-control/state-preset/StatePreset";
+export * from "./components/form-control/ThemeToggle";
+
+// layout
+export * from "./components/layout/FormGroup";
+export * from "./components/layout/FormTable";
+export * from "./components/layout/sidebar/Sidebar";
+export * from "./components/layout/sidebar/SidebarContext";
+export * from "./components/layout/topbar/Topbar";
+
+// data
+export * from "./components/data/Table";
+export * from "./components/data/list/List";
+export * from "./components/data/list/ListContext";
+export * from "./components/data/list/ListItem.styles";
+export * from "./components/data/Pagination";
+export * from "./components/data/sheet/DataSheet";
+export * from "./components/data/sheet/DataSheet.styles";
+export * from "./components/data/sheet/types";
+export * from "./components/data/calendar/Calendar";
+export * from "./components/data/permission-table/PermissionTable";
+export * from "./components/data/kanban/Kanban";
+export * from "./components/data/kanban/KanbanContext";
+
+// display
+export * from "./components/display/Barcode";
+export * from "./components/display/Card";
+export * from "./components/display/Echarts";
+export * from "./components/display/Icon";
+export * from "./components/display/Tag";
+export * from "./components/display/Alert";
+
+// disclosure
+export * from "./components/disclosure/Collapse";
+export * from "./components/disclosure/Dropdown";
+export * from "./components/disclosure/Dialog";
+export * from "./components/disclosure/DialogContext";
+export * from "./components/disclosure/DialogInstanceContext";
+export * from "./components/disclosure/DialogProvider";
+export * from "./components/disclosure/Tabs";
+
+// feedback
+export * from "./components/feedback/notification/NotificationContext";
+export * from "./components/feedback/notification/NotificationProvider";
+export * from "./components/feedback/notification/NotificationBanner";
+export * from "./components/feedback/notification/NotificationBell";
+
+// feedback - loading
+export * from "./components/feedback/loading/LoadingContext";
+export * from "./components/feedback/loading/LoadingProvider";
+export * from "./components/feedback/loading/LoadingContainer";
+
+// feedback - print
+export * from "./components/feedback/print/Print";
+export * from "./components/feedback/print/PrintInstanceContext";
+export * from "./components/feedback/Progress";
+
+// providers
+export * from "./providers/ConfigContext";
+export * from "./providers/InitializeProvider";
+export * from "./providers/ThemeContext";
+export * from "./providers/ServiceClientContext";
+export * from "./providers/ServiceClientProvider";
+export * from "./providers/shared-data/SharedDataContext";
+export * from "./providers/shared-data/SharedDataProvider";
+export * from "./providers/shared-data/SharedDataChangeEvent";
+
+// hooks
+export * from "./hooks/usePersisted";
+export * from "./hooks/usePrint";
+export { createControllableSignal } from "./hooks/createControllableSignal";
+export { createIMEHandler } from "./hooks/createIMEHandler";
+export { createMountTransition } from "./hooks/createMountTransition";
+export { useRouterLink } from "./hooks/useRouterLink";
+
+// styles
+export * from "./styles/tokens.styles";
+export * from "./styles/patterns.styles";
+
+// directives
+export { ripple } from "./directives/ripple";
+
+// helpers
+export { mergeStyles } from "./helpers/mergeStyles";
+export { splitSlots } from "./helpers/splitSlots";
+export { createAppStructure } from "./helpers/createAppStructure";
+export type {
+  AppStructureItem,
+  AppStructureGroupItem,
+  AppStructureLeafItem,
+  AppStructureSubPerm,
+  AppRoute,
+  AppFlatMenu,
+  AppStructure,
+} from "./helpers/createAppStructure";

package/src/providers/ConfigContext.ts

@@ -0,0 +1,59 @@
+import { createContext, useContext } from "solid-js";
+
+/**
+ * 커스텀 저장소 어댑터 인터페이스
+ *
+ * @remarks
+ * - 동기 저장소: `localStorage`, `sessionStorage` 등 그대로 전달 가능
+ * - 비동기 저장소: `getItem`이 `Promise`를 반환하는 구현체 전달
+ */
+export interface StorageAdapter {
+  getItem(key: string): string | null | Promise<string | null>;
+  setItem(key: string, value: string): void | Promise<unknown>;
+  removeItem(key: string): void | Promise<void>;
+}
+
+/**
+ * 앱 전역 설정
+ */
+export interface AppConfig {
+  /**
+   * 클라이언트 식별자 (저장소 key prefix로 사용)
+   */
+  clientName: string;
+
+  /**
+   * 커스텀 저장소 (기본값: localStorage)
+   */
+  storage?: StorageAdapter;
+}
+
+/**
+ * 앱 전역 설정 Context
+ *
+ * @example
+ * ```tsx
+ * // 앱 루트에서 Provider 설정
+ * <ConfigContext.Provider value={{ clientName: "myApp" }}>
+ *   <App />
+ * </ConfigContext.Provider>
+ *
+ * // 컴포넌트에서 사용
+ * const config = useConfig();
+ * console.log(config.clientName); // "myApp"
+ * ```
+ */
+export const ConfigContext = createContext<AppConfig>();
+
+/**
+ * 앱 전역 설정에 접근하는 훅
+ *
+ * @throws ConfigContext.Provider가 없으면 에러 발생
+ */
+export function useConfig(): AppConfig {
+  const context = useContext(ConfigContext);
+  if (!context) {
+    throw new Error("useConfig는 ConfigContext.Provider 내부에서만 사용할 수 있습니다");
+  }
+  return context;
+}

package/src/providers/InitializeProvider.tsx

@@ -0,0 +1,28 @@
+import type { ParentComponent } from "solid-js";
+import { type AppConfig, ConfigContext } from "./ConfigContext";
+import { useClipboardValueCopy } from "../hooks/useClipboardValueCopy";
+
+/**
+ * @simplysm/solid 초기화 Provider
+ *
+ * @remarks
+ * 앱 루트에서 한 번 감싸며, 다음을 초기화한다:
+ * - 앱 전역 설정 (config) Context 제공
+ * - 폼 컨트롤 value 클립보드 복사 지원
+ *
+ * @example
+ * ```tsx
+ * <InitializeProvider config={{ clientName: "myApp" }}>
+ *   <ThemeProvider>
+ *     <App />
+ *   </ThemeProvider>
+ * </InitializeProvider>
+ * ```
+ */
+export const InitializeProvider: ParentComponent<{ config: AppConfig }> = (props) => {
+  // 폼 컨트롤 value 클립보드 복사
+  useClipboardValueCopy();
+
+  // eslint-disable-next-line solid/reactivity -- config는 초기 설정값으로 변경되지 않음
+  return <ConfigContext.Provider value={props.config}>{props.children}</ConfigContext.Provider>;
+};

package/src/providers/ServiceClientContext.ts

@@ -0,0 +1,21 @@
+import { createContext, useContext } from "solid-js";
+import type { ServiceClient, ServiceConnectionConfig } from "@simplysm/service-client";
+
+export interface ServiceClientContextValue {
+  connect: (key: string, options?: Partial<ServiceConnectionConfig>) => Promise<void>;
+  close: (key: string) => Promise<void>;
+  get: (key: string) => ServiceClient;
+  isConnected: (key: string) => boolean;
+}
+
+export const ServiceClientContext = createContext<ServiceClientContextValue>();
+
+export function useServiceClient(): ServiceClientContextValue {
+  const context = useContext(ServiceClientContext);
+  if (!context) {
+    throw new Error(
+      "useServiceClient는 ServiceClientProvider 내부에서만 사용할 수 있습니다. ServiceClientProvider는 InitializeProvider와 NotificationProvider 아래에 위치해야 합니다",
+    );
+  }
+  return context;
+}

package/src/providers/ServiceClientProvider.tsx

@@ -0,0 +1,132 @@
+import { type ParentComponent, onCleanup } from "solid-js";
+import { ServiceClient, type ServiceConnectionConfig } from "@simplysm/service-client";
+import { ServiceClientContext, type ServiceClientContextValue } from "./ServiceClientContext";
+import { useConfig } from "./ConfigContext";
+import { useNotification } from "../components/feedback/notification/NotificationContext";
+
+export const ServiceClientProvider: ParentComponent = (props) => {
+  const config = useConfig();
+  const notification = useNotification();
+
+  const clientMap = new Map<string, ServiceClient>();
+  const reqProgressMap = new Map<string, string>();
+  const resProgressMap = new Map<string, string>();
+
+  onCleanup(() => {
+    for (const client of clientMap.values()) {
+      void client.close();
+    }
+    clientMap.clear();
+  });
+
+  const connect = async (key: string, options?: Partial<ServiceConnectionConfig>): Promise<void> => {
+    if (clientMap.has(key)) {
+      const existing = clientMap.get(key)!;
+      if (!existing.connected) {
+        throw new Error("이미 연결이 끊긴 클라이언트와 같은 키로 연결을 시도하였습니다.");
+      } else {
+        throw new Error("이미 연결된 클라이언트와 같은 키로 연결을 시도하였습니다.");
+      }
+    }
+
+    const defaultConfig: ServiceConnectionConfig = {
+      host: location.hostname,
+      port: Number(location.port) || (location.protocol.startsWith("https") ? 443 : 80),
+      ssl: location.protocol.startsWith("https"),
+    };
+
+    const client = new ServiceClient(config.clientName, {
+      ...defaultConfig,
+      ...options,
+    });
+
+    // 요청 진행률 이벤트
+    client.on("request-progress", (state) => {
+      const existing = reqProgressMap.get(state.uuid);
+
+      if (existing == null) {
+        const id = notification.info("요청을 전송하는 중입니다.", "0%");
+        reqProgressMap.set(state.uuid, id);
+      } else {
+        const percent = Math.round((state.completedSize / state.totalSize) * 100);
+        notification.update(existing, { message: `${percent}%` });
+      }
+
+      if (state.completedSize === state.totalSize) {
+        const id = reqProgressMap.get(state.uuid);
+        if (id != null) {
+          notification.update(
+            id,
+            {
+              title: "요청 전송 완료",
+              message: "100%",
+            },
+            { renotify: true },
+          );
+          reqProgressMap.delete(state.uuid);
+        }
+      }
+    });
+
+    // 응답 진행률 이벤트
+    client.on("response-progress", (state) => {
+      const existing = resProgressMap.get(state.uuid);
+
+      if (existing == null) {
+        const id = notification.info("응답을 전송받는 중입니다.", "0%");
+        resProgressMap.set(state.uuid, id);
+      } else {
+        const percent = Math.round((state.completedSize / state.totalSize) * 100);
+        notification.update(existing, { message: `${percent}%` });
+      }
+
+      if (state.completedSize === state.totalSize) {
+        const id = resProgressMap.get(state.uuid);
+        if (id != null) {
+          notification.update(
+            id,
+            {
+              title: "응답 전송 완료",
+              message: "100%",
+            },
+            { renotify: true },
+          );
+          resProgressMap.delete(state.uuid);
+        }
+      }
+    });
+
+    await client.connect();
+    clientMap.set(key, client);
+  };
+
+  const close = async (key: string): Promise<void> => {
+    const client = clientMap.get(key);
+    if (client) {
+      await client.close();
+      clientMap.delete(key);
+    }
+  };
+
+  const get = (key: string): ServiceClient => {
+    const client = clientMap.get(key);
+    if (!client) {
+      throw new Error(`연결하지 않은 클라이언트 키입니다. ${key}`);
+    }
+    return client;
+  };
+
+  const isConnected = (key: string): boolean => {
+    const client = clientMap.get(key);
+    return client?.connected ?? false;
+  };
+
+  const contextValue: ServiceClientContextValue = {
+    connect,
+    close,
+    get,
+    isConnected,
+  };
+
+  return <ServiceClientContext.Provider value={contextValue}>{props.children}</ServiceClientContext.Provider>;
+};

package/src/providers/ThemeContext.tsx

@@ -0,0 +1,121 @@
+import { createContext, useContext, type ParentComponent, createMemo, createEffect, onCleanup } from "solid-js";
+import { createMediaQuery } from "@solid-primitives/media";
+import { usePersisted } from "../hooks/usePersisted";
+
+/**
+ * 테마 모드
+ * - `light`: 라이트 모드
+ * - `dark`: 다크 모드
+ * - `system`: 시스템 설정 따름
+ */
+export type ThemeMode = "light" | "dark" | "system";
+
+/**
+ * 실제 적용되는 테마 (system일 때 OS 설정에 따라 결정)
+ */
+export type ResolvedTheme = "light" | "dark";
+
+interface ThemeContextValue {
+  /** 현재 테마 모드 (사용자 선택값) */
+  mode: () => ThemeMode;
+  /** 테마 모드 설정 */
+  setMode: (mode: ThemeMode) => void;
+  /** 실제 적용되는 테마 (system일 때 OS 설정 따름) */
+  resolvedTheme: () => ResolvedTheme;
+  /** 다음 모드로 순환 (light → system → dark → light) */
+  cycleMode: () => void;
+}
+
+const ThemeContext = createContext<ThemeContextValue>();
+
+/**
+ * 테마 Context에 접근하는 훅
+ *
+ * @throws ThemeProvider가 없으면 에러 발생
+ *
+ * @example
+ * ```tsx
+ * const { mode, setMode, resolvedTheme, cycleMode } = useTheme();
+ *
+ * // 현재 모드 확인
+ * console.log(mode()); // "light" | "dark" | "system"
+ *
+ * // 실제 적용 테마 확인
+ * console.log(resolvedTheme()); // "light" | "dark"
+ *
+ * // 모드 변경
+ * setMode("dark");
+ *
+ * // 순환 (토글 버튼용)
+ * cycleMode(); // light → system → dark → light
+ * ```
+ */
+export function useTheme(): ThemeContextValue {
+  const context = useContext(ThemeContext);
+  if (!context) {
+    throw new Error(
+      "useTheme는 ThemeProvider 내부에서만 사용할 수 있습니다. ThemeProvider는 InitializeProvider 아래에 위치해야 합니다",
+    );
+  }
+  return context;
+}
+
+/**
+ * 테마 Provider 컴포넌트
+ *
+ * @remarks
+ * - ConfigContext.Provider 내부에서 사용해야 함 (usePersisted 의존)
+ * - localStorage에 테마 설정 저장
+ * - `<html>` 요소에 `dark` 클래스 자동 토글
+ *
+ * @example
+ * ```tsx
+ * <ConfigContext.Provider value={{ clientName: "myApp" }}>
+ *   <ThemeProvider>
+ *     <App />
+ *   </ThemeProvider>
+ * </ConfigContext.Provider>
+ * ```
+ */
+export const ThemeProvider: ParentComponent = (props) => {
+  const [mode, setMode] = usePersisted<ThemeMode>("theme", "system");
+
+  // OS 다크모드 감지
+  const prefersDark = createMediaQuery("(prefers-color-scheme: dark)");
+
+  // 실제 적용 테마 계산
+  const resolvedTheme = createMemo<ResolvedTheme>(() => {
+    const currentMode = mode();
+    if (currentMode === "system") {
+      return prefersDark() ? "dark" : "light";
+    }
+    return currentMode;
+  });
+
+  // 다음 모드로 순환
+  const cycleMode = () => {
+    const current = mode();
+    const next: ThemeMode = current === "light" ? "system" : current === "system" ? "dark" : "light";
+    setMode(next);
+  };
+
+  // <html>에 dark 클래스 토글
+  createEffect(() => {
+    const isDark = resolvedTheme() === "dark";
+    document.documentElement.classList.toggle("dark", isDark);
+  });
+
+  // cleanup 시 dark 클래스 제거
+  onCleanup(() => {
+    document.documentElement.classList.remove("dark");
+  });
+
+  const contextValue: ThemeContextValue = {
+    mode,
+    setMode,
+    resolvedTheme,
+    cycleMode,
+  };
+
+  return <ThemeContext.Provider value={contextValue}>{props.children}</ThemeContext.Provider>;
+};

package/src/providers/shared-data/SharedDataChangeEvent.ts

@@ -0,0 +1,8 @@
+import { ServiceEventListener } from "@simplysm/service-common";
+
+export class SharedDataChangeEvent extends ServiceEventListener<
+  { name: string; filter: unknown },
+  (string | number)[] | undefined
+> {
+  readonly eventName = "SharedDataChangeEvent";
+}

package/src/providers/shared-data/SharedDataContext.ts

@@ -0,0 +1,34 @@
+import { type Accessor, createContext, useContext } from "solid-js";
+
+export interface SharedDataDefinition<T> {
+  serviceKey: string;
+  fetch: (changeKeys?: Array<string | number>) => Promise<T[]>;
+  getKey: (item: T) => string | number;
+  orderBy: [(item: T) => unknown, "asc" | "desc"][];
+  filter?: unknown;
+}
+
+export interface SharedDataAccessor<T> {
+  items: Accessor<T[]>;
+  get: (key: string | number | undefined) => T | undefined;
+  emit: (changeKeys?: Array<string | number>) => Promise<void>;
+}
+
+export type SharedDataValue<T extends Record<string, unknown>> = {
+  [K in keyof T]: SharedDataAccessor<T[K]>;
+} & {
+  wait: () => Promise<void>;
+  loading: Accessor<boolean>;
+};
+
+export const SharedDataContext = createContext<SharedDataValue<Record<string, unknown>>>();
+
+export function useSharedData<T extends Record<string, unknown> = Record<string, unknown>>(): SharedDataValue<T> {
+  const context = useContext(SharedDataContext);
+  if (!context) {
+    throw new Error(
+      "useSharedData는 SharedDataProvider 내부에서만 사용할 수 있습니다. SharedDataProvider는 ServiceClientProvider 아래에 위치해야 합니다",
+    );
+  }
+  return context as unknown as SharedDataValue<T>;
+}

package/src/providers/shared-data/SharedDataProvider.tsx

@@ -0,0 +1,149 @@
+import { type Accessor, type JSX, createMemo, createSignal, onCleanup } from "solid-js";
+import { objEqual, waitUntil } from "@simplysm/core-common";
+import {
+  SharedDataContext,
+  type SharedDataAccessor,
+  type SharedDataDefinition,
+  type SharedDataValue,
+} from "./SharedDataContext";
+import { SharedDataChangeEvent } from "./SharedDataChangeEvent";
+import { useServiceClient } from "../ServiceClientContext";
+import { useNotification } from "../../components/feedback/notification/NotificationContext";
+
+export function SharedDataProvider<T extends Record<string, unknown>>(props: {
+  definitions: { [K in keyof T]: SharedDataDefinition<T[K]> };
+  children: JSX.Element;
+}): JSX.Element {
+  const serviceClient = useServiceClient();
+  const notification = useNotification();
+
+  const [loadingCount, setLoadingCount] = createSignal(0);
+  const loading: Accessor<boolean> = () => loadingCount() > 0;
+
+  const signalMap = new Map<string, ReturnType<typeof createSignal<unknown[]>>>();
+  const memoMap = new Map<string, Accessor<Map<string | number, unknown>>>();
+  const listenerKeyMap = new Map<string, string>();
+  const versionMap = new Map<string, number>();
+
+  function ordering<TT>(data: TT[], orderByList: [(item: TT) => unknown, "asc" | "desc"][]): TT[] {
+    let result = [...data];
+    for (const orderBy of [...orderByList].reverse()) {
+      const selector = (item: TT) => orderBy[0](item) as string | number | undefined;
+      if (orderBy[1] === "desc") {
+        result = result.orderByDesc(selector);
+      } else {
+        result = result.orderBy(selector);
+      }
+    }
+    return result;
+  }
+
+  async function loadData(
+    name: string,
+    def: SharedDataDefinition<unknown>,
+    changeKeys?: Array<string | number>,
+  ): Promise<void> {
+    // CR-1: version counter로 동시 호출 시 데이터 역전 방지
+    const currentVersion = (versionMap.get(name) ?? 0) + 1;
+    versionMap.set(name, currentVersion);
+
+    setLoadingCount((c) => c + 1);
+    try {
+      const signal = signalMap.get(name);
+      if (!signal) throw new Error(`'${name}'에 대한 공유데이터 저장소가 없습니다.`);
+
+      const [, setItems] = signal;
+      const resData = await def.fetch(changeKeys);
+
+      // CR-1: 오래된 응답은 무시
+      if (versionMap.get(name) !== currentVersion) return;
+
+      if (!changeKeys) {
+        setItems(ordering(resData, def.orderBy));
+      } else {
+        setItems((prev) => {
+          const filtered = prev.filter((item) => !changeKeys.includes(def.getKey(item as never)));
+          filtered.push(...resData);
+          return ordering(filtered, def.orderBy);
+        });
+      }
+    } catch (err) {
+      // CR-2: fetch 실패 시 사용자에게 알림
+      notification.danger(
+        "공유 데이터 로드 실패",
+        err instanceof Error ? err.message : `'${name}' 데이터를 불러오는 중 오류가 발생했습니다.`,
+      );
+    } finally {
+      setLoadingCount((c) => c - 1);
+    }
+  }
+
+  async function wait(): Promise<void> {
+    // eslint-disable-next-line solid/reactivity -- waitUntil은 폴링 기반이므로 tracked scope 불필요
+    await waitUntil(() => loadingCount() <= 0);
+  }
+
+  const accessors: Record<string, SharedDataAccessor<unknown>> = {};
+
+  // eslint-disable-next-line solid/reactivity -- definitions는 초기 설정용으로 마운트 시 1회만 읽음
+  for (const [name, def] of Object.entries(props.definitions) as [string, SharedDataDefinition<unknown>][]) {
+    const [items, setItems] = createSignal<unknown[]>([]);
+    // eslint-disable-next-line solid/reactivity -- signal 참조를 Map에 저장하는 것은 반응성 접근이 아님
+    signalMap.set(name, [items, setItems]);
+
+    const itemMap = createMemo(() => {
+      const map = new Map<string | number, unknown>();
+      for (const item of items()) {
+        map.set(def.getKey(item as never), item);
+      }
+      return map;
+    });
+    // eslint-disable-next-line solid/reactivity -- memo 참조를 Map에 저장하는 것은 반응성 접근이 아님
+    memoMap.set(name, itemMap);
+
+    const client = serviceClient.get(def.serviceKey);
+    void client
+      .addEventListener(SharedDataChangeEvent, { name, filter: def.filter }, async (changeKeys) => {
+        await loadData(name, def, changeKeys);
+      })
+      .then((key) => {
+        listenerKeyMap.set(name, key);
+      });
+
+    void loadData(name, def);
+
+    accessors[name] = {
+      items,
+      get: (key: string | number | undefined) => {
+        if (key === undefined) return undefined;
+        return itemMap().get(key);
+      },
+      emit: async (changeKeys?: Array<string | number>) => {
+        await client.emitToServer(
+          SharedDataChangeEvent,
+          (info) => info.name === name && objEqual(info.filter, def.filter),
+          changeKeys,
+        );
+      },
+    };
+  }
+
+  onCleanup(() => {
+    for (const [name] of Object.entries(props.definitions)) {
+      const listenerKey = listenerKeyMap.get(name);
+      if (listenerKey != null) {
+        const def = (props.definitions as Record<string, SharedDataDefinition<unknown>>)[name];
+        const client = serviceClient.get(def.serviceKey);
+        void client.removeEventListener(listenerKey);
+      }
+    }
+  });
+
+  const contextValue = {
+    ...accessors,
+    wait,
+    loading,
+  } as SharedDataValue<Record<string, unknown>>;
+
+  return <SharedDataContext.Provider value={contextValue}>{props.children}</SharedDataContext.Provider>;
+}