@simplysm/solid 13.0.93 → 13.0.96

package/docs/providers-hooks.md

@@ -38,14 +38,23 @@ const theme = useTheme();
 theme.mode();           // "light" | "dark" | "system"
 theme.resolvedTheme();  // "light" | "dark" (OS 설정 반영)
 theme.setMode("dark");
-theme.cycleMode();      // light → system → dark → light
+theme.cycleMode();      // light -> system -> dark -> light
 ```
 
+### useTheme 반환 타입
+
+| 속성 | 타입 | 설명 |
+|------|------|------|
+| `mode()` | `ThemeMode` | 현재 테마 모드 (`"light" \| "dark" \| "system"`) |
+| `setMode(mode)` | `(mode: ThemeMode) => void` | 테마 모드 설정 |
+| `resolvedTheme()` | `ResolvedTheme` | 실제 적용된 테마 (`"light" \| "dark"`) |
+| `cycleMode()` | `() => void` | 다음 모드로 순환 |
+
 ---
 
 ## I18nProvider
 
-다국어 지원. 한국어(ko), 영어(en) 내장.
+다국어 지원. 한국어(ko), 영어(en) 내장. 브라우저 언어 자동 감지.
 
 ```tsx
 import { I18nProvider, useI18n } from "@simplysm/solid";
@@ -70,6 +79,15 @@ i18n.configure({
 });
 ```
 
+### useI18n 반환 타입
+
+| 속성 | 타입 | 설명 |
+|------|------|------|
+| `t(key, params?)` | `(key: string, params?: Record<string, string>) => string` | 번역 조회 |
+| `locale()` | `Accessor<string>` | 현재 로케일 |
+| `setLocale(locale)` | `(locale: string) => void` | 로케일 변경 |
+| `configure(options)` | `(options: I18nConfigureOptions) => void` | 사전 확장/설정 |
+
 ---
 
 ## SharedDataProvider
@@ -159,41 +177,111 @@ await sharedData.wait();
 
 ### createControllableSignal
 
-제어/비제어 컴포넌트 패턴 구현.
+제어/비제어 컴포넌트 패턴 구현. `onChange`가 제공되면 제어 모드, 없으면 비제어 모드.
 
 ```typescript
 import { createControllableSignal } from "@simplysm/solid";
 
 const [value, setValue] = createControllableSignal({
-  value: () => props.value,
+  value: () => props.value ?? "",
   onChange: () => props.onValueChange,
 });
+
+// 함수형 setter 지원
+setValue((prev) => prev + "!");
+```
+
+```typescript
+// 시그니처
+function createControllableSignal<TValue>(options: {
+  value: Accessor<TValue>;
+  onChange: Accessor<((value: TValue) => void) | undefined>;
+}): [Accessor<TValue>, (newValue: TValue | ((prev: TValue) => TValue)) => TValue];
 ```
 
 ### createControllableStore
 
-객체 상태용 제어/비제어 패턴.
+객체 상태용 제어/비제어 패턴. SolidJS store 기반.
+
+```typescript
+import { createControllableStore } from "@simplysm/solid";
+
+const [items, setItems] = createControllableStore<Item[]>({
+  value: () => props.items ?? [],
+  onChange: () => props.onItemsChange,
+});
+
+// SetStoreFunction 오버로드 모두 지원
+setItems(0, "name", "Alice");
+setItems(reconcile(newItems));
+```
+
+```typescript
+// 시그니처
+function createControllableStore<TValue extends object>(options: {
+  value: () => TValue;
+  onChange: () => ((value: TValue) => void) | undefined;
+}): [TValue, SetStoreFunction<TValue>];
+```
 
 ### createIMEHandler
 
-IME(한글 등) 입력 처리.
+IME(한글 등) 입력 처리. 조합 중 DOM 재생성을 방지한다.
+
+```typescript
+import { createIMEHandler } from "@simplysm/solid";
+
+const ime = createIMEHandler((value) => setValue(value));
+
+// 이벤트 핸들러
+onCompositionStart={ime.handleCompositionStart}
+onInput={(e) => ime.handleInput(e.currentTarget.value, e.isComposing)}
+onCompositionEnd={(e) => ime.handleCompositionEnd(e.currentTarget.value)}
+
+// 조합 중 값 (display 용)
+ime.composingValue()
+
+// 조합 강제 완료
+ime.flushComposition()
+```
+
+### createMountTransition
+
+마운트/언마운트 시 애니메이션 상태를 관리한다.
 
 ```typescript
-const ime = createIMEHandler();
-// ime.handleCompositionStart()
-// ime.handleCompositionEnd()
-// ime.handleInput()
-// ime.composingValue()
+import { createMountTransition } from "@simplysm/solid";
+
+const { mounted, animating, unmount } = createMountTransition(() => isVisible());
+
+// mounted: DOM에 마운트 여부
+// animating: 진입/퇴장 애니메이션 중 여부
+// unmount: 언마운트 트리거
 ```
 
 ### useLocalStorage
 
-반응형 localStorage.
+반응형 localStorage. `ConfigProvider`의 `clientName`을 키 접두사로 사용한다.
 
 ```typescript
 import { useLocalStorage } from "@simplysm/solid";
 
-const [theme, setTheme] = useLocalStorage("theme", "light");
+const [token, setToken] = useLocalStorage<string>("auth-token");
+
+setToken("abc123");     // 저장
+token();                // "abc123"
+setToken(undefined);    // 삭제
+
+// 함수형 setter
+setToken((prev) => prev ? prev + "-updated" : "new-token");
+```
+
+```typescript
+// 시그니처
+function useLocalStorage<TValue>(
+  key: string,
+  initialValue?: TValue,
+): [Accessor<TValue | undefined>, StorageSetter<TValue>];
 ```
 
 ### useSyncConfig
@@ -201,30 +289,28 @@ const [theme, setTheme] = useLocalStorage("theme", "light");
 클라이언트명 접두사 붙은 localStorage 동기화.
 
 ```typescript
+import { useSyncConfig } from "@simplysm/solid";
+
 const [config, setConfig] = useSyncConfig("my-setting", defaultValue);
 ```
 
 ### useLogger
 
 ```typescript
+import { useLogger } from "@simplysm/solid";
+
 const logger = useLogger();
 ```
 
 ### useRouterLink
 
 ```typescript
+import { useRouterLink } from "@simplysm/solid";
+
 const navigate = useRouterLink();
 navigate("/users");
 ```
 
-### createMountTransition
-
-마운트 애니메이션 상태 관리.
-
-```typescript
-const { mounted, animating, unmount } = createMountTransition(() => isVisible());
-```
-
 ---
 
 ## createAppStructure
@@ -287,6 +373,33 @@ app.perms;              // 타입 안전한 권한 객체 (app.perms.admin.users
 app.getTitleChainByHref("/admin/users");  // ["관리", "사용자 관리"]
 ```
 
+### AppStructureItem 타입
+
+```typescript
+// 그룹 항목 (children 보유)
+interface AppStructureGroupItem<TModule> {
+  code: string;
+  title: string;
+  icon?: Component<IconProps>;
+  modules?: TModule[];
+  requiredModules?: TModule[];
+  children: AppStructureItem<TModule>[];
+}
+
+// 리프 항목 (페이지 컴포넌트)
+interface AppStructureLeafItem<TModule> {
+  code: string;
+  title: string;
+  icon?: Component<IconProps>;
+  modules?: TModule[];
+  requiredModules?: TModule[];
+  component?: Component;
+  perms?: ("use" | "edit")[];
+  subPerms?: AppStructureSubPerm<TModule>[];
+  isNotMenu?: boolean;
+}
+```
+
 ### AppStructure 반환 타입
 
 | 속성 | 타입 | 설명 |
@@ -355,14 +468,19 @@ themeTokens.primary.border     // border-primary-300 ...
 
 ### ripple
 
-Material Design 스타일 리플 효과.
+Material Design 스타일 리플 효과. 포인터 다운 시 클릭 위치에서 원형 리플이 확산된다.
 
 ```tsx
 import { ripple } from "@simplysm/solid";
+void ripple; // TypeScript directive 등록
 
-<button use:ripple>클릭</button>
+<button use:ripple={!props.disabled}>클릭</button>
 ```
 
+- `prefers-reduced-motion: reduce` 설정 시 리플 비활성화
+- 내부적으로 `overflow: hidden` 컨테이너를 생성하여 부모 요소에 영향 없음
+- `static` 포지션인 경우 자동으로 `relative`로 변경 (cleanup 시 복원)
+
 ---
 
 ## 헬퍼
@@ -384,28 +502,15 @@ mergeStyles("color: red", "font-size: 14px"); // "color: red; font-size: 14px"
 ```typescript
 import { createSlot } from "@simplysm/solid";
 
-// 슬롯 정의
+// 1. 슬롯 정의
 const [MySlot, createMySlotAccessor] = createSlot<{ children: JSX.Element }>();
 
-// 컴포넌트 내부에서 슬롯 접근
+// 2. 컴포넌트 내부에서 슬롯 접근
 const [slotValue, SlotProvider] = createMySlotAccessor();
 
-// 사용
+// 3. 사용
 <SlotProvider>
   <MySlot><span>슬롯 내용</span></MySlot>
-  {/* slotValue()로 접근 */}
+  {/* slotValue()?.children 으로 접근 */}
 </SlotProvider>
 ```
-
-### startPointerDrag
-
-포인터 드래그 인터랙션 관리. 포인터 캡처를 설정하고 move/end 이벤트를 관리한다.
-
-```typescript
-import { startPointerDrag } from "@simplysm/solid";
-
-startPointerDrag(element, event.pointerId, {
-  onMove: (e) => { /* 드래그 중 */ },
-  onEnd: (e) => { /* 드래그 종료 */ },
-});
-```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simplysm/solid",
-  "version": "13.0.93",
+  "version": "13.0.96",
   "description": "Simplysm package - SolidJS library",
   "author": "simplysm",
   "license": "Apache-2.0",
@@ -52,10 +52,10 @@
     "tabbable": "^6.4.0",
     "tailwind-merge": "^3.5.0",
     "tailwindcss": "^3.4.19",
-    "@simplysm/core-browser": "13.0.93",
-    "@simplysm/core-common": "13.0.93",
-    "@simplysm/service-common": "13.0.93",
-    "@simplysm/service-client": "13.0.93"
+    "@simplysm/core-browser": "13.0.96",
+    "@simplysm/core-common": "13.0.96",
+    "@simplysm/service-client": "13.0.96",
+    "@simplysm/service-common": "13.0.96"
   },
   "devDependencies": {
     "@solidjs/testing-library": "^0.8.10"

package/src/components/features/crud-sheet/CrudSheet.tsx

@@ -1,5 +1,6 @@
 import {
   createEffect,
+  createMemo,
   createSignal,
   createUniqueId,
   For,
@@ -10,6 +11,7 @@ import {
 } from "solid-js";
 import { createStore, produce, reconcile } from "solid-js/store";
 import { createControllableStore } from "../../../hooks/createControllableStore";
+import { createControllableSignal } from "../../../hooks/createControllableSignal";
 import type { DateTime } from "@simplysm/core-common";
 import { obj } from "@simplysm/core-common";
 import "@simplysm/core-common"; // register extensions
@@ -77,6 +79,8 @@ const CrudSheetBase = <TItem, TFilter extends Record<string, unknown>>(
     "dialogEdit",
     "excel",
     "selectionMode",
+    "selectedKeys",
+    "onSelectedKeysChange",
     "onSelect",
     "hideAutoTools",
     "close",
@@ -128,7 +132,11 @@ const CrudSheetBase = <TItem, TFilter extends Record<string, unknown>>(
   const [ready, setReady] = createSignal(false);
 
   const [selection, setSelection] = createSignal<TItem[]>([]);
-  const [selectedKeys, setSelectedKeys] = createSignal<Set<string | number>>(new Set());
+  const [selectedKeys, setSelectedKeys] = createControllableSignal<(string | number)[]>({
+    value: () => local.selectedKeys ?? [],
+    onChange: () => local.onSelectedKeysChange,
+  });
+  const selectedKeysSet = createMemo(() => new Set(selectedKeys()));
 
   let formRef: HTMLFormElement | undefined;
 
@@ -146,8 +154,8 @@ const CrudSheetBase = <TItem, TFilter extends Record<string, unknown>>(
   // -- Key-based selection: restore selection when items change --
   createEffect(() => {
     const currentItems = items;
-    const keys = selectedKeys();
-    if (keys.size === 0) {
+    const keysSet = selectedKeysSet();
+    if (keysSet.size === 0) {
       if (selection().length > 0) {
         setSelection([]);
       }
@@ -155,7 +163,7 @@ const CrudSheetBase = <TItem, TFilter extends Record<string, unknown>>(
     }
     const restored = currentItems.filter((item) => {
       const key = local.getItemKey(item);
-      return key != null && keys.has(key);
+      return key != null && keysSet.has(key);
     });
     setSelection(restored);
   });
@@ -346,7 +354,7 @@ const CrudSheetBase = <TItem, TFilter extends Record<string, unknown>>(
       merged.add(key); // Add current page selection
     }
 
-    setSelectedKeys(merged);
+    setSelectedKeys([...merged]);
     setSelection(newSelection);
 
     // Auto-confirm for single selection mode in dialog
@@ -359,14 +367,14 @@ const CrudSheetBase = <TItem, TFilter extends Record<string, unknown>>(
   }
 
   function clearSelection() {
-    setSelectedKeys(new Set<string | number>());
+    setSelectedKeys([]);
     setSelection([]);
   }
 
   function handleSelectConfirm() {
     local.onSelect?.({
       items: selection(),
-      keys: [...selectedKeys()],
+      keys: selectedKeys(),
     });
   }
 

package/src/components/features/crud-sheet/CrudSheet.types.ts

@@ -94,6 +94,8 @@ interface CrudSheetBaseProps<TItem, TFilter extends Record<string, unknown>> {
   onItemsChange?: (items: TItem[]) => void;
   excel?: ExcelConfig<TItem>;
   selectionMode?: "single" | "multiple";
+  selectedKeys?: (string | number)[];
+  onSelectedKeysChange?: (keys: (string | number)[]) => void;
   onSelect?: (result: SelectResult<TItem>) => void;
   onSubmitComplete?: () => void;
   hideAutoTools?: boolean;

package/src/components/layout/sidebar/Sidebar.tsx

@@ -180,11 +180,17 @@ export interface SidebarMenuProps extends Omit<JSX.HTMLAttributes<HTMLDivElement
    * Menu items array
    */
   menus: AppMenu[];
+  /**
+   * When true, all nested menu lists are expanded on initial render.
+   * @default false
+   */
+  defaultOpen?: boolean;
 }
 
 // Internal Context: share initial open state
 interface MenuContextValue {
   initialOpenItems: Accessor<Set<AppMenu>>;
+  defaultOpen: boolean;
 }
 
 const MenuContext = createContext<MenuContextValue>();
@@ -215,7 +221,7 @@ const MenuContext = createContext<MenuContextValue>();
  * ```
  */
 const SidebarMenu: Component<SidebarMenuProps> = (props) => {
-  const [local, rest] = splitProps(props, ["menus", "class"]);
+  const [local, rest] = splitProps(props, ["menus", "class", "defaultOpen"]);
 
   const location = useLocation();
 
@@ -249,7 +255,7 @@ const SidebarMenu: Component<SidebarMenuProps> = (props) => {
   const getClassName = () => twMerge("flex-1 overflow-y-auto", local.class);
 
   return (
-    <MenuContext.Provider value={{ initialOpenItems }}>
+    <MenuContext.Provider value={{ initialOpenItems, defaultOpen: local.defaultOpen ?? false }}>
       <div {...rest} data-sidebar-menu class={getClassName()}>
         <div class={clsx("px-3.5 py-1 text-sm font-bold", text.muted, "uppercase tracking-wider")}>MENU</div>
         <List inset>
@@ -281,7 +287,7 @@ const MenuItem: Component<MenuItemProps> = (props) => {
   // Calculate open state (compare by object reference)
   const shouldBeOpen = () => menuContext.initialOpenItems().has(props.menu);
 
-  const [open, setOpen] = createSignal(false);
+  const [open, setOpen] = createSignal(menuContext.defaultOpen);
 
   // Update open state in response to pathname change
   createEffect(() => {

package/tests/components/features/crud-sheet/CrudSheet.spec.tsx

@@ -1,4 +1,4 @@
-import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
 import type { JSX } from "solid-js";
 import { render } from "@solidjs/testing-library";
 import { CrudSheet } from "../../../../src/components/features/crud-sheet/CrudSheet";
@@ -460,3 +460,118 @@ describe("CrudSheet dialog mode", () => {
     expect(container.textContent).not.toContain("Confirm");
   });
 });
+
+describe("CrudSheet selectedKeys controllable", () => {
+  beforeEach(() => {
+    localStorage.setItem("test.i18n-locale", JSON.stringify("en"));
+  });
+
+  afterEach(() => {
+    localStorage.removeItem("test.i18n-locale");
+  });
+
+  const searchFn = () =>
+    Promise.resolve({
+      items: [
+        { id: 1, name: "홍길동", isDeleted: false },
+        { id: 2, name: "김철수", isDeleted: false },
+        { id: 3, name: "이영희", isDeleted: false },
+      ],
+      pageCount: 1,
+    });
+
+  it("controlled: selectedKeys prop sets initial selection", async () => {
+    const { container } = render(() => (
+      <ConfigProvider clientName="test"><I18nProvider>
+        <TestWrapper>
+        <CrudSheet<TestItem, Record<string, never>>
+          search={searchFn}
+          getItemKey={(item) => item.id}
+          selectionMode="multiple"
+          selectedKeys={[1, 3]}
+          onSelectedKeysChange={() => {}}
+        >
+          <CrudSheet.Column<TestItem> key="name" header="이름">
+            {(ctx) => <div>{ctx.item.name}</div>}
+          </CrudSheet.Column>
+        </CrudSheet>
+      </TestWrapper>
+      </I18nProvider></ConfigProvider>
+    ));
+
+    await new Promise((r) => setTimeout(r, 100));
+
+    const checkboxes = container.querySelectorAll('[role="checkbox"]');
+    // Header checkbox + 3 row checkboxes = 4 total
+    // Row checkboxes: index 1 (id=1, checked), index 2 (id=2, unchecked), index 3 (id=3, checked)
+    const rowCheckboxes = Array.from(checkboxes).slice(1);
+    expect(rowCheckboxes[0].getAttribute("aria-checked")).toBe("true");
+    expect(rowCheckboxes[1].getAttribute("aria-checked")).toBe("false");
+    expect(rowCheckboxes[2].getAttribute("aria-checked")).toBe("true");
+  });
+
+  it("controlled: onSelectedKeysChange is called when row checkbox is clicked", async () => {
+    const onKeysChange = vi.fn();
+
+    const { container } = render(() => (
+      <ConfigProvider clientName="test"><I18nProvider>
+        <TestWrapper>
+        <CrudSheet<TestItem, Record<string, never>>
+          search={searchFn}
+          getItemKey={(item) => item.id}
+          selectionMode="multiple"
+          selectedKeys={[]}
+          onSelectedKeysChange={onKeysChange}
+        >
+          <CrudSheet.Column<TestItem> key="name" header="이름">
+            {(ctx) => <div>{ctx.item.name}</div>}
+          </CrudSheet.Column>
+        </CrudSheet>
+      </TestWrapper>
+      </I18nProvider></ConfigProvider>
+    ));
+
+    await new Promise((r) => setTimeout(r, 100));
+
+    // Click the first row's checkbox cell (the clickable div wrapping the checkbox)
+    const checkboxCells = container.querySelectorAll('[role="checkbox"]');
+    const firstRowCheckboxCell = checkboxCells[1].parentElement;
+    firstRowCheckboxCell?.click();
+
+    await new Promise((r) => setTimeout(r, 50));
+
+    expect(onKeysChange).toHaveBeenCalled();
+    expect(onKeysChange.mock.calls[0][0]).toContain(1);
+  });
+
+  it("uncontrolled: selection works without selectedKeys prop", async () => {
+    const { container } = render(() => (
+      <ConfigProvider clientName="test"><I18nProvider>
+        <TestWrapper>
+        <CrudSheet<TestItem, Record<string, never>>
+          search={searchFn}
+          getItemKey={(item) => item.id}
+          selectionMode="multiple"
+          onSelect={() => {}}
+        >
+          <CrudSheet.Column<TestItem> key="name" header="이름">
+            {(ctx) => <div>{ctx.item.name}</div>}
+          </CrudSheet.Column>
+        </CrudSheet>
+      </TestWrapper>
+      </I18nProvider></ConfigProvider>
+    ));
+
+    await new Promise((r) => setTimeout(r, 100));
+
+    // Click the first row's checkbox cell
+    const checkboxCells = container.querySelectorAll('[role="checkbox"]');
+    const firstRowCheckboxCell = checkboxCells[1].parentElement;
+    firstRowCheckboxCell?.click();
+
+    await new Promise((r) => setTimeout(r, 50));
+
+    // Checkbox should be checked (internal state)
+    expect(checkboxCells[1].getAttribute("aria-checked")).toBe("true");
+  });
+});