@simplysm/solid 13.0.53 → 13.0.56

package/docs/helpers.md

@@ -12,45 +12,6 @@ const style = mergeStyles("color: red", { fontSize: "14px" }, props.style);
 
 ---
 
-## splitSlots
-
-Utility for splitting resolved children into named slots based on `data-*` attributes. Returns a tuple of `[slots accessor, content accessor]`.
-
-Slot keys are matched against the element's `dataset` (camelCase). Sub-components that set a matching data attribute (e.g., `data-select-header`) are separated into the named slot; all other children remain in `content`.
-
-```typescript
-import { splitSlots } from "@simplysm/solid";
-import { children } from "solid-js";
-
-// Inside a component:
-const resolved = children(() => props.children);
-const [slots, content] = splitSlots(resolved, ["selectHeader", "selectAction"] as const);
-
-// Access inside JSX (within a reactive context)
-<div>{slots().selectHeader}</div>   // HTMLElement[] matching data-select-header
-<div>{content()}</div>             // JSX.Element[] – remaining children
-```
-
-**Signature:**
-
-```typescript
-function splitSlots<K extends string>(
-  resolved: { toArray: () => unknown[] },
-  keys: readonly K[],
-): [Accessor<Record<K, HTMLElement[]>>, Accessor<JSX.Element[]>]
-```
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `resolved` | `{ toArray: () => unknown[] }` | Resolved children from SolidJS `children()` |
-| `keys` | `readonly K[]` | Slot key names (camelCase, matched against `element.dataset`) |
-
-Returns a tuple:
-- `slots` — `Accessor<Record<K, HTMLElement[]>>` — named slot elements per key
-- `content` — `Accessor<JSX.Element[]>` — remaining children not matched by any key
-
----
-
 ## ripple directive
 
 Material Design ripple effect directive. Displays ripple effect on click.

package/docs/hooks.md

@@ -163,6 +163,45 @@ setValue((prev) => prev + "!");
 
 ---
 
+## createControllableStore
+
+Store hook that automatically handles Controlled/Uncontrolled patterns for objects and arrays. Similar to `createControllableSignal` but uses SolidJS `createStore` internally, supporting path-based updates via `SetStoreFunction`.
+
+Operates in controlled mode when `onChange` is provided (setter calls `onChange` with cloned value), uncontrolled mode otherwise (internal store only).
+
+```tsx
+import { createControllableStore } from "@simplysm/solid";
+
+// Controlled mode (parent manages state)
+const [items, setItems] = createControllableStore<Item[]>({
+  value: () => props.items ?? [],
+  onChange: () => props.onItemsChange,
+});
+
+// Uncontrolled mode (internal state only)
+const [items, setItems] = createControllableStore<Item[]>({
+  value: () => [],
+  onChange: () => undefined,
+});
+
+// Supports all SetStoreFunction overloads
+setItems(0, "name", "updated");          // path-based update
+setItems(produce((draft) => { ... }));   // produce
+setItems(reconcile(newItems));           // reconcile
+```
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `value` | `() => TValue` | Reactive value accessor (syncs external changes to internal store) |
+| `onChange` | `() => ((value: TValue) => void) \| undefined` | Change callback accessor. When defined, enables controlled mode |
+
+| Return | Type | Description |
+|--------|------|-------------|
+| `[0]` | `TValue` | Store (reactive proxy) |
+| `[1]` | `SetStoreFunction<TValue>` | Store setter (triggers `onChange` in controlled mode) |
+
+---
+
 ## createMountTransition
 
 Mount transition hook for open/close CSS animations. Control DOM rendering with `mounted()` and toggle CSS classes with `animating()`.

package/docs/layout.md

@@ -127,10 +127,79 @@ const userMenus: TopbarUserMenu[] = [
 ```
 
 **Sub-components:**
-- `Topbar.Container` -- Container wrapping main content below topbar
+- `Topbar.Container` -- Container wrapping topbar and main content, provides `TopbarContext`
+- `Topbar.Actions` -- Slot outlet that renders actions registered via `createTopbarActions`
 - `Topbar.Menu` -- Menu items list
 - `Topbar.User` -- User menu (dropdown)
 
+### Topbar Actions Slot
+
+A slot pattern that lets child pages inject action buttons (save, delete, etc.) into the topbar. The parent layout defines **where** actions appear, child pages define **what** to show.
+
+**Layout (define the slot):**
+
+```tsx
+import { Topbar } from "@simplysm/solid";
+
+<Topbar.Container>
+  <Topbar>
+    <span>Title</span>
+    <Topbar.Actions />
+    <div class="flex-1" />
+  </Topbar>
+  <main class="flex-1 overflow-auto p-4">
+    {props.children}
+  </main>
+</Topbar.Container>
+```
+
+**Child page (fill the slot):**
+
+```tsx
+import { createTopbarActions, Button } from "@simplysm/solid";
+
+function UserPage() {
+  createTopbarActions(() => (
+    <>
+      <Button theme="primary">Save</Button>
+      <Button>Cancel</Button>
+    </>
+  ));
+
+  return <div>...</div>;
+}
+```
+
+When `UserPage` mounts, the buttons appear in the topbar. When it unmounts, the actions are automatically cleaned up via `onCleanup`.
+
+**createTopbarActions(accessor: () => JSX.Element): void**
+
+Registers actions in the nearest `Topbar.Container` scope. Automatically removes actions on component unmount. Must be called inside `Topbar.Container`.
+
+**useTopbarActionsAccessor(): Accessor&lt;JSX.Element | undefined&gt;**
+
+Returns the actions accessor directly. For advanced use cases such as building custom topbar components. Must be called inside `Topbar.Container`.
+
+```tsx
+import { useTopbarActionsAccessor } from "@simplysm/solid";
+
+const actions = useTopbarActionsAccessor();
+// actions() returns the currently registered JSX.Element or undefined
+```
+
+**TopbarContext:**
+
+`TopbarContext` is exported for building custom topbar layouts. `Topbar.Container` wraps children with `TopbarContext.Provider`, sharing `actions` accessor and `setActions` setter.
+
+```typescript
+import { TopbarContext } from "@simplysm/solid";
+
+interface TopbarContextValue {
+  actions: Accessor<JSX.Element | undefined>;
+  setActions: Setter<JSX.Element | undefined>;
+}
+```
+
 **TopbarMenuItem type:**
 
 ```typescript

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simplysm/solid",
-  "version": "13.0.53",
+  "version": "13.0.56",
   "description": "심플리즘 패키지 - SolidJS 라이브러리",
   "author": "김석래",
   "license": "Apache-2.0",
@@ -23,6 +23,7 @@
     "*.css"
   ],
   "dependencies": {
+    "@solid-primitives/event-listener": "^2.4.4",
     "@solid-primitives/media": "^2.3.3",
     "@solid-primitives/resize-observer": "^2.1.3",
     "@solid-primitives/storage": "^4.3.3",
@@ -49,8 +50,8 @@
     "solid-tiptap": "^0.8.0",
     "tailwind-merge": "^3.5.0",
     "tailwindcss": "^3.4.19",
-    "@simplysm/core-browser": "13.0.53",
-    "@simplysm/core-common": "13.0.53"
+    "@simplysm/core-browser": "13.0.56",
+    "@simplysm/core-common": "13.0.56"
   },
   "devDependencies": {
     "@solidjs/testing-library": "^0.8.10"

package/src/components/data/crud-detail/CrudDetail.tsx

@@ -0,0 +1,346 @@
+import {
+  children,
+  createMemo,
+  createSignal,
+  type JSX,
+  onMount,
+  Show,
+  splitProps,
+  useContext,
+} from "solid-js";
+import { reconcile, unwrap } from "solid-js/store";
+import { createControllableStore } from "../../../hooks/createControllableStore";
+import { objClone, objEqual } from "@simplysm/core-common";
+import { BusyContainer } from "../../feedback/busy/BusyContainer";
+import { useNotification } from "../../feedback/notification/NotificationContext";
+import { Button } from "../../form-control/Button";
+import { Icon } from "../../display/Icon";
+import { TopbarContext, createTopbarActions } from "../../layout/topbar/TopbarContext";
+import { useDialogInstance } from "../../disclosure/DialogInstanceContext";
+import { Dialog } from "../../disclosure/Dialog";
+import { createEventListener } from "@solid-primitives/event-listener";
+import clsx from "clsx";
+import { IconDeviceFloppy, IconRefresh, IconTrash, IconTrashOff } from "@tabler/icons-solidjs";
+import { isCrudDetailToolsDef, CrudDetailTools } from "./CrudDetailTools";
+import { isCrudDetailBeforeDef, CrudDetailBefore } from "./CrudDetailBefore";
+import { isCrudDetailAfterDef, CrudDetailAfter } from "./CrudDetailAfter";
+import type {
+  CrudDetailBeforeDef,
+  CrudDetailAfterDef,
+  CrudDetailContext,
+  CrudDetailInfo,
+  CrudDetailProps,
+  CrudDetailToolsDef,
+} from "./types";
+
+interface CrudDetailComponent {
+  <TData extends object>(props: CrudDetailProps<TData>): JSX.Element;
+  Tools: typeof CrudDetailTools;
+  Before: typeof CrudDetailBefore;
+  After: typeof CrudDetailAfter;
+}
+
+const CrudDetailBase = <TData extends object>(props: CrudDetailProps<TData>) => {
+  const [local, _rest] = splitProps(props, [
+    "load",
+    "children",
+    "submit",
+    "toggleDelete",
+    "editable",
+    "deletable",
+    "data",
+    "onDataChange",
+    "class",
+  ]);
+
+  const noti = useNotification();
+  const topbarCtx = useContext(TopbarContext);
+  const dialogInstance = useDialogInstance<boolean>();
+
+  const isModal = dialogInstance !== undefined;
+
+  const canEdit = () => local.editable ?? true;
+
+  // -- State --
+  const [data, setData] = createControllableStore<TData>({
+    value: () => local.data ?? ({} as TData),
+    onChange: () => local.onDataChange,
+  });
+  let originalData: TData | undefined;
+
+  const [info, setInfo] = createSignal<CrudDetailInfo>();
+  const [busyCount, setBusyCount] = createSignal(0);
+  const [ready, setReady] = createSignal(false);
+
+  let formRef: HTMLFormElement | undefined;
+
+  // -- Load --
+  async function doLoad() {
+    setBusyCount((c) => c + 1);
+    // eslint-disable-next-line solid/reactivity -- noti.try 내부에서 비동기 호출
+    await noti.try(async () => {
+      const result = await local.load();
+      setData(reconcile(result.data) as any);
+      originalData = objClone(result.data);
+      setInfo(result.info);
+    }, "조회 실패");
+    setBusyCount((c) => c - 1);
+    setReady(true);
+  }
+
+  onMount(() => {
+    void doLoad();
+  });
+
+  // -- Change Detection --
+  function hasChanges(): boolean {
+    if (originalData == null) return false;
+    return !objEqual(unwrap(data) as unknown, originalData as unknown);
+  }
+
+  // -- Refresh --
+  async function handleRefresh() {
+    if (hasChanges()) {
+      if (!confirm("변경사항을 무시하시겠습니까?")) return;
+    }
+    await doLoad();
+  }
+
+  // -- Save --
+  async function handleSave() {
+    if (busyCount() > 0) return;
+    if (!local.submit) return;
+
+    const currentInfo = info();
+    if (currentInfo && !currentInfo.isNew && !hasChanges()) {
+      noti.info("안내", "변경사항이 없습니다.");
+      return;
+    }
+
+    setBusyCount((c) => c + 1);
+    // eslint-disable-next-line solid/reactivity -- noti.try 내부에서 비동기 호출
+    await noti.try(async () => {
+      const result = await local.submit!(objClone(unwrap(data)));
+      if (result) {
+        noti.success("저장 완료", "저장되었습니다.");
+        if (dialogInstance) {
+          dialogInstance.close(true);
+        } else {
+          await doLoad();
+        }
+      }
+    }, "저장 실패");
+    setBusyCount((c) => c - 1);
+  }
+
+  async function handleFormSubmit(e: Event) {
+    e.preventDefault();
+    await handleSave();
+  }
+
+  // -- Toggle Delete --
+  async function handleToggleDelete() {
+    if (busyCount() > 0) return;
+    if (!local.toggleDelete) return;
+
+    const currentInfo = info();
+    if (!currentInfo) return;
+
+    const del = !currentInfo.isDeleted;
+
+    setBusyCount((c) => c + 1);
+    /* eslint-disable solid/reactivity -- noti.try 내부에서 비동기 호출 */
+    await noti.try(
+      async () => {
+        const result = await local.toggleDelete!(del);
+        if (result) {
+          noti.success(
+            del ? "삭제 완료" : "복구 완료",
+            del ? "삭제되었습니다." : "복구되었습니다.",
+          );
+          if (dialogInstance) {
+            dialogInstance.close(true);
+          } else {
+            await doLoad();
+          }
+        }
+      },
+      del ? "삭제 실패" : "복구 실패",
+    );
+    /* eslint-enable solid/reactivity */
+    setBusyCount((c) => c - 1);
+  }
+
+  // -- Keyboard Shortcuts --
+  createEventListener(document, "keydown", (e: KeyboardEvent) => {
+    if (e.ctrlKey && e.key === "s") {
+      e.preventDefault();
+      formRef?.requestSubmit();
+    }
+    if (e.ctrlKey && e.altKey && e.key === "l") {
+      e.preventDefault();
+      void handleRefresh();
+    }
+  });
+
+  // -- Topbar Actions (Page mode) --
+  if (topbarCtx) {
+    createTopbarActions(() => (
+      <>
+        <Show when={canEdit() && local.submit}>
+          <Button
+            size="lg"
+            variant="ghost"
+            theme="primary"
+            onClick={() => formRef?.requestSubmit()}
+          >
+            <Icon icon={IconDeviceFloppy} class="mr-1" />
+            저장
+          </Button>
+        </Show>
+        <Button size="lg" variant="ghost" theme="info" onClick={() => void handleRefresh()}>
+          <Icon icon={IconRefresh} class="mr-1" />
+          새로고침
+        </Button>
+      </>
+    ));
+  }
+
+  // -- Context --
+  const ctx: CrudDetailContext<TData> = {
+    data,
+    setData,
+    info: () => info()!,
+    busy: () => busyCount() > 0,
+    hasChanges,
+    save: handleSave,
+    refresh: handleRefresh,
+  };
+
+  // -- Children Resolution --
+  const rendered = children(() => local.children(ctx));
+  const defs = createMemo(() => {
+    const arr = rendered.toArray();
+    return {
+      tools: arr.find(isCrudDetailToolsDef) as CrudDetailToolsDef | undefined,
+      before: arr.find(isCrudDetailBeforeDef) as CrudDetailBeforeDef | undefined,
+      after: arr.find(isCrudDetailAfterDef) as CrudDetailAfterDef | undefined,
+    };
+  });
+
+  const formContent = () =>
+    rendered
+      .toArray()
+      .filter(
+        (el) =>
+          !isCrudDetailToolsDef(el) && !isCrudDetailBeforeDef(el) && !isCrudDetailAfterDef(el),
+      );
+
+  // -- Render --
+  return (
+    <>
+      {/* Modal mode: Dialog.Action (refresh button in header) */}
+      <Show when={isModal}>
+        <Dialog.Action>
+          <button
+            class="flex items-center px-2 text-base-400 hover:text-base-600"
+            onClick={() => void handleRefresh()}
+          >
+            <Icon icon={IconRefresh} />
+          </button>
+        </Dialog.Action>
+      </Show>
+
+      <BusyContainer
+        ready={ready()}
+        busy={busyCount() > 0}
+        class={clsx("flex h-full flex-col", local.class)}
+      >
+        {/* Toolbar (page/control mode) */}
+        <Show when={!isModal && canEdit()}>
+          <div class="flex gap-2 p-2 pb-0">
+            <Show when={local.submit}>
+              <Button
+                size="sm"
+                theme="primary"
+                variant="ghost"
+                onClick={() => formRef?.requestSubmit()}
+              >
+                <Icon icon={IconDeviceFloppy} class="mr-1" />
+                저장
+              </Button>
+            </Show>
+            <Button size="sm" theme="info" variant="ghost" onClick={() => void handleRefresh()}>
+              <Icon icon={IconRefresh} class="mr-1" />
+              새로고침
+            </Button>
+            <Show
+              when={local.toggleDelete && info() && !info()!.isNew && (local.deletable ?? true)}
+            >
+              {(_) => (
+                <Button
+                  size="sm"
+                  theme="danger"
+                  variant="ghost"
+                  onClick={() => void handleToggleDelete()}
+                >
+                  <Icon icon={info()!.isDeleted ? IconTrashOff : IconTrash} class="mr-1" />
+                  {info()!.isDeleted ? "복구" : "삭제"}
+                </Button>
+              )}
+            </Show>
+            <Show when={defs().tools}>{(toolsDef) => toolsDef().children}</Show>
+          </div>
+        </Show>
+
+        {/* Before (outside form) */}
+        <Show when={defs().before}>{(beforeDef) => beforeDef().children}</Show>
+
+        {/* Form */}
+        <form ref={formRef} class="flex-1 overflow-auto p-2" onSubmit={handleFormSubmit}>
+          {formContent()}
+        </form>
+
+        {/* Last modified info */}
+        <Show when={info()?.lastModifiedAt}>
+          {(_) => (
+            <div class="px-2 pb-1 text-xs text-base-400">
+              최종 수정: {info()!.lastModifiedAt!.toFormatString("yyyy-MM-dd HH:mm")}
+              <Show when={info()?.lastModifiedBy}> ({info()!.lastModifiedBy})</Show>
+            </div>
+          )}
+        </Show>
+
+        {/* After (outside form) */}
+        <Show when={defs().after}>{(afterDef) => afterDef().children}</Show>
+
+        {/* Modal mode: bottom bar */}
+        <Show when={isModal && canEdit()}>
+          <div class="flex gap-2 border-t border-base-200 p-2">
+            <div class="flex-1" />
+            <Show
+              when={local.toggleDelete && info() && !info()!.isNew && (local.deletable ?? true)}
+            >
+              {(_) => (
+                <Button size="sm" theme="danger" onClick={() => void handleToggleDelete()}>
+                  <Icon icon={info()!.isDeleted ? IconTrashOff : IconTrash} class="mr-1" />
+                  {info()!.isDeleted ? "복구" : "삭제"}
+                </Button>
+              )}
+            </Show>
+            <Show when={local.submit}>
+              <Button size="sm" theme="primary" onClick={() => formRef?.requestSubmit()}>
+                확인
+              </Button>
+            </Show>
+          </div>
+        </Show>
+      </BusyContainer>
+    </>
+  );
+};
+
+export const CrudDetail = CrudDetailBase as unknown as CrudDetailComponent;
+CrudDetail.Tools = CrudDetailTools;
+CrudDetail.Before = CrudDetailBefore;
+CrudDetail.After = CrudDetailAfter;

package/src/components/data/crud-detail/CrudDetailAfter.tsx

@@ -0,0 +1,19 @@
+import type { JSX } from "solid-js";
+import type { CrudDetailAfterDef } from "./types";
+
+export function isCrudDetailAfterDef(value: unknown): value is CrudDetailAfterDef {
+  return (
+    value != null &&
+    typeof value === "object" &&
+    (value as Record<string, unknown>)["__type"] === "crud-detail-after"
+  );
+}
+
+/* eslint-disable solid/reactivity -- plain object 반환 패턴으로 reactive context 불필요 */
+export function CrudDetailAfter(props: { children: JSX.Element }): JSX.Element {
+  return {
+    __type: "crud-detail-after",
+    children: props.children,
+  } as unknown as JSX.Element;
+}
+/* eslint-enable solid/reactivity */

package/src/components/data/crud-detail/CrudDetailBefore.tsx

@@ -0,0 +1,19 @@
+import type { JSX } from "solid-js";
+import type { CrudDetailBeforeDef } from "./types";
+
+export function isCrudDetailBeforeDef(value: unknown): value is CrudDetailBeforeDef {
+  return (
+    value != null &&
+    typeof value === "object" &&
+    (value as Record<string, unknown>)["__type"] === "crud-detail-before"
+  );
+}
+
+/* eslint-disable solid/reactivity -- plain object 반환 패턴으로 reactive context 불필요 */
+export function CrudDetailBefore(props: { children: JSX.Element }): JSX.Element {
+  return {
+    __type: "crud-detail-before",
+    children: props.children,
+  } as unknown as JSX.Element;
+}
+/* eslint-enable solid/reactivity */

package/src/components/data/crud-detail/CrudDetailTools.tsx

@@ -0,0 +1,19 @@
+import type { JSX } from "solid-js";
+import type { CrudDetailToolsDef } from "./types";
+
+export function isCrudDetailToolsDef(value: unknown): value is CrudDetailToolsDef {
+  return (
+    value != null &&
+    typeof value === "object" &&
+    (value as Record<string, unknown>)["__type"] === "crud-detail-tools"
+  );
+}
+
+/* eslint-disable solid/reactivity -- plain object 반환 패턴으로 reactive context 불필요 */
+export function CrudDetailTools(props: { children: JSX.Element }): JSX.Element {
+  return {
+    __type: "crud-detail-tools",
+    children: props.children,
+  } as unknown as JSX.Element;
+}
+/* eslint-enable solid/reactivity */

package/src/components/data/crud-detail/types.ts

@@ -0,0 +1,58 @@
+import type { JSX } from "solid-js";
+import type { SetStoreFunction } from "solid-js/store";
+import type { DateTime } from "@simplysm/core-common";
+
+// ── Detail Info ──
+
+export interface CrudDetailInfo {
+  isNew: boolean;
+  isDeleted: boolean;
+  lastModifiedAt?: DateTime;
+  lastModifiedBy?: string;
+}
+
+// ── Context ──
+
+export interface CrudDetailContext<TData> {
+  data: TData;
+  setData: SetStoreFunction<TData>;
+  info: () => CrudDetailInfo;
+  busy: () => boolean;
+  hasChanges: () => boolean;
+  save: () => Promise<void>;
+  refresh: () => Promise<void>;
+}
+
+// ── Props ──
+
+export interface CrudDetailProps<TData extends object> {
+  load: () => Promise<{ data: TData; info: CrudDetailInfo }>;
+  children: (ctx: CrudDetailContext<TData>) => JSX.Element;
+
+  submit?: (data: TData) => Promise<boolean | undefined>;
+  toggleDelete?: (del: boolean) => Promise<boolean | undefined>;
+  editable?: boolean;
+  deletable?: boolean;
+
+  data?: TData;
+  onDataChange?: (data: TData) => void;
+
+  class?: string;
+}
+
+// ── Sub-component Defs ──
+
+export interface CrudDetailToolsDef {
+  __type: "crud-detail-tools";
+  children: JSX.Element;
+}
+
+export interface CrudDetailBeforeDef {
+  __type: "crud-detail-before";
+  children: JSX.Element;
+}
+
+export interface CrudDetailAfterDef {
+  __type: "crud-detail-after";
+  children: JSX.Element;
+}