@simplysm/solid 13.0.33 → 13.0.35

package/src/components/disclosure/DialogContext.ts

@@ -1,40 +1,69 @@
 import { createContext, useContext, type Accessor, type JSX } from "solid-js";
 
+/** 다이얼로그 기본 설정 */
 export interface DialogDefaults {
+  /** ESC 키로 닫기 허용 */
   closeOnEscape?: boolean;
+  /** 백드롭 클릭으로 닫기 허용 */
   closeOnBackdrop?: boolean;
 }
 
+/** 다이얼로그 기본 설정 Context */
 export const DialogDefaultsContext = createContext<Accessor<DialogDefaults>>();
 
+/** 프로그래매틱 다이얼로그 옵션 */
 export interface DialogShowOptions {
+  /** 다이얼로그 제목 */
   title: string;
+  /** 헤더 숨김 */
   hideHeader?: boolean;
+  /** 닫기 버튼 표시 */
   closable?: boolean;
+  /** 백드롭 클릭으로 닫기 */
   closeOnBackdrop?: boolean;
+  /** ESC 키로 닫기 */
   closeOnEscape?: boolean;
+  /** 크기 조절 가능 */
   resizable?: boolean;
+  /** 드래그 이동 가능 */
   movable?: boolean;
+  /** 플로팅 모드 (우하단 고정) */
   float?: boolean;
+  /** 전체 화면 채우기 */
   fill?: boolean;
+  /** 초기 너비 (px) */
   width?: number;
+  /** 초기 높이 (px) */
   height?: number;
+  /** 최소 너비 (px) */
   minWidth?: number;
+  /** 최소 높이 (px) */
   minHeight?: number;
+  /** 플로팅 위치 */
   position?: "bottom-right" | "top-right";
+  /** 헤더 커스텀 스타일 */
   headerStyle?: JSX.CSSProperties | string;
+  /** 닫기 전 확인 함수 (false 반환 시 닫기 취소) */
   canDeactivate?: () => boolean;
 }
 
+/** 프로그래매틱 다이얼로그 Context 값 */
 export interface DialogContextValue {
+  /** 다이얼로그를 열고, 닫힐 때까지 대기하여 결과를 반환 */
   show<T = undefined>(
     factory: () => JSX.Element,
     options: DialogShowOptions,
   ): Promise<T | undefined>;
 }
 
+/** 프로그래매틱 다이얼로그 Context */
 export const DialogContext = createContext<DialogContextValue>();
 
+/**
+ * 프로그래매틱 다이얼로그에 접근하는 훅
+ *
+ * @throws DialogProvider가 없으면 에러 발생
+ */
 export function useDialog(): DialogContextValue {
   const ctx = useContext(DialogContext);
   if (!ctx) throw new Error("useDialog는 DialogProvider 내부에서만 사용할 수 있습니다");

package/src/components/disclosure/DialogInstanceContext.ts

@@ -1,11 +1,25 @@
 import { createContext, useContext } from "solid-js";
 
+/**
+ * 다이얼로그 인스턴스 (프로그래매틱 다이얼로그 내부에서 사용)
+ */
 export interface DialogInstance<TResult> {
+  /** 다이얼로그 닫기 (result는 show()의 Promise로 전달) */
   close: (result?: TResult) => void;
 }
 
+/** 다이얼로그 인스턴스 Context */
 export const DialogInstanceContext = createContext<DialogInstance<unknown>>();
 
+/**
+ * 다이얼로그 인스턴스에 접근하는 훅
+ *
+ * @remarks
+ * DialogProvider.show()로 열린 다이얼로그 내부에서만 값이 존재한다.
+ * Provider 외부에서 호출하면 undefined를 반환한다.
+ *
+ * @returns DialogInstance 또는 undefined (Provider 외부)
+ */
 export function useDialogInstance<TResult = undefined>(): DialogInstance<TResult> | undefined {
   return useContext(DialogInstanceContext) as DialogInstance<TResult> | undefined;
 }

package/src/components/feedback/busy/BusyContext.ts

@@ -1,16 +1,34 @@
 import { createContext, useContext, type Accessor } from "solid-js";
 
+/**
+ * Busy 오버레이 표시 방식
+ * - `spinner`: 전체 화면 스피너
+ * - `bar`: 상단 프로그레스 바
+ */
 export type BusyVariant = "spinner" | "bar";
 
+/**
+ * Busy 오버레이 Context 값
+ */
 export interface BusyContextValue {
+  /** 현재 표시 방식 */
   variant: Accessor<BusyVariant>;
+  /** 오버레이 표시 (중첩 호출 가능, 호출 횟수만큼 hide 필요) */
   show: (message?: string) => void;
+  /** 오버레이 숨김 (모든 show에 대응하는 hide 호출 후 실제 숨김) */
   hide: () => void;
+  /** 프로그레스 바 진행률 설정 (0~100, undefined면 indeterminate) */
   setProgress: (percent: number | undefined) => void;
 }
 
+/** Busy 오버레이 Context */
 export const BusyContext = createContext<BusyContextValue>();
 
+/**
+ * Busy 오버레이에 접근하는 훅
+ *
+ * @throws BusyProvider가 없으면 에러 발생
+ */
 export function useBusy(): BusyContextValue {
   const context = useContext(BusyContext);
   if (!context) {

package/src/components/feedback/busy/BusyProvider.tsx

@@ -6,10 +6,20 @@ import { BusyContainer } from "./BusyContainer";
 
 const overlayClass = clsx("fixed left-0 top-0", "h-screen w-screen", "overflow-hidden");
 
+/** BusyProvider 설정 */
 export interface BusyProviderProps {
+  /** 표시 방식 (기본값: `"spinner"`) */
   variant?: BusyVariant;
 }
 
+/**
+ * Busy 오버레이 Provider
+ *
+ * @remarks
+ * - show/hide는 중첩 호출 가능 (내부 카운터로 관리)
+ * - Portal로 렌더링하여 항상 최상위에 표시
+ * - 독립적으로 동작 (다른 Provider 의존성 없음)
+ */
 export const BusyProvider: ParentComponent<BusyProviderProps> = (props) => {
   const [busyCount, setBusyCount] = createSignal(0);
   const [message, setMessage] = createSignal<string | undefined>();

package/src/components/feedback/notification/NotificationContext.ts

@@ -1,30 +1,53 @@
 import { createContext, useContext, type Accessor } from "solid-js";
 
+/** 알림 테마 */
 export type NotificationTheme = "info" | "success" | "warning" | "danger";
 
+/** 알림 액션 버튼 */
 export interface NotificationAction {
+  /** 버튼 텍스트 */
   label: string;
+  /** 클릭 핸들러 */
   onClick: () => void;
 }
 
+/** 알림 항목 */
 export interface NotificationItem {
+  /** 고유 식별자 */
   id: string;
+  /** 테마 (info, success, warning, danger) */
   theme: NotificationTheme;
+  /** 알림 제목 */
   title: string;
+  /** 알림 메시지 (선택) */
   message?: string;
+  /** 액션 버튼 (선택) */
   action?: NotificationAction;
+  /** 생성 시각 */
   createdAt: Date;
+  /** 읽음 여부 */
   read: boolean;
 }
 
+/** 알림 생성 옵션 */
 export interface NotificationOptions {
+  /** 알림에 표시할 액션 버튼 */
   action?: NotificationAction;
 }
 
+/** 알림 수정 옵션 */
 export interface NotificationUpdateOptions {
+  /** true면 읽은 알림을 다시 읽지 않음 상태로 변경 (배너 재표시) */
   renotify?: boolean;
 }
 
+/**
+ * 알림 시스템 Context 값
+ *
+ * @remarks
+ * 알림 생성, 수정, 삭제 및 읽음 관리를 위한 메서드 제공.
+ * 최대 50개까지 유지되며 초과 시 오래된 항목부터 제거.
+ */
 export interface NotificationContextValue {
   // 상태
   items: Accessor<NotificationItem[]>;
@@ -60,8 +83,14 @@ export interface NotificationContextValue {
   clear: () => void;
 }
 
+/** 알림 시스템 Context */
 export const NotificationContext = createContext<NotificationContextValue>();
 
+/**
+ * 알림 시스템에 접근하는 훅
+ *
+ * @throws NotificationProvider가 없으면 에러 발생
+ */
 export function useNotification(): NotificationContextValue {
   const context = useContext(NotificationContext);
   if (!context) {

package/src/components/feedback/notification/NotificationProvider.tsx

@@ -11,6 +11,15 @@ import { useLogger } from "../../../hooks/useLogger";
 
 const MAX_ITEMS = 50;
 
+/**
+ * 알림 시스템 Provider
+ *
+ * @remarks
+ * - 최대 50개 알림 유지 (초과 시 오래된 항목 자동 제거)
+ * - 읽지 않은 최신 알림을 배너로 표시
+ * - 스크린 리더용 aria-live region 포함
+ * - LoggerProvider가 있으면 에러 알림을 로거에도 기록
+ */
 export const NotificationProvider: ParentComponent = (props) => {
   const logger = useLogger();
   const [items, setItems] = createSignal<NotificationItem[]>([]);

package/src/hooks/useLogger.ts

@@ -3,20 +3,24 @@ import { useLogAdapter, type LogAdapter } from "../providers/LoggerContext";
 
 type LogLevel = Parameters<LogAdapter["write"]>[0];
 
-interface Logger {
+export interface Logger {
   log: (...args: unknown[]) => void;
   info: (...args: unknown[]) => void;
   warn: (...args: unknown[]) => void;
   error: (...args: unknown[]) => void;
+  /** LogAdapter를 나중에 주입. LoggerProvider 내부에서만 사용 가능 */
+  configure: (adapter: LogAdapter) => void;
 }
 
 export function useLogger(): Logger {
-  const logAdapter = useLogAdapter();
+  const loggerCtx = useLogAdapter();
 
   const createLogFunction = (level: LogLevel) => {
     return (...args: unknown[]) => {
-      if (logAdapter) {
-        void logAdapter.write(level, ...args);
+      // Lazy read: 매 호출마다 현재 adapter를 확인
+      const adapter = loggerCtx?.adapter();
+      if (adapter) {
+        void adapter.write(level, ...args);
       } else {
         (consola as any)[level](...args);
       }
@@ -28,5 +32,11 @@ export function useLogger(): Logger {
     info: createLogFunction("info"),
     warn: createLogFunction("warn"),
     error: createLogFunction("error"),
+    configure: (adapter: LogAdapter) => {
+      if (!loggerCtx) {
+        throw new Error("configure()는 LoggerProvider 내부에서만 사용할 수 있습니다");
+      }
+      loggerCtx.configure(adapter);
+    },
   };
 }

package/src/hooks/useSyncConfig.ts

@@ -1,4 +1,4 @@
-import { type Accessor, type Setter, createEffect, createSignal } from "solid-js";
+import { type Accessor, type Setter, createEffect, createSignal, untrack } from "solid-js";
 import { useConfig } from "../providers/ConfigContext";
 import { useSyncStorage } from "../providers/SyncStorageContext";
 
@@ -8,6 +8,8 @@ import { useSyncStorage } from "../providers/SyncStorageContext";
  * Uses `SyncStorageProvider` storage if available, otherwise falls back to `localStorage`.
  * Designed for data that should persist and sync across devices (e.g., theme, user preferences, DataSheet configs).
  *
+ * When the adapter changes via `useSyncStorage().configure()`, re-reads from the new adapter.
+ *
  * @param key - Storage key for the config value
  * @param defaultValue - Default value if no stored value exists
  * @returns Tuple of [value accessor, value setter, ready state accessor]
@@ -28,50 +30,52 @@ export function useSyncConfig<TValue>(
   defaultValue: TValue,
 ): [Accessor<TValue>, Setter<TValue>, Accessor<boolean>] {
   const config = useConfig();
-  const syncStorage = useSyncStorage();
+  const syncStorageCtx = useSyncStorage();
   const prefixedKey = `${config.clientName}.${key}`;
   const [value, setValue] = createSignal<TValue>(defaultValue);
   const [ready, setReady] = createSignal(false);
 
-  // Initialize from storage
-  const initializeFromStorage = async () => {
-    if (!syncStorage) {
-      // Use localStorage synchronously
-      try {
-        const stored = localStorage.getItem(prefixedKey);
-        if (stored !== null) {
-          setValue(() => JSON.parse(stored) as TValue);
+  // Initialize from storage (reactive to adapter changes via configure())
+  createEffect(() => {
+    const currentAdapter = syncStorageCtx?.adapter();
+    setReady(false);
+
+    void (async () => {
+      if (!currentAdapter) {
+        // Use localStorage synchronously
+        try {
+          const stored = localStorage.getItem(prefixedKey);
+          if (stored !== null) {
+            setValue(() => JSON.parse(stored) as TValue);
+          }
+        } catch {
+          // Ignore parse errors, keep default value
         }
-      } catch {
-        // Ignore parse errors, keep default value
+        setReady(true);
+        return;
       }
-      setReady(true);
-      return;
-    }
 
-    // Use syncStorage asynchronously
-    try {
-      const stored = await syncStorage.getItem(prefixedKey);
-      if (stored !== null) {
-        setValue(() => JSON.parse(stored) as TValue);
-      }
-    } catch {
-      // Fall back to localStorage on error
+      // Use custom adapter asynchronously
       try {
-        const stored = localStorage.getItem(prefixedKey);
+        const stored = await currentAdapter.getItem(prefixedKey);
         if (stored !== null) {
           setValue(() => JSON.parse(stored) as TValue);
         }
       } catch {
-        // Ignore parse errors
+        // Fall back to localStorage on error
+        try {
+          const stored = localStorage.getItem(prefixedKey);
+          if (stored !== null) {
+            setValue(() => JSON.parse(stored) as TValue);
+          }
+        } catch {
+          // Ignore parse errors
+        }
+      } finally {
+        setReady(true);
       }
-    } finally {
-      setReady(true);
-    }
-  };
-
-  // Initialize on mount
-  void initializeFromStorage();
+    })();
+  });
 
   // Save to storage whenever value changes
   createEffect(() => {
@@ -79,16 +83,19 @@ export function useSyncConfig<TValue>(
     const currentValue = value();
     const serialized = JSON.stringify(currentValue);
 
-    if (!syncStorage) {
+    // Read adapter untracked to avoid re-running save effect when adapter changes
+    const currentAdapter = untrack(() => syncStorageCtx?.adapter());
+
+    if (!currentAdapter) {
       // Use localStorage synchronously
       localStorage.setItem(prefixedKey, serialized);
       return;
     }
 
-    // Use syncStorage asynchronously
+    // Use custom adapter asynchronously
     void (async () => {
       try {
-        await syncStorage.setItem(prefixedKey, serialized);
+        await currentAdapter.setItem(prefixedKey, serialized);
       } catch {
         // Fall back to localStorage on error
         localStorage.setItem(prefixedKey, serialized);

package/src/index.ts

@@ -82,7 +82,6 @@ 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";
 
 //#endregion
@@ -92,13 +91,11 @@ export * from "./components/disclosure/Tabs";
 // Notification
 export * from "./components/feedback/notification/NotificationContext";
 export * from "./components/feedback/notification/NotificationBell";
-export * from "./components/feedback/notification/NotificationProvider";
 export * from "./components/feedback/notification/NotificationBanner";
 
 // Busy
 export * from "./components/feedback/busy/BusyContext";
 export * from "./components/feedback/busy/BusyContainer";
-export * from "./components/feedback/busy/BusyProvider";
 
 // Print
 export * from "./components/feedback/print/Print";
@@ -109,20 +106,43 @@ export * from "./components/feedback/Progress";
 
 //#region ========== Providers ==========
 
-export * from "./providers/ConfigContext";
-export * from "./providers/SyncStorageContext";
-export * from "./providers/LoggerContext";
-export * from "./providers/ErrorLoggerProvider";
-export * from "./providers/PwaUpdateProvider";
-export * from "./providers/ClipboardProvider";
-export { useTheme, ThemeProvider } from "./providers/ThemeContext";
+// Config
+export { type AppConfig, ConfigContext, useConfig } from "./providers/ConfigContext";
+
+// SyncStorage
+export {
+  type StorageAdapter,
+  type SyncStorageContextValue,
+  SyncStorageContext,
+  useSyncStorage,
+} from "./providers/SyncStorageContext";
+
+// Logger
+export { type LogAdapter, type LoggerContextValue } from "./providers/LoggerContext";
+
+// Theme
+export { useTheme } from "./providers/ThemeContext";
 export type { ThemeMode, ResolvedTheme } from "./providers/ThemeContext";
-export * from "./providers/ServiceClientContext";
-export * from "./providers/ServiceClientProvider";
-export * from "./providers/shared-data/SharedDataContext";
-export * from "./providers/shared-data/SharedDataProvider";
+
+// ServiceClient
+export {
+  type ServiceClientContextValue,
+  ServiceClientContext,
+  useServiceClient,
+} from "./providers/ServiceClientContext";
+
+// SharedData
+export type {
+  SharedDataDefinition,
+  SharedDataAccessor,
+  SharedDataValue,
+} from "./providers/shared-data/SharedDataContext";
+export { SharedDataContext, useSharedData } from "./providers/shared-data/SharedDataContext";
 export * from "./providers/shared-data/SharedDataChangeEvent";
 
+// InitializeProvider (only exported provider)
+export * from "./providers/InitializeProvider";
+
 //#endregion
 
 //#region ========== Hooks ==========

package/src/providers/InitializeProvider.tsx

@@ -0,0 +1,74 @@
+import { type ParentComponent } from "solid-js";
+import { ConfigProvider } from "./ConfigContext";
+import { SyncStorageProvider } from "./SyncStorageContext";
+import { LoggerProvider } from "./LoggerContext";
+import { NotificationProvider } from "../components/feedback/notification/NotificationProvider";
+import { NotificationBanner } from "../components/feedback/notification/NotificationBanner";
+import { ErrorLoggerProvider } from "./ErrorLoggerProvider";
+import { PwaUpdateProvider } from "./PwaUpdateProvider";
+import { ClipboardProvider } from "./ClipboardProvider";
+import { ThemeProvider } from "./ThemeContext";
+import { ServiceClientProvider } from "./ServiceClientProvider";
+import { SharedDataProvider } from "./shared-data/SharedDataProvider";
+import { BusyProvider } from "../components/feedback/busy/BusyProvider";
+import { DialogProvider } from "../components/disclosure/DialogProvider";
+import type { BusyVariant } from "../components/feedback/busy/BusyContext";
+
+export type { BusyVariant };
+
+/**
+ * @simplysm/solid 메인 Provider
+ *
+ * @remarks
+ * - 모든 개별 Provider를 올바른 의존성 순서로 네스팅
+ * - `clientName`만 prop으로 전달하고, 나머지 설정은 각 hook의 `configure()`로 주입
+ * - 개별 Provider를 직접 조합할 필요 없이 이 Provider 하나로 앱을 감싸면 됨
+ *
+ * @example
+ * ```tsx
+ * <InitializeProvider clientName="my-app">
+ *   <AppRoot />
+ * </InitializeProvider>
+ *
+ * function AppRoot() {
+ *   const serviceClient = useServiceClient();
+ *   onMount(async () => {
+ *     await serviceClient.connect("main", { port: 3000 });
+ *     useSyncStorage()!.configure(myStorageAdapter);
+ *     useLogger().configure(myLogAdapter);
+ *     useSharedData().configure(definitions);
+ *   });
+ * }
+ * ```
+ */
+export const InitializeProvider: ParentComponent<{
+  clientName: string;
+  busyVariant?: BusyVariant;
+}> = (props) => {
+  return (
+    <ConfigProvider clientName={props.clientName}>
+      <SyncStorageProvider>
+        <LoggerProvider>
+          <NotificationProvider>
+            <NotificationBanner />
+            <ErrorLoggerProvider>
+              <PwaUpdateProvider>
+                <ClipboardProvider>
+                  <ThemeProvider>
+                    <ServiceClientProvider>
+                      <SharedDataProvider>
+                        <BusyProvider variant={props.busyVariant}>
+                          <DialogProvider>{props.children}</DialogProvider>
+                        </BusyProvider>
+                      </SharedDataProvider>
+                    </ServiceClientProvider>
+                  </ThemeProvider>
+                </ClipboardProvider>
+              </PwaUpdateProvider>
+            </ErrorLoggerProvider>
+          </NotificationProvider>
+        </LoggerProvider>
+      </SyncStorageProvider>
+    </ConfigProvider>
+  );
+};

package/src/providers/LoggerContext.tsx

@@ -1,4 +1,10 @@
-import { createContext, useContext, type ParentComponent } from "solid-js";
+import {
+  type Accessor,
+  createContext,
+  createSignal,
+  useContext,
+  type ParentComponent,
+} from "solid-js";
 
 /**
  * 로그 어댑터 인터페이스
@@ -11,36 +17,59 @@ export interface LogAdapter {
   write(severity: "error" | "warn" | "info" | "log", ...data: any[]): Promise<void> | void;
 }
 
+/**
+ * 로그 어댑터 Context 값
+ *
+ * @remarks
+ * - `adapter`: 현재 설정된 LogAdapter (signal). configure 전에는 undefined
+ * - `configure`: adapter를 나중에 주입하는 함수
+ */
+export interface LoggerContextValue {
+  adapter: Accessor<LogAdapter | undefined>;
+  configure: (adapter: LogAdapter) => void;
+}
+
 /**
  * 로그 어댑터 Context
  *
  * @remarks
  * Provider가 없으면 `undefined` (useLogger에서 consola로 fallback)
  */
-export const LoggerContext = createContext<LogAdapter | undefined>(undefined);
+export const LoggerContext = createContext<LoggerContextValue>();
 
 /**
  * 로그 어댑터 Context에 접근하는 훅
  *
- * @returns LogAdapter 또는 undefined (Provider가 없으면)
+ * @returns LoggerContextValue 또는 undefined (Provider가 없으면)
  */
-export function useLogAdapter(): LogAdapter | undefined {
+export function useLogAdapter(): LoggerContextValue | undefined {
   return useContext(LoggerContext);
 }
 
 /**
  * 로그 어댑터 Provider
  *
+ * @remarks
+ * - prop 없이 사용. adapter는 `useLogger().configure()`로 나중에 주입
+ * - configure 전에는 useLogger가 consola로 fallback
+ *
  * @example
  * ```tsx
- * <LoggerProvider adapter={myLogAdapter}>
+ * <LoggerProvider>
  *   <App />
  * </LoggerProvider>
+ *
+ * // 자식 컴포넌트에서 나중에 설정:
+ * useLogger().configure(myLogAdapter);
  * ```
  */
-export const LoggerProvider: ParentComponent<{ adapter: LogAdapter }> = (props) => {
-  return (
-    // eslint-disable-next-line solid/reactivity -- adapter는 초기 설정값으로 변경되지 않음
-    <LoggerContext.Provider value={props.adapter}>{props.children}</LoggerContext.Provider>
-  );
+export const LoggerProvider: ParentComponent = (props) => {
+  const [adapter, setAdapter] = createSignal<LogAdapter | undefined>();
+
+  const value: LoggerContextValue = {
+    adapter,
+    configure: (a: LogAdapter) => setAdapter(() => a),
+  };
+
+  return <LoggerContext.Provider value={value}>{props.children}</LoggerContext.Provider>;
 };

package/src/providers/ServiceClientContext.ts

@@ -1,15 +1,28 @@
 import { createContext, useContext } from "solid-js";
 import type { ServiceClient, ServiceConnectionConfig } from "@simplysm/service-client";
 
+/**
+ * WebSocket 서비스 클라이언트 Context 값
+ */
 export interface ServiceClientContextValue {
+  /** WebSocket 연결 열기 (key로 다중 연결 관리) */
   connect: (key: string, options?: Partial<ServiceConnectionConfig>) => Promise<void>;
+  /** 연결 닫기 */
   close: (key: string) => Promise<void>;
+  /** 연결된 클라이언트 인스턴스 가져오기 (연결되지 않은 key면 에러 발생) */
   get: (key: string) => ServiceClient;
+  /** 연결 상태 확인 */
   isConnected: (key: string) => boolean;
 }
 
+/** WebSocket 서비스 클라이언트 Context */
 export const ServiceClientContext = createContext<ServiceClientContextValue>();
 
+/**
+ * WebSocket 서비스 클라이언트에 접근하는 훅
+ *
+ * @throws ServiceClientProvider가 없으면 에러 발생
+ */
 export function useServiceClient(): ServiceClientContextValue {
   const context = useContext(ServiceClientContext);
   if (!context) {