@wipco/sdui 0.16.0 → 0.17.1

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import * as React from 'react';
 import React__default, { CSSProperties, ReactNode, ComponentType } from 'react';
-import { S as SduiAction, a as SduiPropValue, b as SduiRule, c as SduiPage } from './types-CeUhMB9Q.js';
-export { d as SduiCalcRef, e as SduiChild, f as SduiIndexRef, g as SduiItemRef, h as SduiNode, i as SduiPageQuery, j as SduiScalar, k as SduiStateRef } from './types-CeUhMB9Q.js';
+import { S as SduiPage, a as SduiAction, b as SduiPropValue, c as SduiRule } from './types-opTPYysN.js';
+export { d as SduiArgRef, e as SduiCalcRef, f as SduiChild, g as SduiIndexRef, h as SduiItemRef, i as SduiNode, j as SduiPageQuery, k as SduiScalar, l as SduiStateRef } from './types-opTPYysN.js';
 import { S as SduiBoxProps, a as SduiContainerLayoutProps, b as SduiColumnsScale, c as SduiGapScale, d as SduiWeightScale, e as SduiTextAlignScale } from './layout-B1QrIBm6.js';
 export { C as CHILD_LAYOUT_PROPS, L as LAYOUT_CSS, f as SduiAlignScale, g as SduiChildLayoutProps, h as SduiSizeScale, i as SduiSpanScale, j as childLayoutFrom, k as columnsClass, l as containerLayoutStyle, m as joinClass, n as mergeStyle, t as typographyStyle } from './layout-B1QrIBm6.js';
 import { D as DatePickerProps, a as DateRangePickerProps } from './DatePicker-BndreCPl.js';
@@ -40,6 +40,28 @@ interface SduiAdapter {
      * 반환값은 구독 해제 함수.
      */
     subscribe?: (channels: string[], onEvent: () => void) => () => void;
+    /**
+     * Fragment 노드가 id로 다른 스펙을 가져올 때 부르는 **훅**이다.
+     *
+     * 반환 계약: `undefined` = 로딩 중(아무것도 그리지 않음), `null` = 없음/실패,
+     * 그 외 = 스펙(body만 쓰인다 — data/urlState/subscribe는 무시).
+     *
+     * 훅인 이유: 요구가 "스펙 캐시 무효화(SSE) → 자동 리렌더"인데, 이는 외부 스토어
+     * 구독 문제라 호스트가 이미 가진 조회 훅(TanStack Query 등)이 정답이다.
+     * ERP 호스트는 한 줄로 잇는다:
+     *   useSpec: (id) => { const q = useQuery(specQuery(id)); return q.isPending ? undefined : (q.data ?? null); }
+     *
+     * 콜백 대안(`loadSpec(id): Promise<…>` + 구독)은 겉모양이 기존 어댑터 관용구에 더
+     * 맞지만 버렸다 — 렌더러가 id별 캐시·구독 대장·재조회를 자체 보유해야 해서 ERP의
+     * ETag/IndexedDB/SSE 완비 캐시와 **이중 캐시**가 되고, sandbox 주석이 실측으로 경고한
+     * "빈 응답이 전역 캐시에 실려 진짜 페이지를 오염" 류의 사고 표면이 그대로 생긴다.
+     *
+     * 훅 계약(호스트가 지켜야 한다):
+     *  - 렌더마다 같은 훅을 같은 순서로 부른다(내부 조건부 훅 금지).
+     *  - 어댑터 객체 정체성을 렌더 중에 갈아 끼우지 않는다(렌더러가 useMemo로 잡고 있지만,
+     *    useSpec이 있다가 없어지는 교체는 훅 순서 위반이다).
+     */
+    useSpec?: (id: string) => SduiPage | null | undefined;
     /**
      * urlState 반영 시 URL 쿼리 교체를 위임한다 — react-router 호스트라면
      * setSearchParams(params, { replace: true })를 연결해 라우터 구독자와
@@ -109,6 +131,8 @@ interface SduiAssetContext {
     cssProperty?: string;
 }
 type SduiAssetResolver = (url: string, ctx: SduiAssetContext) => string | null;
+/** {@link SduiAdapter.useSpec} 구현체의 편의 타입 — 호스트가 훅을 따로 정의해 꽂을 때 쓴다. */
+type SduiUseSpec = NonNullable<SduiAdapter['useSpec']>;
 declare const defaultAdapter: Required<Pick<SduiAdapter, 'navigate' | 'fetch' | 'rawFetch' | 'resolveAsset'>> & SduiAdapter;
 /**
  * **스스로 URL을 만드는 컴포넌트**를 위한 자산 관문.
@@ -1771,4 +1795,4 @@ interface ImageViewerProps {
  */
 declare function ImageViewer({ src, alt, open, onClose }: ImageViewerProps): React__default.ReactPortal | null;
 
-export { Actions, type ActionsProps, Alert, type AlertProps, Avatar, type AvatarProps, Badge, type BadgeProps, type BadgeTone, Breadcrumb, type BreadcrumbItem, type BreadcrumbProps, Button, type ButtonProps, Can, type CanProps, Card, type CardProps, type CascadingSearchOption, Checkbox, type CheckboxProps, Col, type ColProps, type CustomActionHandler, type CustomValidator, DatePickerProps, DateRangePickerProps, Dialog, type DialogProps, Divider, EmptyState, type EmptyStateProps, Field, type FieldProps, Grid, type GridCardConfig, type GridCardRow, type GridProps, Icon, IconButton, type IconButtonProps, type IconProps, ImageViewer, type ImageViewerProps, Input, type InputProps, type Justify, type KeyValueItem, KeyValueList, type KeyValueListProps, type MeterTone, NodeErrorBoundary, PageHead, type PageHeadProps, Pagination, type PaginationProps, ProgressBar, type ProgressBarProps, Radio, type RadioProps, RemoteSearchResults, type RemoteSearchResultsProps, ResultTable, type ResultTableColumn, type ResultTableProps, Row, type RowProps, SduiAction, type SduiAdapter, type SduiAssetContext, type SduiAssetResolver, type SduiBadgeCell, SduiBoxProps, type SduiCanFn, type SduiCanQuery, type SduiCanSetting, type SduiCell, SduiColumnsScale, SduiContainerLayoutProps, type SduiDateCell, SduiDialog, type SduiDispatch, SduiForm, type SduiFormConfig, type SduiFormProps, SduiGapScale, type SduiGridCard, type SduiGridCardAction, type SduiGridCardRow, type SduiIconCell, type SduiImageCell, type SduiLinkCell, type SduiNumberCell, SduiPage, SduiPermissionProvider, type SduiProgressCell, SduiPropValue, type SduiRegistry, SduiRenderer, type SduiRendererProps, type SduiRowCondition, SduiRule, type SduiRuntime, type SduiSearchAction, type SduiSearchColumn, SduiSearchDataProvider, SduiSearchResults, type SduiSearchResultsProps, type SduiTagCell, SduiTextAlignScale, type SduiTextCell, SduiWeightScale, type SearchAction, type SearchColumn, type SearchFetcher, type SearchField, type SearchFilter, type SearchOption, type SearchPage, SearchResults, type SearchResultsProps, type SearchRow, SearchToolbar, type SearchValues, type SearchViewItem, Section, type SectionProps, SegmentedControl, type SegmentedControlProps, type SegmentedItem, Select, type SelectOption, type SelectOptionRecord, type SelectProps, Show, type ShowProps, SidebarNav, type SidebarNavItem, type SidebarNavProps, type SidebarNavSection, type SortDir, SortHandle, type SortHandleProps, SortableList, type SortableListProps, Spacer, type SpacerProps, type SpecIssue, Spinner, type SpinnerProps, StatCard, type StatCardProps, Switch, type SwitchProps, type TabItem, Table, type TableColumn, type TableProps, Tabs, type TabsProps, Tag, type TagProps, Text, type TextPreset, type TextProps, Textarea, type TextareaProps, Toast, type ToastProps, Tooltip, type TooltipProps, boxed, cascadingValuePaths, cellRenderer, cleanSearchValues, createRegistry, defaultAdapter, defaultRegistry, imageRenderer, includesLooseSearch, joinMultiValue, normalizePageSizes, normalizeSearchText, searchFieldKeys, searchValuesFromParams, sortableDropIndex, sortableMove, splitMultiValue, useRemoteSearchPage, useSduiAssetResolver, useSduiCan, useSduiDispatch, useSduiRuntime, useSduiSandbox, useSearchFetcher, validateSpec };
+export { Actions, type ActionsProps, Alert, type AlertProps, Avatar, type AvatarProps, Badge, type BadgeProps, type BadgeTone, Breadcrumb, type BreadcrumbItem, type BreadcrumbProps, Button, type ButtonProps, Can, type CanProps, Card, type CardProps, type CascadingSearchOption, Checkbox, type CheckboxProps, Col, type ColProps, type CustomActionHandler, type CustomValidator, DatePickerProps, DateRangePickerProps, Dialog, type DialogProps, Divider, EmptyState, type EmptyStateProps, Field, type FieldProps, Grid, type GridCardConfig, type GridCardRow, type GridProps, Icon, IconButton, type IconButtonProps, type IconProps, ImageViewer, type ImageViewerProps, Input, type InputProps, type Justify, type KeyValueItem, KeyValueList, type KeyValueListProps, type MeterTone, NodeErrorBoundary, PageHead, type PageHeadProps, Pagination, type PaginationProps, ProgressBar, type ProgressBarProps, Radio, type RadioProps, RemoteSearchResults, type RemoteSearchResultsProps, ResultTable, type ResultTableColumn, type ResultTableProps, Row, type RowProps, SduiAction, type SduiAdapter, type SduiAssetContext, type SduiAssetResolver, type SduiBadgeCell, SduiBoxProps, type SduiCanFn, type SduiCanQuery, type SduiCanSetting, type SduiCell, SduiColumnsScale, SduiContainerLayoutProps, type SduiDateCell, SduiDialog, type SduiDispatch, SduiForm, type SduiFormConfig, type SduiFormProps, SduiGapScale, type SduiGridCard, type SduiGridCardAction, type SduiGridCardRow, type SduiIconCell, type SduiImageCell, type SduiLinkCell, type SduiNumberCell, SduiPage, SduiPermissionProvider, type SduiProgressCell, SduiPropValue, type SduiRegistry, SduiRenderer, type SduiRendererProps, type SduiRowCondition, SduiRule, type SduiRuntime, type SduiSearchAction, type SduiSearchColumn, SduiSearchDataProvider, SduiSearchResults, type SduiSearchResultsProps, type SduiTagCell, SduiTextAlignScale, type SduiTextCell, type SduiUseSpec, SduiWeightScale, type SearchAction, type SearchColumn, type SearchFetcher, type SearchField, type SearchFilter, type SearchOption, type SearchPage, SearchResults, type SearchResultsProps, type SearchRow, SearchToolbar, type SearchValues, type SearchViewItem, Section, type SectionProps, SegmentedControl, type SegmentedControlProps, type SegmentedItem, Select, type SelectOption, type SelectOptionRecord, type SelectProps, Show, type ShowProps, SidebarNav, type SidebarNavItem, type SidebarNavProps, type SidebarNavSection, type SortDir, SortHandle, type SortHandleProps, SortableList, type SortableListProps, Spacer, type SpacerProps, type SpecIssue, Spinner, type SpinnerProps, StatCard, type StatCardProps, Switch, type SwitchProps, type TabItem, Table, type TableColumn, type TableProps, Tabs, type TabsProps, Tag, type TagProps, Text, type TextPreset, type TextProps, Textarea, type TextareaProps, Toast, type ToastProps, Tooltip, type TooltipProps, boxed, cascadingValuePaths, cellRenderer, cleanSearchValues, createRegistry, defaultAdapter, defaultRegistry, imageRenderer, includesLooseSearch, joinMultiValue, normalizePageSizes, normalizeSearchText, searchFieldKeys, searchValuesFromParams, sortableDropIndex, sortableMove, splitMultiValue, useRemoteSearchPage, useSduiAssetResolver, useSduiCan, useSduiDispatch, useSduiRuntime, useSduiSandbox, useSearchFetcher, validateSpec };

package/dist/index.js

@@ -8,7 +8,7 @@ import { EmptyState, Button, Checkbox, SegmentedControl, Spinner, Select, Pagina
 export { Alert, Avatar, Badge, Breadcrumb, Button, Card, Checkbox, Dialog, EmptyState, Field, Icon, IconButton, Input, Pagination, ProgressBar, Radio, SegmentedControl, Select, SidebarNav, Spinner, StatCard, Switch, Table, Tabs, Tag, Textarea, Toast, Tooltip } from './chunk-WIDDHR7L.js';
 import { boxed, mergeStyle, containerLayoutStyle, joinClass, columnsClass, typographyStyle, LAYOUT_CSS, childLayoutFrom, CHILD_LAYOUT_PROPS } from './chunk-SAN4IX6N.js';
 export { CHILD_LAYOUT_PROPS, LAYOUT_CSS, boxed, childLayoutFrom, columnsClass, containerLayoutStyle, joinClass, mergeStyle, typographyStyle } from './chunk-SAN4IX6N.js';
-import React, { createContext, useState, useMemo, useContext, useRef, useEffect, useCallback } from 'react';
+import React11, { createContext, useState, useMemo, useContext, useRef, useEffect, useCallback } from 'react';
 import { jsxs, jsx, Fragment } from 'react/jsx-runtime';
 
 // src/asset-url.ts
@@ -113,7 +113,7 @@ function useSduiDispatch() {
   }
   return dispatch;
 }
-var NodeErrorBoundary = class extends React.Component {
+var NodeErrorBoundary = class extends React11.Component {
   state = { error: null };
   static getDerivedStateFromError(error) {
     return { error };
@@ -300,7 +300,7 @@ function KeyValueList({ source, items, className, style }) {
   return /* @__PURE__ */ jsx("div", { className: joinClass("wp-kv", className), style, children: (items ?? []).map((item, index) => {
     const raw = item.key ? source?.[item.key] : item.value;
     const content = raw === null || raw === void 0 || raw === "" ? "\u2014" : raw;
-    return /* @__PURE__ */ jsxs(React.Fragment, { children: [
+    return /* @__PURE__ */ jsxs(React11.Fragment, { children: [
       /* @__PURE__ */ jsx("span", { className: "wp-kv__k", children: item.label }),
       /* @__PURE__ */ jsx("span", { className: joinClass("wp-kv__v", item.mono && "wp-mono"), children: content })
     ] }, index);
@@ -1866,6 +1866,7 @@ var RULE_NAMES = /* @__PURE__ */ new Set([
   "notBeforeField",
   "custom"
 ]);
+var RENDERER_BUILTINS = /* @__PURE__ */ new Set(["ForEach", "Fragment"]);
 var DENIED_PROPS = /* @__PURE__ */ new Set([
   "dangerouslySetInnerHTML",
   "ref",
@@ -1952,7 +1953,7 @@ function walkChild(child, path, issues, known) {
     issues.push({ path, message: "component\uB294 \uBE44\uC5B4 \uC788\uC9C0 \uC54A\uC740 \uBB38\uC790\uC5F4\uC774\uC5B4\uC57C \uD569\uB2C8\uB2E4" });
     return;
   }
-  if (known && node.component !== "ForEach" && !known.has(node.component)) {
+  if (known && !RENDERER_BUILTINS.has(node.component) && !known.has(node.component)) {
     issues.push({ path, message: `\uB4F1\uB85D\uB418\uC9C0 \uC54A\uC740 \uCEF4\uD3EC\uB10C\uD2B8: ${node.component}` });
   }
   if (node.props !== void 0 && !isPlainObject(node.props)) {
@@ -1981,6 +1982,28 @@ function walkChild(child, path, issues, known) {
       }
     }
   }
+  if (node.component === "Fragment") {
+    const id = isPlainObject(node.props) ? node.props.id : void 0;
+    if ((typeof id !== "string" || id === "") && !isPlainObject(id)) {
+      issues.push({
+        path: `${path}.props.id`,
+        message: "Fragment.id\uB294 \uBE44\uC5B4 \uC788\uC9C0 \uC54A\uC740 \uBB38\uC790\uC5F4(\uB610\uB294 \uAC12 \uCC38\uC870)\uC774\uC5B4\uC57C \uD569\uB2C8\uB2E4"
+      });
+    }
+    const args = isPlainObject(node.props) ? node.props.args : void 0;
+    if (args !== void 0 && !isPlainObject(args)) {
+      issues.push({
+        path: `${path}.props.args`,
+        message: "Fragment.args\uB294 { \uC774\uB984: \uAC12 } \uD3C9\uBA74 \uC624\uBE0C\uC81D\uD2B8\uC5EC\uC57C \uD569\uB2C8\uB2E4"
+      });
+    }
+    if (node.children !== void 0 || node.slots !== void 0) {
+      issues.push({
+        path,
+        message: "Fragment\uB294 children/slots\uB97C \uB80C\uB354\uD558\uC9C0 \uC54A\uC2B5\uB2C8\uB2E4 \u2014 \uC870\uAC01 \uC2A4\uD399\uC758 body\uAC00 \uADF8\uB824\uC9D1\uB2C8\uB2E4"
+      });
+    }
+  }
   if (node.slots !== void 0) {
     if (!isPlainObject(node.slots)) {
       issues.push({ path: `${path}.slots`, message: "slots\uB294 \uAC1D\uCCB4\uC5EC\uC57C \uD569\uB2C8\uB2E4" });
@@ -2029,6 +2052,9 @@ function walkValue(value, path, issues, actionEligible) {
   if ("$state" in value && typeof value.$state !== "string") {
     issues.push({ path, message: "$state\uB294 \uBB38\uC790\uC5F4 \uD0A4\uC5EC\uC57C \uD569\uB2C8\uB2E4" });
   }
+  if ("$arg" in value && typeof value.$arg !== "string") {
+    issues.push({ path, message: "$arg\uB294 \uBB38\uC790\uC5F4 \uC774\uB984\uC774\uC5B4\uC57C \uD569\uB2C8\uB2E4" });
+  }
   if ("$calc" in value) {
     const calc = value.$calc;
     if (!isPlainObject(calc) || typeof calc.op !== "string" || !CALC_OPS.has(calc.op)) {
@@ -2124,6 +2150,23 @@ function revertUnsettledStamps(fetched, runnable, epochs, settled) {
     if (fetched.get(plan.key) === planStamp(plan, epochs)) fetched.delete(plan.key);
   }
 }
+function isArgsFrame(frame) {
+  return "callSiteScope" in frame;
+}
+function nearestItemFrame(scope) {
+  for (let i = scope.length - 1; i >= 0; i--) {
+    const frame = scope[i];
+    if (!isArgsFrame(frame)) return frame;
+  }
+  return void 0;
+}
+function nearestArgsFrame(scope) {
+  for (let i = scope.length - 1; i >= 0; i--) {
+    const frame = scope[i];
+    if (isArgsFrame(frame)) return frame;
+  }
+  return void 0;
+}
 function isPlainObject3(v) {
   return typeof v === "object" && v !== null && !Array.isArray(v);
 }
@@ -2139,12 +2182,33 @@ function isIndexRef(v) {
 function isCalcRef(v) {
   return isPlainObject3(v) && isPlainObject3(v.$calc);
 }
+function isArgRef(v) {
+  return isPlainObject3(v) && typeof v.$arg === "string";
+}
 function isAction(v) {
   return isPlainObject3(v) && typeof v.action === "string";
 }
 function isActionList(v) {
   return Array.isArray(v) && v.length > 0 && v.every(isAction);
 }
+function isActionEntryList(v) {
+  return Array.isArray(v) && v.length > 0 && v.every((x) => isAction(x) || isArgRef(x));
+}
+function expandActionEntries(raw, scope) {
+  if (Array.isArray(raw)) return raw.flatMap((v) => expandActionEntries(v, scope));
+  if (isArgRef(raw)) {
+    const frame = nearestArgsFrame(scope);
+    if (frame?.args && Object.hasOwn(frame.args, raw.$arg)) {
+      return expandActionEntries(frame.args[raw.$arg], frame.callSiteScope);
+    }
+    if (raw.default !== void 0) return expandActionEntries(raw.default, scope);
+    return [];
+  }
+  if (isAction(raw)) return [{ action: raw, scope }];
+  if (raw === void 0 || raw === null) return [];
+  warnOnce2(`action-entry:${typeof raw}`, "[sdui] \uC561\uC158 \uC790\uB9AC\uC5D0 \uC561\uC158\uC774 \uC544\uB2CC \uAC12\uC774 \uC788\uC2B5\uB2C8\uB2E4 \u2014 \uBB34\uC2DC\uD569\uB2C8\uB2E4");
+  return [];
+}
 function eventValue(arg) {
   if (isPlainObject3(arg) && "target" in arg && typeof arg.preventDefault === "function") {
     const target = arg.target;
@@ -2294,9 +2358,12 @@ function SduiNodeRenderer({
     return /* @__PURE__ */ jsx(Fragment, { children: rows.map((item, rowIndex) => {
       const rowScope = [...scope, { item, index: rowIndex }];
       const rowKey = isPlainObject3(item) && typeof item.id === "string" ? item.id : rowIndex;
-      return /* @__PURE__ */ jsx(React.Fragment, { children: childList?.map((child, i) => renderChild(child, i, rowScope, engine)) }, rowKey);
+      return /* @__PURE__ */ jsx(React11.Fragment, { children: childList?.map((child, i) => renderChild(child, i, rowScope, engine)) }, rowKey);
     }) });
   }
+  if (node.component === "Fragment") {
+    return /* @__PURE__ */ jsx(SduiFragment, { node, scope, engine });
+  }
   const Component = typeof node.component === "string" && Object.hasOwn(registry, node.component) ? registry[node.component] : void 0;
   if (!Component) {
     warnOnce2(
@@ -2314,13 +2381,18 @@ function SduiNodeRenderer({
       warnOnce2(`prop:${name}`, `[sdui] \uC2A4\uD399\uC5D0\uC11C \uD5C8\uC6A9\uB418\uC9C0 \uC54A\uB294 \uD504\uB86D: ${name} \u2014 \uBB34\uC2DC\uD569\uB2C8\uB2E4`);
       continue;
     }
-    if (name.startsWith("on") && (isAction(raw) || isActionList(raw))) {
-      const actions = isActionList(raw) ? raw : [raw];
-      props[name] = (arg) => actions.forEach(
-        (a) => dispatch(resolveValue(a, scope), arg)
+    if (name.startsWith("on") && (isAction(raw) || isArgRef(raw) || isActionEntryList(raw))) {
+      props[name] = (arg) => expandActionEntries(raw, scope).forEach(
+        (entry) => dispatch(
+          resolveValue(entry.action, entry.scope),
+          arg,
+          entry.scope
+        )
       );
     } else if (name === "rowClick" && (isAction(raw) || isActionList(raw))) {
       props[name] = raw;
+    } else if (name === "rowClick" && (isArgRef(raw) || isActionEntryList(raw))) {
+      props[name] = expandActionEntries(raw, scope).map((entry) => entry.action);
     } else {
       let resolved = resolveValue(raw, scope);
       if (resolved === null) {
@@ -2362,6 +2434,87 @@ function SduiNodeRenderer({
   const children = childList?.map((child, i) => renderChild(child, i, scope, engine));
   return /* @__PURE__ */ jsx(Component, { ...props, children });
 }
+var SduiFragmentChainContext = React11.createContext([]);
+var FRAGMENT_MAX_DEPTH = 4;
+function SduiFragment({ node, scope, engine }) {
+  const adapter = useSduiAdapter();
+  const chain = React11.useContext(SduiFragmentChainContext);
+  const raw = isPlainObject3(node.props) ? node.props.id : void 0;
+  const id = engine.resolveValue(raw, scope);
+  if (typeof id !== "string" || id === "") {
+    warnOnce2("fragment:id", "[sdui] <Fragment>\uC5D0 \uBB38\uC790\uC5F4 id\uAC00 \uC5C6\uC2B5\uB2C8\uB2E4 \u2014 \uB80C\uB354\uD558\uC9C0 \uC54A\uC2B5\uB2C8\uB2E4");
+    return null;
+  }
+  if (chain.includes(id)) {
+    warnOnce2(
+      `fragment:cycle:${id}`,
+      `[sdui] Fragment \uC21C\uD658 \uCC38\uC870: ${[...chain, id].join(" \u2192 ")} \u2014 \uC7AC\uC9C4\uC785\uC744 \uAC70\uBD80\uD569\uB2C8\uB2E4`
+    );
+    return null;
+  }
+  if (chain.length >= FRAGMENT_MAX_DEPTH) {
+    warnOnce2(
+      `fragment:depth:${id}`,
+      `[sdui] Fragment \uC911\uCCA9\uC774 ${FRAGMENT_MAX_DEPTH}\uB2E8\uC744 \uB118\uC2B5\uB2C8\uB2E4(${[...chain, id].join(" \u2192 ")}) \u2014 \uB80C\uB354\uD558\uC9C0 \uC54A\uC2B5\uB2C8\uB2E4`
+    );
+    return null;
+  }
+  const rawArgs = isPlainObject3(node.props) ? node.props.args : void 0;
+  if (rawArgs !== void 0 && !isPlainObject3(rawArgs)) {
+    warnOnce2(`fragment:args:${id}`, `[sdui] <Fragment ${id}>\uC758 args\uB294 \uD3C9\uBA74 \uC624\uBE0C\uC81D\uD2B8\uC5EC\uC57C \uD569\uB2C8\uB2E4 \u2014 \uBB34\uC2DC\uD569\uB2C8\uB2E4`);
+  }
+  const useSpec = adapter?.useSpec;
+  if (!useSpec) {
+    warnOnce2(
+      "fragment:no-useSpec",
+      "[sdui] Fragment\uB97C \uC4F0\uB824\uBA74 \uC5B4\uB311\uD130\uC5D0 useSpec(id)\uC774 \uD544\uC694\uD569\uB2C8\uB2E4 \u2014 \uB80C\uB354\uD558\uC9C0 \uC54A\uC2B5\uB2C8\uB2E4"
+    );
+    return null;
+  }
+  return /* @__PURE__ */ jsx(
+    SduiFragmentBody,
+    {
+      id,
+      args: isPlainObject3(rawArgs) ? rawArgs : void 0,
+      useSpec,
+      chain,
+      scope,
+      engine
+    },
+    id
+  );
+}
+function SduiFragmentBody({
+  id,
+  args,
+  useSpec,
+  chain,
+  scope,
+  engine
+}) {
+  const spec = useSpec(id);
+  const nextChain = React11.useMemo(() => [...chain, id], [chain, id]);
+  const bodyScope = React11.useMemo(() => [...scope, { args, callSiteScope: scope }], [scope, args]);
+  React11.useEffect(() => {
+    if (!DEV || !isPlainObject3(spec) || !Array.isArray(spec.body)) return;
+    validateSpec(spec, new Set(Object.keys(engine.registry))).forEach(
+      (issue) => console.warn(`[sdui:spec:${id}] ${issue.path} \u2014 ${issue.message}`)
+    );
+  }, [spec, engine.registry, id]);
+  if (spec === void 0) return null;
+  if (spec === null || !isPlainObject3(spec) || !Array.isArray(spec.body)) {
+    warnOnce2(`fragment:missing:${id}`, `[sdui] Fragment \uC2A4\uD399\uC744 \uD574\uC11D\uD560 \uC218 \uC5C6\uC2B5\uB2C8\uB2E4: ${id} \u2014 \uB80C\uB354\uD558\uC9C0 \uC54A\uC2B5\uB2C8\uB2E4`);
+    return null;
+  }
+  const page = spec;
+  if (page.data || page.urlState || page.subscribe) {
+    warnOnce2(
+      `fragment:page-features:${id}`,
+      `[sdui] Fragment \uC2A4\uD399 ${id}\uC758 data/urlState/subscribe\uB294 \uBB34\uC2DC\uB429\uB2C8\uB2E4 \u2014 \uC870\uAC01\uC740 body\uB9CC \uB80C\uB354\uD569\uB2C8\uB2E4`
+    );
+  }
+  return /* @__PURE__ */ jsx(SduiFragmentChainContext.Provider, { value: nextChain, children: page.body.map((child, i) => renderChild(child, i, bodyScope, engine)) });
+}
 function SduiRenderer({
   page,
   registry = defaultRegistry,
@@ -2494,13 +2647,21 @@ function SduiRenderer({
         return current === void 0 ? value.default ?? null : current;
       }
       if (isItemRef(value)) {
-        const frame = scope[scope.length - 1];
+        const frame = nearestItemFrame(scope);
         if (!frame) return null;
         if (value.$item === true) return frame.item;
         return isPlainObject3(frame.item) ? frame.item[value.$item] ?? null : null;
       }
       if (isIndexRef(value)) {
-        return scope[scope.length - 1]?.index ?? null;
+        return nearestItemFrame(scope)?.index ?? null;
+      }
+      if (isArgRef(value)) {
+        const frame = nearestArgsFrame(scope);
+        if (frame?.args && Object.hasOwn(frame.args, value.$arg)) {
+          return resolveValue(frame.args[value.$arg], frame.callSiteScope);
+        }
+        if (value.default !== void 0) return resolveValue(value.default, scope);
+        return void 0;
       }
       if (isCalcRef(value)) {
         const { op: rawOp, args, field: rawField } = value.$calc;
@@ -2649,10 +2810,16 @@ function SduiRenderer({
   const dispatchRef = useRef(() => {
   });
   const dispatch = useCallback(
-    (rawAction, arg) => {
+    (rawAction, arg, scope = EMPTY_SCOPE) => {
+      if (isArgRef(rawAction)) {
+        for (const entry of expandActionEntries(rawAction, scope)) {
+          dispatchRef.current(entry.action, arg, entry.scope);
+        }
+        return;
+      }
       const action = resolveValue(
         rawAction,
-        EMPTY_SCOPE
+        scope
       );
       switch (action.action) {
         case "navigate":
@@ -2756,7 +2923,7 @@ function SduiRenderer({
                 body: values
               });
               setEntries({ [`${formId}.$submitting`]: false, [`${formId}.$resetDirty`]: true });
-              (action.onSuccess ?? []).forEach((a) => dispatchRef.current(a, response));
+              (action.onSuccess ?? []).forEach((a) => dispatchRef.current(a, response, scope));
             } catch (error) {
               setEntries({ [`${formId}.$submitting`]: false });
               const message = error instanceof Error ? error.message : "\uC694\uCCAD\uC774 \uC2E4\uD328\uD588\uC2B5\uB2C8\uB2E4";
@@ -2764,7 +2931,7 @@ function SduiRenderer({
                 warnOnce2(`validate:${formId}`, `[sdui] ${formId} \uAC80\uC99D \uADDC\uCE59 \uC624\uB958: ${message}`);
                 pushToast({ tone: "danger", title: "\uAC80\uC99D \uADDC\uCE59 \uC624\uB958", message });
               } else if (action.onError?.length) {
-                action.onError.forEach((a) => dispatchRef.current(a, message));
+                action.onError.forEach((a) => dispatchRef.current(a, message, scope));
               } else {
                 pushToast({ tone: "danger", title: "\uC800\uC7A5 \uC2E4\uD328", message });
               }
@@ -2775,7 +2942,9 @@ function SduiRenderer({
         case "request":
           void runRequestAction(action, {
             fetch: (path, init) => hostRef.current.fetch(path, init),
-            dispatch: (a, value) => dispatchRef.current(a, value),
+            // scope 를 잇는다 — request 의 onSuccess/onError 도 같은 자리의 텍스트다.
+            // {"$arg"} 체인 항목은 dispatch 진입부가 이 스코프로 펼친다(submitForm과 동일).
+            dispatch: (a, value) => dispatchRef.current(a, value, scope),
             toast: pushToast
           });
           break;

package/dist/meta.d.ts

@@ -1,4 +1,4 @@
-import { a as SduiPropValue, h as SduiNode } from './types-CeUhMB9Q.js';
+import { b as SduiPropValue, i as SduiNode } from './types-opTPYysN.js';
 
 /**
  * 시각 빌더용 컴포넌트 메타데이터 스키마.
@@ -530,9 +530,11 @@ declare const dsComponentMeta: {
  */
 
 declare const ForEachMeta: SduiComponentMeta;
+declare const FragmentMeta: SduiComponentMeta;
 /** 렌더러 내장 어휘의 메타데이터 묶음. */
 declare const builtinComponentMeta: {
     ForEach: SduiComponentMeta;
+    Fragment: SduiComponentMeta;
 };
 
 /**
@@ -553,7 +555,7 @@ declare const SDUI_CATEGORIES: ReadonlyArray<{
     label: string;
 }>;
 /**
- * 라이브러리가 아는 어휘 전체 — 기본 41 + rich 2 + 위젯 21 + DS 6 + 렌더러 내장 1 = 71종.
+ * 라이브러리가 아는 어휘 전체 — 기본 41 + rich 2 + 위젯 21 + DS 6 + 렌더러 내장 2 = 72종.
  * 편집기처럼 어휘 전부를 다뤄야 하는 쪽에서 쓴다.
  *
  * **레지스트리와 일대일이 아니다.** `defaultRegistry`에 없는 것도 들어 있다 —
@@ -582,4 +584,4 @@ declare function paletteGroups(catalog?: Record<string, SduiComponentMeta>): Arr
     items: SduiComponentMeta[];
 }>;
 
-export { ActionsMeta, AlertMeta, AutocompleteFieldMeta, AvatarMeta, BadgeMeta, BreadcrumbMeta, ButtonMeta, CanMeta, CardMeta, ChartMeta, CheckboxMeta, ColMeta, ColumnBoardMeta, DatePickerMeta, DateRangePickerMeta, DialogMeta, DiffViewMeta, DisclosureMeta, DividerMeta, EmptyStateMeta, EventCalendarMeta, FieldMeta, ForEachMeta, FormMeta, GridMeta, IconButtonMeta, IconMeta, ImageLightboxMeta, InlineEditMeta, InputMeta, JsonFieldMeta, KeyValueListMeta, LiveClockMeta, MapPreviewMeta, OrgChartMeta, PageHeadMeta, PaginationMeta, PeriodFilterMeta, PrintSheetMeta, ProgressBarMeta, RadioMeta, RemoteSearchResultsMeta, RowMeta, SDUI_CATEGORIES, SELF_AXIS_PROPS, type SduiCategory, type SduiChildrenMeta, type SduiComponentMeta, type SduiDomMeta, type SduiEnumOption, type SduiPropGroup, type SduiPropKind, type SduiPropMeta, type SduiResizeMeta, type SduiSlotMeta, SearchResultsMeta, SearchableMultiPickerMeta, SectionMeta, SecureScreenMeta, SegmentedControlMeta, SelectMeta, ShowMeta, SidebarNavMeta, SortHandleMeta, SortableListMeta, SpacerMeta, SpinnerMeta, StackedMeterMeta, StatCardMeta, StripMeta, SummaryTableMeta, SwitchMeta, TableMeta, TabsMeta, TagMeta, TagMultiSelectMeta, TextMeta, TextareaMeta, TimelineMeta, ToastMeta, TooltipMeta, TreePickerMeta, TreeViewMeta, allComponentMeta, builtinComponentMeta, coreComponentMeta, dsComponentMeta, getComponentMeta, paletteGroups, richComponentMeta, slotNamesOf, widgetComponentMeta, withSelfAxis, withSelfAxisAll };
+export { ActionsMeta, AlertMeta, AutocompleteFieldMeta, AvatarMeta, BadgeMeta, BreadcrumbMeta, ButtonMeta, CanMeta, CardMeta, ChartMeta, CheckboxMeta, ColMeta, ColumnBoardMeta, DatePickerMeta, DateRangePickerMeta, DialogMeta, DiffViewMeta, DisclosureMeta, DividerMeta, EmptyStateMeta, EventCalendarMeta, FieldMeta, ForEachMeta, FormMeta, FragmentMeta, GridMeta, IconButtonMeta, IconMeta, ImageLightboxMeta, InlineEditMeta, InputMeta, JsonFieldMeta, KeyValueListMeta, LiveClockMeta, MapPreviewMeta, OrgChartMeta, PageHeadMeta, PaginationMeta, PeriodFilterMeta, PrintSheetMeta, ProgressBarMeta, RadioMeta, RemoteSearchResultsMeta, RowMeta, SDUI_CATEGORIES, SELF_AXIS_PROPS, type SduiCategory, type SduiChildrenMeta, type SduiComponentMeta, type SduiDomMeta, type SduiEnumOption, type SduiPropGroup, type SduiPropKind, type SduiPropMeta, type SduiResizeMeta, type SduiSlotMeta, SearchResultsMeta, SearchableMultiPickerMeta, SectionMeta, SecureScreenMeta, SegmentedControlMeta, SelectMeta, ShowMeta, SidebarNavMeta, SortHandleMeta, SortableListMeta, SpacerMeta, SpinnerMeta, StackedMeterMeta, StatCardMeta, StripMeta, SummaryTableMeta, SwitchMeta, TableMeta, TabsMeta, TagMeta, TagMultiSelectMeta, TextMeta, TextareaMeta, TimelineMeta, ToastMeta, TooltipMeta, TreePickerMeta, TreeViewMeta, allComponentMeta, builtinComponentMeta, coreComponentMeta, dsComponentMeta, getComponentMeta, paletteGroups, richComponentMeta, slotNamesOf, widgetComponentMeta, withSelfAxis, withSelfAxisAll };

package/dist/meta.js

@@ -41,8 +41,39 @@ var ForEachMeta = {
   },
   resize: { kind: "none" }
 };
+var FragmentMeta = {
+  name: "Fragment",
+  label: "\uC2A4\uD399 \uC870\uAC01",
+  category: "logic",
+  icon: "component",
+  description: '\uB2E4\uB978 \uC2A4\uD399(id)\uC758 body\uB97C \uC774 \uC790\uB9AC\uC5D0 \uC778\uB77C\uC778 \uB80C\uB354\uD55C\uB2E4. \uC0C8 \uC0C1\uD0DC \uC5C6\uC774 \uD604\uC7AC \uD398\uC774\uC9C0\uC758 $state\xB7$item\xB7\uAD8C\uD55C\uC744 \uADF8\uB300\uB85C \uBCF8\uB2E4 \u2014 \uACF5\uC6A9 \uB2E4\uC774\uC5BC\uB85C\uADF8\uB97C \uC870\uAC01\uC73C\uB85C \uBE7C\uB294 \uC790\uB9AC\uB2E4. args\uB85C \uAC12\xB7\uC561\uC158\uC744 \uB118\uAE30\uBA74 \uC870\uAC01 \uC548\uC5D0\uC11C {"$arg":"\uC774\uB984"}\uC73C\uB85C \uC77D\uB294\uB2E4.',
+  props: [
+    {
+      name: "id",
+      kind: "string",
+      label: "\uC2A4\uD399 ID",
+      required: true,
+      description: '\uAC00\uC838\uC62C \uC2A4\uD399\uC758 id (\uC608: "dialogs/asset/category/catCreate"). \uC5B4\uB311\uD130\uC758 useSpec\uC73C\uB85C \uD574\uC11D\uB41C\uB2E4.',
+      group: "data"
+    },
+    {
+      name: "args",
+      kind: "object",
+      label: "\uC804\uB2EC \uC778\uC790",
+      description: '\uC870\uAC01\uC5D0 \uB118\uAE38 { \uC774\uB984: \uAC12 } \uD3C9\uBA74 \uC624\uBE0C\uC81D\uD2B8. \uAC12\uC740 \uC2A4\uCE7C\uB77C\xB7\uBC14\uC778\uB529($state/$item)\xB7\uC561\uC158(\uB2E8\uC77C/\uBC30\uC5F4) \uBB34\uC5C7\uC774\uB4E0 \uB418\uACE0, \uC870\uAC01 \uC548\uC5D0\uC11C {"$arg":"\uC774\uB984","default"?:\u2026}\uB85C \uC77D\uB294\uB2E4.',
+      group: "data"
+    }
+  ],
+  children: { accepts: false },
+  // 조각의 body를 그린다 — 작성한 children은 렌더되지 않는다
+  dom: { element: "fragment" },
+  // ForEach와 같음 — 자기 요소 없이 자식을 흘려보낸다
+  preset: { component: "Fragment", props: { id: "dialogs/example" } },
+  resize: { kind: "none" }
+};
 var builtinComponentMeta = {
-  ForEach: ForEachMeta
+  ForEach: ForEachMeta,
+  Fragment: FragmentMeta
 };
 
 // src/meta/self-axis.ts
@@ -4526,4 +4557,4 @@ function paletteGroups(catalog = allComponentMeta) {
   })).filter((group) => group.items.length > 0);
 }
 
-export { ActionsMeta, AlertMeta, AutocompleteFieldMeta, AvatarMeta, BadgeMeta, BreadcrumbMeta, ButtonMeta, CanMeta, CardMeta, ChartMeta, CheckboxMeta, ColMeta, ColumnBoardMeta, DatePickerMeta, DateRangePickerMeta, DialogMeta, DiffViewMeta, DisclosureMeta, DividerMeta, EmptyStateMeta, EventCalendarMeta, FieldMeta, ForEachMeta, FormMeta, GridMeta, IconButtonMeta, IconMeta, ImageLightboxMeta, InlineEditMeta, InputMeta, JsonFieldMeta, KeyValueListMeta, LiveClockMeta, MapPreviewMeta, OrgChartMeta, PageHeadMeta, PaginationMeta, PeriodFilterMeta, PrintSheetMeta, ProgressBarMeta, RadioMeta, RemoteSearchResultsMeta, RowMeta, SDUI_CATEGORIES, SELF_AXIS_PROPS, SearchResultsMeta, SearchableMultiPickerMeta, SectionMeta, SecureScreenMeta, SegmentedControlMeta, SelectMeta, ShowMeta, SidebarNavMeta, SortHandleMeta, SortableListMeta, SpacerMeta, SpinnerMeta, StackedMeterMeta, StatCardMeta, StripMeta, SummaryTableMeta, SwitchMeta, TableMeta, TabsMeta, TagMeta, TagMultiSelectMeta, TextMeta, TextareaMeta, TimelineMeta, ToastMeta, TooltipMeta, TreePickerMeta, TreeViewMeta, allComponentMeta, builtinComponentMeta, coreComponentMeta, dsComponentMeta, getComponentMeta, paletteGroups, richComponentMeta, slotNamesOf, widgetComponentMeta, withSelfAxis, withSelfAxisAll };
+export { ActionsMeta, AlertMeta, AutocompleteFieldMeta, AvatarMeta, BadgeMeta, BreadcrumbMeta, ButtonMeta, CanMeta, CardMeta, ChartMeta, CheckboxMeta, ColMeta, ColumnBoardMeta, DatePickerMeta, DateRangePickerMeta, DialogMeta, DiffViewMeta, DisclosureMeta, DividerMeta, EmptyStateMeta, EventCalendarMeta, FieldMeta, ForEachMeta, FormMeta, FragmentMeta, GridMeta, IconButtonMeta, IconMeta, ImageLightboxMeta, InlineEditMeta, InputMeta, JsonFieldMeta, KeyValueListMeta, LiveClockMeta, MapPreviewMeta, OrgChartMeta, PageHeadMeta, PaginationMeta, PeriodFilterMeta, PrintSheetMeta, ProgressBarMeta, RadioMeta, RemoteSearchResultsMeta, RowMeta, SDUI_CATEGORIES, SELF_AXIS_PROPS, SearchResultsMeta, SearchableMultiPickerMeta, SectionMeta, SecureScreenMeta, SegmentedControlMeta, SelectMeta, ShowMeta, SidebarNavMeta, SortHandleMeta, SortableListMeta, SpacerMeta, SpinnerMeta, StackedMeterMeta, StatCardMeta, StripMeta, SummaryTableMeta, SwitchMeta, TableMeta, TabsMeta, TagMeta, TagMultiSelectMeta, TextMeta, TextareaMeta, TimelineMeta, ToastMeta, TooltipMeta, TreePickerMeta, TreeViewMeta, allComponentMeta, builtinComponentMeta, coreComponentMeta, dsComponentMeta, getComponentMeta, paletteGroups, richComponentMeta, slotNamesOf, widgetComponentMeta, withSelfAxis, withSelfAxisAll };

package/dist/{types-CeUhMB9Q.d.ts → types-opTPYysN.d.ts}

@@ -39,6 +39,19 @@ interface SduiStateRef {
 interface SduiItemRef {
     $item: string | true;
 }
+/**
+ * Fragment 조각 안에서 호출부가 넘긴 args 값을 참조한다.
+ *
+ * 조각 스펙(body)의 값 자리 어디서나 쓴다 — 프롭·Show.when·$calc 인자·액션 필드.
+ * 해석 규칙: 가장 가까운 Fragment의 args에서 이름을 찾고, 찾은 **원본 값**을
+ * **호출부 스코프**로 다시 해석한다(호출부의 $state/$item이 호출부 의미로 풀린다).
+ * 이름이 없으면 default, 그것도 없으면 undefined — 경고 없이 조용히 빈다
+ * (Show.when 같은 조건 자리의 정상 폴백을 허용하기 위해서다).
+ */
+interface SduiArgRef {
+    $arg: string;
+    default?: SduiPropValue;
+}
 /** ForEach 반복 스코프 안에서 현재 인덱스(0부터)를 참조한다. */
 interface SduiIndexRef {
     $index: true;
@@ -265,4 +278,4 @@ interface SduiPage {
     body: SduiChild[];
 }
 
-export type { SduiAction as S, SduiPropValue as a, SduiRule as b, SduiPage as c, SduiCalcRef as d, SduiChild as e, SduiIndexRef as f, SduiItemRef as g, SduiNode as h, SduiPageQuery as i, SduiScalar as j, SduiStateRef as k };
+export type { SduiPage as S, SduiAction as a, SduiPropValue as b, SduiRule as c, SduiArgRef as d, SduiCalcRef as e, SduiChild as f, SduiIndexRef as g, SduiItemRef as h, SduiNode as i, SduiPageQuery as j, SduiScalar as k, SduiStateRef as l };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wipco/sdui",
-  "version": "0.16.0",
+  "version": "0.17.1",
   "description": "WIPCO 서버 주도 UI(SDUI) 렌더러 — JSON 페이지 스펙을 React 컴포넌트로 렌더링",
   "keywords": [
     "sdui",