@lodado/sdui-template 1.0.0

package/dist/types/src/react-wrapper/components/SduiLayoutRenderer.d.ts

@@ -0,0 +1,62 @@
+/**
+ * SDUI Layout Renderer
+ *
+ * SDUI Layout Document를 받아서 전체 UI를 렌더링하는 최상위 컴포넌트입니다.
+ * Render Props Pattern: renderNode 함수를 정의하고 하위 컴포넌트에 주입합니다.
+ *
+ * @param document - SDUI Layout Document (required)
+ * @param components - Custom component map (optional, merged with defaults)
+ * @param componentOverrides - Component overrides by ID or type (optional, ID > type priority)
+ * @param onLayoutChange - Callback when layout changes (optional)
+ * @param onError - Error callback (optional)
+ *
+ * @example
+ * ```tsx
+ * <SduiLayoutRenderer
+ *   document={myDocument}
+ *   components={{ CustomChart: CustomChartFactory }}
+ *   onError={(error) => console.error(error)}
+ * />
+ * ```
+ *
+ * @remarks
+ * - Must be wrapped with "use client" directive in Next.js App Router
+ * - Component overrides: byNodeId > byNodeType > defaultComponentFactory
+ * - Errors are passed to onError callback, component continues rendering if possible
+ */
+import React from 'react';
+import type { ComponentFactory } from '../../components/types';
+import type { SduiLayoutDocument } from '../../schema';
+interface SduiLayoutRendererProps {
+    /** SDUI Layout Document */
+    document: SduiLayoutDocument;
+    /** 커스텀 컴포넌트 맵 (componentMap에 추가될 컴포넌트들) */
+    components?: Record<string, ComponentFactory>;
+    /** 1회용 컴포넌트 오버라이드 설정 */
+    componentOverrides?: {
+        byNodeId?: Record<string, ComponentFactory>;
+        byNodeType?: Record<string, ComponentFactory>;
+    };
+    /** Layout change callback */
+    onLayoutChange?: (document: SduiLayoutDocument) => void;
+    /** Error callback */
+    onError?: (error: Error) => void;
+}
+/**
+ * SduiLayoutRenderer 내부 컴포넌트
+ *
+ * useRenderNode hook을 사용하여 renderNode 함수를 생성하고,
+ * 하위 컴포넌트에 주입합니다.
+ * 각 컴포넌트는 이 함수를 통해 자식을 렌더링합니다.
+ */
+declare const SduiLayoutRendererInner: ({ id, componentMap: customComponentMap, }: {
+    id: string;
+    componentMap?: Record<string, ComponentFactory>;
+}) => React.ReactNode;
+/**
+ * SduiLayoutRenderer
+ *
+ * SDUI Layout Document를 렌더링하는 최상위 컴포넌트입니다.
+ */
+export declare const SduiLayoutRenderer: React.FC<SduiLayoutRendererProps>;
+export { SduiLayoutRendererInner };

package/dist/types/src/react-wrapper/components/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Server-Driven UI - React Components
+ *
+ * React components exports
+ */
+export * from "./SduiLayoutRenderer";

package/dist/types/src/react-wrapper/context/SduiLayoutContext.d.ts

@@ -0,0 +1,37 @@
+/**
+ * SDUI Layout Context
+ *
+ * Context API를 사용하여 SduiLayoutStore를 제공합니다.
+ */
+import React from 'react';
+import type { SduiLayoutStore } from '../../store';
+/**
+ * SduiLayoutContext 타입
+ */
+interface SduiLayoutContextValue {
+    /** Store 인스턴스 */
+    store: SduiLayoutStore;
+}
+/**
+ * SduiLayoutProvider Props
+ */
+interface SduiLayoutProviderProps {
+    /** Store 인스턴스 */
+    store: SduiLayoutStore;
+    /** 자식 컴포넌트 */
+    children: React.ReactNode;
+}
+/**
+ * SduiLayoutProvider
+ *
+ * Context를 통해 SduiLayoutStore를 제공합니다.
+ */
+export declare const SduiLayoutProvider: React.FC<SduiLayoutProviderProps>;
+/**
+ * useSduiLayoutContext
+ *
+ * Context에서 store를 가져옵니다.
+ * Provider 외부에서 사용 시 에러를 throw합니다.
+ */
+export declare const useSduiLayoutContext: () => SduiLayoutContextValue;
+export {};

package/dist/types/src/react-wrapper/context/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Server-Driven UI - React Context
+ *
+ * Context API 및 Provider export
+ */
+export * from './SduiLayoutContext';

package/dist/types/src/react-wrapper/hooks/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Server-Driven UI - React Hooks
+ *
+ * React hooks for accessing store state and actions
+ */
+export * from './useRenderNode';
+export * from './useSduiLayoutAction';
+export * from './useSduiNodeSubscription';

package/dist/types/src/react-wrapper/hooks/useRenderNode.d.ts

@@ -0,0 +1,10 @@
+import type { ComponentFactory, RenderNodeFn } from '../../components/types';
+/**
+ * renderNode 함수를 생성하는 hook
+ *
+ * nodes는 React 상태로 관리되므로 변경 시 자동으로 리렌더링됩니다.
+ *
+ * @param componentMap - 기본 컴포넌트 맵 (선택적)
+ * @returns 자식 노드를 렌더링하는 함수
+ */
+export declare const useRenderNode: (componentMap?: Record<string, ComponentFactory>) => RenderNodeFn;

package/dist/types/src/react-wrapper/hooks/useSduiLayoutAction.d.ts

@@ -0,0 +1,15 @@
+/**
+ * useSduiLayoutAction
+ *
+ * Store 인스턴스를 반환하여 액션을 호출할 수 있게 합니다.
+ *
+ * @returns Store 인스턴스
+ *
+ * @example
+ * ```tsx
+ * const store = useSduiLayoutAction();
+ * store.updateNodeState(nodeId, newState);
+ * ```
+ */
+import type { SduiLayoutStore } from '../../store';
+export declare const useSduiLayoutAction: () => SduiLayoutStore;

package/dist/types/src/react-wrapper/hooks/useSduiNodeSubscription.d.ts

@@ -0,0 +1,45 @@
+import type { z, ZodSchema } from 'zod';
+import type { SduiLayoutNode } from '../../schema';
+/**
+ * useSduiNodeSubscription 파라미터 타입
+ */
+export interface UseSduiNodeSubscriptionParams<TSchema extends ZodSchema<Record<string, unknown>> = ZodSchema<Record<string, unknown>>> {
+    /** 구독할 노드 ID */
+    nodeId: string;
+    /** Zod 스키마 (선택적). state를 검증하고, 실패 시 에러를 throw합니다. 성공 시 state는 스키마에서 추론된 타입으로 보장됩니다. */
+    schema?: TSchema;
+}
+/**
+ * 특정 노드 ID를 구독하고 변경 시 forceRender를 트리거합니다.
+ *
+ * - nodes, variables: version 구독으로 변경 감지
+ * - layoutStates: 노드별 구독으로 변경 감지
+ *
+ * @template TSchema - Zod 스키마 타입. 스키마에서 타입을 추론합니다.
+ * @param params - 구독 파라미터 객체
+ *   - `nodeId`: 구독할 노드 ID
+ *   - `schema`: Zod 스키마 (선택적). state를 검증하고, 실패 시 에러를 throw합니다. 성공 시 state는 스키마에서 추론된 타입으로 보장됩니다.
+ * @returns 노드 정보 객체
+ *   - `node`: 노드 엔티티 (SduiLayoutNode | undefined)
+ *   - `type`: 노드 타입 (string | undefined)
+ *   - `state`: 레이아웃 상태 (스키마가 제공되면 z.infer<TSchema>, 아니면 Record<string, unknown>)
+ *   - `childrenIds`: 자식 노드 ID 배열 (string[])
+ *   - `attributes`: 노드 속성 (Record<string, unknown> | undefined)
+ *   - `exists`: 노드 존재 여부 (boolean)
+ *
+ * @example
+ * ```tsx
+ * const { node, state } = useSduiNodeSubscription({
+ *   nodeId: 'node-1',
+ *   schema: baseLayoutStateSchema, // optional
+ * });
+ * ```
+ */
+export declare function useSduiNodeSubscription<TSchema extends ZodSchema<Record<string, unknown>> = ZodSchema<Record<string, unknown>>>(params: UseSduiNodeSubscriptionParams<TSchema>): {
+    node: SduiLayoutNode | undefined;
+    type: string | undefined;
+    state: TSchema extends ZodSchema<any> ? z.infer<TSchema> : Record<string, unknown>;
+    childrenIds: string[];
+    attributes: Record<string, unknown> | undefined;
+    exists: boolean;
+};

package/dist/types/src/react-wrapper/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Server-Driven UI - React Integration
+ *
+ * React components, hooks, and context exports
+ */
+export * from './components';
+export * from './context';
+export * from './hooks';

package/dist/types/src/schema/base.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Server-Driven UI - 기본 스키마
+ *
+ * SDUI의 기본 노드와 문서 구조를 정의합니다.
+ */
+/**
+ * SDUI 노드 기본 인터페이스
+ *
+ * 재귀적 구조를 가지며, 각 노드는 id, type, state, children을 가집니다.
+ */
+export interface SduiNode {
+    /** 노드 고유 식별자 */
+    id: string;
+    /** 컴포넌트 타입 */
+    type: string;
+    /** 상태 (모든 설정값 및 UI 상태) */
+    state?: Record<string, unknown>;
+    /** 외형 스타일 속성 (순수 CSS 스타일만) */
+    attributes?: Record<string, unknown>;
+    /** 자식 노드 배열 (재귀 구조) */
+    children?: SduiNode[];
+}
+/**
+ * SDUI 문서 기본 인터페이스
+ *
+ * 서버에서 내려주는 전체 UI 구조를 담는 루트 문서입니다.
+ */
+export interface SduiDocument {
+    /** 스키마 버전 */
+    version: string;
+    /** 문서 메타데이터 */
+    metadata?: {
+        id?: string;
+        name?: string;
+        description?: string;
+        createdAt?: string;
+        updatedAt?: string;
+        author?: string;
+    };
+    /** 루트 노드 */
+    root: SduiNode;
+    /** 전역 변수 */
+    variables?: Record<string, unknown>;
+}

package/dist/types/src/schema/document.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Server-Driven UI - Layout 전용 문서
+ *
+ * Layout 시스템을 위한 문서 타입 정의
+ */
+import type { SduiDocument } from './base';
+import type { SduiLayoutNode } from './node';
+/**
+ * Layout 전용 문서
+ *
+ * SduiDocument를 상속받아 root를 SduiLayoutNode로 구체화합니다.
+ */
+export interface SduiLayoutDocument extends SduiDocument {
+    /** 루트 노드 (Layout 전용 노드) */
+    root: SduiLayoutNode;
+}

package/dist/types/src/schema/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Server-Driven UI - Schema
+ *
+ * SDUI 스키마 타입들을 export합니다.
+ */
+export type * from './base';
+export type * from './node';
+export type * from './document';

package/dist/types/src/schema/node.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Server-Driven UI - Layout 전용 노드
+ *
+ * Layout 시스템을 위한 노드 타입 정의
+ */
+import type { SduiNode } from './base';
+/**
+ * Layout 전용 노드
+ *
+ * SduiNode를 상속받아 state를 LayoutState로 구체화합니다.
+ */
+export interface SduiLayoutNode extends SduiNode {
+    /** 컴포넌트 타입 */
+    type: string;
+    /** 레이아웃 상태 */
+    state?: Record<string, unknown>;
+    /** 자식 노드 배열 (재귀 구조) */
+    children?: SduiLayoutNode[];
+}

package/dist/types/src/store/SduiLayoutStore.d.ts

@@ -0,0 +1,192 @@
+/**
+ * SDUI Layout Store
+ *
+ * ID 기반 구독 시스템을 사용하여 SDUI Layout 상태를 관리합니다.
+ * 데이터는 일반 변수로 관리하고, 변경 시 해당 노드만 notify하여
+ * 구독한 컴포넌트만 forceRender합니다.
+ *
+ * @description
+ * - 성능 최적화: cloneDeep 제거, 변경된 노드만 리렌더링
+ * - 구독 시스템: ID별 구독자 관리, 선택적 notify
+ */
+import type { ComponentFactory } from '../components/types';
+import type { SduiLayoutDocument } from '../schema';
+import type { SduiLayoutStoreOptions, SduiLayoutStoreState } from './types';
+/**
+ * SduiLayoutStore
+ *
+ * Facade Pattern을 사용하여 SDUI Layout 상태를 관리합니다.
+ * 여러 매니저 클래스를 조합하여 단일 인터페이스를 제공합니다.
+ *
+ * @description
+ * - SubscriptionManager: 구독 시스템 관리
+ * - LayoutStateRepository: 상태 저장소 관리
+ * - DocumentManager: 문서 캐싱 및 직렬화
+ * - VariablesManager: 전역 변수 관리
+ *
+ * 모든 데이터는 일반 변수로 관리하고, 구독 시스템을 통해 변경을 감지합니다.
+ */
+export declare class SduiLayoutStore {
+    /** 구독 시스템 매니저 */
+    private _subscriptionManager;
+    /** 상태 저장소 */
+    private _repository;
+    /** 문서 관리자 */
+    private _documentManager;
+    /** 변수 관리자 */
+    private _variablesManager;
+    /** 컴포넌트 오버라이드 (일반 변수) - ID와 타입을 하나의 맵으로 관리 */
+    private _componentOverrides;
+    constructor(initialState?: Partial<SduiLayoutStoreState>, options?: SduiLayoutStoreOptions);
+    /**
+     * 특정 노드 ID를 구독합니다.
+     *
+     * @param nodeId - 구독할 노드 ID
+     * @param callback - 변경 시 호출될 콜백 (forceRender)
+     * @returns 구독 해제 함수
+     */
+    subscribeNode(nodeId: string, callback: () => void): () => void;
+    /**
+     * version을 구독합니다. (nodes, rootId, variables 변경 감지용)
+     *
+     * @param callback - 변경 시 호출될 콜백 (forceRender)
+     * @returns 구독 해제 함수
+     */
+    subscribeVersion(callback: () => void): () => void;
+    /**
+     * Store 상태를 반환합니다.
+     */
+    get state(): SduiLayoutStoreState;
+    /**
+     * 노드 엔티티를 반환합니다.
+     */
+    get nodes(): Record<string, import("../schema").SduiLayoutNode>;
+    /**
+     * 문서 메타데이터를 반환합니다.
+     *
+     * @throws {MetadataNotFoundError} 메타데이터가 없을 경우
+     */
+    get metadata(): SduiLayoutDocument['metadata'];
+    /**
+     * 컴포넌트 오버라이드 맵을 반환합니다.
+     */
+    getComponentOverrides(): Record<string, ComponentFactory>;
+    /**
+     * ID로 노드를 조회합니다.
+     *
+     * @param nodeId - 조회할 노드 ID
+     * @returns 노드
+     * @throws {NodeNotFoundError} 노드가 존재하지 않을 경우
+     */
+    getNodeById(nodeId: string): import("../schema").SduiLayoutNode;
+    /**
+     * ID로 노드 타입을 조회합니다.
+     *
+     * @param nodeId - 조회할 노드 ID
+     * @returns 노드 타입
+     * @throws {NodeNotFoundError} 노드가 존재하지 않을 경우
+     */
+    getNodeTypeById(nodeId: string): string;
+    /**
+     * ID로 자식 노드 ID 목록을 조회합니다.
+     *
+     * @param nodeId - 조회할 노드 ID
+     * @returns 자식 노드 ID 배열
+     * @throws {NodeNotFoundError} 노드가 존재하지 않을 경우
+     */
+    getChildrenIdsById(nodeId: string): string[];
+    /**
+     * ID로 레이아웃 상태를 조회합니다.
+     *
+     * @param nodeId - 조회할 노드 ID
+     * @returns 레이아웃 상태 (없으면 빈 객체 반환)
+     * @throws {NodeNotFoundError} 노드가 존재하지 않을 경우
+     */
+    getLayoutStateById(nodeId: string): Record<string, unknown>;
+    /**
+     * ID로 속성을 조회합니다.
+     *
+     * @param nodeId - 조회할 노드 ID
+     * @returns 속성 (없으면 빈 객체 반환)
+     * @throws {NodeNotFoundError} 노드가 존재하지 않을 경우
+     */
+    getAttributesById(nodeId: string): Record<string, unknown>;
+    /**
+     * 루트 노드 ID를 반환합니다.
+     *
+     * @returns 루트 노드 ID
+     * @throws {RootNotFoundError} 루트 노드 ID가 존재하지 않을 경우
+     */
+    getRootId(): string;
+    /**
+     * 레이아웃 문서를 업데이트하고 normalize합니다.
+     * 전체 문서가 변경되는 경우이므로 version을 증가시켜 전체 리렌더를 트리거합니다.
+     *
+     * @param document - 업데이트할 레이아웃 문서
+     */
+    updateLayout(document: SduiLayoutDocument): void;
+    /**
+     * 레이아웃 변경사항을 취소하고 원본으로 복원합니다.
+     *
+     * @param documentId - 복원할 문서 ID
+     */
+    cancelEdit(documentId?: string): void;
+    /**
+     * 특정 노드의 상태를 업데이트합니다.
+     *
+     * @param nodeId - 업데이트할 노드 ID
+     * @param state - 새로운 상태
+     * @throws {NodeNotFoundError} 노드가 존재하지 않을 경우
+     */
+    updateNodeState(nodeId: string, state: Partial<Record<string, unknown>>): void;
+    /**
+     * 특정 노드의 속성을 업데이트합니다.
+     *
+     * @param nodeId - 업데이트할 노드 ID
+     * @param attributes - 새로운 속성
+     * @throws {NodeNotFoundError} 노드가 존재하지 않을 경우
+     */
+    updateNodeAttributes(nodeId: string, attributes: Partial<Record<string, unknown>>): void;
+    /**
+     * 전역 변수를 업데이트합니다.
+     * 깊은 복사로 새 객체를 생성하여 React 리렌더를 트리거합니다.
+     *
+     * @param variables - 새로운 전역 변수 객체
+     */
+    updateVariables(variables: Record<string, unknown>): void;
+    /**
+     * 개별 전역 변수를 업데이트합니다.
+     * 깊은 복사로 새 객체를 생성하여 version을 증가시킵니다.
+     *
+     * @param key - 변수 키
+     * @param value - 변수 값
+     */
+    updateVariable(key: string, value: unknown): void;
+    /**
+     * 전역 변수를 삭제합니다.
+     *
+     * @param key - 삭제할 변수 키
+     */
+    deleteVariable(key: string): void;
+    /**
+     * 선택된 노드 ID를 설정합니다.
+     *
+     * @param nodeId - 선택할 노드 ID
+     */
+    setSelectedNodeId(nodeId?: string): void;
+    /**
+     * 현재 상태를 문서로 변환합니다.
+     * 저장/내보내기 시에만 사용합니다.
+     *
+     * @returns 복원된 문서 또는 null
+     */
+    getDocument(): SduiLayoutDocument | null;
+    /**
+     * 캐시를 초기화합니다.
+     */
+    clearCache(): void;
+    /**
+     * 상태를 초기화합니다.
+     */
+    reset(): void;
+}

package/dist/types/src/store/errors.d.ts

@@ -0,0 +1,37 @@
+/**
+ * SDUI Layout Store Errors
+ *
+ * Custom error classes for SDUI Layout Store operations
+ */
+/**
+ * NodeNotFoundError
+ *
+ * Thrown when attempting to access or update a node that does not exist in the store
+ */
+export declare class NodeNotFoundError extends Error {
+    constructor(nodeId: string);
+}
+/**
+ * RootNotFoundError
+ *
+ * Thrown when attempting to access root node ID that does not exist
+ */
+export declare class RootNotFoundError extends Error {
+    constructor();
+}
+/**
+ * MetadataNotFoundError
+ *
+ * Thrown when attempting to access metadata that does not exist
+ */
+export declare class MetadataNotFoundError extends Error {
+    constructor();
+}
+/**
+ * AttributesNotFoundError
+ *
+ * Thrown when attempting to access attributes that does not exist
+ */
+export declare class AttributesNotFoundError extends Error {
+    constructor(nodeId: string);
+}

package/dist/types/src/store/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Server-Driven UI - Store
+ *
+ * Store 클래스 및 타입 export
+ */
+export * from './errors';
+export * from './SduiLayoutStore';
+export * from './types';

package/dist/types/src/store/managers/DocumentManager.d.ts

@@ -0,0 +1,67 @@
+/**
+ * DocumentManager
+ *
+ * 문서 캐싱, 복원, 직렬화를 관리합니다.
+ */
+import type { SduiLayoutDocument } from '../../schema';
+import type { LayoutStateRepository } from './LayoutStateRepository';
+/**
+ * DocumentManager
+ *
+ * 문서 캐싱, 복원, 직렬화를 관리합니다.
+ */
+export declare class DocumentManager {
+    /** 문서 메타데이터 */
+    private _metadata?;
+    /** 캐시된 문서 */
+    private _cached;
+    /** 원본 문서 캐시 (편집 취소용) */
+    private _originalCached;
+    /**
+     * 문서를 캐시합니다.
+     *
+     * @param document - 캐시할 문서
+     */
+    cacheDocument(document: SduiLayoutDocument): void;
+    /**
+     * 메타데이터를 설정합니다.
+     *
+     * @param metadata - 메타데이터
+     */
+    setMetadata(metadata?: SduiLayoutDocument['metadata']): void;
+    /**
+     * 메타데이터를 반환합니다.
+     *
+     * @returns 메타데이터 또는 undefined
+     */
+    getMetadata(): SduiLayoutDocument['metadata'] | undefined;
+    /**
+     * 원본 문서를 반환합니다.
+     *
+     * @param documentId - 문서 ID
+     * @returns 원본 문서 또는 undefined
+     */
+    getOriginalDocument(documentId: string): SduiLayoutDocument | undefined;
+    /**
+     * 문서 ID를 가져옵니다.
+     *
+     * @param rootId - 루트 노드 ID (fallback)
+     * @returns 문서 ID 또는 undefined
+     */
+    getDocumentId(rootId?: string): string | undefined;
+    /**
+     * 현재 상태를 문서로 변환합니다.
+     *
+     * @param repository - 상태 저장소
+     * @returns 복원된 문서 또는 null
+     */
+    getDocument(repository: LayoutStateRepository): SduiLayoutDocument | null;
+    /**
+     * 캐시를 초기화합니다.
+     */
+    clearCache(): void;
+    /**
+     * 상태를 초기화합니다.
+     */
+    reset(): void;
+}