@simplysm/solid 13.0.0-beta.6 → 13.0.1

package/src/hooks/createPwaUpdate.ts

@@ -0,0 +1,73 @@
+import { onCleanup } from "solid-js";
+import { useNotification } from "../components/feedback/notification/NotificationContext";
+
+const UPDATE_INTERVAL = 5 * 60 * 1000; // 5 minutes
+
+/**
+ * PWA Service Worker update detection hook.
+ *
+ * Polls for SW updates every 5 minutes. When a new version is detected,
+ * shows a notification with a reload action via the Notification system.
+ *
+ * No-ops gracefully when:
+ * - `navigator.serviceWorker` is unavailable (HTTP, unsupported browser)
+ * - No service worker is registered (dev mode, tests)
+ *
+ * Must be called inside NotificationProvider.
+ */
+export function createPwaUpdate(): void {
+  if (typeof navigator === "undefined" || !("serviceWorker" in navigator)) return;
+
+  const notification = useNotification();
+  let intervalId: ReturnType<typeof setInterval> | undefined;
+
+  void navigator.serviceWorker.getRegistration().then((registration) => {
+    if (registration == null) return;
+
+    // Periodic update check
+    intervalId = setInterval(() => {
+      void registration.update();
+    }, UPDATE_INTERVAL);
+
+    // Already waiting SW
+    if (registration.waiting != null) {
+      promptUpdate(registration.waiting);
+    }
+
+    // Detect new SW installation
+    registration.addEventListener("updatefound", () => {
+      const newSW = registration.installing;
+      if (newSW == null) return;
+
+      newSW.addEventListener("statechange", () => {
+        if (newSW.state === "installed" && navigator.serviceWorker.controller != null) {
+          promptUpdate(newSW);
+        }
+      });
+    });
+  });
+
+  // Reload when new SW takes control
+  const onControllerChange = () => {
+    window.location.reload();
+  };
+  navigator.serviceWorker.addEventListener("controllerchange", onControllerChange);
+
+  onCleanup(() => {
+    if (intervalId != null) {
+      clearInterval(intervalId);
+    }
+    navigator.serviceWorker.removeEventListener("controllerchange", onControllerChange);
+  });
+
+  function promptUpdate(waitingSW: ServiceWorker): void {
+    notification.info("앱이 업데이트되었습니다", "새로고침하면 최신 버전을 사용할 수 있습니다", {
+      action: {
+        label: "새로고침",
+        onClick: () => {
+          waitingSW.postMessage({ type: "SKIP_WAITING" });
+        },
+      },
+    });
+  }
+}

package/src/hooks/useClipboardValueCopy.ts

@@ -82,7 +82,7 @@ function extractTextFromRange(range: Range): string | null {
     }
     if (node instanceof HTMLSelectElement) {
       if (node.selectedOptions.length > 0) {
-        parts.push(node.selectedOptions[0].textContent?.trim() ?? "");
+        parts.push(node.selectedOptions[0].textContent.trim());
       }
       return;
     }

package/src/hooks/useLocalStorage.ts

@@ -0,0 +1,68 @@
+import { type Accessor, type Setter, createSignal } from "solid-js";
+import { useConfig } from "../providers/ConfigContext";
+
+/**
+ * localStorage 기반 저장소 훅.
+ * syncStorage 설정과 무관하게 항상 localStorage를 사용한다.
+ * 기기별로 독립적으로 유지되어야 하는 데이터(인증 토큰, 기기별 상태 등)에 사용한다.
+ *
+ * 키는 ConfigContext의 `clientName`으로 자동 prefix된다. (`${clientName}.${key}`)
+ *
+ * @template T - 저장할 값의 타입
+ * @param key - localStorage 키
+ * @param initialValue - 초기값 (옵셔널)
+ * @returns [Accessor<T | undefined>, Setter<T | undefined>] 튜플
+ *
+ * @example
+ * ```tsx
+ * const [token, setToken] = useLocalStorage<string>("auth-token");
+ *
+ * // 값 설정
+ * setToken("abc123");
+ *
+ * // 값 읽기
+ * console.log(token()); // "abc123"
+ *
+ * // 값 제거
+ * setToken(undefined);
+ * ```
+ */
+export function useLocalStorage<T>(key: string, initialValue?: T): [Accessor<T | undefined>, Setter<T | undefined>] {
+  const config = useConfig();
+  const prefixedKey = `${config.clientName}.${key}`;
+
+  // localStorage에서 초기값 읽기
+  let storedValue: T | undefined = initialValue;
+  try {
+    const item = localStorage.getItem(prefixedKey);
+    if (item !== null) {
+      storedValue = JSON.parse(item) as T;
+    }
+  } catch {
+    // JSON 파싱 실패 시 초기값 사용
+  }
+
+  const [value, setValue] = createSignal<T | undefined>(storedValue);
+
+  const setAndStore = (newValue: T | undefined | ((prev: T | undefined) => T | undefined)) => {
+    let resolved: T | undefined;
+
+    if (typeof newValue === "function") {
+      resolved = (newValue as (prev: T | undefined) => T | undefined)(value());
+      setValue(() => resolved);
+    } else {
+      resolved = newValue;
+      setValue(() => newValue);
+    }
+
+    if (resolved === undefined) {
+      localStorage.removeItem(prefixedKey);
+    } else {
+      localStorage.setItem(prefixedKey, JSON.stringify(resolved));
+    }
+
+    return resolved;
+  };
+
+  return [value, setAndStore as Setter<T | undefined>];
+}

package/src/hooks/useLogger.ts

@@ -0,0 +1,32 @@
+import { consola } from "consola";
+import { useConfig, type LogAdapter } from "../providers/ConfigContext";
+
+type LogLevel = Parameters<LogAdapter["write"]>[0];
+
+interface Logger {
+  log: (...args: unknown[]) => void;
+  info: (...args: unknown[]) => void;
+  warn: (...args: unknown[]) => void;
+  error: (...args: unknown[]) => void;
+}
+
+export function useLogger(): Logger {
+  const config = useConfig();
+
+  const createLogFunction = (level: LogLevel) => {
+    return (...args: unknown[]) => {
+      if (config.logger) {
+        void config.logger.write(level, ...args);
+      } else {
+        (consola as any)[level](...args);
+      }
+    };
+  };
+
+  return {
+    log: createLogFunction("log"),
+    info: createLogFunction("info"),
+    warn: createLogFunction("warn"),
+    error: createLogFunction("error"),
+  };
+}

package/src/hooks/useSyncConfig.ts

@@ -0,0 +1,99 @@
+import { type Accessor, type Setter, createEffect, createSignal, onCleanup } from "solid-js";
+import { useConfig } from "../providers/ConfigContext";
+
+/**
+ * Creates a reactive signal that syncs configuration data to storage.
+ *
+ * Uses `syncStorage` from ConfigProvider if available, otherwise falls back to `localStorage`.
+ * Designed for data that should persist and sync across devices (e.g., theme, user preferences, DataSheet configs).
+ *
+ * @param key - Storage key for the config value
+ * @param defaultValue - Default value if no stored value exists
+ * @returns Tuple of [value accessor, value setter, loading state accessor]
+ *
+ * @example
+ * ```tsx
+ * const [theme, setTheme, loading] = useSyncConfig("user-theme", "light");
+ *
+ * <Show when={!loading()}>
+ *   <button onClick={() => setTheme(theme() === "light" ? "dark" : "light")}>
+ *     Toggle theme
+ *   </button>
+ * </Show>
+ * ```
+ */
+export function useSyncConfig<T>(key: string, defaultValue: T): [Accessor<T>, Setter<T>, Accessor<boolean>] {
+  const config = useConfig();
+  const prefixedKey = `${config.clientName}.${key}`;
+  const [value, setValue] = createSignal<T>(defaultValue);
+  const [loading, setLoading] = createSignal(false);
+
+  // Initialize from storage
+  const initializeFromStorage = async () => {
+    if (!config.syncStorage) {
+      // Use localStorage synchronously
+      try {
+        const stored = localStorage.getItem(prefixedKey);
+        if (stored !== null) {
+          setValue(() => JSON.parse(stored) as T);
+        }
+      } catch {
+        // Ignore parse errors, keep default value
+      }
+      return;
+    }
+
+    // Use syncStorage asynchronously
+    setLoading(true);
+    try {
+      const stored = await config.syncStorage.getItem(prefixedKey);
+      if (stored !== null) {
+        setValue(() => JSON.parse(stored) as T);
+      }
+    } catch {
+      // Fall back to localStorage on error
+      try {
+        const stored = localStorage.getItem(prefixedKey);
+        if (stored !== null) {
+          setValue(() => JSON.parse(stored) as T);
+        }
+      } catch {
+        // Ignore parse errors
+      }
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  // Initialize on mount
+  void initializeFromStorage();
+
+  // Save to storage whenever value changes
+  createEffect(() => {
+    const currentValue = value();
+    const serialized = JSON.stringify(currentValue);
+
+    if (!config.syncStorage) {
+      // Use localStorage synchronously
+      localStorage.setItem(prefixedKey, serialized);
+      return;
+    }
+
+    // Use syncStorage asynchronously
+    void (async () => {
+      try {
+        await config.syncStorage!.setItem(prefixedKey, serialized);
+      } catch {
+        // Fall back to localStorage on error
+        localStorage.setItem(prefixedKey, serialized);
+      }
+    })();
+  });
+
+  // Clean up (optional, for consistency)
+  onCleanup(() => {
+    // No cleanup needed for storage operations
+  });
+
+  return [value, setValue, loading];
+}

package/src/index.ts

@@ -22,6 +22,7 @@ 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";
+export * from "./components/form-control/Invalid";
 
 // layout
 export * from "./components/layout/FormGroup";
@@ -63,14 +64,14 @@ export * from "./components/disclosure/Tabs";
 
 // feedback
 export * from "./components/feedback/notification/NotificationContext";
+export * from "./components/feedback/notification/NotificationBell";
 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";
+export * from "./components/feedback/loading/LoadingProvider";
 
 // feedback - print
 export * from "./components/feedback/print/Print";
@@ -80,7 +81,8 @@ export * from "./components/feedback/Progress";
 // providers
 export * from "./providers/ConfigContext";
 export * from "./providers/InitializeProvider";
-export * from "./providers/ThemeContext";
+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";
@@ -88,11 +90,14 @@ export * from "./providers/shared-data/SharedDataProvider";
 export * from "./providers/shared-data/SharedDataChangeEvent";
 
 // hooks
-export * from "./hooks/usePersisted";
+export * from "./hooks/useLocalStorage";
+export * from "./hooks/useSyncConfig";
+export * from "./hooks/useLogger";
 export * from "./hooks/usePrint";
 export { createControllableSignal } from "./hooks/createControllableSignal";
 export { createIMEHandler } from "./hooks/createIMEHandler";
 export { createMountTransition } from "./hooks/createMountTransition";
+export { createPwaUpdate } from "./hooks/createPwaUpdate";
 export { useRouterLink } from "./hooks/useRouterLink";
 
 // styles

package/src/providers/ConfigContext.ts

@@ -13,6 +13,17 @@ export interface StorageAdapter {
   removeItem(key: string): void | Promise<void>;
 }
 
+/**
+ * 로그 어댑터 인터페이스
+ *
+ * @remarks
+ * - `useLogger`에서 사용하는 로그 전송 어댑터 (DB, 서버 등)
+ * - adapter가 설정되면 consola 대신 adapter만 사용됨
+ */
+export interface LogAdapter {
+  write(severity: "error" | "warn" | "info" | "log", ...data: any[]): Promise<void> | void;
+}
+
 /**
  * 앱 전역 설정
  */
@@ -23,9 +34,19 @@ export interface AppConfig {
   clientName: string;
 
   /**
-   * 커스텀 저장소 (기본값: localStorage)
+   * 동기화 가능 저장소 (useSyncConfig에서 사용, 없으면 localStorage로 fallback)
+   */
+  syncStorage?: StorageAdapter;
+
+  /**
+   * 로그 어댑터 (useLogger에서 consola 외 추가 전송에 사용)
+   */
+  logger?: LogAdapter;
+
+  /**
+   * 루트 로딩 오버레이 변형 (기본값: "spinner")
    */
-  storage?: StorageAdapter;
+  loadingVariant?: "spinner" | "bar";
 }
 
 /**

package/src/providers/InitializeProvider.tsx

@@ -1,6 +1,43 @@
 import type { ParentComponent } from "solid-js";
+import { onCleanup } from "solid-js";
 import { type AppConfig, ConfigContext } from "./ConfigContext";
 import { useClipboardValueCopy } from "../hooks/useClipboardValueCopy";
+import { ThemeProvider } from "./ThemeContext";
+import { NotificationProvider } from "../components/feedback/notification/NotificationProvider";
+import { NotificationBanner } from "../components/feedback/notification/NotificationBanner";
+import { LoadingProvider } from "../components/feedback/loading/LoadingProvider";
+import { DialogProvider } from "../components/disclosure/DialogProvider";
+import { createPwaUpdate } from "../hooks/createPwaUpdate";
+import { useLogger } from "../hooks/useLogger";
+
+/** Runs PWA update detection inside NotificationProvider context */
+function PwaUpdater() {
+  createPwaUpdate();
+  return null;
+}
+
+/** Captures uncaught errors and unhandled rejections via useLogger */
+function GlobalErrorLogger() {
+  const logger = useLogger();
+
+  const onError = (event: ErrorEvent) => {
+    logger.error("Uncaught error:", event.error ?? event.message);
+  };
+
+  const onUnhandledRejection = (event: PromiseRejectionEvent) => {
+    logger.error("Unhandled rejection:", event.reason);
+  };
+
+  window.addEventListener("error", onError);
+  window.addEventListener("unhandledrejection", onUnhandledRejection);
+
+  onCleanup(() => {
+    window.removeEventListener("error", onError);
+    window.removeEventListener("unhandledrejection", onUnhandledRejection);
+  });
+
+  return null;
+}
 
 /**
  * @simplysm/solid 초기화 Provider
@@ -9,13 +46,16 @@ import { useClipboardValueCopy } from "../hooks/useClipboardValueCopy";
  * 앱 루트에서 한 번 감싸며, 다음을 초기화한다:
  * - 앱 전역 설정 (config) Context 제공
  * - 폼 컨트롤 value 클립보드 복사 지원
+ * - 테마 (라이트/다크/시스템)
+ * - 알림 시스템 + 배너
+ * - 전역 에러 캡처 (window.onerror, unhandledrejection)
+ * - 루트 로딩 오버레이
+ * - 프로그래매틱 다이얼로그
  *
  * @example
  * ```tsx
  * <InitializeProvider config={{ clientName: "myApp" }}>
- *   <ThemeProvider>
- *     <App />
- *   </ThemeProvider>
+ *   <App />
  * </InitializeProvider>
  * ```
  */
@@ -23,6 +63,20 @@ 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>;
+  /* eslint-disable solid/reactivity -- config는 초기 설정값으로 변경되지 않음 */
+  return (
+    <ConfigContext.Provider value={props.config}>
+      <ThemeProvider>
+        <NotificationProvider>
+          <NotificationBanner />
+          <GlobalErrorLogger />
+          <PwaUpdater />
+          <LoadingProvider variant={props.config.loadingVariant}>
+            <DialogProvider>{props.children}</DialogProvider>
+          </LoadingProvider>
+        </NotificationProvider>
+      </ThemeProvider>
+    </ConfigContext.Provider>
+  );
+  /* eslint-enable solid/reactivity */
 };

package/src/providers/ServiceClientProvider.tsx

@@ -1,5 +1,5 @@
 import { type ParentComponent, onCleanup } from "solid-js";
-import { ServiceClient, type ServiceConnectionConfig } from "@simplysm/service-client";
+import { createServiceClient, type ServiceClient, type ServiceConnectionConfig } from "@simplysm/service-client";
 import { ServiceClientContext, type ServiceClientContextValue } from "./ServiceClientContext";
 import { useConfig } from "./ConfigContext";
 import { useNotification } from "../components/feedback/notification/NotificationContext";
@@ -35,7 +35,7 @@ export const ServiceClientProvider: ParentComponent = (props) => {
       ssl: location.protocol.startsWith("https"),
     };
 
-    const client = new ServiceClient(config.clientName, {
+    const client = createServiceClient(config.clientName, {
       ...defaultConfig,
       ...options,
     });

package/src/providers/ThemeContext.tsx

@@ -1,6 +1,6 @@
 import { createContext, useContext, type ParentComponent, createMemo, createEffect, onCleanup } from "solid-js";
 import { createMediaQuery } from "@solid-primitives/media";
-import { usePersisted } from "../hooks/usePersisted";
+import { useSyncConfig } from "../hooks/useSyncConfig";
 
 /**
  * 테마 모드
@@ -64,7 +64,7 @@ export function useTheme(): ThemeContextValue {
  * 테마 Provider 컴포넌트
  *
  * @remarks
- * - ConfigContext.Provider 내부에서 사용해야 함 (usePersisted 의존)
+ * - ConfigContext.Provider 내부에서 사용해야 함 (useSyncConfig 의존)
  * - localStorage에 테마 설정 저장
  * - `<html>` 요소에 `dark` 클래스 자동 토글
  *
@@ -78,7 +78,7 @@ export function useTheme(): ThemeContextValue {
  * ```
  */
 export const ThemeProvider: ParentComponent = (props) => {
-  const [mode, setMode] = usePersisted<ThemeMode>("theme", "system");
+  const [mode, setMode] = useSyncConfig<ThemeMode>("theme", "system");
 
   // OS 다크모드 감지
   const prefersDark = createMediaQuery("(prefers-color-scheme: dark)");

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

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

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

@@ -9,6 +9,7 @@ import {
 import { SharedDataChangeEvent } from "./SharedDataChangeEvent";
 import { useServiceClient } from "../ServiceClientContext";
 import { useNotification } from "../../components/feedback/notification/NotificationContext";
+import { useLogger } from "../../hooks/useLogger";
 
 export function SharedDataProvider<T extends Record<string, unknown>>(props: {
   definitions: { [K in keyof T]: SharedDataDefinition<T[K]> };
@@ -16,6 +17,7 @@ export function SharedDataProvider<T extends Record<string, unknown>>(props: {
 }): JSX.Element {
   const serviceClient = useServiceClient();
   const notification = useNotification();
+  const logger = useLogger();
 
   const [loadingCount, setLoadingCount] = createSignal(0);
   const loading: Accessor<boolean> = () => loadingCount() > 0;
@@ -69,6 +71,7 @@ export function SharedDataProvider<T extends Record<string, unknown>>(props: {
       }
     } catch (err) {
       // CR-2: fetch 실패 시 사용자에게 알림
+      logger.error(`SharedData '${name}' fetch failed:`, err);
       notification.danger(
         "공유 데이터 로드 실패",
         err instanceof Error ? err.message : `'${name}' 데이터를 불러오는 중 오류가 발생했습니다.`,